The qDecoder Project

qDatabase.c File Reference

Database Independent Wrapper API. More...


Functions

Q_DB * qDb (const char *dbtype, const char *addr, int port, const char *username, const char *password, const char *database, bool autocommit)
 Initialize internal connector structure.
static bool _open (Q_DB *db)
 Q_DB->open(): Connect to database server.
static bool _close (Q_DB *db)
 Q_DB->close(): Disconnect from database server.
static int _executeUpdate (Q_DB *db, const char *query)
 Q_DB->executeUpdate(): Executes the update DML.
static int _executeUpdatef (Q_DB *db, const char *format,...)
 Q_DB->executeUpdatef(): Executes the formatted update DML.
static Q_DBRESULT * _executeQuery (Q_DB *db, const char *query)
 Q_DB->executeQuery(): Executes the query.
static Q_DBRESULT * _executeQueryf (Q_DB *db, const char *format,...)
 Q_DB->executeQueryf(): Executes the formatted query.
static bool _beginTran (Q_DB *db)
 Q_DB->beginTran(): Start transaction.
static bool _commit (Q_DB *db)
 Q_DB->commit(): Commit transaction.
static bool _rollback (Q_DB *db)
 Q_DB->rellback(): Roll-back and abort transaction.
static bool _setFetchType (Q_DB *db, bool use)
 Q_DB->setFetchType(): Set result fetching type.
static bool _getConnStatus (Q_DB *db)
 Q_DB->getConnStatus(): Get last connection status.
static bool _ping (Q_DB *db)
 Q_DB->ping(): Checks whether the connection to the server is working.
static const char * _getError (Q_DB *db, unsigned int *errorno)
 Q_DB->getError(): Get error number and message.
static bool _free (Q_DB *db)
 Q_DB->free(): De-allocate Q_DB structure.
static const char * _resultGetStr (Q_DBRESULT *result, const char *field)
 Q_DBRESULT->getStr(): Get the result as string by field name.
static const char * _resultGetStrAt (Q_DBRESULT *result, int idx)
 Q_DBRESULT->getStrAt(): Get the result as string by column number.
static int _resultGetInt (Q_DBRESULT *result, const char *field)
 Q_DBRESULT->getInt(): Get the result as integer by field name.
static int _resultGetIntAt (Q_DBRESULT *result, int idx)
 Q_DBRESULT->getIntAt(): Get the result as integer by column number.
static bool _resultGetNext (Q_DBRESULT *result)
 Q_DBRESULT->getNext(): Retrieves the next row of a result set.
static int _resultGetCols (Q_DBRESULT *result)
 Q_DBRESULT->getCols(): Get the number of columns in the result set.
static int _resultGetRows (Q_DBRESULT *result)
 Q_DBRESULT->getRows(): Get the number of rows in the result set.
static int _resultGetRow (Q_DBRESULT *result)
 Q_DBRESULT->getRow(): Get the current row number.
static bool _resultFree (Q_DBRESULT *result)
 Q_DBRESULT->free(): De-allocate the result.

Detailed Description

Database Independent Wrapper API.

Note:
To use this API, you must include database header file before including qDecoder.h in your source code like below. And please remember that qDecoder must be compiled with ENABLE_MYSQL or ENABLE_SOME_DATABASE option.
   [mysql.h header should be included prior to qDecoder.h header to let qDecoder know that.]
   #include "mysql.h"
   #include "qDecoder.h"


   Q_DB *db = NULL;
   Q_DBRESULT *result = NULL;

   db = qDb("MYSQL", "dbhost.qdecoder.org", 3306, "test", "secret", "sampledb", true);
   if (db == NULL) {
     printf("ERROR: Not supported database type.\n");
     return -1;
   }

   // try to connect
   if (db->open(db) == false) {
     printf("WARNING: Can't connect to database.\n");
     return -1;
   }

   // get results
   result = db->executeQuery(db, "SELECT name, population FROM City");
   if (result != NULL) {
     printf("COLS : %d , ROWS : %d\n", result->getCols(result), result->getRows(result));
     while (result->getNext(result) == true) {
       char *pszName = result->getStr(result, "name");
       int   nPopulation = result->getInt(result, "population");
       printf("Country : %s , Population : %d\n", pszName, nPopulation);
     }
     result->free(result);
   }

   // close connection
   db->close(db);

   // free db object
   db->free(db);

Note:
Use "--enable-threadsafe" configure script option to use under multi-threaded environments.

Function Documentation

Q_DB* qDb ( const char *  dbtype,
const char *  addr,
int  port,
const char *  username,
const char *  password,
const char *  database,
bool  autocommit 
)

Initialize internal connector structure.

Parameters:
dbtype database server type. currently "MYSQL" is only supported
addr ip or fqdn address.
port port number
username database username
password database password
database database server type. currently "MYSQL" is only supported
autocommit sets autocommit mode on if autocommit is true, off if autocommit is false
Returns:
a pointer of Q_DB object in case of successful, otherwise returns NULL.
   Q_DB *db = qDb("MYSQL", "dbhost.qdecoder.org", 3306, "test", "secret", "sampledb", true);
   if (db == NULL) {
     printf("ERROR: Not supported database type.\n");
     return -1;
   }

static bool _open ( Q_DB *  db  )  [static]

Q_DB->open(): Connect to database server.

Parameters:
db a pointer of Q_DB object
Returns:
true if successful, otherwise returns false.

static bool _close ( Q_DB *  db  )  [static]

Q_DB->close(): Disconnect from database server.

Parameters:
db a pointer of Q_DB object
Returns:
true if successful, otherwise returns false.
Note:
Unless you call Q_DB->free(), Q_DB object will keep the database information. So you can re-connect to database using Q_DB->open().

static int _executeUpdate ( Q_DB *  db,
const char *  query 
) [static]

Q_DB->executeUpdate(): Executes the update DML.

Parameters:
db a pointer of Q_DB object
query query string
Returns:
a number of affected rows

static int _executeUpdatef ( Q_DB *  db,
const char *  format,
  ... 
) [static]

Q_DB->executeUpdatef(): Executes the formatted update DML.

Parameters:
db a pointer of Q_DB object
format query string format
Returns:
a number of affected rows, otherwise returns -1

static Q_DBRESULT* _executeQuery ( Q_DB *  db,
const char *  query 
) [static]

Q_DB->executeQuery(): Executes the query.

Parameters:
db a pointer of Q_DB object
query query string
Returns:
a pointer of Q_DBRESULT if successful, otherwise returns NULL

static Q_DBRESULT* _executeQueryf ( Q_DB *  db,
const char *  format,
  ... 
) [static]

Q_DB->executeQueryf(): Executes the formatted query.

Parameters:
db a pointer of Q_DB object
format query string format
Returns:
a pointer of Q_DBRESULT if successful, otherwise returns NULL

static bool _beginTran ( Q_DB *  db  )  [static]

Q_DB->beginTran(): Start transaction.

Parameters:
db a pointer of Q_DB object
Returns:
true if successful, otherwise returns false
   db->beginTran(db);
   (... insert/update/delete ...)
   db->commit(db);

Note:
This operation will raise lock if you compile "--enable-threadsafe" option to protect thread-safe operation. In this case, before calling Q_DB->commit() or Q_DB->rollback(), another threads will be hold.

static bool _commit ( Q_DB *  db  )  [static]

Q_DB->commit(): Commit transaction.

Parameters:
db a pointer of Q_DB object
Returns:
true if successful, otherwise returns false

static bool _rollback ( Q_DB *  db  )  [static]

Q_DB->rellback(): Roll-back and abort transaction.

Parameters:
db a pointer of Q_DB object
Returns:
true if successful, otherwise returns false

static bool _setFetchType ( Q_DB *  db,
bool  use 
) [static]

Q_DB->setFetchType(): Set result fetching type.

