Retrieve Sort Sequence Table (QLGRTVSS) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Qualified table name | Input | Char(20) |
| 4 | Language identifier requested | Input | Char(10) |
| 5 | CCSID of returned table | Input | Binary(4) |
| 6 | Format name | Input | Char(8) |
| 7 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
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 i5/OS globalization topic collection 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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes available |
| 4 | 4 | BINARY(4) | Bytes returned |
| 8 | 8 | BINARY(4) | Job CCSID value |
| 12 | C | BINARY(4) | CCSID of returned table |
| 16 | 10 | CHAR(1) | Substitution values encountered |
| 17 | 11 | CHAR(1) | Weighting of returned sort sequence table |
| 18 | 12 | CHAR(10) | Returned table name |
| 28 | 1C | CHAR(10) | Returned table library name |
| 38 | 26 | CHAR(10) | Job sort sequence table name |
| 48 | 30 | CHAR(10) | Job sort sequence table library name |
| 58 | 3A | CHAR(3) | Job language identifier |
| 61 | 3D | CHAR(2) | Job country or region identifier |
| 63 | 3F | CHAR(256) | Returned sort sequence table |
RSST0200 Format
Following is the format of the information returned. 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) | Job CCSID value |
| 12 | C | BINARY(4) | CCSID of returned table |
| 16 | 10 | CHAR(1) | Substitution values encountered |
| 17 | 11 | CHAR(1) | Weighting of returned sort sequence table |
| 18 | 12 | CHAR(10) | Returned table name |
| 28 | 1C | CHAR(10) | Returned table library name |
| 38 | 26 | CHAR(10) | Job sort sequence table name |
| 48 | 30 | CHAR(10) | Job sort sequence table library name |
| 58 | 3A | CHAR(3) | Job language identifier |
| 61 | 3D | CHAR(2) | Job country or region identifier |
| 63 | 3F | CHAR(1) | Type of sort sequence table returned |
| 64 | 40 | BIN(4) | Offset to returned sort sequence table |
| 68 | 44 | BINARY(4) | Size of returned sort sequence table |
| CHAR(*) | Returned sort sequence table | ||
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:
- 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.
- All tables created before Version 2 Release 3 will always be assumed to be
tagged with a CCSID value of 65535.
- 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:
| *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. |
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:
| 0 | No substitutions were involved. |
| 1 | Substitutions were involved. |
Type of sort sequence table returned. The type of sort sequence table returned. The valid values are:
| 0 | Single byte sort sequence table returned. |
| 1 | UCS-2 sort sequence table returned. |
Weighting of returned sort sequence table. The weighting of sort sequence table returned. The valid values are:
| 1 | A shared-weight table. |
| 2 | A unique-weight table. |
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
| Message ID | Error Message Text |
|---|---|
| CPF2115 E | Object &1 in &2 type *&3 damaged. |
| CPF2169 E | Job's sort sequence information not available. |
| CPF2207 E | Not authorized to use object &1 in library &3 type *&2. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3BC6 E | Sort sequence &1 not valid. |
| CPF3BC7 E | CCSID &1 outside of valid range. |
| CPF3BC8 E | Conversion from CCSID &1 to CCSID &2 is not supported. |
| CPF3BC9 E | Conversion from CCSID &1 to CCSID &2 is not defined. |
| CPF3BCC E | Language identifier &1 not valid. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| 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. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R3
[ Back to top | National Language Support APIs | APIs by category ]