YKDEFGRP (generates a copy group definition file)

This command creates, updates, and backs up the copy group definition file.

This command sets or changes the copy group attributes in the copy group definition file according to the values set for each parameter.

Request body format

{ "action":"submit",
   "cliname":"YKDEFGRP",
   "CLIPARMS":[
     "GROUP△1copy-group-ID"
     [,"PREFIX△11configuration-file-dataset-prefix"]
     [,"DAD△1DADID-of-the-host-on-which-BC-Manager-is-running"]
     [,"BACKUPGROUP△1copy-group-ID-of-the-copy-destination"] 
     [,"LOADGROUP△1{YES|NO}"]
     [,"DESCRIPTION△1description-of-the-copy-group"]
     ,"COPYTYPE△1{SI|TC|UR}"
     ,"PRIDAD△1primary-DADID"
     ,"SECDAD△1secondary-DADID"
     [",PRISCHSET△1primary-subchannel-set-ID"]
     [,"SECSCHSET△1secondary-subchannel-set-ID"]

     [,"COPYPACE△1{SLOW|NORMAL|FAST}"]             ---- for the SI copy type
     [,"PRESETMODE△1{NORMAL|STEADY|QUICK}"]        ---- for the SI copy type
     [,"PROTECTMODE△1{PROTECT|PERMIT}"]            ---- for the SI copy type

     [,"COPYPACE△1{SLOW|NORMAL}"]                  ---- for the TC copy type
     [,"DIFFUNIT△1{CYL|TRK}"]                      ---- for the TC copy type
     [,"FENCELEVEL△1{DATA|STATUS|NEVER}"]          ---- for the TC copy type
     [,"FREEZESCPMODE△1{Y|N}"]                     ---- for the TC copy type
     [,"LINKAGEOPTION△1{HS|NONE}"]                 ---- for the TC copy type
     [,"OPENMF△1{Y|N}"]                            ---- for the TC copy type
     [,"PROTECTMODE△1{PROTECT|PERMIT}"]            ---- for the TC copy type
     [,"TIMESTAMPMODE△1{Y|N}"]                     ---- for the TC copy type

     [,"CTTIMEMODE△1{JOURNAL|VOLUME|ASIS}"]        ---- for the UR copy type
     [,"ERRORLEVEL△1{VOLUME|GROUP}"]               ---- for the UR copy type
     [,"MIRRORID△1mirror-ID"]                      ---- for the UR copy type
     [,"PROTECTMODE△1{PROTECT|PERMIT}"]            ---- for the UR copy type
     [,"SUSPENDOPTION△1{FLUSH|PURGE}"]             ---- for the UR copy type
}

Parameters specified in the request body (common to all copy types)

GROUP copy-group-ID ~ <GROUP string>

Specify the copy group ID to be generated or updated.

Maximum length that can be specified = 44 - (5 + PREFIX length)

PREFIX configuration-file-dataset-prefix

This is a common parameter included in the default parameter dataset. For details, see Creating a default parameter dataset.

DAD DADID-of-the-host-on-which-BC-Manager-is-running

This is a common parameter included in the default parameter dataset. For details, see Creating a default parameter dataset.

BACKUPGROUP copy-group-ID-of-the-copy-destination ~ <GROUP string>

Specify the copy group ID of the destination to which the copy group is replicated.

Maximum length that can be specified = 44 - (5 + PREFIX length)

If this parameter is specified, the command will make a copy before updating the copy group definition file.

This parameter is valid only when the file specified in the GROUP parameter exists and the value specified in the GROUP parameter is different from the value specified in the BACKUPGROUP parameter.

If this parameter is omitted, no copy will be made.

LOADGROUP NO{YES|}

Specify whether to load the copy group definition file specified in the GROUP parameter if the file exists. The default value is YES.

YES

Loads the copy group definition file specified in the GROUP parameter if the file exists.

If the file is loaded, of the copy group attribute information parameters, only those that are specified will be updated. (Even parameters that are normally required can be omitted.)

NO

Does not load the copy group definition file specified in the GROUP parameter even if the file exists.

A new file will be created.

DESCRIPTION description-of-the-copy-group ~ <string of 32 or fewer characters>

Specify a description of the copy group. If this parameter is omitted and no copy group definition file is loaded, a null string is assumed.

COPYTYPE {SI|TC|UR}

Specify the copy type of the copy group.

You cannot change COPYTYPE. If you want to change COPYTYPE, create a new copy group definition by specifying NO in the LOADGROUP parameter.

SI

ShadowImage (SI)

TC

TrueCopy (TC)

UR

Universal Replicator (UR)

PRIDAD primary-DADID ~ <DAD string>

Specify the primary device address domain ID.

SECDAD secondary-DADID ~ <DAD string>

Specify the secondary device address domain ID.

When the value of the COPYTYPE parameter is SI, specify the value that is specified in the PRIDAD parameter. Note that, when defining a Non Gen'ed volume and a Gen'ed volume on the same storage system as a ShadowImage (SI) copy pair, you can specify a different value (the device address domain ID specified when performing an NG scan or the one specified when performing a local scan).

PRISCHSET primary-subchannel-set-ID ~ <one-digit hexadecimal number>

Specify the primary subchannel set ID. For multiple subchannel set IDs, specify a value in the range from 1 to 3. For dummy subchannel set IDs, specify a value in the range from 1 to F. If this parameter is omitted and no copy group definition file is loaded, 0 is assumed.

SECSCHSET secondary-subchannel-set-ID ~ <one-digit hexadecimal number>

Specify the secondary subchannel set ID. The specification is the same as the PRISCHSET parameter.

Parameters specified in the request body (for the SI copy type)

COPYPACE {SLOW|NORMAL|FAST}

Specify the copy pace when a copy pair is created (YKMAKE command) or resynchronized (YKRESYNC command). If this parameter is omitted and no copy group definition file is loaded, NORMAL is assumed.

SLOW

The speed of the copy operation will be slower so as to minimize the impact of the copy operation on the I/O performance of the host.

NORMAL

The speed of the copy operation will be faster. However, if update I/O load on the P-VOL is high, this might affect the I/O performance of the host.

FAST

The speed of the copy operation will be even faster than when the NORMAL parameter is specified. However, because this might affect business operations, we recommend that you perform copy pair operations outside of business hours.

PRESETMODE {NORMAL|UR|STEADY|QUICK}

Specify the type of the ATTIME suspend function and the suspend mode for the ATTIME suspend operation that you want to use when setting an ATTIME suspend time. If this parameter is omitted and no copy group definition file is loaded, NORMAL is assumed.

NORMAL

Uses the NORMAL ATTIME suspend function or the TC ATTIME suspend function.

UR

Uses the UR ATTIME suspend function.

STEADY

Uses the UR ATTIME suspend function. Suspension is performed in STEADY mode.

QUICK

Uses the UR ATTIME suspend function. Suspension is performed in QUICK mode.

PROTECTMODE {PROTECT|PERMIT}

Specify whether to allow writing to the S-VOL. If this parameter is omitted and no copy group definition file is loaded, PERMIT is assumed.

PROTECT

Update of the S-VOL is prohibited after the copy pair is suspended (the YKSUSPND command is executed).

PERMIT

Update of the S-VOL is permitted after the copy pair is suspended (the YKSUSPND command is executed).

Parameters specified in the request body (for the TC copy type)

COPYPACE {SLOW|NORMAL}

Specify the copy pace when a copy pair is created (YKMAKE command) or resynchronized (YKRESYNC command). If this parameter is omitted and no copy group definition file is loaded, PERMIT is assumed.

SLOW

The speed of the copy operation will be slower so as to minimize the impact of the copy operation on the I/O performance of the host.

NORMAL

The speed of the copy operation will be faster. However, if update I/O load on the P-VOL is high, this might affect the I/O performance of the host.

DIFFUNIT {CYL|TRK}

Specify the unit for managing the differential data between the P-VOL and S-VOL (differential-data management unit). If this parameter is omitted and no copy group definition file is loaded, TRK is assumed.

CYL

Differential data is managed in units of cylinders.

TRK

Differential data is managed in units of tracks.

Notes

• If TRK is specified, there is an upper limit to the number of copy pairs that can be created on each storage system. For details, see the TrueCopy for Mainframe User Guide.

• For VSP G1000, VSP G1500, VSP F1500, and VSP 5000 series storage systems, TRK is used even if CYL is specified.

FENCELEVEL {DATA|STATUS|NEVER}

Specify the fence level. If this parameter is omitted and no copy group definition file is loaded, NEVER is assumed.

DATA

Places the P-VOL in the fence status (updates suppressed) when updates to the P-VOL cannot be copied to the S-VOL due to a problem such as a failure.

STATUS

Places the P-VOL in the fence status (updates suppressed) when updates to the P-VOL cannot be copied to the S-VOL due to a problem such as a failure. If a P-VOL is placed in a suspended state by an operation from the primary site, updates to the P-VOL will be accepted.

NEVER

P-VOLs are never placed in the fence status (updates suppressed). Even when a copy pair is suspended, updates to a P-VOL are accepted.

Note 1

The FENCELEVEL parameter cannot be altered when a consistency group ID is specified.

Note 2

For a system volume that is used for control by the OS or by applications such as Business Continuity Manager, if you specify DATA or STATUS for the FENCELEVEL parameter to create and operate a copy pair, writing to the P-VOL is prohibited and the OS or application might hang when a problem such as a failure occurs. For this reason, if you use the system volume as a TrueCopy copy pair, specify NEVER for the FENCELEVEL parameter, or set and operate the system volume itself so that it does not become a TrueCopy copy pair.

FREEZESCPMODE {Y|N}

Specify whether to freeze a storage system (place it in the SCP status) when a failure suspension (SUSPER) occurs. If this parameter is omitted and no copy group definition file is loaded, Y is assumed.

Y

Places the storage system in the SCP status. When a copy group for which Y is specified for this parameter changes to a failure suspension status, execute the YKRUN command to cancel the SCP status. If you do not cancel the SCP status, update I/O operations from the host will be put on hold for a long period of time. Note that you cannot use the SCP Delay Time that was set by using Storage Navigator to change the time for putting update I/O operations on hold. The specification of Y is valid only for TrueCopy copy groups for which consistency group IDs are specified.

N

Does not place the storage system in the SCP status.

LINKAGEOPTION {HS|NONE}

Specify the linkage option. If this parameter is omitted and no copy group definition file is loaded, NONE is assumed.

HS

TrueCopy copy groups with the HyperSwap attribute

NONE

Copy groups other than the above

Notes

• Although you can change the definitions in Business Continuity Manager by specifying HS or NONE for the LINKAGEOPTION parameter, the changes will not be applied to the host or storage system. If the definitions are changed on the host or storage system, make sure that you change the definitions in Business Continuity Manager so that they match the definitions on the host and storage system.

• For PPRC copy pairs in a 2DC configuration with HyperSwap and Universal Replicator, specify HS. For a TrueCopy copy group created by executing the YKH2B command, HS is displayed. If HS is displayed, Business Continuity Manager can be used only for monitoring, and the operations it can perform are limited. However, Business Continuity Manager can be used to dissolve copy pairs (by executing the YKRECVER or YKDELETE command).

OPENMF {Y|N}

Specify whether to use the Open/MF Consistency Preservation function. If this parameter is omitted and no copy group definition file is loaded, N is assumed.

Y

Uses the Open/MF Consistency Preservation function (Open/MF Consistency attribute setting).

N

Does not use the Open/MF Consistency Preservation function.

PROTECTMODE {PROTECT|PERMIT}

Specify whether to allow writing to the S-VOL. If this parameter is omitted and no copy group definition file is loaded, PROTECT is assumed.

PROTECT

Update of the S-VOL is prohibited after the copy pair is suspended (the YKSUSPND command is executed).

PERMIT

Update of the S-VOL is permitted after the copy pair is suspended (the YKSUSPND command is executed).

TIMESTAMPMODE {Y|N}

Specify whether to transfer the writing timestamp to the S-VOL (timestamp transfer mode). If this parameter is omitted and no copy group definition file is loaded, N is assumed.

Y

Transfers the timestamp to the S-VOL. Specify this item only when you are using the TC ATTIME Suspend function, or when you are using the UR ATTIME Suspend function in a 4x4x4 Cascade configuration or a 3DC Cascade configuration.

N

Does not transfer the timestamp to the S-VOL.

Parameters specified in the request body (for the UR copy type)

CTTIMEMODE {JOURNAL|VOLUME|ASIS}

Specify the consistency time mode to be used when the copy type is Universal Replicator. If this parameter is omitted and no copy group definition file is loaded, ASIS is assumed.

JOURNAL

Uses the consistency time that was applied to the restore journal.

VOLUME

Uses the consistency time that was applied to the S-VOL.

ASIS

Behaves in the same way as when VOLUME is specified.

ERRORLEVEL {VOLUME|GROUP}

Specify the error level that determines whether all of the copy pairs in the same consistency group are suspended. If this parameter is omitted and no copy group definition file is loaded, GROUP is assumed.

VOLUME

When a failure occurs, only the affected volumes are suspended.

GROUP

When a failure occurs, all volumes in the same copy group are suspended.

MIRRORID mirror ID ~ <number> (0 to 3)

Specify the mirror ID by using a number in the range from 0 to 3. If this parameter is omitted and no copy group definition file is loaded, 1 is assumed.

Notes

• Do not specify 0 for MIRRORID if you are using a Universal Replicator copy group or a TrueCopy copy group in a 3DC Cascade configuration or 3DC Multi-Target configuration. Note that, in a 3DC Multi-Target configuration or a 2DC configuration where both HyperSwap and Universal Replicator are used, the mirror ID cannot be the same as any other mirror ID assigned to another Universal Replicator copy group.

• When you execute the YKMAKE command, if one or more volumes are not in the SIMPLEX status, the command might not execute correctly.

PROTECTMODE {PROTECT|PERMIT}

Specify whether to allow writing to the S-VOL. If this parameter is omitted and no copy group definition file is loaded, PROTECT is assumed.

PROTECT

Update of the S-VOL is prohibited after the copy pair is suspended (the YKSUSPND command is executed).

PERMIT

Update of the S-VOL is permitted after the copy pair is suspended (the YKSUSPND command is executed).

SUSPENDOPTION {FLUSH|PURGE}

Specify the data synchronization method used at suspension when the copy type is Universal Replicator. If this parameter is omitted and no copy group definition file is loaded, FLUSH is assumed.

FLUSH

Suspends the copy pair after all data is synchronized. Because 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 the main control unit and remote control unit as differential data, and becomes a differential copy target when the copy pair is resynchronized.

PURGE

Suspends the copy pair at the time the suspend request is issued, even if unsynchronized data remains. Unsynchronized data is managed by the main control unit and remote control unit as differential data, and becomes a differential copy target when the copy pair is resynchronized.

Responses

See Responses common to all CLI commands.

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 when the YKDEFGRP command ends.

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