DEC Text Processing Utility Reference Manual

Document revision date: 30 March 2001

DEC Text Processing Utility Reference Manual

Contents

Index

The following example positions you to the next occurrence of the text Mark Twain, where Mark and Twain may be separated by any number of spaces, tabs, or line breaks:

#3
PROCEDURE user_find_mark_twain LOCAL pat1, mark_twain; pat1 := "Mark" + (SPANL (" " + ASCII(9)) \| SPANL ("")) + "Twain"; mark_twain := SEARCH_QUIETLY (pat1, FORWARD, NOEXACT); IF mark_twain = 0 THEN MESSAGE ("String not found"); ELSE POSITION (mark_twain); ENDIF; ENDPROCEDURE;

PROCEDURE user_find_mark_twain 
 
   LOCAL pat1, 
         mark_twain; 
 
   pat1 := "Mark" + (SPANL (" " + ASCII(9)) | SPANL ("")) 
           + "Twain"; 
 
   mark_twain := SEARCH_QUIETLY (pat1, FORWARD, NOEXACT); 
   IF mark_twain = 0 
   THEN 
       MESSAGE ("String not found"); 
   ELSE 
       POSITION (mark_twain); 
   ENDIF; 
ENDPROCEDURE;

SPAWN

Format

SPAWN [[ (string, [[ON |OFF |1 |0]])]]

Parameters

string
The command string that you want to be executed in the context of the subprocess that is created with SPAWN.
ON, 1
A keyword that indicates that control is to be returned to DECTPU after the command has been executed. This is the default unless the value specified for the first parameter is the null string.
OFF, 0
A keyword that indicates that you are to be prompted for additional operating system commands after the specified command has been executed. If the value specified for the first parameter is the null string, the default value for the second parameter is OFF.

Description

The SPAWN procedure creates a subprocess that runs the command line interpreter. SPAWN suspends your DECTPU process and starts a subprocess. This built-in procedure is especially useful for running programs and utilities that take control of the screen (these programs cannot be run in a subprocess created with the CREATE_PROCESS) built-in procedure. See the Guide to the DEC Text Processing Utility for a list of restrictions for subprocesses.
If you are using DCL, you can return to your DECTPU session after finishing in a subprocess by using either the DCL ATTACH command or the DCL LOGOUT command. If you use the DCL ATTACH command, the subprocess is available for future use. If you use the DCL LOGOUT command, the subprocess is deleted. When you return to the DECTPU session, the screen is repainted.
If you specify a DCL command as the parameter for SPAWN, the command is executed after the subprocess is created. When the command completes, the subprocess terminates and control is returned to the DECTPU process. If you want to remain at the system prompt, add the OFF keyword as the second parameter.
Subprocesses created with SPAWN give you direct access to the command line interpreter. These subprocesses are different from the subprocesses created with the CREATE_PROCESS built-in procedure. CREATE_PROCESS creates a subprocess within a DECTPU session, and all of the output from the subprocess goes into a buffer.
SPAWN is not a valid built-in in DECwindows DECTPU. However, if you are running non-DECwindows DECTPU in a DECwindows terminal emulator, SPAWN works as described in this section.
SPAWN fails if you are running in an OpenVMS account with the CAPTIVE flag set in the authorization file.
See the description of the ATTACH built-in procedure for information on moving control from one subprocess to another. See the OpenVMS DCL Dictionary for more information on the characteristics of an OpenVMS spawned subprocess.
If the current buffer is mapped to a visible window, the SPAWN built-in procedure 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 buffer.

Signaled Errors

TPU$_TOOMANY	ERROR	Too many arguments passed to the SPAWN built-in.
TPU$_INVPARAM	ERROR	Wrong type of data sent to the SPAWN built-in.
TPU$_REQUIRESTERM	ERROR	SPAWN is not a valid built-in in DECwindows DECTPU.
TPU$_UNKKEYWORD	ERROR	An unknown keyword was used as an argument. Only ON or OFF is allowed.
TPU$_BADKEY	ERROR	An unknown keyword was used as an argument. Only ON or OFF is allowed.
TPU$_CAPTIVE	WARNING	Unable to create a subprocess in a captive account.
TPU$_CREATEFAIL	WARNING	Unable to activate the subprocess.

Example

