gtpa2m45Application Programming

Optional Customizations

This section includes a description of optional customizations.

Creating and Selecting Locales

This section describes the different types of locales.

What is a Locale?

A C locale consists of a set of constants that depend on geographic area. The constants affect the action of certain library functions (such as the string collation function strcoll) and control:

Note:
Time information is dependent on the system clock setting, which is assumed to be set to Greenwich Mean Time (GMT). If you set the system clock to something other than GMT, see TPF System Generation for details on how to customize the clock value.

The setlocale function selects the appropriate portion of the program's locale. It can be used to change or query the program's entire current locale, or portions of it.

The basic format of the function is:

    setlocale(category, locale)

where category specifies which attributes of the locale you want to change or query, and locale identifies the locale itself (as in LC_C_GERMANY, LC_C_SPAIN, and so on). If you specify "" for locale, the setlocale function will default the locale to LC_DEFAULT_LOCALE.

When the first C program for a given ECB is activated, the equivalent of

    setlocale(LC_ALL, "C");

has been performed. A value of C for the locale specifies the minimal environment for C translation. The program can then call the setlocale function if a different locale is desired.

The setlocale function is described in more detail in the library reference for the IBM C or C++ compiler on the System/390 platform used by your installation.

In ISO-C the C locale supplied by IBM is in C$S370 which is linked in library CISO. All the other shipped locales are in DLMs:

Locale Source DLM
LC_C_GERMANY CLLGER CLLG
LC_C_FRANCE CLLFRN CLLF
LC_C_UK CLLENG CLLE
LC_C_ITALY CLLITL CLLI
LC_C_SPAIN CLLSPA CLLS
LC_C_USA CLLUSA CLLU
LC_C_TPF CLLTPF CLLT

These locales are defined by calling the EDCLOC macro. All of the shipped locales specify a TZDIFF value of 1500 (that is, use the system time zone difference). The TPF system time zone difference is defined in keypoint record A at tag CK1LGD. In order for the standard C time formatting functions to use this value you must define the appropriate time zone name (TNAME). To handle daylight savings time you must also specify the following EDCLOC parameters: DSTSTM, DSTSTW, DSTSTD, STARTTM, SHIFT, DSTENM, DSTENW, DSTEND, ENDTM, and DSTNAME.

For TARGET(TPF), all of the locales are defined in CP segment CL04 (CCLANG). For TARGET(TPF) the absolute value of TZDIFF must not exceed 1440 (minutes, that is 24 hours). System time zone differences are not supported for TARGET(TPF). All of the TARGET(TPF) locales specify a TDZIFF value of -300 for North American eastern standard time. You should modify these locales as appropriate for your installation.

Creating a New ISO-C Locale

You can create a new locale, or modify an existing one, by specifying a new set of parameters to the assembler macro EDCLOC. Edit the locale source file (xxx) and change the EDCLOC parameters to make small changes in a default locale. New locales are created by:

After the new DLM is loaded online, the new values in the new locale are available to the functions setlocale and localeconv.

For example, suppose we wanted to set up a new locale for the North Pole. The locale definition could be as in Figure 50. At the North Pole we might find that every day is Saturday and that every month is December.

Figure 50. Assembler Program for a New Locale

***********************************************************************
* MODULE NAME: NPOLLC                                                 *
* DESCRIPTION: DEFINITION OF C LOCALE "NPOL" FOR THE NORTH POLE.      *
*                                                                     *
***********************************************************************
NPOL   EDCLOC  CHARTYP=1,CTYPE=,CTYPE1=,UPPER=,LOWER=,COLLTAB=,
               COLLSTR=,DEC='.',SEP=,GROUP=(0,0),ICURR=,CURR=,
               MDEC=,MSEP=,MPLUS=,MMINUS=,
               MIFDIGITS=CHAR_MAX,
               MFDIGITS=CHAR_MAX,MGROUP=(0,0),MPCSP=CHAR_MAX,
               MPSBYS=CHAR_MAX,MNCSP=CHAR_MAX,MNSBS=CHAR_MAX,
               MPLUSPOS=CHAR_MAX,MMINUSPOS=CHAR_MAX,
               SDAYS=(SAT,SAT,SAT,SAT,SAT,SAT,SAT),
               LDAYS=(SATURDAY,SATURDAY,SATURDAY,SATURDAY,SATURDAY,
               SATURDAY,SATURDAY),
               SMONS=(DEC,DEC,DEC,DEC,DEC,DEC,DEC,DEC,DEC,DEC,DEC,
               DEC),
               LMONS=(DECEMBER,DECEMBER,DECEMBER,DECEMBER,DECEMBER,
               DECEMBER,DECEMBER,DECEMBER,DECEMBER,DECEMBER,
               DECEMBER,DECEMBER),
               DATFMT='%m/%d/%y',TIMFMT='%H.%M.%S',AM='AM',PM='PM',
               DATTIM='%m/%d/%y %X',
               TZDIFF=0,TNAME=NPST,
               DSTSTM=0,DSTSTW=0,DSTSTD=0,STARTTM=0,SHIFT=0,
               DSTENM=0,DSTENW=0,DSTEND=0,ENDTM=0,DSTNAME=,
               VERSION=1
 
     END  ,

This assembler program only contains a call to the EDCLOC macro (and END). No calls to the BEGIN or TMSPC macro are required; EDCLOC generates all of the required code.

A build script for the North Pole locale could be

Figure 51. Build Script for a New Locale

#######################################################################
# LOAD MODULE NAME: NPOL                                              #
# DESCRIPTION: North Pole locale "NPOL" definition.                   #
#######################################################################
DLM NPOL41
NPOLLC41

The DLM locale is assembled, built, allocated, and loaded. An application can call

      setlocale(LC_ALL, "NPOL") ;

and all standard library functions that take locale values into account would operate in a manner appropriate to the North Pole.

The parameters for defining a locale are fully described in the user's guide for the IBM C or C++ compiler on the System/390 platform used by your installation. Keep the following in mind when creating a locale for the TARGET(TPF) environment:

See the IBM C or C++ user's guide and programming guide for the IBM System/390 platform used by your installation for a description of the macro parameters used to define a locale.

Creating a New localedef Utility-Based Locale

localedef utility-based locales must co-exist with the existing EDCLOC macro-based locales. The existing EDCLOC locales are coded in the application by their load module name. localedef utility-based locales are coded by their 4-character internal name or the long external name. On the setlocale() function, the locale name is first assumed to be a localedef utility-based locale. If a localedef utility-based locale module is not found mapping to the locale name coded, an attempt will then be made to load it as an existing EDCLOC locale.

Preparing the EDCLDEF JCL Procedure for the TPF System

The EDCLDEF job control language (JCL) procedure provided with the compiler takes a locale definition as input and displays the locale module. For the TPF system, the module needs TPF startup code. You must modify the EDCLDEF JCL procedure to create object code for the locale, and the object code can then be link-edited as a new locale module. Figure 52 shows the EDCLDEF JCL procedure as it is shipped. Figure 53 shows you a sample of the EDCLDEF JCL procedure after it has been modified. In these figures, changes that you must make to the EDCLDEF JCL procedure are shown in a bold example font; for example SYSLBLK='3200'.

You must make the following changes to the EDCLDEF JCL procedure:

Figure 52. An EDCLDEF JCL Procedure as Shipped with the Compiler

