odbx_set_option - Change behaviour of the database backend
#include <opendbx/api.h>
int odbx_set_option
(odbx_t* handle, unsigned int option, void* value);
Changes the value of the specified option in the backend module or
the native database library associated to handle by odbx_init().
Before trying to set an option, it should be tested with
odbx_get_option() first to ensure that it is supported by the
backend. Almost all options need to be set before connecting to the database
server using odbx_bind() to take any effect.
The first parameter handle is the connection object created and
returned by odbx_init() which becomes invalid as soon as it was
supplied to odbx_finish().
There are several option values defined as named constants in the
odbx.h header file. The available options whose values can be changed
are:
- ODBX_OPT_TLS
- Use encryption to transmit all data securely over the network via SSL or
TLS. This option can be set to ODBX_TLS_NEVER (the default value) to
prevent encrpytion, ODBX_TLS_ALWAYS to enforce encryption and to fail if
it can't be used between the client library and the server or ODBX_TLS_TRY
to use encryption if possible with the option to fall back to a connection
which isn't encrypted.
- ODBX_OPT_MULTI_STATEMENTS
- Enables the database server to accept multiple statements in one query
string sent via odbx_query() if the value of value is set to
ODBX_ENABLE. Although, it might be possible to disable it by setting it to
ODBX_DISABLE.
- ODBX_OPT_PAGED_RESULTS
- All database servers and client libraries are able to transfer the records
row by row. Some of them can also transfer multiple rows or even all at
once to minimize server load, network traffic and latency. The downside of
this is an increased memory consumption. If paged results are supported by
the backend, passing positive values will fetch the specified number of
records at once from the database server. The value of zero
("0") is special in this case because it asks the backend module
to retrieve all records at once
- ODBX_OPT_COMPRESS
- Enable compressed network traffic between database client and server. This
can maximize the throughput if the network is the bottleneck. Pass an
integer variable with ODBX_ENABLE to enable compression or with
ODBX_DISABLE to disable it for this connection
- ODBX_OPT_MODE
- Some database servers support different modes of operation, e.g. modes for
compliance to other SQL implementations or completely different query
languages. This option is available since OpenDBX 1.1.4. value must point
to a zero terminated string and for a detailed description of the MySQL
modes look at their website
⟨http://dev.mysql.com/doc/refman/5.0/en/server-sql-mode.html⟩
If not stated otherwise, the type of the variable passed to the
third parameter value must be an integer pointer. Its values should be in
the range specified by the option being changed.
odbx_set_option() returns ODBX_ERR_SUCCESS, or an error
code whose value is less than zero if one of the operations couldn't be
completed successfully. Possible error codes are listed in the error section
and they can be feed to odbx_error() and odbx_error_type() to
get further details.
- -ODBX_ERR_PARAM
- One of the supplied parameters is invalid or is NULL and this isn't
allowed in the used backend module or in the native database client
library
- -ODBX_ERR_OPTION
- The value passed to the option parameter isn't one of the values listed in
this manual. The content of value remains unchanged if this error
occurs
- -ODBX_ERR_OPTRO
- The option isn't intended for being changed and could only be read via
odbx_get_option()
- -ODBX_ERR_OPTWR
- Setting the option failed for various reasons. It's most likely that the
value passed via value didn't match the range of values expected by the
backend or the native database library
odbx_bind(), odbx_error(),
odbx_get_option()