1177 lines
35 KiB
HTML
1177 lines
35 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>Request Statistics Collections (QDBSTRS, QdbstRequestStatistics)
|
|
API</title>
|
|
<!-- Begin Header Records -->
|
|
<!-- 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. -->
|
|
<!-- Change History: -->
|
|
<!-- YYMMDD USERID Change description -->
|
|
<!-- Created by Ulrich Thiemann on 07-May-2001 -->
|
|
<!-- Updated by Ulrich Thiemann on 01-Aug-2002 -->
|
|
<!-- 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>Request Statistics Collections (QDBSTRS, QdbstRequestStatistics) API</h2>
|
|
|
|
<div class="box" style="width: 80%;">
|
|
<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="45%">Input data</td>
|
|
<td align="left" valign="top" width="15%">Input</td>
|
|
<td align="left" valign="top" width="30%">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">2</td>
|
|
<td align="left" valign="top">Length of input data</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Binary(4)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">3</td>
|
|
<td align="left" valign="top">Format of input data</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(8)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">Feedback area</td>
|
|
<td align="left" valign="top">Output</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">5</td>
|
|
<td align="left" valign="top">Length of feedback area</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Binary(4)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">6</td>
|
|
<td align="left" valign="top">Feedback keys</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Array(*) of Binary(4)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">7</td>
|
|
<td align="left" valign="top">Number of feedback keys</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Binary(4)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="left" valign="top">Error code</td>
|
|
<td align="left" valign="top">I/O</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
Service Program Name: QDBSTMGR<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: Yes<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The Request Statistics Collections (QDBSTRS, QdbstRequestStatistics) API
|
|
allows the user to request one or more statistics collections for a given set
|
|
of columns of a database file member to be created.</p>
|
|
|
|
<p>The created statistics collections are stored as part of the database file
|
|
member.</p>
|
|
|
|
<p>Options are provided to control whether the statistics are generated in the
|
|
background or to be processed immediately, and whether the status of the
|
|
resulting statistics collections is to be maintained automatically by the
|
|
system or manually by the user.</p>
|
|
|
|
<br>
|
|
|
|
<h3>Section overview</h3>
|
|
<ul>
|
|
<li><a href="#AuthAndLocks">Authorities and Locks</a></li>
|
|
<li><a href="#ReqParmGroup">Required Parameter Group</a></li>
|
|
|
|
<li><a href="#STIR0100Format">STIR0100 Input Format</a></li>
|
|
<li><a href="#VALIDKEYS">Valid Keys - Feedback</a></li>
|
|
<li><a href="#FeedbackFormat">Feedback Area Format</a></li>
|
|
<li><a href="#FieldDescriptions">Field Descriptions</a></li>
|
|
|
|
<li><a href="#ErrorMsgs">Error Messages</a></li>
|
|
<li><a href="#RelInfo">Related Information</a></li>
|
|
</ul>
|
|
|
|
<br>
|
|
|
|
<h3><a name="AuthAndLocks">Authorities and Locks</a></h3>
|
|
|
|
<dl>
|
|
<dt><em>ASP Device Authority</em></dt>
|
|
|
|
<dd>*EXECUTE</dd>
|
|
|
|
<dt><em>File Authority</em></dt>
|
|
|
|
<dd>*OBJALTER, *OBJOPR</dd>
|
|
|
|
<dt><em>File Library Authority</em></dt>
|
|
|
|
<dd>*EXECUTE</dd>
|
|
|
|
<dt><em>File Lock</em></dt>
|
|
|
|
<dd>*SHRRD</dd>
|
|
|
|
<dt><em>Translation Table Authority</em></dt>
|
|
|
|
<dd>*USE</dd>
|
|
|
|
<dt><em>Translation Table Library Authority</em></dt>
|
|
|
|
<dd>*EXECUTE</dd>
|
|
|
|
<dt><em>Translation Table Lock</em></dt>
|
|
|
|
<dd>*SHRRD</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="ReqParmGroup">Required Parameter Group</a></h3>
|
|
|
|
<dl>
|
|
<dt><strong>Input data</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(*)
|
|
|
|
<p>The buffer containing the input parameters according to the
|
|
<em>Format of input data</em> parameter.
|
|
The buffer content has to start at a four-byte boundary.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Length of input data</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4)
|
|
|
|
<p>The length of the input data buffer provided.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Format of input data</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(8)
|
|
|
|
<p>The format of the input data. Possible values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>STIR0100</em></td>
|
|
<td align="left" valign="top">Basic request statistics collections input
|
|
parameters.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>Refer to <a href="#STIR0100Format">STIR0100 Input Format</a> for more
|
|
information.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Feedback area</strong></dt>
|
|
|
|
<dd>OUTPUT; CHAR(*)
|
|
|
|
<p>The buffer to receive feedback data. See <a href="#FeedbackFormat">Feedback
|
|
Area Format</a> for more information. The buffer content has to start at a
|
|
four-byte boundary.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Length of feedback area</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4)
|
|
|
|
<p>The length of the feedback area buffer provided. The required minimum length
|
|
is 16, to fit the feedback area header (see <a href="#FeedbackFormat">
|
|
Feedback Area Format</a>).</p>
|
|
</dd>
|
|
|
|
<dt><strong>Feedback keys</strong></dt>
|
|
|
|
<dd>INPUT; ARRAY(*) OF BINARY(4)
|
|
|
|
<p>The list of fields to return in the feedback area. For a list of valid keys
|
|
see <a href="#VALIDKEYS">Valid Keys - Feedback</a>.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Number of feedback keys</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4)
|
|
|
|
<p>The number of fields to return in the feedback area. If zero is specified,
|
|
all other feedback area parameters (<em>Feedback area</em>, <em>Length of
|
|
feedback area</em>, and <em>Feedback keys</em>) are ignored.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Error code</strong></dt>
|
|
|
|
<dd>I/O; CHAR(*)
|
|
|
|
<p>The structure in which to return error information. For the format of the
|
|
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h4><a name="STIR0100Format">STIR0100 Input Format</a></h4>
|
|
|
|
<p>The basic request statistics collections input parameters. See <a href=
|
|
"#FieldDescriptions">Field Descriptions</a> for details of the fields
|
|
listed.</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%">CHAR(10)</td>
|
|
<td align="left" valign="top" width="60%">ASP device name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">10</td>
|
|
<td align="center" valign="top">A</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">File name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">20</td>
|
|
<td align="center" valign="top">14</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">File library name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">30</td>
|
|
<td align="center" valign="top">1E</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">File member name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">40</td>
|
|
<td align="center" valign="top">28</td>
|
|
<td align="left" valign="top">CHAR(12)</td>
|
|
<td align="left" valign="top">Collection mode</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">Offset to statistics collections</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">Number of statistics collections</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">60</td>
|
|
<td align="center" valign="top">3C</td>
|
|
<td align="left" valign="top">CHAR(*)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The fields below follow the fields above and repeat, in the order listed,
|
|
for each statistics collection, where the first statistics collection starts at
|
|
the given <em>Offset to statistics collections</em>.</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%">Length of statistics collection</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">+4</td>
|
|
<td align="center" valign="top">+4</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of statistics collection name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">+8</td>
|
|
<td align="center" valign="top">+8</td>
|
|
<td align="left" valign="top">CHAR(128)</td>
|
|
<td align="left" valign="top">Statistics collection name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">+136</td>
|
|
<td align="center" valign="top">+88</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Aging mode</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">+146</td>
|
|
<td align="center" valign="top">+92</td>
|
|
<td align="left" valign="top">CHAR(2)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">+148</td>
|
|
<td align="center" valign="top">+94</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Displacement to columns</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">+152</td>
|
|
<td align="center" valign="top">+98</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Number of columns</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">+156</td>
|
|
<td align="center" valign="top">+9C</td>
|
|
<td align="left" valign="top">CHAR(*)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The fields below follow for each statistics collection definition header
|
|
structure as described above and repeat, in the order listed, for each column in
|
|
the current statistics collection, where the data for the first column starts
|
|
at the given offset <em>Offset to columns</em>.</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%">Length of column definition</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">+4</td>
|
|
<td align="center" valign="top">+4</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Column name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">+14</td>
|
|
<td align="center" valign="top">+E</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Translation table name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">+24</td>
|
|
<td align="center" valign="top">+18</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Translation table library name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">+34</td>
|
|
<td align="center" valign="top">+22</td>
|
|
<td align="left" valign="top">CHAR(2)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">+36</td>
|
|
<td align="center" valign="top">+24</td>
|
|
<td align="left" valign="top"> </td>
|
|
<td align="left" valign="top"> </td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h4><a name="VALIDKEYS">Valid Keys - Feedback</a></h4>
|
|
|
|
<p>Use the following keys to specify the fields to be returned in the feedback
|
|
area. Each key can only be specified once. See
|
|
<a href="#FieldDescriptions">Field Descriptions</a> for details of the fields listed.</p>
|
|
|
|
<table border>
|
|
<tr>
|
|
<th align="center" valign="top">Key</th>
|
|
<th align="left" valign="top">Type</th>
|
|
<th align="left" valign="top">Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">1</td>
|
|
<td align="left" valign="top" width="20%">CHAR(10)</td>
|
|
<td align="left" valign="top" width="70%">ASP device name used</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">3</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">File library name used</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">File member name used</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Elapsed time</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">6</td>
|
|
<td align="left" valign="top">CHAR(16)</td>
|
|
<td align="left" valign="top">Internal request ID</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">43</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Total number of statistics collections for
|
|
internal request ID</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">46</td>
|
|
<td align="left" valign="top">Array of CHAR(*)</td>
|
|
<td align="left" valign="top">Statistics collection names used</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">7</td>
|
|
<td align="left" valign="top">Array of CHAR(*)</td>
|
|
<td align="left" valign="top">Internal statistics IDs created</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h4><a name="FeedbackFormat">Feedback Area Format</a></h4>
|
|
|
|
<p>The fields returned in the feedback area will be returned in the order
|
|
requested. See <a href="#FieldDescriptions">Field Descriptions</a> for details
|
|
of the fields listed.</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%">Number of bytes returned</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Number of bytes available</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Number of key fields returned</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">12</td>
|
|
<td align="center" valign="top">C</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Number of key fields available</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" rowspan="5" colspan="2">These fields repeat, in
|
|
the order listed, for each key selected.</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of field information returned</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Key identifier</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of data</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CHAR(*)</td>
|
|
<td align="left" valign="top">Data</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CHAR(*)</td>
|
|
<td align="left" valign="top">Reserved (padding to the next 4 bytes
|
|
boundary)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h4><a name="FieldDescriptions">Field Descriptions</a></h4>
|
|
|
|
<p><strong>Aging mode.</strong> Whether the system is allowed to
|
|
age or remove the resulting collected statistics collection. The possible
|
|
values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*SYS</em></td>
|
|
<td align="left" valign="top">Refresh or removal of the resulting statistics
|
|
collections will be performed automatically by the system.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*USER</em></td>
|
|
<td align="left" valign="top">Refresh or removal will only occur when a user
|
|
requests it.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>ASP device name.</strong> The name of one auxiliary storage pool
|
|
(ASP) device in the ASP group in which the library and file are located.
|
|
The ASP device must have a status of 'Available'. The documented authority
|
|
is required for the given ASP and the primary of the corresponding ASP group.
|
|
The name can be a specific ASP device name
|
|
(for an ASP with a number greater than 32), or one of the
|
|
following special values:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*</em></td>
|
|
<td align="left" valign="top">Locate the library and file in the name space
|
|
for the current thread.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*SYSBAS</em></td>
|
|
<td align="left" valign="top">Locate the library and file in the system ASP
|
|
(ASP number 1) and all basic ASPs (ASP numbers 2 through 32).</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>ASP device name used.</strong> The actual auxiliary storage pool
|
|
device name used, after possible resolution of special values.</p>
|
|
|
|
<p><strong>Collection mode.</strong> Where the processing for the statistics
|
|
collection will be performed, or if merely an estimate is requested. The
|
|
possible values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*IMMEDIATE</em></td>
|
|
<td align="left" valign="top">Execute the request immediately. The statistics
|
|
collection will run in the user's process. Control will not return to the API
|
|
invoker until the collection is complete.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*BACKGROUND</em></td>
|
|
<td align="left" valign="top">The statistics collection will be scheduled for
|
|
execution in system job QDBFSTCCOL. Control will return to the API invoker
|
|
immediately.
|
|
|
|
<p><strong>Note:</strong> If the current setting of the system value QDBFSTCCOL
|
|
does not allow user requested background collections, then the request will be
|
|
queued until the system value is changed to a level allowing the execution of
|
|
the request. </p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*ESTIMATE</em></td>
|
|
<td align="left" valign="top">An estimate is returned immediately for the time,
|
|
that would be required to run the statistics collection. No statistics
|
|
collection will actually be created.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Column name.</strong> The name of a single column within
|
|
a single statistics collection definition.</p>
|
|
|
|
<p><strong>Data.</strong> The data returned for the key
|
|
identifier.</p>
|
|
|
|
<p><strong>Displacement to columns.</strong> Displacement to the
|
|
start of the list of column definitions for the current statistics collection
|
|
definition.</p>
|
|
|
|
<p><strong>Elapsed time.</strong> When the collection mode
|
|
specified is <em>*IMMEDIATE</em>, the value represents the number of seconds
|
|
actually spent processing the requested statistics collection.</p>
|
|
|
|
<p>For any other collection mode, this value represents the estimated time in
|
|
seconds, that the statistics collection should take.</p>
|
|
|
|
<p><strong>File library name.</strong> Where the file for which
|
|
statistics collections are being requested is located.
|
|
You can use these special values for the library name,
|
|
if the <em>ASP Device Name</em> is <em>*</em>:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*CURLIB</em></td>
|
|
<td align="left" valign="top">The job's current library or QGPL if the current
|
|
library is not set.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*LIBL</em></td>
|
|
<td align="left" valign="top">The library list.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*USRLIBL</em></td>
|
|
<td align="left" valign="top">Libraries listed in the user portion of the
|
|
library list.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>File library name used.</strong> The actual file library
|
|
name used, after possible resolution of special values.</p>
|
|
|
|
<p><strong>File member name.</strong> The name of the file member
|
|
to be used for the statistics collections request.</p>
|
|
|
|
<p>This value can be a specific file member name or one of the following
|
|
special values:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*FIRST</em></td>
|
|
<td align="left" valign="top">The first member (in the order created) in the
|
|
specified file.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*LAST</em></td>
|
|
<td align="left" valign="top">The last member (in the order created) in the
|
|
specified file.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>File member name used.</strong> The actual file member
|
|
name used, after possible resolution of special values.</p>
|
|
|
|
<p><strong>File name.</strong> The name of the file for which
|
|
statistics collections are being requested. The file has to be an existing
|
|
local, single format, physical file.</p>
|
|
|
|
<p><strong>Internal request ID.</strong> For a <em>Collection
|
|
mode</em> of <em>*BACKGROUND</em> only, this field is an unique ID for the
|
|
complete list of statistics collections requested here. The request ID stays
|
|
valid until the request is completed and the ID can be used on the <a href=
|
|
"qdbstcancelrequestedstatistics.htm">Cancel Requested Statistics
|
|
Collections</a> (QDBSTCRS, QdbstCancelRequestedStatistics) API.</p>
|
|
|
|
<p><strong>Note:</strong> The ID is stored in binary, non printable form in the
|
|
character array.</p>
|
|
|
|
<p><strong>Internal statistics IDs created.</strong> For a <em>
|
|
Collection mode</em> of <em>*IMMEDIATE</em> only, this will return an array of
|
|
the internal statistics ID created for each of the requested and successfully
|
|
created statistics collections. This statistics ID together with the qualified
|
|
member name can serve as a unique identifier for the created statistics
|
|
collection on the input to the <a href="qdbstdeletestatistics.htm">
|
|
QdbstDeleteStatistics</a>, <a href="qdbstupdatestatistics.htm">
|
|
QdbstUpdateStatistics</a>, and <a href="qdbstlistdetailstatistics.htm">
|
|
QdbstListDetailStatistics</a> APIs. Each ID is returned as a single key value.
|
|
The single key values will be returned in sequence and in the order the
|
|
statistics collections were requested in the input format. The array dimension
|
|
can be determined either by the input format field <em>Number of statistics
|
|
collections</em> or by requesting this number again as <em>Total number of
|
|
statistics collections for internal request ID</em> in the feedback.</p>
|
|
|
|
<p><strong>Note:</strong> The internal statistics ID for a statistics
|
|
collection is also returned on the <a href="qdbstliststatistics.htm">
|
|
QdbstListStatistics</a> API.</p>
|
|
|
|
<p><strong>Note:</strong> The ID is stored in binary, non printable form in the
|
|
character array.</p>
|
|
|
|
<p><strong>Key identifier.</strong> The field returned. For a list
|
|
of valid keys see <a href="#VALIDKEYS">Valid Keys - Feedback</a>.</p>
|
|
|
|
<p><strong>Length of column definition.</strong> Length of this
|
|
column definition.</p>
|
|
|
|
<p><strong>Length of data.</strong> The length of the data returned
|
|
for the field.</p>
|
|
|
|
<p><strong>Length of field information returned.</strong> Total
|
|
number of bytes returned for this field in the feedback area.</p>
|
|
|
|
<p><strong>Length of statistics collection.</strong> Length of this
|
|
statistics collection definition, which can be used to get to the next
|
|
definition.</p>
|
|
|
|
<p><strong>Note:</strong> The length includes all the column definitions for
|
|
this statistics collections.</p>
|
|
|
|
<p><strong>Length of statistics collection name.</strong> Actual
|
|
length of the statistics collection name, up to the maximum length of 128
|
|
characters.</p>
|
|
|
|
<p><strong>Number of bytes available.</strong> Number of bytes that
|
|
could be returned in the feedback area.</p>
|
|
|
|
<p><strong>Number of bytes returned.</strong> Number of bytes
|
|
returned in the feedback area.</p>
|
|
|
|
<p><strong>Number of columns.</strong> Number of columns in a
|
|
single statistics collection definition.</p>
|
|
|
|
<p><strong>Note:</strong> This number must be 1.</p>
|
|
|
|
<p><strong>Number of key fields available.</strong> Number of
|
|
fields that could be returned in the feedback area.</p>
|
|
|
|
<p><strong>Number of key fields returned.</strong> Number of fields
|
|
returned in the feedback area.</p>
|
|
|
|
<p><strong>Number of statistics collections.</strong> Number of
|
|
statistics collection definitions for this request.</p>
|
|
|
|
<p><strong>Offset to statistics collections.</strong> Offset to the
|
|
start of the list of statistics collection definitions for this request.</p>
|
|
|
|
<p><strong>Reserved.</strong> Reserved for future use. If this field is input,
|
|
the field must be set to hexadecimal zeros.</p>
|
|
|
|
<p><strong>Reserved (in feedback area format).</strong> Structure
|
|
padding to guarantee alignment to the next four bytes boundary.</p>
|
|
|
|
<p><strong>Statistics collection names used.</strong> An array of
|
|
the statistics collection names used. Each name is returned as a single key
|
|
value and is either the name specified on input, or the system generated name,
|
|
if the special value <em>*GEN</em> was used on input and if the <em>Collection
|
|
mode</em> specified is <em>*IMMEDIATE</em>. The single key values will be
|
|
returned in sequence and in the order the statistics collections were requested
|
|
in the input format. The array dimension can be determined either by the input
|
|
format field <em>Number of statistics collections</em> or by requesting this
|
|
number again as <em>Total number of statistics collections for internal request
|
|
ID</em> in the feedback.</p>
|
|
|
|
<p><strong>Statistics collection name.</strong> A name unique
|
|
amongst all statistics collections for the file member. The following special
|
|
value can be used:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*GEN</em></td>
|
|
<td align="left" valign="top">The system will generate a unique name for the
|
|
statistics collection.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Note:</strong> The name is given in varying length form, where the
|
|
actual length is passed in the <em>Length of statistics collection name</em>
|
|
field, to indicate how many of the 128 characters are actually part of the name
|
|
text.</p>
|
|
|
|
<p><strong>Total number of statistics collections for internal request
|
|
ID.</strong> Number of statistics collection definitions for this
|
|
request. Gives the array dimension of <em>Statistics collection names used</em>
|
|
and <em>Internal statistics IDs created</em> and is a copy of <em>Number of
|
|
statistics collections</em> in the input format.</p>
|
|
|
|
<p><strong>Translation table name.</strong> This field is relevant
|
|
just for character columns and must be all blanks otherwise. For character
|
|
columns, this is the name of a translation table to be applied to the data in
|
|
this column. The name must be for an existing translation table, or all blanks,
|
|
if no translation table is to be applied.</p>
|
|
|
|
<p><strong>Translation table library name.</strong> Where the
|
|
translation table is located. The name must be for an existing library or all
|
|
blanks, if no translation table is to be applied.</p>
|
|
|
|
<p>You can use these special values for the library name:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*CURLIB</em></td>
|
|
<td align="left" valign="top">The job's current library or QGPL if the current
|
|
library is not set.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*LIBL</em></td>
|
|
<td align="left" valign="top">The library list.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*USRLIBL</em></td>
|
|
<td align="left" valign="top">Libraries listed in the user portion of the
|
|
library list.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3><a name="ErrorMsgs">Error Messages</a></h3>
|
|
|
|
<table width="100%" cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<th align="left" valign="top" nowrap>Message ID</th>
|
|
<th align="left" valign="top">Error Message Text</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF0623 E</td>
|
|
<td align="left" valign="top">Field &1 not found in record format &2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF1866 E</td>
|
|
<td align="left" valign="top">Value &1 for number of fields to return not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF2105 E</td>
|
|
<td align="left" valign="top">Object &1 in &2 type *&3 not found.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF2113 E</td>
|
|
<td align="left" valign="top">Cannot allocate library &1.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF2173 E</td>
|
|
<td align="left" valign="top">Value for ASPDEV not valid with special value for library.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF218C E</td>
|
|
<td align="left" valign="top">&1 not a primary or secondary ASP.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3141 E</td>
|
|
<td align="left" valign="top">Member &2 not found.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF34C0 E</td>
|
|
<td align="left" valign="top">Value &1 for number of fields to return parameter not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C07 E</td>
|
|
<td align="left" valign="top">Error occurred while retrieving information from object &1.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C1D E</td>
|
|
<td align="left" valign="top">Length specified in parameter &1 not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C21 E</td>
|
|
<td align="left" valign="top">Format name &1 is not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C29 E</td>
|
|
<td align="left" valign="top">Object name &1 is not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C36 E</td>
|
|
<td align="left" valign="top">Number of parameters, &1, entered for this API was not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C39 E</td>
|
|
<td align="left" valign="top">Value for reserved field not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C3B E</td>
|
|
<td align="left" valign="top">Value for parameter &2 for API &1 not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C82 E</td>
|
|
<td align="left" valign="top">Key &1 not valid for API &2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C89 E</td>
|
|
<td align="left" valign="top">Key &1 specified more than once.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3CF1 E</td>
|
|
<td align="left" valign="top">Error code parameter not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3CF2 E</td>
|
|
<td align="left" valign="top">Error(s) occurred during running of &1 API.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF4268 E</td>
|
|
<td align="left" valign="top">Object &1 in &2 type *&3 not found.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF9802 E</td>
|
|
<td align="left" valign="top">Not authorized to object &2 in &3.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF9803 E</td>
|
|
<td align="left" valign="top">Cannot allocate object &2 in library &3.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF9804 E</td>
|
|
<td align="left" valign="top">Object &2 in library &3 damaged.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF980B E</td>
|
|
<td align="left" valign="top">Object &1 in library &2 not available.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF9810 E</td>
|
|
<td align="left" valign="top">Library &1 not found.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF9812 E</td>
|
|
<td align="left" valign="top">File &1 in library &2 not found.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF9814 E</td>
|
|
<td align="left" valign="top">Device &1 not found.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF9820 E</td>
|
|
<td align="left" valign="top">Not authorized to use library &1.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF9822 E</td>
|
|
<td align="left" valign="top">Not authorized to file &1 in library &2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF9825 E</td>
|
|
<td align="left" valign="top">Not authorized to device &1.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF9826 E</td>
|
|
<td align="left" valign="top">Cannot allocate file &2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF9830 E</td>
|
|
<td align="left" valign="top">Cannot assign library &1</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF9872 E</td>
|
|
<td align="left" valign="top">Program or service program &1 in library &2 ended. Reason code &3.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFB401 E</td>
|
|
<td align="left" valign="top">API &3 failed with reason code &1.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFB8ED E</td>
|
|
<td align="left" valign="top">Device description &1 not correct for operation.</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
<h3><a name="RelInfo">Related Information</a></h3>
|
|
|
|
<ul>
|
|
<li>the <<strong>qdbst.h</strong>> include file in library QSYSINC, for
|
|
API-related structure declarations and special value declarations.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>the <<strong>qdbstmgr.h</strong>> include file in library QSYSINC,
|
|
for the QdbstRequestStatistics API prototype.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>the <<strong>qdbstrs.h</strong>> include file in library QSYSINC,
|
|
for the QDBSTRS API prototype.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>the system value QDBFSTCCOL.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="qdbstcancelrequestedstatistics.htm">Cancel Requested Statistics
|
|
Collections</a> (QDBSTCRS, QdbstCancelRequestedStatistics) API<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="qdbstdeletestatistics.htm">Delete Statistics Collections</a>
|
|
(QDBSTDS, QdbstDeleteStatistics) API<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="qdbstlistrequestedstatistics.htm">List Requested Statistics
|
|
Collections</a> (QDBSTLRS, QdbstListRequestedStatistics) API<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="qdbstlistdetailstatistics.htm">List Statistics Collection
|
|
Details</a> (QDBSTLDS, QdbstListDetailStatistics) API<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="qdbstliststatistics.htm">List Statistics Collections</a> (QDBSTLS,
|
|
QdbstListStatistics) API<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="qdbstupdatestatistics.htm">Update Statistics Collections</a>
|
|
(QDBSTUS, QdbstUpdateStatistics) API</li>
|
|
</ul>
|
|
|
|
<br>
|
|
|
|
|
|
<hr>
|
|
API introduced: V5R2
|
|
|
|
<hr>
|
|
<table align="center" 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>
|
|
</body>
|
|
</html>
|
|
|