DECTPU aids application and system programmers in developing tools that manipulate text. For example, programmers can use DECTPU to design an editor for a specific environment.

DECTPU provides the following special features:

DECTPU is a language that you can use as a base on which to layer text processing applications. When you choose an editor or other application to layer on DECTPU, that becomes the interface between you and DECTPU. You can also create your own interface to access DECTPU.

Figure 1.1 shows the relationship of DECTPU with EVE as its user interface.

You can use DECTPU on the OpenVMS VAX and OpenVMS Alpha operating systems.

You can display text in two environments:

The DECwindows environment has a number of toolkits and libraries that contain routines for creating and manipulating DECwindows interfaces. DECwindows DECTPU contains a number of built-in procedures that provide access to the routines in the DECwindows libraries and toolkits.

With these procedures, you can create and manipulate various features of a DECwindows interface from within a DECTPU program. In most cases, you can use DECTPU DECwindows built-in procedures without knowing what DECwindows routine a given built-in procedure calls. For a list of the kinds of widgets you can create and manipulate with DECTPU built-in procedures, see Chapter 5.

You cannot directly call DECwindows routines (such as X Toolkit routines) from within a program written in the DECTPU language. To use a DECwindows routine in a DECTPU program, use one or more of the following techniques:

The DECwindows version of DECTPU does not provide access to all of the features of DECwindows. For example, there are no DECTPU built-in procedures to handle floating-point numbers or to manipulate entities such as lines, curves, and fonts.

With DECwindows DECTPU, you can create a wide variety of widgets, designate callback routines for those widgets, fetch and set geometry and text-related resources of the widgets, and perform other functions related to creating a DECwindows application. For example, the DECwindows EVE editor is a text processing interface created with DECwindows DECTPU.

You can use DECTPU programs with DECwindows User Interface Language (UIL) files just as you would use programs in any other language with UIL files. For an example of a DECTPU program and a UIL file designed to work together, see the description of the CREATE_WIDGET built-in in the DEC Text Processing Utility Reference Manual. For more information about using UIL files in conjunction with programs written in other languages, see the VMS DECwindows Guide to Application Programming.

The DECTPU language has an extensive set of data types. You use data types to interpret the meaning of the contents of a variable. Unlike many languages, the DECTPU language has no declarative statement to enforce which data type must be assigned to a variable. A variable in DECTPU assumes a data type when it is used in an assignment statement. For example, the following statement assigns a string data type to the variable this_var:

this_var := ’This can be a string of your choice.’;

The following statement assigns a window data type to the variable x. The window occupies 15 lines on the screen, starting at line 1, and the status line is off (not displayed).

x := CREATE_WINDOW (1, 15, OFF);

Many of the DECTPU data types (for example, learn and pattern) are different from the data types usually foun d in programming languages. See the DEC Text Processing Utility Reference Manual for the keywords used to specify data types. See Chapter 3 of this manual for a discussion of DECTPU data types.

DECTPU language declarations include the following:

See Chapter 4 of this manual for a discussion of DECTPU language declarations.

DECTPU language statements include the following:

See Chapter 4 of this manual for a discussion of DECTPU language statements.

The DECTPU language has many built-in procedures that perform functions such as screen management, key definition, text manipulation, and program execution.

You can use built-in procedures to create your own procedures. You can also invoke built-in procedures from within EVE. The DEC Text Processing Utility Reference Manual contains a description of each of the DECTPU built-in procedures.

You can write your own procedures that combine DECTPU language statements and calls to DECTPU built-in procedures. DECTPU procedures can return values and can be recursive. After you write a procedure and compile it, you use the procedure name to invoke it.

When writing a procedure, use the following guidelines:

If the statement or call is not followed by another statement or call, the semicolon is not necessary.

Example 1.1 is a sample procedure that uses the DECTPU language statements PROCEDURE/ENDPROCEDURE and the built-in procedures POSITION, BEGINNING_OF, and CURRENT_BUFFER to move the current character position to the beginning of the current buffer. The procedure uses the MESSAGE built-in to display a message; it uses the GET_INFO built-in to get the name of the current buffer.

! This procedure moves the editing
! position to the top of the buffer

PROCEDURE user_top

   POSITION (BEGINNING_OF (CURRENT_BUFFER));
   MESSAGE ("Now in buffer" + GET_INFO (CURRENT_BUFFER, "name"));

ENDPROCEDURE;

Once you have compiled this procedure, you can invoke it with the name user_top. For information about writing procedures, see Chapter 4 and Chapter 5.

Table 2.1 lists the default TPU and EVE file specifications on OpenVMS systems.

?

?

?

OpenVMS system managers should note that the OpenVMS systemwide logical name is defined as TPU$SECTION to point to EVE$SECTION.TPU$SECTION. You can modify this logical to use a different default editing interface.

Command files and section files can create or customize a DECTPU editor or application. Initialization files can customize EVE or other layered applications by using EVE or other application-specific commands, settings, and key bindings.

A command file is a file that contains DECTPU source code. A command file has the file type .TPU and is used with the DECTPU /COMMAND= filespec qualifier. DECTPU tries to read a command file unless you specify /NOCOMMAND. The default command file is the file called TPU$COMMAND.TPU in your current directory, if such a file exists. You can specify a different file by defining the logical name TPU$COMMAND.

A section file is the compiled form of DECTPU source code. It is a binary file that has the default file type .TPU$SECTION. It is used with the qualifier /SECTION= filespec . The default section file is TPU$SECTION.TPU$SECTION in the area SYS$SHARE. The systemwide logical name TPU$SECTION is defined as EVE$SECTION. This definition causes the EVE editor to be invoked by default when you use the DCL command EDIT/TPU. You must specify a different section file (for example, /SECTION= my_section_file) or /NOSECTION if you do not want to use the EVE interface.

An initialization file contains commands for a DECTPU-based application. For example, an initialization file for EVE can contain commands that define keys or set margins. Initialization files are easy to create, but they cause DECTPU to start up somewhat more slowly than section and command files do. To invoke an initialization file, use the /INITIALIZATION qualifier. For more information on using initialization files, see Chapter 5.

You can use either a command file or a section file, or both, to customize or extend an existing interface. Generally, you use a command file for minor customization of an interface. Because startup time is faster with a section file, you should use a section file when the customization is lengthy or complex, or when you are creating an interface that is not layered on an existing editor or application. You can use an initialization file only if your application supports the use of such a file.

The source files for EVE are in SYS$ EXAMPLE S. To see a list of the EVE source files, type the following at the DCL prompt:

$ DIRECTORY SYS$EXAMPLES:EVE$*.TPU

If you cannot find these files on your system, see your system manager.

Chapter 5 describes how to write and process command files and section files.

You can run DECTPU with a special editing environment by writing a DCL command procedure that first establishes the environment that you want and then invokes DECTPU. In such a command procedure, you must define SYS$INPUT to have the same value as SYS$COMMAND because DECTPU signals an error if SYS$INPUT is not defined as the terminal. To prevent such an error, place the following statement in the command procedure setting up the environment:

$ DEFINE/USER SYS$INPUT SYS$COMMAND

Example 2.1 shows a DCL command procedure that ‘‘remembers’’ the last file that you were editing and uses it as the input file for DECTPU. When you edit a file, the file name you specify is saved in the DCL symbol last_file_edited . If you do not specify a file name when you invoke the editor the next time, the file name from the previous session is used.

$ IF P1 .NES. "" THEN last_file_edited == P1
$ WRITE SYS$OUTPUT "*** ’’last_file_edited’ ***"
$ DEFINE/USER SYS$INPUT SYS$COMMAND $
EDIT/TPU/COMMAND=DISK$:[USER]TPU$COMMAND.TPU ’last_file_edited’

Example 2.2 establishes an environment that specifies tab stop settings for FORTRAN programs.

$ IF P1 .EQS. "" THEN GOTO REGULAR_INVOKE
$ last_file_edited == P1
$ FTN_TEST = F$FILE_ATTRIBUTES (last_file_edited,"RAT")
$ IF FTN_TEST .NES. "FTN" THEN GOTO REGULAR_INVOKE
$ FTN_INVOKE:
$     DEFINE/USER SYS$INPUT SYS$COMMAND
$     EDIT/TPU/COMMAND=FTNTABS ’last_file_edited’
$ GOTO TPU_DONE
$ REGULAR_INVOKE:
$     DEFINE/USER SYS$INPUT SYS$COMMAND
$     EDIT/TPU/ ’last_file_edited’
$ TPU_DONE:

In some situations, you may want to put all of your editing commands in a file and have them read from the file rather than entering the commands interactively. You may also want DECTPU to perform the edits without displaying them on the screen. You can do this type of editing from a batch job; or, if you want to see the results of the editing session displayed on your screen, you can do this type of editing from a DCL command procedure. Even though the edits are not displayed on your screen as they are being made, your terminal is not free while the command procedure is executing.

Example 2.3 shows a DCL command procedure named INVISIBLE_TPU.COM, which contains a single command line that uses the following qualifiers to invoke DECTPU:

! This command procedure invokes DECTPU without an editor.
! The file GSR.TPU contains the edits to be made.
! Specify the file to which you want the edits made as p1.
!
$ EDIT/TPU/NOSECTION/COMMAND=gsr.tpu/NODISPLAY ’p1’
!

The DECTPU command file GSR.TPU, which is used as the file specification for the /COMMAND qualifier, performs a search through the current buffer and replaces a string or a pattern with a string. Example 2.4 shows the file GSR.TPU. GSR.TPU does not create or manipulate any windows.

