This chapter includes the following sections:
To install Transformation Server, download the archive from the Oracle site (http://edelivery.oracle.com/
). Place the download into a directory that contains a previously downloaded Outside In installation on your local drive to complete installation.
Note:
At least one of the Outside In Export products needs to be installed before Transformation Server is downloaded.
Note:
Transformation Server, its configuration files, and the Outside In Export technologies are designed to reside in the same directory. Placing them elsewhere may result in errors.
You will need to set the TSROOT variable to the location of the Transformation Server installed SDK. For example, for a Linux version of Transformation Server, you would set TSROOT=/user/jsmith/ts/ts_linux-x86-32_sdk/sdk.
If you load more than one OIT SDK, you must copy files from the secondary installations into the top-level OIT SDK directory as follows:
redist – copy all binaries into this directory.
sdk – this directory has several subdirectories: common, demo, lib, resource, samplecode, samplefiles. In each case, copy all of the files from the secondary installation into the top-level OIT SDK subdirectory of the same name. If the top-level OIT SDK directory lacks any directories found in the directory being copied from, just copy those directories over.
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.1, needed by ../../libsc_vw.so, may conflict with libXm.so.3
Problems can also be seen when trying to convert graphics files. For example, zero byte graphics files will be generated if our 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 will print a list of the dependencies that this library has. If the line for the Motif library looks like the following:
libXm.so.1 => not found
then your system may not have a compatible Motif library installed.
The proper solution to both of these problems 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://www.lesstif.org/download.html
. Remember that if you are doing development, you will also need the proper header files, as well.
The Motif library versions used by Oracle when building and testing the Outside In binaries are:
x86 Linux: OpenMotif v. 2.2.3
This product requires the Visual C++ libraries included in the Visual C++ Redistributable Package available from Microsoft. There is a version of this package for the appropriate platform (x86 or x64) version of Windows. This can be downloaded from www.microsoft.com, by searching on the site for the vcredist_x86.exe package.
The required download version is the "Visual C++ Redistributable Packages for Visual Studio 2013."
Oracle Outside In requires the msvcr120.dll redistributable module.
To deploy Visual C++ libraries using the Visual C++ Redistributable Package, perform the following steps:
Transformation Server does not require the setting of the environment variable LD_LIBRARY_PATH in order to run. However, it does require the setting of the PATH environment variable. Transformation Server's process manager (tsmanager) launches child processes, and in order to be able to locate those processes it needs the PATH environment variable to include the path to the directory where Transformation Server is installed.
Additional environment variables for UNIX may need to be set depending upon the Outside In export technology you are invoking via Transformation Server. Please consult the manual for the export technology you are using as to whether it needs additional environment variables to be set for your specific UNIX platform.
Here is an overview of the files contained in the main installation directory for this product:
File | Description |
---|---|
ACE-5.8.1 |
Third party ACE library that provides process control and thread synchronization |
sccts |
C API library for Transformation Server Clients |
ts_buffered_io |
Transformation Server buffered IO library |
ts_components |
Transformation Server support library |
ts_engine_options |
Transformation Server generic options handling library |
ts_file_io_module |
Transformation Server file IO library |
ts_hx_engine |
HTML Export engine for use by tsagent |
ts_ix_engine |
Image Export engine for use by tsagent |
ts_logging_facility |
Transformation Server logging support library |
ts_msg_logger_app |
Transformation Server logging process |
ts_pdf_engine |
PDF Export engine for use by tsagent |
ts_riot_iop_module |
Transformation Server Client side, redirected IO library |
ts_riotstub |
C API support library for Transformation Server Clients |
ts_soap_ext |
Transformation Server SOAP support library |
ts_soap_std |
Transformation Server SOAP support library |
ts_soap_ta_client |
Transformation Server SOAP support library |
ts_soap_ts_client |
Transformation Server SOAP support library |
ts_soap_ts_server |
Transformation Server SOAP support library |
ts_soap_tss |
Transformation Server SOAP support library |
ts_sx_engine |
SearchML Export engine for use by tsagent |
ts_url_iop_module |
Transformation Server HTTP IO library |
ts_utils |
Transformation Server support library |
ts_xx_engine |
XML Export engine for use by tsagent |
tsagent |
Transformation Server agent process |
tsmanager |
Transformation Server manager process |
tsapi.jar |
Java API library for Transformation Sever Clients |
tools.jar |
Java classes used by configserver and option_set_editor utilities |
configserver |
Java GUI application for editing the server_startup.xml file |
option_set_editor |
Java GUI application for editing the agent_option_sets.xml file |
Transformation Server's main application is tsmanager. When this program is started, it will in turn start up Transformation Agents (tsagent) and initiate communication with them. tsmanager will then listen for incoming transformation requests. Incoming requests for transformations are distributed among the running Transformation Agents, who return the results of the requests to tsmanager, which will then send those results back to the original requestor.
tsagent can be started in standalone mode apart from tsmanager as well, for applications where reduced resource usage is desirable.
This section deals with these applications and their command-line parameters.
Note:
If any of the following .xml files that tsmanager and its agents depend upon change while tsmanager is running, then it must be shut down and restarted.
server_startup.xml
agent_option_sets.xml
agent_engine_list.xml
agent_iospect_types.xml
The following is an overview of product details.
The user can alter tsmanager's parameters via the command line, the XML configuration file named server_startup.xml, or both. For parameters that can be set both ways, the command line overrides server_startup.xml. For both methods, parameter string values are case-sensitive. If server_startup.xml is malformed or missing an option, tsmanager will resort to defaults if it can avoid a bailout.
The following command line options have parameters. The command --help provides a list of these as well as their shorthands (e.g., --host = -s).
The hostname or IP address to use when listening to transformation requests. Value may be a name, such as "server.host.com" or an IP address such as "127.0.0.1;" the host address must be valid for the machine on which tsmanager is running. If no host name is specified on the command line or in the configuration file, tsmanager will listen to incoming requests on all available addresses. If no host is specified on either the command line or in server_startup.xml, tsmanager will listen for requests on all of the computer's available IP addresses. The server_startup.xml parameter is the <serverName> subelement of <ConnectionsInfo>.
The TCP port number on which tsmanager will listen for incoming requests. There is no default value; this parameter must be specified. The server_startup.xml parameter is the <port> subelement of <ConnectionsInfo>.
This parameter is only valid on UNIX systems.
This is the directory where pipes will be created. The location must be local to the machine. The default value is /tmp. The server_startup.xml parameter is the <pipeDir> subelement of <logInfo>.
The following command line flags are used.
If set, this option prints supplemental diagnostic information to the log file.
The tsmanager command line syntax is simple:
tsmanager --parameter1 value1 --parameter2 value2 ...
Both the long option and short option can be used for syntax, for example, the port command long option is "--port" and the short option is "-p". Use the --help (-h) command to show the short options. Parameters and their values are separated by one or more spaces or tabs.
The following parameters are supported:
cfgfile: The parameter cfgfile causes tsmanager to update the parameter values in server_startup.xml with the other parameter values specified on the same command line, then exit immediately without initiating any transformation operations.
host: Described in Command Line Options with Parameters.
loghostname: Logs the client host name (slower than logip).
logip: Logs the client's IP address.
numagents: Described in Command Line Options with Parameters.
pipedir: Described in Command Line Options with Parameters.
port: Described in Command Line Options with Parameters.
trace_on: Described in Command Line Flags.
version: Described in Command Line Flags
The following command line will cause tsmanager to listen for incoming transformation requests on TCP port 90 of IP address 127.0.0.1 (localhost).
tsmanager --host 127.0.0.1 --port 90
The following command line will cause tsmanager to listen for incoming transformation requests on TCP port 100 and use a pool of 3 transformation agents to handle transformation requests.
tsmanager --port 100 --numagents 3
When you launch tsmanager, it spawns a logging application called ts_msg_logger_app. This application logs server activity based on parameters specified in the server_startup.xml configuration file (the configuration file is discussed in the following section). The log can be rotated based on a maximum file size (the rotateSize parameter in the logInfo section of the server_startup.xml file) or by time of day (the rotateTime parameter in the logInfo section of the server_startup.xml file). When the log is rotated, the old log file is not deleted.
The file server_startup.xml resides in the same directory as tsmanager. If this file is not present, you must specify at least the port number on the tsmanager command line.
If the rotate_time value of the logInfo section of the configuration file is filled with a valid, non-empty time, rotate_size can be zero or empty. However, if the rotate_time value is empty and the rotate_size value is zero, ts_msg_logger_app will not start and will print out an error message to the console. Also, if both rotate_time and rotate_size have non-empty values, tsmanager will always use the rotate_time value and ignore the rotate_size value.
The path value must be set or ts_msg_logger_app will not start.
Configuration File Example
<TsServerStartup xsi:type="tss:TsServerStartup" ... other attributes deleted for clarity... > <agentsInfo xsi:type="ts:agentsInfo"> <poolSize xsi:type="xsd:unsignedInt">4</poolSize> </agentsInfo> <connectionsInfo xsi:type="tss:connectionsInfo"> <serverName xsi:type="xsd:string"></serverName> <port xsi:type="xsd:unsignedInt">60611</port> </connectionsInfo> <logInfo> <host>128.26.53.89</host> <port>90</port> <path>c:\logs</path> <rotate_time>23:00</rotate_time> <!-- HR:MN --> <rotate_size>5</rotate_size> <!-- in MB --> </logInfo> </TsServerStartup>
In addition to its typical usage, running in tandem with tsmanager, tsagent can be started in standalone mode (using the standalone flag), allowing low-overhead, single-threaded communications with the server. Here is a guide to tsagent's parameters.
The following are command line flags with parameters.
The hostname or IP address to use when listening to transformation requests. Value may be a name, such as "server.host.com" or an IP address such as "127.0.0.1;" the host address must be valid for the machine on which TSagent is running. If no host name is specified on the command line or in the configuration file, TSagent will listen to incoming requests on all available addresses. There is no default value; this parameter must be specified.
The following are other command line flags.
This flag will allow tsagent to connect to one client and when that client ends the connection, tsagent will exit.
This flag is required if you wish to run tsagent in standalone mode separately from tsmanager.
This flag allows the standalone agent to get input from stdin and write output to stdout.
There are several XML configuration files used by Transformation Server to store its configuration information. These files are located in the same directory as the Outside In binaries. A developer may add IO Providers or Transformation Engines to the Transformation Server core by modifying these files.
agent_iospec_types.xml: Contains the list of input/output providers installed on the server. Each element in the list maps an IO "specification type" (for example, path or url) to a module that contains the code that implements the IO Provider interfaces for this type.
agent_engine_list.xml: Contains the list of Transformation Engines available on the server.
agent_option_sets.xml: Contains the predefined sets of transformation options.
server_startup.xml: Contains startup parameters that affect the tsmanager application. If this file is not present, tsmanager parameters must be specified on its command line.
The following are examples from provided files.
agent_iospec_types.xml
<?xml version="1.0" encoding="UTF-8"?> <?file version="1.0"?> <IoSpecTypeToModuleMap xsi:type="tss:IoSpecTypesList" other attributes deleted for clarity...> <SpecType xsi:type="tss:SpecType"> <!-- For local file system and shared file system paths--> <Name xsi:type="xsd:string">path</Name> <Module xsi:type="xsd:string">ts_file_io_module</Module> </SpecType> <SpecType> <!-- used internally for client-side redirected IO support --> <Name xsi:type="xsd:string">riot</Name> <Module xsi:type="xsd:string">ts_riot_iop_module</Module> </SpecType> <SpecType> <!-- For files that can be read (GET) and written (PUT) via HTTP--> <Name xsi:type="xsd:string">url</Name> <Module xsi:type="xsd:string">ts_url_iop_module</Module> </SpecType> </IoSpecTypeToModuleMap>
agent_engine_list.xml
<?xml version="1.0" encoding="UTF-8"?> <?file version="1.0"?> <EngineList xsi:type="tss:EngineList" other attributes deleted for clarity...> <Engine xsi:type="tss:Engine"> <EngineName xsi:type="xsd:string">HTML Export Engine</EngineName> <EngineModule xsi:type="xsd:string">ts_hx_engine</EngineModule> <OutputFormatNames xsi:type="tss:StringList"> <Name xsi:type="xsd:string">html</Name> <Name xsi:type="xsd:string">mhtml</Name> </OutputFormatNames> </Engine> <Engine xsi:type="tss:Engine"> <EngineName xsi:type="xsd:string">Image Export Engine</EngineName> <EngineModule xsi:type="xsd:string">ts_ix_engine</EngineModule> <OutputFormatNames xsi:type="tss:StringList"> <Name xsi:type="xsd:string">bmp</Name> <Name xsi:type="xsd:string">gif</Name> <Name xsi:type="xsd:string">jpeg</Name> <Name xsi:type="xsd:string">png</Name> <Name xsi:type="xsd:string">tiff</Name> </OutputFormatNames> </Engine> <Engine xsi:type="tss:Engine"> <EngineName xsi:type="xsd:string">Search Export Engine</EngineName> <EngineModule xsi:type="xsd:string">ts_sx_engine</EngineModule> <OutputFormatNames xsi:type="tss:StringList"> <Name xsi:type="xsd:string">page-ml</Name> <Name xsi:type="xsd:string">search-ml</Name> <Name xsi:type="xsd:string">search-ml-2</Name> <Name xsi:type="xsd:string">search-ml-3</Name> <Name xsi:type="xsd:string">search-ml-3-1</Name> <Name xsi:type="xsd:string">search-ml-3-2</Name> <Name xsi:type="xsd:string">search-html</Name> <Name xsi:type="xsd:string">search-text</Name> </OutputFormatNames> </Engine> <Engine xsi:type="tss:Engine"> <EngineName xsi:type="xsd:string">XML Export Engine</EngineName> <EngineModule xsi:type="xsd:string">ts_xx_engine</EngineModule> <OutputFormatNames xsi:type="tss:StringList"> <Name xsi:type="xsd:string">flexiondoc-4</Name> <Name xsi:type="xsd:string">flexiondoc-5</Name> <Name xsi:type="xsd:string">flexiondoc_5</Name> <Name xsi:type="xsd:string">flexiondoc-5-1</Name> <Name xsi:type="xsd:string">flexiondoc-5-2</Name> </OutputFormatNames> </Engine> <Engine xsi:type="tss:Engine"> <EngineName xsi:type="xsd:string">PDF Export Engine</EngineName> <EngineModule xsi:type="xsd:string">ts_pdf_engine</EngineModule> <OutputFormatNames xsi:type="tss:StringList"> <Name xsi:type="xsd:string">pdf</Name> </OutputFormatNames> </Engine> </EngineList>
agent_option_sets.xml
<?xml version="1.0" encoding="UTF-8"?> <?file version="1.0"?> <OptionSets xsi:type="tss:OptionSetList" other attributes deleted for clarity...> <OptionSet xsi:type="tss:OptionSet"> <Name xsi:type="xsd:string">Netscape 6.2</Name> <Options xsi:type="tss:OptionList"> <Option xsi:type="ts:Option"> <name xsi:type="xsd:string">flavor</name> <value xsi:type="ts:FlavorEnum">netscape4.0</value> </Option> <Option xsi:type="ts:Option"> <name xsi:type="xsd:string">defaultFont</name> <value xsi:type="tsDefaultFont"> <fontname xsi:type="xsd:string">Times New Roman </fontname> <height xsi:type="xsd:unsignedShort">9</height> </value> </Option> </Options> </OptionSet> <OptionSet xsi:type="tss:OptionSet"> <-- ... more option sets... --> </OptionSet> </OptionSets>
server_startup.xml
<?xml version="1.0" encoding="UTF-8"?> <?file version="1.0"?> <TsServerStartup xsi:type="tss:TsServerStartup" other attributes deleted for clarity...> <agentsInfo xsi:type="ts:agentsInfo"> <poolSize xsi:type="xsd:unsignedInt">4</poolSize> </agentsInfo> <connectionsInfo xsi:type="tss:connectionsInfo"> <serverName xsi:type="xsd:string">127.0.0.1</serverName> <port xsi:type="xsd:unsignedInt">9999</port> </connectionsInfo> </TsServerStartup>
To facilitate easy creation of option sets for transformations, an Option Set Editor application is included with Transformation Server. This application is launched using a batch file called option_set_editor, located in the installation's root directory.
Transformation Server exposes several internal APIs to allow your application to extend the core functionality to better integrate with your application.
The Transformation Engine specification allows your application to integrate non-Outside In export software into the Transformation Server framework. See Transformation Engine Specification for details.
The IO Provider specification allows your application to extend the input and output functionality beyond the file system. See IO Provider Specification for details.