chsess

Parameters for sessions for all storage system types

-help | -h | -?

Lists help for the command. If you specify additional parameters and arguments, those parameters and arguments are ignored.

-quiet

Suppresses the confirmation prompt for this command. This flag answers yes to all confirmation prompts.

-site1loc location

Specifies a location to associate with the site 1 volume role.

-site2loc location

Specifies a location to associate with the site 2 volume role.

-site3loc location

Specifies a location to associate with the site 3 volume role.

-site4loc location

Specifies a location to associate with the site 4 volume role.

-desc description

Specifies the new description for the session. This description can have up to 250 alphanumeric characters. If the description contains white space, enclose it in single quotation marks.

-groupname group_name

Specifies the new session group for the session to belong to. The group name can have up to 250 alphanumeric characters. If the group name contains white spaces, enclose it in single quotation marks.

-rmgroup

Specifies the session should be removed from the session group it currently belongs to.

-name new_session_name

Specifies the new name for the session. This parameter is mutually exclusive and cannot be specified with any other parameter. The session name can have up to 250 alphanumeric characters and must be unique.

Note:

• This command is supported only for users with administrator privileges.
  Important: Do not issue the command under the following conditions:
  • If the session is running.
  • If the session is scheduled to run before renaming can be completed.
• This command is not supported under the following conditions:
  • If HyperSwap® or Hardened Freeze is enabled for the session.
  • If the session is an ESE Sizer session type, a Safeguarded Copy for Storage Virtualize session type, an XIV® or a FlashSystem A9000 session type, or a basic HyperSwap session type.
  • If the session is in transition state.
• This command is supported only when the session is in these states: Defined, Prepared, Suspended, and Protected. A FlashCopy® session can be renamed, when it is in the Target Available state.
• After a session is renamed, operators that previously had access to the session, will no longer have access to the session with the new session name. You must provide access to the newly renamed session on both local and standby servers, to all Operator users and groups who previously had access to it.

session_name... | -

Specifies the name of the session that is to be modified.

Alternatively, use the dash (-) to specify that input for this parameter comes from an input stream (stdin). The dash is supported only in single-shot mode.

Parameters for sessions for IBM DS8000 or TotalStorage Enterprise Storage Server storage systems

-dsinc { yes | no }

For a point-in-time session, specifies whether the FlashCopy relationship is incremental for the next Flash or Start command.

Note: Multiple incremental FlashCopy will be used if the source storage system supports it.

For practice sessions, specifies whether the practice role pair relationship is incremental for the next Flash command. For Global Mirror Either Direction with Two Site Practice sessions, this parameter will apply to both the H1-I1 and H2-I2 role pairs. This parameter is valid for Global Mirror practice sessions only if the source storage system supports multiple incremental FlashCopy. Valid values are yes or no

-dspers { yes | no }

Specifies whether the next FlashCopy relationship for this session is persistent. Valid values are yes or no.

For practice sessions, this parameter applies only to sessions for IBM® DS8000® version 4.2 or later.

-dsnocpy { yes | no }

For a point-in-time session, specifies whether the FlashCopy relationship is established with a background copy for the next Flash or Start command. Valid values are yes or no.

For practice sessions, this parameter applies only to sessions for IBM DS8000 version 4.2 or later.

-dspmir { no | preferred | required }

Specifies the Preserve Mirror option for storage systems. You can specify no, preferred, or required. If this option is not specified, the default is no preserve mirror options.

-dstgtpprc { true | false }

Allows the FlashCopy target volume to be a remote mirror and copy source volume if the option is set to true. This parameter must be set to true for the dspmir parameter to take effect. The default option for this parameter is false.

-rmreserves { yes | no }

Removes the persistent reserve on the target volumes to allow the establishment of a session. When this parameter is set to yes, the setting persists for the session and remains set until you change the value. Warnings are displayed to indicate that the value is set to yes when you attempt to start the session.

-failIfTgtOnline { yes | no }

Determines whether the Start command fails if a target volume is online. If the parameter is set to yes, the target is determined to be online to a host, and the Start command fails.

Notes:

