Document revision date: 30 March 2001

## OpenVMS System Services Reference Manual

Previous | Contents | Index

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.

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 4527PRO_044.HTML