Skip to content

ABAP Keyword Documentation →  ABAP - Reference →  Program Parameters →  Language Environment →  Text Environment 

SET LOCALE LANGUAGE

Short Reference

Other versions: 7.31 | 7.40 | 7.54

Syntax


 SET LOCALE LANGUAGE lang [obsolete_parameters].

Effect

This statement defines the text environment for all programs of the current internal session for the languages specified in lang, and sets sy-langu to the value of lang. The statement has two obsolete additions COUNTRY and MODIFIER that should no longer be used.

lang expects a character-like data object. This must contain a language key with a maximum length of one character, and this value must be contained in the column SPRAS of the database table T002. If the data object lang only contains blank characters, the logon language of the current user is used and the additions are ignored.

The statement SET LOCALE has a different effect depending on whether the system is a Unicode system or a non-Unicode system.

Setting the Text Environment in a Unicode System

In a Unicode system, a language key must be specified in lang, and a country key must be specified in cntry, for which locale properties must be defined in the ICU library of the application server. The possible language keys are contained in the SPRAS column of the database table T002. The locale of the text environment is set accordingly, and influences how internal tables and extracts are sorted using the statement SORT with the addition AS TEXT.

The code page of a Unicode system is always UTF-16 (the ABAP programming language supports the subset UCS-2) and is not influenced by the statement SET LOCALE. After SET LOCALE is executed, however, the non-Unicode code page that would be set by the statement in a non-Unicode system (see below), is used for specific statements such as reading and writing legacy files for conversions.

Setting the Text Environment in a Non-Unicode System

In a non-Unicode system, the language key specified in lang, combined with the current operating system of the application server (system field sy-opsys) and the country key taken explicitly from the database table TCP0D or set explicitly, must produce a valid key for the database table TCP0C. This key is used to extract the name of the operating system specific locale from the column LOCALE and the number of the non-Unicode code page from the column CHARCO. If no entry exists in the table TCP0C for the specified key, a handleable exception is raised. The code page specified by the key in TCP0C must be released as a system code page for the current AS ABAP. Otherwise a handleable exception is raised. SET LOCALE can be used to modify only the language and the locale, but not the environment code page, of the text environment of a single code page system.

A non-Unicode code page can be released as a system code page by entering the SAP code page number in the database table TCPDB, which is edited using the transaction I18N. If the database table TCPDB is empty, it is handled as if it contains a single entry with the number 1100.

Programming Guideline

If possible, do not switch the text environment within the code


Notes

  • The text environment of an internal session should only be changed for the following purposes:

  • Processing character-like data objects that are in a different language to the logon language of the current user. The language is important for the statements SORT ... AS TEXT, TRANSLATE ... TO UPPER CASE and for comparisons that are not case-sensitive.

  • In a non-Unicode system, characters from an Eastern Asian language (Chinese, Japanese, Korean) can be processed. If the text environment is not configured correctly, double-byte characters are not recognized correctly.

  • After processing in a changed text environment, the text environment should be reset to the previous text environment.
  • Instead of the SET LOCALE statement, the four function modules whose names begin with SCP_MIXED_LANGUAGES_ can be used to define or change the current text environment, and to reset it to the original text environment.
  • Do not confuse the statement SET LOCALE LANGUAGE with the statement SET LANGUAGE, used for loading the texts of a text pool.


Example

This example demonstrates the effect of the code page of the text environment on the statement TRANSLATE ... TO UPPER CASE: In Unicode systems, the content of text ("00E400F600FC") that is encoded in accordance with UCS-2 is transformed in the same way in all text environments ("00C400D600DC"). In non-Unicode single code page systems, the program raises an exception, because different code pages are associated with the language keys "E" and "R" (SAP code page numbers 1100 and 1500).

DATA text TYPE c LENGTH 3. 
FIELD-SYMBOLS <hex> TYPE x. 

ASSIGN text TO <hex> CASTING. 
text = 'äöü'. 
cl_demo_output=>write( <hex> ). 

SET LOCALE LANGUAGE 'E'. 
TRANSLATE text TO UPPER CASE. 
cl_demo_output=>write( <hex> ). 

text = 'äöü'. 
SET LOCALE LANGUAGE 'R'. 
TRANSLATE text TO UPPER CASE. 
cl_demo_output=>write( <hex> ). 

SET LOCALE LANGUAGE ' '. 

cl_demo_output=>display( ).

Exceptions


Catchable Exceptions

CX_SY_LOCALIZATION_ERROR

  • Cause: Using the tables TCP0D and TCP0C, a character set was detected that is not released in your system. The released character sets are in the table TCPDB. Normally this table contains exactly one character set and this runtime error occurs because the system has attempted to use a non-compatible language.
    Runtime error: TEXTENV_CODEPAGE_NOT_ALLOWED
  • Cause: No entry exists (for the current platform) in the SAP text environment table TCP0C for the specified keys lang, cntry, and mod.
    Runtime Error: TEXTENV_KEY_INVALID


Non-Catchable Exceptions

  • Cause: Selection of a 'binary' text environment using the modifier 'BINARY', 'C', 'POSIX', or 'RAW'.
    Runtime Error: TEXTENV_BINARY_NOT_SUPPORTED
  • Cause: One of the key values lang, cntry, or mod is longer than the corresponding fields LANGU, COUNTRY, or MODIFIER in the SAP text environment table TCP0C.
    Runtime Error: TEXTENV_KEY_TOO_LONG