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

594 lines
16 KiB
HTML
Raw Permalink 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>Find Field Numbers in List (QGYFNDF) 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. -->
<!-- QEARMVBM SCRIPT A converted by B2H R4.1 (346) (CMS) by KENTALA -->
<!-- at RCHVMW2 on 6 Oct 1998 at 19:53:10 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- File cleanup completed on 6 July 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>Find Field Numbers in List (QGYFNDF) 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%">Request handle</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(4)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Receiver variable</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 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">4</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">5</td>
<td align="left" valign="top">Field specification</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Total number returned</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Record number</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">8</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 Find Field Numbers in List (QGYFNDF) API returns the number of the entry
in a list of information and the value of that field whenever the value of that
field changes. Two types of find operations are supported.</p>
<ul>
<li>Generic find operations: The caller specifies which field in the record is
used to cause a break.</li>
<li>Formatted find operations: The format selected determines which field or
fields cause a break.</li>
</ul>
<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>Request handle</strong></dt>
<dd>INPUT; CHAR(4)
<p>The handle of the request. When a list API is called, a handle is returned
upon successful completion. One of these handles is required as input to this
API.</p>
</dd>
<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 amount of data the application program is prepared to receive. If the
length specified is larger than the amount of data available, the receiver is
not changed beyond the amount of data available.</p>
<p>The receiver variable must be large enough to hold one array entry. For
format FNDF0100 the minimum receiver length must be:</p>
<pre>
4 + field length rounded up to a multiple of 4
</pre>
For format FNDF0200 the minimum receiver length must be:
<pre>
40
</pre>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The content and format of the information returned. The possible format
names are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>FNDF0100</em></td>
<td align="left" valign="top">Generic find operation is performed.
<p>The calling program specifies the field offset and length in the field
specification parameter.</p>
<p>Each time the field changes in the list, a record entry is added to the
receiver variable.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>FNDF0200</em></td>
<td align="left" valign="top">Spooled file find operation by printer is
performed.
<p>This format can only be used against a list of spooled files with format
OSPL0200 that contains the following fields:</p>
<ul>
<li>Device name (field key 208)</li>
<li>Output queue library (field key 207)</li>
<li>Output queue name (field key 206)</li>
</ul>
<p>Each time the device name field changes in the list, a record is added to
the receiver variable. In addition, when the printer assigned value is 2, then
each time the output queue changes in the list a record is added to the
receiver variable.</p>
</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Field specification</strong></dt>
<dd>INPUT; CHAR(*)
<p>The fields to search for a break. For the FNDF0100 format this parameter
must be an array of field offsets and field lengths. The fields specified are
considered one logical field for comparison when searching for changes in the
fields. The values for the fields will be returned in the receiver variable
concatenated in the same order they are specified in this parameter. For the
FNDF0100 format, this parameter must have the following layout:</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%">Number of fields to search on. Valid
values are 1 through 3.</td>
</tr>
<tr>
<td align="left" valign="top" rowspan="2" colspan="2">Offsets vary. These
fields repeat, in the order listed, for each field to search on.</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Field offset</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Field length</td>
</tr>
</table>
<br>
<br>
<p>For the FNDF0200 format, this parameter must have the following layout:</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%">Number of fields to search on. This
must be set to zero (0).</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Total number returned</strong></dt>
<dd>OUTPUT; BINARY(4)
<p>The total number of array entries returned in the receiver variable. This is
not necessarily the total number of entries available. If the receiver variable
is not large enough to hold all available entries, the record number parameter
is set to the record number where the next break occurs.</p>
</dd>
<dt><strong>Record number</strong></dt>
<dd>I/O; BINARY(4)
<p>On input, the record to begin searching for field breaks. This should be set
to 1 for the initial call for a list so that searching begins with the first
record. This program always assumes a field break to have occurred at the
record specified by this parameter. Thus, the record specified is always
returned in the receiver variable.</p>
<p>On output, this parameter indicates whether the information in the receiver
variable is partial or complete. If the receiver variable is complete, this
parameter will be set to zero. If the receiver variable contains partial
information, this parameter will be set to the record number where the next
field break occurs. This value can be specified as input on a subsequent call
to this program to continue the search for field breaks.</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>Format of Receiver Variable</h3>
<h4>Format FNDF0100</h4>
<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%">Record size</td>
</tr>
<tr>
<td align="left" valign="top" rowspan="3" colspan="2">Offsets vary. These
fields repeat, in the order listed, for each entry returned.</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Record number</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Field value</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Padding for boundary alignment</td>
</tr>
</table>
<br>
<br>
<h4>Format FNDF0200</h4>
<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%">Record size</td>
</tr>
<tr>
<td align="left" valign="top" rowspan="6" colspan="2">Offsets vary. These
fields repeat, in the order listed, for each entry returned.</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Record number</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Output queue name</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Output queue library</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Printer assigned value</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Device name</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Padding for boundary alignment</td>
</tr>
</table>
<br>
<br>
<h3>Field Descriptions</h3>
<p><strong>Device name.</strong> The name of the printer device where the
spooled file is printed.</p>
<p><strong>Field value.</strong> The value of the field where the break
occurs.</p>
<p>This is a concatenation of the fields specified to search on. The fields are
concatenated in the order they were specified in the field specification
parameter. The length of this field is the sum of all field lengths specified
in the field specification parameter.</p>
<p><strong>Output queue library.</strong> The name of the library containing
the output queue that the spooled file is assigned.</p>
<p><strong>Output queue name.</strong> The name of the output queue that the
spooled file is assigned.</p>
<p><strong>Padding for boundary alignment.</strong> A reserved field.</p>
<p><strong>Printer assigned value.</strong> The value specifying whether this
spooled file is assigned to a printer. Valid values are 1 through 3.</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="center" valign="bottom">Printer Value</th>
<th align="left" valign="bottom">Description</th>
</tr>
<tr>
<td align="center" valign="top">1</td>
<td align="left" valign="top">Spooled file is assigned to a specific printer.
The device name field contains the name of the printer.</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Spooled file is assigned to multiple printers.
The device name field is set to blanks.</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Spooled file is not assigned to a printer. The
device name field is set to blanks.</td>
</tr>
</table>
<p><strong>Record number.</strong> The record number in the list where the
break occurs.</p>
<p><strong>Record size.</strong> The size of the record in the array shown.</p>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top" nowrap>Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td align="left" valign="top">CPF24B4 E</td>
<td align="left" valign="top">Severe error while addressing parameter
list.</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">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">GUI0001 E</td>
<td align="left" valign="top">Invalid handle specified.</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">GUI0101 E</td>
<td align="left" valign="top">List information is not valid. Reason code
&amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">GUI0102 E</td>
<td align="left" valign="top">Offset of field, &amp;1, is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">GUI0103 E</td>
<td align="left" valign="top">Invalid handle specified. Length of field,
&amp;2, is not valid. Reason code &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">GUI0104 E</td>
<td align="left" valign="top">Record number, &amp;1, is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">GUI0106 E</td>
<td align="left" valign="top">List does not contain required fields.</td>
</tr>
<tr>
<td align="left" valign="top">GUI0107 E</td>
<td align="left" valign="top">Number of fields, &amp;2, is not valid. Reason
code &amp;1.</td>
</tr>
</table>
<br>
<hr>
API introduced: V3R6
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href="aplist.htm">APIs by
category</a></td>
</tr>
</table>
</center>
</body>
</html>