HP OpenVMS Systems Documentation
Guide to the DEC Text Processing Utility
5.5 Executing DECTPU Programs
You can use programs that are already compiled as parameters for the EXECUTE built-in procedure. In addition, you can use buffers, ranges, or strings that contain executable DECTPU statements as parameters for the EXECUTE built-in procedure. DECTPU compiles the contents of the buffer, range, or string if necessary; then DECTPU executes the compiled buffer, range, or string.
After using the TPU command, suppose you used the following statement to create a program called new_program:
You could then execute new_program by using the following statement after using the TPU command:
You could also compile and execute the statements in the current buffer by using the following TPU statement after using the TPU command:
You can enter, compile, and execute small DECTPU programs on the EVE command line. The following example shows a small program that you can enter after the TPU Statement: prompt.
The preceding command executes the program associated with the SET
(TIMER) built-in procedure and causes the string "Executing"
to be displayed at 1-second intervals when a long procedure is
executing. The string is displayed in the last 15 spaces of the prompt
area at 1-second intervals.
If you include procedure declarations as part of a program, the procedure is compiled and the procedure name is added to the DECTPU list of procedures when you execute the program. You invoke the procedure in one of the following ways:
5.5.2 Process Suspension
Pressing Ctrl/C causes DECTPU to stop the execution of a user-written program. You can also stop the execution of the following DECTPU built-in procedures with Ctrl/C:
DECTPU startup files are files that DECTPU reads, compiles, and executes during its initialization sequence.
There are three types of DECTPU startup files:
5.6.1 Section Files
To execute a section file, use the /SECTION qualifier with the EDIT/TPU command or let DECTPU execute the default section file.
The default section file is TPU$SECTION. When DECTPU tries to locate the section file, DECTPU supplies a default directory of SYS$SHARE and a default file type of .TPU$SECTION. OpenVMS systems define the system-wide logical name TPU$SECTION as EVE$SECTION, so the default section file is the file that implements the EVE editor. To override the OpenVMS default, redefine TPU$SECTION.
A command file contains a series of DECTPU procedures followed by a sequence of TPU statements. To direct DECTPU to compile and execute a command file, use the appropriate command syntax, as explained in this section.
The default command file is TPU$COMMAND. When DECTPU tries to locate
the command file, it supplies a default file type of .TPU. To direct
DECTPU to compile and execute a particular command file, define the
logical name TPU$COMMAND to be the file you want DECTPU to use.
For more information on the /COMMAND qualifier, see Section 2.6.2.
An initialization file contains commands to be executed by an application layered on DECTPU. To specify an initialization file to be executed, use the appropriate command syntax, as explained in this section.
DECTPU does not determine the default handling of an initialization file; nor does DECTPU directly load or execute the commands in an initialization file. The application layered on DECTPU must determine the defaults and must handle the loading and execution of an initialization file. For example, EVE reads an initialization file (if one is present) and interprets the initialization commands when it processes the appropriate initialization file. Any key definitions in an initialization file override corresponding key definitions saved in a section file and key definitions in a command file.
Typically, you use EVE initialization files to set values that are not usually saved in a section file, such as margins, tab stops, and bound or free cursor. For a list of the EVE default values that you might want to modify by using an EVE initialization file, see the Extensible Versatile Editor Reference Manual.
To use an initialization file, use the /INITIALIZATION qualifier with
the EDIT/TPU command. For more information on the /INITIALIZATION
qualifier, see Section 2.6.6.
When you invoke DECTPU, by default DECTPU reads, compiles, and executes several files. The sequence in which DECTPU performs these tasks is as follows:
If a layered application makes use of an initialization file, it is the
responsibility of the application to define when the initialization
file is processed. EVE processes initialization files during the
A section file is the binary form of a program that
implements a DECTPU-based editor or application. It is a collection of
compiled DECTPU procedure definitions, variable definitions, and key
bindings. The advantage of using a binary file is that the source code
does not have to be compiled each time you invoke the editor or
application, so startup performance is improved.
To create a section file, begin by writing a program in the DECTPU language. The program must adhere to all the programming conventions discussed throughout this manual. For examples of programs used to create a section file, see the files in the directory SYS$EXAMPLES. This directory contains the sources used to create the EVE section file. To see a list of the EVE source files, type the following:
If you cannot find these files on your system, see your system manager.
When writing the DECTPU program that implements your application, place your initializing statements in a procedure named TPU$INIT_PROCEDURE. Such statements might create buffers, create windows, associate windows with buffers, set up screen attributes, initialize variables, define how the journal facility works, and so on. You can put the procedure TPU$INIT_PROCEDURE anywhere in the procedure declaration portion of your program. DECTPU executes TPU$INIT_PROCEDURE before executing the command file (if there is one). For more information on DECTPU's initialization sequence, see Section 5.6.4.
Place any statements that implement or handle initialization files in a procedure named TPU$INIT_POSTPROCEDURE. DECTPU executes this procedure after both the TPU$INIT_PROCEDURE and the command file have been executed. This enables commands or definitions in the initialization file to modify commands or definitions in the command file. EVE defines both TPU$INIT_PROCEDURE and TPU$INIT_POSTPROCEDURE procedures. For more information on how EVE implements initialization files, see Section 5.6.7.
After you put the desired DECTPU procedures and statements into the program that implements your application, end your program with the following statements:
For more information on SAVE and QUIT, see the descriptions of these built-ins in the DEC Text Processing Utility Reference Manual. For examples of files that use these statements, see Example 5-4 and Example 5-5.
To compile your program into a section file, invoke DECTPU but do not supply as a parameter the name of a file to be edited. Use the /NOSECTION qualifier to indicate that no existing section file should be loaded. Use the /COMMAND qualifier to specify the file that contains your program. For example, to create a section file from a program in a file called my_application.tpu, enter the following at the DCL prompt:
This command causes DECTPU to write the binary form of the file MY_APPLICATION.TPU to the file you specified as the parameter to the SAVE statement in your program. To use the section file, invoke DECTPU, specifying your section file.
To extend an existing section file, begin by writing a program in the DECTPU language.
If you are extending the EVE section file, put your initializing statements in an initialization procedure called TPU$LOCAL_INIT. TPU$LOCAL_INIT is an empty procedure in the EVE section file. When you add your DECTPU statements and procedures to the EVE section file, your procedure named TPU$LOCAL_INIT supersedes EVE's original empty value of TPU$LOCAL_INIT. TPU$LOCAL_INIT is called at the end of the procedure TPU$INIT_PROCEDURE during the initialization sequence. For more information on the initialization sequence, see Section 5.6.4.
If you are extending a non-EVE section file, you must determine whether that section file has implemented the convention of including a TPU$LOCAL_INIT procedure.
After adding DECTPU procedures and statements that implement your application, end your program with the following statements:
For more information on SAVE and QUIT, see the descriptions of these built-ins in the DEC Text Processing Utility Reference Manual.
Example 5-4 shows the syntax of a program that could be used to create a section file.
To add your program to an existing section file, invoke DECTPU but do not supply as a parameter the name of a file to be edited. Use the /SECTION qualifier to specify the section file to which you want to add your program. Use the /COMMAND qualifier to specify the file that contains your program. For example, to add a program called MY_CUSTOMIZATIONS.TPU to the EVE section file, you would enter the following:
This command causes DECTPU to load the EVE section file and then read, compile, and execute the command file you specify. A new section file is created. The new file includes both the EVE section file and the binary form of your program. The section file is written to the file you specified as the parameter to the SAVE statement in your program. To use the section file, invoke DECTPU, specifying your section file.
For more information on invoking DECTPU, see Chapter 2.
For more information on extending the EVE section file, see the
Extensible Versatile Editor Reference Manual.
If you choose to design an application layered on DECTPU and not layered on EVE, you must provide certain basic structures and key definitions to be able to use the DECTPU compiler and interpreter. Example 5-5 is a sample of the source code that creates a minimal interface. It provides the following basic structures:
Because DECTPU does not have any keys defined when invoked without a section file, the sample program also contains the following key definitions:
By default, DECTPU looks for TPU$INIT_PROCEDURE, so the statements that create the structures for a minimal interface are contained in TPU$INIT_PROCEDURE. Individual statements that define keys come after any procedures in the file.
If you entered the text from Example 5-5 into a file named MINI.TPU and you want to compile that file into a section file, enter the following command:
In the previous example, the /NOSECTION qualifier specifies that DECTPU does not read a section file. This ensures that none of the procedures or variables from an existing section file are loaded into the internal DECTPU tables. The /COMMAND qualifier specifies that DECTPU compiles the command file MINI.TPU. The SAVE built-in procedure at the end of the command file specifies that all of the procedures, variables, and key definitions in the file are to be saved in binary form in SYS$LOGIN:MINI.TPU$SECTION. The QUIT built-in procedure then causes you to leave DECTPU.
Example 5-5 contains the source code for a command file that you can use for a minimal interface to DECTPU.
If you created the section file SYS$LOGIN:MINI.TPU$SECTION, you could use the procedures and definitions in that file as an interface to DECTPU. To invoke DECTPU with SYS$LOGIN:MINI.TPU$SECTION as the MINI section file, use the following command:
Whenever you want to add new procedures, variables, learn sequences, or key definitions to a section file, edit the command file to include the new items, and then recompile the command file to produce a section file with the new items. For example, if you want to add key definitions for the arrow keys, you could edit the file MINI.TPU and add the following statements after any procedures in the file:
Recompile the command file with the following command:
After you have completed the previous steps, you can use the section file you created to invoke DECTPU with the new key definitions included.
An alternate way of adding these key definitions to your section file is to enter the definitions as text in the current buffer. You could then press the Tab key (the command prompt key for the minimal interface) and enter the following command after the prompt:
This causes the new key definitions to be added to your current editing context. To add the definitions to the section file so you can use them in future sessions, enter the following statement at the Command prompt:
If you want to save the DECTPU source code for the key definitions,
write out the current buffer or use the EXIT built-in procedure to
leave the DECTPU session so that the contents of the buffer are written
to a file.
A section file that implements a layered application should include the following procedures:
If your application is to support initialization files, the section file that implements the application should also include a procedure called TPU$INIT_POSTPROCEDURE. This procedure should contain the DECTPU statements that implement or handle the initialization files.
For information on EVE's implementation of initialization files, see Section 5.6.7.
You can add other functions to TPU$INIT_PROCEDURE, but it should perform at least these two operations.
If your application allows the end user to customize the application by using a command file, you may want to make available to the user a procedure called TPU$LOCAL_INIT. (Although this name is not required, it is commonly used by DECTPU programmers.)
In EVE, the code that implements the initialization sequence calls TPU$LOCAL_INIT before executing your command or initialization files. EVE defines this procedure but leaves it empty. The user can use this procedure in a command file to contain DECTPU statements that implement private initializations.
You can see the code that implements TPU$LOCAL_INIT in EVE in SYS$EXAMPLES:EVE$CORE.TPU.
A section file that implements a layered application should assign values to the following special variables in the procedure TPU$INIT_PROCEDURE:
If you write a section file that extends the EVE section file, EVE provides six variables (three pairs of synonyms) to be used by layered applications. Although DECTPU automatically declares the variables, the application must assign a value to one of the synonyms in each pair. If you choose to write your own application, your application must contain these structures and procedures.
Table 5-2 shows the names and uses of these variables.