HP OpenVMS Systems Documentation
Guide to the DEC Text Processing Utility
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:
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.
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:
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 (_).
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:
220.127.116.11 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:
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.
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.
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.
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:
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).
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.
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).
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:
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
To invoke the debugger for a section file, specify the following command on your command line:
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:
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.
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:
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.
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:
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:
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:
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.
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.