Unverified Commit 125753ff authored by VZ's avatar VZ Committed by GitHub

Merge pull request #614 from Astrinus/master

Documentation fixes: fix links broken during Markdown transition and some (preexisting) typos.

Also provide an example of using rowsets, see #527.
parents 8b00c6bd 1ea06a74
......@@ -110,24 +110,24 @@ 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:
* `operator<<` that is a shortcut forwarder to the equivalent operator of the `once` member. Example:
```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.
* `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.md#sequences) section.
* `get_last_insert_id` returns true if it could retrieve the last value automatically generated by the database for an auto-incremented field. Notice that although this method takes the table name, for some databases, such as Microsoft SQL Server and SQLite, this value is actually global, so you should attempt to retrieve it immediately after performing an insertion.
* `get_query_stream` provides direct access to the stream object that is used to accumulate the query text and exists in particular to allow the user to imbue specific locale to this stream.
* `set_log_stream` and `get_log_stream` functions for setting and getting the current stream object used for basic query logging. By default, it is `NULL`, which means no logging The string value that is actually logged into the stream is one-line verbatim copy of the query string provided by the user, without including any data from the `use` elements. The query is logged exactly once, before the preparation step.
* `get_last_query` retrieves the text of the last used query.
* `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_dummy_from_table` and `get_dummy_from_clause()`: helpers for writing portable DML statements, see [DML helpers](../utilities.md#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.
See [Connections and simple queries](basics.html) for more examples.
See [connection](../connections.md) and [queries](../queries.md) for more examples.
## class connection_parameters
......@@ -230,7 +230,7 @@ int count;
sql << "select count(*) from person", into(count);
```
See [Binding local dat](exchange.html#bind_local) for more examples
See [Binding output data](../binding.md#binding-output-data-into) for more examples
## function use
......@@ -263,7 +263,7 @@ int val = 7;
sql << "insert into numbers(val) values(:val)", use(val);
```
See [Binding local data](exchange.html#bind_local) for more examples.
See [Binding input data](../binding.md#binding-input-data-use) for more examples.
## class statement
......@@ -330,9 +330,9 @@ statement stmt(sql);
* `exchange_for_rowset` as a special case for binding `rowset` objects.
* `get_backend` function that returns the internal pointer to the concrete backend implementation of the statement object. This is provided for advanced users that need access to the functionality that is not otherwise available.
See [Statement preparation and repeated execution](statements.html#preparation) for example uses.
See [Statement preparation and repeated execution](../statements.md) for example uses.
Most of the functions from the `statement` class interface are called automatically, but can be also used explicitly. See [Interfaces](interfaces) for the description of various way to use this interface.
Most of the functions from the `statement` class interface are called automatically, but can be also used explicitly. See [Interfaces](../interfaces.md) for the description of various way to use this interface.
## class procedure
......@@ -352,7 +352,7 @@ public:
The constructor expects the result of using `prepare` on the `session` object.
See [Stored procedures](statements.html#procedures) for examples.
See [Stored procedures](../procedures.md) for examples.
## class type_conversion
......@@ -372,7 +372,7 @@ struct type_conversion
Users are supposed to properly implement the `from_base` and `to_base` functions in their specializations of this template class.
See [Extending SOCI to support custom (user-defined) C++ types](exchange.html#custom_types).
See [Extending SOCI to support custom (user-defined) C++ types](../types.md#user-defined-c-types).
## class row
......@@ -427,7 +427,7 @@ This class contains the following members:
* `operator>>` for convenience stream-like extraction interface. Subsequent calls to this function are equivalent to calling `get` with increasing position parameter, starting from the beginning.
* `skip` and `reset_get_counter` allow to change the order of data extraction for the above operator.
See [Dynamic resultset binding](exchange.html#dynamic) for examples.
See [Dynamic resultset binding](../types.md#dynamic-binding) for examples.
## class column_properties
......@@ -447,7 +447,7 @@ This class contains the following members:
* `get_name` function that returns the name of the column.
* `get_data_type` that returns the type of the column.
See [Dynamic resultset binding](exchange.html#dynamic) for examples.
See [Dynamic resultset binding](../types.md#dynamic-binding) for examples.
## class values
......@@ -498,7 +498,7 @@ This class contains the same members as the `row` class (with the same meaning)
* `set` function for storing values in named columns or in subsequent positions.
* `operator<<` for convenience.
See [Object-relational mapping](exchange.html#object_relational) for examples.
See [Object-relational mapping](../types.md#object-relational-mapping) for examples.
## class blob
......@@ -531,7 +531,7 @@ This class contains the following members:
* `trim` function that truncates the existing data to the new length.
* `get_backend` function that returns the internal pointer to the concrete backend implementation of the BLOB object. This is provided for advanced users that need access to the functionality that is not otherwise available.
See [Large objects (BLOBs)](exchange.html#blob) for more discussion.
See [Large objects (BLOBs)](../lobs.md) for more discussion.
## class rowid
......
......@@ -59,7 +59,7 @@ int count;
sql << "select count(*) from user_tables", into(count);
```
(See the [SOCI basics](../basics.html) and [exchanging data](../exchange.html) documentation
(See the [connection](../connections.md) and [data binding](../binding.md) documentation
for general information on using the `session` class.)
## SOCI Feature Support
......@@ -84,13 +84,13 @@ For the Firebird backend, this type mapping 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
(See the [dynamic resultset binding](../types.md#dynamic-binding) 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](../binding.md#binding-by-position), the Firebird backend supports
[binding by name](../binding.md#binding-by-name), via an overload of the `use()` function:
int id = 7;
sql << "select name from person where id = :id", use(id, "id")
......@@ -100,12 +100,12 @@ since the underlying API used by the backend doesn't provide this feature.
### Bulk Operations
The Firebird backend has full support for SOCI [bulk operations](../statements.html#bulk) interface.
The Firebird backend has full support for SOCI [bulk operations](../binding.md#bulk-operations) interface.
This feature is also supported by emulation.
### Transactions
[Transactions](../statements.html#transactions) are also fully supported by the Firebird backend.
[Transactions](../transactions.md) 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.
......@@ -113,7 +113,7 @@ committed in `session` destructor.
### BLOB Data Type
The Firebird backend supports working with data stored in columns of type Blob,
via SOCI `[BLOB](../exchange.html#blob)` class.
via SOCI [BLOB](../lobs.md) 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 -
......@@ -130,12 +130,12 @@ This feature is not supported by Firebird backend.
### Stored Procedures
Firebird stored procedures can be executed by using SOCI [Procedure](../statements.html#procedures) class.
Firebird stored procedures can be executed by using SOCI [Procedure](../procedures.md) class.
## Native API Access
SOCI provides access to underlying datbabase APIs via several getBackEnd() functions,
as described in the [beyond SOCI](../beyond.html) documentation.
as described in the [beyond SOCI](../beyond.md) documentation.
The Firebird backend provides the following concrete classes for navite API access:
......
......@@ -2,12 +2,12 @@
Follow the links to learn more about each backend and detailed supported features.
|Oracle|PostgreSQL|MySQL|SQLite3|Firebird|ODBC|DB2|
|--- |--- |--- |--- |--- |--- |--- |
|Binding by Name|YES|YES (>=8.0)|YES|YES|YES|YES|YES|
||[Oracle](oracle.md)|[PostgreSQL](postgresql.md)|[MySQL](mysql.md)|[SQLite3](sqlite3.md)|[Firebird](firebird.md)|[ODBC](odbc.md)|[DB2](db2.md)|
|--- |--- |--- |--- |--- |--- |--- |--- |
|Binding by Name|YES|YES (&ge;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|
|Transactions|YES|YES|YES (&ge;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|
......
......@@ -55,7 +55,8 @@ 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.)
(See the [connection](../connections.md) and [data binding](../binding.md) documentation
for general information on using the `session` class.)
## SOCI Feature Support
......@@ -63,7 +64,7 @@ Once you have created a `session` object as shown above, you can use it to acces
The MySQL 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&lt;T&gt;()`, the type you should pass as `T` depends upon the underlying database type.
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:
|MySQL Data Type|SOCI Data Type|`row::get<T>` specializations|
......@@ -76,12 +77,13 @@ For the MySQL backend, this type mapping is:
|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.)
(See the [dynamic resultset binding](../types.md#dynamic-binding) documentation for general information
on using the `Row` class.)
### Binding by Name
In addition to [binding by position](../exchange.html#bind_position), the MySQL backend supports
[binding by name](../exchange.html#bind_name), via an overload of the `use()` function:
In addition to [binding by position](../binding.md#binding-by-position), the MySQL backend supports
[binding by name](../binding.md#binding-by-name), via an overload of the `use()` function:
int id = 7;
sql << "select name from person where id = :id", use(id, "id")
......@@ -90,7 +92,9 @@ It should be noted that parameter binding of any kind is supported only by means
### Bulk Operations
[Transactions](../statements.html#transactions) are also supported by the MySQL backend. Please note, however, that transactions can only be used when the MySQL server supports them (it depends on options used during the compilation of the server; typically, but not always, servers >=4.0 support transactions and earlier versions do not) and only with appropriate table types.
### Transactions
[Transactions](../transactions.md) are also supported by the MySQL backend. Please note, however, that transactions can only be used when the MySQL server supports them (it depends on options used during the compilation of the server; typically, but not always, servers >=4.0 support transactions and earlier versions do not) and only with appropriate table types.
### BLOB Data Type
......@@ -108,11 +112,11 @@ Nested statements are not supported by the MySQL backend.
### Stored Procedures
MySQL version 5.0 and later supports two kinds of stored routines: stored procedures and stored functions (for details, please consult the [procedure MySQL documentation](http://dev.mysql.com/doc/refman/5.0/en/stored-procedures.html)). Stored functions can be executed by using SOCI's [procedure class](../statements.html#procedures). There is currently no support for stored procedures.
MySQL version 5.0 and later supports two kinds of stored routines: stored procedures and stored functions (for details, please consult the [procedure MySQL documentation](http://dev.mysql.com/doc/refman/5.0/en/stored-procedures.html)). Stored functions can be executed by using SOCI's [procedure class](../procedures.md). There is currently no support for stored procedures.
## Native API Access
SOCI provides access to underlying datbabase APIs via several `get_backend()` functions, as described in the [Beyond SOCI](../beyond.html) documentation.
SOCI provides access to underlying datbabase APIs via several `get_backend()` functions, as described in the [Beyond SOCI](../beyond.md) documentation.
The MySQL backend provides the following concrete classes for native API access:
......
......@@ -48,7 +48,7 @@ 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.)
(See the [connection](../connections.md) and [data binding](../binding.md) documentation for general information on using the `session` class.)
## SOCI Feature Support
......@@ -68,11 +68,11 @@ For the ODBC backend, this type mapping is:
Not all ODBC drivers support all datatypes.
(See the [dynamic resultset binding](../exchange.html#dynamic) documentation for general information on using the `row` class.)
(See the [dynamic resultset binding](../types.md#dynamic-binding) documentation for general information on using the `row` class.)
### 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:
In addition to [binding by position](../binding.md#binding-by-position), the ODBC backend supports [binding by name](../binding.md#binding-by-name), via an overload of the `use()` function:
```cpp
int id = 7;
......@@ -89,7 +89,7 @@ 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:
The ODBC backend has support for SOCI's [bulk operations](../binding.md#bulk-operations) interface. Not all ODBC drivers support bulk operations, the following is a list of some tested backends:
|ODBC Driver|Bulk Read|Bulk Insert|
|--- |--- |--- |
......@@ -100,7 +100,7 @@ The ODBC backend has support for SOCI's [bulk operations](../statements.html#bul
### Transactions
[Transactions](../statements.html#transactions) are also fully supported by the ODBC backend, provided that they are supported by the underlying database.
[Transactions](../transactions.md) are also fully supported by the ODBC backend, provided that they are supported by the underlying database.
### BLOB Data Type
......@@ -120,7 +120,7 @@ Not currently supported.
## 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.md) documentation.
The ODBC backend provides the following concrete classes for navite API access:
......
......@@ -60,7 +60,7 @@ 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.)#
(See the [connection](../connections.md) and [data binding](../binding.md) documentation for general information on using the `session` class.)
## SOCI Feature Support
......@@ -68,7 +68,7 @@ sql << "select count(*) from user_tables", into(count);
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. For the Oracle 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 Oracle backend, this type mapping is:
|Oracle Data Type|SOCI Data Type|`row::get<T>` specializations|
|--- |--- |--- |
......@@ -78,11 +78,11 @@ When calling `row::get<T>()`, the type you should pass as `T` depends upon the n
|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.)
(See the [dynamic resultset binding](../types.md#dynamic-binding) documentation for general information on using the `row` class.)
### Binding by Name
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:
In addition to [binding by position](../binding.md#binding-by-position), the Oracle backend supports [binding by name](../binding.md#binding-by-name), via an overload of the `use()` function:
```cpp
int id = 7;
......@@ -93,7 +93,7 @@ SOCI's use of ':' to indicate a value to be bound within a SQL string is consist
### Bulk Operations
The Oracle backend has full support for SOCI's [bulk operations](../statements.html#bulk) interface.
The Oracle backend has full support for SOCI's [bulk operations](../binding.md#bulk-operations) interface.
### Transactions
......@@ -102,11 +102,11 @@ although transactions with non-default isolation levels have to be managed by ex
### blob Data Type
The Oracle backend supports working with data stored in columns of type Blob, via SOCI's [blob](../exchange.html#blob) class.
The Oracle backend supports working with data stored in columns of type Blob, via SOCI's [blob](../lobs.md) class.
### rowid Data Type
Oracle rowid's are accessible via SOCI's [rowid](../reference.html#rowid) class.
Oracle rowid's are accessible via SOCI's [rowid](../api/client.md#class-rowid) class.
### Nested Statements
......@@ -130,11 +130,11 @@ while (stInner.fetch())
### Stored Procedures
Oracle stored procedures can be executed by using SOCI's [procedure](../statements.html#procedures) class.
Oracle stored procedures can be executed by using SOCI's [procedure](../procedures.md) class.
## Native API Access
SOCI provides access to underlying datbabase APIs via several `get_backend()` functions, as described in the [Beyond SOCI](../beyond.html) documentation.
SOCI provides access to underlying datbabase APIs via several `get_backend()` functions, as described in the [Beyond SOCI](../beyond.md) documentation.
The Oracle backend provides the following concrete classes for navite API access:
......@@ -158,12 +158,12 @@ int main()
{
// regular code
}
catch (oracle_soci_error const &amp; e)
catch (oracle_soci_error const & e)
{
cerr << "Oracle error: " << e.err_num_
<< " " << e.what() << endl;
}
catch (exception const &amp;e)
catch (exception const & e)
{
cerr << "Some other error: "<< e.what() << endl;
}
......
......@@ -47,7 +47,7 @@ session sql("postgresql", "dbname=mydatabase");
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.
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.
In addition to standard PostgreSQL connection parameters, the following can be set:
......@@ -77,7 +77,7 @@ 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.)
(See the [connection](../connections.md) and [data binding](../binding.md) documentation for general information on using the `session` class.)
## SOCI Feature Support
......@@ -96,11 +96,11 @@ When calling `row::get<T>()`, the type you should pass as `T` depends upon the u
|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.)
(See the [dynamic resultset binding](../types.md#dynamic-binding) documentation for general information on using the `row` class.)
### Binding by Name
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:
In addition to [binding by position](../binding.md#binding-by-position), the PostgreSQL backend supports [binding by name](../binding.md#binding-by-name), via an overload of the `use()` function:
```cpp
int id = 7;
......@@ -119,19 +119,19 @@ The use of native syntax is not recommended, but can be nevertheless imposed by
### Bulk Operations
The PostgreSQL backend has full support for SOCI's [bulk operations](../statements.html#bulk) interface.
The PostgreSQL backend has full support for SOCI's [bulk operations](../binding.md#bulk-operations) interface.
### Transactions
[Transactions](../statements.html#transactions) are also fully supported by the PostgreSQL backend.
[Transactions](../transactions.md) are also fully supported by the PostgreSQL backend.
### blob Data Type
The PostgreSQL backend supports working with data stored in columns of type Blob, via SOCI's [blob](../exchange.html#blob) class with the exception that trimming is not supported.
The PostgreSQL backend supports working with data stored in columns of type Blob, via SOCI's [blob](../lobs.md) class with the exception that trimming is not supported.
### rowid Data Type
The concept of row identifier (OID in PostgreSQL) is supported via SOCI's [rowid](../reference.html#rowid) class.
The concept of row identifier (OID in PostgreSQL) is supported via SOCI's [rowid](../api/client.md#class-rowid) class.
### Nested Statements
......@@ -139,11 +139,11 @@ Nested statements are not supported by PostgreSQL backend.
### Stored Procedures
PostgreSQL stored procedures can be executed by using SOCI's [procedure](../statements.html#procedures) class.
PostgreSQL stored procedures can be executed by using SOCI's [procedure](../procedures.md) class.
## Native API Access
SOCI provides access to underlying datbabase APIs via several `get_backend()` functions, as described in the [beyond SOCI](../beyond.html) documentation.
SOCI provides access to underlying datbabase APIs via several `get_backend()` functions, as described in the [beyond SOCI](../beyond.md) documentation.
The PostgreSQL backend provides the following concrete classes for navite API access:
......@@ -166,6 +166,6 @@ format of UUID on output. See the test `test_uuid_column_type_support` for usage
To support older PostgreSQL versions, the following configuration macros are recognized:
* `SOCI_POSTGRESQL_NOBINDBYNAME` - switches off the query rewriting.
* `SOCI_POSTGRESQL_NOPARAMS` - disables support for parameterized queries (binding of use elements),automatically imposes also the `SOCI_POSTGRESQL_NOBINDBYNAME` macro. It is necessary for PostgreSQL 7.3.
* `SOCI_POSTGRESQL_NOPARAMS` - disables support for parameterized queries (binding of use elements), automatically imposes also the `SOCI_POSTGRESQL_NOBINDBYNAME` macro. It is necessary for PostgreSQL 7.3.
* `SOCI_POSTGRESQL_NOPREPARE` - disables support for separate query preparation, which in this backend is significant only in terms of optimization. It is necessary for PostgreSQL 7.3 and 7.4.
* `SOCI_POSTGRESQL_NOSINLGEROWMODE` - disable single mode retrieving query results row-by-row. It is necessary for PostgreSQL prior to version 9.
# SQLite3 Backend Reference
SOCI backend for accessign SQLite 3 database.
SOCI backend for accessing SQLite 3 database.
## Prerequisites
......@@ -47,7 +47,7 @@ session sql("sqlite3", "db=db.sqlite timeout=2 shared_cache=true");
The set of parameters used in the connection string for SQLite is:
* `dbname` or `db`
* `timeout` - set sqlite busy timeout (in seconds) ([link](http://www.sqlite.org/c3ref/busy_timeout.html)
* `timeout` - set sqlite busy timeout (in seconds) ([link](http://www.sqlite.org/c3ref/busy_timeout.html))
* `synchronous` - set the pragma synchronous flag ([link](http://www.sqlite.org/pragma.html#pragma_synchronous))
* `shared_cache` - should be `true` ([link](http://www.sqlite.org/c3ref/enable_shared_cache.html))
......@@ -58,7 +58,7 @@ 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.)
(See the [connection](../connections.md) and [data binding](../binding.md) documentation for general information on using the `session` class.)
## SOCI Feature Support
......@@ -81,11 +81,11 @@ For the SQLite3 backend, this type mapping is complicated by the fact the SQLite
[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.
(See the [dynamic resultset binding](../exchange.html#dynamic) documentation for general information on using the `row` class.)
(See the [dynamic resultset binding](../types.md#dynamic-binding) documentation for general information on using the `row` class.)
### Binding by Name
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:
In addition to [binding by position](../binding.md#binding-by-position), the SQLite3 backend supports [binding by name](../binding.md#binding-by-name), via an overload of the `use()` function:
```cpp
int id = 7;
......@@ -102,15 +102,15 @@ sql << "insert into t(x, y) values(?, ?)", use(i), use(j);
### Bulk Operations
The SQLite3 backend has full support for SOCI's [bulk operations](../statements.html#bulk) interface. However, this support is emulated and is not native.
The SQLite3 backend has full support for SOCI's [bulk operations](../binding.md#bulk-operations) interface. However, this support is emulated and is not native.
### Transactions
[Transactions](../statements.html#transactions) are also fully supported by the SQLite3 backend.
[Transactions](../transactions.md) are also fully supported by the SQLite3 backend.
### BLOB Data Type
The SQLite3 backend supports working with data stored in columns of type Blob, via SOCI's blob class. Because of SQLite3 general typelessness the column does not have to be declared any particular type.
The SQLite3 backend supports working with data stored in columns of type Blob, via SOCI's [BLOB](../lobs.md) class. Because of SQLite3 general typelessness the column does not have to be declared any particular type.
### RowID Data Type
......@@ -126,7 +126,7 @@ Stored procedures are not supported by SQLite3 backend
## Native API Access
SOCI provides access to underlying datbabase APIs via several `get_backend()` functions, as described in the [beyond SOCI](../beyond.html) documentation.
SOCI provides access to underlying datbabase APIs via several `get_backend()` functions, as described in the [beyond SOCI](../beyond.md) documentation.
The SQLite3 backend provides the following concrete classes for navite API access:
......
......@@ -19,7 +19,7 @@ sql << "select name from person where id = 7", into(name);
In the above examples, some data is retrieved from the database and transmitted *into* the given local variable.
There should be as many `into` elements as there are expected columns in the result (see [dynamic resultset binding](#dynamic") for the exception to this rule).
There should be as many `into` elements as there are expected columns in the result (see [dynamic resultset binding](types.md#dynamic-binding) for the exception to this rule).
## Binding input data (use)
......
......@@ -63,7 +63,7 @@ Notice that you need to `#include<soci-odbc.h>` to obtain the option name declar
The existing options are described in the backend-specific part of the documentation.
IBM DB2 driver for ODBC and CLI also support the driver completion requests.
So, the DB2 backend provides similar option `db2_option_driver_complete` with `#include <soci-db1.h>` required to obtain the option name.
So, the DB2 backend provides similar option `db2_option_driver_complete` with `#include <soci-db2.h>` required to obtain the option name.
### Environment configuration
......@@ -107,7 +107,7 @@ The rules for backend naming are the same as with the constructors described abo
The session can be also explicitly `close`d and `reconnect`ed, which can help with basic session error recovery.
The `reconnect` function has no parameters and attempts to use the same values as those provided with earlier constructor or `open` calls.
See also the page devoted to [multithreading](multithreading.html) for a detailed description of connection pools.
See also the page devoted to [multithreading](multithreading.md) for a detailed description of connection pools.
It is possible to have many active `session`s at the same time, even using different backends.
......@@ -115,15 +115,16 @@ It is possible to have many active `session`s at the same time, even using diffe
The following backend factories are currently (as of 3.1.0 release) available:
* [mysql](backends/mysql.html) (requires `#include "soci-mysql.h"`)
* [oracle](backends/oracle.html) (requires `#include "soci-oracle.h"`)
* [postgresql](backends/postgresql.html) (requires `#include "soci-postgresql.h"`)
* [mysql](backends/mysql.md) (requires `#include "soci-mysql.h"`)
* [oracle](backends/oracle.md) (requires `#include "soci-oracle.h"`)
* [postgresql](backends/postgresql.md) (requires `#include "soci-postgresql.h"`)
The following backends are also available, with various levels of completeness:
* [sqlite3](backends/sqlite3.html) (requires `#include "soci-sqlite3.h"`)
* [odbc](backends/odbc.html) (requires `#include "soci-odbc.h"`)
* [firebird](backends/firebird.html) (requires `#include "soci-firebird.h"`)
* [sqlite3](backends/sqlite3.md) (requires `#include "soci-sqlite3.h"`)
* [odbc](backends/odbc.md) (requires `#include "soci-odbc.h"`)
* [firebird](backends/firebird.md) (requires `#include "soci-firebird.h"`)
* [db2](backends/db2.md) (requires `#include "soci-db2.h"`)
## Connection failover
......
......@@ -99,4 +99,4 @@ sql << "insert into person(id, name) values(:id, :name)",
use(ids), use(name, nameIndicators);
```
See also [Integration with Boost](boost.html) to learn how the Boost.Optional library can be used to handle null data conditions in a more natural way.
See also [Integration with Boost](boost.md) to learn how the Boost.Optional library can be used to handle null data conditions in a more natural way.
This diff is collapsed.
......@@ -76,7 +76,7 @@ soci_destroy_session(sql);
The *simple* interface supports single and bulk data exchange for static binding.
Dynamic row description is not supported in this release.
See [Simple client interface](/reference.html#simpleclient) reference documentation for more details.
See [Simple client interface](api/client.md#simple-client-interface) reference documentation for more details.
## Low-level backend interface
......
......@@ -46,9 +46,9 @@ Other backends can be added to the library in the future or by the user himself,
The `parameters` component of the `Connection_String` depends on the given backend, please see the documentation of the main SOCI project for the meaning and recognized options. The web pages related to the backends above are:
* [Oracle](http://soci.sourceforge.net/doc/backends/oracle.html)
* [PostgreSQL](http://soci.sourceforge.net/doc/backends/postgresql.html)
* [MySQL](http://soci.sourceforge.net/doc/backends/mysql.html)
* [Oracle](../../backends/oracle.md)
* [PostgreSQL](../../backends/postgresql.md)
* [MySQL](../../backends/mysql.md)
The `Open` operation can be called only in the disconnected state (which changes the state of `Session` object to connected). The `Close` operation can be called in any state (provided that the session is not associated with the connection pool, see below) and after that the `Session` is in the disconnected state.
......
......@@ -16,7 +16,7 @@ connection_pool pool(poolSize);
for (size_t i = 0; i != poolSize; ++i)
{
session &amp; sql = pool.at(i);
session & sql = pool.at(i);
sql.open("postgresql://dbname=mydb");
}
......@@ -44,4 +44,4 @@ This way, the connection pool guarantees that its session objects are never used
Note that the above scheme is the simplest way to use the connection pool, but it is also constraining in the fact that the `session`'s constructor can *block* waiting for the availability of some entry in the pool.
For more demanding users there are also low-level functions that allow to lease sessions from the pool with timeout on wait.
Please consult the [reference](reference.html) for details.
Please consult the [reference](api/client.md) for details.
......@@ -52,7 +52,7 @@ sql << "DELETE FROM item";
* defined as function object:
```cpp
struct order : std::unary_function<std::string, std::string&gt;
struct order : std::unary_function<std::string, std::string>
{
order(std::string const&amp; by) : by_(by) {}
......
......@@ -70,7 +70,7 @@ for (rowset<int>::const_iterator it = rs.begin(); it != rs.end(); ++it)
}
```
Another example shows how to retrieve more complex results, where `rowset` elements are of type `row` and therefore use [dynamic bindings](exchange.html#dynamic):
Another example shows how to retrieve more complex results, where `rowset` elements are of type `row` and therefore use [dynamic bindings](types.md#dynamic-binding):
```cpp
// person table has 4 columns
......@@ -100,6 +100,28 @@ std::copy(rs.begin(), rs.end(), std::ostream_iterator<std::string>(std::cout, "\
Above, the query result contains a single column which is bound to `rowset` element of type of `std::string`.
All records are sent to standard output using the `std::copy` algorithm.
If you need to use the Core interface with `rowset`, the following example shows how:
```cpp
row r;
statement st(sql);
st.alloc();
st.prepare("select values from numbers");
st.define_and_bind();
// after define_and_bind and before execute
st.exchange_for_rowset(into(r));
st.execute(false);
rowset_iterator<row> it(st, r);
rowset_iterator<row> end;
for (; it != end; ++it) {
// ... access *it
}
```
## Bulk operations
When using some databases, further performance improvements may be possible by having the underlying database API group operations together to reduce network roundtrips.
......
......@@ -9,7 +9,7 @@ The following types are currently supported for use with `into` and `use` expres
* `char` (for character values)
* `short`, `int`, `unsigned long`, `long long`, `double` (for numeric values)
* `std::string` (for string values)
* `std::tm``` (for datetime values)
* `std::tm` (for datetime values)
* `soci::statement` (for nested statements and PL/SQL cursors)
* `soci::blob` (for Binary Large OBjects)
* `soci::row_id` (for row identifiers)
......@@ -99,7 +99,7 @@ The type `T` parameter that should be passed to `row::get<T>()` depends on the S
| `dt_date` | `std::tm` |
The mapping of underlying database column types to SOCI datatypes is database specific.
See the [backend documentation](backends/index.html) for details.
See the [backend documentation](backends/index.md) for details.
The `row` also provides access to indicators for each column:
......@@ -200,9 +200,9 @@ sql << "select count(*) from person", into(i);
cout << "We have " << i.get() << " persons in the database.\n";
```
Note that there is a number of types from the Boost library integrated with SOCI out of the box, see [Integration with Boost](boost.html) for complete description. Use these as examples of conversions for more complext data types.
Note that there is a number of types from the Boost library integrated with SOCI out of the box, see [Integration with Boost](boost.md) for complete description. Use these as examples of conversions for more complext data types.
Another possibility to extend SOCI with custom data types is to use the `into_type<T<` and `use_type<T<` class templates, which specializations can be user-provided. These specializations need to implement the interface defined by, respectively, the `into_type_base` and `use_type_base`
Another possibility to extend SOCI with custom data types is to use the `into_type<T>` and `use_type<T>` class templates, which specializations can be user-provided. These specializations need to implement the interface defined by, respectively, the `into_type_base` and `use_type_base`
classes.
Note that when specializing these template classes the only convention is that when the indicator
......
......@@ -18,7 +18,7 @@ pages:
- Data Indicators: indicators.md
- Data Types: types.md
- LOBs: lobs.md
- Statemets: statements.md
- Statements: statements.md
- Transactions: transactions.md
- Procedures: procedures.md
- Errors: errors.md
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment