Retrieve the name of the next sub-event in a BTS composite event's sub-event queue.
Description
RETRIEVE SUBEVENT:
- Retrieves the name of the next sub-event in a BTS composite event's sub-event queue.
- Resets the retrieved sub-event's fire status to NOTFIRED.
- Causes the composite event's fire status to be re-evaluated.
The firing of a composite event results from the firing of a set of one or more sub-events. The names of sub-events that have fired are placed on the composite event's sub-event queue, from which they can be retrieved, in sequence, by issuing successive RETRIEVE SUBEVENT commands.
You can use this command to discover which sub-event or sub-events caused
a composite event to fire.
Note:
- The presence of events on the sub-event queue does not imply that the composite event has fired. (Some sub-events in the set required to fire the composite event may still be in NOTFIRED state, and not yet on the sub-event queue.) To discover whether a composite event has fired, use the TEST EVENT command.
- Retrieval is destructive; when the name of a fired sub-event is retrieved, that sub-event cannot be retrieved again.
- Because it resets the fire status of the sub-event, RETRIEVE SUBEVENT causes the fire status of the composite event to be re-evaluated.
Options
- EVENT(data-value)
- specifies the name (1–16 characters) of the composite event.
- EVENTTYPE(cvda)
- returns the type of the sub-event. CVDA values are:
- ACTIVITY
- Activity completion.
- INPUT
- Input
- TIMER
- Timer.
- SUBEVENT(data-area)
- returns the 16-character name of the sub-event at the head of the sub-event queue.
Conditions
- 83 END
- RESP2 values:
- 9
- There are no more sub-events to retrieve.
- 10
- The composite event contains no sub-events (it is empty).
- 111 EVENTERR
- RESP2 values:
- 4
- The event specified on the EVENT option is not recognized by BTS.
- 16 INVREQ
- RESP2 values:
- 1
- The command was issued outside the scope of an activity.
- 2
- The event specified on the EVENT option is invalid. It is not a composite event.
