CEESCOL—Compare collation weight of two strings
CEESCOL, which is analogous to the C language function strcoll(), compares two character strings based on the collating sequence specified in the LC_COLLATE category of the current locale. CEESCOL associates a collation weight with every character in the code set for the locale. The characters in the input strings are converted to their collation weights and then compared on the basis of these weights. CEESCOL is sensitive to the locales set by setlocale() or CEESETL, not to the Language Environment settings from COUNTRY or CEE3CTY.
Syntax >>-CEESCOL--(--omitted_parm--,--string1--,--string2--,----------> >--result--,--fc--)--------------------------------------------><
- omitted_parm
- This parameter is reserved for future expansion and must be omitted. For information about how to code an omitted parameter, see Invoking callable services.
- string1 (input)
- A halfword length-prefixed character string (VSTRING) with a maximum length of 4K bytes. string1 points to a string of characters that are to be compared against string2 .
- string2 (input)
- A halfword length-prefixed character string (VSTRING) with a maximum length of 4K bytes. string2 points to a string of characters that string1 is compared against.
- result (output)
- Specifies the result of the string comparison. If successful,
the following values are returned:
- Less than 0, if string1 is less than string2
- Equal to 0, if string1 is equal to string2
- Greater than 0, if string1 is greater than string2
- 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.
Usage notes
- PL/I MTF consideration—CEESCOL 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
- See CEESETL—Set locale operating environment for more information about the CEESETL callable service.
Examples
- Following is an example of CEESCOL called by COBOL.
CBL LIB,QUOTE *Module/File Name: IGZTSCOL ************************************************* * Example for callable service CEESCOL * * COBSCOL - Compare two character strings * * and print the result. * * Valid only for COBOL for MVS & VM Release 2 * * or later. * ************************************************* IDENTIFICATION DIVISION. PROGRAM-ID. COBSCOL. DATA DIVISION. WORKING-STORAGE SECTION. 01 String1. 02 Str1-Length PIC S9(4) BINARY. 02 Str1-String. 03 Str1-Char PIC X OCCURS 0 TO 256 TIMES DEPENDING ON Str1-Length. 01 String2. 02 Str2-Length PIC S9(4) BINARY. 02 Str2-String. 03 Str2-Char PIC X OCCURS 0 TO 256 TIMES DEPENDING ON Str2-Length. 01 Result PIC S9(9) BINARY. 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. ************************************************* * Set up two strings for comparison ************************************************* MOVE 9 TO Str1-Length. MOVE "12345a789" TO Str1-String (1:Str1-Length) MOVE 9 TO Str2-Length. MOVE "12346$789" TO Str2-String (1:Str2-Length) ************************************************* * Call CEESCOL to compare the strings ************************************************* CALL "CEESCOL" USING OMITTED, String1, String2, Result, FC. ************************************************* * Check feedback code ************************************************* IF Severity > 0 DISPLAY "Call to CEESCOL failed. " Msg-No STOP RUN END-IF. ************************************************* * Check result of compare ************************************************* EVALUATE TRUE WHEN Result < 0 DISPLAY "1st string < 2nd string." WHEN Result > 0 DISPLAY "1st string > 2nd string." WHEN OTHER DISPLAY "Strings are identical." END-EVALUATE. STOP RUN. END PROGRAM COBSCOL. - Following is an example of CEESCOL called by PL/I.
*PROCESS MACRO; /*Module/File Name: IBMSCOL */ /****************************************************/ /* Example for callable service CEESCOL */ /* Function: Compare two character strings and */ /* print the result. */ /****************************************************/ PLISCOL: PROC OPTIONS(MAIN); %INCLUDE CEEIBMAW; /* ENTRY defs, macro defs for Language Environment */ %INCLUDE CEEIBMCT; /* FBCHECK macro, FB constants */ %INCLUDE CEEIBMLC; /* Locale category constants */ /* CEESCOL service call arguments */ DCL STRING1 CHAR(256) VARYING;/* first string */ DCL STRING2 CHAR(256) VARYING;/* second string */ DCL RESULT_SCOL BIN FIXED(31);/* result of compare */ 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); STRING1 = '12345a789'; STRING2 = '12346$789'; CALL CEESCOL( *, STRING1, STRING2, RESULT_SCOL,FC); /* FBCHECK macor used (defined in CEEIBMCT) */ IF FBCHECK( FC, CEE3T1 ) THEN DO; DISPLAY ('CEESCOL not completed '||FC.MsgNo ); STOP; END; SELECT; WHEN( RESULT_SCOL < 0 ) PUT SKIP LIST( '"firststring" is less than "secondstring" '); WHEN( RESULT_SCOL > 0 ) PUT SKIP LIST( '"firststring" is greater than "secondstring" '); OTHERWISE PUT SKIP LIST( 'Strings are identical' ); END; /* END SELECT */ END PLISCOL;