This chapter describes the sample applications included in this SDK. They are each designed to highlight a specific aspect of the technology's functionality. We ship built versions of these sample applications. The compiled executables should be in the root directory where the product is installed.
This chapter includes the following sections:
3.1 Building the Samples on a Windows System
Microsoft Visual Studio 2010 files are provided for building each of the sample applications.
Because .vcxproj files may not pick up the right compiler on their own, you need to make sure that you are building with the correct configuration in Visual Studio 2010 or higher.
The project files for the sample applications can be found in the samplecode\win subdirectory of the Outside In SDK.
For specific information about building the sample applications on your UNIX OS, see UNIX Implementation Details.
3.2 An Overview of the Sample Applications
Here's a quick tour of the sample applications provided with this product. Not all of the sample applications are provided for both the Windows and UNIX platforms. See the heading of each application's subsection for clarification.
This section describes the following sample applications.
The name of this sample application varies according to product (ixsample for Image Export).
The following is a basic implementation that uses the default settings for every option.
ixsample Inputfile Outputfile
This sample is provided for instructional value rather than functionality. The output format is always TIF. As an exercise, you may want to try changing the EXOpenExport() call in the application so that it outputs a different graphic type.
3.2.2 export (Windows Only)
This application was designed to facilitate the testing of the software and should not be assumed to be of commercial quality.
No default options are set at initial runtime. The time the software is used, click the Options button and set the options. Failure to do this generates export errors.
The application allows the user to run a single source file. The user can select the source file, an output file and set the various options.
126.96.36.199 The export Main Window
The following figure shows the Main Window for the export application.
Figure 3-1 export Main Window for Image Export
The Main Window is composed of several elements, discussed here.
Output Format menu: This menu allows the user to select the type of output to generate. An entry for the format(s) you license will appear in this menu.
Options button: This opens up a new dialog with one or more tabs exposing the options for the selected product.
Source document field: This is the document to be exported. Click the Browse button to pick the source file, or type in the path name.
'Export to' field: This is the initial resulting output file. Type in a file name or use the Browse button to select a file. Other output files are named based on the one chosen here.
Delete button: Clicking this button deletes all files generated by the last export, listed in the Status: field. This is useful when multiple output files are produced because the default naming rules do not overwrite an existing file. If you run Export over and over again with the same output file name, you can produce a large number of files. Clicking Delete before each export solves this problem.
'After Export, view output file with default application' checkbox: If the export was successful, checking this box launches the initial output file in the application associated with the output flavor's default extension.
Export button: Click this button to start the export process once you've determined the export settings.
Exit button: Click to close the Export application.
This simple command line driven program allows the user to run a single source file through the software. The user can select the source file and output file and set the various options.
To run the program, type:
exsimple in_file out_file config_file
in_file is the input file to be converted
out_file is the output location
config_file is the configuration file that sets the conversion options. If no configuration file is specified, default.cfg in the current directory is used.
The configuration file is a text file used to set the conversion options. We recommend reading through the configuration file for more information about valid options and their values (use of invalid options results in exsimple not producing output).
Follow these instructions to set configurable options.
Set the Output ID before running the software. It is required and must not be omitted. It is also recommended that you set SCCOPT_FALLBACKFORMAT to FI_NONE. This prevents the export of unidentified binary files as though they were text, which could generate pages of garbage output.
This sample application is based on the exsimple sample application. It is designed to demonstrate how to use redirected IO and callbacks when using the software. It takes the same arguments and command line structure as exsimple and the same configuration files can be used. For details, see exsimple.
extract_archive demonstrates using the DATree API to extract all nodes in an archive.
The application is executed from the command line and takes two parameters, the name of the input file and the name of an output directory for the extracted files:
extract_archive input_file output_directory
This sample application is provided more for the instructional value its sample code offers than for the functionality it provides when executed. It primarily works as an example of how to integrate Content Access with Image Export. This particular application does search hit highlighting. However, the general principles of how to get ACC text positions from Content Access should be evident from perusing the source code.
This command takes the following parameters:
When using Image Export, the output type is always TIF.
The following sample command line demonstrates this command:
ixanno InputFile OutputFile HiliteString
A license for Content Access or Search Export is required to enable use of any of the annotation features supported by Image Export. Contact your Outside In sales representative for more information.
3.3 Accessing the SDK via a Java Wrapper
The ExJava Java wrapper, working in tandem with the exporter sample application, provides a working example of one method of interfacing with Oracle's C-based SDK products from a Java application. Export.jar is a Java API wrapper used by a Java application to control the exporter executable and set conversion options. exporter is a C-based executable which performs conversions using the modules in the Outside In SDK.
The exporter executable should be placed in the root directory of the Outside In SDK being used. If more than one Outside In SDK is being used, the contents of each SDK should be unpacked to the same root directory. Export.jar should be placed somewhere in your classpath.
On UNIX systems this sample application must be run from the directory containing the Outside In technology.Java version 1.6 or higher is required to run this sample application.
3.3.1 The ExJava Wrapper API
The JavaDocs documentation for the Java API is provided in the /sdk//samplecode/ExJava/docs directory. Conversion options are set using the ExportProperties.
Additionally, the appropriate .cfg file for the ExportTest sample application found in the Examples/ExportTest directory may provide further insight as to what properties are available and how they correspond to options and values for options.
The Export.jar and its source code can be found in the Java API directory. Place Export.jar somewhere in your classpath. In order to use the ExportTest sample application (which demonstrates how a Java application can use the ExJava API) without modifying your system configuration or the ExJava sample application, you should place the Export.jar file in the root directory of the Outside In SDK product you are using.
3.3.2 The C-Based Exporter Application
This is a standalone executable that runs out of process from the Java API. The Java API controls the conversion through command line parameters that are passed to the executable. After the conversion completes, the executable returns a conversion status code to the Java API. The command line parameters are base-64 encoded to allow for the use of Unicode encoded paths.
As the exporter executable is a C-based application, you will need to make sure the Java API can find the version of exporter appropriate for the platform you are using. Generally, and specifically for the purpose of using the ExportTest sample application, the correct executable should be copied to the root directory of the Oracle export SDK product you are using.
A compiled version of the C exporter program is included in the SDK with the rest of the Outside In binaries. The source for exporter is located in the /sdk/samplecode/ExJava/exporter directory.
The current implementation of ExJava may not produce an error if it cannot find the exporter application. This known issue may be corrected in a future version of ExJava.
3.3.3 Compiling the Executables
A Microsoft Visual Studio 6.0 project file and a UNIX makefile are provided in Exporter/Win and Exporter/Unix, respectively, so that you can modify the Exporter executable or compile it for a platform other than those for which compiled versions of exporter are provided. If you unpacked the ExJava package into the root directory of one of Oracle's export SDK products, you should be able to use the Visual Studio Project and makefile as is. Otherwise, you will need to edit them in order to provide paths to the Oracle export SDK include and library files.
If you are compiling ExJava for use on the Solaris platform, make sure your LD_LIBRARY_PATH contains the Outside In SDK path before trying to build the Exporter module.
3.3.4 The ExportTest Sample Application
ExportTest is an example of how a Java developer could use the ExJava wrapper to use one of the Outside In SDKs. The following is a list of the components that should be placed in the root directory of the Outside In SDK you are using in order to run this sample application:
Export.jar (from the Java API directory)
Exporter module for the platform you wish to use (located in the /sdk/samplecode/ExJava/Exporter/Win or /sdk/samplecode/ExJava/Exporter/Unix directory, depending on which platform you are using)
ix.cfg file (also in Examples/ExportTest directory)
If you are running ExportTest on a UNIX system, make sure to edit the .cfg file so it reflects the correct name of the exporter module you renamed.
ExportTest.jar (also in Examples/ExportTest directory)
The appropriate batch file to run the ExportTest application (ExportTest.bat for Windows and ExportTest.sh for UNIX, both located in the Examples/ExportTest directory)
Once these files are properly copied, execute the batch file with the name/path of an input file to convert, the name for the base output file and the name of the configuration file to use for setting conversion options.
ExportTest.jar uses the contents of the configuration file to determine what option/value pairs it should use when doing the conversion. It is not necessary to use a configuration file when developing your own application.
3.3.5 An Example Conversion Using the ExJava Wrapper
This is a simple outline of the steps for using the ExJava wrapper on a Windows system to convert a Word document called MyWordDoc.Doc. For information about properly setting up your environment to use the Outside In SDK in a UNIX environment, see: UNIX Implementation Details.
Edit the .cfg file and make sure outputid is set to the FI* value appropriate for the Outside In product you've licensed. Alter any other parameters in the .cfg file as needed then save the file.
Execute the following command. The sample command below assumes BMP as the export type. Change this type accordingly:
ExportTest.bat myworddoc.doc output.bmp ix.cfg