OpenVMS RTL Screen Management (SMG$) Manual

Document revision date: 19 July 1999

OpenVMS RTL Screen Management (SMG$) Manual

Contents

Index

SMG$GET_KEYBOARD_ATTRIBUTES

The Get Keyboard Attributes routine gets information about a virtual keyboard and leaves it in a user-supplied area: the keyboard information table (KIT).

Format

SMG$GET_KEYBOARD_ATTRIBUTES keyboard-id ,keyboard-info-table ,keyboard-info-table-size

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

Keyboard identifier. The keyboard-id argument is the address of an unsigned longword containing the identifier of the virtual keyboard from which to read.
Create a virtual keyboard by calling the SMG$CREATE_VIRTUAL_KEYBOARD routine.
keyboard-info-table

OpenVMS usage: unspecified

type: unspecified

access: write only

mechanism: by reference, array reference

Receives the keyboard attributes. The keyboard-info-table argument is the address of a data block into which the keyboard attributes are written.
The KIT is a byte block whose size and field references are described in $SMGDEF. It is the caller's responsibility to allocate the correct size block and to pass its address to this routine.
The values in the keyboard-info-table can be accessed through the following symbolic names:

SMG$L_DEV_CHAR Device characteristics (longword)

SMG$L_DEV_DEPEND Specific characteristics 1 (longword)

SMG$L_DEV_DEPEND2 Specific characteristics 2 (longword)

SMG$L_DEV_DEPEND3 Specific characteristics 3 (longword)

SMG$B_DEV_CLASS Device class (byte) --- for example, DC$_TERM

SMG$B_RECALL_NUM Size of recall buffer (byte)*

SMG$B_DEVTYPE Physical device type (byte) --- for example, TT$_VT100

SMG$B_TYPEAHD_CHAR First character in type-ahead buffer (byte)*

SMG$W_NUM_COLUMNS Terminal width (word)

SMG$W_TYPEAHD_CNT Number of characters in type-ahead buffer (word)*

Items marked with an asterisk (*) will be zero unless the device is a terminal (DEVCLASS = DC$_TERM).
keyboard-info-table-size

OpenVMS usage: longword_unsigned

type: longword (unsigned)

access: read only

mechanism: by reference

Size of the keyboard information table. The keyboard-info-table-size argument is the address of an unsigned longword containing the size of the KIT in bytes.
The size you specify must be exact. You can specify this size with the symbolic constant SMG$C_KEYBOARD_INFO_BLOCK.

Description

SMG$GET_KEYBOARD_ATTRIBUTES retrieves information about a virtual keyboard and leaves this information in the KIT.

Condition Values Returned

SS$_NORMAL Normal successful completion.

SMG$_INVARG KIT is the wrong size.

SMG$_INVKBD_ID Invalid keyboard-id.

Example


10 !+ !This VAX BASIC program demonstrates the use of !SMG$GET_KEYBOARD_ATTRIBUTES. !- OPTION TYPE = EXPLICIT OPTION CONSTANT TYPE = INTEGER %INCLUDE "$SMGDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET" %INCLUDE "$SSDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET" EXTERNAL LONG FUNCTION LIB$SIGNAL( LONG BY VALUE), & SMG$CREATE_VIRTUAL_KEYBOARD( LONG ), & SMG$GET_KEYBOARD_ATTRIBUTES( LONG, ANY, LONG ) DECLARE SMG$ATTRIBUTE_INFO_BLOCK SMG_INFO DECLARE LONG S, KEYBOARD_ID S = SMG$CREATE_VIRTUAL_KEYBOARD( KEYBOARD_ID ) IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL( S ) END IF S = SMG$GET_KEYBOARD_ATTRIBUTES( KEYBOARD_ID, & SMG_INFO, & SMG$C_KEYBOARD_INFO_BLOCK ) IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL( S ) END IF PRINT SMG_INFO::SMG$L_DEV_CHAR ! Device characteristics PRINT SMG_INFO::SMG$L_DEV_DEPEND ! Specific characteristics (1) PRINT SMG_INFO::SMG$L_DEV_DEPEND2 ! Specific characteristics (2) PRINT SMG_INFO::SMG$B_DEV_CLASS ! Device class ( DC$_TERM ) PRINT SMG_INFO::SMG$B_RECALL_NUM ! Size of SMG recall buffer PRINT SMG_INFO::SMG$B_DEV_TYPE ! Device type ( DT$_VT100 ) PRINT SMG_INFO::SMG$B_TYPEAHD_CHAR ! First character in ! typeahead buffer PRINT SMG_INFO::SMG$W_NUM_COLUMNS ! Terminal width PRINT SMG_INFO::SMG$W_TYPEAHD_CNT ! Number of characters in ! typeahead buffer END

