1odbx_init(3)                        OpenDBX                       odbx_init(3)
2
3
4

NAME

6       odbx_init - Allocate per connection data structures
7

SYNOPSIS

9       #include <opendbx/api.h>
10
11
12       int odbx_init (odbx_t** handle, const char* backend, const char* host,
13                     const char* port);
14

DESCRIPTION

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
22       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
29       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
37       • firebird (Firebird/Interbase)
38
39       • mssql (MS SQL Server via FreeTDS)
40
41       • mysql (MySQL)
42
43       • oracle (Oracle 8i/9i/10g)
44
45       • pgsql (PostgreSQL)
46
47       • sqlite (SQLite v2)
48
49       • sqlite3 (SQLite v3)
50
51       • sybase (Sybase ASE)
52
53       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
61       host name string
62              supported  by  Firebird/Interbase,  MySQL, Oracle and PostgreSQL
63              backends
64
65       IP address string
66              supported by Firebird/Interbase, MySQL,  Oracle  and  PostgreSQL
67              backends
68
69       absolute path to Unix domain socket
70              currently supported by the PostgreSQL backend only
71
72       (relative) directory path with trailing slash/backslash
73              required by SQLite and SQLite3 backends
74
75       section name in configuration file
76              required by MS SQL Server and Sybase ASE backends
77
78       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

RETURN VALUE

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

ERRORS

90       -ODBX_ERR_BACKEND
91              The  backend  module returned an error because it couldn't setup
92              the necessary structures
93
94       -ODBX_ERR_PARAM
95              handle is NULL and the  allocated  connection  object  can't  be
96              stored
97
98       -ODBX_ERR_NOMEM
99              Allocating new memory for the connection object failed
100
101       -ODBX_ERR_SIZE
102              The length of a string exceeded the available buffer size
103
104       -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
109       -ODBX_ERR_NOOP
110              The backend module doesn't provide the required function
111

SEE ALSO

113       odbx_bind(),    odbx_capabilities(),    odbx_error(),    odbx_finish(),
114       odbx_get_option(), odbx_set_option()
115
116
117
118                                19 January 2023                   odbx_init(3)
Impressum