Description

A READ_DATA request allows you to read a data item from a data entry in the cache structure and optionally place it in the storage areas specified by BUFFER or BUFLIST and/or ADJAREA.

A data item you attempt to read might not reside in the cache structure at the time the read is requested. (For instance, only a directory entry exists, or neither a directory entry nor a data entry exists.) If this is the case, no data is read. However, you can use a READ_DATA request to allocate a directory entry to the data item. To do this, use the ASSIGN=YES option. This is the method directory-only users employ to allocate a coupling facility cache structure directory entry for a data item.

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.

With a structure allocated in a coupling facility of CFLEVEL=5 or higher, when issuing a READ_DATA request you can choose whether to register interest in the data item. The default, if you do not specify an option, is to register interest in the data item.

You dan register or update your interest in the data item by specifying REGUSER=YES and then specifying 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 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 can specify that registration of your interest in the data item is not to be performed (REGUSER=NO). Be aware that entries in a data item for which no interest has been registered are higher-priority candidates for reclaim processing.

For cache structures allocated in a coupling facility with CFLEVEL=4 or higher, you can specify RETURNDATA=NO to suppress the read function when a REQUEST=READ_DATA is issued. By specifying RETURNDATA=NO, the READ_DATA request will register interest in the entry without returning the associated data. This is useful when data is cached for the entry but you do not want the data to be read. Note that if adjunct is supported by the structure (ADJUNCT=YES on the IXLCONN invocation), data is cached for the entry, and you have specified ADJAREA, then the adjunct will be returned. The CAAADJAREAVALID bit in the cache answer area is set to indicate whether adjunct data was returned.