Guide to the DEC Text Processing Utility
Guide to the DEC Text Processing Utility
This manual introduces the DEC Text Processing Utility (DECTPU). It is
for experienced programmers as well as new users of DECTPU.
This manual supersedes the Guide to the DEC Text Processing Utility, Version 3.1
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
© 2001 Compaq Computer Corporation
Compaq, VAX, VMS and the Compaq logo Registered in U.S. Patent and
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.
The Compaq OpenVMS documentation set is available on CD-ROM.
This manual discusses the DEC Text Processing Utility (DECTPU).
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.
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.
For additional information about OpenVMS products and services, access
the following World Wide Web address:
Compaq welcomes your comments on this manual. Please send comments to
either of the following addresses:
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
If you need help deciding which documentation best meets your needs,
The following conventions are used in this manual:
A sequence such as Ctrl/
x indicates that you must hold down the key labeled Ctrl while
you press another key or a pointing device button.
A sequence such as PF1
x indicates that you must first press and release the key
labeled PF1 and then press and release another key or a pointing device
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
- 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
In command format descriptions, vertical bars separating items inside
brackets indicate that you choose one, none, or more than one of the
In command format descriptions, braces indicate required elements; you
must choose one of the options listed.
This text style represents the introduction of a new term or the name
of an argument, an attribute, or a reason.
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 indicates a command, the name of a routine, 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.
A hyphen at the end of a command format description, command line, or
code line indicates that the command or statement continues on the
All numbers in text are assumed to be decimal unless otherwise noted.
Nondecimal radixes---binary, octal, or hexadecimal---are explicitly
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
- The Extensible Versatile Editor (EVE) interface, which is written
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
- 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
Figure 1-1 DECTPU as a Base for EVE
1.1.3 DECTPU Environments
You can use DECTPU on the OpenVMS VAX and OpenVMS Alpha operating
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
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
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
- Use a DECTPU built-in procedure that calls a DECwindows routine.
Examples of such DECTPU built-in procedures include the following:
- DELETE (WIDGET)
- 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)
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.)
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
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
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
Figure 1-2 DECTPU as a Base for User-Written Interfaces
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
that you can document your procedures easily. There are also
capabilities for debugging procedures with user-written debugging
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
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
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
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
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.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.
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
POSITION (BEGINNING_OF (CURRENT_BUFFER));
MESSAGE ("Now in buffer" + GET_INFO (CURRENT_BUFFER, "name"));
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.