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 evaluated */
>       char ***pResult,      /* Results of the query */
>       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);

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 are give a NULL pointer. All other values are in their UTF-8 zero-terminated string representation as returned by sqlite3_column_text().

A result table might consists 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 malloc-ed. 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:

F12371 | If a sqlite3_get_table() fails a memory allocation, then it frees the result table under construction, aborts the query in process, skips any subsequent queries, sets the *resultp output pointer to NULL and returns SQLITE_NOMEM.
F12373 | If the ncolumn parameter to sqlite3_get_table() is not NULL then sqlite3_get_table() write the number of columns in the result set of the query into *ncolumn if the query is successful (if the function returns SQLITE_OK).
F12374 | If the nrow parameter to sqlite3_get_table() is not NULL then sqlite3_get_table() write the number of rows in the result set of the query into *nrow if the query is successful (if the function returns SQLITE_OK).
F12376 | The sqlite3_get_table() function sets its *ncolumn value to the number of columns in the result set of the query in the sql parameter, or to zero if the query in sql has an empty result set.

See also lists of Objects, Constants, and Functions.

This page last modified 2008/01/31 20:37:13 UTC