 |
OpenVMS/Hangul RTL Korean Screen Management (SMG$)
Manual
SMG$ Reference Section
This section contains detailed descriptions of all routines provided by
the Korean RTL Screen Management (SMG$) Facility.
SMG$ADD_KEY_DEF
The Add Key Definition routine adds a keypad key definition to a table
of key definitions.
Format
SMG$ADD_KEY_DEF key-table-id ,key-name [,if-state] [,attributes]
[,equivalence-string] [,state-string]
RETURNS
| OpenVMS usage |
cond_value |
| type |
longword (unsigned) |
| access |
write only |
| mechanism |
by value |
Arguments
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.
Description
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.
Condition Values Returned
|
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.
SMG$BEGIN_DISPLAY_UPDATE
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.
Format
SMG$BEGIN_DISPLAY_UPDATE display-id
RETURNS
| OpenVMS usage |
cond_value |
| type |
longword (unsigned) |
| access |
write only |
| mechanism |
by value |
Arguments
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.
Description
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 Korean 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.
Condition Values Returned
|
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.
|
SMG$BEGIN_PASTEBOARD_UPDATE
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.
Format
SMG$BEGIN_PASTEBOARD_UPDATE pasteboard-id
RETURNS
| OpenVMS usage |
cond_value |
| type |
longword (unsigned) |
| access |
write only |
| mechanism |
by value |
Arguments
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.
Description
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 Korean 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.
Condition Values Returned
|
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.
|
SMG$CANCEL_INPUT
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.
Format
SMG$CANCEL_INPUT keyboard-id
RETURNS
| OpenVMS usage |
cond_value |
| type |
longword (unsigned) |
| access |
write only |
| mechanism |
by value |
Arguments
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.
Description
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.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVKBD_ID
|
Invalid
keyboard-id.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
SMG$CHANGE_PBD_CHARACTERISTICS
The Change Pasteboard Characteristics routine lets you change the
characteristics associated with a pasteboard.
Format
SMG$CHANGE_PBD_CHARACTERISTICS
pasteboard-id [,desired-width] [,width] [,desired-height] [,height]
[,desired-background-color] [,background-color]
RETURNS
| OpenVMS usage |
cond_value |
| type |
longword (unsigned) |
| access |
write only |
| mechanism |
by value |
Arguments
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.
Description
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.
Condition Values Returned
|
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.
|
|
