When an activity is reattached, it uses the RETRIEVE REATTACH EVENT
command to discover the event that caused reattachment. The names
of reattachment events are placed on the reattachment queue, and from
there the activity deals with them.
About this task
If the event that caused it to be reattached is composite,
the activity might also need to issue one or more RETRIEVE SUBEVENT
commands to discover the subevent or subevents that fired.
At
times reattachment might occur because of the firing of more than
one event. When reattachment events occur, their names are placed
on a queue—the
reattachment queue
—from where they can be retrieved
with RETRIEVE REATTACH EVENT commands. Each activity has a reattachment
queue, which:
- May be empty
- Contains only the names of those reattachment events that have
fired and not been retrieved.
Often, when an activity is reattached there is only one event
on the reattachment queue, because activities are reactivated as each
reattachment event occurs. However, it is possible for the
reattachment
queue to contain 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.
Figure 1
shows the event pool and reattachment
queue for a particular activity. The reattachment queue contains the
names A1 and C1.
Figure 1. A reattachment
queue.
The queue contains the names A1 and C1.
Important: With one exception,
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 abending, because it has not progressed, it has not reset
any reattachment events and is therefore in danger of getting into
an unintentional loop.
The one exception to this general rule is
if the activity program issues a RETURN ENDACTIVITY command—in which
case, it is not required to have issued a RETRIEVE REATTACH EVENT
command in the current activation.
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 REATTACH EVENT 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 sync point does not occur
until
the activation returns.