Small. Fast. Reliable.
Choose any three.

About Sitemap Documentation Download License News Developers Support

## SQLite C Interface

## One-Step Query Execution Interface

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

The sqlite3_exec() interface is a convenient way of running one or more SQL statements without having to write a lot of C code. The UTF-8 encoded SQL statements are passed in as the second parameter to sqlite3_exec(). The statements are evaluated one by one until either an error or an interrupt is encountered, or until they are all done. The 3rd parameter is an optional callback that is invoked once for each row of any query results produced by the SQL statements. The 5th parameter tells where to write any error messages.

The error message passed back through the 5th parameter is held in memory obtained from sqlite3_malloc(). To avoid a memory leak, the calling application should call sqlite3_free() on any error message returned through the 5th parameter when it has finished using the error message.

If the SQL statement in the 2nd parameter is NULL or an empty string or a string containing only whitespace and comments, then no SQL statements are evaluated and the database is not changed.

The sqlite3_exec() interface is implemented in terms of sqlite3_prepare_v2(), sqlite3_step(), and sqlite3_finalize(). The sqlite3_exec() routine does nothing to the database that cannot be done by sqlite3_prepare_v2(), sqlite3_step(), and sqlite3_finalize().

### Invariants:

H12101 | A successful invocation of sqlite3_exec(D,S,C,A,E) shall sequentially evaluate all of the UTF-8 encoded, semicolon-separated SQL statements in the zero-terminated string S within the context of the database connection D.
H12102 | If the S parameter to sqlite3_exec(D,S,C,A,E) is NULL then the actions of the interface shall be the same as if the S parameter were an empty string.
H12104 | The return value of sqlite3_exec() shall be SQLITE_OK if all SQL statements run successfully and to completion.
H12105 | The return value of sqlite3_exec() shall be an appropriate non-zero error code if any SQL statement fails.
H12107 | If one or more of the SQL statements handed to sqlite3_exec() return results and the 3rd parameter is not NULL, then the callback function specified by the 3rd parameter shall be invoked once for each row of result.
H12110 | If the callback returns a non-zero value then sqlite3_exec() shall abort the SQL statement it is currently evaluating, skip all subsequent SQL statements, and return SQLITE_ABORT.
H12113 | The sqlite3_exec() routine shall pass its 4th parameter through as the 1st parameter of the callback.
H12116 | The sqlite3_exec() routine shall set the 2nd parameter of its callback to be the number of columns in the current row of result.
H12119 | The sqlite3_exec() routine shall set the 3rd parameter of its callback to be an array of pointers to strings holding the values for each column in the current result set row as obtained from sqlite3_column_text().
H12122 | The sqlite3_exec() routine shall set the 4th parameter of its callback to be an array of pointers to strings holding the names of result columns as obtained from sqlite3_column_name().
H12125 | If the 3rd parameter to sqlite3_exec() is NULL then sqlite3_exec() shall silently discard query results.
H12131 | If an error occurs while parsing or evaluating any of the SQL statements in the S parameter of sqlite3_exec(D,S,C,A,E) and if the E parameter is not NULL, then sqlite3_exec() shall store in *E an appropriate error message written into memory obtained from sqlite3_malloc().
H12134 | The sqlite3_exec(D,S,C,A,E) routine shall set the value of *E to NULL if E is not NULL and there are no errors.
H12137 | The sqlite3_exec(D,S,C,A,E) function shall set the error code and message accessible via sqlite3_errcode(), sqlite3_extended_errcode(), sqlite3_errmsg(), and sqlite3_errmsg16().
H12138 | If the S parameter to sqlite3_exec(D,S,C,A,E) is NULL or an empty string or contains nothing other than whitespace, comments, and/or semicolons, then results of sqlite3_errcode(), sqlite3_extended_errcode(), sqlite3_errmsg(), and sqlite3_errmsg16() shall reset to indicate no errors.

### Assumptions:

A12141 | The first parameter to sqlite3_exec() must be an valid and open database connection.
A12142 | The database connection must not be closed while sqlite3_exec() is running.
A12143 | The calling function should use sqlite3_free() to free the memory that *errmsg is left pointing at once the error message is no longer needed.
A12145 | The SQL statement text in the 2nd parameter to sqlite3_exec() must remain unchanged while sqlite3_exec() is running.

See also lists of Objects, Constants, and Functions.

This page last modified 2008/08/11 17:57:43 UTC