Understanding the Essbase Unicode Implementation

In This Section:

About Unicode

When to Use Unicode-Mode Applications

Locales and the ESSLANG Variable

Unicode and Non-Unicode Application Modes

Unicode and Non-Unicode Essbase Server Modes

Increased Name Lengths

Compatibility Between Different Versions of Client Programs and Essbase Applications

Unicode-Enabled C API

Identification of Text Encoding and Locale

Unicode-Enabled Administration Tools

Retrieval Tools

SQL Interface


The information in this chapter applies to block storage and aggregate storage databases.

About Unicode

Sharing data across national and language boundaries is a challenge for multinational businesses. Traditionally, each computer stores and renders text based on its locale specification. A locale identifies the local language and cultural conventions, such as currency and date format, data sort order, and character-set encoding. Encoding refers to the bit combinations used to store the character text as data, as defined by a code page or an encoding format. In Essbase, code pages map characters to bit combinations for non-Unicode encodings.

Because different encodings can map the same bit combination to different characters, a file created on one computer can be misinterpreted by another computer with a different locale.

The Unicode Standard enables computers with different locales to share character data. Unicode provides encoding forms with thousands of bit combinations, enough to support the character sets of multiple languages simultaneously. By combining all character mappings into one encoding form, Unicode enables users to correctly view character data created on computers with different locale settings.

Essbase conforms to version 2.1 of the Unicode Standard and uses UTF-8 encoding. See www.unicode.org.

Through its Unicode implementation, Essbase enables employees of global businesses to view, in their own languages, company information stored in Essbase databases. For example, using alias tables in their respective languages, users in Taiwan can view database reports in Chinese characters, and users in France can view the same reports in French characters.

The following topics describe the characteristics of the Essbase implementation of Unicode.


In Essbase, user-defined character sets (UDC) are not supported.

When to Use Unicode-Mode Applications

Consider working with Unicode-mode applications only in the following situations:

  • You need to enable users with different languages to view, in their own languages and character sets, information from a common database.

    For example, using alias tables in Japanese and German, users in Japan and Germany can view information about a common product set in their own languages.

  • You need to handle artifact names longer than non-Unicode-mode applications support.

    For example, application and database names need to include more than eight characters, or you are working with a multibyte character set, and you need to handle more characters in artifact names.

    See Limits.

  • For a translated, multibyte Essbase implementation, you have experienced a “round-trip” problem, where two different bit values can map to the same character, which can occur in communications between multibyte operating systems and application programs.

    As Java applications, Administration Services and Provider Services always work in Unicode; therefore, no round-trip conversion errors occur.

When deciding whether to use Unicode-mode applications, consider the following points:

  • Using non-Unicode text files with Unicode-mode applications requires an understanding of locales and care in managing them. Oracle recommends using UTF-8 encoded files to prevent errors that can cause database corruption.

    See Managing File Encoding.

  • To work with Unicode-mode applications, custom client programs that were written to support non-Unicode-mode applications must be built to use the longer strings used by Unicode-mode applications. This task may be a simple rebuild or may involve reprogramming, depending on the design of the applications. Depending on how modified programs are coded, more memory may be required.

    See the Oracle Essbase API Reference.

Locales and the ESSLANG Variable

Essbase uses the ESSLANG variable to define the locale of a computer. For example, to support American English, you can set ESSLANG to English_UnitedStates.Latin1@Binary.

The ESSLANG variable includes a code-page specification that maps bit combinations to characters. Although a locale specification contains several kinds of information about the language and culture that the computer supports, Essbase uses only the code-page portion; cultural conventions and sort-order portions are not used.

For each Essbase Server installation, you must specify the ESSLANG variable, which should be set to the locale that is defined for the computer's operating system.

For client computers, specifying the ESSLANG variable is optional. If ESSLANG is defined, Essbase uses the ESSLANG value as the computer locale. If ESSLANG is not specified, the operating system locale is used.

The ESSLANG variable is set when you install Essbase. See the Oracle Hyperion Enterprise Performance Management System Installation and Configuration Guide.

For non-Unicode-mode clients and applications, the client and Essbase Server locale values must be the same. For Unicode-mode applications, client and Essbase Server locale values can be different.

Unicode and Non-Unicode Application Modes

Applications are designated as Unicode-mode applications or non-Unicode-mode applications.

Unicode-mode applications support multiple character sets. When Essbase works with Unicode-mode applications, it uses the UTF-8 encoding form to interpret and store character text. Character-based artifacts in Unicode-mode applications, such as member and alias names, can include characters from different languages.

Because Unicode-mode applications accept input files in non-Unicode-encoding and UTF-8, Essbase relies on locale indicators and user prompting to read or write non-Unicode-encoded files.

Clients working with Unicode-mode applications can have locales different from that of Essbase Server. For example, client computers with Japanese locales and client computers with German locales can work with the same Unicode-mode application on an instance of Essbase Server that has a Spanish locale.

For Unicode-mode applications, the limits of most artifact names are longer than the limits in non-Unicode-mode applications, and the limits are calculated based on characters rather than bytes. See Increased Name Lengths.

Non-Unicode-mode applications support one character set that is defined by a locale value that must be the same for Essbase Server and all non-Unicode clients that work with non-Unicode-mode applications. By default, Essbase creates applications in non-Unicode mode.

You can define an application as Unicode-mode when you create the application (see Creating Unicode-Mode Applications), or you can migrate a non-Unicode-mode application to Unicode mode in a separate step (see Migrating Applications to Unicode Mode).


