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

542 lines
14 KiB
HTML
Raw Permalink 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>Retrieve User Index Attributes (QUSRUIAT) 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. -->
<!-- QUSRUIAT SCRIPT A converted by B2H R4.1 (346) (CMS) by PMHALL at -->
<!-- RCHVMW2 on 7 Oct 1998 at 17:22:54 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- Edited by Kersten Jan 02 -->
<!--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 language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<h2>Retrieve User Index Attributes (QUSRUIAT) API</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%">Receiver variable</td>
<td align="left" valign="top" width="20%">Output</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Length of receiver variable</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 name</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">Qualified user index name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">5</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;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Retrieve User Index Attributes (QUSRUIAT) API retrieves information
about the current attributes and the current operational statistics of the
user index.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>User Index Library Authority</em></dt>
<dd>*EXECUTE</dd>
<dt><em>User Index Authority</em></dt>
<dd>*USE</dd>
<dt><em>User Index Lock</em></dt>
<dd>*SHRUPD</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The variable that is to receive the information requested. You can
specify the size of this area to be smaller than the format requested if
you specify the length of receiver variable parameter correctly. As a
result, the API returns only the data that the area can hold.</p>
</dd>
<dt><strong>Length of receiver variable</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the receiver variable. If the length is larger than the
size of the receiver variable, the results may not be predictable. The
minimum length is 8 bytes.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the index information returned.</p>
<p>The format name supported is:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>IDXA0100</em></td>
<td align="left" valign="top">Basic information</td>
</tr>
</table>
<p>Refer to <a href="#HDRRTVA1">IDXA0100 Format</a> for details on the
format.</p>
</dd>
<dt><strong>Qualified user index name</strong></dt>
<dd>INPUT; CHAR(20)
<p>The user index for which you want to retrieve information, and the
library in which it is located. The first 10 characters contain the user
index name, and the second 10 characters contain the library name.</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</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list</td>
</tr>
</table>
<br>
</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>
<h3><a name="HDRRTVA1">IDXA0100 Format</a></h3>
<p>The following information is returned for the IDXA0100 format. For
detailed descriptions of the fields in the table, see <a href="#HDRRTVA2">
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%">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">Bytes available</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">User index name</td>
</tr>
<tr>
<td align="center" valign="top">18</td>
<td align="center" valign="top">12</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">User index library name</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Entry length attribute</td>
</tr>
<tr>
<td align="center" valign="top">29</td>
<td align="center" valign="top">1D</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Immediate update</td>
</tr>
<tr>
<td align="center" valign="top">30</td>
<td align="center" valign="top">1E</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Key insertion</td>
</tr>
<tr>
<td align="center" valign="top">31</td>
<td align="center" valign="top">1F</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Optimized processing mode</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">CHAR(4)</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">BINARY(4)</td>
<td align="left" valign="top">Entry length</td>
</tr>
<tr>
<td align="center" valign="top">40</td>
<td align="center" valign="top">28</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Maximum entry length</td>
</tr>
<tr>
<td align="center" valign="top">44</td>
<td align="center" valign="top">2C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Key length</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">Number of entries added</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">Number of entries removed</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 retrieve operations</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRRTVA2">Field Descriptions</a></h3>
<p><strong>Bytes available.</strong> The length of all data available to
return. All available data is returned if enough space is provided.</p>
<p><strong>Bytes returned.</strong> The length of the data actually
returned.</p>
<p><strong>Entry length.</strong> For user indexes with fixed-length
entries, this is the length of each index entry. For user indexes with
variable-length entries, this is equal to the longest entry that has ever
been inserted into the index. Valid values are from 1 through 2000.</p>
<p><strong>Entry length attribute.</strong> The types of entries in the
user index.</p>
<p>Possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>F</em></td>
<td align="left" valign="top">Fixed-length entries</td>
</tr>
<tr>
<td align="left" valign="top"><em>V</em></td>
<td align="left" valign="top">Variable-length entries</td>
</tr>
</table>
<p><strong>Immediate update.</strong> Whether or not the updates to the
index are written synchronously to auxiliary storage on each update to the
index.</p>
<p>The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">No immediate update</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Immediate update</td>
</tr>
</table>
<p><strong>Key insertion.</strong> Whether or not the inserts to the index
are by key.</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">No insertion by key</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Insertion by key</td>
</tr>
</table>
<p><strong>Key length.</strong> The length of the key where the first byte
of an entry is the beginning of the key for the index entries. This field
will be 0 for a nonkeyed user index.</p>
<p><strong>Maximum entry length.</strong> The maximum entry length any
user index entry can have.</p>
<p><strong>Number of entries added.</strong> The number of entries added
to the user index. The number of entries currently in the index can be
obtained by subtracting the number of entries removed from the number of
entries added.</p>
<p><strong>Number of entries removed.</strong> The number of entries
removed from the user index.</p>
<p><strong>Number of retrieve operations.</strong> The number of times
either the FNDINXEN (find independent index entry) MI instruction or
Retrieve User Index Entry (QUSRTVUI) API has been used on this user index.
The QUSRUIAT API or MATINXAT (materialize independent index attributes) MI
instruction sets the number of retrieve operations to 0 after the retrieve
or materialize operation is completed.</p>
<p><strong>Optimized processing mode.</strong> Whether the user index is
maintained in a manner that optimizes performance for:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Random references</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Sequential references</td>
</tr>
</table>
<p><strong>Reserved.</strong> An ignored field.</p>
<p><strong>User index library name.</strong> The name of the library
containing the user index. This information is helpful when *CURLIB or
*LIBL is specified in the qualified user index name parameter.</p>
<p><strong>User index name.</strong> The name of the user index.</p>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPF24B4 E</td>
<td width="85%" valign="top">Severe error while addressing parameter list.</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">CPF3C19 E</td>
<td align="left" valign="top">Error occurred with receiver variable specified.</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">CPF3C24 E</td>
<td align="left" valign="top">Length of the receiver variable is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C90 E</td>
<td align="left" valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF8100 E</td>
<td align="left" valign="top">All CPF81xx messages could be returned. xx is from 01 to
FF.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9801 E</td>
<td align="left" valign="top">Object &amp;2 in library &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">CPF9807 E</td>
<td align="left" valign="top">One or more libraries in library list deleted.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9808 E</td>
<td align="left" valign="top">Cannot allocate one or more libraries on library
list.</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">CPF9820 E</td>
<td align="left" valign="top">Not authorized to use library &amp;1.</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>
</table>
<br>
<hr>
API introduced: V2R3
<hr>
<table cellpadding="2" cellspacing="2" align="center">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href="obj1.htm">Object API categories</a> | <a
href="aplist.htm">API by category</a></td>
</tr>
</table>
</body>
</html>