CQSDEL request

A CQSDEL request deletes one or more data objects from a queue structure or a resource structure.

Format for CQSDEL

DELETE function of CQSDEL

Use the DELETE function of a CQSDEL request to delete one or more data objects from a queue structure or a resource structure.

DSECT function of CQSDEL

Use the DSECT function of a CQSDEL request to include equate (EQU) statements in your program for the CQSDEL parameter list length and CQSDEL return and reason codes.

Usage of CQSDEL

A CQSDEL request deletes one or more data objects from a queue structure or a resource structure. The client specifies a delete list that contains one or more list entries, for which each list entry is a separate delete request (either by lock token, by queue name, by queue name and UOW, by resource ID, or by resource type and owner). Each list entry is processed separately and receives its own completion code.

Parameter description:

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

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

A 4-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.

FEEDBACK=feedbackaddress

A 4-byte input parameter that specifies the address of a feedback area to receive structure utilization feedback about the CQS structure. This information includes the number of entries and elements that are allocated in the structure and the number currently in use. If the structure is in overflow mode, information about both the primary and overflow structure is returned. This parameter is optional for FUNC=DELETE; it is invalid for other CQSDEL functions. FEEDBACK= is required when FEEDBACKLEN= is specified.

The utilization data returned is guaranteed only to be current for the structures from which the data objects that were specified in the list entries by the LIST= parameter were actually deleted. Data for structures (overflow or primary) that were not accessed is as of the last time CQS put or deleted an object to that other structure, and might be obsolete if that last access was far in the past. This is because CQS receives the structure usage data back from the structure when it issues a write request or a delete request to the structure. CQS saves this information about both primary and overflow structures. However, if CQS does not receive requests to access one of the structures for a period of time, that structure's saved data can become out of date if other CQSs in the IMSplex are updating it. You should consider the data returned in the FEEDBACK area as an approximation of the structures' usage, and not necessarily a precise measurement.

The format of the feedback area is described by mapping macro CQSSFBA – the CQS Structure Feedback Area. This area contains the Product-Sensitive Programming Interface (PSPI). For details about the feedback area, see the CQSSFBA macro shipped with IMS. The fields that are related to the overflow structure are meaningful only when the overflow structure is allocated. They are zero when there is no overflow structure. If the CQSDEL request receives a nonzero return code, the feedback area data might not be returned, depending on how far CQSDEL processing progressed before the failure. For a nonzero CQSDEL return code, either the feedback area is unchanged (no data returned) or it contains the current structure usage data (data returned).

FEEDBACKLEN=feedbacklength

A 4-byte input parameter that specifies the size of the feedback area specified by the FEEDBACK parameter. The FEEDBACKLEN parameter is optional for FUNC=DELETE. FEEDBACKLEN= is required when FEEDBACK= is specified.

SFBA_HDR_LN, the EQU symbol for the feedback area header section length, is defined in the CQSSFBA macro to be the maximum length of the area required for a given CQS version. If you pass a length less than the minimum value, then CQS returns no feedback data.

The feedback area total area length EQU symbol SFBA_LN is defined in the CQSSFBA macro to be the maximum length of the area required for a given CQS version. This EQU value might change in the future if new fields are added. If you cannot tolerate the length of your feedback area changing, you should define your own length value based on the offset+length of the last field in the CQSSFBA DSECT mapping that your program accesses.

You can pass a length less than the maximum value. CQS will truncate the feedback data to fit into your passed area. You can also pass a length greater than the maximum value. CQS will copy back the entire mapped feedback area; any excess storage beyond the area's length is unpredictable on return from CQS.

The feedback area length field SFBA_LENGTH in the header section is an output parameter. It is assigned the maximum length of the feedback area at run time and can be used to obtain the complete feedback data.

If you pass an EQU symbol as the length of the feedback area, ensure that you use the FEEDBACKLEN=@(symbol) notation. Use FEEDBACKLEN=symbol when you pass a symbol that is a label on a word of storage that contains the feedback area length.

LIST=listaddress

A 4-byte input parameter that specifies the address of a delete list containing one or more entries. Each entry is a separate delete request. Some fields in each entry must be initialized by the client prior to the CQSDEL request. Other fields are returned by CQS upon completion of the request.

The CQSDELL 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:

deletetype

One-byte input parameter field that contains the delete type. This is a required parameter. deletetype can have one of the following values:

