Syntax

Parameters

None.

Description

The ABORT procedure stops any executing procedures and causes DECTPU to wait for the next key press. ABORT returns control to DECTPU’s main control loop. It causes an immediate exit from all invoked procedures.

Although ABORT behaves much like a built-in, it is actually a DECTPU language element.

ABORT is evaluated for correct syntax at com pile time. In contrast, DECTPU procedures are usually evaluated for a correct parameter count and parameter types at execution time.

Signaled Errors

ABORT is a language element and has no completion codes.

Example

The following example stops execution of the current procedure and returns to DECTPU’s main loop. The error handler does not try to recover from an error.

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

Syntax

Parameters

Description

The ADD_KEY_MAP procedure adds one or more key maps to a key map list. Key maps are added, in the order specified, to either the top or the bottom of the key map list. Key map precedence in a key map list is used to resolve any conflicts between key definitions. The key definition in a preceding key map overrides any conflicting key definitions in key maps that follow in the key map list.

See the descriptions of the DEFINE_KEY, CREATE_KEY_MAP, and CREATE_KEY_MAP_LIST built-in procedures for more information on key definitions, key maps, and key map lists, respectively. Also, see the description of the REMOVE_KEY_MAP built-in procedure for information on removing key maps from a key map list.

Signaled Errors

Examples

Syntax

Parameters

Description

The ADJUST_WINDOW procedure changes the size or screen location, or both, of a window and makes the window that you specify the current window. If you want to check the visible size or location, or both, of a window before making an adjustment to it, use any of the following statements:

SHOW (WINDOW);

SHOW (WINDOWS);

top := GET_INFO (window, "top", VISIBLE_WINDOW);
MESSAGE (STR (top));

bottom := GET_INFO (window, "bottom", VISIBLE_WINDOW);
MESSAGE (STR (bottom));

There are screen line numbers at both the top and bottom of the visible window. Adjust the size of a visible window by changing either or both of these screen line numbers. Make these changes by adding to or subtracting from the current screen line number, not by specifying the screen line number itself.

You can enlarge a window by decreasing the screen line number at the top of the window. (Specify a negative value for integer1.) You can also enlarge a window by increasing the screen line number at the bottom of the window. (Specify a positive value for integer2.) The following example adds four lines to the current window, provided that the values fall within the screen boundaries:

ADJUST_WINDOW (CURRENT_WINDOW, -2, +2)

If you specify integers that attempt to set the screen line number beyond the screen boundaries, DECTPU issues a warning message. DECTPU then sets the window boundary at the edge (top or bottom, as appropriate) of the screen.

You can reduce a window by increasing the screen line number at the top of the window. (Specify a positive value for integer1.) You can also reduce a window by decreasing the screen line number at the bottom of the window. (Specify a negative value for integer2.) If you attempt to make the size of the window smaller than one line (two lines if the window has a status line, three lines if the window has a status line and a horizontal scroll bar), DECTPU issues an error message and no adjustment occurs. The following example reduces the current window by four lines:

ADJUST_WINDOW (CURRENT_WINDOW, +2, -2)

You can also use ADJUST_WINDOW to change the position of the window on the screen without changing the size of the window. The following command moves the current window two lines higher on the screen, provided that the values fall within the screen boundaries:

ADJUST_WINDOW (CURRENT_WINDOW, -2, -2)

Figure 2.1 below shows a screen layout that appears when you invoke DECTPU with EVE and a user-written command file. In this case, the user-written command file divides the screen into two windows. The top window has 15 text lines (including the "End-of-file" message) and a status line. The bottom window has five text lines and a status line. The two bottom lines of the screen are the command window and message window, each consisting of one line.

The user-written command file uses the variable second_window to identify the bottom window. Figure 2.2 shows the screen layout after you enter ADJUST_WINDOW (second_window, –5, 0) after the appropriate prompt from EVE. Both the top and bottom windows now contain 10 lines of text and a status line; the cursor is located in the bottom window. The command and message windows still contain one line each.

ADJUST_WINDOW adds (+/–) integer1 to the "visible_top" and (+/–) integer2 to the "visible_bottom" of a window. The mapping of the window to its buffer is not changed. The new values for the screen line numbers become the values for the original top and original bottom. See the Guide to the DEC Text Processing Utility for more information on window dimensions and window values.

Using ADJUST_WINDOW on a window makes it the current window; that is, DECTPU puts the cursor in that window if the cursor was not already there, and DECTPU marks that window as current in DECTPU’s internal tracking system. DECTPU may scroll or adjust the text in the window to keep the current position visible after the adjustment occurs.

Both ADJUST_WINDOW and MAP may split or occlu de other windows.

If you execute ADJUST_WINDOW within a procedure, the screen is not immediately updated to reflect the adjustment. The adjustment is made after the entire procedure is finished executing and control returns to the screen manager. If you want the screen to reflect the adjustment to the window before the entire procedure is executed, you can force the immediate update of a window by adding an UPDATE statement to the procedure. See the UPDATE built-in procedure for more information.

If you have defined a top or bottom scroll margin, and the window is adjusted so that the scroll margins no longer fit, DECTPU signals TPU$_ADJSCROLLREG and the scroll margins shrink proportionally. For example, if you have a 10-line window, with an 8-line top scroll margin, shrinking the window to a 5-line window also reduces the top scroll margin to four lines.

Signaled Errors

Examples

Syntax

Parameters

None.

Description

The ANCHOR procedure forces the next pattern element either to match immediately or else to fail. When SEARCH fails to find a match for a pattern, it usually tries the search again. To try again, the SEARCH built-in procedure moves the starting position one character forward or backward, depending upon the direction of the search. SEARCH continues this operation until it either finds a match for the pattern or reaches the end or beginning of the buffer or range being searched.

If ANCHOR appears as the first element of a com plex pattern, the search does not move the starting position. Instead, the search examines the next (or previous) character to determine if it matches the next character or element in the complex pattern. If the pattern does not match starting in the original position, the search fails. SEARCH does not move the starting position nor try the search again.

When you use the plus sign (+) operator rather than the ampersand (&) operator to build complex patterns, ANCHOR is useful only as the first element of a complex pattern. It is legal elsewhere in a pattern but has no effect.

Although ANCHOR behaves much like a built-in, it is actually a keyword.

For more information on patterns or modes of pattern searching, see the Guide to the DEC Text Processing Utility.

Signaled Errors

ANCHOR is a keyword and has no completion codes.

Examples

Syntax

Parameters

Return Value

A pattern matching one or more characters that appear in the string, buffer, or range passed as the first parameter to ANY.

Description

The ANY procedure returns a pattern that matches one or more characters from the set specified. You use ANY to construct patterns.

Signaled Errors

Examples

Syntax

Parameters

None.

Description

The APPEND_LINE procedure places the current line at the end of the previous line. You can use APPEND_LINE to delete line terminators.

The editing point in the line that was the current line before APPEND_LINE was executed becomes the editing point.

Using APPEND_LINE may cause DECTPU to insert padding spaces or blank lines in the buffer. APPEND_LINE causes the screen manager to place the editing point at the cursor position if the current buffer is mapped to a visible window.

For more information on the distinction between the cursor position and the editing point, see Appendix C.

If the cursor is not located on a character (that is, if the cursor is before the beginning of a line, beyond the end of a line, in the middle of a tab, or below the end of the buffer), DECTPU inserts padding spaces or blank lines into the buffer to fill the space between the cursor position and the nearest text.

Signaled Errors

Examples

Syntax

Parameter

Return Value

A pattern that matches an arbitrary sequence of characters starting at the editing point and extending for the length you specify.

Description

The ARB procedure returns a pattern that matches an arbitrary sequence of characters starting at the editing point and extending for the length you specify. You can use ARB for wildcard matches of fixed length.

For more information on patterns, see the Guide to the DEC Text Processing Utility.

Signaled Errors

Examples

Syntax

Parameters

