Event-related commands

This section describes the CICS® business transaction services event-related commands.

Terminology

This section is a brief reminder of some of the terms used to describe BTS events. For a more detailed introduction to BTS events, see BTS events.

Event states

An event can be in one of two states: FIRED (true) or NOTFIRED (false). Which state it is in is known as the event’s fire status.

Atomic events

Atomic events are simple, "low-level" events. The BTS atomic events are:

Activity completion events
Events that fire on completion of an activity.
Input events
Events delivered to an activity when it is activated, conveying the reason for its attachment.
Timer events
Events that fire when a timer expires.
System events
Input events defined by the BTS system.
Note:
Activity, input, timer, and composite events are referred to as user-defined events, because they are defined by the programmer. System events are defined by BTS.

Composite events

A composite event is a method of grouping user-defined (that is, non-system) atomic events in a logical expression, which is named. An atomic event that is included in a composite event is known as a sub-event. Sub-events that fire are placed on the composite event’s sub-event queue. Each composite event has a sub-event queue associated with it. The sub-event queue:

Reattachment events

An event that fires, and thereby causes an activity to be reattached, is known as a reattachment event. All user-defined events except sub-events cause the activity to which they are defined to be reattached when they fire. Thus, all user-defined events (both atomic and composite, but excluding sub-events) are potentially reattachment events. All system events are reattachment events.

At times, reattachment may occur because of the firing of more than one event. Reattachment events are placed on the activity’s reattachment queue, from which they can be retrieved. Each activity has a reattachment queue, which:

Timers

A timer is a BTS object that expires when the system time becomes greater than a specified time, or after a specified period has elapsed. When you define a timer, a timer event is automatically associated with it. When the timer expires, its associated event fires.

Event pools

Events are defined within event pools. Each activity has an event pool, which contains the set of events that it recognizes (that is, events that have been defined to it, and 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 except FORCE TIMER operate on the event pool associated with the current activity.

The event-related commands

All the event-related commands operate on the current activity’s event pool.

Use these commands to define user events other than activity completion and timer events:

DEFINE INPUT EVENT
Defines an input event.
DEFINE COMPOSITE EVENT
Defines a composite event.

Use these commands to control timers and timer events:

DEFINE TIMER
Defines a timer, and associates an event with it.
FORCE TIMER
Forces early expiry of a timer, and causes the timer’s associated event to fire.
CHECK TIMER
Returns the status of a timer and, if the timer has expired, deletes its associated event.
DELETE TIMER
Deletes a timer and its associated event (if any).

Use these commands to manipulate events:

ADD SUBEVENT
Adds a sub-event to a composite event.
REMOVE SUBEVENT
Removes a sub-event from a composite event.
DELETE EVENT
Removes an input or composite event from the current activity’s event pool.
Note:
DELETE EVENT cannot be used to delete activity completion events (which are implicitly deleted when a response from the completed activity has been acknowledged by a CHECK ACTIVITY command, or when a DELETE ACTIVITY command is issued), timer events, or system events.
RETRIEVE REATTACH EVENT
Retrieves the name of an event that caused the current activity to be reattached and, if the event is atomic, resets its fire status to NOTFIRED.
RETRIEVE SUBEVENT
Retrieves the name of the next sub-event in a composite event’s sub-event queue, and resets the retrieved sub-event’s fire status to NOTFIRED.

Use this command to check whether an event has fired:

TEST EVENT
Tests whether an event has fired.

Related concepts
Process- and activity-related commands
Container commands
Browsing and inquiry commands
System events
Using the BTS API to write business applications
The Sale example application
Related reference
BTS application programming commands
[[ Contents Previous Page | Next Page Index ]]