18 Implementing Globalization and Bidirectional Support

18.1 Globalization Support Architecture

Globalization support architecture consists of two parts:

• Language-Independent Functions

• Language-Dependent Data

18.2 Globalization Support Environment Variables

Globalization support environment variables are automatically set to default values during Oracle Application Server installation.

Table 18-1 lists and describes globalization support-related environment variables that are particularly relevant to OracleAS Reports Services.

NLS_LANG=language_territory.charset

NLS_LANG=FRENCH_FRANCE.WE8ISO8859P1

NLS_LANG=FRENCH_SWITZERLAND.WE8ISO8859P1

ARIAL.....=ARIAL.....WE8ISO8859P1

English:
ORA-00942: table or view does not exist
REP-0110: Unable to open file.

French:
ORA-0092: table ou vue inexistante
REP-0110: Impossible d'ouvrir le fichier

DEVELOPER_NLS_LANG=language_territory.charset
USER_NLS_LANG=language_territory.charset

18.3 Specifying a Character Set in a JSP or XML File

If you are running the Web layout of your JSP report, then you may need to add a character set to your JSP file using the following syntax (the following example specifies a Japanese character set):

<%@ page contentType="text/html;charset=Shift_JIS" %>
<META http-equiv="Content-Type" content="text/html;charset=Shift_JIS">

<?xml version="1.0" encoding="&Encoding" ?>

The values expressed for the character set should call a character set that is compatible with the one specified for OracleAS Reports Services. The values for character sets used on the Web (IANA-defined character sets) are different from the values expressed in the NLS_LANG environment variable. Table 18-2 lists commonly used IANA-defined character sets for the charset parameter:

18.4 Bidirectional Support

Bidirectional support enables you to design applications in those languages whose natural writing direction is right to left, such as Middle Eastern and North African languages. Bidirectional support enables you to control:

• Layout direction, which includes displaying items with labels at the right of the item and correct placement of check boxes and radio buttons.

• Reading order, which includes text direction (for example, 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 globalization support environment variables DEVELOPER_NLS_LANG and USER_NLS_LANG rather than inheriting the NLS_LANG settings. 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. For more information, refer to Section 18.2, "Globalization Support Environment Variables".

On Windows, when you generate PDF output with font subsetting enabled for languages that read right to left (such as Hebrew and Arabic), Oracle Reports 10g Release 2 (10.1.2) introduces an enhancement that ensures text will be accurately right-aligned (refer to Section 6.4, "Generating a Bidirectional (BiDi) PDF File").

On UNIX, you may continue to see misalignment of right-aligned text in PDF output for languages that read right to left. To work around this issue, use fixed width fonts instead of variable width fonts. For example, Miriam Fixed True Type font (Hebrew) is a fixed width font available on Windows 2000, and can be used for font subsetting on UNIX platforms to correct any font alignment issues with Hebrew fonts. For more information about resolving font issues across different platforms, see Chapter 7, "Resolving Cross-Platform Porting Issues".

18.5 Unicode

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 through the Internet.

This section discusses the following aspects of Unicode in Oracle Reports:

• Unicode Support

• Unicode Font Support

• Enabling Unicode Support

NLS_LANG=JAPANESE_JAPAN.JA16SJIS

NLS_LANG=GERMAN_GERMANY.WE8ISO8859P1

NLS_LANG=JAPANESE_JAPAN.UTF8
NLS_LANG=GERMAN_GERMANY.UTF8
NLS_LANG=AMERICAN_AMERICA.UTF8

NLS_LANG=language_territory.UTF8

18.6 Translating Applications

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_LANG 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.

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 SRW.MESSAGE built-in procedure, 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.

18.7 Troubleshooting Globalization Issues

To help resolve globalization issues that may occur in your multilingual applications, this section provides the following troubleshooting information:

• Embedding a Character Set in a JSP file Dynamically

• Setting Globalization Support Environment Variables

• Repairing Garbled Fonts When Using the WE8ISO8859P15 Character Set

• Opening or Running an Encoded JSP Report

• Resolving ERR-063001 xxx.dtd null

• Running Oracle Reports in a Japanese Environment on HP-UX

Embedding a Character Set in a JSP file Dynamically

In Oracle Reports, Web report templates are configured for Western European character encoding by default. However, for other languages, you can specify the character encoding for every JSP file by using both the charset attribute of the <Meta> tag and the <%@page%> page directive.

To dynamically associate the appropriate character encoding with the JSP file, you can make the following modifications:

1. Edit the rw*.html files and the blank_template.jsp file:

   1. Modify the page directive to read

      <%@ page contentType="text/html;charset=yourIANAencoding" %>
      
      

      where:

      yourIANAencoding is the IANA-defined character set name that corresponds to the NLS_CHARACTERSET portion of the NLS_LANG variable.

   2. Modify the <Meta> tag inside the <Head> tag to read:

      <meta http-equiv="Content-Type"
      content="text/html;charset=yourIANAencoding" />
      

      
      

      Note: The template files; that is, rw*.html, and blank_template.jsp, are located in the ORACLE_HOME/reports/templates/ directory.

      
      

2. Edit the template.xsl (ORACLE_HOME/reports/templates/) file:

   1. Modify the <xsl:output> tag to read:

      <xsl:output
           method="jsp"
           indent="yes"
           encoding="yourIANAencoding"
         />
      
      

      where

      yourIANAencoding is the IANA-defined character set name that corresponds to the NLS_CHARACTERSET portion of the NLS_LANG variable.

   2. Add the page directive to the file:

      <%@ page contentType="text/html;charset=yourIANAencoding" %>
      
      

   3. Add or modify the <META> tag inside the <HEAD> tag:

      <meta http-equiv="Content-Type"
      content="text/html;charset=yourIANAencoding" />
      
      

      where

      yourIANAencoding is the IANA-defined character set name that corresponds to the NLS_CHARACTERSET portion of the NLS_LANG variable.

Setting Globalization Support Environment Variables

The Tk2Motif.rgb file contains resource settings for the Motif version of the Oracle Toolkit. For example, it specifies the font mapping between the character set used by Oracle Reports, specified in NLS_CHARACTERSET, and X fonts.

Oracle Reports looks for this file in the directory ORACLE_HOME/guicommon/tk/admin/language, where language is derived from the language setting in NLS_LANG.

If the file does not exist, then Oracle Reports looks for the default version in ORACLE_HOME/guicommon/tk/admin. This version is configured for WEISO8859P1, the Western European character set.

If your NLS_LANG or NLS_CHARACTERSET specifies a character set that is not normally used for the language you have set in NLS_LANG, then Oracle Reports generates an error.

For example, if you have set NLS_LANG=AMERICAN_AMERICA.JA16EUC, then Oracle Reports locates Tk2Motif.rgb in the directory ORACLE_HOME/guicommon/tk/admin/. The language setting in NLS_LANG is AMERICAN, and there is no language subdirectory associated with AMERICAN, so Oracle Reports uses the default file. Since this version is designed for WE8ISO8859P1, and your NLS_LANG character set is JA16EUC, Oracle Reports generates the error REP-3000.

To work around this problem, set the value of the environment variable TK_UNKNOWN to the location of your character set-specific Tk2Motif.rgb file.

For example, if NLS_LANG=AMERICAN_AMERICA.JA16EUC, then set TK_UNKNOWN=ORACLE_HOME/guicommon/tk/admin/JA. Even though your language is set to AMERICAN, Oracle Reports will use the Tk2Motif.rgb file in the JA language subdirectory.

Repairing Garbled Fonts When Using the WE8ISO8859P15 Character Set

You may see garbled output when you run a multibyte report on UNIX with we8iso8859p15 character set.

To work around this issue, you must do the following:

1. Make an entry for the fonts used in your default printer's .ppd file. This file is located in the following directory:

   $ORACLE_HOME/guicommon/tk/admin
   
   

   
   

   Note: The entries are for the fonts that appears garbled in the report output.

   
   

2. Set the encoding scheme in the font's AFM file to FontSpecific if it is AdobeStandardEncoding. Thus, the following entry in the AFM file:

   EncodingScheme AdobeStandardEncoding
   
   

   must change to:

   EncodingScheme FontSpecific
   

Opening or Running an Encoded JSP Report

If your JSP report's character encoding (for example, EUC-JP) differs from the character set portion of the NLS_LANG environment variable (for example, JA16SJIS), then you will get the following errors:

• when running the JSP file:

  REP-6106 or 6104 with javax.servlet.jsp.JspException  (multibyte)
  REP-0495 Unable to tokenize the query (singlebyte)
  
  

• when opening the JSP file using Reports Builder:

  REP-0069 Internal Error or REP-6106
  
  

To work around this issue, you must ensure that your JSP report's character encoding matches the IANA-defined character set corresponding to Oracle Reports' character set portion of the NLS_LANG variable.

For example:

JSP Report encoding:

<%@ page contentType="text/html;charset=EUC-JP" %>
<META http-equiv="Content-Type" content="text/html;charset=EUC-JP">

This JSP file needs to be encoded in the character set (EUC-JP).

Oracle Reports encoding:

NLS_LANG=JAPANESE_JAPAN.JA16EUC

In this example, the JSP report's encoding (EUC-JP) matches Oracle Reports' character set portion of NLS_LANG; that is, JA16EUC.

Resolving ERR-063001 xxx.dtd null

When you create a report against an XML data source, you must ensure that the encoding of both the XML file (data source) as well as the DTD matches the encoding of Oracle Reports.

When you create an XML report against a table -- for example, a Japanese table-- the group element name is in the table's language that is Japanese. To match the data source, you should set the group's element name in the DTD to Japanese. The XML and DTD files can be in any encoding that supports Japanese, for example, Shift_JIS, EUC-JP, or UTF-8. However, when the encoding of the XML data source as well as the DTD differs from Oracle Reports, you will see the following error:

ERR-063001 xxx.dtd null

To work around this issue, you must ensure that both the data source XML files as well as the DTD file for an XML report is encoded in the character set portion of Reports Runtime NLS_LANG.

For example, if your NLS_LANG=JAPANESE_JAPAN.JA16SJIS, then both your data source XML file as well as your DTD file should be encoded in Shift_JIS.

Running Oracle Reports in a Japanese Environment on HP-UX

If you want to use Oracle Reports in the HP-UX Japanese environment with NLS_LANG=JAPANESE_JAPAN.JA16SJIS, you will need to modify the appropriate Tk2Motif.rgb file before using Oracle Reports because this file contains EUC encoded Japanese resources.

Convert the Tk2Motif.rgb file to Shift-JIS encoding, or remove the last seven entries from this file. Otherwise, Oracle Reports may fail.