Delphi +

ZeosLib

+ Firebird

Instalacin, comentarios y ejemplos de uso

A ZEOS basics tutorial not only for Firebird ...

Author Michael Seeger (ZeosLib Development Team) Date 26.03.2008, 16:01 Views 6143 at 22,03,2010 Description A ZEOS basics tutorial not only for Firebird ... Category Firebird / Interbase Type The ZeosLib DBOs 6.1.5 - With Delphi 7 and Firebird 1.5 This little article shows how

to access Firebird databases by using the ZEOS component Library in version 6.1.5 (including Patches 1&2) and how to use these components in database applications. It does not matter if you use the "real" SQL-Server or the embedded version which is restricted to local held databases. A couple of examples (also migrated Delphi-BDE demos) shall explain how to use the ZEOS components.

Although this article describes the usage of the ZEOS Library using Firebird, all the basics can be used with other SQL servers / databases that are supported by ZEOS. Note: The Firebird Server can be downloaded from download section of http://www.ibphoenix.com http://www.firebirdsql.org

The ZEOS Library

The name "ZEOS" has no special meaning. The founders of ZEOS found that this name just sounded good. Since that time the Library is called "ZEOS". Generally we can say about the ZEOS Library that the developers are inteneded to copy the functions and the behaviour of the corresponding BDE components as good as possible. The intension is to minimize the learning courve for developers who migrate from BDE to ZEOS. Of course there must have been made some compromises so that they are not a hundred percent compatible because the ZEOS components shall be applicable universally. The ZEOS Library in version 6.1.5 consists of the following nine components which shall be introduced in the following: TZConnection TZQuery TZReadOnlyQuery TZUpdateSQL TZTable TZStoredProc TZSQLProcessor TZSQLMonitor TZSQLMetadata

