Document revision date: 19 July 1999

Format

REALIZE_WIDGET (widget)

Parameter

widget

The widget you want DECTPU to realize.

Description

The REALIZE_WIDGET procedure creates a widget window for the specified widget and, if a composite widget, recursively realizes all the widget's managed children. REALIZE_WIDGET interacts with the widget's mapped_when_managed bit. The setting of this bit determines whether or not DECTPU maps the widget window to the display. See the OpenVMS DECwindows Toolkit Routines Reference Manual for a complete explanation.

Signaled Errors

Format

buffer1 := RECOVER_BUFFER (string1 {[[,string2 ]] |[[,buffer2 ]]})

Parameters

string1

The name of the buffer you are trying to recover.

string2

The name of the journal file you want DECTPU to use to recover your buffer. If you did not use SET (JOURNALING) to set a journal file name, in most cases DECTPU will have created the journal file by using its default journal file naming algorithm. If the journal file was named by default, you need not specify a journal file name with RECOVER_BUFFER. If you specified a journal file name by using SET (JOURNALING), use the same name with RECOVER_BUFFER.

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

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

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.

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!]".

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

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

Examples

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

REFRESH 
      

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

PROCEDURE user_repaint 
   ERASE (message_buffer); 
   REFRESH; 
ENDPROCEDURE; 
      

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

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:

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.

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; 
      

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

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

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

Examples

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

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.

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

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

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.

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.

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; 
      

---

Previous

Next

Contents

Index

	privacy and legal statement
6020PRO_022.HTML