/sys$common/syshlp/helplib.hlb System Services, $GETDVI  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    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.

    Refer to the OpenVMS System Services Reference Manual to view the
    item code diagram and descriptor fields table.

 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:

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