CQSPUT request

Usage of CQSPUT

A CQSPUT request allows a client to place a data object on a queue. The data object can be either the only one for a unit of work, or it can be one in a series for a unit of work. The data object can be added to the beginning or to the end of the queue. After the data object is on the queue, it is available to any client that has access to that queue.

You can put multiple objects on the same queue for unit of work. Do not move these objects (CQSMOVE request) or allow these objects to be moved to the overflow structure (CQSCONN request); otherwise, CQS cannot recover the objects.

If a unit of work consists of multiple data objects, and they are all on the same queue, then when CQS places the first data object on the queue, it notifies other clients that have registered interest in the queue, even though not all of the data objects for the UOW are on the queue yet and the UOW has not yet been committed.

The first request that places a data object on a queue for a unit of work determines whether that unit of work is recoverable or nonrecoverable. The actions taken for a data object when a client fails, CQS fails, a structure is copied, or a structure is recovered depend on whether the unit of work is recoverable and, if so, whether it has been committed. The following table shows the actions taken for each case.

When a data object is put on a queue, a time stamp is stored with the data object. The source of the time stamp is based on whether TIMESTAMP= is used on the CQSPUT= request. If TIMESTAMP= is specified on the CQSPUT request, the value specified for TIMESTAMP= is stored with the data object. If TIMESTAMP= is not specified on the CQSPUT request, a time stamp representing the current time is generated and stored with the data object. The time stamp is returned on the CQSQUERY FUNC=QTYPE request if it is associated with the oldest data object on the queue or the newest data object on the queue.

A CQSPUT FUNC=FORGET request terminates any CQSPUT FUNC=PUT requests, and causes CQS to discard internal information CQS has about the unit of work. The unit of work is identified by the put token. The client should make this request after receiving a response from the final CQSPUT FUNC=PUT request issued for the unit of work. The CQSPUT FUNC=FORGET request is rejected if the unit of work is recoverable but not committed.

A CQSPUT FUNC=ABORT request removes from the queues all uncommitted data objects associated with a recoverable unit of work. The unit of work is identified by the put token. The request is rejected if the unit of work is nonrecoverable or if the unit of work is recoverable, but already committed.

Examples:  To put a single object for a unit of work on the queues, issue the following requests:

CQSPUT FUNC=PUT,COMMIT=YES,...
⋮
CQSPUT FUNC=FORGET,...

To put multiple objects for a unit of work on the queues, issue the following requests:

CQSPUT FUNC=PUT,COMMIT=NO,...
⋮
CQSPUT FUNC=PUT,COMMIT=NO,...
⋮
CQSPUT FUNC=PUT,COMMIT=YES,...
⋮
CQSPUT FUNC=FORGET,...

Parameter description:

COMMIT=YES | NO

Input parameter that indicates whether to commit a recoverable unit of work. One or more data objects can be placed on the queues for a recoverable unit of work.

The COMMIT= parameter applies only to recoverable units of work and is only valid if RECOVERABLE=YES is specified. The parameter is ignored if RECOVERABLE=NO is specified.

COMMIT=YES must be specified (either by itself or as part of OPTWORD1) for the final (or only) CQSPUT FUNC=PUT request issued for a unit of work. If more than one data object is placed on the queues for a unit of work, COMMIT=NO must be specified on all except the final CQSPUT FUNC=PUT request of the series. COMMIT=YES must be specified on the final CQSPUT FUNC=PUT request.

The COMMIT parameter cannot be used if the OPTWORD1 parameter is specified. If the OPTWORD1 parameter is used instead of COMMIT, you can use the following equate (EQU) statements to generate the value for the OPTWORD1 parameter:

CQSPUT_CMTYEQUX  COMMIT=YES
CQSPUT_CMTNEQUX   COMMIT=NO

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.

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.

DATAOBJ=dataobjectaddress

A 4-byte input parameter that specifies the address of the client data object to be placed on the specified queue.

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=PUT; it is invalid for other CQSPUT functions. FEEDBACK= is required when FEEDBACKLEN= is specified.

The utilization data returned is guaranteed only to be current for the structures to which the data object passed on the DATAOBJ= parameter was actually written. Data for the 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 CQSPUT request receives a nonzero return code, the feedback area data might not be returned, depending on how far CQSPUT processing progressed before the failure. For a nonzero CQSPUT 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=PUT; it is invalid for other CQSPUT functions. FEEDBACKLEN= is required when the FEEDBACK= parameter is specified.

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

SFBA_LN, the EQU symbol for the feedback area total area length, 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.

LOCAL=NO | N | YES | Y

Input parameter that indicates whether the client should keep a local copy of the data.

NO

Indicates the client wants CQS to place the data object on the specified client queue and make the object available to other CQSs.

YES

Indicates that the client wants CQS to place the data object on the shared queues and to lock the object. LOCAL=YES also indicates that the client will keep a local copy of the data object in a local buffer.

