Document revision date: 15 July 2002

1. Enter the SHOW DEVICE command and the physical device name.
2. Device DKA300 has NOFE set indicating that the device cannot support shadowing data repair.

For SCSI devices that support READL and WRITEL operations, SDA displays a Characteristics field that does not contain the NOFE flag, similar to the following example:

SDA> SHOW DEVICE DKA200: I/O data structures ------------------- COLOR$DKA200 Generic_DK UCB address: 806EEAF0 Device status: 00021810 online,valid,unload,lcl_valid Characteristics: 1C4D4008 dir,fod,shr,avl,mnt,elg,idv,odv,rnd 01010281 clu,srv,nnm,scsi

The Characteristics field does not show a NOFE bit set; therefore, device DKA200 can support shadowing data repair.

4.9.5 Obtaining Shadow Set Information With F$GETDVI

The F$GETDVI lexical function provides another method for obtaining information about devices mounted in shadow sets. Using F$GETDVI, you can obtain general device and volume information and specific information about the shadow set status of the device or volume. For example, you can determine the following types of information:

• Whether a device is a shadow set virtual unit or a shadow set member
• Whether a copy operation is in progress on a device
• What type of copy operation is in progress on a device
• 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

You can use the F$GETDVI lexical function interactively at the DCL command level or in a DCL command procedure. You can also use the $GETDVI system service with volume shadowing (see Section 5.6).

The format for the F$GETDVI lexical function is as follows:

F$GETDVI (device-name,item)

You supply two arguments to the F$GETDVI lexical function: a physical device name and the name of an item that specifies the type of information you want to obtain.

The OpenVMS DCL Dictionary contains a large list of item codes that you can supply as an argument to F$GETDVI. Table 4-4 lists the items specific to volume shadowing that you can supply as arguments to the F$GETDVI lexical function. The table lists the type of information returned by each item and the data types of the return values.

Table 4-4 F$GETDVI Item Codes for Volume Shadowing

Item	Return Type	Information Returned
SHDW_CATCHUP_COPYING	String	Returns TRUE or FALSE to indicate whether the device is a member that is the target of a copy operation.
SHDW_MASTER	String	Returns TRUE or FALSE to indicate whether the device is a virtual unit.
SHDW_MASTER_NAME	String	Returns the name of the virtual unit that represents the shadow set of which the specified device is a member. F$GETDVI returns a null string if the specified device is not a member or is, itself, a virtual unit.
SHDW_MEMBER	String	Returns TRUE or FALSE to indicate whether the device is a shadow set member.
SHDW_MERGE_COPYING	String	Returns TRUE or FALSE to indicate whether the device is a member that is a merge member of the shadow set.
SHDW_NEXT_MBR_NAME	String	Returns the device name of the next member in the shadow set. If you specify a virtual unit, F$GETDVI returns the device name of a member of the shadow set. If you specify the name of a shadow set member with the device name and item arguments, F$GETDVI returns the name of the "next" member or a null string if there are no more members. To determine all the members of a shadow set, first specify the virtual unit to F$GETDVI; on subsequent calls, specify the member name returned by the previous F$GETDVI call until it has finished, when it returns a null member name.

Example

To check a device for possible shadow set membership, you could include the following DCL command in a command procedure:

$ IF F$GETDVI("WRKD$:","SHDW_MEMBER") THEN GOTO SHADOW_MEMBER

If WRKD$ (a logical name for a disk) is a shadow set member, then F$GETDVI returns the string TRUE and directs the procedure to the volume labeled SHADOW_MEMBER.

See the OpenVMS DCL Dictionary for additional information about the F$GETDVI lexical function.

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$_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_MINICOPY_REQUIRED means that $MOUNT fails if minicopy has not been enabled on the disk. MNT$M_MINICOPY_OPTIONAL means that $MOUNT continues even if minicopy has not been enabled on the disk. 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. MNT$M_REQUIRE_MEMBERS controls whether every physical device specified with the /SHADOW qualifier must be accessible when the MOUNT command is issued in order for the $MOUNT system service to take effect. MNT$M_VERIFY_LABELS requires that any member to be added to the shadow set have a volume label of SCRATCH_DISK. This helps ensure that the wrong disk is not added to a shadow set. If you plan to use VERIFY_LABELS, you must assign the disk a label first. You can do this either by initializing the disk to be added to the set with the label SCRATCH_DISK or by specifying a label for the disk with the SET VOLUME/LABEL command. The default is NOVERIFY_LABEL, which means that the volume label of the copy targets will not be checked. This default behavior is the same that occurred prior to the introduction of this option.
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.

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
• 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.

	privacy and legal statement
5423PRO_007.HTML