Document revision date: 19 July 1999

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

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.

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; ! only 0's and 1's are legal. constant bad_hex := %x10abg; ! 'g' is illegal digit. constant not_a_radix := %z0123; ! No such radix.

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

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.
• 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.

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.

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;

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
• 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

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:

• DECTPU's main window widget
• DECTPU's 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.

DIGITAL 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.

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 EVE's 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 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.

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.

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.

DIGITAL 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.

DECTPU does not automatically grab the secondary selection. Layered applications are responsible for handling this selection.

	privacy and legal statement
6018PRO_010.HTML