mirror of
https://github.com/SOCI/soci.git
synced 2026-01-06 05:00:33 -06:00
[docs] Replace HTML tables with Markdown tables
Use fenced code blocks with language specification. Update database/os/compiler tables for some backends.
This commit is contained in:
Mateusz Loskot
@@ -1,88 +1,103 @@
|
||||
# Backends reference
|
||||
|
||||
This part of the documentation is provided for those who want towrite (and contribute!) their own backends.
|
||||
It is anyway recommendedthat authors of new backend see the code of some existing backend forhints on how things are really done.
|
||||
This part of the documentation is provided for those who want towrite (and contribute!) their
|
||||
own backends. It is anyway recommendedthat authors of new backend see the code of some existing
|
||||
backend forhints on how things are really done.
|
||||
|
||||
The backend interface is a set of base classes that the actual backendsare supposed to specialize.
|
||||
The main SOCI interface uses only theinterface and respecting the protocol (for example, the order offunction calls) described here.
|
||||
Note that both the interface and theprotocol were initially designed with the Oracle database in mind, which means that whereas it is quite natural with respect to the way Oracle API (OCI) works, it might impose some implementation burden on otherbackends, where things are done differently and therefore have to beadjusted, cached, converted, etc.
|
||||
The main SOCI interface uses only theinterface and respecting the protocol (for example,
|
||||
the order of function calls) described here.
|
||||
Note that both the interface and theprotocol were initially designed with the Oracle database in
|
||||
mind, which means that whereas it is quite natural with respect to the way Oracle API (OCI) works,
|
||||
it might impose some implementation burden on otherbackends, where things are done differently
|
||||
and therefore have to beadjusted, cached, converted, etc.
|
||||
|
||||
The interface to the common SOCI interface is defined in the `core/soci-backend.h` header file.
|
||||
This file is dissected below.
|
||||
|
||||
All names are defined in either `soci` or `soci::details` namespace.
|
||||
|
||||
// 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
|
||||
};
|
||||
```cpp
|
||||
// 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 enum type for indicator variables
|
||||
enum indicator { i_ok, i_null, i_truncated };
|
||||
|
||||
// data types, as used to describe exchange format
|
||||
enum exchange_type
|
||||
{
|
||||
x_char,
|
||||
x_stdstring,
|
||||
x_short,
|
||||
x_integer,
|
||||
x_long_long,
|
||||
x_unsigned_long_long,
|
||||
x_double,
|
||||
x_stdtm,
|
||||
x_statement,
|
||||
x_rowid,
|
||||
x_blob
|
||||
};
|
||||
// data types, as used to describe exchange format
|
||||
enum exchange_type
|
||||
{
|
||||
x_char,
|
||||
x_stdstring,
|
||||
x_short,
|
||||
x_integer,
|
||||
x_long_long,
|
||||
x_unsigned_long_long,
|
||||
x_double,
|
||||
x_stdtm,
|
||||
x_statement,
|
||||
x_rowid,
|
||||
x_blob
|
||||
};
|
||||
|
||||
struct cstring_descriptor
|
||||
{
|
||||
cstring_descriptor(char * str, std::size_t bufSize)
|
||||
: str_(str), bufSize_(bufSize) {}
|
||||
struct cstring_descriptor
|
||||
{
|
||||
cstring_descriptor(char * str, std::size_t bufSize)
|
||||
: str_(str), bufSize_(bufSize) {}
|
||||
|
||||
char * str_;
|
||||
std::size_t bufSize_;
|
||||
};
|
||||
char * str_;
|
||||
std::size_t bufSize_;
|
||||
};
|
||||
|
||||
// actually in error.h:
|
||||
class soci_error : public std::runtime_error
|
||||
{
|
||||
public:
|
||||
soci_error(std::string const & msg);
|
||||
};
|
||||
// actually in error.h:
|
||||
class soci_error : public std::runtime_error
|
||||
{
|
||||
public:
|
||||
soci_error(std::string const & msg);
|
||||
};
|
||||
```
|
||||
|
||||
The `data_type` enumeration type defines all types that form the core type support for SOCI.
|
||||
The enum itself can be used by clients when dealing with dynamic rowset description.
|
||||
|
||||
The `indicator` enumeration type defines all recognized *states* of data.
|
||||
The `i_truncated` state is provided for the case where the string is retrieved from the database into the char buffer that is not long enough to hold the whole value.
|
||||
The `i_truncated` state is provided for the case where the string is retrieved from the database
|
||||
into the char buffer that is not long enough to hold the whole value.
|
||||
|
||||
The `exchange_type` enumeration type defines all possible types that can be used with the `into` and `use` elements.
|
||||
The `exchange_type` enumeration type defines all possible types that can be used
|
||||
with the `into` and `use` elements.
|
||||
|
||||
The `cstring_descriptor` is a helper class that allows to store the address of `char` buffer together with its size.
|
||||
The `cstring_descriptor` is a helper class that allows to store the address of `char` buffer
|
||||
together with its size.
|
||||
The objects of this class are passed to the backend when the `x_cstring` type is involved.
|
||||
|
||||
The `soci_error` class is an exception type used for database-related (and also usage-related) errors.
|
||||
The backends should throw exceptions of this or derived type only.
|
||||
|
||||
class standard_into_type_backend
|
||||
{
|
||||
public:
|
||||
standard_into_type_backend() {}
|
||||
virtual ~standard_into_type_backend() {}
|
||||
```cpp
|
||||
class standard_into_type_backend
|
||||
{
|
||||
public:
|
||||
standard_into_type_backend() {}
|
||||
virtual ~standard_into_type_backend() {}
|
||||
|
||||
virtual void define_by_pos(int& position, void* data, exchange_type type) = 0;
|
||||
virtual void define_by_pos(int& position, void* data, exchange_type type) = 0;
|
||||
|
||||
virtual void pre_fetch() = 0;
|
||||
virtual void post_fetch(bool gotData, bool calledFromFetch, indicator* ind) = 0;
|
||||
virtual void pre_fetch() = 0;
|
||||
virtual void post_fetch(bool gotData, bool calledFromFetch, indicator* ind) = 0;
|
||||
|
||||
virtual void clean_up() = 0;
|
||||
};
|
||||
virtual void clean_up() = 0;
|
||||
};
|
||||
```
|
||||
|
||||
The `standard_into_type_back_end` class implements the dynamic interactions with the simple (non-bulk) `into` elements.
|
||||
The objects of this class (or, rather, of the derived class implemented by the actual backend) are created by the `statement` object when the `into` element is bound - in terms of lifetime management, `statement` is the master of this class.
|
||||
The `standard_into_type_back_end` class implements the dynamic interactions with the simple
|
||||
(non-bulk) `into` elements.
|
||||
The objects of this class (or, rather, of the derived class implemented by the actual backend)
|
||||
are created by the `statement` object when the `into` element is bound - in terms of lifetime
|
||||
management, `statement` is the master of this class.
|
||||
|
||||
* `define_by_pos` - Called when the `into` element is bound, once and before the statement is executed. The `data` pointer points to the variable used for `into` element (or to the `cstring_descriptor` object, which is artificially created when the plain `char` buffer is used for data exchange). The `position` parameter is a "column number", assigned by the library. The backend should increase this parameter, according to the number of fields actually taken (usually 1).
|
||||
* `pre_fetch` - Called before each row is fetched.
|
||||
@@ -92,22 +107,24 @@ The objects of this class (or, rather, of the derived class implemented by the a
|
||||
The intended use of `pre_fetch` and `post_fetch` functions is to manage any internal buffer and/or data conversion foreach value retrieved from the database.
|
||||
If the given server supportsbinary data transmission and the data format for the given type agreeswith what is used on the client machine, then these two functions neednot do anything; otherwise buffer management and data conversionsshould go there.
|
||||
|
||||
class vector_into_type_backend
|
||||
{
|
||||
public:
|
||||
vector_into_type_backend() {}
|
||||
virtual ~vector_into_type_backend() {}
|
||||
```cpp
|
||||
class vector_into_type_backend
|
||||
{
|
||||
public:
|
||||
vector_into_type_backend() {}
|
||||
virtual ~vector_into_type_backend() {}
|
||||
|
||||
virtual void define_by_pos(int& position, void* data, exchange_type type) = 0;
|
||||
virtual void define_by_pos(int& position, void* data, exchange_type type) = 0;
|
||||
|
||||
virtual void pre_fetch() = 0;
|
||||
virtual void post_fetch(bool gotData, indicator* ind) = 0;
|
||||
virtual void pre_fetch() = 0;
|
||||
virtual void post_fetch(bool gotData, indicator* ind) = 0;
|
||||
|
||||
virtual void resize(std::size_t sz) = 0;
|
||||
virtual std::size_t size() = 0;
|
||||
virtual void resize(std::size_t sz) = 0;
|
||||
virtual std::size_t size() = 0;
|
||||
|
||||
virtual void clean_up() = 0;
|
||||
};
|
||||
virtual void clean_up() = 0;
|
||||
};
|
||||
```
|
||||
|
||||
The `vector_into_type_back_end` has similar structure and purpose as the previous one, but is used for vectors (bulk data retrieval).
|
||||
|
||||
@@ -116,70 +133,73 @@ The important difference with regard to the previous class is that `ind` points
|
||||
The backend should fill this array according to the actual state of the retrieved data.
|
||||
|
||||
* `bind_by_pos` - Called for each `use` element, once and before the statement is executed - for those `use` elements that do not provide explicit names for parameter binding. The meaning of parameters is same as in previous classes.
|
||||
* `bind_by_name` - Called for those `use` elements that provide the explicit name.
|
||||
* `bind_by_name` - Called for those `use` elements that provide the explicit name.
|
||||
* `pre_use` - Called before the data is transmitted to the server (this means before the statement is executed, which can happen many times for the prepared statement). `ind` points to the indicator provided by the user (or is `NULL`).
|
||||
* `post_use` - Called after statement execution. `gotData` and `ind` have the same meaning as in `standard_into_type_back_end::post_fetch`, and this can be used by those backends whose respective servers support two-way data exchange (like in/out parameters in stored procedures).
|
||||
|
||||
The intended use for `pre_use` and `post_use` methods is to manage any internal buffers and/or data conversion.
|
||||
They can be called many times with the same statement.
|
||||
|
||||
class vector_use_type_backend
|
||||
{
|
||||
public:
|
||||
virtual ~vector_use_type_backend() {}
|
||||
```cpp
|
||||
class vector_use_type_backend
|
||||
{
|
||||
public:
|
||||
virtual ~vector_use_type_backend() {}
|
||||
|
||||
virtual void bind_by_pos(int& position,
|
||||
void* data, exchange_type type) = 0;
|
||||
virtual void bind_by_name(std::string const& name,
|
||||
void* data, exchange_type type) = 0;
|
||||
virtual void bind_by_pos(int& position,
|
||||
void* data, exchange_type type) = 0;
|
||||
virtual void bind_by_name(std::string const& name,
|
||||
void* data, exchange_type type) = 0;
|
||||
|
||||
virtual void pre_use(indicator const* ind) = 0;
|
||||
virtual void pre_use(indicator const* ind) = 0;
|
||||
|
||||
virtual std::size_t size() = 0;
|
||||
|
||||
virtual void clean_up() = 0;
|
||||
};
|
||||
virtual std::size_t size() = 0;
|
||||
|
||||
virtual void clean_up() = 0;
|
||||
};
|
||||
```
|
||||
|
||||
Objects of this type (or rather of type derived from this one) are used to implement interactions with user-provided vector (bulk) `use` elements and are managed by the `statement` object.
|
||||
The `data` pointer points to the whole vector object provided by the user (and *not* to its internal buffer); `ind` points to the beginning of the array of indicators (or is `NULL`).
|
||||
The meaning of this interface is analogous to those presented above.
|
||||
|
||||
class statement_backend
|
||||
```cpp
|
||||
class statement_backend
|
||||
{
|
||||
public:
|
||||
statement_backend() {}
|
||||
virtual ~statement_backend() {}
|
||||
|
||||
virtual void alloc() = 0;
|
||||
virtual void clean_up() = 0;
|
||||
|
||||
virtual void prepare(std::string const& query, statement_type eType) = 0;
|
||||
|
||||
enum exec_fetch_result
|
||||
{
|
||||
public:
|
||||
statement_backend() {}
|
||||
virtual ~statement_backend() {}
|
||||
|
||||
virtual void alloc() = 0;
|
||||
virtual void clean_up() = 0;
|
||||
|
||||
virtual void prepare(std::string const& query, statement_type eType) = 0;
|
||||
|
||||
enum exec_fetch_result
|
||||
{
|
||||
ef_success,
|
||||
ef_no_data
|
||||
};
|
||||
|
||||
virtual exec_fetch_result execute(int number) = 0;
|
||||
virtual exec_fetch_result fetch(int number) = 0;
|
||||
|
||||
virtual long long get_affected_rows() = 0;
|
||||
virtual int get_number_of_rows() = 0;
|
||||
|
||||
virtual std::string rewrite_for_procedure_call(std::string const& query) = 0;
|
||||
|
||||
virtual int prepare_for_describe() = 0;
|
||||
virtual void describe_column(int colNum, data_type& dtype,
|
||||
std::string& column_name) = 0;
|
||||
|
||||
virtual standard_into_type_backend* make_into_type_backend() = 0;
|
||||
virtual standard_use_type_backend* make_use_type_backend() = 0;
|
||||
virtual vector_into_type_backend* make_vector_into_type_backend() = 0;
|
||||
virtual vector_use_type_backend* make_vector_use_type_backend() = 0;
|
||||
ef_success,
|
||||
ef_no_data
|
||||
};
|
||||
|
||||
virtual exec_fetch_result execute(int number) = 0;
|
||||
virtual exec_fetch_result fetch(int number) = 0;
|
||||
|
||||
virtual long long get_affected_rows() = 0;
|
||||
virtual int get_number_of_rows() = 0;
|
||||
|
||||
virtual std::string rewrite_for_procedure_call(std::string const& query) = 0;
|
||||
|
||||
virtual int prepare_for_describe() = 0;
|
||||
virtual void describe_column(int colNum, data_type& dtype,
|
||||
std::string& column_name) = 0;
|
||||
|
||||
virtual standard_into_type_backend* make_into_type_backend() = 0;
|
||||
virtual standard_use_type_backend* make_use_type_backend() = 0;
|
||||
virtual vector_into_type_backend* make_vector_into_type_backend() = 0;
|
||||
virtual vector_use_type_backend* make_vector_use_type_backend() = 0;
|
||||
};
|
||||
```
|
||||
|
||||
The `statement_backend` type implements the internals of the `statement` objects.
|
||||
The objects of this class are created by the `session` object.
|
||||
|
||||
@@ -200,48 +220,54 @@ The objects of this class are created by the `session` object.
|
||||
1. Whether the query is executed using the simple one-time syntax or is prepared, the `alloc`, `prepare` and `execute` functions are always called, in this order.
|
||||
2. All `into` and `use` elements are bound (their `define_by_pos` or `bind_by_pos`/`bind_by_name` functions are called) *between* statement preparation and execution.
|
||||
|
||||
class rowid_backend
|
||||
{
|
||||
public:
|
||||
virtual ~rowid_backend() {}
|
||||
};
|
||||
```cpp
|
||||
class rowid_backend
|
||||
{
|
||||
public:
|
||||
virtual ~rowid_backend() {}
|
||||
};
|
||||
```
|
||||
|
||||
The `rowid_backend` class is a hook for the backends to provide their own state for the row identifier. It has no functions, since the only portable interaction with the row identifier object is to use it with `into` and `use` elements.
|
||||
|
||||
class blob_backend
|
||||
{
|
||||
public:
|
||||
virtual ~blob_backend() {}
|
||||
```cpp
|
||||
class blob_backend
|
||||
{
|
||||
public:
|
||||
virtual ~blob_backend() {}
|
||||
|
||||
virtual std::size_t get_len() = 0;
|
||||
virtual std::size_t read(std::size_t offset, char * buf,
|
||||
std::size_t toRead) = 0;
|
||||
virtual std::size_t write(std::size_t offset, char const * buf,
|
||||
std::size_t toWrite) = 0;
|
||||
virtual std::size_t append(char const * buf, std::size_t toWrite) = 0;
|
||||
virtual void trim(std::size_t newLen) = 0;
|
||||
};
|
||||
virtual std::size_t get_len() = 0;
|
||||
virtual std::size_t read(std::size_t offset, char * buf,
|
||||
std::size_t toRead) = 0;
|
||||
virtual std::size_t write(std::size_t offset, char const * buf,
|
||||
std::size_t toWrite) = 0;
|
||||
virtual std::size_t append(char const * buf, std::size_t toWrite) = 0;
|
||||
virtual void trim(std::size_t newLen) = 0;
|
||||
};
|
||||
```
|
||||
|
||||
The `blob_backend` interface provides the entry points for the `blob` methods.
|
||||
|
||||
class session_backend
|
||||
{
|
||||
public:
|
||||
virtual ~session_backend() {}
|
||||
```cpp
|
||||
class session_backend
|
||||
{
|
||||
public:
|
||||
virtual ~session_backend() {}
|
||||
|
||||
virtual void begin() = 0;
|
||||
virtual void commit() = 0;
|
||||
virtual void rollback() = 0;
|
||||
virtual void begin() = 0;
|
||||
virtual void commit() = 0;
|
||||
virtual void rollback() = 0;
|
||||
|
||||
virtual bool get_next_sequence_value(session&, std::string const&, long&);
|
||||
virtual bool get_last_insert_id(session&, std::string const&, long&);
|
||||
virtual bool get_next_sequence_value(session&, std::string const&, long&);
|
||||
virtual bool get_last_insert_id(session&, std::string const&, long&);
|
||||
|
||||
virtual std::string get_backend_name() const = 0;
|
||||
virtual std::string get_backend_name() const = 0;
|
||||
|
||||
virtual statement_backend * make_statement_backend() = 0;
|
||||
virtual rowid_backend * make_rowid_backend() = 0;
|
||||
virtual blob_backend * make_blob_backend() = 0;
|
||||
};
|
||||
virtual statement_backend * make_statement_backend() = 0;
|
||||
virtual rowid_backend * make_rowid_backend() = 0;
|
||||
virtual blob_backend * make_blob_backend() = 0;
|
||||
};
|
||||
```
|
||||
|
||||
The object of the class derived from `session_backend` implements the internals of the `session` object.
|
||||
|
||||
@@ -249,13 +275,15 @@ The object of the class derived from `session_backend` implements the internals
|
||||
* `get_next_sequence_value`, `get_last_insert_id` - Called to retrieve sequences or auto-generated values and every backend should define at least one of them to allow the code using auto-generated values to work.
|
||||
* `make_statement_backend`, `make_rowid_backend`, `make_blob_backend` - Called to create respective implementations for the `statement`, `rowid` and `blob` classes.
|
||||
|
||||
struct backend_factory
|
||||
{
|
||||
virtual ~backend_factory() {}
|
||||
```cpp
|
||||
struct backend_factory
|
||||
{
|
||||
virtual ~backend_factory() {}
|
||||
|
||||
virtual details::session_backend * make_session(
|
||||
std::string const& connectString) const = 0;
|
||||
};
|
||||
virtual details::session_backend * make_session(
|
||||
std::string const& connectString) const = 0;
|
||||
};
|
||||
```
|
||||
|
||||
The `backend_factory` is a base class for backend-provided factory class that is able to create valid sessions. The `connectString` parameter passed to `make_session` is provided here by the `session` constructor and contains only the backend-related parameters, without the backend name (if the dynamic backend loading is used).
|
||||
|
||||
@@ -263,21 +291,23 @@ The actual backend factory object is supposed to be provided by the backend impl
|
||||
|
||||
The following example is taken from `soci-postgresql.h`, which declares entities of the PostgreSQL backend:
|
||||
|
||||
struct postgresql_backend_factory : backend_factory
|
||||
{
|
||||
virtual postgresql_session_backend* make_session(
|
||||
std::string const& connectString) const;
|
||||
};
|
||||
extern postgresql_backend_factory const postgresql;
|
||||
```cpp
|
||||
struct postgresql_backend_factory : backend_factory
|
||||
{
|
||||
virtual postgresql_session_backend* make_session(
|
||||
std::string const& connectString) const;
|
||||
};
|
||||
extern postgresql_backend_factory const postgresql;
|
||||
|
||||
extern "C"
|
||||
{
|
||||
extern "C"
|
||||
{
|
||||
|
||||
// for dynamic backend loading
|
||||
backend_factory const * factory_postgresql();
|
||||
// for dynamic backend loading
|
||||
backend_factory const * factory_postgresql();
|
||||
|
||||
} // extern "C"
|
||||
} // extern "C"
|
||||
```
|
||||
|
||||
With the above declarations, it is enough to pass the `postgresql` factory name to the constructor of the `session` object, which will use this factory to create concrete implementations for any other objects that are needed, with the help of appropriate `make_XYZ` functions. Alternatively, the `factory_postgresql` function will be called automatically by the backend loader if the backend name is provided at run-time instead.
|
||||
|
||||
Note that the backend source code is placed in the `backends/*name*` directory (for example, `backends/oracle`) and the test driver is in `backends/*name*/test`. There is also `backends/empty` directory provided as a skeleton for development of new backends and their tests. It is recommended that all backends respect naming conventions by just appending their name to the base-class names. The backend name used for the global factory object should clearly identify the given database engine, like `oracle`, `postgresql`, `mysql`, and so on.
|
||||
Note that the backend source code is placed in the `backends/*name*` directory (for example, `backends/oracle`) and the test driver is in `backends/*name*/test`. There is also `backends/empty` directory provided as a skeleton for development of new backends and their tests. It is recommended that all backends respect naming conventions by just appending their name to the base-class names. The backend name used for the global factory object should clearly identify the given database engine, like `oracle`, `postgresql`, `mysql`, and so on.
|
||||
|
||||
@@ -11,14 +11,16 @@ Types related to the backend interface are named here.
|
||||
|
||||
The following types are commonly used in the rest of the interface:
|
||||
|
||||
// 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 };
|
||||
```cpp
|
||||
// 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 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 { /* ... */ };
|
||||
// the type used for reporting exceptions
|
||||
class soci_error : public std::runtime_error { /* ... */ };
|
||||
```
|
||||
|
||||
The `data_type` type defines the basic SOCI data types. User provided data types need to be associated with one of these basic types.
|
||||
|
||||
@@ -26,84 +28,93 @@ The `indicator` type defines the possible states of data.
|
||||
|
||||
The `soci_error` type is used for error reporting.
|
||||
|
||||
|
||||
## class session
|
||||
|
||||
The `session` class encapsulates the connection to the database.
|
||||
|
||||
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);
|
||||
```cpp
|
||||
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();
|
||||
~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 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();
|
||||
void begin();
|
||||
void commit();
|
||||
void rollback();
|
||||
|
||||
*IT* once;
|
||||
*IT* prepare;
|
||||
*IT* once;
|
||||
*IT* prepare;
|
||||
|
||||
template <typename T> *IT* operator<<(T const & t);
|
||||
template <typename T> *IT* operator<<(T const & t);
|
||||
|
||||
bool got_data() const;
|
||||
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);
|
||||
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();
|
||||
std::ostringstream & get_query_stream();
|
||||
|
||||
void set_log_stream(std::ostream * s);
|
||||
std::ostream * get_log_stream() const;
|
||||
void set_log_stream(std::ostream * s);
|
||||
std::ostream * get_log_stream() const;
|
||||
|
||||
std::string get_last_query() const;
|
||||
std::string get_last_query() const;
|
||||
|
||||
void uppercase_column_names(bool forceToUpper);
|
||||
void uppercase_column_names(bool forceToUpper);
|
||||
|
||||
std::string get_dummy_from_table() const;
|
||||
std::string get_dummy_from_clause() const;
|
||||
std::string get_dummy_from_table() const;
|
||||
std::string get_dummy_from_clause() const;
|
||||
|
||||
details::session_backend * get_backend();
|
||||
details::session_backend * get_backend();
|
||||
|
||||
std::string get_backend_name() const;
|
||||
};
|
||||
std::string get_backend_name() const;
|
||||
};
|
||||
```
|
||||
|
||||
This class contains the following members:
|
||||
|
||||
* 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:
|
||||
|
||||
session sql(postgresql, "dbname=mydb");
|
||||
session sql("postgresql", "dbname=mydb");
|
||||
session sql("postgresql://dbname=mydb");
|
||||
```cpp
|
||||
session sql(postgresql, "dbname=mydb");
|
||||
session sql("postgresql", "dbname=mydb");
|
||||
session sql("postgresql://dbname=mydb");
|
||||
```
|
||||
|
||||
* The constructors that take backend name as string load the shared library (if not yet loaded) with name computed as `libsoci_ABC.so` (or `libsoci_ABC.dll` on Windows) where `ABC` is the given backend name.
|
||||
* `open`, `close` and `reconnect` functions for reusing the same session object many times; the `reconnect` function attempts to establish the connection with the same parameters as most recently used with constructor or `open`. The arguments for `open` are treated in the same way as for constructors.
|
||||
* `begin`, `commit` and `rollback` functions for transaction control.
|
||||
* `once` member, which is used for performing *instant* queries that do not need to be separately prepared. Example:
|
||||
|
||||
sql.once << "drop table persons";
|
||||
```cpp
|
||||
sql.once << "drop table persons";
|
||||
```
|
||||
|
||||
* `prepare` member, which is used for statement preparation - the result of the statement preparation must be provided to the constructor of the `statement` class. Example:
|
||||
|
||||
int i;
|
||||
statement st = (sql.prepare <<
|
||||
"insert into numbers(value) values(:val)", use(i));
|
||||
```cpp
|
||||
int i;
|
||||
statement st = (sql.prepare <<
|
||||
"insert into numbers(value) values(:val)", use(i));
|
||||
```
|
||||
|
||||
`operator<<` that is a shortcut forwarder to the equivalent operator of the `once` member. Example:
|
||||
|
||||
sql << "drop table persons";
|
||||
```cpp
|
||||
sql << "drop table persons";
|
||||
```
|
||||
|
||||
* `got_data` returns true if the last executed query had non-empty result.
|
||||
* `get_next_sequence_value` 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 `get_last_insert_id()` as explained in ["Working with sequences"](beyond.html#sequences) section.
|
||||
@@ -114,7 +125,7 @@ This class contains the following members:
|
||||
* `uppercase_column_names` 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).
|
||||
* `get_dummy_from_table` and `get_dummy_from_clause()`: helpers for writing portable DML statements, see [DML helpers](statement.html#dml) for more details.
|
||||
* `get_backend` 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.
|
||||
*`get_backend_name` is a convenience forwarder to the same function of the backend object.
|
||||
* `get_backend_name` is a convenience forwarder to the same function of the backend object.
|
||||
|
||||
See [Connections and simple queries](basics.html) for more examples.
|
||||
|
||||
@@ -122,19 +133,19 @@ See [Connections and simple queries](basics.html) for more examples.
|
||||
|
||||
The `connection_parameters` class is a simple container for the backend pointer, connection string and any other connection options. It is used together with `session` constructor and `open()` method.
|
||||
|
||||
```cpp
|
||||
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);
|
||||
|
||||
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
|
||||
};
|
||||
|
||||
void set_option(const char * name, std::string const & value);
|
||||
bool get_option(const char * name, std::string & value) const
|
||||
};
|
||||
```
|
||||
|
||||
The methods of this class are:
|
||||
|
||||
@@ -146,22 +157,24 @@ The methods of this class are:
|
||||
|
||||
The `connection_pool` 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.
|
||||
|
||||
class connection_pool
|
||||
{
|
||||
public:
|
||||
explicit connection_pool(std::size_t size);
|
||||
~connection_pool();
|
||||
```cpp
|
||||
class connection_pool
|
||||
{
|
||||
public:
|
||||
explicit connection_pool(std::size_t size);
|
||||
~connection_pool();
|
||||
|
||||
session & at(std::size_t pos);
|
||||
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);
|
||||
};
|
||||
std::size_t lease();
|
||||
bool try_lease(std::size_t & pos, int timeout);
|
||||
void give_back(std::size_t pos);
|
||||
};
|
||||
```
|
||||
|
||||
The operations of the pool are:
|
||||
|
||||
* Constructor that takes the intended size of the pool. After construction, the pool contains regular `session` objects in disconnected state.
|
||||
* Constructor that takes the intended size of the pool. After construction, the pool contains regular `session` objects in disconnected state.
|
||||
* `at` function that provides direct access to any given entryin the pool. This function is *non-synchronized*.
|
||||
* `lease` 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 *locked*.
|
||||
* `try_lease` acts like `lease`, but allows to set up a time-out (relative, in milliseconds) on waiting. Negative time-out value means no time-out. Returns `true` if the entry was obtained, in which case its position is written to the `pos` parametr, and `false` if no entry was available before the time-out.
|
||||
@@ -171,19 +184,21 @@ The operations of the pool are:
|
||||
|
||||
The class `transaction` 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 *if* the transaction was not explicitly committed before.
|
||||
|
||||
class transaction
|
||||
{
|
||||
public:
|
||||
explicit transaction(session & sql);
|
||||
```cpp
|
||||
class transaction
|
||||
{
|
||||
public:
|
||||
explicit transaction(session & sql);
|
||||
|
||||
~transaction();
|
||||
~transaction();
|
||||
|
||||
void commit();
|
||||
void rollback();
|
||||
void commit();
|
||||
void rollback();
|
||||
|
||||
private:
|
||||
// ...
|
||||
};
|
||||
private:
|
||||
// ...
|
||||
};
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
@@ -191,25 +206,29 @@ Note that objects of this class are not notified of other transaction related op
|
||||
|
||||
The function `into` is used for binding local output data (in other words, it defines where the results of the query are stored).
|
||||
|
||||
template <typename T>
|
||||
IT into(T & t);
|
||||
```cpp
|
||||
template <typename T>
|
||||
IT into(T & t);
|
||||
|
||||
template <typename T, typename T1>
|
||||
IT into(T & t, T1 p1);
|
||||
template <typename T, typename T1>
|
||||
IT into(T & t, T1 p1);
|
||||
|
||||
template <typename T>
|
||||
IT into(T & t, indicator & ind);
|
||||
template <typename T>
|
||||
IT into(T & t, indicator & ind);
|
||||
|
||||
template <typename T, typename T1>
|
||||
IT into(T & t, indicator & ind, T1 p1);
|
||||
template <typename T, typename T1>
|
||||
IT into(T & t, indicator & ind, T1 p1);
|
||||
|
||||
template <typename T>
|
||||
IT into(T & t, std::vector<indicator> & ind);
|
||||
template <typename T>
|
||||
IT into(T & t, std::vector<indicator> & ind);
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
int count;
|
||||
sql << "select count(*) from person", into(count);
|
||||
```cpp
|
||||
int count;
|
||||
sql << "select count(*) from person", into(count);
|
||||
```
|
||||
|
||||
See [Binding local dat](exchange.html#bind_local) for more examples
|
||||
|
||||
@@ -217,29 +236,32 @@ See [Binding local dat](exchange.html#bind_local) for more examples
|
||||
|
||||
The function `use` is used for binding local input data (in other words, it defines where the parameters of the query come from).
|
||||
|
||||
template <typename T>
|
||||
*IT* use(T & t);
|
||||
```cpp
|
||||
template <typename T>
|
||||
*IT* use(T & t);
|
||||
|
||||
template <typename T, typename T1>
|
||||
*IT* use(T & t, T1 p1);
|
||||
template <typename T, typename T1>
|
||||
*IT* use(T & t, T1 p1);
|
||||
|
||||
template <typename T>
|
||||
*IT* use(T & t, indicator & ind);
|
||||
template <typename T>
|
||||
*IT* use(T & t, indicator & ind);
|
||||
|
||||
template <typename T, typename T1>
|
||||
*IT* use(T & t, indicator & ind, T1 p1);
|
||||
template <typename T, typename T1>
|
||||
*IT* use(T & t, indicator & ind, T1 p1);
|
||||
|
||||
template <typename T>
|
||||
*IT* use(T & t, std::vector<indicator> const & ind);
|
||||
|
||||
template <typename T, typename T1>
|
||||
*IT* use(T & t, std::vector<indicator> const & ind, T1 p1);
|
||||
template <typename T>
|
||||
*IT* use(T & t, std::vector<indicator> const & ind);
|
||||
|
||||
template <typename T, typename T1>
|
||||
*IT* use(T & t, std::vector<indicator> const & ind, T1 p1);
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
int val = 7;
|
||||
sql << "insert into numbers(val) values(:val)", use(val);
|
||||
```cpp
|
||||
int val = 7;
|
||||
sql << "insert into numbers(val) values(:val)", use(val);
|
||||
```
|
||||
|
||||
See [Binding local data](exchange.html#bind_local) for more examples.
|
||||
|
||||
@@ -247,44 +269,48 @@ See [Binding local data](exchange.html#bind_local) for more examples.
|
||||
|
||||
The `statement` class encapsulates the prepared statement.
|
||||
|
||||
class statement
|
||||
{
|
||||
public:
|
||||
statement(session & s);
|
||||
statement(*IT* const & prep);
|
||||
~statement();
|
||||
```cpp
|
||||
class statement
|
||||
{
|
||||
public:
|
||||
statement(session & s);
|
||||
statement(*IT* const & prep);
|
||||
~statement();
|
||||
|
||||
statement(statement const & other);
|
||||
void operator=(statement const & other);
|
||||
statement(statement const & other);
|
||||
void operator=(statement const & other);
|
||||
|
||||
void alloc();
|
||||
void bind(values & v);
|
||||
void exchange(*IT* const & i);
|
||||
void exchange(*IT* const & u);
|
||||
void clean_up();
|
||||
void bind_clean_up();
|
||||
void alloc();
|
||||
void bind(values & v);
|
||||
void exchange(*IT* const & i);
|
||||
void exchange(*IT* const & u);
|
||||
void clean_up();
|
||||
void bind_clean_up();
|
||||
|
||||
void prepare(std::string const & query);
|
||||
void define_and_bind();
|
||||
void prepare(std::string const & query);
|
||||
void define_and_bind();
|
||||
|
||||
bool execute(bool withDataExchange = false);
|
||||
long long get_affected_rows();
|
||||
bool fetch();
|
||||
bool execute(bool withDataExchange = false);
|
||||
long long get_affected_rows();
|
||||
bool fetch();
|
||||
|
||||
bool got_data() const;
|
||||
bool got_data() const;
|
||||
|
||||
void describe();
|
||||
void set_row(row * r);
|
||||
void exchange_for_rowset(*IT* const & i);
|
||||
void describe();
|
||||
void set_row(row * r);
|
||||
void exchange_for_rowset(*IT* const & i);
|
||||
|
||||
details::statement_backend * get_backend();
|
||||
};
|
||||
details::statement_backend * get_backend();
|
||||
};
|
||||
```
|
||||
|
||||
This class contains the following members:
|
||||
|
||||
* Constructor accepting the `session` object. This can be used for later query preparation. Example:
|
||||
|
||||
statement stmt(sql);
|
||||
```cpp
|
||||
statement stmt(sql);
|
||||
```
|
||||
|
||||
* Constructor accepting the result of using `prepare` on the `session` object, see example provided above for the `session` class.
|
||||
* Copy operations.
|
||||
@@ -312,15 +338,17 @@ Most of the functions from the `statement` class interface are called automatica
|
||||
|
||||
The `procedure` class encapsulates the call to the stored procedure and is aimed for higher portability of the client code.
|
||||
|
||||
class procedure
|
||||
{
|
||||
public:
|
||||
procedure(*IT* const & prep);
|
||||
```cpp
|
||||
class procedure
|
||||
{
|
||||
public:
|
||||
procedure(*IT* const & prep);
|
||||
|
||||
bool execute(bool withDataExchange = false);
|
||||
bool fetch();
|
||||
bool got_data() const;
|
||||
};
|
||||
bool execute(bool withDataExchange = false);
|
||||
bool fetch();
|
||||
bool got_data() const;
|
||||
};
|
||||
```
|
||||
|
||||
The constructor expects the result of using `prepare` on the `session` object.
|
||||
|
||||
@@ -330,15 +358,17 @@ See [Stored procedures](statements.html#procedures) for examples.
|
||||
|
||||
The `type_conversion` 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.
|
||||
|
||||
template <typename T>
|
||||
struct type_conversion
|
||||
{
|
||||
typedef T base_type;
|
||||
```cpp
|
||||
template <typename T>
|
||||
struct type_conversion
|
||||
{
|
||||
typedef T base_type;
|
||||
|
||||
static void from_base(base_type const & in, indicator ind, T & out);
|
||||
static void from_base(base_type const & in, indicator ind, T & out);
|
||||
|
||||
static void to_base(T const & in, base_type & out, indicator & ind);
|
||||
};
|
||||
static void to_base(T const & in, base_type & out, indicator & ind);
|
||||
};
|
||||
```
|
||||
|
||||
Users are supposed to properly implement the `from_base` and `to_base` functions in their specializations of this template class.
|
||||
|
||||
@@ -348,41 +378,43 @@ See [Extending SOCI to support custom (user-defined) C++ types](exchange.html#cu
|
||||
|
||||
The `row` class encapsulates the data and type information retrieved for the single row when the dynamic rowset binding is used.
|
||||
|
||||
class row
|
||||
{
|
||||
public:
|
||||
row();
|
||||
~row();
|
||||
```cpp
|
||||
class row
|
||||
{
|
||||
public:
|
||||
row();
|
||||
~row();
|
||||
|
||||
void uppercase_column_names(bool forceToUpper);
|
||||
void uppercase_column_names(bool forceToUpper);
|
||||
|
||||
std::size_t size() const;
|
||||
std::size_t size() const;
|
||||
|
||||
indicator get_indicator(std::size_t pos) const;
|
||||
indicator get_indicator(std::string const & name) 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;
|
||||
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) const;
|
||||
|
||||
template <typename T>
|
||||
T get(std::size_t pos, T const & nullValue) 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) const;
|
||||
|
||||
template <typename T>
|
||||
T get(std::string const & name, T const & nullValue) const;
|
||||
template <typename T>
|
||||
T get(std::string const & name, T const & nullValue) const;
|
||||
|
||||
template <typename T>
|
||||
row const & operator>>(T & value) const;
|
||||
template <typename T>
|
||||
row const & operator>>(T & value) const;
|
||||
|
||||
void skip(std::size_t num = 1) const;
|
||||
void skip(std::size_t num = 1) const;
|
||||
|
||||
void reset_get_counter() const
|
||||
};
|
||||
void reset_get_counter() const
|
||||
};
|
||||
```
|
||||
|
||||
This class contains the following members:
|
||||
|
||||
@@ -401,12 +433,14 @@ See [Dynamic resultset binding](exchange.html#dynamic) for examples.
|
||||
|
||||
The `column_properties` class provides the type and name information about the particular column in a rowset.
|
||||
|
||||
class column_properties
|
||||
{
|
||||
public:
|
||||
std::string get_name() const;
|
||||
data_type get_data_type() const;
|
||||
};
|
||||
```cpp
|
||||
class column_properties
|
||||
{
|
||||
public:
|
||||
std::string get_name() const;
|
||||
data_type get_data_type() const;
|
||||
};
|
||||
```
|
||||
|
||||
This class contains the following members:
|
||||
|
||||
@@ -419,43 +453,45 @@ See [Dynamic resultset binding](exchange.html#dynamic) for examples.
|
||||
|
||||
The `values` class encapsulates the data and type information and is used for object-relational mapping.
|
||||
|
||||
class values
|
||||
{
|
||||
public:
|
||||
values();
|
||||
```cpp
|
||||
class values
|
||||
{
|
||||
public:
|
||||
values();
|
||||
|
||||
void uppercase_column_names(bool forceToUpper);
|
||||
void uppercase_column_names(bool forceToUpper);
|
||||
|
||||
indicator get_indicator(std::size_t pos) const;
|
||||
indicator get_indicator(std::string const & name) const;
|
||||
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) const;
|
||||
|
||||
template <typename T>
|
||||
T get(std::size_t pos, T const & nullValue) 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) const;
|
||||
|
||||
template <typename T>
|
||||
T get(std::string const & name, T const & nullValue) const;
|
||||
template <typename T>
|
||||
T get(std::string const & name, T const & nullValue) const;
|
||||
|
||||
template <typename T>
|
||||
values const & operator>>(T & value) const;
|
||||
template <typename T>
|
||||
values const & operator>>(T & value) const;
|
||||
|
||||
void skip(std::size_t num = 1) const;
|
||||
void reset_get_counter() 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(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>
|
||||
void set(const T & value, indicator indic = i_ok);
|
||||
|
||||
template <typename T>
|
||||
values & operator<<(T const & value);
|
||||
};
|
||||
template <typename T>
|
||||
values & operator<<(T const & value);
|
||||
};
|
||||
```
|
||||
|
||||
This class contains the same members as the `row` class (with the same meaning) plus:
|
||||
|
||||
@@ -468,20 +504,22 @@ See [Object-relational mapping](exchange.html#object_relational) for examples.
|
||||
|
||||
The `blob` class encapsulates the "large object" functionality.
|
||||
|
||||
class blob
|
||||
{
|
||||
public:
|
||||
explicit blob(session & s);
|
||||
~blob();
|
||||
```cpp
|
||||
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);
|
||||
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();
|
||||
};
|
||||
details::blob_backend * get_backend();
|
||||
};
|
||||
```
|
||||
|
||||
This class contains the following members:
|
||||
|
||||
@@ -499,39 +537,44 @@ See [Large objects (BLOBs)](exchange.html#blob) for more discussion.
|
||||
|
||||
The `rowid` class encapsulates the "row identifier" object.
|
||||
|
||||
class rowid
|
||||
{
|
||||
public:
|
||||
explicit rowid(Session & s);
|
||||
~rowid();
|
||||
```cpp
|
||||
class rowid
|
||||
{
|
||||
public:
|
||||
explicit rowid(Session & s);
|
||||
~rowid();
|
||||
|
||||
details::rowid_backend * get_backend();
|
||||
};
|
||||
details::rowid_backend * get_backend();
|
||||
};
|
||||
```
|
||||
|
||||
This class contains the following members:
|
||||
|
||||
* Constructor associating the `rowid` object with the `session` object.
|
||||
* `get_backend` function that returns the internal pointer to the concrete backend implementation of the `rowid` object.
|
||||
|
||||
|
||||
## class backend_factory
|
||||
|
||||
The `backend_factory` class provides the abstract interface for concrete backend factories.
|
||||
|
||||
struct backend_factory
|
||||
{
|
||||
virtual details::session_backend * make_session(
|
||||
std::string const & connectString) const = 0;
|
||||
};
|
||||
```cpp
|
||||
struct backend_factory
|
||||
{
|
||||
virtual details::session_backend * make_session(
|
||||
std::string const & connectString) const = 0;
|
||||
};
|
||||
```
|
||||
|
||||
The only member of this class is the `make_session` function that is supposed to create concrete backend implementation of the session object.
|
||||
|
||||
Objects of this type are declared by each backend and should be provided to the constructor of the `session` class. In simple programs users do not need to use this class directly, but the example use is:
|
||||
|
||||
backend_factory & factory = postgresql;
|
||||
std::string connectionParameters = "dbname=mydb";
|
||||
```cpp
|
||||
backend_factory & factory = postgresql;
|
||||
std::string connectionParameters = "dbname=mydb";
|
||||
|
||||
session sql(factory, parameters);
|
||||
session sql(factory, parameters);
|
||||
```
|
||||
|
||||
## Simple Client Interface
|
||||
|
||||
@@ -541,34 +584,37 @@ The functionality of this interface is limited and in particular the dynamic row
|
||||
|
||||
Users of this interface need to explicitly `#include <soci-simple.h>`.
|
||||
|
||||
typedef void * session_handle;
|
||||
session_handle soci_create_session(char const * connectionString);
|
||||
void soci_destroy_session(session_handle s);
|
||||
```c
|
||||
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);
|
||||
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);
|
||||
int soci_session_state(session_handle s);
|
||||
char const * soci_session_error_message(session_handle s);
|
||||
```
|
||||
|
||||
The functions above provide the *session* abstraction with the help of opaque handle. The `soci_session_state` function returns `1` if there was no error during the most recently executed function and `0` otherwise, in which case the `soci_session_error_message` can be used to obtain a human-readable error description.
|
||||
|
||||
Note that the only function that cannot report all errors this way is `soci_create_session`, which returns `NULL` 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.
|
||||
|
||||
```c
|
||||
typedef void *blob_handle;
|
||||
blob_handle soci_create_blob(session_handle s);
|
||||
void soci_destroy_blob(blob_handle b);
|
||||
|
||||
typedef void *blob_handle;
|
||||
blob_handle soci_create_blob(session_handle s);
|
||||
void soci_destroy_blob(blob_handle b);
|
||||
int soci_blob_get_len(blob_handle b);
|
||||
int soci_blob_read(blob_handle b, int offset, char *buf, int toRead);
|
||||
int soci_blob_write(blob_handle b, int offset, char const *buf, int toWrite);
|
||||
int soci_blob_append(blob_handle b, char const *buf, int toWrite);
|
||||
int soci_blob_trim(blob_handle b, int newLen);
|
||||
|
||||
int soci_blob_get_len(blob_handle b);
|
||||
int soci_blob_read(blob_handle b, int offset, char *buf, int toRead);
|
||||
int soci_blob_write(blob_handle b, int offset, char const *buf, int toWrite);
|
||||
int soci_blob_append(blob_handle b, char const *buf, int toWrite);
|
||||
int soci_blob_trim(blob_handle b, int newLen);
|
||||
|
||||
int soci_blob_state(blob_handle b);
|
||||
char const * soci_blob_error_message(blob_handle b);
|
||||
int soci_blob_state(blob_handle b);
|
||||
char const * soci_blob_error_message(blob_handle b);
|
||||
```
|
||||
|
||||
The functions above provide the *blob* abstraction with the help of opaque handle. The `soci_blob_state` function returns `1` if there was no error during the most recently executed function and `0` otherwise, in which case the `soci_session_error_message` can be used to obtain a human-readable error description.
|
||||
|
||||
@@ -576,114 +622,132 @@ For easy error testing, functions `soci_blob_read`, `soci_blob_write`, `soci_blo
|
||||
|
||||
Note that the only function that cannot report all errors this way is `soci_create_blob`, which returns `NULL` if it was not possible to create an internal object representing the blob.
|
||||
|
||||
```c
|
||||
typedef void * statement_handle;
|
||||
statement_handle soci_create_statement(session_handle s);
|
||||
void soci_destroy_statement(statement_handle st);
|
||||
|
||||
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);
|
||||
int soci_statement_state(statement_handle s);
|
||||
char const * soci_statement_error_message(statement_handle s);
|
||||
```
|
||||
|
||||
The functions above create and destroy the statement object. If the statement cannot be created by the `soci_create_statement` 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.
|
||||
|
||||
```c
|
||||
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_blob (statement_handle st);
|
||||
|
||||
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_blob (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);
|
||||
```
|
||||
|
||||
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);
|
||||
|
||||
These functions create new data items for storing query results (*into elements*). 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, `-1` is returned and the error condition is set in the statement object.
|
||||
These functions create new data items for storing query results (*into elements*). 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, `-1` is returned and the error condition is set in the statement object.
|
||||
|
||||
The `_v` versions create a `vector` into elements, which can be used
|
||||
to retrieve whole arrays of results.
|
||||
|
||||
int soci_get_into_state(statement_handle st, int position);
|
||||
int soci_get_into_state_v(statement_handle st, int position, int index);
|
||||
```c
|
||||
int soci_get_into_state(statement_handle st, int position);
|
||||
int soci_get_into_state_v(statement_handle st, int position, int index);
|
||||
```
|
||||
|
||||
This function returns `1` if the into element at the given position has non-null value and `0` otherwise. The `_v` version works with `vector` elements and expects an array index.
|
||||
|
||||
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);
|
||||
blob_handle soci_get_into_blob (statement_handle st, int position);
|
||||
```c
|
||||
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);
|
||||
blob_handle soci_get_into_blob (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);
|
||||
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);
|
||||
```
|
||||
|
||||
The functions above allow to retrieve the current value of the given into element.
|
||||
|
||||
**Note:** The `date` function returns the date value in the "`YYYY MM DD HH mm ss`" string format.
|
||||
|
||||
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_blob (statement_handle st, char const * name);
|
||||
```c
|
||||
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_blob (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);
|
||||
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);
|
||||
```
|
||||
|
||||
The functions above allow to create new data elements that will be used to provide data to the query (*use elements*). The new elements can be later identified by given name, which must be unique for the given statement.
|
||||
|
||||
void soci_set_use_state(statement_handle st, char const * name, int state);
|
||||
```c
|
||||
void soci_set_use_state(statement_handle st, char const * name, int state);
|
||||
```
|
||||
|
||||
The `soci_set_use_state` function allows to set the state of the given use element. If the `state` parameter is set to non-zero the use element is considered non-null (which is also the default state after creating the use element).
|
||||
|
||||
int soci_use_get_size_v(statement_handle st);
|
||||
void soci_use_resize_v (statement_handle st, int new_size);
|
||||
```c
|
||||
int soci_use_get_size_v(statement_handle st);
|
||||
void soci_use_resize_v (statement_handle st, int new_size);
|
||||
```
|
||||
|
||||
These functions get and set the size of vector use elements (see comments for vector into elements above).
|
||||
|
||||
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_blob (statement_handle st, char const * name, blob_handle blob);
|
||||
```c
|
||||
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_blob (statement_handle st, char const * name, blob_handle blob);
|
||||
|
||||
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);
|
||||
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);
|
||||
```
|
||||
|
||||
The functions above set the value of the given use element, for both single and vector elements.
|
||||
|
||||
**Note:** The expected format for the data values is "`YYYY MM DD HH mm ss`".
|
||||
|
||||
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);
|
||||
blob_handle soci_get_use_blob (statement_handle st, char const * name);
|
||||
```c
|
||||
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);
|
||||
blob_handle soci_get_use_blob (statement_handle st, char const * name);
|
||||
```
|
||||
|
||||
These functions allow to inspect the state and value of named use elements.
|
||||
|
||||
***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.
|
||||
|
||||
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);
|
||||
```c
|
||||
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);
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
@@ -10,17 +10,14 @@ See [Tested Platforms](#tested-platforms).
|
||||
|
||||
### Tested Platforms
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr><th>DB2 version</th><th>Operating System</th><th>Compiler</th></tr>
|
||||
<tr><td>-</td><td>Linux PPC64</td><td>GCC</td></tr>
|
||||
<tr><td>9.1</td><td>Linux</td><td>GCC</td></tr>
|
||||
<tr><td>9.5</td><td>Linux</td><td>GCC</td></tr>
|
||||
<tr><td>9.7</td><td>Linux</td><td>GCC</td></tr>
|
||||
<tr><td>10.1</td><td>Linux</td><td>GCC</td></tr>
|
||||
<tr><td>10.1</td><td>Windows 8</td><td>Visual Studio 2012</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|DB2 |OS|Compiler|
|
||||
|--- |--- |--- |
|
||||
|-|Linux PPC64|GCC|
|
||||
|9.1|Linux|GCC|
|
||||
|9.5|Linux|GCC|
|
||||
|9.7|Linux|GCC|
|
||||
|10.1|Linux|GCC|
|
||||
|10.1|Windows 8|Visual Studio 2012|
|
||||
|
||||
### Required Client Libraries
|
||||
|
||||
@@ -30,11 +27,16 @@ The SOCI DB2 backend requires IBM DB2 Call Level Interface (CLI) library.
|
||||
|
||||
On Unix, before using the DB2 backend please make sure, that you have sourced DB2 profile into your environment:
|
||||
|
||||
. ~/db2inst1/sqllib/db2profile
|
||||
```sh
|
||||
. ~/db2inst1/sqllib/db2profile
|
||||
```
|
||||
|
||||
To establish a connection to the DB2 database, create a session object using the <code>DB2</code> backend factory together with the database file name:
|
||||
To establish a connection to the DB2 database, create a session object using the DB2
|
||||
backend factory together with the database file name:
|
||||
|
||||
soci::session sql(soci::db2, "your DB2 connection string here");
|
||||
```cpp
|
||||
soci::session sql(soci::db2, "your DB2 connection string here");
|
||||
```
|
||||
|
||||
## SOCI Feature Support
|
||||
|
||||
@@ -56,15 +58,16 @@ Currently, not supported.
|
||||
|
||||
### Nested Statements
|
||||
|
||||
Nesting statements are not processed by SOCI in any special way and they work as implemented by the DB2 database.
|
||||
Nesting statements are not processed by SOCI in any special way and they work as implemented
|
||||
by the DB2 database.
|
||||
|
||||
### Stored Procedures
|
||||
|
||||
Stored procedures are supported, with <code>CALL</code> statement.
|
||||
Stored procedures are supported, with `CALL` statement.
|
||||
|
||||
## Native API Access
|
||||
|
||||
*TODO*
|
||||
TODO
|
||||
|
||||
## Backend-specific extensions
|
||||
|
||||
@@ -72,16 +75,19 @@ None.
|
||||
|
||||
## Configuration options
|
||||
|
||||
This backend supports `db2_option_driver_complete` option which can be passed to
|
||||
it via `connection_parameters` class. The value of this option is passed to
|
||||
`SQLDriverConnect()` function as "driver completion" parameter and so must be
|
||||
one of `SQL_DRIVER_XXX` values, in the string form. The default value of this
|
||||
option is `SQL_DRIVER_PROMPT` meaning that the driver will query the user for
|
||||
the user name and/or the password if they are not stored together with the
|
||||
connection. If this is undesirable for some reason, you can use `SQL_DRIVER_NOPROMPT` value for this option to suppress showing the message box:
|
||||
This backend supports `db2_option_driver_complete` option which can be passed to it via
|
||||
`connection_parameters` class. The value of this option is passed to `SQLDriverConnect()`
|
||||
function as "driver completion" parameter and so must be one of `SQL_DRIVER_XXX` values,
|
||||
in the string form. The default value of this option is `SQL_DRIVER_PROMPT` meaning
|
||||
that the driver will query the user for the user name and/or the password if they are
|
||||
not stored together with the connection. If this is undesirable for some reason,
|
||||
you can use `SQL_DRIVER_NOPROMPT` value for this option to suppress showing the message box:
|
||||
|
||||
connection_parameters parameters("db2", "DSN=sample");
|
||||
parameters.set_option(db2_option_driver_complete, "0" /* SQL_DRIVER_NOPROMPT */);
|
||||
session sql(parameters);
|
||||
```cpp
|
||||
connection_parameters parameters("db2", "DSN=sample");
|
||||
parameters.set_option(db2_option_driver_complete, "0" /* SQL_DRIVER_NOPROMPT */);
|
||||
session sql(parameters);
|
||||
```
|
||||
|
||||
Note, `db2_option_driver_complete` controls driver completion specific to the IBM DB2 driver for ODBC and CLI.
|
||||
Note, `db2_option_driver_complete` controls driver completion specific to the IBM DB2 driver
|
||||
for ODBC and CLI.
|
||||
|
||||
@@ -6,20 +6,19 @@ SOCI backend for accessing Firebird database.
|
||||
|
||||
### Supported Versions
|
||||
|
||||
The SOCI Firebird backend supports versions of Firebird from 1.5 to 2.5 and can be used with either the client-server or embedded Firebird libraries.
|
||||
The former is the default, to select the latter set <tt>SOCI_FIREBIRD_EMBEDDED</tt> CMake option to <tt>ON</tt> value when building.
|
||||
The SOCI Firebird backend supports versions of Firebird from 1.5 to 2.5 and can be used with
|
||||
either the client-server or embedded Firebird libraries.
|
||||
The former is the default, to select the latter set `SOCI_FIREBIRD_EMBEDDED` CMake option to `ON`
|
||||
value when building.
|
||||
|
||||
### Tested Platforms
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr><th>Firebird version</th><th>Operating System</th><th>Compiler</th></tr>
|
||||
<tr><td>1.5.2.4731</td><td>SunOS 5.10</td><td>g++ 3.4.3</td></tr>
|
||||
<tr><td>1.5.2.4731</td><td>Windows XP</td><td>Visual C++ 8.0</td></tr>
|
||||
<tr><td>1.5.3.4870</td><td>Windows XP</td><td>Visual C++ 8.0 Professional</td></tr>
|
||||
<tr><td>2.5.2.26540</td><td>Debian GNU/Linux 7</td><td>g++ 4.7.2</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|Firebird |OS|Compiler|
|
||||
|--- |--- |--- |
|
||||
|1.5.2.4731|SunOS 5.10|g++ 3.4.3|
|
||||
|1.5.2.4731|Windows XP|Visual C++ 8.0|
|
||||
|1.5.3.4870|Windows XP|Visual C++ 8.0 Professional|
|
||||
|2.5.2.26540|Debian GNU/Linux 7|g++ 4.7.2|
|
||||
|
||||
### Required Client Libraries
|
||||
|
||||
@@ -27,16 +26,19 @@ The Firebird backend requires Firebird's `libfbclient` client library.
|
||||
|
||||
## Connecting to the Database
|
||||
|
||||
To establish a connection to a Firebird database, create a Session object using the firebird backend factory together with a connection string:
|
||||
To establish a connection to a Firebird database, create a Session object using the firebird
|
||||
backend factory together with a connection string:
|
||||
|
||||
BackEndFactory const &backEnd = firebird;
|
||||
Session sql(backEnd,
|
||||
"service=/usr/local/firbird/db/test.fdb user=SYSDBA password=masterkey");
|
||||
```cpp
|
||||
BackEndFactory const &backEnd = firebird;
|
||||
session sql(backEnd, "service=/usr/local/firbird/db/test.fdb user=SYSDBA password=masterkey");
|
||||
```
|
||||
|
||||
or simply:
|
||||
|
||||
Session sql(firebird,
|
||||
"service=/usr/local/firbird/db/test.fdb user=SYSDBA password=masterkey");
|
||||
```cpp
|
||||
session sql(firebird, "service=/usr/local/firbird/db/test.fdb user=SYSDBA password=masterkey");
|
||||
```
|
||||
|
||||
The set of parameters used in the connection string for Firebird is:
|
||||
|
||||
@@ -46,92 +48,76 @@ The set of parameters used in the connection string for Firebird is:
|
||||
* role
|
||||
* charset
|
||||
|
||||
The following parameters have to be provided as part of the connection string : *service*, *user*, *password*. Role and charset parameters are optional.
|
||||
The following parameters have to be provided as part of the connection string : *service*, *user*,
|
||||
*password*. Role and charset parameters are optional.
|
||||
|
||||
Once you have created a `Session` object as shown above, you can use it to access the database, for example:
|
||||
Once you have created a `session` object as shown above, you can use it to access the database, for example:
|
||||
|
||||
int count;
|
||||
sql << "select count(*) from user_tables", into(count);
|
||||
|
||||
(See the [SOCI basics](../basics.html) and [exchanging data](../exchange.html) documentation for general information on using the `Session` class.)
|
||||
```cpp
|
||||
int count;
|
||||
sql << "select count(*) from user_tables", into(count);
|
||||
```
|
||||
|
||||
(See the [SOCI basics](../basics.html) and [exchanging data](../exchange.html) documentation
|
||||
for general information on using the `session` class.)
|
||||
|
||||
## SOCI Feature Support
|
||||
|
||||
### Dynamic Binding
|
||||
|
||||
The Firebird backend supports the use of the SOCI `Row` class, which facilitates retrieval of data whose type is not known at compile time.
|
||||
The Firebird backend supports the use of the SOCI `row` class, which facilitates retrieval of data whose
|
||||
type is not known at compile time.
|
||||
|
||||
When calling `Row::get<T>()`, the type you should pass as T depends upon the underlying database type. For the Firebird backend, this type mapping is:
|
||||
When calling `row::get<T>()`, the type you should pass as T depends upon the underlying database type.
|
||||
For the Firebird backend, this type mapping is:
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>Firebird Data Type</th>
|
||||
<th>SOCI Data Type</th>
|
||||
<th><code>Row::get<T></code> specializations</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>numeric, decimal <br />*(where scale > 0)*</td>
|
||||
<td><code>eDouble</code></td>
|
||||
<td><code>double</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>numeric, decimal <sup>[<a href="#note1">1</a>]</sup><br />*(where scale = 0)*</td>
|
||||
<td><code>eInteger, eDouble</code></td>
|
||||
<td><code>int, double</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>double precision, float</td>
|
||||
<td><code>eDouble</code></td>
|
||||
<td><code>double</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>smallint, integer</td>
|
||||
<td><code>eInteger</code></td>
|
||||
<td><code>int</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>char, varchar</td>
|
||||
<td><code>eString</code></td>
|
||||
<td><code>std::string</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>date, time, timestamp</td>
|
||||
<td><code>eDate</code></td>
|
||||
<td><code>std::tm</code></code></code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|Firebird Data Type|SOCI Data Type|`row::get<T>` specializations|
|
||||
|--- |--- |--- |
|
||||
|numeric, decimal (where scale > 0)|eDouble|double|
|
||||
|numeric, decimal [^1] (where scale = 0)|eInteger, eDouble|int, double|
|
||||
|double precision, float|eDouble|double|
|
||||
|smallint, integer|eInteger|int|
|
||||
|char, varchar|eString|std::string|
|
||||
|date, time, timestamp|eDate|std::tm|
|
||||
|
||||
<a name="note1" /> <sup>[1]</sup> There is also 64bit integer type for larger values which is
|
||||
[^1] There is also 64bit integer type for larger values which is
|
||||
currently not supported.
|
||||
|
||||
(See the [dynamic resultset binding](../exchange.html#dynamic) documentation for general information on using the `Row` class.)
|
||||
|
||||
(See the [dynamic resultset binding](../exchange.html#dynamic) documentation for general information
|
||||
on using the `Row` class.)
|
||||
|
||||
### Binding by Name
|
||||
|
||||
In addition to [binding by position](../exchange.html#bind_position), the Firebird backend supports [binding by name](../exchange.html#bind_name), via an overload of the `use()` function:
|
||||
In addition to [binding by position](../exchange.html#bind_position), the Firebird backend supports
|
||||
[binding by name](../exchange.html#bind_name), via an overload of the `use()` function:
|
||||
|
||||
int id = 7;
|
||||
sql << "select name from person where id = :id", use(id, "id")
|
||||
|
||||
It should be noted that parameter binding by name is supported only by means of emulation, since the underlying API used by the backend doesn't provide this feature.
|
||||
It should be noted that parameter binding by name is supported only by means of emulation,
|
||||
since the underlying API used by the backend doesn't provide this feature.
|
||||
|
||||
### Bulk Operations
|
||||
|
||||
The Firebird backend has full support for SOCI's [bulk operations](../statements.html#bulk) interface. This feature is also supported by emulation.
|
||||
The Firebird backend has full support for SOCI [bulk operations](../statements.html#bulk) interface.
|
||||
This feature is also supported by emulation.
|
||||
|
||||
### Transactions
|
||||
|
||||
[Transactions](../statements.html#transactions) are also fully supported by the Firebird backend. In fact, an implicit transaction is always started when using this backend if one hadn't been started by explicitly calling <tt>begin()</tt> before. The current transaction is automatically committed in `Session's` destructor.
|
||||
[Transactions](../statements.html#transactions) are also fully supported by the Firebird backend.
|
||||
In fact, an implicit transaction is always started when using this backend if one hadn't been
|
||||
started by explicitly calling `begin()` before. The current transaction is automatically
|
||||
committed in `session` destructor.
|
||||
|
||||
### BLOB Data Type
|
||||
|
||||
The Firebird backend supports working with data stored in columns of type Blob, via SOCI's `[BLOB](../exchange.html#blob)` class.
|
||||
The Firebird backend supports working with data stored in columns of type Blob,
|
||||
via SOCI `[BLOB](../exchange.html#blob)` class.
|
||||
|
||||
It should by noted, that entire Blob data is fetched from database to allow random read and write access. This is because Firebird itself allows only writing to a new Blob or reading from existing one - modifications of existing Blob means creating a new one. Firebird backend hides those details from user.
|
||||
It should by noted, that entire Blob data is fetched from database to allow random read and write access.
|
||||
This is because Firebird itself allows only writing to a new Blob or reading from existing one -
|
||||
modifications of existing Blob means creating a new one.
|
||||
Firebird backend hides those details from user.
|
||||
|
||||
### RowID Data Type
|
||||
|
||||
@@ -143,41 +129,25 @@ This feature is not supported by Firebird backend.
|
||||
|
||||
### Stored Procedures
|
||||
|
||||
Firebird stored procedures can be executed by using SOCI's [Procedure](../statements.html#procedures) class.
|
||||
Firebird stored procedures can be executed by using SOCI [Procedure](../statements.html#procedures) class.
|
||||
|
||||
## Native API Access
|
||||
|
||||
SOCI provides access to underlying datbabase APIs via several getBackEnd() functions, as described in the [beyond SOCI](../beyond.html) documentation.
|
||||
SOCI provides access to underlying datbabase APIs via several getBackEnd() functions,
|
||||
as described in the [beyond SOCI](../beyond.html) documentation.
|
||||
|
||||
The Firebird backend provides the following concrete classes for navite API access:
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>Accessor Function</th>
|
||||
<th>Concrete Class</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>SessionBackEnd* Session::getBackEnd()</code></td>
|
||||
<td><code>FirebirdSessionBackEnd</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>StatementBackEnd* Statement::getBackEnd()</code></td>
|
||||
<td><code>FirebirdStatementBackEnd</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>BLOBBackEnd* BLOB::getBackEnd()</code></td>
|
||||
<td><code>FirebirdBLOBBackEnd</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>RowIDBackEnd* RowID::getBackEnd()</code></td>
|
||||
<td<>code>FirebirdRowIDBackEnd</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|Accessor Function|Concrete Class|
|
||||
|--- |--- |
|
||||
|SessionBackEnd* Session::getBackEnd()|FirebirdSessionBackEnd|
|
||||
|StatementBackEnd* Statement::getBackEnd()|FirebirdStatementBackEnd|
|
||||
|BLOBBackEnd* BLOB::getBackEnd()|FirebirdBLOBBackEnd|
|
||||
|RowIDBackEnd* RowID::getBackEnd()|
|
||||
|
||||
## Backend-specific extensions
|
||||
|
||||
### FirebirdSOCIError
|
||||
|
||||
The Firebird backend can throw instances of class `FirebirdSOCIError`, which is publicly derived from `SOCIError` and has an additional public `status_` member containing the Firebird status vector.
|
||||
The Firebird backend can throw instances of class `FirebirdSOCIError`, which is publicly derived
|
||||
from `SOCIError` and has an additional public `status_` member containing the Firebird status vector.
|
||||
|
||||
@@ -2,97 +2,13 @@
|
||||
|
||||
Follow the links to learn more about each backend and detailed supported features.
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th></th>
|
||||
<th><a href="oracle">Oracle</a></th>
|
||||
<th><a href="postgresql">PostgreSQL</a></th>
|
||||
<th><a href="mysql">MySQL</a></th>
|
||||
<th><a href="sqlite3">SQLite3</a></th>
|
||||
<th><a href="firebird">Firebird</a></th>
|
||||
<th><a href="odbc">ODBC</a></th>
|
||||
<th><a href="db2">DB2</a></th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Binding by Name</td>
|
||||
<td>YES</td>
|
||||
<td>YES (>=8.0)</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Dynamic Binding</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Bulk Operations</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Transactions</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>YES (>=4.0)</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>BLOB Data Type</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>YES (mapped to `std::string`)</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>NO</td>
|
||||
<td>NO</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>RowID Data Type</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>NO</td>
|
||||
<td>NO</td>
|
||||
<td>NO</td>
|
||||
<td>NO</td>
|
||||
<td>NO</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Nested Statements</td>
|
||||
<td>YES</td>
|
||||
<td>NO</td>
|
||||
<td>NO</td>
|
||||
<td>NO</td>
|
||||
<td>NO</td>
|
||||
<td>NO</td>
|
||||
<td>YES</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Stored Procedures</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>NO (but stored functions, YES)</td>
|
||||
<td>NO</td>
|
||||
<td>YES</td>
|
||||
<td>NO</td>
|
||||
<td>YES</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|Oracle|PostgreSQL|MySQL|SQLite3|Firebird|ODBC|DB2|
|
||||
|--- |--- |--- |--- |--- |--- |--- |
|
||||
|Binding by Name|YES|YES (>=8.0)|YES|YES|YES|YES|YES|
|
||||
|Dynamic Binding|YES|YES|YES|YES|YES|YES|
|
||||
|Bulk Operations|YES|YES|YES|YES|YES|YES|YES|
|
||||
|Transactions|YES|YES|YES (>=4.0)|YES|YES|YES|YES|
|
||||
|BLOB Data Type|YES|YES|YES (mapped to `std::string`)|YES|YES|NO|NO|
|
||||
|RowID Data Type|YES|YES|NO|NO|NO|NO|NO|
|
||||
|Nested Statements|YES|NO|NO|NO|NO|NO|YES|
|
||||
|Stored Procedures|YES|YES|NO (but stored functions, YES)|NO|YES|NO|YES|
|
||||
|
||||
@@ -10,14 +10,11 @@ The SOCI MySQL backend should in principle work with every version of MySQL 5.x.
|
||||
|
||||
### Tested Platforms
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr><th>MySQL version</th><th>Operating System</th><th>Compiler</th></tr>
|
||||
<tr><td>8.0.1</td><td>Windows 10</td><td>Visual Studio 2017 (15.3.3)</td></tr>
|
||||
<tr><td>5.5.28</td><td>OS X 10.8.2</td><td>Apple LLVM version 4.2 (clang-425.0.24)</td></tr>
|
||||
<tr><td>5.0.96</td><td>Ubuntu 8.04.4 LTS (Hardy Heron)</td><td>g++ (GCC) 4.2.4 (Ubuntu 4.2.4-1ubuntu4)</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|MySQL|OS|Compiler|
|
||||
|--- |--- |--- |
|
||||
|8.0.1|Windows 10|Visual Studio 2017 (15.3.3)|
|
||||
|5.5.28|OS X 10.8.2|Apple LLVM version 4.2 (clang-425.0.24)|
|
||||
|5.0.96|Ubuntu 8.04.4 LTS (Hardy Heron)|g++ (GCC) 4.2.4 (Ubuntu 4.2.4-1ubuntu4)|
|
||||
|
||||
### Required Client Libraries
|
||||
|
||||
@@ -57,7 +54,6 @@ Once you have created a `session` object as shown above, you can use it to acces
|
||||
int count;
|
||||
sql << "select count(*) from invoices", into(count);
|
||||
|
||||
|
||||
(See the [SOCI basics]("../basics.html) and [exchanging data](../exchange.html) documentation for general information on using the `session` class.)
|
||||
|
||||
## SOCI Feature Support
|
||||
@@ -69,52 +65,15 @@ The MySQL backend supports the use of the SOCI `row` class, which facilitates re
|
||||
When calling `row::get<T>()`, the type you should pass as `T` depends upon the underlying database type.
|
||||
For the MySQL backend, this type mapping is:
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>MySQL Data Type</th>
|
||||
<th>SOCI Data Type</th>
|
||||
<th><code>row::get<T></code> specializations</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>FLOAT, DOUBLE, DECIMAL and synonyms</td>
|
||||
<td><code>dt_double</code></td>
|
||||
<td><code>double</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>TINYINT, TINYINT UNSIGNED, SMALLINT, SMALLINT UNSIGNED, INT</td>
|
||||
<td><code>dt_integer</code></td>
|
||||
<td><code>int</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>INT UNSIGNED</td>
|
||||
<td><code>dt_long_long</code></td>
|
||||
<td><code>long long</code> or </code>unsigned</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>BIGINT</td>
|
||||
<td><code>dt_long_long</code></td>
|
||||
<td><code>long long</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>BIGINT UNSIGNED</td>
|
||||
<td><code>dt_unsigned_long_long</code></td>
|
||||
<td><code>unsigned long long</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>CHAR, VARCHAR, BINARY, VARBINARY, TINYBLOB, MEDIUMBLOB, BLOB,
|
||||
LONGBLOB, TINYTEXT, MEDIUMTEXT, TEXT, LONGTEXT, ENUM</td>
|
||||
<td><code>dt_string</code></td>
|
||||
<td><code>std::string</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>TIMESTAMP (works only with MySQL >= 5.0), DATE,
|
||||
TIME, DATETIME</td>
|
||||
<td><code>dt_date</code></td>
|
||||
<td><code>std::tm</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|MySQL Data Type|SOCI Data Type|`row::get<T>` specializations|
|
||||
|--- |--- |--- |
|
||||
|FLOAT, DOUBLE, DECIMAL and synonyms|dt_double|double|
|
||||
|TINYINT, TINYINT UNSIGNED, SMALLINT, SMALLINT UNSIGNED, INT|dt_integer|int|
|
||||
|INT UNSIGNED|dt_long_long|long long or unsigned|
|
||||
|BIGINT|dt_long_long|long long|
|
||||
|BIGINT UNSIGNED|dt_unsigned_long_long|unsigned long long|
|
||||
|CHAR, VARCHAR, BINARY, VARBINARY, TINYBLOB, MEDIUMBLOB, BLOB,LONGBLOB, TINYTEXT, MEDIUMTEXT, TEXT, LONGTEXT, ENUM|dt_string|std::string|
|
||||
|TIMESTAMP (works only with MySQL >= 5.0), DATE, TIME, DATETIME|dt_date|std::tm|
|
||||
|
||||
(See the [dynamic resultset binding](../exchange.html#dynamic) documentation for general information on using the `Row` class.)
|
||||
|
||||
@@ -156,22 +115,10 @@ SOCI provides access to underlying datbabase APIs via several `get_backend()` fu
|
||||
|
||||
The MySQL backend provides the following concrete classes for native API access:
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>Accessor Function</th>
|
||||
<th>Concrete Class</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>session_backend * session::get_backend()</code></td>
|
||||
<td><code>mysql_session_backend</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>statement_backend * statement::get_backend()</code></td>
|
||||
<td><code>mysql_statement_backend</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|Accessor Function|Concrete Class|
|
||||
|--- |--- |
|
||||
|session_backend * session::get_backend()|mysql_session_backend|
|
||||
|statement_backend * statement::get_backend()|mysql_statement_backend|
|
||||
|
||||
## Backend-specific extensions
|
||||
|
||||
|
||||
@@ -10,18 +10,15 @@ The SOCI ODBC backend is supported for use with ODBC 3.
|
||||
|
||||
### Tested Platforms
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr><th>ODBC version</th><th>Operating System</th><th>Compiler</th></tr>
|
||||
<tr><td>3</td><td>Linux (Ubuntu 12.04)</td><td>g++ 4.6.3</td></tr>
|
||||
<tr><td>3</td><td>Linux (Ubuntu 12.04)</td><td>clang 3.2</td></tr>
|
||||
<tr><td>3.8</td><td>Windows 8</td><td>Visual Studio 2012</td></tr>
|
||||
<tr><td>3</td><td>Windows 7</td><td>Visual Studio 2010</td></tr>
|
||||
<tr><td>3</td><td>Windows XP</td><td>Visual Studio 2005 (express)</td></tr>
|
||||
<tr><td>3</td><td>Windows XP</td><td>Visual C++ 8.0 Professional</td></tr>
|
||||
<tr><td>3</td><td>Windows XP</td><td>g++ 3.3.4 (Cygwin)</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|ODBC|OS|Compiler|
|
||||
|--- |--- |--- |
|
||||
|3|Linux (Ubuntu 12.04)|g++ 4.6.3|
|
||||
|3|Linux (Ubuntu 12.04)|clang 3.2|
|
||||
|3.8|Windows 8|Visual Studio 2012|
|
||||
|3|Windows 7|Visual Studio 2010|
|
||||
|3|Windows XP|Visual Studio 2005 (express)|
|
||||
|3|Windows XP|Visual C++ 8.0 Professional|
|
||||
|3|Windows XP|g++ 3.3.4 (Cygwin)|
|
||||
|
||||
### Required Client Libraries
|
||||
|
||||
@@ -31,19 +28,25 @@ The SOCI ODBC backend requires the ODBC client library.
|
||||
|
||||
To establish a connection to the ODBC database, create a Session object using the `ODBC` backend factory together with a connection string:
|
||||
|
||||
backend_factory const& backEnd = odbc;
|
||||
session sql(backEnd, "filedsn=c:\\my.dsn");
|
||||
```cpp
|
||||
backend_factory const& backEnd = odbc;
|
||||
session sql(backEnd, "filedsn=c:\\my.dsn");
|
||||
```
|
||||
|
||||
or simply:
|
||||
|
||||
session sql(odbc, "filedsn=c:\\my.dsn");
|
||||
```cpp
|
||||
session sql(odbc, "filedsn=c:\\my.dsn");
|
||||
```
|
||||
|
||||
The set of parameters used in the connection string for ODBC is the same as accepted by the `[SQLDriverConnect](http://msdn.microsoft.com/library/default.asp?url=/library/en-us/odbcsql/od_odbc_d_4x4k.asp)` function from the ODBC library.
|
||||
The set of parameters used in the connection string for ODBC is the same as accepted by the [SQLDriverConnect](http://msdn.microsoft.com/library/default.asp?url=/library/en-us/odbcsql/od_odbc_d_4x4k.asp) function from the ODBC library.
|
||||
|
||||
Once you have created a `session` object as shown above, you can use it to access the database, for example:
|
||||
|
||||
int count;
|
||||
sql << "select count(*) from invoices", into(count);
|
||||
```cpp
|
||||
int count;
|
||||
sql << "select count(*) from invoices", into(count);
|
||||
```
|
||||
|
||||
(See the [SOCI basics](../basics.html) and [exchanging data](../exchange.html) documentation for general information on using the `session` class.)
|
||||
|
||||
@@ -56,97 +59,44 @@ The ODBC backend supports the use of the SOCI `row` class, which facilitates ret
|
||||
When calling `row::get<T>()`, the type you should pass as T depends upon the underlying database type.
|
||||
For the ODBC backend, this type mapping is:
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>ODBC Data Type</th>
|
||||
<th>SOCI Data Type</th>
|
||||
<th><code>row::get<T></code> specializations</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SQL_DOUBLE
|
||||
, SQL_DECIMAL
|
||||
, SQL_REAL
|
||||
, SQL_FLOAT
|
||||
, SQL_NUMERIC
|
||||
</td>
|
||||
<td><code>dt_double</code></td>
|
||||
<td><code>double</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SQL_TINYINT
|
||||
, SQL_SMALLINT
|
||||
, SQL_INTEGER
|
||||
, SQL_BIGINT</td>
|
||||
<td><code>dt_integer</code></td>
|
||||
<td><code>int</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SQL_CHAR, SQL_VARCHAR</td>
|
||||
<td><code>dt_string</code></td>
|
||||
<td><code>std::string</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SQL_TYPE_DATE
|
||||
, SQL_TYPE_TIME
|
||||
, SQL_TYPE_TIMESTAMP</td>
|
||||
<td><code>dt_date</code></td>
|
||||
<td><code>std::tm</code></code></code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|ODBC Data Type|SOCI Data Type|`row::get<T>` specializations|
|
||||
|--- |--- |--- |
|
||||
|SQL_DOUBLE, SQL_DECIMAL, SQL_REAL, SQL_FLOAT, SQL_NUMERIC|dt_double|double|
|
||||
|SQL_TINYINT, SQL_SMALLINT, SQL_INTEGER, SQL_BIGINT|dt_integer|int|
|
||||
|SQL_CHAR, SQL_VARCHAR|dt_string|std::string|
|
||||
|SQL_TYPE_DATE, SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP|dt_date|std::tm|
|
||||
|
||||
Not all ODBC drivers support all datatypes.
|
||||
|
||||
(See the [dynamic resultset binding](../exchange.html#dynamic) documentation for general information on using the `row` class.)
|
||||
|
||||
|
||||
### Binding by Name
|
||||
### Binding by Name
|
||||
|
||||
In addition to [binding by position](../exchange.html#bind_position), the ODBC backend supports [binding by name](../exchange.html#bind_name), via an overload of the `use()` function:
|
||||
|
||||
int id = 7;
|
||||
sql << "select name from person where id = :id", use(id, "id")
|
||||
```cpp
|
||||
int id = 7;
|
||||
sql << "select name from person where id = :id", use(id, "id")
|
||||
```
|
||||
|
||||
Apart from the portable "colon-name" syntax above, which is achieved by rewriting the query string, the backend also supports the ODBC ? syntax:
|
||||
|
||||
int i = 7;
|
||||
int j = 8;
|
||||
sql << "insert into t(x, y) values(?, ?)", use(i), use(j);
|
||||
```cpp
|
||||
int i = 7;
|
||||
int j = 8;
|
||||
sql << "insert into t(x, y) values(?, ?)", use(i), use(j);
|
||||
```
|
||||
|
||||
### Bulk Operations
|
||||
|
||||
The ODBC backend has support for SOCI's [bulk operations](../statements.html#bulk) interface. Not all ODBC drivers support bulk operations, the following is a list of some tested backends:
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>ODBC Driver</th>
|
||||
<th>Bulk Read</th>
|
||||
<th>Bulk Insert</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>MS SQL Server 2005</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>MS Access 2003</td>
|
||||
<td>YES</td>
|
||||
<td>NO</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>PostgresQL 8.1</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>MySQL 4.1</td>
|
||||
<td>NO</td>
|
||||
<td>NO</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|ODBC Driver|Bulk Read|Bulk Insert|
|
||||
|--- |--- |--- |
|
||||
|MS SQL Server 2005|YES|YES|
|
||||
|MS Access 2003|YES|NO|
|
||||
|PostgresQL 8.1|YES|YES|
|
||||
|MySQL 4.1|NO|NO|
|
||||
|
||||
### Transactions
|
||||
|
||||
@@ -174,26 +124,11 @@ SOCI provides access to underlying datbabase APIs via several getBackEnd() funct
|
||||
|
||||
The ODBC backend provides the following concrete classes for navite API access:
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>Accessor Function</th>
|
||||
<th>Concrete Class</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>session_backend* session::get_backend()</code></td>
|
||||
<td><code>odbc_statement_backend</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>statement_backend* statement::get_backend()</code></td>
|
||||
<td><code>odbc_statement_backend</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>rowid_backend* rowid::get_backend()</code></td>
|
||||
<td><code>odbc_rowid_backend</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|Accessor Function|Concrete Class|
|
||||
|--- |--- |
|
||||
|session_backend* session::get_backend()|odbc_statement_backend|
|
||||
|statement_backend* statement::get_backend()|odbc_statement_backend|
|
||||
|rowid_backend* rowid::get_backend()|odbc_rowid_backend|
|
||||
|
||||
## Backend-specific extensions
|
||||
|
||||
@@ -201,24 +136,26 @@ The ODBC backend provides the following concrete classes for navite API access:
|
||||
|
||||
The ODBC backend can throw instances of class `odbc_soci_error`, which is publicly derived from `soci_error` and has additional public members containing the ODBC error code, the Native database error code, and the message returned from ODBC:
|
||||
|
||||
int main()
|
||||
```cpp
|
||||
int main()
|
||||
{
|
||||
try
|
||||
{
|
||||
try
|
||||
{
|
||||
// regular code
|
||||
}
|
||||
catch (soci::odbc_soci_error const& e)
|
||||
{
|
||||
cerr << "ODBC Error Code: " << e.odbc_error_code() << endl
|
||||
<< "Native Error Code: " << e.native_error_code() << endl
|
||||
<< "SOCI Message: " << e.what() << std::endl
|
||||
<< "ODBC Message: " << e.odbc_error_message() << endl;
|
||||
}
|
||||
catch (exception const &e)
|
||||
{
|
||||
cerr << "Some other error: " << e.what() << endl;
|
||||
}
|
||||
// regular code
|
||||
}
|
||||
catch (soci::odbc_soci_error const& e)
|
||||
{
|
||||
cerr << "ODBC Error Code: " << e.odbc_error_code() << endl
|
||||
<< "Native Error Code: " << e.native_error_code() << endl
|
||||
<< "SOCI Message: " << e.what() << std::endl
|
||||
<< "ODBC Message: " << e.odbc_error_message() << endl;
|
||||
}
|
||||
catch (exception const &e)
|
||||
{
|
||||
cerr << "Some other error: " << e.what() << endl;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### get_connection_string()
|
||||
|
||||
@@ -229,6 +166,8 @@ that returns fully expanded connection string as returned by the `SQLDriverConne
|
||||
|
||||
This backend supports `odbc_option_driver_complete` option which can be passed to it via `connection_parameters` class. The value of this option is passed to `SQLDriverConnect()` function as "driver completion" parameter and so must be one of `SQL_DRIVER_XXX` values, in the string form. The default value of this option is `SQL_DRIVER_PROMPT` meaning that the driver will query the user for the user name and/or the password if they are not stored together with the connection. If this is undesirable for some reason, you can use `SQL_DRIVER_NOPROMPT` value for this option to suppress showing the message box:
|
||||
|
||||
connection_parameters parameters("odbc", "DSN=mydb");
|
||||
parameters.set_option(odbc_option_driver_complete, "0" /* SQL_DRIVER_NOPROMPT */);
|
||||
session sql(parameters);
|
||||
```cpp
|
||||
connection_parameters parameters("odbc", "DSN=mydb");
|
||||
parameters.set_option(odbc_option_driver_complete, "0" /* SQL_DRIVER_NOPROMPT */);
|
||||
session sql(parameters);
|
||||
```
|
||||
|
||||
@@ -11,12 +11,10 @@ Older versions of Oracle may work as well, but they have not been tested by the
|
||||
|
||||
### Tested Platforms
|
||||
|
||||
<table>
|
||||
<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>
|
||||
|Oracle|OS|Compiler|
|
||||
|--- |--- |--- |
|
||||
|10.2.0 (XE)|RedHat 5|g++ 4.3|
|
||||
|11.2.0 (XE)|Ubuntu 12.04|g++ 4.6.3|
|
||||
|
||||
### Required Client Libraries
|
||||
|
||||
@@ -24,22 +22,26 @@ The SOCI Oracle backend requires Oracle's `libclntsh` client library. Depending
|
||||
|
||||
Note that the SOCI library itself depends also on `libdl`, so the minimum set of libraries needed to compile a basic client program is:
|
||||
|
||||
-lsoci_core -lsoci_oracle -ldl -lclntsh -lnnz10
|
||||
```sh
|
||||
-lsoci_core -lsoci_oracle -ldl -lclntsh -lnnz10
|
||||
```
|
||||
|
||||
### Connecting to the Database
|
||||
|
||||
To establish a connection to an Oracle database, create a `session` object using the oracle backend factory together with a connection string:
|
||||
|
||||
session sql(oracle, "service=orcl user=scott password=tiger");
|
||||
```cpp
|
||||
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");
|
||||
|
||||
// or:
|
||||
session sql("oracle://service=orcl user=scott password=tiger");
|
||||
// or:
|
||||
session sql("oracle://service=orcl user=scott password=tiger");
|
||||
|
||||
// or:
|
||||
session sql(oracle, "service=//your_host:1521/your_sid user=scott password=tiger");
|
||||
// or:
|
||||
session sql(oracle, "service=//your_host:1521/your_sid user=scott password=tiger");
|
||||
```
|
||||
|
||||
The set of parameters used in the connection string for Oracle is:
|
||||
|
||||
@@ -53,8 +55,10 @@ If both `user` and `password` are provided, the session will authenticate using
|
||||
|
||||
Once you have created a `session` object as shown above, you can use it to access the database, for example:
|
||||
|
||||
int count;
|
||||
sql << "select count(*) from user_tables", into(count);
|
||||
```cpp
|
||||
int count;
|
||||
sql << "select count(*) from user_tables", into(count);
|
||||
```
|
||||
|
||||
(See the [SOCI basics](../basics.html) and [exchanging data](../exchange.html) documentation for general information on using the `session` class.)#
|
||||
|
||||
@@ -64,43 +68,15 @@ Once you have created a `session` object as shown above, you can use it to acces
|
||||
|
||||
The Oracle backend supports the use of the SOCI `row` class, which facilitates retrieval of data which type is not known at compile time.
|
||||
|
||||
When calling `row::get<T>()`, the type you should pass as `T` depends upon the nderlying database type.<br/> For the Oracle backend, this type mapping is:
|
||||
|
||||
<table>
|
||||
<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></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
When calling `row::get<T>()`, the type you should pass as `T` depends upon the nderlying database type. For the Oracle backend, this type mapping is:
|
||||
|
||||
|Oracle Data Type|SOCI Data Type|`row::get<T>` specializations|
|
||||
|--- |--- |--- |
|
||||
|number (where scale > 0)|dt_double|double|
|
||||
|number(where scale = 0 and precision ≤ `std::numeric_limits<int>::digits10`)|dt_integer|int|
|
||||
|number|dt_long_long|long long|
|
||||
|char, varchar, varchar2|dt_string|std::string|
|
||||
|date|dt_date|std::tm|
|
||||
|
||||
(See the [dynamic resultset binding](../exchange.html#dynamic) documentation for general information on using the `row` class.)
|
||||
|
||||
@@ -108,8 +84,10 @@ When calling `row::get<T>()`, the type you should pass as `T` depends upon the n
|
||||
|
||||
In addition to [binding by position](../exchange.html#bind_position), the Oracle backend supports [binding by name](../exchange.html#bind_name), via an overload of the `use()` function:
|
||||
|
||||
int id = 7;
|
||||
sql << "select name from person where id = :id", use(id, "id")
|
||||
```cpp
|
||||
int id = 7;
|
||||
sql << "select name from person where id = :id", use(id, "id")
|
||||
```
|
||||
|
||||
SOCI's use of ':' to indicate a value to be bound within a SQL string is consistant with the underlying Oracle client library syntax.
|
||||
|
||||
@@ -134,19 +112,21 @@ Oracle rowid's are accessible via SOCI's [rowid](../reference.html#rowid) class.
|
||||
|
||||
The Oracle backend supports selecting into objects of type `statement`, so that you may work with nested sql statements and PL/SQL cursors:
|
||||
|
||||
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();
|
||||
```cpp
|
||||
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';
|
||||
}
|
||||
while (stInner.fetch())
|
||||
{
|
||||
std::cout << name << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
### Stored Procedures
|
||||
|
||||
@@ -158,30 +138,12 @@ SOCI provides access to underlying datbabase APIs via several `get_backend()` fu
|
||||
|
||||
The Oracle backend provides the following concrete classes for navite API access:
|
||||
|
||||
<table>
|
||||
<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>
|
||||
|Accessor Function|Concrete Class|
|
||||
|--- |--- |
|
||||
|session_backend * session::get_backend()|oracle_session_backend|
|
||||
|statement_backend * statement::get_backend()|oracle_statement_backend|
|
||||
|blob_backend * blob::get_backend()|oracle_blob_backend|
|
||||
|rowid_backend * rowid::get_backend()|oracle_rowid_backend|
|
||||
|
||||
## Backend-specific extensions
|
||||
|
||||
@@ -189,19 +151,21 @@ The Oracle backend provides the following concrete classes for navite API access
|
||||
|
||||
The Oracle backend can throw instances of class `oracle_soci_error`, which is publicly derived from `soci_error` and has an additional public `err_num_` member containing the Oracle error code:
|
||||
|
||||
int main()
|
||||
```cpp
|
||||
int main()
|
||||
{
|
||||
try
|
||||
{
|
||||
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;
|
||||
}
|
||||
// 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;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -10,15 +10,18 @@ The SOCI PostgreSQL backend is supported for use with PostgreSQL >= 7.3, althoug
|
||||
|
||||
### Tested Platforms
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr><th>PostgreSQL version</th><th>Operating System</th><th>Compiler</th></tr>
|
||||
<tr><td>9.0</td><td>Mac OS X 10.6.6</td><td>g++ 4.2</td></tr>
|
||||
<tr><td>8.4</td><td>FreeBSD 8.2</td><td>g++ 4.1</td></tr>
|
||||
<tr><td>8.4</td><td>Debian 6</td><td>g++ 4.3</td></tr>
|
||||
<tr><td>8.4</td><td>RedHat 5</td><td>g++ 4.3</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|PostgreSQL|OS|Compiler|
|
||||
|--- |--- |--- |
|
||||
|9.6|Windows Server 2016|MSVC++ 14.1|
|
||||
|9.4|Windows Server 2012 R2|MSVC++ 14.0|
|
||||
|9.4|Windows Server 2012 R2|MSVC++ 12.0|
|
||||
|9.4|Windows Server 2012 R2|MSVC++ 11.0|
|
||||
|9.4|Windows Server 2012 R2|Mingw-w64/GCC 4.8|
|
||||
|9.3|Ubuntu 12.04|g++ 4.6.3|
|
||||
|9.0|Mac OS X 10.6.6|g++ 4.2|
|
||||
|8.4|FreeBSD 8.2|g++ 4.1|
|
||||
|8.4|Debian 6|g++ 4.3|
|
||||
|8.4|RedHat 5|g++ 4.3|
|
||||
|
||||
### Required Client Libraries
|
||||
|
||||
@@ -26,20 +29,23 @@ The SOCI PostgreSQL backend requires PostgreSQL's `libpq` client library.
|
||||
|
||||
Note that the SOCI library itself depends also on `libdl`, so the minimum set of libraries needed to compile a basic client program is:
|
||||
|
||||
-lsoci_core -lsoci_postgresql -ldl -lpq
|
||||
```sh
|
||||
-lsoci_core -lsoci_postgresql -ldl -lpq
|
||||
```
|
||||
|
||||
### Connecting to the Database
|
||||
|
||||
To establish a connection to the PostgreSQL database, create a `session` object using the `postgresql` backend factory together with a connection string:
|
||||
|
||||
```cpp
|
||||
session sql(postgresql, "dbname=mydatabase");
|
||||
|
||||
session sql(postgresql, "dbname=mydatabase");
|
||||
// or:
|
||||
session sql("postgresql", "dbname=mydatabase");
|
||||
|
||||
// or:
|
||||
session sql("postgresql", "dbname=mydatabase");
|
||||
|
||||
// or:
|
||||
session sql("postgresql://dbname=mydatabase");
|
||||
// or:
|
||||
session sql("postgresql://dbname=mydatabase");
|
||||
```
|
||||
|
||||
The set of parameters used in the connection string for PostgreSQL is the same as accepted by the `[PQconnectdb](http://www.postgresql.org/docs/8.3/interactive/libpq.html#LIBPQ-CONNECT)` function from the `libpq` library.
|
||||
|
||||
@@ -49,7 +55,9 @@ In addition to standard PostgreSQL connection parameters, the following can be s
|
||||
|
||||
For example:
|
||||
|
||||
session sql(postgresql, "dbname=mydatabase singlerows=true");
|
||||
```cpp
|
||||
session sql(postgresql, "dbname=mydatabase singlerows=true");
|
||||
```
|
||||
|
||||
If the `singlerows` parameter is set to `true` or `yes`, then queries will be executed in the single-row mode, which prevents the client library from loading full query result set into memory and instead fetches rows one by one, as they are requested by the statement's fetch() function. This mode can be of interest to those users who want to make their client applications more responsive (with more fine-grained operation) by avoiding potentially long blocking times when complete query results are loaded to client's memory.
|
||||
Note that in the single-row operation:
|
||||
@@ -64,58 +72,29 @@ disable it.
|
||||
|
||||
Once you have created a `session` object as shown above, you can use it to access the database, for example:
|
||||
|
||||
int count;
|
||||
sql << "select count(*) from invoices", into(count);
|
||||
```cpp
|
||||
int count;
|
||||
sql << "select count(*) from invoices", into(count);
|
||||
```
|
||||
|
||||
(See the [exchanging data](../basics.html">SOCI basics</a> and <a href="../exchange.html) documentation for general information on using the `session` class.)
|
||||
|
||||
## SOCI Feature Support
|
||||
## SOCI Feature Support
|
||||
|
||||
### Dynamic Binding
|
||||
|
||||
The PostgreSQL backend supports the use of the SOCI `row` class, which facilitates retrieval of data whose type is not known at compile time.
|
||||
|
||||
When calling `row::get<T>()`, the type you should pass as `T` depends upon the underlying database type.<br/> For the PostgreSQL backend, this type mapping is:
|
||||
When calling `row::get<T>()`, the type you should pass as `T` depends upon the underlying database type. For the PostgreSQL backend, this type mapping is:
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>PostgreSQL Data Type</th>
|
||||
<th>SOCI Data Type</th>
|
||||
<th><code>row::get<T></code> specializations</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>numeric, real, double</td>
|
||||
<td><code>dt_double</code></td>
|
||||
<td><code>double</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>boolean, smallint, integer</td>
|
||||
<td><code>dt_integer</code></td>
|
||||
<td><code>int</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>int8</td>
|
||||
<td><code>dt_long_long</code></td>
|
||||
<td><code>long long</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>oid</td>
|
||||
<td><code>dt_integer</code></td>
|
||||
<td><code>unsigned long</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>char, varchar, text, cstring, bpchar</td>
|
||||
<td><code>dt_string</code></td>
|
||||
<td><code>std::string</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>abstime, reltime, date, time, timestamp, timestamptz, timetz</td>
|
||||
<td><code>dt_date</code></td>
|
||||
<td><code>std::tm</code></code></code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|PostgreSQL Data Type|SOCI Data Type|`row::get<T>` specializations|
|
||||
|--- |--- |--- |
|
||||
|numeric, real, double|dt_double|double|
|
||||
|boolean, smallint, integer|dt_integer|int|
|
||||
|int8|dt_long_long|long long|
|
||||
|oid|dt_integer|unsigned long|
|
||||
|char, varchar, text, cstring, bpchar|dt_string|std::string|
|
||||
|abstime, reltime, date, time, timestamp, timestamptz, timetz|dt_date|std::tm|
|
||||
|
||||
(See the [dynamic resultset binding](../exchange.html#dynamic) documentation for general information on using the `row` class.)
|
||||
|
||||
@@ -123,14 +102,18 @@ When calling `row::get<T>()`, the type you should pass as `T` depends upon the u
|
||||
|
||||
In addition to [binding by position](../exchange.html#bind_position), the PostgreSQL backend supports [binding by name](../exchange.html#bind_name), via an overload of the `use()` function:
|
||||
|
||||
int id = 7;
|
||||
sql << "select name from person where id = :id", use(id, "id")
|
||||
```cpp
|
||||
int id = 7;
|
||||
sql << "select name from person where id = :id", use(id, "id")
|
||||
```
|
||||
|
||||
Apart from the portable "colon-name" syntax above, which is achieved by rewriting the query string, the backend also supports the PostgreSQL native numbered syntax:
|
||||
|
||||
int i = 7;
|
||||
int j = 8;
|
||||
sql << "insert into t(x, y) values($1, $2)", use(i), use(j);
|
||||
```cpp
|
||||
int i = 7;
|
||||
int j = 8;
|
||||
sql << "insert into t(x, y) values($1, $2)", use(i), use(j);
|
||||
```
|
||||
|
||||
The use of native syntax is not recommended, but can be nevertheless imposed by switching off the query rewriting. This can be achieved by defining the macro `SOCI_POSTGRESQL_NOBINDBYNAME` and it is actually necessary for PostgreSQL 7.3, in which case binding of use elements is not supported at all. See the [Configuration options](#options) section for details.
|
||||
|
||||
@@ -164,30 +147,12 @@ SOCI provides access to underlying datbabase APIs via several `get_backend()` fu
|
||||
|
||||
The PostgreSQL backend provides the following concrete classes for navite API access:
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>Accessor Function</th>
|
||||
<th>Concrete Class</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>session_backend * session::get_backend()</code></td>
|
||||
<td><code>postgresql_session_backend</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>statement_backend * statement::get_backend()</code></td>
|
||||
<td><code>postgresql_statement_backend</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>blob_backend * blob::get_backend()</code></td>
|
||||
<td><code>postgresql_blob_backend</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>rowid_backend * rowid::get_backend()</code></td>
|
||||
<td><code>postgresql_rowid_backend</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|Accessor Function|Concrete Class|
|
||||
|--- |--- |
|
||||
|session_backend * session::get_backend()|postgresql_session_backend|
|
||||
|statement_backend * statement::get_backend()|postgresql_statement_backend|
|
||||
|blob_backend * blob::get_backend()|postgresql_blob_backend|
|
||||
|rowid_backend * rowid::get_backend()|postgresql_rowid_backend|
|
||||
|
||||
## Backend-specific extensions
|
||||
|
||||
|
||||
@@ -10,20 +10,23 @@ The SOCI SQLite3 backend is supported for use with SQLite3 >= 3.1
|
||||
|
||||
### Tested Platforms
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr><th>SQLite3 version</th><th>Operating System</th><th>Compiler</th></tr>
|
||||
<tr><td>3.5.2</td><td>Mac OS X 10.5</td><td>g++ 4.0.1</td></tr>
|
||||
<tr><td>3.1.3</td><td>Mac OS X 10.4</td><td>g++ 4.0.1</td></tr>
|
||||
<tr><td>3.2.1</td><td>Linux i686 2.6.10-gentoo-r6</td><td>g++ 3.4.5</td></tr>
|
||||
<tr><td>3.3.4</td><td>Ubuntu 5.1</td><td>g++ 4.0.2</td></tr>
|
||||
<tr><td>3.3.4</td><td>Windows XP</td><td>(cygwin) g++ 3.3.4</td></tr>
|
||||
<tr><td>3.3.4</td><td>Windows XP</td><td>Visual C++ 2005 Express Edition</td></tr>
|
||||
<tr><td>3.3.8</td><td>Windows XP</td><td>Visual C++ 2005 Professional</td></tr>
|
||||
<tr><td>3.4.0</td><td>Windows XP</td><td>(cygwin) g++ 3.4.4</td></tr>
|
||||
<tr><td>3.4.0</td><td>Windows XP</td><td>Visual C++ 2005 Express Edition</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|SQLite3|OS|Compiler|
|
||||
|--- |--- |--- |
|
||||
|3.12.1|Windows Server 2016|MSVC++ 14.1|
|
||||
|3.12.1|Windows Server 2012 R2|MSVC++ 14.0|
|
||||
|3.12.1|Windows Server 2012 R2|MSVC++ 12.0|
|
||||
|3.12.1|Windows Server 2012 R2|MSVC++ 11.0|
|
||||
|3.12.1|Windows Server 2012 R2|Mingw-w64/GCC 4.8|
|
||||
|3.7.9|Ubuntu 12.04|g++ 4.6.3|
|
||||
|3.4.0|Windows XP|(cygwin) g++ 3.4.4|
|
||||
|3.4.0|Windows XP|Visual C++ 2005 Express Edition|
|
||||
|3.3.8|Windows XP|Visual C++ 2005 Professional|
|
||||
|3.5.2|Mac OS X 10.5|g++ 4.0.1|
|
||||
|3.3.4|Ubuntu 5.1|g++ 4.0.2|
|
||||
|3.3.4|Windows XP|(cygwin) g++ 3.3.4|
|
||||
|3.3.4|Windows XP|Visual C++ 2005 Express Edition|
|
||||
|3.2.1|Linux i686 2.6.10-gentoo-r6|g++ 3.4.5|
|
||||
|3.1.3|Mac OS X 10.4|g++ 4.0.1|
|
||||
|
||||
### Required Client Libraries
|
||||
|
||||
@@ -33,11 +36,13 @@ The SOCI SQLite3 backend requires SQLite3's `libsqlite3` client library.
|
||||
|
||||
To establish a connection to the SQLite3 database, create a Session object using the `SQLite3` backend factory together with the database file name:
|
||||
|
||||
session sql(sqlite3, "database_filename");
|
||||
```cpp
|
||||
session sql(sqlite3, "database_filename");
|
||||
|
||||
// or:
|
||||
// or:
|
||||
|
||||
session sql("sqlite3", "db=db.sqlite timeout=2 shared_cache=true");
|
||||
session sql("sqlite3", "db=db.sqlite timeout=2 shared_cache=true");
|
||||
```
|
||||
|
||||
The set of parameters used in the connection string for SQLite is:
|
||||
|
||||
@@ -48,8 +53,10 @@ The set of parameters used in the connection string for SQLite is:
|
||||
|
||||
Once you have created a `session` object as shown above, you can use it to access the database, for example:
|
||||
|
||||
int count;
|
||||
sql << "select count(*) from invoices", into(count);
|
||||
```cpp
|
||||
int count;
|
||||
sql << "select count(*) from invoices", into(count);
|
||||
```
|
||||
|
||||
(See the [SOCI basics](../basics.html) and [exchanging data](../exchange.html) documentation for general information on using the `session` class.)
|
||||
|
||||
@@ -63,45 +70,14 @@ When calling `row::get<T>()`, the type you should pass as T depends upon the und
|
||||
|
||||
For the SQLite3 backend, this type mapping is complicated by the fact the SQLite3 does not enforce [types][INTEGER_PRIMARY_KEY] and makes no attempt to validate the type names used in table creation or alteration statements. SQLite3 will return the type as a string, SOCI will recognize the following strings and match them the corresponding SOCI types:
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>SQLite3 Data Type</th>
|
||||
<th>SOCI Data Type</th>
|
||||
<th><code>row::get<T></code> specializations</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>*float*, *double*</td>
|
||||
<td><code>dt_double</code></td>
|
||||
<td><code>double</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>*int8*, *bigint*</td>
|
||||
<td><code>dt_long_long</code></td>
|
||||
<td><code>long long</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>*unsigned big int*</td>
|
||||
<td><code>dt_unsigned_long_long</code></td>
|
||||
<td><code>unsigned long long</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>*int*, *boolean*</td>
|
||||
<td><code>dt_integer</code></td>
|
||||
<td><code>int</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>*text, *char*</td>
|
||||
<td><code>dt_string</code></td>
|
||||
<td><code>std::string</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>*date*, *time*</td>
|
||||
<td><code>dt_date</code></td>
|
||||
<td><code>std::tm</code></code></code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|SQLite3 Data Type|SOCI Data Type|`row::get<T>` specializations|
|
||||
|--- |--- |--- |
|
||||
|*float*, *double*|dt_double|double|
|
||||
|*int8*, *bigint*|dt_long_long|long long|
|
||||
|*unsigned big int*|dt_unsigned_long_long|unsigned long long|
|
||||
|*int*, *boolean*|dt_integer|int|
|
||||
|*text, *char*|dt_string|std::string|
|
||||
|*date*, *time*|dt_date|std::tm|
|
||||
|
||||
[INTEGER_PRIMARY_KEY] : There is one case where SQLite3 enforces type. If a column is declared as "integer primary key", then SQLite3 uses that as an alias to the internal ROWID column that exists for every table. Only integers are allowed in this column.
|
||||
|
||||
@@ -111,14 +87,18 @@ For the SQLite3 backend, this type mapping is complicated by the fact the SQLite
|
||||
|
||||
In addition to [binding by position](../exchange.html#bind_position), the SQLite3 backend supports [binding by name](../exchange.html#bind_name), via an overload of the `use()` function:
|
||||
|
||||
int id = 7;
|
||||
sql << "select name from person where id = :id", use(id, "id")
|
||||
```cpp
|
||||
int id = 7;
|
||||
sql << "select name from person where id = :id", use(id, "id")
|
||||
```
|
||||
|
||||
The backend also supports the SQLite3 native numbered syntax, "one or more literals can be replace by a parameter "?" or ":AAA" or "@AAA" or "$VVV" where AAA is an alphanumeric identifier and VVV is a variable name according to the syntax rules of the TCL programming language." [[1]](http://www.sqlite.org/capi3ref.html#sqlite3_bind_int):
|
||||
|
||||
int i = 7;
|
||||
int j = 8;
|
||||
sql << "insert into t(x, y) values(?, ?)", use(i), use(j);
|
||||
```cpp
|
||||
int i = 7;
|
||||
int j = 8;
|
||||
sql << "insert into t(x, y) values(?, ?)", use(i), use(j);
|
||||
```
|
||||
|
||||
### Bulk Operations
|
||||
|
||||
@@ -150,26 +130,11 @@ SOCI provides access to underlying datbabase APIs via several `get_backend()` fu
|
||||
|
||||
The SQLite3 backend provides the following concrete classes for navite API access:
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>Accessor Function</th>
|
||||
<th>Concrete Class</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>session_backend* session::get_backend()</code></td>
|
||||
<td><code>sqlie3_session_backend</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>statement_backend* statement::get_backend()</code></td>
|
||||
<td><code>sqlite3_statement_backend</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>rowid_backend* rowid::get_backend()</code></td>
|
||||
<td><code>sqlite3_rowid_backend</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|Accessor Function|Concrete Class|
|
||||
|--- |--- |
|
||||
|session_backend* session::get_backend()|sqlie3_session_backend|
|
||||
|statement_backend* statement::get_backend()|sqlite3_statement_backend|
|
||||
|rowid_backend* rowid::get_backend()|sqlite3_rowid_backend|
|
||||
|
||||
## Backend-specific extensions
|
||||
|
||||
|
||||
Reference in New Issue
Block a user