CQSQUERY request

Usage of CQSQUERY

Below is a list of CQSQUERY requests:

CQSQUERY FUNC=QNAME

For CQSQUERY FUNC=QNAME, the number of data objects for the queuename specified in LIST= is returned.

CQSQUERY FUNC=QNAME1

For CQSQUERY FUNC=QNAME1, the status of each queue is returned as either being empty or containing at least one object for the queuenames specified in LIST=.

FUNC=QNAME1 is identical to FUNC=QNAME except for the outputs. FUNC=QNAME1 requires fewer coupling facility (CF) accesses than FUNC=QNAME when there are many objects on a queue. It can be used for situations where users only need to know whether the queue is empty or not.

Important: CQSQUERY FUNC=QNAME1 is available in IMS V15 and higher versions and requires APAR PH40806.

If a CQSQUERY FUNC=QUNAME1 request is issued to a CQS that is either lower than IMS V15, or is at IMS V15 but without APAR PH40806 installed, the request fails with either:

• For authorized clients, return code RQRCPARM (X'08'), reason code RQYFUNC (X'0218')
• For non-authorized clients, return code RQRCSYS (X'14'), reason code RSCBDRQF (X'0628')

Code using CQSQUERY FUNC=QNAME1 can tolerate a back-level CQS by checking for the above return/reason code combinations, and issuing CQSQUERY FUNC=QNAME if either is received.

CQSQUERY FUNC=QRYOBJS

For CQSQUERY FUNC=QRYOBJS, the number of data objects for the queuename specified in LIST= is returned. Each queue name in the list can be up to 16 bytes long. The first byte of the qname is treated as the QTYPE. The input list for each qname also has 8 bytes of user data that are copied to the output for each entry that is a match for the input queue name.

The CQSQUERY FUNC=QRYOBJS output is returned both in the input list and the output buffer. The input list has the completion code for the queue name. If the completion code is 0, then the queue names that match the input queue name and their queue counts are returned in the output buffer. If the completion code is non-zero, no data is passed for that queue name in the output buffer. The input list has the total queue count found for the queue name. If the queue name is a wildcard parameter, this queue count is the total queue counts of all the queue names that match the wildcard parameter. An entry for each queue name that is a match is passed in the output buffer along with the queue count for the queue name. If the buffer size specified is too small, the data that fits in the buffer is passed back, and the actual length required is passed back in the QDATASZ field.

Recommendation: Use the CQSQUERY FUNC=QRYOBJS request carefully, because it causes CQS to read every data object on the queue type, and thus could have a significant performance impact.

CQSQUERY FUNC=QTYPE

For CQSQUERY FUNC=QTYPE, information about all the queues in the queue type is returned, including the queue name, data object count, oldest data object time stamp, and newest data object time stamp.

Recommendation: Use the CQSQUERY FUNC=QTYPE request carefully, because it causes CQS to read every data object on the queue type, and thus could have a significant performance impact.

For CQSQUERY FUNC=QTYPE, CQS does the following if the buffer area is not large enough to hold all of the requested data:

• Returns as many complete records that can fit into the buffer area
• Sets QDATASZ to the length that is needed to contain the statistics data in its entirety
• Sets the reason code for 'Partial Data Returned'

The client program can then make another request with a larger buffer.

If the QAGE parameter is specified, only information for queues older than the specified queue age is returned. If you are only interested in queue counts, you can omit the QAGE parameter for better performance of the CQSQUERY request.

CQSQUERY FUNC=STATISTICS

For CQSQUERY FUNC=STATISTICS, CQS returns the following information in the client buffer:

• Status on the current capacity of the primary structure
• Maximum capacity of the primary structure (if XES dynamic reconfiguration is available)
• Current operation mode (normal, overflow, or rebuild)
• Elements-to-entries ratio (returned in the buffer passed by the client for this request)

If an overflow structure is defined and the current operation mode for the primary structure is overflow mode, CQS also returns the current and maximum capacity for the associated overflow structure. If the primary structure is not in overflow mode and an overflow structure is defined, CQS returns the overflow structure name and a status indicating that the overflow structure is not in use.

If the buffer area is not large enough to contain the statistics data for all of the requested structures, CQSQUERY FUNC=STATISTICS sets the STATSZAR field to be the length of a single statistics entry, and sets the reason code to 'Buffer Size Too Small.' The size of the buffer that is required to complete the request can be obtained by multiplying the value returned in STATSZAR by the number of list entries specified in the request.

CQSQUERY FUNC=STRSTAT

For CQSQUERY FUNC=STRSTAT, CQS returns the following information:

• Structure process statistics
• CQS request statistics
• Data object statistics
• Queue name statistics
• z/OS® request statistics
• Structure rebuild statistics
• Structure checkpoint statistics

For this function, CQS does the following if the buffer area is not large enough to hold all of the requested data: The client program can then make another request with a larger buffer.

• Returns as many complete records that can fit into the buffer area
• Sets QDATASZ to the length that is needed to contain the statistics data in its entirety
• Sets the reason code for 'Partial Data Returned'

The following keywords apply to the CQSQUERY macro. Note that some of the information provided here applies to specific CQSQUERY functions.

BUFFER=bufferaddress

Four-byte input parameter that specifies the address of the buffer to hold information passed to the client.

For CQSQUERY FUNC=QTYPE, the buffer is mapped by the CQSQRYQT DSECT. For CQSQUERY FUNC=STATISTICS, the buffer is mapped by the CQSQRYST DSECT. For CQSQUERY FUNC=STRSTAT, the buffer is mapped by the CQSQSTAT DSECT. For CQSQUERY FUNC=QRYOBJS, the buffer is mapped by the CQSQRYQO DSECT.

BUFSIZE=buffersize

Four-byte input parameter that specifies the size of the buffer passed by the client.

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 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 a list containing one or more entries. For the CQSQUERY FUNC=QNAME, CQSQUERY FUNC=QNAME1 and CQSQUERY FUNC=QRYOBJS requests, this list contains queue names for which to retrieve information. The list consists of input and output parameters. At least one list item is required.

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

• For a CQSQUERY FUNC=QNAME or CQSQUERY FUNC=QNAME1 request, 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'

  queuename is invalid.

  X'00000020'

  Structure is inaccessible. Retry request.

  X'00000024'

  CQS internal error.

  clientdata

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

  queuename

  Sixteen-byte input parameter that specifies the queue name for which data object count information is to be retrieved. This parameter is required.

  qcnt

  Four-byte output field to receive one of the following output information about the queue when the request is successfully completed (the compcode field is X'00000000’):

  • For FUNC=QNAME, qcnt contains the count of objects on the queue.
  • For FUNC=QNAME1, qcnt contains zero if there are no objects on the queue. It contains a non-zero value if there is at least one object on the queue.

• For a CQSQUERY FUNC=STATISTICS request, 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'

  Request completed successfully.

  X'00000008'

  connecttoken is invalid.

  X'0000000C'

  A CQSRSYNC is required for this structure.

  X'00000020'

  Structure is inaccessible. Retry request.

  X'00000024'

  CQS internal error.

  clientdata

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

  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.

  outputoffset

  Four-byte output parameter that specifies the offset of the output data area for this entry in the output buffer.

• For a CQSQUERY FUNC=QRYOBJS request, 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'0000'

  Request completed successfully. A list of resources that match the qname and their queue counts are returned in the output buffer.

  X'0004'

  qname is invalid.

  X'0010'

  qname does not have any objects. The queue count is zero.

  X'0020'

  Retry error for the qname. Retry the CQSQUERY FUNC=QRYOBJS to obtain the queue counts. The output returned in the output buffer might be invalid.

  X'0024'

  CQS internal error. Retry the CQSQUERY FUNC=QRYOBJS to obtain the queue counts. The output returned in the output buffer might be invalid.

  clientdata

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

  queuename

  Sixteen-byte input parameter that specifies the queue name for which data object count information is to be retrieved. This parameter is required. The queuename can be a wildcard parameter.

  qcnt

  Four-byte output parameter that specifies a field to contain the data object count for the queue name specified. If the queuename is a wildcard parameter, this parameter specifies a field to contain the total queue counts of all qnames that match the wildcard parameter.

LISTVER=1 | listversion

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

QAGE=queueagevalue

Input parameter that specifies the address of a 4-byte field to contain the queue age in the unit that is specified by the QAGEUNITS parameter.

The queue age is determined by the age of its oldest message. Valid queue age values are:

• From X'0' to X'16D' (0 to 365 in decimal) if the unit is days
• From X’0’ to X’ 1E13380’(0 to 31536000 in decimal) if the unit is seconds

This parameter is used as a filter for determining which queues the CQSQUERY FUNC=QTYPE request processes. The CQSQUERY request returns information for queues that contain data objects which are older than the specified queueagevalue. If you specify 0 for queueagevalue, or omit the QAGE parameter, the CQSQUERY request processes all queues for the queue type.

Important: Specifying QAGE causes all the data objects in the queue to be read, which incurs additional performance overhead.

QAGEUNITS=DAYS|SECONDS|queueageunitsvalue

Input parameter that specifies the unit of the queue age value that is passed onto QAGE. Available units are DAYS, SECONDS, or a value that can be set at run time in a register or in a 4-byte field in storage. The default unit of the queue age is DAYS.

If the QAGEUNITS parameter is specified as SECONDS or the value is 1 (EQU value QRY_QAGEUNITS_SECONDS, defined in macro CQSQRYL), the unit of the queue age is seconds.

If QAGEUNITS is specified as DAYS or the value is 0 (EQU value QRY_QAGEUNITS_DAYS, defined in macro CQSQRYL), the unit of the queue age is days.

QDATASZ=querydatasizeaddress

Output parameter that specifies the address of a 4-byte field to contain the size of the information returned to the client. If partial data is returned in the buffer, this field contains the actual buffer size needed to hold the information.

QTYPE=queuetypeaddress

Input parameter that specifies the address of a 4-byte field that contains the queue type. Valid values for the queue type are from 1 to 255 (decimal).

QTYPENM=COLDQ

Input parameter that indicates that the CQSQUERY request is for information about the COLDQ.

This parameter enables a client to obtain the same type of information for the cold queue as can be obtained for a client queue using the CQSQUERY FUNC=QTYPE request with QTYPE=queuetypeaddress specified.

RETCODE=returncodeaddress

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

STATSZAR=statisticssizeaddress

Output parameter that specifies the address of a 4-byte field to contain the length of a single statistics entry returned in the output buffer for a CQSQUERY FUNC=STATISTICS request.

If partial data is returned, the size of the required buffer can be obtained by multiplying the value returned in this field by the number of list entries specified.

Return and reason codes for CQSQUERY

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