You cannot convert a Unicode-mode application to non-Unicode mode.

Unicode-mode and non-Unicode-mode applications can reside on the same Essbase Server.

Unicode and Non-Unicode Essbase Server Modes

Essbase Server is in Unicode mode when it has permission to create Unicode-mode applications and to migrate existing applications to Unicode mode. See Setting Essbase Server to Unicode Mode.

Whether Essbase Server is in Unicode mode affects only the creation and migration of applications. Regardless of the Essbase Server Unicode setting, you can work with both Unicode mode and non-Unicode-mode applications.

Increased Name Lengths

For Unicode-mode applications, the maximum number of characters allowed in strings, such as application, database, and member names, is greater than the maximum allowed for non-Unicode-mode applications.

The maximum length of Unicode artifact names is based on the number of characters, regardless of how many bytes each character requires. The maximum length of non-Unicode artifact names is calculated in bytes.

Not limiting by bytes is advantageous for applications using multibyte character sets, such as Chinese and Japanese. For example, the limit for member names in Unicode-mode applications is 80 characters, even if they are multibyte characters, whereas the limit for member names in non-Unicode applications is 80 bytes. See Limits.


The increased size limits may affect the size of the outline and user-written client programs.

To take advantage of longer name sizes, users may decide to work with Unicode-mode applications, even if all users work in the same locale (see When to Use Unicode-Mode Applications).

Compatibility Between Different Versions of Client Programs and Essbase Applications

Essbase supports Unicode-mode and non-Unicode-mode client programs.

Non-Unicode-mode client programs (for example, MaxL Shell and Spreadsheet Add-in):

  • Communicate with Essbase API in short strings

  • Cannot make changes to Unicode-mode outlines

  • Cannot perform outline synchronization of Unicode-mode outlines

Unicode-mode client programs (for example, Administration Services Console and Smart View):

  • Communicate with Essbase API in Unicode encoding, using long strings

  • Cannot synchronize non-Unicode-mode outlines with multibyte characters


If you use Administration Services Console or another tool to create a MaxL script and save it in UTF-8 and then execute the script in MaxL Shell, MaxL Shell assumes the role of a Unicode-mode client. You can use this approach, for example, to update outlines through dimension builds. When you create the script, remember to include the UTF-8 signature. See Encoding Indicators.

Unicode-Enabled C API

Custom-written client programs used with pre-7.0 Essbase releases cannot be used with Unicode-mode applications because these custom programs use short strings and short buffers.

To provide restricted access to Unicode-mode applications, these older custom client programs, depending on how they are written, can be recompiled in a Unicode-enabled release of Essbase. When recompiled, the programs work with long buffers but short strings.

For complete access to Unicode-mode and non-Unicode-mode applications, existing custom applications must be modified using the Essbase API functions for Unicode. Rewritten and compiled clients work with long buffers and long strings for full Unicode support. See the Oracle Essbase API Reference.

Identification of Text Encoding and Locale

Essbase supports use of non-Unicode-encoded files, such as report and calculation scripts, with Unicode-mode applications. To identify a file's encoding type, Essbase looks for encoding indicators (UTF-8 signature or locale indicator). If a file does not contain either encoding indicator, and the file is not on Essbase Server, Administration Services prompts the user for the locale of the file. See Encoding Indicators.

The Essbase Unicode File Utility includes options to insert a UTF-8 signature or locale indicator in text files. Or you can use a text editor or other means to insert them. See Essbase Unicode File Utility.

Unicode-Enabled Administration Tools

To administer Unicode-mode applications, you can use Administration Services and MaxL Shell. With Administration Services Console, which is a Unicode-mode client, you can administer Unicode-mode and non-Unicode-mode applications.

Unicode-related administration activities include changing the Unicode-related mode of Essbase Server to enable or disable the following abilities:

  • Creation of Unicode-mode applications

  • Migration of non-Unicode-mode applications to Unicode mode

  • Viewing of Unicode-related status of Essbase Server and applications

See Administering Unicode-Mode Applications.

Retrieval Tools

Essbase provides several methods for retrieving data from Unicode-mode and non-Unicode-mode applications.

Report Script

Report script output files are encoded to the encoding of the application. For example, if a report script is run against a database in a Unicode-mode application, the report script output is encoded in UTF-8; if run against a database in a non-Unicode-mode application, the output is encoded in the encoding of the application.


With Smart View, you can view data in Unicode-mode and non-Unicode-mode applications.

To run Smart View, you connect to Oracle Hyperion Provider Services. To install these programs, see the Oracle Hyperion Enterprise Performance Management System Installation and Configuration Guide.

For information about working with Smart View, see the Oracle Hyperion Smart View for Office User's Guide.


Spreadsheet Add-in does not support Unicode.

SQL Interface

With SQL Interface, you can load data from a Unicode-mode relational database to a Unicode-mode Essbase application. Table 66 shows supported encodings for Unicode-mode and non-Unicode-mode applications:

Table 66. SQL Interface Supported Encodings for Unicode-Mode and Non-Unicode-Mode Applications

Application mode

Relational Database Encoding


A supported non-Unicode encoding


A supported non-Unicode encoding



SQL Interface accepts user authentication (user name and password) and application information in UTF-8 encoding.

See Supported Locales.


To learn more about Unicode-mode applications, use the Sample_U.Basic application. Member names in Sample_U.Basic are in English.

Table 66 lists the non-English alias tables and their import files included in the Sample_U.Basic database:

Table 67. Non-English Alias Tables in the Sample_U.Basic Database

LanguageNon-English Alias Table