CQSUPD request

Usage of CQSUPD

A CQSUPD creates or updates one or more uniquely named resources on a resource structure. CQSUPD creates a resource if it does not exist, or updates a resource if it does exist. A resource can be created or updated with or without client data. Examples of resources include transactions and control blocks.

Parameter Description:

CONTOKEN=connecttokenaddress

Address of a 16-byte input parameter that specifies the connect token that uniquely identifies the client's connection to a particular coupling facility structure managed by CQS. The connect token is returned by the CQSCONN request.

COUNT=resourcelistcount

Four-byte input parameter that specifies the number of entries in the list.

CQSTOKEN=cqstokenaddress

Address of a 16-byte input parameter that specifies the CQS registration token that uniquely identifies the client's connection to CQS. The registration token is returned by the CQSREG request.

ECB=ecbaddress

Address of a 4-byte input parameter that specifies 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.

LISTSIZE=resourcelistsize

Four-byte input parameter that specifies the size of the resource list. The list size must be specified because each entry in the list might have a variable length.

LISTVER=1 | listversion

Input parameter that specifies an equate for the list version. Use the DSECT function of a CQSUPD request to include equate (EQU) statements in your program for the CQSUPD list versions.

LIST=resourcelistaddress

Address of an input parameter that specifies a variable size resource list containing one or more entries. Each entry is a separate update request. Some fields in each entry must be initialized by the client prior to the CQSUPD request. Other fields are returned by CQS upon completion of the request.

The CQSUPDL 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 fields:

listentrylength

Four-byte input field that specifies the length of the list entry. The list entry length is variable, depending upon the data2 length, if specified. This parameter is required.

resourceid

Twelve-byte input field that contains the unique identifier of the resource to be created or updated on the resource structure. The resource identifier is unique in the IMSplex. The resource identifier consists of a 1-byte name type followed by an 11-byte client-defined resource name. The name type ensures uniqueness of client-defined names for resources with the same name type. Resources of different resource types can have the same name type. Valid values for the name type are decimal numbers from 1 to 255. The client-defined name has meaning to the client and consists of alphanumeric characters. This parameter is required.

resourcetype

One-byte 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. This parameter is required.

reserved

Three-byte reserved field.

options

Four-byte input field that specifies update options. This parameter is optional. Possible options are:

X'80000000'

Return data1 and owner, if update fails because of a version mismatch. This incurs the performance overhead of an additional CF access.

X'40000000'

Return data2, data1, and owner if update fails because of version mismatch. The data2 is returned if data2buffer and data2buffersize are specified. This incurs the performance overhead of an additional CF access.

X'20000000'

Delete data2.

compcode

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

X'00000000'

Request completed successfully.

X'00000004'

Request succeeded successfully, but only partial data returned in data2buffer.

X'00000020'

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

X'00000024'

CQS internal error.

X'00000028'

Version doesn't match that of existing resource.

X'00000030'

Resource already exists as a different name type.

X'00000034'

Structure is full.

X'00000038'

Resourcetype is invalid. The resource type must be a decimal number from 1 to 255.

X'0000003C'

Listentrylength is invalid. The list entry length must be a non-zero number greater than or equal to the minimum list entry length. See the CQSUPDL DSECT.

X'00000040'

Structure is inaccessible.

X'00000044'

No CQS address space.

version

Eight-byte input and output field that specifies the version of a resource. The version is the number of times the resource has been updated. For the initial CQSUPD request to create the resource, version must be zero on input. For a subsequent CQSUPD request to update an existing resource, version must match the existing resource's version. The CQSUPD request increments the version by 1, updates the resource with the new version, and returns the new version as output. If a CQSUPD request to update an existing resource fails because of a version mismatch, CQS returns the correct version to the client as output. This parameter is required. If the data object is created, version is ignored on input and a version of 1 is returned as output.

owner

Eight-byte input and output field that specifies the owner of a resource. On input, owner is set for the resource. Specify zeroes to set no owner of a resource. Only one owner is permitted. If the update request fails because of a version mismatch and the option to return the owner is specified, the owner of the existing resource is returned as output. This parameter is required.

data1

Twenty-four-byte input and output field that specifies data1, a small piece of client data for the resource to be updated. Specify zeroes to set no client data in data1. If the CQSUPD request fails because of a version mismatch and the option to return data1 is specified, data1 of the existing resource is returned as output. The performance of accessing the client data specified by data1 is faster than accessing client data specified by data2. This parameter is required.

data2size

Four-byte input and output field that specifies the size of client data data2 in data2buffer for the resource to be updated. Specify zero on input, if there is no data2 to update. If the CQSUPD request fails because of a version mismatch and the option to return data2 is set, the data2 size of the existing resource is returned as output. This parameter is optional.

data2buffersize

Four-byte input field that specifies the size of the data2buffer containing the client data data2 for the resource to be updated or returned as output. The maximum size that can be specified is 61312 bytes (X'EF80'). Specify zero if data2 does not need to be updated or returned as output. This parameter is optional.

data2buffer

Variable size input and output buffer that specifies data2, a large piece of client data for the resource to be updated. If the CQSUPD request fails because of a version mismatch and the option to return data2 is specified, data2 of the existing resource is returned, as much as fits into the data2buffer. This parameter is optional.

PARM=parmaddress

Address of an input 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 CQSUPD_PARM_LEN (defined using the FUNC=DSECT request).

RETCODE=returncodeaddress

Address of a 4-byte output field to contain the CQSUPD return code. If the return code in register 15 is non-zero, the values returned for returncodeaddress and reasoncodeaddress are not valid because CQS detected an error and did not process the request.

RSNCODE=reasoncodeaddress

Address of a 4-byte output field to contain the CQSUPD reason code.

Return and reason codes for CQSUPD

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