The following example spawns a subprocess and puts your DECTPU process on hold. The DCL command is executed in the subprocess to show the translation of the logical name SYS$LOGIN, and you are left at the DCL prompt. After completing work in the subprocess, you can return to your DECTPU session by using the DCL ATTACH command or the DCL LOGOUT command.


SPAWN ("SHOW LOGICAL SYS$LOGIN", OFF)

SPLIT_LINE

Format

SPLIT_LINE

Parameters

None.

Description

The SPLIT_LINE procedure breaks the current line before the editing point and creates two lines. The relative screen position of the line you are splitting may change as a result of this procedure. The first line contains any characters to the left of the editing point. The second line contains the rest of the characters. The new line that is created is inserted directly after the former current line.
When you use SPLIT_LINE, the editing point remains on the same character, but that character is now the first character on the newly created line.
If the editing point is not the first character in the line being split, the left margin of the old line is not changed. The new line, which contains the editing point and the characters to the right of the editing point, takes the buffer's left margin as its own left margin.
If the editing point is the first character of a line, SPLIT_LINE creates a blank line where the original line was. The left margin of this blank line is the buffer's left margin. SPLIT_LINE moves the original line, including the editing point, to the line below the blank line. If the original line had a left margin different from the buffer's current left margin, SPLIT_LINE preserves the original line's left margin when it moves the line down.
If the editing point is on a blank line, SPLIT_LINE creates a new blank line below the existing line. The editing point moves to the new blank line. The new blank line receives the buffer's left margin value. If the original blank line had a left margin different from the buffer's current left margin, the original blank line retains its margin.
Using SPLIT_LINE may cause DECTPU to insert padding spaces or blank lines in the buffer. SPLIT_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

TPU$_NOCURRENTBUF	WARNING	You are not positioned in a buffer.
TPU$_NOCACHE	ERROR	There is not enough memory to allocate a new cache.
TPU$_NOTMODIFIABLE	WARNING	You cannot modify an unmodifiable buffer.
TPU$_TOOMANY	ERROR	SPLIT_LINE takes no arguments.

Example

The following example splits a line at the editing point. If the editing point is row 1, column 1, the procedure causes the screen to scroll.


PROCEDURE user_split_line LOCAL old_position, new_position; SPLIT_LINE; IF (CURRENT_ROW = 1) AND (CURRENT_COLUMN = 1) THEN old_position := MARK (NONE); SCROLL (CURRENT_WINDOW, -1); new_position := MARK (NONE); !Make sure we scrolled before doing CURSOR_VERTICAL IF new_position <> old_position THEN CURSOR_VERTICAL (1); ENDIF; ENDIF; ENDPROCEDURE;

PROCEDURE user_split_line 
 
   LOCAL old_position, 
         new_position; 
   SPLIT_LINE; 
   IF (CURRENT_ROW = 1) AND (CURRENT_COLUMN = 1) 
   THEN 
       old_position := MARK (NONE); 
       SCROLL (CURRENT_WINDOW, -1); 
       new_position := MARK (NONE); 
       !Make sure we scrolled before doing CURSOR_VERTICAL 
         IF new_position <> old_position 
         THEN 
             CURSOR_VERTICAL (1); 
         ENDIF; 
   ENDIF; 
ENDPROCEDURE;

STR

Formats

string3 := STR ( {integer1 [[ ,integer2 ]] |keyword |string1})
string3 := STR

( {{buffer |range} [[ [[, string2 ]] [[, ON |, OFF |, 1 |, 0]] ]]})

Parameters

integer1
The integer you want converted to a string.
integer2
The radix (base) you want DECTPU to use when converting the first integer parameter to a string. The default radix is 10. The other allowable values are 8 and 16.
keyword
The keyword whose string representation you want.
string1
Any string. STR now accepts a parameter of type string, so you need not check the type of the parameter you supply to the built-in.
buffer
The buffer whose contents you want returned as a string.
range
The range whose contents you want returned as a string.
string2
A string that specifies how you want line ends represented. The default is the null string. You can use string2 only if you specify a range or buffer as the first parameter. If you want to specify the ON or OFF keyword but do not want to specify string2, you must use a comma before the keyword as a placeholder, as follows:
new_string := STR (old_buffer, , ON);
ON, 1
A keyword that directs DECTPU to insert spaces, thus preserving the white space created by the left margin of each record in the specified buffer or range. If you specify a buffer or range with a left margin greater than 1, the ON keyword directs DECTPU to insert a corresponding number of spaces after the line ends in the resulting string. For example, if the left margin of the specified lines is 10 and you use the ON keyword, DECTPU inserts 9 spaces after each line end in the resulting string. DECTPU does not insert any spaces after line beginnings that do not contain characters. If the first line of a buffer or range starts at the left margin, DECTPU inserts spaces before the text in the first line.
You can use this keyword only if you specify a buffer or range as a parameter.
OFF, 0
A keyword that directs DECTPU to ignore the left margin setting of the records in the specified buffer or range. This is the default. For example, if the left margin of the specified lines is 10 and you use the OFF keyword, DECTPU does not insert any spaces after the line ends in the resulting string.
You can use this keyword only if you specify a buffer or range as a parameter.

Return Value

A string that is the equivalent of the parameter you specify.

Description

The STR procedure returns a string equivalent for an integer, a keyword, a string, or the contents of a range or buffer. If you use the first format, STR returns a string representation of an integer or a keyword. You can then use the variable that contains the returned string in operations that require string data types. For another method of generating a string representation of an integer, see the description of the FAO built-in procedure.
If you use the second format, STR returns a string equivalent for any string or for the contents of a range or buffer.

Signaled Errors

TPU$_TRUNCATE	WARNING	You specified a buffer or range so large that converting it would exceed the maximum length for a string. DECTPU has truncated characters from the returned string.
TPU$_NEEDTOASSIGN	ERROR	STR must appear on the right-hand side of an assignment statement.
TPU$_TOOFEW	ERROR	STR requires at least one argument.
TPU$_TOOMANY	ERROR	STR accepts only two arguments.
TPU$_INVPARAM	ERROR	The argument to STR must be an integer, buffer, string, or range.
TPU$_BADVALUE	ERROR	You specified a value other than 8, 10, or 16 for the radix parameter.

Examples

The following example creates a string that uses the text in the select range. Line breaks are marked with the string CRLF. The white space created by the margin is preserved by inserting spaces after the line breaks.

#1
return_string := STR (SELECT_RANGE, "<CRLF>", ON);

The following example uses the STR built-in procedure to convert the integer variables v1 and v2 to strings so that your row and column position can be displayed in the message area:

#2
PROCEDURE user_display_position v1 := GET_INFO (second_window, "current_column"); MESSAGE ("Column: " + STR (v1)); v2 := GET_INFO (second_window, "current_row"); MESSAGE ("Row: " + STR (v2)); ENDPROCEDURE;

PROCEDURE user_display_position 
 
   v1 := GET_INFO (second_window, "current_column"); 
   MESSAGE ("Column: " + STR (v1)); 
 
   v2 := GET_INFO (second_window, "current_row"); 
   MESSAGE ("Row: " + STR (v2)); 
 
ENDPROCEDURE;

The following example forms a string that uses the text in the range "this_range":

#3
this_string := STR (this_range, "EOL")

In the string, each end-of-line is represented by the letters EOL. For example, suppose the text in "this_range" is as follows:
Sufficient unto the day are the cares thereof
Given the text in "this_range", "this_string" contains the following:
Sufficient unto the dayEOLare the cares thereof
If "this_range" extends to the character after the "f" in "thereof", "this_string" contains the following:
Sufficient unto the dayEOLare the cares thereofEOL

SUBSTR

Format

string2 := SUBSTR ( {buffer |range |string} , integer1 [[ , integer2 ]])

Parameters

buffer
The buffer that contains the substring.
range
The range that contains the substring.
string
The string that contains the substring.
integer1
The character position at which the substring starts. The first character position is 1.
integer2
The number of characters to include in the substring. If you do not specify this parameter, DECTPU sets the returned string's end point to the end of the first parameter.

Return Value

A string that represents a substring of a string or range.

Description

The SUBSTR procedure returns a string that represents a substring of a buffer, range, or string. If you specify a larger number of characters for integer2 than are present in the substring, only the characters present are returned in string2. No error is signaled.

Signaled Errors

TPU$_NEEDTOASSIGN	ERROR	SUBSTR must appear on the right-hand side of an assignment statement.
TPU$_TOOFEW	ERROR	SUBSTR requires three arguments.
TPU$_TOOMANY	ERROR	SUBSTR accepts only three arguments.
TPU$_INVPARAM	ERROR	One of the arguments to SUBSTR is of the wrong type.
TPU$_ARGMISMATCH	ERROR	One of the arguments to SUBSTR is of the wrong type.
TPU$_TRUNCATE	WARNING	You specified a buffer or range so large that returning the requested substring would exceed the maximum length for a string. DECTPU has truncated characters from the returned string.

Examples

The following example returns the string "com" in the variable file_type. The substring starts at the seventh character position (c) and contains three characters (com). If you use a larger number for integer2, for example, 7, the variable file_type still contains "com" and no error is signaled.

#1
file_type := SUBSTR ("login.com", 7, 3)

The following example capitalizes the first character in a string. It does not affect any other characters in the string. It makes use of the fact that SUBSTR returns a null string if the second parameter points past the end of the string.

#2
! Capitalize the first letter in a string. ! PROCEDURE user_initial_cap (my_string) LOCAL first_part_of_string, rest_of_string, first_letter, cur_loc; cur_loc := 1; first_part_of_string := ""; rest_of_string := ""; LOOP first_letter := SUBSTR (my_string, cur_loc, 1); EXITIF first_letter = ""; EXITIF (first_letter >= "a") AND (first_letter <= "z"); EXITIF (first_letter >= "A") AND (first_letter <= "Z"); cur_loc := cur_loc + 1; ENDLOOP; CHANGE_CASE (first_letter, UPPER); first_part_of_string := SUBSTR (my_string, 1, cur_loc - 1); rest_of_string := SUBSTR (my_string, cur_loc + 1, LENGTH (my_string) - cur_loc); my_string := first_part_of_string + first_letter + rest_of_string; ENDPROCEDURE;

! Capitalize the first letter in a string. 
! 
PROCEDURE user_initial_cap (my_string) 
 
LOCAL 
    first_part_of_string, 
    rest_of_string, 
    first_letter, 
    cur_loc; 
 
cur_loc := 1; 
first_part_of_string := ""; 
rest_of_string := ""; 
 
LOOP 
    first_letter := SUBSTR (my_string, cur_loc, 1); 
    EXITIF first_letter = ""; 
    EXITIF (first_letter >= "a") AND (first_letter <= "z"); 
    EXITIF (first_letter >= "A") AND (first_letter <= "Z"); 
    cur_loc := cur_loc + 1; 
ENDLOOP; 
 
CHANGE_CASE (first_letter, UPPER); 
first_part_of_string := SUBSTR (my_string, 1, cur_loc - 1); 
rest_of_string := SUBSTR (my_string, cur_loc + 1, 
                          LENGTH (my_string) - cur_loc); 
 
my_string := first_part_of_string + first_letter 
             + rest_of_string; 
 
ENDPROCEDURE;

TRANSLATE

Format

{buffer1 |range1 |string1} := TRANSLATE ({buffer2 |range2 |string2} , string3, string4 [[, {IN_PLACE |NOT_IN_PLACE}]])

Parameters

buffer2
A buffer in which one or more characters are to be replaced. You cannot use the NOT_IN_PLACE keyword if you specify a buffer for the first parameter.
range2
A range in which one or more characters are to be replaced. You cannot use the NOT_IN_PLACE keyword if you specify a range for the first parameter.
string2
A string in which one or more characters are to be replaced. If a return value is specified, the substitution is performed in the returned string. If you specify IN_PLACE for the third parameter, TRANSLATE makes the specified change to the string specified in the first parameter. If string2 is a constant, IN_PLACE has no effect.
string3
The string of replacement characters.
string4
The literal characters within the text specified by parameter 1 that are to be replaced.
IN_PLACE
A keyword that directs DECTPU to make the indicated change in the buffer, range, or string specified. This is the default.
NOT_IN_PLACE
A keyword that directs DECTPU to leave the specified string unchanged and return a string that is the result of the specified translation. You cannot use NOT_IN_PLACE if the first parameter is specified as a range or buffer. To use NOT_IN_PLACE, you must specify a return value for TRANSLATE.

Return Values

buffer1
A variable of type buffer that points to the buffer that contains the modified text, if you specify a buffer for the first parameter. The variable returned_buffer points to the same buffer pointed to by the buffer variable specified as the first parameter.
range1
A range that contains the modified text, if you specify a range for the first parameter. The returned range spans the same text as the range specified as a parameter, but they are two separate ranges. If you subsequently change or delete one of the ranges, this has no effect on the other range.
string1
A string that contains the modified text, when you specify a string for the first parameter. TRANSLATE can return a string even if you specify IN_PLACE.

Description

The TRANSLATE procedure substitutes one set of specified characters for another set. TRANSLATE returns a value for the translated range or buffer or for the string representation of the translated text. TRANSLATE is based on the Run-Time Library (RTL) routine STR$TRANSLATE. For complete information on STR$TRANSLATE, see the OpenVMS RTL String Manipulation (STR$) Manual.
TRANSLATE searches the text specified by the first parameter for the characters contained in the third parameter. When DECTPU finds the sequence specified by string3, DECTPU substitutes the first character in string2 for the first character in string3, and so forth.
If the translate string, string2, is shorter than the match string, string3, and the number of matched character positions is greater than the number of character positions in the translate string, the translation character is a space.
The IN_PLACE and NOT_IN_PLACE keywords specify whether the source is to be changed. IN_PLACE means that the source is modified; NOT_IN_PLACE indicates that the source is not changed.

Signaled Errors

TPU$_TOOFEW	ERROR	TRANSLATE requires three arguments.
TPU$_TOOMANY	ERROR	TRANSLATE accepts no more than three arguments.
TPU$_ARGMISMATCH	ERROR	One of your arguments to TRANSLATE is of the wrong data type.
TPU$_INVPARAM	ERROR	One of your arguments to TRANSLATE is of the wrong data type.
TPU$_NOTMODIFIABLE	WARNING	You cannot translate text in an unmodifiable buffer.
TPU$_CONTROLC	ERROR	You pressed Ctrl/C during the execution of TRANSLATE.

Examples

The following example replaces any lowercase "i" in second_buffer with an uppercase "I":

#1
TRANSLATE (second_buffer, "I","i")

The following example strips the eighth bit from all characters in the current buffer. You can use this kind of procedure for reading files from systems like TOPS--20 (on which the eighth bit is set) without using the DEC Multinational Character Set.

#2
PROCEDURE user_strip_eighth LOCAL i, ! Loop counter seven, ! ASCII (0) through ASCII (127) eight; ! ASCII (128) through ASCII (255) ! Build translate strings seven := ""; eight := ""; i := 0; LOOP seven := seven + ASCII (i); eight := eight + ASCII (i + 128); i := i + 1; EXITIF i = 128; ENDLOOP; TRANSLATE (CURRENT_BUFFER, seven, eight); ENDPROCEDURE;

PROCEDURE user_strip_eighth 
 
   LOCAL i,          ! Loop counter 
         seven,      ! ASCII (0) through ASCII (127) 
         eight;      ! ASCII (128) through ASCII (255) 
 
! Build translate strings 
 
   seven := ""; 
   eight := ""; 
   i := 0; 
   LOOP 
      seven := seven + ASCII (i); 
      eight := eight + ASCII (i + 128); 
      i := i + 1; 
      EXITIF i = 128; 
   ENDLOOP; 
 
   TRANSLATE (CURRENT_BUFFER, seven, eight); 
 
ENDPROCEDURE;

UNANCHOR

Format

UNANCHOR

Parameters

None.

Description

The UNANCHOR procedure specifies that the next pattern element may match anywhere after the previous pattern element. Usually, when a pattern contains several concatenated or linked pattern elements, the pattern matches only when the text that matches one particular pattern element immediately follows the text that matches the previous pattern element. If UNANCHOR appears between two pattern elements, the text that matches the second pattern element may appear anywhere after the text that matches the first pattern element.
Although UNANCHOR behaves much like a built-in, it is actually a keyword.
For more information on patterns or pattern searching, see the Guide to the DEC Text Processing Utility.

Signaled Errors

UNANCHOR is a keyword and has no completion codes.

Examples

The following example creates a pattern that matches any text beginning with the letter a and ending with the digits 123. Any amount of text may appear between the a and the 123.

#1
pat1 := "a" + UNANCHOR + "123"

Previous Next Contents Index

privacy and legal statement

6020PRO_037.HTML