CQSDISC request

The CQSDISC request allows a client to disconnect from one or more coupling facility structures.

Format for CQSDISC

DISCABND function of CQSDISC

You use the DISCABND function of a CQSDISC request while the client is terminating abnormally to terminate client connections to all coupling facility structures.

Read syntax diagramSkip visual syntax diagramCQSDISCFUNC=DISCABNDCQSTOKEN= cqstokenaddressPARM= parmaddressAOPTWORD1= optionwordvalueECB= ecbaddressRETCODE= returncodeaddressRSNCODE= reasoncodeaddressLISTVER= 1
A
Read syntax diagramSkip visual syntax diagramCQSSHUT=YESCQSSHUT=NO

DISCNORM function of CQSDISC

Use the DISCNORM function of a CQSDISC request while the client is terminating normally to terminate client connections to one or more coupling facility structures.

Read syntax diagramSkip visual syntax diagramCQSDISCFUNC=DISCNORMCQSTOKEN= cqstokenaddressPARM= parmaddressCOUNT= countLIST= listaddressAOPTWORD1= optionwordvalueECB= ecbaddressRETCODE= returncodeaddressRSNCODE= reasoncodeaddressLISTVER= 1
A
Read syntax diagramSkip visual syntax diagramCQSSHUT=YESCQSSHUT=NO

DSECT function of CQSDISC

Use the DSECT function of a CQSDISC request to include equate (EQU) statements in your program for the CQSDISC parameter list length, CQSDISC return and reason codes, and literals that can be used to build the OPTWORD1 parameter.

Read syntax diagramSkip visual syntax diagramCQSDISCFUNC=DSECT

Usage of CQSDISC

Restriction: The CQSDISC request does not support structure attributes for resource structures.

The CQSDISC request allows a client to disconnect from one or more coupling facility structures. CQS disconnects client resources associated with the structures. The client needs to issue a CQSDEREG request to completely disconnect from CQS.

A CQSDISC FUNC=DISCABND request, used when the client is terminating abnormally, terminates client connections to all coupling facility structures.

A CQSDISC FUNC=DISCNORM, used when the client is terminating normally, terminates client connections to one or more coupling facility structures. The client specifies a disconnect list containing one or more list entries, for which each entry is a separate disconnect request. As each structure disconnect is completed, the connect token for that structure is invalidated and can no longer be used by the client.

Parameter Description:
COUNT=count
Four-byte input parameter that specifies the number of list entries in the disconnect list.
CQSSHUT=YES | NO
Input parameter that indicates whether or not the CQS address space should be shut down after all clients have disconnected.

If CQSSHUT=YES is specified, new clients continue to be allowed to issue CQSCONN requests. The CQSSHUT FUNC=QUIESCE request can be used to prevent new clients from issuing CQSCONN requests.

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

CQSDISC_SHUTYEQX   CQSSHUT=YES
CQSDISC_SHUTNEQX    CQSSHUT=NO
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 the request is processed synchronously.
LIST=listaddress
Four-byte input parameter that specifies the address of a disconnect list containing one or more entries. Each entry is a separate request to disconnect a client from a coupling facility structure. Some fields in each entry must be initialized by the client prior to the CQSDISC request. Other fields are returned by CQS upon completion of the CQSDISC request.

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

connecttoken
Sixteen-byte input parameter that specifies the 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. This parameter is required.
structureattributes
Four-byte input parameter field that contains the structure attributes.
+0
Flag byte 1, with the following bits defined:
X'80'
When set to 0, indicates that CQS should not perform a structure checkpoint for the structure.

When set to 1, indicates that CQS should perform a structure checkpoint for the structure.

X'40'
When set to 0, indicates that CQS should not perform disconnect processing for the structure if there is any inflight work (locked objects) on the structure. If inflight work is found, CQS will set completion code X'00000008' in the compcode field, and will return a return code of X'0000000C', and a reason code of either X'00000300' or X'00000304' for the request.

When set to 1, indicates that CQS should disconnect from the structure, even if there is inflight work (locked objects) on the structure. If inflight work is found, CQS will set completion code X'00000008' in the compcode field, and will return a return code of X'00000004', and a reason code of X'00000140' for the request, if no other errors in disconnect processing occur. Note that the return and reason code is a warning only; the disconnect processing is still performed.

The remaining bits in this byte are not used, and must be set to zero.

+1
The next 3 bytes are not used, and must be set to zero.
compcode
Four-byte output field to receive the completion code from the request. Possible completion codes are:
X'00000000'
Request completed successfully.
X'00000004'
connecttoken is invalid.
X'00000008'
The client has inflight work for the structure. If the X'40' bit in the first byte of the structureattributes parameter was set to one, the disconnect processing was successful for the structure, and this completion code is informational.

If the X'40' bit was zero, the disconnect processing was not done for this structure, and the CQS client should complete the inflight work before continuing.

X'0000000C'
Structure attributes are not allowed for a resource structure.
LISTVER=1 | listversion
Input parameter that specifies an equate for the list version. Use the DSECT function of a CQSDISC request to include equate (EQU) statements in your program for the CQSDISC list versions.
OPTWORD1=optionwordvalue
Four-byte input parameter that specifies the literals for this request. This parameter can be used instead of CQSSHUT. Equate (EQU) statements for the literal values are listed under the description of the CQSSHUT parameter. Equate statements can also be generated by using the DSECT function. The OPTWORD1 parameter cannot be used if CQSSHUT 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 CQSDISC_PARM_LEN (defined using the FUNC=DSECT request).
RETCODE=returncodeaddress
Output parameter that specifies the address of a 4-byte field to contain the CQSDISC 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 CQSDISC reason code.

Return and reason codes for CQSDISC

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

Table 1. CQSDISC return and reason codes
Return code Reason code Meaning
X'00000000' X'00000000' Request completed successfully.
X'00000004' X'00000130' Request completed successfully for the requested structures. Client is still connected to additional coupling facility structures.
X'00000004' X'00000140' Request completed successfully for the requested structures. At least one structure had inflight work for this client, but the client indicated that disconnect processing was allowed with inflight work at CQSDISC. The completion code field for those structures contains X'00000008'.
X'00000008' X'00000210' cqstoken is invalid.
X'00000008' X'00000218' FUNC is invalid.
X'00000008' X'00000250' count is invalid.
X'00000008' X'00000254' listaddress is invalid.
X'00000008' X'00000284' Parmlist version is invalid.
X'00000008' X'00000288' List version is invalid.
X'0000000C' X'00000300' Request succeeded for at least one but not all list entries. See compcode for individual errors.
X'0000000C' X'00000304' Request failed for all list entries. See compcode for individual errors.
X'00000010' X'00000430' No CQS address space.