2003-04-08

Using DLLs and Causeway DOS Extender

Devore sent me this HOWTO for using DLLs and Causeway DOS Extender with Watcom C++. I thought it was generally interesting, so I decided to re-post it here:

It is recommended that you understand and familiarize yourself with the basic operation of Windows DLLs before using them with CauseWay under DOS. You should also study the DLL example code provided on the CauseWay distribution disk. The DLL example code file names begins with the characters DLL. The MAKEFILE file will build an example application using DLLs. Simply type:

WMAKE

after installing CauseWay, to build DLLTEST.EXE.

NOTE: The DLL startup code has changed in versions 10.5a, 10.6, and above of Watcom C++. Different files must be used with DLLs using these Watcom versions. Use DLLR105A.OBJ for register-based parameter passing and DLLS105A.OBJ for stack-based parameter passing. To use these files either edit CWSYSTEM.LNK so that "libfile dllstrts" and "libfile dllstrtr" become "libfile dlls105a" and "libfile dllr105a" or rename the DLLR105A.OBJ and DLLS105A.OBJ files to DLLSTRTR.OBJ and DLLSTRTS.OBJ.

DLL code should be compiled with the /s option to disable stack checking and the /bd option to generate DLL-suitable code. Specify a system type of CWDLLR for register-based parameter passing or CWDLLS for stack-based parameter passing.

A DLL file is a standard EXE file with the following requirement: The program start address should be an initialization and termination function, rather than a main program entry point. The entry address will be called twice: Once after loading to allow the DLL to perform initialization and once just prior to the DLL being unloaded from memory to allow it to clean up for termination. Entry conditions are: register EAX=0 for initialization and register EAX=1 for termination. An initialization code return value of EAX=0 indicates no errors. A code of any other value indicates an error has occurred and loading should be terminated. If an error condition is returned, it is up to the DLL to display an error message, CauseWay will simply report a load error. The entry address is a FAR call, so the initialization code should use a RETF to return control to the calling program.

A minimal DLL startup system is provided in the DLLSTRTR.OBJ (register- based) and the DLLSTRTS.OBJ (stack-based) files on the CauseWay distribution disk. Link with the NOD option to prevent the linker from using the standard startup code.