10      !+ 
        !This VAX BASIC program demonstrates the use of 
        !SMG$GET_KEYBOARD_ATTRIBUTES. 
        !- 
 
        OPTION TYPE = EXPLICIT 
        OPTION CONSTANT TYPE = INTEGER 
 
        %INCLUDE "$SMGDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET" 
        %INCLUDE "$SSDEF"  %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET" 
 
        EXTERNAL LONG FUNCTION LIB$SIGNAL( LONG BY VALUE),              & 
                               SMG$CREATE_VIRTUAL_KEYBOARD( LONG ),     & 
                               SMG$GET_KEYBOARD_ATTRIBUTES( LONG, ANY, LONG ) 
 
        DECLARE SMG$ATTRIBUTE_INFO_BLOCK SMG_INFO 
        DECLARE LONG S, KEYBOARD_ID 
 
        S = SMG$CREATE_VIRTUAL_KEYBOARD( KEYBOARD_ID ) 
        IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL( S ) END IF 
 
        S = SMG$GET_KEYBOARD_ATTRIBUTES( KEYBOARD_ID, & 
                                           SMG_INFO,      & 
                                           SMG$C_KEYBOARD_INFO_BLOCK ) 
       IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL( S ) END IF 
 
        PRINT SMG_INFO::SMG$L_DEV_CHAR          ! Device characteristics 
        PRINT SMG_INFO::SMG$L_DEV_DEPEND        ! Specific characteristics (1) 
        PRINT SMG_INFO::SMG$L_DEV_DEPEND2       ! Specific characteristics (2) 
        PRINT SMG_INFO::SMG$B_DEV_CLASS         ! Device class ( DC$_TERM ) 
        PRINT SMG_INFO::SMG$B_RECALL_NUM        ! Size of SMG recall buffer 
        PRINT SMG_INFO::SMG$B_DEV_TYPE          ! Device type ( DT$_VT100 ) 
        PRINT SMG_INFO::SMG$B_TYPEAHD_CHAR      ! First character in 
                                                ! typeahead buffer 
        PRINT SMG_INFO::SMG$W_NUM_COLUMNS       ! Terminal width 
        PRINT SMG_INFO::SMG$W_TYPEAHD_CNT       ! Number of characters in 
                                                ! typeahead buffer 
        END

SMG$GET_KEY_DEF

The Get Key Definition routine returns the key definition for a specified key.

Format

SMG$GET_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

Specifies the key table from which you are extracting a definition. The key-table-id argument is the address of an unsigned longword that contains the key table identifier.
The key table identifier is returned by SMG$CREATE_KEY_TABLE.
key-name

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Specifies the name of the key associated with the definition. The key-name argument is the address of a descriptor pointing to the key name.
Table 3-1 lists the valid key names.
if-state

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Specifies the current state name in effect after the key is pressed. The if-state argument is the address of a descriptor pointing to the state name.
See SMG$ADD_KEY_DEF for more information.

attributes

OpenVMS usage: mask_longword

type: longword (unsigned)

access: write only

mechanism: by reference

Receives the attributes bit mask for this key definition. The attributes argument is the address of a longword into which is written the bit mask describing the key's attributes.
Valid values are as follows:

SMG$M_KEY_NOECHO If set, this bit specifies that equiv_string is not to be echoed when this key is pressed. If clear, equiv_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.

SMG$M_KEY_LOCKSTATE If set, and if state-string is specified, the state name specified by state-string remains at 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 key stroke.

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.

equivalence-string

OpenVMS usage: char_string

type: character string

access: write only

mechanism: by descriptor

Receives the equivalence string for this key definition. The equivalence-string argument is the address of a descriptor pointing to the string into which is written the equivalence string.
state-string

