mirror of
https://github.com/Xahau/xahaud.git
synced 2025-12-06 17:27:52 +00:00
261 lines
9.1 KiB
HTML
261 lines
9.1 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en'>
|
|
<head>
|
|
<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type" />
|
|
<link rel="stylesheet" type="text/css" href="../style.css" />
|
|
<title>SOCI - Oracle Backend Reference</title>
|
|
</head>
|
|
|
|
<body>
|
|
<p class="banner">SOCI - The C++ Database Access Library</p>
|
|
|
|
<h2>Oracle 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="#oracle_soci_error">oracle_soci_error</a><br />
|
|
</div>
|
|
</div>
|
|
|
|
<h3 id="prerequisites">Prerequisites</h3>
|
|
<h4 id="versions">Supported Versions</h4>
|
|
|
|
<p>The SOCI Oracle backend is currently supported for use with Oracle 10 or later.<br />
|
|
Older versions of Oracle may work as well, but they have not been tested by the SOCI team.</p>
|
|
|
|
<h4 id="tested">Tested Platforms</h4>
|
|
|
|
<table border="1" cellpadding="5" cellspacing="0">
|
|
<tbody>
|
|
<tr><th>Oracle version</th><th>Operating System</th><th>Compiler</th></tr>
|
|
<tr><td>10.2.0 (XE)</td><td>RedHat 5</td><td>g++ 4.3</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h4 id="required">Required Client Libraries</h4>
|
|
|
|
<p>The SOCI Oracle backend requires Oracle's <code>libclntsh</code> client library.
|
|
Depending on the particular system, the <code>libnnz10</code> library might be needed as well.</p>
|
|
<p>Note that the SOCI library itself depends also on <code>libdl</code>, so the minimum set of libraries needed to compile a basic client program is:</p>
|
|
<pre class="example">
|
|
-lsoci_core -lsoci_oracle -ldl -lclntsh -lnnz10
|
|
</pre>
|
|
|
|
<h4 id="connecting">Connecting to the Database</h4>
|
|
|
|
<p>To establish a connection to an Oracle database, create a <code>session</code> object
|
|
using the oracle backend factory together with a connection string:</p>
|
|
|
|
<pre class="example">
|
|
session sql(oracle, "service=orcl user=scott password=tiger");
|
|
|
|
// or:
|
|
session sql("oracle", "service=orcl user=scott password=tiger");
|
|
|
|
// or:
|
|
session sql("oracle://service=orcl user=scott password=tiger");
|
|
</pre>
|
|
|
|
<p>The set of parameters used in the connection string for Oracle is:</p>
|
|
<ul>
|
|
<li><code>service</code></li>
|
|
<li><code>user</code></li>
|
|
<li><code>password</code></li>
|
|
<li><code>mode</code> (optional)</li>
|
|
</ul>
|
|
<p>The first 3 of these parameters have to be provided as part of the connection string.</p>
|
|
<p>The <code>mode</code> parameter allows to specify the connection mode and can be any of:</p>
|
|
<ul>
|
|
<li><code>default</code> (which is assumed if omitted)</li>
|
|
<li><code>sysdba</code></li>
|
|
<li><code>sysoper</code></li>
|
|
</ul>
|
|
|
|
<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 user_tables", 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 Oracle backend supports the use of the SOCI <code>row</code> class, which facilitates retrieval of data which type is not known at compile time.</p>
|
|
|
|
<p>When calling <code>row::get<T>()</code>, the type you should pass as <code>T</code> depends upon the underlying database type.<br/> For the Oracle backend, this type mapping is:</p>
|
|
|
|
<table border="1" cellpadding="5" cellspacing="0">
|
|
<tbody>
|
|
<tr>
|
|
<th>Oracle Data Type</th>
|
|
<th>SOCI Data Type</th>
|
|
<th><code>row::get<T></code> specializations</th>
|
|
</tr>
|
|
<tr>
|
|
<td>number <i>(where scale > 0)</i></td>
|
|
<td><code>dt_double</code></td>
|
|
<td><code>double</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>number<br /><i>(where scale = 0 and precision ≤ std::numeric_limits<int>::digits10)</i></td>
|
|
<td><code>dt_integer</code></td>
|
|
<td><code>int</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>number</td>
|
|
<td><code>dt_long_long</code></td>
|
|
<td><code>long long</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>char, varchar, varchar2</td>
|
|
<td><code>dt_string</code></td>
|
|
<td><code>std::string</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>date</td>
|
|
<td><code>dt_date</code></td>
|
|
<td><code>std::tm</code><code></code></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<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 Oracle 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>SOCI's use of ':' to indicate a value to be bound within a SQL string is consistant with the underlying Oracle client library syntax.</p>
|
|
|
|
<h4 id="bulk">Bulk Operations</h4>
|
|
|
|
<p>The Oracle backend has full support for SOCI's <a href="../statements.html#bulk">bulk operations</a> interface.</p>
|
|
|
|
<h4 id="transactions">Transactions</h4>
|
|
|
|
<p><a href="../statements.html#transactions">Transactions</a> are also fully supported by the Oracle backend,
|
|
although transactions with non-default isolation levels have to be managed by explicit SQL statements.</p>
|
|
|
|
<h4 id="blob">blob Data Type</h4>
|
|
|
|
<p>The Oracle backend supports working with data stored in columns of type Blob, via SOCI's <a href="../exchange.html#blob"><code>blob</code></a> class.</p>
|
|
|
|
<h4 id="rowid">rowid Data Type</h4>
|
|
|
|
<p>Oracle rowid's are accessible via SOCI's <a href="../reference.html#rowid"><code>rowid</code></a> class.</p>
|
|
|
|
<h4 id="nested">Nested Statements</h4>
|
|
|
|
<p>The Oracle backend supports selecting into objects of type <code>statement</code>, so that you may work with nested sql statements and PL/SQL cursors:</p>
|
|
|
|
<pre class="example">
|
|
statement stInner(sql);
|
|
statement stOuter = (sql.prepare <<
|
|
"select cursor(select name from person order by id)"
|
|
" from person where id = 1",
|
|
into(stInner));
|
|
stInner.exchange(into(name));
|
|
stOuter.execute();
|
|
stOuter.fetch();
|
|
|
|
while (stInner.fetch())
|
|
{
|
|
std::cout << name << '\n';
|
|
}
|
|
</pre>
|
|
|
|
<h4 id="procedures">Stored Procedures</h4>
|
|
|
|
<p>Oracle stored procedures can be executed by using SOCI's <a href="../statements.html#procedures"><code>procedure</code></a> class.</p>
|
|
|
|
<h3 id="native">Acessing the native database API</h3>
|
|
|
|
<p>SOCI provides access to underlying datbabase APIs via several <code>get_backend()</code> functions, as described in the <a href="../beyond.html">Beyond SOCI</a> documentation.</p>
|
|
|
|
<p>The Oracle 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>oracle_session_backend</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>statement_backend * statement::get_backend()</code></td>
|
|
<td><code>oracle_statement_backend</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>blob_backend * blob::get_backend()</code></td>
|
|
<td><code>oracle_blob_backend</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>rowid_backend * rowid::get_backend()</code></td>
|
|
<td><code>oracle_rowid_backend</code></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
|
|
<h3 id="extensions">Backend-specific extensions</h3>
|
|
<h4 id="oracle_soci_error">eracle=soci_error</h4>
|
|
|
|
<p>The Oracle backend can throw instances of class <code>oracle_soci_error</code>,
|
|
which is publicly derived from <code>soci_error</code> and has an
|
|
additional public <code>err_num_</code> member containing the Oracle error code:</p>
|
|
|
|
<pre class="example">
|
|
int main()
|
|
{
|
|
try
|
|
{
|
|
// regular code
|
|
}
|
|
catch (oracle_soci_error const & e)
|
|
{
|
|
cerr << "Oracle error: " << e.err_num_
|
|
<< " " << e.what() << endl;
|
|
}
|
|
catch (exception const &e)
|
|
{
|
|
cerr << "Some other error: " << e.what() << endl;
|
|
}
|
|
}
|
|
</pre>
|
|
|
|
<p class="copyright">Copyright © 2004-2008 Maciej Sobczak, Stephen Hutton</p>
|
|
</body>
|
|
</html>
|