odbx_set_option(3)

NAME

odbx_set_option - Change behaviour of the database backend

SYNOPSIS

FC#include <opendbx/api.h>F[0]

FCint odbx_set_optionF[0] FC(odbx_t* handle, unsigned int option, void* value);F[0]

DESCRIPTION

Changes the value of the specified option in the backend module or the native database library associated to handle by FCodbx_initF[0](). Before trying to set an option, it should be tested with FCodbx_get_optionF[0]() first to ensure that it is supported by the backend. Almost all options need to be set before connecting to the database server using FCodbx_bindF[0]() to take any effect.

The first parameter FChandleF[0] is the connection object created and returned by FCodbx_initF[0]() which becomes invalid as soon as it was supplied to FCodbx_finishF[0]().

There are several FCoptionF[0] values defined as named constants in the odbx.h header file. The available options whose values can be changed are:

FCODBX_OPT_TLSF[0]: Use encryption to transmit all data securely over the network via SSL or TLS. This option can be set to FCODBX_TLS_NEVERF[0] (the default value) to prevent encrpytion, FCODBX_TLS_ALWAYSF[0] to enforce encryption and to fail if it can't be used between the client library and the server or FCODBX_TLS_TRYF[0] to use encryption if possible with the option to fall back to a connection which isn't encrypted.

FCODBX_OPT_MULTI_STATEMENTSF[0]: Enables the database server to accept multiple statements in one query string sent via FCodbx_queryF[0]() if the value of value is set to FCODBX_ENABLEF[0]. Although, it might be possible to disable it by setting it to FCODBX_DISABLEF[0].

FCODBX_OPT_PAGED_RESULTSF[0]: 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

FCODBX_OPT_COMPRESSF[0]: 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 FCODBX_ENABLEF[0] to enable compression or with FCODBX_DISABLEF[0] to disable it for this connection

FCODBX_OPT_MODEF[0]: 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. FCvalueF[0] 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 FCvalueF[0] must be an integer pointer. Its values should be in the range specified by the option being changed.

RETURN VALUE

FCodbx_set_optionF[0]() returns FCODBX_ERR_SUCCESSF[0], 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 FCodbx_errorF[0]() and FCodbx_error_typeF[0]() to get further details.

ERRORS

-FCODBX_ERR_PARAMF[0]: 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

-FCODBX_ERR_OPTIONF[0]: The value passed to the FCoptionF[0] parameter isn't one of the values listed in this manual. The content of FCvalueF[0] remains unchanged if this error occurs

-FCODBX_ERR_OPTROF[0]: The option isn't intended for being changed and could only be read via FCodbx_get_optionF[0]()

-FCODBX_ERR_OPTWRF[0]: Setting the option failed for various reasons. It's most likely that the value passed via FCvalueF[0] didn't match the range of values expected by the backend or the native database library