Composition operations are the routines you use to manipulate virtual displays on a pasteboard and thus to create an image on a terminal screen. These operations include pasting, unpasting, repasting, moving and popping virtual displays, checking virtual displays for occlusion, and listing the pasting order.

2.1.1. Paste Operation

Virtual displays are visible on a physical device only while they are pasted to a pasteboard. Paste a display to a pasteboard by calling SMG$PASTE_VIRTUAL_DISPLAY and specifying the pasteboard coordinates as the origin of the virtual display. (The origin is the top left-hand corner.) The pasteboard itself has no boundaries, but of course the physical screen does. Thus you can paste a display to a pasteboard in such a way that some or all of the display does not appear on the terminal screen.

Pasting virtual displays to a pasteboard is a logical operation that maps the contents of a virtual display to a location on the screen by specifying the row and column of the pasteboard that coincide with row 1 and column 1 of the virtual display. For example, pasting a 6-row virtual display "A" to pasteboard rows 1 through 6 and pasting a second 6-row virtual display "B" to pasteboard rows 7 through 12 places virtual display "B" immediately below virtual display "A" on the screen. See Figure 2.1, “Paste Operation”.

2.1.2. Unpaste Operation

You can make a virtual display disappear from the physical screen using the SMG$UNPASTE_VIRTUAL_DISPLAY routine. To continue the example in Section 2.1.1, “Paste Operation”, if virtual display "B" is unpasted, the results appear as in Figure 2.2, “Unpaste Operation”.

Unpasting a virtual display does not destroy the virtual display or its contents; it simply removes the display from the pasteboard.

Displays can overlap partially or completely, depending on their size, where they are pasted, and the order in which they are pasted. This overlap is called occlusion. Unpasting the top display causes the underlying displays to be visible.

2.1.3. Repaste Operation

You can move a virtual display to a new location on the pasteboard by calling SMG$REPASTE_VIRTUAL_DISPLAY, which prevents the screen from being left blank during the unpaste and repaste operations. Figure 2.3, “Repaste Operation” shows the effect of repasting the second display farther to the right. Notice that display 2 has been pulled out of its former pasting order and is now uppermost—hiding part of display 3, which was uppermost before the repasting operation.

2.1.4. Move Operation

You can also move a virtual display around the pasteboard while preserving its pasting order by calling the SMG$MOVE_VIRTUAL_DISPLAY routine. Figure 2.4, “Move Operation” shows the effect of moving the second display to the right. Note the difference between the unpaste and move operations: the pasting order does not change with a move. Thus, display 2 remains partially occluded by display 3.

The routine SMG$MOVE_TEXT allows you to move text from one virtual display to another virtual display. Given two points in opposite corners of the rectangle, SMG$MOVE_TEXT determines the desired width and height. This routine moves the attributes of the first virtual display, thus moving the rectangle of text and erasing it from the first virtual display.

2.1.5. Delete and Pop Operations

The unpaste, repaste, and move operations shown thus far do not destroy the virtual displays affected. You can remove and delete a virtual display by calling the SMG$DELETE_VIRTUAL_DISPLAY routine. You can also remove a number of virtual displays from a pasteboard and delete them in a single operation by calling SMG$POP_VIRTUAL_DISPLAY. This routine unpastes and deletes the specified virtual display and all other virtual displays that were pasted after the one specified.

The pop operation is useful in a modular environment. For example, you can call a subroutine and pass only the pasteboard-id upon which it is to produce output. The subroutine then creates additional virtual displays and pastes them to the indicated pasteboard. When the subroutine returns control to its caller, it returns the display-idof the first virtual display it has pasted. The calling program can then undo the effects of the subroutine by calling SMG$POP_VIRTUAL_DISPLAY, passing the identifier of the virtual display returned by the subroutine. This technique minimizes the amount of information to be passed between the calling program and its subroutine. Figure 2.5, “Pop Operation” shows the effects of popping display 2.

2.1.6. Occlusion Check Operation

You may want to know if a display is occluded, as pasted on a given pasteboard. You can find this out by calling the SMG$CHECK_FOR_OCCLUSION routine. For example, in the configuration in Figure 2.6, “Occlusion Check”, displays 1 and 2 would be reported as being occluded, while displays 3 and 4 would be reported as not occluded. You cannot use this test to determine which display is pasted uppermost on the pasteboard; it determines only whether or not the display, as pasted, is occluded.

If you have multiple virtual displays pasted to a pasteboard, you can use SMG$LIST_PASTING_ORDER to determine the order in which virtual displays are pasted. This routine returns the identifier of the first, or bottommost, virtual display pasted. Call SMG$LIST_PASTING_ORDER in a loop until the identifiers of all the succeeding pasted virtual displays are returned.

The routine SMG$LIST_PASTEBOARD_ORDER gives you the inverse of the information returned by SMG$LIST_PASTING_ORDER. SMG$LIST_PASTEBOARD_ORDER returns the identifier of the first, or bottommost, pasteboard to which the specified virtual display is pasted.

This section describes the screen management routines used to perform output through virtual displays.

Writing to a virtual display is similar to writing directly to the terminal. However, writing to a virtual display is done entirely by calling screen management routines. The Screen Management Facility allows you to erase the screen, set the cursor position, and scroll output text. Text is arranged in the virtual display's buffer, so you do not need to paste before it can receive output. When you write to the physical screen, you are limited by the physical boundaries of the screen. Similarly, screen management output operations are confined to the boundaries of the virtual display: you cannot write text beyond the last column of a virtual display.

