1.Dd January 24, 2024 2.Dt SQLITE3_STEP 3 3.Os 4.Sh NAME 5.Nm sqlite3_step 6.Nd evaluate an SQL statement 7.Sh SYNOPSIS 8.In sqlite3.h 9.Ft int 10.Fo sqlite3_step 11.Fa "sqlite3_stmt*" 12.Fc 13.Sh DESCRIPTION 14After a prepared statement has been prepared using 15any of 16.Fn sqlite3_prepare_v2 , 17.Fn sqlite3_prepare_v3 , 18.Fn sqlite3_prepare16_v2 , 19or 20.Fn sqlite3_prepare16_v3 21or one of the legacy interfaces 22.Fn sqlite3_prepare 23or 24.Fn sqlite3_prepare16 , 25this function must be called one or more times to evaluate the statement. 26.Pp 27The details of the behavior of the sqlite3_step() interface depend 28on whether the statement was prepared using the newer "vX" interfaces 29.Fn sqlite3_prepare_v3 , 30.Fn sqlite3_prepare_v2 , 31.Fn sqlite3_prepare16_v3 , 32.Fn sqlite3_prepare16_v2 33or the older legacy interfaces 34.Fn sqlite3_prepare 35and 36.Fn sqlite3_prepare16 . 37The use of the new "vX" interface is recommended for new applications 38but the legacy interface will continue to be supported. 39.Pp 40In the legacy interface, the return value will be either SQLITE_BUSY, 41SQLITE_DONE, SQLITE_ROW, SQLITE_ERROR, 42or SQLITE_MISUSE. 43With the "v2" interface, any of the other result codes 44or extended result codes might be returned as 45well. 46.Pp 47SQLITE_BUSY means that the database engine was unable to 48acquire the database locks it needs to do its job. 49If the statement is a COMMIT or occurs outside of an explicit 50transaction, then you can retry the statement. 51If the statement is not a COMMIT and occurs within an explicit 52transaction then you should rollback the transaction before continuing. 53.Pp 54SQLITE_DONE means that the statement has finished executing 55successfully. 56sqlite3_step() should not be called again on this virtual machine without 57first calling 58.Fn sqlite3_reset 59to reset the virtual machine back to its initial state. 60.Pp 61If the SQL statement being executed returns any data, then SQLITE_ROW 62is returned each time a new row of data is ready for processing by 63the caller. 64The values may be accessed using the column access functions. 65sqlite3_step() is called again to retrieve the next row of data. 66.Pp 67SQLITE_ERROR means that a run-time error (such as a constraint 68violation) has occurred. 69sqlite3_step() should not be called again on the VM. 70More information may be found by calling 71.Fn sqlite3_errmsg . 72With the legacy interface, a more specific error code (for example, 73SQLITE_INTERRUPT, SQLITE_SCHEMA, SQLITE_CORRUPT, 74and so forth) can be obtained by calling 75.Fn sqlite3_reset 76on the prepared statement. 77In the "v2" interface, the more specific error code is returned directly 78by sqlite3_step(). 79.Pp 80SQLITE_MISUSE means that the this routine was called inappropriately. 81Perhaps it was called on a prepared statement that 82has already been finalized or on one that had previously returned 83SQLITE_ERROR or SQLITE_DONE. 84Or it could be the case that the same database connection is being 85used by two or more threads at the same moment in time. 86.Pp 87For all versions of SQLite up to and including 3.6.23.1, a call to 88.Fn sqlite3_reset 89was required after sqlite3_step() returned anything other than SQLITE_ROW 90before any subsequent invocation of sqlite3_step(). 91Failure to reset the prepared statement using 92.Fn sqlite3_reset 93would result in an SQLITE_MISUSE return from sqlite3_step(). 94But after version 3.6.23.1 (dateof:3.6.23.1, 95sqlite3_step() began calling 96.Fn sqlite3_reset 97automatically in this circumstance rather than returning SQLITE_MISUSE. 98This is not considered a compatibility break because any application 99that ever receives an SQLITE_MISUSE error is broken by definition. 100The SQLITE_OMIT_AUTORESET compile-time option 101can be used to restore the legacy behavior. 102.Pp 103\fBGoofy Interface Alert:\fP In the legacy interface, the sqlite3_step() 104API always returns a generic error code, SQLITE_ERROR, 105following any error other than SQLITE_BUSY and SQLITE_MISUSE. 106You must call 107.Fn sqlite3_reset 108or 109.Fn sqlite3_finalize 110in order to find one of the specific error codes that better 111describes the error. 112We admit that this is a goofy design. 113The problem has been fixed with the "v2" interface. 114If you prepare all of your SQL statements using 115.Fn sqlite3_prepare_v3 116or 117.Fn sqlite3_prepare_v2 118or 119.Fn sqlite3_prepare16_v2 120or 121.Fn sqlite3_prepare16_v3 122instead of the legacy 123.Fn sqlite3_prepare 124and 125.Fn sqlite3_prepare16 126interfaces, then the more specific error codes are returned 127directly by sqlite3_step(). 128The use of the "vX" interfaces is recommended. 129.Sh IMPLEMENTATION NOTES 130These declarations were extracted from the 131interface documentation at line 4904. 132.Bd -literal 133SQLITE_API int sqlite3_step(sqlite3_stmt*); 134.Ed 135.Sh SEE ALSO 136.Xr sqlite3_column_blob 3 , 137.Xr sqlite3_errcode 3 , 138.Xr sqlite3_finalize 3 , 139.Xr sqlite3_prepare 3 , 140.Xr sqlite3_reset 3 , 141.Xr sqlite3_stmt 3 , 142.Xr SQLITE_OK 3 143