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

754 lines
22 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>Remove User Index Entries (QUSRMVUI) 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. -->
<!-- QUSRMVUI SCRIPT A converted by B2H R4.1 (346) (CMS) by PMHALL at -->
<!-- RCHVMW2 on 7 Oct 1998 at 22:42:51 -->
<!-- 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>Remove User Index Entries (QUSRMVUI) 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%">Number of entries removed</td>
<td align="left" valign="top" width="20%">Output</td>
<td align="left" valign="top" width="20%">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Entries removed</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Length of entries removed</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">4</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">5</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">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">Remove 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">Remove 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 remove 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">Remove 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 Remove User Index Entries (QUSRMVUI) API removes one or more user index
entries that match the values specified on the remove criteria parameter. It
returns the number of entries that were removed and, optionally, returns the
actual index entries removed.</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>*CHANGE</dd>
<dt><em>User Index Lock</em></dt>
<dd>*SHRUPD</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Number of entries removed</strong></dt>
<dd>OUTPUT; BINARY(4)
<p>The number of index entries, satisfying the values specified on the remove
criteria parameter, that were successfully removed from the user index. If this
field is 0, no entries satisfied the remove criteria. This value can never be
greater than the maximum number of entries parameter.</p>
</dd>
<dt><strong>Entries removed</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The actual entries removed. All entries that satisfied the remove criteria
parameter and were removed (up to the maximum number of entries parameter) are
returned if sufficient space is provided. The API returns only the data that
the area can hold.</p>
<p>The size of the entries removed 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>To determine if all the entries are valid in the entries removed parameter,
compare the bytes returned and the bytes available fields in the entries
removed parameter.</p>
<p>The entries are always returned starting with the entry that is closest to
or equal to the remove argument. Then entries are kept in the order that they
proceed away from the remove criteria parameter. Each entry removed from the
user index is based on the binary value of the remove criteria. No other
collating sequence is supported. User indexes can contain only scalar data,
which makes the index entries contiguous. Use the entry lengths and entry
offsets parameter to parse the entries that were removed and returned in this
parameter.</p>
<p>If you do not want the entries that were removed to be returned in this
parameter, specify 0 for the length of entries removed parameter.</p>
<p>Every entry removed causes the number of entries removed parameter to be
incremented by 1. You can also use the Retrieve User Index Attributes
(QUSRUIAT) API to retrieve this information.</p>
<p>Refer to <a href="#HDRIDX02">IDXE0100 Format</a> for the layout of this
parameter.</p>
</dd>
<dt><strong>Length of entries removed</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the entries removed parameter. If this length is larger than
the actual size of the entries removed parameter, the results may not be
predictable. The minimum length is 0 or &gt;= (greater than or equal to) 8
bytes. If 0 is used, the entries removed from the index are not returned and
the bytes returned and the bytes available in the entries removed parameter are
not set.</p>
</dd>
<dt><strong>Entry lengths and entry offsets</strong></dt>
<dd>OUTPUT; ARRAY of CHAR(8)
<p>A data structure that contains entry lengths and entry offsets for all
entries that were found that met the remove criteria parameter. An entry length
and entry offset exist for every entry returned in the entries removed
parameter. These entry lengths and entry offsets are used to parse through the
entries removed parameter. If the length of entries removed parameter is 0,
this information will not be returned.</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 entries removed and the entry
lengths and offset parameter for this API to return complete information to
you.</p>
<p>You will not receive complete information in the following two
situations.</p>
<ul>
<li>You provide enough space in the entries removed parameter for the API to
return all index entries removed, 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 entries
removed parameter. Check the bytes returned and bytes available fields in the
entry lengths and entry offsets parameter to ensure 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 entries
removed parameter to return all index entries removed. 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 entries removed parameter to ensure that the information is
complete.</li>
</ul>
<p>See <a href="#HDRRMV01">Format for Entry Lengths and Entry Offsets</a> for
details on 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. If the length is longer
than the entry lengths and entry offsets parameter, the results may not be
predictable. The minimum length is 8. If the length of entries removed
parameter is 0, which means you do not want the entries removed to be returned,
this parameter is ignored.</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 removed. If the entries are successfully removed from the user index, the
name of the library that contained the user index entries is returned. 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 from which you want to remove entries, 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 user index entries that were removed.</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>
<br>
<p>Refer to <a href="#HDRIDX02">IDXE0100 Format</a> for details on the
format.</p>
</dd>
<dt><strong>Maximum number of entries</strong></dt>
<dd>INPUT; BINARY(4)
<p>The maximum number of user index entries to be removed that satisfy the
remove criteria. Valid values are 1 through 4095.</p>
</dd>
<dt><strong>Remove type</strong></dt>
<dd>INPUT; BINARY(4)
<p>The type of remove operation 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>Remove entries that are equal to the remove criteria.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Greater than
<p>Remove entries that are greater than the remove criteria.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">Less than
<p>Remove entries that are less than the remove criteria.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>4</em></td>
<td align="left" valign="top">Greater than or equal
<p>Remove entries that are greater than or equal to the remove criteria.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>5</em></td>
<td align="left" valign="top">Less than or equal
<p>Remove entries that are less than or equal to the remove criteria.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>6</em></td>
<td align="left" valign="top">First
<p>Remove 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>Remove 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>Remove all entries between the two arguments specified in the remove
criteria.</p>
</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Remove criteria</strong></dt>
<dd>INPUT; CHAR(*)
<p>The criteria used to find matches in the user index.</p>
<p>When the remove type is 8 (between), this parameter contains two criteria
elements of the same length. The first element is considered the starting
element, and the second element is the ending element. This parameter is
ignored when the remove type is 6 (first) or 7 (last).</p>
</dd>
<dt><strong>Length of remove criteria</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the remove criteria being used. This parameter is ignored when
the remove type is 6 (first) or 7 (last). If the remove 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 remove criteria can be
greater than the length of the key.</p>
</dd>
<dt><strong>Remove criteria offset</strong></dt>
<dd>INPUT; BINARY(4)
<p>The offset of the second element from the beginning of the remove criteria
parameter. This parameter is ignored unless the remove 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="HDRRMV01">Format for Entry Lengths and Entry Offsets</a></h3>
<p>The following information is returned in the entry lengths and entry offsets
parameter. This information is needed to parse through the entries removed
parameter. For detailed descriptions of the fields in the table, see <a href=
"#HDRRMV03">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 removed.</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="HDRIDX02">IDXE0100 Format</a></h3>
<p>The following information is returned for the IDXE0100 format. For detailed
descriptions of the fields in the table, see <a href="#HDRRMV03">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="HDRRMV03">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 removed from the user
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
parameter to the first byte of the first entry.</p>
<p><strong>Entry 1-n.</strong> All entries that satisfy the remove criteria (up
through the maximum number of entries) are returned. User indexes contain only
scalar data, which makes the index entries contiguous. Use the entry length and
entry offset values to parse this parameter.</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">CPF3C21 E</td>
<td align="left" valign="top">Format name &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">CPF3C70 E</td>
<td align="left" valign="top">Length of entries removed parameter 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">CPF3C77 E</td>
<td align="left" valign="top">Remove type &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>