|
Oracle® Application Server Reports Services Publishing Reports to the Web
10g (9.0.4) Part Number B13673-01 |
|
|
|
|
Oracle® Application Server Reports Services Publishing Reports to the Web
10g (9.0.4) Part Number B13673-01 |
|
|
|
|
When you design reports to be deployed to different countries, you must consider such things as character sets and text reading order. OracleAS Reports Services includes the support you need to address any issues related to these considerations: National Language Support (NLS) for character sets and bidirectional support for text reading order.
Oracle NLS makes it possible to design applications that can be deployed in several different languages. Oracle supports most European, Middle Eastern, and Asian languages. NLS enables you to:
Use international character sets (including multibyte character sets)
Display data according to the appropriate language and territory conventions
Extract strings that appear in your interface and translate them
Bidirectional support enables you to display data in either a left-to-right or right-to-left orientation, depending on the requirements of your audience.
This chapter provides a look at NLS architecture, including NLS settings relevant to Reports; explains how to specify character sets in a JSP; and offers information on bidirectional, Unicode, and translation support available through Oracle9i. It includes the following main sections:
Oracle NLS architecture consists of two parts:
Language-independent functions handle manipulation of data in an appropriate manner, depending on the language and territory of the runtime operator. Data is automatically formatted according to local date and time conventions.
With language-dependent data, you can isolate your data. This enables your application to deal only with translating strings that are unique to your application.
Because the language-dependent data is separate from the code, the operation of NLS functions is governed by the data supplied at runtime. New languages can be added and language-specific application characteristics can be altered without requiring code changes. This architecture also enables language-dependent features to be specified for each session.
NLS environment variables are automatically set to default values during Oracle Application Server installation.
|
Note: On a given OracleAS Reports Services host machine, you can specify only one language. If you are providing application server services to a multilingual audience, you must have a separate host machine for each language. |
Table 18-1 lists and describes NLS-related environment variables that are particularly relevant to OracleAS Reports Services.
|
Note: For more information on all NLS environment variables, see the Oracle Application Server 10g Globalization Guide on the Oracle Technology Network, (http://otn.oracle.com).
|
Table 18-1 Environment variables particularly related to OracleAS Reports Services
| Variable | Description |
|---|---|
NLS_LANG
|
Relevant to OracleAS Reports Services. The language settings used by OracleAS Reports Services. |
DEVELOPER_NLS_LANG
|
The language for Reports Builder. |
USER_NLS_LANG
|
The language for the Reports Runtime component. |
The NLS_LANG environment variable specifies the language, territory, and character set settings to be used by OracleAS Reports Services. Specifically:
The language for messages displayed to the user
The default format masks used for DATE and NUMBER data types
The sorting sequence
The character set
|
Note: This environment variable is set automatically when you install Oracle Application Server. Refer to Defining the NLS_LANG Environment Variable for more information about changing the environment variable after installing Oracle Application Server. |
NLS_LANG=language_territory.charset
The values are defined as follows:
Specifies the language and its conventions for displaying messages (including error messages) as well as day and month names. If language is not specified, then the value defaults to American.
Specifies the territory and its conventions for default date format, decimal character used for numbers, currency symbol, and calculation of week and day numbers. If territory is not specified, then the value defaults to America.
Specifies the character set in which data is displayed. This should be a character set that matches your language and platform. This option also specifies the character set used for displaying messages.
|
Note: When you use features like OracleAS Portal Security, Portal Destination, and Job Status Repository, the JDBC database connections made by OracleAS Reports Services may override the initialNLS_LANG setting. This change may in turn affect the behavior of the running report, such as bidirectional output in PDF. On UNIX platforms, you can work around this issue by setting the NLS_LANG explicitly in report.sh. You can also use the new environment switching functionality to dynamically set the environment for reports. Refer to Dynamic Environment Switching, for more information.
|
Refer to the Oracle Application Server 10g Globalization Guide for more information on the commonly used language, territory, and character values for NLS_LANG.
Your NLS_LANG setting should take into account regional differences between countries that use (basically) the same language. For example, if you want to run in French (as used in France), then you set the NLS_LANG environment variable:
NLS_LANG=FRENCH_FRANCE.WE8ISO8859P1
If you want to run in French, but this time as used in Switzerland, you would set the NLS_LANG environment variable:
NLS_LANG=FRENCH_SWITZERLAND.WE8ISO8859P1
|
Note: The language for therwserver pages such as help, showjobs,showenv and error messages are delivered from machine's locale (or LANG on Solaris) and not NLS_LANG. For example, you have set your middle tier locale to French and NLS_LANG=JAPANESE_JAPAN.JA16SJIS, the showjobs or error messages will be displayed in French, not in Japanese.
|
You define the NLS_LANG environment variable in the same way you define other environment variables on your Windows or UNIX operating system.
To define the NLS_LANG environment variable on Windows, do the following:
|
Note: Back up your registry before you edit it. |
Expand the HKEY_LOCAL_MACHINE node, then expand the SOFTWARE node.
Click ORACLE to display the Oracle environment variables in the right panel of the Registry Editor.
Double-click the NLS_LANG environment variable.
Type the new value for NLS_LANG in the Value data text box.
Click OK.
The character set component of the NLS environment variables specifies the character set in which data is represented in your environment. When data is transferred from a system using one character set to a system using another character set, it is processed and displayed correctly on the second system, even though some characters might be represented by different binary values in the character sets.
If you are designing a multilingual application, or even a single-language application that runs with multiple character sets, you need to determine the character set most widely used at runtime and then generate with the NLS environment variable set to that particular character set.
If you design and generate an application in one character set and run it in another character set, performance can suffer. Furthermore, if the runtime character set does not contain all the characters in the generate character set, then question marks appear in place of the unrecognized characters.
Portable Document Format (PDF) supports multibyte character sets.
There might be situations where you create an application with a specific font but find that a different font is being used when you run that application. You would most likely encounter this when using an English font (such as MS Sans Serif or Arial) in environments other than Western European. This occurs because OracleAS Reports Services checks to see if the character set associated with the font matches the character set specified by the language environment variable. If the two do not match, OracleAS Reports Services automatically substitutes the font with another font whose associated character set matches the character set specified by the language environment variable. This automatic substitution assures that the data being returned from the database gets displayed correctly in the application.
|
Note: If you enter local characters using an English font, then Windows does an implicit association with another font. |
There might be cases, however, where you do not want this substitution to take place. You can avoid this substitution by mapping all desired fonts to the WE8ISO8859P1 character set in the font alias file (uifont.ali). For example, if you are unable to use the Arial font in your application, you can add the following line to your font alias file (located at ORACLE_HOME\TOOLS\COMMON\):
ARIAL.....=ARIAL.....WE8ISO8859P1
Each line in the uifont.ali file takes the following syntax:
Face.Size.Style.Weight.Width.CharSet=Face.Size.Style.Weight.Width.CharSet
In this example, you’re saying that any ARIAL font should be mapped to the same value, but with the WE8ISO8859P1 character set.
Refer to NLS Environment Variables for more information about the language environment variables.
While the character set ensures that the individual characters needed for each language are available, support for national conventions provides correct localized display of data items.
The specified language determines the default conventions for the following characteristics:
Language for day and month names and their abbreviations (specified in the SQL functions TO_CHAR and TO_DATE)
Default sorting sequence for character data when ORDER BY is specified (GROUP BY uses a binary sort unless ORDER BY is specified)
Affirmative and negative response strings
For example, if the language is set to French, then the following messages in English are converted to French:
English: ORA-00942: table or view does not exist FRM-10043: Cannot open file. French: ORA-0092: table ou vue inexistante FRM-10043: Ouverture de fichier impossible
The specified territory determines the conventions for the following default date and numeric formatting characteristics:
Date format
Decimal character and group separator
Local currency symbol
ISO currency symbol
Week start day
Credit and debit symbol
ISO week flag
List separator
For example, if the territory is set to France, then the numbers are formatted using a comma as the decimal character.
If you must use two sets of resource and message files at the same time, then two other language environment variables are available. These can be used after Oracle Application Server installation is completed.
DEVELOPER_NLS_LANG
USER_NLS_LANG
The syntax for DEVELOPER_NLS_LANG and USER_NLS_LANG is the same as for the NLS_LANG environment variable. That is:
DEVELOPER_NLS_LANG=language_territory.charset USER_NLS_LANG=language_territory.charset
Use these environment variables in lieu of the NLS_LANG environment variable in the following situations:
You prefer to use the Reports Builder in English, but you are developing an application for another language. DEVELOPER_NLS_LANG and USER_NLS_LANG environment variables allow you to use different language settings for the Reports Builder and Reports Runtime.
You are creating an application to run in a language for which a local language version of Reports Builder is not currently available.
If these environment variables are not specifically set, then NLS_LANG default values will be used.
If you are producing HTML with your JSP, then you may need to add a character set to your JSP file using the following syntax (this one specifies a Japanese character set):
<META http-equiv="Content-Type" content="text/html;charset=shift_jis">
Additionally, if you plan on outputting a report to XML, you may wish to include a character set in the report’s XML Prolog Value property, following this syntax:
<?xml version="1.0" encoding="shift_jis" ?>
In both instances, the values expressed for the character set should call a character set that is compatible with the one specified for the host environment. The values for character sets used on the Web are different from the values expressed in the NLS_LANG environment variable. Table 18-2 lists commonly used values for the IANA charset or encoding parameter:
|
Note: The values forcharset and encoding are not case sensitive. You can enter them in lower- or uppercase.
|
|
Note: To set the character set in a .rdf file that you plan to use to generate HTML, you must ensure that the Before Report Escape property includes the following:charset="text/html;charset=&encoding"
|
Table 18-2 Valid Values for the IANA charset
| Languages | IANA character set name |
|---|---|
| AMERICAN | ISO-8859-1, ISO-8859-15, windows-1252, US-ASCII, UTF-8 |
| ARABIC | ISO-8859-6, windows-1256, UTF-8 |
| ASSAMESE | UTF-8 |
| BANGLA | UTF-8 |
| BENGALI | UTF-8 |
| BRAZILIAN PORTUGESE | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| BULGARIAN | ISO-8859-5, windows-1251, KOI8-R, UTF8 |
| CANADIAN FRENCH | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| CATALAN | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| CROATIAN | ISO-8859-2, windows-1250, UTF-8 |
| CZECH | ISO-8859-2, windows-1250, UTF-8 |
| DANISH | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| DUTCH | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| EGYPTIAN | ISO-8859-6, windows-1256, UTF-8 |
| ENGLISH | ISO-8859-1, ISO-8859-15, windows-1252, US-ASCII, UTF-8 |
| ESTONIAN | ISO-8859-4, ISO-8859-13, windows-1257, UTF-8 |
| FINNISH | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| FRENCH | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| GERMAN DIN | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| GERMAN | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| GREEK | ISO-8859-7, windows-1253, UTF-8 |
| GUJARATI | UTF-8 |
| HEBREW | ISO-8859-8-I, windows-1255, UTF-8 |
| HINDI | UTF-8 |
| HUNGARIAN | ISO-8859-2, windows-1250, UTF8 |
| ICELANDIC | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| INDONESIAN | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| ITALIAN | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| JAPANESE | EUC-JP, Shift_JIS, UTF-8 |
| KANNADA | UTF-8 |
| KOREAN | EUC-KR, UTF-8 |
| LATIN AMERICAN SPANISH | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| LATVIAN | ISO-8859-4, ISO-8859-13, windows-1257, UTF-8 |
| LITHUANIAN | ISO-8859-4, ISO-8859-13, windows-1257, UTF-8 |
| MALAY | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| MALAYALAM | UTF-8 |
| MARATHI | UTF-8 |
| MEXICAN SPANISH | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| NORWEGIAN | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| ORIYA | UTF-8 |
| POLISH | ISO-8859-2, windows-1250, UTF8 |
| PORTUGESE | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| PUNJABI | UTF-8 |
| ROMANIAN | ISO-8859-2, windows-1250, UTF-8 |
| RUSSIAN | ISO-8859-5, windows-1251, KOI8-R, UTF-8 |
| SIMPLIFIED CHINESE | GBK, GB18030, UTF-8 |
| SLOVAK | ISO-8859-2, windows-1250, UTF-8 |
| SLOVENIAN | ISO-8859-2, windows-1250, UTF-8 |
| SPANISH | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| SWEDISH | ISO-8859-1, ISO-8859-15, windows-1252, UTF-8 |
| TAMIL | UTF-8 |
| TELUGU | UTF-8 |
| THAI | TIS-620, UTF-8 |
| TRADITIONAL CHINESE | Big5, Big5-HKSCS, UTF-8 |
| TURKISH | ISO-8859-9, windows-1254, UTF-8 |
| UKRANIAN | ISO-8859-5, windows-1251, KOI8-U, UTF-8 |
| VIETNAMESE | windows-1258, UTF-8 |
Bidirectional support enables you to design applications in Middle Eastern and North African languages whose natural writing direction is right to left. Bidirectional support enables you to control:
Reading order, which includes text direction (e.g., right to left or left to right)
Alignment, which includes switching point-of-origin from upper left to upper right
When you are designing bidirectional applications, you might want to use the NLS environment variables DEVELOPER_NLS_LANG and USER_NLS_LANG rather than NLS_LANG. For example, if you want to use an American interface while developing an Arabic application in a Windows environment, then set these environment variables as follows:
DEVELOPER_NLS_LANG=AMERICAN_AMERICA.AR8MSWIN1256 USER_NLS_LANG=ARABIC_UNITED ARAB EMIRATES.AR8MSWIN1256
Note that, in this example, the DEVELOPER_NLS_LANG environment variable uses an Arabic character set. Refer to NLS Environment Variables for more information about environment variables.
|
Note: When you use features like OracleAS Portal Security, Portal Destination, and Job Status Repository, the JDBC database connections made by OracleAS Reports Services may override the initialNLS_LANG setting. This change may in turn affect the behavior of the running report, such as bidirectional output in PDF. On UNIX platforms, you can work around this issue by setting the NLS_LANG explicitly in report.sh. You can also use the new environment switching functionality to dynamically set the environment for reports. Refer to Dynamic Environment Switching, for more information.
|
Unicode is a global character set that allows multilingual text to be displayed in a single application. This enables multinational corporations to develop a single multilingual application and deploy it worldwide.
Global markets require a character set that:
Allows a single implementation of a product for all languages, yet is simple enough to be implemented everywhere
Contains all major living scripts
Supports multilingual users and organizations
Enables worldwide interchange of data via the Internet
OracleAS Reports Services provides Unicode support. If you use Unicode, you are able to display multiple languages, both single-byte languages such as Western Europe, Eastern Europe, Bidirectional Middle Eastern, and multibyte Asian languages such as Chinese, Japanese, and Korean (CJK) in the same application.
Use of a single character set that encompasses all languages eliminates the need to have various character sets for various languages. For example, to display a multibyte language such as Japanese, the NLS_LANG environment variable must be set to the following:
NLS_LANG=JAPANESE_JAPAN.JA16SJIS
To display a single-byte language such as German, NLS_LANG must be set to the following:
NLS_LANG=GERMAN_GERMANY.WE8ISO8859P1
The obvious disadvantage of this scheme is that applications can only display characters from one character set at a time. Mixed character set data is not possible.
With the Unicode character set, you can set the character set portion of NLS_LANG to UTF8 instead of a specific language character set. This allows characters from different languages and character sets to be displayed simultaneously. For example, to display Japanese and German together on the screen, the NLS_LANG variable must be set to one of the following:
NLS_LANG=JAPANESE_JAPAN.UTF8 NLS_LANG=GERMAN_GERMANY.UTF8
Unicode capability gives the application developer and end user the ability to display multilingual text in a report. This includes text from a database containing Unicode, multilingual text, text in graphical user interface (GUI) objects, text input from the keyboard, and text from the clipboard. OracleAS Reports Services currently supports Unicode on Windows.
|
Note: If you develop applications for the Web, then you can use Unicode because of the Unicode support provided by Java through the browser. |
OracleAS Reports Services relies on the operating system for the font and input method for different languages. To enter and display text in a particular language, you must be running a version of the operating system that supports that language. Font support is limited but not restricted to the operating system font.
Windows NT release 4.0 and later versions provide True Type Big Fonts. These fonts contain all the characters necessary to display or print multilingual text. If you try to type, display, or print multilingual text and see unexpected characters, then you are probably not using a Big Font. Big Fonts provided by Microsoft under Windows NT release 4.0 and later, are as follows:
Arial
Courier New
Lucida Console
Lucida Sans Unicode
Times New Roman
Third-party Unicode fonts are also available.
To enable Unicode support, set the NLS_LANG environment variable as follows:
NLS_LANG=language_territory.UTF8
Refer to NLS Environment Variables for more information about environment variables.
You can use the SQL command ALTER SESSION to override some NLS defaults, if you are connected to an Oracle database via the USERID keyword or have connected via the Connect dialog in Reports Builder. For example, suppose you are building a report against an Oracle database that will publish data to different geographic locations. You might want to change the currency symbol, thousands grouping, and decimal indicator that the Oracle database uses when it formats a currency field depending on a user parameter. You could accomplish this task in several ways, but one method is to alter the Oracle database session NLS_LANG variable in a Before Report trigger.
|
Note: ALTER SESSION does not apply to pluggable data source queries (for example, JDBC and XML). |
|
Note: For more information on the ALTER SESSION command, see the Oracle9i SQL Reference, available on the Oracle Technology Network, (http://otn.oracle.com).
|
In any OracleAS Reports Services application, you see many types of messages, including:
Error messages from the database
Runtime error messages produced by OracleAS Reports Services
Messages and boilerplate text defined as part of the application
If the NLS environment variable is set correctly and the appropriate message files are available, then translation of messages for the first two items is done for you. To translate messages and boilerplate text defined as part of the application, you can use the Oracle translation tool, TranslationHub, and you might also find it useful to use PL/SQL Libraries for strings of code.
|
Note: You'll find information about using TranslationHub on the Oracle9iDS documentation CD and on the Oracle Technology Network, (http://otn.oracle.com).
|
Manual translation is required for constant text within a PL/SQL block because that text is not clearly delimited, but is often built up from variables and pieces of strings. To translate these strings, you can use PL/SQL libraries to implement a flexible message structure.
You can use attachable PL/SQL libraries to implement a flexible message function for messages that are displayed programmatically by the built-in routine SRW.MESSAGE, or by assigning a message to a display item from a trigger or procedure. The library can be stored on the host and dynamically attached at runtime. At runtime, based on a search path, you can pull in the attached library. For example, a library might hold only the Italian messages:
FUNCTION nls_appl_mesg(index_no NUMBER)
RETURN CHAR
IS
msg CHAR(80);
BEGIN
IF index_no = 1001 THEN
msg := 'L''impiegato che Voi cercate non esiste...';
ELSIF index_no = 1002 THEN
msg := 'Lo stipendio non puo essere minore di zero.';
ELSIF ...
.
.
ELSE
msg := 'ERRORE: Indice messaggio inesistente.';
END IF;
RETURN msg;
END;
A routine like this could be used anywhere a character expression would normally be valid. For example, to display text with the appropriately translated application message, you might include the following code:
srw.message(1001,nls_appl_mesg(1001));
To change the application to another language, simply replace the PL/SQL library containing the nls_appl_mes function with a library of the same name containing the nls_appl_mesg function with translated text.
