File: reference.html

package info (click to toggle)
soci 2.2.0-4
links: PTS, VCS
area: main
in suites: lenny
size: 3,400 kB
ctags: 1,969
sloc: cpp: 17,658; sh: 8,749; makefile: 379
file content (607 lines) | stat: -rw-r--r-- 20,049 bytes
<!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 - reference</title>
</head>

<body>
<p class="banner">SOCI - The C++ Database Access Library</p>

<h2>Client interface reference</h2>

<div class="navigation">
<a href="#commontypes">commonly used types</a><br />
<a href="#session">class Session</a><br />
<a href="#into">function into</a><br />
<a href="#use">function use</a><br />
<a href="#statement">class Statement</a><br />
<a href="#procedure">class Procedure</a><br />
<a href="#typeconversion">class TypeConversion</a><br />
<a href="#row">class Row</a><br />
<a href="#columnproperties">class ColumnProperties</a><br />
<a href="#values">class Values</a><br />
<a href="#blob">class BLOB</a><br />
<a href="rowid">class RowID</a><br />
<a href="#backendfactory">class BackEndFactory</a><br />
</div>

<p>The client interface is a set of classes and free functions declared in
the <code>soci.h</code> header file. All names are declared in the <code>SOCI</code>
namespace.</p>

<p>There are also additional names declared in the <code>SOCI::details</code>
namespace, but they are not supposed to be directly used by the users
of the library and are therefore not documented here. When such types
are used in the declarations that are part of the "public" interface,
they are replaced by "IT", which means "internal type". Types related
to the backend interface are named here, but documented on the <a
 href="backends.html">next page</a>.</p>

<h3 id="commontypes">commonly used types</h3>

<p>The following types are commonly used in the rest of the interface:</p>

<pre class="example">
// data types, as seen by the user
enum eDataType { eString, eChar, eDate, eDouble, eInteger,
                 eUnsignedLong };

// the enum type for indicator variables
enum eIndicator { eOK, eNoData, eNull, eTruncated };

// the type used for reporting exceptions
class SOCIError : public std::runtime_error { /* ... */ };
</pre>

<p>The <code>eDataType</code> type defines the basic SOCI data types.
User provided data types need to be associated with one of these basic
types.</p>

<p>The <code>eIndicator</code> type defines the possible states of data.</p>

<p>The <code>SOCIError</code> type is used for error reporting.</p>

<h3 id="session">class Session</h3>

<p>The <code>Session</code> class encapsulates the connection to the
database.</p>

<pre class="example">
class Session
{
public:
    Session(BackEndFactory const &amp;factory, std::string const &amp; connectString);
    ~Session();

    void begin();
    void commit();
    void rollback();
    <i>IT</i> once;
    <i>IT</i> prepare;

    template &lt;typename T&gt; <i>IT</i> operator&lt;&lt;(T const &amp;t);

    void setLogStream(std::ostream *s);
    std::ostream * getLogStream() const;

    std::string getLastQuery() const;

    details::SessionBackEnd * getBackEnd();
};
</pre>

<p>This class contains the following members:</p>
<ul>
  <li>Constructor expecting the backend factory object (which is
declared in the relevant backend interface) and the generic connection
string, which is interpreted by the backend implementation. Example:
<pre class="example">
Session sql(postgresql, "dbname=mydb");
</pre>
  </li>
  <li><code>begin</code>, <code>commit</code> and <code>rollback</code>
functions for transaction control. Example:
<pre class="example">
sql.rollback();
</pre>
  </li>
  <li><code>once</code> member, which is used for performing "instant"
queries that do not need to be separately prepared. Example:
<pre class="example">
sql.once &lt;&lt; "drop table persons";
</pre>
  </li>
  <li><code>prepare</code> member, which is used for statement
preparation - the result of the statement preparation must be provided
to the constructor of the <code>Statement</code> class. Example:
<pre class="example">
int i;
Statement st = (sql.prepare &lt;&lt;
                "insert into numbers(value) values(:val)", use(i));
