BTS events

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.

Atomic events

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

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.

Note:
The RUN command can also be used to activate a process multiple times, delivering a different input event on each activation. This is not discussed here--see Using client/server processing.

Activity completion events

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.)

Timer events

When you define a timer, a timer event is automatically associated with it. When the timer expires, its associated event fires.

Note:
If you do not specify the EVENT option of the DEFINE TIMER command, the timer event is given the same name as the timer itself.

System events

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.

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.

Figure 5. Composite events. An OR composite event fires when any of its sub-events fires. An AND composite event fires when all of its sub-events have fired.
 The picture 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. Neither of C1’s sub-events have fired. Therefore, C1 has not fired. One of C2’s sub-events has fired. Therefore, because C2 uses the OR operator, C2 itself has fired. One of C3’s sub-events has fired. Therefore, because C3 uses the AND operator, C3 itself has not fired. Both of C4’s sub-events has fired. Therefore, because C4 uses the AND operator, C4 itself has fired.

Notes:
  1. An empty composite event that uses the AND operator is always true (FIRED). An empty composite event that uses the OR operator is always false (NOTFIRED).
  2. The following cannot be added as sub-events to a composite event:
    • Composite events
    • Sub-events of other composite events
    • System events
    • Input events, if the composite uses the AND operator.

The sub-event queue

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.

Figure 6. Sub-event queues. The sub-event queue for composite event C1 contains the name T1. The sub-event queue for composite event C2 contains the names S1 and S3.
 The picture shows two composite events, C1 and C2. C1 contains two sub-events, T0 and T1. T1, but not T0, has fired. Because C1 uses the OR Boolean operator, it too has fired. T1 is on C1’s sub-event queue, because it has fired and not yet been retrieved. C2 contains three sub-events, S1, S2, and S3. S1 and S3, but not S2, have fired. Because C2 uses the AND Boolean operator, it has not fired. S1 and S3 are on C2’s sub-event queue, because they have fired and not yet been retrieved.

Event pools

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:

  1. Events that have been defined to it by means of:
  2. System events.

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.

Figure 7. An event pool
 The picture shows a rectangle representing an event pool. It contains four atomic events and two composite events. Some of the events are in FIRED state, the others in NOTFIRED state.

Deleting events

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.

Table 4. Commands used to delete events
Event type Deletion commands
Activity completion
  1. CHECK ACTIVITY (if the activity has completed)
  2. DELETE ACTIVITY
Composite
  1. DELETE EVENT
  2. RETURN ENDACTIVITY
Input
  1. DELETE EVENT
  2. RETURN ENDACTIVITY
System Cannot be deleted
Timer
  1. CHECK TIMER (if the timer has expired)
  2. DELETE TIMER
  3. RETURN ENDACTIVITY

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.)

Reattachment events and activity activation

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.

Note:
The firing of a sub-event never directly causes an activity to be reattached--it is the firing of the associated composite event that does so. Therefore, a sub-event can never be a reattachment event.

Handling reattachment events

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.

Figure 8. A reattachment queue. The queue contains the names A1 and C1.
 The picture shows a rectangle representing an event pool. It contains four atomic events and two composite events. One of the atomic events, A!, and one of the composite events, C!, are in FIRED state. The picture also shows a reattachment queue for a particular activity. The reattachment queue contains two events, A1 and C1. The events are on the queue because they are reattachment events that have fired and not yet been retrieved.
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 made no progress--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 syncpoint does not occur until the activation returns.

Resetting and deleting reattachment events

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.

Figure 9. Handling reattachment events. The "Handle atomic event" box is expanded in Figure 10. The figure shows multiple reattachment events being handled in a single activation--you may prefer to handle one per activation.
 The picture is a flow chart showing how an activity might handle reattachment events. At the top of the chart is a RETRIEVE REATTACH EVENT command. Depending on whether the retrieved event is an atomic or composite event, different paths are followed. If the retrieved event is an atomic event, the activity handles it in the way described in the next picture. It then checks for more reattachment events on the  reattachment queue. If there are more reattachment events on the reattachment queue, the activity loops back to issue another RETRIEVE REATTACH EVENT command. If not, it issues an EXEC CICS RETURN. If the retrieved event is a composite event, the activity issues a RETRIEVE SUBEVENT command. It handles the retrieved atomic event in the way described in the next picture. It then checks for more atomic events on the  sub-event queue. If there are more atomic events on the sub-event queue, the activity loops back to issue another RETRIEVE SUBEVENT EVENT command. If not, it decides whether the retrieved composite event is still required. If it isn't, it issues a DELETE EVENT(comp-event) command. The activity then checks for more reattachment events on the  reattachment queue. If there are more reattachment events on the reattachment queue, the activity loops back to issue another RETRIEVE REATTACH EVENT command. If not, it issues an EXEC CICS RETURN.

Figure 10. Handling atomic events
 The picture is a flow chart showing how an activity might handle atomic events. There are four elipses, representing the four types of atomic event--system, input, activity completion, and timer. If the retrieved event is an input event, the activity decides whether the event is still required. If it isn’t, it issues a DELETE EVENT(input_event) command. If the retrieved event is an activity completion event, the activity issues a CHECK ACTIVITY command. If the retrieved event is a timer event, the activity issues a CHECK TIMER command. The activity then processes the event according to its internal rules for dealing with different types of event.
Notes:
  1. Figure 9 shows multiple reattachment events being handled in a single activation. This may not always be appropriate. You may want always to retrieve only one reattachment event per activation, even if there is more than one event on the reattachment queue. This could be the case if, for example, you want a syncpoint to be taken between each processing step. (Note especially that a child activity that is run asynchronously is not started until a syncpoint occurs when its parent returns. Dealing with many reattachment events in the same activation could delay the start of the child.)
  2. The figures show input and composite events being explicitly deleted by means of DELETE EVENT commands. This is not always strictly necessary--see Using the ENDACTIVITY option of the RETURN command. Similarly, it may not always be necessary to issue CHECK TIMER commands. If you don’t, timer events can be deleted by means of a RETURN ENDACTIVITY command issued on the activity’s final activation.

Activity completion

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):

  1. If the activity has correctly dealt with at least one reattachment event during its current activation (see Handling reattachment events):
    If there are events on the reattachment queue
    The activity is immediately reactivated to deal with the fired events.
    If there are no events on the reattachment queue
    If there are user events in the event pool
    The activity becomes dormant until a reattachment event occurs.
    If there are no user events in the event pool
    The activity completes normally.
  2. If the activity has not correctly dealt with at least one reattachment event during its current activation, it abends.
Using the ENDACTIVITY option of the RETURN command

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:

If there are no user events in the activity’s event pool
The activity completes normally.
If there are user events (fired or unfired) in the activity’s event pool

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.

Related concepts
BTS activities and processes
BTS data-containers
BTS timers
What are CICS business transaction services?
The Sale example application
Related reference
Event-related commands

4.
Or when it is empty.

[[ Contents Previous Page | Next Page Index ]]