NAME

       odbx_init - Allocate per connection data structures

SYNOPSIS

       #include <opendbx/api.h>

       int odbx_init (odbx_t** handle, const char* backend, const char* host, const char* port);

DESCRIPTION

       odbx_init()  allocates  and  initializes  an opaque object required for all further operations within the
       OpenDBX library which is used to identify the connection and  to  maintain  per  connection  information.
       Depending on the backend it can open a connection to the database server but often this is done not until
       performing authentication through odbx_bind().

       The pointer of the newly allocated connection  object  is  stored  in  handle  if  odbx_init()  completes
       successfully. Otherwise, the value of the handle variable will be undefined and must not be used as input
       for other functions of the library. The returned connection object must  be  freed  by  odbx_finish()  to
       avoid memory leaks if it will be no longer used by the application.

       The  OpenDBX  library  provides  access  to  several  different database implementations through a single
       interface and therefore has to know which one of the available backend modules  it  should  use  for  the
       operations.  The  backend parameter will be used to perform the lookup of the requested module. It has to
       be a zero-terminated ASCII string with all characters in in lower case. Currently, these backend  modules
       are available:

       • firebird (Firebird/Interbase)

       • mssql (MS SQL Server via FreeTDS)

       • mysql (MySQL)

       • oracle (Oracle 8i/9i/10g)

       • pgsql (PostgreSQL)

       • sqlite (SQLite v2)

       • sqlite3 (SQLite v3)

       • sybase (Sybase ASE)

       Connecting  to  a  database server requires at least an identifier to know where the database is located.
       There are several kinds of identifiers like host names, IP addresses, named pipes, etc.  which  could  be
       used. One of them can be provided via the host parameter and it is up to the native database library what
       it will accept. Most native libraries accept at least host names  and  IP  addresses  and  also  use  the
       provided port in this case. The available methods for host are:

       host name string
              supported by Firebird/Interbase, MySQL, Oracle and PostgreSQL backends

       IP address string
              supported by Firebird/Interbase, MySQL, Oracle and PostgreSQL backends

       absolute path to Unix domain socket
              currently supported by the PostgreSQL backend only

       (relative) directory path with trailing slash/backslash
              required by SQLite and SQLite3 backends

       section name in configuration file
              required by MS SQL Server and Sybase ASE backends

       Depending  on the native database library, it's also possible to use database specific default values for
       the host and port parameters by supplying empty, zero-terminated strings or a NULL value.

RETURN VALUE

       odbx_init() 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_BACKEND
              The backend module returned an error because it couldn't setup the necessary structures

       -ODBX_ERR_PARAM
              handle is NULL and the allocated connection object can't be stored

       -ODBX_ERR_NOMEM
              Allocating new memory for the connection object failed

       -ODBX_ERR_SIZE
              The length of a string exceeded the available buffer size

       -ODBX_ERR_NOTEXIST
              A backend module with this name wasn't found. Either the module isn't installed,  the  given  name
              was wrong or not in the correct character case

       -ODBX_ERR_NOOP
              The backend module doesn't provide the required function

SEE ALSO

       odbx_bind(), odbx_capabilities(), odbx_error(), odbx_finish(), odbx_get_option(), odbx_set_option()

                                                 21 October 2016                                    odbx_init(3)