Truncate Character Data (QLGTRDTA) API

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:

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

2. 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.
   
   
3. 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.

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

[ Back to top | National Language Support APIs | APIs by category ]