Administering Unicode-Mode Applications

In This Section:

Setting Up a Computer for Unicode Support

Defining Password Security

Naming Applications and Databases

Managing Unicode-Mode Essbase Servers

Managing Unicode-Mode Applications

Using Control Characters in Report Scripts

Working with Partitions

Working with Logs

Managing File Encoding

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

Setting Up a Computer for Unicode Support

Install the following tools (provided by third-party vendors) for working with UTF-8 encoded text on computers that manage Unicode-mode applications:

  • UTF-8 fonts: For viewing UTF-8 encoded text that contains non-ASCII characters

  • (Optional) Unicode editor (which includes the UTF-8 signature): For manual editing of data sources or other text files

Essbase provides the Essbase Unicode File Utility, which converts text files to UTF-8 encoding. See Essbase Unicode File Utility.

Defining Password Security

Essbase security is defined at the Essbase Server level. To create passwords, use characters encoded according to the code page specified in the ESSLANG variable on the Essbase Server computer.

In a multibyte character set environment, passwords cannot contain multibyte characters. Consider using the characters in the standard ASCII character set, in the range from 0 through 127, which includes the uppercase and lowercase letters in the standard English alphabet and the numerals 0 through 9. These characters are common to all code pages and to UTF-8.

Naming Applications and Databases

When you name applications and databases, you must use characters that are supported by the character set that is specified by the ESSLANG variable. On the computer where Essbase Server is installed, the ESSLANG variable must be set to the locale that is defined for the computer's operating system.

Managing Unicode-Mode Essbase Servers

The topics in this section discuss processes for managing Unicode-mode Essbase Servers.

Setting Essbase Server to Unicode Mode

By setting Essbase Server to Unicode mode, you grant permission for creating Unicode-mode applications and for migrating applications to Unicode mode.

  To set Essbase Server to Unicode mode, use a tool:

Tool

Topic

Location

Administration Services

Managing Essbase Server Permissions to Create Unicode-Mode Applications

Oracle Essbase Administration Services Online Help

MaxL

alter system

Oracle Essbase Technical Reference

Note:

You can work with Unicode-mode applications without Essbase Server being set to Unicode mode.

Viewing the Unicode-Related Mode of Essbase Server

The Unicode-related mode of Essbase Server indicates whether Essbase Server has permission to create Unicode-mode applications and to migrate applications to Unicode mode.

In Administration Services Console, the Unicode-related mode is shown as a server property.

In MaxL Shell, the Unicode-related mode is displayed as the configuration, with the following values:

  • 2, for non-Unicode-mode applications

  • 3, for Unicode-mode applications

  To see whether Essbase Server is set to Unicode mode, use a tool:

Tool

Topic

Location

Administration Services

Managing the Essbase Server Permission to Create Unicode-Mode Applications

Oracle Essbase Administration Services Online Help

MaxL

display system

Oracle Essbase Technical Reference

Managing Unicode-Mode Applications

The topics in this section discuss processes for managing Unicode-mode applications.

Creating Unicode-Mode Applications

When you create an application, you can specify the application to be Unicode-mode-enabled.

  To create a Unicode-mode-enabled application, use a tool:

Tool

Topic

Location

Administration Services

Creating Unicode-Mode Applications

Oracle Essbase Administration Services Online Help

MaxL

create application

Oracle Essbase Technical Reference

Migrating Applications to Unicode Mode

When Essbase Server migrates a non-Unicode-mode application to Unicode mode, the character encoding in the application files is converted to UTF-8 encoding.

Before migrating application files to Unicode mode, perform the following tasks:

  • Back up all application and database files in the application.

    See the Oracle Hyperion Enterprise Performance Management System Backup and Recovery Guide.

  • If needed, apply the outline change files and then remove them.

    If present, outline change files reside in each database directory, with the database name as the file name and a .chg extension; for example, /sample/basic/basic.chg.

  • To avoid mixing Unicode encoding and non-Unicode encoding in log files, back up log files and then clear or remove them.

    Log files end with any of the following extensions: .log, .xcp, and .olg.

  • Grant Essbase Server permission to migrate applications to Unicode mode. See Setting Essbase Server to Unicode Mode.

  To migrate an application from non-Unicode mode to Unicode mode, use a tool:

