CQSRECVR request

Usage of CQSRECVR

A CQSRECVR FUNC=DELETE request deletes a data object associated with a UOW from the cold queue. Only one data object is deleted.

A CQSRECVR FUNC=RETRIEVE request retrieves a copy of the data object associated with a UOW from the cold queue. The data object remains on the cold queue, and is available for other CQSRECVR requests. The data object is returned in the client buffer specified for the CQSRECVR FUNC=RETRIEVE request.

If the data object is the same size as or smaller than the client buffer provided, the data object is returned in the buffer, and the rest of the buffer is not changed. The size of the data object is returned to the client.

If the size of the data object is greater than the size of the client buffer, the data object is not returned. The size of the data object is returned to the client.

A CQSRECVR FUNC=UNLOCK request unlocks a data object associated with a UOW on the cold queue. The data object is moved from the cold queue to the original client queue, and is available for other CQS requests. The position to which the data object should be moved can be specified by the 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.

CLDTOKEN=coldqueuetokenaddress

Input parameter that specifies the address of a 16-byte cold-queue token, which along with the UOW identifies the data object that is to be recovered from the CQS cold queue (COLDQ).

The cold-queue token is passed to the client in the SEVX_RETOKEN field of the Resync entry in the CQS Structure Event exit routine. This exit routine is called for a CQS-initiated resynchronization when the UOW status is COLD.

CONTOKEN=connecttokenaddress

Input parameter that specifies the address of a 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 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.

OBJSIZE=dataobjectsizeaddress

Output parameter that specifies the address of a 4-byte area to hold 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 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 QPOS. Equate (EQU) statements for the literal values are listed in the description of the QPOS parameter. Equate statements can also be generated by using the DSECT function. The OPTWORD1 parameter cannot be used if 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 CQSRECVR_PARM_LEN (defined using the FUNC=DSECT request).

QPOS=SYSTEM | FIRST | LAST

Input parameter that specifies the position on the queue to which the unlocked data object is to be added. The default is SYSTEM.

FIRST

Indicates the data object is unlocked and added to the beginning of the queue.

LAST

Indicates the data object is unlocked and added to the end of the queue.

SYSTEM

Indicates the data object is unlocked and added to either the beginning or the end of the queue, depending on its original position. If the CQSREAD request that locked this data object obtained the data object from the beginning of the queue, the data object is unlocked and added to the beginning of the queue. If the CQSREAD request obtained the data object from the end of the queue, the data object is unlocked and added to 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:

CQSRECVR_QPOSSEQUX  QPOS=SYSTEM
CQSRECVR_QPOSFEQUX  QPOS=FIRST
CQSRECVR_QPOSLEQUX   QPOS=LAST

RETCODE=returncodeaddress

Output parameter that specifies the address of a 4-byte field to contain the CQSRECVR 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 CQSRECVR reason code.

UOW=uowaddress

Input parameter that specifies the address of a 32-byte area to hold the unit of work (UOW) of a data object. The UOW, together with the coldqueuetoken, identifies the data object to be recovered from the cold queue.

The UOW is passed to the client in the SEVX_REUOW field of the Resync entry in the CQS Structure Event exit routine. This exit routine is called for a CQS-initiated resynchronization when the UOW status is COLD.

Return and reason codes for CQSRECVR

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