Return Value

The character with the specified ASCII value (if you specify an integer or keyword parameter).

The ASCII value of the string you specify (if you specify a string parameter).

Description

The ASCII procedure returns the ASCII value of a character or the character that has the specified ASCII value. The result of ASCII depends upon its argument. If the argument is an integer, ASCII returns a string of length 1 that represents the character of the DEC Multinational Character Set corresponding to the integer you specify. If the argument is a string, ASCII takes the first character of the string and returns the integer corresponding to the ASCII value of that character.

If the argument to ASCII is a keyword, that keyword must be a key name. The KEY_NAME built-in produces key names. In addition, there are several predefined keywords that are key names. See the Guide to the DEC Text Processing Utility for a list of these keywords.

If the keyword is a key name and the key produces a printing character, ASCII returns that character; otherwise, it returns the character whose ASCII value is 0.

Signaled Errors

Examples

Syntax

Parameters

Description

The ATTACH procedure enables you to switch control from your current process to another OpenVMS process that you previously created.

To use ATTACH you must have previously created a subprocess. If the process you specify is not part of the current job or does not exist, an error message is displayed. For information on creating subprocesses, see the description of SPAWN.

ATTACH suspends the current DECTPU process and switches context to the process you use as a parameter. If you do not specify a parameter for ATTACH, DECTPU switches control to the parent or owner process. A subsequent use of the DCL ATTACH command (or a logout from any process except the parent process) resumes the execution of the suspended DECTPU process.

In all cases, DECTPU first deassigns the terminal. If a DECTPU process is resumed following a SPAWN or ATTACH command, DECTPU reassigns the terminal and refreshes the screen.

If the current buffer is mapped to a visible window, the ATTACH built-in causes the screen manager to synchronize the editing point (which is a buffer location) with the cursor position (which is a window location). This may result in the insertion of padding spaces or lines into the buffer if the cursor position is before the beginning of a line, in the middle of a tab, beyond the end of a line, or after the last line in the file.

ATTACH is not a valid built-in in DECwindows DECTPU. However, if you are running non DECwindows DECTPU in a DECwindows terminal emulator, ATTACH works as described.

Signaled Errors

Examples

Syntax

Parameters

Return Value

A marker that points to the first character position of the specified buffer or range.

Description

The BEGINNING_OF procedure returns a marker that points to the first position of a buffer or a range. If you use the marker returned by BEGINNING_OF as a parameter for the POSITION built-in procedure, the editing point moves to the marker.

Signaled Errors

Examples

Syntax

Parameters

None.

Description

The BREAK procedure activates the debugger if DECTPU was invoked with the /DEBUG qualifier. If there is no debugger, BREAK causes the following message to be displayed in the message window:

Breakpoint at line xxx

It has no other effect. Although BREAK behaves much like a built-in, it is actually a DECTPU language element.

BREAK is evaluated for correct syntax at compile time. In contrast, DECTPU procedures are usually evaluated for a correct parameter count and parameter types at execution time.

Signaled Errors

BREAK is a language element and has no completion codes.

Example

The following example contains a break statement. If the statement is executed, DECTPU’s debugger is activated, enabling you to debug that section of the code.

PROCEDURE user_not_quite_working
     .
     .
     .
   BREAK;
     .
     .
     .
ENDPROCEDURE;

Syntax

Parameters

Return Value

The value returned by the called program.

Description

The CALL_USER procedure calls a program written in another language from within DECTPU. The CALL_USER parameters are passed to the external routine exactly as you enter them; DECTPU does not process the parameters in any way.

The integer is passed by reference, and string1 is passed by descriptor. String2 is the value returned by the external program.

In addition to returning the value string2 to CALL_USER, the external program returns a status code that tells whether the program executed successfully. You can trap this status code in an ON_ERROR statement. An even-numbered status code (low bit in R0 clear) causes the ON_ERROR statement to be executed. The ERROR lexical element returns the status value from the program in the form of a keyword.

The CALL_USER parameters are input parameters for the external program you are calling. DECTPU does not process the parameters in any way but passes them to the external procedure exactly as you enter them. You must supply both parameters even if the routine you are calling does not require that information be passed to it. Enter the following null parameters to indicate that you are not passing any actual values:

CALL_USER (0,"")

For information on the DECTPU callable interface, see the VSI OpenVMS Utility Routines Manual.

Signaled Errors

Examples

Syntax

Parameters

Return Values

Description

The CHANGE_CASE procedure changes the case of all alphabetic characters in a buffer, range, or string, according to the keyword that you specify. Optionally, CHANGE_CASE returns a string, range, or buffer containing the changed text.

Signaled Errors

Examples

Syntax

Parameters

Return Value

The program created by compiling the declarations and statements in the string, range, or buffer. If the program fails to compile, an integer zero is returned.

Description

The COMPILE procedure converts DECTPU procedures and statements into an internal, compiled format. Valid items for compilation can be represented by a string, a range, or a buffer. COMPILE optionally returns a program.

The program that COMPILE optionally returns is the compiled form of valid DECTPU procedures, statements, or both. You can assign the compiled version of DECTPU code to a variable name. DECTPU statements, as well as procedure definitions, can be stored by DECTPU in the program returned by COMPILE. Later in your editing session, you can execute the DECTPU code that you com piled by using the program as a parameter for the EXECUTE built-in procedure. You can also use the program as a parameter for the DEFINE_KEY built-in procedure to define a key to execute the program. Then you can execute the program by pressing that key.

COMPILE returns a program variable only if the compilation generates executable statements. COMPILE does not return a program variable if you compile any of the following:

DECTPU cannot compile a string or line of text in a buffer or range longer than 256 characters. If DECTPU encounters a longer string or line, DECTPU truncates characters after the 256th character and attempts to compile the truncated string.

If necessary, use the SET (INFORMATIONAL, ON) built-in procedure before compiling a procedure interactively to see the compiler messages.

To check the results of a compilation to determine whether execution is possible, use the following statement in a program:

x := COMPILE (my_range);
!if the program is nonzero, continue
IF x <> 0

THEN

  .
  .
  .

ENDIF;

If x = 0, no program is generated because of compilation errors or because there are no executable statements. The statement "IF x <> 0 THEN" allows your program to continue as long as a program is generated.

You can also use an ON_ERROR statement to check the result of a com pilation. This statement tells you whether the compilation completed successfully; it does not tell you whether execution is possible.

Signaled Errors

Examples

Syntax

Parameters

Description

The CONVERT procedure, given the coordinates of a point in one coordinate system, returns the corresponding coordinates for the point in the coordinate system you specify. The converted coordinates are returned using the to_x_integer and to_y_integer parameters. Coordinate systems are distinguished both by units employed and where each places its origin.

Signaled Errors

Example

The following example converts a point’s location from the current window’s coordinate system (with the origin in the upper left-hand corner of the window) to the DECTPU screen’s coordinate system (with the origin in the upper left-hand corner of the DECTPU screen).

PROCEDURE user_convert

LOCAL source_x,
      source_y,
      dest_x,
      dest_y;

source_x := 1;
source_y := 1;
dest_x := 0;
dest_y := 0;


CONVERT (CURRENT_WINDOW, COORDINATES, source_x, source_y,
         SCREEN, COORDINATES, dest_x, dest_y);


ENDPROCEDURE;

If the current window is not the top window, CONVERT changes the value of the y coordinate to reflect the difference in the DECTPU screen’s coordinate system. For more information about the difference between a DECTPU window and the DECTPU screen, see the program development chapter in the Guide to the DEC Text Processing Utility.

Syntax

Parameters

Return Value

The range where the copied text has been placed.

Description

The COPY_TEXT procedure makes a copy of the text you specify and places it in the current buffer. If the current buffer is in insert mode, the text you specify is inserted before the current position in the current buffer. If the current buffer is in overstrike mode, the text you specify replaces text starting at the current position and continuing for the length of the string, range, or buffer.