Parameters:
db a pointer of Q_DB object
use false for storing the results to client (default mode), true for fetching directly from server,
Returns:
true if successful otherwise returns false
Note:
If Q_DB->setFetchType(db, true) is called, the results does not actually read into the client. Instead, each row must be retrieved individually by making calls to Q_DBRESULT->getNext(). This reads the result of a query directly from the server without storing it in local buffer, which is somewhat faster and uses much less memory than default behavior Q_DB->setFetchType(db, false).

static bool _getConnStatus ( Q_DB *  db  )  [static]

Q_DB->getConnStatus(): Get last connection status.

Parameters:
db a pointer of Q_DB object
Returns:
true if the connection flag is set to alive, otherwise returns false
Note:
This function just returns the the connection status flag.

static bool _ping ( Q_DB *  db  )  [static]

Q_DB->ping(): Checks whether the connection to the server is working.

Parameters:
db a pointer of Q_DB object
Returns:
true if connection is alive, false if connection is not available and failed to reconnect
Note:
If the connection has gone down, an attempt to reconnect.

static const char* _getError ( Q_DB *  db,
unsigned int *  errorno 
) [static]

Q_DB->getError(): Get error number and message.

Parameters:
db a pointer of Q_DB object
errorno if not NULL, error number will be stored
Returns:
a pointer of error message string
Note:
Do not free returned error message

static bool _free ( Q_DB *  db  )  [static]

Q_DB->free(): De-allocate Q_DB structure.

Parameters:
db a pointer of Q_DB object
Returns:
true if successful, otherwise returns false.

static const char* _resultGetStr ( Q_DBRESULT *  result,
const char *  field 
) [static]

Q_DBRESULT->getStr(): Get the result as string by field name.

Parameters:
result a pointer of Q_DBRESULT
field column name
Returns:
a string pointer if successful, otherwise returns NULL.
Note:
Do not free returned string.

static const char* _resultGetStrAt ( Q_DBRESULT *  result,
int  idx 
) [static]

Q_DBRESULT->getStrAt(): Get the result as string by column number.

Parameters:
result a pointer of Q_DBRESULT
idx column number (first column is 1)
Returns:
a string pointer if successful, otherwise returns NULL.

static int _resultGetInt ( Q_DBRESULT *  result,
const char *  field 
) [static]

Q_DBRESULT->getInt(): Get the result as integer by field name.

Parameters:
result a pointer of Q_DBRESULT
field column name
Returns:
a integer converted value

static int _resultGetIntAt ( Q_DBRESULT *  result,
int  idx 
) [static]

Q_DBRESULT->getIntAt(): Get the result as integer by column number.

Parameters:
result a pointer of Q_DBRESULT
idx column number (first column is 1)
Returns:
a integer converted value

static bool _resultGetNext ( Q_DBRESULT *  result  )  [static]

Q_DBRESULT->getNext(): Retrieves the next row of a result set.

Parameters:
result a pointer of Q_DBRESULT
Returns:
true if successful, false if no more rows are left

static int _resultGetCols ( Q_DBRESULT *  result  )  [static]

Q_DBRESULT->getCols(): Get the number of columns in the result set.

Parameters:
result a pointer of Q_DBRESULT
Returns:
the number of columns in the result set

static int _resultGetRows ( Q_DBRESULT *  result  )  [static]

Q_DBRESULT->getRows(): Get the number of rows in the result set.

Parameters:
result a pointer of Q_DBRESULT
Returns:
the number of rows in the result set

static int _resultGetRow ( Q_DBRESULT *  result  )  [static]

Q_DBRESULT->getRow(): Get the current row number.

Parameters:
result a pointer of Q_DBRESULT
Returns:
current fetching row number of the result set
Note:
This number is sequencial counter which is started from 1.

static bool _resultFree ( Q_DBRESULT *  result  )  [static]

Q_DBRESULT->free(): De-allocate the result.

Parameters:
result a pointer of Q_DBRESULT
Returns:
true if successful, otherwise returns false

[Home] [About] [Examples] [Changes] [Download] [SVN Repository] [Install] [Reference]