ViewVC Help
View File | Revision Log | Show Annotations | Download File | View Changeset | Root Listing
root/public/ibx/branches/udr/client/IB.pas
Revision: 364
Committed: Tue Dec 7 13:30:09 2021 UTC (2 years, 3 months ago) by tony
Content type: text/x-pascal
Original Path: ibx/branches/journaling/fbintf/IB.pas
File size: 67408 byte(s)
Log Message:
Fixes merged

File Contents

# User Rev Content
1 tony 45 (*
2     * Firebird Interface (fbintf). The fbintf components provide a set of
3     * Pascal language bindings for the Firebird API. Although predominantly
4     * a new development they include source code taken from IBX and may be
5     * considered a derived product. This software thus also includes the copyright
6     * notice and license conditions from IBX.
7     *
8     * Except for those parts dervied from IBX, contents of this file are subject
9     * to the Initial Developer's Public License Version 1.0 (the "License"); you
10     * may not use this file except in compliance with the License. You may obtain a
11     * copy of the License here:
12     *
13     * http://www.firebirdsql.org/index.php?op=doc&id=idpl
14     *
15     * Software distributed under the License is distributed on an "AS
16     * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
17     * implied. See the License for the specific language governing rights
18     * and limitations under the License.
19     *
20     * The Initial Developer of the Original Code is Tony Whyman.
21     *
22     * The Original Code is (C) 2016 Tony Whyman, MWA Software
23     * (http://www.mwasoftware.co.uk).
24     *
25     * All Rights Reserved.
26     *
27     * Contributor(s): ______________________________________.
28     *
29     *)
30     {************************************************************************}
31     { }
32     { Borland Delphi Visual Component Library }
33     { InterBase Express core components }
34     { }
35     { Copyright (c) 1998-2000 Inprise Corporation }
36     { }
37     { InterBase Express is based in part on the product }
38     { Free IB Components, written by Gregory H. Deatz for }
39     { Hoagland, Longo, Moran, Dunst & Doukas Company. }
40     { Free IB Components is used under license. }
41     { }
42     { The contents of this file are subject to the InterBase }
43     { Public License Version 1.0 (the "License"); you may not }
44     { use this file except in compliance with the License. You }
45     { may obtain a copy of the License at http://www.Inprise.com/IPL.html }
46     { Software distributed under the License is distributed on }
47     { an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either }
48     { express or implied. See the License for the specific language }
49     { governing rights and limitations under the License. }
50     { The Original Code was created by InterBase Software Corporation }
51     { and its successors. }
52     { Portions created by Inprise Corporation are Copyright (C) Inprise }
53     { Corporation. All Rights Reserved. }
54     { Contributor(s): Jeff Overcash }
55     { }
56     { IBX For Lazarus (Firebird Express) }
57     { Contributor: Tony Whyman, MWA Software http://www.mwasoftware.co.uk }
58     { Portions created by MWA Software are copyright McCallum Whyman }
59     { Associates Ltd 2011 - 2015 }
60     { }
61     {************************************************************************}
62     unit IB;
63 tony 56 {$IFDEF MSWINDOWS}
64     {$DEFINE WINDOWS}
65     {$ENDIF}
66 tony 45
67     {$IFDEF FPC}
68 tony 56 {$mode delphi}
69 tony 45 {$codepage UTF8}
70     {$interfaces COM}
71 tony 56 {$IF defined(FPC) and (FPC_FULLVERSION < 30000) }
72 tony 45 {$ERROR FPC Version 3.0.0 or later is required}
73 tony 56 {$IFEND}
74 tony 45 {$ENDIF}
75    
76 tony 270 {$IFNDEF LEGACYFIREBIRDAPIONLY}
77 tony 45 {$DEFINE USEFIREBIRD3API}
78 tony 270 {$ENDIF}
79     {$IFNDEF FIREBIRD3APIONLY}
80 tony 45 {$DEFINE USELEGACYFIREBIRDAPI}
81 tony 270 {$ENDIF}
82 tony 45
83     {
84     This unit defines the interfaces used to provide the Pascal Language
85     bindings for the Firebird API. These are COM style references counted interfaces
86     and are automatically freed when they go out of scope.
87    
88     The interface definition is independent of the Firebird API version and two
89     implementations are provided. One is for the legacy API (2.5 and earlier) and the
90     other is for the new object orientated API (3.0 and later). By default, both are
91     available with the 3.0 API used if it is available. Otherwise the 2.5 API is used.
92     The above two defines can be used to force only one implementation by undefining
93     the symbol for the unwanted API.
94    
95     Note that the FirebirdAPI function defined below is used for initial access to
96     the language bindings.
97    
98     The goals of these Pascal Langauge bindings are to provide:
99    
100     1. A set of reference counted interfaces providing complete access to the Firebird API.
101    
102     2. Application Independence from the Firebird API version.
103    
104     3. All data access through strongly typed variables and functions with no need for
105     the end user to manipulate untyped data in buffers such as the legacy API SQLDA
106     or the Firebird 3.0 message buffer.
107    
108     4. A stable platform for LCL Packages (e.g. IBX) that implement the TDataSet model
109     with independence from the Firebird API version.
110    
111     5. Straightforward progammatic access to the Firebird API from Pascal programs.
112    
113 tony 56 6. FPC and Delphi Support.
114    
115 tony 45 String Types
116     ============
117    
118     From FPC 3.0 onwards, ANSISTRINGs include the codepage in their definition. All
119     strings used by the interface are sensitive to the codepage in that the codepage
120     for all strings returned by an interface is consistent with the SQL Character set
121     used for the database connection. Input strings will be transliterated, where possible
122     and if necessary, to the codepage consistent with the character set used for
123     the database connection.
124     }
125    
126     interface
127    
128     uses
129 tony 263 Classes,
130     {$IFDEF WINDOWS}Windows, {$ENDIF}
131     {$IFDEF FPC} Dynlibs, {$ENDIF}
132 tony 315 SysUtils, DB, FBMessages, IBExternals, FmtBcd;
133 tony 45
134 tony 47 const
135     {Interface version information}
136     FBIntf_Major = 1;
137 tony 364 FBIntf_Minor = 4;
138     FBIntf_Release = 0;
139     FBIntf_Version = '1.4.0';
140 tony 47
141 tony 315 const
142     {DPB, TPB and SPB Parameter Block Name Prefixes}
143     DPBPrefix = 'isc_dpb_';
144     TPBPrefix = 'isc_tpb_';
145    
146     const
147     {Time Zone ID constraint}
148     MaxOffsetTimeZoneID = 2879; {lower values represent a time zone offset between
149     -23:59 and 23:59. Higher values are keys to the
150     Time Zone database.}
151    
152     TimeZoneID_GMT = 23*minsPerHour + 59;
153     decimillisecondsPerSecond = 10000;
154     TimeZoneDisplacementDelta = 60*23 + 59; {23:59 in minutes}
155    
156 tony 45 {These include files are converted from the 'C' originals in the Firebird API
157     and define the various constants used by the API}
158    
159 tony 56 {$I 'include/consts_pub.inc'}
160 tony 315 {$I 'include/dyn_consts.inc'}
161 tony 56 {$I 'include/inf_pub.inc'}
162     {$I 'include/configkeys.inc'}
163 tony 315 {$I 'include/blr.inc'}
164 tony 45
165     {The following constants define the values return by calls to the GetSQLType
166     methods provided by several of the interfaces defined below.}
167    
168     (*********************)
169     (** SQL definitions **)
170     (*********************)
171     SQL_VARYING = 448;
172     SQL_TEXT = 452;
173     SQL_DOUBLE = 480;
174     SQL_FLOAT = 482;
175     SQL_LONG = 496;
176     SQL_SHORT = 500;
177     SQL_TIMESTAMP = 510;
178     SQL_BLOB = 520;
179     SQL_D_FLOAT = 530;
180     SQL_ARRAY = 540;
181     SQL_QUAD = 550;
182     SQL_TYPE_TIME = 560;
183     SQL_TYPE_DATE = 570;
184     SQL_INT64 = 580;
185 tony 315 SQL_TIMESTAMP_TZ_EX = 32748;
186     SQL_TIME_TZ_EX = 32750;
187     SQL_INT128 = 32752;
188 tony 45 SQL_BOOLEAN = 32764;
189 tony 315 SQL_TIMESTAMP_TZ = 32754;
190     SQL_TIME_TZ = 32756;
191     SQL_DEC_FIXED = 32758; {FB4 Beta 1 only}
192     SQL_DEC16 = 32760;
193     SQL_DEC34 = 32762;
194     SQL_NULL = 32766;
195 tony 45 SQL_DATE = SQL_TIMESTAMP;
196    
197     type
198     TGDS_QUAD = record
199     gds_quad_high : ISC_LONG;
200     gds_quad_low : UISC_LONG;
201     end;
202     TGDS__QUAD = TGDS_QUAD;
203     TISC_QUAD = TGDS_QUAD;
204     PGDS_QUAD = ^TGDS_QUAD;
205     PGDS__QUAD = ^TGDS__QUAD;
206     PISC_QUAD = ^TISC_QUAD;
207    
208 tony 56 {$IFNDEF FPC}
209 tony 263 {Delphi missing definitions}
210     type
211     TLibHandle = THandle;
212    
213     const
214     NilHandle = 0;
215     DirectorySeparator = '\';
216    
217 tony 56 {Delphi only seems to define CP_UTF8 and CP_UTF16}
218     const
219     CP_ACP = 0; // default to ANSI code page
220     CP_OEMCP = 1; // default to OEM (console) code page
221     CP_UTF16BE = 1201; // unicodeFFFE
222     CP_UTF7 = 65000; // utf-7
223     CP_ASCII = 20127; // us-ascii
224     CP_NONE = $FFFF; // rawbytestring encoding
225    
226     {$ENDIF}
227    
228     type
229     {$IF not declared(TSystemCodePage)}
230     TSystemCodePage = word; {not defined in Delphi}
231     {$IFEND}
232    
233 tony 45 TIBSQLStatementTypes =
234     (SQLUnknown, SQLSelect, SQLInsert,
235     SQLUpdate, SQLDelete, SQLDDL,
236     SQLGetSegment, SQLPutSegment,
237     SQLExecProcedure, SQLStartTransaction,
238     SQLCommit, SQLRollback,
239 tony 291 SQLSelectForUpdate, SQLSetGenerator,
240     SQLSavePoint);
241 tony 45
242     TFBStatusCode = cardinal;
243     TByteArray = array of byte;
244 tony 315 TFBTimeZoneID = ISC_USHORT;
245 tony 45
246 tony 263 IFirebirdAPI = interface;
247 tony 45 IAttachment = interface;
248     ITransaction = interface;
249 tony 291 IStatement = interface;
250 tony 45
251 tony 56 {The IParameterBlock interface provides the template for all parameter
252 tony 45 block interfaces}
253    
254 tony 56 IParameterBlock<_IItem> = interface
255 tony 45 function getCount: integer;
256     function Add(ParamType: byte): _IItem;
257     function getItems(index: integer): _IItem;
258     function Find(ParamType: byte): _IItem;
259     procedure PrintBuf; {can be used to print buffer in hex for debugging}
260     property Count: integer read getCount;
261     property Items[index: integer]: _IItem read getItems; default;
262     end;
263    
264 tony 315 IParameterBlockWithTypeNames<_IItem> = interface(IParameterBlock<_IItem>)
265     function AddByTypeName(ParamTypeName: AnsiString): _IItem;
266 tony 345 function GetDPBParamTypeName(ParamType: byte): Ansistring; deprecated 'Use Get ParamTypeName';
267     function GetParamTypeName(ParamType: byte): Ansistring;
268 tony 315 end;
269    
270 tony 45 {IParameterBlockItem is not used on its own but instead provides a base type for
271     different parameter block items }
272    
273     IParameterBlockItem = interface
274 tony 56 ['{53b23f7b-abda-46a5-9aa5-07bd5e723266}']
275 tony 45 function getParamType: byte;
276     function getAsInteger: integer;
277 tony 56 function getAsString: AnsiString;
278 tony 45 function getAsByte: byte;
279 tony 56 procedure setAsString(aValue: AnsiString);
280 tony 45 procedure setAsByte(aValue: byte);
281     procedure SetAsInteger(aValue: integer);
282 tony 56 property AsString: AnsiString read getAsString write setAsString;
283 tony 45 property AsByte: byte read getAsByte write setAsByte;
284     property AsInteger: integer read getAsInteger write SetAsInteger;
285     end;
286    
287 tony 315 IParameterBlockItemWithTypeName = interface(IParameterBlockItem)
288     function getParamTypeName: AnsiString;
289     end;
290 tony 45
291     {The IStatus interface provides access to error information, if any, returned
292     by the last API call. It can also be used to customise the error message
293     returned by a database engine exception - see EIBInterbaseError.
294    
295     This interface can be accessed from IFirebirdAPI.
296     }
297    
298 tony 291 TIBDataBaseErrorMessage = (ShowSQLCode,
299     ShowIBMessage,
300     ShowSQLMessage);
301    
302     TIBDataBaseErrorMessages = set of TIBDataBaseErrorMessage;
303    
304 tony 345 TStatusCode = long;
305    
306 tony 45 IStatus = interface
307 tony 56 ['{34167722-af38-4831-b08a-93162d58ede3}']
308 tony 345 function GetIBErrorCode: TStatusCode;
309     function Getsqlcode: TStatusCode;
310 tony 56 function GetMessage: AnsiString;
311 tony 45 function CheckStatusVector(ErrorCodes: array of TFBStatusCode): Boolean;
312     function GetIBDataBaseErrorMessages: TIBDataBaseErrorMessages;
313     procedure SetIBDataBaseErrorMessages(Value: TIBDataBaseErrorMessages);
314     end;
315    
316     { The array metadata interface provides access to the metadata used to describe
317     an array column in a Firebird table.
318     }
319    
320     TArrayBound = record
321     UpperBound: short;
322     LowerBound: short;
323     end;
324     TArrayBounds = array of TArrayBound;
325    
326     IArrayMetaData = interface
327 tony 56 ['{7dd0aea4-59af-4c2a-b958-565d5025c489}']
328 tony 45 function GetSQLType: cardinal;
329 tony 56 function GetSQLTypeName: AnsiString;
330 tony 45 function GetScale: integer;
331     function GetSize: cardinal;
332 tony 309 function GetCharSetWidth: integer;
333 tony 45 function GetCharSetID: cardinal;
334 tony 56 function GetTableName: AnsiString;
335     function GetColumnName: AnsiString;
336 tony 45 function GetDimensions: integer;
337     function GetBounds: TArrayBounds;
338     end;
339    
340     {The array interface provides access to and modification of the array data
341     contained in an array field of a Firebird Table. The array element is
342     selected by specifying its co-ordinates using an integer array. The
343     getter and setter methods used should be appropriate for the type of data
344     contained in the array. Automatic conversion is provided to and from strings.
345     That is GetAsString and SetAsString are safe to use for sql types other than
346     boolean.
347    
348     The interface is returned by a GetAsArray getter method (see ISQLData). A new array
349     can be obtained from the IAttachment interface. The SetAsArray setter method
350     (See ISQLParam) is used to apply an updated or new array to the database using
351     an UPDATE or INSERT statement.
352    
353     }
354    
355     TArrayEventReason = (arChanging,arChanged);
356     IArray = interface;
357     TArrayEventHandler = procedure(Sender: IArray; Reason: TArrayEventReason) of object;
358    
359     IArray = interface(IArrayMetaData)
360 tony 56 ['{631c6bb1-fb49-44fb-a64a-c49859632b88}']
361 tony 45 function GetArrayID: TISC_QUAD;
362     procedure Clear;
363     function IsEmpty: boolean;
364     procedure PreLoad;
365     procedure CancelChanges;
366     procedure SaveChanges;
367     function GetAsInteger(index: array of integer): integer;
368     function GetAsBoolean(index: array of integer): boolean;
369     function GetAsCurrency(index: array of integer): Currency;
370     function GetAsInt64(index: array of integer): Int64;
371 tony 315 function GetAsDateTime(index: array of integer): TDateTime; overload;
372     procedure GetAsDateTime(index: array of integer; var aDateTime: TDateTime; var dstOffset: smallint; var aTimezoneID: TFBTimeZoneID); overload;
373     procedure GetAsDateTime(index: array of integer; var aDateTime: TDateTime; var dstOffset: smallint; var aTimezone: AnsiString); overload;
374     procedure GetAsTime(index: array of integer; var aTime: TDateTime; var dstOffset: smallint; var aTimezoneID: TFBTimeZoneID; OnDate: TDateTime); overload;
375     procedure GetAsTime(index: array of integer; var aTime: TDateTime; var dstOffset: smallint; var aTimezone: AnsiString; OnDate: TDateTime); overload;
376     function GetAsUTCDateTime(index: array of integer): TDateTime;
377 tony 45 function GetAsDouble(index: array of integer): Double;
378     function GetAsFloat(index: array of integer): Float;
379     function GetAsLong(index: array of integer): Long;
380     function GetAsShort(index: array of integer): Short;
381 tony 56 function GetAsString(index: array of integer): AnsiString;
382 tony 45 function GetAsVariant(index: array of integer): Variant;
383 tony 315 function GetAsBCD(index: array of integer): tBCD;
384 tony 45 procedure SetAsInteger(index: array of integer; AValue: integer);
385     procedure SetAsBoolean(index: array of integer; AValue: boolean);
386     procedure SetAsCurrency(index: array of integer; Value: Currency);
387     procedure SetAsInt64(index: array of integer; Value: Int64);
388     procedure SetAsDate(index: array of integer; Value: TDateTime);
389 tony 315 procedure SetAsDateTime(index: array of integer; Value: TDateTime); overload;
390     procedure SetAsDateTime(index: array of integer; aValue: TDateTime; aTimeZoneID: TFBTimeZoneID); overload;
391     procedure SetAsDateTime(index: array of integer; aValue: TDateTime; aTimeZone: AnsiString); overload;
392     procedure SetAsTime(index: array of integer; Value: TDateTime); overload;
393     procedure SetAsTime(index: array of integer; aValue: TDateTime; OnDate: TDateTime; aTimeZoneID: TFBTimeZoneID); overload;
394     procedure SetAsTime(index: array of integer; aValue: TDateTime; OnDate: TDateTime; aTimeZone: AnsiString); overload;
395     procedure SetAsUTCDateTime(index: array of integer; aUTCTime: TDateTime);
396 tony 45 procedure SetAsLong(index: array of integer; Value: Long);
397     procedure SetAsDouble(index: array of integer; Value: Double);
398     procedure SetAsFloat(index: array of integer; Value: Float);
399     procedure SetAsShort(index: array of integer; Value: Short);
400 tony 56 procedure SetAsString(index: array of integer; Value: AnsiString);
401 tony 45 procedure SetAsVariant(index: array of integer; Value: Variant);
402 tony 315 procedure SetAsBcd(index: array of integer; aValue: tBCD);
403 tony 45 procedure SetBounds(dim, UpperBound, LowerBound: integer);
404     function GetAttachment: IAttachment;
405     function GetTransaction: ITransaction;
406     procedure AddEventHandler(Handler: TArrayEventHandler);
407     procedure RemoveEventHandler(Handler: TArrayEventHandler);
408     end;
409    
410     { The Blob metadata interface provides access to the metadata used to describe
411     a blob column in a Firebird table.
412     }
413    
414     IBlobMetaData = interface
415 tony 56 ['{575f3c61-bb33-46a5-8975-bb7d1b6e37cc}']
416 tony 45 function GetSubType: integer;
417     function GetCharSetID: cardinal;
418     function GetCodePage: TSystemCodePage;
419     function GetSegmentSize: cardinal;
420 tony 56 function GetRelationName: AnsiString;
421     function GetColumnName: AnsiString;
422 tony 45 end;
423    
424     {The Blob Parameter block is used to select a Blob Filter}
425    
426 tony 56 IBPBItem = interface (IParameterBlockItem)
427     ['{660822a5-3114-4c16-b6cb-c1a7b2aba70d}']
428     end;
429 tony 45
430 tony 87 IBPB = interface (IParameterBlock<IBPBItem>)
431 tony 56 ['{e0cb9eb5-17f7-4416-b7d1-3cddd1dfca76}']
432     end;
433 tony 45
434     { The Blob Interface provides access to a blob data item.
435    
436     The interface is returned by a GetAsBlob getter method (see ISQLData). A new Blob
437     can be obtained from the IAttachment interface. The SetAsBlob setter method
438     (See ISQLParam) is used to apply an updated or new array to the database using
439     an UPDATE or INSERT statement.
440     }
441    
442     TFBBlobMode = (fbmRead,fbmWrite);
443     TBlobType = (btSegmented,btStream);
444    
445     IBlob = interface(IBlobMetaData)
446 tony 56 ['{3090a145-7780-442b-b15b-efd4568b8611}']
447 tony 45 function GetBPB: IBPB;
448     procedure Cancel;
449     procedure Close;
450     function GetBlobID: TISC_QUAD;
451     function GetBlobMode: TFBBlobMode;
452     function GetBlobSize: Int64;
453     procedure GetInfo(var NumSegments: Int64; var MaxSegmentSize,
454     TotalSize: Int64; var BlobType: TBlobType);
455     function Read(var Buffer; Count: Longint): Longint;
456     function Write(const Buffer; Count: Longint): Longint;
457 tony 56 function LoadFromFile(Filename: AnsiString): IBlob;
458 tony 45 function LoadFromStream(S: TStream) : IBlob;
459 tony 56 function SaveToFile(Filename: AnsiString): IBlob;
460 tony 45 function SaveToStream(S: TStream): IBlob;
461     function GetAsString: rawbytestring;
462     procedure SetAsString(aValue: rawbytestring);
463     function SetString(aValue: rawbytestring): IBlob;
464     function GetAttachment: IAttachment;
465     function GetTransaction: ITransaction;
466     property AsString: rawbytestring read GetAsString write SetAsString;
467     end;
468    
469     { The IColumnMetaData interface provides access to the per column metadata for
470     the output of an SQL Statement.
471     }
472    
473 tony 270 TIBDateTimeFormats = (dfTimestamp, {SQL TIMESTAMP}
474     dfDateTime, {SQL DATETIME}
475 tony 315 dfTime, {SQL TIME}
476     dfTimestampTZ, {SQL_TIMESTAMP_TZ}
477     dfTimeTZ); {SQLTIME_TZ
478 tony 270
479 tony 45 { IColumnMetaData }
480    
481     IColumnMetaData = interface
482 tony 56 ['{c222e6c3-53c1-469f-9e05-0a5c3ef232d8}']
483 tony 45 function GetIndex: integer;
484     function GetSQLType: cardinal;
485 tony 56 function GetSQLTypeName: AnsiString;
486 tony 45 function getSubtype: integer;
487 tony 56 function getRelationName: AnsiString;
488     function getOwnerName: AnsiString;
489     function getSQLName: AnsiString; {Name of the column}
490     function getAliasName: AnsiString; {Alias Name of column or Column Name if no alias}
491     function getName: AnsiString; {Disambiguated uppercase Field Name}
492 tony 45 function getScale: integer;
493     function getCharSetID: cardinal;
494     function getCodePage: TSystemCodePage;
495 tony 310 function GetCharSetWidth: integer;
496 tony 45 function getIsNullable: boolean;
497     function GetSize: cardinal;
498     function GetArrayMetaData: IArrayMetaData; {Valid only for Array SQL Type}
499     function GetBlobMetaData: IBlobMetaData; {Valid only for Blob SQL Type}
500 tony 270 function GetDateTimeStrLength(DateTimeFormat: TIBDateTimeFormats): integer;
501 tony 291 function GetStatement: IStatement;
502     function GetTransaction: ITransaction;
503 tony 56 property Name: AnsiString read GetName;
504 tony 45 property Size: cardinal read GetSize;
505     property SQLType: cardinal read GetSQLType;
506     property Scale: integer read getScale;
507     property SQLSubtype: integer read getSubtype;
508     property IsNullable: Boolean read GetIsNullable;
509     end;
510    
511     {
512     The IMetaData interface provides access to the set of column metadata
513     for the output of an SQL Statement
514     }
515    
516     { IMetaData }
517    
518     IMetaData = interface
519 tony 56 ['{4dafdbb6-0d36-4f1f-9c95-8b132804b965}']
520 tony 45 function getCount: integer;
521     function getColumnMetaData(index: integer): IColumnMetaData;
522 tony 56 function GetUniqueRelationName: AnsiString; {Non empty if all columns come from the same table}
523     function ByName(Idx: AnsiString): IColumnMetaData;
524 tony 45 property ColMetaData[index: integer]: IColumnMetaData read getColumnMetaData; default;
525     property Count: integer read getCount;
526     end;
527    
528     {
529     The ISQLData interface provides access to the data returned in a field in the
530     current row returned from a query or the result of an SQL Execute statement.
531    
532     It subclasses IColumnMetaData and so also provides access to the metadata
533     associated with the column.
534    
535     The getter and setter methods, and the corresponding properties, provide typed
536     access to the field data. The method/property used should be consistent
537     with the SQL Type. Automatic conversion is provided from strings.
538     That is GetAsString is safe to use for sql types other than boolean.
539     }
540    
541    
542     ISQLData = interface(IColumnMetaData)
543 tony 56 ['{3f493e31-7e3f-4606-a07c-b210b9e3619d}']
544 tony 291 function GetStrDataLength: short;
545 tony 45 function GetAsBoolean: boolean;
546     function GetAsCurrency: Currency;
547     function GetAsInt64: Int64;
548 tony 315 function GetAsDateTime: TDateTime; overload;
549     procedure GetAsDateTime(var aDateTime: TDateTime; var dstOffset: smallint; var aTimezoneID: TFBTimeZoneID); overload;
550     procedure GetAsDateTime(var aDateTime: TDateTime; var dstOffset: smallint; var aTimezone: AnsiString); overload;
551     procedure GetAsTime(var aTime: TDateTime; var dstOffset: smallint; var aTimezoneID: TFBTimeZoneID; OnDate: TDateTime); overload;
552     procedure GetAsTime(var aTime: TDateTime; var dstOffset: smallint; var aTimezone: AnsiString; OnDate: TDateTime); overload;
553     procedure GetAsTime(var aTime: TDateTime; var dstOffset: smallint; var aTimezoneID: TFBTimeZoneID); overload;
554     procedure GetAsTime(var aTime: TDateTime; var dstOffset: smallint; var aTimezone: AnsiString); overload;
555     function GetAsUTCDateTime: TDateTime;
556 tony 45 function GetAsDouble: Double;
557     function GetAsFloat: Float;
558     function GetAsLong: Long;
559     function GetAsPointer: Pointer;
560     function GetAsQuad: TISC_QUAD;
561     function GetAsShort: short;
562 tony 56 function GetAsString: AnsiString;
563 tony 45 function GetIsNull: Boolean;
564     function GetAsVariant: Variant;
565     function GetAsBlob: IBlob; overload;
566     function GetAsBlob(BPB: IBPB): IBlob; overload;
567     function GetAsArray: IArray;
568 tony 315 function GetAsBCD: tBCD;
569 tony 45 property AsDate: TDateTime read GetAsDateTime;
570     property AsBoolean:boolean read GetAsBoolean;
571     property AsTime: TDateTime read GetAsDateTime;
572     property AsDateTime: TDateTime read GetAsDateTime ;
573     property AsDouble: Double read GetAsDouble;
574     property AsFloat: Float read GetAsFloat;
575     property AsCurrency: Currency read GetAsCurrency;
576     property AsInt64: Int64 read GetAsInt64 ;
577     property AsInteger: Integer read GetAsLong;
578     property AsLong: Long read GetAsLong;
579     property AsPointer: Pointer read GetAsPointer;
580     property AsQuad: TISC_QUAD read GetAsQuad;
581     property AsShort: short read GetAsShort;
582 tony 56 property AsString: AnsiString read GetAsString;
583 tony 45 property AsVariant: Variant read GetAsVariant ;
584     property AsBlob: IBlob read GetAsBlob;
585     property AsArray: IArray read GetAsArray;
586 tony 315 property AsBCD: tBCD read GetAsBCD;
587 tony 45 property IsNull: Boolean read GetIsNull;
588     property Value: Variant read GetAsVariant;
589     end;
590    
591     { An IResults interface is returned as the result of an SQL Execute statement
592     and provides access to the fields returned, if any. It is a collection of
593     ISQLData interfaces which are, in turn, used to access the data returned by
594     each field of the result set.
595     }
596    
597     IResults = interface
598 tony 56 ['{e836b2bb-93d1-4bbf-a8eb-7ce535de3bb5}']
599 tony 45 function getCount: integer;
600 tony 291 function GetStatement: IStatement;
601 tony 45 function GetTransaction: ITransaction;
602 tony 56 function ByName(Idx: AnsiString): ISQLData;
603 tony 45 function getSQLData(index: integer): ISQLData;
604 tony 56 procedure GetData(index: integer; var IsNull:boolean; var len: short; var data: PByte);
605 tony 45 procedure SetRetainInterfaces(aValue: boolean);
606     property Data[index: integer]: ISQLData read getSQLData; default;
607     property Count: integer read getCount;
608     end;
609    
610     { An IResultSet interface is returned as the result of an SQL Open Cursor statement
611     (e.g. Select Statement) and provides access to the fields returned, if any
612     for the current row. It is a collection of ISQLData interfaces which are,
613     in turn, used to access the data returned by each field of the current row.
614     }
615     IResultSet = interface(IResults)
616 tony 56 ['{0ae4979b-7857-4e8c-8918-ec6f155b51a0}']
617 tony 350 function FetchNext: boolean; {fetch next record}
618     function FetchPrior: boolean; {fetch previous record}
619     function FetchFirst:boolean; {fetch first record}
620     function FetchLast: boolean; {fetch last record}
621     function FetchAbsolute(position: Integer): boolean; {fetch record by its absolute position in result set}
622     function FetchRelative(offset: Integer): boolean; {fetch record by position relative to current}
623 tony 56 function GetCursorName: AnsiString;
624 tony 350 function IsBof: boolean;
625 tony 45 function IsEof: boolean;
626     procedure Close;
627     end;
628    
629     {The ISQLParam interface is used to provide access to each parameter in a
630 tony 349 parametised SQL Statement. The interface comprises the Setter Methods and properties used to
631 tony 45 set the value of each parameter.
632    
633     Automatic conversion is provided to and from strings. That is GetAsString and
634     SetAsString are safe to use for sql types other than boolean - provided automatic
635     conversion is possible.
636 tony 349
637     ISQLParam is subclassed from the IParamMetaData interface. This interface provides
638     access to the parameter metadata. This metadata is mutable and can change after
639     a parameter is set to a given value. This is acceptable as long as the parameter
640     metadata is type compatible with the underlying column metadata and hence the
641     parameter value can be converted by Firebird into a value acceptable by the
642     underlying column. The column metadata, which is unmutable, can be obtained
643     by the ISQLParam.getColMetadata interface. When a statement is prepared, the
644     parameter metadata is always initialised to the column metadata.
645 tony 45 }
646    
647 tony 349 IParamMetaData = interface
648     ['{4e148c4e-2d48-4991-a263-f66eca05c6aa}']
649 tony 45 function GetSQLType: cardinal;
650 tony 56 function GetSQLTypeName: AnsiString;
651 tony 45 function getSubtype: integer;
652     function getScale: integer;
653     function getCharSetID: cardinal;
654     function getCodePage: TSystemCodePage;
655     function getIsNullable: boolean;
656     function GetSize: cardinal;
657 tony 349 property SQLType: cardinal read GetSQLType;
658     end;
659    
660     ISQLParam = interface(IParamMetaData)
661     ['{b22b4578-6d41-4807-a9a9-d2ec8d1d5a14}']
662     function getColMetadata: IParamMetaData;
663     function GetIndex: integer;
664     function getName: AnsiString;
665 tony 45 function GetAsBoolean: boolean;
666     function GetAsCurrency: Currency;
667     function GetAsInt64: Int64;
668 tony 315 function GetAsDateTime: TDateTime; overload;
669     procedure GetAsDateTime(var aDateTime: TDateTime; var dstOffset: smallint; var aTimezoneID: TFBTimeZoneID); overload;
670     procedure GetAsDateTime(var aDateTime: TDateTime; var dstOffset: smallint; var aTimezone: AnsiString); overload;
671     procedure GetAsTime(var aTime: TDateTime; var dstOffset: smallint; var aTimezoneID: TFBTimeZoneID; OnDate: TDateTime); overload;
672     procedure GetAsTime(var aTime: TDateTime; var dstOffset: smallint; var aTimezone: AnsiString; OnDate: TDateTime); overload;
673     procedure GetAsTime(var aTime: TDateTime; var dstOffset: smallint; var aTimezoneID: TFBTimeZoneID); overload;
674     procedure GetAsTime(var aTime: TDateTime; var dstOffset: smallint; var aTimezone: AnsiString); overload;
675     function GetAsUTCDateTime: TDateTime;
676 tony 45 function GetAsDouble: Double;
677     function GetAsFloat: Float;
678     function GetAsLong: Long;
679     function GetAsPointer: Pointer;
680     function GetAsQuad: TISC_QUAD;
681     function GetAsShort: short;
682 tony 56 function GetAsString: AnsiString;
683 tony 45 function GetIsNull: boolean;
684     function GetAsVariant: Variant;
685     function GetAsBlob: IBlob;
686     function GetAsArray: IArray;
687 tony 315 function GetAsBCD: tBCD;
688     function GetStatement: IStatement;
689     function GetTransaction: ITransaction;
690 tony 45 procedure Clear;
691     function GetModified: boolean;
692     procedure SetAsBoolean(AValue: boolean);
693     procedure SetAsCurrency(aValue: Currency);
694     procedure SetAsInt64(aValue: Int64);
695     procedure SetAsDate(aValue: TDateTime);
696     procedure SetAsLong(aValue: Long);
697 tony 315 procedure SetAsTime(aValue: TDateTime); overload;
698     procedure SetAsTime(aValue: TDateTime; OnDate: TDateTime; aTimeZoneID: TFBTimeZoneID); overload;
699     procedure SetAsTime(aValue: TDateTime; OnDate: TDateTime; aTimeZone: AnsiString); overload;
700     procedure SetAsTime(aValue: TDateTime; aTimeZoneID: TFBTimeZoneID); overload;
701     procedure SetAsTime(aValue: TDateTime; aTimeZone: AnsiString); overload;
702     procedure SetAsDateTime(aValue: TDateTime); overload;
703     procedure SetAsDateTime(aValue: TDateTime; aTimeZoneID: TFBTimeZoneID); overload;
704     procedure SetAsDateTime(aValue: TDateTime; aTimeZone: AnsiString); overload;
705     procedure SetAsUTCDateTime(aUTCTime: TDateTime);
706 tony 45 procedure SetAsDouble(aValue: Double);
707     procedure SetAsFloat(aValue: Float);
708     procedure SetAsPointer(aValue: Pointer);
709     procedure SetAsShort(aValue: Short);
710 tony 56 procedure SetAsString(aValue: AnsiString);
711 tony 45 procedure SetAsVariant(aValue: Variant);
712     procedure SetIsNull(aValue: Boolean);
713     procedure SetAsBlob(aValue: IBlob);
714     procedure SetAsArray(anArray: IArray);
715     procedure SetAsQuad(aValue: TISC_QUAD);
716     procedure SetCharSetID(aValue: cardinal);
717 tony 315 procedure SetAsBcd(aValue: tBCD);
718 tony 45 property AsDate: TDateTime read GetAsDateTime write SetAsDate;
719     property AsBoolean:boolean read GetAsBoolean write SetAsBoolean;
720     property AsTime: TDateTime read GetAsDateTime write SetAsTime;
721     property AsDateTime: TDateTime read GetAsDateTime write SetAsDateTime;
722     property AsDouble: Double read GetAsDouble write SetAsDouble;
723     property AsFloat: Float read GetAsFloat write SetAsFloat;
724     property AsCurrency: Currency read GetAsCurrency write SetAsCurrency;
725     property AsInt64: Int64 read GetAsInt64 write SetAsInt64;
726     property AsInteger: Integer read GetAsLong write SetAsLong;
727     property AsLong: Long read GetAsLong write SetAsLong;
728     property AsPointer: Pointer read GetAsPointer write SetAsPointer;
729     property AsShort: Short read GetAsShort write SetAsShort;
730 tony 56 property AsString: AnsiString read GetAsString write SetAsString;
731 tony 45 property AsVariant: Variant read GetAsVariant write SetAsVariant;
732     property AsBlob: IBlob read GetAsBlob write SetAsBlob;
733     property AsArray: IArray read GetAsArray write SetAsArray;
734 tony 315 property AsBCD: tBCD read GetAsBCD write SetAsBCD;
735 tony 45 property AsQuad: TISC_QUAD read GetAsQuad write SetAsQuad;
736     property Value: Variant read GetAsVariant write SetAsVariant;
737     property IsNull: Boolean read GetIsNull write SetIsNull;
738     property IsNullable: Boolean read GetIsNullable;
739     property Modified: Boolean read getModified;
740 tony 56 property Name: AnsiString read GetName;
741 tony 45 end;
742    
743     {
744     The ISQLParams interface provides access to the collection of parameters used
745     for the input to an SQL Statement
746     }
747    
748     ISQLParams = interface
749 tony 56 ['{c6d95ac7-b2b7-461b-b890-afef0acbb077}']
750 tony 45 function getCount: integer;
751     function getSQLParam(index: integer): ISQLParam;
752 tony 56 function ByName(Idx: AnsiString): ISQLParam ;
753 tony 45 function GetModified: Boolean;
754 tony 287 function GetHasCaseSensitiveParams: Boolean;
755 tony 45 property Modified: Boolean read GetModified;
756     property Params[index: integer]: ISQLParam read getSQLParam; default;
757     property Count: integer read getCount;
758     end;
759    
760 tony 47
761     TPerfStats = (psCurrentMemory, psMaxMemory,
762     psRealTime, psUserTime, psBuffers,
763     psReads, psWrites, psFetches,psDeltaMemory);
764    
765 tony 209 TPerfCounters = array[TPerfStats] of Int64;
766 tony 47
767 tony 345 {Batch Query Execution Support}
768    
769     TBatchCompletionState = (bcExecuteFailed, bcSuccessNoInfo, bcNoMoreErrors);
770    
771     IBatchCompletion = interface
772     ['{9bc3d49d-16d9-4606-94e5-ee987103ad92}']
773     function getTotalProcessed: cardinal;
774     function getState(updateNo: cardinal): TBatchCompletionState;
775     function getStatusMessage(updateNo: cardinal): AnsiString;
776     function getUpdated: integer;
777     function getErrorStatus(var RowNo: integer; var status: IStatus): boolean;
778     end;
779    
780 tony 45 {The IStatement interface provides access to an SQL Statement once it has been
781     initially prepared. The interface is returned from the IAttachment interface.
782     }
783    
784 tony 359 TStatementFlag = (stHasCursor,stRepeatExecute,stScrollable);
785     TStatementFlags = set of TStatementFlag;
786    
787 tony 45 IStatement = interface
788 tony 56 ['{a260576d-a07d-4a66-b02d-1b72543fd7cf}']
789 tony 45 function GetMetaData: IMetaData; {Output Metadata}
790     function GetSQLParams: ISQLParams;{Statement Parameters}
791 tony 56 function GetPlan: AnsiString;
792 tony 45 function GetRowsAffected(var SelectCount, InsertCount, UpdateCount, DeleteCount: integer): boolean;
793     function GetSQLStatementType: TIBSQLStatementTypes;
794 tony 345 function GetSQLStatementTypeName: AnsiString;
795 tony 56 function GetSQLText: AnsiString;
796 tony 263 function GetProcessedSQLText: AnsiString;
797 tony 45 function GetSQLDialect: integer;
798 tony 359 function GetFlags: TStatementFlags;
799 tony 45 function IsPrepared: boolean;
800 tony 345 function HasBatchMode: boolean;
801     function IsInBatchMode: boolean;
802 tony 350 procedure Prepare(aTransaction: ITransaction=nil); overload;
803     procedure Prepare(CursorName: AnsiString; aTransaction: ITransaction=nil); overload;
804 tony 45 function Execute(aTransaction: ITransaction=nil): IResults;
805 tony 350 function OpenCursor(aTransaction: ITransaction=nil): IResultSet; overload;
806     function OpenCursor(Scrollable: boolean; aTransaction: ITransaction=nil): IResultSet; overload;
807 tony 45 function GetAttachment: IAttachment;
808     function GetTransaction: ITransaction;
809     procedure SetRetainInterfaces(aValue: boolean);
810 tony 47 procedure EnableStatistics(aValue: boolean);
811     function GetPerfStatistics(var stats: TPerfCounters): boolean;
812 tony 345 {IBatch interface support}
813     procedure AddToBatch;
814     function ExecuteBatch(aTransaction: ITransaction=nil): IBatchCompletion;
815     procedure CancelBatch;
816     function GetBatchCompletion: IBatchCompletion;
817     function GetBatchRowLimit: integer;
818     procedure SetBatchRowLimit(aLimit: integer);
819 tony 347 {Stale Reference Check}
820     procedure SetStaleReferenceChecks(Enable:boolean); {default true}
821     function GetStaleReferenceChecks: boolean;
822 tony 345
823 tony 45 property MetaData: IMetaData read GetMetaData;
824     property SQLParams: ISQLParams read GetSQLParams;
825     property SQLStatementType: TIBSQLStatementTypes read GetSQLStatementType;
826     end;
827    
828 tony 359 ITrInfoItem = interface
829     ['{41455e1a-f84e-4e26-aff0-1a78e8b69cfe}']
830     function getItemType: byte;
831     function getSize: integer;
832     function getAsString: AnsiString;
833     function getAsInteger: int64;
834     procedure DecodeTraIsolation(var IsolationType, RecVersion: byte);
835     end;
836    
837     { ITrInformation }
838    
839     ITrInformation = interface
840     ['{e6ea4a52-c1a1-44ba-9609-c8bcc7cba7b2}']
841     function GetCount: integer;
842     function GetItem(index: integer): ITrInfoItem;
843     function Find(ItemType: byte): ITrInfoItem;
844     procedure PrintBuf; {can be used to print buffer in hex for debugging}
845     property Count: integer read GetCount;
846     property Items[index: integer]: ITrInfoItem read getItem; default;
847     end;
848    
849 tony 45 {Transaction Parameter Block: (TPB)
850    
851     The TPB provides the parameters used when starting a transaction. It is allocated
852     empty by the FirebirdAPI and the parameters are then added to it. Each individual
853     parameter may be accessed by the ITPBItem interface which can be used to set the
854     value, if any, of the parameter.
855    
856     The TPB parameters, and the associated symbolic codes and parameter values may be
857     found in the Interbase 6.0 API Guide.
858     }
859    
860 tony 315 ITPBItem = interface(IParameterBlockItemWithTypeName)
861 tony 56 ['{544c1f2b-7c12-4a87-a4a5-face7ea72671}']
862     end;
863 tony 45
864 tony 315 ITPB = interface(IParameterBlockWithTypeNames<ITPBItem>)
865 tony 56 ['{7369b0ff-defe-437b-81fe-19b211d42d25}']
866 tony 363 function AsText: AnsiString;
867 tony 56 end;
868 tony 45
869     {The ITransactionAction interface provides access to a Transaction once it
870     has been initially started. After a Commit or Rollback, a transaction
871     may be restarted, optinally with a new TPB.
872    
873     A multi-database transaction is started from the FirebirdAPI. A single database
874     transaction is started from the IAttachment interface.
875     }
876    
877     TTransactionAction = (TARollback, TACommit, TACommitRetaining, TARollbackRetaining);
878     TTransactionCompletion = TARollback.. TACommit;
879    
880     ITransaction = interface
881 tony 56 ['{30928d0e-a9d7-4c61-b7cf-14f4f38abe2a}']
882 tony 45 function getTPB: ITPB;
883     procedure Start(DefaultCompletion: TTransactionCompletion=taCommit);
884     function GetInTransaction: boolean;
885 tony 359 function GetIsReadOnly: boolean;
886     function GetTransactionID: integer;
887 tony 363 function GetJournalingActive(attachment: IAttachment): boolean;
888     function GetDefaultCompletion: TTransactionCompletion;
889 tony 45 procedure PrepareForCommit; {Two phase commit - stage 1}
890     procedure Commit(Force: boolean=false);
891     procedure CommitRetaining;
892     function HasActivity: boolean;
893     procedure Rollback(Force: boolean=false);
894     procedure RollbackRetaining;
895     function GetAttachmentCount: integer;
896     function GetAttachment(index: integer): IAttachment;
897 tony 359 function GetTrInformation(Requests: array of byte): ITrInformation; overload;
898     function GetTrInformation(Request: byte): ITrInformation; overload;
899 tony 363 function GetTransactionName: AnsiString;
900     procedure SetTransactionName(aValue: AnsiString);
901 tony 45 property InTransaction: boolean read GetInTransaction;
902 tony 363 property TransactionName: AnsiString read GetTransactionName write SetTransactionName;
903 tony 45 end;
904    
905     { The IEvents Interface is used to handle events from a single database. The
906     interface is allocated from the IAttachment Interface.
907    
908     Note that the EventHandler called when an event occurs following AsynWaitForEvent
909     is called in a different thread to the calling program and TThread.Synchronize
910     may be needed to pass the event back to the main thread.
911    
912     Neither AsyncWaitForEvent nor WaitForEvent is intended to be thread safe
913     in a multi-threaded environment and should always be called from the main
914     thread.
915     }
916    
917     TEventInfo = record
918 tony 56 EventName: AnsiString;
919 tony 45 Count: integer;
920     end;
921    
922     TEventCounts = array of TEventInfo;
923     IEvents = interface;
924     TEventHandler = procedure(Sender: IEvents) of object;
925    
926     { IEvents }
927    
928     IEvents = interface
929 tony 56 ['{6a0be233-ed08-4524-889c-2e45d0c20e5f}']
930 tony 45 procedure GetEvents(EventNames: TStrings);
931     procedure SetEvents(EventNames: TStrings); overload;
932 tony 56 procedure SetEvents(EventName: AnsiString); overload;
933 tony 45 procedure Cancel;
934     function ExtractEventCounts: TEventCounts;
935     procedure WaitForEvent;
936     procedure AsyncWaitForEvent(EventHandler: TEventHandler);
937     function GetAttachment: IAttachment;
938     end;
939    
940 tony 315 TTZTextOptions = (tzOffset, {Time Zone Rendered as an offset to GMT}
941     tzGMT, {No Time Zone. Time part is always rendered in GMT}
942     tzOriginalID); {Time Zone shown as originally entered}
943    
944     {The ITimeZoneServices interface provides access to the time zone database
945     used for the attachment. It may be used in support of TIMESTAMP WITH TIME ZONE
946     and TIME WITH TIME ZONE data types.}
947    
948     ITimeZoneServices = interface
949     ['{163821f5-ebef-42b9-ac60-8ac4b5c09954}']
950     {utility functions}
951     function TimeZoneID2TimeZoneName(aTimeZoneID: TFBTimeZoneID): AnsiString;
952     function TimeZoneName2TimeZoneID(aTimeZone: AnsiString): TFBTimeZoneID;
953     function LocalTimeToGMT(aLocalTime: TDateTime; aTimeZone: AnsiString): TDateTime; overload;
954     function LocalTimeToGMT(aLocalTime: TDateTime; aTimeZoneID: TFBTimeZoneID): TDateTime; overload;
955     function GMTToLocalTime(aGMTTime: TDateTime; aTimeZone: AnsiString): TDateTime; overload;
956     function GMTToLocalTime(aGMTTime: TDateTime; aTimeZoneID: TFBTimeZoneID): TDateTime; overload;
957     function GetEffectiveOffsetMins(aLocalTime: TDateTime; aTimeZone: AnsiString): integer; overload;
958     function GetEffectiveOffsetMins(aLocalTime: TDateTime; aTimeZoneID: TFBTimeZoneID): integer; overload;
959    
960     {Time Zone DB Information}
961     function UsingRemoteTZDB: boolean;
962     procedure SetUseLocalTZDB(useLocalTZDB: boolean);
963     function GetLocalTimeZoneName: AnsiString;
964     function GetLocalTimeZoneID: TFBTimeZoneID;
965     procedure GetTimeZoneInfo(aTimeZone: AnsiString; OnDate: TDateTime;
966     var ZoneOffset, DSTOffset, EffectiveOffset: integer);
967     {Configurable Options}
968     function GetTimeTZDate: TDateTime;
969     procedure SetTimeTZDate(aDate: TDateTime);
970     function GetTZTextOption: TTZTextOptions;
971     procedure SetTZTextOption(aOptionValue: TTZTextOptions);
972     end;
973    
974 tony 45 {The IDBInformation Interface.
975    
976     An IDBInformation interface is returned by the IAttachment GetDBInformation
977     method. The interface provides access to the information requested and
978     returned by the method.
979    
980     IDBInformation itself gives access to a collection of IDBInfoItems. Each one
981     provides information requested, as indicated by the ItemType and the actual
982     value of the information. In some cases, the returned item is itself a
983     colletion of IDBInfoItems.
984    
985     The IDBInformation items, and the associated symbolic codes and parameter values may be
986     found in the Interbase 6.0 API Guide.
987     }
988    
989     TDBOperationCount = record
990     TableID: UShort;
991     Count: cardinal;
992     end;
993    
994     TDBOperationCounts = array of TDBOperationCount;
995    
996     IDBInfoItem = interface
997 tony 56 ['{eeb97b51-ec0f-473f-9f75-c1721f055fcb}']
998 tony 45 function getItemType: byte;
999     function getSize: integer;
1000     procedure getRawBytes(var Buffer);
1001 tony 56 function getAsString: AnsiString;
1002 tony 345 function getAsInteger: int64;
1003 tony 56 procedure DecodeIDCluster(var ConnectionType: integer; var DBFileName, DBSiteName: AnsiString);
1004 tony 45 function getAsBytes: TByteArray;
1005 tony 143 function getAsDateTime: TDateTime;
1006 tony 56 procedure DecodeVersionString(var Version: byte; var VersionString: AnsiString);
1007 tony 45 function getOperationCounts: TDBOperationCounts;
1008     procedure DecodeUserNames(UserNames: TStrings);
1009    
1010     {user names only}
1011     function GetCount: integer;
1012     function GetItem(index: integer): IDBInfoItem;
1013     function Find(ItemType: byte): IDBInfoItem;
1014 tony 345 property AsInteger: int64 read getAsInteger;
1015 tony 56 property AsString: AnsiString read GetAsString;
1016 tony 45 property Count: integer read GetCount;
1017     property Items[index: integer]: IDBInfoItem read getItem; default;
1018     end;
1019    
1020     { IDBInformation }
1021    
1022     IDBInformation = interface
1023 tony 56 ['{7ac6777f-f0a9-498a-9f5c-4a57a554df81}']
1024 tony 45 function GetCount: integer;
1025     function GetItem(index: integer): IDBInfoItem;
1026     function Find(ItemType: byte): IDBInfoItem;
1027     procedure PrintBuf; {can be used to print buffer in hex for debugging}
1028     property Count: integer read GetCount;
1029     property Items[index: integer]: IDBInfoItem read getItem; default;
1030     end;
1031    
1032 tony 143 {The Database Information Request Block is used to pass requests for
1033     database information where at least one item requested has a parameter.
1034     At present, this is only fb_info_page_contents which has a single
1035     integer parameter.}
1036    
1037     IDIRBItem = interface(IParameterBlockItem)
1038     ['{d34a7511-8435-4a24-81a7-5103d218d234}']
1039     end;
1040    
1041     IDIRB = interface(IParameterBlock<IDIRBItem>)
1042     ['{1010e5ac-0a8f-403b-a302-91625e9d9579}']
1043     end;
1044    
1045    
1046 tony 45 {The Database Parameter Block (DPB).
1047    
1048     The DPB provides the parameters used when connecting to a database. It is allocated
1049     empty by the FirebirdAPI and the parameters are then added to it. Each individual
1050     parameter may be accessed by the IDPBItem interface which can be used to set the
1051     value, if any, of the parameter.
1052    
1053     The DPB parameters, and the associated symbolic codes and parameter values may be
1054     found in the Interbase 6.0 API Guide.
1055     }
1056    
1057 tony 315 IDPBItem = interface(IParameterBlockItemWithTypeName)
1058 tony 56 ['{123d4ad0-087a-4cd1-a344-1b3d03b30673}']
1059     end;
1060 tony 45
1061 tony 315 IDPB = interface(IParameterBlockWithTypeNames<IDPBItem>)
1062     ['{e676067b-1cf4-4eba-9256-9724f57e0d16}']
1063     end;
1064 tony 45
1065 tony 363 {Journaling options. Default is [joReadWriteTransactions,joModifyQueries] }
1066    
1067     TJournalOption = (joReadOnlyTransactions, joReadWriteTransactions,
1068     joModifyQueries, joReadOnlyQueries);
1069    
1070     TJournalOptions = set of TJournalOption;
1071    
1072 tony 45 {The IAttachment interface provides access to a Database Connection. It may be
1073     used to:
1074    
1075     a. Disconnect and reconnect to the database.
1076    
1077     b. Start a Transaction on the database
1078    
1079     c. Execute directly SQL DDL Statements and others that return no information.
1080    
1081     d. OpenCursors (i.e. execute SQL Select statements and return the results)
1082    
1083     e. Prepare SQL Statements, returning an IStatement interface for further processing.
1084    
1085     f. Provide access to an SQL Event Handler.
1086    
1087     g. Access Database Information.
1088    
1089     h. Support the handling of Array and Blob data.
1090    
1091     Note that SQL statements can be prepared with named parameters (PSQL style).
1092     This then allows the parameters to be accessed by name. The same name can
1093     be used for more than one parameter, allowing a single operation to be used
1094     to set all parameters with the same name.
1095     }
1096    
1097     { IAttachment }
1098    
1099     IAttachment = interface
1100 tony 56 ['{466e9b67-9def-4807-b3e7-e08a35e7185c}']
1101 tony 263 function getFirebirdAPI: IFirebirdAPI;
1102 tony 45 function getDPB: IDPB;
1103     function AllocateBPB: IBPB;
1104 tony 143 function AllocateDIRB: IDIRB;
1105 tony 45 procedure Connect;
1106     procedure Disconnect(Force: boolean=false);
1107     function IsConnected: boolean;
1108     procedure DropDatabase;
1109 tony 363 function StartTransaction(TPB: array of byte;
1110     DefaultCompletion: TTransactionCompletion=taCommit;
1111     aName: AnsiString=''): ITransaction; overload;
1112     function StartTransaction(TPB: ITPB;
1113     DefaultCompletion: TTransactionCompletion=taCommit;
1114     aName: AnsiString=''): ITransaction; overload;
1115 tony 56 procedure ExecImmediate(transaction: ITransaction; sql: AnsiString; SQLDialect: integer); overload;
1116     procedure ExecImmediate(TPB: array of byte; sql: AnsiString; SQLDialect: integer); overload;
1117     procedure ExecImmediate(transaction: ITransaction; sql: AnsiString); overload;
1118     procedure ExecImmediate(TPB: array of byte; sql: AnsiString); overload;
1119     function ExecuteSQL(TPB: array of byte; sql: AnsiString; SQLDialect: integer; params: array of const): IResults; overload;
1120     function ExecuteSQL(transaction: ITransaction; sql: AnsiString; SQLDialect: integer; params: array of const): IResults; overload;
1121     function ExecuteSQL(TPB: array of byte; sql: AnsiString; params: array of const): IResults; overload;
1122     function ExecuteSQL(transaction: ITransaction; sql: AnsiString; params: array of const): IResults; overload;
1123     function OpenCursor(transaction: ITransaction; sql: AnsiString; aSQLDialect: integer;
1124 tony 350 Scrollable: boolean=false): IResultSet; overload;
1125     function OpenCursor(transaction: ITransaction; sql: AnsiString; aSQLDialect: integer;
1126 tony 45 params: array of const): IResultSet; overload;
1127 tony 350 function OpenCursor(transaction: ITransaction; sql: AnsiString; Scrollable: boolean=false): IResultSet; overload;
1128     function OpenCursor(transaction: ITransaction; sql: AnsiString; Scrollable: boolean;
1129     params: array of const): IResultSet; overload;
1130 tony 56 function OpenCursor(transaction: ITransaction; sql: AnsiString;
1131 tony 45 params: array of const): IResultSet; overload;
1132 tony 350 function OpenCursor(transaction: ITransaction; sql: AnsiString; aSQLDialect: integer; Scrollable: boolean;
1133     params: array of const): IResultSet; overload;
1134 tony 56 function OpenCursorAtStart(transaction: ITransaction; sql: AnsiString; aSQLDialect: integer;
1135 tony 350 Scrollable: boolean=false): IResultSet; overload;
1136     function OpenCursorAtStart(transaction: ITransaction; sql: AnsiString; aSQLDialect: integer;
1137 tony 45 params: array of const): IResultSet; overload;
1138 tony 350 function OpenCursorAtStart(transaction: ITransaction; sql: AnsiString; aSQLDialect: integer; Scrollable: boolean;
1139     params: array of const): IResultSet; overload;
1140     function OpenCursorAtStart(transaction: ITransaction; sql: AnsiString; Scrollable: boolean=false): IResultSet; overload;
1141 tony 56 function OpenCursorAtStart(transaction: ITransaction; sql: AnsiString;
1142 tony 45 params: array of const): IResultSet; overload;
1143 tony 350 function OpenCursorAtStart(transaction: ITransaction; sql: AnsiString; Scrollable: boolean;
1144     params: array of const): IResultSet; overload;
1145     function OpenCursorAtStart(sql: AnsiString; Scrollable: boolean=false): IResultSet; overload;
1146     function OpenCursorAtStart(sql: AnsiString; Scrollable: boolean;
1147     params: array of const): IResultSet; overload;
1148 tony 56 function OpenCursorAtStart(sql: AnsiString;
1149 tony 45 params: array of const): IResultSet; overload;
1150 tony 350 function Prepare(transaction: ITransaction; sql: AnsiString; aSQLDialect: integer; CursorName: AnsiString=''): IStatement; overload;
1151     function Prepare(transaction: ITransaction; sql: AnsiString; CursorName: AnsiString=''): IStatement; overload;
1152 tony 56 function PrepareWithNamedParameters(transaction: ITransaction; sql: AnsiString;
1153 tony 270 aSQLDialect: integer; GenerateParamNames: boolean=false;
1154 tony 350 CaseSensitiveParams: boolean = false; CursorName: AnsiString=''): IStatement; overload;
1155 tony 56 function PrepareWithNamedParameters(transaction: ITransaction; sql: AnsiString;
1156 tony 270 GenerateParamNames: boolean=false;
1157 tony 350 CaseSensitiveParams: boolean = false; CursorName: AnsiString=''): IStatement; overload;
1158 tony 45
1159     {Events}
1160     function GetEventHandler(Events: TStrings): IEvents; overload;
1161 tony 56 function GetEventHandler(Event: AnsiString): IEvents; overload;
1162 tony 45
1163     {Blob - may use to open existing Blobs. However, ISQLData.AsBlob is preferred}
1164    
1165 tony 56 function CreateBlob(transaction: ITransaction; RelationName, ColumnName: AnsiString; BPB: IBPB=nil): IBlob; overload;
1166 tony 45 function CreateBlob(transaction: ITransaction; BlobMetaData: IBlobMetaData; BPB: IBPB=nil): IBlob; overload;
1167     function CreateBlob(transaction: ITransaction; SubType: integer; CharSetID: cardinal=0; BPB: IBPB=nil): IBlob; overload;
1168 tony 291 function OpenBlob(transaction: ITransaction; RelationName, ColumnName: AnsiString; BlobID: TISC_QUAD; BPB: IBPB=nil): IBlob; overload;
1169     function OpenBlob(transaction: ITransaction; BlobMetaData: IBlobMetaData; BlobID: TISC_QUAD; BPB: IBPB=nil): IBlob; overload;
1170 tony 345 function GetInlineBlobLimit: integer;
1171     procedure SetInlineBlobLimit(limit: integer);
1172 tony 45
1173     {Array - may use to open existing arrays. However, ISQLData.AsArray is preferred}
1174    
1175 tony 291 function OpenArray(transaction: ITransaction; RelationName, ColumnName: AnsiString; ArrayID: TISC_QUAD): IArray; overload;
1176     function OpenArray(transaction: ITransaction; ArrayMetaData: IArrayMetaData; ArrayID: TISC_QUAD): IArray; overload;
1177 tony 56 function CreateArray(transaction: ITransaction; RelationName, ColumnName: AnsiString): IArray; overload;
1178 tony 45 function CreateArray(transaction: ITransaction; ArrayMetaData: IArrayMetaData): IArray; overload;
1179 tony 56 function CreateArrayMetaData(SQLType: cardinal; tableName: AnsiString; columnName: AnsiString;
1180 tony 47 Scale: integer; size: cardinal; charSetID: cardinal; dimensions: cardinal;
1181     bounds: TArrayBounds): IArrayMetaData;
1182 tony 45
1183     {Database Information}
1184     function GetSQLDialect: integer;
1185 tony 363 function GetAttachmentID: integer;
1186 tony 56 function GetBlobMetaData(Transaction: ITransaction; tableName, columnName: AnsiString): IBlobMetaData;
1187     function GetArrayMetaData(Transaction: ITransaction; tableName, columnName: AnsiString): IArrayMetaData;
1188 tony 45 function GetDBInformation(Requests: array of byte): IDBInformation; overload;
1189     function GetDBInformation(Request: byte): IDBInformation; overload;
1190 tony 143 function GetDBInformation(Requests: IDIRB): IDBInformation; overload;
1191 tony 117 function GetConnectString: AnsiString;
1192     function GetRemoteProtocol: AnsiString;
1193 tony 143 function GetAuthenticationMethod: AnsiString;
1194 tony 209 function GetSecurityDatabase: AnsiString;
1195 tony 117 function GetODSMajorVersion: integer;
1196     function GetODSMinorVersion: integer;
1197 tony 266 procedure getFBVersion(version: TStrings);
1198 tony 45 function HasActivity: boolean;
1199 tony 315 function HasDecFloatSupport: boolean;
1200 tony 345 function HasBatchMode: boolean;
1201 tony 352 function HasScollableCursors: boolean;
1202 tony 363 function HasTable(aTableName: AnsiString): boolean;
1203 tony 60
1204     {Character Sets}
1205 tony 109 function HasDefaultCharSet: boolean;
1206     function GetDefaultCharSetID: integer;
1207 tony 60 function GetCharsetName(CharSetID: integer): AnsiString;
1208     function CharSetID2CodePage(CharSetID: integer; var CodePage: TSystemCodePage): boolean;
1209     function CodePage2CharSetID(CodePage: TSystemCodePage; var CharSetID: integer): boolean;
1210     function CharSetName2CharSetID(CharSetName: AnsiString; var CharSetID: integer): boolean;
1211     function CharSetWidth(CharSetID: integer; var Width: integer): boolean;
1212     procedure RegisterCharSet(CharSetName: AnsiString; CodePage: TSystemCodePage;
1213     AllowReverseLookup:boolean; out CharSetID: integer);
1214 tony 45
1215 tony 315 {Time Zone Database}
1216     function GetTimeZoneServices: ITimeZoneServices;
1217     function HasTimeZoneSupport: boolean;
1218 tony 363
1219     {Client side Journaling}
1220     function JournalingActive: boolean;
1221     function GetJournalOptions: TJournalOptions;
1222     function StartJournaling(aJournalLogFile: AnsiString): integer; overload;
1223     function StartJournaling(aJournalLogFile: AnsiString; Options: TJournalOptions): integer; overload;
1224     procedure StopJournaling(RetainJournal: boolean);
1225 tony 315 end;
1226    
1227 tony 231 TProtocolAll = (TCP, SPX, NamedPipe, Local, inet, inet4, inet6, wnet, xnet, unknownProtocol);
1228 tony 143 TProtocol = TCP..xnet;
1229 tony 45
1230     {Service Parameter Block (SPB).
1231    
1232     The SPB provides the parameters used when connecting to a Service Manager. It is
1233     allocated empty by the FirebirdAPI and the parameters are then added to it. Each
1234     individual parameter may be accessed by the ISPBItem interface which can be used
1235     to set the value, if any, of the parameter.
1236    
1237     The SPB parameters, and the associated symbolic codes and parameter values may be
1238     found in the Interbase 6.0 API Guide.
1239    
1240     }
1241    
1242 tony 315 ISPBItem = interface(IParameterBlockItemWithTypeName)
1243 tony 56 ['{5d08ae2b-4519-41bd-8b40-97cd451c3f6a}']
1244     end;
1245 tony 45
1246 tony 315 ISPB = interface(IParameterBlockWithTypeNames<ISPBItem>)
1247 tony 56 ['{2c5836fd-41ed-4426-9b7d-5af580ec2659}']
1248     end;
1249 tony 45
1250     {Service Query Parameter Block (SQPB).
1251    
1252     This is a specialised parameter block used to send data to a service manager
1253     in a Query Request.
1254     }
1255    
1256     ISQPBItem = interface(IParameterBlockItem)
1257 tony 56 ['{b07841a6-33b3-47f0-b5a2-028cbc86dc97}']
1258 tony 45 function CopyFrom(source: TStream; count: integer): integer;
1259     end;
1260    
1261 tony 56 ISQPB = interface(IParameterBlock<ISQPBItem>)
1262     ['{8553e66b-ee62-498b-8431-dff030211447}']
1263     end;
1264 tony 45
1265     {Service Request Block (SRB).
1266    
1267     The SRB specifies what is requested from the Service Manager when starting a
1268     service or querying a service. It is allocated empty by the ServiceManager API and
1269     the parameters are then added to it. Each individual parameter may be accessed
1270     by the ISRBItem interface which can be used to set the value, if any, of the parameter.
1271    
1272     The SRB parameters, and the associated symbolic codes and parameter values may be
1273     found in the Interbase 6.0 API Guide.
1274    
1275     }
1276    
1277 tony 56 ISRBItem = interface(IParameterBlockItem)
1278     ['{47ec790e-f265-4b30-9dcd-261e51677245}']
1279     end;
1280 tony 45
1281 tony 56 ISRB = interface(IParameterBlock<ISRBItem>)
1282     ['{9f2e204f-3c33-4e44-90f9-9135e95dafb9}']
1283     end;
1284 tony 45
1285     {The Service Query Results Interface.
1286    
1287     An IServiceQueryResults interface is returned by the IServiceManager Query
1288     method. The interface provides access to the information requested and
1289     returned by the method.
1290    
1291     IServiceQueryResults itself gives access to a collection of IServiceQueryResultItem.
1292     Each one provides information requested, as indicated by the ItemType and the actual
1293     value of the information. In some cases, the returned item is itself a
1294     collection of IServiceQueryResultSubItem.
1295    
1296     The IServiceQueryResultItem items, and the associated symbolic codes and parameter values may be
1297     found in the Interbase 6.0 API Guide.
1298     }
1299    
1300     IServiceQueryResultSubItem = interface
1301 tony 56 ['{8a4c381e-9923-4cc9-a96b-553729248640}']
1302 tony 45 function getItemType: byte;
1303     function getSize: integer;
1304     procedure getRawBytes(var Buffer);
1305 tony 56 function getAsString: AnsiString;
1306 tony 345 function getAsInteger: int64;
1307 tony 45 function getAsByte: byte;
1308     function CopyTo(stream: TStream; count: integer): integer;
1309 tony 56 property AsString: AnsiString read getAsString;
1310 tony 345 property AsInteger: int64 read getAsInteger;
1311 tony 45 property AsByte: byte read getAsByte;
1312     end;
1313    
1314     IServiceQueryResultItem = interface(IServiceQueryResultSubItem)
1315 tony 56 ['{b2806886-206c-4024-8df9-5fe0a7630a5e}']
1316 tony 45 function getCount: integer;
1317     function getItem(index: integer): IServiceQueryResultSubItem;
1318     function find(ItemType: byte): IServiceQueryResultSubItem;
1319     property Items[index: integer]: IServiceQueryResultSubItem read getItem; default;
1320     property Count: integer read getCount;
1321     end;
1322    
1323     IServiceQueryResults = interface
1324 tony 56 ['{8fbbef7d-fe03-4409-828a-a787d34ef531}']
1325 tony 45 function getCount: integer;
1326     function getItem(index: integer): IServiceQueryResultItem;
1327     function find(ItemType: byte): IServiceQueryResultItem;
1328     procedure PrintBuf; {can be used to print buffer in hex for debugging}
1329     property Items[index: integer]: IServiceQueryResultItem read getItem; default;
1330     property Count: integer read getCount;
1331     end;
1332    
1333 tony 263 IFirebirdLibrary = interface;
1334    
1335 tony 45 {The IServiceManager interface provides access to a service manager. It can
1336     used to Detach and re-attach to Service Manager, to start services and to
1337     query the service manager.
1338    
1339     The interface is returned by the FirebirdAPI GetService Manager method.
1340     }
1341    
1342     { IServiceManager }
1343    
1344     IServiceManager = interface
1345 tony 56 ['{905b587d-1e1f-4e40-a3f8-a3519f852e48}']
1346 tony 263 function getFirebirdAPI: IFirebirdAPI;
1347 tony 45 function getSPB: ISPB;
1348 tony 56 function getServerName: AnsiString;
1349 tony 209 function getProtocol: TProtocol;
1350     function getPortNo: AnsiString;
1351 tony 45 procedure Attach;
1352     procedure Detach(Force: boolean=false);
1353     function IsAttached: boolean;
1354     function AllocateSRB: ISRB;
1355     function AllocateSQPB: ISQPB;
1356 tony 209 function Start(Request: ISRB; RaiseExceptionOnError: boolean=true): boolean;
1357     function Query(SQPB: ISQPB; Request: ISRB; RaiseExceptionOnError: boolean=true) :IServiceQueryResults; overload;
1358     function Query(Request: ISRB; RaiseExceptionOnError: boolean=true) :IServiceQueryResults; overload;
1359 tony 45 end;
1360    
1361 tony 263 {Tbe Firebird Library API used to get information about the Firebird library}
1362    
1363    
1364     IFirebirdLibrary = interface
1365     ['{3c04e0a1-12e0-428a-b2e1-bc6fcd97b79b}']
1366     function GetHandle: TLibHandle;
1367     function GetLibraryName: string;
1368     function GetLibraryFilePath: string;
1369     function GetFirebirdAPI: IFirebirdAPI;
1370     end;
1371    
1372 tony 45 {The Firebird API.
1373    
1374     This is the base interface and is used to create/open a database connection, to
1375     start a transaction on multiple databases and the access the service manager.
1376    
1377     The interface is returned by the FirebirdAPI function.
1378     }
1379    
1380 tony 315 { IFirebirdAPI }
1381    
1382 tony 45 IFirebirdAPI = interface
1383 tony 56 ['{edeee691-c8d3-4dcf-a780-cd7e432821d5}']
1384 tony 45 {Database connections}
1385     function AllocateDPB: IDPB;
1386 tony 56 function OpenDatabase(DatabaseName: AnsiString; DPB: IDPB; RaiseExceptionOnConnectError: boolean=true): IAttachment;
1387     function CreateDatabase(DatabaseName: AnsiString; DPB: IDPB; RaiseExceptionOnError: boolean=true): IAttachment; overload;
1388     function CreateDatabase(sql: AnsiString; aSQLDialect: integer; RaiseExceptionOnError: boolean=true): IAttachment; overload;
1389 tony 45
1390     {Start Transaction against multiple databases}
1391     function AllocateTPB: ITPB;
1392     function StartTransaction(Attachments: array of IAttachment;
1393 tony 363 TPB: array of byte; DefaultCompletion: TTransactionCompletion=taCommit;
1394     aName: AnsiString=''): ITransaction; overload;
1395 tony 45 function StartTransaction(Attachments: array of IAttachment;
1396 tony 363 TPB: ITPB; DefaultCompletion: TTransactionCompletion=taCommit;
1397     aName: AnsiString=''): ITransaction; overload;
1398 tony 45
1399     {Service Manager}
1400     function HasServiceAPI: boolean;
1401     function AllocateSPB: ISPB;
1402 tony 143 function GetServiceManager(ServerName: AnsiString; Protocol: TProtocol; SPB: ISPB): IServiceManager; overload;
1403     function GetServiceManager(ServerName: AnsiString; Port: AnsiString; Protocol: TProtocol; SPB: ISPB): IServiceManager; overload;
1404 tony 45
1405     {Information}
1406     function GetStatus: IStatus;
1407     function HasRollbackRetaining: boolean;
1408     function IsEmbeddedServer: boolean;
1409 tony 56 function GetImplementationVersion: AnsiString;
1410 tony 308 function GetClientMajor: integer;
1411     function GetClientMinor: integer;
1412 tony 315 function HasDecFloatSupport: boolean;
1413     function HasLocalTZDB: boolean;
1414     function HasTimeZoneSupport: boolean;
1415     function HasExtendedTZSupport: boolean;
1416 tony 45
1417     {Firebird 3 API}
1418     function HasMasterIntf: boolean;
1419 tony 315 function GetIMaster: TObject; deprecated 'Use FirebirdAPI.QueryInterface and FBClientLib.pas IFBIMasterProvider instead';
1420 tony 263 function GetFBLibrary: IFirebirdLibrary;
1421 tony 45 end;
1422    
1423     type
1424     TOnGetLibraryName = procedure(var libname: string);
1425    
1426     const
1427     OnGetLibraryName: TOnGetLibraryName = nil;
1428     AllowUseOfFBLIB: boolean = false;
1429    
1430     type
1431     { EIBError }
1432    
1433     EIBError = class(EDatabaseError)
1434     private
1435     FSQLCode: Long;
1436     public
1437 tony 56 constructor Create(ASQLCode: Long; Msg: AnsiString);
1438 tony 45 property SQLCode: Long read FSQLCode;
1439     end;
1440    
1441     { EIBInterBaseError - Firebird Engine errors}
1442    
1443     EIBInterBaseError = class(EIBError)
1444     private
1445     FIBErrorCode: Long;
1446     public
1447     constructor Create(Status: IStatus); overload;
1448 tony 56 constructor Create(ASQLCode: Long; AIBErrorCode: Long; Msg: AnsiString); overload;
1449 tony 45 property IBErrorCode: Long read FIBErrorCode;
1450     end;
1451    
1452     {IB Client Exceptions}
1453     EIBClientError = class(EIBError);
1454    
1455 tony 345 {Used to explicitly report a Batch Buffer overflow}
1456     EIBBatchBufferOverflow = class(EIBError);
1457    
1458 tony 45 {The Firebird API function is used to access the IFirebirdAPI interface.
1459    
1460     It will load the Firebird Client Library if this is not already loaded and
1461     select an implementation of the Firebird API (legacy 2.5 or 3.0.
1462     }
1463    
1464     function FirebirdAPI: IFirebirdAPI;
1465    
1466     {IBX support functions. Probably best ignored i.e. always used the FirebirdAPI
1467 tony 315 function to load the library and check if it's loaded.}
1468 tony 45
1469     function TryIBLoad: Boolean;
1470     procedure CheckIBLoaded;
1471    
1472 tony 263 {If you want to explicitly load the Firebird library from a
1473     non-default location then use this function and its GetFirebirdAPI function
1474     to get the API.}
1475    
1476     function LoadFBLibrary(aLibPathName: string): IFirebirdLibrary;
1477    
1478 tony 363 {$if not declared(NULL)} {Needed for Delphi}
1479     function Null: Variant; // Null standard constant
1480     {$define NEEDNULLFUNCTION}
1481     {$ifend}
1482 tony 315
1483 tony 45 implementation
1484    
1485 tony 363 uses FBClientAPI {$if not declared(NULL)}, Variants {$ifend}
1486 tony 45 {$IFDEF USELEGACYFIREBIRDAPI}, FB25ClientAPI {$ENDIF}
1487     {$IFDEF USEFIREBIRD3API}, FB30ClientAPI {$ENDIF};
1488    
1489 tony 263 var FDefaultFBLibrary: IFirebirdLibrary;
1490 tony 45
1491 tony 263 type
1492    
1493     { TFBLibrary }
1494    
1495     TFBLibraryImpl = class(TFBLibrary)
1496     protected
1497     function GetFirebird3API: IFirebirdAPI; override;
1498     function GetLegacyFirebirdAPI: IFirebirdAPI; override;
1499     end;
1500    
1501     function TFBLibraryImpl.GetFirebird3API: IFirebirdAPI;
1502     begin
1503     {$IFDEF USEFIREBIRD3API}
1504     Result := TFB30ClientAPI.Create(self);
1505     {$ELSE}
1506     Result := nil;
1507     {$ENDIF}
1508     end;
1509    
1510     function TFBLibraryImpl.GetLegacyFirebirdAPI: IFirebirdAPI;
1511     begin
1512     {$IFDEF USELEGACYFIREBIRDAPI}
1513     Result := TFB25ClientAPI.Create(self);
1514     {$ELSE}
1515     Result := nil;
1516     {$ENDIF}
1517     end;
1518    
1519 tony 45 function FirebirdAPI: IFirebirdAPI;
1520     begin
1521 tony 263 if FDefaultFBLibrary = nil then
1522 tony 45 CheckIBLoaded;
1523 tony 263 Result := FDefaultFBLibrary.GetFirebirdAPI;
1524 tony 45 end;
1525    
1526     function TryIBLoad: Boolean;
1527 tony 263 var fblib: IFirebirdLibrary;
1528 tony 45 begin
1529 tony 263 Result := FDefaultFBLibrary <> nil;
1530 tony 45 try
1531     if not Result then
1532     begin
1533 tony 263 fblib := TFBLibraryImpl.Create;
1534     if (fblib <> nil) and (fblib.GetFirebirdAPI <> nil) then
1535     FDefaultFBLibrary := fblib;
1536     Result := FDefaultFBLibrary <> nil;
1537 tony 45 end;
1538     except
1539     SysUtils.showexception(ExceptObject,ExceptAddr);
1540     Result := false;
1541     end;
1542     end;
1543    
1544     procedure CheckIBLoaded;
1545     begin
1546     if not TryIBLoad then
1547     IBError(ibxeInterBaseMissing, [nil]);
1548     end;
1549    
1550 tony 263 function LoadFBLibrary(aLibPathName: string): IFirebirdLibrary;
1551     var fblib: IFirebirdLibrary;
1552     begin
1553     if trim(aLibPathName) = '' then
1554     begin
1555     CheckIBLoaded;
1556     Result := FDefaultFBLibrary;
1557     end
1558     else
1559     begin
1560     fblib := TFBLibraryImpl.GetFBLibrary(aLibPathName);
1561     if (fblib = nil) or (fblib.GetFirebirdAPI = nil) then
1562     IBError(ibxeInterBaseMissing, [nil]);
1563     Result := fblib;
1564     end;
1565     end;
1566    
1567 tony 45 { EIBError }
1568    
1569 tony 56 constructor EIBError.Create(ASQLCode: Long; Msg: AnsiString);
1570 tony 45 begin
1571     inherited Create(Msg);
1572     FSQLCode := ASQLCode;
1573     end;
1574    
1575     { EIBInterBaseError }
1576    
1577     constructor EIBInterBaseError.Create(Status: IStatus);
1578     begin
1579     inherited Create(Status.Getsqlcode,Status.GetMessage);
1580     FIBErrorCode := Status.GetIBErrorCode;
1581     end;
1582    
1583     constructor EIBInterBaseError.Create(ASQLCode: Long; AIBErrorCode: Long;
1584 tony 56 Msg: AnsiString);
1585 tony 45 begin
1586     inherited Create(ASQLCode,Msg);
1587     FIBErrorCode := AIBErrorCode;
1588     end;
1589    
1590 tony 363 {$ifdef NEEDNULLFUNCTION}
1591     function Null: Variant; // Null standard constant
1592     begin
1593     VarClearProc(TVarData(Result));
1594     TVarData(Result).VType := varnull;
1595     end;
1596     {$endif}
1597 tony 45
1598     initialization
1599 tony 263 FDefaultFBLibrary := nil;
1600 tony 45
1601 tony 209 finalization
1602 tony 263 FDefaultFBLibrary := nil;
1603 tony 45
1604     end.
1605