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

2232 lines
72 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>Sort (QLGSORT) 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 (QLGSORT) API</h2>
<div class="box" style="width: 70%;">
<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 control block</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(*)</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">Length of returned data</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Binary(4)</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>
&nbsp;&nbsp;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>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Sort (QLGSORT) API provides a generalized sort function that can be
directly called by any application program. This API can be used to sort data
in files or data in an input buffer with a single call. This API can also be
used to initialize a sort function where a series of calls using the Sort
Input/Output (QLGSRTIO) API is done to repeatedly add data to be sorted as a
set of records and return sorted data as a set of records.</p>
<p>The following types of sort operations can be done with the API:</p>
<ul>
<li>Sort up to 32 input files and produce 1 to 32 output files, each containing
the full list of sorted records.<br>
<br>
</li>
<li>Sort up to 32 input files and return all of the records in the output data
buffer parameter.<br>
<br>
</li>
<li>Sort up to 32 input files, and return the output a set at a time through
the QLGSRTIO API.<br>
<br>
</li>
<li>Sort a set of records in the input data buffer parameter and produce 1 to
32 output files, each containing the full list of sorted records.<br>
<br>
</li>
<li>Sort a set of records in the input data buffer parameter and return all of
the records in the output data buffer parameter.<br>
<br>
</li>
<li>Sort a set of records in the input data buffer parameter and return the
output a set at a time through the QLGSRTIO API.<br>
<br>
</li>
<li>Initialize a sort where the records are provided a set at a time through
the QLGSRTIO API and produce 1 to 32 output files, each containing the full
list of sorted records.<br>
<br>
</li>
<li>Initialize a sort where the records are provided a set at a time through
the QLGSRTIO API and are also returned a set at a time through that API.</li>
</ul>
<p>The sort allows the application to indicate whether character data should be
sorted as a binary (hexadecimal) sort or sorted using a national language sort
sequence for obtaining sort results consistent with a specific locale. When
specifying a character field as binary (hexadecimal), the national language
sort sequence is not used. The hexadecimal sort is helpful if DBCS-graphic data
is being sorted. This sort can also be used to define character fields that
contain hexadecimal or bit data. The caller can indicate if character data
being sorted might contain double-byte characters. This type of field is
considered a DBCS-open field, where DBCS data is surrounded by control
characters. If a field is defined as such, the API will apply a national
language sort sequence only to the single-byte data in the field. Performance
may be slower when this type of character field is defined because of
additional checking that occurs for DBCS data. If a field is defined as a
single-byte field but DBCS data exists in the field, the national language sort
sequence is applied to the DBCS data as if it were single-byte data, which may
result in an unexpected sequence.</p>
<p>The sort allows a character field to contain 2-byte characters in UCS-2. If
a field is defined as such, the API will apply a UCS-2 national language sort
sequence if specified in the national language sort information.</p>
<p>The sort allows a character field to be variable length. All occurrences of
the variable length character field have the same maximum length. The actual
data length is defined by a 2-byte binary value that immediately precedes the
character field. When using a variable length field, all bytes between the
actual data length and the maximum data length are sorted as if they were
blanks. Variable length fields are allowed only when sorting buffers of data or
when using files for both input and output.</p>
<p>The sort allows a record to be defined for variable length record access.
When using variable length record access, a 2-byte binary value indicates the
actual data length of the record. When sorting records of different length, the
shorter record is logically padded to the length of the longer record with
blanks. This occurs only if the sort specification refers to a key size greater
than the actual record length of the shorter record. This support is mutually
exclusive of variable-length-field sort support. It is allowed only when
sorting buffers of data and when using externally described database files.
When using database files for both input and output, the file must be defined
as having all fixed length fields except for the last field. The last field
must be variable length.</p>
<p>The sort also allows fields to be defined as null capable. Fields that are
set to null sort higher than any non-null value. Null support is allowed only
when sorting buffers of data and when using externally described database files
for both input and output.</p>
<p>The QLGSORT API requires that no earlier sort be active for this job at the
time the sort is called. This is especially important when the QLGSORT API is
called to initialize a sort and the QLGSRTIO API is repeatedly called to add
data to the sort or return data from the sort. When retrieving data from the
sort using the QLGSRTIO API, the normal operation is to continue calling
QLGSRTIO until all of the data is returned. Whenever a get request is made and
there is no more data to be returned, the sort is ended. If a get request is
made and data still remains to be returned, the sort is still active until
another get request is made and all of the data is returned. Another way to end
the sort is to specify Cancel (request type 4) on the QLGSRTIO API call. The
cancel request causes the sort to end immediately, regardless of whether there
is still data to be returned. Whenever a sort is active and QLGSORT is called
again by the same job, an error is returned.</p>
<p>When using the QLGSRTIO API to put data to the sort and the output is to be
put in output files, the end put operation on the call to the QLGSRTIO API
causes the data to be sorted and the output to be generated. The sort is then
ended without the need to call QLGSRTIO with a cancel request.</p>
<p>When QLGSORT is called once to perform sorting of data in an input data
buffer or in files, with the output going to an output data buffer or files,
the sort is ended within that one call. All internal spaces have been deleted.
Subsequent calls to the QLGSORT API are therefore valid.</p>
<p>If input files are specified and an error occurs with any of them, an error
message is returned and no sorting occurs. It is up to the caller to determine
if the QLGSORT API must be called again to perform the sort operation. There is
no capability to continue with the previous sort.</p>
<p>If output files are specified, the file member of a physical output file is
cleared before the sorted data is put to the file. If output files are
specified and an open or put error occurs with any of the files, the sort
continues to put data to the files that are not in error. For some I/O errors,
an inquiry message is sent to the system operator message queue (QSYSOPR).
Processing stops until a reply is received for the message. If all of the
output files are in error, a message is returned indicating that the data was
sorted but there were no valid output files in which to put the data.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Input File Authority</em></dt>
<dd>*USE<br>
<br>
</dd>
<dt><em>Input File Library Authority</em></dt>
<dd>*USE<br>
<br>
</dd>
<dt><em>Output File Authority</em></dt>
<dd>Both *OBJOPR and *ADD or both *OBJALT and *ADD<br>
<br>
</dd>
<dt><em>Output File Library Authority</em></dt>
<dd>*USE<br>
<br>
</dd>
<dt><em>Sort Sequence Table Authority</em></dt>
<dd>*USE<br>
<br>
</dd>
<dt><em>Sort Sequence Table Library Authority</em></dt>
<dd>*USE<br>
<br>
</dd>
<dt><em>Input File Lock</em></dt>
<dd>*SHRNUP<br>
<br>
</dd>
<dt><em>Output File Lock</em></dt>
<dd>*EXCL<br>
<br>
</dd>
<dt><em>Sort Sequence Table Lock</em></dt>
<dd>*SHRNUP</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Request control block</strong></dt>
<dd>INPUT; CHAR(*)
<p>Information defining the sort, such as whether a list of files or an input
data buffer will be sorted. It also defines the keys to be used for the sort.
Refer to <a href="#HDRSORTFMT">Format of Request Control Block</a> for
details.</p>
</dd>
<dt><strong>Input data buffer</strong></dt>
<dd>INPUT; CHAR(*)
<p>The input data to be sorted. The calling program is responsible for adding
all of the data to be sorted to this parameter before calling the QLGSORT API.
The input data buffer parameter must contain the data to be sorted when the
type of request field is 4, 5, or 6. For information on how to format this
buffer, see <a href="#HDRBUFFER">Buffer Layout Examples</a>.</p>
<p>This parameter is ignored when the type of request field is 1, 2, 3, 7, or 8
because either the file data will be sorted or the data will be provided
through calls to the QLGSRTIO API.</p>
</dd>
<dt><strong>Output data buffer</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The sorted output data to be returned to the calling program. The output
data buffer parameter will contain the sorted output data when the type of
request field in the request control block is 2 or 5.</p>
<p>This parameter is ignored when the type of request field is 1, 3, 4, 6, 7,
or 8 because data is either provided in output files or through calls to the
QLGSRTIO API. For information on how this buffer is formatted, see <a href=
"#HDRBUFFER">Buffer Layout Examples</a>.</p>
<p>The QLGSORT API returns only the data that the buffer can hold, up to the
length of data that is available to be returned. The size of the output data
buffer must be greater than or equal to the record length field of the request
control block. This is to ensure that at least one record can be provided as
output. The output data buffer parameter can be the same as the input data
buffer parameter.</p>
</dd>
<dt><strong>Length of output data buffer</strong></dt>
<dd>INPUT; BINARY(4)
<p>The maximum length of the output data to be returned to the calling program
in the output data buffer parameter. If this length is larger than the actual
size of the output data buffer parameter, the results may not be predictable.
The length of output data buffer must be at least as large as the record length
value specified in the request control block when the type of request field in
the request control block is 2 or 5. If it is not, an error is returned.</p>
<p>The length of output data must be set to 0 when the type of request field is
1, 3, 4, 6, 7, or 8 because the data is returned either as output files or
through calls to the QLGSRTIO API. The maximum length allowed is 16MB less 512
bytes.</p>
</dd>
<dt><strong>Length of returned data</strong></dt>
<dd>OUTPUT; BINARY(4)
<p>The actual length of the output data added to the output data buffer
parameter. When no output data is returned, this parameter is set to 0.</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>This parameter is ignored when the type of request field is 2, 3, 5, 6, 7,
or 8. This is because data is returned in buffers or through calls to the
QLGSRTIO API.</p>
<p>The number of records added to each output file corresponds to the list of
files specified in the request control block. To receive results, you must also
set the options field in the request control block to 4, 5, 6, or 7.</p>
<p>See <a href="#HDRRRFDBK">Format of Returned Records Feedback Information</a>
for details.</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. See the <a href="#HDRRRFDBK">Format of Returned Records Feedback
Information</a> for details.</p>
<p>This parameter is ignored when the type of request field is 2, 3, 5, 6, 7,
or 8. This is because data is returned in buffers or through calls to the
QLGSRTIO API.</p>
</dd>
</dl>
<br>
<h3><a name="HDRSORTFMT">Format of Request Control Block</a></h3>
<p>For a description of the fields in this format, see <a href="#HDRSORTFLD">
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%">Length of request control block</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%">Type of request</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%">Reserved</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%">Options</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%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Record length</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">20</td>
<td align="center" valign="TOP" width="10%">14</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Record count</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">24</td>
<td align="center" valign="TOP" width="10%">18</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Offset to key list</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">28</td>
<td align="center" valign="TOP" width="10%">1C</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Number of keys</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">32</td>
<td align="center" valign="TOP" width="10%">20</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Offset to national language sort
information</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">36</td>
<td align="center" valign="TOP" width="10%">24</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Offset to input file list</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">40</td>
<td align="center" valign="TOP" width="10%">28</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Number of input files</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">44</td>
<td align="center" valign="TOP" width="10%">2C</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Offset to output file list</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">48</td>
<td align="center" valign="TOP" width="10%">30</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Number of output files</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">52</td>
<td align="center" valign="TOP" width="10%">34</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Length of key entry</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">56</td>
<td align="center" valign="TOP" width="10%">38</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Length of national language sort
sequence information</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">60</td>
<td align="center" valign="TOP" width="10%">4C</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Length of input file entry</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">64</td>
<td align="center" valign="TOP" width="10%">50</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Length of output file entry</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">68</td>
<td align="center" valign="TOP" width="10%">54</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Offset to null byte map</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">72</td>
<td align="center" valign="TOP" width="10%">58</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Offset to variable length record
access information</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">76</td>
<td align="center" valign="TOP" width="10%">6C</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Reserved</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>Note:</strong> Format of
entries in the key list. The following fields are repeated for each key entry.
The decimal and hexadecimal offsets depend on the number of key entries. The
first key entry is found by using the offset to key list field. At least one
key must be specified. Sorting will be done on the keys in the order they are
specified.</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Key starting position</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Key string size</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Key data type</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Sort order</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Ordinal position of key field</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>Note:</strong> Format of
national language sort information. The following fields are not repeated. The
decimal and hexadecimal offsets depend on the number of key entries. The first
field is found by using the offset to national language sort information field.
If you want a hexadecimal sort instead of a national language sort, set the
offset to national language sort information field to 0. In this case, you do
not need to specify the sort sequence fields.</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">CHAR(20)</td>
<td align="left" valign="top" width="60%">Qualified sort table name</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Sort sequence CCSID</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">CHAR(10)</td>
<td align="left" valign="top" width="60%">Sort sequence language ID</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">CHAR(256)</td>
<td align="left" valign="top" width="60%">Sort sequence table</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>Note:</strong> Format of
entries in the input file list. The following fields are repeated for each
input file entry. The decimal and hexadecimal offsets depend on the number of
input file entries and the number of key entries. The first input file entry is
found by using the offset to input file list field. If the input data buffer
parameter contains data to be sorted, or data will be provided through the
QLGSRTIO API, the offset to input file list field must be set to 0.</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">CHAR(20)</td>
<td align="left" valign="top" width="60%">Qualified input file name</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">CHAR(10)</td>
<td align="left" valign="top" width="60%">Input member name</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Variable length record access</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Null-capable fields</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>Note:</strong> Format of
entries in the output file list. The following fields are repeated for each
output file entry. The decimal and hexadecimal offsets depend on the number of
input file list entries and key list entries. The first output file entry is
found by using the offset to output file list field. If the sorted records are
to be returned in the output data buffer, or data will be returned through
calls to the QLGSRTIO API, the offset to output file list field must be set to
0.</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">CHAR(20)</td>
<td align="left" valign="top" width="60%">Qualified output file name</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">CHAR(10)</td>
<td align="left" valign="top" width="60%">Output member name</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Variable length record access</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Null-capable fields</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRRRFDBK">Format of Returned Records Feedback
Information</a></h3>
<p>For a description of the fields in this format, see <a href="#HDRSORTFLD">
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</td>
</tr>
<tr>
<td align="center" valign="TOP" width="10%">&nbsp;</td>
<td align="center" valign="TOP" width="10%">&nbsp;</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="HDRSORTFLD">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>Input member name.</strong> The name of the member in the input
file. A value of *FIRST indicates that the first member of the file will be
used. A value of *LAST indicates that the last member of the file will be used.
If the specified member does not exist, an error is returned and no sorting is
done.</p>
<p><strong>Key data type.</strong> The following are the values that may be
specified:</p>
<table cellpadding="3">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td valign="top">Signed binary.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td valign="top">Signed binary floating point.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td valign="top">Signed zoned decimal.</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td valign="top">Signed packed decimal.</td>
</tr>
<tr>
<td align="left" valign="top"><em>4</em></td>
<td valign="top">Character with national language sort sequence applied, if
specified. DBCS data will be treated as single-byte data.</td>
</tr>
<tr>
<td align="left" valign="top"><em>5</em></td>
<td valign="top">Mixed character with national language sort sequence applied,
if specified, only to single-byte data.</td>
</tr>
<tr>
<td align="left" valign="top"><em>6</em></td>
<td valign="top">Character with no national language sort sequence applied, if
specified.</td>
</tr>
<tr>
<td align="left" valign="top"><em>7</em></td>
<td valign="top">Unsigned packed decimal. All numbers will have the sign forced
positive ('F'X).</td>
</tr>
<tr>
<td align="left" valign="top"><em>8</em></td>
<td valign="top">Unsigned zoned decimal. All numbers will have the sign forced
positive ('F'X).</td>
</tr>
<tr>
<td align="left" valign="top"><em>9</em></td>
<td valign="top">Unsigned binary.</td>
</tr>
<tr>
<td align="left" valign="top"><em>10</em></td>
<td valign="top">Zoned decimal with a sign over the leading digit. The sign
occupies the left-most 4-bits of the value.</td>
</tr>
<tr>
<td align="left" valign="top"><em>11</em></td>
<td valign="top">Zoned decimal with a separate trailing sign. Valid values are
+, -, and blank.</td>
</tr>
<tr>
<td align="left" valign="top"><em>12</em></td>
<td valign="top">Zoned decimal with a separate leading sign. Valid values are
+, -, and blank.</td>
</tr>
<tr>
<td align="left" valign="top"><em>13</em></td>
<td valign="top">Date in the form of MM/DD/YY, where:
<table cellpadding="3">
<tr>
<td align="left" valign="top"><em>YY</em></td>
<td valign="top">Year</td>
</tr>
<tr>
<td align="left" valign="top"><em>MM</em></td>
<td valign="top">Month</td>
</tr>
<tr>
<td align="left" valign="top"><em>DD</em></td>
<td valign="top">Day</td>
</tr>
</table>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>14</em></td>
<td valign="top">Date in the form of DD/MM/YY</td>
</tr>
<tr>
<td align="left" valign="top"><em>15</em></td>
<td valign="top">Date in the form of DD.MM.YYYY</td>
</tr>
<tr>
<td align="left" valign="top"><em>16</em></td>
<td valign="top">Date in the form of MM/DD/YYYY</td>
</tr>
<tr>
<td align="left" valign="top"><em>17</em></td>
<td valign="top">All other date/time formats</td>
</tr>
<tr>
<td align="left" valign="top"><em>18</em></td>
<td valign="top">Time in the form of HH:MM xM, where:
<table cellpadding="3">
<tr>
<td align="left" valign="top"><em>HH</em></td>
<td valign="top">Hour</td>
</tr>
<tr>
<td align="left" valign="top"><em>MM</em></td>
<td valign="top">Minute</td>
</tr>
<tr>
<td align="left" valign="top"><em>x</em></td>
<td valign="top">A or P</td>
</tr>
</table>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>19</em></td>
<td valign="top">Variable length character with national language sort sequence
applied, if specified. DBCS data will be treated as single-byte data.</td>
</tr>
<tr>
<td align="left" valign="top"><em>20</em></td>
<td valign="top">Variable length mixed character with national language sort
sequence applied, if specified, only to single-byte data.</td>
</tr>
<tr>
<td align="left" valign="top"><em>21</em></td>
<td valign="top">Variable length character with no national language sort
sequence applied, if specified.</td>
</tr>
<tr>
<td align="left" valign="top"><em>22</em></td>
<td valign="top">Variable length UCS-2 character with national language sort
sequence applied, if specified.</td>
</tr>
<tr>
<td align="left" valign="top"><em>23</em></td>
<td valign="top">UCS-2 character with national language sort sequence applied,
if specified.</td>
</tr>
</table>
<p>The use of any other value will cause an error to be returned.</p>
<p><strong>Key starting position.</strong> The starting position of the key
field in the record. The starting position must be greater than 0 and cannot
exceed the record length specified in the record length field, or an error is
returned.</p>
<p>The same key starting position is used for all records to be sorted. Padding
of blanks occurs on records that are shorter than the record length field. If a
key starting position is within the area that is padded, these records are
normally sorted into the first positions.</p>
<p>For key data types 19, 20, 21, and 22, the starting position should be byte
0 of the 2-byte length that precedes the character data.</p>
<p><strong>Key string size.</strong> The number of bytes to be used for sorting
this field. If the key field data type is 19, 20, 21, or 22, this must be the
maximum length of the field in single bytes not including the 2-byte binary
length in front of the data. The key string size must be greater than 0, and
the string size plus the key starting position cannot exceed the record length
field; otherwise, an error is returned. Also, the sum of the size of all of the
keys cannot exceed 2000 bytes. If the sum exceeds this maximum, an error is
returned.</p>
<p><strong>Note:</strong> Data that is encoded in UCS-2 requires 2 bytes for
each character.</p>
<p><strong>Length of input file entry.</strong> The total length of the input
file entry. If specified, the minimum length must be 30 bytes. If the input
file includes any of the following, the length of the entry must be 38
bytes:</p>
<ul>
<li>Variable length record access<br>
<br>
</li>
<li>Null-capable fields</li>
</ul>
<p><strong>Length of key entry.</strong> The total length of the key entry. If
a null key is allowed, the key length must be 20 bytes. If specified, the
minimum length must be 16 bytes.</p>
<p><strong>Length of national language sort sequence information.</strong> The
total length of the national language sort sequence information. If specified,
the minimum length must be 290 bytes.</p>
<p><strong>Length of output file entry.</strong> The total length of the output
file entry. If specified, the minimum length must be 30 bytes. If the output
file includes either of the following, the length of the entry must be 38
bytes:</p>
<ul>
<li>Variable length record access<br>
<br>
</li>
<li>Null-capable fields</li>
</ul>
<p><strong>Length of request control block.</strong> The total length of the
request control block. The minimum size is 72 bytes, which allows for one key
in the key list, no input or output files, and no national language sort
sequence information. An error is returned if the length specified is less than
the minimum.</p>
<p><strong>Null-capable fields.</strong> Whether null-capable fields are
supported in a file. The possible values follow:</p>
<table cellpadding="3">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td valign="top">The file does not contain null-capable fields.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td valign="top">The file contains null-capable fields. This value is allowed
only when sorting externally described database files.</td>
</tr>
</table>
<p><strong>Number of input files.</strong> The number of input files specified
in the input file list. If the number of input files is 0 and the request type
field is 1,2, or 3 (file sort), an error is returned. Up to 32 input files can
be specified.</p>
<p><strong>Number of keys.</strong> The number of keys specified in the request
control block. The sum of the lengths of all of the key fields cannot exceed
2000 bytes. Therefore the number of keys is limited to a maximum of 2000,which
allows each key to be 1 byte long. At least one key field must be defined.</p>
<p><strong>Number of output files.</strong> The number of output files
specified in the output file list. If the number of output files is 0 and the
request type field is 1, 4, or 7 (file output), an error is returned. Up to 32
output files can be specified.</p>
<p><strong>Offset to input file list.</strong> The offset to the start of the
input file list structure. If data in the input data buffer parameter is being
sorted, or input data will be provided by the QLGSRTIO API, the input file list
structure is not required and this offset must be set to 0.</p>
<p><strong>Offset to key list.</strong> The offset to the start of the key list
structure. At least one key must be defined in the key list structure, or an
error is returned.</p>
<p><strong>Offset to national language sort information.</strong> The offset to
the start of the national language sort information structure. If you want a
hexadecimal sort instead of a national language sort, set this offset to 0. In
this case, you do not need to specify the sort sequence fields.</p>
<p><strong>Offset to null byte map.</strong> The offset to the start of the
null byte map. The null byte map contains a 1-byte value for each field in the
record. The order of the bytes corresponds to the order of the fields. If the
field contains null data, the value should be set to 1; otherwise, the value
should be 0.</p>
<p>This offset must be set if there are null-capable fields in the input
buffer. If there are no null-capable fields in the input buffer, the value must
be set to 0. Also, the value must be set to 0 if the type of request is 1, 2,
3, 4, or 7. See the <a href="#HDRBUFFER">Buffer Layout Examples</a> for
information on how to format this buffer.</p>
<p><strong>Offset to output file list.</strong> The offset to the start of the
output file list structure. If data is being returned in the output data buffer
parameter or if the QLGSRTIO API will be used to return the sorted data, the
output file list structure is not required and this offset must be set to
0.</p>
<p><strong>Offset to start of returned records array.</strong> The offset to
the returned records array.</p>
<p><strong>Offset to variable length record access information.</strong> The
offset to the start of the variable length record access information. This
offset must be set if variable length record access is being used for buffer
processing.</p>
<p>The offset should be set to the maximum length of the actual user-defined
data for a record in a buffer or file plus 1 byte. For example, if the largest
user data in the buffer is 80 bytes, this field would be 81. At offset 81
within each record to be sorted, a 2-byte binary value is set to indicate the
actual length of the user data.</p>
<p>When used in conjunction with null-capable fields, this offset value must be
less than the value specified for the offset to null byte map field. This
offset must be 0 unless the type of request is 5, 6, or 8 and the buffer
contains variable length records.</p>
<p><strong>Options.</strong> Additional options to be handled by the sort. The
following values are defined:</p>
<table cellpadding="3">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td valign="top">No options used.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td valign="top">Log record count messages. One message is returned in the job
log for each output file indicating the number of records written to the output
file. When output files are not used, one message is returned indicating the
total number of records sorted.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td valign="top">Throw away duplicate keyed records when writing to files
requiring unique keys. The normal processing is to maintain duplicates in the
order in which they are received. This option allows for succeeding data to be
written to the file or buffer by bypassing records with duplicate keys. If this
option is not selected and a duplicate key is encountered when writing data to
a database file defined to have unique keys, a message is returned. No further
data is entered into the file.</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td valign="top">Log record count messages and throw away duplicate keyed
records. This option is a combination of options 1 and 2.</td>
</tr>
<tr>
<td align="left" valign="top"><em>4</em></td>
<td valign="top">Store record count for each file in the returned records
feedback. When output files are not used, a message is returned to the job log
indicating the total number of records sorted.</td>
</tr>
<tr>
<td align="left" valign="top"><em>5</em></td>
<td valign="top">Store record count for each file in the returned records
feedback and log record count messages. When output files are not used, a
message is returned to the job log indicating the total number of records
sorted. This option is a combination of options 1 and 4.</td>
</tr>
<tr>
<td align="left" valign="top"><em>6</em></td>
<td valign="top">Store record count for each file in the returned records
feedback and throw away duplicate keyed records. This option is a combination
of options 2 and 4.</td>
</tr>
<tr>
<td align="left" valign="top"><em>7</em></td>
<td valign="top">Store record count for each file in the returned records
feedback, log record count messages, and throw away duplicate keyed records.
This option is a combination of options 1, 2, and 4.</td>
</tr>
</table>
<p><strong>Ordinal position of key field.</strong> The ordinal position of the
key field relative to all fields within the record. This value must be set if
sorting on a null-capable field.</p>
<p><strong>Output member name.</strong> The name of the member in the output
file. A value of *FIRST indicates that the first member of the file should be
used. A value of *LAST indicates that the last member of the file should be
used.</p>
<p><strong>Qualified input file name.</strong> The name of a file whose data is
to be sorted, and the library in which it is located. The first 10 characters
contain the file name, and the second 10 characters contain the library
name.</p>
<p>The library name can have the following special values:</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td valign="top">The current library list.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td valign="top">The job's current library.</td>
</tr>
</table>
<p>All values must be padded with blanks to the right of the value.</p>
<p>If a file is specified that does not exist or is unavailable (for example,
locked), an error is returned for that file and no further files are read. No
sorted data is returned for any of the files already read without errors.</p>
<p>The QLGSORT API supports database (both logical and physical), diskette, and
tape files. Any other file type is not recognized and an error is returned.
Variable length record access and null-capable fields are supported for
externally described database files only.</p>
<p>The data in each of the files is sorted as the common record length
specified in the record length field. However, if the file contains variable
length fields or uses variable length record access, the data is sorted using
the actual length of the data. The data is truncated or padded with blanks as
necessary when the record length of the input file is different than the record
length value.</p>
<p>The total length of all the records in all the input files cannot exceed
16MB for the data to be returned in the output data buffer parameter. If your
files have more data than this, you should consider having the output data sent
to output files, or use the QLGSRTIO API to repeatedly retrieve sets of sorted
data.</p>
<p><strong>Qualified output file name.</strong> The name of a file that is to
receive sorted data, and the library in which it is located. The first 10
characters contain the file name, and the second 10 characters contain the
library name.</p>
<p>The library name can have the following special values:</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td valign="top">The current library list.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td valign="top">The job's current library.</td>
</tr>
</table>
<p>All values must be padded with blanks to the right of the value.</p>
<p>If a file is specified that does not exist or is unavailable (for example,
locked), a diagnostic error is returned indicating the error and the file in
error. If an error occurs when the file is opened or put, a message is returned
indicating the error and the file in error. For some I/O errors, an inquiry
message is sent to the system operator message queue (QSYSOPR). Processing
stops until a reply is received for the message. The QLGSORT API continues to
put data to the other files that do not have errors. If none of the output
files could be opened, an error message is returned indicating that the sort
was successful but there were no files in which the sorted data could be
returned.</p>
<p>The QLGSORT API supports database (both logical and physical), diskette, and
tape files. Any other file type is not recognized and an error is returned, but
the sort continues to provide output to any other output file types that are
supported. Variable length record access and null-capable fields are supported
for externally described database files only. The same file can be used both as
an input and as an output file.</p>
<p>If the sorted output is returned in the output data buffer parameter, or
returned using the QLGSRTIO API, the output file list is not used. If the
number of output files field is greater than 0, there must be exactly that
number of output files specified, or an error is returned.</p>
<p>Each output file contains the full sorted set of records unless an error
occurred for a file. Record truncation or padding of blanks occurs when writing
to the output file and when the file record length is different than the sorted
record length. One reason to have more than one output file is to provide a
backup or shadow of your output data as it is being sorted.</p>
<p><strong>Qualified sort table name.</strong> The name of a sort table to be
used for sorting the character data, and the library in which it is located.
The first 10 characters contain the sort table name, and the second 10
characters contain the library name.</p>
<p>When a qualified sort table name is specified, the sort sequence language ID
and sort sequence table fields are ignored.</p>
<p>The following special values are supported for the table name. These values
must be in uppercase, left-justified, and padded with blanks to the right of
the value.</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*JOB</em></td>
<td valign="top">The sort sequence of the job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*JOBRUN</em></td>
<td valign="top">The API treats this value the same as *JOB.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LANGIDUNQ</em></td>
<td valign="top">The unique-weight sort sequence table that is associated with
the sort sequence language ID field.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LANGIDSHR</em></td>
<td valign="top">The shared-weight sort sequence table that is associated with
the sort sequence language ID field.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*HEX</em></td>
<td valign="top">The hexadecimal value of the characters.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*TABLE</em></td>
<td valign="top">The sort sequence table provided in the sort sequence table
field.</td>
</tr>
</table>
<p><strong>Note:</strong> Both *JOB and *JOBRUN are accepted to accommodate
calls from other programs that accept both values and for which the two have
different semantics.</p>
<p>The following special values are supported for the library name. These
values must be in uppercase, left-justified, and padded with blanks to the
right of the value.</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td valign="top">The user's library list.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td valign="top">The current library.</td>
</tr>
</table>
<p>If a special value is used for the table name, the second 10 characters used
for the library name must be blank.</p>
<p><strong>Record count.</strong> The number of records that exist in the input
data buffer parameter when input data is to be sorted. Only the number of
records specified in the record count field are sorted, even if more than this
number exist in the input data buffer parameter. The record count multiplied by
the record length must not be greater than 16MB.</p>
<p>The record count field must be greater than 0 when the type of request field
is 4, 5, or 6 (input data to be sorted). If it is not, an error is
returned.</p>
<p>The record count field must be set to 0 when the type of request field is 1,
2, 3, 7, or 8 because input files are being sorted or the data will be provided
by the QLGSRTIO API. If it is not, an error is returned.</p>
<p><strong>Record length.</strong> The record length that the sort uses for
processing. When a data buffer is being sorted, this is the maximum length of a
record in the buffer. The value includes the following:</p>
<ul>
<li>The bytes used to store the actual user data<br>
<br>
</li>
<li>The 2-byte binary length for data type 19, 20, 21, or 22<br>
<br>
</li>
<li>The 2-byte binary length of the user data when using variable length record
access<br>
<br>
</li>
<li>The null byte map if using null field support</li>
</ul>
<p>For example, assume a user record contains five fields having a total length
of 80 bytes, supports nulls, and is processed using variable length record
access. The record length field 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>When a list of files is being sorted, this record length defines the length
used for sorting all the files. If the data is to be returned in the output
data buffer, the record count multiplied by the record length cannot be greater
than 16MB.</p>
<p>If an input file has a record length that is longer than the specified
record length, it is truncated. If an input file has a record length that is
shorter, it is padded with blanks.</p>
<p>When data is being provided through the QLGSRTIO API, this record length
defines the length used for sorting all the records. Each set of records added
to the sort through the QLGSRTIO API defines a record length for that set.
Records that are longer than the record length defined here are truncated.
Records that are shorter are padded with blanks.</p>
<p>The following special value is defined:</p>
<table cellpadding="3">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><strong>0</strong></td>
<td valign="top">QLGSORT assumes the maximum record length to be that of the
first input file processed. If 0 is specified when an input data buffer is
being sorted, or if data is being provided through calls to the QLGSRTIO API,
an error occurs.</td>
</tr>
</table>
<p><strong>Reserved.</strong> A reserved field. This field must be set to
0.</p>
<p><strong>Returned records.</strong> The number of records returned in an
output file.</p>
<p><strong>Sort order.</strong> The order to be used for sorting.</p>
<p>The following special values are defined:</p>
<table cellpadding="3">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>1</em></td>
<td valign="top">Sort in an ascending sequence.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td valign="top">Sort in a descending sequence.</td>
</tr>
</table>
<p><strong>Sort sequence CCSID.</strong> The CCSID to be used, along with the
sort sequence language ID, for retrieving the national language sort sequence
table for sorting the character data.</p>
<p>The valid values for this parameter are:</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td valign="top">The CCSID of the job is the CCSID of the sort sequence table
to be used.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1-65533</em></td>
<td valign="top">A valid CCSID in this range must be specified or an error is
returned.</td>
</tr>
<tr>
<td align="left" valign="top"><em>65535</em></td>
<td valign="top">The CCSID of the sort sequence table that is found should be
used. No CCSID conversion should be done on the found table.</td>
</tr>
</table>
<p>The following table summarizes when the CCSID value is required and when it
will be ignored based on the value in the qualified sort table name field in
the request control block.</p>
<table border width="50%">
<!-- width="50" -->
<tr>
<th align="center" valign="TOP">Qualified Sort Table Name</th>
<th align="center" valign="TOP">CCSID</th>
</tr>
<tr>
<td align="center" valign="TOP" width="50%">*JOB</td>
<td align="center" valign="TOP" width="50%">Required</td>
</tr>
<tr>
<td align="center" valign="TOP">*JOBRUN</td>
<td align="center" valign="TOP">Required</td>
</tr>
<tr>
<td align="center" valign="TOP">*LANGIDUNQ</td>
<td align="center" valign="TOP">Required</td>
</tr>
<tr>
<td align="center" valign="TOP">*LANGIDSHR</td>
<td align="center" valign="TOP">Required</td>
</tr>
<tr>
<td align="center" valign="TOP">*HEX</td>
<td align="center" valign="TOP">Ignored</td>
</tr>
<tr>
<td align="center" valign="TOP">*TABLE</td>
<td align="center" valign="TOP">Ignored</td>
</tr>
<tr>
<td align="center" valign="TOP">Table name and library</td>
<td align="center" valign="TOP">Ignored</td>
</tr>
</table>
<p><strong>Sort sequence language ID.</strong> The language ID to be used to
obtain a national language sort sequence table for sorting the character data.
All values must be padded with blanks to the right of the value and must be in
uppercase.</p>
<p>Possible values for this parameter are:</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*JOB</em></td>
<td valign="top">The language identifier of the job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*JOBRUN</em></td>
<td valign="top">The API treats this value the same as *JOB.</td>
</tr>
<tr>
<td align="left" valign="top"><em>Specific language identifier</em></td>
<td valign="top">A valid 3-character language identifier. For example, Danish
would be "DAN". See the <a href="../nls/rbagsglobalmain.htm">globalization</a>
topic for a complete list of valid language identifiers.</td>
</tr>
</table>
<p><strong>Note:</strong> Both *JOB and *JOBRUN are accepted to accommodate
calls from other programs that accept both values and for which the two have
different semantics.</p>
<p>The following table summarizes when the sort sequence language ID is
required and when it is ignored based on the value in the qualified sort table
name field in the request control block.</p>
<table border width="50%">
<!-- width="50" -->
<tr>
<th valign="TOP">Qualified Sort Table Name</th>
<th valign="TOP">Language ID</th>
</tr>
<tr>
<td align="center" valign="TOP" width="50%">*JOB</td>
<td align="center" valign="TOP" width="50%">Required</td>
</tr>
<tr>
<td align="center" valign="TOP" width="50%">*JOBRUN</td>
<td align="center" valign="TOP" width="50%">Required</td>
</tr>
<tr>
<td align="center" valign="TOP" width="50%">*LANGIDUNQ</td>
<td align="center" valign="TOP" width="50%">Required</td>
</tr>
<tr>
<td align="center" valign="TOP" width="50%">*LANGIDSHR</td>
<td align="center" valign="TOP" width="50%">Required</td>
</tr>
<tr>
<td align="center" valign="TOP" width="50%">*HEX</td>
<td align="center" valign="TOP" width="50%">Ignored</td>
</tr>
<tr>
<td align="center" valign="TOP" width="50%">*TABLE</td>
<td align="center" valign="TOP" width="50%">Ignored</td>
</tr>
<tr>
<td align="center" valign="TOP" width="50%">Table name and library</td>
<td align="center" valign="TOP" width="50%">Ignored</td>
</tr>
</table>
<p><strong>Sort sequence table.</strong> The sort table to be used for sorting
the character data. This field is only used when the qualified sort table name
field is *TABLE. Otherwise, it is ignored. If UCS-2 data is to be sorted, use
the QLGRTVSS API to retrieve a UCS-2 sort sequence table.</p>
<p><strong>Type of request.</strong> The type of sort operation being
requested. The following values are defined:</p>
<table cellpadding="3">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>1</em></td>
<td valign="top">Input files are sorted, and the output goes to an output
file.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td valign="top">Input files are sorted, and the output goes to the output data
buffer parameter.</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td valign="top">Input files are sorted, and the output is held for the
QLGSRTIO API to retrieve one set at a time.</td>
</tr>
<tr>
<td align="left" valign="top"><em>4</em></td>
<td valign="top">Data in an input data buffer is sorted, and the output goes to
an output file.</td>
</tr>
<tr>
<td align="left" valign="top"><em>5</em></td>
<td valign="top">Data in an input data buffer is sorted, and the output goes to
the output data buffer parameter.</td>
</tr>
<tr>
<td align="left" valign="top"><em>6</em></td>
<td valign="top">Data in an input data buffer is sorted, and the output is held
for the QLGSRTIO API to retrieve one set at a time.</td>
</tr>
<tr>
<td align="left" valign="top"><em>7</em></td>
<td valign="top">Input data is provided by the QLGSRTIO API, and the output
goes to an output file.</td>
</tr>
<tr>
<td align="left" valign="top"><em>8</em></td>
<td valign="top">A sort is initialized so that data can be provided through the
QLGSRTIO API one set at a time and retrieved one set at a time through the
QLGSRTIO API.</td>
</tr>
</table>
<p>The following table summarizes the input source and output target for each
type of request.</p>
<table border width="70%">
<tr>
<th valign="TOP">Type of Request</th>
<th valign="TOP">Source</th>
<th valign="TOP">Target</th>
</tr>
<tr>
<td align="center" valign="TOP" width="20%">1</td>
<td align="left" valign="top" width="40%">Input files</td>
<td align="left" valign="top" width="40%">Output files</td>
</tr>
<tr>
<td align="center" valign="TOP" width="20%">2</td>
<td align="left" valign="top" width="40%">Input files</td>
<td align="left" valign="top" width="40%">Output data buffer</td>
</tr>
<tr>
<td align="center" valign="TOP" width="20%">3</td>
<td align="left" valign="top" width="40%">Input files</td>
<td align="left" valign="top" width="40%">QLGSRTIO API calls</td>
</tr>
<tr>
<td align="center" valign="TOP" width="20%">4</td>
<td align="left" valign="top" width="40%">Input data buffer</td>
<td align="left" valign="top" width="40%">Output files</td>
</tr>
<tr>
<td align="center" valign="TOP" width="20%">5</td>
<td align="left" valign="top" width="40%">Input data buffer</td>
<td align="left" valign="top" width="40%">Output data buffer</td>
</tr>
<tr>
<td align="center" valign="TOP" width="20%">6</td>
<td align="left" valign="top" width="40%">Input data buffer</td>
<td align="left" valign="top" width="40%">QLGSRTIO API calls</td>
</tr>
<tr>
<td align="center" valign="TOP" width="20%">7</td>
<td align="left" valign="top" width="40%">QLGSRTIO API calls</td>
<td align="left" valign="top" width="40%">Output files</td>
</tr>
<tr>
<td align="center" valign="TOP" width="20%">8</td>
<td align="left" valign="top" width="40%">QLGSRTIO API calls</td>
<td align="left" valign="top" width="40%">QLGSRTIO API calls</td>
</tr>
</table>
<p>If the input files contain variable length fields, null fields, or use
variable length record access, the only type of request allowed is 1.</p>
<p>If the input buffer contains variable length fields, null fields, or uses
variable length record access, the only type of requests allowed are 5, 6, or
8.</p>
<p><strong>Variable length record access.</strong> Whether variable length
record access should be used for input or output files.</p>
<p>The possible values follow:</p>
<table cellpadding="3">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td valign="top">Do not use variable length record access.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td valign="top">Use variable length record access. This value is allowed only
when using externally described database files. All fields but the last one in
the file are defined as fixed length, and the last field is defined as variable
length.</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRBUFFER">Buffer Layout Examples</a></h3>
<p>The following examples show the layout of the buffer for fixed and variable
length fields, null-capable fields, and variable length record access. The null
byte map indicates whether the field is null (1) or contains data (0).</p>
<p><strong>Buffer with Fixed Length Fields</strong></p>
<p>If the sort includes none of the following, the record length field is set
to the total number of bytes for all the fields:</p>
<ul>
<li>Variable length fields<br>
<br>
</li>
<li>Null-capable fields<br>
<br>
</li>
<li>Variable length record access</li>
</ul>
<p>Following is an example of a buffer containing 4 fields that are fixed
length. The record length and the fields used for the sort are indicated.</p>
<pre>
Field 1 Char 8
Field 2 Char 10
Field 3 Char 3
Field 4 Char 10
Record length = 31
Sort on fields 1 and 3
</pre>
<table border width="50%" cellpadding="5">
<tr>
<th valign="top">Field 1</th>
<th valign="top">Field 2</th>
<th valign="top">Field 3</th>
<th valign="top">Field 4</th>
</tr>
<tr>
<td align="left" valign="top" width="25%">JJJJJJJJ<br>
FFF<br>
KKKKK</td>
<td align="left" valign="top" width="25%">A1B2C3D4E5<br>
A5B4C3D2E1<br>
A1B2C3D4E5</td>
<td align="left" valign="top" width="25%">XXX<br>
YY<br>
ZZZ</td>
<td align="left" valign="top" width="25%">1111111111<br>
222222<br>
33333333</td>
</tr>
</table>
<p><strong>Buffer with Variable Length Character Fields</strong></p>
<p>This is an example of a buffer that contains variable length fields. The
length of the each variable length field must be contained in a 2-byte binary
value that precedes the data.</p>
<pre>
Field 1 Char 8
Field 2 Char 10
Field 3 Char 3
Field 4 is variable length character
Record length = 33 (31 bytes for the maximum length
of the data plus 2 bytes for
the field length)
Sort on fields 1 and 3
</pre>
<table border width="60%" cellpadding="5">
<tr>
<th valign="top">Field 1</th>
<th valign="top">Field 2</th>
<th valign="top">Field 3</th>
<th valign="top" colspan="2">Field 4</th>
</tr>
<tr>
<th valign="top">Data</th>
<th valign="top">Data</th>
<th valign="top">Data</th>
<th valign="top">Length</th>
<th valign="top">Data</th>
</tr>
<tr>
<td align="left" valign="top" width="20%">JJJJJJJJ<br>
FFF<br>
KKKKK</td>
<td align="left" valign="top" width="20%">A1B2C3D4E5<br>
A5B4C3D2E1<br>
A1B2C3D4E5</td>
<td align="left" valign="top" width="20%">XXX<br>
YY<br>
ZZZ</td>
<td align="left" valign="top" width="20%">10<br>
6<br>
8</td>
<td align="left" valign="top" width="20%">1111111111<br>
222222<br>
33333333</td>
</tr>
</table>
<p><strong>Buffer with Variable Length Character Fields and Null-Capable
Fields</strong></p>
<p>If the buffer contains variable length fields and null-capable fields, the
null byte map must follow the record. The offset to the null byte map is set in
the offset to null byte map field. The null byte map contains one byte for each
field. The bytes correspond to the field order. For example, for null byte map
0010, fields&nbsp;1, 2, and 4 contain data and field 3 is null.</p>
<p>The position of each key must be set in the ordinal position of key
field.</p>
<pre>
Field 1 Char 8
Field 2 Char 10
Field 3 is null capable Char 3
Field 4 is variable length character
Record length = 37 (31 bytes for the maximum length
of the data plus 2 bytes for
the field length of field 4 plus
4 bytes for the null byte map)
Sort on fields 1 and 3
</pre>
<table border width="60%" cellpadding="5">
<tr>
<th valign="top">Field 1</th>
<th valign="top">Field 2</th>
<th valign="top">Field 3</th>
<th valign="top" colspan="2">Field 4</th>
<th valign="middle" rowspan="2">Null Byte Map</th>
</tr>
<tr>
<th valign="top">Data</th>
<th valign="top">Data</th>
<th valign="top">Data</th>
<th valign="top">Length</th>
<th valign="top">Data</th>
</tr>
<tr>
<td align="left" valign="top" width="17%">JJJJJJJJ<br>
FFF<br>
KKKKK</td>
<td align="left" valign="top" width="17%">A1B2C3D4E5<br>
A5B4C3D2E1<br>
A1B2C3D4E5</td>
<td align="left" valign="top" width="17%">XXX<br>
*NULL<br>
ZZZ</td>
<td align="left" valign="top" width="17%">10<br>
6<br>
8</td>
<td align="left" valign="top" width="16%">1111111111<br>
222222<br>
33333333</td>
<td align="left" valign="top" width="16%">0000<br>
0010<br>
0000</td>
</tr>
</table>
<p><strong>Buffer with Variable Length Record Access and Null-Capable
Fields</strong></p>
<p>If the buffer contains variable length records, the actual length of the
record must be added to the end of the data. It must precede the null byte
map.</p>
<pre>
Field 1 Char 8
Field 2 Char 10
Field 3 is null capable Char 3
Field 4 is variable length character
Record length = 37 (31 bytes for the maximum length
of the data plus 2 bytes for
the user record length plus
4 bytes for the null byte map)
Sort on fields 1 and 3
</pre>
<table border width="70%" cellpadding="5">
<tr>
<th valign="top">Field 1</th>
<th valign="top">Field 2</th>
<th valign="top">Field 3</th>
<th valign="top">Field 4</th>
<th valign="middle" rowspan="2">Actual Record Length</th>
<th valign="middle" rowspan="2">Null Byte Map</th>
</tr>
<tr>
<th valign="top">Data</th>
<th valign="top">Data</th>
<th valign="top">Data</th>
<th valign="top">Data</th>
</tr>
<tr>
<td align="left" valign="top" width="17%">JJJJJJJJ<br>
FFF<br>
KKKKK</td>
<td align="left" valign="top" width="17%">A1B2C3D4E5<br>
A5B4C3D2E1<br>
A1B2C3D4E5</td>
<td align="left" valign="top" width="17%">XXX<br>
*NULL<br>
ZZZ</td>
<td align="left" valign="top" width="17%">1111111111<br>
222222<br>
33333333</td>
<td align="left" valign="top" width="16">31<br>
27<br>
29</td>
<td align="left" valign="top" width="16">0000<br>
0010<br>
0000</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">CPF2115 E</td>
<td valign="top">Object &amp;1 in &amp;2 type *&amp;3 damaged.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2207 E</td>
<td valign="top">Not authorized to use object &amp;1 in library &amp;3 type
*&amp;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">CPF3BC6 E</td>
<td valign="top">Sort sequence &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3BC7 E</td>
<td valign="top">CCSID &amp;1 outside of valid range.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3BC8 E</td>
<td valign="top">Conversion from CCSID &amp;1 to CCSID &amp;2 is not
supported.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3BC9 E</td>
<td valign="top">Conversion from CCSID &amp;1 to CCSID &amp;2 is not
defined.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3BCC E</td>
<td valign="top">Language identifier &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3BD3 E</td>
<td valign="top">Sort already active.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3BD5 E</td>
<td valign="top">Sort request control block field &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3BD6 E</td>
<td valign="top">Key field &amp;1 is not valid for key number &amp;2.</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">CPF3BD8 E</td>
<td valign="top">Input file entry &amp;3 field &amp;4 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3BD9 E</td>
<td valign="top">Output file entry &amp;3 field &amp;4 is not valid.</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 &amp;1 in library
&amp;2.</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 &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3BE6 E</td>
<td valign="top">Number of parameters, &amp;1, entered for this API was not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3BE7 E</td>
<td valign="top">File &amp;1 in library &amp;2 or file entry &amp;4 has error
&amp;3.</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">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 &amp;1 in library &amp;2 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9504 E</td>
<td valign="top">An invalid search order was specified.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9801 E</td>
<td valign="top">Object &amp;2 in library &amp;3 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9802 E</td>
<td valign="top">Not authorized to object &amp;2 in &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9803 E</td>
<td valign="top">Cannot allocate object &amp;2 in library &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9810 E</td>
<td valign="top">Library &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9812 E</td>
<td valign="top">File &amp;1 in library &amp;2 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9820 E</td>
<td valign="top">Not authorized to use library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9830 E</td>
<td valign="top">Cannot assign library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9845 E</td>
<td valign="top">Error occurred while opening file &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9846 E</td>
<td valign="top">Error while processing file &amp;1 in library &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td valign="top">Program or service program &amp;1 in library &amp;2 ended.
Reason code &amp;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>
Reference in New Issue Copy Permalink