Small. Fast. Reliable.
Choose any three.

About Sitemap Documentation Download License News Developers Support

## SQLite C Interface

## Evaluate An SQL Statement

>     int sqlite3_step(sqlite3_stmt*);

After a prepared statement has been prepared using either sqlite3_prepare_v2() or sqlite3_prepare16_v2() or one of the legacy interfaces sqlite3_prepare() or sqlite3_prepare16(), this function must be called one or more times to evaluate the statement.

The details of the behavior of the sqlite3_step() interface depend on whether the statement was prepared using the newer "v2" interface sqlite3_prepare_v2() and sqlite3_prepare16_v2() or the older legacy interface sqlite3_prepare() and sqlite3_prepare16(). The use of the new "v2" interface is recommended for new applications but the legacy interface will continue to be supported.

In the legacy interface, the return value will be either SQLITE_BUSY, SQLITE_DONE, SQLITE_ROW, SQLITE_ERROR, or SQLITE_MISUSE. With the "v2" interface, any of the other result codes or extended result codes might be returned as well.

SQLITE_BUSY means that the database engine was unable to acquire the database locks it needs to do its job. If the statement is a COMMIT or occurs outside of an explicit transaction, then you can retry the statement. If the statement is not a COMMIT and occurs within a explicit transaction then you should rollback the transaction before continuing.

SQLITE_DONE means that the statement has finished executing successfully. sqlite3_step() should not be called again on this virtual machine without first calling sqlite3_reset() to reset the virtual machine back to its initial state.

If the SQL statement being executed returns any data, then SQLITE_ROW is returned each time a new row of data is ready for processing by the caller. The values may be accessed using the column access functions. sqlite3_step() is called again to retrieve the next row of data.

SQLITE_ERROR means that a run-time error (such as a constraint violation) has occurred. sqlite3_step() should not be called again on the VM. More information may be found by calling sqlite3_errmsg(). With the legacy interface, a more specific error code (for example, SQLITE_INTERRUPT, SQLITE_SCHEMA, SQLITE_CORRUPT, and so forth) can be obtained by calling sqlite3_reset() on the prepared statement. In the "v2" interface, the more specific error code is returned directly by sqlite3_step().

SQLITE_MISUSE means that the this routine was called inappropriately. Perhaps it was called on a prepared statement that has already been finalized or on one that had previously returned SQLITE_ERROR or SQLITE_DONE. Or it could be the case that the same database connection is being used by two or more threads at the same moment in time.

Goofy Interface Alert: In the legacy interface, the sqlite3_step() API always returns a generic error code, SQLITE_ERROR, following any error other than SQLITE_BUSY and SQLITE_MISUSE. You must call sqlite3_reset() or sqlite3_finalize() in order to find one of the specific error codes that better describes the error. We admit that this is a goofy design. The problem has been fixed with the "v2" interface. If you prepare all of your SQL statements using either sqlite3_prepare_v2() or sqlite3_prepare16_v2() instead of the legacy sqlite3_prepare() and sqlite3_prepare16() interfaces, then the more specific error codes are returned directly by sqlite3_step(). The use of the "v2" interface is recommended.

### Invariants:

H13202 | If the prepared statement S is ready to be run, then sqlite3_step(S) advances that prepared statement until completion or until it is ready to return another row of the result set, or until an interrupt or a run-time error occurs.
H15304 | When a call to sqlite3_step(S) causes the prepared statement S to run to completion, the function returns SQLITE_DONE.
H15306 | When a call to sqlite3_step(S) stops because it is ready to return another row of the result set, it returns SQLITE_ROW.
H15308 | If a call to sqlite3_step(S) encounters an interrupt or a run-time error, it returns an appropriate error code that is not one of SQLITE_OK, SQLITE_ROW, or SQLITE_DONE.
H15310 | If an interrupt or a run-time error occurs during a call to sqlite3_step(S) for a prepared statement S created using legacy interfaces sqlite3_prepare() or sqlite3_prepare16(), then the function returns either SQLITE_ERROR, SQLITE_BUSY, or SQLITE_MISUSE.

See also lists of Objects, Constants, and Functions.

This page last modified 2008/12/09 18:44:04 UTC