</pre>
  </li>
  <li><code>operator&lt;&lt;</code> that is a shortcut forwarder to the
equivalent operator of the <code>once</code> member. Example:
<pre class="example">
sql &lt;&lt; "drop table persons";
</pre>
  </li>
  <li><code>setLogStream</code> and <code>getLogStream</code> functions for setting and getting the current stream object used for basic query logging. By default, it is <code>NULL</code>, which means no logging. The string value that is actually logged into the stream is one-line verbatim copy of the query string provided by the user, without including any data from the <code>use</code> elements. The query is logged exactly once, before the preparation step.</li>
  <li><code>getLastQuery</code> function for retrieving the text of the last used query.</li>
  <li><code>getBackEnd</code> function that returns the internal
pointer to the concrete backend implementation of the session. This is
provided for advanced users that need access to the functionality that
is not otherwise available.</li>
</ul>

<p>See <a href="basics.html">Connections and simple queries</a> for more
examples.</p>

<h3 id="into">function into</h3>

<p>The function <code>into</code> is used for binding local output data
(in other words, it defines where the results of the query are stored).</p>

<pre class="example">
template &lt;typename T&gt;
<i>IT</i> into(T &amp;t);

template &lt;typename T, typename T1&gt;
<i>IT</i> into(T &amp;t, T1 p1);

template &lt;typename T&gt;
<i>IT</i> into(T &amp;t, eIndicator &amp;indicator);

template &lt;typename T, typename T1&gt;
<i>IT</i> into(T &amp;t, eIndicator &amp;ind, T1 p1);

template &lt;typename T&gt;
<i>IT</i> into(T &amp;t, std::vector&lt;eIndicator&gt; &amp;indicator);
</pre>

<p>Example:</p>

<pre class="example">
int count;
sql &lt;&lt; "select count(*) from person", into(count);
</pre>

<p>See <a href="exchange.html#bind_local">Binding local data</a>
for more examples.</p>

<h3 id="use">function use</h3>

<p>The function <code>use</code> is used for binding local input data (in
other words, it defines where the parameters of the query come from).</p>

<pre class="example">
template &lt;typename T&gt;
<i>IT</i> use(T &amp;t);

template &lt;typename T, typename T1&gt;
<i>IT</i> use(T &amp;t, T1 p1);

template &lt;typename T&gt;
<i>IT</i> use(T &amp;t, eIndicator &amp;indicator);

template &lt;typename T, typename T1&gt;
<i>IT</i> use(T &amp;t, eIndicator &amp;ind, T1 p1);

template &lt;typename T&gt;
<i>IT</i> use(T &amp;t, std::vector&lt;eIndicator&gt; const &amp;indicator);

template &lt;typename T, typename T1&gt;
<i>IT</i> use(T &amp;t, std::vector&lt;eIndicator&gt; const &amp;ind, T1 p1);
</pre>

<p>Example:</p>

<pre class="example">
int val = 7;
sql &lt;&lt; "insert into numbers(val) values(:val)", use(val);
</pre>

<p>See <a href="exchange.html#bind_local">Binding local data</a>
for more examples.</p>

<h3 id="statement">class Statement</h3>

<p>The <code>Statement</code> class encapsulates the prepared statement.</p>

<pre class="example">
class Statement
{
public:
    Statement(Session &amp;s);
    Statement(<i>IT</i> const &amp;prep);
    ~Statement();

    void alloc();
    void bind(Values&amp; values);
    void exchange(<i>IT</i> const &amp;i); // for into
    void exchange(<i>IT</i> const &amp;u); // for use
    void cleanUp();

    void prepare(std::string const &amp;query);
    void defineAndBind();

    bool execute(bool withDataExchange = false);
    bool fetch();

    void describe();
    void setRow(Row* r);

    details::StatementBackEnd * getBackEnd();

