bionic (3) odbx_set_option.3.gz

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

                                                 21 October 2016                              odbx_set_option(3)