HP OpenVMS Systems Documentation
OpenVMS/Hanzi RTL Chinese Screen Management (SMG$) Manual
The Chinese Screen Management Facility does not support an RMS file for the input device.
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 Chinese screen
management routines map the different terminator character sequences
into a uniform set of function codes. (See Section 3.5 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 three 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. All read operations can be aborted by calling the SMG$CANCEL_INPUT routine.
The SMG$READ_COMPOSED_LINE and SMG$READ_STRING routines have an
optional argument (character-set) for the character
set of the text to be input. If character-set argument
is omitted, Chinese Screen Management Facility uses the
SMG$DEFAULT_CHARACTER_SET logical name to get the character set of the input text.
Refer to Table 2-1 in Section 2.2.14 for the valid definitions of
the SMG$DEFAULT_CHARACTER_SET logical name. If an invalid character set name is
assigned in SMG$DEFAULT_CHARACTER_SET logical name, or if the logical name is not
defined, the character set name of the input text is unknown.
3.2 Setting and Retrieving Virtual Keyboard Characteristics
In the same way that you can retrieve information about and set pasteboard characteristics, the Chinese Screen Management facility also provides routines that let you retrieve and set the characteristics of a virtual keyboard.
The SMG$GET_KEYBOARD_ATTRIBUTES routine lets you retrieve 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.
3.3 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 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 DEFINE/KEY command (or a file of these commands). See the description of these routines for more information; see OpenVMS DCL Dictionary for an explanation of the DEFINE/KEY command.
The keys that can be defined are function and keypad keys listed in Table 3-1, the control key sequences (Ctrl/A through Ctrl/Z with the exception of Ctrl/M (RETURN)), 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
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. 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.
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 Chinese screen management routines transparently map the different terminator character sequences into a uniform set of function codes.
Input operations terminated by a condition are indicated by the terminator codes SMG$K_TRM_CANCELLED, SMG$K_TRM_TIMEOUT, SMG$K_TRM_BUFFER_FULL, and SMG$K_TRM_UNKNOWN.
For calls to SMG$READ_STRING, the default single terminator characters 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. 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.3 for more information.
The routine SMG$NAME_TO_KEYCODE translates the name of a key on the keyboard to its corresponding terminator code, while SMG$KEYCODE_TO_NAME translates the terminator code to the corresponding name of the key on the keyboard.
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 Chinese screen management input routines.
|Key Name||Value||VT200 and VT300 Series||VT100||VT52|
|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|
Symbolic definitions of the terminator values are provided in Digital-supplied symbol libraries named $SMGDEF (for example, in a MACRO program you would issue a call to $SMGDEF to extract these definitions). The symbol names are of the form SMG$K_TRM_keyname, where keyname is the key name given in Table 3-1. For terminator codes 1 through 26 which correspond to the control sequences Ctrl/A through Ctrl/Z, the key names are CTRLA for Ctrl/A, CTRLB for Ctrl/B, and so on. The following synonyms are also defined: