NAME

       odbx_get_option - Query backend for implemented options

SYNOPSIS

       #include <opendbx/api.h>

       int odbx_get_option (odbx_t* handle, unsigned int option, void* value);

DESCRIPTION

       odbx_get_option() asks the backend module associated to handle by odbx_init() for implemented options and
       their  current  values. This function can be used at every stage as long as handle points to a valid con‐
       nection object. Its primary use is to find out supported features of the backend  module  and  to  enable
       them  with  odbx_set_option()  before  the  connection  to  the database server is established by calling
       odbx_bind().

       The first parameter handle is the connection object created and returned by odbx_init() which becomes in‐
       valid as soon as it was supplied to odbx_finish().

       There are several option 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 option values by
       odbx_set_option() to change the behavior of the backend module. The available options are:

       ODBX_OPT_API_VERSION
              The API version implemented by the backend. Currently, it returns only zero and  is  reserved  for
              the future

       ODBX_OPT_THREAD_SAFE
              If it is safe to use this backend and especially the native database client library in an applica‐
              tion  which uses threads where more than one thread opens database connections via the OpenDBX li‐
              brary

       ODBX_OPT_TLS
              The database client library may support transmitting all data securely by encrypting  the  network
              traffic via SSL or TLS

       ODBX_OPT_MULTI_STATEMENTS
              The  database  server  may be able to support multiple SQL statements in one query string sent via
              odbx_query()

       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

       ODBX_OPT_COMPRESS
              Support of compressed network traffic between database client and server. This can lead to  higher
              throughput if the network is the bottleneck

       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 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 value parameter by odbx_get_op‐
       tion() will be of boolean nature and therefore is ODBX_ENABLE for a supported option or ODBX_DISABLE  for
       an option which isn't supported.

RETURN VALUE

       odbx_get_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.

ERRORS

       -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  con‐
              tent of value remains unchanged if this error occurs

SEE ALSO

       odbx_bind(), odbx_error(), odbx_error_type(), odbx_init(), odbx_set_option()

                                                  3 April 2024                                odbx_get_option(3)