Returns information related to the primary and secondary device
characteristics of an I/O device.
NOTE
All pathname-related information pertains only to Alpha and
Integrity server systems.
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, see
the Synchronize ($SYNCH) service.
NOTE ABOUT ITEM CODES
For item codes that return a string data type, failure to
pass in a buffer that is large enough to hold the returned
data results in silent data truncation. When $GETDVI
completes, VSI recommends that you check the returned length
field of an item list descriptor for each item code that
can return a string. If the returned length is equal to the
size of the buffer allocated to hold the returned data, the
data might have been truncated. In that case, call $GETDVI
iteratively with a larger buffer until the length of the
returned data is less than the size of the buffer allocated.
Unless the description of an item code specifies otherwise,
VSI recommends that you use a buffer of 32 bytes to hold
the returned string. $GETDVI pads the unused portion of the
buffer with null characters.
Format
SYS$GETDVI [efn] ,[chan] ,[devnam] ,itmlst [,iosb] [,astadr]
[,astprm] [,nullarg] [,pathname]
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,...);
1 – 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).
VSI strongly recommends the use of the EFN$C_ENF "no event flag"
value as the event flag if you are not using an event flag to
externally synchronize with the completion of this system service
call. The $EFNDEF macro defines EFN$C_ENF. For more information,
see the VSI OpenVMS Programming Concepts Manual.
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 do 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 do 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.
To view the item code diagram and descriptor fields table, see
the VSI OpenVMS System Services Reference Manual.
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 VSI.
Though this argument is optional, VSI strongly recommends that you
specify it, for the following reasons:
o 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.
o If you are using the $SYNCH service to synchronize completion
of the service, the I/O status block is a required argument
for $SYNCH.
o 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 VSI.
pathname
OpenVMS usage:path_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
On Alpha and Integrity server systems, the name of the path about
which $GETDVI is to return information. The pathname argument
is the address of a character string descriptor pointing to this
name string. The pathname can be used with either the chan or the
devnam argument.
Check the definitions of the item codes to see if the pathname
argument is used. In general, item codes that return information
that can vary by path make use of the pathname argument. Use
the SHOW DEVICE /FULL command, the SYS$DEVICE_PATH_SCAN system
service, or the F$MULTIPATH DCL lexical function to see the paths
for a multipath device.
If the pathname argument is used, it is validated against the
existing paths for the device specified. If the path does not
exist, the error SS$_NOSUCHPATH is returned, even if the item
code or codes used do not make use of the pathname argument.