Reviewing Sublist and Event Queue Monitoring

The following points outline the use of an event queue to accomplish sublist monitoring:

A keyed list structure is allocated in a coupling facility with CFLEVEL=3 or higher. The connector specifies both a local vector and a percentage of storage for event monitor control objects.
Connectors to the structure register interest in monitoring their event queues and specify the vector index to be associated with the event queue. (IXLLIST REQUEST=MONITOR_EVENTQ)
When a connector registers interest in monitoring one or more sublists, the system creates an EMC to uniquely associate the user with each sublist. (IXLLIST REQUEST=MONITOR_SUBLIST, IXLLIST REQUEST=MONITOR_SUBLISTS)
When a monitored sublist transitions to a nonempty state, an EMC is queued to the user's event queue. Users are notified either through their list transition exit or their own polling protocol.
Users read EMCs from their event queues and examine the EMC contents to identify a monitored sublist that has transitioned. The operation that reads the EMCs also dequeues them from the event queue. (IXLLIST REQUEST=DEQ_EVENTQ)

You must be aware of certain timing considerations when monitoring state transitions of both a sublist and an event queue. Some examples are:

The queueing of an EMC to an event queue occurs asynchronously with respect to the command that caused the queueing to be performed. For example,
- You add the first entry to a sublist that you are monitoring.
- You read and dequeue the EMCs from your event queue.
Result: The EMC for the sublist that just transitioned to a nonempty state might or might NOT have been queued to your event queue by the time the DEQ_EVENTQ command is processed. Thus the EMC representing the now-nonempty sublist might or might not be read by the DEQ_EVENTQ command.
The withdrawal of an EMC from an event queue occurs asynchronously with respect to the command that caused the withdrawal to be performed. For example,
- You delete the last entry from a sublist that you are monitoring.
- You read and dequeue the EMCs from your event queue.
Result: The EMC for the sublist for which the last entry was deleted might or might NOT have been withdrawn from your event queue by the time the DEQ_EVENTQ command is processed. Thus the EMC representing the now-empty sublist might or might not be read by the DEQ_EVENTQ command.
The list notification signal that sets the state of the local vector entry that represents the empty or nonempty state of the event queue occurs asynchronously with respect to the state change of the event queue. For example,
- You read and dequeue all EMCs from your event queue so that it is now empty.
- You test the local vector entry with which you are monitoring your event queue.
Result: The local vector entry might or might NOT indicate that the event queue is now empty.

In all cases, the coupling facility preserves the ordering of individual EMCs on the event queue and list notification signals for setting a given vector index.

For any particular EMC, the coupling facility preserves the ordering of queueing and withdrawal processes, so that the final location of the EMC — either on or off the event queue — is always correct.
For any given vector entry, the coupling facility preserves the ordering of list notification signals to set the vector entry, so that the final state of the vector entry — either empty or nonempty — is always correct.