Changes to the Firebird API and ODS

API (Application Programming Interface)

Some needed changes have been performed in the Firebird API. They include:

User restrictions in the DPB

A. Peshkov

From v.2.0.5 and v2.1.2 onward

Several DPB parameters have been made inaccessible to ordinary users, closing some dangerous loopholes. In some cases, they are settings that would alter the database header settings and potentially cause corruptions if not performed under administrator control; in others, they initiate operations that are otherwise restricted to the SYSDBA. They are:

isc_dpb_shutdown and isc_dpb_online
isc_dpb_gbak_attach, isc_dpb_gfix_attach and isc_dpb_gstat_attach
isc_dpb_verify
isc_dpb_no_db_triggers
isc_dpb_set_db_sql_dialect
isc_dpb_sweep_interval
isc_dpb_force_write
isc_dpb_no_reserve
isc_dpb_set_db_readonly
isc_dpb_set_page_buffers (on Superserver)

The parameter isc_dpb_set_page_buffers can still be used by ordinary users on Classic and it will set the buffer size temporarily for that user and that session only. When used by the SYSDBA on either Superserver or Classic, it will change the buffer count in the database header, i.e., make a permanent change to the default buffer size.

Important note for developers and users of data access drivers and tools:

This change will affect any of the listed DPB parameters that have been explicitly set, either by including them in the DPB implementation by default property values or by enabling them in tools and applications that access databases as ordinary users. For example, a Delphi application that included 'RESERVE PAGE SPACE=TRUE' and 'FORCED WRITES=TRUE' in its database Params property, which caused no problems when the application connected to Firebird 1.x, 2.0.x or 2.1.0/2.1.1, now rejects a connection by a non-SYSDBA user with ISC ERROR CODE 335544788, Unable to perform operation. You must be either SYSDBA or owner of the database.

Cleanup of `ibase.h`

D. Yemanov, A. Peshkov

The API header file, ibase.h has been subjected to a cleanup. With the result that public headers no longer contain private declarations.

Lock timeout for `WAIT` transactions

A. Karyakin, D. Yemanov

The new feature extends the WAIT mode by making provision to set a finite time interval to wait for the concurrent transactions. If the timeout has passed, an error (isc_lock_timeout) is reported.

Timeout intervals can now be specified per transaction, using the new TPB constant isc_tpb_lock_timeout in the API.

Note: The DSQL equivalent is implemented via the LOCK TIMEOUT <value> clause of the SET TRANSACTION statement.

`isc_dsql_sql_info()` now includes relation aliases

D. Yemanov

The function call isc_dsql_sql_info() has been extended to enable relation aliases to be retrieved, if required.

Enhancement to `isc_blob_lookup_desc()`

A. dos Santos Fernandes

isc_blob_lookup_desc() now also describes blobs that are outputs of stored procedures.

API identifies client version

N. Samofatov

The macro definition FB_API_VER is added to ibase.h to indicate the current API version. The number corresponds to the appropriate Firebird version.

The current value of FB_API_VER is 20 (two-digit equivalent of 2.0). This macro can be used by client applications to check the version of ibase.h its being compiled with.

Additions to the `isc_database_info()` structure

V. Horsun

The following items have been added to the isc_database_info() function call structure:

`isc_info_active_tran_count`

Returns the number of currently active transactions.

`isc_info_creation_date`

Returns the date and time when the database was [re]created.

To decode the returned value, call isc_vax_integer twice to extract (first) the date and (second) the time portions of the ISC_TIMESTAMP. Then, use isc_decode_timestamp() as usual.

Additions to the `isc_transaction_info()` structure

V. Horsun

The following items have been added to the isc_transaction_info() function call structure:

`isc_info_tra_oldest_interesting`

Returns the number of the oldest [interesting] transaction when the current transaction started. For snapshot transactions, this is also the number of the oldest transaction in the private copy of the transaction inventory page (TIP).

`isc_info_tra_oldest_active`

For a read-committed transaction, returns the number of the current transaction.
For all other transactions, returns the number of the oldest active transaction when the current transaction started.

`isc_info_tra_oldest_snapshot`

Returns the number of the lowest tra_oldest_active of all transactions that were active when the current transaction started.

Note: This value is used as the threshold ("high-water mark") for garbage collection.

`isc_info_tra_isolation`