• Online means that path groups are present. A path group is necessary, but is not enough to indicate that the volume is online. For example, an LPAR that is not part of a sysplex can be taken down (for example, through a power-off without a shutdown) and path groups display as present, but no LPAR has the volume online. That is, the path groups are present, but IBM z/OS® software might think the volumes are offline.
• It cannot be determined with absolute certainty whether the target is online to a host.
• This parameter affects only count key data (CKD) volumes.

-failIfTgtOnline_fc { yes | no }

Determines whether the Flash command fails if a target volume is online. If the parameter is set to yes, the target is determined to be online to a host, and the Flash command fails.

Notes:

• Online means that path groups are present. A path group is necessary, but is not enough to indicate that the volume is online. For example, an LPAR that is not part of a sysplex can be taken down (for example, through a power-off without a shutdown) and path groups display as present, but no LPAR has the volume online. That is, the path groups are present, but IBM z/OS software might think the volumes are offline.
• It cannot be determined with absolute certainty whether the target is online to a host.
• This parameter affects only count key data (CKD) volumes.

-reset_tgt_reserve_fc { yes | no }

Resets any reserves for target volumes during a FlashCopy Flash command. This parameter affects only fixed block data (FB) volumes

-aftersuspend { hold | release }

Specifies the session operation after a suspend occurs. This parameter applies to Metro Mirror and Metro Global Mirror sessions. Valid policies are:

hold

Does not allow any updates to the primary volume after a suspend.

release

Allows updates to the primary volume after a suspend.

-expireautoroll_h1 { yes | no }

Specifies whether the Copy Services Management server will automatically expire an entire backup when it detects the hardware has rolled off the backup on at least one volume. Set this option to free up additional space whenever one or more volumes do not have enough backup capacity to form new backups. This can help avoid out-of-space conditions. However, when a backup is automatically expired, it is no longer available for recovery across any of the volumes that contained that backup. By default, this option is not set. When this option is not set, the backup is not automatically expired so that if one or more volumes did not auto roll the backup, those volumes can still be recovered to that backup. To allow recovery to those volumes, you must remove any volumes indicating that they auto rolled that backup, from the session.

Note: If you set this option, but the backup is in a recovery relationship, and the hardware rolls a volume off, Copy Services Manager does not expire it.

allowexpire_h1 { yes | no }

Specifies whether backups can be manually expired or not. If this option is not set, the Expire Backup and the Terminate command will not be allowed.

-backupfreq_h1 backup_frequency_h1

Specifies the value in minutes for how often a Safeguarded Copy backup can be taken.

-minretention_h1 min_retention

Specifies the number of backups to be retained. This option indicates that a backup should not expire even if it is older than the time specified for backupretention option, if the deletion of backup would cause the total number of backups to fall below this number. This option applies only to deletions due to the specified backup retention period time and does not apply to the Expire Backup command.

-backupretention_h1 backup_retention_h1

Specifies the value in hours for how long Safeguarded Copy backups should be retained. After the time has elapsed the backups will be expired.

-snapshotretention_h1 snapshot_retention_h1

Specifies the value in hours for how long Storage Virtualize Copy snapshots should be retained. After the time has elapsed the snapshots will be expired.

-recovernocopy_h1r1 { yes | no }

For the h1r1 role pair, specifies whether the recovery relationship is established with a background copy for the next Recover Backup command. Valid values are yes or no.

-recoverpersistent_h1r1 { yes | no }

For the h1r1 role pair, specifies whether the recovery relationship is established with persistence for the next Recover Backup command. Valid values are yes or no. Support for persistent recovery on Safeguarded Copy requires the proper level of DS8000 microcode.

-zosSysplex {sysplex_name || NO_ASSOCIATION }

Specifies or clears the z/OS sysplex that is associated with the session. The -zosSysplex or -zosSystem parameter is required to use the -SiteSelectionHS and -PriorityHS parameters and the parameters for managing HyperSwap and enabling hardened freeze. -zosSysplexh1h2 and -zosSysplexh3h4 relate to the role pair.

sysplex_name

Specifies the z/OS sysplex and host system(separated by a dash "-") that is connected to the storage system.

NO_ASSOCIATION

Clears the associated sysplex if a sysplex is defined for the session.

