YKGETGRP (gets copy group information)

Request body format

{ "action":"submit",
   "cliname":"YKGETGRP",
[  "offset":first-sequence-number-of-the-pairs-or-groups-to-be-output,]
[  "limit":number-of-pairs-or-groups-to-be-output,]
[  "fields":"category-to-be-output",]
   "operands":"[GROUP(copy-group-ID) ]
         [△1CTID (C/TID-or-M-JNLID)]
         [△1SUBCTID(R-JNLID)]
         [△1LOADGROUP(YES|NO|FORCE)
         [△1PREFIX(prefix)] [△1DAD(local-device-address-domain-ID)]  ]
         [△1{STATE(pair-status-of-the-pairs-to-be-output[,pair-status-of-the-pairs-to-be-output...])
             |XSTATE(pair-status-of-the-pairs-to-be-excluded[,pair-status-of-the-pairs-to-be-excluded...])  }]
         [△1MATCHING(minimum-matching-rate:maximum-matching-rate)  ]
         [△1CTDelta(minimum-number-of-seconds[:maximum-number-of-seconds])  ]
         [△1VOLSER(volume-serial-number|volume-serial-number-wildcard)  ]
         [△1priSN(storage-system-serial-number)  ]
         [△1priSSID(SSID)  ]
         [△1priCU(first-control-unit-number[:last-control-unit-number])  ]
         [△1priCCA(first-command-control-address-number[:last-command-control-address-number])  ]
         [△1priDEVN(first-device-number[:last-device-number])  ]
         [△1priHostStatus(ONLINE|OFFLINE)  ]
         [△1priFenceStatus(SOFT|SPID|BOTH|UNFENCE)  ]
         [△1secSN(storage-system-serial-number)  ]
         [△1secSSID(SSID)  ]
         [△1secCU(first-control-unit-number[:last-control-unit-number])  ]
         [△1secCCA(first-command-control-address-number[:last-command-control-address-number])  ]
         [△1secDEVN(first-device-number[:last-device-number])  ]
         [△1secHostStatus(ONLINE|OFFLINE)  ]
         [△1secFenceStatus(SOFT|SPID|BOTH|UNFENCE)  ]
         "
}

Parameters specified in the request body

If neither the offset key nor the operands key is specified, all copy pairs in all copy groups will be output.

offset key: first-sequence-number-of-the-pairs-or-groups-to-be-output ~ <numeric characters><<0>>

Specify the first sequence number of the copy pairs or copy groups to be output (first group = sequence number 0, first pair of the first group = sequence number 1).

Each copy pair and each copy group are counted once.

If you omit this parameter, output will start from the first copy pair of the first copy group.

Specify the sum of the number of copy pairs to be output and the number of copy groups to be output.

Specify one of the following categories as the category to be output.

• SUMMARY
• OPTION
• EXCTG
• GROUP
• PAIR

To specify multiple categories, separate them by using commas (,) as in "fields":"SUMMARY,OPTION".

If you omit the fields key, all of the following categories are assumed: SUMMARY, OPTION, EXCTG, GROUP, and PAIR.

The following table provides an overview of the values specified for the fields key and the information that is output. For details on the values specified for the fields key and the information that is output, see Table 1.

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

The following describes the parameters to be specified for the operands key. For the operands key, specify conditions to narrow down the copy groups, consistency groups, and copy pairs to be output.

Specify the copy group IDs of the copy groups to be output. If you specify this parameter but you do not specify the LOADGROUP(YES|FORCE) parameter and have not run the YKLOAD command, an error occurs. If only one copy group has been loaded and you do not specify the LOADGROUP(YES|FORCE) parameter, you can omit this parameter.

Specify the consistency group ID of the consistency group to be output or specify the M-journal group ID.

Specify the R-journal group ID of the consistency group to be output.

Specify whether to load copy groups before running YKGETGRP.

ALL

Loads the copy groups specified for the GROUP parameter if they have not already been loaded.

NO

Does not load copy groups. If no copy groups have been loaded, an error occurs.

FORCE