PROCEDURE global_search_replace (str_or_pat, str2)

! This procedure performs a search through the current
! buffer and replaces a string or a pattern with a new string

LOCAL src_range, replacement_count;

! Return to caller if string not found
ON_ERROR
   msg_text := FAO (’Completed !UL  replacement!%S’, replacement_count);
   MESSAGE (msg_text);
   RETURN;
ENDON_ERROR;

replacement_count := 0;

LOOP
   src_range := SEARCH (str_or_pat, FORWARD);  ! Search returns a range if found
   ERASE (src_range);                          ! Remove first string
   POSITION (END_OF (src_range));              ! Move to right place
   COPY_TEXT (str2);                           ! Replace with second string
   replacement_count := replacement_count + 1;
ENDLOOP;
ENDPROCEDURE;        ! global_search_replace

! Executable statements
input_file := GET_INFO (COMMAND_LINE, "file_name");
main_buffer:= CREATE_BUFFER ("main", input_file);
POSITION (BEGINNING_OF (main_buffer));
global_search_replace ("xyz$_", "user$_");
pat1:= "" & LINE_BEGIN & "t";
POSITION (BEGINNING_OF (main_buffer));
global_search_replace (pat1, "T");
WRITE_FILE (main_buffer, "newfile.dat");
QUIT;

To use the DCL command procedure INVISIBLE_TPU.COM interactively, invoke it with the DCL command @ (at sign). For example, to use INVISIBLE_ TPU.COM interactively on a file called MY_F ILE.TXT, type the following at the DCL prompt:

$ @invisible_tpu my_file.txt

You must explicitly write out any modified buffer s before leaving the editor with QUIT or EXIT. If you use QUIT before writing out such buffer s, DECTPU quits without saving the modifications. If you use EXIT, DECTPU asks if it should write the file before exiting.

In keystroke journaling, DECTPU keeps track of each keystroke made during a session, regardless of which buffer is in use. If a system interruption occurs during a session, you can reconstruct the work done during the session. To determine the name of the keystroke journal file, use a statement similar to the following:

filename := GET_INFO (SYSTEM, "journal_file");

For more information on using a keystroke journal file for recovery, see ??? and the Extensible Versatile Editor Reference Manual.

To reconstruct your work, use the /JOURNAL and /RECOVER qualifiers. The following example shows system recovery on a file called JACKI.SDML:

$ EDIT/TPU JACKI.SDML /JOURNAL /RECOVER

Buffer-change journaling creates a separate journal file for each text buffer. The application can use the enhanced SET (JOURNALING) built-in to direct DECTPU to establish and maintain a separate journal file for any buffer or buffer s created during the session. The application programmer or user can also use the SET (JOURNALING) built-in to turn journaling off or on for a given buffer during a session.

In the buffer’s journal file, DECTPU keeps track of the following record attributes (and any changes made to them):

The journal file also tracks the following:

To determine whether buffer-change journaling is turned on, use the following statement:

status := GET_INFO (buffer_name, "journaling");

For more information on record attributes and display values, see the descriptions of the SET (RECORD_ATTRIBUTE) and SET (DISPLAY_VALUE) built-in procedures in the DEC Text Processing Utility Manual.

Buffer-change journaling does not keep a record of all keystrokes performed while editing a given buffer.

By default, DECTPU creates the buffer-change journal file name by using the following algorithm:

For example, a buffer named TEST.BAR has a default journal file name of TEST_ BAR.TPU$ JOURNAL.

DECTPU puts all journal files in the directory defined by the logical name TPU$ JOURNAL. By default, this logical is defined as SYS$SCRATCH. You can reassign this logical name. For example, if you want journal files written to the current default directory, define TPU$ JOURNAL as [ ].

The /CHARACTER_SET qualifier determines the character set you want DECTPU to use to display 8-bit characters. The choice of character set affects how DECTPU performs the following operations on characters:

The choice of character set also affects how your text appears when printed. For the text displayed in DECTPU to look the same when printed, you must choose the same character set for both DECTPU and the printer. There are two ways to specify the character set you want to use:

If the character set you specify either with /CHARACTER_SET or by defining TPU$CHARACTER_SET is invalid, the editing session is aborted, returning you to the DCL level.

Table 2.3 shows the values you can specify with the /CHARACTER_SET qualifier or the TPU$CHARACTER_SET logical name.

• /COMMAND[[=filespec]]
• /NOCOMMAND
• /COMMAND=TPU$COMMAND.TPU (default)

The /COMMAND qualifier determines whether DECTPU com piles and executes a command file (a file of DECTPU procedures and statements) at startup time. Command files extend or modify a DECTPU-based application or create a new application. The default file type for DECTPU comman d files is .TPU. You cannot use wildcards in the file specification.

By default, DECTPU tries to read a command file called TPU$COMMAND.TPU in your default directory. You can use a full file specification after the /COMMAND qualifier or define the logical name TPU$COMMAND to point to a command file other than the default.

To determine whether you specified /COMMAND on the DCL command line, use the following call in the application:

x := GET_INFO (COMMAND_LINE, "command");

The preceding call returns 1 if /COMMAND was specified, 0 otherwise. To fetch the name of the command file specified on the command line, use the following call:

x := GET_INFO (COMMAND_LINE, "command_file");

For more information on GET_INFO, see the DEC Text Processing Utility Manual.

The following command causes DECTPU to read a command file named SYS$LOGIN:MY_TPU$COMMAND.TPU and uses LETTER.RNO as the input file for an editing session:

EDIT/TPU/COMMAND=sys$login:my_tpu$command.tpu letter.rno

To prevent DECTPU from processing a command file, use the /NOCOMMAND qualifier. If you usually invoke DECTPU without a command file, define a symbol similar to the following:

$ EDIT/TPU/COMMAND=sys$login:my_tpu$command.tpu letter.rno

Using /NOCOMMAND when you do not want to use a command file decreases startup time by eliminating the search for a command file. If you specify a command file that does not exist, DECTPU terminates the editing session and returns you to the DCL command level. For more information on writing and using command files, see Chapter 5.

• /CREATE (default)
• /NOCREATE

The /CREATE qualifier controls whether a DECTPU-based application creates a new file when the specified input file is not foun d. If you do not specify /CREATE or /NOCREATE on the comman d line, DECTPU sets the default to /CREATE but does not specify a default name for the file to be created.

The application layered on DECTPU is responsible for handling this qualifier. To determine if you specified /CREATE on the DCL command line, include the following call in the application:

x := GET_INFO (COMMAND_LINE, "create");

The preceding call returns 1 if /CREATE was specified, 0 otherwise. For more information on GET_INFO, see the DEC Text Processing Utility Manual.

By default, EVE creates a new file if the specified input file does not exist. If you use /NOCREATE and specify an input file that does not exist, EVE aborts the editing session and returns you to the DCL command level. For example, if your default device and directory are DISK$:[USER] and you specify a nonexistent file, NEWFILE.DAT, your command and EVE’s response would be as follows:

• /DEBUG[[=deb ug_source_filename]]
• /NODEBUG (default)

The /DEBUG qualifier determines whether DECTPU loads, compiles, and executes a file implementing a DECTPU debugger. If /DEBUG is specified, DECTPU reads, compiles, and executes the contents of a debugger file before executing the procedure TPU$INIT_PROCEDURE and before executing the command file. For more information on the DECTPU initialization sequence, see Chapter 5.

By default, DECTPU does not load a debugger. If you specify that a debugger is to be loaded but do not supply a file specification, DECTPU loads the file SYS$SHARE:TPU$DEBUG.TPU. For more information on how to use the default DECTPU debugger, see Chapter 5.

To use a debugger file other than the default, use the /DEBUG qualifier and specify the device, directory, and file name of the debugger to be used. If you specify only the file name, DECTPU searches SYS$SHARE for the file. You can define the logical name TPU$DEBUG to specify a file that contains a debugger program. Once you define this logical name, using /DEBUG without specifying a file calls the file specified by TPU$DEBUG.

• /NODISPLAY

To choose the DECwindows or the non-DECwindows version of DECTPU, use the /DISPLAY qualifier on the DCL command line when you invoke DECTPU.

The /DISPLAY qualifier is optional. By default, DECTPU uses /DISPLAY=CHARACTER_CELL, regardless of whether you are running DECTPU on a workstation or a terminal.

If you specify /DISPLAY=CHARACTER_CELL, DECTPU uses its character-cell screen manager, which implements the non-DECwindows version of DECTPU by running in a DECterm terminal emulator or on a physical terminal.

If you specify /DISPLAY=DECWINDOWS, and if the DECwindows environment is available, DECTPU uses the DECwindows screen manager, which creates a DECwindows window in which to run DECTPU.

If you specify /DISPLAY=DECWINDOWS and the DECwindows environment is not available, DECTPU uses its character-cell screen manager to implement the non-DECwindows version of DECTPU.

For more information about the difference between a DECwindows window and a DECTPU window, see Chapter 5.

The /NODISPLAY qualifier causes DECTPU to run without using the screen display and the keyboard functions of a terminal. Use /NODISPLAY in the following cases:

When you use /NODISPLAY, all operations continue as usual, except that no output occurs. The only exception is that information usually put into the message buffer will appear on SYS$OUTPUT if no message buffer is available.

The following command causes DECTPU to edit the file MY_BATCH_F ILE.RNO without using terminal functions such as screen display:

$ EDIT/TPU/NODISPLAY my_batch_file.rno

• /INITIALIZATION[[=filespec]] (default)
• /NOINITIALIZATION

The /INITIALIZATION qualifier determines whether the DECTPU-based application being run executes a file of initialization commands. The application layered on DECTPU is responsible for processing this qualifier.

To determine whether you specified /INITIALIZATION on the DCL command line, use the following call in the application:

x := GET_INFO (COMMAND_LINE, "initialization");

The preceding call returns 1 if /INITIALIZATION was specified, 0 otherwise. To fetch the name of the initialization file specified on the command line, use the following call:

x := GET_INFO (COMMAND_LINE, "initialization_file");

For more information on GET_INFO, see the DEC Text Processing Utility Manual.

If you do not specify any form of /INITIALIZATION on the DCL command line, DECTPU specifies /INITIALIZATION but does not supply a default file specification. The default file specification for /INITIALIZATION is set by the application. VSI recommends that a user-written application define the default file specification of an initialization file by using the following format:

facility$init.facility

For example, the default initialization file for the EVE editor is EVE$INIT.EVE.

In EVE, if you do not specify a device or directory, EVE first checks the current directory. If the specified (or default) initialization file is not there, EVE checks SYS$LOGIN. If EVE finds the specified (or default) initialization file, EVE executes the commands in the file.

For more information on using initialization files with EVE, see Chapter 5 and the Extensible Versatile Editor Reference Manual.

The /INTERFACE qualifier determines the interface or screen display you want (same as /DISPLAY). The default is CHARACTER_CELL. For example, to invoke EVE with the DECwindows interface, use the following command:

$ EDIT/TPU /INTERFACE=DECWINDOWS

Then, if DECwindows is available, DECTPU displays the editing session in a separate window on your workstation screen and enables DECwindows features; for example, the EVE screen layout includes a menu bar and scroll bars. If DECwindows is not available, DECTPU works as if on a character-cell terminal.

• /JOURNAL[[=in put_file.TJL]] (default for EVE)
• /NOJOURNAL (default for DECTPU)

The /JOURNAL qualifier determines whether DECTPU keeps a journal file of an editing session so you can recover the session if it is unexpectedly interrupted. DECTPU offers two forms of journaling:

The application layered on DECTPU is responsible for processing this qualifier. To determine whether you specified /JOURNAL on the DCL command line, use the following call in the application:

x := GET_INFO (COMMAND_LINE, "journal");

The preceding call returns 1 if /JOURNAL was specified, 0 otherwise.

To determine whether buffer-change journaling is turned on for a buffer, use a statement similar to the following:

status := GET_INFO (buffer_name, "journaling");

To determine the name of the keystroke journal file specified on the command line, use the following call:

x := GET_INFO (COMMAND_LINE, "journal_file");

For more information on GET_INFO, see the DEC Text Processing Utility Manual.

In EVE, if you do not specify any form of /JOURNAL or specify /JOURNAL but not a journal file, buffer-change journaling is turned on. The buffer-change journal file’s default file type is .TPU$ JOURNAL.

If you specify /JOURNAL= filename, then EVE also turns on keystroke journaling. The keystroke journal file’s default file type is .TJL.

To prevent EVE from creating either a keystroke or buffer-change journal file for an editing session, use the /NOJOURNAL qualifier. For example, the following command causes EVE to turn off buffer-change journaling when you edit the input file MEMO.TXT:

$ EDIT/TPU/NOJOURNAL memo.txt

If you are developing an application layered on DECTPU, you can use the built-in JOURNAL_OPEN to direct DECTPU to create a keystroke journal file for an editing session. Using JOURNAL_OPEN causes DECTPU to provide a 500-byte buffer in which to journal keystrokes. By default, DECTPU writes the contents of the buffer to the journal file when the buffer is full.

You can use the built-in procedure SET (JOURNALING) to turn on buffer-change journaling, even if you have used /NOJOURNAL to turn it off initially. You can also use SET (JOURNALING) to adjust the journaling frequency. For more information on JOURNAL_OPEN and SET (JOURNALING), see the DEC Text Processing Utility Manual. For more information on buffer-change journaling, see Section 2.4.

Once a keystroke journal file is created, use the /RECOVER qualifier to direct DECTPU to process the commands in the keystroke journal file. For example, the following command causes DECTPU to recover a previous editing session on an input file named MEMO.TXT. Because the journal file has a name different from the input file name, both /JOURNAL and /RECOVER are used. The name of the keystroke journal file is MEMO.TJL:

$ EDIT/TPU/RECOVER/JOURNAL=memo.tjl memo.txt

In buffer-change journaling, to recover the changes made to a specified buffer, use the built-in RECOVER_BUFFER procedure. For more information on RECOVER_BUFFER, see the DEC Text Processing Utility Manual. For more information on how to recover from an interrupted EVE editing session, see the Extensible Versatile Editor Reference Manual.

• /MODIFY (default)
• /NOMODIFY

The /MODIFY qualifier determines whether the first user buffer in an editing session is modifiable. The application layered on DECTPU is responsible for processing /MODIFY.

To determine what form of the /MODIFY qualifier was used on the DCL command line, use the following calls:

• x := GET_INFO (COMMAND_LINE, "modify");
• x := GET_INFO (COMMAND_LINE, "nomodify");

The first statement returns 1 if /MODIFY was explicitly specified on the command line, 0 otherwise. The second statement returns 1 if /NOMODIFY was explicitly specified on the command line, 0 otherwise. If both statements return 0, then the application is expected to determine the default behavior.

For more information on GET_INFO, see the DEC Text Processing Utility Manual.

If you invoke EVE and do not specify /MODIFY, /NOMODIFY, /READ_ONLY, or /NOWRITE, EVE makes the first user buffer of the editing session modifiable. If you specify /NOMODIFY, EVE makes the first user buffer unmodifiable. Regardless of what qualifiers you use on the DCL command line, EVE makes all user buffer s after the first buffer modifiable.

If you do not specify either form of the /MODIFY qualifier, EVE checks whether you have used any form of the /READ_ONLY or /WRITE qualifier. By default, a read-only buffer is unmodifiable and a write buffer is modifiable. However, if you specify /READ_ONLY and /MODIFY or /NOWRITE and /MODIFY, the buffer is modifiable. Similarly, if you specify /WRITE and /NOMODIFY or /NOREAD_ ONLY and /NOMODIFY, the buffer is unmodifiable.

• /OUTPUT[[=in put_file.type]] (default)
• /NOOUTPUT

The /OUTPUT qualifier determines whether the output of your DECTPU session is written to a file. The application layered on DECTPU is responsible for processing this qualifier.

To determine whether you specified /OUTPUT on the DCL command line, use the following call in the application:

x := GET_INFO (COMMAND_LINE, "output");

The preceding call returns 1 if /OUTPUT was specified, 0 otherwise. To fetch the name of the output file specified on the command line, use the following call:

x := GET_INFO (COMMAND_LINE, "output_file");

For more information on GET_INFO, see the DEC Text Processing Utility Manual.

If you do not specify any form of /OUTPUT on the DCL command line, DECTPU specifies /OUTPUT but does not supply a default file specification.

In EVE, when you use /OUTPUT, you can name the file created from the main buffer when you exit from DECTPU. For example, the following command causes DECTPU to read in a file called LETTER.RNO and to write the contents of the main buffer to the file NEWLET.RNO upon exiting from DECTPU:

$ EDIT/TPU/OUTPUT=newlet.rno letter.rno

If you use /OUTPUT= to specify an output file, EVE modifies the buffer even if you do not modify the actual text. In this case, when you exit from EVE, EVE writes the buffer to the output file you specify.

By default, the output file has the same name as the input file, and the version number is one higher than the highest existing version of the input file. You can specify a different name for the output file by using the file specification argument for the /OUTPUT qualifier.

In EVE, specifying /NOOUTPUT causes EVE to suppress creation of an output file for the first buffer of the editing session. Using /NOOUTPUT does not suppress creation of a journal file.

Using /NOOUTPUT, you can develop an application that lets you control the output of a file. For example, an application could be coded so that if you specify /NOOUTPUT on the DCL command line, DECTPU would set the NO_WRITE attribute for the main buffer and suppress creation of an output file for that buffer.

• /READ_ONLY
• /NOREAD_ONLY (default)

The /READ_ONLY qualifier determines whether the application layered on DECTPU creates an output file from the contents of the main buffer if the contents are modified.

The processing of the /READ_ONLY qualifier is interrelated with the processing of the /WRITE qualifier. /READ_ONLY is equivalent to /NOWRITE; /NOREAD_ ONLY is equivalent to /WRITE.

DECTPU signals an error and returns control to DCL if DECTPU encounters either of the following combinations of qualifiers on the DCL command line:

The application layered on DECTPU is responsible for processing this qualifier. To determine whether either the /READ_ONLY or /NOWRITE qualifier was used on the DCL command line, use the following call in an application:

x := GET_INFO (COMMAND_LINE, "read_only");

This statement returns 1 if /READ_ONLY or /NOWRITE was explicitly specified on the command line.

To determine whether either /NOREAD_ONLY or /WRITE was used on the DCL command line, use the following call in an application:

x := GET_INFO (COMMAND_LINE, "write");

This statement returns 1 if /NOREAD_ONLY or /WRITE was explicitly specified on the command line.

If both GET_INFO calls return false, the application is expected to determine the default behavior. For more information on GET_INFO, see the DEC Text Processing Utility Manual.

In EVE, using the /READ_ONLY qualifier is equivalent to using the /NOJOURNAL, /NOMODIFY, and /NOOUTPUT qualifiers. If you specify /READ_ ONLY, DECTPU does not maintain a journal file for your editing session, and the NO_WRITE and NO_MODIFY attributes are set for the main buffer. When a buffer is set to NO_WRITE, the contents of the buffer are not written out upon exit, regardless of whether the session is terminated with the EXIT built-in or the QUIT built-in. For example, if you want to edit a file called MEETING.MEM but not write out the contents when exiting or quitting, use the following command:

$ EDIT/TPU/READ_ONLY meeting.mem

In response to the /NOREAD_ONLY qualifier, EVE writes out the buffer specified on the command line (if the buffer has been modified) when an EXIT command is issued. This is the default behavior.

• /RECOVER
• /NORECOVER (default)

The /RECOVER qualifier determines whether DECTPU reads a keystroke journal file at the start of an editing session to recover edits made during a prior interrupted editing session. For example, the following command causes DECTPU to recover the edits made in a previous EVE editing session on the file NOTES.TXT:

$ EDIT/TPU/RECOVER notes.txt

To determine whether you specified /RECOVER on the DCL command line, use the following call:

x := GET_INFO (COMMAND_LINE, "recover");

The preceding call returns 1 if /RECOVER was specified, 0 otherwise. For more information on GET_INFO, see the DEC Text Processing Utility Manual.

DECTPU uses /RECOVER to recover a keystroke journal file only. In buffer-change journaling, to recover the changes made to a specified buffer, use the RECOVER_BUFFER built-in procedure. For more information on RECOVER_BUFFER, see the DEC Text Processing Utility Manual.

If DECTPU encounters and executes the built-in JOURNAL_OPEN procedure while running a layered application, by default DECTPU opens the journal file for output only. If you specify /RECOVER when invoking DECTPU with a layered application, then when the built-in procedure JOURNAL_OPEN is executed, the keystroke journal file is opened for input and output. DECTPU opens the input file to restore whatever commands it contains. Then DECTPU continues to journal keystrokes for the rest of the editing session or until a statement that contains the built-in JOURNAL_CLOSE is executed.

When you recover an editing session, every file used during the session must be in the same state as it was at the start of the session being recovered. Each terminal characteristic must also be in the same state as it was at the start of the editing session being recovered. If you have changed the width or page length of the terminal, you must change the attribute back to the value it had at the start of the editing session you want to recover. Check especially the following values:

If the journal file has a different name from the input file, you must include both /JOURNAL and /RECOVER with the EDIT/TPU command. For example, if you want to use the keystroke journal file SAVE.T JL to recover the edits you made to a file called LETTER.DAT, enter the following command on the DCL command line:

$ EDIT/TPU/RECOVER/JOURNAL=save.TJL letter.dat

In EVE, you can use /RECOVER to recover either an editing session from a keystroke journal file or a single buffer from a buffer-change journal file. If you specify /JOURNAL= filename, EVE recovers from the specified keystroke journal file. Otherwise, EVE recovers from a buffer-change journal file that corresponds to the input parameter (or the buffer specified on the command line if no input parameter is specified).

For more information on journaling and recovery in EVE, see the Extensible Versatile Editor Reference Manual.

• /SECTION[[=filespec]]
• /NOSECTION
• /SECTION=TPU$SECTION (default)

The /SECTION qualifier determines whether DECTPU loads a section file. A section file is a startup file that contains key definitions and compiled procedures in binary form.

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

You can specify a different section file. The preferred method is to define the logical name TPU$SECTION to point to a section file other than the default file. You can also supply a full file specification for the /SECTION qualifier. For example, if your device is called DISK$USER and your directory is called [SMITH], the following command causes DECTPU to read a section file called VT100INI.TPU$SECTION:

$ EDIT/TPU/SECTION=disk$user:[smith]vt100ini

If you omit the device and directory in the file specification, DECTPU assumes the file is in SYS$SHARE. The section file must be located on the same node on which you are running DECTPU.

To determine whether /SECTION was specified on the DCL command line, use the following call in the application:

x := GET_INFO (COMMAND_LINE, "section");

The preceding call returns 1 if /SECTION was specified, 0 otherwise. To fetch the name of the section file specified on the command line, use the following call:

x := GET_INFO (COMMAND_LINE, "section_file");

For more information on GET_INFO, see the DEC Text Processing Utility Manual.

You must compile the file used as the value for the /SECTION qualifier. To do so, run the source code version of the file through DECTPU and then use the built-in procedure SAVE. This process converts the file to the proper binary form.

For more information on creating and using section files, see Chapter 5. If you specify the /NOSECTION qualifier, DECTPU does not load a section file. Unless you use the /COMMAND qualifier with /NOSECTION, DECTPU has no user interface and no keys are defined. In this state, the only way to exit from DECTPU is to press Ctrl/Y. Typically, you use /NOSECTION when you create your own layered DECTPU application without EVE as a base.

• /START_POSITION=(line,column)
• /START_POSITION=(1,1) (default)

The /START_POSITION qualifier determines where the application layered on DECTPU positions the cursor.

The following built-in procedures return values of the pattern data type:

See the DEC Text Processing Utility Reference Manual for a complete description of these pattern built-in procedures.

You can use the following keywords as the first argument to the SEARCH or SEARCH_QUIETLY built-in procedures. You can also use them to form patterns in expressions that use the pattern operators. See the DEC Text Processing Utility Reference Manual for a complete description of these keywords.

The following are the DECTPU pattern operators:

The pattern operators are equal in DECTPU’s precedence of operators. For more information on the precedence of DECTPU operators, see Chapter 4. Pattern operators associate from left to right. Thus, the following two DECTPU statements are identical:

pat1 := a + b & c | d @ e;
pat1 := (((a + b) & c) | d) @ e;

In addition to the pattern operators, you can use two relational operators, equal ( = ) and not equal (<>), to compare patterns. The following sections discuss the pattern operators.

 p1 := "a" & ANY("012345678");
p2 := "c" & ARB (1);

p1 := LINE_BEGIN + "a";
p2 := "b" + LINE_END;

pat1 := "abc" | "bcd";
pat2 := "bcd" | "abc";
pat3 := "bc" | "bcd";
pat4 := "bcd" | "bc";

pat1 := "a" + ("b" @ var1) + "c" + ("d" @ var1)
        + ("e" | ("x" @ var1)); 

pat1 := notany("abc", 2) + span("123");
pat2 := pat1;

pat1 := LINE_BEGIN + ANY ("abc");
pat2 := LINE_BEGIN + this_pat; 

When you execute a DECTPU statement that contains a pattern expression, DECTPU builds an internal representation of the pattern. DECTPU uses the current contents of any buffer s or ranges used as arguments to pattern built-ins in the pattern expression to build the internal representation. Later changes to those buffer s and ranges do not affect the internal representation for the pattern. DECTPU also uses the current values of any variables used in the pattern expression. Later changes to these variables do not affect the internal representation of the pattern. For example, suppose you wrote the following code fragment:

p1 := "abc";
p2 := "123";
pat := p1 & p2;
p1 := "xyz";
SEARCH (pat, FORWARD);

Given this code fragment, the search matches the string "abc123 " because the variable pat is evaluated as it is built from p1 and p2 during the assignment statement.

The SEARCH and SEARCH_QUIETLY built-ins use the following algorithm to find a match for a pattern:

Anchoring a pattern forces SEARCH or SEARCH_QUIETLY to match the anchored part of the pattern to text starting at the current search position. If the anchored part of a pattern fails to match that text, SEARCH or SEARCH_ QUIETLY stops searching.

Usually, all pattern elements other than the first pattern element of a pattern are anchored. This means that a pattern can match text starting at any point in the searched text but that once it starts matching, each pattern element must match the text immediately following the text that matched the previous pattern element.

To direct DECTPU to stop searching if the characters starting at the editing point do not match the pattern, use the ANCHOR keyword as the first pattern element. For example, the following pattern matches only if the string abc occurs at the editing point:

pat1 := ANCHOR + "abc";

There are two ways to unanchor pattern elements in the midst of a pattern. The easiest is to concatenate or link the UNANCHOR keyword before the pattern element you want to unanchor. The following pattern unanchors the pattern element xyz:

pat1 := "abc" + UNANCHOR + "xyz";

This means that the pattern pat1 matches any text beginning with the characters abc and ending with the characters xyz. It does not matter what or how many characters or line breaks appear between the two sets of characters. Since SEARCH or SEARCH_QUIETLY matches the first xyz it finds, the text between the two sets of characters by definition does not contain the string xyz.

The second way to unanchor a pattern element is to use the special properties of the link operator ( & ). While the concatenation operator always anchors the right pattern element to the left, the link operator does so only if the right pattern element is not a pattern variable. If the link operator’s right pattern element is a pattern variable, the link operator unanchors that pattern element. The pattern pat2 defined by the following assignments matches any sequence of text that begins with the letter a and ends with a digit.

pat1 := ANY ("0123456789");
pat2 := "a" & pat1;

Any amount of text can occur between the a and the digit. Pat2 matches the same text as the following pattern:

pat3 := "a" + UNANCHOR + ANY( "0123456789" );

The link operator unanchors a pattern variable regardless of what the left pattern element is. In particular, the following two patterns match the same text:

pat2 := "a" & pat1;
pat3 := "a" & ANCHOR & pat1;

If you are using pattern variables to form patterns and you wish those variables to be anchored, you have two choices: you can use the concatenation operator, or you can use the ANCHOR keyword as the first element of any pattern the pattern variables reference.

Windows are defined in lines and columns. In EVE, all windows extend the full width of the screen or terminal emulator. In DECTPU, you can set the window width to be narrower than the width of the screen or terminal emulator.

