Welcome to EXTRAS-SOCI!

ODBC Backend Reference

Prerequisites

Supported Versions

The SOCI ODBC backend is supported for use with ODBC 3.

Tested Platforms

ODBC version	Operating System	Compiler
3	Windows XP	Visual Studio 2005 (express)
3	Windows XP	Visual C++ 8.0 Professional
3	Windows XP	(cygwin) g++ 3.3.4

Required Client Libraries

The SOCI ODBC backend requires the ODBC client library.

Connecting to the Database

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

BackEndFactory const &backEnd = odbc;
Session sql(backEnd, "filedsn=c:\\my.dsn");

or simply:

Session sql(odbc, "filedsn=c:\\my.dsn");

The set of parameters used in the connection string for ODBC is the same as accepted by the SQLDriverConnect function from the ODBC library.

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 invoices", into(count);

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

SOCI Feature Support

Dynamic Binding

The ODBC 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 ODBC backend, this type mapping is:

ODBC Data Type	SOCI Data Type	`Row::get<T>` specializations
SQL_DOUBLE , SQL_DECIMAL , SQL_REAL , SQL_FLOAT , SQL_NUMERIC	`eDouble`	`double`
SQL_TINYINT , SQL_SMALLINT , SQL_INTEGER , SQL_BIGINT	`eInteger`	`int`
SQL_CHAR, SQL_VARCHAR	`eString`	`std::string`
SQL_TYPE_DATE , SQL_TYPE_TIME , SQL_TYPE_TIMESTAMP	`eDate`	`std::tm`

Not all ODBC drivers support all datatypes

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

Binding by Name

In addition to binding by position, the ODBC 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")

Apart from the portable "colon-name" syntax above, which is achieved by rewriting the query string, the backend also supports the ODBC ? syntax:

int i = 7;
int j = 8;
sql << "insert into t(x, y) values(?, ?)", use(i), use(j);

Bulk Operations

The ODBC backend has support for SOCI's bulk operations interface. Not all ODBC drivers support bulk operations, the following is a list of some tested backends:

ODBC Driver	Bulk Read	Bulk Insert
MS SQL Server 2005	YES	YES
MS Access 2003	YES	NO
PostgresQL 8.1	YES	YES
MySQL 4.1	NO	NO

Transactions

Transactions are also fully supported by the ODBC backend, provided that they are supported by the underlying database.

BLOB Data Type

Not currently supported

RowID Data Type

Not currently supported

Nested Statements

Not currently supported

Stored Procedures

Not currently supported

Acessing the native database API

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

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

Accessor Function	Concrete Class
`SessionBackEnd* Session::getBackEnd()`	`ODBCSessionBackEnd`
`StatementBackEnd* Statement::getBackEnd()`	`ODBCStatementBackEnd`
`RowIDBackEnd* RowID::getBackEnd()`	`ODBCRowIDBackEnd`

Backend-specific extensions

ODBCSOCIError

The ODBC backend can throw instances of class ODBCSOCIError, which is publicly derived from SOCIError and has additional public members containing the ODBC error code, the Native database error code, and the message returned from ODBC:

int main()
{
    try
    {
        // regular code
    }
    catch (SOCI::ODBCSOCIError const & e)
    {
        cerr << "ODBC Error Code: " << e.odbcErrorCode() << endl
             << "Native Error Code: " << e.nativeErrorCode() << endl
             << "SOCI Message: " << e.what() << std::endl
             << "ODBC Message: " << e.odbcErrorMessage() << endl;
    }
   catch (exception const &e)
    {
        cerr << "Some other error: " << e.what() << endl;
    }
}

Configuration options

None