You cannot see changes to a virtual display on the screen unless the virtual display is pasted to the part of the pasteboard that is visible on the screen. If the virtual display is not pasted, or if it is pasted in a position that is not visible, such changes are reflected only in the internal database that represents the virtual display.

IF SMG$CURSOR_ROW ( Display-id ) > Max-row
THEN
  BEGIN

   .
   .
   .

  END

CALL SMG$RETURN_CURSOR_POS ( Display-id, Cursor-row, Cursor-column )
IF Cursor-row > Max-row
  THEN
    BEGIN

   .
   .
   .

    END

Display_attributes = ( SMG$M_REVERSE OR SMG$M_UNDERLINE )

2.2.7. Drawing and Removing Drawn Lines and Characters

The following routines provide a simple way to construct horizontal and vertical lines:

• SMG$DRAW_LINE constructs either horizontal or vertical lines, given the end points of those lines.

• SMG$DRAW_RECTANGLE draws a rectangle given the position of the upper left-hand corner and the lower right-hand corner.

• SMG$DRAW_CHAR draws one line-drawing character.

If you want to erase a line drawn with SMG$DRAW_LINE or SMG$DRAW_RECTANGLE, use SMG$REMOVE_LINE. This routine removes the line but preserves the line-drawing characters at any line intersections.

Like all screen management routines, these are device independent. If the resulting line is to be drawn on a VT100 terminal, the VT100 line-drawing character set is used. If the same line is drawn on a VT52 terminal (which does not have this hardware capability), the lines are automatically approximated by the use of the plus sign (+), the vertical bar (|), and the dash (--). Your program does not have to supply different character codes for different types of terminals.

In addition, these routines automatically provide an appropriate character at the intersection of two lines. For example, if a program writes a horizontal line directly to the screen and then writes a vertical line that intersects the horizontal line, you would normally see what appears in Figure 2.7, “Lines Drawn Without SMG$DRAW_LINE”.

If these same lines are drawn using SMG$DRAW_LINE, the screen shows what appears in Figure 2.8, “Lines Drawn Without SMG$DRAW_LINE”.

This section describes the screen management routines that control special modes of operation: minimal update, buffering, and whether or not tabs are used in updating. These modes let you optimize the manner in which information is actually written to the screen. To invoke these modes, use the SMG$CONTROL_MODE routine.

Normally, you need not be concerned with these modes; the Screen Management Facility optimizes output so that characters appear to be displayed on the screen immediately. For some applications, however, you may want to take advantage of these mode settings. The following sections describe these modes of operation.

If you want to construct a complex virtual display that requires several scrolling, cursor positioning, and output operations but do not want the interim steps to be visible, you can batch the output operations. Batching a series of operations to a virtual display lets the application hide the interim steps.

You may also want to construct a complex pasteboard image but have it appear on the screen only after the entire picture is complete. Unpasting and repasting leaves the screen blank during the construction process, so in this case you can batch a series of composition operations and let the screen show only the final effect.

The Screen Management Facility provides a mechanism for batching a series of operations at both the virtual display level and the pasteboard level. These are described in the following sections.

Data may be obtained from a virtual keyboard in the following ways:

All read operations can be aborted by calling the SMG$CANCEL_INPUT routine.

You can read information from a workstation terminal's locator device, such as a mouse or a tablet, by calling SMG$READ_LOCATOR. (This routine does not read locator information from the VT300 series terminals.) This routine tells you at which row and column the locator is pointing and which button was pressed.

In the same way that you can retrieve information about and set pasteboard characteristics, the Screen Management Facility also provides routines that let you retrieve and set the characteristics of a virtual keyboard.

The SMG$GET_KEYBOARD_ATTRIBUTES routine retrieves requested information about a virtual keyboard. It deposits this information in a user-supplied area called the keyboard information table (KIT). The information returned includes the following:

You can use SMG$SET_KEYPAD_MODE to set the terminal's numeric keypad to either numeric or applications mode. In applications mode, numeric keypad keys are considered function keys and may be used as terminators. In numeric mode, these keys are equivalent to the corresponding keys on the main keyboard. Note that the terminal must support applications mode, or the call to SMG$SET_KEYPAD_MODE will fail.

In addition to the functions provided by SMG$READ_STRING, line composition with keypad keys provides a powerful and flexible tool for applications that have line-oriented commands (for example, utilities that use the Command Definition Utility). (See the VSI OpenVMS Command Definition, Librarian, and Message Utilities Manual for more information.)

With line composition, you can define certain keys (discussed below) to be equivalent to a string of characters. When you enter a line and press one of these keys, the equivalence string for that key is inserted into the returned command string. For example, if the application defines the key PF2 to have the equivalence string "HELP", then when you press the PF2 key, that command is returned to the application. You can also specify that the equivalence string be echoed; in this case, the string "HELP" is echoed. The recognition of keypad keys and the insertion of the equivalence string are handled automatically by SMG$READ_COMPOSED_LINE; the application treats the returned line just as if you had typed the entire line.

Key definitions are placed in a key definition table, which is created by a call to SMG$CREATE_KEY_TABLE. Key definitions can be added to and deleted from the table by calls to SMG$ADD_KEY_DEF and SMG$DELETE_KEY_DEF. Key definitions can also be added by calls to SMG$DEFINE_KEY and SMG$LOAD_KEY_DEFS; these routines accept a DCL command DEFINE/KEY (or a file of these commands). See the description of these routines for more information; see the VSI OpenVMS DCL Dictionary for an explanation of the DEFINE/KEY command.