-zosSystem {system_name | NO_ASSOCIATION }

Specifies or clears the z/OS system that is associated with the session. The -zosSystem or -zosSysplex parameter is required to use the -SiteSelectionHS and -PriorityHS parameters and the parameters for managing HyperSwap and enabling hardened freeze. -zosSystemh1h2 and -zosSystemh3h4 relate to the role pair.

system_name

Specifies the z/OS system and host system(separated by a dash "-") that is connected to the storage system.

NO_ASSOCIATION

Clears the associated system if a system is defined for the session.

-SiteSelectionHS { auto | priority }

For multi-target sessions, determines how HyperSwap Manager selects the target site for a HyperSwap operation.

The following values are valid for this parameter:

auto

Enables HyperSwap Manager to select the target site for a HyperSwap operation. This is the default value.

HyperSwap Manager selects the target site that keeps the most sysplex members active. If multiple target sites are equal candidates for the HyperSwap operation, HyperSwap Manager uses the priority value to select the target site. For example, if both site 1 and site 3 are equal, but the priority value is 3,2,1, HyperSwap selects site 3.

priority

Directs HyperSwap Manager to select the target site that is based on the priority list that is specified by the -PriorityHS parameter.

-PriorityHS priority_list

For multi-target sessions, determines the priority in which HyperSwap Manager selects the target site for a HyperSwap operation. The value for this parameter is a string with the list of sites in order of priority. You can separate the sites by a comma (,) or a semi-colon (;).

The default value is 1,2,3, which indicates that the first priority is site 1, the second priority is site 2, and the third priority is site 3. If site 1 is the active site, then the first value 1 is ignored. HyperSwap Manager selects site 2 or 3 depending on the HyperSwap status and availability of the sites, with site 2 being the preferred site.

If you enter the parameter -SiteSelectionHS auto, this parameter is used only when multiple target sites are equal candidates for a HyperSwap operation.

If you enter the parameter -SiteSelectionHS priority, this parameter determines the order in which HyperSwap Manager selects the target site.

-manageH1H2withHyperSwap { yes | no }

-manageH1H3withHyperSwap { yes | no }

-manageH2H3withHyperSwap { yes | no }

Enables the following session types to use Basic HyperSwap.

• Metro Mirror Failover/Failback
• Metro Global Mirror
• Metro Global Mirror with Practice
• Metro Mirror-Metro Mirror

For single-target sessions, use the -manageH1H2withHyperSwap parameter. For multi-target sessions, use the applicable parameter for each role pair. For example, if you want to apply this parameter to only the H1>H3 role pair, use -manageH1H3withHyperSwap.

The following values are valid values for these parameters:

yes

Enables the following HyperSwap options to be set for the session:

• -disableHS { yes | no }
• -onConfigErrorHS { disable | partition }
• -onPlannedErrorHS { disable | partition }
• -onUnplannedErrorHS { disable | partition }

no

Disables HyperSwap options for the session.

-disableHS { yes | no }

Disables HyperSwap for all of the role pairs that are in the session. This parameter is applicable only if a -manageHxHxwithHyperSwap parameter is set to yes.

If HyperSwap detects a triggering event while it is disabled, it does not perform a swap.

Issuing the -disableHS no parameter resets the disable command (-disableHS yes), but does not necessarily mean that HyperSwap is enabled. It might mean only that HyperSwap is no longer disabled for operator reasons. For example, the HyperSwap address spaces were not started, a new member was in the process of joining the sysplex, or there was a HyperSwap in progress.

To determine the reasons that HyperSwap might be disabled, see the session messages in the GUI. To view the messages, open the Sessions page, select the session, and click Session Actions > View/Modify > View Messages.

-onPlannedErrorHS { disable | partition }

This optional parameter specifies the policy for the action to be taken when an error occurs during a planned HyperSwap. Valid policies are:

disable

HyperSwap processing is stopped and backed up, and HyperSwap is disabled.

partition

Systems that cannot complete the swap operation are partitioned out of the sysplex, and the HyperSwap continues with the remaining members of the sysplex. This is the default value.

-onUnplannedErrorHS { disable | partition }

