|
HP OpenVMS Systems Documentation |
|
OpenVMS System Services Reference Manual
Note that, for terminals only, individual $GETDVI item codes are provided for most of the informational items returned in the DVI$_DEVDEPEND longword bit vector. The names of these item codes have the format DVI$_TT_xxxx, where xxxx is the characteristic name. The same characteristic name follows the underscore character in the symbolic name for each bit (defined by the $TTDEF macro) in the DVI$_DEVDEPEND longword. For example, the DVI$_TT_NOECHO item code returns the same information as that returned in the DVI$_DEVDEPEND bit whose symbolic name is TT$V_NOECHO. Each such item code requires that the buffer specify a longword value, which is interpreted as Boolean. A value of 0 indicates that the terminal does not have that characteristic; a value of 1 indicates that it does. The list of these terminal-specific item codes follows this list of item codes. DVI$_DEVDEPEND2Returns 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_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 the device name as a 64-byte, zero-filled string. The node name is also returned.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 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 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$_ERRCNTReturns the device's error count as an unsigned integer longword.DVI$_FC_NODE_NAMEDVI$_FC_PORT_NAMEReturns 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$_FREEBLOCKSReturns the number of free blocks on a disk as an unsigned integer longword. This item code is applicable only to disks.DVI$_FULLDEVNAMReturns 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_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. 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$_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$_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$_MSCP_UNIT_NUMBERReturns the internal coded value for MSCP unit numbers as a longword integer. This item code is reserved to Compaq.DVI$_MT3_DENSITYThe 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_SUPPORTEDReturns the density of the device. Valid for tapes only. This code is an unsigned longword integer.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$_OPCNTReturns the operation count for the volume as an unsigned integer longword.DVI$_OWNUICReturns the user identification code (UIC) of the owner of the device as a standard 4-byte UIC.DVI$_PIDReturns the process identification (PID) of the owner of the device as an unsigned integer longword.DVI$_PREFERRED_CPUThe 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$_RECSIZReturns the blocked record size as an unsigned integer longword.DVI$_REFCNTReturns the number of channels assigned to the device as an unsigned integer longword.DVI$_REMOTE_DEVICEReturns 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$_ROOTDEVNAMReturns 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$_SECTORSReturns the number of sectors per track as an unsigned integer longword. This item code is applicable only to disks.DVI$_SERIALNUMReturns the serial number of the volume as an unsigned integer longword. This item code is applicable only to disks.DVI$_SERVED_DEVICEReturns 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_COPYINGReturns 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_MEMBERReturns 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_MASTERReturns a longword, which is interpreted as Boolean. The value 1 indicates that the device is a virtual unit.DVI$_SHDW_MASTER_NAMEWhen 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.
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_MEMBERReturns a longword, which is interpreted as Boolean. The value 1 indicates that the device is a shadow set member.DVI$_SHDW_MERGE_COPYINGReturns 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_NAMEReturns 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.
Because a device name can include up to 64 characters, the buffer length field of the item descriptor should specify 64 (bytes). DVI$_STSReturns 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:
DVI$_TRACKSReturns the number of tracks per cylinder as an unsigned integer longword. This item code is applicable only to disks.DVI$_TRANSCNTReturns the transaction count for the volume as an unsigned integer longword.DVI$_TT_ACCPORNAMReturns 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_CHARSETReturns, 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:
DVI$_TT_CS_HANGULReturns 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_HANYUReturns 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_HANZIReturns 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_KANAReturns 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_KANJIReturns 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_THAIReturns 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_PHYDEVNAMReturns 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$_UNITReturns the unit number as an unsigned integer longword.DVI$_VOLCOUNTReturns the number of volumes in the volume set as an unsigned integer longword. This item code is applicable only to disks.DVI$_VOLNAMReturns the volume name as a 12-byte zero-filled string.DVI$_VOLNUMBERReturns the volume number of this volume in the volume set as an unsigned integer longword. This item code is applicable only to disks.DVI$_VOLSETMEMReturns 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$_VPROTReturns the volume protection mask as a standard 4-byte protection mask.DVI$_TT_xxxxDVI$_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$_WWIDReturns 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$_yyyyDVI$_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. DescriptionThe 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. |