Firebird is normally distributed as a single exe installation package which may be downloaded from http://www.firebirdsql.org. Currently, 2.5 is the most recent release. You should download the most recent 2.x installation package for 32-bit or 64-bit Windows as appropriate, and install it.
When run from the IDE, IBX for Lazarus should then automatically find and use the Firebird client DLL.
In order to use the example application, you need to ensure that the Firebird Aliases file contains a link to the example employee data.
-
For example, for Firebird 2.1, the pathname to the aliases file is
C:\Program Files\firebird\Firebird_2_1\aliases.conf
and it must contain the entry:
employee = C:\Program Files\firebird\Firebird_2_1\examples\empbuild\employee.fdb
-
For Firebird 2.5, the entry should be:
employee = C:\Program Files\firebird\Firebird_2_5\examples\empbuild\employee.fdb
Distributing the Firebird Client DLL with your Applications
When distributing an application that includes IBX for Lazarus, you must also include the Firebird Client Library or embedded Server (See Below). In the former case, a Firebird Server must also be available to host the database. However, this can and probably will be installed separately on the same or a remote server.
The simplest strategy is to install, in the same folder as your application is installed, the following Firebird files:
-
fbclient.dll
-
firebird.msg
-
firebird.conf
These are typically found in the “C:\Program Files\Firebird_2_x” folder and its “bin” subfolder (when installing from the standard Firebird distribution). Note: the three files must be in the same folder as the application executable if IBX is to find them.
Personal Database Applications
If your application is a Personal Database Application. That is, the database resides on the same system as your application, it is single user, intended to be accessible only to its owner, and a separate database login is seen as unnecessary, then the Firebird embedded server should be used when the application is deployed.
From IBX 1.4.0 onwards, the TIBLocalDBSupport component provides simplified management of Personal Databases.
The Firebird embedded server may be downloaded from http://www.firebirdsql.org as a single zip archive. The contents of this archive should be installed in the same folder as your application executable. IBX for Lazarus will then automatically find and load the embedded Firebird Server.
When using the Embedded Server and TIBLocalDBSupport is not in use, the IBDatabase object properties should be set as follows:
-
Database Name: Full pathname for the database file.
-
“user_name” parameter: SYSDBA
-
“password” parameter: masterkey
-
Logon Promt: false
If a Service API component is being used (these are on the Firebird Admin tab) then the properties of this component should be set as follows:
-
Server Name: empty
-
Protocol: Local
-
“user_name” parameter: SYSDBA
-
“password” parameter: masterkey
-
Logon Prompt: false
How IBX Finds the Firebird DLL
If the above instructions are followed then you should have no problem accessing Firebird from your Lazarus application. However, for debugging purposes and more advanced applications, it is useful to know how IBX for Lazarus finds the Firebird Client Library. IBX for Lazarus uses the following algorithm to locate the Firebird DLL. The algorithm terminates as soon as the library has been located:
| 1
|
When the Firebird Library is to be loaded, IBX first looks in the same folder as the application executable is located. It checks to see if fbembedded.dll (the embedded server DLL) is present here. If it is then this is loaded. If not then it checks to see if fbclient.dll is present. If so, then it is loaded. In the latter case, IBX also sets the FIREBIRD environment variable to the path to this folder, prior to loading the library. This has the effect of forcing the Firebird Client to look for the firebird.conf and firebird.msg files in the same folder. They must thus also be installed here. This is to ensure that the DLL uses the correct versions of these files. If the FIREBIRD environment variable is not set then the DLL will use the Windows registry to find the files. If another Firebird installation is present on the same system this may point to a different version of these files. |
| 2 |
If the FIREBIRD environment variable is set then the directory this points to is searched for the FB Client DLL and then then underlying "bin" directory |
| 3 |
IBX then uses the Windows Registry to locate the most recent Firebird installation. It opens the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Firebird Project\Firebird Server\Instances, and then reads the “Default Instance” string value. This is then assumed to be the full path Firebird installation. If the fbclient dll is present in this folder's “bin” subfolder, then the DLL is loaded. Note that in this case, the FIREBIRD environment variable is not set as the Firebird Client Library will also use the same registry entries to locate its support files. |
| 4 |
IBX now looks in the default installation folders for first Firebird 2.5 and then Firebird 2.1. These are <Program Files Folder>\Firebird\Firebird_2_x |
| 5 |
IBX then uses the Windows Path to search for and load fbclient.dll. |
| 6 |
If the DLL is still not found, then in quiet desperation, IBX will attempt to load the legacy InterBase gds32.dll again using the Windows Search Path. |
In practice, case 1 above should be used for deployed applications, whilst case 2 is the preferred approach for a development system. Cases 3 and 4 are really attempts to get something to work on a broken system.
Overridding the Firebird Client Library Search Algorithm
The Windows implementation also recognises the OnGetLibraryName event handler.
In your program, you can create an event handler for the OnGetLibraryName event defined in the IBIntf Unit. The event handler should be set in an initialization section and has the type:
procedure(var libname: string)
If present, then the event handler is called before the Firebird Library is loaded and must return the absolute path to Firebird Client Library DLL. IBX will attempt to load this DLL. If it fails then the error is reported but otherwise no further attempt is made. If the FIREBIRD environment variable needs to be set then this must be set by your event handler.