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