HP OpenVMS System Services Reference Manual


Previous Contents Index

The allocatable device name, sometimes called the allocation-class device name, uniquely identifies each device that is currently accessible to any given node in an OpenVMS cluster or to a single-node OpenVMS system. This item code generates the same name on every system for a device that is accessible on multiple cluster nodes through multiple paths or servers.

The device name string returned by the DVI$_ALLDEVNAM item code is recommended for use with the $ASSIGN service, regardless of whether the system is clustered or whether the device is cluster accessible, because it returns the same string value for all conditions.

Another possible use for the DVI$_ALLDEVNAM item code might be an application wherein processes need to coordinate their access to devices (not volumes) using the lock manager. In this case, the program would make the device 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 and (2) the allocatable device name of the device.

Depending on the device type and characteristics, the format of the returned name may include an allocation class or node name prefix.

Use the name returned by the DVI$_DEVLOCKNAM item code to coordinate access to volumes.

DVI$_ALLOCLASS

Returns the allocation class of the host as a longword integer between 0 and 32767. An allocation class is a unique number between 0 and 32767 that the system manager assigns to a pair of hosts and the dual-pathed devices that the hosts make available to other nodes in the cluster.

The allocation class provides a way for you to access dual-pathed devices through either of the hosts that act as servers to the cluster. In this way, if one host of an allocation class set is not available, you can gain access to a device specified by that allocation class through the other host of the allocation class. You do not have to be concerned about which host of the allocation class provides access to the device. Specifically, the device name string has the following format:

$allocation_class$device_name

For a detailed discussion of allocation classes, see HP OpenVMS Cluster Systems.

DVI$_ALT_HOST_AVAIL

Returns a longword that is interpreted as Boolean. A value of 1 indicates that the host serving the alternate path is available; a value of 0 indicates that it is not available.

The host is the node that makes the device available to other nodes in the OpenVMS Cluster system. A host node can be a VMS system with an MSCP server or an HSC50 controller.

A dual-pathed device is one that is made available to the cluster by two hosts. Each of the hosts provides access (serves a path) to the device for users. One host serves the primary path; the other host serves the alternate path. The primary path is the path that the system creates through the first available host.

Do not be concerned with which host provides access to the device. When accessing a device, you specify the allocation class of the desired device, not the name of the host that serves it.

If the host serving the primary path fails, the system automatically creates a path to the device through the alternate host.

DVI$_ALT_HOST_NAME

Returns the name of the host serving the alternate path as a string.

For more information about hosts, dual-pathed devices, and primary and alternate paths, see the description of the DVI$_ALT_HOST_AVAIL item code.

DVI$_ALT_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 alternate 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.

HP suggests this item code be used solely for display purposes, and do not use it during an attempt to determine the particular cluster hardware configuration.

DVI$_AVAILABLE_PATH_COUNT

On Alpha and Integrity server systems, returns the number of available, working paths for a multipath-capable device as an unsigned longword.

DVI$_CLUSTER

Returns the volume cluster size as an unsigned integer longword. This item code is applicable only to disks.

DVI$_CYLINDERS

Returns the number of cylinders on the volume as an unsigned integer longword. This item code is applicable only to disks.

DVI$_DEVBUFSIZ

Returns the device buffer size (for example, the width of a terminal or the block size of a tape) as an unsigned integer longword.

DVI$_DEVCHAR

Returns device-independent characteristics as a 4-byte bit vector. Each characteristic is represented by a bit. When $GETDVI sets a bit, the device has the corresponding characteristic. Each bit in the vector has a symbolic name. The $DEVDEF macro defines the following symbolic names:
Symbol Description
DEV$V_REC Device is record oriented.
DEV$V_CCL Device is a carriage control device.
DEV$V_TRM Device is a terminal.
DEV$V_DIR Device is directory structured.
DEV$V_SDI Device is single-directory structured.
DEV$V_SQD Device is sequential and block oriented.
DEV$V_SPL Device is being spooled.
DEV$V_OPR Device is an operator.
DEV$V_RCT Disk contains Revector Cache Table (RCT). This bit is set for every DSA disk.
DEV$V_NET Device is a network device.
DEV$V_FOD Device is files oriented.
DEV$V_DUA Device is dual ported.
DEV$V_SHR Device is shareable.
DEV$V_GEN Device is a generic device.
DEV$V_AVL Device is available for use.
DEV$V_MNT Device is mounted.
DEV$V_MBX Device is a mailbox.
DEV$V_DMT Device is marked for dismount.
DEV$V_ELG Device has error logging enabled.
DEV$V_ALL Device is allocated.
DEV$V_FOR Device is mounted foreign.
DEV$V_SWL Device is software write locked.
DEV$V_IDV Device can provide input.
DEV$V_ODV Device can provide output.
DEV$V_RND Device allows random access.
DEV$V_RTM Device is a real-time device.
DEV$V_RCK Device has read-checking enabled.
DEV$V_WCK Device has write-checking enabled.

Note that each device characteristic has its own individual $GETDVI item code with the format DVI$_xxxx, where xxxx are the characters following the underscore character in the symbolic name for that device characteristic.

For example, when you specify the item code DVI$_REC, $GETDVI returns a longword value that is interpreted as Boolean. If the value is 0, the device is not record oriented; if the value is 1, it is record oriented. This information is identical to that returned in the DEV$V_REC bit of the longword vector specified by the DVI$_DEVCHAR item code.

The buffer must specify a longword for all of these device-characteristic item codes.

DVI$_DEVCHAR2

Returns additional device-independent characteristics as a 4-byte bit vector. Each bit in the vector, when set, corresponds to a symbolic name. The $DEVDEF macro defines the following symbolic names:
Symbol Description
DEV$V_CLU Device is available clusterwide.
DEV$V_DET Device is detached terminal.
DEV$V_RTT Device has remote terminal UCB extension.
DEV$V_CDP Dual-pathed device with two UCBs.
DEV$V_2P Two paths are known to this device.
DEV$V_MSCP Device accessed using MSCP (disk or tape). Before using this bit to differentiate between types of disk and tape devices, be sure that no other more appropriate differentiation mechanism exists.
DEV$V_SSM Device is a shadow set member.
DEV$V_SRV Device is served by the MSCP server.
DEV$V_RED Device is redirected terminal.
DEV$V_NNM Device has node$ prefix.
DEV$V_WBC Device supports write-back caching.
DEV$V_WTC Device supports write-through caching.
DEV$V_HOC Device supports host caching.
DEV$V_LOC Device accessible by local (non-emulated) controller.
DEV$V_DFS Device is DFS-served.
DEV$V_DAP Device is DAP accessed.
DEV$V_NLT Device is not-last-track; that is, it has no bad block. Information is on its last track.
DEV$V_SEX Device (tape) supports serious exception handling.
DEV$V_SHD Device is a member of a host-based shadow set.
DEV$V_VRT Device is a shadow set virtual unit.
DEV$V_LDR Loader present (tapes).
DEV$V_NOLB Device ignores server load balancing requests.
DEV$V_NOCLU Device will never be available clusterwide.
DEV$V_VMEM Virtual member of a constituent set.
DEV$V_SCSI Device is a SCSI device.
DEV$V_WLG Device has write-logging capability.
DEV$V_NOFE Device does not support forced error.

DVI$_DEVCLASS

Returns the device class as an unsigned integer longword. Each class has a corresponding symbol. The $DCDEF macro defines these symbols. The following table describes each device class symbol:
Symbol Description
DC$_DISK Disk device
DC$_TAPE Tape device
DC$_SCOM Synchronous communications device
DC$_CARD Card reader
DC$_TERM Terminal
DC$_LP Line printer
DC$_REALTIME Real-time
DC$_MAILBOX Mailbox
DC$_MISC Miscellaneous device
DC$_BUS Peripheral adapter

DVI$_DEVDEPEND

Returns device-dependent characteristics as a 4-byte bit vector. To determine what information is returned for a particular device, see the HP OpenVMS I/O User's 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. To determine what information is returned for a particular device, see the HP OpenVMS I/O User's Reference Manual.

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_MAX_IO_SIZE

On Alpha and Integrity server systems, returns the maximum unsegmented transfer size supported by the device's device driver as an unsigned integer longword. Note that although this value is the absolute maximum size supported by the device driver, other software layers (RMS and XFC, for example) might impose lower maximum values limiting the maximum unsegmented transfer size.

DVI$_DEVICE_TYPE_NAME

Returns a string identifying the type of device about which information was requested. HP recommends a buffer size of 64 bytes to return the device type name.

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 a displayable device name as a string.

Although DVI$_DEVNAM returns a displayable device name, it might not return a unique name for cluster-accessible devices. For this reason, the DVI$_DEVNAM item code is not recommended for use with the $ASSIGN service. Use the DVI$_ALLDEVNAM item code with the $ASSIGN service.

Depending on the device type and characteristics, the format of the returned name may include an allocation class or node name prefix.

The DVI$_DEVNAM item code is provided solely for compatibility with existing programs from previous OpenVMS releases; therefore, HP recommends that you use the DVI$_ALLDEVNAM, DVI$_FULLDEVNAM, or DVI$_DISPLAY_DEVNAM item codes, depending on the function required.

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, see the HP OpenVMS I/O User's Reference Manual.

DVI$_DEVTYPE

Returns the device type as an unsigned integer longword. The $DCDEF 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 a displayable device name as a string. HP recommends a buffer size of 64 bytes to return the displayable device name.

The format of the returned name includes the allocatable device name for the device (see DVI$_ALLDEVNAM) followed by any current primary or secondary path information for the device.

Depending on the device type and characteristics, the format of the returned name may include an allocation class or node name prefix.

The device name string returned by the DVI$_DISPLAY_DEVNAM item code cannot be used for the $ASSIGN service. Use the DVI$_ALLDEVNAM item code to form the device name for the $ASSIGN service.

DVI$_ERASE_ON_DELETE

On Alpha and Integrity server systems, returns an unsigned longword, which is interpreted as Boolean. A value of 1 indicates that disk blocks are zeroed upon file deletion on the volume.

DVI$_ERRCNT

Returns the error count of the device as an unsigned longword. The error count might have been reset with the SET DEVICE/RESET=ERRCNT command. If the error count has been reset, use the SHOW DEVICE/FULL command to display the date and time that the error count was reset.

On Alpha and Integrity server systems, this item code can be used with the PATHNAME parameter. If the PATHNAME parameter is omitted, the summation of the error 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 error count for that path is returned.

DVI$_ERROR_RESET_TIME

On Alpha and Integrity server systems, returns the time at which the error count was reset as a 64-bit VMS date/time format.

DVI$_EXPSIZE

On Alpha and Integrity server systems, returns the current expansion limit on the volume as an unsigned integer longword.

DVI$_FC_HBA_FIRMWARE_REV

On Alpha and Integrity server systems, returns the firmware revision information of a fibre channel host bus adapter as a string. A null string is returned for all other devices.

DVI$_FC_NODE_NAME

DVI$_FC_PORT_NAME

On Alpha and Integrity server systems, returns the Fibre Channel Node or Port name for the Fibre Channel Host Bus Adapter as a string for each of these values.

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 a displayable device name as a string.

DVI$_FULLDEVNAM returns a displayable device name, which includes appropriate identification to distinguish cluster-accessible devices by including the allocation class or node name in the device string.

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, do not use this name as a resource name in input to the lock manager; instead, use the name returned by the DVI$_DEVLOCKNAM item code for locking volumes and the name returned by DVI$_ALLDEVNAM for locking devices.

Depending on the device type and characteristics, the format of the returned name may include an allocation class or node name prefix.

The name returned by the DVI$_FULLDEVNAM item code can be used for the $ASSIGN service. HP recommends that you use the DVI$_ALLDEVNAM item code to form the name for the $ASSIGN service, so that the name appears the same regardless of which OpenVMS Cluster node is accessing the device.

DVI$_HARDLINKS_SUPPORTED

On Alpha and Integrity server systems, returns an unsigned longword, which is interpreted as Boolean. A value of 1 indicates that POSIX hardlinks, rather than aliases, are supported.

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, see the description of the DVI$_ALT_HOST_AVAIL item code.

DVI$_HOST_COUNT

Returns the number of hosts that make the device available to other nodes in the OpenVMS Cluster system as a longword integer. 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, see 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 string.

For more information about hosts, dual-pathed devices, and primary and alternate paths, see 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.

HP suggests this item code be used solely for display purposes; do not use it during an attempt to determine the particular cluster hardware configuration.

DVI$_LAN_ALL_MULTICAST_MODE

On Alpha and Integrity server systems, returns an unsigned longword, which is interpreted as Boolean. A value of 1 indicates that the device is enabled to receive all multicast packets, rather than only packets addressed to enabled multicast addresses.

DVI$_LAN_AUTONEG_ENABLED

On Alpha and Integrity server systems, returns an unsigned longword, which is interpreted as Boolean. A value of 1 indicates that the device is set to autonegotiate the speed and duplex settings.

DVI$_LAN_DEFAULT_MAC_ADDRESS

On Alpha and Integrity server systems, returns the default media access control (MAC) address of the device as a string.

DVI$_LAN_FULL_DUPLEX

On Alpha and Integrity server systems, returns an unsigned longword, which is interpreted as Boolean. A value of 1 indicates that the device is operating in full-duplex mode.

DVI$_LAN_JUMBO_FRAMES_ENABLED

On Alpha and Integrity server systems, returns an unsigned longword, which is interpreted as Boolean. A value of 1 indicates that jumbo frames are enabled on the device.

DVI$_LAN_LINK_STATE_VALID

On Alpha and Integrity server systems, returns an unsigned longword, which is interpreted as Boolean. A value of 1 indicates that the device driver for the LAN device correctly maintains the link status.

The device drivers for the following adapters do not maintain the link status: DEMNA, any TURBOchannel adapter, any PCMCIA adapter, any Token Ring adapter, Galaxy shared memory, TGEC, DE205, DE422, DE425, DE434, DE435, DE500-XA. (The -AA and -BA variants are supported.)

DVI$_LAN_LINK_UP

On Alpha and Integrity server systems, returns an unsigned longword, which is interpreted as Boolean. A value of 1 indicates that the link is up. This item code is valid only for the template device (that is, unit number 0); this item returns 0 if used against a nontemplate LAN device.

This item is supported only on newer adapters. To determine whether or not a particular LAN device supports DVI$_LAN_LINK_UP, you must first call $GETDVI using the item code DVI$_LAN_LINK_STATE_VALID. For more information, see that item code.

If DVI$_LAN_LINK_UP is used on an adapter that does not maintain the link status, the returned status from $GETDVI will be SS$_UNSUPPORTED. For more information, see DVI$_LAN_LINK_VALID.

DVI$_LAN_MAC_ADDRESS

On Alpha and Integrity server systems, returns the current MAC address of the device as a string. Note that certain protocols, such as DECnet Phase IV, change the default MAC address to one based on the DECnet address. For DECnet Phase IV, the MAC address is in the form AA-00-04-00-nn-mm, where nn-mm is calculated by multiplying the DECnet Phase IV area number by 1024, adding the node number (that is, the number following the dot), taking the hexadecimal representation of that sum, and swapping the two bytes.

For example, a node with a DECnet Phase IV address of 3.31 gives a decimal representation of 3103 (the value corresponding to the system parameter SCSSYSTEMID) and a hexadecimal representation of 0C1F. If DECnet Phase IV is started on this system, the MAC address of any LAN adapter on this system running DECnet is AA-00-04-00-1F-0C. < PARAMITEM>(DVI$_LAN_PROMISCUOUS_MODE) On Alpha and Integrity server systems, returns an unsigned longword, which is interpreted as Boolean. A value of 1 indicates that the device is enabled to receive all packets, not just packets addressed to the MAC address and enabled multicast addresses.

DVI$_LAN_PROTOCOL_NAME

On Alpha and Integrity server systems, returns the name of the LAN protocol running on the device as a string.

DVI$_LAN_PROTOCOL_TYPE

On Alpha and Integrity server systems, returns the LAN protocol type running on the device as a string.

DVI$_LAN_SPEED

On Alpha and Integrity server systems, returns the speed of the LAN device (in Mb/s) as an unsigned longword. Valid values are 4, 10, 16, 100, 1000, and 10000.

DVI$_LOCKID

Returns the lock ID of the lock on a disk as an unsigned longword. 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.

DVI$_LOGVOLNAM

Returns the logical name of the volume or volume set as a string.

DVI$_MAILBOX_BUFFER_QUOTA

On Alpha and Integrity server systems, returns the current mailbox quota as an unsigned integer longword.

DVI$_MAILBOX_INITIAL_QUOTA

On Alpha and Integrity server systems, returns the initial mailbox quota as an unsigned integer longword.

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 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 string. This item code is applicable only to disks and tapes.

DVI$_MOUNT_TIME

On Alpha and Integrity server systems, returns the time at which the volume was mounted. Because the returned time is in the standard 64-bit absolute time format, specify 8 (bytes) for the buffer length field in the item descriptor.


Previous Next Contents Index