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

510 lines
16 KiB
HTML
Raw Normal View History

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>Add List Multiple Entries (QUIADDLM) 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>Add List Multiple Entries (QUIADDLM) 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">Input</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">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">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">8</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">9</td>
<td align="left" valign="top">Record numbers</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">10</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">11</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">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 Add List Multiple Entries (QUIADDLM) API adds one or more new entries to
a list. The new entries are inserted immediately before or immediately after
the entry identified by the current entry for the list. They can also be
inserted at the beginning or end of the list. On return to the application
program, the current entry points to the most recently inserted entry.</p>
<p>The contents of all dialog variables corresponding to columns in the list
are saved in each added entry. When the operation completes successfully, the
corresponding dialog variables contain the values from the last list entry
successfully added.</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) API or the Open Print
Application (QUIOPNPA) API when the application is opened.</p>
</dd>
<dt><strong>Variable buffer</strong></dt>
<dd>INPUT; CHAR(*)
<p> The program buffer from 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 an open application, dialog variables are
copied from the variable buffer to the application variable pool before the
list entry is added. This parameter operation is the same as using the Put
Dialog Variable (QUIPUTV) API immediately before the Add List Multiple Entry
(QUIADDLM) API.</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 has a value greater than one and the
record numbers parameter has a value of zero, the size of the variable buffer
must be at least equal to the value on the number of records parameter
multiplied by the value on the record size parameter.</p>
<p> When the number of records parameter has a value greater than one and the
record numbers parameter has a nonzero value, the size of the variable buffer
must be at least equal to the largest value in the array of record numbers
multiplied by the value of 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 determining which dialog variables are
copied from the variable buffer to the application variable pool. The variable
record must be defined in the panel group for the open application.</p>
<p> 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 QUIPUTV API is not used during the QUIADDLM
API. The variable buffer, variable buffer length, number of records, record
size, and record numbers parameters are ignored.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>List name</strong></dt>
<dd>INPUT; CHAR(10)
<p> The name of the list to which entries are added. If the list is not
currently active in the open application, it is activated by this API.</p>
</dd>
<dt><strong>Option</strong></dt>
<dd>INPUT; CHAR(4)
<p> The location of the new entry in the list. When an entry is added to the
list, the current entry is always changed to point to the new list entry.</p>
<p> One of the following values must be specified to indicate the new entry's
location:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>FRST</em></td>
<td align="left" valign="top">Added as the first entry in the list</td>
</tr>
<tr>
<td align="left" valign="top"><em>LAST</em></td>
<td align="left" valign="top">Added as the last entry in the list</td>
</tr>
<tr>
<td align="left" valign="top"><em>NEXT</em></td>
<td align="left" valign="top">Added after the current entry</td>
</tr>
<tr>
<td align="left" valign="top"><em>PREV</em></td>
<td align="left" valign="top">Added before the current entry</td>
</tr>
</table>
<br>
</dd>
<dt><strong>List entry handle</strong></dt>
<dd>OUTPUT; CHAR(4)
<p> The list entry handle returned to the application program from the current
entry. This value is the handle of the entry just inserted into the list. If
more than one list entry is added, this parameter contains the list entry
handle of the last entry successfully added.</p>
</dd>
<dt><strong>Number of records</strong></dt>
<dd>INPUT; BINARY(4)
<p> The total number of entries the application program wants to add to the
list. If the variable record name parameter specifies the name of a variable
record defined in the panel group for this open application, this parameter can
be used with the record size, record count, and record numbers parameters to
add multiple entries to the list. When the variable record name parameter has
the value *NONE, the number of records parameter is ignored.</p>
<p> 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 added to the list. The record
size, record count, and record numbers parameters are ignored.</td>
</tr>
</table>
<p> When the number of records parameter is greater than 1, the variable buffer
parameter must contain all the entries to be added to the list. The record size
parameter defines the size of each record within the variable buffer, and is
used to calculate the offset of each record from the first record. The variable
record, identified by the variable record name parameter, defines the format of
each record.</p>
</dd>
<dt><strong>Record numbers</strong></dt>
<dd>INPUT; CHAR (*)
<p> An array of record numbers. Each entry in the array is a BINARY(4) value
from 1 to 32767. The array specifies the order in which entries are added to
the list. The first record number defines the first entry added to the list,
the second record number defines the second entry, and so forth. Each record
number specifies a record from the variable buffer containing the values for an
entry to be added to the list. The dimension of the array must be at least as
large as the value for the number of records parameter.</p>
<p> The following special value can be used in the first array element:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Records from the variable buffer are used in
sequential order. The array of record numbers needs to have only one
element.</td>
</tr>
</table>
<p> When the record numbers parameter is 0, 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 on the record size parameter. When the record
numbers parameter has a nonzero value, the size of the variable buffer must be
at least equal to the largest value specified in the record numbers array
multiplied by the record size value.</p>
<p> The record numbers parameter allows applications to add more than one list
entry from data structures already available to the application program. This
is useful when the existing order of records in the data structures is not
desired for the list entries, or when certain records should not be added to
the list.</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 added to the list. The record size is also used to calculate the offset of
each record after the first record.</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 added. Validation is done on packed or
zoned data values in each record. If an error is found, the Add List Multiple
Entries (QUIADDLM) API ends at that point with an exception; unusable data
causes a partial update of the list. This parameter returns the number of list
entries successfully added to the application program, even if an error
occurs.</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>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">CPF6AA1 E</td>
<td align="left" valign="top">The value of the action field is not correct at
this time. Reason code &amp;5.</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">CPF6A2B E</td>
<td align="left" valign="top">Value for Option 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">CPF6A30 E</td>
<td align="left" valign="top">Value for Record Numbers parameter not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A36 E</td>
<td align="left" valign="top">Data not correct for dialog variable &amp;4 in
panel group &amp;1 in &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A37 E</td>
<td align="left" valign="top">Data not correct for dialog variable &amp;4 in
panel group &amp;1 in &amp;2.</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">CPF6A9D E</td>
<td align="left" valign="top">Size limit reached for list &amp;4.</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">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">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>