SOCI - The C++ Database Access Library

## Firebird Backend Reference

### Prerequisites

#### Supported Versions

The SOCI Firebird backend is currently supported for use with Firebird 1.5.
Other versions of Firebird may work as well, but they have not been tested by the SOCI team.

#### Tested Platforms

Firebird version | Operating System | Compiler
--- | --- | ---
1.5.2.4731 | SunOS 5.10 | g++ 3.4.3
1.5.2.4731 | Windows XP | Visual C++ 8.0
1.5.3.4870 | Windows XP | Visual C++ 8.0 Professional

#### Required Client Libraries

The Firebird backend requires Firebird's `libfbclient` client library.

#### Connecting to the Database

To establish a connection to a Firebird database, create a Session object using the firebird backend factory together with a connection string:

    BackEndFactory const &backEnd = firebird;
    Session sql(backEnd,
            "service=/usr/local/firbird/db/test.fdb user=SYSDBA password=masterkey");

or simply:

    Session sql(firebird,
            "service=/usr/local/firbird/db/test.fdb user=SYSDBA password=masterkey");

The set of parameters used in the connection string for Firebird is:

- service
- user
- password
- role
- charset

The following parameters have to be provided as part of the connection string : service, user, password. Role and charset parameters are optional.

Once you have created a `Session` object as shown above, you can use it to access the database, for example:

    int count;
    sql << "select count(*) from user_tables", into(count);

(See the SOCI basics and exchanging data documentation for general information on using the `Session` class.)

### SOCI Feature Support

#### Dynamic Binding

The Firebird backend supports the use of the SOCI `Row` class, which facilitates retrieval of data whose type is not known at compile time.

When calling `Row::get<T>()`, the type you should pass as T depends upon the underlying database type. For the Firebird backend, this type mapping is:

Firebird Data Type | SOCI Data Type | `Row::get<T>` specializations
--- | --- | ---
numeric, decimal (where scale > 0) | `eDouble` | `double`
numeric, decimal [1] (where scale = 0) | `eInteger, eDouble` | `int, double`
double precision, float | `eDouble` | `double`
smallint, integer | `eInteger` | `int`
char, varchar | `eString` | `std::string`
date, time, timestamp | `eDate` | `std::tm```

[1] There is also 64bit integer type for larger values which is currently not supported.

(See the dynamic resultset binding documentation for general information on using the `Row` class.)

#### Binding by Name

In addition to binding by position, the Firebird backend supports binding by name, via an overload of the `use()` function:

    int id = 7;
    sql << "select name from person where id = :id", use(id, "id")

It should be noted that parameter binding by name is supported only by means of emulation, since the underlying API used by the backend doesn't provide this feature.

#### Bulk Operations

The Firebird backend has full support for SOCI's bulk operations interface. This feature is also supported by emulation.

#### Transactions

Transactions are also fully supported by the Firebird backend. In fact, there is always a transaction which is automatically commited in `Session's` destructor.
See the Configuration options section for more details.

#### BLOB Data Type

The Firebird backend supports working with data stored in columns of type Blob, via SOCI's `BLOB` class.

It should by noted, that entire Blob data is fetched from database to allow random read and write access. This is because Firebird itself allows only writing to a new Blob or reading from existing one - modifications of existing Blob means creating a new one. Firebird backend hides those details from user.

#### RowID Data Type

This feature is not supported by Firebird backend.

#### Nested Statements

This feature is not supported by Firebird backend.

#### Stored Procedures

Firebird stored procedures can be executed by using SOCI's Procedure class.

### Acessing the native database API

SOCI provides access to underlying datbabase APIs via several getBackEnd() functions, as described in the beyond SOCI documentation.

The Firebird backend provides the following concrete classes for navite API access:

Accessor Function | Concrete Class
--- | ---
`SessionBackEnd* Session::getBackEnd()` | `FirebirdSessionBackEnd`
`StatementBackEnd* Statement::getBackEnd()` | `FirebirdStatementBackEnd`
`BLOBBackEnd* BLOB::getBackEnd()` | `FirebirdBLOBBackEnd`
`RowIDBackEnd* RowID::getBackEnd()` | `FirebirdRowIDBackEnd`

### Backend-specific extensions

#### FirebirdSOCIError

The Firebird backend can throw instances of class `FirebirdSOCIError`, which is publicly derived from `SOCIError` and has an additional public `status_` member containing the Firebird status vector.

### Configuration options

The Firebird backend recognize the following configuration macros :

- `SOCI_FIREBIRD_NORESTARTTRANSACTION` - Transactions will not be restarted automatically after commit() or rollback(). The default is to restart transactions.

Copyright © 2004-2006 Maciej Sobczak, Stephen Hutton, Rafal Bobrowski