Export can run independently from the calling application. This is called out of process. Out-of-process conversions protect the stability of the calling application in the rare case when a malformed document causes Export to fail. You can also run Export in the same process as the calling application. This is called in process. However, it is strongly recommended you convert documents out of process whenever possible.
The Export out-of-process framework uses a client-server architecture. The calling application sends an out-of-process conversion request to the Service Request Broker in the main Export process. The Broker then creates, monitors, and manages a Servant process for the request—each request is handled by one independent Servant process. Data is exchanged between the application thread and the Servant through TCP/IP sockets. The source data is sent to the Servant process as a data stream or file, converted in the Servant, and then returned to the application thread. At that point, the application can either terminate the Servant process or send more data for conversion.
Multiple conversion requests can be sent from multiple threads in the calling application simultaneously. All requests sent from one thread are processed by the Servant mapped to that thread, in other words, each thread can only have one Servant to process its conversion requests.
Any standard conversion errors generated by the Servant are sent to the application.
The following are requirements for running Export out of process:
Other Export API functions and the File Extraction functions always run in-process.
Although most components of the out-of-process conversion are transparent, the following parameters are configurable:
File-size threshold/temporary file location
Conversion time-out
Listener port numbers and time-out
Connection time-out and retry
Servant process name
These parameters are defined internally, but you can override the default by defining the parameter in the formats_e.ini
file. The formats_e.ini
file is in the directory install\OS\bin
, where install
is the path name of the Export installation directory and OS
is the name of the operating system.
To set the parameters, add the following section to the formats_e.ini
file:
[KVExportOOPOptions] TempFileSizeMark= TempFilePath= WaitForConvert= WaitForConnectionTime= ListenerPortList= ListenerTimeout= ConnectRetryInterval= ConnectRetry= ServantName= EnableDebugOutput= EnableDebugLog= LogFilePath= ClientLogFile= ServerLogFile=
Each parameter is described in the following table. The default values for these parameters are set to ensure reasonable performance on most systems. If you are processing a large number of files, or running Export on a slow machine, you might need to increase some of the time-out and retry values.
To convert files out of process
If required, set parameters for the out-of-process conversion in the formats_e.ini
file. See Configure Out-of-Process Conversions.
Initialize an Export session.
Define the conversion options.
Initialize an out-of-process session.
Convert the input and/or call other functions that can run out of process.
Terminate the out-of-process session and the Servant process.
Shutdown the Export session.
To ensure that multithreaded conversions are thread-safe, you must create a unique context pointer for every thread by calling fpInit()
. In addition, threads must not share context pointers, and the same context pointer must be used for all API calls in the same thread. Creating a context pointer for every thread does not affect performance because the context pointer uses minimal resources.
All functions that can run in out-of-process mode must be called within the out-of-process session (that is, after the call to initialize the out-of-process session and before the call to end the out-of-process session).
When terminating an out-of-process session, persist the Servant process by setting the Boolean flag bKeepServantAlive
in the KVXMLEndOOPSession()
function or endOOPSession
method. If the Servant process remains active, subsequent conversion requests are processed more quickly because the Servant process is already prepared to receive data. Only terminate the Servant when there are no more out-of-process requests.
To recover from a failure in the Servant process, start a new out-of-process session. This creates a new Servant process for the next conversion.
The cnv2xmloop
sample program demonstrates how to run Export out of process.
To convert files out of process in the C API
If required, set parameters for the out-of-process conversion in the formats_e.ini
file. See Configure Out-of-Process Conversions.
Declare instances of the following types and assign values to the members as required:
KVXMLTemplateEx KVXMLOptionsEx KVXMLHeadingInfo KVXMLTOCOptions
See XML Export API Structures for more information.
Load the KVXML
library and obtain the KVXMLInterface
entry point by calling KVXMLGetInterface()
.
See KVXMLGetInterface().
Initialize an Export session by calling fpInit()
. See fpInit().
If you are using streams for the input and output source, follow these steps; otherwise, proceed to Step 6:
Create an input stream (KVInputStream
) by calling fpFileToInputStreamCreate()
. See fpFileToInputStreamCreate().
Create an output stream (KVOutputStream
) by calling fpFileToOutputStreamCreate()
. See fpFileToOutputStreamCreate().
Proceed to Step 6.
Set up an out-of-process session by calling KVXMLStartOOPSession()
.
KVXMLStartOOPSession(). This function performs the following:
Initializes the out-of-process session.
Specifies the input stream or file. If you are using an input file, set pFileName
to the file name, and set pInputStream
to NULL
. If you are using an input stream, set pInputStream
to point to KVInputStream
, and set pFileName
to NULL
.
Sets conversion options in the KVXMLTemplate
, KVXMLOptions
, and KVXMLTOCOptions
data structures.
Creates a Servant process.
Establishes a communication channel between the application thread and the Servant.
Sends the data to the Servant.
See the sample code in Example—KVXMLStartOOPSession, and KVXMLStartOOPSession().
Convert the input and generate the output files by calling KVXMLConvertFile()
or fpConvertStream()
. The KVXMLTemplate
, KVXMLOptions
, and KVXMLTOCOptions
structures are defined in the call to KVXMLStartOOPSession()
, and should be NULL
in the conversion call. A conversion function can be called only once in a single out-of-process session. See KVXMLConvertFile(), and fpConvertStream().
Terminate the out-of-process session by calling KVXMLEndOOPSession()
. The Servant ends the current conversion session, and releases the source data and session resources. See sample code in Example—KVXMLEndOOPSession, and KVXMLEndOOPSession().
If you used streams, free the memory allocated for the input stream and output stream by calling the fpFileToInputSreamFree()
and fpFileToOutputStreamFree()
functions. See fpFileToInputStreamFree() and fpFileToOutputStreamFree().
After all files are converted, terminate the out-of-process session and the Servant process by calling KVXMLEndOOPSession()
and setting the Boolean to FALSE
.
After the out-of-process session and Servant are terminated, shut down the Export session by calling fpShutDown()
. See fpShutDown().
The following sample code is from the cnv2xmloop
sample program:
/* declare OOP startsession function pointer */ KVXML_START_OOP_SESSION fpKVXMLStartOOPSession; /* assign OOP startsession function pointer */ fpKVXMLStartOOPSession = (KVXML_START_OOP_SESSION)mpGetProcAddress (hKVXML,"KVXMLStartOOPSession"); if(!fpKVXMLStartOOPSession) { printf("Error assigning KVXMLStartOOPSession pointer\n"); (*KVXMLInt.fpFileToInputStreamFree)(pKVXML, &Input); (*KVXMLInt.fpFileToOutputStreamFree)(pKVXML, &Output); mpFreeLibrary(hKVXML); return 7; } /********START OOP SESSION *****************/ if(!(*fpKVXMLStartOOPSession)(pKVXML, &Input, NULL, &XMLTemplates, /* Markup and related variables */ &XMLOptions, /* Options */ NULL, /* TOC options */ &oopServantPID, &error, 0, NULL, NULL)) { printf("Error calling fpKVXMLStartOOPSession \n"); (*KVXMLInt.fpShutDown)(pKVXML); mpFreeLibrary(hKVXML); return 9; }
The following sample code is from the cnv2xmloop
sample program:
/* declare endsession function pointer */ KVXML_END_OOP_SESSION fpKVXMLEndOOPSession; /* assign OOP endsession function pointer */ fpKVXMLEndOOPSession = (KVXML_END_OOP_SESSION)mpGetProcAddress (hKVXML, "KVXMLEndOOPSession"); if(!fpKVXMLEndOOPSession) { printf("Error assigning KVXMLEndOOPSession pointer\n"); (*KVXMLInt.fpFileToInputStreamFree)(pKVXML, &Input); (*KVXMLInt.fpFileToOutputStreamFree)(pKVXML, &Output); mpFreeLibrary(hKVXML); return 8; } /********END OOP SESSION, DO NOT KEEP SERVANT ALIVE *********/ if(!(*fpKVXMLEndOOPSession)(pKVXML, FALSE, &error, 0, NULL, NULL)) { printf("Error calling fpKVXMLEndOOPSession \n"); (*KVXMLInt.fpShutDown)(pKVXML); mpFreeLibrary(hKVXML); return 10; }
|