Compaq Computer Accessories 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  
Com p a q Com p u ter Cor p or a tion  
Hou ston , Texa s  
 
Contents  
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
ix  
1 Overview of the DEC Text Processing Utility  
1.1  
Description of DECTPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
DECTPU Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
DECTPU and User Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
DECTPU Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Description of DECwindows DECTPU . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
DECwindows DECTPU and DECwindows Features . . . . . . . . . . . . . .  
DECwindows DECTPU and the DECwindows User Interface  
1–1  
1–1  
1–2  
1–2  
1–2  
1–3  
1.1.1  
1.1.2  
1.1.3  
1.2  
1.2.1  
1.2.2  
Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Description of EVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
DECTPU Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Language Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Language Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Built-In Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
User-Written Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Terminals Supported by DECTPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Learning Path for DECTPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
1–4  
1–4  
1–5  
1–6  
1–6  
1–6  
1–6  
1–7  
1–7  
1–8  
1.3  
1.4  
1.4.1  
1.4.2  
1.4.3  
1.4.4  
1.4.5  
1.5  
1.6  
2 Getting Started with DECTPU  
2.1  
Invoking DECTPU on OpenVMS Systems . . . . . . . . . . . . . . . . . . . . . . . . .  
2–1  
2–2  
2–2  
2–3  
2–3  
2–4  
2–6  
2–6  
2–7  
2–7  
2–8  
2–8  
2–9  
2.1.1  
2.1.2  
2.2  
2.2.1  
2.2.2  
2.3  
Default File Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Startup Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Invoking DECTPU from a DCL Command Procedure . . . . . . . . . . . . . . . .  
Setting Up a Special Editing Environment . . . . . . . . . . . . . . . . . . . . .  
Creating a Noninteractive Application . . . . . . . . . . . . . . . . . . . . . . . . .  
Invoking DECTPU from a Batch J ob . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Using J ournal Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Keystroke J ournaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Buffer-Change J ournaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Buffer-Change J ournal File-Naming Algorithm . . . . . . . . . . . . . . . . . .  
Avoiding Errors Related to Virtual Address Space . . . . . . . . . . . . . . . . . . .  
Using OpenVMS EDIT/TPU Command Qualifiers . . . . . . . . . . . . . . . . . . .  
/CHARACTER_SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
/COMMAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
/CREATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
/DEBUG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
/DISPLAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
/INITIALIZATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
/INTERFACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
2.4  
2.4.1  
2.4.2  
2.4.3  
2.5  
2.6  
2.6.1  
2.6.2  
2.6.3  
2.6.4  
2.6.5  
2.6.6  
2.6.7  
2–9  
2–10  
2–11  
2–12  
2–12  
2–13  
2–14  
iii  
 
2.6.8  
2.6.9  
/J OURNAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
/MODIFY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
/OUTPUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
/READ_ONLY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
/RECOVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
/SECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
/START_POSITION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
2–14  
2–15  
2–16  
2–17  
2–18  
2–19  
2–20  
2.6.10  
2.6.11  
2.6.12  
2.6.13  
2.6.14  
3 DEC Text Processing Utility Data Types  
3.1  
3.2  
3.3  
3.4  
3.5  
3.6  
3.7  
3.7.1  
3.7.2  
3.7.3  
3.7.3.1  
3.7.3.2  
3.7.3.3  
3.7.3.4  
3.7.3.5  
3.7.4  
3.7.5  
3.7.6  
3.8  
3.9  
3.10  
3.11  
3.12  
3.13  
3.14  
3.14.1  
3.14.2  
3.14.3  
3.14.4  
3.14.5  
3.14.6  
3.14.7  
3.14.8  
Array Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Buffer Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Integer Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Keyword Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Learn Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Marker Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Pattern Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Using Pattern Built-In Procedures and Keywords . . . . . . . . . . . . . . . .  
Using Keywords to Build Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Using Pattern Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
+ (Pattern Concatenation Operator) . . . . . . . . . . . . . . . . . . . . . . . .  
& (Pattern Linking Operator) . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
3–2  
3–3  
3–4  
3–5  
3–7  
3–8  
3–10  
3–12  
3–12  
3–13  
3–13  
3–13  
3–14  
3–14  
3–15  
3–16  
3–16  
3–17  
3–18  
3–18  
3–19  
3–20  
3–21  
3–22  
3–22  
3–23  
3–23  
3–24  
3–24  
3–25  
3–25  
3–25  
3–26  
|
(Pattern Alternation Operator) . . . . . . . . . . . . . . . . . . . . . . . . .  
@ (Partial Pattern Assignment Operator) . . . . . . . . . . . . . . . . . . .  
Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Compiling and Executing Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Searching for a Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Anchoring a Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Process Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Program Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Range Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
String Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Unspecified Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Widget Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Window Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Defining Window Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Creating Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Displaying Window Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Mapping Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Removing Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Using the Screen Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Getting Information on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Terminals That Do Not Support Windows . . . . . . . . . . . . . . . . . . . . . .  
4 Lexical Elements of the DEC Text Processing Utility Language  
4.1  
4.2  
4.3  
4.3.1  
4.3.2  
4.3.3  
4.3.4  
4.3.5  
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Case Sensitivity of Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
DEC Multinational Character Set (DEC_MCS) . . . . . . . . . . . . . . . . . .  
ISO Latin1 Character Set (ISO_LATIN1) . . . . . . . . . . . . . . . . . . . . . . .  
General Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Entering Control Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
DECTPU Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
4–1  
4–1  
4–2  
4–2  
4–3  
4–3  
4–3  
4–4  
iv  
 
4.4  
4.5  
4.6  
4.7  
4.8  
4.8.1  
4.8.2  
4.8.3  
4.8.4  
4.9  
4.9.1  
4.9.2  
4.9.3  
4.9.4  
4.9.4.1  
4.9.4.2  
4.9.4.3  
4.9.4.4  
4.9.4.5  
4.9.4.6  
4.9.4.7  
4.9.4.8  
4.9.4.9  
4.9.4.10  
4.9.4.11  
4.9.4.12  
4.9.4.13  
4.9.4.14  
4.9.4.15  
4.9.4.16  
4.9.4.17  
4.9.4.18  
4.9.4.19  
4.9.5  
Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Arithmetic Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Relational Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Pattern Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Boolean Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Reserved Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Built-In Procedure Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Predefined Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Declarations and Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Module Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Procedure Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Procedure Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Procedure Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Procedures That Return a Result . . . . . . . . . . . . . . . . . . . . . . . . . .  
Recursive Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
ON_ERROR Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Assignment Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Repetitive Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Conditional Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Case Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Procedural Error Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Case-Style Error Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Ctrl/C Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
RETURN Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
ABORT Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Miscellaneous Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
EQUIVALENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
LOCAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
CONSTANT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
VARIABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Lexical Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Conditional Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Specifying the Radix of Numeric Constants . . . . . . . . . . . . . . . . . . . . .  
4–5  
4–5  
4–6  
4–7  
4–8  
4–10  
4–10  
4–11  
4–11  
4–12  
4–12  
4–12  
4–12  
4–13  
4–14  
4–15  
4–15  
4–15  
4–18  
4–18  
4–19  
4–19  
4–19  
4–20  
4–20  
4–20  
4–21  
4–23  
4–24  
4–25  
4–28  
4–28  
4–29  
4–30  
4–30  
4–30  
4–32  
4–32  
4–32  
4–33  
4–34  
4.9.5.1  
4.9.5.2  
4.9.5.3  
4.9.5.4  
4.10  
4.10.1  
4.10.2  
5 DEC Text Processing Utility Program Development  
5.1  
Creating DECTPU Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Simple Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Complex Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Program Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Programming in DECwindows DECTPU . . . . . . . . . . . . . . . . . . . . . . . . . .  
Widget Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Input Focus Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
5–1  
5–2  
5–2  
5–3  
5–4  
5–4  
5–5  
5.1.1  
5.1.2  
5.1.3  
5.2  
5.2.1  
5.2.2  
v
 
5.2.3  
Global Selection Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Difference Between Global Selection and Clipboard . . . . . . . . . . . .  
Handling of Multiple Global Selections . . . . . . . . . . . . . . . . . . . . .  
Relation of Global Selection to Input Focus . . . . . . . . . . . . . . . . . .  
Response to Requests for Information About the Global  
5–6  
5–6  
5–6  
5–6  
5.2.3.1  
5.2.3.2  
5.2.3.3  
5.2.3.4  
Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Using Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Background on DECwindows Callbacks . . . . . . . . . . . . . . . . . . . . .  
Internally Defined DECTPU Callback Routines and  
5–7  
5–7  
5–8  
5.2.4  
5.2.4.1  
5.2.4.2  
Application-Level Callback Action Routines . . . . . . . . . . . . . . . . . .  
Internally Defined DECTPU Callback Routines with UIL . . . . . . .  
Internally Defined DECTPU Callback Routines with Widgets Not  
Defined by UIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Application-Level Callback Action Routines . . . . . . . . . . . . . . . . . .  
Callable Interface-Level Callback Routines . . . . . . . . . . . . . . . . . .  
Using Closures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Specifying Values for Widget Resources in DECwindows DECTPU . . .  
DECTPU Data Types for Specifying Resource Values . . . . . . . . . .  
Specifying a List as a Resource Value . . . . . . . . . . . . . . . . . . . . . .  
Writing Code Compatible with DECwindows EVE . . . . . . . . . . . . . . . . . . .  
Select Ranges in DECwindows EVE . . . . . . . . . . . . . . . . . . . . . . . . . .  
Dynamic Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Static Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Found Range Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Relation of EVE Selection to DECwindows Global Selection . . . . .  
Compiling DECTPU Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Compiling on the EVE Command Line . . . . . . . . . . . . . . . . . . . . . . . .  
Compiling in a DECTPU Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Executing DECTPU Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Procedure Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Process Suspension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Using DECTPU Startup Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Section Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Command Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Initialization Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Sequence in Which DECTPU Processes Startup Files . . . . . . . . . . . . .  
Using Section Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Creating and Processing a New Section File . . . . . . . . . . . . . . . . .  
Extending an Existing Section File . . . . . . . . . . . . . . . . . . . . . . . .  
Sample Section File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Recommended Conventions for Section Files . . . . . . . . . . . . . . . . .  
Using Command Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Using EVE Initialization Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Using an EVE Initialization File at Startup . . . . . . . . . . . . . . . . .  
Using an EVE Initialization File During an Editing Session . . . . .  
How an EVE Initialization File Affects Buffer Settings . . . . . . . . .  
Debugging DECTPU Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Using Your Own Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Using the DECTPU Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Debugging Section Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Debugging Command Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Debugging Other DECTPU Source Code . . . . . . . . . . . . . . . . . . . .  
Getting Started with the DECTPU Debugger . . . . . . . . . . . . . . . . . . .  
Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
5–8  
5–8  
5.2.4.3  
5.2.4.4  
5–9  
5–9  
5–9  
5.2.4.5  
5.2.4.6  
5.2.5  
5–10  
5–10  
5–10  
5–11  
5–13  
5–13  
5–13  
5–13  
5–14  
5–14  
5–14  
5–15  
5–15  
5–15  
5–16  
5–16  
5–17  
5–17  
5–17  
5–18  
5–18  
5–19  
5–19  
5–20  
5–21  
5–23  
5–24  
5–25  
5–26  
5–27  
5–27  
5–28  
5–28  
5–28  
5–28  
5–29  
5–29  
5–29  
5–30  
5.2.6  
5.2.6.1  
5.2.6.2  
5.3  
5.3.1  
5.3.1.1  
5.3.1.2  
5.3.1.3  
5.3.1.4  
5.4  
5.4.1  
5.4.2  
5.5  
5.5.1  
5.5.2  
5.6  
5.6.1  
5.6.2  
5.6.3  
5.6.4  
5.6.5  
5.6.5.1  
5.6.5.2  
5.6.5.3  
5.6.5.4  
5.6.6  
5.6.7  
5.6.7.1  
5.6.7.2  
5.6.7.3  
5.7  
5.7.1  
5.7.2  
5.7.2.1  
5.7.2.2  
5.7.2.3  
5.7.3  
5.8  
vi  
 
A Sample DECTPU Procedures  
A.1  
A.2  
A.3  
A.4  
Line-Mode Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
A–1  
A–2  
A–6  
A–7  
Translation of Control Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Restoring Terminal Width Before Exiting from DECTPU . . . . . . . . . . . . .  
Running DECTPU from an OpenVMS Subprocess . . . . . . . . . . . . . . . . . .  
B DECTPU Terminal Support  
B.1  
Using Screen-Oriented Editing on Supported Terminals . . . . . . . . . . . . . .  
B–1  
B–1  
B–3  
B–3  
B–3  
B.1.1  
B.1.2  
B.2  
Terminal Settings on OpenVMS Systems That Affect DECTPU . . . . .  
SET TERMINAL Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Using Line-Mode Editing on Unsupported Terminals . . . . . . . . . . . . . . . .  
Using Terminal Wrap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
B.3  
C DECTPU Debugger Commands  
Index  
Examples  
1–1  
2–1  
2–2  
2–3  
2–4  
3–1  
4–1  
4–2  
4–3  
4–4  
4–5  
4–6  
4–7  
4–8  
4–9  
4–10  
4–11  
4–12  
4–13  
4–14  
4–15  
5–1  
5–2  
5–3  
5–4  
5–5  
5–6  
5–7  
Sample User-Written Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
1–7  
2–4  
DCL Command Procedure FILENAME.COM . . . . . . . . . . . . . . . . . . . .  
DCL Command Procedure FORTRAN_TS.COM . . . . . . . . . . . . . . . . .  
DCL Command Procedure INVISIBLE_TPU.COM . . . . . . . . . . . . . . .  
DECTPU Command File GSR.TPU . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Suppressing the Addition of Padding Blanks . . . . . . . . . . . . . . . . . . . .  
Global and Local Variable Declarations . . . . . . . . . . . . . . . . . . . . . . . .  
Global and Local Constant Declarations . . . . . . . . . . . . . . . . . . . . . . .  
Procedure That Uses Relational Operators on Markers . . . . . . . . . . . .  
Simple Procedure with Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Complex Procedure with Optional Parameters . . . . . . . . . . . . . . . . . . .  
Procedure That Returns a Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Procedure Within Another Procedure . . . . . . . . . . . . . . . . . . . . . . . . . .  
Recursive Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Procedure That Uses the CASE Statement . . . . . . . . . . . . . . . . . . . . .  
Procedure That Uses the ON_ERROR Statement . . . . . . . . . . . . . . . .  
Procedure with a Case-Style Error Handler . . . . . . . . . . . . . . . . . . . . .  
Procedure That Returns a Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Procedure That Returns a Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Using RETURN in an ON_ERROR Section . . . . . . . . . . . . . . . . . . . . .  
Simple Error Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
SHOW (SUMMARY) Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Syntax of a DECTPU Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Sample DECTPU Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Sample Program for a Section File . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Source Code for Minimal Interface to DECTPU . . . . . . . . . . . . . . . . . .  
Command File for GOTO_TEXT_MARKER . . . . . . . . . . . . . . . . . . . . .  
SHOW DEFAULTS BUFFER Display . . . . . . . . . . . . . . . . . . . . . . . . .  
2–4  
2–5  
2–5  
3–10  
4–5  
4–6  
4–11  
4–16  
4–17  
4–18  
4–18  
4–19  
4–22  
4–24  
4–26  
4–28  
4–29  
4–29  
4–30  
5–2  
5–3  
5–4  
5–20  
5–22  
5–25  
5–27  
vii  
 
A–1  
A–2  
A–3  
A–4  
B–1  
Line-Mode Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Procedure to Display Control Characters . . . . . . . . . . . . . . . . . . . . . . .  
Procedure to Restore Screen to Original Width . . . . . . . . . . . . . . . . . .  
Procedure to Run DECTPU from a Subprocess . . . . . . . . . . . . . . . . . .  
DCL Command Procedure for SET TERM/NOWRAP . . . . . . . . . . . . . .  
A–1  
A–2  
A–6  
A–7  
B–4  
Figures  
1–1  
1–2  
DECTPU as a Base for EVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
DECTPU as a Base for User-Written Interfaces . . . . . . . . . . . . . . . . .  
1–2  
1–5  
Tables  
2–1  
2–2  
2–3  
3–1  
3–2  
4–1  
4–2  
4–3  
4–4  
4–5  
4–6  
5–1  
Default File Specifications on OpenVMS Systems . . . . . . . . . . . . . . . .  
J ournaling Behavior Established by EVE . . . . . . . . . . . . . . . . . . . . . .  
Character Set Values You Can Set with /CHARACTER_SET . . . . . . . .  
Keywords Used for Key Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Effects of Two String-Reduction Operations . . . . . . . . . . . . . . . . . . . . .  
Categories of ASCII Character Set Characters . . . . . . . . . . . . . . . . . .  
Categories of DEC Multinational Character Set Characters . . . . . . . .  
Categories for ISO Latin1 Characters . . . . . . . . . . . . . . . . . . . . . . . . .  
DECTPU Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
DECTPU Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Operator Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
2–2  
2–6  
2–10  
3–6  
3–21  
4–2  
4–2  
4–3  
4–4  
4–7  
4–8  
Relationship Between DECTPU Data Types and DECwindows  
Argument Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
5–11  
5–2  
B–1  
Special DECTPU Variables That Require a Value from a Layered  
Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
5–24  
B–1  
Terminal Behavior That Affects DECTPUs Performance . . . . . . . . . . .  
viii  
 
Preface  
This manual discusses the DEC Text Processing Utility (DECTPU).  
Intended Audience  
This manual is for experienced programmers who know at least one computer  
language, as well as for new users of DECTPU. Some features of DECTPU, for  
example, the callable interface and the built-in procedure FILE_PARSE, are  
for system programmers who understand Compaq OpenVMS operating system  
concepts. Relevant documents about the OpenVMS operating system are listed  
under Related Documents.  
Document Structure  
This manual is organized as follows:  
Chapter 1 contains an overview of DECTPU.  
Chapter 2 describes how to invoke DECTPU.  
Chapter 3 provides detailed information on DECTPU data types.  
Chapter 4 discusses the lexical elements of DECTPU. These include the  
character set, identifiers, variables, constants, and reserved words, such as  
DECTPU language statements.  
Chapter 5 describes DECTPU program development.  
Appendix A contains sample procedures written in DECTPU.  
Appendix B describes terminals supported by DECTPU.  
Appendix C lists commands for debugging DECTPU.  
Related Documents  
For additional information about OpenVMS products and services, access the  
following World Wide Web address:  
http://www.openvms.compaq.com/  
Reader’s Comments  
Compaq welcomes your comments on this manual. Please send comments to  
either of the following addresses:  
Internet  
op en vm sd oc@com p a q.com  
ix  
 
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  
PF1 x  
Return  
A sequence such as Ctrl/x indicates that you must hold down  
the key labeled Ctrl while you press another key or a pointing  
device button.  
A sequence such as PF1 x indicates that you must first press  
and release the key labeled PF1 and then press and release  
another key or a pointing device 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.  
. . .  
A horizontal ellipsis in examples indicates one of the following  
possibilities:  
Additional optional arguments in a statement have been  
omitted.  
The preceding item or items can be repeated one or more  
times.  
Additional parameters, values, or other information can be  
entered.  
.
.
.
A vertical ellipsis indicates the omission of items from a code  
example or command format; the items are omitted because  
they are not important to the topic being discussed.  
( )  
In command format descriptions, parentheses indicate that you  
must enclose the options in parentheses if you choose more  
than one.  
[ ]  
In command format descriptions, brackets indicate optional  
elements. You can choose one, none, or all of the options.  
(Brackets are not optional, however, in the syntax of a directory  
name in an OpenVMS file specification or in the syntax of a  
substring specification in an assignment statement.)  
[ | ]  
{ }  
In command format descriptions, vertical bars separating  
items inside brackets indicate that you choose one, none, or  
more than one of the options.  
In command format descriptions, braces indicate required  
elements; you must choose one of the options listed.  
x
 
bold text  
This text style represents the introduction of a new term or the  
name of an argument, an attribute, or a reason.  
italic text  
Italic text indicates important information, complete titles  
of manuals, or variables. Variables include information that  
varies in system output (Internal error number), in command  
lines (/PRODUCER=name), and in command parameters in  
text (where dd represents the predefined code for the device  
type).  
UPPERCASE TEXT  
Uppercase text indicates a command, the name of a routine,  
the name of a file, or the abbreviation for a system privilege.  
Monospace text  
Monospace type indicates code examples and interactive screen  
displays.  
In the C programming language, monospace type in text  
identifies the following elements: keywords, the names  
of independently compiled external functions and files,  
syntax summaries, and references to variables or identifiers  
introduced in an example.  
-
A hyphen at the end of a command format description,  
command line, or code line indicates that the command or  
statement continues on the following line.  
numbers  
All numbers in text are assumed to be decimal unless  
otherwise noted. Nondecimal radixes—binary, octal, or  
hexadecimal—are explicitly indicated.  
xi  
 
 
1
Overview of the DEC Text Processing Utility  
This chapter presents information about the DEC Text Processing Utility  
(DECTPU). The chapter includes the following:  
A description of DECTPU  
A description of DECwindows DECTPU  
A description of the Extensible Versatile Editor (EVE)  
Information about the DECTPU language  
Information about the hardware that DECTPU supports  
How to learn more about DECTPU  
1.1 Description of DECTPU  
DECTPU is a high-performance, programmable, text processing utility that  
includes the following:  
A high-level procedural language  
A compiler  
An interpreter  
Text manipulation routines  
Integrated display managers for the character-cell terminal and DECwindows  
environments  
The Extensible Versatile Editor (EVE) interface, which is written in DECTPU  
DECTPU is a procedural programming language that enables text processing  
tasks; it is not an application.  
1.1.1 DECTPU Features  
DECTPU aids application and system programmers in developing tools that  
manipulate text. For example, programmers can use DECTPU to design an  
editor for a specific environment.  
DECTPU provides the following special features:  
Multiple buffers  
Multiple windows  
Multiple subprocesses  
Keystroke and buffer-change journaling  
Text processing in batch mode  
Insert or overstrike text entry  
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 definition  
Procedural language  
Callable interface  
1.1.2 DECTPU and User Applications  
DECTPU is a language that you can use as a base on which to layer text  
processing applications. When you choose an editor or other application to layer  
on DECTPU, that becomes the interface between you and DECTPU. You can also  
create your own interface to access DECTPU.  
Figure 1–1 shows the relationship of DECTPU with EVE as its user interface.  
Figure 1–1 DECTPU as a Base for EVE  
EVE  
Editor  
D
E
C
T
P
U
ZK−6545−GE  
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.  
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 floating-point numbers or to manipulate entities such as lines, curves,  
and fonts.  
With DECwindows DECTPU, you can create a wide variety of widgets, designate  
callback routines for those widgets, fetch and set geometry and text-related  
resources of the widgets, and perform other functions related to creating a  
DECwindows application. For example, the DECwindows EVE editor is a text  
processing interface created with DECwindows DECTPU.  
1.2.2 DECwindows DECTPU and the DECwindows User Interface Language  
You can use DECTPU programs with DECwindows User Interface Language  
(UIL) files just as you would use programs in any other language with UIL  
files. For an example of a DECTPU program and a UIL file designed to work  
together, see the description of the CREATE_WIDGET built-in in the DEC Text  
Processing Utility Reference Manual. For more information about using UIL  
files in conjunction with programs written in other languages, see the VMS  
DECwindows Guide to Application Programming.  
1.3 Description of EVE  
The Extensible Versatile Editor (EVE) is the editor provided with DECTPU. EVE  
is easy to learn and to use. You can access many of EVEs editing functions by  
pressing a single key on the keypad. EVE is also a powerful and efficient editor,  
which makes it attractive to experienced users of text editors. You can access  
more advanced editing functions by entering commands on the EVE command  
line. Many of the special features of DECTPU (such as multiple windows) are  
available with EVE commands. You can access other DECTPU features by  
entering DECTPU statements from within EVE.  
EVE has both a character-cell and a DECwindows interface. To use EVEs  
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  
UserWritten  
Extensions  
to EVE  
UserWritten  
Application  
EVE  
Editor  
D
E
C
T
P
U
ZK6544GE  
You can implement extensions to EVE with any of the following:  
A DECTPU command file (DECTPU source code)  
A DECTPU section file (compiled DECTPU code in binary form)  
An initialization file (commands in a format that EVE can process)  
Because a DECTPU section file is already compiled, startup time for your  
editor or application is shorter when you use a section file than when you use a  
command file or an initialization file. Section 2.1.2 contains more information on  
startup files.  
To implement an editor or application that is entirely user written, use a section  
file. Chapter 5 contains more information on DECTPU command files, section  
files, and initialization files. The DEC Text Processing Utility Reference Manual  
contains information on layering applications on DECTPU.  
1.4 DECTPU Language  
You can view the DECTPU language as the most basic component of DECTPU.  
To access the features of DECTPU, write a program in the DECTPU language  
and then use the utility to compile and execute the program. A program written  
in DECTPU can be as simple as a single statement or as complex as the section  
file that implements EVE.  
The block-structured DECTPU language is easy to learn and use. DECTPU  
language features include a large number of data types, relational operators,  
error interception, looping and case statements, and built-in procedures that  
simplify development or extension of an editor or application. Comments are  
indicated with a single comment character ( ! ) so that you can document your  
procedures easily. There are also capabilities for debugging procedures with  
user-written debugging programs.  
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 definition, text manipulation, and program execution.  
You can use built-in procedures to create your own procedures. You can also  
invoke built-in procedures from within EVE. The DEC Text Processing Utility  
Reference Manual contains a description of each of the DECTPU built-in  
procedures.  
1–6 Overview of the DEC Text Processing Utility  
 
Overview of the DEC Text Processing Utility  
1.4 DECTPU Language  
1.4.5 User-Written Procedures  
You can write your own procedures that combine DECTPU language statements  
and calls to DECTPU built-in procedures. DECTPU procedures can return values  
and can be recursive. After you write a procedure and compile it, you use the  
procedure name to invoke it.  
When writing a procedure, use the following guidelines:  
Start each procedure with the word PROCEDURE, followed by the procedure  
name of your choice.  
End each procedure with the word ENDPROCEDURE.  
Place a semicolon after each statement or built-in call if the statement or call  
is followed by another statement or call.  
If the statement or call is not followed by another statement or call, the  
semicolon is not necessary.  
Example 1–1 is a sample procedure that uses the DECTPU language statements  
PROCEDURE/ENDPROCEDURE and the built-in procedures POSITION,  
BEGINNING_OF, and CURRENT_BUFFER to move the current character  
position to the beginning of the current buffer. The procedure uses the MESSAGE  
built-in to display a message; it uses the GET_INFO built-in to get the name of  
the current buffer.  
Example 1–1 Sample User-Written Procedure  
! This procedure moves the editing  
! position to the top of the buffer  
PROCEDURE user_top  
POSITION (BEGINNING_OF (CURRENT_BUFFER));  
MESSAGE ("Now in buffer" + GET_INFO (CURRENT_BUFFER, "name"));  
ENDPROCEDURE;  
Once you have compiled this procedure, you can invoke it with the name user_top.  
For information about writing procedures, see Chapter 4 and Chapter 5.  
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  
DECTPUs 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 qualifier 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  
1.6 Learning Path for DECTPU  
The suggested path for learning to use DECTPU is to first 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 definitions the editor  
uses. Then write DECTPU procedures to implement your extensions. Make  
sure that the DECTPU procedures you write do not conflict 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  
 
