CEESTXF—Transform string characters into collation weights
CEESTXF, which is analogous to the C language function strcfrm(), transforms every character in a character string to its unique collation weight. The collation weights are established from the LC_COLLATE category for the locale. CEESTFX also returns the length of the transformed string. CEESTXF is sensitive to the locales set by setlocale() or CEESETL, not to the Language Environment settings from COUNTRY or CEE3CTY.
Syntax >>-CEESTXF--(--omitted_parm--,--mbstring--,--number--,----------> >--txfstring--,--length--,--fc--)------------------------------><
- omitted_parm
- This parameter is reserved for future expansion and must be omitted. For information about how to code an omitted parm, see Invoking callable services.
- mbstring (input)
- A halfword length-prefixed character string (VSTRING) that is to be transformed.
- number (input)
- A 4-byte integer that specifies the number of bytes of mbstring to be transformed. The value of this parameter must be greater than zero; otherwise, an error is reported, and no transformation is attempted.
- txfstring (output)
- A halfword length-prefixed character string (VSTRING) where the transformation of mbstring is to be placed.
- length (output)
- A 4-byte integer that specifies the length of the transformed string, if successful.
- fc (output)
- A 12-byte feedback code, optional in some languages,
that indicates the result of this service. If you choose to omit this
parameter, refer to Invoking callable services for the
appropriate syntax to indicate that the feedback code was omitted.
The following symbolic conditions can result from this service:
Code Severity Message number Message text CEE000 0 — The service completed successfully. CEE3T1 3 4001 General Failure: Service could not be completed. CEE3TF 3 4015 Input Error: The number of characters to be transformed must be greater than zero.
Usage notes
- PL/I MTF consideration—CEESETL is not supported in PL/I MTF applications.
- This callable service uses the C/C++ runtime library. The C/C++ library must be installed and accessible even when this service is called from a non-C program.
For more information
- For more information about the setlocale() ,see COUNTRY, CEE3CTY—Set default country, and CEE3LNG—Set national language.
- For more information about the CEESETL callable service, see CEESETL—Set locale operating environment.
Examples
- Following is an example of CEESTXF called by COBOL.
CBL LIB,QUOTE *Module/File Name: IGZTSTXF ************************************************* * Example for callable service CEESTXF * * COBSTXF - Query current collate category and * * build input string as function of * * locale name. * * Translate string as function of * * locale. * * Valid only for COBOL for MVS & VM Release 2 * * or later. * ************************************************* IDENTIFICATION DIVISION. PROGRAM-ID. COBSTXF. DATA DIVISION. WORKING-STORAGE SECTION. 01 MBS. 02 MBS-Length PIC S9(4) BINARY. 02 MBS-String PIC X(10). 01 TXF. 02 TXF-Length PIC S9(4) BINARY. 02 TXF-String PIC X(256). 01 Locale-Name. 02 LN-Length PIC S9(4) BINARY. 02 LN-String PIC X(256). * Use Locale category constants COPY CEEIGZLC. 01 MBS-Size PIC S9(9) BINARY VALUE 0. 01 TXF-Size PIC S9(9) BINARY VALUE 0. 01 FC. 02 Condition-Token-Value. COPY CEEIGZCT. 03 Case-1-Condition-ID. 04 Severity PIC S9(4) BINARY. 04 Msg-No PIC S9(4) BINARY. 03 Case-2-Condition-ID REDEFINES Case-1-Condition-ID. 04 Class-Code PIC S9(4) BINARY. 04 Cause-Code PIC S9(4) BINARY. 03 Case-Sev-Ctl PIC X. 03 Facility-ID PIC XXX. 02 I-S-Info PIC S9(9) BINARY. PROCEDURE DIVISION. ************************************************* * Call CEEQRYL to retrieve locale name ************************************************* CALL "CEEQRYL" USING LC-COLLATE, Locale-Name, FC. ************************************************* * Check feedback code and set input string ************************************************* IF Severity = 0 IF LN-String (1:LN-Length) = "Sv-SE.IBM-1047" MOVE 10 TO MBS-Length MOVE 10 TO MBS-Size MOVE "7,123,456." TO MBS-String (1:MBS-Length) ELSE MOVE 7 TO MBS-Length MOVE 7 TO MBS-Size MOVE "8765432" TO MBS-String (1:MBS-Length) END-IF ELSE DISPLAY "Call to CEEQRYL failed. " Msg-No STOP RUN END-IF. MOVE SPACES TO TXF-String. MOVE 0 to TXF-Length. ************************************************* * Call CEESTXF to translate the string ************************************************* CALL "CEESTXF" USING OMITTED, MBS, MBS-Size, TXF, TXF-Size, FC. ************************************************* * Check feedback code and return length ************************************************* IF Severity = 0 IF TXF-Length > 0 DISPLAY "Translated string is " TXF-String ELSE DISPLAY "String not translated." END-IF ELSE DISPLAY "Call to CEESTXF failed. " Msg-No END-IF. STOP RUN. END PROGRAM COBSTXF. - Following is an example of CEESTXF called by PL/I.
*PROCESS MACRO; /*Module/File Name: IBMSTXF */ /****************************************************/ /* Example for callable service CEESTXF */ /* Function: Query current collate category and */ /* build input string as function of locale name. */ /* Translate string as function of locale. */ /****************************************************/ PLISTXF: PROC OPTIONS(MAIN); %INCLUDE CEEIBMAW; /* ENTRY defs, macro defs */ %INCLUDE CEEIBMCT; /* FBCHECK macro, FB constants */ %INCLUDE CEEIBMLC; /* Locale category constants */ /* CEESTXF service call arguments */ DCL MBSTRING CHAR(10) VARYING; /* input string */ DCL MBNUMBER BIN FIXED(31); /* input length */ DCL TXFSTRING CHAR(256) VARYING; /* output string */ DCL TXFLENGTH BIN FIXED(31); /* output length */ /* CEEQRYL service call arguments */ DCL LOCALE_NAME_COLLATE CHAR(256) VARYING; DCL 01 FC, /* Feedback token */ 03 MsgSev REAL FIXED BINARY(15,0), 03 MsgNo REAL FIXED BINARY(15,0), 03 Flags, 05 Case BIT(2), 05 Severity BIT(3), 05 Control BIT(3), 03 FacID CHAR(3), /* Facility ID */ 03 ISI /* Instance-Specific Information */ REAL FIXED BINARY(31,0); /* retrieve active locale for collate category */ /* Use LC_COLLATE category const from CEEIBMLC */ CALL CEEQRYL ( LC_COLLATE, LOCALE_NAME_COLLATE, FC); /* FBCHECK macro used (defined in CEEIBMCT) */ IF FBCHECK( FC, CEE000 ) THEN DO; /* successful query, set string for CEESTXF */ IF LOCALE_NAME_COLLATE = 'Sv_SE.IBM-1047' THEN MBSTRING = '7,123,456.'; ELSE MBSTRING = '8765432'; MBNUMBER = LENGTH(MBSTRING); END; ELSE DO; DISPLAY ( 'Locale LC_COLLATE '||FC.MsgNo ); STOP; END; TXFSTRING = '; CALL CEESTXF ( *, MBSTRING, MBNUMBER, TXFSTRING, TXFLENGTH, FC ); IF FBCHECK( FC, CEE000 ) THEN DO; /* successful call, use transformed length */ IF TXFLENGTH >0 THEN DO; PUT SKIP LIST( 'Transformed string is '|| SUBSTR(TXFSTRING,1, TXFLENGTH) ); END; END; ELSE DO; IF FBCHECK( FC, CEE3TF ) THEN DO; DISPLAY ( 'Zero length input string' ); END; END; END PLISTXF;