OpenVMS User's Manual

The debugger that is supplied with DECTPU is in SYS$SHARE:TPU$DEBUG.TPU. This file provides commands to manipulate variables and to control program execution.

A.5.3 Specifying a Debug File

There are two ways to specify a debug file of your own:

• Define the logical name TPU$DEBUG to specify your debugger file and then use the /DEBUG qualifier when you invoke DECTPU. You can enter the definition in your LOGIN.COM file.
• Use the /DEBUG= qualifier and specify a debugger file. This overrides any definition of the TPU$DEBUG logical name. The default file type is .TPU. For example, the following command uses a debugger file named MYDEBUG.TPU to edit a file named MYPROCS.TPU:

  $ EDIT/TPU MYPROCS.TPU /DEBUG=MYDEBUG
  

  
  DECTPU assumes the debugger file is in SYS$SHARE. If your debugger file is stored elsewhere, use a complete file specification, including the device (disk) and directory.

For more information about the DECTPU debugging package, read the comments in the source file or see the DEC Text Processing Utility Reference Manual.

A.6 Using DECTPU Procedures to Extend EVE

The EVE editor is built on the DEC Text Processing Utility (DECTPU). With the EVE command TPU, you can enter any DECTPU statement or series of statements that can be expressed on one command line.

A.6.1 Entering DECTPU Commands

To enter a DECTPU command, enter the command TPU followed by the DECTPU statement you want to execute. For example, to execute the DECTPU statement APPEND_LINE, which places the current line at the end of the previous line, enter the following command string:

Command: TPU APPEND_LINE 

For more information about the TPU command, type HELP TPU. See the DEC Text Processing Utility Reference Manual for a complete list of DECTPU statements and procedures.

A.6.2 Writing DECTPU Procedures

Because EVE is an editor written in the DECTPU programming language, you can extend EVE functions by writing procedures in DECTPU. This section assumes that you are familiar with the DECTPU programming language described in the DEC Text Processing Utility Reference Manual.

Before you begin writing DECTPU procedures to modify EVE, Digital recommends that you study the EVE source code, which is stored in SYS$EXAMPLE:EVE$*.TPU. (The wildcard character (*) in the file specification indicates that EVE source code is stored in many files.) These files are put together by using EVE$BUILD. Variables and statements in your procedures should be consistent with EVE variables and statements so that you can avoid making changes that adversely affect EVE operations.

A.6.3 Rules for Writing EVE Command Procedures

You can write procedures in the DECTPU programming language that are, in effect, new EVE commands. When you write new EVE command procedures, follow these rules:

• Prefix the procedure name with the label EVE_ so that EVE recognizes the procedure as an EVE command. After you compile the procedure, execute it by pressing the Do key and typing the procedure name without the EVE_ prefix or the underscores. For example, enter SET LEFT MARGIN for the EVE_SET_LEFT_MARGIN procedure. (You can also define a key to execute the new command.)
• The words PROCEDURE and ENDPROCEDURE must start in column 1.
• Initialize all global variables in a single procedure named TPU$LOCAL_INIT or in a module initialization procedure if you build with EVE$BUILD.
• Define a global variable to associate the parameter with the data-type integer if the EVE command you are writing takes any integer parameters (such as SET LEFT MARGIN 2, where 2 is the parameter). When you are using the EVE commands that you have defined, EVE passes the null string (" ") if you do not provide a value for a string parameter. If you do not provide a value for an integer parameter, EVE passes the value EVE$K_NO_ARG.
• Digital recommends placing global variables in a procedure called TPU$LOCAL_INIT, which is called each time EVE starts. Place all procedures that use parameters in the same file that contains the TPU$LOCAL_INIT procedure.
• In general, each of the global variable names that define command parameters must consist of the following three parts:
  • The first part of the variable name must be EVE$.
  • The second part defines the variable's sequence within a procedure. For the first variable, it is ARG1; for the second, ARG2; and so on.
  • The third part of the variable name is the procedure name without the EVE_ prefix.

This is an example of a global variable definition for command parameters:

• The following definition of the global variable EVE$ARG1_ADD tells EVE to expect an integer as the first parameter for EVE_ADD:

  EVE$ARG1_ADD := "INTEGER"; 
  

