Description

A READ request allows you to read a single list entry from the list structure into the storage areas specified by BUFLIST or BUFFER and/or ADJAREA. To designate an entry to be read, specify one of the following parameters or parameter combinations:

List number (LISTNUM) with list position (LISTPOS)
Entry identifier (ENTRYID)
Entry name (ENTRYNAME)
Locate by list cursor (LOCBYCURSOR) with a list number (LISTNUM)
Entry key (ENTRYKEY) with a list number (LISTNUM)

Entry keys, however, are not unique within the structure such that different entries may have the same key (a sublist) on the same list. If there is a sublist of entries with the same key as the ENTRYKEY key (or that satisfies the KEYREQTYPE criteria, if specified), the entry that is designated is the entry at the HEAD or TAIL of the sublist as specified by LISTPOS. (KEYREQTYPE allows you to designate an entry with a key that varies from, but is as close as possible to, the specified key.)

With a coupling facility of CFLEVEL=1 or higher, the following additional functions are supported for a READ request:

You can specify that a list entry is to be read only after a successful comparison of the list authority value for the target list with a user-specified value. You specify the list authority comparison requirements using AUTHCOMP and AUTHCOMPTYPE. If the request is successful, you can also update the list authority value to a new value that you specify with NEWAUTH.
You can specify that a list entry be read only if it passes a version number comparison. You specify the version comparison requirements using VERSCOMP and VERSCOMPTYPE.
There are additional list cursor options. You can update the list cursor conditionally, and you can set the list cursor to point to the current entry instead of the previous or next entry.

A READ request reads any combination of the following types of data for the designated entry:

List entry controls
Entry data
Adjunct data

Whether a particular type of data is returned depends on whether you specified the local storage area to contain that data. Listed below are the types of data that are returned when the indicated storage areas are specified:

List entry controls, the number of list entries or elements residing on the list, and the total number of allocated entries in the structure are returned in the answer area (ANSAREA) mapped by IXLYLAA.
Entry data is returned in a buffer (BUFFER) or list of buffers (BUFLIST).
Adjunct data is returned to the adjunct area (ADJAREA).
If you do not specify either BUFFER or BUFLIST, or ADJAREA, list entry controls are returned in the answer area.

Additionally, you can perform locking functions with a READ request by specifying LOCKOPER. The lock designated by LOCKINDEX will be operated on as specified by LOCKOPER.