Deleting List Entries from a List

Using IXLLSTM REQUEST=DELETE_LIST to request that a list scan process be performed such that entries meeting a specified set of criteria are removed from the list on which they reside and returned to the pool of free entries for reuse.

Processing begins with the entry located by the LOCATOR keyword and proceeds sequentially along the list in the direction specified by DIRECTION until the head or tail of the list is reached, or if entry key comparison or secondary key comparison is requested, until the scan has progressed past all entries for which those key comparisons could be 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.

Specifying LOCKINDEX in conjunction with LOCKOPER causes lock comparison to precede processing of any list entries. LOCKINDEX may 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.

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 DELETE_LIST scan, because these concurrent operations can cause entries on the list to be skipped or scanned more than once during DELETE_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.

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

Specifying KEYCOMPARE=YES in conjunction with ENTRYKEY causes entry 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 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 deleted, 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 deleted for this request is returned in the answer area specified by ANSAREA.

A DELETE_LIST request might complete prematurely if the coupling facility model dependent timeout criteria is exceeded. In this event appropriate return and reason codes, and the number of entries which have been deleted by the current request are provided. 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 DELETE_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 might be deleted or moved to another position on the same list or a different list) after the completion of the first DELETE_LIST request and before the invocation of the resuming DELETE_LIST request. This might cause the resuming DELETE_LIST request to fail, skip entries, or reprocess some entries that have already been processed. If a resuming DELETE_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 which 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 DELETE_LIST processing is ongoing, this can result in anomalous behavior for the overall DELETE_LIST scan process. Entries on the list might be skipped or reprocessed more than once, and this might result in entries that should have been deleted being "missed" by the scan. For example:

The list is being scanned in a left-to-right direction by a DELETE_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 DELETE_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 DELETE_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 DELETE_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 reprocessed by the scan process.
An entry that matches the DELETE_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 deleted.
Other examples are also possible.

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

To avoid such anomalies, consider using serialized list functions (LOCKINDEX and LOCKOPER) to lock out concurrent operations for the duration of the entire DELETE_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 they must meet the same interface requirements as non-resumed requests. Resumed requests might in turn experience premature completion.

This is a new list services function introduced in Release 9 and cannot be invoked on systems running a level of OS/390® lower than Release 9. DELETE_LIST is only valid when the structure is allocated in a CFLEVEL=9 or higher CF.