Updated: 11 December 1998

Guide to the DEC Text Processing Utility

Order Number: AA--PWCBB--TE

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.1 OpenVMS VAX Version 7.1

Digital Equipment Corporation Maynard, Massachusetts

Digital Equipment 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 Digital or an authorized sublicensor.

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

© Digital Equipment Corporation 1996. All rights reserved.

The following are trademarks of Digital Equipment Corporation: Bookreader, DECdirect, DECwindows, Digital, OpenVMS, OpenVMS Cluster, VAX, VAX DOCUMENT, VAXcluster, VMS, VMScluster, and the DIGITAL 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.2m.

Contents

Index

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.

Related Documents

See the following documents for additional information:

• DEC Text Processing Utility Reference Manual
  Contains the following:
  • Detailed descriptions of the DECTPU built-in procedures
  • Sample procedures written in DECwindows DECTPU
  • Lists of each DECTPU message, its abbreviation, and its severity level
  • A discussion of EVE$BUILD, a tool that you can use to layer applications onto EVE or to build new DECTPU applications
  • Cursor customizations you can make to your DECTPU screen manager

• OpenVMS User's Manual
  Contains information on learning how to use the Extensible Versatile Editor (EVE) and describes system services.
• Extensible Versatile Editor Reference Manual
  Contains reference information on EVE commands.
• OpenVMS Utility Routines Manual
  Contains a chapter that presents the DECTPU callable interface on OpenVMS systems.
• Overview of OpenVMS Documentation
  Briefly describes all OpenVMS system documentation, defines the intended audience for each manual, and provides a synopsis of each manual's contents.
• OpenVMS DCL Dictionary
  Describes the DCL commands that enable you to create, copy, and print files that contain DECTPU programs.
• OpenVMS Run-Time Library documentation
  Describes routines of the run-time library.
• OpenVMS Record Management Services Reference Manual
  Describes OpenVMS RMS services.

For additional information on the Open Systems Software Group (OSSG) products and services, access the Digital OpenVMS World Wide Web site. Use the following URL:

http://www.openvms.digital.com

Reader's Comments

Digital 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 881-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail	OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following table to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

Conventions

The name of the OpenVMS AXP operating system has been changed to the OpenVMS Alpha operating system. Any references to OpenVMS AXP or AXP are synonymous with OpenVMS Alpha or Alpha.

VMScluster systems are now referred to as OpenVMS Cluster systems. Unless otherwise specified, references to OpenVMS Clusters or clusters in this document are synonymous with VMSclusters.

In this manual, every use of DECwindows and DECwindows Motif refers to DECwindows Motif for OpenVMS software.

The following conventions are also 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 or GOLD x	A sequence such as PF1 x or GOLD x indicates that you must first press and release the key labeled PF1 or GOLD and then press and release another key or a pointing device button. GOLD key sequences can also have a slash (/), dash (--), or underscore (_) as a delimiter in EVE commands.
[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.)
...	Horizontal ellipsis points in examples indicate 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.
. . .	Vertical ellipsis points indicate 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, if you choose more than one option, you must enclose the choices in parentheses.
[ ]	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, braces indicate a required choice of options; you must choose one of the options listed.
text style	This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason. This style is also used to show user input in Bookreader versions of the manual.
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 device-name contains up to five alphanumeric characters).
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 type	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.

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

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

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

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

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.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

6018PRO.HTML