odbx_get_option(3)

NAME

odbx_get_option - Query backend for implemented options

SYNOPSIS

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

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

DESCRIPTION

FCodbx_get_optionF[0]() asks the backend module associated to FChandleF[0] by FCodbx_initF[0]() for implemented options and their current values. This function can be used at every stage as long as FChandleF[0] points to a valid connection object. Its primary use is to find out supported features of the backend module and to enable them with FCodbx_set_optionF[0]() before the connection to the database server is established by calling FCodbx_bindF[0]().

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. A few of them are for informational purpose only while most of the options can also be set to different FCoptionF[0] values by FCodbx_set_optionF[0]() to change the behavior of the backend module. The available options are:

FCODBX_OPT_API_VERSIONF[0]: The API version implemented by the backend. Currently, it returns only zero and is reserved for the future

FCODBX_OPT_THREAD_SAFEF[0]: If it is safe to use this backend and especially the native database client library in an application which uses threads where more than one thread opens database connections via the OpenDBX library

FCODBX_OPT_TLSF[0]: The database client library may support transmitting all data securely by encrypting the network traffic via SSL or TLS

FCODBX_OPT_MULTI_STATEMENTSF[0]: The database server may be able to support multiple SQL statements in one query string sent via FCodbx_queryF[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

FCODBX_OPT_COMPRESSF[0]: Support of compressed network traffic between database client and server. This can lead to higher throughput if the network is the bottleneck

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 be a pointer to an integer variable where the backend module will store the result for the supplied option. If it's not stated otherwise, the value assigned to the FCvalueF[0] parameter by FCodbx_get_optionF[0]() will be of boolean nature and therefore is FCODBX_ENABLEF[0] for a supported option or FCODBX_DISABLEF[0] for an option which isn't supported.

RETURN VALUE

FCodbx_get_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