    Session &amp;session_;
};
</pre>

<p>This class contains the following members:</p>
<ul>
  <li>Constructor accepting the <code>Session</code> object. This can
be used for later query preparation. Example:
<pre class="example">
Statement stmt(sql);
</pre>
  </li>
  <li>Constructor accepting the result of using <code>prepare</code>
on the <code>Session</code> object, see example provided above for the
    <code>Session</code> class.</li>
  <li><code>alloc</code> function, which allocates necessary resources.
This is normally called automatically.</li>
  <li><code>bind</code> function, which is used to bind the Values
object - this is used in the object-relational mapping and normally
called automatically.</li>
  <li>exchange functions for registering the binding of local data -
they expect the result of calling the <code>into</code> or <code>use</code>
functions and are normally invoked automatically.</li>
  <li><code>cleanUp</code> function for cleaning up resources, normally
called automatically.</li>
  <li><code>prepare</code> function for preparing the statement for
repeated execution.</li>
  <li><code>defineAndBind</code> function for actually executing the
registered bindings, normally called automatically.
  </li>
  <li><code>execute</code> function for executing the statement. If its
parameter is <code>false</code> then there is no data exchange with
locally bound variables (this form should be used if later <code>fetch</code>
of multiple rows is foreseen).</li>
  <li><code>fetch</code> function for retrieving the next portion of
the result.</li>
  <li><code>describe</code> function for extracting the type
information for the result (but no data is exchanged). This is normally
called automatically and only when dynamic resultset binding is used.</li>
  <li><code>setRow</code> function for associating the <code>Statement</code>
and <code>Row</code> objects, normally called automatically.</li>
  <li><code>getBackEnd</code> function that returns the internal
pointer to
the concrete backend implementation of the statement object. This is
provided
for advanced users that need access to the functionality that is not
otherwise available.</li>
  <li><code>session_</code> reference to the "parent" <code>Session</code>
object that was used to create this object.</li>
</ul>

<p>Most of the functions from the <code>Statement</code> class
interface are called automatically, but can be also used explicitly.
Example:</p>

<pre class="example">
Statement stmt(sql);
stmt.alloc();
stmt.prepare("select count(*) from persons");
int count;
stmt.exchange(into(count)); // repeat for all variables if there are more
stmt.defineAndBind();
stmt.execute(true);         // or execute() followed by fetch()
stmt.cleanUp();             // optional, destructor will do this anyway
</pre>

<p>See <a href="statements.html#preparation">Statement preparation and
repeated execution</a> for example uses.</p>

<h3 id="procedure">class Procedure</h3>

<p>The <code>Procedure</code> class encapsulates the call to the stored
procedure. It provides the same public interface as the <code>Statement</code>
class, but automatically adds the necessary "decorations" to the SQL
call (when they are required) for higher portability of the client code.</p>

<pre class="example">
class Procedure : public Statement
{
public:
    Procedure(Session &amp;s);
    Procedure(<i>IT</i> const &amp;prep);
};
</pre>

<p>The second constructor above expects the result of using <code>prepare</code>
on the <code>Session</code> object.</p>

<p>See <a href="statements.html#procedures">Stored procedures</a> for
examples.</p>

<h3 id="typeconversion">class TypeConversion</h3>

<p>The <code>TypeConversion</code> class is a traits class that is
supposed to be provided (specialized) by the user for defining
conversions to and from one of the basic SOCI types.</p>

<pre class="example">
template &lt;class T&gt;
struct TypeConversion
{
    typedef <i>SomeBasicType</i> base_type;
    static T from(<i>SomeBasicType</i> &amp;t);
    static <i>SomeBasicType</i> to(T &amp;t);
};
</pre>

<p>Users are supposed to properly implement the <code>from</code> and <code>to</code>
functions in their specializations of this template class.</p>

<p>See <a href="exchange.html#custom_types">Extending
SOCI to support custom (user-defined) C++ types</a>.</p>

