CQSREAD request

Usage of CQSREAD

A CQSREAD request retrieves a copy of the client data object from a specific queue. The data object is not deleted from the queue, but for a CQSREAD FUNC=READ request it is locked, preventing the data object from being accessed by subsequent CQS requests (except ones using the proper lock token). The data object can be retrieved from the beginning or from the end of the queue. The data object is returned in the client buffer provided for the CQSREAD request.

A lock token is returned to the client and identifies the data object. This token must be passed to CQS for any requests that act on the locked data object (for example, CQSDEL, CQSMOVE, CQSREAD, or CQSUNLCK).

If the size of the data object retrieved is greater than the size of the client buffer and PARTIAL=YES is specified, the amount of data that fits in the client buffer is returned to the client. A return or reason code is also returned, indicating a partial data object is returned, as is the actual data object size.

If the size of the data object retrieved is greater than the size of the client buffer and PARTIAL=NO is specified, no data object is returned. A return and reason code is returned, indicating that no data object is returned because the client buffer size is too small. The actual data object size is also returned to the client.

If the size of the data object retrieved is the same size as or smaller than the client buffer, the complete data object is moved into the buffer, and the rest of the buffer is not changed. The data object size is also returned to the client.

A CQSREAD FUNC=CONTINUE request retrieves the rest of the data object when partial data is returned on a prior CQSREAD request.

A CQSREAD FUNC=REREAD request re-reads a locked data object that was previously read and locked (a prior CQSREAD FUNC=READ request). The data object remains locked.

Related reading: See the following example of how to use a CQSREAD request for a CQS client.

Parameter Description:

BUFFER=bufferaddress

Four-byte input parameter that specifies the address of the client buffer that will hold the data object retrieved from the queue.

BUFSIZE=buffersize

Four-byte input parameter that specifies the size of the client buffer.

CONTOKEN=connecttokenaddress

Input parameter that specifies the address of the 16-byte connect token that uniquely identifies the client's connection to a particular coupling facility structure managed by this CQS. The connect token is returned by the CQSCONN request.

CQSTOKEN=cqstokenaddress

Input parameter that specifies the address of the 16-byte CQS registration token that uniquely identifies the client's connection to CQS. The registration token is returned by the CQSREG request.

ECB=ecbaddress

Four-byte input parameter that specifies the address of the z/OS® event control block (ECB) used for asynchronous requests. If ECB is specified, the request is processed asynchronously; otherwise it is processed synchronously.

LCKTOKEN=locktokenaddress

Input and output parameter that specifies the address of the 16-byte lock token for the data object that was locked by the CQSREAD request.

For a CQSREAD FUNC=READ request, the lock token is zero on input. It is also used as an output area to hold the lock token returned to the client. For a CQSREAD FUNC=REREAD or FUNC=CONTINUE request, this field is an input area that contains the lock token returned on a prior CQSREAD request.

LOCAL=NO | YES

Input parameter that indicates whether or not the client should process a local copy of the data object from the client address space.

NO

Indicates the client wants CQS to return the data object from the specified client queue and lock the data object. This causes CQS to access the coupling facility to retrieve the data object.

YES

Indicates that the client is processing a local copy of a data object from its local buffers. This request returns the lock token of the data object which the client can use to access the copy of the data object on the shared queues. The data object was placed on the shared queues by a CQSPUT LOCAL=YES request.

By using a local copy of the data object, the client can reduce the performance overhead of using shared queues. As long as the data object is on the shared queues, it can be recovered if the client fails. As long as the data object remains locked, it is not available to any other client.

The data object is not returned to the client on a CQSREAD request because the client has the local copy. If the client does not issue the CQSREAD LOCAL=YES request and the connection between the client and CQS is lost, CQS unlocks the data object and makes it available to any client.

Restriction: If you specify LOCAL=YES, you cannot use the TIMESTAMP parameter.

