Click above to get retro games delivered to your door ever month!

 Loading DLLs dynamically at run time
------------------------------------------------------------------------------
 The previous sections discuss the implementation of DLLs which are to be
 statically linked to the main .EXE, so the module and function names of the
 DLLs and details of their functionality must be available and specified at
 compile and link time.

 An even more powerful feature of DLLs is the ability to dynamically load and
 execute new DLLs at program run time, with almost no prior knowledge of
 their name or functionality. This allows programs to be written to be
 extended at a later stage with completely new functionality, such as new
 database drivers or whole new modules such as a report writer or a backup
 option.

 The Windows 3.x API provides three functions to dynamically load DLLs,
 namely Loadlibrary(), GetProcAddress() and FreeLibrary().
 LoadLibrary() takes as a parameter the name of the DLL to load, and if the
 library is loaded successfully it returns a unique number, or handle, to
 identify the library for future operations. If the load fails, the value
 returned is an error code as defined in the standard WINDOWS.H or
 WINDOWS.INC files, and is always less than the HINSTANCE_ERROR value of 32
 which is also defined in WINDOWS.H. If a directory path is specified along
 with the DLL name, Windows just looks in that directory path, but if only a
 name is passed then it looks in the following locations:

 . In the directory from which the main .EXE was loaded (the load
   path).
 . In the current directory.
 . In the PATH environment variable paths.

 To obtain the address of exported functions in the DLL just loaded, the
 handle returned by LoadLibrary() and a pointer to the name of the required
 function are passed to the GetProcAddress() function. If the named function
 exists in the DLL then a pointer to the function code is returned, otherwise
 a null pointer is returned to indicate that the function does not exist or
 the DLL does not export a function with that name.

 Finally, before exiting the program, the function FreeLibrary() should be
 called with the library handle to free the memory and resources used by the
 DLL. The example programs in the \C\DLL\DYN subdirectory of the Blinker
 installation directory show how to create a Windows program and a DOS
 extended program which both dynamically load and execute the same Windows
 DLL. The relevant part of the Windows main program looks as follows:

 if ( (hLibInst = LoadLibrary (LibName)) > HINSTANCE_ERROR )
    {
    TestPtr = (TEST) GetProcAddress (hLibInst, FunName);
    if ( TestPtr )
       {
       wsprintf (msgbuf, "%s returned ", FunName);
       strcat (msgbuf, (*TestPtr) (1));
       WasOK++;
       }
    else
       wsprintf (msgbuf, "%s%s%s", FunName,
                      " does not exist in library ",  LibName);
    }
 else
    {
    if (hLibInst = 2)
       strcpy (msgbuf, "Unable to find ");
    else
       strcpy (msgbuf, "Error loading ");
    strcat (msgbuf, LibName);
    }

 /* Display the result */
 MessageBox (hwnd, msgbuf, "",
    MB_APPLMODAL | (WasOK ? MB_ICONINFORMATION :
    MB_ICONEXCLAMATION) | MB_OK);

 /* Free the library */
    if (hLibInst > HINSTANCE_ERROR)
       FreeLibrary (hLibInst);

 The Blinker DOS extender provides the same three functions as the Windows
 API for low level languages such as C, Pascal and Assembler, so the
 equivalent DOS extended program to dynamically load and execute a DLL looks
 almost identical, and behaves in exactly the same way. Please refer to the
 examples in the \C\DLL subdirectories for more details, or to the Windows
 SDK documentation on the DLL manipulation functions.

 Equivalent functions for high level languages are also provided by the
 extender, and these are discussed in more detail in the section entitled
 'Special considerations for all DLL code' in Chapter 3.