CQSRSYNC request

Usage of CQSRSYNC

A CQSRSYNC request allows a client to resynchronize indoubt data for one structure with CQS. This request must be the first request the client issues following a CQSCONN request.

A CQSRSYNC request is required even if the client does not have any indoubt units of work (UOWs) to resolve, for example when the client performs a cold start or a warm start after a normal termination. This request is required because CQS might have information about a connection and have unresolved UOWs to process.

If there are unresolved UOWs, CQS calls the client's Structure Event exit routine as part of resynchronization. CQS calls the routine to inform the client of UOWs that CQS knows about and that the client did not pass on the CQSRSYNC request. This process is referred to as CQS-initiated resynchronization.

The exit routine is called during client cold start or restart only if CQS has unresolved UOWs. The Structure Event exit routine can be called more than once for CQS-initiated resynchronization. For each UOW passed to the exit routine, the client is responsible for taking the correct action to resolve the UOW based on the status returned by CQS.

If CQS cold started, CQS has no knowledge of client UOWs. In this case, the resynchronization list is not processed. CQS looks for CQSREAD requests that were incomplete at the time CQS terminated. If there is incomplete work, the data objects are moved to the cold queue and the Structure Event exit routine is called to inform the client of the unresolved UOWs for the data objects.

After the CQSRSYNC request completes, some UOWs might have a deferred resynchronization status. This status indicates that CQS is still resynchronizing the UOW. When CQS completes resynchronization, the Structure Event exit routine is called to indicate the state of the UOW. Deferred resynchronization only applies to UOWs that CQS cannot resynchronize during the CQSRSYNC request, and does not occur for a client cold start. The exit routine is called once for each deferred UOW, and so the exit routine can be called multiple times for deferred resynchronization.

Parameter Description:

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.

COUNT=count

Four-byte input parameter that specifies the number of entries in the resync list.

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.

LIST=listaddress

Four-byte input parameter that specifies the address of the resync list. Each entry contains an indoubt UOW that the client needs to resolve. Some fields in each entry must be initialized by the client prior to the CQSRSYNC request. Other fields are returned by CQS upon completion of the CQSRSYNC request.

The CQSRSYNL list entry DSECT maps the list entries and can be used by the client. Multiple list entries must reside in contiguous storage.

Each list entry contains the following:

clientdata

Four-byte input parameter that specifies the client data field. This parameter is optional. CQS does not use data stored in this entry.

uow

Thirty-two-byte input parameter that specifies the unit of work identifier for the queue. This parameter is required and must be initialized by the client prior to the CQSRSYNC request.

clientstatus

Two-byte input parameter that contains the status of the UOW. This status represents the last action the client performed for this UOW. This parameter is required and must be initialized by the client prior to the CQSRSYNC request.

Possible values for the status are shown in the following table.

Table 1. UOW status from the client

Status	Meaning
X'0010'	Put Complete The last (or only) CQSPUT request in a series of CQSPUT requests has been issued for the UOW. All data objects for the UOW are assumed to be on the coupling facility.
X'0020'	Read The data object for the UOW is assumed to be locked on the coupling facility.
X'0030'	Unlock A CQSUNLCK request with lock token was issued for the UOW. The data object is assumed to have been unlocked and made available on the work queue on the coupling facility.
X'0040'	Move A CQSMOVE request with lock token was issued for the UOW. The data object is assumed to have been moved to a new queue on the coupling facility.
X'0050'	Delete A CQSDEL request with lock token was issued for the UOW. The data object is assumed to have been deleted from the coupling facility.

cqsstate

Two-byte output parameter to receive the resulting state of the UOW from CQS. This parameter is returned by CQS as a result of the CQSRSYNC request.

Possible values for the status are shown in the following table.

Table 2. UOW status from CQS

Status	Meaning
X'0010'	Put Insync Client status is Put Complete. CQS status is Put Complete. CQS knows about the UOW and all data objects for the UOW are out on the coupling facility. A put token is returned for the UOW. The client should use the put token to issue a CQSPUT FUNC=FORGET request.
X'0012'	Resync Deferred Client status is Put Complete. CQS status is Indoubt. This status is only returned for recoverable UOWs. CQS knows about the UOW but is still in the process of determining its status. The client should wait until its Structure Event exit routine is called by CQS. CQS will post the client's Structure Event exit routine, passing the UOW and a status for the UOW. If the status is PUT Insync, a put token for the UOW is also returned. The client should use the put token to issue a CQSPUT FUNC=FORGET request. If the status is PUT Failed, the client must reissue the CQSPUT FUNC=PUT request. If the status is Unknown, the data object might or might not be on the coupling facility.
X'0020'	Read Insync Client status is Read. CQS status is Read Complete. CQS found the data object for the UOW to be locked. A lock token is returned for the UOW. The client should use this lock token on subsequent CQS requests for the data object with this UOW.
X'0030'	Unlock Insync Client status is Read Unlock. CQS status is Unlock Insync. CQS found the data object for the UOW to be locked, and unlocked it. No further action is required by the client.
X'0050'	Delete Insync Client status is Delete. CQS status is Delete Insync. CQS found the data object for the UOW to be locked and deleted it. No further action is required by the client.
X'00F1'	Locked One of the following conditions exists: Client status is Delete. CQS status is Locked. CQS found the UOW to be locked, but could not delete the data object from the structure. The data object remains locked. A lock token is returned for the UOW. The client should use this lock token and reissue the CQSDEL request. Client status is Move. CQS status is Locked. CQS found the data object for UOW in Locked state. The CQSMOVE could not be completed because the new queue name is not available. A lock token is returned for the UOW. The client should use this lock token and reissue the CQSMOVE request. Client status is Unlock. CQS status is Locked. CQS found the UOW to be locked, but could not unlock the data object. The data object remains locked. A lock token is returned for the UOW. The client should use this lock token and reissue the CQSUNLCK request.
X'00F2'	Unknown Client status is any valid client status. The UOW is unknown to CQS. If the client believes the UOW to be in PUT Complete status, the client must determine whether or not to reissue the CQSPUT request. If the client believes the UOW to have a status of Delete, Move, Read, or Unlock, the prior request could have completed.

resynctoken

Sixteen-byte output parameter to receive a token that the client uses to complete processing for the UOW. When the state is Put Insync, this field contains the put token. When the state is Locked, this field contains the lock token. This field is returned by CQS as a result of the CQSRSYNC request.

compcode

Four-byte output field to receive the completion code from the request. Possible completion codes are:

X'00000000'

CQS successfully processed this UOW. Client and CQS are in sync for this UOW. An Insync state is returned for this UOW.

X'00000004'

CQS successfully processed this UOW. Client and CQS are not in sync for this UOW. CQS returns its known state for this UOW.

X'00000008'

clientstatus is invalid. CQS could not resynchronize this UOW. The cqsstate is not returned.

X'0000000C'

uow is invalid. CQS could not resynchronize this UOW. The cqsstate is not returned.

X'00000010'

CQS internal error. CQS could not resynchronize this UOW. The cqsstate is not returned.

LISTVER=1 | listversion

Input parameter that specifies an equate for the list version. Use the DSECT function of a CQSRSYNC request to include equate (EQU) statements in your program for the CQSRSYNC list versions.

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 CQSRSYNC_PARM_LEN (defined using the FUNC=DSECT request).

RETCODE=returncodeaddress

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

Return and reason codes for CQSRSYNC

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