/ Check-in [1c2656fd]
Login

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

Overview
Comment:Update comments in sqlite3.h. No changes to code. (CVS 3734)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 1c2656fdf6176a7365db4e11f4bbf47721da72b4
User & Date: drh 2007-03-28 13:07:41
Context
2007-03-28
14:30
Correctly handle NULLs in IN operators. Ticket #2273. The changes in where.c and in the WhereLevel.aInLoop structure are not strictly necessary to fix this problem - they just make the code easier to read. Only the change in OP_Next/OP_Prev operator of vdbe.c is required. (CVS 3735) check-in: 26348556 user: drh tags: trunk
13:07
Update comments in sqlite3.h. No changes to code. (CVS 3734) check-in: 1c2656fd user: drh tags: trunk
01:59
Fix an memory allocation error revealed by malloc3.test. (CVS 3733) check-in: 0f7fdb02 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.199 2007/03/27 16:19:52 danielk1977 Exp $
           15  +** @(#) $Id: sqlite.h.in,v 1.200 2007/03/28 13:07:41 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++.
................................................................................
   236    236   ** Enable or disable the extended result codes.
   237    237   */
   238    238   int sqlite3_extended_result_codes(sqlite3*, int onoff);
   239    239   
   240    240   /*
   241    241   ** Each entry in an SQLite table has a unique integer key.  (The key is
   242    242   ** the value of the INTEGER PRIMARY KEY column if there is such a column,
   243         -** otherwise the key is generated at random.  The unique key is always
          243  +** otherwise the key is generated automatically.  The unique key is always
   244    244   ** available as the ROWID, OID, or _ROWID_ column.)  The following routine
   245    245   ** returns the integer key of the most recent insert in the database.
   246         -**
   247         -** This function is similar to the mysql_insert_id() function from MySQL.
   248    246   */
   249    247   sqlite_int64 sqlite3_last_insert_rowid(sqlite3*);
   250    248   
   251    249   /*
   252    250   ** This function returns the number of database rows that were changed
   253         -** (or inserted or deleted) by the most recent called sqlite3_exec().
          251  +** (or inserted or deleted) by the most recent SQL statement.  Only
          252  +** changes that are directly specified by the INSERT, UPDATE, or
          253  +** DELETE statement are counted.  Auxiliary changes caused by
          254  +** triggers are not counted.   Within the body of a trigger, however,
          255  +** the sqlite3_changes() API can be called to find the number of
          256  +** changes in the most recently completed INSERT, UPDATE, or DELETE
          257  +** statement within the body of the trigger.
   254    258   **
   255    259   ** All changes are counted, even if they were later undone by a
   256    260   ** ROLLBACK or ABORT.  Except, changes associated with creating and
   257    261   ** dropping tables are not counted.
   258    262   **
   259         -** If a callback invokes sqlite3_exec() recursively, then the changes
   260         -** in the inner, recursive call are counted together with the changes
   261         -** in the outer call.
          263  +** If a callback invokes sqlite3_exec() or sqlite3_step() recursively,
          264  +** then the changes in the inner, recursive call are counted together
          265  +** with the changes in the outer call.
   262    266   **
   263    267   ** SQLite implements the command "DELETE FROM table" without a WHERE clause
   264    268   ** by dropping and recreating the table.  (This is much faster than going
   265    269   ** through and deleting individual elements form the table.)  Because of
   266    270   ** this optimization, the change count for "DELETE FROM table" will be
   267    271   ** zero regardless of the number of elements that were originally in the
   268    272   ** table. To get an accurate count of the number of rows deleted, use
................................................................................
   289    293   int sqlite3_total_changes(sqlite3*);
   290    294   
   291    295   /* This function causes any pending database operation to abort and
   292    296   ** return at its earliest opportunity.  This routine is typically
   293    297   ** called in response to a user action such as pressing "Cancel"
   294    298   ** or Ctrl-C where the user wants a long query operation to halt
   295    299   ** immediately.
          300  +**
          301  +** It is safe to call this routine from a different thread that the
          302  +** thread that is currently running the database operation. 
   296    303   */
   297    304   void sqlite3_interrupt(sqlite3*);
   298    305   
   299    306   
   300    307   /* These functions return true if the given input string comprises
   301    308   ** one or more complete SQL statements. For the sqlite3_complete() call,
   302    309   ** the parameter must be a nul-terminated UTF-8 string. For
   303    310   ** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string
   304    311   ** is required.
   305    312   **
   306         -** The algorithm is simple.  If the last token other than spaces
   307         -** and comments is a semicolon, then return true.  otherwise return
   308         -** false.
          313  +** This routine is useful for command-line input to see of the user has
          314  +** entered a complete statement of SQL or if the current statement needs
          315  +** to be continued on the next line.  The algorithm is simple.  If the 
          316  +** last token other than spaces and comments is a semicolon, then return 
          317  +** true.  Actually, the algorithm is a little more complicated than that
          318  +** in order to deal with triggers, but the basic idea is the same:  the
          319  +** statement is not complete unless it ends in a semicolon.
   309    320   */
   310    321   int sqlite3_complete(const char *sql);
   311    322   int sqlite3_complete16(const void *sql);
   312    323   
   313    324   /*
   314    325   ** This routine identifies a callback function that is invoked
   315    326   ** whenever an attempt is made to open a database table that is
................................................................................
   740    751   ** with the implementations of user-defined functions.
   741    752   */
   742    753   typedef struct sqlite3_context sqlite3_context;
   743    754   typedef struct Mem sqlite3_value;
   744    755   
   745    756   /*
   746    757   ** In the SQL strings input to sqlite3_prepare() and sqlite3_prepare16(),
   747         -** one or more literals can be replace by parameters "?" or ":AAA" or
   748         -** "$VVV" where AAA is an identifer and VVV is a variable name according
   749         -** to the syntax rules of the TCL programming language.
   750         -** The value of these parameters (also called "host parameter names") can
   751         -** be set using the routines listed below.
          758  +** one or more literals can be replace by parameters "?" or "?NNN" or 
          759  +** ":AAA" or "@AAA" or "$VVV" where NNN is a integer, AAA is an identifer,
          760  +** and VVV is a variable name according  to the syntax rules of the
          761  +** TCL programming language.  The value of these parameters (also called
          762  +** "host parameter names") can be set using the routines listed below.
   752    763   **
   753         -** In every case, the first parameter is a pointer to the sqlite3_stmt
   754         -** structure returned from sqlite3_prepare().  The second parameter is the
   755         -** index of the parameter.  The first parameter as an index of 1.  For
   756         -** named parameters (":AAA" or "$VVV") you can use 
          764  +** In every case, the first argument is a pointer to the sqlite3_stmt
          765  +** structure returned from sqlite3_prepare().  The second argument is the
          766  +** index of the host parameter name.  The first host parameter as an index 
          767  +** of 1.  For named host parameters (":AAA" or "$VVV") you can use 
   757    768   ** sqlite3_bind_parameter_index() to get the correct index value given
   758         -** the parameters name.  If the same named parameter occurs more than
          769  +** the parameter name.  If the same named parameter occurs more than
   759    770   ** once, it is assigned the same index each time.
   760    771   **
   761         -** The fifth parameter to sqlite3_bind_blob(), sqlite3_bind_text(), and
          772  +** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
   762    773   ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
   763    774   ** text after SQLite has finished with it.  If the fifth argument is the
   764    775   ** special value SQLITE_STATIC, then the library assumes that the information
   765    776   ** is in static, unmanaged space and does not need to be freed.  If the
   766    777   ** fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its
   767         -** own private copy of the data.
          778  +** own private copy of the data before the sqlite3_bind_* routine returns.
   768    779   **
   769         -** The sqlite3_bind_* routine must be called before sqlite3_step() after
   770         -** an sqlite3_prepare() or sqlite3_reset().  Unbound parameterss are
   771         -** interpreted as NULL.
          780  +** The sqlite3_bind_* routine must be called before sqlite3_step() and after
          781  +** an sqlite3_prepare() or sqlite3_reset().  Bindings persist across
          782  +** multiple calls to sqlite3_reset() and sqlite3_step().  Unbound parameters 
          783  +** are interpreted as NULL.
   772    784   */
   773    785   int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
   774    786   int sqlite3_bind_double(sqlite3_stmt*, int, double);
   775    787   int sqlite3_bind_int(sqlite3_stmt*, int, int);
   776    788   int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite_int64);
   777    789   int sqlite3_bind_null(sqlite3_stmt*, int);
   778    790   int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
   779    791   int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
   780    792   int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
   781    793   
   782    794   /*
   783         -** Return the number of parameters in a compiled SQL statement.  This
          795  +** Return the number of host parameters in a compiled SQL statement.  This
   784    796   ** routine was added to support DBD::SQLite.
   785    797   */
   786    798   int sqlite3_bind_parameter_count(sqlite3_stmt*);
   787    799   
   788    800   /*
   789         -** Return the name of the i-th parameter.  Ordinary parameters "?" are
          801  +** Return the name of the i-th name parameter.  Ordinary parameters "?" are
   790    802   ** nameless and a NULL is returned.  For parameters of the form :AAA or
   791    803   ** $VVV the complete text of the parameter name is returned, including
   792    804   ** the initial ":" or "$".  NULL is returned if the index is out of range.
   793    805   */
   794    806   const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
   795    807   
   796    808   /*
................................................................................
   818    830   ** second function parameter.  The string returned is UTF-8 for
   819    831   ** sqlite3_column_name() and UTF-16 for sqlite3_column_name16().
   820    832   */
   821    833   const char *sqlite3_column_name(sqlite3_stmt*,int);
   822    834   const void *sqlite3_column_name16(sqlite3_stmt*,int);
   823    835   
   824    836   /*
   825         -** The first parameter to the following calls is a compiled SQL statement.
          837  +** The first argument to the following calls is a compiled SQL statement.
   826    838   ** These functions return information about the Nth column returned by 
   827    839   ** the statement, where N is the second function argument.
   828    840   **
   829    841   ** If the Nth column returned by the statement is not a column value,
   830    842   ** then all of the functions return NULL. Otherwise, the return the 
   831    843   ** name of the attached database, table and column that the expression
   832    844   ** extracts a value from.