Description

A MONITOR_SUBLISTS request allows you to start monitoring a set of sublists in a list structure. Each sublist is designated by a list number and an entry key. You cannot stop monitoring the sublists with the MONITOR_SUBLISTS request. (Use the MONITOR_SUBLIST request to stop the monitoring of each individual sublist.)

While sublist monitoring is in effect, the system will queue or withdraw event monitor controls (EMCs) on your event queue to indicate the empty or nonempty state of the sublists. Use sublist monitoring in conjunction with event queue monitoring to process state transitions for monitored sublists.

Information about the sublists to be monitored is contained in the storage area specified by BUFFER or BUFLIST. The information for each sublist entry is mapped by the IXLYMSRI macro. The entries are indexed with the first entry starting at offset zero in the BUFFER or BUFLIST area. To designate the entries to be monitored, specify the starting and ending index numbers of the IXLYMSRI entries with the STARTINDEX and ENDINDEX keywords.

A MONITOR_SUBLISTS request can complete prematurely for the following reasons:

The request has exceeded the model-dependent time-out criteria. The index of the next IXLYMSRI entry to be processed is returned in the answer area (ANSAREA).
There is insufficient event monitor control space in the list structure to register as a sublist monitor. The index of the first unprocessed IXLYMSRI entry (the entry that experienced the failure) is returned in the answer area.
The user has specified a list number that is not valid in an IXLYMSRI entry. The index of the failing IXLYMSRI entry is returned in the answer area.

Before restarting a MONITOR_SUBLISTS request that has completed prematurely, you should process the entries that were successfully returned. Determine how to restart based on the type of premature completion that occurred.

In the case of model-dependent time-out you can update STARTINDEX to field LAAMNSLS_FAILINDEX in the answer area on a subsequent MONITOR_SUBLISTS request to finish processing the entries.
In the case of insufficient EMC space you must take actions to relieve the space constraints before updating STARTINDEX on a subsequent MONITOR_SUBLISTS request.
In the case of a list number that is not valid, you must correct the erroneous specification before updating STARTINDEX on a subsequent MONITOR_SUBLISTS request.

A MONITOR_SUBLISTS request can be issued only for keyed list structures allocated in a coupling facility of CFLEVEL=3 or higher. MONITOR_SUBLISTS requests issued for a list structure allocated in a coupling facility of CFLEVEL 0, 1, or 2 will fail.