//*********************************************************************
//*                                                                   *
//* LICENSED MATERIALS - PROPERTY OF IBM                              *
//*                                                                   *
//* 5647-A01                                                          *
//* (C) COPYRIGHT IBM CORP. 1988, 1997 ALL RIGHTS RESERVED            *
//*                                                                   *
//* US GOVERNMENT USERS RESTRICTED RIGHTS - USE,                      *
//* DUPLICATION OR DISCLOSURE RESTRICTED BY GSA ADP                   *
//* SCHEDULE CONTRACT WITH IBM CORP                                   *
//*                                                                   *
//*********************************************************************
//***********************************************************/
//*    MVS PROGRAM PRODUCTS TEAM                            */
//*                                                         */
//* THE FOLLOWING CHANGES MADE TO CORRECT PROCEDURE	        */
//* 1. VIO CHANGED TO SYSDA                                */
//* 2. LIBPRFX='CEE' TO LIBPREX='SYS1.CEE.V2R4M0'          */
//* 3. LNGPRFX='CBC' TO LNGPRFX='SYS1.CBC.V2R4MO'          */
//*                                                        */
//**********************************************************/
//*********************************************************************
//*                                                                   *
//* INVOKE THE LOCALEDEF UTILITY OT CREATE C SOURCE CODE              *
//* THEN COMPILE AND LIKN EDIT THE PROGRAM                            *
//*                                                                   *
//* OS/390 C/C++                                                      *
//*                                                                   *
//* RELEASE LEVEL:  02.04.00  (VERSION.RELEASE.MODIFICATION LEVEL)    *
//*                                                                   *
//*********************************************************************
//*
//EDCLDEF PROC  INFILE=,                 < INPUT ... REQUIRED
//  CREGSIZ='4M',                        < COMPILER REGION SIZE
//  CPARM=,                              < COMPILER OPTIONS
//  SYSLBLK='3200',                     < BLOCKSIZE FOR &&LOADSET
//* LIBPRFX='CEE';                       < PREFIX FOR LIBRARY DSN
//  LIBPRFX='SYS1.CEE.V2R4M0',           < PREFIX FOR LIBRARY DSN
//* LNGPRFX='CBC',                       < PREFIX FOR LANGUAGE DSN
//  LNGPRFX='SYS1.CBC.V2R4M0',           < PREFIX FOR LANGUAGE DSN
//  CLANG='EDCMSGE', < NOT USED IN THIS RELEASE. KEPT FOR COMPATIBILITY
//  LOPT=,                               < LOCALDEF OPTIONS
//  DCB80='(RECFM=FB,LRECL=80,BLKSIZE=3200',       <DCB FOR LRECL 80
//  DCB3200='(RECFM=FB,LRECL=3200,BLKSIZE=12800(', <DCB FOR LRECL 3200b
// OUTFILE='&&GSET(GO),DISP=(MOD,PASS),UNIT=SYSDA,SPACE=(TRK,(7,7,1))',
//  TUNIT='SYSDA'                          < UNIT FOR TEMPORARY FILES
//*
//*-------------------------------------------------------------
//* LOCALDEF STEP:
//* INVOKE CBC3LDEF MODULE TO READ LOCALE DEFINITION FILE AND
//* GENERATE C CODE.
//*-------------------------------------------------------------
//          EXEC PGM=CBC3LDEF,REGION=6144K,
//    PARM=(&LOPT)
//STEPLIB  DD  DSNAME=&LIBPRFX..SCEERUN,DISP=SHR
//         DD  DSNAME=&LNGPRFX..SCBCCMP,DISP=SHR
//SYSOUT   DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  DSNAME=&INFILE,DISP=SHR
//SYSPUNCH DD  DSNAME=&&SYSCIN,DISP=(NEW,PASS),
//         DCB=(RECFM=FB,LRECL=120,BLKSIZE=4800),
//         SPACE=(4800,(100,100)),UNIT=&TUNIT.
//EDCCMAP  DD  DSNAME=&LIBPRFX..SCEEMAP,DISP=SHR
//EDCLOCL  DD  DSNAME=&LIBPRFX..SCEELOCL,DISP=SHR
//*-------------------------------------------------------------
//*  COMPILE STEP:
//*-------------------------------------------------------------
//COMPILE EXEC PGM=CBCDRVR,REGION=&CREGSIZ,
//   COND=(4,LT,LOCALDEF),
//   PARM=('NOSEQ,NOMARGINS',
//   '&CPARM')
//STEPLIB  DD  DSNAME=&LIBPRFX..SCEERUN,DISP=SHR
//         DD  DSNAME=&LNGPRFX..SCBCCMP,DISP=SHR
//SYSMSGS  DD  DUMMY,DSN=&LNGPRFX..SCBC3MSG(&CLANG),DISP=SHR
//SYSLIN   DD  DSNAME=&&SYSCIN,DISP=(OLD,DELETE)
//SYSLIB   DD  DSNAME=&LIBPRFX..SCEEH.H,DISP=SHR
//         DD  DSNAME=&&LOADSET,UNIT=&TUNIT.,
//SYSPRINT DD  SYSOUT=*
//SYSOUT   DD  SYSOUT=*
//SYSCPRT  DD  SYSOUT=*
//SYSUT1   DD  UNIT=&TUNIT.,SPACE=(32000,(30,30)),DCB=&DCB80
//SYSUT4   DD  UNIT=&TUNIT.,SPACE=(32000,(30,30)),DCB=&DCB80
//SYSUT5   DD  UNIT=&TUNIT.,SPACE=(32000,(30,30)),DCB=&DCB3200
//SYSUT6   DD  UNIT=&TUNIT.,SPACE=(32000,(30,30)),DCB=&DCB3200
//SYSUT7   DD  UNIT=&TUNIT.,SPACE=(32000,(30,30)),DCB=&DCB3200
//SYSUT8   DD  UNIT=&TUNIT.,SPACE=(32000,(30,30)),DCB=&DCB3200
//SYSUT9   DD  UNIT=&TUNIT.,SPACE=(32000,(30,30)),
//             DCB=(RECFM=VB,LRECL=137,BLKSIZE=882)
//SYSUT10  DD  SYSOUT=*
 

