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

1545 lines
46 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!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>List Statistics Collection Details (QDBSTLDS, QdbstListDetailStatistics)
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 03-May-2001 -->
<!-- Updated by Ulrich Thiemann on 01-Aug-2002 -->
<!-- File cleanup completed Feb 2002 by v2cdijab -->
<!-- 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>List Statistics Collection Details (QDBSTLDS, QdbstListDetailStatistics) API</h2>
<div class="box" style="width: 80%;">
<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%">Qualified user space name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Format of output</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Input data</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">4</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">5</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">6</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>
&nbsp;&nbsp;Service Program Name: QDBSTMGR<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The List Statistics Collection Details (QDBSTLDS, QdbstListDetailStatistics) API
lists additional statistics data
for a single statistics collection, not returned by the <a href=
"qdbstliststatistics.htm">List Statistics Collections (QDBSTLS,
QdbstListStatistics) API</a>. Available additional data is the list of most
frequent values and the list of histogram ranges values.</p>
The generated list output replaces any existing list in the user space.
<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="#STIV0100Format">STIV0100 Input Format</a></li>
<li><a href="#VALIDKEYS">Valid Keys - Request output</a></li>
<li><a href="#GeneratedListFormat">Format of the Generated List</a></li>
<li><a href="#InputParmSection">Input parameter section</a></li>
<li><a href="#HeaderSection">Header section</a></li>
<li><a href="#DetailValuesHeader">Detail Values Header</a></li>
<li><a href="#ValueDesc">Detail Value Format Description</a></li>
<li><a href="#ListDataSection">List data section</a></li>
<li><a href="#MFVFormat">Most frequent values list entry format</a></li>
<li><a href="#HistogramFormat">Histogram range values list entry 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>
<h3><a name="AuthAndLocks">Authorities and Locks</a></h3>
<dl>
<dt><em>User Space Authority</em></dt>
<dd>*CHANGE</dd>
<dt><em>User Space Library Authority</em></dt>
<dd>*EXECUTE</dd>
<dt><em>User Space Lock</em></dt>
<dd>*EXCLRD</dd>
<dt><em>ASP Device Authority</em></dt>
<dd>*EXECUTE</dd>
<dt><em>File Authority</em></dt>
<dd>*OBJOPR, *READ</dd>
<dt><em>File Library Authority</em></dt>
<dd>*EXECUTE</dd>
<dt><em>File Lock</em></dt>
<dd>*SHRRD</dd>
</dl>
<br>
<h3><a name="ReqParmGroup">Required Parameter Group</a></h3>
<dl>
<dt><strong>Qualified user space name</strong></dt>
<dd>INPUT; CHAR(20)
<p>The user space that is to receive the generated list, and the library in
which it is located. The first 10 characters contain the user space name, and
the second 10 characters contain the library name. 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>
</dd>
<dt><strong>Format of output</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the statistics collection details list to be returned.
Possible format names are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>STOV0100</em></td>
<td align="left" valign="top">Statistics collection details list with list
entries for the requested keys.</td>
</tr>
</table>
<p>Refer to <a href="#GeneratedListFormat">Format of generated list</a> and <a
href="#STOV0100Format">STOV0100 Output Format</a> for more
information.</p>
</dd>
<dt><strong>Input data</strong></dt>
<dd>INPUT; CHAR(*)
<p>The buffer containing the input parameters according to the format of input
data parameter. The buffer content has to start at a 4-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>STIV0100</em></td>
<td align="left" valign="top">List statistics collection details input
parameters.</td>
</tr>
</table>
<p>Refer to <a href="#STIV0100Format">STIV0100 Input Format</a> for more
information.</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="STIV0100Format">STIV0100 Input Format</a></h4>
<p>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">0A</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(16)</td>
<td align="left" valign="top">Internal statistics ID</td>
</tr>
<tr>
<td align="center" valign="top">56</td>
<td align="center" valign="top">38</td>
<td align="left" valign="top">CHAR(48)</td>
<td align="left" valign="top">Continuation handle</td>
</tr>
<tr>
<td align="center" valign="top">104</td>
<td align="center" valign="top">68</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to fields to return</td>
</tr>
<tr>
<td align="center" valign="top">108</td>
<td align="center" valign="top">6C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of fields to return</td>
</tr>
<tr>
<td align="center" valign="top">112</td>
<td align="center" valign="top">70</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">Array(*) of BINARY(4)</td>
<td align="left" valign="top">Keys of fields to return</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Reserved</td>
</tr>
</table>
<br>
<br>
<h4><a name="VALIDKEYS">Valid Keys - Request output</a></h4>
<p>Each key can only be specified once.
See <a href="#FieldDescriptions">Field Descriptions</a> for details of the
fields listed.</p>
<table border width="80%">
<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="15%">32</td>
<td align="left" valign="top" width="20%">CHAR(*)</td>
<td align="left" valign="top" width="65%"><a href="#MFVFormat">Most frequent
values</a></td>
</tr>
<tr>
<td align="center" valign="top">33</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top"><a href="#HistogramFormat">Histogram range
values</a></td>
</tr>
</table>
<br>
<br>
<h3><a name="GeneratedListFormat">Format of the Generated List</a></h3>
<p>The statistics collection details list consists of:</p>
<ul>
<li>A user area</li>
<li>A generic header</li>
<li><a href="#InputParmSection">An input parameter section</a></li>
<li><a href="#HeaderSection">A header section</a></li>
<li><a href="#ListDataSection">A list data section</a></li>
</ul>
<p>The user area and generic header are described in <a href="../apiref/usf.htm">User
space format for list APIs</a>. The remaining items are described in the
following sections.</p>
<br>
<h4><a name="InputParmSection">Input Parameter Section</a></h4>
<p>The following information is returned in the input parameter section. For
detailed descriptions of the fields in this table, see <a href=
"#FieldDescriptions">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%">CHAR(10)</td>
<td align="left" valign="top" width="60%">User space name specified</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">User space library name specified</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Format of output specified</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of input data specified</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Format of input data specified</td>
</tr>
<tr>
<td align="center" valign="top">40</td>
<td align="center" valign="top">28</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">ASP device name specified</td>
</tr>
<tr>
<td align="center" valign="top">50</td>
<td align="center" valign="top">32</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">File name specified</td>
</tr>
<tr>
<td align="center" valign="top">60</td>
<td align="center" valign="top">3C</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">File library name specified</td>
</tr>
<tr>
<td align="center" valign="top">70</td>
<td align="center" valign="top">46</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">File member name specified</td>
</tr>
<tr>
<td align="center" valign="top">80</td>
<td align="center" valign="top">50</td>
<td align="left" valign="top">CHAR(48)</td>
<td align="left" valign="top">Continuation handle specified</td>
</tr>
<tr>
<td align="center" valign="top">128</td>
<td align="center" valign="top">80</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to fields to return specified</td>
</tr>
<tr>
<td align="center" valign="top">132</td>
<td align="center" valign="top">84</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of fields to return specified</td>
</tr>
<tr>
<td align="center" valign="top">136</td>
<td align="center" valign="top">88</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Displacement to specified fields to return</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">Array(*) of BINARY(4)</td>
<td align="left" valign="top">Keys of fields to return specified</td>
</tr>
</table>
<br>
<br>
<h4><a name="#HeaderSection">Header Section</a></h4>
<p>For detailed descriptions of the fields in this table, see <a href=
"#FieldDescriptions">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%">CHAR(10)</td>
<td align="left" valign="top" width="60%">ASP device name used</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 library name used</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 member name used</td>
</tr>
<tr>
<td align="center" valign="top">30</td>
<td align="center" valign="top">1E</td>
<td align="left" valign="top">CHAR(2)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">CHAR(48)</td>
<td align="left" valign="top">Continuation handle</td>
</tr>
<tr>
<td align="center" valign="top">80</td>
<td align="center" valign="top">50</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Displacement to <a href="#DetailValuesHeader">
detail values header</a> of most frequent values</td>
</tr>
<tr>
<td align="center" valign="top">84</td>
<td align="center" valign="top">54</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Displacement to <a href="#DetailValuesHeader">
detail values header</a> of histogram range values</td>
</tr>
<tr>
<td align="center" valign="top">88</td>
<td align="center" valign="top">58</td>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">&nbsp;</td>
</tr>
</table>
<br>
<br>
<h4><a name="#DetailValuesHeader">Detail Values Header</a></h4>
<p>This structure contains fields describing general information for list
entries of a certain kind (most frequent values or histogram range values)
returned in the list data section.</p>
<p>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%">Offset to first detail value
entry</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 detail value entries</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">Length of detail value entry</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 detail value columns</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Displacement to <a href="#ValueDesc">format</a>
of first detail value column.</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of detail value column format</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">&nbsp;</td>
</tr>
</table>
<br>
<br>
<h4><a name="ValueDesc">Detail Value Format Description</a></h4>
<p>The description of a single detail value column value. 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%">SQL data type</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">Field length</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">Length in bytes</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">Scale</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Precision</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Radix</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">CCSID</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</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">38</td>
<td align="center" valign="top">26</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">48</td>
<td align="center" valign="top">30</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">DDS type</td>
</tr>
<tr>
<td align="center" valign="top">49</td>
<td align="center" valign="top">31</td>
<td align="left" valign="top">CHAR(3)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">52</td>
<td align="center" valign="top">34</td>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">&nbsp;</td>
</tr>
</table>
<br>
<br>
<h3><a name="ListDataSection"></a><a name="STOV0100Format">List Data Section - STOV0100 Format</a></h3>
<p> The list data section returned for output format STOV0100
contains list entries as specified in the <a href="#MFVFormat">Most frequent
values list entry format</a> and the <a href="#HistogramFormat">Histogram range
values list entry format</a>.</p>
<p>See the <a href="#HeaderSection">Header Section</a> for additional fields that
describe information common to all Most frequent value and Histogram range
value list entries.</p>
<br>
<h4><a name="MFVFormat">Most Frequent Values List Entry Format</a></h4>
<p>The format below describes the layout of a single most frequent value
returned as a list entry in the list data section. See <a href=
"#FieldDescriptions">Field Descriptions</a> and the <a href="#HeaderSection">
Header Section</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(8)</td>
<td align="left" valign="top" width="60%">Count for this most frequent
value</td>
</tr>
<tr>
<td align="center" valign="top">0</td>
<td align="center" valign="top">0</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Displacement to first most frequent value column
value</td>
</tr>
<tr>
<td align="center" valign="top">0</td>
<td align="center" valign="top">0</td>
<td align="left" valign="top">CHAR(4)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">Array of CHAR(*)</td>
<td align="left" valign="top">Most frequent value columns values</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Reserved</td>
</tr>
</table>
<br>
<br>
<h4><a name="HistogramFormat">Histogram Range Values List Entry Format</a></h4>
<p>This format describes the layout of a single histogram range value returned
as a list entry in the list data section. See <a href="#FieldDescriptions">
Field Descriptions</a> and the <a href="#HeaderSection">Header Section</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(8)</td>
<td align="left" valign="top" width="60%">Count for this histogram range
value</td>
</tr>
<tr>
<td align="center" valign="top">0</td>
<td align="center" valign="top">0</td>
<td align="left" valign="top">BINARY(8)</td>
<td align="left" valign="top">Count for this histogram range's high value</td>
</tr>
<tr>
<td align="center" valign="top">0</td>
<td align="center" valign="top">0</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Displacement to first histogram range value
column pair</td>
</tr>
<tr>
<td align="center" valign="top">0</td>
<td align="center" valign="top">0</td>
<td align="left" valign="top">CHAR(4)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">Array of CHAR(*)</td>
<td align="left" valign="top">Low/High value pairs of histogram range value
columns</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Reserved</td>
</tr>
</table>
<br>
<br>
<h3><a name="FieldDescriptions">Field Descriptions</a></h3>
<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>CCSID.</strong> The value's CCSID for character type values.</p>
<p><strong>Note:</strong> The CCSID here describes the CCSID of the original
value, before translation using the also given <a href=
"#TranslationTableNameField">translation table</a>.</p>
<p><strong>Continuation handle (input section).</strong> The handle used to
continue from a previous call to this API that resulted in partially complete
information. You can determine if a previous call resulted in partially
complete information by checking the Information Status variable in the generic
user space header following the API call.</p>
<p>If the API is not attempting to continue from a previous call, this
parameter must be set to blanks. Otherwise, a valid continuation value must be
supplied. The value may be obtained from the list header section of the user
space used in the previous call. When continuing, the first entry in the
returned list is the entry that immediately follows the last entry returned in
the previous call.</p>
<p><strong>Continuation handle (header section).</strong> A continuation point
for the API. This value is set based on the contents of the Information Status
variable in the generic header for the user space. The following situations can
occur:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top" nowrap><em>Information status-C</em></td>
<td align="left" valign="top">The information returned in the user space is
valid and complete. No continuation is necessary and the continuation handle is
set to blanks.</td>
</tr>
<tr>
<td align="left" valign="top"><em>Information status-P</em></td>
<td align="left" valign="top">The information returned in the user space is
valid but incomplete. The user may call the API again, starting where the last
call left off. The continuation handle contains a value which may be supplied
as an input parameter in later calls.</td>
</tr>
<tr>
<td align="left" valign="top"><em>Information status-I</em></td>
<td align="left" valign="top">The information returned in the user space is not
valid and incomplete. The content of the continuation handle is
unpredictable.</td>
</tr>
</table>
<p><strong>Count for this histogram range's high value.</strong> If the
statistics collection key chosen for the high value of this histogram range
value is estimated to occur very often, compared to the other values in this
histogram range, this count will be set to the estimated number of occurrences
of this key value in the file member.</p>
<p><strong>Note:</strong> A value of 0 indicates, that this additional
information about the high value is not available.</p>
<p><strong>Count for this histogram range value.</strong> How many statistics
collection key values are estimated to occur in this histogram range.</p>
<p><strong>Count for this most frequent value.</strong> How often the most
frequent statistics collection key value is estimated to occur in the file
member.</p>
<p><strong>DDS type.</strong> Data type code
(corresponding to the <em>SQL Data Type</em>) for the value.
See <a href="../rzakb/kickoff.htm">DDS Reference: Physical and Logical Files</a>.</p>
<p><strong>Displacement detail values header of histogram range
values.</strong> Displacement to the general information for the histogram
range values list entries.</p>
<p><strong>Note:</strong> The displacement will be zero if no histogram range
value information was returned.</p>
<p><strong>Displacement to detail values header of most frequent
values.</strong> Displacement to the general information for the most frequent
values list entries. The displacement will be zero if no most frequent value
information was returned.</p>
<p><strong>Displacement to first histogram range value column pair.</strong>
Displacement to the start of the array of <em>Low/High value pairs of histogram
range value columns</em>.</p>
<p><strong>Displacement to first most frequent value column value.</strong>
Displacement to the start of the array of <em>Most frequent value column
values</em>.</p>
<p><strong>Displacement to format of first detail value column.</strong>
Displacement to the array of format descriptions for the detail value column
values (compare <em>Number of detail value columns</em> and <em>Length of
detail value column format</em>).</p>
<p><strong>Note:</strong> Due to performance reasons, these formats might be
different from the formats of the original columns the detail value is based
on. For example, long character columns might be represented in a truncated
form, or varying character columns might have been converted to a fixed length
form.</p>
<p><strong>Note:</strong> For DATE, TIME, and TIMESTAMP columns, the detail
value column values will be returned as *ISO formatted text and the column
format will describe a character SQL data type of appropriate length.</p>
<p><strong>Displacement to specified fields to return.</strong>
Displacement to the start of the array of specified fields to return.</p>
<p><strong>Note:</strong> This is not the offset specified on input, but the
displacement within the input parameter section. See the <a href=
"#OffsetToFieldsSpecified">Offset to fields to return specified</a>
instead.</p>
<p><strong>Field length.</strong> Value field length.</p>
<p><strong>File library name.</strong> The location of the file for which
statistics collection details are to be listed. 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 list request. 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
collection details are to be listed. The file has to be an existing local,
single format, physical file.</p>
<p><strong>Histogram range values.</strong> The list of histogram range values.
See <a href="#HistogramFormat">Histogram range values list entry format</a> for
the layout of this list.</p>
<p><strong>Internal statistics ID.</strong> Together with the qualified file
name and member name, this represents a unique ID for the statistics collection
details to be listed.</p>
<p><strong>Key identifier.</strong> The field returned. For a list of valid
keys see <a href="#VALIDKEYS">Valid Keys - Request output</a>.</p>
<p><strong>Keys of fields to return.</strong> The list of fields in the list.
For a list of valid keys see <a href="#VALIDKEYS">Valid Keys - Request output</a>.</p>
<p><strong>Length in bytes.</strong> Length of returned column value in list
entry, in bytes. This also gives the displacement to the next column value,
where appropriate.</p>
<p><strong>Length of detail value column format.</strong> The number of bytes
for a single detail value column format. This is also the offset to the next
detail value column format, for any but the last detail value column format of
this kind of detail values. (See <em>Number of detail value columns</em>).</p>
<p><strong>Length of detail value entry.</strong> The number of bytes for a
single detail value list entry. This is also the offset to the next detail
value list entry for any but the last detail value list entry of this kind of
detail values in the list data section (See <em>Number of detail value
entries</em>).</p>
<p><strong>Low/High value pairs of histogram range value columns.</strong> The
array of lower, exclusive, and upper, inclusive, histogram range column values
for each column in the statistics collection key. The values are returned in
the following order: Low value of first range value column, high value of first
range value column, ... , low value of last range value column, high value of
last range value column. The array dimension is given by the <em>Number of
detail value columns</em> and the formats of the column values are referenced
by the <em>Displacement to format of first detail value column</em>. Lower and
upper value column always have the same format for a single column in the
statistics collection key. The size of a single value column is given by the
<em>Length in bytes</em> in the format.</p>
<p><strong>Note:</strong> The column values for the low value of the first
histogram range will be set to all X'00' and should be treated as undefined,
representing 'negative infinity'.</p>
<p><strong>Most frequent value columns values.</strong> The array of this most
frequent value's column values. The array dimension is given by the <em>Number
of detail value columns</em> and the formats of the column values are
referenced by the <em>Displacement to format of first detail value column</em>.
The size of a single value column is given by the <em>Length in bytes</em> in
the corresponding format.</p>
<p><strong>Most frequent values.</strong> The list of most frequent values. See
<a href="#MFVFormat">Most frequent values list entry format</a> for the layout
of this list.</p>
<p><strong>Number of detail value columns.</strong> Number of columns in the
statistics key for this kind of detail values.</p>
<p><strong>Number of detail value entries.</strong> Number of list entries for
this kind of detail values (most frequent values or histogram range values)
returned on this API call. This value will be zero, if this kind of detail
value was not requested to be returned, or, if during this API call, no space
was available anymore to fit any value information of this kind into the user
space besides other requested detail information. Compare the <em>Continuation
handle</em> in the <a href="#HeaderSection">Header Section</a>, how to retrieve
the remaining API information in such a case.</p>
<p><strong>Number of fields to return.</strong> The number of fields to return
in the list.</p>
<p><strong>Offset to fields to return.</strong> Offset to the start of the
array of fields to return.</p>
<p><strong><a name="#OffsetToFieldsSpecified">Offset to fields to return
specified.</a></strong> The offset to fields to return as specified on the call
of the API.</p>
<p><strong>Offset to first detail value entry.</strong> The offset to the start
of the list of this kind of detail value entries within the <a href=
"#STOV0100Format">List data section - STOV0100 Format</a>.</p>
<p><strong>Note:</strong> The offset is relative to the start of the user
space. The offset is valid only if the Number of detail value entries field is
not set to zero.</p>
<p><strong>Offset to value of most frequent value column.</strong> The offset
to the value of the most frequent value column.</p>
<p><strong>Precision.</strong> The precision of the value for numeric data type
values.</p>
<p><strong>Radix.</strong> Whether the value precision is specified in number
of binary or decimal digits for numeric data type values. The possible values
are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Value precision is number of binary digits.</td>
</tr>
<tr>
<td align="left" valign="top"><em>10</em></td>
<td align="left" valign="top">Value precision is number of decimal digits.</td>
</tr>
</table>
<p><strong>Reserved.</strong> Reserved for future use. If this field is input,
the field must be set to hexadecimal zeros.</p>
<p><strong>SQL data type.</strong> The SQLTYPE of the value as explained in the
<a href="../db2/rbafzmst02.htm">SQL Reference</a>.</p>
<p><strong>Scale.</strong> The scale of the value for numeric data type
values.</p>
<p><strong>Translation table library name.</strong> The library where the
translation table used was located. If no translation table was used, the
library name is set to all blanks.</p>
<p><strong><a name="TranslationTableNameField">Translation table
name.</a></strong> The translation table used on the value, when the statistics
collection was created. If no translation table was used, the table name is set
to all blanks.</p>
<p><strong>Note:</strong> The value is actually returned in the translated
form.</p>
<p><strong>User space name specified.</strong> The user space name as specified
on the call of the API.</p>
<p><strong>User space library name specified.</strong> The user space library
name as specified on the call of the API.</p>
<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 &amp;1 not found in record format &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1866 E</td>
<td align="left" valign="top">Value &amp;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 &amp;1 in &amp;2 type *&amp;3 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2113 E</td>
<td align="left" valign="top">Cannot allocate library &amp;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">&amp;1 not a primary or secondary ASP.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3141 E</td>
<td align="left" valign="top">Member &amp;2 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF34C0 E</td>
<td align="left" valign="top">Value &amp;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 &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C1D E</td>
<td align="left" valign="top">Length specified in parameter &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C21 E</td>
<td align="left" valign="top">Format name &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C29 E</td>
<td align="left" valign="top">Object name &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C36 E</td>
<td align="left" valign="top">Number of parameters, &amp;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 &amp;2 for API &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C82 E</td>
<td align="left" valign="top">Key &amp;1 not valid for API &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C89 E</td>
<td align="left" valign="top">Key &amp;1 specified more than once.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CE2 E</td>
<td align="left" valign="top">Continuation handle not valid.</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 &amp;1 API.</td>
</tr>
<tr>
<td align="left" valign="top">CPF4268 E</td>
<td align="left" valign="top">Object &amp;1 in &amp;2 type *&amp;3 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9802 E</td>
<td align="left" valign="top">Not authorized to object &amp;2 in &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9803 E</td>
<td align="left" valign="top">Cannot allocate object &amp;2 in library &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9804 E</td>
<td align="left" valign="top">Object &amp;2 in library &amp;3 damaged.</td>
</tr>
<tr>
<td align="left" valign="top">CPF980B E</td>
<td align="left" valign="top">Object &amp;1 in library &amp;2 not available.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9810 E</td>
<td align="left" valign="top">Library &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9812 E</td>
<td align="left" valign="top">File &amp;1 in library &amp;2 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9814 E</td>
<td align="left" valign="top">Device &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9820 E</td>
<td align="left" valign="top">Not authorized to use library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9822 E</td>
<td align="left" valign="top">Not authorized to file &amp;1 in library &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9825 E</td>
<td align="left" valign="top">Not authorized to device &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9826 E</td>
<td align="left" valign="top">Cannot allocate file &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9830 E</td>
<td align="left" valign="top">Cannot assign library &amp;1</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library &amp;2 ended. Reason code &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB401 E</td>
<td align="left" valign="top">API &amp;3 failed with reason code &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB8ED E</td>
<td align="left" valign="top">Device description &amp;1 not correct for operation.</td>
</tr>
</table>
<br>
<br>
<h3><a name="RelInfo">Related Information</a></h3>
<ul>
<li>the &lt;<strong>qdbst.h</strong>&gt; include file in library QSYSINC, for
API-related structure declarations and special value declarations.<br>
<br>
</li>
<li>the &lt;<strong>qdbstmgr.h</strong>&gt; include file in library QSYSINC,
for the QdbstListDetailStatistics API prototype.<br>
<br>
</li>
<li>the &lt;<strong>qdbstlds.h</strong>&gt; include file in library QSYSINC,
for the QDBSTLDS API prototype.<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="qdbstliststatistics.htm">List Statistics Collections</a> (QDBSTLS,
QdbstListStatistics) API<br>
<br>
</li>
<li><a href="qdbstrequeststatistics.htm">Request Statistics Collections</a>
(QDBSTRS, QdbstRequestStatistics) 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>