HP Volume Shadowing for OpenVMS: OpenVMS Version 8.4 > Chapter 5 Creating and Managing Shadow Sets with System Services

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

$GETDVI Shadow Set Item Codes

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

Table 5-2 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_COPIER_NODE

Returns the name of the node that is actively performing either the copy or the merge operation, as a string

DVI$_SHDW_DEVICE_COUNT

Returns the total number of devices in the virtual unit, including devices being added as copy targets, as a longword

DVI$_SHDW_GENERATION

Returns the current, internal revision number of the virtual unit, as a quadword.

DVI$_SHDW_MASTER

Returns a Boolean longword. The value 1 indicates that the device is a virtual unit.

DVI$_SHDW_MASTER_MBR

Returns the name of the master member unit that is used for merge and copy repair operations and for shadow set recovery operations, as a string.

DVI$_SHDW_MASTER_NAME

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.

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

If you specify a virtual unit or a device that is not a shadow set member, $GETDVI returns a null string.

DVI$_SHDW_MBR_COPY_DONE

Returns the percentage of the copy operation that is complete on the current member unit, as a longword.

DVI$_SHDW_MBR_COUNT

Returns the number of full source members in the virtual unit, as a longword. Devices added as copy targets are not full source members.
DVI$_SHDW_MBR_MERGE_DONE

Returns the percentage of the merge operation that has been completed on the member, as a longword.

DVI$_SHDW_MBR_READ_COST

Returns the current value set for the member unit, as a longword. This value can be modified to use a customer-specified value.

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_MINIMERGE_ENABLE

Returns a longword interpreted as a Boolean. A value of TRUE indicates that the virtual unit undergoes a minimerge, not a full merge, if a system in the cluster fails.

DVI$_SHDW_NEXT_MBR_NAME

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.

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

DVI$_SHDW_READ_SOURCE

Returns the name of the member unit that is used for reads, at this point in time, as a longword. DVI$_SHDW_READ_SOURCE uses the unit that has the lowest value of the sum of its queue length and read cost for reads. This is a dynamic value.

DVI$_SHDW_SITE

Returns as a longword the site value for the specified value. This value is set by the SET DEVICE or SET SHADOW command.

DVI$_SHDW_TIMEOUT

Returns the customer-specified timeout value set for the device, as a long word. If you do not set a value by way of the SETSHOWSHADOW utility, the SYSGEN parameter SHADOW_MBR_TWO is used for member units and MVTIMEOUT is used for virtual units.

 

Obtaining the Device Names of Shadow Set Members

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.

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.

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 “Virtual Unit Names”. 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.