The allowable dimensions of a window often depend on whether the window has a status line, a horizontal scroll bar, or both. A status line occupies the last line of a window. By default, a status line contains information about the buffer and the file associated with the window. You can turn a status line on or off with the SET (STATUS_LINE) built-in procedure.

A horizontal scroll bar is a one-line widget at the bottom of a window that you can use to shift the window to the right or left, controlling what text in the buffer can be seen through the window. You can turn a horizontal scroll bar on or off with the SET (SCROLL_BAR) built-in procedure.

Lines on the screen are counted from 1 to the number of lines on the screen; lines in a window are counted from 1 to the number of lines in the window. Columns on the screen are counted from 1 to the physical width of the screen; columns in a window are counted from 1 to the number of columns in the window.

The minimum length for a window is one line if you do not include a status line or horizontal scroll bar, two lines if you include either a status line or a horizontal scroll bar, and three lines if you include both a status line and scroll bar.

The maximum length of a window is the number of lines on your screen. For example, if your screen is 24 lines long, the maximum size for a single window is 24 lines. On the same size screen, you can have a maximum of 24 visible windows if you do not use status lines or horizontal scroll bars. If you use a status line and a horizontal scroll bar for each window, the maximum number of visible windows is 8.

When you use a device that supports windows (see Chapter 1 for information on terminals that DECTPU supports), you or the section file that initializes your application must create and map windows. In most instances, it is also advisable to map a buffer to the window. To map a buffer to a window, use the MAP built-in procedure. If you do not associate a buffer with a window and map the window to the screen, the only items displayed on the screen are messages that are written to the screen at the cursor position.

The CREATE_WINDOW built-in procedure defines the size and location of a window and specifies whether a status line is to be displayed. CREATE_ WINDOW also adds the window to DECTPU’s internal list of windows available for mapping. At creation, a window is marked as being not visible and not mapped and the following values for the window are calculated and stored:

Later calls to ADJUST_WINDOW may change these values.

When you use the CREATE_WINDOW built-in procedure to create a window, DECTPU saves the numbers of the screen lines that delimit the window in original_top and original_bottom. When you map a window to the screen with the MAP built-in procedure, the window becomes visible on the screen. If it is the only window on the screen, its visible_top and visible_bottom values are the same as its original_top and original_bottom values. You can use SHOW (WINDOWS) to display the original and the visible values or the GET_INFO built-in procedure to retrieve them.

However, if there is already a window on the screen and you map another window over part of it, the values for the previous window’s visible_top, visible_bottom , and visible_length are modified. The value for visible_length of the previous window is different from its original_length until the new window is removed from the screen. As long as the new window is on the screen and does not have another window mapped over it, its original top and bottom are the same as its visible top and bottom.

When you want a window and its associated buffer to be visible on the screen, use the MAP built-in procedure. Mapping a window to the screen has the following effects:

Mapping a window to the screen may have the following side effect s:

When a newly mapped window becomes the current window (the MAP, POSITION, and ADJ UST_WINDOW built-in procedures cause this to happen), the cursor is placed in the current window. In addition to the active cursor position in the current window, there is a marker that designates a cursor position in all other windows. The cursor position in a window other than the current window is the last location of the cursor when it was in the window. By maintaining a cursor position in all windows, DECTPU lets you edit in multiple locations of a single buffer if that buffer is associated with more than one window.

For more information on the cursor position in a window and the POSITION built-in procedure, see the DEC Text Processing Utility Reference Manual.

To remove a window from the screen, you can use either the UNMAP built-in procedure or the DELETE built-in procedure. UNMAP removes a window from the screen. However, the window is still in DECTPU’s internal list of windows. It is available to be remapped to the screen without being re-created. DELETE removes a window from the screen and also removes it from DECTPU’s list of windows. It is then no longer available for future mapping to the screen.

Unmapping or deleting a window has the following effects:

The screen manager is the part of DECTPU that controls the display of data on the screen. You can manipulate data without having it appear on a terminal screen (see Chapter 5). However, if you use the DECTPU window capability to make your edits visible, the screen manager controls the screen.

In the main control loop of DECTPU, the screen manager is not called to perform its duties until all commands bound to the last key pressed have finished executing and all input in the type-ahead buffer has been processed. Upon completion of all the commands, the screen manager updates every window to reflect the current state of the part of the buffer that is visible in the window. If you want to make the screen reflect changes to the buffer prior to the end of a procedure, use the UPDATE built-in procedure to force the updating of the window. Using UPDATE is recommended with built-in procedures such as CURRENT_COLUMN that query DECTPU for the current cursor position. To ensure that the cursor position returned is the correct location (up to the point of the most recently issued command), use UPDATE before using CURRENT_ COLUMN or CURRENT_ROW.

There are two DECTPU built-in procedures that return information about windows:

GET_INFO and SHOW (WINDOW). GET_INFO returns information that you can store in a variable. You can get information about the visible and original values of windows, as well as about other attributes that you have set up for your window environment. See GET_ INFO in the DEC Text Processing Utility Reference Manual.

SHOW (WINDOW) or SHOW (WINDOWS) puts information about windows in the SHOW_BUFFER. If you use an editor that has an INFO_WINDOW, you can display the SHOW_BUFFER information in the INFO_WINDOW.

DECTPU supports windows only for ANSI character-cell terminals. Noncharacter-cell terminals do not support windows and are considered “unsupported devices”.

If you are using an unsupported device, you must use the /NODISPLAY qualifier when you invoke DECTPU. /NODISPLAY informs DECTPU that you do not expect the device from which you are issuing DECTPU commands to support screen-oriented editing. If one of the previous conditions exists and you do not specify the /NODISPLAY qualifier, DECTPU exits with an error condition.

You are using an unsupported device if logical name SYS$INPUT points to an unsupported device, such as a character-cell terminal. Appendix B contains more information about DECTPU terminal support. Chapter 2 contains more information on the /NODISPLAY qualifier.

The DEC Multinational Character Set characters from 128 to 255 are extended control characters and supplemental multinational characters. Table 4.2 shows the categories into which you can group the characters.

For a complete list of characters in the DEC Multinational Character Set, see the OpenVMS documentation.

The ISO Latin1 Character Set characters from 128 to 255 are extended control characters and Latin1 supplemental multinational characters. Table 4.3 shows the groups into which you can categorize characters.

For a complete list of the ISO Latin1 Character Set, see the OpenVMS documentation.

If you specify the GENERAL keyword with the /CHARACTER_SET qualifier or the -C option, DECTPU is unable to set a character set for 8-bit characters. The character set used and how DECTPU displays 8-bit characters are the same as before you started DECTPU. For this reason, the characters from 128 to 255 in the General Character Sets are not specific to any character set.

There are two ways to enter control characters in DECTPU:

Certain symbols have special meanings in DECTPU. You can use them as statement delimiters, operators, or other syntactic elements. Table 4.4 lists the DECTPU symbols and their functions.

You can use any of the arithmetic operators (+, –, *, / ) with integer data types to form arithmetic expressions. DECTPU performs only integer arithmetic. The following are examples of valid DECTPU expressions:

12 + 4             ! adds two integers

"abc" + "def"      ! concatenates two strings 

The following is not a valid DECTPU expression because it mixes data types:

"abc" + 12         ! you cannot mix data types 

When performing integer division, DECTPU truncates the remainder; it does not round. The following examples show the results of division operations:

Expression         Result

 39 / 10              3
 -39 / 10            -3

A relational expression tests the relationship between items of the same data type and returns an integer result. If the relationship is true, the result is integer 1; if the relationship is false, the result is integer 0.

Use the following relational operators with any of the DECTPU data types:

For example, the following code fragment tests whether string1 starts with a letter that occurs later in the alphabet than the starting letter of string2:

string1 := "gastropod";
string2 := "arachnid";
IF string1 > string2
THEN
    MESSAGE ("Out of alphabetical order ");
ENDIF;

Use the following relational operators for comparisons of integers, strings, or markers:

When used with markers, these operators test whether one marker is closer to (or farther from) the top of the buffer than another marker. (If markers are in different buffer s, they will return as false.) For example, the procedure in Example 4.3 uses relational operators to determine which half of the buffer the cursor is located in.

PROCEDURE which_half

LOCAL  number_lines,
       saved_mark;

saved_mark := MARK (FREE_CURSOR);
POSITION (BEGINNING_OF (CURRENT_BUFFER));
number_lines := GET_INFO (current_buffer, "record_count");
IF number_lines = 0
        
THEN
    MESSAGE ("The current buffer is empty");
ELSE
    MOVE_VERTICAL (number_lines/2);
      IF MARK (FREE_CURSOR) = saved_mark
      THEN
          MESSAGE ("You are at the middle of the buffer");
      ELSE
          IF MARK (FREE_CURSOR) < saved_mark
          THEN
            MESSAGE ("You are in the second half of the buffer");
          ELSE
            MESSAGE ("You are in the first half of the buffer");
          ENDIF;
      ENDIF;

ENDIF;

ENDPROCEDURE;

A pattern expression consists of the pattern operators (+, &, | , @) combined with string constants, string variables, pattern variables, pattern procedures, pattern keywords, or parentheses. The following are valid pattern expressions:

pat1 := LINE_BEGIN + SPAN ("0123456789") + ANY ("abc"); 

pat2 := LINE_END + ("end"|"begin"); 

