Open topic with navigation

# Convert Files Out of Process

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.

NOTE: Currently, the main Export process and Servant processes must run on the same host.

The following are requirements for running Export out of process:

- Internet Protocol (TCP/IP) must be installed
- Multithreaded processing must be supported on the operating system platform
- The user application must be built with a multithreaded runtime library

fpConvertStream() | fpGetConvertFileList()
fpGetSummaryInfo() | fpSetStyleMapping()
KVHTMLConfig() | KVHTMLConvertFile()
KVHTMLSetStyleSheet() |

NOTE: When converting in out-of-process mode, these functions must be called after the call to start an out-of-process session and before the call to end an out-of-process session.

Other HTML Export functions, the File Extraction functions, and the COM methods always run in-process.

## Configure Out-of-Process Conversions

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 Parameters for Out-of-Process Conversion. 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.

Parameters for Out-of-Process Conversion

Parameter | Description
--- | ---
`TempFileSizeMark` unit = megabytes default=10 | The file-size threshold. If the input file received by the Servant is larger than this value, temporary files are created to store the data. The directory in which the temporary files are stored is defined by the `TempFilePath` parameter. If the file received is smaller than this value, the data is stored in memory in the Servant. This applies only when the input is a stream.
`TempFilePath` type = file path default = current working directory | The directory in which temporary files are stored. Temporary files are created when you use the `fpConvertStream()` API, and the input file surpasses the file-size threshold (`TempFileSizeMark`). If the Servant cannot access the file path, an error is generated. This applies only when converting in stream mode.
`WaitForConvert` unit = seconds default = 1800 range = 30~3600 | The length of time to wait for a Servant to convert a file. If the conversion is not completed within the specified time, the error code "`Wait for child process failed`" is generated.
`WaitForConnectionTime` unit = seconds default = 180 range = 15~600 | The length of time to wait for the Servant to connect to the application thread after the application has sent a conversion request to the Broker. If the Servant does not connect within the specified time, the error code "`Wait for child process failed`" is generated. If there are many Servant processes running simultaneously, you might need to increase this value.
`ListenerPortList` type = integer default = 9985, 9986, 9987, 9988, 9989 | The TCP/IP port number used for communication between the calling application and the Servant. You can specify a single port number, or a series of numbers separated by commas.
`ListenerTimeout` unit = seconds default = 10 range = 5~30 | The length of time to wait for the Servant listener thread to get a process ID from the Servant after the connection is established. If the ID is not obtained within the specified time, the error code "`Wait for child process failed`" is generated. During this time, no other Servant can connect with the application.
`ConnectRetryInterval` unit = microseconds default = 0.1 range = 50000~500000 | The length of time to wait after a Servant has failed to connect to the application before it retries the connection. A Servant might be unable to connect because the application is waiting for another Servant to send a process ID. To calculate the total retry interval, the value set here is added to the platform-specific TCP retry value (on Windows, this is 1 second).
`ConnectRetry` type = integer default = 120 range = 30~600 | The number of attempts the Servant makes to connect to the calling application. This value and the total retry interval determine the total delay time. The total delay is calculated as follows: `ConnectRetryInterval` + `platform-specific_TCP_retry_value` * `ConnectRetry` For example, if the `ConnectRetryInterval` is set to 2 seconds, and the Export process is running on Windows (the default TCP retry value on Windows is 1 second), the total delay would be: 2 + 1 * 120 = 360 The Servant would attempt to connect to the application every 3 seconds for 120 attempts for a total of 360 seconds.
`ServantName` type = string default = servant | The name of the Servant process. To move the Servant to another location, enter a fully qualified path.

## Run Export Out of Process—Overview

To convert files out of process

1. If required, set parameters for the out-of-process conversion in the `formats_e.ini` file. See Configure Out-of-Process Conversions.

2. Initialize an Export session.

3. If you are using streams, create an input stream.

4. Define the conversion options.

5. Initialize an out-of-process session.

6. Convert the input and/or call other functions that can run out of process.

7. Shut down the out-of-process session.

8. Repeat Step 3 through Step 7 for additional files.

9. Terminate the out-of-process session and the Servant process.

10. Shutdown the Export session.

### Recommendations

- 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 `KVHTMLEndOOPSession()` 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.

## Run Export Out of Process

The `cnv2htmloop` sample program demonstrates how to run Export out of process.

To convert files out of process in the C API

1. If required, set parameters for the out-of-process conversion in the `formats_e.ini` file. See Configure Out-of-Process Conversions.

2. Declare instances of the following types and assign values to the members as required:

       KVHTMLTemplateEx
       KVHTMLOptionsEx
       KVHTMLHeadingInfo
       KVHTMLTOCOptions

   SeeHTML Export API Structures for more information.

3. Load the `KVHTML` library and obtain the `KVHTMLInterfaceEx` entry point by calling `KVHTMLGetInterfaceEx()`.

   See KVHTMLGetInterfaceEx().

4. Initialize an Export session by calling `fpInit()`. See fpInit().

