Writing User-Defined Data

When you write a changed data item (CHANGED=YES) to the cache structure, you can also write eight bytes of user-defined data to the directory entry for the data item. (User-defined data might identify the user, typically a process or task identifier, that updates the data item.)

The system writes the user-defined data only if one of the following occurs:

The data item name is currently undefined in the cache structure.
The data item name is defined in the cache structure but there is no data stored in the data entry.
The data item is currently stored in the cache structure and is marked as unchanged.

The system does not use the user-defined data. You establish your own protocol to make use of the data. For cache structures allocated in a coupling facility with CFLEVEL=5 or higher, you can, however, request that the system maintain a queue of the data items for which user-defined data was written to the directory entry. Then, when reading the cast-out class statistical information with REQUEST=READ_COSTATS, the system returns for each cast-out class, the count of data elements and the user data for the UDF order queue entry having the smallest value.

To enable UDF (user data field) order queues, the following conditions must be met:

The structure must be allocated in a coupling facility with CFLEVEL=5 or higher.
The initial IXLCONN invocation to connect to the structure must specify UDFORDER=YES. After the structure's allocation, an indicator in IXLYCONA indicates whether UDF order queues are supported.
The IXLCACHE REQUEST=READ_COSTATS invocation must specify COSTATSFMT=COSTATSLIST.

Note that if a structure is allocated in a coupling facility with CFLEVEL=5 or higher and the IXLCACHE invocation specifies COSTATSFMT=COSTATSLIST, but UDF order queues are not supported by the structure, the system returns the user data of the first entry in the cast-out class queue.