NAME
sqlite3_get_table,
sqlite3_free_table
—
Convenience Routines For Running Queries
SYNOPSIS
int
sqlite3_get_table(
sqlite3 *db,
const char *zSql,
char
***pazResult,
int *pnRow,
int
*pnColumn,
char **pzErrmsg );
void
sqlite3_free_table(
char **result);
DESCRIPTION
This is a legacy interface that is preserved for backwards compatibility. Use of
this interface is not recommended.
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 and
returns a result table to the pointer given in its 3rd parameter.
After the application has finished with the result from sqlite3_get_table(), it
must pass the result table pointer 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().
SEE ALSO
sqlite3_column_blob(3),
sqlite3_errcode(3),
sqlite3_exec(3),
sqlite3_malloc(3),
sqlite3_get_table(3),
sqlite3_malloc(3)