/ Check-in [e1f7cf06]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Updates tests and documentation to justify the behavior observed in ticket #2158. No changes to code. (CVS 3580)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:e1f7cf065d2c4ca53e233a4506759a1899ad0560
User & Date: drh 2007-01-09 15:02:03
Context
2007-01-09
15:06
Documentation and tests to show that the cause of a parsing error is available on sqlite3_errmsg after sqlite3_step return SQLITE_SCHEMA. (CVS 3581) check-in: 31a661d4 user: drh tags: trunk
15:02
Updates tests and documentation to justify the behavior observed in ticket #2158. No changes to code. (CVS 3580) check-in: e1f7cf06 user: drh tags: trunk
14:37
Do not use the symbol "interrupt" since that is a reserved word in OpenWatcom. Ticket #2159. (CVS 3579) check-in: 9960ba57 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to test/capi3c.test.

9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
....
1148
1149
1150
1151
1152
1153
1154



1155




1156





























1157
#
#***********************************************************************
# This file implements regression tests for SQLite library.  
#
# 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 $
#

set testdir [file dirname $argv0]
source $testdir/tester.tcl

# Return the UTF-16 representation of the supplied UTF-8 string $str.
# If $nt is true, append two 0x00 bytes as a nul terminator.
................................................................................
  sqlite3_finalize $STMT
} SQLITE_BUSY
do_test capi3c-18.5 {
  db2 eval {COMMIT}
  db2 close
} {}







































finish_test







|







 







>
>
>
|
>
>
>
>
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
....
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
#
#***********************************************************************
# This file implements regression tests for SQLite library.  
#
# 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.4 2007/01/09 15:02:03 drh Exp $
#

set testdir [file dirname $argv0]
source $testdir/tester.tcl

# Return the UTF-16 representation of the supplied UTF-8 string $str.
# If $nt is true, append two 0x00 bytes as a nul terminator.
................................................................................
  sqlite3_finalize $STMT
} SQLITE_BUSY
do_test capi3c-18.5 {
  db2 eval {COMMIT}
  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

Changes to www/capi3ref.tcl.

1
2
3
4
5
6
7
8
....
1177
1178
1179
1180
1181
1182
1183
1184

1185
1186
1187




1188
1189
1190
1191








1192
1193
1194
1195
1196
1197
1198


1199
1200
1201
1202
1203
1204
1205
set rcsid {$Id: capi3ref.tcl,v 1.47 2007/01/04 16:37:41 drh Exp $}
source common.tcl
header {C/C++ Interface For SQLite Version 3}
puts {
<h2>C/C++ Interface For SQLite Version 3</h2>
}

proc api {name prototype desc {notused x}} {
................................................................................
 empty string or a comment) then *ppStmt is set to NULL.  The calling
 procedure is responsible for deleting this compiled SQL statement
 using sqlite3_finalize() after it has finished with it.

 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
 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.




 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








 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
 SQLITE_ERROR code and you would have to make a second call to
 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.


}

api {} {
void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
} {
 <i>Experimental</i>

|







 







|
>
|

|
>
>
>
>


|
<
>
>
>
>
>
>
>
>







>
>







1
2
3
4
5
6
7
8
....
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195

1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
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 {
<h2>C/C++ Interface For SQLite Version 3</h2>
}

proc api {name prototype desc {notused x}} {
................................................................................
 empty string or a comment) then *ppStmt is set to NULL.  The calling
 procedure is responsible for deleting this compiled SQL statement
 using sqlite3_finalize() after it has finished with it.

 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 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 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.  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
 SQLITE_ERROR code and you would have to make a second call to
 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 {} {
void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
} {
 <i>Experimental</i>