Compaq DEC Text Processing Utility (DECTPU) Guide 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

Preface
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.
• 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 [email protected]
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/xA sequence such as Ctrl/xindicates that you must hold down
the key labeled Ctrl while you press another key or a pointing
device button.
PF1 xA sequence such as PF1 xindicates that you must first press
and release the key labeled PF1 and then press and release
another key or a pointing device button.
Return 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.
. . . A horizontal ellipsis in examples indicates one of the following
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.
( ) In command format descriptions, parentheses indicate that you
must enclose the options in parentheses if you choose more
than one.
[ ] In command format descriptions, brackets indicate optional
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.)
[|] In command format descriptions, vertical bars separating
items inside brackets indicate that you choose one, none, or
more than one of the options.
{ } In command format descriptions, braces indicate required
elements; you must choose one of the options listed.
x

bold text This text style represents the introduction of a new term or the
name of an argument, an attribute, or a reason.
italic text Italic text indicates important information, complete titles
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).
UPPERCASE TEXT Uppercase text indicates a command, the name of a routine,
the name of a file, or the abbreviation for a system privilege.
Monospace text 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.
- A hyphen at the end of a command format description,
command line, or code line indicates that the command or
statement continues on the following line.
numbers All numbers in text are assumed to be decimal unless
otherwise noted. Nondecimal radixes—binary, octal, or
hexadecimal—are explicitly indicated.
xi

1
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
• 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
D E C T P U
ZK−6545−GE
Editor
EVE
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.
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
ZK−6544−GE
D E C T P U
Application
User−Written Editor EVE
to EVE
Extensions
User−Written
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.
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

Overview of the DEC Text Processing Utility
1.4 DECTPU Language
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.
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