Skip Headers
Oracle® Outside In Transformation Server Developer's Guide
Release 8.4.0
Part Number E12868-03
Go to Documentation Home
Home		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
View PDF

4 Initiating Transformations Using the C/C++ API

To use Transformation Server in a C or C++ application, the application should load the sccts module and communicate with its API functions. General operation consists of the following steps:

The module SCCTS implements the Transformation Server C/C++ interface. Source files that use SCCTS should include the header file sccts.h, and make sure that the other header files included in the Transformation Server SDK are in the project's include path. Projects using SCCTS should link with SCCTS.LIB, which is included in the Transformation Server SDK. Additionally, the modules that reside in the root level of the Outside In Transformation Suite directory are required to be in the same directory as SCCTS.

Note:

The return values listed for these functions are only a selection of the most common error messages returned. For each function, other error messages are possible. These messages can be found in sccerr.h and tserr.h.

This chapter includes the following sections:

4.1 TSInit

This function must be called before any attempt to perform a transformation or option setting can be made. If TSInit succeeds, TSDeInit must be called regardless of any other API calls.

Prototype

TSERR TSInit(
    LPTSINITPARAMS pParams,
    PTSHANDLE      phSession);

Parameters

Return Values

4.1.1 TSINITPARAMSVER2 Structure

This structure is used to describe C-Stub initialization parameters.

This structure replaces the older TSINITPARAMS structure. While still valid, the TSINITPARAMS structure does not support client-side redirected IO on Linux systems where client and server reside on different machines. This new structure does support such configurations. It should also be noted that the newer structure resolves an issue seen in previous releases that affected developers on multi-homed machines.

Structure

A C data structure defined in sccts.h as follows:

typedef struct TSINITPARAMStagVer2
{
   VTDWORD    dwVersion;
   VTLPSTR    szServer;
   VTWORD     wPort;
   OpenIOProc openIO;
   VTWORD     wIOPort;
   VTLPSTR    szIOServer;
} TSINITPARAMSVER2, *PTSINITPARAMSVER2;

  • dwVersion: Identifies the version of this structure being used. Always set this value to SCCTS_INITPARAMS_CURRENTVERSION.

  • szServer: Null-terminated string that contains the address where Transformation Server is listening for transformation requests. May be either a host name or dotted-decimal IP address.

  • wPort: Port number upon which Transformation Server has been configured to listen for connections.

  • openIO: Points to an OpenIO function (see Section 8.5.1, "Handling Redirected IO" for more information). May be set to null if redirected IO is not being used.

  • wIOPort: Port number on the local machine to be used for IO-related TCP communication between Transformation Server and sccts. If redirected IO is not used, this parameter is ignored. If redirected IO is used and this parameter is set to zero, an available port will be arbitrarily chosen for the IO communication.

  • szIOServer: Host name/IP address of where redirected IO is taking place, needed only when the source or sink uses redirected IO. This is used in conjunction with the wIOPort parameter (null-terminated).

Note:

Redirected IO occurs when the specType field of a TS_IOSpec structure is set to the value of "redirect". Setting specType to "redirect" means that the file referenced in the TS_IOSpec structure needs to be accessed via client supplied IO functions. The wIOPort and szIOServer parameters are ignored if the OpenIO parameter is null.

Example

TSINITPARAMSVER2   initParms;
initParms.dwVersion = SCCTS_INITPARAMS_CURRENTVERSION;
initParms.szServer = "server1.example.com";
initParms.wPort = 747;


if( TSERR_OK != TSInit(&initParms) )
{
   /* exit with an error */
}

4.2 TSMemFree

This function allows the application using SCCTS to free allocated memory that was returned through the SCCTS interface. This function is not a generic de-allocator, and should only be called to free memory returned from an SCCTS interface function. Upon return from this function, the memory location pointed to by pvMem will be invalid.

Prototype

TSMemFree (
   TSHANDLE    hSession,
   void* pvMem);

Parameters

4.3 TSSetOption

This function is called to set the value of a transformation option.

For HTML Export and XML Export: The identifier (hOptions) indicates what particular option is being specified. sccts supports two type of identifiers: predefined numeric ID values or text names. Numeric option identifiers may only be used to specify options for the Outside In Transformation Engines; all other transformation engines must use names for option identifiers. An option name may be any character string; its character set must be UTF-8 encoded Unicode. The names used for option identifiers are defined by the Export Engine.

The option value data (pOptionValue) must be in a form that conforms to the set of supported data types (see Appendix B, "C/C++ Client Data Types" ).

Prototype

TSERR TSSetOption(
   TSHANDLE    hSession,
   VTLPSTR     szOptionName,
   VTLPVOID    pOptionValue,
   VTDWORD     dwOptionType
   );

Parameters

Return Values

4.4 TSSetOptionById

This function is called to set the value of a transformation option. It is provided to ease compatibility with code that was written to consume the embedded versions of Outside In Export Technologies. The options set-able by this function are specific to Outside In Export Technologies.

Prototype

TSERR TSSetOptionById(
   TSHANDLE   hSession,
   VTDWORD    dwOptionId,
   VTLPVOID   pOptionValue,
   VTDWORD    dwOptionSize
   );

Parameters

Return Values

4.5 TSRunTransform

TSRunTransform is used to send the transformation request to the server.

Prototype

TSERR TSRunTransform(
   TSHANDLE              hSession,
   LPTS_IOSpec           pSource,
   LPTS_IOSpec           pSink,
   VTLPSTR               szOutputFormat,
   VTLPSTR               szOptionSet,
   TS_TransformResult ** ppResults);

Parameters

Return Values

4.6 TSDeInit

After the client application is done with all the possible transformations it needed to perform, TSDeInit needs to be called. This function should be called right before the sccts module is ready to be released. Make sure that this function is called in tandem with TSInit initialization function.

Prototype
TSERR TSDeInit(
   TSHANDLE hSession
   );

Parameters

Return Values

4.7 Sample Applications

Transformation Server ships with two sample applications that demonstrate the use of the SCCTS module: TSCLIENT and TSDEMO.

Some notes concerning these sample applications:

4.7.1 tsclient

This is a Win32 application written in C++, with a dialog-based interface. Various controls and dialog boxes allow you to specify the options that affect how a document is transformed.

4.7.2 tsdemo

Note:

To build tsdemo, you will need to link to lib/sccts.lib and include common/* in your path.

This is a command-line application written in C. The options that affect the transformation itself are controlled via a text-based configuration file. The command line parameters include the TCP host and port where Transformation Server is running, as well as the input, output, and configuration files to be used.

The command-line syntax is as follows:

tsdemo ServerName PortNumber InputFile [IOServer] OutputFile ConfigurationFile [IO Type]

Here is a guide to the valid command-line parameters for tsdemo:

  • ServerName: The host name or IP address where Transformation Server is running. (Required)

  • PortNumber: The port number on which Transformation Server will accept connections. (Required)

  • InputFile: The path/URL to the input file. This parameter requires either an absolute path to a file, or a path to a file that is relative to Transformation Suite's root install directory. (Required)

  • IOServer: Host name/IP address of where redirected IO is taking place, needed only when the source or sink uses redirected IO. (Optional)

  • OutputFile: The path/URL to the output file. (Required)

  • ConfigurationFile: The desired output format. (Required)

  • IO Type: The type of IO specification used for the input and output parameters. May be a file system path (p), redirected (r), or URL (u). Default is p. (Optional)

    Note:

    Note for HTML Export: Even when u is specified for this parameter, tsdemo still expects a file path for the template and not a URL path.

Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us