Sort (QLGSORT) API

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.

The following types of sort operations can be done with the API:

• Sort up to 32 input files and produce 1 to 32 output files, each containing the full list of sorted records.
  
  
• Sort up to 32 input files and return all of the records in the output data buffer parameter.
  
  
• Sort up to 32 input files, and return the output a set at a time through the QLGSRTIO API.
  
  
• 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.
  
  
• Sort a set of records in the input data buffer parameter and return all of the records in the output data buffer parameter.
  
  
• Sort a set of records in the input data buffer parameter and return the output a set at a time through the QLGSRTIO API.
  
  
• 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.
  
  
• 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Authorities and Locks

Input File Authority

*USE

Input File Library Authority

*USE

Output File Authority

Both *OBJOPR and *ADD or both *OBJALT and *ADD

Output File Library Authority

*USE

Sort Sequence Table Authority

*USE

Sort Sequence Table Library Authority

*USE

Input File Lock

*SHRNUP

Output File Lock

*EXCL

Sort Sequence Table Lock

*SHRNUP

Required Parameter Group

Request control block

INPUT; CHAR(*)

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 Format of Request Control Block for details.

Input data buffer

INPUT; CHAR(*)

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 Buffer Layout Examples.

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.

Output data buffer

OUTPUT; CHAR(*)

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.

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 Buffer Layout Examples.

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.

Length of output data buffer

INPUT; BINARY(4)

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.

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.

Length of returned data

OUTPUT; BINARY(4)

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.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Optional Parameter Group

Returned records feedback

OUTPUT; CHAR(*)

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.

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.

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.

See Format of Returned Records Feedback Information for details.

Length of returned records feedback

INPUT; BINARY(4)

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 Format of Returned Records Feedback Information for details.

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.

Format of Request Control Block

For a description of the fields in this format, see Field Descriptions.

Format of Returned Records Feedback Information

For a description of the fields in this format, see Field Descriptions.

Field Descriptions

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.

Input member name. 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.

Key data type. The following are the values that may be specified:

The use of any other value will cause an error to be returned.

Key starting position. 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.

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.

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.

Key string size. 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.

Note: Data that is encoded in UCS-2 requires 2 bytes for each character.

Length of input file entry. 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:

• Variable length record access
  
  
• Null-capable fields

Length of key entry. 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.

Length of national language sort sequence information. The total length of the national language sort sequence information. If specified, the minimum length must be 290 bytes.

Length of output file entry. 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:

• Variable length record access
  
  
• Null-capable fields

Length of request control block. 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.

Null-capable fields. Whether null-capable fields are supported in a file. The possible values follow:

Number of input files. 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.

Number of keys. 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.

Number of output files. 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.

Offset to input file list. 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.

Offset to key list. 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.

Offset to national language sort information. 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.

Offset to null byte map. 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.

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 Buffer Layout Examples for information on how to format this buffer.

Offset to output file list. 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.

Offset to start of returned records array. The offset to the returned records array.

Offset to variable length record access information. 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.

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.

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.

Options. Additional options to be handled by the sort. The following values are defined:

Ordinal position of key field. 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.

Output member name. 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.

Qualified input file name. 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.

The library name can have the following special values:

All values must be padded with blanks to the right of the value.

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.

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.

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.

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.

Qualified output file name. 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.

The library name can have the following special values:

All values must be padded with blanks to the right of the value.

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.

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.

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.

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.

Qualified sort table name. 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.

When a qualified sort table name is specified, the sort sequence language ID and sort sequence table fields are ignored.

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.

Note: Both *JOB and *JOBRUN are accepted to accommodate calls from other programs that accept both values and for which the two have different semantics.

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.

If a special value is used for the table name, the second 10 characters used for the library name must be blank.

Record count. 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.

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.

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.

Record length. 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:

• The bytes used to store the actual user data
  
  
• The 2-byte binary length for data type 19, 20, 21, or 22
  
  
• The 2-byte binary length of the user data when using variable length record access
  
  
• The null byte map if using null field support

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.

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.

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.

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.

The following special value is defined:

Reserved. A reserved field. This field must be set to 0.

Returned records. The number of records returned in an output file.

Sort order. The order to be used for sorting.

The following special values are defined:

Sort sequence CCSID. 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.

The valid values for this parameter are:

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.

Sort sequence language ID. 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.

Possible values for this parameter are:

Note: Both *JOB and *JOBRUN are accepted to accommodate calls from other programs that accept both values and for which the two have different semantics.

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.

Sort sequence table. 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.

Type of request. The type of sort operation being requested. The following values are defined:

The following table summarizes the input source and output target for each type of request.

If the input files contain variable length fields, null fields, or use variable length record access, the only type of request allowed is 1.

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.

Variable length record access. Whether variable length record access should be used for input or output files.

The possible values follow:

Buffer Layout Examples

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).

Buffer with Fixed Length Fields

If the sort includes none of the following, the record length field is set to the total number of bytes for all the fields:

• Variable length fields
  
  
• Null-capable fields
  
  
• Variable length record access

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.

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

Buffer with Variable Length Character Fields

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.

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

Buffer with Variable Length Character Fields and Null-Capable Fields

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 1, 2, and 4 contain data and field 3 is null.

The position of each key must be set in the ordinal position of key field.

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

Buffer with Variable Length Record Access and Null-Capable Fields

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.

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

Error Messages