The CCSTOCCS_TRANS_TEXT_COMPLEX procedure is an advanced character mapping operation that supports the complex translation requirements of mixed, multibyte and 16-bit coded character sets, as well as the standard 8-bit coded character sets.
Unlike the standard 8-bit mapping procedures of the CENTRALSUPPORT library, the multibyte character mappings handled by this procedure can be done only within the CCSTOCCS_TRANS_TEXT_COMPLEX procedure in the CENTRALSUPPORT library. No multibyte translate tables are available to calling programs.
The CCSTOCCS_TRANS_TEXT_COMPLEX procedure maintains a STATE array so that mappings can be spread over multiple calls. The procedure also includes an OPTION parameter that controls how error recovery is handled and how mappings are terminated.
Example
The following example takes a string encoded in the UCS2NT coded character set and translates the string to the ASERIESEBCDIC coded character set. Refer to the MultiLingual System Administration, Operations, and Programming Guide to determine the coded character set numbers. For instance, the coded character set number for UCS2NT is 84 and the coded character set number for ASERIESEBCDIC is 4. These numbers can also be retrieved by calling VALIDATE_NAME_RETURN_NUM with the coded character set names.
The string Complex is represented by hexadecimal codes 43006F006D0070006C0065007800 in the UCS2NT coded character set. When translated to the ASERIESEBCDIC coded character set, the string displays as Complex in the output file.
BEGIN
$ INCLUDE INTL="SYMBOL/INTL/ALGOL/PROPERTIES." 10000000-49999999
FILE OUT(KIND=DISK,UNITS=CHARACTERS,FILEUSE=IO,FILETYPE=0,NEWFILE,
MAXRECSIZE=80,TITLE="OUT/ALGOL/CCSTOCCS_COMPLEX.");
EBCDIC ARRAY SOURCE[0:19]
,DEST[0:19];
REAL ARRAY STATE[0:9];
INTEGER CCSNUMFROM
,CCSNUMTO
,SOURCE_START
,SOURCE_BYTES
,DEST_START
,DEST_BYTES
,OPTION
,RESULT;
CCSNUMFROM := 84; % UCS2NT
CCSNUMTO := 4; % ASERIESEBCDIC
SOURCE_START := 0;
SOURCE_BYTES := 14;
DEST_START := 0;
DEST_BYTES := 10;
OPTION := CS_OPT_INITIAL_COMPLETEV;
REPLACE SOURCE[0] BY 48"43006F006D0070006C0065007800";
RESULT := CCSTOCCS_TRANS_TEXT_COMPLEX(CCSNUMFROM, CCSNUMTO, SOURCE,
SOURCE_START, SOURCE_BYTES, DEST, DEST_START, DEST_BYTES,
STATE, OPTION);
WRITE(OUT,<"RESULT = ",J4>, RESULT);
IF RESULT EQL CS_DATAOKV THEN
WRITE(OUT, <"DEST = ",A7>, DEST);
CLOSE(OUT,LOCK);
END. | Note: | SOURCE_INX and DEST_INX are not used twice to offset into the arrays. The pointer version of the Complex procedure ignores the SOURCE_INX and DEST_INX parameters on input to the procedure. On output to the procedure, the SOURCE_INX parameter is incremented by the amount of source consumed and the DEST_INX parameter is incremented by the amount of data mapped into the destination. |
Output
RESULT = 1 DEST = Complex
In the preceding call, the parameters have the following meanings:
-
CCSNUMFROM is the library number of the source CCS.
-
CCSNUMTO is the library number of the destination CCS.
-
SOURCE contains the characters to be mapped. The maximum is 64,000 words.
-
SOURCE_START specifies the byte offset (0 relative) where the mapping in SOURCE starts. SOURCE_START is ignored on input by the _PTR version. The output marks the offset to where the mapping ended.
-
SOURCE_BYTES is the number of bytes to be mapped beginning at the SOURCE_INX. The value of SOURCE_BYTES + SOURCE_INX must be equal to the value of LEQ_SIZE (SOURCE).
-
DEST contains the mapped text. The size of this record might need to be larger than the record in SOURCE-TEXT. Using a record that is twice the size of the source always works.
-
DEST_START specifies the byte offset (0 relative) where the mapped text is stored in DEST. DEST_START is ignored on input by the _PTR version. The output marks the offset where the mapped text ends.
-
DEST_BYTES is the maximum number of bytes beginning at DEST_INX that can be filled with destination characters. The value of DEST_BYTES + DEST_INX must be equal to the value of LEQ_SIZE (DEST).
-
STATE is a real array that is ten words long. STATE is owned, but untouched by, the caller. The following descriptions are for words 0-9:
Word
Description
Word 0
Indices to CENTRALSUPPORT tables
Word 1
Previous-operation status information
Word 2
Partial source character
Word 3
Special case optimization information
Words 4–9
Reserved
-
OPTION indicates whether this is a continuation call. Following are the values and their meanings:
Value
Meaning
0
CS_OPT_INITIAL_COMPLETEV is the first call for a combination of source and destination coded character sets. The source data stream is complete and the data is mapped in one call.
5
CS_OPT_COMPLETEV is the beginning of a new source data stream, but NOT the first call for this combination of source and destination coded character sets. The source data stream is complete and the data is mapped in one call.
2
CS_OPT_INITIAL_HEADV is the first call for a combination of source and destination coded character sets. The source data is incomplete or the destination is not large enough to hold all of the data in one call.
7
CS_OPT_HEADV is the beginning of a new source data stream; it is not the first call for this combination of source and destination coded character sets. The source data stream is incomplete or the destination is not large enough to hold all of the data in one call.
3
CS_OPT_MIDDLEV is the second or higher call for a source data stream; it is not the last call.
1
CS_OPT_TAILV is the second or higher call for a source data stream and it is the last call.
The CCSTOCCS_TRANS_TEXT_COMPLEX procedure can return the following values:
|
CS_ARRAY_TOO_SMALLV (3001) |
CS_FILE_ACCESS_ERRORV (1000) |
|
CS_BAD_ARRAY_DESCRIPTIONV (3000) |
CS_FAULTV (1001) |
|
CS_BAD_DATA_LENV (3002) |
CS_INCOMPLETE_CHARV (2005) |
|
CS_DATA_NOT_FOUNDV (4002) |
CS_INCOMPLETE_DATAV (2004) |
|
CS_DATAOKV (1) |
CS_SOFTERRV (1002) |
