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/quigetlm.htm

747 lines
23 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>Get List Multiple Entries (QUIGETLM) 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 Multiple Entries (QUIGETLM) 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">Number of records</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">Record size</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">Record count</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">15</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 Multiple Entries (QUIGETLM) API accesses one or more entries in
a list and updates the corresponding dialog variables with the values contained
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 last entry
retrieved, except when retrieving the extended action entry. The extended
action entry can be retrieved using this API, and can be updated using the
Update List Entry (QUIUPDLE) API.</p>
<p>When the operation completes successfully, the corresponding dialog
variables contain the values from the last list entry retrieved.</p>
<p>If an error variable corresponding to a field in the list entry is specified
in the variable record, which is 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 -->
<!-- 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) API 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> 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 list
entry is retrieved.</p>
<p> The variable buffer must be large enough to contain all the variables
specified in the variable record definition.</p>
<p> When the number of records parameter is greater than 1, the size of the
variable buffer must be at least equal to the value specified on the number of
records parameter multiplied by the value specified on the record size
parameter.</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 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.</p>
<p> The special value of *NONE may not be used with the QUIGETLM API.</p>
</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)
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> Sets 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 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.</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.</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 QUIGETLM 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. Y must be used if the number of records parameter is greater than
1. 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 using comparison operators other than
equal (EQ) or not equal (NE).</p>
<p> This parameter is only used when FSLT, LSLT, NSLT, or PSLT is specified for
the positioning option parameter. It is ignored if any other value is
specified.</p>
<p> The relational condition defined by this parameter must exist between the
dialog variable value 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 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 content 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. If any other value is
specified for the positioning option parameter, this parameter is ignored and
the list is not extended.</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.</p>
<p> 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>Number of records</strong></dt>
<dd>INPUT; BINARY(4)
<p> The total number of entries to retrieve from the list. The following
special value can be used:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Only one entry is retrieved from the list. The
record size and record count parameters are ignored when this value is
used.</td>
</tr>
</table>
<p> When this parameter is greater than 1, the variable buffer must contain
space for all the entries retrieved from the list.</p>
<p> When this parameter is greater than 1 (multiple entries are being
retrieved), the positioning option parameter must have one of the following
values: NEXT, PREV, NSLT, PSLT, FSLT, or LSLT.</p>
</dd>
<dt><strong>Record size</strong></dt>
<dd>INPUT; BINARY(4)
<p> The size of each record within the variable buffer when multiple records
are retrieved from the list. This parameter also calculates the offset of each
record after the first one.</p>
<p> When the number of records parameter is 1, this parameter is ignored.</p>
</dd>
<dt><strong>Record count</strong></dt>
<dd>OUTPUT; BINARY(4)
<p> The number of list entries actually retrieved. When the number of records
parameter is 1, this parameter is ignored.</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>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<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">CPF6A06 E</td>
<td align="left" valign="top">Record size or record number too large.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A13 E</td>
<td align="left" valign="top">Application &amp;3 closed prematurely.</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">CPF6A90 E</td>
<td align="left" valign="top">Value not correct. Reason code &amp;3.</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: V2R2
<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 Copy Permalink