Skip Headers

Oracle® Application Server Reports Services Publishing Reports to the Web 10g (9.0.4) Part Number B13673-01 |
| Home | Contents | Index

# 5 Printing on UNIX with Oracle Reports

Oracle Reports provides a rich set of features out of the box for printing on various platforms. Printing on UNIX requires some setup and configuration to create the proper printing environment. This chapter provides information about printing on UNIX with Oracle Reports. In particular, it covers:

- UNIX Printing Overview

- Setting Up a Printer on UNIX

- Configuring the Printing Environment

- Printer-Related Files

- NLS Support

- Debugging Options

- Frequently Asked Questions

## 5.1 UNIX Printing Overview

This section explains how to print from Oracle Reports on UNIX and highlights the key differences between the UNIX and Windows platforms. It also explains the operating system requirements for any application to print successfully.

- General Printing Mechanism

- Oracle Reports Printing Mechanism on UNIX and Windows

- Printing Support

### 5.1.1 General Printing Mechanism

In trying to understand how printing works for Oracle Reports on UNIX, it is useful to have the Microsoft Windows printing mechanism as a reference point. Microsoft Windows provides an application level API that supports different types of printers based on the installed printer drivers. Applications can interact with various printer drivers through these standard APIs. For example, to change the paper margin, an application needs to call the appropriate Microsoft Windows API method, which conveys the desired changes to the printer driver. On Microsoft Windows, printer drivers are printer specific, i.e., you need to install a specific printer driver for a printer. These printer drivers know how to communicate to the printer and provide services to applications that need to send output to the printer. Applications can access the printer properties, change their properties, and perform printing through these standard APIs.

Motif and character-based UNIX operating systems do not have their own standard interface to printers as does Microsoft Windows. Individual applications are responsible for sending their output in a streamed file to the printer and adhering to the specifications of the printer. On UNIX platforms, Oracle Reports output must be formatted properly (e.g., PostScript or PCL) before sending it as a stream to the printers. To print on UNIX, Oracle Reports mimics the behavior of the Microsoft Windows printer drivers internally. The next section describes more precisely how this mechanism works on UNIX.

### 5.1.2 Oracle Reports Printing Mechanism on UNIX and Windows

The diagrams below depicts the differences between Oracle Reports printing on UNIX and on Microsoft Windows.

Figure 5-1 Oracle Reports printing on UNIX

Description of the illustration uxprt_unixprinting.gif

Figure 5-2 Oracle Reports printing on Microsoft Windows

Description of the illustration uxprt_windowsprinting.gif

To support printing on UNIX, Oracle Reports internally creates logical printer drivers. A logical printer driver simulates the behavior of Microsoft Windows printer drivers and provides a printing service interface for Oracle Reports on UNIX. Through the logical printer driver, Oracle Reports can access the printer properties and perform printer-related operations. These logical drivers:

- Support PostScript and PCL printing specifications, which are the most popular printing standards.

- Read the printer description files (e.g., PPD or HPD) to get the printer descriptions.

- Embed the various printer commands in the generated PostScript or PCL output. For example, to change paper margin, the logical printer driver needs to write the corresponding printer commands in the generated output. These commands differ depending on whether you use a PostScript or a PCL printer. When the generated PostScript or PCL file is sent to the printer via the printing executable (e.g., `lpr`), the printer interprets the commands in the file and processes them accordingly.

To function correctly, the logical printer drivers require the following input:

- The printer queue name that is used to spool the print request.

- The printer description file that contains the printer properties.

- The driver type required by the specified printer queue, PostScript or PCL.

You provide this information in a file called `uiprint.txt`. Oracle Reports uses this file to get a list of the printer queue names available for printing. In `uiprint.txt`, you need to specify the printer queue name, the type of driver needed for the queue, the version of the driver, and any special printer description file that the print driver needs for that specific printer (e.g., a PPD file for the PostScript driver). Once this information is available, the internal logical printer drivers are constructed and they use the definition files provided to access the printer properties.

### 5.1.3 Printing Support

Oracle Reports supports the following printing standards on UNIX:

- PostScript Level 1 and 2

- PCL Level 3

- ASCII (for character mode printing)

The printers you use with Oracle Reports should be compatible with the above versions.

## 5.2 Setting Up a Printer on UNIX

This section describes:

- Installing a Printer on UNIX

- Verifying the Printer Setup for Oracle Reports

### 5.2.1 Installing a Printer on UNIX

The installation of a printer queue is slightly different depending upon your flavor of UNIX. Some platforms may have user interface tools to help in the installation. Please refer to your UNIX platform documentation for the steps on adding a printer queue.

The following sample script adds a printer queue on the Solaris 2.6 platform. The domain information `expldomain` and printer names `printer1` and `printer2` are hard coded in this example. The printer is a Xerox DCS model.

    #!/bin/sh
    echo "Please enter the Printer Name Either printer1 or printer2\n"
    read PRINTER
    LOGFILE=/var/adm/config.log
    PATH=/usr/bin:/usr/sbin:$PATH
    export PRINTER LOGFILE PATH
    lpsystem -t bsd expldomain >$LOGFILE 2>&1
    lpadmin -p "$PRINTER" -s expldomain!"$PRINTER"  -I any >$LOGFILE 2>&1
    mkdir -p /usr/Xerox_DCS /usr/Xerox_DCS/original
    chown -R 755 /usr/Xerox_DCS /usr/Xerox_DCS/original
    cp /usr/bin/lp /usr/Xerox_DCS/original
    mv /usr/bin/lp /usr/bin/lp.Xerox
    ln -s /tmp /usr/Xerox_DCS/tmp
    echo "$PRINTER" > /usr/Xerox_DCS/printer.db
    cp  /usr/local/packages/dc99cc23.txt  /usr/Xerox_DCS
    ln -s /usr/Xerox_DCS/dc99cc23.txt /usr/bin/lp
    lpadmin -d "$PRINTER"

### 5.2.2 Verifying the Printer Setup for Oracle Reports

To verify that your printer queue installed correctly:

1. Make sure that the PPD or HPD file used with the installed printer queue is available in the following location:

       ORACLE_HOME/guicommon9/tk90/admin/PPD
       ORACLE_HOME/guicommon9/tk90/admin/HPD

2. Make sure that the font metrics, AFM or TFM files, installed on the printer are available in the following location:

       ORACLE_HOME/guicommon9/tk90/admin/AFM
       ORACLE_HOME/guicommon9/tk90/admin/TFM

## 5.3 Configuring the Printing Environment

This section explains the various configuration steps to be performed on UNIX after printer installation.

- Editing uiprint.txt File

- Environment Variables

- Print Property Dialog Boxes

### 5.3.1 Editing uiprint.txt File

As discussed in UNIX Printing Overview , Oracle Reports creates logical printer drivers. To create these internal printer drivers, it needs information from you like the available printer queue, the type of driver to be used with the queue, the version of the driver, and the printer description file.`uiprint.txt` is the main file for providing this information. It is located in:

    ORACLE_HOME/guicommon9/tk90/admin

`uiprint.txt` is the printer configuration file and Oracle Reports reads it when it creates the internal printer drivers. You should modify this file for each instance of Oracle Reports.

The format of entries in `uiprint.txt` is:

    Printer:DriverType:DriverVersion:PrinterDescription:PrinterDescriptionFile:

This one line entry, in prescribed format, in `uiprint.txt` defines a printer to be used by Oracle Reports. Each line contains five fields separated by colons. Table 5-1 describes each element of the `uiprint.txt` entry.

Table 5-1 uiprint.txt entry elements

Element | Description
--- | ---
Printer | Specifies the name of the printer (or printer queue), as used with the `lpr` or `lp` command. To get a list of all available printers, use the following command: lpstat -a To check the status of the printer, use the `lpstat` command: Solaris lpstat -p printername Linux lpstat -p printername HP-UX lpstat -d printername HP Tru64 lpstat -p printername IBM AIX lpstat -pprintername No space is allowed after `-p` on IBM AIX.
DriverType | Specifies the type of printer driver used for the printer. The driver can be PostScript, PCL, or ASCII.
DriverVersion | Specifies the version of the driver type that should be used. This can be 1 or 2 for PostScript printers, and PCL Version 5 for PCL.
PrinterDescription | Specifies the description of the printer, for example, the speed and the location of the printer. This information is used for display in the printer-related dialog box.
- PrinterDescriptionFile | Specifies the printer description file to be used with the printer. It can be one of the following types: When using a PostScript printer, this entry contains the name of a PPD file. PPD stands for PostScript Printer Description. If Oracle Reports cannot find the specified PPD file, it uses `default.ppd`. Oracle Reports searches for PPD files in:
      ORACLE_HOME/guicommon9/tk90/admin/PPD
- When using a PCL printer, this entry contains the name of an HPD file. If Oracle Reports cannot find the specified HPD file, it uses `ui4.hpd`. Oracle Reports searches for HPD files in:
      ORACLE_HOME/guicommon9/tk90/admin/HPD
When using an ASCII printer, this entry would be set to none. This field is ignored for all ASCII printers.

Usage Note:

- All the fields in the `uiprint.txt` entry must be filled and every line must end with a colon.

- At least one entry must be defined in `uiprint.txt`. Alternatively, you can set the related printer variables (`TK_PRINTER` and `PRINTER`). Without these, Oracle Reports is unable to perform any printer-related task.

  See Also: Environment Variables For more information on printer-related environment variables.

  The internal printer drivers provide a drawing surface for Oracle Reports. In addition to using this surface for printing, Oracle Reports uses it internally whenever output is generated to a file. Hence, you need to have a valid entry in `uiprint.txt` or to set one of the printer-related environment variables. To simplify the selection of printers for your users, we recommended that you list all printers accessible to users in `uiprint.txt`.

Example:

Following are two example entries for `uiprint.txt`:

    colprt14:PostScript:2:RMSC Atrium HPLaserJet5:default.ppd:
    colprt15PCL:5:RMSC 1st Floor HPLaser4:ui4.hpd:

### 5.3.2 Environment Variables

This section lists the environment variables related to printing:

See Also: Appendix B, " Reports-Related Environment Variables " For more information on the various environment variables that can be set in Oracle Reports.

- TK_PRINTER / PRINTER

- TK_PRINTER

- TK_PRINT_STATUS

- REPORTS_NO_DUMMY_PRINTER

- TK90_HPD and ORACLE_HPD

- TK90_PPD and ORACLE_PPD

- TK90_TFM and ORACLE_TFM

- TK90_AFM and ORACLE_AFM

### 5.3.3 Print Property Dialog Boxes

On UNIX, Reports Builder provides several dialog boxes for printer-related operations.

#### 5.3.3.1 Page Setup dialog box

The Page Setup dialog box enables you to specify how the printed page appears. The available options depend on the type of printer driver being used. The internal printer drivers use this dialog box to get all the information necessary, (e.g., scale, rotation, width, and height) for formatting a page on a printer.

#### 5.3.3.2 Print Job dialog box

Each print job has unique characteristics depending on the printer driver being used. The Print Job dialog box displays just prior to print job execution and prompts you for the print job information required to send the job to the printer.

## 5.4 Printer-Related Files

This section explains the different printing related files. It gives an overview of these files and also provides information for editing these files for common printing needs.

- Overview of Files

- PPD Files

- HPD Files

- Font Metrics Files

- uifont.ali

- uiprint.txt

- Editing the Printer-Related Files

### 5.4.1 Overview of Files

Table 5-2 lists files used by Oracle Reports for printing on UNIX.

Table 5-2 Printer-related files overview

File name/extension | Description
--- | ---
`.ppd` | PostScript Printer Definition file
`.hpd` | HP glue file
`.afm` | Adobe font metrics file
`.tfm` | PCL font metrics file
`uifont.ali` | font aliasing file
`uiprint.txt` | printer configuration file

### 5.4.2 PPD Files

PostScript is Adobe’s page description programming language. PPD files define what capabilities a printer has for applications like Oracle Reports. For example, a PPD file might define which paper tray to use, what paper sizes are available, what is the physical dimension of the paper, and what font is available. Currently, Oracle Reports reads the paper sizes and fonts available on the printer as well as its default resolution from this file. In the future, more information may be used, such as memory for proper image partitioning.

The only reason to modify the PPD file is to allow Oracle Reports to recognize newly added fonts or memory. You can also change the `DefaultPageSize` to your preferred page size.

Note: Page sizes, like all PPD entries, are case sensitive. Other entries in the PPD file should generally be left undisturbed.

When you select a printer that is not listed in `uiprint.txt` or change the type of printer to a PostScript type in the Choose Printer dialog box, you are prompted for the PPD file for the printer. You must choose the PPD file for a printer that most closely resembles the printer being used. PPD file names typically bear some resemblance to the printer model name.

In `uiprint.txt`, a PPD file must be specified for each printer. If an invalid PPD file is specified for the current printer (e.g., no PPD file is found or the PPD file format is wrong), Oracle Reports will use `default.ppd` for that printer. You should make `default.ppd` a copy of another PPD file that better reflects the most likely default, local printer.

Oracle Reports includes a common set of PPD files, but sometimes you may need to get specific PPD files for your printers from the vendor. Table 5-3 shows some examples of PPD files that are shipped with Oracle Reports:

Table 5-3 Common PPD files shipped with Oracle Reports

PPD file name | Corresponding Printer
--- | ---
`appl230.ppd` | Apple LaserWriter v23.0
`datap462.ppd` | Dataproducts LZR-2665
`declps32.ppd` | Digital PrintServer 40
`default.ppd` | Default Level 1 PostScript Printer
`hpljet41.ppd` | HP LaserJet 4/4M PostScript 600DPI
`lwntx470.ppd` | Apple LaserWriter II NTX
`nccps801.ppd` | NEC Colormate PS/80
`tkphzr33.ppd` | Tektronix Phaser III PXi v2011.108
`l530_523.ppd` | Linotronic 530
`screenprinter.ppd` | Default PPD file to be used when a printer is not available on UNIX.

If you need a PPD file that is not among those shipped with Oracle Reports, you must do one of the following (in order of preference):

- Ask the printer vendor for the PPD file.

- Download the PPD file from Adobe's Web site

- Copy an existing PPD file and edit it

- Ask Adobe for the PPD specs and write the PPD file.

The PostScript file only has the font information not the font metrics. Oracle Reports refers to the AFM file installed for the font metrics information. The font vendors provide these AFM files. Oracle Reports ships AFM files for some of the most commonly used fonts. The printer must have the required font installed in order to correctly print the PostScript file generated by Oracle Reports.

#### 5.4.2.1 Local customization of PPD files

A PPD file is a static representation of the features of a printer. It contains default factory settings. Once a printer is installed, features such as additional memory, paper trays, and fonts may be added to the device. The task of managing a device is a dynamic issue that requires keeping track of fonts downloaded to disk, error handlers, RAM-based fonts and procedure sets, default device setup, and so forth. This kind of device management is beyond the scope of PPD files. However, there are some provisions for customizing the information contained in PPD files to adapt them to local instances of printers or to specific applications when necessary.

Instead of modifying the original PPD file, another approach would be having a new file having the local customization of certain parameters and refer to the primary file for the remaining information. The local customization file must contain a reference to the primary PPD file in this format:

    *Include: "filename"

where `filename` is the name of the primary PPD file. This referencing allows a system administrator to later replace the primary PPD file without forcing users to edit their local customization files. A file referenced by the `*Include` keyword is treated as though it were in the including (local customization) file.

For example, suppose that the `default.ppd` file is defined as:

    *PPD-Adobe: "4.0"
    *Include: "datap462.ppd"

    *% Page definitions
    *DefaultPageSize: Letter
    …………………………
    *DefaultPageRegion: Letter

The primary PPD file is `datap462.ppd`.

Administrators should change the name of the included file to conform to their site's default printer type.

When a local customization file includes a primary PPD file, there might be several instances of the same keyword in the composite file. Hence, the location of the primary file in the customization file (beginning or end) is important and effects the changes made by the customization file.

### 5.4.3 HPD Files

HPD files provide functionality for PCL printers that is similar to what PPD files provide for PostScript printers. HPD or HP glue files provide information on what fonts are available for a PCL printer. The HPD file format can be found in the HP PCL5 Developer's Guide.

Just as PostScript has AFM files, every HP font must have an associated TFM file. The font vendor should provide TFM files and new fonts should be added to the HPD file for your printer when installed. For a new font, you should specify the following fields in the HPD file:

    FONT={fontname}
    /tfm={tfm-filename}

where

`fontname` is a descriptive name for the font.

`tfm-filename` is the base file name for the TFM file.

If the TFM file isn't specific enough, you can also specify the following after the FONT field:

    /ptsize={size {size ...}}

If the specified font is a bit mapped font but is listed in the TFM file as a scalable font, you can limit the point sizes used by listing the acceptable sizes as follows:

    /symset={symset {symset ...}}

This field limits the supported symbol sets to those listed. See the HP PCL documentation for a list of recognized symbol sets.

Oracle Reports also supports the `defaultpaper` field for printing to PCL format. This field can be used to set the `defaultpaper` to be used by the Toolkit. The format of this field is:

    <defaultpaper={papername}>

For example, the following sets the paper name to A4:

    <defaultpaper=A4>

The paper name is case insensitive. If you specify `defaultpaper` in more than one place, then the last instance of `defaultpaper` is used. If you specify a paper name that is not supported by the printer, `defaultpaper` is ignored and LETTER is used as the paper name instead. Similarly, if the paper name is incorrect, then LETTER is used.

### 5.4.4 Font Metrics Files

Oracle Reports supports two kinds of font metrics files:

- AFM files

- TFM files

#### 5.4.4.1 AFM files

Each AFM files contains the font-related metrics for a single font. The metrics include various font attributes such as style, weight, width, and character set. AFM files and a description of the AFM file format are typically available from the font or printer vendors.

To install the AFM file, just copy it to the AFM file location, which is listed in Verifying the Printer Setup for Oracle Reports. The name of the file must match name of the font without the `.afm` extension. For example, if the font name is `CodedreineunBold`, the file name must be `CodedreineunBold`.

To verify the font name, you can look for the fontname string in the AFM file. Please note that the AFM files are not font files, they are metrics files, which give information on how to properly format the characters for the printer. If you have an AFM file for a font, but the font is not present on the printer, Oracle Reports cannot generate the correct output on the printer because of the font metrics mismatch. You must ensure that the font used to design the report is also available on the printer.

#### 5.4.4.2 TFM files

PCL5 uses HPD and TFM files. The HPD file contains the list of available fonts for the printer and each font refers to a TFM file. TFM files serve the same purpose as Adobe's AFM files, with each file listing information about a single font. The HPD file is an ASCII file, which can be edited, but the TFM file is a binary file, which cannot be edited.

To use a new font in Oracle Reports and have it appear correctly in PCL output, you need the HPD and TFM files for the printer. You can copy an HPD file from an existing one, provided that you ensure it is suitable for your printer. The fonts specified in the HPD file must be available on the printer.

Oracle Reports includes a common set of TFM files. If you need other font metrics files for your printer, you should obtain them from your font or printer vendor. To install the TFM file, just copy it to the TFM file location, which is listed in Verifying the Printer Setup for Oracle Reports.

### 5.4.5 uifont.ali

The `uifont.ali` file defines the font aliases used by Oracle Reports. It is an extremely useful tool for cross-platform development because it enables you to define which fonts to substitute when a particular font is unavailable. `uifont.ali` is located in:

    ORACLE_HOME/guicommon9/tk90/admin

To alias a font, use the following syntax:

    source_font = destination_font

For each font, you may also specify the following attributes:

    face.size.style.weight.width.character_set

Styles may also be combined using a plus sign + to delimit the styles. For example:

    Arial.Italic+Overstrike = Helvetica.12.Italic.Bold

This entry maps any Arial font that has both Italic and Overstrike styles to a 12-point, bold, and italic Helvetica font. Font faces can be case sensitive depending on the platform and the surface, i.e., printer or system.

See Also: Chapter 4, " Managing Fonts in Oracle Reports" For more font-related information.

### 5.4.6 uiprint.txt

`uiprint.txt` provides a convenient way for you to provide details about the printer queue, such as the type of printer driver and the printer description. You should edit `uiprint.txt` for each instance of Oracle Reports.

See Also: Editing uiprint.txt File For more information about `uiprint.txt`

### 5.4.7 Editing the Printer-Related Files

The sections that follow describe how to edit the various print-related files.

#### 5.4.7.1 Editing PPD files

In some cases, you may need to change certain attributes in your PPD file. The sections that follow describe some of the attributes that you would commonly need to change.

##### 5.4.7.1.1 Changing the default paper size

Suppose that you need the page size to be A4 for some of your reports. On Motif platforms, the printer driver is specified in `uiprint.txt` and the default page size is not necessarily set to A4. For example, `hpljet41.ppd` has LETTER as the default page size. Note that the default page size setting for each printer queue is taken from the corresponding PPD file.

To set A4 as the default page size, you would do the following:

1. Edit `uiprint.txt` to include a PostScript Printer Description file (extension is .ppd) that supports the A4 page size. For example, you might include `hpljet41.ppd`.

2. As a backup, make a copy of `hpljet41.ppd`.

3. Add an entry to `uiprint.txt`:

       Printer_name: PostScript:1: the printer on floor1:hpljet41.ppd

4. Edit `hpljet41.ppd` and change these settings as follows:

       DefaultPageSize: A4
       DefaultPageRegion: A4
       DefaultImageableArea: A4
       DefaultPaperDimension: A4

##### 5.4.7.1.2 Changing the printer margin settings

To change the margins, you need to modify the ImageableArea section in the PPD file. ImageableArea provides the bounding box of the area in which the printer may print for the page size named mediaOption. There will be one statement for each named page size supported by the device. *DefaultImageableArea provides the mediaOption name of the default imageable area. Since there can be only one default page size, this value should be the same as the value of *DefaultPageSize, *DefaultPageRegion, and *DefaultPaperDimension.

The syntax for defining imageable area is as follows:

    *ImageableArea mediaOption: "llx lly urx ury "
    *DefaultImageableArea: mediaOption | Unknown

`ll` stands for lower left corner and `ur` for upper right corner. The bounding box value of *ImageableArea is given as four real numbers, representing the x and y coordinates of the lower left and upper right corners of the region, respectively, in the PostScript language default user space coordinate system. The x and y axes of a given page size correspond to the x and y axes of that page size in the *PaperDimension entry.

The imageable area is defined as the part of the page where the printer may actually make marks. On some printers, the imageable area of a given page size varies as a result of the current resolution, amount of memory, the direction of paper feed, and other factors. In PPD files where the imageable area of a given page size can vary, the imageable area recorded for that page size will be the intersection of all possible imageable areas for that page size. This formula ensures that the available imageable area is never smaller than that shown in the PPD file and all marks made within the imageable area will be visible. It does, however, also mean that the imageable area in the current configuration might actually be larger than the imageable area shown in the PPD file.

The following table contains the option keywords currently registered for `mediaOption`, which designates a given page size on a device:

Table 5-4 mediaOption keywords

mediaOption (paper size) | size (pts) | size (mm) | size (inches)
--- | --- | --- | ---
Letter | 612 * 792 | 215.9 * 279.4 | 8.5 * 11
Legal | 612 * 1008 | 215.9 * 355.6 | 8.5 * 14
Ledger | 1224 * 792 | 431.8 * 279.4 | 17 * 11
Tabloid | 792 * 1224 | 279.4 * 431.8 | 11 * 17
A3 | 842 * 1191 | 297 * 420 | 11.69 * 16.54
A4 | 595 * 842 | 210 * 297 | 8.27 * 11.69
A5 | 420 * 595 | 148 * 210 | 5.83 * 8.27
B4 | 729 * 1032 | 257 * 364 | 10.12 * 14.33
B5 | 516 * 729 | 182 * 257 | 7.17 * 10.12

Example

To change the margins of an A4 page in the `default.ppd`, you would perform the following steps:

1. Modify the default page from `Letter` to `A4` in the following sections:

       *% Page definitions
       *DefaultPageSize: A4
       *PageSize A4: " "

       *% These entries set up the frame buffer. Usually used with manual feed.
       *DefaultPageRegion: A4
       *PageRegion A4: "A4"

       *% These provide the physical dimensions of the paper (by keyword)
       *DefaultPaperDimension: A4
       *PaperDimension A4: "595 842"

2. Add the margin definition in the following sections:

       *% Imageable (writable) areas for each page size, in pixels
       *DefaultImageableArea: A4
       *ImageableArea A4: "2 2 593 840 "

   Note: All PPD entries are case sensitive.

##### 5.4.7.1.3 Adding a new font entry to PPD files

On PostScript printers, Oracle Reports only allows you to use fonts known to be available on the printer. Since printers are rarely available for personal requests on multi-process operating systems, Oracle Reports gets a complete list of fonts from the PPD file.

When a new font is installed on the printer, a corresponding font entry needs to be added to the printer's PPD file. The format for a font entry is:

    *Font {fontname}: {encoding} "({version})" {charset}

where

`{fontname}` is the Adobe font face name as specified in PostScript.

`{encoding}` is the PostScript encoding name.

`{version}` is the FontInfo version number.

`{charset}` is the Adobe character set.

The `encoding` value has slightly different meanings depending on the font type. If the encoding cannot be determined, the value of encoding may be set to unknown. Fonts are usually re-encoded by applications to provide other encodings; the `charset` value for each font indicates which encodings are possible for that font. For more information, please refer to the PPD specification from Adobe.

When new fonts are added to the printer, the matching AFM files must also be added to the font metrics directory. Oracle Reports requires the AFM files to get the actual font attributes and properly place text on the printed page.

Example

Suppose you add a new font, CodedreineunBold, and need to edit the PPD file to include the new font.

1. In the PPD file, search for:

       *% Font Information

2. For the new font, append the following at the end of the paragraph:

       *Font CodedreineunBold: Standard '(00.1001)" Standard ROM

##### 5.4.7.1.4 Overriding the printer tray setting

The PostScript output generated by Oracle Reports has the tray information embedded into it. The PPD file defines the default tray to be used and is followed by the definitions of valid trays for the printer. To print to a different tray, the `DefaultInputSlot` entry in the PPD file must be updated.

In the PPD file, you should find a section that lists the default tray and the valid input slots. The section typically starts with a line like this one:

    *OpenUI *InputSlot:   <PickOne>

The default tray entry looks like the following:

    *DefaultInputSlot: Lower

The defined slots typically follow the default entry and look like the following:

    *InputSlot Upper/Multipurpose Tray: "
    ...
    *InputSlot Lower/Paper Cassette: "

The section ends with a line like the following:

    *CloseUI: *InputSlot

You can set `DefaultInputSlot` to be any of the values in the list of defined slots.

#### 5.4.7.2 Editing HPD files for PCL printing

In some cases, you may need to change certain attributes in you HPD file. The sections that follow describe some of the attributes that you would commonly need to change.

##### 5.4.7.2.1 Changing the paper size

For example, to change the papersize to A4, add the following to the HPD file used:

     <defaultpaper=A4>

##### 5.4.7.2.2 Adding a new font entry

As with PostScript's AFM files, every HP font must have a TFM file in order for Oracle Reports to use it. The font vendor should provide TFM files. You should add new fonts to the HPD file when you install them.

You must specify the following settings in the HPD file for any new font:

    FONT={fontname}        # {fontname} is a descriptive name for the font
    /tfm={tfm-filename}    # {tfm-filename} is the base filename for TFM file

Note: The font name entries in HPD files must be unique.

## 5.5 NLS Support

This section explains multibyte character set printing support from Oracle Reports. It also explains the new PASTA component, which is supported only for Oracle Reports when installed and used in conjunction with Oracle Applications.

- Multibyte Character Set Printing

- Overview of IX and PASTA

### 5.5.1 Multibyte Character Set Printing

Oracle Reports does not currently support Unicode character sets in PostScript output. As an alternative, you can use Oracle Reports PDF output, which supports multibyte character sets, and print it.

Oracle Reports supports a set of encoding schemes for the AFM files for the multibyte character sets.

See Also: Chapter 4, " Managing Fonts in Oracle Reports" For more font-related information.

The fonts must be installed on the printer that prints the PostScript report output.

Example

Suppose you build a report and its generated PostScript output contains a Chinese character set. First, you need AFM and PPD files that adhere to the encoding scheme for multibyte character sets. The destination printer must also have the required Chinese fonts installed because the PostScript file generated by Oracle Reports on UNIX does not have fonts embedded in it. The PostScript file contains only the font name and the font metrics taken from the AFM files. If you try to send the report to a printer that does not have the Chinese fonts installed, it will not print the Chinese characters properly.

### 5.5.2 Overview of IX and PASTA

When installed and used with Oracle Applications, Oracle Reports has an additional utility for font embedding in PostScript output.

For character mode reports, the utility is called PASTA. For bit-mapped reports, a new component called IX is shipped with Oracle Reports. IX allows you to embed the fonts in the PostScript output thereby allowing you to print even if the font is not installed on the printer. Both PASTA and IX are supported only for Oracle Reports used with Oracle Applications.

When used for character mode reports, PASTA takes tagged character mode output (generated via an appropriate `prt` file) and generates a PostScript rendition of it. IX enables Oracle Reports to print PostScript bit-mapped reports for all character sets, including UTF8, on a PostScript printer. With this functionality, PostScript printing in Unicode as well as all native languages on Solaris is supported. The IX library is turned off by default with the Oracle Reports patch.

Please refer to your Oracle Applications System Administrator’s Guide for the setup and usage information for IX and PASTA with Oracle Reports. If you are a member of MetaLink (`http://metalink.oracle.com`), you can also get this information from MetaLink notes 189708.1 and 159225.

If you have problems with PASTA, you can use the following technique to isolate the problem:

1. Unset the PASTA environment variable.

2. Try to perform the steps that caused the problem again.

3. If the problem reproduces without the environment variable set, then it should be treated as a normal Oracle Reports printing problem and the diagnostic steps provided in this document should be applied.

   If the problem reproduces only with the PASTA environment variable set, then follow the diagnostic process given in the Oracle Applications documentation.

## 5.6 Debugging Options

This section explains the different environment variables and techniques available in Oracle Reports for the debugging of UNIX printing problems.

- DEBUG_SLFIND

- TK_DEBUG_POSTSCRIPT

### 5.6.1 DEBUG_SLFIND

If this environment variable is set, the file-finding routine lists what was searched for and where Oracle Reports searched for it. This information is a tremendous help if your current configuration does not work. You can send the output to a file, `stdout` (for standard output), or to `stderr` (for output to standard error). If you try to send the output to a file and it cannot be written to, Oracle Reports uses `stderr` instead.

We recommend sending the output to a file because it is faster and the output can be quite large. Sample output from `DEBUG_SLFIND` is shown below. Notice how the debug information generated helps you identify the various setup issues, such as which PPD and AFM files are being referred to and their location.

You can see all of the following in this output:

- The various environment variables, such as `TK90_PPD` and `TK90_AFM`, and their values.

- The resource files, such as the PPD and AFM, and their locations, which helps you to determine if any are the missing.

- The default location of various resource files under `ORACLE_HOME`.

    slsfindfile(): checking environment variable TK90_PPD(8).
    slsfindfile(): environment variable not set
    slsfindfile(): checking environment variable ORACLE_PPD(10).
    slsfindfile(): environment variable not set
    slfpath():     looking up path
                   /s/rw/994/solohome/guicommon9/tk90/admin/PPD/
    slfexist():    testing /s/rw/994/solohome/guicommon9/tk90/admin/PPD
    slfexist():    testing /s/rw/994/solohome/guicommon9/tk90/admin/PPD/default.ppd
    slsfindfile():returned
    /s/rw/994/solohome/guicommon9/tk90/admin/PPD/default.ppd
    slfindfile():  type = 39 (AFM)slfindfile():  name = Courier-Bold
    slsfindfile(): checking environment variable TK90_AFM(8).
    slsfindfile(): environment variable not set
    slsfindfile(): checking environment variable ORACLE_AFM(10).
    slsfindfile(): checking ORACLE_HOME environment variable.
    slsfindfile(): environment variable set to /s/rw/994/solohome (len=18)
    slfpath():     looking up path	/s/rw/994/solohome/guicommon9/tk90/admin/AFM/
    slfexist():    testing /s/rw/994/solohome/guicommon9/tk90/admin/AFM
    slfexist(): testing /s/rw/994/solohome/guicommon9/tk90/admin/AFM/Courier-Bold
    slsfindfile():returned /s/rw/994/solohome/guicommon9/tk90/admin/AFM/Courier-Bold
    slfindfile():  name = uiprint.txt
    slsfindfile(): checking ORACLE_HOME environment variable.
    slfpath():     looking up path	/s/rw/994/solohome/guicommon9/tk90/admin/
    slfexist():    testing /s/rw/994/solohome/guicommon9/tk90/admin
    slfexist():    testing /s/rw/994/solohome/guicommon9/tk90/admin/uiprint.txt
    slsfindfile(): returned /s/rw/994/solohome/guicommon9/tk90/admin/uiprint.txt

### 5.6.2 TK_DEBUG_POSTSCRIPT

This variable effects the PostScript output generated by Oracle Reports. Table 5-5 shows the settings for this variable.

Table 5-5 Settings for TK_DEBUG_POSTSCRIPT

Setting | Description
--- | ---
Functions (Func) | Function lists each toolkit function called in comments in the PostScript output.
Long (L) | Long produces more intelligible PostScript output but runs much more slowly than normal PostScript generation.
Memory (Mem) | Memory displays memory usage at the bottom of each page.

Any of the options can appear in the environment variable, abbreviated down to one letter. You can set it to any combination of these, separated by "/". This variable is case insensitive. For example, `Func/L/Mem` would give you all three options.

Note: The PostScript output from this variable is for your own debugging purposes. You do not need to provide this output to Oracle Support for investigation.

## 5.7 Frequently Asked Questions

This section addresses some commonly encountered problems with UNIX printing.

- Common Printing Error Messages

- PCL Printing Issues

- PostScript Printing Issues

- Font-Related Printing Issues

- Printed Output Issues

### 5.7.1 Common Printing Error Messages

REP-00177 - Error while running in remote server
REP-1800 - Formatter error
REP-3300 - Fatal error in 'component name
UI-9 - This function call is out of context.
REP-3002: Internal error initializing printer information
Cause:

These errors generally indicate a printer configuration issue.

Action:

Check the printer queues that have been defined at the operating system level in your setup. You can use:

- `lpc status`

- `lpstat -a`

If a valid printer queue is installed, check for the following:

- `uiprint.txt` must have a valid entry for the printer.

- Oracle Reports must be able to open and read the `uiprint.txt` file:

  The person running the report must have operating system level read permissions on `uiprint.txt`. Oracle Reports must be able to open the `uiprint.txt`. UNIX operating systems do have an open file limit. If you are over that limit, Oracle Reports might not be able to open `uiprint.txt`.

- The printer description files specified in `uiprint.txt` must exist in your installation in:

      ORACLE_HOME/guicommon9/tk90/admin

- The printer specified in `uiprint.txt` must be enabled at the operating system level. A quick test is to try printing any file from the command line using `lp` or `lpr`. If you can print using one of these commands and get the output on the printer, then the printer is enabled.

- The printer queue and `uiprint.txt` entry syntax must be valid.

  If the printer validation fails, refer to the environment variables `TK_PRINT_STATUS` and `REPORTS_NO_DUMMY_PRINTER` in Environment Variables.

REP-00826 - Invalid printer driver xxx specified by parameter desformat.
REP-00177 - Error while running in remote server (When run through CGI)
Cause:

An invalid value was specified for `DESFORMAT` for the specified report execution mode.

Solution:

The `DESFORMAT` parameter specifies which output format is needed. Valid formats are:

- For bit-mapped reports, any of the output formats supported by Oracle Reports (Postscript, PCL, PDF, HTML, XML, HTMLCSS) is valid for `DESFORMAT`. You should not give the PRT file names here. While running to a file, the `DESFORMAT` parameter needs to be set to a valid printer queue. Oracle Reports uses the printer definition file associated with the printer to format the output.

- For character mode reports, `DESFORMAT` sets up the output for ASCII printers and passes escape characters. For running character mode reports, make sure you change the `MODE` parameter to Character and use any valid .PRT file.

Table 5-6 maps the command line options (`DESTYPE`, `DESNAME`, and `DESFORMAT`) to the printer by what you are trying to achieve.

Table 5-6 DESTYPE, DESNAME, and DESFORMAT settings by case

Case | DESTYPE | DESNAME | DESFORMAT
--- | --- | --- | ---
Generating to a file | File | file_name.ps | printer name
Printing | Printer | printer name |
Distribute=Yes |  |  | printer name
Mode=Character |  |  | `file_name``.prt`

REP-01800 - Formatter error.
REP-00177 - Error while running in remote server

(When run through CGI)

Cause:

The error indicates that a printer configuration issue has occurred on a UNIX server. Even if there is not a physical printer available on the system, you have to set it up as if there was one.

Solution:

1. Verify that there is a valid entry in `uiprint.txt`.

2. If you have multiple printer queue entries in `uiprint.txt` and you need to set the default printer, verify that the environment variable is set to a printer that is listed in `uiprint.txt`. If the related environment variable is not set, then the first entry in `uiprint.txt` is used. For more information about printer related environment variables, refer to Environment Variables.

If there is no printer available for your system, refer to Configuring the Printing Environment for alternatives.

Error while printing to a printer with spaces in its name
Cause

If you are on Solaris 2.8 and have printers that have spaces in the names, you may encounter a bug that causes an error resulting from the lpr/lp command including quotes around the printer name.

Solution

To resolve this issue, you must do either one of the following:

- Remove the spaces in the printer’s name.

- Install the Solaris 2.8 patch from Sun Microsystems that fixes the lpr/lp command so that quotes can be used in printers names.

  and

- Modify the section of rwlpr.sh that provides the workaround for including quotes, in order to make accessible any printer that has a space in the name. The rwlpr.sh file is located in the ORACLE_HOME/bin directory.

  Specifically, make the following changes:

      #either LPR or LP Command was found
      if [ -x $PRNCMDPATH ]
       then
         if [ `basename $PRNCMDPATH` = "lpr" ]
         then
          #if [ `/usr/bin/uname -r` = "5.8" ]
          #then
            #$PRNCMDPATH `echo $@ | tr -d "\""`
          #else
            $PRNCMDPATH "$@"
          #fi
        else
         # parse and Fix the command Line as Required by lp
         #if [ `/usr/bin/uname -r` = "5.8" ]
         #then
           #getLpCommandLine `echo $@ | tr -d "\""`
         #else
           getLpCommandLine "$@"
         #fi
         $PRNCMDPATH
        fi
        # exit with the command's exit code , This will tell the
        # server Print module if the command completed successfully
        # or not.
        exit $?
      fi
      done

### 5.7.2 PCL Printing Issues

Why do fields that appear as gray on my PC print as white on a UNIX PCL printer?

PCL color printing is not supported. When the pattern is set to transparent, PCL printing uses the white pen (in PCL language) to draw. When the pattern is set to a solid pattern, it uses the black pen. This behavior occurs irrespective of what color is set for the foreground or background. PostScript printing logic is different. It uses the foreground color set when the pattern is solid and the background color set when the pattern is transparent.

What PCL level is supported in Oracle Reports?

The Oracle Reports PCL driver currently supports the features of PCL Level 3. It does support HPD files for later PCL versions, but it will not honor the additional features introduced since PCL Level 3.

### 5.7.3 PostScript Printing Issues

What is the work around for duplex printing on PostScript printers?

You should have a printer with a duplex option and an appropriate PPD file. The example that follows was tested with a PPD file for the Kyocera FS-9000 printer. You also need the UNIX `sed` tool named to filter the output file.

The problem with duplexing is that it is enabled at the job level, but it gets reset in the page setup because the paper size and printer tray information are generated for every page. To work around this problem, you need a script that removes the page level setup information to avoid resetting the duplex setting. A side effect of this work around is that you cannot switch the printer tray between pages.

1. Write a `sed` script with the following three lines:

       /^%%BeginPageSetup/,$ {
          /^%%BeginFeature/,/^%%EndFeature/d
       }

2. Save the script to a file named `duplexsed`.

3. Copy `duplexsed` to an appropriate directory, such as `ORACLE_HOME``/bin`.

4. Set the environment variable `TK_PRINT` as follows:

       TK_PRINT="sed -f $ORACLE_HOME/bin/duplexsed | lpr -l -s -P'%n' -#'%c'"
       export TK_PRINT

   Note: Print commands differ for various kinds of UNIX. Check your installation guide and man pages for your platform. Refer to Environment Variables for a description of `TK_PRINT`. The command stored in `TK_PRINT` is only executed if `DESTYPE=PRINTER`. If `DESTYPE=FILE`, you still get a PostScript file with page level setup information. You can run the `duplexsed` script against the PostScript file to correct it.

What Postscript level is supported in Oracle Reports?

Oracle Reports supports PostScript Level 1 and 2.

How do you dynamically change the printer tray setting in the midst of a print job?

In some cases, you may want to switch printer trays in the middle of a report. For example, you might want the first page of a report printed on letterhead stationary and subsequent pages printed on plain white paper. For character mode reports, you can achieve this result through a combination of editing the .prt file and changing the report’s properties. For bit-mapped reports, you use the `SRW.SET_PRINTER_TRAY` built-in function. On UNIX, this functionality is supported for PostScript output but not PCL output. For PCL, Oracle Reports ignores the commands for changing orientation and paper tray. Although dynamically changing the orientation and printer tray for PCL is not supported on UNIX, you can change them at runtime through the print dialog box for PCL.

By using the Before Report, Between Pages, or format triggers you can switch to different printer trays as your report formats. This allows you to easily print pages of the same report on different sheets of paper.

`SRW.SET_PRINTER_TRAY` is a built in Oracle Reports function for setting the printer tray. The Reports Builder online help system describes this function’s syntax.

Example

From the Before Report trigger, you can set the printer tray for the very first page:

    function BeforeReport return boolean is
    begin
        srw.set_printer_tray('UPPER PAPER TRAY');
        return (TRUE);
    end;

To set the printer tray dynamically for subsequent pages, add a format Trigger to an item that prints on each page of the report. The following code checks for even pages and sets the page number accordingly:

    function B_tbpFormatTrigger return boolean is
    page_num number;
    begin
       srw.get_page_num(page_num);
      begin
     if mod(page_num, 2) = 0 then
       srw.set_printer_tray('UPPER PAPER TRAY');
      else
       srw.set_printer_tray('LOWER PAPER TRAY');
     end if;
      return (true);
    end;
    end;

Why does the external print command ignore the tray select option while trying to print the PostScript output generated by Oracle Reports?

Suppose that you enter the following print command:

    - lp -dprinter -oupper $report_print_file1

In this case, the `-oupper` option in the `lp` command is ignored. The reason for this behavior is that Oracle Reports generates tray information in its PostScript output. The tray selection in the PostScript overrides the specification on the command line. If you want the tray information on the command line to be respected, you need to remove the tray information from the PostScript file. You can do this by searching for and removing the following from your PostScript file:

    %%BeginFeature: *InputSlot name of printer tray
    ....
    %%EndFeature

For more information on switching printer trays, refer to How do you dynamically change the printer tray setting in the midst of a print job?

### 5.7.4 Font-Related Printing Issues

How do you check whether a font is used in Oracle Reports printing?

PostScript files have a list of fonts, which is created after reading the PPD file. If you examine the PostScript file, you can check the fonts by looking for the following tags:

- `DocumentNeededResource` has the list of fonts referenced in the PPD file.

- `DocumentSuppliedResource` has the list of fonts for which the PostScript driver was able to find corresponding AFM files.

- `%%Page` before the field's `%IncludeResource:font` has the font name that will be used for the field.

For PCL output files, you can check whether a particular font was used. Depending on this information, the font settings in Oracle Reports or the printer can be modified.

See Also: Chapter 4, " Managing Fonts in Oracle Reports" For more font-related information.

What is the real difference between running reports to Screen and Preview?

Formatting a report to Screen, for screen fonts, guarantees that the report will look good in the Paper Design view of the Report Editor. If an attempt is made to print a report formatted with screen fonts, though, it is likely to come out with some differences because screen fonts typically map very poorly to printer fonts. If Preview is selected instead of Screen, the report is formatted with printer fonts and the output on the screen is almost certain to match the printed output.

Will there be any font issues if I do not have a valid printer installed?

Earlier versions of OracleAS Reports Services required a valid printer on UNIX for fonts. When no valid printer was available, OracleAS Reports Services used the screen fonts, which again required the `DISPLAY` variable mentioned above. In OracleAS Reports Services 10g (9.0.4) includes a default screen printer surface, ScreenPrinter, that emulates a screen or printer for fonts in the absence of an available printer. As a result, OracleAS Reports Services does not require a printer on UNIX as of OracleAS Reports Services 10g (9.0.4).

See Also: Chapter 5, " Printing on UNIX with Oracle Reports " For more information on DISPLAY and printer dependencies on UNIX.

### 5.7.5 Printed Output Issues

Why does my report look okay on the screen but have truncated data when printed?

Any one of a number of possible causes may account for the truncation of fields.

- Check the field and determine if it is allowed to expand.

  1. In Reports Builder, double-click the field in the Paper Design or Paper Layout view to display the Property Inspector.

  2. Find the Horizontal Elasticity property.

  3. If it is set to Fixed, you should change it to Variable or Expand.

  4. Run the report to the printer.

  5. If it still truncates, it could be that the field requires multiple lines.

  6. Return to the Property Inspector for the field and check its Vertical Elasticity.

  7. If it is set to Fixed, you should change it to Variable or Expand.

  8. Run the report to the printer again.

- If the right most fields on the page are always the ones truncating, it could be an issue with the printable area of the printer. If you are using a PCL printer, then you will have to estimate the size of the printable area and resize your margins accordingly:

  1. Open the report in Reports Builder.

  2. Go to the Paper Layout view.

  3. Click on the Margin tool on the top tool bar. A thick black line appears indicating where the body of your report ends and the margin begins.

  4. Click and drag the black line to the left approximately 0.5 inches.

  5. Save and run the report to the printer again.

  6. If necessary, repeat steps 4 and 5 to determine approximately where the printable area boundary is located and then ensure that your report body fits within that area.

  If you are using a PostScript printer, you can get the printable area boundary to appear in the Paper Layout view as follows:

  1. Open the report in Reports Builder.

  2. Choose File > Page Setup.

  3. Verify that the margins are small and that the orientation is correct.

  4. Click OK. The Paper Layout view should now be able to read the boundary.

  5. Go to the Paper Layout view.

  6. Click on the Margin tool on the top tool bar. A thick black line appears indicating where the body of your report ends and the margin begins. A black hashed line also appears indicating the boundary of the printable area.

  7. Ensure that the thick black line is inside of the black hashed line. If it is not, click and drag the black line inside the printable area.

  8. Click the Margin tool to leave margin mode.

  9. If necessary, reposition your fields to fit within the new body boundaries.

  10. Save and run the report to the printer.

- For PCL, if it is still truncating, try using a fixed space font instead of a proportional font. Sometimes PCL printers have problems interpreting proportional space fonts and it leads to truncation. You should try using a fixed space font, such as Courier, and possibly font aliasing.

  See Also: Chapter 4, " Managing Fonts in Oracle Reports" For more font-related information.

  Note: Default layouts are built against a generic printer. Each printer has its own printable area. As a result, you may have to reset the report to fit the printer. Ideally, if you know the various printers you will be using, you can design the report from the start to fit the printer with the smallest printable area.