-----------------------------------------------------------------------------
Modifications to CLIPS source files for creation of a MS-Windows-based DLL
by Blake Buhlig
February 22, 1993

No copyrights exist on any files or modifications, except those belonging
to COSMIC and/or NASA, Microsoft, and Borland.
-----------------------------------------------------------------------------

This is a hastily prepared distribution, so it is very possible that I forgot
some necessary file.  If so, or if you have a question or suggestion, 
then you can contact me by my E-mail address (through December 1994, 
anyway):

Internet:     bb760597@longs.LANCE.ColoState.edu



INTRODUCTION
------------
        During the summer of 1992, I began implementation of a Windows-based 
expert system development tool using CLIPS v5.1.  The project, which was 
part of an undergraduate research program at Colorado State University,
involved interfacing CLIPS with C++ code.  It was envisioned that the expert 
system part of the development tool would be created with CLIPS, while the 
Microsoft Windows support would be designed with Borland C++ and Application
Frameworks.
        Due to various problems with statically-linking the CLIPS object code 
with my C++ code, I sought to create a Dynamic Link Library out of the CLIPS 
source code.  This package is the result of my efforts thus far. 




IMPORTANT WARNING!!!!        
---------------------
        It should be emphasized that THIS CODE IS NOT WELL-TESTED, and hence
any serious developer should be skeptical of every modification and creation
I have given here.  All I can offer is that what I have included here did
produce a functional CLIPS DLL that has helped advance my project.  However,
my project is not finished yet, which means that sometime in the
future I might discover some catastrophic problem that would force me to
somehow change or even scrap this approach altogether.
        I am releasing what I have here to help everyone else trying to
create a CLIPS DLL.  But if for some reason what I suggest doesn't work,
don't hold me accountable.





A POSSIBLY CATASTROPHIC BUG... 
------------------------------
        Before I go any further, let me point out a possible bug with this 
code that may discourage you from continuing.  I have noticed that I cannot 
execute more than one instance of my development tool at a time without
running in to some sort of UAE.  I haven't really investigated further 
because in my particular application, this is a fairly minor problem.  
However, your purpose for investigating the DLL approach might be to execute
multiple CLIPS processes simultaneously.  If this is the case, be aware
that the bug I discovered might be a problem with the DLL involving
multiple applications calling the DLL at once.




FILES
-----
        Without further delay, I will describe how you can make your own DLL.
First, note that I have included several modified files from the original 
CLIPS distribution:

        CONSTRCT.C   CONSTANT.H
        RETRACT.C    CONSTRCT.H
        ROUTER.C     ROUTER.H
        SYSDEP.C     SETUP.H
        SYSIO.C      SYSDEP.H

Some of these files were modified specifically to facilitate the DLL; others
were changed for other purposes.  In each file, I have tried to document
changes where appropriate.  If I were you, though, I would run a comparison
between the original CLIPS distribution and these files, and explicitly find
out what changes I did make.  When you are satisfied, replace the original
distribution files with these files.

The other files I have included add required extra support for the DLL.
Most of them will need to be modified to suit you own needs.  The files
are as follows:

        CLIPSDLL.MAK    USERFUNC.C
        CLIPSDLL.PRJ    DXCLPFNS.H
        CLIPSDLL.DSK    DXCLPFNS.C
        CLIPSDLL.DEF
        DLLSHELL.C

The MAK, PRJ, and DSK files are all Borland C++ specific compiler
configuration files.  If you are using MSC or some other compiler, you will 
need to make modifications.  Even if you are using Borland, you will 
probably still need to customize directory names.  If you don't use some
file that I mention below, or want to add your own files, make sure you add
these to the makefile or the project file.

The CLIPSDLL.DEF file is the module definition file for the DLL.  I think
it is compatible with all compilers.  The most important thing to know about
this file is that, in it, one must declare explicitly every CLIPS function 
to be called from the external language.  This includes every function in the
CLIPS Advanced Programming Guide.  I think I have already declared all 
documented functions, but you should check yourself just to be sure.
Note that macros are NOT be declared in this file.

The DLLSHELL.C file includes the required DLL entry and exit functions 
LibMain and WEP.  In my project, these are do-nothing functions.  One could
potentially put the InitializeCLIPS() call in LibMain, but I decided to call 
it from my C++ program.

The file USERFUNC.C declares and defines the UserFunctions() function.  In
my version, I have declared and defined two functions that allow the CLIPS
process to send messages to Windows.

The files DXCLPFNS.H and DXCLPDNS.C declare and define certain functions that
allow me to directly send and receive data to and from the DLL.  For example,
the function DefineCLIPSHWindow(HWND aHandle) lets me control a global
HWND variable declared in USERFUNC.C.  This variable gives the 
message-sending functions in USERFUNC.C the handle of the window I want to
have messages sent to.  Note that, since the functions in DXCLPFNS.C will
be called from an external program, I must (and did) declare them in the
CLIPSDLL.DEF file.


After you have modified all necessary files, transfer them into the same
directory as the rest of the CLIPS distribution, and build the DLL using
the makefile or project file.  Then test it out with your own program!



NOTES
-----
        There are some technical things I need to mention before you
start customizing the files and building the DLL:

        * Always #include <windows.h> before <clips.h>.  I'm not sure why,
          but if I do it the other way around, compiler errors always occur.

        * This DLL was built with the Large Memory Model.  If you do things
          differently, you may run into trouble with near, far, and huge
          pointers, and the like.

        * After building the DLL, make sure an import library was created
          for the DLL.  If not, use IMPLIB or some other tool to make one.
          Then, make sure you add the import library to your program's 
          makefile or project file.

        * If you get linkage errors when binding the DLL to your main program,
          check the .DEF file and insure that you added all functions that
          you are calling from the CLIPS DLL.


REGARDS
-------
        Well, that's all I can think of right now.  If you find something
wrong with the DLL, or if you just can't get things to work, then feel free
to drop me a message at the address I mentioned earlier.

        Good Luck...

