YKEWAIT (waits for a copy group to reach a specified status)

Applies to ShadowImage, TrueCopy, TrueCopy with the HyperSwap attribute, and Universal Replicator.

Monitors the volume status transition of copy pairs for the specified copy group and waits for a certain specified status.

Request body format

{ "action":"submit",
   "cliname":"YKEWAIT",
   "operands":"
     [GROUP(copy-group-ID)]
     △1GOTO({DUPLEX|SUSPEND|SIMPLEX|SUSPVS|HOLD|SWAPPING|SWAP2SUS})
     △1TIMEOUT(timeout-value)
     [△1NOINVALIDCHECK] 
     [△1DEVN(p-vol-device-number, s-vol-device-number)]
     [△1TO({PRIMARY|SECONDARY})]
     [△1VOLUNIT] 
     [△1UNTIL(number-of-copy-pairs-in-transition) ]
   "
}

Parameters specified in the request body

GROUP(copy-group-ID) ~ <GROUP string>

Specify the ID of the target copy groups that are loaded. If only one copy group is loaded, you can omit this parameter.

GOTO({DUPLEX|SUSPEND|SIMPLEX|SUSPVS|HOLD|SWAPPING|SWAP2SUS})

Specify the status of the copy group to be monitored. When all the copy pairs in the group change to the specified status, the YKEWAIT command terminates successfully.

DUPLEX

The command waits until all the copy pairs in the group reach the DUPLEX status. However, if the status of any copy pair changes to the SIMPLEX, SUSPCU, SUSPER, TRANS, SUSPVS, HOLDER, NODELTA, CONSLOST, or INVALID status, the YKEWAIT command terminates abnormally with return code 8.

When the command waits for copy pairs in the copy group container with EXCTG ID to reach the DUPLEX status, it first waits for all journal groups in the copy group container with EXCTG ID to be registered in EXCTG. If an error is detected during EXCTG registration, the YKZ297E message is output and the command terminates abnormally with return code 44.

SUSPEND

The command waits until all the copy pairs in the group reach the SUSPOP or SWAPPING status. However, if the status of any copy pair changes to the SIMPLEX, SUSPER, SUSPCU, HOLD, HOLDER, HOLDTRNS, NODELTA, CONSLOST, or INVALID status, the YKEWAIT command terminates abnormally with return code 8.

SIMPLEX

The command waits until all the copy pairs in the group reach the SIMPLEX status. However, if the status of any copy pair changes to the SUSPER, SUSPCU, HOLDER, CONSLOST, or INVALID status, the YKEWAIT command terminates abnormally with return code 8.

SUSPVS

The command waits until all copy pairs in the group reach the SUSPOP or SUSPVS status. However, if the status of any copy pair changes to the SUSPER, SIMPLEX, SUSPCU, HOLD, HOLDER, HOLDTRNS, NODELTA, CONSLOST, or INVALID status, the YKEWAIT command terminates abnormally with return code 8.

HOLD

Applies to Universal Replicator.

The command waits for all copy pairs in the group to reach the HOLD status. However, if any copy pair takes the SIMPLEX, SUSPER, SUSPCU, HOLDER, NODELTA, or INVALID status, the YKEWAIT command terminates abnormally with return code 8. In rare cases, delta resync pairs might stay in HOLDTRNS status. If this occurs, the YKEWAIT command does not terminate until the time specified by TIMEOUT parameter elapses.

In the Copy Group Status Summary panel, the number of copy pairs in the HOLD status is included in the displayed number of pairs in the SUSPOP status. In the Copy Group Storage System Summary panel, the number of pairs in the HOLD status is included in the displayed number of pairs in the SUSPOP status.

SWAPPING

Applies to TrueCopy, TrueCopy with the HyperSwap attribute, and Universal Replicator.

The command waits until all copy pairs in the group reach the SWAPPING status. However, if the status of any copy pair changes to the SIMPLEX, HOLD, HOLDER, HOLDTRNS, NODELTA, CONSLOST, or INVALID status, the YKEWAIT command terminates abnormally with return code 8.

SWAP2SUS

Applies to TrueCopy, and Universal Replicator.

