Run Export Out-of-Process

The cnv2xmloop 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:

    KVXMLTemplateEx
    KVXMLOptions
    KVXMLHeadingInfo
    KVXMLTOCOptions

    See XML Export API Structures for more information.

  3. Load the KVXML library and call KVXMLGetInterfaceEx().

  4. Initialize an Export session by calling 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 Step 6.

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

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

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

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

  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 to Step 9 for additional files.

  11. After all files are converted, terminate the out-of-process session and the Servant process by calling KVXMLEndOOPSession() 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—KVXMLStartOOPSession

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;    
}

Example—KVXMLEndOOPSession

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;
}