Delphi FireDac Connection - Felix John COLIBRI.

• abstract : setting up a FireDac connection : using Delphi code, using the FdDrivers.Ini and FdConnectionDefs.Ini files at design time and run time. The Firedac Connection architecture
  
• key words : FireDac, FireBird, FdDrivers.Ini, FdConnectionDefs, tFdConnection, tFdPhysIbDriverLink, Uml Class Diagrams
  
• software used : Windows XP Home, Windows 2010 64 bit, Delphi 5, Delphi 6, Delphi Xe3
  
• hardware used : Pentium 2.800Mhz, 512 M memory, 140 G hard disc, cloud server, 2.4 Ghz, 7 GB
  
• scope : Delphi 5 to Delphi 10 Seatle
  
• level : Delphi developer
  
• plan :
  
  • Connection Using FireDac
    
  • FireDac connection using code
    
  • Using FdDrivers.Ini and FdConnectionDefs.Ini
    
  • The FireDac Connection UML Class diagrams
    
  • Download the Sources
    

1 - Connection Using FireDac

This article presents

• a first example using code only technique
  
• the FdDrivers.Ini and FdConnectionDefs.Ini files
  
• the UML class diagram of the involved components
  

2 - FireDac connection using code

2.1 - The required information

• driver information
  
• database specific information
  

2.2 - tFdPhysIbDriverLink

There is such a driver link for each supported Sql Engine:

For Interbase / Firebird, the fields required are:

• BaseDriverId is a predefined ReadOnly name, 'IB' for the FireBird tFdIbDriverLink
  
• DriverId is an identifier which will be used by the tFdConnection to find its driver information
  
• VendorHome and VendorLib specify the location and name of the FireBird client .DLL
  

• the client driver is in the FireBird intallation folder

  

• and initialisation by code looks like

  With ADPhysIBDriverLink1 Do Begin   // BaseDriverId:= 'IB'; ReadOnly   DriverId:= 'FB25';   VendorHome := 'C:\Program Files\Firebird\Firebird_2_5';    VendorLib := 'fbclient.dll'; End; // with ADPhysIBDriverLink1

  
  

• the VendorHome is the path the Firebird's home, not to the BIN\ where the FbClient.Dll is stored. Specifying the bin\ path works also
  
• we can also specify the full file name in VendorLib

  With ADPhysIBDriverLink1 Do Begin   DriverId:= 'FB25';   VendorLib:= 'C:\Program Files\Firebird\Firebird_2_5\bin\fbclient.dll'; End; // with ADPhysIBDriverLink1

  
  

• there are two "Program Files" folders:

  

• Firebird was installed in the default (64 bit) folder, but the Firebird install contains a Wow64 bit folder where the 32 bit FbClient.Dll lives:

  
  

2.3 - The tFdConnection

2.3.1 - DriverId and Params

• DriverId is the name of a tFdPhysIbDriverLink.DriverId. In our case this is 'FB25'
  
• Params contains the other parameters:
  
  • Server is the Ip address of the Sql Server
    
  • Database is the path and file name of the database file
    
  • User_Name and Password are the login parameters
    

Please note that

• DriverId has the same value as tFdPhysIbDriverLink.DriverId
  
• this name can also be specified in the Params property. In fact, specifying DriverId adds the Params value 'DriverId=FB25' to the Params list
  
• if hardcoding those values bothers you, you still can
  
  • stuff the parameters in some .Txt file
    
  • use Params.LoadFromFile to load them
    

2.4 - Using the Object Inspector

3 - Using FdDrivers.Ini and FdConnectionDefs.Ini

3.1 - The .INI files

• contain the same information
  
• are stored outside of the program, avoiding to hardcode the information in the code or the .DFM
  

• fdDrivers.INI which specifies drivers information
  
• fdConnectionDefs.INI which specifies database informations
  

As usual, it is a good idea to make a safety copy of those files before starting to modify them.

3.2 - Location of the .INI files

• for use at designe time, in the \Delphi\BIN\ folder
  
• for use at run time
  
  • in the folder of the application's .EXE
    
  • in the folder specified by the Registry

    

  • in a folder specified by the FdManager.DriverDefFileName and FdMaager.ConnectionDefFileName
    

For the 64 bit Windows, the FireDac components were installed using the Xe3 .ZIP, and the default XE3 folder was chosen to nest those components

• here are the FireDac .INI files

  

• and the registry entries are

  
  

3.3 - fdDrivers.INI

The file used for this article, which is in the downloadable .ZIP is

where

• FB25 is used on a 32 bit Vista PC
  
• FB25_64_BIT_PC_32_BIT_TARGET is for 32 bit .EXE compiled on a 64 bit Windows
  

• the first section is a section defining the text encoding
  
• if you use a file with only one section

  [FB25] BaseDriverID=IB VendorLibWin32=C:\Program Files\Firebird\Firebird_2_5\bin\fbclient.dll

  when you connect the database, you will get an error

  

  Adding any section, even a bogus one, will open the connection without any problem

  [bogus] [FB25] BaseDriverID=IB VendorLibWin32=C:\Program Files\Firebird\Firebird_2_5\bin\fbclient.dll

  
  

3.4 - FdConnectionDefs.INI

• the Tcp / Ip address
  
• the database path and file name
  
• the User / Password login
  

The ConnectionDefs_sample.INI contains a couple of other definitions (Sql Server, Oracle, ASA, Postgres etc)

And here is our own FdConnectionDefs.Ini:

3.4.1 - Using ConnectionDefs

	drop a tFdConnection on the form
	set its COnnectionDefName to Ib_Demo
	uncheck LoginPrompt
	check Connected

• the DriverId Params route and the ConnectionDefName route are exclusive: specifying DriverId clears ConnectionDefName and vice versa
  

