8 Upgrading Applications to Use Transformation Server

8.3.1.1 Replacing the Document Handle with an "Option Set Handle"

In the embedded versions of the Outside In Export interfaces, options are tied to a "document handle" – an identifier returned from DAOpenDocument that tells the Export module to which input document the options should apply. The Transformation Server C client presents a different model: the input document is not "opened" in any way prior to initiating a transformation; and transformation options are grouped together in an "option set" that may be applied to more than one input document.

Embedded Version

VTHDOC hDoc;     /* document handle */
DAERR deResult ; /* result code*/
deResult = DAOpenDocument(
    &hDoc,                     /* receives handle to document */
    IOTYPE_ANSIPATH,           /* type of path to file */
    (VTLPVOID) pInputPath,     /* input file */
    0);                        /* flags */
/* when the document no longer needs to be open */
DACloseDocument(hDoc);

C Client Version

TSOPTIONS hOpt;     /* option set handle */
TSERR     tsResult; /* result code */
tsResult = TSOpenOptions (
    NULL,    /* name of option set (null term. string or NULL)*/
    &hOpt ); /* receives handle to option set */
/* when the options are no longer needed */
TSCloseOptions(hOpt);

8.3.1.2 Setting Options

The SCCTS module includes a function called TSSetOptionById that supports most of the data structures and option identifiers that were used in the embedded interface function DASetOption. Apart from their names, the functions differ only in the first parameter, which controls how the options are collected (with a "document handle" vs. an "option set handle").

Most options that affect a transformation can be specified with the same data types that were used in the interface to SCCEX. For these options, simply replace the VTHDOC parameter with a TSOPTIONS parameter, and call TSSetOptionById instead of DASetOption. The following is an example:

Embedded Version

DAERR deResult; /* result code*/
DWORD dwVal = FI_GIF;
    deResult = DASetOption( hDoc, SCCOPT_GRAPHIC_TYPE,
        (LPVOID)&dwVal, sizeof(DWORD));

C Client Version

TSERR tsResult; /* result code */
DWORD dwVal = FI_GIF;
    tsResult = TSSetOptionById( hOpt, SCCOPT_GRAPHIC_TYPE,
        (LPVOID)&dwVal, sizeof(DWORD));

8.3.1.3 Exceptions to This Rule (HTML Export Only)

The option SCCOPT_EX_TEMPLATE, which identifies the template to be used when producing output documents, must be specified with a different data type than it was in the embedded API.

In the embedded API this option was specified via a special function called DASetFileSpecOption. In the C client API the template location is described in a TS_IOSpec data structure, which is specified through the TSSetOptionById function. As a result of this difference, the C client uses a different identifier, defined as SCCOPT_TS_TEMPLATE, that is specific to the C client. Any attempt to specify an option identified as SCCOPT_EX_TEMPLATE will fail.

Embedded Version

deResult = DASetFileSpecOption( hDoc, SCCOPT_EX_TEMPLATE,
    IOTYPE_ANSIPATH, "\\exports\templates\template.html" );

C Client Version

TS_IOSpec template;
    template.spec.str = "\\exports\templates\template.html";
    template.spec.charset = ts_windows_1252;
    template.specType = "path";
    tsResult = TSSetOptionById( hOpt, SCCOPT_TS_TEMPLATE,
        (LPVOID)&template, sizeof(TS_IOSpec));

8.3.2.1 EX_CALLBACK_ID_CREATENEWFILE

This functionality represented by this callback has been distributed to different areas of the client API. This callback existed to notify the calling application when a new output file was about to be created, allowing the application to change the both the name and the hyperlink (URL) used to reference the file in the transformation output.

For an application using Transformation Server's built-in input and output facilities, the ability to change the names of the output file or its URL will not be supported in the Transformation Server client. For applications that provide their own IO through the redirected IO interface, this callback's functionality will be supported through the IOGetInfo messages IOGETINFO_CREATENEWOUTPUTSPEC (and IOGETINFO_HYPERLINK for HTML Export). For details, please refer to the documentation for redirected IO.

The reporting capabilities of this message are provided by the results of the TSRunTransform function, which provides an array containing the specifications of all output files created for the transformation.

8.3.2.2 EX_CALLBACK_ID_NEWFILEINFO

The reporting capabilities of this message are provided by the results of the TSRunTransform function, which provides an array containing the specifications of all output files created for the transformation.

8.3.2.3 EX_CALLBACK_ID_ALTLINK (HTML Export Only)

This callback's functionality has been replaced by a new option: SCCOPT_TS_ALTLINK. This option is specified as a data structure (OIT_AltLink) containing two TS_stringData structures, one for the "previous" and one for the "next" alt links.

Embedded Version