Tool

Topic

Location

Administration Services

Migrating Applications to Unicode Mode

Oracle Essbase Administration Services Online Help

MaxL

alter application

Oracle Essbase Technical Reference

Text files, such as calculation scripts, report scripts, and data sources, are not converted to UTF-8 encoding. For Unicode-mode applications, text files can be encoded in UTF-8 or in non-Unicode locales. You can use Essbase Unicode File Utility to convert non-Unicode-encoded files to UTF-8. See Essbase Unicode File Utility.

Note:

If you choose to work with non-Unicode text files in your Unicode-mode application, ensure that you understand how Essbase determines the locales of non-Unicode text files. See Managing File Encoding.

Backing Up and Restoring Databases Between Unicode and Non-Unicode Applications

When working with Unicode and non-Unicode applications, Essbase does not allow a backed up database from a Unicode application to be restored to a non-Unicode application.

For a list of supported combinations of restoring backed up databases between Unicode and non-Unicode applications, see the Oracle Hyperion Enterprise Performance Management System Backup and Recovery Guide.

Viewing the Unicode-Related Mode of an Application

In Administration Services, the Unicode-related mode of an application is shown as an application property. In MaxL, it is displayed as the application type, with the following values:

  • 2, for non-Unicode-mode applications

  • 3, for Unicode-mode applications

  To see whether an application is a Unicode-mode application, use a tool:

Tool

Topic

Location

Administration Services

Monitoring Applications

Oracle Essbase Administration Services Online Help

MaxL

display application

Oracle Essbase Technical Reference

Using Control Characters in Report Scripts

When working with reports for non-Unicode-mode applications, Report Writer uses language-specific codes that enable columnar data to line up precisely. Because Unicode does not contain language-specific formatting codes within its encoding, report columns may not line up precisely.

Non-Unicode-mode applications that use single-byte code pages support the following Hexadecimal control characters in report scripts:

x20, x09, x0A, x0D, xB3, xC3, xC4, xC2, xC0, x0C, xB1

Unicode-mode applications and non-Unicode-mode applications that use multibyte code pages support the following Hexadecimal control characters in report scripts:

x20, x09, x0A, x0C, x0D

Working with Partitions

Consider the following situations when designing and working with partitions:

  • Partitions cannot connect non-Unicode-mode databases to Unicode-mode databases.

  • For transparent and replicated (but not linked) partitions, the application mode of both ends of the partitions must be the same—either Unicode mode or non-Unicode mode.

  • All databases in a partition must be in the same encoding.

  • Partitions across Unicode-mode databases can be administered by Unicode-mode clients; for example, Administration Services or MaxL scripts executed in Administration Services Console.

  • Non-Unicode-mode outlines containing multibyte characters cannot be synchronized by Unicode-mode clients, such as Administration Services and MaxL scripts. You can, however, use a client that is not Unicode-enabled or a non-Unicode mode client, such as MaxL Shell (essmsh).

Working with Logs

By default, the Essbase agent log file is encoded to the locale specified by the ESSLANG variable defined for Essbase Server. You can use the UNICODEAGENTLOG configuration setting to write the agent log file in UTF-8 encoding. With a UTF-8 font, all characters in the log file should be readable. See the Oracle Essbase Technical Reference.

Application and outline change log files for databases in Unicode-mode applications are UTF-8 encoded. To view:

  • Application logs, use Log Viewer or Log Analyzer in Administration Services, or a UTF-8 editor

  • Outline change logs, use a UTF-8 editor

You cannot change the encoding of log files related to Unicode-mode applications to non-Unicode encoding.

Managing File Encoding

Essbase supports many non-Unicode encodings (see Supported Locales). In addition, UTF-8 encoding is supported for Unicode-mode applications.

