Description

A WRITE_DATALIST request allows you to write data to a cache structure for a given set of entries for a connection specified by CONTOKEN. Each entry to be written to the structure is identified by a write-operation-block (a WOB, mapped by IXLYWOB) contained in the BUFFER or BUFLIST storage area. When BUFFER is specified, 1 to 256 write-operation-blocks are allowed. When BUFLIST is specified, 1 to 16 write-operation-blocks are allowed.

The system references the write-operation-blocks by an index into BUFFER or BUFLIST and an offset specifying the location of the data area to be processed. The entries are processed sequentially beginning with the write-operation-block specified by the first index entry (STARTINDEX) and ending with the write-operation-block specified by the last index entry (ENDINDEX). The write-operation-block entries are numbered starting with 1. DATAOFFSET contains the offset in 256-byte increments into the storage area pointed to bu BUFFER or BUFLIST. This is where the data resides that coincides with the write-operation-blocks.

Each write-operation-block contains the following information:

Name of the entry
Data area size in terms of the number of elements
Storage class
Additional information needed to write an entry to the cache structure

As each write-operation-block is processed, information about the request is returned in a write-operation-response-block (WORB). There is a one-to-one correspondence between each WOB in the BUFFER or BUFLIST and a WORB that the system returns in WORBAREA. The contents of each WORB, mapped by IXLYWORB, are as follows:

The castout count for the castout class to which data was just written
Total changed count for the storage class to which data was just written
The invalidated local cache vector index, if any
Additional information related to writing the data to the cache structure.

Additionally, the answer area (ANSAREA) contains the invalidated local cache validity vector, which is updated for each WOB processed.

When you issue a WRITE_DATALIST request, based on the contents of the WOB, you can specify whether you do not want to register interest in the entry, whether you want to deregister any outstanding interest for a different entry, whether a directory entry is to be assigned, and, depending on the value of a change control indicator in the WOB, how registered interest and cross-invalidations are to be performed.

The suppress registration indicator specifies whether the request should register connection interest in the entry.
The assignment suppression control indicator specifies whether a directory entry should be assigned if one does not currently exist.
OLDNAME specifies the name of the data item for which your interest should be deregistered. If both OLDNAME and NAME are specified in a WOB and their values are not equal, the name replacement control indicator specifies whether deregistration of interest for OLDNAME should be performed.
The change control indicator specifies whether changed data is to be written to an entry in the cache structure.

See z/OS MVS Programming: Sysplex Services Guide for a complete list of WOB indicators and how their settings affect the processing of each entry.

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

Version number comparison fails.
Cast-out class specified is not valid.
Parity bits specified are not valid.
Inconsistency in the changed status of the data.
Data area size specified is not valid.
Storage class specified is not valid.
Inability to obtain resources from the storage class specified.
Inaccurate element number specified.
Entry does not exist.

In these cases, all of the prior write-operation-blocks were processed and the index of the failing write-operation-block is returned in the answer area (CAAWDLINDEX). See z/OS MVS Programming: Sysplex Services Guide for a complete description of the instances listed above.

Processing of an entire WRITE_DATALIST request can be suppressed in the following instances:

The write-operation-block contains both the change control indicator and the get cast-out lock control indicator set.
The write-operation-block contains a local cache vector index that is not valid.
LOCALREGCNTL=YES is specified for the WRITE_DATALIST request, but the assignment suppression control indicator and change control indicator are not set in each write-operation block.

In these cases, none of the specified write-operation-blocks was processed and the index of the failing write-operation-block is returned in the answer area (CAAWDLINDEX).

A WRITE_DATALIST request can complete prematurely because the request exceeds the time-out criteria for the coupling facility (time-out criteria is model-dependent) or because the WORBAREA becomes full before processing is complete for the requested WOBs. When a request completes prematurely, the system returns an index value (CAAWDLINDEX) in the answer area that you can use to restart the WRITE_DATALIST request. The index value when a WRITE_DATALIST completes prematurely is the index of the first unprocessed write-operation-block. Also returned in the answer area is the offset in the data block of the data area for the next write-operation-block to be processed and the invalidated local cache validity vector. All prior write-operation-blocks were processed.

To continue processing the remaining write-operation-blocks, reissue the WRITE_DATALIST request specifying the write-operation-block index and the offset of the next data area returned in the answer area as the STARTINDEX and the DATAOFFSET.

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

For more information, see z/OS MVS Programming: Sysplex Services Guide.