From: David Tolpin (dvd@renderx.com)
Date: Fri Jan 03 2003 - 13:23:16 PST
>
> I (and many others) would like to try the COM wrapper before we spend the
> $5000
Hi,
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
below.
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:
ROOT=<xep_path>.
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
branch:
HKEY_LOCAL_MACHINE\SOFTWARE\RenderX\XEP
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
(SAFEARRAY VARIANT)
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 majordomo@renderx.com from the address
you are subscribed from.
(*) By using the Service, you expressly agree to these Terms of Service http://www.renderx.com/tos.html
This archive was generated by hypermail 2.1.5 : Fri Jan 03 2003 - 13:21:01 PST