Document statement::get_affected_rows().

Change the structure of the "Beyond SOCI" page to allow adding documentation of other non-standard SQL constructs there later.
SOCI · Jul 10, 2012 · 36e9089 · 36e9089
1 parent f48ef8d
commit 36e9089
Show file tree

Hide file tree

Showing 4 changed files with 40 additions and 6 deletions.
diff --git a/doc/beyond.html b/doc/beyond.html
@@ -3,16 +3,46 @@
 <head>
   <meta content="text/html; charset=ISO-8859-1"  http-equiv="content-type" />
   <link rel="stylesheet" type="text/css" href="style.css" />
-  <title>SOCI - beyond</title>
+  <title>SOCI - beyond standard SQL</title>
 </head>
 
 <body>
 <p class="banner">SOCI - The C++ Database Access Library</p>
 
-<h2>Beyond SOCI</h2>
+<h2>Beyond standard SQL</h2>
+
+<p>Sometimes the standard SQL is not enough and database-specific syntax needs
+to be used. When possible and practical, SOCI provides wrappers hiding the
+differences between the backends and this section describes these wrappers.
+And if this is still not enough, you can use the backend-specific methods
+directly as described below.</p>
+
+<h3>Getting the number of rows affected by an operation</h3>
+
+<p>It can be useful to know how many rows were affected by the last SQL
+statement, most often when using <tt>INSERT</tt>, <tt>UPDATE</tt> or
+<tt>DELETE</tt>. SOCI provides <code>statement::get_affected_rows()</code>
+method allowing to do this:</p>
+
+<pre class="example">
+statement st = (sql.prepare &lt;&lt; "update some_table ...");
+st.execute(true);
+
+if ( !st.get_affected_rows() ) {
+    ... investigate why no rows were modified ...
+}
+</pre>
+
+<div class="note">
+<p><span class="note">Portability note:</span></p>
+This method is currently not supported by the Oracle backend. It is however
+supported when using Oracle database via ODBC backend.</p>
+</div>
+
+<h3>Beyond SOCI API</h3>
 
 <p>As the original name of the library (Simple Oracle Call Interface)
-clearly stated, SOCI is intended to be a <i>simple</i> library, targetting the
+clearly stated, SOCI is intended to be a <i>simple</i> library, targeting the
 majority of needs in regular C++ application. We do not claim that
 <i>everything</i> can be done with SOCI and it was never the intent of the
 library. What is important, though, is that the simplicity of the

diff --git a/doc/index.html b/doc/index.html
@@ -21,7 +21,7 @@ <h1>Documentation and tutorial</h1>
 <a href="multithreading.html">Multithreading and SOCI</a><br />
 <a href="boost.html">Integration with Boost</a><br />
 <a href="interfaces.html">Interfaces</a><br />
-<a href="beyond.html">Beyond SOCI</a><br />
+<a href="beyond.html">Beyond standard SQL</a><br />
 <a href="reference.html">Client interface reference</a><br />
 <a href="backends.html">Backends reference</a><br />
 <a href="rationale.html">Rationale FAQ</a><br /><br />

diff --git a/doc/interfaces.html b/doc/interfaces.html
@@ -92,7 +92,7 @@ <h4>Low-level backend interface</h4>
       <a href="boost.html">Previous (Boost)</a>
     </td>
     <td class="foot-link-right">
-      <a href="beyond.html">Next (Beyond SOCI)</a>
+      <a href="beyond.html">Next (Beyond standard SQL)</a>
     </td>
   </tr>
 </table>

diff --git a/doc/reference.html b/doc/reference.html
@@ -343,6 +343,7 @@ <h3 id="statement">class statement</h3>
     void define_and_bind();
 
     bool execute(bool withDataExchange = false);
+    long long get_affected_rows();
     bool fetch();
 
     bool got_data() const;
@@ -385,6 +386,9 @@ <h3 id="statement">class statement</h3>
 locally bound variables (this form should be used if later <code>fetch</code>
 of multiple rows is foreseen). Returns <code>true</code> if there was at least
 one row of data returned.</li>
+  <li><code>get_affected_rows</code> function returns the number of rows
+affected by the last statement. Returns <code>-1</code> if it's not
+implemented by the backend being used.</li>
   <li><code>fetch</code> function for retrieving the next portion of
 the result. Returns <code>true</code> if there was new data.</li>
 <li><code>got_data</code> return <code>true</code> if the most recent
@@ -893,7 +897,7 @@ <h3 id="simpleclient">Simple client interface</h3>
 <table class="foot-links" border="0" cellpadding="2" cellspacing="2">
   <tr>
     <td class="foot-link-left">
-      <a href="beyond.html">Previous (Beyond SOCI)</a>
+      <a href="beyond.html">Previous (Beyond standard SQL)</a>
     </td>
     <td class="foot-link-right">
       <a href="backends.html">Next (Backends reference)</a>