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