Convert Case (QLGCNVCS, QlgConvertCase) API
Required Parameter Group:
| 1 | Request control block | Input | Char(*) |
| 2 | Input data | Input | Char(*) |
| 3 | Output data | Output | Char(*) |
| 4 | Length of data | Input | Binary(4) |
| 5 | Error code | I/O | Char(*) |
Service Program: QLGCASE
Default Public Authority: *USE
Threadsafe: No
The Convert Case (OPM, QLGCNVCS; ILE, QlgConvertCase) API provides a case conversion function that can be directly called by any application program. This API can be used to convert character data to either uppercase or lowercase.
This API supports conversion for single-byte, mixed-byte, and UCS2 (Universal Multiple-Octet Coded Character Set with 16 bits per character) character sets. For the mixed-byte character set data, only the single-byte portion of the data is converted. This API does not convert double-byte character data from any double-byte character set (DBCS) or from a mixed-byte character set.
This API can base case conversion on a CCSID, whereas the Convert Data (QDCXLATE) API uses only table objects.
Authorities and Locks
- Table Authority
- *USE
- Table Library
- *USE
- Table Lock
- *SHRNUP
Required Parameter Group
- Request control block
- INPUT; CHAR(*)
The information that defines the case conversion alternatives. Refer to Format of Request Control Block for details.
- Input data
- INPUT; CHAR(*)
The input data being converted.
- Output data
- OUTPUT; CHAR(*)
The converted output data that is returned to the calling program. The storage allocated for this output buffer parameter must be at least as long as the input data buffer or unpredictable results may occur.
- Length of data
- INPUT; BINARY(4)
The length of the data being converted in the input data parameter. Any data that extends beyond the specified length is ignored. The specified length must be a value greater than 0 and less than 16 773 104 bytes.
The length of the storage allocated for the output data is assumed to be the same size as the length of the input data.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of Request Control Block
The following table shows the layout of the request control block. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Type of request |
| Note: The rest of the layout when the request is 1 (CCSID format) | |||
| 4 | 4 | BINARY(4) | CCSID of input data |
| 8 | 8 | BINARY(4) | Case request |
| 12 | C | CHAR(10) | Reserved |
| Note: The rest of the layout when the request is 2 (table object format) | |||
| 4 | 4 | BINARY(4) | DBCS indicator |
| 8 | 8 | CHAR(20) | Qualified table name |
| Note: The rest of the layout when the request is 3 (user-defined format) | |||
| 4 | 4 | BINARY(4) | DBCS indicator |
| 8 | 8 | BINARY(4) | Reserved |
| 12 | C | BINARY(4) | Length of user-defined table |
| 16 | 10 | CHAR(*) | User-defined case conversion table |
Field Descriptions
Case request. A request that specifies the type of case conversion to be performed. Valid values are:
| 0 | Convert the input data to uppercase. |
| 1 | Convert the input data to lowercase. |
CCSID of input data. The coded character set identifier (CCSID) of the input data to be converted. Case conversion is performed based on this CCSID. For a list of valid CCSIDs, see the i5/OS globalization topic collection. The valid values are:
| 0 | The CCSID of the job is used to determine the CCSID of the data to be converted. If the job CCSID is 65535, the CCSID from the default CCSID (DFTCCSID) job attribute is used. |
| 1-65533 | A valid CCSID in this range. |
DBCS indicator. The indicator that specifies whether or not double-byte data exists in the input data.
| 0 | Input data does not contain any double-byte values. |
| 1 | Input data may contain mixed values where the double-byte data is surrounded by shift-out and shift-in characters. Any double-byte data found between a shift-out and shift-in character is ignored and returned to the output data buffer as is. |
When the DBCS indicator is 0 but the input data contains double-byte values, this API processes the double-byte data as single-byte data. This also pertains to the shift-in and shift-out characters. It is recommended that an indicator of 0 be used when processing input data that contains only single-byte data because the performance is faster.
Length of user-defined table. The length (in bytes) of the user-defined case conversion table. This length must be 256.
Qualified table name. The table used to convert the data. The first 10 characters contain the table name. The second 10 characters contain the name of the library in which the table resides.
The system-supplied tables only provide uppercasing of the data. For a list of valid case conversion tables supplied by the system, see the i5/OS globalization topic collection.
You can use the following special values for the library name:
| *LIBL | The library list. |
| *CURLIB | The job's current library. |
Reserved. A reserved field that must be set to hexadecimal zeros.
Type of request. The input information format of the case conversion being requested. The layout of the request control block parameter is based on one of the following values:
| 1 | CCSID format |
| 2 | Table object format |
| 3 | User-defined format |
User-defined case conversion table. The user-defined case conversion table used to convert the input data.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3BC7 E | CCSID &1 outside of valid range. |
| CPF3BDE E | CCSID &1 not supported by API. |
| CPF3BE5 E | Value &1 for case request not valid. |
| CPF3BE8 E | Value &1 for DBCS indicator not valid. |
| CPF3BE9 E | Value &1 for reserved field not valid. |
| CPF3BEA E | User-defined table length &1 not valid. |
| CPF3BEB E | Type of request &1 not valid. |
| CPF3BEC E | Value &1 for reserved field not valid. |
| CPF3C12 E | Length of data is not valid. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. (This message applies only to the QLGCNVCS API, not the QlgConvertCase API.) |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9804 E | Object &2 in library &3 damaged. |
| CPF9805 E | Object &2 in library &3 destroyed. |
| CPF9807 E | One or more libraries in library list deleted. |
| CPF9808 E | Cannot allocate one or more libraries on library list. |
| CPF9809 E | Library &1 cannot be accessed. |
| CPF9810 E | Library &1 not found. |
| CPF9830 E | Cannot assign library &1. |
API introduced: V3R1
[ Back to top | National Language Support APIs | APIs by category ]