HP OpenVMS Systems Documentation

Volume Shadowing for OpenVMS

4.9.4 Displaying Shadow Set Information With SDA

The System Dump Analyzer (SDA) is a utility provided with the OpenVMS operating system. Although the main function of SDA is for crash dump analysis, it is also a useful tool for examining a running system, including the shadow sets. You can also use SDA to determine whether or not a third-party SCSI device supports the shadowing data repair (disk bad block errors) capability.An example is included in Section 4.9.4.1.

The SDA command SHOW DEVICE displays information from the system data structures that describe the devices in the system configuration. To examine a shadow set, first enter ANALYZE/SYSTEM at the DCL prompt to invoke the System Dump Analyzer. Then at the SDA> prompt, enter the SHOW DEVICE command followed by the virtual unit name.

The following example shows how to obtain information about the shadow set represented by the virtual unit DSA80. Compare the SDA output in the following example with the DCL SHOW DEVICE output shown in the last example in Section 4.9.3.

$ ANALYZE/SYSTEM
VAX/VMS System analyzer
SDA> SHOW DEVICE DSA80
I/O data structures
-------------------
DSA80                                   HSJ00              UCB address:  810B7F50
Device status:   00021810 online,valid,unload,lcl_valid
Characteristics: 1C4D4008 dir,fod,shr,avl,mnt,elg,idv,odv,rnd
                 00082021 clu,mscp,loc,vrt
Owner UIC [004000,000015]   Operation count        138   ORB address    810B8080
      PID        00000000   Error count              0   DDB address    813F49F0
Alloc. lock ID   009C2595   Reference count          1   DDT address    810BEBB8
Alloc. class            0   Online count             1   VCB address    810BE3F0
Class/Type          01/15   BOFF                  0000   CRB address    8129EB10
Def. buf. size        512   Byte count            0200   PDT address    810121A0
DEVDEPEND        04E00E33   SVAPTE            81FDE55C   CDDB address   813F4360
DEVDEPND2        00000000   DEVSTS                0004   SHAD address   8111D460
FLCK index             34   RWAITCNT              0000   I/O wait queue    empty
DLCK address     00000000
Shadow Device status:   0004 nocnvrt
  ----- Shadow Descriptor Block (SHAD) 8111D460 -----
Virtual Unit status:              0041 normal,merging
Members                2    Act user IRPs          0    VU UCB          810B7F50
Devices                2    SCB LBN         0006CC63    Write log addr  00000000
Fcpy Targets           0    Generation Num  28D47C20    Master FL          empty
Mcpy Targets           2                    00935BC7    Restart FL         empty
Last Read Index        1    Virtual Unit Id 00000000
Master Index           0                    12610050
     ----- SHAD Device summary for Virtual Unit  DSA80  -----
Device $255$DUA56
 Index 0 Device Status    A6 merge,cip,src,valid
 UCB 810510D0     VCB 81400A00      Unit Id. 12A10038 000000FF
 Merge LBN 0004B94D
Device $255$DUA58
 Index 1 Device Status    A6 merge,cip,src,valid
 UCB 81051260     VCB 81439800      Unit Id. 12A1003A 000000FF
 Merge LBN 0004B94D
SDA> exit

The SDA utility's SHOW DEVICE command first displays device characteristics of the DSA80 virtual unit and the addresses of data structures. SDA then displays the DSA80 virtual unit status and the status of the individual shadow set members. Notice how the device status for each member reflects that the unit is in a merge state. For example, $255$DUA56 is shown with the following device status:

Device $255$DUA56
 Index 0 Device Status    A6 merge (1), cip (2), src (3), valid (4)
 UCB 810510D0     VCB 81400A00      Unit Id. 12A10038 000000FF
 Merge LBN 0004B94D

This information translates to the following:

merge---$255$DUA56 is marked for a merge operation.
cip---Copy in progress. In this example, a merge operation is in progress.
src---$255$DUA56 is considered a source member for the read operations.
valid---The SCB information on $255$DUA56 is considered valid.

Notice also how both devices $255$DUA56 and $255$DUA58 show that, at the time the SDA took this "snapshot" of the shadow set, the merge operation is merging at LBN 0004B94D.

The following example shows an SDA display of the same shadow set when $255$DUA56 is a merge member and $255$DUA58 is the recipient of a copy operation. A shadow set can be in this merge/copy state when a node that has the shadow set mounted crashes while a member in the shadow set is undergoing a copy operation. Volume shadowing automatically marks the member undergoing the copy operation so that it receives a merge operation after the copy operation completes. This ensures consistency across the shadow set.

