1. Developer's Guide
  2. Using the C/C++ API
  3. UNIX Implementation Details

6 UNIX Implementation Details

This chapter describes the UNIX implementation of the HTML Export SDK. The UNIX implementation of the Export product set is delivered as a set of shared libraries.

For a list of the currently supported platforms, see Outside In Technology and click links under Certified Platforms and Supported Formats from the Get Started page.

This chapter includes the following sections:

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

/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. For more information, see Changing Resources.

/sdk/samplecode

Contains a subdirectory holding the source code for a sample application. For more information, see Sample Applications.

/sdk/samplefiles

Contains sample input files authored in a variety of popular graphics, word processor, compression, spreadsheet and presentation applications.

/sdk/template

Contains a number of sample templates designed to exercise HTML Export's template language. Some templates consist of multiple files. When this is the case, main.htm is the file to which the SCCOPT_TEMPLATE option should point.

6.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. SCCOPT_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.

6.2 Libraries and Structure

On UNIX platforms the Outside In products 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 Environment Variables.

The following is a brief description of the included libraries and support files. In instances where a file extension is listed as .*, the file extension varies for each UNIX platform (sl on HP-UX, so on Linux and Solaris).

6.2.1 API Libraries

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

Library Description HTML Export Image Export PDF Export Search Export XML Export Web View Export

libsc_da.*

Data Access module

X

X

X

X

X

X

libsc_ex.*

Export module

X

X

X

X

X

X

libsc_fi.*

File Identification module (identifies files based on their contents).

X

X

X

X

X

X

The File ID Specification may not be used directly by any application or workflow without it being separately licensed expressly for that purpose.

6.2.2 Support Libraries

The following libraries are used for support.

Library Description HTML Export Image Export PDF Export Search Export XML Export Web View Export

libccflex.*

A data model adapter that converts from stream model utilized by Outside In filters to the FlexionDoc Tree model used as a basis by XML Export.

X

libexpatw.*

A third-party XML parser.

X

liboc_emul.*

Output component emulation module

X

X

X

X

X

X

libos_gd.*

The internal rendering GDI implementation. This library is only supported on Linux (32- and 64-bit Intel), Solaris (32-bit SPARC), HP-UX (32-bit RISC), and AIX (32-bit PPC).

X

X

X

X

libos_pdf.*

PDF generation module

X

libos_xwin.*

The native GDI implementation

X

X

X

X

libsc_anno.*

The annotation module

X

X

X

X

libsc_ca.*

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

X

X

X

X

libsc_ch.*

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

X

X

X

X

X

X

libsc_du.*

Display Utilities module (includes text formatting)

X

X

X

X

X

X

libsc_fmt.*

Formatting module (resolves numbers to formatted strings)

X

X

X

X

X

X

libsc_fut.*

Filter utility module

X

X

X

X

X

X

libsc_ind.*

Indexing engine. In Search Export, it handles common functionality.

X

X

X

X

X

libsc_lo.*

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

X

X

X

X

X

X

libsc_sd.*

Schema Definition Module Manager (brokers multiple Schema Definition Modules)

X

libsc_ut.*

Utility functions, including IO subsystem

X

X

X

X

X

X

libsc_xp.*

XPrinter bridge

X

X

X

X

libsdflex.*

Schema Definition module (handles conversion of XML string names and attribute values to compact binary representations and vice versa)

X

libwv_core.*

The Abstraction layer

X

X

X

X

X

X

libwv_gdlib.so

The GDI rendering module. This library is only supported on Linux (32- and 64-bit Intel), Solaris (32-bit SPARC), HP-UX (32-bit RISC), and AIX (32-bit PPC).

X

X

X

X

6.2.3 Engine Libraries

The following libraries are used for display purposes.

Library Description    HTML Export Image Export PDF Export Search Export XML Export Web View Export

libde_bmp.*

Raster rendering engine (TIFF, GIF, BMP, PNG, PCX…)

X

X

X

libde_vect.*

Vector/Presentation rendering engine (PowerPoint, Impress, Freelance)

X

X

X

X

X

libde_ss.*

Spreadsheet/Database (Excel, Calc, Lotus 123)

X

X

X

libde_tree*

Archive (ZIP, GZIP, TAR…)

X

X

libde_wp.*

Document (Word, Writer, WordPerfect)

X

X

X

X

6.2.4 Filter and Export Filter Libraries

The following libraries are used for filtering.

libex_gdsf must be linked with libsc_img.* at compile time. This forces the filter to be dependent on libsc_img.* at runtime, even though that module may not be used directly. If you want to reduce your application's physical footprint, you can experiment with unlinking libsc_img.*.

Library Description HTML Export Image Export PDF Export Search Export XML Export Web View Export

libvs_*.*

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

X

X

X

X

X

X

libex_gdsf.*

Export filter for GIF, JPEG, and PNG graphics files

X

X

X

libex_h5.*

Export filter for HTML5 files

X

libsc_img.*

Image conversion module

X

X

X

X

libex_itext.*

Export filter for SearchText

X

libex_html.*

Export filter for HTML files

X

libex_img.*

Extended image conversion module

X

libex_xml.*

Export filter for XML files using the Flexiondoc schema

X

libex_page.*

Export filter for XML files using the PageML schema

X

libex_pagelayout.*

Page Layout module

X

libex_ixml.*

Export filters for XML files using the SearchML schema

X

libex_ihtml.*

Export filter for SearchHTML

X

6.2.5 Premier Graphics Filters

The following are graphics filters.

Library Description HTML Export Image Export PDF Export Search Export XML Export Web View Export

libi*.*

These files are the import filters for premier graphics formats.

X

X

X

X

X

X

libis_unx2.*

Interface to premier graphics filters

X

X

X

X

X

X

6.2.6 Additional Files

The following files are also used.

Library Description HTML Export Image Export PDF Export Search Export XML Export Web View Export

adinit.dat

Support file for the vsacad and vsacd2 filters

X

X

X

X

X

X

ccbf.so

Internal

X

cmmap000.bin

Tables for character mapping (all character sets)

X

X

X

X

X

X

cmmap000.sbc

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

X

X

X

X

X

X

cmmap000.dbc

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

X

X

X

X

X

X

exbf.so

Internal

X

flexiondoc.dtd

The DTD version of the Flexiondoc schema

X

flexiondoc.xsd

The schema version of the Flexiondoc schema

X

libfreetype.so.6

TrueType font rendering module for the GD output solution. 32-bit Linux and Solaris Sparc only.

X

X

X

X

X

oitnsf.id

Support file for the vsnsf filter.

X

X

X

X

X

X

pageml.dtd

The Document Type Definition for the PageML schema

X

pageml.xsd

The Extensible Schema Definition for the PageML schema

X

searchml3.dtd

The Document Type Definitions for the SearchML schema

X

searchml3.xsd

The Extensible Schema Definitions for the SearchML schema

X

6.3 The Basics

Sample applications are provided with the SDK. These applications demonstrate most of the concepts described in this manual. For a complete description of the sample applications, see Sample Applications.

6.3.1 What You Need in Your Source Code

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

#define UNIX
#include <sccex.h>

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

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

HTML Export can generate many open files at the same time, thereby hitting user/system-defined limits. There are two UNIX solutions to this:

  • Increase the maximum file count by using the ulimit console command. Consult the UNIX man pages for your shell of choice (sh, ksh, bash) for the shell command "ulimit."

  • Make a system call in the code (before calling export functions):

    setrlimit(RLIMIT_NOFILE,...)

    Consult the UNIX man pages for the system C function "setrlimit."

6.3.2 Information Storage

This software is based on the Outside In Viewer Technology (or simply "Viewer Technology"). A file of default options is always created, and a list of available filters and a list of available display engines are also built by the technology, usually the first time the product runs (for UNIX implementations). You do not need to ship these lists with your application.

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

The files are:

  • *.f: Filter lists

  • *.d: Display engine list

  • *.opt: Persistent options

The technology does not actually use the list of default options created by the Viewer Technology.

The filenames 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 Technology and/or other Viewer Technology-based products are installed on a single system. The filenames are built from an 11-character string derived from the directory the 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.