Using COPY_TEXT may cause DECTPU to insert padding spaces or blank lines in the buffer. COPY_TEXT causes the screen manager to place the editing point at the cursor position if the current buffer is mapped to a visible window. For more information on the distinction between the cursor position and the editing point, see Appendix C.

If the cursor is not located on a character (that is, if the cursor is before the beginning of a line, beyond the end of a line, in the middle of a tab, or below the end of the buffer), DECTPU inserts padding spaces or blank lines into the buffer to fill the space between the cursor position and the nearest text.

Signaled Errors

Examples

Syntax

Parameters

Return Value

The variable that is to contain the newly created array

Description

The CREATE_ARRAY procedure creates an array. In DECTPU, an array is a one-dimensional collection of data values that you can consider or manipulate as a unit.

To create an array variable called bat , use the CREATE_ARRAY built-in as follows:

bat := CREATE_aARRAY;

DECTPU arrays can have a static portion, a dynamic portion, or both. A static array or portion of an array contains predeclared integer-indexed elements.

These elements are allocated contiguous memory locations to support quick processing. To create an array with a static portion, specify the number of contiguous integer-indexed elements when you create the array. You also have the option of specifying a beginning index number other than 1. For example, the following statement creates an array with 100 predeclared integer-indexed elements starting at 15:

bat := CREATE_ARRAY (100, 15);

All static elements of a newly created array are initialized to the data type unspecified.

A dynamic portion of an array contains elements indexed with expressions evaluating to any DECTPU data type except unspecified, learn, pattern, or program. Dynamic array elements are dynamically created and deleted as needed. To create a dynamic array element, assign a value to an element of an existing array. For example, the following statement creates a dynamic element in the array bat indexed by the string "bar" and assigns the integer value 10 to the element:

bat{"bar"} := 10;

To create an array with both static and dynamic elements, first create the static portion of the array. Then use assignment statements to create as many dynamic elements as you wish. For example, the following code fragment creates an array stored in the variable small_array. The array has 15 static elements and one dynamic element. The first static element is given the value 10. The dynamic element is indexed by the string "fred" and contains the value 100.

small_array := CREATE_ARRAY (15);
small_array{1} := 10;
small_array{"fred"} := 100;

To delete a dynamic array element, assign to it the constant TPU$K_UNSPECIFIED, which is of type unspecified.

One array can contain elements indexed with several data types. For example, you can create an array containing elements indexed with integers, buffers, windows, markers, and strings. An array element can be of any data type. All array elements of a newly created array are of type unspecified.

If the same array has been assigned to more than one variable, DECTPU does not create multiple copies of the array. Instead, each variable points to the array that has been assigned to it. DECTPU arrays are reference counted, meaning that each array has a counter keeping track of how many variables point to it.

DECTPU arrays are autodelete data types, meaning that when no variables point to an array, the array is deleted automatically. You can also delete an array explicitly by using the DELETE built-in. For example, the following statement deletes the array bat:

DELETE (bat);

If you delete an array that still has variables pointing to it, the variables receive the data type unspecified after the deletion.

If you modify an array pointed to by more than one variable, modifications made using one variable show up when another variable references the modified element. To duplicate an array, you must write a procedure to create a new array and copy the old array’s elements to the new array.

To refer to an array element, use the array variable name followed by an index expression enclosed in braces or parentheses. For example, if bar were a variable of type marker, the following statement would assign the integer value 10 to the element indexed by bar:

bat{bar} := 10;

You can perform the same operations on array elements that you can on other DECTPU variables, with one exception: you cannot make partial pattern assignments to array elements.

See the Guide to the DEC Text Processing Utility for additional information about arrays.

Signaled Errors

Examples

Syntax

Parameters

Return Value

The buffer created by CREATE_BUFFER.

Description

The CREATE_BUFFER procedure defines a new work space for editing text. You can create an empty buffer or you can associate an input file name with the buffer. CREATE_BUFFER optionally returns a buffer.

Although you do not have to assign the buffer that you create to a variable, you need to make a variable assignment if you want to refer to the buffer for future use. The buffer variable on the left-hand side of an assignment statement is the item that you must use when you specify a buffer as a parameter for other DECTPU built-in procedures. For example, to move to a buffer for editing, enter the buffer variable after the POSITION built-in procedure:

my_buffer_variable := CREATE_BUFFER ("my_buffer_name", "my_file_name");
POSITION (my_buffer_variable);

The buffer name that you specify as the first parameter for the CREATE_BUFFER built-in procedure (for example, "my_buffer_name") is used by DECTPU to identify the buffer on the status line. To change the status line, use the SET (STATUS_LINE) built-in procedure.

If you want to skip an optional parameter and specify a subsequent optional parameter, you must use a comma as a placeholder for the skipped parameter.

You can create multiple buffers. Buffers can be empty or they can contain text. The current buffer is the buffer in which any DECTPU commands that you execute take effect (unless you specify another buffer). Only one buffer can be the current buffer. See the CURRENT_BUFFER built-in procedure for more information.

A buffer is visible when it is associated with a window that is mapped to the screen. A buffer can be associated with multiple windows, in which case any edits that you make to the buffer are reflected in all of the windows in which the buffer is visible. To get a list of all the buffers in your editing context, use the SHOW (BUFFERS) built-in procedure.

When you use the following keywords with the SET built-in procedure, you can establish attributes for buffers. The text describes the default for the attributes:

See the SET built-in procedure for more information on these keywords.

Signaled Errors

Examples

Syntax

Parameter

Return Value

A string that is the name of the key map created.

Description

The CREATE_KEY_MAP procedure creates and names a key map. CREATE_KEY_MAP optionally returns a string that is the name of the key map created. A key map is a set of key definitions. Key maps let you manipulate key definitions as a group. Key maps and their key definitions are saved in section files. The default key map for DECTPU is TPU$KEY_MAP, contained in the default key map list TPU$KEY_MAP_LIST. See the description on key map lists in CREATE_KEY_MAP_LIST.

The EVE editor does not use the default key map TPU$KEY_MAP. In EVE, the name of a key map is not the same as the variable that contains the key map. For example, the EVE variable EVE$X_USER_KEYS contains the key map named EVE$USER_KEYS, which stores your key definitions. EVE stores all its key maps in the default key map list TPU$KEY_MAP_LIST. However, the default key map, TPU$KEY_MAP, is removed from the default key map list by the standard EVE section file.

When you create a key map, its keys are undefined. Each key map can hold definitions for all characters in the DEC Multinational Character Set and all the keypad keys and the function keys, in both their shifted and unshifted forms. Each key map has its own name (a string). This name cannot be the same as that of either another key map or a key map list.

Signaled Errors

Examples

The following example creates a key map and defines two keys in the key map. The name of the key map is stored in the variable sample_key_map.

PROCEDURE init_sample_key_map

sample_key_map := CREATE_KEY_MAP ("sample_key_map");

DEFINE_KEY ("EXIT", Ctrl_Z_KEY, "Exit application", sample_key_map);
DEFINE_KEY ("COPY_TEXT (’XYZZY’)", Ctrl_B_KEY, "Magic Word", sample_key_map);

ENDPROCEDURE;

Syntax

Parameters

Return Value

A string that is the name of the key map list created.

Description

The CREATE_KEY_MAP_LIST procedure creates and names a key map list, and also specifies the initial key maps in the key map list it creates. CREATE_KEY_MAP_LIST optionally returns a string that is the name of the key map list created. A key map list is an ordered set of key maps. Key map lists let you change the procedures bound to your keys. To find the definition of a given key, DECTPU searches through the key maps in the specified or default key map list until DECTPU either finds a definition for the key or reaches the end of the last key map in the list.

DECTPU provides the default key map list TPU$KEY_MAP_LIST, which contains the default key map TPU$KEY_MAP. See the description of the CREATE_KEY_MAP built-in procedure for more information on key maps.

