Updated: 11 December 1998

Guide to the DEC Text Processing Utility

You can write your own procedures that combine DECTPU language statements and calls to DECTPU built-in procedures. DECTPU procedures can return values and can be recursive. After you write a procedure and compile it, you use the procedure name to invoke it.

When writing a procedure, use the following guidelines:

• Start each procedure with the word PROCEDURE, followed by the procedure name of your choice.
• End each procedure with the word ENDPROCEDURE.
• Place a semicolon after each statement or built-in call if the statement or call is followed by another statement or call.
  If the statement or call is not followed by another statement or call, the semicolon is not necessary.

Example 1-1 is a sample procedure that uses the DECTPU language statements PROCEDURE/ENDPROCEDURE and the built-in procedures POSITION, BEGINNING_OF, and CURRENT_BUFFER to move the current character position to the beginning of the current buffer. The procedure uses the MESSAGE built-in to display a message; it uses the GET_INFO built-in to get the name of the current buffer.

Example 1-1 Sample User-Written Procedure

! This procedure moves the editing ! position to the top of the buffer PROCEDURE user_top POSITION (BEGINNING_OF (CURRENT_BUFFER)); MESSAGE ("Now in buffer" + GET_INFO (CURRENT_BUFFER, "name")); ENDPROCEDURE;

Once you have compiled this procedure, you can invoke it with the name user_top. For information about writing procedures, see Chapter 4 and Chapter 5.

1.5 Terminals Supported by DECTPU

DECTPU runs on all VAX and Alpha computers, and supports screen-oriented editing on the Digital 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.

1.6 Learning Path for DECTPU

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.

This chapter describes the following:

• Invoking DECTPU on OpenVMS systems
• Invoking DECTPU from a DCL command procedure
• Invoking DECTPU from a batch job
• Using journal files
• Avoiding errors related to virtual address space
• Using OpenVMS command line qualifiers

On OpenVMS systems you can invoke DECTPU through the Digital Command Language (DCL).

The basic DCL command for invoking DECTPU with EVE (the default editor) is as follows:

$ EDIT/TPU

To invoke DECTPU from DCL, type the command EDIT/TPU, optionally followed by the name of your file:

$ EDIT/TPU text_file.lis

This command opens TEXT_FILE.LIS for editing.

If you are using the EVE editor, Digital 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 message.

2.1.1 Default File Specifications

Table 2-1 lists the default TPU and EVE file specifications on OpenVMS systems.

Table 2-1 Default File Specifications on OpenVMS Systems

File	OpenVMS File Specification
Section	SYS$SHARE:TPU$SECTION.TPU$SECTION
Command	TPU$COMMAND.TPU
Init	SYS$DISK:EVE$INIT.EVE
Init	SYS$LOGIN:EVE$INIT.EVE
Debugger	SYS$SHARE:TPU$DEBUG.TPU
Keystroke journal	SYS$DISK:.TJL
Buffer-change journal	SYS$SCRATCH:.TPU$JOURNAL
Buffer-change journal	TPU$JOURNAL:.TPU$JOURNAL
Work	SYS$SCRATCH:.TPU$WORK
Motif Resource	SYS$LIBRARY:.UID 1
Application defaults	DECW$SYSTEM_DEFAULTS:.DAT
Application defaults	DECW$USER_DEFAULTS:.DAT
EVE Motif resource	SYS$SHARE:EVE$WIDGETS.UID
EVE sources	SYS$EXAMPLES:EVE$*.*

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.

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.

The source files for EVE are in SYS$EXAMPLES. To see a list of the EVE source files, type the following at the DCL prompt:

$ DIRECTORY SYS$EXAMPLES:EVE$*.TPU

If you cannot find these files on your system, see your system manager.

Chapter 5 describes how to write and process command files and section files.

2.2 Invoking DECTPU from a DCL Command Procedure

There are two reasons that you might want to invoke DECTPU from a command procedure:

• To set up a special environment for interactive editing
• To create a noninteractive, DECTPU-based application

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:

2.2.2 Creating a Noninteractive Application

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:

• /NOSECTION---This qualifier prevents DECTPU from using a section file. All procedures and key definitions must be specified in a command file.
• /COMMAND=gsr.tpu---This qualifier specifies a command file that contains the code to be executed (GSR.TPU).
• /NODISPLAY---This qualifier suppresses screen display.

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

Journal files help you to recover your work when the system fails. This section discusses the journaling methods you can use with DECTPU.

DECTPU offers two journaling methods:

• Keystroke journaling
• Buffer-change journaling

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.

Table 2-2 Journaling Behavior Established by EVE

OpenVMS Qualifier	Effect on Keystroke Journaling	Effect on Buffer-Change Journaling
None specified	Disabled	Enabled.
/JOURNAL	Disabled	Enabled.
/JOURNAL = filename	Enabled	Enabled.
/NOJOURNAL	Disabled	Disabled. However, you can use SET (JOURNALING) to enable buffer-change journaling.

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.

To determine the name of the keystroke journal file, use a statement similar to the following:

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.

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

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

6018PRO_001.HTML