Document revision date: 19 July 1999

Tabs are used for minimal updating. When you are using tabs, you must ensure that the tab stops are set to the Digital default locations. Do not use tabs if you want to be sure that the application will run regardless of the tab settings the user has set on the terminal.

Any tabs that you output to the screen are converted to eight spaces by SMG$ before being output to the screen. The only exception to this is when using SMG$CREATE_VIRTUAL_DISPLAY with the display-attributes argument set to SMG$M_DISPLAY_CONTROLS. In this case, the tab character is printed rather than interpreted as eight spaces.

2.4 Batching Output Operations

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.

2.4.1 Display Update Batching

The SMG$BEGIN_DISPLAY_UPDATE routine causes output operations to a pasted display to be reflected only in the display's buffers. When all operations to the display are finished, the application can call the SMG$END_DISPLAY_UPDATE routine, which causes the display's buffer to be written to the pasteboard.

The SMG$BEGIN_DISPLAY_UPDATE and SMG$END_DISPLAY_UPDATE routines increment and decrement a counter. When this counter's value is zero, output to the virtual display is immediately sent to the pasteboard. When the counter's value is nonzero, output operations are batched; the display batching level is equal to the counter's value. Notice that the counter mechanism allows a subroutine to request and turn off batching without disturbing the batching level of the calling program.

You can call SMG$FLUSH_DISPLAY_UPDATE in place of a call to SMG$END_DISPLAY_UPDATE that is immediately followed by a call to SMG$BEGIN_DISPLAY_UPDATE, when the batch count is zero, with much better performance than the two calls.

2.4.2 Pasteboard Update Batching

You accomplish pasteboard batching by calling the SMG$BEGIN_PASTEBOARD_UPDATE routine, performing several composition operations, and finally calling the SMG$END_PASTEBOARD_UPDATE routine. The SMG$BEGIN_PASTEBOARD_UPDATE routine causes output operations to be reflected only in the pasteboard buffer, not on the physical screen. The SMG$END_PASTEBOARD_UPDATE routine causes the pasteboard buffer to be written to the physical screen.

The SMG$BEGIN_PASTEBOARD_UPDATE and SMG$END_PASTEBOARD_UPDATE routines increment and decrement a counter. When this counter's value is zero, output to the pasteboard is immediately sent to the physical screen. When the counter's value is nonzero, output operations are batched; the pasteboard batching level is equal to the value of the counter. Notice that the counter mechanism allows a subroutine to request and turn off batching without disturbing the batching level of the calling program.

This chapter describes the screen management routines used to perform input from a virtual keyboard. Remember that while a virtual keyboard is usually associated with a terminal, it may also be associated with any OpenVMS RMS file to which you have access. If the RMS file is on another node in a network, you may need a valid account for that node.

The Screen Management Facility provides a flexible set of routines for performing input from a terminal or a file. The input routines can be used in conjunction with the output routines, or they can be used by themselves. You establish an input source, called a virtual keyboard, by calling the SMG$CREATE_VIRTUAL_KEYBOARD routine. You delete a virtual keyboard by calling the SMG$DELETE_VIRTUAL_KEYBOARD routine.

A virtual keyboard is a logical structure for input operations, just as a pasteboard is a logical structure for output operations. The advantage of using virtual keyboards is device independence. When using the screen management input routines, you need not worry about the type of terminal being used. For example, your program need not know which line terminators a particular terminal uses; the screen management routines map the different terminator character sequences into a uniform set of function codes. (See Section 3.6 for more information about terminator codes.) Virtual keyboards are also important for processing function/keypad keys.

3.1 Obtaining Data from Virtual Keyboards

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

• SMG$READ_STRING reads a string composed of characters and a terminator. This flexible routine provides access to many features of the OpenVMS terminal driver.
• SMG$READ_COMPOSED_LINE reads a line composed of ordinary keystrokes and predefined strings associated with keypad and function keys; it provides an easy way to code an interface for command-oriented utilities by providing single-key command capabilities.
• SMG$READ_KEYSTROKE reads one keystroke entered at the keyboard. It reads function/keypad keys as well as alphanumeric keys.
• SMG$READ_VERIFY reads a string and verifies that string against a user-supplied picture string.

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

3.2 Obtaining Data from a Mouse or Tablet

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.

3.3 Setting and Retrieving Virtual Keyboard Characteristics

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:

• The current device characteristics
• The device class
• The size of the recall buffer
• The physical device type
• The first character in the type-ahead buffer
• The terminal width
• The number of characters in the type-ahead buffer

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.

3.4 Line Composition Using Keypad Keys

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

3.5 States

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.

3.6 Terminators

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.1 Single-Character Terminators

For single-character terminators, the value is the terminator's 8-bit character code. Single-character terminator codes are in the range 0 through 255.

For calls to SMG$READ_STRING and SMG$READ_VERIFY, the default single character terminators are all the characters in the range 0 through 31 except backspace (8), horizontal tab (9), line feed (10), vertical tab (11), and form feed (12). Note that these characters make up the default terminator set for the OpenVMS terminal driver. However, any 8-bit character code is potentially a terminator.

The set of terminator characters may be changed by calls to SMG$READ_STRING or SMG$READ_VERIFY. For calls to SMG$READ_COMPOSED_LINE, the only default single terminator characters are the carriage return (13) and Ctrl/Z (26). Changes to the terminator set for SMG$READ_COMPOSED_LINE are made by key definitions; see the description of line composition in Section 3.4 for more information.

Behavior of input operations may vary in response to a Ctrl/Z. Under certain conditions, a Ctrl/Z in the input stream terminates the current read operation as well as the next read operation. You may need to issue an additional read to satisfy the Ctrl/Z.

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

Table 3-1 Terminator Values

Key Name	Value	VT200 and VT300 Series	VT100	VT52
Keypad Keys
DELETE	SMG$K_TRM_DELETE	< X|	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 1	0	0	0
KP1	SMG$K_TRM_KP1 1	1	1	1
KP2	SMG$K_TRM_KP2 1	2	2	2
KP3	SMG$K_TRM_KP3 1	3	3	3
KP4	SMG$K_TRM_KP4 1	4	4	4
KP5	SMG$K_TRM_KP5 1	5	5	5
KP6	SMG$K_TRM_KP6 1	6	6	6
KP7	SMG$K_TRM_KP7 1	7	7	7
KP8	SMG$K_TRM_KP8 1	8	8	8
KP9	SMG$K_TRM_KP9 1	9	9	9
ENTER	SMG$K_TRM_ENTER 2	ENTER	ENTER	ENTER
MINUS	SMG$K_TRM_MINUS 1	--	--
COMMA	SMG$K_TRM_COMMA 1	,	,
PERIOD	SMG$K_TRM_PERIOD 1	.	.
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 3	HELP
DO	SMG$K_TRM_DO 3	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 4

	privacy and legal statement
5935PRO_003.HTML