Linking into Delphi (API interface)

Required files:

The following files are needed in order to link the DLL into Delphi programs:

TcAdsDll.dll is located in the Windows NT/2000 'System32' directory.

Optional for static linking:
NOTE: The declaration files TcAdsAPI.pas and TcAdsDEF.pas are included in the archive delphi_adsdll_api_units.zip.

To be able to compile the samples yourself you need:

In theory you can also work on the samples with a newer Delphi version. Additional adaptations to the new Delphi version often need to be made in the source code after the conversion of the project. These adaptations may be necessary, for example, due to a change in the compiler in the handling of the VARIANT data types or string data types.

Calling DLLs in Delphi

Before routines that are defined in the TcAdsDLL can be called, they must first be imported. There are two ways to carry out the import: one is to declare a procedure or function as external, the other is to call the Windows API directly. In both methods, the routine is not linked until the application's runtime. This means that the DLL is not required at compile time. By the same token, however, it means that the compiler cannot check whether the routine has been correctly imported.

Loading the DLL function statically

The simplest way to import a procedure or function is to declare it with the external directive:

procedure MyDllFunction; external
'MYLIB.DLL';

This declaration will load the MYLIB.DLL file when the program starts. As the program executes, the MyDllFunction identifier always refers to the same entry point in the same DLL.

You can insert the declaration of an imported routine directly into the program or unit in which it is called. In order to be able to maintain your programs more easily you should, however, collect all the external declarations into a separate "import unit". This unit will then contain the constants and the type definitions needed for the interface to the DLL (Delphi's Windows unit is a good example of this). Other modules that access the import unit can call all the routines that are declared within it.

Detailed information about external declarations and dynamic loading via calls to the Windows API are to be found in the Delphi online help.

The following rules should be observed when porting the TcAdsDLL to Pascal applications:

The most important TcAdsDLL.DLL declarations have been summarized in two units: TcAdsDEF.pas and TcAdsAPI.pas. If you want to load the functions statically, these units must be integrated into the Delphi application via a Uses clause.

Information about the Delphi memory manager in multi-threading applications

The Delphi memory manager uses ‘critical sections’ in order to ensure thread safety in multi-threading applications. However, the ‘critical sections’ are only used if a not so well-known system variable IsMultiThread is set to True. The IsMultiThread variable is defined in the 'System.pas' unit, which is used implicitly by all Delphi units.

The IsMultiThread variable must be set to True whenever the application or a referenced library uses multiple threads. Otherwise the application or the library is not 'thread safe'.
However, IsMultiThread is only implicitly set if the developer uses the Delphi TThread object in the application or in the library.

The Delphi memory manager assumes, for example, that the application is a single-thread application if:

Access to common resources is not locked in this case.

TcAdsDLL.dll uses its own threads, however. For this reason it must be ensured that the IsMultiThread variable is set to True as soon as TcAdsDLL is integrated into a Delphi application.

In the current versions of the TcAdsDEF.pas and TcAdsAPI.pas units, the IsMultiThread variable is set to True in the initialization section. However, it is the developer’s responsibility to ensure that the variable is always set at the correct point in time in a multi-threading application.