CQSINFRM request

Usage of CQSINFRM

A client uses a CQSINFRM request to register or deregister interest for one or more queues on a specific coupling facility structure. When a queue goes from empty to non-empty, CQS notifies all clients that registered interest for the queue of the change in status by scheduling the Structure Inform Client exit routine.

The client can issue CQSREAD or CQSBRWSE requests to retrieve data from a queue. A client can make data objects available on a queue using CQSPUT, CQSMOVE, or CQSUNLCK requests.

A client that has registered interest in a queue is only notified when the queue goes from empty to non-empty, or if a data object is available on the queue when the CQSINFRM request is issued. The client does not receive notification when additional data objects are placed on a non-empty queue.

After a client deregisters interest in a queue, it is no longer notified when one of the queues goes from empty to non-empty. Because client notifications occur asynchronously with CQSINFRM requests, the client should expect to be notified about new data objects that arrive between the time the client issues the CQSINFRM FUNC=UNINFORM request and the time CQS processes the request.

Parameter Description:

COUNT=count

Four-byte input parameter that specifies the number of structure list entries in the structure 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 structure list. The structure list is built in contiguous storage, and the size of the list must be specified using the LISTSIZE parameter. The structure list should contain an entry for each coupling facility structure for which the client will register or deregister interest. Each structure list entry must contain a list of the queues for which the client will register or deregister interest.

Each connect token in a structure list entry and queue name in the queue list entry must be initialized prior to the request. Upon completion of the request, CQS returns the structure completion code for the structure list and the queue completion code for the queue list.

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

Each structure list entry contains the following parameters:

connecttoken

Sixteen-byte input parameter that specifies the connect token that uniquely identifies the client's connection to CQS and a specific coupling facility structure. The connect token is returned by the CQSCONN request. This parameter is required.

structurecompletioncode

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

X'00000000'

Request completed successfully.

X'00000004'

Request completed successfully for all queues. At least one queue has work on it. See the queue completion code to determine which queues have work on them.

X'00000010'

connecttoken is invalid.

X'00000014'

queuelistcount is invalid.

X'00000018'

Inform exit routine does not exist. The Structure Inform exit routine was not specified on CQSCONN request for structure.

X'00000020'

Request completed successfully for at least one, but not all queues in queuelist. See queuecompletioncode for individual errors.

X'00000024'

Request failed for all queues in queuelist. See queuecompletioncode for individual errors or successes.

X'00000030'

A CQSRSYNC is required for this structure.

X'00000034'

CQSINFRM is not allowed for a resource structure.

queuelistcount

Four-byte input parameter that specifies the number of queues in the queue list. This parameter is required.

Recommendation: For optimum performance, a client that registers interest in many queues should issue multiple CQSINFRM requests, in which each request lists no more than 1024 queues.

queuelist

Variable length input area that contains one or more queue lists. A queue list, built by the client, should contain an entry for each queue on the structure for which the client will register or deregister interest. The queue names must be initialized prior to the request. This parameter is required.

Each queue list entry contains the following:

queuename

Sixteen-byte input field that contains the name of the queue for which the client is registering interest. This parameter is required.

queuerequestflag

One-byte input field that contains flags specific to this queue that can be set for this CQSINFRM request.

X'80'

Call the client Inform exit routine if there are data objects on the queue at the time the client issues the CQSINFRM FUNC=INFORM request. Applies only to CQSINFRM FUNC=INFORM requests.

queuecompletioncode

Four-byte output field to receive the completion code for the specified queue. Possible completion codes are:

X'00000000'

Request completed successfully.

X'00000040'

Work exists on queue.

X'00000044'

queuename is invalid.

X'00000048'

CQS internal error.

X'00000050'

Structure is full. No more event monitoring controls (EMC)s are available for queue registration.

X'00000054'

Structure is inaccessible. Retry request.

LISTSIZE=listsize

Four-byte input parameter that specifies the size of the structure list. The client builds the structure list and must specify the size of the structure list in this field.

LISTVER=1 | listversion

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

RETCODE=returncodeaddress

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

Return and reason codes for CQSINFRM

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