Document revision date: 30 March 2001

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

The following example removes the current character and the nine characters following it and copies them in the string variable take_out_chars. If there are only five characters following the current character, then this statement deletes only the current character and the five following it. It does not also delete characters on the next line.

take_out_chars := ERASE_CHARACTER (10) 
      

The following example deletes the character to the left of the editing point. If the editing point is at the beginning of a line, the procedure appends the current line to the previous line.

! This procedure deletes the character to the 
! left of the current character.  If at the 
! beginning of a line, it appends the current 
! line to the previous line. 
 
PROCEDURE user_delete_key 
 
   LOCAL deleted_char; 
 
   deleted_char := ERASE_CHARACTER (-1); 
 
   IF deleted_char = ""    ! nothing deleted 
   THEN 
       APPEND_LINE; 
   ENDIF; 
ENDPROCEDURE; 
 
      

Format

[[string := ]] ERASE_LINE

Parameters

None.

Return Value

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

The following example removes the current line from the current buffer:

ERASE_LINE 
 
 
 
      

The following example removes the current line from the current buffer and stores the string of characters representing that line in the variable take_out_line:

take_out_line := ERASE_LINE 
      

Format

keyword := ERROR

Parameters

None.

Return Value

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

Signaled Errors

Example

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; 
      

Format

integer := ERROR_LINE

Parameters

None.

Return Value

Description

The ERROR_LINE procedure returns the line number at which the latest error or warning occurs. If a procedure was compiled 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 compile time. In contrast, DECTPU procedures are usually evaluated for a correct parameter count and parameter types at execution.

Signaled Errors

Example

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; 
      

Format

string := ERROR_TEXT

Parameters

None.

Return Value

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

Signaled Errors

Example

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; 
      

Format

EXECUTE ({buffer|key-name[[, key-map-list-name|, key-map-name]] |learn|program|range|string})

Parameters

buffer

The buffer that you want to execute.

key-name

The DECTPU key name for a key or a combination of keys. DECTPU locates and executes the definition bound to the key.

key-map-list-name

The name of the key map list in which the key is defined. This optional parameter is valid only when the first parameter is a key name. If you specify a key map list as the second parameter, DECTPU uses the first definition of the key specified by key_name found in any of the key maps specified by the key map list. If you do not specify any value for the second parameter, DECTPU uses the first definition of the key specified by key_name found in the key map list bound to the current buffer.

key-map-name

The name of the key map in which the key is defined. This optional parameter is valid only when the first parameter is a key name. Use this parameter only if the key specified by the first parameter is defined in the key map specified as the second parameter. If you do not specify any value for the second parameter, DECTPU uses the first definition of the key specified by key_name found in the key map list bound to the current buffer.

learn

The learn sequence that you want to replay.

program

The program that you want to execute.

range

The range that you want to execute.

string

The string that you want to execute.

Description

The EXECUTE procedure does one of the following:

• Executes programs that you have previously compiled
• Compiles and then executes any executable statements in a buffer, a range, or a string
• Replays a learn sequence
• Executes a program bound to a key

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

In the following example, the procedure test returns a program data type. If you execute a buffer or range that contains the following code, DECTPU compiles and executes the procedure test. A program data type is then returned, the program is used as the parameter for the EXECUTE built-in procedure, and the string "abc" is written to the message area.

PROCEDURE test 
 
! After compiling the string 'MESSAGE ("abc")', 
! DECTPU returns a program that is the compiled 
! form of the string. 
 
   RETURN COMPILE ('MESSAGE ("abc")'); 
ENDPROCEDURE; 
 
! The built-in procedure EXECUTE executes the 
! program returned by the procedure "test." 
 
EXECUTE (test); 
 
      

The following example compiles the contents of main_buffer and then executes any executable statements. If you have any text in the main buffer other than DECTPU statements, you get an error message. If there are procedure definitions in main_buffer, they are compiled; they are not executed until you run the procedure (either by entering the procedure name after the appropriate prompt from your interface or by calling the procedure from within another procedure).

EXECUTE (main_buffer) 
      

The following example prompts you for a DECTPU command to execute and then executes the command:

