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

725 lines
20 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>Open List of Validation List Entries (QSYOLVLE) 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. -->
<!-- Sec SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- 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 type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<h2>Open List of Validation List Entries (QSYOLVLE) 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">List information</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(80)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Number of records to return</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 name</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">Qualified validation list name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">7</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: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Open List of Validation List Entries (QSYOLVLE) API returns a list of
validation list entries in a validation list object. Upon successful completion
of this API, a handle is returned in the list information parameter. You may
use this handle on subsequent calls to the following APIs:</p>
<ul>
<li>Get List Entries (QGYGTLE)</li>
<li>Find List Entry (QGYFNDE)</li>
<li>Close List (QGYCLST)</li>
</ul>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Authority to Validation List</em></dt>
<dd>*USE</dd>
<dt><em>Authority to Validation List Library</em></dt>
<dd>*EXECUTE</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The receiver variable that receives the information requested. You can
specify the size of the 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>
</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 are not predictable.</p>
</dd>
<dt><strong>List Information</strong></dt>
<dd>OUTPUT; CHAR(80)
<p>Information about the list that is created by this program. See <a href=
"#HDRLVLELI">Format of List information</a> for a description of the layout of
this parameter.</p>
</dd>
<dt><strong>Number of records to return</strong></dt>
<dd>INPUT; BINARY(4)
<p>The number of records in the list to put into the receiver variable.
Possible values follow:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top">The entire list is built synchronously.</td>
</tr>
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The entire list is built asynchronously in a
server job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>Positive number of records</em></td>
<td align="left" valign="top">At least that many records will be built
synchronously and the remainder will be built asynchronously in a server
job.</td>
</tr>
</table>
<br>
<br>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The name of the format that is used to return information about the
validation list entries.</p>
<p>You can specify these formats:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em><a href="#HDRVLD1G">VLDE0100</a></em></td>
<td align="left" valign="top">The order and format of the data that is returned
in the receiver variable for each validation list entry in the list.</td>
</tr>
</table>
<br>
<br>
</dd>
<dt><strong>Qualified validation list name</strong></dt>
<dd>INPUT; CHAR(20)
<p>The qualified object name of the validation list that contains the entries
to return. The first 10 characters specify the validation list name, and the
second 10 characters specify the library. 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 current library is used to locate the
validation list. If there is no current library, QGPL (general purpose library)
is used.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list is used to locate the validation
list.</td>
</tr>
</table>
<br>
<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="HDRLVLELI">Format of List information</a></h3>
<p>For detailed descriptions of the fields in the tables, see <a href=
"#HDRfield">Field Descriptions</a>.<br>
</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%">Total records</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">Records returned</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">CHAR(4)</td>
<td align="left" valign="top">Request handle</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">Record length</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Information complete indicator</td>
</tr>
<tr>
<td align="center" valign="top">17</td>
<td align="center" valign="top">11</td>
<td align="left" valign="top">CHAR(13)</td>
<td align="left" valign="top">Date and time created</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">List status indicator</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">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of information returned</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">First record in buffer</td>
</tr>
<tr>
<td align="center" valign="top">40</td>
<td align="center" valign="top">28</td>
<td align="left" valign="top">CHAR(40)</td>
<td align="left" valign="top">Reserved</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRfield">Field Descriptions</a></h3>
<p><strong>Date and time created.</strong> The date and time when the list was
created. The 13 characters are:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Century, where 0 indicates years 19<em>xx</em>
and 1 indicates years 20<em>xx</em>.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2-7</em></td>
<td align="left" valign="top">The date, in YYMMDD (year, month, and day)
format.</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>8-13</em></td>
<td align="left" valign="top">The time of day, in HHMMSS (hours, minutes, and
seconds) format.</td>
</tr>
</table>
<p><strong>First record in buffer.</strong> The number of the first record in
the receiver variable.</p>
<p><strong>Information complete indicator.</strong> Whether all information
that was requested has been supplied.</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>I</em></td>
<td align="left" valign="top">Incomplete information. An interruption causes
the list to contain incomplete information about a buffer or buffers.</td>
</tr>
<tr>
<td align="left" valign="top"><em>P</em></td>
<td align="left" valign="top">Partial and accurate information. Partial
information is returned when the maximum space was used and not all of the
buffers requested were read.</td>
</tr>
<tr>
<td align="left" valign="top"><em>C</em></td>
<td align="left" valign="top">Complete and accurate information. All the
buffers requested are read and returned.</td>
</tr>
</table>
<p><strong>Length of information returned.</strong> The size in bytes of the
information returned in the receiver variable.</p>
<p><strong>List status indicator.</strong> The status of building the list.
Possible values follow:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The list building is pending.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The list is in the process of being built.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">The list has been completely built.</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">An error occurred when building the list. An
error will be signalled to the caller of the QGYGTLE API.</td>
</tr>
<tr>
<td align="left" valign="top"><em>4</em></td>
<td align="left" valign="top">The list is primed and ready to be built.</td>
</tr>
</table>
<p><strong>Record length.</strong> The length of each record of information
returned. This value will be set to 0 because the record lengths are variable.
You can obtain the length of individual records from the records
themselves.</p>
<p><strong>Records returned.</strong> The number of records returned in the
receiver variable.</p>
<p>This is the smallest of the following three values:</p>
<ul>
<li>The number of records that fit into the receiver variable.</li>
<li>The number of records in the list.</li>
<li>The number of records that are requested.</li>
</ul>
<p><strong>Request handle.</strong> The handle of the request that can be used
for subsequent requests of information from the list. The handle is valid until
the Close List (QGYCLST) API is called to close the list, or until the job
ends.</p>
<p><strong>Note:</strong> This field should be treated as a hexadecimal field.
It should not be converted from one CCSID to another, for example, EBCDIC to
ASCII, because doing so could result in an unusable value.</p>
<p><strong>Reserved.</strong> An ignored field.</p>
<p><strong>Total records.</strong> The total number of records available in the
list.<br>
</p>
<h3><a name="HDRVLD1G">VLDE0100 Format</a></h3>
<p>The following table describes the order and format of the data that is
returned in the receiver variable for each validation list entry in the list.
For detailed descriptions of the fields in the table, see <a href=
"#HDROLVLEFL">Field Descriptions</a>.<br>
</p>
<table border width="80%">
<tr>
<th align="center" valign="bottom" colspan="2">Offset</th>
<th align="left" valign="bottom" rowspan="2">Type</th>
<th align="left" valign="bottom" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">0</td>
<td align="center" valign="top" width="10%">0</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Length of 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">Displacement to entry ID</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 entry ID</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">CCSID of entry ID</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 encrypted data</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 encrypted data</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 of encrypted data</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">Displacement to entry data</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of entry data</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">CCSID of entry data</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">Entry ID</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">Encrypted data</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">Entry data</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDROLVLEFL">Field Descriptions</a></h3>
<p><strong>CCSID of encrypted data.</strong> The CCSID of the encrypted data
that was specified when the validation list entry was added or changed.</p>
<p><strong>CCSID of entry data.</strong> The CCSID of the entry data that was
specified when the validation list entry was added or changed.</p>
<p><strong>CCSID of entry ID.</strong> The CCSID of the entry ID that was
specified when the validation list entry was added.</p>
<p><strong>Displacement to encrypted data.</strong> The displacement in the
entry to the start of the encrypted data.</p>
<p><strong>Displacement to entry data.</strong> The displacement in the entry
to the start of the entry data.</p>
<p><strong>Displacement to entry ID.</strong> The displacement in the entry to
the start of the entry ID.</p>
<p><strong>Encrypted data.</strong>
The encrypted data associated with the validation list entry. This data is only
returned if the entry specifies that the encrypted data is two way encrypted,
the QRETSVRSEC system value is '1', and the user has *USE, *ADD, and *UPD
authority to the validation list. If the data is to be returned, it is
decrypted and returned in this field.</p>
<p><strong>Entry data.</strong> The data associated with the validation list
entry.</p>
<p><strong>Entry ID.</strong> The entry ID for the validation list entry.</p>
<p><strong>Length of encrypted
data.</strong> The length (in bytes) of the encrypted data. If the data is
one-way encrypted, the QRETSVRSEC system value is '0', or the user is not
authorized to have the encrypted data returned, this value will be 0.</p>
<p><strong>Length of entry.</strong> The length (in bytes) of the current
entry. This length can be used to access the next entry.</p>
<p><strong>Length of entry data.</strong> The length (in bytes) of the entry
data.</p>
<p><strong>Length of entry ID.</strong> The length (in bytes) of the entry
ID.<br>
</p>
<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">CPF226B E</td>
<td align="left" valign="top">Validation list entry does not exist.</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">CPF3C90 E</td>
<td align="left" valign="top">Literal value cannot be changed.</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">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">CPF9804 E</td>
<td align="left" valign="top">Object &amp;2 in library &amp;3 damaged.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9821 E</td>
<td align="left" valign="top">Not authorized to program &amp;1 in library
&amp;2.</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">GUI0002 E</td>
<td align="left" valign="top">&amp;2 is not valid for length of receiver
variable.</td>
</tr>
<tr>
<td align="left" valign="top">GUI0027 E</td>
<td align="left" valign="top">&amp;1 is not valid for number of records to
return.</td>
</tr>
</table>
<br>
<hr>
API introduced: V4R2
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"sec.htm">Security APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>