DEC Text Processing Utility Reference Manual

Updated: 11 December 1998

DEC Text Processing Utility Reference Manual

Contents

Index

The following example deletes embedded carriage-return/line-feed pairs:

#2
PROCEDURE user_remove_crlfs LOCAL crlf, here, cr_range; crlf := ASCII (13) + ASCII (10); here := MARK (NONE); POSITION (BEGINNING_OF (CURRENT_BUFFER)); LOOP cr_range := SEARCH_QUIETLY (crlf, FORWARD, EXACT); EXITIF cr_range = 0; ERASE (cr_range); POSITION (cr_range); ENDLOOP; POSITION (here); ENDPROCEDURE;

PROCEDURE user_remove_crlfs 
 
   LOCAL crlf, 
         here, 
         cr_range; 
 
   crlf := ASCII (13) + ASCII (10); 
   here := MARK (NONE); 
   POSITION (BEGINNING_OF (CURRENT_BUFFER)); 
 
   LOOP 
      cr_range := SEARCH_QUIETLY (crlf, FORWARD, EXACT); 
      EXITIF cr_range = 0; 
      ERASE (cr_range); 
      POSITION (cr_range); 
   ENDLOOP; 
 
   POSITION (here); 
ENDPROCEDURE;

ERASE_CHARACTER

Format

[[string := ]] ERASE_CHARACTER (integer)

Parameter

integer
An expression that evaluates to an integer, which may be signed. The value indicates which characters, and how many of them, are to be erased.

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

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;

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

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;

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;

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

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)

Previous Next Contents Index

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

6020PRO_008.HTML

DEC Text Processing Utility Reference Manual

ERASE_CHARACTER

Format

[[string := ]] ERASE_CHARACTER (integer)

Parameter

integer

Return Value

Description

Signaled Errors

Examples

ERASE_LINE

Format

[[string := ]] ERASE_LINE

Parameters

Return Value

Description

Signaled Errors

Examples

ERROR

Format

keyword := ERROR

Parameters

Return Value

Description

Signaled Errors

Example

ERROR_LINE

Format

integer := ERROR_LINE

Parameters

Return Value

Description

Signaled Errors

Example

ERROR_TEXT

Format

string := ERROR_TEXT

Parameters

Return Value

Description

Signaled Errors

Example

EXECUTE

Format

EXECUTE ( buffer key-name , key-map-list-name, key-map-name learn program range string)

Parameters

buffer

key-name

key-map-list-name

key-map-name

learn

program

range

string

Description

Signaled Errors

Examples

EXIT

Format

EXIT

Parameters

Description

Signaled Errors

EXPAND_NAME

Format

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

Parameters

string1

ALL

KEYWORDS

PROCEDURES

VARIABLES

Return Value

Description

Signaled Errors

Examples

EXECUTE (

buffer
key-name
, key-map-list-name
, key-map-name

learn
program
range
string
)

string2 := EXPAND_NAME (string1

, ALL
, KEYWORDS
, PROCEDURES
, VARIABLES
)