Copyright Digital Equipment Corp. All rights reserved.
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).
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.
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.
For information on using wildcard mode, see the VSI OpenVMS System
Services Reference Manual.
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.
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 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, 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 $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.