Reading List Entries from a List

Use IXLLSTM REQUEST=READ_LIST to request that a list scan process be performed such that reading the entries that meet a specific set of criteria. The entry data, adjunct data, list entry controls, or any combination of these for the selected entries on the list might be read into the buffer storage area specified for the request (designated by BUFFER or BUFLIST).

When adjunct data is requested, the adjunct data for the first entry processed is returned in the storage area specified by ADJAREA. The adjunct data for all other entries is returned in the buffer storage area.

When list entry controls are requested, the entry controls for the first entry processed are returned in the answer area specified by ANSAREA. The entry controls for all other entries are returned in the buffer storage area.

The LOCATOR keyword designates the entry, and the DIRECTION keyword specifies the direction. The Processing begins with the entry and proceeds sequentially along the list in the direction until the head or tail of the list is reached. If the entry key comparison or the secondary key comparison is requested, the process ends when the scan has progressed past all entries for which those key comparisons is successful.

Specifying AUTHCOMPARE=YES in conjunction with AUTHCOMP causes list authority comparison for the designated list to precede processing of any list entries. If the list authority verification fails, the list authority, the list control information and appropriate return and reason codes are provided in the ANSAREA.

Specifying LOCKINDEX in conjunction with LOCKOPER causes lock comparison to precede processing of any list entries. LOCKINDEX can optionally be specified to indicate the index of the serialized list lock to be compared within the lock table for the list structure. If the lock comparison fails, the lock table entry and appropriate return and reason codes are provided in the ANSAREA.

Note: The use of serialized list functions might be useful to serialize the list against other concurrent operations that could otherwise execute in parallel with the READ_LIST scan, because these concurrent operations can cause entries on the list to be skipped or scanned more than once during READ_LIST processing.

Specifying LISTCOMPARE=YES in conjunction with LISTNUM causes list number comparison for the designated starting list entry to precede processing of any list entries. If the designated list entry exists, but the list number verification fails, the list entry controls and appropriate return and reason codes are provided in the ANSAREA.

Specifying VERSCOMPARE=YES in conjunction with VERSCOMP might optionally be used as a filter to restrict processing to those entries with a version number as specified by VERSCOMPTYPE.

Specifying KEYCOMPARE=YES in conjunction with ENTRYKEY causes key comparison to be performed as a filter, as specified by KEYREQTYPE.

Specifying SKEYCOMPARE=YES in conjunction with SECONDARYKEY causes secondary key comparison to be performed as a filter, as specified by SKEYREQTYPE.

DIRECTION can optionally be specified to indicate direction of processing for traversing the list.

The absence of AUTHCOMPARE or LISTCOMPARE, or specifying AUTHCOMPARE=NO or LISTCOMPARE=NO indicates no list authority or list number comparisons are to be performed before processing any list entries. The absence of LOCKINDEX indicates that no lock comparison is to be performed before processing any list entries.

The absence of VERSCOMPARE, KEYCOMPARE, or SKEYCOMPARE or specifying VERSCOMPARE=NO, KEYCOMPARE=NO, or SKEYCOMPARE=NO indicates no version number, entry key value, or secondary key value comparisons are to be performed as a filter when selecting entries to be processed.

For any list entries to be processed, the list number comparison, the list authority comparison and the lock operation, must succeed if they are requested.

For a particular list entry to be read, the version number comparison, the entry key comparison, and the secondary key comparison, must succeed if they are requested. Otherwise, no processing is performed for the current entry and processing continues with the next entry to be considered.

When the request completes successfully, the number of entries for which entry data, adjunct data, or list entry controls or both was read is returned in the answer area specified by ANSAREA.

A READ_LIST request might complete prematurely due to exhaustion of the storage specified for the buffer storage area, or if coupling facility model dependent timeout criteria is exceeded. In this event appropriate return and reason codes are provided, and the number of entries for which data has been returned on the current request is provided in ANSAREA. The list entry controls for the next appropriate entry in the list sequence to be processed is returned in ANSAREA. These list entry controls can be used to designate the entry with which to resume processing on a subsequent, resuming READ_LIST request, so as to continue the overall scan process for the list.

Note: The disposition of this list entry might change as a result of another operation (for example, the entry may be deleted or moved to another position on the same list or a different list) after the completion of the first READ_LIST request and before the invocation of the resuming READ_LIST request. This might cause the resuming READ_LIST request to fail, skip entries, or reprocess some entries that have already been processed. If a resuming READ_LIST request fails with an "entry not found" condition, the list might not yet have been completely scanned and the scan needs to be restarted from the beginning.

If other concurrent operations, such as other commands that can create entries, delete entries, or move entries to a different position on the same list or a different list, are permitted to execute while READ_LIST processing is ongoing, this can result in anomalous behavior for the overall READ_LIST scan process. Entries on the list can be skipped or reprocessed more than once, and this might result in entries that should have been read being "missed" by the scan, or might result in the same entry being read multiple times. For example:

The list is being scanned in a left-to-right direction by a READ_LIST command, and a concurrently-executing command moves an entry on the list to the right. If the moved entry was being processed by the READ_LIST command at the time it was moved, the intervening entries between the moved entry's old position and its new position on the list can be skipped by the scan process.
The list is being scanned in a left-to-right direction by a READ_LIST command, and a concurrently executing command moves an entry on the list to the left. If the moved entry was being processed by the READ_LIST command at the time it was moved, the intervening entries between the moved entry's old position and its new position on the list might be reprocessed by the scan process, and if the entries pass the requested filtering criteria, might be read in again.
An entry that matches the READ_LIST request's filtering criteria is created on, or moved into, the list that is being scanned. Depending on whether the entry is placed onto the list "ahead of" or "behind" the ongoing scan process, the entry might or might not be read.
Other examples are also possible.

Note: Such anomalies can occur both within the processing of a single READ_LIST request, and in the gap between the completion of one READ_LIST request and the initiation of a subsequent, resuming one.

In order to avoid such anomalies, consider making use of serialized list functions (LOCKINDEX and LOCKOPER) to lock out concurrent operations for the duration of the entire READ_LIST scan process, from before initiating the first request, through any premature completion and re-drive processing that may occur, until the scan process indicates that the list has been processed to completion.

Resumed requests are processed identically to non-resumed requests and must meet the same interface requirements as non-resumed requests. For example, the buffer storage area boundary and length requirements are unchanged. Resumed requests might in turn experience premature completion.

See READ_LIST: Reading Multiple List Entries from a List for additional information about reading list entries, including how to handle an incompletely processed request.