Document revision date: 30 March 2001

This chapter describes the DECTPU built-in procedures. The discussion of each procedure is divided, as applicable, into the following parts:

• Format
• Parameters
• Description
• Signaled Errors (listing the warnings and errors signaled, if applicable)
• Examples

This section lists the DECTPU built-in procedures in alphabetical order and describes each in detail.

The descriptions of built-in procedures that return useful values show a return value in the format section. The built-in procedure descriptions that do not show a return value in the format section either return 0 or signal TPU$_NORETURNVALUE, "Built-in does not return a value."

Format

ABORT

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 compile time. In contrast, DECTPU procedures are usually evaluated for a correct parameter count and parameter types at execution time.

Signaled Errors

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; 
      

Format

ADD_KEY_MAP (key-map-list-name, {"first",|"last",} key-map-name
[[,... ]])

Parameters

key-map-list-name

A string that specifies the name of the key map list.

"first"

A string that directs DECTPU to add the key map to the beginning of the key map list. In cases where a key is defined in multiple key maps, the first definition found for that key in any of the key maps in a key map list is used.

"last"

A string that directs DECTPU to add the key map to the end of the key map list. In cases where a key is defined in multiple key maps, the first definition found for that key in any of the key maps in a key map list is used.

key-map-name

A string that specifies the name of the key map to be added to the key map list. You can specify more than one key map. Key maps are added to the key map list in the order specified. The order of a key map in a key map list determines precedence among any conflicting key definitions.

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

The following example adds the default key map TPU$KEY_MAP to the default key map list, TPU$KEY_MAP_LIST. Usually (except in the EVE editor) TPU$KEY_MAP is a member of the default key map list.

ADD_KEY_MAP ("TPU$KEY_MAP_LIST", "last", "TPU$KEY_MAP"); 
 
      

The following example creates a key map called HELP_KEYS and adds it to the beginning of the default key map list, TPU$KEY_MAP_LIST. Key definitions in the new key map are invoked over definitions in the key maps already in the list.

help_keys := CREATE_KEY_MAP ("help_keys"); 
ADD_KEY_MAP ("TPU$KEY_MAP_LIST", "first", help_keys); 
      

Format

ADJUST_WINDOW (window, integer1, integer2)

Parameters

window

The window whose size or location you want to change. The window that you specify becomes the current window, and the buffer mapped to that window becomes the current buffer.

integer1

The signed integer value that you add to the screen line number at the top of the window.

integer2

The signed integer value that you add to the screen line number at the bottom of the window.

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

Figure 2-1 Screen Layout Before Using ADJUST_WINDOW

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.

Figure 2-2 Screen Layout After Using ADJUST_WINDOW

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

The following example reduces the current window by removing five lines from the top of the window. If the top line of the window is screen line number 11, this statement changes the top line of the window to screen line number 16. (If the bottom line of the window is less than screen line number 16, DECTPU signals an error.)

ADJUST_WINDOW (CURRENT_WINDOW, +5, 0) 
      

The following example removes five lines from the top of a window and puts a help window in their place:

PROCEDURE user_display_help 
   top_of_window := GET_INFO (CURRENT_WINDOW, "VISIBLE_TOP"); 
       ! 
       ! Remove the top five lines from the current window 
       ! and replace them with a help window 
       ! 
   ADJUST_WINDOW (CURRENT_WINDOW, +5, 0); 
   example_window := CREATE_WINDOW (top_of_window, 5, ON); 
   example_buffer := CREATE_BUFFER ("EXAMPLE", 
                                    "sys$login:template.txt"); 
   MAP (example_window, example_buffer); 
ENDPROCEDURE; 
      

Format

ANCHOR

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

Examples

The following example creates a pattern that matches the string a123. Because ANCHOR appears as the first element of the pattern, SEARCH will find a123 only if the string appears at the starting position for the search.

pat1 := ANCHOR + "a123"; 
 

 
      

The following example starts at the beginning of a buffer and searches forward, removing all comments that begin in column 1. The ANCHOR keyword in this example ties the search to the first character of a line (the current character). This prevents the search function from finding and removing exclamation points in the middle of a line (for example, in the FAO directive !AS).

PROCEDURE user_remove_comments 
   LOCAL pat1, 
         number_removed, 
         end_mark; 
   pat1 := ANCHOR + "!"; 
   number_removed := 0; 
   end_mark := END_OF (CURRENT_BUFFER); 
 
   POSITION (BEGINNING_OF (CURRENT_BUFFER)); 
   LOOP 
      EXITIF MARK (NONE) = end_mark; 
      r1 := SEARCH_QUIETLY (pat1, FORWARD); 
      IF r1 <> 0 
         THEN                    ! comment found so erase it 
            ERASE_LINE; 
            number_removed := number_removed + 1; 
      ENDIF; 
      MOVE_VERTICAL (1); ! move to the next line 
   ENDLOOP; 
   MESSAGE (FAO ("!ZL comment!%S removed.", number_removed)); 
ENDPROCEDURE; 
      

Format

) pattern := ANY ({buffer|range|string}) [[, integer1 ]]

Parameters

buffer

An expression that evaluates to a buffer. ANY matches any of the characters in the resulting buffer.

range

An expression that evaluates to a range. ANY matches any of the characters in the resulting range.

string

An expression that evaluates to a string. ANY matches any of the characters in the resulting string.

integer1

A value that indicates how many contiguous characters ANY matches. The default value for this integer is 1.

Return Value

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

The following example creates a pattern that matches any one of the characters h, i, j, k, and l:

pat1 := ANY ("hijkl") 
      

The following example creates a pattern that matches any one of the characters a, b, c, x, and y:

a_buf := CREATE_BUFFER ("new buffer"); 
POSITION (a_buf); 
COPY_TEXT ("xy"); 
SPLIT_LINE; 
COPY_TEXT ("abc"); 
pat1 := ANY (a_buf); 
 
      

The following example finds an ENDPROCEDURE statement that starts in column 1 and moves the editing point to the end of the statement:

PROCEDURE user_find_endprocedure 
   LOCAL  endprocedure_pattern, 
       search_range; 
   endprocedure_pattern := (LINE_BEGIN + "ENDPROCEDURE") + 
                           (LINE_END | ANY (";! " + ASCII (9))); 
   search_range := SEARCH_QUIETLY (endprocedure_pattern, FORWARD); 
   IF search_range = 0 
      THEN 
         MESSAGE ("Endprocedure statement not found"); 
      ELSE 
         POSITION (END_OF (search_range)); 
   ENDIF; 
ENDPROCEDURE; 
      

Format

APPEND_LINE

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

The following example adds the current line to the end of the previous line:

APPEND_LINE 
      

The following example deletes the character to the left of the cursor. If you are at the beginning of a line, the procedure appends the current line to the end of the previous line. The procedure works correctly even if the window is shifted.

! The following procedure deletes the character 
! to the left of the cursor.  If the cursor is at the 
! beginning of a line, it appends the current line 
! to the end of the previous line. 
! 
PROCEDURE user_delete_char 
   IF CURRENT_OFFSET = 0 
      THEN 
         APPEND_LINE; 
      ELSE 
         ERASE_CHARACTER (-1); 
   ENDIF; 
ENDPROCEDURE; 
      

You can bind this procedure to the delete key with the following statement:

DEFINE_KEY ("user_delete_char", DEL_KEY);

Format

pattern := ARB (integer)

Parameter

integer

The number of characters in the pattern. This integer must be positive.

Return Value

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

	privacy and legal statement
6020PRO_001.HTML