Small, Fast, Reliable.
Choose any three.

SQLite C Interface

Convenience Routines For Running Queries

int sqlite3_get_table(
  sqlite3*,              /* An open database */
  const char *sql,       /* SQL to be executed */
  char ***resultp,       /* Result written to a char *[]  that this points to */
  int *nrow,             /* Number of result rows written here */
  int *ncolumn,          /* Number of result columns written here */
  char **errmsg          /* Error msg written here */
);
void sqlite3_free_table(char **result);

This next routine is a convenience wrapper around sqlite3_exec(). Instead of invoking a user-supplied callback for each row of the result, this routine remembers each row of the result in memory obtained from sqlite3_malloc(), then returns all of the result after the query has finished.

As an example, suppose the query result where this table:

Name        | Age
-----------------------
Alice       | 43
Bob         | 28
Cindy       | 21

If the 3rd argument were &azResult then after the function returns azResult will contain the following data:

azResult[0] = "Name";
azResult[1] = "Age";
azResult[2] = "Alice";
azResult[3] = "43";
azResult[4] = "Bob";
azResult[5] = "28";
azResult[6] = "Cindy";
azResult[7] = "21";

Notice that there is an extra row of data containing the column headers. But the *nrow return value is still 3. *ncolumn is set to 2. In general, the number of values inserted into azResult will be ((*nrow) + 1)*(*ncolumn).

After the calling function has finished using the result, it should pass the result data pointer to sqlite3_free_table() in order to release the memory that was malloc-ed. Because of the way the sqlite3_malloc() happens, the calling function must not try to call sqlite3_free() directly. Only sqlite3_free_table() is able to release the memory properly and safely.

The return value of this routine is the same as from sqlite3_exec().

See also lists of Objects, Constants, and Functions.


This page last modified 2007/11/22 00:41:31 UTC