|
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. Note that the name returned by the DVI$_DEVLOCKNAM item code should be used 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, refer to 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 either a VAX 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. You should 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 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$_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 should not be used during an attempt to determine the particular cluster hardware configuration. DVI$_AVAILABLE_PATH_COUNTOn Alpha and I64, returns as an unsigned longword the number of available, working paths for a multipath-capable device.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, refer to 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. Refer to the HP 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_NAMEReturns a string identifying the type of device about which information was requested.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 64-byte, zero-filled string.DVI$_DEVNAM returns a displayable device name; however, 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, refer to the HP OpenVMS I/O User's Reference Manual.DVI$_DEVTYPEReturns the device type as an unsigned integer longword. The $TTDEF 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 256-byte, zero-filled string.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 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 I64, 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 I64, 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 I64, returns as a 64-bit VMS date/time format the time at which the error count was reset.DVI$_EXPSIZEOn Alpha and I64, returns the current expansion limit on the volume.DVI$_FC_NODE_NAMEDVI$_FC_PORT_NAMEOn Alpha and I64, 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, HP 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$_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 64-byte, zero-filled 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, 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. 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 I64, 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, refer to the description of the DVI$_ALT_HOST_AVAIL item code. DVI$_HOST_COUNTReturns, 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_NAMEReturns 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_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, and should not be used during an attempt to determine the particular cluster hardware configuration. DVI$_LOCKIDReturns 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$_LOGVOLNAMReturns the logical name of the volume or volume set as a 64-byte string.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 64-byte, zero-filled 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 64-byte, zero-filled string. This item code is applicable only to disks and tapes.DVI$_MOUNT_TIMEOn Alpha and I64, returns the time at which the volume was mounted. Because the returned time is in the standard 64-bit absolute time format, the buffer length field in the item descriptor should specify 8 (bytes).Note that for volumes mounted in a cluster, only the time of the initial mount is recorded; the time of any subsequent mount is not recorded. DVI$_MOUNTCNTReturns 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$_MOUNTVER_ELIGIBLEOn Alpha and I64, returns an unsigned longword, which is interpreted as Boolean. A value of 1 indicates the volume is eligible to undergo mount verification. A volume mounted with either the /FOREIGN or /NOMOUNT_VERIFICATION qualifier is not subject to mount verification.DVI$_MPDEV_AUTO_PATH_SW_CNTOn Alpha and I64, returns as an unsigned longword the number of times a multipath device has automatically switched paths due to an I/O error, or as the result of automatically "failing back" to a local path from a remote path after the local path became available.DVI$_MPDEV_CURRENT_PATHOn Alpha and I64, returns the current path name for multipath devices as a string.If the device is not part of a multipath set, $GETDVI will return the name of the device path if the class driver for this device supports path names. SYS$DKDRIVER, SYS$DUDRIVER, SYS$MKDRIVER, and SYS$GKDRIVER support path names. If the class driver for the device does not support path names, $GETDVI returns a null string. DVI$_MPDEV_MAN_PATH_SW_CNTOn Alpha and I64, returns as an unsigned longword the number of times a multipath device has manually switched paths due to a $SET DEVICE /PATH /SWITCH command or the use of the $SET_DEVICE system service.DVI$_MSCP_UNIT_NUMBERReturns the internal coded value for MSCP unit numbers as a longword integer. This item code is reserved to HP.DVI$_MT3_DENSITYReturns the density of the device. Valid for tapes only. This code is an unsigned longword integer.DVI$_MT3_SUPPORTEDThe 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$_MULTIPATHOn Alpha and I64, returns a longword, interpreted as Boolean. A value of 1 indicates the device is a member of a multipath set.DVI$_MVSUPMSGOn Alpha and I64, returns an unsigned longword, interpreted as Boolean. A value of 1 indicates that mount verification OPCOM messages are currently being suppressed on this device. See the MVSUPMSG_INTVL AND MVSUPMSG_NUM system parameters for more information on the suppression of mount verification messages.DVI$_NEXTDEVNAMReturns 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$_NOCACHE_ON_VOLUMEOn Alpha and I64, returns an unsigned longword, which is interpreted as Boolean. A value of 1 indicates the volume is mounted with all caching disabledDVI$_NOHIGHWATEROn Alpha and I64, returns an unsigned longword, which is interpreted as Boolean. A value of 1 indicates that high-water marking is disabled on the volume.DVI$_NOSHARE_MOUNTEDOn Alpha and I64, returns an unsigned longword, which is interpreted as Boolean. A value of 1 indicates the volume is mounted /NOSHARE.DVI$_ODS2_SUBSET0On Alpha and I64, returns an unsigned longword, which is interpreted as Boolean. A value of 1 indicates the volume supports only a subset of the ODS-2 file structure.DVI$_ODS5On Alpha and I64, returns an unsigned longword, which is interpreted as Boolean. A value of 1 indicates the volume is mounted ODS-5.DVI$_OPCNTReturns the operation count of the device as an unsigned longword. Note that the operation count might have been reset with the SET DEVICE/RESET=OPCNT command.
|