From: drh Date: Tue, 7 Dec 2004 02:14:51 +0000 (+0000) Subject: Updates to API documentation and comments in sqlite3.h. (CVS 2155) X-Git-Tag: version-3.6.10~3997 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=32c0d4f17b8a6263ae352714b97a0c27670b15ff;p=thirdparty%2Fsqlite.git Updates to API documentation and comments in sqlite3.h. (CVS 2155) FossilOrigin-Name: 46584348f3cc10c0c6e9ba42110a6c03caf1497e --- diff --git a/manifest b/manifest index 79453b5000..331eac8b8e 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Get\sthe\sbuild\sof\ssqlite3_analyzer\sworking\swith\sMakefile.in.\s(CVS\s2154) -D 2004-12-02T20:17:01 +C Updates\sto\sAPI\sdocumentation\sand\scomments\sin\ssqlite3.h.\s(CVS\s2155) +D 2004-12-07T02:14:51 F Makefile.in da09f379b80c8cd78d78abaa0f32ca90a124e884 F Makefile.linux-gcc a9e5a0d309fa7c38e7c14d3ecf7690879d3a5457 F README a01693e454a00cc117967e3f9fdab2d4d52e9bc1 @@ -61,7 +61,7 @@ F src/printf.c 3d20b21cfecadacecac3fb7274e746cb81d3d357 F src/random.c eff68e3f257e05e81eae6c4d50a51eb88beb4ff3 F src/select.c 36cc9da999596578566e167d310e99f2005a7f03 F src/shell.c e8f4f486cbf6e60d81173146ac8a6522c930fa51 -F src/sqlite.h.in f4a0e527c84281aef7aaa5afb027b00159c97f71 +F src/sqlite.h.in fa75850f412808afd38fddc1fd6456f4efc6fb97 F src/sqliteInt.h 1dc643cf84f1d83bd45e314f724bb824ee24c000 F src/table.c 25b3ff2b39b7d87e8d4a5da0713d68dfc06cbee9 F src/tclsqlite.c 68b45ae5a96424abdc1732cb03b1efbb0c1821b3 @@ -229,7 +229,7 @@ F www/audit.tcl 90e09d580f79c7efec0c7d6f447b7ec5c2dce5c0 F www/autoinc.tcl b357f5ba954b046ee35392ce0f884a2fcfcdea06 F www/c_interface.tcl b51b08591554c16a0c3ef718364a508ac25abc7e F www/capi3.tcl 5c1cb163f4d2a54e2d0e22dcc399dd71245c8b89 -F www/capi3ref.tcl 682ed717d564a1234badb8a563837547e140a382 +F www/capi3ref.tcl c5a3ae75fc3505c034f3c4bbb62ab94cf359ac39 F www/changes.tcl f2b34859843d9f06a0611eb6d44af767891b09ef F www/common.tcl de758130d54d95d151ea0d17a2ae5b92e1bb01de F www/compile.tcl d9431a45a7551e833b0361ca5826831205276b05 @@ -262,7 +262,7 @@ F www/tclsqlite.tcl 560ecd6a916b320e59f2917317398f3d59b7cc25 F www/vdbe.tcl 095f106d93875c94b47367384ebc870517431618 F www/version3.tcl 092a01f5ef430d2c4acc0ae558d74c4bb89638a0 F www/whentouse.tcl fdacb0ba2d39831e8a6240d05a490026ad4c4e4c -P d75014c299496a02f6850545beb0ab669802bf87 -R 59ee0077c73ea218abb0e30b9f6d0555 +P f7415a0d6433980ff6c25cf2238f5e9881c38873 +R 3e773cbf7b112fee9ee1223a2128d596 U drh -Z f3bab5fdb442cbf5388edb1fd0d9e34d +Z 5d04f9ad0daf17e058e901e2fe7ea384 diff --git a/manifest.uuid b/manifest.uuid index 61b5fb0a53..ee438f0152 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -f7415a0d6433980ff6c25cf2238f5e9881c38873 \ No newline at end of file +46584348f3cc10c0c6e9ba42110a6c03caf1497e \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index bc17344177..d4633bbd83 100644 --- a/src/sqlite.h.in +++ b/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.124 2004/11/23 15:41:16 danielk1977 Exp $ +** @(#) $Id: sqlite.h.in,v 1.125 2004/12/07 02:14:51 drh Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ @@ -608,14 +608,19 @@ typedef struct Mem sqlite3_value; /* ** In the SQL strings input to sqlite3_prepare() and sqlite3_prepare16(), -** one or more literals can be replace by a wildcard "?" or ":N:" where -** N is an integer. These value of these wildcard literals can be set -** using the routines listed below. +** one or more literals can be replace by parameters "?" or ":AAA" or +** "$VVV" where AAA is an identifer and VVV is a variable name according +** to the syntax rules of the TCL programming language. +** The value of these parameters (also called "host parameter names") can +** be set using the routines listed below. ** ** In every case, the first parameter is a pointer to the sqlite3_stmt ** structure returned from sqlite3_prepare(). The second parameter is the -** index of the wildcard. The first "?" has an index of 1. ":N:" wildcards -** use the index N. +** index of the parameter. The first parameter as an index of 1. For +** named parameters (":AAA" or "$VVV") you can use +** sqlite3_bind_parameter_index() to get the correct index value given +** the parameters name. If the same named parameter occurs more than +** once, it is assigned the same index each time. ** ** The fifth parameter to sqlite3_bind_blob(), sqlite3_bind_text(), and ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or @@ -626,8 +631,8 @@ typedef struct Mem sqlite3_value; ** own private copy of the data. ** ** The sqlite3_bind_* routine must be called before sqlite3_step() after -** an sqlite3_prepare() or sqlite3_reset(). Unbound wildcards are interpreted -** as NULL. +** an sqlite3_prepare() or sqlite3_reset(). Unbound parameterss are +** interpreted as NULL. */ int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); int sqlite3_bind_double(sqlite3_stmt*, int, double); @@ -639,16 +644,16 @@ int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); /* -** Return the number of wildcards in a compiled SQL statement. This +** Return the number of parameters in a compiled SQL statement. This ** routine was added to support DBD::SQLite. */ int sqlite3_bind_parameter_count(sqlite3_stmt*); /* -** Return the name of the i-th parameter. Ordinary wildcards "?" are -** nameless and a NULL is returned. For wildcards of the form :N or -** $vvvv the complete text of the wildcard is returned. -** NULL is returned if the index is out of range. +** Return the name of the i-th parameter. Ordinary parameters "?" are +** nameless and a NULL is returned. For parameters of the form :AAA or +** $VVV the complete text of the parameter name is returned, including +** the initial ":" or "$". NULL is returned if the index is out of range. */ const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); diff --git a/www/capi3ref.tcl b/www/capi3ref.tcl index 42d9ba7c97..fa69b1b322 100644 --- a/www/capi3ref.tcl +++ b/www/capi3ref.tcl @@ -1,4 +1,4 @@ -set rcsid {$Id: capi3ref.tcl,v 1.16 2004/11/20 21:02:14 drh Exp $} +set rcsid {$Id: capi3ref.tcl,v 1.17 2004/12/07 02:14:52 drh Exp $} source common.tcl header {C/C++ Interface For SQLite Version 3} puts { @@ -59,7 +59,7 @@ api {} { api {} { void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); } { - Aggregate functions use the following routine to allocate + Aggregate functions use this routine to allocate a structure for storing their state. The first time this routine is called for a particular aggregate, a new structure of size nBytes is allocated, zeroed, and returned. On subsequent calls (for the @@ -89,44 +89,52 @@ api {} { #define SQLITE_TRANSIENT ((void(*)(void *))-1) } { In the SQL strings input to sqlite3_prepare() and sqlite3_prepare16(), - one or more literals can be replace by a wildcard "?" or ":AAA" where - AAA is an alphanumeric identifier. - The value of these wildcard literals (also called "host parameter names") - can be set using these routines. - - The first parameter is a pointer to the sqlite3_stmt - structure returned from sqlite3_prepare(). The second parameter is the - index of the wildcard. The first wildcard has an index of 1. - - The fifth parameter to sqlite3_bind_blob(), sqlite3_bind_text(), and + one or more literals can be replace by a parameter "?" or ":AAA" or "\$VVV" + where AAA is an alphanumeric identifier and VVV is a variable name according + to the syntax rules of the TCL programming language. + The values of these parameters (also called "host parameter names") + can be set using the sqlite3_bind_*() routines. + + The first argument to the sqlite3_bind_*() routines always is a pointer + to the sqlite3_stmt structure returned from sqlite3_prepare(). The second + argument is the index of the parameter to be set. The first parameter has + an index of 1. When the same named parameter is used more than once, second + and subsequent + occurrences have the same index as the first occurrence. The index for + named parameters can be looked up using the + sqlite3_bind_parameter_name() API if desired. + + 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 special value SQLITE_STATIC, then the library assumes that the information is in static, unmanaged space and does not need to be freed. If the fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its - own private copy of the data. + own private copy of the data before returning. - The sqlite3_bind_*() routine must be called after + The sqlite3_bind_*() routines must be called after sqlite3_prepare() or sqlite3_reset() and before sqlite3_step(). - Bindings are not reset by the sqlite3_reset() routine. - Unbound wildcards are interpreted as NULL. + Bindings are not cleared by the sqlite3_reset() routine. + Unbound parameters are interpreted as NULL. } api {} { int sqlite3_bind_parameter_count(sqlite3_stmt*); } { - Return the number of wildcards in the precompiled statement given as + Return the number of parameters in the precompiled statement given as the argument. } api {} { const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int n); } { - Return the name of the n-th wildcard in the precompiled statement. - Wildcards of the form ":AAA" have a name which is the string ":AAA". - Wildcards of the form "?" or "?NNN" have no name. + Return the name of the n-th parameter in the precompiled statement. + Parameters of the form ":AAA" or "\$VVV" have a name which is the + string ":AAA" or "\$VVV". In other words, the initial ":" or "$" + is included as part of the name. + Parameters of the form "?" have no name. - If the value n is out of range or if the n-th wildcard is nameless, + If the value n is out of range or if the n-th parameter is nameless, then NULL is returned. The returned string is always in the UTF-8 encoding. } @@ -134,9 +142,9 @@ api {} { api {} { int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); } { - Return the index of the wildcard with the given name. + Return the index of the parameter with the given name. The name must match exactly. - If there is no wildcard with the given name, return 0. + If there is no parameter with the given name, return 0. The string zName is always in the UTF-8 encoding. } @@ -195,7 +203,7 @@ api {} { SQLite implements the command "DELETE FROM table" without a WHERE clause by dropping and recreating the table. (This is much faster than going - through and deleting individual elements form the table.) Because of + through and deleting individual elements from the table.) Because of this optimization, the change count for "DELETE FROM table" will be zero regardless of the number of elements that were originally in the table. To get an accurate count of the number of rows deleted, use @@ -254,9 +262,9 @@ int sqlite3_column_type(sqlite3_stmt*, int iCol); #define SQLITE_BLOB 4 #define SQLITE_NULL 5 } { - These routines returns information about the information + These routines return information about the information in a single column of the current result row of a query. In every - case the first parameter is a pointer to the SQL statement that is being + case the first argument is a pointer to the SQL statement that is being executed (the sqlite_stmt* that was returned from sqlite3_prepare()) and the second argument is the index of the column for which information should be returned. iCol is zero-indexed. The left-most column as an @@ -319,7 +327,7 @@ api {} { const char *sqlite3_column_decltype(sqlite3_stmt *, int i); const void *sqlite3_column_decltype16(sqlite3_stmt*,int); } { - The first parameter is a prepared SQL statement. If this statement + The first argument is a prepared SQL statement. If this statement is a SELECT statement, the Nth column of the returned result set of the SELECT is a table column then the declared type of the table column is returned. If the Nth column of the result set is not at table @@ -347,9 +355,9 @@ api {} { const char *sqlite3_column_name(sqlite3_stmt*,int); const void *sqlite3_column_name16(sqlite3_stmt*,int); } { - The first parameter is a prepared SQL statement. This function returns + The first argument is a prepared SQL statement. This function returns the column heading for the Nth column of that statement, where N is the - second function parameter. The string returned is UTF-8 for + second function argument. The string returned is UTF-8 for sqlite3_column_name() and UTF-16 for sqlite3_column_name16(). } @@ -376,12 +384,8 @@ int sqlite3_complete16(const void *sql); } { These functions return true if the given input string comprises one or more complete SQL statements. - The parameter must be a nul-terminated UTF-8 string for sqlite3_complete() + The argument must be a nul-terminated UTF-8 string for sqlite3_complete() and a nul-terminated UTF-16 string for sqlite3_complete16(). - - The algorithm is simple. If the last token other than spaces - and comments is a semicolon, then return true. otherwise return - false. } {} api {} { @@ -424,7 +428,7 @@ int sqlite3_create_collation16( sequence (so that SQLite cannot call it anymore). Each time the user supplied function is invoked, it is passed a copy of the void* passed as the fourth argument to sqlite3_create_collation() or - sqlite3_create_collation16() as its first parameter. + sqlite3_create_collation16() as its first argument. The remaining arguments to the user-supplied routine are two strings, each represented by a [length, data] pair and encoded in the encoding @@ -462,7 +466,7 @@ int sqlite3_collation_needed16( sqlite3_collation_needed16(). The second argument is the database handle. The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE or SQLITE_UTF16LE, indicating the most desirable form of the collation - sequence function required. The fourth parameter is the name of the + sequence function required. The fourth argument is the name of the required collation sequence. The collation sequence is returned to SQLite by a collation-needed @@ -497,9 +501,9 @@ int sqlite3_create_function16( #define SQLITE_UTF16LE 4 #define SQLITE_ANY 5 } { - These two functions are used to add user functions or aggregates - implemented in C to the SQL language interpreted by SQLite. The - difference only between the two is that the second parameter, the + These two functions are used to add SQL functions or aggregates + implemented in C. The + only difference between these two routines is that the second argument, the name of the (scalar) function or aggregate, is encoded in UTF-8 for sqlite3_create_function() and UTF-16 for sqlite3_create_function16(). @@ -509,11 +513,11 @@ int sqlite3_create_function16( be added individually to each database handle with which they will be used. - The third parameter is the number of arguments that the function or - aggregate takes. If this parameter is -1 then the function or + The third argument is the number of arguments that the function or + aggregate takes. If this argument is -1 then the function or aggregate may take any number of arguments. - The fourth parameter, eTextRep, specifies what type of text arguments + The fourth argument, eTextRep, specifies what type of text arguments this function prefers to receive. Any function should be able to work work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be more efficient with one representation than another. Users are allowed @@ -521,21 +525,21 @@ int sqlite3_create_function16( depending on the text representation of the arguments. The the implementation which provides the best match is used. If there is only a single implementation which does not care what text representation is used, - then the fourth parameter should be SQLITE_ANY. + then the fourth argument should be SQLITE_ANY. - The fifth parameter is an arbitrary pointer. The function implementations + The fifth argument is an arbitrary pointer. The function implementations can gain access to this pointer using the sqlite_user_data() API. - The sixth, seventh and eighth, xFunc, xStep and xFinal, are + The sixth, seventh and eighth argumens, xFunc, xStep and xFinal, are pointers to user implemented C functions that implement the user function or aggregate. A scalar function requires an implementation of the xFunc callback only, NULL pointers should be passed as the xStep - and xFinal parameters. An aggregate function requires an implementation - of xStep and xFinal, but NULL should be passed for xFunc. To delete an + and xFinal arguments. An aggregate function requires an implementation + of xStep and xFinal, and NULL should be passed for xFunc. To delete an existing user function or aggregate, pass NULL for all three function - callback. Specifying an inconstant set of callback values, such as an - xFunc and an xFinal, or an xStep but no xFinal, SQLITE_ERROR is - returned. + callbacks. Specifying an inconstant set of callback values, such as an + xFunc and an xFinal, or an xStep but no xFinal, results in an SQLITE_ERROR + return. } api {} { @@ -595,19 +599,19 @@ int sqlite3_exec( A function to executes one or more statements of SQL. If one or more of the SQL statements are queries, then - the callback function specified by the 3rd parameter is + the callback function specified by the 3rd argument is invoked once for each row of the query result. This callback should normally return 0. If the callback returns a non-zero value then the query is aborted, all subsequent SQL statements are skipped and the sqlite3_exec() function returns the SQLITE_ABORT. - The 4th parameter is an arbitrary pointer that is passed - to the callback function as its first parameter. + The 4th argument is an arbitrary pointer that is passed + to the callback function as its first argument. - The 2nd parameter to the callback function is the number of - columns in the query result. The 3rd parameter to the callback + The 2nd argument to the callback function is the number of + columns in the query result. The 3rd argument to the callback is an array of strings holding the values for each column. - The 4th parameter to the callback is an array of strings holding + The 4th argument to the callback is an array of strings holding the names of each column. The callback function may be NULL, even for queries. A NULL @@ -731,7 +735,7 @@ long long int sqlite3_last_insert_rowid(sqlite3*); Each entry in an SQLite table has a unique integer key. (The key is the value of the INTEGER PRIMARY KEY column if there is such a column, otherwise the key is generated at random. The unique key is always - available as the ROWID, OID, or _ROWID_ column.) The following routine + available as the ROWID, OID, or _ROWID_ column.) This routine returns the integer key of the most recent insert in the database. This function is similar to the mysql_insert_id() function from MySQL. @@ -839,9 +843,9 @@ int sqlite3_prepare16( compile, is assumed to be encoded in UTF-8 for the sqlite3_prepare() function and UTF-16 for sqlite3_prepare16(). - The first parameter "db" is an SQLite database handle. The second - parameter "zSql" is the statement to be compiled, encoded as either - UTF-8 or UTF-16 (see above). If the next parameter, "nBytes", is less + The first argument "db" is an SQLite database handle. The second + argument "zSql" is the statement to be compiled, encoded as either + UTF-8 or UTF-16 (see above). If the next argument, "nBytes", is less than zero, then zSql is read up to the first nul terminator. If "nBytes" is not less than zero, then it is the length of the string zSql in bytes (not characters). @@ -853,7 +857,9 @@ int sqlite3_prepare16( *ppStmt is left pointing to a compiled SQL statement that can be executed using sqlite3_step(). Or if there is an error, *ppStmt may be set to NULL. If the input text contained no SQL (if the input is and - empty string or a comment) then *ppStmt is set to NULL. + empty string or a comment) then *ppStmt is set to NULL. The calling + procedure is responsible for deleting this compiled SQL statement + using sqlite3_finalize() after it has finished with it. On success, SQLITE_OK is returned. Otherwise an error code is returned. } @@ -913,9 +919,9 @@ void sqlite3_result_text16be(sqlite3_context*, const void*, int n, void(*)(void* void sqlite3_result_text16le(sqlite3_context*, const void*, int n, void(*)(void*)); void sqlite3_result_value(sqlite3_context*, sqlite3_value*); } { - User-defined functions invoke the following routines in order to + User-defined functions invoke these routines in order to set their return value. The sqlite3_result_value() routine is used - to return an exact copy of one of the parameters to the function. + to return an exact copy of one of the arguments to the function. The operation of these routines is very similar to the operation of sqlite3_bind_blob() and its cousins. Refer to the documentation there @@ -964,12 +970,12 @@ int sqlite3_set_authorizer( SQL statement should be aborted with an error and SQLITE_IGNORE if the column should be treated as a NULL value. - The second parameter to the access authorization function above will - be one of the values below. These values signify what kind of operation - is to be authorized. The 3rd and 4th parameters to the authorization - function will be parameters or NULL depending on which of the following - codes is used as the second parameter. The 5th parameter is the name - of the database ("main", "temp", etc.) if applicable. The 6th parameter + The second argument to the access authorization function will be one + of the defined constants shown. These values signify what kind of operation + is to be authorized. The 3rd and 4th arguments to the authorization + function will be arguments or NULL depending on which of the following + codes is used as the second argument. The 5th argument is the name + of the database ("main", "temp", etc.) if applicable. The 6th argument is the name of the inner-most trigger or view that is responsible for the access attempt or NULL if this access attempt is directly from input SQL code. @@ -999,12 +1005,13 @@ int sqlite3_step(sqlite3_stmt*); SQLITE_DONE means that the statement has finished executing successfully. sqlite3_step() should not be called again on this virtual - machine. + machine without first calling sqlite3_reset() to reset the virtual + machine back to its initial state. If the SQL statement being executed returns any data, then SQLITE_ROW is returned each time a new row of data is ready for processing by the caller. The values may be accessed using - the sqlite3_column_*() functions described below. sqlite3_step() + the sqlite3_column_*() functions. sqlite3_step() is called again to retrieve the next row of data. SQLITE_ERROR means that a run-time error (such as a constraint @@ -1032,7 +1039,7 @@ void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); api {} { void *sqlite3_user_data(sqlite3_context*); } { - The pUserData parameter to the sqlite3_create_function() and + The pUserData argument to the sqlite3_create_function() and sqlite3_create_function16() routines used to register user functions is available to the implementation of the function using this call. @@ -1051,9 +1058,9 @@ const void *sqlite3_value_text16be(sqlite3_value*); const void *sqlite3_value_text16le(sqlite3_value*); int sqlite3_value_type(sqlite3_value*); } { - This group of routines returns information about parameters to + This group of routines returns information about arguments to a user-defined function. Function implementations use these routines - to access their parameters. These routines are the same as the + to access their arguments. These routines are the same as the sqlite3_column_... routines except that these routines take a single sqlite3_value* pointer instead of an sqlite3_stmt* and an integer column number.