Description

A CASTOUT_DATALIST request allows you to read a set of data items from entries in the cache structure to the storage areas specified by BUFFER, BUFLIST, DEIBAREA, and/or ADJAREA. From these areas, the data can be written to permanent storage such as DASD. This is part of the cast-out process. The set of entries identified for castout processing is specified by CASTOUTLIST, which contains a list of up to 8 16-byte entry names.

The system references the entries in the CASTOUTLIST by an index into the list and processes them sequentially beginning with the entry specified by the first index (STARTINDEX) and ending with the entry identified by the last index (ENDINDEX). The entries are numbered starting with 1.

When you issue a CASTOUT_DATALIST request:

A cast-out lock is obtained for the set of entries specified in CASTOUTLIST. This lock protects the data item from further cast-out processing until the cast-out lock is released. (To release the cast-out lock, you must issue an UNLOCK_CASTOUT request.)
The change indicator in the directory entry for each entry is updated to indicate the data entry contains unchanged data. (Note that the data is considered changed until the cast-out lock is released.)

When processing is initiated for a CASTOUT_DATALIST request, the system moves the DEIB, which contains directory information for the entry, to DEIBAREA and adjunct data, if present in the structure, to ADJAREA for the first processed name in the CASTOUTLIST pointed to by STARTINDEX. The data area from the first processed entry is moved to the output BUFFER or BUFLIST. Subsequent processing of entries in the CASTOUTLIST move the DEIB, adjunct data if it exists, and the data area from the processed entry to the output BUFFER or BUFLIST. This continues until the end of the CASTOUTLIST pointed to by ENDINDEX is reached or until processing is discontinued.

Processing for a CASTOUT_DATALIST request can be discontinued in the following instances:

Another connection or process currently holds the cast-out lock for the entry being processed. The entry is not processed and ANSAREA contains:
- The index of the name in the CASTOUTLIST
- The value of the cast-out lock
- The value of the cast-out lock state
All prior entries in the CASTOUTLIST will have been processed.
Entry data is not cached, or the cached entry data is not changed. The entry is not processed and ANSAREA contains:
- The index of the name in the CASTOUTLIST
- The changed data indicator
- The data-cached indicator
All prior entries in the CASTOUTLIST will have been processed.
The entry name being processed in the CASTOUTLIST is not in the directory. The entry is not processed and ANSAREA contains:
- The index of the name in the CASTOUTLIST
All prior entries in the CASTOUTLIST will have been processed.
The size of the BUFFER or BUFLIST is not large enough to contain the data area for the entry specified by STARTINDEX. The entry is not processed and ANSAREA contains:
- The number of elements in the indexed entry
No entries are processed.
The remaining space in the BUFFER or BUFLIST is not large enough to contain the data area for the current entry in the CASTOUTLIST. The entry is not processed and ANSAREA contains:
- The index of the entry in CASTOUTLIST being processed
- The number of elements in the desired entry
All prior entries in the CASTOUTLIST will have been processed.

A CASTOUT_DATALIST can complete prematurely because the request exceeds the time-out criteria for the coupling facility. (Time-out criteria is model-dependent.) When a request completes prematurely, the system returns an index value (CAACDLINDEX) in the answer area that you can use to restart the CASTOUT_DATALIST request. The index value when a CASTOUT_DATALIST completes prematurely is the index of the first unprocessed entry in the CASTOUTLIST.

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