|
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.