Compaq AA-PWCBD-TE User Manual

Guide to the DEC Text
ProcessingUtility

Order Number: AA–PWCBD–TE

April 2001

This manual introduces the DEC Text Processing Utility (DECTPU). It
is for experienced programmers as well as new users of DECTPU.

Revision/Update Information: This manual supersedes the Guide

to the DEC Text Processing Utility,

Version 3.1

Software Version: OpenVMS Alpha Version 7.3

OpenVMS VAX Version 7.3
The content of this manual has not

changed sinced OpenVMS Version 7.1

Compaq Computer Corporation
Houston, Texas

© 2001 Compaq Computer Corporation
Compaq, VAX, VMS and the Compaq logo Registered in U.S. Patent and Trademark Office.
OpenVMS is a trademark of Compaq Information Technologies Group, L.P. in the United States and

other countries.
PostScript is a registered trademark of Adobe Systems Incorporated.
Motif is a registered trademark of the The Open Group.
All other product names mentioned herein may be the trademarks or registered trademarks of their

respective companies.
Confidential computer software. Valid license from Compaq or authorized sublicensor required

for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer
Software, Computer Software Documentation, and Technical Data for Commercial Items are
licensed to the U.S. Government under vendor’s standard commercial license.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The
information in this document is provided "as is" without warranty of any kind and is subject
to change without notice. The warranties for Compaq products are set forth in the express
limited warranty statements accompanying such products. Nothing herein should be construed as
constituting an additional warranty.

ZK6018

The Compaq OpenVMS documentation set is available on CD-ROM.

This document was prepared using DECdocument, Version 3.3-1b.

Contents

Preface ............................................................ ix

1 Overview of the DEC Text Processing Utility

1.1 Description of DECTPU ....................................... 1–1

1.1.1 DECTPU Features ........................................ 1–1

1.1.2 DECTPU and User Applications ............................. 1–2

1.1.3 DECTPU Environments .................................... 1–2

1.2 Description of DECwindows DECTPU ............................ 1–2

1.2.1 DECwindows DECTPU and DECwindows Features .............. 1–3

1.2.2 DECwindows DECTPU and the DECwindows User Interface

Language ............................................... 1–4

1.3 Description of EVE. . . ........................................ 1–4

1.4 DECTPU Language . . ........................................ 1–5

1.4.1 Data Types.............................................. 1–6

1.4.2 Language Declarations..................................... 1–6

1.4.3 Language Statements ..................................... 1–6

1.4.4 Built-In Procedures ....................................... 1–6

1.4.5 User-Written Procedures . . . ................................ 1–7

1.5 Terminals Supported by DECTPU ............................... 1–7

1.6 Learning Path for DECTPU .................................... 1–8

2 Getting Started with DECTPU

2.1 Invoking DECTPU on OpenVMS Systems . . ....................... 2–1

2.1.1 Default File Specifications . . ................................ 2–2

2.1.2 Startup Files ............................................ 2–2

2.2 Invoking DECTPU from a DCL Command Procedure . ............... 2–3

2.2.1 Setting Up a Special Editing Environment ..................... 2–3

2.2.2 Creating a Noninteractive Application . . ....................... 2–4

2.3 Invoking DECTPU from a Batch Job ............................. 2–6

2.4 Using Journal Files . . ........................................ 2–6

2.4.1 Keystroke Journaling ...................................... 2–7

2.4.2 Buffer-Change Journaling . . ................................ 2–7

2.4.3 Buffer-Change Journal File-Naming Algorithm . . . ............... 2–8

2.5 Avoiding Errors Related to Virtual Address Space ................... 2–8

2.6 Using OpenVMS EDIT/TPU Command Qualifiers ................... 2–9

2.6.1 /CHARACTER_SET ....................................... 2–9

2.6.2 /COMMAND............................................. 2–10

2.6.3 /CREATE ............................................... 2–11

2.6.4 /DEBUG ................................................ 2–12

2.6.5 /DISPLAY............................................... 2–12

2.6.6 /INITIALIZATION ........................................ 2–13

2.6.7 /INTERFACE ............................................ 2–14

iii

2.6.8 /JOURNAL. . ............................................ 2–14

2.6.9 /MODIFY . . . ............................................ 2–15

2.6.10 /OUTPUT . . . ............................................ 2–16

2.6.11 /READ_ONLY............................................ 2–17

2.6.12 /RECOVER. . ............................................ 2–18

2.6.13 /SECTION . . ............................................ 2–19

2.6.14 /START_POSITION . . . .................................... 2–20

3 DEC Text Processing Utility Data Types

3.1 Array Data Type ............................................ 3–2

3.2 Buffer Data Type ............................................ 3–3

3.3 Integer Data Type ........................................... 3–4

3.4 Keyword Data Type .......................................... 3–5

3.5 Learn Data Type ............................................ 3–7

3.6 Marker Data Type ........................................... 3–8

3.7 Pattern Data Type ........................................... 3–10

3.7.1 Using Pattern Built-In Procedures and Keywords ................ 3–12

3.7.2 Using Keywords to Build Patterns ............................ 3–12

3.7.3 Using Pattern Operators ................................... 3–13

3.7.3.1 + (Pattern Concatenation Operator) ........................ 3–13

3.7.3.2 & (Pattern Linking Operator) ............................ 3–13

3.7.3.3 | (Pattern Alternation Operator) ......................... 3–14

3.7.3.4 @ (Partial Pattern Assignment Operator) ................... 3–14

3.7.3.5 Relational Operators ................................... 3–15

3.7.4 Compiling and Executing Patterns ........................... 3–16

3.7.5 Searching for a Pattern .................................... 3–16

3.7.6 Anchoring a Pattern. . . .................................... 3–17

3.8 Process Data Type ........................................... 3–18

3.9 Program Data Type .......................................... 3–18

3.10 Range Data Type ............................................ 3–19

3.11 String Data Type ............................................ 3–20

3.12 Unspecified Data Type ........................................ 3–21

3.13 Widget Data Type ........................................... 3–22

3.14 Window Data Type ........................................... 3–22

3.14.1 Defining Window Dimensions................................ 3–23

3.14.2 Creating Windows ........................................ 3–23

3.14.3 Displaying Window Values .................................. 3–24

3.14.4 Mapping Windows ........................................ 3–24

3.14.5 Removing Windows . . . .................................... 3–25

3.14.6 Using the Screen Manager .................................. 3–25

3.14.7 Getting Information on Windows . ............................ 3–25

3.14.8 Terminals That Do Not Support Windows . . . ................... 3–26

4 Lexical Elements of the DEC Text Processing Utility Language

4.1 Overview .................................................. 4–1

4.2 Case Sensitivity of Characters .................................. 4–1

4.3 Character Sets . . ............................................ 4–2

4.3.1 DEC Multinational Character Set (DEC_MCS) .................. 4–2

4.3.2 ISO Latin1 Character Set (ISO_LATIN1)....................... 4–3

4.3.3 General Character Sets .................................... 4–3

4.3.4 Entering Control Characters ................................ 4–3

4.3.5 DECTPU Symbols ........................................ 4–4

iv

4.4 Identifiers . ................................................ 4–5

4.5 Variables . . ................................................ 4–5

4.6 Constants . . ................................................ 4–6

4.7 Operators . . ................................................ 4–7

4.8 Expressions ................................................ 4–8

4.8.1 Arithmetic Expressions .................................... 4–10

4.8.2 Relational Expressions ..................................... 4–10

4.8.3 Pattern Expressions ....................................... 4–11

4.8.4 Boolean Expressions ...................................... 4–11

4.9 Reserved Words ............................................. 4–12

4.9.1 Keywords ............................................... 4–12

4.9.2 Built-In Procedure Names . . ................................ 4–12

4.9.3 Predefined Constants ...................................... 4–12

4.9.4 Declarations and Statements ................................ 4–13

4.9.4.1 Module Declaration .................................... 4–14

4.9.4.2 Procedure Declaration . . ................................ 4–15

4.9.4.3 Procedure Names ...................................... 4–15

4.9.4.4 Procedure Parameters . . ................................ 4–15

4.9.4.5 Procedures That Return a Result . . . ....................... 4–18

4.9.4.6 Recursive Procedures . . . ................................ 4–18

4.9.4.7 Local Variables ........................................ 4–19

4.9.4.8 Constants ............................................ 4–19

4.9.4.9 ON_ERROR Statements ................................ 4–19

4.9.4.10 Assignment Statement . . ................................ 4–20

4.9.4.11 Repetitive Statement . . . ................................ 4–20

4.9.4.12 Conditional Statement . . ................................ 4–20

4.9.4.13 Case Statement ....................................... 4–21

4.9.4.14 Error Handling ....................................... 4–23

4.9.4.15 Procedural Error Handlers............................... 4–24

4.9.4.16 Case-Style Error Handlers ............................... 4–25

4.9.4.17 Ctrl/C Handling ....................................... 4–28

4.9.4.18 RETURN Statement . . . ................................ 4–28

4.9.4.19 ABORT Statement ..................................... 4–29

4.9.5 Miscellaneous Declarations . ................................ 4–30

4.9.5.1 EQUIVALENCE ....................................... 4–30

4.9.5.2 LOCAL.............................................. 4–30

4.9.5.3 CONSTANT . . ........................................ 4–32

4.9.5.4 VARIABLE . . . ........................................ 4–32

4.10 Lexical Keywords ............................................ 4–32

4.10.1 Conditional Compilation . . . ................................ 4–33

4.10.2 Specifying the Radix of Numeric Constants ..................... 4–34

5 DEC Text Processing Utility Program Development

5.1 Creating DECTPU Programs . . . ................................ 5–1

5.1.1 Simple Programs . ........................................ 5–2

5.1.2 Complex Programs ........................................ 5–2

5.1.3 Program Syntax . . ........................................ 5–3

5.2 Programming in DECwindows DECTPU . . . ....................... 5–4

5.2.1 Widget Support . . ........................................ 5–4

5.2.2 Input Focus Support ...................................... 5–5

v

5.2.3 Global Selection Support ................................... 5–6

5.2.3.1 Difference Between Global Selection and Clipboard . ........... 5–6

5.2.3.2 Handling of Multiple Global Selections . . ................... 5–6

5.2.3.3 Relation of Global Selection to Input Focus .................. 5–6

5.2.3.4 Response to Requests for Information About the Global

Selection ............................................ 5–7

5.2.4 Using Callbacks .......................................... 5–7

5.2.4.1 Background on DECwindows Callbacks . . ................... 5–8

5.2.4.2 Internally Defined DECTPU Callback Routines and

Application-Level Callback Action Routines .................. 5–8

5.2.4.3 Internally Defined DECTPU Callback Routines with UIL ....... 5–8

5.2.4.4 Internally Defined DECTPU Callback Routines with Widgets Not

Defined by UIL . . . .................................... 5–9

5.2.4.5 Application-Level Callback Action Routines .................. 5–9

5.2.4.6 Callable Interface-Level Callback Routines .................. 5–9

5.2.5 Using Closures ........................................... 5–10

5.2.6 Specifying Values for Widget Resources in DECwindows DECTPU . . . 5–10

5.2.6.1 DECTPU Data Types for Specifying Resource Values .......... 5–10

5.2.6.2 Specifying a List as a Resource Value . . . ................... 5–11

5.3 Writing Code Compatible with DECwindows EVE ................... 5–13

5.3.1 Select Ranges in DECwindows EVE .......................... 5–13

5.3.1.1 Dynamic Selection . .................................... 5–13

5.3.1.2 Static Selection . . . .................................... 5–13

5.3.1.3 Found Range Selection.................................. 5–14

5.3.1.4 Relation of EVE Selection to DECwindows Global Selection . . . . . 5–14

5.4 Compiling DECTPU Programs .................................. 5–14

5.4.1 Compiling on the EVE Command Line ........................ 5–15

5.4.2 Compiling in a DECTPU Buffer . . ............................ 5–15

5.5 Executing DECTPU Programs .................................. 5–15

5.5.1 Procedure Execution . . .................................... 5–16

5.5.2 Process Suspension . . . .................................... 5–16

5.6 Using DECTPU Startup Files .................................. 5–17

5.6.1 Section Files. ............................................ 5–17

5.6.2 Command Files .......................................... 5–17

5.6.3 Initialization Files ........................................ 5–18

5.6.4 Sequence in Which DECTPU Processes Startup Files . . ........... 5–18

5.6.5 Using Section Files . . . .................................... 5–19

5.6.5.1 Creating and Processing a New Section File ................. 5–19

5.6.5.2 Extending an Existing Section File ........................ 5–20

5.6.5.3 Sample Section File .................................... 5–21

5.6.5.4 Recommended Conventions for Section Files ................. 5–23

5.6.6 Using Command Files . .................................... 5–24

5.6.7 Using EVE Initialization Files . . . ............................ 5–25

5.6.7.1 Using an EVE Initialization File at Startup ................. 5–26

5.6.7.2 Using an EVE Initialization File During an Editing Session . . . . . 5–27

5.6.7.3 How an EVE Initialization File Affects Buffer Settings ......... 5–27

5.7 Debugging DECTPU Programs ................................. 5–28

5.7.1 Using Your Own Debugger .................................. 5–28

5.7.2 Using the DECTPU Debugger . . . ............................ 5–28

5.7.2.1 Debugging Section Files ................................. 5–28

5.7.2.2 Debugging Command Files . . ............................ 5–29

5.7.2.3 Debugging Other DECTPU Source Code . ................... 5–29

5.7.3 Getting Started with the DECTPU Debugger ................... 5–29

5.8 Handling Errors . ............................................ 5–30

vi

A Sample DECTPU Procedures

A.1 Line-Mode Editor ............................................ A–1

A.2 Translation of Control Characters ............................... A–2

A.3 Restoring Terminal Width Before Exiting from DECTPU ............. A–6

A.4 Running DECTPU from an OpenVMS Subprocess . . . ............... A–7

B DECTPU Terminal Support

B.1 Using Screen-Oriented Editing on Supported Terminals .............. B–1

B.1.1 Terminal Settings on OpenVMS Systems That Affect DECTPU ..... B–1

B.1.2 SET TERMINAL Command . ................................ B–3

B.2 Using Line-Mode Editing on Unsupported Terminals . ............... B–3

B.3 Using Terminal Wrap. ........................................ B–3

C DECTPU Debugger Commands

Index

Examples

1–1 Sample User-Written Procedure .............................. 1–7

2–1 DCL Command Procedure FILENAME.COM .................... 2–4

2–2 DCL Command Procedure FORTRAN_TS.COM . . ............... 2–4

2–3 DCL Command Procedure INVISIBLE_TPU.COM ............... 2–5

2–4 DECTPU Command File GSR.TPU ........................... 2–5

3–1 Suppressing the Addition of Padding Blanks .................... 3–10

4–1 Global and Local Variable Declarations . ....................... 4–5

4–2 Global and Local Constant Declarations ....................... 4–6

4–3 Procedure That Uses Relational Operators on Markers ............ 4–11

4–4 Simple Procedure with Parameters ........................... 4–16

4–5 Complex Procedure with Optional Parameters ................... 4–17

4–6 Procedure That Returns a Result ............................. 4–18

4–7 Procedure Within Another Procedure . . . ....................... 4–18

4–8 Recursive Procedure ....................................... 4–19

4–9 Procedure That Uses the CASE Statement ..................... 4–22

4–10 Procedure That Uses the ON_ERROR Statement . ............... 4–24

4–11 Procedure with a Case-Style Error Handler ..................... 4–26

4–12 Procedure That Returns a Value ............................. 4–28

4–13 Procedure That Returns a Status............................. 4–29

4–14 Using RETURN in an ON_ERROR Section ..................... 4–29

4–15 Simple Error Handler ..................................... 4–30

5–1 SHOW (SUMMARY) Display ................................ 5–2

5–2 Syntax of a DECTPU Program ............................... 5–3

5–3 Sample DECTPU Programs . ................................ 5–4

5–4 Sample Program for a Section File ............................ 5–20

5–5 Source Code for Minimal Interface to DECTPU . . . ............... 5–22

5–6 Command File for GOTO_TEXT_MARKER ..................... 5–25

5–7 SHOW DEFAULTS BUFFER Display . . ....................... 5–27

vii

A–1 Line-Mode Editing ........................................ A–1

A–2 Procedure to Display Control Characters ....................... A–2

A–3 Procedure to Restore Screen to Original Width .................. A–6

A–4 Procedure to Run DECTPU from a Subprocess .................. A–7

B–1 DCL Command Procedure for SET TERM/NOWRAP . . . ........... B–4

Figures

1–1 DECTPU as a Base for EVE ................................ 1–2

1–2 DECTPU as a Base for User-Written Interfaces ................. 1–5

Tables

2–1 Default File Specifications on OpenVMS Systems ................ 2–2

2–2 Journaling Behavior Established by EVE . . . ................... 2–6

2–3 Character Set Values You Can Set with /CHARACTER_SET ........ 2–10

3–1 Keywords Used for Key Names . . ............................ 3–6

3–2 Effects of Two String-Reduction Operations . . ................... 3–21

4–1 Categories of ASCII Character Set Characters .................. 4–2

4–2 Categories of DEC Multinational Character Set Characters ........ 4–2

4–3 Categories for ISO Latin1 Characters ......................... 4–3

4–4 DECTPU Symbols ........................................ 4–4

4–5 DECTPU Operators . . . .................................... 4–7

4–6 Operator Precedence . . .................................... 4–8

5–1 Relationship Between DECTPU Data Types and DECwindows

Argument Data Types . .................................... 5–11

5–2 Special DECTPU Variables That Require a Value from a Layered

Application . . ............................................ 5–24

B–1 Terminal Behavior That Affects DECTPU’s Performance ........... B–1

viii

This manual discusses the DEC Text Processing Utility (DECTPU).

Intended Audience

This manual is for experienced programmers who know at least one computer
language, as well as for new users of DECTPU. Some features of DECTPU, for
example, the callable interface and the built-in procedure FILE_PARSE, are
for system programmers who understand Compaq OpenVMS operating system
concepts. Relevant documents about the OpenVMS operating system are listed
under Related Documents.

Document Structure

This manual is organized as follows:

• Chapter 1 contains an overview of DECTPU.

• Chapter 2 describes how to invoke DECTPU.

• Chapter 3 provides detailed information on DECTPU data types.

• Chapter 4 discusses the lexical elements of DECTPU. These include the

character set, identifiers, variables, constants, and reserved words, such as
DECTPU language statements.

Preface

• Chapter 5 describes DECTPU program development.

• Appendix A contains sample procedures written in DECTPU.

• Appendix B describes terminals supported by DECTPU.

• Appendix C lists commands for debugging DECTPU.

Related Documents

For additional information about OpenVMS products and services, access the
following World Wide Web address:

http://www.openvms.compaq.com/

Reader’s Comments

Compaq welcomes your comments on this manual. Please send comments to
either of the following addresses:

Internet [e-mail]

ix

Mail Compaq Computer Corporation

OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

http://www.openvms.compaq.com/

If you need help deciding which documentation best meets your needs, call
800-282-6672.

Conventions

The following conventions are used in this manual:

Ctrl/x A sequence such as Ctrl/x indicates that you must hold down

PF1 x A sequence such as PF1 x indicates that you must first press

Return

. . . A horizontal ellipsis in examples indicates one of the following

.
.
.

( ) In command format descriptions, parentheses indicate that you

[ ] In command format descriptions, brackets indicate optional

[|] In command format descriptions, vertical bars separating

{ } In command format descriptions, braces indicate required

the key labeled Ctrl while you press another key or a pointing
device button.

and release the key labeled PF1 and then press and release
another key or a pointing device button.

In examples, a key name enclosed in a box indicates that
you press a key on the keyboard. (In text, a key name is not
enclosed in a box.)

In the HTML version of this document, this convention appears
as brackets, rather than a box.

possibilities:

• Additional optional arguments in a statement have been
omitted.

• The preceding item or items can be repeated one or more
times.

• Additional parameters, values, or other information can be
entered.

A vertical ellipsis indicates the omission of items from a code
example or command format; the items are omitted because
they are not important to the topic being discussed.

must enclose the options in parentheses if you choose more
than one.

elements. You can choose one, none, or all of the options.
(Brackets are not optional, however, in the syntax of a directory
name in an OpenVMS file specification or in the syntax of a
substring specification in an assignment statement.)

items inside brackets indicate that you choose one, none, or
more than one of the options.

elements; you must choose one of the options listed.

x

bold text This text style represents the introduction of a new term or the

italic text Italic text indicates important information, complete titles

UPPERCASE TEXT Uppercase text indicates a command, the name of a routine,

Monospace text

- A hyphen at the end of a command format description,

numbers All numbers in text are assumed to be decimal unless

name of an argument, an attribute, or a reason.

of manuals, or variables. Variables include information that
varies in system output (Internal error number), in command
lines (/PRODUCER=name), and in command parameters in
text (where dd represents the predefined code for the device
type).

the name of a file, or the abbreviation for a system privilege.
Monospace type indicates code examples and interactive screen

displays.
In the C programming language, monospace type in text

identifies the following elements: keywords, the names
of independently compiled external functions and files,
syntax summaries, and references to variables or identifiers
introduced in an example.

command line, or code line indicates that the command or
statement continues on the following line.

otherwise noted. Nondecimal radixes—binary, octal, or
hexadecimal—are explicitly indicated.

xi

Overview of the DEC Text Processing Utility

This chapter presents information about the DEC Text Processing Utility
(DECTPU). The chapter includes the following:

• A description of DECTPU

• A description of DECwindows DECTPU

• A description of the Extensible Versatile Editor (EVE)

• Information about the DECTPU language

• Information about the hardware that DECTPU supports

• How to learn more about DECTPU

1.1 Description of DECTPU

DECTPU is a high-performance, programmable, text processing utility that
includes the following:

• A high-level procedural language

1

• A compiler

• An interpreter

• Text manipulation routines

• Integrated display managers for the character-cell terminal and DECwindows
environments

• The Extensible Versatile Editor (EVE) interface, which is written in DECTPU

DECTPU is a procedural programming language that enables text processing
tasks; it is not an application.

1.1.1 DECTPU Features

DECTPU aids application and system programmers in developing tools that
manipulate text. For example, programmers can use DECTPU to design an
editor for a specific environment.

DECTPU provides the following special features:

• Multiple buffers

• Multiple windows

• Multiple subprocesses

• Keystroke and buffer-change journaling

• Text processing in batch mode

• Insert or overstrike text entry

Overview of the DEC Text Processing Utility 1–1

Overview of the DEC Text Processing Utility

1.1 Description of DECTPU

• Free or bound cursor motion

• Learn sequences

• Pattern matching

• Key definition

• Procedural language

• Callable interface

1.1.2 DECTPU and User Applications

DECTPU is a language that you can use as a base on which to layer text
processing applications. When you choose an editor or other application to layer
on DECTPU, that becomes the interface between you and DECTPU. You can also
create your own interface to access DECTPU.

Figure 1–1 shows the relationship of DECTPU with EVE as its user interface.

Figure 1–1 DECTPU as a Base for EVE

EVE

Editor

D E C T P U

1.1.3 DECTPU Environments

You can use DECTPU on the OpenVMS VAX and OpenVMS Alpha operating
systems.

You can display text in two environments:

• Character-cell terminals

• Bit-mapped workstations running the DECwindows software

1.2 Description of DECwindows DECTPU

DECTPU supports the Compaq DECwindows Motif for OpenVMS user interface.
The variant of DECTPU that supports window-oriented user interfaces is known
as DECwindows DECTPU. The windows referred to as DECwindows are not the
same as DECTPU windows. For more information about the difference between
DECwindows and DECTPU windows, see Chapter 5.

ZK−6545−GE

Because DECTPU is a language, not an application, DECTPU does not have a
window-oriented interface. However, DECTPU does provide built-in procedures to
interact with the DECwindows Motif environment. (For information on invoking
DECTPU on systems running DECwindows Motif, see Chapter 2.)

1–2 Overview of the DEC Text Processing Utility

Overview of the DEC Text Processing Utility

1.2 Description of DECwindows DECTPU

1.2.1 DECwindows DECTPU and DECwindows Features

The DECwindows environment has a number of toolkits and libraries that contain
routines for creating and manipulating DECwindows interfaces. DECwindows
DECTPU contains a number of built-in procedures that provide access to the
routines in the DECwindows libraries and toolkits.

With these procedures, you can create and manipulate various features of a
DECwindows interface from within a DECTPU program. In most cases, you
can use DECTPU DECwindows built-in procedures without knowing what
DECwindows routine a given built-in procedure calls. For a list of the kinds of
widgets you can create and manipulate with DECTPU built-in procedures, see
Chapter 5.

You cannot directly call DECwindows routines (such as X Toolkit routines) from
within a program written in the DECTPU language. To use a DECwindows
routine in a DECTPU program, use one or more of the following techniques:

• Use a DECTPU built-in procedure that calls a DECwindows routine.
Examples of such DECTPU built-in procedures include the following:

CREATE_WIDGET
DELETE (WIDGET)
MANAGE_WIDGET
REALIZE_WIDGET
SEND_CLIENT_MESSAGE
SET (CLIENT_MESSAGE)
SET (DRM_HIERARCHY)
SET (ICON_NAME)
SET (ICON_PIXMAP)
SET (MAPPED_WHEN_MANAGED)
SET (WIDGET)
SET (WIDGET_CALL_DATA)
SET (WIDGET_CALLBACK)
UNMANAGE_WIDGET

For more information about how to use the DECwindows built-ins in
DECTPU, see the individual built-in descriptions in the DEC Text Processing
Utility Reference Manual.

• Use a compiled language that follows the OpenVMS calling standard to write
a function or a program that calls the desired routine. You can then invoke
DECTPU in one of the following ways:

Use the built-in procedure CALL_USER in your DECTPU program
when the program is written in a non-DECTPU language. (For more
information about using the built-in procedure CALL_USER, see the DEC
Text Processing Utility Reference Manual.)

Use the DECTPU callable interface to invoke DECTPU from the program.
(For more information about using the DECTPU callable interface, see
the OpenVMS Utility Routines Manual.)

Overview of the DEC Text Processing Utility 1–3

Overview of the DEC Text Processing Utility

1.2 Description of DECwindows DECTPU

The DECwindows version of DECTPU does not provide access to all of the
features of DECwindows. For example, there are no DECTPU built-in procedures
to handle floating-point numbers or to manipulate entities such as lines, curves,
and fonts.

With DECwindows DECTPU, you can create a wide variety of widgets, designate
callback routines for those widgets, fetch and set geometry and text-related
resources of the widgets, and perform other functions related to creating a
DECwindows application. For example, the DECwindows EVE editor is a text
processing interface created with DECwindows DECTPU.

1.2.2 DECwindows DECTPU and the DECwindows User Interface Language

You can use DECTPU programs with DECwindows User Interface Language
(UIL) files just as you would use programs in any other language with UIL
files. For an example of a DECTPU program and a UIL file designed to work
together, see the description of the CREATE_WIDGET built-in in the DEC Text
Processing Utility Reference Manual. For more information about using UIL
files in conjunction with programs written in other languages, see the VMS
DECwindows Guide to Application Programming.

1.3 Description of EVE

The Extensible Versatile Editor (EVE) is the editor provided with DECTPU. EVE
is easy to learn and to use. You can access many of EVE’s editing functions by
pressing a single key on the keypad. EVE is also a powerful and efficient editor,
which makes it attractive to experienced users of text editors. You can access
more advanced editing functions by entering commands on the EVE command
line. Many of the special features of DECTPU (such as multiple windows) are
available with EVE commands. You can access other DECTPU features by
entering DECTPU statements from within EVE.

EVE has both a character-cell and a DECwindows interface. To use EVE’s
DECwindows interface, you must be using a bit-mapped terminal or workstation.

Although EVE is a fully functional editor, it is designed to make customization
easy. You can use either DECTPU statements or EVE commands to tailor EVE to
your editing style.

You can write extensions for EVE or you can write a completely separate interface
for DECTPU. Figure 1–2 shows the interface choices for DECTPU.

1–4 Overview of the DEC Text Processing Utility

Overview of the DEC Text Processing Utility

1.3 Description of EVE

Figure 1–2 DECTPU as a Base for User-Written Interfaces

User−Written

Extensions

to EVE

User−Written

Application

D E C T P U

You can implement extensions to EVE with any of the following:

• A DECTPU command file (DECTPU source code)

• A DECTPU section file (compiled DECTPU code in binary form)

• An initialization file (commands in a format that EVE can process)

Because a DECTPU section file is already compiled, startup time for your
editor or application is shorter when you use a section file than when you use a
command file or an initialization file. Section 2.1.2 contains more information on
startup files.

To implement an editor or application that is entirely user written, use a section
file. Chapter 5 contains more information on DECTPU command files, section
files, and initialization files. The DEC Text Processing Utility Reference Manual
contains information on layering applications on DECTPU.

EVE

Editor

ZK−6544−GE

1.4 DECTPU Language

You can view the DECTPU language as the most basic component of DECTPU.
To access the features of DECTPU, write a program in the DECTPU language
and then use the utility to compile and execute the program. A program written
in DECTPU can be as simple as a single statement or as complex as the section
file that implements EVE.

The block-structured DECTPU language is easy to learn and use. DECTPU
language features include a large number of data types, relational operators,
error interception, looping and case statements, and built-in procedures that
simplify development or extension of an editor or application. Comments are
indicated with a single comment character (!) so that you can document your
procedures easily. There are also capabilities for debugging procedures with
user-written debugging programs.

Overview of the DEC Text Processing Utility 1–5

Overview of the DEC Text Processing Utility

1.4 DECTPU Language

1.4.1 Data Types

The DECTPU language has an extensive set of data types. You use data types to
interpret the meaning of the contents of a variable. Unlike many languages, the
DECTPU language has no declarative statement to enforce which data type must
be assigned to a variable. A variable in DECTPU assumes a data type when it is
used in an assignment statement. For example, the following statement assigns
a string data type to the variable this_var:

this_var := ’This can be a string of your choice.’;

The following statement assigns a window data type to the variable x. The
window occupies 15 lines on the screen, starting at line 1, and the status line is
off (not displayed).

x := CREATE_WINDOW (1, 15, OFF);

Many of the DECTPU data types (for example, learn and pattern) are different
from the data types usually found in programming languages. See the DEC Text
Processing Reference Manual for the keywords used to specify data types. See
Chapter 3 of this manual for a discussion of DECTPU data types.

1.4.2 Language Declarations

DECTPU language declarations include the following:

• Module declaration (MODULE/IDENT/ENDMODULE)

• Procedure declaration (PROCEDURE/ENDPROCEDURE)

• Constant declaration (CONSTANT)

• Global variable declaration (VARIABLE)

• Local variable declaration (LOCAL)
See Chapter 4 of this manual for a discussion of DECTPU language declarations.

1.4.3 Language Statements

DECTPU language statements include the following:

• Assignment statement (:=)

• Repetitive statement (LOOP/EXITIF/ENDLOOP)

• Conditional statement (IF/THEN/ELSE/ENDIF)

• Case statement (CASE/ENDCASE)

• Error statement (ON_ERROR/ENDON_ERROR)
See Chapter 4 of this manual for a discussion of DECTPU language statements.

1.4.4 Built-In Procedures

The DECTPU language has many built-in procedures that perform functions such
as screen management, key definition, text manipulation, and program execution.

You can use built-in procedures to create your own procedures. You can also
invoke built-in procedures from within EVE. The DEC Text Processing Utility
Reference Manual contains a description of each of the DECTPU built-in
procedures.

1–6 Overview of the DEC Text Processing Utility

1.4.5 User-Written Procedures

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.

Overview of the DEC Text Processing Utility

1.4 DECTPU Language

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

Overview of the DEC Text Processing Utility 1–7

Overview of the DEC Text Processing Utility

1.6 Learning Path for DECTPU

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.

1–8 Overview of the DEC Text Processing Utility

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:

2

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

Getting Started with DECTPU 2–1

Getting Started with DECTPU

2.1 Invoking DECTPU on OpenVMS Systems

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
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$*.*

1

2

3

1

These directory and file type defaults are added by the Motif Resource Manager if missing from the

file specification.

2

xxxxxx = suffix from mktemp(3). Note that this file is invisible.

3

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

2–2 Getting Started with DECTPU

Getting Started with DECTPU

2.1 Invoking DECTPU on OpenVMS Systems

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

Getting Started with DECTPU 2–3

Getting Started with DECTPU

2.2 Invoking DECTPU from a DCL Command Procedure

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.

2–4 Getting Started with DECTPU

Getting Started with DECTPU

2.2 Invoking DECTPU from a DCL Command Procedure

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.

Getting Started with DECTPU 2–5

Getting Started with DECTPU

2.3 Invoking DECTPU from a Batch Job

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

Effect on

OpenVMS Qualifier

None specified Disabled Enabled.
/JOURNAL Disabled Enabled.
/JOURNAL = filename Enabled Enabled.
/NOJOURNAL Disabled Disabled. However, you can use SET

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.

Keystroke
Journaling Effect on Buffer-Change Journaling

(JOURNALING) to enable buffer-change
journaling.

Caution

2–6 Getting Started with DECTPU

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.

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

Getting Started with DECTPU

2.4 Using Journal Files

Note

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.

Getting Started with DECTPU 2–7

Getting Started with DECTPU

2.4 Using Journal Files

2.4.3 Buffer-Change Journal File-Naming Algorithm

By default, DECTPU creates the buffer-change journal file name by using the
following algorithm:

1. Converts all characters in the buffer name that are not alphanumeric, a
dollar sign, underscore, or hyphen to underscores

2. Truncates the resulting file name to 39 characters

3. Adds the file type .TPU$JOURNAL

For example, a buffer named TEST.BAR has a default journal file name of TEST_
BAR.TPU$JOURNAL.

DECTPU puts all journal files in the directory defined by the logical name
TPU$JOURNAL. By default, this logical is defined as SYS$SCRATCH. You can
reassign this logical name. For example, if you want journal files written to the
current default directory, define TPU$JOURNAL as [].

2.5 Avoiding Errors Related to Virtual Address Space

DECTPU manipulates data in a process’s virtual memory space. If the space
required by the DECTPU images, data structures, and files in memory exceeds
the virtual address space, DECTPU tries to write part of the data to the work
file, thus freeing up space for other parts of the data that it needs immediately.

If the work file is full, DECTPU attempts to return either a TPU$_GETMEM
or TPU$_NOCACHE error message. Although you may be able to free up some
space by deleting unused buffers, Compaq recommends that you terminate the
DECTPU session if you encounter either of these errors. You can then start a
new session with fewer or smaller buffers. Alternatively, you may want to put
the work file on a disk that contains more free space. Use one of the following
methods to do this:

• Redefine TPU$WORK to point to the disk with more free space.

• Invoke DECTPU with the /WORK=filename qualifier.

DECTPU may be unable to signal an error when it frees up memory by writing to
the work file. In this case, DECTPU aborts with a fatal internal error.

You may be able to avoid writing to the work file by increasing the virtual
address space available to a process. The virtual address space is controlled by
the following two factors:

• The SYSGEN parameter VIRTUALP AGECNT

• The page file quota of the account you are using

The VIRTUALPAGECNT parameter controls the number of virtual pages that
can be mapped for a process. For more information on VIRTUALPAGECNT, see
the description of this parameter in the OpenVMS documentation on the System
Generation Utility (SYSGEN).

The page file quota controls the number of pages in the system paging file that
can be allocated to your process. For more information on the page file quota, see
the description of the /PGFLQUOTA qualifier in the OpenVMS documentation on
the Authorize Utility (AUTHORIZE).

You may need to modify both the VIRTUALPAGECNT parameter and the page
file quota to enlarge the virtual address space.

2–8 Getting Started with DECTPU

Getting Started with DECTPU

2.5 Avoiding Errors Related to Virtual Address Space

DECTPU keeps strings in a different virtual pool than it does other memory.
Once DECTPU starts writing to the work file, the size of the string memory pool
is fixed. DECTPU cannot write strings to the work file, so if it needs to allocate
more space in the string memory pool, it will fail with a fatal internal error.
If you encounter this problem, you can expand the string memory pool during
startup by preallocating several large strings. The following example shows how
to do this:

PROCEDURE preallocate_strings
LOCAL

str_len,
string1,
string2;

str_len := 65535;
string1 := ’a’ * str_len;
string2 := string1;
ENDPROCEDURE;

2.6 Using OpenVMS EDIT/TPU Command Qualifiers

The DCL command EDIT/TPU has qualifiers for setting attributes of DECTPU
or an application layered on DECTPU. The qualifiers fall into the following two
categories:

• Qualifiers handled by DECTPU
Qualifiers in this category have their defaults set by DECTPU.

• Qualifiers handled by the application layered on DECTPU
Some qualifiers in this category have their defaults set entirely by DECTPU;

some have their defaults set entirely by the layered application, and some
have their defaults set partly by each.

The following sections present the qualifiers in alphabetical order, giving a
detailed description of each. The examples in the following sections show the
qualifiers directly after the EDIT/TPU command and before the input file
specification. You can place the qualifiers anywhere on the command line after
EDIT/TPU. These sections show the defaults that are set if you use EVE. They
also explain how EVE handles each qualifier that can be processed by a layered
application. Applications not based on EVE may handle qualifiers differently.

2.6.1 /CHARACTER_SET

/CHARACTER_SET=DEC_MCS (default)

The /CHARACTER_SET qualifier determines the character set you want
DECTPU to use to display 8-bit characters. The choice of character set affects
how DECTPU performs the following operations on characters:

• Converting to lowercase

• Converting to uppercase

• Inverting case

• Removing diacritical marks

• Converting to uppercase and removing diacritical marks

Getting Started with DECTPU 2–9

Getting Started with DECTPU

2.6 Using OpenVMS EDIT/TPU Command Qualifiers

The choice of character set also affects how your text appears when printed. For
the text displayed in DECTPU to look the same when printed, you must choose
the same character set for both DECTPU and the printer.

There are two ways to specify the character set you want to use:

• Define the TPU$CHARACTER_SET logical name to specify the character set.
This lets you use that character set for all editing sessions—including

when you invoke DECTPU within MAIL or other utilities. You can put the
definition in your LOGIN.COM file. For example, the following commands
define TPU$CHARACTER_SET as ISO_LATIN1 and then use that character
set to invoke DECTPU:

$ DEFINE TPU$CHARACTER_SET ISO_LATIN1
$ EDIT/TPU

• Use /CHARACTER_SET= and specify the character set on the command line.
This overrides any definition of the TPU$CHARACTER_SET logical name.

By default, DECTPU uses the DEC_MCS character set. For example, the
following command specifies the GENERAL character set to invoke DECTPU.
DECTPU uses the current character set to display 8-bit characters and does
not use the default DEC Supplemental Graphics character set.

If the character set you specify either with /CHARACTER_SET or by defining
TPU$CHARACTER_SET is invalid, the editing session is aborted, returning you
to the DCL level.

Table 2–3 shows the values you can specify with the /CHARACTER_SET qualifier
or the TPU$CHARACTER_SET logical name.

Table 2–3 Character Set Values You Can Set with /CHARACTER_SET

Value Description

DEC_MCS This is the default setting that uses the DEC Supplemental

ISO_LATIN1 This character set contains supplemental and multinational

GENERAL DECTPU does not specify a character set for 8-bit characters.

2.6.2 /COMMAND

$ EDIT/TPU/CHARACTER_SET=general

Graphics character set containing supplemental and
multinational characters, such as letters with accents and
umlauts.

characters that contain LATIN1 characters, such as the non­breaking space, multiplication and division signs, and the
trademark sign.

8-bit characters are displayed the same as they were before
you started DECTPU.

/COMMAND[[=filespec]]
/NOCOMMAND
/COMMAND=TPU$COMMAND.TPU (default)

The /COMMAND qualifier determines whether DECTPU compiles and executes
a command file (a file of DECTPU procedures and statements) at startup time.
Command files extend or modify a DECTPU-based application or create a new
application. The default file type for DECTPU command files is .TPU. You cannot
use wildcards in the file specification.

2–10 Getting Started with DECTPU