Document revision date: 30 March 2001

When mounting volume sets, always list the volume with the largest storage capacity first. You should name the largest volume first because the volume set and directory information goes on the first volume listed in a MOUNT command line. A small-capacity disk may not have adequate storage for the volume and directory information.

Example 5-3 shows the MACRO-32 statements required to produce a $MOUNT system service item to mount a volume set that contains two shadow sets.

Example 5-3 Item List to Create and Mount a Volume Set

DSA23: .ASCID /DSA23:/ DSA51: .ASCID /DSA51:/ MEMBER009: .ASCID /$4$DUA9:/ MEMBER005: .ASCID /$4$DUA5:/ MEMBER010: .ASCID /$4$DUA10:/ MEMBER012: .ASCID /$4$DUA12:/ MEMBER003: .ASCID /$4$DUA3:/ MEMBER034: .ASCID /$4$DUA34:/ VOLUME_WORK1: .ASCID /WORK1/ VOLUME_WORK2: .ASCID /WORK2/ VOLUME_LOGNM: .ASCID /WRKD$/ .MACRO .ITEM, SIZE, CODE, BUFFER, RETURN=0 .WORD SIZE, CODE .ADDRESS BUFFER, RETURN .ENDM .ITEM ITMLST: .ITEM 6, MNT$_SHANAM, DSA23 (1) .ITEM 8, MNT$_SHAMEM, MEMBER009 (2) .ITEM 8, MNT$_SHAMEM, MEMBER005 .ITEM 9, MNT$_SHAMEM, MEMBER010 .ITEM 5, MNT$_VOLNAM, VOLUME_WORK1 (3) .ITEM 6, MNT$_SHANAM, DSA51 (4) .ITEM 9, MNT$_SHAMEM, MEMBER012 (4) .ITEM 8, MNT$_SHAMEM, MEMBER003 .ITEM 9, MNT$_SHAMEM, MEMBER034 .ITEM 5, MNT$_VOLNAM, VOLUME_WORK2 (4) .ITEM 5, MNT$_LOGNAM, VOLUME_LOGNM (5) .LONG 0

The following list describes the elements in Example 5-3:

1. Notice that the virtual unit item descriptor for the first volume in the volume set occurs first. This item descriptor specifies DSA23 as the name of the first virtual unit in the volume set.
2. The virtual unit item descriptor is followed by item descriptors for each of the devices or members that are to be represented by the first virtual unit: $4$DUA9, $4$DUA5, and $4$DUA10.
3. The member item descriptors are followed by an item descriptor that specifies the volume label for the first shadow set in the volume set as WORK1.
4. Following the descriptors for the first shadow set in the volume set are similar item descriptors for the second shadow set in the volume set. These item descriptors specify the second virtual unit as DSA51; the devices as $4$DUA12, $4$DUA3, and $4$DUA34; and the volume label as WORK2.
5. The last item descriptor specifies the logical name for the entire volume set as WRKD$.

You can use the $DISMOU system service to perform the following three shadow set operations:

• Remove a member from a shadow set
• Remove a member from a shadow set for a minicopy operation (as described in Section 7.12)
• Dismount a shadow set across a cluster from a single node
• Dismount and dissolve a shadow set

The call to the $DISMOU system service has the following format:

SYS$DISMOU devnam, flags

The action that $DISMOU takes depends in part on whether you specify a shadow set virtual unit or a shadow set member in the devnam argument.

For a complete description of the $DISMOU service and its arguments, see the OpenVMS System Services Reference Manual.

5.4.1 Removing Members from Shadow Sets

If you want to remove a single member from a shadow set, you must make a call to $DISMOU. In the devnam argument, you should specify the name of the shadow set member you want to remove. The specified member is spun down unless you specify the DMT$M_NOUNLOAD option in the flags argument.

The MACRO-32 code in Example 5-4 demonstrates a call to $DISMOU that removes the member $2$DUA9 from a shadow set.

Example 5-4 Removing a Member from a Shadow Set

$DMTDEF FLAGS: .LONG DMT$M_NOUNLOAD MEMBER001: .ASCID /$2$DUA9:/ . . . $DISMOU_S - devnam = MEMBER001, - flags = FLAGS . . . .END

5.4.2 Dismounting and Dissolving Shadow Sets

If you want to dismount a shadow set on a single node, you must make a call to $DISMOU. In the devnam argument, you should specify the name of the virtual unit that represents the shadow set you want to dismount. If you want to dismount the shadow set clusterwide, specify the DMT$M_CLUSTER option in the flags argument of the call.