• The following definition of the global variable EVE$ARG1_HELLO tells EVE to expect a string as the first parameter to EVE_HELLO:

  EVE$ARG1_HELLO := "STRING"; 
  

The integer variables are required.

A.6.5 Compiling DECTPU Procedures

The EXTEND EVE command enables you to compile a DECTPU procedure without leaving EVE. To compile the procedure that the cursor is in, use the EXTEND THIS command. To compile one procedure, enter the command EXTEND EVE and the name of the procedure you want to compile. To compile all procedures in a file, enter the command EXTEND EVE * (which is the same as the EVE command EXTEND ALL). If you miss a message from the compiler, use the command BUFFER MESSAGES to read the messages stored in the Messages buffer.

A.6.6 Example: Creating DECTPU Procedures

The following example illustrates how to create and compile DECTPU procedures to define an ADD command, a HELLO command, and the parameters for both commands. Invoke EVE to edit the file MYPROCEDURES.TPU and insert the following text into the file:

! Procedure to add two integers and display the result in the 
! message window 
 
PROCEDURE EVE_ADD (A1, A2) 
 
LOCAL   TEMP, 
        N1, 
        N2; 
 
IF NOT EVE$PROMPT_NUMBER (A1, N1, "First number to add: ", 
                          "No number specified.") 
THEN 
    RETURN (FALSE); 
ENDIF; 
 
IF NOT EVE$PROMPT_NUMBER (A2, N2, "Second number to add: ", 
                          "No number specified.") 
THEN 
    RETURN (FALSE); 
ENDIF; 
 
TEMP := N1 + N2; 
MESSAGE (STR (N1) + " + " + STR (N2) + " = " + STR (TEMP)); 
RETURN (TRUE); 
 
ENDPROCEDURE; 
 
 
PROCEDURE EVE_HELLO (MY_NAME) 
LOCAL   THE_NAME; 
 
IF EVE$PROMPT_STRING (MY_NAME, THE_NAME, "Name: ", "We haven't met") 
THEN 
    MESSAGE ("Hello " + THE_NAME); 
    RETURN (TRUE); 
ELSE 
    RETURN (FALSE); 
ENDIF; 
 
ENDPROCEDURE; 
 
EVE$ARG1_ADD := "INTEGER"; 
EVE$ARG2_ADD := "INTEGER"; 
 

Use the syntax shown in the file MYPROCEDURES.TPU to put the definitions for the two parameter variables in your TPU$LOCAL_INIT procedure.

To compile the procedures you have entered into MYPROCEDURES.TPU, press the Do key, type EXTEND EVE *, and press the Return key. If you are going to use the newly compiled commands in the current editing session, you must execute TPU$LOCAL_INIT by entering the command TPU TPU$LOCAL_INIT.

A.7 Creating Section Files

A section file contains key definitions, learn sequences, and compiled DECTPU statements and procedures in binary form. Because section files are in binary form, they set up the editing environment very quickly, but you cannot display or edit a binary file. Use a section file to implement editing features that are not likely to change from one editing session to another. The default file type for section files is .TPU$SECTION.

A.7.1 Startup Section Files

EVE requires a section file for startup. By default, EVE uses the section file EVE$SECTION.TPU$SECTION located in directory SYS$SHARE. This default section file defines the editing keys, shown in Figure 8-1 and Figure 8-2, as well as the standard EVE commands.

A.7.2 Modifying Section Files

Rather than use the default section file, you can create a modified section file that contains the standard EVE functions as well as your own key definitions, learn sequences, and editing functions. You can create a section file in two ways:

• If you have a small number of key definitions and learn sequences, define editing keys and assign learn sequences interactively. To save the definitions in a section file, enter the SAVE EXTENDED EVE command.
  The default file type for section files is .TPU$SECTION. Each time you enter the SAVE EXTENDED EVE command, you can specify the same file to ensure that all your customizations are saved cumulatively in the same file.
• If you have a large number of modifications, create a command file with key definitions and DECTPU procedures. (Note, however, that a command file cannot have learn sequences.) End the file with the SAVE and QUIT statements, assigning a section file name with the file type .TPU$SECTION, as shown in Section A.8.7. Then invoke EVE with the /COMMAND qualifier and the command file name. EVE executes statements in the command file, saves the compiled procedures and key definitions in the section file named in the SAVE statement, and then executes the QUIT statement, returning control to the DCL. You can now use the new section file, as named in the SAVE statement.

To use a section file, specify the section file name with the /SECTION qualifier on the EVE command line. For example, the following command invokes EVE with a section file named MY_SECTION.TPU$SECTION, located in directory ALEXIS on a disk called WORK1:

$ EDIT/TPU/SECTION=WORK1:[ALEXIS]MY_SECTION

By default, DECTPU uses the section file whose logical name is TPU$SECTION. If you define this logical name in your LOGIN.COM file, DECTPU automatically uses your section file when you invoke EVE. For example:

$ DEFINE TPU$SECTION WORK1:[ALEXIS]MY_SECTION.TPU$SECTION 

Use the EVE command SHOW SUMMARY to display the name of the current section file.

A.7.5 Section Files Execution

EVE executes a section file before a command file or an initialization file. Therefore, definitions in the command file and initialization file override section file definitions. When you want to set the characteristics of the editing environment, use either a command file or an initialization file. EVE executes these commands upon startup, so the appearance of the buffer and the editing mode is adjusted according to your definition.

A.8 Creating Command Files

A command file is a source program that contains DECTPU procedures and executable statements. A DECTPU procedure is a set of related DECTPU statements that are executed when the procedure name is invoked. The statements and procedures define what happens when you press a key or enter a command. The default file type for command files is .TPU.

When you use an EVE command, you are actually invoking a compiled DECTPU procedure. For example, the EVE command SET KEYPAD EDT invokes the EVE_SET_KEYPAD_EDT procedure in the standard EVE section file.

EVE executes a command file after a section file. For this reason, any key definitions or procedures defined in a command file override those in a section file.

A.8.1 Command File Usage

There are two different ways to use a command file. A command file can create an editing environment that is independent of the section file, or a command file can be used to produce a new section file.

A.8.2 Setting Editing Defaults

Whenever you want to set editing defaults, use a command file because EVE executes the statements in the command file (or initialization file) at startup and applies the new defaults. See Section A.9 for a list of commands that set the editing environment. For example, you can use one command file to set up margins and tabs and a header for a memo and another command file to set tabs suitable for writing a financial report.

To create a command file, invoke EVE and specify a file name with the file type .TPU, such as MY_COMMAND.TPU. Once in the editor, enter DECTPU statements and procedures.

A.8.3 Converting Command Files

If you intend to use a command file to create a section file, conclude the file with the SAVE and QUIT statements and include a file specification for the section file, as shown in Section A.8.7. To convert the command file to a section file, invoke EVE with the /COMMAND qualifier. For example:

$ EDIT/TPU/COMMAND=MY_COMMANDS

One advantage of creating a section file from a command file is that a command file can be easily edited. This is especially important when you want to add DECTPU procedures or add a large number of key definitions.

A.8.4 Adding Functions to the EVE Editor

To use a command file to set the characteristics of the editing environment and add functions to the standard EVE editor, again invoke EVE with the /COMMAND qualifier. For example:

$ EDIT/TPU/COMMAND=DATA_SETUP 

EVE again executes the statements in the command file but because there is no SAVE statement, the compiled procedures and key definitions are not saved.

A.8.5 Default Files Specification

If you do not include a command qualifier, EVE searches for the file specified by the logical name TPU$COMMAND. You can define this logical name in your LOGIN.COM file. If this file is not found, DECTPU then searches for a file named TPU$COMMAND.TPU in the current directory.

A.8.6 Rules for Writing Command Files

Keep in mind the following rules and suggestions when writing command files:

• Use comments to document a command file. An exclamation point (!) starts a comment. When DECTPU encounters the exclamation point, it ignores everything else on the line.
• Start each procedure with the word "procedure".
• End each DECTPU statement in the procedure with a semicolon (;).
• Make each EVE command correspond to the name of a DECTPU procedure in the section file of standard EVE (SYS$SHARE:EVE$SECTION.TPU$SECTION).
  You can use the names of these DECTPU procedures in procedures you write, or you can execute them independently as DECTPU statements. If your command file contains both user-written procedures and executable DECTPU statements, put all the procedures before any of the executable statements.
