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()

                                         17 October 2021                             odbx_init(3)