The qDecoder Project: C/C++ Library

- Main Page
- Data Structures
- Files

- File List
- Globals

# 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 : %d\n", qDbGetCols(result), qDbGetRows(result));
         while (qDbResultNext(result) == true) {
           char *pszName = qDbGetValue(result, "name");
           int   nPopulation = qDbGetInt(result, "population");
           printf("Country : %s , Population : %d\n", 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]