ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/xqrygovr.htm

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>
&nbsp;&nbsp;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>
&nbsp;&nbsp;Exit Point Name: QIBM_QQQ_QUERY_GOVR<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Exit Point Format Name: QRYG0100<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;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>