HANDLE AID

Handles attention identifiers.

Note: HANDLE AID is not supported for C or C++ programs.

Syntax

HANDLE AID

Condition: INVREQ

Description

HANDLE AID handles attention identifiers. An attention identifier (AID) is a character that is in a data stream and indicates that the user has pressed a key, such as the Enter key, that requests an action by the system.

This command is used to specify the program label to which control is to be passed when an Attention Identifier (AID) is received from a display device. Control is passed after the input operation has completed; that is, after any data that is received, in addition to the AID, has been passed to the application program.

A HANDLE AID command that specifies an option without an associated label deactivates the effect of that option in any previously issued HANDLE AID command. You can also suspend (and later restore) the effect of HANDLE AID by means of the PUSH HANDLE and POP HANDLE commands.

In the absence of a HANDLE AID command, control returns to the application program at the point immediately following the input command.

You must ensure that the HANDLE AID command is executed before the command that might cause the associated AID. Note that the HANDLE AID command for a given AID applies only to the program in which it is specified, and it remains active while the program is running, or until another HANDLE AID command for the same AID is encountered, in which case the new command overrides the previous one.

Options

No more than 16 options are allowed in the same HANDLE AID command; you must specify additional options in further commands.

The options that can be specified are:

ANYKEY: Any PA key, any PF key, or the CLEAR key, but not ENTER.
CLEAR: For the key of that name.
CLRPARTN: For the key of that name.
ENTER: For the key of that name.
LIGHTPEN: For compatibility with IBM® mainframe-based CICS®; never raised by CICS TX on Cloud.
OPERID: For compatibility with IBM mainframe-based CICS; never raised by CICS TX on Cloud.
PA1-3: Any of the program access keys.
PF1-24: Any of the program function keys.
TRIGGER: For compatibility with IBM mainframe-based CICS; never raised by CICS TX on Cloud.

Examples

The following example shows a HANDLE AID command that specifies one label for the PA1 key, and a second label for PA2 and PA3, all the PF keys except PF10, and the CLEAR key. If a PF10 AID is received, control returns to the application program at the instruction that immediately follows the input command.

EXEC CICS HANDLE AID
          PA1(LAB1)
          ANYKEY(LAB2)
          PF10

If a task is initiated from a terminal by means of an AID, the first RECEIVE command in the task does not read from the terminal but copies only the input buffer, so that control can be passed by means of a HANDLE AID command for that AID.

The EIBAID field in the EXEC Interface Block (EIB) holds a code for the attention identifier that is associated with the last terminal control or Basic Mapping Support (BMS) input operation. To simplify testing the contents of the EIBAID field in your application program, CICS provides a copy book that contains a list of symbolic names that are associated with the attention identifier constants. For further details, see Attention identifier constants list (DFHAID).

Conditions

INVREQ

Occurs when a remotely linked-to program attempts to execute a HANDLE AID command that refers to the principal facility.

The storage that is specified in the DATA option is not addressed by a pointer that is returned by a GETMAIN command (RESP2=1).

Default action: Terminates the task abnormally.