This contains a basic COM binding for the
main enterprise functions (initially just
converting RML to PDF), as well as an
example client application.

License
-------
All rights reserved.  This is commercial software and
will be included in future versions of the ReportLab
distribution.  Customers for our Enterprise Report Server
products are welcome to use and adapt this in any way.
Others may evaluate as they wish. I'll write something
more formal later...

Prerequisites
-------------
This presumes you have a standard installation
on Windows including Python 2.2.x, the Pythonwin
extensions and a recent copy of ReportLab's software.
If you go to our download page and follow the 
instructions "ReportLab Windows Installer Package"
(NOT Windows Evaluation Package), you will 
have such an installation.

Install
-------
Unzip this archive a working directory anywhere you
wish. Run the script "rl_com_wrapper.py" from a DOS 
prompt in this directory to register it.  Here's
what you should see:

C:\code\rlextra\bindings\com>rl_com_wrapper.py
Registered: ReportLab.ReportServer

C:\code\rlextra\bindings\com>

You should now have a COM object available for use
from any language which supports it.


Testing
-------
The enclosed rlcomtestapp.exe is a GUI which will
test/demonstrate the use.  When it starts, it does
nothing.  When you click 'Start COM Server' it
should either do it, or complain.  You may then
select an RML file and convert it to PDF in one
of two ways:

API:
----
Here is the ReportServer API today.


double(num):
- doubles a number, as any easy test if the server is
alive.

convertRmlToPdfInMemory(rmlText):
 - pass in rml text, retrieve PDF document as a string.
See discussion below on Unicode

convertRmlFileToPdfFile(rmlFileName, pdfFileName):
 - convert to PDF and store on disk in given filename.
This will overide any filename in the RML itself (we
intend to deprecate the filename attribute).


We plan to expose our other capabilities - PageCatcher,
Encryption, Preppy, pyRXP and so on - in the near future.
Please ask us what you want!

 
API Discussion:
---------------
Returning PDF files:

In Python it is normal to use 8-bit strings and to represent
a 'byte array' as a large string.  We thus return a PDF document
as a 'big string' in memory.  However, this comes back in
Unicode (with a default Latin-1 conversion).  If you save the
string to disk it should be streamed out to disk with a Latin-1
conversion so the original bytes are recovered.  Nevertheless
the generated PDFs seem fine, even ones containing Japanese
characters :-)

We'd welcome advice or requests on the best way to return a
'byte stream' which could contain anything - including nulls
- to an enclosing VB program.


Thread safety:
We do not guarantee thread safety as the underlying library was
written without it as a concern.  However, our libraries have
been in use for several years in long running environments and
we haven't had any reports of outright thread-dangerousness
either :-)  Don't write scripts which redefine obvious globals
such as the length of a 'cm' or the color 'blue'or parallel
processing may result in strange looking documents! 

We plan to add a basic queue mechanism to ensure that requests
are processed sequentially as a workaround; and another mechanism
which starts a new process for each job.  It is also possible
to ensure 100% safety by specifying the right COM apartment model.
PDF making is intrinsically a heavy job and the overhead of starting
a Python interpreter is small compared to that of rendering, say, a 
10-page investment prospectus in real time.


- Andy Robinson
ReportLab Inc. 21 January 2003