Updates tests and documentation to justify the behavior observed in

ticket #2158.  No changes to code. (CVS 3580)

FossilOrigin-Name: e1f7cf065d2c4ca53e233a4506759a1899ad0560

manifest

@@ -1,5 +1,5 @@
-C Do\snot\suse\sthe\ssymbol\s"interrupt"\ssince\sthat\sis\sa\sreserved\sword\sin\nOpenWatcom.\s\sTicket\s#2159.\s(CVS\s3579)
-D 2007-01-09T14:37:18
+C Updates\stests\sand\sdocumentation\sto\sjustify\sthe\sbehavior\sobserved\sin\nticket\s#2158.\s\sNo\schanges\sto\scode.\s(CVS\s3580)
+D 2007-01-09T15:02:03
 F Makefile.in 7fa74bf4359aa899da5586e394d17735f221315f
 F Makefile.linux-gcc 2d8574d1ba75f129aba2019f0b959db380a90935
 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028
@@ -169,7 +169,7 @@ F test/busy.test 0271c854738e23ad76e10d4096a698e5af29d211
 F test/capi2.test 7ecc9b342cc9ec27b53bbf95724cf2e5874fd496
 F test/capi3.test 4063c4be79fb00704154a1e459a38364de9162a9
 F test/capi3b.test 5f0bc94b104e11086b1103b20277e1910f59c7f4
-F test/capi3c.test 19502516df7d541d02bc1662a1b55b925a4a09d0
+F test/capi3c.test 9cb59f052c03f10323fd561e7eac1123ce4d0b97
 F test/cast.test f88e7b6946e9a467cf4bb142d92bb65a83747fc2
 F test/check.test e5ea0c1a06c10e81e3434ca029e2c4a562f2b673
 F test/collate1.test add9454cef160677bb8b34148b8f277ce7f9f1c4
@@ -380,7 +380,7 @@ F www/audit.tcl 90e09d580f79c7efec0c7d6f447b7ec5c2dce5c0
 F www/autoinc.tcl b357f5ba954b046ee35392ce0f884a2fcfcdea06
 F www/c_interface.tcl b51b08591554c16a0c3ef718364a508ac25abc7e
 F www/capi3.tcl 7a7cc225fe02eb7ab861a6019b08baa0014409e1
-F www/capi3ref.tcl 4dbc9521c06b6d5bf0b2f826106fa906c829a55a
+F www/capi3ref.tcl 15a48151bdb0e288b3074331f0e081cd42787b67
 F www/changes.tcl 45bd748d77a00949b7ec7fae7913d139f1b85df4
 F www/common.tcl 14d121c28532ad20c3e349caa4db708b0b822083
 F www/compile.tcl 276546d7eb445add5a867193bbd80f6919a6b084
@@ -424,7 +424,7 @@ F www/tclsqlite.tcl bb0d1357328a42b1993d78573e587c6dcbc964b9
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b
 F www/whentouse.tcl 97e2b5cd296f7d8057e11f44427dea8a4c2db513
-P 43fe7fc1c38f8d9b3c1346cb1d890c2e25cefe15
-R e98954756609bfce82c59eadb5e3c69f
+P 9960ba576827f8ced6eac101313a481f2a2f4b69
+R c38bdef3b37314606ca846892d62f254
 U drh
-Z 5efaea5986d54f8af6d96dce43672e32
+Z c2c4bfa9a140d0193015499de1c84622

manifest.uuid

@@ -1 +1 @@
-9960ba576827f8ced6eac101313a481f2a2f4b69
+e1f7cf065d2c4ca53e233a4506759a1899ad0560

test/capi3c.test

@@ -13,7 +13,7 @@
 # This is a copy of the capi3.test file that has been adapted to
 # test the new sqlite3_prepare_v2 interface.
 #
-# $Id: capi3c.test,v 1.3 2007/01/08 22:40:33 drh Exp $
+# $Id: capi3c.test,v 1.4 2007/01/09 15:02:03 drh Exp $
 #
 
 set testdir [file dirname $argv0]