• there is no direct tFdConnection property specifying the FdDriverLink
  
• it turns out that
  
  • our Ib_demo section specifies
    
    • the Sql engine : BaseDrvierId is IB
      
    • the DriverId, FB25
      
  • to find the FireBird client .DLL, FireDac
    
    • uses the FdManager singleton
      
    • the FdManager contains the name of the FdDrivers.Ini
      
    • this .Ini specifies where the FireBird client .Dll is located
      
    • when the connection is opened, the driver is loaded using LoadLibrary
      

3.4.2 - tFdConnection.ConnectionDefName

4 - The FdConnection component editor

We can then

• either select the ConnectionDef

  

  and we can test the connection

• or the DriverId

  

  and we have to manually fill the required values
  

5 - The Firedac Connection Demo

A couple of features are worth mentionning:

• the systematic use of Interfaces to get the connection

  Var l_i_fd_physical_connection: IADPhysConnection;   ADPhysManager.ConnectionDefs.Storage.FileName := '$(ADHOME)\DB\ADConnectionDefs.ini';   ADPhysManager.Open;   // -- create the physical connection using one of the ConnectionDef   ADPhysManager.CreateConnection('DbDemos', l_i_fd_physical_connection);   l_i_fd_physical_connection.Open;   l_i_fd_physical_connection.Close;   l_i_fd_physical_connection := Nil;

  
  

• the average FireDac application usually imports many FireDac units:

  Uses Windows ...   uADGUIxIntf, uADGUIxFormsWait, uADStanIntf, uADCompGUIx,   uADPhysIB, uADStanOption, uADStanError, uADPhysIntf, uADStanDef,   uADStanPool, uADStanAsync, uADPhysManager, uADCompClient, uADStanParam,   uADDatSManager, uADDAptIntf, uADDAptManager, uADCompDataSet,   uADGUIxFormsfLogin, uADGUIxFormsfError

• in this example, we tried to add as few units as possible
  
  • we first imported uAdPhysIntf
    
  • the code compiled, but trying to open the connection triggered an exception about a missing standard definition factory :

    

  • fianlly, the physical IB driver factory was missing:

    
    

  In the end, we only had to import 3 FireDac units

  Uses ...     , uAdPhysIntf     , uAdStanDef     , uADPhysIB     ;

  This is of no concern to the application developper, but is a good indication of the degree of information hiding achieved by the FireDac library.
  

6 - The FireDac Connection UML Class diagrams

6.1 - The FdConnection Classes

6.2 - The Physical Driver Classes

Please note that

• there is a PhysManagerObj global variable which is a singleton (it is even in the Interface)
  
• in the tPhysDriverLink.Create constructor, each physical driver link registers itself in the physical manager list
  
• whenever a client library must be loaded, the singleton is used to locate the relevant physical driver link and load the .DLL
  

7 - Download the Sources

• firedac_connection_firebird_databases.zip: the two Firebird Databases used by our code (185 K)
  
• firedac_connection_by_code.zip: connection using Delphi code (6 K)
  
• firedac_connection_using_inis.zip: connection using the .INI files (6 K)
  
• firedac_connection_using_interfaces.zip: connection using Interfaces (6 K)
  

• the main program (.DPR, .DOF, .RES), the main form (.PAS, .DFM), and any other auxiliary form
  
• any .TXT for parameters, samples, test data
  
• all units (.PAS) for units
  

• are self-contained: you will not need any other product (unless expressly mentioned).
  
• for Delphi 6 projects, can be used from any folder (the pathes are RELATIVE)
  
• will not modify your PC in any way beyond the path where you placed the .ZIP (no registry changes, no path creation etc).
  

• create or select any folder of your choice
  
• unzip the downloaded file
  
• using Delphi, compile and execute
  

The Pascal code uses the Alsacian notation, which prefixes identifier by program area: K_onstant, T_ype, G_lobal, L_ocal, P_arametre, F_unction, C_lass etc. This notation is presented in the Alsacian Notation paper.
The .ZIP file(s) contain:

• the main program (.DPROJ, .DPR, .RES), the main form (.PAS, .ASPX), and any other auxiliary form or files
  
• any .TXT for parameters, samples, test data
  
• all units (.PAS .ASPX and other) for units
  

• are self-contained: you will not need any other product (unless expressly mentioned).
  
• will not modify your PC in any way beyond the path where you placed the .ZIP (no registry changes, no path outside from the container path creation etc).
  

• create or select any folder of your choice.
  
• unzip the downloaded file
  
• using Delphi, compile and execute
  

The Pascal code uses the Alsacian notation, which prefixes identifier by program area: K_onstant, T_ype, G_lobal, L_ocal, P_arametre, F_unction, C_lass etc. This notation is presented in the Alsacian Notation paper.

Please note

• you can download the .ZIP containting the Mastapp and Employee database
  
• you must adjust the pathes and database file names to the pathes of the databases you want to connect to
  
• those changes must be performed
  
  • in the code connection for the first .ZIP
    
  • in both the FireDac installation and the .EXE folder .INIs. Our .INI work for a database folder at the same level as the project folders
    

• please tell us at fcolibri@felix-colibri.com if you found some errors, mistakes, bugs, broken links or had some problem downloading the file. Resulting corrections will be helpful for other readers
  
• we welcome any comment, criticism, enhancement, other sources or reference suggestion. Just send an e-mail to fcolibri@felix-colibri.com.
  
• or more simply, enter your (anonymous or with your e-mail if you want an answer) comments below and clic the "send" button

  Name :
  E-mail :
  Comments * :

• and if you liked this article, talk about this site to your fellow developpers, add a link to your links page ou mention our articles in your blog or newsgroup posts when relevant. That's the way we operate: the more traffic and Google references we get, the more articles we will write.
  

8 - The author