friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
14ed2849c6
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qusrtvui.htm

783 lines
22 KiB
HTML
Raw Normal View History

Add readme and dist folders
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 Entries (QUSRTVUI) 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. -->
<!-- QUSRTVUI SCRIPT A converted by B2H R4.1 (346) (CMS) by PMHALL at -->
<!-- RCHVMW2 on 7 Oct 1998 at 17:16:10 -->
<!-- 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 Entries (QUSRTVUI) 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%">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">Entry lengths and entry offsets</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Array(*) of Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Length of entry lengths and offsets</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">Number of entries returned</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Returned library name</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">7</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">8</td>
<td align="left" valign="top">Format</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="left" valign="top">Maximum number of entries</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="left" valign="top">Search type</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">11</td>
<td align="left" valign="top">Search criteria</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="left" valign="top">Length of search criteria</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">13</td>
<td align="left" valign="top">Search criteria offset</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">14</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 Entries (QUSRTVUI) API retrieves user index
entries that match the criteria specified on the search criteria
parameter.</p>
<p>The entries are always returned starting with the entry that is closest
to or equal to the search criteria parameter and then proceeding away from
the search criteria. The number of entries returned parameter will never
exceed the value specified in the maximum number of entries parameter.
Each entry retrieved from the user index is based on the binary value of
the search criteria parameter. No other collating sequence is
supported.</p>
<p>Every entry retrieved causes the number of retrieve operations to be
incremented by 1.</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 as
long as you specify the length parameter correctly. As a result, the API
returns only the data that the area can hold.</p>
<p>Use the entry lengths and entry offsets parameter to parse through this
parameter. If the number of entries returned parameter is 0, then only the
bytes available and the bytes provided have been changed.</p>
<p>To determine if all the entries are valid in the receiver variable,
compare the bytes returned and bytes available fields. If the bytes
returned are less than the bytes available, your receiver variable is not
large enough to hold all the entries that match the search criteria
parameter. While processing the entries, you need to make sure that
both:</p>
<ul>
<li>Your current offset in the receiver variable plus the entry offset is
less than the length of the receiver variable</li>
<li>Your current offset in the receiver variable plus the entry offset
plus the entry length is less than the length of the receiver
variable.</li>
</ul>
<p>The size of the receiver variable parameter should be greater than or
equal to:</p>
<pre>
8 + (the maximum number of entries parameter
* the maximum entry length)
</pre>
<p>The maximum entry length was defined when the index was created. It can
be obtained by using the Retrieve User Index Attributes (QUSRUIAT)
API.</p>
<p>Refer to the <a href="#HDRRTVE1">IDXE0100 Format</a> for the layout of
this parameter.</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>Entry lengths and entry offsets</strong></dt>
<dd>OUTPUT; ARRAY(*) of CHAR(8)
<p>A data structure containing entry lengths and entry offsets for all
entries found that met the search criteria. An entry length and entry
offset exist for every entry returned in the receiver variable. These
entry lengths and entry offsets are used to parse through the receiver
variable.</p>
<p>The size of the entry lengths and entry offsets parameter should be at
least:</p>
<pre>
8 + (the maximum number of entries parameter * 8)
</pre>
<p>You must provide enough space in both the receiver variable and the
entry lengths and entry offsets parameter for this API to return this
information to you. You will not receive complete information in the
following two situations.</p>
<ul>
<li>You provide enough space in the receiver variable parameter for the
API to return all index entries, but there is not enough space in the
entry lengths and entry offset parameter to return the lengths and offsets
for all entries. You will be unable to parse through all of the entries in
the receiver variable parameter. Check the bytes returned and bytes
available fields in the entry lengths and entry offsets parameter to
ensure that the information is complete.</li>
<li>You provide enough space in the entry lengths and entry offsets
parameter to return all lengths and offsets, but there is not enough space
in the receiver variable parameter to return all index entries
retrieved.
Some of the entry lengths and entry offsets will not be valid; they will
refer to index entries that could not be returned to you. Check the bytes
returned and bytes available fields in the receiver variable parameter to
ensure that the information is complete.</li>
</ul>
<p>See the <a href="#HDRRTVE2">Format for Entry Lengths and Entry
Offsets</a> for details about the data structure.</p>
</dd>
<dt><strong>Length of entry lengths and entry offsets</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the entry lengths and entry offsets parameter. If the
length is longer than the entry lengths and entry offsets parameter, the
results may not be predictable. The minimum length is 8.</p>
<p>If the receiver variable cannot hold all the entries that satisfy the
search criteria:</p>
<ul>
<li>The entries are truncated.</li>
<li>Not all the information in the entry lengths and entry offsets
parameter is valid.</li>
</ul>
</dd>
<dt><strong>Number of entries returned</strong></dt>
<dd>OUTPUT; BINARY(4)
<p>The total number of index entries found that satisfy the search
criteria. If this field is 0, no entries satisfied the search criteria.
This value can never be greater than the maximum number of entries
parameter.</p>
</dd>
<dt><strong>Returned library name</strong></dt>
<dd>OUTPUT; CHAR(10)
<p>The name of the library that contains the user index from which
the entries were successfully retrieved. This parameter is not set if an
error occurs.</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>Format</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the receiver variable.</p>
<p>The format name supported is:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>IDXE0100</em></td>
<td align="left" valign="top">Basic Information</td>
</tr>
</table>
<p>Refer to <a href="#HDRRTVE1">IDXE0100 Format</a> for details about the
format.</p>
</dd>
<dt><strong>Maximum number of entries</strong></dt>
<dd>INPUT; BINARY(4)
<p>The maximum number of index entries to be returned that match the
search criteria. Valid values are 1 through 4095.</p>
</dd>
<dt><strong>Search type</strong></dt>
<dd>INPUT; BINARY(4)
<p>The type of search that is to be performed.</p>
<p>Valid values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Equal
<p>Find entries that are equal to the searcg criteria.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Greater than
<p>Find entries that are greater than the search criteria.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">Less than
<p>Find entries that are less than the search criteria.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>4</em></td>
<td align="left" valign="top">Greater than or equal
<p>Find entries that are greater than or equal to the search criteria.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>5</em></td>
<td align="left" valign="top">Less than or equal
<p>Find entries that are less than or equal to the search criteria.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>6</em></td>
<td align="left" valign="top">First
<p>Find the first index entry or entries.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>7</em></td>
<td align="left" valign="top">Last
<p>Find the last index entry or entries.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>8</em></td>
<td align="left" valign="top">Between
<p>Find all entries between the two arguments specified in the search
criteria.</p>
</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Search criteria</strong></dt>
<dd>INPUT; CHAR(*)
<p>The criteria used to find matches in the user index.</p>
<p>If the search type is 8 (between), both search elements must have the
same length. When the search type is 8 (between), this parameter contains
two search elements. The first element is considered the starting element,
and the second element is the ending element.</p>
<p>This parameter is ignored when the search type parameter is 6 (first)
or 7 (last).</p>
</dd>
<dt><strong>Length of search criteria</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the search criteria that is to be used. This parameter is
ignored when the search type is 6 (first) or 7 (last).</p>
<p>If the search type is 8 (between), this parameter specifies the length
of the first element. The second element must have the same length as the
first element. Valid values are 1-2000, depending on how the user index
was created.</p>
<p>For a fixed and keyed user index, the length of the search
criteria:</p>
<ul>
<li>Can be greater than the length of the key</li>
<li>Must be less than or equal to the entry length</li>
</ul><br>
</dd>
<dt><strong>Search criteria offset</strong></dt>
<dd>INPUT; BINARY(4)
<p>The offset of the second search element from the beginning of the
search criteria parameter. This parameter is ignored unless the search
type is 8 (between).</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>
<h3><a name="HDRRTVE2">Format for Entry Lengths and Entry Offsets</a></h3>
<p>The following information is returned in the entry lengths and entry
offsets parameter. The information is needed to parse through the receiver
variable. For detailed descriptions of the fields in the table, see <a
href="#HDRRTVE3">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="left" valign="top" colspan="4"><strong>Note:</strong> The
following fields will be repeated. The number of times they are repeated
depends on the length of the entry lengths and entry offsets parameter and
the number of entries actually retrieved.</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Entry length</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Entry offset</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRRTVE1">IDXE0100 Format</a></h3>
<p>The following index information is returned for the IDXE0100 format in
the receiver variable parameter. For detailed descriptions of the fields
in the table, see <a href="#HDRRTVE3">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(*)</td>
<td align="left" valign="top">Entry 1-n</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRRTVE3">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> The length of the entry retrieved from
the index. Valid values are 1-2000, depending on how the user index was
created.</p>
<p><strong>Entry offset.</strong> The number of bytes from the beginning
of the immediately preceding entry to the first byte of the entry
returned. For the first entry, the offset is the number of bytes from the
beginning of the receiver variable to the first byte of the first
entry.</p>
<p><strong>Entry 1-n.</strong> All entries that satisfy the search
criteria (up to the maximum number of entries parameter) are returned.
User indexes are created to contain only scalar data, which results in the
index entries being contiguous. Use the entry length and entry offset
values to parse this field.</p>
<p>This field is repeated by the value in the number of entries returned
parameter if the receiver variable is large enough to hold all of the
entries found.
</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">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">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">CPF3C7A E</td>
<td align="left" valign="top">Search type &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C7D E</td>
<td align="left" valign="top">Remove or search information is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C76 E</td>
<td align="left" valign="top">Length of lengths and offsets of entries &amp;1 is not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C78 E</td>
<td align="left" valign="top">Criteria length &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C79 E</td>
<td align="left" valign="top">Maximum number of entries &amp;1 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">CPF9838 E</td>
<td align="left" valign="top">User profile storage limit exceeded.</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>
Reference in New Issue Copy Permalink