@@ -1152,6 +1152,42 @@ do_test capi3c-18.5 {
   db2 close
 } {}
 
-
+# Ticket #2158.  The sqlite3_step() will still return SQLITE_SCHEMA
+# if the database schema changes in a way that makes the statement
+# no longer valid.
+#
+do_test capi3c-19.1 {
+  db eval {
+     CREATE TABLE t3(x,y);
+     INSERT INTO t3 VALUES(1,2);
+  }
+  set STMT [sqlite3_prepare_v2 $DB {SELECT * FROM t3} -1 TAIL]
+  sqlite3_step $STMT
+} SQLITE_ROW
+do_test capi3c-19.2 {
+  sqlite3_column_int $STMT 0
+} 1
+do_test capi3c-19.3 {
+  sqlite3_step $STMT
+} SQLITE_DONE
+do_test capi3c-19.4 {
+  sqlite3_reset $STMT
+  db eval {DROP TABLE t3}
+  sqlite3_step $STMT
+} SQLITE_SCHEMA
+do_test capi3c-19.5 {
+  sqlite3_reset $STMT
+  db eval {
+     CREATE TABLE t3(x,y);
+     INSERT INTO t3 VALUES(1,2);
+  }
+  sqlite3_step $STMT
+} SQLITE_ROW
+do_test capi3c-19.6 {
+  sqlite3_column_int $STMT 1
+} 2
+do_test capi3c-19.99 {
+  sqlite3_finalize $STMT
+} SQLITE_OK
 
 finish_test

www/capi3ref.tcl

@@ -1,4 +1,4 @@
-set rcsid {$Id: capi3ref.tcl,v 1.47 2007/01/04 16:37:41 drh Exp $}
+set rcsid {$Id: capi3ref.tcl,v 1.48 2007/01/09 15:02:03 drh Exp $}
 source common.tcl
 header {C/C++ Interface For SQLite Version 3}
 puts {
@@ -1181,14 +1181,26 @@ int sqlite3_prepare16(
  On success, SQLITE_OK is returned.  Otherwise an error code is returned.
 
  The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
- recommended for all new programs. The other two older interfaces are retained
- for backwards compatibility. In the "v2" interfaces, the prepared statement
+ recommended for all new programs. The two older interfaces are retained
+ for backwards compatibility, but their use is discouraged.
+ In the "v2" interfaces, the prepared statement
  that is returned (the sqlite3_stmt object) contains a copy of the original
- SQL. This causes the sqlite3_step() interface to behave a little differently.
+ SQL. This causes the sqlite3_step() interface to behave a differently in
+ two ways:
+
+ <ol>
+ <li>
  If the database schema changes, instead of returning SQLITE_SCHEMA as it
  always used to do, sqlite3_step() will automatically recompile the SQL
- statement and try to run it again. Only after 5 consecutive failures will
- an SQLITE_SCHEMA failure be reported back. The other change is that
+ statement and try to run it again.  If the schema has changed in a way
+ that makes the statement no longer valid, sqlite3_step() will still
+ return SQLITE_SCHEMA.  But unlike the legacy behavior, SQLITE_SCHEMA is
+ now a fatal error.  Calling sqlite3_prepare_v2() again will not make the
+ error go away.
+ </li>
+
+ <li>
+ When an error occurs, 
  sqlite3_step() will return one of the detailed result-codes
  like SQLITE_IOERR or SQLITE_FULL or SQLITE_SCHEMA directly. The
  legacy behavior was that sqlite3_step() would only return a generic
@@ -1196,6 +1208,8 @@ int sqlite3_prepare16(
  sqlite3_reset() in order to find the underlying cause of the problem.
  With the "v2" prepare interfaces, the underlying reason for the error is
  returned directly.
+ </li>
+ </ol>
 }
 
 api {} {