Document revision date: 30 March 2001

## DEC Text Processing Utility Reference Manual

Previous | Contents | Index

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

TPU$_TOOFEW | ERROR | ERASE_CHARACTER requires one argument.
TPU$_TOOMANY | ERROR | ERASE_CHARACTER accepts only one argument.
TPU$_INVPARAM | ERROR | The argument to ERASE_CHARACTER must be an integer.
TPU$_NOCURRENTBUF | WARNING | There is no current buffer to erase characters from.
TPU$_NOTMODIFIABLE | WARNING | You cannot modify an unmodifiable buffer.

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

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

#2
    ! 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;

## ERASE_LINE

### Format

> [[string := ]] ERASE_LINE

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

TPU$_TOOMANY | ERROR | ERASE_LINE accepts no arguments.
TPU$_NOTMODIFIABLE | WARNING | You cannot erase a line in an unmodifiable buffer.
TPU$_NOCURRENTBUF | ERROR | You must select a buffer before erasing a line.

### Examples

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

#1
    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:

#2
    take_out_line := ERASE_LINE

## ERROR

### Format

> keyword := ERROR

### 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 compile time. In contrast, 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.

### 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;

## ERROR_LINE

### Format

> integer := ERROR_LINE

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

ERROR is a language element and has no completion codes.

### 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;

## ERROR_TEXT

### Format

> string := ERROR_TEXT

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

### 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;

## EXECUTE

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

TPU$_NODEFINITION | WARNING | There is no definition for this key.
TPU$_REPLAYWARNING | WARNING | Inconsistency during the execution of a learn sequence...sequence is proceeding.
TPU$_REPLAYFAIL | WARNING | Inconsistency during the execution of a learn sequence...execution stopped.
TPU$_RECURLEARN | ERROR | You cannot execute learn sequences recursively.
TPU$_CONTROLC | ERROR | The execution of the command terminated because you pressed Ctrl/C.
TPU$_EXECUTEFAIL | WARNING | Execution of the indicated item halted because it contains an error.
TPU$_COMPILEFAIL | WARNING | Compilation aborted because of syntax errors.
TPU$_ARGMISMATCH | ERROR | A parameter's data type is unsupported.
TPU$_TOOFEW | ERROR | Too few arguments.
TPU$_TOOMANY | ERROR | Too many arguments.
TPU$_NOTDEFINABLE | WARNING | Key cannot be defined.
TPU$_NOCURRENTBUF | WARNING | Key map or key map list not specified, and there is no current buffer.
TPU$_NOKEYMAP | WARNING | Key map or key map list not defined.
TPU$_NOTMODIFIABLE | WARNING | You cannot copy text into an unmodifiable buffer.
TPU$_NODEFINITION | WARNING | Key not defined.

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

#1
    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).

#2
    EXECUTE (main_buffer)

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

#3

    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.

#4
    PROCEDURE user_tpu (TPU_COMMAND)

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

## EXIT

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

TPU$_EXITFAIL | WARNING | The EXIT did not complete successfully because of problems writing modified buffers.
TPU$_TOOMANY | ERROR | EXIT takes no arguments.

## EXPAND_NAME

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

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

TPU$_NONAMES | WARNING | No names were found matching the one requested.
TPU$_MULTIPLENAMES | WARNING | More than one name matching the one requested was found.
TPU$_NEEDTOASSIGN | ERROR | EXPAND_NAME must appear on the right-hand side of an assignment statement.
TPU$_TOOFEW | ERROR | EXPAND_NAME requires two arguments.
TPU$_TOOMANY | ERROR | EXPAND_NAME accepts no more than two arguments.
TPU$_INVPARAM | ERROR | One of the arguments you passed to EXPAND_NAME has the wrong data type.
TPU$_BADKEY | WARNING | You specified an invalid keyword as the second argument.

### Examples

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

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

#2
    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;

## FAO

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

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.

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 6020PRO_008.HTML