/ Check-in [21d44fa5]
Login

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

Overview
Comment:Documentation updates (ticket #1279). Add the sqlite3_db_handle API. (ticket #1275). (CVS 2507)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 21d44fa5e7163dc658f7147885518d90218347f7
User & Date: drh 2005-06-12 22:01:43
Context
2005-06-12
22:12
Fix documentation typos. (CVS 2508) check-in: 41049062 user: drh tags: trunk
22:01
Documentation updates (ticket #1279). Add the sqlite3_db_handle API. (ticket #1275). (CVS 2507) check-in: 21d44fa5 user: drh tags: trunk
21:35
Update older opcode names to be more meaningful in light of the latest code design. (CVS 2506) check-in: 36f2da1f user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

     8      8   **    May you find forgiveness for yourself and forgive others.
     9      9   **    May you share freely, never taking more than you give.
    10     10   **
    11     11   *************************************************************************
    12     12   ** This header file defines the interface that the SQLite library
    13     13   ** presents to client programs.
    14     14   **
    15         -** @(#) $Id: sqlite.h.in,v 1.134 2005/05/26 16:23:34 drh Exp $
           15  +** @(#) $Id: sqlite.h.in,v 1.135 2005/06/12 22:01:43 drh Exp $
    16     16   */
    17     17   #ifndef _SQLITE3_H_
    18     18   #define _SQLITE3_H_
    19     19   #include <stdarg.h>     /* Needed for the definition of va_list */
    20     20   
    21     21   /*
    22     22   ** Make sure we can call this stuff from C++.
................................................................................
   684    684   ** must match exactly.  If no parameter with the given name is found,
   685    685   ** return 0.
   686    686   */
   687    687   int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
   688    688   
   689    689   /*
   690    690   ** Set all the parameters in the compiled SQL statement to NULL.
   691         -**
   692         -******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
   693    691   */
   694    692   int sqlite3_clear_bindings(sqlite3_stmt*);
   695    693   
   696    694   /*
   697    695   ** Return the number of columns in the result set returned by the compiled
   698    696   ** SQL statement. This routine returns 0 if pStmt is an SQL statement
   699    697   ** that does not return data (for example an UPDATE).
................................................................................
  1187   1185   ** Sleep for a little while. The second parameter is the number of
  1188   1186   ** miliseconds to sleep for. 
  1189   1187   **
  1190   1188   ** If the operating system does not support sleep requests with 
  1191   1189   ** milisecond time resolution, then the time will be rounded up to 
  1192   1190   ** the nearest second. The number of miliseconds of sleep actually 
  1193   1191   ** requested from the operating system is returned.
  1194         -**
  1195         -******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
  1196   1192   */
  1197   1193   int sqlite3_sleep(int);
  1198   1194   
  1199   1195   /*
  1200   1196   ** Return TRUE (non-zero) of the statement supplied as an argument needs
  1201   1197   ** to be recompiled.  A statement needs to be recompiled whenever the
  1202   1198   ** execution environment changes in a way that would alter the program
  1203   1199   ** that sqlite3_prepare() generates.  For example, if new functions or
  1204   1200   ** collating sequences are registered or if an authorizer function is
  1205   1201   ** added or changed.
  1206   1202   **
  1207         -******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
  1208   1203   */
  1209   1204   int sqlite3_expired(sqlite3_stmt*);
  1210   1205   
  1211   1206   /*
  1212   1207   ** Move all bindings from the first prepared statement over to the second.
  1213   1208   ** This routine is useful, for example, if the first prepared statement
  1214   1209   ** fails with an SQLITE_SCHEMA error.  The same SQL can be prepared into
  1215   1210   ** the second prepared statement then all of the bindings transfered over
  1216   1211   ** to the second statement before the first statement is finalized.
  1217         -**
  1218         -******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
  1219   1212   */
  1220   1213   int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
  1221   1214   
  1222   1215   /*
  1223   1216   ** If the following global variable is made to point to a
  1224   1217   ** string which is the name of a directory, then all temporary files
  1225   1218   ** created by SQLite will be placed in that directory.  If this variable
................................................................................
  1253   1246   int sqlite3_global_recover();
  1254   1247   
  1255   1248   /*
  1256   1249   ** Test to see whether or not the database connection is in autocommit
  1257   1250   ** mode.  Return TRUE if it is and FALSE if not.  Autocommit mode is on
  1258   1251   ** by default.  Autocommit is disabled by a BEGIN statement and reenabled
  1259   1252   ** by the next COMMIT or ROLLBACK.
  1260         -**
  1261         -******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
  1262   1253   */
  1263   1254   int sqlite3_get_autocommit(sqlite3*);
  1264   1255   
  1265         -
         1256  +/*
         1257  +** Return the sqlite3* database handle to which the prepared statement given
         1258  +** in the argument belongs.  This is the same database handle that was
         1259  +** the first argument to the sqlite3_prepare() that was used to create
         1260  +** the statement in the first place.
         1261  +*/
         1262  +sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
  1266   1263   
  1267   1264   #ifdef __cplusplus
  1268   1265   }  /* End of the 'extern "C"' block */
  1269   1266   #endif
  1270   1267   #endif

Changes to src/test1.c.

     9      9   **    May you share freely, never taking more than you give.
    10     10   **
    11     11   *************************************************************************
    12     12   ** Code for testing the printf() interface to SQLite.  This code
    13     13   ** is not included in the SQLite library.  It is used for automated
    14     14   ** testing of the SQLite library.
    15     15   **
    16         -** $Id: test1.c,v 1.143 2005/06/07 07:58:49 danielk1977 Exp $
           16  +** $Id: test1.c,v 1.144 2005/06/12 22:01:43 drh Exp $
    17     17   */
    18     18   #include "sqliteInt.h"
    19     19   #include "tcl.h"
    20     20   #include "os.h"
    21     21   #include <stdlib.h>
    22     22   #include <string.h>
    23     23   
................................................................................
    59     59   }
    60     60   #define errorName sqlite3TestErrorName
    61     61   
    62     62   /*
    63     63   ** Convert an sqlite3_stmt* into an sqlite3*.  This depends on the
    64     64   ** fact that the sqlite3* is the first field in the Vdbe structure.
    65     65   */
    66         -#define StmtToDb(X)   ((X)?*(sqlite3**)(X):0)
           66  +#define StmtToDb(X)   sqlite3_db_handle(X)
    67     67   
    68     68   /*
    69     69   ** Check a return value to make sure it agrees with the results
    70     70   ** from sqlite3_errcode.
    71     71   */
    72     72   int sqlite3TestErrCode(Tcl_Interp *interp, sqlite3 *db, int rc){
    73     73     if( rc!=SQLITE_MISUSE && rc!=SQLITE_OK && sqlite3_errcode(db)!=rc ){

Changes to src/vdbeapi.c.

    19     19   /*
    20     20   ** Return TRUE (non-zero) of the statement supplied as an argument needs
    21     21   ** to be recompiled.  A statement needs to be recompiled whenever the
    22     22   ** execution environment changes in a way that would alter the program
    23     23   ** that sqlite3_prepare() generates.  For example, if new functions or
    24     24   ** collating sequences are registered or if an authorizer function is
    25     25   ** added or changed.
    26         -**
    27         -***** EXPERIMENTAL ******
    28     26   */
    29     27   int sqlite3_expired(sqlite3_stmt *pStmt){
    30     28     Vdbe *p = (Vdbe*)pStmt;
    31     29     return p==0 || p->expired;
    32     30   }
    33     31   
    34     32   /**************************** sqlite3_value_  *******************************
................................................................................
   666    664           return i+1;
   667    665         }
   668    666       }
   669    667     }
   670    668     return 0;
   671    669   }
   672    670   
   673         -/* EXPERIMENTAL
   674         -** 
          671  +/*
   675    672   ** Transfer all bindings from the first statement over to the second.
   676    673   ** If the two statements contain a different number of bindings, then
   677    674   ** an SQLITE_ERROR is returned.
   678    675   */
   679    676   int sqlite3_transfer_bindings(sqlite3_stmt *pFromStmt, sqlite3_stmt *pToStmt){
   680    677     Vdbe *pFrom = (Vdbe*)pFromStmt;
   681    678     Vdbe *pTo = (Vdbe*)pToStmt;
................................................................................
   688    685       return SQLITE_ERROR;
   689    686     }
   690    687     for(i=0; rc==SQLITE_OK && i<pFrom->nVar; i++){
   691    688       rc = sqlite3VdbeMemMove(&pTo->aVar[i], &pFrom->aVar[i]);
   692    689     }
   693    690     return rc;
   694    691   }
          692  +
          693  +/*
          694  +** Return the sqlite3* database handle to which the prepared statement given
          695  +** in the argument belongs.  This is the same database handle that was
          696  +** the first argument to the sqlite3_prepare() that was used to create
          697  +** the statement in the first place.
          698  +*/
          699  +sqlite3 *sqlite3_db_handle(sqlite3_stmt *pStmt){
          700  +  return pStmt ? ((Vdbe*)pStmt)->db : 0;
          701  +}

Changes to www/capi3ref.tcl.

     1         -set rcsid {$Id: capi3ref.tcl,v 1.20 2005/03/14 02:01:50 drh Exp $}
            1  +set rcsid {$Id: capi3ref.tcl,v 1.21 2005/06/12 22:01:43 drh Exp $}
     2      2   source common.tcl
     3      3   header {C/C++ Interface For SQLite Version 3}
     4      4   puts {
     5      5   <h2>C/C++ Interface For SQLite Version 3</h2>
     6      6   }
     7      7   
     8      8   proc api {name prototype desc {notused x}} {
................................................................................
    99     99    to the sqlite3_stmt structure returned from sqlite3_prepare().  The second
   100    100    argument is the index of the parameter to be set.  The first parameter has
   101    101    an index of 1. When the same named parameter is used more than once, second
   102    102    and subsequent
   103    103    occurrences have the same index as the first occurrence.  The index for
   104    104    named parameters can be looked up using the
   105    105    sqlite3_bind_parameter_name() API if desired.
          106  +
          107  + The third argument is the value to bind to the parameter.
          108  +
          109  + In those
          110  + routines that have a fourth argument, its value is the number of bytes
          111  + in the parameter.  This is the number of characters for UTF-8 strings
          112  + and the number of bytes for UTF-16 strings and blobs.  The number
          113  + of bytes does not include the zero-terminator at the end of strings.
          114  + If the fourth parameter is negative, the length of the string is
          115  + computed using strlen().
   106    116   
   107    117    The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
   108    118    sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
   109    119    text after SQLite has finished with it.  If the fifth argument is the
   110    120    special value SQLITE_STATIC, then the library assumes that the information
   111    121    is in static, unmanaged space and does not need to be freed.  If the
   112    122    fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its
................................................................................
  1081   1091    sqlite3_column_... routines except that these routines take a single
  1082   1092    sqlite3_value* pointer instead of an sqlite3_stmt* and an integer
  1083   1093    column number.
  1084   1094   
  1085   1095    See the documentation under sqlite3_column_blob for additional
  1086   1096    information.
  1087   1097   }
         1098  +
         1099  +api {} {
         1100  +  int sqlite3_sleep(int);
         1101  +} {
         1102  + Sleep for a little while. The second parameter is the number of
         1103  + miliseconds to sleep for. 
         1104  +
         1105  + If the operating system does not support sleep requests with 
         1106  + milisecond time resolution, then the time will be rounded up to 
         1107  + the nearest second. The number of miliseconds of sleep actually 
         1108  + requested from the operating system is returned.
         1109  +}
         1110  +
         1111  +api {} {
         1112  +  int sqlite3_expired(sqlite3_stmt*);
         1113  +} {
         1114  + Return TRUE (non-zero) of the statement supplied as an argument needs
         1115  + to be recompiled.  A statement needs to be recompiled whenever the
         1116  + execution environment changes in a way that would alter the program
         1117  + that sqlite3_prepare() generates.  For example, if new functions or
         1118  + collating sequences are registered or if an authorizer function is
         1119  + added or changed.
         1120  +}
         1121  +
         1122  +api {} {
         1123  +  int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
         1124  +} {
         1125  + Move all bindings from the first prepared statement over to the second.
         1126  + This routine is useful, for example, if the first prepared statement
         1127  + fails with an SQLITE_SCHEMA error.  The same SQL can be prepared into
         1128  + the second prepared statement then all of the bindings transfered over
         1129  + to the second statement before the first statement is finalized.
         1130  +}
         1131  +
         1132  +api {} {
         1133  +  int sqlite3_global_recover();
         1134  +} {
         1135  + This function is called to recover from a malloc() failure that occured
         1136  + within the SQLite library. Normally, after a single malloc() fails the 
         1137  + library refuses to function (all major calls return SQLITE_NOMEM).
         1138  + This function restores the library state so that it can be used again.
         1139  +
         1140  + All existing statements (sqlite3_stmt pointers) must be finalized or
         1141  + reset before this call is made. Otherwise, SQLITE_BUSY is returned.
         1142  + If any in-memory databases are in use, either as a main or TEMP
         1143  + database, SQLITE_ERROR is returned. In either of these cases, the 
         1144  + library is not reset and remains unusable.
         1145  +
         1146  + This function is *not* threadsafe. Calling this from within a threaded
         1147  + application when threads other than the caller have used SQLite is
         1148  + dangerous and will almost certainly result in malfunctions.
         1149  +
         1150  + This functionality can be omitted from a build by defining the 
         1151  + SQLITE_OMIT_GLOBALRECOVER at compile time.
         1152  +}
         1153  +
         1154  +api {} {
         1155  +  int sqlite3_get_autocommit(sqlite3*);
         1156  +} {
         1157  + Test to see whether or not the database connection is in autocommit
         1158  + mode.  Return TRUE if it is and FALSE if not.  Autocommit mode is on
         1159  + by default.  Autocommit is disabled by a BEGIN statement and reenabled
         1160  + by the next COMMIT or ROLLBACK.
         1161  +}
         1162  +
         1163  +api {} {
         1164  +  int sqlite3_clear_bindings(sqlite3_stmt*);
         1165  +} {
         1166  + Set all the parameters in the compiled SQL statement back to NULL.
         1167  +}
         1168  +
         1169  +api {} {
         1170  +  int sqlite3_db_handle(sqlite3_stmt*);
         1171  +} {
         1172  + Return the sqlite3* database handle to which the prepared statement given
         1173  + in the argument belongs.  This is the same database handle that was
         1174  + the first argument to the sqlite3_prepare() that was used to create
         1175  + the statement in the first place.
         1176  +}
         1177  +
  1088   1178   
  1089   1179   set n 0
  1090   1180   set i 0
  1091   1181   foreach item $apilist {
  1092   1182     set namelist [lindex $item 0]
  1093   1183     foreach name $namelist {
  1094   1184       set n_to_name($n) $name