1: Delete by lock token.
2: Delete by queue name.
3: Delete by queue name and unit of work.
4: Delete by resource ID and version.
5: Delete by resource type with the specified owner.

Recommendation: For better performance, use delete type 1 or delete type 2 because they are more efficient than delete type 3.

deleteqpos

One-byte input parameter field that specifies either that all data objects are to be deleted or the position on the queue of data objects to be deleted. This parameter is only used for delete type 2. deleteqpos can have one of the following values:

1: Delete all data objects on the queue.
2: Delete the first data object on the queue.
3: Delete the last data object on the queue.

The locktoken, deleteqpos, and uow fields are mutually exclusive.

reserved

A 2-byte reserved field.

objdelcnt

A 4-byte output parameter field to receive the number of data objects deleted.

compcode

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

X'00000000': Request completed successfully.
X'00000004': Invalid deleteqpos (Delete type 2).
X'00000008': Invalid deletetype.
X'0000000C': Invalid locktoken (Delete type 1).
X'00000010': Invalid queuename (Delete type 2 or type 3).
X'00000014': Invalid uow (Delete type 3).
X'0000001C': Structure is inaccessible. Try the request again later.
X'00000020': CQS internal error.
X'00000024': Data object not found on queue (Delete type 2) or on queuename for UOW (Delete type 3), or on resource structure (Delete type 4). It is up to the client to determine whether this case should be treated as an error or not.
X'00000028': Delete type 1, 2, or 3 is invalid for a resource structure.
X'00000032': Delete type 4 or 5 is invalid for a queue structure.
X'00000036': Resourceid is invalid. The name type must be a decimal number between 1 - 255.
X'00000040': Version is invalid. The version must be a number greater than zero.
X'00000044': Version does not match that of an existing resource.
X'00000048': Resourcetype is invalid. The resource type must be a decimal number between 1 - 255.

locktoken

A 16-byte input parameter field that contains the lock token. The lock token is returned by the CQSREAD request. This parameter is only used for delete type 1.

The locktoken, deleteqpos, and uow fields are mutually exclusive. The locktoken and queuename fields are also mutually exclusive.

queuename

A 16-byte input parameter field that contains the queue name. This parameter is only used for delete types 2 and 3.

The locktoken and queuename fields are mutually exclusive.

uow

A 32-byte input parameter that contains the unit of work. This parameter is only used for delete type 3.

The locktoken, deleteqpos, and uow fields are mutually exclusive.

resourceid

A 12-byte input parameter that contains the unique identifier of the resource data object to delete. This parameter is required for delete type 4. The resourceid, locktoken, queuename, and resourceytpe fields are mutually exclusive.

version

An 8-byte input and output parameter that contains the version of the resource to be deleted. The version specified must match the version of the resource for the delete request to succeed. The version is a count of the number of times the resource has been updated. This parameter is required for delete type 4. If the delete fails because of version mismatch, the version is returned as output.

resourcetype

A 1-byte input parameter that contains 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 for delete types 4 and 5. Specify zero to delete all resources of a resource type that are not owned.

reserved

A 3-byte reserved field.

owner

An 8-byte input parameter that specifies the owner for which to delete resources of the specified resource type. This parameter is required for delete type 5.

LISTVER=1 | listversion

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

PARM=parmaddress

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

RETCODE=returncodeaddress

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

Return and reason codes for CQSDEL

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

Table 1. CQSDEL return and reason codes
Return code	Reason code	Meaning
X'00000000'	X'00000000'	Request completed successfully.
X'00000008'	X'00000210'	`cqstoken` is invalid.
X'00000008'	X'00000214'	`connecttoken` is invalid.
X'00000008'	X'00000218'	FUNC is invalid.
X'00000008'	X'00000250'	`count` is invalid.
X'00000008'	X'00000254'	`listaddress` is invalid.
X'00000008'	X'00000284'	Parameter list version is invalid.
X'00000008'	X'00000288'	List version is invalid.
X'0000000C'	X'00000300'	Request succeeded for at least one, but not all, list entries. See `compcode` for individual errors.
X'0000000C'	X'00000304'	Request failed for all list entries. See `compcode` for individual errors.
X'00000010'	X'00000400'	A CQSRSYNC is required for this structure.
X'00000010'	X'00000430'	No CQS address space.
X'00000014'	X'00000500'	CQS internal error.