|
HP OpenVMS Systems Documentation |
|
HP OpenVMS System Services Reference Manual
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$_ALLOCLASSReturns 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:
For a detailed discussion of allocation classes, see HP OpenVMS Cluster Systems. DVI$_ALT_HOST_AVAILReturns 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_NAMEReturns 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_TYPEReturns 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_COUNTOn Alpha and Integrity server systems, returns the number of available, working paths for a multipath-capable device as an unsigned longword.DVI$_CLUSTERReturns the volume cluster size as an unsigned integer longword. This item code is applicable only to disks.DVI$_CYLINDERSReturns the number of cylinders on the volume as an unsigned integer longword. This item code is applicable only to disks.DVI$_DEVBUFSIZReturns the device buffer size (for example, the width of a terminal or the block size of a tape) as an unsigned integer longword.DVI$_DEVCHARReturns 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:
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$_DEVCHAR2Returns 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:
DVI$_DEVCLASSReturns 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:
DVI$_DEVDEPENDReturns 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$_DEVDEPEND2Returns 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_SIZEOn 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_NAMEReturns 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$_DEVLOCKNAMReturns 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$_DEVNAMReturns 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$_DEVSTSReturns 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$_DEVTYPEReturns the device type as an unsigned integer longword. The $DCDEF macro defines symbols for the device types.DVI$_DFS_ACCESSReturns 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_DEVNAMReturns 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_DELETEOn 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$_ERRCNTReturns 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_TIMEOn Alpha and Integrity server systems, returns the time at which the error count was reset as a 64-bit VMS date/time format.DVI$_EXPSIZEOn Alpha and Integrity server systems, returns the current expansion limit on the volume as an unsigned integer longword.DVI$_FC_HBA_FIRMWARE_REVOn 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_NAMEDVI$_FC_PORT_NAMEOn 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$_FREEBLOCKSReturns the number of free blocks on a disk as an unsigned integer longword. This item code is applicable only to disks.DVI$_FULLDEVNAMReturns 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_SUPPORTEDOn 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_AVAILReturns 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_COUNTReturns 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_NAMEReturns 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_TYPEReturns 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_MODEOn 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_ENABLEDOn 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_ADDRESSOn Alpha and Integrity server systems, returns the default media access control (MAC) address of the device as a string.DVI$_LAN_FULL_DUPLEXOn 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_ENABLEDOn 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_VALIDOn 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_UPOn 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_ADDRESSOn 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_NAMEOn Alpha and Integrity server systems, returns the name of the LAN protocol running on the device as a string.DVI$_LAN_PROTOCOL_TYPEOn Alpha and Integrity server systems, returns the LAN protocol type running on the device as a string.DVI$_LAN_SPEEDOn 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$_LOCKIDReturns 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$_LOGVOLNAMReturns the logical name of the volume or volume set as a string.DVI$_MAILBOX_BUFFER_QUOTAOn Alpha and Integrity server systems, returns the current mailbox quota as an unsigned integer longword.DVI$_MAILBOX_INITIAL_QUOTAOn Alpha and Integrity server systems, returns the initial mailbox quota as an unsigned integer longword.DVI$_MAXBLOCKReturns the maximum number of blocks on the volume as an unsigned integer longword. This item code is applicable only to disks.DVI$_MAXFILESReturns the maximum number of files on the volume as an unsigned integer longword. This item code is applicable only to disks.DVI$_MEDIA_IDReturns the nondecoded media ID as a longword. This item code is applicable only to disks and tapes.DVI$_MEDIA_NAMEReturns 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_TYPEReturns 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_TIMEOn 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.
|