The products still function if these files cannot be created for some reason. In that situation, however, significant performance degradation should be expected.

6.4 Character Sets

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

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 gives additional performance benefits for English documents, but cannot 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 (cmmap000.dbc) is also included. Both cmmap000.sbc and cmmap000.dbc are located in the /sdk/common directory of the technology.

6.5 Runtime Considerations

The following is information to consider during run-time.

6.5.1 X Server Requirement

Note:

The X Server requirement can be eliminated by setting the SCCOPT_RENDERING_PREFER_OIT option to TRUE.

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 in XML Export 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.

A runtime check for the presence of X libraries is performed to accommodate system with and without available X servers. This check looks on the system-specific library path variable for the X libraries. If the X libraries are not found, this product does not perform vector graphics conversion.

Be sure to set the $DISPLAY environment variable before running this product when non-raster/vector graphic conversion is needed. This is especially 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 tells the system to use the X Windows server on the console.

6.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, Outside In attempts 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 uses it to convert the object. When a metafile snapshot is not available on UNIX platforms, the technology is unable to convert the OLE2 object.

6.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 Outside In is set up to display 256 colors, images produced on that system would be limited to 256 colors.

  • For all vector image formats that HX converts, we require that the X11 display support either 1 bit, 4 bits, 8 bits, 24 bits, or 32 bits.

  • If SCCOPT_RENDERING_PREFER_OIT = TRUE on UNIX then we're using internal rendering of vector formats, and we don't use the X11 display.

  • Raster image formats when converted do not need the X11 display, so are not sensitive to the bit depth of the display.

Note:

SCCOPT_RENDERING_PREFER_OIT is only supported on Linux x86-32 and Solaris Sparc-32 platforms.

6.5.4 Signal Handling

These products trap and handle 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

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

6.6 Environment Variables

Several environment variables may be used at run time. Following is a short summary of those variables and their usage.

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

$GDFONTPATH

This variable must be set. It includes one or more paths to fonts for use with Outside In's internal graphics rendering code.

$HOME

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

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

  • 61 = Liberation Sans

  • Andale Mono = Liberation Sans

  • Courier = Liberation Sans

  • Courier New = Liberation Sans

  • Lucida Console = Liberation Sans

  • MS Gothic = Liberation Sans

  • MS Mincho = Liberation Sans

  • OCR A Extended = Liberation Sans

  • OCR B = Liberation Sans

  • Agency FB = Liberation Sans

  • Arial = Liberation Sans

  • Arial Black = Liberation Sans

  • Arial Narrow = Liberation Sans

  • Arial Rounded MT = Liberation Sans

  • Arial Unicode MS = Liberation Sans

  • Berline Sans FB = Liberation Sans

  • Calibri = Liberation Sans

  • Frank Gothic Demi = Liberation Sans

  • Frank Gothic Medium Cond = Liberation Sans

  • Franklin Gothic Book = Liberation Sans

  • Futura = Liberation Sans

  • Geneva = Liberation Sans

  • Gill Sans = Liberation Sans

  • Gill Sans MT = Liberation Sans

  • Lucida Sans Regular = Liberation Sans

  • Lucida Sans Unicode = Liberation Sans

  • Modern No. 20 = Liberation Sans

  • Tahoma = Liberation Sans

  • Trebuchet MS = Liberation Sans

  • Tw Cen MT = Liberation Sans

  • Verdana = Liberation Sans

  • Albany = Liberation Sans

  • Franklin Gothic = Liberation Sans

  • Franklin Demi = Liberation Sans

  • Franklin Demi Cond = Liberation Sans

  • Franklin Gothic Heavy = Liberation Sans

  • Algerian = Liberation Serif

  • Baskerville = Liberation Serif

  • Bell MT = Liberation Serif

  • Bodoni MT = Liberation Serif

  • Bodoni MT Black = Liberation Serif

  • Book Antiqua = Liberation Serif

  • Bookman Old Style = Liberation Serif

  • Calisto MT = Liberation Serif

  • Cambria = Liberation Serif

  • Centaur = Liberation Serif

  • Century = Liberation Serif

  • Century Gothic = Liberation Serif

  • Century Schoolbook = Liberation Serif

  • Elephant = Liberation Serif

  • Footlight MT Light = Liberation Serif

  • Garamond = Liberation Serif

  • Georgia = Liberation Serif

  • Goudy Old Style = Liberation Serif

  • Lucida Bright = Liberation Serif

  • MS Serif = Liberation Serif

  • New York = Liberation Serif

  • Palatino = Liberation Serif

  • Perpetua = Liberation Serif

  • Times = Liberation Serif

  • times = Liberation Serif

  • Times New Roman = Liberation Serif

6.8 Changing Resources

All of the strings used in the UNIX versions of Outside In products are contained in the lodlgstr.h file. 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.

In addition to lodlgstr.h, the scclo.o object file is provided. This 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 Outside In. It may be necessary to make minor modifications to the makefile so the system header files and libraries can be found for compiling and linking.

Standard INCLUDE and LIB make variables are defined for each platform in the makefile. Edit these variables to point to the header files and libraries on your particular system. Other make variables are:

  • TECHINCLUDE: May need to be edited to point to the location of the Outside In /common header files supplied with the SDK.

  • BUILDDIR: May need to be edited to point to the location of the makefile, lodlgstr.h, and scclo.o (which should all be in the same directory).

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

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

6.9 HP-UX Compiling and Linking

The libsc_ex.sl and libsc_da.sl libraries are the only ones that must be linked with your application. They can be loaded when your application starts by linking them directly at compile time or they can be loaded dynamically by your application using library load functions (for example, shl_load).

To use HTML Export's annotation functions, you also must link to libsc_ca.sl, requiring a separate license to Outside In Content Access or Search Export. Contact your Outside In sales representative for more information.

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 product libraries are used.

The following are example command lines used to compile the sample application exsimple from the /sdk/samplecode directory. The command lines are separated into sections for HP-UX and HP-UX on Itanium. 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.

When using HTML Export, the libex_gdsf filter must link with libsc_img at compile time. This forces the filter to be dependent on libsc_img at runtime, even though that module may not be used directly. If you are looking to reduce your application's physical footprint, you can experiment with unlinking libsc_img.

6.9.1 HP-UX on RISC 

cc -w -o ../exsimple/unix/exsimple ../exsimple/unix/exsimple.c +DAportable -Ae -I/usr/include -I../../common -L../../demo -L/usr/lib -lsc_ex -lsc_da -Wl,+s,+b,'$ORIGIN'

6.9.2 HP-UX on RISC (64 bit) 

cc -w -o ../exsimple/unix/exsimple ../exsimple/unix/exsimple.c +DD64 -I/usr/include -I../../common -L../../demo -L/usr/lib/pa20_64 -DUNIX_64 -lsc_ex -lsc_da -Wl,+s,+b,'$ORIGIN'

6.9.3 HP-UX on Itanium (64 bit) 

cc -w -o ../exsimple/unix/exsimple ../exsimple/unix/exsimple.c +DD64 -I../../common -L../../demo -lsc_ex -lsc_da -DUNIX_64 -Wl,+s,+b,'$ORIGIN'

6.10 IBM AIX Compiling and Linking

All libraries should be installed into a single directory and the directory must be included in the system's shared library path ($LIBPATH). $LIBPATH must be set and must point to the directory containing the Outside In technology.

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

To use the HTML Export annotation function, you must also link to libsc_ca.sl, requiring a separate license to Outside In Content Access or Search Export. Contact your Outside In sales representative for more information.

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 product libraries are used.

The following is an example command line used to compile the sample application exsimple from the /sdk/samplecode directory. 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 -Llibrary 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.

When using HTML Export, the libex_gdsf filter must be linked with libsc_img at compile time. This forces the filter to be dependent on libsc_img at runtime, even though that module may not be used directly. If you are looking to reduce your application's physical footprint, you can experiment with unlinking libsc_img.

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

6.10.1 IBM AIX (32-bit pSeries) 

gcc -w -o ../exsimple/unix/exsimple ../exsimple/unix/exsimple.c -I../../common -L../../demo -lsc_ex -lsc_da -DFUNCPROTO -Wl,-brtl

6.10.2 IBM AIX PPC (64-bit) 

gcc -w -o ../exsimple/unix/exsimple ../exsimple/unix/exsimple.c -maix64 -I../../common -L../../demo -lsc_ex -lsc_da -DUNIX_64 -DFUNCPROTO -Wl,-brtl

6.11 Linux Compiling and Linking

This section discusses issues involving Linux compiling and linking.

6.11.1 Library Compatibility

This section discusses Linux library compatibility issues.

6.11.1.1 Motif Libraries

Problems can be seen when using Export products and trying to convert graphics files. For example, zero-byte graphics files are generated if the technology cannot find the proper Motif library. You can check to see if this is the case by running the following command:

ldd libos_xwin.so

This prints a list of the dependencies that this library has. If the line for the Motif library is similar to the following then your system may not have a compatible Motif library:

libXm.so.3 => not found

The solution is to install a compatible Motif library and use it to build your application. Often, the installation discs for your particular Linux platform 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.

If you are doing development, you must use the proper header files, as well.

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

  • x86 Linux - OpenMotif v. 2.2.3

  • zSeries Linux - OpenMotif v. 2.2.3

  • Itanium Linux - OpenMotif v. 2.1.30

When using HTML Export, the libex_gdsf filter must be linked with libsc_img at compile time. This forces the filter to be dependent on libsc_img at runtime, even though that module may not be used directly. If you want to reduce your application's physical footprint, you can experiment with unlinking libsc_img.

6.11.1.2 GLIBC and Compiler Versions

The following table indicates the compiler version used and the minimum required version of the GNU standard C library needed for Outside In operation.

Distribution Compiler Version GLIBC Version

x86 Linux

3.3.2

libc.so.6 (2.3.2 or newer)

Itanium Linux

3.3.2

libc.so.6 (2.3.2 or newer)

zSeries Linux

3.3.6

libc.so.6 (2.3.2 or newer)
6.11.1.3 Other Libraries

In addition to libc.so.6, 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)

  • libXt.so.6

  • libstdc++.so.6

  • libgcc_so.1

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

6.11.2 Compiling and Linking

The libsc_ex.so and libsc_da.so are the only libraries that must be linked with your applications. They can be loaded when your application starts by linking them directly at compile time or they can be loaded dynamically by your application using library load functions (for example, dlopen).

To use HTML Export annotation functions, you must also link to libsc_ca.so, requiring a separate license to Outside In Content Access or Search Export. Contact your Outside In sales representative for more information.

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 product libraries are used.

The following are example command lines used to compile the sample application exsimple from the /sdk/samplecode directory. 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 the compiler and linker can locate all required files.

The -L/usr/X11R6/lib option is also available.

6.11.2.1 Linux 32-bit, including Linux PPC 
gcc -w -o ../exsimple/unix/exsimple ../exsimple/unix/exsimple.c -I/usr/local/include -I../../common -L../../demo -L/usr/local/lib -lsc_ex -lsc_da -Wl,-rpath,../../demo -Wl,-rpath,'${ORIGIN}'
6.11.2.2 Linux 64-bit 
gcc -w -o ../exsimple/unix/exsimple ../exsimple/unix/exsimple.c -I/usr/local/include -I../../common -L../../demo -L/usr/local/lib -lsc_ex -lsc_da -DUNIX_64 -Wl,-rpath,../../demo -Wl,-rpath,'${ORIGIN}'
6.11.2.3 Linux zSeries 
gcc -w -o ../exsimple/unix/exsimple ../exsimple/unix/exsimple.c -I/usr/local/include -I../../common -L../../demo -L/usr/local/lib -lsc_ex -lsc_da -Wl,-rpath,../../demo -Wl,-rpath,'${ORIGIN}'

6.12 Oracle Solaris Compiling and Linking

Note:

These products do not support the "Solaris BSD" mode.

All libraries should be installed into a single directory. The libsc_ex.so, and libsc_da.so libraries must be linked with your application. It can be loaded when your application starts by linking them directly at compile time or they can be loaded dynamically by your application using library load functions (for example, dlopen).