• End each procedure with the word "endprocedure".
• Use EVE_ as the first four characters of the procedure name when you write a procedure that implements a command in EVE, By following this convention, the procedure name, without the characters EVE_, becomes an EVE command.
  Because a command file executes after a section file, a procedure overwrites a command by the same name in the section file. For example, if you name a procedure EVE_ERASE_CHARACTER, the ERASE CHARACTER command executes your procedure, not the standard EVE command.
• Place parameters in parentheses if you use a DECTPU procedure name that requires parameters. The EVE format is as follows:

  SET LEFT MARGIN 10 
  

  
  The DECTPU format is as follows:

  eve_set_left_margin(10); 
  

• If a parameter is a string rather than an integer, enclose the parameter in quotation marks (" ") To pass a null parameter, use an empty pair of quotation marks (" ").
• Compile procedures before invoking them. Then the procedure can be invoked as either an EVE command or as a DECTPU executable statement.
• Add a procedure called TPU$LOCAL_INIT to a command file that you use as a section file. This procedure should contain all executable statements (including those calling other procedures) that you want to be defined and executed when EVE is invoked. Because any executable statement in this procedure is executed when EVE is invoked, the statements in this procedure become default settings for the EVE editor.
• Add the statement QUIT as the last statement in a command file if the file is to be compiled as a section file. QUIT ends EVE processing and returns control to the DCL prompt.

The following example shows a command file that modifies EVE to be more like the EDT editor. This file creates a personal section file named MY_SECTION.TPU$SECTION.

 
!********************************************************************* 
!Command file making EVE more like EDT 
!and implementing personal customizations 
!********************************************************************* 
 
!Procedure to delete a line and close the gap left by the deletion  (1)
 
PROCEDURE EVE_ZAPLINE 
 
EVE_END_OF_LINE; 
 
EVE_ERASE_START_OF_LINE;      (2)
 
EVE_DELETE; 
 
ENDPROCEDURE      
 
 
!Procedure to move the cursor to the beginning of the next paragraph: 
 
PROCEDURE EVE_NEXT_PARAGRAPH  (3)
 
LOCAL   PAT1, 
        THE_RANGE; 
 
PAT1 := line_begin + line_begin + ARB (1); 
THE_RANGE := SEARCH_QUIETLY (PAT1, forward, exact); 
 
IF THE_RANGE <> 0 
THEN 
    POSITION (END_OF (THE_RANGE)); 
    RETURN (TRUE);            (4) 
ELSE 
    RETURN (FALSE); 
ENDIF; 
 
ENDPROCEDURE 
 
!Procedure to make EVE behave more like EDT 
 
PROCEDURE EVE_MIMIC_EDT 
 
EVE_SET_KEYPAD_EDT; 
EVE_SET_CURSOR_BOUND; 
EVE_SET_LEFT_MARGIN(10);      (5)
 
ENDPROCEDURE 
 
!Procedure to transpose two characters 
 
PROCEDURE EVE_TRANSPOSE 
 
LOCAL   WHACK; 
 
WHACK := ERASE_CHARACTER (1); 
MOVE_HORIZONTAL (1); 
COPY_TEXT (WHACK); 
 
RETURN (TRUE); 
ENDPROCEDURE 
 
!Procedure to make both the screen width and the right margin narrow 
 
PROCEDURE EVE_NARROW_SCREEN 
 
EVE_SET_WIDTH (80); 
EVE_SET_RIGHT_MARGIN (79); 
 
ENDPROCEDURE; 
 
!Procedure to make both the screen width and the right margin wide 
 
PROCEDURE EVE_WIDE_SCREEN 
 
EVE_SET_WIDTH (132); 
EVE_SET_RIGHT_MARGIN (131); 
 
ENDPROCEDURE; 
 
!Procedure to toggle screen width and right margin from 
!the current setting to the other setting, for example to 
!change to wide if narrow, change to narrow if wide 
 
PROCEDURE EVE_CHANGE_WIDTH    (6)   
 
