Name

sqlite3_exec() — Execute SQL statements

Definition

int sqlite3_exec( sqlite3* db, const char* sql,
                  exec_callback, void* udp, char** errmsg );

int exec_callback( void* udp, int c_num, char** c_vals, char** c_names );

db

A database connection.

sql

A null-terminated, UTF-8 encoded string that contains one or more SQL statements. If more than one SQL statement is provided, they must be separated by semicolons.

exec_callback

An optional callback function. This application-defined callback is called once for each row in the result set. If set to NULL, no result data will be made available.

udp

An application-defined user-data pointer. This value is made available to the exec callback function.

errmsg

An optional reference to a string pointer. If the function returns anything other than SQLITE_OK, an error message will be passed back. If no error is encountered, the pointer will be set to NULL. The reference may be NULL to ignore error messages. Error messages must be freed with sqlite3_free().

c_num

The number of columns in the current result row.

c_vals

An array of UTF-8 strings that contain the values of the current result row. These values are generated with sqlite3_column_text() and use the same conversion rules. There is no way to determine the original datatype of the value.

c_names

An array of UTF-8 strings that contain the column names of the current result row. These are generated with sqlite3_column_name().

Returns (sqlite3_exec())

An SQLite result code.

Returns (exec_callback())

If the callback returns a nonzero value, execution of the current statement is halted and sqlite3_exec() will immediately return SQLITE_ABORT.

Description

This function is a convenience function used to run SQL statements in one step. This function will prepare and step through one or more SQL statements, calling the provided callback with each result row. The callback can then process each row of the results. The callback should not attempt to free the memory used to hold the column names or value strings. All result values are given as strings.

Although sqlite3_exec() is an easy way to execute standalone SQL statements, it does not allow the use of statement parameters. This can lead to performance and security concerns for statements that require application-defined values. Manually preparing and executing the statement allows the use of statement parameters and the sqlite3_bind_xxx() functions.

This function has no performance advantage over the explicit sqlite3_prepare() and sqlite3_step() functions. In fact, sqlite3_exec() uses those functions internally.

See Also

sqlite3_column_xxx() (in specific, sqlite3_column_text()), sqlite3_column_name(), sqlite3_prepare_xxx(), sqlite3_step()