Figure 53. A Sample Modified EDCLDEF JCL Procedure

//*********************************************************************
//*                                                                   *
//* LICENSED MATERIALS - PROPERTY OF IBM                              *
//*                                                                   *
//* 5647-A01                                                          *
//* (C) COPYRIGHT IBM CORP. 1988, 1997 ALL RIGHTS RESERVED            *
//*                                                                   *
//* US GOVERNMENT USERS RESTRICTED RIGHTS - USE,                      *
//* DUPLICATION OR DISCLOSURE RESTRICTED BY GSA ADP                   *
//* SCHEDULE CONTRACT WITH IBM CORP                                   *
//*                                                                   *
//*********************************************************************
//***********************************************************/
//*    MVS PROGRAM PRODUCTS TEAM                            */
//*                                                         */
//* THE FOLLOWING CHANGES MADE TO CORRECT PROCEDURE	        */
//* 1. VIO CHANGED TO SYSDA                                */
//* 2. LIBPRFX='CEE' TO LIBPREX='SYS1.CEE.V2R4M0'          */
//* 3. LNGPRFX='CBC' TO LNGPRFX='SYS1.CBC.V2R4MO'          */
//*                                                        */
//**********************************************************/
//*********************************************************************
//*                                                                   *
//* INVOKE THE LOCALEDEF UTILITY OT CREATE C SOURCE CODE              *
//* THEN COMPILE AND LIKN EDIT THE PROGRAM                            *
//*                                                                   *
//* OS/390 C/C++                                                      *
//*                                                                   *
//* RELEASE LEVEL:  02.04.00  (VERSION.RELEASE.MODIFICATION LEVEL)    *
//*                                                                   *
//*********************************************************************
//*
//EDCLDEF PROC  INFILE=,                 < INPUT ... REQUIRED
//  CREGSIZ='4M',                        < COMPILER REGION SIZE
//  CPARM=,                              < COMPILER OPTIONS
//* LIBPRFX='CEE',                       < PREFIX FOR LIBRARY DSN
//  LIBPRFX='SYS1.CEE',                  < PREFIX FOR LIBRARY DSN
//* LNGPRFX='CBC',                       < PREFIX FOR LANGUAGE DSN
//  LNGPRFX='SYS1.CBC',                  < PREFIX FOR LANGUAGE DSN
//  CLANG='EDCMSGE', < NOT USED IN THIS RELEASE. KEPT FOR COMPATIBILITY
//  LOPT=,                               < LOCALDEF OPTIONS
//  DCB80='(RECFM=FB,LRECL=80,BLKSIZE=3200)',      <DCB FOR LRECL 80
//  DCB3200='(RECFM=FB,LRECL=3200,BLKSIZE=12800)', <DCB FOR LRECL 3200
//  OUTFILE=,
//  TUNIT='SYSDA'                        < UNIT FOR TEMPORARY FILES
//*
//*-------------------------------------------------------------
//* LOCALDEF STEP:
//* INVOKE CBC3LDEF MODULE TO READ LOCALE DEFINITION FILE AND
//* GENERATE C CODE.
//*-------------------------------------------------------------
//LOCALDEF  EXEC PGM=CB3LDEF,REGION=6144K,
//    PARM=(&LOPT)
//STEPLIB  DD  DSNAME=&LIBPRFX..SCEERUN,DISP=SHR
//         DD  DSNAME=&LNGPRFX..SCBCCMP,DISP=SHR
//SYSOUT   DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  DSNAME=&INFILE,DISP=SHR
//SYSPUNCH DD  DSNAME=&&SYSCIN,DISP=(NEW,PASS),
//         DCB=(RECFM=FB,LRECL=120,BLKSIZE=4800),
//         SPACE=(9800,(500,200),UNIT=&TUNIT.
//EDCCMAP  DD  DSNAME=&LIBPRFX..SCEECMAP,DISP=SHR
//*EDCLOCL  DD  DSNAME=&LIBPRFX..SCEELOCX,DISP=SHR
//EDCLOCL  DD  DSNAME=&LIBPRFX..SCEELOCL,DISP=SHR
//*
//*-------------------------------------------------------------
//*  CREATE SYSCIN1
//*-------------------------------------------------------------
//CREATE EXEC PGM=ICEGENER
//SYSPRINT DD SYSOUT=*
//SYSUT1   DDDSN=ACP.CHDR.SARAT(PRAGMA),DISP=SHR
//SYSUT2   DD  DSNAME=&&SYSCIN1,DISP=(NEW,PASS),
//         DCB=(RECFM=FB,LRECL=120,BLKSIZE=4800),
//         SPACE=(10,(10,10)),UNIT=SYSDA
//SYSIN    DD DUMMY
//*
//*----------------------------------------------
//*  MERGE SYSHD AND SYSCIN PRODUCING SYSCIN2
//*----------------------------------------------
//MERGE EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSUT1   DD DSN=&&SYSCIN1,DIS=(OLD,DELETE)
//         DD DSN=&&SYSCIN,DIS=(OLD,DELETE)
//SYSUT2   DD  DSNAME=&&SYSCIN2,DISP=(NEW,PASS),
//         DCB=(RECFM=FB,LRECL=120,BLKSIZE=4800),
//         SPACE=(4000,(100,100)),UNIT=SYSDA
//SYSIN    DD DUMMY
//*-------------------------------------------------------------
//*  COMPILE STEP:
//*-------------------------------------------------------------
//COMPILE EXEC PGM=CBCDRVR,REGION=&CREGSIZ,
//   COND=(4,LT,LOCALDEF),
//   PARM=('NOSEQ,NOMARGINS',
//   '&CPARM)
//STEPLIB  DD  DSNAME=&LIBPRFX..SCEERUN,DISP=SHR
//         DD  DSNAME=&LNGPRFX..SCBCCMP,DISP=SHR
//SYSMSGS  DD  DUMMY,DSN=&LNGPRFX..SCBC3MSG(&CLANG),DISP=SHR
//SYSIN    DD  DSNAME=&&SYSCIN2,DISP=(OLD,DELETE)
//SYSLIB   DD
//         DD  DSNAME=&LIBPRFX..SCEEH.H,DISP=SHR
//         DD  DSNAME=&LIBPRFX..SCEEH.SYS.H,DISP=SHR
//SYSLIN   DD  DSNAME=&OUTFILE,DISP=SHR
//SYSPRINT DD  SYSOUT=*
//SYSOUT   DD  SYSOUT=*
//SYSCPRT  DD  SYSOUT=*
//SYSUT1   DD  UNIT=&TUNIT.,SPACE=(32000,(30,30)),DCB=&DCB80
//SYSUT4   DD  UNIT=&TUNIT.,SPACE=(32000,(30,30)),DCB=&DCB80
//SYSUT5   DD  UNIT=&TUNIT.,SPACE=(32000,(30,30)),DCB=&DCB3200
//SYSUT6   DD  UNIT=&TUNIT.,SPACE=(32000,(30,30)),DCB=&DCB3200
//SYSUT7   DD  UNIT=&TUNIT.,SPACE=(32000,(30,30)),DCB=&DCB3200
//SYSUT8   DD  UNIT=&TUNIT.,SPACE=(32000,(30,30)),DCB=&DCB3200
//SYSUT9   DD  UNIT=&TUNIT.,SPACE=(32000,(30,30)),
//             DCB=(RECFM=VB,LRECL=137,BLKSIZE=882)
//SYSUT10  DD  SYSOUT=*

