|
Document revision date: 19 July 1999
|
![[Compaq]](../../images/compaq.gif) |
![[Go to the documentation home page]](../../images/buttons/bn_site_home.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs.gif)
![[Help on this site]](../../images/buttons/bn_site_help.gif)
![[How to contact us]](../../images/buttons/bn_comments.gif)
|
![[OpenVMS documentation]](../../images/ovmsdoc_sec_head.gif)
|
OpenVMS System Services Reference Manual
This information allows you to determine if a function works on remote
disk devices with DFS. Access control lists (ACLs), for example, cannot
be set or displayed on local disk devices with DFS.
DVI$_DISPLAY_DEVNAM
When you specify DVI$_DISPLAY_DEVNAM, $GETDVI returns the preferred
device name for user displays as a 256-byte zero-filled string. The
DVI$_DISPLAY_DEVNAM item code is not recommended for use with the
$ASSIGN service. Use the DVI$_ALLDEVNAM item code to return an
allocation class device name that is usable as input to a program.
DVI$_ERRCNT
When you specify DVI$_ERRCNT, $GETDVI returns the device's error count
as an unsigned integer longword.
DVI$_FREEBLOCKS
When you specify DVI$_FREEBLOCKS, $GETDVI returns the number of free
blocks on a disk as an unsigned integer longword. This item code is
applicable only to disks.
DVI$_FULLDEVNAM
When you specify DVI$_FULLDEVNAM, $GETDVI returns the node name and
device name as a 64-byte, zero-filled string.
The DVI$_FULLDEVNAM item code is useful in an OpenVMS Cluster
environment because, unlike DVI$_DEVNAM, DVI$_FULLDEVNAM returns the
name of the node on which the device resides.
One use for the DVI$_FULLDEVNAM item code might be to retrieve the name
of a device in order to have that name displayed on a terminal.
However, you should not use this name as a resource name as input to
the lock manager; use the name returned by the DVI$_DEVLOCKNAM item
code for locking volumes and the name returned by DVI$_ALLDEVNAM for
locking devices.
DVI$_HOST_AVAIL
When you specify DVI$_HOST_AVAIL, $GETDVI returns a longword, which is
interpreted as Boolean. A value of 1 indicates that the host serving
the primary path is available; a value of 0 indicates that it is not
available.
For more information about hosts, dual-pathed devices, and primary and
alternate paths, refer to the description of the DVI$_ALT_HOST_AVAIL
item code.
DVI$_HOST_COUNT
When you specify DVI$_HOST_COUNT, $GETDVI returns, as a longword
integer, the number of hosts that make the device available to other
nodes in the OpenVMS Cluster system. One or two hosts, but no more, can
make a device available to other nodes in the cluster.
For more information about hosts, dual-pathed devices, and primary and
alternate paths, refer to the description of the DVI$_ALT_HOST_AVAIL
item code.
DVI$_HOST_NAME
When you specify DVI$_HOST_NAME, $GETDVI returns the name of the host
serving the primary path as a 64-byte, zero-filled string.
For more information about hosts, dual-pathed devices, and primary and
alternate paths, refer to the description of the DVI$_ALT_HOST_AVAIL
item code.
DVI$_HOST_TYPE
When you specify DVI$_HOST_TYPE, $GETDVI returns, as a 4-byte string,
the type of host serving the primary path. Each hardware type has a
symbolic name.
The following table shows each symbolic name and the host it denotes on
VAX systems.
| Name |
Host |
|
VAX
|
Any VAX family processor
|
|
HS50
|
HSC50
|
|
HS70
|
HSC70
|
The following table shows each symbolic name and the host it denotes on
Alpha systems.
| Name |
Host |
|
Alpha
|
Any Alpha family processor
|
|
HS50
|
HSC50
|
|
HS70
|
HSC70
|
For more information about hosts, dual-pathed devices, and primary and
alternate paths, refer to the description of the DVI$_ALT_HOST_AVAIL
item code.
DVI$_LOCKID
When you specify DVI$_LOCKID, $GETDVI returns the lock ID of the lock
on a disk. The lock manager locks a disk if it is available to all
nodes in an OpenVMS Cluster system and it is either allocated or
mounted. A disk is available to all nodes in an OpenVMS Cluster system
if, for example, it is served by an HSC controller or MSCP server or if
it is a dual-ported MASSBUS disk.
The buffer must specify a longword into which $GETDVI is to return the
4-byte hexadecimal lock ID.
DVI$_LOGVOLNAM
When you specify DVI$_LOGVOLNAM, $GETDVI returns the logical name of
the volume or volume set as a 64-byte string.
DVI$_MAXBLOCK
When you specify DVI$_MAXBLOCK, $GETDVI returns the maximum number of
blocks on the volume as an unsigned integer longword. This item code is
applicable only to disks.
DVI$_MAXFILES
When you specify DVI$_MAXFILES, $GETDVI returns the maximum number of
files on the volume as an unsigned integer longword. This item code is
applicable only to disks.
DVI$_MEDIA_ID
When you specify DVI$_MEDIA_ID, $GETDVI returns the nondecoded media ID
as a longword. This item code is applicable only to disks and tapes.
DVI$_MEDIA_NAME
When you specify DVI$_MEDIA_NAME, $GETDVI returns the name of the
volume type (for example, RK07 or TA78) as a 64-byte, zero-filled
string. This item code is applicable only to disks and tapes.
DVI$_MEDIA_TYPE
When you specify DVI$_MEDIA_TYPE, $GETDVI returns the device name
prefix of the volume (for example, DM for an RK07 device or MU for a
TA78 device) as a 64-byte, zero-filled string. This item code is
applicable only to disks and tapes.
DVI$_MOUNTCNT
When you specify DVI$_MOUNTCNT, $GETDVI returns the mount count for the
volume as an unsigned integer longword.
DVI$_MSCP_UNIT_NUMBER
When you specify DVI$_MSCP_UNIT_NUMBER, $GETDVI returns the internal
coded value for MSCP unit numbers as a longword integer. This item code
is reserved to Compaq.
DVI$_NEXTDEVNAM
When you specify DVI$_NEXTDEVNAM, $GETDVI returns the device name of
the next volume in the volume set as a 64-byte, zero-filled string. The
node name is also returned. This item code is applicable only to disks.
DVI$_OPCNT
When you specify DVI$_OPCNT, $GETDVI returns the operation count for
the volume as an unsigned integer longword.
DVI$_OWNUIC
When you specify DVI$_OWNUIC, $GETDVI returns the user identification
code (UIC) of the owner of the device as a standard 4-byte UIC.
DVI$_PID
When you specify DVI$_PID, $GETDVI returns the process identification
(PID) of the owner of the device as an unsigned integer longword.
DVI$_RECSIZ
When you specify DVI$_RECSIZ, $GETDVI returns the blocked record size
as an unsigned integer longword.
DVI$_REFCNT
When you specify DVI$_REFCNT, $GETDVI returns the number of channels
assigned to the device as an unsigned integer longword.
DVI$_REMOTE_DEVICE
When you specify DVI$_REMOTE_DEVICE, $GETDVI 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
When you specify DVI$_ROOTDEVNAM, $GETDVI 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$_SECTORS
When you specify DVI$_SECTORS, $GETDVI returns the number of sectors
per track as an unsigned integer longword. This item code is applicable
only to disks.
DVI$_SERIALNUM
When you specify DVI$_SERIALNUM, $GETDVI returns the serial number of
the volume as an unsigned integer longword. This item code is
applicable only to disks.
DVI$_SERVED_DEVICE
When you specify DVI$_SERVED_DEVICE, $GETDVI 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
When you specify DVI$_SHDW_CATCHUP_COPYING, $GETDVI 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_FAILED_MEMBER
When you specify DVI$_SHDW_FAILED_MEMBER, $GETDVI returns a longword,
which is interpreted as Boolean. The value 1 indicates that the device
is a member that has been removed from the shadow set by the remote
server. The DVI$_SHDW_FAILED_MEMBER item code is for use only with VAX
Volume Shadowing (phase I).
DVI$_SHDW_MASTER
When you specify DVI$_SHDW_MASTER, $GETDVI returns a longword, which is
interpreted as Boolean. The value 1 indicates that the device is a
virtual unit.
DVI$_SHDW_MASTER_NAME
When you specify DVI$_SHOW_MASTER_NAME and the specified device is a
shadow set member, $GETDVI returns the device name of the virtual unit
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.
Note
Shadow set members must have a nonzero allocation class to operate in
an OpenVMS Cluster system. See 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_MEMBER
When you specify DVI$_SHDW_MEMBER, $GETDVI returns a longword, which is
interpreted as Boolean. The value 1 indicates that the device is a
shadow set member.
DVI$_SHDW_MERGE_COPYING
When you specify DVI$_SHDW_MERGE_COPYING, $GETDVI 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_NEXT_MBR_NAME
When you specify DVI$_SHDW_NEXT_MBR_NAME, $GETDVI returns the device
name of the next member in the shadow set. If you specify a virtual
unit with the chan or devnam
agrument, 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 agrument,
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 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 DUS10,
$GETDVI returns the string $255$DUS10.
Note
Shadow set members must have a nonzero allocation class to operate in
an OpenVMS Cluster system. See 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$_STS
When you specify DVI$_STS, $GETDVI 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_TIM
|
Timeout is enabled.
|
|
UCB$V_INT
|
Interrupt is expected.
|
|
UCB$V_ERLOGIP
|
Error log is in progress on unit.
|
|
UCB$V_CANCEL
|
I/O on unit is canceled.
|
|
UCB$V_ONLINE
|
Unit is on line.
|
|
UCB$V_POWER
|
Power failed while unit busy.
|
|
UCB$V_TIMOUT
|
Unit timed out.
|
|
UCB$V_INTTYPE
|
Receiver interrupt.
|
|
UCB$V_BSY
|
Unit is busy.
|
|
UCB$V_MOUNTING
|
Device is being mounted.
|
|
UCB$V_DEADMO
|
Deallocate at dismount.
|
|
UCB$V_VALID
|
Volume is software valid.
|
|
UCB$V_UNLOAD
|
Unload volume at dismount.
|
|
UCB$V_TEMPLATE
|
Template UCB from which other UCBs for this device type are made.
|
|
UCB$V_MNTVERIP
|
Mount verification is in progress.
|
|
UCB$V_WRONGVOL
|
Wrong volume detected during mount verification.
|
|
UCB$V_DELETEUCB
|
Delete this UCB when reference count equals 0.
|
DVI$_TRACKS
When you specify DVI$_TRACKS, $GETDVI returns the number of tracks per
cylinder as an unsigned integer longword. This item code is applicable
only to disks.
DVI$_TRANSCNT
When you specify DVI$_TRANSCNT, $GETDVI returns the transaction count
for the volume as an unsigned integer longword.
DVI$_TT_ACCPORNAM
When you specify DVI$_TT_ACCPORNAM, $GETDVI 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
When you specify DVI$TT_CHARSET, $GETDVI 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
When you specify DVI$_TT_CS_HANGUL, $GETDVI 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
When you specify DVI$_TT_CS_HANYU, $GETDVI 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
When you specify DVI$_TT_CS_HANZI, $GETDVI 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
When you specify DVI$_TT_CS_KANA, $GETDVI 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
When you specify DVI$_TT_CS_KANJI, $GETDVI 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
When you specify DVI$_TT_CS_THAI, $GETDVI 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
When you specify DVI$_TT_PHYDEVNAM, $GETDVI 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
When you specify DVI$_UNIT, $GETDVI returns the unit number as an
unsigned integer longword.
DVI$_VOLCOUNT
When you specify DVI$_VOLCOUNT, $GETDVI returns the number of volumes
in the volume set as an unsigned integer longword. This item code is
applicable only to disks.
DVI$_VOLNAM
When you specify DVI$_VOLNAM, $GETDVI returns the volume name as a
12-byte zero-filled string.
DVI$_VOLNUMBER
When you specify DVI$_VOLNUMBER, $GETDVI 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
When you specify DVI$_VOLSETMEM, $GETDVI returns a longword value,
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$_VPROT
When you specify DVI$_VPROT, $GETDVI 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
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$_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_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.
|
Condition Values Returned in the I/O Status Block
1
Same as those returned in R0.