Changes the characteristics of shadow sets created using Volume Shadowing for OpenVMS. For more information about volume shadowing, see the HP Volume Shadowing for OpenVMS manual.

Requires SYSPRV privilege.

Note The following qualifiers are used exclusively to manage host-based minimerge (HBMM) operations and do not apply to other operations: /DELETE /DISABLE /ENABLE /NAME /POLICY If you specify any other (non-HBMM) qualifiers in a command that includes HBMM qualifiers, the command will fail.

Format

SET SHADOW [device-name[:]]

Parameter

device-name[:]

Specifies the name of a shadow set (DSAn:) or shadow set member (ddcu:), depending on the command qualifiers (see parameter formats specified in some qualifier descriptions).

For most qualifiers that take a shadow set (DSAn:) as a parameter the /ALL qualifier can be used in place of the shadow set name to indicate that the requested action applies to all shadow sets on the system. (Exceptions are noted in the description of /ALL.)

Description

The SET SHADOW command and its qualifiers are designed to give the user greater control over the behavior of shadow sets. These commands act upon the shadow set (also known as the virtual unit) or, in some cases, on the individual shadow set member that you specify.

Unless otherwise noted, the qualifier settings typically remain in effect until they are changed using either the SET SHADOW or SET DEVICE command or until the shadow set or shadow set member is dismounted. If the shadow set is remounted or a shadow set member is returned to the shadow set from which it was dismounted, the settings must be specified again.

Some SET SHADOW qualifiers also can be specified using the SET DEVICE command, where they have the same effect. However, if your focus is on changing characteristics of shadow sets, the SET SHADOW command provides more options.

Qualifiers

/ABORT_VIRTUAL_UNIT DSAn:

/ABORT_VIRTUAL_UNIT /ALL

Aborts mount verification on the specified shadow set or on all shadow sets in mount verification on the system.

Use this qualifier when you know that the unit cannot be recovered. When you use this qualifier, the shadow set must be in mount verification. The shadow set aborts mount verification immediately on the system from which the command is issued. If the shadow set is not in mount verification, this command returns the error %SYSTEM-E-UNSUPPORTED, unsupported operation or function.

After this command completes, the shadow set still must be dismounted. Use the following command to dismount the shadow set:

$ DISMOUNT/ABORT/OVERRIDE=CHECKS DSAn:

/ALL

Causes the command to operate on all shadow sets that are mounted on the system from which the command is issued.

/ALL can be used instead of DSAn: in most commands that take a shadow set device specification as a parameter. Exceptions are /DEMAND_MERGE, /DELETE, and /EVALUATE=RESOURCES. /ALL also cannot be specified with /POLICY or any qualifier that operates only on individual shadow set members (for example, /MEMBER_TIMEOUT and /FORCE_REMOVAL).

/CONFIRM

/NOCONFIRM (default)

Specifies whether a query is made before each merge operation to confirm that the operation should be performed on the designated shadow set.

This qualifier can be used only in conjunction with the /DEMAND_MERGE qualifier.

The following responses are valid in response to the query:

• Affirmative: YES, TRUE, or 1
• Negative: NO, FALSE, 0 (zero), or pressing the Return key.
• End the process: QUIT or Ctrl/Z
• When you enter ALL, the command continues to process, but no further prompts are given.

You can enter word responses in uppercase or lowercase letters, and words can be abbreviated to one or more letters. If you enter an illegal response, DCL redisplays the prompt. (See the SET SHADOW examples.)

/COPY_SOURCE ddcu:

/COPY_SOURCE DSAn:

/COPY_SOURCE /ALL

Specifies which source member of a shadow set to use as the source for read data during full copy operations when a third member is added to a shadow set that contains two full members. This qualifier affects only those copy operations that do not use disk copy data (DCD) commands. The source specified by this qualifier persists until the shadow set is dismounted.

Some storage controllers, such as the HSG80, have a read-ahead cache, which significantly improves a device's read performance. Copy operations normally alternate reads between the two source members, which effectively nullifies the benefits of the read-ahead cache. This qualifier lets you force all reads from a single, specified source member for the duration of a copy operation.

In addition to improving copy performance, /COPY_SOURCE can be used to prevent read operations from a specific shadow set member that is considered unreliable. By specifying only the healthy shadow set member, the copy operations can continue to completion. The unreliable shadow set member can be removed once the copy operation completes successfully.

If a shadow set (DSAn:) is specified, all reads for full copy operations are performed from the device that is the current "master" member, regardless of the physical location of that device.

If a shadow set member (ddcu:) is specified, that member is used as the read source for all copy operations. This setting allows you to choose any source member. For example, you can choose a source member that is at the same site as the member being added, rather than using a master member that is not at the same site.

If /ALL is specified, all reads for full copy operations on all currently mounted virtual units are performed from the master member.

/DELETE DSAn:

/DELETE /NAME

Used in conjunction with /POLICY=HBMM, /DELETE removes a host-based minimerge (HBMM) policy from a specified shadow set, or deletes an HBMM named policy from the entire cluster. For example, the following command removes the policy that is currently associated with shadow set DSA1:

$ SET SHADOW /DELETE DSA1 /POLICY=HBMM

In contrast, the following command removes COMPANY_POLICY from the cluster:

$ SET SHADOW /DELETE /NAME=COMPANY_POLICY /POLICY=HBMM

You cannot delete the NODEFAULT policy.

You cannot specify /ALL with /DELETE.

/DEMAND_MERGE DSAn:

Initiates a merge operation on the specified shadow set. This qualifier is useful if the shadow set was created with the INITIALIZE/SHADOW command without the use of the /ERASE qualifier. For more information about using /DEMAND_MERGE, see the HP Volume Shadowing for OpenVMS manual.

You cannot specify /ALL with /DEMAND_MERGE.

An OPCOM message is displayed for each shadow set indicating that a demand merge has been invoked and recording the process ID (PID) of the process that executed the command. For example:

%%%%%%%%%%% OPCOM 9-MAR-2004 10:35:23.24 %%%%%%%%%%% Message from user SYSTEM on NODE1 Demand Merge requested for _DSA721:, PID: 2760009A

/DISABLE=HBMM DSAn:

/DISABLE=HBMM /ALL

Disables host-based minimerge (HBMM) on the specified shadow set or clusterwide on all shadow sets.

HBMM is the only supported value for /DISABLE, and it must be included.

/ENABLE=HBMM

Enables host-based minimerge (HBMM) on the specified shadow set or across the entire cluster if an applicable HBMM policy exists.

HBMM is the only supported value for /ENABLE, and it must be included.

/EVALUATE=RESOURCES

Forces the system to evaluate whether it should act on most shadow copy and merge operations currently being managed on the system. It cancels most operations and then, based on the value of system parameter SHADOW_MAX_COPY and the copy/merge priority of each shadow set), it evaluates the order in which the pending copies and merges should be restarted.

RESOURCES is the only supported value for /EVALUATE, and it must be included.

/EVALUATE does not apply to MSCP-based minimerge operations. MSCP-based minimerge operations are not subject to cancellation and restart by /EVALUATE.

This command is intended to be used after changing the value of the dynamic system parameter SHADOW_MAX_COPY or after issuing a SET SHADOW /PRIORITY=n command for a shadow set. After a suitable delay, all available SHADOW_MAX_COPY slots on the system are allocated using the priority list.

/FORCE_REMOVAL ddcu:

/NOFORCE_REMOVAL ddcu:

Expels the specified shadow set member from the shadow set. The specified device must be a member of a shadow set that is mounted on the system where the command is issued. You cannot specify /ALL with /FORCE_REMOVAL.

If connectivity to a device has been lost and the shadow set is in mount verification, this qualifier causes the member to be expelled from the shadow set immediately.

If the shadow set is not currently in mount verification, no immediate action is taken. If connectivity to a device has been lost but the shadow set is not in mount verification, this qualifier lets you flag the member to be expelled from the shadow set as soon as the shadow set enters mount verification. If no action has been taken on the specified member and you wish to clear the flag, use /NOFORCE_REMOVAL.

If the shadow set is dismounted before the member is expelled, the FORCE_REMOVAL request expires.

/LOG

Instructs the volume shadowing software to display a brief message confirming that the SET SHADOW command completed. If /OUTPUT is also specified, this information is written to the output file.

/MEMBER_TIMEOUT=n ddcu:

Specifies the timeout value to be used for a shadow set member. The specified device must be a member of a shadow set that is mounted on the system where the command is issued.

The value supplied by this qualifier overrides the system parameter SHADOW_MBR_TMO for this specific device. Each member of a shadow set can be assigned a different MEMBER_TIMEOUT value.

The valid range for n is 1 through 16777215 seconds.

The timeout value set by /MEMBER_TIMEOUT does not persist after the shadow set is dismounted.

/MVTIMEOUT=n DSAn:

/MVTIMEOUT=n /ALL

Specifies the mount verification timeout value to be used for all shadow sets on the cluster or for the shadow set specified by its virtual unit name (DSAn:). The specified shadow set must be mounted on the system where the command is issued.

The value supplied by this qualifier overrides the value specified by the system parameter MVTIMEOUT for this specific shadow set.

Note You cannot change the value of MVTIMEOUT for a system disk. Any attempt to do so results in an error.

The valid range for n is 1 through 16777215 seconds.

The timeout value set by /MVTIMEOUT does not persist after the shadow set is dismounted.

/NAME=policy-name

Used with /POLICY=HBMM to define a named host-based minimerge (HBMM) policy or used with /DELETE to delete a policy. The policy is defined clusterwide. See detailed descriptions under /DELETE and /POLICY.

Policy names are case insensitive and must consist of from 1 to 64 characters. Only letters, numbers, the dollar sign ($), and the underscore (_) are allowed.

If you create a default policy, you must assign it the name DEFAULT.

For details about creating and using policy names, see the HP Volume Shadowing for OpenVMS manual.

/OUTPUT=file-name

Outputs any messages to the specified file.

/POLICY=HBMM[=policy-name]

/POLICY=HBMM[=policy-specification]

Creates or deletes a policy for host-based minimerge (HBMM).

HBMM is the only supported value for the /POLICY qualifier, and it must be included. You can optionally specify a named policy, including DEFAULT, or you can specify NODEFAULT to indicate that the shadow set to which it is applied is not to use HBMM, including any DEFAULT policy. For details about specifying policies and using the DEFAULT and NODEFAULT policy names, see the HP Volume Shadowing for OpenVMS manual.

When /POLICY is specified with /DELETE, it removes either a specified HBMM named policy or the HBMM policy for a specific shadow set. You cannot delete the NODEFAULT policy.

When /POLICY is specified with /NAME, it defines a clusterwide named policy. When no qualifiers other than /NAME or /DELETE are specified, /POLICY defines a policy for a specific shadow set.

When defining a policy, you use three keywords (MASTER_LIST, COUNT, and RESET_THRESHOLD) to control the placement and management of HBMM bitmaps. An HBMM policy specification consists of a list of these keywords enclosed within parentheses. Only the MASTER_LIST keyword is required. If COUNT and RESET_THRESHOLD are omitted, default values are applied.

• MASTER_LIST=list
  The MASTER_LIST keyword is used to identify a set of systems as candidates for a master bitmap. The list value can be a single system name; a parenthesized, comma-separated list of system names; or the wildcard character, as shown in the following examples:

  MASTER_LIST=NODE1 MASTER_LIST=(NODE1,NODE2,NODE3) MASTER_LIST=*

  
  When the system list consists of a single system name or the wildcard character, parentheses are optional.
  An HBMM policy must include at least one MASTER_LIST. Multiple master lists are optional. If a policy has multiple master lists, the entire policy must be enclosed with parentheses, and each constituent master list must be separated by a comma as shown in the following example:

  (MASTER_LIST=(NODE1,NODE2), MASTER_LIST=(NODE3,NODE4))

  
  There is no significance to the position of a system name in a master list.

• COUNT=n
  The COUNT keyword specifies how many systems in the master list can have master bitmaps. Therefore, the COUNT keyword and its associated MASTER_LIST must be enclosed within a single parenthetical statement.
  The COUNT value specifies the number of systems on which you want master bitmaps. It does not necessarily mean that the first n systems in the list will be chosen.
  When the COUNT keyword is omitted, the default value is 6 or the number of systems in the master list, whichever is smaller.
  You cannot specify more than one COUNT keyword per master list.
  Examples:

  (MASTER_LIST=(NODE1,NODE2,NODE3), COUNT=2)

  (MASTER_LIST=(NODE1,NODE2,NODE3),COUNT=2),(COUNT=2,MASTER_LIST=(NODE4,NODE5,NODE6))

• RESET_THRESHOLD=n
  The RESET_THRESHOLD keyword specifies the number of blocks that can be set before the bitmap is eligible to be cleared. Each set bit in a master bitmap corresponds to a set of blocks to be merged, so this value can affect the merge time.
  Bitmaps are eligible to be cleared when the RESET_THRESHOLD is exceeded. However, the reset is not guaranteed to occur immediately when the threshold is crossed. For more information about choosing a value for this attribute, see the HP Volume Shadowing for OpenVMS manual.
  The reset threshold is associated with a specific HBMM policy, so the RESET_THRESHOLD keyword can be defined only once in a policy specification. Because its scope is the entire policy, the RESET_THRESHOLD keyword cannot be specified inside a constituent master list when the policy uses multiple master lists.
  When the RESET_THRESHOLD keyword is omitted, the value of 100000 is used by default.
  Example:

  (MASTER_LIST=*, COUNT=4, RESET_THRESHOLD=100000)

Example:

The command in the following example defines the HBMM named policy POLICY_2, which has two master lists. Having multiple master lists can be useful in a multiple-site OpenVMS Cluster configuration because a policy can be defined to ensure that at least one surviving system has an HBMM bitmap in the event of an outage at one or more sites.

$ SET SHADOW /POLICY=HBMM=( - _$ (MASTER_LIST=(NODE1,NODE2,NODE3), COUNT=2), - _$ (MASTER_LIST=(NODE4,NODE5,NODE6), COUNT=2), - _$ RESET_THRESHOLD=150000) - _$ /NAME=POLICY_2

In a policy with multiple master lists, a given system name can appear in only one master list.

A shadow set need not be mounted to have an HBMM policy defined for it.

See the SET SHADOW Examples section for several more /POLICY examples.

/PRIORITY=n DSAn:

Overrides the current default priority setting. Priorities range from 0 (lowest) to 10000 (highest). The default priority is 5000. A shadow set with a priority of 0 is never considered for a merge or a copy on the system.

When a recovery operation (that is, either a merge or a copy) is needed on multiple shadow sets, the shadow sets are recovered in priority order from highest to lowest. The priority setting is system specific; any change in priority made on a single system does not propagate to the entire cluster and does not persist across a system reboot.

Once this qualifier has been applied to a virtual unit that is mounted, the setting persists across any subsequent DISMOUNT and MOUNT commands.

/READ_COST=n ddcu:

/READ_COST=n DSAn:

/READ_COST=n $n$DGAn:

Enables you to modify the default cost assigned to each shadow set member (ddcu:). By modifying the assignments, you can bias the reads in favor of one member of a two-member shadow set or, in the case of three-member shadow sets, in favor of one or two members of the set over the remaining members. The device specified must be a shadow set or member of a shadow set that is mounted on the system where the command is issued.

The valid range for the specified cost is 1 through 65,535 units.

The shadowing driver assigns default READ_COST values to shadow set members when each member is initially mounted. The default value depends on the device type and its configuration relative to the system mounting it. The following list of device types is ordered by the default READ_COST assignments, from the lowest cost to the highest cost:

• DECram device
• Directly connected device in the same physical location
• Directly connected device in a remote location
• DECram served device
• Default value for other served devices

The value supplied by the /READ_COST qualifier overrides the default assignment. The shadowing driver adds the value of the current queue depth of the shadow set member to the READ_COST value and then reads from the member with the lowest value.

Different systems in the cluster can assign different costs to each shadow set member.

When this qualifier specifies a shadow set (DSAn:) instead of a shadow set member, the /READ_COST qualifier switches the read cost setting for all shadow set members back to the default read cost settings established automatically by the shadowing software. The specified shadow set must be mounted on the system where the command is issued.

You cannot specify a value for /READ_COST when you specify /ALL.

If the /SITE command qualifier has been specified, the shadowing driver takes site values into account when it assigns default READ_COST values. In order for the shadowing software to determine whether a device is in the category of "directly connected device in a remote location," the /SITE command qualifier must have been applied to both the shadow set and the shadow set member.

Reads requested for a shadow set from a system at site 1 are performed from a shadow set member that is also at site 1. Reads requested for the same shadow set from site 2 can read from the member located at site 2.

/RECOVERY_OPTIONS=DELAY_PER_SERVED_MEMBER=n

Allows the system manager to adjust the rating assigned to a system based on a delay assessed for each MSCP served shadow set member on that system. The value specified by this qualifier overrides the value established by the SHADOW_PSM_RDLY system parameter. The default delay for each MSCP served member is 30 seconds and the valid range for the specified delay is 0 through 65,535 seconds.

When a copy or merge operation is needed on a shadow set that is mounted on multiple systems, OpenVMS Volume Shadowing attempts to perform this work on a system that has a local connection to all of the shadow set members. Systems are rated with a penalty (delay time) assessed for each shadow set member that is MSCP served to the system. No delay is added for local members, so a system with all locally accessible shadow set members is likely to perform the work before a system where one or more members is served.

IF /ALL is also specified, the specified delay is applied to all currently mounted shadow sets.

See the HP Volume Shadowing for OpenVMS manual for more information.

/RESET=COUNTERS

Resets the shadowing specific counters that are maintained for each shadow set. These counters can be displayed using the SHOW SHADOW command.

The counters that are reset to 0 are the following:

HBMM Reset Count
Copy Hotblocks
Copy Collisions
SCP Merge Repair Cnt
APP Merge Repair Cnt

The the HBMM Reset Count is a running total of the number of times that the HBMM Reset Threshold was exceeded and therefore, the number of times the bitmaps were reset. (The threshhold is set by the RESET_THRESHOLD keyword in the /POLICY qualifier.) For more information, see the HP Volume Shadowing for OpenVMS.

/SITE=n ddcu:

/SITE=n DSAn:

Indicates to the shadowing driver the site location of the specified shadow set (DSAn:) or shadow set member (ddcu:).

The SHADOW_SITE_ID system parameter defines the default site location of the shadow set. You can override the default location of the shadow set with the /SITE qualifier.

The valid range for the site location, represented by n, is 1 through 255.

If /ALL is specified, all virtual units are assigned the new value. The shadow set's member site values remain unchanged.

After you apply this qualifier, the setting remains in effect until you change it using a SET SHADOW/SITE command.

This qualifier can improve read performance because the member that is physically local to the system will be the preferred disk from which to read, provided that you specify the /SITE qualifier for each shadow set member and for the shadow set. (In a Fibre Channel configuration, shadow set members at different sites are directly attached to the system. For the Volume Shadowing and OpenVMS Cluster software, there is no distinction between local and remote in multiple-site Fibre Channel configurations.)

Examples

$ ! Command sequence used on system 1 at site 1:
$ MOUNT/SYSTEM DSA0:/SHADOW=($1$DGA0:,$1$DGA1:) TEST
$ SET SHADOW/SITE=1  DSA0:
$ !
$ ! Command sequence used on system 2 at site 2:
$ MOUNT/SYSTEM DSA0:/SHADOW=($1$DGA0:,$1$DGA1:) TEST
$ SET SHADOW/SITE=2  DSA0:
$ !
$ ! Commands used on both system 1 and system 2:
$ SET SHADOW/SITE=1  $1$DGA0:
$ SET SHADOW/SITE=2  $1$DGA1:
 
      

In this example, the system at site 1 will perform reads from $1$DGA0, which is located at that site, while the system at site 2 will perform reads from $1$DGA1, which is located at site 2.

$ SET SHADOW DSA1: /POLICY=HBMM=  -
_$      (MASTER_LIST=(NODE1,NODE2,NODE3), COUNT=2, -
_$      RESET_THRESHOLD=75000)
      

This command defines an HBMM policy for shadow set DSA1:. The policy specifies that no more than two systems of the three systems listed can have an HBMM master bitmap. Once 75000 blocks have been modified on DSA1:, any existing HBMM bitmaps are zeroed.

$ SET SHADOW /POLICY=HBMM=(MASTER_LIST= -
_$ (NODE1,NODE2,NODE3), RESET_THRESHOLD=75000, COUNT=2) -
_$ /NAME=HONESTY_IS_BEST
      

This command defines the named policy HONESTY_IS_BEST. This policy is available to all cluster members, but is not applied to any specific shadow set.

$ SET SHADOW DSA1: /POLICY=HBMM=HONESTY_IS_BEST
      

This command associates the named policy HONESTY_IS_BEST with shadow set DSA1.

$ SET SHADOW /POLICY=HBMM=( -
_$       (MASTER_LIST=(NODE1,NODE2,NODE3), COUNT=2), -
_$       (MASTER_LIST=(NODE4,NODE5,NODE6), COUNT=2), -
_$               RESET_THRESHOLD=150000) -
_$               /NAME=POLICY_2
      

This command defines the HBMM named policy POLICY_2, which has two master lists.

$ SET SHADOW DSA2: /POLICY=HBMM=POLICY_2
      

This command associates the named policy POLICY_2 with shadow set DSA2.

$ SET SHADOW /POLICY=HBMM /DELETE /NAME=POLICY_2
      

This command deletes the named policy POLICY_2. Note that any shadow set that had acquired the attributes of POLICY_2 by execution of a SET SHADOW DSAn: /POLICY=HBMM=POLICY_2 command is not affected. Changes made to a named policy are not retroactive to a mounted shadow set that was assigned the characteristics of a previous version of that named policy.

$ SET SHADOW  DSA1: /POLICY=HBMM /DELETE
      

This command deletes the existing HBMM policy from DSA1:. If this HBMM policy is enabled on DSA1:, you must first execute the following command to disable the policy before you can delete it:

$ SET SHADOW DSA1: /DISABLE=HBMM

$ SET SHADOW /DEMAND_MERGE/CONFIRM
Allow merge of _DSA721:? [N]:y
Allow merge of _DSA850:? [N]: TRUE
Allow merge of _DSA1010:? [N]:N
$
      

In this example, a merge operation is initiated on DSA721: and DSA850: but not on DSA1010:.