2
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 files  
Avoiding errors related to virtual address space  
Using OpenVMS command line qualifiers  
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 file:  
$ 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 files on the DECTPU command line. The files  
must be separated by commas. The maximum number of files you can specify is  
10. For the ambiguous file 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 Specifications  
Table 2–1 lists the default TPU and EVE file specifications on OpenVMS systems.  
Table 2–1 Default File Specifications on OpenVMS Systems  
File  
OpenVMS File Specification  
Section  
SYS$SHARE:TPU$SECTION.TPU$SECTION  
TPU$COMMAND.TPU  
Command  
Init  
SYS$DISK:EVE$INIT.EVE  
Init  
SYS$LOGIN:EVE$INIT.EVE  
SYS$SHARE:TPU$DEBUG.TPU  
SYS$DISK:.TJ L  
Debugger  
Keystroke journal  
Buffer-change journal  
Buffer-change journal  
Work  
SYS$SCRATCH:.TPU$J OURNAL  
TPU$J OURNAL:.TPU$J OURNAL  
SYS$SCRATCH:.TPU$WORK  
SYS$LIBRARY:.UID1  
Motif Resource  
Application defaults  
Application defaults  
EVE Motif resource  
EVE sources  
DECW$SYSTEM_DEFAULTS:.DAT  
DECW$USER_DEFAULTS:.DAT2  
SYS$SHARE:EVE$WIDGETS.UID3  
SYS$EXAMPLES:EVE$*.*  
1These directory and file type defaults are added by the Motif Resource Manager if missing from the  
file specification.  
2xxxxxx = suffix from mktemp(3). Note that this file is invisible.  
3These X resource files are used only by dmtpu and dxtpu.  
OpenVMS system managers should note that the OpenVMS systemwide logical  
name is defined 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 files and section files can create or customize a DECTPU editor or  
application. Initialization files can customize EVE or other layered applications  
by using EVE or other application-specific commands, settings, and key bindings.  
A com m a n d file is a file that contains DECTPU source code. A command file has  
the file type .TPU and is used with the DECTPU /COMMAND=filespec qualifier.  
DECTPU tries to read a command file unless you specify /NOCOMMAND. The  
default command file is the file called TPU$COMMAND.TPU in your current  
directory, if such a file exists. You can specify a different file by defining the  
logical name TPU$COMMAND.  
A section file is the compiled form of DECTPU source code. It is a binary  
file that has the default file type .TPU$SECTION. It is used with the qualifier  
/SECTION=filespec. The default section file is TPU$SECTION.TPU$SECTION in  
the area SYS$SHARE. The systemwide logical name TPU$SECTION is defined  
as EVE$SECTION. This definition causes the EVE editor to be invoked by default  
when you use the DCL command EDIT/TPU. You must specify a different section  
file (for example, /SECTION= my_section_file) 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 qualifier, DECTPU  
does not use any binary file to provide an interface. Even the Return and  
Delete keys are not defined. Use /NOSECTION when you are running a  
standalone command file or when you are creating a new section file and  
do not want the procedures, variables, and definitions from an existing  
section file to be included. See Section 2.6 and Chapter 5 for more  
information on /NOSECTION.  
An in itia liza tion file contains commands for a DECTPU-based application. For  
example, an initialization file for EVE can contain commands that define keys or  
set margins. Initialization files are easy to create, but they cause DECTPU to  
start up somewhat more slowly than section and command files do. To invoke an  
initialization file, use the /INITIALIZATION qualifier. For more information on  
using initialization files, see Chapter 5.  
You can use either a command file or a section file, or both, to customize or extend  
an existing interface. Generally, you use a command file for minor customization  
of an interface. Because startup time is faster with a section file, you should  
use a section file 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 file only if your application supports the use of such a  
file.  
The source files for EVE are in SYS$EXAMPLES. To see a list of the EVE source  
files, type the following at the DCL prompt:  
$ DIRECTORY SYS$EXAMPLES:EVE$*.TPU  
If you cannot find these files on your system, see your system manager.  
Chapter 5 describes how to write and process command files and section files.  
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 first establishes the environment that you want  
and then invokes DECTPU. In such a command procedure, you must define  
SYS$INPUT to have the same value as SYS$COMMAND because DECTPU  
signals an error if SYS$INPUT is not defined 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 file  
that you were editing and uses it as the input file for DECTPU. When you edit a  
file, the file name you specify is saved in the DCL symbol last_file_edited. If you  
do not specify a file name when you invoke the editor the next time, the file 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 specifies 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  
file and have them read from the file 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 qualifiers to invoke  
DECTPU:  
/NOSECTION—This qualifier prevents DECTPU from using a section file. All  
procedures and key definitions must be specified in a command file.  
/COMMAND=gsr.tpu—This qualifier specifies a command file that contains  
the code to be executed (GSR.TPU).  
/NODISPLAYThis qualifier 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 file GSR.TPU, which is used as the file specification  
for the /COMMAND qualifier, performs a search through the current buffer  
and replaces a string or a pattern with a string. Example 2–4 shows the file  
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);  
ERASE (src_range);  
! Search returns a range if found  
! Remove first string  
POSITION (END_OF (src_range));  
COPY_TEXT (str2);  
replacement_count := replacement_count + 1;  
! Move to right place  
! Replace with second string  
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 file called MY_FILE.TXT, type the following at the  
DCL prompt:  
$ @invisible_tpu my_file.txt  
You must explicitly write out any modified buffers before leaving the editor with  
QUIT or EXIT. If you use QUIT before writing out such buffers, DECTPU quits  
without saving the modifications. If you use EXIT, DECTPU asks if it should  
write the file before exiting.  
Getting Started with DECTPU 2–5  
 
Getting Started with DECTPU  
2.3 Invoking DECTPU from a Batch Job  
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 file GSR.TPU (shown in Example 2–4) to  
make edits in batch mode to a file 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 file that the batch job creates.  
In batch DECTPU, EXIT is the same as QUIT.  
2.4 Using Journal Files  
J ournal files 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 J OURNAL_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  
Keystroke  
Journaling  
OpenVMS Qualifier  
Effect on Buffer-Change Journaling  
None specified  
Disabled  
Disabled  
Enabled  
Disabled  
Enabled.  
Enabled.  
Enabled.  
/J OURNAL  
/J OURNAL = filename  
/NOJ OURNAL  
Disabled. However, you can use SET  
(J OURNALING) to enable buffer-change  
journaling.  
Caution  
J ournal files contain a record of all information being edited. Therefore,  
when editing files that contain secure or confidential data, be sure to keep  
the journal files secure as well.  
You must use the same major version of DECTPU to recover the journal  
that you used to create it.  
2–6 Getting Started with DECTPU  
 
Getting Started with DECTPU  
2.4 Using Journal Files  
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 file, use a statement similar to  
the following:  
filename := GET_INFO (SYSTEM, "journal_file");  
For more information on using a keystroke journal file for recovery, see  
Section 2.6.8 and the Extensible Versatile Editor Reference Manual.  
Note  
Compaq strongly recommends the use of buffer-change journaling rather  
than keystroke journaling.  
To reconstruct your work, use the /J OURNAL and /RECOVER qualifiers. The  
following example shows system recovery on a file called J ACKI.SDML:  
$ EDIT/TPU JACKI.SDML /JOURNAL /RECOVER  
2.4.2 Buffer-Change Journaling  
Buffer-change journaling creates a separate journal file for each text buffer.  
The application can use the enhanced SET (J OURNALING) built-in to direct  
DECTPU to establish and maintain a separate journal file for any buffer or  
buffers created during the session. The application programmer or user can also  
use the SET (J OURNALING) built-in to turn journaling off or on for a given  
buffer during a session.  
In the buffer s journal file, DECTPU keeps track of the following record attributes  
(and any changes made to them):  
Left margin setting  
Modifiability or unmodifiability  
Display value  
The journal file 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 file 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 file name to 39 characters  
3. Adds the file type .TPU$J OURNAL  
For example, a buffer named TEST.BAR has a default journal file name of TEST_  
BAR.TPU$J OURNAL.  
DECTPU puts all journal files in the directory defined by the logical name  
TPU$J OURNAL. By default, this logical is defined as SYS$SCRATCH. You can  
reassign this logical name. For example, if you want journal files written to the  
current default directory, define TPU$J OURNAL as [ ].  
2.5 Avoiding Errors Related to Virtual Address Space  
DECTPU manipulates data in a processs virtual memory space. If the space  
required by the DECTPU images, data structures, and files in memory exceeds  
the virtual address space, DECTPU tries to write part of the data to the work  
file, thus freeing up space for other parts of the data that it needs immediately.  
If the work file 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 file on a disk that contains more free space. Use one of the following  
methods to do this:  
Redefine TPU$WORK to point to the disk with more free space.  
Invoke DECTPU with the /WORK=filename qualifier.  
DECTPU may be unable to signal an error when it frees up memory by writing to  
the work file. In this case, DECTPU aborts with a fatal internal error.  
You may be able to avoid writing to the work file by increasing the virtual  
address space available to a process. The virtual address space is controlled by  
the following two factors:  
The SYSGEN parameter VIRTUALPAGECNT  
The page file 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 file quota controls the number of pages in the system paging file that  
can be allocated to your process. For more information on the page file quota, see  
the description of the /PGFLQUOTA qualifier in the OpenVMS documentation on  
the Authorize Utility (AUTHORIZE).  
You may need to modify both the VIRTUALPAGECNT parameter and the page  
file 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 file, the size of the string memory pool  
is fixed. DECTPU cannot write strings to the work file, 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 Qualifiers  
The DCL command EDIT/TPU has qualifiers for setting attributes of DECTPU  
or an application layered on DECTPU. The qualifiers fall into the following two  
categories:  
Qualifiers handled by DECTPU  
Qualifiers in this category have their defaults set by DECTPU.  
Qualifiers handled by the application layered on DECTPU  
Some qualifiers 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 qualifiers in alphabetical order, giving a  
detailed description of each. The examples in the following sections show the  
qualifiers directly after the EDIT/TPU command and before the input file  
specification. You can place the qualifiers 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 qualifier that can be processed by a layered  
application. Applications not based on EVE may handle qualifiers differently.  
2.6.1 /CHARACTER_SET  
/CHARACTER_SET=DEC_MCS (default)  
The /CHARACTER_SET qualifier 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 Qualifiers  
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:  
Define 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  
definition in your LOGIN.COM file. For example, the following commands  
define 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 definition of the TPU$CHARACTER_SET logical name.  
By default, DECTPU uses the DEC_MCS character set. For example, the  
following command specifies 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.  
$
EDIT/TPU/CHARACTER_SET=general  
If the character set you specify either with /CHARACTER_SET or by defining  
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 qualifier  
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  
Graphics character set containing supplemental and  
multinational characters, such as letters with accents and  
umlauts.  
ISO_LATIN1  
GENERAL  
This character set contains supplemental and multinational  
characters that contain LATIN1 characters, such as the non-  
breaking space, multiplication and division signs, and the  
trademark sign.  
DECTPU does not specify a character set for 8-bit characters.  
8-bit characters are displayed the same as they were before  
you started DECTPU.  
2.6.2 /COMMAND  
/COMMAND[[=filespec]]  
/NOCOMMAND  
/COMMAND=TPU$COMMAND.TPU (default)  
The /COMMAND qualifier determines whether DECTPU compiles and executes  
a command file (a file of DECTPU procedures and statements) at startup time.  
Command files extend or modify a DECTPU-based application or create a new  
application. The default file type for DECTPU command files is .TPU. You cannot  
use wildcards in the file specification.  
2–10 Getting Started with DECTPU  
 
Getting Started with DECTPU  
2.6 Using OpenVMS EDIT/TPU Command Qualifiers  
By default, DECTPU tries to read a command file called TPU$COMMAND.TPU  
in your default directory. You can use a full file specification after the  
/COMMAND qualifier or define the logical name TPU$COMMAND to point  
to a command file other than the default.  
To determine whether you specified /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 specified, 0 otherwise. To fetch  
the name of the command file specified 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 file named  
SYS$LOGIN:MY_TPU$COMMAND.TPU and uses LETTER.RNO as the input  
file for an editing session:  
$ EDIT/TPU/COMMAND=sys$login:my_tpu$command.tpu letter.rno  
To prevent DECTPU from processing a command file, use the /NOCOMMAND  
qualifier. If you usually invoke DECTPU without a command file, define a symbol  
similar to the following:  
$ EVE == "EDIT/TPU/NOCOMMAND"  
Using /NOCOMMAND when you do not want to use a command file decreases  
startup time by eliminating the search for a command file.  
If you specify a command file 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 files, see Chapter 5.  
2.6.3 /CREATE  
/CREATE (default)  
/NOCREATE  
The /CREATE qualifier controls whether a DECTPU-based application creates a  
new file when the specified input file 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 file to be created.  
The application layered on DECTPU is responsible for handling this qualifier.  
To determine if you specified /CREATE on the DCL command line, include the  
following call in the application:  
x := GET_INFO (COMMAND_LINE, "create");  
The preceding call returns 1 if /CREATE was specified, 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 Qualifiers  
By default, EVE creates a new file if the specified input file does not exist. If you  
use /NOCREATE and specify an input file 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 file,  
NEWFILE.DAT, your command and EVEs 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_filename]]  
/NODEBUG (default)  
The /DEBUG qualifier determines whether DECTPU loads, compiles, and  
executes a file implementing a DECTPU debugger. If /DEBUG is specified,  
DECTPU reads, compiles, and executes the contents of a debugger file before  
executing the procedure TPU$INIT_PROCEDURE and before executing the  
command file.  
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 file specification, DECTPU loads the file  
SYS$SHARE:TPU$DEBUG.TPU.  
For more information on how to use the default DECTPU debugger, see  
Chapter 5.  
To use a debugger file other than the default, use the /DEBUG qualifier and  
specify the device, directory, and file name of the debugger to be used. If you  
specify only the file name, DECTPU searches SYS$SHARE for the file. You can  
define the logical name TPU$DEBUG to specify a file that contains a debugger  
program. Once you define this logical name, using /DEBUG without specifying a  
file calls the file specified by TPU$DEBUG.  
2.6.5 /DISPLAY  
/NODISPLAY  
To choose the DECwindows or the non-DECwindows version of DECTPU, use the  
/DISPLAY qualifier on the DCL command line when you invoke DECTPU.  
The /DISPLAY qualifier 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.  
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  
 
Getting Started with DECTPU  
2.6 Using OpenVMS EDIT/TPU Command Qualifiers  
The /NODISPLAY qualifier 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 file MY_BATCH_FILE.RNO  
without using terminal functions such as screen display:  
$ EDIT/TPU/NODISPLAY my_batch_file.rno  
2.6.6 /INITIALIZATION  
/INITIALIZATION[[=filespec]] (default)  
/NOINITIALIZATION  
The /INITIALIZATION qualifier determines whether the DECTPU-based  
application being run executes a file of initialization commands. The application  
layered on DECTPU is responsible for processing this qualifier.  
To determine whether you specified /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 specified, 0 otherwise. To  
fetch the name of the initialization file specified 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 specifies /INITIALIZATION but does not supply a default file  
specification. The default file specification for /INITIALIZATION is set by the  
application. Compaq recommends that a user-written application define the  
default file specification of an initialization file by using the following format:  
facility$init.facility  
For example, the default initialization file for the EVE editor is EVE$INIT.EVE.  
In EVE, if you do not specify a device or directory, EVE first checks the current  
directory. If the specified (or default) initialization file is not there, EVE checks  
SYS$LOGIN. If EVE finds the specified (or default) initialization file, EVE  
executes the commands in the file.  
For more information on using initialization files 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 Qualifiers  
2.6.7 /INTERFACE  
The /INTERFACE qualifier 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  
/J OURNAL[[=input_file.TJ L]] (default for EVE)  
/NOJ OURNAL (default for DECTPU)  
The /J OURNAL qualifier determines whether DECTPU keeps a journal file 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 file, 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 file, keeps track of changes made to  
buffers for each buffer created during the session.  
The application layered on DECTPU is responsible for processing this qualifier.  
To determine whether you specified /J OURNAL on the DCL command line, use  
the following call in the application:  
x := GET_INFO (COMMAND_LINE, "journal");  
The preceding call returns 1 if /J OURNAL was specified, 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 file specified 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 /J OURNAL or specify /J OURNAL  
but not a journal file, buffer-change journaling is turned on. The buffer-change  
journal files default file type is .TPU$J OURNAL.  
If you specify /J OURNAL=filename, then EVE also turns on keystroke journaling.  
The keystroke journal files default file type is .TJ L.  
To prevent EVE from creating either a keystroke or buffer-change journal file for  
an editing session, use the /NOJ OURNAL qualifier. For example, the following  
command causes EVE to turn off buffer-change journaling when you edit the  
input file MEMO.TXT:  
2–14 Getting Started with DECTPU  
 
Getting Started with DECTPU  
2.6 Using OpenVMS EDIT/TPU Command Qualifiers  
$ EDIT/TPU/NOJOURNAL memo.txt  
If you are developing an application layered on DECTPU, you can use the built-in  
J OURNAL_OPEN to direct DECTPU to create a keystroke journal file for an  
editing session. Using J OURNAL_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 file when the buffer is full.  
You can use the built-in procedure SET (J OURNALING) to turn on buffer-change  
journaling, even if you have used /NOJ OURNAL to turn it off initially. You can  
also use SET (J OURNALING) to adjust the journaling frequency.  
For more information on J OURNAL_OPEN and SET (J OURNALING), see  
the DEC Text Processing Utility Reference Manual. For more information on  
buffer-change journaling, see Section 2.4.  
Once a keystroke journal file is created, use the /RECOVER qualifier to direct  
DECTPU to process the commands in the keystroke journal file. For example, the  
following command causes DECTPU to recover a previous editing session on an  
input file named MEMO.TXT. Because the journal file has a name different from  
the input file name, both /J OURNAL and /RECOVER are used. The name of the  
keystroke journal file is MEMO.TJ L:  
$ EDIT/TPU/RECOVER/JOURNAL=memo.tjl memo.txt  
In buffer-change journaling, to recover the changes made to a specified 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.  
Note  
Compaq strongly recommends the use of buffer-change journaling rather  
than keystroke journaling.  
2.6.9 /MODIFY  
/MODIFY (default)  
/NOMODIFY  
The /MODIFY qualifier determines whether the first user buffer in an editing  
session is modifiable. The application layered on DECTPU is responsible for  
processing /MODIFY.  
To determine what form of the /MODIFY qualifier was used on the DCL command  
line, use the following calls:  
x := GET_INFO (COMMAND_LINE, "modify");  
x := GET_INFO (COMMAND_LINE, "nomodify");  
The first statement returns 1 if /MODIFY was explicitly specified on the command  
line, 0 otherwise. The second statement returns 1 if /NOMODIFY was explicitly  
specified 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 Qualifiers  
If you invoke EVE and do not specify /MODIFY, /NOMODIFY, /READ_ONLY, or  
/NOWRITE, EVE makes the first user buffer of the editing session modifiable.  
If you specify /NOMODIFY, EVE makes the first user buffer unmodifiable.  
Regardless of what qualifiers you use on the DCL command line, EVE makes all  
user buffers after the first buffer modifiable.  
If you do not specify either form of the /MODIFY qualifier, EVE checks whether  
you have used any form of the /READ_ONLY or /WRITE qualifier. By default,  
a read-only buffer is unmodifiable and a write buffer is modifiable. However, if  
you specify /READ_ONLY and /MODIFY or /NOWRITE and /MODIFY, the buffer  
is modifiable. Similarly, if you specify /WRITE and /NOMODIFY or /NOREAD_  
ONLY and /NOMODIFY, the buffer is unmodifiable.  
2.6.10 /OUTPUT  
/OUTPUT[[=input_file.type]] (default)  
/NOOUTPUT  
The /OUTPUT qualifier determines whether the output of your DECTPU session  
is written to a file. The application layered on DECTPU is responsible for  
processing this qualifier.  
To determine whether you specified /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 specified, 0 otherwise. To fetch the  
name of the output file specified 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  
specifies /OUTPUT but does not supply a default file specification.  
In EVE, when you use /OUTPUT, you can name the file created from the main  
buffer when you exit from DECTPU. For example, the following command causes  
DECTPU to read in a file called LETTER.RNO and to write the contents of the  
main buffer to the file NEWLET.RNO upon exiting from DECTPU:  
$ EDIT/TPU/OUTPUT=newlet.rno letter.rno  
If you use /OUTPUT= to specify an output file, EVE modifies 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 file you specify.  
By default, the output file has the same name as the input file, and the version  
number is one higher than the highest existing version of the input file. You  
can specify a different name for the output file by using the file specification  
argument for the /OUTPUT qualifier.  
In EVE, specifying /NOOUTPUT causes EVE to suppress creation of an output  
file for the first buffer of the editing session. Using /NOOUTPUT does not  
suppress creation of a journal file.  
2–16 Getting Started with DECTPU  
 
Getting Started with DECTPU  
2.6 Using OpenVMS EDIT/TPU Command Qualifiers  
Using /NOOUTPUT, you can develop an application that lets you control the  
output of a file. 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 file for that  
buffer.  
2.6.11 /READ_ONLY  
/READ_ONLY  
/NOREAD_ONLY (default)  
The /READ_ONLY qualifier determines whether the application layered on  
DECTPU creates an output file from the contents of the main buffer if the  
contents are modified.  
The processing of the /READ_ONLY qualifier is interrelated with the processing  
of the /WRITE qualifier. /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 qualifiers on the DCL command line:  
/READ_ONLY and /WRITE  
/NOREAD_ONLY and /NO_WRITE  
The application layered on DECTPU is responsible for processing this qualifier.  
To determine whether either the /READ_ONLY or /NOWRITE qualifier 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 specified  
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 specified  
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 qualifier is equivalent to using the  
/NOJ OURNAL, /NOMODIFY, and /NOOUTPUT qualifiers. If you specify /READ_  
ONLY, DECTPU does not maintain a journal file 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 file 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 qualifier, EVE writes out the buffer specified  
on the command line (if the buffer has been modified) 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 Qualifiers  
2.6.12 /RECOVER  
/RECOVER  
/NORECOVER (default)  
The /RECOVER qualifier determines whether DECTPU reads a keystroke  
journal file 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 file  
NOTES.TXT:  
$ EDIT/TPU/RECOVER notes.txt  
To determine whether you specified /RECOVER on the DCL command line, use  
the following call:  
x := GET_INFO (COMMAND_LINE, "recover");  
The preceding call returns 1 if /RECOVER was specified, 0 otherwise.  
For more information on GET_INFO, see the DEC Text Processing Utility  
Reference Manual.  
DECTPU uses /RECOVER to recover a keystroke journal file only. In buffer-  
change journaling, to recover the changes made to a specified 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 J OURNAL_OPEN  
while running a layered application, by default DECTPU opens the journal file  
for output only. If you specify /RECOVER when invoking DECTPU with a layered  
application, then when the built-in procedure J OURNAL_OPEN is executed,  
the keystroke journal file is opened for input and output. DECTPU opens the  
input file 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 J OURNAL_CLOSE is executed.  
When you recover an editing session, every file 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 file has a different name from the input file, you must include both  
/J OURNAL and /RECOVER with the EDIT/TPU command. For example, if you  
want to use the keystroke journal file SAVE.TJ L to recover the edits you made to  
a file called LETTER.DAT, enter the following command on the DCL command  
line:  
2–18 Getting Started with DECTPU  
 
Getting Started with DECTPU  
2.6 Using OpenVMS EDIT/TPU Command Qualifiers  
$ EDIT/TPU/RECOVER/JOURNAL=save.TJL letter.dat  
In EVE, you can use /RECOVER to recover either an editing session from a  
keystroke journal file or a single buffer from a buffer-change journal file. If you  
specify /J OURNAL=filename, EVE recovers from the specified keystroke journal  
file. Otherwise, EVE recovers from a buffer-change journal file that corresponds  
to the input parameter (or the buffer specified on the command line if no input  
parameter is specified).  
For more information on journaling and recovery in EVE, see the Extensible  
Versatile Editor Reference Manual.  
2.6.13 /SECTION  
/SECTION[[=filespec]]  
/NOSECTION  
/SECTION=TPU$SECTION (default)  
The /SECTION qualifier determines whether DECTPU loads a section file. A  
section file is a startup file that contains key definitions and compiled procedures  
in binary form.  
The default section file is TPU$SECTION. When DECTPU tries to locate the  
section file, DECTPU supplies a default directory of SYS$SHARE and a default  
file type of .TPU$SECTION. OpenVMS systems define the systemwide logical  
name TPU$SECTION as EVE$SECTION, so the default section file is the file  
that implements the EVE editor. To override the OpenVMS default, redefine  
TPU$SECTION.  
You can specify a different section file. The preferred method is to define the  
logical name TPU$SECTION to point to a section file other than the default  
file. You can also supply a full file specification for the /SECTION qualifier.  
For example, if your device is called DISK$USER and your directory is called  
[SMITH], the following command causes DECTPU to read a section file called  
VT100INI.TPU$SECTION:  
$ EDIT/TPU/SECTION=disk$user:[smith]vt100ini  
If you omit the device and directory in the file specification, DECTPU assumes  
the file is in SYS$SHARE. The section file must be located on the same node on  
which you are running DECTPU.  
To determine whether /SECTION was specified 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 specified, 0 otherwise. To fetch the  
name of the section file specified 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 file used as the value for the /SECTION qualifier. To do so,  
run the source code version of the file through DECTPU and then use the built-in  
procedure SAVE. This process converts the file to the proper binary form.  
For more information on creating and using section files, see Chapter 5.  
Getting Started with DECTPU 2–19  
 
Getting Started with DECTPU  
2.6 Using OpenVMS EDIT/TPU Command Qualifiers  
If you specify the /NOSECTION qualifier, DECTPU does not load a section file.  
Unless you use the /COMMAND qualifier with /NOSECTION, DECTPU has no  
user interface and no keys are defined. 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 qualifier determines where the application layered on  
DECTPU positions the cursor.  
2–20 Getting Started with DECTPU  
 
3
DEC Text Processing Utility Data Types  
A d a ta typ e 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 specific 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  
3.1 Array Data Type  
An a r r a y 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  
specified 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 specifies 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 unspecified. 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 specified 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 first statement creates an integer-indexed array,  
int_array. The array has 10 elements; the first element starts at index 1. The  
second statement stores a string in the first 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 unspecified. 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 unspecified.  
You can delete an element in the array by assigning the data type unspecified 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 find 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;  
Note  
DECTPU does not guarantee the order in which it will return the array  
indexes.  
3.2 Buffer Data Type  
A bu ffer 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");  
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 identifier 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 file with the buffer, making it easier for you to remember  
which buffer contains the contents of a given file.  
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 DECTPUs 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 DECTPUs 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 fills the line to 32767 characters.  
If you try to read a file 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 file. 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  
 
DEC Text Processing Utility Data Types  
3.3 Integer Data Type  
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  
Keyw or d s 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 first  
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, "status_video") has the following  
keywords as possible return values:  
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 define 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  
VT400, VT300, VT200  
DECTPU Key Name  
Series Key  
VT100 Key  
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  
Down arrow  
Left arrow  
Right arrow  
Find / E1  
Insert Here / E2  
Remove / E3  
Select / E4  
Prev Screen / E5  
Next Screen / E6  
Help / F15  
Do / F16  
F6, F7, . . . , F20  
Ctrl/space  
Tab  
Up arrow  
Down arrow  
Left arrow  
Right arrow  
Down  
Left  
Right  
E1  
E2  
E3  
E4  
E5  
E6  
Help  
Do  
F6, F7, . . . , F20  
NULL_KEY  
TAB_KEY  
RET_KEY  
DEL_KEY  
LF_KEY  
BS_KEY  
Ctrl_A_KEY  
Ctrl_B_KEY  
.
Ctrl/space  
Tab  
Return  
Return  
Delete  
Line feed  
Backspace  
Ctrl/A1  
Ctrl/B  
.
x
<
Ctrl/J  
Ctrl/H  
Ctrl/A1  
Ctrl/B  
.
.
.
.
.
.
.
1Ctrl/A means pressing the Ctrl key simultaneously with the A key. A and a produce the same results.  
(continued on next page)  
3–6 DEC Text Processing Utility Data Types  
 
