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, HP 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,
       HP 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).

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

    Though this argument is optional, HP 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 HP.

 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.