758 lines
25 KiB
HTML
758 lines
25 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>Sort Input/Output (QLGSRTIO) 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. -->
|
||
|
|
<!-- NETMG2 SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
|
||
|
|
<!-- RCHVMW2 on 29 Jan 1999 at 10:01:37 -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- YYMMDD USERID Change description -->
|
||
|
|
<!--File Edited December 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 language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<h2>Sort Input/Output (QLGSRTIO) API</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 75%;">
|
||
|
|
<br>
|
||
|
|
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 control block</td>
|
||
|
|
<td align="left" valign="top" width="20%">Input</td>
|
||
|
|
<td align="left" valign="top" width="20%">Char(16)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">2</td>
|
||
|
|
<td align="left" valign="top">Input data 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">Output data buffer</td>
|
||
|
|
<td align="left" valign="top">Output</td>
|
||
|
|
<td align="left" valign="top">Char(*)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">4</td>
|
||
|
|
<td align="left" valign="top">Length of output data buffer</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">Output data information</td>
|
||
|
|
<td align="left" valign="top">Output</td>
|
||
|
|
<td align="left" valign="top">Char(16)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">6</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>
|
||
|
|
Optional Parameter Group:<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
<table width="100%">
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">7</td>
|
||
|
|
<td align="left" valign="top" width="50%">Returned records feedback</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">8</td>
|
||
|
|
<td align="left" valign="top">Length of returned records feedback</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: No<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The Sort Input/Output (QLGSRTIO) API is used to provide a set of records at
|
||
|
|
a time to be sorted and to return a set of records at a time that have already
|
||
|
|
been sorted. This API can only be used after the QLGSORT API has been called to
|
||
|
|
initialize the sort function. This initialization defines such things as the
|
||
|
|
length of data to be sorted and the fields to be sorted. An error is returned
|
||
|
|
if QLGSRTIO is called without QLGSORT having been called for initializing.</p>
|
||
|
|
|
||
|
|
<p>After the initialization is complete, the QLGSRTIO API can be called
|
||
|
|
repeatedly to add a set of records to be sorted. When all of the records have
|
||
|
|
been provided, the QLGSRTIO API must be called with an end put request, which
|
||
|
|
causes the added records to be sorted. Once the records are sorted, the
|
||
|
|
QLGSRTIO API can be called repeatedly to return sets of sorted records until no
|
||
|
|
more records can be returned or the application has determined that it no
|
||
|
|
longer wants sorted records.</p>
|
||
|
|
|
||
|
|
<p>The QLGSRTIO API can also be used to provide sets of records at a time to
|
||
|
|
the sort and have the output from the sort go to output files. The type of
|
||
|
|
request in the request control block on the QLGSORT API can be set to specify
|
||
|
|
that the output from the sort is output files.</p>
|
||
|
|
|
||
|
|
<p>The QLGSRTIO API provides a function to cancel the sort at any time. When
|
||
|
|
the sort is canceled, all work areas initialized for the sort are deactivated,
|
||
|
|
so the QLGSORT API can be called again to perform another sort. If the QLGSRTIO
|
||
|
|
API is being used to return records from a sort a set at a time, the QLGSRTIO
|
||
|
|
API automatically ends the sort when a get request is made and all of the
|
||
|
|
sorted records have been returned. If all of the records are not retrieved, a
|
||
|
|
cancel is required to complete this sort if another call to the QLGSORT API
|
||
|
|
will be made within this job. If a cancelation is not requested, the sort is
|
||
|
|
still considered active and an error is returned on any future calls to the
|
||
|
|
QLGSORT API within this job. When the job ends, the sort automatically ends. If
|
||
|
|
the QLGSRTIO API is only being used to add records to the sort a set at a time,
|
||
|
|
with the output going to output files, the end put request causes the data to
|
||
|
|
be sorted and put to the output files, and the sort ends. No additional cancel
|
||
|
|
request is needed.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Authorities and Locks</h3>
|
||
|
|
|
||
|
|
<p>The locks needed for this API are set in the QLGSORT API and remain in
|
||
|
|
effect until a cancel request is made by the QLGSRTIO API or until an end put
|
||
|
|
request is made to return the sorted data to output files.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Required Parameter Group</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Request control block</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(16)
|
||
|
|
|
||
|
|
<p>Whether data is being put to the sort or retrieved from the sort. This
|
||
|
|
parameter also defines information about the input and output data. See <a
|
||
|
|
href="#HDRSRTIFMT">Format of Request Control Block</a> for details.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Input data buffer</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>The data to be added to the sort. This parameter is only used on a put
|
||
|
|
request. It is ignored for end put, get, and cancel requests. See the <a href=
|
||
|
|
"QLGSORT.htm#HDRBUFFER">Buffer Layout Examples</a> for information on how to
|
||
|
|
format this buffer. If the call to QLGSORT specified that input files or an
|
||
|
|
input data buffer were to be sorted and if QLGSRTIO is then called specifying a
|
||
|
|
put request and input data, an error is returned.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Output data buffer</strong></dt>
|
||
|
|
|
||
|
|
<dd>OUTPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>The sorted data being returned to the application. This parameter is only
|
||
|
|
used on a get request. It is ignored for put, end put, and cancel requests. If
|
||
|
|
the call to the QLGSORT API specified that files were to be returned and the
|
||
|
|
QLGSRTIO API is then called specifying a get request, an error is returned.
|
||
|
|
This parameter can be the same as the input data buffer parameter. The format
|
||
|
|
of the data in the buffer is the same as for the input data buffer.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Length of output data buffer</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The maximum amount of data that can be returned from the sort on a get
|
||
|
|
request. This value must be greater than 0 or an error is returned. QLGSRTIO
|
||
|
|
returns only the number of records specified in the request control block
|
||
|
|
parameter, but only up to the size of the output data buffer. The length of the
|
||
|
|
output data buffer must be at least as large as the record length value
|
||
|
|
specified in the request control block on the QLGSORT API call. That length
|
||
|
|
specified the record length to be used by the sort. If this output data length
|
||
|
|
is not large enough to hold at least one record, an error is returned. The
|
||
|
|
maximum length allowed is 16MB less 512 bytes.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Output data information</strong></dt>
|
||
|
|
|
||
|
|
<dd>OUTPUT; CHAR(16)
|
||
|
|
|
||
|
|
<p>Information to be returned to the calling program as a result of a put or
|
||
|
|
get request. See <a href="#HDRSRTOFMT">Format of Output Data Information</a>
|
||
|
|
for details on the format.</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>Optional Parameter Group</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Returned records feedback</strong></dt>
|
||
|
|
|
||
|
|
<dd>OUTPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>The number of records added to each output file to be returned to the
|
||
|
|
calling program. The returned records feedback parameter contains the number of
|
||
|
|
records added to each output file.</p>
|
||
|
|
|
||
|
|
<p>The number of records added to each output file corresponds to the list of
|
||
|
|
files specified in the request control block.</p>
|
||
|
|
|
||
|
|
<p>This parameter is used only for sorted data returned in an output file for
|
||
|
|
the following:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Request type 7 to the Sort (QLGSORT) API<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Request type 2 (End Put) to the QLGSRTIO API</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>To receive results, set the options field in the request control block for
|
||
|
|
the QLGSORT API to 4, 5, 6, or 7.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Length of returned records feedback</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The length of the returned records feedback parameter to be returned to the
|
||
|
|
calling program. If this length is larger than the actual size of the returned
|
||
|
|
records feedback parameter, the results may not be predictable. The minimum
|
||
|
|
length is 8.</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3><a name="HDRSRTIFMT">Format of Request Control Block</a></h3>
|
||
|
|
|
||
|
|
<p>For a description of the fields in this format, see <a href="#HDRSIOFLD">
|
||
|
|
Field Descriptions</a>.</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 valign="bottom" align="center">Dec</th>
|
||
|
|
<th valign="bottom" align="center">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%">Type of request</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="10%">4</td>
|
||
|
|
<td align="center" valign="TOP" width="10%">4</td>
|
||
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Reserved</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="10%">8</td>
|
||
|
|
<td align="center" valign="TOP" width="10%">8</td>
|
||
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Record length</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="10%">12</td>
|
||
|
|
<td align="center" valign="TOP" width="10%">C</td>
|
||
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Record count</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
<h3><a name="HDRSRTOFMT">Format of Output Data Information</a></h3>
|
||
|
|
|
||
|
|
<p>For a description of the fields in this format, see <a href="#HDRSIOFLD">
|
||
|
|
Field Descriptions</a>.</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 valign="bottom" align="center">Dec</th>
|
||
|
|
<th valign="bottom" align="center">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 records processed</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="10%">4</td>
|
||
|
|
<td align="center" valign="TOP" width="10%">4</td>
|
||
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Number of records available</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="10%">8</td>
|
||
|
|
<td align="center" valign="TOP" width="10%">8</td>
|
||
|
|
<td align="left" valign="top" width="20%">CHAR(8)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Reserved</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
<h3><a name="HDRFDBKFMT">Format of Returned Records Feedback
|
||
|
|
Information</a></h3>
|
||
|
|
|
||
|
|
<p>For a description of the fields in this format, see <a href="#HDRSIOFLD">
|
||
|
|
Field Descriptions</a>.</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 valign="bottom" align="center">Dec</th>
|
||
|
|
<th valign="bottom" align="center">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%">Bytes available</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="10%">4</td>
|
||
|
|
<td align="center" valign="TOP" width="10%">4</td>
|
||
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Bytes returned</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="10%">8</td>
|
||
|
|
<td align="center" valign="TOP" width="10%">8</td>
|
||
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Offset to start of returned records
|
||
|
|
array</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="10%">12</td>
|
||
|
|
<td align="center" valign="TOP" width="10%">C</td>
|
||
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Number of output files returned</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="10%">16</td>
|
||
|
|
<td align="center" valign="TOP" width="10%">10</td>
|
||
|
|
<td align="left" valign="top" width="20%">CHAR(*)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Reserved</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="10%"> </td>
|
||
|
|
<td align="center" valign="TOP" width="10%"> </td>
|
||
|
|
<td align="left" valign="top" width="20%">ARRAY of BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Returned records</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
<h3><a name="HDRSIOFLD">Field Descriptions</a></h3>
|
||
|
|
|
||
|
|
<p><strong>Bytes available.</strong> The number of bytes of data available to
|
||
|
|
be returned. All available data is returned if enough space is provided.</p>
|
||
|
|
|
||
|
|
<p><strong>Bytes returned.</strong> The number of bytes of data returned.</p>
|
||
|
|
|
||
|
|
<p><strong>Number of output files returned.</strong> The number of output files
|
||
|
|
specified in the request control block of the QLGSORT API.</p>
|
||
|
|
|
||
|
|
<p><strong>Number of records available.</strong> For a put request, the total
|
||
|
|
number of records that have been put (are available) for sorting. For the first
|
||
|
|
put request, this will equal the number of records processed. After the second
|
||
|
|
put request, it will contain the total of the first two put requests. An
|
||
|
|
application might find this helpful if it only wants to sort a maximum number
|
||
|
|
of records without counting the number from each put.</p>
|
||
|
|
|
||
|
|
<p>For a get request, this field defines the total number of records that have
|
||
|
|
not been returned to the application. An application can use this information
|
||
|
|
to determine an appropriate time to end if it does not intend to process all of
|
||
|
|
the sorted records.</p>
|
||
|
|
|
||
|
|
<p><strong>Number of records processed.</strong> For a put request, the number
|
||
|
|
of records actually put to the sort function from the input data buffer
|
||
|
|
parameter. This value is always the same as the record count specified in the
|
||
|
|
request control block.</p>
|
||
|
|
|
||
|
|
<p>For a get request, this field defines the number of records actually
|
||
|
|
returned in the output data buffer parameter. This value never exceeds the
|
||
|
|
record count specified in the QLGSRTIO request control block parameter. If more
|
||
|
|
records are requested than are available, the records processed count is set to
|
||
|
|
the actual number returned. The number of records processed multiplied by the
|
||
|
|
record length must not be greater than 16MB.</p>
|
||
|
|
|
||
|
|
<p><strong>Offset to start of returned records array.</strong> Offset to the
|
||
|
|
returned records array.</p>
|
||
|
|
|
||
|
|
<p><strong>Record count.</strong> For a put request, the number of records that
|
||
|
|
are being provided to the sort. The record count must be greater than 0 or an
|
||
|
|
error is returned. Only the number of records specified by this field are
|
||
|
|
processed even if more records are provided in the input data buffer
|
||
|
|
parameter.</p>
|
||
|
|
|
||
|
|
<p>For a get request, this field defines the maximum number of records that can
|
||
|
|
be returned to the application. The number of records processed field in the
|
||
|
|
output data information parameter indicates the actual number of records
|
||
|
|
returned.</p>
|
||
|
|
|
||
|
|
<p>Using record counts greater than 1 can improve performance.</p>
|
||
|
|
|
||
|
|
<p><strong>Record length.</strong> The size of each record given to the sort or
|
||
|
|
the size of each record returned from the sort. For a put request, each record
|
||
|
|
retrieved from the input data buffer must have the length specified by the
|
||
|
|
record length field.</p>
|
||
|
|
|
||
|
|
<p>This value includes the following:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The bytes used to store the length of any variable length fields<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Variable length record access information<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Any null byte map</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>For example, assume a logical record equals 80, and the record is variable
|
||
|
|
length with three of the five fields null capable. The record length would be
|
||
|
|
87. That is, 80 for the logical record, 2 for the length of the record, and 5
|
||
|
|
for the null byte map.</p>
|
||
|
|
|
||
|
|
<p>The offsets to the variable length record access information and the null
|
||
|
|
byte map are specified in the QLGSORT API request control block.</p>
|
||
|
|
|
||
|
|
<p>When data is provided through this API, the record length specified in the
|
||
|
|
QLGSORT API defines the length used for sorting all the records. The record
|
||
|
|
length specified here defines the record length for the current set of data to
|
||
|
|
be sorted. If the input data record length is shorter than the sort record
|
||
|
|
length, each of the records is padded with blanks. If the input data record
|
||
|
|
length is longer than the sort record length, each input record is
|
||
|
|
truncated.</p>
|
||
|
|
|
||
|
|
<p>On a get request, each record is put to the output data buffer parameter
|
||
|
|
with the specified record length. If the sort record length is longer, each
|
||
|
|
record is truncated. If the sort record length is shorter, each record is
|
||
|
|
padded with blanks. The number of records processed multiplied by the record
|
||
|
|
length cannot be greater than 16MB.</p>
|
||
|
|
|
||
|
|
<p><strong>Reserved.</strong> A reserved field. This field must be set to 0 in
|
||
|
|
the request control block. In the output information, the reserved character
|
||
|
|
field is set to blanks.</p>
|
||
|
|
|
||
|
|
<p><strong>Returned records.</strong> The number of records returned in an
|
||
|
|
output file.</p>
|
||
|
|
|
||
|
|
<p><strong>Type of request.</strong> The type of operation being requested. The
|
||
|
|
following values are defined:</p>
|
||
|
|
|
||
|
|
<table cellpadding="3">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>1 (Put)</em></td>
|
||
|
|
<td valign="top">Input data is provided to the sort function where it is stored
|
||
|
|
by the sort program in internal buffers until an end put request is made and
|
||
|
|
the data is sorted. One or more calls to the API with the put request can be
|
||
|
|
done until all of the data to be sorted has been provided to the sort program.
|
||
|
|
|
||
|
|
<p>A put request is only valid after a call to the QLGSORT API is done to
|
||
|
|
initialize a sort for input from QLGSRTIO and before an end put request is
|
||
|
|
made. If a put request is made at any other time, an error is returned.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>2 (End put)</em></td>
|
||
|
|
<td valign="top">All of the input data has been added to the sort, and the data
|
||
|
|
should now be sorted. This operation must be requested before a get request is
|
||
|
|
made, or an error is returned.
|
||
|
|
|
||
|
|
<p>An end put request causes the input to the sort to be complete. No
|
||
|
|
additional put requests can be made to the QLGSRTIO API without first doing an
|
||
|
|
initialization through the QLGSORT API; otherwise, an error is returned.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>3 (Get)</em></td>
|
||
|
|
<td valign="top">Sorted data is returned to the caller. One or more calls to
|
||
|
|
the API with the get request can be done until all of the data has been
|
||
|
|
retrieved or no further data is needed. If no further get requests are made but
|
||
|
|
data is still available to be retrieved, a cancel request must be made to end
|
||
|
|
the sort.
|
||
|
|
|
||
|
|
<p>A get request is valid for each of the following conditions:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>After an end put request was done (to cause the data to be sorted)<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>After a previous get request<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>If the sort was done on input files or on an input data buffer using sort
|
||
|
|
request type 3 or 6 of the QLGSORT API</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>If a get request is made at any other time, an error is returned.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>4 (Cancel)</em></td>
|
||
|
|
<td valign="top">The sort should be canceled immediately. All internal buffers
|
||
|
|
are cleared and deleted. This operation can be requested at any time. If
|
||
|
|
requested after a put request, no sorting is performed. If requested after a
|
||
|
|
get request, no further sort records are returned. The sort is automatically
|
||
|
|
ended when a get request is made and no data is available to be returned. If
|
||
|
|
all of the data was not retrieved, a cancel request should always be made. If
|
||
|
|
this is not done and another sort request is made using the QLGSORT API, an
|
||
|
|
error occurs because a sort is already active.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
<h3>Error Messages</h3>
|
||
|
|
|
||
|
|
<table width="100%" cellpadding="3">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top">Message ID</th>
|
||
|
|
<th align="left" valign="top">Error Message Text</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF2207 E</td>
|
||
|
|
<td valign="top">Not authorized to use object &1 in library &3 type
|
||
|
|
*&2.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF24B4 E</td>
|
||
|
|
<td valign="top">Severe error while addressing parameter list.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3BD0 E</td>
|
||
|
|
<td valign="top">QLGSRTIO request control block field &1 is not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3BD1 E</td>
|
||
|
|
<td valign="top">Output data length parameter is not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3BD2 E</td>
|
||
|
|
<td valign="top">Type of request &1 is not valid at this time.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3BD7 E</td>
|
||
|
|
<td valign="top">Key size exceeds maximum.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3BDA E</td>
|
||
|
|
<td valign="top">No output files could be opened.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3BDB E</td>
|
||
|
|
<td valign="top">Sort internal storage limit exceeded.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3BDC E</td>
|
||
|
|
<td valign="top">Duplicate keys encountered for file &1 in library
|
||
|
|
&2.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3BF0 E</td>
|
||
|
|
<td valign="top">Sort sequence table specified or supplied is not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3C36 E</td>
|
||
|
|
<td valign="top">Number of parameters, &1, entered for this API was not
|
||
|
|
valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3BE2 E</td>
|
||
|
|
<td valign="top">Returned record feedback length not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3BE4 E</td>
|
||
|
|
<td valign="top">Buffer information is not valid. Reason &1.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3BE7 E</td>
|
||
|
|
<td valign="top">File &1 in library &2 or file entry &4 has error
|
||
|
|
&3.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3C90 E</td>
|
||
|
|
<td valign="top">Literal value cannot be changed.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3CF1 E</td>
|
||
|
|
<td valign="top">Error code parameter not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF5715 E</td>
|
||
|
|
<td valign="top">File &1 in library &2 not found.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9801 E</td>
|
||
|
|
<td valign="top">Object &2 in library &3 not found.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9802 E</td>
|
||
|
|
<td valign="top">Not authorized to object &2 in &3.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9803 E</td>
|
||
|
|
<td valign="top">Cannot allocate object &2 in library &3.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9810 E</td>
|
||
|
|
<td valign="top">Library &1 not found.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9812 E</td>
|
||
|
|
<td valign="top">File &1 in library &2 not found.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9820 E</td>
|
||
|
|
<td valign="top">Not authorized to use library &1.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9822 E</td>
|
||
|
|
<td valign="top">Not authorized to file &1 in library &2.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9830 E</td>
|
||
|
|
<td valign="top">Cannot assign library &1.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9845 E</td>
|
||
|
|
<td valign="top">Error occurred while opening file &1.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9846 E</td>
|
||
|
|
<td valign="top">Error while processing file &1 in library &2.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9872 E</td>
|
||
|
|
<td valign="top">Program or service program &1 in library &2 ended.
|
||
|
|
Reason code &3.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
API introduced: V2R3
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
||
|
|
"nls1.htm">National Language Support APIs</a> | <a href="aplist.htm">APIs by
|
||
|
|
category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|