Compaq AA-PWCBD-TE 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 Ofﬁce. 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. Conﬁdential 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.

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 Speciﬁcations . . ................................ 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 Qualiﬁers ................... 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 Unspeciﬁed Data Type ........................................ 3–21

3.13 Widget Data Type ........................................... 3–22

3.14 Window Data Type ........................................... 3–22

3.14.1 Deﬁning 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

4.4 Identiﬁers . ................................................ 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 Predeﬁned 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

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 Deﬁned DECTPU Callback Routines and

Application-Level Callback Action Routines .................. 5–8

5.2.4.3 Internally Deﬁned DECTPU Callback Routines with UIL ....... 5–8

5.2.4.4 Internally Deﬁned DECTPU Callback Routines with Widgets Not

Deﬁned 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

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 Speciﬁcations 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

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, identiﬁers, variables, constants, and reserved words, such as DECTPU language statements.

Preface

• 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. Please send comments to either of the following addresses:

Internet openvmsdoc@compaq.com

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/x A sequence such as Ctrl/x indicates that you must hold down

PF1 x A sequence such as PF1 x indicates that you must ﬁrst press

Return

. . . A horizontal ellipsis in examples indicates one of the following

. . .

( ) In command format descriptions, parentheses indicate that you

[ ] In command format descriptions, brackets indicate optional

[|] In command format descriptions, vertical bars separating

{ } In command format descriptions, braces indicate required

the key labeled Ctrl while you press another key or a pointing device button.

and release the key labeled PF1 and then press and release another key or a pointing device button.

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.

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.

must enclose the options in parentheses if you choose more than one.

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 ﬁle speciﬁcation or in the syntax of a substring speciﬁcation in an assignment statement.)

items inside brackets indicate that you choose one, none, or more than one of the options.

elements; you must choose one of the options listed.

bold text This text style represents the introduction of a new term or the

italic text Italic text indicates important information, complete titles

UPPERCASE TEXT Uppercase text indicates a command, the name of a routine,

Monospace text

- A hyphen at the end of a command format description,

numbers All numbers in text are assumed to be decimal unless

name of an argument, an attribute, or a reason.

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 predeﬁned code for the device type).

the name of a ﬁle, 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

identiﬁes the following elements: keywords, the names of independently compiled external functions and ﬁles, syntax summaries, and references to variables or identiﬁers introduced in an example.

command line, or code line indicates that the command or statement continues on the following line.

otherwise noted. Nondecimal radixes—binary, octal, or hexadecimal—are explicitly indicated.

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 speciﬁc 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 deﬁnition

• 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

EVE

Editor

D E C T P U

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.

ZK−6545−GE

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 ﬂoating-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) ﬁles just as you would use programs in any other language with UIL ﬁles. For an example of a DECTPU program and a UIL ﬁle 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 ﬁles 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 efﬁcient 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

User−Written

Extensions

to EVE

User−Written

Application

D E C T P U

You can implement extensions to EVE with any of the following:

• A DECTPU command ﬁle (DECTPU source code)

• A DECTPU section ﬁle (compiled DECTPU code in binary form)

• An initialization ﬁle (commands in a format that EVE can process)

Because a DECTPU section ﬁle is already compiled, startup time for your editor or application is shorter when you use a section ﬁle than when you use a command ﬁle or an initialization ﬁle. Section 2.1.2 contains more information on startup ﬁles.

To implement an editor or application that is entirely user written, use a section ﬁle. Chapter 5 contains more information on DECTPU command ﬁles, section ﬁles, and initialization ﬁles. The DEC Text Processing Utility Reference Manual contains information on layering applications on DECTPU.

EVE

Editor

ZK−6544−GE

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 ﬁle 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 deﬁnition, 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

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.

Overview of the DEC Text Processing Utility

1.4 DECTPU Language

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 qualiﬁer 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

The suggested path for learning to use DECTPU is to ﬁrst 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 deﬁnitions the editor uses. Then write DECTPU procedures to implement your extensions. Make sure that the DECTPU procedures you write do not conﬂict 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

Getting Started with DECTPU

This chapter describes the following:

• Invoking DECTPU on OpenVMS systems

• Invoking DECTPU from a DCL command procedure

• Invoking DECTPU from a batch job

• Using journal ﬁles

• Avoiding errors related to virtual address space

• Using OpenVMS command line qualiﬁers

2.1 Invoking DECTPU on OpenVMS Systems

On OpenVMS systems you can invoke DECTPU through the Digital Command Language (DCL).

The basic DCL command for invoking DECTPU with EVE (the default editor) is as follows:

$ EDIT/TPU

To invoke DECTPU from DCL, type the command EDIT/TPU, optionally followed by the name of your ﬁle:

$ EDIT/TPU text_file.lis

This command opens TEXT_FILE.LIS for editing. If you are using the EVE editor, Compaq suggests that you create a symbol like

the following one to simplify invoking EVE:

$ EVE == "EDIT/TPU"

When you invoke DECTPU with the preceding command, you are usually placed in EVE, the default editor. However, you should check that your system manager has not overridden this default.

You can specify multiple input ﬁles on the DECTPU command line. The ﬁles must be separated by commas. The maximum number of ﬁles you can specify is

10. For the ambiguous ﬁle names, EVE displays a warning message.

Getting Started with DECTPU 2–1

Getting Started with DECTPU

2.1 Invoking DECTPU on OpenVMS Systems

2.1.1 Default File Speciﬁcations

Table 2–1 lists the default TPU and EVE ﬁle speciﬁcations on OpenVMS systems.

Table 2–1 Default File Speciﬁcations on OpenVMS Systems

File OpenVMS File Speciﬁcation

Section SYS$SHARE:TPU$SECTION.TPU$SECTION Command TPU$COMMAND.TPU Init SYS$DISK:EVE$INIT.EVE Init SYS$LOGIN:EVE$INIT.EVE Debugger SYS$SHARE:TPU$DEBUG.TPU Keystroke journal SYS$DISK:.TJL Buffer-change journal SYS$SCRATCH:.TPU$JOURNAL Buffer-change journal TPU$JOURNAL:.TPU$JOURNAL Work SYS$SCRATCH:.TPU$WORK Motif Resource SYS$LIBRARY:.UID Application defaults DECW$SYSTEM_DEFAULTS:.DAT Application defaults DECW$USER_DEFAULTS:.DAT EVE Motif resource SYS$SHARE:EVE$WIDGETS.UID EVE sources SYS$EXAMPLES:EVE$*.*

These directory and ﬁle type defaults are added by the Motif Resource Manager if missing from the

ﬁle speciﬁcation.

xxxxxx = sufﬁx from mktemp(3). Note that this ﬁle is invisible.

These X resource ﬁles are used only by dmtpu and dxtpu.

OpenVMS system managers should note that the OpenVMS systemwide logical name is deﬁned as TPU$SECTION to point to EVE$SECTION.TPU$SECTION. You can modify this logical to use a different default editing interface.

2.1.2 Startup Files

Command ﬁles and section ﬁles can create or customize a DECTPU editor or application. Initialization ﬁles can customize EVE or other layered applications by using EVE or other application-speciﬁc commands, settings, and key bindings.

A command ﬁle is a ﬁle that contains DECTPU source code. A command ﬁle has the ﬁle type .TPU and is used with the DECTPU /COMMAND=ﬁlespec qualiﬁer. DECTPU tries to read a command ﬁle unless you specify /NOCOMMAND. The default command ﬁle is the ﬁle called TPU$COMMAND.TPU in your current directory, if such a ﬁle exists. You can specify a different ﬁle by deﬁning the logical name TPU$COMMAND.

A section ﬁle is the compiled form of DECTPU source code. It is a binary ﬁle that has the default ﬁle type .TPU$SECTION. It is used with the qualiﬁer /SECTION=ﬁlespec. The default section ﬁle is TPU$SECTION.TPU$SECTION in the area SYS$SHARE. The systemwide logical name TPU$SECTION is deﬁned as EVE$SECTION. This deﬁnition causes the EVE editor to be invoked by default when you use the DCL command EDIT/TPU. You must specify a different section ﬁle (for example, /SECTION= my_section_ﬁle) or /NOSECTION if you do not want to use the EVE interface.

2–2 Getting Started with DECTPU

Getting Started with DECTPU

2.1 Invoking DECTPU on OpenVMS Systems

Note

When you invoke DECTPU with the /NOSECTION qualiﬁer, DECTPU does not use any binary ﬁle to provide an interface. Even the Return and Delete keys are not deﬁned. Use /NOSECTION when you are running a standalone command ﬁle or when you are creating a new section ﬁle and do not want the procedures, variables, and deﬁnitions from an existing section ﬁle to be included. See Section 2.6 and Chapter 5 for more information on /NOSECTION.

An initialization ﬁle contains commands for a DECTPU-based application. For example, an initialization ﬁle for EVE can contain commands that deﬁne keys or set margins. Initialization ﬁles are easy to create, but they cause DECTPU to start up somewhat more slowly than section and command ﬁles do. To invoke an initialization ﬁle, use the /INITIALIZATION qualiﬁer. For more information on using initialization ﬁles, see Chapter 5.

You can use either a command ﬁle or a section ﬁle, or both, to customize or extend an existing interface. Generally, you use a command ﬁle for minor customization of an interface. Because startup time is faster with a section ﬁle, you should use a section ﬁle when the customization is lengthy or complex, or when you are creating an interface that is not layered on an existing editor or application. You can use an initialization ﬁle only if your application supports the use of such a ﬁle.

The source ﬁles for EVE are in SYS$EXAMPLES. To see a list of the EVE source ﬁles, type the following at the DCL prompt:

$ DIRECTORY SYS$EXAMPLES:EVE$*.TPU

If you cannot ﬁnd these ﬁles on your system, see your system manager. Chapter 5 describes how to write and process command ﬁles and section ﬁles.

2.2 Invoking DECTPU from a DCL Command Procedure

There are two reasons that you might want to invoke DECTPU from a command procedure:

• To set up a special environment for interactive editing

• To create a noninteractive, DECTPU-based application

The following sections explain how to do this.

2.2.1 Setting Up a Special Editing Environment

You can run DECTPU with a special editing environment by writing a DCL command procedure that ﬁrst establishes the environment that you want and then invokes DECTPU. In such a command procedure, you must deﬁne SYS$INPUT to have the same value as SYS$COMMAND because DECTPU signals an error if SYS$INPUT is not deﬁned as the terminal. To prevent such an error, place the following statement in the command procedure setting up the environment:

$ DEFINE/USER SYS$INPUT SYS$COMMAND

Getting Started with DECTPU 2–3

Getting Started with DECTPU

2.2 Invoking DECTPU from a DCL Command Procedure

Example 2–1 shows a DCL command procedure that ‘‘remembers’’ the last ﬁle that you were editing and uses it as the input ﬁle for DECTPU. When you edit a ﬁle, the ﬁle name you specify is saved in the DCL symbol last_ﬁle_edited. If you do not specify a ﬁle name when you invoke the editor the next time, the ﬁle name from the previous session is used.

Example 2–1 DCL Command Procedure FILENAME.COM

$ IF P1 .NES. "" THEN last_file_edited == P1 $ WRITE SYS$OUTPUT "*** ’’last_file_edited’ ***" $ DEFINE/USER SYS$INPUT SYS$COMMAND $ EDIT/TPU/COMMAND=DISK$:[USER]TPU$COMMAND.TPU ’last_file_edited’

Example 2–2 establishes an environment that speciﬁes tab stop settings for FORTRAN programs.

Example 2–2 DCL Command Procedure FORTRAN_TS.COM

$ IF P1 .EQS. "" THEN GOTO REGULAR_INVOKE $ last_file_edited == P1 $ FTN_TEST = F$FILE_ATTRIBUTES (last_file_edited,"RAT") $ IF FTN_TEST .NES. "FTN" THEN GOTO REGULAR_INVOKE $ FTN_INVOKE: $ DEFINE/USER SYS$INPUT SYS$COMMAND $ EDIT/TPU/COMMAND=FTNTABS ’last_file_edited’ $ GOTO TPU_DONE $ REGULAR_INVOKE: $ DEFINE/USER SYS$INPUT SYS$COMMAND $ EDIT/TPU/ ’last_file_edited’ $ TPU_DONE:

2.2.2 Creating a Noninteractive Application

In some situations, you may want to put all of your editing commands in a ﬁle and have them read from the ﬁle rather than entering the commands interactively. You may also want DECTPU to perform the edits without displaying them on the screen. You can do this type of editing from a batch job; or, if you want to see the results of the editing session displayed on your screen, you can do this type of editing from a DCL command procedure. Even though the edits are not displayed on your screen as they are being made, your terminal is not free while the command procedure is executing.

Example 2–3 shows a DCL command procedure named INVISIBLE_TPU.COM, which contains a single command line that uses the following qualiﬁers to invoke DECTPU:

• /NOSECTION—This qualiﬁer prevents DECTPU from using a section ﬁle. All procedures and key deﬁnitions must be speciﬁed in a command ﬁle.

• /COMMAND=gsr.tpu—This qualiﬁer speciﬁes a command ﬁle that contains the code to be executed (GSR.TPU).

• /NODISPLAY—This qualiﬁer suppresses screen display.

2–4 Getting Started with DECTPU

Getting Started with DECTPU

2.2 Invoking DECTPU from a DCL Command Procedure

Example 2–3 DCL Command Procedure INVISIBLE_TPU.COM

! This command procedure invokes DECTPU without an editor. ! The file GSR.TPU contains the edits to be made. ! Specify the file to which you want the edits made as p1. ! $ EDIT/TPU/NOSECTION/COMMAND=gsr.tpu/NODISPLAY ’p1’ !

The DECTPU command ﬁle GSR.TPU, which is used as the ﬁle speciﬁcation for the /COMMAND qualiﬁer, performs a search through the current buffer and replaces a string or a pattern with a string. Example 2–4 shows the ﬁle GSR.TPU. GSR.TPU does not create or manipulate any windows.

Example 2–4 DECTPU Command File GSR.TPU

PROCEDURE global_search_replace (str_or_pat, str2) ! This procedure performs a search through the current

! buffer and replaces a string or a pattern with a new string LOCAL src_range, replacement_count; ! Return to caller if string not found

ON_ERROR

msg_text := FAO (’Completed !UL replacement!%S’, replacement_count); MESSAGE (msg_text); RETURN;

ENDON_ERROR; replacement_count := 0; LOOP

src_range := SEARCH (str_or_pat, FORWARD); ! Search returns a range if found ERASE (src_range); ! Remove first string POSITION (END_OF (src_range)); ! Move to right place COPY_TEXT (str2); ! Replace with second string

replacement_count := replacement_count + 1; ENDLOOP; ENDPROCEDURE; ! global_search_replace

! Executable statements input_file := GET_INFO (COMMAND_LINE, "file_name"); main_buffer:= CREATE_BUFFER ("main", input_file); POSITION (BEGINNING_OF (main_buffer)); global_search_replace ("xyz$_", "user$_"); pat1:= "" & LINE_BEGIN & "t"; POSITION (BEGINNING_OF (main_buffer)); global_search_replace (pat1, "T"); WRITE_FILE (main_buffer, "newfile.dat"); QUIT;

To use the DCL command procedure INVISIBLE_TPU.COM interactively, invoke it with the DCL command @ (at sign). For example, to use INVISIBLE_ TPU.COM interactively on a ﬁle called MY_FILE.TXT, type the following at the DCL prompt:

$ @invisible_tpu my_file.txt

You must explicitly write out any modiﬁed buffers before leaving the editor with QUIT or EXIT. If you use QUIT before writing out such buffers, DECTPU quits without saving the modiﬁcations. If you use EXIT, DECTPU asks if it should write the ﬁle before exiting.

Getting Started with DECTPU 2–5

Getting Started with DECTPU

2.3 Invoking DECTPU from a Batch Job

If you want your edits to be made in batch rather than at the terminal, you can use the DCL command SUBMIT to send your job to a batch queue.

For example, if you want to use the ﬁle GSR.TPU (shown in Example 2–4) to make edits in batch mode to a ﬁle called MY_FILE.TXT, enter the following command:

