A BTS event is a means by which CICS® business transaction services signal progress in a process. It informs an activity that an action is required or has completed. "Event" is used in its ordinary sense of "something that happens". To define an event recognizable by CICS business transaction services, such a happening is given a name. An activity program uses such commands as DEFINE INPUT EVENT, DEFINE TIMER, and the EVENT option of DEFINE ACTIVITY to name events about which it wants to be informed.
Named events have Boolean values--FIRED or NOTFIRED. When first defined, an event has the NOTFIRED value. When an event occurs it is said to fire (that is, to make the transition from NOTFIRED to FIRED). An activity can, for example:
BTS events can be atomic or composite.
An atomic event is a single, "low-level" occurrence (which may happen under the control of BTS or outside the control of BTS). There are four types of atomic event:
Atomic events are the basic components out of which composite events (see Composite events) can be constructed.
Input events tell activities why they are being run. A RUN or LINK ACTIVITY command delivers an input event to an activity, and thus activates the activity. (The INPUTEVENT option on the command names the input event and thus defines it to the requestor.)
The first time an activity is run, CICS always sends it the DFHINITIAL system event. DFHINITIAL tells the activity to perform its initial housekeeping. Typically, this involves defining further events for which it may be activated.
An activity must use the RETRIEVE REATTACH EVENT command to discover the event or events that caused it to be activated. On any activation (but typically on its first, when it is invoked with DFHINITIAL), it may use the DEFINE INPUT EVENT command to define some input events for which it can be activated subsequently.
The completion of a child activity (but not a root activity) causes the activity completion event to fire. (The EVENT option on the DEFINE ACTIVITY command names the activity completion event and thus defines it. If EVENT is not specified, the completion event is given the same name as the activity itself.)
When you define a timer, a timer event is automatically associated with it. When the timer expires, its associated event fires.
All the other types of event described in this section (including composite events) are referred to as user-defined events, because they are defined by the BTS application programmer, using commands such as DEFINE INPUT EVENT, DEFINE TIMER, DEFINE COMPOSITE EVENT, and the EVENT option of DEFINE ACTIVITY. BTS system events, on the other hand, are defined by BTS. They are a special kind of input event.
There is only one type of BTS system event--DFHINITIAL. See System events.
System events cannot be included in composite events.
A composite event is a "high-level" event, formed from zero or more user-defined (that is, non-system) atomic events. When included in a composite event, an atomic event is known as a sub-event.
The DEFINE COMPOSITE EVENT command defines a predicate, which is a logical expression typically involving sub-events. At all times, the composite event’s fire status reflects the value of the predicate. When the predicate becomes true, the composite event fires; when it becomes false, the composite’s fire status reverts to NOTFIRED.
The logical operator that is applied to the composite event’s predicate is one of the Boolean operators AND or OR. AND and OR cannot both be used.
When first defined, a composite event contains between zero and eight sub-events. (A composite event that contains zero sub-events is said to be "empty".) The ADD SUBEVENT command can be used to add further sub-events to the composite event. A composite event that uses the OR Boolean operator fires when any of its sub-events fires. A composite event that uses the AND operator fires when all of its sub-events have fired.4
Figure 5 shows four composite events, C1 through C4. Each composite event contains two sub-events. C1 and C2 use the OR Boolean operator. C3 and C4 use the AND operator. The shaded circles indicate the events that have fired.
The names of sub-events that fire are placed on the composite event’s sub-event queue--from where they can be retrieved by issuing one or more RETRIEVE SUBEVENT commands. Each composite event has a sub-event queue associated with it. The sub-event queue:
Figure 6 shows all the events that are recognized by a particular activity. Among them are two composite events, C1 and C2. The sub-event queue for C1 contains the name T1. The sub-event queue for C2 contains the names S1 and S3.
Events are defined within event pools. Each activity has an event pool, which contains the set of events that it recognizes. The events that an activity recognizes are:
An activity’s event pool is initialized when the activity is created, and deleted when the activity is deleted. All the event-related commands described in Event-related commands, except FORCE TIMER, operate on the event pool associated with the current activity.
Figure 7 shows an activity’s event pool.
You can delete an event (that is, discard both the event and its name). If the event is a sub-event, the value of the composite event will be that of its predicate, after the sub-event has been removed from the predicate’s Boolean expression.
The command you use to delete an event depends on the type of event to be deleted:
Table 4 summarizes the commands that can be used to delete each type of event.
Event type | Deletion commands |
---|---|
Activity completion |
|
Composite |
|
Input |
|
System | Cannot be deleted |
Timer |
|
Before it can complete normally, an activity must have deleted all the activity completion events in its event pool. (That is, it must have dealt with all its child activities--see Activity completion.)
An activity is reattached (reactivated) on the firing of any event (other than a sub-event) that is in its event pool. In other words, an activity is reattached when either of the following types of event occurs:
An event that causes an activity to be reactivated is known as a reattachment event.
When an activity is reattached, it should use the RETRIEVE REATTACH EVENT command to discover the event that caused reattachment. If the event that caused it to be reattached is composite, the activity may also need to issue one or more RETRIEVE SUBEVENT commands to discover the sub-event or sub-events that fired.
At times reattachment may 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 by means of RETRIEVE REATTACH EVENT commands. Each activity has a reattachment queue, which:
Often, when an activity is reattached there will be 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 8 shows the event pool and reattachment queue for a particular activity. The reattachment queue contains the names A1 and C1.
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 syncpoint does not occur until the activation returns.
Retrieving an atomic event from the reattachment queue automatically causes the event’s fire status to be reset to NOTFIRED.
Retrieving a composite event from the reattachment queue does not reset the event’s fire status to NOTFIRED, because a composite event is only reset when its predicate becomes false. Thus, if an activity program retrieves a composite event, it should reset the fire status of the sub-event or sub-events that have fired. (One way of doing this is to issue one or more RETRIEVE SUBEVENT commands.) This in turn causes the fire status of the composite event to be re-evaluated.
If the activity was reattached because of the completion of one of its children, it should issue a CHECK ACTIVITY command to check whether the child activity completed normally. On return from the CHECK ACTIVITY command, CICS deletes the activity completion event from the parent’s event pool.
If the activity was reattached because of the expiry of a timer, it can issue a CHECK TIMER command to check whether the timer expired normally. On return from the CHECK TIMER command, CICS deletes the timer event from the activity’s event pool.
If the activity wants to delete input and composite events from its event pool, it can issue DELETE EVENT commands. Alternatively, it can rely on a RETURN ENDACTIVITY command, issued on its final activation, to delete them.
Figure 9 shows a typical sequence that an activity might use to handle reattachment events. The "Handle atomic event" box is expanded in Figure 10.
An activity completes normally when it returns with no user events in its event pool.
When an activity issues an EXEC CICS RETURN command (without the ENDACTIVITY option):
Optionally, an activity program can use the ENDACTIVITY option of the EXEC CICS RETURN command to signal that it has completed all its processing steps and is not to be reactivated. One advantage of using ENDACTIVITY is that the activity program does not have to bother about deleting user events--other than activity completion events--from its event pool before completing; the events are deleted automatically by CICS.
When an activity issues an EXEC CICS RETURN ENDACTIVITY command:
It is recommended that you issue a RETURN ENDACTIVITY command at the end of the final activation of an activity, as a way of ensuring that the activity completes. For example, if, through a program logic error, an activity returns from what it believes to be its final activation with an unfired event in its event pool, it is possible that the activity could go dormant forever, and never complete. Coding RETURN ENDACTIVITY deletes the event and forces the activity to complete.