.Dd January 24, 2024
.Dt SQLITE3_RESET 3
.Os
.Sh NAME
.Nm sqlite3_reset
.Nd reset a prepared statement object
.Sh SYNOPSIS
.In sqlite3.h
.Ft int
.Fo sqlite3_reset
.Fa "sqlite3_stmt *pStmt"
.Fc
.Sh DESCRIPTION
The sqlite3_reset() function is called to reset a prepared statement
object back to its initial state, ready to be re-executed.
Any SQL statement variables that had values bound to them using the
sqlite3_bind_*() API retain their values.
Use
.Fn sqlite3_clear_bindings
to reset the bindings.
.Pp
The sqlite3_reset(S) interface resets the prepared statement
S back to the beginning of its program.
.Pp
The return code from sqlite3_reset(S) indicates whether
or not the previous evaluation of prepared statement S completed successfully.
If sqlite3_step(S) has never before been called on S
or if sqlite3_step(S) has not been called since the
previous call to sqlite3_reset(S), then sqlite3_reset(S)
will return SQLITE_OK.
.Pp
If the most recent call to sqlite3_step(S) for the prepared statement
S indicated an error, then sqlite3_reset(S) returns
an appropriate error code.
The sqlite3_reset(S) interface might also return an
error code if there were no prior errors but the process
of resetting the prepared statement caused a new error.
For example, if an INSERT statement with a RETURNING
clause is only stepped one time, that one call to sqlite3_step(S)
might return SQLITE_ROW but the overall statement might still fail
and the sqlite3_reset(S) call might return SQLITE_BUSY
if locking constraints prevent the database change from committing.
Therefore, it is important that applications check the return code
from sqlite3_reset(S) even if no prior call to sqlite3_step(S)
indicated a problem.
.Pp
The sqlite3_reset(S) interface does not change the
values of any bindings on the prepared statement
S.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 5293.
.Bd -literal
SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
.Ed
.Sh SEE ALSO
.Xr sqlite3_bind_blob 3 ,
.Xr sqlite3_clear_bindings 3 ,
.Xr sqlite3_stmt 3 ,
.Xr SQLITE_OK 3