PRODUCT  :  Borland C++                           NUMBER  :  1394
  VERSION  :  1.0
       OS  :  OS/2
     DATE  :  October 25, 1993                         PAGE  :  1/2

    TITLE  :  Simple example of a DLL under OS/2





                   SIMPLE DLL EXAMPLE FOR OS/2 2.0.
                   ================================

  In OS/2 2.0. Dynamic Link Libraries are supported to allow the
  programmer to have the flexibility to load and unload code and
  data as it is needed by an executing application. The DLL file
  also allows separate executables to share the same code. This is
  also how the OS/2 2.0 Operating System functions. It is one large
  collection of DLL files.

  Static Linking with a DLL file.
  -------------------------------

  A)   Create the DLL with BC++.
       Must use TLINK.EXE Option /Tod for DLL file.

  B)   Create an import library to be used by the executable that
       uses the DLL file. Run IMPLIB.EXE on the DLL file to create
       and import library .LIB file.

  C)   Use the import library, created in step B, when linking the
       executable that uses the DLL. The import library can be
       linked to the same as any other library file.

  D)   Functions that that reside in the DLL will need be to
       prototyped with the _EXPFUNC  function modifier to notify
       the compiler that these functions will be exported from the
       DLL to be accessible by other modules.  Example:

       void _EXPFUNC MyDLLFunction (void);

  Summary: When the executable starts it will load the DLL file.
  The functions in the DLL will then be available to the
  executable. The DLL file must reside in a directory that is in
  the current LIBPATH environment variable in OS/2's CONFIG.SYS
  file.

  Run time load of a DLL file by an executable.
  ---------------------------------------------

  A)   Create the DLL with BC++
       Must use TLINK.EXE option /Tod for DLL file.













  PRODUCT  :  Borland C++                           NUMBER  :  1394
  VERSION  :  1.0
       OS  :  OS/2
     DATE  :  October 25, 1993                         PAGE  :  2/2

    TITLE  :  Use of DLL's in OS/2




  B)   In this situation the program has to "manually" load the DLL
       file.  This is accomplished by using the DosLoadModule() API
       function from the Control Program Interface API. The
       DosLoadModule() requires the name of the DLL file to load
       the DLL.

  C)   When the DLL file is loaded, in order for the executable
       program to actually call one of the DLL functions, you must
       first get the address of the DLL function with
       DosQueryProcAddr().  DosQueryProcAddr() takes as a
       parameter, the name of the function (as a string) returns
       the address of that function. A pointer to function is
       required to hold the DLL function.  You can now call the
       function via the pointer.  Example:

       DosLoadModule (errorBuf, sizeof (errorBuf), "MyDLL",
                      &hmod);
       // load the DLL
       DosQuerryProcAddress (hmod, 0, "MyDLLFunction",
                             (PPFN) &pfn);
       // get the address of the function into our pointer.
       pfn ();
       // call the function via the pointer

  D)   This method of loading the DLL file allows the executable
       program to unload the DLL file after it is done using the
       code that resides inside of it. This can be done with
       DosFreeModule(). ie.

       DosFreeModule (hmod);

  Summary: This method of DLL usage provides the executable with
  total control of when the DLL is in memory and when it's not. Of
  course if other executables use the DLL file then the DLL code
  could be left in memory even after our executable calls the
  DosFreeModule().


  DISCLAIMER: You have the right to use this technical information
  subject to the terms of the No-Nonsense License Statement that
  you received with the Borland product to which this information
  pertains.