Changes to the error handling policies of sqlite3_exec() to make them

more consistent.  Changes to the documentation on the error handling
polices of sqlite3_exec() so that the documentation and code agree. (CVS 5148)

FossilOrigin-Name: a0376c7907db8e2993ce48e484001e981fbbb187

diff --git a/manifest b/manifest
index 1a1d2b28b85238dfddbd02ec2a1a9789f47dfbb4..d96063514697d6449b14640553650203d07e80b9 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Added\smore\sDST\sboundary\schecks\sfor\s2006\sand\s2007.\s\sAdded\scheck\sfor\ssuspect\sWindows\sDST\simplementations\sand\swarning\sabout\sthem.\s\sTicket\s#2322.\s(CVS\s5147)
-D 2008-05-20T14:01:59
+C Changes\sto\sthe\serror\shandling\spolicies\sof\ssqlite3_exec()\sto\smake\sthem\nmore\sconsistent.\s\sChanges\sto\sthe\sdocumentation\son\sthe\serror\shandling\npolices\sof\ssqlite3_exec()\sso\sthat\sthe\sdocumentation\sand\scode\sagree.\s(CVS\s5148)
+D 2008-05-20T15:44:31
 F Makefile.arm-wince-mingw32ce-gcc ac5f7b2cef0cd850d6f755ba6ee4ab961b1fadf7
 F Makefile.in 79aeba12300a54903f1b1257c1e7c190234045dd
 F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654
@@ -100,7 +100,7 @@ F src/hash.c fd8cb06fb54c2fe7d48c9195792059a2e5be8b70
 F src/hash.h 031cd9f915aff27e12262cb9eb570ac1b8326b53
 F src/insert.c 77f0829b3e2edd19e9238195c56b0d56ab000f17
 F src/journal.c cffd2cd214e58c0e99c3ff632b3bee6c7cbb260e
-F src/legacy.c 4568e4762272cd671722f0b054eb05801aab2af2
+F src/legacy.c 8f5a2b25d9673b4004287cf2bf51dbf7d0738406
 F src/loadext.c eac6c61810a3b531808774bec7f3d238cfe261f3
 F src/main.c 2d1cf908a2e874f9bad7e8bff6b93c057dff6ba7
 F src/malloc.c 12c1ae98ef1eff34b13c9eb526e0b7b479e1e820
@@ -130,7 +130,7 @@ F src/printf.c f2d4f6c5b0ec24b643e85fe60258adad8b1f6acc
 F src/random.c 2b2db2de4ab491f5a14d3480466f8f4b5a5db74a
 F src/select.c da43ce3080112aa77863e9c570c1df19a892acb8
 F src/shell.c a12ea645271b7876c8f080146f48e20b00d367ec
-F src/sqlite.h.in f1d8355483f2688ab385522bd95edaecc55b1f2a
+F src/sqlite.h.in a7c0d013f1e7658d577f444c19401028bebefb8e
 F src/sqlite3ext.h faacd0e6a81aabee0861c6d7883c9172e74ef5b3
 F src/sqliteInt.h 70a2b0bf856bbdb86b10d994ea863f6591ab7144
 F src/sqliteLimit.h f435e728c6b620ef7312814d660a81f9356eb5c8
@@ -636,7 +636,7 @@ F www/tclsqlite.tcl 8be95ee6dba05eabcd27a9d91331c803f2ce2130
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b
 F www/whentouse.tcl fc46eae081251c3c181bd79c5faef8195d7991a5
-P 2faf69ca1da43f8083b96675a4886648f10177d8
-R 6df5a2e7a1004d286b1e02fdd89d3f9d
-U shane
-Z 473f14dd2f4e8d627d9c50329fe96aff
+P 14226ff0a7af7b39a1089a17eeb5bbb8d09d778d
+R 1df4c3c30897afb9891ee14aa1e87dfb
+U drh
+Z 8a6ec6e166342e293c336a4411766224

diff --git a/manifest.uuid b/manifest.uuid
index d54c470d878d86e1896067082014d15d37d7960e..f64423666b72499982cc8afdd49a2cd2708d4f9e 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-14226ff0a7af7b39a1089a17eeb5bbb8d09d778d
\ No newline at end of file
+a0376c7907db8e2993ce48e484001e981fbbb187
\ No newline at end of file

diff --git a/src/legacy.c b/src/legacy.c
index ea12e80741a7ca2ce90c0c09a7b044828b868d75..130ba01748bfe7955b7501184b44377fdc2c59c9 100644 (file)
--- a/src/legacy.c
+++ b/src/legacy.c
@@ -14,7 +14,7 @@
 ** other files are for internal use by SQLite and should not be
 ** accessed by users of the library.
 **
-** $Id: legacy.c,v 1.25 2008/05/19 23:51:55 drh Exp $
+** $Id: legacy.c,v 1.26 2008/05/20 15:44:31 drh Exp $
 */
 
 #include "sqliteInt.h"