5. If you are using streams for the input and output source, follow these steps; otherwise, proceed to Step 6:

   1. Create an input stream (`KVInputStream`) by calling `fpFileToInputStreamCreate()`. See fpFileToInputStreamCreate().

   2. Create an output stream (`KVOutputStream`) by calling `fpFileToOutputStreamCreate()`. See fpFileToOutputStreamCreate().

   3. Proceed to Set up an out-of-process session by calling KVHTMLStartOOPSession(). .

6. Set up an out-of-process session by calling `KVHTMLStartOOPSession()`.

   See KVHTMLStartOOPSession(). 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`.

   - Passes conversion options from the `KVHTMLTemplateEx`, `KVHTMLOptionsEx`, and `KVHTMLTOCOptions` 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—KVHTMLStartOOPSession, and KVHTMLStartOOPSession().

7. Convert the input and generate the output files by calling `KVHTMLConvertFile()` or `fpConvertStream()`. The `KVHTMLTemplateEx`, `KVHTMLOptionsEx`, and `KVHTMLTOCOptions` structures are passed in the call to `KVHTMLStartOOPSession()`, and should be `NULL` in the conversion call. A conversion function can be called only once in a single out-of-process session. See KVHTMLConvertFile(), and fpConvertStream().

8. Terminate the out-of-process session by calling `KVHTMLEndOOPSession()`. The Servant ends the current conversion session, and releases the source data and session resources. See sample code in Example—KVHTMLEndOOPSession, and KVHTMLEndOOPSession().

9. 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().

10. Repeat Step 5 through Step 9 for additional files.

11. After all files are converted, terminate the out-of-process session and the Servant process by calling `KVHTMLEndOOPSession()` and setting the Boolean to `FALSE`.

12. After the out-of-process session and Servant are terminated, shut down the Export session by calling `fpShutDown()`. See fpShutDown().

### Example—KVHTMLStartOOPSession

The following sample code is from the `cnv2htmloop` sample program:

    /* declare OOP startsession function pointer */
    KVHTML_START_OOP_SESSION fpKVHTMLStartOOPSession;
    /* assign OOP startsession function pointer */
    fpKVHTMLStartOOPSession = (KVHTML_START_OOP_SESSION)mpGetProcAddress
                              (hKVHTML, "KVHTMLStartOOPSession");
       if(!fpKVHTMLStartOOPSession)
       {
          printf("Error assigning KVHTMLStartOOPSession pointer\n");
          (*KVHTMLInt.fpFileToInputStreamFree)(pKVHTML, &Input);
          (*KVHTMLInt.fpFileToOutputStreamFree)(pKVHTML, &Output);
          mpFreeLibrary(hKVHTML);
          return 7;
       }
    /********START OOP SESSION *****************/
    if(!(*fpKVHTMLStartOOPSession)(pKVHTML,
            &Input,
            NULL,
            &HTMLTemplates,        /* Markup and related variables */
            &HTMLOptions,          /* Options */
            NULL,                  /* TOC options */
            &oopServantPID,
            &error,
            0,
            NULL,
            NULL))
    {
       printf("Error calling fpKVHTMLStartOOPSession \n");
       (*KVHTMLInt.fpShutDown)(pKVHTML);
       mpFreeLibrary(hKVHTML);
       return 9;
    }

### Example—KVHTMLEndOOPSession

The following sample code is from the `cnv2htmloop` sample program:

    /* declare endsession function pointer */
    KVHTML_END_OOP_SESSION   fpKVHTMLEndOOPSession;
    /* assign OOP endsession function pointer */
    fpKVHTMLEndOOPSession = (KVHTML_END_OOP_SESSION)mpGetProcAddress
                            (hKVHTML, "KVHTMLEndOOPSession");
       if(!fpKVHTMLEndOOPSession)
       {
          printf("Error assigning KVHTMLEndOOPSession pointer\n");
          (*KVHTMLInt.fpFileToInputStreamFree)(pKVHTML, &Input);
          (*KVHTMLInt.fpFileToOutputStreamFree)(pKVHTML, &Output);
          mpFreeLibrary(hKVHTML);
          return 8;
       }
    /********END OOP SESSION, DO NOT KEEP SERVANT ALIVE *********/
    if(!(*fpKVHTMLEndOOPSession)(pKVHTML,
            FALSE,
            &error,
            0,
            NULL,
            NULL))
    {
       printf("Error calling fpKVHTMLEndOOPSession \n");
       (*KVHTMLInt.fpShutDown)(pKVHTML);
       mpFreeLibrary(hKVHTML);
       return 10;
    }

© 2006-2018 EntIT Software LLC, a Micro Focus company | Send documentation feedback to Micro Focus Close Send documentation feedback To open the configured email client on this computer, open an email window. Otherwise, copy the information below to a web mail client, and send this email to swpdl.idoldocsfeedback@microfocus.com. We appreciate your feedback! Product: Topic Title: Help Topic: Feedback:

_FT_HTML5_bannerTitle.htm