skip book previous and next navigation links
go up to top of book: HP Volume Shadowing for OpenVMS HP Volume Shadowing for OpenVMS
go to beginning of chapter: Creating and Managing Shadow Sets with System... Creating and Managing Shadow Sets with System...
go to previous page: Evaluating Condition Values Returned by $DISMOU and $MOUNT Evaluating Condition Values Returned by $DISMOU and $MOUNT
go to next page: Ensuring Shadow Set ConsistencyEnsuring Shadow Set Consistency
end of book navigation links

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, refer to the HP OpenVMS System Services Reference Manual.


NoteIf 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  

SYS$GETDVI Item Codes lists the information returned by the $GETDVI shadow set item codes.

Table 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 will undergo 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.


go to previous page: Evaluating Condition Values Returned by $DISMOU and $MOUNT Evaluating Condition Values Returned by $DISMOU and $MOUNT
go to next page: Ensuring Shadow Set ConsistencyEnsuring Shadow Set Consistency