CQSBRWSE request

Usage notes

A CQSBRWSE FUNC=BROWSE request retrieves a copy of a data object from a specific queue on a queue structure. The first CQSBRWSE FUNC=BROWSE request takes a snapshot of the data objects that meet the selection criteria and returns a copy of the first data object. The data object is neither deleted nor locked, and can be accessed by any subsequent CQS request. Each subsequent CQSBRWSE FUNC=BROWSE request retrieves a copy of the next data object. The data object is returned in the client buffer that is specified on the CQSBRWSE request. The size of the data object is passed to the client.

A browse token maintains the cursor position of the data objects that are being browsed. A CQSBRWSE FUNC=BROWSE request with a zero browse token returns the first data object. A CQSBRWSE FUNC=BROWSE request with a non-zero browse token retrieves the next data object on the queue that is associated with the browse token. If the data object that is returned is the last data object on the queue, CQS invalidates the browse token and frees any data structures associated with that browse token.

When a CQSBRWSE FUNC=BROWSE request is issued and the buffer that is passed is not large enough to hold the next data object, partial data is returned. The buffer is filled with as much of the data object as can fit. The CQSBRWSE FUNC=CONTINUE request retrieves the rest of the data object.

A CQSBRWSE FUNC=BRWSOBJS request retrieves information about one or more data objects from a resource structure. The first CQSBRWSE FUNC=BRWSOBJS request takes a snapshot of the data objects that meet the selection criteria and returns information about one or more of those data objects. The request returns as many data object entries as fit are returned in the client buffer that is specified on the CQSBRWSE request. Each subsequent CQSBRWSE FUNC=BRWSOBJS request retrieves the next set of data object entries. A browse token maintains the cursor position of the data objects that are being browsed. A CQSBRWSE FUNC=BRWSOBJS request with a zero browse token retrieves information about as many data objects as fit in the buffer. A CQSBRWSE FUNC=BRWSOBJS request with a non-zero browse token retrieves the next group of data object entries. If the buffer contains information about the last data object being browsed, CQS invalidates the browse token and frees any data structures associated with that browse token.

A CQSBRWSE FUNC=COMPLETE request indicates to CQS that the CQSBRWSE request that is associated with a browse token is complete. The browse token from the prior CQSBRWSE request is required. CQS invalidates the browse token and frees any data structures that are associated with it. The client should issue a CQSBRWSE FUNC=COMPLETE request if it is not retrieving all of the data objects on the specified queue.

The CQSBRWSE FUNC=CONTINUE request is not supported for a resource structure because the CQSBRWSE FUNC=BRWSOBJS request does not return partial data.

Parameters

BRWTOKEN=browsetokenaddress

Input and output parameter that specifies the address of the 16-byte browse token. The browse token maintains the cursor position of the data objects that are being browsed.

Set the browse token to zero on the initial CQSBRWSE request. Pass the browse token that is returned by CQS on a CQSBRWSE FUNC=BROWSE or FUNC=BRWSOBJS request as input on a subsequent CQSBRWSE=BROWSE, CQSBRWSE=CONTINUE, CQSBRWSE=COMPLETE, or CQSBRWSE=BRWSOBJS request.

On output, the browse token uniquely identifies the current data object that is being browsed, which is returned in the buffer identified by the BUFFER parameter.

For a CQSBRWSE FUNC=CONTINUE request, a CQSBRWSE FUNC=COMPLETE request, or a subsequent CQSBRWSE FUNC=BROWSE request, the BRWTOKEN parameter is an input parameter that specifies the browse token returned by CQS on the prior CQSBRWSE FUNC=BROWSE request.

BUFFER=bufferaddress

4-byte input parameter that specifies the address of a client buffer that holds information that is retrieved about one or more data objects.

For a CQSBRWSE FUNC=BROWSE request, the client buffer contains a copy of the data object retrieved from the queue on a queue structure.

For a CQSBRWSE FUNC=BRWSOBJS request, the client buffer contains the count of data object entries and one or more data object entries. Each data object entry contains information about one resource data object that is retrieved from the resource structure. Each data object entry contains information about a browsed data object such as the resource ID, the completion code, resource ID status, version, owner, client data1, optional client data2, and user data that was passed in the input list. If the size of the information is greater than the buffer size passed by the client, the buffer is filled with as many resource entries as can fit. The BUFFER is mapped by the CQSBRWSB DSECT.

The resource ID status indicates how the resource ID in the data object entry is associated with the input parameter. With this information, you can tie the input parameter to the data object entries that are generated in the output buffer. Possible resource ID statuses are:

Specific parameter

A specific resource ID. This data object entry contains the resource ID that matches the input parameter.

Wildcard parameter

A wildcard parameter was specified. This data object entry contains the wildcard parameter and a completion code. This data object entry does not contain information about a specific resource ID. If the completion code is zero, one or more wildcard match list entries follow.

Wildcard match

A wildcard parameter was specified. This data object contains information about one resource ID that matches the input wildcard parameter. All wildcard match list entries follow contiguously after a wildcard parameter list entry.

Possible completion codes are:

X'00000000'

Request completed successfully.

X'00000020'

