OpenVMS System Services Reference Manual

Document revision date: 19 July 1999

OpenVMS System Services Reference Manual

Contents

Index

$GETDVI

Returns information related to the primary and secondary device characteristics of an I/O device.
For synchronous completion, use the Get Device/Volume Information and Wait ($GETDVIW) service. The $GETDVIW service is identical to the $GETDVI service in every way except that $GETDVIW returns to the caller with the requested information.
For additional information about system service completion, refer to the Synchronize ($SYNCH) service.

Format

SYS$GETDVI [efn] ,[chan] ,[devnam] ,itmlst [,iosb] [,astadr] [,astprm] [,nullarg]

C Prototype

int sys$getdvi (unsigned int efn, unsigned short int chan, void *devnam, void *itmlst, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm, struct _generic_64 *nullarg);

Arguments

efn

OpenVMS usage: ef_number

type: longword (unsigned)

access: read only

mechanism: by value

Number of the event flag to be set when $GETDVI returns the requested information. The efn argument is a longword containing this number; however, $GETDVI uses only the low-order byte.
Upon request initiation, $GETDVI clears the specified event flag (or event flag 0 if efn was not specified). Then, when $GETDVI returns the requested information, it sets the specified event flag (or event flag 0).
chan

OpenVMS usage: channel

type: word (unsigned)

access: read only

mechanism: by value

Number of the I/O channel assigned to the device about which information is desired. The chan argument is a word containing this number.
To identify a device to $GETDVI, you can specify either the chan or devnam argument, but you should not specify both. If you specify both arguments, the chan argument is used.
If you specify neither chan nor devnam, $GETDVI uses a default value of 0 for chan.
devnam

OpenVMS usage: device_name

type: character-coded text string

access: read only

mechanism: by descriptor--fixed-length string descriptor

The name of the device about which $GETDVI is to return information. The devnam argument is the address of a character string descriptor pointing to this name string.
The device name string can be either a physical device name or a logical name. If the first character in the string is an underscore (_), the string is considered a physical device name; otherwise, the string is considered a logical name and logical name translation is performed until either a physical device name is found or the system default number of translations has been performed.
If the device name string contains a colon (:), the colon and the characters that follow it are ignored.
To identify a device to $GETDVI, you can specify either the chan or devnam argument, but you should not specify both. If both arguments are specified, the chan argument is used.
If you specify neither chan nor devnam, $GETDVI uses a default value of 0 for chan.
itmlst

OpenVMS usage: item_list_3

type: longword (unsigned)

access: read only

mechanism: by reference

Item list specifying which information about the device is to be returned. The itmlst argument is the address of a list of item descriptors, each of which describes an item of information. The list of item descriptors is terminated by a longword of 0. The following diagram depicts the format of a single item descriptor.

The following table defines the item descriptor fields.

Descriptor Field Definition

Buffer length A word containing a user-supplied integer specifying the length (in bytes) of the buffer in which $GETDVI is to write the information. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. If the value of buffer length is too long, $GETDVI truncates the data.

Item code A word containing a user-supplied symbolic code specifying the item of information that $GETDVI is to return. The $DVIDEF macro defines these codes. Each item code is described in the Item Codes section.

Buffer address A longword containing the user-supplied address of the buffer in which $GETDVI is to write the information.

Return length address A longword containing the user-supplied address of a word in which $GETDVI is to write the information.

Descriptor Field	Definition
Buffer length	A word containing a user-supplied integer specifying the length (in bytes) of the buffer in which $GETDVI is to write the information. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. If the value of buffer length is too long, $GETDVI truncates the data.
Item code	A word containing a user-supplied symbolic code specifying the item of information that $GETDVI is to return. The $DVIDEF macro defines these codes. Each item code is described in the Item Codes section.
Buffer address	A longword containing the user-supplied address of the buffer in which $GETDVI is to write the information.
Return length address	A longword containing the user-supplied address of a word in which $GETDVI is to write the information.

iosb

OpenVMS usage:	io_status_block
type:	quadword (unsigned)
access:	write only
mechanism:	by reference

I/O status block that is to receive the final completion status. The iosb argument is the address of the quadword I/O status block.

When you specify the iosb argument, $GETDVI sets the quadword to 0 upon request initiation. Upon request completion, a condition value is returned to the first longword; the second longword is reserved to Compaq.

Though this argument is optional, Compaq strongly recommends that you specify it, for the following reasons:

If you are using an event flag to signal the completion of the service, you can test the I/O status block for a condition value to be sure that the event flag was not set by an event other than service completion.
If you are using the $SYNCH service to synchronize completion of the service, the I/O status block is a required argument for $SYNCH.
The condition value returned in R0 and the condition value returned in the I/O status block provide information about different aspects of the call to the $GETDVI service. The condition value returned in R0 gives you information about the success or failure of the service call itself; the condition value returned in the I/O status block gives you information about the success or failure of the service operation. Therefore, to accurately assess the success or failure of the call to $GETDVI, you must check the condition values returned in both R0 and the I/O status block.

