Skip Headers
Oracle® Outside In Viewer Developer's Guide
Release 8.4.1
Part Number E12845-05
Go to Documentation Home
Home		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
View PDF

3 UNIX Implementation Details

The UNIX implementation of the Oracle Outside In Viewer is delivered as a set of shared libraries.

The Viewer under all supported UNIX X Windows systems is implemented as the SccViewer widget class. The viewer widget is provided in OSF Motif style. The Oracle Outside In Viewer must be able to dynamically link against a Motif 2-compatible library named libXm.so.2. On Linux systems, the Oracle Outside In Viewer will use libXm.so.1. For more information, see Section 3.13, "Linux Compiling and Linking."

SccViewer widget provides all the functionality you need to view a file. The application sends SCCVW messages to the widget using the widget's XsccViewerAcceptMessage function. The widget returns communication to the application through its callback resource.

For a list of the currently supported platforms, see:

http://www.oracle.com/technetwork/indexes/documentation/index.html#middleware

Click on Outside In Technology, then click the Certification Information PDF.

This chapter includes the following sections:

3.1 Installation

To install the demo version of the SDK, copy the tgz file corresponding to your platform (available on the web site) to a local directory of your choice. Decompress the tgz file and then extract from the resulting tar file as follows:

gunzip tgzfile
tar xvf tarfile

The installation directory should contain the following directory structure:

Directory Description

/docs

Includes HTML and PDF versions of the manual you are reading right now.

/redist

Contains a working copy of the UNIX version of the technology.

/sdk/common

Contains the C include files needed to build or rebuild the technology.

/sdk/demo

Contains the compiled executables of the sample applications.

/sdk/resource

Contains localization resource files.

/sdk/samplecode

Contains a subdirectory holding the source code for a sample application.

/sdk/samplefiles

Contains sample files designed to exercise the technology.

3.1.1 NSF Support

Notes Storage Format (NSF) files are produced by the Lotus Notes Client or the Lotus Domino server. The NSF filter is the only Outside In filter that requires the native application to be present to filter the input documents. Due to integration with an outside application, NSF support will not work with redirected I/O nor will it work when an NSF file is embedded in another file. Lotus Domino version 8 must be installed on the same machine as OIT. The NSF filter is currently only supported on the Win32, Win x86-64, Linux x86-32, and Solaris Sparc 32 platforms. SCCID_LOTUSNOTESDIRECTORY is a Windows-only option and is ignored on Unix.

Additional steps must be taken to prepare the system. It is necessary to know the name of the directory in which Lotus Domino has been installed. On Linux, this default directory is /opt/ibm/lotus/notes/latest/linux. On Solaris, it is /opt/ibm/lotus/notes/latest/sunspa.

  • In the Lotus Domino directory, check for the existence of a file called "notes.ini". If the file "notes.ini" does not exist, create it in that directory and ensure that it contains the following single line:

    [Notes]

  • Add the Lotus Domino directory to the $LD_LIBRARY_PATH environment variable.

  • Set the environment variable $Notes_ExecDirectory to the Lotus Domino directory.

3.2 Libraries and Structure

On the UNIX platforms, Oracle Outside In technologies are delivered with a set of shared libraries. All libraries should be installed to a single directory. Depending upon your application, you may also need to add that directory to the system's runtime search path. For more information, see Section 3.6, "Environment Variables."

The following is a brief description of the included libraries and support files. Note that in instances where a file extension is listed as .*, the file extension will vary for each UNIX platform (sl on HP/UX, so on Linux and Solaris).

API Libraries

These libraries implement the API. They should be linked with the developer's application.

File Description

libsc_ca.*

Content Access module (provides organized chunker data for the developer)

libsc_da.*

Data Access module

libsc_fi.*

File Identification module (identifies files based on their contents). The File ID Specification may not be used directly by any application or workflow without it being separately licensed expressly for that purpose.

libsc_ta.*

Text Access module (provides straight text data for the developer)

libsc_vw.*

Viewer module (this is the library that your application loads, providing control of all viewer functions)

libsc_vw.o

IBM AIX only! Same as libsc_vw.a, except that this is not a library archive file (used with load subroutine to load the viewer at run time).

Support Libraries

File Description

libos_xwin.*

The native GDI implementation

libsc_anno.*

The annotation module

libsc_ch.*

Chunker (provides caching of and access to filter data for the display engines)

libsc_du.*

Display Utilities module (includes text formatting)

libsc_fa.*

Filter Access module

libsc_fmt.*

Formatting module (resolves numbers to formatted strings)

libsc_fut.*

Filter utility module

libsc_ind.*

Indexing engine

libsc_lo.*

Localization library (all strings, menus, dialogs and dialog procedures reside here)

libsc_ut.*

Utility functions, including IO subsystem

libsc_xp.*

XPrinter bridge

libwv_core.*

The GDI Abstraction layer

Display Engine Libraries

File Description

libde_bmp.*

Bitmap (TIFF, GIF, BMP, PCX…)

libde_vect.*

Vector/Presentation (PowerPoint, Impress, Freelance…)

libde_ss.*

Spreadsheet/Database (Excel, Calc, Lotus 123…)

libde_tree.*

Archive (ZIP, GZIP, TAR…)

libde_wp.*

Document (Word, Writer, WordPerfect…)

Filter Libraries

File Description

libvs_*.*

Filters for specific file types (there are more than 150 of these filters, covering more than 600 file formats)

Premier Graphics Filters

File Description

i*2.flt

These 30 .flt files are the import filters for premier graphics formats

isunx2.flt

Interface to premier graphics filters

Additional Files

File Description

adinit.dat

Support file for the vsacad and vsacd2 filters

cmmap000.bin

Tables for character mapping (all character sets)

cmmap000.sbc

Tables for character mapping (single-byte character sets). This file is located in the common directory.

cmmap000.dbc

Identical to cmmap000.Bin, but renamed for clarity (.dbc = double-byte character). This file is located in the common directory.

oitnsf.id

Support file for the vsnsf filter.

3.3 The Basics

All the steps outlined in this section are used in the sample applications provided with the SDK. Looking at the code for the apitest sample application is recommended for a real world example of this process.

3.3.1 What You Need in Your Source Code

Any source code that uses this product should #include the file sccvw.h and #define UNIX. For example, a UNIX application might have a source file with the following lines:

#define UNIX
#include <sccvw.h>

and a 64-bit UNIX application might have a source file with the following lines:

#define UNIX
#define UNIX_64
#include <sccvw.h>

3.3.2 Options and Information Storage

The technology creates three sets of information: the default options, a list of available filters and a list of available display engines. In the UNIX implementations, these lists are built by the technology as needed, usually the first time the Viewer is run. You do not need to ship these lists with your application.

These lists are stored in the $HOME/.oit directory. If the $HOME environment variable is not set, the files are placed in the same directory as the Oracle Outside In Technology. If a .oit directory does not exist in the user's $HOME directory, the .oit directory will be created automatically by the technology. The files are automatically regenerated if corrupted or deleted.

The files are:

  • *.d: Display engine list

  • *.opt: Persistent options

The names of these option files end in *.opt, and are intended to be unique enough to avoid conflict for any combination of machine name and install directory. This is intended to prevent problems with version conflicts when multiple versions of the Viewer and/or other Viewer-based products are installed on a single system. The file names are built from an 11-character string derived from the directory the Oracle Outside In technology resides in and the name of the machine it is being run on. The string is generated by code derived from the RSA Data Security, Inc. MD5 Message-Digest Algorithm.

3.3.3 Creating a SccViewer Widget

Standard X Toolkit Intrinsics functions may be used to create SccViewer widgets. The class pointer is sccViewerWidgetClass. The class name is SccViewerWidget. You may also set the associated resources at the creation time. The following sample code creates a SccViewer widget:

Widget   testWidget;
Widget   main_w;
   ...
testWidget = XtVaCreatedManagedWidget(
   "MyViewerWidget",
   sccViewerWidgetClass,           /* class pointer */
   main_w,                         /* parent widget */
   XtNsccViewerScrollBarWidth, 20, /* set scroll bar 
   NULL);                             resource*/

3.3.4 Sending Messages to a SccViewer Widget

The function XsccViewerAcceptMessage is provided to handle all SCCVW messages from the application to a SccViewer widget. Its syntax is:

long XsccViewerAcceptMessage(
         Widget sccViewerWidget,    /* the viewer widget */
         unsigned long dwMessage,   /* the SCCVW message */
         unsigned long wParam,      /* generic parameter */
         unsigned long lParam)      /* generic parameter */

SCCVW messages are like commands and requests from the application. For example, if you want to view a new file, you simply send a SCCVW_VIEWFILE message. The contents of dwMessage, wParam and lParam are described in the Messages section of this manual.

3.3.5 Callback from a SccViewer Widget

When a SccViewer widget needs to send a SCCVW message back to the application, it calls its callback resource XtNsccViewerCallback. The callback structure is:

typedef struct _SccViewerCallbackStruct
   {
   int reason;                /* same value as dwMessage */
   unsigned long dwMessage;   /* SCCVW message */
   unsigned long wParam;      /* generic parameter */
   unsigned long lParam;      /* generic parameter */
   long lAppReturn;           /* result from application */
   } SccViewerCallbackStruct, *SccViewerCallbackPtr;

3.4 Character Sets

This section provides information about supported character sets.

3.4.1 Default API Character Set

The strings passed in the UNIX API are ISO8859-1 by default.

3.4.2 Double-Byte Character Set Mapping

Please note that to optimize performance on systems that do not require DBCS support, a second character mapping bin file, that does not contain any of the DBCS pages, is now included. The second bin file will give additional performance benefits for English documents, but will not be able to handle DBCS documents. To use the new bin file, replace the cmmap000.bin with the new bin file, cmmap000.sbc. For clarity, a copy of the cmmap000.bin file named cmmap000.dbc has also been included. Both the cmmap000.sbc and cmmap000.dbc files are located in the Common directory of the technology.

3.5 Runtime Considerations

This section provides information about runtime considerations.

3.5.1 X Server Requirement

Access to a running X Windows server and the presence of Motif (or LessTif on Linux) are required to convert from vector formats on UNIX systems. Examples of vector graphics files include CAD drawings and presentation files such as Power Point 97 files. Bitmap graphic conversion, handled by the libDE_BMP.* engine, does not require access to a running X Windows server. Examples of bitmap file formats include GIF, JPEG, TIFF, and Windows BMP files.

Note that in order to accommodate both systems with and without X servers available, a runtime check for the presence of X libraries is performed. This check looks on the system-specific library path variable for the X libraries. If the X libraries are not found, this product will not perform vector graphics conversion.

Do not forget to set the $DISPLAY environment variable before running this product when vector graphic conversion is desired. This is particularly important to remember in situations such as CGI programs that start with a limited environment. For example, when running the technology from a remote session, setting DISPLAY=:0.0 will tell the system to use the X Windows server on the console.

3.5.2 OLE2 Objects

Some documents that the developer is attempting to convert may contain embedded OLE2 objects. There are platform-dependent limits on what the technology can do with OLE2 objects. However, Oracle Outside In will attempt to take advantage of the fact that some documents accompany an OLE2 embedding with a graphic snapshot, in the form of a Windows metafile.

On all platforms, when a metafile snapshot is available, the technology will use it to convert the object. When a metafile snapshot is not available on UNIX platforms, the technology will be unable to convert the OLE2 object.

3.5.3 Machine-Dependent Graphics Context

The system uses a machine configuration dependent graphics context to render some images. The number of colors available in the systems graphics context is a particularly important limiting factor. For example, if the video driver for a system running Oracle Outside In is set up to display 256 colors, images produced on that system would be limited to 256 colors.

3.5.4 Signal Handling

This product traps and handles the following signals:

  • SIGABRT

  • SIGBUS

  • SIGFPE

  • SIGILL

  • SIGINT

  • SIGSEGV

  • SIGTERM

Developers who wish to override our default handling of these signals should set up their own signal handlers. This may be safely done after the developer's application has called DAInitEx().


Note:

The Java Native Interface (JNI) allows Java code to call and be called by native code (C/C++ in the case of OIT). You may run into problems if Java isn't allowed to handle signals and forward them to OIT. If OIT catches the signals and forwards them to Java, the JVMs will sometimes crash. OIT installs signal handlers when DAInitEx() is called, so if you call OIT after the JVM is created, you will need to use libjsig. Refer here for more information:

http://www.oracle.com/technetwork/java/javase/index-137495.html

3.5.5 Runtime Search Path and $ORIGIN

Libraries and sample applications are all built with the $ORIGIN variable as part of the binaries' runtime search path. This means that at runtime, OIT libraries will automatically look in the directory they were loaded from to find their dependent libraries. You don't necessarily need to include the technology directory in your LD_LIBRARY_PATH or SHLIB_PATH.

As an example, an application that resides in the same directory as the OIT libraries and includes $ORIGIN in its runtime search path will have its dependent OIT libraries found automatically. You will still need to include the technology directory in your linker's search path at link time using something like -L and possibly -rpath-link.

Another example is an application that loads OIT libraries from a known directory. The loading of the first OIT library will locate the dependent libraries.

Note:

This feature does not work on AIX and FreeBSD.

3.6 Environment Variables

There are a number of environment variables that the UNIX implementation of the technology may use at run time. While described elsewhere, following is a short summary of those variables and what they do.

Variable Description

$LD_LIBRARY_PATH (FreeBSD, HP-UX Itanium 64, Linux, Solaris)

$SHLIB_PATH (HP-UX RISC 32)

$LIBPATH (AIX, iSeries)

These variables help your system's dynamic loader locate objects at runtime. If you have problems with libraries failing to load, try adding the path to the Oracle Outside In libraries to the appropriate environment variable. See your system's manual for the dynamic loader and its configuration for details.

Note that for products that have a 64-bit PA/RISC, 64-bit Solaris and Linux PPC/PPC64 distributable, they will also go under $LD_LIBRARY_PATH.

$DISPLAY

Must be set to point to a valid X Server to view files. For more information, see Section 3.5.1, "X Server Requirement."

$HOME

Must be set to allow the system to write the option, filter and display engine lists. For more information, see Section 3.3.2, "Options and Information Storage."

3.7 Menus

The Viewer exposes a number of menus that developers can use at their discretion. The specifics of the OEM's interaction with these menus under UNIX is discussed here.

3.7.1 Context Menu

The Viewer pops up a view window-specific context menu when the right mouse button is pressed. The context menu under UNIX contains Copy and the display engine's menu. For example, the following is an image of the context menu that appears while viewing a spreadsheet:

Figure 3-1 Spreadsheet Context Menu

Graphic of spreadsheet context menu

If this meets your application's needs and user interface standards, you can ignore the interaction described in the next section and let the Viewer do all the work. If you wish to handle the right button click yourself, this functionality can be overridden by handling the SCCVW_CONTEXTMENU message.

3.7.2 Menu Interaction

Each type of display engine (Document, Bitmap, Archive, etc.) has functions that are unique to the kinds of files it can view. For instance, zooming, rotation and dithering are functions associated with graphic images, but not with spreadsheets. To handle these specialized tasks, each display engine has a menu that is tailored specifically for it.

When the application receives a SCCVW_DISPLAYCHANGE message, it may call SCCVW_GETDISPLAYINFO. One of the elements returned by this message is a handle to a pop-up menu. The application may then do whatever it likes with this menu (except destroy it), such as saving it to be popped up at another time.

3.8 Default Font Aliases

The technology includes the following default font alias map for UNIX platforms. The first value is the original font, and the second is the alias.

3.9 Changing Resources

All of the strings used in the UNIX versions of Oracle Outside In products are contained in a file called lodlgstr.h. This file, located in the resource directory, can be modified for internationalization and other purposes. Everything necessary to rebuild the resource library to use the modified source file is included with the SDK.

Along with lodlgstr.h, an object file, scclo.o, has been provided which is necessary for the linking phase of the build. A makefile has also been provided for building the library. The makefile allows building on all of the UNIX platforms supported by Oracle Outside In. It may be necessary to make minor modifications to the makefile so that the system header files and libraries can be found for compiling and linking. There are standard INCLUDE and LIB make variables defined for each platform in the makefile – simply edit these variables to point to the header files and libraries on your particular system. Other make variables are:

Once these make variables are set, simply change to the build directory and type make. The resource library, libsc_lo, will be built and placed in the appropriate platform-specific directory. To use this library, copy it into the directory where the Oracle Outside In product resides, and the new, modified resource strings will then be used by the technology.

Menu constants are included in lomenu.h in the common directory.

All dialog boxes are created directly in the viewer code internally and are compiled and linked in the normal compilation process. There are no separate resource files corresponding to the .rc files in the Windows code.

Additional viewer resources are defined in xsccvw.h, which is included in the code for the sample executables and the viewer.

3.10 Xprinter Technology Setup and Description

Oracle has added UNIX printing capability through the Xprinter technology licensed from Bristol Technology. This technology adds several files to the Oracle Outside In Viewer. The following sections describe those files and how to customize them for your needs.

3.10.1 Overview of Xprinter Components

This section discusses Xprinter components.

3.10.1.1 Font Metric Files

The xprinter/fontmetrics/afm directory contains Adobe Font Metric (AFM) files. Since Xprinter uses these files internally, your Oracle Outside In applications will not normally access them directly.

3.10.1.2 Printer Description Files

PostScript Printer Description (PPD) files provide Xprinter with model-specific printer information, such as the available ROM fonts, paper bins, supported paper sizes, and available memory. Xprinter uses this information internally. PPD files are located by default in the xprinter/ppds directory.

The Oracle Outside In technology ships with a set of PPD files for printers that are supported and have been verified with the Xprinter technology. PPD files for other printers can be obtained from the manufacturer of a specific printer. Although they have not been verified with this technology, a new PPD file can be copied into the xprinter/ppds directory and this should make that printer available through this technology.

3.10.1.3 Soft Fonts

A soft font is an executable program that can be downloaded to a PostScript to make available a font not in the printer ROM. PostScript soft fonts are located in the xprinter/pssoftfonts directory which you will have to create when you add soft fonts to your system. For information about how to add a soft font to your system, see Section 3.10.3, "Customizing the Xprinter Environment."

3.10.1.4 Configuration Files

A configuration file, psstd.fonts, is copied to the xprinter directory. This file provides mappings of X Window font names to equivalent PostScript font names.

To map color names to their RGB values, Xprinter internally uses the xprinter/rgb.txt configuration file.

The xprinter/xprinter.prolog file contains the default PostScript prolog used by Xprinter.

The xprinter/Xpdefaults configuration file contains system default setup information. The Xprinter Printer Setup widget reads the file. The parameter values specified in this file apply to every other user on the system. For instructions about how to modify this file for your particular printer configuration, see Section 3.10.3, "Customizing the Xprinter Environment."

3.10.2 Using the Xprinter Printer Setup Widget

The Xprinter Printer Setup widget provides a standard user interface for selecting certain model-specific printer options such as paper trays, paper size, page orientation, and the spooler command.

The Xprinter Printer Setup widget also does the following:

Reads default configuration information from file $HOME/.Xpdefaults, which is your local setup information file

  • Presents this information to you and lets you modify these defaults as desired. You may then choose one of these options:

  • Save these default changes and store them in $HOME/.Xpdefaults

  • Cancel the changes

  • Provide the change information to your application for subsequent use in configuring the printer

3.10.2.1 Using Printer Setup Widget Buttons

The action area of the Printer Setup Widget contains up to six buttons:

  • Apply: Provides changed configuration information to the application without updating the $HOME/.Xpdefaults file.

  • Save: Writes the current configuration information to your default printer information file $HOME/.Xpdefaults.

  • Reset: Reloads the default configuration from $HOME/.Xpdefaults.

  • Cancel: Closes the dialog and aborts all configuration changes.

  • Options: Displays the options dialog box that allows you to select a different printer setup. This button is disabled if output is configured to be sent to a file instead of a printer.

  • Install: Displays the installation dialog box that allows you to add or remove printer devices and printer ports from the $HOME/.Xpdefaults file.

3.10.2.2 Configuring Printer Setup Options

You can specify the following options on the initial Printer Setup dialog:

  • Output to: Specify whether to send output to a file or to a printer. If you choose Printer Specific, you can send output to any printer type/port combination configured in your $HOME/.Xpdefaults file. If the port is FILE: (as in this example), Xprinter creates an output file specifically for the specified printer type. If you choose Generic (File Only), print output is sent to an Encapsulated PostScript or generic PCL file.

  • Printer: This field only appears if you select Output to: Printer Specific. It specifies the name of the default printer type/port to send print output to. Click the Options button to specify a different printer type/port combination.

  • File Name: This field only appears if you select Output to: Generic (File Only). Type the name of the print file you wish to create. To pipe print output to a command, type a ! character as the first character and then specify the command to pipe output to. For example, to pipe output to the lp command, enter the following:

    !lp -d ps

  • EPSF, PCL4, PCL5: This field only appears if you select Output to: File. Click this button to display a list of output file types and select the desired type. Available types are EPSF (Encapsulated PostScript), PCL4, andPCL5.

  • Orientation: Specify portrait or landscape.

  • Scale: To increase the size of the output, specify a value greater than 1.00. To reduce the size, specify a value less than 1.00. For example, a value of 2.00 would double the size of the output; a value of 0.50 would reduce it by half.

  • Copies: Specify the number of copies to print.

3.10.2.3 Adding a New Printer to the List of Printer Choices

To add a new printer to the list of available printers, you must perform the following steps:

  1. Define a port, which is an alias for the print command.

  2. Associate the port with the printer's PPD file.

To Define a New Port

To define a new port using the Printer Setup dialog, perform the following steps:

  1. Type the port definition in the Edit Port edit box. Port definitions have the following format:

    port= print_command

    The print_command is the command for sending output to the printer port. For example, suppose you have two printers: ORION and SIRIUS. Your definitions may look like the following:

    ORION=rsh bandit "lp -d ps1"
SIRIUS=rsh bandit "lp -d ps2"

    In this example, both printers are connected to the system bandit, so the print command is a remote shell command executed on bandit. ORION is a PostScript printer, so the command lp -d ps1 is executed on bandit to print to ORION. SIRIUS is another PostScript printer, so the print command executed on bandit to print to SIRIUS is lp -d ps2.

  2. Click Add/Replace. The new port is now included in the list of current port definitions.

  3. Repeat Step 2 for each printer you want to send output to.

To Modify an Existing Port

To modify an existing port using the Printer Setup dialog, perform the following steps:

  1. Display the Ports dialog. From the Printer Setup dialog, click Install, then Add Printer, then Define New Port.

  2. Select the port you want to modify and edit the port information in the Edit Port edit box.

  3. Click Add/Replace. The modified port is now included in the list of current port definitions.

To Match a Printer Device to a Port

To match a printer device to a port using the Printer Setup dialog, perform the following steps:

  1. Display the Add Printer dialog. From the Printer Setup dialog, click Install and then Add Printer.

  2. In the Printer Devices field, select the description that matches the printer you are installing. If no description matches your printer, contact your printer vendor for a printer description (PPD) file.

  3. Select the desired port in the Current Port Definitions list box and click Add Selected. The new printer is now included in the list of currently installed printers.

To Remove an Installed Printer

To remove a printer device/port combination using the Printer Setup dialog, perform the following steps:

  1. Display the Printer Installation dialog. From the Printer Setup dialog, click Install.

  2. In the Currently Installed Printers list box, select the printer you want to remove and click Remove Selected.

3.10.2.4 Localization Resources

Change the following resource definitions in your application's app-defaults file to translate the Printer Setup widget to another language:

*XbPrinterBox.applyLabelString: Apply
*XbPrinterBox.resetLabelString: Reset
*XbPrinterBox.optionsLabelString: Options...
*XbPrinterBox.cancelLabelString: Cancel
*XbPrinterBox.saveLabelString: Save
*XbPrinterBox.installLabelString: Install...
*XbPrinterBox.helpLabelString: Help
*XbPrinterBox.outputLabelString: Output To:
*XbPrinterBox.printerToggleString: Printer Specific
*XbPrinterBox.fileToggleString: Generic (File Only)
*XbPrinterBox.printerLabelString: Printer:
*XbPrinterBox.printerListString: Printer Name:
*XbPrinterBox.reslLabelString: Resolution:
*XbPrinterBox.pageLabelString: Page Size:
*XbPrinterBox.trayLabelString: Paper Tray:
*XbPrinterBox.fileLabelString: File Name:
*XbPrinterBox.orientLabelString: Orientation:
*XbPrinterBox.scaleLabelString: Scale:
*XbPrinterBox.portraitString: Portrait
*XbPrinterBox.landscapeString: Landscape
*XbPrinterBox.copiesLabelString: Copies:
*XbPrinterBox.title: Printer Setup
*XbPrinterBox.optionsDialogTitle: Options
*XbPrinterBox.copyrightDialogTitle: Copyright
*XbPrinterBox.copyrightOkLabelString: Ok
*XbPrinterBox.optionsOkLabelString: Ok
*XbPrinterBox.optionsCancelLabelString: Cancel
*XbPrinterBox.installDialogTitle: Printer Installation
*XbPrinterBox.installRemoveSelectedLabelString: Remove Selected
*XbPrinterBox.installAddPrinterLabelString: Add Printer...
*XbPrinterBox.installDismissLabelString: Dismiss
*XbPrinterBox.installCancelLabelString: Cancel
*XbPrinterBox.installCurrentPrintersLabelString: Currently Installed Printers
*XbPrinterBox.addPrinterDialogTitle: Add Printer
*XbPrinterBox.addPrinterAddSelectedLabelString: Add Selected
*XbPrinterBox.addPrinterDefineNewPortLabelString: Define New Port...
*XbPrinterBox.addPrinterDismissLabelString: Dismiss
*XbPrinterBox.addPrinterPrinterDevicesLabelString: Printer Devices
*XbPrinterBox.addPrinterCurrentPortDefinitionsLabelString: Current Port Definitions
*XbPrinterBox.portsDialogTitle: Ports
*XbPrinterBox.portsAddReplaceLabelString: Add-Replace
*XbPrinterBox.portsRemoveLabelString: Remove
*XbPrinterBox.portsSpoolerLabelString: Spooler
*XbPrinterBox.portsDismissLabelString: Dismiss
*XbPrinterBox.portsCancelLabelString: Cancel
*XbPrinterBox.portsPortsLabelString: Ports
*XbPrinterBox.portsEditPortLabelString: Edit Port:

3.10.3 Customizing the Xprinter Environment

Xprinter allows you to configure options such as paper trays, paper size, and page orientation, so you do not need to hard-code these values in your application. You can use Xprinter configuration options to customize your Xprinter environment in the following ways:

  • Specify the printer to X Window font mappings

  • Customize printer description files

  • Modify system and user default printer setup values

  • Add a downloadable soft font to your system

  • Print Japanese characters

Mapping Printer Fonts to X Window Fonts

For compliance with the font-naming scheme recommended in X11, Release 5, Xprinter requires a font name mapping between the names of the available fonts on the printer and the names of the equivalent fonts in the standard XFLD format.

The xprinter/psstd.fonts file contains the font mapping for all PostScript printers. This file contains two fields: the face name of the printer font and the corresponding X Window font name.

Important:

The psstd.fonts file does not list the available fonts on the configured printer. Instead, the list of the available fonts for a printer is read from the printer's corresponding PPD file.

If your printer contains fonts that are not listed in psstd.fonts, you must add an entry for the font in psstd.fonts to access the font on the printer. Xprinter uses the font naming convention of X11, Release 5 to specify scalable fonts. A point size of zero represents a scalable font. For instance, if the scalable font Helvetica exists on the printer, the font name returned from the file would have the following format (assuming a 300 DPI printer):

-adobe-helvetica-medium-r-normal--0-0-300-300-p-0-iso8859-1

Customizing Printer Description Files

Xprinter uses the Adobe PostScript Printer Description (PPD) files to describe model-specific features such as the available RAM, fonts, papers trays, supported paper sizes, and other printer-specific information.

Adobe defined the PPD standard so that technologies like Xprinter can be printer independent. Adobe and other printer manufacturers provide PPD files for all PostScript-compatible printers.

Xprinter contains PPD files for about two hundred different printers and plotters. They are installed in xprinter/ppds. You can obtain additional printer PPD files from either Adobe or the manufacturer of your printer.

Modifying Default Printer Setup Values

Xprinter retrieves default printer setup information from the file .Xpdefaults in your home directory. If this file does not exist, Xprinter reads the information from the file xprinter/Xpdefaults. The Xprinter Printer Setup widget writes modifications to the default setup in $HOME/.Xpdefaults. However, it never modifies the default information in the file xprinter/Xpdefaults. If the file $HOME/.Xpdefaults does not already exist, the Xprinter Printer Setup widget creates it.

Although the most common way to modify the default Printer Setup values is with the Printer Setup widget, which updates $HOME/.Xpdefaults automatically, you can also edit this file with any text editor and make changes directly.

You may make the modify the $HOME/.Xpdefaults file to do the following:

  • Define printer ports

  • Match printer types to defined ports

  • Specify the default printer

  • Specify printer-specific options

Defining a Port

A printer port is an alias for the print command. It is defined in the [ports] section of $HOME/.Xpdefaults and appears as part of the Printer Name in the Printer Setup dialog. For example, the following is the first Printer Name in the Printer Setup dialog before you make any changes to $HOME/.Xpdefaults:

AppleLaserWriter v23.0 PostScript on FILE:

In this Printer Name, FILE: is the port name. To send output to a printer instead of a file, you must define a port for each printer you want to direct output to. Port entries in the [ports] section have the following format:

port= print_command

The print_command is the command for sending output to the printer port. For example, suppose you have two printers: ORION and SIRIUS. Your [ports] section may look like the following example:

[ports]
ORION=rsh bandit "lp -d ps1"
SIRIUS=rsh bandit "lp -d ps2"

In this example, both printers are connected to the system bandit, so the print command is a remote shell command executed on bandit. ORION is a PostScript printer, so the command lp -d ps1 is executed on bandit to print to ORION. SIRIUS is another PostScript printer, so the print command executed on bandit to print to SIRIUS is lp -d ps2.

If you have a printer connected to your local system, you need to add an entry for it as well. For the local printer, you need to add an entry similar to the following:

[ports]
ORION=rsh bandit "lp -d ps1"
SIRIUS=rsh bandit "lp -d ps2"
LOCAL=lp -d ps

Your printer port can be any name you choose except FILE:, which is the only reserved port name. It causes Xprinter to create a print file formatted specifically for the specified printer type.

You must create an entry in the [ports] section for every printer you wish to be able to print to.

Matching a Printer Type to a Defined Port

Once you've defined a port for each printer, you must tell Xprinter what type of printer is associated with each port. You list device types in the [devices] section of the .Xpdefaults file. Each entry in the [devices] section has the following format:

alias= PPD_file driver,port

Note that there must be a space between the PPD_file and driver and a comma between the driver and the port. The following list describes each part of this entry:

  • alias: The alias is a descriptive name used to identify the printer. It can be anything you like. The alias is the name of the printer that appears in the printer setup dialog (for example, HP LaserJet III SI PostScript).

  • PPD_file: The PPD_file is the name of the printer description (PPD) file used by the printer, without the .ppd extension. Look in the file xprinter/ppds/filename.map to identify the PPD file for your printer.

  • driver: The driver is the type of driver the printer uses. The only valid value is PostScript.

  • port: The port is the printer port as listed in the [ports] section of the .Xpdefaults file (ORION, SIRIUS, and LOCAL in the example [ports] section).

Printer Configuration Examples

This example demonstrates how to configure the following printers:

Port Printer Type Output Type

ORION

HP LaserJet IIISi PostScript v52.3

PostScript

SIRIUS

SunPics NeWSprinter20

PostScript

LOCAL

QMS-PS 2200 v52.3

PostScript

  1. First, choose an alias for each printer. To make it easy to identify the printer you want to use from the Printer Setup dialog, you might use the following aliases for these printers:

    • HP LaserJet PS

    • NeWSprinter

    • QMS PS

      Note:

      If you use the Printer Setup dialog to associate ports and PPD files, you cannot specify a printer alias. You must choose an alias from the predefined list that appears in the Printer Devices list box in the Add Printer dialog. The corresponding PPD file is already associated with the printer aliases in this list box.

  2. Next, identify the PPD file associated with each of these printers. In the xprinter/ppds/filename.map file, you can see that the PPD file for the printer on port ORION is hp3si523.ps, the PPD file for the printer on port LOCAL is q2200523.ps, and the PPD file for the printer on port SIRIUS is np20.ps.

    In this example, the [devices] section of the .Xpdefaults file would be as follows:

    [devices]
HP LaserJet PS=HP3SI523 PostScript,ORION
NeWSprinter=NP20 PostScript,SIRIUS
QMS PS=Q2200523 PostScript,LOCAL

    Once you've added these entries to your .Xpdefaults file, the following printer choices are available from the printer setup dialog:

    HP LaserJet PS on ORION
NeWSprinter on SIRIUS
QMS PS on LOCAL

Specifying a Default Printer

Now that you've configured all available printers, you can make one of them the default printer. To make a specific printer the default printer on the printer setup dialog, add an entry of the following format to the [windows] section of the .Xpdefaults file:

[windows]
device= PPD_file, driver, port

You simply need to provide the same information that you used in the [devices] section. Only the format of the entry is different; there is a comma between the PPD_file and the driver instead of a space.

For example, suppose you want the default printer to be the printer at port ORION. Your [windows] section would look like the following:

[windows]
device=HP3SI523,PostScript,ORION

The first three sections of your .Xpdefaults file looks like the following:

[windows]
device=HP3SI523,PostScript,ORION
[ports]
ORION=rsh bandit "lp -d ps"
SIRUS=rsh bandit "lp -d ps2"
LOCAL=lp -d ps
[devices]
HP LaserJet PS=HP3SI523 PostScript,ORION
NeWSprinter=NP20 PostScript,SIRIUS
QMS PS=Q2200523 PostScript,LOCAL

In your default .Xpdefaults file, the [windows] entry looks like the following:

[windows]
device=NULL,PostScript,FILE:

Since no PPD file is listed (NULL), the default on the printer setup dialog is to print generic PostScript to a file. You can specify the filename and change the type of output to PCL on the Printer Setup dialog.

Specifying Printer-Specific Options

For each printer defined in the devices section, you can include a section that lists the default printer-specific options for that printer. The options available vary between different printers, but typical options include number of copies, page size, paper tray, and orientation. The following is an example printer-specific section for default printer in the example .Xpdefaults file:

[HP3SI523,PostScript]
Scale=0.80
Copies=1
PaperTray=Lower
PageSize=Letter
Orientation=Portrait
DPI=300

Adding a Soft Font

Xprinter can access fonts from two sources: ROM-resident fonts and soft fonts. ROM-resident fonts are built into the printer. To access them, you do not need to add additional information for the printer. Instead, Xprinter determines whether or not a font is resident on a ROM by querying the PPD file for the specified printer.

You can extend the number of fonts available to you by adding soft fonts to your system. When you add a soft font, Xprinter detects it and downloads it as necessary when requested to do so by the application.

To add a soft font to your system, perform these steps in the following sequence:

  1. Copy the PostScript Font-Binary (PFB) file from the TypeLibrary diskette to the xprinter/pssoftfonts directory. The TypeLibrary diskette is available from the font vendor.

  2. Rename the PBF file to the face name of the font. Typically, TypeLibrary file names are abbreviated. For example, the filename for face name AGaramond-Bold is gdb_.pfb.

  3. Copying the file to this directory makes the file available to Xprinter for downloading to a PostScript printer.

  4. Copy the AFM (Adobe Font Metric) file for the font to the directory xprinter/fontmetrics/afm. Again, rename the file to the face name of the font with a .afm extension. Using the example of AGaramond-Bold, the AFM file should be copied to xprinter/fontmetrics/afm/agaramond-bold.afm.

  5. Modify the xprinter/psstd.fonts file. This modification is necessary to cause Xprinter to create the X Window font name for the new font and provide the required mapping, as in the following example:

    AGaramond-Bold, -adobe-garamond-bold-normal--%d-%d-%d-%d-p-0-iso8859-1

    When Xprinter performs font operations, particularly querying the available fonts and loading fonts, it searches the PPD file for the available ROM fonts. Xprinter also searches the directory xprinter/pssoftfonts for the available soft fonts.

    An Oracle Outside In application should not need to consider whether the font originated in the printer ROM or if it is a downloadable soft font. Extending the fonts available to the Oracle Outside In application should be completely transparent to the application user.

3.11 HP-UX Compiling and Linking

All libraries should be installed into a single directory and the directory should be included in the system's executable path ($PATH).

The libsc_vw.sl is the only library that needs to be linked with your application. It can be loaded when your application starts by linking it directly at compile time or it can be loaded dynamically by your application using library load functions (for example, shl_load).

The shared libraries are dependent on the presence of the X libraries Xm, Xt and X11 if vector graphics support is required. It is the application developer's responsibility to ensure that the needed functions from these libraries are present before the Viewer libraries are used.

The following are example command lines used to compile the sample application apitest from the /sdk/samplecode/unix directory. Note this is only an example. The actual command line required on the developer's system may vary. The example assumes that the include and library file search paths for the technology libraries and any required X libraries are set correctly. If they are not set correctly, the search paths for the include and/or library files must be explicitly specified via the -I<include file path> and/or -L<library file path> options, respectively, so that the compiler and linker can locate all required files.

cc -w -o ../apitest/unix/apitest ../apitest/unix/apitest.c +DAportable -Ae -I/usr/include -I../../common -I/usr/X11R6/include -L/usr/lib -L../../demo -lsc_vw -lsc_fi -lXm -lXt -lX11 -Wl,+s,+b,'$ORIGIN'

3.12 IBM AIX Compiling and Linking

All libraries should be installed into a single directory and the directory must be included in the system's executable path ($PATH).

Note:

$LIBPATH MUST be set and must point to the directory containing the Oracle Outside In Technology.

Oracle Outside In technology has been updated to increase performance, at a cost of using more memory. It is possible that this increased memory usage may cause a problem on AIX systems, which can be very conservative in the amount of memory they grant to processes. If your application experiences problems due to memory limitations with Oracle Outside In, you may be able to fix this problem by using the "large page" memory model. If you anticipate viewing or converting very large files with Oracle Outside In technology, we recommend linking your applications with the -bmaxdata flag (for example, 'cc -o foo foo.c -bmaxdata:0x80000000'). If you are currently seeing illegal instruction errors followed by immediate program exit, this is likely due to not using the large data model.

The shared libraries are dependent on the presence of the X libraries Xm, Xt and X11 if vector graphics support is required. It is the application developer's responsibility to ensure that the needed functions from these libraries are present before the Viewer libraries are used.

The following is an example command line used to compile the sample application apitest from the /sdk/samplecode/unix directory. Please note that this command line is only an example. The actual command line required on the developer's system may vary. The example assumes that the include and library file search paths for the technology libraries and any required X libraries are set correctly. If they are not set correctly, the search paths for the include and/or library files must be explicitly specified via the -I<include file path> and/or -L<library file path> options, respectively, so that the compiler and linker can locate all required files. Developers need to pass -brtl to the linker to list libraries in the link command as dependencies of their applications.

Developers may need to use the -qcpluscmt flag to allow C++ style comments.

gcc -w -o ../apitest/unix/apitest ../apitest/unix/apitest.c -I/usr/X11R6/include -I../../common -L../../demo -lsc_vw -lsc_fi -lXm -lXt -lX11  -Wl, -brtl

3.13 Linux Compiling and Linking

This section provides information about Linux compiling and linking.

3.13.1 Library Compatibility

This section provides information about library compatibility.

3.13.1.1 Motif Libraries

On some Linux installations, particularly newer ones, the Motif libraries that are installed are not compatible with the libraries that are used to build the Oracle Outside In technology. This is known to be the case with most of the SuSE installations, for example. It is likely that you have a binary incompatibility if you try to build one of the Xwindows-based sample applications included with this product and see an error at compile time that looks like the following:

warning: libXm.so.3, needed by ../../libsc_vw.so, may conflict with libXm.so.2

The proper solution to this problem is to install a compatible Motif library and use it to build your application. Often, the installation discs for your particular Linux platform will have the proper libraries. If your installation discs do not have the libraries, instructions for downloading a binary rpm can be found at http://rpmfind.net/linux/RPM.

Remember that if you are doing development, you will also need the proper header files, as well.

The following is a list of the Motif library versions used by Oracle when building and testing the Oracle Outside In binaries.

  • x86 Linux: OpenMotif v. 2.2.3

  • Itanium Linux: OpenMotif v. 2.1.30.

3.13.1.2 GLIBC and Compiler Versions

For each Linux platform supported by Oracle Outside In, the following table indicates the compiler version used and the minimum required version of the GNU standard C library upon which Oracle Outside In depends.

Distribution Compiler Version Output Type

x86 Linux

3.3.2

libc.so.6 (2.2.4 or newer)

Itanium Linux

3.3.2

libc.so.6 (2.2.4 or newer)

zSeries Linux

3.3.6

libc.so.6 (2.3.2 or newer)

3.13.1.3 Other Libraries

In addition to libc.so.6, Oracle Outside In is dependent upon the following libraries:

  • libXm.so.3 (in particular, libXm.so.3.0.2 or newer, due to issues in OpenMotif 2.2.2)

  • libstdc++.so.5.0.5

  • libgcc_so.1

  • libXt.so.6

Note that libgcc_s.so.1 was introduced with GCC 3.0, so any distribution based on a pre-GCC 3.0 compiler will not include libgcc_s.so.1.

The following table summarizes what is included with the RedHat and SuSE distributions supported by Oracle Outside In and what needs to be added/modified to make Oracle Outside In run on these systems. Developers may have trouble building with libstdc++.so.5 versions before 5.0.5 due to unversioned symbols. Upgrade to 5.0.5 to correct the problem.

Libraries on Linux Systems as Distributed (IA32)

Advanced Server 3.0 Support Information

libc.so.6 version

/lib/libc-2.3.2

libstdc++

/usr/lib/libstdc++.so.5.0.3

libgcc_s.so.1

/lib/libgcc_s.so-3.2.3-20030829.so.1

libXm.so.X

libXm.so.2 (OpenMotif 2.1.30-8)

libXm.so.3.0.1 (OpenMotif 2.2.2-16)

Required to Use Oracle Outside In

  • Update to >= libXm.so.3.0.2 (OpenMotif >=2.2.3)

  • Default system install has the proper libstdc++.so.5

  • Default system install includes libgcc_s.so.1

  • Install X libraries

Advanced Server 4.0 Support Information

libc.so.6 version

/lib/libc-2.3.4

libstdc++

/usr/lib/libstdc++.so.6.0.3

libgcc_s.so.1

/usr/lib/libgcc_s.so-3.4.3-20041213.so.1

libXm.so.X

libXm.so.2 (OpenMotif 2.1.30-11)

libXm.so.3.0.2 (OpenMotif 2.2.3-6)

Required to Use Oracle Outside In

  • Install Motif 2.2.3 from distribution media

  • Install libstdc++.so.5 (included with gcc 3.2 - 3.3.6)

  • Default system install includes libgcc_s.so.1

  • Install X libraries

SuSE 8.1 Support Information

libc.so.6 version

/lib/libc.so.6 (GLIBC 2.2.5)

libstdc++

/usr/lib/libstdc++.so.5.0.0

libgcc_s.so.1

/lib/libgcc_s.so.1

libXm.so.X

libXm.so.3.0.1

Required to Use Oracle Outside In

  • Update to >= libXm.so.3.0.2 (OpenMotif >=2.2.3)

  • Default system install has proper libstdc++.so.5

  • Default system install has libgcc_so.1

  • Install X libraries

SuSE 9.0 Support Information

libc.so.6 version

/lib/libc.so.6 (GLIBC 2.3.4)

libstdc++

/usr/lib/libstdc++.so.5.0.6 + old libraries

libgcc_s.so.1

/lib/libgcc_s.so.1

libXm.so.X

libXm.so.3.0.1

Required to Use Oracle Outside In

  • Update to >= libXm.so.3.0.2 (OpenMotif >=2.2.3)

  • Default system install has proper libstdc++.so.5

  • Default system install has libgcc_so.1

  • Install X libraries

Libraries on Linux Systems as Distributed (IA64)

SuSE 8.1 Support Information

libc.so.6 version

/lib/libc.so.6 (GLIBC 2.2.5)

libstdc++

/usr/lib/libstdc++.so.5.0.0

libgcc_s.so.1

/lib/libgcc_s.so.1

Required to Use Oracle Outside In

  • Update to >= libXm.so.3.0.2 (OpenMotif >=2.2.3)

  • Default system install has proper libstdc++.so.5

  • Default system install has libgcc_so.1

  • Install X libraries

SuSE 9.0 Support Information

libc.so.6 version

/lib/libc.so.6 (GLIBC 2.3.4)

libstdc++

/usr/lib/libstdc++.so.5.0.6 + old libraries

libgcc_s.so.1

/lib/libgcc_s.so.1

Required to Use Oracle Outside In

  • Update to >= libXm.so.3.0.2 (OpenMotif >=2.2.3)

  • Default system install has proper libstdc++.so.5

  • Default system install has libgcc_so.1

  • Install X libraries

SuSE Linux Enterprise Server 8.0 Support Information

libc.so.6 version

/lib/libc.so.6.1 (GLIBC 2.2.6)

libstdc++

/usr/lib/libstdc++-libc6.2-2.so.3

/usr/lib/libstdc++.so.5.0.0

libgcc_s.so.1

/lib/libgcc_s.so.1

Required to Use Oracle Outside In

  • Update to >= libXm.so.3.0.2 (OpenMotif >=2.2.3)

  • Default system install has proper libstdc++.so.5.

  • Default system install has libgcc_so.1

  • Install X libraries

3.13.2 Compiling and Linking

All libraries should be installed into a single directory and the directory should be included in the system's executable path ($PATH).

The libsc_vw.so module is the only library that must be linked with your application. It can be loaded when your application starts by linking it directly at compile time or it can be loaded dynamically by your application using library load functions (for example, dlopen).

The shared libraries are dependent on the presence of the X libraries Xm, Xt and X11 if vector graphics support is required. It is the application developer's responsibility to ensure that the needed functions from these libraries are present before the libraries are used.

The following is an example command line used to compile the sample application apitest from the /sdk/samplecode/unix directory. Please note that this command line is only an example. The actual command line required on the developer's system may vary. The example assumes that the include and library file search paths for the technology libraries and any required X libraries are set correctly. If they are not set correctly, the search paths for the include and/or library files must be explicitly specified via the -I<include file path> and/or -L<library file path> options, respectively, so that the compiler and linker can locate all required files.

gcc -w -o ../apitest/unix/apitest ../apitest/unix/apitest.c -I../../common -I/usr/X11R6/include -L../../demo -lsc_vw -lsc_fi -L/usr/X11R6/lib -lXm -lXt -lX11 -Wl,-rpath,../../demo -Wl,-rpath,'${ORIGIN}'

3.14 Oracle Solaris Compiling and Linking

This product does not support the old Solaris BSD mode.

All libraries should be installed into a single directory.

The libsc_vw.so module is the only library that must be linked with your application. It can be loaded when your application starts by linking it directly at compile time or it can be loaded dynamically by your application using library load functions (for example, dlopen).

The shared libraries are dependent on the presence of the X libraries Xm, Xt and X11 if vector graphics support is required. It is the application developer's responsibility to ensure that the needed functions from these libraries are present before the libraries are used.

The following is an example command line used to compile the sample application apitest from the /sdk/samplecode/unix directory. Please note that this command line is only an example. The actual command line required on the developer's system may vary. The example assumes that the include and library file search paths for the technology libraries and any required X libraries are set correctly. If they are not set correctly, the search paths for the include and/or library files must be explicitly specified via the -I<include file path> and/or -L<library file path> options, respectively, so that the compiler and linker can locate all required files.

Developers may need to use the -xcc flag to allow C++ style comments.

3.14.1 Solaris SPARC

cc -w -o ../apitest/unix/apitest ../apitest/unix/apitest.c -I/usr/include -I/usr/dt/share/include -I../../common -L../../demo -L/usr/lib -L/lib -lXm -lXt -lX11 -lsc_vw -lsc_fi -Wl,-R,'${ORIGIN}'

Note: When running the 32-bit SPARC binaries on Solaris 9 systems, you may see the following error:

ld.so.1: simple: fatal: libm.so.1: version `SUNW_1.1.1' not found
(required by file ./libsc_vw.so)

This is due to a missing system patch. Please apply one of the following patches (or its successor) to your system to correct.

  • For Solaris 9: Patch 111722-04

3.14.2 Solaris x86

Note:

Your system will require Solaris patch 108436, which contains the C++ library libCstd.so.1.

cc -w -o ../apitest/unix/apitest ../apitest/unix/apitest.c -I/usr/include -I/usr/dt/share/include -I../../common -L../../demo -L/usr/lib -L/lib -lXm -lXt -lX11 -lsc_vw -lsc_fi -Wl,-R,'${ORIGIN}'
Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us