OpenVMS usage: char_string

type: character string

access: write only

mechanism: by descriptor

Receives the new state name, if any, which is set by this key definition. The state-string argument is the address of a descriptor pointing to the string into which is written the new state string.

Description

SMG$GET_KEY_DEF returns the key definition associated with a specified key-name and if-state. This key definition may be used in calls to SMG$READ_COMPOSED_LINE.

Condition Values Returned

SS$_NORMAL Normal successful completion.

SMG$_INVKEYNAM Invalid key-name.

SMG$_INVKTB_ID Invalid key-table-id.

SMG$_KEYNOTDEF Key not defined.

SMG$_WRONUMARG Wrong number of arguments.

Any condition values returned by LIB$SCOPY_DXDX.

SMG$GET_NUMERIC_DATA

The Get Numeric Terminal Data routine accesses TERMTABLE.EXE and returns the value associated with a specified Boolean or numeric capability.

Format

SMG$GET_NUMERIC_DATA termtable-address ,request-code ,buffer-address

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

termtable-address

OpenVMS usage: address

type: longword (unsigned)

access: read only

mechanism: by reference

Specifies the address of the TERMTABLE entry for the desired terminal. The termtable-address argument is the address of an unsigned longword that contains the address of the terminal capabilities table (TERMTABLE).
Before calling SMG$GET_NUMERIC_DATA, you must obtain this terminal table address by calling either SMG$INIT_TERM_TABLE or SMG$INIT_TERM_TABLE_BY_TYPE.
request-code

OpenVMS usage: longword_unsigned

type: longword (unsigned)

access: read only

mechanism: by reference

Request code that specifies the desired capability. The request-code argument is an unsigned longword constant containing this request code. The request code is of the form SMG$K_code, where code corresponds to a keyword in the terminal capabilities table (TERMTABLE), for example, ANSI_CRT. The SMG$K_code constants can be found in the Digital-supplied library $SMGTRMPTR.
See Table 5-1, Table 5-2, Table 5-3, and Table 5-4 for valid capability fields.
buffer-address

OpenVMS usage: address

type: longword (unsigned)

access: write only

mechanism: by reference

Address of the first byte of the longword to which SMG$GET_NUMERIC_DATA writes the numeric capability data. The buffer-address argument is an unsigned longword that contains the address of this buffer.

Description

SMG$GET_NUMERIC_DATA extracts the requested numeric information from a specified terminal table. Before calling SMG$GET_NUMERIC_DATA, you must obtain that terminal table address by calling either SMG$INIT_TERM_TABLE or SMG$INIT_TERM_TABLE_BY_TYPE. This routine need only be used if you are doing your own TERMTABLE access, and only when you perform direct (non-SMG$) I/O to terminals.

Condition Values Returned

SS$_NORMAL Normal successful completion.

SMG$_INVREQCOD Invalid request code.

SMG$_INVTERTAB Invalid terminal table address.

SMG$GET_PASTEBOARD_ATTRIBUTES

The Get Pasteboard Attributes routine gets pasteboard attributes and stores them in the pasteboard information table.

Format

SMG$GET_PASTEBOARD_ATTRIBUTES pasteboard-id ,pasteboard-info-table ,pasteboard-info-table-size

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 information is requested. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
pasteboard-info-table

OpenVMS usage: unspecified

type: unspecified

access: write only

mechanism: by reference, array reference

Receives the pasteboard attributes. The pasteboard-info-table argument is the address of a data structure into which are written the pasteboard attributes.
The values in the pasteboard-info-table can be accessed through the following symbolic names:

SMG$L_DEVCHAR Device characteristics (longword).

SMG$L_DEVDEPEND Specific characteristics 1 (longword).

SMG$L_DEVDEPEND2 Specific characteristics 2 (longword).

SMG$L_DEVDEPEND3 Specific characteristics 3 (longword).

SMG$B_DEVCLASS Device class (byte)---for example, DC$_TERM.

SMG$B_SMG_DEVTYPE Internal SMG device type (byte). The four possible values for SMG$B_SMG_DEVTYPE are as follows:

SMG$K_UNKNOWN
SMG$K_VTFOREIGN
SMG$K_HARDCOPY
SMG$K_VTTERMTABLE