pat3 := SCAN (’;"!’) + (NOTANY ("’") & LINE_END); 

See Chapter 3 for more information on pattern expressions.

DECTPU performs bitwise logical operations on Boolean expressions. This means that the logical operation is performed on the individual bits of the operands to produce the individual bits of the result. In the following example, the value of user_variable is set to 3.

user_variable := 3 AND 7;

As another example, if user_var were %X7777 (30583), then you would use the following statement to set user_var to %x0077 (119):

user_var := user_var AND %XFF

A true value in DECTPU is any odd integer; a false value is any even integer. Use the logical operators (AND, NOT, OR, XOR) to combine one or more expressions. DECTPU evaluates Boolean expressions enclosed in parentheses before other

elements. The following example shows the use of parentheses to ensure that the Boolean expression is evaluated correctly:

IF (X = 12) AND (y <> 40)
THEN
  .
  .
  .
ENDIF;

Keywords are a DECTPU data type. They are reserved words that have special meaning to the compiler. You can redefine DECTPU keywords only in local declarations (local constants, local variables, and parameters in a parameter list). If you give a local constant, local variable, or parameter the same name as that of a keyword, the compiler issues a message notifying you that the local declaration or parameter temporarily supersedes the keyword. In such a circumstance, the keyword is said to be occluded. See Chapter 3 and the DEC Text Processing Utility Reference Manual for more information on keywords.

The DECTPU language has many built-in procedures that perform functions such as screen management, key definition, text manipulation, and program execution. You can redefine DECTPU built-in procedures only in local declarations (local constants, local variables, and parameters in a parameter list). If you give a local constant, local variable, or parameter the same name as that of a built-in procedure, the compiler issues a message notifying you that the local declaration or parameter temporarily supersedes the built-in. In such a circumstance, the built-in is said to be occluded. See the DEC Text Processing Utility Reference Manual for a complete description of the DECTPU built-in procedures.

The following is a list of predefined global constants that DECTPU sets up. You cannot redefine these constants.

A DECTPU program can consist of a sequence of declarations and statements. These declarations and statements control the action performed in a procedure or a program. The following reserved words are the language elements that when combined properly make up the declarations and statements of DECTPU:

GLOBAL, UNIVERSAL, BEGIN, and END are words reserved for future expansion of the DECTPU language.

The DECTPU declarations and statements are reserved words that you cannot define. Any attempt to redefine these words results in a compilation error.

MODULE module-name IDENT string-literal ⟦declarations⟧ ⟦ON_ERROR ... 
ENDON_ERROR⟧ statement_1; . . . statement_ n; ENDMODULE

MODULE user_mod IDENT "v1.0"

PROCEDURE user_hello
    MESSAGE ("Hello");
ENDPROCEDURE;

ON_ERROR
    MESSAGE ("Good-bye");
END_ON_ERROR;

user_hello;
ENDMODULE

PROCEDURE procedure-name ⟦ (parameter-list) ⟧ ⟦local-declarations⟧
⟦ON_ERROR ... ENDON_ERROR⟧ statement_1; statement_2; . . . statement_ n;
ENDPROCEDURE;

PROCEDURE version

   MESSAGE ("This is Version 1-020");

ENDPROCEDURE;

PROCEDURE user_input_output (a, b)

   a :=a+ 5;
   b := a;
ENDPROCEDURE;

PROCEDURE proc-name ⟦ ( ⟦req-p aram ⟦...⟧ ⟧ ⟦;op t-param ⟦...⟧ ⟧ ) ⟧ . . . 
ENDPROCEDURE;

!This procedure adds two integers. The parameters, int1 and int2,
!are replaced by the actual values that you supply.
!The result of the addition is written to the message area.

PROCEDURE ADD (int1, int2)

   MESSAGE (STR (int1 + int2));

ENDPROCEDURE;

ADD (5, 6);

CONSTANT
    user_warning       := 0,        ! Warning severity code
    user_success       := 1,        ! Success severity code
    user_error         := 2,        ! Error severity code
    user_informational := 3,        ! Informational severity code
    user_fatal         := 4;        ! Fatal severity code
!
! Output a message with fatal/error/warning flash.
!
PROCEDURE user_message (the_text; the_severity)

LOCAL flash_it;
!
! Only flash warning, error, or fatal messages.
!
CASE the_severity FROM user_warning TO user_fatal
    [user_warning, user_error, user_fatal] : flash_it := TRUE;

    [user_success, user_informational] : flash_it := FALSE;

    [OUTRANGE] : flash_it := FALSE;

ENDCASE;
!
! Output the message - flash it, if appropriate.
!
MESSAGE (the_text);
IF flash_it
THEN
    SLEEP ("0 00:00:00.3");
    MESSAGE ("");
    SLEEP ("0 00:00:00.3");
    MESSAGE (the_text);
ENDIF;

ENDPROCEDURE;

partial_1 := param_1;
partial_2 := param_2;
my_procedure (partial_1, partial_2);

PROCEDURE user_on_end_of_line !test if at eol, return true or false

IF CURRENT_OFFSET = LENGTH (CURRENT_LINE)    ! we are on eol
THEN
    user_on_end_of_line := 1                   ! return true
ELSE
    user_on_end_of_line := 0                   ! return false
ENDIF;

ENDPROCEDURE;

PROCEDURE user_nested_procedure
   .
   .
   .
IF user_on_end_of_line = 1 ! at the eol mark
THEN
    MESSAGE ("Cursor is at the end of the line")
ELSE
    MESSAGE ("Cursor is not at the end of the line")
ENDIF;
   .
   .
   .
ENDPROCEDURE;

PROCEDURE user_reverse
LOCAL temp_string;

temp_string := READ_LINE("input>");

                          ! Read a response

IF temp_string <> " "     ! Quit if nothing entered
                          ! but the RETURN key.
THEN
    user_reverse          ! Call user_reverse recursively
ELSE
    RETURN                ! All done, go to display lines
ENDIF;
MESSAGE (temp_string);    ! Display lines typed in reverse order
                          ! in the message window
ENDPROCEDURE;

LOCAL variable-name ⟦,...⟧;

PROCEDURE test
   LOCAL X;
   EXECUTE ("X := 3");
   MOVE_VERTICAL (X);
ENDPROCEDURE;

CONSTANT constant-name := compile-time-constant-expression ⟦,...⟧; 

identifier := expression;

X := "abc";

LOOP statement_1; statement_2; . . . EXITIF expression; statement_ n;
ENDLOOP;

EXITIF expression;

LOOP
   EXITIF CURRENT_OFFSET = 0;
   temp_string := CURRENT_CHARACTER;
   EXITIF (temp_string <> " ") AND
          (temp_string <> ASCII(9));
   MOVE_HORIZONTAL (-1);
   temp_length := temp_length + 1;
ENDLOOP;

IF expression THEN statement_1; . . . statement_ n ⟦ELSE alternate-statement_ 1;
. . . alternate-statement_ n;⟧ ENDIF;

PROCEDURE set_direct

MESSAGE ("Press PF3 or PF4 to indicate direction");
temp_char := READ_KEY;
IF temp_char = KP5
THEN
    SET (REVERSE, CURRENT_BUFFER);
ELSE
    IF temp_char = KP4
    THEN
        SET (FORWARD, CURRENT_BUFFER);
    ENDIF;
ENDIF;

ENDPROCEDURE;

relation_1 := clause_1;
relation_2 := clause_2;
IF relation_1 AND relation_2
THEN
  .
  .
  .
ENDIF;

CASE case-selector ⟦FROM
lower-constant-expr, TO upper-constant-expr⟧
     [constant-expr_1 ⟦,...⟧] : statement ⟦,...⟧;
     [constant-expr_2 ⟦,...⟧] : statement ⟦,...⟧;
          .
          .
          .

     [constant-expr_n ⟦,...⟧] : statement ⟦,...⟧;

    ⟦[INRANGE] : statement ⟦,...⟧ ;⟧

    ⟦[OUTRANGE] : statement ⟦,...⟧ ;⟧
ENDCASE;

PROCEDURE grades

answers := READ_LINE ("Enter number of correct answers:",5);
answers := INT (answers);

CASE answers FROM 0 TO 10
                   [10] : score := "A+";
                    [9] : score := "A";
                    [8] : score := "B";
                    [7] : score := "C";
                    [6] : score := "D";
          [0,1,2,3,4,5] : score := "F";
             [OUTRANGE] : score := "Invalid entry.";
ENDCASE;

MESSAGE (score);

ENDPROCEDURE;

ON_ERROR statement_1; statement_2; . . . statement_n; ENDON_ERROR;

!
! Gold 7 emulation (command line processing)
!
PROCEDURE command_line

LOCAL
   line_read, X;

ON_ERROR
    MESSAGE ("Unrecognized command: " + line_read);
    RETURN;
ENDON_ERROR;
!
! Get the command(s) to execute
!
line_read := READ_LINE ("DECTPU Statement: "); ! get line from user
!
! compile them

!
IF line_read <> ""
THEN
    X := COMPILE (line_read);
ELSE
    RETURN
ENDIF;
!
! execute
!
IF X <>0
THEN
    EXECUTE (X);
ENDIF;

ENDPROCEDURE;

 ON_ERROR [con dition_1]: statement_1;... [con dition_2]: statement_2;... . . .
[condition_n]: statement_ n; ENDON_ERROR;

! This error handler uses [OTHERWISE] alone as a shortcut.
ON_ERROR [OTHERWISE] : ;
ENDON_ERROR

! This error handler has the same effect as using
! [OTHERWISE] alone.

ON_ERROR
[OTHERWISE] :
   LEARN_ABORT;
   RETURN (FALSE);
ENDON_ERROR;

PROCEDURE eve$learn_abort

ON_ERROR
    [TPU$_CONTROLC]:
       MESSAGE (ERROR_TEXT);
       RETURN (LEARN_ABORT);
ENDON_ERROR;

IF LEARN_ABORT
THEN
    eve$message (EVE$_LEARNABORT);
    RETURN (TRUE);
ELSE
    RETURN (FALSE);
ENDIF;

ENDPROCEDURE;

RETURN expression;

PROCEDURE user_get_shift_key

LOCAL key_to_shift; ! Keyword for key pressed after shift key

SET (SHIFT_KEY, LAST_KEY);
key_to_shift := KEY_NAME (READ_KEY, SHIFT_KEY);
RETURN key_to_shift;

ENDPROCEDURE;

PROCEDURE user_at_end_of_line

! This procedure returns a 1 (true) if user is at the end of a
! line, or a 0 (false) if the current character is not at the
! end of a line

ON_ERROR
! Suppress warning message
   RETURN (1);
ENDON_ERROR;

IF CURRENT_OFFSET = LENGTH (CURRENT_LINE)
THEN
    RETURN (1);
ELSE
    RETURN (0);
ENDIF;

ENDPROCEDURE;

! Attach to the parent process. Used when EVE is spawned
! from DCL and run in a subprocess ("kept DECTPU"). The
! ATTACH command can be used for more flexible process control.

PROCEDURE eve_attach
ON_ERROR
    IF ERROR = TPU$_NOPARENT
    THEN
        MESSAGE ("Not running DECTPU in a subprocess");
        RETURN;
    ENDIF;
ENDON_ERROR;

ATTACH;

ENDPROCEDURE; 

ABORT

ON_ERROR
   MESSAGE ("Aborting procedure because of error.");
   ABORT;
ENDON_ERROR; 

This section describes the following DECTPU language declarations:

EQUIVALENCE synonym_name1 = real_name1, synonym_name2 = real_name2, ...;

LOCAL variable-name ⟦,...⟧;

MODULE mmm IDENT "mmm"

PROCEDURE bat;                  ! Declare procedure "bat" in module "mmm"
LOCAL
    X; ! "X" is local to procedure "bat"

    X := "Within procedure bat, within module mmm";
MESSAGE (X);

ENDPROCEDURE; ! End procedure "bat"

LOCAL
        X;                      ! "X" is local to
                                ! procedure "mmm_module_init"

X := "Starting or ending the module init code";
MESSAGE (X);
bat;
MESSAGE (X);

ENDMODULE;              ! End module "mmm"

PROCEDURE bar           ! Declare procedure "bar"

LOCAL
        X;                      ! "X" is local to procedure "bar"

X := "In procedure bar, which is outside all modules";
MESSAGE (X);

ENDPROCEDURE;           ! End procedure "bar"

LOCAL
        X;                      ! "X" is local to the unbound code...

X := "Starting or ending the unbound, non-init code";
MESSAGE (X);
mmm_module_init;
bat;
bar;
MESSAGE (X);
EXIT;

$
EDIT/TPU/NOSECTION/NOINITIALIZE/NODISPLAY/COMMAND=temp.tpu
Starting or ending the unbound, non-init code
Starting or ending the module init code
Within procedure bat, within module mmm
Starting or ending the module init code
Within procedure bat, within module mmm
In procedure bar, which is outside all modules
Starting or ending the unbound, non-init code

CONSTANT constant-name := compile-time-constant-expression ⟦,...⟧

VARIABLE variable-name ⟦,...⟧;

The following lexical keywords control what code is compiled under different conditions:

You use conditional compilation lexical keywords in a manner similar to ordinary IF/THEN/ELSE/ENDIF statements. The syntax is as follows:

%IFDEF variable_or_proc_name %THEN ... [%ELSE ...] %ENDIF

or

%IF boolean_expression %THEN ... [%ELSE ...] %ENDIF

If you use the %IFDEF structure, specify variable_or_proc_name as the name of a DECTPU procedure or variable. IFDEF is a statement that says ‘‘if a variable or procedure with this name is defined.’’ If the name is defined, the compiler compiles the code marked by %THEN. If the name is not defined, the compiler compiles the code marked by %ELSE.

If you use the %IF structure, specify boolean_expression as either a numeric constant or a defined global variable whose value is an integer. Any odd value is true and any even value is false. If the variable or constant contains a value that is odd, the compiler compiles the code marked by %THEN. If the variable or constant contains a value that is even, the compiler compiles the code marked by %ELSE.

You do not have to put conditional compilation lexical keywords at the beginning of a line. You can nest conditional statements to a depth of 2**32-1. For example:

ON_ERROR
    [TPU$_CREATEFAIL]:
%IF eve$x_option_decwindows
%THEN
      IF eve$x_decwindows_active
      THEN
          eve$popup_message (MESSAGE_TEXT (EVE$_CANTCREADCL, 1));
      ELSE
          eve$message (EVE$_CANTCREADCL);
      ENDIF;
%ELSE
      eve$message (EVE$_CANTCREADCL);
%ENDIF
      eve$learn_abort;
      RETURN (FALSE);
   [OTHERWISE]:
ENDON_ERROR;

This ON_ERROR procedure determines whether a pop-up message widget or a simple message is used, depending on whether the code is being compiled by a DECwindows version of DECTPU.

You can specify constants with binary, octal, hexadecimal, and decimal radices.

To specify a numeric constant in binary, precede the number with %B. The number can consist only of the digits 0 and 1.

To specify a numeric constant in octal, precede the number with %O. The number can consist only of the digits 0 through 7.

To specify a numeric constant in hexadecimal, precede the number with %X. The number can consist of digits 0–9 and A–F.

There is no radix specifier for decimal. Any numeric constant without an explicit radix specifier is assumed to be decimal. The radix specifier may be in uppercase or lowercase.

The following are examples of correct numeric constants:

!
! Many different ways of saying the same thing.
!
CONSTANT binary_constant := %b11111;
CONSTANT octal_constant := %o37;
CONSTANT decimal_constant := 31;
CONSTANT hex_constant := %x1f;
!
! Compile time expressions work, too.
!
CONSTANT negative_value := -%x1f;
CONSTANT strange_zero := hex_constant - %x1f;

Invalid constructs for numeric constants return the error level message TPU$_ UNKLEXICAL, "Unknown lexical element" during compilation. The following examples are not valid:

constant bad_binary := %b123;      ! only 0’s and 1’s are legal.
constant bad_hex := %x10abg;       ! ’g’ is illegal digit.
constant not_a_radix := %z0123;    ! No such radix.

The following statement is an example of a simple program:

 SHOW (SUMMARY); 

The preceding statement, entered after the appropriate prompt from your editor, causes DECTPU to execute the program associated with the SHOW (SUMMARY) statement. If you use EVE with a user-written command file, your screen may display text similar to Example 5.1.

DECTPU V3.1  1993-08-17 08:37

Journal file:

Section file name: EVE$SECTION  Ident: V3.1  Date: 17-AUG-1993 08:49
   Activated from: TPU$SECTION
       Created by: DECTPU V3.1  1993-08-17 08:37

Extension: SCREEN_UPDATER  Ident: DECTPU V3.1  1993-08-17 08:37

Timer Message:         working

 24 System buffers and 1 User buffer

When writing complex DECTPU programs, avoid the following practices:

These practices, if carried to extremes, can cause the parser stack to overflow.

The DECTPU parser currently allows a maximum stack depth of 1000 syntax tree nodes. When the parser first encounters a DECTPU statement, the parser assigns each token in the statement to a syntax tree node. For example, the statement “a := 1” contains three tokens, each of which occupies a syntax tree node. After the parser parses this statement, only the assignment statement remains on the stack of nodes. The a and the 1 are subtrees to the assignment syntax tree node.

The most common cause of stack overflow, which is signaled by the status TPU$_ STACKOVER, is creating one or more large procedures whose statements occu py too many syntax tree nodes. To make your program manageable by the parser, break the large procedures into smaller ones.

Other possible reasons for a TPU$_STACKOVER con dition are that you have too many statements that are not in procedures, or that you have too many small procedures. If you have too many small procedures, you must either consolidate them or break them into separate files.

To see an example of a complex DECTPU program, examine the source files that implement EVE. The EVE source code files are located at SYS$ EXAMPLE S:EVE$*.*. These files contain many procedure declarations and executable statements that specify EVE’s screen layout and display. These files also contain key definitions that specify which editing operations are performed when you press certain keys on the keyboard. You can examine these files to learn the programming techniques that were used to create EVE.

See Section 5.6 for information on using a command file or section file to create or customize an application layered on DECTPU. See theDEC Text Processing Utility Reference Manual for information on using the EVE$BUILD module to layer applications on top of EVE.

The rules for writing DECTPU programs are simple. You must use a semicolon to separate each executable statement from other statements. In a program, you must place all procedure declarations before any executable statements that are not part of a procedure declaration. For information on DECTPU data types, see Chapter 3. For information on DECTPU language elements, see Chapter 4. Example 5.2 shows the correct syntax for a DECTPU program.

PROCEDURE
    .
    . 
   . 
ENDPROCEDURE

PROCEDURE;
    .
    .
    .
ENDPROCEDURE;
    .
    .
    .
PROCEDURE
    .
    .
    .
ENDPROCEDURE;

statement 1;
statement 2;
    .
    .
    .
statement n;

A variety of syntactically correct DECTPU programs is shown in Example 5.3.

! Program 1
! This program consists of a single DECTPU built-in procedure.
   SHOW (KEYWORDS);

! Program 2
! This program consists of an assignment statement that
! gives a value to the variable video_attribute

   video_attribute := UNDERLINE;

! Program 3
! This program consists of the DECTPU LOOP statement (with
! a condition for exiting) and the DECTPU built-in procedure ERASE_LINE.
  x := 0; LOOP x :=x+1; EXITIF x > 100; ERASE_LINE; ENDLOOP;

! Program 4
! This program consists of a single procedure that makes
! DECTPU quit the editing session.

   PROCEDURE user_quit
      QUIT;         ! do DECTPU quit operation
   ENDPROCEDURE;

! Program 5
! This program is a collection of procedures that
! makes DECTPU accept "e", "ex", or "exi" as
! the command for a DECTPU exit operation.

   PROCEDURE e
      EXIT;         ! do DECTPU exit operation
   ENDPROCEDURE;

   PROCEDURE ex
      EXIT; ENDPROCEDURE;

   PROCEDURE exi
      EXIT;
   ENDPROCEDURE;

With DECwindows DECTPU, you can create widgets from within DECTPU programs by using the CREATE_WIDGET built-in procedure. For more information on widgets, see the OpenVMS overview documentation.

With the CREATE_WIDGET built-in, you can create the following widgets in DECTPU:

In DECwindows, at most one of the applications on the screen can have the input focus; that is, only one application can accept user input from the keyboard. For more information about the input focus, see the Motif documentation.

DECwindows DECTPU automatically grabs the input focus whenever you cause an unmodified M1DOWN event (that is, an event not modified by Shift, Ctrl, or other modifying key) while the pointer cursor is in either of the following locations:

DECwindows assigns input focus to DECTPU only if and when it is possible to do so. To make sure that DECwindows can assign input focus, your application should use the GET_INFO (SCREEN, “input_focus”) built-in procedure. If assignment of input focus to DECTPU is enabled, DECTPU can receive input focus in the following circumstances:

In the Motif environment, DECTPU supports both implicit and explicit focus policies.

VSI recommends that you use only a DECwindows section file with DECwindows DECTPU. (All versions of EVE shipped with VSI OpenVMS Version 5.1 or higher are compatible with DECwindows and are suitable for building DECwindows section files, as well as DECTPU Version 3.0 or higher.) However, if you do not follow this recommendation, DECTPU’s automatic grabbing of the input focus enables your layered application to interact with other DECwindows applications.

Global selection in DECwindows is a means of preserving information selected by you so your selection, or data about your selection, can pass between DECwindows applications. Each DECwindows application can own one or more global selections.

This section presents background information on the DECwindows concept of callbacks and explains how DECwindows DECTPU implements this concept.

With DECwindows, you can specify a closure value for a widget. (DECwindows documentation refers to closures as tags.) DECwindows does not define what a closure value is; a closure is simply a value that DECwindows understands how to recognize and manipulate so that a DECwindows application programmer can use the value if needed in the application. For general information about using closures in DECwindows, see the OpenVMS documentation overview.

When a widget calls back to the DECwindows application, the callback parameters include the closure value assigned to the widget. DECwindows allows the application to define the significance and possible values of the closure.

DECTPU supports closure values of type string and integer. Closure values are optional for widgets used by applications layered on DECTPU. If you do not specify a closure value, the GET_INFO (WIDGET, "callback_parameters", array) built-in procedure returns unspecified in the "closure" array element. If you create a widget without using a UIL file, the GET_INFO (WIDGET, "callback_ parameters ", array) built-in procedure returns the closure you specified as a parameter to CREATE_WIDGET. If you create a widget by using a UIL file, the GET_INFO (WIDGET, "callback_parameters ", array) built-in procedure returns the closure value (if any) defined in the X Resource Manager. If none is defined, the built-in returns unspecified.

DECTPU leaves it to the layered application to use the closure in any way the application programmer wishes. DECTPU passes through to the application any closure value received as part of a callback.

DECwindows EVE provides an example of how an application can use closure values. DECwindows EVE assigns a unique closure value to every widget instance that can be created during an EVE editing session. Each closure value corresponds to something that EVE must do in response to the activation of that particular widget. When an event causes DECTPU to execute EVE’s main callback program, the GET_INFO (WIDGET, "callback_parameters", array) built-in procedure returns the widget activated, the reason code (the reason the widget is calling back), and the closure associated with the particular widget instance.

EVE’s main callback program contains an array that is indexed with values identical to the widget closure values. Each array element contains a pointer to the EVE code to be executed in response to the corresponding widget’s callback. EVE’s callback program uses the closure value to locate the appropriate array index so the correct EVE routine can be executed in response to the callback.

If your layered application does not use EVE’s callback program, then its callback program or learn sequence must have a mechanism for determining which widget is calling back and which application code should be executed as a result.

This section discusses techniques for specifying values for widget resources.

line_feed := ASCII (10);
resource_array {"items" + line_feed + "itemsCount"}:=list_array;

GET_INFO (widget, "WIDGET_INFO", array)

items<line-feed>items_count

"items" + ASCII(10) + "itemsCount"

This section is intended for programmers who are extending EVE or layering an application on EVE.

There are four possible types of selection:

EVE can use only one type of selection at a time. The ways in which these selections differ are explained in the following sections.

EVE has a routine called EVE$SELECTION that returns the current selection, regardless of whether the selection is dynamic, static, formed from a found range, or the primary global selection. You can use the SELECT_RANGE built-in procedure to get the current selection if the selection is a dynamic selection. However, VSI recommends that you use EVE$SELECTION to get the current selection because this routine returns the current selection regardless of how it was created. To see how the EVE$SELECTION routine works and what parameters it takes, see the code for this routine in SYS$ EXAMPLE S:EVE$CORE.TPU.

r1 := EVE$SELECTION (TRUE, TRUE, TRUE, TRUE, FALSE)

You can compile a simple DECTPU program by entering it on the EVE command line. For example, if you use the TPU command and then enter the SHOW (SUMMARY) statement, DECTPU compiles and executes the program associated with the SHOW (SUMMARY) statement.

DECTPU programs are usually compiled by entering DECTPU procedures and statements in a buffer and then compiling the buffer. If you are using EVE, you can enter the SHOW (VARIABLE S) command in a buffer and compile the buffer by using the TPU command and entering the following statement after the prompt:

TPU Statement: COMPILE (CURRENT_BUFFER);

The program associated with SHOW (VARIABLE S) is not executed until you enter the following statement:

TPU Statement: EXECUTE (CURRENT_BUFFER);

If you use a buffer, a range, or a string as the parameter for the EXECUTE built-in procedure, DECTPU first compiles and then executes the buffer, range, or string. See the description of EXECUTE in the DEC Text Processing Utility Reference Manual.

The COMPILE built-in procedure optionally returns a program data type. If you want to use the program that you are compiling later in your session, you can assign the program that is returned to a variable. The following example shows how to make this assignment:

new_program := COMPILE (CURRENT_BUFFER);

If no error messages are issued while you compile the current buffer, you can then execute the program new_program with the following statement:

EXECUTE (new_program);

You can use the COMPILE built-in procedure to compile certain parts of a buffer rather than a whole buffer. To do so, create a range that includes the statements within the buffer that you want compiled, and then specify the range as the parameter for COMPILE.

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:

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:

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

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.

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.

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

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.

$ DIR SYS$EXAMPLES:EVE$*.TPU

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

PROCEDURE tpu$local_init
     .
     .
     . ENDPROCEDURE;

PROCEDURE vt100_keys
    .
    .
    .
ENDPROCEDURE;

vt100_keys;  !Call the procedure that defines the keys

SAVE ("vt100ini.tpusection");

QUIT;

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

! 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

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

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

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

TPU Statement: EXECUTE (CURRENT_BUFFER);

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

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:

$ EDIT/TPU/COMMAND ⟦= filespec⟧

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.

PROCEDURE goto_text_marker

   LOCAL text_marker_pattern,
         text_marker_range;

   text_marker_pattern := ’%(/*’ + MATCH (’*/)%’);
   text_marker_range :=  SEARCH_QUIETLY (text_marker_pattern,
                             GET_INFO (CURRENT_BUFFER, "direction"));
   IF text_marker_range <> 0
   THEN
       POSITION (text_marker_range);
   ELSE
       MESSAGE ("Text_marker not found");
   ENDIF;

   RETURN text_marker_range;

