A DELETE_NAMELIST request allows you to specify a set of data entries that you want to delete from the structure. Each entry is represented by a name block, mapped by the IXLYDNNB macro. The name block contains the name of the structure entry for which delete processing is to be performed and optionally, a version comparison value used when version comparison is requested. The name blocks are contained in the storage area specified by BUFFER or the buffers specified by BUFLIST.

The system references the name blocks by an index into the buffer and processes them sequentially beginning with the name block identify by the first index (STARTINDEX) and ending with the data item identified by the last index (ENDINDEX). The name blocks are numbered starting with one.

For each structure entry, the DELETETYPE keyword indicates what specifically will be deleted. The DELETETYPE keyword provides options that allow you to delete the directory entry and associated data, only the changed data but not the directory entry, only the unchanged data but not the directory entry, or any entry (changed or unchanged) but not the directory data.

If any name block fails to identify an existing structure entry, processing either continues or terminates, depending on the value specified for the ERRORACTION keyword. If ERRORACTION=TERMINATE, processing stops and the index value of the name block that caused the problem is returned in the CAADNLINDEX field in the IXLYCAA answer area. If ERRORACTION=CONTINUE, processing continues with the next name block.

Each name block can optionally contain a comparative version number that is to be compared with the version number associated with the cache structure entry identified in the name block. The VERSCOMPTYPE keyword is used to define how the comparison is to be performed. If a version comparison mismatch occurs, then processing will either terminate or continue depending on the value specified for the ERRORACTION keyword. If ERRORACTION=TERMINATE is specified, processing stops and the index value of the name block that caused the problem is returned in the CAADNLINDEX field in the IXLYCAA answer area. If ERRORACTION=CONTINUE is specified, processing continues with the next name block.

A DELETE_NAMELIST can complete prematurely because the request exceeds the time-out criteria for the coupling facility (time-out criteria is model-dependent) or a halt condition is found as a result of specifying HALTONCHANGED=YES. When a request completes prematurely, the system returns an index value (CAADNLINDEX) in the answer area which you can use to restart the DELETE_NAMELIST request. The index value returned when a DELETE_NAMELIST request completes prematurely is the index of the first unprocessed name block (or in the case of when the request was halted because a structure entry met the HALTONCHANGED criteria, the index of the name block that caused the request to halt).

A DELETE_NAMELIST request can be issued only for cache structures allocated in a coupling facility of CFLEVEL=5 or higher. DELETE_NAMELIST requests issued for a cache structure allocated in a coupling facility of CFLEVEL=0 through 4 will fail.

For DELETETYPE=DIRANDDATA, a check of the changed status of data and cast-out lock state for a structure entry may be requested prior to processing the structure entry by specifying the HALTONCHANGED=YES keyword. If a structure entry is found to either contain changed data or for which the cast-out lock is currently held, then processing of the DELETE_NAMELIST request is halted and the system returns the index value (CAADNLINDEX) of the name block meeting the halt criteria in the answer area. When the DELETE_NAMELIST request is halted as per requested, the application is expected to take some action to change the state of the indicated structure entry data to "unchanged" (that is, the cast-out lock is not held and the status of the data is unchanged) before resuming the request. One such action could be to read the entry data for castout, write the data to permanent storage, then reset the cast-out lock to the not-held state. After taking such action, the DELETE_NAMELIST request may be started at the element in the list of name elements that originally caused the request to halt by setting input parameter STARTINDEX to CAADNLINDEX.