Difference between revisions of "OpenDBX/C API/odbx init"

From Linuxnetworks
< OpenDBX‎ | C API
Jump to: navigation, search
(description)
(rewrite)
Line 9: Line 9:
 
     const char* '''port''' )
 
     const char* '''port''' )
  
−
= Description: =
+
= Description =
  
−
'''odbx_init()''' allocates and initializes an opaque object required for all further operations within the OpenDBX library and 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 [[OpenDBX_bind|odbx_bind()]]. The pointer of the newly created object is stored in the parameter '''handle''' provided by the calling function. You must not free the returned object yourself but have to use [[OpenDBX_finish|odbx_finish()]] instead to avoid memory leaks.
+
'''odbx_init()''' allocates and initializes an opaque object required for all further operations within the OpenDBX library 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 [[OpenDBX_bind|odbx_bind()]].
  
−
= Parameters: =
+
The pointer of the newly allocated connection object is stored in '''handle''' if '''odbx_init()''' completes successfully. Otherwise, the value of the odbx_t* variable will be undefined and must not be used as input for other functions of the library. The returned connection object should be freed by [[OpenDBX_finish|odbx_finish()]] to avoid memory leaks if it will be no longer used by the application.
  
−
* handle: Pointer where the newly allocated connection object should be stored
+
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 all 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:
−
* backend: Name of the backend you want to use (mysql, pgsql, sqlite and sqlite3 - depends on the installed libraries)
+
−
* host: Host name or IP address of the database server or path to database file
+
−
* port: Port number the database server is listening to
+
  
−
= Return values: =
+
* 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)
  
−
* ODBX_ERR_SUCCESS on success
+
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. PostgreSQL supports an absolute path to its Unix domain socket located in the file system too, whereas SQLite needs the path to its database file.
−
* Less than zero if an error occured
+
  
−
= Errors: =
+
= 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 used by '''odbx_error()''' and '''odbx_error_type()''' to get further details.
 +
 
 +
= Errors =
  
 
* -ODBX_ERR_BACKEND: Any error returned by the backend
 
* -ODBX_ERR_BACKEND: Any error returned by the backend
Line 34: Line 41:
 
* -ODBX_ERR_NOOP: A function does not exist in the backend
 
* -ODBX_ERR_NOOP: A function does not exist in the backend
  
−
= See also: =
+
= See also =
  
 
* [[OpenDBX_capabilities]]
 
* [[OpenDBX_capabilities]]

Revision as of 18:54, 17 February 2007


#include <odbx.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 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 odbx_t* variable will be undefined and must not be used as input for other functions of the library. The returned connection object should 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 all 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. PostgreSQL supports an absolute path to its Unix domain socket located in the file system too, whereas SQLite needs the path to its database file.

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 used by odbx_error() and odbx_error_type() to get further details.

Errors

  • -ODBX_ERR_BACKEND: Any error returned by the backend
  • -ODBX_ERR_PARAM: "handle" is NULL
  • -ODBX_ERR_NOMEM: Allocating new memory failed
  • -ODBX_ERR_TOOLONG: The length of a string exceeded the buffer size
  • -ODBX_ERR_NOTEXIST: Backend library was not found
  • -ODBX_ERR_NOOP: A function does not exist in the backend

See also


Back to Overview

Retrieved from "https://linuxnetworks.de/doc/index.php?title=OpenDBX/C_API/odbx_init&oldid=2236"