Document revision date: 30 March 2001

## OpenVMS RTL Screen Management (SMG$) Manual

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

## 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 library supplied by Compaq, $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.

Previous | Next | Contents | Index

| privacy and legal statement |
5935PRO_020.HTML