Returns the isolation level of the current transaction. The format of the returned clumplets is:

 isc_info_tra_isolation,
   1, isc_info_tra_consistency | isc_info_tra_concurrency |
   2, isc_info_tra_read_committed,
   isc_info_tra_no_rec_version | isc_info_tra_rec_version

That is, for Read Committed transactions, two items are returned (isolation level and record versioning policy) while, for other transactions, one item is returned (isolation level).

`isc_info_tra_access`

Returns the access mode (read-only or read-write) of the current transaction. The format of the returned clumplets is:

 isc_info_tra_access, 1, isc_info_tra_readonly | isc_info_tra_readwrite

`isc_info_tra_lock_timeout`

Returns the lock timeout set for the current transaction.

Improved Services API

The following improvements have been added to the Services API:

Task execution optimized

D. Yemanov

Services are now executed as threads rather than processes on some threadable CS builds (currently 32-bit Windows and Solaris).

New function for delivering error text

C. Valderrama

The new function fb_interpret() replaces the former isc_interpret() for extracting the text for a Firebird error message from the error status vector to a client buffer.

Important: isc_interpret() is vulnerable to overruns and is deprecated as unsafe. The new function should be used instead.

Accommodation of new shutdown `<state>` parameters

D. Yemanov

API access to database shutdown is through flags appended to the isc_dpb_shutdown parameter in the DBP argument passed to isc_attach_database(). The symbols for the <state> flags are:

 #define isc_dpb_shut_cache 		0x1
 #define isc_dpb_shut_attachment 	0x2
 #define isc_dpb_shut_transaction 	0x4
 #define isc_dpb_shut_force 		0x8
 #define isc_dpb_shut_mode_mask 	0x70

 #define isc_dpb_shut_default 		0x0
 #define isc_dpb_shut_normal 		0x10
 #define isc_dpb_shut_multi 		0x20
 #define isc_dpb_shut_single 		0x30
 #define isc_dpb_shut_full 		0x40

Example of Use in C/C++

 char dpb_buffer[256], *dpb, *p;
 ISC_STATUS status_vector[ISC_STATUS_LENGTH];
 isc_db_handle handle = NULL;

 dpb = dpb_buffer;

 *dpb++ = isc_dpb_version1;

 const char* user_name = "SYSDBA";
 const int user_name_length = strlen(user_name);
 *dpb++ = isc_dpb_user_name;
 *dpb++ = user_name_length;
 memcpy(dpb, user_name, user_name_length);
 dpb += user_name_length;

 const char* user_password = "masterkey";
 const int user_password_length = strlen(user_password);
 *dpb++ = isc_dpb_password;
 *dpb++ = user_password_length;
 memcpy(dpb, user_password, user_password_length);
 dpb += user_password_length;
 // Force an immediate full database shutdown
 *dpb++ = isc_dpb_shutdown;
 *dpb++ = isc_dpb_shut_force | isc_dpb_shut_full;

 const int dpb_length = dpb - dpb_buffer;

 isc_attach_database(status_vector,
                     0, "employee.db",
                     &handle,
                     dpb_length, dpb_buffer);

 if (status_vector[0] == 1 && status_vector[1])
 {
 isc_print_status(status_vector);
 }
 else
 {
 isc_detach_database(status_vector, &handle);
 }

ODS (On-Disk Structure) Changes

On-disk structure (ODS) changes include the following:

New ODS Number

Firebird 2.0 creates databases with an ODS (On-Disk Structure) version of 11.

Size limit for exception messages increased

V. Horsun

Maximum size of exception messages raised from 78 to 1021 bytes.

New description field for generators

C. Valderrama

Added RDB$DESCRIPTION to RDB$GENERATORS, so now you can include description text when creating generators.

New description field for SQL roles

C. Valderrama

Added RDB$DESCRIPTION and RDB$SYSTEM_FLAG to RDB$ROLES to allow description text and to flag user-defined roles, respectively.

"ODS Type" recognition

N. Samofatov

Introduced a concept of ODS type to distinguish between InterBase and Firebird databases.

Smarter DSQL error reporting

C. Valderrama

The DSQL parser will now try to report the line and column number of an incomplete statement.

New column in `RDB$Index_Segments`

D. Yemanov, A. Brinkman

A new column RDB$STATISTICS has been added to the system table RDB$INDEX_SEGMENTS to store the per-segment selectivity values for multi-key indexes.

Note: The column of the same name in RDB$INDICES is kept for compatibility and still represents the total index selectivity, that is used for a full index match.