Document revision date: 30 March 2001

## Guide to the DEC Text Processing Utility

Previous | Contents | Index

## 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.

## 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.

## Chapter 2
Getting Started with DECTPU

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

## 2.1 Invoking DECTPU on OpenVMS Systems

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, 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 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 2
EVE Motif resource | SYS$SHARE:EVE$WIDGETS.UID 3
EVE sources | SYS$EXAMPLES:EVE$*.*

1These directory and file type defaults are added by the Motif Resource Manager if missing from the file specification.
2xxxxxx = suffix from mktemp(3). Note that this file is invisible.
3These X resource files are used only by dmtpu and dxtpu.

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.

Note 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.

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.

Caution 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.

### 2.4.1 Keystroke 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.

Note 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

### 2.4.2 Buffer-Change Journaling

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

- Left margin setting
- Modifiability or unmodifiability
- Display value

The journal file also tracks the following:

- Characters inserted in and deleted from a record (including the location where the change took place)
- Records inserted in and deleted from a buffer (including the location where the change took place)

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.

Buffer-change journaling does not keep a record of all keystrokes performed while editing a given buffer.

Previous | Next | Contents | Index

| privacy and legal statement |
6018PRO_001.HTML