All keyboard keys can be defined by calling SMG$ADD_KEY_DEF and can be used with SMG$READ_COMPOSED_LINE. Other definable keys include the function and keypad keys listed in Table 3.1, “Terminator Values”, the control key sequences (Ctrl/A through Ctrl/Z), and line editing keys if line editing is disabled.

A key definition has several attributes. The TERMINATE attribute specifies whether the input line is terminated when this key is pressed; the NOTERMINATE attribute specifies that more characters and keystrokes may be entered. TERMINATE is the default.

The ECHO attribute specifies whether the equivalence string is echoed when the key is pressed. ECHO is the default.

The PROTECT attribute specifies whether this key definition can be changed or deleted once it is defined. NOPROTECT is the default.

The remaining attributes are LOCK_STATE, IF_STATE, and STATE. They are described in the following section.

A given key may have many definitions, depending on the value of the current state; the state is used to determine the meaning of the key. For example, if PF1 is defined as setting the state to "GOLD" and if PF2 with IF_STATE="GOLD" is defined as "HELP *", pressing PF1 and then PF2 would result in "HELP *" being returned as the command line. Note that in this case the PF1 definition would have no equivalence string and would specify the NOTERMINATE attribute.

A state name is any string comprising up to 31 alphanumeric characters, and can include the dollar sign ($) and underscore (_). When a line is being composed from normal keystrokes and equivalence strings, SMG$READ_COMPOSED_LINE maintains a string called the current state name. Before the first key is pressed, the current state is "DEFAULT". If you press a key whose definition has specified a value for the STATE attribute, the current state is changed to the specified state. Unless you specify the LOCK_STATE attribute, the state name reverts to "DEFAULT" after the next defined key is pressed.

A terminator ends a transfer of data from the virtual keyboard. A terminator may be a single character such as a carriage return or Ctrl/Z, a character sequence (escape sequence) generated by pressing a function key on a keyboard, or a condition such as timeout or buffer full.

The terminator is not part of the data read from the virtual keyboard; it is returned to the caller in a separate argument as an integer (unsigned word) value.

3.6.2. Character Sequence Terminators

Character sequence terminators are returned in a device-independent fashion. The codes are in the form SMG$K_TRM_keyname (for example, SMG$K_TRM_DELETE). A unique code is assigned to each possible function key on VT220 (and VT200-compatible) terminals. Key codes on other terminals are returned using the code of the equivalent VT220 key. Therefore, the application program need not know which type of terminal is being used; the screen management routines transparently map the different terminator character sequences into a uniform set of function codes.

Table 3.1, “Terminator Values” lists the terminator name or condition for each terminator that is not a single character. The table also lists the code and the key legend for each terminator on the different types of terminals supported by the screen management input routines.

Key Name	Value	VT200 and VT300 Series	VT100	VT52
Keypad Keys
DELETE	SMG$K_TRM_DELETE		DELETE	DEL
PF1	SMG$K_TRM_PF1	PF1	PF1	Blue
PF2	SMG$K_TRM_PF2	PF2	PF2	Red
PF3	SMG$K_TRM_PF3	PF3	PF3	Black
PF4	SMG$K_TRM_PF4	PF4	PF4
KP0	SMG$K_TRM_KP0?	0	0	0
KP1	SMG$K_TRM_KP1?	1	1	1
KP2	SMG$K_TRM_KP2?	2	2	2
KP3	SMG$K_TRM_KP3?	3	3	3
KP4	SMG$K_TRM_KP4?	4	4	4
KP5	SMG$K_TRM_KP5?	5	5	5
KP6	SMG$K_TRM_KP6?	6	6	6
KP7	SMG$K_TRM_KP7?	7	7	7
KP8	SMG$K_TRM_KP8?	8	8	8
KP9	SMG$K_TRM_KP9?	9	9	9
ENTER	SMG$K_TRM_ENTER?	ENTER	ENTER	ENTER
MINUS	SMG$K_TRM_MINUS?	—	—
COMMA	SMG$K_TRM_COMMA?	,	,
PERIOD	SMG$K_TRM_PERIOD?	.	.
Cursor Positioning Keys
UP	SMG$K_TRM_UP	Up arrow	Up arrow	Up arrow
DOWN	SMG$K_TRM_DOWN	Down arrow	Down arrow	Down arrow
LEFT	SMG$K_TRM_LEFT	Left arrow	Left arrow	Left arrow
RIGHT	SMG$K_TRM_RIGHT	Right arrow	Right arrow	Right arrow
Function Keys
F6	SMG$K_TRM_F6	F6
F7	SMG$K_TRM_F7	F7
F8	SMG$K_TRM_F8	F8
F9	SMG$K_TRM_F9	F9
F10	SMG$K_TRM_F10	F10
F11	SMG$K_TRM_F11	F11
F12	SMG$K_TRM_F12	F12
F13	SMG$K_TRM_F13	F13
F14	SMG$K_TRM_F14	F14
HELP	SMG$K_TRM_HELP?	HELP
DO	SMG$K_TRM_DO?	DO
F17	SMG$K_TRM_F17	F17
F18	SMG$K_TRM_F18	F18
F19	SMG$K_TRM_F19	F19
F20	SMG$K_TRM_F20	F20
Editing Keys
FIND	SMG$K_TRM_FIND	Find
INSERT_HERE	SMG$K_TRM_INSERT_HERE	Insert Here
REMOVE	SMG$K_TRM_REMOVE	Remove
SELECT	SMG$K_TRM_SELECT	Select
PREV_SCREEN	SMG$K_TRM_PREV_SCREEN	Prev Screen
NEXT_SCREEN	SMG$K_TRM_NEXT_SCREEN	Next Screen
Conditions
CANCELED	SMG$K_TRM_CANCELLED
TIMEOUT	SMG$K_TRM_TIMEOUT
BUFFER_FULL	SMG$K_TRM_BUFFER_FULL
UNKNOWN	SMG$K_TRM_UNKNOWN?