The CREATE_KEY_MAP_LIST built-in procedure creates a new key map list, names the key map list, and specifies the initial key maps contained in the list.

Key map lists store directions on what DECTPU is to do when you press an undefined key associated with a printable character. By default, a key map list directs DECTPU to insert undefined printable characters into the current buffer. To change the default, use the SET (SELF_INSERT) built-in procedure.

A newly created key map list is not bound to any buffer. To bind a key map list to a buffer, use the SET (KEY_MAP_LIST) built-in procedure. When you use the POSITION built-in to select a current buffer, the key map list that is bound to the buffer is automatically activated.

A newly created key map list has no procedure defined to be called when an undefined key is referenced. You can define such a procedure with the SET (UNDEFINED_KEY) built-in procedure. The default is to display the message "key has no definition".

Key map lists are saved in section files, along with any undefined key procedures and the SELF_INSERT settings.

Signaled Errors

Examples

The following example creates two key maps and groups them into a key map list:

PROCEDURE init_help_key_map_list

help_user_keys := CREATE_KEY_MAP ("help_user_keys");
help_keys := CREATE_KEY_MAP ("help_keys");
help_key_list := CREATE_KEY_MAP_LIST ("help_key_list", help_user_keys,
                 help_keys);
ENDPROCEDURE;

Syntax

Parameters

Return Value

The process created.

Description

The CREATE_PROCESS procedure starts a subprocess and associates a buffer with it. You can optionally specify an initial command to send to the subprocess.

You can create multiple subprocesses. When you exit from DECTPU, any subprocesses you have created with CREATE_PROCESS are deleted. If you want to remove a subprocess before exiting, use the DELETE built-in procedure with the process as a parameter (DELETE (proc1)), or set the variable to integer zero, as follows:

proc1 := 0

CREATE_PROCESS creates a subprocess of a DECTPU session and all of the output from the subprocess goes into a DECTPU buffer. You cannot run a program or utility that takes over control of the screen from a process created with this built-in procedure. You can, however, use the SPAWN built-in procedure to create a subprocess that suspends your DECTPU process and places you directly at the system command prompt. You can then run programs that control the whole screen.

See the Guide to the DEC Text Processing Utility for a list of subprocess restrictions.

Signaled Errors

Examples

The following example creates a buffer to hold the output from the DCL commands executed by the OpenVMS subprocess:

! Create a buffer to hold the output from the DCL commands
! "SET NOON" and "DIRECTORY".

PROCEDURE user_dcl_process
   dcl_buffer := CREATE_BUFFER ("dcl_buffer");
   MAP (main_window, dcl_buffer);
   my_dcl_process := CREATE_PROCESS (dcl_buffer, "SET NOON");
   MESSAGE ("Creating DCL subprocess...");
   SEND ("DIRECTORY", my_dcl_process);
ENDPROCEDURE;

Syntax

Parameters

Return Value

The range created by CREATE_RANGE.

Description

The CREATE_RANGE procedure returns a range that includes two delimiters and all the characters between them, and sets the video attributes for displaying the characters when they are visible on the screen. A range delimiter can be a marker, the beginning or end of a line, or the beginning or end of a buffer. The beginning and ending delimiters do not have to be of the same type but must be in the same buffer.

CREATE_RANGE establishes a range that is delimited by the markers you specify. You can create multiple ranges in a buffer. When you apply video attributes to a range, you can see the range if it is in a visible buffer. A range may overlap another range.

If you clear the contents of a range with the ERASE built-in procedure, the range structure still exists. The range and its video attributes, if any, move to the next character or position beyond where the range ended before the range was erased.

To remove the range structure, use the DELETE built-in procedure or set the variable to which the range is assigned to zero (r1 := 0).

In portions of a range that either are associated with nonprintable characters or are not associated with characters at all, DECTPU does not display any of the video attributes of the range. However, if you insert new characters into portions of a range where the video attributes have not been displayed, the new characters do display the video attributes that apply to the range.

CREATE_RANGE checks whether the markers you specify as parameters are free markers. A free marker is a marker not bound to a character. For more information on free markers, see the description of the MARK built-in procedure.

If a marker defining a range is a free marker, DECTPU ties the range to the character or end-of-line nearest to the free marker to use as the range delimiter. An end-of-line is not a character but is a point to which a marker can be bound.

Signaled Errors

Examples

Syntax

Syntax

Parameters

Return Value

The newly created widget.

Description

The CREATE_WIDGET procedure creates a widget. The widget name that you specify in the User Interface Definition (UID) file must match the case of the widget name that you specify as a parameter to CREATE_WIDGET. If you specify case-sensitive widget names in your User Interface Language (UIL) file, you must use the same widget name case with CREATE_WIDGET as you used in the UIL file. If you specify case-insensitive widget names in your UIL file, the UIL compiler translates all widget names to uppercase, so in this instance you must use uppercase widget names with CREATE_WIDGET. Example 1 in the Examples section specifies case-insensitive widget names in the UIL file and specifies an uppercase name for the widget with the CREATE_WIDGET built-in procedure.

If you specify one or more callback arguments in your UIL file, specify either the routine TPU$WIDGET_INTEGER_CALLBACK or the routine TPU$WIDGET_STRING_CALLBACK. For more information about specifying callbacks, see the Guide to the DEC Text Processing Utility. For more information about UIL files, see the VMS DECwindows Guide to Application Programming. DECTPU uses the Motif Version 1.1-3 compatibility libraries and requires that UID files are produced using the 1.1-3 UIL compiler and not the version 1.2 UIL compiler provided with new releases of DECwindows. Procedures for using the 1.1-3 UIL com piler are described in the DECwindows release notes.

Signaled Errors

Examples

Syntax

Parameters

Return Value

The window created by CREATE_WINDOW.

Description

The CREATE_WINDOW procedure defines a screen area called a window. You must specify the screen line number at which the window starts, the length of the window, and whether the status line is to be displayed. CREATE_WINDOW optionally returns the newly created window. If you want to use the window that you create as a parameter for any other built-in procedure, then you should specify a variable into which the window is returned.

You can create multiple windows on the screen, but only one window can be the current window. The cursor is positioned in the current window. The current window and the current buffer are not necessarily the same.

To make a window visible, you must associate a buffer with the window and then map the window to the screen. The following command maps main_window to the screen:

MAP (main_window, main_buffer)

See the MAP built-in procedure for more information.

The following keywords used with the SET built-in procedure let you establish attributes for windows. This list shows the defaults for the attributes:

See the SET built-in procedure for more information on these keywords.

Use the SHIFT built-in procedure to display text that lies to the right of the window’s right edge in an unshifted window. For more information, see the description of the SHIFT built-in in this chapter.

Signaled Errors

Examples

Syntax

Parameters

None.

Return Value

The buffer in which you are currently positioned.

Description

The CURRENT_BUFFER procedure returns the buffer in which you are currently positioned. The current buffer is the work space in which any DECTPU statements you execute take effect. The editing point is in the current buffer. The editing point is not necessarily the same as the cursor position.

Signaled Errors

Examples

Syntax

Parameters

None.

Return Value

A string that consists of the character at the editing point in the current buffer.

Description

The CURRENT_CHARACTER procedure returns the character at the editing point in the current buffer at which most editing operations are carried out. Each buffer maintains its own editing point, but only the editing point in the current buffer is the active editing point. An editing point, which always refers to a character position in a buffer, is not necessarily the same as the cursor position, which always refers to a location in a window. For more information on the distinction between the editing point and the cursor position, see Appendix C.

If the editing point is at the end of a line, CURRENT_CHARACTER returns a null string. If the editing point is at the end of a buffer, CURRENT_CHARACTER returns a null string and also signals a warning.

Using CURRENT_CHARACTER may cause DECTPU to insert padding spaces or blank lines in the buffer. CURRENT_CHARACTER causes the screen manager to place the editing point at the cursor position if the current buffer is mapped to a visible window. For more information on the distinction between the cursor position and the editing point, see Appendix C.

