Convert a Graphic Character String (CDRCVRT, QTQCVRT) API

Required Parameter Group:

1	CCSID1	Input	Int(4)
2	ST1	Input	Int(4)
3	S1	Input	Char(*)
4	L1	Input	Int(4)
5	CCSID2	Input	Int(4)
6	ST2	Input	Int(4)
7	GCCASN	Input	Int(4)
8	L2	Input	Int(4)
9	S2	Output	Char(*)
10	L3	Output	Int(4)
11	L4	Output	Int(4)
12	FB	Output	Feedback

Default Public Authority: *USE

Threadsafe: Yes

The Convert a Graphic Character String (CDRCVRT, QTQCVRT) API converts a graphic character data string of the identified string type (ST1) represented in a specified from CCSID (CCSID1) to a graphic character data string of the required string type (ST2) that is represented in another specified to CCSID (CCSID2).

The function assumes that the entire string to be converted is known and is passed to the function. Also, the caller has provided sufficient space for the returned converted string. In case of an overflow situation, an orderly truncation would result.

Authorities and Locks

None.

Required Parameter Group

CCSID1

INPUT; INT(4)

This variable contains the CCSID value for the input graphic character data string being converted. The valid range is 1 to 65,533.

ST1

INPUT; INT(4)

This variable contains the type of input string. The following types are defined:

Type	Explanation
0	A graphic character string, as semantically defined by CCSID1.
1	A graphic character string, as semantically defined by CCSID1, and null-terminated.

S1

INPUT; CHAR(*)

This variable contains the graphic character data to be converted.

L1

INPUT; INT(4)

This variable contains the length (in number of bytes) of:

the string to be converted when ST1=0 or
the input buffer when ST1=1

The valid range is from 1 to 32,767.

CCSID2

INPUT; INT(4)

This variable contains the CCSID value for the converted graphic character data string. The valid range is 1 to 65,533.

ST2

INPUT; INT(4)

This variable contains the type of output string. The following types are defined:

Type	Explanation
0	A graphic character string, as semantically defined by CCSID2.
1	A graphic character string, as semantically defined by CCSID2, and null-terminated.
2	A graphic character string, as semantically defined by CCSID2, and SPACE-padded.

GCCASN

INPUT; INT(4)

This variable contains a number that identifies which conversion alternative is to be selected to convert graphic character data from (CCSID1, ST1) to (CCSID2, ST2). Valid values are:

Value	Nature of the Conversion Alternative Selected
0	Used to select the designated "installation default" conversion method and tables.
1	Used to select the CDRA-defined default method and associated conversion tables. The difference management criterion used in the creation of the selected tables is based on country or region requirements to serve the majority of applications using the selected CCSID pairs.
57	Enforced subset match.

Notes:

The values 0 and 1 are treated the same.
Character Data Representation, SC09-1391, contains the CDRA-defined default conversion tables. This book is not available online, but can be ordered from the IBM Publications Center.

L2

INPUT; INT(4)

This variable contains the byte-length of the allocated area to contain the converted graphic character data. The valid range is 1 to 32,767.

S2

OUTPUT; CHAR(*)

The converted graphic character data. The area's allocated length is given in L2.

Under certain error conditions the output may contain the results of converting only a part of the input string.

L3

OUTPUT; INT(4)

This variable contains the byte-length of the converted string returned in S2.

The byte-length includes any null termination or padding characters necessary to retain the semantics of CCSID2 and ST2.

L4

OUTPUT; INT(4)

The implementation of this API does not support the function of this parameter. This value is always returned as 0.

FB

OUTPUT; FEEDBACK

The function returns (in this feedback array) the processing status (and any associated reason) for this function; the field type is array of three 32-bit two's complement binary values (12 bytes, or 96 bits); the status code is a non-negative number in the first 16 bits, and the reason code is a non-negative number in the second 16 bits. The following are specific meanings of the status code and associated reason code values (in hexadecimal) contained in the first 32 bits of FB.

Feedback Codes and Conditions

