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

 CA-Clipper 5.x shared DLL example
------------------------------------------------------------------------------
 Due to the unique nature of the CA-Clipper 5.x run time library, its use of
 tokenised code and a symbol table, CA-Clipper requires some extra assistance
 to support CA-Clipper code in a DLL. As a result, there is only one type of
 CA-Clipper code DLL for all types of programs.

 The CA-Clipper runtime system is divided into a number of sub-systems, such
 as screen input / output and database drivers, which are structured so that
 only the code for the sub-systems actually needed by the program is linked
 into the final .EXE. When using a .DLL, however, it would be possible to
 create a small main function which simply calls another function in a .DLL,
 without referencing any of the sub-systems. If the tokenised code in the DLL
 then attempted to use one of the sub-systems which had not been linked, a
 run time error would result.

 It is therefore necessary to link an extra .OBJ file into the main .EXE file
 to ensure that all the sub-systems are included in the main program, and an
 extra .OBJ file into each .DLL file to interface to the main .EXE.
 BLXCLPnn.OBJ (for the .EXE) and BLDCLPnn.OBJ (for each .DLL), where nn
 represents the version of CA-Clipper, are provided in the OBJ subdirectory
 of the Blinker directory. They will therefore be found automatically by
 Blinker from the OBJ environment variable if a normal installation was
 performed.
 The protected mode library BLXCLPnn should not be included in the link file
 for the DLL, as it it is not required. Neither should CA-Clipper's standard
 libraries, such as CLIPPER, EXTEND, TERMINAL and DBFNTX. To ensure that this
 is the case, check that they do not appear in the DLL link script file, or
 any included scripts, and also include the link script command NODEFLIB to
 prevent any default libraries from being linked into the DLL.

 Due to the run time operation of the CA-Clipper symbol table, unresolved
 externals while linking a DLL can be ignored and overidden, using the
 BLINKER EXECUTABLE NODELETE command, provided the functions will exist in
 the main EXE or another DLL by the time the code calling that function is
 actually executed. This practice is not recommended in live programs as it
 will result in run time errors if the functions are not found, but it can be
 useful during testing or while building a DLL.

 For example, to create a CA-Clipper 5.3 test program and DLL using the
 example program in the \CLP\DLL\STC subdirectory of the Blinker installation
 directory, compile the .PRG files as normal.

 CLIPPER t -m -n            Normal compile for main program
 CLIPPER d -m -n            Normal compile for a DLL

 Now create a separate link script file for the DLL, including an export
 definition for the function to be exported, and link the DLL. Then use an
 import librarian such as BLILIB (see the section `The BLILIB import
 librarian' in Chapter 4) to create an import library which can be linked
 with the calling program:

 # D.LNK to create D.DLL
 OUTPUT d                   # The output file name
 FILE D                     # List .OBJs here
 FILE bldclp53              # .OBJ file for each .DLL
 DEFBEGIN                   # Module definition commands
    LIBRARY  d              # Indicate a DLL
    EXETYPE  WINDOWS 3.1    # It is for Windows 3.1 and above
    EXPORTS                 # Export the following symbols
       STATTEST             # Export STATTEST by name
 DEFEND                     # End module definition commands
 NODEFLIB                   # Ensure no default libraries
 BLINKER @D                 # Link the .DLL
 BLILIB /ID d /OL d         # Create the import library

 Finally create the main link file to use the special .OBJ file and the
 generated import library instead of linking the D.OBJ file directly:

 # T.LNK to create T.EXE
 BLI EXECUTABLE EXTENDED    # Create DOS extended program
 OUTPUT t                   # The output file name
 FILE test                  # List .OBJs here
 FILE blxclp53              # .OBJ file for main .EXE
 LIB d                      # The import library
 LIB blxclp53               # Blinker protected mode library
 BLINKER @T

 This should now have created T.EXE which will load and execute the code in
 D.DLL.

 By including the file BLXCLP53.OBJ in the main program, all of the
 CA-Clipper run time will be included in the main .EXE file, causing an
 increase in size for small programs. It will, however, ensure that any
 CA-Clipper code can be placed in the DLLs associated with the main program.

 The file CLDLLEXT.PRG in the \CLP subdirectory of the Blinker installation
 directory can also be modified, compiled and linked into the main program to
 force some optional parts of the Clipper runtime library into the main .EXE
 file if they are required.

 Please refer to the Windows online help file BLINKER.HLP for the latest
 information on creating CA-Clipper code .DLLs, and for details on how to
 minimise the extra overhead being linked into the main program.