Small. Fast. Reliable.
Choose any three.

About Sitemap Documentation Download License News Developers Support

## 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/12/14 14:37:57 UTC