VMS Help DEFINE, /KEY  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Associates an equivalence string and a set of attributes with a
    key on the terminal keyboard.

    Format

      DEFINE/KEY  key-name equivalence-string

1 - Parameters

 key-name

    Specifies the name of the key that you are defining. All
    definable keys on VT52 terminals are located on the numeric
    keypad. On VT100-series terminals, you can define the left and
    right arrow keys as well as all the keys on the numeric keypad.
    On terminals with LK201 keyboards, the following three types of
    keys can be defined:

    o  Keys on the numeric keypad

    o  Keys on the editing keypad (except the up and down arrow keys)

    o  Keys on the function key row across the top of the keyboard
       (except keys F1 to F5)

    The following table lists the key names in column one. The
    remaining three columns indicate the key designations on the
    keyboards of the three different types of terminals that allow
    key definitions.

    Key Name            LK201              VT100-Series  VT52

    PF1                 PF1                PF1           [blue]
    PF2                 PF2                PF2           [red]
    PF3                 PF3                PF3           [gray]
    PF4                 PF4                PF4           - -
    KP0, KP1, ..., KP9  0, 1, ..., 9       0, 1, ..., 9  0, 1, ..., 9
    Period              .                  .             .
    Comma               ,                  ,             n/a
    Minus               -                  -             n/a
    Enter               Enter              ENTER         ENTER
    Left                < -                < -           < -
    Right               - >                - >           - >
    Find (E1)           Find               -             -
    Insert Here (E2)    Insert Here        -             -
    Remove (E3)         Remove             -             -
    Select (E4)         Select             -             -
    Prev Screen (E5)    Prev Screen        -             -
    Next Screen (E6)    Next Screen        -             -
    Help                Help               -             -
    Do                  Do                 -             -
    F6, F7, ..., F20    F6, F7, ..., F20   -             -

    Some definable keys are enabled for definition all the time.
    Others, including KP0 to KP9, Period, Comma, and Minus, must be
    enabled for definition purposes. You must enter either the SET
    TERMINAL/APPLICATION or the SET TERMINAL/NONUMERIC command before
    using these keys.

    On LK201 keyboards, you cannot define the up and down arrow keys
    or function keys F1 to F5. The left and right arrow keys and the
    F6 to F14 keys are reserved for command line editing. You must
    enter the SET TERMINAL/NOLINE_EDITING command before defining
    these keys. You can also press Ctrl/V to enable keys F7 to F14.
    Note that Ctrl/V will not enable the F6 key.

 equivalence-string

    Specifies the character string to be processed when you press
    the key. Enclose the string in quotation marks (" ")  to preserve
    spaces and lowercase characters.

2 - Qualifiers

 2.1 - /ECHO

       /ECHO (default)
       /NOECHO

    Displays the equivalence string on your screen after the key
    has been pressed. You cannot use the /NOECHO qualifier with the
    /NOTERMINATE qualifier.

 2.2 - /ERASE

       /ERASE
       /NOERASE (default)

    Determines whether the current line is erased before the key
    translation is inserted.

 2.3 - /IF_STATE

       /IF_STATE=(state-name,...)
       /NOIF_STATE

    Specifies a list of one or more states, one of which must be in
    effect for the key definition to work. The /NOIF_STATE qualifier
    has the same meaning as /IF_STATE=current_state. The state name
    is an alphanumeric string. States are established with the /SET_
    STATE qualifier or the SET KEY command. If you specify only one
    state name, you can omit the parentheses. By including several
    state names, you can define a key to have the same function in
    all the specified states.

 2.4 - /LOCK_STATE

       /LOCK_STATE
       /NOLOCK_STATE (default)

    Specifies that the state set by the /SET_STATE qualifier remain
    in effect until explicitly changed. (By default, the /SET_STATE
    qualifier is in effect only for the next definable key you press
    or the next read-terminating character that you type.) This
    qualifier can be specified only with the /SET_STATE qualifier.

 2.5 - /LOG

       /LOG (default)
       /NOLOG

    Displays a message indicating that the key definition has been
    successfully created.

 2.6 - /SET_STATE

       /SET_STATE=state-name
       /NOSET_STATE (default)

    Causes the specified state-name to be set when the key is
    pressed. (By default, the current locked state is reset when
    the key is pressed.) If you have not included this qualifier with
    a key definition, you can use the SET KEY command to change the
    current state. The state name can be any alphanumeric string;
    specify the state as a character string enclosed in quotation
    marks.

 2.7 - /TERMINATE

       /TERMINATE
       /NOTERMINATE (default)

    Specifies whether the current equivalence string is to be
    processed immediately when the key is pressed (equivalent to
    entering the string and pressing Return). By default, you can
    press other keys before the definition is processed. This allows
    you to create key definitions that insert text into command
    lines, after prompts, or into other text that you are entering.

3 - Examples

    1.$ DEFINE/KEY PF3 "SHOW TIME" /TERMINATE
      %DCL-I-DEFKEY, DEFAULT key PF3 has been defined
      $ <PF3>
      $ SHOW TIME
        14-DEC-2001 14:43:59

      In this example, the DEFINE/KEY command defines the PF3 key on
      the keypad to perform the SHOW TIME command. DEFAULT refers to
      the default state.

    2.$ DEFINE/KEY PF1 "SHOW " /SET_STATE=GOLD/NOTERMINATE/ECHO
      %DCL-I-DEFKEY, DEFAULT key PF1 has been defined
      $ DEFINE/KEY PF1 " DEFAULT" /TERMINATE/IF_STATE=GOLD/ECHO
      %DCL-I-DEFKEY, GOLD key PF1 has been defined
      $ <PF1>
      $ <PF1>
      $ SHOW DEFAULT
      DISK1:[JOHN.TEST]

      In this example, the first DEFINE/KEY command defines the PF1
      key to be the string SHOW. The state is set to GOLD for the
      subsequent key. The /NOTERMINATE qualifier instructs the system
      not to process the string when the key is pressed. The second
      DEFINE/KEY command defines the use of the PF1 key when the
      keypad is in the GOLD state. When the keypad is in the GOLD
      state, pressing PF1 causes the current read to be terminated.

      If you press the PF1 key twice, the system displays and
      processes the SHOW DEFAULT command.

      The word DEFAULT in the second line of the example indicates
      that the PF1 key has been defined in the default state. Note
      the space before the word DEFAULT in the second DEFINE/KEY
      command. If the space is omitted, the system fails to recognize
      DEFAULT as the keyword for the SHOW command.

    3.$ SET KEY/STATE=ONE
      %DCL-I-SETKEY, keypad state has been set to ONE
      $ DEFINE/KEY PF1 "ONE"
      %DCL-I-DEFKEY, ONE key PF1 has been defined
      $ DEFINE/KEY/IF_STATE=ONE PF1 "ONE"
      %DCL-I-DEFKEY, ONE key PF1 has been defined

      This example shows two ways to define the PF1 key to be "ONE"
      for state ONE.

      The second DEFINE/KEY command shows the preferred method for
      defining keys. This method eliminates the possibility of
      error by specifying the state in the same command as the key
      definition.