|
Document revision date: 30 March 2001
|
![[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
Note that, for terminals only, individual $GETDVI item codes are
provided for most of the informational items returned in the
DVI$_DEVDEPEND longword bit vector. The names of these item codes have
the format DVI$_TT_xxxx, where xxxx is the characteristic
name. The same characteristic name follows the underscore character in
the symbolic name for each bit (defined by the $TTDEF macro) in the
DVI$_DEVDEPEND longword. For example, the DVI$_TT_NOECHO item code
returns the same information as that returned in the DVI$_DEVDEPEND bit
whose symbolic name is TT$V_NOECHO.
Each such item code requires that the buffer specify a longword value,
which is interpreted as Boolean. A value of 0 indicates that the
terminal does not have that characteristic; a value of 1 indicates that
it does.
The list of these terminal-specific item codes follows this list of
item codes.
DVI$_DEVDEPEND2
Returns additional device-dependent characteristics as a 4-byte bit
vector. Refer to the OpenVMS I/O User's Reference Manual to determine what information is
returned for a particular device.
Note that, for terminals only, individual $GETDVI item codes are
provided for most of the informational items returned in the
DVI$_DEVDEPEND2 longword bit vector. As with DVI$_DEVDEPEND, the same
characteristic name appears in the item code as appears in the symbolic
name defined for each bit in the DVI$_DEVDEPEND2 longword, except that
in the case of DVI$_DEVDEPEND2, the symbolic names for bits are defined
by the $TT2DEF macro.
The list of these terminal-specific item codes follows this list of
item codes.
DVI$_DEVICE_TYPE_NAME
Returns a string identifying the type of device about which information
was requested.
DVI$_DEVLOCKNAM
Returns the device lock name, which is a 64-byte string. The device
lock name uniquely identifies each volume or volume set in an OpenVMS
Cluster system or in a single-node system. This item code is applicable
only to disks.
The item code is applicable to all disk volumes and volume sets:
mounted, not mounted, mounted shared, mounted private, or mounted
foreign.
The device lock name is assigned to a volume when it is first mounted,
and you cannot change this name, even if the volume name itself is
changed. This allows any process on any node in an OpenVMS Cluster
system to access a uniquely identified volume.
One use for the device lock name might be in an application wherein
processes need to coordinate their access to files using the lock
manager. In this case, the program would make the file a resource to be
locked by the lock manager, specifying as the resource name the
following concatenated components: (1) a user facility prefix followed
by an underscore character, (2) the device lock name of the volume on
which the file resides, and (3) the file ID of the file.
DVI$_DEVNAM
Returns the device name as a 64-byte, zero-filled string. The node name
is also returned.
DVI$_DEVSTS
Returns device-dependent status information as a 4-byte bit vector. The
$UCBDEF macro defines symbols for the status bits. For this
device-dependent information, refer to the OpenVMS I/O User's Reference Manual.
DVI$_DEVTYPE
Returns the device type as an unsigned integer longword. The $TTDEF
macro defines symbols for the device types.
DVI$_DFS_ACCESS
Returns a Boolean value indicating whether a device is a DFS served
disk. A value of 0 indicates that the device is a DFS served disk; a
value of 1 indicates that the device is not.
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
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
Returns the device's error count as an unsigned integer longword.
DVI$_FC_NODE_NAME
DVI$_FC_PORT_NAME
Returns the Fibre Channel Node or Port name for the Fibre Channel Host
Bus Adapter as a zero-filled string for each of these values. If a
Fibre Channel Disk or Tape is directly attached to the system, then the
codes also work for these devices.
The maximum length of this string may change in the future; therefore,
Compaq recommends that you pass a 32-byte buffer 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$_FREEBLOCKS
Returns the number of free blocks on a disk as an unsigned integer
longword. This item code is applicable only to disks.
DVI$_FULLDEVNAM
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
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
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
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
Returns a four-byte string containing an arbitrary text description of
the OpenVMS host or cluster storage controller that is serving this
storage device. The particular text string displayed was provided to
the local OpenVMS system by the remote System Communications Services
(SCS) server.
Storage devices are served within an OpenVMS Cluster utilizing the SCS
protocol, with the server running on a remote OpenVMS system or on an
SCS-capable storage controller. The host type value displayed is
determined from the local cluster storage hardware configuration, and
indicates the type of devices serving the storage for the available SCS
path or paths to the particular storage device.
Item codes in this group include: DVI$_HOST_TYPE, DVI$_ALT_HOST_TYPE,
DVI$_HOST_AVAIL, and DVI$_ALT_HOST_AVAIL. Also related is
DVI$_HOST_NAME.
Compaq suggests this item code be used solely for display purposes, and
should not be used during an attempt to determine the particular
cluster hardware configuration.
DVI$_LOCKID
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
Returns the logical name of the volume or volume set as a 64-byte
string.
DVI$_MAXBLOCK
Returns the maximum number of blocks on the volume as an unsigned
integer longword. This item code is applicable only to disks.
DVI$_MAXFILES
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
Returns the nondecoded media ID as a longword. This item code is
applicable only to disks and tapes.
DVI$_MEDIA_NAME
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
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
Returns the mount count for the volume as an unsigned integer longword
and displays the number of times the volume has been mounted on the
local system.
The value of MOUNTCNT displayed by the SHOW DEVICE command is the total
of all mounts of the volume across all members of the cluster.
DVI$_MSCP_UNIT_NUMBER
Returns the internal coded value for MSCP unit numbers as a longword
integer. This item code is reserved to Compaq.
DVI$_MT3_DENSITY
The return value of 1 indicates that the device supports tape density
codes defined by MT3DEF. Valid for tapes only. This code is an unsigned
longword integer.
DVI$_MT3_SUPPORTED
Returns the density of the device. Valid for tapes only. This code is
an unsigned longword integer.
DVI$_NEXTDEVNAM
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
Returns the operation count for the volume as an unsigned integer
longword.
DVI$_OWNUIC
Returns the user identification code (UIC) of the owner of the device
as a standard 4-byte UIC.
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$_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$_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_FAILED_MEMBER
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
Returns a longword, which is interpreted as Boolean. The value 1
indicates that the device is a virtual unit.
DVI$_SHDW_MASTER_NAME
When 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. Refer to 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
Returns a longword, which is interpreted as Boolean. The value 1
indicates that the device is a shadow set member.
DVI$_SHDW_MERGE_COPYING
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
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. Refer to 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
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
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$_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 integer longword.
DVI$_VOLCOUNT
Returns the number of volumes in the volume set as an unsigned integer
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 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
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$_WWID
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, Compaq 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.