1odbx_init(3) OpenDBX odbx_init(3)
2
6 odbx_init - Allocate per connection data structures
7
9 #include <opendbx/api.h>
10 int odbx_init (odbx_t** handle, const char* backend, const char* host,
13 const char* port);
14
16 odbx_init() allocates and initializes an opaque object required for all
17 further operations within the OpenDBX library which is used to identify
18 the connection and to maintain per connection information. Depending on
19 the backend it can open a connection to the database server but often
20 this is done not until performing authentication through odbx_bind().
21 The pointer of the newly allocated connection object is stored in han‐
23 dle if odbx_init() completes successfully. Otherwise, the value of the
24 handle variable will be undefined and must not be used as input for
25 other functions of the library. The returned connection object must be
26 freed by odbx_finish() to avoid memory leaks if it will be no longer
27 used by the application.
28 The OpenDBX library provides access to several different database im‐
30 plementations through a single interface and therefore has to know
31 which one of the available backend modules it should use for the opera‐
32 tions. The backend parameter will be used to perform the lookup of the
33 requested module. It has to be a zero-terminated ASCII string with all
34 characters in in lower case. Currently, these backend modules are
35 available:
36 • firebird (Firebird/Interbase)
38 • mssql (MS SQL Server via FreeTDS)
40 • mysql (MySQL)
42 • oracle (Oracle 8i/9i/10g)
44 • pgsql (PostgreSQL)
46 • sqlite (SQLite v2)
48 • sqlite3 (SQLite v3)
50 • sybase (Sybase ASE)
52 Connecting to a database server requires at least an identifier to know
54 where the database is located. There are several kinds of identifiers
55 like host names, IP addresses, named pipes, etc. which could be used.
56 One of them can be provided via the host parameter and it is up to the
57 native database library what it will accept. Most native libraries ac‐
58 cept at least host names and IP addresses and also use the provided
59 port in this case. The available methods for host are:
60 host name string
62 supported by Firebird/Interbase, MySQL, Oracle and PostgreSQL
63 backends
64 IP address string
66 supported by Firebird/Interbase, MySQL, Oracle and PostgreSQL
67 backends
68 absolute path to Unix domain socket
70 currently supported by the PostgreSQL backend only
71 (relative) directory path with trailing slash/backslash
73 required by SQLite and SQLite3 backends
74 section name in configuration file
76 required by MS SQL Server and Sybase ASE backends
77 Depending on the native database library, it's also possible to use
79 database specific default values for the host and port parameters by
80 supplying empty, zero-terminated strings or a NULL value.
81
83 odbx_init() returns ODBX_ERR_SUCCESS, or an error code whose value is
84 less than zero if one of the operations couldn't be completed success‐
85 fully. Possible error codes are listed in the error section and they
86 can be feed to odbx_error() and odbx_error_type() to get further de‐
87 tails.
88
90 -ODBX_ERR_BACKEND
91 The backend module returned an error because it couldn't setup
92 the necessary structures
93 -ODBX_ERR_PARAM
95 handle is NULL and the allocated connection object can't be
96 stored
97 -ODBX_ERR_NOMEM
99 Allocating new memory for the connection object failed
100 -ODBX_ERR_SIZE
102 The length of a string exceeded the available buffer size
103 -ODBX_ERR_NOTEXIST
105 A backend module with this name wasn't found. Either the module
106 isn't installed, the given name was wrong or not in the correct
107 character case
108 -ODBX_ERR_NOOP
110 The backend module doesn't provide the required function
111
113 odbx_bind(), odbx_capabilities(), odbx_error(), odbx_finish(),
114 odbx_get_option(), odbx_set_option()
115 19 January 2023 odbx_init(3)