RETRIEVE REATTACH EVENT

Retrieve the name of an event that caused the current BTS activity to be reattached.

RETRIEVE REATTACH EVENT

Read syntax diagramSkip visual syntax diagramRETRIEVEREATTACHEVENT( data-area)EVENTTYPE( cvda)

Conditions: END, INVREQ

Description

RETRIEVE REATTACH EVENT:
  • Returns the name of the next event in the current BTS activity's reattachment queue.
  • If the retrieved event is atomic, resets its fire status to NOTFIRED. (Composite events are not reset by this command, but only when their predicates become false.)

Use this command to find the name of the event that caused the activity to be reattached. In some cases, reattachment could result from the firing of more than one event—if, for example, the activity has previously been suspended, and reattachment events occurred while it was suspended; or if two or more timer events fire simultaneously. The event name or names are placed on the reattachment queue, from where they can be retrieved by issuing one or more RETRIEVE REATTACH EVENT commands.

Each time it is activated, an activity must deal with at least one reattachment event. That is, it must issue at least one RETRIEVE REATTACH EVENT command, and (if this is not done automatically by CICS®) reset the fire status of the retrieved event to NOTFIRED—see Resetting and deleting reattachment events . Failure to do so results in the activity completing abnormally, because it has made no progress—it has not reset any reattachment events and is therefore in danger of getting into an unintentional loop.

If there are multiple events on its reattachment queue, an activity can, by issuing multiple RETRIEVE REATTACH EVENT commands, deal with several or all of them in a single activation. Alternatively, it can deal with them singly, by issuing only one RETRIEVE command per activation and returning; it is then reactivated to deal with the next event on its reattachment queue. Which approach you choose is a matter of program design. Bear in mind, if you deal with several reattachment events in the same activation, that a syncpoint does not occur until the activation returns.

Note: The retrieval of a composite event from the reattachment queue does not reset the state of the composite event to NOTFIRED. Thus, if it retrieves a composite reattachment event, the activity program may need to issue one or more RETRIEVE SUBEVENT commands, to retrieve (and reset) the sub-event or sub-events that have fired. This in turn causes the fire status of the composite event to be re-evaluated.

Options

EVENT(data-area)
returns the 16-character name of the event which caused this activity to be reattached.
EVENTTYPE(cvda)
returns the type of the reattachment event. CVDA values are:
ACTIVITY
Activity completion.
COMPOSITE
Composite.
INPUT
Input
SYSTEM
The BTS system event, DFHINITIAL.
TIMER
Timer.

Conditions

83 END
RESP2 values:
8
There are no more events to retrieve.
16 INVREQ
RESP2 values:
1
The command was issued outside the scope of an activity.