The Screen Management Facility allows you to access and change the contents of the application recall buffer. By default, the recall buffer stores the previous 20 commands or data lines entered by the user to the application.

The SMG$RETURN_INPUT_LINE routine lets you request a particular line from the recall buffer. You can either specify the appropriate line number for the line to be recalled, or you can specify a match string. If you use a match string, SMG$RETURN_INPUT_LINE searches for and returns the line that matches the specified string. This routine aids in the implementation of a DCL-style RECALL command.

The SMG$REPLACE_INPUT_LINE routine lets you replace the specified line or lines in the recall buffer with the specified string. The remaining lines of the recall buffer are deleted. This routine aids in processing line continuations.

SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING, and SMG$READ_VERIFY accept an optional display-id argument. If a display-id is supplied, it designates the virtual display in which the input operation should occur. By specifying display-id, you enable the Screen Management Facility to remain aware of the changes caused by character echoing. If you omit display-id, the Screen Management Facility assumes that screen management output is not being used.

Note that if the display-id argument is specified for any one of the above-mentioned input routines, then the length of the prompt string plus the input is limited to the number of columns in the display or, where specified, to the maximum number of characters to be read. (In the case of SMG$READ_KEYSTROKE, this restriction applies only to the length of the prompt string.)

The following types of asynchronous events can disrupt the screen image:

The Screen Management Facility lets you use a subprocess to execute DCL commands from an application. Only one subprocess is allowed per virtual display.

$ SHOW PROCESS/SUB
$ STOP/IDENT=xxxx

The Screen Management Facility lets you move the cursor to a specified location on the physical screen. It does so through the SMG$SET_PHYSICAL_CURSOR routine. However, if you attempt to move the cursor to a pasteboard position outside the screen boundaries, an error is returned.

The Screen Management Facility supplies an exit handler, which is invoked before image termination. This handler deletes all pasteboards and virtual keyboards associated with the current image and resets the terminal characteristics. The Screen Management Facility's exit handler may or may not be invoked before any user-supplied exit handlers. Therefore, you should not delete pasteboards or virtual displays from inside a user-supplied exit handler because they may already have been deleted by the Screen Management Facility exit handler and their identifiers deassigned.

TERMTABLE.EXE is a database containing information about any number of different types of terminals. You extract information from this database with these steps:

When using screen management routines to perform I/O to foreign terminals, you need only create the proper TERMTABLE entries for the foreign terminals you use. The steps listed above are necessary only when your program performs I/O directly to foreign terminals.

The first step can be performed in either of two ways. You can either pass a string that contains a terminal name (for example, "VT100") to the SMG$INIT_TERM_TABLE routine, or you can pass a value returned by the OpenVMS system service $GETDVI to the SMG$INIT_TERM_TABLE_BY_TYPE routine. The returned value may be a symbolic terminal type (for example, TT$_VT100 or TT$_VT52) or a value assigned by the SMG$ foreign terminal routines to designate a particular foreign terminal.

The second step requires that you call the SMG$GET_TERM_DATA routine. This routine extracts a command string (for example, an escape sequence) from TERMTABLE and stores it in a buffer you provide. It is then your responsibility to write the command string to the terminal. It may be necessary to call SMG$GET_TERM_DATA many times; each time you receive the command sequence you can perform a different operation. You should also call SMG$GET_TERM_DATA each time you want to use a capability string that requires a substitution or arithmetic operation for an argument. However, you may want to save the static capability strings in your program's local storage. These static capability strings can be retrieved once and used any number of times.

The third step is optional; it merely frees the virtual memory used to access the information in the database.

The DCL commands SET and SHOW TERMINAL recognize any name defined in TERMTABLE, as well as the current set of valid OpenVMS terminal names. If you use the SET TERMINAL/DEVICE=name command to specify a terminal that is unknown to the OpenVMS operating system, the TERMTABLE database is searched for the named terminal.

Two routines are provided to obtain the address of a specific terminal definition. SMG$INIT_TERM_TABLE accepts a terminal name as input; SMG$INIT_TERM_TABLE_BY_TYPE accepts a device type as input. Each maps to a specific terminal entry in the TERMTABLE.EXE section. These routines return this identifier to the caller for use in future calls.

SMG$GET_TERM_DATA accepts the identifier of the compiled TERMTABLE database and a request code. The request code is used as an index into the data to retrieve the appropriate escape sequence. Some sequences are static; they do not contain any variable information and are simply copied into the caller's buffer. Variable sequences, which include a ! or % directive, cause additional processing to take place. An example of a variable sequence is the VT300-series set cursor command: the required binary row and column numbers must be converted to ASCII for the set cursor sequence. SMG$GET_TERM_DATA uses the optional input arguments to do the conversion before copying the sequence to the caller's buffer.

