.Dd January 24, 2024
.Dt SQLITE3_STEP 3
.Os
.Sh NAME
.Nm sqlite3_step
.Nd evaluate an SQL statement
.Sh SYNOPSIS
.In sqlite3.h
.Ft int
.Fo sqlite3_step
.Fa "sqlite3_stmt*"
.Fc
.Sh DESCRIPTION
After a prepared statement has been prepared using
any of
.Fn sqlite3_prepare_v2 ,
.Fn sqlite3_prepare_v3 ,
.Fn sqlite3_prepare16_v2 ,
or
.Fn sqlite3_prepare16_v3
or one of the legacy interfaces
.Fn sqlite3_prepare
or
.Fn sqlite3_prepare16 ,
this function must be called one or more times to evaluate the statement.
.Pp
The details of the behavior of the sqlite3_step() interface depend
on whether the statement was prepared using the newer "vX" interfaces
.Fn sqlite3_prepare_v3 ,
.Fn sqlite3_prepare_v2 ,
.Fn sqlite3_prepare16_v3 ,
.Fn sqlite3_prepare16_v2
or the older legacy interfaces
.Fn sqlite3_prepare
and
.Fn sqlite3_prepare16 .
The use of the new "vX" interface is recommended for new applications
but the legacy interface will continue to be supported.
.Pp
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.
.Pp
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 an explicit
transaction then you should rollback the transaction before continuing.
.Pp
SQLITE_DONE means that the statement has finished executing
successfully.
sqlite3_step() should not be called again on this virtual machine without
first calling
.Fn sqlite3_reset
to reset the virtual machine back to its initial state.
.Pp
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.
.Pp
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
.Fn 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
.Fn sqlite3_reset
on the prepared statement.
In the "v2" interface, the more specific error code is returned directly
by sqlite3_step().
.Pp
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.
.Pp
For all versions of SQLite up to and including 3.6.23.1, a call to
.Fn sqlite3_reset
was required after sqlite3_step() returned anything other than SQLITE_ROW
before any subsequent invocation of sqlite3_step().
Failure to reset the prepared statement using
.Fn sqlite3_reset
would result in an SQLITE_MISUSE return from sqlite3_step().
But after version 3.6.23.1 (dateof:3.6.23.1,
sqlite3_step() began calling
.Fn sqlite3_reset
automatically in this circumstance rather than returning SQLITE_MISUSE.
This is not considered a compatibility break because any application
that ever receives an SQLITE_MISUSE error is broken by definition.
The SQLITE_OMIT_AUTORESET compile-time option
can be used to restore the legacy behavior.
.Pp
\fBGoofy Interface Alert:\fP 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
.Fn sqlite3_reset
or
.Fn 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
.Fn sqlite3_prepare_v3
or
.Fn sqlite3_prepare_v2
or
.Fn sqlite3_prepare16_v2
or
.Fn sqlite3_prepare16_v3
instead of the legacy
.Fn sqlite3_prepare
and
.Fn sqlite3_prepare16
interfaces, then the more specific error codes are returned
directly by sqlite3_step().
The use of the "vX" interfaces is recommended.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 4904.
.Bd -literal
SQLITE_API int sqlite3_step(sqlite3_stmt*);
.Ed
.Sh SEE ALSO
.Xr sqlite3_column_blob 3 ,
.Xr sqlite3_errcode 3 ,
.Xr sqlite3_finalize 3 ,
.Xr sqlite3_prepare 3 ,
.Xr sqlite3_reset 3 ,
.Xr sqlite3_stmt 3 ,
.Xr SQLITE_OK 3