Initialization support
[Estron backend plugins]

---

Detailed Description

This module allows DWI to access a variety of data sources using a uniform programming interface: essentially, this is a database API wrapper. This wrapper is very DWI-specific, and is not (really) meant for use by other applications (although it has been). The API borrows conceptual elements from the Postgres libpg API and the ODBC API, and so should be "inutitively obvious" to experienced database programmers. This wrapper allows a variety of different database-access drivers to be operated behind it.

The idea of having a 'wrapper' for database access is not new, and so its worth discussing why 'yet another' wrapper has been created. There are several reasons:

1) This wrapper originially wrapped ODBC. I didn't know ODBC very well when I did this, and I was worried that ODBC sucked. The wrapper allows suckage to be hidden or fixed. 2) The wrapper would allows native Postgress interfaces to be quickly developed, in case the suckage of 1 was too great. 3) The wrapper allows drivers to be added for non-traditional data sources. This would allow DWI to treat these non-traditional data sources in a a database-like way: an important feature, since, to DWI, everything looks like a database. Note: to do this properly, we would need to move the "builder.h" and "builder.c" files from the other directory to here: the builder would be used only by SQL data sources; other data sources would have to handle key-value pairs differently.

This wrapper currently supports only two "providers": ODBC and libdbi (http://libdbi.sourceforge.net).

Typedefs
typedef struct DuiDBConnection_s	DuiDBConnection
typedef struct DuiDBRecordSet_s	DuiDBRecordSet
Functions
void	dui_db_init (void)
DuiDBConnection *	dui_connection_new (const char *provider, const char *dbname, const char *username, const char *authentication_token)
void	dui_connection_free (DuiDBConnection *conn)
DuiDBRecordSet *	dui_connection_exec (DuiDBConnection *, const char *buff)
DuiDBRecordSet *	dui_connection_tables (DuiDBConnection *)
DuiDBRecordSet *	dui_connection_table_columns (DuiDBConnection *, const char *table_name)
void	dui_recordset_free (DuiDBRecordSet *)
int	dui_recordset_rewind (DuiDBRecordSet *rs)
int	dui_recordset_fetch_row (DuiDBRecordSet *rs)
const char *	dui_recordset_get_value (DuiDBRecordSet *, const char *fieldname)
int	dui_connection_catch_error (DuiDBConnection *conn, char **ret_str)
int	dui_recordset_catch_error (DuiDBRecordSet *, char **ret_str)
struct timespec	dui_connection_get_now (DuiDBConnection *conn)
void	dui_connection_lock (DuiDBConnection *conn, const char *tablename)
void	dui_connection_unlock (DuiDBConnection *conn, const char *tablename)

---

Function Documentation

int dui_connection_catch_error	(	DuiDBConnection *	conn,
		char **	ret_str
	)

Return an error code and error string. The design philosphy of the DUI database connection is to be as self-healing as possible, and to report as few errors as possible, so that the system does 'the right thing' as often as possible, so that the API remains easy to use. However, its impossible to ignore all errors; this routine provides a way of getting them.

Returns zero if no error, else returns non-zero. An error string is returned in ret_str if its non-null. The act of calling this routine will also clear the error report (but not the error condition).

Definition at line 173 of file dui-initdb.c.

{
    return 0;
}

DuiDBRecordSet* dui_connection_exec	(	DuiDBConnection *	,
		const char *	buff
	)

Issue a query on this connection. FYI -- the query is actually performed asynchronously; the record set may not yet contain valid data when this routine returns. Valid data is not available until the (possibly blocking) routine dui_recordset_fetch_row() is called. Note that some queries may result in errors: e.g. if a query uses a table that does not exist. If the resulting recordset contains no rows, you may want to check dui_recordset_catch_error() for errors.

Definition at line 228 of file dui-initdb.c.

{
    DuiDBRecordSet *rs = NULL;
    DuiDBPlugin *plg;
    
    if (!conn) return NULL;

    plg = conn->provider;
    if (!plg) return NULL;
    
    if (plg->connection_exec)
    {
        rs = (plg->connection_exec) (conn, buff);
    }
    if (!rs) return NULL;
    rs->provider = plg;

    return rs;
}

struct timespec dui_connection_get_now

(

DuiDBConnection *

conn

)

[read]

Return the the current time, in UTC, at the database server. This value is typically used to provide timestamps for data records. This function is provided as a callable subroutine to ensure portability and common operation for different databases. The SQL statement 'SELECT now() as x' is usally enough for most, but possibly not all databases.

Bug:

timespec needs to be removed.

Definition at line 181 of file dui-initdb.c.

{
    DuiDBPlugin *plg;
    struct timespec ts = {0,-1};
    if (!conn) return ts;

    plg = conn->provider;
    if (!plg) return ts;
    if (!plg->get_now) return ts;

    ts = (plg->get_now) (conn);
    return ts;
}

void dui_connection_lock	(	DuiDBConnection *	conn,
		const char *	tablename
	)

Lock the indicated tablename in the database server, thus serializing update access. This function is provided as a callable subroutine to ensure portability and common operation for different databases. Not all databases support the same locking mechanisms or locking primitives; this subroutine provides the common api to sereialize database updates.

The subroutine takes a tablename to be locked as the argument. The lock is not expected to fail; if the lock can't be gotten immediately, the subroutine will stall until the lock is available. The unlock is expected to globally commit the changes, making them visible to other clients.

Definition at line 198 of file dui-initdb.c.

{
    DuiDBPlugin *plg;

    if (!conn) return;
    plg = conn->provider;
    if (!plg) return;
    if (!plg->lock) return;

    (plg->lock) (conn, tablename);
}

DuiDBConnection* dui_connection_new	(	const char *	provider,
		const char *	dbname,
		const char *	username,
		const char *	authentication_token
	)

The dui_connection_new() routine establishes a connection to the indicated database, using the indicated login. The "provider" field is the name of the driver to use. Currently, only "odbc" and "libdbi" are supported.

The ODBC driver expects "dbname" to specify an existing database, and "username" to specify a valid username for logging into the database. The "authentication token" must be a valid password or other ticket that authorizes access.

Definition at line 106 of file dui-initdb.c.

{
    DuiDBPlugin *plg = NULL;
    DuiDBConnection *dbc = NULL;

    if (!provider) return NULL;

   plg = find_provider (db_provider_list, provider);
    if (!plg) 
    {
        if (!strcmp (provider, "odbc"))
        {
            load_driver ("libdwi-db-odbc.so", "dui_odbc_init", "ODBC");
        }
        else
        if (!strcmp (provider, "libpg"))
        {
            load_driver ("libdwi-db-libpg.so", "dui_libpg_init", "Postgres");
        }
        else
        if (!strcmp (provider, "libdbi"))
        {
            load_driver ("libdwi-db-libdbi.so", "dui_libdbi_init", "DBI");
        }

    plg = find_provider (db_provider_list, provider);
    }
    if (!plg) 
    {
        PERR ("Can't find database provider \"%s\" for database \"%s\"", 
               provider, dbname);
        return NULL;
    }

    if (!plg->connection_new) return NULL;

    dbc = (plg->connection_new) (dbname, username, authentication_token);
    
    if (!dbc) return NULL;
    dbc->provider = plg;
    return dbc;
}

DuiDBRecordSet* dui_connection_table_columns	(	DuiDBConnection *	,
		const char *	table_name
	)

Get a list of columns in the named table

Definition at line 274 of file dui-initdb.c.

{
    DuiDBRecordSet *rs = NULL;
    DuiDBPlugin *plg;
    
    if (!conn) return NULL;

    plg = conn->provider;
    if (!plg) return NULL;
    
    if (plg->connection_table_columns)
    {
        rs = (plg->connection_table_columns) (conn, tablename);
    }
    if (!rs) return NULL;
    rs->provider = plg;

    return rs;
}

DuiDBRecordSet* dui_connection_tables

(

DuiDBConnection *

)

Return a list of tables on this connection.

Definition at line 251 of file dui-initdb.c.

{
    DuiDBRecordSet *rs = NULL;
    DuiDBPlugin *plg;
    
    if (!conn) return NULL;

    plg = conn->provider;
    if (!plg) return NULL;
    
    if (plg->connection_tables)
    {
        rs = (plg->connection_tables) (conn);
    }
    if (!rs) return NULL;
    rs->provider = plg;

    return rs;
}

void dui_connection_unlock	(	DuiDBConnection *	conn,
		const char *	tablename
	)

Bug:

under what cases would we need to support rollback?

Definition at line 213 of file dui-initdb.c.

{
    DuiDBPlugin *plg;
    if (!conn) return;

    plg = conn->provider;
    if (!plg) return;
    if (!plg->unlock) return;

    (plg->unlock) (conn, tablename);
}

void dui_db_init

(

void

)

Must call this before using this subsystem

Definition at line 84 of file dui-initdb.c.

{
}

int dui_recordset_fetch_row

(

DuiDBRecordSet *

rs

)

Prep a row. Basically, this gets the 'next' row out of the database. Subsequent field fetches are for this row. Returns zero if there are no more rows, else returns a non-zero value if there are more rows.

Definition at line 334 of file dui-initdb.c.

{
    DuiDBPlugin *plg;
    
    if (!rs) return 0;

    plg = rs->provider;
    if (!plg) return 0;
    
    if (plg->recordset_fetch_row)
    {
        return (plg->recordset_fetch_row) (rs);
    }
    return 0;
}

void dui_recordset_free

(

DuiDBRecordSet *

)

Release the record set when one is done with it

Definition at line 297 of file dui-initdb.c.

{
    DuiDBPlugin *plg;
    
    if (!rs) return;

    plg = rs->provider;
    if (!plg) return;
    
    if (plg->recordset_free)
    {
        (plg->recordset_free) (rs);
    }
}

const char* dui_recordset_get_value	(	DuiDBRecordSet *	,
		const char *	fieldname
	)

Get the field value by name. This is a little different/easier than the usual trick of getting it by column number.

Definition at line 353 of file dui-initdb.c.

{
    DuiDBPlugin *plg;
    
    if (!rs) return NULL;

    plg = rs->provider;
    if (!plg) return NULL;
    
    if (plg->recordset_get_value)
    {
        return (plg->recordset_get_value) (rs, fieldname);
    }
    return NULL;
}

int dui_recordset_rewind

(

DuiDBRecordSet *

rs

)

Set the row pointer to the start of the the recordset. Returns 0 if there is no first row.

Definition at line 315 of file dui-initdb.c.

{
    DuiDBPlugin *plg;
    
    if (!rs) return 0;

    plg = rs->provider;
    if (!plg) return 0;
    
    if (plg->recordset_rewind)
    {
        return (plg->recordset_rewind) (rs);
    }
    return 0;
}