To use HTML Export annotation functions, you must link to libsc_ca.sl, requiring a separate license to Outside In Content Access or Search Export. Contact your Outside In sales representative for more information.

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 product libraries are used.

The following is an example command line used to compile the sample application exsimple from the /sdk/samplecode directory. 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.

When using HTML Export, the libex_gdsf filter must be linked with libsc_img at compile time. This forces the filter to be dependent on libsc_img at runtime, even though that module may not be used directly. If you want to reduce your application's physical footprint, you can experiment with unlinking libsc_img.

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

6.12.1 Oracle Solaris SPARC 

cc -w -o ../exsimple/unix/exsimple ../exsimple/unix/exsimple.c -I/usr/include -I/usr/dt/share/include -I../../common -L../../demo -L/usr/lib -L/lib -lsc_ex -lsc_da -Wl,-R,../../demo -Wl,-R,'${ORIGIN}'

Note: When running the 32-bit SPARC binaries on Solaris 8 or 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 8 - Patch 111721-04

  • For Solaris 9 - Patch 111722-04

6.12.2 Oracle Solaris (SPARC) 64 

cc -w -o ../exsimple/unix/exsimple ../exsimple/unix/exsimple.c -xtarget=generic64 -I/usr/include -I/usr/dt/share/include -I../../common -L../../demo -L/usr/lib -L/lib -lsc_ex -lsc_da -DUNIX_64 -Wl,-R,../../demo -Wl,-R,'${ORIGIN}'

6.12.3 Oracle Solaris x86

Note:

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

cc -w -o ../exsimple/unix/exsimple ../exsimple/unix/exsimple.c -I/usr/include -I/usr/dt/share/include -I../../common -L../../demo -L/usr/lib -L/lib -lsc_ex -lsc_da -Wl,-R,../../demo -Wl,-R,'${ORIGIN}'

6.12.4 Oracle Solaris x64 

cc -w -o ../exsimple/unix/exsimple ../exsimple/unix/exsimple.c -xtarget=native64 -I/usr/include -I/usr/dt/share/include -I../../common -L../../demo -L/usr/lib -L/lib -lsc_ex -lsc_da -DUNIX_64 -Wl,-R,../../demo -Wl,-R,'${ORIGIN}'

6.12.5 Oracle Solaris X Server Display Memory Issue

On some Solaris systems, the X Server does not free the memory for a display until the last close display call is made on that display. This problem is limited strictly to the Oracle Solaris OS and does not affect any other platforms, UNIX or otherwise. It also does not affect HTML Export when graphics conversions are turned off.

This problem is most noticeable when doing large amounts of graphics processing, when system memory usage can grow without bound. This memory can only be freed by shutting down the X Windows display the user pointed the technology to use via the DISPLAY environment variable. If that display is the "console" display, the user must log out of the console in order to free the memory. Users may be able to avoid this problem by choosing a display that they can close periodically.

6.13 z/OS Compiling and Linking

The libsc_ex.x and libsc_da.x libraries must be linked with your application. They can be loaded when your application starts by linking them directly at compile time or they can be loaded dynamically by your application using library load functions (for example, dlopen).

To use HTML Export's annotation functions, link to libsc_ca.x, which requires a separate license to Outside In Content Access or Search Export. Contact your Outside In sales representative for more information.

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 product libraries are used.

All libraries should be installed into a single directory and the directory must be included in the system's shared library path ($LIBPATH). $LIBPATH must be set and must point to the directory containing the Outside In technology.

The following is an example command line used to compile the sample application exsimple from the /sdk/samplecode directory. 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 the compiler and linker can locate all required files. 

c89 -o ../exsimple/unix/exsimple -I/usr/include/X11 -I/usr/local/include -I../../common -W 'c,ASCII,LANGLVL(ANSI,LONGLONG)' -D_ZOS_SOURCE -D_XOPEN_SOURCE=500 -Wl,DLL,XPLINK -L../../demo -L/usr/local/lib -L/usr/local/lib/oivt ../../demo/libsc_fa.x ../../demo/libsc_ex.x ../../demo/libsc_da.x ../exsimple/unix/exsimple.c