190 lines
5.0 KiB
Plaintext
190 lines
5.0 KiB
Plaintext
_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.
|