Status	Reason	Meaning
0000	0000	The function completed successfully.
0001	0001	Requested conversion is not supported
0001	0005	The requested conversion algorithm specified by GCCASN does not support the specified (CCSID1, ST1) to (CCSID2, ST2) combination.
0001	0006	GCCASN value is 0; but an "installation default" was not found in the GCCST, for the pair (CCSID1, ST1) to (CCSID2, ST2).
0002	0001	CCSID1 value is 0, which is reserved to indicate defaulting to a higher level in a hierarchy. The caller must resolve the default before calling this function.
0002	0002	CCSID2 value is 0, which is reserved to indicate defaulting to a higher level in a hierarchy. The caller must resolve the default before calling this function.
0003	0001	CCSID1 is 65,535.
0003	0002	CCSID2 is 65,535.
0004	0001	The length value in L2 allocated for area S2 was too small for the output data. A properly truncated and terminated converted string that fits within the allocated maximum is returned in the area starting at S2 with its byte-length in L3. The value in L4 is set to 0.
0004	0002	The encoding scheme of CCSID1 is X'1301' (mixed Host; single-byte/double-byte encoding). The length value in L2 allocated for area S2 was too small for the output data. A properly truncated and terminated converted string that fits within the allocated maximum is returned in the area starting at S2 with its byte-length in L3. The value in L4 is set to 0.
0005	0001	A pure double-byte CCSID1 was specified and either: ST1=0 and L1 is odd, or ST1=1 and an orphan byte was found.
0005	0004	ES of CCSID1 is X'1301', and a malformed string--an odd number of bytes between SO, SI bracket--was encountered.
0005	0005	A null-terminated input string was specified using ST1=1; however, there was no null-termination character in S1 within the length L1 specified.
0005	0006	A null-terminated output string was specified using ST2=1; however, the output string contains one or more characters matching the null-termination character, resulting from using the selected conversion tables and methods.
0005	0007	A SPACE-padded output string was specified using ST2=2; however, the definition for SPACE character could not be obtained. The CCSID resource definition did not have an entry for SPACE character definition, or the CCSID resource definition could not be found.
0005	0008	A pure double-byte CCSID2 with ST2=1 was specified, and an odd value was specified for length L2 of the output buffer. The convert function returns only an even number of bytes (maximum L2-1 bytes), including the null-termination character in S2.
0005	0009	A pure double-byte CCSID2 with ST2=2 (SPACE-padded string) was specified, and an odd value was specified for length L2 of the output buffer. The convert function returns L2-1 bytes, including the SPACE-padding characters, in S2.
0005	000C	ES of CCSID1 is X'1301', and a trailing SI bracket is missing.
0005	000D	ES of CCSID1 is X'1301', and a trailing SI code point was encountered without first encountering its corresponding leading SO code point (the number of intervening code points may have been odd or even; the code points would have been treated as single-byte code points because the leading SO was missing).
0006	0001	The selection table (GCCST) was not found.
0006	0002	A CDRA resource is currently unavailable.
0006	0003	The conversion method identified in the GCCST for the specified selection is currently unavailable.
0006	0004	A conversion table identified in the GCCST for the specified selection is not found.
0007	0001	The system GCCST resource accessed by the function is found to be invalid in structure.
0007	0002	The system GCCT resource accessed by the function is found to be invalid in structure.
0007	0003	The table type of GCCT does not match the method selected from GCCST.
0008	0001	CCSID1 value is not in the range 0 to 65,535.
0008	0002	CCSID2 value is not in the range 0 to 65,535.
0008	0003	ST1 value is not in the range 0 to 255.
0008	0004	ST2 value is not in the range 0 to 255.
0008	0005	L1 is outside the range permitted by this implementation.
0008	0006	L2 is outside the range permitted by this implementation.
0008	0007	GCCASN is not in the range 0 to 255.
0100	0001	One or more input graphic characters were replaced with a "SUB" character specified for the output string.
0100	0002	The conversion specified resulted in character mismatches graphic character(s) in CCSID2.

Usage Notes

Some of the above status and reason code values are possible only when the method selected and the tables used have the capabilities to indicate that a character replacement has occurred (using shadow flags or other equivalent means) or that a substitution with a SUB character was done.
When CDRCVRT terminates with a feedback code indicating that the area allocated for output was insufficient, it is the responsibility of the caller to ensure that the remaining portion of the input string is semantically correct prior to making a subsequent call to complete the conversion. For example, in the case of input data with an encoding scheme of X'1301' (mixed host SB/DB encoding), an SI is added at the end of the truncated output string if required; however, no alteration is made to the input string. If a subsequent call is made with the remainder of the input string, the function terminates unsuccessfully and an SI is encountered without a leading SO.
When the encoding associated with a CCSID is such that all graphic character code points are a fixed number of bytes (for example, two for pure double-byte), the assumption is that there are no characters (control or graphic) with a code point width different from that called for by the encoding scheme (other than the termination characters appropriate for the specified input string type) in the input string. The caller is responsible for filtering out any characters or sequences before calling the function.

API introduced: V2R2

Top | National Language Support APIs | APIs by category