By keeping a local copy of the data object, the client can reduce the performance impact of using shared queues. By keeping the data object on the shared queues, it can be recovered if the client fails. By locking the data object, it is not available to any other client.

The client must issue the CQSREAD LOCAL=YES request to process the data (retrieve the lock token for the data object and inform CQS that the client is processing the data). The data object is not returned to the client on a CQSREAD request because the client has the local copy. If the client does not issue the CQSREAD LOCAL=YES request and the connection between the client and CQS is lost, CQS unlocks the data object and makes it available to any client.

The LOCAL parameter cannot be used if the OPTWORD1 parameter is specified. If the OPTWORD1 parameter is used instead of LOCAL, you can use the following equate (EQU) statements to generate the value for the OPTWORD1 parameter:

CQSPUT_LCLYEQUX  LOCAL=YES
CQSPUT_LCLNEQUX   LOCAL=NO

OBJSIZE=dataobjectsizeaddress

Input parameter that specifies the address of a 4-byte area to hold the size of the client data object to be placed on the queue. The maximum size that can be specified is 61312 bytes (X'EF80').

OPTWORD1=optionwordvalue

A 4-byte input parameter that specifies the literals for this request. This parameter can be used instead of COMMIT, LOCAL, QPOS, and RECOVERABLE. Equate (EQU) statements for the literal values are listed under the descriptions of the COMMIT, LOCAL, QPOS, and RECOVERABLE parameters. Equate statements can be also generated by using the DSECT function. The OPTWORD1 parameter cannot be used if COMMIT, LOCAL, QPOS, or RECOVERABLE is specified.

Requirement: If you code the OPTWORD1 parameter, you must pass a value that is composed of one equate value for each literal value supported by this macro.

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

PUTTOKEN=puttokenaddress

A 4-byte input and output parameter that specifies the address of a 16-byte token to be used by CQS to relate a series of CQSPUT requests for a unit of work. The token must be zero for the initial CQSPUT request of a series. An updated token is returned by CQS for each CQSPUT request. The updated token must be returned to CQS on the next CQSPUT request for the unit of work. The puttoken must also be returned to CQS for any CQSPUT FUNC=FORGET or CQSPUT FUNC=ABORT requests.

QNAME=queuenameaddress

Input parameter that specifies the address of the 16-byte name of the queue on which the data object is to be placed. The first byte of the queue name cannot be zero because it is used to determine the queue type. If the value in the first byte is greater than the maximum number of queue types defined by CQS, it is folded into one of the existing queue types. If the last data object for a unit of work is being put on the structure, the data object must be put on a different queue than any of the previous data objects for that unit of work.

QPOS=LAST | FIRST

Input parameter that specifies the position on the queue at which to place the client data object.

FIRST

The data object is added to the beginning of the queue.

LAST

The data object is added to the end of the queue.

The QPOS parameter cannot be used if the OPTWORD1 parameter is specified. If the OPTWORD1 parameter is specified instead of QPOS, you can use the following equate (EQU) statements to generate the value for the OPTWORD1 parameter:

CQSPUT_QPOSFEQUX  QPOS=FIRST
CQSPUT_QPOSLEQUX   QPOS=LAST

RECOVERABLE=YES | NO

Input parameter that specifies whether the unit of work is recoverable by CQS. RECOVERABLE=NO indicates that the unit of work is nonrecoverable. Only one data object can be placed on the queues for a nonrecoverable unit of work. RECOVERABLE=YES indicates that the unit of work is recoverable. One or more data objects can be placed on the queues for a recoverable unit of work.

The RECOVERABLE=YES parameter must be specified for each CQSPUT FUNC=PUT request issued for the unit of work. The unit of work is not committed until the final (or only) data object for the series is placed on the queues (COMMIT=YES specified).

The RECOVERABLE parameter cannot be used if the OPTWORD1 parameter is specified. If the OPTWORD1 parameter is specified instead of RECOVERABLE, you can use the following equate (EQU) statements to generate the value for the OPTWORD1 parameter:

CQSPUT_RECVYEQUX  RECOVERABLE=YES
CQSPUT_RECVNEQUX   RECOVERABLE=NO

RETCODE=returncodeaddress

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

TIMESTAMP=timestampaddress

A 4-byte input parameter that specifies the address of an 8-byte STCK value that is stored with the data object as the time the data object was placed on the queue. If the TIMESTAMP parameter is omitted, the current time is stored with the data object.

UOW=uowaddress

Input parameter that specifies the address of a 32-byte area to hold the unit of work. This parameter is required for the initial (or only) CQSPUT FUNC=PUT request issued for a unit of work. It is ignored for all subsequent CQSPUT FUNC=PUT requests issued for that unit of work.

When a value is specified for the UOW= parameter, PUTTOKEN=0 must also be specified. The value specified for the UOW= parameter cannot be all zeroes, and must be unique within the shared queues. The client is responsible for ensuring that the value is unique.

Return and reason codes for CQSPUT

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