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:
|
|
|
For a complete description of the $GETDVI and $GETDVIW services and their arguments, see the HP OpenVMS System Services Reference Manual.
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. |
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.
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.
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.