Forcibly loads copy groups even if the copy pair definitions for a copy group do not exist or are otherwise incomplete. Specify this value to view the copy group definitions.

You do not need to run YKLOAD after you run YKGETGRP with the LOADGROUP(YES) parameter specified, but you do need to run YKLOAD after you run YKGETGRP with LOADGROUP(FORCE) specified. If you run YKGETGRP with LOADGROUP(YES) specified, the route list will not be loaded. For this reason, if you want to then run a CLI command that requires a remote command environment, first use YKLOAD to load the route list.

If you specified YES or FORCE for the LOADGROUP parameter, specify the prefix of the copy group definition file to be loaded. If you omit this, the value of the default parameter PREFIX is assumed.

If another configuration file is already loaded, the prefix must be the same as that of the loaded configuration file.

If you specified YES or FORCE for the LOADGROUP parameter, specify the device address domain ID of the current host (the local device address domain ID). If you omit this, the value of the default parameter DAD is assumed.

STATE(pair-status-of-the-pairs-to-be-output[,pair-status-of-the-pairs-to-be-output...])

The following describes the parameters related to copy pair output conditions. The parameters related to copy pair output conditions are valid if the PAIR parameter is specified for the fields key or if the fields key is omitted.

The following apply to all parameters related to copy pair output conditions.

• The parameter names are not case sensitive.

• Only copy pairs that satisfy the condition specified as the parameter value and enclosed in parentheses ( ) are output.

• If you specify multiple parameters at the same time, only copy pairs that meet all of the conditions specified by the parameters are output. If you specify conflicting parameters at the same time, an error occurs.

• If you specify the same parameter more than once, the value first specified for the parameter is valid.

Copy pairs that match any of the specified copy pair statuses are output.

You can specify the following values.

SIMPLEX, DUPLEX, PENDING, SUSPOP, SUSPCU, SUSPVS, SUSPER, REVRSY, INVALID, TRANS, SWAPPING, HOLD, HOLDER, CHKJNL, HOLDTRNS, NODELTA, CONSLOST

The output copy pairs are those for which the specified value matches the value obtained when the immediately preceding YKQUERY or YKEWAIT command was executed. Until the YKQUERY or YKEWAIT command is run, no information is obtained and thus no copy pairs are output.

Copy pairs that do not match any of the specified copy pair statuses are output.

You can specify the following values.

SIMPLEX, DUPLEX, PENDING, SUSPOP, SUSPCU, SUSPVS, SUSPER, REVRSY, INVALID, TRANS, SWAPPING, HOLD, HOLDER, CHKJNL, HOLDTRNS, NODELTA, CONSLOST

The output copy pairs are those for which the specified value matches the value obtained when the immediately preceding YKQUERY or YKEWAIT command was executed. Until the YKQUERY or YKEWAIT command is run, no information is obtained and thus no copy pairs are output.

Copy pairs whose copy pair matching rate is greater than or equal to minimum-matching-rate and less than or equal to maximum-matching-rate are output.

The copy pair matching rates used are those obtained when the immediately preceding YKQUERY command was executed. Until the YKQUERY command is run, no information is obtained and thus no copy pairs are output.

Copy pairs for which the consistency delta value is greater than or equal to minimum-number-of-seconds and less than or equal to maximum-number-of-seconds are output.

If the maximum number of seconds is omitted, 999999999 is assumed.

The consistency delta values used are those obtained when the immediately preceding YKQUERY command was executed. Until the YKQUERY command is run, no information is obtained and thus no copy pairs are output.

Copy pairs whose volume serial number matches the specified volume-serial-number are output.

If you specify * at the end of the value, copy pairs whose volume serial number starts with volume-serial-number-wildcard are output.

Copy pairs for which the storage system serial number of the P-VOL matches the specified storage-system-serial-number are output.

priSSID(SSID) ~ <four-digit hexadecimal number>((0000-FFFF))

Copy pairs for which the storage system ID of the P-VOL matches the specified SSID are output.

priCU(first-control-unit-number[,last-control-unit-number]) ~ <two-digit hexadecimal number>((00-FF))