Specifies the policy for the action to be taken when an error occurs during an unplanned HyperSwap. Valid policies are:

disable

HyperSwap processing is stopped and backed up, HyperSwap is disabled, and a permanent I/O error is returned to any users of the failing device.

partition

Systems that cannot complete the swap operation are partitioned out of the sysplex, and the HyperSwap continues with the remaining members of the sysplex. This is the default value.

-enableHardenedFreeze { yes | no }

-enableH1H2HardenedFreeze { yes | no }

-enableH1H3HardenedFreeze { yes | no }

-enableH2H3HardenedFreeze { yes | no }

Specifies whether the z/OS Input/Output Supervisor (IOS) is used to manage freeze operations. If this parameter is set to yes, the following actions can occur:

• A freeze can occur regardless of whether the copy services management server is started or stopped.
• You can include z/OS system volumes such as paging, database, and WebSphere® Application Server hierarchical file system (HFS) volumes as Metro Mirror volumes in the session. When you set the -enableHardenedFreeze parameter to yes, IOS manages the freeze operations for all Metro Mirror volumes in the session, which prevents the copy services management server from freezing itself. This parameter does not enable IOS to manage freeze operations for Global Mirror volumes.

IOS support for managing freeze operations is included with HyperSwap. This parameter is ignored if the -manageH1H2withHyperSwap parameter is set to yes.

This parameter requires two z/OS address spaces: the Basic HyperSwap Management address space and the Basic HyperSwap API address space. For instructions about how to start these address spaces, see Preparing to use HyperSwap from z/OS in Knowledge Center.

-enableHardwareReserves { yes | no }

Specifies whether the z/OS Input/Output Supervisor (IOS) will allow hardware reserves on volumes in the session when a HyperSwap configuration has been loaded.

Support for hardware reserves requires the proper level of DS8000 microcode and z/OS IOS maintenance.

-coordint coordination_interval_time

Specifies the new coordination interval time for Global Mirror type sessions. This parameter is meant to be used by advanced users. -coordint_h1j3, -coordint_h2j1, -coordint_h1j2, -coordint_h3j1, -coordint_h3j2, and -coordint_h2j3 relate to the role pair.

-rpo rpo_value

Specifies the new consistency group interval time in seconds for the XX-XX role pair. The value of data exposure for the session trends toward this value. This parameter applies only to Global Mirror session types and copy types where the recovery point objective (RPO) is mapped. A value of 0 specifies that the storage system continuously attempt to form consistency groups. The possible range of values is 0 - 65535. The default is 0.

Parameters -rpo_h1j2, -rpo_h1j3, -rpo_h2j1, -rpo_h3j1, -rpo_h3j2, and -rpo_h2j3 relate to the role pair.

-dsRPOwarning dsRPOwarning_value

Specifies whether an alert is generated when an RPO threshold is exceeded for a role pair. This parameter applies only to Global Mirror and Metro Global Mirror sessions.

The range of values is 0 - 65535. The default is 0, which specifies that no alerts are generated. If the value is other than 0, it must be greater than the value for the -rpo parameter and less than the value for the -dsRPOsevere parameter.

Parameters -dsRPOwarning_h1j2, -dsRPOwarning_h1j3, -dsRPOwarning_h2j1, -dsRPOwarning_h3j1, -dsRPOwarning_h3j2, and -dsRPOwarning_h2j3 relate to the role pair.

-dsRPOsevere dsRPOsevere_value

Specifies whether an alert is generated and the session status is changed to Severe when an RPO threshold is exceeded for a role pair. This parameter applies only to Global Mirror and Metro Global Mirror sessions.

The range of values is 0 - 65535. The default is 0, which specifies that no alerts are generated. If the value is other than 0, it must be greater than the value for the -dsRPOwarning parameter.

Parameters -dsRPOsevere_h1j2, -dsRPOsevere_h1j3, -dsRPOsevere_h2j1, -dsRPOsevere_h3j1, -dsRPOsevere_h3j2, and -dsRPOsevere_h2j3 relate to the role pair.

-reflash { yes | no }

