Description

A WRITE_DATA request allows you to write data from the storage areas specified by BUFFER or BUFLIST and/or ADJAREA to a data entry in the cache structure. (A data entry is storage in the coupling facility cache structure comprised of one or more data elements where the system stores a data item. For more information, please see the z/OS MVS Programming: Sysplex Services Guide.) The NAME parameter identifies the data item that will be, or has already been, introduced to the structure. Once introduced to the structure, NAME also references the structure resources (the directory entry and data entry) allocated for that data item.

You can use the WRITE_DATA request to either:

Create a new data entry to contain the data item. (A directory entry would also be allocated.)
Update the contents of an existing data entry with the new or changed data item.

To register or update your interest in a data item, you must specify an index into your local cache vector (VECTORINDEX) to be associated with the data item in the structure. This index identifies a vector entry that cache services uses to indicate both your interest in the data item and the validity of your locally cached copy of the data item. Having registered interest in a data item means that you have a valid copy of the data item in your local cache buffer. When another user updates the data item in the structure, cache services will update the data item's associated vector entry, thereby deregistering your interest in the data item and invalidating your locally cached copy.

Cache services is responsible for deregistering your interest in a data item whenever another user updates the data item in the structure. You are responsible for maintaining the association between the entry in your local cache vector and the copy of the data item in your local cache buffer. You are also responsible for upholding any serialization protocols and procedures established to manage access to this shared data.

For structures allocated in a coupling facility of CFLEVEL=5 or higher, you can request that interest be deregistered in the entry specified by OLDNAME without registering interest in the entry specified by NAME.

The WHENREG parameter allows you to specify that the data be written only if you have already registered your interest in the data item: (To have a registered interest in the data item, the entry must already exist in the structure.)

If you specify WHENREG=YES without VECTORINDEX, your interest must already be registered. (To have a registered interest in the data item, the entry must already exist in the structure and the vector index must be the same as that with which you registered interest.)
If you specify WHENREG=YES with VECTORINDEX (valid only for structures in a CFLEVEL=2 and higher coupling facility), your interest must already be registered and the vector index specified must be the same as that with which you are currently registered. When VECTORINDEX is specified and the vector index does not equal the vector index with which you currently have a registered interest in the data item, the system fails the WRITE_DATA request and returns the vector index with which you are currently registered in the cache answer area.
If you specify WHENREG=NO, the data item is written regardless of whether your interest is already registered. For a structure llocated in a coupling facility of CFLEVEL=4 or lower:
- If the entry exists in the structure, your interest is updated.
- If the entry does not exist in the structure, it is created and your interest is registered.
VECTORINDEX is required when WHENREG=NO is specified for structures allocated in a coupling facility of CFLEVEL=4 or lower.

Optionally, for structures allocated in a coupling facility of CFLEVEL=5 or higher, you can use the REGUSER keyword to specify whether interest in the entry is to be registered or not.
If REGUSER=YES is specified, interest in the entry is registered. When registration is performed, if connection interest is already registered, the specified VECTORINDEX replaces any previously specified local cache vector index for the entry.
VECTORINDEX is required when REGUSER=YES is either specified or selected by default.
If REGUSER=NO is specified, interest in the entry will not be registered. Be aware that entries in a data item for which no interest has been registered are higher-priority candidates for reclaim processing than those for which interest is registered.
VECTORINDEX is required when REGUSER=NO is specified along with OLDNAME and is ignored if REGUSER=NO is specified without OLDNAME. When OLDNAME is also specified with VECTORINDEX, interest is deregistered in the entry specified by OLDNAME.

You can write either changed (CHANGED=YES) or unchanged (CHANGED=NO) data to the cache structure. If you write changed data (cache copy is different from permanent storage copy) you must assign the data item to a cast-out class (COCLASS). You must assign both changed and unchanged data items to a storage class (STGCLASS).

For structures allocated in a coupling facility with CFLEVEL=3 or lower, BUFFER or BUFLIST is required and ELEMNUM must be 1 or greater. For structures allocated in a coupling facility with CFLEVEL=4 or higher,

When CHANGED=YES, BUFFER or BUFLIST is required and ELEMNUM must be 1 or greater.
When CHANGED=NO, neither BUFFER nor BUFLIST is required and ELEMNUM can be 0 or greater.

You also have the option to invalidate other users' local copies of the data (CROSSINVAL) and to obtain the cast-out lock (GETCOLOCK), if necessary.

For structures allocated in a coupling facility of CFLEVEL=5 or higher, the VERSCOMP keyword allows you to specify a value that is to be compared with the version number associated with the entry being processed. The VERSCOMPTYPE keyword is used to define how the comparison is to be performed. If a version comparison mismatch occurs, processing terminates with no change to the structure. If a version comparison is successful, you can update (or choose not to update) the value of the entry version number by specifying the VERSUPDATE keyword.

For structures allocated in a coupling facility of CFLEVEL=9 or higher, the ASSIGN keyword on an IXLCACHE REQUEST=WRITE_DATA,WHENREG=NO request allows you to specify that the system is to suppress the creation of a new directory entry when an existing directory entry is not found.

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