Previous | Contents |
The Add Key Definition routine adds a keypad key definition to a table of key definitions.
SMG$ADD_KEY_DEF key-table-id ,key-name [,if-state] [,attributes] [,equivalence-string] [,state-string]
OpenVMS usage cond_value type longword (unsigned) access write only mechanism by value
key-table-id
OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference
Identifies the key table to which you are adding a key definition. The key-table-id argument is the address of an unsigned longword that contains the key table identifier.Key-table-id is returned by the SMG$CREATE_KEY_TABLE routine.
key-name
OpenVMS usage char_string type character string access read only mechanism by descriptor
Identifies the key whose value you are defining. The key-name argument is the address of a descriptor pointing to this key name. The SMG$ADD_KEY_DEF routine changes the string to uppercase and removes trailing blanks.Table 3-1 in Chapter 3 lists the valid key names.
if-state
OpenVMS usage char_string type character string access read only mechanism by descriptor
Qualifies the value returned when key-name is struck. The if-state argument is the address of a descriptor pointing to the state string.If if-state is specified, this definition of key-name is used only if the current state matches the specified if-state string. The if-state argument must be from 1 to 31 characters in length. If this argument is omitted, if-state defaults to the value "DEFAULT."
attributes
OpenVMS usage mask_longword type longword (unsigned) access read only mechanism by reference
Longword bit mask specifying additional attributes of this key definition. The attributes argument is the address of an unsigned longword that contains this attribute mask. If omitted, the mask is zero.Valid attributes are described in the following list:
SMG$M_KEY_NOECHO If set, this bit specifies that equivalence-string is not to be echoed when this key is pressed. If clear, equivalence-string is echoed. If SMG$M_KEY_TERMINATE is not set, SMG$M_KEY_NOECHO is ignored. SMG$M_KEY_TERMINATE If set, this bit specifies that when this key is pressed (as qualified by if-state) the input line is complete and more characters should not be accepted. If clear, more characters may be accepted. In other words, setting this bit causes equivalence-string to be treated as a terminator. SMG$M_KEY_LOCK If set, and if state-string is specified, the state name specified by state-string remains the current state until explicitly changed by a subsequent keystroke whose definition includes a state-string. If clear, the state name specified by state-string remains in effect only for the next defined keystroke. SMG$M_KEY_PROTECTED If set, this bit specifies that this key definition cannot be modified or deleted. If clear, the key definition can be modified or deleted. The remaining bits are undefined and must be zero. It is possible to perform a logical OR operation on these values to set more than one attribute at a time.
equivalence-string
OpenVMS usage char_string type character string access read only mechanism by descriptor
Character string to be substituted for the keystroke in the returned line. The equivalence-string argument is the address of a descriptor pointing to this equivalence string.Equivalence-string is echoed unless SMG$M_KEY_NOECHO is set. If equivalence-string is omitted, no equivalence string is defined for this key.
state-string
OpenVMS usage char_string type character string access read only mechanism by descriptor
Contains a new state name which becomes the current state when this key is pressed. The state-string argument is the address of a descriptor pointing to the new state string.If omitted, no new state is defined. If the current state is temporary (that is, if SMG$M_KEY_LOCK was not specified for the most recently pressed defined key), the current state-string becomes DEFAULT.
SMG$ADD_KEY_DEF inserts a key definition into a key definition table. The table must have been created with a call to SMG$CREATE_KEY_TABLE. After SMG$ADD_KEY_DEF executes, the specified equivalence string is returned when the user types the specified key in response to the SMG$READ_COMPOSED_LINE routine.You can define all keys on the VT100, VT200-series, and VT300-series keyboards and keypads with the following exceptions:
- The Compose Character key on VT200-series and VT300-series keyboards
- The ESCAPE key
- The SHIFT keys
- The keys F1 through F5 on VT200-series and VT300-series keyboards
There are some keys and key definitions that you can define but that Digital strongly suggests you avoid defining. SMG$ does not return an error when you use them as key names, but the definitions you assign to these key combinations are not executed unless you set your terminal in the following special ways at the DCL level.
- Ctrl/C, Ctrl/O, Ctrl/X, and F6 - To use a definition that you bind to these keys, you must first enter the DCL command SET TERMINAL/PASTHRU.
- Ctrl/T, Ctrl/Y - To use a definition that you bind to these keys, you must first enter either the DCL command SET TERMINAL/PASTHRU or SET NOCONTROL, or both.
- Ctrl/S, Ctrl/Q - To use a definition that you bind to these keys, you must first enter the DCL command SET TERMINAL/NOTTSYNC.
Digital does not recommend that you use these special terminal settings. The settings may cause unpredictable results if you do not understand all the implications of changing the default settings for giving the terminal driver control.
SS$_NORMAL Normal successful completion. SMG$_PREDEFREP Successful completion. The previous key definition has been replaced. SMG$_INVDEFATT Invalid key definition attributes. SMG$_INVKEYNAM Invalid key-name. SMG$_INVKTB_ID Invalid key-table-id. SMG$_KEYDEFPRO Key definition is protected against change or deletion. SMG$_WRONUMARG Wrong number of arguments.
Any condition values returned by LIB$COPY_DXDX.
The Begin Batching of Display Updates routine saves, or batches, all output to a virtual display until a matching call to SMG$END_DISPLAY_UPDATE is encountered.
SMG$BEGIN_DISPLAY_UPDATE display-id
OpenVMS usage cond_value type longword (unsigned) access write only mechanism by value
display-id
OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference
Specifies the virtual display for which output is to be batched. The display-id argument is the address of an unsigned longword that contains the display identifier.Display-id is returned by SMG$CREATE_VIRTUAL_DISPLAY.
SMG$BEGIN_DISPLAY_UPDATE lets you make more than one change to a display and have the changes appear only after all changes are complete. Thus, the user sees the display change from its initial state to its final state, without seeing any of the intermediate states.Batching terminates when SMG$END_DISPLAY_UPDATE has been called the same number of times for a given display as has SMG$BEGIN_DISPLAY_UPDATE. The Chinese Screen Management Facility keeps track of batching for a given display; thus, the calls to the SMG$BEGIN_DISPLAY_UPDATE and SMG$END_DISPLAY_UPDATE need not occur in the same module.
SS$_NORMAL Normal successful completion. SMG$_BATWAS_ON Successful completion; batching has already been initiated. SMG$_WRONUMARG Wrong number of arguments. SMG$_INVDIS_ID Invalid display-id.
The Begin Batching of Pasteboard Updates routine saves, or batches, all output to a pasteboard until a matching call to SMG$END_PASTEBOARD_UPDATE is encountered.
SMG$BEGIN_PASTEBOARD_UPDATE pasteboard-id
OpenVMS usage cond_value type longword (unsigned) access write only mechanism by value
pasteboard-id
OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference
Specifies the pasteboard for which output is to be batched. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.Pasteboard-id is returned by SMG$CREATE_PASTEBOARD.
SMG$BEGIN_PASTEBOARD_UPDATE lets you make more than one change to a pasteboard and have the changes appear only after all changes are complete. Thus, the user sees the pasteboard change from its initial state to its final state, without seeing any of the intermediate states.Batching terminates when SMG$END_PASTEBOARD_UPDATE has been called the same number of times for a given pasteboard as has SMG$BEGIN_PASTEBOARD_UPDATE. The Chinese Screen Management Facility keeps track of batching for a given pasteboard; thus, the calls to the SMG$BEGIN_PASTEBOARD_UPDATE and SMG$END_PASTEBOARD_UPDATE need not occur in the same module.
SS$_NORMAL Normal successful completion. SMG$_BATWAS_ON Successful completion; batching has already been initiated. SMG$_WRONUMARG Wrong number of arguments. SMG$_INVPAS_ID Invalid pasteboard-id.
The Cancel Input Request routine immediately cancels any read-in-progress that was issued by SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, or SMG$READ_STRING.
SMG$CANCEL_INPUT keyboard-id
OpenVMS usage cond_value type longword (unsigned) access write only mechanism by value
keyboard-id
OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference
Specifies the virtual keyboard for which the input is to be canceled. The keyboard-id argument is the address of an unsigned longword that contains the keyboard identifier.Keyboard-id is returned by SMG$CREATE_VIRTUAL_KEYBOARD.
SMG$CANCEL_INPUT causes immediate termination of an SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, or SMG$READ_STRING input operation from a terminal. The condition code SS$_CANCEL or SS$_ABORT is returned to those routines when you use SMG$CANCEL_INPUT.
SS$_NORMAL Normal successful completion. SMG$_INVKBD_ID Invalid keyboard-id. SMG$_WRONUMARG Wrong number of arguments.
The Change Pasteboard Characteristics routine lets you change the characteristics associated with a pasteboard.
SMG$CHANGE_PBD_CHARACTERISTICSpasteboard-id [,desired-width] [,width] [,desired-height] [,height] [,desired-background-color] [,background-color]
OpenVMS usage cond_value type longword (unsigned) access write only mechanism by value
pasteboard-id
OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference
Specifies the pasteboard whose characteristics are to be changed. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.Pasteboard-id is returned by SMG$CREATE_PASTEBOARD.
desired-width
OpenVMS usage longword_signed type longword (signed) access read only mechanism by reference
New width for the pasteboard. The desired-width argument is the address of a signed longword that contains the desired width. If omitted, the width does not change.width
OpenVMS usage longword_signed type longword (signed) access write only mechanism by reference
Receives the physical width of the pasteboard. The width argument is the address of a signed longword into which is written the actual width of the pasteboard.If the terminal cannot be set exactly to desired-width, width may be larger than desired-width. If the physical width of the terminal is smaller than desired-width, width may be smaller than desired-width.
desired-height
OpenVMS usage longword_signed type longword (signed) access read only mechanism by reference
New height for the pasteboard. The desired-height argument is the address of a signed longword that contains the desired height of the pasteboard. If desired-height is omitted, the height does not change.height
OpenVMS usage longword_signed type longword (signed) access write only mechanism by reference
Receives the physical height of the pasteboard. The height argument is the address of a signed longword into which is written the actual height of the pasteboard.If the terminal cannot be set exactly to desired-height, height may be larger than desired-height. If the physical height of the terminal is smaller than desired-height, height may be smaller than desired-height.
desired-background-color
OpenVMS usage longword_unsigned type longword (unsigned) access read only mechanism by reference
Symbolic name for the desired background color. The desired-background-color argument is the address of an unsigned longword that contains the desired color.The symbols listed below are defined in $SMGDEF. Valid values for desired-background-color are as follows:
SMG$C_COLOR_WHITE White background SMG$C_COLOR_BLACK Black background SMG$C_COLOR_BLUE Blue background SMG$C_COLOR_CYAN Cyan (green-blue) background SMG$C_COLOR_GREEN Green background SMG$C_COLOR_MAGENTA Magenta background SMG$C_COLOR_RED Red background SMG$C_COLOR_YELLOW Yellow background SMG$C_COLOR_LIGHT Light background SMG$C_COLOR_DARK Dark background SMG$C_COLOR_USER1 User-defined background 1 SMG$C_COLOR_USER2 User-defined background 2 If you omit desired-background-color, or if the terminal hardware does not support the background color specified, the background color is not changed.
background-color
OpenVMS usage longword_unsigned type longword (unsigned) access write only mechanism by reference
Receives the background color chosen. The background-color argument is the address of an unsigned longword into which is written the background color.This routine may return any of the values listed in the desired-background-color argument description or SMG$C_COLOR_UNKNOWN. If the desired-background-color argument is omitted, the value of background-color does not change.
SMG$CHANGE_PBD_CHARACTERISTICS lets you change the width, height, and background color associated with a pasteboard.If necessary, this routine will notify the OpenVMS operating system of the change in pasteboard characteristics by updating the terminal characteristics displayed when you enter the DCL command SHOW TERMINAL.
Do not use SMG$CHANGE_PBD_CHARACTERISTICS on a batched pasteboard.
SS$_NORMAL Normal successful completion. SMG$_INVCOLARG Unknown background color specified. SMG$_INVPAGARG Invalid height of 0 desired. SMG$_INVWIDARG Invalid width of 0 desired. SMG$_PBDIN_USE Cannot change characteristics while batching is on. SMG$_WRONUMARG Wrong number of arguments. SS$_xxx Any error from $QIOW.
Previous | Next | Contents |