Unverified Commit 1ea06a74 authored by Astrinus's avatar Astrinus Committed by GitHub

Merge pull request #1 from Astrinus/docs-refactoring

Docs refactoring
parents 8b00c6bd efbc6c90
...@@ -110,24 +110,24 @@ statement st = (sql.prepare << ...@@ -110,24 +110,24 @@ statement st = (sql.prepare <<
"insert into numbers(value) values(:val)", use(i)); "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 ```cpp
sql << "drop table persons"; sql << "drop table persons";
``` ```
* `got_data` returns true if the last executed query had non-empty result. * `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_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. * `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. * `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. * `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). * `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` 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. See [connection](../connections.md) and [queries](../queries.md) for more examples.
## class connection_parameters ## class connection_parameters
...@@ -230,7 +230,7 @@ int count; ...@@ -230,7 +230,7 @@ int count;
sql << "select count(*) from person", into(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 ## function use
...@@ -263,7 +263,7 @@ int val = 7; ...@@ -263,7 +263,7 @@ int val = 7;
sql << "insert into numbers(val) values(:val)", use(val); 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 ## class statement
...@@ -330,9 +330,9 @@ statement stmt(sql); ...@@ -330,9 +330,9 @@ statement stmt(sql);
* `exchange_for_rowset` as a special case for binding `rowset` objects. * `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. * `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 ## class procedure
...@@ -352,7 +352,7 @@ public: ...@@ -352,7 +352,7 @@ public:
The constructor expects the result of using `prepare` on the `session` object. 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 ## class type_conversion
...@@ -372,7 +372,7 @@ struct 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. 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 ## class row
...@@ -427,7 +427,7 @@ This class contains the following members: ...@@ -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. * `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. * `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 ## class column_properties
...@@ -447,7 +447,7 @@ This class contains the following members: ...@@ -447,7 +447,7 @@ This class contains the following members:
* `get_name` function that returns the name of the column. * `get_name` function that returns the name of the column.
* `get_data_type` that returns the type 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 ## class values
...@@ -498,7 +498,7 @@ This class contains the same members as the `row` class (with the same meaning) ...@@ -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. * `set` function for storing values in named columns or in subsequent positions.
* `operator<<` for convenience. * `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 ## class blob
...@@ -531,7 +531,7 @@ This class contains the following members: ...@@ -531,7 +531,7 @@ This class contains the following members:
* `trim` function that truncates the existing data to the new length. * `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. * `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 ## class rowid
......
...@@ -59,7 +59,7 @@ int count; ...@@ -59,7 +59,7 @@ int count;
sql << "select count(*) from user_tables", into(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.) for general information on using the `session` class.)
## SOCI Feature Support ## SOCI Feature Support
...@@ -84,13 +84,13 @@ For the Firebird backend, this type mapping is: ...@@ -84,13 +84,13 @@ For the Firebird backend, this type mapping is:
[^1] 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. 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.) on using the `Row` class.)
### Binding by Name ### Binding by Name
In addition to [binding by position](../exchange.html#bind_position), the Firebird backend supports In addition to [binding by position](../binding.md#binding-by-position), the Firebird backend supports
[binding by name](../exchange.html#bind_name), via an overload of the `use()` function: [binding by name](../binding.md#binding-by-name), via an overload of the `use()` function:
int id = 7; int id = 7;
sql << "select name from person where id = :id", use(id, "id") 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. ...@@ -100,12 +100,12 @@ since the underlying API used by the backend doesn't provide this feature.
### Bulk Operations ### 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. This feature is also supported by emulation.
### Transactions ### 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 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 started by explicitly calling `begin()` before. The current transaction is automatically
committed in `session` destructor. committed in `session` destructor.
...@@ -113,7 +113,7 @@ committed in `session` destructor. ...@@ -113,7 +113,7 @@ committed in `session` destructor.
### BLOB Data Type ### BLOB Data Type
The Firebird backend supports working with data stored in columns of type Blob, 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. 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 - 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. ...@@ -130,12 +130,12 @@ This feature is not supported by Firebird backend.
### Stored Procedures ### 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 ## Native API Access
SOCI provides access to underlying datbabase APIs via several getBackEnd() functions, 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: The Firebird backend provides the following concrete classes for navite API access:
......
...@@ -2,12 +2,12 @@ ...@@ -2,12 +2,12 @@
Follow the links to learn more about each backend and detailed supported features. Follow the links to learn more about each backend and detailed supported features.
|Oracle|PostgreSQL|MySQL|SQLite3|Firebird|ODBC|DB2| ||[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 (>=8.0)|YES|YES|YES|YES|YES| |Binding by Name|YES|YES (&ge;8.0)|YES|YES|YES|YES|YES|
|Dynamic Binding|YES|YES|YES|YES|YES|YES| |Dynamic Binding|YES|YES|YES|YES|YES|YES|
|Bulk Operations|YES|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| |BLOB Data Type|YES|YES|YES (mapped to `std::string`)|YES|YES|NO|NO|
|RowID Data Type|YES|YES|NO|NO|NO|NO|NO| |RowID Data Type|YES|YES|NO|NO|NO|NO|NO|
|Nested Statements|YES|NO|NO|NO|NO|NO|YES| |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 ...@@ -55,7 +55,8 @@ Once you have created a `session` object as shown above, you can use it to acces
int count; int count;
sql << "select count(*) from invoices", into(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 ## SOCI Feature Support
...@@ -63,7 +64,7 @@ Once you have created a `session` object as shown above, you can use it to acces ...@@ -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. 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: For the MySQL backend, this type mapping is:
|MySQL Data Type|SOCI Data Type|`row::get<T>` specializations| |MySQL Data Type|SOCI Data Type|`row::get<T>` specializations|
...@@ -76,12 +77,13 @@ For the MySQL backend, this type mapping is: ...@@ -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| |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| |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 ### Binding by Name
In addition to [binding by position](../exchange.html#bind_position), the MySQL backend supports In addition to [binding by position](../binding.md#binding-by-position), the MySQL backend supports
[binding by name](../exchange.html#bind_name), via an overload of the `use()` function: [binding by name](../binding.md#binding-by-name), via an overload of the `use()` function:
int id = 7; int id = 7;
sql << "select name from person where id = :id", use(id, "id") 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 ...@@ -90,7 +92,9 @@ It should be noted that parameter binding of any kind is supported only by means
### Bulk Operations ### 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 ### BLOB Data Type
...@@ -108,11 +112,11 @@ Nested statements are not supported by the MySQL backend. ...@@ -108,11 +112,11 @@ Nested statements are not supported by the MySQL backend.
### Stored Procedures ### 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 ## 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: The MySQL backend provides the following concrete classes for native API access:
......
...@@ -48,7 +48,7 @@ int count; ...@@ -48,7 +48,7 @@ int count;
sql << "select count(*) from invoices", into(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 ## SOCI Feature Support
...@@ -68,11 +68,11 @@ For the ODBC backend, this type mapping is: ...@@ -68,11 +68,11 @@ For the ODBC backend, this type mapping is:
Not all ODBC drivers support all datatypes. 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 ### 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 ```cpp
int id = 7; int id = 7;
...@@ -89,7 +89,7 @@ sql << "insert into t(x, y) values(?, ?)", use(i), use(j); ...@@ -89,7 +89,7 @@ sql << "insert into t(x, y) values(?, ?)", use(i), use(j);
### Bulk Operations ### 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| |ODBC Driver|Bulk Read|Bulk Insert|
|--- |--- |--- | |--- |--- |--- |
...@@ -100,7 +100,7 @@ The ODBC backend has support for SOCI's [bulk operations](../statements.html#bul ...@@ -100,7 +100,7 @@ The ODBC backend has support for SOCI's [bulk operations](../statements.html#bul
### Transactions ### 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 ### BLOB Data Type
...@@ -120,7 +120,7 @@ Not currently supported. ...@@ -120,7 +120,7 @@ Not currently supported.
## Native API Access ## 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: The ODBC backend provides the following concrete classes for navite API access:
......
...@@ -60,7 +60,7 @@ int count; ...@@ -60,7 +60,7 @@ int count;
sql << "select count(*) from user_tables", into(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 ## SOCI Feature Support
...@@ -68,7 +68,7 @@ sql << "select count(*) from user_tables", into(count); ...@@ -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. 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| |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 ...@@ -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| |char, varchar, varchar2|dt_string|std::string|
|date|dt_date|std::tm| |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 ### 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 ```cpp
int id = 7; int id = 7;
...@@ -93,7 +93,7 @@ SOCI's use of ':' to indicate a value to be bound within a SQL string is consist ...@@ -93,7 +93,7 @@ SOCI's use of ':' to indicate a value to be bound within a SQL string is consist
### Bulk Operations ### 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 ### Transactions
...@@ -102,11 +102,11 @@ although transactions with non-default isolation levels have to be managed by ex ...@@ -102,11 +102,11 @@ although transactions with non-default isolation levels have to be managed by ex
### blob Data Type ### 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 ### 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 ### Nested Statements
...@@ -130,11 +130,11 @@ while (stInner.fetch()) ...@@ -130,11 +130,11 @@ while (stInner.fetch())
### Stored Procedures ### 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 ## 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: The Oracle backend provides the following concrete classes for navite API access:
...@@ -158,12 +158,12 @@ int main() ...@@ -158,12 +158,12 @@ int main()
{ {
// regular code // regular code
} }
catch (oracle_soci_error const &amp; e) catch (oracle_soci_error const & e)
{ {
cerr << "Oracle error: " << e.err_num_ cerr << "Oracle error: " << e.err_num_
<< " " << e.what() << endl; << " " << e.what() << endl;
} }
catch (exception const &amp;e) catch (exception const & e)
{ {
cerr << "Some other error: "<< e.what() << endl; cerr << "Some other error: "<< e.what() << endl;
} }
......
...@@ -47,7 +47,7 @@ session sql("postgresql", "dbname=mydatabase"); ...@@ -47,7 +47,7 @@ session sql("postgresql", "dbname=mydatabase");
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: In addition to standard PostgreSQL connection parameters, the following can be set:
...@@ -77,7 +77,7 @@ int count; ...@@ -77,7 +77,7 @@ int count;
sql << "select count(*) from invoices", into(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 ## SOCI Feature Support
...@@ -96,11 +96,11 @@ When calling `row::get<T>()`, the type you should pass as `T` depends upon the u ...@@ -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| |char, varchar, text, cstring, bpchar|dt_string|std::string|
|abstime, reltime, date, time, timestamp, timestamptz, timetz|dt_date|std::tm| |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 ### 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 ```cpp
int id = 7; int id = 7;
...@@ -119,19 +119,19 @@ The use of native syntax is not recommended, but can be nevertheless imposed by ...@@ -119,19 +119,19 @@ The use of native syntax is not recommended, but can be nevertheless imposed by
### Bulk Operations ### 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
[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 ### 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 ### 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 ### Nested Statements
...@@ -139,11 +139,11 @@ Nested statements are not supported by PostgreSQL backend. ...@@ -139,11 +139,11 @@ Nested statements are not supported by PostgreSQL backend.
### Stored Procedures ### 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 ## 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: 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 ...@@ -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: To support older PostgreSQL versions, the following configuration macros are recognized:
* `SOCI_POSTGRESQL_NOBINDBYNAME` - switches off the query rewriting. * `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_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. * `SOCI_POSTGRESQL_NOSINLGEROWMODE` - disable single mode retrieving query results row-by-row. It is necessary for PostgreSQL prior to version 9.
# SQLite3 Backend Reference # SQLite3 Backend Reference
SOCI backend for accessign SQLite 3 database. SOCI backend for accessing SQLite 3 database.
## Prerequisites ## Prerequisites
...@@ -47,7 +47,7 @@ session sql("sqlite3", "db=db.sqlite timeout=2 shared_cache=true"); ...@@ -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: The set of parameters used in the connection string for SQLite is:
* `dbname` or `db` * `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)) * `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)) * `shared_cache` - should be `true` ([link](http://www.sqlite.org/c3ref/enable_shared_cache.html))
...@@ -58,7 +58,7 @@ int count; ...@@ -58,7 +58,7 @@ int count;
sql << "select count(*) from invoices", into(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 ## SOCI Feature Support
...@@ -81,11 +81,11 @@ For the SQLite3 backend, this type mapping is complicated by the fact the SQLite ...@@ -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. [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 ### 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 ```cpp
int id = 7; int id = 7;
...@@ -102,19 +102,19 @@ sql << "insert into t(x, y) values(?, ?)", use(i), use(j); ...@@ -102,19 +102,19 @@ sql << "insert into t(x, y) values(?, ?)", use(i), use(j);
### Bulk Operations ### 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
[Transactions](../statements.html#transactions) are also fully supported by the SQLite3 backend.