diff options
Diffstat (limited to 'src/sqlite.h.in')
| -rw-r--r-- | src/sqlite.h.in | 30 |
1 files changed, 17 insertions, 13 deletions
diff --git a/src/sqlite.h.in b/src/sqlite.h.in index 9e165c1e5..668cfa54b 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -4425,24 +4425,28 @@ int sqlite3_stmt_isexplain(sqlite3_stmt *pStmt); ** CAPI3REF: Change The EXPLAIN Setting For A Prepared Statement ** METHOD: sqlite3_stmt ** -** ^The sqlite3_stmt_explain(S,E) interface changes the EXPLAIN +** The sqlite3_stmt_explain(S,E) interface changes the EXPLAIN ** setting for prepared statement S. If E is zero, then S becomes ** a normal prepared statement. If E is 1, then S behaves as if ** its SQL text began with "EXPLAIN". If E is 2, then S behaves as if ** its SQL text began with "EXPLAIN QUERY PLAN". ** -** Calling sqlite3_stmt_explain(S,E) causes prepared statement S -** to be reprepared. A call to sqlite3_stmt_explain(S,E) will fail -** with SQLITE_ERROR if S cannot be re-prepared because it was created -** using sqlite3_prepare() instead of the newer sqlite_prepare_v2() or -** sqlite3_prepare_v3() interfaces and hence has no saved SQL text with -** which to reprepare. Changing the explain setting for a prepared -** statement does not change the original SQL text for the statement. -** Hence, if the SQL text originally began with EXPLAIN or EXPLAIN -** QUERY PLAN, but sqlite3_stmt_explain(S,0) is called to convert the -** statement into an ordinary statement, the EXPLAIN or EXPLAIN QUERY -** PLAN keywords still appear in the sqlite3_sql(S) output, even though -** the statement now acts like a normal SQL statement. +** Calling sqlite3_stmt_explain(S,E) might cause S to be reprepared. +** SQLite tries to avoid a reprepare, but a reprepare might be necessary +** on the first transition into EXPLAIN or EXPLAIN QUERY PLAN mode. +** +** Because of the potential need to reprepare, a call to +** sqlite3_stmt_explain(S,E) will fail with SQLITE_ERROR if S cannot be +** reprepared because it was created using sqlite3_prepare() instead of +** the newer sqlite_prepare_v2() or sqlite3_prepare_v3() interfaces and +** hence has no saved SQL text with which to reprepare. +** +** Changing the explain setting for a prepared statement does not change +** the original SQL text for the statement. Hence, if the SQL text originally +** began with EXPLAIN or EXPLAIN QUERY PLAN, but sqlite3_stmt_explain(S,0) +** is called to convert the statement into an ordinary statement, the EXPLAIN +** or EXPLAIN QUERY PLAN keywords will still appear in the sqlite3_sql(S) +** output, even though the statement now acts like a normal SQL statement. ** ** This routine returns SQLITE_OK if the explain mode is successfully ** changed, or an error code if the explain mode could not be changed. |