mirror of
https://github.com/XRPLF/rippled.git
synced 2025-11-19 10:35:50 +00:00
289 lines
10 KiB
HTML
289 lines
10 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html>
|
|
<head>
|
|
<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type" />
|
|
<link rel="stylesheet" type="text/css" href="../style.css" />
|
|
<title>SOCI - ODBC Backend Reference</title>
|
|
</head>
|
|
|
|
<body>
|
|
<p class="banner">SOCI - The C++ Database Access Library</p>
|
|
|
|
<h2>ODBC Backend Reference</h2>
|
|
|
|
<div class="navigation">
|
|
<a href="#prerequisites">Prerequisites</a><br />
|
|
<div class="navigation-indented">
|
|
<a href="#versions">Supported Versions</a><br />
|
|
<a href="#tested">Tested Platforms</a><br />
|
|
<a href="#required">Required Client Libraries</a><br />
|
|
</div>
|
|
<a href="#connecting">Connecting to the Database</a><br />
|
|
|
|
<a href="#support">SOCI Feature Support</a><br />
|
|
<div class="navigation-indented">
|
|
<a href="#dynamic">Dynamic Binding</a><br />
|
|
<a href="#bindingbyname">Binding by Name</a><br />
|
|
<a href="#bulk">Bulk Operations</a><br />
|
|
<a href="#transactions">Transactions</a><br />
|
|
<a href="#blob">BLOB Data Type</a><br />
|
|
<a href="#rowid">RowID Data Type</a><br />
|
|
<a href="#nested">Nested Statements</a><br />
|
|
<a href="#procedures">Stored Procedures</a><br />
|
|
</div>
|
|
<a href="#native">Accessing the Native Database API</a><br />
|
|
<a href="#extensions">Backend-specific Extensions</a><br />
|
|
<div class="navigation-indented">
|
|
<a href="#odbc_soci_error">odbc_soci_error</a><br />
|
|
</div>
|
|
<a href="#options">Configuration options</a><br />
|
|
</div>
|
|
|
|
<h3 id="prerequisites">Prerequisites</h3>
|
|
<h4 id="versions">Supported Versions</h4>
|
|
|
|
<p>The SOCI ODBC backend is supported for use with ODBC 3.</p>
|
|
|
|
<h4 id="tested">Tested Platforms</h4>
|
|
|
|
<table border="1" cellpadding="5" cellspacing="0">
|
|
<tbody>
|
|
<tr><th>ODBC version</th><th>Operating System</th><th>Compiler</th></tr>
|
|
<tr><td>3</td><td>Linux (Ubuntu 12.04)</td><td>g++ 4.6.3</td></tr>
|
|
<tr><td>3</td><td>Linux (Ubuntu 12.04)</td><td>clang 3.2</td></tr>
|
|
<tr><td>3.8</td><td>Windows 8</td><td>Visual Studio 2012</td></tr>
|
|
<tr><td>3</td><td>Windows 7</td><td>Visual Studio 2010</td></tr>
|
|
<tr><td>3</td><td>Windows XP</td><td>Visual Studio 2005 (express)</td></tr>
|
|
<tr><td>3</td><td>Windows XP</td><td>Visual C++ 8.0 Professional</td></tr>
|
|
<tr><td>3</td><td>Windows XP</td><td>g++ 3.3.4 (Cygwin)</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h4 id="required">Required Client Libraries</h4>
|
|
|
|
<p>The SOCI ODBC backend requires the ODBC client library.</p>
|
|
|
|
<h4 id="connecting">Connecting to the Database</h4>
|
|
|
|
<p>To establish a connection to the ODBC database, create a Session object
|
|
using the <code>ODBC</code> backend factory together with a connection string:</p>
|
|
|
|
<pre class="example">
|
|
backend_factory const& backEnd = odbc;
|
|
session sql(backEnd, "filedsn=c:\\my.dsn");
|
|
</pre>
|
|
|
|
<p>or simply:</p>
|
|
|
|
<pre class="example">
|
|
session sql(odbc, "filedsn=c:\\my.dsn");
|
|
</pre>
|
|
|
|
<p>The set of parameters used in the connection string for ODBC is the same as accepted by the <code><a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/odbcsql/od_odbc_d_4x4k.asp">SQLDriverConnect</a></code> function from the ODBC library.</p>
|
|
|
|
<p>Once you have created a <code>session</code> object as shown above, you can use it to access the database, for example:</p>
|
|
<pre class="example">
|
|
int count;
|
|
sql << "select count(*) from invoices", into(count);
|
|
</pre>
|
|
|
|
<p>(See the <a href="../basics.html">SOCI basics</a> and <a href="../exchange.html">exchanging data</a> documentation for general information on using the <code>session</code> class.)</p>
|
|
|
|
<h3 id="support">SOCI Feature Support</h3>
|
|
<h4 id="dynamic">Dynamic Binding</h4>
|
|
|
|
<p>The ODBC backend supports the use of the SOCI <code>row</code> class, which facilitates retrieval of data whose type is not known at compile time.</p>
|
|
|
|
<p>When calling <code>row::get<T>()</code>, the type you should pass as T depends upon the underlying database type.<br/> For the ODBC backend, this type mapping is:</p>
|
|
|
|
<table border="1" cellpadding="5" cellspacing="0">
|
|
<tbody>
|
|
<tr>
|
|
<th>ODBC Data Type</th>
|
|
<th>SOCI Data Type</th>
|
|
<th><code>row::get<T></code> specializations</th>
|
|
</tr>
|
|
<tr>
|
|
<td>SQL_DOUBLE
|
|
, SQL_DECIMAL
|
|
, SQL_REAL
|
|
, SQL_FLOAT
|
|
, SQL_NUMERIC
|
|
</td>
|
|
<td><code>dt_double</code></td>
|
|
<td><code>double</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>SQL_TINYINT
|
|
, SQL_SMALLINT
|
|
, SQL_INTEGER
|
|
, SQL_BIGINT</td>
|
|
<td><code>dt_integer</code></td>
|
|
<td><code>int</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>SQL_CHAR, SQL_VARCHAR</td>
|
|
<td><code>dt_string</code></td>
|
|
<td><code>std::string</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>SQL_TYPE_DATE
|
|
, SQL_TYPE_TIME
|
|
, SQL_TYPE_TIMESTAMP</td>
|
|
<td><code>dt_date</code></td>
|
|
<td><code>std::tm</code><code></code></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p>Not all ODBC drivers support all datatypes</p>
|
|
|
|
<p>(See the <a href="../exchange.html#dynamic">dynamic resultset binding</a> documentation for general information on using the <code>row</code> class.)</p>
|
|
|
|
<h4 id="bindingbyname">Binding by Name</h4>
|
|
|
|
<p>In addition to <a href="../exchange.html#bind_position">binding by position</a>, the ODBC backend supports <a href="../exchange.html#bind_name">binding by name</a>, via an overload of the <code>use()</code> function:</p>
|
|
|
|
<pre class="example">
|
|
int id = 7;
|
|
sql << "select name from person where id = :id", use(id, "id")
|
|
</pre>
|
|
|
|
<p>Apart from the portable "colon-name" syntax above, which is achieved by rewriting the query string, the backend also supports the ODBC ? syntax:</p>
|
|
|
|
<pre class="example">
|
|
int i = 7;
|
|
int j = 8;
|
|
sql << "insert into t(x, y) values(?, ?)", use(i), use(j);
|
|
</pre>
|
|
|
|
<h4 id="bulk">Bulk Operations</h4>
|
|
|
|
<p>The ODBC backend has support for SOCI's <a href="../statements.html#bulk">bulk operations</a> interface. Not all ODBC drivers support bulk operations, the following is a list of some tested backends:</p>
|
|
|
|
<table border="1" cellpadding="5" cellspacing="0">
|
|
<tbody>
|
|
<tr>
|
|
<th>ODBC Driver</th>
|
|
<th>Bulk Read</th>
|
|
<th>Bulk Insert</th>
|
|
</tr>
|
|
<tr>
|
|
<td>MS SQL Server 2005</td>
|
|
<td>YES</td>
|
|
<td>YES</td>
|
|
</tr>
|
|
<tr>
|
|
<td>MS Access 2003</td>
|
|
<td>YES</td>
|
|
<td>NO</td>
|
|
</tr>
|
|
<tr>
|
|
<td>PostgresQL 8.1</td>
|
|
<td>YES</td>
|
|
<td>YES</td>
|
|
</tr>
|
|
<tr>
|
|
<td>MySQL 4.1</td>
|
|
<td>NO</td>
|
|
<td>NO</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h4 id="transactions">Transactions</h4>
|
|
|
|
<p><a href="../statements.html#transactions">Transactions</a> are also fully supported by the ODBC backend, provided that they are supported by the underlying database.</p>
|
|
|
|
<h4 id="blob">BLOB Data Type</h4>
|
|
|
|
<p>Not currently supported</p>
|
|
|
|
<h4 id="rowid">RowID Data Type</h4>
|
|
|
|
<p>Not currently supported</p>
|
|
|
|
<h4 id="nested">Nested Statements</h4>
|
|
|
|
<p>Not currently supported</p>
|
|
|
|
<h4 id="procedures">Stored Procedures</h4>
|
|
|
|
<p>Not currently supported</p>
|
|
|
|
<h3 id="native">Acessing the native database API</h3>
|
|
|
|
<p>SOCI provides access to underlying datbabase APIs via several getBackEnd() functions, as described in the <a href="../beyond.html">beyond SOCI</a> documentation.</p>
|
|
|
|
<p>The ODBC backend provides the following concrete classes for navite API access:</p>
|
|
|
|
<table border="1" cellpadding="5" cellspacing="0">
|
|
<tbody>
|
|
<tr>
|
|
<th>Accessor Function</th>
|
|
<th>Concrete Class</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code>session_backend* session::get_backend()</code></td>
|
|
<td><code>odbc_statement_backend</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>statement_backend* statement::get_backend()</code></td>
|
|
<td><code>odbc_statement_backend</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>rowid_backend* rowid::get_backend()</code></td>
|
|
<td><code>odbc_rowid_backend</code></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
|
|
<h3 id="extensions">Backend-specific extensions</h3>
|
|
<h4 id="odbc_soci_error">odbc_soci_error</h4>
|
|
|
|
<p>The ODBC backend can throw instances of class <code>odbc_soci_error</code>,
|
|
which is publicly derived from <code>soci_error</code> and has
|
|
additional public members containing the ODBC error code, the Native database
|
|
error code, and the message returned from ODBC:</p>
|
|
|
|
<pre class="example">
|
|
int main()
|
|
{
|
|
try
|
|
{
|
|
// regular code
|
|
}
|
|
catch (soci::odbc_soci_error const& e)
|
|
{
|
|
cerr << "ODBC Error Code: " << e.odbc_error_code() << endl
|
|
<< "Native Error Code: " << e.native_error_code() << endl
|
|
<< "SOCI Message: " << e.what() << std::endl
|
|
<< "ODBC Message: " << e.odbc_error_message() << endl;
|
|
}
|
|
catch (exception const &e)
|
|
{
|
|
cerr << "Some other error: " << e.what() << endl;
|
|
}
|
|
}
|
|
</pre>
|
|
|
|
<h4 id="get_connection_string">get_connection_string()</h4>
|
|
<p>The <code>odbc_session_backend</code> class provides <code>std::string get_connection_string() const</code> method
|
|
that returns fully expanded connection string as returned by the <code>SQLDriverConnect</code> function.</p>
|
|
|
|
<h3 id="options">Configuration options</h3>
|
|
|
|
<p>This backend supports <code>odbc_option_driver_complete</code> option which can be passed to it via <code>connection_parameters</code> class. The value of this option is passed to <code>SQLDriverConnect()</code> function as "driver completion" parameter and so must be one of <code>SQL_DRIVER_XXX</code> values, in the string form. The default value of this option is <code>SQL_DRIVER_PROMPT</code> meaning that the driver will query the user for the user name and/or the password if they are not stored together with the connection. If this is undesirable for some reason, you can use <code>SQL_DRIVER_NOPROMPT</code> value for this option to suppress showing the message box:</p>
|
|
|
|
<pre class="example">
|
|
connection_parameters parameters("odbc", "DSN=mydb");
|
|
parameters.set_option(odbc_option_driver_complete, "0" /* SQL_DRIVER_NOPROMPT */);
|
|
session sql(parameters);
|
|
</pre>
|
|
|
|
<p class="copyright">Copyright © 2013 Mateusz Loskot</p>
|
|
<p class="copyright">Copyright © 2004-2006 Maciej Sobczak, Stephen Hutton, David Courtney</p>
|
|
</body>
|
|
</html>
|