The Resourceid parameter is invalid. The name type must be a decimal number from 1 to 255.

X'00000024'

CQS internal error.

X'00000040'

No resources matching either resource ID, resource type, owner, or some combination of these, were found.

BUFSIZE=buffersize

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

CLDTOKEN=coldqueuetokenaddress

Output parameter that specifies the address of the 16-byte cold-queue token for the data object, which, along with the UOW, identifies an object on the cold queue.

You can use the cold-queue token and unit of work (UOW) on a CQSRECVR request to retrieve or delete objects on the cold queue.

CLIENT=clientnameaddress

4-byte output parameter that specifies the address of an 8-byte field to contain the name of the client that locked the data object with a CQSREAD request. This parameter is valid only when the QTYPE=COLD parameter is specified.

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=resourcelistcount

4-byte input parameter that specifies the number of entries in the resource 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

4-byte input parameter that specifies the address of the z/OS® event control block (ECB) that is used for asynchronous requests. If ECB is specified, the request is processed asynchronously; otherwise, it is processed synchronously.

LIST=resourcelistaddress

Address of a variable size input parameter that specifies a resource list that contains one or more entries. Each entry is a separate browse request. The client must initialize some fields in each entry before issuing the CQSBRWSE request. Other fields are returned by CQS when the request completes.

The CQSBRWSL 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 parameters:

resourceid

12-byte input field that contains the unique identifier of the resources to be browsed. The resource ID can be a wildcard parameter. The resource ID is unique in the IMSplex. The resource ID consists of a 1-byte name type, followed by an 11-byte client-defined name. The name type ensures uniqueness of client-defined names for resources with the same name type. Resources of different resource types might have the same name type. A valid value for the name type is a decimal number from 1 to 255. The client-defined name has meaning to the client and consists of alphanumeric characters. If you use a wildcard parameter to specify the resource ID, also specify the resource type, to enhance performance. You must specify the resource ID, resource type, or both.

resourcetype

1-byte input field that specifies the resource type. The resource type is a client-defined physical grouping of resources on the resource structure. Valid values for the resource type are decimal numbers from 1 to 255. If the resource type is greater than the maximum number of resource types defined by CQS (11), it is folded into one of the existing resource types. You must specify the resource type, resource ID, or both.

reserved

3-byte reserved field.

owner

8-byte input parameter that identifies the owner of the resource data objects to be browsed. The CQSBRWSE request returns only those resource data objects that are owned by the specific owner. owner is an optional parameter.

options

4-byte input parameter that specifies browse options. Possible options are:

X'80000000'

Return data2 for the browsed data objects.

userdata

Four-byte input parameter that specifies user data. This user data is passed on output for each data object that matches the input resource ID parameter.

LISTVER=1 | listversion

Input parameter that specifies an equate for the list version. The default value is 1. Use the DSECT function of a CQSBRWSE request to include equate (EQU) statements in your program for the CQSBRWSE list versions.

OBJSIZE=dataobjectsizeaddress

Output parameter that specifies the address of a 4-byte area to store the size of a data object or data object entry.

If a CQSBRWSE FUNC=BROWSE request is issued and the size of the data object is greater than the buffer size passed by the client, the buffer is filled with as much of the data object as fits. The request receives a return and reason code indicating partial data returned. The size of the data object is returned in the location specified by the OBJSIZE parameter. If the size of the data object is less than or equal to the size of the buffer, the data object is moved into the buffer and the remainder of the buffer is not changed.

If a CQSBRWSE FUNC=BRWSOBJS request is issued, as many data object entries as can fit are moved into the buffer. The client must then issue a subsequent CQSBRWSE FUNC=BRWSOBJS request to retrieve the next data object entries. If the buffer is not large enough to hold the next data object entry, the request receives a return and reason code indicating the buffer is too small. The size of the next data object entry to be returned is saved in the location specified by the OBJSIZE parameter.

PARM=parmaddress

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

QNAME=queuenameaddress

4-byte output parameter that specifies the address of a 16-byte queue name field.

For a CQSBRWSE request that specifies the QTYPE=COLD and CLDTOKEN parameters, the queue name field is an output field to contain the original client queue name for the data object being returned. This client queue name contained the data object before it was moved to the cold queue.

For all other CQSBRWSE requests, the queue name field is an input field that specifies the queue name from which the data object is retrieved for all CQSBRWSE requests.

QTYPE=COLD

Input parameter that specifies the queue type from which the data object is to be retrieved. COLD Indicates that the data object is to be retrieved from the cold queue.

RETCODE=returncodeaddress

Output parameter that specifies the address of a 4-byte field to contain the CQSBRWSE return code.

If the return code in register 15 is a non-zero value, 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 CQSBRWSE reason code.

TIMESTAMP=timestampaddress

4-byte output parameter that specifies the address of an 8-byte field to contain the time stamp when the data object was placed on the queues.

UOW=uowaddress

Output parameter that specifies the address of a 32-byte area to hold the unit of work (UOW) of the data object retrieved from the queue. The UOW is a unique identifier generated by the client that stored the data object on the queue (CQSPUT request).

Return and reason codes

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