MafwDB

MafwDB — wrapper around sqlite

Synopsis

gboolean            mafw_db_begin                       (void);
#define             mafw_db_bind_blob                   (stmt, col, val, size)
#define             mafw_db_bind_int                    (stmt, col, val)
#define             mafw_db_bind_int64                  (stmt, col, val)
#define             mafw_db_bind_null                   (stmt, col)
#define             mafw_db_bind_text                   (stmt, col, val)
gint                mafw_db_change                      (sqlite3_stmt *stmt,
                                                         gboolean csint_may_fail);
#define             mafw_db_column_blob                 (stmt, col)
#define             mafw_db_column_int
#define             mafw_db_column_int64
#define             mafw_db_column_null                 (stmt, col)
#define             mafw_db_column_text                 (stmt, col)
gboolean            mafw_db_commit                      (void);
gint                mafw_db_delete                      (sqlite3_stmt *stmt);
gint                mafw_db_do                          (sqlite3_stmt *stmt);
gint                mafw_db_exec                        (gchar const *query);
sqlite3*            mafw_db_get                         (void);
gint                mafw_db_nchanges                    (void);
sqlite3_stmt*       mafw_db_prepare                     (gchar const *query);
gboolean            mafw_db_rollback                    (void);
gint                mafw_db_select                      (sqlite3_stmt *stmt,
                                                         gboolean expect_row);
void                mafw_db_trace                       (void);

Description

This is a set of functions to make like against sqlite a bit easier.

NOTE All binding macros starts counting columns from 0. This is different from the sqlite_bind_*() counterparts, which start indexing from 1, but is consistent with sqlite_column_*().

Details

mafw_db_begin ()

gboolean            mafw_db_begin                       (void);

Convenience function to begin a new transaction. Returns whether it succeeded; on failure a warning is printed. It is an error to start a new transaction while the previous one is not closed.

Returns : TRUE if ok, FALSE otherwise

mafw_db_bind_blob()

#define             mafw_db_bind_blob(stmt, col, val, size)

Binds a byte value to a placeholder with the most commonplace parameters. It relies on the data value remaining valid until the statement is executed.

Note

It starts counting columns from 0. This is different from the sqlite_bind_*() counterparts, which start indexing from 1.

stmt : statement
col : column to set the value
val : new value
size : size of the value

mafw_db_bind_int()

#define             mafw_db_bind_int(stmt, col, val)

Binds an integer value to a placeholder.

Note

It starts counting columns from 0. This is different from the sqlite_bind_*() counterparts, which start indexing from 1.

stmt : statement
col : column to set the value
val : new value

mafw_db_bind_int64()

#define             mafw_db_bind_int64(stmt, col, val)

Binds a int64 value to a placeholder.

Note

It starts counting columns from 0. This is different from the sqlite_bind_*() counterparts, which start indexing from 1.

stmt : statement
col : column to set the value
val : new value

mafw_db_bind_null()

#define             mafw_db_bind_null(stmt, col)

Binds a NULL value to a placeholder with the most commonplace parameters.

Note

It starts counting columns from 0. This is different from the sqlite_bind_*() counterparts, which start indexing from 1.

stmt : statement
col : column to set the value

mafw_db_bind_text()

#define             mafw_db_bind_text(stmt, col, val)

Binds a text value to a placeholder with the most commonplace parameters. It relies on the text value remaining valid until the statement is executed.

Note

It starts counting columns from 0. This is different from the sqlite_bind_*() counterparts, which start indexing from 1.

stmt : statement
col : column to set the value
val : new value

mafw_db_change ()

gint                mafw_db_change                      (sqlite3_stmt *stmt,
                                                         gboolean csint_may_fail);

Attempts to INSERT or UPDATE a row. On error an error message is printed unless it was an expected constraint violation.

stmt : the statement
csint_may_fail : TRUE if operationg can fail
Returns : a sqlite error code

mafw_db_column_blob()

#define             mafw_db_column_blob(stmt, col)

Calls sqlite3_column_blob. Returns the data at column col.

stmt : statement
col : column to get the value

mafw_db_column_int

#define mafw_db_column_int		sqlite3_column_int

Calls sqlite3_column_int. Returns the integer value at column col.


mafw_db_column_int64

#define mafw_db_column_int64		sqlite3_column_int64

Calls sqlite3_column_int64. Returns the integer value at column col.


mafw_db_column_null()

#define             mafw_db_column_null(stmt, col)

Checks, whether the value at col is NULL or not.

stmt : statement
col : column to check the value

mafw_db_column_text()

#define             mafw_db_column_text(stmt, col)

Calls sqlite3_column_text, suppresses gcc's warnings about signed vs. unsigned pointers. Returns the text at column col.

stmt : statement
col : column to get the value

mafw_db_commit ()

gboolean            mafw_db_commit                      (void);

Like mafw_db_begin but COMMITS the active transaction. If it fails you should ROLLBACK your work.

Returns : TRUE if ok, FALSE otherwise.

mafw_db_delete ()

gint                mafw_db_delete                      (sqlite3_stmt *stmt);

Attempts to DELETE a row. On failure a warning is printed.

stmt : statement
Returns : a sqlite error code

mafw_db_do ()

gint                mafw_db_do                          (sqlite3_stmt *stmt);

Tries to execute stmt until the database is unlocked. Between retries SQLite waits for a random amount of time. Note that you need to sqlite3_reset(stmt) after done with it.

stmt : statement
Returns : a sqlite error code.

mafw_db_exec ()

gint                mafw_db_exec                        (gchar const *query);

Executes query, handling busy database errors, and returns the result code of the operation. This function is mainly intended for CREATE TABLE statements, so you should not execute any query that returns any rows (SELECT), unless you are very sure about it. Please note that any kind of errors are reported, eg. "table already exist".

query : the query to execute
Returns : a sqlite error code

mafw_db_get ()

sqlite3*            mafw_db_get                         (void);

Gets a handle to the framework database, taking care of the database creation and error handling. As this resource is global may not free it.

Returns : the handle

mafw_db_nchanges ()

gint                mafw_db_nchanges                    (void);

Convenience function to obtain the number of rows changed due to the last statement, as defined by sqlite3_changes().

Returns : a sqlite error code

mafw_db_prepare ()

sqlite3_stmt*       mafw_db_prepare                     (gchar const *query);

Gets the prepared statement equivalent of query, which should contain exactly one SQL statement. Errors (like a syntax errors) are treated fatal. Take into account that TABLES query refers to must exist before you compile them with this function.

query : the query
Returns : the statement

mafw_db_rollback ()

gboolean            mafw_db_rollback                    (void);

Like mafw_db_begin but ROLLBACKs the current transaction.

Returns : TRUE if ok, FALSE otherwise.

mafw_db_select ()

gint                mafw_db_select                      (sqlite3_stmt *stmt,
                                                         gboolean expect_row);

Attempts to fetch the next row of a SELECT query. On error or if a row was expected but no more found an error message is printed. Returns the same code as sqlite3_exec.

stmt : the statement
expect_row : TRUE if a row is expected
Returns : a sqlite error code

mafw_db_trace ()

void                mafw_db_trace                       (void);

Print every SQL statement about to be executed. Host variables are not expanded.