HP OpenVMS Systems Documentation

The prompt for the command file name shows, in brackets, the default command file that EVE uses if you press the Return key at the prompt without typing a file name. This default is one of the following:

• The command file specified with the /COMMAND qualifier when you invoked EVE
• A file called TPU$COMMAND.TPU in your current directory
• The command file defined by the logical name TPU$COMMAND

You can set your preferred default command file --- that is, the command file you want EVE to create or update without having to specify the file each time you save attributes. For example, the following command sets your default command file as MYCOM in your current directory:

Command: SET DEFAULT COMMAND FILE MYCOM

If you want to save in a command file rather than in a section file, you should also use the SET NOSECTION FILE PROMPTING command. Then, when you save attributes, EVE asks whether to save in a command file without first asking whether to save in a section file.

Typically, when you use SET DEFAULT COMMAND FILE, you specify the command file you are going to use at startup for future editing sessions. The command does not determine the command file to be executed when you invoke EVE, but only the command file in which you save attributes and menu definitions.

For more information about creating and using command files, see the EVE online help topic called Command Files.

A.3.8 Saving EVE Default Attributes

The SAVE SYSTEM ATTRIBUTES command saves EVE default settings and menu entries in a section file or command file. Thus, if you set several attributes and defined or undefined menu entries, you can use SAVE SYSTEM ATTRIBUTES to restore the standard EVE settings and menus to your section file or command file.

SAVE SYSTEM ATTRIBUTES does not change the settings currently in effect --- for example, it does not enable free cursor motion or invisible tabs --- but saves only the EVE defaults in a section file or command file.

A.4 Using DECTPU Within EVE

You can use DECTPU within EVE to create DECTPU command files and to use the DECTPU debugging package.

File creation switches and qualifiers determine whether DECTPU creates a buffer when it does not find the input file. The processing results of using this qualifier depend on the DECTPU application you are using.

In EVE, files are created by default. If the input file does not exist, EVE uses the input file name and file type to create the buffer name. If you do not specify an input file, EVE creates a buffer named Main.

A.4.1 Creating DECTPU Command Files

To create DECTPU command files, use the /CREATE or /NOCREATE qualifiers, as follows:

$ EDIT/TPU /CREATE (default)
$ EDIT/TPU /NOCREATE

Use the /NOCREATE qualifier to avoid invoking the editor in case you mistype the input file specification or to edit only an existing file.

If EVE does not find an input file you have specified, it terminates the editing session and returns you to the system level, as in the following example:

$ EDIT/TPU NEW.DAT /NOCREATE
Input file does not exist: NEW.DAT;

Debug switches and qualifiers determine whether DECTPU runs a debug file. A debug file is useful for testing procedures for an application that you are creating.

To edit the code in the file you are debugging, follow these rules:

1. Use the GO command. You cannot use wildcards to specify the debug file.
2. Specify only one debug file at a time. DECTPU compiles and executes the debug file before executing TPU$INIT_PROCEDURE.

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.

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.5 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.

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.5.1 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, Compaq 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.

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.
• Compaq 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.5.2 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.

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.6 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.

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.

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 EVE Command File. 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.

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

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.7.1 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.8 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.

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 EVE Command File. 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.7.2 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.

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.7.2.1 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.

EVE Command File

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: