HP OpenVMS Systems Documentation

Order Number: AA--PWCBD--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.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 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:

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:

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

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