Difference between revisions of "F$GETQUI()"

From VSI OpenVMS Wiki
Jump to: navigation, search
 
(12 intermediate revisions by 3 users not shown)
Line 1: Line 1:
'''F$GETQUI()''' is a [Lexical functions|lexical function]] that returns information about queues, including batch and print jobs currently in the queues, form definitions, characteristic definitions kept in the queue database, and queue managers. For most operations, read access is required.
+
'''F$GETQUI()''' is a [[Lexical functions|lexical function]] that returns information about queues, including batch and print jobs currently in the queues, form definitions, characteristic definitions kept in the queue database, and queue managers. For most operations, read access is required.
  
 
=Format=
 
=Format=
  
F$GETQUI (function,[[F$GETQUI()#item|[item]]],[[F$GETQUI()#object-id|[object-id]]],[[F$GETQUI()#flags|[flags]]])
+
F$GETQUI ([[F$GETQUI()#function|function]],[[F$GETQUI()#item|[item]]],[[F$GETQUI()#object-id|[object-id]]],[[F$GETQUI()#flags|[flags]]])
 
 
 
 
  
 
Brackets ([]) denote an optional argument. Some function arguments cannot be specified with the item-code, the object-id, or the flags argument; visit the [[F$GETQUI()#function|function section]] below for more information.
 
Brackets ([]) denote an optional argument. Some function arguments cannot be specified with the item-code, the object-id, or the flags argument; visit the [[F$GETQUI()#function|function section]] below for more information.
Line 19: Line 17:
 
! Function  !! Description
 
! Function  !! Description
 
|-
 
|-
| CANCEL_OPERATION || Terminates any wildcard operation that may have been initiated by a previous call to F$GETQUI.
+
| [[CANCEL_OPERATION]] || Terminates any wildcard operation that may have been initiated by a previous call to F$GETQUI.
 
|-
 
|-
| DISPLAY_CHARACTERISTIC || Returns information about a specific characteristic definition or the next characteristic definition in a wildcard operation.
+
| [[DISPLAY_CHARACTERISTIC]] || Returns information about a specific 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_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 [[F$GETQUI Context|queue context]]; DISPLAY_ENTRY does not require that [[F$GETQUI Context|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_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_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_JOB]] || Returns information about the next job defined for the current [[F$GETQUI Context|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 [[F$GETQUI Context|queue context]]; DISPLAY_ENTRY does not require that [[F$GETQUI Context|queue context]] be established.
 
|-
 
|-
| DISPLAY_MANAGER || Returns information about a specific queue manager or the next queue manager in a wildcard operation.
+
| [[DISPLAY_MANAGER]] || Returns information about a specific [[Queue manager|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.
+
| [[DISPLAY_QUEUE]] || Returns information about a specific [[Queue|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.
+
| [[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.
+
Some function arguments cannot be specified with the item-code, the object-id, or the flags argument. See the function pages for the exact syntax.
 +
 
 +
==item==
 +
 
 +
Corresponds to a [[$GETQUI output item codes|$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.
 +
 
 +
==object-id==
 +
 
 +
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 or in some cases the wildcard characters. Wildcards (asterisks (*) and percent signs (%)) are allowed with the following functions:
 +
 
 +
* DISPLAY_CHARACTERISTIC
 +
* DISPLAY_ENTRY
 +
* DISPLAY_FORM
 +
* DISPLAY_MANAGER
 +
* DISPLAY_QUEUE
 +
 
 +
A wildcard can represent only object names, not object numbers.  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.
 +
 
 +
==flags==
 +
 
 +
Specifies a list of keywords, separated by commas, that corresponds to the flags defined for the $GETQUI system service (see the table below). These flags are used to define the scope of the object search specified in the call to the $GETQUI system service. Note that the keywords can be used only with certain function codes; see the function pages for details.
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
! Function  !! Format Line
+
! Keyword  !! Valid Function Code !! Description
 
|-
 
|-
| CANCEL_OPERATION || F$GETQUI("CANCEL_OPERATION") or F$GETQUI(" ")
+
| 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.
 
|-
 
|-
| DISPLAY_CHARACTERISTIC || F$GETQUI("DISPLAY_CHARACTERISTIC", [item],object-id,[flags])
+
| BATCH
 +
|  
 +
* DISPLAY_QUEUE
 +
* DISPLAY_ENTRY
 +
| Selects batch queues.
 
|-
 
|-
| DISPLAY_ENTRY || F$GETQUI("DISPLAY_ENTRY",[item], [object-id],[flags])
+
| EXECUTING_JOBS
 +
|
 +
* DISPLAY_ENTRY  
 +
* DISPLAY_JOB
 +
| Selects executing jobs.
 
|-
 
|-
| DISPLAY_FILE || F$GETQUI("DISPLAY_FILE",[item],,[flags])
+
| FREEZE_CONTEXT
 +
|
 +
* DISPLAY_CHARACTERISTIC
 +
* DISPLAY_ENTRY
 +
* DISPLAY_FILE  
 +
* DISPLAY_FORM
 +
* DISPLAY_JOB
 +
* DISPLAY_MANAGER
 +
* DISPLAY_QUEUE
 +
| When in wildcard mode, prevents advance of wildcard context to the next object. If you do not specify this flag, the context is advanced to the next object.
 
|-
 
|-
| DISPLAY_FORM || F$GETQUI("DISPLAY_FORM",[item], object-id,[flags])
+
| GENERIC
 +
|  
 +
* DISPLAY_ENTRY
 +
* DISPLAY_QUEUE
 +
| Selects generic queues for searching.
 
|-
 
|-
| DISPLAY_JOB || F$GETQUI("DISPLAY_JOB",[item],,[flags])
+
| HOLDING_JOBS
 +
|
 +
* DISPLAY_ENTRY
 +
* DISPLAY_JOB  
 +
| Selects jobs on unconditional hold.
 
|-
 
|-
| DISPLAY_MANAGER || F$GETQUI("DISPLAY_MANAGER",[item],object-id,[flags])
+
| PENDING_JOBS
 +
|  
 +
* DISPLAY_ENTRY
 +
* DISPLAY_JOB
 +
| Selects pending jobs.
 
|-
 
|-
| DISPLAY_QUEUE || F$GETQUI("DISPLAY_QUEUE",[item],object-id,[flags])
+
| PRINTER
 +
|
 +
* DISPLAY_QUEUE  
 +
* DISPLAY_ENTRY
 +
| Selects printer queues.
 
|-
 
|-
| TRANSLATE_QUEUE || F$GETQUI("TRANSLATE_QUEUE",[item],object-id)
+
| RETAINED_JOBS
 +
|  
 +
* DISPLAY_ENTRY
 +
* DISPLAY_JOB
 +
| Selects jobs being retained.
 +
|-
 +
| SERVER
 +
|
 +
* DISPLAY_QUEUE
 +
* DISPLAY_ENTRY
 +
| Selects server queues.
 +
|-
 +
| SYMBIONT
 +
|
 +
* DISPLAY_QUEUE
 +
* DISPLAY_ENTRY
 +
| Selects all output queues. Equivalent to specifying "PRINTER,SERVER,TERMINAL".
 +
|-
 +
| TERMINAL
 +
|
 +
* DISPLAY_QUEUE
 +
* DISPLAY_ENTRY
 +
| Selects terminal queues.
 +
|-
 +
| THIS_JOB
 +
|
 +
* DISPLAY_ENTRY
 +
* DISPLAY_FILE
 +
* DISPLAY_JOB
 +
* DISPLAY_QUEUE
 +
| Selects all job file information about the calling batch job (entry), the command file being executed, or the queue associated with the calling batch job.
 +
|-
 +
| TIMED_RELEASE_JOBS
 +
|
 +
* DISPLAY_ENTRY
 +
* DISPLAY_JOB
 +
| Selects jobs on hold until a specified time.
 +
|-
 +
| WILDCARD
 +
|
 +
* DISPLAY_CHARACTERISTIC
 +
* DISPLAY_ENTRY
 +
* DISPLAY_FORM
 +
* DISPLAY_MANAGER
 +
* DISPLAY_QUEUE
 +
| Establishes and saves a context. Because the context is saved, the next operation can be performed based on that context.
 
|}
 
|}
  
==item==
 
 
Corresponds to a [[$GETQUI output item codes|$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.
 
 
==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
+
=See also=
DISPLAY_ENTRY
+
* [http://www.migrationspecialties.com/pdf/VTJ_F$GETQUI.pdf| F$GETQUI to the Rescue, Bruce Claremont's article for OpenVMS Technical Journal V11]
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 codes|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 the keywords can be used only with certain function codes.
+
[[Category: Lexical Functions]]

Latest revision as of 15:35, 26 November 2019

F$GETQUI() is a lexical function that returns information about queues, including batch and print jobs currently in the queues, form definitions, characteristic definitions kept in the queue database, and queue managers. For most operations, read access is required.

Format

F$GETQUI (function,[item],[object-id],[flags])

Brackets ([]) denote an optional argument. Some function arguments cannot be specified with the item-code, the object-id, or the flags argument; visit the function section below for more information.

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_CHARACTERISTIC Returns information about a specific 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. See the function pages for the exact syntax.

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.

object-id

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 or in some cases the wildcard characters. Wildcards (asterisks (*) and percent signs (%)) are allowed with the following functions:

  • DISPLAY_CHARACTERISTIC
  • DISPLAY_ENTRY
  • DISPLAY_FORM
  • DISPLAY_MANAGER
  • DISPLAY_QUEUE

A wildcard can represent only object names, not object numbers. 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.

flags

Specifies a list of keywords, separated by commas, that corresponds to the flags defined for the $GETQUI system service (see the table below). These flags are used to define the scope of the object search specified in the call to the $GETQUI system service. Note that the keywords can be used only with certain function codes; see the function pages for details.

Keyword Valid Function 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
  • DISPLAY_ENTRY
Selects batch queues.
EXECUTING_JOBS
  • DISPLAY_ENTRY
  • DISPLAY_JOB
Selects executing jobs.
FREEZE_CONTEXT
  • DISPLAY_CHARACTERISTIC
  • DISPLAY_ENTRY
  • DISPLAY_FILE
  • DISPLAY_FORM
  • DISPLAY_JOB
  • DISPLAY_MANAGER
  • DISPLAY_QUEUE
When in wildcard mode, prevents advance of wildcard context to the next object. If you do not specify this flag, the context is advanced to the next object.
GENERIC
  • DISPLAY_ENTRY
  • DISPLAY_QUEUE
Selects generic queues for searching.
HOLDING_JOBS
  • DISPLAY_ENTRY
  • DISPLAY_JOB
Selects jobs on unconditional hold.
PENDING_JOBS
  • DISPLAY_ENTRY
  • DISPLAY_JOB
Selects pending jobs.
PRINTER
  • DISPLAY_QUEUE
  • DISPLAY_ENTRY
Selects printer queues.
RETAINED_JOBS
  • DISPLAY_ENTRY
  • DISPLAY_JOB
Selects jobs being retained.
SERVER
  • DISPLAY_QUEUE
  • DISPLAY_ENTRY
Selects server queues.
SYMBIONT
  • DISPLAY_QUEUE
  • DISPLAY_ENTRY
Selects all output queues. Equivalent to specifying "PRINTER,SERVER,TERMINAL".
TERMINAL
  • DISPLAY_QUEUE
  • DISPLAY_ENTRY
Selects terminal queues.
THIS_JOB
  • DISPLAY_ENTRY
  • DISPLAY_FILE
  • DISPLAY_JOB
  • DISPLAY_QUEUE
Selects all job file information about the calling batch job (entry), the command file being executed, or the queue associated with the calling batch job.
TIMED_RELEASE_JOBS
  • DISPLAY_ENTRY
  • DISPLAY_JOB
Selects jobs on hold until a specified time.
WILDCARD
  • DISPLAY_CHARACTERISTIC
  • DISPLAY_ENTRY
  • DISPLAY_FORM
  • DISPLAY_MANAGER
  • DISPLAY_QUEUE
Establishes and saves a context. Because the context is saved, the next operation can be performed based on that context.


See also