Document revision date: 19 July 1999

This chapter describes how to create, mount, dismount, and dissolve shadow sets using the $MOUNT and $DISMOU system services. It also describes how to use the $GETDVI system service to access current information about the state of shadow sets. For complete information about these OpenVMS system services, see the OpenVMS System Services Reference Manual.

5.1 Using $MOUNT to Create and Mount Shadow Sets

You can create and mount shadow sets using the $MOUNT system service in a user-written program. Program calls to $MOUNT that create, mount, or add devices to shadow sets use the same syntax. To direct the system to perform any mount operation, you construct a $MOUNT item list. The item list specifies the virtual unit that represents the shadow set and the members (physical devices) that the shadow set contains.

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

SYS$MOUNT itmlst

Example 5-1 illustrates MACRO-32 statements that produce a $MOUNT system service item list to create and mount a shadow set.

Example 5-1 Item List to Create and Mount a Shadow Set

DSA23: .ASCID /DSA23:/ MEMBER001: .ASCID /$4$DUA9:/ MEMBER002: .ASCID /$4$DUA5:/ VOLUME_LABEL: .ASCID /MYVOLUME/ VOLUME_LOGNM: .ASCID /DISK$MYVOLUME/ .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, MEMBER001 (2) .ITEM 8, MNT$_SHAMEM, MEMBER002 .ITEM 8, MNT$_VOLNAM, VOLUME_LABEL (3) .ITEM 13, MNT$_LOGNAM, VOLUME_LOGNM (4) .LONG 0

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

1. Notice that the virtual unit item descriptor occurs first. This item descriptor specifies DSA23 as the name of the virtual unit. See Section 4.2 for the proper naming syntax for the virtual unit and shadow set members.
2. The virtual unit item descriptor is followed by two member-unit item descriptors. Because Volume Shadowing for OpenVMS automatically determines the type of operation (copy or merge) necessary before disks can join a shadow set, all of the devices are mounted with MNT$_SHAMEM item descriptors. These item descriptors specify that the physical devices, $4$DUA9 and $4$DUA5, are to join the shadow set represented by DSA23.
3. The member item descriptors are followed by an item descriptor that specifies MYVOLUME as the volume label for the shadow set.
4. The last item descriptor specifies DISK$MYVOLUME as the logical name for the shadow set.

Later, if you want to add another device to the shadow set, you make another call to $MOUNT that specifies an item list that contains the name of the virtual unit and the name of the device you want to add to the shadow set. Example 5-2 shows how to add the physical device $4$DUA10: to the shadow set created in Example 5-1.

Example 5-2 Item List to Add a Member to a Shadow Set

DSA23: .ASCID /DSA23:/ MEMBER003: .ASCID /$4$DUA10:/ VOLUME_LABEL: .ASCID /MYVOLUME/ VOLUME_LOGNM: .ASCID /DISK$MYVOLUME/ .MACRO .ITEM, SIZE, CODE, BUFFER, RETURN=0 .WORD SIZE, CODE .ADDRESS BUFFER, RETURN .ENDM .ITEM ITMLST: .ITEM 6, MNT$_SHANAM, DSA23 .ITEM 9, MNT$_SHAMEM, MEMBER003 .ITEM 8, MNT$_VOLNAM, VOLUME_LABEL .ITEM 13, MNT$_LOGNAM, VOLUME_LOGNM .LONG 0

Section 5.2 briefly describes the $MOUNT shadow set item codes and discusses how to construct a valid $MOUNT item list. For a complete description of the $MOUNT service and all its item codes, refer to the OpenVMS System Services Reference Manual.

5.2 $MOUNT Shadow Set Item Codes

This section briefly describes the SYS$MOUNT item codes that are useful for shadow set management. Refer to the OpenVMS System Services Reference Manual for complete information about SYS$MOUNT, item codes, and other system services.

Table 5-1 describes the $MOUNT shadow set item codes.

Table 5-1 SYS$MOUNT Item Codes

Item Code	Function
MNT$_SHANAM	Specifies the name of the virtual unit to be mounted. The buffer is a 1- to 64-character string containing the virtual unit name in the format DSA n:. This string can also be a logical name; if it is a logical name, it must translate to a virtual unit name. An item list must include at least one MNT$_SHANAM item descriptor. If you are mounting a volume set containing more than one shadow set, you must include one MNT$_SHANAM item descriptor for each virtual unit included in the volume set.
MNT$_SHAMEM	Specifies the name of a physical device to be mounted into a shadow set. The shadowing software adds the device to the shadow set represented by the virtual unit specified in the MNT$_SHANAM item descriptor. The MNT$_SHAMEM descriptor is a 1- to 64-character string containing the device name. The string can be a physical device name or a logical name; if it is a logical name, it must translate to a physical device name. An item list must contain at least one item descriptor specifying a member; this item descriptor must appear after the MNT$_SHANAM item descriptor.
MNT$_FLAGS	Specifies a longword bit vector in which each bit specifies an option for the mount operation. The buffer must contain a longword, which is the bit vector. The $MNTDEF macro defines symbolic names for each option (bit) in the bit vector. You construct the bit vector by specifying the symbolic names for the desired options in a logical OR operation. The following list describes the symbolic names for each shadow set option: MNT$M_INCLUDE automatically reconstructs a shadow set to the state it was in before the shadow set was dissolved (because of dismounting or system failure). Use this option when mounting a complete shadow set. MNT$M_NOCOPY disables automatic copy operations on all physical devices being mounted or added to a shadow set. This option prevents accidental loss of data that could occur if an unintended device is added to the shadow set. MNT$M_OVR_SHAMEM allows you to mount former shadow set members outside of the shadow set. If you do not specify this option, $MOUNT automatically mounts the volume write-locked to prevent accidental deletion of data. To specify this option, you must either own the volume or have the VOLPRO privilege. When you use this option, the shadow set generation number is erased from the volume. If you then remount the volume in the former shadow set, $MOUNT considers it an unrelated volume and marks it for a copy operation.

Here are some important things to remember when you construct a $MOUNT item list:

• Every item list that mounts a shadow set must contain at least one item descriptor that specifies the virtual unit and at least one item descriptor that specifies a member.
• The item descriptor that specifies the virtual unit must come before the item descriptors that specify the members contained in the shadow set. Then, you can specify any number of members that are to be represented by that virtual unit by using the MNT$_SHAMEM item code.
• When mounting a volume set, your item list must contain an item descriptor for each virtual unit. The virtual unit item descriptor must be followed by item descriptors specifying the members to be represented by that virtual unit.
• When you mount a shadow set, the system determines whether a device requires a copy or merge operation before it can join the shadow set. Therefore, you can use the MNT$_SHAMEM item code to specify any member, regardless of the operation the device requires.

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
• 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 Member Units 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, there is no longer any meaningful relationship between the virtual unit and the shadow set members, or among the shadow set members.

• 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_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 member units
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 B 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 name of the virtual unit that represents the shadow set of which the specified device 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.

	privacy and legal statement
5423PRO_005.HTML