Customizing a locale

This topic describes how you can create your own locales, based on the locale definition files supplied by IBM®. See Locales supplied with z/OS XL C/C++ for more information on the compiled locales and locale source files. The information in this topic applies to the format of locales based on the localedef utility.

The following example assumes that the target of the generated locale will be a data set, but locales may also reside in a z/OS® UNIX file system (see Locale naming conventions for differences in object names). In this example you will build a locale named TEXAN using the charmap file representing the IBM-1047 encoded character set. The locale is derived from the locale representing the English language and the cultural conventions of the United States. We will assume that non-XPLINK, XPLINK, and AMODE 64 applications will use the TEXAN locale. All three versions of the TEXAN locale will be generated.

1. See Locale source files to determine the source of the locale you are going to use. In this case, it is the English language in the United States locale, the source for which is the member EDC$EUEY of the PDS CEE.SCEELOCX.
2. Copy the member EDC$EUEY from PDS CEE.SCEELOCX to the data set hlq.LOCALE.SOURCE which has been pre-allocated with the same attributes as CEE.SCEELOCX.
3. In your new file, change the locale variables to the desired values. For example, change

   d_t_fmt "%a %b %e %H:%M:%S %Z %Y

   to

   d_t_fmt "Howdy Pardner %a %b %e %H:%M:%S %Z %Y"

4. This locale's Language-Territory value is TEXAN. The Codeset value is IBM-1047. TEXAN is not a valid PDS resident locale name in the runtime library, because it does not appear in the runtime Locale Name Table. You must modify the table to include the TEXAN locale. Here are the steps to follow.
   1. Copy the member EDC$LCNM from PDS CEE.SCEESAMP to the data set hlq.LOCALE.TABLE which has been pre-allocated with the same attributes as CEE.SCEESAMP. The z/OS XL C/C++ Library uses this table to map locale code registry prefixes into two-character codes.
   2. For this example, insert a new line into the assembler table before the last EDCLOCNM TYPE=END entry:

      EDCLOCNM TYPE=ENTRY,LOCALE='TEXAN',CODESET='IBM-1047',CODE='1T'

5. Now that your locale name table has been modified, you must make it available to the system. Assemble the EDC$LCNM member and link-edit it into the hlq.LOCALE.LOADLIB load library with the member name EDC$LCNM. For our example, this is done as follows:

       //HLASM    EXEC PGM=ASMA90
       //SYSPRINT DD SYSOUT=*
       //SYSLIB   DD DSN=SYS1.MACLIB,DISP=SHR
       //         DD DSN=CEE.SCEEMAC,DISP=SHR
       //SYSUT1   DD UNIT=VIO,DISP=(NEW,DELETE),SPACE=(32000,(30,30))
       //SYSUT2   DD UNIT=VIO,DISP=(NEW,DELETE),SPACE=(32000,(30,30))
       //SYSUT3   DD UNIT=VIO,DISP=(NEW,DELETE),SPACE=(32000,(30,30))
       //SYSPUNCH DD DUMMY
       //SYSLIN   DD DSN=<hlq>.LOCALE.OBJECT(EDC$LCNM),DISP=SHR
       //SYSIN    DD DSN=<hlq>.LOCALE.TABLE(EDC$LCNM),DISP=SHR
       //*
       //LKED     EXEC   EDCL,
       //         OUTFILE='<hlq>.LOCALE.LOADLIB(EDC$LCNM),DISP=SHR'
       //LKED.SYSLIN  DD DSN=<hlq>.LOCALE.OBJECT(EDC$LCNM),DISP=SHR

6. Generate the non-XPLINK, XPLINKand 64–bit locale objects into a load library. Note that both the XPLINK and 64–bit locale objects must be placed in a PDSE, while non-XPLINK locale objects may be in either a PDS or PDSE load library.
   1. Determine the correct locale object names, using the locale naming Conventions outlined in Locale naming conventions. PDS resident locale object names are of the form prefixLTCC .

      For this non-XPLINK locale the prefix is EDC$, the LT code for TEXAN is 1T and the CC code for IBM-1047 is EY. The non-XPLINK object name is therefore EDC$1TEY.

      For this XPLINK locale the prefix is CEH$. The LTand CC codes remain the same. The XPLINK object name is therefore CEH$1TEY.

      For this 64–bit locale the prefix is CEQ$. The LT and CC codes remain the same. The 64–bit locale object name is, therefore, CEQ$1TEY.

   2. Use localedef to generate the locale objects.
      • For non-XPLINK:

        //GENLOCNX EXEC PROC=EDCLDEF,
         // INFILE='hlq.LOCALE.SOURCE(TEXAN)',
         //
         OUTFILE='hlq.LOCALE.LOADLIB(EDC$1TEY),DISP=SHR',
         // LOPT='CHARMAP(IBM-1047)'

      • For XPLINK:

        //GENLOCX EXEC PROC=EDCXLDEF,
         // INFILE='hlq.LOCALE.SOURCE(TEXAN)',
         //
         OUTFILE='hlq.LOCALE.PDSE.LOADLIB(CEH$1TEY),DISP=SHR',
         // LOPT='CHARMAP(IBM-1047)'

      • For 64–bit

        The batch and TSO versions of the localedef utility cannot be used to generate 64–bit locales. The UNIX Systems Services utility must be used. To do this from TSO or batch the BPXBATCH utility can be used. See z/OS UNIX System Services Command Reference for more information about BPXBATCH. Here, we will assume we are in a UNIX System Services shell session:

        cp "//'hlq.LOCALE.SOURCE(TEXAN)'" texan.localedef
        localedef -6 -i texan.localedef -f /usr/lib/nls/charmap/IBM-1047
                        TEXAN.IBM-1047.lp64
        cp TEXAN.IBM-1047.lp64 "//'hlq.LOCALE.PDSE.LOADLIB(CEQ$1TEY)'"

   See z/OS XL C/C++ User's Guide for detailed information about the batch and TSO versions of localedef utility. The UNIX System Services version of the localedef utility is also described in z/OS UNIX System Services Command Reference.

   Note: The TEXAN locale uses one of the IBM supplied CHARMAPs. If you need to customize a CHARMAP, then you must define its two-letter CC code in the Codeset Name table EDCUCSNM. This is similar to defining the locale TEXAN in EDC$LCNM. The two-letter CHARMAP codes beginning with a number are reserved for customer use. This is the same as the convention for customer-supplied Locale Name LT codes in the Locale Name table. The CC portion of your locale object names would then change to be the new CC value you added to the Codeset Name table.