YKSUSPND (suspends copy pairs)

Applies to ShadowImage, TrueCopy, and Universal Replicator.

This command suspends a copy pair for the specified copy group and changes the volume status to the SUSPOP status.

The following table describes the correspondence between functions, copy types, and parameter names.

Legend: Y: Can be specified; --: Cannot be specified

Request body format

{ "action":"submit",
   "cliname":"YKSUSPND",
   "operands":"
     [GROUP(copy-group-ID)]
     [△1DEVN(p-vol-device-number, s-vol-device-number)]
     △1{ATTIME(time-value)  [△1ATOPT({NORMAL|UR[({STEADY|QUICK})]})] [
          △1TIMEOUT(timeout-value)] [△1GENID(Generation-ID)]
       |CANCEL [({NORMAL|UR})] [△1DEVN(p-vol-device-number, s-vol-device-number)][△1VOLUNIT]
       |PURGE   [△1SVOL({PROTECT|PERMIT})] [△1DEVN(p-vol-device-number, s-vol-device-number)] [△1VOLUNIT]
       |FLUSH    [△1SVOL({PROTECT|PERMIT})] [△1DEVN(p-vol-device-number, s-vol-device-number)] [△1VOLUNIT]
       |QUICK    [△1SVOL({PROTECT|PERMIT})] [△1DEVN(p-vol-device-number, s-vol-device-number)][△1VOLUNIT]
       |FORWARD [△1SVOL({PROTECT|PERMIT})] [△1DEVN(p-vol-device-number, s-vol-device-number)][△1VOLUNIT]
       |REVERSE [△1SVOL({PROTECT|PERMIT})] [△1DEVN(p-vol-device-number, s-vol-device-number)][△1VOLUNIT]
       }
     [△1SELECT({ALL|COND})] 
   "
}

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.

DEVN(p-vol-device-number,s-vol-device-number) ~ <4-digit hexadecimal number, 4-digit hexadecimal number>

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

ATTIME(time-value)

Applies to ShadowImage.

If you use the ATTIME suspend function, specify the time at which suspend processing is performed.

This parameter is valid for copy groups specified by consistency group ID. If a storage system that does not support the TC ATTIME suspend time is included, and if you do not use the UR ATTIME Suspend function, this parameter cannot be specified for a remote storage system. You must use the UR ATTIME Suspend function for a copy group in which the P-VOLs are Non Gen'ed volumes. If you do not use the UR ATTIME Suspend function, an I/O error will occur.

For a copy group to which the NORMAL ATTIME suspend time or the TC ATTIME suspend time has been set, do not set the UR ATTIME suspend time. If you want to set the UR ATTIME suspend time for a copy group to which the NORMAL ATTIME suspend time or the TC ATTIME suspend time has been set, and if a storage system that does not support the TC ATTIME suspend time is included, cancel the setting of the NORMAL ATTIME suspend time or the TC ATTIME suspend time without using the Remote DKC Control function, and then set the UR ATTIME suspend time.

This setting is reset by P/S ON/OFF on the primary storage system.

The format of time-value is as follows:

YYYYMMDD:HHMMSS:mmmm:ss, {LOCAL|GMT}

YYYY ~ <numeric characters> ((1970-2042))

Specify the year.

MM ~ <numeric characters> ((01-12))

Specify the month.

DD ~ <numeric characters> ((01-31))

Specify the date.

HH ~ <numeric characters> ((00-23))

Specify the hour.

MM ~ <numeric characters> ((00-59))

Specify the minute.

SS ~ <numeric characters> ((00-59))

Specify the second.

mmmm ~ <numeric characters> ((0000-9999))

Specify an offset value from the time specified in YYYYMMDD:HHMMSS, in minutes.

ss ~ <numeric characters> ((00-99))

Specify an offset value from the time specified in YYYYMMDD:HHMMSS, in seconds.

LOCAL

This value means that the specified time is in local time.

GMT

This value means that the specified time is in GMT.

Applies to ShadowImage.

Specify the type of UR ATTIME Suspend function to be used. If you omit this parameter, the value specified in the ISPF panel when the ShadowImage copy pair was defined will be set.

NORMAL

The NORMAL ATTIME Suspend function or the TC ATTIME Suspend function is used.

UR

The UR ATTIME Suspend function is used.

A suspend mode (STEADY or QUICK) is set for the value specified on the ISPF panel during the ShadowImage copy pair definition.

STEADY

The suspend mode is set to STEADY.

The S-VOL can be referenced and updated after the data has been completely copied and the status has changed to SUSPOP.

QUICK

The suspend mode is set to QUICK.

The S-VOL can be referenced and updated even while data is being copied.

If you omit STEADY and QUICK, the value specified on the ISPF panel when the ShadowImage copy pair was defined is set.