SMG$B_PHY_DEVTYPE Physical device type (byte)---for example, TT$_VT100. The possible values for SMG$B_PHY_DEVTYPE are defined in $TTDEF in STARLET.

SMG$B_ROWS Number of rows on pasteboard (byte).

SMG$W_WIDTH Pasteboard width (word).

SMG$B_COLOR Background color setting (byte). Valid values for SMG$B_COLOR are as follows:

SMG$C_COLOR_UNKNOWN Unknown background color

SMG$C_COLOR_WHITE Light background

SMG$C_COLOR_BLACK Dark 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 White background

SMG$C_COLOR_DARK Black background

SMG$C_COLOR_USER1 User-defined background 1

SMG$C_COLOR_USER2 User-defined background 2

SMG$B_PARITY Parity attributes (byte)---this field is zero if the pasteboard is not a terminal.

SMG$W_SPEED Terminal speed (word)---this field is zero if the pasteboard is not a terminal.

SMG$W_FILL Fill characteristics (word)---this field is zero if the pasteboard is not a terminal.

SMG$W_PHYS_CURSOR_ROW Pasteboard row containing physical cursor (word).

SMG$W_PHYS_CURSOR_COL Pasteboard column containing physical cursor (word).

SMG$L_CURSOR_DID Display identifier of topmost display containing physical cursor (longword).

pasteboard-info-table-size

OpenVMS usage: longword_unsigned

type: longword (unsigned)

access: read only

mechanism: by reference

Specifies the number of bytes in the pasteboard information table. The pasteboard-info-table-size argument is the address of an unsigned longword that contains the size (in bytes) of the pasteboard information table.
The size you specify must be exact. You can specify this size with the symbolic constant SMG$C_PASTEBOARD_INFO_BLOCK.

Description

SMG$GET_PASTEBOARD_ATTRIBUTES gets pasteboard attributes and stores them in the pasteboard information table.

Condition Values Returned

SS$_NORMAL Normal successful completion.

SMG$_INVARG Incorrect size specified in pasteboard-info-table-size.

SMG$_WRONUMARG Wrong number of arguments.

Contents

Index

privacy and legal statement

5935PRO_020.HTML

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

OpenVMS usage:	identifier
type:	longword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	unspecified
type:	unspecified
access:	write only
mechanism:	by reference, array reference

SMG$L_DEV_CHAR	Device characteristics (longword)
SMG$L_DEV_DEPEND	Specific characteristics 1 (longword)
SMG$L_DEV_DEPEND2	Specific characteristics 2 (longword)
SMG$L_DEV_DEPEND3	Specific characteristics 3 (longword)
SMG$B_DEV_CLASS	Device class (byte) --- for example, DC$_TERM
SMG$B_RECALL_NUM	Size of recall buffer (byte)*
SMG$B_DEVTYPE	Physical device type (byte) --- for example, TT$_VT100
SMG$B_TYPEAHD_CHAR	First character in type-ahead buffer (byte)*
SMG$W_NUM_COLUMNS	Terminal width (word)
SMG$W_TYPEAHD_CNT	Number of characters in type-ahead buffer (word)*

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

SS$_NORMAL	Normal successful completion.
SMG$_INVARG	KIT is the wrong size.
SMG$_INVKBD_ID	Invalid keyboard-id.

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	write only
mechanism:	by reference

SMG$M_KEY_NOECHO	If set, this bit specifies that equiv_string is not to be echoed when this key is pressed. If clear, equiv_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.
SMG$M_KEY_LOCKSTATE	If set, and if state-string is specified, the state name specified by state-string remains at 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 key stroke.
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.

SS$_NORMAL	Normal successful completion.
SMG$_INVKEYNAM	Invalid key-name.
SMG$_INVKTB_ID	Invalid key-table-id.
SMG$_KEYNOTDEF	Key not defined.
SMG$_WRONUMARG	Wrong number of arguments.

OpenVMS usage:	address
type:	longword (unsigned)
access:	read only
mechanism:	by reference

SS$_NORMAL	Normal successful completion.
SMG$_INVREQCOD	Invalid request code.
SMG$_INVTERTAB	Invalid terminal table address.