VMS Help
Lexicals, F$GETQUI
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
|
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])
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 ("").
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. On
VAX, queue manager information is also available.
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_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 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_FILE Selects all job file
DISPLAY_JOB information about the
DISPLAY_QUEUE calling batch job, 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
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.
[legal]
[privacy]
[GNU]
[policy]
[netiquette]
[sponsors]
[FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.