1odbx_set_option(3) OpenDBX odbx_set_option(3)
2
6 odbx_set_option - Change behaviour of the database backend
7
9 #include <opendbx/api.h>
10 int odbx_set_option (odbx_t* handle, unsigned int option, void* value);
13
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 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 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 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 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 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 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 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
69 ⟨http://dev.mysql.com/doc/refman/5.0/en/server-sql-mode.html⟩
70 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
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
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 -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 -ODBX_ERR_OPTRO
94 The option isn't intended for being changed and could only be
95 read via odbx_get_option()
96 -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
103 odbx_bind(), odbx_error(), odbx_get_option()
104 28 July 2020 odbx_set_option(3)