| Oracle® Outside In Content Access Developer's Guide Release 8.4.1 Part Number E12846-05 |
|
|
View PDF |
| Oracle® Outside In Content Access Developer's Guide Release 8.4.1 Part Number E12846-05 |
|
|
View PDF |
The UNIX implementation of Content Access is delivered as a set of shared libraries. 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:
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. For more information, see Section 3.7, "Changing Resources." |
|
/sdk/samplecode |
Contains a subdirectory holding the source code for a sample application. For more information, see Chapter 10, "Sample Applications." |
|
/sdk/samplefiles |
Contains sample files designed to exercise the technology. |
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.
On the UNIX platforms, 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).
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) |
| File | Description |
|---|---|
|
libsc_ch.* |
Chunker (provides caching of and access to filter data for the display engine) |
|
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 Abstraction layer |
| File | Description |
|---|---|
|
libvs_*.* |
Filters for specific file types (there are more than 150 of these filters, covering more than 600 file formats) |
| 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. |
All the steps outlined in this section are used in the sample applications provided with the SDK. Looking at the code for the casample sample application (see Chapter 10, "Sample Applications") is recommended for a real world example of this process.
Any source code that uses this product should #include the file sccca.h (for Content Access) and/or sccta.h (for Text Access) and #define UNIX. For example, a 32-bit UNIX application might have a source file with the following lines:
#define UNIX #include <sccca.h> /* If using ContentAccess */ #include <sccta.h> /* If using Text Access */
and a 64-bit UNIX application might have a source file with the following lines:
#define UNIX #define UNIX_64 #include <sccta.h>
Three sets of information are created by the technology: the default options, a list of available filters and a list of available display engines. In the UNIX implementations, these lists are built as needed, usually the first time the product 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 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:
*.f: Filter lists
*.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 Technology and/or other Viewer Technology-based products are installed on a single system. The file names 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.
This section provides information about character sets.
To optimize performance on systems that do not require DBCS support, a second character mapping bin file not containing any of the DBCS pages is now included. The second bin file gives 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.
This section provides information about runtime considerations.
This product traps and handles the following signals:
SIGABRT
SIGBUS
SIGFPE
SIGILL
SIGINT
SIGSEGV
SIGTERM
To override the default handling of these signals you can set your own signal handlers. This can be 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:
|
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.
There are a number of environment variables the UNIX implementation of the technology may use at run time. While described elsewhere, following is a short summary of those variables and their usage.
| Variable | Description |
|---|---|
|
Must be set to include the directory containing the .flt files. Only applicable to AIX. |
|
|
$LD_LIBRARY_PATH (FreeBSD, HP-UX Itanium 64, Linux, Solaris) |
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. |
|
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." |
All of the strings used in the UNIX versions of 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 that 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 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. 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 that are 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 make variables are set, 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 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.
In the following example, libsc_ca.sl and libsc_da.sl are the only libraries that need to be linked with the casample. Not all applications that use the Content Access module will require the use of these libraries. They can be loaded when the 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).
The following are example command lines used to compile the sample application casample from the /sdk/samplecode/unix directory. The command lines are separated into sections for HP/UX and HP/UX on Itanium (which requires GCC). 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.
cc -w -o ../casample/unix/casample ../casample/unix/casample.c +DAportable -Ae -I/usr/include -I../../common -L../../demo -L/usr/lib -lm -lsc_ca -lsc_da -DUNIX -Wl,+s,+b,'$ORIGIN'
cc -w -o ../casample/unix/casample ../casample/unix/casample.c +DD64 -I../../common -L../../demo -L/usr/lib/hpux64 -lsc_da -lsc_ca -DUNIX -DUNIX_64 -Wl,+s,+b,'$ORIGIN'
All libraries should be installed into a single directory and the directory must be included in the system's shared library path ($LIBPATH) as well as the executable path ($PATH).
Note:
$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 probably due to not using the large data model.
The following is an example command line used to compile the sample application casample from the /sdk/samplecode/unix 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. Developers need to pass -brtl to the linker to list libraries in the link command as dependencies of their applications.
Note:
Developers may need to use the -qcpluscmt flag to allow C++ style comments.
gcc -w -o ../casample/unix/casample ../casample/unix/casample.c -I../../common -L../../demo -lsc_ca -lsc_da -DUNIX -DFUNCPROTO -Wl,-brtl
This section provides information about Linux compiling and linking.
This section provides information about library compatibility.
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 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.
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 Outside In binaries:
x86 Linux: OpenMotif v. 2.2.3
zSeries Linux: OpenMotif v. 2.2.3
Itanium Linux: OpenMotif v. 2.1.30.
Note:
If a directory needs to be specified for the compiler to find the shared libraries, it is recommended that the $LD_LIBRARY_PATH environment variable be used. This will prevent the compiler from hard-coding the library's current directory into the executable as the only directory to search for the library at run time. Instead, the system will first search the directories specified by $LD_LIBRARY_PATH for the library.
For each Linux platform supported by Outside In, the following table indicates the compiler version used and the minimum required version of the GNU standard C library upon which Outside In depends.
| Distribution | Compiler Version | GLIBC Version |
|---|---|---|
|
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) |
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)
libstdc++.so.5.0.5
libgcc_so.1
libXt.so.6
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 Outside In and what needs to be added/modified to make 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 Outside In |
|
| 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 Outside In |
|
| 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 Outside In |
|
| 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 Outside In |
|
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 |
|
libXm.so.X |
libXm.so.3.0.1 |
|
Required to Use Outside In |
|
| 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 Outside In |
|
| 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 |
|
libXm.so.X |
libXm.so.3.0.1 |
|
Required to Use Outside In |
|
Libraries on Linux PPC Systems
| SuSE Linux Enterprise Server 10 PPC | Support Information |
|---|---|
|
libc.so.6 version |
/lib/libc.so.6 (GLIBC 2.3.4 or higher) |
|
libstdc++ |
/usr/lib/libstdc++.so.6.0.8 |
|
libgcc_s.so.1 |
/lib/libgcc_s.so.1 |
|
libXm.so.X |
libXm.so.3 |
|
Required to Use Outside In |
|
In the following example, the libsc_ca.so and libsc_da.so are the only libraries needing to be linked with the casample. Not all applications that use the Content Access module will require the use of all of these libraries. They can be loaded when the 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).
The following is an example command line used to compile the sample application casample 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 the compiler and linker can locate all required files.
Linux 32-bit (includes Linux PPC)
gcc -w -o ../casample/unix/casample ../casample/unix/casample.c -I/usr/local/include -I../../common -L../../demo -L/usr/local/lib -lsc_da -lsc_ca -DUNIX -Wl,-rpath,../../demo -Wl,-rpath,'${ORIGIN}'
gcc -w -o ../casample/unix/casample ../casample/unix/casample.c -I/usr/local/include -I../../common -L../../demo -L/usr/local/lib -lsc_da -lsc_ca -DUNIX -DUNIX_64 -Wl,-rpath,../../demo -Wl,-rpath,'${ORIGIN}'
gcc -w -o ../casample/unix/casample ../casample/unix/casample.c -I/usr/local/include -I../../common -L../../demo -L/usr/local/lib -lsc_da -lsc_ca -DUNIX -Wl,-rpath,../../demo -Wl,-rpath,'${ORIGIN}'
All libraries should be installed into a single directory.
Note:
This product does not support the old Solaris BSD mode.
In the following example, the libsc_ca.so and libsc_da.so are the only libraries that need to be linked with the casample. Not all applications that use the Content Access module will require the use of all of these libraries. They can be loaded when the 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).
The following is an example command line used to compile the sample application casample 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.
Note:
Developers may need to use the -xcc flag to allow C++ style comments.
cc -I/usr/include -I/usr/dt/share/include -I../../common -w -o ../casample/unix/casample ../casample/unix/casample.c -L../../demo -L/usr/lib -L/lib -lc -ldl -lsc_ca -lsc_da -DUNIX -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 the following patch (or its successor) to your system to correct.
For Solaris 9 - Patch 111722-04
Note:
Your system will require Solaris patch 108436, which contains the C++ library libCstd.so.1.
cc -I/usr/include -I/usr/dt/share/include -I../../common -w -o ../casample/unix/casample ../casample/unix/casample.c -L../../demo -L/usr/lib -lsc_ca -lsc_da -DUNIX -R '$ORIGIN'+ -DUNIX
The following is an example command line used to compile the sample application casample 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 the compiler and linker can locate all required files.
gcc -w -o ../casample/unix/casample ../casample/unix/casample.c -I/usr/local/include -I../../common -L../../demo -L/usr/local/lib -lsc_da -lsc_ca -DUNIX -Wl,-rpath,../../demo
|
 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|