Each of the sample applications included in this SDK is 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:
11.1 Building the Samples on a Windows System
Microsoft Visual Studio project files are provided for building each of the sample applications. For 32-bit versions of Windows, versions of the project files are provided for Visual Studio 6 (.dsp files) and Visual Studio 2005 (.vcproj files).
Because .vcproj files may not pick up the right compiler on their own, you need to make sure that you are building with the Win64 configuration in Visual Studio 2005. For 64-bit versions of Windows, only the Visual Studio 2005 versions are available.
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.
11.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.
batch_process_ca demonstrates running HTML Export in a separate process on multiple input files. It also allows the timing of each run.
The application is executed from the command line and takes several possible parameters:
batch_process_hx -f inputfile -o outputfile or [-d inputdir -o outputdir] [-i iterations] [-q] [-b]
-f specifies the name of a single input file.
-d specifies the name of an input directory of files.
-o specifies the name of an output file if -f is being used, or the name of an output directory if -d is being used.
-i is an optional parameter specifying the number of iterations to perform.
-q and -q2 diminish the output to the screen.
-b increases the amount of content in the output including processing tags and sub-documents.
The following is a basic implementation that uses the default settings for every option.
You can use the option template parameter and specify a template to override the default option settings.
This sample is provided for instructional value rather than functionality. As an exercise, you may want to try changing the SCCOPT_GRAPHIC_TYPE option so it outputs a different graphic type.
11.2.3 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 choose the source file, an output file and set the various options.
220.127.116.11 The export Main Window
The following figure shows the Main Window for the export application.
Figure 11-1 export Main Window for HTML 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 drop-down 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 click the Browse button to choose 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: 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 choose the source file, an output file and set the various options.
This macro is not supported for templates used to create MHTML output.
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 following configuration options before running the software:
outputid: This is the output ID (corresponding to the dwOutputId parameter of the EXOpenExport function). It is required and must not be commented out.
template: This corresponds to the SCCOPT_EX_TEMPLATE option, and indicates the template file to be used. If this option is not set, HTML Export uses the internal standard template.
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 more information, 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 HTML 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:
The following sample command line demonstrates this command:
hxanno InputFile OutputFile HiliteString
A license for Content Access or Search Export is required to enable use of any of the annotation features supported by HTML Export. Contact your Outside In sales representative for more information.
11.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.
11.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.
11.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.
11.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.
11.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)
hx.cfg (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 if you so choose not to.
11.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 system, 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 HTML as the export type. Change this type accordingly:
ExportTest.bat myworddoc.doc output.html hx.cfg