If the cursor is not located on a character (that is, if the cursor is before the beginning of a line, beyond the end of a line, in the middle of a tab, or below the end of the buffer), DECTPU inserts padding spaces or blank lines into the buffer to fill the space between the cursor position and the nearest text.

Signaled Errors

Examples

Syntax

Parameters

None.

Return Value

An integer that is the column number of the current cursor position on the screen.

Description

The CURRENT_COLUMN procedure returns an integer that is the current column number of the cursor position on the screen. The column numbers range from 1 on the extreme left of the screen to the maximum value allowed for the terminal type you are using on the extreme right of the screen.

The value returned by CURRENT_COLUMN and the value returned by GET_INFO (SCREEN, "current_column") are equivalent.

When used in a procedure, CURRENT_COLUMN does not necessarily return the position where the cursor has been placed by other statements in the procedure. DECTPU generally does not update the screen until all statements in a procedure are executed. If you want the cursor position to reflect the actual editing location, put an UPDATE statement in your procedure immediately before any statements containing CURRENT_COLUMN, as follows:

UPDATE (CURRENT_WINDOW);

If you do not want to update a window to get the current value for CURRENT_COLUMN, you can use the GET_INFO built-in procedure (buffer_variable, "offset_column"). This built-in returns the column number that the current offset in the buffer would have if it were mapped to a window, and if you were to force a screen update. This built-in returns an accurate value only if both of the following conditions are true:

GET_INFO (window_variable, "current_column") does not necessarily return the column number that the cursor would occupy if you caused an explicit screen update.

If a window is shifted, CURRENT_COLUMN still returns the current column number of the cursor on the screen. However, the value returned by x := GET_INFO (buffer, "offset_column") includes the number of columns by which the window is shifted. For example, if a window is shifted to the left by eight column s, CURRENT_COLUMN returns the value 1, while x := GET_INFO (buffer, "offset_column") returns the value 9.

Signaled Errors

Examples

Syntax

Parameters

None.

Return Value

A keyword (FORWARD or REVERSE) that indicates the current direction of the current buffer.

Description

The CURRENT_DIRECTION procedure returns a keyword (FORWARD or REVERSE) that indicates the current direction of the current buffer. See also the descriptions of the SET (FORWARD) and SET (REVERSE) built-in procedures. If the FORWARD keyword is returned, the current direction is toward the end of the buffer. If the REVERSE keyword is returned, the current direction is toward the beginning of the buffer.

Signaled Errors

Examples

Syntax

Parameters

None.

Return Value

A string that represents the current line.

Description

The CURRENT_LINE procedure returns a string that represents the current line. The current line is the line that contains the editing point. If you are positioned on a line that has a length of 0, CURRENT_LINE returns a null string. If you are positioned at the end of the buffer, CURRENT_LINE returns a null string and also signals a warning.

Using CURRENT_LINE may cause DECTPU to insert padding spaces or blank lines in the buffer. CURRENT_LINE causes the screen manager to place the editing point at the cursor position if the current buffer is mapped to a visible window. For more information on the distinction between the cursor position and the editing point, see Appendix C.

If the cursor is not located on a character (that is, if the cursor is before the beginning of a line, beyond the end of a line, in the middle of a tab, or below the end of the buffer), DECTPU inserts padding spaces or blank lines into the buffer to fill the space between the cursor position and the nearest text.

Signaled Errors

Examples

Syntax

Parameters

None.

Return Value

An integer that is the offset of the editing point within the current line.

Description

The CURRENT_OFFSET procedure returns an integer for the offse t of the editing point within the current line. The current offset is the number of positions a character is located from the first character position in the current line (offse t 0). In DECTPU, the leftmost character position is offset 0, and this offset is increased by 1 for each character position (including the tab character) to the right. DECTPU numbers columns starting with the leftmost position on the screen where a character could be placed, regardless of where the margin is. This leftmost position is numbered 1.

Using CURRENT_OFFSET may cause DECTPU to insert padding spaces or blank lines in the buffer. CURRENT_OFFSET causes the screen manager to place the editing point at the cursor position if the current buffer is mapped to a visible window. For more information on the distinction between the cursor position and the editing point, see Appendix C.

If the cursor is not located on a character (that is, if the cursor is before the beginning of a line, beyond the end of a line, in the middle of a tab, or below the end of the buffer), DECTPU inserts padding spaces or blank lines into the buffer to fill the space between the cursor position and the nearest text.

If you are using an interface with free cursor motion, when you move beyond the end of a line CURRENT_OFFSET makes the current cursor position the new end-of-line.

If the current offset equals the length of the current line, you are positioned at the end of the line.

Signaled Errors

Examples

Syntax

Parameters

None.

Return Value

An integer that represents the screen line on which the cursor is located.

Description

The CURRENT_ROW procedure returns an integer that is the screen line on which the cursor is located. The screen lines are numbered from 1 at the top of the screen to the maximum number of lines available on the terminal. You can get the value of the current row by using the GET_INFO (SCREEN, "current_ row") built-in procedure.

When used in a procedure, CURRENT_ROW does not necessarily return the position where the cursor has been placed by other statements in the procedure. The value returned by CURRENT_ROW may not be the current value because DECTPU generally does not update the screen until all statements in a procedure are executed. If you want the cursor position to reflect the actual editing location, put an UPDATE statement in your procedure immediately before any statements containing CURRENT_ROW, as follows:

UPDATE (CURRENT_WINDOW);

Signaled Errors

Examples

Syntax

Parameters

None.

Return Value

The window in which the cursor is visible.

Description

The CURRENT_WINDOW procedure returns the window in which the cursor is visible. The current window is the window on which you have most recently performed one of the following operations:

The current window contains the cursor at the screen coordinates current_row and current_column. The current buffer is not necessarily associated with the current window.

Signaled Errors

Examples

Syntax

Parameter

Return Value

An integer that represents the number of columns the cursor moved. If DECTPU cannot move the cursor as many columns as specified by integer1, DECTPU moves the cursor as many columns as possible. The return value may be negative. This notation is reserved for future versions of DECTPU. A negative return value does not denote that the cursor moved to the left. Rather, the integer shows the number of spaces that the cursor moved right or left. If the cursor did not move, integer2 has the value 0. If the CURSOR_HORIZONTAL built-in produces an error, the value of integer2 is indeterminate.

Description

The CURSOR_HORIZONTAL procedure moves the cursor position across the screen and optionally returns the cursor movement status. You can use CURSOR_HORIZONTAL to provide free cursor movement in a horizontal direction. Free cursor movement means that the cursor is not tied to text, but can move across all available columns in a screen line.

If you move before the beginning of a line, after the end of a line, in the middle of a tab, or beyond the end-of-file mark, other built-ins may cause padding lines or spaces to be added to the buffer.

If you use the CURSOR_HORIZONTAL built-in within a procedure, screen updating occurs in the following manner:

Signaled Errors

Examples

Syntax

Parameters

Return Value

An integer that represents the number of rows that the cursor moved up or down. If DECTPU could not move the cursor as many rows as specified by integer1, DECTPU moves the cursor as many rows as possible.

If CROSS_WINDOW_BOUNDS is set to ON, CURSOR_VERTICAL may position the cursor to another window. In this case, CURSOR_VERTICAL returns the negative of the number of rows the cursor moved. A negative return value does not denote that the cursor moved upward.

If the cursor did not move, integer2 has the value 0. If the CURSOR_VERTICAL built-in procedure produced an error, the value of integer2 is indeterminate.

Description

The CURSOR_VERTICAL procedure moves the cursor position up or down the screen and optionally returns the cursor movement status. You can use CURSOR_VERTICAL to provide free cursor movement in a vertical direction. Free cursor movement means that the cursor is not tied to text, but that it can move up and down to all lines on the screen that can be edited, whether or not there is text at that column in the new line.

The cursor does not move beyond the top or the bottom edges of the screen. However, CURSOR_VERTICAL can cross window boundaries, depending upon the current setting of the CROSS_WINDOW_BOUNDS flag. See SET (CROSS_WINDOW_BOUNDS) for information on how to set this flag. Use the POSITION built-in to move the cursor to a different window on the screen.

When CROSS_WINDOW_BOUNDS is set to ON, CURSOR_VERTICAL can move the cursor position to a new window. The new window in which the cursor is positioned becomes the current window. The column position of the cursor remains unchanged unless vertical movement would position the cursor outside the bounds of a window narrower than the previous window. In this instance, the cursor moves to the left until it is positioned within the right boundary of the narrower window.

When CROSS_WINDOW_BOUNDS is set to OFF, CURSOR_VERTICAL does not move the cursor outside the current window. If the SET (SCROLLING) built-in has been used to set scrolling margins, CURSOR_VERTICAL also attempts to keep the cursor within the scroll margins.

CURSOR_VERTICAL positions the cursor only in screen areas in which editing can occur. For example, CURSOR_VERTICAL does not position the cursor on the status line of a window, in the prompt area, or in an area of the screen that is not part of a window. The blank portion of a segmented window is not considered part of a window for this purpose.

If you use CURSOR_VERTICAL within a procedure, screen updating occur s in the following manner:

Signaled Errors

Examples

Syntax

Parameters

None.

Return Value

An integer that represents the line number of the current breakpoint.

Description

The DEBUG_LINE procedure returns the line number of the current breakpoint. Use DEBUG_LINE when writing your own DECTPU debugger.

VSI recommends that you use the debugger provided in SYS$SHARE:TPU$DEBUG.TPU.

Signaled Errors

Examples

Syntax

Parameters

Description

The DEFINE_KEY procedure associates executable DECTPU code with a key or a combination of keys. DEFINE_KEY com piles the first parameter if it is a string, buffer, or range.

If you use DEFINE_KEY to change the definition of a key that was previously defined, DECTPU does not save the previous definition.

You can define all the keys on the LK201 and LK401 keyboards and keypads with the following exceptions:

There are some keys that you can define but that VSI strongly recommends you avoid defining. DECTPU does not signal an error when you use them as keyword parameters. However, on character-cell terminals the definitions you assign to these key combinations are not executed unless you set your terminal in special ways at the DCL level. VSI recommends that you do not use the following special terminal settings. The settings may cause unpredictable results if you do not understand all the implications of changing the default settings:

The PF1 key is the default shift key for the editor. You cannot define PF1 unless you use either the SET (SHIFT_KEY, keyword) built-in procedure or the EVE SET GOLD KEY command to define a different key as the shift key for the editor.

Whenever you extend EVE by writing a procedure that can be bound to a key, the procedure must return true or false, as needed, to indicate whether execution of the procedure completed successfully. EVE’s REPEAT command relies on this return value to determine whether to halt repetition of a command, a procedure bound to a key, or a learn sequence.

Signaled Errors

Examples

Syntax

Parameters

Return Value

An integer used by the CREATE_WIDGET built-in to identify the class of widget to be created.

Description

The DEFINE_WIDGET_CLASS procedure defines a widget class and optional creation routine for later use in creating widgets of that class.

Defining a class that is already defined returns the existing class integer. Defining a new class also defines the widget creation routine as the second parameter, if specified, or the X toolkit routine XtCreateWidget.

Signaled Errors

Examples

For a sample procedure using the DEFINE_WIDGET_CLASS built-in, see Example A.1.

Syntax

Parameters

Description

The DELETE procedure removes DECTPU structures from your editing context. When you delete a structure (for example, a range), all variables that refer to that structure are reset to unspecified. If the deleted structure had any associated resources, these resources are returned to the editor. When a buffer is deleted, the associated journal file (if any) is closed and deleted.

Depending upon how many variables are referencing an entity, or how many other entities are associated with the entity you are deleting, processing the DELETE built-in procedure can be time consuming. DELETE cannot be terminated by a Ctrl/C.

Any variables that reference the deleted entity are set to unspecified and all other entities that are associated with the deleted entity are also deleted. Use the DELETE built-in procedure with caution.

Signaled Errors

Examples

Syntax

Parameters

Return Values

Description

The EDIT procedure modifies a string accor ding to the keywords you specify. EDIT is similar (although not identical) to the DCL lexical function F$EDIT. DECTPU modifies the first parameter of the EDIT built-in in place. EDIT does not modify a literal string.

By default, EDIT does not modify quoted text that occurs within a string. For example, the following code does not change the case of WELL:

string_to_change := ’HE SANG "WELL"’; edit (string_to_change, LOWER);

The variable string_to_change has the value he sang "WELL" .

If you specify more than one of the TRIM keywords (TRIM, TRIM_LEADING, TRIM_TRAILING), all of the TRIM operations you specify are performed.

If you specify more than one of the case conversion keywords (UPPER, LOWER, INVERT), the last keyword that you specify determines how the characters in the string are modified.

If you specify both of the quote recognition keywords (ON, OFF), the last keyword you specify determines whether EDIT modifies quoted text.

If you specify no keywords, EDIT does nothing to the passed string.

You can disable the recognition of quotation marks and apostrophes as DECTPU quote characters by using the OFF keyword as a parameter for EDIT. When you use the OFF keyword, DECTPU preserves any quotation marks and apostrophes in the edited text and performs the editing tasks you specify on the text within the quotation marks and apostrophes. OFF may appear anywhere in the keyword list. It need not be the final parameter.

If the string you specify has opening quotation marks but not closing quotation marks, the status TPU$_MISSINGQUOTE is returned. All text starting at the unclosed opening quotation mark and continuing to the end of the string is considered to be part of the quoted string and is not modified.

EDIT is similar to the DCL lexical function F$EDIT, with the following differences:

Signaled Errors

Examples

Syntax

Parameters

Return Value

A marker pointing to the last character position in a buffer or range.

Description

The END_OF procedure returns a marker that points to the last character position in a buffer or a range. If you use the marker returned by the END_OF built-in as a parameter for the POSITION built-in procedure, the editing point moves to this marker.

Signaled Errors

Examples

Syntax

Parameters

Description

The ERASE procedure removes the contents of the buffer or range that you specify. However, the buffer structure still remains a part of your editing context and the editing point remains in the buffer even if you remove the contents of the buffer. The space that was occupied by the contents of the buffer is returned to the system and is available for reuse. Only the end-of-buffer line remains.

When you erase a range, the contents of the range are removed from the buffer. The range structure is still a part of your editing context. You can use the range structure later in your editing session to delimit an area of text within a buffer.

Note that text does not belong to a range; it belongs to a buffer. Ranges are merely a way of manipulating portions of text within a buffer. For more information on ranges, see the Guide to the DEC Text Processing Utility.

Signaled Errors

Examples

Syntax

Parameters

Return Value

A string that represents the characters deleted by ERASE_CHARACTER.

Description

The ERASE_CHARACTER procedure deletes up to the number of characters that you specify and optionally returns a string that represents the characters you deleted.

If the argument to ERASE_CHARACTER is a positive integer, ERASE_CHARACTER deletes that many characters, starting at the current position and continuing toward the end of the line. If the argument is negative, ERASE_CHARACTER deletes characters to the left of the current character. It uses the absolute value of the parameter to determine the number of characters to delete.

ERASE_CHARACTER stops deleting characters if it reaches the beginning or the end of the line before deleting the specified number of characters.

Using ERASE_CHARACTER may cause DECTPU to insert padding spaces or blank lines in the buffer. ERASE_CHARACTER causes the screen manager to place the editing point at the cursor position if the current buffer is mapped to a visible window. For more information on the distinction between the cursor position and the editing point, see Appendix C.

If the cursor is not located on a character (that is, if the cursor is before the beginning of a line, beyond the end of a line, in the middle of a tab, or below the end of the buffer), DECTPU inserts padding spaces or blank lines into the buffer to fill the space between the cursor position and the nearest text.

ERASE_CHARACTER optionally returns a string that contains the characters that it deleted.

Signaled Errors

Examples

Syntax

Parameters

None.

Return Value

A string that contains the text of the deleted line.

Description

The ERASE_LINE procedure removes the current line from the current buffer. The current position moves to the first character of the line following the deleted line. ERASE_LINE optionally returns a string containing the text of the deleted line.

Using ERASE_LINE may cause DECTPU to insert padding spaces or blank lines in the buffer. ERASE_LINE causes the screen manager to place the editing point at the cursor position if the current buffer is mapped to a visible window. For more information on the distinction between the cursor position and the editing point, see Appendix C.

If the cursor is not located on a character (that is, if the cursor is before the beginning of a line, beyond the end of a line, in the middle of a tab, or below the end of the buffer), DECTPU inserts padding spaces or blank lines into the buffer to fill the space between the cursor position and the nearest text.

If the screen manager inserts padding spaces, ERASE_LINE deletes these spaces when it deletes the line. The spaces appear in the returned string. If the screen manager inserts padding lines into the buffer, ERASE_LINE deletes only the last of these lines.

Signaled Errors

Examples

Syntax

Parameters

None.

Return Value

A keyword that represents the most recent error.

Description

The ERROR procedure returns a keyword for the latest error. The possible error and warning codes for each built-in procedure are included in the description of each built-in procedure. The OpenVMS System Messages and Recovery Procedures Reference Manual includes all the possible completion codes for DECTPU as well as the appropriate explanations and suggested user actions.

The value returned by ERROR is meaningful only inside an error handler after an error has occurred. The value outside an error handler is indeterminate.

Although ERROR behaves much like a built-in, it is actually a DECTPU language element.

ERROR is evaluated for correct syntax at com pile time. In contra st, DECTPU procedures are usually evaluated for a correct parameter count and parameter types at execution.

Signaled Errors

ERROR is a language element and has no completion codes.

Examples

The following example uses the ERROR language element to determine the error that invoked the error handler. If the error was that SEARCH could not find the specified string, then the procedure returns normally. If the error was something else, then the text of the error message is written to the MESSAGES buffer and any executing procedures are terminated.

PROCEDURE strip_blanks

! Remove trailing blanks from all the lines in a buffer

    LOCAL blank_chars,
          blank_pattern,
          blank_range;

    ON_ERROR
        IF ERROR = TPU$_STRNOTFOUND
        THEN
            RETURN;
        ELSE
            MESSAGE (ERROR_TEXT);
            ABORT;
    ENDIF;
ENDON_ERROR;
        blank_chars := ASCII (32) + ASCII (9);
        blank_pattern := (SPAN (blank_chars) @ blank_range) + LINE_END;
    LOOP
       SEARCH (blank_pattern, FORWARD);
       POSITION (BEGINNING_OF (blank_range));
       ERASE (blank_range);
    ENDLOOP;
ENDPROCEDURE;

Syntax

Parameters

None.

Return Value

An integer that represents the line number of the most recent error.

Description

The ERROR_LINE procedure returns the line number at which the latest error or warning occur s. If a procedure was com piled from a buffer or range, ERROR_LINE returns the line number within the buffer. This may be different from the line number within the procedure. If the procedure was compiled from a string, ERROR_LINE returns 1.

The value returned by ERROR_LINE is meaningful only inside an error handler after an error has occurred. The value outside an error handler is indeterminate.

Although ERROR_LINE behaves much like a built-in, it is actually a DECTPU language element.

ERROR_LINE is evaluated for correct syntax at com pile time. In contra st, DECTPU procedures are usually evaluated for a correct parameter count and parameter types at execution.

Signaled Errors

ERROR is a language element and has no completion codes.

Examples

The following example uses the ERROR_LINE built-in procedure to report the line in which the error occurred:

PROCEDURE strip_blanks

! Remove trailing blanks from all the lines in a buffer

   LOCAL blank_chars,
         blank_pattern,
         blank_range;

    ON_ERROR
        MESSAGE (ERROR_TEXT);
        MESSAGE ("Error on line " + STR (ERROR_LINE));
        RETURN;
    ENDON_ERROR;

    blank_chars := ASCII (32) + ASCII (9);
    blank_pattern := (SPAN (blank_chars) @ blank_range) + LINE_END;

    LOOP
       SEARCH (blank_pattern, FORWARD);
       POSITION (blank_range);
       ERASE (blank_range);
    ENDLOOP;
ENDPROCEDURE;

Syntax

Parameters

None.

Return Value

A string that contains the text of the most recent error message.

Description

The ERROR_TEXT procedure returns the text of the most recent error or warning message.

The possible error and warning codes for each built-in procedure are included in the description of each built-in procedure. The OpenVMS System Messages and Recovery Procedures Reference Manual includes all the possible completion codes for DECTPU as well as the appropriate explanations and suggested user actions.

The value returned by ERROR_TEXT is meaningful only inside an error handler after an error has occurred. The value outside an error handler is indeterminate.

Although ERROR_TEXT behaves much like a built-in, it is actually a DECTPU language element.

ERROR_TEXT is evaluated for correct syntax at com pile time. In contrast, DECTPU procedures are usually evaluated for a correct parameter count and parameter types at execution.

Signaled Errors

ERROR_TEXT is a language element and has no completion codes.

Examples

The following example uses the ERROR_TEXT built-in procedure to report what happened and where:

PROCEDURE strip_blanks

! Remove Trailing blanks from all the lines in a buffer

   LOCAL blank_chars,
         blank_pattern,
         blank_range;

   ON_ERROR
         MESSAGE (ERROR_TEXT);
         MESSAGE ("Error on line " + STR (ERROR_LINE));
         RETURN;
   ENDON_ERROR;

blank_chars := ASCII (32) + ASCII (9);
blank_pattern := (SPAN (blank_chars) @ blank_range) + LINE_END;

   LOOP
         SEARCH (blank_pattern, FOREWARD);
         POSITION (BEGINNING_OF (blank_range));
         ERASE (blank_range);
   ENDLOOP;
ENDPROCEDURE;

Syntax

Parameters

Description

The EXECUTE procedure does one of the following:

EXECUTE performs different actions depending upon the data type of the parameter.

If the parameter is a string or the contents of a buffer or range, it must contain only valid DECTPU statements; otherwise, you get an error message and no action is taken. See the description of the COMPILE built-in procedure for restrictions and other information on compiling strings or the contents of a buffer or range. When you pass a string to EXECUTE, the string cannot be longer than 256 characters.

Procedures are usually executed by entering the name of a compiled procedure at the appropriate prompt from your editing interface, or by calling the procedure from within another procedure. However, you can execute procedures with the EXECUTE built-in procedure if the procedure returns a data type that is a valid parameter.

Signaled Errors

Examples

Syntax

Parameters

None.

Description

The EXIT command terminates the editing session and writes out any modified buffers that have associated files. DECTPU queries you for a file name for any buffer that you have modified that does not already have an associated file.

Buffers that have the NO_WRITE attribute are not written out. See SET (NO_WRITE, buffer).

If you do not modify a buffer, DECTPU does not write out the buffer to a file when you use EXIT. If you modify a buffer that has an associated file name (because you specified a file name for the second parameter of CREATE_BUFFER),

DECTPU writes out a new version of the file. DECTPU requires the application to make backup copies of existing files before using EXIT.

If you modify a buffer that does not have an associated file name, DECTPU asks you to specify a file name if you want to write the buffer. If you press the Return key rather than entering a file name, the modified buffer is discarded. DECTPU queries you about all modified buffers that do not have associated file names. The order of the query is the order in which the buffers were created.

DECTPU deletes journal files (if any) upon exiting.

If an error occurs while you are exiting, the exit halts and control returns to the application.

Signaled Errors

Syntax

Parameters