Because a bit combination can map to different characters in different encodings, you must understand how Essbase works with file encodings, particularly if you intend to use non-Unicode-encoded files with Unicode-mode applications.

Note:

Oracle recommends using UTF-8-encoded files for Unicode-mode applications shared across multiple locales. Using UTF-8 encoding is simpler, because you need not keep track of locales and encoding, and it can be more efficient, because Essbase Administration Server uses Unicode encoding internally, and no internal conversion between formats is needed.

The following topics describe how Essbase determines the encoding of files and how you manage files with different encoding.

How the Encoding of a File Is Determined

With non-Unicode-mode applications, Essbase and Administration Services assume that character text is encoded to the locale specified by the ESSLANG value defined for Essbase Server.

When Essbase works with Unicode-mode applications, it encodes character text in UTF-8 encoding internally and stores character text in UTF-8. Export files also are encoded in UTF-8. When Essbase works with Unicode-mode applications, it can also handle non-Unicode-encoded input files (such as script files, rules files, and data sources), converting them internally to UTF-8.

Note:

For Unicode-mode applications, Essbase requires that dbname.cfg query log settings file be encoded in UTF-8.

Essbase and Administration Services use file-encoding indicators (UTF-8 signature or locale indicator) to know whether a file is encoded in UTF-8 or in a supported non-Unicode encoding.

A locale indicator is optional for a non-Unicode input file whose encoding matches the locale of Essbase Server. If, however, the encoding does not match, you must provide a locale indicator. See Encoding Indicators.

UTF-8-encoded text files must include the UTF-8 signature.

Administration Services uses the following process to determine the encoding of a non-Unicode-encoded file:

  1. If a locale indicator is present in the file, Administration Services uses the specified encoding.

  2. If a locale indicator is not present, and the file is located within an application, Administration Services uses the encoding specified in the Essbase Server locale.

  3. It a locale indicator is not present, and the file is not located within an application, Administration Services determines the encoding based on the type of file:

    • Text files: Administration Services prompts for the encoding.

    • Outline and rules files: Administration Services uses the encoding specified in the Essbase Server locale.

When Essbase performs a dimension build or data load, the rules file and data file can have different encodings. For example, the text in a rules file can be in UTF-8 encoding, and the data source can be encoded to a non-Unicode computer locale.

Note:

When you use Administration Services Console to create script files or data sources, the appropriate encoding indicator is automatically included in the file. If you use any other tool to create Unicode-encoded text files, you must ensure that the UTF-8 signature is included. Non-Unicode-encoded text files require a locale indicator if the encoding is different from the Essbase Server locale.

The following Essbase system text files are encoded to the locale specified by the ESSLANG value defined for Essbase Server:

  • essbase.cfg

  • ESSCMD scripts

Encoding Indicators

To properly interpret text, such as member names, Essbase must know how it is encoded. Many files contain an encoding indicator, but occasionally you may be prompted to specify the encoding; for example, in the following cases:

  • Administration Services creates a file and stores it in a different location than the Essbase Server

  • Administration Services reads a file created by a non-Unicode, pre-7.0 release of Essbase

The type of encoding indicator depends on the type of file:

  • Files that are internal to applications and databases and that users cannot directly edit are primarily binary files and do not contain encoding indicators.

    Character text in these files is encoded based on the application mode:

    • Text in Unicode-mode application files is UTF-8 encoded.

    • Text in non-Unicode-mode application files is encoded to the locale specified in the ESSLANG variable of the Essbase Server where the application was created.

  • Binary files that you can edit (such as outline and rules files)

    As needed, Essbase keeps track internally of whether the character text is in UTF-8 encoding. If not UTF-8, Essbase uses an internal locale indicator to identify the locale used for character text encoding.

  • The following text files that you can edit use a UTF-8 signature or a locale indicator to indicate their encoding:

    • Calculation scripts

    • Report scripts

    • MaxL scripts

    • Data sources for dimension builds and data loads

    • Alias table import files (Administration Services requires alias table import files to be UTF-8 encoded)

Caution!

