Returns information about queues, including batch and print jobs
currently in the queues, form definitions, and characteristic
definitions kept in the queue database.
Also returns information about queue managers.
For most operations, read (R) access is required.
Format
F$GETQUI(function,[item],[object-id],[flags])
1 – Return Value
Either an integer or a character string, depending on the item
you request. For items that return a Boolean value, the string
is TRUE or FALSE. If the $GETQUI system service returns an error
code, F$GETQUI returns a null string ("").
2 – Arguments
function
Specifies the action that the F$GETQUI lexical function is to
perform. F$GETQUI supports all functions that can be specified
with the $GETQUI system service. The following table lists these
functions:
Function Description
CANCEL_OPERATION Terminates any wildcard operation that may
have been initiated by a previous call to
F$GETQUI.
DISPLAY_ Returns information about a specific
CHARACTERISTIC characteristic definition or the next
characteristic definition in a wildcard
operation.
DISPLAY_ENTRY Returns information about a specific job
entry or the next job entry that matches
the selection criteria in a wildcard
operation. The DISPLAY_ENTRY function code
is similar to the DISPLAY_JOB function
code in that both return job information.
DISPLAY_JOB, however, requires that a
call be made to establish queue context;
DISPLAY_ENTRY does not require that queue
context be established. Only those entries
that match the user-name of the current
process will be processed.
DISPLAY_FILE Returns information about the next file
defined for the current job context. Before
you make a call to F$GETQUI to request
file information, you must make a call to
display queue and job information (with
the DISPLAY_QUEUE and DISPLAY_JOB function
codes) or to display entry information
(with the DISPLAY_ENTRY function code).
DISPLAY_FORM Returns information about a specific form
definition or the next form definition in a
wildcard operation.
DISPLAY_JOB Returns information about the next job
defined for the current queue context.
Before you make a call to F$GETQUI to
request job information, you must make a
call to display queue information (with
the DISPLAY_QUEUE function code). The
DISPLAY_JOB function code is similar to
the DISPLAY_ENTRY function code in that
both return job information. DISPLAY_JOB,
however, requires that a call be made to
establish queue context; DISPLAY_ENTRY
does not require that queue context be
established.
DISPLAY_MANAGER Returns information about a specific queue
manager or the next queue manager in a
wildcard operation.
DISPLAY_QUEUE Returns information about a specific queue
definition or the next queue definition in
a wildcard operation.
TRANSLATE_QUEUE Translates a logical name for a queue to
the equivalence name for the queue.
Some function arguments cannot be specified with the item-
code, the object-id, or the flags argument. The following table
lists each function argument and corresponding format line to
show whether the item-code, object-id, and flags arguments
are required, optional, or not applicable for that specific
function. In the following format lines, brackets ([ ]) denote
an optional argument. An omitted argument means the argument is
not applicable for that function. Note that two commas (,,) must
be used as placeholders to denote an omitted (whether optional or
not applicable) argument.
Function Format Line
CANCEL_ F$GETQUI("CANCEL_OPERATION") or F$GETQUI(" ")
OPERATION
DISPLAY_ F$GETQUI("DISPLAY_CHARACTERISTIC",
CHARACTERISTIC [item],object-id,[flags])
DISPLAY_ENTRY F$GETQUI("DISPLAY_ENTRY",[item], [object-
id],[flags])
DISPLAY_FILE F$GETQUI("DISPLAY_FILE",[item],,[flags])
DISPLAY_FORM F$GETQUI("DISPLAY_FORM",[item], object-
id,[flags])
DISPLAY_JOB F$GETQUI("DISPLAY_JOB",[item],,[flags])
DISPLAY_MANAGER F$GETQUI("DISPLAY_MANAGER",[item],object-
id,[flags])
DISPLAY_QUEUE F$GETQUI("DISPLAY_QUEUE",[item],object-
id,[flags])
TRANSLATE_QUEUE F$GETQUI("TRANSLATE_QUEUE",[item],object-id)
item
Corresponds to a $GETQUI system service output item code. The
item argument specifies the kind of information you want returned
about a particular queue, job, file, form, or characteristic.
These are the item codes:
ACCOUNT_NAME AFTER_TIME ASSIGNED_QUEUE_NAME
AUTOSTART_ON BASE_PRIORITY CHARACTERISTICS
CHARACTERISTIC_NAME CHARACTERISTIC_NUMBER CHECKPOINT_DATA
CLI COMPLETED_BLOCKS CONDITION_VECTOR
CPU_DEFAULT CPU_LIMIT DEFAULT_FORM_NAME
DEFAULT_FORM_STOCK DEVICE_NAME ENTRY_NUMBER
EXECUTING_JOB_COUNT FILE_BURST FILE_CHECKPOINTED
FILE_COPIES FILE_COPIES_DONE FILE_COUNT
FILE_DELETE FILE_DEVICE FILE_DID
FILE_DOUBLE_SPACE FILE_EXECUTING FILE_FLAG
FILE_FLAGS FILE_IDENTIFICATION FILE_PAGE_HEADER
FILE_PAGINATE FILE_PASSALL FILE_SETUP_MODULES
FILE_SPECIFICATION FILE_STATUS FILE_TRAILER
FIRST_PAGE FORM_DESCRIPTION FORM_FLAGS
FORM_LENGTH FORM_MARGIN_BOTTOM FORM_MARGIN_LEFT
FORM_MARGIN_RIGHT FORM_MARGIN_TOP FORM_NAME
FORM_NUMBER FORM_SETUP_MODULES FORM_SHEET_FEED
FORM_STOCK FORM_TRUNCATE FORM_WIDTH
FORM_WRAP GENERIC_TARGET HOLDING_JOB_COUNT
INTERVENING_BLOCKS INTERVENING_JOBS JOB_ABORTING
JOB_COMPLETION_QUEUE JOB_COMPLETION_TIME JOB_COPIES
JOB_COPIES_DONE JOB_CPU_LIMIT JOB_ERROR_RETENTION
JOB_EXECUTING JOB_FILE_BURST JOB_FILE_BURST_ONE
JOB_FILE_FLAG JOB_FILE_FLAG_ONE JOB_FILE_PAGINATE
JOB_FILE_TRAILER JOB_FILE_TRAILER_ONE JOB_FLAGS
JOB_HOLDING JOB_INACCESSIBLE JOB_LIMIT
JOB_LOG_DELETE JOB_LOG_NULL JOB_LOG_SPOOL
JOB_LOWERCASE JOB_NAME JOB_NOTIFY
JOB_PENDING JOB_PID JOB_REFUSED
JOB_RESET_MODULES JOB_RESTART JOB_RETAINED
JOB_RETENTION JOB_RETENTION_TIME JOB_SIZE
JOB_SIZE_MAXIMUM JOB_SIZE_MINIMUM JOB_STALLED
JOB_STARTING JOB_STATUS JOB_SUSPENDED
JOB_TIMED_RELEASE JOB_WSDEFAULT JOB_WSEXTENT
JOB_WSQUOTA LAST_PAGE LIBRARY_SPECIFICATION
LOG_QUEUE LOG_SPECIFICATION MANAGER_NAME
MANAGER_NODE MANAGER_STATUS NOTE
OPERATOR_REQUEST OWNER_UIC PAGE_SETUP_MODULES
PARAMETER_1 to PARAMETER_8 ENDING_JOB_BLOCK_COUNT PENDING_JOB_COUNT
PENDING_JOB_REASON PEND_CHAR_MISMATCH PEND_JOB_SIZE_MAX
PEND_JOB_SIZE_MIN PEND_LOWERCASE_MISMATCH PEND_NO_ACCESS
PEND_QUEUE_BUSY PEND_QUEUE_STATE PEND_STOCK_MISMATCH
PRIORITY PROCESSOR PROTECTION
QUEUE_ACL_SPECIFIED QUEUE_ALIGNING QUEUE_AUTOSTART
QUEUE_AUTOSTART_INACTIVE QUEUE_AVAILABLE QUEUE_BATCH
QUEUE_BUSY QUEUE_CLOSED QUEUE_CPU_DEFAULT
QUEUE_CPU_LIMIT QUEUE_DESCRIPTION QUEUE_DIRECTORY
QUEUE_FILE_BURST QUEUE_FILE_BURST_ONE QUEUE_FILE_FLAG
QUEUE_FILE_FLAG_ONE QUEUE_FILE_PAGINATE QUEUE_FILE_TRAILER
QUEUE_FILE_TRAILER_ONE QUEUE_FLAGS QUEUE_GENERIC
QUEUE_GENERIC_SELECTION QUEUE_IDLE QUEUE_JOB_BURST
QUEUE_JOB_FLAG QUEUE_JOB_SIZE_SCHED QUEUE_JOB_TRAILER
QUEUE_LOWERCASE QUEUE_NAME QUEUE_PAUSED
QUEUE_PAUSING QUEUE_PRINTER QUEUE_RECORD_BLOCKING
QUEUE_REMOTE QUEUE_RESETTING QUEUE_RESUMING
QUEUE_RETAIN_ALL QUEUE_RETAIN_ERROR QUEUE_SERVER
QUEUE_STALLED QUEUE_STARTING QUEUE_STATUS
QUEUE_STOP_PENDING QUEUE_STOPPED QUEUE_STOPPING
QUEUE_SWAP QUEUE_TERMINAL QUEUE_UNAVAILABLE
QUEUE_WSDEFAULT QUEUE_WSEXTENT QUEUE_WSQUOTA
RAD REQUEUE_QUEUE_NAME RESTART_QUEUE_NAME
RETAINED_JOB_COUNT SCSNODE_NAME SECURITY_INACCESSIBLE
SUBMISSION_TIME TIMED_RELEASE_JOB_COUNT UIC
USERNAME WSDEFAULT WSEXTENT
WSQUOTA
object-id
Corresponds to the $GETQUI system service QUI$SEARCH_NAME, QUI$_
SEARCH_NUMBER, and QUI$_SEARCH_JOB_NAME input item codes. The
object-id argument specifies either the name or the number of
an object (for example, a specific queue name, job name, or
form number) about which F$GETQUI is to return information. The
asterisk (*) and the percent sign (%) wildcard characters are
allowed for the following functions:
DISPLAY_CHARACTERISTIC
DISPLAY_ENTRY
DISPLAY_FORM
DISPLAY_MANAGER
DISPLAY_QUEUE
By specifying an asterisk (*) or percent sign (%) wildcard
character as the object-id argument on successive calls, you
can get status information about one or more jobs in a specific
queue or about files within jobs in a specific queue. When a name
is used with wildcard characters, each call returns information
for the next object (queue, form, and so on) in the list. A null
string ("") is returned when the end of the list is reached. A
wildcard can represent only object names, not object numbers.
flags
Specifies a list of keywords, separated by commas, that
corresponds to the flags defined for the $GETQUI system service
QUI$_SEARCH_FLAGS input item code. (These flags are used to
define the scope of the object search specified in the call to
the $GETQUI system service.) Note that keywords in the following
table can be used only with certain function codes.
Valid Function
Keyword Code Description
ALL_JOBS DISPLAY_JOB Requests that F$GETQUI
search all jobs included
in the established queue
context. If you do not
specify this flag, F$GETQUI
returns information only
about jobs that have the
same user name as the
caller.
BATCH DISPLAY_QUEUE Selects batch queues.
DISPLAY_ENTRY
EXECUTING_JOBS DISPLAY_ENTRY Selects executing jobs.
DISPLAY_JOB
FREEZE_CONTEXT DISPLAY_ When in wildcard mode,
CHARACTERISTIC prevents advance of wildcard
DISPLAY_ENTRY context to the next object.
DISPLAY_FILE If you do not specify
DISPLAY_FORM this flag, the context is
DISPLAY_JOB advanced to the next object.
DISPLAY_MANAGER
DISPLAY_QUEUE
GENERIC DISPLAY_ENTRY Selects generic queues for
DISPLAY_QUEUE searching.
HOLDING_JOBS DISPLAY_ENTRY Selects jobs on
DISPLAY_JOB unconditional hold.
PENDING_JOBS DISPLAY_ENTRY Selects pending jobs.
DISPLAY_JOB
PRINTER DISPLAY_QUEUE Selects printer queues.
DISPLAY_ENTRY
RETAINED_JOBS DISPLAY_ENTRY Selects jobs being retained.
DISPLAY_JOB
SERVER DISPLAY_QUEUE Selects server queues.
DISPLAY_ENTRY
SYMBIONT DISPLAY_QUEUE Selects all output queues.
DISPLAY_ENTRY Equivalent to specifying
"PRINTER,SERVER,TERMINAL".
TERMINAL DISPLAY_QUEUE Selects terminal queues.
DISPLAY_ENTRY
THIS_JOB DISPLAY_ENTRY Selects all job file
DISPLAY_FILE information about the
DISPLAY_JOB calling batch job (entry),
DISPLAY_QUEUE the command file being
executed, or the queue
associated with the calling
batch job.
TIMED_RELEASE_ DISPLAY_ENTRY Selects jobs on hold until a
JOBS DISPLAY_JOB specified time.
WILDCARD DISPLAY_ Establishes and saves a
CHARACTERISTIC context. Because the context
DISPLAY_ENTRY is saved, the next operation
DISPLAY_FORM can be performed based on
DISPLAY_MANAGER that context.
DISPLAY_QUEUE
3 – Examples
1.$ BLOCKS = F$GETQUI("DISPLAY_ENTRY" ,"JOB_SIZE", 1347)
In this example, the F$GETQUI lexical function is used to
obtain the size in blocks of print job 1347. The value returned
reflects the total number of blocks occupied by the files
associated with the job.
2.$ IF F$GETQUI("DISPLAY_QUEUE", "QUEUE_STOPPED", "VAX1_BATCH") .EQS.
"TRUE" THEN GOTO 500
In this example, the F$GETQUI lexical function is used to
return a value of TRUE or FALSE depending on whether the queue
VAX1_BATCH is in a stopped state. If VAX1_BATCH is not in the
system, F$GETQUI returns a null string ("").
3.! This command procedure shows all queues and the jobs in them.
$ TEMP = F$GETQUI("")
$ QLOOP:
$ QNAME = F$GETQUI("DISPLAY_QUEUE","QUEUE_NAME","*")
$ IF QNAME .EQS. "" THEN EXIT
$ WRITE SYS$OUTPUT ""
$ WRITE SYS$OUTPUT "QUEUE: ", QNAME
$ JLOOP:
$ NOACCESS = F$GETQUI("DISPLAY_JOB","JOB_INACCESSIBLE",,"ALL_JOBS")
$ IF NOACCESS .EQS. "TRUE" THEN GOTO JLOOP
$ IF NOACCESS .EQS. "" THEN GOTO QLOOP
$ JNAME = F$GETQUI("DISPLAY_JOB","JOB_NAME",,"FREEZE_CONTEXT")
$ WRITE SYS$OUTPUT " JOB: ", JNAME
$ GOTO JLOOP
This sample command procedure displays all the queues in the
system and all the jobs to which the user has read access
in the system. In the outer loop a wildcard display queue
operation is performed. No call is made to establish the right
to obtain information about the queue, because all users have
implicit read access to queue attributes. Because a wildcard
queue name is specified ("*"), wildcard queue context is
maintained across calls to F$GETQUI.
In the inner loop, to obtain information about all jobs, we
enter nested wildcard mode from wildcard display queue mode.
In this loop, a call is made to establish the right to obtain
information about these jobs because users do not have implicit
read access to jobs. The FREEZE_CONTEXT keyword is used in
the request for a job name to prevent the advance of the
wildcard context to the next object. After the job name has
been retrieved and displayed, the procedure loops back up for
the next job. The context is advanced because the procedure has
not used the FREEZE_CONTEXT keyword. The wildcard queue context
is dissolved when the list of matching queues is exhausted.
Finally, F$GETQUI returns a null string ("") to denote that no
more objects match the specified search criteria.
4.$ THIS_NODE = F$EDIT(F$GETSYI("SCSNODE"),"COLLAPSE")
$ TEMP = F$GETQUI("CANCEL_OPERATION")
$ SET NOON
$LOOP:
$ QUEUE = F$GETQUI("DISPLAY_QUEUE","QUEUE_NAME","*","WILDCARD")
$ IF QUEUE .EQS. "" THEN GOTO ENDLOOP
$ IF THIS_NODE .EQS.-
F$GETQUI("DISPLAY_QUEUE","SCSNODE_NAME","*","WILDCARD,FREEZE_CONTEXT")
$ THEN
$ IF .NOT.-
F$GETQUI("DISPLAY_QUEUE","QUEUE_AUTOSTART","*","WILDCARD,FREEZE_CONTEXT")-
THEN START/QUEUE 'QUEUE'
$ ENDIF
$ GOTO LOOP
$ENDLOOP:
$ SET ON
This command procedure looks at all queues associated with the
local cluster node and starts any queue that is not marked as
autostart.
The procedure starts by obtaining the nodename of the local
system and clearing the F$GETQUI context. In addition, error
handling is turned off for the loop so that, if a queue had
been started previously, the resulting error from the START
QUEUE command does not abort the command procedure.
Inside the loop, the F$GETQUI function gets the next queue name
in the queue list. If the result is empty, then it has reached
the end of the list and it exits the loop.
The next IF statement checks to see if the queue runs on the
local node. If it does, then the next statement checks to see
if the queue is marked as an autostart queue. If that is false,
then the queue is started with the start command. The loop is
then repeated.
The final command of the procedure restores DCL error handling
to the previous setting.
5.$ IF p1.EQS."" THEN INQUIRE p1 "Queue name"
$ TEMP = F$GETQUI("")
$ QLOOP:
$ QNAME = F$GETQUI("DISPLAY_QUEUE","QUEUE_NAME",p1,"WILDCARD")
$ IF QNAME .EQS. "" THEN EXIT
$ WRITE SYS$OUTPUT ""
$ WRITE SYS$OUTPUT "QUEUE: ", QNAME
$ JLOOP:
$ RETAINED = F$GETQUI("DISPLAY_JOB","JOB_RETAINED",,"ALL_JOBS")
$ IF RETAINED .EQS. "" THEN GOTO QLOOP
$ Entry = F$GETQUI("DISPLAY_JOB","ENTRY_NUMBER",,"FREEZE_CONTEXT,ALL_JOBS")
$ WRITE SYS$OUTPUT " Entry: ''Entry' Retained: ''RETAINED'"
$ IF RETAINED.EQS."TRUE" THEN DELETE/ENTRY='Entry'
$ GOTO JLOOP
This command procedure deletes all retained entries from a
nominated queue or queues. Wildcards are allowed.
6.$ WRITE SYS$OUTPUT F$GETQUI("DISPLAY_QUEUE","RAD","BATCHQ1")
-1
This example returns the value of the RAD. A value of "-1"
indicates no RAD value is attributed to the queue.