<h3 id="row">class Row</h3>

<p>The <code>Row</code> class encapsulates the data and type information
retrieved for the single row when the dynamic rowset binding is used.</p>

<pre class="example">
class Row
{
public:
    Row();
    ~Row();

    void addProperties(ColumnProperties const &amp;cp);
    std::size_t size() const;

    eIndicator indicator(std::size_t pos) const;
    eIndicator indicator(std::string const &amp;name) const;

    template &lt;typename T&gt;
    void addHolder(T* t, eIndicator* ind);

    ColumnProperties const &amp; getProperties (std::size_t pos) const;
    ColumnProperties const &amp; getProperties (std::string const &amp;name) const;

    template &lt;typename T&gt;
    T get(std::size_t pos) const;

    template &lt;typename T&gt;
    T get(std::size_t pos, T const &amp;nullValue) const;

    template &lt;typename T&gt;
    T get(std::string const &amp;name) const;

    template &lt;typename T&gt;
    T get(std::string const &amp;name, T const &amp;nullValue) const;

    template &lt;typename T&gt;
    Row const &amp; operator&gt;&gt;(T &amp;value) const;
};
</pre>

<p>This class contains the following members:</p>
<ul>
  <li>Default constructor that allows to declare a <code>Row</code>
variable.</li>
  <li><code>addProperties</code> function for associating the <code>ColumnProperties</code>
object with the <code>Row</code>, called automatically.</li>
  <li><code>size</code> function that returns the number of columns in
the row.</li>
  <li><code>indicator</code> function that returns the indicator value
for the given column (column is specified by position - starting from 0
- or by name).</li>
  <li><code>addHolder</code> function that adds new holder object that
registers the given object for later bind, called automatically.</li>
  <li><code>getProperties</code> function that returns the properties
of the column given by position (starting from 0) or by name.</li>
  <li><code>get</code> functions that return the value of the column
given by position or name. If the column contains null, then these
functions either return the provided "default" <code>nullValue</code>
or throw an exception.</li>
  <li><code>operator&gt;&gt;</code> for convenience stream-like
extraction interface. Subsequent calls to this function are equivalent
to calling <code>get</code> with increasing position parameter,
starting from the beginning.</li>
</ul>

<p>See <a href="exchange.html#dynamic">Dynamic resultset binding</a> for
examples.</p>

<h3 id="columnproperties">class ColumnProperties</h3>

<p>The <code>ColumnProperties</code> class provides the type and name
information about the particular column in a rowset.</p>

<pre class="example">
enum eDataType { eString, eChar, eDate, eDouble, eInteger, eUnsignedLong };

class ColumnProperties
{
public:
    std::string getName() const;
    eDataType getDataType() const;
};
</pre>

<p>This class contains the following members:</p>
<ul>
  <li><code>getName</code> function that returns the name of the column.</li>
  <li><code>getDataType</code> that returns the type of the column.</li>
</ul>

<p>See <a href="exchange.html#dynamic">Dynamic resultset binding</a> for
examples.</p>

<h3 id="values">class Values</h3>

<p>The <code>Values</code> class encapsulates the data and type
information and is used for object-relational mapping.</p>

<pre class="example">
class Values
{
public:
    Values();

    eIndicator indicator(std::size_t pos) const;
    eIndicator indicator(std::string const &amp;name) const;

    template &lt;typename T&gt;
    T get(std::size_t pos) const;

    template &lt;typename T&gt;
    T get(std::size_t pos, T const &amp;nullValue) const;

    template &lt;typename T&gt;
    T get(std::string const &amp;name) const;

    template &lt;typename T&gt;
    T get(std::string const &amp;name, T const &amp;nullValue) const;

    template &lt;typename T&gt;
    Values const &amp; operator&gt;&gt;(T &amp;value) const;

    template &lt;typename T&gt;
    void set(std::string const &amp;name, T &amp;value, eIndicator indicator=eOK);
};
</pre>

