[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

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


Previous Contents

SMG$ Reference Section

This section contains detailed descriptions of all routines provided by the Chinese 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 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.


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


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.


Previous Next Contents