4 Initiating Transformations Using the C/C++ API

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

• pParams: Pointer to a data structure, TSINITPARAMS, that describes C-Stub initialization parameters.

• phSession: Pointer to a variable of type TSHANDLE. Upon successful return from TSInit, this variable will be set to the "session handle" to be used in subsequent calls to the SCCTS interface. Note that this handle must not be used simultaneously in multiple threads.

Return Values

• TSERR_OK: Indicates success.

• TSERR_UNKNOWN: Error trapping caught an unforeseen exception, such as an operating system or hardware exception. Please examine the status of the machine running the sccts module (including available memory, hard drive space and connectivity).

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

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

• hSession: The handle for the Transformation Server session.

• pvMem: A pointer to allocated memory returned from the SCCTS interface.

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

• hSession: The handle for the Transformation Server session.

• szOptionName: Name of the option to be set in Unicode, null-terminated.

• pOptionValue: Pointer to the value of the option.

• dwOptionType: Type identifier indicating what type of option value is pointed to by pOptionValue. Allowable option types and their identifiers are described later in this book.

Return Values

• TSERR_OK: Indicates success.

• TSERR_BADPARAM: One of the parameter values in the function call is incorrect.

• TSERR_UNKNOWN: Error trapping caught an unforeseen exception, such as an operating system or hardware exception. Please examine the status of the machine running the sccts module (including available memory, hard drive space and connectivity).

• TSERR_BADOPTIONTYPE: dwOptionType was invalid.

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

• hSession: The handle for the Transformation Server session.

• dwOptionId: The identifier of the option to be set.

• pOptionValue: Pointer to a buffer containing the value of the option.

• dwOptionSize: The size in bytes of the data pointed to by pOptionValue. For a string value, the null terminator should be included when calculating dwOptionSize.

Return Values

• TSERR_OK: Indicates success.

• TSERR_BADPARAM: One of the parameter values in the function call is incorrect.

• TSERR_UNKNOWN: Error trapping caught an unforeseen exception, such as an operating system or hardware exception. Please examine the status of the machine running the sccts module (including available memory, hard drive space and connectivity).

• TSERR_INVALIDOPTION: dwOptionId was invalid.

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

• hSession: The handle for the Transformation Server session.

• pSource: Pointer to a TS_IOSpec structure defining the transformation source. The valid values for this parameter are defined in the server-side configuration file, agent_iospec_types.xml. If unedited, this file specifies path, url or riot as the three valid values. See Section 8.4.1, "Specifying Inputs and Outputs with TS_IOSpec" for more details.

• pSink: Pointer to a TS_IOSpec structure defining the transformation sink. The valid values for this parameter are defined in the server-side configuration file, agent_iospec_types.xml. If unedited, this file specifies path, url or riot as the three valid values. See Section 8.4.1, "Specifying Inputs and Outputs with TS_IOSpec".

• szOutputFormat: Output format name in UTF-8 encoded Unicode, null-terminated. The valid output formats are contained in the configuration file called agent_engine_list.xml.

• szOptionSet: Option set name in UTF-8 encoded Unicode, null-terminated. Option sets can be coded by hand, or using the included option set editor (see Section 2.4, "The Option Set Editor").

• ppResults: Results of the transformation. It should also be noted that the data returned in the TS_TransformResult pointer must be freed by the calling application. This is done through a single call to TSMemFree. See Section 4.2, "TSMemFree" for details.

Return Values

• TSERR_OK: Indicates success.

• TSERR_BADPARAM: One of the parameter values in the function call is incorrect.

• TSERR_UNKNOWN: Error trapping caught an unforeseen exception, such as an operating system or hardware exception. Please examine the status of the machine running the sccts module (including available memory, hard drive space and connectivity).

• TSERR_OBJECTREFERENCEINVALID: AddReference method of the Options object returned NULL. Check that the Options parameter is valid.

• TSERR_OUTPUTFORMAT_NOTSUPPORTED: The output format designated in the call is not supported for the transform being attempted.

• TSERR_OPTIONSET_NOTSUPPORTED: The option set designated in the call is not supported for the transform being attempted.

• TSERR_ALLOCFAILED: Memory allocation failed.

• TSERR_INPUTOPENFAILED: Could not open the designated input file.

• TSERR_OUTPUTOPENFAILED: Could not create the designated output file.

• TSERR_FILECLOSEFAILED: A resource failed to be closed properly.

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

• hSession: The handle for the Transformation Server session.

Return Values

• TSERR_OK: Indicates success.

• TSERR_UNKNOWN: Error trapping caught an unforeseen exception, such as an operating system or hardware exception. Please examine the status of the machine running the sccts module (including available memory, hard drive space and connectivity).

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:

• The source code for these applications is provided, along with Microsoft Developer Studio project files. These applications were designed to demonstrate the use of the Transformation Server and the SCCTS module. They are freely modifiable, but are not warranteed and should not be assumed to be of commercial quality.

• TSCLIENT makes use of Microsoft Foundation Classes (MFC) and therefore must be built using Microsoft Developer Studio.

• Both of these applications demonstrate the use of custom IO Providers (also referred to as redirected IO). In both cases, the redirected IO code does nothing more than implement a thin layer on top of the file system input and output. As a result, the file specifications for these examples of redirected IO are identical to normal file system paths (unless the URL IO type is chosen, in which case the file specification must be a URL, not a file system path).

• In order to transform documents, both of these applications require Transformation Server (tsmanager) to be running and accessible via TCP/IP.

• These applications must be linked with SCCTS, which in turn requires access to various support DLL files located in the root level of the Outside In Transformation Suite directory. Running these sample applications from any other directory will result in an error, unless you add Transformation Suite's root directory to your path.

• The following information is needed to build the sample app tsdemo on Unix.

  To build on Solaris:

  make _solaris=1 clean all
  

  To build on Linux:

  make _linux=1 clean all
  

tsdemo ServerName PortNumber InputFile OutputFile ConfigurationFile [IO Type switch] [IOServerName]