ENDPROCEDURE;

If you name the file that contain s this procedure TEXT_MARKERS.TPU, you can invoke DECTPU with EVE and your command file with the following command:

$ EDIT/TPU/COMMAND=device:[directory]text_markers.tpu

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

SET LEFT MARGIN 5
SET RIGHT MARGIN 60
OVERSTRIKE MODE
DEFINE KEY=gold/q QUIT
SET KEYPAD EDT

$ EDIT/TPU/INITIALIZATION=MY_INIT.EVE

Command: @MYEVE

Command: SHOW DEFAULTS BUFFER

EVE V3.1 1993-08-17 08:47
Information about buffer $DEFAULTS$

    Not modified               Left margin set to: 1
    Mode: Insert               Right margin set to: 79
    Paragraph indent: none     WPS word wrap indent: none
    Read-only                  Unmodifiable
    Direction: Forward
    Max lines: no limit
Tab stops set every 8 columns.
Word wrap: 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:

$ EDIT/TPU/DEBUG=MY_DEBUGGER.TPU MIGHT_BE_BUGGY.TPU

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

$ EDIT/TPU/DEBUG

Debug: SET BREAKPOINT user_fum

$ EDIT/TPU/NOSECTION/COMMAND=MY_COMMANDS.TPU/DEBUG

$ EDIT/TPU/DEBUG USER_APPLICATION.TPU

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:

Command: TPU DEBUGON

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:

Command: TPU user_fum

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.