NAME

       odbx_set_option - Change behaviour of the database backend

SYNOPSIS

       #include <opendbx/api.h>

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

DESCRIPTION

       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.

RETURN VALUE

       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.

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

SEE ALSO

       odbx_bind(), odbx_error(), odbx_get_option()

                                           3 April 2024                        odbx_set_option(3)