$ SUBMIT invisible_tpu.COM/LOG=invisible_tpu.LOG/parameter=my_file.txt

This job is then entered in the default batch queue for your system. The results are sent to the log ﬁle that the batch job creates.

In batch DECTPU, EXIT is the same as QUIT.

2.4 Using Journal Files

Journal ﬁles help you to recover your work when the system fails. This section discusses the journaling methods you can use with DECTPU.

DECTPU offers two journaling methods:

• Keystroke journaling

• Buffer-change journaling You can use both keystroke and buffer-change journaling at the same time (except

on DECwindows, where you can use only buffer-change journaling). To turn on keystroke journaling, the application uses the JOURNAL_OPEN built-in.

The application layered on DECTPU, not the DECTPU engine, determines what kind of journaling is turned on and under what conditions. Table 2–2 shows the journaling behavior established by EVE.

Table 2–2 Journaling Behavior Established by EVE

Effect on

OpenVMS Qualiﬁer

None speciﬁed Disabled Enabled. /JOURNAL Disabled Enabled. /JOURNAL = ﬁlename Enabled Enabled. /NOJOURNAL Disabled Disabled. However, you can use SET

Journal ﬁles contain a record of all information being edited. Therefore, when editing ﬁles that contain secure or conﬁdential data, be sure to keep the journal ﬁles secure as well.

You must use the same major version of DECTPU to recover the journal that you used to create it.

Keystroke Journaling Effect on Buffer-Change Journaling

(JOURNALING) to enable buffer-change journaling.

Caution

2–6 Getting Started with DECTPU

2.4.1 Keystroke Journaling

In keystroke journaling, DECTPU keeps track of each keystroke made during a session, regardless of which buffer is in use. If a system interruption occurs during a session, you can reconstruct the work done during the session.

To determine the name of the keystroke journal ﬁle, use a statement similar to the following:

filename := GET_INFO (SYSTEM, "journal_file");

For more information on using a keystroke journal ﬁle for recovery, see Section 2.6.8 and the Extensible Versatile Editor Reference Manual.

Compaq strongly recommends the use of buffer-change journaling rather than keystroke journaling.

To reconstruct your work, use the /JOURNAL and /RECOVER qualiﬁers. The following example shows system recovery on a ﬁle called JACKI.SDML:

$ EDIT/TPU JACKI.SDML /JOURNAL /RECOVER

Getting Started with DECTPU

2.4 Using Journal Files

Note

2.4.2 Buffer-Change Journaling

Buffer-change journaling creates a separate journal ﬁle for each text buffer. The application can use the enhanced SET (JOURNALING) built-in to direct DECTPU to establish and maintain a separate journal ﬁle for any buffer or buffers created during the session. The application programmer or user can also use the SET (JOURNALING) built-in to turn journaling off or on for a given buffer during a session.

In the buffer’s journal ﬁle, DECTPU keeps track of the following record attributes (and any changes made to them):

• Left margin setting

• Modiﬁability or unmodiﬁability

• Display value The journal ﬁle also tracks the following:

• Characters inserted in and deleted from a record (including the location where the change took place)

• Records inserted in and deleted from a buffer (including the location where the change took place)

To determine whether buffer-change journaling is turned on, use the following statement:

status := GET_INFO (buffer_name, "journaling");

For more information on record attributes and display values, see the descriptions of the SET (RECORD_ATTRIBUTE) and SET (DISPLAY_VALUE) built-in procedures in the DEC Text Processing Utility Reference Manual.

Buffer-change journaling does not keep a record of all keystrokes performed while editing a given buffer.

Getting Started with DECTPU 2–7

Getting Started with DECTPU

2.4 Using Journal Files

2.4.3 Buffer-Change Journal File-Naming Algorithm

By default, DECTPU creates the buffer-change journal ﬁle name by using the following algorithm:

1. Converts all characters in the buffer name that are not alphanumeric, a dollar sign, underscore, or hyphen to underscores

2. Truncates the resulting ﬁle name to 39 characters

3. Adds the ﬁle type .TPU$JOURNAL

For example, a buffer named TEST.BAR has a default journal ﬁle name of TEST_ BAR.TPU$JOURNAL.

DECTPU puts all journal ﬁles in the directory deﬁned by the logical name TPU$JOURNAL. By default, this logical is deﬁned as SYS$SCRATCH. You can reassign this logical name. For example, if you want journal ﬁles written to the current default directory, deﬁne TPU$JOURNAL as [].

2.5 Avoiding Errors Related to Virtual Address Space

DECTPU manipulates data in a process’s virtual memory space. If the space required by the DECTPU images, data structures, and ﬁles in memory exceeds the virtual address space, DECTPU tries to write part of the data to the work ﬁle, thus freeing up space for other parts of the data that it needs immediately.

If the work ﬁle is full, DECTPU attempts to return either a TPU$_GETMEM or TPU$_NOCACHE error message. Although you may be able to free up some space by deleting unused buffers, Compaq recommends that you terminate the DECTPU session if you encounter either of these errors. You can then start a new session with fewer or smaller buffers. Alternatively, you may want to put the work ﬁle on a disk that contains more free space. Use one of the following methods to do this:

• Redeﬁne TPU$WORK to point to the disk with more free space.

• Invoke DECTPU with the /WORK=ﬁlename qualiﬁer.

DECTPU may be unable to signal an error when it frees up memory by writing to the work ﬁle. In this case, DECTPU aborts with a fatal internal error.

You may be able to avoid writing to the work ﬁle by increasing the virtual address space available to a process. The virtual address space is controlled by the following two factors:

• The SYSGEN parameter VIRTUALP AGECNT

• The page ﬁle quota of the account you are using

The VIRTUALPAGECNT parameter controls the number of virtual pages that can be mapped for a process. For more information on VIRTUALPAGECNT, see the description of this parameter in the OpenVMS documentation on the System Generation Utility (SYSGEN).

The page ﬁle quota controls the number of pages in the system paging ﬁle that can be allocated to your process. For more information on the page ﬁle quota, see the description of the /PGFLQUOTA qualiﬁer in the OpenVMS documentation on the Authorize Utility (AUTHORIZE).

You may need to modify both the VIRTUALPAGECNT parameter and the page ﬁle quota to enlarge the virtual address space.

2–8 Getting Started with DECTPU

Getting Started with DECTPU

2.5 Avoiding Errors Related to Virtual Address Space

DECTPU keeps strings in a different virtual pool than it does other memory. Once DECTPU starts writing to the work ﬁle, the size of the string memory pool is ﬁxed. DECTPU cannot write strings to the work ﬁle, so if it needs to allocate more space in the string memory pool, it will fail with a fatal internal error. If you encounter this problem, you can expand the string memory pool during startup by preallocating several large strings. The following example shows how to do this:

PROCEDURE preallocate_strings LOCAL

str_len, string1, string2;

str_len := 65535; string1 := ’a’ * str_len; string2 := string1; ENDPROCEDURE;

2.6 Using OpenVMS EDIT/TPU Command Qualiﬁers

The DCL command EDIT/TPU has qualiﬁers for setting attributes of DECTPU or an application layered on DECTPU. The qualiﬁers fall into the following two categories:

• Qualiﬁers handled by DECTPU Qualiﬁers in this category have their defaults set by DECTPU.

• Qualiﬁers handled by the application layered on DECTPU Some qualiﬁers in this category have their defaults set entirely by DECTPU;

some have their defaults set entirely by the layered application, and some have their defaults set partly by each.

The following sections present the qualiﬁers in alphabetical order, giving a detailed description of each. The examples in the following sections show the qualiﬁers directly after the EDIT/TPU command and before the input ﬁle speciﬁcation. You can place the qualiﬁers anywhere on the command line after EDIT/TPU. These sections show the defaults that are set if you use EVE. They also explain how EVE handles each qualiﬁer that can be processed by a layered application. Applications not based on EVE may handle qualiﬁers differently.

2.6.1 /CHARACTER_SET

/CHARACTER_SET=DEC_MCS (default)

The /CHARACTER_SET qualiﬁer determines the character set you want DECTPU to use to display 8-bit characters. The choice of character set affects how DECTPU performs the following operations on characters:

• Converting to lowercase

• Converting to uppercase

• Inverting case

• Removing diacritical marks

• Converting to uppercase and removing diacritical marks

Getting Started with DECTPU 2–9

Getting Started with DECTPU

2.6 Using OpenVMS EDIT/TPU Command Qualiﬁers

The choice of character set also affects how your text appears when printed. For the text displayed in DECTPU to look the same when printed, you must choose the same character set for both DECTPU and the printer.

There are two ways to specify the character set you want to use:

• Deﬁne the TPU$CHARACTER_SET logical name to specify the character set. This lets you use that character set for all editing sessions—including

when you invoke DECTPU within MAIL or other utilities. You can put the deﬁnition in your LOGIN.COM ﬁle. For example, the following commands deﬁne TPU$CHARACTER_SET as ISO_LATIN1 and then use that character set to invoke DECTPU:

$ DEFINE TPU$CHARACTER_SET ISO_LATIN1 $ EDIT/TPU

• Use /CHARACTER_SET= and specify the character set on the command line. This overrides any deﬁnition of the TPU$CHARACTER_SET logical name.

By default, DECTPU uses the DEC_MCS character set. For example, the following command speciﬁes the GENERAL character set to invoke DECTPU. DECTPU uses the current character set to display 8-bit characters and does not use the default DEC Supplemental Graphics character set.

If the character set you specify either with /CHARACTER_SET or by deﬁning TPU$CHARACTER_SET is invalid, the editing session is aborted, returning you to the DCL level.

Table 2–3 shows the values you can specify with the /CHARACTER_SET qualiﬁer or the TPU$CHARACTER_SET logical name.

Table 2–3 Character Set Values You Can Set with /CHARACTER_SET

Value Description

DEC_MCS This is the default setting that uses the DEC Supplemental

ISO_LATIN1 This character set contains supplemental and multinational

GENERAL DECTPU does not specify a character set for 8-bit characters.

2.6.2 /COMMAND

$ EDIT/TPU/CHARACTER_SET=general

Graphics character set containing supplemental and multinational characters, such as letters with accents and umlauts.

characters that contain LATIN1 characters, such as the nonbreaking space, multiplication and division signs, and the trademark sign.

8-bit characters are displayed the same as they were before you started DECTPU.

/COMMAND[[=ﬁlespec]] /NOCOMMAND /COMMAND=TPU$COMMAND.TPU (default)

The /COMMAND qualiﬁer determines whether DECTPU compiles and executes a command ﬁle (a ﬁle of DECTPU procedures and statements) at startup time. Command ﬁles extend or modify a DECTPU-based application or create a new application. The default ﬁle type for DECTPU command ﬁles is .TPU. You cannot use wildcards in the ﬁle speciﬁcation.

2–10 Getting Started with DECTPU

Getting Started with DECTPU

2.6 Using OpenVMS EDIT/TPU Command Qualiﬁers

By default, DECTPU tries to read a command ﬁle called TPU$COMMAND.TPU in your default directory. You can use a full ﬁle speciﬁcation after the /COMMAND qualiﬁer or deﬁne the logical name TPU$COMMAND to point to a command ﬁle other than the default.

To determine whether you speciﬁed /COMMAND on the DCL command line, use the following call in the application:

x := GET_INFO (COMMAND_LINE, "command");

The preceding call returns 1 if /COMMAND was speciﬁed, 0 otherwise. To fetch the name of the command ﬁle speciﬁed on the command line, use the following call:

x := GET_INFO (COMMAND_LINE, "command_file");

For more information on GET_INFO, see the DEC Text Processing Utility Reference Manual.

The following command causes DECTPU to read a command ﬁle named SYS$LOGIN:MY_TPU$COMMAND.TPU and uses LETTER.RNO as the input ﬁle for an editing session:

$ EDIT/TPU/COMMAND=sys$login:my_tpu$command.tpu letter.rno

To prevent DECTPU from processing a command ﬁle, use the /NOCOMMAND qualiﬁer. If you usually invoke DECTPU without a command ﬁle, deﬁne a symbol similar to the following:

$ EVE == "EDIT/TPU/NOCOMMAND"

Using /NOCOMMAND when you do not want to use a command ﬁle decreases startup time by eliminating the search for a command ﬁle.

If you specify a command ﬁle that does not exist, DECTPU terminates the editing session and returns you to the DCL command level.

For more information on writing and using command ﬁles, see Chapter 5.

2.6.3 /CREATE

The /CREATE qualiﬁer controls whether a DECTPU-based application creates a new ﬁle when the speciﬁed input ﬁle is not found. If you do not specify /CREATE or /NOCREATE on the command line, DECTPU sets the default to /CREATE but does not specify a default name for the ﬁle to be created.

The application layered on DECTPU is responsible for handling this qualiﬁer. To determine if you speciﬁed /CREATE on the DCL command line, include the

following call in the application:

/CREATE (default) /NOCREATE

x := GET_INFO (COMMAND_LINE, "create");

The preceding call returns 1 if /CREATE was speciﬁed, 0 otherwise. For more information on GET_INFO, see the DEC Text Processing Utility

Reference Manual.

Getting Started with DECTPU 2–11

Getting Started with DECTPU

2.6 Using OpenVMS EDIT/TPU Command Qualiﬁers

By default, EVE creates a new ﬁle if the speciﬁed input ﬁle does not exist. If you use /NOCREATE and specify an input ﬁle that does not exist, EVE aborts the editing session and returns you to the DCL command level. For example, if your default device and directory are DISK$:[USER] and you specify a nonexistent ﬁle, NEWFILE.DAT, your command and EVE’s response would be as follows:

$ EDIT/TPU/NOCREATE newfile.dat Input file does not exist: DISK$:[USER]NEWFILE.DAT;

2.6.4 /DEBUG

/DEBUG[[=debug_source_ﬁlename]] /NODEBUG (default)

The /DEBUG qualiﬁer determines whether DECTPU loads, compiles, and executes a ﬁle implementing a DECTPU debugger. If /DEBUG is speciﬁed, DECTPU reads, compiles, and executes the contents of a debugger ﬁle before executing the procedure TPU$INIT_PROCEDURE and before executing the command ﬁle.

For more information on the DECTPU initialization sequence, see Chapter 5. By default, DECTPU does not load a debugger. If you specify that a debugger

is to be loaded but do not supply a ﬁle speciﬁcation, DECTPU loads the ﬁle SYS$SHARE:TPU$DEBUG.TPU.

For more information on how to use the default DECTPU debugger, see Chapter 5.

To use a debugger ﬁle other than the default, use the /DEBUG qualiﬁer and specify the device, directory, and ﬁle name of the debugger to be used. If you specify only the ﬁle name, DECTPU searches SYS$SHARE for the ﬁle. You can deﬁne the logical name TPU$DEBUG to specify a ﬁle that contains a debugger program. Once you deﬁne this logical name, using /DEBUG without specifying a ﬁle calls the ﬁle speciﬁed by TPU$DEBUG.

2.6.5 /DISPLAY

To choose the DECwindows or the non-DECwindows version of DECTPU, use the /DISPLAY qualiﬁer on the DCL command line when you invoke DECTPU.

The /DISPLAY qualiﬁer is optional. By default, DECTPU uses /DISPLAY=CHARACTER_CELL, regardless of whether you are running DECTPU on a workstation or a terminal.

If you specify /DISPLAY=CHARACTER_CELL, DECTPU uses its character-cell screen manager, which implements the non-DECwindows version of DECTPU by running in a DECterm terminal emulator or on a physical terminal.

If you specify /DISPLAY=DECWINDOWS, and if the DECwindows environment is available, DECTPU uses the DECwindows screen manager, which creates a DECwindows window in which to run DECTPU.

/NODISPLAY

If you specify /DISPLAY=DECWINDOWS and the DECwindows environment is not available, DECTPU uses its character-cell screen manager to implement the non-DECwindows version of DECTPU.

For more information about the difference between a DECwindows window and a DECTPU window, see Chapter 5.

2–12 Getting Started with DECTPU

The /NODISPLAY qualiﬁer causes DECTPU to run without using the screen display and the keyboard functions of a terminal. Use /NODISPLAY in the following cases:

• When running DECTPU procedures in a batch job

