Small. Fast. Reliable.
Choose any three.

SQLite C Interface

One-Step Query Execution Interface

int sqlite3_exec(
  sqlite3*,                                  /* An open database */
  const char *sql,                           /* SQL to be evaluted */
  int (*callback)(void*,int,char**,char**),  /* Callback function */
  void *,                                    /* 1st argument to callback */
  char **errmsg                              /* Error msg written here */
);

The sqlite3_exec() interface evaluates zero or more UTF-8 encoded, semicolon-separated SQL statements in the zero-terminated string of its second argument. The SQL statements are evaluated in the context of the database connection specified by in the first argument. SQL statements are prepared one by one using sqlite3_prepare() or the equivalent, evaluated using one or more calls to sqlite3_step(), then destroyed using sqlite3_finalize(). The return value of sqlite3_exec() is SQLITE_OK if all SQL statement run successfully.

If one or more of the SQL statements handed to sqlite3_exec() are queries, then the callback function specified by the 3rd parameter is invoked once for each row of the query result. If the callback returns a non-zero value then the query is aborted, all subsequent SQL statements are skipped and the sqlite3_exec() function returns the SQLITE_ABORT.

The 4th parameter to sqlite3_exec() is an arbitrary pointer that is passed through to the callback function as its first parameter.

The 2nd parameter to the callback function is the number of columns in the query result. The 3rd parameter to the callback is an array of pointers to strings holding the values for each column as extracted using sqlite3_column_text(). NULL values in the result set result in a NULL pointer. All other value are in their UTF-8 string representation. The 4th parameter to the callback is an array of strings obtained using sqlite3_column_name() and holding the names of each column, also in UTF-8.

The callback function may be NULL, even for queries. A NULL callback is not an error. It just means that no callback will be invoked.

If an error occurs while parsing or evaluating the SQL then an appropriate error message is written into memory obtained from sqlite3_malloc() and *errmsg is made to point to that message assuming errmsg is not NULL. The calling function is responsible for freeing the memory using sqlite3_free(). If sqlite3_malloc() fails while attempting to generate the error message, *errmsg is set to NULL. If errmsg is NULL then no attempt is made to generate an error message. (TODO: Is the return code SQLITE_NOMEM or the original error code?) (TODO: What happens if there are multiple errors? Do we get code for the first error, or is the choice of reported error arbitrary?)

The return value is is SQLITE_OK if there are no errors and some other return code if there is an error. The particular return value depends on the type of error.

See also lists of Objects, Constants, and Functions.


This page last modified 2007/12/14 14:37:57 UTC