astadr

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by reference

AST service routine to be executed when $GETDVI completes. The astadr argument is the address of this routine.

If you specify astadr, the AST routine executes at the same access mode as the caller of the $GETDVI service.

astprm

OpenVMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

AST parameter to be passed to the AST service routine specified by the astadr argument. The astprm argument is the longword parameter.

nullarg

OpenVMS usage:	null_arg
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

Placeholding argument reserved to Compaq.

Item Codes

DVI$_ACPPID
When you specify DVI$_ACPPID, $GETDVI returns the ACP process ID as an unsigned integer longword.
DVI$_ACPTYPE
When you specify DVI$_ACPTYPE, $GETDVI returns the ACP type code as an unsigned integer longword. The following symbols define each of the ACP type codes that $GETDVI can return.

Symbol Description

DVI$C_ACP_F11V1 Files-11 Level 1

DVI$C_ACP_F11V2 Files-11 Level 2

DVI$C_ACP_F11V5 Files-11 Level 5

DVI$C_ACP_MTA Magnetic tape

DVI$C_ACP_NET Networks

DVI$C_ACP_REM Remote I/O

DVI$_ALLDEVNAM
When you specify DVI$_ALLDEVNAM, $GETDVI returns the allocation-class device name, which is a 64-byte string. The allocation-class device name uniquely identifies each device that is currently connected to any node in an OpenVMS Cluster system or to a single-node system. This item code generates a single unique name for a device even if the device is dual ported.
One use for the allocation-class device name might be in 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 allocation-class device name of the device.
Note that the name returned by the DVI$_DEVLOCKNAM item code should be used to coordinate access to volumes.
DVI$_ALLOCLASS
When you specify DVI$_ALLOCLASS, $GETDVI 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, refer to OpenVMS Cluster Systems.
DVI$_ALT_HOST_AVAIL
When you specify DVI$_ALT_HOST_AVAIL, $GETDVI 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 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_NAME
When you specify DVI$_ALT_HOST_NAME, $GETDVI returns 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_TYPE
When you specify DVI$_ALT_HOST_TYPE, $GETDVI returns, as a 4-byte string, the hardware type of the host serving the alternate path. Each hardware type has a symbolic name.
The following table shows each symbolic name and the host it denotes on VAX systems.

Name Host

VAX Any VAX family processor

HS50 HSC50

HS70 HSC70

The following table shows each symbolic name and the host it denotes on Alpha systems.

Name Host

Alpha Any Alpha family processor

HS50 HSC50

HS70 HSC70

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$_CLUSTER
When you specify DVI$_CLUSTER, $GETDVI returns the volume cluster size as an unsigned integer longword. This item code is applicable only to disks.
DVI$_CYLINDERS
When you specify DVI$_CYLINDERS, $GETDVI returns the number of cylinders on the volume as an unsigned integer longword. This item code is applicable only to disks.
DVI$_DEVBUFSIZ
When you specify DVI$_DEVBUFSIZ, $GETDVI 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
When you specify DVI$_DEVCHAR, $GETDVI 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 DAA 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
When you specify DVI$_DEVCHAR2, $GETDVI 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 an SCSI device.

DEV$V_WLG Device has write-logging capability.

DEV$V_NOFE Device does not support forced error.

DVI$_DEVCLASS
When you specify DVI$_DEVCLASS, $GETDVI 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

DVI$_DEVDEPEND
When you specify DVI$_DEVDEPEND, $GETDVI returns device-dependent characteristics as a 4-byte bit vector. To determine what information is returned for a particular device, refer to the 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
When you specify DVI$_DEVDEPEND2, $GETDVI 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
When you specify DVI$_DEVICE_TYPE_NAME, $GETDVI returns a string identifying the type of device about which information was requested.
DVI$_DEVLOCKNAM
When you specify DVI$_DEVLOCKNAM, $GETDVI 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
When you specify DVI$_DEVNAM, $GETDVI returns the device name as a 64-byte, zero-filled string. The node name is also returned.
DVI$_DEVSTS
When you specify DVI$_DEVSTS, $GETDVI 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
When you specify DVI$_DEVTYPE, $GETDVI returns the device type as an unsigned integer longword. The $TTDEF macro defines symbols for the device types.
DVI$_DFS_ACCESS
When you specify DVI$_DFS_ACCESS, $GETDVI 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.

Previous Next Contents Index

privacy and legal statement

4527PRO_041.HTML

OpenVMS usage:	ef_number
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	channel
type:	word (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	device_name
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

OpenVMS usage:	item_list_3
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Symbol	Description
DVI$C_ACP_F11V1	Files-11 Level 1
DVI$C_ACP_F11V2	Files-11 Level 2
DVI$C_ACP_F11V5	Files-11 Level 5
DVI$C_ACP_MTA	Magnetic tape
DVI$C_ACP_NET	Networks
DVI$C_ACP_REM	Remote I/O

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 DAA 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.

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 an SCSI device.
DEV$V_WLG	Device has write-logging capability.
DEV$V_NOFE	Device does not support forced error.

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