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

682 lines
21 KiB
HTML
Raw Blame History

<!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>Get List Entry (QUIGETLE) 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. -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--Edited by Kersten Nov 2001 -->
<!-- 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>Get List Entry (QUIGETLE) 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%">Application handle</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Variable buffer</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">Variable buffer length</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">Variable record name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">List name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Positioning option</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(4)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Copy option</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(1)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">Selection criteria</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="left" valign="top">Selection handle</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(4)</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="left" valign="top">Extend option</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(1)</td>
</tr>
<tr>
<td align="center" valign="top">11</td>
<td align="left" valign="top">List entry handle</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(4)</td>
</tr>
<tr>
<td align="center" valign="top">12</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 Get List Entry (QUIGETLE) API accesses an entry in a list and optionally
updates the corresponding dialog variables to the values in the list entry.</p>
<p>The entry accessed depends on the positioning option parameter and the value
of the current entry pointer for the list. On return to the application
program, the current entry pointer in the list points to the entry retrieved,
except when retrieving the extended action entry. The extended action entry is
a pseudo list entry that can be retrieved using this API, and can be updated
using the Update List Entry (QUIUPDLE) API.</p>
<p>If requested, the corresponding dialog variables contain the values from the
list entry retrieved.</p>
<p>If an error variable corresponding to a field in the list entry is specified
in the variable record, identified by the variable record name parameter, it is
set according to the error state of the corresponding dialog variable.</p>
<br>
<!-- Please NOTE: DO NOT DELETE THIS SECTION if this API has no authorities and locks. -->
<!-- Instead, use the commented out coding below to indicate NONE. -->
<h3>Authorities and Locks</h3>
<!-- Use this if there are no authorities and locks. -->
<p>None.</p>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Application handle</strong></dt>
<dd>INPUT; CHAR(8)
<p> The application handle assigned by the UIM and returned to the application
program by the Open Display Application (QUIOPNDA) or Open Print Application
(QUIOPNPA) API when the application is opened.</p>
</dd>
<dt><strong>Variable buffer</strong></dt>
<dd>OUTPUT; CHAR(*)
<p> The program buffer into which dialog variable values are copied. The dialog
variables are copied in the order specified in the variable record
definition.</p>
<p> If the variable record name parameter specifies the name of a variable
record defined in the panel group for this open application, dialog variables
are copied into the variable buffer from the application variable pool after
the list entry is retrieved. This parameter does the same job as using the Get
Dialog Variable (QUIGETV) API immediately after the QUIGETLE API.</p>
<p> The variable buffer must be large enough to contain all the variables
specified in the variable record definition.</p>
</dd>
<dt><strong>Variable buffer length</strong></dt>
<dd>INPUT; BINARY(4)
<p> The length of the variable buffer. The buffer must be large enough to
contain all the dialog variables in the variable record definition, which is
specified in the variable record name parameter.</p>
</dd>
<dt><strong>Variable record name</strong></dt>
<dd>INPUT; CHAR(10)
<p> The name of the variable record that determines which dialog variables are
copied between the application variable pool and the variable buffer. The
variable record must be defined in the panel group for the open application.
The following special value can be used:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*NONE</em></td>
<td align="left" valign="top">The QUIGETV API is not done during the QUIGETLE
API; the parameter for the variable buffer is ignored when this value is
used.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>List name</strong></dt>
<dd>INPUT; CHAR(10)
<p> The name of the list from which an entry is retrieved. If the list is not
currently active in the open application, an error is reported. A list is made
active the first time an entry is inserted with the Add List Entry (QUIADDLE)
API or Add List Multiple Entries (QUIADDLM) API, or when the list attributes
are set with the Set List Attributes (QUISETLA) API.</p>
</dd>
<dt><strong>Positioning option</strong></dt>
<dd>INPUT; CHAR(4)
<p> The placement of the current entry pointer to the list entry specified. If
a positioning error occurs, the current list position is not changed. One of
the following values must be specified to set the entry pointer to the
appropriate position:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>Value</em></td>
<td align="left" valign="top"><strong>Pointer Position</strong></td>
</tr>
<tr>
<td align="left" valign="top"><em>BOT</em></td>
<td align="left" valign="top">The bottom of the list. A special position just
after the last list entry in a list that is complete at the bottom.</td>
</tr>
<tr>
<td align="left" valign="top"><em>FRST</em></td>
<td align="left" valign="top">The first entry in the currently built list. If
the list is empty, an error is reported.</td>
</tr>
<tr>
<td align="left" valign="top"><em>FSLT</em></td>
<td align="left" valign="top">The entire list is searched in a forward
direction to locate an entry satisfying the condition specified by the
selection criteria parameter. If the list is empty, an error is reported. The
current entry pointer for the list entry is repositioned at the first entry in
the list and the search proceeds forward, including the first entry. The search
does not wrap. Note that if the list is incomplete at the top, the incomplete
list processing program will not be called to complete the list at the top. It
will start searching from the first entry in the currently built list. The
incomplete list processing program will be called to fill in the entries at the
bottom if the list is incomplete at the bottom.</td>
</tr>
<tr>
<td align="left" valign="top"><em>HNDL</em></td>
<td align="left" valign="top">The list entry specified by the selection handle
parameter.</td>
</tr>
<tr>
<td align="left" valign="top"><em>LAST</em></td>
<td align="left" valign="top">The last entry in the currently built list. If
the list is empty, an error is reported.</td>
</tr>
<tr>
<td align="left" valign="top"><em>LSLT</em></td>
<td align="left" valign="top">The entire list is searched in a backward
direction to locate an entry satisfying the condition specified by the
selection criteria parameter. If the list is empty, an error is reported. The
current list entry pointer is repositioned to the last entry in the list and
the search proceeds backward, including the last entry. The search does not
wrap. Note that if the list is incomplete at the bottom, the incomplete list
processing program will not be called to complete the list at the bottom. It
will start searching from the last entry in the currently built list. The
incomplete list processing program will be called to fill in the entries at the
top if the list is incomplete at the top.</td>
</tr>
<tr>
<td align="left" valign="top"><em>NEXT</em></td>
<td align="left" valign="top">The current entry pointer is advanced one entry,
pointing to the next entry in the list.</td>
</tr>
<tr>
<td align="left" valign="top"><em>NSLT</em></td>
<td align="left" valign="top">The list is searched in a forward direction to
locate an entry satisfying the condition specified by the selection criteria
parameter. The search starts with the entry after the current list entry
pointer and does not wrap.</td>
</tr>
<tr>
<td align="left" valign="top"><em>PREV</em></td>
<td align="left" valign="top">The current entry pointer is moved back one
entry, pointing to the previous entry in the list.</td>
</tr>
<tr>
<td align="left" valign="top"><em>PSLT</em></td>
<td align="left" valign="top">The list is searched in a backward direction to
locate an entry satisfying the condition specified by the selection criteria
parameter. The search starts with the entry before the current list entry
pointer and does not wrap.</td>
</tr>
<tr>
<td align="left" valign="top"><em>SAME</em></td>
<td align="left" valign="top">The current entry pointer remains unchanged,
pointing to the same entry in the list.</td>
</tr>
<tr>
<td align="left" valign="top"><em>TOP</em></td>
<td align="left" valign="top">The top of the list. A special position just
prior to the first list entry in a list that is complete at the top.</td>
</tr>
</table>
<p><strong>Note:</strong> After running the QUIGETLE API once with the
positioning option parameter of FSLT or LSLT, the application program should
change the positioning option parameter to NSLT or PSLT. It does this to avoid
repeatedly positioning at the beginning or end of the list and searching the
same list entries.</p>
</dd>
<dt><strong>Copy option</strong></dt>
<dd>INPUT; CHAR(1)
<p> Determines whether or not the data values in the list entry are copied into
the corresponding dialog variables when positioning is complete. One of the
following values must be specified:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>Y</em></td>
<td align="left" valign="top">The data values in the current list entry after
the positioning operations are performed are copied into corresponding dialog
variables. This value must be specified if the variable record name parameter
specifies the name of a variable record defined in the panel group for the open
application. This value is not allowed when the current entry is positioned to
TOP or BOT.</td>
</tr>
<tr>
<td align="left" valign="top"><em>N</em></td>
<td align="left" valign="top">The data values in the current list entry after
positioning the list are not copied into corresponding dialog variables.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Selection criteria</strong></dt>
<dd>INPUT; CHAR(20)
<p> The selection criteria used when positioning the list by variable
selection. Positioning by variable selection allows the application program to
search forward to find the next entry, or backward to find a previous entry
satisfying a given condition. The search is not dependent on sorted list
entries, but the application program might need to build the list in sorted
order to get a consistent result when application comparison operators are
other than equal (EQ) or not equal (NE).</p>
<p> This parameter is only used when one of the following values is specified
for the positioning option parameter: FSLT, LSLT, NSLT, or PSLT. It is ignored
if any other value is specified.</p>
<p> The relational condition defined by this parameter must exist between the
value of a dialog variable and that dialog variable's corresponding value in a
list entry when selection positioning is performed.</p>
<p> The first 10 characters of this parameter must contain a comparison
operator. The operator must be left-adjusted and padded with blanks.</p>
<p>One of the following values must be specified for the comparison
operator:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>EQ</em></td>
<td align="left" valign="top">The list entry value equals the dialog variable
value.</td>
</tr>
<tr>
<td align="left" valign="top"><em>NE</em></td>
<td align="left" valign="top">The list entry value is not equal to the dialog
variable value.</td>
</tr>
<tr>
<td align="left" valign="top"><em>GT</em></td>
<td align="left" valign="top">The list entry value is greater than the dialog
variable value.</td>
</tr>
<tr>
<td align="left" valign="top"><em>LT</em></td>
<td align="left" valign="top">The list entry value is less than the dialog
variable value.</td>
</tr>
<tr>
<td align="left" valign="top"><em>GE</em></td>
<td align="left" valign="top">The list entry value is greater than or equal to
the dialog variable value.</td>
</tr>
<tr>
<td align="left" valign="top"><em>LE</em></td>
<td align="left" valign="top">The list entry value is less than or equal to the
dialog variable value.</td>
</tr>
</table>
<p> The second 10 characters of this parameter must contain the name of the
dialog variable used in the comparison. The dialog variable name specified must
be defined in the list being searched.</p>
</dd>
<dt><strong>Selection handle</strong></dt>
<dd>INPUT; CHAR(4)
<p> The list entry handle used when positioning the current entry pointer to a
specific entry. This parameter is used only when the positioning option
parameter has the value HNDL; it is ignored if any other value is
specified.</p>
<p> The following special value can be specified:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>EXTE</em></td>
<td align="left" valign="top">Retrieves the contents of the extended action
entry. The contents of the extended action entry are copied to the associated
dialog variables in the variable pool. However, the current entry pointer for
the list is not changed when the extended action entry is retrieved.</td>
</tr>
</table>
<p> A list entry handle uniquely distinguishes an entry until it is removed
from the list, even if other entries are inserted and removed from the
list.</p>
</dd>
<dt><strong>Extend option</strong></dt>
<dd>INPUT; CHAR(1)
<p> Indicates whether or not an incomplete list is automatically extended in
the attempt to retrieve the requested list entry. The list can be extended when
one of the following values is specified for the positioning option parameter:
NEXT, PREV, TOP, BOT, NSLT, PSLT, FSLT, or LSLT. This parameter is ignored and
the list is not extended if any other value is specified for the positioning
option parameter.</p>
<p> One of the following values must be specified:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>Y</em></td>
<td align="left" valign="top">The list is extended, if necessary, to find the
requested list entry.</td>
</tr>
<tr>
<td align="left" valign="top"><em>N</em></td>
<td align="left" valign="top">The list is not extended to find the requested
list entry. This option can be used if the program calling the QUIGETLE API
needs to process only entries already in the list.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>List entry handle</strong></dt>
<dd>OUTPUT; CHAR(4)
<p> The list entry handle from the current entry pointer in the list. This
value is the handle of the entry to which the list was last positioned by this
API. The following special values may be returned:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>TOP</em></td>
<td align="left" valign="top">The current entry pointer is positioned at the
top of the list.</td>
</tr>
<tr>
<td align="left" valign="top"><em>BOT</em></td>
<td align="left" valign="top">The current entry pointer is set at the bottom of
the 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>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">CPF3C90 E</td>
<td width="85%" valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6AA0 E</td>
<td align="left" valign="top">Request is not allowed when extending a list that
is not complete.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A0B E</td>
<td align="left" valign="top">Application handle &amp;3 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A0C E</td>
<td align="left" valign="top">Application domain error for application
&amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A0F E</td>
<td align="left" valign="top">Previous error occurred while running application
&amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A14 E</td>
<td align="left" valign="top">Program defined by variable &amp;4 cannot be
called.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A15 E</td>
<td align="left" valign="top">Errors occurred in list exit program.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A2C E</td>
<td align="left" valign="top">Value for Option parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A2D E</td>
<td align="left" valign="top">Value for Selection Criteria parameter not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A24 E</td>
<td align="left" valign="top">Parameter &amp;1 not passed correctly.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A25 E</td>
<td align="left" valign="top">Return code length of &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A27 E</td>
<td align="left" valign="top">Value for Extend Option parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A38 E</td>
<td align="left" valign="top">Variable record &amp;4 not defined in panel
group.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A39 E</td>
<td align="left" valign="top">Variable buffer length too small.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A91 E</td>
<td align="left" valign="top">List &amp;4 does not exist.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A92 E</td>
<td align="left" valign="top">List &amp;4 not active.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A93 E</td>
<td align="left" valign="top">Operation not valid when current entry is
&amp;5.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A95 E</td>
<td align="left" valign="top">List &amp;4 either not complete or not
extended.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A96 E</td>
<td align="left" valign="top">Variable &amp;5 is not in list definition.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A97 E</td>
<td align="left" valign="top">Variable &amp;5 not valid type for select
comparison.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A98 E</td>
<td align="left" valign="top">Entry not found in list &amp;4 in panel group
&amp;1 in &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>
</table>
<br>
<hr>
API introduced: V3R6
<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=
"uim1.htm">User Interface Manager (UIM) APIs</a> | <a href="aplist.htm">APIs by
category</a> </td>
</tr>
</table>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink