| 1 | Request control block | Input | Char(16) |
| 2 | Input data buffer | Input | Char(*) |
| 3 | Output data buffer | Output | Char(*) |
| 4 | Length of output data buffer | Input | Binary(4) |
| 5 | Output data information | Output | Char(16) |
| 6 | Error code | I/O | Char(*) |
| 7 | Returned records feedback | Output | Char(*) |
| 8 | Length of returned records feedback | Input | Binary(4) |
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.
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.
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.
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.
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.
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 Format of Request Control Block for details.
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 Buffer Layout Examples 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.
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.
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.
Information to be returned to the calling program as a result of a put or get request. See Format of Output Data Information for details on the format.
The structure in which to return error information. For the format of the structure, see Error Code Parameter.
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.
The number of records added to each output file corresponds to the list of files specified in the request control block.
This parameter is used only for sorted data returned in an output file for the following:
To receive results, set the options field in the request control block for the QLGSORT API to 4, 5, 6, or 7.
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.
For a description of the fields in this format, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Type of request |
| 4 | 4 | BINARY(4) | Reserved |
| 8 | 8 | BINARY(4) | Record length |
| 12 | C | BINARY(4) | Record count |
For a description of the fields in this format, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number of records processed |
| 4 | 4 | BINARY(4) | Number of records available |
| 8 | 8 | CHAR(8) | Reserved |
For a description of the fields in this format, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes available |
| 4 | 4 | BINARY(4) | Bytes returned |
| 8 | 8 | BINARY(4) | Offset to start of returned records array |
| 12 | C | BINARY(4) | Number of output files returned |
| 16 | 10 | CHAR(*) | Reserved |
| ARRAY of BINARY(4) | Returned records | ||
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned. The number of bytes of data returned.
Number of output files returned. The number of output files specified in the request control block of the QLGSORT API.
Number of records available. 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.
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.
Number of records processed. 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.
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.
Offset to start of returned records array. Offset to the returned records array.
Record count. 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.
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.
Using record counts greater than 1 can improve performance.
Record length. 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.
This value includes the following:
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.
The offsets to the variable length record access information and the null byte map are specified in the QLGSORT API request control block.
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.
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.
Reserved. 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.
Returned records. The number of records returned in an output file.
Type of request. The type of operation being requested. The following values are defined:
| 1 (Put) | 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.
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. |
| 2 (End put) | 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.
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. |
| 3 (Get) | 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.
A get request is valid for each of the following conditions:
If a get request is made at any other time, an error is returned. |
| 4 (Cancel) | 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. |
| Message ID | Error Message Text |
|---|---|
| CPF2207 E | Not authorized to use object &1 in library &3 type *&2. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3BD0 E | QLGSRTIO request control block field &1 is not valid. |
| CPF3BD1 E | Output data length parameter is not valid. |
| CPF3BD2 E | Type of request &1 is not valid at this time. |
| CPF3BD7 E | Key size exceeds maximum. |
| CPF3BDA E | No output files could be opened. |
| CPF3BDB E | Sort internal storage limit exceeded. |
| CPF3BDC E | Duplicate keys encountered for file &1 in library &2. |
| CPF3BF0 E | Sort sequence table specified or supplied is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3BE2 E | Returned record feedback length not valid. |
| CPF3BE4 E | Buffer information is not valid. Reason &1. |
| CPF3BE7 E | File &1 in library &2 or file entry &4 has error &3. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF5715 E | File &1 in library &2 not found. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9810 E | Library &1 not found. |
| CPF9812 E | File &1 in library &2 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9822 E | Not authorized to file &1 in library &2. |
| CPF9830 E | Cannot assign library &1. |
| CPF9845 E | Error occurred while opening file &1. |
| CPF9846 E | Error while processing file &1 in library &2. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| Top | National Language Support APIs | APIs by category |