The example first shows output for one shadow set member, using the DCL command SHOW DEVICE $255$DUA58; then the example shows the output for the entire shadow set, using the SDA command SHOW DEVICE DSA80. (SDA is invoked by the ANALYZE/SYSTEM command.)

$ SHOW DEVICE $255$DUA58
Device                  Device           Error    Volume         Free  Trans Mnt
 Name                   Status           Count     Label        Blocks Count Cnt
DSA80:                  Mounted              0  SHADTEST1       890937     1   3

$255$DUA56:   (SHASTA)  ShadowMergeMbr       0  (merging DSA80:   0% merged)
$255$DUA58:   (SHASTA)  ShadowCopying        0  (copy trgt DSA80: 9% copied )

$ ANALYZE/SYSTEM
VAX/VMS System analyzer
SDA> SHOW DEVICE DSA80
I/O data structures
-------------------
DSA80                                   RA81              UCB address:  810B7F50
Device status:   00021810 online,valid,unload,lcl_valid
Characteristics: 1C4D4008 dir,fod,shr,avl,mnt,elg,idv,odv,rnd
                 00082021 clu,mscp,loc,vrt
Owner UIC [004000,000015]   Operation count        130   ORB address    810B8080
      PID        00000000   Error count              0   DDB address    813F49F0
Alloc. lock ID   009C2595   Reference count          1   DDT address    810BEBB8
Alloc. class            0   Online count             1   VCB address    810BE3F0
Class/Type          01/15   BOFF                  0000   CRB address    8129EB10
Def. buf. size        512   Byte count            0000   PDT address    810121A0
DEVDEPEND        04E00E33   SVAPTE            00000000   CDDB address   813F4360
DEVDEPND2        00000000   DEVSTS                0004   SHAD address   8111D460
FLCK index             34   RWAITCNT              0000   I/O wait queue    empty
DLCK address     00000000
Shadow Device status:   0004 nocnvrt
  ----- Shadow Descriptor Block (SHAD) 8111D460 -----
Virtual Unit status:              0061 normal,copying,merging
Members                1    Act user IRPs          0    VU UCB          810B7F50
Devices                2    SCB LBN         0006CC63    Master FL         empty
Fcpy Targets           1    Generation Num  7B7BE060    Restart FL         empty
Mcpy Targets           0                    00935BC4
Last Read Index        0    Virtual Unit Id 00000000
Master Index           0                    12610050
     ----- SHAD Device summary for Virtual Unit  DSA80  -----
Device $255$DUA56
 Index 0 Device Status    A2 merge,src,valid
 UCB 810510D0     VCB 81400A00      Unit Id. 12A10038 000000FF
 Merge LBN FFFFFFFF
Device $255$DUA58
 Index 1 Device Status    87 fcpy,merge,cip,valid
 UCB 81051260     VCB 81439800      Unit Id. 12A1003A 000000FF
 Copy LBN 00033671

In this example, in the SHAD Device summary for Virtual Unit DSA80 display, the device status ( fcpy ) for $255$DUA58 shows that it is the target of a full copy operation. The source of the operation is $255$DUA56; notice that the Merge LBN line for $255$DUA56 shows a series of Fs ( FFFFFFFF ). This notation indicates that a merge operation must be done after the copy operation completes. The Copy LBN line for the target disk $255$DUA58 shows that the copy operation is currently copying at LBN 00033671.

4.9.4.1 Using SDA to Obtain Information About Third-Party SCSI Devices

When you mount a SCSI disk, the SCSI disk class driver, DKDRIVER, checks the device-specific parameters to see whether the disk supports READL/WRITEL commands.

If a SCSI disk does not support READL and WRITEL commands, DKDRIVER sets a NOFE (no forced error) bit to indicate that the disk cannot support the shadowing data repair (disk bad block errors) capability. You can use the SDA command SHOW DEVICE to check for the NOFE flag in the Characteristics field of the SDA display.

$ ANALYZE/SYSTEM
SDA> SHOW DEVICE DKA300:(1)
I/O data structures
-------------------
COLOR$DKA300              Generic_DK        UCB address:  80A665E0

Device status:   00000010 online
Characteristics: 1C454008 dir,fod,shr,avl,elg,idv,odv,rnd
                 05010281 clu,srv,nnm,scsi,nofe(2)
   .
   .
   .

Enter the SHOW DEVICE command and the physical device name.
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.

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.

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.

Chapter 5
Creating and 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:

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.
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.
The member item descriptors are followed by an item descriptor that specifies MYVOLUME as the volume label for the shadow set.
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.

Contents

Index