int sqlite3_step( sqlite3_stmt* stmt );
stmt
A prepared statement.
An SQLite status code. If a result row is
available, SQLITE_ROW will be returned. When the
statement is done executing, SQLITE_DONE is returned.
Any other value should be considered some type of
error.
This function executes a prepared statement. The function will
return SQLITE_DONE when the
statement has finished executing. At that point, the statement
must be reset before sqlite3_step() can be called again. If the
prepared statement returns any type of value, SQLITE_ROW will be returned.
This indicates a row of data values are available. The
application can extract these values using the sqlite3_column_xxx() functions.
The application can continue to call sqlite3_step() until it returns SQLITE_DONE. This function
should never return SQLITE_OK.
Many SQL commands, such as CREATE
TABLE, never return any SQL values. Most other
SQL commands, such as INSERT,
UPDATE, and DELETE, do not return any SQL
values by default. All of these SQL commands will typically
perform their action and return SQLITE_DONE on the first call to sqlite3_step().
Other commands, like many of the PRAGMA commands, return a single value. In this
interface, these are returned as single-column, single-row
tables. The first call to sqlite3_step() should return SQLITE_ROW, and the second call
should return SQLITE_DONE.
The second call is not actually required, and the application
can simply reset or finalize the statement after the SQL return
value is retrieved.
The SELECT command, and some
PRAGMA commands, will
return full result sets. These are returned one row at a time,
using repeated calls to sqlite3_step().
An application does not have to wait for sqlite3_step() to return
SQLITE_DONE before it
calls sqlite3_reset() or
sqlite3_finalize(). The
current execution can be canceled at any time.
If an error occurs, the results depend on how the statement was
prepared. It is recommended that
all new development use the _v2 versions of sqlite3_prepare(). This makes sqlite3_step()
return more specific error codes. For more information on how
sqlite3_step()
processes error codes, see Prepare v2.
If the database connection encounters concurrency issues, calls
to sqlite3_step() are where
the errors will usually manifest themselves. If a required
database lock is currently unavailable, the code SQLITE_BUSY will be returned.
Properly dealing with this error code is a complex topic. See
Database Locking for details.