Index Readme Library Examples Utilities Changes License Support Register

 DataReel DLL Kit

Overview
DLL Kit Files
Building A DLL
Building A Project
Exporting Templates


Overview

The DataReel DLL kit is supplied as an additional component to the open-source library. The DLL kit includes all the necessary source code and makefiles to build WIN32 dynamic link libraries for all the currently supported WIN32 platforms. Dynamic linking is a mechanism where executables link to the library at run-time. Static linking is a process that links the library and executable together forming a standalone executable. Dynamic linking results in smaller executables and allows you to modify the library without re-compiling the executables. The primary disadvantages of dynamic linking are the complexities of developing the DLL itself and executable dependency issues that complicate binary distributions. Static and dynamic libraries speed up compile times considerably and allow you organize and manage large projects more efficiently.

Pre-compiled DLLs are available from glNET Software. Additionally glNET Software provides custom-built static libraries, WIN32 dynamic link libraries, and UNIX shared libraries. For more information about obtaining the DataReel DLL kit or pre-compiled libraries please contact:

glNET Software
P.O. Box 820314
South Florida, FL. 33082-0314
FAX: 413-622-7705
glnet@glnetsoftware.com
http://www.glnetsoftware.com


DLL Kit Files

The DataReel DLL kit is distributed as a zip archive and should be installed in the "dll" subdirectory of the source code distribution. The dll directory is composed of four subdirectories and includes WIN32 makefiles used to build DLLs. The "dll\include" and "dll\src" subdirectories contain a mirror copy of the source code distribution with DLL imports/exports for all library components that require external linkage. The DLL entry point, import/export macro, and dependencies are defined in the following files supplied with the DLL kit:

gxdlincs.h - Required include files referenced in the stdafx.h file.
stdafx.h - Standard system include files, and project specific include files.
gxdlcode.h - Defines the "GXDLCODE_API" DLL import/export macro.
stdafx.cpp - Source code file used to generate pre-compiled headers.
gxdlcode.cpp - Defines the entry point for the DLL application.

The "dll\release" and "dll\debug" subdirectories are used by the WIN32 DLL makefile to store release and debug versions of the DLL and all other compiled files.


Building A DLL

The MSVC dynamic link libraries have been built using the following compilers and tested on the subsequent WIN32 platforms:

Microsoft Visual C/C++ 4.2
Microsoft Visual C/C++ 6.0 SP3 
Windows 95A
Windows 95C
Windows 98 
Windows 98SE
Windows NT 4.0 SP4 Server
Windows NT 4.0 SP4 Workstation

The WIN32 DLL kit includes two makefiles used to compile the DLL and a VC template file used to generate application makefiles. The DLL makefiles included with the DLL kit do not require any modifications to build a WIN32 DLL. The following makefiles are required to build the DLL:

msvc.env - Common environment settings for the DLL and project makefiles.
msvc.mak - Makefile used to build the dynamic link library

All configurable parameters are contained in the msvc.env include file. When building DLLs within the MSVC IDE please refer to the msvc.env $(DEFMACS) variable for the required and optional preprocessor directives. To set the preprocessor directives for your active configuration press Alt-F7 and select the C++ tab. If you encounter any run-time errors after building a DLL within the MSVC IDE always check the compiler and linker set in the msvc.env and msvc.mak files against the MSVC IDE active configuration. NOTE: Using the C++ "new" and "delete" operators may not always be safe with the debug version of LIBCMT. By default the MSVC IDE will use LIBCMTD.LIB specified by the /MTd compiler flag. To avoid possible run-time errors be sure to use MSVCRTD.LIB by specifying the /MDd compiler flag.

To build the 32-bit debug and release libraries outside of the MSVC IDE execute the following commands:

C:\>CD C:\dreel410\dll
nmake -f msvc.mak FINAL=0
nmake -f msvc.mak clean
nmake -f msvc.mak FINAL=1
nmake -f msvc.mak clean

This will generate the "debug\gxcode32d.dll" debug DLL and the "release\gxcode32.dll" release DLL. The debug and release subdirectories will also contain a .lib file that must be linked to the project at compile time, a .exp file containing the DLL exports, a .pch file containing precompiled headers, and a .pdb program database file.

To build the 64-bit debug and release libraries outside of the MSVC IDE execute the following commands:

C:\>CD C:\dreel410\dll
nmake -f msvc.mak FINAL=0 64BITCFG=1
nmake -f msvc.mak clean
nmake -f msvc.mak FINAL=1 64BITCFG=1
nmake -f msvc.mak clean

This will generate the "debug\gxcode64d.lib" debug DLL and the "release\gxcode64.lib" release DLL. The debug and release subdirectories will also contain a .lib file that must be linked to the project at compile time, a .exp file containing the DLL exports, a .pch file containing precompiled headers, and a .pdb program database file.


Building A Project

A makefile template is supplied in the dll directory and is used to build applications using the dynamic library with compiler and linker options set in the compiler's ".env" file. Before using the template file you must set the absolute path to the DataReel library in the template file's $(GCODE_LIB_DIR) variable:

# Setup my path to the gxcode library
GCODE_LIB_DIR = #--> Set the absolute path here

To use the makefile template copy the template to the project directory and set the absolute path:

copy C:\dreel410\dll\template.vc C:\dreel410\examples.db\simple\Makefile
edit C:\dreel410\examples.db\simple\Makefile

# Setup my path to the gxcode library
GCODE_LIB_DIR = C:\dreel410

To build the project executable execute one of the following commands depending on your configuration:

C:\>CD C:\dreel410\examples.db\simple
nmake FINAL=0
nmake FINAL=1
nmake FINAL=0 64BITCFG=1
nmake FINAL=1 64BITCFG=1

The template file will link the project's object file to the .lib file in the dreel410\dll\debug directory if FINAL=0 or the dreel410\dll\release directory if FINAL=1.

NOTE: Before the executable can be launched you must install the DLL or set a path to the DLL. The DLL can be installed in the directory with the executable, in the Windows system directory, or be visible in any set path.


Exporting Templates

None of the core database or communication components use templates but a few non-essential general support classes use the generic binary search tree and linked-list, which generate warnings when the DLL is compiled. This is a known, non-fatal incompatibly with MSVC 6 noted in DataReel version 4. The long-term solution will be to re-code individual versions of the parameterized data structures directly for the data type being used.

The following technical note was found this note in the MSVC 6 documentation in reference to exporting template class and functions.

DLLs for Beginners, Debabrata Sarma, Microsoft Developer Support, November 1996

Exporting Template Class and Functions
Visual C++ does not support export of template class or functions. One reason for this arises from the notion of a template itself. A class template is an abstract representation of similar, but distinct, types. There is no code or data that exists to be exported until an instance of a class template is generated. One workaround (not recommended) is to declare the template class or functions with the declspec attribute in the DLL and instantiate all possible types in the DLL source. As you can see, this defeats the very purpose of using templates.

For the same reason, you cannot export the Standard Template Library (STL) classes or functions.


DataReel Copyright © 2001 glNET Software, All Rights Reserved