[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

OpenVMS/Hangul RTL Korean Screen Management (SMG$) Manual


Previous Contents


Chapter 3
Korean Screen Management Input Operations

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

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

Note

The Korean 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 Korean 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, Korean 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 Korean 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 Korean 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 Korean 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      

1These are the keys on the numeric keypad, not the main keyboard. These values are used only if the terminal keypad is in applications mode; if the keypad is in numeric mode, the keys are equivalent to the keys with the same legends on the main keyboard. See the description of SMG$SET_KEYPAD_MODE for more information.
2If the keypad is in numeric mode, ENTER is equivalent to a carriage return. See the description of SMG$SET_KEYPAD_MODE for more information.
3HELP and DO are in the F15 and F16 positions on the VT220 keyboard.
4If an unrecognized terminator is received, the value is SMG$K_TRM_UNKNOWN.

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:

Symbol Synonym
SMG$K_TRM_BS SMG$K_TRM_CTRLH
SMG$K_TRM_HT SMG$K_TRM_CTRLI
SMG$K_TRM_LF SMG$K_TRM_CTRLJ
SMG$K_TRM_CR SMG$K_TRM_CTRLM
SMG$K_TRM_E1 SMG$K_TRM_FIND
SMG$K_TRM_E2 SMG$K_TRM_INSERT_HERE
SMG$K_TRM_E3 SMG$K_TRM_REMOVE
SMG$K_TRM_E4 SMG$K_TRM_SELECT
SMG$K_TRM_E5 SMG$K_TRM_PREV_SCREEN
SMG$K_TRM_E6 SMG$K_TRM_NEXTSCREEN
SMG$K_TRM_F15 HELP
SMG$K_TRM_F16 DO


Previous Next Contents