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 *db,          /* An open database */
>       const char *zSql,     /* SQL to be evaluated */
>       char ***pazResult,    /* Results of the query */
>       int *pnRow,           /* Number of result rows written here */
>       int *pnColumn,        /* Number of result columns written here */
>       char **pzErrmsg       /* Error msg written here */
>     );
>     void sqlite3_free_table(char **result);

Definition: A result table is memory data structure created by the sqlite3_get_table() interface. A result table records the complete query results from one or more queries.

The table conceptually has a number of rows and columns. But these numbers are not part of the result table itself. These numbers are obtained separately. Let N be the number of rows and M be the number of columns.

A result table is an array of pointers to zero-terminated UTF-8 strings. There are (N+1)*M elements in the array. The first M pointers point to zero-terminated strings that contain the names of the columns. The remaining entries all point to query results. NULL values result in NULL pointers. All other values are in their UTF-8 zero-terminated string representation as returned by sqlite3_column_text().

A result table might consist of one or more memory allocations. It is not safe to pass a result table directly to sqlite3_free(). A result table should be deallocated using sqlite3_free_table().

As an example of the result table format, suppose a query result is as follows:

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

There are two column (M==2) and three rows (N==3). Thus the result table has 8 entries. Suppose the result table is stored in an array names azResult. Then azResult holds this content:

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

The sqlite3_get_table() function evaluates one or more semicolon-separated SQL statements in the zero-terminated UTF-8 string of its 2nd parameter. It returns a result table to the pointer given in its 3rd parameter.

After the calling function has finished using the result, it should pass the pointer to the result table to sqlite3_free_table() in order to release the memory that was malloced. Because of the way the sqlite3_malloc() happens within sqlite3_get_table(), 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 sqlite3_get_table() interface is implemented as a wrapper around sqlite3_exec(). The sqlite3_get_table() routine does not have access to any internal data structures of SQLite. It uses only the public interface defined here. As a consequence, errors that occur in the wrapper layer outside of the internal sqlite3_exec() call are not reflected in subsequent calls to sqlite3_errcode() or sqlite3_errmsg().

### Invariants:

H12371 | If a sqlite3_get_table() fails a memory allocation, then it shall free the result table under construction, abort the query in process, skip any subsequent queries, set the *pazResult output pointer to NULL and return SQLITE_NOMEM.
H12373 | If the pnColumn parameter to sqlite3_get_table() is not NULL then a successful invocation of sqlite3_get_table() shall write the number of columns in the result set of the query into *pnColumn.
H12374 | If the pnRow parameter to sqlite3_get_table() is not NULL then a successful invocation of sqlite3_get_table() shall writes the number of rows in the result set of the query into *pnRow.
H12376 | A successful invocation of sqlite3_get_table() that computes N rows of result with C columns per row shall make *pazResult point to an array of pointers to (N+1)*C strings where the first C strings are column names as obtained from sqlite3_column_name() and the rest are column result values obtained from sqlite3_column_text().
H12379 | The values in the pazResult array returned by sqlite3_get_table() shall remain valid until cleared by sqlite3_free_table().
H12382 | When an error occurs during evaluation of sqlite3_get_table() the function shall set *pazResult to NULL, write an error message into memory obtained from sqlite3_malloc(), make **pzErrmsg point to that error message, and return a appropriate error code.

See also lists of Objects, Constants, and Functions.

This page last modified 2008/08/11 17:57:43 UTC