InstallingtheZEOSLibraryandadditionalstuff
TheinstallationoftheZEOSLibraryunderDelphi7professionalisnotthatcomplicated.Oncethecurrent ZEOSversionandallthepatches(whilewritingthisarticleitwaslibraryversion6.1.5andthecorresponding patches1&2)aredownloadedandunzippedintoadirectoryofyourchoicecompletelyyouonlyhaveto followtheinstallationinstructions(note:FirebirddoesnotneedanyadditionalDLL's,here!): OpenthedelphiprojectgroupZeosDbo.bpgfromsubdirectorypackages\delphi7ZeosDbo.bpgandinstall thefollowingcomponentsingivenorder: ZCore.bpl ZParseSql.bpl ZPlain.bpl ZDbc.bpl ZComponent.bpl

Note:Ifthereoccursomeerrorswhilecompilingthatsaythatacertaindcufilecouldnotbefoundthenjust addthesubdirectorypackages\delphi7\buildtodelphislibrarypath.Alldcufilesthatarecreatedwhile compilationarelocatedhere. Attention:TheclientlibraryofFirebirdServerversion1.5.1(notembedded!)wasdeliveredas"gds32.dll" andnot"fbclient.dll".ThiscausestroublewhileaccessingviaZEOSbecausetheprotocol"firebird1.5" aassumesaDLLnamed"fbclient.dll".Aworkaroundistocopythe"gds32.dll"andrenamethiscopyto "fbclient.dll".

Additive:EventAlertercomponent(TZIBEventAlerter) Anadditionalcomponent,thatonlyexistsforFirebird(andalsoInterbase)interceptsall(registered)events, thataretriggeredbyStoredProceduresofadatabase,andmakesitpossibletoreactuponthem.This componentwaspostedbyAlexeyGilev(aka"GAF")intotheZEOSForumandmadeavailabletotheZEOS Team.Theoriginalversioncanbedownloadedhere: http://sourceforge.net/tracker/index.php?func=detail&aid=911233&group_id=35994&atid=415826 TheeventalerterisonlytestedforZEOSversion6.1.4butrunswithsomemodificationswithoutany problemsinversion6.1.5(withPatch1&2).TheeventalerterthatwasportedtoZEOSversion6.1.5willbe installedasfollows(pleaseconsidertheReadMefile!I'mnotgoingtogiveanywarrentythatthissolutionis errorfree!Youuseitatyourownrisk!): DownloadpatchforZIBEventAlerter(integrated)here unzipthefilesanddistributethemtotheaccordingZEOSdirectories ifnecessaryrecompileandreinstallZEOS(seeabove)

Basics:Transactions
SomemandatorybasicsabouttransactionshavetobetoldinordertounderstandhowtheTZConnection componentworksinternallyandhowtoworkwithit. Ingeneral:Youonlycanhaveaccesstoadatabasewithinthecontextofavalid("running")transaction.A transactionhastofulfillthefollowingfourcharacteristicsthatareknownasACIDcharacteristicsofa transaction.

Atomicity Allactionsperformedonadatabasehavetobeexecutedsuccessfully.Ifonlyoneerroroccursthenthe originalstateofthedatabasehastoberestored.Accordingtotheprinciple"allornothing". Consitency Atransaktiontransfersadatabasefromoneconsitentstatetoanotherconsistentstate.Ifanerroroccurs thentheoriginalstateofthedatabasehastoberestored. Isolation Atransactionhastobehandledbytheserverasifitwastheonlyonerunning.Thismeansithastorun indepentlyfromothertransactions.Ausermustnotnoticethechangesdonebyotherusers. Durability ChangesinthedatasetofadatabasethatarecausedbySQLstatementsthatareexecutedbetweenthe startofatransactionandaCOMMIThavetobefixedirrevocably. Transactionsencapsulateconsecutiveaccessesonadatabase.Adatabaseaccessmaybeofreadingor writingnature(INSERT,UPDATE,DELETE)oritmaychangethestructureofadatabase.Transactionsare terminatedbyCOMMITorROLLBACK.COMMITconfirmsallchangesinadatabasesincethestartofa transaction.ROLLBACKresetsallchangesinadatabasesincethestartofatransaction. Transactionsrunningontheserverhavetobeisolatedfromeachother.Sotheymayrunindependently.A transactionhastobehandledbytheserverasitwastheonlyonethatiscurrentlyrunning.Thismeansfor theuserthathemustneverseethechangesofotheruserswhileheisinarunningtransactionbecausethe otherchangeshavenothingtodowithhistransaction.Thisiscalledtheisolationofatransaction.Byusing differenttransactionisolationlevels(TILs)thedevelopermayprotectthedataofanSQLresultsetfrom accessbyothertransactions.Thebehaviourdescribedaboveiscalledthestandardisolationlevelknownas SERIALIZABLE.ThestandardisolationlevelofFirebirdiscalledSNAPSHOTandcomesverycloseto SERIALIZABLE.

TZConnection
TheTZConnectioncomponentisacombinationofaBDETDatabaselikecomponentacomponentthat handlesatransaction.ThiscombinationmakessensebecauseallaccesstoaFirebirddatabase(andalso otherdatabases)isalwaysmadeinarunningtransaction.SuchatransactionisstartetbytheZEOSLibrary wheneveraconnection(methodConnectofTZConnection)toadatabaseisopened.Thiscausesthateach databaseaccessisdonewithinthecontextofarunningtransaction,automatically.Thesocalled AutoCommitmodeisalwayson(setto"True").ThisisalsothestandardbehaviourofthecorrespondingBDE component.IfAutoCommitisactivatedtheneverychangeofanSQLstatementwillbeconfirmedinthe databasebyCOMMITateritssuccessfullexecution.Ifthisbehaviourshallbeturnedoffandanexplicit transactionshallbestartedthenthemethodStartTransactionhastobecalled.Withinthisexplicittransaction itispossibletoexecuteacoupleofSQLstatementsthatmakechangestothedatabase,insuccession. Thesestatementsthencanbeconfirmedasa"group"byCOMMIT.Ifanexplicittransactionisactivethen AutoCommitisalwaysturnedoff.ByCallingtheMethodCommitallthechangesmadewithinthisexplicit transactionareconfirmed.CallingthemethodRollbackresetsthesechanges.InbothcasesAutoCommitwill besettoTruewhenthemethodcall(CommitorRollback)isdone.Theexplicittransactionhasended.

Retaining AfterconfirmingthechanesmadeinatransactionbyCOMMITorresettingthembyROLLLBACKthe transactionnormallyisgoingtobeendedandanexistingresultsetofaqueryorstoredprocedurewillbe discarded.TheseCOMMITsandROLLBACKsarecalled"hard"commitor"hard"rollback.Byusingthe ZEOSlibrarythiswillbecomealittlebitdifferent.ZEOSkeepstheresultsetalive.Thisisachievedbyclosing transactionwith"soft"commitsor"soft"rollbacks.AllthisisdonebytheTZConnectionobject.Thismethodis

calledretaining.TheCOMMITandROLLBACKcommandsareexecutedwiththeadditionRETAINING. Retainingcausestheclosingofthecurrenttransactionandimmediatelyopeninganewtransactionwithall thedataandresources(especiallytheresultset)ofthe"old"transaction. Retainingbecomesaproblemifitisusesforhugetables.Itconstrainstheinternalcleanupmechanismof firebird(garbagecollection).Thisleads(becauseoftheversioningandthemultigenerationalarchitectureof Firebird)toalotofoldrecordsthathavetobekeptbutwillnotbeneededanymore.Thisinfluencesthe server'sperformancedinanegativeway.Asocalledsweepwoulddiscardtheseoldversionsandimprove theperformance.Thissweepwillonlybeexecutedbysendinga"hard"COMMITorROLLBACK.TheZEOS Libraryonlyexecutesthese"hard"commandswhenendingthedatabaseconnection(closingconnection).It isnotpossibletosendthemwhileadatabaseconnectionisactive.Sothedatabaseconnectionshouldbe deactivatedandimmediatelyactivatedoccasionallytoachievethisperformanceimprovement.

TransactionIsolationLevelsofTZConnection TheTZConnectioncomponentprovidesfourusefulandpredefinedTransactionIsolationLevels(TIL): tiRepeatableRead ItcorrespondstotheTIL"SNAPSHOT"whichisthestandardofFirebirdservers.Itisacombinationofthe trasactionparameters"concurrency"and"nowait".Asnapshotofthecurrentdatabaseismade.Otherusers areonlyinfluenced(constrained)iftwotransactionsworkononerecordsimultaneously.Ifconflictsarise whileaccessingdataanerrormessagewillbereturned.Changeswithinothertransactionswillnotbe noticed.ThisTILcoverstherequirementoftheSQLstandard(SERIALIZABLE)widely. tiReadCommitted ItcorrespondstotheTIL"READCOMMITTED".Itisacombinationofthetransactionparameters "read_committed","rec_version"and"nowait".ThisTILrecognizesallchangesinothertransactionthathave beenconfirmedbyCOMMIT.Theparameter"rec_version"isresponsibleforthebehaviourthatthemost currentvaluesthatwerecommittedbyotheruserswillbeconsidered.theparameter"nowait"isresposiblefor thebehaviourthatthereisnowaitingforthereleaseofalockedrecord.Sotheserverismorestressedthan inTILtiRepeatableReadbecauseithastodoalltherefreshestogetthesevaluesagainandagain. tiSerializable ItcorrespondstotheTIL"SNAPSHOTTABLESTABILITY".Itisusedtogetanexclusiveaccesstotheresult set.Realizedbytransactionparameter"consistency"itpreventsthat"foreign"transactionmayaccessthe writtendata.Onlythetransactionwhichhaswrittenthedatamayaccessthem.Thispreventsalsoamulti useraccesstothewrittendata.BecausethisTILisveryrestrictivebyaccessingwrittendataitshouldbe appliedwithcautionandcare. tiNone NoTILisusedtoisolatethetransaction. TheTILtiReadUncommittedisnotsupportedbyFirebird.IfthisTILisused,anerrorwillbetriggerdedand thetransactionwillnotbeisolated(likeusingtiNone). Recommendation ItisadvisabletoisolatetransactionswithtransactionisolationleveltiRepeatableRead(theFirebirdstandard). ThisTILcoverstherequirementoftheSQLstandard(SERIALIZABLE)widely.Itpreventsallproblems concerningconsistencythatmayarisebyusingtransactions.SecondchoicewouldbetiReadCommittedbut thisdependsontheapplicationandthenecessityifthereseultsetalwayshastobecurrent.

CustomizingTILs IfyouwanttocustomizeyourTILsorexpandagivenTILthenyoucandothisbyusingtheparametersof TZConnection.ThemostimportantthingaboutthisisthattheTILthatshouldbeexpandedhastobesetin propertyIsolationLevel.IfitissettheTILparameters(seeIB/FBAPIreference)youwanttoaddmaybe addedinsourcecode.ThefollowingexampleshowstheexpansionofaTILpresettotiNone: : ZConnection.TransactIsolationLevel := tiNone; ZConnection.Properties.Add('isc_tpb_concurrency'); ZConnection.Properties.Add('isc_tpb_wait'); ZConnection.Connect; :

Protocol ThemostimportantsettinginaTZConnectionobjectistheserverprotocolitissetinpropertyProtocol.It determineswhichprotocolshallbeusedandthuswhichSQLserverwillbeaccessed.Thismethodmakes ZEOSsoflexible.Youdon'thavetoinstallspecialcomponentsforeachdatabaseyouwanttoaccessasit wasinVersions5.xandearlier.Thecomponentswillbeinstalledonce.Thisisenough.Youonlychoosethe protocolforthesupportedSQLserveryouwanttoaccessandyouaredone.Soyousetprotocol"firebird 1.5"toaccessFirebird1.5server. ReadOnlyConnection ThedatabaseconnectionmaintainedbyaTZConnectionobjectissettoreadonlybydefault(ReadOnly= True).Thismeansthatnowritingaccesstotheconnecteddatabaseisallowed.Togetwritingaccesstothe databaseyouhavetosetReadOnlytoFalse. Codepages Codepageswillbedeterminedbysettingparameter"lc_ctype"or"Codepage"inTZConnection.This parametermustbeaddedtothepropertyProperties.E.g.: ZConection.Properties.Add ('lc_ctype=ISO8859_1'); or ZConnection.Properties.Add ('Codepage=ISO8859_1');

Note:TheCodepagesupportofFirebird(alsoembeddedversion)inversion1.5withZEOSisalittlebit buggy.ThesebugsarecorrectedinFirebirdversion1.5.1. FeaturesoftheFirebirdembeddedserver NormallytheservernameorIPaddressoftheserverisgiveninpropertyHostName.ByusingaFirebird embeddedserveryoumayleavethispropertyempty.OnlypropertyDatabasehastobedetermined.Here youhavetospecifydrivepathandnameofthedatabaseincludingextension. Anotherfeatureoftheembeddedserveristhatyoumayspecifyanyloginnamewithapaswordofyour choice.Itdoesn'tmatterwhatyouchooseyouwillgetconnected. SettingtheTZConnectionobjectpropertyConnectedtoTrueindesigntimeisextremelybadifyoudon'treset

ittoFalsebeforecompiling.IfyouthenstartthecompiledapplicationwithIDErunningyouwillgetanerror thatsaysthatthedatabasecannotbeopenedbecauseitisalreadyinuse.Soyoushouldestablishthe connectiontothedatabasewhenstartingtheapplication(e.g.inOnCreateeventofthemainform)andthen opentheneededqueriesandtables.Deactivatingtheconnectionshouldalsobedoneinmainform(e.g.in OnDestroy).Itisnotnecessarytocloseallopenqueriesandtables.Thiswillbedonewhenclosingthe connectionoftheTZConnectionobject.Ifyouusedatamodelformsyouhavetotakecarethatthedatamodel formiscreatedbeforethemainformiscreated(setintheIDE'sprojectoptions).. UsefulTZConnectionparameters AdditionalparametersforestablishingconnectionstoFirebirddatabasesare:: CreateNewDataBase: AnewdatabasewillbecreatedbasedonthespecifiedCREATEDATABASEstatements.Whenthedatabase iscreatedtheconnectionwillbeestablishedimmediately.AllthishappensbycallingtheConnectmethodof TZConnection. : ZConnection1.Database := 'd:\db1.fdb'; ZConnection1.Protocol := 'firebird-1.5'; ZConnection1.Properties.Add ('CreateNewDatabase=CREATE DATABASE ' + QuotedStr ('d:\db1.fdb') + ' USER ' + QuotedStr ('sysdba') + ' PASSWORD ' + QuotedStr ('masterkey') + ' PAGE_SIZE 4096 DEFAULT CHARACTER SET ISO8859_1'); ZConnection1.Connect; :

ToexecutethiscorrectlyyouhavetosettheDatabaseandProtocolpropertiesatminimum(alsopossiblein objectinspector). Dialect: ThisparametersetsFirebird'sSQLdialiect.Tosetdialect"1"youhavetousethefollowingcode: ZConnection.Properties.Add ('Dialect=1');

ThedialectofFirebird1.5.xissetto"3"bydefault. Rolename: Thisparametersetsarolename.Aloggedinuserthenworksinthecontextoftherole'srightsbutbeforethe userhastobeassignedtothisrole.TheFirebirdembeddedserverdoesnotsupportthisfeature.

TZQuery
TheusageofTZQueryissimilartotheusageofBDE'sTQuerycomponent. Recommandation:RequestLiveandTZUpdateSQL IfanSQLdatasetshallbeupdatablethenRequestLivehastobesettotrueandyoushouldgenerallyuse accordingupdateSQLstatementsthatwillbedefinedinTZUpdateSQL.Ifthisisdonejustassign TZUpdateSQLtotheTZQueryobject.Nowallchangesthatwillbemadeintheresultsetwillbedonetothe databasebyusingthedefinedstatementsofTZUpdateSQL.AccordingtoexperienceRequestLivemode runsmoresmoothlybyusingTZUpdateSQL.

UsageofparametersinSQLstatements UsingparametersinSELECTstatmentsisaseasyasusingthemwithBDE'sTQuery.IfTZQueryhasa resultsetthenyouhavetousetheOpenmethod.IfyouwanttoexecuteanSQLstatementwhichhasno resultset(e.g.:INSERTorUPDATE)youhavetouseExecSQL(seealso:TZStoredProc).

TZReadOnlyQuery
ThisisaQuerycomponentthatisquitesimilartotheTZQuerycomponent.Thereisjustonedifference:The resultsetisreadonly.ThereisnopossibilitytoassignaTZUpdateSQLobject.

TZUpdateSQL
ATZUpdateSQLobjectprovidesstatementstomodifythedataofaresultsetthatisretrievedbyaTZQuery object.TheTZUpdateSQLcomponentiscomparabletoBDE'sTUpdateSQLcomponent.Hereisanexample howtodefinethestatementsofanSQLstatementwithcorrespondingupdatestatements(basedonadialect 3database): SQL.Sql: SELECT * FROM names UpdateSQL.InsertSql: INSERT INTO names (recno, name) VALUES (:recno, :name) UpdateSQL.ModifySql: UPDATE names SET recno = :RecNo, name = :name WHERE recno = :old_recno UpdateSQL.DeleteSql: DELETE FROM names WHERE recno = :old_recno

The"OLD_"parameterprefixforSQLstatements The"old_"prefixishandledaccordingtothehandlingwithBDEcomponents.Byusing"OLD_"asprefixfora fieldnameyouareabletoaccessthevalueofthefieldbeforeitwaschanged.Thisisveryhelpfulifyouhave tocomparefieldvaluesinaWHEREclause. Querieswithreadonlyresultsets IngenealaTZUpdateSQLobjectisassignedtoaTZQueryobjectthathasareadonlyresultset.Thismakes itpossibletochangeitsdata.Suchreadonlyqueriesarequeriesthatjoinmultipletables.Butalsowith "normal""RequestLive"resultsetsyoumayuseTZUpdateSQL(see:TZQuery).

MultiplestatementsinTZQueryandTZUpdateSQL ThecomponentsTZQueryandTZUpdateSqlprovidethepossibilitytoexecutemultiplestatements,internally. SoitispossibletoplacemultipleSQLstatements(evenwithparameters)forexecutioninSQLproperty. Theyonlyhavetobeseparatedbysemicolon.Hereanexample: : With Query do Begin Sql.Clear; Sql.Add('DELETE FROM table1;'); Sql.Add('INSERT INTO table1 VALUES (:Val1, :Val2);'); Sql.Add('INSERT INTO table2 VALUES (:Val3, :Val2);'); Sql.Add('UPDATE table3 SET field1 = :Val4;'); Params.ParamByName('Val1').AsInteger := 123; : ExecSql; End; :

Thestatementswillbeexecutedingivenorder.Itisalsopossibletoexecutemultiplestatementsiftheyare groupedinthismannerinsidemultipleTZUpdateSqlObjectsinordertoupdatemultipletables.

TZTable
TZTableactslikeBDE'sTTable.AsaprincipleyouonlyshoulduseTZTableinaC/Sapplicationifyouhave verysmalltablesbecauseallrecordsofthetablewillbetransferredfromserverintoclient'smemoryby openingtheTZTable.Thisisabahavioursimilartoa"SELECT*FROMXYZ"statement.Youshouldeven preventastatementlikethisinaC/Sapplication.Theintensionistokeeptheresultsetthathastobe transferredfromservertoclientassmallaspossible(perferablyonleonerecord).

TZStoredProc
TZStoredProcprovidesthepossiblitytoexecutestoredproceduresthataresavedinadatabase.Thereare twokindsofstoredprocedures:Proceduresthatreturnaresultsetandproceduresthatdonotreturna resultset.TZStoredProcworkssimilartoBDE'sTStoredProc.Theonlydifferencebetweenthemisthatyou don'thavetocallPreparebeforeyoucalltheExecProcmethod. StoredProcedureswithResultsets IfastoredprocedurereturnsaresultsetthenitwillbeactivatedbycallingtheOpenmethod(whenall existingparametershavegottheirvalues): : With spSumByName do Begin Close; ParamByName ('Name').Value := 'DontKnowHow'; Open; End; :

TheresultsetcanbeworkedonlikearesultsetofaTZQuery.

StoredProcedureswithoutResultsets IfastoredprocedurehasnoresultsetthenitwillbeexecutedbycallingtheExecProcmethod(whenall existingparametershavegottheirvalues).Hereisanexample(conConnection.AutoCommit=True): : With spDeleteByName do Begin ParamByName ('Name').Value := 'DontKnowHow'; conConnection.StartTransaction Try // execute StoredProc ExecProc; Except conConnection.Rollback; End; conConnection.Commit; End; :

Attention :BuginZEOSLibraryV6.1.5! IfastoredprocedurewasexecutedviaExecProcatleastonetime,anexceptionwillbetriggeredwhen disconnectingTZConnection(usedbyTZStoredProc)fromdatabase.Exception'sMessageis:"invalid statementhandle".SQLerrornumberis901.ThisExceptionwillnotbetriggeredifthestoredprocedureis executedusingaTZQueryorTZReadOnlyQuery.Executionofthestoredprocedurewillbedonebycalling theprocedureusingthefollowingSQLcommand(putintotheSQLproperty): [syntax="sql"]EXECUTEPROCEDUREDeleteByName(:Name)[/color][/font][/list] ExecutingastoredprocedurethiswayissimilartoexecutioninTZStoredProc(conConnection.AutoCommit= True): : // using a TZQuery object With qryDeleteByName do Begin ParamByName ('Name').Value := 'DontKnowHow'; conConnection.StartTransaction Try ExecSQL; // execute SQL statement in TZQuery Except conConnection.Rollback; End; conConnection.Commit; End; : Info:Evenwithadialect3databaseitisnotneededtoputthenameofthestoredprocedureintoquotation marksNamesofstoredproceduresinFirebirdarenotcasesensitive. ProblemswithTZStoredProcwhenusingdialect1databases Theproblemwhenusingdialect1databasesisthatthemetadataofstoredproecedureisnotproperly transferredtotheTZStoredProcobjectswhenchoosingthestoredprocedureinobjectinspector.All parapeterdataisnotproperlyinterpreted.Anupdatefromdialect1todialect3solvesthisproblem.Isthe dialect1databasevitalfortheapplicationsystemthenaTZQueryorTZReadOnlyQueryhastobeusedas workaround.

TZSQLProcessor
ThiscomponentprovidesthefunctiontoprocessSQLscriptsthatcanbeloadedbycallingthemethods LoadFromStream()orLoadFromFile().TheloadedSQLScriptisputintoanaccordingpropertycalledScript. Importanisthatthecorrectdelimiterforthescriptisset(PropertyisalsoDelimiter).Bydefault";"willbeset asdelimiter.Thisissufficientforthemostscripts.Butifyouwanttocreatestoredproceduresortriggersvia scriptyoushouldsetdelimiteraccordingtothesettingofthescript's"SETTERM>newDelimiter< >oldDelimiter<"command(normally"^"isusedforthis).InadditiontothisthepropertyDelimiterTypehasto besettodtSetTerm.HeresomelinesofcodethatshowhowtoprocessanSQLscript: : sqlScript.Script.Clear; sqlScript.LoadFromFile('c:\temp\createdb.sql'); conConnection.StartTransaction; Try sqlScript.Execute; Except conConnection.Rollback; End; conConnection.Commit; : TheSQLscriptisprocessedwithinanexplicittransaktion(AutoCommitisturnedon).Ifexecutionsucceeds thechangeswillbecommittedotherwisetheywillberolledback.

TZSQLMonitor
UsingtheTZSQLMonitorcomponentyoumaylogcertainactionsoreventsoftheZEOSdatabase components.ThejournalmaybewrittenasfileorcollectedinaTMemoobjectorsomethinglikethat. Writingtheactionsoreventstoalogfileonlyneedsafewsettings: : sqlMonitor.FileName := 'C:\Log\MyAppLog.log'; sqlMonitor.Active := True; sqlMonitor.AutoSave := True; : TocollecttheloggedactionsoreventsinaTMemoobjectyouhavetoimplementtheOnLogTraceeventas follows: Procedure Tfrm_MyApp.sqlMonitorLogTrace (Sender: TObject; Event: TZLoggingEvent); Begin If Trim (Event.Error) > '' Then memMontor.Lines.Add (DateTimeToStr (Event.Timestamp) + ': ' + Event.Message + #13#10 + ' Error: ' + Event.Error) Else memMontor.Lines.Add (DateTimeToStr (Event.Timestamp) + ': ' + Event.Message); End; // sqlMonitorLogTrace TheOnLogTraceeventisalwaystriggeredwhenanactionoreventwasloggedbysqlMonitor.LogEvent (oEvent).TheoEventparameterstandsforaninstanceofaTZLoggingEventclassobject.

PropertiesofTZLoggingEvent Category(TZLoggingCategory):Standsforthecategoryoftheloggedactionorevent(lcConnect, lcDisconnect,lcTransaction,lcExecuteorlcOther) Protocol(String):Theprotocolthatisusedtoaccessthedatabase(see:TZConnection) Message(String):Thetextthatislogged. ErrorCode(Integer):Theerrorcodeincaseofanerror. Error(String):Theerrortextincaseofanerror. Timestamp(TDateTime):Dateandtimeoftheloggedactionorevent.

TZSQLMetadata
WiththisspecialTDataSetcomponentitispossibletoaccessthemetadataofadatabaseliketables, columns,etc.(Thischapterisstilltobeexpanded!)

TZIBEventAlerter(AddOnonlyforFirebirdandInterbase)
ByusingthiscomponentyouareabletointercepteventstriggeredbystoredproceduresofaFirebird databaseandreacttothem.Youonlyhavetoregistertheevent'stext(string)youwanttoreacttoinproperty Eventswhichisastringlist.Youcandothisusingobjectinspectororinsidethesourcecode.Theeventalerter isactivatedbyregisteringthelistedevents.TodothisyoushouldcalltheRegistereventsmethodbecause thePropertiesAutoRegisterandRegistereddonotworkproperly.Ifyouoncehaveregisteredtheeventsthe componentisabletoreacttothem.Alleventsareunregistered(deleted)bycallingmethodUnregisterEvents andtheeventalertetisturnedoff. Registrationofeventsand"activation"oftheeventalerter: : EventAlerter.Events.Add ('Minimum Stock Level Reached'); EventAlerter.Events.Add ('Credit Limit Exceeded'); EventAlerter.RegisterEvents; :

Master/DetailwithZEOSLibrary
ZEOSDataSetcomponentscomewithtwokindsofmaster/detailconnections:thosewithaserversidedfilter andthosewithaclientsidedfilter.BothkindsandonekindinadditiointhatisindependentfromZEOS(and thuswithoutanycomfort)willbedescribedhere. Note:Ifwetalkabout"master"or"detail"thenaTDataSetdescendant(TZQuery/TZReadOnlyQuery, TZTableoraTZStoredProc)ismeantthataccesseseitheramasterresultsetoradetailresultsetofa master/detailconnection.

Master/Detailwithserversidedfilters ThismethodisthedefaultbehaviouroftheBDE'sTQuerycomponent.Amaster/detailconnectionoftwo DataSetsisestablishedasfollows: Themaster'sDataSourceisassignedtotheDataSourceofthedetail. Allprimarykeyfieldsofthemasterhavetobecomparedwiththeforeignkeyfieldsofthedetailinthe detailSQLstatement.

Thisisanexampleforasimplemaster/detailqueries.Requirement:WeuseTZQueryorTZReadOnlyQuery toestablishthemaster/detailconnection: MasterSQL: SELECT id, feld1, feld2, feld3 FROM master [*]DetailSQL: SELECT feld1, feld2, master_id FROM detail WHERE master_id = :id Parameter:idstandsforthecontentofmaster's"id"field(istheprimarykey)becausethemaster's DataSourceisassignedtothepropertyDataSourceofthedetail.Sothisparameterreferencestothe"id" fieldofthemaster.Therield"master_id"indetailqueryistheforeignkeyfieldofthedetailtablewhich referencestheprimarykeyofthemaster. Ifthecursorofthemasterchangesitspositionwhileserversidedfiltersareused,theSQLstatementofthe detailisexecutedusingthecurrentkeyvalues.Sotheresultsetofthedetailisautomaticallyrefreshed. Master/Detailwithclientsidedfilters ThisisthedefaultbehaviourofaBDETTablecomponent.Hereamaster/detailconnectionbetweentwo DataSetsisestablishedasfollows: TheDataSourceofthemasterisassignedtothepropertyMasterDataSourceofthedetail. TheprimarykeyfieldsofthemasterareassignedtopropertyMasterFieldofthedetail. Theforeignkeyofthedetailwhichreferencestheprimarykeyofthemasterisassignedtopropety IndexFieldNames.

Thisisanexampleforasimplemaster/detailqueries.Requirement:WeuseTZQueryorTZReadOnlyQuery toestablishthemaster/detailconnection: MasterSQL: SELECT id, feld1, feld2, feld3 FROM master DetailSQL: SELECT feld1, feld2, master_id FROM detail WHERE master_id = :id Parameter:idstandsforthecontentofmaster's"id"field(istheprimarykey)becausethemaster's DataSourceisassignedtothepropertyDataSourceofthedetail.Sothisparameterreferencestothe"id"

fieldofthemaster.Therield"master_id"indetailqueryistheforeignkeyfieldofthedetailtablewhich referencestheprimarykeyofthemaster. Ifthecursorofthemasterchangesitspositionwhileserversidedfiltersareused,theSQLstatementofthe detailisexecutedusingthecurrentkeyvalues.Sotheresultsetofthedetailisautomaticallyrefreshed. Master/Detailwithclientsidedfilters ThisisthedefaultbehaviourofaBDETTablecomponent.Hereamaster/detailconnectionbetweentwo DataSetsisestablishedasfollows: TheDataSourceofthemasterisassignedtothepropertyMasterDataSourceofthedetail. TheprimarykeyfieldsofthemasterareassignedtopropertyMasterFieldofthedetail. Theforeignkeyofthedetailwhichreferencestheprimarykeyofthemasterisassignedtopropety IndexFieldNames.

WithclientsidedfiltersbothDataSetsfirsttransferalltablerowsfromservertoclient.Thedetailthensetsa filter(onclientside)togetthedetailsaccordingtothecurrentmasterrecord. Incaseofcreatinganewdetailrecordforamaster/detailconnectionwithaclientsidedfilterthereisakindof automatism:TheForeignkeyfieldsofthedetail(setinpropertyIndexFieldNamesofthedetail)willbefilled automaticallywiththeaccording(current)primarykeydataofthemaster(setinpropteryMasterFieldofthe detail).Note:Withserversidedfiltersyouhavetocareaboutthisfunctionality,manuallyinyourprogram's code.ThiscanbeachievedbyimplementingtheOnNewRecordeventofthedetail.Thiseventisalways triggeredwhenannewrecordistobecreated(see:DelphionlinehelpforTDataSet).AccordingtotheSQL statements,definedaboveyouonlyhavetoimplementthefollowing: Procedure dmMasterDetail.qryDetailNewRecord (DataSet: TDataSet); Begin qryDetailMASTER_ID.Value := qryMasterID.Value; End; CorrespondingTFieldswerecreatedforthefields"master_id"ofthedetailand"id"ofthemasterusingthe fieldeditor. Formaster/detailconnectionsinZEOSthereisanadditionaloptionthatissetinpropertyOptions:Itis doAlwaysResyncDetail.Ifthisoptionissetthentheresultsetofthedetailisonlyrefreshedwhenpostis calledorarecordchanges(bothwithinmasterDataSet). Master/Detail"byhand" Normallyyouimplementamaster/detailconnectionaccordingtothemethodusedbyserversidedfilters.The SQLstatementsforthislookexactlylikethat.Onlythepropertiesthataresetinmasteranddetail(see above)willnotbesethere.BothTZQuerisareworkingindependently.Thismeans:ThedetailDataSetdoes notrecognizeanychangesinmasterDataSet.Itssynchronzationhastobeimplemented,manually.Thiswill bedoneintheOnChangeeventofthemaster.OnChangeistriggeredwhenchangingtoanewrecordor fielddatahasbeenchanged(see:DelphionlinehelpforTDataSource).Synchronizationofthedetail (accordingtotheexampleabove)wouldbeimplementedlikethis: Procedure dmMasterDetail.dsMasterDataChange ( Sender: TObject; Field: TField); Begin With qryDetail do Begin Close; ParamByName('id').Value := qryMasterID.Value; Open; End; End;

ThisisthesamefunctionthatZEOSexecutesautomaticallywhenusingserversidedfilters:Thedetailquery isexecuted(agin)withthecurrentIDvalueofthemasterwhichwillbeassignedtoparameter":id"inthe detailquery.Sotheresultsetofthedetailwillberefreshedaccordingtothecurrentmasterrecord. IfanewrecordshallbecreatedindetailDataSetthenyouhavetoactthesamewayaswithserversided filters(seeabove).

CachedUpdates
ThedevelopersoftheZEOSLibraryareintendedtoimplementthefunctionalityoftheBDEcomponentsas goodaspossible.ThisiswhythereisalsothepossibilityofcachedupdateswithZEOS.Youonlyhavetoset thepropertyCachedUpdatesofaDataSetdescendant(TZTable,TZQueryoderTZStoredProc)totrue.From thistimeonallchangesintheresultsetwillbecachedandtheycanbeeasilycommittedtothedatabaseby callingApplyUpdatesandCommitUpdatesoneaftertheothereitherautomaticallyinyourprogramcodeor triggeredmanuallybyauser.CancelUpdatescausesthatthecangeswillnotbecommittedtothedatabase. Inthiscaseallcachedchangeswillbereset(likeusingaROLLBACK).Hereyouwillfindalittlecodesnippet thattriestoshowyouhowcachedupdatesareimplemented(don'targueaboutthesenseinthis...). AutoCommitmodeofTZConnectinisturnedon(True): : With DataSet do Begin bEverythingOK := True; CachedUpdates := True; DataSet.First; While (not DataSet.EOF) and (bEverythingOK) do Begin DataSet.Edit; : // process record : DataSet.Post; DataSet.Next; : bEverythingOK := AFunctionForValidation; End; If bEverythingOK Then Begin ApplyUpdates; CommitUpdates; End Else CancelUpdates; CachedUpdates := False; End; :

BLOBFields
AccordingtoBDE'scomponentsthecomponentsoftheZEOSLibraryarecapableofhandlingBLOBfields. HereisanexamplehowanewrecordwithaBLOBfieldiscreated.TheBLOBfieldisfilledwithabitmap.To achievethiswehavetouseaStream: : Var TheStream : TMemoryStream; Begin TheStream := TMemoryStream.Create; Try Image1.Picture.Bitmap.Savetostream(TheStream); With qryBlobInsert do Begin Sql.Text := 'INSERT INTO EVENTS (EventNo,EVENT_PHOTO) ' + 'VALUES (100,:ThePicture)'; Params.Clear; Params.CreateParam(ftBlob,'ThePicture', ptInput); ParamByName('ThePicture').LoadfromStream(TheStream,ftBlob); ExecSQL; End; Finally TheStream.Free; End; End; : Thissectionaboutblobfieldsisnotcompleted,yet.PleasefeelfreetosendmeaprivatemessageoreMailif youhaveanyissuesaboutblobsinordertoexpandthissection.

Sampleproject:"EasyQuery"
TopreventbeingtootheoreticalnowwewillcreateasmallsampleprojectthodemonstratehowtheZEOS componentsareusedingeneral.Wewillcreateasmallapplicationthataccessesthetables"Customer"and "Country"oftheFirebirdsampledatbase"Employee".Youshouldbeabletonavigateintable"Customer" andedititsdata.AndnotbeintooboringwewillimplementaDBLookupComboboxforfield"Country"intable "Customer".Thisfieldisaforeignkeythatreferencestofield"Country"intable"Country". Solet'sgetstarted! FirstofallwehavetocreateanewprojectinDelphi.Additionalytothedefaultformwehavetocreatea DataModule. ThefollowingpropertiesoftheDataModulehavetobeset: Name:dmEasyQuery ComponentsfortheDataModule

TZConnection Database:Employee.fdb Name:conEmployee Password:"password" Protocol:firebird1.5 ReadOnly:False TransactionIsolationLevel:tiReadCommitted User:"username"

TZQuery Connection:conEmployee Name:qryCustomer RequestLive:True SQL:SELECT*FROMcustomerORDERBYcustomer UpdateObject:updCustomer

Note:YouhavetocreatepersistentTFieldsforalltablefieldsusingthefieldeditor! TheOnAfterPosteventofqryCustomerwillbeimplementedlikethis: procedure TdmEasyQuery.qryCustomerAfterPost(DataSet: TDataSet); begin // Refresh of resultset to actualize (sort) data shown in DBGrid. qryCustomer.Refresh; end;

TZReadOnlyQuery Connection:conEmployee Name:roqryCountry SQL:SELECTcountryFROMcountryORDERBY1

Note:YouhavetocreatepersistentTFieldsforalltablefieldsusingthefieldeditor! TZUpdateSQL DeleteSQL:createdbyUpdateSqleditor InsertSQL:createdbyUpdateSqleditor ModifySQL:createdbyUpdateSqleditor Name:updCustomer

Thedelete,insertandmodifyStatementsfortheTZUpdateSQLobjectarecreatedwiththeUpdateSQL editor,automatically.TheeditorwillbeactivatedbydoubleclickingontheTZUpdateSQLcomponent.Askey fieldyouhavetoselectthefieldCUST_NO.ThefieldsADDRESS_LINE1,ADDRESS_LINE2, CITY,STATE_PROVINCE,COUNTRYundPOSTAL_CODEwillselectedasupdatefieldsinlist"Update

Fields".Nowthestatementswillbegeneratedbyclickingbutton"GenerateSQL".Ifyouonlyhavesucheasy queriesyoucansavealotoftypingbyusingtheUpdateSQLeditor.Ifitgetsalittlemorcomplexyoushould createtheneededstatements"byhand".

TDataSource DataSet:sqlCustomer Name:dsCustomer

TDataSource DataSet:rosqlCountry Name:dsCountry

NowthecreatedDataModulewillbesavedasdm_EasyQuery.pas.[/list] Componentsfortheform

 Themainformwillhavethefollowingcomponentsandisinitializedasfollows: Properties Caption:EasyQueryDemo Name:frmEasyQuery IntheUnit'sinterfaceyouhavetoadddm_EasyQuerytotheusesclausetogetaccesstothe databasecomponents. Thefollowingeventsofthemainformhavetobeimplemented:: OnCreate Whencreatingtheformtheconnectiontothedatabasewillbeestablished.Afterconnectingtothe databasethequerieswillbeopened: procedure TForm1.FormCreate(Sender: TObject); begin dmEasyQuery.conEmployee.Connect; dmEasyQuery.qryCustomer.Open; dmEasyQuery.roqryCountry.Open; end; OnDestroy Whenclosingtheapplication(destroyingthemainform)thedatabaseconnectionwillbecut.All querieswillbeclosedautomaticallybeforedisconnecting. procedure TForm1.FormDestroy(Sender: TObject); begin dmEasyQuery.conEmployee.Disconnect; end; TLabel Caption:CUSTOMER

TDBGrid DataSource:dmEasyQuery.dsCustomer Options.dgTabs:False IncolumneditorwewillcreateaTColumnsettingitspropertyFieldNameto"CUSTOMER".Afterthat theaccordingcolumninDBGrid1willbeenlarged.

TDBEdit (5x) TLabel] (5x) TheseobjectswillbecreatedbyusingthecolumneditorofqryCustomer:Selectcolumns ADDRESS_LINE1,ADDRESS_LINE2,CITY,STATE_PROVINCEandPOSTAL_CODEanddragand dropthemontothenmainform.Alignthemandadaptthemtothelayoutyouseeinthescreenshot. TLabel Caption:COUNTRY TDBLookUpComboBox DataField:COUNTRY DataSource:dmEasyQuery.dsCustomer KeyField:COUNTRY ListField:COUNTRY ListSource:dmEasyQuery.dsCountry TDBNavigator DataSource:dmEasyQuery.dsCustomer

Nowthecreatedformwillbesavedasfrm_EasyQuery.pas.

Note:Thefollowingprojectoptionshavetobechanged: dmEasyQueryhastobeplacedontopofthecreationorderinlist"Createautomatically".This ensuresthatallobjectsoffrmEasyQuerymayaccessthedatabaseobjects.frmEasyQueryisstill themainform.

AdditionalExamples
FishFact ThisisthemostpopulardatabasedemoforDelphi.ItwasmigratedtouseZEOScomponents. Transactions Asampleapplicationconcerning"transactionswithZEOS".Itusesasmallselfmadetestdatabase. StoredProc Thisisasampleapplikationthatshowshowtousestoredproecedures.ThedatabaseistheFirebird Employeesampledatabase. MasterDetail Asmallapplicationthatshowshowmaster/detailconnections(serverandclientsided)willbeimplemented. EventDemo AlsoaDelphidatabasesamplethatwasmigratedfromIBXtoZEOS.ItusesthecomponentTIBEventAlerter. ThisapplicationneedsthedatabaseEvents(shippedwithDelphi)thathadtobemigratedtodialect3toget thissamplerunning. YouwillfindtheseExamplesherefordownload. AdownloadablePDFVersionofthisTutorialisalsoonitsway!

MichaelSeeger ZeosLibDevelopmentTeam