• When using DECTPU on an unsupported terminal When you use /NODISPLAY, all operations continue as usual, except that no

output occurs. (The only exception is that information usually put into the message buffer will appear on SYS$OUTPUT if no message buffer is available.)

The following command causes DECTPU to edit the ﬁle MY_BATCH_FILE.RNO without using terminal functions such as screen display:

$ EDIT/TPU/NODISPLAY my_batch_file.rno

2.6.6 /INITIALIZATION

/INITIALIZATION[[=ﬁlespec]] (default) /NOINITIALIZATION

The /INITIALIZATION qualiﬁer determines whether the DECTPU-based application being run executes a ﬁle of initialization commands. The application layered on DECTPU is responsible for processing this qualiﬁer.

Getting Started with DECTPU

2.6 Using OpenVMS EDIT/TPU Command Qualiﬁers

To determine whether you speciﬁed /INITIALIZATION on the DCL command line, use the following call in the application:

x := GET_INFO (COMMAND_LINE, "initialization");

The preceding call returns 1 if /INITIALIZATION was speciﬁed, 0 otherwise. To fetch the name of the initialization ﬁle speciﬁed on the command line, use the following call:

x := GET_INFO (COMMAND_LINE, "initialization_file");

For more information on GET_INFO, see the DEC Text Processing Utility Reference Manual.

If you do not specify any form of /INITIALIZATION on the DCL command line, DECTPU speciﬁes /INITIALIZATION but does not supply a default ﬁle speciﬁcation. The default ﬁle speciﬁcation for /INITIALIZATION is set by the application. Compaq recommends that a user-written application deﬁne the default ﬁle speciﬁcation of an initialization ﬁle by using the following format:

facility$init.facility

For example, the default initialization ﬁle for the EVE editor is EVE$INIT.EVE. In EVE, if you do not specify a device or directory, EVE ﬁrst checks the current

directory. If the speciﬁed (or default) initialization ﬁle is not there, EVE checks SYS$LOGIN. If EVE ﬁnds the speciﬁed (or default) initialization ﬁle, EVE executes the commands in the ﬁle.

For more information on using initialization ﬁles with EVE, see Chapter 5 and the Extensible Versatile Editor Reference Manual.

Getting Started with DECTPU 2–13

Getting Started with DECTPU

2.6 Using OpenVMS EDIT/TPU Command Qualiﬁers

2.6.7 /INTERFACE

The /INTERFACE qualiﬁer determines the interface or screen display you want (same as /DISPLAY). The default is CHARACTER_CELL.

For example, to invoke EVE with the DECwindows interface, use the following command:

$ EDIT/TPU /INTERFACE=DECWINDOWS

Then, if DECwindows is available, DECTPU displays the editing session in a separate window on your workstation screen and enables DECwindows features; for example, the EVE screen layout includes a menu bar and scroll bars. If DECwindows is not available, DECTPU works as if on a character-cell terminal.

2.6.8 /JOURNAL

/JOURNAL[[=input_ﬁle.TJL]] (default for EVE) /NOJOURNAL (default for DECTPU)

The /JOURNAL qualiﬁer determines whether DECTPU keeps a journal ﬁle of an editing session so you can recover the session if it is unexpectedly interrupted. DECTPU offers two forms of journaling:

• Keystroke—In a single journal ﬁle, keeps track of each keystroke you make, regardless of which buffer is in use when you press the key.

• Buffer-change—In a separate journal ﬁle, keeps track of changes made to buffers for each buffer created during the session.

The application layered on DECTPU is responsible for processing this qualiﬁer. To determine whether you speciﬁed /JOURNAL on the DCL command line, use

the following call in the application:

x := GET_INFO (COMMAND_LINE, "journal");

The preceding call returns 1 if /JOURNAL was speciﬁed, 0 otherwise. To determine whether buffer-change journaling is turned on for a buffer, use a

statement similar to the following:

status := GET_INFO (buffer_name, "journaling");

To determine the name of the keystroke journal ﬁle speciﬁed on the command line, use the following call:

x := GET_INFO (COMMAND_LINE, "journal_file");

For more information on GET_INFO, see the DEC Text Processing Utility Reference Manual.

In EVE, if you do not specify any form of /JOURNAL or specify /JOURNAL but not a journal ﬁle, buffer-change journaling is turned on. The buffer-change journal ﬁle’s default ﬁle type is .TPU$JOURNAL.

If you specify /JOURNAL=ﬁlename, then EVE also turns on keystroke journaling. The keystroke journal ﬁle’s default ﬁle type is .TJL.

To prevent EVE from creating either a keystroke or buffer-change journal ﬁle for an editing session, use the /NOJOURNAL qualiﬁer. For example, the following command causes EVE to turn off buffer-change journaling when you edit the input ﬁle MEMO.TXT:

2–14 Getting Started with DECTPU

Getting Started with DECTPU

2.6 Using OpenVMS EDIT/TPU Command Qualiﬁers

$ EDIT/TPU/NOJOURNAL memo.txt

If you are developing an application layered on DECTPU, you can use the built-in JOURNAL_OPEN to direct DECTPU to create a keystroke journal ﬁle for an editing session. Using JOURNAL_OPEN causes DECTPU to provide a 500-byte buffer in which to journal keystrokes. By default, DECTPU writes the contents of the buffer to the journal ﬁle when the buffer is full.

You can use the built-in procedure SET (JOURNALING) to turn on buffer-change journaling, even if you have used /NOJOURNAL to turn it off initially. You can also use SET (JOURNALING) to adjust the journaling frequency.

For more information on JOURNAL_OPEN and SET (JOURNALING), see the DEC Text Processing Utility Reference Manual. For more information on buffer-change journaling, see Section 2.4.

Once a keystroke journal ﬁle is created, use the /RECOVER qualiﬁer to direct DECTPU to process the commands in the keystroke journal ﬁle. For example, the following command causes DECTPU to recover a previous editing session on an input ﬁle named MEMO.TXT. Because the journal ﬁle has a name different from the input ﬁle name, both /JOURNAL and /RECOVER are used. The name of the keystroke journal ﬁle is MEMO.TJL:

$ EDIT/TPU/RECOVER/JOURNAL=memo.tjl memo.txt

In buffer-change journaling, to recover the changes made to a speciﬁed buffer, use the RECOVER_BUFFER built-in procedure.

For more information on RECOVER_BUFFER, see the DEC Text Processing Utility Reference Manual. For more information on how to recover from an interrupted EVE editing session, see the Extensible Versatile Editor Reference Manual.

2.6.9 /MODIFY

The /MODIFY qualiﬁer determines whether the ﬁrst user buffer in an editing session is modiﬁable. The application layered on DECTPU is responsible for processing /MODIFY.

To determine what form of the /MODIFY qualiﬁer was used on the DCL command line, use the following calls:

x := GET_INFO (COMMAND_LINE, "modify"); x := GET_INFO (COMMAND_LINE, "nomodify");

Note

Compaq strongly recommends the use of buffer-change journaling rather than keystroke journaling.

/MODIFY (default) /NOMODIFY

The ﬁrst statement returns 1 if /MODIFY was explicitly speciﬁed on the command line, 0 otherwise. The second statement returns 1 if /NOMODIFY was explicitly speciﬁed on the command line, 0 otherwise. If both statements return 0, then the application is expected to determine the default behavior.

For more information on GET_INFO, see the DEC Text Processing Utility Reference Manual.

Getting Started with DECTPU 2–15

Getting Started with DECTPU

2.6 Using OpenVMS EDIT/TPU Command Qualiﬁers

If you invoke EVE and do not specify /MODIFY, /NOMODIFY, /READ_ONLY, or /NOWRITE, EVE makes the ﬁrst user buffer of the editing session modiﬁable. If you specify /NOMODIFY, EVE makes the ﬁrst user buffer unmodiﬁable. Regardless of what qualiﬁers you use on the DCL command line, EVE makes all user buffers after the ﬁrst buffer modiﬁable.

If you do not specify either form of the /MODIFY qualiﬁer, EVE checks whether you have used any form of the /READ_ONLY or /WRITE qualiﬁer. By default, a read-only buffer is unmodiﬁable and a write buffer is modiﬁable. However, if you specify /READ_ONLY and /MODIFY or /NOWRITE and /MODIFY, the buffer is modiﬁable. Similarly, if you specify /WRITE and /NOMODIFY or /NOREAD_ ONLY and /NOMODIFY, the buffer is unmodiﬁable.

2.6.10 /OUTPUT

/OUTPUT[[=input_ﬁle.type]] (default) /NOOUTPUT

The /OUTPUT qualiﬁer determines whether the output of your DECTPU session is written to a ﬁle. The application layered on DECTPU is responsible for processing this qualiﬁer.

To determine whether you speciﬁed /OUTPUT on the DCL command line, use the following call in the application:

x := GET_INFO (COMMAND_LINE, "output");

The preceding call returns 1 if /OUTPUT was speciﬁed, 0 otherwise. To fetch the name of the output ﬁle speciﬁed on the command line, use the following call:

x := GET_INFO (COMMAND_LINE, "output_file");

For more information on GET_INFO, see the DEC Text Processing Utility Reference Manual.

If you do not specify any form of /OUTPUT on the DCL command line, DECTPU speciﬁes /OUTPUT but does not supply a default ﬁle speciﬁcation.

In EVE, when you use /OUTPUT, you can name the ﬁle created from the main buffer when you exit from DECTPU. For example, the following command causes DECTPU to read in a ﬁle called LETTER.RNO and to write the contents of the main buffer to the ﬁle NEWLET.RNO upon exiting from DECTPU:

$ EDIT/TPU/OUTPUT=newlet.rno letter.rno

If you use /OUTPUT= to specify an output ﬁle, EVE modiﬁes the buffer even if you do not modify the actual text. In this case, when you exit from EVE, EVE writes the buffer to the output ﬁle you specify.

By default, the output ﬁle has the same name as the input ﬁle, and the version number is one higher than the highest existing version of the input ﬁle. You can specify a different name for the output ﬁle by using the ﬁle speciﬁcation argument for the /OUTPUT qualiﬁer.

In EVE, specifying /NOOUTPUT causes EVE to suppress creation of an output ﬁle for the ﬁrst buffer of the editing session. Using /NOOUTPUT does not suppress creation of a journal ﬁle.

2–16 Getting Started with DECTPU

Using /NOOUTPUT, you can develop an application that lets you control the output of a ﬁle. For example, an application could be coded so that if you specify /NOOUTPUT on the DCL command line, DECTPU would set the NO_WRITE attribute for the main buffer and suppress creation of an output ﬁle for that buffer.

2.6.11 /READ_ONLY

/READ_ONLY /NOREAD_ONLY (default)

The /READ_ONLY qualiﬁer determines whether the application layered on DECTPU creates an output ﬁle from the contents of the main buffer if the contents are modiﬁed.

The processing of the /READ_ONLY qualiﬁer is interrelated with the processing of the /WRITE qualiﬁer. /READ_ONLY is equivalent to /NOWRITE; /NOREAD_ ONLY is equivalent to /WRITE.

DECTPU signals an error and returns control to DCL if DECTPU encounters either of the following combinations of qualiﬁers on the DCL command line:

• /READ_ONLY and /WRITE

Getting Started with DECTPU

2.6 Using OpenVMS EDIT/TPU Command Qualiﬁers

• /NOREAD_ONLY and /NO_WRITE The application layered on DECTPU is responsible for processing this qualiﬁer. To determine whether either the /READ_ONLY or /NOWRITE qualiﬁer was used

on the DCL command line, use the following call in an application:

x := GET_INFO (COMMAND_LINE, "read_only");

This statement returns 1 if /READ_ONLY or /NOWRITE was explicitly speciﬁed on the command line.

To determine whether either /NOREAD_ONLY or /WRITE was used on the DCL command line, use the following call in an application:

x := GET_INFO (COMMAND_LINE, "write");

This statement returns 1 if /NOREAD_ONLY or /WRITE was explicitly speciﬁed on the command line.

If both GET_INFO calls return false, the application is expected to determine the default behavior. For more information on GET_INFO, see the DEC Text Processing Utility Reference Manual.

In EVE, using the /READ_ONLY qualiﬁer is equivalent to using the /NOJOURNAL, /NOMODIFY, and /NOOUTPUT qualiﬁers. If you specify /READ_ ONLY, DECTPU does not maintain a journal ﬁle for your editing session, and the NO_WRITE and NO_MODIFY attributes are set for the main buffer. When a buffer is set to NO_WRITE, the contents of the buffer are not written out upon exit, regardless of whether the session is terminated with the EXIT built-in or the QUIT built-in. For example, if you want to edit a ﬁle called MEETING.MEM but not write out the contents when exiting or quitting, use the following command:

$ EDIT/TPU/READ_ONLY meeting.mem

In response to the /NOREAD_ONLY qualiﬁer, EVE writes out the buffer speciﬁed on the command line (if the buffer has been modiﬁed) when an EXIT command is issued. This is the default behavior.

Getting Started with DECTPU 2–17

Getting Started with DECTPU

2.6 Using OpenVMS EDIT/TPU Command Qualiﬁers

2.6.12 /RECOVER

/RECOVER /NORECOVER (default)

The /RECOVER qualiﬁer determines whether DECTPU reads a keystroke journal ﬁle at the start of an editing session to recover edits made during a prior interrupted editing session. For example, the following command causes DECTPU to recover the edits made in a previous EVE editing session on the ﬁle NOTES.TXT:

$ EDIT/TPU/RECOVER notes.txt

To determine whether you speciﬁed /RECOVER on the DCL command line, use the following call:

x := GET_INFO (COMMAND_LINE, "recover");

The preceding call returns 1 if /RECOVER was speciﬁed, 0 otherwise. For more information on GET_INFO, see the DEC Text Processing Utility

Reference Manual. DECTPU uses /RECOVER to recover a keystroke journal ﬁle only. In buffer-

change journaling, to recover the changes made to a speciﬁed buffer, use the RECOVER_BUFFER built-in procedure.

For more information on RECOVER_BUFFER, see the DEC Text Processing Utility Reference Manual.

If DECTPU encounters and executes the built-in procedure JOURNAL_OPEN while running a layered application, by default DECTPU opens the journal ﬁle for output only. If you specify /RECOVER when invoking DECTPU with a layered application, then when the built-in procedure JOURNAL_OPEN is executed, the keystroke journal ﬁle is opened for input and output. DECTPU opens the input ﬁle to restore whatever commands it contains. Then DECTPU continues to journal keystrokes for the rest of the editing session or until a statement that contains the built-in JOURNAL_CLOSE is executed.

When you recover an editing session, every ﬁle used during the session must be in the same state as it was at the start of the session being recovered. Each terminal characteristic must also be in the same state as it was at the start of the editing session being recovered. If you have changed the width or page length of the terminal, you must change the attribute back to the value it had at the start of the editing session you want to recover. Check especially the following values:

• Device type

• Edit mode

• 8-bit

• Page length

• Width

If the journal ﬁle has a different name from the input ﬁle, you must include both /JOURNAL and /RECOVER with the EDIT/TPU command. For example, if you want to use the keystroke journal ﬁle SAVE.TJL to recover the edits you made to a ﬁle called LETTER.DAT, enter the following command on the DCL command line:

2–18 Getting Started with DECTPU

$ EDIT/TPU/RECOVER/JOURNAL=save.TJL letter.dat

In EVE, you can use /RECOVER to recover either an editing session from a keystroke journal ﬁle or a single buffer from a buffer-change journal ﬁle. If you specify /JOURNAL=ﬁlename, EVE recovers from the speciﬁed keystroke journal ﬁle. Otherwise, EVE recovers from a buffer-change journal ﬁle that corresponds to the input parameter (or the buffer speciﬁed on the command line if no input parameter is speciﬁed).

For more information on journaling and recovery in EVE, see the Extensible Versatile Editor Reference Manual.

2.6.13 /SECTION

/SECTION[[=ﬁlespec]] /NOSECTION /SECTION=TPU$SECTION (default)

The /SECTION qualiﬁer determines whether DECTPU loads a section ﬁle. A section ﬁle is a startup ﬁle that contains key deﬁnitions and compiled procedures in binary form.

The default section ﬁle is TPU$SECTION. When DECTPU tries to locate the section ﬁle, DECTPU supplies a default directory of SYS$SHARE and a default ﬁle type of .TPU$SECTION. OpenVMS systems deﬁne the systemwide logical name TPU$SECTION as EVE$SECTION, so the default section ﬁle is the ﬁle that implements the EVE editor. To override the OpenVMS default, redeﬁne TPU$SECTION.

Getting Started with DECTPU

2.6 Using OpenVMS EDIT/TPU Command Qualiﬁers

You can specify a different section ﬁle. The preferred method is to deﬁne the logical name TPU$SECTION to point to a section ﬁle other than the default ﬁle. You can also supply a full ﬁle speciﬁcation for the /SECTION qualiﬁer. For example, if your device is called DISK$USER and your directory is called [SMITH], the following command causes DECTPU to read a section ﬁle called VT100INI.TPU$SECTION:

$ EDIT/TPU/SECTION=disk$user:[smith]vt100ini

If you omit the device and directory in the ﬁle speciﬁcation, DECTPU assumes the ﬁle is in SYS$SHARE. The section ﬁle must be located on the same node on which you are running DECTPU.

To determine whether /SECTION was speciﬁed on the DCL command line, use the following call in the application:

x := GET_INFO (COMMAND_LINE, "section");

The preceding call returns 1 if /SECTION was speciﬁed, 0 otherwise. To fetch the name of the section ﬁle speciﬁed on the command line, use the following call:

x := GET_INFO (COMMAND_LINE, "section_file");

For more information on GET_INFO, see the DEC Text Processing Utility Reference Manual.

You must compile the ﬁle used as the value for the /SECTION qualiﬁer. To do so, run the source code version of the ﬁle through DECTPU and then use the built-in procedure SAVE. This process converts the ﬁle to the proper binary form.

For more information on creating and using section ﬁles, see Chapter 5.

Getting Started with DECTPU 2–19

Getting Started with DECTPU

2.6 Using OpenVMS EDIT/TPU Command Qualiﬁers

If you specify the /NOSECTION qualiﬁer, DECTPU does not load a section ﬁle. Unless you use the /COMMAND qualiﬁer with /NOSECTION, DECTPU has no user interface and no keys are deﬁned. In this state, the only way to exit from DECTPU is to press Ctrl/Y. Typically, you use /NOSECTION when you create your own layered DECTPU application without EVE as a base.

2.6.14 /START_POSITION

/START_POSITION=(line,column) /START_POSITION=(1,1) (default)

The /START_POSITION qualiﬁer determines where the application layered on DECTPU positions the cursor.

2–20 Getting Started with DECTPU

DEC Text Processing Utility Data Types

A data type is a group of elements that ‘‘belong together’’; the elements are all formed in the same way and are treated consistently. The data type of a variable determines the operations that can be performed on it. The DECTPU data types are represented by the following keywords:

• ARRAY

• BUFFER

• INTEGER

• KEYWORD

• LEARN

• MARKER

• PATTERN

• PROCESS

• PROGRAM

• RANGE

• STRING

• UNSPECIFIED

• WIDGET

• WINDOW You use data types to interpret the contents of a variable. Unlike many

programming languages, DECTPU permits any variable to have any type of data as a value. DECTPU has no declaration statement to restrict the type of data that you can assign to a variable. DECTPU variables take on a data type when they are placed on the left-hand side of an assignment statement. The right-hand side of the assignment statement determines the data type of the variable.

Although you can construct variables freely, DECTPU built-in procedures require that their parameters be of speciﬁc data types. Each built-in procedure can operate only on certain data types. Some built-in procedures return a value of a certain data type when they are executed. The following sections describe the DECTPU data types.

DEC Text Processing Utility Data Types 3–1

DEC Text Processing Utility Data Types

3.1 Array Data Type

An array is a structure for storing and manipulating a group of elements. These elements can be of any data type. You create arrays with the CREATE_ARRAY built-in procedure. For example, the following statement creates the array new_array:

new_array := CREATE_ARRAY;

You can delete arrays with the DELETE built-in procedure. When you create an array, you can optionally direct DECTPU to allocate a

speciﬁed number of integer-indexed array elements. DECTPU processes this block of preallocated elements quickly. You can direct DECTPU to create such a block of elements only at the time you create the array.

The following statement creates the array int_array, directs DECTPU to allocate 10 sequential, integer-indexed elements to the array, and speciﬁes that the lowest index value should be 1:

int_array := CREATE_ARRAY (10, 1);

Regardless of whether you specify a preallocated block of elements, you can always add array elements dynamically. Dynamically added elements can be of any data type except learn, pattern, program, or unspeciﬁed. You can mix the data types of indexes in an array.

In the following code fragment, the array mix_array is created and the integer 1 is stored in the array element indexed by the marker mark1.

mix_array := CREATE_ARRAY; mark1 := MARK (NONE); mix_array {mark1} := 1; mix_array {"Kansas"} := "Toto";

You can index dynamic elements with integers, even if this means that the array ends up with more integer-indexed elements than you speciﬁed when you created the array. DECTPU does not process dynamically added integer-indexed elements as quickly as it processes preallocated elements.

To refer to an array element, use the name of an existing array variable followed by the array index enclosed in braces ( { } ) or parentheses ( ( ) ). For example, if you create an array and store it in the variable my_array, the following are valid element names:

my_array{2} my_array("fred")

To create an element dynamically for an existing array, use the new element as the target of an assignment statement. The following statement creates the element "string1" in the array my_array and assigns the element to the string

"Topeka":

my_array{"string1"} := "Topeka";

In the following example, the ﬁrst statement creates an integer-indexed array, int_array. The array has 10 elements; the ﬁrst element starts at index 1. The second statement stores a string in the ﬁrst integer-indexed element of the array. The third statement stores a buffer in the eighth element of the array. The fourth statement adds an integer-indexed element dynamically. This new element contains a string.

3–2 DEC Text Processing Utility Data Types

DEC Text Processing Utility Data Types

3.1 Array Data Type

int_array := CREATE_ARRAY (10, 1); int_array {1} := "Store a string in the first element"; int_array {8} := CURRENT_BUFFER; int_array {42} := "This is a dynamically created element.";

If you assign a value to an element that has not yet been created, then that element is dynamically created and both the index and the value are stored. Subsequent references to that element index return the stored value.

In most cases, if you reference an element that has not yet been created and you do not assign a value to the nonexistent element, DECTPU does not create the element. DECTPU simply returns the data type unspeciﬁed. However, if you reference a nonexistent element by passing the nonexistent element to a procedure, DECTPU adds a new element to the array, giving the element the index you pass to the procedure. DECTPU assigns to this new element the data type unspeciﬁed.

You can delete an element in the array by assigning the data type unspeciﬁed to the element. For example, the following statement deletes the element my_array

"fred"}:

{

my_array {"fred"} := TPU$K_UNSPECIFIED;

The following code fragment shows how you can ﬁnd all the indexes in an array:

the_index := GET_INFO (the_array, "FIRST"); LOOP

EXITIF the_index = TPU$K_UNSPECIFIED; . . . the_index := GET_INFO (the_array, "NEXT");

ENDLOOP;

DECTPU does not guarantee the order in which it will return the array indexes.

3.2 Buffer Data Type

A buffer is a work space for manipulating text. A buffer can be empty or it can contain text records. You can have multiple buffers. A value of the buffer data type is returned by the CREATE_BUFFER, CURRENT_BUFFER, and GET_INFO built-in procedures. CREATE_BUFFER is the only built-in procedure that creates a new buffer. CURRENT_BUFFER and GET_INFO return pointers to existing buffers.

The following statement makes the variable my_buf a variable of type buffer:

my_buf := CREATE_BUFFER ("my_buffer");

Note

When you use a buffer as a parameter for DECTPU built-in procedures, you must use as the parameter the variable to which you assigned the buffer. For example, if you want to erase the contents of the buffer created in the preceding statement, enter the following:

ERASE (my_buf);

DEC Text Processing Utility Data Types 3–3

DEC Text Processing Utility Data Types

3.2 Buffer Data Type

In this statement, my_buf is the identiﬁer for the variable my_buf. The string

"my_buffer" is the name associated with the buffer. The distinction between the

name of the buffer variable and the name of the buffer is useful when you are developing an application layered on DECTPU. For example, the application can use an internal buffer name such as main_buffer to manipulate a given buffer (such as the main buffer in EVE). However, the application can associate the name of your input ﬁle with the buffer, making it easier for you to remember which buffer contains the contents of a given ﬁle.

If you want to delete the buffer itself, use the DELETE built-in procedure with the buffer variable as the parameter.

More than one buffer variable can represent the same buffer. The following statement causes both my_buf and old_buf to point to the same buffer:

old_buf := my_buf;

A buffer remains in DECTPU’s internal list of buffers even when there are no variables pointing to it. You can use the GET_INFO built-in procedure to retrieve buffers from DECTPU’s internal list.

Creating a buffer does not cause the information contained in the buffer to become visible on the screen. The buffer must be associated with a window that is mapped to the screen for the buffer contents to be visible. Editing can take place in a buffer even if the buffer is not mapped to a window on the screen.

The current buffer contains the active editing point. The editing point can be different from the cursor position, and often each is in a different location. When the current buffer is associated with a visible window (one that is mapped to the screen), the editing point and the cursor position are usually the same.

At present, a line in a buffer can contain up to 32767 characters. If you try to create a line that is longer than 32767 characters, DECTPU truncates the inserted text and inserts only the amount that ﬁlls the line to 32767 characters. If you try to read a ﬁle that contains lines longer than 32767 characters, DECTPU truncates all characters after the 32767 characters.

You can associate a single buffer with 0 to 255 windows for editing purposes. You can have a buffer visible in two windows so that you can look at two separate parts of the same ﬁle. For example, you could display a set of declarations in one window and code that uses the declarations in another window. Edits made to a buffer show up in all windows to which that buffer is mapped and in which the editing point is visible.

3.3 Integer Data Type

DECTPU uses the integer data type to represent numeric data. DECTPU performs only integer arithmetic. The type integer consists of the whole number values ranging from –2,147,483,648 to 2,147,483,647. In DECTPU, an integer constant is a sequence of decimal digits; no commas or decimal points are allowed.

The following example assigns a value of the integer data type to the variable x:

x := 12345;

3–4 DEC Text Processing Utility Data Types

DECTPU also supports binary, octal, and hexadecimal integers. Binary integers are preceded by %b or %B, octal by %o or %O, and hexadecimal by %x or %X. Thus, all the following statements are acceptable:

x := %B10000; x := %o20; x := %X130; x := 12345;

3.4 Keyword Data Type

Keywords are reserved words in DECTPU that have special meaning to the compiler.

To see a list of all DECTPU keywords, use the SHOW (KEYWORDS) built-in. You use keywords in the following ways:

• As parameters for DECTPU built-in procedures. For example, the ﬁrst parameter of the SET built-in procedure is always a keyword (for instance, PAD, SCROLLING, STATUS_LINE).

• As values returned by DECTPU built-in procedures, such as CURRENT_ DIRECTION, KEY_NAME, LAST_KEY, READ_KEY, and GET_INFO. For example, the call GET_INFO (window, keywords as possible return values:

DEC Text Processing Utility Data Types

3.3 Integer Data Type

"status_video") has the following

BLINK BOLD NONE REVERSE SPECIAL_GRAPHICS UNDERLINE

• As pattern directives. The following keywords fall into this category:

ANCHOR BUFFER_BEGIN BUFFER_END LINE_BEGIN LINE_END PAGE_BREAK REMAIN UNANCHOR

These keywords, which behave like built-in procedures, are described in the DEC Text Processing Utility Reference Manual.

• To specify the DECTPU data types (BUFFER, MARKER, LEARN, and so on).

• To report warning or error status conditions (TPU$_BADMARGINS, TPU$_ CREATEFAIL, TPU$_NOEOBSTR, and so on).

• To pass the names of keys to DECTPU procedures.

DEC Text Processing Utility Data Types 3–5

DEC Text Processing Utility Data Types

3.4 Keyword Data Type

Table 3–1 shows the correspondence between keywords used as DECTPU key names and the keys on the VT400, VT300, VT200, and VT100 series of keyboards. You do not have to deﬁne a key or control sequence just because there is a DECTPU keyword for the key or sequence.

Table 3–1 Keywords Used for Key Names

DECTPU Key Name

PF1 PF1 PF1 PF2 PF2 PF2 PF3 PF3 PF3 PF4 PF4 PF4 KP0, KP1, . . . , KP9 0, 1, . . . , 9 0, 1, . . . , 9 Period . . Comma , , Minus – – Enter Enter Enter Up Up arrow Up arrow Down Down arrow Down arrow Left Left arrow Left arrow Right Right arrow Right arrow E1 Find / E1 E2 Insert Here / E2 E3 Remove / E3 E4 Select / E4 E5 Prev Screen / E5 E6 Next Screen / E6 Help Help / F15 Do Do / F16 F6, F7, . . . , F20 F6, F7, . . . , F20 NULL_KEY Ctrl/space Ctrl/space TAB_KEY Tab Tab RET_KEY Return Return DEL_KEY LF_KEY Ctrl/J Line feed BS_KEY Ctrl/H Backspace Ctrl_A_KEY Ctrl/A Ctrl_B_KEY Ctrl/B Ctrl/B

.. . .. . .. .

VT400, VT300, VT200 Series Key VT100 Key

Delete

Ctrl/A

Ctrl/A means pressing the Ctrl key simultaneously with the A key. A and a produce the same results.

3–6 DEC Text Processing Utility Data Types

(continued on next page)

DEC Text Processing Utility Data Types

3.4 Keyword Data Type

Table 3–1 (Cont.) Keywords Used for Key Names

DECTPU Key Name

Ctrl_Z_KEY Ctrl/Z Ctrl/Z

The OpenVMS terminal driver handles the following keys as special cases. Compaq recommends that you avoid deﬁning the following control characters and function key:

• Ctrl/C

• Ctrl/O

• Ctrl/Q

• Ctrl/S

• Ctrl/T

• Ctrl/X

• Ctrl/Y

•F6

VT400, VT300, VT200 Series Key VT100 Key

3.5 Learn Data Type

A learn sequence is a collection of DECTPU keystrokes for use later. The LEARN_BEGIN built-in procedure starts collecting keystrokes; the LEARN_END built-in procedure stops the collection of keystrokes and returns a value of the learn data type as a result. The following example assigns a learn data type to the variable x:

LEARN_BEGIN (EXACT);

. . .

x := LEARN_END;

All keystrokes that you enter between the LEARN_BEGIN and LEARN_END built-in procedures are stored in the variable x. The EXACT keyword speciﬁes that, when the learn sequence is replayed, the input (if any) for the built-in procedures READ_CHAR, READ_KEY, and READ_LINE (if used in the learn sequence) will be the same as the input entered when the learn sequence was created. If you specify NO_EXACT, a replay of a learn sequence containing keys that invoke the built-in procedures READ_LINE, READ_KEY, or READ_CHAR looks for new input.

For more information on replaying a learn sequence, see LEARN_BEGIN and LEARN_END in the DEC Text Processing Utility Reference Manual.

You can use the LEARN_ABORT built-in procedure to interrupt the execution of a learn sequence. For information on using LEARN_ABORT, see LEARN_ABORT in the DEC Text Processing Utility Reference Manual.

DEC Text Processing Utility Data Types 3–7

DEC Text Processing Utility Data Types

3.5 Learn Data Type

To enable your user-written DECTPU procedures to work successfully with learn sequences, you must observe the following coding rules when you write procedures that you or someone else can bind to a key:

• The procedure should return true or false, as needed, to indicate whether execution of the procedure completed successfully.

• The procedure should invoke the LEARN_ABORT built-in in case of error.

These practices help prevent a learn sequence from ﬁnishing if the learn sequence calls the user-written procedure and the procedure is not executed successfully.

A procedure that does not explicitly return a value returns 0 by default, thus aborting a learn sequence.

Learn sequences do not include mouse input or characters inserted in a widget.

Note

If, while recording a learn sequence, a margin action routine is executed (such as EVE’s word wrap), the routine may not be executed during the replay of the sequence.

3.6 Marker Data Type

A marker is a reference point in a buffer. You can think of a marker as a ‘‘place holder.’’ To create a marker, use the MARK built-in procedure.

The following example assigns a value of the marker data type to the variable x:

x := MARK (NONE);

After this statement is executed, the variable x contains the character position where the editing point was located when the statement was executed. The editing point is the point in a buffer at which most editing operations are carried out.

You can cause a marker to be displayed with varying video attributes (BLINK, BOLD, REVERSE, UNDERLINE). The NONE keyword in the preceding example speciﬁes that the marker does not have any video attributes.

When you use the MARK built-in, DECTPU puts the marker on the buffer’s editing point. The editing point is not necessarily the same as the window’s cursor position.

A marker can be either free or bound. Free markers are useful for establishing place marks in locations that do not contain characters, such as locations before the beginning of a line, after the end of a line, in the white space created by a tab, or below the end of a buffer. By placing a free marker in such a location, you make it possible to establish the editing point at that location without inserting padding space characters that could complicate later operations such as FILL.

3–8 DEC Text Processing Utility Data Types

DEC Text Processing Utility Data Types

3.6 Marker Data Type

A marker is bound if there is a character in the position marked by the editing point at the time you create the marker. A bound marker is tied to the character on which it is created. If you move the character to which a marker is bound, the marker moves with the character. If you delete the character to which a marker is bound, DECTPU binds the marker to the nearest character or to the end of the line if that is closer than any character.

To force the creation of a bound marker, use the MARK built-in with any of its parameters except FREE_CURSOR. This operation creates a bound marker even if the editing point is beyond the end of a line, before the beginning of a line, in the middle of a tab, or beyond the end of a buffer. To create a bound marker in a location where there is no character, DECTPU ﬁlls the space between the marker and the nearest character with padding space characters.

A marker is usually free if all of the following conditions are true:

• You used MARK (FREE_CURSOR) to create the marker.

• There was no character in the position marked by the editing point at the time you created the marker.

• Nothing has happened to cause the marker to become bound.

The following paragraphs explain each of these conditions in more detail. If you use the MARK (FREE_CURSOR) built-in procedure and there is a

character in the position marked by the editing point, the marker is bound even though you specify otherwise. Once a marker becomes bound, it remains bound throughout its existence. To determine whether a marker is bound, use the following GET_INFO call:

GET_INFO (marker_variable, "bound");

DECTPU keeps track of the location of a free marker by measuring the distance between the marker and the character nearest to the marker. If you move the character from which DECTPU measures distance to a free marker, the marker moves too. DECTPU preserves a uniform distance between the character and the marker. If you collapse white space that contains one or more free markers (for example, if you delete a tab or use the APPEND_LINE built-in procedure), DECTPU preserves the markers and binds them to the nearest character.

If you use the POSITION built-in procedure to establish the editing point at a free marker, the marker remains free and the editing point is also said to be free; that is, the editing point is not bound to a character. Some operations cause DECTPU to ﬁll the space between a free marker and the nearest character with padding space characters, thereby converting the free marker to a bound marker. For example, if you type text into the buffer when the editing point is detached, DECTPU inserts padding space characters between the nearest character and the editing point. Using any of the following built-in procedures when the editing point is detached also causes DECTPU to perform padding:

• APPEND_LINE

• COPY_TEXT

• CURRENT_CHARACTER

• CURRENT_LINE

• CURRENT_OFFSET

• ERASE_CHARACTER

DEC Text Processing Utility Data Types 3–9

DEC Text Processing Utility Data Types

3.6 Marker Data Type

• ERASE_LINE

• MOVE_HORIZONTAL

• MOVE_TEXT

• MOVE_VERTICAL

• SELECT

• SELECT_RANGE

• SPLIT_LINE Example 3–1 shows how to suppress padding while using these built-ins. The

example assumes that the editing point is free. The code in this example assigns the string representation of the current line to the variable bat without adding padding blanks to the buffer.

Example 3–1 Suppressing the Addition of Padding Blanks

x := MARK (FREE_CURSOR); ! Places a marker at the

POSITION (SEARCH_QUIETLY ("",FORWARD)); ! Moves the active editing

bat := CURRENT_LINE; ! Assigns the string

POSITION (x); ! Returns the active editing

To remove a marker, use the DELETE built-in procedure with the marker as a parameter. For example, the following statement deletes the marker mark1:

DELETE (mark1);

You can also set all variables referring to the marker to refer to something else, for example, tpu$k_unspeciﬁed or 0. The following statement sets the variable mark1 to 0:

mark1 := 0;

If mark1 were the only variable referring to a marker, that marker would be deleted upon execution of the previous statement.

The marker data type is returned by the MARK, SELECT, BEGINNING_OF, END_OF, and GET_INFO built-in procedures.

! detached editing point

! point to the nearest ! text character

! representation of the ! current line to bat without ! adding padding blanks

! point to the free marker

3.7 Pattern Data Type

A pattern is a structure that DECTPU uses when it searches for text in a buffer. You can think of a pattern as a template that DECTPU compares to the searched text, looking for a match between the pattern and the searched text. You can use a variable whose data type is the pattern data type when you specify the ﬁrst parameter to the SEARCH and SEARCH_QUIETLY built-in procedures.

3–10 DEC Text Processing Utility Data Types

DEC Text Processing Utility Data Types

3.7 Pattern Data Type

To create a pattern, use DECTPU pattern operators (+, &, |, @) to connect any of the following:

• String constants

• String variables

• Pattern variables

• Calls to pattern built-in procedures

• The following keywords:

ANCHOR BUFFER_BEGIN BUFFER_END LINE_BEGIN LINE_END PAGE_BREAK REMAIN UNANCHOR

• Parentheses (to enclose expressions)

Patterns can be simple or complex. A simple pattern can be composed of sets of strings connected by one of the pattern operators. The following example indicates that pat1 matches either the string

pat1 := "abc" | "def";

If you connect two strings with the + operator, the result is a string rather than a pattern. For example, the following statement gives pat1 the string data type:

pat1 := "abc" + "def";

The SEARCH and SEARCH_QUIETLY built-in procedures accept such a string as a parameter.

A more complex pattern uses pattern built-in procedures and existing patterns to form a new pattern. The following example indicates that pat2 matches the string "abc" followed by the longest string that contains any characters from the string "12345":

pat2 := "abc" + SPAN ("12345");

Pat2 matches the string "abc123" in the text string "xyzabc123def". Following are additional examples of statements that create complex patterns:

pat1 := any( "abc" ); pat2 := line_begin + remain; pat3 := "abc" | "xes"; pat4 := pat1 + "12"; pat5 := "xes" @ var1; pat6 := "abc" & "123";

"abc" or the string "def":

You can assign a pattern to a variable and then use the variable as a parameter for the SEARCH or SEARCH_QUIETLY built-in procedure. SEARCH or SEARCH_QUIETLY looks for the character sequences speciﬁed by the pattern that you use as a parameter. If SEARCH or SEARCH_QUIETLY ﬁnds a match

DEC Text Processing Utility Data Types 3–11

DEC Text Processing Utility Data Types

3.7 Pattern Data Type

for the pattern, the built-in returns a range that contains the text that matches the pattern. You can assign the range to a variable.

The following example uses strings and pattern operators to create a pattern that is stored in the variable my_pat. The variable is then used with the SEARCH or SEARCH_QUIETLY built-in procedure in a forward direction. If SEARCH or SEARCH_QUIETLY ﬁnds a match for my_pat, the range of matching text is stored in the variable match_range. The POSITION built-in procedure causes the editing point to move to the beginning of match_range.

my_pat := ("abc" | "def") + "::"; match_range := SEARCH (my_pat, FORWARD); POSITION (match_range);

3.7.1 Using Pattern Built-In Procedures and Keywords

The following built-in procedures return values of the pattern data type:

• ANY

• ARB

• MATCH

• NOTANY

• SCAN

• SCANL

•SPAN

• SPANL See the DEC Text Processing Utility Reference Manual for a complete description

of these pattern built-in procedures.

3.7.2 Using Keywords to Build Patterns

You can use the following keywords as the ﬁrst argument to the SEARCH or SEARCH_QUIETLY built-in procedures. You can also use them to form patterns in expressions that use the pattern operators. See the DEC Text Processing Utility Reference Manual for a complete description of these keywords.

• ANCHOR

• BUFFER_BEGIN

• BUFFER_END

• LINE_BEGIN

• LINE_END

• PAGE_BREAK

• REMAIN

• UNANCHOR

3–12 DEC Text Processing Utility Data Types

3.7.3 Using Pattern Operators

The following are the DECTPU pattern operators:

• Concatenation operator (+)

• Link operator (&)

• Alternation operator(|)

• Partial pattern assignment operator (@)

The pattern operators are equal in DECTPU’s precedence of operators. For more information on the precedence of DECTPU operators, see Chapter 4. Pattern operators associate from left to right. Thus, the following two DECTPU statements are identical:

pat1 := a + b & c | d @ e; pat1 := (((a + b) & c) | d) @ e;

In addition to the pattern operators, you can use two relational operators, equal (=) and not equal (<>), to compare patterns.

The following sections discuss the pattern operators.

3.7.3.1 + (Pattern Concatenation Operator)

The concatenation operator ( + ) tells SEARCH or SEARCH_QUIETLY that text matching the right pattern element must immediately follow the text matching the left pattern element in order for the complete pattern to match. In other words, the concatenation operator speciﬁes a search in which the right pattern element is anchored to the left. For example, the following pattern matches only if there is a line in the searched text that ends with the string abc.

DEC Text Processing Utility Data Types

3.7 Pattern Data Type

pat1 := "abc" + line_end;

If SEARCH or SEARCH_QUIETLY ﬁnds such a line, the built-in returns a range that contains the text abc and the end of the line.

Compaq recommends that you use the concatenation operator rather than the link operator unless you speciﬁcally require the link operator.

3.7.3.2 & (Pattern Linking Operator)

The link operator (&) is similar to the concatenation operator (+). Unlike the concatenation operator, the link operator does not necessarily cause an anchored search. If you deﬁne a pattern by specifying any pattern element, an ampersand (&), and a pattern or keyword variable, a search for each subpattern is not an anchored search.

If you link elements other than pattern variables, the search is an anchored search unless you specify otherwise. Strings, constants, and the results of built-in procedures are not pattern variables.

For example, suppose you deﬁned two subpattern variables as follows:

p1 := "a" & ANY("012345678"); p2 := "c" & ARB (1);

You then deﬁne the following pattern variable:

pat_var := p1 & p2

DEC Text Processing Utility Data Types 3–13

DEC Text Processing Utility Data Types

3.7 Pattern Data Type

Given this sequence of deﬁnitions, a search for pat_var succeeds if DECTPU encounters the following string:

a5xcd

Because two pattern variables are linked, DECTPU searches ﬁrst for the text that matches p1, then unanchors the search, and then searches for the text that matches p2.

To specify an anchored search when the right-hand subpattern is a pattern or keyword variable, use a plus sign (+). You must use a plus sign (+) to anchor the search if the right-hand subpattern is a keyword variable. If the right-hand subpattern is a pattern variable, you can use the ANCHOR keyword as the ﬁrst element of that subpattern to anchor the right-hand subpattern.

For example, suppose you deﬁned the following patterns:

p1 := LINE_BEGIN + "a"; p2 := "b" + LINE_END;

You anchor the search for p2 by using (+) as follows:

pat_var := p1 + p2;

If you use an ampersand (&), you unanchor the search for p2. You can also anchor the search for p2 by deﬁning p2 as follows:

p2 := ANCHOR + "b" + LINE_END;

3.7.3.3 | (Pattern Alternation Operator)

The alternation operator ( | ) tells SEARCH or SEARCH_QUIETLY to match a sequence of characters if those characters match either of the pattern elements separated by the alternation operator. The following pattern matches either the string abc or the string xes:

pat1 := "abc" | "xes";

If the text being searched contains text that matches both alternatives, SEARCH or SEARCH_QUIETLY matches the earliest occurring match. If two matches start at the same character, SEARCH or SEARCH_QUIETLY matches the left element. For example, suppose you had the search text abcd and the following pattern deﬁnitions:

pat1 := "abc" | "bcd"; pat2 := "bcd" | "abc"; pat3 := "bc" | "bcd"; pat4 := "bcd" | "bc";

Given these deﬁnitions and search text, a search for the patterns pat1 and pat2 would return a range that contains the text abc. A search for the pattern pat3 would return a range that contains the text bc. Finally, a search for the pattern pat4 would return a range that contains the text bcd.

3.7.3.4 @ (Partial Pattern Assignment Operator)

The partial pattern assignment operator (@) tells SEARCH or SEARCH_ QUIETLY to create a range that contains the text matching the pattern element to the left of the partial pattern assignment operator. When the search is completed, the variable to the right of the partial pattern assignment operator references the created range. If SEARCH or SEARCH_QUIETLY is given the search text abcdefg and the following pattern, it returns a range that contains the text abcdefg:

3–14 DEC Text Processing Utility Data Types

DEC Text Processing Utility Data Types

3.7 Pattern Data Type

pat1 := "abc" + (arb(2) @ var1) + remain;

SEARCH or SEARCH_QUIETLY also assigns to var1 a range that contains the text de.

If you assign to a variable a partial pattern that matches a position, rather than a character, the partial pattern variable is a range that contains the character or line-end at the point in the ﬁle where the partial pattern was matched. For example, in any of the following patterns that contain partial pattern assignments, the variable partial_pattern_variable contains the character or line-end at the point in the ﬁle where the partial pattern was matched:

"" @ partial_pattern_variable

•

• ANCHOR @ partial_pattern_variable

• UNANCHOR @ partial_pattern_variable

• LINE_BEGIN @ partial_pattern_variable

• BUFFER_BEGIN @ partial_pattern_variable

If you use one of the preceding patterns when the cursor is free (that is, in an area that does not contain text, such as the area after the end of a line), the variable partial_pattern_variable contains the line-end or character nearest to the cursor.

SEARCH or SEARCH_QUIETLY does partial pattern assignment only if the complete pattern matches. If the complete pattern matches, it makes assignments only to those variables paired with pattern elements that are used in the complete match. If a partial pattern assignment variable appears more than once in a pattern in places where it is legal for a partial pattern assignment to occur, the last occurrence in the pattern determines what range SEARCH assigns to the variable. For example, with the search text abcdefg and the following pattern, SEARCH or SEARCH_QUIETLY returns a range that contains the text abcde and assigns a range that contains the text d to the variable var1:

pat1 := "a" + ("b" @ var1) + "c" + ("d" @ var1)

3.7.3.5 Relational Operators

You can use the two relational operators, equal (=) and not equal (<>), to compare patterns. Two patterns are equal if they are the same pattern, as pat1 and pat2 are in the following example:

pat1 := notany("abc", 2) + span("123"); pat2 := pat1;

Two patterns are also equal if they have the same internal representation. Patterns have the same internal representation only if they are built in exactly the same way. The order of the characters in the arguments to ANY, NOTANY, SCAN, SCANL, SPAN, and SPANL does not matter when you are comparing patterns returned by any of these built-ins. Other than this, almost any difference in the building of two patterns makes those patterns unequal. For example, suppose you deﬁned the variable this_pat as follows:

+ ("e" | ("x" @ var1));

this_pat := ANY ("abc");

DEC Text Processing Utility Data Types 3–15

DEC Text Processing Utility Data Types

3.7 Pattern Data Type

Given this deﬁnition, the following patterns match the same text but are not equal:

pat1 := LINE_BEGIN + ANY ("abc"); pat2 := LINE_BEGIN + this_pat;

3.7.4 Compiling and Executing Patterns

When you execute a DECTPU statement that contains a pattern expression, DECTPU builds an internal representation of the pattern. DECTPU uses the current contents of any buffers or ranges used as arguments to pattern built-ins in the pattern expression to build the internal representation. Later changes to those buffers and ranges do not affect the internal representation for the pattern. DECTPU also uses the current values of any variables used in the pattern expression. Later changes to these variables do not affect the internal representation of the pattern. For example, suppose you wrote the following code fragment:

p1 := "abc"; p2 := "123"; pat := p1 & p2; p1 := "xyz"; SEARCH (pat, FORWARD);

Given this code fragment, the search matches the string "abc123" because the variable pat is evaluated as it is built from p1 and p2 during the assignment statement.

3.7.5 Searching for a Pattern

The SEARCH and SEARCH_QUIETLY built-ins use the following algorithm to ﬁnd a match for a pattern:

1. Put the internal marker that marks the search position at the starting position for the search. The starting position is determined as follows:

• If you do not specify where to search, search the current buffer, starting

at the editing point.

• If you specify a buffer or range where the search is to take place, start at

the beginning or end of the buffer or range, depending on the direction of the search.

2. Check whether the pattern matches text, starting at the current search position and extending toward the end of the searched buffer or range. If a range is being searched, the matched text cannot extend beyond the end of that range. If the pattern matches, return a range that contains the matching text and stop searching.

3. If the previous step fails, move the search position one character forward or backward, depending upon the direction of the search. If this is impossible because the search position is at the end or beginning of the searched buffer or range, stop searching. If this step succeeds, repeat the previous step.

This algorithm changes if you specify a reverse search for a pattern starting with SCAN, SPAN, SCANL, or SPANL. For more information, see the descriptions of these built-in procedures in the DEC Text Processing Utility Reference Manual.

3–16 DEC Text Processing Utility Data Types

Note

3.7.6 Anchoring a Pattern

Anchoring a pattern forces SEARCH or SEARCH_QUIETLY to match the anchored part of the pattern to text starting at the current search position. If the anchored part of a pattern fails to match that text, SEARCH or SEARCH_ QUIETLY stops searching.

Usually, all pattern elements other than the ﬁrst pattern element of a pattern are anchored. This means that a pattern can match text starting at any point in the searched text but that once it starts matching, each pattern element must match the text immediately following the text that matched the previous pattern element.

To direct DECTPU to stop searching if the characters starting at the editing point do not match the pattern, use the ANCHOR keyword as the ﬁrst pattern element. For example, the following pattern matches only if the string abc occurs at the editing point:

pat1 := ANCHOR + "abc";

There are two ways to unanchor pattern elements in the midst of a pattern. The easiest is to concatenate or link the UNANCHOR keyword before the pattern element you want to unanchor. The following pattern unanchors the pattern element xyz:

DEC Text Processing Utility Data Types

3.7 Pattern Data Type

pat1 := "abc" + UNANCHOR + "xyz";

This means that the pattern pat1 matches any text beginning with the characters abc and ending with the characters xyz. It does not matter what or how many

characters or line breaks appear between the two sets of characters. Since SEARCH or SEARCH_QUIETLY matches the ﬁrst xyz it ﬁnds, the text between the two sets of characters by deﬁnition does not contain the string xyz.

The second way to unanchor a pattern element is to use the special properties of the link operator (&). While the concatenation operator always anchors the right pattern element to the left, the link operator does so only if the right pattern element is not a pattern variable. If the link operator’s right pattern element is a pattern variable, the link operator unanchors that pattern element. The pattern pat2 deﬁned by the following assignments matches any sequence of text that begins with the letter a and ends with a digit.

pat1 := ANY ("0123456789"); pat2 := "a" & pat1;

Any amount of text can occur between the a and the digit. Pat2 matches the same text as the following pattern:

pat3 := "a" + UNANCHOR + ANY( "0123456789" );

The link operator unanchors a pattern variable regardless of what the left pattern element is. In particular, the following two patterns match the same text:

pat2 := "a" & pat1; pat3 := "a" & ANCHOR & pat1;

If you are using pattern variables to form patterns and you wish those variables to be anchored, you have two choices: you can use the concatenation operator, or you can use the ANCHOR keyword as the ﬁrst element of any pattern the pattern variables reference.

DEC Text Processing Utility Data Types 3–17

DEC Text Processing Utility Data Types

3.8 Process Data Type

The CREATE_PROCESS built-in procedure returns a value of the process data type.

A DECTPU process runs as a subprocess. DECTPU processes have the same restrictions that OpenVMS subprocesses have.

Following are some of the restrictions:

• You cannot create more DECTPU processes than your account subprocess quota allows.

• You cannot spawn a subprocess in an account that has the CAPTIVE ﬂag set.

• Only OpenVMS utilities that can perform I/O to a mailbox and that do simple reads and writes (for example, MAIL) can run in a DECTPU process. Programs like FMS, PHONE, or any other program that takes full control of the screen, do not work properly in a DECTPU process. See the built-in procedure SPAWN for information on running these types of programs from DECTPU.

• You do not see any prompts from the utility you are using. For example, in MAIL, you have to be aware of the sequence of prompts for sending a mail message because you do not see the prompts.

The following example assigns a value of the process data type to the variable x:

x := CREATE_PROCESS (main_buffer, "MAIL");

The ﬁrst parameter speciﬁes that the output from the process is to be stored in MAIN_BUFFER. The string "MAIL" is the ﬁrst command sent to the subprocess.

To pass commands to a subprocess, use the SEND built-in procedure, as follows:

SEND ("MAIL", x);

To pass the READ command to the Mail utility, enter the following DECTPU statement:

SEND ("READ", x);

The output from the READ command is stored in the buffer associated with the process x. If the buffer associated with a process is deleted, the process is deleted as well.

3.9 Program Data Type

A program is the compiled form of a sequence of DECTPU procedures and executable statements. The COMPILE and LOOKUP_KEY built-in procedures can optionally return a value of the program data type as a result. The following example assigns a value of the program data type to the variable x:

x := COMPILE (main_buffer);

MAIN_BUFFER must contain only DECTPU declarations, executable statements, and comments. All declarations must come before any executable statements that are not included in the declarations. The declarations and statements are compiled and the resulting program is stored in the variable x.

3–18 DEC Text Processing Utility Data Types

3.10 Range Data Type

A range contains all the text between (and including) two markers. You can form a range with the CREATE_RANGE built-in procedure. A range is associated with characters within a buffer. If the characters within a range move, the range moves with them. If characters are added or deleted between two markers that delimit a range, the size of the range changes. If all the characters in a range are deleted, the range moves to the nearest character.

DECTPU does not support ranges of zero length unless the range begins and ends at the end of a buffer. All other ranges contain at least one character (which could be a space character) or a line-end (if the range is created at the end of a line).

If you create a range by specifying a free marker as a parameter to the CREATE_ RANGE built-in, DECTPU creates a new marker and binds the marker to the text nearest to the free marker position. DECTPU uses the new bound marker as the range delimiter. This operation does not cause insertion of padding spaces.

Deleting the markers used to create a range does not affect the range. To convert the contents of a range to a string, use either the STR or the SUBSTR

built-in procedure.

DEC Text Processing Utility Data Types

3.10 Range Data Type

To remove a range, use the DELETE built-in procedure with the range as a parameter. For example, the following statement deletes the range range1:

DELETE (range1);

You can also delete a range by removing all variable references to the range. To do this, set all variables referring to the range to some other value, such as 0. For example, the following statement sets the variable range1 to 0:

range1 := 0;

Deleting a range does not remove the characters of the range from the buffer; it merely removes the range data structure. To remove the characters of a range, use the ERASE built-in procedure with the range as a parameter. For example, ERASE (my_range) removes all the characters in my_range, but it does not remove the range structure. Using the statement DELETE (range_variable) removes the range data structure, but does not affect the characters in the range.

The following built-in procedures, as well as the partial pattern assignment operator, all return values of the range data type:

• CHANGE_CASE

• CREATE_RANGE

• EDIT

• GET_INFO

• READ_CLIPBOARD

• READ_GLOBAL_SELECT

• SEARCH

• SEARCH_QUIETLY

• SELECT_RANGE

• TRANSLATE

DEC Text Processing Utility Data Types 3–19

DEC Text Processing Utility Data Types

3.10 Range Data Type

The following example assigns a value of the range data type to the variable x:

x := CREATE_RANGE (mark1, mark2, UNDERLINE);

You can specify the video attribute with which DECTPU should display a range. The possible attributes are BLINK, BOLD, REVERSE, and UNDERLINE. The UNDERLINE keyword in the preceding example speciﬁes that the characters in the range will be underlined when they appear on the screen. You cannot give more than one video attribute to a range. However, to apply multiple video attributes to a given set of characters, you can deﬁne more than one range that contains those characters and give one video attribute to each range.

3.11 String Data Type

DECTPU uses the string data type to represent character data. A value of the string data type can contain any of the elements of a character set. You can select one of the following character sets to use with your string data:

• DEC_MCS—DEC Multinational Character Set

• ISO_LATIN1—ISO Latin1 Character Set

• GENERAL—Other general character sets

DECTPU uses the string data type to represent character data. A value of the string data type can contain any of the elements of the character sets mentioned previously. To specify a string constant, enclose the value in quotation marks. In DECTPU, you can use either the quotation mark ( delimiter for a string. The following statements assign a value of the string data type to the variable x:

x := ’abcd’; x := "abcd";

To specify the quote character itself within a string, type the character twice if you are using the same quote character as the delimiter for the string. The following statements show how to quote an apostrophe and a quotation mark, respectively:

x := ’’’’; ! The value assigned to x is ’. x := """"; ! The value assigned to x is ".

If you use the alternate quote character as the delimiter for the string within which you want to specify a quote character, you do not have to type the character twice. The following statements show how to quote an apostrophe and a quotation mark, respectively, when you use the alternate quote character to delimit the string:

x := "’"; ! The value assigned to x is ’. x := ’"’; ! The value assigned to x is ".

A null string is a string of length zero. You can assign a null string to the variable x in the following way:

" ) or the apostrophe ( ’ ) as the

x:=’’;

To create a string from the contents of a range, use the STR or the SUBSTR built-in procedure. To create a string from the contents of a buffer, use the STR built-in.

3–20 DEC Text Processing Utility Data Types

DEC Text Processing Utility Data Types

3.11 String Data Type

The maximum length for a string is 65,535 characters. A restriction of the DECTPU compiler is that a string constant (an open quotation mark, some characters, and a close quotation mark) must have both its opening and closing quotation marks on the same line. While a string can be up to 65,535 characters long, a line in a DECTPU buffer can only be 32767 characters long. If you try to create a line that is longer than 32767 characters, DECTPU truncates the inserted text to the amount that ﬁlls the line to 32767 characters.

Many DECTPU built-in procedures return a value of the string data type. The ASCII built-in procedure, for example, returns a string for the ordinal value that you use as a parameter. The following statement returns the string variable my_char:

my_char := ASCII (75);

To replicate a string, specify the string to be reproduced, then the multiplication operator (*), and then the number of times you want the string to be replicated. For example, the following DECTPU statement inserts 10 underscores into the current buffer at the editing point:

COPY_TEXT ("_" * 10)

The string to be replicated must be on the left-hand side of the operator. For example, the following DECTPU statement produces an error:

"K" in the

COPY_TEXT (10 * "_")

To reduce a string, specify the string to be modiﬁed, then the subtraction operator (–), and then the substring to be removed. Table 3–2 shows the effects of two string-reduction operations.

Table 3–2 Effects of Two String-Reduction Operations

DECTPU Statement Result

COPY_TEXT ("FILENAME.MEM"–"FILE") Inserts the string "NAME.MEM" into

COPY_TEXT ("woolly"–"wool") Inserts the string "ly" into the current

3.12 Unspeciﬁed Data Type

An unspeciﬁed value is the initial value of a variable after it has been compiled (added to the DECTPU symbol table). In the following example, the COMPILE built-in procedure creates the variable x and initially gives it the data type unspeciﬁed unless x has previously been declared as a global variable:

COMPILE ("x := 1");

An assignment statement that creates a variable must be executed before a data type is assigned to the variable. In the following example, when you use the EXECUTE built-in procedure to run the program that is stored in the variable prog, the variable x is assigned an integer value:

the current buffer at the editing point.

buffer at the editing point.

prog := COMPILE ("x := 1"); EXECUTE (prog);

DEC Text Processing Utility Data Types 3–21

DEC Text Processing Utility Data Types

3.12 Unspeciﬁed Data Type

To give a variable the data type unspeciﬁed, assign the predeﬁned constant TPU$K_UNSPECIFIED to the variable:

prog := TPU$K_UNSPECIFIED;

3.13 Widget Data Type

The DECwindows version of DECTPU provides the widget data type to support DECwindows widgets. The non-DECwindows version of DECTPU does not support this data type.

A widget is an interaction mechanism by which users give input to an application or receive messages from an application.

You can use the equal operator (=) or the not-equal operator (<>) on widgets to determine whether they are equal (that is, whether they are the same widget instance), but you cannot use any other relational or arithmetic operators on them.

Once you have created a widget instance, DECTPU does not delete the widget instance, even if there are no variables referencing it. To delete a widget, use the DELETE built-in procedure.

DECwindows DECTPU provides the same support for DECwindows gadgets that it provides for widgets. A gadget is a structure similar to a widget, but it is not associated with its own unique DECwindows window. Gadgets do not require as much memory to implement as widgets do. In most cases, you can use the same DECwindows DECTPU built-ins on gadgets that you use on widgets.

For more information on widgets or gadgets, see the OpenVMS overview documentation.

3.14 Window Data Type

A window is a portion of the screen that displays as much of the text in a buffer as will ﬁt in the screen area. In EVE, the screen contains three windows by default: a large window for viewing the text in your editing buffer and two one-line windows for displaying commands and messages. In EVE or in a user-written interface, you can subdivide the screen to create more windows.

A variable of the window data type ‘‘contains’’ a window. The CREATE_WINDOW, CURRENT_WINDOW, and GET_INFO built-in procedures return a value of the window data type. CREATE_WINDOW is the only built-in procedure that creates a new window. The following example assigns a value of the window data type to the variable x:

x := CREATE_WINDOW (1, 12, OFF);

The ﬁrst parameter speciﬁes that the window starts at screen line number 1. The second parameter speciﬁes that the window is 12 lines in length. The OFF keyword speciﬁes that a status line is not to be displayed when the window is mapped to the screen.

3–22 DEC Text Processing Utility Data Types

3.14.1 Deﬁning Window Dimensions

Windows are deﬁned in lines and columns. In EVE, all windows extend the full width of the screen or terminal emulator. In DECTPU, you can set the window width to be narrower than the width of the screen or terminal emulator.

The allowable dimensions of a window often depend on whether the window has a status line, a horizontal scroll bar, or both. A status line occupies the last line of a window. By default, a status line contains information about the buffer and the ﬁle associated with the window. You can turn a status line on or off with the SET (STATUS_LINE) built-in procedure.

A horizontal scroll bar is a one-line widget at the bottom of a window that you can use to shift the window to the right or left, controlling what text in the buffer can be seen through the window. You can turn a horizontal scroll bar on or off with the SET (SCROLL_BAR) built-in procedure.

Lines on the screen are counted from 1 to the number of lines on the screen; lines in a window are counted from 1 to the number of lines in the window. Columns on the screen are counted from 1 to the physical width of the screen; columns in a window are counted from 1 to the number of columns in the window.

The minimum length for a window is one line if you do not include a status line or horizontal scroll bar, two lines if you include either a status line or a horizontal scroll bar, and three lines if you include both a status line and scroll bar.

DEC Text Processing Utility Data Types

3.14 Window Data Type

The maximum length of a window is the number of lines on your screen. For example, if your screen is 24 lines long, the maximum size for a single window is 24 lines. On the same size screen, you can have a maximum of 24 visible windows if you do not use status lines or horizontal scroll bars. If you use a status line and a horizontal scroll bar for each window, the maximum number of visible windows is 8.

3.14.2 Creating Windows

When you use a device that supports windows (see Appendix B for information on terminals that DECTPU supports), you or the section ﬁle that initializes your application must create and map windows. In most instances, it is also advisable to map a buffer to the window. To map a buffer to a window, use the MAP built-in procedure. If you do not associate a buffer with a window and map the window to the screen, the only items displayed on the screen are messages that are written to the screen at the cursor position.

The CREATE_WINDOW built-in procedure deﬁnes the size and location of a window and speciﬁes whether a status line is to be displayed. CREATE_ WINDOW also adds the window to DECTPU’s internal list of windows available for mapping. At creation, a window is marked as being not visible and not mapped and the following values for the window are calculated and stored:

• Original_top—Screen line number of the top of the window when it was created.

• Original_bottom—Screen line number of the bottom of the window when it was created (not including the status line).

• Original_length—Number of lines in the window (including the status line).

Later calls to ADJUST_WINDOW may change these values.

DEC Text Processing Utility Data Types 3–23

DEC Text Processing Utility Data Types

3.14 Window Data Type

3.14.3 Displaying Window Values

When you use the CREATE_WINDOW built-in procedure to create a window, DECTPU saves the numbers of the screen lines that delimit the window in original_top and original_bottom. When you map a window to the screen with the MAP built-in procedure, the window becomes visible on the screen. If it is the only window on the screen, its visible_top and visible_bottom values are the same as its original_top and original_bottom values. You can use SHOW (WINDOWS) to display the original and the visible values or the GET_INFO built-in procedure to retrieve them.

However, if there is already a window on the screen and you map another window over part of it, the values for the previous window’s visible_top, visible_bottom, and visible_length are modiﬁed. The value for visible_length of the previous window is different from its original_length until the new window is removed from the screen. As long as the new window is on the screen and does not have another window mapped over it, its original top and bottom are the same as its visible top and bottom.

3.14.4 Mapping Windows

When you want a window and its associated buffer to be visible on the screen, use the MAP built-in procedure. Mapping a window to the screen has the following effects:

• The mapped window becomes the current window and the cursor is moved to the editing point in the buffer associated with the window.

• The buffer associated with the window becomes the current buffer.

• The window is marked as visible and mapped.

• The visible_top, visible_bottom, and visible_length of the window are calculated and stored. Initially, these values are the same as the original values that were calculated when the window was created. (See the last item in the next list.)

Mapping a window to the screen may have the following side effects:

• The newly mapped window may occlude other windows. This happens when the original_top or original_bottom line of the newly mapped window overlaps the boundaries of existing visible windows. Overlapping can cause some windows to be totally occluded or not visible. Occluded windows are still marked mapped; when the window that is covering them is unmapped, they may reappear on the screen without being explicitly remapped.

• If the newly mapped window divides a window into two parts, only the top part of the segmented window continues to be updated. The lower part of the segmented window is erased at the next window update.

• The visible_top, visible_bottom, and visible_length values of a window that is occluded change from their original values.

When a newly mapped window becomes the current window (the MAP, POSITION, and ADJUST_WINDOW built-in procedures cause this to happen), the cursor is placed in the current window. In addition to the active cursor position in the current window, there is a marker that designates a cursor position in all other windows. The cursor position in a window other than the current window is the last location of the cursor when it was in the window. By maintaining a cursor position in all windows, DECTPU lets you edit in multiple locations of a single buffer if that buffer is associated with more than one window.

3–24 DEC Text Processing Utility Data Types

For more information on the cursor position in a window and the POSITION built-in procedure, see the DEC Text Processing Utility Reference Manual.

3.14.5 Removing Windows

To remove a window from the screen, you can use either the UNMAP built-in procedure or the DELETE built-in procedure. UNMAP removes a window from the screen. However, the window is still in DECTPU’s internal list of windows. It is available to be remapped to the screen without being re-created. DELETE removes a window from the screen and also removes it from DECTPU’s list of windows. It is then no longer available for future mapping to the screen.

Unmapping or deleting a window has the following effects:

• The unmapped window is marked as not visible and not mapped.

• Another window becomes the current window and the cursor is moved to the last cursor position in that window.

• If other windows were occluded by the window you removed from the screen, text from the occluded windows reappears on the screen. The visible_top, visible_bottom, and visible_length values of the previously occluded windows are modiﬁed according to the lines that are returned to them when the occluding window is unmapped. When an occluding window is removed, the window or windows it occluded become visible again.

DEC Text Processing Utility Data Types

3.14 Window Data Type

3.14.6 Using the Screen Manager

The screen manager is the part of DECTPU that controls the display of data on the screen. You can manipulate data without having it appear on a terminal screen (see Chapter 5). However, if you use the DECTPU window capability to make your edits visible, the screen manager controls the screen.

In the main control loop of DECTPU, the screen manager is not called to perform its duties until all commands bound to the last key pressed have ﬁnished executing and all input in the type-ahead buffer has been processed. Upon completion of all the commands, the screen manager updates every window to reﬂect the current state of the part of the buffer that is visible in the window. If you want to make the screen reﬂect changes to the buffer prior to the end of a procedure, use the UPDATE built-in procedure to force the updating of the window. Using UPDATE is recommended with built-in procedures such as CURRENT_COLUMN that query DECTPU for the current cursor position. To ensure that the cursor position returned is the correct location (up to the point of the most recently issued command), use UPDATE before using CURRENT_ COLUMN or CURRENT_ROW.

3.14.7 Getting Information on Windows

There are two DECTPU built-in procedures that return information about windows: GET_INFO and SHOW (WINDOW).

GET_INFO returns information that you can store in a variable. You can get information about the visible and original values of windows, as well as about other attributes that you have set up for your window environment. See GET_ INFO in the DEC Text Processing Utility Reference Manual.

SHOW (WINDOW) or SHOW (WINDOWS) puts information about windows in the SHOW_BUFFER. If you use an editor that has an INFO_WINDOW, you can display the SHOW_BUFFER information in the INFO_WINDOW.

DEC Text Processing Utility Data Types 3–25

DEC Text Processing Utility Data Types

3.14 Window Data Type

3.14.8 Terminals That Do Not Support Windows

DECTPU supports windows only for ANSI character-cell terminals. Noncharacter-cell terminals do not support windows and are considered ‘‘unsupported devices.’’

If you are using an unsupported device, you must use the /NODISPLAY qualiﬁer when you invoke DECTPU. /NODISPLAY informs DECTPU that you do not expect the device from which you are issuing DECTPU commands to support screen-oriented editing. If one of the previous conditions exists and you do not specify the /NODISPLAY qualiﬁer, DECTPU exits with an error condition.

You are using an unsupported device if logical name SYS$INPUT points to an unsupported device, such as a character-cell terminal.

Appendix B contains more information about DECTPU terminal support. Chapter 2 contains more information on the /NODISPLAY qualiﬁer.

3–26 DEC Text Processing Utility Data Types

Lexical Elements of the DEC Text Processing

Utility Language

4.1 Overview

A DECTPU program is composed of lexical elements. A lexical element may be an individual character, such as an arithmetic operator, or it may be a group of characters, such as an identiﬁer. The basic unit of a lexical element is a character from either the DEC Multinational Character Set or the ISO_LATIN1 Character Set.

This chapter describes the following DECTPU lexical elements:

• Character set

• Identiﬁers

• Variables

• Constants

• Operators

• Expressions

• Reserved words

• Lexical keywords

4.2 Case Sensitivity of Characters

The DECTPU compiler does not distinguish between uppercase and lowercase characters except when they appear as part of a quoted string. For example, the word EDITOR has the same meaning when written in any of the following ways:

EDITOR EDitOR editor

The following, however, are quoted strings, and therefore represent different values:

"XYZ"

xyz"

Lexical Elements of the DEC Text Processing Utility Language 4–1

Lexical Elements of the DEC Text Processing Utility Language

4.3 Character Sets

When you invoke DECTPU, you can use one of the following keywords with the /CHARACTER_SET qualiﬁer to specify the character set that you want DECTPU to use:

• DEC_MCS (for the DEC Multinational Character Set)

• ISO_LATIN1 (for the ISO Latin1 Character Set)

• GENERAL (for other general character sets)

• TPU$CHARACTER_SET (see the DCL help topic for this logical name) Each character set is an 8-bit character set with 256 characters. Each character

in a set is assigned a decimal equivalent number ranging from 0 to 255. Each character set uses an extension of the American Standard Code for Information Interchange (ASCII) character set for the ﬁrst 128 characters. Table 4–1 shows the categories into which you can group the ASCII characters.

Table 4–1 Categories of ASCII Character Set Characters

Category Meaning

0–31 Nonprinting characters such as tab, line feed, carriage return, and bell 32 Space 33–64 Special characters such as the ampersand (&), question mark ( ?), equal

65–122 The uppercase and lowercase letters A through Z and a through z 123–126 Special characters such as the left brace ( {) and the tilde (~) 127 Delete

sign (=), and the numbers 0 through 9

The following sections discuss the types of character sets supported by DECTPU.

4.3.1 DEC Multinational Character Set (DEC_MCS)

The DEC Multinational Character Set characters from 128 to 255 are extended control characters and supplemental multinational characters. Table 4–2 shows the categories into which you can group the characters.

Table 4–2 Categories of DEC Multinational Character Set Characters

Category Meaning

128–159 Extended control characters 160 Reserved 161–191 Supplemental special graphics characters such as the copyright sign ( © )

192–254 The supplemental multinational uppercase and lowercase letters such as the

255 Reserved

and the degree sign (°)

Spanish Ñ and ñ

For a complete list of characters in the DEC Multinational Character Set, see the OpenVMS documentation.

4–2 Lexical Elements of the DEC Text Processing Utility Language

Lexical Elements of the DEC Text Processing Utility Language

4.3.2 ISO Latin1 Character Set (ISO_LATIN1)

The ISO Latin1 Character Set characters from 128 to 255 are extended control characters and Latin1 supplemental multinational characters. Table 4–3 shows the groups into which you can categorize characters.

Table 4–3 Categories for ISO Latin1 Characters

128-159 Extended control characters 160-191 Latin1 supplemental graphics characters such as the nonbreaking space and

the currency sign

192-255 The Latin1 supplemental uppercase and lowercase letters such as the

uppercase and lowercase thorn

For a complete list of the ISO Latin1 Character Set, see the OpenVMS documentation.

4.3.3 General Character Sets

If you specify the GENERAL keyword with the /CHARACTER_SET qualiﬁer or the -C option, DECTPU is unable to set a character set for 8-bit characters. The character set used and how DECTPU displays 8-bit characters are the same as before you started DECTPU. For this reason, the characters from 128 to 255 in the General Character Sets are not speciﬁc to any character set.

4.3 Character Sets

4.3.4 Entering Control Characters

There are two ways to enter control characters in DECTPU:

• Use the ASCII built-in procedure with the decimal value of the control character that you want to enter. The following statement causes the escape character to be entered in the current buffer:

COPY_TEXT (ASCII (27));

• Use the special functions provided by EVE to enter control characters: – EVE provides a QUOTE command that is bound to Ctrl/V to insert control

characters in a buffer. For example, to use the quote command to insert an escape character in a buffer, do the following:

1. Press Ctrl/V.

2. Press the ESCAPE key (on VT100-series terminals) or Ctrl/[. For example:

Ctrl/V ESC

– EVE’s EDT-like keypad setting provides a SPECINS key sequence to

insert control characters in a buffer. Use the SPECINS key to enter a control character as follows:

1. Press the GOLD key.

2. Enter the ASCII value of the special character that you want to insert in the buffer; in this case 27 (the escape character). (Use the keys on the keyboard, not the ones on the keypad.)

3. Press the GOLD key again.

4. Press the SPECINS key on the EDT keypad.

Lexical Elements of the DEC Text Processing Utility Language 4–3

Lexical Elements of the DEC Text Processing Utility Language

4.3 Character Sets

For example:

GOLD 27 GOLD Specins

4.3.5 DECTPU Symbols

Certain symbols have special meanings in DECTPU. You can use them as statement delimiters, operators, or other syntactic elements. Table 4–4 lists the DECTPU symbols and their functions.

Table 4–4 DECTPU Symbols

Name Symbol DECTPU Function

Apostrophe ’ Delimits a string Assignment operator := Assigns a value to a variable At sign @ Partial pattern assignment operator Left brace { Opens an array element index expression Close parenthesis ) Ends parameter list, expression, procedure call,

Comma , Separates parameters Exclamation point ! Begins comment Dollar sign $ Indicates a variable, constant, keyword, or

Right brace } Closes array element index expression Equal sign = Relational operator Greater than sign > Relational operator Greater than or equal to

sign Slash / Integer division operator Asterisk * Integer multiplication operator Left bracket [ Begins case label Less than sign < Relational operator Less than or equal to

sign Minus sign – Subtraction operator Not equal sign <> Relational operator Vertical bar | Pattern alternation operator Open parenthesis ( Begins parameter list, expression, argument list, or

Ampersand & Pattern linkage operator Plus sign + String concatenation operator, pattern

Quotation mark " Delimits string Right bracket ] Ends case label Semicolon ; Separates language statements Underscore _ Separates words in identiﬁers

>= Relational operator

<= Relational operator

argument list, or array element index

procedure name that is reserved to Compaq

array element index

concatenation operator, integer addition operator

4–4 Lexical Elements of the DEC Text Processing Utility Language

4.4 Identiﬁers

In DECTPU, identiﬁers are used to name programs, procedures, keywords, and variables. An identiﬁer is a combination of alphabetic characters, digits, dollar signs, and underscores, and it must conform to the following restrictions:

• An identiﬁer cannot contain any spaces or symbols except the dollar sign and

• Identiﬁers cannot be more than 132 characters long. DECTPU identiﬁers for built-in procedures, constants, keywords, and global

variables are reserved words. You can create your own identiﬁers to name programs, procedures, constants,

and variables. Any symbol that is neither declared nor used as the target of an assignment statement is assumed to be an undeﬁned procedure.

4.5 Variables

Variables are names given to DECTPU storage locations that hold values. A variable name can be any valid DECTPU identiﬁer that is not a DECTPU reserved word or the name of a DECTPU procedure. You assign a value to a variable by using a valid identiﬁer as the left-hand side of an assignment statement. Following is an example of a variable assignment:

Lexical Elements of the DEC Text Processing Utility Language

4.4 Identiﬁers

the underscore.

new_buffer := CREATE_BUFFER ("new_buffer_name");

Compaq suggests that you establish some convention for naming variables so that you can distinguish your variables from the variables in the section ﬁle that you are using.

DECTPU allows two kinds of variables: global and local. Global variables are in effect throughout a DECTPU environment. Local variables are evaluated only within the procedure or unbound code in which they are declared. A variable is implicitly global unless you use the LOCAL declaration. You can also declare global variables with the VARIABLE declaration.

Example 4–1 shows a global variable declaration and a procedure that contains a local variable declaration.

Example 4–1 Global and Local Variable Declarations

VARIABLE user_tab_char; ! Tab key procedure. Always inserts a tab, even if current mode

! is overstrike. PROCEDURE user_tab LOCAL this_mode; ! Local variable for current mode this_mode := GET_INFO (CURRENT_BUFFER, "mode"); ! Save current mode

SET (INSERT, CURRENT_BUFFER); ! Set mode to insert user_tab_char := ASCII (9); ! Define the tab char COPY_TEXT (user_tab_char); ! Insert tab SET (this_mode, CURRENT_BUFFER); ! Reset original mode

ENDPROCEDURE;

Lexical Elements of the DEC Text Processing Utility Language 4–5

Lexical Elements of the DEC Text Processing Utility Language

4.5 Variables

The global variable user_tab_char is assigned a value when the procedure user_tab is executing. Since the variable is a global variable, it could have been

assigned a value outside the procedure user_tab. The local variable this_mode has the value established in the procedure user_tab

only when this procedure is executing. You can have a variable also named this_mode in another procedure. The two variables are not the same and may have different values. You can also have a global variable named this_mode. However, using this_mode as a global variable when you are also using it as a local variable is likely to confuse people who read your code. DECTPU will return an informational message during compilation if a local variable has the same name as a global variable.

4.6 Constants

DECTPU has three types of constants:

• Integers

• Strings

• Keywords Integer constants can be any integer value that is valid in DECTPU. See the DEC

Text Processing Utility Reference Manual for more information on the integer data type.

String constants can be one character or a combination of characters delimited by apostrophes or quotation marks. See the DEC Text Processing Utility Reference Manual for a complete description of how to quote strings in DECTPU.

Keywords are reserved words that have special meaning to the DECTPU compiler. See Chapter 3 for a complete description of keywords.

With the CONSTANT declaration, you can associate a name with a constant expression. User-deﬁned constants can be locally or globally deﬁned.

A local constant is a constant declared within a procedure declaration. The scope of the constant is limited to the procedure in which it is deﬁned.

A global constant is a constant declared outside a procedure. Once a global constant has been deﬁned, it is set for the life of the DECTPU session. You can reassign to a constant the same value it was assigned previously, but you cannot redeﬁne a constant during a DECTPU session.

See Section 4.9.5.3 for a complete description of the CONSTANT declaration. Example 4–2 shows a global constant declaration and a procedure that contains a

local constant declaration.

Example 4–2 Global and Local Constant Declarations

! Define some global constants. CONSTANT

user_bell := BELL, user_hello := "Hello", user_ten := 10;

! Hello world procedure.

4–6 Lexical Elements of the DEC Text Processing Utility Language

(continued on next page)

Example 4–2 (Cont.) Global and Local Constant Declarations

PROCEDURE user_hello_world CONSTANT

world := "world";

MESSAGE (user_hello + " " + world); ! Display "Hello world" ENDPROCEDURE;

4.7 Operators

DECTPU uses symbols and characters as language operators. There are ﬁve types of operators:

• Arithmetic

• String

• Relational

• Pattern

• Logical Table 4–5 lists the symbols and language elements that DECTPU uses as

operators.

Lexical Elements of the DEC Text Processing Utility Language

4.6 Constants

! in message area

Table 4–5 DECTPU Operators

Type Symbol Description

Arithmetic + Addition, unary plus

– Subtraction, unary minus * Multiplication / Division

String + String concatenation

- String reduction * String replication

Relational <> Not equal to

= Equal to < Less than <= Less than or equal to > Greater than >= Greater than or equal to

Pattern | Pattern alternation

@ Partial pattern assignment

(continued on next page)

Lexical Elements of the DEC Text Processing Utility Language 4–7

Lexical Elements of the DEC Text Processing Utility Language

4.7 Operators

Table 4–5 (Cont.) DECTPU Operators

Type Symbol Description

+ Pattern concatenation & Pattern linkage

Logical AND Boolean AND

NOT Boolean NOT OR Boolean OR XOR Boolean exclusive OR

You can use the + operator to concatenate strings. You can also use the relational operators to compare a string with a string, a marker with a marker, or a range with a range.

The precedence of the operators in an expression determines the order in which the operands are evaluated. Table 4–6 lists the order of precedence for DECTPU operators. Operators of equal precedence are listed on the same line.

Table 4–6 Operator Precedence

Operator Precedence

unary +,unary – Highest NOT *, /, AND @, &, +, –, |, OR, XOR =, <>, <, <=, >, >= := Lowest

Expressions enclosed in parentheses are evaluated ﬁrst. You must use parentheses for correct evaluation of an expression that combines relational operators.

You can use parentheses in an expression to force a particular order for combining operands. For example:

Expression Result 8*5/2-4 16

8*5/(2-4) -20

4.8 Expressions

An expression can be a constant, a variable, a procedure, or a combination of these separated by operators. You can use expressions in a DECTPU procedure where an identiﬁer or constant is required. Expressions are frequently used within DECTPU conditional language statements.

The data types of all elements of a DECTPU expression must be the same. The following are exceptions to this rule:

• You can mix keywords, strings, and pattern variables in expressions used to create patterns.

4–8 Lexical Elements of the DEC Text Processing Utility Language

Lexical Elements of the DEC Text Processing Utility Language

4.8 Expressions

• You can mix data types when using the not equal (<>) and equal (=) relational operators.

• You can mix strings and integers when doing string replication.

Except for these cases, DECTPU does not perform implicit type conversions to allow for the mixing of data types within an expression. If you mix data types, DECTPU issues an error message.

In the following example, the elements (J > 4) and (my_string =

") each evaluate to an integer type (odd integers are true; even integers are

string false) so that they can be used following the DECTPU IF statement:

IF (J > 4) AND (my_string = "this is my string") THEN

. . .

With the exception of patterns and the relational operators, the result of an expression is the same data type as the elements that make up the expression.

The following example shows a pattern expression that uses a string data type on the right-hand side of the expression. The LINE_BEGIN and REMAIN pattern keywords are used with the string constant "the" to create a pattern data type that is stored in the variable pat1:

pat1 := LINE_BEGIN + "the" + REMAIN;

Whenever possible, the DECTPU compiler evaluates constant expressions at compile time. DECTPU built-in procedures that can return a constant value given constant input are evaluated at compile time.

In the following example, the variable fubar has a single string assigned to it:

fubar := ASCII (27) + "[0m";

Note

"this is my

Do not assume that the DECTPU compiler automatically evaluates an expression in left-to-right order.

To avoid the need to rewrite code, you should write as if this compiler optimization were already implemented. If you need the compiler to evaluate an expression in a particular order, you should force the compiler to evaluate each operand in order before using the expression. To do so, use each operand in an assignment statement before using it in an expression. For example, suppose you want to use ROUTINE_1 and ROUTINE_2 in an expression.

Suppose, too, that ROUTINE_1 must be evaluated ﬁrst because it prompts for user input. To get this result, you could use the following code:

PARTIAL_1 := ROUTINE_1; PARTIAL_2 := ROUTINE_2;

You could then use a statement in which the order of evaluation was important, such as the following:

IF PARTIAL_1 OR PARTIAL_2

. . .

Lexical Elements of the DEC Text Processing Utility Language 4–9

Lexical Elements of the DEC Text Processing Utility Language

4.8 Expressions

There are four types of DECTPU expressions:

• Arithmetic

• Relational

• Pattern

• Boolean The following sections discuss each of these expression types.

4.8.1 Arithmetic Expressions

You can use any of the arithmetic operators (+, –, *, / ) with integer data types to form arithmetic expressions. DECTPU performs only integer arithmetic. The following are examples of valid DECTPU expressions:

12 + 4 ! adds two integers "abc" + "def" ! concatenates two strings

The following is not a valid DECTPU expression because it mixes data types:

"abc" + 12 ! you cannot mix data types

When performing integer division, DECTPU truncates the remainder; it does not round. The following examples show the results of division operations:

Expression Result

39 / 10 3

-39 / 10 -3

4.8.2 Relational Expressions

A relational expression tests the relationship between items of the same data type and returns an integer result. If the relationship is true, the result is integer 1; if the relationship is false, the result is integer 0.

Use the following relational operators with any of the DECTPU data types:

• Not equal operator (<>)

• Equal operator (=) For example, the following code fragment tests whether string1 starts with a

letter that occurs later in the alphabet than the starting letter of string2:

string1 := "gastropod"; string2 := "arachnid"; IF string1 > string2 THEN

MESSAGE ("Out of alphabetical order ");

ENDIF;

Use the following relational operators for comparisons of integers, strings, or markers:

• Greater than operator (>)

• Less than operator (<)

• Greater than or equal to operator (>=)

• Less than or equal to operator (<=)

4–10 Lexical Elements of the DEC Text Processing Utility Language

Lexical Elements of the DEC Text Processing Utility Language

4.8 Expressions

When used with markers, these operators test whether one marker is closer to (or farther from) the top of the buffer than another marker. (If markers are in different buffers, they will return as false.) For example, the procedure in Example 4–3 uses relational operators to determine which half of the buffer the cursor is located in.

Example 4–3 Procedure That Uses Relational Operators on Markers

PROCEDURE which_half LOCAL number_lines,

saved_mark := MARK (FREE_CURSOR); POSITION (BEGINNING_OF (CURRENT_BUFFER)); number_lines := GET_INFO (current_buffer, "record_count"); IF number_lines = 0 THEN

ELSE

ENDIF; ENDPROCEDURE;

saved_mark;

MESSAGE ("The current buffer is empty"); MOVE_VERTICAL (number_lines/2);

IF MARK (FREE_CURSOR) = saved_mark THEN

MESSAGE ("You are at the middle of the buffer");

ELSE

IF MARK (FREE_CURSOR) < saved_mark THEN

MESSAGE ("You are in the second half of the buffer");

ELSE

MESSAGE ("You are in the first half of the buffer");

ENDIF;

4.8.3 Pattern Expressions

A pattern expression consists of the pattern operators (+, &, |, @) combined with string constants, string variables, pattern variables, pattern procedures, pattern keywords, or parentheses. The following are valid pattern expressions:

pat1 := LINE_BEGIN + SPAN ("0123456789") + ANY ("abc"); pat2 := LINE_END + ("end"|"begin"); pat3 := SCAN (’;"!’) + (NOTANY ("’") & LINE_END);

See Chapter 3 for more information on pattern expressions.

4.8.4 Boolean Expressions

DECTPU performs bitwise logical operations on Boolean expressions. This means that the logical operation is performed on the individual bits of the operands to produce the individual bits of the result. In the following example, the value of user_variable is set to 3.

user_variable := 3 AND 7;

As another example, if user_var were %X7777 (30583), then you would use the following statement to set user_var to %x0077 (119):

user_var := user_var AND %XFF

Lexical Elements of the DEC Text Processing Utility Language 4–11

Lexical Elements of the DEC Text Processing Utility Language

4.8 Expressions

A true value in DECTPU is any odd integer; a false value is any even integer. Use the logical operators (AND, NOT, OR, XOR) to combine one or more expressions. DECTPU evaluates Boolean expressions enclosed in parentheses before other elements. The following example shows the use of parentheses to ensure that the Boolean expression is evaluated correctly:

IF (X = 12) AND (y <> 40) THEN

. . .

ENDIF;

4.9 Reserved Words

Reserved words are words that are deﬁned by DECTPU and that have a special meaning for the compiler.

DECTPU reserved words can be divided into the following categories:

• Keywords

• Built-in procedure names

• Predeﬁned constants

• Declarations and statements The following sections describe the categories of reserved words.

4.9.1 Keywords

Keywords are a DECTPU data type. They are reserved words that have special meaning to the compiler. You can redeﬁne DECTPU keywords only in local declarations (local constants, local variables, and parameters in a parameter list). If you give a local constant, local variable, or parameter the same name as that of a keyword, the compiler issues a message notifying you that the local declaration or parameter temporarily supersedes the keyword. In such a circumstance, the keyword is said to be occluded. See Chapter 3 and the DEC Text Processing Utility Reference Manual for more information on keywords.

4.9.2 Built-In Procedure Names

The DECTPU language has many built-in procedures that perform functions such as screen management, key deﬁnition, text manipulation, and program execution. You can redeﬁne DECTPU built-in procedures only in local declarations (local constants, local variables, and parameters in a parameter list). If you give a local constant, local variable, or parameter the same name as that of a built-in procedure, the compiler issues a message notifying you that the local declaration or parameter temporarily supersedes the built-in. In such a circumstance, the built-in is said to be occluded. See the DEC Text Processing Utility Reference Manual for a complete description of the DECTPU built-in procedures.

4.9.3 Predeﬁned Constants

The following is a list of predeﬁned global constants that DECTPU sets up. You cannot redeﬁne these constants.

• FALSE

• TPU$K_ALT_MODIFIED

• TPU$K_CTRL_MODIFIED

4–12 Lexical Elements of the DEC Text Processing Utility Language

Lexical Elements of the DEC Text Processing Utility Language

• TPU$K_HELP_MODIFIED

• TPU$K_MESSAGE_FACILITY

• TPU$K_MESSAGE_ID

• TPU$K_MESSAGE_SEVERITY

• TPU$K_MESSAGE_TEXT

• TPU$K_SEARCH_CASE

• TPU$K_SEARCH_DIACRITICAL

• TPU$K_SHIFT_MODIFIED

• TPU$K_UNSPECIFIED

• TRUE

4.9.4 Declarations and Statements

A DECTPU program can consist of a sequence of declarations and statements. These declarations and statements control the action performed in a procedure or a program. The following reserved words are the language elements that when combined properly make up the declarations and statements of DECTPU:

4.9 Reserved Words

• Module declaration

MODULE IDENT ENDMODULE

• Procedure declaration

PROCEDURE ENDPROCEDURE

• Repetitive statement

LOOP EXITIF ENDLOOP

• Conditional statement

IF THEN ELSE ENDIF

• Case statement

CASE FROM TO INRANGE OUTRANGE

Lexical Elements of the DEC Text Processing Utility Language 4–13

Lexical Elements of the DEC Text Processing Utility Language

4.9 Reserved Words

ENDCASE

• Error statement ON_ERROR ENDON_ERROR

• RETURN statement

• ABORT statement

• Miscellaneous declarations EQUIVALENCE LOCAL CONSTANT VARIABLE

GLOBAL, UNIVERSAL, BEGIN, and END are words reserved for future expansion of the DECTPU language.

The DECTPU declarations and statements are reserved words that you cannot deﬁne. Any attempt to redeﬁne these words results in a compilation error.

4.9.4.1 Module Declaration

With the MODULE/ENDMODULE declaration, you can group a series of global CONSTANT declarations, VARIABLE declarations, PROCEDURE declarations, and executable statements as one entity. After you compile a module, the compiler will generate two procedures for you. One procedure returns the identiﬁcation for the module and the other contains all the executable statements for the module. The procedure names generated by the compiler are module- name_MODULE_IDENT and module-name_MODULE_INIT, respectively.

Syntax

MODULE module-name IDENT string-literal

Compaq AA-PWCBD-TE User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Examples

Figures

Tables

Intended Audience

Document Structure

Preface

Related Documents

Reader’s Comments

How To Order Additional Documentation

Conventions

Overview of the DEC Text Processing Utility

1.1 Description of DECTPU

1.1.1 DECTPU Features

1.1.2 DECTPU and User Applications

Figure 1–1 DECTPU as a Base for EVE

1.1.3 DECTPU Environments

1.2 Description of DECwindows DECTPU

1.2.1 DECwindows DECTPU and DECwindows Features

1.2.2 DECwindows DECTPU and the DECwindows User Interface Language

1.3 Description of EVE

Figure 1–2 DECTPU as a Base for User-Written Interfaces

1.4 DECTPU Language

1.4.1 Data Types

1.4.2 Language Declarations

1.4.3 Language Statements

1.4.4 Built-In Procedures

1.4.5 User-Written Procedures

Example 1–1 Sample User-Written Procedure

1.5 Terminals Supported by DECTPU

1.6 Learning Path for DECTPU

Getting Started with DECTPU

2.1 Invoking DECTPU on OpenVMS Systems

2.1.2 Startup Files

2.2 Invoking DECTPU from a DCL Command Procedure

2.2.1 Setting Up a Special Editing Environment

Example 2–1 DCL Command Procedure FILENAME.COM

Example 2–2 DCL Command Procedure FORTRAN_TS.COM

2.2.2 Creating a Noninteractive Application

Example 2–3 DCL Command Procedure INVISIBLE_TPU.COM

Example 2–4 DECTPU Command File GSR.TPU

2.3 Invoking DECTPU from a Batch Job

2.4 Using Journal Files

Table 2–2 Journaling Behavior Established by EVE

2.4.1 Keystroke Journaling

2.4.2 Buffer-Change Journaling

2.4.3 Buffer-Change Journal File-Naming Algorithm

2.5 Avoiding Errors Related to Virtual Address Space

2.6.1 /CHARACTER_SET

Table 2–3 Character Set Values You Can Set with /CHARACTER_SET

2.6.2 /COMMAND

2.6.3 /CREATE

2.6.4 /DEBUG

2.6.5 /DISPLAY

2.6.6 /INITIALIZATION

2.6.7 /INTERFACE

2.6.8 /JOURNAL

2.6.9 /MODIFY

2.6.10 /OUTPUT

2.6.11 /READ_ONLY

2.6.12 /RECOVER

2.6.13 /SECTION

2.6.14 /START_POSITION

DEC Text Processing Utility Data Types

3.1 Array Data Type

3.2 Buffer Data Type

3.3 Integer Data Type

3.4 Keyword Data Type

Table 3–1 Keywords Used for Key Names

3.5 Learn Data Type

3.6 Marker Data Type

Example 3–1 Suppressing the Addition of Padding Blanks

3.7 Pattern Data Type

3.7.1 Using Pattern Built-In Procedures and Keywords

3.7.2 Using Keywords to Build Patterns

3.7.3 Using Pattern Operators