SQLite

Check-in [a0376c7907]
Login

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

Overview
Comment: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)
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: a0376c7907db8e2993ce48e484001e981fbbb187
User & Date: drh 2008-05-20 15:44:31.000
Context
2008-05-20
18:43
Corrections to the documented behavior of sqlite3_last_insert_rowid(). (This change is unrelated to the problem reported by Bram de Jong. That comes next.) (CVS 5149) (check-in: 894085a59c user: drh tags: trunk)
15:44
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) (check-in: a0376c7907 user: drh tags: trunk)
14:01
Added more DST boundary checks for 2006 and 2007. Added check for suspect Windows DST implementations and warning about them. Ticket #2322. (CVS 5147) (check-in: 14226ff0a7 user: shane tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to src/legacy.c.
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
**
*************************************************************************
** Main file for the SQLite library.  The routines in this file
** implement the programmer interface to the library.  Routines in
** 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 $
*/

#include "sqliteInt.h"
#include <ctype.h>

/*
** Execute SQL code.  Return one of the SQLITE_ success/failure







|







10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
**
*************************************************************************
** Main file for the SQLite library.  The routines in this file
** implement the programmer interface to the library.  Routines in
** other files are for internal use by SQLite and should not be
** accessed by users of the library.
**
** $Id: legacy.c,v 1.26 2008/05/20 15:44:31 drh Exp $
*/

#include "sqliteInt.h"
#include <ctype.h>

/*
** Execute SQL code.  Return one of the SQLITE_ success/failure
41
42
43
44
45
46
47
48
49
50

51
52
53
54
55
56
57
  const char *zLeftover;
  sqlite3_stmt *pStmt = 0;
  char **azCols = 0;

  int nRetry = 0;
  int nCallback;

  if( zSql==0 ) return SQLITE_OK;

  sqlite3_mutex_enter(db->mutex);

  while( (rc==SQLITE_OK || (rc==SQLITE_SCHEMA && (++nRetry)<2)) && zSql[0] ){
    int nCol;
    char **azVals = 0;

    pStmt = 0;
    rc = sqlite3_prepare(db, zSql, -1, &pStmt, &zLeftover);
    assert( rc==SQLITE_OK || pStmt==0 );







|


>







41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
  const char *zLeftover;
  sqlite3_stmt *pStmt = 0;
  char **azCols = 0;

  int nRetry = 0;
  int nCallback;

  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;

    pStmt = 0;
    rc = sqlite3_prepare(db, zSql, -1, &pStmt, &zLeftover);
    assert( rc==SQLITE_OK || pStmt==0 );
Changes to src/sqlite.h.in.
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
** on how SQLite interfaces are suppose to operate.
**
** The name of this file under configuration management is "sqlite.h.in".
** The makefile makes some minor changes to this file (such as inserting
** 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 $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
#include <stdarg.h>     /* Needed for the definition of va_list */

/*
** Make sure we can call this stuff from C++.







|







26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
** on how SQLite interfaces are suppose to operate.
**
** The name of this file under configuration management is "sqlite.h.in".
** The makefile makes some minor changes to this file (such as inserting
** the version number) and changes its name to "sqlite3.h" as
** part of the build process.
**
** @(#) $Id: sqlite.h.in,v 1.314 2008/05/20 15:44:31 drh Exp $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
#include <stdarg.h>     /* Needed for the definition of va_list */