case EX_CALLBACK_ID_ALTLINK:
{
   EXALTLINKCALLBACKDATA *pData = 
      (EXALTLINKCALLBACKDATA*)pCommandOrInfoData;
   result = SCCERR_NOTHANDLED;

   if( pData->dwType == EX_ALTLINK_PREV )
   {
      lstrcpy(pData->pAltURLStr, "alternate prev-page link");
      result = SCCERR_OK;   
   }
   else if( pData->dwType == EX_ALTLINK_NEXT )
   {
      lstrcpy(pData->pAltURLStr, "alternate next-page link");
      result = SCCERR_OK;   
   }
}
break;

C Client Version

HWX_AltLink   altLinks;
altLinks.prev.str = "alternate prev-page link";
altLinks.prev.charset = ts_windows_1252;
altLinks.next.str = "alternate next-page link";
altLinks.next.charset = ts_windows_1252;

TSSetOptionById( hOpt, SCCOPT_TS_ALTLINK, (VTLPVOID)&altLinks, 
   sizeof(HWX_AltLink);

8.3.2.4 EX_CALLBACK_ID_PROCESSLINK (HTML Export Only)

This functionality represented by this callback message has limited support in Transformation Server. While the option to insert alternate links is not available, the basic ability to skip or process linked graphics is presented as a Boolean option with the identifier SCCOPT_TS_SKIPLINKEDIMAGES. This option allows the calling application to specify that linked files should be either transformed or skipped.

C Client Example

VTBOOL   bSkipLinkedImages = TRUE;
TSSetOptionById( hOpt, SCCOPT_TS_SKIPLINKEDIMAGES,
   &bSkipLinkedImages, sizeof(VTBOOL) );

8.3.2.5 Unsupported Callbacks

The functionality represented by the following embedded API callback messages is not supported on the Transformation Server client side:

• EX_CALLBACK_ID_CUSTOMELEMENTLIST

• EX_CALLBACK_ID_GRAPHICEXPORTFAILURE

• EX_CALLBACK_ID_OEMOUTPUT

• EX_CALLBACK_ID_OEMOUTPUT_VER2

• EX_CALLBACK_ID_PROCESSELEMENTSTR

• EX_CALLBACK_ID_PROCESSELEMENTSTR_VER2

• EX_CALLBACK_ID_REFLINK

• EX_CALLBACK_ID_ENTERARCHIVE

• EX_CALLBACK_ID_LEAVEARCHIVE

8.5.1.1 Server-Side vs. Client-Side Redirected IO

As a client-server application, Transformation Server runs its transformation operations in a separate process from the "client" application that uses it. For maximum flexibility, Transformation Server allows redirected IO to be provided on either the server side or the client side. In other words, the code that provides the IO may execute in the process of the client application or in the process where the transformation occurs. From an implementation point of view, there is little to no difference between the two approaches; it is entirely possible to use the same binary code to provide redirected IO on both the client and server.

As in the embedded API, an application that provides redirected IO must implement the functions defined in the BASEIO interface. In client-side redirected IO, the C client API communicates through TCP/IP with the server-side transformation process, and relays IO operations to the BASEIO interface provided by the application. In server-side redirected IO, the application provides its redirected IO code in a dynamically loadable library that is loaded by the transformation process as needed. Communication with the redirected IO code then proceeds in-process as the transformation is being performed.

While the server-side redirected IO may require a small amount of additional work when compared to client-side redirected IO, it has a significant performance advantage in the fact that all IO occurs in-process. Client-side IO, on the other hand, has the ability to communicate in-process with the client application that is requesting the transformation, which may be a requirement for retrieving or writing the data.

8.5.1.2 What's Different About Redirected IO in Transformation Server

From an implementation point of view, the main differences between redirected IO in Transformation Server versus the embedded API are:

1. How the IO "targets" are specified in the API.

2. How IOGetInfo queries are handled.

struct myIOStruct 
{
   BASEIO   baseIO;
   MYDATA   privateData;
};
/* ... initialize myIOStruct ...*/
EXRunExport( hDoc, (HIOFILE) &myIOStruct, FI_HTML, ... )

8.5.1.3 Redirected IO on the Client Side

The following steps are necessary to take an existing implementation of redirected IO and make it available to the Transformation Server C Client API.

1. Define a way to represent an IO target in a text string that can be passed in a TS_IOSpec structure.

2. Implement an OpenIO function that maps from TS_IOSpec to your BASEIO structure.

3. Modify your IOGetInfo function to handle the new Transformation Server style queries.

4. Provide the pointer to your OpenIO function in the initialization structure passed to TSInit.

8.5.1.4 Redirected IO on the Server Side

To make redirected IO available on the server side, perform steps 1 through 3 above, and then do the following:

1. Build your redirected IO code into a loadable module/DLL, with OpenIO specified as an exported function.

2. Modify the Transformation Server configuration file agent_iospec_types.xml to indicate the location of your IO module.

In the preceding step, you must also define an IO spec type for your module (the specType field in the TS_IOSpec structure). Note that the specType value redirect is reserved for client-side redirected IO, and will not work for a server-side IO provider.

Note that these two approaches are not mutually exclusive. There's no reason an IO Provider built for server-side redirected IO couldn't be used on the client side, as well.