Understanding Sublist Monitoring

Sublist monitoring differs from list or event queue monitoring in the way in which the user is notified of a change in the state of the sublist. While sublist monitoring is in effect, the system will queue or withdraw EMCs to or from your event queue to indicate the empty or nonempty state of the sublist. An event queue is present for each structure user when the structure is a keyed list structure that resides in a coupling facility with CFLEVEL=3 or higher. To determine whether a sublist transition has occurred, monitor your event queue for the presence or absence of EMCs.

With a keyed list structure allocated in a coupling facility with CFLEVEL=3 or higher, you can register interest in monitoring a single sublist within a list or multiple sublists within one or more lists.

The IXLLIST REQUEST=MONITOR_SUBLIST request allows you to register or deregister interest in monitoring a single sublist. You identify the sublist to be monitored by list number and entry key. You can also specify 16 bytes of user data, called the user notification controls, to reside in the EMC.
The IXLLIST REQUEST=MONITOR_SUBLISTS request allows you to register interest in monitoring multiple sublists (from 1 to 1024) with a single command. Information about the sublists in which you wish to register interest is stored in a buffer area that you specify. The information about each sublist is mapped by the macro IXLYMSRI and includes the following:
- List number of the sublist to be monitored
- List entry key of the sublist to be monitored
- 16 bytes of user-defined data, called user notification controls, to reside in the EMC.
On a MONITOR_SUBLISTS request you also must provide a storage area, called a MOSVECTOR, which is used to return the “monitored object state” for each sublist that was processed by the request. The monitored object state indicates whether a sublist was empty or nonempty at the time you registered monitoring interest; thus the MOSVECTOR provides you with information on the initial state of the sublists in which you've registered a monitoring interest.

Each bit in the MOSVECTOR area corresponds one-to-one with an IXLYMSRI entry in the input buffer for the request. Only those bits in the MOSVECTOR that correspond to IXLYMSRI entries that were actually processed by the current request are valid; all other bits in the MOSVECTOR are unpredictable.

A MONITOR_SUBLISTS request can complete prematurely for a variety of reasons, such as a model dependent timeout, an incorrectly-specified list number, or a lack of available event monitor controls. When this occurs, the user should handle the set of registrations that were performed on the current request (including observing the monitored object states in the MOSVECTOR area) before reissuing the MONITOR_SUBLISTS request to continue processing additional IXLYMSRI entries, because the second request will not return valid information for any entries other than those that are actually processed by the second request. On completion of the second request, the state of the MOSVECTOR bits corresponding to IXLYMSRI entries that were processed by the first request is unpredictable.

See MONITOR_SUBLIST, MONITOR_SUBLISTS: Monitoring Sublists for a description of the MONITOR_SUBLIST and MONITOR_SUBLISTS functions of IXLLIST.

Once you have determined that one or more EMCs are queued to your event queue, you can issue an IXLLIST REQUEST=DEQ_EVENTQ request to read the information in the EMCs to identify the sublists that have transitioned from empty to nonempty.