/*
** Make sure we can call this stuff from C++.
266
267
268
269
270
271
272










273
274
275
276
277
278
279
280
281
282
283
284
285
286
287

288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
** sqlite3_exec().  The statements are evaluated one by one
** until either an error or an interrupt is encountered or
** until they are all done.  The 3rd parameter is an optional
** callback that is invoked once for each row of any query results
** produced by the SQL statements.  The 5th parameter tells where
** to write any error messages.
**










** 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
** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
** The sqlite3_exec() is just a convenient wrapper.
**
** INVARIANTS:
** 
** {F12101} A successful invocation of [sqlite3_exec(D,S,C,A,E)]
**          shall evaluate all of the UTF-8 encoded, semicolon-separated,
**          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.

**
** {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.
**
** {F12107} If one or more of the SQL statements handed to [sqlite3_exec()]
**          return results and the 3rd parameter is not NULL, then
**          the callback function specified by the 3rd parameter shall be
**          invoked once for each row of result.
**
** {F12110} If the callback returns a non-zero value then [sqlite3_exec()]
**          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
**          as the 1st parameter of the callback.
**
** {F12116} The [sqlite3_exec()] routine sets the 2nd parameter of its
**          callback to be the number of columns in the current row of
**          result.
**
** {F12119} The [sqlite3_exec()] routine sets the 3rd parameter of its 
**          callback to be an array of pointers to strings holding the
**          values for each column in the current result set row as
**          obtained from [sqlite3_column_text()].
**
** {F12122} The [sqlite3_exec()] routine sets the 4th parameter of its
**          callback to be an array of pointers to strings holding the
**          names of result columns as obtained from [sqlite3_column_name()].
**
** {F12125} If the 3rd parameter to [sqlite3_exec()] is NULL then
**          [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
**          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.
**
** {F12137} The [sqlite3_exec()] function sets 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
**          semicolons, then results of [sqlite3_errcode()],
**          [sqlite3_errmsg()], and [sqlite3_errmsg16()]
**          shall reset to indicate no errors.
**
** LIMITATIONS:
**
** {U12141} The first parameter to [sqlite3_exec()] must be an valid and open
**          [database connection].
**
** {U12142} The database connection must not be closed while
**          [sqlite3_exec()] is running.
** 
** {U12143} The calling function is should use [sqlite3_free()] to free
**          the memory that *errmsg is left pointing at once the error
**          message is no longer needed.
**
** {U12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()]
**          must remain unchanged while [sqlite3_exec()] is running.
*/
int sqlite3_exec(







>
>
>
>
>
>
>
>
>
>


|

<








|
|
>





|










<
<
<
<
|



















<
<
<
<


|
|


|
|

|
|
|

|
|












|







266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286

287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313




314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333




334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
** sqlite3_exec().  The statements are evaluated one by one
** until either an error or an interrupt is encountered or
** until they are all done.  The 3rd parameter is an optional
** callback that is invoked once for each row of any query results
** 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 to the database that cannot be done
** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].

**
** INVARIANTS:
** 
** {F12101} A successful invocation of [sqlite3_exec(D,S,C,A,E)]
**          shall evaluate all of the UTF-8 encoded, semicolon-separated,
**          SQL statements in the zero-terminated string S within the
**          context of the D [database connection].
**
** {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.
**
** {F12107} If one or more of the SQL statements handed to [sqlite3_exec()]
**          return results and the 3rd parameter is not NULL, then
**          the callback function specified by the 3rd parameter shall be
**          invoked once for each row of result.
**
** {F12110} If the callback returns a non-zero value then [sqlite3_exec()]
**          shall aborted the SQL statement it is currently evaluating,
**          skip all subsequent SQL statements, and return [SQLITE_ABORT].
**




** {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
**          callback to be the number of columns in the current row of
**          result.
**
** {F12119} The [sqlite3_exec()] routine sets the 3rd parameter of its 
**          callback to be an array of pointers to strings holding the
**          values for each column in the current result set row as
**          obtained from [sqlite3_column_text()].
**
** {F12122} The [sqlite3_exec()] routine sets the 4th parameter of its
**          callback to be an array of pointers to strings holding the
**          names of result columns as obtained from [sqlite3_column_name()].
**
** {F12125} If the 3rd parameter to [sqlite3_exec()] is NULL then
**          [sqlite3_exec()] never invokes a callback.  All query
**          results are silently discarded.
**




** {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 [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 shall set the value of
**          *E to NULL if E is not NULL and there are no errors.
**
** {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 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.
**
** LIMITATIONS:
**
** {U12141} The first parameter to [sqlite3_exec()] must be an valid and open
**          [database connection].
**
** {U12142} The database connection must not be closed while
**          [sqlite3_exec()] is running.
** 
** {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.
**
** {U12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()]
**          must remain unchanged while [sqlite3_exec()] is running.
*/
int sqlite3_exec(