Revision as of 19:44, 18 February 2007

#include <odbx.h>

int odbx_bind(
    odbx_t* handle,
    const char* database,
    const char* who,
    const char* cred,
    int method ) 

int odbx_bind_simple(
    odbx_t* handle,
    const char* database,
    const char* who,
    const char* cred )

Description

odbx_bind() associates a connection created by odbx_init() to a specific database instance after the server verified and accepted the authentication details. All further operations will (normally) only affect the tables and records within this database instance. They may be limited to certain subset depending on the privileges granted to the given user account. If binding to the database instance succeeded, odbx_bind() also enables compatibility to the ANSI SQL standard if this is possible for the database server implementation.

odbx_bind_simple() performs the same tasks as odbx_bind() but can't do anything else than simple user name / password authentication. It shouldn't be used in applications linking to the OpenDBX library version 1.1.1 or later and it will be removed from the library at a later stage.

Both functions accept almost the same parameters. The handle parameter always has to be a pointer to a valid connection object allocated by odbx_init(). The availability of certain options or the behavior of the connection associated to the given connection reference can be changed by calling odbx_get_option() respectively odbx_set_option() but this must be done before calling odbx_bind(). Examples of such options are the thread-safetiness of the native database client library or to enable support for sending multiple statements at once.

database is necessary to let the database server know which database instance should be used for executing all further requests. In combination with the authentication parameters who and cred, it usually allows or denies operations on tables and records within this database instance. Contrary to that, SQLite doesn't use who and cred but instead relies on the file system permissions to grant access to the whole database file. If they are used, the supplied values for all three parameters must be zero-terminated strings and should be in exactly the same character case as stored by the database manager. Otherwise, they can also be NULL. Some database libraries also support the use of default values provided by a configuration file if a parameter is NULL.

method specifies the mechanism for authenticating a user account before it can perform operations on tables and records. Currently, all database backend modules only support the ODBX_BIND_SIMPLE method which provides basic user name / password authentication. In this case, the parameter who must be the name of an user account while cred has to be the password that belongs to the given account.

An already associated connection object can be detached from the database and rebound to the same database server. It is possible to bind it to another database instance, with another user account and other options by detaching the connection object with odbx_unbind() first before invoking odbx_bind() with the same or with different parameters again.

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 

The backend module returned an error because it couldn't connect to the database or the authentication using the supplied parameters failed

-ODBX_ERR_PARAM 

One of the supplied parameters is invalid or is NULL and this isn't allowed in the used backend module or in the native database client library

-ODBX_ERR_NOMEM 

Allocating additionally required memory failed

-ODBX_ERR_SIZE 

The length of a string exceeded the available buffer size

-ODBX_ERR_NOTSUP 

The supplied authentication method is not supported by the backend module

See also

• OpenDBX_error
• OpenDBX_error_type
• OpenDBX_escape
• OpenDBX_query
• OpenDBX_unbind

Back to Overview