1odbx_set_option(3)                  OpenDBX                 odbx_set_option(3)
2
3
4

NAME

6       odbx_set_option - Change behaviour of the database backend
7

SYNOPSIS

9       #include <opendbx/api.h>
10
11
12       int odbx_set_option (odbx_t* handle, unsigned int option, void* value);
13

DESCRIPTION

15       Changes  the value of the specified option in the backend module or the
16       native database library associated to  handle  by  odbx_init().  Before
17       trying  to  set  an  option, it should be tested with odbx_get_option()
18       first to ensure that it is supported by the backend. Almost all options
19       need  to  be  set  before  connecting  to  the  database  server  using
20       odbx_bind() to take any effect.
21
22       The first parameter handle is the connection  object  created  and  re‐
23       turned  by odbx_init() which becomes invalid as soon as it was supplied
24       to odbx_finish().
25
26       There are several option values  defined  as  named  constants  in  the
27       odbx.h  header  file. The available options whose values can be changed
28       are:
29
30       ODBX_OPT_TLS
31              Use encryption to transmit all data securely  over  the  network
32              via  SSL  or  TLS. This option can be set to ODBX_TLS_NEVER (the
33              default value) to prevent encrpytion, ODBX_TLS_ALWAYS to enforce
34              encryption  and  to  fail if it can't be used between the client
35              library and the server or ODBX_TLS_TRY to use encryption if pos‐
36              sible  with  the option to fall back to a connection which isn't
37              encrypted.
38
39       ODBX_OPT_MULTI_STATEMENTS
40              Enables the database server to accept multiple statements in one
41              query  string sent via odbx_query() if the value of value is set
42              to ODBX_ENABLE. Although, it might be possible to disable it  by
43              setting it to ODBX_DISABLE.
44
45       ODBX_OPT_PAGED_RESULTS
46              All  database  servers and client libraries are able to transfer
47              the records row by row. Some of them can also transfer  multiple
48              rows  or even all at once to minimize server load, network traf‐
49              fic and latency. The downside of this  is  an  increased  memory
50              consumption.  If  paged  results  are  supported by the backend,
51              passing positive values  will  fetch  the  specified  number  of
52              records  at  once  from  the  database server. The value of zero
53              ("0") is special in this case because it asks the backend module
54              to retrieve all records at once
55
56       ODBX_OPT_COMPRESS
57              Enable  compressed  network  traffic between database client and
58              server. This can maximize the throughput if the network  is  the
59              bottleneck.  Pass an integer variable with ODBX_ENABLE to enable
60              compression or with ODBX_DISABLE to disable it for this  connec‐
61              tion
62
63       ODBX_OPT_MODE
64              Some database servers support different modes of operation, e.g.
65              modes for compliance to other SQL implementations or  completely
66              different query languages. This option is available since OpenD‐
67              BX 1.1.4. value must point to a zero terminated string and for a
68              detailed description of the MySQL modes look at their website
69http://dev.mysql.com/doc/refman/5.0/en/server-sql-mode.html
70
71       If not stated otherwise, the type of the variable passed to  the  third
72       parameter value must be an integer pointer. Its values should be in the
73       range specified by the option being changed.
74

RETURN VALUE

76       odbx_set_option() returns ODBX_ERR_SUCCESS, or an error code whose val‐
77       ue  is  less  than  zero if one of the operations couldn't be completed
78       successfully. Possible error codes are listed in the error section  and
79       they  can  be feed to odbx_error() and odbx_error_type() to get further
80       details.
81

ERRORS

83       -ODBX_ERR_PARAM
84              One of the supplied parameters is invalid or is  NULL  and  this
85              isn't  allowed in the used backend module or in the native data‐
86              base client library
87
88       -ODBX_ERR_OPTION
89              The value passed to the option parameter isn't one of the values
90              listed in this manual. The content of value remains unchanged if
91              this error occurs
92
93       -ODBX_ERR_OPTRO
94              The option isn't intended for being changed and  could  only  be
95              read via odbx_get_option()
96
97       -ODBX_ERR_OPTWR
98              Setting  the option failed for various reasons. It's most likely
99              that the value passed via value didn't match the range of values
100              expected by the backend or the native database library
101

SEE ALSO

103       odbx_bind(), odbx_error(), odbx_get_option()
104
105
106
107                                 28 July 2020               odbx_set_option(3)
Impressum