IF GET_INFO (SCREEN, "width") <> 80 
THEN 
    EVE_NARROW_SCREEN; 
ELSE 
    EVE_WIDE_SCREEN; 
ENDIF; 
 
ENDPROCEDURE; 
 
PROCEDURE TPU$LOCAL_INIT      (7)            
 
EVE_MIMIC_EDT;                (8)    
 
EVE$DEFINE_KEY ("EVE_NEXT_PARAGRAPH", CTRL_P_KEY, "Next Para", 
                EVE$X_USER_KEYS); (9) 
 
EVE$DEFINE_KEY("EVE_ZAPLINE", KEY_NAME ("O", SHIFT_KEY), "Zap Line", 
               EVE$X_USER_KEYS);  (10) 
 
EVE$DEFINE_KEY ("EVE_TWO_WINDOWS", F17, "Two Windows", EVE$X_USER_KEYS); 
                                                              (11)         
 
EVE$DEFINE_KEY ("EVE_OTHER_WINDOW", CTRL_G_KEY, "Other Window", 
                EVE$X_USER_KEYS); (12)        
 
EVE$DEFINE_KEY ("EVE_GET_FILE('')", KEY_NAME (KP6, SHIFT_KEY), "Get File", 
                EVE$X_USER_KEYS); (13) 
 
EVE$DEFINE_KEY ("EVE_TRANSPOSE", KEY_NAME (F20, SHIFT_KEY), "Transpose", 
                EVE$X_USER_KEYS); (14)
ENDPROCEDURE 
 
TPU$LOCAL_INIT;               (15) 
 
SAVE ("WORK:[LINCOLN]MY_SECTION.TPU$SECTION");   (16)                     
 
QUIT;                         (17)                                 
 

As you examine the example, note the following:

1. This line is preceded by an exclamation point (!), thus DECTPU ignores everything else on the line.
2. Each EVE command corresponds to the name of a DECTPU procedure in the section file of standard EVE (SYS$SHARE:EVE$SECTION.TPU$SECTION).
   You can use the names of these DECTPU procedures in procedures you write, or you can execute them independently as DECTPU statements. If your command file contains both user-written procedures and executable DECTPU statements, put all the procedures before any of the executable statements.
3. This command calls the EVE procedure EVE_NEXT_PARAGRAPH. Once the section file is compiled, you can use the new EVE command NEXT PARAGRAPH.
4. For an EVE command to be usable with a repeat count (either by itself or as part of a learn sequence), it must return TRUE when it succeeds.
5. The EVE command SET LEFT MARGIN requires a parameter specifying where to set the left margin. In this example, it is set to 10.
6. The procedure named EVE_CHANGE_WIDTH can be invoked as the EVE command CHANGE WIDTH. The procedure name can also be invoked as the DECTPU executable statement EVE_CHANGE_WIDTH.
7. The procedure called TPU$LOCAL_INIT is used as a section file.
8. This DECTPU statement invokes the procedure EVE_MIMIC_EDT, which contains DECTPU statements that change the EVE settings. If you compile the sample command file, save it in a personal section file, and use that section file to invoke EVE. By doing this, the keypad setting, cursor style, and left margin are automatically set by the procedure EVE_MIMIC_EDT. As a result, EVE behaves like EDT at startup.
9. This DECTPU statement uses the predefined EVE routine EVE$DEFINE_KEY to define the user-written procedure EVE_NEXT_PARAGRAPH for the key sequence Ctrl/P. The EVE$DEFINE_KEY routine ensures that the program bound to the key has an error handler. The DECTPU built-in DEFINE_KEY does not perform this step.
   There are four parameters to EVE$DEFINE_KEY. (This routine uses the same parameters as the DECTPU built-in DEFINE_KEY.) The first specifies the EVE procedure or command to be bound to a key. The second specifies the key to which the command should be bound. The third specifies the label that EVE should use for the key in the Help keypad diagram. The fourth is an EVE variable specifying the keymap list in which the key definition should be saved. Use the variable name EVE$X_USER_KEYS for the fourth parameter unless you are an advanced user implementing a special application.
