DEC Text Processing Utility Reference Manual

Updated: 11 December 1998

DEC Text Processing Utility Reference Manual

Contents

Index

Do not specify any directory name in this string. Specify only the buffer name and the extension, if any.

buffer2

The buffer whose attributes you want applied to the newly created buffer. For more information on using a buffer as a template, see the description of the CREATE_BUFFER built-in procedure.

Return Value

The buffer that contains the recovered text. If the recovery failed, the integer 0 is returned.

Description

The RECOVER_BUFFER procedure reconstructs the work done in the buffer whose name you specify. DECTPU uses the specified buffer name to create a new buffer. It then uses the information in the original buffer's journal file to recover all the changes made to records in the original file. The resulting recovery is written to the newly created buffer.
Do not confuse the RECOVER_BUFFER built-in procedure with the /RECOVER qualifier. You use the /RECOVER qualifier to invoke DECTPU to recover a session or buffer. RECOVER_BUFFER, on the other hand, is used after DECTPU has been invoked. It uses a buffer-change journal file to recover the changes made to a specified buffer.
RECOVER_BUFFER works only with buffer-change journaling; you cannot recover a keystroke journal file with RECOVER_BUFFER.
Only the first parameter (the old buffer name) is required. If you want to specify the third parameter but not the second, you must use a comma as a placeholder, as follows:
RECOVER_BUFFER ("junk.txt", , template_buffer);
The third parameter is optional.
If some text is missing after recovery, the reason might be that the last few changes did not trigger a write operation. For more information on how DECTPU manages write operations to a journal file, see the description of the SET (JOURNALING) built-in procedure.
Buffer-change journaling does not journal changes in buffer attributes (such as modifiability of the buffer or visibility of tabs). Buffer-change journaling tracks only changes to records in the buffer, such as addition, deletion, or modification of a record or changes in a record's attributes.
If you press Ctrl/C during a recovery, DECTPU terminates the recovery, closes the journal file, and deletes the newly created buffer.
If possible, after a successful recovery, DECTPU continues journaling new changes into the journal file that was used during the recovery. However, it is likely that the journal file contains partial records at the end. In this case, DECTPU cannot continue journaling to the same file. DECTPU closes the journal file, marks the buffer unsafe for journaling, and signals an error.

Note
Be careful when using the default naming algorithm while editing multiple buffers. If DECTPU created your journal file as a result of editing multiple buffers with the same or similar names, RECOVER_BUFFER might not recover the buffer you intend.

For more information on the default journal file naming algorithm, see the Guide to the DEC Text Processing Utility. For example, suppose you were editing two buffers, one called TEST! and the other called TEST?. The default journal file naming algorithm creates for each buffer a journal file named TEST_.TPU$JOURNAL. The journal file for the buffer created first has the lower version number. If there were a system interruption while you were editing both buffers, and if the journal file for TEST! had the lower version number, then RECOVER_BUFFER would recover the journal file created for the buffer TEST?.
When you write the contents of a buffer to a file, DECTPU erases the journal file. If you write the contents of the buffer to a file other than the default output file, the journal file contains a pointer to the file to which you last wrote the buffer. For example, if the buffer is called MAIN but you write the contents of the buffer to a file called OPUS.TXT, the journal file contains a pointer to the file OPUS.TXT. OPUS.TXT is known as the "source file" because during a recovery DECTPU uses OPUS.TXT as the source for the contents of the buffer as they were when the write operation was performed.

Caution
If you delete the source file, or any of the files read into the buffer, the buffer becomes unrecoverable.
Similarly, if you have changed the name of the original files required for a recovery, the buffer will be unrecoverable. DECTPU prompts for a new file name if it cannot find the original file. Be careful to specify the correct file name in this case.
You must use the same major version of DECTPU to recover the journal that you used to create it.

Signaled Errors

TPU$_JRNLNOTSAFE	WARNING	The buffer is not safe for journaling.
TPU$_NOTJOURNAL	ERROR	The file specified is not a valid journal file.
TPU$_RECOVERABORT	WARNING	An inconsistency was found between the journal file and the currently executing procedure. Recovery is aborted and the journal file closed.
TPU$_RECOVERFAIL	ERROR	Recovery was terminated abnormally due to journal file inconsistency.
TPU$_RECOVERQUIT	WARNING	You did not specify a valid source file name.

Examples

The following example directs DECTPU to find the buffer-change journal file associated with the original buffer JUNK.TXT and to create a new buffer called JUNK.TXT. Also, it uses the information from the journal file to recover the changes made in the original JUNK.TXT buffer. The results of the recovery are placed in the new JUNK.TXT buffer.

#1
RECOVER_BUFFER ("JUNK.TXT");

The following example creates a default buffer, changes an attribute of the default buffer, and creates a user buffer. The fourth statement turns on buffer-change journaling and designates the file named USER1_JOURNAL.TPU$JOURNAL as the journaling file. At some later point in the session (represented by the ellipsis) the RECOVER_BUFFER statement is used to recover the contents of the old USER1.TXT by using the journal file USER1_JOURNAL.TPU$JOURNAL. The attributes of the defaults buffer are applied to the newly created buffer USER1.TXT. In this case, the new buffer has the end-of-buffer text "[That's all, folks!]".

#2
defaults_buffer := CREATE_BUFFER ("Defaults"); SET (EOB_TEST, defaults_buffer, "[That's all, folks!]"); user_buffer := CREATE_BUFFER ("User1.txt", "", defaults_buffer); SET (JOURNALING, user_buffer, ON, "user1_journal.tpu$journal"); . . . RECOVER_BUFFER ("User1.txt", "user1_journal.tpu$journal", defaults_buffer);

defaults_buffer := CREATE_BUFFER ("Defaults"); 
 
SET (EOB_TEST, defaults_buffer, "[That's all, folks!]"); 
 
user_buffer := CREATE_BUFFER ("User1.txt", "", defaults_buffer); 
 
SET (JOURNALING, user_buffer, ON, "user1_journal.tpu$journal"); 
    . 
    . 
    . 
RECOVER_BUFFER ("User1.txt", "user1_journal.tpu$journal", 
                 defaults_buffer);

REFRESH

Format

REFRESH

Parameters

None.

Description

The REFRESH procedure repaints the whole screen. REFRESH erases any extraneous characters, such as those caused by noise on a communication line, and repositions the text so that the screen represents the last known state of the editing context.
REFRESH causes a redrawing of every line of every window that is mapped to the screen. The prompt area is erased. This built-in procedure causes the screen to change immediately. Even if REFRESH is issued from within a procedure, the action takes place immediately; DECTPU does not wait until the entire procedure is completed to execute REFRESH.
If screen updating is disabled when DECTPU executes the REFRESH command, DECTPU performs the refresh operation when updating is enabled again.
DECTPU reissues escape sequences as appropriate to do any of the following:

To set the width of the terminal
To set the scrolling region
To set the keypad to applications mode
To set the video attributes to a known state
To clear the screen of a Digital-supported terminal
To reset the nonalphanumeric character sets

REFRESH repaints the whole screen. See UPDATE for a description of how to update a single window to make it reflect the current state of its associated buffer. If you want to update every visible window without erasing the screen, use the UPDATE (ALL) built-in procedure.
See Appendix C for an explanation of how the screen is updated under various circumstances.

Signaled Error

TPU$_TOOMANY

ERROR

REFRESH takes no parameters.

Examples

The following example causes the screen manager to repaint the whole screen so that it reflects the current internal state of the editor:

#1
REFRESH

The following example removes the contents of the message buffer and then repaints the whole screen:

#2
PROCEDURE user_repaint ERASE (message_buffer); REFRESH; ENDPROCEDURE;

REMAIN

Format

REMAIN

Parameters

None.

Description

The REMAIN procedure specifies that all characters from the current position to the end of the line should be included in a pattern. When used as part of a complex pattern or as an argument to SEARCH, REMAIN matches the rest of the characters on a line. REMAIN matches successfully even if there are no more characters on the line.
Although REMAIN behaves much like a built-in, it is actually a keyword.

Signaled Errors

REMAIN is a keyword and has no completion codes.

Examples

The following example stores in the variable pat1 a pattern that matches all lines that have an exclamation point at the beginning of the line:

#1
pat1 := LINE_BEGIN + "!" + REMAIN

The following example removes all comments from the current buffer. It does not correctly handle quoted strings that contain exclamation points.

#2
PROCEDURE remove_comments LOCAL pat1, here, comment_range; here := MARK (NONE); ! Remember our location pat1 := "!" + REMAIN; POSITION (BEGINNING_OF (CURRENT_BUFFER)); LOOP comment_range := SEARCH_QUIETLY (pat1, FORWARD); EXITIF comment_range = 0; ERASE (comment_range); POSITION (comment_range); ENDLOOP; POSITION (here); ENDPROCEDURE;

PROCEDURE remove_comments 
 
   LOCAL pat1, 
         here, 
         comment_range; 
 
   here := MARK (NONE);   ! Remember our location 
   pat1 := "!" + REMAIN; 
 
   POSITION (BEGINNING_OF (CURRENT_BUFFER)); 
   LOOP 
      comment_range := SEARCH_QUIETLY (pat1, FORWARD); 
      EXITIF comment_range = 0; 
 
      ERASE (comment_range); 
      POSITION (comment_range); 
   ENDLOOP; 
 
   POSITION (here); 
ENDPROCEDURE;

REMOVE_KEY_MAP

Format

REMOVE_KEY_MAP (string1, string2 [[, ALL ]])

Parameters

string1
A quoted string, or a variable name representing a string constant, that specifies the name of the key map list containing the key map to be removed.
string2
A quoted string, or a variable name representing a string constant, that specifies the name of the key map to be removed from the key map list.
ALL
This keyword is an optional argument. It specifies that all the key maps with the name specified by string2 in the key map list are to be removed.

Description

The REMOVE_KEY_MAP procedure removes one or more key maps from a key map list. If the optional ALL keyword is specified, all of the key maps with the specified name in the key map list are removed from the list; otherwise, only the first entry with the specified name is removed.

Signaled Errors

TPU$_NOKEYMAP	WARNING	You specified an argument that is not a defined key map.
TPU$_NOKEYMAPLIST	WARNING	You specified an argument that is not a defined key map list.
TPU$_KEYMAPNOTFND	WARNING	The key map you specified is not found.
TPU$_EMPTYKMLIST	WARNING	The key map list you specified contains no key maps.
TPU$_TOOFEW	ERROR	Too few arguments passed to the REMOVE_KEY_MAP built-in.
TPU$_TOOMANY	ERROR	Too many arguments passed to the REMOVE_KEY_MAP built-in.
TPU$_INVPARAM	ERROR	Wrong type of data sent to the REMOVE_KEY_MAP built-in.
TPU$_UNKKEYWORD	ERROR	An unknown keyword was used as an argument. Only the ALL keyword is allowed.
TPU$_BADKEY	ERROR	An unknown keyword was used as an argument. Only the ALL keyword is allowed.

Example

In the following example, a key map list named KEYMAP_LIST is created. The call to SHOW (KEY_MAP_LISTS) shows that the key map list contains three key maps: KEYMAP_1, KEYMAP_2, and KEYMAP_1 again. After the call to REMOVE_KEY_MAP, the call to SHOW (KEY_MAP_LISTS) shows that the key map list contains only KEYMAP_2.


user$keymap_1 := CREATE_KEY_MAP ("keymap_1"); user$keymap_2 := CREATE_KEY_MAP ("keymap_2"); user$keymap_list := CREATE_KEY_MAP_LIST ("keymap_list", user$keymap_1, user$keymap_2); ADD_KEY_MAP (user$keymap_list, "last", user$keymap_1); . . . SHOW (KEY_MAP_LISTS); . . . REMOVE_KEY_MAP (user$keymap_list, user$keymap_1, ALL); . . . SHOW (KEY_MAP_LISTS);

user$keymap_1 := CREATE_KEY_MAP ("keymap_1"); 
 
user$keymap_2 := CREATE_KEY_MAP ("keymap_2"); 
 
user$keymap_list := CREATE_KEY_MAP_LIST ("keymap_list", user$keymap_1, 
                                         user$keymap_2); 
 
ADD_KEY_MAP (user$keymap_list, "last", user$keymap_1); 
     . 
     . 
     . 
SHOW (KEY_MAP_LISTS); 
     . 
     . 
     . 
REMOVE_KEY_MAP (user$keymap_list, user$keymap_1, ALL); 
     . 
     . 
     . 
SHOW (KEY_MAP_LISTS);

RETURN

Format

RETURN [[ expression ]]

RETURN is a DECTPU language element. It does not take parameters. However, it is optionally followed by a DECTPU expression.

Parameter

expression
This expression can be any DECTPU expression, variable, or built-in. It specifies what the current procedure should return to its caller. If not specified, RETURN returns 0. The expression can be enclosed within optional parentheses.

Description

The RETURN procedure is a DECTPU language element; it returns control from the current procedure to its caller, optionally specifying the value the current procedure returns to the caller.
RETURN 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

RETURN is a language element and signals no errors or warnings.

Examples

The following example erases the message buffer. If the current buffer is the message buffer, it returns without erasing it.

#1
PROCEDURE user_erase_message_buffer IF CURRENT_BUFFER = message_buffer THEN RETURN; ENDIF; ERASE (message_buffer); ENDPROCEDURE;

The following example searches for a string. If it does not find the string, it returns the string "String not found"; otherwise, it returns the range containing the found string.

#2
PROCEDURE user_find_string (look_for) ON_ERROR RETURN "String not found"; ENDON_ERROR; RETURN SEARCH (look_for, FORWARD); ENDPROCEDURE;

SAVE

Format

SAVE (string1 [[,"NO_DEBUG_NAMES"]]
[[,"NO_PROCEDURE_NAMES"]]
[[,"IDENT", string2]])

Parameters

string1
A string that is a valid file specification. If you supply only a file name, DECTPU uses the current device and directory, not necessarily the SYS$LOGIN device and directory, in the file specification.
"NO_DEBUG_NAMES"
A string that prevents DECTPU from writing debugging information to the section file. When you use "NO_DEBUG_NAMES", DECTPU does not write procedure parameter names or local variable names. You can reduce the size of the section file by specifying this string. Do not specify this string if you intend to use the DECTPU debugger on the section file.
"NO_PROCEDURE_NAMES"
A string, or a variable or constant name representing this string, that prevents DECTPU from writing procedure names to the section file. You can reduce the size of the section file by specifying this string. However, the procedure names are required to display a meaningful traceback when an error occurs. Therefore, do not specify this string if you want to use the application created by the section file with the TRACEBACK or LINE_NUMBER function set to ON.
"IDENT"
A string that specifies that you want to assign an identifying string, such as a version number, to the section file.
string2
The string (usually a version number) that you want to assign to the section file.

Description

The SAVE procedure writes the binary forms of all currently defined procedures, variables, key definitions, key maps, and key map lists to the section file you specify. Use SAVE to create DECTPU section files. If you are adding to an existing section file, the new section file contains all of the items from the original section file and the new items from the current editing session.
Section files enable DECTPU interfaces to start up quickly because they contain the following items in binary form:

All compiled PROCEDURE...ENDPROCEDURE statements
Every variable created (only the variable's name is saved, not its contents)
Every key definition that binds a statement, procedure, program, or learn sequence to a key, including the comments that you add to key definitions
Every key map and key map list created
All defined constants

When you use the SAVE built-in procedure during an editing session to add items to an existing section file, SAVE does not keep items that were established interactively with the SET built-in procedure (for example, margin settings for buffers, or setting the editor's shift key to something other than the PF1 key).
If you do not specify a device and directory in the string parameter, DECTPU uses your current device and directory. The default file type is TPU$SECTION.
File backups are automatically provided by RMS.
When you use the SAVE built-in procedure, informational messages are generated for any undefined procedures or ambiguous symbols as they are written to the section file. If the display of informational messages has been disabled, these messages are not displayed.

Signaled Errors

TPU$_SAVEERROR	ERROR	The section cannot be created because of errors in the context being saved.
TPU$_TOOFEW	ERROR	Too few arguments passed to the SAVE built-in.
TPU$_TOOMANY	ERROR	Too many arguments passed to the SAVE built-in.
TPU$_INVPARAM	ERROR	Wrong type of data sent to the SAVE built-in.
TPU$_SECTUNDEFPROC	WARNING	Undefined procedures or ambiguous symbols were found while the section file was being written.
TPU$_BADSYMTAB	ERROR	DECTPU's symbol tables are inconsistent.
TPU$_SAVEUNDEFPROC	INFORMATIONAL	An undefined procedure is being written to the section file.
TPU$_SAVEAMBIGSYM	INFORMATIONAL	An ambiguous symbol is being written to the section file.

Examples

The following example procedure, issued just before exiting from the editor, adds all of the procedure definitions, key definitions, and variables from your current editing session to the OpenVMS section file with which you invoked DECTPU. The new file that you specify, SYS$LOGIN:mysection.TPU$SECTION, contains initialization items from the original section file and from your editing session.

#1
SAVE ("SYS$LOGIN:mysection.TPU$SECTION")

To invoke DECTPU with the new section file, enter the following command at the DCL level:
$ EDIT/TPU/SECTION=sys$login:mysection
The following example shows how you can use SAVE in a command file to extend an application. The first procedure moves the cursor to the beginning of the next paragraph. The second procedure defines a shift key and binds the procedure eve_next_paragraph to the period key on the keypad. The SAVE statement directs DECTPU to write the binary form of eve_next_paragraph and the key definition to a section file called MY_SECTION.TPU$SECTION. The second and third parameters to the SAVE statement direct DECTPU to assign the string "V1.5" to the section file. The QUIT statement terminates the DECTPU session.

#2
PROCEDURE eve_next_paragraph LOCAL pat1, the_range; pat1 := LINE_BEGIN + LINE_BEGIN + ARB (1); the_range := SEARCH_QUIETLY (pat1, FORWARD, EXACT); IF the_range <> 0 THEN POSITION (END_OF (the_range)); ENDIF; ENDPROCEDURE; PROCEDURE tpu$local_init SET (SHIFT_KEY, KP0); DEFINE_KEY ("eve_next_paragraph", PERIOD, "Next Para"); ENDPROCEDURE; SAVE ("my_section", "ident", "V1.5"); QUIT;

PROCEDURE eve_next_paragraph 
 
   LOCAL pat1, 
         the_range; 
 
   pat1 := LINE_BEGIN + LINE_BEGIN + ARB (1); 
   the_range := SEARCH_QUIETLY (pat1, FORWARD, EXACT); 
 
   IF the_range <> 0 
   THEN 
       POSITION (END_OF (the_range)); 
   ENDIF; 
ENDPROCEDURE; 
 
PROCEDURE tpu$local_init 
   SET (SHIFT_KEY, KP0); 
   DEFINE_KEY ("eve_next_paragraph", PERIOD, "Next Para"); 
ENDPROCEDURE; 
 
SAVE ("my_section", "ident", "V1.5"); 
QUIT;

SCAN

Format

pattern := SCAN (

buffer
range
string
[[,

FORWARD
REVERSE
]])

Parameters

buffer
An expression that evaluates to a buffer. SCAN does not match any of the characters that appear in the buffer.
range
An expression that evaluates to a range. SCAN does not match any of the characters that appear in the range.
string
An expression that evaluates to a string. SCAN does not match any of the characters that appear in the string.
FORWARD
A keyword that directs DECTPU to match characters in the forward direction. This is the default.
REVERSE
A keyword that directs DECTPU to match characters as follows: first, match characters in the forward direction until DECTPU finds a character that is a member of the set of characters. Next, return to the first character matched and start matching characters in the reverse direction until DECTPU finds a character that is in the set.
You can specify REVERSE only if you are using SCAN in the first element of a pattern being used in a reverse search. In all other contexts, specifying REVERSE has no effect.
The behavior enabled by REVERSE allows an alternate form of reverse search. By default, a reverse search stops as soon as a successful match occurs, even if there might have been a longer successful match in the reverse direction. By specifying REVERSE, you direct DECTPU not to stop matching in either direction until it has matched as many characters as possible.

Return Value

A pattern matching only characters that do not appear in the buffer, range, or string used as the parameter.

Description

The SCAN procedure returns a pattern that matches only characters that do not appear in the string, buffer, or range used as its parameter. SCAN matches as many characters as possible, stopping only if it finds a character that is present in its parameter or if it reaches the end of a line. If SCAN is part of a larger pattern, SCAN does not match a character if doing so prevents the rest of the pattern from matching.
SCAN does not cross line boundaries. To match a string of characters that may cross one or more line boundaries, use SCANL.

Signaled Errors

TPU$_NEEDTOASSIGN	ERROR	SCAN must appear on the right-hand side of an assignment statement.
TPU$_TOOFEW	ERROR	SCAN requires at least one argument.
TPU$_TOOMANY	ERROR	SCAN accepts no more than one argument.
TPU$_ARGMISMATCH	ERROR	SCAN was given an argument of the wrong type.
TPU$_CONTROLC	ERROR	You pressed Ctrl/C during the execution of SCAN.

Examples

The following example stores a pattern that matches the longest string of characters that does not contain a, b, or c in pat1:

#1
pat1 := SCAN ("abc")

Previous Next Contents Index

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

6020PRO_022.HTML

DEC Text Processing Utility Reference Manual

buffer2

Return Value

Description

Signaled Errors

Examples

REFRESH

Format

REFRESH

Parameters

Description

Signaled Error

Examples

REMAIN

Format

REMAIN

Parameters

Description

Signaled Errors

Examples

REMOVE_KEY_MAP

Format

REMOVE_KEY_MAP (string1, string2 [[, ALL ]])

Parameters

string1

string2

ALL

Description

Signaled Errors

Example

RETURN

Format

RETURN [[ expression ]]

Parameter

expression

Description

Signaled Errors

Examples

SAVE

Format

SAVE (string1 [[,"NO_DEBUG_NAMES"]] [[,"NO_PROCEDURE_NAMES"]] [[,"IDENT", string2]])

Parameters

string1

"NO_DEBUG_NAMES"

"NO_PROCEDURE_NAMES"

"IDENT"

string2

Description

Signaled Errors

Examples

SCAN

Format

pattern := SCAN ( buffer range string [[, FORWARD REVERSE ]])

Parameters

buffer

range

string

FORWARD

REVERSE

Return Value

Description

Signaled Errors

Examples

SAVE (string1 [[,"NO_DEBUG_NAMES"]]
[[,"NO_PROCEDURE_NAMES"]]
[[,"IDENT", string2]])

pattern := SCAN (

buffer
range
string
[[,

FORWARD
REVERSE
]])