Note that if the NORMAL ATTIME Suspend function is used, even if STEADY is specified, QUICK mode is set for storage systems that do not support the TC ATTIME Suspend function.

Applies to ShadowImage.

Specify the timeout value in minutes. If you use the UR ATTIME Suspend function, when the journal is acquired at the remote storage system, the copy pair is suspended when the time period specified in the TIMEOUT parameter elapses after the time that was specified in the ATTIME parameter. This suspension takes place even if the update journal is not acquired after the time specified in the ATTIME parameter, or even if no-update journal is detected. Note that if the Universal Replicator copy pair is in the suspend status at the ATTIME suspend time, the value specified in the TIMEOUT parameter will become invalid, and the ShadowImage copy pair will be suspended at the ATTIME suspend time.

If you specify 0 or omit this parameter, the timeout value determined by the storage system will be set.

Applies to ShadowImage.

Specify a generation ID. The default value (used when this parameter is omitted) is 00. Generation IDs can be used as a generation number used for identifying the generation of backups.

For example, generation IDs are useful when you need to maintain consistency between multiple storage systems. If you have specified different generation IDs for the volumes of individual storage systems each time you set the ATTIME suspend time, all storage systems can be recovered from the same volumes that have the same generation ID when the storage systems are recovered.

Applies to ShadowImage.

If this parameter is used, the ATTIME suspend time is canceled. This parameter is valid for copy groups specified by consistency group ID. If a storage system that does not support the TC ATTIME Suspend function is included and the P-VOL is a Non Gen'ed volume, an I/O error occurs.

CANCEL(NORMAL)

Specify this parameter to cancel the NORMAL ATTIME suspend time.

CANCEL(UR)

Specify this parameter to cancel the UR ATTIME suspend time.

Legend: --: Not applicable

#1: If the CANCEL parameter was specified, the return code is 0. If the CANCEL(NORMAL) parameter was specified, the return code is 48.

#2: The return code is 0.

#3: This is run if the CANCEL(UR) or CANCEL parameter was specified.

#4: This is run if the CANCEL(NORMAL) or CANCEL parameter was specified.

Applies to Universal Replicator.

When this is specified, the copy pair is suspended when a suspend request is issued, even if unsynchronized data remains. Unsynchronized data is managed by main control unit and remote control unit as differential data, and becomes a differential copy target when the copy pair is synchronized.

Applies to Universal Replicator.

Suspends the copy pair after all pending data is synchronized. Since the suspension is performed when data up until the time of the suspend request is synchronized, the system does not wait for updating to finish. Data updated after the suspend request is managed by main control unit and remote control unit as differential data, and becomes a differential copy target when the copy pair is synchronized.

Applies to ShadowImage.

Suspends in the QUICK mode.

The S-VOL can be read or written even when data is being copied. When this parameter is not specified, the S-VOL can be read or written after data copying, and transition to the SUSPOP status have finished. For details on what happens when the ATTIME parameter is specified for the NORMAL ATTIME Suspend function, see the ShadowImage for Mainframe User Guide. When the UR ATTIME Suspend function is used, the method of performing suspensions used depends on the specified ATOPT parameter.

Applies to TrueCopy and Universal Replicator.

When the copy direction is forward

Places copy pairs in the SUSPOP status, so that the copy direction goes from the primary site to the secondary site after resynchronization.

When a storage system is VSP G1000, VSP G1500, VSP F1500, or VSP 5000 series and the copy type is TrueCopy or Universal Replicator, if you specify this parameter to a copy pair whose status is SWAPPING, the SWAPPING status is canceled, and the status of the copy pair changes to SUSPOP. Note that, for the Universal Replicator copy type, if you specify this parameter for a copy pair whose status was changed from a suspend status (SUSPOP, SUSPCU, or SUSPER) to the SWAPPING status, the status of the copy pair returns to the previous suspend status.

If this parameter is specified for Universal Replicator, the data synchronization method during the suspension will be the same as that used when the FLUSH parameter is specified.

When the copy direction is reverse

Places copy pairs in the SUSPOP status, so that the copy direction goes from the primary site to the secondary site after SWAPPING. If this parameter is specified for Universal Replicator, the data synchronization method during the suspension will be the same as that used when the FLUSH parameter is specified.

Applies to TrueCopy and Universal Replicator.

When the copy direction is forward

Places copy pairs in the SWAPPING status, so that the copy direction goes from the secondary site to the primary site after resynchronization. If this parameter is specified for Universal Replicator, the data synchronization method during the suspension will be the same as that used when the FLUSH parameter is specified.

When the copy direction is reverse

Places copy pairs in the SUSPOP status, so that the copy direction goes from the secondary site to the primary site after resynchronization.

