Guide to the DEC Text Processing Utility 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.
© 2001 Compaq Computer Corporation Compaq, VAX, VMS and the Compaq logo Registered in U.S. Patent and Trademark Office. OpenVMS is a trademark of Compaq Information Technologies Group, L.P. in the United States and other countries. PostScript is a registered trademark of Adobe Systems Incorporated. Motif is a registered trademark of the The Open Group. All other product names mentioned herein may be the trademarks or registered trademarks of their respective companies. Confidential computer software.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix 1 Overview of the DEC Text Processing Utility 1.1 1.1.1 1.1.2 1.1.3 1.2 1.2.1 1.2.2 1.3 1.4 1.4.1 1.4.2 1.4.3 1.4.4 1.4.5 1.5 1.6 Description of DECTPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DECTPU Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DECTPU and User Applications . . . . . . . . . . . . . . . . . . . . .
2.6.8 2.6.9 2.6.10 2.6.11 2.6.12 2.6.13 2.6.14 /JOURNAL . . . . . . . /MODIFY . . . . . . . . /OUTPUT . . . . . . . . /READ_ONLY . . . . . /RECOVER . . . . . . . /SECTION . . . . . . . /START_POSITION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4 Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.5 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.6 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.7 Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.8 Expressions . . . . . . . . . . . . . . . . . . . .
5.2.3 5.2.3.1 5.2.3.2 5.2.3.3 5.2.3.4 5.2.4 5.2.4.1 5.2.4.2 5.2.4.3 5.2.4.4 5.2.4.5 5.2.4.6 5.2.5 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 Global Selection Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Difference Between Global Selection and Clipboard . . . . . . . .
A Sample DECTPU Procedures A.1 A.2 A.3 A.4 Line-Mode Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Translation of Control Characters . . . . . . . . . . . . . . . . . . Restoring Terminal Width Before Exiting from DECTPU Running DECTPU from an OpenVMS Subprocess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A–1 A–2 A–6 A–7 Using Screen-Oriented Editing on Supported Terminals . . . . . . . . .
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 DECTPU as a Base for EVE . . . . . . . . .
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.
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.
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).
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.
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.
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.
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.
Overview of the DEC Text Processing Utility 1.
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.
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.
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.
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).
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 Command TPU$COMMAND.TPU Init SYS$DISK:EVE$INIT.EVE Init SYS$LOGIN:EVE$INIT.EVE Debugger SYS$SHARE:TPU$DEBUG.TPU Keystroke journal SYS$DISK:.TJL Buffer-change journal SYS$SCRATCH:.
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.
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.
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.
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.
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.
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$JOURNAL For example, a buffer named TEST.BAR has a default journal file name of TEST_ BAR.TPU$JOURNAL.
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.
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.
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.
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 EVE’s response would be as follows: $ EDIT/TPU/NOCREATE newfile.
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.
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.
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 JOURNAL_OPEN to direct DECTPU to create a keystroke journal file for an editing session. Using JOURNAL_OPEN causes DECTPU to provide a 500-byte buffer in which to journal keystrokes. By default, DECTPU writes the contents of the buffer to the journal file when the buffer is full.
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.
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.
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.
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 /JOURNAL=filename, EVE recovers from the specified keystroke journal file.
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.
3 DEC Text Processing Utility Data Types A data type is a group of elements that ‘‘belong together’’; the elements are all formed in the same way and are treated consistently. The data type of a variable determines the operations that can be performed on it.
DEC Text Processing Utility Data Types 3.1 Array Data Type 3.1 Array Data Type An array is a structure for storing and manipulating a group of elements. These elements can be of any data type. You create arrays with the CREATE_ARRAY built-in procedure. For example, the following statement creates the array new_array: new_array := CREATE_ARRAY; You can delete arrays with the DELETE built-in procedure.
DEC Text Processing Utility Data Types 3.1 Array Data Type int_array int_array int_array int_array := CREATE_ARRAY (10, 1); {1} := "Store a string in the first element"; {8} := CURRENT_BUFFER; {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.
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).
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 x x x := := := := %B10000; %o20; %X130; 12345; 3.4 Keyword Data Type Keywords are reserved words in DECTPU that have special meaning to the compiler. To see a list of all DECTPU keywords, use the SHOW (KEYWORDS) built-in.
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 DECTPU Key Name VT400, VT300, VT200 Series Key VT100 Key PF1 PF1 PF1 PF2 PF2 PF2 PF3 PF3 PF3 PF4 PF4 PF4 KP0, KP1, . . .
DEC Text Processing Utility Data Types 3.4 Keyword Data Type Table 3–1 (Cont.) Keywords Used for Key Names DECTPU Key Name VT400, VT300, VT200 Series Key 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.
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.
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.
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.
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.
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.
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 DECTPU’s precedence of operators. For more information on the precedence of DECTPU operators, see Chapter 4. Pattern operators associate from left to right.
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 ( + ).
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.
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.
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.
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.
DEC Text Processing Utility Data Types 3.10 Range Data Type 3.10 Range Data Type A range contains all the text between (and including) two markers. You can form a range with the CREATE_RANGE built-in procedure. A range is associated with characters within a buffer. If the characters within a range move, the range moves with them. If characters are added or deleted between two markers that delimit a range, the size of the range changes.
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.
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.
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.
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.
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.
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 DECTPU’s internal list of windows.
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.
4 Lexical Elements of the DEC Text Processing Utility Language 4.1 Overview A DECTPU program is composed of lexical elements. A lexical element may be an individual character, such as an arithmetic operator, or it may be a group of characters, such as an identifier. The basic unit of a lexical element is a character from either the DEC Multinational Character Set or the ISO_LATIN1 Character Set.
Lexical Elements of the DEC Text Processing Utility Language 4.3 Character Sets 4.
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.
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.
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 identifier 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.
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.
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.
Lexical Elements of the DEC Text Processing Utility Language 4.7 Operators Table 4–5 (Cont.) DECTPU Operators Type Logical Symbol Description + Pattern concatenation & Pattern linkage AND Boolean AND NOT Boolean NOT OR Boolean OR XOR Boolean exclusive OR You can use the + operator to concatenate strings. You can also use the relational operators to compare a string with a string, a marker with a marker, or a range with a range.
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.
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.
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.
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.
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.
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.
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.
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.
Lexical Elements of the DEC Text Processing Utility Language 4.9 Reserved Words Example 4–5 Complex Procedure with Optional Parameters CONSTANT user_warning := 0, ! Warning severity code user_success := 1, ! Success severity code user_error := 2, ! Error severity code user_informational := 3, ! Informational severity code user_fatal := 4; ! Fatal severity code ! ! Output a message with fatal/error/warning flash.
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 function procedures. 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.
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 RETURN ENDIF; MESSAGE (temp_string); ! Call user_reverse recursively ! All done, go to display lines ! Display lines typed in reverse order ! in the message window ENDPROCEDURE; 4.9.4.
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 identifier := 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.
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.
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.
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 error handler. An error handler is an optional part of a DECTPU procedure or program. An error handler traps WARNING and ERROR status values.
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.
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.
Lexical Elements of the DEC Text Processing Utility Language 4.
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.
Lexical Elements of the DEC Text Processing Utility Language 4.
Lexical Elements of the DEC Text Processing Utility Language 4.
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.
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.
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.
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 ...
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.
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.
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.
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$*.*.
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.
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.
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.
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.
DEC Text Processing Utility Program Development 5.2 Programming in DECwindows DECTPU 5.2.4.1 Background on DECwindows Callbacks A callback 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.
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.
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.
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.
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.
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.
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.
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.
DEC Text Processing Utility Program Development 5.
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.
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.
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.
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.
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.
DEC Text Processing Utility Program Development 5.6 Using DECTPU Startup Files Example 5–5 Source Code for Minimal Interface to DECTPU ! MINI.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Sample DECTPU Procedures A.1 Line-Mode Editor Example A–1 (Cont.
Sample DECTPU Procedures A.2 Translation of Control Characters Example A–2 (Cont.
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.
Sample DECTPU Procedures A.2 Translation of Control Characters Example A–2 (Cont.
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.
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.
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.
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.
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.
DECTPU Terminal Support B.
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.
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.
Index 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 pattern ( | ), 3–14 AND operator, 4–8 Arithmetic expression, 4–10 ARRAY data type, 3–2 to 3–3 Assignment statement, 4–20 B Base of numeric constant specifying, 4–34 Batch job, 2–6 Boolean expression, 4–11 Bound marker, 3–9 to 3–10 Buffer erasing, 3–4 journal file, 2–6 variables, 3–4 Buffer, multiple,
/CREATE qualifier, 2–11 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 active editing point, 3–4 Current window, 3–24 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 MARK, 3–8 to 3–10 PATTERN
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 $DEFAULTS$ buffer, 5–27 initialization file
Journaling (cont’d) layered application control, 2–6 using both keystroke and buffer-change journaling, 2–7 "journaling" string constant parameter GET_INFO built-in, 2–6, 2–14 /JOURNAL qualifier, 2–6, 2–14 "journal_file" string constant parameter GET_INFO built-in, 2–7, 2–14 JOURNAL_OPEN built-in procedure, 2–7, 2–15 K Key name table, 3–6 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–
Pattern (cont’d) 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 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 returning result, 3–8, 4–18 PROCEDURE statement, 4–15 to 4–19 PROCESS data type, 3–18 Program add to section file, 5–20 calling DEC
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 definition, 2–2 initialization file, 2–2 order of execution, 5–18 section file, 2–2 /START_POSITION qualifier, 2–20 Statement separator for, 5–3 Static selection, 5–13 String concatenating, 4–4 String constants, 4–6 STRING data type, 3–20 to 3–21 Subprocess restrictions on OpenVMS systems, 3–18 running DECTPU from, A–7 Supported terminals, 1–7 Symbols, 4–4 Syntax, 5–3 T
W Widget listing of, 5–4 WIDGET data type, 3–22 Widget resources data types of, 5–10 to 5–11 specifying, 5–10 Window creating, 3–23 current, 3–24 definition, 3–22 dimensions, 3–23 getting information, 3–25 length, 3–23 mapping, 3–24 removing, 3–25 unmapping, 3–25 unsupported terminals, 3–26 updating, 3–25 values, 3–24 width, 3–23 WINDOW data type, 3–22 to 3–26 X XOR operator, 4–8 Index–7