10. This DECTPU statement defines the procedure EVE_ZAPLINE for the key sequence GOLD O. This line demonstrates the DECTPU format to use when defining a sequence that consists of the GOLD key plus a letter key. Using "shift_key" makes the definition case insensitive, so that both o and O are defined.
11. This statement defines the EVE command TWO WINDOWS for the F17 key.
12. This statement defines the EVE command OTHER WINDOW for the key sequence Ctrl/G.
13. This statement defines the EVE command GET FILE for the key sequence GOLD KP6. This keypad binding supersedes the previous definition of the GOLD KP6 key. The EVE_MIMIC_EDT procedure sets the keypad to EDT and the EDT keypad then binds the GOLD KP6 key sequence to the INSERT HERE command. However, this DECTPU statement changes the key binding to the GET FILE command. The pair of single quotation marks passes a null argument to the procedure.
14. This statement defines the procedure EVE_TRANSPOSE for the key sequence GOLD F20.
15. This statement calls the procedure TPU$LOCAL_INIT, which is then executed, creating new default settings for EVE.
16. The SAVE statement is included to create a new section file. The device, directory, and file name of the section file are specified in parentheses and quotation marks.
17. The QUIT command ends EVE processing and returns control to the DCL prompt.

Rather than defining keys or setting the characteristics of an editing session interactively, you can put EVE commands and key definitions in an initialization file. You can execute an initialization file when invoking EVE or during an editing session by using the execute procedure (@) command. For example,

Command: @SETUP_INIT

The following rules apply when creating initialization files:

• Begin each command on a separate line.
• Precede each line of comments with an exclamation point (!) and place separately from command lines.
• Give the initialization file the file type .EVE.

This is an example of an initialization file:

SET TABS EVERY 5 
SET LEFT MARGIN 15 
SET RIGHT MARGIN 75 
OVERSTRIKE MODE 
DEFINE KEY=Ctrl/D ERASE WORD 
DEFINE KEY=GOLD W START OF LINE 
DEFINE KEY=KP5 FILL PARAGRAPH 
! 
!Binds the EDT forward function (KP4 on 
!EDT keypad) to GOLD F 
! 
DEFINE KEY=GOLD F EDT KP4 

You can specify an initialization file with the /INITIALIZATION qualifier, defined as EVE$INIT in your LOGIN.COM file or named EVE$INIT.EVE in your SYS$LOGIN directory. The following command invokes EVE with the initialization file named MY_INIT:

$ EDIT/TPU/INIT=WORK1:[ALEXIS]MY_INIT

By default, DECTPU uses the initialization file whose logical name is EVE$INIT. If you define this logical name in your LOGIN.COM file, DECTPU automatically uses your initialization file when you invoke EVE. For example, you could insert the following command in your LOGIN.COM file:

$ DEFINE EVE$INIT WORK1:[ALEXIS]MY_INIT.EVE 

When EVE starts up, it looks first for a section file, then for a command file, and finally for an initialization file. Because an initialization file is executed after a section file and a command file, the definitions in an initialization file override those in a section file or a command file. For this reason, place commands that define the editing environment in either your command file or your initialization file.

A.9.5 Commands That Define the Environment

Commands that define the environment include the following:

• SET CURSOR BOUND or FREE
• SET FIND WHITESPACE or NOWHITESPACE
• SET GOLD KEY
• SET KEYPAD
• SET LEFT MARGIN
• SET RIGHT MARGIN
• SET SCROLL MARGINS
• SET TABS AT or EVERY
• SET TABS SPACES, MOVEMENT, or INSERT
• SET TABS VISIBLE or INVISIBLE
• SET WIDTH
• SET WILDCARD VMS or ULTRIX
• SET WRAP or NOWRAP
• The default mode of the buffer: CHANGE MODE, OVERSTRIKE MODE, or INSERT MODE
• The default direction of the buffer: CHANGE DIRECTION, FORWARD, or REVERSE

You can save key definitions, learn sequences, and DECTPU procedures in a startup file. With a startup file, you can save all the modifications you have made to EVE so you do not have to recreate your modifications at each editing session.

A.10.1 Types of Startup Files

EVE has three types of startup files:

• Section files
• Command files
• Initialization files

  6489P039.HTM
  OSSG Documentation
  22-NOV-1996 13:17:36.21

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal