CQSCONN request

Usage of CQSCONN

The CQSCONN request connects a client to one or more coupling facility structures. The client specifies a connect list containing one or more list entries, for which each entry is a separate connect request. If the connection to a structure is successful, a connect token is returned to the client, representing the connection to the structure. The client must specify this token on all subsequent CQS requests for that structure. A maximum of 32 clients can use a CQS address space to connect to a coupling facility structure.

• structureattributes
• overflowstructurename
• structureinformexit
• structureinformparm
• qtypecnt
• qtypelist

A CQSCONN FUNC=CONNECT request must be issued after a CQSREG FUNC=REGISTER request and before any other CQS requests. Also, after a CQS abnormal termination and restart, and after the client has reregistered with CQS, a CQSCONN FUNC=CONNECT request is required before the client can issue any other CQS requests.

Parameter Description:

COUNT=count

Four-byte input parameter that specifies the number of list entries in the connect 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.

FCCQSSSN=fccqsssnaddress

Four-byte input parameter that specifies the address of the failed client CQS subsystem. When one client takes over for another client, this is the SSN of the CQS that was connected to the failed client.

This keyword is not applicable to a resource structure.

LIST=listaddress

Four-byte input parameter that specifies the address of a connect list containing one or more entries. Each entry is a separate request to connect a client to a coupling facility structure. Some fields for each entry must be initialized by the client prior to the CQSCONN request. Other fields are returned by CQS upon completion of the CQSCONN request.

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

Note: All fields in the CQSCONNL DSECT currently documented as Not Used must be set to zero by the caller of CQSCONN.

Each list entry contains the following parameters:

compcode

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

X'00000000'

Client connection successful. A connect token is returned to the client.

X'00000004'

The client is already connected to the structure through this CQS. A connect token is returned to the client.

X'00000008'

structurename is invalid.

X'0000000C'

The Structure Event exit routine address was not specified.

X'00000010'

The client is already connected to the structure through another CQS. A client can only be connected to a given structure through one CQS. The client is not connected to the structure through this CQS. This does not affect the status of a client connection with another CQS.

X'00000014'

CQS internal error.

X'00000018'

The client specified the FCCQSSSN= parameter to connect to the structure to take over work for a failed client. CQS could not find a valid system-checkpoint log token for the CQS that was connected to the failed client. CQS issued message CQS0033A, to which the operator replied REJECT.

X'0000001C'

The user ID of the client address space is not authorized to connect to the structure.

X'00000020'

structureinformexit was specified but is not allowed for a resource structure.

X'00000024'

structureinformparm was specified but is not allowed for a resource structure.

X'0000002C'

structureattributes was specified but is not allowed for a resource structure.

X'00000030'

Qtype was specified but is not allowed for a resource structure.

X'00000034'

FCCQSSSN was specified but is not allowed for a resource structure.

structureattributes

Four-byte input and output parameter field that contains the structure attributes.

+0

Flag byte 1, with the following bits defined:

X'80'

Indicates the specification of the structure wait for rebuild attribute. The first client in the sysplex to connect to a structure defines this attribute for all clients. It is returned on the connect request to allow clients to verify that the attribute is set correctly for their needs because it might have been set by a prior client connection.

The value specified for structureattributes remains in effect for the life of the structure, and cannot be changed.

When set to 0, indicates that client requests to write and retrieve data objects from the structure do not wait for a rebuild to complete.

When set to 1, indicates that client requests to write and retrieve data objects from the structure must wait for a rebuild to complete.

X’40’

Output flag returned by CQS. For queue structures only, this flag indicates whether the structure is a non-recoverable structure (whether RECOVERABLE=NO was specified in the CQSSGxxx PROCLIB member for the structure). This flag is set to 1 if the structure is a non-recoverable structure; otherwise, it is set to 0.

This flag is not applicable to a resource structure.

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.

structuretype

One-byte output parameter field that specifies the structure type as either a queue structure or a resource structure.

structureversion

Eight-byte output parameter field that specifies the structure version of the structure to which the client just connected.

structurename

Sixteen-byte input parameter field that contains the name of the structure to which the client wants to connect. This parameter is required.

overflowstructurename

Sixteen-byte output parameter field to receive the name of the overflow structure, if one was defined to CQS in the CQS Global Structure Definition PROCLIB member, CQSSGxxx.

This parameter is not applicable to a resource structure.

connecttoken

Sixteen-byte output parameter field to receive the connect token that uniquely identifies the client's connection to a particular coupling facility structure managed by this CQS.

structureeventexit

Four-byte input parameter field that contains the Structure Event exit routine address. This parameter is required.

structureeventparm

Four-byte input parameter field that contains client data that CQS passes to the Structure Event exit routine every time the exit is called. This parameter is optional; set it to zero if you do not want to pass any data to the exit routine.

structureinformexit

Four-byte input parameter field that contains the Structure Inform exit routine address. This parameter is optional; set it to zero if you do not have a Structure Inform exit routine.

This parameter is not applicable to a resource structure.

structureinformparm

Four-byte input parameter field that contains client data that CQS passes to the Structure Inform exit routine every time the exit is called. This parameter is optional; set it to zero if you do not want to pass any data to the exit routine.

This parameter is not applicable to a resource structure.

qtypecnt

Four-byte input parameter field that contains the number of queue type entries in the queue type list. This parameter is optional; set it to zero if you do not have any entries in the queue type list.

This parameter is not applicable to a resource structure.

qtypelst

Variable length input area for the queue type list.

This parameter is not applicable to a resource structure.

The length of this area is equal to the value specified for qtypecnt. Each queue type entry is a 1-byte value of a queue type that should not be moved to the overflow structure if the primary structure goes into overflow mode. This parameter is optional.

When using version 1 of the CQSCONN parameter list (the default), build the queue type list starting at label CNLQTYPL in the CQSCONNL DSECT, which maps the list entry. When using version 16 of the CQSCONN parameter list, build the queue type list starting at label CNLQTYPL_V16.

After a queue type is defined, it remains in effect for the life of the structure, and is not moved to the overflow structure.

If no queue types are listed, the default is for all queue types to be eligible for overflow. This list should only be included if there are certain queue types the client knows should not be moved (perhaps based on the client's use of the queue types).

Recommendation: Clients should exclude from processing those queue types that allow multiple objects with the same queue name and UOW. CQS cannot recover multiple objects with the same queue name and UOW that are allowed to be moved to the overflow structure.

logstreamname

Twenty-six-byte output parameter field to receive the name of the z/OS log stream associated with the CQS structure. This field is set to all blanks for non-recoverable queue structures and for resource structures.

This field is present only for CQSCONN lists at version 16 or later.

logstreamstructurename

Sixteen-byte output parameter field to receive the name of the CF structure associated with the z/OS log stream that is associated with the CQS structure. This field is set to all blanks for non-recoverable queue structures, resource structures, and structures with DASD-only z/OS log streams.

This field is present only for CQSCONN lists at version 16 or later.

LISTSIZE=listsize

Four-byte input parameter that specifies the size of the connect list. listsize specifies the total length of all entries in the list, not the length of a single entry.

LISTVER=1 | listversion

Input parameter that specifies the parameter list version. Use the DSECT function of the CQSCONN request to include equate (EQU) statements in your program for the CQSCONN list versions and lengths. The following parameter list versions are supported:

1

EQU symbol is CNL_LVER1. This is the default parameter list version. This version of the parameter list includes all fields documented under the LIST= parameter except for those that are specifically noted as being present only in a higher list version. The minimum length of a version 1 parameter list entry is CNL_MINLNV1 bytes. Queue type entries, if present, begin at label CNLQTYPL in the CQSCONNL DSECT, mapping the list entry.

16

EQU symbol is CNL_LVER16. A version 16 parameter list contains additional output fields beyond the fields present in a version 1 parameter list. These additional fields are documented under the LIST= parameter and are returned only when a version 16 format parameter list is passed. The minimum length of a version 16 parameter list entry is CNL_MINLNV16 bytes. Queue type entries, if present, begin at label CNLQTYPL_V16 in the CQSCONNL DSECT, mapping the list entry.

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

RETCODE=returncodeaddress

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

Return and reason codes for CQSCONN

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