HP OpenVMS Systems Documentation
Guide to the DEC Text Processing Utility
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.
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.
The next two sections explain the DECTPU lexical keywords and how to use them for the following:
4.10.1 Conditional Compilation
You use conditional compilation lexical keywords in a manner similar to ordinary IF/THEN/ELSE/ENDIF statements. The syntax is as follows:
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:
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.
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:
Invalid constructs for numeric constants return the error level message TPU$_UNKLEXICAL, "Unknown lexical element" during compilation. The following examples are not valid:
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
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.
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 EVE's 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.
|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; ! do DECTPU quit operation ENDPROCEDURE; ! 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;
This section provides information about programming with DECTPU in the
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:
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:
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:
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, DECTPU's
automatic grabbing of the input focus enables your layered application
to interact with other DECwindows applications.
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.
188.8.131.52 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 EVE's STORE TEXT command) that sends new information to the
clipboard. By default EVE does not use the clipboard.
184.108.40.206 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
220.127.116.11 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 application's 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.
18.104.22.168 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.
DECTPU's 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, DECTPU's 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.