Guide to the DEC Text Processing Utility

Document revision date: 19 July 1999

Guide to the DEC Text Processing Utility

Order Number: AA--PWCBC--TE

January 1999

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.2
OpenVMS VAX Version 7.2

The content of this manual has not changed sinced OpenVMS Version 7.1

Compaq Computer Corporation
Houston, Texas

Reprinted January 1999

Compaq Computer Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Compaq or an authorized sublicensor.

Compaq conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

The following are trademarks of Compaq Computer Corporation: Alpha, Compaq, DECdirect, DECterm, DECwindows, DIGITAL, OpenVMS, VAX, VAX DOCUMENT, VAXcluster, VMS, VT100, VT300, and the Compaq logo.

The following are third-party trademarks:

PostScript is a registered trademark of Adobe Systems Incorporated.

Motif is a registered trademark of the Open Software Foundation, Inc.

All other trademarks and registered trademarks are the property of their respective holders.

ZK6018

The OpenVMS documentation set is available on CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2n.

Contents Index

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

Reader's Comments

Compaq welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet openvmsdoc@zko.mts.dec.com

Fax 603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08

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.digital.com:81/

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

Conventions

The following conventions are used in this manual:

Ctrl/ x 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.

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

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.

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

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 DECwindows Motif 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.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.)

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.

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 (!) so that you can document your procedures easily. There are also capabilities for debugging procedures with user-written debugging programs.

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

Contents

Index

privacy and legal statement

6018PRO.HTML

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail	Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

Ctrl/ x	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.
PF1 x	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 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.
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.