HP OpenVMS Systems Documentation
Guide to the DEC Text Processing Utility
1.5 Terminals Supported by DECTPU
DECTPU runs on all VAX and Alpha computers, and supports screen-oriented editing on the Compaq VT400-, VT300-, VT200-, and VT100-series terminals, as well as on other video display terminals that respond to ANSI control functions.
Optimum screen-oriented editing performance occurs when you run DECTPU from VT400-series, VT300-series, VT220-series, and VT100-series terminals. Some video terminal hardware does not have optimum DECTPU performance. See Appendix B for a list of hardware characteristics that may adversely affect DECTPU's performance.
Although you cannot use the screen-oriented features of DECTPU on a
VT52 terminal, hardcopy terminal, or foreign terminal that does not
respond to ANSI control functions, you can run DECTPU on these
terminals with line-mode editing. For information on how to implement
this style of editing, see the description of the /NODISPLAY qualifier
in Chapter 2 and the sample line-mode editor in Appendix A.
The suggested path for learning to use DECTPU is to first read the documentation describing EVE if you are not familiar with that editor. The DECTPU/EVE documentation contains both reference and tutorial material for new EVE users. It also contains material for more experienced users of text editors and explains how to use DECTPU to extend the EVE interface.
When you are familiar with EVE, you may want to extend or customize it. Study the source code to see which procedures, variables, and key definitions the editor uses. Then write DECTPU procedures to implement your extensions. Make sure that the DECTPU procedures you write do not conflict with procedures or variables that EVE uses.
To help you learn about the DECTPU language, this manual contains examples of DECTPU procedures and programs. Many of the descriptions of the built-in procedures in the DEC Text Processing Utility Reference Manual also have a short sample procedure that uses the built-in procedure in an appropriate context.
Appendix A contains longer sample procedures that perform useful editing tasks. These procedures are merely samples; you can adapt them for your own use. You must substitute an appropriate value for any item in lowercase in sample procedures and syntax examples.
For more information on designing your own DECTPU-based editor or application rather than using EVE, see Chapter 5.
$ EDIT/TPU text_file.lis
This command opens TEXT_FILE.LIS for editing.
If you are using the EVE editor, Compaq suggests that you create a symbol like the following one to simplify invoking EVE:
$ EVE == "EDIT/TPU"
When you invoke DECTPU with the preceding command, you are usually placed in EVE, the default editor. However, you should check that your system manager has not overridden this default.
You can specify multiple input files on the DECTPU command line. The
files must be separated by commas. The maximum number of files you can
specify is 10. For the ambiguous file names, EVE displays a warning
2.1.1 Default File Specifications
Table 2-1 lists the default TPU and EVE file specifications on OpenVMS systems.
|File||OpenVMS File Specification|
|Motif Resource||SYS$LIBRARY:.UID 1|
|Application defaults||DECW$USER_DEFAULTS:.DAT 2|
|EVE Motif resource||SYS$SHARE:EVE$WIDGETS.UID 3|
OpenVMS system managers should note that the OpenVMS systemwide logical
name is defined as TPU$SECTION to point to EVE$SECTION.TPU$SECTION. You
can modify this logical to use a different default editing interface.
2.1.2 Startup Files
Command files and section files can create or customize a DECTPU editor or application. Initialization files can customize EVE or other layered applications by using EVE or other application-specific commands, settings, and key bindings.
A command file is a file that contains DECTPU source code. A command file has the file type .TPU and is used with the DECTPU /COMMAND=filespec qualifier. DECTPU tries to read a command file unless you specify /NOCOMMAND. The default command file is the file called TPU$COMMAND.TPU in your current directory, if such a file exists. You can specify a different file by defining the logical name TPU$COMMAND.
A section file is the compiled form of DECTPU source code. It is a binary file that has the default file type .TPU$SECTION. It is used with the qualifier /SECTION=filespec. The default section file is TPU$SECTION.TPU$SECTION in the area SYS$SHARE. The systemwide logical name TPU$SECTION is defined as EVE$SECTION. This definition causes the EVE editor to be invoked by default when you use the DCL command EDIT/TPU. You must specify a different section file (for example, /SECTION= my_section_file) or /NOSECTION if you do not want to use the EVE interface.
When you invoke DECTPU with the /NOSECTION qualifier, DECTPU does not use any binary file to provide an interface. Even the Return and Delete keys are not defined. Use /NOSECTION when you are running a standalone command file or when you are creating a new section file and do not want the procedures, variables, and definitions from an existing section file to be included. See Section 2.6 and Chapter 5 for more information on /NOSECTION.
An initialization file contains commands for a DECTPU-based application. For example, an initialization file for EVE can contain commands that define keys or set margins. Initialization files are easy to create, but they cause DECTPU to start up somewhat more slowly than section and command files do. To invoke an initialization file, use the /INITIALIZATION qualifier. For more information on using initialization files, see Chapter 5.
You can use either a command file or a section file, or both, to customize or extend an existing interface. Generally, you use a command file for minor customization of an interface. Because startup time is faster with a section file, you should use a section file when the customization is lengthy or complex, or when you are creating an interface that is not layered on an existing editor or application. You can use an initialization file only if your application supports the use of such a file.
$ DIRECTORY SYS$EXAMPLES:EVE$*.TPU
If you cannot find these files on your system, see your system manager.
There are two reasons that you might want to invoke DECTPU from a command procedure:
The following sections explain how to do this.
2.2.1 Setting Up a Special Editing Environment
You can run DECTPU with a special editing environment by writing a DCL command procedure that first establishes the environment that you want and then invokes DECTPU. In such a command procedure, you must define SYS$INPUT to have the same value as SYS$COMMAND because DECTPU signals an error if SYS$INPUT is not defined as the terminal. To prevent such an error, place the following statement in the command procedure setting up the environment:
$ DEFINE/USER SYS$INPUT SYS$COMMAND
Example 2-1 shows a DCL command procedure that "remembers" the last file that you were editing and uses it as the input file for DECTPU. When you edit a file, the file name you specify is saved in the DCL symbol last_file_edited. If you do not specify a file name when you invoke the editor the next time, the file name from the previous session is used.
|Example 2-1 DCL Command Procedure FILENAME.COM|
$ IF P1 .NES. "" THEN last_file_edited == P1 $ WRITE SYS$OUTPUT "*** ''last_file_edited' ***" $ DEFINE/USER SYS$INPUT SYS$COMMAND $ EDIT/TPU/COMMAND=DISK$:[USER]TPU$COMMAND.TPU 'last_file_edited'
Example 2-2 establishes an environment that specifies tab stop settings for FORTRAN programs.
|Example 2-2 DCL Command Procedure FORTRAN_TS.COM|
$ IF P1 .EQS. "" THEN GOTO REGULAR_INVOKE $ last_file_edited == P1 $ FTN_TEST = F$FILE_ATTRIBUTES (last_file_edited,"RAT") $ IF FTN_TEST .NES. "FTN" THEN GOTO REGULAR_INVOKE $ FTN_INVOKE: $ DEFINE/USER SYS$INPUT SYS$COMMAND $ EDIT/TPU/COMMAND=FTNTABS 'last_file_edited' $ GOTO TPU_DONE $ REGULAR_INVOKE: $ DEFINE/USER SYS$INPUT SYS$COMMAND $ EDIT/TPU/ 'last_file_edited' $ TPU_DONE:
In some situations, you may want to put all of your editing commands in a file and have them read from the file rather than entering the commands interactively. You may also want DECTPU to perform the edits without displaying them on the screen. You can do this type of editing from a batch job; or, if you want to see the results of the editing session displayed on your screen, you can do this type of editing from a DCL command procedure. Even though the edits are not displayed on your screen as they are being made, your terminal is not free while the command procedure is executing.
Example 2-3 shows a DCL command procedure named INVISIBLE_TPU.COM, which contains a single command line that uses the following qualifiers to invoke DECTPU:
|Example 2-3 DCL Command Procedure INVISIBLE_TPU.COM|
! This command procedure invokes DECTPU without an editor. ! The file GSR.TPU contains the edits to be made. ! Specify the file to which you want the edits made as p1. ! $ EDIT/TPU/NOSECTION/COMMAND=gsr.tpu/NODISPLAY 'p1' !
The DECTPU command file GSR.TPU, which is used as the file specification for the /COMMAND qualifier, performs a search through the current buffer and replaces a string or a pattern with a string. Example 2-4 shows the file GSR.TPU. GSR.TPU does not create or manipulate any windows.
|Example 2-4 DECTPU Command File GSR.TPU|
PROCEDURE global_search_replace (str_or_pat, str2) ! This procedure performs a search through the current ! buffer and replaces a string or a pattern with a new string LOCAL src_range, replacement_count; ! Return to caller if string not found ON_ERROR msg_text := FAO ('Completed !UL replacement!%S', replacement_count); MESSAGE (msg_text); RETURN; ENDON_ERROR; replacement_count := 0; LOOP src_range := SEARCH (str_or_pat, FORWARD); ! Search returns a range if found ERASE (src_range); ! Remove first string POSITION (END_OF (src_range)); ! Move to right place COPY_TEXT (str2); ! Replace with second string replacement_count := replacement_count + 1; ENDLOOP; ENDPROCEDURE; ! global_search_replace ! Executable statements input_file := GET_INFO (COMMAND_LINE, "file_name"); main_buffer:= CREATE_BUFFER ("main", input_file); POSITION (BEGINNING_OF (main_buffer)); global_search_replace ("xyz$_", "user$_"); pat1:= "" & LINE_BEGIN & "t"; POSITION (BEGINNING_OF (main_buffer)); global_search_replace (pat1, "T"); WRITE_FILE (main_buffer, "newfile.dat"); QUIT;
To use the DCL command procedure INVISIBLE_TPU.COM interactively, invoke it with the DCL command @ (at sign). For example, to use INVISIBLE_TPU.COM interactively on a file called MY_FILE.TXT, type the following at the DCL prompt:
$ @invisible_tpu my_file.txt
You must explicitly write out any modified buffers before leaving the
editor with QUIT or EXIT. If you use QUIT before writing out such
buffers, DECTPU quits without saving the modifications. If you use
EXIT, DECTPU asks if it should write the file before exiting.
2.3 Invoking DECTPU from a Batch Job
If you want your edits to be made in batch rather than at the terminal, you can use the DCL command SUBMIT to send your job to a batch queue.
For example, if you want to use the file GSR.TPU (shown in Example 2-4) to make edits in batch mode to a file called MY_FILE.TXT, enter the following command:
$ SUBMIT invisible_tpu.COM/LOG=invisible_tpu.LOG/parameter=my_file.txt
This job is then entered in the default batch queue for your system. The results are sent to the log file that the batch job creates.
In batch DECTPU, EXIT is the same as QUIT.
2.4 Using Journal Files
DECTPU offers two journaling methods:
You can use both keystroke and buffer-change journaling at the same time (except on DECwindows, where you can use only buffer-change journaling). To turn on keystroke journaling, the application uses the JOURNAL_OPEN built-in.
The application layered on DECTPU, not the DECTPU engine, determines what kind of journaling is turned on and under what conditions. Table 2-2 shows the journaling behavior established by EVE.
|OpenVMS Qualifier||Effect on Keystroke Journaling||Effect on Buffer-Change Journaling|
|/JOURNAL = filename||Enabled||Enabled.|
|/NOJOURNAL||Disabled||Disabled. However, you can use SET (JOURNALING) to enable buffer-change journaling.|
Journal files contain a record of all information being edited. Therefore, when editing files that contain secure or confidential data, be sure to keep the journal files secure as well.
You must use the same major version of DECTPU to recover the journal that you used to create it.
In keystroke journaling, DECTPU keeps track of each keystroke made during a session, regardless of which buffer is in use. If a system interruption occurs during a session, you can reconstruct the work done during the session.
filename := GET_INFO (SYSTEM, "journal_file");
For more information on using a keystroke journal file for recovery, see Section 2.6.8 and the Extensible Versatile Editor Reference Manual.
Compaq strongly recommends the use of buffer-change journaling rather than keystroke journaling.
To reconstruct your work, use the /JOURNAL and /RECOVER qualifiers. The following example shows system recovery on a file called JACKI.SDML:
$ EDIT/TPU JACKI.SDML /JOURNAL /RECOVER
Buffer-change journaling creates a separate journal file for each text buffer. The application can use the enhanced SET (JOURNALING) built-in to direct DECTPU to establish and maintain a separate journal file for any buffer or buffers created during the session. The application programmer or user can also use the SET (JOURNALING) built-in to turn journaling off or on for a given buffer during a session.
In the buffer's journal file, DECTPU keeps track of the following record attributes (and any changes made to them):
The journal file also tracks the following:
To determine whether buffer-change journaling is turned on, use the following statement:
status := GET_INFO (buffer_name, "journaling");
For more information on record attributes and display values, see the descriptions of the SET (RECORD_ATTRIBUTE) and SET (DISPLAY_VALUE) built-in procedures in the DEC Text Processing Utility Reference Manual.