If you do not provide any optional input arguments to SMG$GET_TERM_DATA, it uses a default of 1 for each argument that the capability requires. Nevertheless, you cannot supply some of the optional arguments and accept the default for others—you must supply all or none of them. SMG$GET_NUMERIC_DATA provides a simplified interface for users who wish to obtain numeric or Boolean data only.

When all terminal I/O has been completed, SMG$DEL_TERM_TABLE can be called to release the virtual memory used. This routine is useful only if you do not need TERMTABLE for the duration of your program; releasing virtual memory may make it available for reuse by your program.

A skeleton TERMTABLE.TXT is supplied in SYS$SYSTEM:. SMGTERMS.TXT, which defines non-foreign terminals, is also provided. The skeleton TERMTABLE.TXT uses the REQUIRE directive to include the separate source file SMGTERMS.TXT. Thus, only third-party terminals are actually defined in the TERMTABLE.TXT source file.

If you have a foreign (third-party) terminal, the Screen Management Facility does not know what your terminal can and cannot do—in other words, what the terminal's capabilities are. Capability fields let you tell the Screen Management Facility what capabilities are supported for your foreign terminal. These fields let SMG$ use your terminal capabilities rather than emulate common terminal functions, which in turn improves SMG$'s performance.

Three types of capability fields are allowed in a TERMTABLE entry:

The following sections describe these capability fields in detail.

Functions that are common to most terminals have been chosen as possible fields; not all functions of all terminal types are represented. (Specifically, there is no support for block mode, graphics, or typesetting composition functions.) Screen-oriented applications should be planned around typical terminal functions, and should not depend on features that exist on only one or a few models.

For applications that must support an unusual terminal, some generic capability names are reserved for user definition. Names of the form PRIVATE_BOO_n, PRIVATE_NUM_n, and PRIVATE_STR_n, where n is a number from 1 to 10, may be included as user-defined terminal definitions and returned by the TERMTABLE interface routines. Since meanings are assigned by the user, private capabilities vary between applications. Sites running several applications must guard against multiple definitions for a single private capability. (For example, you should include separate terminal entries for a terminal that requires PRIVATE_STR_1 to mean two different things, depending on the application program being run.) In general, you should not have to use private capabilities.

The following characters are used as delimiters in capability fields:

BOOLEAN {Boolean-capability = binary-digit} [,...]

NAME = "VT300_series"

  BOOLEAN

    ansi_crt = 1,         dec_crt = 1

NUMERIC {numeric-capability = value} [,...]

NAME = "VT300_series"

  NUMERIC

    rows = 24,         columns = 80

NAME = "VT300_series"

  .
  .
  .

    STRING
        begin_alternate_char = "^N",
        end_alternate_char = "^O",
        erase_whole_display = "$[2J"

  .
  .
  .

END

NAME = "VT300_series"

  .
  .
  .

    STRING
    set_cursor_abs = "$[!UL;!ULH"

  .
  .
  .

END

NAME = "VT52"

  .
  .
  .

    STRING
    set_cursor_abs = "$Y(%1+31)(%2+31)"

  .
  .
  .

END

The source code for the database is an ASCII file named TERMTABLE.TXT. This file contains an entry for each type of terminal. Each entry lists a terminal's capabilities and other device-specific information, such as initialization sequences and screen size; a TERMTABLE entry can span more than one record in the file. A terminal definition can be added by editing the TERMTABLE.TXT file; TERMTABLE.TXT must then be reprocessed by running SYS$SYSTEM:SMGBLDTRM.EXE.

TERMTABLE.TXT can be created with any text editor. A TERMTABLE entry consists of a terminal name, followed by any number of capability fields and their values (see Section 5.2, “Capability Fields” for more information about capability fields). Although TERMTABLE.TXT must be formatted for compilation, capability names are descriptive and can be easily understood. Terminal names must be unique; for example, if more than one definition is needed for a foreign terminal, then a second name must be used.

When a TERMTABLE routine first searches for a terminal entry, it tries to find TERMTABLE.EXE in the area logically named TERM$TABLOC. If the specified terminal entry is not found there, the routine then searches for TERMTABLE.EXE in SYS$SYSTEM. If you want to use a terminal definition that differs from the system definition for that terminal, you can create a private copy of TERMTABLE.TXT and TERMTABLE.EXE. You can then define a single terminal with a definition that is different from the one in SYS$SYSTEM:TERMTABLE.EXE and still use the rest of the standard system definitions.

NAME = "terminal-name" capability-field [,...] END

REQUIRE "filespec"

In the above format, "filespec" is a valid OpenVMS file specification.

!
!       Private versions of terminal definitions
!
NAME = 'myvt300'

        BOOLEAN
        ansi_crt = 1,           dec_crt = 1

        NUMERIC
        rows = 24,              columns = 80,
        wide_screen_columns = 132

        STRING
        begin_alternate_char = "^N",
        end_alternate_char = "^O",
        erase_whole_display = "$[2J",
        init_string = "$_(B",
        set_cursor_abs = "$[!UL;!ULH"
END

NAME = "MYVT52"

        BOOLEAN
        ansi_crt = 0,           dec_crt = 1

        NUMERIC
        rows = 24,              columns = 80,
        wide_screen_columns = 80

        STRING
        begin_alternate_char = "$F"
        end_alternate_char = "$G",
        erase_whole_display = "$Y(32)(32)$J",  !position to 1,1; then erase
        set_cursor_abs = "$Y(%1+31)(%2+31)"

END

For the set cursor sequence listed for a VT300 series (MYVT300), the string returned depends on the values provided in the argument vector supplied with the call to the SMG$GET_TERM_DATA routine. For example, to position the cursor to row 3 and column 12, you supply these longword values as the second and third entries in the vector (the first entry is the number of values that follow). The SMG$GET_TERM_DATA routine converts these longword values into their ASCII values and inserts the converted values into the string returned at the point of the respective !UL directives.

For the set cursor sequence listed for a VT52 (MYVT52), the string returned depends not on argument substitution, but on an arithmetic operation (because the VT52 requires biasing). The arithmetic operator is used to add 31 (decimal) to the row and column numbers supplied in entries 2 and 3 of the argument vector for the SMG$GET_TERM_DATA routine.

The INIT_STRING field in MYVT300 is included to point out that the parenthesis is normally treated as a special character indicating an arithmetic expression. A parenthesis must be preceded by an underscore in order to be interpreted as a normal text character. Thus the string "$_(B" yields ESC(B, a command that designates the ASCII character set into G0.

The ERASE_WHOLE_DISPLAY sequence for MYVT52 shows that it may be necessary to combine sequences in order to provide a certain function. The VT52 does not have a command that erases the entire screen. However, you can erase the entire screen by homing the cursor and then using the command that erases from the current position to the end of the screen.

10  ! Program to call the Termtable interface routines
    !
    ! This program sets the cursor to row 12 column 1,
    ! and erase to the bottom of the screen.  If the cursor
    ! positioning or erasing to the end of the screen
    ! capabilities are not defined, a message is output.

    %INCLUDE "$SMGTRMPTR" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
    OPTION TYPE = EXPLICIT, SIZE = INTEGER LONG

    EXTERNAL INTEGER FUNCTION SYS$ASSIGN, SYS$DASSGN, SYS$QIOW
    EXTERNAL INTEGER FUNCTION LIB$GETDVI, LIB$GET_EF, LIB$FREE_EF
    EXTERNAL INTEGER FUNCTION SMG$INIT_TERM_TABLE_BY_TYPE, SMG$GET_TERM_DATA

    EXTERNAL INTEGER CONSTANT IO$_WRITEVBLK, DVI$_DEVTYPE

    COMMON (buf) STRING Data_buffer = 20         ! buffer to hold terminal data

    DECLARE INTEGER Sys_status,                   &
                    Chan,                         &
                    Term_type,                    &
                    Term_table_addr,              &
                    Arg_vector (2),               &
                    Ret_len,                      &
                    Event_flag

    ! Assign a channel for LIB$GETDVI and SYS$QIOW.

    Sys_status = SYS$ASSIGN ('SYS$OUTPUT', Chan, , , )

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Error from SYS$ASSIGN : ";Sys_status
      GOTO Done
    END IF

    ! Get the terminal type.

    Sys_status = LIB$GETDVI (DVI$_DEVTYPE   ! request item code              &
                             ,Chan          ! channel assigned to SYS$OUTPUT &
                             ,              ! omit device name               &
                             ,Term_type)    ! place to return type

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Error from LIB$GETDVI : ";Sys_status
      GOTO Done
    END IF

    ! Get the definition for the type of terminal we are running on.

    Sys_status =  SMG$INIT_TERM_TABLE_BY_TYPE (Term_type, Term_table_addr)

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Error getting terminal definition : ";Sys_status
      GOTO Done
    END IF

    ! Get the sequence to position the cursor to 12,1

    Arg_vector (0) = 2%             ! number of args to follow
    Arg_vector (1) = 12%            ! row number
    Arg_vector (2) = 1%             ! column number

    Sys_status = SMG$GET_TERM_DATA                                        &
                    ( Term_table_addr       ! addr of terminal definition &
                      ,SMG$K_SET_CURSOR_ABS ! request code                &
                      ,20%                  ! max buffer length           &
                      ,Ret_len              ! length of sequence returned &
                      ,Data_buffer BY REF   ! buffer to hold sequence     &
                      ,Arg_vector (0) )     ! optional vector with
                                            ! row and column numbers

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Error getting cursor sequence : ";Sys_status
      GOTO Done
    END IF

    IF Ret_len = 0%
    THEN
      PRINT "Cursor sequence not available"
      GOTO Done
    END IF

    ! Get a unique event flag number

    Sys_status = LIB$GET_EF (Event_flag)

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Unable to allocate an event flag"
      GOTO Done
    END IF

    ! Output the cursor sequence to the terminal.

    Sys_status = SYS$QIOW ( Event_flag BY VALUE     ! event flag number  &
                            ,Chan BY VALUE          ! channel number     &
                            ,IO$_WRITEVBLK BY VALUE ! function code      &
                            , , ,                   ! no iosb,           &
                                                    ! ast routine,       &
                                                    ! or  argument       &
                            ,Data_buffer BY REF     ! buffer to output   &
                            ,Ret_len BY VALUE       ! bytes returned     &
                            , , , , )               ! null arguments

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Error from SYS$QIOW : ";Sys_status
      GOTO Done
    END IF

    ! Get the sequence to erase from current cursor to end of screen.

    Sys_status = SMG$GET_TERM_DATA                                           &
                         ( Term_table_addr ! addr of terminal definition     &
                           ,SMG$K_ERASE_TO_END_DISPLAY ! request code        &
                           ,20%                        ! max buffer length   &
                           ,Ret_len                    ! bytes returned      &
                           ,Data_buffer BY REF)        ! buffer for sequence

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Error getting erase sequence : ";Sys_status
      GOTO Done
    END IF

    IF Ret_len = 0%
    THEN
      PRINT "Erase sequence not available"
      GOTO Done
    END IF

    ! Output the erase sequence to the terminal.

    Sys_status = SYS$QIOW (Event_flag BY VALUE          ! event flag number    &
                                ,Chan BY VALUE          ! channel number       &
                                ,IO$_WRITEVBLK BY VALUE ! function code value  &
                                , , ,                   ! no iosb,             &
                                                        ! ast routine,         &
                                                        ! or  argument         &
                                ,Data_buffer BY REF     ! buffer to output     &
                                ,Ret_len BY VALUE       ! bytes in buffer      &
                                , , , , )               ! null arguments

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Error from SYS$QIOW : ";Sys_status
      GOTO Done
    END IF

    ! Deassign the channel.

    Sys_status = SYS$DASSGN (Chan BY VALUE)

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Error from SYS$DASSGN : ";Sys_status
      GOTO Done
    END IF

    ! Deallocate event flag so other programs can use it.

    Sys_status = LIB$FREE_EF (Event_flag)

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Unable to deallocate event flag"
      GOTO Done
    END IF

32767  Done: END

Accessing an ASCII file for each screen program is inefficient because the ASCII text must be processed as binary information before it can be returned as a string ready for the terminal. To avoid paying the price of this processing at the start of every image, TERMTABLE.TXT is "precompiled" into the required binary format. A screen application then gets its terminal sequences from the precompiled binary capabilities file.

Compile TERMTABLE.TXT by running the SYS$SYSTEM:SMGBLDTRM.EXE program. This utility accepts TERMTABLE.TXT as an input file and creates TERMTABLE.EXE as an output file on the device and directory pointed to by the logical TERM$TABLOC.

The compiled terminal capabilities are stored as a table in a file which is mapped as a permanent global section. Thus, user programs map to the global section rather than having their own copies of the capabilities data.

If a user compiles a private TERMTABLE.TXT from his or her own directory, the interface routines access it by mapping it as a temporary section. TERMTABLE interface routines look for a definition in the temporary section before looking in the system's permanent global section.

Note that system managers may want to coordinate terminal definitions so that nonstandard definitions are confined to a user's private area.

Most users do not have the privilege to create a permanent global section. A short program, SYS$SYSTEM:SMGMAPTRM.EXE, that maps the compiled TERMTABLE as a global section, is part of the standard OpenVMS startup procedure. In order to map an updated TERMTABLE.EXE as the global section, the existing global section must first be deleted. Deleting the global section while the system is active may cause a user's program to fail; therefore the system must be rebooted in order to make an updated TERMTABLE.EXE the default.

To reduce compiling time and the size of the resulting global section, the terminal definitions in SYS$SYSTEM:TERMTABLE.TXT should be kept to a minimum. Only the types of terminals that are actually attached to the computer system should be defined.

The tables in Section 5.2, “Capability Fields” show whether or not the Screen Management Facility can request a particular capability string. Some functions, such as wide characters or line drawing, are requested only if the user calls the screen management routines that output wide text or draw lines. If all you want to do is write normal text to the screen, only the following set of fields needs to be defined.

Essential Capabilities

If SET_CURSOR_ABS is omitted, the Screen Management Facility treats the terminal as a hardcopy device. (For more information on using the Screen Management Facility with a hardcopy device, refer to the SMG$SNAPSHOT routine.

Operation of the Screen Management Facility is more efficient if the following optional capabilities are also provided:

If you do not include ERASE_TO_END_DISPLAY, ERASE_TO_END_LINE, or SET_SCROLLING_REGION, the Screen Management Facility inserts blanks to perform these functions. However, inserting blanks is a slower operation. Similarly, hardware scrolling also improves output speed; if scrolling is not available, the Screen Management Facility must rewrite the entire screen.

The Screen Management Facility uses the ASCII character set. If your terminal has a line-drawing character set, you should define the line drawing characters (bottom_t_char, horizontal_bar, and so forth). If line-drawing characters are not defined, the Screen Management Facility uses normal ASCII characters to draw borders.

The Screen Management Facility also relies on the terminal characteristics maintained by the terminal driver. You can change these characteristics with the DCL command SET TERMINAL. For example, if you type SET TERMINAL/NOTAB, then the Screen Management Facility does not send tabs to the terminal.

A foreign terminal is any terminal for which the device type is not one of the standard terminals recognized by the OpenVMS operating system, or any terminal on which the ANSI_CRT characteristic is not set.

When you use an ANSI terminal, typing a special key such as a function key or a keypad key sends an escape sequence (as defined by the ANSI standard) to the OpenVMS terminal driver. The OpenVMS terminal driver understands this ANSI standard and interprets the escape sequence according to this standard. Thus, the OpenVMS terminal driver knows how long the escape sequence is and what characters are allowed in which positions in that sequence.

The OpenVMS terminal driver does not echo any of the printing characters from the sequence because those characters are interpreted with special meaning as part of the escape sequence. Normal keys are echoed unless the TRM$M_TM_NOECHO modifier is specified.

The OpenVMS terminal driver returns to the Screen Management Facility the sequence, the length of the sequence, and the number of characters entered before the function key was pressed. The Screen Management Facility determines which key was pressed by comparing the sequence and its length against the list of key definitions for that particular terminal in TERMTABLE.EXE. This code is returned to the user in the format SMG$K_TRM_xxx, where xxx is used to specify the particular key.

When you press a special key such as a function key or a keypad key on a foreign terminal, a non-ANSI sequence is sent to the OpenVMS terminal driver. If this sequence starts with a control character, the OpenVMS terminal driver interprets this character as a terminator. (By default all control characters are terminators unless you use a terminator mask to specify otherwise.) The terminal driver then stops reading characters and returns to the Screen Management Facility the character, a length of 1, and the number of characters entered before the function key was pressed.

The Screen Management Facility looks at the returned character. If it is a control character, the Screen Management Facility looks in the type-ahead buffer for the next characters of the sequence. If there are characters in the type-ahead buffer, the Screen Management Facility reads one character from the type-ahead buffer, appends it to the control sequence it has already, and checks this new sequence against the list of key definitions for this terminal in TERMTABLE.EXE to determine which key was pressed. If the sequence is not matched, the next character is read from the type-ahead buffer. This continues until a match is found or the type-ahead buffer is empty. Since the terminal driver does not know about this sequence, any printable characters in the sequence are echoed by the terminal driver unless the noecho modifier was specified by the user. Because the Screen Management Facility does not know what characters make up this sequence, it disables line editing in order to allow the actual characters that make up the sequence to be returned to the Screen Management Facility.

Terminals whose special keys send a sequence that does not start with a control character are not supported by the Screen Management Facility for input. Changing the terminator mask to exclude the control character that starts the function key sequence is not supported. In addition, the performance of a foreign terminal doing input will not match that of a non-foreign terminal doing the same input since SMG$ must parse the sequence in place of the OpenVMS terminal driver.

The DCL command SET TERMINAL is the mechanism for setting your terminal to conform to a TERMTABLE definition. SET TERMINAL causes the following three fields to be retrieved from the TERMTABLE database and set for your terminal:

In addition, if the corresponding Boolean capability is set in the terminal definition, the following flags are set:

If any of these fields is missing from your definition, the previous setting for that characteristic is retained; SET TERMINAL does not try to set that characteristic for your terminal. You should include all of the above capabilities in your definitions to avoid unpredictable settings.

SET TERMINAL operates as it always has for known terminals such as the VT300 series, VT200 series, VT100, and VT52. When SET TERMINAL encounters an unknown device name, it searches TERMTABLE for a definition with that name. Notice that your definitions must have names other than the names that SET TERMINAL currently recognizes. The terminals currently recognized are listed as follows:

If SET TERMINAL finds the device name in its own internal tables, it does not search the TERMTABLE database.

Since the SET TERMINAL command recognizes only the first 15 characters of a device name, you may want to limit your terminal names to 15 characters.

The SET TERMINAL/DEVICE=name command causes the TERMTABLE database to be searched for the named terminal, if that terminal is unknown to the OpenVMS operating system. SET TERMINAL/DEVICE=name then sets various terminal characteristics, as shown in the following table, based on the presence of these capabilities in the TERMTABLE database:

The SET TERMINAL/DEVICE_TYPE=format must be used with TERMTABLE terminals. SET TERMINAL/name is an old format that works for a small set of device names and is maintained only for compatibility with previous versions of the OpenVMS operating system.

There are two ways in which an application can call screen management routines.

In either case, the calling routine is likely at some point to call a subsystem so that the subsystem can write data to the screen.

At some later point, the terminal user will want to remove the subsystem-specific display. However, if the subsystem created and used a virtual display to display the data, the display identifier is not available to the calling program and therefore the calling program cannot remove it. Furthermore, unless the calling program is a direct user of the Screen Management Facility, the screen's pasteboard identifier is also not available to it.

The solution is to require that all callable routines that use the Screen Management Facility, directly or indirectly, have an (optional) input argument for the pasteboard-id and an (optional) output argument for the virtual display-id. Passing the pasteboard and display identifiers lets you avoid accumulating subsystem-specific data on the screen that cannot be removed by the calling program.

These guidelines are developed as follows:

By adhering to the following guidelines, you can develop your application in a modular fashion:

A different situation exists if you call a subroutine (or subsystem) that writes to the screen without using the Screen Management Facility. When the Screen Management Facility is bypassed (that is, when text is placed on the screen outside screen management's control), problems result when an attempt is made to perform a screen update.

For this reason, the Screen Management Facility provides two routines for turning over the screen (or a part of it) temporarily to a program that does not use screen management, and for restoring the screen to its previous state after control is returned from the non-SMG$ routine. These routines are SMG$SAVE_PHYSICAL_SCREEN and SMG$RESTORE_PHYSICAL_SCREEN.

Before you call a routine that performs non-SMG$ I/O to the screen, you should call the SMG$SAVE_PHYSICAL_SCREEN routine, specifying what part of the screen is to be turned over to the non-SMG$ routine. SMG$SAVE_PHYSICAL_SCREEN erases the specified area, sets the terminal's physical scrolling region to this area, and sets the physical cursor to row 1, column 1 of the area. If the non-SMG$ code does only sequential input and output (that is, if it does no direct cursor addressing) its output will be confined to the specified area of the screen.

When control is returned from the non-SMG$ routine, you simply call SMG$RESTORE_PHYSICAL_SCREEN, which restores the screen image as it was before the call to SMG$SAVE_PHYSICAL_SCREEN.