Truncate Character Data (QLGTRDTA) API
Required Parameter Group:
1 | Output data buffer | Output | Char(*) |
2 | Length of output data returned | Output | Binary(4) |
3 | Remaining data buffer | Output | Char(*) |
4 | Remaining data length | Output | Binary(4) |
5 | Input data buffer | Input | Char(*) |
6 | Length of buffers | Input | Binary(4) |
7 | Truncate length | Input | Binary(4) |
8 | CCSID of input data | Input | Binary(4) |
9 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Truncate Character Data (QLGTRDTA) API truncates a CCSID-tagged string of character data to a requested length. This API is used to truncate a string of data properly. The string is truncated with respect to the encoding of the data using the encoding scheme of the CCSID. A typical use of this API would be to properly truncate mixed-byte strings for use in a display screen.
This API works in the following manner:
- Given the truncate length requested for the result, truncate the input data
in a proper manner to no longer than this value. If the length of the input
data buffer is less than the requested truncate length, the returned length is
set to the input length and the data in the input data buffer is placed in the
resultant output data buffer.
Proper manner means that no multibyte characters are split and no control information is lost. In the situation where characters would be split, the truncation point is re-adjusted to an acceptable position to allow truncation. If control characters are required to be appended to the output, adjustment to the output may be done. For example, if the requested string is in the ISO-2022 encoding scheme, the truncate length requested is reduced by three. This allows for appending the ASCII single-byte escape sequence ('1B2842'X) to the output data returned.
- Place this result into the requested output data buffer and set its length
in the length of output data returned parameter. Pad the rest of this parameter
with the appropriate blank characters. When the length of input is less than
the truncate length, all data is placed in the output data buffer because the
condition would call for no truncation.
- Place the remaining input data (properly formed) into the remaining data buffer and set its length in the remaining data length parameter. Properly formed data refers to providing a valid string for the type of data being used. For example, mixed EBCDIC data must have matched control characters (X'0E' and X'0F') around any double-byte character data.
Authorities and Locks
None.
Required Parameter Group
- Output data buffer
- OUTPUT; CHAR(*)
The buffer that receives the properly formed truncated string. This parameter must be the same size as the value specified for the length of buffers parameter.
- Length of output data returned
- OUTPUT; BINARY(4)
The number of bytes of data actually returned in the resultant output buffer.
- Remaining data buffer
- OUTPUT; CHAR(*)
The buffer that receives the data remaining after the truncation has been done. This buffer must be the same size as the input data buffer.
- Remaining data length
- OUTPUT; BINARY(4)
The length of the data remaining after the truncation has been done. This data is the length of the remaining data buffer.
- Input data buffer
- INPUT; CHAR(*)
The buffer that holds the input data.
- Length of buffers
- INPUT; BINARY(4)
The length of each of the following data buffers:
- Input data buffer
- Output data buffer
- Remaining data buffer
The maximum size of each data buffer is 32767 bytes.
- Input data buffer
- Truncate length
- INPUT; BINARY(4)
The maximum length of data to be returned in the output data buffer. Valid values are 1 through 32767.
- CCSID of input data
- INPUT; BINARY(4)
The CCSID of the data to be truncated. Valid values are 0 through 65533 and 65535. If the CCSID value 0 is provided, the job's default CCSID is used.
If the CCSID tag of the data is not known, a value of 65535 should be used. If the CCSID value is 65535, the data is assumed to be a mixed-byte EBCDIC string that is properly formed.
The supported encoding schemes are single-byte data, mixed-byte EBCDIC data, double-byte data, PC mixed data, ISO-2022 data, and extended UNIX® coded-character set (EUC) data. The following specific encoding schemes are supported:
Single-byte data '1100'X, '2100'X, '3100'X, '4100'X,'4105'X,'4155'X, '5100'X,'5150'X,'6100'X Double-byte data '1200'X, '2200'X, '3200'X,'5200'X,'7200'X Mixed EBCDIC data '1301'X Mixed PC data '2300'X,'3300'X ISO-2022 data '5404'X EUC data '4403'X See the i5/OS globalization topic collection for more information about CCSID values and encoding schemes.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Error Messages
Message ID | Error Message Text |
---|---|
CPF24B4 E | Severe error while addressing parameter list. |
CPF2647 E | Buffer length not valid. |
CPF3BC7 E | CCSID &1 outside of valid range. |
CPF3BCA E | CCSID &1 not supported. |
CPF3BCB E | Encoding scheme &1 of CCSID &2 not supported. |
CPF3BCF E | Truncate length not valid. |
CPF3C90 E | Literal value cannot be changed. |
CPF3CF1 E | Error code parameter not valid. |
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 ]