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