F$GETQUI Context - Revision history

Jane.doe: Fixed some typos reported in Jon Pinkley's email

2023-12-20T10:18:58Z

Fixed some typos reported in Jon Pinkley's email

← Older revision		Revision as of 10:18, 20 December 2023
Line 80:		Line 80:
	$ NAME_THREE = F$GETQUI("DISPLAY_JOB","JOB_NAME",,"ALL_JOBS")		$ NAME_THREE = F$GETQUI("DISPLAY_JOB","JOB_NAME",,"ALL_JOBS")
	$ SHOW SYM NAME_THREE		$ SHOW SYM NAME_THREE
	~~QNAME~~ == "TEST1"		NAME_THREE == "TEST1"
	$ NAME_FOUR = F$GETQUI("DISPLAY_JOB","JOB_NAME",,"ALL_JOBS")		$ NAME_FOUR = F$GETQUI("DISPLAY_JOB","JOB_NAME",,"ALL_JOBS")
	$ SHOW SYM NAME_FOUR		$ SHOW SYM NAME_FOUR
	~~QNAME~~ == "TEST2"		NAME_FOUR == "TEST2"
	</nowiki>		</nowiki>

Jane.doe: fixed formatting as per comment by Jon Pinkley

2023-12-20T09:50:01Z

fixed formatting as per comment by Jon Pinkley

← Older revision		Revision as of 09:50, 20 December 2023
Line 90:		Line 90:
	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):		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):

	<nowiki>		<nowiki>
	$ QNAME = F$GETQUI("DISPLAY_QUEUE","QUEUE_NAME","*")		$ QNAME = F$GETQUI("DISPLAY_QUEUE","QUEUE_NAME","*")
	$ SHOW SYM QNAME		$ SHOW SYM QNAME
Line 100:		Line 100:
	$ SHOW SYM ENTRY		$ SHOW SYM ENTRY
	B = 71 Hex = 00000046 Octal = 00000000106		B = 71 Hex = 00000046 Octal = 00000000106
	</nowiki>		</nowiki>

	=Preserving the Context=		=Preserving the Context=
Line 106:		Line 106:
	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:		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:

	<nowiki>		<nowiki>

	$ SHOW QUEUE		$ SHOW QUEUE

Line 129:		Line 128:
	$ SHOW SYM ENTRY		$ SHOW SYM ENTRY
	B = 70 Hex = 00000046 Octal = 00000000106		B = 70 Hex = 00000046 Octal = 00000000106
	</nowiki>		</nowiki>

	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 [[F$GETQUI Context#Establishing a Context\|section above]].		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 [[F$GETQUI Context#Establishing a Context\|section above]].

Madsweeney at 23:03, 18 June 2020

2020-06-18T23:03:09Z

← Older revision		Revision as of 23:03, 18 June 2020
Line 21:		Line 21:
	Batch queue ZQ, idle, on IA10:: \| client process sends GQ to the queue manager in getqui_context		Batch queue ZQ, idle, on IA10:: \| client process sends GQ to the queue manager in getqui_context
	\| ZQ queue manager uses client passed GQ to lookup the next queue in the database		\| ZQ queue manager uses client passed GQ to lookup the next queue in the database
	Job summary: queue is empty \| queue manager finds ZQ, updates the context with GQ		Job summary: queue is empty \| queue manager finds ZQ, updates the context with ZQ
	\| queue manager returns ZQ to client in getqui_context		\| queue manager returns ZQ to client in getqui_context
	\|-----------------		\|-----------------

Madsweeney at 21:33, 18 June 2020

2020-06-18T21:33:13Z

Madsweeney at 21:31, 18 June 2020

2020-06-18T21:31:14Z

← Older revision		Revision as of 21:31, 18 June 2020
Line 1:		Line 1:
	A ~~'''~~context~~'''~~ is a ~~data structure used by~~ the [[F$GETQUI()\|F$GETQUI~~]] [[Lexical functions\|lexical function]]~~ that ~~represents an element of the~~ queue system ~~such as a [[Queue\|~~queue~~]] or [[Job\|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~~()~~#function~~\|F$~~GETQUI functions]] can be used~~ to ~~establish contexts:~~		A queue manager will receive requests simultaneously from many processes and from many different threads within a process. The queue manager must maintain context for all of the requesting threads on the cluster. A data structure called the GETQUI_CONTEXT is passed back and forth between a queue manager and a client to manage communication. The context maintains a "pointer" to tell a queue manager where to retrieve information for the next F$GETQUI call. Context is an opaque structure and is not user visible.

			Processes have one built-in queue context called the Default Context, context number 0 (zero). Whenever the context is omitted from a F$GETQUI call, context 0 is used. DCL commands that retrieve queue system information like SHOW QUEUE and SHOW ENTRY contain many sys$getqui() system services calls using the default context. Remembering queue commands use the default context is important for DCL programmers because it can cause unexpected results from F$GETQUI calls using the default context.

			An example may explain the concept of the context best.

			Suppose your system or cluster has 3 queues, AQ, GQ and ZQ. The SHOW QUEUE command below makes 4 sys$getqui() calls to retrieve the queue information to output on your device. The figure below illustrates the contents of the GETQUI_CONTEXT data structure during the four sys$getqui() calls. The default context is used the four sys$getqui() calls. The text to the left of the bars is the DCL input and output. To the right of the bar is the value of the GETQUI_CONTEXT value followed by a short description of the processing of the sys$getqui() call.
			<pre>

			SYSTEM IA10> show queue/summ %Q \|GETQUI_CONTEXT Description
			\| <null> client process sends null in getqui context
			Batch queue AQ, idle, on IA10:: \|
			\| AQ queue manager looks up the first queue in it's database
			Job summary: queue is empty \| queue manager returns AQ to client in getqui_context
			\|
			\| client process sends AQ to the queue manager in getqui_context
			Batch queue GQ, idle, on IA10:: \| queue manager uses client passed AQ to lookup the next queue in the database
			\| GQ queue manager finds GQ, updates the getqui_context with GQ
			Job summary: queue is empty \| queue manager returns GQ to client in getqui_context
			\|
			Batch queue ZQ, idle, on IA10:: \| client process sends GQ to the queue manager in getqui_context
			\| ZQ queue manager uses client passed GQ to lookup the next queue in the database
			Job summary: queue is empty \| queue manager finds ZQ, updates the context with GQ
			\| queue manager returns ZQ to client in getqui_context
			\|
			\| client process sends ZQ to the queue manager in getqui_context
			\| queue manager looks up the next queue in the database
			\| No queue found after ZQ
			\| Queue manager returns JBC-Q-NOMOREQUE
			</pre>

			When querying the queue system for information, the sys$getqui call message to the queue manager



	* DISPLAY_CHARACTERISTIC		* DISPLAY_CHARACTERISTIC

Jane.doe: Created page with "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..."

2019-11-26T15:02:13Z

Created page with "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..."

New page

A '''context''' is a data structure used by the [[F$GETQUI()|F$GETQUI]] [[Lexical functions|lexical function]] that represents an element of the queue system such as a [[Queue|queue]] or [[Job|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()#function|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:

<nowiki>
$ QNAME = F$GETQUI("DISPLAY_QUEUE","QUEUE_NAME","*")
</nowiki>

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

<nowiki>

$ 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"
</nowiki>

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):

<nowiki>
$ 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
</nowiki>

=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:

<nowiki>

$ 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
</nowiki>

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 [[F$GETQUI Context#Establishing a Context|section above]].

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

<nowiki>
a = f$getqui("CANCEL_OPERATION")
</nowiki>

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.

[[Category:Lexical Functions]]

← Older revision		Revision as of 21:33, 18 June 2020
Line 10:		Line 10:
	SYSTEM IA10> show queue/summ %Q \|GETQUI_CONTEXT Description		SYSTEM IA10> show queue/summ %Q \|GETQUI_CONTEXT Description
	\| <null> client process sends null in getqui context		\| <null> client process sends null in getqui context
	Batch queue AQ, idle, on IA10:: \|		Batch queue AQ, idle, on IA10:: \|-----------------
	\| AQ queue manager looks up the first queue in it's database		\| AQ queue manager looks up the first queue in it's database
	Job summary: queue is empty \| queue manager returns AQ to client in getqui_context		Job summary: queue is empty \| queue manager returns AQ to client in getqui_context
	\|		\|-----------------
	\| client process sends AQ to the queue manager in getqui_context		\| client process sends AQ to the queue manager in getqui_context
	Batch queue GQ, idle, on IA10:: \| queue manager uses client passed AQ to lookup the next queue in the database		Batch queue GQ, idle, on IA10:: \| queue manager uses client passed AQ to lookup the next queue in the database
	\| GQ queue manager finds GQ, updates the getqui_context with GQ		\| GQ queue manager finds GQ, updates the getqui_context with GQ
	Job summary: queue is empty \| queue manager returns GQ to client in getqui_context		Job summary: queue is empty \| queue manager returns GQ to client in getqui_context
	\|		\|-----------------
	Batch queue ZQ, idle, on IA10:: \| client process sends GQ to the queue manager in getqui_context		Batch queue ZQ, idle, on IA10:: \| client process sends GQ to the queue manager in getqui_context
	\| ZQ queue manager uses client passed GQ to lookup the next queue in the database		\| ZQ queue manager uses client passed GQ to lookup the next queue in the database
	Job summary: queue is empty \| queue manager finds ZQ, updates the context with GQ		Job summary: queue is empty \| queue manager finds ZQ, updates the context with GQ
	\| queue manager returns ZQ to client in getqui_context		\| queue manager returns ZQ to client in getqui_context
	\|		\|-----------------
	\| client process sends ZQ to the queue manager in getqui_context		\| client process sends ZQ to the queue manager in getqui_context
	\| queue manager looks up the next queue in the database		\| queue manager looks up the next queue in the database