Function SetLocale() Foundation

Retrieve or change country-specific literals, formats or separators

Syntax
SetLocale( <nDefine>, [<cNewSetting>] ) --> cOldSetting
Scope
Read-only settings: process-wide
Changeable settings: thread-local
Parameters
<nDefine>
<nDefine> is a #define constant indicating a country-specific setting. All valid constants are found in the NLS.CH file.
<cNewSetting>
The optional expression <cNewSetting> can specify a new value for a country-specific setting. However, this is only possible for changeable settings (see below).
Return

The function returns the setting which is set before the function is called (the old setting).

Description

The funtion SetLocale() is used to localize an Xbase++ application. It retrieves country-specific settings of the operating system, and changes such settings for the Xbase++ process/thread. A country-specific setting can be the decimal separator, the date and time format, for example. The function distinguishes changeable and read only settings:

General country settings (Read only)
Constant Description
NLS_ICOUNTRY Country code of the operating system: "1" = USA, "49" = Germany
NLS_IANSICP Code page of the ANSI charset, like "1252"
NLS_SANSICP Code page name of the ANSI charset, like "windows-1252"
NLS_IOEMCP Code page of the OEM charset, like "437"

Week and month names depending on OS settings (Read only)
Group Constant Description
Week days NLS_SDAYNAME1 Literal strings for the 1st to the 7th day of the week:
NLS_SDAYNAME2 - 1st day corresponds to Monday
NLS_SDAYNAME3 - 7th day corresponds to Sunday
NLS_SDAYNAME4
NLS_SDAYNAME5
NLS_SDAYNAME6
NLS_SDAYNAME7
Months NLS_SMONTHNAME1 Literal strings for the 1st to the 12th month:
NLS_SMONTHNAME2 - 1st month corresponds to January
NLS_SMONTHNAME3 - 12th month corresponds to December
NLS_SMONTHNAME4
NLS_SMONTHNAME5
NLS_SMONTHNAME6
NLS_SMONTHNAME7
NLS_SMONTHNAME8
NLS_SMONTHNAME9
NLS_SMONTHNAME10
NLS_SMONTHNAME11
NLS_SMONTHNAME12

Abbreviated day and month names depending on OS settings (Read only)
Group Constant Description
Week days NLS_SABBREVDAYNAME1 short strings for the 1st to the 7th day of the week:
NLS_SABBREVDAYNAME2 - 1st day corresponds to ie. Mon
NLS_SABBREVDAYNAME3 - 7th day corresponds to ie. Sun
NLS_SABBREVDAYNAME4
NLS_SABBREVDAYNAME5
NLS_SABBREVDAYNAME6
NLS_SABBREVDAYNAME7
Months NLS_SABBREVMONTHNAME1 short strings for the 1st to the 12th month:
NLS_SABBREVMONTHNAME2 - 1st month corresponds to Jan
NLS_SABBREVMONTHNAME3 - 12th month corresponds to Dec
NLS_SABBREVMONTHNAME4
NLS_SABBREVMONTHNAME5
NLS_SABBREVMONTHNAME6
NLS_SABBREVMONTHNAME7
NLS_SABBREVMONTHNAME8
NLS_SABBREVMONTHNAME9
NLS_SABBREVMONTHNAME10
NLS_SABBREVMONTHNAME11
NLS_SABBREVMONTHNAME12

Fixed week and month names (Read only, English in internationl version)
Group Constant Description
Week days NLS_SFDAYNAME1 fixed strings for the 1st to the 7th day of the week:
NLS_SFDAYNAME2 - 1st day corresponds to Monday
NLS_SFDAYNAME3 - 7th day corresponds to Sunday
NLS_SFDAYNAME4
NLS_SFDAYNAME5
NLS_SFDAYNAME6
NLS_SFDAYNAME7
Months NLS_SFMONTHNAME1 fixed strings for the 1st to the 12th month:
NLS_SFMONTHNAME2 - 1st month corresponds to January
NLS_SFMONTHNAME3 - 12th month corresponds to December
NLS_SFMONTHNAME4
NLS_SFMONTHNAME5
NLS_SFMONTHNAME6
NLS_SFMONTHNAME7
NLS_SFMONTHNAME8
NLS_SFMONTHNAME9
NLS_SFMONTHNAME10
NLS_SFMONTHNAME11
NLS_SFMONTHNAME12

Default values for changeable settings are read from the operating system. They can be altered during runtime of a program:

Settings for separators (one character)
Constant Example Description
NLS_SLIST ";" List separator
NLS_SDECIMAL "," "." Decimal separator
NLS_STHOUSAND "," "." " " Thousand separator

Settings for currency (max. two characters)
Constant Example Description
NLS_SCURRENCY "DM" "$" Currency symbol
NLS_ICURRENCY Position of the symbol
"0" => DM99
"1" => 99DM
"2" => DM 99
"3" => 99 DM
NLS_ICURRDIGITS "2" "4" Number of decimal places for currencies
NLS_ICURRENCYEURO "0" Disable Euro symbol usage
"1" Enable Euro symbol usage

Displaying the Euro symbol

The upcoming currency of the European community requires programs being able to display a new currency symbol. Xbase++ introduces Euro support with the SetLocale() function, but to sucessfully display the new symbol in an application, the operating system must be made "Euro aware". This is accomplished by upgrading the operating system with an Euro patch, available for download at the homepage of the operating system's manufacturer. The upgrade changes some system fonts, adds the new symbol to these fonts and changes national keyboard and character mappings. Note that not all fonts are upgraded and that keyboard mappings differ for some countries:

Key mappings for the Euro symbol
Key Valid for
AltGr + E most European countries
AltGr + U Poland, Hungaria
AltGr + 4 Ireland, Latvia, UK
AltGr + 5 US-international

The Euro support is disabled by default in Xbase++. To prepare a program for the Euro symbol, SetLocale( NLS_ICURRENCYEURO, "1" ) must be called at program start. This causes Chr(213) be used as Euro symbol in the OEM character set, or Chr(128) in the ANSI character set, respectively.

Since the display of the Euro symbol requires an appropriate font be selected, it is necessary to link the Xbase++ application for hybrid or GUI mode (use GUI=yes in the project file or the linker switch /PM:PM). In text mode applications, the availability of the Euro symbol depends on built-in text fonts which cannot be changed at runtime from an Xbase++ application.

The display of the Euro symbol in a hybrid application relies on the OEM font used by the XbpCrt window. The characters available in the font depend in turn on the code page selected for the operating system. To display the Euro symbol with the default font of the XbpCrt window, code page 850 must be selected. This code page is used in many European countries. The OEM codepage 437 (common in US), however, does not contain this new symbol.

Settings for logical values (one character)
Constant Example Description
NLS_SYES "J" "Y" "O" Letter for Yes (logical true)
NLS_SNO "N" "F" Letter for No (logical false)

Settings for date values
Constant Example Description
NLS_SDATE "." "/" "-" Date separator
NLS_IDATE Date format
"0" => MM/DD/YY
"1" => DD/MM/YY
"2" => YY/MM/DD
NLS_ICENTURY Digits for the century
"0" => 97
"1" => 1997

Settings for the time format
Constant Example Description
NLS_STIME "." Time separator
NLS_ITIME 12/24h format
"0" => 12h
"1" => 24h
NLS_S1159 "AM" Marker "morning"
NLS_S2359 "PM" Marker "afternoon"
NLS_STIMEZONE "EST" Name of the time zone
NLS_ITZBIAS "-120" Time zone bias local time to UTC in minutes incl. NLS_ITZDAYLIGHTBIAS
NLS_ITZDAYLIGHTBIAS "60" Bias during daylight saving time in minutes

The string returned for NLS_STIMEZONE can be either the abbreviation of a time zone like "EST", or the long name of the time zone like "Middleeuropean Summer Time", it solely depends on the operating system setting. The NLS_ITZBIAS describes the difference from the local time zone to UTC in minutes. If the daylight saving is active the NLS_ITZDAYLIGHTBIAS was already added to this value.

Examples
Retrieve all country-specific settings

// The example lists all country-specific settings 
// to a file and displays it using MemoEdit() 

#include "Nls.ch" 

PROCEDURE Main 
   LOCAL aSettings := { ; 
   { "NLS_ICOUNTRY    " , NLS_ICOUNTRY     }, ; 
   { "NLS_SLIST       " , NLS_SLIST        }, ; 
   { "NLS_SDECIMAL    " , NLS_SDECIMAL     }, ; 
   { "NLS_STHOUSAND   " , NLS_STHOUSAND    }, ; 
   { "NLS_SCURRENCY   " , NLS_SCURRENCY    }, ; 
   { "NLS_ICURRENCY   " , NLS_ICURRENCY    }, ; 
   { "NLS_ICURRDIGITS " , NLS_ICURRDIGITS  }, ; 
   { "NLS_SDATE       " , NLS_SDATE        }, ; 
   { "NLS_IDATE       " , NLS_IDATE        }, ; 
   { "NLS_ICENTURY    " , NLS_ICENTURY     }, ; 
   { "NLS_STIME       " , NLS_STIME        }, ; 
   { "NLS_ITIME       " , NLS_ITIME        }, ; 
   { "NLS_S1159       " , NLS_S1159        }, ; 
   { "NLS_S2359       " , NLS_S2359        }, ; 
   { "NLS_STIMEZONE   " , NLS_STIMEZONE    }, ; 
   { "NLS_ITZBIAS     " , NLS_ITZBIAS      }, ; 
   { "NLS_SYES        " , NLS_SYES         }, ; 
   { "NLS_SNO         " , NLS_SNO          }, ; 
   { "NLS_SDAYNAME1   " , NLS_SDAYNAME1    }, ; 
   { "NLS_SDAYNAME2   " , NLS_SDAYNAME2    }, ; 
   { "NLS_SDAYNAME3   " , NLS_SDAYNAME3    }, ; 
   { "NLS_SDAYNAME4   " , NLS_SDAYNAME4    }, ; 
   { "NLS_SDAYNAME5   " , NLS_SDAYNAME5    }, ; 
   { "NLS_SDAYNAME6   " , NLS_SDAYNAME6    }, ; 
   { "NLS_SDAYNAME7   " , NLS_SDAYNAME7    }, ; 
   { "NLS_SMONTHNAME1 " , NLS_SMONTHNAME1  }, ; 
   { "NLS_SMONTHNAME2 " , NLS_SMONTHNAME2  }, ; 
   { "NLS_SMONTHNAME3 " , NLS_SMONTHNAME3  }, ; 
   { "NLS_SMONTHNAME4 " , NLS_SMONTHNAME4  }, ; 
   { "NLS_SMONTHNAME5 " , NLS_SMONTHNAME5  }, ; 
   { "NLS_SMONTHNAME6 " , NLS_SMONTHNAME6  }, ; 
   { "NLS_SMONTHNAME7 " , NLS_SMONTHNAME7  }, ; 
   { "NLS_SMONTHNAME8 " , NLS_SMONTHNAME8  }, ; 
   { "NLS_SMONTHNAME9 " , NLS_SMONTHNAME9  }, ; 
   { "NLS_SMONTHNAME10" , NLS_SMONTHNAME10 }, ; 
   { "NLS_SMONTHNAME11" , NLS_SMONTHNAME11 }, ; 
   { "NLS_SMONTHNAME12" , NLS_SMONTHNAME12 }  } 

   SET ALTERNATE TO NLS.TXT 
   SET ALTERNATE ON 
   AEval( aSettings, ; 
          {|a| QOut( a[1], '"'+SetLocale( a[2] )+'"' ) } ) 

   SET ALTERNATE OFF 
   SET ALTERNATE TO 
   CLS 
   Memoedit( MemoRead( "NLS.TXT" ) ) 

RETURN 
Define formats for numbers and logical values

// The example demonstrates how to define display 
// formats for numbers and logical values. 

#include "Nls.ch" 

PROCEDURE Main 
   LOCAL nNumber := 1234567.89 
   LOCAL cPicture:= "999,999,999.99" 
   LOCAL lTrue   := .T., lFalse := .F. 
   LOCAL dDate   := Date() 

   ? nNumber                            // result:    1234567,89 
   ? Str( nNumber )                     // result:    1234567.89 
   ? Transform( nNumber, cPicture )     // result:  1.234.567,89 

   SetLocale( NLS_STHOUSAND  , "t" ) 
   SetLocale( NLS_SDECIMAL   , "d" ) 

   ? nNumber                            // result:    1234567d89 
   ? Str( nNumber )                     // result:    1234567.89 
   ? Transform( nNumber, cPicture )     // result:  1t234t567d89 

   ? lTrue , Transform( lTrue , "Y" )   // result: .T. T 
   ? lFalse, Transform( lFalse, "Y" )   // result: .F. F 

   SetLocale( NLS_SYES , "1" ) 
   SetLocale( NLS_SNO  , "0" ) 

   ? lTrue , Transform( lTrue , "Y" )   // result: .T. 0 
   ? lFalse, Transform( lFalse, "Y" )   // result: .F. 1 

   // Only 0 and 1 is accepted as input for logical values 
   @ row()  , 0 SAY "True " GET lTrue  PICTURE "Y" 
   @ row()+1, 0 SAY "False" GET lFalse PICTURE "Y" 
   READ 

RETURN 
Currency formats for numbers

// The example shows different possibilities of 
// formatting numbers as currency. 

#include "Nls.ch" 

PROCEDURE Main 
   LOCAL nNumber := 12345.67 
   LOCAL cPicture:= "@$ 999,999.99" 

   ? nNumber                            // result:    12345,67 
   ? Transform( nNumber, cPicture )     // result: 12.345,67 DM 

   SetLocale( NLS_STHOUSAND, "'"  ) 
   SetLocale( NLS_SDECIMAL , "."  ) 
   SetLocale( NLS_SCURRENCY, "FF" ) 

   ? Transform( nNumber, cPicture )     // result: 12'345.67 FF 

   SetLocale( NLS_ICURRENCY, "0"  ) 
   ? Transform( nNumber, cPicture )     // result: FF12'345.67 

   SetLocale( NLS_ICURRENCY, "1"  ) 
   ? Transform( nNumber, cPicture )     // result: 12'345.67FF 

   SetLocale( NLS_ICURRENCY, "2"  ) 
   ? Transform( nNumber, cPicture )     // result: FF 12'345.67 

   SetLocale( NLS_ICURRENCY, "3"  ) 
   ? Transform( nNumber, cPicture )     // result: 12'345.67 FF 

RETURN 
Displaying the Euro symbol
// The program demonstrates the procedure how to 
// prepare an application for the European currency symbol 
// 
// TEST.PRG 
// 
// Compile & Link: xpp test /link:"/PM:PM" 
// 

#include "Appevent.ch" 
#include "Font.ch" 
#include "Nls.ch" 

PROCEDURE MAIN 
   LOCAL nEvent, mp1, mp2, oXbp 
   SETCOLOR( "N/W" ) 
   CLS 

   SetLocale( NLS_SCURRENCY, Chr(213) ) 
   ? "Euro OFF Chr(213) =", Chr(213) 
   WAIT 
   SetLocale( NLS_ICURRENCYEURO, "1" ) 

   // Configure the XbpCrt window, so the new font 
   // containing the Euro character becomes effective 
   SetAppWindow():configure() 
   SetColor( "N/W" ) 
   CLS 
   ? "Euro ON  Chr(213) =", Chr(213) 

   // Select characters as currency symbol 
   SetLocale( NLS_SCURRENCY, "$" ) 
   ? "Dollar in PICTURE", Transform( 123.45, "@$" ) 

   SetLocale( NLS_SCURRENCY, Chr(213) ) 
   ? "Euro   in PICTURE", Transform( 123.45, "@$" ) 

   // Entering the Euro sign in an SLE requires 
   // a font supporting this character 
   oXbp := XbpSLE():new(,,{50,200}, {300,24}) 
   oXbp:create() 
   oXbp:setFontCompoundName( FONT_HELV_MEDIUM ) 
   oXbp:setData( "Press AltGr+5" ) 

   DO WHILE nEvent <> xbeP_Close 
      nEvent := AppEvent( @mp1, @mp2, @oXbp ) 
      oXbp:handleEvent( nEvent, mp1, mp2 ) 
   ENDDO 
RETURN 
Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.