Place the modified EDCLDEF JCL procedure in the proclib data set. See Figure 54 for a sample JCL to create object code for a locale using the modified EDCLDEF JCL procedure. In this figure, changes that you must make to the EDCLDEF JCL procedure shipped are shown in a bold example font; for example (EDC$1TEY).

Figure 54. Sample JCL Using the Modified EDCLDEF JCL Procedure

//LCDEFC   JOB MSGLEVEL=(1,1),CLASS=A,MSGCLASS=A
//* NOTE: EDCLDEFT isthe modified EDCLDEF procedure.
//LDEFCOMP EXEC EDCLDEFT,
//* provide PDS member where the locale definition source
//* is placed for INFILE parameter.
//        INFILE='ACP.LOCALE.SOURCE(EDC$1TEY)',
//* NOTE: ProvidePDS member where the object code for the locale
//* must be placed for OUTFILE parameter
//        OUTFILE='ACP.REL40.OB(CL1TEYVV)',
//* NOTE: In addition to any other compile options always provide
//* MARGINS(1,72) on CPARM parameter.
//        CPARM='MARGINS(1,72)'
//COMPILE.SYSLIB DD DSNAME=ACP.CHDR.REL40,DISP=SHR
/*
//

Preparing localedef Utility-Based Locale Load Modules

You can use one of the locale definitions provided with the compiler, modify one of them, or create a new one using the format documented in the IBM C/C++ programming guide on the IBM System/390 platform used by your installation.

To Prepare the localedef Utility-Based Locales Load Module:
  1. Prepare the locale definition. See the IBM C/C++ programmer's guide on the IBM System/390 platform used by your installation.
  2. Run the modified EDCLDEF JCL procedure to create the object file (TEXT) for the locale.
  3. Create the build script for the locale load module. These locales must be link-edited with the additional CENTPT40 object file. See Figure 55 for an example of a build script for the 1TEY locale compiled in JCL. In this figure, changes that you must make to the EDCLDEF JCL procedure shipped by IBM are shown in a bold example font; for example PDS member CL1TEY

    Figure 55. Example of a Build Script for the 1TEY Locale

    #####################################################################
    # This build script is to build CNLT locale module.                 #
    # The object code for this locale is in PDS member CL1TEY.#
    # The locales external long name is MYLOC.IBM-1047, the internal    #
    # short name is 1TEY where 1T maps to MYLOC from locale name table  #
    # and EY maps to IBM-1047 from code set name table.  The locale     #
    # module will reside in CNLT and the locales internal name          #
    # 1TEY should be mapped to CNLT in locale module name mapping table #
    # in CLM0DN.                                                        #
    #####################################################################
    #                                                                   #
    # SCRIPT NAME:   CNLTBS                                             #
    #                                                                   #
    # DESCRIPTION:  New extended locale called MYLOC that uses          #
    #               code set name IBM-1047 or <CC> = EY.                #
    #               Locale code or <LT> code = 1T.                      #
    #               Remember <LT> for user defined locales need to      #
    #               have a numeric.                                     #
    #####################################################################
    DLM  CNLT40
     
    #Object File  Function                                Source Language
    #-----------  --------                                ---------------
     
    CENTPT40      # remember this is needed for           Assembler
                  # locales
    CL1TEYVV      # TEXT created by the modified          Locale definition
    	           # EDCLDEF PROC
    
  4. Using the C load module build tool (CBLD), create the locale load module.

Other Changes Needed to Use localedef Utility-Based Locales

Add an entry for the locale in the locale name table by adding an EDCLOCNM macro call as documented in the IBM C/C++ programming guide for the compiler on the IBM System/390 platform used by your installation. The locale name table is in the CLNM assembler (BAL) source file. As shipped, this would have the EDCLOCNM call entries for the localedef utility-based locales shipped with the TPF system. Locale name table segment CLNM is part of DLM CLNM. The following is an entry that would be added for the sample locale:

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

If a new code set is used that is not in the code set name table, you must add an entry for it. Code set name table is in the CSNM assembler (BAL) source file. Code set name table CSNM is part of DLM CSNM. See Character Sets for more information about the CSNM code set name table.

The CMLM source file contains a table mapping the localedef utility-based locale names to the TPF locale load module names. This source file is part of DLM CMLM. Modify the CMLM source file to add an entry mapping the new locale name to the load module name. The locale name has two parts:

Using localedef Utility-Based Locales

You can code the new localedef utility-based locale name two different ways in the setlocale function call:

Before activating any application that uses the locale, do the following:

  1. Modify locale name table CLNM.
  2. Modify code set name table CSNM.
  3. Modify locale module name mapping table CMLM as in Other Changes Needed to Use localedef Utility-Based Locales.
  4. Build and load the CLNM, CSNM, and CMLM DLMs.
  5. Build the locale load module.

See the IBM C/C++ programming guide and user's guide for the compiler on the IBM System/390 platform that is used by your installation for more information about the localedef utility-based locale definitions and how to use, customize, and modify them.

For setlocale(LC_ALL,""), the C locale is set. You can change this definition by setting the locale-related environment variable. For example, if setenv("LC_ALL","MYLOC.IBM-1047",1) is issued to initialize the LC_ALL environment variable, setlocale(LC_ALL,"") will then set and return the "MYLOC.IBM-147" locale.

Note:
This indicates that you have changed the default NULL string locale set by the TPF system.

Creating a New TARGET(TPF) Locale

For TPF systems, a set of C locales is provided in copy member CL04 of the CCLANG CSECT. A locale is generated using a special assembler macro to which you pass parameters. The locale in effect when the first C program is activated for a given ECB is known as EDC$S370 in CL04; this is the system name for the locale shown in the previous example. For other locales the system name appearing in CL04 has EDC$ as the first part of the name followed by xxxx (EDC$xxxx), where xxxx is the first 4 characters of the name of the country. For example, the system name for the locale for Germany is EDC$GERM.

Note:
You can find that the EDC$S370 locale is not an acceptable locale for any of the applications in your environment. If this is true you can simply modify the macro parameters for this locale in CL04, and reassemble CCLANG. This frees application programs from always having to call the setlocale function before initiating their normal processing.

You can create a new locale, or modify an existing one, by specifying a new set of parameters to the assembler macros in CL04. To do this, modify CL04 as follows:

  1. Copy 1 of the existing locales that describes a locale most similar to the 1 that you are creating. Choose a system name for the new locale with EDC$ as the first 4 characters followed by xxxx (EDC$xxxx) where xxxx represents 1-4 characters.
  2. Change the invocation parameters to define the categories of the new locale.
  3. Add an entry to the LOCALTAB table in CL04 for your new locale. (Follow the instructions in the listing commentary.)
  4. Reassemble CCLANG and link-edit the control program again. Load the new control program to your system. Your new locale is now available for use by applications. It can be called (via setlocale) using the xxxx portion of the locale name defined in step 1.

C Language Support User Exits

The C language user exits are dynamic user exits that can be activated the first time a C program is called for a given ECB. When the exits are given control, the first C language stack block has been allocated, and the first stack frame, containing the library function work area, has been initialized. Information concerning the C user exit interface can be found in the TPF System Installation Support Reference.

User exits are provided, as follows:

  1. The first user exit (CSK, CENV) provides the system programmer the capability to make changes to the environment.
  2. Other user exits support test tools to allow trap points before and after a library function is called.
  3. Two user exits provide access to entry and exit through stack processing.

Extending the Library Function Work Area

The purpose of the library function work area is to provide an area of storage for data that must be available to various library functions throughout the life of an ECB. User-written library functions can also require storage of this type in order to perform their tasks.

The C user exit can be used to allocate and initialize additional storage in the library function work area for use by library functions. The storage is allocated in the first stack frame, beginning at the end of the IBM library function work area. This region is known as the user expansion area. The pointer to the user expansion area should be loaded by the user library function whenever access to the storage is desired. See Coding Your Own Library Functions, for an example.

Collection of Data

User exits (EFCE and RTNE) can be activated every time a C program is called for a given ECB, so the number of times the user exit is called in a given time interval can be accumulated. This can be used to calculate the percentage of ECBs active in the system, over a period of time, that called C programs.

Customizing User Data Area in ISO-C Modules

The TPF system provides user data areas that can be initialized with user-defined data at system startup. You can access these user data areas from applications written in C/C++ by using the data object name for the user data area in the desired module type. Following is the TPF code segment in which the user data area resides and the user data area data object name for each module type:

Module Type Startup Code Segment Data Object Name
DLM CSTRTD @@USRDMD
LLM CSTRTL @@USRLBD
DLL CSTDLL @@USRDLD

Object code only (OCO) dummy stub data objects are provided to set up and initialize the user data areas. These dummy stub data objects consist of the following code, where @@USRxxx is the data object name:

@@USRxxx CSECT
@@USRxxx AMODE ANY
@@USRxxx RMODE ANY
         DS    0D
         DC    4F'0'
         END				
Note:
These stub data objects are autocalled into the module.

You supply your own user data area by replacing the particular existing OCO dummy stub data object in data set ACP.STUB.REL40 with a user data object by using the following steps:

  1. Create a source segment containing the code for the stub data object you wish to customize.
  2. Substitute your customized data in place of the current data.
  3. Assemble the segment with data set ACP.STUB.REL40 as the target for the object module.
  4. Link-edit all modules requiring access to the user data area.
Note:
To avoid loading incorrect user data, there should be a single copy of that particular stub data object and it should be in data set ACP.STUB.REL40. Delete any copies of the stub data object that are in data set ACP.CLIB.REL40.