<p>This class contains the following members:</p>
<ul>
  <li><code>indicator</code> functions with the same meaning as in the <code>Row</code>
class.</li>
  <li><code>get</code> functions with the same meaning as in the <code>Row</code>
class.</li>
  <li><code>operator&gt;&gt;</code> for convenience stream-like
extraction interface. Subsequent calls to this function are equivalent
to calling <code>get</code> with increasing position parameter,
starting from the beginning.</li>
  <li><code>set</code> function for storing values in named columns.</li>
</ul>

<p>See <a href="exchange.html#object_relational">Object-relational mapping</a>
for examples.</p>

<h3 id="blob">class BLOB</h3>

<p>The <code>BLOB</code> class encapsulates the "large object"
functionality.</p>

<pre class="example">
class BLOB
{
public:
    BLOB(Session &amp;s);
    ~BLOB();

    std::size_t getLen();
    std::size_t read(std::size_t offset, char *buf, std::size_t toRead);
    std::size_t write(std::size_t offset, char const *buf, std::size_t toWrite);
    std::size_t append(char const *buf, std::size_t toWrite);
    void trim(std::size_t newLen);

    details::BLOBBackEnd * getBackEnd();
};
</pre>

<p>This class contains the following members:</p>
<ul>
  <li>Constructor associating the BLOB object with the Session object.</li>
  <li><code>getLen</code> function that returns the size of the BLOB
object.</li>
  <li><code>read</code> function that reads the BLOB data into provided
buffer.</li>
  <li><code>write</code> function that writes the BLOB data from
provided buffer.</li>
  <li><code>append</code> function that appends to the existing BLOB
data.</li>
  <li><code>trim</code> function that truncates the existing data to
the new length.</li>
  <li><code>getBackEnd</code> function that returns the internal
pointer to
the concrete backend implementation of the BLOB object. This is
provided
for advanced users that need access to the functionality that is not
otherwise available.</li>
</ul>

<p>See <a href="exchange.html#blob">Large objects (BLOBs)</a> for more
discussion.</p>

<h3 id="rowid">class RowID</h3>

<p>The <code>RowID</code> class encapsulates the "row identifier" object.</p>

<pre class="example">
class RowID
{
public:
    RowID(Session &amp;s);
    ~RowID();

    details::RowIDBackEnd * getBackEnd();
};
</pre>

<p>This class contains the following members:</p>
<ul>
  <li>Constructor associating the <code>RowID</code> object with the <code>Session</code>
object.</li>
  <li><code>getBackEnd</code> function that returns the internal
pointer to
the concrete backend implementation of the <code>RowID</code> object.</li>
</ul>

<h3 id="backendfactory">class BackEndFactory</h3>

<p>The <code>BackEndFactory</code> class provides the abstract interface
for concrete backend factories.</p>

<pre class="example">
struct BackEndFactory
{
    virtual details::SessionBackEnd * makeSession(
        std::string const &amp;connectString) const = 0;
};
</pre>

<p>The only member of this class is the <code>makeSession</code> function
that is supposed to create concrete backend implementation of the
session object.</p>

<p>Objects of this type are declared by each backend and should be
provided to the constructor of the <code>Session</code> class.
In simple programs users do not need to use this class directly, but
the example use is:</p>

<pre class="example">
BackEndFactory &amp;factory = postgresql;
std::string connectionParameters = "dbname=mydb";

Session sql(factory, parameters);
</pre>

<table class="foot-links" border="0" cellpadding="2" cellspacing="2">
  <tr>
    <td class="foot-link-left">
      <a href="beyond.html">Previous (Beyond SOCI)</a>
    </td>
    <td class="foot-link-right">
      <a href="backends.html">Next (Backends reference)</a>
    </td>
  </tr>
</table>

<p class="copyright">Copyright &copy; 2004-2006 Maciej Sobczak, Stephen Hutton</p>
</body>
</html>