VMS Help RTL Routines, SMG$, SMG$ADD_KEY_DEF  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    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]

1 - Returns

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

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

    The key table identifier argument 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.

 if-state

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

    Qualifies the value returned when key-name is pressed. 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.

    The equivalence-string argument is displayed 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 that 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_LOCKSTATE was not specified for
    the most recently pressed defined key), the current state-string
    becomes DEFAULT.