Document revision date: 30 March 2001
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

Guide to the DEC Text Processing Utility
Previous Contents Index

5.6.6 Using Command Files

A command file is a DECTPU source file that can contain procedures, key definitions, and other DECTPU executable statements. You can have any number of command files in your directory. You might want to write one command file that customizes your editor for programming in Pascal, another command file that customizes your editor for text editing, and so on. If you have several command files, give them names that remind you of their contents. If you have one command file that you use most of the time, name it TPU$COMMAND.TPU.

The command to invoke DECTPU with a command file is: 


$ EDIT/TPU/COMMAND [[= filespec]]

If you name your command file TPU$COMMAND.TPU and it is in your default directory, DECTPU reads the file by default, without your having to use the /COMMAND qualifier. If you name your file something other than TPU$COMMAND.TPU, or if you put it in a directory other than your default directory, you must use the /COMMAND qualifier explicitly and provide a full file specification after the qualifier.

DECTPU reads a command file, compiles it, and executes any commands that do not contain syntax errors. If there are errors, DECTPU writes an error message to the message area. The command file can customize or extend the application implemented by the section file with which you invoked DECTPU.

Example 5-6 is a sample DECTPU command file that defines a procedure that moves the editing point to the beginning of a segment of text delimited by the characters %(/* at the beginning and */)% at the end.

Example 5-6 Command File for GOTO_TEXT_MARKER 

 
PROCEDURE goto_text_marker 
 
   LOCAL text_marker_pattern, 
         text_marker_range; 
 
   text_marker_pattern := '%(/*' + MATCH ('*/)%'); 
   text_marker_range :=  SEARCH_QUIETLY (text_marker_pattern, 
                             GET_INFO (CURRENT_BUFFER, "direction")); 
   IF text_marker_range <> 0 
   THEN 
       POSITION (text_marker_range); 
   ELSE 
       MESSAGE ("Text_marker not found"); 
   ENDIF; 
 
   RETURN text_marker_range; 
 
ENDPROCEDURE;

If you name the file that contains this procedure TEXT_MARKERS.TPU, you can invoke DECTPU with EVE and your command file with the following command: 


$ EDIT/TPU/COMMAND=device:[directory]text_markers.tpu

If you add procedures or statements to the command file TEXT_MARKERS.TPU, place all procedures before any individual statements that are not listed within a procedure (for example, key definitions to move to the next text marker).

Remember to name your variables and procedures so they do not conflict with DECTPU reserved words and predefined identifiers. Compaq recommends that you prefix your variable and procedure names with three letters (your initials, for example) followed by an underscore (_).

5.6.7 Using EVE Initialization Files

An initialization file is a file that contains commands to be executed by an application. Any application layered on DECTPU can support initialization files.

With EVE initialization files, you can do the following:

EVE initialization files contain EVE commands that are executed either when you invoke the editor or when you issue the EVE @ (at sign) command.

To create an EVE initialization file, put in the file the EVE commands you want to use to customize the editor. Use one command on each line and one line for each command. Do not separate the commands with semicolons. If a command in an EVE initialization file is incomplete, EVE prompts you for more information, the same as if you were typing the command during an editing session. Comments in EVE initialization files must be on lines separate from commands and must begin with an exclamation point (!). You cannot nest EVE initialization files. Do not use the DO command in an EVE initialization file.

The following sample initialization file sets left and right margins, establishes overstrike mode, binds the QUIT command to the GOLD/Q key sequence, and enables an EDT-like keypad: 


SET LEFT MARGIN 5 
SET RIGHT MARGIN 60 
OVERSTRIKE MODE 
DEFINE KEY=gold/q QUIT 
SET KEYPAD EDT

5.6.7.1 Using an EVE Initialization File at Startup

You can cause an initialization file to be executed in any of the following ways when you invoke EVE:

The first and third methods are appropriate if you intend to use one initialization file most of the time to customize your editing sessions. If you name the file EVE$INIT.EVE and do not specify another EVE initialization file on the command line, EVE automatically executes that file when you invoke DECTPU.

Use the second method to control which initialization file EVE executes to customize the editing session. For example, if you have an EVE$INIT file but want to use another initialization file, specify the other file by using the /INITIALIZATION qualifier to EDIT/TPU. To specify an initialization file called MY_INIT.EVE, enter the following command string on the command line: 


$ EDIT/TPU/INITIALIZATION=MY_INIT.EVE

EVE always executes the initialization file specified on the command line, if such a file is present. If no file is specified on the command line, EVE searches for EVE$INIT.EVE first in the current directory and then in your login area. If EVE finds EVE$INIT.EVE, it executes that file. If the file is not found, the editor checks whether the logical name EVE$INIT has been defined.

If you plan to create several initialization files and to use them equally, you may not want to name one of the files EVE$INIT. For example, if you want one initialization file to set narrow margins and another to set wide margins, create both files and specify the file you want when you invoke EVE.

5.6.7.2 Using an EVE Initialization File During an Editing Session

To execute an EVE initialization file during an editing session, use the @ (at sign) command and specify the file. For example, the following command executes an initialization file called MYEVE.EVE in your current (default) directory. 


Command: @MYEVE

Commands for buffer settings apply to the current buffer. This is effectively the same as typing the commands that the file contains. You may want to create initialization files to execute two or more related commands, such as resetting both margins.

5.6.7.3 How an EVE Initialization File Affects Buffer Settings

Commands in an EVE initialization file that set buffer characteristics (such as margins and tab stops) affect a system buffer named $DEFAULTS$. Buffers created during the editing session have the same settings as $DEFAULTS$. For example, if your initialization file contains the command SET RIGHT MARGIN 65, the value 65 is used as the right margin setting for the main buffer and for any buffers you create during the session with GET FILE or BUFFER commands.

To see the settings for the $DEFAULTS$ buffer, use the EVE command SHOW DEFAULTS BUFFER. For example, if you want to know what the tab settings are for the $DEFAULTS$ buffer, type the following command: 


Command: SHOW DEFAULTS BUFFER

This command causes EVE to show buffer information in a format similar to the format in Example 5-7 (using values that apply to your editing session).

Example 5-7 SHOW DEFAULTS BUFFER Display 

 EVE V3.1 1993-08-17 08:47 
 Information about buffer $DEFAULTS$ 
 
     Not modified               Left margin set to: 1 
     Mode: Insert               Right margin set to: 79 
     Paragraph indent: none     WPS word wrap indent: none 
     Read-only                  Unmodifiable 
     Direction: Forward         
     Max lines: no limit        
 Tab stops set every 8 columns. 
 Word wrap: on

To change the characteristics of the $DEFAULTS$ buffer during an editing session, use the command BUFFER $DEFAULTS$ to put the defaults buffer in a window. This buffer is empty and you cannot add text to it. However, when you change the settings of the $DEFAULTS$ buffer, the changes are saved and used to set the characteristics of any user buffers you create.

Use commands such as SET RIGHT MARGIN, SET LEFT MARGIN, SET TABS, FORWARD, REVERSE, INSERT, or OVERSTRIKE to change the characteristics of the $DEFAULTS$ buffer. The new characteristics are applied to new buffers but not to existing ones. To leave the $DEFAULTS$ buffer and put a different buffer in the window, use the BUFFER command.

5.7 Debugging DECTPU Programs

This section discusses the options you have for debugging DECTPU programs.

To debug DECTPU programs, you can do one of the following:

Regardless of which debugger you use, you may find it helpful to enable the display of error line numbers by using SET (LINE_NUMBER, ON) and to enable the display of procedures called when an error occurs by using SET (TRACEBACK, ON).

5.7.1 Using Your Own Debugger

If you write your own debugger, you can invoke it (and bypass the default bugger) by using the /DEBUG qualifier with the EDIT/TPU command. For example, to use a debugger called MY_DEBUGGER.TPU on a file called MIGHT_BE_BUGGY.TPU, type the following: 


$ EDIT/TPU/DEBUG=MY_DEBUGGER.TPU MIGHT_BE_BUGGY.TPU

5.7.2 Using the DECTPU Debugger

You can invoke the DECTPU debugger to debug one of the following kinds of files:

The following sections contain more information on debugging each kind of file.

5.7.2.1 Debugging Section Files

To invoke the debugger for a section file, specify the following command on your command line: 


$ EDIT/TPU/DEBUG

Use of your system's debug command causes the DECTPU initialization routine to execute the debugger file before the system runs its initialization procedure.

The debugger initially creates a window that fills most of the screen. The window consists of the following three areas:

