| Firebird Documentation Index → Firebird 2.0.6 Release Notes → Changes to the Firebird API and ODS |
|
|
|
Table of Contents
Some other needed changes have been performed in the Firebird API. They include.-
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.
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.”
The API header file, ibase.h has been subjected to a cleanup. with the result that public headers no longer contain private declarations.
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.
The DSQL equivalent is implemented via the LOCK TIMEOUT <value> clause of the SET TRANSACTION statement.
The function call isc_dsql_sql_info() has been extended to enable relation aliases to be retrieved, if required.
isc_blob_lookup_desc() now also describes blobs that are outputs of stored procedures
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.
The following items have been added to the isc_database_info() function call structure:
The following items have been added to the isc_transaction_info() function call structure:
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).
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.
Returns the number of the lowest tra_oldest_active of all
transactions that were active when the current transaction started.
This value is used as the threshold ("high-water mark") for garbage collection.
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).
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
The following improvements have been added to the Services API:
Services are now executed as threads rather than processes on some threadable CS builds (currently 32- bit Windows and Solaris).
The new function fb_interpret() replaces the former
isc_interprete() for extracting the text for a Firebird error message from the error status vector to a
client buffer.
isc_interprete() is vulnerable to overruns and is deprecated as unsafe. The new function should be used instead.
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); }
On-disk structure (ODS) changes include the following:
Maximum size of exception messages raised from 78 to 1021 bytes.
Added RDB$DESCRIPTION to RDB$GENERATORS, so now you can include description text when creating generators.
Added RDB$DESCRIPTION and RDB$SYSTEM_FLAG to RDB$ROLES to allow description text and to flag user-defined roles, respectively.
Introduced a concept of ODS type to distinguish between InterBase and Firebird databases.
The DSQL parser will now try to report the line and column number of an incomplete statement.
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.
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.
|
| Firebird Documentation Index → Firebird 2.0.6 Release Notes → Changes to the Firebird API and ODS |