Copy pairs for which the control unit number of the P-VOL is the same as or higher than the specified first-control-unit-number and the same as or lower than last-control-unit-number are output.

If last-control-unit-number is omitted, the value specified for first-control-unit-number is assumed.

Copy pairs for which the command control address number of the P-VOL is the same as or higher than the specified first-command-control-address-number and the same as or lower than last-command-control-address-number are output.

If last-command-control-address-number is omitted, the value specified for first-command-control-address-number is assumed.

Copy pairs for which the device number of the P-VOL is the same as or higher than the specified first-device-number and the same as or lower than last-device-number are output.

If last-device-number is omitted, the value specified for first-device-number is assumed. The value of the primary subchannel set ID in the copy group definition file is used as the subchannel set ID.

ONLINE

Copy pairs for which the host connection status of the P-VOL is online are output.

OFFLINE

Copy pairs for which the host connection status of the P-VOL is offline are output.

The host connection status used are those obtained when the immediately preceding YKQUERY command was executed. Until the YKQUERY command is run, no information is obtained and thus no copy pairs are output.

SOFT

Copy pairs whose P-VOL is in the Soft Fence status are output.

SPID

Copy pairs whose P-VOL is in the SPID Fence status are output.

BOTH

Copy pairs whose P-VOL is in the Soft Fence status or the SPID Fence status are output.

UNFENCE

Copy pairs whose P-VOL is neither in the Soft Fence nor in the SPID Fence status are output.

The copy pair matching rates used are those obtained when the immediately preceding YKFENCE QUERY TO(PRIMARY) command was executed. Until the YKFENCE QUERY TO(PRIMARY) command is run, no information is obtained and thus no copy pairs are output.

Copy pairs for which the storage system serial number of the S-VOL matches the specified storage-system-serial-number are output.

The output copy pairs are those for which the specified value matches the value obtained when the YKLOAD command was output.

Copy pairs for which the storage system ID of the S-VOL matches the specified SSID are output.

The output copy pairs are those for which the specified value matches the value obtained when the YKLOAD command was output.

Copy pairs for which the control unit number of the S-VOL is the same as or higher than the specified first-control-unit-number and the same as or lower than last-control-unit-number are output.

If last-control-unit-number is omitted, the value specified for first-control-unit-number is assumed.

The output copy pairs are those for which the specified value matches the value obtained when the YKLOAD command was output.

Copy pairs for which the command control address number of the S-VOL is the same as or higher than the specified first-command-control-address-number and the same as or lower than last-command-control-address-number are output.

If last-command-control-address-number is omitted, the value specified for first-command-control-address-number is assumed.

The output copy pairs are those for which the specified value matches the value obtained when the YKLOAD command was output.

Copy pairs for which the device number of the S-VOL is the same as or higher than the specified first-device-number and the same as or lower than last-device-number are output.

If last-device-number is omitted, the value specified for first-device-number is assumed. The value of the secondary subchannel set ID in the copy group definition file is used as the subchannel set ID.

The output copy pairs are those for which the specified value matches the value obtained when the YKLOAD command was output.

ONLINE

Copy pairs for which the host connection status of the S-VOL is online are output.

OFFLINE

Copy pairs for which the host connection status of the S-VOL is offline are output.

The host connection status used are those obtained when the immediately preceding YKQUERY command was executed. Until the YKQUERY command is run, no information is obtained and thus no copy pairs are output.

SOFT

Copy pairs whose S-VOL is in the Soft Fence status are output.

SPID

Copy pairs whose S-VOL is in the SPID Fence status are output.

BOTH

Copy pairs whose S-VOL is in the Soft Fence status or the SPID Fence status are output.

UNFENCE

Copy pairs whose S-VOL is neither in the Soft Fence nor in the SPID Fence status are output.

The copy pair matching rates used are those obtained when the immediately preceding YKFENCE QUERY TO(SECONDARY) command was executed. Until the YKFENCE QUERY TO(SECONDARY) command is run, no information is obtained and thus no copy pairs are output.

Responses

See Responses returned by YKGETGRP.

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

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