When DECTPU displays the debug window, you can set breakpoints in the section file by using the SET BREAKPOINT command. For example, if you want to debug a procedure called user_fum, type the following on the debugger command line: 


Debug: SET BREAKPOINT user_fum

After setting breakpoints, use the GO command to switch control of execution from the debugger to DECTPU. After you have used this command, the screen displays the code you specified.

5.7.2.2 Debugging Command Files

To invoke the debugger on a command file, use the /DEBUG, /COMMAND, and /NOSECTION qualifiers. To debug a command file called MY_COMMANDS.TPU, type the following at the DCL prompt: 


$ EDIT/TPU/NOSECTION/COMMAND=MY_COMMANDS.TPU/DEBUG

DECTPU compiles and executes the debugger and places the debug window on the screen before compiling the command file. As a result, you must set breakpoints in the command file before it has been compiled. When you set breakpoints, DECTPU notifies you that you have specified breakpoints at nonexistent procedures.

To continue with the debugging session, use the GO command. GO causes DECTPU to compile the contents of the command file. Recompiling a procedure does not remove any breakpoints set in that procedure.

You cannot use the DECTPU debugger on a file that does not contain DECTPU procedures. If your command file does not contain any procedures, you must find a different method of debugging it.

5.7.2.3 Debugging Other DECTPU Source Code

To debug a DECTPU program that is not a section file or a command file, use the /DEBUG qualifier when you invoke DECTPU. For example, to debug procedures in a file called USER_APPLICATION.TPU, invoke the debugger on the command line as follows: 


$ EDIT/TPU/DEBUG USER_APPLICATION.TPU

The debugger creates a window that fills the screen as described in Section 5.7.2.1.

5.7.3 Getting Started with the DECTPU Debugger

This section describes using the default DECTPU debugger with EVE.

If you know which parts of the code you want to debug, use the SET BREAKPOINT command to set breakpoints. If you need to look at the code before setting breakpoints, use the GO command as soon as the debugger window appears. This places on the screen the code in the file you specified on the command line. At this point, EVE commands are available so you can manipulate the text. To return to the debugger so you can set breakpoints, enter the command DEBUG at the EVE command line. You can also gain access to the debugger with the DECTPU procedure called DEBUGON. To invoke this procedure from within EVE, type the following at the EVE Command prompt: 


Command: TPU DEBUGON

When you use either DEBUG or DEBUGON, the screen displays the debugger window and command line. After setting breakpoints, use the GO command to return control of execution to DECTPU.

To compile all code in the buffer, use the EXTEND ALL command or use the COMPILE (CURRENT_BUFFER) statement. To execute a procedure after compilation, use the TPU command. For example, if you want to execute the compiled procedure user_fum, type the following at the EVE Command prompt: 


Command: TPU user_fum

When DECTPU encounters a breakpoint (or when you use the STEP command described later), DECTPU invokes the debugger program. As the debugger assumes control, it receives from DECTPU the name of the procedure whose execution has been suspended. The debugger searches its source buffer for that procedure.

When DECTPU encounters the first breakpoint in the session, the code you are debugging has not yet been placed in the debugger's source buffer. The debugger prompts for the name of the file that contains your code. Using your response, the debugger places your code in its source buffer. The debugger uses your previous response to supply missing fields, if any, in subsequent file names that you specify. All files read into the source buffer remain there, so that the time DECTPU takes to find a procedure may increase as more files are read into the source buffer.

You cannot use the TPU command followed by the MESSAGE built-in procedure to examine the contents of a local variable while debugging. To use the MESSAGE built-in to examine a local variable, you must write the MESSAGE built-in into the procedure you are debugging. After the statement that contains MESSAGE is executed, you can examine the message buffer to see the results. Alternatively, you can use the debugger EXAMINE command to examine local variables and the formal parameters of the suspended procedure.

5.8 Handling Errors

Each DECTPU built-in procedure returns one or more status codes telling you what happened when the built-in was executed. A DECTPU status code can have one of the following severity levels:

You can enable or disable the display of informational or success messages with the SET (INFORMATIONAL) and SET (SUCCESS) built-in procedures.

See Chapter 4 for a description of how to use the ON_ERROR language statement to trap error and warning messages.

In addition to messages that are generated by DECTPU, a built-in procedure may return system messages.

Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
6018PRO_013.HTML