When a storage system is VSP G1000, VSP G1500, VSP F1500, or VSP 5000 series and the copy type is TrueCopy or Universal Replicator, if you specify this parameter to a copy pair whose status is SWAPPING, the SWAPPING status is canceled, and the status of the copy pair changes to SUSPOP. Note that, for the Universal Replicator copy type, if you specify this parameter for a copy pair whose status was changed from a suspend status (SUSPOP, SUSPCU, or SUSPER) to the SWAPPING status, the status of the copy pair returns to the previous suspend status.

If this parameter is specified for Universal Replicator, the data synchronization method during the suspension will be the same as that used when the FLUSH parameter is specified.

When neither the FORWARD parameter nor the REVERSE parameter are specified, the status of copy pairs become SUSPOP. The status of the copy pair is not changed to SWAPPING. In addition, the SWAPPING status is not canceled.

Specify whether writing to the S-VOL is permitted or protected after a volume is suspended (SUSPOP).

When this parameter is not specified, the value specified in the ISPF panel is assumed. For SI copy pairs, if the ATTIME parameter or CANCEL parameter are both specified, this specification is disregarded, and writing to an S-VOL in the suspend status will be permitted.

When changing the status of a copy pair to SWAPPING or to a suspend status by canceling the SWAPPING status, specification of this parameter will be ignored, and the settings will permit writing to an S-VOL.

PROTECT

This value means that writing to the S-VOL is protected after a volume is suspended (SUSPOP).

PERMIT

This value means that writing to the S-VOL is permitted after a volume is suspended (SUSPOP).

VOLUNIT

When this is specified, operation is performed by volume even when the environment supports operation by group.

Usually, to operate by volume only those copy pairs whose statuses do not match due to such reasons as failure, specify this along with the SELECT(COND) parameter.

Specify the selection method for the copy pair to be manipulated by the command. When not specified, ALL is assumed.

ALL

All the copy pairs in the copy group are to be manipulated by the command. Note that if the DEVN parameter is specified, the copy pair specified for the parameter becomes the execution target of the command.

COND

The pairs to be manipulated by the command depend on their volume status. If all copy pairs in the copy group are either affected by the command or in the target status, processing terminates with return code 0. If copy pairs that are not affected by the command are included in the copy group, processing terminates with return code 4. For more information about copy groups affected by the command and its target status, see the table "Copy pair statuses for which commands with SELECT(COND) specified are subject to processing" in the Hitachi Business Continuity Manager User Guide.

Notes

• If more than one of the ATTIME, CANCEL, PURGE, FLUSH, QUICK, FORWARD, and REVERSE parameters is specified, the last specified parameter takes effect.

• The YKSUSPND command terminates successfully when the instruction to the copy pair succeeds. Even if the YKSUSPND command has terminated with return code 0, the copy pair might not be in the SUSPOP or SWAPPING status. Therefore, after you have executed the YKSUSPND command, use the YKQUERY or YKEWAIT command to make sure that the copy pair status has changed to SUSPOP or SWAPPING. If there is a volume with a status that has not been changed, re-execute the YKSUSPND command with the VOLUNIT parameter specified for all copy pairs.

• If operations with a REVERSE specification such as planned outage take place, to control TrueCopy from the script, we recommend that you specify the FORWARD or REVERSE parameter.

• After executing the YKSUSPND command, make sure that the statuses for all copy pairs in the copy group are transitioning to SUSPOP or SWAPPING, before executing the YKRESYNC command. If the YKRESYNC command is executed without checking this first, the copy directions in the copy group might become mixed-up, or transition to the correct status might not occur.

• If the ATTIME suspend function is used, no copy pair can be added to the copy pair. Execute the YKSUSPND command with the CANCEL parameter specified or the YKRESYNC command to cancel the ATTIME suspend time and then add a copy pair.

• To change the status of a copy pair in the SWAPPING status to a suspend status, execute the YKQUERY or YKEWAIT command, and then execute the YKSUSPND command. If you do not execute the YKQUERY or YKEWAIT command, the YKSUSPND command will terminate with return code 32.

• In some cases, the ShadowImage copy pair will not change to suspend status. This occurs if the ShadowImage copy pair, specified by the ATTIME suspend time, changes its status to soft fence before the ATTIME suspend time arrives, after which the soft fence status is reset after the ATTIME suspend time arrives. Execute the YKSUSPND command with the CANCEL parameter specified to cancel the ATTIME suspend time, and operate the copy pair as necessary.

  If the soft fence status is reset before the ATTIME suspend time arrives, suspend is executed when the ATTIME suspend time arrives.

Responses

See Responses returned by YKDELETE, YKMAKE, YKRECVER, YKRESYNC, YKSUSPND, or YKRMTCDV.

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 YKSUSPND command.

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