Do not use non-Unicode-encoded files containing locale indicators with pre-7.0 release Essbase Server installations, which are not Unicode enabled. To remove the locale indicators, use Essbase Unicode File Utility. See Essbase Unicode File Utility.

UTF-8 Signature

UTF-8-encoded text files must contain the UTF-8 signature, which is a mark at the beginning of a text file. This signature is visible in some third-party UTF-8 text editors.

Many UTF-8 text editors can create the UTF-8 signature, or you can use the Essbase Unicode File Utility to insert the UTF-8 signature into a file (see Essbase Unicode File Utility).

When you create a file using Administration Services Console, a UTF-8 signature is automatically inserted in the file.

Locale Indicator (Locale Header Record)

The locale indicator is a locale header record, which is an additional text record that identifies the encoding of a non-Unicode text file. You can insert the locale header record as the first record in a non-Unicode-encoded text file when you create the file, or you can use Essbase Unicode File Utility to add the header.

Caution!

Do not insert a locale header record in a UTF-8 encoded file. If a text file contains both types of encoding indicators, the locale header is read as the first data record.

The locale header record has the following format:

//ESS_LOCALE locale-name

locale-name is a supported Global C locale in the format that is used for the ESSLANG variable:

language_territory.code_page_name@sortsequence

The following example displays a locale header record for a specific Russian code page:

//ESS_LOCALE Russian_Russia.ISO-8859-5@Default

Note:

Essbase consults only the code_page_name portion of the record. The sortsequence specification does not affect sort sequences in report scripts.

The following rules also apply:

  • After locale-name, use a blank, tab or <end of line> to end the header.

  • You can include blanks or tabs in the following locations:

    • Before the keyword “//ESS_LOCALE

    • Between “//ESS_LOCALE” and locale-name

    • After the locale specification

For compatibility, Administration Services Console saves calculation scripts on a pre-7.0 release Essbase Server installation in a different format. Instead of prefixing the locale with //, Administration Services Console inserts the locale header between calculation script comment indicators:

/* */

Supported Locales

The following supported locales can be used in locale header records, in Essbase Unicode File Utility, and as ESSLANG variable values:

Arabic_SaudiArabia.ISO-8859-6@Default
Arabic_SaudiArabia.MS1256@Default
Croatian_Croatia.ISO-8859-2@Croatian
Croatian_Croatia.MS1250@Croatian
CyrillicSerbian_Yugoslavia.ISO-8859-5@Default
CyrillicSerbian_Yugoslavia.MS1251@Default
Czech_CzechRepublic.ISO-8859-2@Czech
Czech_CzechRepublic.MS1250@Czech
Danish_Denmark.ISO-8859-15@Danish
Danish_Denmark.IBM500@Danish
Danish_Denmark.Latin1@Danish
Danish_Denmark.MS1252@Danish
Dutch_Netherlands.IBM037@Default
Dutch_Netherlands.IBM500@Default
Dutch_Netherlands.ISO-8859-15@Default
Dutch_Netherlands.Latin1@Default
Dutch_Netherlands.MS1252@Default
English_UnitedStates.IBM037@Binary
English_UnitedStates.IBM285@Binary
English_UnitedStates.IBM500@Binary
English_UnitedStates.MS1252@Binary
English_UnitedStates.Latin1@Binary
English_UnitedStates.US-ASCII@Binary
Finnish_Finland.IBM500@Finnish
Finnish_Finland.ISO-8859-15@Finnish
Finnish_Finland.Latin1@Finnish
Finnish_Finland.MS1252@Finnish
French_France.IBM297@Default
French_France.IBM500@Default
French_France.ISO-8859-15@Default
French_France.Latin1@Default
French_France.MS1252@Default
German_Germany.IBM273@Default
German_Germany.IBM500@Default
German_Germany.ISO-8859-15@Default
German_Germany.Latin1@Default
German_Germany.MS1252@Default
Greek_Greece.ISO-8859-7@Default
Greek_Greece.MS1253@Default
Hebrew_Israel.ISO-8859-8@Default
Hebrew_Israel.MS1255@Default
Hungarian_Hungary.ISO-8859-2@Hungarian
Hungarian_Hungary.MS1250@Hungarian
Italian_Italy.IBM280@Default
Italian_Italy.IBM500@Default
Italian_Italy.ISO-8859-15@Default
Italian_Italy.Latin1@Default
Italian_Italy.MS1252@Default
Japanese_Japan.IBM930@Binary
Japanese_Japan.JapanEUC@Binary
Japanese_Japan.MS932@Binary
Korean_Korea.MS1361@Binary
Korean_Korea.MS949@Binary
Norwegian_Norway.IBM500@Danish
Norwegian_Norway.ISO-8859-10@Danish
Norwegian_Norway.ISO-8859-15@Danish
Norwegian_Norway.ISO-8859-4@Danish
Norwegian_Norway.Latin1@Danish
Norwegian_Norway.MS1252.Default
Portuguese_Portugal.IBM037@Default
Portuguese_Portugal.IBM500@Default
Portuguese_Portugal.ISO-8859-15@Default
Portuguese_Portugal.Latin1@Default
Portuguese_Portugal.MS1252@Default
Romanian_Romania.ISO-8859-2@Romanian
Romanian_Romania.MS1250@Romanian
Russian_Russia.ISO-8859-5@Default
Russian_Russia.MS1251@Default
Serbian_Yugoslavia.ISO-8859-2@Default
Serbian_Yugoslavia.MS1250@Default
SimplifiedChinese_China.IBM935@Binary
SimplifiedChinese_China.MS936@Binary
SimplifiedChinese_China.UTF-8@Binary
Slovak_Slovakia.ISO-8859-2@Slovak
Slovak_Slovakia.MS1250@Slovak
Slovenian_Slovenia.ISO-8859-10@Slovenian
Slovenian_Slovenia.ISO-8859-2@Slovenian
Slovenian_Slovenia.ISO-8859-4@Slovenian
Slovenian_Slovenia.MS1250@Slovenian
Spanish_Spain.IBM500@Spanish
Spanish_Spain.ISO-8859-15@Spanish
Spanish_Spain.Latin1@Spanish
Spanish_Spain.MS1252@Spanish
Swedish_Sweden.IBM500@Swedish
Swedish_Sweden.ISO-8859-15@Swedish
Swedish_Sweden.Latin1@Swedish
Swedish_Sweden.MS1252@Swedish
Thai_Thailand.MS874@Thai
TraditionalChinese_Taiwan.EUC-TW@Binary
TraditionalChinese_Taiwan.IBM937@Binary
TraditionalChinese_Taiwan.MS950@Binary
Turkish_Turkey.ISO-8859-3@Turkish
Turkish_Turkey.ISO-8859-9@Turkish
Turkish_Turkey.MS1254@Turkish
Ukrainian_Ukraine.ISO-8859-5@Ukrainian
Ukrainian_Ukraine.MS1251@Ukrainian

Essbase Unicode File Utility

You can use Essbase Unicode File Utility to convert non-Unicode-encoded text files to UTF-8 encoding, or to add or delete encoding indicators. This program supports the following operations:

  • Converting non-Unicode-encoded text files to UTF-8 encoding, including the UTF-8 signature.

  • Adding UTF-8 signatures to UTF-8-encoded text files.

  • Inserting a locale header record at the beginning of non-Unicode-encoded text files.

  • Adding a locale indicator to outline files (.otl) or rules files (.rul).

  • Removing locale indicators from files (the utility cannot remove UTF-8 signatures).

Located in the ESSBASEPATH/bin directory, Essbase Unicode File Utility is called essutf8.exe (in Windows) or ESSUTF8 (in UNIX). You can use the utility program with the following files:

  • Calculation scripts

  • Report scripts

  • MaxL scripts

  • Text data sources for dimension builds and data loads

  • Alias table import files

  • Outline files

  • Rules files

For information about this utility and its command syntax, see the Oracle Essbase Technical Reference.