For sessions with journal volumes, specifies whether to reflash a consistent set of data to the journal volume after a Recover command is issued to the session. Reflashing to the journal volume ensures that there is a consistent copy of the data to recover from if failures occur during resynchronization. Valid values are yes or no. If you enter no, the journal volumes will not have a consistent copy of the data after the recover operation. However, the space will be available when using space efficient volumes.

-preventreflash { yes | no }

For sessions with practice volumes, specifies whether to allow the session to issue another Flash that will overwrite the existing data on the practice volumes. If the option is set to yes, after a Flash or Recover, the session will not allow another Flash to occur until the Allow Practice Flash command is issued.

-maxdrain max_drain_time

Specifies the new maximum drain time for Global Mirror type sessions. This parameter is meant to be used by advanced users.

If you specify -maxdrain 0, the storage system uses its default value instead of zero. Any other positive integer in the valid range is accepted by the storage system. However, when a zero is sent to the storage system, the storage system is instructed to set the value back to its default value.

The -maxdrain parameter is related to the DS -drain parameter. The default value for the -drain parameter is 30240 seconds; the maximum value for the -maxdrain parameter is 65,535 seconds. For more information, see the mkgmir command in the IBM DS8000 Command-Line Interface User's Guide.

Parameters -maxdrain_h1j3, -maxdrain_h2j3, -maxdrain_h2j1, -maxdrain_h1j2, -maxdrain_h3j1, and -maxdrain_h3j2 relate to the role pair.

Parameters for sessions for SAN Volume Controller, Storwize® family, or Storwize V7000 Unified storage systems

-svcinc { yes | no }

For a point-in-time session, specifies whether the FlashCopy relationship for the storage systems is incremental for the next Flash or Start command. Valid values are yes or no.

-svccopyrate svc_background_copy_rate

Specifies the copy rate that the storage systems use to complete the background copy of the FlashCopy relationships. For older storage systems running IBM Spectrum Virtualize, specify a value in the range 0-100; for newer storage systems at release 7.8.1 and higher, specify a value in the range 0-150. The default is 50.

When you specify 0, you are specifying the equivalent of the no-copy option for a TotalStorage Enterprise Storage Server or IBM DS8000 FlashCopy session. If the session is completing a background copy when you change the option, the background copy rate of the consistency group on the storage system will be immediately modified.

The consistency group immediately uses the new rate to complete the background copy.

-svccopyrate_h2i2 svc_background_copy_rate

Specifies the copy rate that the storage systems use to complete the background copy of the FlashCopy relationships. For older storage systems running IBM Spectrum Virtualize, specify a value in the range 0-100; for newer storage systems at release 7.8.1 and higher, specify a value in the range 0-150. The default is 50.

A value of 0 is the equivalent of specifying the no-copy option for a TotalStorage Enterprise Storage Server® or IBM DS8000 FlashCopy session. If the session is completing a background copy when you change the option, the background copy rate of the consistency group on the storage system is immediately updated. The consistency group immediately uses that rate to complete the background copy.

-enableChangeVolumes { yes | no }

Specifies whether the use of change volumes is enabled in the copy sets for the session. Change volumes are denoted as Cx, where x identifies the site. These volumes contain point-in-time images that are copied from the H1 and H2 volumes. The C1 volume stores changes from the H1 volume. These changes are sent from the C1 volume to the H2 volume, and then to the C2 volume.

Because the data that is replicated between sites contains point-in-time changes rather than all changes, a lower bandwidth link is required between the sites when change volumes are used. However, the use of change volumes can result in an increase to data exposure. Therefore, you might want to enable or disable this option depending on your network traffic or business requirements.

The valid values for this parameter are yes or no. The default is yes. This parameter applies only to Global Mirror Failover/Failback with Change Volumes sessions.

The images are copied to the change volumes during the cycle period that is defined by the -cycleperiod parameter.

The use of this parameter requires that the session is in an inactive state. An example of an inactive state is Defined or Suspended.

-cycleperiod cycle_period

Specifies the period in seconds in which the change volumes are refreshed with a consistent copy of the data. If a copy does not complete in the cycle period, the next cycle period will not start until the copy is complete. The range of possible values is 60 - 86400. The default is 300. This parameter applies only to Global Mirror Failover/Failback with Change Volumes sessions.

