mirror of
https://github.com/XRPLF/rippled.git
synced 2025-11-24 13:05:53 +00:00
964 lines
37 KiB
HTML
964 lines
37 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 - 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="#parameters">class connection_parameters</a><br />
|
|
<a href="#pool">class connection_pool</a><br />
|
|
<a href="#transaction">class transaction</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 type_conversion</a><br />
|
|
<a href="#row">class row</a><br />
|
|
<a href="#columnproperties">class column_properties</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 backend_factory</a><br /><br />
|
|
<a href="#simpleclient">Simple client interface</a><br />
|
|
</div>
|
|
|
|
<p>The core client interface is a set of classes and free functions declared in
|
|
the <code>soci.h</code> header file. All names are dbeclared 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 data_type { dt_string, dt_date, dt_double, dt_integer, dt_long_long, dt_unsigned_long_long };
|
|
|
|
// the enum type for indicator variables
|
|
enum indicator { i_ok, i_null, i_truncated };
|
|
|
|
// the type used for reporting exceptions
|
|
class soci_error : public std::runtime_error { /* ... */ };
|
|
</pre>
|
|
|
|
<p>The <code>data_type</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>indicator</code> type defines the possible states of data.</p>
|
|
|
|
<p>The <code>soci_error</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();
|
|
explicit session(connection_parameters const & parameters);
|
|
session(backend_factory const & factory, std::string const & connectString);
|
|
session(std::string const & backendName, std::string const & connectString);
|
|
explicit session(std::string const & connectString);
|
|
explicit session(connection_pool & pool);
|
|
|
|
~session();
|
|
|
|
void open(backend_factory const & factory, std::string const & connectString);
|
|
void open(std::string const & backendName, std::string const & connectString);
|
|
void open(std::string const & connectString);
|
|
void close();
|
|
void reconnect();
|
|
|
|
void begin();
|
|
void commit();
|
|
void rollback();
|
|
|
|
<i>IT</i> once;
|
|
<i>IT</i> prepare;
|
|
|
|
template <typename T> <i>IT</i> operator<<(T const & t);
|
|
|
|
bool got_data() const;
|
|
|
|
bool get_next_sequence_value(std::string const & sequence, long & value);
|
|
bool get_last_insert_id(std::string const & table, long & value);
|
|
|
|
std::ostringstream & get_query_stream();
|
|
|
|
void set_log_stream(std::ostream * s);
|
|
std::ostream * get_log_stream() const;
|
|
|
|
std::string get_last_query() const;
|
|
|
|
void uppercase_column_names(bool forceToUpper);
|
|
|
|
details::session_backend * get_backend();
|
|
|
|
std::string get_backend_name() const;
|
|
};
|
|
</pre>
|
|
|
|
<p>This class contains the following members:</p>
|
|
<ul>
|
|
<li>Various constructors. The default one creates the session in the disconnected state.
|
|
The others expect the backend factory object, or the backend name, or the URL-like
|
|
composed connection string or the special parameters object containing both the backend
|
|
and the connection string as well as possibly other connection options.
|
|
The last constructor creates a session proxy associated
|
|
with the session that is available in the given pool and releases it back to the pool
|
|
when its lifetime ends. Example:
|
|
<pre class="example">
|
|
session sql(postgresql, "dbname=mydb");
|
|
session sql("postgresql", "dbname=mydb");
|
|
session sql("postgresql://dbname=mydb");
|
|
</pre>
|
|
The constructors that take backend name as string load the shared library (if not yet loaded)
|
|
with name computed as <code>libsoci_ABC.so</code> (or <code>libsoci_ABC.dll</code> on Windows)
|
|
where <code>ABC</code> is the given backend name.
|
|
</li>
|
|
<li><code>open</code>, <code>close</code> and <code>reconnect</code> functions for
|
|
reusing the same session object many times; the <code>reconnect</code> function attempts
|
|
to establish the connection with the same parameters as most recently used with constructor
|
|
or <code>open</code>. The arguments for <code>open</code> are treated in the same way as
|
|
for constructors.
|
|
</li>
|
|
<li><code>begin</code>, <code>commit</code> and <code>rollback</code>
|
|
functions for transaction control.
|
|
</li>
|
|
<li><code>once</code> member, which is used for performing <i>instant</i>
|
|
queries that do not need to be separately prepared. Example:
|
|
<pre class="example">
|
|
sql.once << "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 <<
|
|
"insert into numbers(value) values(:val)", use(i));
|
|
</pre>
|
|
</li>
|
|
<li><code>operator<<</code> that is a shortcut forwarder to the
|
|
equivalent operator of the <code>once</code> member. Example:
|
|
<pre class="example">
|
|
sql << "drop table persons";
|
|
</pre>
|
|
</li>
|
|
<li><code>got_data</code> returns true if the last executed query had non-empty result.</li>
|
|
<li><code>get_next_sequence_value</code> returns true if the next value of
|
|
the sequence with the specified name was generated and returned in its
|
|
second argument. Unless you can be sure that your program will use only
|
|
databases that support sequences, consider using this method in conjunction
|
|
with <code>get_last_insert_id()</code> as explained in
|
|
<a href="beyond.html#sequences">"Working with sequences"</a> section.</li>
|
|
<li><code>get_last_insert_id</code> returns true if it could retrieve the
|
|
last value automatically generated by the database for an auto-incremented
|
|
field. Notice that although this method takes the table name, for some
|
|
databases, such as Microsoft SQL Server and SQLite, this value is actually
|
|
global, so you should attempt to retrieve it immediately after performing an
|
|
insertion.</li>
|
|
<li><code>get_query_stream</code> provides direct access to the stream object that is used
|
|
to accumulate the query text and exists in particular to allow the user to imbue specific locale
|
|
to this stream.</li>
|
|
<li><code>set_log_stream</code> and <code>get_log_stream</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>get_last_query</code> retrieves the text of the last used query.</li>
|
|
<li><code>uppercase_column_names</code> allows to force all column names to uppercase in dynamic row description;
|
|
this function is particularly useful for portability, since various database servers
|
|
report column names differently (some preserve case, some change it).</li>
|
|
<li><code>get_backend</code> 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>
|
|
<li><code>get_backend_name</code> is a convenience forwarder to the same function
|
|
of the backend object.</li>
|
|
</ul>
|
|
|
|
<p>See <a href="basics.html">Connections and simple queries</a> for more
|
|
examples.</p>
|
|
|
|
<h3 id="parameters">class connection_parameters</h3>
|
|
|
|
<p>The <code>connection_parameters</code> class is a simple container for the backend pointer, connection string and any other connection options. It is used together with <code>session</code> constructor and <code>open()</code> method.</p>
|
|
|
|
<pre class="example">
|
|
class connection_parameters
|
|
{
|
|
public:
|
|
connection_parameters();
|
|
connection_parameters(backend_factory const & factory, std::string const & connectString);
|
|
connection_parameters(std::string const & backendName, std::string const & connectString);
|
|
explicit connection_parameters(std::string const & fullConnectString);
|
|
|
|
void set_option(const char * name, std::string const & value);
|
|
bool get_option(const char * name, std::string & value) const
|
|
};
|
|
</pre>
|
|
|
|
<p>The methods of this class are:</p>
|
|
<ul>
|
|
<li>Default constructor is rarely used as it creates an uninitialized
|
|
object and the only way to initialize it later is to assign another, valid,
|
|
connection_parameters object to this one.</li>
|
|
<li>The other constructors correspond to the similar constructors of the
|
|
<code>session</code> class and specify both the backend, either as a
|
|
pointer to it or by name, and the connection string.</li>
|
|
<li><code>set_option</code> can be used to set the value of an option with
|
|
the given name. Currently all option values are strings, so if you need to
|
|
set a numeric option you need to convert it to a string first. If an option
|
|
with the given name had been already set before, its old value is
|
|
overwritten.</li>
|
|
</ul>
|
|
|
|
<h3 id="pool">class connection_pool</h3>
|
|
|
|
<p>The <code>connection_pool</code> class encapsulates the thread-safe pool of connections
|
|
and ensures that only one thread at a time has access to any connection that it manages.</p>
|
|
|
|
<pre class="example">
|
|
class connection_pool
|
|
{
|
|
public:
|
|
explicit connection_pool(std::size_t size);
|
|
~connection_pool();
|
|
|
|
session & at(std::size_t pos);
|
|
|
|
std::size_t lease();
|
|
bool try_lease(std::size_t & pos, int timeout);
|
|
void give_back(std::size_t pos);
|
|
};
|
|
</pre>
|
|
|
|
<p>The operations of the pool are:</p>
|
|
|
|
<ul>
|
|
<li>Constructor that takes the intended size of the pool. After construction,
|
|
the pool contains regular <code>session</code> objects in disconnected state.</li>
|
|
<li><code>at</code> function that provides direct access to any given entry
|
|
in the pool. This function is <i>non-synchronized</i>.</li>
|
|
<li><code>lease</code> function waits until some entry is available (which means
|
|
that it is not used) and returns the position of that entry in the pool, marking
|
|
it as <i>locked</i>.</li>
|
|
<li><code>try_lease</code> acts like <code>lease</code>, but allows to set up a
|
|
time-out (relative, in milliseconds) on waiting. Negative time-out value means no time-out.
|
|
Returns <code>true</code> if the entry was obtained, in which case its position
|
|
is written to the <code>pos</code> parametr, and <code>false</code> if no entry
|
|
was available before the time-out.</li>
|
|
<li><code>give_back</code> should be called when the entry on the given position
|
|
is no longer in use and can be passed to other requesting thread.</li>
|
|
</ul>
|
|
<p>Note: calls to <code>lease</code> and <code>give_back</code> are automated by the
|
|
dedicated constructor of the <code>session</code> class, see above.</p>
|
|
|
|
<h3 id="transaction">class transaction</h3>
|
|
|
|
<p>The class <code>transaction</code> can be used for associating the transaction
|
|
with some code scope. It is a RAII wrapper for regular transaction operations that
|
|
automatically rolls back in its destructor <i>if</i> the transaction was not explicitly
|
|
committed before.</p>
|
|
<pre class="example">
|
|
class transaction
|
|
{
|
|
public:
|
|
explicit transaction(session & sql);
|
|
|
|
~transaction();
|
|
|
|
void commit();
|
|
void rollback();
|
|
|
|
private:
|
|
// ...
|
|
};
|
|
</pre>
|
|
|
|
<p>Note that objects of this class are not notified of other transaction related operations
|
|
that might be executed by user code explicitly or hidden inside SQL queries.
|
|
It is not recommended to mix different ways of managing transactions.</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 <typename T>
|
|
<i>IT</i> into(T & t);
|
|
|
|
template <typename T, typename T1>
|
|
<i>IT</i> into(T & t, T1 p1);
|
|
|
|
template <typename T>
|
|
<i>IT</i> into(T & t, indicator & ind);
|
|
|
|
template <typename T, typename T1>
|
|
<i>IT</i> into(T & t, indicator & ind, T1 p1);
|
|
|
|
template <typename T>
|
|
<i>IT</i> into(T & t, std::vector<indicator> & ind);
|
|
</pre>
|
|
|
|
<p>Example:</p>
|
|
|
|
<pre class="example">
|
|
int count;
|
|
sql << "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 <typename T>
|
|
<i>IT</i> use(T & t);
|
|
|
|
template <typename T, typename T1>
|
|
<i>IT</i> use(T & t, T1 p1);
|
|
|
|
template <typename T>
|
|
<i>IT</i> use(T & t, indicator & ind);
|
|
|
|
template <typename T, typename T1>
|
|
<i>IT</i> use(T & t, indicator & ind, T1 p1);
|
|
|
|
template <typename T>
|
|
<i>IT</i> use(T & t, std::vector<indicator> const & ind);
|
|
|
|
template <typename T, typename T1>
|
|
<i>IT</i> use(T & t, std::vector<indicator> const & ind, T1 p1);
|
|
</pre>
|
|
|
|
<p>Example:</p>
|
|
|
|
<pre class="example">
|
|
int val = 7;
|
|
sql << "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 & s);
|
|
statement(<i>IT</i> const & prep);
|
|
~statement();
|
|
|
|
statement(statement const & other);
|
|
void operator=(statement const & other);
|
|
|
|
void alloc();
|
|
void bind(values & v);
|
|
void exchange(<i>IT</i> const & i);
|
|
void exchange(<i>IT</i> const & u);
|
|
void clean_up();
|
|
|
|
void prepare(std::string const & query);
|
|
void define_and_bind();
|
|
|
|
bool execute(bool withDataExchange = false);
|
|
long long get_affected_rows();
|
|
bool fetch();
|
|
|
|
bool got_data() const;
|
|
|
|
void describe();
|
|
void set_row(row * r);
|
|
void exchange_for_rowset(<i>IT</i> const & i);
|
|
|
|
details::statement_backend * get_backend();
|
|
};
|
|
</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>Copy operations.</li>
|
|
<li><code>alloc</code> function, which allocates necessary internal resources.</li>
|
|
<li><code>bind</code> function, which is used to bind the <code>values</code>
|
|
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>clean_up</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>define_and_bind</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). 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
|
|
execution returned any rows.</li>
|
|
<li><code>describe</code> function for extracting the type
|
|
information for the result (note: no data is exchanged). This is normally
|
|
called automatically and only when dynamic resultset binding is used.</li>
|
|
<li><code>set_row</code> function for associating the <code>statement</code>
|
|
and <code>row</code> objects, normally called automatically.</li>
|
|
<li><code>exchange_for_rowset</code> as a special case for binding <code>rowset</code>
|
|
objects.</li>
|
|
<li><code>get_backend</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>
|
|
</ul>
|
|
|
|
<p>See <a href="statements.html#preparation">Statement preparation and
|
|
repeated execution</a> for example uses.</p>
|
|
|
|
<p>Most of the functions from the <code>statement</code> class
|
|
interface are called automatically, but can be also used explicitly.
|
|
See <a href="interfaces">Interfaces</a> for the description of various way to use
|
|
this interface.</p>
|
|
|
|
<h3 id="procedure">class procedure</h3>
|
|
|
|
<p>The <code>procedure</code> class encapsulates the call to the stored
|
|
procedure and is aimed for higher portability of the client code.</p>
|
|
|
|
<pre class="example">
|
|
class procedure
|
|
{
|
|
public:
|
|
procedure(<i>IT</i> const & prep);
|
|
|
|
bool execute(bool withDataExchange = false);
|
|
bool fetch();
|
|
bool got_data() const;
|
|
};
|
|
</pre>
|
|
|
|
<p>The constructor 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 type_conversion</h3>
|
|
|
|
<p>The <code>type_conversion</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 <typename T>
|
|
struct type_conversion
|
|
{
|
|
typedef T base_type;
|
|
|
|
static void from_base(base_type const & in, indicator ind, T & out);
|
|
|
|
static void to_base(T const & in, base_type & out, indicator & ind);
|
|
};
|
|
</pre>
|
|
|
|
<p>Users are supposed to properly implement the <code>from_base</code> and <code>to_base</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 uppercase_column_names(bool forceToUpper);
|
|
|
|
std::size_t size() const;
|
|
|
|
indicator get_indicator(std::size_t pos) const;
|
|
indicator get_indicator(std::string const & name) const;
|
|
|
|
column_properties const & get_properties (std::size_t pos) const;
|
|
column_properties const & get_properties (std::string const & name) const;
|
|
|
|
template <typename T>
|
|
T get(std::size_t pos) const;
|
|
|
|
template <typename T>
|
|
T get(std::size_t pos, T const & nullValue) const;
|
|
|
|
template <typename T>
|
|
T get(std::string const & name) const;
|
|
|
|
template <typename T>
|
|
T get(std::string const & name, T const & nullValue) const;
|
|
|
|
template <typename T>
|
|
row const & operator>>(T & value) const;
|
|
|
|
void skip(std::size_t num = 1) const;
|
|
|
|
void reset_get_counter() 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>uppercase_column_names</code> - see the same function in the <code>session</code> class.</li>
|
|
<li><code>size</code> function that returns the number of columns in
|
|
the row.</li>
|
|
<li><code>get_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>get_properties</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>></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>skip</code> and <code>reset_get_counter</code> allow to change the
|
|
order of data extraction for the above operator.</li>
|
|
</ul>
|
|
|
|
<p>See <a href="exchange.html#dynamic">Dynamic resultset binding</a> for
|
|
examples.</p>
|
|
|
|
<h3 id="columnproperties">class column_properties</h3>
|
|
|
|
<p>The <code>column_properties</code> class provides the type and name
|
|
information about the particular column in a rowset.</p>
|
|
|
|
<pre class="example">
|
|
class column_properties
|
|
{
|
|
public:
|
|
std::string get_name() const;
|
|
data_type get_data_type() const;
|
|
};
|
|
</pre>
|
|
|
|
<p>This class contains the following members:</p>
|
|
<ul>
|
|
<li><code>get_name</code> function that returns the name of the column.</li>
|
|
<li><code>get_data_type</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();
|
|
|
|
void uppercase_column_names(bool forceToUpper);
|
|
|
|
indicator get_indicator(std::size_t pos) const;
|
|
indicator get_indicator(std::string const & name) const;
|
|
|
|
template <typename T>
|
|
T get(std::size_t pos) const;
|
|
|
|
template <typename T>
|
|
T get(std::size_t pos, T const & nullValue) const;
|
|
|
|
template <typename T>
|
|
T get(std::string const & name) const;
|
|
|
|
template <typename T>
|
|
T get(std::string const & name, T const & nullValue) const;
|
|
|
|
template <typename T>
|
|
values const & operator>>(T & value) const;
|
|
|
|
void skip(std::size_t num = 1) const;
|
|
void reset_get_counter() const;
|
|
|
|
template <typename T>
|
|
void set(std::string const & name, T const & value, indicator indic = i_ok);
|
|
|
|
template <typename T>
|
|
void set(const T & value, indicator indic = i_ok);
|
|
|
|
template <typename T>
|
|
values & operator<<(T const & value);
|
|
};
|
|
</pre>
|
|
|
|
<p>This class contains the same members as the <code>row</code> class (with the same meaning)
|
|
plus:</p>
|
|
<ul>
|
|
<li><code>set</code> function for storing values in named columns or in subsequent positions.</li>
|
|
<li><code>operator<<</code> for convenience.</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:
|
|
explicit blob(session & 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::blob_backend * get_backend();
|
|
};
|
|
</pre>
|
|
|
|
<p>This class contains the following members:</p>
|
|
<ul>
|
|
<li>Constructor associating the <code>blob</code> object with the <code>session</code> object.</li>
|
|
<li><code>get_len</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>get_backend</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:
|
|
explicit rowid(Session & s);
|
|
~rowid();
|
|
|
|
details::rowid_backend * get_backend();
|
|
};
|
|
</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>get_backend</code> function that returns the internal
|
|
pointer to
|
|
the concrete backend implementation of the <code>rowid</code> object.</li>
|
|
</ul>
|
|
|
|
<h3 id="backendfactory">class backend_factory</h3>
|
|
|
|
<p>The <code>backend_factory</code> class provides the abstract interface
|
|
for concrete backend factories.</p>
|
|
|
|
<pre class="example">
|
|
struct backend_factory
|
|
{
|
|
virtual details::session_backend * make_session(
|
|
std::string const & connectString) const = 0;
|
|
};
|
|
</pre>
|
|
|
|
<p>The only member of this class is the <code>make_session</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">
|
|
backend_factory & factory = postgresql;
|
|
std::string connectionParameters = "dbname=mydb";
|
|
|
|
session sql(factory, parameters);
|
|
</pre>
|
|
|
|
<h3 id="simpleclient">Simple client interface</h3>
|
|
|
|
<p>The simple client interface is provided with other languages in mind,
|
|
to allow easy integration of the SOCI library with script interpreters and those
|
|
languages that have the ability to link directly with object files using
|
|
the "C" calling convention.</p>
|
|
<p>The functionality of this interface is limited and in particular the
|
|
dynamic rowset description and type conversions are not supported in this release.
|
|
On the other hand, the important feature of this interface is that it does not
|
|
require passing pointers to data managed by the user, because all data is handled
|
|
at the SOCI side. This should make it easier to integrate SOCI with languages that
|
|
have constrained ability to understand the C type system.</p>
|
|
<p>Users of this interface need to explicitly <code>#include <soci-simple.h></code>.</p>
|
|
|
|
<pre class="example">
|
|
typedef void * session_handle;
|
|
session_handle soci_create_session(char const * connectionString);
|
|
void soci_destroy_session(session_handle s);
|
|
|
|
void soci_begin(session_handle s);
|
|
void soci_commit(session_handle s);
|
|
void soci_rollback(session_handle s);
|
|
|
|
int soci_session_state(session_handle s);
|
|
char const * soci_session_error_message(session_handle s);
|
|
</pre>
|
|
|
|
<p>The functions above provide the <i>session</i> abstraction with the help of opaque handle.
|
|
The <code>soci_session_state</code> function returns <code>1</code> if there was no error
|
|
during the most recently executed function and <code>0</code> otherwise, in which
|
|
case the <code>soci_session_error_message</code> can be used to obtain a human-readable
|
|
error description.</p>
|
|
<p>Note that the only function that cannot report all errors this way is <code>soci_create_session</code>,
|
|
which returns <code>NULL</code> if it was not possible to create an internal object
|
|
representing the session. However, if the proxy object was created, but the connection
|
|
could not be established for whatever reason, the error message can be obtained in
|
|
the regular way.</p>
|
|
|
|
<pre class="example">
|
|
typedef void * statement_handle;
|
|
statement_handle soci_create_statement(session_handle s);
|
|
void soci_destroy_statement(statement_handle st);
|
|
|
|
int soci_statement_state(statement_handle s);
|
|
char const * soci_statement_error_message(statement_handle s);
|
|
</pre>
|
|
|
|
<p>The functions above create and destroy the statement object. If the statement cannot
|
|
be created by the <code>soci_create_statement</code> function, the error condition is set up in the related session object;
|
|
for all other functions the error condition is set in the statement object itself.</p>
|
|
|
|
<pre class="example">
|
|
int soci_into_string (statement_handle st);
|
|
int soci_into_int (statement_handle st);
|
|
int soci_into_long_long(statement_handle st);
|
|
int soci_into_double (statement_handle st);
|
|
int soci_into_date (statement_handle st);
|
|
|
|
int soci_into_string_v (statement_handle st);
|
|
int soci_into_int_v (statement_handle st);
|
|
int soci_into_long_long_v(statement_handle st);
|
|
int soci_into_double_v (statement_handle st);
|
|
int soci_into_date_v (statement_handle st);
|
|
</pre>
|
|
|
|
<p>These functions create new data items for storing query results (<i>into elements</i>).
|
|
These elements can be later identified by their position, which is counted from 0. For convenience,
|
|
these function return the position of the currently added element. In case of error,
|
|
<code>-1</code> is returned and the error condition is set in the statement object.</p>
|
|
<p>The <code>_v</code> versions create a <code>vector</code> into elements, which can be used
|
|
to retrieve whole arrays of results.</p>
|
|
|
|
<pre class="example">
|
|
int soci_get_into_state(statement_handle st, int position);
|
|
int soci_get_into_state_v(statement_handle st, int position, int index);
|
|
</pre>
|
|
|
|
<p>This function returns <code>1</code> if the into element at the given position has non-null value and <code>0</code> otherwise.
|
|
The <code>_v</code> version works with <code>vector</code> elements and expects an array index.</p>
|
|
|
|
<pre class="example">
|
|
int soci_into_get_size_v(statement_handle st);
|
|
void soci_into_resize_v (statement_handle st, int new_size);
|
|
</pre>
|
|
|
|
<p>The functions above allow to get and set the size of vector into element.</p>
|
|
|
|
<p>Note: the <code>soci_into_resize_v</code> always sets <i>all</i> into vectors in the given statement
|
|
to the same size, which guarantees that all vector into elements have equal size.</p>
|
|
|
|
<pre class="example">
|
|
char const * soci_get_into_string (statement_handle st, int position);
|
|
int soci_get_into_int (statement_handle st, int position);
|
|
long long soci_get_into_long_long(statement_handle st, int position);
|
|
double soci_get_into_double (statement_handle st, int position);
|
|
char const * soci_get_into_date (statement_handle st, int position);
|
|
|
|
char const * soci_get_into_string_v (statement_handle st, int position, int index);
|
|
int soci_get_into_int_v (statement_handle st, int position, int index);
|
|
long long soci_get_into_long_long_v(statement_handle st, int position, int index);
|
|
double soci_get_into_double_v (statement_handle st, int position, int index);
|
|
char const * soci_get_into_date_v (statement_handle st, int position, int index);
|
|
</pre>
|
|
|
|
<p>The functions above allow to retrieve the current value of the given into element.</p>
|
|
|
|
<p>Note: the <code>date</code> function returns the date value in the "<code>YYYY MM DD HH mm ss</code>" string format.</p>
|
|
|
|
<pre class="example">
|
|
void soci_use_string (statement_handle st, char const * name);
|
|
void soci_use_int (statement_handle st, char const * name);
|
|
void soci_use_long_long(statement_handle st, char const * name);
|
|
void soci_use_double (statement_handle st, char const * name);
|
|
void soci_use_date (statement_handle st, char const * name);
|
|
|
|
void soci_use_string_v (statement_handle st, char const * name);
|
|
void soci_use_int_v (statement_handle st, char const * name);
|
|
void soci_use_long_long_v(statement_handle st, char const * name);
|
|
void soci_use_double_v (statement_handle st, char const * name);
|
|
void soci_use_date_v (statement_handle st, char const * name);
|
|
</pre>
|
|
|
|
<p>The functions above allow to create new data elements that will be used to provide
|
|
data to the query (<i>use elements</i>). The new elements can be later identified by given name, which
|
|
must be unique for the given statement.</p>
|
|
|
|
<pre class="example">
|
|
void soci_set_use_state(statement_handle st, char const * name, int state);
|
|
</pre>
|
|
|
|
<p>The <code>soci_set_use_state</code> function allows to set the state of the given use element.
|
|
If the <code>state</code> parameter is set to non-zero the use element is considered non-null
|
|
(which is also the default state after creating the use element).</p>
|
|
|
|
<pre class="example">
|
|
int soci_use_get_size_v(statement_handle st);
|
|
void soci_use_resize_v (statement_handle st, int new_size);
|
|
</pre>
|
|
|
|
<p>These functions get and set the size of vector use elements (see comments for vector into elements above).</p>
|
|
|
|
<pre class="example">
|
|
void soci_set_use_string (statement_handle st, char const * name, char const * val);
|
|
void soci_set_use_int (statement_handle st, char const * name, int val);
|
|
void soci_set_use_long_long(statement_handle st, char const * name, long long val);
|
|
void soci_set_use_double (statement_handle st, char const * name, double val);
|
|
void soci_set_use_date (statement_handle st, char const * name, char const * val);
|
|
|
|
void soci_set_use_state_v (statement_handle st, char const * name, int index, int state);
|
|
void soci_set_use_string_v (statement_handle st, char const * name, int index, char const * val);
|
|
void soci_set_use_int_v (statement_handle st, char const * name, int index, int val);
|
|
void soci_set_use_long_long_v(statement_handle st, char const * name, int index, long long val);
|
|
void soci_set_use_double_v (statement_handle st, char const * name, int index, double val);
|
|
void soci_set_use_date_v (statement_handle st, char const * name, int index, char const * val);
|
|
</pre>
|
|
|
|
<p>The functions above set the value of the given use element, for both single and vector elements.</p>
|
|
|
|
<p>Note: the expected format for the data values is "<code>YYYY MM DD HH mm ss</code>".</p>
|
|
|
|
<pre class="example">
|
|
int soci_get_use_state (statement_handle st, char const * name);
|
|
char const * soci_get_use_string (statement_handle st, char const * name);
|
|
int soci_get_use_int (statement_handle st, char const * name);
|
|
long long soci_get_use_long_long(statement_handle st, char const * name);
|
|
double soci_get_use_double (statement_handle st, char const * name);
|
|
char const * soci_get_use_date (statement_handle st, char const * name);
|
|
</pre>
|
|
|
|
<p>These functions allow to inspect the state and value of named use elements.</p>
|
|
<p>Note: these functions are provide only for single use elements, not for vectors;
|
|
the rationale for this is that modifiable use elements are not supported for bulk operations.</p>
|
|
|
|
<pre class="example">
|
|
void soci_prepare(statement_handle st, char const * query);
|
|
int soci_execute(statement_handle st, int withDataExchange);
|
|
int soci_fetch(statement_handle st);
|
|
int soci_got_data(statement_handle st);
|
|
</pre>
|
|
|
|
<p>The functions above provide the core execution functionality for the statement object
|
|
and their meaning is equivalent to the respective functions in the core C++ interface
|
|
described above.</p>
|
|
|
|
<table class="foot-links" border="0" cellpadding="2" cellspacing="2">
|
|
<tr>
|
|
<td class="foot-link-left">
|
|
<a href="beyond.html">Previous (Beyond standard SQL)</a>
|
|
</td>
|
|
<td class="foot-link-right">
|
|
<a href="backends.html">Next (Backends reference)</a>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p class="copyright">Copyright © 2013 Mateusz Loskot</p>
|
|
<p class="copyright">Copyright © 2012 Vadim Zeitlin</p>
|
|
<p class="copyright">Copyright © 2004-2006 Maciej Sobczak, Stephen Hutton</p>
|
|
</body>
|
|
</html>
|