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 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:

  1. The values 0 and 1 are treated the same.

  2. Character Data Representation, SC09-1391, contains the CDRA-defined default conversion tables. This manual is not available online, but can be ordered from the IBM® Publications CenterLink outside information 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

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

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

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

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