Retrieve Sort Sequence Table (QLGRTVSS) API

The Retrieve Sort Sequence Table (QLGRTVSS) API returns a sort sequence table based on the required input parameters. It will also return some associated job information.

Authorities and Locks

Sort Sequence Table Authority

*USE

Sort Sequence Table Library Authority

*USE

Sort Sequence Table Lock

*SHRNUP

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested, provided you specify the length of receiver variable parameter correctly. As a result, the API returns only the data the area can hold.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable. If the length is larger than the size of the receiver variable, the results are not predictable. The minimum length is 8 bytes.

Qualified table name

INPUT; CHAR(20)

The sort sequence table to retrieve. The first 10 characters contain the table name, and the second 10 characters contain the name of the library in which the table resides.

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.

*JOB	The sort sequence of the job.
*JOBRUN	The API treats this value the same as *JOB.
*LANGIDUNQ	The unique-weight sort sequence table that is associated with the language identifier requested parameter.
*LANGIDSHR	The shared-weight sort sequence table that is associated with the language identifier requested parameter.
*HEX	The sort sequence according to the hexadecimal value of the characters.

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.

*LIBL	The user's library list.
*CURLIB	The current library.

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

Language identifier requested

INPUT; CHAR(10)

The language identifier of the sort sequence table to be used. All values must be in uppercase and must be padded with blanks to the right of the value. This value will be ignored if the value of the table name parameter is a table object or *HEX. Valid values are:

*JOB	Use the language identifier of the job.
*JOBRUN	The API treats this value the same as *JOB.
Specific language identifier	A valid 3-character language identifier. For example, Danish would be "DAN". See the globalization topic for a complete list of valid language identifiers.

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.

CCSID of returned table

INPUT; BINARY(4)

The coded character set identifier (CCSID) in which the sort sequence table should be returned. The valid values for this parameter are:

0	The CCSID of the job will be used to determine the CCSID of the sort sequence table to be returned.
1-65533	A valid CCSID in this range.
65535	The CCSID of the sort sequence table that is found should be used. No CCSID conversion should be done on the found table.

Format name

INPUT; CHAR(8)

The content and format of the information returned for each table. The format name is:

RSST0100

Sort sequence format for single-byte sort sequence table.

See RSST0100 Format for a description of this format.

RSST0200

Sort sequence format for a single-byte or UCS-2 sort sequence table.

See RSST0200 Format for a description of this format.

Error code

I/O; CHAR(*)

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

RSST0100 Format

Following is the format of the information returned. For a description of the fields in this format, see Field Descriptions.

RSST0200 Format

Following is the format of the information returned. For a description of the fields in this format, see Field Descriptions.

Field Descriptions

Bytes available. The number of bytes of information available.

Bytes returned. The number of bytes of information returned.

CCSID of returned table. The coded character set identifier (CCSID) in which the returned sort sequence table is encoded.

Notes:

1. No conversion is performed if the CCSID tag of the stored table is 65535 or if the job CCSID value is used and it is 65535.
   
   
2. All tables created before Version 2 Release 3 will always be assumed to be tagged with a CCSID value of 65535.
   
   
3. If *HEX is specified for the sort sequence to get, this value is set to 65535.

Job CCSID value. The CCSID value of this job.

Job country or region identifier. The country or region identifier of this job.

Job language identifier. The language identifier of this job.

Job sort sequence table library name. The sort sequence table library name of this job.

Job sort sequence table name. The sort sequence table name of this job. It can have one of the special values:

Offset to returned sort sequence table. The offset in bytes to the first element in the returned sort sequence table. A value of 0 indicates no table was returned.

Returned table name. The name of the sort sequence table that was returned.

The value of the returned table name is "*N         " if the table returned is the result of a requested sort sequence of *HEX or the result of converting an existing table from its stored CCSID representation to the CCSID requested. (A new table object will not be created in this case.)

Returned table library name. The name of the sort sequence table library that was returned.

The value of the returned table library name is "*N         " if the table returned is the result of a requested sort sequence of *HEX or the result of converting an existing table from its stored CCSID representation to the CCSID requested.

If *LIBL or *CURLIB was specified for the qualified table name, the name of the library in which the sort sequence resides will be returned.

Returned sort sequence table. The variable length sort sequence table that is described by the input values. The returned UCS-2 sort sequence table can be used as control map type E-1 for the XLATEMB instruction by using the information that starts at offset 94 from the beginning of the table and ends at the end of the table.

Size of returned sort sequence table. The number of bytes in the sort sequence table that is returned.

Substitution values encountered. Whether substitution values were involved during the conversion from the source CCSID of the table to the requested CCSID. A substitution occurs when a character in the source CCSID does not exist in the requested CCSID. The valid values are:

Type of sort sequence table returned. The type of sort sequence table returned. The valid values are:

Weighting of returned sort sequence table. The weighting of sort sequence table returned. The valid values are:

Note: Any table created prior to Version 2 Release 3 is always returned as a shared-weight table.

Layout of a Returned UCS-2 Sort Sequence Table

The size of a returned sort sequence table includes 128 bytes of the header, 4 bytes containing the number of cells, and the number of cells * 4 bytes.

A cell has the following layout:

2 bytes for the code point

2 bytes for the weight

The remainder of the line is ignored and can be used for comments.

The following is an example of a UCS-2 sort sequence table.

Error Messages