 |
HP OpenVMS System Services Reference Manual
HP OpenVMS System Services Reference Manual
On Alpha and I64, this item code can be used with the PATHNAME
parameter. If the PATHNAME parameter is omitted, the summation of the
operation counts for all paths in a multipath device is returned (which
was the behavior prior to the introduction of the PATHNAME parameter).
If the PATHNAME parameter is specified, only the operation count for
that path is returned.
DVI$_OWNUIC
Returns the user identification code (UIC) of the owner of the device
as a standard 4-byte UIC.
DVI$_PATH_AVAILABLE
On Alpha and I64, returns an unsigned longword, interpreted as Boolean.
A value of 1 indicates the specified path is available.
This item code is usually used with the PATHNAME parameter. If the
PATHNAME parameter is omitted, information about the current path of
the multipath device is returned.
DVI$_PATH_NOT_RESPONDING
On Alpha and I64, returns an unsigned longword, interpreted as Boolean.
A value of 1 indicates the specified path is marked as not responding.
This item code is usually used with the PATHNAME parameter. If the
PATHNAME parameter is omitted, information about the current path of
the multipath device is returned.
DVI$_PATH_POLL_ENABLED
On Alpha and I64, returns an unsigned longword, interpreted as Boolean.
A value of 1 indicates that the specified path is enabled for multipath
polling.
This item code is usually used with the PATHNAME parameter. If the
PATHNAME parameter is omitted, information about the current path of
the multipath device is returned.
DVI$_PATH_SWITCH_FROM_TIME
On Alpha and I64, returns the time from which this path was switched,
either manually or automatically. Because the returned time is in the
standard 64-bit absolute time format, the buffer length field in the
item descriptor should specify 8 (bytes).
This item code is usually used with the PATHNAME parameter. If the
PATHNAME parameter is omitted, information about the current path of
the multipath device is returned.
DVI$_PATH_SWITCH_TO_TIME
On Alpha and I64, returns the time to which this path was switched,
either manually or automatically. Because the returned time is in the
standard 64-bit absolute time format, the buffer length field in the
item descriptor should specify 8 (bytes).
This item code is usually used with the PATHNAME parameter. If the
PATHNAME parameter is omitted, information about the current path of
the multipath device is returned.
DVI$_PATH_USER_DISABLED
On Alpha and I64, returns an unsigned longword, interpreted as Boolean.
A value of 1 indicates the specified path has been disabled using the
$SET DEVICE /PATH /NOENABLE command.
This item code is usually used with the PATHNAME parameter. If the
PATHNAME parameter is omitted, information about the current path of
the multipath device is returned.
DVI$_PID
Returns the process identification (PID) of the owner of the device as
an unsigned integer longword.
DVI$_PREFERRED_CPU
The return argument is a 32-bit CPU bit mask with a bit set indicating
the preferred CPU. A return argument containing a bit mask of zero
indicates that no preferred CPU exists, either because Fast Path is
disabled or the device is not a Fast Path capable device. The return
argument serves as a CPU bit mask input argument to the
$PROCESS_AFFINITY system service. The argument can be used to assign an
application process to the optimal preferred CPU.
DVI$_PROT_SUBSYSTEM_ENABLED
On Alpha and I64, returns an unsigned longword, which is interpreted as
Boolean. A value of 1 indicates the volume is mounted with protected
subsystems enabled.
DVI$_RECSIZ
Returns the blocked record size as an unsigned integer longword.
DVI$_REFCNT
Returns the number of channels assigned to the device as an unsigned
integer longword.
DVI$_REMOTE_DEVICE
Returns a longword, which is interpreted as Boolean. A value of 1
indicates that the device is a remote device; a value of 0 indicates
that it is not a remote device. A remote device is a device that is not
directly connected to the local node, but instead is visible through
the OpenVMS Cluster system.
DVI$_ROOTDEVNAM
Returns the device name of the root volume in the volume set as a
64-byte, zero-filled string. This item code is applicable only to disks.
DVI$_SCSI_DEVICE_FIRMWARE_REV
On Alpha and I64, returns as a four-character string the firmware
revision of a SCSI disk or SCSI tape. This item code is valid only for
SCSI disks and SCSI tapes; a null string is returned for any other
device.
DVI$_SECTORS
Returns the number of sectors per track as an unsigned integer
longword. This item code is applicable only to disks.
DVI$_SERIALNUM
Returns the serial number of the volume as an unsigned integer
longword. This item code is applicable only to disks.
DVI$_SERVED_DEVICE
Returns a longword, which is interpreted as Boolean. A value of 1
indicates that the device is a served device; a value of 0 indicates
that it is not a served device. A served device is one whose local node
makes it available to other nodes in the OpenVMS Cluster system.
DVI$_SHDW_CATCHUP_COPYING
Returns a longword, which is interpreted as Boolean. The value 1
indicates that the device is the target of a full copy operation.
DVI$_SHDW_COPIER_NODE
On Alpha and I64, returns the name of the node that is actively
performing either the copy or the merge operation, as a string.
DVI$_SHDW_DEVICE_COUNT
On Alpha and I64, returns the total number of devices in the virtual
unit, including devices being added as copy targets, as a longword.
DVI$_SHDW_GENERATION
On Alpha and I64, returns the current, internal revision number of the
virtual unit, as a quadword.
DVI$_SHDW_MASTER
Returns a longword, which is interpreted as Boolean. The value 1
indicates that the device is a virtual unit named DSAnnnn:.
DVI$_SHDW_MASTER_MBR
On Alpha and I64, 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
device name of the virtual unit (DSAnnnn:) that represents the shadow
set of which the specified device is a member. $GETDVI returns a null
string if the specified device is not a member or is itself a virtual
unit (DSAnnnn:).
Note
Shadow set members must have a nonzero allocation class to operate in
an OpenVMS Cluster system. Refer to HP Volume Shadowing for OpenVMS for more information.
|
Because the shadow set virtual unit name can include up to 64
characters, the buffer length field of the item descriptor should
specify 64 (bytes).
DVI$_SHDW_MBR_COPY_DONE
On Alpha and I64, returns the percentage of the copy operation that is
complete on the current member unit, as a longword.
DVI$_SHDW_MBR_COUNT
On Alpha and I64, 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
On Alpha and I64, returns the percentage of the merge operation that
has been completed on the member, as a longword.
DVI$_SHDW_MBR_READ_COST
On Alpha and I64, 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 longword, which is interpreted as Boolean. The value 1
indicates that the device is a shadow set member.
DVI$_SHDW_MERGE_COPYING
On Alpha and I64, returns a longword, which is interpreted as Boolean.
The value 1 indicates that the device is a merge member of the shadow
set.
DVI$_SHDW_MINIMERGE_ENABLE
On Alpha and I64, returns a longword, which is interpreted as Boolean.
The value 1 indicates that the virtual unit will undergo a mini-merge
and not a full merge, if a system in the cluster crashes.
DVI$_SHDW_NEXT_MBR_NAME
Returns the device name of the next member in the shadow set. If you
specify a virtual unit with the chan or
devnam argument, DVI$_SHDW_NEXT_MBR_NAME returns the
device name of a member of a shadow set. If you specify the name of a
shadow set member unit with the chan or
devnam argument, DVI$_SHDW_NEXT_MBR_NAME returns the
name of the next member unit or a null string if there are no more
members.
To determine all the members of a shadow set, first specify the virtual
unit (DSAnnnn:) to $GETDVI. Then, on subsequent calls, specify the
member name returned by the previous $GETDVI call until it returns a
null member name.
When the shadow set members have a nonzero allocation class, the device
name returned by $GETDVI contains the allocation class; the name has
the form $allocation-class$device. For example, if a shadow
set has an allocation class of 255 and the device name is DUA42,
$GETDVI returns the string $255$DUA42.
Note
Shadow set members must have a nonzero allocation class to operate in
an OpenVMS Cluster system. Refer to HP Volume Shadowing for OpenVMS for more information.
|
Because a device name can include up to 64 characters, the buffer
length field of the item descriptor should specify 64 (bytes).
DVI$_SHDW_READ_SOURCE
On Alpha and I64, 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_TIMEOUT
On Alpha and I64, returns the customer-specified timeout value set for
the device, as a long word.
If you do not set a value using the SETSHOWSHADOW utility, the SYSGEN
parameter SHADOW_MBR_TWO is used for member units and MVTIMEOUT is used
for virtual units.
DVI$_STS
Returns the device unit status as a 4-byte bit vector. Each bit in the
vector, when set, corresponds to a symbolic name that is defined by the
$UCBDEF macro. The following table describes each name:
| Symbol |
Description |
|
UCB$V_ALTBSY
|
Unit is busy via alternate startio path.
|
|
UCB$V_BSY
|
Unit is busy.
|
|
UCB$V_CANCEL
|
I/O on unit is canceled.
|
|
UCB$V_CLUTRAN
|
OpenVMS Cluster state transition in progress.
|
|
UCB$V_DEADMO
|
Deallocate at dismount.
|
|
UCB$V_DELETEUCB
|
Delete this UCB when reference count equals 0.
|
|
UCB$V_DISMOUNT
|
Dismount in progress.
|
|
UCB$V_ERLOGIP
|
Error log is in progress on unit.
|
|
UCB$V_EXFUNC_SUPP
|
Unit supports the EXFUNC bit.
|
|
UCB$V_FAST_PATH
|
Unit supports FAST PATH Affinity.
|
|
UCB$V_FP_HWINT
|
Unit supports FAST PATH hardware interrupt CPU Affinity.
|
|
UCB$V_INT
|
Interrupt is expected.
|
|
UCB$V_INTTYPE
|
Receiver interrupt.
|
|
UCB$V_IOPOST_LOCAL
|
Unit supports I/O post processing on the current CPU.
|
|
UCB$V_LCL_VALID
|
Volume is valid on the local node.
|
|
UCB$V_MNTVERIP
|
Mount verification is in progress.
|
|
UCB$V_MOUNTING
|
Device is being mounted.
|
|
UCB$V_MNTVERPND
|
Mount verification is pending on busy device.
|
|
UCB$V_NO_ASSIGN
|
Unit cannot have channels assigned to it.
|
|
UCB$V_ONLINE
|
Unit is on line.
|
|
UCB$V_PATHVERIP
|
Path verification is in progress for this device.
|
|
UCB$V_POWER
|
Power failed while unit busy.
|
|
UCB$V_SNAPSHOT
|
Restart validation is in progress.
|
|
UCB$V_SUPMVMSG
|
If set, suppress success type mount version messages.
|
|
UCB$V_SVPN_END
|
Last byte used from page mapped by system virtual page number (SVPN).
|
|
UCB$V_TEMPLATE
|
Template UCB from which other UCBs for this device type are made.
|
|
UCB$V_TIM
|
Timeout is enabled.
|
|
UCB$V_TIMOUT
|
Unit timed out.
|
|
UCB$V_UNLOAD
|
Unload volume at dismount.
|
|
UCB$V_VALID
|
Volume is software valid.
|
|
UCB$V_WRONGVOL
|
Wrong volume detected during mount verification.
|
|
UCB$V_WRTLOCKMV
|
Write-locked mount verification in progress.
|
DVI$_TOTAL_PATH_COUNT
On Alpha and I64, returns as an unsigned longword the number of paths
for a multipath-capable device.
DVI$_TRACKS
Returns the number of tracks per cylinder as an unsigned integer
longword. This item code is applicable only to disks.
DVI$_TRANSCNT
Returns the transaction count for the volume as an unsigned integer
longword.
DVI$_QLEN
On Alpha and I64, returns the queue length for the device, as a long
word. Note that this value is the number of I/O requests already in the
driver and not the depth of the I/O pending queue.
DVI$_TT_ACCPORNAM
Returns the name of the remote access port associated with a channel
number or with a physical or virtual terminal device number. If you
specify a device that is not a remote terminal or a remote type that
does not support this feature, $GETDVI returns a null string. The
$GETDVI service returns the access port name as a 64-byte, zero-filled
string.
The $GETDVI service returns the name in the format of the remote
system. If the remote system is a LAT terminal server, $GETDVI returns
the name as server_name/port_name. The names are separated by
the slash (/) character. If the remote system is an X.29 terminal, the
name is returned as network.remote_DTE.
When writing applications, you should use the string returned by
DVI$_ACCPORNAM, instead of the physical device name, to identify remote
terminals.
DVI$_TT_CHARSET
Returns, as a 4-byte bit vector, the character sets supported by the
terminal. Each bit in the vector, when set, corresponds to the name of
a coded character set. The $TTCDEF macro defines the following coded
character sets:
| Symbol |
Description |
|
TTC$V_HANGUL
|
DEC Korean
|
|
TTC$V_HANYU
|
DEC Hanyu
|
|
TTC$V_HANZI
|
DEC Hanzi
|
|
TTC$V_KANA
|
DEC Kana
|
|
TTC$V_KANJI
|
DEC Kanji
|
|
TTC$V_THAI
|
DEC Thai
|
DVI$_TT_CS_HANGUL
Returns a longword, which is interpreted as Boolean. A value of 1
indicates that the device supports the DEC Korean coded character set;
a value of 0 indicates that the device does not support the DEC Korean
coded character set.
DVI$_TT_CS_HANYU
Returns a longword, which is interpreted as Boolean. A value of 1
indicates that the device supports the DEC Hanyu coded character set; a
value of 0 indicates that the device does not support the DEC Hanyu
coded character set.
DVI$_TT_CS_HANZI
Returns a longword, which is interpreted as Boolean. A value of 1
indicates that the device supports the DEC Hanzi coded character set; a
value of 0 indicates that the device does not support the DEC Hanzi
coded character set.
DVI$_TT_CS_KANA
Returns a longword, which is interpreted as Boolean. A value of 1
indicates that the device supports the DEC Kana coded character set; a
value of 0 indicates that the device does not support the DEC Kana
coded character set.
DVI$_TT_CS_KANJI
Returns a longword, which is interpreted as Boolean. A value of 1
indicates that the device supports the DEC Kanji coded character set; a
value of 0 indicates that the device does not support the DEC Kanji
coded character set.
DVI$_TT_CS_THAI
Returns a longword, which is interpreted as Boolean. A value of 1
indicates that the device supports the DEC Thai coded character set; a
value of 0 indicates that the device does not support the DEC Thai
coded character set.
DVI$_TT_PHYDEVNAM
Returns a string containing the physical device name of a terminal. If
the caller specifies a disconnected virtual terminal or a device that
is not a terminal, $GETDVI returns a null string. $GETDVI returns the
physical device name as a 64-byte, zero-filled string.
DVI$_UNIT
Returns the unit number as an unsigned longword.
DVI$_VOLCHAR
On Alpha and I64 systems, returns a 128-bit string (16 bytes) that
represents the volume characteristics or capabilities of the mounted
device. If a bit is set, the volume is capable of performing the
function.
DVI$_VOLCOUNT
Returns the number of volumes in the volume set as an unsigned
longword. This item code is applicable only to disks.
DVI$_VOLNAM
Returns the volume name as a 12-byte, zero-filled string.
DVI$_VOLNUMBER
Returns the volume number of this volume in the volume set as an
unsigned integer longword. This item code is applicable only to disks.
DVI$_VOLSETMEM
Returns a longword, which is interpreted as Boolean. A value of 1
indicates that the device is part of a volume set; a value of 0
indicates that it is not. This item code is applicable only to disks.
DVI$_VOLSIZE
On Alpha and I64, returns the volume's current logical volume size.
DVI$_VOLUME_EXTEND_QUANTITY
On Alpha and I64, returns as an unsigned longword the number of blocks
to be used as the default extension size for all files on the volume.
DVI$_VOLUME_MOUNT_GROUP
On Alpha and I64, returns an unsigned longword, interpreted as Boolean.
A value of 1 indicates the volume is mounted /GROUP.
DVI$_VOLUME_MOUNT_SYS
On Alpha and I64, returns an unsigned longword, interpreted as Boolean.
A value of 1 indicates the volume is mounted /SYSTEM.
DVI$_VPROT
Returns the volume protection mask as a standard 4-byte protection mask.
DVI$_TT_xxxx
DVI$_TT_xxxx is the format for a series of item codes that return
information about terminals. This information consists of terminal
characteristics. The xxxx portion of the item code name
specifies a single terminal characteristic.
Each of these item codes requires that the buffer specify a longword
into which $GETDVI will write a 0 or 1: 0 if the terminal does not have
the specified characteristic, and 1 if the terminal does have it. The
one exception is the DVI$_TT_PAGE item code, which when specified
causes $GETDVI to return a decimal longword value that is the page size
of the terminal.
You can also obtain this terminal-specific information by using the
DVI$_DEVDEPEND and DVI$_DEVDEPEND2 item codes. Each of these two item
codes specifies a longword bit vector wherein each bit corresponds to a
terminal characteristic; $GETDVI sets the corresponding bit for each
characteristic possessed by the terminal.
Following is a list of the item codes that return information about
terminal characteristics. For information about these characteristics,
refer to the description of the F$GETDVI lexical function in the
HP OpenVMS DCL Dictionary.
|
DVI$_TT_NOECHO
|
DVI$_TT_NOTYPEAHD
|
|
DVI$_TT_HOSTSYNC
|
DVI$_TT_TTSYNC
|
|
DVI$_TT_ESCAPE
|
DVI$_TT_LOWER
|
|
DVI$_TT_MECHTAB
|
DVI$_TT_WRAP
|
|
DVI$_TT_LFFILL
|
DVI$_TT_SCOPE
|
|
DVI$_TT_CRFILL
|
DVI$_TT_SETSPEED
|
|
DVI$_TT_EIGHTBIT
|
DVI$_TT_MBXDSABL
|
|
DVI$_TT_READSYNC
|
DVI$_TT_MECHFORM
|
|
DVI$_TT_NOBRDCST
|
DVI$_TT_HALFDUP
|
|
DVI$_TT_MODEM
|
DVI$_TT_OPER
|
|
DVI$_TT_LOCALECHO
|
DVI$_TT_AUTOBAUD
|
|
DVI$_TT_PAGE
|
DVI$_TT_HANGUP
|
|
DVI$_TT_MODHANGUP
|
DVI$_TT_BRDCSTMBX
|
|
DVI$_TT_DMA
|
DVI$_TT_ALTYPEAHD
|
|
DVI$_TT_ANSICRT
|
DVI$_TT_REGIS
|
|
DVI$_TT_AVO
|
DVI$_TT_EDIT
|
|
DVI$_TT_BLOCK
|
DVI$_TT_DECCRT
|
|
DVI$_TT_EDITING
|
DVI$_TT_INSERT
|
|
DVI$_TT_DIALUP
|
DVI$_TT_SECURE
|
|
DVI$_TT_FALLBACK
|
DVI$_TT_DISCONNECT
|
|
DVI$_TT_PASTHRU
|
DVI$_TT_SIXEL
|
|
DVI$_TT_PRINTER
|
DVI$_TT_APP_KEYPAD
|
|
DVI$_TT_DRCS
|
DVI$_TT_SYSPWD
|
|
DVI$_TT_DECCRT2
|
|
|
DVI$_TT_DECCRT3
|
|
|
DVI$_TT_DECCRT4
|
|
DVI$_WRITETHRU_CACHE_ENABLED
On Alpha and I64, returns an unsigned longword, which is interpreted as
Boolean. A value of 1 indicates the volume is mounted with
write-through caching enabled.
DVI$_WWID
On Alpha and I64, returns the World Wide Identifier (WWID) of Fibre
Channel Disk and Tape devices as a zero-filled string of indeterminate
length.
The maximum length of this string may change with new devices;
therefore, HP recommends that a 380-byte buffer be passed to this
function.
A return length address should also be passed with the call and
examined when the function completes. If the return length is equal to
the size of the buffer, then call $GETDVI again with a larger buffer to
ensure that the complete name has been read.
DVI$_yyyy
DVI$_yyyy is the format for a series of item codes that return
device-independent characteristics of a device. There is an item code
for each device characteristic returned in the longword bit vector
specified by the DVI$_DEVCHAR item code.
In the description of the DVI$_DEVCHAR item code is a list of symbol
names in which each symbol represents a device characteristic. To
construct the $GETDVI item code for each device characteristic,
substitute for yyyy that portion of the symbol name that
follows the underscore character. For example, the DVI$_REC item code
returns the same information as the DEV$V_REC bit in the DVI$_DEVCHAR
longword bit vector.
The buffer for each of these item codes must specify a longword value,
which is interpreted as Boolean. The $GETDVI service writes the value 1
into the longword if the device has the specified characteristic and
the value 0 if it does not.
Description
The Get Device/Volume Information service returns primary and secondary
device characteristics information about an I/O device. You can use the
chan argument only if (1) the channel has already been
assigned, and (2) the caller's access mode is equal to or more
privileged than the access mode from which the original channel
assignment was made.
The caller of $GETDVI does not need to have a channel assigned to the
device about which information is desired.
The $GETDVI service returns information about both primary device
characteristics and secondary device characteristics. By default,
$GETDVI returns information about the primary device characteristics
only.
To obtain information about secondary device characteristics, you must
perform a logical OR operation on the item code specifying the
information desired with the code DVI$C_SECONDARY.
You can obtain information about primary and secondary devices in a
single call to $GETDVI.
In most cases, the two sets of characteristics (primary and secondary)
returned by $GETDVI are identical. However, the two sets provide
different information in the following cases:
- If the device has an associated mailbox, the primary
characteristics are those of the assigned device and the secondary
characteristics are those of the associated mailbox.
- If the device is a spooled device, the primary characteristics are
those of the intermediate device (such as the disk) and the secondary
characteristics are those of the spooled device (such as the printer).
- If the device represents a logical link on the network, the
secondary characteristics contain information about the link.
Unless otherwise stated in the description of the item code, $GETDVI
returns information about the local node only.
Required Access or Privileges
None
Required Quota
Sufficient AST quota.
Related Services
$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC,
$DASSGN, $DELMBX, $DEVICE_PATH_SCAN, $DEVICE_SCAN, $DISMOU, $GETDVIW,
$GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $IO_FASTPATH, $MOUNT, $PUTMSG,
$QIO, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The device name string descriptor, device name string, or
itmlst argument cannot be read; or the buffer or
return length longword cannot be written by the caller.
|
|
SS$_BADPARAM
|
The item list contains an invalid item code, or the buffer address
field in an item descriptor specifies less than four bytes for the
return length information.
|
|
SS$_EXASTLM
|
The process has exceeded its AST limit quota.
|
|
SS$_IVCHAN
|
You specified an invalid channel number, that is, a channel number
larger than the number of channels.
|
|
SS$_IVDEVNAM
|
The device name string contains invalid characters, or neither the
devnam nor
chan argument was specified.
|
|
SS$_IVLOGNAM
|
The device name string has a length of 0 or has more than 63 characters.
|
|
SS$_NONLOCAL
|
The device is on a remote system.
|
|
SS$_NOPRIV
|
The specified channel is not assigned or was assigned from a more
privileged access mode.
|
|
SS$_NOSUCHDEV
|
The specified device does not exist on the host system.
|
|
SS$_NOSUCHPATH
|
On Alpha and I64, the specified path does not exist for the device,
even though the device itself does exist.
|
Condition Values Returned in the I/O Status Block
1
Same as those returned in R0.
