CEESETL—Set locale operating environment

CEESETL, analogous to the C language function setlocale(), establishes a global locale operating environment, which determines the behavior of character collation, character classification, date and time formatting, numeric punctuation, and positive/negative response patterns. CEESETL is sensitive to the locales set by setlocale() or CEESETL, not to the Language Environment settings from COUNTRY or CEE3CTY.


Syntax

>>-CEESETL--(--localename--,--category--,--fc--)---------------><

localename (input)

A halfword length-prefixed character string (VSTRING) with a maximum of 256 bytes. localename is a valid locale name known to the locale model. The category named in the call is set according to the named locale. If localename is null or blank, CEESETL sets the locale environment according to the environment variables. This is the equivalent to specifying setlocale(LC_ALL,""). If these environment variables are defined, you can locate them in the following order:

LC_ALL if it is defined and not null
LANG if it is defined and not null
The default C locale

category (input)

A symbolic integer number that represents all or part of the locale for a program. Depending on the value of the localename, these categories can be initiated by the values of global categories of corresponding names. The following values for the category parameter are valid:

LC_ALL: A 4-byte integer (with a value of -1) that affects all locale categories associated with a program's locale.
LC_COLLATE: A 4-byte integer (with a value of 0) that affects the behavior of regular expression and collation subroutines.
LC_CTYPE: A 4-byte integer (with a value of 1) that affects the behavior of regular expression, character classification, case conversion, and wide character subroutines.
LC_MESSAGES: A 4-byte integer (with a value of 6) that affects the format and values for positive and negative responses.
LC_MONETARY: A 4-byte integer (with a value of 3) that affects the behavior of subroutines that format monetary values.
LC_NUMERIC: A 4-byte integer (with a value of 2) that affects the behavior of subroutines that format non-monetary numeric values.
LC_TIME: A 4-byte integer (with a value of 4) that affects the behavior of time conversion subroutines.

Language Environment locale callable services do not support the LC_TOD and LC_SYNTAX categories.

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.
CEE2KD	3	2701	An invalid category parameter was passed to a locale function.
CEE2KE	3	2702	An invalid locale name parameter was passed to a locale function.
CEE3T1	3	4001	General Failure: Service could not be completed.

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.
The LC_ALL category indicates that all categories are to be changed with regard to the specific locale. The LC_ALL value, when set by CEESETL, becomes the current values for all six LC_* categories.
If the active locale is not explicitly set with CEESETL or setlocale(category, localename), then the locale chosen is as follows:
- With POSIX(OFF), the SAA C locale is chosen, and querying the locale with CEEQRYL returns "C" as the locale name.
- With POSIX(ON), the POSIX C locale is chosen, and querying the locale with CEEQRYL returns "POSIX" as the locale name.
The SAA C locale provides compatibility with previous releases of C/370. The POSIX C locale provides consistency with POSIX requirements and supports the z/OS UNIX environment.

For more information

See z/OS XL C/C++ Runtime Library Reference for details of how various locale categories affect C/C++ language functions.
For more information about specifying environment variables to set the locale, see z/OS XL C/C++ Programming Guide.
For information about the definition of the SAA C and POSIX C locales and the differences between them, see z/OS XL C/C++ Programming Guide.
For more information about LC_TIME, see CEEQDTC—Query locale date and time conventions.

Examples

Following is an example of CEESETL called by COBOL.

       CBL LIB,QUOTE
      *Module/File Name: IGZTSETL
      *************************************************
      *  Example for callable service CEESETL         *
      *   COBSETL - Set all global locale environment *
      *              categories to country Sweden.    *
      *             Query one category.               *
      *************************************************
       IDENTIFICATION DIVISION.
       PROGRAM-ID.  COBSETL.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  Locale-Name.
           02  LN-Length  PIC S9(4) BINARY.
           02  LN-String  PIC X(256).
       01  Locale-Time.
           02  LT-Length  PIC S9(4) BINARY.
           02  LT-String  PIC X(256).
      * Use Locale category constants
       COPY CEEIGZLC.
      *
       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 locale name for Sweden
      *************************************************
           MOVE 14 TO LN-Length.
           MOVE 'Sv_SE.IBM-1047'
                   TO LN-String (1:LN-Length).

      *************************************************
      *  Set all locale categories to Sweden
      *  Use LC-ALL category constant from CEEIGZLC
      *************************************************
           CALL 'CEESETL' USING Locale-Name, LC-ALL,
                                FC.

      *************************************************
      *  Check feedback code
      *************************************************
           IF Severity > 0
              DISPLAY 'Call to CEESETL failed. ' Msg-No
              STOP RUN
           END-IF.  
      *************************************************
      *  Retrieve active locale for LC-TIME category
      *************************************************
           CALL 'CEEQRYL' USING LC-TIME, Locale-Time,
                                FC.

      *************************************************
      *  Check feedback code and correct locale
      *************************************************
           IF Severity = 0
              IF LT-String(1:LT-Length) =
                      LN-String(1:LN-Length)
                 DISPLAY 'Successful query.'
              ELSE
                 DISPLAY 'Unsuccessful query.'
              END-IF
           ELSE
              DISPLAY 'Call to CEEQRYL failed. ' Msg-No
           END-IF.

           STOP RUN.
       END PROGRAM COBSETL.

Following is an example of CEESETL called by COBOL.

*PROCESS MACRO;
 /*Module/File Name: IBMSETL                         */
 /****************************************************/
 /* Example for callable service CEESETL             */
 /* Function: Set all global locale environment      */
 /*  categories to country. Query one category.      */
 /****************************************************/

 PLISETL: PROC OPTIONS(MAIN);

 %INCLUDE CEEIBMAW; /* ENTRY defs, macro defs        */
 %INCLUDE CEEIBMCT; /* FBCHECK macro, FB constants   */
 %INCLUDE CEEIBMLC; /* Locale category constants     */

 /* CEESETL service call arguments */
 DCL LOCALE_NAME CHAR(14) VARYING;

 /* CEEQRYL service call arguments */
 DCL LOCALE_NAME_TIME 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);
   /* init locale name with IBM default for Sweden  */
   LOCALE_NAME = 'Sv_SE.IBM-1047';

   /* use LC_ALL category const from CEEIBMLC */
   CALL CEESETL ( LOCALE_NAME, LC_ALL, FC );

   /* FBCHECK macro used (defined in CEEIBMCT) */
   IF FBCHECK( FC, CEE2KE ) THEN
     DO;  /* invalid locale name */
       DISPLAY ( 'Locale LC_ALL Call '||FC.MsgNo );
       STOP;
     END;

   /* retrieve active locale for LC_TIME category */
   /* use LC_TIME category const from CEEIBMLC */
   CALL CEEQRYL ( LC_TIME, LOCALE_NAME_TIME, FC );

   IF FBCHECK( FC, CEE000 ) THEN
     DO;  /* successful query, check category name */
       IF LOCALE_NAME_TIME ¬= LOCALE_NAME THEN
         DO;
           DISPLAY ( 'Invalid LOCALE_NAME_TIME ' );
           STOP;
         END;
       ELSE
         DO;
           PUT SKIP LIST('Successful query LC_TIME',
                          LOCALE_NAME_TIME);
         END;
     END;
   ELSE
     DO;
       DISPLAY ( 'LC_TIME Category Call '||FC.MsgNo );
       STOP;
     END;

 END PLISETL;