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