Document revision date: 19 July 1999
[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.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: 


TPU Statement: new_program := COMPILE (CURRENT_BUFFER);

You could then execute new_program by using the following statement after using the TPU command: 


TPU Statement: EXECUTE (new_program);

You could also compile and execute the statements in the current buffer by using the following TPU statement after using the TPU command: 


TPU Statement: EXECUTE (CURRENT_BUFFER);

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. 


TPU Statement: SET (TIMER, ON, "Executing");

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.

5.5.1 Procedure Execution

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

To suspend a process, you can use Ctrl/C.

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:

Caution
Because DECTPU does not journal Ctrl/C, using Ctrl/C may affect the accuracy of your keystroke journal file. In addition, Ctrl/C prevents completion of some built-in procedures, such as ERASE_RANGE, MOVE_TEXT, and FILL. DECTPU behavior after such an interruption is unpredictable. DIGITAL recommends that you exit from the editor after pressing Ctrl/C to ensure that you do not lose any work because of an inaccurate keystroke journal file.

Buffer-change journaling works properly with Ctrl/C. Therefore, if you are not using keystroke journaling, exiting from the editor is not necessary.

For more information on the effects of pressing Ctrl/C, see Section 4.9.4.14 and Section 4.9.4.16.

5.6 Using DECTPU Startup Files

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

A section file is the compiled binary form of a file that contains DECTPU source code. To direct DECTPU to execute a section file, use the appropriate command syntax for your section.

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.

For more information on the /SECTION qualifier, see Section 2.6.13.

5.6.2 Command Files

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.

To specify a DECTPU command file, use either the /COMMAND qualifier with the EDIT/TPU command or let DECTPU compile and execute the default command file.

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.

5.6.3 Initialization Files

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.

5.6.4 Sequence in Which DECTPU Processes Startup Files

When you invoke DECTPU, by default DECTPU reads, compiles, and executes several files. The sequence in which DECTPU performs these tasks is as follows:

  1. DECTPU loads into memory the specified or default section file unless you specify the /NOSECTION qualifier on the command line.
  2. DECTPU reads the specified or default command file, if found, into a buffer named $LOCAL$INI$ unless you specify the /NOCOMMAND qualifier on the command line.
  3. If you specify the /DEBUG qualifier on the command line, DECTPU reads the specified or default debugger file into a buffer named $DEBUG$INI$. A debugger file contains DECTPU procedures and statements to help debug DECTPU code. For more information on the default DECTPU debugger, see Section 5.7.
  4. If the buffer named $DEBUG$INI$ (which contains debugger code) is present, DECTPU compiles the buffer and executes the resulting program.
  5. DECTPU calls and executes the procedure named TPU$INIT_PROCEDURE if the procedure is present in the section file or is defined in the debug file.
  6. If the command file is read into the buffer named $LOCAL$INI$, DECTPU compiles that buffer and executes the resulting program.
  7. DECTPU calls and executes the procedure named TPU$INIT_POSTPROCEDURE if the layered application has defined this procedure in the section file, debug file, or command file.

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 TPU$INIT_POSTPROCEDURE phase.

5.6.5 Using Section Files

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.

5.6.5.1 Creating and Processing a New Section File

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: 


$ DIR SYS$EXAMPLES:EVE$*.TPU

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: 


$ EDIT/TPU/NOSECTION/COMMAND=my_application.tpu

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.

For more information on invoking DECTPU, see Chapter 2.

5.6.5.2 Extending an Existing 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.

Example 5-4 Sample Program for a Section File 

PROCEDURE tpu$local_init 
     . 
     . 
     . 
ENDPROCEDURE; 
 
PROCEDURE vt100_keys 
    . 
    . 
    . 
ENDPROCEDURE; 
 
vt100_keys;  !Call the procedure that defines the keys 
 
SAVE ("vt100ini.tpusection"); 
 
QUIT;

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: 


$ EDIT/TPU/SECTION=EVE$SECTION/COMMAND=my_customizations.tpu

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.

5.6.5.3 Sample Section File

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: 


$ EDIT/TPU/NOSECTION/COMMAND=MINI.TPU

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.

Example 5-5 Source Code for Minimal Interface to DECTPU 

! MINI.TPU - minimal DECTPU interface 
 
PROCEDURE tpu$init_procedure 
 
! Create a buffer and window for messages 
 
    message_buffer := CREATE_BUFFER ("Message Buffer"); 
    SET (NO_WRITE, message_buffer); 
    SET (SYSTEM, message_buffer); 
    SET (EOB_TEXT, message_buffer, ""); 
    message_window := CREATE_WINDOW (21, 4, OFF); 
    MAP (message_window, message_buffer); 
 
! Create a buffer and window for SHOW 
 
    show_buffer := CREATE_BUFFER("Show Buffer"); 
    SET (NO_WRITE, show_buffer); 
    SET (SYSTEM, show_buffer); 
    info_window := CREATE_WINDOW (1, 20, ON); 
 
! Create a buffer and window for editing 
 
    main_buffer := CREATE_BUFFER ("Main Buffer"); 
    main_window := CREATE_WINDOW (1, 20, ON); 
    MAP (main_window, main_buffer); 
! Create an area on the screen for prompts 
 
    SET (PROMPT_AREA, 21, 1, NONE); 
 
!Put the editing point in the main buffer 
 
    POSITION (main_buffer); 
    tpu$local_init; 
 
ENDPROCEDURE; 
 
PROCEDURE tpu$local_init   !Procedure to allow end users 
                           !to add private extensions 
ENDPROCEDURE; 
 
! Define the minimal editing keys: 
 
  DEFINE_KEY ("SPLIT_LINE", RET_KEY); 
  DEFINE_KEY ("ERASE_CHARACTER(-1)", DEL_KEY); 
  DEFINE_KEY ("EXECUTE(READ_LINE('DECTPU Statement: '))", TAB_KEY); 
  DEFINE_KEY ("EXIT", Ctrl_Z_KEY); 
 
! Create a section file and then quit 
 
IF (get_info/system,("operating_system")=ULTRIX) 
THEN 
   save('/usr/user/jacki/mini.tpu_section'); 
ELSE 
   save('sys$login.mini); 
ENDIF 
 
QUIT; 
 
! End of MINI.TPU

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: 


$ EDIT/TPU/SECTION=SYS$LOGIN:MINI your_text.fil

You can define the logical name TPU$SECTION to point to your section file. By default, DECTPU looks for a file that TPU$SECTION points to and reads that file as the default section file.

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: 


DEFINE_KEY  ("MOVE_VERTICAL (-1)",  UP); 
DEFINE_KEY  ("MOVE_VERTICAL (1)",   DOWN); 
DEFINE_KEY  ("MOVE_HORIZONTAL (1)",  RIGHT); 
DEFINE_KEY  ("MOVE_HORIZONTAL (-1)", LEFT);

Recompile the command file with the following command: 


$ EDIT/TPU/NOSECTION/COMMAND=MINI.TPU

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: 


TPU Statement: EXECUTE (CURRENT_BUFFER);

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: 


Command: SAVE ("sys$login:mini");

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.

5.6.5.4 Recommended Conventions for Section Files

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.

The TPU$INIT_PROCEDURE procedure should perform the following operations:

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.

Table 5-2 Special DECTPU Variables That Require a Value from a Layered Application
Recommended Name Synonym Provided for Backward Compatibility Data Type Structure How DECTPU Uses the Variable
TPU$X_MESSAGE_BUFFER MESSAGE_BUFFER Buffer DECTPU writes messages in this buffer. If the MESSAGE_BUFFER is associated with a window that is mapped to the screen, DECTPU updates the window. If the application does not assign a buffer to this variable, DECTPU writes messages to the screen.
TPU$X_SHOW_BUFFER SHOW_BUFFER Buffer DECTPU writes information stored by the SHOW built-in in this buffer.
TPU$X_SHOW_WINDOW INFO_WINDOW Window DECTPU displays information stored by the SHOW built-in in this window.

If you want to use the SHOW built-in procedure in your application, you must create these special variables that DECTPU uses for SHOW.

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_012.HTML