[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

Volume Shadowing for OpenVMS


Previous Contents Index


Chapter 5
Managing Shadow Sets with System Services

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 for Adding 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:

5.3 Using $MOUNT to Mount Volume Sets

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 for Creating and Mounting 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$.

5.4 Using $DISMOU to Dismount Shadow Sets

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

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.

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:

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:

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.

Note

If you use the file-system-related item codes with the $GETDVI system service to obtain meaningful system information (such as FREEBLOCK information) for a shadow set, you should specify the virtual unit name with the $GETDVI service. If you specify the device name of one of the shadow set members, the $GETDVI service returns a value of 0.

5.6.1 $GETDVI Shadow Set Item Codes

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.


1Because shadow set device names can include up to 64 characters, the buffer length field of this item descriptor should specify 64 (bytes).


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
5423PRO_005.HTML