When you dismount a shadow set on a single node in an OpenVMS Cluster system, and other nodes in the OpenVMS Cluster still have the shadow set mounted, none of the shadow set members contained in the shadow set are spun down, even if you have not specified the DMT$M_NOUNLOAD flag. After this call completes, the shadow set is unavailable on the node from which the call was made. The shadow set is still available to other nodes in the cluster that have the shadow set mounted.

If the node on which the shadow set is being dismounted is the only node that has the shadow set mounted, the shadow set dissolves. The shadow set member devices are spun down unless you specify the DMT$M_NOUNLOAD flag.

The MACRO-32 code in Example 5-5 demonstrates how to use the $DISMOU system service to dismount the shadow set represented by the virtual unit DSA23.

Example 5-5 Dismounting and Dissolving a Shadow Set Locally

$DMTDEF FLAGS: .LONG 0 DSA23: .ASCID /DSA23:/ . . . $DISMOU_S - devnam = DSA23, - flags = FLAGS . . . .END

When a shadow set is dissolved:

• Each of the former shadow set members can be mounted as a single disk for other purposes.
  Each volume, however, continues to be marked as having been part of a shadow set. After you dissolve a shadow set, each volume retains the volume shadowing generation number that identifies it as being a former shadow set member (unless you remount the volume outside of the shadow set). Volumes marked as having been part of a shadow set are automatically software write-locked to prevent accidental deletion of data. You cannot mount these volumes for writing outside of a shadow set unless you use the MNT$M_OVR_SHAMEM option with the system service MNT$_FLAGS item code.
• The virtual unit changes to an offline state.

The MACRO-32 code in Example 5-6 demonstrates a call to the $DISMOU system service to perform a dismount across the cluster. When the shadow set is dismounted from the last node, the shadow set is dissolved.

Example 5-6 Dismounting and Dissolving a Shadow Set Across the Cluster

$DMTDEF FLAGS: .LONG DMT$M_CLUSTER DSA23: .ASCID /DSA23:/ . . . $DISMOU_S - devnam = DSA23, - flags = FLAGS . . . .END

You must specify the DMT$M_CLUSTER option with the flags argument if you want the shadow set dismounted from every node in the cluster. When each node in the cluster has dismounted the shadow set (the number of hosts having the shadow set mounted reaches zero), the volume shadowing software dissolves the shadow set.

5.4.3 Setting $DISMOU Flags for Shadow Set Operations

Table 5-2 lists the options for the $DISMOU flags argument and describes the shadow set operations that use these options. For a full description of each of these flag options, see the description of the $DISMOU service in the OpenVMS System Services Reference Manual.

Table 5-2 $DISMOU Flag Options

Option	Description
DMT$M_MINICOPY_REQUIRED	$DISMOU fails if minicopy has not been enabled on the disk.
DMT$M_MINICOPY_OPTIONAL	$DISMOU takes place, regardless of whether minicopy is enabled on the disk.
DMT$M_FORCE	If connectivity to a device has been lost and the shadow set is in mount verification, this flag causes a named shadow set member to be immediately expelled from the shadow set.
DMT$M_UNLOAD	Valid for all shadowing-related requests.
DMT$M_CLUSTER	Valid for all shadowing-related requests.
DMT$M_ABORT	Honored for virtual units, ignored for members.
DMT$M_UNIT	Ignored for virtual units and their members.

5.5 Evaluating Condition Values Returned by $DISMOU and $MOUNT

This section discusses the condition values returned by the $DISMOU and $MOUNT system services that pertain to mounting and using shadow sets. For a complete list of the condition values returned by these services, see the OpenVMS System Services Reference Manual.

If $MOUNT returns the condition value SS$_BADPARAM, your item list probably contains one of the following errors:

• The virtual unit specified in one of your MNT$_SHANAM item descriptors contains a name other than DSAn:.
• A MNT$_SHAMEM item descriptor appears in the item list before any MNT$_SHANAM item descriptor.
• Your item list contains a MNT$_SHANAM item descriptor, but it is not followed by the item descriptor MNT$_SHAMEM.
• A MNT$_DEVNAM item descriptor appears in the item list in the middle of a series of item descriptors that specify a single shadow set. You can construct a volume set that contains one or more nonshadowed disks, as well as one or more shadow sets. However, when you use the MNT$_DEVNAM item descriptor to specify the nonshadowed disk, it must not appear between the MNT$_SHANAM item descriptor that specifies a virtual unit and the item descriptors that specify the members of the shadow set that the virtual unit represents.
• The following list contains possible status messages that $MOUNT can return when mounting and using shadow sets:
  • SS$_VOLINV (label mismatched)
  • SS$_SHACHASTA (shadow state change occurred during a mount operation)
  • SS$_MEDOFL (physical unit not accessible)
  • SS$_INCSHAMEM (physical disk incompatible for shadow set)

See also Appendix A for shadowing-related status messages.

5.6 Using $GETDVI to Obtain Information About Shadow Sets

The $GETDVI system service is useful for obtaining information about the shadow set devices on your system. Through the use of the shadow set item codes, you can determine the following types of information:

• Whether a device is a shadow set virtual unit or a shadow set member
• Whether a device is the target of a copy or merge operation
• The name of the virtual unit that represents the shadow set of which the particular device is a member
• The entire membership of a shadow set, including the virtual unit and all of the members
• Whether or not a member has been removed from the shadow set

The call to $GETDVI has the following format:

SYS$GETDVI [efn],[chan],[devnam],itmlst,[iosb],[astadr],[astprm],[nullarg]

For a complete description of the $GETDVI and $GETDVIW services and their arguments, see the OpenVMS System Services Reference Manual.

Table 5-3 lists the information returned by the $GETDVI shadow set item codes.

Table 5-3 SYS$GETDVI Item Codes

Item Code	Function
DVI$_SHDW_CATCHUP_COPYING	Returns a Boolean longword. The value 1 indicates that the device is the target of a copy operation.
DVI$_SHDW_MASTER	Returns a Boolean longword. The value 1 indicates that the device is a virtual unit.
DVI$_SHDW_MASTER_NAME 1	When the specified device is a shadow set member, $GETDVI returns the virtual unit name for the shadow set of which it is a member. If you specify a virtual unit or a device that is not a shadow set member, $GETDVI returns a null string.
DVI$_SHDW_MEMBER	Returns a Boolean longword. The value 1 indicates that the device is a shadow set member.
DVI$_SHDW_MERGE_COPYING	Returns a Boolean longword. The value 1 indicates that the device is a merge member of the shadow set.
DVI$_SHDW_NEXT_MBR_NAME 1	Returns the device name of the next member in the shadow set. If you specify a virtual unit, $GETDVI returns the member device names in the shadow set. If you specify the name of a device that is neither a virtual unit nor a shadow set member, $GETDVI returns a null string.

To obtain the device names of all members of a shadow set, you must make a series of calls to $GETDVI. In your first call to $GETDVI, you can specify either the virtual unit that represents the shadow set or the device name of a member of the shadow set.

5.6.2.1 Virtual Unit Names

If your first call specifies the name of the virtual unit, the item list should contain a DVI$_SHDW_NEXT_MBR_NAME item descriptor into which $GETDVI returns the name of the lowest-numbered member of the shadow set. The devnam argument of the next call to $GETDVI should specify the device name returned in the previous call's DVI$_SHDW_NEXT_MBR_NAME item descriptor. This second call's item list should contain a DVI$_SHDW_NEXT_MBR_NAME item descriptor to receive the name of the next-highest-numbered unit in the shadow set. You should repeat these calls to $GETDVI until $GETDVI returns a null string, which means that there are no more members in the shadow set.

5.6.2.2 Shadow Set Member Names

If your first call specifies the device name of a shadow set member, you must determine the name of the virtual unit that represents the shadow set before you can obtain the device names of all members contained in the shadow set. Therefore, if your first call specifies a member, it should also specify an item list that contains a DVI$_SHDW_MASTER_NAME item descriptor. $GETDVI returns to this descriptor the name of the virtual unit that represents the shadow set. You can now make the series of calls to $GETDVI described in Section 5.6.2.1. The devnam argument of each call specifies the name of the device returned in the previous call's DVI$_SHDW_NEXT_MBR_NAME item descriptor. You repeat these calls until $GETDVI returns a null string, indicating that there are no more members in the shadow set.

Volume shadowing performs four basic functions. The two most important, as with any disk I/O subsystem, are to satisfy read and write requests. The other two functions, copy and merge, are required for shadow set maintenance.

Copy and merge operations are the cornerstone of achieving data availability. Under certain circumstances, Volume Shadowing for OpenVMS must perform a copy or a merge operation to ensure that corresponding LBNs on all shadow set members contain the same information. Although volume shadowing automatically performs these operations, this chapter provides an overview of their operation.

Copy and merge operations occur at the same time that applications and user processes read and write to active shadow set members, thereby having a minimal effect on current application processing.

6.1 Shadow Set Consistency

During the life of a shadow set, the state of any shadow set member relative to the rest of the members of the shadow set can vary. The shadow set is considered to be in a steady state when all of its members are known to contain identical data. Changes in the composition of the shadow set are inevitable because:

• Disk drives occasionally need corrective maintenance.
• New disks are added to replace other disks.
• System failures occur, requiring merge operations to take place within the shadow set.
• Controllers fail, requiring maintenance.
• System management functions, such as backup, are required.

For example, suppose an operator dismounts a member of a shadow set and then remounts the member back into the shadow set. During the member's absence, the remaining members of the shadow set may have experienced write operations. Thus, the information on the member being remounted into the shadow set will differ from the information on the rest of the shadow set. Therefore, a copy (or minicopy) operation is required.

As another example, consider a situation where a shadow set is mounted by several systems in an OpenVMS Cluster configuration. If one of those systems fails, the data on the members of the shadow set may differ because of outstanding or incomplete write operations issued by the failed system. The shadowing software resolves this situation by performing a merge operation.

In any event, copy and merge operations allow volume shadowing to preserve the consistency of the data written to the shadow set. A shadow set is considered to be in a transient state when one or more of its members are undergoing a copy or a merge operation.

Additionally, volume shadowing maintains shadow set consistency by:

• Maintaining consistent data on shadow set members by automatically detecting and replacing bad blocks on one shadow set member and rewriting those bad blocks with good data from another shadow set member.
• Notifying all nodes when a member is added or removed from a shadow set, and ensuring the shadow set membership is consistent clusterwide.

Volume shadowing uses two internal mechanisms to coordinate shadow set consistency:

• Storage control blocks (SCBs)
  Volume shadowing uses a storage control block (SCB) as a primary method for controlling shadow set membership. Each physical disk contains an SCB in which the shadowing software records the names of all the current members of the shadow set. Each time the composition of the shadow set changes, the SCB on all members is updated. This feature simplifies clusterwide membership coordination and is also used by the MOUNT qualifier /INCLUDE to reconstruct a shadow set.
• Shadow set generation number
  Volume shadowing uses a shadow set generation number as a primary method of determining shadow set member validity and status. A shadow set generation number is an incrementing value that is stored on every member of a shadow set. Each time a membership change occurs to the shadow set (members are mounted, dismounted, or fail), the generation number on the remaining members is incremented. Thus, if a shadow set's generation number is 100 and a member is dismounted from the set, the generation numbers on the remaining members are incremented to 101. The removed member's generation number remains at 100. When mounting shadow sets, the shadowing software uses the generation numbers, found in the SCB on the physical units, to determine the need for and direction of copy operations.

Table 6-1 lists some of the information contained in the SCB.

Table 6-1 Information in the Storage Control Block (SCB)

SCB Information	Function
Volume label	Identifies a unique name for the volume. Every member of a shadow set must use the same volume label.
BACKUP revision number	A BACKUP/IMAGE restoration rearranges the location of data on a volume and sets a revision number to record this change. The Mount utility (MOUNT) checks the revision number of the proposed shadow set member against the numbers on current or other proposed shadow set members. If the revision number differs, the shadowing software determines whether a copy or merge operation is required to bring the data on the less current members up to date.
Volume shadowing generation number	When a member joins a shadow set, it is marked with a volume shadowing generation number. You can zero the generation number by using the /OVERRIDE=SHADOW_MEMBERSHIP qualifier with the MOUNT command.
Mount and dismount status	The SCB mount status field is used as a flag that is set when a volume is mounted and cleared when it is dismounted. There is also a count of the number of nodes that have mounted the shadow set write-enabled. The MOUNT command checks this field when a disk is mounted. If the flag is set, this indicates that the disk volume was incorrectly dismounted. This will occur in the event of system failure. When mounting shadow sets that were incorrectly dismounted, or where the write count field is not correct, the shadowing software automatically initiates merge operations.

Upon receiving a command to mount a shadow set, the volume shadowing software immediately determines whether a copy or a merge operation is required; if either is required, the software automatically performs the operation to reconcile data differences. If you are not sure which disks might be targets of copy operations, you can specify the /CONFIRM or /NOCOPY qualifiers when you use the MOUNT command. To disable performing any copy operations, use the /NOCOPY qualifier. If you mount a shadow set interactively, use the /CONFIRM qualifier to instruct MOUNT to display the targets of copy operations and request permission before the operations are performed.

When you dismount an individual shadow set member, you produce a situation similar to a hardware disk failure. Because files remain open on the virtual unit, the removed physical unit is marked as not being properly dismounted.

After one of the devices is removed from a shadow set, the remaining shadow set members have their generation number incremented, identifying them as being more current than the former shadow set member. This generation number aids in determining the correct copy operation if you remount the member into a shadow set.

	privacy and legal statement
5423PRO_007.HTML