HP OpenVMS Systems Documentation

OpenVMS/Hanzi RTL Chinese Screen Management (SMG$) Manual

This chapter describes the Chinese screen management routines used to perform input from a virtual keyboard. A virtual keyboard is associated with a terminal.

The Chinese Screen Management Facility provides a flexible set of routines for performing input from a terminal. 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 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:

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

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

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: