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 COUNTRYand MODIFIER that should no longer be used.

lang expects a character-like darta 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 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 explicity, 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 as a system code page for the current AS ABAP. Otherwise a handleable exception is raised. This has different consequences for single code page systems and MDMP systems:

  • In a single code page system, only one code page is released as a system code page. With SET LOCALE, only the language and the locale can be changed and not the code page of the text environment.
  • In an MDMP system, multiple code pages are released as system code pages. SET LOCALE can be used to change the language, the locale, and the code page of the text environment. If the code page found in TCP0C is released, the SET LOCALE statement sets this code page as the environment code page.

A non-Unicode codepage can be released as a system code page by entering the SAP code page number in the database table TCPDB, which is maintained using the executable program RSCPINST. 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 coding


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 ignore upper/lower case.

  • 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.
  • When the system code page is changed in MDMP systems, a compatible code page must also be installed on the presentation server that is used. Otherwise, it may not be possible to display all the characters on the screen.
  • 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 that is coded in accordance with UTF-16 ("00E400F600FC") is converted in the same way in all text environments ("00E400F600FC"). 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). In MDMP systems in which the code pages 1100 and 1500 are released, the binary content of text ("E4F6FC" in codepage 1100) is converted differently according to the code page. In a text environment with the code page 1100, the characters are interpreted as umlauts. In a text environment with the code page 1500, these are cyrillic characters. When converting to uppercase, the system searches in the code page for the appropriate character according to the text environment, and converts it accordingly. The result for code page 1100 is "C4D6DC", and for code page 1500 is "C4A6AC".

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

ASSIGN text TO <hex> CASTING. 
text = 'äöü'. 
WRITE / <hex>. 

SET LOCALE LANGUAGE 'E'. 
TRANSLATE text TO UPPER CASE. 
WRITE / <hex>. 

text = 'äöü'. 
SET LOCALE LANGUAGE 'R'. 
TRANSLATE text TO UPPER CASE. 
WRITE / <hex>. 

SET LOCALE LANGUAGE ' '.

Exceptions


Catchable Exceptions

CX_SY_LOCALIZATION_ERROR

  • Cause: Using the tables TCP0D and TCP0C, the system has detected a character set 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