KEYI (Key Item)

The KEYI tag defines a key assignment within a key mapping list.

Parameters

KEY=virtual-key

This attribute specifies the name of the key to assign to the command. The conversion utility supports F1-F24 only.

CMD=internal-command-name

This attribute specifies the command that ISPF runs when the user presses the key.

The internal-command-name must follow the standard naming convention described in Rules for variable names.

As an extension to the Dialog Tag Language, the conversion utility supports special ISPF command syntax for internal-command-name. In this case, the internal-command-name must have these characteristics:

• 2-9 single-byte characters in length
• The first character must be a ‘>’, ‘:’, or ‘%’.

  To code the > character you must use the &gtsym predefined entity. See Predefined entities for more information.

• The second character must be A-Z, a-z, @, #, or $.
• Remaining characters, if any, must be A-Z, a-z, @, #, $, or 0-9.

Lowercase characters are translated to their uppercase equivalents by default.

CASE=UPPER | MIXED

This attribute specifies whether the internal-command-name is converted to uppercase characters or stored as entered in the tag definition.

FKA=NO | YES | LONG | SHORT

This attribute specifies whether the key assignment is to appear in the function key area of an application panel. The default value NO indicates that the key is not to appear. You must specify FKA=YES, FKA=LONG, or FKA=SHORT if you want the key to be displayed in the function key area.

When FKA=NO is specified, the key is active even if it is not displayed.

PARM=parm-string

This attribute allows a parameter to be added to the command specified by the CMD attribute. The combined length of the command and the parameter is limited to 40 bytes. When the combined length exceeds 40 bytes, truncation of the PARM occurs at the end of the last complete word in the parm-string, for a parm-string containing multiple words. A parm-string which is a single word is truncated at position 40.

FKA-text

This is the text for the key which is to appear in the function key area of the panels that refer to the key list. This text is appended to the string "Fn=" (with no intervening space) to create the displayed format. Use initial caps for the FKA-text value.

If not specified, the FKA-text defaults to the internal-command-name specified for the key.

The function key area is formatted at run time based on the panel size. The maximum number of bytes allowed for FKA-text is 64. If the text exceeds 64 bytes, it is truncated and a warning message is issued. The conversion utility removes excess blanks from FKA-text. The first 8 bytes of the resulting text are used by ISPF.

Comments

The KEYI tag defines a key assignment within a key mapping list. Key assignments provide a means of associating commands with keys.

KEYI tags with the same assignment cause the conversion utility to issue a warning message and retain only the first occurrence.

Restrictions

• You must code the KEYI tag within a KEYL definition. See KEYL (Key List) for a complete description of this tag.
• Each KEYI definition can only have one command assigned to it. Additionally, CUA requires these conventions when assigning commands to certain keys:
  • If KEY=F1 or F13, then CMD must be HELP.
  • If KEY=F3 or F15, then CMD must be EXIT.
  • If KEY=F12 or F24, then CMD must be CANCEL.

  ISPF lets you provide the name of your own command on these keys.

  If you code the command HELP, EXIT, or CANCEL as part of your KEYI definition, then HELP must be assigned to key F1 or F13, EXIT must be assigned to F3 or F15, and CANCEL must be assigned to F12 or F24.

Processing

None.