370 lines
12 KiB
HTML
370 lines
12 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
|
<title>Query Governor Exit Program</title>
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
|
<!-- US Government Users Restricted Rights -->
|
|
<!-- Use, duplication or disclosure restricted by -->
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
|
<!-- Begin Header Records -->
|
|
<!-- Created for V5R4 on 050801 by Craig Aldrich -->
|
|
<!-- Change history: -->
|
|
<!-- 050801 CSA Created document, 3602.6 -->
|
|
<!-- End Header Records -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
<a name="Top_Of_Page"></a>
|
|
<!--Java sync-link-->
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
|
</script>
|
|
|
|
<h2><img src="v5r4delta.gif" alt="Start of change">Query Governor Exit Program</h2>
|
|
|
|
<div class="box" style="width: 70%;">
|
|
<br>
|
|
Required Parameter Group:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">1</td>
|
|
<td align="left" valign="top" width="50%">Query Governor Input
|
|
Information</td>
|
|
<td align="left" valign="top" width="20%">Input</td>
|
|
<td align="left" valign="top" width="20%">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">2</td>
|
|
<td align="left" valign="top" width="50%">Return Code</td>
|
|
<td align="left" valign="top" width="20%">Output</td>
|
|
<td align="left" valign="top" width="20%">Binary(4)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
Exit Point Name: QIBM_QQQ_QUERY_GOVR<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Exit Point Format Name: QRYG0100<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
QSYSINC Member Name: EQQQRYGV<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p> The Query Governor exit program is called when a job is running a query
|
|
and the estimated runtime or temporary storage usage has exceeded the user
|
|
specified limits. This exit is called in the job that is attempting to run the
|
|
query. The exit program is passed a structure that contains the estimated runtime,
|
|
the user specified runtime limit, the estimated temporary storage usage, and the
|
|
user specified temporary storage limit for the query. Also included is the
|
|
Structured Query Language (SQL) statement text of the query, if applicable.
|
|
The exit program may set a return code value that is basically used to either
|
|
ignore the exceeded limit and continue running the query or end the query request.
|
|
When a query is run, the operating system calls the user-written exit program
|
|
through the registration facility. For information about adding an exit program
|
|
to an exit point, see the <a href="reg1.htm">Registration Facility APIs</a>.</p>
|
|
|
|
<p>Only query full opens will call the exit program, thus if the query is the
|
|
result of an SQL statement, pseudo opens will not call the exit program. Also,
|
|
a query of a DDM file will not call the exit program on the source system, but
|
|
it could call the exit program on the target system. A native open of an SQL
|
|
view could call the exit program.</p>
|
|
|
|
<p>The Query Governor can be enabled by using the Query processing time limit
|
|
(QRYTIMLMT) or Query temporary storage limit (QRYSTGLMT) parameters on the
|
|
Change Query Attributes (CHGQRYA) CL command. It can also be enabled by setting
|
|
the QUERY_TIME_LIMIT or STORAGE_LIMIT options in the query options file. The
|
|
query time limit can also be enabled by using the QQRYTIMLMT system value.
|
|
</p>
|
|
|
|
<p>Authorities and Locks</p>
|
|
|
|
<dl>
|
|
<dt><em> User Profile Authority</em></dt>
|
|
|
|
<dd>*ALLOBJ and *SECADM to add or remove exit programs to the registration
|
|
facility<br>
|
|
<br>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3>Required Parameter Group</h3>
|
|
|
|
<dl>
|
|
<dt><b>Query Governor Input Information</b></dt>
|
|
|
|
<dd>INPUT;CHAR(*)<br>
|
|
|
|
<p>Information needed by the exit program with respect to the query that
|
|
exceeded user specified runtime or temporary storage usage limits. For the format
|
|
of this parameter, see <a href="#SQLR0100">QRYG0100 Format</a>.</p>
|
|
|
|
<br>
|
|
</dd>
|
|
</dl>
|
|
|
|
<dl>
|
|
<dt><b>Query Governor Output Information</b></dt>
|
|
|
|
<dd>OUTPUT;BINARY(4)<br>
|
|
<br>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p><strong>Return code. The return code to indicate whether the query should be
|
|
canceled. The valid values are:</strong></p>
|
|
|
|
<dl>
|
|
<dt><em>0</em></dt>
|
|
|
|
<dd>If it exists, the next exit program will be called allowing the query to still
|
|
be run to completion or cancelled without issuing the inquiry message CPA4259. If
|
|
this is the last exit program, the query will issue the CPA4259 inquiry message and
|
|
let the system or user handle the request. This is the initial default action.</dd>
|
|
|
|
<dt><em>1</em></dt>
|
|
|
|
<dd>If it exists, the next exit program will be called allowing the query to still
|
|
be cancelled without issuing the inquiry message. If this is the last exit program
|
|
or no other exit programs return a 3, the exceeded limit will be ignored and the
|
|
query will be allowed to run to completion. </dd>
|
|
|
|
<dt><em>2</em></dt>
|
|
|
|
<dd>Same as 1, except that the database monitor will also gather information about
|
|
the query if FTRQRYGOVR(*YES) is specified on the COMMENT parameter of the Start
|
|
Database Monitor (STRDBMON) command. See <a href="#Usage_Notes">Usage Notes</a> for
|
|
more information.</dd>
|
|
|
|
<dt><em>3</em></dt>
|
|
|
|
<dd>The query will be cancelled. Any remaining exit programs will not be called.</dd>
|
|
|
|
</dl>
|
|
|
|
<br>
|
|
<h3><a name="SQLR0100">QRYG0100 Format</a></h3>
|
|
|
|
<p>The following tables show the format of the input information parameter for
|
|
the exit program. For detailed descriptions of the fields in the table, see <a
|
|
href="#FieldDESCR">Field Descriptions</a>.</p>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th align="center" valign="bottom">Dec</th>
|
|
<th align="center" valign="bottom">Hex</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">0</td>
|
|
<td align="center" valign="top" width="10%">0</td>
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
|
<td align="left" valign="top" width="60%">Size of fixed header for QRYG0100</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">CHAR(8)</td>
|
|
<td align="left" valign="top">Format name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">12</td>
|
|
<td align="center" valign="top">C</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Job name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">22</td>
|
|
<td align="center" valign="top">16</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">User name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">32</td>
|
|
<td align="center" valign="top">20</td>
|
|
<td align="left" valign="top">CHAR(6)</td>
|
|
<td align="left" valign="top">Job number</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">38</td>
|
|
<td align="center" valign="top">26</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Current user name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">48</td>
|
|
<td align="center" valign="top">30</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Estimated runtime in seconds</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">52</td>
|
|
<td align="center" valign="top">34</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Specified time limit in seconds</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">56</td>
|
|
<td align="center" valign="top">38</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Estimated temporary storage usage in megabytes</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">60</td>
|
|
<td align="center" valign="top">3C</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Specified temporary storage limit in megabytes</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">64</td>
|
|
<td align="center" valign="top">40</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Offset to SQL statement text</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">68</td>
|
|
<td align="center" valign="top">44</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of SQL statement text</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">72</td>
|
|
<td align="center" valign="top">48</td>
|
|
<td align="left" valign="top">CHAR(*)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
<h3><a name="FieldDESCR">Field Descriptions</a></h3>
|
|
|
|
<p><strong>Current user name.</strong> The current user profile initiating the
|
|
query.</p>
|
|
|
|
<p><strong>Estimated runtime in seconds.</strong> The query's estimated runtime
|
|
in number of seconds.</p>
|
|
|
|
<p><strong>Estimated temporary storage usage in megabytes.</strong> The query's
|
|
estimated query temporary storage usage number in megabytes.</p>
|
|
|
|
<p><strong>Format name.</strong> The name of the format being used.</p>
|
|
|
|
<p><strong>Job name.</strong> The name of the job issuing the query request.</p>
|
|
|
|
<p><strong>Job number.</strong> The number of the job issuing the query
|
|
request.</p>
|
|
|
|
<p><strong>Length of SQL statement text.</strong> The length of the SQL statement
|
|
that exceeded the user specified query limit. 0 if the query is not SQL.</p>
|
|
|
|
<p><strong>Offset to SQL statement text.</strong> Offset from the start of the
|
|
Query Governor Input Information to the SQL statment that exceeded the user
|
|
specified query limit. 0 if the query is not SQL.</p>
|
|
|
|
<dl compact>
|
|
<dt><strong>Reserved.</strong> A reserved field.</dt>
|
|
</dl>
|
|
|
|
<p><strong>Size of fixed header for QRYG0100.</strong> Size of fixed header
|
|
information.</p>
|
|
|
|
<p><strong>Specified temporary storage limit in megabytes.</strong> The user specified
|
|
query temporary storage usage limit in number of megabytes.</p>
|
|
|
|
<p><strong>Specified time limit in seconds.</strong> The user specified query
|
|
time limit in number of seconds.</p>
|
|
|
|
<p><strong>User Name.</strong> The user name under which the job that is issuing the
|
|
query request is started.</p>
|
|
|
|
<br>
|
|
<h3><a name="Usage_Notes">Usage Notes</a></h3>
|
|
|
|
<ul>
|
|
<li>Exit program(s) will be called for all query requests where the estimated
|
|
runtime and/or temporary storage usage exceed user specified limits.</li>
|
|
|
|
<li>If an exit program fails for any reason (not found, not authorized,
|
|
function check in the program) the messages will be left in the job log and
|
|
processing of the query will be determined by the current default action.
|
|
The current default action is determined by the return code of the previously
|
|
called exit program. For the initial exit program, the default is 0.</li>
|
|
|
|
<li>Exit program(s) registered for this exit point must be thread safe and
|
|
compiled with ACTGRP(*CALLER) because the exit program may be called as the
|
|
result of a query in an SQL external function. SQL external functions do not
|
|
allow ACTGRP(*NEW).</li>
|
|
|
|
<li>Exit program(s) will run in the job that issues the query request.</li>
|
|
|
|
<li>Exit program(s) registered after a job has started might not be called for
|
|
that existing job.</li>
|
|
|
|
<li>Exit program(s) removed after a job has started may continue to be called for
|
|
that existing job.</li>
|
|
|
|
<li>Exit program(s) must be defined in the system ASP.</li>
|
|
|
|
<li>When an exit program executes a query or an SQL function, the exit
|
|
program could be called recursively. The exit program doing these operations
|
|
must be coded to avoid recursion loops.</li>
|
|
|
|
<li>Many applications and tools set the query time limit to 0 for gathering
|
|
performance information. It is recommended that exit program(s) return a 0
|
|
for a query time limit of 0.</li>
|
|
|
|
<li>For a return code of 2 or 3, the database monitor will gather information
|
|
about the query that exceeded the user specified limit if FTRQRYGOVR(*YES) is
|
|
specified on the COMMENT parameter of the STRDBMON command. If FTRQRYGOVR(*ALWAYS)
|
|
is specified, the database monitor will gather information regardless of the
|
|
return code.</li>
|
|
|
|
<li>The query governor will be ignored and exit program(s) will not be called
|
|
for queries run in system jobs such as initial program load (IPL) and the install
|
|
path.</li>
|
|
|
|
</ul>
|
|
|
|
<img src="v5r4deltaend.gif" alt="End of change">
|
|
<hr>
|
|
Exit program introduced: V5R4
|
|
|
|
<hr>
|
|
<center>
|
|
<table cellpadding="2" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
|
"file1.htm">Database and File APIs</a> | <a href="aplist.htm">APIs by
|
|
category</a></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
</body>
|
|
</html>
|
|
|