CQSMOVE request
A CQSMOVE request moves one or all client data objects from one queue to another. Data objects can be moved from the first or last position of the old queue to the first or last position on the new queue.
Format for CQSMOVE
DSECT function of CQSMOVE
You use the DSECT function of a CQSMOVE request to include equate (EQU) statements in your program for the CQSMOVE parameter list length, CQSMOVE return and reason codes, and literals that can be used to build the OPTWORD1 parameter.
MOVE function of CQSMOVE
Use the MOVE function of a CQSMOVE request to move one or all data objects from one queue to another. You must code a macro invocation for each combination of literal parameters.
MOVE Function of CQSMOVE using Literal Parameters
You can use the OPTWORD1 parameter to code a single invocation of the macro and set the options at runtime. However, you cannot use the COUNT, NEWQPOS, and OLDQPOS parameters if you use the OPTWORD1 parameter.
MOVE Function of CQSMOVE using OPTWORD1 Parameter
Usage of CQSMOVE
A CQSMOVE request moves one or all client data objects from one queue to another. Data objects can be moved from the first or last position of the old queue to the first or last position on the new queue. The client identifies the data objects to be moved either by the old queue name and queue position, or by the lock token. Do not move multiple objects with the same queue name and UOW; otherwise CQS cannot recover the objects.
If CQS or the client fails before CQS responds to the client, the CQSMOVE request might not complete. The client must reconnect to CQS after the failure and may have to issue the CQSMOVE request again, in case the failure occurred before the move was committed, or to resume a move with COUNT=ALL.
- 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=ONE | ALL
- Input parameter that specifies the number of data objects on the
old queue to be moved; the client can move either one or all of them.
The COUNT parameter cannot be used when the OPTWORD1 parameter is specified. If you specify the OPTWORD1 parameter instead of the COUNT parameter, you can use the following equate (EQU) symbols to generate the value for the OPTWORD1 parameter:
CQSMOVE_CNT1EQUX COUNT=ONE CQSMOVE_CNT1EQUX COUNT=ALL - 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.
- LCKTOKEN=locktokenaddress
- Input parameter that specifies the address of the 16-byte lock token for the locked data object to be moved. The lock token uniquely identifies a data object locked by a CQSREAD request.
- MVCNT=movecountaddress
- Output parameter that specifies the address of a 4-byte field to receive the number of data objects that were moved. Even when the return or reason code is non-zero, it is possible that CQS moved some data objects.
- NEWQ=newqueuenameaddress
- Input parameter that specifies the address of the 16-byte name of the new queue to which the data object is to be moved.
- NEWQPOS=FIRST | LAST
- Input parameter that specifies the position on the new queue to
which data objects are moved, either first or last.
The NEWQPOS parameter cannot be used when the OPTWORD1 parameter is specified. If the OPTWORD1 parameter is specified instead of NEWQPOS, you can use the following equate (EQU) statements to generate the value for the OPTWORD1 parameter:
CQSMOVE_NEWQFEQUX NEWQPOS=FIRST CQSMOVE_NEWQLEQUX NEWQPOS=LAST - OLDQ=oldqueuenameaddress
- Input parameter that specifies the address of the 16-byte name of the old queue from which the data object is to be moved.
- OLDQPOS=FIRST | LAST
- Input parameter that specifies the position on the old queue from
which data objects are to be moved, either first or last. The OLDQPOS parameter cannot be used when the OPTWORD1 parameter is specified. If the OPTWORD1 parameter is specified instead of OLDQPOS, you can use the following equate (EQU) statements to generate the value for the OPTWORD1 parameter:
CQSMOVE_OLDQFEQUX OLDQPOS=FIRST CQSMOVE_OLDQLEQUX OLDQPOS=LAST - OPTWORD1=optionwordvalue
- Four-byte input parameter that specifies the literals for this
request. This parameter can be used instead of COUNT, NEWQPOS, and
OLDQPOS. Equate (EQU) statements for the literal values are listed
under the COUNT, NEWQPOS, and OLDQPOS parameter descriptions. Equate
statements can also be generated by using the DSECT function. The
OPTWORD1 parameter cannot be used if COUNT, NEWQPOS, or OLDQPOS 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
- 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
EQUvalue CQSMOVE_PARM_LEN (defined using the FUNC=DSECT request). - RETCODE=returncodeaddress
- Output parameter that specifies the address of a 4-byte field
to contain the CQSMOVE 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 CQSMOVE reason code.
Return and reason codes for CQSMOVE
The following table lists the return and reason code combinations that can be returned for CQSMOVE requests. Use a CQSMOVE FUNC=DSECT request to include equate statements in your program for the return and reason codes.
| Return code | Reason code | Meaning |
|---|---|---|
| X'00000000' | X'00000000' | Request completed successfully. |
| X'00000004' | X'00000128' | No data object to move for queue name specified. |
| X'00000008' | X'00000210' | cqstoken is invalid. |
| X'00000008' | X'00000214' | connecttoken is invalid. |
| X'00000008' | X'00000218' | FUNC is invalid. |
| X'00000008' | X'0000021C' | locktoken is invalid. |
| X'00000008' | X'00000220' | Queue name is invalid. |
| X'00000008' | X'00000224' | Buffer address is invalid. |
| X'00000008' | X'0000027C' | CQSMOVE is not allowed for a resource structure. |
| X'00000008' | X'00000284' | Parmlist version is invalid. |
| X'00000010' | X'00000400' | A CQSRSYNC is required for this structure. |
| X'00000010' | X'00000404' | Structure is inaccessible. Retry request later. |
| X'00000010' | X'00000414' | Unable to move the data object because the destination queue is full. CQSMOVE requests for other queues are allowed. |
| X'00000010' | X'0000041C' | Request pending. A structure recovery or CQS restart might be required to complete. |
| X'00000010' | X'00000430' | No CQS address space. |
| X'00000010' | X'00000440' | Locked (nonrecoverable) data object lost due to rebuild. |
| X'00000014' | X'00000500' | CQS internal error. |
| X'00000014' | X'00000504' | z/OS logger write error, data objects were not moved. |