Remember, you can redirect the output of a command-line application to a text file with the > symbol:

tdump --ee mydll.dll > dump.txt

Using a DLLProc

As I mentioned earlier, any initialization code that the DLL needs to execute can be done in the DLL's main code block. That's easy enough, but what about finalization code? DLLs don't have initialization and finalization sections as other units do. You might dynamically allocate memory in the DLL's main code block, but where do you free it? The answer is a DLLProc. A DLLProc is a procedure that is called at certain times during the life of a DLL. I'll explain how to use a DLLProc in just a bit, but first let me tell you why DLLProc exists.

A DLL receives messages from Windows when it is loaded into memory and just before it is unloaded from memory. It also receives messages when a process attaches to or detaches from an already-loaded DLL (as in the case of several applications all using the same DLL). To get these messages, you create a procedure with a specific signature and assign the address of that procedure to the global variable DLLProc. A typical DLLProc procedure might look like this:

procedure MyDLLProc(Reason: Integer);
begin
  if Reason = DLL_PROCESS_DETACH then
    { DLL is unloading. Cleanup code here. }
end;

Just declaring a DLLProc procedure is not enough to ensure that the DLLProc will be used. You must also assign the address of the procedure to the DLLProc global variable. You do that in the DLL's main code block. For example:

begin
  DLLProc := @MyDLLProc;
  { More initialization code. }
end.

This code will be executed as soon as the DLL loads. The DLLProc is now installed and will be called automatically as processes attach and detach from the DLL or when the DLL unloads. Listing 19.2 shows the source code for a DLL that implements a DLLProc.

LISTING 19.2. A DLL UNIT THAT USES A DLLProc.

library TestDLL;
uses

  SysUtils,

  Classes,
  Forms,
  Windows;
var
  SomeBuffer : Pointer;
procedure MyDLLProc(Reason: Integer);
begin
  if Reason = DLL_PROCESS_DETACH then
    { DLL is unloading. Cleanup code here. }
    FreeMem(SomeBuffer);
end;
procedure SayHello(AForm : TForm);
begin
  MessageBox(AForm.Handle, `Hello From a DLL!',
    `DLL Message Box', MB_OK or MB_ICONEXCLAMATION);
end;
{ More DLL code here that uses SomeBuffer. }
exports
  SayHello;
begin
  { Assign our DLLProc to the DLLProc global variable. }
  DLLProc := @MyDLLProc;
  SomeBuffer := AllocMem(1024);
end.

As you might have surmised from Listing 19.2, the Reason parameter of the DLLProc procedure contains a value representing the reason that the DLLProc is being called. Table 19.1 lists the possible values of the Reason parameter.

TABLE 19.1. DLLProc Reason VALUES.

Value	Description
DLL_PROCESS_DETACH	The DLL is about to unload from memory.
DLL_THREAD_ATTACH	A process is attaching to the DLL.
DLL_THREAD_DETACH	A process is detaching from the DLL.

---

NOTE: Earlier in this section I said that a DLL will receive a message from Windows when the DLL is initially loaded into memory. It is reasonable to expect that when a DLL loads, the DLLProc is called with a Reason parameter equal to DLL_PROCESS_ATTACH. That doesn't happen, however. Windows defines a DLL_PROCESS_ATTACH message, but Object Pascal does not pass it on to the DLLProc. Instead, Object Pascal calls the DLL's main code block when the DLL_PROCESS_ATTACH message is received. Beca use the main block is called when DLL_PROCESS_ATTACH is received, it is not necessary for Object Pascal to pass that message on to the DLLProc.

---

The DLL_PROCESS_DETACH message is received only once, just before the DLL unloads from memory. (The DLL_THREAD_ATTACH and DLL_THREAD_DETACH messages might be received many times if a DLL is used by several processes. Processes can include applications, multiple threads in a single application, or other DLLs.) You can use a DLLProc, then, to perform any cleanup code required for the DLL.

Loading DLLs

Before you use a function or procedure in a DLL, you first have to load the DLL into memory. Loading DLLs at runtime can be accomplished in two ways, as follows:

• Static loading

• Dynamic loading

Both methods have their advantages and disadvantages. I'll explain the differences between static loading and dynamic loading next.

Static Loading

Static loading means that your DLL is automatically loaded when the application that calls the DLL is executed. To use static loading, you declare a function or procedure that resides in the DLL with the external keyword (more on that in the section "Calling Using Static Loading"). The DLL is automatically loaded when the application loads, and you call any functions or procedures exported from the DLL just as you would any other function or procedure. This is by far the easiest way to use code contained in a DLL. The disadvantage to this approach is that if a DLL that the program references is missing, the program will refuse to load.

Dynamic Loading

Dynamic loading means that you specifically load the DLL when needed and unload it when you are done with it. This type of DLL loading has its advantages and disadvantages, too. One advantage is that the DLL is in memory only as long as you need it, so you are making more efficient use of memory. Another advantage is that your application will load more quickly when using dynamic loading because not all the code needed to run the program is loaded when the application initially loads.

The primary disadvantage to using the dynamic loading approach is that it is a bit more work for you. First, you need to load the DLL with the Windows API function LoadLibrary. Then, when you are done with the DLL, you unload it with FreeLibrary. Further (and this is where the work comes in), you need to use the GetProcAddress function to obtain a pointer to the function or procedure you want to call. To say that this approach can be a tad confusing would be an understatement. The following section describes how to call procedures and functions in DLLs using both static and dynamic loading.

Calling Functions and Procedures Located in DLLs

The method you use to call a function or procedure in a DLL depends on whether the DLL was statically or dynamically loaded.

Calling Using Static Loading

Calling functions and procedures from DLLs that are statically loaded is simple. First the calling application must contain a declaration for the function or procedure. After that, you call the function or procedure as you do a regular function 
or procedure. To import a function or procedure contained in a DLL, use the external modifier in the function or procedure declaration. For example, given the SayHello procedure shown earlier, the declaration in the calling application would look like 
this:

procedure SayHello(AForm : TForm); external `testdll.dll';

The external keyword tells the compiler that the procedure can be found in a DLL (TESTDLL.DLL in this case). The actual procedure call looks no different than any other:

SayHello(Self);

After you have properly imported the function or procedure, you call it like any other function or procedure. This step presumes, of course, that t he procedure has been exported from the DLL as described earlier.

---

CAUTION: When you declare functions and procedures contained in a DLL, be sure you get spelling and capitalization right. This is one place in Object Pascal programming where capitalization counts! If you misspell or improperly capitalize a function or procedure name, you will get an exception at runtime and the application will refuse to load.

---

---

USING THE external KEYWORD

The external keyword has three flavors. Using external you can import a procedure or function in one of three ways:

• By actual name
  
• By ordinal value
  
• By renaming

The first way of importing, by actual name, is the method you have seen used up to this point. You simply declare the name of the function or procedure exactly as it appears in the DLL--for example,

procedure SayHello(AForm : TForm); external `testdll.dll';

The second way of importing, by ordinal value, requires you to specify the ordinal value of the function or procedure as exported from the DLL:

procedure SomeOrdinalProcedure;  external `testdll.dll' index 99;

In this case, I am importing the procedure that is exported from the DLL as index 99. I can name the procedure anything I want in the calling application as long as the signature matches that of the procedure in the DLL. I can name the procedure anything I want because the procedure is exported by ordinal value and not by the procedure name.
The third method, by renaming, enables me to import the procedure by it original name, but give the procedure a new name in the calling application. It looks like this:

procedure CoolProcedure; 
  external `testdll.dll' name `DoSomethingReallyCool';

Here I am importi ng a procedure called DoSomethingReallyCool and renaming it to CoolProcedure.

Of these three methods, the first, importing by name, is the most commonly used.

---

The trick in writing and using DLLs, then, is in getting the imports and exports right. Otherwise, there's nothing to it. Unless you need the flexibility that dynamic loading provides, you should almost always opt for static loading.

Calling Functions and Procedures Using Dynamic Loading

Calling functions and procedures in DLLs that are dynamically loaded isn't a lot of fun. It requires that you declare a pointer to the function or procedure in the DLL, and pointers to functions can be confusing. To illustrate, let's say you have a procedure in a DLL called SayHello (the SayHello procedure gets a workout in this chapter). It would look like this in the DLL's source code:

procedure SayHello(AForm : TForm);
begin
  MessageBox(AForm.Handle, `Hello From a DLL!',
    `DLL Message Box', MB_OK or MB_ICONEXCLAMATION);
end;

To call this procedure from your program, you first have to declare a type that describes the procedure:

type
  TSayHello = procedure(AForm : TForm);

Now that you've done that, you must load the DLL, use GetProcAddress to get a pointer to the procedure, call the procedure, and, finally, unload the DLL. Here's how the whole operation looks:

var
  DLLInstance : THandle;
  SayHello : TSayHello;
begin
  { Load the DLL. }
  DLLInstance := LoadLibrary(`testdll.dll');
  { Get the address of the procedure. }
  @SayHello := GetProcAddress(DLLInstance, `SayHello');
  { Call the procedure. }
  SayHello(Self);
  { Unload the DLL. }
  FreeLibrary(DLLInstance);
end;

As I said, loading a DLL dynamically is a bit more work. Still, when you need to load a DLL at runtime, that's the way you have to do it. Note that this code is pared down a bit for clarity. You will almost always add some error-checking code to ensure that the DLL loads correctly and that GetProcAddress returns a good address. Here's how the code looks with error checking code in place:

procedure TForm1.DynamicLoadBtnClick(Sender: TObject);
type
  TSayHello = procedure(AForm : TForm);
var
  DLLInstance : THandle;
  SayHello : TSayHello;
begin
  DLLInstance := LoadLibrary(`testdll.dll');
  if DLLInstance = 0 then begin
    MessageDlg(`Unable to load DLL.', mtError, [mbOK], 0);
    Exit;
  end;
  @SayHello := GetProcAddress(DLLInstance, `SayHello');
  if @SayHello <> nil then
    SayHello(Self)
  else
    MessageDlg(`Unable to locate procedure.', mtError, [mbOK], 0);
  FreeLibrary(DLLInstance);
end;

As you can see, you probably won't use dynamic loading of DLLs unless you absolutely have to.

Creating a DLL Project with the Object Repository

Creating a DLL in Delphi is accomplished through the Object Repository. (The Object Repository is covered on Day 8, "Creating Applications in Delphi."). To create a DLL project, follow these steps:

1. Choose File|New to display the Object Repository.

2. Double-click the DLL icon.

Were you expecting it to be more complicated than that? Delphi creates the DLL project and displays the Code Editor. The file in the edit window looks like this:

library Project2;
{ Important note about DLL memory management: ShareMem must be the
  first unit in your library's USES clause AND your project's (select
  View-Project Source) USES clause if your DLL exports any procedures or
  functions that pass strings as parameters or function results. This
  applies to all strings passed to and from your DLL--even those that
  are nested in records and classes. ShareMem is the interface unit to
  the DELPHIMM.DLL shared memory manager, which must be deployed along
  with your DLL. To avoid using DELPHIMM.DLL, pass string information
  using PChar or ShortString parameters. }



uses
  SysUtils,
  Classes;
begin
end.

Now you can begin adding code to the DLL. Be sure to add any exported procedure or function names to the exports section. Write any standalone functions or procedures that you need in your DLL. When you are finished adding code, you can choose Compile or Build from the Project menu to build the DLL.

---

COMMENTING THE DLL UNIT

I want to take a moment to explain the large comment block at the top of a DLL unit. This message is telling you that if your DLL has exported functions and procedures that take a long string type as a parameter or if your exported functions return a long string, you must do the following:

• Put ShareMem at the beginning of the uses list in both the DLL source and the calling application's main unit. Be sure that ShareMem comes before other units in the uses list.
  
• Ship the Borlndmm.dll file with your DLL. Notice that I said Borlndmm.dll and not Delphimm.dll, as the comments in the DLL code indicate. Borland changed the name of the memory manager DLL but neglected to change the comments generated when you create a new DLL unit. The comments are not completely misleading, however, because both Delphimm.dll and Borlndmm.dll are included with Delphi 4.

To avoid this requirement, just be sure that your DLL functions and procedures don't take any long string parameters and that your DLL functions don't return a long string. Instead of using a long string, you can use a PChar or a short string. For example, rather than use

procedure MyProcedure(var S : string);
begin
  { Procedure code here. }
end;

use this:

procedure MyFunction(S : PChar);
begin

{ Procedure code here. }

end;

This situation is easy enough to work around, so you should never have the need for Borlndmm.dll. You just need to be aware of the restrictions placed on using the long string in DLL functions and procedures. Note that you can use long strings in functions and procedures used within the DLL itself without the need for Borlndmm.dll. This applies only to exported functions and procedures.

---

---

NOTE: I always remove the comments about Borlndmm.dll when I create a new DLL. You can certainly leave them in the DLLs source code if you want. After you understand what the comments are saying, you won't need them anymore, so you might as well remove them.

---

The next three listings contain code that illustrates the concepts discussed thus far. Listing 19.3 contains a DLL that will be called statically from a calling application. Listing 19.4 contains a DLL that is called dynamically from the calling application and implements a DLLProc. Finally, Listing 19.5 contains a program that calls the two DLLs. The program has a form with four buttons that call various procedures in the two DLLs. The book's code (available at http://www.mcp.com/info) contains the sample programs for the projects in these three listings.

LISTING 19.3. TestDll.dpr.

library TestDLL;
uses
  SysUtils,
  Classes,
  Forms,
  Windows;
procedure SayHello(AForm : TForm);
begin
  MessageBox(AForm.Handle, `Hello From a DLL!',
    `DLL Message Box', MB_OK or MB_ICONEXCLAMATION);
end;
procedure DoSomething;
begin
  MessageBox(0, `This procedure was exported by ordinal.',
    `DLL Message Box', MB_OK or MB_ICONEXCLAMATION);
end;
procedure DoSomethingReallyCool;
begin
  MessageBox(0, `Something really cool.',
    `DLL Message Box', MB_OK or MB_ICONEXCLAMATION);
end;
exports
  SayHello,
  DoSomething index 99,
  DoSomethingReallyCool;
begin
end.

LISTING 19.4. DynLoad.dpr.

library TestDLL;
uses
  SysUtils,
  Classes,
  Forms,
  Windows;
procedure MyDLLProc(Reason: Integer);
begin
  if Reason = DLL_PROCESS_DETACH then
    { DLL is unloading. Cleanup code here. }
  Mes


sageBox(0, `DLL is unloading!',
    `DLL Message', MB_OK or MB_ICONEXCLAMATION);
end;
procedure SayHelloDyn(AForm : TForm);
begin
  MessageBox(AForm.Handle, `Hello From a DLL!' + #13 +
    `This DLL was loaded dynamically',
    `DLL Message', MB_OK or MB_ICONEXCLAMATION); 
end;
exports
  SayHelloDyn;
begin
  DLLProc := @MyDLLProc;
end.

LISTING 19.5. CallDllU.pas.

unit CallDLLU;

interface
uses
  Windows, Messages, SysUtils, Classes, Graphics, 
  Controls, Forms, Dialogs, StdCtrls;
type
  TForm1 = class(TForm)
    HelloBtn: TButton;
    OrdBtn: TButton;
    DynamicLoadBtn: TButton;
    NamedBtn: TButton;
    procedure HelloBtnClick(Sender: TObject);
    procedure OrdBtnClick(Sender: TObject);
    procedure DynamicLoadBtnClick(Sender: TObject);
    procedure NamedBtnClick(Sender: TObject);
  private
    { Private declarations }
  public
    { Public declarations }
  end;
var
  Form1: TForm1;
{ A procedure imported by name. }
procedure SayHello(AForm : TForm);
  external `testdll.dll';
{ A procedure imported by ordinal. }
procedure OrdinalProcedure;
  external `testdll.dll' index 99;
{ A procedure imported and renamed. }
procedure CoolProcedure;
  external `testdll.dll' name `DoSomethingReallyCool';
implementation
{$R *.DFM}
procedure TForm1.HelloBtnClick(Sender: TObject);
begin
  SayHello(Self);
end;
procedure TForm1.OrdBtnClick(Sender: TObject); 
begin
  OrdinalProcedure;
end;
procedure TForm1.NamedBtnClick(Sender: TObject);
begin
  CoolProcedure;
end;
procedure TForm1.DynamicLoadBtnClick(Sender: TObject);
type
  TSayHello = procedure(AForm : TForm);
var
  DLLInstance : THandle;
  SayHello    : TSayHello;
begin
  { Load the DLL. }
  DLLInstance := LoadLibrary(`DynLoad.dll');
  { If loading fails then bail out. }
  if DLLInstance = 0 then begin
    MessageDlg(`Unable to load DLL.', mtError, [mbOK], 0);
    Exit;
  end;
  { Assign the procedure pointer. }
  @SayHello := GetProcAddress(DLLInstance, `SayHelloDyn');
  { If the procedure was found then call it. }
  if @SayHello <> n


il then
    SayHello(Self)
  else
    MessageDlg(`Unable to locate procedure.', mtError, [mbOK], 0);
  { Unload the DLL. }
  FreeLibrary(DLLInstance);
end;
end. 

Using Forms in DLLs

Your DLLs can contain forms as well as code. There isn't much difference in the way the form is created compared to the way a form in an application is created. First, I'll explain how to write a DLL containing a form. After that, I'll talk about the special case of using an MDI form in a DLL.

Writing a DLL Containing a Form

Writing a DLL that contains forms is not much more difficult than writing a DLL that contains code only. I believe in learning by example, so in this section, you build a DLL containing a form. Perform these steps:

1. Create a new DLL project (remove the comments at the top of the DLL, if desired). Save the DLL as MyForms.dpr.

2. Choose File|New Form to create a new form for the DLL project. Add any components you want to the form.

3. Change the Name property of the new form to DLLForm. Save the form as DLLFormU.pas.

4. Switch back to the DLL source unit. Add a function called ShowForm that creates and shows the form. Use this code:

function ShowForm : Integer; stdcall;
var
  Form : TDLLForm;
begin
  Form := TDLLForm.Create(Application);
  Result := Form.ShowModal;
  Form.Free;
end;

5. Add an exports section to the DLL and export the ShowForm function. Here's how the exports section should look:

exports
  ShowForm;

6. Choose Project|Build MyForms to build the DLL. Save the DLL.

That's all there is to creating the DLL. Notice that the ShowForm function is declared with the stdcall keyword. This keyword tells the compiler to export the function using the standard call calling convention. Exporting the function as stdcall enables this DLL to be used by development environments other than Delphi.

New Term: Calling conventions specify how the compiler should pass arguments when calling functions and procedures. The five primary calling conventions are stdcall, cdecl, pascal, register, and safecall. See the "Calling Conventions" topic in the Delphi help file for more information on calling conventions.

Notice also that the return value of the DLL's ShowForm function is the value returned from the ShowModal function. This enables you to return some status information to the calling application. Listing 19.6 shows the code for the DLL.

LISTING 19.6. THE FINISHED DLL.

library MyForms;
uses
  SysUtils,
  Classes,
  Forms,
  DLLFormU in `DLLFormU.pas' {DLLForm};
function ShowForm : Integer; stdcall;
var
  Form : TDLLForm;
begin
  Form := TDLLForm.Create(Application);
  Result := Form.ShowModal;
  Form.Free;
end;
exports
  ShowForm;
  
begin
end.

Now the calling application can declare the ShowForm function and call the function. Listing 19.7 shows a Delphi application that calls the MyForms DLL.

LISTING 19.7. AN APPLICATION TO CALL THE MyForms DLL.

unit TestAppU;
interface
uses
  Windows, Messages, SysUtils, Classes, Graphics, 
  Controls, Forms, Dialogs, StdCtrls;
type
  TForm1 = class(TForm)
    Button1: TButton;
    procedure Button1Click(Sender: TObject);
  private
    { Private declarations }
  public
    { Public declarations }
  end;
var
  Form1: TForm1;
function ShowForm : Integer; stdcall;
  external `myforms.dll';
implementation
{$R *.DFM}
procedure TForm1.Button1Click(Sender: TObject);
begin
  ShowForm;
end;
end.

Notice that I used the stdcall keyword again when I declared the function in the calling application. Because the function was exported from the DLL with stdcall, it must also be imported w ith stdcall. You must always import a function or procedure with the same calling convention that you used to export it.

---

NOTE: If your Delphi DLLs are going to be used only by Delphi applications, you don't need to worry about using stdcall when exporting your functions and procedures. If, however, there is a chance that your DLL will be called from a wide range of applications, you should export your functions and procedures with stdcall.

---

Calling an MDI Form in a DLL

Having an MDI child form in a DLL is a special case. (MDI forms are discussed on Day 4, "The Delphi IDE Explored.") Let's say you have a Delphi application and the main form is an MDI form. If you try to use an MDI child form contained in a DLL, you will get an exception from VCL that says No MDI forms are currently active. "What? But I have an MDI form in my application!" Not according to VCL, you don't. Here's what happens.

When you attempt to show your MDI child form, VCL checks whether the Application object's MainForm property is valid. If the MainForm property is not valid, an exception is thrown. So what's the problem? The MainForm is valid, right? The problem is that the DLL also contains an Application object, and it is the DLL Application object's MainForm that is checked, not the application's MainForm. Because a DLL doesn't have a main form, this check will always fail.

The fix for this problem is to assign the DLL's Application object to the Application object of the calling application. Naturally, this will work only if the calling application is a VCL application. That's not the whole story, though. Before the DLL unloads, you must also set the DLL's Application object back to its original state. This enables the VCL memory manager to clean up any memory allocated for the DLL. It means that you have to store the DLL's Application object pointer in a global variable in the DLL so that it can be r estored before the DLL unloads.

Let's back up for a moment and review the steps required to show an MDI child form in a DLL:

1. Create a global TApplication pointer in the DLL.

2. Save the DLL's Application object in the global TApplication pointer.

3. Assign the calling application's Application object to the DLL's Application object.

4. Create and show the MDI child form.

5. Reset the DLL's Application object before the DLL unloads.

The first step is easy. Just place the following code near the top of your DLL's source unit:

var

DllApp : TApplication;

Be sure that you place the var keyword below the uses list in the DLL source unit.

Next, create a procedure that will do the TApplication switch and create the child form. The procedure will look like this:

procedure ShowMDIChild(MainApp : TApplication);
var
  Child : TMDIChild;
begin
  if not Assigned(DllApp) then begin
    DllApp := Application;
    Application := MainApp;
  end;
  Child := TMDIChild.Create(Application.MainForm);
  Child.Show;
end;

Examine this code for a moment. When you call this procedure, you will pass the Application object of the calling application. If the DllApp pointer has not yet been assigned, you assign the DLL's Application object to the temporary pointer. Then you assign the Application object of the calling application to the DLL's Application object. This check ensures that the Application object is set only once. After that, the MDI child form is created, passing the calling application's MainForm as the owner. Finally, the form is shown.

All that remains is to reset the DLL's Application pointer before unloading the DLL. You can use a DLLProc to restore the DLL's application pointer:

procedure MyDLLProc(Reason: Integer);
begin
  if Reason = DLL_PROCESS_DETACH then
    { DLL is unloadi


ng. Restore the Application pointer. }
    if Assigned(DllApp) then
      Application := DllApp;
end;

Remember, you saved the DLL's Application pointer earlier, so now you just restore it.

As you can see, placing an MDI child form in a DLL requires extra work, but it is certainly possible. The code for the book has an application project called MDIApp and a DLL project called MyForms. These two projects illustrate using an MDI form in a DLL.

Showing a DLL Form from a Non-Delphi Application

Calling a form from a non-VCL application requires a slightly different approach. What you have to do is create a standalone function in the DLL that is called by the calling application. This function can be called from any program provided you declare the function with stdcall. Within the function body, you then create and execute the form. The function looks like this:

function ShowForm : Integer; stdcall;

var

  Form : TMyForm;
begin
  Form := TMyForm.Create(Application);
  Result := Form.ShowModal;
  Form.Free;
end;

Notice that Application is passed for the form's parent. This is the DLL's Application object and serves as the owner of the form. Although I explicitly free the TMyForm object, it isn't strictly necessary because the DLL's Application object will delete the form if I neglect to.

Using Resources in DLLs

Sometimes it's convenient to have resources contained in a DLL. I've already mentioned internationalization and how a DLL can be used to make your program more easily portable to languages other than the one for which it was designed. Let's say you have an instructions screen for your application and that those instructions are contained in five strings in a DLL. The strings might be named IDS_INSTRUCTION1, IDS_INSTRUCTION2, and so on. You could load and display the strings like this:

LoadString(DllInstance, IDS_INSTRUCTION1, Buff, SizeOf(Buff));
InstructionLabel1.Caption :=


 Buff;

The first parameter of the LoadString function contains the instance handle of the module where the strings can be found. The second parameter contains the ID number of the resource to load. You could create DLLs that contain string resources in several different languages and simply load the appropriate DLL based on a user selection. The code might look like the following:

var
  DLLName : String;
begin
  case Language of
    laFrench : DllName := `french.dll';
    laGerman : DllName := `german.dll';;
    laSpanish : DllName := `spanish.dll';
    laEnglish : DllName := `english.dll';
  end;
  DllInstance := LoadLibrary(PChar(dllName));
end;

You only have to load the correct DLL; the rest of the code remains the same (assuming the strings have the same identifiers in each of the DLLs, of course). This is just one example of using resources contained in a DLL. You will find many uses for this technique.

Creating a Resource DLL

You can create a DLL that contains only resources, or you can mix code and resources in the same DLL. Placing resources in a DLL is much the same as adding resources to an application. To create a resource DLL, start a new DLL project and then add a line in the DLL to link the resources:

{$R RESOURC.RES}

That's all there is to creating a resource DLL. I discussed creating resource files on Day 8, so I won't go over that ground again here.

Putting the Resource DLL to Work

You must have the DLL's instance handle before you can access resources contained in the DLL. If your DLL contains resources only, you will load the DLL dynamically. If your DLL contains resources and code, you might choose to load the DLL statically. If you load the DLL statically, you will still have to call LoadLibrary to get the instance handle:

DllInstance := LoadLibrary(`resource.dll');

Now you can use the instance handle wherever required. The foll owing code loads a bitmap resource contained in a DLL into an Image component:

procedure TMainForm.FormCreate(Sender: TObject);
begin
  DLLInstance := LoadLibrary(`resource.dll');
  if DLLInstance <> 0 then begin
    Image.Picture.Bitmap.
      LoadFromResourceName(DLLInstance, `ID_BITMAP1');
    FreeLibrary(DLLInstance);
  end else
    MessageDlg(`Error loading resource DLL.',
      mtError, [mbOk], 0);
end;

Actually, there's not much left to say. To review, though, you know that you can load resource DLLs either statically or dynamically. Either way you have to use LoadLibrary to get the instance handle of the DLL. Don't forget to call FreeLibrary when you are done with the DLL or before your application closes.

---

NOTE: Using dynamic loading has the added advantage of allowing your application to load faster. In many cases you load the resource DLL only when it's needed and unload it when it's no longer needed. This results in your application using less memory than when the resources are contained in the executable file. The downside to static loading is that your users might see a slight pause when the resource DLL loads. Try to anticipate as much as possible and load the resource DLL when it is least likely to be noticed.

---

Remember JumpingJack from Day 8? The book's code has a version of JumpingJack that loads the bitmap, sound, and string resources from a DLL. Check out that program for an example of using resources in a DLL.

Summary

Using dynamic link libraries isn't as difficult as it might first appear. DLLs are a great way to reuse code. After you create a DLL, you can call it from any application that needs the functionality the code in that DLL provides. Placing VCL forms in a DLL and then calling those forms from a non-Delphi application is a powerful feature. This means that you can create forms that others can call from just about any type of Windows ap plication, whether it is an application written in OWL, MFC, straight C, Visual Basic, and so on. Using resources in DLLs is effective if you have a lot of resources in your application and you want to control when and where those resources are loaded.

Workshop

The Workshop contains quiz questions to help you solidify your understanding of the material covered and exercises to provide you with experience in using what you have learned. You can find the answers to the quiz questions in Appendix A, "Answers to the Quiz Questions."

Q&A

Q I have a relatively small program, and I don't see the need to use DLLs. Should I reevaluate my structure?

A Probably not. For small applications, DLLs are often not necessary. Any time you have classes that can be reused, you might as well use a DLL, but don't go out of your way to use DLLs in a small application.

Q I'm trying to use a function in a DLL, but I keep getting an error on the function declaration. The error says, Unsatisfied forward or external declaration. What am I doing wrong?

A You have forgotten the external keyword in your function declaration.

Q That GetProcAddress thing is a little weird. Do I have to use it to call functions and procedures in my DLL?

A No. Just use static loading and you won't have to worry about the LoadLibrary, GetProcAddress, and FreeLibrary functions.

Q My program compiles correctly, but at runtime I get an error that says The procedure entry point XXX cannot be found in the dynamic link library XXX.DLL. What's wrong?

A There are two possibilities that can lead to that error. First, you might have accidentally misspelled or improperly capitalized a function name when you declared the function in the calling application. Second, you might have forgotten to place the function name in the exports section of the DLL.

Q I have a form contained in a DLL, and my calling application is a Delphi program. The size of the DLL is pretty large. Is there any way I can reduce that?

A Unfortunately, no. This is where the power of programming in Delphi works against you a little. Both the calling application and the DLL contain some of the same VCL code. In other words, the code is being duplicated in both the .exe and the .dll. You just have to live with the larger overall program size if you are using forms in DLLs. You can eliminate this problem by using runtime packages. When you use runtime packages, both the calling application and the DLL can use code in the runtime packages.

Q I have a lot of wave files for my application. Right now they are contained in separate files, but I would like to place them all in one file. Is a resource DLL a good idea here?

A Absolutely. The only disadvantage is that if you need just one wave file, you must load the entire DLL. Still, by using dynamic loading, you can load and unload the DLL as required. The PlaySound function makes it easy to play sounds from a DLL.

Q I live in a French-speaking country. Why should I bother with internationalization of my program?

A It depends entirely on your target audience. If you know that your application will be distributed only in countries where French is the native language, you don't have to worry about internationalization. But if there is even the slightest possibility that your program could be marketed in other countries, you should plan from the beginning on international support. It's much easier to do it right the first time than to go back and fix it later.

Quiz

1. How do you load a DLL using static loading?

2. How do you load a DLL using dynamic loading?

3. How do you call a function or procedure from a DLL that has been loaded statically?

4. What steps do you have to take to ensure that a function or procedure in your DLL can be called from outside the DLL?

5. In the case of a DLL that has been dynamically loaded, can you unload the DLL at any time or only when the program closes?

6. What must you do to display a Delphi form contained in a DLL from a non-Delphi program?

7. What is the name of the keyword used to declare functions and procedures imported from a DLL?

8. How do you add resources to a DLL?

9. Does a resource DLL need to contain code as well as the resources?

10. Can a DLL containing resources be loaded statically (when the program loads)?

Exercises

1. Create a DLL that contains a procedure that displays a message box when called.

2. Create a calling application that will call the DLL in exercise 1.

3. Create a DLL containing a form and a calling application that will display the form.

4. Create a DLL that has two bitmap resources.

5. Create a program that will display on demand either bitmap resource in your new DLL. (Hint: Use a TImage component and the LoadFromResourceId method.)

6. Extra Credit: Write five DLLs, each of which contains the same strings but in different languages.

7. Extra Credit: Write a calling application that displays the strings you created in exercise 6. Enable the user to choose the language to be used in the application. Display the strings in the language ch osen.

---

© Copyright, Macmillan Computer Publishing. All rights reserved.