38 Building a Report with Multibyte Characters for PDF Output

In this chapter, you will learn about reports that include multibyte characters. By following the steps in this chapter, you can generate the PDF report output shown in Figure 38-1 and Figure 38-2.

Figure 38-1 Output of the multibyte character set UTF8 report in Japanese

Description of "Figure 38-1 Output of the multibyte character set UTF8 report in Japanese"

Figure 38-2 Output of the same multibyte character set UTF8 report in Polish

Description of "Figure 38-2 Output of the same multibyte character set UTF8 report in Polish"

Concepts

With multibyte character support built into Oracle Reports, you can publish reports in any language for your global enterprise. You can produce reports that display text in multibyte character sets, such as Simplified Chinese, Traditional Chinese, Japanese, Korean, and Unicode.
Oracle Reports supports multibyte characters in various output formats, including PDF. In this chapter, you will build a multibyte character set report using the UTF8 character set to generate PDF output.
You can generate a portable PDF file using Oracle Reports. The PDF features, such as font subsetting and embedding, enable you to generate PDF files that can be viewed on an end user's computer without having special fonts installed.

Note:
You must have Acrobat Reader installed on your computer to view PDF output.
When you use PDF font embedding, you include the entire font set in the PDF file.
PDF font embedding in Oracle Reports is for single-byte Type1 fonts and not for TrueType fonts. Therefore, if you want to include specific TrueType fonts in your report, you must first convert these fonts to Type1 fonts using any of the available third party tools.

Tip:
Make sure that you have the necessary licenses for the fonts before embedding them in your output PDF file.
Although PDF font subsetting and font embedding are mutually exclusive, PDF font subsetting is a variant of PDF font embedding. PDF font subsetting is the preferred method of creating multibyte reports because it works for both single and multibyte fonts.
With the font subsetting, the PDF output file contains information of only those characters that appear in the document. Therefore, this feature produces more efficient output in terms of file size. Both font embedding and subsetting eliminate the dependency of installing specific fonts on your computer.

Note:

For more information, see "Using PDF in Oracle Reports" in the Oracle Application Server Reports Services Publishing Reports to the Web manual, available on the Oracle Technology Network Oracle Reports Documentation page (http://www.oracle.com/technology/documentation/reports.html).

Example Scenario

In this example, you have an international business with offices in the United States, Japan, and Poland. In the organization, local managers have control of the inventory of the warehouses. Offices in different locations want to print the list of products in their preferred language. You will create a report in PDF format that contains multibyte characters for the Web and paper output.

As you build this example report, you will:

Create the query and paper layout for a multibyte report using the Report Wizard.
Display multibyte characters in the report using the UTF8 TrueType font.
Create a PDF document of your report.

To see a sample multibyte character set report, open the examples folder named Multibyte\result, then open the Oracle Reports example named Multibyte_UTF8.rdf. For details on how to open it, see "Accessing the Example Reports" in the Preface.

38.1 Prerequisites for this example

To build the example in this chapter, you must have the example files we have provided (see "Example Scenario", above), as well as access to the Order Entry sample schema provided with the Oracle Database. If you do not know if you have access to this sample schema, contact your database administrator. You must also have Acrobat Reader installed on your system.

Note:

Due to some limitations of Oracle Reports regarding use of the UTF-8 character set and multibyte fonts on UNIX, it is recommended to build this report only on Windows. To deploy a multibyte report on UNIX, refer the chapter "Fixing Cross-platform Porting Issues" in the Oracle Application Server Reports Services Publishing Reports to the Web manual.

Perform the following set up activities before you run the report:

In the Windows registry, under IDS_HOME in the ORACLE key, set NLS_LANG to AMERICAN_AMERICA.UTF8.

Tip:
Back up your registry before editing it as working with registry keys can cause the system to become unstable.

Open the uifont.ali file and edit it to specify the TrueType font file name. Type "Arial Unicode MS" = "ARIALUNI.TTF" under the [PDF:Subset] section. After including the line, the uifont.ali file should look like:

Figure 38-3 uifont.ali file edited to include the TrueType font file name

Description of "Figure 38-3 uifont.ali file edited to include the TrueType font file name"

Note:

On Windows, the uifont.ali file is located in: ORACLE_HOME\tools\common. On UNIX, it is located in: ORACLE_HOME/guicommon/tk/admin. The uifont.ali file defines the font aliases used by Oracle Reports and is extremely useful for cross-platform development. This file enables you to define which fonts to substitute when a particular font is unavailable. For more information, see the "Font Related Features" section in the "Using PDF in Oracle Reports" chapter in the Oracle Application Server Reports Services Publishing Reports to the Web manual, available on the Oracle Technology Network Oracle Reports Documentation page (http://www.oracle.com/technology/documentation/reports.html).

In the Windows registry under the Oracle key and IDS_HOME, add the location of the ARIALUNI.TTF TrueType font file to the value of REPORTS_PATH. For example, C:\WINNT\Fonts.

Note:
Install the TrueType font file ARIALUNI.TTF into C:\WINNT\Fonts, if it is not already there.

38.2 Create the query and paper layout for a multibyte report

When you create a report, you can use either the Report Wizard to assist you or create the report manually.

To build the report in this example, you will use the Report Wizard. Using the wizard you will specify the layout, style, fields, and template details for the report. You will also provide the SQL query that contains the condition with a runtime user parameter. This parameter allows users to specify the language in which they want the report output printed.

To create a simple report:

Launch Reports Builder (or, if already open, choose File > New > Report).
In the Welcome or New Report dialog box, select Use the Report Wizard, then click OK.
If the Welcome page displays, click Next.
On the next page, make sure that Create both Web and Paper Layout is selected, then click Next.
On the Style page:
- Type a Title for your report, such as Product List.
- Make sure that Tabular is selected.
- Click Next.
On the Data Source page, make sure that SQL Query is selected, then click Next.
On the Data page, click Query Builder.
In the Select Data Tables dialog box, click PRODUCT_DESCRIPTIONS, then click Include.
Click Close.
The table is displayed in the Query Builder. Click to the left of the following column names to select them:
- PRODUCT_ID
- LANGUAGE ID
- TRANSLATED_NAME
- TRANSLATED_DESCRIPTION
Click OK.

In the Data Source definition field, your query should look something like this:

SELECT ALL PRODUCT_DESCRIPTIONS.PRODUCT_ID, 
PRODUCT_DESCRIPTIONS.LANGUAGE_ID, 
PRODUCT_DESCRIPTIONS.TRANSLATED_NAME, 
PRODUCT_DESCRIPTIONS.TRANSLATED_DESCRIPTION
FROM PRODUCT_DESCRIPTIONS

Note:

You can enter this query in any of the following ways:

Copy and paste the code from the provided text file called utf8_code.txt into the Data Source definition field.
Click Query Builder to build the query without entering any code manually, as described in the steps above.
Type the code in the Data Source definition field.

In the Data Source definition field, type where language_id = :p_lang_id, after the FROM clause in the query. This adds the where clause to the query definition The where clause restricts data based on the language selected by the user at runtime.

Your query should now look like this:

SELECT ALL PRODUCT_DESCRIPTIONS.PRODUCT_ID, 
PRODUCT_DESCRIPTIONS.LANGUAGE_ID, 
PRODUCT_DESCRIPTIONS.TRANSLATED_NAME, 
PRODUCT_DESCRIPTIONS.TRANSLATED_DESCRIPTION
FROM PRODUCT_DESCRIPTIONS
where language_id = :p_lang_id

Note:

The expression, :p_lang_id, when prefixed with a colon is treated as a parameter. If the parameter does not exist, Reports Builder creates the parameter. From here on, you can access this parameter in the User Parameters section under the Data Model node in the Object Navigator.

Click Next.

Reports Builder displays the following message to indicate that an additional parameter is created:
```
Note: The query 'Q_1' has created the bind parameter(s) 'P_LANG_ID'.
```
Click OK.
On the Fields page:
- Click PRODUCT_ID in the Available Fields list, and click the right arrow (>) to move the field to the Displayed Fields list.
- Click TRANSLATED_NAME and click the right arrow (>) to move the field to the Displayed Fields list.
- Click TRANSLATED_DESCRIPTION and then click the right arrow (>) to move the field to the Displayed Fields list.
Click Next.
On the Totals page, click Next.
Click Next on the Labels page.
On the Templates page, make sure that Beige is selected and click Finish.

Reports Builder displays the Runtime Parameter Form because you referenced a user parameter.
Type JA, and click the Run Report button to execute the report.

The report output is displayed in Paper Design view. It should look something like this:

Figure 38-4 Paper design view of the report without Japanese characters in default setting

Description of "Figure 38-4 Paper design view of the report without Japanese characters in default setting"

Tip:
If you do not see any results, make sure that the value JA is typed in capital letters so that data is retrieved from the database for the specified condition.

You will not see any Japanese characters yet since a UTF8 TrueType font has not been selected.

Save the report as multibyteutf8_your_initials.rdf.

Note:

When designing a report, it is good practice to save it frequently under a different file name as a precautionary measure. Then, if you need to revisit some of the changes or if you generate an error, you can go back to the previously saved file and make revisions from that point.

38.3 Display multibyte characters in the report

You have successfully created and executed the report. Next, you have to change the font to a UTF8 multicharacter set TrueType font to see the characters of the language chosen in the report output.

To change the font to a multicharacter TrueType font:

In the Paper Design view, Shift-click the values below the Translated Name and Translated Description labels to select all the values in these two columns. You can now change their properties simultaneously.
From the font box in the toolbar, choose Arial Unicode MS.

The report is executed and the Paper Design view of the report output is displayed in Japanese characters. It should look something like this:

Figure 38-5 Paper design view of the report with Japanese characters

Description of "Figure 38-5 Paper design view of the report with Japanese characters"

To run the same report in another language:

To run the same report again with a different runtime parameter and see the output in another language, perform the following steps:

Click the Run Paper Layout button in the toolbar, or choose Program > Run Paper Layout.
In the Runtime Parameter Form, type the value PL, and click the Run Report button to run the report.

The Paper Design view of the report output is displayed with Polish characters. It should look something like this:

Figure 38-6 Paper design view of the report with Polish characters

Description of "Figure 38-6 Paper design view of the report with Polish characters"

38.4 Create a PDF document of your report

Reports Builder supports multibyte characters in the PDF format. By generating the PDF file of your report, you have the advantages of being able to:

create the report output in a portable format.

use PDF font subsetting and PDF font embedding feature.

Tip:

Make sure you perform the following steps before you generate the file:

Change the registry entry for NLS_LANG to AMERICAN_AMERICA.UTF8.
Edit the uifont.ali file.
Edit the REPORTS_PATH registry entry.

See Section 38.1, "Prerequisites for this example" for more details.

To generate the PDF file:

In Reports Builder, choose File > Generate to File > PDF.
Save the report as multibyteutf8_your_initials.pdf.
In the Runtime Parameter Form that displays, type the value PL (exactly as shown), and click the Run Report button to execute the report.

The Report Progress dialog box is displayed and provides the print status of the PDF output. When the PDF is created, this dialog box disappears.
Locate the PDF file (multibyteutf8_your_initials.pdf) and double-click to open the file.

It should look something like this:

Figure 38-7 PDF file of the report with Polish characters

Description of "Figure 38-7 PDF file of the report with Polish characters"

Note:

You can open the PDF file on any computer and it will look exactly the same, without installing any Unicode font. This is because the PDF file includes the font used in the report.

Notice the default rough visual appearance of the characters in the PDF output. You can smooth the characters by using "smoothe lineart" setting in Acrobat Reader.

38.5 Summary

Congratulations! You have successfully created a report to support any character set in your enterprise. You have used Reports Builder to generate a portable PDF file using font subsetting.

You now know how to:

create the query and paper layout for the multibyte report using the Report Wizard.
display multibyte characters using the UTF8 TrueType font.
create a portable PDF file of your report.

For more information on any of the wizards, views, or properties used in this example, refer to the Oracle Reports online Help, which is available in Reports Builder or hosted on the Oracle Technology Network (OTN), as described in Section 3.1.1, "Using the Oracle Reports online Help".