DEC Text Processing Utility Data Types  
3.4 Keyword Data Type  
Table 3–1 (Cont.) Keywords Used for Key Names  
VT400, VT300, VT200  
Series Key  
DECTPU Key Name  
VT100 Key  
Ctrl_Z_KEY  
Ctrl/Z  
Ctrl/Z  
The OpenVMS terminal driver handles the following keys as special cases.  
Compaq recommends that you avoid defining the following control characters and  
function key:  
Ctrl/C  
Ctrl/O  
Ctrl/Q  
Ctrl/S  
Ctrl/T  
Ctrl/X  
Ctrl/Y  
F6  
3.5 Learn Data Type  
A lea r n sequ en ce 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 specifies  
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 finishing 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.  
Note  
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 EVEs word wrap), the routine may not be executed during the  
replay of the sequence.  
3.6 Marker Data Type  
A m a r k er 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  
specifies 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 windows  
cursor position.  
A marker can be either fr ee or bou n d . 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 fills 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 fill 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  
! detached editing point  
POSITION (SEARCH_QUIETLY ("",FORWARD)); ! Moves the active editing  
! point to the nearest  
! text character  
bat := CURRENT_LINE;  
! Assigns the string  
! representation of the  
! current line to bat without  
! adding padding blanks  
POSITION (x);  
! Returns the active editing  
! point to the free marker  
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_unspecified 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.  
3.7 Pattern Data Type  
A p a tter n 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 first  
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 "abc" or the string "def":  
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";  
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 specified by the pattern  
that you use as a parameter. If SEARCH or SEARCH_QUIETLY finds 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 finds 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 first 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  
 
DEC Text Processing Utility Data Types  
3.7 Pattern Data Type  
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 DECTPUs 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 specifies 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.  
pat1 := "abc" + line_end;  
If SEARCH or SEARCH_QUIETLY finds 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 specifically 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 define 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 defined two subpattern variables as follows:  
p1 := "a" & ANY("012345678");  
p2 := "c" & ARB (1);  
You then define 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 definitions, a search for pat_var succeeds if DECTPU  
encounters the following string:  
a5xcd  
Because two pattern variables are linked, DECTPU searches first 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 first  
element of that subpattern to anchor the right-hand subpattern.  
For example, suppose you defined 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 defining 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 definitions:  
pat1 := "abc" | "bcd";  
pat2 := "bcd" | "abc";  
pat3 := "bc" | "bcd";  
pat4 := "bcd" | "bc";  
Given these definitions 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 file 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 file 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)  
+ ("e" | ("x" @ 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 defined the variable this_pat as follows:  
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 definition, 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  
find 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.  
Note  
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  
 
DEC Text Processing Utility Data Types  
3.7 Pattern Data Type  
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 first 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 first 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:  
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 first xyz it finds, the text between  
the two sets of characters by definition 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 defined 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 first 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  
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 flag 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 first parameter specifies that the output from the process is to be stored in  
MAIN_BUFFER. The string "MAIL" is the first 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 p r ogr a m 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  
 
DEC Text Processing Utility Data Types  
3.10 Range Data Type  
3.10 Range Data Type  
A r a n ge 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.  
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 specifies 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 define 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 ( " ) or the apostrophe ( ) as the  
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 := ’’’’;  
x := """";  
! The value assigned to x is ’.  
! 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 := "’";  
x := ’"’;  
! The value assigned to x is ’.  
! 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:  
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 fills 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 "K" in the  
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:  
COPY_TEXT (10 * "_")  
To reduce a string, specify the string to be modified, 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  
the current buffer at the editing point.  
COPY_TEXT ("woolly""wool")  
Inserts the string "ly" into the current  
buffer at the editing point.  
3.12 Unspecified Data Type  
An unspecified 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  
unspecified 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:  
prog := COMPILE ("x := 1");  
EXECUTE (prog);  
DEC Text Processing Utility Data Types 3–21  
 
DEC Text Processing Utility Data Types  
3.12 Unspecified Data Type  
To give a variable the data type unspecified, assign the predefined 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 w id get 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 ga d get 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 w in d ow is a portion of the screen that displays as much of the text in a  
buffer as will fit 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 first parameter specifies that the window starts at screen line number 1.  
The second parameter specifies that the window is 12 lines in length. The OFF  
keyword specifies 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  
 
DEC Text Processing Utility Data Types  
3.14 Window Data Type  
3.14.1 Defining Window Dimensions  
Windows are defined 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 file 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.  
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 file 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 defines the size and location of  
a window and specifies whether a status line is to be displayed. CREATE_  
WINDOW also adds the window to DECTPUs 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_lengthNumber of lines in the window (including the status line).  
Later calls to ADJ UST_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 windows visible_top, visible_bottom,  
and visible_length are modified. 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 ADJ UST_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  
 
DEC Text Processing Utility Data Types  
3.14 Window Data Type  
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 DECTPUs 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 DECTPUs 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 modified 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.  
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 finished  
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  
reflect the current state of the part of the buffer that is visible in the window.  
If you want to make the screen reflect 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 qualifier  
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 qualifier, 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 qualifier.  
3–26 DEC Text Processing Utility Data Types  
 
4
Lexical Elements of the DEC Text Processing  
Utility Language  
4.1 Overview  
A DECTPU program is composed of lexical elements. A lexica l elem en t may be  
an individual character, such as an arithmetic operator, or it may be a group of  
characters, such as an identifier. 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  
Identifiers  
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  
4.3 Character Sets  
When you invoke DECTPU, you can use one of the following keywords with the  
/CHARACTER_SET qualifier 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 first 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  
32  
Nonprinting characters such as tab, line feed, carriage return, and bell  
Space  
33–64  
Special characters such as the ampersand ( & ), question mark ( ? ), equal  
sign ( = ), and the numbers 0 through 9  
65–122  
123–126  
127  
The uppercase and lowercase letters A through Z and a through z  
Special characters such as the left brace ( { ) and the tilde ( ~ )  
Delete  
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  
160  
Extended control characters  
Reserved  
161–191  
Supplemental special graphics characters such as the copyright sign ( © )  
and the degree sign ( ° )  
192–254  
255  
The supplemental multinational uppercase and lowercase letters such as the  
Spanish Ñ and ñ  
Reserved  
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 Character Sets  
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  
160-191  
Extended control characters  
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 qualifier 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 specific to any character set.  
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  
EVEs 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  
At sign  
Assigns a value to a variable  
Partial pattern assignment operator  
Opens an array element index expression  
Left brace  
Close parenthesis  
)
Ends parameter list, expression, procedure call,  
argument list, or array element index  
Comma  
,
Separates parameters  
Begins comment  
Exclamation point  
Dollar sign  
!
$
Indicates a variable, constant, keyword, or  
procedure name that is reserved to Compaq  
Right brace  
}
Closes array element index expression  
Relational operator  
Equal sign  
=
>
Greater than sign  
Relational operator  
Greater than or equal to >=  
sign  
Relational operator  
Slash  
/
Integer division operator  
Integer multiplication operator  
Begins case label  
Asterisk  
*
Left bracket  
Less than sign  
[
<
<=  
Relational operator  
Less than or equal to  
sign  
Relational operator  
Minus sign  
Subtraction operator  
Not equal sign  
Vertical bar  
<>  
Relational operator  
|
Pattern alternation operator  
Open parenthesis  
(
Begins parameter list, expression, argument list, or  
array element index  
Ampersand  
Plus sign  
&
+
Pattern linkage operator  
String concatenation operator, pattern  
concatenation operator, integer addition operator  
Quotation mark  
Right bracket  
Semicolon  
"
]
Delimits string  
Ends case label  
;
Separates language statements  
Separates words in identifiers  
Underscore  
_
4–4 Lexical Elements of the DEC Text Processing Utility Language  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.4 Identifiers  
4.4 Identifiers  
In DECTPU, identifiers are used to name programs, procedures, keywords, and  
variables. An id en tifier is a combination of alphabetic characters, digits, dollar  
signs, and underscores, and it must conform to the following restrictions:  
An identifier cannot contain any spaces or symbols except the dollar sign and  
the underscore.  
Identifiers cannot be more than 132 characters long.  
DECTPU identifiers for built-in procedures, constants, keywords, and global  
variables are reserved words.  
You can create your own identifiers 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 undefined procedure.  
4.5 Variables  
Va r ia bles are names given to DECTPU storage locations that hold values.  
A variable name can be any valid DECTPU identifier 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 identifier as the left-hand side of an assignment  
statement. Following is an example of a variable assignment:  
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 file 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);  
user_tab_char := ASCII (9);  
COPY_TEXT (user_tab_char);  
SET (this_mode, CURRENT_BUFFER);  
! Set mode to insert  
! Define the tab char  
! Insert tab  
! 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-defined constants can be locally or globally defined.  
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 defined.  
A global constant is a constant declared outside a procedure. Once a global  
constant has been defined, 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  
redefine 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.  
(continued on next page)  
4–6 Lexical Elements of the DEC Text Processing Utility Language  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.6 Constants  
Example 4–2 (Cont.) Global and Local Constant Declarations  
PROCEDURE user_hello_world  
CONSTANT  
world := "world";  
MESSAGE (user_hello + " " + world);  
! Display "Hello world"  
! in message area  
ENDPROCEDURE;  
4.7 Operators  
DECTPU uses symbols and characters as language operators. There are five  
types of operators:  
Arithmetic  
String  
Relational  
Pattern  
Logical  
Table 4–5 lists the symbols and language elements that DECTPU uses as  
operators.  
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  
NOT  
OR  
Boolean AND  
Boolean NOT  
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 –  
NOT  
Highest  
*, /, AND  
@, &, +, –, | , OR, XOR  
=, <>, <, <=, >, >=  
:=  
Lowest  
Expressions enclosed in parentheses are evaluated first. 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  
8 * 5 / (2 - 4)  
16  
-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 identifier 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 = "this is my  
string") each evaluate to an integer type (odd integers are true; even integers are  
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  
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 first 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  
-39 / 10  
3
-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;  
saved_mark := MARK (FREE_CURSOR);  
POSITION (BEGINNING_OF (CURRENT_BUFFER));  
number_lines := GET_INFO (current_buffer, "record_count");  
IF number_lines = 0  
THEN  
MESSAGE ("The current buffer is empty");  
ELSE  
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;  
ENDIF;  
ENDIF;  
ENDPROCEDURE;  
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 defined 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  
Predefined 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 redefine 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 definition, text manipulation, and program execution.  
You can redefine 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 Predefined Constants  
The following is a list of predefined global constants that DECTPU sets up. You  
cannot redefine 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  
4.9 Reserved Words  
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:  
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  
define. Any attempt to redefine 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  
identification 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 [[declarations]] [[ON_ERROR ...  
ENDON_ERROR]] statement_1; . . . statement_n; ENDMODULE  
The declarations part of a module can include any number of global VARIABLE,  
CONSTANT, and PROCEDURE declarations.  
The ON_ERROR/ENDON_ERROR block, if used, must appear after the  
declarations and before the DECTPU statements that make up the body of  
the module. Statements that make up the body of a module must be separated  
with semicolons. For more information on error handlers, see Section 4.9.4.14.  
In the following example, the compiler creates two procedures: user_mod_  
module_ident and user_mod_module_init. User_mod_module_ident returns the  
string "v1.0". User_mod_module_init calls the routine user_hello.  
MODULE user_mod IDENT "v1.0"  
PROCEDURE user_hello  
MESSAGE ("Hello");  
ENDPROCEDURE;  
ON_ERROR  
MESSAGE ("Good-bye");  
END_ON_ERROR;  
user_hello;  
ENDMODULE  
4–14 Lexical Elements of the DEC Text Processing Utility Language  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.9 Reserved Words  
4.9.4.2 Procedure Declaration  
The PROCEDURE/ENDPROCEDURE declaration delimits a series of DECTPU  
statements so they can be called as a unit. With the PROCEDURE/  
ENDPROCEDURE combination, you can declare a procedure with a name so  
that you can call it from another procedure or from the command line of a  
DECTPU editing interface. Once you have compiled a procedure, you can enter  
the procedure name as a statement in another procedure, or enter the procedure  
name after the TPU Statement: prompt on the command line of EVE.  
Syntax  
PROCEDURE procedure-name [[ (parameter-list) ]] [[local-declarations]]  
[[ON_ERROR ... ENDON_ERROR]] statement_1; statement_2; . . . statement_n;  
ENDPROCEDURE;  
The local declarations part of a procedure can include any number of LOCAL and  
CONSTANT declarations.  
The ON_ERROR/ENDON_ERROR block, if used, must appear after the  
declarations and before the DECTPU statements that make up the body of  
the procedure. For more information on error handlers, see Section 4.9.4.14.  
After the ON_ERROR/ENDON_ERROR block, you can use any kind of  
DECTPU language statements in the body of a procedure except another  
ON_ERROR/ENDON_ERROR block. Statements that make up the body of a  
procedure must be separated with semicolons. For example:  
PROCEDURE version  
MESSAGE ("This is Version 1-020");  
ENDPROCEDURE;  
This procedure writes the text "This is Version 1–020" in the message area.  
4.9.4.3 Procedure Names  
A procedure name can be any valid identifier that is not a DECTPU reserved  
word. Compaq suggests that you use a convention when naming your procedures.  
For instance, you might prefix procedure names with your initials. In this way,  
you can easily distinguish procedures that you write from other procedures  
such as the DECTPU built-in procedures. For example, if J ohn Smith writes  
a procedure that creates two windows, he might name his procedure js_two_  
windows. This helps ensure that his procedure name is a unique name. Most  
of the sample procedures in this manual have the prefix user_ with procedure  
names.  
4.9.4.4 Procedure Parameters  
Using parameters with procedures is optional. If you use parameters, they can be  
input parameters, output parameters, or both. For example:  
PROCEDURE user_input_output (a, b)  
a := a + 5;  
b := a;  
ENDPROCEDURE;  
In the preceding procedure, a is an input parameter. It is also an output  
parameter because it is modified by the procedure input_output. In the same  
procedure, b is an output parameter.  
Lexical Elements of the DEC Text Processing Utility Language 4–15  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.9 Reserved Words  
The scope of procedure parameters is limited to the procedure in which they  
are defined. The maximum number of parameters in a parameter list is 127.  
A procedure can declare its parameters as required or optional. Required  
parameters and optional parameters are separated by a semicolon. Parameters  
before the semicolon are required parameters; those after the semicolon are  
optional. If no semicolon is specified, then the parameters are required.  
Syntax  
PROCEDURE proc-name [[ ( [[req-param [[...]] ]] [[;opt-param [[...]] ]] ) ]] . . .  
ENDPROCEDURE;  
A procedure parameter is a place holder or dummy identifier that is replaced by  
an actual value in the program that calls the procedure. The value that replaces  
a parameter is called an a r gu m en t. Arguments can be expressions. There does  
not have to be any correlation between the names used for parameters and the  
values used for arguments. All arguments are passed by reference. Example 4–4  
shows a simple procedure with parameters.  
Example 4–4 Simple Procedure with Parameters  
!This procedure adds two integers. The parameters, int1 and int2,  
!are replaced by the actual values that you supply.  
!The result of the addition is written to the message area.  
PROCEDURE ADD (int1, int2)  
MESSAGE (STR (int1 + int2));  
ENDPROCEDURE;  
For example, call the procedure ADD and specify the values 5 and 6 as  
arguments, as follows:  
ADD (5, 6);  
The string "11" is written to the message buffer.  
Any caller of a procedure must use all required parameters to call it. The caller  
can also use optional parameters. If the required parameters are not present  
or the procedure is called with too many parameters (more than the sum of the  
required and optional parameters), then DECTPU issues an error.  
If a procedure is called with the required number of parameters, but with less  
than the maximum number of parameters, then the remaining parameters up to  
the maximum automatically become null parameters.’ A n u ll p a r a m eter is a  
modifiable parameter of data type unspecified. A null parameter can be assigned  
a value and will become the value it is assigned, but the parameter s value is  
discarded when the procedure exits.  
Null parameters can also be explicitly passed to a procedure. You can do this by  
omitting a parameter when calling the procedure.  
Example 4–5 shows a more complex procedure that uses optional parameters.  
4–16 Lexical Elements of the DEC Text Processing Utility Language  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.9 Reserved Words  
Example 4–5 Complex Procedure with Optional Parameters  
CONSTANT  
user_warning  
user_success  
user_error  
:= 0,  
:= 1,  
:= 2,  
! Warning severity code  
! Success severity code  
! Error severity code  
user_informational := 3,  
user_fatal := 4;  
! Informational severity code  
! Fatal severity code  
!
! Output a message with fatal/error/warning flash.  
!
PROCEDURE user_message (the_text; the_severity)  
LOCAL flash_it;  
!
! Only flash warning, error, or fatal messages.  
!
CASE the_severity FROM user_warning TO user_fatal  
[user_warning, user_error, user_fatal] : flash_it := TRUE;  
[user_success, user_informational] : flash_it := FALSE;  
[OUTRANGE] : flash_it := FALSE;  
ENDCASE;  
!
! Output the message - flash it, if appropriate.  
!
MESSAGE (the_text);  
IF flash_it  
THEN  
SLEEP ("0 00:00:00.3");  
MESSAGE ("");  
SLEEP ("0 00:00:00.3");  
MESSAGE (the_text);  
ENDIF;  
ENDPROCEDURE;  
Caution  
Do not assume that the DECTPU compiler automatically evaluates  
parameters in the order in which you place them.  
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  
parameters in a particular order, you should force the compiler to evaluate each  
parameter in order before calling the procedure. To do so, use each parameter in  
an assignment statement before calling the procedure. For example, suppose you  
want to call a procedure whose parameter list includes PARAM_1 and PARAM_2.  
Suppose, too, that PARAM_1 must be evaluated first. To get this result, you could  
use the following code:  
partial_1 := param_1;  
partial_2 := param_2;  
my_procedure (partial_1, partial_2);  
Lexical Elements of the DEC Text Processing Utility Language 4–17  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.9 Reserved Words  
4.9.4.5 Procedures That Return a Result  
Procedures that return a result are called fu n ction p r oced u r es. Example 4–6  
shows a procedure that returns a true ( 1 ) or false ( 0 ) value.  
Note  
All DECTPU procedures return a result. If they do not do so explicitly,  
DECTPU returns 0.  
Example 4–6 Procedure That Returns a Result  
PROCEDURE user_on_end_of_line !test if at eol, return true or false  
IF CURRENT_OFFSET = LENGTH (CURRENT_LINE)  
! we are on eol  
! return true  
! return false  
THEN  
user_on_end_of_line := 1  
ELSE  
user_on_end_of_line := 0  
ENDIF;  
ENDPROCEDURE;  
Another way of assigning a value of 1 or 0 to a procedure is to use the DECTPU  
RETURN language statement followed by a value. See Example 4–13.  
You can use a procedure that returns a result as a part of a conditional statement  
to test for certain conditions. Example 4–7 shows the procedure in Example 4–6  
within another procedure.  
Example 4–7 Procedure Within Another Procedure  
PROCEDURE user_nested_procedure  
.
.
.
IF user_on_end_of_line = 1  
THEN  
! at the eol mark  
MESSAGE ("Cursor is at the end of the line")  
MESSAGE ("Cursor is not at the end of the line")  
ELSE  
ENDIF;  
.
.
.
ENDPROCEDURE;  
4.9.4.6 Recursive Procedures  
Procedures that call themselves are called r ecu r sive p r oced u r es. Example 4–8  
shows a procedure named user_reverse that displays a list of responses to the  
READ_LINE built-in procedure in reverse order. Note the call to the procedure  
user_reverse within the procedure body.  
4–18 Lexical Elements of the DEC Text Processing Utility Language  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.9 Reserved Words  
Example 4–8 Recursive Procedure  
PROCEDURE user_reverse  
LOCAL temp_string;  
temp_string := READ_LINE("input>");  
! Read a response  
IF temp_string <> " "  
! Quit if nothing entered  
! but the RETURN key.  
THEN  
user_reverse  
ELSE  
! Call user_reverse recursively  
! All done, go to display lines  
RETURN  
ENDIF;  
MESSAGE (temp_string);  
! Display lines typed in reverse order  
! in the message window  
ENDPROCEDURE;  
4.9.4.7 Local Variables  
The use of local variables in procedures is optional. If you use local variables,  
they hold the values that you assign them only in the procedure in which you  
declare them. The maximum number of local variables that you can use is 255.  
Local variables are initialized to 0.  
Syntax  
LOCAL variable-name [[,...]];  
If you declare a local variable in a procedure and, in the same procedure, use  
the EXECUTE built-in to assign a value to a variable with the same name as  
the local variable, the result of the EXECUTE built-in has no effect on the local  
variable. Consider the following code fragment:  
PROCEDURE test  
LOCAL X;  
EXECUTE ("X := 3");  
MOVE_VERTICAL (X);  
ENDPROCEDURE;  
In this fragment, when the compiler evaluates the string "X := 3", the compiler  
assumes X is a global variable. The compiler creates a global variable X (if none  
exists) and assigns the value 3 to the variable. When the MOVE_VERTICAL  
built-in procedure uses the local variable X, the local variable has the value 0 and  
the MOVE_VERTICAL built-in has no effect.  
Local variables may also be declared in unbound code. See Section 4.9.5.2.  
4.9.4.8 Constants  
The use of constants in procedures is optional. The scope of a constant declared  
within a procedure is limited to the procedure in which it is defined. See  
Section 4.9.5.3 for more information on the CONSTANT declaration.  
Syntax  
CONSTANT constant-name := compile-time-constant-expression [[,...]];  
4.9.4.9 ON_ERROR Statements  
The use of ON_ERROR statements in procedures is optional. If you use an ON_  
ERROR statement, you must place it at the top of the procedure just after any  
LOCAL and CONSTANT declarations. The ON_ERROR statement specifies the  
action or actions to be taken if an ERROR or WARNING status is returned. See  
Section 4.9.4.14 for more information on ON_ERROR statements.  
Lexical Elements of the DEC Text Processing Utility Language 4–19  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.9 Reserved Words  
4.9.4.10 Assignment Statement  
The assignment statement assigns a value to a variable. In so doing, it associates  
the variable with the appropriate data type.  
Syntax  
identier := expression;  
The assignment operator is a combination of two characters: a colon and an  
equal sign (:=). Do not confuse this operator with the equal sign (=), which is a  
relational operator that checks for equality.  
DECTPU does not do any type checking on the data type being stored. Any data  
type may be stored in any variable. For example:  
X := "abc";  
This assignment statement stores the string "abc" in variable X.  
4.9.4.11 Repetitive Statement  
The LOOP/ENDLOOP statements specify the repetitive execution of a statement  
or statements until the condition specified by EXITIF is met.  
Syntax  
LOOP statement_1; statement_2; . . . EXITIF expression; statement_n;  
ENDLOOP;  
The EXITIF statement is the mechanism for exiting from a loop. You can place  
the EXITIF statement anywhere inside a LOOP/ENDLOOP combination. You  
can also use the EXITIF statement as many times as you like. When the EXITIF  
statement is true, it causes a branch to the statement following the ENDLOOP  
statement.  
Syntax  
EXITIF expression;  
The expression is optional; without it, EXITIF always exits from the loop.  
Any DECTPU language statement except an ON_ERROR statement can appear  
inside a LOOP/ENDLOOP combination. For example:  
LOOP  
EXITIF CURRENT_OFFSET = 0;  
temp_string := CURRENT_CHARACTER;  
EXITIF (temp_string <> " ") AND  
(temp_string <> ASCII(9));  
MOVE_HORIZONTAL (-1);  
temp_length := temp_length + 1;  
ENDLOOP;  
This procedure uses the EXITIF statement twice. Each expression following an  
EXITIF statement defines a condition that causes an exit from the loop. The  
statements in the loop are repeated until one of the EXITIF conditions is met.  
4.9.4.12 Conditional Statement  
The IF/THEN statement causes the execution of a statement or group of  
statements, depending on the value of a Boolean expression. If the expression  
is true, the statement is executed; otherwise, program control passes to the  
statement following the IF/THEN statement.  
The optional ELSE clause provides an alternative group of statements for  
execution. The ELSE clause is executed if the test condition specified by IF/THEN  
is false.  
4–20 Lexical Elements of the DEC Text Processing Utility Language  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.9 Reserved Words  
The ENDIF statement specifies the end of a conditional statement.  
Syntax  
IF expression THEN statement_1; . . . statement_n [[ELSE alternate-statement_  
1;  
. . . alternate-statement_n;]] ENDIF;  
You can use any DECTPU language statements except ON_ERROR statements in  
a THEN or ELSE clause. For example:  
PROCEDURE set_direct  
MESSAGE ("Press PF3 or PF4 to indicate direction");  
temp_char := READ_KEY;  
IF temp_char = KP5  
THEN  
SET (REVERSE, CURRENT_BUFFER);  
ELSE  
IF temp_char = KP4  
THEN  
SET (FORWARD, CURRENT_BUFFER);  
ENDIF;  
ENDIF;  
ENDPROCEDURE;  
In this example, nested IF/THEN/ELSE statements test whether a buffer  
direction should be forward or reverse.  
Caution  
Do not assume that the DECTPU compiler automatically evaluates all  
parts of an IF statement.  
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  
all clauses of a conditional statement, you should force the compiler to evaluate  
each clause before using the conditional statement. To do so, use each clause in  
an assignment statement before using it in a conditional statement. For example,  
suppose you want the compiler to evaluate both CLAUSE_1 and CLAUSE_2 in a  
conditional statement. To get this result, you could use the following code:  
relation_1 := clause_1;  
relation_2 := clause_2;  
IF relation_1 AND relation_2  
THEN  
.
.
.
ENDIF;  
4.9.4.13 Case Statement  
The CASE statement is a selection control structure that lets you list several  
alternate actions and choose one of them to be executed at run time. In a CASE  
statement, case labels are associated with the possible executable statements or  
actions to be performed. The CASE statement then executes the statement or  
statements labeled with a value that matches the value of the case selector.  
Lexical Elements of the DEC Text Processing Utility Language 4–21  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.9 Reserved Words  
Syntax  
CASE case-selector [[FROM  
lower-constant-expr, TO upper-constant-expr]]  
[constant-expr_1 [[,...]]] : statement [[,...]];  
[constant-expr_2 [[,...]]] : statement [[,...]];  
.
.
.
[constant-expr_n [[,...]]] : statement [[,...]];  
[[[INRANGE] : statement [[,...]] ;]]  
[[[OUTRANGE] : statement [[,...]] ;]]  
ENDCASE;  
The single brackets are not optional for case constants. Example 4–9 shows how  
to use the CASE statement in a procedure.  
CASE constant expressions must evaluate at compile time to either a keyword,  
a string constant, or an integer constant. All constant expressions in the CASE  
statement must be of the same data type. There are two special case constants  
in DECTPU: INRANGE and OUTRANGE. INRANGE matches anything that  
falls within the case range that does not have a case label associated with it.  
OUTRANGE matches anything that falls outside the case range. These special  
case constants are optional.  
FROM and TO clauses of a CASE statement are not required. If FROM and  
TO clauses are not specified, INRANGE and OUTRANGE labels refer to data  
between the minimum and maximum specified labels.  
Example 4–9 shows a sample procedure that uses the CASE statement.  
Example 4–9 Procedure That Uses the CASE Statement  
PROCEDURE grades  
answers := READ_LINE ("Enter number of correct answers:",5);  
answers := INT (answers);  
CASE answers FROM 0 TO 10  
[10] : score := "A+";  
[9] : score := "A";  
[8] : score := "B";  
[7] : score := "C";  
[6] : score := "D";  
[0,1,2,3,4,5] : score := "F";  
[OUTRANGE] : score := "Invalid entry.";  
ENDCASE;  
MESSAGE (score);  
ENDPROCEDURE;  
This CASE statement compares the value of the constant selector answers to  
the case labels (the numbers 0 through 10). If the value of answers is any of  
the numbers from 0 through 10, the statement to the right of that number  
is executed. If the value of answers is outside the range of 0 through 10, the  
statement to the right of [OUTRANGE] is executed. The value of score is written  
in the message area after the execution of the CASE statement.  
4–22 Lexical Elements of the DEC Text Processing Utility Language  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.9 Reserved Words  
4.9.4.14 Error Handling  
A block of code starting with ON_ERROR and ending with ENDON_ERROR  
defines the actions that are to be taken when a procedure fails to execute  
successfully. Such a block of code is called an er r or h a n d ler . An error handler  
is an optional part of a DECTPU procedure or program. An error handler traps  
WARNING and ERROR status values. (See SET (INFORMATIONAL) and SET  
(SUCCESS) in the DEC Text Processing Utility Reference Manual for information  
on handling informational and success status values.)  
It is good programming practice to put an error handler in all but the simplest  
procedures. However, if you omit the error handler, DECTPUs default error  
handling behavior is as follows:  
If you press Ctrl/C, DECTPU places an error message in the message buffer,  
exits from all currently active procedures (in their reverse calling order), and  
returns to the wait for next key loop.  
If an error or warning is generated during a CALL_USER routine, ERROR is  
set to the keyword that represents the failure status of the routine, ERROR_  
LINE is set to the line number of the error, and ERROR_TEXT is set to the  
message associated with the error or warning. DECTPU places the message  
in the message buffer, then resumes execution at the statement after the  
statement that generated the error or warning.  
For other errors and warnings, ERROR is set to the keyword that represents  
the error or warning, ERROR_LINE is set to the line number of the error, and  
ERROR_TEXT is set to the message associated with the error or warning.  
DECTPU places the message in the message buffer, then resumes execution  
at the statement after the statement that generated the error or warning.  
In a procedure, the error handler must be placed at the beginning of a  
procedure—after the procedure parameter list, the LOCAL or CONSTANT  
declarations, if present, and before the body of the procedure. In a program,  
the ON_ERROR language statements must be placed after all the global  
declarations (PROCEDURE, CONSTANT, and VARIABLE) and before any  
executable statements. Error statements can contain any DECTPU language  
statements except other ON_ERROR statements.  
There are three DECTPU lexical elements that are useful in an error handler:  
ERROR, ERROR_LINE, and ERROR_TEXT.  
ERROR returns a keyword for the error or warning. The DEC Text Processing  
Utility Reference Manual includes information on the possible error and warning  
keywords that each built-in procedure can return.  
ERROR_LINE returns the line number at which the error or warning occurs. If  
a procedure was compiled from a buffer or range, ERROR_LINE returns the line  
number within the buffer. (This may be different from the line number within  
the procedure.) If the procedure was compiled from a string, ERROR_LINE  
returns 1.  
ERROR_TEXT returns the text of the error or warning, exactly as DECTPU  
would display it in the message buffer, with all parameters filled in.  
After the execution of an error statement, you can choose where to resume  
execution of a program. The options are the following:  
ABORT—This language statement causes an exit back to the DECTPU wait  
for next key loop.  
Lexical Elements of the DEC Text Processing Utility Language 4–23  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.9 Reserved Words  
RETURN—This language statement stops the execution of the procedure in  
which the error occurred but continues execution of the rest of the program.  
If you do not specify ABORT or RETURN, the default is to continue executing the  
program from the point at which the error occurred.  
DECTPU provides two forms of error handler: procedural and case style.  
4.9.4.15 Procedural Error Handlers  
If a WARNING status is trapped by an ON_ERROR statement, the warning  
message is suppressed. However, if an ERROR status is trapped, the message is  
displayed. With the ON_ERROR trap, you can do additional error handling after  
the DECTPU message is displayed.  
Syntax  
ON_ERROR statement_1; statement_2; . . . statement_n; ENDON_ERROR;  
Example 4–10 shows error statements at the beginning of a procedure. These  
statements return control to the caller if the input on the command line of an  
interface is not correct. Any warning or error status returned by a statement in  
the body of the procedure causes the error statements to be executed.  
Example 4–10 Procedure That Uses the ON_ERROR Statement  
!
! Gold 7 emulation (command line processing)  
!
PROCEDURE command_line  
LOCAL  
line_read, X;  
ON_ERROR  
MESSAGE ("Unrecognized command: " + line_read);  
RETURN;  
ENDON_ERROR;  
!
! Get the command(s) to execute  
!
line_read := READ_LINE ("DECTPU Statement: "); ! get line from user  
!
! compile them  
!
IF line_read <> ""  
THEN  
X := COMPILE (line_read);  
ELSE  
RETURN  
ENDIF;  
!
! execute  
!
IF X <> 0  
THEN  
EXECUTE (X);  
ENDIF;  
ENDPROCEDURE;  
The effects of a procedural error handler are as follows:  
If you press Ctrl/C, DECTPU places an error message in the message buffer,  
exits from all currently active procedures (in their reverse calling order), and  
returns to the wait for next key loop.  
4–24 Lexical Elements of the DEC Text Processing Utility Language  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.9 Reserved Words  
If an error or warning is generated during a CALL_USER routine, ERROR is  
set to a keyword that represents the failure status of the routine, ERROR_  
LINE is set to the line number of the error, and ERROR_TEXT is set to  
a warning or error message that is placed in the message buffer. Finally,  
DECTPU runs the error handler code.  
For other warnings and errors, ERROR is set to a keyword that represents  
the error or warning, ERROR_LINE is set to the line number of the error,  
and ERROR_TEXT is set to the error or warning message associated with  
the keyword. DECTPU places error messages in the message buffer but  
suppresses the display of warning messages. Finally, DECTPU runs the error  
handler code.  
If an error or warning is generated during execution of a procedural error handler,  
DECTPU behaves as follows:  
If you press Ctrl/C during the error handler, DECTPU puts an error message  
in the message buffer, exits from all currently active procedures (in their  
reverse calling order), and returns to the wait for next key loop.  
For other errors and warnings, the appropriate error or warning message  
is written to the message buffer. DECTPU resumes execution at the next  
statement after the statement that generated the error.  
4.9.4.16 Case-Style Error Handlers  
Case-style error handlers provide a number of advantages over procedural error  
handlers. With case-style error handlers, you can do the following:  
Suppress the automatic display of both warning and error status messages  
Trap the TPU$_CONTROLC status  
Write clearer code  
Syntax  
ON_ERROR [condition_1]: statement_1;... [condition_2]: statement_2;... . . .  
[condition_n]: statement_n; ENDON_ERROR;  
You can use the [OTHERWISE] selector alone in an error handler as a shortcut.  
For example, the following two error handlers have the same effect:  
! This error handler uses [OTHERWISE] alone as a shortcut.  
ON_ERROR  
[OTHERWISE] : ;  
ENDON_ERROR  
! This error handler has the same effect as using  
! [OTHERWISE] alone.  
ON_ERROR  
[OTHERWISE] :  
LEARN_ABORT;  
RETURN (FALSE);  
ENDON_ERROR;  
Example 4–11 from the EVE editor shows a procedure with a case-style error  
handler.  
Lexical Elements of the DEC Text Processing Utility Language 4–25  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.9 Reserved Words  
Example 4–11 Procedure with a Case-Style Error Handler  
PROCEDURE eve$learn_abort  
ON_ERROR  
[TPU$_CONTROLC]:  
MESSAGE (ERROR_TEXT);  
RETURN (LEARN_ABORT);  
ENDON_ERROR;  
IF LEARN_ABORT  
THEN  
eve$message (EVE$_LEARNABORT);  
RETURN (TRUE);  
ELSE  
RETURN (FALSE);  
ENDIF;  
ENDPROCEDURE;  
If a program or procedure has a case-style error handler, DECTPU handles errors  
and warnings as follows:  
If you press Ctrl/C, DECTPU determines whether the error handler contains  
a selector labeled TPU$_CONTROLC. If so, DECTPU sets ERROR to TPU$_  
CONTROLC, ERROR_LINE to the line that DECTPU was executing when  
Ctrl/C was pressed, and ERROR_TEXT to the message associated with TPU$_  
CONTROLC. DECTPU then executes the statements associated with the  
selector. If there is no TPU$_CONTROLC selector, DECTPU exits from the  
error handler and looks for a TPU$_CONTROLC selector in the procedures  
or program (if any) in which the current procedure is nested. If no TPU$_  
CONTROLC selector is found in the containing procedures or program,  
DECTPU places the message associated with TPU$_CONTROLC in the  
message buffer.  
If an error or warning is generated during a CALL_USER routine, ERROR is  
set to a keyword that represents the failure status of the routine, ERROR_  
LINE is set to the line number of the error, and ERROR_TEXT is set to  
the warning or error message associated with the keyword. DECTPU then  
processes the error handler that trapped the CALL_USER error in the same  
way that DECTPU processes normal case-style error handlers.  
For other warnings and errors, ERROR is set to a keyword that represents  
the error or warning, ERROR_LINE is set to the line number of the error,  
and ERROR_TEXT is set to the error or warning message associated with the  
keyword.  
The way a case-style error handler processes an error or warning depends  
on how the error handler traps the error. There are three possible ways, as  
follows:  
The error handler can trap the error by using a selector that matches the  
error exactly (that is, using a selector other than OTHERWISE).  
The error handler can trap the error by using the OTHERWISE selector.  
The error handler can completely fail to trap the error.  
The following discussion explains how a case-style error handler processes an  
error or warning in each of these circumstances.  
4–26 Lexical Elements of the DEC Text Processing Utility Language  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.9 Reserved Words  
If the error or warning is trapped by a selector other than OTHERWISE,  
DECTPU does not place the error or warning message in the message  
buffer unless the error handler code instructs it to do so. In this case, after  
setting ERROR, ERROR_LINE, and ERROR_TEXT, DECTPU executes  
the code associated with the selector. If the code does not return to the  
calling procedure or program, DECTPU checks whether one of the selectors  
associated with the code just executed is TPU$_CONTROLC or OTHERWISE.  
If so, DECTPU performs the equivalent of the following sequence:  
special_error_symbol := 0;  
LEARN_ABORT;  
RETURN (FALSE);  
If not, the error handler terminates and DECTPU resumes execution at the  
next statement after the statement that generated the error or warning.  
For more information on the special error symbol in DECTPU, see the  
description of the SET (SPECIAL_ERROR_SYMBOL) built-in procedure  
in the DEC Text Processing Utility Reference Manual.  
If the error or warning is trapped by the OTHERWISE selector, DECTPU  
writes the associated error or warning message in the message buffer. Next,  
DECTPU executes the code associated with the OTHERWISE selector. If the  
code does not return to the calling procedure or program, DECTPU performs  
the equivalent of the following sequence:  
special_error_symbol := 0;  
LEARN_ABORT;  
RETURN (FALSE);  
If the error or warning is not trapped by any selector, DECTPU writes the  
associated error or warning message in the message buffer. Next, DECTPU  
performs the equivalent of the following sequence:  
special_error_symbol := 0;  
LEARN_ABORT;  
RETURN (FALSE);  
If an error or warning is generated during execution of a case-style error handler,  
DECTPU behaves as follows:  
If you press Ctrl/C during the error handler, DECTPU sets ERROR to  
TPU$_CONTROLC, ERROR_LINE to the line being executed when Ctrl/C  
was pressed, and ERROR_TEXT to the message associated with TPU$_  
CONTROLC.  
If one of the case selectors in the error handler is TPU$_CONTROLC,  
DECTPU executes the code associated with the selector. If the code does not  
return to the calling procedure or program, DECTPU performs the equivalent  
of the following sequence:  
special_error_symbol := 0;  
LEARN_ABORT;  
RETURN (FALSE);  
If none of the selectors is TPU$_CONTROLC, then DECTPU exits from the  
error handler and looks for a TPU$_CONTROLC selector in the procedures  
or program (if any) in which the current procedure is nested. If DECTPU  
does not find a TPU$_CONTROLC selector in the containing procedures or  
program, DECTPU places the message associated with TPU$_CONTROLC in  
the message buffer.  
Lexical Elements of the DEC Text Processing Utility Language 4–27  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.9 Reserved Words  
If the error is not due to you pressing Ctrl/C, the error message is written  
to the message buffer and DECTPU performs the equivalent of the following  
sequence:  
special_error_symbol := 0;  
LEARN_ABORT;  
RETURN (FALSE);  
In a procedure with a case-style error handler, an ABORT statement produces  
the same effect as the sequence Ctrl/C, with one exception: an ABORT statement  
in the TPU$_CONTROLC clause of a case-style error handler does not reinvoke  
the TPU$_CONTROLC clause, as is the case when Ctrl/C is pressed while  
TPU$_CONTROLC is executing. Instead, an ABORT statement causes DECTPU  
to exit from the error handler and look for a TPU$_CONTROLC selector in  
the procedures or program (if any) in which the current procedure is nested. If  
DECTPU does not find a TPU$_CONTROLC selector in the containing procedures  
or program, DECTPU places the message associated with TPU$_CONTROLC in  
the message buffer.  
4.9.4.17 Ctrl/C Handling  
The ability to trap a Ctrl/C in your DECTPU program is both powerful and  
dangerous. When you press Ctrl/C, you usually want the application that is  
running to prompt for a new command. The ability to trap the Ctrl/C is intended  
to allow a procedure to clean up and exit gracefully.  
4.9.4.18 RETURN Statement  
The RETURN statement causes a return to the procedure that called the current  
procedure or program. The return is to the statement that follows the statement  
that called the current procedure or program. You can specify an expression after  
the RETURN statement and the value of this expression is passed to the calling  
procedure.  
Syntax  
RETURN expression;  
The expression is optional; if it is missing, DECTPU supplies a 0. Also,  
the RETURN statement itself is optional. That is, if DECTPU reaches the  
endprocedure of a procedure before encountering a RETURN statement, it will  
return 0.  
Example 4–12 shows a sample procedure in which a value is returned to the  
calling procedure.  
Example 4–12 Procedure That Returns a Value  
PROCEDURE user_get_shift_key  
LOCAL key_to_shift; ! Keyword for key pressed after shift key  
SET (SHIFT_KEY, LAST_KEY);  
key_to_shift := KEY_NAME (READ_KEY, SHIFT_KEY);  
RETURN key_to_shift;  
ENDPROCEDURE;  
In addition to using RETURN to pass a value, you can use a 1 (true) or a 0 (false)  
with the RETURN statement to indicate the status of a procedure. Example 4–13  
shows this usage of the RETURN statement.  
4–28 Lexical Elements of the DEC Text Processing Utility Language  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.9 Reserved Words  
Example 4–13 Procedure That Returns a Status  
PROCEDURE user_at_end_of_line  
! This procedure returns a 1 (true) if user is at the end of a  
! line, or a 0 (false) if the current character is not at the  
! end of a line  
ON_ERROR  
! Suppress warning message  
RETURN (1);  
ENDON_ERROR;  
IF CURRENT_OFFSET = LENGTH (CURRENT_LINE)  
THEN  
RETURN (1);  
ELSE  
RETURN (0);  
ENDIF;  
ENDPROCEDURE;  
You can use the RETURN statement in the ON_ERROR section of a procedure  
to specify a return to the calling procedure if an error occurs in the current  
procedure. Example 4–14 uses the RETURN statement in an ON_ERROR  
section.  
Example 4–14 Using RETURN in an ON_ERROR Section  
! Attach to the parent process. Used when EVE is spawned  
! from DCL and run in a subprocess ("kept DECTPU"). The  
! ATTACH command can be used for more flexible process control.  
PROCEDURE eve_attach  
ON_ERROR  
IF ERROR = TPU$_NOPARENT  
THEN  
MESSAGE ("Not running DECTPU in a subprocess");  
RETURN;  
ENDIF;  
ENDON_ERROR;  
ATTACH;  
ENDPROCEDURE;  
4.9.4.19 ABORT Statement  
The ABORT statement stops any executing procedures and causes DECTPU to  
wait for the next keystroke. ABORT is commonly used in error handlers. For  
additional information on using ABORT in error handlers, see Section 4.9.4.14.  
Syntax  
ABORT  
Example 4–15 shows a simple error handler that contains an ABORT statement.  
Lexical Elements of the DEC Text Processing Utility Language 4–29  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.9 Reserved Words  
Example 4–15 Simple Error Handler  
ON_ERROR  
MESSAGE ("Aborting procedure because of error.");  
ABORT;  
ENDON_ERROR;  
4.9.5 Miscellaneous Declarations  
This section describes the following DECTPU language declarations:  
EQUIVALENCE  
LOCAL  
CONSTANT  
VARIABLE  
4.9.5.1 EQUIVALENCE  
With the EQUIVALENCE declaration, you can create synonyms. Equivalences  
work only when both real_name and synonym_name are defined at the same time.  
You cannot save a section file that contains real_name and then later use that  
section file to extend code that uses an EQUIVALENCE of the saved name. To  
avoid problems, include all EQUIVALENCE declarations in the same compilation  
unit where real_name is defined.  
The equivalences can reside in different compilation units, but you must use all  
of the compilation units when building the section file from scratch. If you use a  
base section file that you extend interactively, you cannot make equivalences to  
procedures or variables defined in the base section file.  
Syntax  
EQUIVALENCE synonym_name1 = real_name1, synonym_name2 = real_name2,  
...;  
Elements of the EQUIVALENCE Statement  
real_name  
A user-defined global variable or procedure name. If real_name is undefined,  
DECTPU defines it as an ambiguous name. This ambiguous name can become a  
variable or procedure later.  
synonym_name  
A name to be defined as a synonym for the real_name.  
4.9.5.2 LOCAL  
With the LOCAL declaration, you can identify certain variables as local variables  
rather than global variables. All variables are considered to be global variables  
unless you explicitly use the LOCAL declaration to identify them as local  
variables. The LOCAL declaration in a procedure is optional. It must be specified  
after the PROCEDURE statement and before any ON_ERROR statement.  
LOCAL declarations and CONSTANT declarations can be intermixed.  
The maximum number of local variables you can declare in a procedure is 255.  
Local variables are initialized to 0.  
4–30 Lexical Elements of the DEC Text Processing Utility Language  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.9 Reserved Words  
Syntax  
LOCAL variable-name [[,...]];  
Local variables may also be declared in unbound code. Such variables are  
accessible only within that unbound code.  
Unbound code can occur in the following places:  
Module initialization code  
This occurs after all procedure declarations within a module but before the  
ENDMODULE statement.  
Executable code  
This occurs after all module and procedure declarations in a file but before  
the end of file.  
The following example shows a complete compilation unit. This unit contains  
a module named mmm that, in turn, contains a procedure bat and some  
initialization code mmm_module_init, a procedure bar defined outside the module,  
and some unbound code at the end of the file. In each of these sections of code, a  
local variable X is defined. The variable is displayed using the MESSAGE built-in  
procedure.  
MODULE mmm IDENT "mmm"  
PROCEDURE bat;  
LOCAL  
! Declare procedure "bat" in module "mmm"  
X; ! "X" is local to procedure "bat"  
X := "Within procedure bat, within module mmm";  
MESSAGE (X);  
ENDPROCEDURE; ! End procedure "bat"  
LOCAL  
X;  
! "X" is local to  
! procedure "mmm_module_init"  
X := "Starting or ending the module init code";  
MESSAGE (X);  
bat;  
MESSAGE (X);  
ENDMODULE;  
! End module "mmm"  
PROCEDURE bar  
! Declare procedure "bar"  
LOCAL  
X;  
! "X" is local to procedure "bar"  
X := "In procedure bar, which is outside all modules";  
MESSAGE (X);  
ENDPROCEDURE;  
! End procedure "bar"  
LOCAL  
X;  
! "X" is local to the unbound code...  
X := "Starting or ending the unbound, non-init code";  
MESSAGE (X);  
mmm_module_init;  
bat;  
bar;  
MESSAGE (X);  
EXIT;  
Lexical Elements of the DEC Text Processing Utility Language 4–31  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.9 Reserved Words  
If this code is included in TEMP.TPU, the following command demonstrates the  
scope of the various local variables:  
$
EDIT/TPU/NOSECTION/NOINITIALIZE/NODISPLAY/COMMAND=temp.tpu  
Starting or ending the unbound, non-init code  
Starting or ending the module init code  
Within procedure bat, within module mmm  
Starting or ending the module init code  
Within procedure bat, within module mmm  
In procedure bar, which is outside all modules  
Starting or ending the unbound, non-init code  
4.9.5.3 CONSTANT  
With the CONSTANT declaration, you can associate a name with certain constant  
expressions. The constant expression must evaluate at compile time to a keyword,  
a string, an integer, or an unspecified constant value. The maximum length of  
a string constant allowed in a constant declaration is about 4000 characters in  
length. DECTPU sets up some predefined global constants. See Section 4.9.3 for  
a list of predefined constants.  
Constants can be either globally or locally defined. Global constants are constants  
declared outside procedure declarations. Once a global constant has been defined,  
it is set for the life of the DECTPU session. An attempt to redefine a constant  
will succeed only if the constant value is the same.  
Local constants are constants declared within a procedure. You must specify a  
local CONSTANT declaration after the PROCEDURE statement and before any  
ON_ERROR statement. You can intermix LOCAL statements and CONSTANT  
statements.  
Syntax  
CONSTANT constant-name := compile-time-constant-expression [[,...]];  
4.9.5.4 VARIABLE  
With the VARIABLE declaration, you can identify certain variables as global  
variables. Any symbols that are neither declared nor used as the target of an  
assignment statement before being referenced by DECTPU are assumed to  
be undefined procedures. You must use the VARIABLE declaration outside a  
procedure declaration. Initialize global variables to the data type unspecified.  
Syntax  
VARIABLE variable-name [[,...]];  
4.10 Lexical Keywords  
The next two sections explain the DECTPU lexical keywords and how to use  
them for the following:  
Conditional compiling  
Specifying the radix of numeric constants  
4–32 Lexical Elements of the DEC Text Processing Utility Language  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.10 Lexical Keywords  
4.10.1 Conditional Compilation  
The following lexical keywords control what code is compiled under different  
conditions:  
%IF  
%IFDEF  
%THEN  
%ELSE  
%ENDIF  
You use conditional compilation lexical keywords in a manner similar to ordinary  
IF/THEN/ELSE/ENDIF statements. The syntax is as follows:  
%IFDEF variable_or_proc_name %THEN ... [%ELSE ...] %ENDIF  
or  
%IF boolean_expression %THEN ... [%ELSE ...] %ENDIF  
If you use the %IFDEF structure, specify variable_or_proc_name as the name of  
a DECTPU procedure or variable. IFDEF is a statement that says if a variable  
or procedure with this name is defined.If the name is defined, the compiler  
compiles the code marked by %THEN. If the name is not defined, the compiler  
compiles the code marked by %ELSE.  
If you use the %IF structure, specify boolean_expression as either a numeric  
constant or a defined global variable whose value is an integer. Any odd value  
is true and any even value is false. If the variable or constant contains a value  
that is odd, the compiler compiles the code marked by %THEN. If the variable or  
constant contains a value that is even, the compiler compiles the code marked by  
%ELSE.  
You do not have to put conditional compilation lexical keywords at the beginning  
of a line. You can nest conditional statements to a depth of 2**32-1. For example:  
ON_ERROR  
[TPU$_CREATEFAIL]:  
%IF eve$x_option_decwindows  
%THEN  
IF eve$x_decwindows_active  
THEN  
eve$popup_message (MESSAGE_TEXT (EVE$_CANTCREADCL, 1));  
ELSE  
eve$message (EVE$_CANTCREADCL);  
ENDIF;  
%ELSE  
eve$message (EVE$_CANTCREADCL);  
%ENDIF  
eve$learn_abort;  
RETURN (FALSE);  
[OTHERWISE]:  
ENDON_ERROR;  
This ON_ERROR procedure determines whether a pop-up message widget or a  
simple message is used, depending on whether the code is being compiled by a  
DECwindows version of DECTPU.  
Lexical Elements of the DEC Text Processing Utility Language 4–33  
 
Lexical Elements of the DEC Text Processing Utility Language  
4.10 Lexical Keywords  
4.10.2 Specifying the Radix of Numeric Constants  
You can specify constants with binary, octal, hexadecimal, and decimal radices.  
To specify a numeric constant in binary, precede the number with %B. The  
number can consist only of the digits 0 and 1.  
To specify a numeric constant in octal, precede the number with %O. The number  
can consist only of the digits 0 through 7.  
To specify a numeric constant in hexadecimal, precede the number with %X. The  
number can consist of digits 0–9 and A–F.  
There is no radix specifier for decimal. Any numeric constant without an explicit  
radix specifier is assumed to be decimal. The radix specifier may be in uppercase  
or lowercase.  
The following are examples of correct numeric constants:  
!
! Many different ways of saying the same thing.  
!
CONSTANT binary_constant := %b11111;  
CONSTANT octal_constant := %o37;  
CONSTANT decimal_constant := 31;  
CONSTANT hex_constant := %x1f;  
!
! Compile time expressions work, too.  
!
CONSTANT negative_value := -%x1f;  
CONSTANT strange_zero := hex_constant - %x1f;  
Invalid constructs for numeric constants return the error level message TPU$_  
UNKLEXICAL, "Unknown lexical element" during compilation. The following  
examples are not valid:  
constant bad_binary := %b123;  
constant bad_hex := %x10abg;  
constant not_a_radix := %z0123;  
! only 0’s and 1’s are legal.  
! ’g’ is illegal digit.  
! No such radix.  
4–34 Lexical Elements of the DEC Text Processing Utility Language  
 
5
DEC Text Processing Utility Program  
Development  
Previous chapters have described the lexical elements of the DECTPU language,  
such as data types, language statements, expressions, built-in procedures,  
and so on. This chapter describes how to combine these elements in DECTPU  
programs. You can use DECTPU programs to perform editing tasks, to customize  
or extend an existing application, or to implement your own application layered  
on DECTPU.  
Before you start writing programs to customize or extend an existing application,  
you should be familiar with the DECTPU source code that creates the editor  
or application that you want to change. For example, if you use the Extensible  
Versatile Editor (EVE) and you want to change the size of the main window, you  
must know and use the procedure name that EVE uses for that window. (If you  
want to change the main window, you use the procedure name eve$main_window.  
Many of the EVE variables and procedure names begin with eve$.)  
The sample procedures and syntax examples in this book use uppercase letters  
for items that you can enter exactly as shown. DECTPU reserved words, such as  
built-in procedures, keywords, and language statements are shown in uppercase.  
Lowercase items in a syntax example or sample procedure indicate that you must  
provide an appropriate substitute for that item.  
This chapter discusses the following topics:  
Creating DECTPU programs  
Programming in DECwindows DECTPU  
Writing code compatible with DECwindows EVE  
Compiling DECTPU programs  
Executing DECTPU programs  
Using DECTPU startup files  
Debugging DECTPU programs  
Handling Errors  
5.1 Creating DECTPU Programs  
When you write a DECTPU program, keep the following pointers in mind:  
You can use EVE or some other editor to enter or change the source code of a  
program in the DECTPU language.  
A program can be a single executable statement or a collection of executable  
statements.  
DEC Text Processing Utility Program Development 5–1  
 
DEC Text Processing Utility Program Development  
5.1 Creating DECTPU Programs  
You can use executable statements either within procedures or outside  
procedures. You must place all procedure declarations before any executable  
statements that are not in procedures.  
You can enter DECTPU statements from within EVE by using the EVE  
command TPU. For more information on using this command, see the  
Extensible Versatile Editor Reference Manual.  
5.1.1 Simple Programs  
The following statement is an example of a simple program:  
SHOW (SUMMARY);  
The preceding statement, entered after the appropriate prompt from your editor,  
causes DECTPU to execute the program associated with the SHOW (SUMMARY)  
statement. If you use EVE with a user-written command file, your screen may  
display text similar to Example 5–1.  
Example 5–1 SHOW (SUMMARY) Display  
DECTPU V3.1 1993-08-17 08:37  
Journal file:  
Section file name: EVE$SECTION Ident: V3.1 Date: 17-AUG-1993 08:49  
Activated from: TPU$SECTION  
Created by: DECTPU V3.1 1993-08-17 08:37  
Extension: SCREEN_UPDATER Ident: DECTPU V3.1 1993-08-17 08:37  
Timer Message:  
working  
24 System buffers and 1 User buffer  
5.1.2 Complex Programs  
When writing complex DECTPU programs, avoid the following practices:  
Creating large procedures  
Creating large number of procedures  
Including a large number of executable statements that are not within  
procedures  
These practices, if carried to extremes, can cause the parser stack to overflow.  
The DECTPU parser currently allows a maximum stack depth of 1000 syntax  
tree nodes. When the parser first encounters a DECTPU statement, the parser  
assigns each token in the statement to a syntax tree node. For example, the  
statement ‘a := 1 contains three tokens, each of which occupies a syntax tree  
node. After the parser parses this statement, only the assignment statement  
remains on the stack of nodes. The a and the 1 are subtrees to the assignment  
syntax tree node.  
The most common cause of stack overflow, which is signaled by the status TPU$_  
STACKOVER, is creating one or more large procedures whose statements occupy  
too many syntax tree nodes. To make your program manageable by the parser,  
break the large procedures into smaller ones.  
5–2 DEC Text Processing Utility Program Development  
 
DEC Text Processing Utility Program Development  
5.1 Creating DECTPU Programs  
Other possible reasons for a TPU$_STACKOVER condition are that you have too  
many statements that are not in procedures, or that you have too many small  
procedures. If you have too many small procedures, you must either consolidate  
them or break them into separate files.  
To see an example of a complex DECTPU program, examine the source  
files that implement EVE. The EVE source code files are located at  
SYS$EXAMPLES:EVE$*.*. These files contain many procedure declarations  
and executable statements that specify EVEs screen layout and display. These  
files also contain key definitions that specify which editing operations are  
performed when you press certain keys on the keyboard. You can examine these  
files to learn the programming techniques that were used to create EVE.  
See Section 5.6 for information on using a command file or section file to create  
or customize an application layered on DECTPU. See the DEC Text Processing  
Utility Reference Manual for information on using the EVE$BUILD module to  
layer applications on top of EVE.  
5.1.3 Program Syntax  
The rules for writing DECTPU programs are simple. You must use a semicolon  
to separate each executable statement from other statements. In a program, you  
must place all procedure declarations before any executable statements that are  
not part of a procedure declaration. For information on DECTPU data types,  
see Chapter 3. For information on DECTPU language elements, see Chapter 4.  
Example 5–2 shows the correct syntax for a DECTPU program.  
Example 5–2 Syntax of a DECTPU Program  
PROCEDURE  
.
.
.
ENDPROCEDURE  
PROCEDURE;  
.
.
.
ENDPROCEDURE;  
.
.
.
PROCEDURE  
.
.
.
ENDPROCEDURE;  
statement 1;  
statement 2;  
.
.
.
statement n;  
A variety of syntactically correct DECTPU programs is shown in Example 5–3.  
DEC Text Processing Utility Program Development 5–3  
 
DEC Text Processing Utility Program Development  
5.1 Creating DECTPU Programs  
Example 5–3 Sample DECTPU Programs  
! Program 1  
! This program consists of a single DECTPU built-in procedure.  
SHOW (KEYWORDS);  
! Program 2  
! This program consists of an assignment statement that  
! gives a value to the variable video_attribute  
video_attribute := UNDERLINE;  
! Program 3  
! This program consists of the DECTPU LOOP statement (with  
! a condition for exiting) and the DECTPU built-in procedure ERASE_LINE.  
x := 0; LOOP x :=x+1; EXITIF x > 100; ERASE_LINE; ENDLOOP;  
! Program 4  
! This program consists of a single procedure that makes  
! DECTPU quit the editing session.  
PROCEDURE user_quit  
QUIT;  
ENDPROCEDURE;  
! do DECTPU quit operation  
! Program 5  
! This program is a collection of procedures that  
! makes DECTPU accept "e", "ex", or "exi" as  
! the command for a DECTPU exit operation.  
PROCEDURE e  
EXIT;  
! do DECTPU exit operation  
ENDPROCEDURE;  
PROCEDURE ex  
EXIT;  
ENDPROCEDURE;  
PROCEDURE exi  
EXIT;  
ENDPROCEDURE;  
5.2 Programming in DECwindows DECTPU  
This section provides information about programming with DECTPU in the  
DECwindows environment.  
5.2.1 Widget Support  
With DECwindows DECTPU, you can create widgets from within DECTPU  
programs by using the CREATE_WIDGET built-in procedure. For more  
information on widgets, see the OpenVMS overview documentation.  
With the CREATE_WIDGET built-in, you can create the following widgets in  
DECTPU:  
Caution_box  
Dialog_box  
File_selection  
Label  
List_box  
Main_window  
5–4 DEC Text Processing Utility Program Development  
 
DEC Text Processing Utility Program Development  
5.2 Programming in DECwindows DECTPU  
Menu_bar  
Popup_attached_db  
Popup_dialog_box  
Popup_menu  
Pulldown_entry  
Pulldown_menu  
Push_button  
Scroll_bar (vertical and horizontal)  
Separator  
Simple_text  
Toggle_button  
5.2.2 Input Focus Support  
In DECwindows, at most one of the applications on the screen can have the input  
focus; that is, only one application can accept user input from the keyboard. For  
more information about the input focus, see the Motif documentation.  
DECwindows DECTPU automatically grabs the input focus whenever you cause  
an unmodified M1DOWN event (that is, an event not modified by Shift, Ctrl,  
or other modifying key) while the pointer cursor is in either of the following  
locations:  
DECTPUs main window widget  
DECTPUs title bar  
DECwindows assigns input focus to DECTPU only if and when it is possible to  
do so. To make sure that DECwindows can assign input focus, your application  
should use the GET_INFO (SCREEN, input_focus’) built-in procedure.  
If assignment of input focus to DECTPU is enabled, DECTPU can receive input  
focus in the following circumstances:  
DECwindows DECTPU grabs input focus  
The DECwindows session manager assigns input focus to DECTPU  
An application layered on DECTPU requests input focus  
In the Motif environment, DECTPU supports both implicit and explicit focus  
policies.  
Compaq recommends that you use only a DECwindows section file with  
DECwindows DECTPU. (All versions of EVE shipped with OpenVMS Version  
5.1 or higher are compatible with DECwindows and are suitable for building  
DECwindows section files, as well as DECTPU Version 3.0 or higher.) However,  
if you do not follow this recommendation, DECTPUs automatic grabbing of the  
input focus enables your layered application to interact with other DECwindows  
applications.  
DEC Text Processing Utility Program Development 5–5  
 
DEC Text Processing Utility Program Development  
5.2 Programming in DECwindows DECTPU  
5.2.3 Global Selection Support  
Global selection in DECwindows is a means of preserving information selected  
by you so your selection, or data about your selection, can pass between  
DECwindows applications. Each DECwindows application can own one or  
more global selections.  
5.2.3.1 Difference Between Global Selection and Clipboard  
A global selection differs from the clipboard in that the global selection changes  
dynamically as you change the select range, while the contents of the clipboard  
remain unchanged until you use a command (such as EVEs STORE TEXT  
command) that sends new information to the clipboard. By default EVE does not  
use the clipboard.  
5.2.3.2 Handling of Multiple Global Selections  
At any particular time, a global selection is owned by at most one DECwindows  
application; a global selection can also be unowned. A DECwindows application  
can own more than one global selection at the same time. For example, an  
application layered on DECTPU can own both the primary and secondary global  
selections. The DECwindows server determines which application currently owns  
which global selection.  
Information about a global selection property may be stored in different formats,  
but the format of a particular property must be the same for all DECwindows  
applications. DECTPU directly accepts information that is stored in integer  
or string format. DECTPU handles information in other formats by describing  
the information in an array. For more information about this array, see the  
descriptions of the GET_GLOBAL_SELECT and WRITE_GLOBAL_SELECT  
built-in procedures in the DEC Text Processing Utility Reference Manual.  
Global selections are identified in DECTPU either as strings or keywords. While  
DECwindows provides for many global selections, applications conforming to  
the Motif Style Guide are concerned with only two selections—the primary  
and secondary selections. DECTPU provides a pair of keywords (PRIMARY  
and SECONDARY) to refer to these selections. DECTPU also provides built-  
in procedures that enable layered applications to manipulate global selection  
information.  
You can refer to other global selections by specifying a string instead of the  
keywords PRIMARY and SECONDARY. For example, if your application has a  
global selection whose name is auxiliary, use the string "auxiliary" to specify the  
selection. Selection names are case sensitive; the string "auxiliary" does not refer  
to the same global selection as the string "AUXILIARY".  
5.2.3.3 Relation of Global Selection to Input Focus  
An application that conforms to the Motif Style Guide requests ownership of the  
primary global selection in its input focus grab procedure. Regardless of whether  
the application conforms, when DECTPU gets the input focus, it automatically  
grabs the primary global selection if it is not already the owner.  
An application cannot prevent DECTPU from attempting to assert ownership of  
the primary global selection when DECTPU receives the input focus. If DECTPU  
gets the primary selection by grabbing ownership itself, DECTPU automatically  
executes the applications global selection grab routine if one is present. If you are  
writing an application that conforms to the Motif Style Guide and you find that  
DECTPU has had to grab ownership of the primary selection itself and execute  
the global select grab routine, your application may have a design problem.  
5–6 DEC Text Processing Utility Program Development  
 
DEC Text Processing Utility Program Development  
5.2 Programming in DECwindows DECTPU  
5.2.3.4 Response to Requests for Information About the Global Selection  
DECTPU provides a three-level hierarchy for responding to requests from another  
application for information about the current selection. Applications layered on  
DECTPU may specify a routine that responds to requests for information about  
global selections either for the entire application or for one or more buffers in the  
application.  
When DECTPU receives a request for information, it checks whether there is a  
routine for the current buffer that responds to information about global selections.  
If no buffer-specific routine is available, DECTPU checks for an application-  
wide routine. If no application-wide routine is available, DECTPU can provide  
information only about the primary selection, the file name, font, line number,  
and text.  
DECTPU responds to all other requests with a message that no information  
is available. DECTPU does not send requests for information about the global  
selection to other DECwindows applications. DECTPU applications may use the  
various built-in procedures to do so.  
DECTPUs responses to requests for information about the primary selection are  
as follows:  
"FILE_NAME"  
DECTPU responds with the string returned by the GET_INFO  
(CURRENT_BUFFER, "file_name") built-in procedure.  
"FONT"  
DECTPU responds with the string returned by the GET_INFO  
(SYSTEM, "default_font") built-in procedure.  
"LINE_NUMBER"  
DECTPU responds with the value of type span containing the  
record number where the select range starts and the record  
number where the select range ends.  
"TEXT" or "STRING"  
DECTPU responds with the text of the select range as a string,  
with each line break represented by a line feed.  
Compaq recommends that you use only a DECwindows section file with  
DECwindows DECTPU. However, if you do not follow this recommendation,  
DECTPUs automatic grabbing of the primary global selection enables your  
layered application to interact with other DECwindows applications.  
If an application requests information about the primary global selection while  
DECTPU owns the selection, DECTPU attempts to respond to the request if  
the application cannot do so. If DECTPU responds to the request by sending  
the text of a buffer or range, DECTPU converts the buffer or range to a string,  
converts line breaks to line feeds, and inserts padding blanks before text to  
fill any unoccupied space between the margins. If neither the application nor  
DECTPU can respond to the request, DECTPU informs DECwindows that the  
requested information is not available.  
DECTPU does not automatically grab the secondary selection. Layered  
applications are responsible for handling this selection.  
5.2.4 Using Callbacks  
This section presents background information on the DECwindows concept of  
callbacks and explains how DECwindows DECTPU implements this concept.  
DEC Text Processing Utility Program Development 5–7  
 
DEC Text Processing Utility Program Development  
5.2 Programming in DECwindows DECTPU  
5.2.4.1 Background on DECwindows Callbacks  
A ca llba ck is a mechanism used by a DECwindows widget to notify an  
application that the widget has been modified in some way. DECwindows  
applications have one or more callback routines that define what the application  
does in response to the callback.  
For more information about the use of callbacks and callback routines in  
DECwindows programs, see the OpenVMS documentation overview.  
5.2.4.2 Internally Defined DECTPU Callback Routines and Application-Level Callback Action  
Routines  
DECTPU implements the DECwindows concept of callback routines by providing  
internally defined routines that deliver the information obtained from a widgets  
callback to a layered application. These routines are referred to as internally  
defined DECTPU callback routines.’  
When a widget calls back to DECTPU, DECTPU packages the callback  
information, adds the information to its input queue, and returns to the widget.  
DECTPU may not process the callback packet on its input queue until later. As  
a result, the information about the widget that DECTPU gets from the callback  
may not match the information returned by the GET_INFO (widget_variable,  
"widget_info") built-in procedure.  
When DECTPU processes the callback packet, it uses the CREATE_WIDGET  
built-in or the SET (WIDGET_CALLBACK) built-in to execute the program  
or learn sequence that was associated with the widget. This program or  
learn sequence controls what the application does in response to the callback  
information passed by the DECTPU callback routines. An applications callback  
routines are referred to as application-level callback action routines.’  
The following sections present information on internally defined DECTPU  
callback routines and on application-level callback action routines.  
5.2.4.3 Internally Defined DECTPU Callback Routines with UIL  
DECTPU declares two internally defined callback routines to the X Resource  
Manager to handle incoming callbacks and dispatch them to the layered  
application:  
TPU$WIDGET_INTEGER_CALLBACK—Use this routine as the callback  
routine for all callbacks that have an integer closure.  
TPU$WIDGET_STRING_CALLBACK—Use this routine as the callback  
routine for all callbacks that have a string closure.  
Although DECwindows lets you specify a different callback routine for each  
reason that a widget can call back, DECwindows DECTPU does not support this  
capability. Instead, it provides only the two callback routines mentioned.  
Use these callback routines only if you are specifying a widgets callback resources  
in a User Interface Language (UIL) file. When a widget is part of an X Resource  
Manager hierarchy, do not include callback resource names or values in the array  
you pass to SET (WIDGET). Instead, specify one of the two internally defined  
callback routines in the UIL file.  
5–8 DEC Text Processing Utility Program Development  
 
DEC Text Processing Utility Program Development  
5.2 Programming in DECwindows DECTPU  
5.2.4.4 Internally Defined DECTPU Callback Routines with Widgets Not Defined by UIL  
Although the SET (WIDGET) built-in procedure lets you specify values for  
various resources of a widget, there are restrictions on specifying values for  
callback resources of widgets. When a widget is not part of an X Resource  
Manager hierarchy, specify the names of the callback resources in the array  
you pass to SET (WIDGET), and specify 0 as the value of each such callback  
resource. DECTPU automatically substitutes its common callback entry point for  
the 0 value. A widget calls back only for those reasons specified in the widgets  
argument list. If a reason is omitted from the list, the corresponding event does  
not cause a callback.  
5.2.4.5 Application-Level Callback Action Routines  
When DECTPU receives a widget callback, it identifies and executes the  
layered application procedure or learn sequence that has been designated as  
the callback action routine. You can designate a procedure or learn sequence  
as a callback action routine either when the widget is created, by using the  
CREATE_WIDGET built-in procedure, or at some later time, by using the SET  
(WIDGET_CALLBACK) built-in procedure. When you specify an application-level  
callback program or learn sequence with CREATE_WIDGET or SET (WIDGET_  
CALLBACK), all widgets in the same X Resource Manager hierarchy have the  
same callback program or learn sequence. Therefore, the callback program or  
learn sequence must have a mechanism for handling all possible callback reasons.  
5.2.4.6 Callable Interface-Level Callback Routines  
If you are layering an application on DECTPU or on EVE, you can specify callable  
interface-level callback routines only if you are specifying a widgets callback  
resources in a User Interface Language (UIL) file.  
Callbacks can pass values known as closures. Closu r es are strings or integers  
whose function depends on the application you are writing. (DECwindows  
documentation refers to closures as tags.) For more information about what  
closures are and how to use them, see Section 5.2.5.  
You use the DECTPU callable interface routine TPU$WIDGET_INTEGER_  
CALLBACK as the callback routine for all callbacks that have an integer closure.  
You use the DECTPU routine TPU$WIDGET_STRING_CALLBACK for all  
callbacks that have a string closure.  
When a widget is part of an X Resource Manager hierarchy, do not include  
callback resource names or values in the array you pass to SET (WIDGET).  
Instead, specify the callback routine in the UIL file. When a widget is not part  
of an X Resource Manager hierarchy, specify the names of the callback resources  
in the array you pass to SET (WIDGET), and specify 0 as the value of each such  
callback resource. DECTPU automatically substitutes its common callback entry  
point for the 0 value. A widget calls back only for those reasons specified in the  
widgets argument list. If a reason is omitted from the list, the corresponding  
event does not cause a callback.  
DEC Text Processing Utility Program Development 5–9  
 
DEC Text Processing Utility Program Development  
5.2 Programming in DECwindows DECTPU  
5.2.5 Using Closures  
With DECwindows, you can specify a closure value for a widget. (DECwindows  
documentation refers to closures as tags.) DECwindows does not define what a  
closure value is; a closure is simply a value that DECwindows understands how  
to recognize and manipulate so that a DECwindows application programmer can  
use the value if needed in the application. For general information about using  
closures in DECwindows, see the OpenVMS documentation overview.  
When a widget calls back to the DECwindows application, the callback  
parameters include the closure value assigned to the widget. DECwindows  
allows the application to define the significance and possible values of the closure.  
DECTPU supports closure values of type string and integer. Closure values are  
optional for widgets used by applications layered on DECTPU. If you do not  
specify a closure value, the GET_INFO (WIDGET, "callback_parameters", array)  
built-in procedure returns unspecified in the "closure" array element. If you  
create a widget without using a UIL file, the GET_INFO (WIDGET, "callback_  
parameters", array) built-in procedure returns the closure you specified as a  
parameter to CREATE_WIDGET. If you create a widget by using a UIL file, the  
GET_INFO (WIDGET, "callback_parameters", array) built-in procedure returns  
the closure value (if any) defined in the X Resource Manager. If none is defined,  
the built-in returns unspecified.  
DECTPU leaves it to the layered application to use the closure in any way the  
application programmer wishes. DECTPU passes through to the application any  
closure value received as part of a callback.  
DECwindows EVE provides an example of how an application can use closure  
values. DECwindows EVE assigns a unique closure value to every widget  
instance that can be created during an EVE editing session. Each closure value  
corresponds to something that EVE must do in response to the activation of  
that particular widget. When an event causes DECTPU to execute EVEs main  
callback program, the GET_INFO (WIDGET, "callback_parameters", array) built-  
in procedure returns the widget activated, the reason code (the reason the widget  
is calling back), and the closure associated with the particular widget instance.  
EVEs main callback program contains an array that is indexed with values  
identical to the widget closure values. Each array element contains a pointer to  
the EVE code to be executed in response to the corresponding widgets callback.  
EVEs callback program uses the closure value to locate the appropriate array  
index so the correct EVE routine can be executed in response to the callback.  
If your layered application does not use EVEs callback program, then its callback  
program or learn sequence must have a mechanism for determining which widget  
is calling back and which application code should be executed as a result.  
5.2.6 Specifying Values for Widget Resources in DECwindows DECTPU  
This section discusses techniques for specifying values for widget resources.  
5.2.6.1 DECTPU Data Types for Specifying Resource Values  
DECTPU supports the following data types with which to specify values for  
widget resources:  
String  
Array of strings  
Integer  
5–10 DEC Text Processing Utility Program Development  
 
DEC Text Processing Utility Program Development  
5.2 Programming in DECwindows DECTPU  
DECTPU converts the value you specify into the data type appropriate for the  
widget resource you are setting. Table 5–1 shows the relationship between  
DECTPU data types for widget resources and DECwindows data types for widget  
resources.  
Table 5–1 Relationship Between DECTPU Data Types and DECwindows  
Argument Data Types  
DECwindows Argument Data Type  
DECTPU Data Type  
Array of strings  
Boolean  
Array of strings  
Integer  
Callback  
Integer (0)  
String  
Compound string  
Compound string table  
Dimension  
Array of strings  
Integer  
Integer  
Integer  
Position  
Integer  
Short  
Integer  
String  
String  
Unsigned character  
Integer  
DECTPU does not support setting values for resources (such as pixmap, color  
map, font, icon, widget, and so on) whose data types are not listed in this table.  
When you pass an array that specifies values for a widgets resources by using  
CREATE_WIDGET or SET (WIDGET), DECTPU verifies that each array index  
is a string that corresponds to a valid resource name for the specified widget.  
DECTPU also verifies that the data type of the value you specify is valid for the  
specified resource.  
5.2.6.2 Specifying a List as a Resource Value  
List box and file selection widgets manipulate lists. For example, the file selection  
widget manipulates a list of files. The widget resource that stores such a list is  
specified to DECTPU by using an array.  
To handle an array that passes a list to a widget, DECwindows must know how  
many elements the array contains. For example, if you set the value of the  
"items" resource of a list box widget to point to a given array, DECwindows  
does not handle the array successfully unless the list box widgets "itemsCount"  
resource contains the number of elements in the array.  
However, you do not necessarily know how many elements the array has at a  
given moment. To help you pass arrays, DECTPU has a convention for referring  
to widget resources. If you follow the convention, DECTPU will handle the  
resource that stores the number of array elements.  
The following paragraphs discuss the naming convention in more detail.  
DEC Text Processing Utility Program Development 5–11  
 
DEC Text Processing Utility Program Development  
5.2 Programming in DECwindows DECTPU  
Setting Resources  
When you use the SET (WIDGET) built-in procedure to pass a list to a widget,  
you must specify both the list name and the list count resource in the same array  
index, separated by a line feed (ASCII (10)). The array element should be the  
array that is to be passed. For example, to specify the "items" resource to the list  
box widget, use code similar to the following:  
line_feed := ASCII (10);  
resource_array {"items" + line_feed + "itemsCount"}:=list_array;  
The line-feed character, ASCII (10), is a delimiter that separates two resource  
names.  
DECTPU automatically generates two resource entries. The first is the array of  
strings that specifies the data to the list box for the "items" resource. The second  
is the count of elements in the array for the "itemsCount" resource.  
Getting Resources  
To get resource values from a widget, use the following statement:  
GET_INFO (widget, "WIDGET_INFO", array)  
The indices of the array parameter are strings or string constants that name  
the resources whose values you want. (The initial values in the array are  
unimportant.) The GET_INFO statement directs DECTPU to fetch the specified  
resource values of the specified widget and put the values in the array.  
For list box widgets or file selection widgets, one element of the array receives  
another array that contains the list manipulated by the widget. The indices  
of this array are of type integer. The lowest index has the value 0, and each  
subsequent index is incremented by 1. The contents of the array elements are of  
type string.  
When you create the index of the element that receives the widgets list, you must  
observe the same naming convention as for setting resources so that DECTPU  
can handle both the list itself and the resource value that specifies the length of  
the list. Give the index the following format:  
items<line-feed>items_count  
For example, if you used GET_INFO (widget, "WIDGET_INFO", array) to get  
resource values from a list box widget, you could specify the index for the element  
storing the widgets list as follows:  
"items" + ASCII(10) + "itemsCount"  
The element for the widgets list does not actually contain an array until after  
execution of the GET_INFO statement. When DECTPU encounters the GET_  
INFO statement, it parses the indices of the specified array. When DECTPU  
parses the index of the element for the widgets list, it fetches both the list itself  
and the length of the list. Using the resource specifying the length, DECTPU  
creates an array of the correct size to hold the widgets list.  
See the DEC Text Processing Utility Reference Manual for sample uses of  
DECwindows DECTPU built-ins.  
5–12 DEC Text Processing Utility Program Development  
 
DEC Text Processing Utility Program Development  
5.3 Writing Code Compatible with DECwindows EVE  
5.3 Writing Code Compatible with DECwindows EVE  
This section provides information useful for programmers who extend  
DECwindows EVE or layer applications on DECwindows EVE.  
5.3.1 Select Ranges in DECwindows EVE  
This section is intended for programmers who are extending EVE or layering an  
application on EVE.  
There are four possible types of selection:  
Dynamic selection  
Static selection  
Found range selection  
DECwindows primary or secondary global selection  
EVE can use only one type of selection at a time. The ways in which these  
selections differ are explained in the following sections.  
EVE has a routine called EVE$SELECTION that returns the current selection,  
regardless of whether the selection is dynamic, static, formed from a found  
range, or the primary global selection. You can use the SELECT_RANGE  
built-in procedure to get the current selection if the selection is a dynamic  
selection. However, Compaq recommends that you use EVE$SELECTION to  
get the current selection because this routine returns the current selection  
regardless of how it was created. To see how the EVE$SELECTION routine  
works and what parameters it takes, see the code for this routine in  
SYS$EXAMPLES:EVE$CORE.TPU.  
5.3.1.1 Dynamic Selection  
When you press the Select key or invoke the SELECT command, EVE creates a  
dynamic selection. A dynamic selection expands and contracts as you move the  
text cursor. Moving the text cursor away from the text already selected does not  
cancel the selection. If you use the mouse to start a selection while a dynamic  
selection is active, the dynamic selection is canceled.  
If EVEs current selection is a dynamic selection, the routine EVE$SELECTION  
returns the selected range and terminates the selection. If, for some reason, you  
want to use a statement that returns the current dynamic selection but does not  
terminate it, you can use a statement whose format is similar to the following:  
r1 := EVE$SELECTION (TRUE, TRUE, TRUE, TRUE, FALSE)  
The last parameter directs EVE$SELECTION not to terminate the selection. For  
more information on how to use these parameters, see the EVE$SELECTION  
routine in SYS$EXAMPLES:EVE$CORE.TPU.  
5.3.1.2 Static Selection  
EVE creates a static selection if you do any of the following:  
Click the MB1 mouse button two or more times to select a word, line,  
paragraph, or buffer  
Use the EVE command SELECT ALL  
Press the MB1 mouse button, drag the mouse across text, and then release  
the mouse button  
DEC Text Processing Utility Program Development 5–13  
 
DEC Text Processing Utility Program Development  
5.3 Writing Code Compatible with DECwindows EVE  
Use the MB1 mouse button with the Shift key to extend a selection  
EVE implements a static selection by creating a range upon which you can  
perform EVE commands such as STORE TEXT or REMOVE. However, EVE does  
not use the DECTPU SELECT built-in procedure to start this range. Thus, if  
you use the SELECT_RANGE built-in while a static selection is active, DECTPU  
returns the message No select active.’  
If you move the text cursor off the text in the static selection, the selection is  
canceled.  
5.3.1.3 Found Range Selection  
When EVE positions to the beginning of a range as the result of the FIND  
command, the WILDCARD FIND command, or pressing the Find key, EVE  
creates a found range that contains the text EVE found as a match for your  
search string. If no other selection is active, EVE treats the found range as the  
current selection.  
EVE implements a found range selection by creating a range upon which you  
can perform EVE commands such as STORE TEXT or REMOVE. However, EVE  
does not use the DECTPU SELECT built-in procedure to start this range. Thus,  
if you use the SELECT_RANGE built-in while a found range selection is active,  
DECTPU returns the message No select active.’  
If you move the text cursor off the text in the found range selection, the selection  
is canceled.  
5.3.1.4 Relation of EVE Selection to DECwindows Global Selection  
If EVE has a dynamic selection or a static selection active, that selection is  
automatically designated as the primary global selection. A found range selection  
is not designated as the primary global selection.  
You can use the routine EVE$SELECTION to get the text of the primary global  
selection when an application other than DECTPU owns the selection. To do so,  
the call to EVE$SELECTION must be in code bound to a mouse button other  
than MB1. The value returned is a string that contains the text of the primary  
global selection.  
5.4 Compiling DECTPU Programs  
Before compiling programs in DECTPU, you should enable the display of  
informational messages to help you locate errors. EVE automatically enables  
the display of informational messages for you when you use the EXTEND EVE  
command. For more information on displaying messages, see the description  
of the SET (INFORMATIONAL) built-in procedure in the DEC Text Processing  
Utility Reference Manual.  
The DECTPU compiler numbers the lines of code it compiles. The line numbers  
begin with 1. For a string, all DECTPU statements are considered to be on line  
1. For a range, line 1 is the first line of the range, regardless of where in the  
buffer the range begins. Buffers are numbered starting at the first line. When a  
compilation error occurs, DECTPU tells you the approximate line number where  
the error occurred. To move to the line at which the error occurred, use the  
POSITION (integer) built-in procedure.  
In EVE, you can use the LINE command. For example, the command LINE 42  
moves the editing point and the cursor to line 42.  
5–14 DEC Text Processing Utility Program Development  
 
DEC Text Processing Utility Program Development  
5.4 Compiling DECTPU Programs  
To see DECTPU messages while in EVE, use the BUFFER MESSAGES  
command. To return to the original buffer or another buffer of your choice,  
use the BUFFER name_of_buffer command.  
There are two ways to compile a program in DECTPU: on the command line of  
EVE or in a DECTPU buffer.  
5.4.1 Compiling on the EVE Command Line  
You can compile a simple DECTPU program by entering it on the EVE command  
line. For example, if you use the TPU command and then enter the SHOW  
(SUMMARY) statement, DECTPU compiles and executes the program associated  
with the SHOW (SUMMARY) statement.  
5.4.2 Compiling in a DECTPU Buffer  
DECTPU programs are usually compiled by entering DECTPU procedures and  
statements in a buffer and then compiling the buffer. If you are using EVE,  
you can enter the SHOW (VARIABLES) command in a buffer and compile the  
buffer by using the TPU command and entering the following statement after the  
prompt:  
TPU Statement: COMPILE (CURRENT_BUFFER);  
The program associated with SHOW (VARIABLES) is not executed until you  
enter the following statement:  
TPU Statement: EXECUTE (CURRENT_BUFFER);  
If you use a buffer, a range, or a string as the parameter for the EXECUTE  
built-in procedure, DECTPU first compiles and then executes the buffer, range,  
or string. See the description of EXECUTE in the DEC Text Processing Utility  
Reference Manual.  
The COMPILE built-in procedure optionally returns a program data type. If you  
want to use the program that you are compiling later in your session, you can  
assign the program that is returned to a variable. The following example shows  
how to make this assignment:  
new_program := COMPILE (CURRENT_BUFFER);  
If no error messages are issued while you compile the current buffer, you can  
then execute the program new_program with the following statement:  
EXECUTE (new_program);  
You can use the COMPILE built-in procedure to compile certain parts of a buffer  
rather than a whole buffer. To do so, create a range that includes the statements  
within the buffer that you want compiled, and then specify the range as the  
parameter for COMPILE.  
5.5 Executing DECTPU Programs  
You can use programs that are already compiled as parameters for the EXECUTE  
built-in procedure. In addition, you can use buffers, ranges, or strings that  
contain executable DECTPU statements as parameters for the EXECUTE built-in  
procedure. DECTPU compiles the contents of the buffer, range, or string if  
necessary; then DECTPU executes the compiled buffer, range, or string.  
DEC Text Processing Utility Program Development 5–15  
 
DEC Text Processing Utility Program Development  
5.5 Executing DECTPU Programs  
After using the TPU command, suppose you used the following statement to  
create a program called new_program:  
TPU Statement: new_program := COMPILE (CURRENT_BUFFER);  
You could then execute new_program by using the following statement after using  
the TPU command:  
TPU Statement: EXECUTE (new_program);  
You could also compile and execute the statements in the current buffer by using  
the following TPU statement after using the TPU command:  
TPU Statement: EXECUTE (CURRENT_BUFFER);  
You can enter, compile, and execute small DECTPU programs on the EVE  
command line. The following example shows a small program that you can enter  
after the TPU Statement: prompt.  
TPU Statement: SET (TIMER, ON, "Executing");  
The preceding command executes the program associated with the SET (TIMER)  
built-in procedure and causes the string "Executing" to be displayed at 1-second  
intervals when a long procedure is executing. The string is displayed in the last  
15 spaces of the prompt area at 1-second intervals.  
5.5.1 Procedure Execution  
If you include procedure declarations as part of a program, the procedure is  
compiled and the procedure name is added to the DECTPU list of procedures  
when you execute the program. You invoke the procedure in one of the following  
ways:  
Enter the name of the compiled procedure after the TPU Statement: prompt  
from EVE.  
Call the procedure from within a program or another procedure.  
5.5.2 Process Suspension  
To suspend a process, you can use Ctrl/C.  
Pressing Ctrl/C causes DECTPU to stop the execution of a user-written program.  
You can also stop the execution of the following DECTPU built-in procedures with  
Ctrl/C:  
LEARN_BEGIN . . . LEARN_END (execution of a learn sequence)  
READ_FILE  
SEARCH  
WRITE_FILE  
Caution  
Because DECTPU does not journal Ctrl/C, using Ctrl/C may affect the  
accuracy of your keystroke journal file. In addition, Ctrl/C prevents  
completion of some built-in procedures, such as ERASE_RANGE, MOVE_  
TEXT, and FILL. DECTPU behavior after such an interruption is  
unpredictable. Compaq recommends that you exit from the editor after  
pressing Ctrl/C to ensure that you do not lose any work because of an  
inaccurate keystroke journal file.  
5–16 DEC Text Processing Utility Program Development  
 
DEC Text Processing Utility Program Development  
5.5 Executing DECTPU Programs  
Buffer-change journaling works properly with Ctrl/C. Therefore, if you are  
not using keystroke journaling, exiting from the editor is not necessary.  
For more information on the effects of pressing Ctrl/C, see Section 4.9.4.14 and  
Section 4.9.4.16.  
5.6 Using DECTPU Startup Files  
DECTPU startup files are files that DECTPU reads, compiles, and executes  
during its initialization sequence.  
There are three types of DECTPU startup files:  
Section files  
Command files  
Initialization files  
5.6.1 Section Files  
A section file is the compiled binary form of a file that contains DECTPU source  
code. To direct DECTPU to execute a section file, use the appropriate command  
syntax for your section.  
To execute a section file, use the /SECTION qualifier with the EDIT/TPU  
command or let DECTPU execute the default section file.  
The default section file is TPU$SECTION. When DECTPU tries to locate the  
section file, DECTPU supplies a default directory of SYS$SHARE and a default  
file type of .TPU$SECTION. OpenVMS systems define the system-wide logical  
name TPU$SECTION as EVE$SECTION, so the default section file is the file  
that implements the EVE editor. To override the OpenVMS default, redefine  
TPU$SECTION.  
For more information on the /SECTION qualifier, see Section 2.6.13.  
5.6.2 Command Files  
A command file contains a series of DECTPU procedures followed by a sequence  
of TPU statements. To direct DECTPU to compile and execute a command file,  
use the appropriate command syntax, as explained in this section.  
To specify a DECTPU command file, use either the /COMMAND qualifier with the  
EDIT/TPU command or let DECTPU compile and execute the default command  
file.  
The default command file is TPU$COMMAND. When DECTPU tries to locate  
the command file, it supplies a default file type of .TPU. To direct DECTPU  
to compile and execute a particular command file, define the logical name  
TPU$COMMAND to be the file you want DECTPU to use. For more information  
on the /COMMAND qualifier, see Section 2.6.2.  
DEC Text Processing Utility Program Development 5–17  
 
DEC Text Processing Utility Program Development  
5.6 Using DECTPU Startup Files  
5.6.3 Initialization Files  
An initialization file contains commands to be executed by an application layered  
on DECTPU. To specify an initialization file to be executed, use the appropriate  
command syntax, as explained in this section.  
DECTPU does not determine the default handling of an initialization file; nor  
does DECTPU directly load or execute the commands in an initialization file. The  
application layered on DECTPU must determine the defaults and must handle  
the loading and execution of an initialization file. For example, EVE reads an  
initialization file (if one is present) and interprets the initialization commands  
when it processes the appropriate initialization file. Any key definitions in an  
initialization file override corresponding key definitions saved in a section file and  
key definitions in a command file.  
Typically, you use EVE initialization files to set values that are not usually saved  
in a section file, such as margins, tab stops, and bound or free cursor. For a  
list of the EVE default values that you might want to modify by using an EVE  
initialization file, see the Extensible Versatile Editor Reference Manual.  
To use an initialization file, use the /INITIALIZATION qualifier with the  
EDIT/TPU command. For more information on the /INITIALIZATION qualifier,  
see Section 2.6.6.  
5.6.4 Sequence in Which DECTPU Processes Startup Files  
When you invoke DECTPU, by default DECTPU reads, compiles, and executes  
several files. The sequence in which DECTPU performs these tasks is as follows:  
1. DECTPU loads into memory the specified or default section file unless you  
specify the /NOSECTION qualifier on the command line.  
2. DECTPU reads the specified or default command file, if found, into a buffer  
named $LOCAL$INI$ unless you specify the /NOCOMMAND qualifier on the  
command line.  
3. If you specify the /DEBUG qualifier on the command line, DECTPU reads  
the specified or default debugger file into a buffer named $DEBUG$INI$. A  
debugger file contains DECTPU procedures and statements to help debug  
DECTPU code. For more information on the default DECTPU debugger, see  
Section 5.7.  
4. If the buffer named $DEBUG$INI$ (which contains debugger code) is present,  
DECTPU compiles the buffer and executes the resulting program.  
5. DECTPU calls and executes the procedure named TPU$INIT_PROCEDURE  
if the procedure is present in the section file or is defined in the debug file.  
6. If the command file is read into the buffer named $LOCAL$INI$, DECTPU  
compiles that buffer and executes the resulting program.  
7. DECTPU calls and executes the procedure named  
TPU$INIT_POSTPROCEDURE if the layered application has defined this  
procedure in the section file, debug file, or command file.  
If a layered application makes use of an initialization file, it is the responsibility  
of the application to define when the initialization file is processed. EVE  
processes initialization files during the TPU$INIT_POSTPROCEDURE phase.  
5–18 DEC Text Processing Utility Program Development  
 
DEC Text Processing Utility Program Development  
5.6 Using DECTPU Startup Files  
5.6.5 Using Section Files  
A section file is the binary form of a program that implements a DECTPU-based  
editor or application. It is a collection of compiled DECTPU procedure definitions,  
variable definitions, and key bindings. The advantage of using a binary file is  
that the source code does not have to be compiled each time you invoke the editor  
or application, so startup performance is improved.  
5.6.5.1 Creating and Processing a New Section File  
To create a section file, begin by writing a program in the DECTPU language.  
The program must adhere to all the programming conventions discussed  
throughout this manual. For examples of programs used to create a section  
file, see the files in the directory SYS$EXAMPLES. This directory contains the  
sources used to create the EVE section file. To see a list of the EVE source files,  
type the following:  
$ DIR SYS$EXAMPLES:EVE$*.TPU  
If you cannot find these files on your system, see your system manager.  
When writing the DECTPU program that implements your application, place your  
initializing statements in a procedure named TPU$INIT_PROCEDURE. Such  
statements might create buffers, create windows, associate windows with buffers,  
set up screen attributes, initialize variables, define how the journal facility works,  
and so on. You can put the procedure TPU$INIT_PROCEDURE anywhere  
in the procedure declaration portion of your program. DECTPU executes  
TPU$INIT_PROCEDURE before executing the command file (if there is one).  
For more information on DECTPUs initialization sequence, see Section 5.6.4.  
Place any statements that implement or handle initialization files in a procedure  
named TPU$INIT_POSTPROCEDURE. DECTPU executes this procedure  
after both the TPU$INIT_PROCEDURE and the command file have been  
executed. This enables commands or definitions in the initialization file to modify  
commands or definitions in the command file. EVE defines both TPU$INIT_  
PROCEDURE and TPU$INIT_POSTPROCEDURE procedures. For more  
information on how EVE implements initialization files, see Section 5.6.7.  
After you put the desired DECTPU procedures and statements into the  
program that implements your application, end your program with the following  
statements:  
A statement that contains the SAVE built-in procedure. SAVE is the  
mechanism by which you store all currently defined procedures, variables,  
and bound keys in binary form.  
The QUIT built-in procedure. QUIT ends the DECTPU session.  
For more information on SAVE and QUIT, see the descriptions of these built-ins  
in the DEC Text Processing Utility Reference Manual. For examples of files that  
use these statements, see Example 5–4 and Example 5–5.  
To compile your program into a section file, invoke DECTPU but do not supply  
as a parameter the name of a file to be edited. Use the /NOSECTION qualifier  
to indicate that no existing section file should be loaded. Use the /COMMAND  
qualifier to specify the file that contains your program. For example, to create a  
section file from a program in a file called my_application.tpu, enter the following  
at the DCL prompt:  
$ EDIT/TPU/NOSECTION/COMMAND=my_application.tpu  
DEC Text Processing Utility Program Development 5–19  
 
DEC Text Processing Utility Program Development  
5.6 Using DECTPU Startup Files  
This command causes DECTPU to write the binary form of the file MY_  
APPLICATION.TPU to the file you specified as the parameter to the SAVE  
statement in your program. To use the section file, invoke DECTPU, specifying  
your section file.  
For more information on invoking DECTPU, see Chapter 2.  
5.6.5.2 Extending an Existing Section File  
To extend an existing section file, begin by writing a program in the DECTPU  
language.  
If you are extending the EVE section file, put your initializing statements in  
an initialization procedure called TPU$LOCAL_INIT. TPU$LOCAL_INIT is  
an empty procedure in the EVE section file. When you add your DECTPU  
statements and procedures to the EVE section file, your procedure named  
TPU$LOCAL_INIT supersedes EVEs original empty value of TPU$LOCAL_INIT.  
TPU$LOCAL_INIT is called at the end of the procedure TPU$INIT_  
PROCEDURE during the initialization sequence. For more information on the  
initialization sequence, see Section 5.6.4.  
If you are extending a non-EVE section file, you must determine whether that  
section file has implemented the convention of including a TPU$LOCAL_INIT  
procedure.  
After adding DECTPU procedures and statements that implement your  
application, end your program with the following statements:  
A statement that contains the SAVE built-in procedure. SAVE is the  
mechanism by which you store all currently defined procedures, variables,  
and bound keys in binary form.  
The QUIT built-in procedure. QUIT ends the DECTPU session.  
For more information on SAVE and QUIT, see the descriptions of these built-ins  
in the DEC Text Processing Utility Reference Manual.  
Example 5–4 shows the syntax of a program that could be used to create a section  
file.  
Example 5–4 Sample Program for a Section File  
PROCEDURE tpu$local_init  
.
.
.
ENDPROCEDURE;  
PROCEDURE vt100_keys  
.
.
.
ENDPROCEDURE;  
vt100_keys; !Call the procedure that defines the keys  
SAVE ("vt100ini.tpusection");  
QUIT;  
To add your program to an existing section file, invoke DECTPU but do not  
supply as a parameter the name of a file to be edited. Use the /SECTION  
qualifier to specify the section file to which you want to add your program.  
Use the /COMMAND qualifier to specify the file that contains your program.  
5–20 DEC Text Processing Utility Program Development  
 
DEC Text Processing Utility Program Development  
5.6 Using DECTPU Startup Files  
For example, to add a program called MY_CUSTOMIZATIONS.TPU to the EVE  
section file, you would enter the following:  
$ EDIT/TPU/SECTION=EVE$SECTION/COMMAND=my_customizations.tpu  
This command causes DECTPU to load the EVE section file and then read,  
compile, and execute the command file you specify. A new section file is created.  
The new file includes both the EVE section file and the binary form of your  
program. The section file is written to the file you specified as the parameter to  
the SAVE statement in your program. To use the section file, invoke DECTPU,  
specifying your section file.  
For more information on invoking DECTPU, see Chapter 2.  
For more information on extending the EVE section file, see the Extensible  
Versatile Editor Reference Manual.  
5.6.5.3 Sample Section File  
If you choose to design an application layered on DECTPU and not layered on  
EVE, you must provide certain basic structures and key definitions to be able to  
use the DECTPU compiler and interpreter. Example 5–5 is a sample of the source  
code that creates a minimal interface. It provides the following basic structures:  
A buffer and a window for DECTPU messages  
A buffer and a window for information from the SHOW built-in procedure  
A buffer and a window in which to enter DECTPU programs or text  
A prompt area in which to enter DECTPU commands  
Because DECTPU does not have any keys defined when invoked without a section  
file, the sample program also contains the following key definitions:  
Return key  
Delete key  
Key for exiting from DECTPU  
Key for entering DECTPU statements (Example 5–5 uses the Tab key)  
By default, DECTPU looks for TPU$INIT_PROCEDURE, so the statements  
that create the structures for a minimal interface are contained in TPU$INIT_  
PROCEDURE. Individual statements that define keys come after any procedures  
in the file.  
If you entered the text from Example 5–5 into a file named MINI.TPU and you  
want to compile that file into a section file, enter the following command:  
$ EDIT/TPU/NOSECTION/COMMAND=MINI.TPU  
In the previous example, the /NOSECTION qualifier specifies that DECTPU does  
not read a section file. This ensures that none of the procedures or variables  
from an existing section file are loaded into the internal DECTPU tables.  
The /COMMAND qualifier specifies that DECTPU compiles the command file  
MINI.TPU. The SAVE built-in procedure at the end of the command file specifies  
that all of the procedures, variables, and key definitions in the file are to be  
saved in binary form in SYS$LOGIN:MINI.TPU$SECTION. The QUIT built-in  
procedure then causes you to leave DECTPU.  
Example 5–5 contains the source code for a command file that you can use for a  
minimal interface to DECTPU.  
DEC Text Processing Utility Program Development 5–21  
 
DEC Text Processing Utility Program Development  
5.6 Using DECTPU Startup Files  
Example 5–5 Source Code for Minimal Interface to DECTPU  
! MINI.TPU - minimal DECTPU interface  
PROCEDURE tpu$init_procedure  
! Create a buffer and window for messages  
message_buffer := CREATE_BUFFER ("Message Buffer");  
SET (NO_WRITE, message_buffer);  
SET (SYSTEM, message_buffer);  
SET (EOB_TEXT, message_buffer, "");  
message_window := CREATE_WINDOW (21, 4, OFF);  
MAP (message_window, message_buffer);  
! Create a buffer and window for SHOW  
show_buffer := CREATE_BUFFER("Show Buffer");  
SET (NO_WRITE, show_buffer);  
SET (SYSTEM, show_buffer);  
info_window := CREATE_WINDOW (1, 20, ON);  
! Create a buffer and window for editing  
main_buffer := CREATE_BUFFER ("Main Buffer");  
main_window := CREATE_WINDOW (1, 20, ON);  
MAP (main_window, main_buffer);  
! Create an area on the screen for prompts  
SET (PROMPT_AREA, 21, 1, NONE);  
!Put the editing point in the main buffer  
POSITION (main_buffer);  
tpu$local_init;  
ENDPROCEDURE;  
PROCEDURE tpu$local_init  
ENDPROCEDURE;  
!Procedure to allow end users  
!to add private extensions  
! Define the minimal editing keys:  
DEFINE_KEY ("SPLIT_LINE", RET_KEY);  
DEFINE_KEY ("ERASE_CHARACTER(-1)", DEL_KEY);  
DEFINE_KEY ("EXECUTE(READ_LINE(’DECTPU Statement: ’))", TAB_KEY);  
DEFINE_KEY ("EXIT", Ctrl_Z_KEY);  
! Create a section file and then quit  
IF (get_info/system,("operating_system")=ULTRIX)  
THEN  
save(’/usr/user/jacki/mini.tpu_section’);  
ELSE  
save(’sys$login.mini);  
ENDIF  
QUIT;  
! End of MINI.TPU  
If you created the section file SYS$LOGIN:MINI.TPU$SECTION, you could use  
the procedures and definitions in that file as an interface to DECTPU. To invoke  
DECTPU with SYS$LOGIN:MINI.TPU$SECTION as the MINI section file, use  
the following command:  
$ EDIT/TPU/SECTION=SYS$LOGIN:MINI your_text.fil  
You can define the logical name TPU$SECTION to point to your section file. By  
default, DECTPU looks for a file that TPU$SECTION points to and reads that  
file as the default section file.  
5–22 DEC Text Processing Utility Program Development  
 
DEC Text Processing Utility Program Development  
5.6 Using DECTPU Startup Files  
Whenever you want to add new procedures, variables, learn sequences, or key  
definitions to a section file, edit the command file to include the new items, and  
then recompile the command file to produce a section file with the new items. For  
example, if you want to add key definitions for the arrow keys, you could edit the  
file MINI.TPU and add the following statements after any procedures in the file:  
DEFINE_KEY ("MOVE_VERTICAL (-1)", UP);  
DEFINE_KEY ("MOVE_VERTICAL (1)",  
DOWN);  
DEFINE_KEY ("MOVE_HORIZONTAL (1)", RIGHT);  
DEFINE_KEY ("MOVE_HORIZONTAL (-1)", LEFT);  
Recompile the command file with the following command:  
$ EDIT/TPU/NOSECTION/COMMAND=MINI.TPU  
After you have completed the previous steps, you can use the section file you  
created to invoke DECTPU with the new key definitions included.  
An alternate way of adding these key definitions to your section file is to enter  
the definitions as text in the current buffer. You could then press the Tab key (the  
command prompt key for the minimal interface) and enter the following command  
after the prompt:  
TPU Statement: EXECUTE (CURRENT_BUFFER);  
This causes the new key definitions to be added to your current editing context.  
To add the definitions to the section file so you can use them in future sessions,  
enter the following statement at the Command prompt:  
Command: SAVE ("sys$login:mini");  
If you want to save the DECTPU source code for the key definitions, write out the  
current buffer or use the EXIT built-in procedure to leave the DECTPU session  
so that the contents of the buffer are written to a file.  
5.6.5.4 Recommended Conventions for Section Files  
A section file that implements a layered application should include the following  
procedures:  
TPU$INIT_PROCEDURE  
TPU$LOCAL_INIT  
If your application is to support initialization files, the section file that  
implements the application should also include a procedure called TPU$INIT_  
POSTPROCEDURE. This procedure should contain the DECTPU statements that  
implement or handle the initialization files.  
For information on EVEs implementation of initialization files, see Section 5.6.7.  
The TPU$INIT_PROCEDURE procedure should perform the following operations:  
Initialize all global variables to their startup values  
Create all required work spaces for the editor (see the list of special purpose  
buffers and windows in Table 5–2)  
You can add other functions to TPU$INIT_PROCEDURE, but it should perform  
at least these two operations.  
If your application allows the end user to customize the application by using a  
command file, you may want to make available to the user a procedure called  
TPU$LOCAL_INIT. (Although this name is not required, it is commonly used by  
DECTPU programmers.)  
DEC Text Processing Utility Program Development 5–23  
 
DEC Text Processing Utility Program Development  
5.6 Using DECTPU Startup Files  
In EVE, the code that implements the initialization sequence calls  
TPU$LOCAL_INIT before executing your command or initialization files. EVE  
defines this procedure but leaves it empty. The user can use this procedure  
in a command file to contain DECTPU statements that implement private  
initializations.  
You can see the code that implements TPU$LOCAL_INIT in EVE in  
SYS$EXAMPLES:EVE$CORE.TPU.  
A section file that implements a layered application should assign values to the  
following special variables in the procedure TPU$INIT_PROCEDURE:  
TPU$X_MESSAGE_BUFFER or MESSAGE_BUFFER  
TPU$X_SHOW_BUFFER or SHOW_BUFFER  
TPU$X_SHOW_WINDOW or INFO_WINDOW  
If you write a section file that extends the EVE section file, EVE provides six  
variables (three pairs of synonyms) to be used by layered applications. Although  
DECTPU automatically declares the variables, the application must assign a  
value to one of the synonyms in each pair. If you choose to write your own  
application, your application must contain these structures and procedures.  
Table 5–2 shows the names and uses of these variables.  
Table 5–2 Special DECTPU Variables That Require a Value from a Layered Application  
Synonym Provided  
for Backward  
Compatibility  
Data Type  
Structure  
Recommended Name  
How DECTPU Uses the Variable  
TPU$X_MESSAGE_  
BUFFER  
MESSAGE_BUFFER  
Buffer  
DECTPU writes messages in this buffer. If the  
MESSAGE_BUFFER is associated with a window  
that is mapped to the screen, DECTPU updates the  
window. If the application does not assign a buffer  
to this variable, DECTPU writes messages to the  
screen.  
TPU$X_SHOW_  
BUFFER  
SHOW_BUFFER  
INFO_WINDOW  
Buffer  
DECTPU writes information stored by the SHOW  
built-in in this buffer.  
TPU$X_SHOW_  
WINDOW  
Window  
DECTPU displays information stored by the SHOW  
built-in in this window.  
If you want to use the SHOW built-in procedure in your application, you must  
create these special variables that DECTPU uses for SHOW.  
5.6.6 Using Command Files  
A com m a n d file is a DECTPU source file that can contain procedures, key  
definitions, and other DECTPU executable statements. You can have any number  
of command files in your directory. You might want to write one command file  
that customizes your editor for programming in Pascal, another command file  
that customizes your editor for text editing, and so on. If you have several  
command files, give them names that remind you of their contents. If you have  
one command file that you use most of the time, name it TPU$COMMAND.TPU.  
The command to invoke DECTPU with a command file is:  
$ EDIT/TPU/COMMAND [[= filespec]]  
5–24 DEC Text Processing Utility Program Development  
 
DEC Text Processing Utility Program Development  
5.6 Using DECTPU Startup Files  
If you name your command file TPU$COMMAND.TPU and it is in your  
default directory, DECTPU reads the file by default, without your having to  
use the /COMMAND qualifier. If you name your file something other than  
TPU$COMMAND.TPU, or if you put it in a directory other than your default  
directory, you must use the /COMMAND qualifier explicitly and provide a full file  
specification after the qualifier.  
DECTPU reads a command file, compiles it, and executes any commands that do  
not contain syntax errors. If there are errors, DECTPU writes an error message  
to the message area. The command file can customize or extend the application  
implemented by the section file with which you invoked DECTPU.  
Example 5–6 is a sample DECTPU command file that defines a procedure that  
moves the editing point to the beginning of a segment of text delimited by the  
characters %(/ * at the beginning and */ )% at the end.  
Example 5–6 Command File for GOTO_TEXT_MARKER  
PROCEDURE goto_text_marker  
LOCAL text_marker_pattern,  
text_marker_range;  
text_marker_pattern := ’%(/*’ + MATCH (’*/)%’);  
text_marker_range := SEARCH_QUIETLY (text_marker_pattern,  
GET_INFO (CURRENT_BUFFER, "direction"));  
IF text_marker_range <> 0  
THEN  
POSITION (text_marker_range);  
ELSE  
MESSAGE ("Text_marker not found");  
ENDIF;  
RETURN text_marker_range;  
ENDPROCEDURE;  
If you name the file that contains this procedure TEXT_MARKERS.TPU, you can  
invoke DECTPU with EVE and your command file with the following command:  
$ EDIT/TPU/COMMAND=device:[directory]text_markers.tpu  
If you add procedures or statements to the command file TEXT_MARKERS.TPU,  
place all procedures before any individual statements that are not listed within a  
procedure (for example, key definitions to move to the next text marker).  
Remember to name your variables and procedures so they do not conflict with  
DECTPU reserved words and predefined identifiers. Compaq recommends that  
you prefix your variable and procedure names with three letters (your initials, for  
example) followed by an underscore ( _ ).  
5.6.7 Using EVE Initialization Files  
An in itia liza tion file is a file that contains commands to be executed by an  
application. Any application layered on DECTPU can support initialization files.  
With EVE initialization files, you can do the following:  
Use EVE commands in a startup file to customize editing sessions  
DEC Text Processing Utility Program Development 5–25  
 
DEC Text Processing Utility Program Development  
5.6 Using DECTPU Startup Files  
Set formats for individual buffers  
EVE initialization files contain EVE commands that are executed either when  
you invoke the editor or when you issue the EVE @ (at sign) command.  
To create an EVE initialization file, put in the file the EVE commands you  
want to use to customize the editor. Use one command on each line and one  
line for each command. Do not separate the commands with semicolons. If a  
command in an EVE initialization file is incomplete, EVE prompts you for more  
information, the same as if you were typing the command during an editing  
session. Comments in EVE initialization files must be on lines separate from  
commands and must begin with an exclamation point (!). You cannot nest EVE  
initialization files. Do not use the DO command in an EVE initialization file.  
The following sample initialization file sets left and right margins, establishes  
overstrike mode, binds the QUIT command to the GOLD/Q key sequence, and  
enables an EDT-like keypad:  
SET LEFT MARGIN 5  
SET RIGHT MARGIN 60  
OVERSTRIKE MODE  
DEFINE KEY=gold/q QUIT  
SET KEYPAD EDT  
5.6.7.1 Using an EVE Initialization File at Startup  
You can cause an initialization file to be executed in any of the following ways  
when you invoke EVE:  
Name the file EVE$INIT.EVE. This is the default file name for EVE  
initialization files.  
Specify the name of the initialization file as a qualifier to the EDIT/TPU  
command.  
Define a logical name, EVE$INIT, to point to your initialization file.  
The first and third methods are appropriate if you intend to use one initialization  
file most of the time to customize your editing sessions. If you name the  
file EVE$INIT.EVE and do not specify another EVE initialization file on the  
command line, EVE automatically executes that file when you invoke DECTPU.  
Use the second method to control which initialization file EVE executes to  
customize the editing session. For example, if you have an EVE$INIT file  
but want to use another initialization file, specify the other file by using the  
/INITIALIZATION qualifier to EDIT/TPU. To specify an initialization file called  
MY_INIT.EVE, enter the following command string on the command line:  
$ EDIT/TPU/INITIALIZATION=MY_INIT.EVE  
EVE always executes the initialization file specified on the command line, if such  
a file is present. If no file is specified on the command line, EVE searches for  
EVE$INIT.EVE first in the current directory and then in your login area. If EVE  
finds EVE$INIT.EVE, it executes that file. If the file is not found, the editor  
checks whether the logical name EVE$INIT has been defined.  
If you plan to create several initialization files and to use them equally, you  
may not want to name one of the files EVE$INIT. For example, if you want one  
initialization file to set narrow margins and another to set wide margins, create  
both files and specify the file you want when you invoke EVE.  
5–26 DEC Text Processing Utility Program Development  
 
DEC Text Processing Utility Program Development  
5.6 Using DECTPU Startup Files  
5.6.7.2 Using an EVE Initialization File During an Editing Session  
To execute an EVE initialization file during an editing session, use the @ (at sign)  
command and specify the file. For example, the following command executes an  
initialization file called MYEVE.EVE in your current (default) directory.  
Command: @MYEVE  
Commands for buffer settings apply to the current buffer. This is effectively the  
same as typing the commands that the file contains. You may want to create  
initialization files to execute two or more related commands, such as resetting  
both margins.  
5.6.7.3 How an EVE Initialization File Affects Buffer Settings  
Commands in an EVE initialization file that set buffer characteristics (such as  
margins and tab stops) affect a system buffer named $DEFAULTS$. Buffers  
created during the editing session have the same settings as $DEFAULTS$. For  
example, if your initialization file contains the command SET RIGHT MARGIN  
65, the value 65 is used as the right margin setting for the main buffer and for  
any buffers you create during the session with GET FILE or BUFFER commands.  
To see the settings for the $DEFAULTS$ buffer, use the EVE command SHOW  
DEFAULTS BUFFER. For example, if you want to know what the tab settings  
are for the $DEFAULTS$ buffer, type the following command:  
Command: SHOW DEFAULTS BUFFER  
This command causes EVE to show buffer information in a format similar to the  
format in Example 5–7 (using values that apply to your editing session).  
Example 5–7 SHOW DEFAULTS BUFFER Display  
EVE V3.1 1993-08-17 08:47  
Information about buffer $DEFAULTS$  
Not modified  
Mode: Insert  
Paragraph indent: none  
Read-only  
Left margin set to: 1  
Right margin set to: 79  
WPS word wrap indent: none  
Unmodifiable  
Direction: Forward  
Max lines: no limit  
Tab stops set every 8 columns.  
Word wrap: on  
To change the characteristics of the $DEFAULTS$ buffer during an editing  
session, use the command BUFFER $DEFAULTS$ to put the defaults buffer in a  
window. This buffer is empty and you cannot add text to it. However, when you  
change the settings of the $DEFAULTS$ buffer, the changes are saved and used  
to set the characteristics of any user buffers you create.  
Use commands such as SET RIGHT MARGIN, SET LEFT MARGIN, SET TABS,  
FORWARD, REVERSE, INSERT, or OVERSTRIKE to change the characteristics  
of the $DEFAULTS$ buffer. The new characteristics are applied to new buffers  
but not to existing ones. To leave the $DEFAULTS$ buffer and put a different  
buffer in the window, use the BUFFER command.  
DEC Text Processing Utility Program Development 5–27  
 
DEC Text Processing Utility Program Development  
5.7 Debugging DECTPU Programs  
5.7 Debugging DECTPU Programs  
This section discusses the options you have for debugging DECTPU programs.  
To debug DECTPU programs, you can do one of the following:  
Write your own debugger in the DECTPU language. This is discussed in  
Section 5.7.1.  
Use the DECTPU debugger provided in TPU$DEBUG.TPU. This is discussed  
in Section 5.7.2.  
Regardless of which debugger you use, you may find it helpful to enable  
the display of error line numbers by using SET (LINE_NUMBER, ON) and  
to enable the display of procedures called when an error occurs by using  
SET (TRACEBACK, ON).  
5.7.1 Using Your Own Debugger  
If you write your own debugger, you can invoke it (and bypass the default bugger)  
by using the /DEBUG qualifier with the EDIT/TPU command. For example,  
to use a debugger called MY_DEBUGGER.TPU on a file called MIGHT_BE_  
BUGGY.TPU, type the following:  
$ EDIT/TPU/DEBUG=MY_DEBUGGER.TPU MIGHT_BE_BUGGY.TPU  
5.7.2 Using the DECTPU Debugger  
You can invoke the DECTPU debugger to debug one of the following kinds of files:  
Section files  
Command files  
Files that contain DECTPU programs that are not startup programs  
The following sections contain more information on debugging each kind of file.  
5.7.2.1 Debugging Section Files  
To invoke the debugger for a section file, specify the following command on your  
command line:  
$ EDIT/TPU/DEBUG  
Use of your systems debug command causes the DECTPU initialization routine  
to execute the debugger file before the system runs its initialization procedure.  
The debugger initially creates a window that fills most of the screen. The window  
consists of the following three areas:  
Source area—Displays your code when it has been placed in the debugger  
source buffer.  
Output areaDisplays one-line messages or one-line results of an EXAMINE  
command.  
Debug command line—Displays the Debug: prompt.  
When DECTPU displays the debug window, you can set breakpoints in the  
section file by using the SET BREAKPOINT command. For example, if you  
want to debug a procedure called user_fum, type the following on the debugger  
command line:  
Debug: SET BREAKPOINT user_fum  
5–28 DEC Text Processing Utility Program Development  
 
DEC Text Processing Utility Program Development  
5.7 Debugging DECTPU Programs  
After setting breakpoints, use the GO command to switch control of execution  
from the debugger to DECTPU. After you have used this command, the screen  
displays the code you specified.  
5.7.2.2 Debugging Command Files  
To invoke the debugger on a command file, use the /DEBUG, /COMMAND, and  
/NOSECTION qualifiers. To debug a command file called MY_COMMANDS.TPU,  
type the following at the DCL prompt:  
$ EDIT/TPU/NOSECTION/COMMAND=MY_COMMANDS.TPU/DEBUG  
DECTPU compiles and executes the debugger and places the debug window  
on the screen before compiling the command file. As a result, you must set  
breakpoints in the command file before it has been compiled. When you set  
breakpoints, DECTPU notifies you that you have specified breakpoints at  
nonexistent procedures.  
To continue with the debugging session, use the GO command. GO causes  
DECTPU to compile the contents of the command file. Recompiling a procedure  
does not remove any breakpoints set in that procedure.  
You cannot use the DECTPU debugger on a file that does not contain DECTPU  
procedures. If your command file does not contain any procedures, you must find  
a different method of debugging it.  
5.7.2.3 Debugging Other DECTPU Source Code  
To debug a DECTPU program that is not a section file or a command file, use the  
/DEBUG qualifier when you invoke DECTPU. For example, to debug procedures  
in a file called USER_APPLICATION.TPU, invoke the debugger on the command  
line as follows:  
$ EDIT/TPU/DEBUG USER_APPLICATION.TPU  
The debugger creates a window that fills the screen as described in  
Section 5.7.2.1.  
5.7.3 Getting Started with the DECTPU Debugger  
This section describes using the default DECTPU debugger with EVE.  
If you know which parts of the code you want to debug, use the SET  
BREAKPOINT command to set breakpoints. If you need to look at the code  
before setting breakpoints, use the GO command as soon as the debugger  
window appears. This places on the screen the code in the file you specified  
on the command line. At this point, EVE commands are available so you can  
manipulate the text. To return to the debugger so you can set breakpoints, enter  
the command DEBUG at the EVE command line. You can also gain access to  
the debugger with the DECTPU procedure called DEBUGON. To invoke this  
procedure from within EVE, type the following at the EVE Command prompt:  
Command: TPU DEBUGON  
When you use either DEBUG or DEBUGON, the screen displays the debugger  
window and command line. After setting breakpoints, use the GO command to  
return control of execution to DECTPU.  
DEC Text Processing Utility Program Development 5–29  
 
DEC Text Processing Utility Program Development  
5.7 Debugging DECTPU Programs  
To compile all code in the buffer, use the EXTEND ALL command or use the  
COMPILE (CURRENT_BUFFER) statement. To execute a procedure after  
compilation, use the TPU command. For example, if you want to execute the  
compiled procedure user_fum, type the following at the EVE Command prompt:  
Command: TPU user_fum  
When DECTPU encounters a breakpoint (or when you use the STEP command  
described later), DECTPU invokes the debugger program. As the debugger  
assumes control, it receives from DECTPU the name of the procedure whose  
execution has been suspended. The debugger searches its source buffer for that  
procedure.  
When DECTPU encounters the first breakpoint in the session, the code you are  
debugging has not yet been placed in the debugger s source buffer. The debugger  
prompts for the name of the file that contains your code. Using your response,  
the debugger places your code in its source buffer. The debugger uses your  
previous response to supply missing fields, if any, in subsequent file names that  
you specify. All files read into the source buffer remain there, so that the time  
DECTPU takes to find a procedure may increase as more files are read into the  
source buffer.  
You cannot use the TPU command followed by the MESSAGE built-in procedure  
to examine the contents of a local variable while debugging. To use the  
MESSAGE built-in to examine a local variable, you must write the MESSAGE  
built-in into the procedure you are debugging. After the statement that contains  
MESSAGE is executed, you can examine the message buffer to see the results.  
Alternatively, you can use the debugger EXAMINE command to examine local  
variables and the formal parameters of the suspended procedure.  
5.8 Handling Errors  
Each DECTPU built-in procedure returns one or more status codes telling you  
what happened when the built-in was executed. A DECTPU status code can have  
one of the following severity levels:  
SUCCESS  
INFORMATIONAL  
WARNING  
ERROR  
FATAL  
You can enable or disable the display of informational or success messages with  
the SET (INFORMATIONAL) and SET (SUCCESS) built-in procedures.  
See Chapter 4 for a description of how to use the ON_ERROR language statement  
to trap error and warning messages.  
In addition to messages that are generated by DECTPU, a built-in procedure may  
return system messages.  
5–30 DEC Text Processing Utility Program Development  
 
A
Sample DECTPU Procedures  
The following DECTPU procedures are samples of how to use DECTPU to  
perform certain tasks. These procedures show one way of using DECTPU; there  
may be other, more efficient ways to perform the same task. Make changes to  
these procedures to accommodate your style of editing.  
For these procedures to compile and execute correctly, you must make sure that  
there are no conflicts between these sample procedures and your interface. This  
appendix contains the following types of procedures:  
1. Line-mode editor  
2. Translation of control characters  
3. Restoring terminal width before exiting from DECTPU  
4. DCL command procedure to run DECTPU from a subprocess  
A.1 Line-Mode Editor  
Example A–1 shows a portion of an editing interface that uses line mode rather  
than screen displays for editing tasks. You can use this mode of editing for batch  
jobs or for running DECTPU on terminals that do not support screen-oriented  
editing.  
Example A–1 Line-Mode Editing  
! Portion of a line mode editor for DECTPU  
!
input_file := GET_INFO (COMMAND_LINE, "file_name"); ! Set up main  
main_buffer := CREATE_BUFFER ("MAIN", input_file);  
! buffer from input  
POSITION (BEGINNING_OF (main_buffer));  
!
! file  
LOOP  
! Continuously loop until QUIT  
cmd := READ_LINE ("*");  
IF cmd = ""  
THEN  
cmd_char := "N";  
ELSE  
cmd_char := SUBSTR (cmd, 1, 1); CHANGE_CASE (cmd_char, UPPER);  
ENDIF;  
CASE cmd_char FROM "I" TO "T"  
! Only accepting I,L,N,Q,T  
(continued on next page)  
Sample DECTPU Procedures A–1  
 
Sample DECTPU Procedures  
A.1 Line-Mode Editor  
Example A–1 (Cont.) Line-Mode Editing  
!Top of buffer command  
["T"]:  
POSITION (BEGINNING_OF (CURRENT_BUFFER));  
MESSAGE (CURRENT_LINE);  
!Next line command  
["N"]:  
MOVE_HORIZONTAL (-CURRENT_OFFSET);  
MOVE_VERTICAL (1);  
MESSAGE (CURRENT_LINE);  
!Insert text command  
["I"]:  
SPLIT_LINE;  
COPY_TEXT (SUBSTR (cmd, 2, 999));  
MESSAGE (CURRENT_LINE);  
!List from here to end of file command  
["L"]:  
m1 := MARK (NONE);  
LOOP  
MESSAGE (CURRENT_LINE);  
MOVE_VERTICAL (1);  
EXITIF MARK (NONE) = END_OF (CURRENT_BUFFER);  
ENDLOOP;  
POSITION (m1);  
!QUIT  
["Q"]:  
QUIT;  
[INRANGE,OUTRANGE]:  
MESSAGE ("Unrecognized command - enter I,L,N,Q or T");  
ENDCASE;  
ENDLOOP;  
A.2 Translation of Control Characters  
Example A–2 shows how to display control characters in a meaningful way.  
This is accomplished by translating the buffer to a different visual format and  
mapping this new form to a window. On the VT400, VT300, and VT200 series of  
terminals, control characters are shown as reverse question marks; on the VT100  
series of terminals, they are shown as rectangles.  
Example A–2 Procedure to Display Control Characters  
! This procedure performs the substitution of meaningful characters  
! for the escape or control characters.  
!
PROCEDURE translate_controls (char_range)  
LOCAL  
replace_text;  
!
! If the translation array is not yet set up, then do it now. The elements  
! that we do not initialize will contain the value TPUK_UNSPECIFIED. They are  
! characters that TPU will display meaningfully.  
!
IF translate_array = TPU$K_UNSPECIFIED  
THEN  
(continued on next page)  
A–2 Sample DECTPU Procedures  
 
Sample DECTPU Procedures  
A.2 Translation of Control Characters  
Example A–2 (Cont.) Procedure to Display Control Characters  
translate_array := CREATE_ARRAY (32, 0);  
translate_array {1} := ’<SOH>’;  
translate_array {2} := ’<STX>’;  
translate_array {3} := ’<ETX>’;  
translate_array {4} := ’<EOT>’;  
translate_array {5} := ’<ENQ>’;  
translate_array {6} := ’<ACK>’;  
translate_array {7} := ’<BEL>’;  
translate_array {8} := ’<BS>’;  
translate_array {14} := ’<SO>’;  
translate_array {15} := ’<SI>’;  
translate_array {16} := ’<DLE>’;  
translate_array {17} := ’<DC1>’;  
translate_array {18} := ’<DC2>’;  
translate_array {19} := ’<DC3>’;  
translate_array {20} := ’<DC4>’;  
translate_array {21} := ’<NAK>’;  
translate_array {22} := ’<SYN>’;  
translate_array {23} := ’<ETB>’;  
translate_array {24} := ’<CAN>’;  
translate_array {25} := ’<EM>’;  
translate_array {26} := ’<SUB>’;  
translate_array {27} := ’<ESC>’;  
translate_array {28} := ’<FS>’;  
translate_array {29} := ’<GS>’;  
translate_array {30} := ’<RS>’;  
translate_array {31} := ’<US>’;  
ENDIF;  
!
! The range *must* be a single character long  
!
IF LENGTH (char_range) <> 1  
THEN  
RETURN 0;  
ENDIF;  
!
! Find the character  
!
replace_text := translate_array {ASCII (STR (char_range))};  
!
! If we got back a value of TPU$K_UNSPECIFIED, TPU will display the character  
! meaningfully  
!
IF replace_text = TPU$K_UNSPECIFIED  
THEN  
RETURN 0;  
ENDIF;  
!
! Erase the range and insert the new text  
!
ERASE (char_range);  
COPY_TEXT (replace_text);  
RETURN 1;  
ENDPROCEDURE;  
(continued on next page)  
Sample DECTPU Procedures A–3  
 
Sample DECTPU Procedures  
A.2 Translation of Control Characters  
Example A–2 (Cont.) Procedure to Display Control Characters  
!
! This procedure controls the outer loop search for the special  
! control characters that we want to view.  
!
PROCEDURE view_controls (source_buffer)  
CONSTANT  
Ctrl_char_str :=  
ASCII (0) + ASCII (1) + ASCII (2) + ASCII (3) +  
ASCII (4) + ASCII (5) + ASCII (6) + ASCII (7) +  
ASCII (8) + ASCII (9) + ASCII (10) + ASCII (11) +  
ASCII (12) + ASCII (13) + ASCII (14) + ASCII (15) +  
ASCII (16) + ASCII (17) + ASCII (18) + ASCII (19) +  
ASCII (20) + ASCII (21) + ASCII (22) + ASCII (23) +  
ASCII (24) + ASCII (25) + ASCII (26) + ASCII (27) +  
ASCII (28) + ASCII (29) + ASCII (30) + ASCII (31);  
LOCAL  
Ctrl_char_pattern,  
Ctrl_char_range;  
! Create the translation buffer and window, if necessary  
!
IF translate_buffer = TPU$K_UNSPECIFIED  
THEN  
translate_buffer := CREATE_BUFFER ("translation");  
SET (NO_WRITE, translate_buffer);  
ENDIF;  
IF translate_window = TPU$K_UNSPECIFIED  
THEN  
translate_window := CREATE_WINDOW (1, 10, ON);  
ENDIF;  
!
! Make a copy of the buffer we are translating  
!
ERASE (translate_buffer);  
POSITION (translate_buffer);  
COPY_TEXT (source_buffer);  
!
! Search for any control characters and translate them. If a control character  
! is not found, SEARCH_QUIETLY will return a 0.  
!
Ctrl_char_pattern := ANY (Ctrl_char_str);  
POSITION (BEGINNING_OF (translate_buffer));  
(continued on next page)  
A–4 Sample DECTPU Procedures  
 
Sample DECTPU Procedures  
A.2 Translation of Control Characters  
Example A–2 (Cont.) Procedure to Display Control Characters  
LOOP  
Ctrl_char_range := SEARCH_QUIETLY (Ctrl_char_pattern, FORWARD);  
EXITIF Ctrl_char_range = 0;  
POSITION (Ctrl_char_range);  
!
! If we did not translate the character, move past it  
!
IF NOT translate_controls (Ctrl_char_range)  
THEN  
MOVE_HORIZONTAL (1);  
ENDIF;  
ENDLOOP;  
!
! Now display what we have done  
!
POSITION (BEGINNING_OF (translate_buffer));  
MAP (translate_window, translate_buffer);  
ENDPROCEDURE;  
Sample DECTPU Procedures A–5  
 
Sample DECTPU Procedures  
A.3 Restoring Terminal Width Before Exiting from DECTPU  
A.3 Restoring Terminal Width Before Exiting from DECTPU  
Example A–3 compares the current width of the screen with the original width.  
If the current width differs from the original width, the procedure restores each  
window to its original width. The screen is refreshed so that information is  
visible on the screen after you exit from DECTPU. When all of the window widths  
are the same, the physical screen width is changed.  
Example A–3 Procedure to Restore Screen to Original Width  
PROCEDURE user_restore_screen  
LOCAL  
original_screen_width,  
temp_w;  
original_screen_width := GET_INFO (SCREEN, "original_width");  
IF original_screen_width <> GET_INFO (SCREEN, "width")  
THEN  
temp_w := get_info(windows,"first");  
LOOP  
EXITIF temp_w = 0;  
SET (WIDTH, temp_w, original_screen_width);  
temp_w := GET_INFO (WINDOWS, "next");  
ENDLOOP;  
REFRESH;  
ENDIF;  
ENDPROCEDURE;  
! Define the key combination Ctrl/E to do an exit which  
! restores the screen to its original width, repaints  
! the screen, and then exits.  
DEFINE_KEY ("user_restore_screen;EXIT", Ctrl_E_KEY);  
A–6 Sample DECTPU Procedures  
 
Sample DECTPU Procedures  
A.4 Running DECTPU from an OpenVMS Subprocess  
A.4 Running DECTPU from an OpenVMS Subprocess  
Example A–4 shows one way of running DECTPU from a subprocess. It also  
shows how to move to or from the subprocess.  
Example A–4 Procedure to Run DECTPU from a Subprocess  
!
!DCL command procedure to run DECTPU from subprocess  
!
!Put $ e = "@keptedit"  
!in your login.com. This spawns the editor the first time  
!and attaches to it after that. I have defined a key to be  
!"attach" so it always goes back to the parent.  
$ tt = f$getdvi("sys$command","devnam") - "_" - "_" - ":"  
$ edit_name = "Edit_" + tt  
$ priv_list = f$setprv("NOWORLD, NOGROUP")  
$ pid = 0  
$10$:  
$ proc = f$getjpi(f$pid(pid), "PRCNAM")  
$ if proc .eqs. edit_name then goto attach  
$ if pid .ne. 0 then goto 10$  
$spawn:  
$ priv_list = f$setprv(priv_list)  
$ write sys$error "[Spawning a new Kept Editor]"  
$ define/nolog sys$input sys$command:  
$ t1 = f$edit(p1 + " " + p2 + " " + p3 + " " + p4 + " "  
+ p5 + " " + p6 + " " + p7 + " " + p8,"COLLAPSE")  
$ spawn/process="’’edit_name’" /nolog edit/tpu ’t1’  
$ write sys$error "[Attached to DCL in directory ’’f$env("DEFAULT")’]"  
$ exit  
$attach:  
$ priv_list = f$setprv(priv_list)  
$ write sys$error "[Attaching to Kept Editor]"  
$ define/nolog sys$input sys$command:  
$ attach "’’edit_name’"  
$ write sys$error "[Attached to DCL in directory ’’f$env("DEFAULT")’]"  
$ exit  
Sample DECTPU Procedures A–7  
 
 
B
DECTPU Terminal Support  
This appendix lists the terminals that support screen-oriented editing and  
describes how differences among these terminals affect the way DECTPU  
performs. This appendix also describes how you can run DECTPU on terminals  
that do not support screen-oriented editing. Finally, this appendix tells you how  
DECTPU manages wrapping and how you can modify that.  
B.1 Using Screen-Oriented Editing on Supported Terminals  
DECTPU supports screen-oriented editing only on terminals that respond to  
ANSI control functions and that operate in ANSI mode.  
DECTPU screen-oriented editing is designed to optimize the features available  
with the Compaq VT400, VT300, and VT200 families of terminals and the  
Compaq VT100 family of terminals. DECTPU does not support screen-oriented  
editing on Compaq VT52-compatible terminals. Optimum DECTPU performance  
is achieved on the VT300-series, VT200-series, and VT100-series terminals. Some  
of the high-performance characteristics of DECTPU may not be apparent on the  
terminals listed in Table B–1 for the reasons stated.  
Table B–1 Terminal Behavior That Affects DECTPU’s Performance  
Terminal  
Characteristic  
VT102  
VT240  
Slow autorepeat rate  
Slow autorepeat rate  
Slower scrolling region setup time than the VT220.  
GIGI  
One form of scrolling region (DECTPU repaints screen, rather than use  
this scrolling mechanism)  
Variable autorepeat rate (cursor keys pick up speed when used repeatedly)  
By default, your DECTPU session runs with the screen management file  
TPU$CCTSHR.EXE. To check your terminal setting, enter the following command  
at the command prompt:  
$ SHOW TERMINAL  
B.1.1 Terminal Settings on OpenVMS Systems That Affect DECTPU  
The following settings may affect the behavior of DECTPU, depending on the  
terminal that you use.  
DECTPU Terminal Support B–1  
 
DECTPU Terminal Support  
B.1 Using Screen-Oriented Editing on Supported Terminals  
132-Column Mode  
Only terminals that set the DEC_CRT mode bit and the advanced video mode  
bit can alter their physical width from 80 columns to 132 and back. All other  
terminals keep the physical width that is set when you enter the editor.  
For the DECTPU screen manager to behave predictably on GIGI terminals, you  
should report the terminal width as 84 to OpenVMS systems. Use the DCL  
command SET TERMINAL/DEVICE=VT100 to set the proper terminal width.  
Autorepeat ON/OFF and Auxiliary Keypad Enabling  
To take advantage of the SET (AUTO_REPEAT) built-in procedure or to  
enable the auxiliary keypad for applications mode, the terminal must be set  
to DEC_CRT3, DEC_CRT2, DEC_CRT, or VT100. Use the DCL command SET  
TERMINAL/DEVICE=characteristic to set the terminal.  
Control Sequence Introducer  
DECTPU can use one 8-bit control sequence introducer (CSI) to introduce a  
terminal control sequence. (Usually you use the 2-character combination of the  
ESCAPE key and the left bracket ( [ ).) To take advantage of this feature, set your  
terminal to DEC_CRT2 mode. The Compaq VT300-series and VT220 and VT240  
terminals currently support this feature.  
Cursor Positioning  
If your terminal sets the DEC_CRT mode bit, DECTPU assumes that when  
control sequences that position the cursor to row 1 or column 1 are sent to the  
terminal, the 1 can be omitted. If your terminal does not behave correctly when it  
receives these control sequences, you must turn off the DEC_CRT mode bit. Some  
foreign terminals may not be fully compatible with DECTPU and may exhibit this  
behavior.  
Edit Mode  
Terminals that are operating in edit mode allow the editor to take advantage  
of special edit-mode control sequences during deletion and insertion of text  
for optimization purposes. Some current Compaq terminals that support edit  
mode include the VT102, the VT220, the VT240, the VT241, and VT300-series  
terminals.  
8-Bit Characters  
ANSI terminals operating in 8-bit mode have the ability to use the supplemental  
characters and control sequences in the DEC Multinational Character Set. The  
Compaq VT300-series and the VT220 and VT240 terminals currently support  
8-bit character mode. If you have the 8-bit mode bit set, DECTPU designates  
the DEC Multinational Character Set into G2 and invokes it into GR. For  
more information on how your terminal interacts with the DEC Multinational  
Character Set, refer to the programming manual for your specific terminal.  
Scrolling  
DECTPU uses scrolling regions only for terminals that have the DEC_CRT mode  
bit set. On other terminals, DECTPU repaints the window when a scroll would  
have been used (for example, when a line is deleted or inserted).  
Video Attributes  
When you set the video attributes of windows, markers, or ranges, only those  
attributes supported by your terminal type give predictable results. Most ANSI  
CRTs support reverse video. However, only terminals that support DEC_CRT  
mode with the advanced video option (AVO) have the full range of video attributes  
(reverse, bold, blink, underline) that DECTPU supports.  
B–2 DECTPU Terminal Support  
 
DECTPU Terminal Support  
B.1 Using Screen-Oriented Editing on Supported Terminals  
B.1.2 SET TERMINAL Command  
When you use the SET TERMINAL command to specify characteristics for your  
terminal, make sure to set only those characteristics that are supported by  
your terminal. If you set characteristics that the terminal does not support, the  
screen-oriented functions of DECTPU may behave unpredictably. For example, if  
you run DECTPU on a VT100 terminal and you set the DEC_CRT2 characteristic  
that VT100s do not support, DECTPU tries to use 8-bit CSI controls. This could  
cause ;7m to appear on the screen where the reverse video attribute should be  
set.  
Most users do not knowingly set characteristics that are not supported by their  
terminals. However, if you temporarily move to a different type of terminal, your  
LOGIN.COM file may have characteristics set for your usual terminal that do  
not apply to the current terminal. This problem may also occur if, before running  
DECTPU, you run a program that modifies your terminal characteristics without  
your knowledge.  
If you see unexpected video attributes or extraneous characters on the screen, exit  
from DECTPU and check your terminal characteristics with the DCL command  
SHOW TERMINAL.  
To recover your files, use the same terminal characteristics you used to create  
your file; otherwise, a journal file inconsistency may occur, depending on how  
your interface is written.  
B.2 Using Line-Mode Editing on Unsupported Terminals  
If you want to run DECTPU from an unsupported terminal, you must inform  
DECTPU that you do not want to use screen capabilities. To invoke DECTPU  
on an unsupported terminal, use the /NODISPLAY qualifier after the EDIT/TPU  
command. See Chapter 2 for more information on this qualifier. While in no-  
display mode, DECTPU uses the RTL generic LIB$PUT_OUTPUT routine to  
display prompts and messages at the current location in SYS$OUTPUT. By using  
a combination of the READ_LINE and MESSAGE built-in procedures, you can  
devise your own line-mode editing functions or perform editing tasks from a batch  
job. See the sample line-mode editor in Appendix A.  
B.3 Using Terminal Wrap  
Terminal wrap characteristics perform differently on each operating system.  
If you have enabled an automatic wrap setting on your terminal, DECTPU  
disables this setting in order to manage the screen more efficiently. When you  
exit from DECTPU, DECTPU restores all terminal characteristics. If the SET  
TERM/NOWRAP command is active, DECTPU leaves the hardware wrap off.  
However, if the SET TERM/WRAP command is active, DECTPU assumes that  
you want hardware wrap on, so it turns it on when you exit from DECTPU.  
You can prevent DECTPU from turning on hardware wrap by specifying  
SET TERM/NOWRAP before invoking DECTPU. You can enter the command  
interactively, or you can write a DCL command procedure that makes this  
setting part of your DECTPU environment. Example B–1 shows a DCL command  
procedure that is used to control this terminal setting before and after a DECTPU  
session.  
DECTPU Terminal Support B–3  
 
DECTPU Terminal Support  
B.3 Using Terminal Wrap  
Example B–1 DCL Command Procedure for SET TERM/NOWRAP  
$ SET TERM/NOWRAP  
$ ASSIGN/USER SYS$COMMAND SYS$INPUT  
$ EDIT/TPU/SECTION = EDTSECINI  
$ SET TERM/WRAP  
B–4 DECTPU Terminal Support  
 
C
DECTPU Debugger Commands  
You can use the following commands for debugging once you have set breakpoints,  
compiled code, and started execution.  
ATTACH process  
Suspends the current editing session and transfers control to another active  
process or subprocess.  
DCL process names are case sensitive.  
CANCEL BREAKPOINT procedure-name  
Cancels a breakpoint set with the SET BREAKPOINT command.  
DEPOSIT variable := expression  
Lets you set the values of global variables, local variables, and formal  
parameters.  
DISPLAY SOURCE  
Clears text from the screen after use of the HELP or SHOW BREAKPOINTS  
command. Causes the source display area to display your code.  
EXAMINE variable  
Displays the current contents of global and local variables, global constants,  
formal parameters of the procedure that has been interrupted, and variables local  
to that procedure. Local constants cannot be examined.  
GO  
Causes the debugger to relinquish control of execution until it is invoked again by  
a breakpoint, by the DEBUG command, or by the DEBUGON procedure.  
HELP  
Lists available debugger commands and keypad bindings.  
QUIT  
Stops execution of the current procedure. Uses the ABORT statement to return  
to the main loop of DECTPU. This command is useful when you have located a  
problem in a procedure and are ready to get out of the procedure.  
SCROLL [-] number-of-lines  
Scrolls text in the source display area by the specified number of lines. To scroll  
backward through the code in the display area, specify a negative number of  
lines.  
To scroll forward by one line less than the number of lines in the display  
window, press the Next Screen key or the sequence GOLD/Down Arrow. To  
scroll backward in the same way, press the Prev Screen key or the sequence  
GOLD/Up Arrow.  
SET BREAKPOINT procedure-name  
Invokes the debugger when the specified procedure is entered.  
DECTPU Debugger Commands C–1  
 
DECTPU Debugger Commands  
SET WINDOW top, length  
Places the top of the debugger window at the line number specified by the top  
parameter. Extends the window down by the number of lines specified by the  
length parameter. The default length is 7 lines. The minimum valid length is 3  
lines. The SET WINDOW command changes only the size of the source display  
area. The output area and command line always occupy exactly one line.  
SHIFT [-] number-of-columns  
Moves the source display window left or right across the source code to display  
text wider than the screen.  
To move left, you press the key sequence GOLD/Left Arrow, then enter the  
number of columns to move. To move right, you press the key sequence  
GOLD/Right Arrow, then enter the number of columns to move.  
SHOW BREAKPOINTS  
List the current breakpoints in the debugger source window. To redisplay code in  
the source window, use the DISPLAY SOURCE command.  
SPAWN subprocess  
Suspends the current editing session and creates a new process.  
STEP  
Executes one line of DECTPU code, then returns control to the debugger. If you  
have several DECTPU statements on one line, all statements are executed before  
control returns to the debugger.  
TPU statement  
Executes the DECTPU statement you specify. You can enter more than one  
statement by using the TPU command just once.  
C–2 DECTPU Debugger Commands  
 
Index  
Callbacks, 5–7 to 5–9  
handling in EVE, 5–10  
CASE statement, 4–21 to 4–22  
Case-style error handler, 4–25 to 4–28  
Character set, 4–1  
Character_cell display, 2–12  
/CHARACTER_SET qualifier, 2–9  
Closures, 5–10  
A
@ command, 5–27  
Abort  
resulting from exceeding virtual address space,  
2–8  
ABORT statement, 4–24, 4–29 to 4–30  
Active editing point, 3–4  
Algorithm  
for naming buffer-change journal file, 2–8  
Alternation  
Command files, 5–24 to 5–25  
debugging, 5–29  
default, 5–17  
definition, 2–2  
sample, 5–25  
pattern ( | ), 3–14  
AND operator, 4–8  
Command line  
Arithmetic expression, 4–10  
ARRAY data type, 3–2 to 3–3  
Assignment statement, 4–20  
/J OURNAL qualifier, 2–6  
/NOJ OURNAL qualifier, 2–6  
/RECOVER qualifier, 2–6  
Command parameter  
B
See EDIT/TPU command  
Base of numeric constant  
specifying, 4–34  
/COMMAND qualifier, 2–4 to 2–5, 2–10 to 2–11,  
5–21  
Batch job, 2–6  
Command qualifiers  
Boolean expression, 4–11  
Bound marker, 3–9 to 3–10  
Buffer  
See EDIT/TPU command, qualifiers  
Comment character, 1–5  
Compilation  
conditional, 4–33  
COMPILE built-in procedure, 5–15  
Compiling  
erasing, 3–4  
journal file, 2–6  
variables, 3–4  
Buffer, multiple, 3–4  
Buffer-change journaling, 2–6  
default file naming, 2–8  
enabling, 2–6, 2–14  
BUFFER command  
for message buffer, 5–15  
BUFFER data type, 3–3 to 3–4  
Buffer names, 3–4  
Built-in procedure  
in a DECTPU buffer, 5–15  
in EVE, 5–15  
programs, 5–14 to 5–15  
to create section file, 5–19  
Concatenation  
pattern ( + ), 3–13  
string, 4–4  
Conditional compilation, 4–33  
Conditional statements, 4–20 to 4–21  
Constant  
specifying radix of, 4–34  
CONSTANT declaration, 4–32  
Constants, 4–6 to 4–7  
local, 4–19  
name of as reserved word, 4–12  
occluded, 4–12  
C
Callable interface, 5–1  
Callback routines  
levels of, 5–8  
predefined, 4–12  
Control character  
entering, 4–3  
translation example, A–2  
Index–1  
 
Debugging (contd)  
/CREATE qualifier, 2–11  
STEP command, 5–30, C–2  
to examine contents of local variable, 5–30  
TPU command, C–2  
CREATE_WIDGET built-in procedure  
using to specify callback routine, 5–8  
using to specify resource values, 5–11  
CREATE_WINDOW built-in procedure, 3–23  
Ctrl/C, 5–16  
with case-style error handler, 4–26, 4–27  
with procedural error handler, 4–24, 4–25  
Current buffer  
DEBUGON procedure, 5–29  
/DEBUG qualifier, 2–12, 5–28  
DECTPU  
DECwindows, 1–2  
journaling methods, 2–6  
relationship with DECwindows features, 1–3  
running from subprocess example, A–7  
used with UIL, 1–4  
active editing point, 3–4  
Current window, 3–24  
DECwindows DECTPU  
invoking with /DISPLAY, 2–12  
DEC_CRT2 mode, B–3  
DEC_CRT mode, B–2  
Default editing interface, 2–2  
Default file-naming algorithm  
buffer-change journal, 2–8  
$DEFAULTS$ buffer, 5–27  
Deletion  
D
Data type  
checking, 5–10, 5–11  
definition, 3–1  
keywords  
ARRAY, 3–2 to 3–3  
BUFFER, 3–3 to 3–4  
INTEGER, 3–4 to 3–5  
KEYWORD, 3–5 to 3–7  
LEARN, 3–7 to 3–8  
buffer, 3–4  
marker, 3–10  
range, 3–19  
MARK, 3–8 to 3–10  
window, 3–25  
Displaying version number, 5–2  
/DISPLAY qualifier, 2–12  
PATTERN, 3–10 to 3–17  
PROCESS, 3–18  
PROGRAM, 3–18  
RANGE, 3–19 to 3–20  
STRING, 3–20 to 3–21  
UNSPECIFIED, 3–21 to 3–22  
WIDGET, 3–22  
See also /NODISPLAY  
Dynamic selection  
in EVE, 5–13  
WINDOW, 3–22 to 3–26  
Data types, 1–6  
E
EDIT/TPU command, 2–1  
qualifiers, 2–9 to 2–20  
/CHARACTER_SET, 2–9  
/COMMAND, 2–10 to 2–11  
/CREATE, 2–11  
DCL command procedure  
example, A–7  
$DEBUG$INI$ buffer, 5–18  
DEBUG command, 5–29  
Debugger  
/DEBUG, 2–12, 5–28  
/DISPLAY, 2–12  
/INITIALIZATION, 2–13  
/INTERFACE, 2–14  
/J OURNAL, 2–14  
/MODIFY, 2–15  
/OUTPUT, 2–16  
/READ_ONLY, 2–17  
/RECOVER, 2–18  
/SECTION, 2–19  
invoking, 5–28  
Debugging, 5–28 to C–2  
ATTACH command, C–1  
CANCEL BREAKPOINT command, C–1  
command files, 5–29  
DEPOSIT command, C–1  
DISPLAY SOURCE command, C–1  
EXAMINE command, C–1  
GO command, 5–29, C–1  
HELP command, C–1  
program, 5–29  
/START_POSITION, 2–20  
QUIT command, C–1  
SCROLL command, C–1  
section files, 5–28  
Editing interface  
See EVE  
Editing point, 3–4  
SET BREAKPOINT command, 5–28, C–1  
SET WINDOW command, C–2  
SHIFT command, C–2  
SHOW BREAKPOINTS command, C–2  
source code, 5–29  
ELSE clause, 4–20  
%ELSE lexical keyword, 4–33  
%ENDIF lexical keyword, 4–33  
SPAWN command, C–2  
Index–2  
 
ENDIF statement, 4–20 to 4–21  
ENDLOOP statement, 4–20  
ENDMODULE statement, 4–14  
ENDON_ERROR statement, 4–23 to 4–28  
ENDPROCEDURE statement, 4–15 to 4–19  
Entering control characters, 4–3  
EQUIVALENCE statement, 4–30  
Error  
resulting from exceeding virtual address space,  
2–8  
Error handler  
case-style, 4–25 to 4–28  
procedural, 4–24 to 4–25  
Error handling, 4–23 to 4–28, 5–30  
ERROR lexical element, 4–23  
ERROR_LINE lexical element, 4–23  
ERROR_TEXT lexical element, 4–23  
EVE  
Function procedures, 4–18  
G
Gadget, 3–22  
GET_INFO built-in procedure  
string constant parameter  
"journaling", 2–6, 2–14  
"journal_file", 2–7, 2–14  
WIDGET keyword parameter  
"callback_parameters", 5–10  
Global selection  
support for, 5–6 to 5–7  
Global variable, 4–5  
I
Identifier, 4–5  
IDENT statement, 4–14  
%IFDEF lexical keyword, 4–33  
%IF lexical keyword, 4–33  
IF statement, 4–20 to 4–21  
INFO_WINDOW variable, 5–24  
Initialization files  
$DEFAULTS$ buffer, 5–27  
initialization files, 5–25 to 5–27  
during a session, 5–27  
effects on buffer settings, 5–27  
Initialization files, 2–13  
message buffer, 5–15  
default handling, 5–18  
definition, 2–3  
output file, 2–16  
source files, 5–3  
during a session, 5–27  
effects on buffer settings, 5–27  
EVE, 5–25 to 5–27  
EVE$INIT logical name, 5–26  
EVE$SELECTION procedure  
using to obtain EVEs current selection, 5–13  
EVE default settings, 5–27  
EVE source files, 2–3  
EXECUTE built-in procedure, 5–15  
EXITIF statement, 4–20  
Expressions, 4–8 to 4–12  
arithmetic, 4–10  
/INITIALIZATION qualifier, 2–13  
Initializing variables, 3–21  
Input files, 2–1  
multiple, 2–1  
Input focus  
support for, 5–5  
INRANGE case constant, 4–22  
Integer constants, 4–6  
INTEGER data type, 3–4 to 3–5  
/INTERFACE qualifier, 2–14  
Interruption of program, 5–16  
Invoking DECTPU, 2–1  
from a batch job, 2–6  
Boolean, 4–11  
evaluation by compiler, 4–9  
pattern, 4–11  
relational, 4–10  
types of, 4–10  
Extensible Versatile Editor  
See EVE  
from DCL command procedure, 2–3  
interactively, 2–1  
F
restrictions to consider before, 2–8  
Fatal internal error  
resulting from exceeding virtual address space,  
2–8  
File  
default name for journaling, 2–8  
File specifications  
default file specifications, 2–2  
Found range selection  
in EVE, 5–14  
J
J ournal file  
default name, 2–8  
getting name of, 2–7, 2–14  
security caution, 2–6  
J ournaling  
buffer-change, 2–6  
default file name, 2–8  
enabling buffer-change journaling, 2–6, 2–14  
enabling keystroke journaling, 2–7, 2–14  
EVE default behavior, 2–6  
Free marker, 3–8 to 3–10  
Index–3  
 
J ournaling (contd)  
layered application control, 2–6  
using both keystroke and buffer-change  
journaling, 2–7  
M
MARK data type, 3–8 to 3–10  
Marker  
"journaling" string constant parameter  
GET_INFO built-in, 2–6, 2–14  
deleting, 3–10  
/J OURNAL qualifier, 2–6, 2–14  
"journal_file" string constant parameter  
GET_INFO built-in, 2–7, 2–14  
padding effects, 3–9 to 3–10  
video attributes, 3–8  
Memory  
J OURNAL_OPEN built-in procedure, 2–7, 2–15  
error resulting from exceeding, 2–8  
Message buffer, 5–15  
MESSAGE_BUFFER variable, 5–24  
/MODIFY qualifier, 2–15  
Module declaration  
K
Key name  
table, 3–6  
syntax, 4–14  
Keystroke journaling  
compared to buffer-change journaling, 2–6  
enabling, 2–7, 2–14  
Keyword, 4–12  
key name, 3–6  
occluded, 4–12  
Keyword constants, 4–6  
KEYWORD data type, 3–5 to 3–7  
Keywords  
MODULE statement, 4–14  
N
Names for procedures, 4–15  
/NOJ OURNAL qualifier, 2–6  
Noninteractive editing, 2–4  
NOT operator, 4–8  
Null parameters, 4–16  
Numeric constant  
lexical, 4–32  
specifying radix of, 4–34  
L
O
LEARN data type, 3–7 to 3–8  
Lexical element, 4–1  
Lexical keywords, 4–32 to 4–34  
LINE command, 5–14  
Line-mode editing, B–3  
Line-mode editor  
ON_ERROR statement, 4–23 to 4–28  
location, 4–23  
ON_ERROR Statement, 4–19  
Operators, 4–7 to 4–8  
partial pattern assignment (@), 3–14  
pattern alternation ( | ), 3–14  
pattern concatenation ( + ), 3–13  
pattern linking (&), 3–13  
precedence, 4–8  
example, A–1  
List  
specifying as a resource value, 5–11  
$LOCAL$INI$ buffer, 5–18  
LOCAL declaration, 4–30 to 4–32  
Local variable, 4–5, 4–19  
Local variables, 4–30  
Logical names  
relational, 3–15  
OR operator, 4–8  
Output file, 2–16  
/OUTPUT qualifier, 2–16  
OUTRANGE case constant, 4–22  
EVE$INIT, 5–26  
TPU$COMMAND, 2–11  
TPU$DEBUG, 2–12  
TPU$SECTION, 2–19  
Logical operators  
P
Parameters  
for procedures, 4–15 to 4–17  
Parentheses  
AND operator, 4–8  
NOT operator, 4–8  
in expressions, 4–8  
Parser  
OR operator, 4–8  
XOR operator, 4–8  
maximum stack depth of, 5–2  
Partial pattern assignment (@), 3–14  
Pattern  
LOOP statement, 4–20  
alternation ( | ), 3–14  
built-in procedures, 3–12  
compilation, 3–16  
concatenation ( + ), 3–13  
Index–4  
 
Pattern (contd)  
Recursive procedure, 4–18  
Relational expression, 4–10  
Relational operators, 3–15  
Removal of window, 3–25  
Repetitive statements, 4–20  
Reserved word  
built-in procedures, 4–12  
keywords, 4–12  
language elements, 4–13 to 4–14  
predefined constants, 4–12  
Resource  
execution, 3–16  
expression, 4–11  
linking (&), 3–13  
operators, 3–13  
searching, 3–10  
Pattern assignment  
partial (@), 3–14  
PATTERN data type, 3–10 to 3–17  
Predefined constants  
names, 4–12  
Procedural error handler, 4–24 to 4–25  
Procedure  
supported data types for, 5–11  
Restoring terminal width  
example, A–6  
executing, 5–16  
name, 4–15  
parameter, 4–15 to 4–17  
recommended naming conventions, 5–25  
recommended size for, 5–2  
recursive, 4–18  
Restrictions  
for DECTPU virtual address space, 2–8  
for subprocesses on OpenVMS systems, 3–18  
RETURN statement, 4–24, 4–28 to 4–29  
returning result, 3–8, 4–18  
PROCEDURE statement, 4–15 to 4–19  
PROCESS data type, 3–18  
Program  
S
Screen manager, 3–25  
Search  
add to section file, 5–20  
calling DECTPU from, 5–1  
compiling, 5–14 to 5–15  
complex, 5–2  
anchoring a pattern, 3–17  
for pattern, 3–10  
unanchoring pattern elements, 3–17  
Section files, 2–19  
debugging, 5–28 to C–2  
DECwindows DECTPU, 5–4  
executing, 5–15 to 5–16  
interrupting, 5–16  
order, 5–3  
simple, 5–2  
creating, 5–19  
debugging, 5–28  
default, 5–17  
definition, 2–2  
extending, 5–20  
processing, 5–19, 5–20  
recommended conventions, 5–23  
/SECTION qualifier, 2–19, 5–21  
Security considerations, 2–6  
Selection, 5–13  
syntax, 5–3  
example, 5–3  
writing, 5–1 to 5–12  
PROGRAM data type, 3–18  
dynamic, 5–13  
found range, 5–14  
static, 5–13  
Select range  
Q
Qualifiers  
See EDIT/TPU command, qualifiers  
in EVE, 5–13  
Semicolon  
as statement separator, 1–7, 4–4, 4–14, 4–15,  
4–16, 5–3  
Separator  
R
Radix of numeric constant  
specifying, 4–34  
Range  
semicolon used as, 1–7, 4–4, 4–14, 4–15, 4–16,  
5–3  
deleting, 3–19  
erasing, 3–19  
SET (WIDGET) built-in procedure  
using to specify resource values, 5–11  
SET (WIDGET_CALLBACK) built-in procedure  
using to specify callback routine, 5–8  
SET built-in procedure  
WIDGET, 5–9  
video attributes, 3–20  
RANGE data type, 3–19 to 3–20  
/READ_ONLY qualifier, 2–17  
/RECOVER qualifier, 2–6, 2–18  
Recovery  
SHOW (KEYWORDS) built-in procedure, 3–5  
SHOW DEFAULTS BUFFER command, 5–27  
of buffer contents, 2–6  
Index–5  
 
Showing version number, 5–2  
SHOW_BUFFER variable, 5–24  
Source files for EVE, 2–3  
Startup files, 2–2 to 2–3, 5–17 to 5–27  
command file, 2–2  
TPU$WIDGET_STRING_CALLBACK callback  
routine, 5–8, 5–9  
TPU$X_MESSAGE_BUFFER variable, 5–24  
TPU$X_SHOW_BUFFER variable, 5–24  
TPU$X_SHOW_WINDOW variable, 5–24  
TPU$_UNKLEXICAL error message, 4–34  
TPU command, 5–15  
definition, 2–2  
initialization file, 2–2  
order of execution, 5–18  
section file, 2–2  
TPU debugger, 5–28 to C–2  
ATTACH command, C–1  
/START_POSITION qualifier, 2–20  
Statement  
CANCEL BREAKPOINT command, C–1  
DEBUGON procedure, 5–29  
DEPOSIT command, C–1  
separator for, 5–3  
Static selection, 5–13  
String  
DISPLAY SOURCE command, C–1  
EXAMINE command, C–1  
concatenating, 4–4  
GO command, 5–29, C–1  
String constants, 4–6  
STRING data type, 3–20 to 3–21  
Subprocess  
HELP command, C–1  
invoking, 5–28  
QUIT command, C–1  
restrictions on OpenVMS systems, 3–18  
running DECTPU from, A–7  
Supported terminals, 1–7  
Symbols, 4–4  
SCROLL command, C–1  
SET BREAKPOINT command, 5–28, C–1  
SET WINDOW command, C–2  
SHIFT command, C–2  
Syntax, 5–3  
SHOW BREAKPOINTS command, C–2  
SPAWN command, C–2  
STEP command, 5–30, C–2  
TPU command, C–2  
T
Terminal  
behavior, B–1  
DEC_CRT2, B–3  
U
restoring width, A–6  
setting, B–1 to B–3  
Unbound code  
use of local variables in, 4–31  
UNSPECIFIED data type, 3–21 to 3–22  
Unsupported terminals, 3–26  
Updating windows, 3–25  
AUTO_REPEAT, B–2  
auxiliary keypad, B–2  
132 columns, B–2  
control sequence introducer, B–2  
CSI, B–2  
Utility routines  
forming the DECTPU callable interface, 5–1  
cursor, B–2  
DEC_CRT, B–2  
edit mode, B–2  
V
Value(s)  
eightbit characters, B–2  
scrolling, B–2  
video attributes, B–2  
support, B–1  
assigning to widget resources, 5–9  
Variable  
buffer, 3–4  
global, 4–5  
width  
initializing, 3–21  
restoring, A–6  
local, 4–5, 4–19, 4–30  
VARIABLE declaration, 4–32  
Variables  
recommended naming conventions, 5–25  
Version number, 5–2  
Video attribute  
marker, 3–8  
range, 3–20  
Virtual address space  
DECTPU restriction concerning, 2–8  
Terminal support, 1–7  
%THEN lexical keyword, 4–33  
TPU$COMMAND logical name, 2–11, 5–17  
TPU$DEBUG logical name, 2–12  
TPU$INIT_PROCEDURE procedure, 5–18, 5–23  
TPU$LOCAL_INIT procedure, 5–23  
TPU$SECTION logical name, 2–19, 5–17, 5–22  
TPU$STACKOVER status  
correcting, 5–2  
TPU$WIDGET_INTEGER_CALLBACK callback  
routine, 5–8, 5–9  
Index–6  
 
getting information, 3–25  
length, 3–23  
mapping, 3–24  
W
Widget  
removing, 3–25  
listing of, 5–4  
unmapping, 3–25  
unsupported terminals, 3–26  
updating, 3–25  
values, 3–24  
width, 3–23  
WIDGET data type, 3–22  
Widget resources  
data types of, 5–10 to 5–11  
specifying, 5–10  
Window  
WINDOW data type, 3–22 to 3–26  
creating, 3–23  
current, 3–24  
definition, 3–22  
dimensions, 3–23  
X
XOR operator, 4–8  
Index–7  
 
 

Coleman Patio Furniture 2000008349 User Manual
Conair Hair Dryer 146XR User Manual
Crown Audio Microphone PCC 170SWO User Manual
Curtis Conference Phone TID970 User Manual
Dynaflex Telephone Accessories LCD User Manual
Dynex Indoor Furnishings DX WD1202 User Manual
ETA Systems Power Supply PD8 User Manual
Fellowes Paper Shredder FS5M User Manual
Fellowes Paper Shredder PS 79Ci User Manual
Glen Dimplex Home Appliances Ltd Cooktop PBI60R User Manual