In This Section:
Setting Up a Computer for Unicode Support
Naming Applications and Databases
Managing Unicode-Mode Essbase Servers
Managing Unicode-Mode Applications
The information in this chapter applies to block storage and aggregate storage databases.
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.
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.
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.
The topics in this section discuss processes for managing Unicode-mode Essbase Servers.
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: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:
The topics in this section discuss processes for managing Unicode-mode applications.
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.
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.
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. |
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.
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
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.
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).
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.
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.
The following topics describe how Essbase determines the encoding of files and how you manage files with different encoding.
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.
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:
If a locale indicator is present in the file, Administration Services uses the specified encoding.
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.
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:
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.
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:
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:
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:
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-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.
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.
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-namelocale-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:
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:
/* */
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
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.
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:
For information about this utility and its command syntax, see the Oracle Essbase Technical Reference.