Re: RE: [xep-support] XEP's COM wrapper?!

From: David Tolpin (
Date: Fri Jan 03 2003 - 13:23:16 PST

  • Next message: Werner Donné: "Re: [xep-support] METRIC and HYPHEN properties"

    > I (and many others) would like to try the COM wrapper before we spend the
    > $5000


    thank you for the input. First, it is $700, not $5000 to try COM; COM is available
    with developer stamped. Then, while I cannot make it available for free (because
    then I'll be answering for free one too many questions about something broken in
    Windows instead of writing code), I can publish the documentation. A description
    of the exposed interface follows.

    XEP COM Wrapper

    1. Overview

    XEP COM wrapper provides COM interface to XEP formatter engine,
    thus permitting its use in any COM-enabled environment. XEP COM
    wrapper is a single Dynamic Link Library, registered as a COM
    object in Windows.

    2. Contents of the package:

    readme.txt - this document

    XEP.DLL - principal DLL for the COM object. Incorporates TLB library.
    XEP.IDL - IDL definition for IXEPFormatter COM inteface.
    XEPJNI.JAR - Java stub classes

    EXAMPLES\CppClient\ - C++ client sample
    EXAMPLES\PHPClient\ - PHP client sample
    EXAMPLES\VBClient\ - Visual Basic client sample

    UTILS\XEPCOMCFG\xepcomcfg.exe - GUI utility to configure XEP COM settings
    UTILS\XEPCOMCFGCL\xepcomcfgcl.exe - console utility to configure XEP COM settings

    3. Requirements

    The following software must be installed on your computer in order
    to access XEP through COM interface:
    - XEP formatter version 3.0 or later, properly installed and activated;
    - Sun JDK/JRE version 1.2.2 or later (1.3 or later strongly recommended).

    XEP COM depends on JVM.DLL which is a part of Sun Java Runtime Environment;
    the path to this DLL must be present in your system-wide PATH. Typically,
    JVM.DLL is located in a subdirectory of JRE\BIN in your Java home directory.
    For JDK1.3, available subdirectories are HOTSPOT (recommended) or CLASSIC;
    for JDK1.4 they are CLIENT (recommended) and SERVER.

    4. Installation

    To install XEP COM wrapper, follow this procedure:

    A. Ensure that a copy of JVM.DLL can be found in one of the directories
       included in the PATH. XEP COM wrapper will refuse to install if it
       cannot find a Java VM.

    B. Ensure that you have write access to HKEY_LOCAL_MACHINE\Software
       branch of your computer's Registry. Normally, this requires local
       administrator privileges.

    C. Run XEPCOMSETUP.EXE and follow on-screen instructions.

    D. Upon successful completion, configure XEP COM wrapper with one of
       configuration tools (XEPCOMCFG.EXE or XEPCOMCFGCL.EXE); see explanations

    5. Deinstallation

    To remove XEP COM wrapper from your system, use 'Add/Remove Programs'
    option in the Control Panel.

    6. Configuration

    XEP COM wrapper must be configured before use. There are three types
    of configuration options:
      - classpath;
      - Java properties;
      - JVM options.

    Classpath is a list of directories and JAR files used by Java virtual
    machine to search for Java classes. It should contain all JAR files
    from XEP installation (located in its lib/ subdirectory), and XEPJNI.JAR
    stuib file supplied with XEP COM wrapper. Please refer to XEP documentation
    for additional details.

    Properties are used to set XEP options; their use is described in
    XEP documentation (XEP 3.x User Guide). You must set at least a
    property to specify the path to an existing XEP 3.x installation:

    The last type of configuration entries are JVM options, used to control
    behaviour of the underlying Java VM. An important example are options that
    set Java heap size limits: -Xms and -Xmx. By default, the amount of memory
    available to Java VM is limited to 64 MB regardless of the RAM size
    of the host machine. We strongly recommend setting these to higher
    values. For a machine with <N> megabytes of RAM, reasonable defaults are
    <N - 64> for the upper heap size limit (-Xmx) and <N/2> (or less) for the
    lower limit (-Xms). For instance, the following yields effective memory usage
    on a computer with 512 MB of RAM:

        -Xms128M -Xmx400M

    XEP COM stores its configuration information in the following registry


    There are three sub-keys (CLASSPATH, PROPERTIES, JVMOPTIONS) corresponding
    to each option type. A simple GUI utility, UTILS\XEPCOMCFG\XEPCOMCFG.EXE,
    provides a means to set up registry entries for the wrapper. Its interface
    is self-explanatory.

    You could also use simple command-line utility (UTILS\XEPCOMCFGCL\XEPCOMCFGCL.EXE)
    for batch-mode configuration. Here is an example of XEPCOMCFGCL call sequence
    to configure XEP COM wrapper on a machine having 256 MB of RAM, with XEP 3.13
    installed at C:\XEP, and COM wrapper files unpacked to C:\XEPCOM:

    xepconfigcl set_classpath C:/XEPCOM/xepjni.jar;C:/XEP/lib/xep313_client.jar;C:/XEP/lib/cryptix32-pgp.jar;C:/XEP/lib/cryptix32.jar;C:/XEP/lib/xt.jar;C:/XEP/lib/saxon.jar

    xepconfigcl set_properties ROOT=C:\XEP

    xepconfigcl set_jvmoptions -Xms128M -Xmx192M

    7. Using XEP COM wrapper

    XEP COM wrapper fully conforms to COM specification and can be used in
    any COM environment where Sun JVM (JVM.DLL) is available.

    The principal COM interface implemented by XEP COM wrapper is IXEPFormatter;
    it extends IDispatch. In addition to standard IDispatch methods,
    the interface exposes the following methods:

    HRESULT setOutputFormat([in] VARIANT vFormat);
    HRESULT setStylesheetFile([in] VARIANT vXSLFilename);
    HRESULT setStylesheet([in] VARIANT vXSL);
    HRESULT renderFile([in] VARIANT vFOFilename, [out, retval] VARIANT* vDataout);
    HRESULT render([in] VARIANT vFO, [out, retval] VARIANT* vDataout);
    HRESULT transformFile([in] VARIANT vXMLFilename, [out, retval] VARIANT* vDataout);
    HRESULT transform([in] VARIANT vXML, [out, retval] VARIANT* vDataout);
    HRESULT getDiagnostic([out, retval] VARIANT* vDiagnostic);

    All these methods use two types of parameters: BSTR packed in a VARIANT,
    and SAFEARRAY of bytes packed in VARIANT. The methods fall into 5 groups:

    1) HRESULT setOutputFormat([in] VARIANT vFormat);

         This method should be called before any other methods.
         It sets output format. The argument is a symbolic name of the output
         format; valid names are "PDF", "PostScript", and "XML" (see XEP
         User Guide for details). Parameter type is BSTR string packed in VARIANT.

    2) HRESULT setStylesheetFile([in] VARIANT vXSLFilename);
       HRESULT setStylesheet([in] VARIANT vXSL);

         These methods select an XSLT stylesheet to be used in transformation.
         set StylesheetFile or setStylesheet method must be called before
         transform() method. The first method takes a filename for the stylesheet
         as BSTR VARIANT. The second one takes XSLT stylesheet as an array of
         bytes (SAFEARRAY VARIANT)

    3) HRESULT renderFile([in] VARIANT vFOFilename, [out, retval] VARIANT* vDataout);
       HRESULT render([in] VARIANT vFO, [out, retval] VARIANT* vDataout);

         These methods take an XSL FO document at input, and return the result
         as a byte array (SAFEARRAY VARIANT). Output format is defined by
         a previous call to 'setOutputFormat' method. The first method takes
         XSL FO file name as a BSTR VARIANT, while the second one reads
         XSL FO data from an array of bytes (SAFEARRAY VARIANT)

    4) HRESULT transformFile([in] VARIANT vXMLFilename, [out, retval] VARIANT* vDataout);
       HRESULT transform([in] VARIANT vXML, [out, retval] VARIANT* vDataout);

         These methods transform its argument XML data using XSLT stylesheet
         previously set by 'setStylesheet/setStylesheetFile' methods,
         render the resulting XSL FO instance to the specified output
         format, and return the result as a byte array (SAFEARRAY VARIANT).
         Output format must be previously set by 'setOutputFormat' method.
         First method takes The first method takes XML filename as a BSTR
         VARIANT, while the second one reads XML data from an array of bytes

    5) HRESULT getDiagnostic([out, retval] VARIANT* vDiagnostic);

         This method returns diagnostic messages produced by XEP formatter.
         These messages could stem from exceptions thrown during last method
         call (in most cases, this is a result of formatter's misconfiguration
         or misbehaviour), or warnings/errors produced during formatting
         as a reaction to incorrect user input.

    The distribution includes samples of XEP COM wrapper usage in three
    programming languages: C++, Visual Basic, and PHP. All samples are
    stored in the EXAMPLES\ subdirectory of the installation target directory.

    (*) To unsubscribe, send a message with words 'unsubscribe xep-support'
    in the body of the message to from the address
    you are subscribed from.
    (*) By using the Service, you expressly agree to these Terms of Service

    This archive was generated by hypermail 2.1.5 : Fri Jan 03 2003 - 13:21:01 PST