From 18657a960e125336f704ea058e25c27bd3900dcb Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 5 May 2024 19:28:19 +0200 Subject: Adding upstream version 3.40.1. Signed-off-by: Daniel Baumann --- www/c3ref/free_table.html | 207 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 www/c3ref/free_table.html (limited to 'www/c3ref/free_table.html') diff --git a/www/c3ref/free_table.html b/www/c3ref/free_table.html new file mode 100644 index 0000000..9c08c28 --- /dev/null +++ b/www/c3ref/free_table.html @@ -0,0 +1,207 @@ + + + + + +Convenience Routines For Running Queries + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ + +
+

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);
+
+

+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 columns (M==2) and three rows (N==3). Thus the +result table has 8 entries. Suppose the result table is stored +in an array named 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 lists of + Objects, + Constants, and + Functions.

+ -- cgit v1.2.3