ViewVC Help
View File | Revision Log | Show Annotations | Download File | View Changeset | Root Listing
root/public/ibx/trunk/doc/readme.windows.xhtml
(Generate patch)

Comparing ibx/trunk/doc/readme.windows.xhtml (file contents):
Revision 36 by tony, Fri Mar 13 10:26:52 2015 UTC vs.
Revision 37 by tony, Mon Feb 15 14:44:25 2016 UTC

# Line 1 | Line 1
1   <?xml version="1.0" encoding="UTF-8"?>
2 < <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN" "http://www.w3.org/Math/DTD/mathml2/xhtml-math11-f.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><!--This file was converted to xhtml by LibreOffice - see http://cgit.freedesktop.org/libreoffice/core/tree/filter/source/xslt for the code.--><head profile="http://dublincore.org/documents/dcmi-terms/"><meta http-equiv="Content-Type" content="application/xhtml+xml; charset=utf-8"/><title xml:lang="en-US">- no title specified</title><meta name="DCTERMS.title" content="" xml:lang="en-US"/><meta name="DCTERMS.language" content="en-US" scheme="DCTERMS.RFC4646"/><meta name="DCTERMS.source" content="http://xml.openoffice.org/odf2xhtml"/><meta name="DCTERMS.creator" content="Tony Whyman"/><meta name="DCTERMS.issued" content="2011-05-03T15:13:51" scheme="DCTERMS.W3CDTF"/><meta name="DCTERMS.contributor" content="Tony Whyman"/><meta name="DCTERMS.modified" content="2015-02-25T12:50:45.461690519" scheme="DCTERMS.W3CDTF"/><meta name="DCTERMS.provenance" content="" xml:lang="en-US"/><meta name="DCTERMS.subject" content="," xml:lang="en-US"/><link rel="schema.DC" href="http://purl.org/dc/elements/1.1/" hreflang="en"/><link rel="schema.DCTERMS" href="http://purl.org/dc/terms/" hreflang="en"/><link rel="schema.DCTYPE" href="http://purl.org/dc/dcmitype/" hreflang="en"/><link rel="schema.DCAM" href="http://purl.org/dc/dcam/" hreflang="en"/><style type="text/css">
2 > <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN" "http://www.w3.org/Math/DTD/mathml2/xhtml-math11-f.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><!--This file was converted to xhtml by LibreOffice - see http://cgit.freedesktop.org/libreoffice/core/tree/filter/source/xslt for the code.--><head profile="http://dublincore.org/documents/dcmi-terms/"><meta http-equiv="Content-Type" content="application/xhtml+xml; charset=utf-8"/><title xml:lang="en-US">- no title specified</title><meta name="DCTERMS.title" content="" xml:lang="en-US"/><meta name="DCTERMS.language" content="en-US" scheme="DCTERMS.RFC4646"/><meta name="DCTERMS.source" content="http://xml.openoffice.org/odf2xhtml"/><meta name="DCTERMS.creator" content="Tony Whyman"/><meta name="DCTERMS.issued" content="2011-05-03T15:13:51" scheme="DCTERMS.W3CDTF"/><meta name="DCTERMS.contributor" content="Tony Whyman"/><meta name="DCTERMS.modified" content="2016-02-12T13:53:24.498085572" scheme="DCTERMS.W3CDTF"/><meta name="DCTERMS.provenance" content="" xml:lang="en-US"/><meta name="DCTERMS.subject" content="," xml:lang="en-US"/><link rel="schema.DC" href="http://purl.org/dc/elements/1.1/" hreflang="en"/><link rel="schema.DCTERMS" href="http://purl.org/dc/terms/" hreflang="en"/><link rel="schema.DCTYPE" href="http://purl.org/dc/dcmitype/" hreflang="en"/><link rel="schema.DCAM" href="http://purl.org/dc/dcam/" hreflang="en"/><style type="text/css">
3          @page {  }
4          table { border-collapse:collapse; border-spacing:0; empty-cells:show }
5          td, th { vertical-align:top; font-size:12pt;}
# Line 14 | Line 14
14          .Heading_20_1 { font-size:115%; margin-bottom:0.0799in; margin-top:0in; font-family:Arial; writing-mode:page; font-weight:bold; }
15          .Heading_20_2 { font-size:14pt; margin-bottom:0.0835in; margin-top:0.1665in; font-family:Arial; writing-mode:page; font-style:italic; font-weight:bold; }
16          .P1 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; font-style:normal; }
17 <        .P10 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; }
18 <        .P11 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; }
19 <        .P12 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; }
17 >        .P10 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Courier New; writing-mode:page; margin-left:0.5in; margin-right:0in; text-indent:0in; }
18 >        .P11 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; margin-left:0in; margin-right:0in; text-indent:0in; }
19 >        .P12 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; margin-left:0in; margin-right:0in; text-indent:0in; font-style:normal; }
20          .P13 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; }
21 <        .P14 { font-size:14pt; font-style:normal; font-weight:bold; margin-bottom:0.0835in; margin-top:0.1665in; font-family:Arial; writing-mode:page; }
22 <        .P15 { font-size:12pt; font-family:Times New Roman; writing-mode:page; }
23 <        .P2 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; }
24 <        .P3 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; margin-left:0.5in; margin-right:0in; text-indent:0in; }
25 <        .P4 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Courier New; writing-mode:page; margin-left:0.5in; margin-right:0in; text-indent:0in; }
26 <        .P5 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Courier New; writing-mode:page; margin-left:0.5in; margin-right:0in; text-indent:0in; font-style:normal; }
27 <        .P6 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Courier New; writing-mode:page; margin-left:0.5in; margin-right:0in; text-indent:0in; }
28 <        .P7 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; margin-left:0in; margin-right:0in; text-indent:0in; }
29 <        .P8 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; margin-left:0in; margin-right:0in; text-indent:0in; font-style:normal; }
30 <        .P9 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; }
21 >        .P14 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; }
22 >        .P15 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; }
23 >        .P16 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; }
24 >        .P17 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; }
25 >        .P18 { font-size:14pt; font-style:normal; font-weight:bold; margin-bottom:0.0835in; margin-top:0.1665in; font-family:Arial; writing-mode:page; }
26 >        .P19 { font-size:12pt; font-family:Times New Roman; writing-mode:page; }
27 >        .P2 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; font-style:normal; }
28 >        .P3 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; font-style:normal; }
29 >        .P4 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; }
30 >        .P5 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; }
31 >        .P6 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; }
32 >        .P7 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; margin-left:0.5in; margin-right:0in; text-indent:0in; }
33 >        .P8 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Courier New; writing-mode:page; margin-left:0.5in; margin-right:0in; text-indent:0in; }
34 >        .P9 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Courier New; writing-mode:page; margin-left:0.5in; margin-right:0in; text-indent:0in; font-style:normal; }
35          .Standard { font-size:12pt; font-family:Times New Roman; writing-mode:page; }
36          .Text_20_body { font-size:12pt; font-family:Times New Roman; writing-mode:page; margin-top:0in; margin-bottom:0.0835in; }
37          .Table1 { float:none; }
# Line 35 | Line 39
39          .Bullet_20_Symbols { font-family:OpenSymbol; }
40          .Internet_20_link { color:#000080; text-decoration:underline; }
41          .T1 { font-style:normal; }
42 <        .T2 { font-style:italic; }
42 >        .T2 { font-style:normal; }
43 >        .T3 { font-style:normal; }
44 >        .T4 { font-style:italic; }
45          <!-- ODF styles with no properties representable as CSS -->
46 <        .Table1.A .Table1.B .Numbering_20_Symbols .T3  { }
47 <        </style></head><body dir="ltr" style="max-width:8.2681in;margin-top:0.7874in; margin-bottom:0.7874in; margin-left:0.7874in; margin-right:0.7874in; writing-mode:lr-tb; "><h1 class="Heading_20_1"><a id="a__Using_Firebird_with_IBX_Under_Windows"><span/></a>Using Firebird with IBX Under Windows</h1><p class="Text_20_body">Firebird is normally distributed as a single exe <span class="T3">installation</span> package which may be downloaded from <a href="http://www.firebirdsql.org/" class="Internet_20_link">http://www.firebirdsql.org</a>. 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.</p><p class="Text_20_body">When run from the IDE, IBX for Lazarus should then automatically find and use the Firebird client DLL.</p><p class="P2">In order to use the example application, you need to ensure that the Firebird Aliases file contains a link to the example employee data. </p><ul><li><p class="P9" style="margin-left:0cm;"><span class="Bullet_20_Symbols" style="display:block;float:left;min-width:0.635cm;">•</span>For example, for Firebird 2.1, the pathname to the aliases file is<span class="odfLiEnd"/> </p></li></ul><p class="P4">C:\Program Files\firebird\Firebird_2_1\aliases.conf</p><p class="P3">and it must contain the entry:</p><p class="P4">employee = C:\Program Files\firebird\Firebird_2_1\examples\empbuild\employee.fdb</p><ul><li><p class="P10" style="margin-left:0cm;"><span class="Bullet_20_Symbols" style="display:block;float:left;min-width:0.635cm;">•</span>For Firebird 2.5, the entry should be:<span class="odfLiEnd"/> </p></li></ul><p class="P6">employee =  C:\Program Files\firebird\Firebird_2_5\examples\empbuild\employee.fdb</p><h2 class="Heading_20_2"><a id="a__Distributing_the_Firebird_Client_DLL_with_your_Applications"><span/></a>Distributing the Firebird Client DLL with your Applications</h2><p class="Text_20_body">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.</p><p class="Text_20_body">The simplest strategy is to install, in the same folder as your application is installed, the following Firebird files:</p><ul><li><p class="P11" style="margin-left:0cm;"><span class="Bullet_20_Symbols" style="display:block;float:left;min-width:0.635cm;">•</span>fbclient.dll<span class="odfLiEnd"/> </p></li><li><p class="P11" style="margin-left:0cm;"><span class="Bullet_20_Symbols" style="display:block;float:left;min-width:0.635cm;">•</span>firebird.msg<span class="odfLiEnd"/> </p></li><li><p class="P11" style="margin-left:0cm;"><span class="Bullet_20_Symbols" style="display:block;float:left;min-width:0.635cm;">•</span>firebird.conf<span class="odfLiEnd"/> </p></li></ul><p class="Standard">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.</p><h2 class="Heading_20_2"><a id="a__Personal_Database_Applications"><span/></a>Personal Database Applications</h2><p class="Text_20_body">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.</p><p class="Text_20_body">This may be downloaded from <a href="http://www.firebirdsql.org/" class="Internet_20_link">http://www.firebirdsql.org</a> 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.</p><p class="Text_20_body">When using the Embedded Server, the IBDatabase object properties should be set as follows:</p><ol><li><p class="P12" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">1.</span>Database Name: Full pathname for the database file.<span class="odfLiEnd"/> </p></li><li><p class="P12" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">2.</span>“user_name” parameter: SYSDBA<span class="odfLiEnd"/> </p></li><li><p class="P12" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">3.</span>“password” parameter: masterkey<span class="odfLiEnd"/> </p></li><li><p class="P12" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">4.</span>Logon Promt: false<span class="odfLiEnd"/> </p></li></ol><p class="Text_20_body">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:</p><ol><li><p class="P13" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">1.</span>Server Name: empty<span class="odfLiEnd"/> </p></li><li><p class="P13" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">2.</span>Protocol: Local<span class="odfLiEnd"/> </p></li><li><p class="P13" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">3.</span>“user_name” parameter: SYSDBA<span class="odfLiEnd"/> </p></li><li><p class="P13" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">4.</span>“password” parameter: masterkey<span class="odfLiEnd"/> </p></li><li><p class="P13" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">5.</span>Logon Prompt: false<span class="odfLiEnd"/> </p></li></ol><h2 class="Heading_20_2"><a id="a__How_IBX_Finds_the_Firebird_DLL"><span/></a>How IBX Finds the Firebird DLL</h2><p class="P1">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:</p><table border="0" cellspacing="0" cellpadding="0" class="Table1"><colgroup><col/><col/></colgroup><tr><td style="text-align:left;" class="Table1_A1"><ol><li><p class="P15" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">1.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;" class="Table1_A1"><p class="Text_20_body"><span class="T1">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 </span><span class="T2">fbembedded.dll</span><span class="T1"> (the embedded server DLL) is present here. If it is then this is loaded. If not then it checks to see if </span><span class="T2">fbclient.dll</span><span class="T1"> is present. If so, then it is loaded.</span></p><p class="P7"><span class="T1">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 </span><span class="T2">firebird.conf</span><span class="T1"> and </span><span class="T2">firebird.msg</span><span class="T1"> 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.</span></p></td></tr><tr><td style="text-align:left;" class="Table1_A1"><ol><li><p class="P15" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">2.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;" class="Table1_A1"><p class="P1">If neither is present, then IBX 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.</p><p class="P8">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.</p></td></tr><tr><td style="text-align:left;" class="Table1_A1"><ol><li><p class="P15" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">3.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;" class="Table1_A1"><p class="P1">If the registry cannot be used to locate the Firebird Client lbrary, then IBX uses the Windows Path to search for and load <span class="T2">fbclient.dll</span>.</p></td></tr><tr><td style="text-align:left;" class="Table1_A1"><ol><li><p class="P15" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">4.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;" class="Table1_A1"><p class="P1">If the DLL is still not found, then in quiet desperation, IBX will attempt to load the legacy InterBase <span class="T2">gds32.dll </span>again using the Windows Search Path.</p></td></tr></table><p class="P1"> </p><p class="P1">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.</p><h2 class="P14"><a id="a__Overridding_the_Firebird_Client_Library_Search_Algorithm"><span/></a>Overridding the Firebird Client Library Search Algorithm</h2><p class="Text_20_body"><span class="T1">The Windows implementation also recognises the  </span><span class="T2">OnGetLibraryName </span><span class="T1">event handler.</span></p><p class="Text_20_body"><span class="T1">In your program, you can create an event handler for the </span><span class="T2">OnGetLibraryName</span><span class="T1"> event defined in the IBIntf Unit. The event handler should be set in an initialization section and has the type:</span></p><p class="P5">procedure(var libname: string)</p><p class="P1">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.</p></body></html>
46 >        .Table1.A .Table1.B .Numbering_20_Symbols .T5 .T6 .T7  { }
47 >        </style></head><body dir="ltr" style="max-width:8.2681in;margin-top:0.7874in; margin-bottom:0.7874in; margin-left:0.7874in; margin-right:0.7874in; writing-mode:lr-tb; "><h1 class="Heading_20_1"><a id="a__Using_Firebird_with_IBX_Under_Windows"><span/></a>Using Firebird with IBX Under Windows</h1><p class="Text_20_body">Firebird is normally distributed as a single exe <span class="T5">installation</span> package which may be downloaded from <a href="http://www.firebirdsql.org/" class="Internet_20_link">http://www.firebirdsql.org</a>. 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.</p><p class="Text_20_body">When run from the IDE, IBX for Lazarus should then automatically find and use the Firebird client DLL.</p><p class="P4">In order to use the example application, you need to ensure that the Firebird Aliases file contains a link to the example employee data. </p><ul><li><p class="P13" style="margin-left:0cm;"><span class="Bullet_20_Symbols" style="display:block;float:left;min-width:0.635cm;">•</span>For example, for Firebird 2.1, the pathname to the aliases file is<span class="odfLiEnd"/> </p></li></ul><p class="P8">C:\Program Files\firebird\Firebird_2_1\aliases.conf</p><p class="P7">and it must contain the entry:</p><p class="P8">employee = C:\Program Files\firebird\Firebird_2_1\examples\empbuild\employee.fdb</p><ul><li><p class="P14" style="margin-left:0cm;"><span class="Bullet_20_Symbols" style="display:block;float:left;min-width:0.635cm;">•</span>For Firebird 2.5, the entry should be:<span class="odfLiEnd"/> </p></li></ul><p class="P10">employee =  C:\Program Files\firebird\Firebird_2_5\examples\empbuild\employee.fdb</p><h2 class="Heading_20_2"><a id="a__Distributing_the_Firebird_Client_DLL_with_your_Applications"><span/></a>Distributing the Firebird Client DLL with your Applications</h2><p class="Text_20_body">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.</p><p class="Text_20_body">The simplest strategy is to install, in the same folder as your application is installed, the following Firebird files:</p><ul><li><p class="P15" style="margin-left:0cm;"><span class="Bullet_20_Symbols" style="display:block;float:left;min-width:0.635cm;">•</span>fbclient.dll<span class="odfLiEnd"/> </p></li><li><p class="P15" style="margin-left:0cm;"><span class="Bullet_20_Symbols" style="display:block;float:left;min-width:0.635cm;">•</span>firebird.msg<span class="odfLiEnd"/> </p></li><li><p class="P15" style="margin-left:0cm;"><span class="Bullet_20_Symbols" style="display:block;float:left;min-width:0.635cm;">•</span>firebird.conf<span class="odfLiEnd"/> </p></li></ul><p class="Standard">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.</p><h2 class="Heading_20_2"><a id="a__Personal_Database_Applications"><span/></a>Personal Database Applications</h2><p class="Text_20_body">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.</p><p class="P2">From IBX 1.4.0 onwards, the TIBLocalDBSupport component provides simplified management of Personal Databases.</p><p class="P5"><span class="T6">The Firebird embedded server</span> may be downloaded from <a href="http://www.firebirdsql.org/" class="Internet_20_link">http://www.firebirdsql.org</a> 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.</p><p class="P5">When using the Embedded Server <span class="T6">and </span><span class="T2">TIBLocalDBSupport </span><span class="T3">is not in use</span>, the IBDatabase object properties should be set as follows:</p><ol><li><p class="P16" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">1.</span>Database Name: Full pathname for the database file.<span class="odfLiEnd"/> </p></li><li><p class="P16" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">2.</span>“user_name” parameter: SYSDBA<span class="odfLiEnd"/> </p></li><li><p class="P16" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">3.</span>“password” parameter: masterkey<span class="odfLiEnd"/> </p></li><li><p class="P16" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">4.</span>Logon Promt: false<span class="odfLiEnd"/> </p></li></ol><p class="Text_20_body">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:</p><ol><li><p class="P17" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">1.</span>Server Name: empty<span class="odfLiEnd"/> </p></li><li><p class="P17" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">2.</span>Protocol: Local<span class="odfLiEnd"/> </p></li><li><p class="P17" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">3.</span>“user_name” parameter: SYSDBA<span class="odfLiEnd"/> </p></li><li><p class="P17" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">4.</span>“password” parameter: masterkey<span class="odfLiEnd"/> </p></li><li><p class="P17" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">5.</span>Logon Prompt: false<span class="odfLiEnd"/> </p></li></ol><h2 class="Heading_20_2"><a id="a__How_IBX_Finds_the_Firebird_DLL"><span/></a>How IBX Finds the Firebird DLL</h2><p class="P1">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 DL<span class="T7">L. The algorithm terminates as soon as the library has been located</span>:</p><table border="0" cellspacing="0" cellpadding="0" class="Table1"><colgroup><col/><col/></colgroup><tr><td style="text-align:left;" class="Table1_A1"><ol><li><p class="P19" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">1.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;" class="Table1_A1"><p class="Text_20_body"><span class="T1">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 </span><span class="T4">fbembedded.dll</span><span class="T1"> (the embedded server DLL) is present here. If it is then this is loaded. If not then it checks to see if </span><span class="T4">fbclient.dll</span><span class="T1"> is present. If so, then it is loaded.</span></p><p class="P11"><span class="T1">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 </span><span class="T4">firebird.conf</span><span class="T1"> and </span><span class="T4">firebird.msg</span><span class="T1"> 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.</span></p></td></tr><tr><td style="text-align:left;" class="Table1_A1"><ol><li><p class="P19" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">2.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;" class="Table1_A1"><p class="P6">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</p></td></tr><tr><td style="text-align:left;" class="Table1_A1"><ol><li><p class="P19" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">3.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;" class="Table1_A1"><p class="P1">IBX <span class="T7">then </span>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.</p><p class="P12">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.</p></td></tr><tr><td style="text-align:left;" class="Table1_A1"><ol><li><p class="P19" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">4.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;" class="Table1_A1"><p class="P3">IBX now looks in the default installation folders for first Firebird 2.5 and then Firebird 2.1. These are &lt;Program Files Folder&gt;\Firebird\Firebird_2_x</p></td></tr><tr><td style="text-align:left;" class="Table1_A1"><ol><li><p class="P19" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">5.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;" class="Table1_A1"><p class="P1">IBX <span class="T7">then </span>uses the Windows Path to search for and load <span class="T4">fbclient.dll</span>.</p></td></tr><tr><td style="text-align:left;" class="Table1_A1"><ol><li><p class="P19" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">6.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;" class="Table1_A1"><p class="P1">If the DLL is still not found, then in quiet desperation, IBX will attempt to load the legacy InterBase <span class="T4">gds32.dll </span>again using the Windows Search Path.</p></td></tr></table><p class="P1"> </p><p class="P1">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.</p><h2 class="P18"><a id="a__Overridding_the_Firebird_Client_Library_Search_Algorithm"><span/></a>Overridding the Firebird Client Library Search Algorithm</h2><p class="Text_20_body"><span class="T1">The Windows implementation also recognises the  </span><span class="T4">OnGetLibraryName </span><span class="T1">event handler.</span></p><p class="Text_20_body"><span class="T1">In your program, you can create an event handler for the </span><span class="T4">OnGetLibraryName</span><span class="T1"> event defined in the IBIntf Unit. The event handler should be set in an initialization section and has the type:</span></p><p class="P9">procedure(var libname: string)</p><p class="P1">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.</p></body></html>

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines