CQSUNLCK request

Usage of CQSUNLCK

A CQSUNLCK FUNC=UNLOCK request unlocks one or more data objects and moves them into the first or last position on the queue. The client passes an unlock list that contains one or more list entries, where each entry is a separate unlock request. A successful CQSUNLCK request invalidates the lock token and makes the data object available to any client for a CQSBRWSE, CQSDEL, CQSMOVE, or CQSREAD request.

The CQSUNLCK FUNC=FORCE request enables a CQS client to forcibly unlock data objects read from the specified queue type by the specified failed CQS client, so that the data objects do not remain on the LOCKQ until the failed CQS client restarts. Force unlock also removes the CQS's knowledge of locked data objects, if this CQS processed the CQSREAD requests that locked the data objects.

When a CQS client fails, its locked data objects remain on the LOCKQ until the CQS client restarts, resyncs with CQS, and decides what to do with the locked data objects, or until a CQS client forcibly unlocks the data objects. Locked data objects are not accessible by other CQS clients.

• Define IMSplex with CSL.

  The IMSplex must be defined with a Common Service Layer, so that CQS clients are notified when a CQS client fails.

• Select queue type candidates.

  Select one or more queue types whose data objects are candidates to be forcibly unlocked. All of the data objects with the specified queue type are candidates. There is no way to select specific data objects of a queue type to be forcibly unlocked.

• Forcibly unlock another CQS client's data objects when CQS client fails.

  When a CQS client fails, it may leave locked data objects on the LOCKQ. Another CQS client should issue the CQSUNLCK FUNC=FORCE request, so that data objects do not remain on the LOCKQ until the failed CQS client restarts.

  Issue a CQSUNLCK FUNC=FORCE request only to forcibly unlock data objects of a CQS client that is currently not active. It is up to the CQS client issuing the CQSUNLCK FUNC=FORCE request to ensure that the target CQS client is not active.

  It is up to the CQS clients in the IMSplex to ensure that only one CQS client issues the CQSUNLCK FUNC=FORCE request. All members in an IMSplex defined with a CSL are notified when a member fails. Multiple CQSUNLCK FUNC=FORCE requests may have the following undesirable results:

  • Unnecessary CF accesses.

    The CQSUNLCK FUNC=FORCE request incurs multiple CF accesses to look at data objects on the candidate queue type. If multiple CQSUNLCK FUNC=FORCE requests are issued, each request makes the same numerous CF accesses. These extra CF accesses are unnecessary and incur additional performance overhead. If the performance overhead of unnecessary CF accesses is unacceptable, it is up to the CQS clients in the IMSplex to ensure that only one CQS client issues the CQSUNLCK FUNC=FORCE.

    It is up to the CQS clients in the IMSplex to ensure that exactly one CQS client issues the CQSUNLCK FUNC=FORCE request successfully. If a CQS client issues the CQSUNLCK FUNC=FORCE request and a failure occurs, such as CQSUNLCK error, structure failure, loss of link, and so on, then the CQS clients in the IMSplex must ensure that the CQSUNLCK FUNC=FORCE request is issued successfully after the error is corrected.

  • Data objects incorrectly unlocked.

    If a failed CQS client initializes right away, it might forcibly unlock its own data objects, resync with CQS, and put new data objects on the queue structure, before another CQS client attempts to forcibly unlock the failed CQS client's data objects. The other CQS client could incorrectly unlock data objects for UOWs that are in flight. It is up to the CQS clients in the IMSplex to ensure that exactly one CQS client forcibly unlocks data objects for the specified client.

• Forcibly unlock CQS client's own data objects when CQS client initializes.

  When a CQS client initializes, it should forcibly unlock its own data objects before issuing CQSRSYNC. This ensures that the CQS client's data objects are unlocked before resync, in case no other CQS client was available at failure time to do the force unlock. Force unlock also cleans up CQS's knowledge of the IMS client's locked data objects, since this CQS processed the CQSREAD request that locked the data objects.

• Resync with CQS, handling UOWs that are candidates for unlock force.

  When building the resync list to pass to CQS on the CQSRSYNC request, mark all candidates for the UNLOCK FORCE with a CQS client status of forced. CQS resync checks for the client status of forced and sets the UOWs to a CQS status of unlock in sync.

• Forcibly unlock other failed CQS clients' data objects when CQS client initializes.

  When a CQS client initializes, it should forcibly unlock the data objects of failed CQS clients, in case no other CQS client was available to do the force unlock when the CQS clients failed. After an initializing CQS client resyncs with CQS, it should issue one CQSUNLCK FUNC=FORCE request per failed CQS client, to forcibly unlock data objects on the candidate queue types.

Parameter Description:

CLIENT=clientnameaddress

Eight-byte input field that specifies the CQS client for which to forcibly unlock data objects. The client name is the same name specified on the CQSREG request when the client registered to CQS. A CQS client can forcibly unlock its own locked data objects before issuing the CQSRSYNC request. A CQS client can forcibly unlock another CQS client's locked data objects after issuing the CQSRSYNC request.

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 list entries in the unlock list or four-byte output parameter to receive the count of data objects that were forcibly unlocked.

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 unlock list. Each entry is a separate CQSUNLCK request. Some fields in each entry must be initialized by the client prior to the CQSUNLCK request. Other fields are returned by CQS upon completion of the CQSUNLCK request.

The CQSUNLL 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:

compcode

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

X'00000000'

Request completed successfully.

X'00000004'

locktoken is invalid.

X'00000008'

Structure inaccessible. Retry request later.

X'0000000C'

Unable to unlock the data object, because the original queue for the data object is full. No data objects can be moved to the named queue, but CQSUNLCK requests for other queues are allowed.

X'00000010'

CQS internal error.

X'00000014'

Data object was lost because the structure was rebuilt. The data object was nonrecoverable and a rebuild occurred after the data object was locked. The data object is now lost.

X'00000018'

z/OS logger write error, data objects were not unlocked.

qpos

One-byte input parameter that indicates the position on the queue to which the unlocked element is to be added.

X'00'

Original client queue position. If the CQSREAD request that locked this data object read the first data object, this request unlocks the data object and adds it to beginning of the queue. If the CQSREAD request read the last data object, this request unlocks the data object and adds it to the end of the queue.

X'01'

End of queue.

X'02'

Beginning of queue.

locktoken

Sixteen-byte input parameter that specifies the lock token that uniquely identifies the data object locked by a CQSREAD request. This parameter is required.

LISTVER=1 | listversion

Input parameter that specifies an equate for the list version. Use the DSECT function of a CQSUNLCK request to include equate (EQU) statements in your program for the CQSUNLCK 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 CQSUNLCK_PARM_LEN (defined using the FUNC=DSECT request).

QTYPE=queuetype

Four-byte input parameter that specifies the queue type from which the locked data objects were read. Valid values for the queue type are from 1 to 255 (decimal).

RETCODE=returncodeaddress

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

Return and reason codes for CQSUNLCK

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