ARCHIVE/rippled
1
0
Fork 0
mirror of https://github.com/XRPLF/rippled.git synced 2025-11-19 18:45:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Squashed 'src/soci/' content from commit 6e9312c

Browse Source 
git-subtree-dir: src/soci
git-subtree-split: 6e9312c4bb3748907bd28d62c40feca42878cfef
This commit is contained in:
Vinnie Falco
2015-03-18 19:36:00 -07:00
commit 9708a12607
341 changed files with 54122 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
doc/interfaces.html Normal file
View File

@@ -0,0 +1,103 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//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 - integration with Boost</title>
</head>
<body>
<p class="banner">SOCI - The C++ Database Access Library</p>
<h2>Interfaces</h2>
<p>One of the major features of SOCI, although not immediately visible, is the variety of interfaces (APIs) that are available for the user. These can be divided into <i>sugar</i>, <i>core</i> and <i>simple</i>.</p>
<h4>Sugar</h4>
<p>The most exposed and promoted interface supports the syntax sugar that makes SOCI similar in look and feel to embedded SQL. The example of application code using this interface is:</p>
<pre class="example">
session sql("postgresql://dbname=mydb");
int id = 123;
string name;
sql &lt;&lt; "select name from persons where id = :id", into(name), use(id);
</pre>
<h4>Core</h4>
<p>The above example is equivalent to the following, more explicit sequence of calls:</p>
<pre class="example">
session sql("postgresql://dbname=mydb");
int id = 123;
string name;
statement st(sql);
st.exchange(into(name));
st.exchange(use(id));
st.alloc();
st.prepare("select name from persons where id = :id");
st.define_and_bind();
st.execute(true);
</pre>
<p>The value of the <i>core</i> interface is that it is the basis for all other interfaces, and can be also used by developers to easily prepare their own convenience interfaces. Users who cannot or for some reason do not want to use the natural <i>sugar</i> interface should try the <i>core</i> one as the foundation and access point to all SOCI functionality.</p>
<p>Note that the <i>sugar</i> interface wraps only those parts of the <i>core</i> that are related to data binding and query streaming.</p>
<h4>Simple</h4>
<p>The <i>simple</i> interface is provided specifically to allow easy integration of the SOCI library with other languages that have the ability to link with binaries using the "C" calling convention. To facilitate this integration, the <i>simple</i> interface does not use any pointers to data except C-style strings and opaque handles, but the consequence of this is that user data is managed by SOCI and not by user code. To avoid exceptions passing the module boundaries, all errors are reported as state variables of relevant objects.</p>
<p>The above examples can be rewritten as (without error-handling):</p>
<pre class="example">
#include &lt;soci-simple.h&gt;
// ...
session_handle sql = soci_create_session("postgresql://dbname=mydb");
statement_handle st = soci_create_statement(sql);
soci_use_int(st, "id");
soci_set_use_int(st, "id", 123);
int namePosition = soci_into_string(st);
soci_prepare(st, "select name from persons where id = :id");
soci_execute(st, true);
char const * name = soci_get_into_string(st, namePosition);
printf("name is %s\n", name);
soci_destroy_statement(st);
soci_destroy_session(sql);
</pre>
<p>The <i>simple</i> interface supports single and bulk data exchange for static binding. Dynamic row description is not supported in this release.</p>
<p>See <a href="reference.html#simpleclient">Simple client interface</a> reference documentation for more details.</p>
<h4>Low-level backend interface</h4>
<p>The low-level backend interface allows to interact with backends directly and in principle allows to access the database without involving any other component. There is no particular reason to use this interface in the user code.</p>
<table class="foot-links" border="0" cellpadding="2" cellspacing="2">
<tr>
<td class="foot-link-left">
<a href="boost.html">Previous (Boost)</a>
</td>
<td class="foot-link-right">
<a href="beyond.html">Next (Beyond standard SQL)</a>
</td>
</tr>
</table>
<p class="copyright">Copyright &copy; 2012 Vadim Zeitlin</p>
<p class="copyright">Copyright &copy; 2004-2008 Maciej Sobczak, Stephen Hutton</p>
</body>
</html>