_MzCOM_
=======

This directory contains the files for MzCOM, a COM 
class wrapper for MzScheme.

The code is in the file mzcom.exe.  During normal
installation of MzCOM from the file mzcom.plt, the
executable is registered automatically.  You can 
move the .exe to whatever location you like, but
you'll need to re-register it.  From the command
line, run

  mzcom.exe /RegServer

If you move mzcom.exe, you'll also need to set the Windows 
environment variables PLTHOME or PLTCOLLECTS for 
MzCOM to find collections.  

The mzcom.exe executable also requires the dynamic 
libraries libmzsch<version>.dll and libmzgc<version>.dll.
Those files must be in your PATH.  If you have DrScheme 
installed, those files are in the System32 subdirectory of the 
main Windows directory, which is in the default Windows PATH.

Loading MzCOM
-------------

To load a COM object, COM hosts require a COM class 
name or a ProgID.  MzCOM has the class name 
"MzObj Class" and the ProgID "MzCOM.MzObj.<version>",
where <version> is the version number, such as 200.

In the Visual BASIC 6 environment, from the menu 
Project|References (VB6), check "MzCOM 1.0 Type Library".  
In Visual BASIC .NET, choose Project|Add Reference,
and from the COM tab, select "MzCOM 1.0 Type Library".
In your code, declare a variable, then assign to it:

  DIM schemeObject AS MzObj
  SET schemeObject = NEW MzObj

From Visual C++:

 #include "mzcom.h" 
     
 CLSID clsid;
 IMzObj *pIMzObj;

 CoInitialize(NULL);
 CLSIDFromProgID(L"MzCOM.MzObj.<version>",&clsid);
 CoCreateInstance(clsid,NULL,CLSCTX_SERVER,IID_IMzObj,
                        (void **)&pIMzObj);

where <version> is the version number.  You'll need the 
definition of IID_IMzObj (see GUID's, below).  The header 
file mzcom.h is in plt\src\worksp\mzcom\. This C/C++ code 
is for illustration.  Of course, your actual code should 
check return values.  

Using PLT's MysterX, available at 

  http://www.plt-scheme.org/software/mysterx/

you can load MzCOM with either

  (cci/coclass "MzObj Class")

or

  (cci/progid "MzCOM.MzObj.<version>")

Consult your documentation for loading MzCOM into other
COM environments.  MzCOM is compiled as a "dual-mode"
class, meaning its methods may be called directly or by
using OLE Automation.

GUID's
------

When compiled, the directory

  plt\src\worksp\mzcom\

contains the file MzCOM_i.c that contains GUID's for MzCOM.
Those GUID's are

  const IID IID_IMzObj = 
    {0xA604CBA8,0x2AB5,0x11D4,{0xB6,0xD3,0x00,0x60,0x08,0x90,0x02,0xFE}};

  const IID LIBID_MZCOMLib = 
    {0xA604CB9C,0x2AB5,0x11D4,{0xB6,0xD3,0x00,0x60,0x08,0x90,0x02,0xFE}};

  const IID DIID__IMzObjEvents = 
    {0xA604CBA9,0x2AB5,0x11D4,{0xB6,0xD3,0x00,0x60,0x08,0x90,0x02,0xFE}};

  const CLSID CLSID_MzObj = 
    {0xA3B0AF9E,0x2AB0,0x11D4,{0xB6,0xD2,0x00,0x60,0x08,0x90,0x02,0xFE}};

which represent the IMzObj interface, the MzCOM type library,
the IMzObjEvents interface, and the MzObj class, respectively.

Methods
-------

MzCOM has three methods.

> About :: void About(void)

About() takes no arguments and displays an informational 
dialog.

> Eval :: BSTR Eval(BSTR input)

Eval() takes and returns BSTR's (BASIC strings).  The
returned value is the result of evaluating the input
expression, formatted as a string.  The input string
may contain several S-expressions.  The embedded MzScheme
updates its environment with each evaluation.  Therefore,
it is possible to define procedures in a call to 
Eval(), and use the procedures in subsequent calls.

> Reset :: void Reset(void)

Reset() resets the Scheme environment to the 
initial environment.  Also, the custodian for the 
primary Scheme thread is invoked, shutting 
all its managed values.

Events
------

MzCOM has a single event.

> SchemeError()

The SchemeError() event is passed a BSTR (BASIC string)
that explains the error.  

Errors
------

When an error occurs in MzCOM, it creates a COM
error object.  C and C++ clients can use GetErrorInfo()
to retrieve error information.  Clients implemented 
in other languages typically have some equivalent means 
to obtain COM error information.

Collections
-----------

If mzcom.exe is installed to its default location,
MzCOM is able to find other PLT collections. 
When setting up the collection paths, MzCOM adds 
the variable

> mzcom-exe

to the global environment.  That variable is bound 
to a string containing the full pathname for mzcom.exe.

If mzcom.exe is moved to another location, you should 
set either the PLTHOME or PLTCOLLECTS environment 
variables before loading MzCOM.

Evaluation thread
-----------------

The MzScheme evaluator runs in a Win32 thread created
when MzCOM is loaded.  If an expression kills the 
primary MzScheme thread, as in 

  (kill-thread (current-thread))

then the evaluator Win32 thread is also killed.  
When that happens, subsequent calls to Eval() will fail.

Contact us
----------

If you need more information on using MzCOM, please 
contact us at scheme@plt-scheme.org.

Acknowledgments
---------------

MzCOM was developed in response to a query by 
Andre Van Meulebrouck.  Andre also did extensive 
testing with Visual BASIC.