ViewVC Help
View File | Revision Log | Show Annotations | Download File | View Changeset | Root Listing
root/public/ibx/branches/journaling/fbintf/IB.pas
Revision: 291
Committed: Fri Apr 17 10:26:08 2020 UTC (3 years, 11 months ago) by tony
Content type: text/x-pascal
Original Path: ibx/trunk/fbintf/IB.pas
File size: 53065 byte(s)
Log Message:
Changed for 2.3.4 merged into public release

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     SysUtils, DB, FBMessages, IBExternals;
133 tony 45
134 tony 47 const
135     {Interface version information}
136     FBIntf_Major = 1;
137 tony 154 FBIntf_Minor = 1;
138 tony 287 FBIntf_Release = 5;
139     FBIntf_Version = '1.1.5';
140 tony 47
141 tony 45 {These include files are converted from the 'C' originals in the Firebird API
142     and define the various constants used by the API}
143    
144 tony 56 {$I 'include/consts_pub.inc'}
145     {$I 'include/inf_pub.inc'}
146     {$I 'include/configkeys.inc'}
147 tony 45
148     {The following constants define the values return by calls to the GetSQLType
149     methods provided by several of the interfaces defined below.}
150    
151     (*********************)
152     (** SQL definitions **)
153     (*********************)
154     SQL_VARYING = 448;
155     SQL_TEXT = 452;
156     SQL_DOUBLE = 480;
157     SQL_FLOAT = 482;
158     SQL_LONG = 496;
159     SQL_SHORT = 500;
160     SQL_TIMESTAMP = 510;
161     SQL_BLOB = 520;
162     SQL_D_FLOAT = 530;
163     SQL_ARRAY = 540;
164     SQL_QUAD = 550;
165     SQL_TYPE_TIME = 560;
166     SQL_TYPE_DATE = 570;
167     SQL_INT64 = 580;
168     SQL_BOOLEAN = 32764;
169     SQL_DATE = SQL_TIMESTAMP;
170    
171     type
172     TGDS_QUAD = record
173     gds_quad_high : ISC_LONG;
174     gds_quad_low : UISC_LONG;
175     end;
176     TGDS__QUAD = TGDS_QUAD;
177     TISC_QUAD = TGDS_QUAD;
178     PGDS_QUAD = ^TGDS_QUAD;
179     PGDS__QUAD = ^TGDS__QUAD;
180     PISC_QUAD = ^TISC_QUAD;
181    
182 tony 56 {$IFNDEF FPC}
183 tony 263 {Delphi missing definitions}
184     type
185     TLibHandle = THandle;
186    
187     const
188     NilHandle = 0;
189     DirectorySeparator = '\';
190    
191 tony 56 {Delphi only seems to define CP_UTF8 and CP_UTF16}
192     const
193     CP_ACP = 0; // default to ANSI code page
194     CP_OEMCP = 1; // default to OEM (console) code page
195     CP_UTF16BE = 1201; // unicodeFFFE
196     CP_UTF7 = 65000; // utf-7
197     CP_ASCII = 20127; // us-ascii
198     CP_NONE = $FFFF; // rawbytestring encoding
199    
200     {$ENDIF}
201    
202     type
203     {$IF not declared(TSystemCodePage)}
204     TSystemCodePage = word; {not defined in Delphi}
205     {$IFEND}
206    
207 tony 45 TIBSQLStatementTypes =
208     (SQLUnknown, SQLSelect, SQLInsert,
209     SQLUpdate, SQLDelete, SQLDDL,
210     SQLGetSegment, SQLPutSegment,
211     SQLExecProcedure, SQLStartTransaction,
212     SQLCommit, SQLRollback,
213 tony 291 SQLSelectForUpdate, SQLSetGenerator,
214     SQLSavePoint);
215 tony 45
216     TFBStatusCode = cardinal;
217     TByteArray = array of byte;
218    
219 tony 263 IFirebirdAPI = interface;
220 tony 45 IAttachment = interface;
221     ITransaction = interface;
222 tony 291 IStatement = interface;
223 tony 45
224 tony 56 {The IParameterBlock interface provides the template for all parameter
225 tony 45 block interfaces}
226    
227 tony 56 IParameterBlock<_IItem> = interface
228 tony 45 function getCount: integer;
229     function Add(ParamType: byte): _IItem;
230     function getItems(index: integer): _IItem;
231     function Find(ParamType: byte): _IItem;
232     procedure PrintBuf; {can be used to print buffer in hex for debugging}
233     property Count: integer read getCount;
234     property Items[index: integer]: _IItem read getItems; default;
235     end;
236    
237     {IParameterBlockItem is not used on its own but instead provides a base type for
238     different parameter block items }
239    
240     IParameterBlockItem = interface
241 tony 56 ['{53b23f7b-abda-46a5-9aa5-07bd5e723266}']
242 tony 45 function getParamType: byte;
243     function getAsInteger: integer;
244 tony 56 function getAsString: AnsiString;
245 tony 45 function getAsByte: byte;
246 tony 56 procedure setAsString(aValue: AnsiString);
247 tony 45 procedure setAsByte(aValue: byte);
248     procedure SetAsInteger(aValue: integer);
249 tony 56 property AsString: AnsiString read getAsString write setAsString;
250 tony 45 property AsByte: byte read getAsByte write setAsByte;
251     property AsInteger: integer read getAsInteger write SetAsInteger;
252     end;
253    
254    
255     {The IStatus interface provides access to error information, if any, returned
256     by the last API call. It can also be used to customise the error message
257     returned by a database engine exception - see EIBInterbaseError.
258    
259     This interface can be accessed from IFirebirdAPI.
260     }
261    
262 tony 291 TIBDataBaseErrorMessage = (ShowSQLCode,
263     ShowIBMessage,
264     ShowSQLMessage);
265    
266     TIBDataBaseErrorMessages = set of TIBDataBaseErrorMessage;
267    
268 tony 45 IStatus = interface
269 tony 56 ['{34167722-af38-4831-b08a-93162d58ede3}']
270 tony 45 function GetIBErrorCode: Long;
271     function Getsqlcode: Long;
272 tony 56 function GetMessage: AnsiString;
273 tony 45 function CheckStatusVector(ErrorCodes: array of TFBStatusCode): Boolean;
274     function GetIBDataBaseErrorMessages: TIBDataBaseErrorMessages;
275     procedure SetIBDataBaseErrorMessages(Value: TIBDataBaseErrorMessages);
276     end;
277    
278     { The array metadata interface provides access to the metadata used to describe
279     an array column in a Firebird table.
280     }
281    
282     TArrayBound = record
283     UpperBound: short;
284     LowerBound: short;
285     end;
286     TArrayBounds = array of TArrayBound;
287    
288     IArrayMetaData = interface
289 tony 56 ['{7dd0aea4-59af-4c2a-b958-565d5025c489}']
290 tony 45 function GetSQLType: cardinal;
291 tony 56 function GetSQLTypeName: AnsiString;
292 tony 45 function GetScale: integer;
293     function GetSize: cardinal;
294     function GetCharSetID: cardinal;
295 tony 56 function GetTableName: AnsiString;
296     function GetColumnName: AnsiString;
297 tony 45 function GetDimensions: integer;
298     function GetBounds: TArrayBounds;
299     end;
300    
301     {The array interface provides access to and modification of the array data
302     contained in an array field of a Firebird Table. The array element is
303     selected by specifying its co-ordinates using an integer array. The
304     getter and setter methods used should be appropriate for the type of data
305     contained in the array. Automatic conversion is provided to and from strings.
306     That is GetAsString and SetAsString are safe to use for sql types other than
307     boolean.
308    
309     The interface is returned by a GetAsArray getter method (see ISQLData). A new array
310     can be obtained from the IAttachment interface. The SetAsArray setter method
311     (See ISQLParam) is used to apply an updated or new array to the database using
312     an UPDATE or INSERT statement.
313    
314     }
315    
316     TArrayEventReason = (arChanging,arChanged);
317     IArray = interface;
318     TArrayEventHandler = procedure(Sender: IArray; Reason: TArrayEventReason) of object;
319    
320     IArray = interface(IArrayMetaData)
321 tony 56 ['{631c6bb1-fb49-44fb-a64a-c49859632b88}']
322 tony 45 function GetArrayID: TISC_QUAD;
323     procedure Clear;
324     function IsEmpty: boolean;
325     procedure PreLoad;
326     procedure CancelChanges;
327     procedure SaveChanges;
328     function GetAsInteger(index: array of integer): integer;
329     function GetAsBoolean(index: array of integer): boolean;
330     function GetAsCurrency(index: array of integer): Currency;
331     function GetAsInt64(index: array of integer): Int64;
332     function GetAsDateTime(index: array of integer): TDateTime;
333     function GetAsDouble(index: array of integer): Double;
334     function GetAsFloat(index: array of integer): Float;
335     function GetAsLong(index: array of integer): Long;
336     function GetAsShort(index: array of integer): Short;
337 tony 56 function GetAsString(index: array of integer): AnsiString;
338 tony 45 function GetAsVariant(index: array of integer): Variant;
339     procedure SetAsInteger(index: array of integer; AValue: integer);
340     procedure SetAsBoolean(index: array of integer; AValue: boolean);
341     procedure SetAsCurrency(index: array of integer; Value: Currency);
342     procedure SetAsInt64(index: array of integer; Value: Int64);
343     procedure SetAsDate(index: array of integer; Value: TDateTime);
344     procedure SetAsLong(index: array of integer; Value: Long);
345     procedure SetAsTime(index: array of integer; Value: TDateTime);
346     procedure SetAsDateTime(index: array of integer; Value: TDateTime);
347     procedure SetAsDouble(index: array of integer; Value: Double);
348     procedure SetAsFloat(index: array of integer; Value: Float);
349     procedure SetAsShort(index: array of integer; Value: Short);
350 tony 56 procedure SetAsString(index: array of integer; Value: AnsiString);
351 tony 45 procedure SetAsVariant(index: array of integer; Value: Variant);
352     procedure SetBounds(dim, UpperBound, LowerBound: integer);
353     function GetAttachment: IAttachment;
354     function GetTransaction: ITransaction;
355     procedure AddEventHandler(Handler: TArrayEventHandler);
356     procedure RemoveEventHandler(Handler: TArrayEventHandler);
357     end;
358    
359     { The Blob metadata interface provides access to the metadata used to describe
360     a blob column in a Firebird table.
361     }
362    
363     IBlobMetaData = interface
364 tony 56 ['{575f3c61-bb33-46a5-8975-bb7d1b6e37cc}']
365 tony 45 function GetSubType: integer;
366     function GetCharSetID: cardinal;
367     function GetCodePage: TSystemCodePage;
368     function GetSegmentSize: cardinal;
369 tony 56 function GetRelationName: AnsiString;
370     function GetColumnName: AnsiString;
371 tony 45 end;
372    
373     {The Blob Parameter block is used to select a Blob Filter}
374    
375 tony 56 IBPBItem = interface (IParameterBlockItem)
376     ['{660822a5-3114-4c16-b6cb-c1a7b2aba70d}']
377     end;
378 tony 45
379 tony 87 IBPB = interface (IParameterBlock<IBPBItem>)
380 tony 56 ['{e0cb9eb5-17f7-4416-b7d1-3cddd1dfca76}']
381     end;
382 tony 45
383     { The Blob Interface provides access to a blob data item.
384    
385     The interface is returned by a GetAsBlob getter method (see ISQLData). A new Blob
386     can be obtained from the IAttachment interface. The SetAsBlob setter method
387     (See ISQLParam) is used to apply an updated or new array to the database using
388     an UPDATE or INSERT statement.
389     }
390    
391     TFBBlobMode = (fbmRead,fbmWrite);
392     TBlobType = (btSegmented,btStream);
393    
394     IBlob = interface(IBlobMetaData)
395 tony 56 ['{3090a145-7780-442b-b15b-efd4568b8611}']
396 tony 45 function GetBPB: IBPB;
397     procedure Cancel;
398     procedure Close;
399     function GetBlobID: TISC_QUAD;
400     function GetBlobMode: TFBBlobMode;
401     function GetBlobSize: Int64;
402     procedure GetInfo(var NumSegments: Int64; var MaxSegmentSize,
403     TotalSize: Int64; var BlobType: TBlobType);
404     function Read(var Buffer; Count: Longint): Longint;
405     function Write(const Buffer; Count: Longint): Longint;
406 tony 56 function LoadFromFile(Filename: AnsiString): IBlob;
407 tony 45 function LoadFromStream(S: TStream) : IBlob;
408 tony 56 function SaveToFile(Filename: AnsiString): IBlob;
409 tony 45 function SaveToStream(S: TStream): IBlob;
410     function GetAsString: rawbytestring;
411     procedure SetAsString(aValue: rawbytestring);
412     function SetString(aValue: rawbytestring): IBlob;
413     function GetAttachment: IAttachment;
414     function GetTransaction: ITransaction;
415     property AsString: rawbytestring read GetAsString write SetAsString;
416     end;
417    
418     { The IColumnMetaData interface provides access to the per column metadata for
419     the output of an SQL Statement.
420     }
421    
422 tony 270 TIBDateTimeFormats = (dfTimestamp, {SQL TIMESTAMP}
423     dfDateTime, {SQL DATETIME}
424     dfTime); {SQL TIME}
425    
426 tony 45 { IColumnMetaData }
427    
428     IColumnMetaData = interface
429 tony 56 ['{c222e6c3-53c1-469f-9e05-0a5c3ef232d8}']
430 tony 45 function GetIndex: integer;
431     function GetSQLType: cardinal;
432 tony 56 function GetSQLTypeName: AnsiString;
433 tony 45 function getSubtype: integer;
434 tony 56 function getRelationName: AnsiString;
435     function getOwnerName: AnsiString;
436     function getSQLName: AnsiString; {Name of the column}
437     function getAliasName: AnsiString; {Alias Name of column or Column Name if no alias}
438     function getName: AnsiString; {Disambiguated uppercase Field Name}
439 tony 45 function getScale: integer;
440     function getCharSetID: cardinal;
441     function getCodePage: TSystemCodePage;
442     function getIsNullable: boolean;
443     function GetSize: cardinal;
444     function GetArrayMetaData: IArrayMetaData; {Valid only for Array SQL Type}
445     function GetBlobMetaData: IBlobMetaData; {Valid only for Blob SQL Type}
446 tony 270 function GetDateTimeStrLength(DateTimeFormat: TIBDateTimeFormats): integer;
447 tony 291 function GetStatement: IStatement;
448     function GetTransaction: ITransaction;
449 tony 56 property Name: AnsiString read GetName;
450 tony 45 property Size: cardinal read GetSize;
451     property SQLType: cardinal read GetSQLType;
452     property Scale: integer read getScale;
453     property SQLSubtype: integer read getSubtype;
454     property IsNullable: Boolean read GetIsNullable;
455     end;
456    
457     {
458     The IMetaData interface provides access to the set of column metadata
459     for the output of an SQL Statement
460     }
461    
462     { IMetaData }
463    
464     IMetaData = interface
465 tony 56 ['{4dafdbb6-0d36-4f1f-9c95-8b132804b965}']
466 tony 45 function getCount: integer;
467     function getColumnMetaData(index: integer): IColumnMetaData;
468 tony 56 function GetUniqueRelationName: AnsiString; {Non empty if all columns come from the same table}
469     function ByName(Idx: AnsiString): IColumnMetaData;
470 tony 45 property ColMetaData[index: integer]: IColumnMetaData read getColumnMetaData; default;
471     property Count: integer read getCount;
472     end;
473    
474     {
475     The ISQLData interface provides access to the data returned in a field in the
476     current row returned from a query or the result of an SQL Execute statement.
477    
478     It subclasses IColumnMetaData and so also provides access to the metadata
479     associated with the column.
480    
481     The getter and setter methods, and the corresponding properties, provide typed
482     access to the field data. The method/property used should be consistent
483     with the SQL Type. Automatic conversion is provided from strings.
484     That is GetAsString is safe to use for sql types other than boolean.
485     }
486    
487    
488     ISQLData = interface(IColumnMetaData)
489 tony 56 ['{3f493e31-7e3f-4606-a07c-b210b9e3619d}']
490 tony 291 function GetStrDataLength: short;
491 tony 45 function GetAsBoolean: boolean;
492     function GetAsCurrency: Currency;
493     function GetAsInt64: Int64;
494     function GetAsDateTime: TDateTime;
495     function GetAsDouble: Double;
496     function GetAsFloat: Float;
497     function GetAsLong: Long;
498     function GetAsPointer: Pointer;
499     function GetAsQuad: TISC_QUAD;
500     function GetAsShort: short;
501 tony 56 function GetAsString: AnsiString;
502 tony 45 function GetIsNull: Boolean;
503     function GetAsVariant: Variant;
504     function GetAsBlob: IBlob; overload;
505     function GetAsBlob(BPB: IBPB): IBlob; overload;
506     function GetAsArray: IArray;
507     property AsDate: TDateTime read GetAsDateTime;
508     property AsBoolean:boolean read GetAsBoolean;
509     property AsTime: TDateTime read GetAsDateTime;
510     property AsDateTime: TDateTime read GetAsDateTime ;
511     property AsDouble: Double read GetAsDouble;
512     property AsFloat: Float read GetAsFloat;
513     property AsCurrency: Currency read GetAsCurrency;
514     property AsInt64: Int64 read GetAsInt64 ;
515     property AsInteger: Integer read GetAsLong;
516     property AsLong: Long read GetAsLong;
517     property AsPointer: Pointer read GetAsPointer;
518     property AsQuad: TISC_QUAD read GetAsQuad;
519     property AsShort: short read GetAsShort;
520 tony 56 property AsString: AnsiString read GetAsString;
521 tony 45 property AsVariant: Variant read GetAsVariant ;
522     property AsBlob: IBlob read GetAsBlob;
523     property AsArray: IArray read GetAsArray;
524     property IsNull: Boolean read GetIsNull;
525     property Value: Variant read GetAsVariant;
526     end;
527    
528     { An IResults interface is returned as the result of an SQL Execute statement
529     and provides access to the fields returned, if any. It is a collection of
530     ISQLData interfaces which are, in turn, used to access the data returned by
531     each field of the result set.
532     }
533    
534     IResults = interface
535 tony 56 ['{e836b2bb-93d1-4bbf-a8eb-7ce535de3bb5}']
536 tony 45 function getCount: integer;
537 tony 291 function GetStatement: IStatement;
538 tony 45 function GetTransaction: ITransaction;
539 tony 56 function ByName(Idx: AnsiString): ISQLData;
540 tony 45 function getSQLData(index: integer): ISQLData;
541 tony 56 procedure GetData(index: integer; var IsNull:boolean; var len: short; var data: PByte);
542 tony 45 procedure SetRetainInterfaces(aValue: boolean);
543     property Data[index: integer]: ISQLData read getSQLData; default;
544     property Count: integer read getCount;
545     end;
546    
547     { An IResultSet interface is returned as the result of an SQL Open Cursor statement
548     (e.g. Select Statement) and provides access to the fields returned, if any
549     for the current row. It is a collection of ISQLData interfaces which are,
550     in turn, used to access the data returned by each field of the current row.
551     }
552     IResultSet = interface(IResults)
553 tony 56 ['{0ae4979b-7857-4e8c-8918-ec6f155b51a0}']
554 tony 45 function FetchNext: boolean;
555 tony 56 function GetCursorName: AnsiString;
556 tony 45 function IsEof: boolean;
557     procedure Close;
558     end;
559    
560     {The ISQLParam interface is used to provide access to each parameter in a
561     parametised SQL Statement. It subclasses IColumnMetaData and this part of
562     the interface may be used to access information on the expected SQL Type, etc.
563    
564     It also subclasses ISQLData and this part of the interface may be used to access
565     current values for each parameter.
566    
567     Otherwise, the interface comprises the Setter Methods and properties used to
568     set the value of each parameter.
569    
570     Automatic conversion is provided to and from strings. That is GetAsString and
571     SetAsString are safe to use for sql types other than boolean - provided automatic
572     conversion is possible.
573     }
574    
575     ISQLParam = interface
576 tony 56 ['{b22b4578-6d41-4807-a9a9-d2ec8d1d5a14}']
577 tony 45 function GetIndex: integer;
578     function GetSQLType: cardinal;
579 tony 56 function GetSQLTypeName: AnsiString;
580 tony 45 function getSubtype: integer;
581 tony 56 function getName: AnsiString;
582 tony 45 function getScale: integer;
583     function getCharSetID: cardinal;
584     function getCodePage: TSystemCodePage;
585     function getIsNullable: boolean;
586     function GetSize: cardinal;
587     function GetAsBoolean: boolean;
588     function GetAsCurrency: Currency;
589     function GetAsInt64: Int64;
590     function GetAsDateTime: TDateTime;
591     function GetAsDouble: Double;
592     function GetAsFloat: Float;
593     function GetAsLong: Long;
594     function GetAsPointer: Pointer;
595     function GetAsQuad: TISC_QUAD;
596     function GetAsShort: short;
597 tony 56 function GetAsString: AnsiString;
598 tony 45 function GetIsNull: boolean;
599     function GetAsVariant: Variant;
600     function GetAsBlob: IBlob;
601     function GetAsArray: IArray;
602     procedure Clear;
603     function GetModified: boolean;
604     procedure SetAsBoolean(AValue: boolean);
605     procedure SetAsCurrency(aValue: Currency);
606     procedure SetAsInt64(aValue: Int64);
607     procedure SetAsDate(aValue: TDateTime);
608     procedure SetAsLong(aValue: Long);
609     procedure SetAsTime(aValue: TDateTime);
610     procedure SetAsDateTime(aValue: TDateTime);
611     procedure SetAsDouble(aValue: Double);
612     procedure SetAsFloat(aValue: Float);
613     procedure SetAsPointer(aValue: Pointer);
614     procedure SetAsShort(aValue: Short);
615 tony 56 procedure SetAsString(aValue: AnsiString);
616 tony 45 procedure SetAsVariant(aValue: Variant);
617     procedure SetIsNull(aValue: Boolean);
618     procedure SetAsBlob(aValue: IBlob);
619     procedure SetAsArray(anArray: IArray);
620     procedure SetAsQuad(aValue: TISC_QUAD);
621     procedure SetCharSetID(aValue: cardinal);
622     property AsDate: TDateTime read GetAsDateTime write SetAsDate;
623     property AsBoolean:boolean read GetAsBoolean write SetAsBoolean;
624     property AsTime: TDateTime read GetAsDateTime write SetAsTime;
625     property AsDateTime: TDateTime read GetAsDateTime write SetAsDateTime;
626     property AsDouble: Double read GetAsDouble write SetAsDouble;
627     property AsFloat: Float read GetAsFloat write SetAsFloat;
628     property AsCurrency: Currency read GetAsCurrency write SetAsCurrency;
629     property AsInt64: Int64 read GetAsInt64 write SetAsInt64;
630     property AsInteger: Integer read GetAsLong write SetAsLong;
631     property AsLong: Long read GetAsLong write SetAsLong;
632     property AsPointer: Pointer read GetAsPointer write SetAsPointer;
633     property AsShort: Short read GetAsShort write SetAsShort;
634 tony 56 property AsString: AnsiString read GetAsString write SetAsString;
635 tony 45 property AsVariant: Variant read GetAsVariant write SetAsVariant;
636     property AsBlob: IBlob read GetAsBlob write SetAsBlob;
637     property AsArray: IArray read GetAsArray write SetAsArray;
638     property AsQuad: TISC_QUAD read GetAsQuad write SetAsQuad;
639     property Value: Variant read GetAsVariant write SetAsVariant;
640     property IsNull: Boolean read GetIsNull write SetIsNull;
641     property IsNullable: Boolean read GetIsNullable;
642     property Modified: Boolean read getModified;
643 tony 56 property Name: AnsiString read GetName;
644 tony 45 property SQLType: cardinal read GetSQLType;
645     end;
646    
647     {
648     The ISQLParams interface provides access to the collection of parameters used
649     for the input to an SQL Statement
650     }
651    
652     ISQLParams = interface
653 tony 56 ['{c6d95ac7-b2b7-461b-b890-afef0acbb077}']
654 tony 45 function getCount: integer;
655     function getSQLParam(index: integer): ISQLParam;
656 tony 56 function ByName(Idx: AnsiString): ISQLParam ;
657 tony 45 function GetModified: Boolean;
658 tony 287 function GetHasCaseSensitiveParams: Boolean;
659 tony 45 property Modified: Boolean read GetModified;
660     property Params[index: integer]: ISQLParam read getSQLParam; default;
661     property Count: integer read getCount;
662     end;
663    
664 tony 47
665     TPerfStats = (psCurrentMemory, psMaxMemory,
666     psRealTime, psUserTime, psBuffers,
667     psReads, psWrites, psFetches,psDeltaMemory);
668    
669 tony 209 TPerfCounters = array[TPerfStats] of Int64;
670 tony 47
671 tony 45 {The IStatement interface provides access to an SQL Statement once it has been
672     initially prepared. The interface is returned from the IAttachment interface.
673     }
674    
675     IStatement = interface
676 tony 56 ['{a260576d-a07d-4a66-b02d-1b72543fd7cf}']
677 tony 45 function GetMetaData: IMetaData; {Output Metadata}
678     function GetSQLParams: ISQLParams;{Statement Parameters}
679 tony 56 function GetPlan: AnsiString;
680 tony 45 function GetRowsAffected(var SelectCount, InsertCount, UpdateCount, DeleteCount: integer): boolean;
681     function GetSQLStatementType: TIBSQLStatementTypes;
682 tony 56 function GetSQLText: AnsiString;
683 tony 263 function GetProcessedSQLText: AnsiString;
684 tony 45 function GetSQLDialect: integer;
685     function IsPrepared: boolean;
686     procedure Prepare(aTransaction: ITransaction=nil);
687     function Execute(aTransaction: ITransaction=nil): IResults;
688     function OpenCursor(aTransaction: ITransaction=nil): IResultSet;
689     function GetAttachment: IAttachment;
690     function GetTransaction: ITransaction;
691     procedure SetRetainInterfaces(aValue: boolean);
692 tony 47 procedure EnableStatistics(aValue: boolean);
693     function GetPerfStatistics(var stats: TPerfCounters): boolean;
694 tony 45 property MetaData: IMetaData read GetMetaData;
695     property SQLParams: ISQLParams read GetSQLParams;
696     property SQLStatementType: TIBSQLStatementTypes read GetSQLStatementType;
697     end;
698    
699     {Transaction Parameter Block: (TPB)
700    
701     The TPB provides the parameters used when starting a transaction. It is allocated
702     empty by the FirebirdAPI and the parameters are then added to it. Each individual
703     parameter may be accessed by the ITPBItem interface which can be used to set the
704     value, if any, of the parameter.
705    
706     The TPB parameters, and the associated symbolic codes and parameter values may be
707     found in the Interbase 6.0 API Guide.
708     }
709    
710 tony 56 ITPBItem = interface(IParameterBlockItem)
711     ['{544c1f2b-7c12-4a87-a4a5-face7ea72671}']
712     end;
713 tony 45
714 tony 56 ITPB = interface(IParameterBlock<ITPBItem>)
715     ['{7369b0ff-defe-437b-81fe-19b211d42d25}']
716     end;
717 tony 45
718     {The ITransactionAction interface provides access to a Transaction once it
719     has been initially started. After a Commit or Rollback, a transaction
720     may be restarted, optinally with a new TPB.
721    
722     A multi-database transaction is started from the FirebirdAPI. A single database
723     transaction is started from the IAttachment interface.
724     }
725    
726     TTransactionAction = (TARollback, TACommit, TACommitRetaining, TARollbackRetaining);
727     TTransactionCompletion = TARollback.. TACommit;
728    
729     ITransaction = interface
730 tony 56 ['{30928d0e-a9d7-4c61-b7cf-14f4f38abe2a}']
731 tony 45 function getTPB: ITPB;
732     procedure Start(DefaultCompletion: TTransactionCompletion=taCommit);
733     function GetInTransaction: boolean;
734     procedure PrepareForCommit; {Two phase commit - stage 1}
735     procedure Commit(Force: boolean=false);
736     procedure CommitRetaining;
737     function HasActivity: boolean;
738     procedure Rollback(Force: boolean=false);
739     procedure RollbackRetaining;
740     function GetAttachmentCount: integer;
741     function GetAttachment(index: integer): IAttachment;
742     property InTransaction: boolean read GetInTransaction;
743     end;
744    
745     { The IEvents Interface is used to handle events from a single database. The
746     interface is allocated from the IAttachment Interface.
747    
748     Note that the EventHandler called when an event occurs following AsynWaitForEvent
749     is called in a different thread to the calling program and TThread.Synchronize
750     may be needed to pass the event back to the main thread.
751    
752     Neither AsyncWaitForEvent nor WaitForEvent is intended to be thread safe
753     in a multi-threaded environment and should always be called from the main
754     thread.
755     }
756    
757     TEventInfo = record
758 tony 56 EventName: AnsiString;
759 tony 45 Count: integer;
760     end;
761    
762     TEventCounts = array of TEventInfo;
763     IEvents = interface;
764     TEventHandler = procedure(Sender: IEvents) of object;
765    
766     { IEvents }
767    
768     IEvents = interface
769 tony 56 ['{6a0be233-ed08-4524-889c-2e45d0c20e5f}']
770 tony 45 procedure GetEvents(EventNames: TStrings);
771     procedure SetEvents(EventNames: TStrings); overload;
772 tony 56 procedure SetEvents(EventName: AnsiString); overload;
773 tony 45 procedure Cancel;
774     function ExtractEventCounts: TEventCounts;
775     procedure WaitForEvent;
776     procedure AsyncWaitForEvent(EventHandler: TEventHandler);
777     function GetAttachment: IAttachment;
778     end;
779    
780     {The IDBInformation Interface.
781    
782     An IDBInformation interface is returned by the IAttachment GetDBInformation
783     method. The interface provides access to the information requested and
784     returned by the method.
785    
786     IDBInformation itself gives access to a collection of IDBInfoItems. Each one
787     provides information requested, as indicated by the ItemType and the actual
788     value of the information. In some cases, the returned item is itself a
789     colletion of IDBInfoItems.
790    
791     The IDBInformation items, and the associated symbolic codes and parameter values may be
792     found in the Interbase 6.0 API Guide.
793     }
794    
795     TDBOperationCount = record
796     TableID: UShort;
797     Count: cardinal;
798     end;
799    
800     TDBOperationCounts = array of TDBOperationCount;
801    
802     IDBInfoItem = interface
803 tony 56 ['{eeb97b51-ec0f-473f-9f75-c1721f055fcb}']
804 tony 45 function getItemType: byte;
805     function getSize: integer;
806     procedure getRawBytes(var Buffer);
807 tony 56 function getAsString: AnsiString;
808 tony 45 function getAsInteger: integer;
809 tony 56 procedure DecodeIDCluster(var ConnectionType: integer; var DBFileName, DBSiteName: AnsiString);
810 tony 45 function getAsBytes: TByteArray;
811 tony 143 function getAsDateTime: TDateTime;
812 tony 56 procedure DecodeVersionString(var Version: byte; var VersionString: AnsiString);
813 tony 45 function getOperationCounts: TDBOperationCounts;
814     procedure DecodeUserNames(UserNames: TStrings);
815    
816     {user names only}
817     function GetCount: integer;
818     function GetItem(index: integer): IDBInfoItem;
819     function Find(ItemType: byte): IDBInfoItem;
820     property AsInteger: integer read getAsInteger;
821 tony 56 property AsString: AnsiString read GetAsString;
822 tony 45 property Count: integer read GetCount;
823     property Items[index: integer]: IDBInfoItem read getItem; default;
824     end;
825    
826     { IDBInformation }
827    
828     IDBInformation = interface
829 tony 56 ['{7ac6777f-f0a9-498a-9f5c-4a57a554df81}']
830 tony 45 function GetCount: integer;
831     function GetItem(index: integer): IDBInfoItem;
832     function Find(ItemType: byte): IDBInfoItem;
833     procedure PrintBuf; {can be used to print buffer in hex for debugging}
834     property Count: integer read GetCount;
835     property Items[index: integer]: IDBInfoItem read getItem; default;
836     end;
837    
838 tony 143 {The Database Information Request Block is used to pass requests for
839     database information where at least one item requested has a parameter.
840     At present, this is only fb_info_page_contents which has a single
841     integer parameter.}
842    
843     IDIRBItem = interface(IParameterBlockItem)
844     ['{d34a7511-8435-4a24-81a7-5103d218d234}']
845     end;
846    
847     IDIRB = interface(IParameterBlock<IDIRBItem>)
848     ['{1010e5ac-0a8f-403b-a302-91625e9d9579}']
849     end;
850    
851    
852 tony 45 {The Database Parameter Block (DPB).
853    
854     The DPB provides the parameters used when connecting to a database. It is allocated
855     empty by the FirebirdAPI and the parameters are then added to it. Each individual
856     parameter may be accessed by the IDPBItem interface which can be used to set the
857     value, if any, of the parameter.
858    
859     The DPB parameters, and the associated symbolic codes and parameter values may be
860     found in the Interbase 6.0 API Guide.
861     }
862    
863 tony 56 IDPBItem = interface(IParameterBlockItem)
864     ['{123d4ad0-087a-4cd1-a344-1b3d03b30673}']
865     end;
866 tony 45
867 tony 56 IDPB = interface(IParameterBlock<IDPBItem>)
868     ['{e676067b-1cf4-4eba-9256-9724f57e0d16}']
869     end;
870 tony 45
871     {The IAttachment interface provides access to a Database Connection. It may be
872     used to:
873    
874     a. Disconnect and reconnect to the database.
875    
876     b. Start a Transaction on the database
877    
878     c. Execute directly SQL DDL Statements and others that return no information.
879    
880     d. OpenCursors (i.e. execute SQL Select statements and return the results)
881    
882     e. Prepare SQL Statements, returning an IStatement interface for further processing.
883    
884     f. Provide access to an SQL Event Handler.
885    
886     g. Access Database Information.
887    
888     h. Support the handling of Array and Blob data.
889    
890     Note that SQL statements can be prepared with named parameters (PSQL style).
891     This then allows the parameters to be accessed by name. The same name can
892     be used for more than one parameter, allowing a single operation to be used
893     to set all parameters with the same name.
894     }
895    
896     { IAttachment }
897    
898     IAttachment = interface
899 tony 56 ['{466e9b67-9def-4807-b3e7-e08a35e7185c}']
900 tony 263 function getFirebirdAPI: IFirebirdAPI;
901 tony 45 function getDPB: IDPB;
902     function AllocateBPB: IBPB;
903 tony 143 function AllocateDIRB: IDIRB;
904 tony 45 procedure Connect;
905     procedure Disconnect(Force: boolean=false);
906     function IsConnected: boolean;
907     procedure DropDatabase;
908     function StartTransaction(TPB: array of byte; DefaultCompletion: TTransactionCompletion=taCommit): ITransaction; overload;
909     function StartTransaction(TPB: ITPB; DefaultCompletion: TTransactionCompletion=taCommit): ITransaction; overload;
910 tony 56 procedure ExecImmediate(transaction: ITransaction; sql: AnsiString; SQLDialect: integer); overload;
911     procedure ExecImmediate(TPB: array of byte; sql: AnsiString; SQLDialect: integer); overload;
912     procedure ExecImmediate(transaction: ITransaction; sql: AnsiString); overload;
913     procedure ExecImmediate(TPB: array of byte; sql: AnsiString); overload;
914     function ExecuteSQL(TPB: array of byte; sql: AnsiString; SQLDialect: integer; params: array of const): IResults; overload;
915     function ExecuteSQL(transaction: ITransaction; sql: AnsiString; SQLDialect: integer; params: array of const): IResults; overload;
916     function ExecuteSQL(TPB: array of byte; sql: AnsiString; params: array of const): IResults; overload;
917     function ExecuteSQL(transaction: ITransaction; sql: AnsiString; params: array of const): IResults; overload;
918     function OpenCursor(transaction: ITransaction; sql: AnsiString; aSQLDialect: integer): IResultSet; overload;
919     function OpenCursor(transaction: ITransaction; sql: AnsiString; aSQLDialect: integer;
920 tony 45 params: array of const): IResultSet; overload;
921 tony 56 function OpenCursor(transaction: ITransaction; sql: AnsiString): IResultSet; overload;
922     function OpenCursor(transaction: ITransaction; sql: AnsiString;
923 tony 45 params: array of const): IResultSet; overload;
924 tony 56 function OpenCursorAtStart(transaction: ITransaction; sql: AnsiString; aSQLDialect: integer): IResultSet; overload;
925     function OpenCursorAtStart(transaction: ITransaction; sql: AnsiString; aSQLDialect: integer;
926 tony 45 params: array of const): IResultSet; overload;
927 tony 56 function OpenCursorAtStart(transaction: ITransaction; sql: AnsiString): IResultSet; overload;
928     function OpenCursorAtStart(transaction: ITransaction; sql: AnsiString;
929 tony 45 params: array of const): IResultSet; overload;
930 tony 56 function OpenCursorAtStart(sql: AnsiString): IResultSet; overload;
931     function OpenCursorAtStart(sql: AnsiString;
932 tony 45 params: array of const): IResultSet; overload;
933 tony 56 function Prepare(transaction: ITransaction; sql: AnsiString; aSQLDialect: integer): IStatement; overload;
934     function Prepare(transaction: ITransaction; sql: AnsiString): IStatement; overload;
935     function PrepareWithNamedParameters(transaction: ITransaction; sql: AnsiString;
936 tony 270 aSQLDialect: integer; GenerateParamNames: boolean=false;
937     CaseSensitiveParams: boolean = false): IStatement; overload;
938 tony 56 function PrepareWithNamedParameters(transaction: ITransaction; sql: AnsiString;
939 tony 270 GenerateParamNames: boolean=false;
940     CaseSensitiveParams: boolean = false): IStatement; overload;
941 tony 45
942     {Events}
943     function GetEventHandler(Events: TStrings): IEvents; overload;
944 tony 56 function GetEventHandler(Event: AnsiString): IEvents; overload;
945 tony 45
946     {Blob - may use to open existing Blobs. However, ISQLData.AsBlob is preferred}
947    
948 tony 56 function CreateBlob(transaction: ITransaction; RelationName, ColumnName: AnsiString; BPB: IBPB=nil): IBlob; overload;
949 tony 45 function CreateBlob(transaction: ITransaction; BlobMetaData: IBlobMetaData; BPB: IBPB=nil): IBlob; overload;
950     function CreateBlob(transaction: ITransaction; SubType: integer; CharSetID: cardinal=0; BPB: IBPB=nil): IBlob; overload;
951 tony 291 function OpenBlob(transaction: ITransaction; RelationName, ColumnName: AnsiString; BlobID: TISC_QUAD; BPB: IBPB=nil): IBlob; overload;
952     function OpenBlob(transaction: ITransaction; BlobMetaData: IBlobMetaData; BlobID: TISC_QUAD; BPB: IBPB=nil): IBlob; overload;
953 tony 45
954     {Array - may use to open existing arrays. However, ISQLData.AsArray is preferred}
955    
956 tony 291 function OpenArray(transaction: ITransaction; RelationName, ColumnName: AnsiString; ArrayID: TISC_QUAD): IArray; overload;
957     function OpenArray(transaction: ITransaction; ArrayMetaData: IArrayMetaData; ArrayID: TISC_QUAD): IArray; overload;
958 tony 56 function CreateArray(transaction: ITransaction; RelationName, ColumnName: AnsiString): IArray; overload;
959 tony 45 function CreateArray(transaction: ITransaction; ArrayMetaData: IArrayMetaData): IArray; overload;
960 tony 56 function CreateArrayMetaData(SQLType: cardinal; tableName: AnsiString; columnName: AnsiString;
961 tony 47 Scale: integer; size: cardinal; charSetID: cardinal; dimensions: cardinal;
962     bounds: TArrayBounds): IArrayMetaData;
963 tony 45
964     {Database Information}
965     function GetSQLDialect: integer;
966 tony 56 function GetBlobMetaData(Transaction: ITransaction; tableName, columnName: AnsiString): IBlobMetaData;
967     function GetArrayMetaData(Transaction: ITransaction; tableName, columnName: AnsiString): IArrayMetaData;
968 tony 45 function GetDBInformation(Requests: array of byte): IDBInformation; overload;
969     function GetDBInformation(Request: byte): IDBInformation; overload;
970 tony 143 function GetDBInformation(Requests: IDIRB): IDBInformation; overload;
971 tony 117 function GetConnectString: AnsiString;
972     function GetRemoteProtocol: AnsiString;
973 tony 143 function GetAuthenticationMethod: AnsiString;
974 tony 209 function GetSecurityDatabase: AnsiString;
975 tony 117 function GetODSMajorVersion: integer;
976     function GetODSMinorVersion: integer;
977 tony 266 procedure getFBVersion(version: TStrings);
978 tony 45 function HasActivity: boolean;
979 tony 60
980     {Character Sets}
981 tony 109 function HasDefaultCharSet: boolean;
982     function GetDefaultCharSetID: integer;
983 tony 60 function GetCharsetName(CharSetID: integer): AnsiString;
984     function CharSetID2CodePage(CharSetID: integer; var CodePage: TSystemCodePage): boolean;
985     function CodePage2CharSetID(CodePage: TSystemCodePage; var CharSetID: integer): boolean;
986     function CharSetName2CharSetID(CharSetName: AnsiString; var CharSetID: integer): boolean;
987     function CharSetWidth(CharSetID: integer; var Width: integer): boolean;
988     procedure RegisterCharSet(CharSetName: AnsiString; CodePage: TSystemCodePage;
989     AllowReverseLookup:boolean; out CharSetID: integer);
990 tony 45 end;
991    
992 tony 231 TProtocolAll = (TCP, SPX, NamedPipe, Local, inet, inet4, inet6, wnet, xnet, unknownProtocol);
993 tony 143 TProtocol = TCP..xnet;
994 tony 45
995     {Service Parameter Block (SPB).
996    
997     The SPB provides the parameters used when connecting to a Service Manager. It is
998     allocated empty by the FirebirdAPI and the parameters are then added to it. Each
999     individual parameter may be accessed by the ISPBItem interface which can be used
1000     to set the value, if any, of the parameter.
1001    
1002     The SPB parameters, and the associated symbolic codes and parameter values may be
1003     found in the Interbase 6.0 API Guide.
1004    
1005     }
1006    
1007 tony 56 ISPBItem = interface(IParameterBlockItem)
1008     ['{5d08ae2b-4519-41bd-8b40-97cd451c3f6a}']
1009     end;
1010 tony 45
1011 tony 56 ISPB = interface(IParameterBlock<ISPBItem>)
1012     ['{2c5836fd-41ed-4426-9b7d-5af580ec2659}']
1013     end;
1014 tony 45
1015     {Service Query Parameter Block (SQPB).
1016    
1017     This is a specialised parameter block used to send data to a service manager
1018     in a Query Request.
1019     }
1020    
1021     ISQPBItem = interface(IParameterBlockItem)
1022 tony 56 ['{b07841a6-33b3-47f0-b5a2-028cbc86dc97}']
1023 tony 45 function CopyFrom(source: TStream; count: integer): integer;
1024     end;
1025    
1026 tony 56 ISQPB = interface(IParameterBlock<ISQPBItem>)
1027     ['{8553e66b-ee62-498b-8431-dff030211447}']
1028     end;
1029 tony 45
1030     {Service Request Block (SRB).
1031    
1032     The SRB specifies what is requested from the Service Manager when starting a
1033     service or querying a service. It is allocated empty by the ServiceManager API and
1034     the parameters are then added to it. Each individual parameter may be accessed
1035     by the ISRBItem interface which can be used to set the value, if any, of the parameter.
1036    
1037     The SRB parameters, and the associated symbolic codes and parameter values may be
1038     found in the Interbase 6.0 API Guide.
1039    
1040     }
1041    
1042 tony 56 ISRBItem = interface(IParameterBlockItem)
1043     ['{47ec790e-f265-4b30-9dcd-261e51677245}']
1044     end;
1045 tony 45
1046 tony 56 ISRB = interface(IParameterBlock<ISRBItem>)
1047     ['{9f2e204f-3c33-4e44-90f9-9135e95dafb9}']
1048     end;
1049 tony 45
1050     {The Service Query Results Interface.
1051    
1052     An IServiceQueryResults interface is returned by the IServiceManager Query
1053     method. The interface provides access to the information requested and
1054     returned by the method.
1055    
1056     IServiceQueryResults itself gives access to a collection of IServiceQueryResultItem.
1057     Each one provides information requested, as indicated by the ItemType and the actual
1058     value of the information. In some cases, the returned item is itself a
1059     collection of IServiceQueryResultSubItem.
1060    
1061     The IServiceQueryResultItem items, and the associated symbolic codes and parameter values may be
1062     found in the Interbase 6.0 API Guide.
1063     }
1064    
1065     IServiceQueryResultSubItem = interface
1066 tony 56 ['{8a4c381e-9923-4cc9-a96b-553729248640}']
1067 tony 45 function getItemType: byte;
1068     function getSize: integer;
1069     procedure getRawBytes(var Buffer);
1070 tony 56 function getAsString: AnsiString;
1071 tony 45 function getAsInteger: integer;
1072     function getAsByte: byte;
1073     function CopyTo(stream: TStream; count: integer): integer;
1074 tony 56 property AsString: AnsiString read getAsString;
1075 tony 45 property AsInteger: integer read getAsInteger;
1076     property AsByte: byte read getAsByte;
1077     end;
1078    
1079     IServiceQueryResultItem = interface(IServiceQueryResultSubItem)
1080 tony 56 ['{b2806886-206c-4024-8df9-5fe0a7630a5e}']
1081 tony 45 function getCount: integer;
1082     function getItem(index: integer): IServiceQueryResultSubItem;
1083     function find(ItemType: byte): IServiceQueryResultSubItem;
1084     property Items[index: integer]: IServiceQueryResultSubItem read getItem; default;
1085     property Count: integer read getCount;
1086     end;
1087    
1088     IServiceQueryResults = interface
1089 tony 56 ['{8fbbef7d-fe03-4409-828a-a787d34ef531}']
1090 tony 45 function getCount: integer;
1091     function getItem(index: integer): IServiceQueryResultItem;
1092     function find(ItemType: byte): IServiceQueryResultItem;
1093     procedure PrintBuf; {can be used to print buffer in hex for debugging}
1094     property Items[index: integer]: IServiceQueryResultItem read getItem; default;
1095     property Count: integer read getCount;
1096     end;
1097    
1098 tony 263 IFirebirdLibrary = interface;
1099    
1100 tony 45 {The IServiceManager interface provides access to a service manager. It can
1101     used to Detach and re-attach to Service Manager, to start services and to
1102     query the service manager.
1103    
1104     The interface is returned by the FirebirdAPI GetService Manager method.
1105     }
1106    
1107     { IServiceManager }
1108    
1109     IServiceManager = interface
1110 tony 56 ['{905b587d-1e1f-4e40-a3f8-a3519f852e48}']
1111 tony 263 function getFirebirdAPI: IFirebirdAPI;
1112 tony 45 function getSPB: ISPB;
1113 tony 56 function getServerName: AnsiString;
1114 tony 209 function getProtocol: TProtocol;
1115     function getPortNo: AnsiString;
1116 tony 45 procedure Attach;
1117     procedure Detach(Force: boolean=false);
1118     function IsAttached: boolean;
1119     function AllocateSRB: ISRB;
1120     function AllocateSQPB: ISQPB;
1121 tony 209 function Start(Request: ISRB; RaiseExceptionOnError: boolean=true): boolean;
1122     function Query(SQPB: ISQPB; Request: ISRB; RaiseExceptionOnError: boolean=true) :IServiceQueryResults; overload;
1123     function Query(Request: ISRB; RaiseExceptionOnError: boolean=true) :IServiceQueryResults; overload;
1124 tony 45 end;
1125    
1126 tony 263 {Tbe Firebird Library API used to get information about the Firebird library}
1127    
1128    
1129     IFirebirdLibrary = interface
1130     ['{3c04e0a1-12e0-428a-b2e1-bc6fcd97b79b}']
1131     function GetHandle: TLibHandle;
1132     function GetLibraryName: string;
1133     function GetLibraryFilePath: string;
1134     function GetFirebirdAPI: IFirebirdAPI;
1135     end;
1136    
1137 tony 45 {The Firebird API.
1138    
1139     This is the base interface and is used to create/open a database connection, to
1140     start a transaction on multiple databases and the access the service manager.
1141    
1142     The interface is returned by the FirebirdAPI function.
1143     }
1144    
1145     IFirebirdAPI = interface
1146 tony 56 ['{edeee691-c8d3-4dcf-a780-cd7e432821d5}']
1147 tony 45 {Database connections}
1148     function AllocateDPB: IDPB;
1149 tony 56 function OpenDatabase(DatabaseName: AnsiString; DPB: IDPB; RaiseExceptionOnConnectError: boolean=true): IAttachment;
1150     function CreateDatabase(DatabaseName: AnsiString; DPB: IDPB; RaiseExceptionOnError: boolean=true): IAttachment; overload;
1151     function CreateDatabase(sql: AnsiString; aSQLDialect: integer; RaiseExceptionOnError: boolean=true): IAttachment; overload;
1152 tony 45
1153     {Start Transaction against multiple databases}
1154     function AllocateTPB: ITPB;
1155     function StartTransaction(Attachments: array of IAttachment;
1156     TPB: array of byte; DefaultCompletion: TTransactionCompletion=taCommit): ITransaction; overload;
1157     function StartTransaction(Attachments: array of IAttachment;
1158     TPB: ITPB; DefaultCompletion: TTransactionCompletion=taCommit): ITransaction; overload;
1159    
1160     {Service Manager}
1161     function HasServiceAPI: boolean;
1162     function AllocateSPB: ISPB;
1163 tony 143 function GetServiceManager(ServerName: AnsiString; Protocol: TProtocol; SPB: ISPB): IServiceManager; overload;
1164     function GetServiceManager(ServerName: AnsiString; Port: AnsiString; Protocol: TProtocol; SPB: ISPB): IServiceManager; overload;
1165 tony 45
1166     {Information}
1167     function GetStatus: IStatus;
1168     function HasRollbackRetaining: boolean;
1169     function IsEmbeddedServer: boolean;
1170 tony 56 function GetImplementationVersion: AnsiString;
1171 tony 45
1172     {Firebird 3 API}
1173     function HasMasterIntf: boolean;
1174     function GetIMaster: TObject;
1175 tony 263 function GetFBLibrary: IFirebirdLibrary;
1176 tony 45 end;
1177    
1178     type
1179     TOnGetLibraryName = procedure(var libname: string);
1180    
1181     const
1182     OnGetLibraryName: TOnGetLibraryName = nil;
1183     AllowUseOfFBLIB: boolean = false;
1184    
1185     type
1186     { EIBError }
1187    
1188     EIBError = class(EDatabaseError)
1189     private
1190     FSQLCode: Long;
1191     public
1192 tony 56 constructor Create(ASQLCode: Long; Msg: AnsiString);
1193 tony 45 property SQLCode: Long read FSQLCode;
1194     end;
1195    
1196     { EIBInterBaseError - Firebird Engine errors}
1197    
1198     EIBInterBaseError = class(EIBError)
1199     private
1200     FIBErrorCode: Long;
1201     public
1202     constructor Create(Status: IStatus); overload;
1203 tony 56 constructor Create(ASQLCode: Long; AIBErrorCode: Long; Msg: AnsiString); overload;
1204 tony 45 property IBErrorCode: Long read FIBErrorCode;
1205     end;
1206    
1207     {IB Client Exceptions}
1208     EIBClientError = class(EIBError);
1209    
1210     {The Firebird API function is used to access the IFirebirdAPI interface.
1211    
1212     It will load the Firebird Client Library if this is not already loaded and
1213     select an implementation of the Firebird API (legacy 2.5 or 3.0.
1214     }
1215    
1216     function FirebirdAPI: IFirebirdAPI;
1217    
1218     {IBX support functions. Probably best ignored i.e. always used the FirebirdAPI
1219     functino to load the library and check if it's loaded.}
1220    
1221     function TryIBLoad: Boolean;
1222     procedure CheckIBLoaded;
1223    
1224 tony 263 {If you want to explicitly load the Firebird library from a
1225     non-default location then use this function and its GetFirebirdAPI function
1226     to get the API.}
1227    
1228     function LoadFBLibrary(aLibPathName: string): IFirebirdLibrary;
1229    
1230 tony 45 implementation
1231    
1232     uses FBClientAPI
1233     {$IFDEF USELEGACYFIREBIRDAPI}, FB25ClientAPI {$ENDIF}
1234     {$IFDEF USEFIREBIRD3API}, FB30ClientAPI {$ENDIF};
1235    
1236 tony 263 var FDefaultFBLibrary: IFirebirdLibrary;
1237 tony 45
1238 tony 263 type
1239    
1240     { TFBLibrary }
1241    
1242     TFBLibraryImpl = class(TFBLibrary)
1243     protected
1244     function GetFirebird3API: IFirebirdAPI; override;
1245     function GetLegacyFirebirdAPI: IFirebirdAPI; override;
1246     end;
1247    
1248     function TFBLibraryImpl.GetFirebird3API: IFirebirdAPI;
1249     begin
1250     {$IFDEF USEFIREBIRD3API}
1251     Result := TFB30ClientAPI.Create(self);
1252     {$ELSE}
1253     Result := nil;
1254     {$ENDIF}
1255     end;
1256    
1257     function TFBLibraryImpl.GetLegacyFirebirdAPI: IFirebirdAPI;
1258     begin
1259     {$IFDEF USELEGACYFIREBIRDAPI}
1260     Result := TFB25ClientAPI.Create(self);
1261     {$ELSE}
1262     Result := nil;
1263     {$ENDIF}
1264     end;
1265    
1266 tony 45 function FirebirdAPI: IFirebirdAPI;
1267     begin
1268 tony 263 if FDefaultFBLibrary = nil then
1269 tony 45 CheckIBLoaded;
1270 tony 263 Result := FDefaultFBLibrary.GetFirebirdAPI;
1271 tony 45 end;
1272    
1273     function TryIBLoad: Boolean;
1274 tony 263 var fblib: IFirebirdLibrary;
1275 tony 45 begin
1276 tony 263 Result := FDefaultFBLibrary <> nil;
1277 tony 45 try
1278     if not Result then
1279     begin
1280 tony 263 fblib := TFBLibraryImpl.Create;
1281     if (fblib <> nil) and (fblib.GetFirebirdAPI <> nil) then
1282     FDefaultFBLibrary := fblib;
1283     Result := FDefaultFBLibrary <> nil;
1284 tony 45 end;
1285     except
1286     SysUtils.showexception(ExceptObject,ExceptAddr);
1287     Result := false;
1288     end;
1289     end;
1290    
1291     procedure CheckIBLoaded;
1292     begin
1293     if not TryIBLoad then
1294     IBError(ibxeInterBaseMissing, [nil]);
1295     end;
1296    
1297 tony 263 function LoadFBLibrary(aLibPathName: string): IFirebirdLibrary;
1298     var fblib: IFirebirdLibrary;
1299     begin
1300     if trim(aLibPathName) = '' then
1301     begin
1302     CheckIBLoaded;
1303     Result := FDefaultFBLibrary;
1304     end
1305     else
1306     begin
1307     fblib := TFBLibraryImpl.GetFBLibrary(aLibPathName);
1308     if (fblib = nil) or (fblib.GetFirebirdAPI = nil) then
1309     IBError(ibxeInterBaseMissing, [nil]);
1310     Result := fblib;
1311     end;
1312     end;
1313    
1314 tony 45 { EIBError }
1315    
1316 tony 56 constructor EIBError.Create(ASQLCode: Long; Msg: AnsiString);
1317 tony 45 begin
1318     inherited Create(Msg);
1319     FSQLCode := ASQLCode;
1320     end;
1321    
1322     { EIBInterBaseError }
1323    
1324     constructor EIBInterBaseError.Create(Status: IStatus);
1325     begin
1326     inherited Create(Status.Getsqlcode,Status.GetMessage);
1327     FIBErrorCode := Status.GetIBErrorCode;
1328     end;
1329    
1330     constructor EIBInterBaseError.Create(ASQLCode: Long; AIBErrorCode: Long;
1331 tony 56 Msg: AnsiString);
1332 tony 45 begin
1333     inherited Create(ASQLCode,Msg);
1334     FIBErrorCode := AIBErrorCode;
1335     end;
1336    
1337    
1338     initialization
1339 tony 263 FDefaultFBLibrary := nil;
1340 tony 45
1341 tony 209 finalization
1342 tony 263 FDefaultFBLibrary := nil;
1343 tony 45
1344     end.
1345