The qDecoder Project

qDatabase.c File Reference

Database Independent Wrapper API. More…


Functions

Q_DB * qDbInit (const char *dbtype, const char *addr, int port, const char *username, const char *password, const char *database, bool autocommit)
 Initialize internal connector structure.
bool qDbOpen (Q_DB *db)
 Connect to database server.
bool qDbClose (Q_DB *db)
 Disconnect from database server.
bool qDbFree (Q_DB *db)
 De-allocate Q_DB structure.
const char * qDbGetError (Q_DB *db, unsigned int *errorno)
 Get error number and message.
bool qDbPing (Q_DB *db)
 Checks whether the connection to the server is working.
bool qDbGetLastConnStatus (Q_DB *db)
 Get last connection status.
bool qDbSetFetchType (Q_DB *db, bool use)
 Set result fetching type.
int qDbExecuteUpdate (Q_DB *db, const char *query)
 Executes the update DML.
int qDbExecuteUpdatef (Q_DB *db, const char *format,…)
 Executes the formatted update DML.
Q_DBRESULT * qDbExecuteQuery (Q_DB *db, const char *query)
 Executes the query.
Q_DBRESULT * qDbExecuteQueryf (Q_DB *db, const char *format,…)
 Executes the formatted query.
bool qDbResultNext (Q_DBRESULT *result)
 Retrieves the next row of a result set.
bool qDbResultFree (Q_DBRESULT *result)
 De-allocate the result.
int qDbGetCols (Q_DBRESULT *result)
 Get the number of columns in the result set.
int qDbGetRows (Q_DBRESULT *result)
 Get the number of rows in the result set.
int qDbGetRow (Q_DBRESULT *result)
 Get the current row number.
const char * qDbGetStr (Q_DBRESULT *result, const char *field)
 Get the result as string by field name.
const char * qDbGetStrAt (Q_DBRESULT *result, int idx)
 Get the result as string by column number.
int qDbGetInt (Q_DBRESULT *result, const char *field)
 Get the result as integer by field name.
int qDbGetIntAt (Q_DBRESULT *result, int idx)
 Get the result as integer by column number.
bool qDbBeginTran (Q_DB *db)
 Start transaction.
bool qDbEndTran (Q_DB *db, bool commit)
 End transaction.
bool qDbCommit (Q_DB *db)
 Commit transaction.
bool qDbRollback (Q_DB *db)
 Roll-back transaction.

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.
   [include order at your source codes]
   #include "mysql.h"
   #include "qDecoder.h"

Not documented yet, please refer below sample codes. 

   Q_DB *db = NULL;
   Q_DBRESULT *result = NULL;
   db = qDbInit("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 (qDbOpen(db) == false) {
     printf("WARNING: Can't connect to database.n");
     return -1;
   }
   // get results
   result = qDbExecuteQuery(db, "SELECT name, population FROM City");
   if (result != NULL) {
     printf("COLS : %d , ROWS : %dn", qDbGetCols(result), qDbGetRows(result));
     while (qDbResultNext(result) == true) {
       char *pszName = qDbGetValue(result, "name");
       int   nPopulation = qDbGetInt(result, "population");
       printf("Country : %s , Population : %dn", pszName, nPopulation);
     }
     qDbResultFree(result);
   }
   // close connection
   qDbClose(db);
   // free db object
   qDbFree(db);

Function Documentation

Q_DB* qDbInit ( 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 structure in case of successful, otherwise returns NULL.
   Q_DB *db = NULL;
   db = qDbInit("MYSQL", "dbhost.qdecoder.org", 3306, "test", "secret", "sampledb", true);
   if (db == NULL) {
     printf("ERROR: Not supported database type.n");
     return -1;
   }

bool qDbOpen ( Q_DB *  db  ) 

Connect to database server.

Parameters:
db a pointer of Q_DB which is returned by qDbInit()
Returns:
true if successful, otherwise returns false.

bool qDbClose ( Q_DB *  db  ) 

Disconnect from database server.

Parameters:
db a pointer of Q_DB structure
Returns:
true if successful, otherwise returns false.
Note:
Before you call qDbFree(), Q_DB structure still contains database information. So you can re-connect to database using qDbOpen() without qDbInit().

bool qDbFree ( Q_DB *  db  ) 

De-allocate Q_DB structure.

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

const char* qDbGetError ( Q_DB *  db,
unsigned int *  errorno 
)

Get error number and message.

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

bool qDbPing ( Q_DB *  db  ) 

Checks whether the connection to the server is working.

Parameters:
db a pointer of Q_DB structure
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.

bool qDbGetLastConnStatus ( Q_DB *  db  ) 

Get last connection status.

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

bool qDbSetFetchType ( Q_DB *  db,
bool  use 
)

Set result fetching type.

Parameters:
db a pointer of Q_DB structure
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 qDbSetFetchType(db, true) is called, the results does not actually read into the client. Instead, each row must be retrieved individually by making calls to qDbResultNext(). 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 qDbSetFetchType(db, false).

int qDbExecuteUpdate ( Q_DB *  db,
const char *  query 
)

Executes the update DML.

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

int qDbExecuteUpdatef ( Q_DB *  db,
const char *  format,
  … 
)

Executes the formatted update DML.

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

Q_DBRESULT* qDbExecuteQuery ( Q_DB *  db,
const char *  query 
)

Executes the query.

Parameters:
db a pointer of Q_DB structure
query query string
Returns:
a pointer of Q_DBRESULT

Q_DBRESULT* qDbExecuteQueryf ( Q_DB *  db,
const char *  format,
  … 
)

Executes the formatted query.

Parameters:
db a pointer of Q_DB structure
format query string format
Returns:
a pointer of Q_DBRESULT

bool qDbResultNext ( Q_DBRESULT *  result  ) 

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

bool qDbResultFree ( Q_DBRESULT *  result  ) 

De-allocate the result.

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

int qDbGetCols ( Q_DBRESULT *  result  ) 

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

int qDbGetRows ( Q_DBRESULT *  result  ) 

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

int qDbGetRow ( Q_DBRESULT *  result  ) 

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.

const char* qDbGetStr ( Q_DBRESULT *  result,
const char *  field 
)

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.

const char* qDbGetStrAt ( Q_DBRESULT *  result,
int  idx 
)

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.

int qDbGetInt ( Q_DBRESULT *  result,
const char *  field 
)

Get the result as integer by field name.

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

int qDbGetIntAt ( Q_DBRESULT *  result,
int  idx 
)

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

bool qDbBeginTran ( Q_DB *  db  ) 

Start transaction.

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

bool qDbEndTran ( Q_DB *  db,
bool  commit 
)

End transaction.

Parameters:
db a pointer of Q_DB structure
commit true for commit, false for roll-back
Returns:
true if successful, otherwise returns false

bool qDbCommit ( Q_DB *  db  ) 

Commit transaction.

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

bool qDbRollback ( Q_DB *  db  ) 

Roll-back transaction.

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

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