The LOCAL parameter cannot be used when the OPTWORD1 parameter is specified. If the OPTWORD1 parameter is specified instead of LOCAL, you can use the following equate (EQU) statements to generate the value for the OPTWORD1 parameter:

CQSREAD_LCLYEQUX  LOCAL=YES
CQSREAD_LCLNEQUX   LOCAL=NO

OBJSIZE=dataobjectsizeaddress

Output parameter to receive the address of a 4-byte field that holds the size of the data object. If the data object size is greater than the client buffer size, this field contains the actual data object size. If partial data is returned, the size of the data object returned is the size of the client buffer specified.

OPTWORD1=optionwordvalue

Four-byte input parameter that specifies the literals for this request. This parameter can be used instead of LOCAL, PARTIAL, and QPOS. Equate (EQU) statements for the literal values are listed in the descriptions for the LOCAL, PARTIAL, and QPOS parameters. Equate statements can also be generated by using the DSECT function. The OPTWORD1 parameter cannot be used if LOCAL, PARTIAL, or QPOS is specified.

Requirement: If you code the OPTWORD1 parameter, you must pass a value that is composed of one equate value for each literal value supported by this macro.

PARM=parmaddress

Four-byte input parameter that specifies the address of a parameter list used by the request to pass parameters to CQS. The length of the storage area must be at least equal to the EQU value CQSREAD_PARM_LEN (defined using the FUNC=DSECT request).

PARTIAL=YES | NO

Input parameter that specifies whether partial data is to be retrieved, and whether the data object is to be locked if the data object size is greater than the client buffer size.

YES

If the data object size is greater than the client buffer size, the data object is locked and partial data is returned in the client buffer. The actual size of the data object is returned in dataobjectsize.

NO

If the data object size is greater than the client buffer size, the data object is neither locked nor retrieved. The actual size of the data object is returned in dataobjectsize.

The PARTIAL parameter cannot be used when the OPTWORD1 parameter is specified. If the OPTWORD1 parameter is specified instead of PARTIAL, you can use the following equate (EQU) statements to generate the value for the OPTWORD1 parameter:

CQSREAD_PRTLNEQUX  PARTIAL=NO
CQSREAD_PRTLYEQUX   PARTIAL=YES

QNAME=queuenameaddress

Input parameter that specifies the address of the 16-byte queue name from which the data object is to be retrieved. The first byte of the queue name identifies the queue type.

QPOS=FIRST | LAST

Input parameter that specifies the position on the queue from which the data object is to be retrieved.

FIRST

The data object is retrieved from the beginning of the queue.

LAST

The data object is retrieved from the end of the queue.

The QPOS parameter cannot be used when the OPTWORD1 parameter is specified. If the OPTWORD1 parameter is specified instead of QPOS, you can use the following equate (EQU) statements to generate the value for the OPTWORD1 parameter:

CQSREAD_QPOSLEQUX  QPOS=LAST
CQSREAD_QPOSFEQUX   QPOS=FIRST

RETCODE=returncodeaddress

Output parameter that specifies the address of a 4-byte field to contain the CQSREAD return code.

If the return code in register 15 is nonzero, the values in the return and reason code fields are invalid, because the CQS interface detected an error and was unable to send the request to CQS.

RSNCODE=reasoncodeaddress

Output parameter that specifies the address of a 4-byte field to contain the CQSREAD reason code.

TIMESTAMP=timestampaddress

Four-byte output parameter that specifies the address of an eight-byte field to contain the time stamp of when the data object was placed on the queues.

Attention: If LOCAL=YES is specified, CQS does not read the data object from the structure, and the time stamp cannot be obtained.

UOW=uowaddress

Output parameter that specifies the address of a 32-byte area to hold the unit of work (UOW) of the data object retrieved from the queue. The UOW was generated by the client that put the data object on the queue using a CQSPUT request.

Return and reason codes for CQSREAD

The following table lists the return and reason code combinations that can be returned for CQSREAD requests. Use a CQSREAD FUNC=DSECT request to include equate statements in your program for the return and reason codes.