F$GETQUI Context

A context is a data structure used by the F$GETQUI lexical function that represents an element of the queue system such as a queue or job. A context can be established with certain calls to F$GETQUI and then used by other calls to select objects within that context such as jobs in a queue. The following F$GETQUI functions can be used to establish contexts:

• DISPLAY_CHARACTERISTIC
• DISPLAY_ENTRY
• DISPLAY_FILE
• DISPLAY_FORM
• DISPLAY_JOB
• DISPLAY_MANAGER
• DISPLAY_QUEUE

Establishing a Context

To establish a queue context, make a wildcard call to F$GETQUI using a DISPLAY_QUEUE function, for example:

$  QNAME = F$GETQUI("DISPLAY_QUEUE","QUEUE_NAME","*") 
 

Calls to F$GETQUI between this one and the next similar call will use the context of this queue. For example:

$ SHOW QUEUE

Batch queue QUEUE$ONE, idle, on SMAN43::

Generic printer queue SYS$PRINT

  Entry  Jobname         Username     Blocks  Status
  -----  -------         --------     ------  ------
     70  TEST1            JDOE         1     Pending
         (32 intervening jobs containing 65 blocks)
     71  TEST2            JDOE         3     Pending

$  QNAME = F$GETQUI("DISPLAY_QUEUE","QUEUE_NAME","*") 
$ SHOW SYM QNAME
  QNAME == "QUEUE$ONE"
$  NAME_ONE = F$GETQUI("DISPLAY_JOB","JOB_NAME",,"ALL_JOBS")
$ SHOW SYM NAME_ONE
  QNAME == ""
$  NAME_TWO = F$GETQUI("DISPLAY_JOB","JOB_NAME",,"ALL_JOBS")
$ SHOW SYM NAME_TWO
  QNAME == ""
$  QNAME = F$GETQUI("DISPLAY_QUEUE","QUEUE_NAME","*")
$ SHOW SYM QNAME
  QNAME == "SYS$PRINT"
$  NAME_THREE = F$GETQUI("DISPLAY_JOB","JOB_NAME",,"ALL_JOBS")
$ SHOW SYM NAME_THREE
  QNAME == "TEST1"
$  NAME_FOUR = F$GETQUI("DISPLAY_JOB","JOB_NAME",,"ALL_JOBS")
$ SHOW SYM NAME_FOUR
  QNAME == "TEST2"
 

SHOW QUEUE reveals that we have two queues, QUEUE$ONE and SYS$PRINT. QUEUE_ONE has no jobs in it and QUEUE$PRINT has two jobs pending. The first call to F$GETQUI establishes queue context of the first queue - QUEUE$ONE. All subsequent calls to F$GETQUI until the context is changed obtain information within that context, i.e. on that queue. There are two calls to DISPLAY_JOB, both return an empty string, because there are no jobs in that queue and therefore their names are empty strings. The second call to F$GETQUI advances queue context, so all subsequent calls operate within the context of SYS$PRINT rather that QUEUE$ONE. And since SYS$PRINT has jobs, we start seeing actual names for these jobs. Note that DISPLAY_JOB establishes job context; if we wanted to display additional information for job TEST1 - say, its entry number - that call would have to include the "FREEZE_CONTEXT" flag at the end, otherwise the job context would advance and you would get the entry number of TEST2 (71) rather than TEST1 (70):

$ QNAME = F$GETQUI("DISPLAY_QUEUE","QUEUE_NAME","*") $ SHOW SYM QNAME QNAME == "SYS$PRINT" $ NAME_THREE = F$GETQUI("DISPLAY_JOB","JOB_NAME",,"ALL_JOBS") $ SHOW SYM NAME_THREE QNAME == "TEST1" $ ENTRY = F$GETQUI("DISPLAY_JOB","ENTRY_NUMBER",,"ALL_JOBS") $ SHOW SYM ENTRY B = 71 Hex = 00000046 Octal = 00000000106

Preserving the Context

To preserve context, use the "FREEZE_CONTEXT" flag. It is available for all functions that establish context. Here is how it can be used to preserve job context:

$ SHOW QUEUE Batch queue QUEUE$ONE, idle, on SMAN43:: Generic printer queue SYS$PRINT Entry Jobname Username Blocks Status ----- ------- -------- ------ ------ 70 TEST1 JDOE 1 Pending (32 intervening jobs containing 65 blocks) 71 TEST2 JDOE 3 Pending $ QNAME = F$GETQUI("DISPLAY_QUEUE","QUEUE_NAME","*") $ SHOW SYM QNAME QNAME == "SYS$PRINT" $ NAME_THREE = F$GETQUI("DISPLAY_JOB","JOB_NAME",,"ALL_JOBS") $ SHOW SYM NAME_THREE QNAME == "TEST1" $ ENTRY = F$GETQUI("DISPLAY_JOB","ENTRY_NUMBER",,"FREEZE_CONTEXT") $ SHOW SYM ENTRY B = 70 Hex = 00000046 Octal = 00000000106

In the example above, NAME_THREE = F$GETQUI("DISPLAY_JOB","JOB_NAME",,"ALL_JOBS") is used to establish job context of job TEST1 with entry number 70. The subsequent call uses the "FREEZE_CONTEXT" flag, so the context remains that of TEST1 and its entry number (70) is displayed. Had that flag not been used, the job context would advance and the entry number of the next job (TEST2; 72) would be displayed - that is illustrated at the end of the section above.

Cancelling a Context

A context can be cancelled with a call to F$GETQUI CANCEL_OPERATION function:

a = f$getqui("CANCEL_OPERATION")
 

The symbol does not matter. It is recommeded to do this every time before establishing a new context to make sure that no contexts that may have been established by the previous command procedures interfere with it.