Documentation updates (ticket #1279). Add the sqlite3_db_handle API.

(ticket #1275). (CVS 2507)

FossilOrigin-Name: 21d44fa5e7163dc658f7147885518d90218347f7

manifest

@@ -1,5 +1,5 @@
-C Update\solder\sopcode\snames\sto\sbe\smore\smeaningful\sin\slight\sof\sthe\slatest\ncode\sdesign.\s(CVS\s2506)
+C Documentation\supdates\s(ticket\s#1279).\s\sAdd\sthe\ssqlite3_db_handle\sAPI.\n(ticket\s#1275).\s(CVS\s2507)
-D 2005-06-12T21:35:52
+D 2005-06-12T22:01:43
 F Makefile.in 8129e7f261d405db783676f9ca31e0841768c652
 F Makefile.linux-gcc 06be33b2a9ad4f005a5f42b22c4a19dab3cbb5c7
 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028
@@ -62,11 +62,11 @@ F src/printf.c 3d20b21cfecadacecac3fb7274e746cb81d3d357
 F src/random.c 90adff4e73a3b249eb4f1fc2a6ff9cf78c7233a4
 F src/select.c 28b752e58955c7920711fbdbfdcd369a2bd09448
 F src/shell.c 25b3217d7c64e6497225439d261a253a23efff26
-F src/sqlite.h.in f28f5b018f03a66aaf0bc1ab6985d8605d6b964f
+F src/sqlite.h.in 99d615b1e8635ceb45e6fb0551bcb6c71180c238
 F src/sqliteInt.h c620e07e0c7e6e09d8623d165427f0f1f659aad5
 F src/table.c 25b3ff2b39b7d87e8d4a5da0713d68dfc06cbee9
 F src/tclsqlite.c af0f002d9d6ab4f7f32b9bee5b57665946e76ad9
-F src/test1.c 1ab9e62dd51a999ea1842f0bc8ae677d5ca04861
+F src/test1.c 5956d1c61b89d84c2b2ab01f065b1cd878917213
 F src/test2.c 716c1809dba8e5be6093703e9cada99d627542dc
 F src/test3.c 683e1e3819152ffd35da2f201e507228921148d0
 F src/test4.c 7c6b9fc33dd1f3f93c7f1ee6e5e6d016afa6c1df
@@ -80,7 +80,7 @@ F src/vacuum.c 829d9e1a6d7c094b80e0899686670932eafd768c
 F src/vdbe.c c2511f392598928254504e3b2c5ec47f4fef2b53
 F src/vdbe.h 75e466d84d362b0c4498978a9d6b1e6bd32ecf3b
 F src/vdbeInt.h 4312faf41630a6c215924b6c7c2f39ebb1af8ffb
-F src/vdbeapi.c 9a9556b9d7e3a052f58de389caf69449558e7380
+F src/vdbeapi.c 3f858d2236df0d127249a6a166e0e25b5de650ed
 F src/vdbeaux.c c99e32abeba4b7522e3922afff2c32ff4bd17eb5
 F src/vdbemem.c 48a64ae95a9edc6e8d940300dad15d70d1670398
 F src/where.c 3a9a2258ab3364655e9ea215ad5ae7bf41813f54
@@ -246,7 +246,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 59c7da9ef1f24dcb10b247cd3b7452cf76ab36f0
+F www/capi3ref.tcl e3308069810d9078887eaac63751fd8267feac97
 F www/changes.tcl 87c94ac17dd5d671db7b849205f71f50e881013a
 F www/common.tcl de758130d54d95d151ea0d17a2ae5b92e1bb01de
 F www/compile.tcl 276546d7eb445add5a867193bbd80f6919a6b084
@@ -281,7 +281,7 @@ F www/tclsqlite.tcl 425be741b8ae664f55cb1ef2371aab0a75109cf9
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl a99cf5f6d8bd4d5537584a2b342f0fb9fa601d8b
 F www/whentouse.tcl 528299b8316726dbcc5548e9aa0648c8b1bd055b
-P 97b348a5ad2f090ba7a75467b97c6dfb575df09c
+P 36f2da1f8d8d434f861ecad55c9d86549751c954
-R 8569c8c1f2245087cc1ec4a7869dfa68
+R 88f39d183a36e18d13d5fd06f6aee694
 U drh
-Z 08316380432fe4e2f32db98927281007
+Z 952b31c2115abe98683d1e27e0717e7e

manifest.uuid

@@ -1 +1 @@
-36f2da1f8d8d434f861ecad55c9d86549751c954
+21d44fa5e7163dc658f7147885518d90218347f7

src/sqlite.h.in

@@ -12,7 +12,7 @@
 ** This header file defines the interface that the SQLite library
 ** presents to client programs.
 **
-** @(#) $Id: sqlite.h.in,v 1.134 2005/05/26 16:23:34 drh Exp $
+** @(#) $Id: sqlite.h.in,v 1.135 2005/06/12 22:01:43 drh Exp $
 */
 #ifndef _SQLITE3_H_
 #define _SQLITE3_H_
@@ -688,8 +688,6 @@ int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
 
 /*
 ** Set all the parameters in the compiled SQL statement to NULL.
-**
-******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
 */
 int sqlite3_clear_bindings(sqlite3_stmt*);
 
@@ -1191,8 +1189,6 @@ int sqlite3_rekey(
 ** milisecond time resolution, then the time will be rounded up to 
 ** the nearest second. The number of miliseconds of sleep actually 
 ** requested from the operating system is returned.
-**
-******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
 */
 int sqlite3_sleep(int);
 
@@ -1204,7 +1200,6 @@ int sqlite3_sleep(int);
 ** collating sequences are registered or if an authorizer function is
 ** added or changed.
 **
-******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
 */
 int sqlite3_expired(sqlite3_stmt*);
 
@@ -1214,8 +1209,6 @@ int sqlite3_expired(sqlite3_stmt*);
 ** fails with an SQLITE_SCHEMA error.  The same SQL can be prepared into
 ** the second prepared statement then all of the bindings transfered over
 ** to the second statement before the first statement is finalized.
-**
-******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
 */
 int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
 
@@ -1257,12 +1250,16 @@ int sqlite3_global_recover();
 ** mode.  Return TRUE if it is and FALSE if not.  Autocommit mode is on
 ** by default.  Autocommit is disabled by a BEGIN statement and reenabled
 ** by the next COMMIT or ROLLBACK.
-**
-******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
 */
 int sqlite3_get_autocommit(sqlite3*);
 
-
+/*
+** Return the sqlite3* database handle to which the prepared statement given
+** in the argument belongs.  This is the same database handle that was
+** the first argument to the sqlite3_prepare() that was used to create
+** the statement in the first place.
+*/
+sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
 
 #ifdef __cplusplus
 }  /* End of the 'extern "C"' block */

src/test1.c

@@ -13,7 +13,7 @@
 ** is not included in the SQLite library.  It is used for automated
 ** testing of the SQLite library.
 **
-** $Id: test1.c,v 1.143 2005/06/07 07:58:49 danielk1977 Exp $
+** $Id: test1.c,v 1.144 2005/06/12 22:01:43 drh Exp $
 */
 #include "sqliteInt.h"
 #include "tcl.h"
@@ -63,7 +63,7 @@ const char *sqlite3TestErrorName(int rc){
 ** Convert an sqlite3_stmt* into an sqlite3*.  This depends on the
 ** fact that the sqlite3* is the first field in the Vdbe structure.
 */
-#define StmtToDb(X)   ((X)?*(sqlite3**)(X):0)
+#define StmtToDb(X)   sqlite3_db_handle(X)
 
 /*
 ** Check a return value to make sure it agrees with the results

src/vdbeapi.c

@@ -23,8 +23,6 @@
 ** that sqlite3_prepare() generates.  For example, if new functions or
 ** collating sequences are registered or if an authorizer function is
 ** added or changed.
-**
-***** EXPERIMENTAL ******
 */
 int sqlite3_expired(sqlite3_stmt *pStmt){
   Vdbe *p = (Vdbe*)pStmt;
@@ -670,8 +668,7 @@ int sqlite3_bind_parameter_index(sqlite3_stmt *pStmt, const char *zName){
   return 0;
 }
 
-/* EXPERIMENTAL
+/*
-** 
 ** Transfer all bindings from the first statement over to the second.
 ** If the two statements contain a different number of bindings, then
 ** an SQLITE_ERROR is returned.
@@ -692,3 +689,13 @@ int sqlite3_transfer_bindings(sqlite3_stmt *pFromStmt, sqlite3_stmt *pToStmt){
   }
   return rc;
 }
+
+/*
+** Return the sqlite3* database handle to which the prepared statement given
+** in the argument belongs.  This is the same database handle that was
+** the first argument to the sqlite3_prepare() that was used to create
+** the statement in the first place.
+*/
+sqlite3 *sqlite3_db_handle(sqlite3_stmt *pStmt){
+  return pStmt ? ((Vdbe*)pStmt)->db : 0;
+}

www/capi3ref.tcl

@@ -1,4 +1,4 @@
-set rcsid {$Id: capi3ref.tcl,v 1.20 2005/03/14 02:01:50 drh Exp $}
+set rcsid {$Id: capi3ref.tcl,v 1.21 2005/06/12 22:01:43 drh Exp $}
 source common.tcl
 header {C/C++ Interface For SQLite Version 3}
 puts {
@@ -104,6 +104,16 @@ api {} {
  named parameters can be looked up using the
  sqlite3_bind_parameter_name() API if desired.
 
+ The third argument is the value to bind to the parameter.
+
+ In those
+ routines that have a fourth argument, its value is the number of bytes
+ in the parameter.  This is the number of characters for UTF-8 strings
+ and the number of bytes for UTF-16 strings and blobs.  The number
+ of bytes does not include the zero-terminator at the end of strings.
+ If the fourth parameter is negative, the length of the string is
+ computed using strlen().
+
  The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
  sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
  text after SQLite has finished with it.  If the fifth argument is the
@@ -1086,6 +1096,86 @@ int sqlite3_value_type(sqlite3_value*);
  information.
 }
 
+api {} {
+  int sqlite3_sleep(int);
+} {
+ Sleep for a little while. The second parameter is the number of
+ miliseconds to sleep for. 
+
+ If the operating system does not support sleep requests with 
+ milisecond time resolution, then the time will be rounded up to 
+ the nearest second. The number of miliseconds of sleep actually 
+ requested from the operating system is returned.
+}
+
+api {} {
+  int sqlite3_expired(sqlite3_stmt*);
+} {
+ Return TRUE (non-zero) of the statement supplied as an argument needs
+ to be recompiled.  A statement needs to be recompiled whenever the
+ execution environment changes in a way that would alter the program
+ that sqlite3_prepare() generates.  For example, if new functions or
+ collating sequences are registered or if an authorizer function is
+ added or changed.
+}
+
+api {} {
+  int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
+} {
+ Move all bindings from the first prepared statement over to the second.
+ This routine is useful, for example, if the first prepared statement
+ fails with an SQLITE_SCHEMA error.  The same SQL can be prepared into
+ the second prepared statement then all of the bindings transfered over
+ to the second statement before the first statement is finalized.
+}
+
+api {} {
+  int sqlite3_global_recover();
+} {
+ This function is called to recover from a malloc() failure that occured
+ within the SQLite library. Normally, after a single malloc() fails the 
+ library refuses to function (all major calls return SQLITE_NOMEM).
+ This function restores the library state so that it can be used again.
+
+ All existing statements (sqlite3_stmt pointers) must be finalized or
+ reset before this call is made. Otherwise, SQLITE_BUSY is returned.
+ If any in-memory databases are in use, either as a main or TEMP
+ database, SQLITE_ERROR is returned. In either of these cases, the 
+ library is not reset and remains unusable.
+
+ This function is *not* threadsafe. Calling this from within a threaded
+ application when threads other than the caller have used SQLite is
+ dangerous and will almost certainly result in malfunctions.
+
+ This functionality can be omitted from a build by defining the 
+ SQLITE_OMIT_GLOBALRECOVER at compile time.
+}
+
+api {} {
+  int sqlite3_get_autocommit(sqlite3*);
+} {
+ Test to see whether or not the database connection is in autocommit
+ mode.  Return TRUE if it is and FALSE if not.  Autocommit mode is on
+ by default.  Autocommit is disabled by a BEGIN statement and reenabled
+ by the next COMMIT or ROLLBACK.
+}
+
+api {} {
+  int sqlite3_clear_bindings(sqlite3_stmt*);
+} {
+ Set all the parameters in the compiled SQL statement back to NULL.
+}
+
+api {} {
+  int sqlite3_db_handle(sqlite3_stmt*);
+} {
+ Return the sqlite3* database handle to which the prepared statement given
+ in the argument belongs.  This is the same database handle that was
+ the first argument to the sqlite3_prepare() that was used to create
+ the statement in the first place.
+}
+
+
 set n 0
 set i 0
 foreach item $apilist {