C++ Builder Tutorial

Creating a Dynamic Link Library

Introduction

A dynamic link library or DLL is a program that another program needs for its functionality. It usually has an extension of .dll although it could sometimes have another extension. DLLs are created for various reasons, the most regular of which allows different programs to "call" the same DLL.

Start Borland C++ Builder if you didn't yet. From the Standard toolbar, click the New button .
From the New Items dialog box, click DLL Wizard
Click OK.
On the DLL Wizard, click the C++ radio button and only the Use VCL check box
Click OK
To save the current project, on the main menu, click File -> Save All
To make things easier, from the Save Unit1 As dialog box, locate the common folder called Programs and display it in the Save In combo box.
Click the Create New Folder button, type DLLExercise and press Enter.
Double-click the new folder to display it in the Save In combo box. In the File Name edit box, change the name of the unit to DLLUnit and click Save.
Change the name of the project to DLLProject and click Save.
Examine and read the whole file, especially the commented section.

On top of the DLLEntryPoint() function, declare the needed functions and implement them as follows:

//---------------------------------------------------------------------------
#include <vcl.h>
#include <windows.h>
#pragma hdrstop
//---------------------------------------------------------------------------
#pragma argsused
//---------------------------------------------------------------------------
// This function is used to calculate the total area of a parallelepid rect
double BoxArea(double L, double H, double W);
// This function is used to calculate the volume of a parallelepid rectangle
double BoxVolume(double L, double H, double W);
//---------------------------------------------------------------------------
int WINAPI DllEntryPoint(HINSTANCE hinst, unsigned long reason, void* lpReserved)
{
    return 1;
}
//---------------------------------------------------------------------------
double BoxArea(double L, double H, double W)
{
    return 2 * ((L*H) + (L*W) + (H*W));
}
//---------------------------------------------------------------------------
double BoxVolume(double L, double H, double W)
{
    return L * H * W;
}
//---------------------------------------------------------------------------

Because the above functions cannot be accessed from outside the DLL, we will provide a function that can pass data from outside and to the external programs.
Declare such a function as follows:

//---------------------------------------------------------------------------
#include <vcl.h>
#include <windows.h>
#pragma hdrstop
//---------------------------------------------------------------------------
#pragma argsused
//---------------------------------------------------------------------------
// This function is used to calculate the total area of a parallelepid rect
double BoxArea(double L, double H, double W);
// This function is used to calculate the volume of a rectangular parallelepid
double BoxVolume(double L, double H, double W);
// This function is used to get the dimensions of a rectangular parallelepid
// calculate the area and volume, then pass the calculated values to the
// function that called it.
extern "C" __declspec(dllexport)void BoxProperties(double Length, double Height,
                                    double Width, double& Area, double& Volume);
//---------------------------------------------------------------------------
int WINAPI DllEntryPoint(HINSTANCE hinst, unsigned long reason, void* lpReserved)
{
    return 1;
}
//---------------------------------------------------------------------------
double BoxArea(double L, double H, double W)
{
    return 2 * ((L*H) + (L*W) + (H*W));
}
//---------------------------------------------------------------------------
double BoxVolume(double L, double H, double W)
{
    return L * H * W;
}
//---------------------------------------------------------------------------
void BoxProperties(double L, double H, double W, double& A, double& V)
{
    A = BoxArea(L, H, W);
    V = BoxVolume(L, H, W);
}
//---------------------------------------------------------------------------

To save your project, on the main menu, click File -> Save All.
To build the DLL, on the main menu, click Project -> Build DLLProject. During the building process, a dialog box will display the evolution. If there is a mistake somewhere, correct it. When everything goes fine, the dialog box will disappear.
To get the DLL ready for use, you will have to import it using the Implib utility. To do that, access the Command Prompt (it depends on the operating system you are using. In Win2000/XP you can click Start -> Programs -> Accessories -> Command Prompt). Type CD\ to remove whatever directory is displaying.
Display the directory where the DLL project was created. For this exercise, this would be:
C:\Programs\DLLExercise (this means you will type CD Programs\DLLExercise).
Once you are inside the folder of the DLL project, type implib DLLProject.lib DLLProject.dll and press Enter
When the DLL has been imported, type Exit and press Enter.
Save your project

A Project That Uses the DLL

Now we will create a project to use our DLL. Although our DLL can be used in any program, we will first implement it in a VCL application.

Start a new project with the default form.
To save the project, on the main menu, click File -> Save All.
Locate and display the same folder in which the DLL project was created.
Save the unit as Main and the project as ParaRect
Design the form as follows:
Besides the labels you can read, from top -> down, the form has five Edit controls named edtLength, edtHeight, edtWidth, edtArea, and edtVolume respectively. Then add two buttons named btnCalculate and btnExit.
To add the DLL to the current project, on the main menu, click Project -> Add To Project...
From the Add To Project dialog box, click DLLUnit and click OK

On the form, double-click the Exit button and implement its OnClick event as follows:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnExitClick(TObject *Sender)
{
    Close();
}
//---------------------------------------------------------------------------

On the form, double-click the Calculate button.

To call the DLL, change the file as follows:

//---------------------------------------------------------------------------
#include <vcl.h>
#pragma hdrstop

#include "Main.h"
//---------------------------------------------------------------------------
#pragma package(smart_init)
#pragma resource "*.dfm"
TForm1 *Form1;
//---------------------------------------------------------------------------
extern "C" __declspec(dllimport)void BoxProperties(double L, double H,
                                    double W, double& A, double& V);
//---------------------------------------------------------------------------
__fastcall TForm1::TForm1(TComponent* Owner)
    : TForm(Owner)
{
}
//---------------------------------------------------------------------------
void __fastcall TForm1::btnExitClick(TObject *Sender)
{
    Close();
}
//---------------------------------------------------------------------------
void __fastcall TForm1::btnCalcultateClick(TObject *Sender)
{
    double Length, Height, Width, Area, Volume;

    Length = edtLength->Text.ToDouble();
    Height = edtHeight->Text.ToDouble();
    Width = edtWidth->Text.ToDouble();

    BoxProperties(Length, Height, Width, Area, Volume);

    edtArea->Text = Area;
    edtVolume->Text = Volume;
}
//---------------------------------------------------------------------------

To save the project, on the main menu, click File -> Save All.
To execute the project, on the main menu, click Run -> Run.

Testing the DLL

At this time, our DLL is distributable. You can pass it to another programmer and give just small instructions on how to use it. As an example, we will call it from a console application.

Open Windows Explorer and display the content of the folder in which the DLL project was created.
On the right pane, click the file with .dll extension. Press and hold Ctrl. Click the file with extension .lib.
After making sure that both files are selected, on the main menu of Windows Explorer, click Edit -> Copy. Close Windows Explorer.
In C++ Builder, to start a new project, on the main menu, click File -> New.
On the New Items dialog box, click Console Wizard and click OK.
On the Console Wizard dialog box, click the C++ radio button, the Use VCL, and the Console Application check boxes. Click OK.
To save the current project, on the main menu, click File -> Save All.
Locate and display the Programs folder. double-click the Bcb folder to display it in the Save In combo box.
Click the Create New Folder button, type Consoler and press Enter
Double-click the new folder to display it in the Save In combo box.
As the Consoler folder displays in the Save In combo box, right-click the main empty area and click Paste
It will look like nothing happened. Click the arrow of the Files Of Type combo box and select All Files. Depending on how your computer is set up to display extensions, you should have two new files: DLLProject.dll and DLLProject.lib
Click the arrow of the Files Of Type combo box again and select C++ Builder Unit (*.cpp).
In the File Name, change the content to Main and click Save
To change the name of the project, type Consoler and click Save
To add the DLL to the current project, on the main menu, click Project -> Add To Project...
Click the arrow of the Files Of Type combo box and select Library File (*.lib)
Click the only file displaying: DLLProject
Click Open

To call the DLL, change the content of the Main.cpp file as follows:

//---------------------------------------------------------------------------
#include <iostream.h>
#include <vcl.h>
#pragma hdrstop
//---------------------------------------------------------------------------
extern "C" __declspec(dllimport)void BoxProperties(double L, double H,
                                    double W, double& A, double& V);
//---------------------------------------------------------------------------

#pragma argsused
int main(int argc, char* argv[])
{
    double Length, Height, Width, Area, Volume;

    cout << "Enter the dimensions of the box\n";
    cout << "Length: ";
    cin >> Length;
    cout << "Height: ";
    cin >> Height;
    cout << "Width: ";
    cin >> Width;

    BoxProperties(Length, Height, Width, Area, Volume);

    cout << "\nProperties of the box";
    cout << "\nLength:  " << Length;
    cout << "\nHeight:  " << Height;
    cout << "\nWidth:   " << Width;
    cout << "\nArea:    " << Area;
    cout << "\nVolumne: " << Volume;

    cout << "\n\nPress any key to continue...";
    getchar();
    return 0;
}
//---------------------------------------------------------------------------

To execute the project, on the main menu, click Run -> Run.


Previous	Copyright © 2001-2007 FunctionX, Inc.