VMS Help System Services, $GETQUI  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Returns information about queues and the jobs initiated from
    those queues.

    The $GETQUI service completes asynchronously; for synchronous
    completion, use the Get Queue Information and Wait ($GETQUIW)
    service.

    For additional information about system service completion, refer
    to the Synchronize ($SYNCH) service.

    Format

      SYS$GETQUI  [efn] ,func [,context] [,itmlst] [,iosb] [,astadr]

                  [,astprm]

    C Prototype

      int sys$getqui  (unsigned int efn, unsigned short int func,

                      unsigned int *context, void *itmlst, struct

                      _iosb *iosb, void (*astadr)(__unknown_params),

                      int astprm);

    Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag to be set when $GETQUI completes. The
    efn argument is a longword containing this number; however,
    $GETQUI uses only the low-order byte. The efn argument is
    optional.

    When the request is queued, $GETQUI clears the specified event
    flag (or event flag 0 if efn was not specified). Then, when the
    operation completes, $GETQUI sets the specified event flag (or
    event flag 0).

 func

    OpenVMS usage:function_code
    type:         word (unsigned)
    access:       read only
    mechanism:    by value
    Function code specifying the function that $GETQUI is to perform.
    The func argument is a word containing this function code. The
    $QUIDEF macro defines the names of each function code.

    You can specify only one function code in a single call to
    $GETQUI. Most function codes require or allow for additional
    information to be passed in the call. You pass this information
    by using the itmlst argument, which specifies a list of one or
    more item descriptors. Each item descriptor in turn specifies an
    item code, which either describes the specific information to be
    returned by $GETQUI, or otherwise affects the action designated
    by the function code.

    You can use wildcard mode to make a sequence of calls to $GETQUI
    to get information about all characteristics, form definitions,
    queues, or jobs contained in the system job queue file.

    Refer to the OpenVMS System Services Reference Manual for
    information on using wildcard mode.

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Address of a longword containing the number of a context stream
    for this call to the $GETQUI system service. If the argument is
    unspecified or 0, the service uses the default context stream
    (#0).

    To generate a new context stream, the specified longword must
    contain -1. $GETQUI then modifies the longword to hold the
    context number for that stream of operation. The context is
    marked with the caller's mode (user, supervisor, executive, or
    kernel). Any attempt to use that context in successive calls
    is checked and no call from a mode outside the recorded mode is
    allowed access.

    To clean up a context, make a $GETQUI call using the QUI$_CANCEL_
    OPERATION function code and specify the address of the context
    number as the context argument.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list supplying information to be used in performing the
    function specified by the func argument. The itmlst argument is
    the address of the item list. The item list consists of one or
    more item descriptors, each of which contains an item code. The
    item list is terminated by an item code of 0 or 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 into which $GETQUI writes the completion status
    after the requested operation has completed. The iosb argument is
    the address of the I/O status block.

    At request initiation, $GETQUI sets the value of the quadword I/O
    status block to 0. When the requested operation has completed,
    $GETQUI writes a condition value in the first longword of the
    I/O status block. It writes the value 0 into the second longword;
    this longword is unused and reserved for future use.

    The condition values returned by $GETQUI in the I/O status block
    are condition values from the JBC facility, which are defined by
    the $JBCMSGDEF macro. The condition values returned from the JBC
    facility are listed in the section Condition Values Returned in
    the I/O Status Block section.

    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 $GETQUI 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 $GETQUI, 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 $GETQUI completes. The
    astadr argument is the address of this routine.

    If specified, the AST routine executes at the same access mode as
    the caller of $GETQUI.

 astprm

    OpenVMS usage:user_parm
    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 this longword
    parameter.