ViewVC Help
View File | Revision Log | Show Annotations | Download File | View Changeset | Root Listing
root/public/ibx/branches/udr/client/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

# Content
1 (*
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 {$IFDEF MSWINDOWS}
64 {$DEFINE WINDOWS}
65 {$ENDIF}
66
67 {$IFDEF FPC}
68 {$mode delphi}
69 {$codepage UTF8}
70 {$interfaces COM}
71 {$IF defined(FPC) and (FPC_FULLVERSION < 30000) }
72 {$ERROR FPC Version 3.0.0 or later is required}
73 {$IFEND}
74 {$ENDIF}
75
76 {$IFNDEF LEGACYFIREBIRDAPIONLY}
77 {$DEFINE USEFIREBIRD3API}
78 {$ENDIF}
79 {$IFNDEF FIREBIRD3APIONLY}
80 {$DEFINE USELEGACYFIREBIRDAPI}
81 {$ENDIF}
82
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 6. FPC and Delphi Support.
114
115 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 Classes,
130 {$IFDEF WINDOWS}Windows, {$ENDIF}
131 {$IFDEF FPC} Dynlibs, {$ENDIF}
132 SysUtils, DB, FBMessages, IBExternals;
133
134 const
135 {Interface version information}
136 FBIntf_Major = 1;
137 FBIntf_Minor = 1;
138 FBIntf_Release = 5;
139 FBIntf_Version = '1.1.5';
140
141 {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 {$I 'include/consts_pub.inc'}
145 {$I 'include/inf_pub.inc'}
146 {$I 'include/configkeys.inc'}
147
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 {$IFNDEF FPC}
183 {Delphi missing definitions}
184 type
185 TLibHandle = THandle;
186
187 const
188 NilHandle = 0;
189 DirectorySeparator = '\';
190
191 {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 TIBSQLStatementTypes =
208 (SQLUnknown, SQLSelect, SQLInsert,
209 SQLUpdate, SQLDelete, SQLDDL,
210 SQLGetSegment, SQLPutSegment,
211 SQLExecProcedure, SQLStartTransaction,
212 SQLCommit, SQLRollback,
213 SQLSelectForUpdate, SQLSetGenerator,
214 SQLSavePoint);
215
216 TFBStatusCode = cardinal;
217 TByteArray = array of byte;
218
219 IFirebirdAPI = interface;
220 IAttachment = interface;
221 ITransaction = interface;
222 IStatement = interface;
223
224 {The IParameterBlock interface provides the template for all parameter
225 block interfaces}
226
227 IParameterBlock<_IItem> = interface
228 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 ['{53b23f7b-abda-46a5-9aa5-07bd5e723266}']
242 function getParamType: byte;
243 function getAsInteger: integer;
244 function getAsString: AnsiString;
245 function getAsByte: byte;
246 procedure setAsString(aValue: AnsiString);
247 procedure setAsByte(aValue: byte);
248 procedure SetAsInteger(aValue: integer);
249 property AsString: AnsiString read getAsString write setAsString;
250 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 TIBDataBaseErrorMessage = (ShowSQLCode,
263 ShowIBMessage,
264 ShowSQLMessage);
265
266 TIBDataBaseErrorMessages = set of TIBDataBaseErrorMessage;
267
268 IStatus = interface
269 ['{34167722-af38-4831-b08a-93162d58ede3}']
270 function GetIBErrorCode: Long;
271 function Getsqlcode: Long;
272 function GetMessage: AnsiString;
273 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 ['{7dd0aea4-59af-4c2a-b958-565d5025c489}']
290 function GetSQLType: cardinal;
291 function GetSQLTypeName: AnsiString;
292 function GetScale: integer;
293 function GetSize: cardinal;
294 function GetCharSetID: cardinal;
295 function GetTableName: AnsiString;
296 function GetColumnName: AnsiString;
297 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 ['{631c6bb1-fb49-44fb-a64a-c49859632b88}']
322 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 function GetAsString(index: array of integer): AnsiString;
338 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 procedure SetAsString(index: array of integer; Value: AnsiString);
351 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 ['{575f3c61-bb33-46a5-8975-bb7d1b6e37cc}']
365 function GetSubType: integer;
366 function GetCharSetID: cardinal;
367 function GetCodePage: TSystemCodePage;
368 function GetSegmentSize: cardinal;
369 function GetRelationName: AnsiString;
370 function GetColumnName: AnsiString;
371 end;
372
373 {The Blob Parameter block is used to select a Blob Filter}
374
375 IBPBItem = interface (IParameterBlockItem)
376 ['{660822a5-3114-4c16-b6cb-c1a7b2aba70d}']
377 end;
378
379 IBPB = interface (IParameterBlock<IBPBItem>)
380 ['{e0cb9eb5-17f7-4416-b7d1-3cddd1dfca76}']
381 end;
382
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 ['{3090a145-7780-442b-b15b-efd4568b8611}']
396 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 function LoadFromFile(Filename: AnsiString): IBlob;
407 function LoadFromStream(S: TStream) : IBlob;
408 function SaveToFile(Filename: AnsiString): IBlob;
409 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 TIBDateTimeFormats = (dfTimestamp, {SQL TIMESTAMP}
423 dfDateTime, {SQL DATETIME}
424 dfTime); {SQL TIME}
425
426 { IColumnMetaData }
427
428 IColumnMetaData = interface
429 ['{c222e6c3-53c1-469f-9e05-0a5c3ef232d8}']
430 function GetIndex: integer;
431 function GetSQLType: cardinal;
432 function GetSQLTypeName: AnsiString;
433 function getSubtype: integer;
434 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 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 function GetDateTimeStrLength(DateTimeFormat: TIBDateTimeFormats): integer;
447 function GetStatement: IStatement;
448 function GetTransaction: ITransaction;
449 property Name: AnsiString read GetName;
450 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 ['{4dafdbb6-0d36-4f1f-9c95-8b132804b965}']
466 function getCount: integer;
467 function getColumnMetaData(index: integer): IColumnMetaData;
468 function GetUniqueRelationName: AnsiString; {Non empty if all columns come from the same table}
469 function ByName(Idx: AnsiString): IColumnMetaData;
470 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 ['{3f493e31-7e3f-4606-a07c-b210b9e3619d}']
490 function GetStrDataLength: short;
491 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 function GetAsString: AnsiString;
502 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 property AsString: AnsiString read GetAsString;
521 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 ['{e836b2bb-93d1-4bbf-a8eb-7ce535de3bb5}']
536 function getCount: integer;
537 function GetStatement: IStatement;
538 function GetTransaction: ITransaction;
539 function ByName(Idx: AnsiString): ISQLData;
540 function getSQLData(index: integer): ISQLData;
541 procedure GetData(index: integer; var IsNull:boolean; var len: short; var data: PByte);
542 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 ['{0ae4979b-7857-4e8c-8918-ec6f155b51a0}']
554 function FetchNext: boolean;
555 function GetCursorName: AnsiString;
556 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 ['{b22b4578-6d41-4807-a9a9-d2ec8d1d5a14}']
577 function GetIndex: integer;
578 function GetSQLType: cardinal;
579 function GetSQLTypeName: AnsiString;
580 function getSubtype: integer;
581 function getName: AnsiString;
582 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 function GetAsString: AnsiString;
598 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 procedure SetAsString(aValue: AnsiString);
616 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 property AsString: AnsiString read GetAsString write SetAsString;
635 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 property Name: AnsiString read GetName;
644 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 ['{c6d95ac7-b2b7-461b-b890-afef0acbb077}']
654 function getCount: integer;
655 function getSQLParam(index: integer): ISQLParam;
656 function ByName(Idx: AnsiString): ISQLParam ;
657 function GetModified: Boolean;
658 function GetHasCaseSensitiveParams: Boolean;
659 property Modified: Boolean read GetModified;
660 property Params[index: integer]: ISQLParam read getSQLParam; default;
661 property Count: integer read getCount;
662 end;
663
664
665 TPerfStats = (psCurrentMemory, psMaxMemory,
666 psRealTime, psUserTime, psBuffers,
667 psReads, psWrites, psFetches,psDeltaMemory);
668
669 TPerfCounters = array[TPerfStats] of Int64;
670
671 {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 ['{a260576d-a07d-4a66-b02d-1b72543fd7cf}']
677 function GetMetaData: IMetaData; {Output Metadata}
678 function GetSQLParams: ISQLParams;{Statement Parameters}
679 function GetPlan: AnsiString;
680 function GetRowsAffected(var SelectCount, InsertCount, UpdateCount, DeleteCount: integer): boolean;
681 function GetSQLStatementType: TIBSQLStatementTypes;
682 function GetSQLText: AnsiString;
683 function GetProcessedSQLText: AnsiString;
684 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 procedure EnableStatistics(aValue: boolean);
693 function GetPerfStatistics(var stats: TPerfCounters): boolean;
694 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 ITPBItem = interface(IParameterBlockItem)
711 ['{544c1f2b-7c12-4a87-a4a5-face7ea72671}']
712 end;
713
714 ITPB = interface(IParameterBlock<ITPBItem>)
715 ['{7369b0ff-defe-437b-81fe-19b211d42d25}']
716 end;
717
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 ['{30928d0e-a9d7-4c61-b7cf-14f4f38abe2a}']
731 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 EventName: AnsiString;
759 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 ['{6a0be233-ed08-4524-889c-2e45d0c20e5f}']
770 procedure GetEvents(EventNames: TStrings);
771 procedure SetEvents(EventNames: TStrings); overload;
772 procedure SetEvents(EventName: AnsiString); overload;
773 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 ['{eeb97b51-ec0f-473f-9f75-c1721f055fcb}']
804 function getItemType: byte;
805 function getSize: integer;
806 procedure getRawBytes(var Buffer);
807 function getAsString: AnsiString;
808 function getAsInteger: integer;
809 procedure DecodeIDCluster(var ConnectionType: integer; var DBFileName, DBSiteName: AnsiString);
810 function getAsBytes: TByteArray;
811 function getAsDateTime: TDateTime;
812 procedure DecodeVersionString(var Version: byte; var VersionString: AnsiString);
813 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 property AsString: AnsiString read GetAsString;
822 property Count: integer read GetCount;
823 property Items[index: integer]: IDBInfoItem read getItem; default;
824 end;
825
826 { IDBInformation }
827
828 IDBInformation = interface
829 ['{7ac6777f-f0a9-498a-9f5c-4a57a554df81}']
830 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 {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 {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 IDPBItem = interface(IParameterBlockItem)
864 ['{123d4ad0-087a-4cd1-a344-1b3d03b30673}']
865 end;
866
867 IDPB = interface(IParameterBlock<IDPBItem>)
868 ['{e676067b-1cf4-4eba-9256-9724f57e0d16}']
869 end;
870
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 ['{466e9b67-9def-4807-b3e7-e08a35e7185c}']
900 function getFirebirdAPI: IFirebirdAPI;
901 function getDPB: IDPB;
902 function AllocateBPB: IBPB;
903 function AllocateDIRB: IDIRB;
904 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 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 params: array of const): IResultSet; overload;
921 function OpenCursor(transaction: ITransaction; sql: AnsiString): IResultSet; overload;
922 function OpenCursor(transaction: ITransaction; sql: AnsiString;
923 params: array of const): IResultSet; overload;
924 function OpenCursorAtStart(transaction: ITransaction; sql: AnsiString; aSQLDialect: integer): IResultSet; overload;
925 function OpenCursorAtStart(transaction: ITransaction; sql: AnsiString; aSQLDialect: integer;
926 params: array of const): IResultSet; overload;
927 function OpenCursorAtStart(transaction: ITransaction; sql: AnsiString): IResultSet; overload;
928 function OpenCursorAtStart(transaction: ITransaction; sql: AnsiString;
929 params: array of const): IResultSet; overload;
930 function OpenCursorAtStart(sql: AnsiString): IResultSet; overload;
931 function OpenCursorAtStart(sql: AnsiString;
932 params: array of const): IResultSet; overload;
933 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 aSQLDialect: integer; GenerateParamNames: boolean=false;
937 CaseSensitiveParams: boolean = false): IStatement; overload;
938 function PrepareWithNamedParameters(transaction: ITransaction; sql: AnsiString;
939 GenerateParamNames: boolean=false;
940 CaseSensitiveParams: boolean = false): IStatement; overload;
941
942 {Events}
943 function GetEventHandler(Events: TStrings): IEvents; overload;
944 function GetEventHandler(Event: AnsiString): IEvents; overload;
945
946 {Blob - may use to open existing Blobs. However, ISQLData.AsBlob is preferred}
947
948 function CreateBlob(transaction: ITransaction; RelationName, ColumnName: AnsiString; BPB: IBPB=nil): IBlob; overload;
949 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 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
954 {Array - may use to open existing arrays. However, ISQLData.AsArray is preferred}
955
956 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 function CreateArray(transaction: ITransaction; RelationName, ColumnName: AnsiString): IArray; overload;
959 function CreateArray(transaction: ITransaction; ArrayMetaData: IArrayMetaData): IArray; overload;
960 function CreateArrayMetaData(SQLType: cardinal; tableName: AnsiString; columnName: AnsiString;
961 Scale: integer; size: cardinal; charSetID: cardinal; dimensions: cardinal;
962 bounds: TArrayBounds): IArrayMetaData;
963
964 {Database Information}
965 function GetSQLDialect: integer;
966 function GetBlobMetaData(Transaction: ITransaction; tableName, columnName: AnsiString): IBlobMetaData;
967 function GetArrayMetaData(Transaction: ITransaction; tableName, columnName: AnsiString): IArrayMetaData;
968 function GetDBInformation(Requests: array of byte): IDBInformation; overload;
969 function GetDBInformation(Request: byte): IDBInformation; overload;
970 function GetDBInformation(Requests: IDIRB): IDBInformation; overload;
971 function GetConnectString: AnsiString;
972 function GetRemoteProtocol: AnsiString;
973 function GetAuthenticationMethod: AnsiString;
974 function GetSecurityDatabase: AnsiString;
975 function GetODSMajorVersion: integer;
976 function GetODSMinorVersion: integer;
977 procedure getFBVersion(version: TStrings);
978 function HasActivity: boolean;
979
980 {Character Sets}
981 function HasDefaultCharSet: boolean;
982 function GetDefaultCharSetID: integer;
983 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 end;
991
992 TProtocolAll = (TCP, SPX, NamedPipe, Local, inet, inet4, inet6, wnet, xnet, unknownProtocol);
993 TProtocol = TCP..xnet;
994
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 ISPBItem = interface(IParameterBlockItem)
1008 ['{5d08ae2b-4519-41bd-8b40-97cd451c3f6a}']
1009 end;
1010
1011 ISPB = interface(IParameterBlock<ISPBItem>)
1012 ['{2c5836fd-41ed-4426-9b7d-5af580ec2659}']
1013 end;
1014
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 ['{b07841a6-33b3-47f0-b5a2-028cbc86dc97}']
1023 function CopyFrom(source: TStream; count: integer): integer;
1024 end;
1025
1026 ISQPB = interface(IParameterBlock<ISQPBItem>)
1027 ['{8553e66b-ee62-498b-8431-dff030211447}']
1028 end;
1029
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 ISRBItem = interface(IParameterBlockItem)
1043 ['{47ec790e-f265-4b30-9dcd-261e51677245}']
1044 end;
1045
1046 ISRB = interface(IParameterBlock<ISRBItem>)
1047 ['{9f2e204f-3c33-4e44-90f9-9135e95dafb9}']
1048 end;
1049
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 ['{8a4c381e-9923-4cc9-a96b-553729248640}']
1067 function getItemType: byte;
1068 function getSize: integer;
1069 procedure getRawBytes(var Buffer);
1070 function getAsString: AnsiString;
1071 function getAsInteger: integer;
1072 function getAsByte: byte;
1073 function CopyTo(stream: TStream; count: integer): integer;
1074 property AsString: AnsiString read getAsString;
1075 property AsInteger: integer read getAsInteger;
1076 property AsByte: byte read getAsByte;
1077 end;
1078
1079 IServiceQueryResultItem = interface(IServiceQueryResultSubItem)
1080 ['{b2806886-206c-4024-8df9-5fe0a7630a5e}']
1081 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 ['{8fbbef7d-fe03-4409-828a-a787d34ef531}']
1090 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 IFirebirdLibrary = interface;
1099
1100 {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 ['{905b587d-1e1f-4e40-a3f8-a3519f852e48}']
1111 function getFirebirdAPI: IFirebirdAPI;
1112 function getSPB: ISPB;
1113 function getServerName: AnsiString;
1114 function getProtocol: TProtocol;
1115 function getPortNo: AnsiString;
1116 procedure Attach;
1117 procedure Detach(Force: boolean=false);
1118 function IsAttached: boolean;
1119 function AllocateSRB: ISRB;
1120 function AllocateSQPB: ISQPB;
1121 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 end;
1125
1126 {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 {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 ['{edeee691-c8d3-4dcf-a780-cd7e432821d5}']
1147 {Database connections}
1148 function AllocateDPB: IDPB;
1149 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
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 function GetServiceManager(ServerName: AnsiString; Protocol: TProtocol; SPB: ISPB): IServiceManager; overload;
1164 function GetServiceManager(ServerName: AnsiString; Port: AnsiString; Protocol: TProtocol; SPB: ISPB): IServiceManager; overload;
1165
1166 {Information}
1167 function GetStatus: IStatus;
1168 function HasRollbackRetaining: boolean;
1169 function IsEmbeddedServer: boolean;
1170 function GetImplementationVersion: AnsiString;
1171
1172 {Firebird 3 API}
1173 function HasMasterIntf: boolean;
1174 function GetIMaster: TObject;
1175 function GetFBLibrary: IFirebirdLibrary;
1176 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 constructor Create(ASQLCode: Long; Msg: AnsiString);
1193 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 constructor Create(ASQLCode: Long; AIBErrorCode: Long; Msg: AnsiString); overload;
1204 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 {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 implementation
1231
1232 uses FBClientAPI
1233 {$IFDEF USELEGACYFIREBIRDAPI}, FB25ClientAPI {$ENDIF}
1234 {$IFDEF USEFIREBIRD3API}, FB30ClientAPI {$ENDIF};
1235
1236 var FDefaultFBLibrary: IFirebirdLibrary;
1237
1238 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 function FirebirdAPI: IFirebirdAPI;
1267 begin
1268 if FDefaultFBLibrary = nil then
1269 CheckIBLoaded;
1270 Result := FDefaultFBLibrary.GetFirebirdAPI;
1271 end;
1272
1273 function TryIBLoad: Boolean;
1274 var fblib: IFirebirdLibrary;
1275 begin
1276 Result := FDefaultFBLibrary <> nil;
1277 try
1278 if not Result then
1279 begin
1280 fblib := TFBLibraryImpl.Create;
1281 if (fblib <> nil) and (fblib.GetFirebirdAPI <> nil) then
1282 FDefaultFBLibrary := fblib;
1283 Result := FDefaultFBLibrary <> nil;
1284 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 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 { EIBError }
1315
1316 constructor EIBError.Create(ASQLCode: Long; Msg: AnsiString);
1317 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 Msg: AnsiString);
1332 begin
1333 inherited Create(ASQLCode,Msg);
1334 FIBErrorCode := AIBErrorCode;
1335 end;
1336
1337
1338 initialization
1339 FDefaultFBLibrary := nil;
1340
1341 finalization
1342 FDefaultFBLibrary := nil;
1343
1344 end.
1345