Updated: 11 December 1998

Guide to the DEC Text Processing Utility

• /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 Reference 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 buffers 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.

2.6.10 /OUTPUT

• /OUTPUT[[=input_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 Reference 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.

2.6.11 /READ_ONLY

• /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:

• /READ_ONLY and /WRITE
• /NOREAD_ONLY and /NO_WRITE

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

2.6.12 /RECOVER

• /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 Reference 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 Reference Manual.

If DECTPU encounters and executes the built-in procedure JOURNAL_OPEN 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:

• Device type
• Edit mode
• 8-bit
• Page length
• Width

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

2.6.13 /SECTION

• /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 Reference 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.

2.6.14 /START_POSITION

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

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

A data type is a group of elements that "belong together"; the elements are all formed in the same way and are treated consistently. The data type of a variable determines the operations that can be performed on it. The DECTPU data types are represented by the following keywords:

• ARRAY
• BUFFER
• INTEGER
• KEYWORD
• LEARN
• MARKER
• PATTERN
• PROCESS
• PROGRAM
• RANGE
• STRING
• UNSPECIFIED
• WIDGET
• WINDOW

You use data types to interpret the contents of a variable. Unlike many programming languages, DECTPU permits any variable to have any type of data as a value. DECTPU has no declaration statement to restrict the type of data that you can assign to a variable. DECTPU variables take on a data type when they are placed on the left-hand side of an assignment statement. The right-hand side of the assignment statement determines the data type of the variable.

Although you can construct variables freely, DECTPU built-in procedures require that their parameters be of specific data types. Each built-in procedure can operate only on certain data types. Some built-in procedures return a value of a certain data type when they are executed. The following sections describe the DECTPU data types.

3.1 Array Data Type

An array is a structure for storing and manipulating a group of elements. These elements can be of any data type. You create arrays with the CREATE_ARRAY built-in procedure. For example, the following statement creates the array new_array:

new_array := CREATE_ARRAY;

You can delete arrays with the DELETE built-in procedure.

When you create an array, you can optionally direct DECTPU to allocate a specified number of integer-indexed array elements. DECTPU processes this block of preallocated elements quickly. You can direct DECTPU to create such a block of elements only at the time you create the array.

The following statement creates the array int_array, directs DECTPU to allocate 10 sequential, integer-indexed elements to the array, and specifies that the lowest index value should be 1:

int_array := CREATE_ARRAY (10, 1);

Regardless of whether you specify a preallocated block of elements, you can always add array elements dynamically. Dynamically added elements can be of any data type except learn, pattern, program, or unspecified. You can mix the data types of indexes in an array.

In the following code fragment, the array mix_array is created and the integer 1 is stored in the array element indexed by the marker mark1.

mix_array := CREATE_ARRAY; mark1 := MARK (NONE); mix_array {mark1} := 1; mix_array {"Kansas"} := "Toto";

You can index dynamic elements with integers, even if this means that the array ends up with more integer-indexed elements than you specified when you created the array. DECTPU does not process dynamically added integer-indexed elements as quickly as it processes preallocated elements.

To refer to an array element, use the name of an existing array variable followed by the array index enclosed in braces ( { } ) or parentheses ( () ). For example, if you create an array and store it in the variable my_array, the following are valid element names:

my_array{2} my_array("fred")

To create an element dynamically for an existing array, use the new element as the target of an assignment statement. The following statement creates the element "string1" in the array my_array and assigns the element to the string "Topeka":

my_array{"string1"} := "Topeka";

In the following example, the first statement creates an integer-indexed array, int_array. The array has 10 elements; the first element starts at index 1. The second statement stores a string in the first integer-indexed element of the array. The third statement stores a buffer in the eighth element of the array. The fourth statement adds an integer-indexed element dynamically. This new element contains a string.

int_array := CREATE_ARRAY (10, 1); int_array {1} := "Store a string in the first element"; int_array {8} := CURRENT_BUFFER; int_array {42} := "This is a dynamically created element.";

If you assign a value to an element that has not yet been created, then that element is dynamically created and both the index and the value are stored. Subsequent references to that element index return the stored value.

In most cases, if you reference an element that has not yet been created and you do not assign a value to the nonexistent element, DECTPU does not create the element. DECTPU simply returns the data type unspecified. However, if you reference a nonexistent element by passing the nonexistent element to a procedure, DECTPU adds a new element to the array, giving the element the index you pass to the procedure. DECTPU assigns to this new element the data type unspecified.

You can delete an element in the array by assigning the data type unspecified to the element. For example, the following statement deletes the element my_array {"fred"}:

my_array {"fred"} := TPU$K_UNSPECIFIED;

The following code fragment shows how you can find all the indexes in an array:

the_index := GET_INFO (the_array, "FIRST"); LOOP EXITIF the_index = TPU$K_UNSPECIFIED; . . . the_index := GET_INFO (the_array, "NEXT"); ENDLOOP;

A buffer is a work space for manipulating text. A buffer can be empty or it can contain text records. You can have multiple buffers. A value of the buffer data type is returned by the CREATE_BUFFER, CURRENT_BUFFER, and GET_INFO built-in procedures. CREATE_BUFFER is the only built-in procedure that creates a new buffer. CURRENT_BUFFER and GET_INFO return pointers to existing buffers.

The following statement makes the variable my_buf a variable of type buffer:

my_buf := CREATE_BUFFER ("my_buffer");

When you use a buffer as a parameter for DECTPU built-in procedures, you must use as the parameter the variable to which you assigned the buffer. For example, if you want to erase the contents of the buffer created in the preceding statement, enter the following:

ERASE (my_buf);

In this statement, my_buf is the identifier for the variable my_buf. The string "my_buffer" is the name associated with the buffer. The distinction between the name of the buffer variable and the name of the buffer is useful when you are developing an application layered on DECTPU. For example, the application can use an internal buffer name such as main_buffer to manipulate a given buffer (such as the main buffer in EVE). However, the application can associate the name of your input file with the buffer, making it easier for you to remember which buffer contains the contents of a given file.

If you want to delete the buffer itself, use the DELETE built-in procedure with the buffer variable as the parameter.

More than one buffer variable can represent the same buffer. The following statement causes both my_buf and old_buf to point to the same buffer:

old_buf := my_buf;

A buffer remains in DECTPU's internal list of buffers even when there are no variables pointing to it. You can use the GET_INFO built-in procedure to retrieve buffers from DECTPU's internal list.

Creating a buffer does not cause the information contained in the buffer to become visible on the screen. The buffer must be associated with a window that is mapped to the screen for the buffer contents to be visible. Editing can take place in a buffer even if the buffer is not mapped to a window on the screen.

The current buffer contains the active editing point. The editing point can be different from the cursor position, and often each is in a different location. When the current buffer is associated with a visible window (one that is mapped to the screen), the editing point and the cursor position are usually the same.

At present, a line in a buffer can contain up to 32767 characters. If you try to create a line that is longer than 32767 characters, DECTPU truncates the inserted text and inserts only the amount that fills the line to 32767 characters. If you try to read a file that contains lines longer than 32767 characters, DECTPU truncates all characters after the 32767 characters.

You can associate a single buffer with 0 to 255 windows for editing purposes. You can have a buffer visible in two windows so that you can look at two separate parts of the same file. For example, you could display a set of declarations in one window and code that uses the declarations in another window. Edits made to a buffer show up in all windows to which that buffer is mapped and in which the editing point is visible.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

6018PRO_003.HTML