Return Value

Returns a string that contains the names that begin with the string you specify.

Description

The EXPAND_NAME procedure returns a string that contains the names of any DECTPU global variables, keywords, or procedures (built-in or user-written) that begin with the string that you specify. DECTPU searches its internal symbol tables to find a match, using your input string as the directive for the match.

If there are no matches for the substring you specify, a null string is returned and a warning (TPU$_NONAMES) is signaled. If only one DECTPU name matches the substring you specify, the name is returned with no trailing space. If more than one DECTPU name matches your substring, all of the matching names are returned. The matching names are returned as a concatenated string with words separated by a single space. Multiple names signal a warning (TPU$_MULTIPLENAMES).

Use EXPAND_NAME in procedures that perform command completion or that interpret abbreviated names.

EXPAND_NAME does not expand the names of local variables.

Signaled Errors

Examples

Syntax

Parameters

Return Value

A string that contains the output you specify in ASCII format.

Description

The FAO procedure invokes the Formatted ASCII Output ($FAO) system service to convert a control string to a formatted ASCII output string. By specifying arguments for FAO directives in the control string, you can control the processing performed by the $FAO system service. The FAO procedure returns a string that contains the formatted ASCII output, constructed according to the rules of the $FAO system service. The control string directs the formatting process, and the optional arguments are values to be substituted into the control string.

FAO accepts up to 127 parameters. It can return strings of 65535 characters maximum.

For complete information on the $FAO system service, see the VSI OpenVMS System Services Reference Manual.

To ensure that you get meaningful results, you should use the !AS directive for strings and the !OL, !XL, !ZL, !UL, or !SL directive for integers.

Signaled Errors

Examples

Syntax

Parameters

Return Value

A string that contains an expanded file specification or the file specification field that you specify.

Description

The FILE_PARSE procedure parses a file specification and returns a string that contains the expanded file specification or the field that you specify. If you do not provide a complete file specification, FILE_PARSE supplies defaults in the return string.

If an error occurs during the parse, FILE_PARSE returns a null string. With FILE_PARSE, you can parse file specification s into their individual fields and merge fields from three file specifications into one file specification.

Specify the first three parameters as strings. The remaining parameters are keywords. File specifications that include OpenVMS logical names and device names must terminate with a colon. If you omit optional parameters to the left of a given parameter, you must include null strings as placeholders for the missing parameters.

If you omit any fields from the file specified in filespec , FILE_PARSE supplies defaults, first from string1 and then from string2 . The exception to this is that the version field is not supplied from string2.

If you omit the device, directory, type, or version fields from the files specified in filespec , string1 , or string2 , FILE_PARSE supplies default values. The default values are the current device and directory, the file type delimiter (.), and the file version delimiter (;). The exception to this is that the current device and directory are not supplied if either string1 or string2 contains a node field.

You can specify as many of the keywords for field names as you wish as long as you do not specify fields that are duplicates of fields returned by the head or tail keywords. For example, you cannot request the head field along with the node, device, or directory fields; and you cannot request the tail field along with the name, type, or version fields. If valid keyword combinations are present, FILE_PARSE returns a string containing only those fields requested. The fields are returned in normal file specification order. The normal delimiters are included, but there are no other characters separating the fields. For example, suppose you direct DECTPU to execute the following statements:

result := FILE_PARSE ("junk.txt","work::","disk1:",NODE, DEPROVICE, TYPE);
MESSAGE (result);

When the statements execute, DECTPU displays the following string:

WORK::DISK1:.TXT

The FILE_PARSE built-in procedure parses the file specification provided and returns the portions of the resultant file specification requested. It does not check that the file exists.

You can use wildcard directives in supplying file specifications.

The table gives an example of the parsing of the following OpenVMS file specification:

node1::usera$:[flamingo.work]eve$section.tpu$section;12

Signaled Errors

Examples

The following example returns a full file specification for the file PROGRAM.PAS. The second parameter provides the name of the directory in which the file can be found. Because the device and version fields are missing from the two parameters, FILE_PARSE includes the current device and the version delimiter (;) in the returned file specification.

spec := FILE_PARSE ("program.pass", "[abbott]")

Syntax

Parameters

Return Value

A string that contains the partial or full file specification that you request from $SEARCH.

Description

The FILE_SEARCH procedure searches one or more directories and returns the partial or full file specification that matches your request. You must use this built-in procedure multiple times with the same parameter to get all of the occurrences of a file name in the directories.

Specify the first three parameters as strings. The remaining parameters are keywords. File specifications that include OpenVMS logical names and device names must terminate with a colon. If you omit optional parameters to the left of a given parameter, you must include null strings as placeholders for the missing parameters.

Unlike the FILE_PARSE built-in, FILE_SEARCH verifies that the file you specify exists.

If FILE_SEARCH does not find a matching file, or if the built-in finds one or more matches but is invoked again and does not find another match, FILE SEARCH returns a null string but not an error status. Thus, the null string can act as an "end of matching files" indicator. When FILE_SEARCH returns the status TPU$_SEARCHFAIL, look in the message buffer to see why the search was unsuccessful.

Refer to the description of the FILE_PARSE built-in for more information on using the optional parameters to FILE_SEARCH.

Signaled Errors

Examples

Syntax

Parameters

Description

The FILL procedure reformat s the text in the specified buffer or range so that the lines of text are approximately the same length. FILL recognizes two classes of characters: text characters and word separators. Any character can be a word separator, and any character other than the space character can be a text character. The space character is always a word separator, even if it is not present in the second parameter passed to FILL.

A word is a contiguous sequence of text characters, all of which are included on the same line, immediately preceded by a word separator or a line break, and immediately followed by a word separator or line break. If the first or last character in the specified range is a text character, that character marks the beginning or end of a word, regardless of any characters outside the range. Filling a range that starts or ends in the middle of a word may result in the insertion of a line break between that part of the word inside the filled range and that part of the word outside the range.

When filling a range or buffer, FILL does the following to each line:

FILL sets the line’s left margin to the default left margin unless that line is the first line of the buffer or range being filled. In this case, FILL sets the line’s left margin to the fill left margin plus the first line indent. However, if you are filling a range and the range does not start at the beginning of a line, FILL does not change the left margin of that line.

FILL moves a word up to the previous line if the previous line is in the range to be filled and if the word fits on the previous line without extending beyond the fill right margin. Before moving the word up, FILL appends a space to the end of the previous line if that line ends in a space or a text character. It does not append a space if the previous line ends in a word separator other than the space character.

When moving a word up, FILL also moves up any word separators that follow the word, even if these word separators extend beyond the default right margin. Fill does not move up any word separator that would cause the length of the previous line to exceed the buffer’s maximum record size. If the previous line now ends in a space, FILL deletes that space. FILL does not delete more than one such space.

FILL moves any word separators at the beginning of a line up to the previous line. It does this even if the word separators extend beyond the fill right margin.

FILL splits a line into two lines whenever the line contains two or more words and one of the words extends beyond the fill right margin. FILL splits the line at the first character of the first word that contains characters to the right of the fill right margin, unless that word starts at the beginning of the line. In this case, FILL does not split the line.

When operating on a range that does not begin at the first character of a line but does begin left of the fill left margin, FILL splits the line at the first character of the range.

FILL places the cursor at the end of the filled text after completing the previously described tasks.

Signaled Errors

Examples

Syntax

Parameters

None.

Return Value

A string that consists of the data read from the clipboard. Line breaks are indicated by a line-feed character (ASCII (10)).

Description

The GET_CLIPBOARD procedure reads STRING format data from the clipboard and returns a string that contains this data. DECwindows provides a clipboard that lets you move data between applications. Applications can write to the clipboard to replace previous data, and can read from the clipboard to get a copy of existing data. The data in the clipboard can be in multiple format s, but all the information in the clipboard must be written at the same time.

DECTPU provides no clipboard support for applications not written for DECwindows.

Signaled Errors