-svcRPOwarning_h1h2 svcRPOwarning_h1h2_value

Specifies whether an alert is generated when an RPO threshold is exceeded for a H1-H2 role pair. This parameter applies only to Global Mirror Failover/Failback with Change Volumes sessions.

The range of values is 0 - 172800. The default is 0, which specifies that no alerts are generated. If the value is other than 0, it must be greater than the value for the -cycleperiod parameter and less than the value for the -svcRPOsevere_h1h2 parameter.

-svcRPOsevere_h1h2 svcRPOsevere_h1h2_value

Specifies whether an alert is generated and the session status is changed to Severe when an RPO threshold is exceeded for a H1-H2 role pair. This parameter applies only to Global Mirror Failover/Failback with Change Volumes sessions.

The range of values is 0 - 172800. The default is 0, which specifies that no alerts are generated. If the value is other than 0, it must be greater than the value for the -svcRPOwarning_h1h2 parameter.

-enableAutoRestart { yes | no }

Specifies whether the session should restart automatically if it unexpectedly suspends with reason code 1720 or 1920. An automatic restart is attempted for every suspend with reason code 1720 or 1920 a certain number of times (determined be the storage server's gmlinktolerance value) within a 30 minute time period. If the number of allowable automatic restarts is exceeded within the time period, the session will not restart automatically on the next unexpected suspend. Issue a Start command to restart the session, clear the automatic restart counters and enable automatic restarts.

If a Global Mirror with Change Volumes session is running with change volumes disabled, this option causes the session to restart automatically with change volumes enabled and form consistency groups based on the cycle time defined in the session properties. After the condition that caused the suspend with reason code 1720 or 1920 is fixed, you can disable change volumes manually by issuing the chsess CLI command with the -enableChangeVolumes option set to No.

Warning: Enabling this option causes the session to be automatically restarted by the server. When this occurs, the secondary site will not be consistent until the relationships are fully re-synced.

-autoRestartDelay delay_time

Specifies the amount of time, in seconds, in which the copy services management server will wait after an unexpected suspend with reason code 1720 or 1920 before automatically restarting the session. This option is only valid when the -enableAutoRestart option is set to Yes.

The range of values is 0 - 43200. The default value is 0, which specifies that the session is restarted immediately following a suspend with reason code 1720 or 1920.

recoverypool svc_recovery_pool_name

For Safeguarded Copy and Snapshot sessions, specifies the single pool that should be used to define the recovery volumes in.

defaultrecoverypool

Indicates that the source pool or pools of the source volumes should be used to define the recovery volume in.

snapshotpool svc_snapshot_pool_ID

For Snapshot sessions, specifies the single child pool ID that should be used to create the snapshot volumes in.

defaultsnapshotpool

Indicates that the snapshot will be created in the same pool or pools as the source volumes.

Parameters for sessions for FlashSystems/IBM Spectrum Accelerate systems

-rpo rpo_value

Specifies the RPO threshold for the session in seconds. The -rpo parameter works with the -schedule parameter to determine:

• How often FlashSystem/IBM Spectrum® Accelerate attempts to form a consistency group.
• Whether the RPO value exceeds the threshold.

If the RPO on the storage system exceeds the RPO threshold for the session, the session changes to the Severe state and an alert is generated. The possible range of values is 30 - 86400. The default is 30.

-schedule schedule

For a FlashSystem/IBM Spectrum Accelerate Global Mirror session, this option specifies how often FlashSystem/IBM Spectrum Accelerate forms a consistency group to ensure consistency on the secondary side and achieve the RPO that is set by the -rpo option. 

The following are the possible values for –schedule: {never | min_interval | 00:00:30 | 00:00:40 | 00:00:50 | 00:01:00 | 00:01:10 | 00:01:20 | 00:01:30 | 00:01:40 | 00:01:50 | 00:02:00 | 00:05:00 | 00:10:00 | 00:15:00 | 00:30:00 | 01:00:00 | 02:00:00 | 03:00:00 | 04:00:00 | 06:00:00 | 08:00:00 | 12:00:00}

The default is min_interval, which is 20 seconds.