@@ -45,9 +45,10 @@ int sqlite3_exec(
   int nRetry = 0;
   int nCallback;
 
-  if( zSql==0 ) return SQLITE_OK;
+  if( zSql==0 ) zSql = "";
 
   sqlite3_mutex_enter(db->mutex);
+  sqlite3Error(db, SQLITE_OK, 0);
   while( (rc==SQLITE_OK || (rc==SQLITE_SCHEMA && (++nRetry)<2)) && zSql[0] ){
     int nCol;
     char **azVals = 0;

diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index 47d8cf6c084b75e9a36396ad1035af465cd99366..116bee7546e693019dde4026bbd68d671d93d8f7 100644 (file)
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -30,7 +30,7 @@
 ** the version number) and changes its name to "sqlite3.h" as
 ** part of the build process.
 **
-** @(#) $Id: sqlite.h.in,v 1.313 2008/05/19 23:51:55 drh Exp $
+** @(#) $Id: sqlite.h.in,v 1.314 2008/05/20 15:44:31 drh Exp $
 */
 #ifndef _SQLITE3_H_
 #define _SQLITE3_H_
@@ -270,11 +270,20 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**);
 ** produced by the SQL statements.  The 5th parameter tells where
 ** to write any error messages.
 **
+** The error message passed back through the 5th parameter is held
+** in memory obtained from [sqlite3_malloc()].  To avoid a memory leak,
+** the calling application should call [sqlite3_free()] on any error
+** message returned through the 5th parameter when it has finished using
+** the error message.
+**
+** If the SQL statement in the 2nd parameter is NULL or an empty string
+** or a string containing only whitespace and comments, then SQL
+** statements are evaluated and the database is unchanged.
+**
 ** The sqlite3_exec() interface is implemented in terms of
 ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
-** The sqlite3_exec() routine does nothing that cannot be done
+** The sqlite3_exec() routine does nothing to the database that cannot be done
 ** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
-** The sqlite3_exec() is just a convenient wrapper.
 **
 ** INVARIANTS:
 ** 
@@ -283,14 +292,15 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**);
 **          SQL statements in the zero-terminated string S within the
 **          context of the D [database connection].
 **
-** {F12102} When the S argment to [sqlite3_exec(D,S,C,A,E)] is an empty string
-**          then the [sqlite3_exec()] call shall be a no-op.
+** {F12102} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is NULL then
+**          the actions of the interface shall be the same as if the
+**          S parameter where an empty string.
 **
 ** {F12104} The return value of [sqlite3_exec()] shall be SQLITE_OK if all
 **          SQL statements run successfully and to completion.
 **
 ** {F12105} The return value of [sqlite3_exec()] shall be an appropriate 
-**          non-zero error code if any SQL statement fails.
+**          non-zero [error code] if any SQL statement fails.
 **
 ** {F12107} If one or more of the SQL statements handed to [sqlite3_exec()]
 **          return results and the 3rd parameter is not NULL, then
@@ -301,11 +311,7 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**);
 **          shall aborted the SQL statement it is currently evaluating,
 **          skip all subsequent SQL statements, and return [SQLITE_ABORT].
 **
-** {F12111} Following a call to [sqlite3_exec()] where the callback returns
-**          non-zero, the [sqlite3_errcode()], [sqlite3_errmsg()], and
-**          [sqlite3_errmsg16()] routines shall return no error.
-**
-** {F12113} The [sqlite3_exec()] routine will pass its 4th parameter through
+** {F12113} The [sqlite3_exec()] routine shall pass its 4th parameter through
 **          as the 1st parameter of the callback.
 **
 ** {F12116} The [sqlite3_exec()] routine sets the 2nd parameter of its
@@ -325,25 +331,21 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**);
 **          [sqlite3_exec()] never invokes a callback.  All query
 **          results are silently discarded.
 **
-** {F12128} If an error occurs while parsing or evaluating any of the SQL
-**          statements handed to [sqlite3_exec()] then [sqlite3_exec()] will
-**          return an [error code] other than [SQLITE_OK].
-**
 ** {F12131} If an error occurs while parsing or evaluating any of the SQL
 **          handed in the S parameter of [sqlite3_exec(D,S,C,A,E)] and if
-**          the E parameter is not NULL, then sqlit3_exec shall store in *E
-**          an appropriate error message written into memory obtained
+**          the E parameter is not NULL, then [sqlite3_exec()] shall store
+**          in *E an appropriate error message written into memory obtained
 **          from [sqlite3_malloc()].
 **
-** {F12134} The [sqlite3_exec(D,S,C,A,E)] routine does not change the value of
-**          *E if E is NULL or if there are no errors.
+** {F12134} The [sqlite3_exec(D,S,C,A,E)] routine shall set the value of
+**          *E to NULL if E is not NULL and there are no errors.
 **
-** {F12137} The [sqlite3_exec()] function sets the error code and message
-**          accessible via [sqlite3_errcode()], [sqlite3_errmsg()], and
-**          [sqlite3_errmsg16()].
+** {F12137} The [sqlite3_exec(D,S,C,A,E)] function shall set the error code
+**          and message accessible via [sqlite3_errcode()],
+**          [sqlite3_errmsg()], and [sqlite3_errmsg16()].
 **
-** {F12138} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is not an empty
-**          string but contains nothing other than whitespace, comments, and/or
+** {F12138} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is a null or empty
+**          string or contains nothing other than whitespace, comments, and/or
 **          semicolons, then results of [sqlite3_errcode()],
 **          [sqlite3_errmsg()], and [sqlite3_errmsg16()]
 **          shall reset to indicate no errors.
@@ -356,7 +358,7 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**);
 ** {U12142} The database connection must not be closed while
 **          [sqlite3_exec()] is running.
 ** 
-** {U12143} The calling function is should use [sqlite3_free()] to free
+** {U12143} The calling function should use [sqlite3_free()] to free
 **          the memory that *errmsg is left pointing at once the error
 **          message is no longer needed.
 **