PROCEDURE user_do 
 
   command_string := READ_LINE ("Enter DECTPU command to execute: "); 
   EXECUTE (command_string); 
ENDPROCEDURE; 

 
 
      

The following example executes a command with informational messages turned on, and then turns the informational messages off after the command is executed. You must replace the parameter TPU_COMMAND with the DECTPU statement that you want.

PROCEDURE user_tpu (TPU_COMMAND) 
 
   SET (INFORMATIONAL, ON); 
   EXECUTE (TPU_COMMAND); 
   SET (INFORMATIONAL, OFF); 
ENDPROCEDURE; 
      

Format

EXIT

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

Format

string2 := EXPAND_NAME (string1 {, ALL|, KEYWORDS|, PROCEDURES|, VARIABLES})

Parameters

string1

An expression that evaluates to a string. If the string contains one or more asterisks (*) or percent signs (%), then the string is a wildcard specification of the DECTPU names to match. An asterisk matches zero or more characters and a percent sign matches exactly one character. If the string does not contain any asterisks or percent signs, then the string is the initial substring of a DECTPU name.

ALL

A keyword specifying that you want DECTPU to match all names.

KEYWORDS

A keyword specifying that you want DECTPU to match only keyword names.

PROCEDURES

A keyword specifying that you want DECTPU to match only procedure names.

VARIABLES

A keyword specifying that you want DECTPU to match only global variable names. EXPAND_NAME does not expand the names of local variables.

Return Value

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

In the following example, the assignment statement requests all the keywords whose names are two characters long:

full_name := EXPAND_NAME ("%%", KEYWORDS) 
      

This assignment statement returns the following DECTPU keyword names in the string full_name:

ON UP DO E5 F6 E4 F7 F4 F5 E6 E1 F2 F3 E3 F1 E2 F8 F9

The following example uses the string that you enter as the parameter, and puts the expanded form of a valid DECTPU procedure name that matches the string in the message area. If the initial string matches multiple procedure names, or if it is not a valid DECTPU procedure name, an explanatory message is written to the message area.

PROCEDURE user_quick_parse (abbreviated_name) 
 
   ON_ERROR 
       IF ERROR = TPU$_NONAMES 
       THEN 
           MESSAGE ("No such procedure."); 
       ELSE 
          IF ERROR = TPU$_MULTIPLENAMES 
          THEN 
              MESSAGE ("Ambiguous abbreviation."); 
          ENDIF; 
       ENDIF; 
       RETURN; 
   ENDON_ERROR; 
 
   expanded_name := EXPAND_NAME (abbreviated_name, PROCEDURES); 
   MESSAGE ("The procedure is " + expanded_name + "."); 
ENDPROCEDURE; 
      

Format

string2 := FAO (string1 [[, {integer1|string3} [[, ... {integer_n |string_n } ]] ]])

Parameters

string1

A string that consists of the fixed text of the output string and Formatted ASCII Output (FAO) directives.

Some FAO directives that you can use as part of the string are the following:

!AS	Inserts a string as is
!OL	Converts a longword to octal notation
!XL	Converts a longword to hexadecimal notation
!ZL	Converts a longword to decimal notation
!UL	Converts a longword to decimal notation without adjusting for negative numbers
!SL	Converts a longword to decimal notation with negative numbers converted
!/	Inserts a new line (carriage return/line feed)
!_	Inserts a tab
!}	Inserts a form feed
!!	Inserts an exclamation mark
!%S	Inserts an s if the most recently converted number is not 1
!%T	Inserts the current time if you enter 0 as the parameter (you cannot pass a specific time because DECTPU does not use quadwords)
!%D	Inserts the current date and time if you enter 0 as the parameter (you cannot pass a specific date because DECTPU does not use quadwords)

integer1 ... integer_n

An expression that evaluates to an integer. $FAO uses these integers as arguments to the FAO directives in string2 to form string1.

string3 ... string_n

An expression that evaluates to a string. $FAO uses these strings as arguments to the FAO directives in string2 to form string1.

Return Value

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.

---

Previous

Next

Contents

Index

	privacy and legal statement
6020PRO_008.HTML