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.
- the string to be converted when ST1=0 or
- 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 manual is not available online,
but can be ordered from the
IBM® Publications Center
.
- The values 0 and 1 are treated the same.
- 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:
|
| 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
[ Back to top | National Language Support APIs | APIs by category ]