| 1 |
<?xml version="1.0" encoding="UTF-8"?> |
| 2 |
<!DOCTYPE html |
| 3 |
PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN" "http://www.w3.org/TR/MathML2/dtd/xhtml-math11-f.dtd"> |
| 4 |
<html xmlns="http://www.w3.org/1999/xhtml"><!--This file was converted to xhtml by OpenOffice.org - see http://xml.openoffice.org/odf2xhtml for more info.--><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="2011-05-06T11:11:01" 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"/><base href="."/><style type="text/css"> |
| 5 |
@page { } |
| 6 |
table { border-collapse:collapse; border-spacing:0; empty-cells:show } |
| 7 |
td, th { vertical-align:top; font-size:12pt;} |
| 8 |
h1, h2, h3, h4, h5, h6 { clear:both } |
| 9 |
ol, ul { margin:0; padding:0;} |
| 10 |
li { list-style: none; margin:0; padding:0;} |
| 11 |
<!-- "li span.odfLiEnd" - IE 7 issue--> |
| 12 |
li span. { clear: both; line-height:0; width:0; height:0; margin:0; padding:0; } |
| 13 |
span.footnodeNumber { padding-right:1em; } |
| 14 |
span.annotation_style_by_filter { font-size:95%; font-family:Arial; background-color:#fff000; margin:0; border:0; padding:0; } |
| 15 |
* { margin:0;} |
| 16 |
.Heading_20_1 { font-size:115%; margin-bottom:0.0835in; margin-top:0.1665in; font-family:Arial; writing-mode:page; font-weight:bold; } |
| 17 |
.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; } |
| 18 |
.P1 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; font-style:normal; } |
| 19 |
.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; } |
| 20 |
.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; } |
| 21 |
.P13 { font-size:14pt; font-style:normal; font-weight:bold; margin-bottom:0.0835in; margin-top:0.1665in; font-family:Arial; writing-mode:page; } |
| 22 |
.P2 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Courier New; writing-mode:page; } |
| 23 |
.P3 { 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; } |
| 24 |
.P4 { font-size:12pt; font-family:Times New Roman; writing-mode:page; } |
| 25 |
.P5 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; } |
| 26 |
.P6 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; } |
| 27 |
.P7 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; } |
| 28 |
.Standard { font-size:12pt; font-family:Times New Roman; writing-mode:page; } |
| 29 |
.Text_20_body { font-size:12pt; font-family:Times New Roman; writing-mode:page; margin-top:0in; margin-bottom:0.0835in; } |
| 30 |
.Table1 { width:6.6931in; float:none; } |
| 31 |
.Table1_A1 { padding:0.0382in; border-style:none; } |
| 32 |
.Table1_A { width:0.5111in; } |
| 33 |
.Table1_B { width:6.1819in; } |
| 34 |
.Bullet_20_Symbols { font-family:OpenSymbol; } |
| 35 |
.T2 { font-style:normal; } |
| 36 |
.T3 { font-style:italic; } |
| 37 |
<!-- ODF styles with no properties representable as CSS --> |
| 38 |
.Numbering_20_Symbols { } |
| 39 |
</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; "><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 installataion package which may be downloaded from <a href="http://www.firebirdsql.org/">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="Text_20_body">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</p><p class="P2">C:\Program Files\firebird\Firebird_2_1\aliases.conf</p><p class="Text_20_body">and it must contain the entry:</p><p class="P2">employee = C:\Program Files\firebird\Firebird_2_1\examples\empbuild\employee.fdb</p><p class="Text_20_body">After editing the aliases file, you should restart the Firebird Server (or the computer).</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="P5" style="margin-left:0cm;"><span class="Bullet_20_Symbols" style="display:block;float:left;min-width:0cm">•.</span>fbclient.dll<span class="odfLiEnd"/> </p></li><li><p class="P5" style="margin-left:0cm;"><span class="Bullet_20_Symbols" style="display:block;float:left;min-width:0cm">•.</span>firebird.msg<span class="odfLiEnd"/> </p></li><li><p class="P5" style="margin-left:0cm;"><span class="Bullet_20_Symbols" style="display:block;float:left;min-width:0cm">•.</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/">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="P6" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0cm">1.</span>Database Name: Full pathname for the database file.<span class="odfLiEnd"/> </p></li><li><p class="P6" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0cm">2.</span>“user_name” parameter: SYSDBA<span class="odfLiEnd"/> </p></li><li><p class="P6" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0cm">3.</span>“password” parameter: masterkey<span class="odfLiEnd"/> </p></li><li><p class="P6" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0cm">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="P7" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0cm">1.</span>Server Name: empty<span class="odfLiEnd"/> </p></li><li><p class="P7" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0cm">2.</span>Protocol: Local<span class="odfLiEnd"/> </p></li><li><p class="P7" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0cm">3.</span>“user_name” parameter: SYSDBA<span class="odfLiEnd"/> </p></li><li><p class="P7" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0cm">4.</span>“password” parameter: masterkey<span class="odfLiEnd"/> </p></li><li><p class="P7" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0cm">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 width="57"/><col width="686"/></colgroup><tr><td style="text-align:left;width:0.5111in; " class="Table1_A1"><ol><li><p class="P4" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0cm">1.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;width:6.1819in; " class="Table1_A1"><p class="Text_20_body"><span class="T2">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="T3">fbembedded.dll</span><span class="T2"> (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="T3">fbclient.dll</span><span class="T2"> is present. If so, then it is loaded.</span></p><p class="P11"><span class="T2">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="T3">firebird.conf</span><span class="T2"> and </span><span class="T3">firebird.msg</span><span class="T2"> 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;width:0.5111in; " class="Table1_A1"><ol><li><p class="P4" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0cm">2.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;width:6.1819in; " 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="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;width:0.5111in; " class="Table1_A1"><ol><li><p class="P4" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0cm">3.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;width:6.1819in; " 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="T3">fbclient.dll</span>.</p></td></tr><tr><td style="text-align:left;width:0.5111in; " class="Table1_A1"><ol><li><p class="P4" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0cm">4.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;width:6.1819in; " 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="T3">gds32.dll </span>again using the Windows Search Path.</p></td></tr></table><p class="P1"> </p><p class="Text_20_body"><span class="T2">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.</span></p><h2 class="P13"><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="T2">The Windows implementation also recognises the </span><span class="T3">OnGetLibraryName </span><span class="T2">event handler.</span></p><p class="Text_20_body"><span class="T2">In your program, you can create an event handler for the </span><span class="T3">OnGetLibraryName</span><span class="T2"> event defined in the </span><span class="T2">IBIntf Unit. The event handler should be set in an initialization section and has the type:</span></p><p class="P3">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> |