The command waits until all copy pairs in the group reach the SUSPOP, SUSPER, or SUSPCU status. However, if the status of any copy pair changes to the SIMPLEX, HOLD, HOLDER, HOLDTRNS, NODELTA, CONSLOST, or INVALID status, the YKEWAIT command terminates abnormally with return code 8.

Specify a timeout value in minutes. If the specified duration has elapsed before the status specified by the GOTO parameter is attained, the YKEWAIT command checks the status of the copy group at that moment. If the status is the same as the one specified in the GOTO parameter, the command terminates normally (return code = 0). If not, it terminates abnormally with the return code 4.

If 0 is specified in TIMEOUT parameter, it looks at the status of the copy group immediately, and then returns as described as above.

For copy group containers with EXCTG IDs, if this time value elapses before all journal groups are registered in EXCTG, the YKZ298W message is output and the YKEWAIT command terminates abnormally with return code 4. If the YKZ298W message is output, the REXX variable is disabled (the same state as before the YKEWAIT command was executed).

Processing continues even when the status changes to anything other than the status specified by the GOTO parameter (invalid statuses). If this parameter is specified, and the status does not change to that specified in the GOTO parameter, the command processing will continue until the timeout time specified in the TIMEOUT parameter is reached.

The invalid statuses below differ depending on the value specified in the GOTO parameter. The following table shows an invalid status for each value specifiable in the GOTO parameter.

When the command waits for copy pairs in the copy group container with EXCTG ID to reach DUPLEX status, it first waits for all journal groups in the copy group container with EXCTG ID to be registered in EXCTG. If an error is detected during EXCTG registration, the YKZ297E message is output and the command terminates abnormally with return code 44.

When the command monitors the status of a copy pair in a ShadowImage copy group to which the UR ATTIME suspend time has been set, the check operation differs depending on whether the NOINVALIDCHECK parameter is specified:

• If the NOINVALIDCHECK parameter is not specified

  The status of the Universal Replicator copy pair at the time of ShadowImage copy pair suspension will be checked. If an error is detected, the YKZ407E message, YKZ408E message, or YKZ409E message is output and the command terminates abnormally with return code 24.

• If the NOINVALIDCHECK parameter is specified

  The status of the Universal Replicator copy pair at the time of ShadowImage copy pair suspension will not be checked.

Specify the device number of the copy pair (P-VOL and S-VOL) to operate.

Note that, for copy group containers with EXCTG IDs, the command checks the EXCTG registration information for all copy group containers.

After specifying the copy pair to operate, to view REXX variables (such as SimplexCt) shown in information for copy pairs that are not operation targets, execute the YKQUERY command or YKEWAIT command for all copy pairs.

TO({PRIMARY|SECONDARY})

Applies to TrueCopy, TrueCopy with the HyperSwap attribute, and Universal Replicator.

Specify this parameter to monitor copy groups by monitoring the status of either P-VOLs or S-VOLs.

When the TO parameter is specified, the copy group container is not checked for EXCTG registration information.

PRIMARY

Monitors the status of P-VOL during copy group definition.

SECONDARY

Monitors the status of S-VOL during copy group definition.

Usually, information is obtained for each control unit, but when this parameter is specified, information is obtained for each volume.

Specify the number of copy pairs that are undergoing transition to the specified status. If the number of copy pairs that are in transition becomes equal to or lower than the value specified for this parameter during monitoring of copy pair status transition, the monitoring of status transitions finishes. If the NOINVALIDCHECK parameter is specified, the invalid statuses indicated in the preceding table "Invalid status for each value specifiable in the GOTO parameter" are considered as copy pairs that are in transition.

Responses

See Responses returned by YKEWAIT.

Return code

If the CLI command has finished running, the return code of the CLI command is set in the rc key of the response. If an error occurs before the CLI command is run, the BCM Web API server sets the return code.

The following table lists and describes the return codes of the YKEWAIT command.

#: If a time-out has taken place, use the YKQUERY command to check the status of the copy pair. If there is a copy pair where a transition has not taken place, the S-VOL of the copy pair might be ONLINE. Place it OFFLINE and re-execute the commands. In addition, for copy group containers with EXCTG IDs, check if the journal group has been registered in EXCTG.

For details about return codes set by the BCM Web API server, see Return codes set by the BCM Web API server.