CONTENTS Title Page Copyright Page Preface VAXTPU Tutorial Section 1 Overview of the VAX Text Processing Utility 1.1 What Is VAXTPU? 1.2 What Is DECwindows VAXTPU? 1.2.1 DECwindows VAXTPU and DECwindows Features 1.2.2 DECwindows VAXTPU and the DECwindows User Interface Language 1.3 What Is EVE? 1.4 The VAXTPU Language 1.4.1 VAXTPU Data Types 1.4.2 VAXTPU Language Declarations 1.4.3 VAXTPU Language Statements 1.4.4 VAXTPU Built-In Procedures 1.4.5 User-Written Procedures 1.5 Terminals Supported by VAXTPU 1.6 Invoking VAXTPU 1.6.1 Using EDIT/TPU Command Qualifiers 1.6.2 Using Startup Files 1.7 Using Journal Files 1.7.1 Buffer Change Journal File Naming Algorithm 1.8 Learning More About VAXTPU 2 VAXTPU Data Types 2.1 Array 2.2 Buffer 2.3 Integer 2.4 Keyword 2.5 Learn 2.6 Marker 2.7 Pattern 2.7.1 Pattern Built-In Procedures 2.7.2 Keywords That Can Be Used to Build Patterns 2.7.3 Pattern Operators 2.7.3.1 + (Pattern Concatenation Operator) 2.7.3.2 & (Pattern Linking Operator) 2.7.3.3 | (Pattern Alternation Operator) 2.7.3.4 @ (Partial Pattern Assignment Operator) 2.7.3.5 Relational Operators 2.7.4 Pattern Compilation and Execution 2.7.5 Searching 2.7.6 Anchoring a Search 2.8 Process 2.9 Program 2.10 Range 2.11 String 2.12 Unspecified 2.13 Widget 2.14 Window 2.14.1 Window Dimensions 2.14.2 Creating Windows 2.14.3 Window Values 2.14.4 Mapping Windows 2.14.5 Removing Windows 2.14.6 Screen Manager 2.14.7 Getting Information on Windows 2.14.8 Terminals That Do Not Support Windows 3 Lexical Elements of the VAXTPU Language 3.1 Overview 3.2 Character Set 3.2.1 Entering Control Characters 3.2.2 VAXTPU Symbols 3.3 Identifiers 3.4 Variables 3.5 Constants 3.6 Operators 3.7 Expressions 3.7.1 Arithmetic Expressions 3.7.2 Relational Expressions 3.7.3 Pattern Expressions 3.7.4 Boolean Expressions 3.8 Reserved Words 3.8.1 Keywords 3.8.2 Built-In Procedure Names 3.8.3 Predefined Constants 3.8.4 Declarations and Statements 3.8.4.1 The Module Declaration 3.8.4.2 The Procedure Declaration 3.8.4.2.1 Procedure Names 3.8.4.2.2 Procedure Parameters 3.8.4.2.3 Procedures That Return a Result 3.8.4.2.4 Recursive Procedures 3.8.4.2.5 Local Variables 3.8.4.2.6 Constants 3.8.4.2.7 ON_ERROR Statements 3.8.4.3 The Assignment Statement 3.8.4.4 The Repetitive Statement 3.8.4.5 The Conditional Statement 3.8.4.6 The Case Statement 3.8.4.7 Error Handling 3.8.4.7.1 Procedural Error Handlers 3.8.4.7.2 Case-Style Error Handlers 3.8.4.7.3 CTRL/C Handling 3.8.4.8 The RETURN Statement 3.8.4.9 The ABORT Statement 3.8.4.10 Miscellaneous Declarations 3.8.4.10.1 EQUIVALENCE Statement 3.8.4.10.2 LOCAL 3.8.4.10.3 CONSTANT 3.8.4.10.4 VARIABLE 3.9 Lexical Keywords 3.9.1 Conditional Compilation 3.9.2 Specifying the Radix of Numeric Constants 4 VAXTPU Program Development 4.1 Creating VAXTPU Programs 4.1.1 Simple Programs 4.1.2 Complex Programs 4.1.3 Program Syntax 4.2 Programming in DECwindows VAXTPU 4.2.1 Widgets Supported by DECwindows VAXTPU 4.2.2 Input Focus Support in DECwindows VAXTPU 4.2.3 Global Selection Support in DECwindows VAXTPU 4.2.3.1 Difference Between Global Selection and Clipboard 4.2.3.2 Handling of Multiple Global Selections 4.2.3.3 Relation of Global Selection to Input Focus in DECwindows VAXTPU 4.2.3.4 DECwindows VAXTPU's Response to Requests for Information About the Global Selection 4.2.4 Using Callbacks in DECwindows VAXTPU 4.2.4.1 Background on DECwindows Callbacks 4.2.4.2 Understanding the Difference Between VAXTPU's Internally-Defined Callback Routines and a Layered Application' 4.2.4.3 Using Internally-Defined VAXTPU Callback Routines with UIL 4.2.4.4 Using Internally-Defined VAXTPU Callback Routines with Widgets Not Defined by UIL 4.2.4.5 Using Application-Level Callback Action Routines 4.2.4.6 Callable Interface-Level Callback Routines 4.2.5 Using Closures in DECwindows VAXTPU 4.2.6 Specifying Values for Widget Resources in DECwindows VAXTPU 4.2.6.1 VAXTPU Data Types for Specifying Resource Values 4.2.6.2 Specifying a List as a Resource Value 4.3 Writing Code Compatible with DECwindows EVE 4.3.1 Screen Objects in Applications Layered on DECwindows VAXTPU 4.3.2 Select Ranges in DECwindows EVE 4.3.2.1 Dynamic Selection 4.3.2.2 Static Selection 4.3.2.3 Found Range Selection 4.3.2.4 Relation of EVE Selection to DECwindows Global Selection 4.4 Compiling VAXTPU Programs 4.4.1 Compiling on the EVE Command Line 4.4.2 Compiling in a VAXTPU Buffer 4.5 Executing VAXTPU Programs 4.5.1 Interrupting Execution with CTRL/C 4.5.2 Procedure Execution 4.6 VAXTPU Startup Files 4.6.1 Sequence in Which VAXTPU Processes Startup Files 4.6.2 Section Files 4.6.2.1 Creating and Processing a New Section File 4.6.2.2 Extending an Existing Section File 4.6.2.3 A Sample Section File 4.6.2.4 Recommended Conventions for Section Files 4.6.2.4.1 TPU$INIT_PROCEDURE 4.6.2.4.2 TPU$LOCAL_INIT 4.6.2.4.3 Special Variables 4.6.3 Command Files 4.6.4 EVE Initialization Files 4.6.4.1 Using an EVE Initialization File at Startup 4.6.4.2 Using an EVE Initialization File During an Editing Session 4.6.4.3 How an EVE Initialization File Affects Buffer Settings 4.7 Debugging VAXTPU Programs 4.7.1 Invoking the VAXTPU Debugger 4.7.1.1 Section Files 4.7.1.2 Command Files 4.7.1.3 Other VAXTPU Source Code 4.7.2 Getting Started with the VAXTPU Debugger 4.7.3 VAXTPU Debugger Commands 4.8 Error Handling 5 Invoking VAXTPU 5.1 Avoiding Errors Related to Virtual Address Space 5.2 Invoking VAXTPU from a DCL Command Procedure 5.2.1 Setting Up a Special Editing Environment 5.2.2 Creating a Noninteractive Application 5.3 Invoking VAXTPU from a Batch Job 5.4 Qualifiers to the DCL Command EDIT/TPU 5.4.1 /COMMAND 5.4.2 /CREATE 5.4.3 /DEBUG 5.4.4 /DISPLAY 5.4.5 /INITIALIZATION 5.4.6 /INTERFACE 5.4.7 /JOURNAL 5.4.8 /MODIFY 5.4.9 /OUTPUT 5.4.10 /READ_ONLY 5.4.11 /RECOVER 5.4.12 /SECTION 5.4.13 /START_POSITION 5.4.14 /WRITE 5.5 How EVE Uses /MODIFY, /OUTPUT, /READ_ONLY, and /WRITE 5.6 Specifying a Parameter to EDIT/TPU 6 VAXTPU Screen Management 6.1 How the Screen Manager Handles Windows and Buffers 6.1.1 Buffer Changes 6.1.2 Window Changes 6.1.2.1 Making a Window Current 6.1.2.2 Mapping a Window 6.1.2.3 Shifting a Window 6.1.2.4 Deleting a Window 6.1.2.5 How VAXTPU Window Size Affects a Terminal Emulator 6.1.2.6 How VAXTPU Window Size Affects the Display on a Terminal 6.1.2.7 How a Window Displays Insertion of Records into a Buffer 6.1.2.8 How a Window Displays Deletion of Records from a Buffer 6.1.2.9 How a Window Displays Changes to a Record in a Buffer 6.2 Invoking the Screen Manager 6.2.1 Enabling Screen Updates 6.2.2 Automatic Updates 6.2.3 Updating Windows 6.2.4 Updating the Whole Screen 6.2.5 The REFRESH Built-In 6.2.6 The SCROLL Built-In 6.3 Cursor Position Compared to Editing Point 6.4 Built-In Padding VAXTPU Reference Section 7 VAXTPU Built-In Procedures 7.1 Built-In Procedures Grouped According to Function 7.1.1 Screen Layout 7.1.2 Cursor Movement 7.1.3 Moving the Editing Position 7.1.4 Text Manipulation 7.1.5 Pattern Matching 7.1.6 Status of the Editing Context 7.1.7 Defining Keys 7.1.8 Multiple Processing 7.1.9 Program Execution 7.1.10 DECwindows VAXTPU-Specific 7.1.11 Miscellaneous 7.2 Descriptions of the Built-In Procedures ABORT ADD_KEY_MAP ADJUST_WINDOW ANCHOR ANY APPEND_LINE ARB ASCII ATTACH BEGINNING_OF BREAK CALL_USER CHANGE_CASE COMPILE CONVERT COPY_TEXT CREATE_ARRAY CREATE_BUFFER CREATE_KEY_MAP CREATE_KEY_MAP_LIST CREATE_PROCESS CREATE_RANGE CREATE_WIDGET CREATE_WINDOW CURRENT_BUFFER CURRENT_CHARACTER CURRENT_COLUMN CURRENT_DIRECTION CURRENT_LINE CURRENT_OFFSET CURRENT_ROW CURRENT_WINDOW CURSOR_HORIZONTAL CURSOR_VERTICAL DEBUG_LINE DEFINE_KEY DEFINE_WIDGET_CLASS DELETE EDIT END_OF ERASE ERASE_CHARACTER ERASE_LINE ERROR ERROR_LINE ERROR_TEXT EXECUTE EXIT EXPAND_NAME FAO FILE_PARSE FILE_SEARCH FILL GET_CLIPBOARD GET_DEFAULT GET_GLOBAL_SELECT GET_INFO GET_INFO (any_keyname) GET_INFO (any_keyword) GET_INFO (any_variable) GET_INFO (ARRAY) GET_INFO (array_variable) GET_INFO (BUFFER) GET_INFO (buffer_variable) GET_INFO (COMMAND_LINE) GET_INFO (DEBUG) GET_INFO (DEFINED_KEY) GET_INFO (integer_variable) GET_INFO (KEY_MAP) GET_INFO (KEY_MAP_LIST) GET_INFO (marker_variable) GET_INFO (mouse_event_keyword) GET_INFO (PROCEDURES) GET_INFO (PROCESS) GET_INFO (process_variable) GET_INFO (range_variable) GET_INFO (SCREEN) GET_INFO (string_variable) GET_INFO (SYSTEM) GET_INFO (WIDGET) GET_INFO (widget_variable) GET_INFO (WINDOW) GET_INFO (window_variable) HELP_TEXT INDEX INT JOURNAL_CLOSE JOURNAL_OPEN KEY_NAME LAST_KEY LEARN_ABORT LEARN_BEGIN and LEARN_END LENGTH LINE_BEGIN LINE_END LOCATE_MOUSE LOOKUP_KEY MANAGE_WIDGET MAP MARK MATCH MESSAGE MESSAGE_TEXT MODIFY_RANGE MOVE_HORIZONTAL MOVE_TEXT MOVE_VERTICAL NOTANY PAGE_BREAK POSITION QUIT READ_CHAR READ_CLIPBOARD READ_FILE READ_GLOBAL_SELECT READ_KEY READ_LINE REALIZE_WIDGET RECOVER_BUFFER REFRESH REMAIN REMOVE_KEY_MAP RETURN SAVE SCAN SCANL SCROLL SEARCH SEARCH_QUIETLY SELECT SELECT_RANGE SEND SEND_CLIENT_MESSAGE SEND_EOF SET SET (ACTIVE_AREA) SET (AUTO_REPEAT) SET (BELL) SET (CLIENT_MESSAGE) SET (COLUMN_MOVE_VERTICAL) SET (CROSS_WINDOW_BOUNDS) SET (DEBUG) SET (DEFAULT_DIRECTORY) SET (DETACHED_ACTION) SET (DISPLAY_VALUE) SET (DRM_HIERARCHY) SET (ENABLE_RESIZE) SET (EOB_TEXT) SET (ERASE_UNMODIFIABLE) SET (FACILITY_NAME) SET (FORWARD) SET (GLOBAL_SELECT) SET (GLOBAL_SELECT_GRAB) SET (GLOBAL_SELECT_READ) SET (GLOBAL_SELECT_TIME) SET (GLOBAL_SELECT_UNGRAB) SET (HEIGHT) SET (ICON_NAME) SET (ICON_PIXMAP) SET (ICONIFY_PIXMAP) SET (INFORMATIONAL) SET (INPUT_FOCUS) SET (INPUT_FOCUS_GRAB) SET (INPUT_FOCUS_UNGRAB) SET (INSERT) SET (JOURNALING) SET (KEYSTROKE_RECOVERY) SET (KEY_MAP_LIST) SET (LEFT_MARGIN) SET (LEFT_MARGIN_ACTION) SET (LINE_NUMBER) SET (MAPPED_WHEN_MANAGED) SET (MARGINS) SET (MAX_LINES) SET (MENU_POSITION) SET (MESSAGE_ACTION_LEVEL) SET (MESSAGE_ACTION_TYPE) SET (MESSAGE_FLAGS) SET (MODIFIABLE) SET (MODIFIED) SET (MOUSE) SET (NO_WRITE) SET (OUTPUT_FILE) SET (OVERSTRIKE) SET (PAD) SET (PAD_OVERSTRUCK_TABS) SET (PERMANENT) SET (POST_KEY_PROCEDURE) SET (PRE_KEY_PROCEDURE) SET (PROMPT_AREA) SET (RECORD_ATTRIBUTE) SET (RESIZE_ACTION) SET (REVERSE) SET (RIGHT_MARGIN) SET (RIGHT_MARGIN_ACTION) SET (SCREEN_LIMITS) SET (SCREEN_UPDATE) SET (SCROLL_BAR) SET (SCROLL_BAR_AUTO_THUMB) SET (SCROLLING) SET (SELF_INSERT) SET (SHIFT_KEY) SET (SPECIAL_ERROR_SYMBOL) SET (STATUS_LINE) SET (SUCCESS) SET (SYSTEM) SET (TAB_STOPS) SET (TEXT) SET (TIMER) SET (TRACEBACK) SET (UNDEFINED_KEY) SET (VIDEO) SET (WIDGET) SET (WIDGET_CALL_DATA) SET (WIDGET_CALLBACK) SET (WIDTH) SHIFT SHOW SLEEP SPAN SPANL SPAWN SPLIT_LINE STR SUBSTR TRANSLATE UNANCHOR UNDEFINE_KEY UNMANAGE_WIDGET UNMAP UPDATE WRITE_CLIPBOARD WRITE_FILE WRITE_GLOBAL_SELECT A Sample VAXTPU Procedures A.1 Line-Mode Editor A.2 Translation of Control Characters A.3 Restoring Terminal Width Before Exiting from VAXTPU A.4 Running VAXTPU from a Subprocess B Sample DECwindows VAXTPU Procedures B.1 Using DECwindows VAXTPU Built-ins B.2 Displaying a Dialog Box B.3 Creating a ``Mouse Pad'' B.4 Implementing an EDT-Style APPEND Command B.5 Testing and Returning a Select Range B.6 Resizing Windows B.7 Unmapping Saved Windows B.8 Mapping Saved Windows B.9 Handling Callbacks from a Scroll Bar Widget B.10 Implementing the COPY SELECTION Operation B.11 Reactivating a Select Range B.12 Copying Selected Material from EVE to Another DECwindows Application C VAXTPU Terminal Support C.1 Screen-Oriented Editing on Supported Terminals C.1.1 Terminal Settings That Affect VAXTPU C.1.2 The DCL Command SET TERMINAL C.2 Line-Mode Editing on Unsupported Terminals C.3 Terminal Wrap D VAXTPU Messages E DEC Multinational Character Set F VAXTPU File Support G EVE$BUILD Module G.1 How to Prepare Code for Use with EVE$BUILD G.1.1 Module Identifiers G.1.2 Parsers G.1.3 Initialization G.1.4 Command Synonyms G.1.5 Status Line Fields G.1.6 Exit and Quit Handlers G.1.7 How to Invoke EVE$BUILD G.2 What Happens When You Use EVE$BUILD EXAMPLES 1-1 Sample User-Written Procedure 2-1 Suppressing the Addition of Padding Blanks 3-1 Global and Local Variable Declarations 3-2 Global and Local Constant Declarations 3-3 A Procedure Using Relational Operators on Markers 3-4 Simple Procedure with Parameters 3-5 Complex Procedure with Optional Parameters 3-6 Procedure That Returns a Result 3-7 Procedure Within Another Procedure 3-8 Recursive Procedure 3-9 Procedure Using the CASE Statement 3-10 Procedure Using the ON_ERROR Statement 3-11 Procedure with a Case-Style Error Handler 3-12 Procedure That Returns a Value 3-13 Procedure Returning a Status 3-14 Using RETURN in an ON_ERROR Section 3-15 Simple Error Handler 4-1 SHOW (SUMMARY) Display 4-2 Syntax of a VAXTPU Program 4-3 Sample VAXTPU Programs 4-4 Sample Program for a Section File 4-5 Source Code for Minimal Interface 4-6 Command File for Go to Text Marker 4-7 SHOW DEFAULTS BUFFER Display 5-1 DCL Command Procedure FILENAME.COM 5-2 DCL Command Procedure FORTRAN_TS.COM 5-3 DCL Command Procedure INVISIBLE_TPU.COM 5-4 VAXTPU Command File GSR.TPU 7-1 Initialization Procedure Using Variants of the SET Built-In B-1 EVE Procedure That Displays a Selection Dialog Box B-2 Procedure That Creates a ``Mouse Pad'' B-3 EVE Procedure That Implements a Variant of the EDT APPEND Command B-4 EVE Procedure That Returns a Select Range B-5 Procedure That Resizes Windows B-6 EVE Procedure That Unmaps Saved Windows B-7 Procedure That Maps Saved Windows B-8 EVE Procedure That Handles Callbacks from a Scroll Bar Widget B-9 EVE Procedure That Implements the COPY SELECTION Operation B-10 EVE Procedure That Reactivates a Select Range B-11 EVE Procedure That Implements COPY SELECTION C-1 DCL Command Procedure for SET TERM/NOWRAP FIGURES 1-1 VAXTPU as a Base for EVE 1-2 VAXTPU as a Base for User-Written Interfaces 4-1 Nomenclature of DECwindows VAXTPU Screen Objects 7-1 Screen Layout Before Using ADJUST_WINDOW 7-2 Screen Layout After Using ADJUST_WINDOW TABLES 1-1 Qualifiers to the DCL Command EDIT/TPU 1-2 Journaling Behavior Established by EVE 2-1 Keywords Used for Key Names 3-1 VAXTPU Symbols 3-2 VAXTPU Operators 3-3 Operator Precedence 4-1 Correspondence Between VAXTPU Data Types and DECwindows Argument Data Types 4-2 Special VAXTPU Variables Requiring a Value from a Layered Application 5-1 Summary of How VAXTPU and the Application Layered on VAXTPU Relate to the Qualifiers to EDIT/TPU 7-1 CREATE_RANGE Keyword Parameters 7-2 GET_INFO Built-in Procedures by First Parameter 7-3 VAXTPU Keywords Representing Mouse Events 7-4 Detached Cursor Flag Constants 7-5 Valid Keywords for the Third Parameter When the Second Parameter is "Bottom", "Left", "Length", "Right", "Top", or" 7-6 Message Flag Values 7-7 Message Flag Values 7-8 MODIFY_RANGE Keyword Parameters 7-9 VAXTPU Keywords Representing Mouse Events 7-10 Selected Built-in Actions When ERASE_UNMODIFIABLE is Turned Off 7-11 Message Codes for $PUTMSG System Service 7-12 Message Flag Values C-1 Terminal Behavior That Affects VAXTPU's Performance D-1 VAXTPU Messages and Their Severity Levels E-1 DEC Multinational Character Set F-1 VAXTPU Support of File Attributes