From 93db69ee0fd9d17f8fd26704af73b55f6a88e3ae Mon Sep 17 00:00:00 2001 From: drh Date: Tue, 1 Jun 2004 01:22:37 +0000 Subject: [PATCH] Add the capi3ref.html page to the website. (CVS 1516) FossilOrigin-Name: 89f54f1ffdddc99340777cda6d9b1d7446549fa2 --- main.mk | 4 + manifest | 19 +- manifest.uuid | 2 +- publish.sh | 110 +++--- www/capi3ref.tcl | 940 +++++++++++++++++++++++++++++++++++++++++++++++ www/docs.tcl | 5 +- 6 files changed, 1025 insertions(+), 55 deletions(-) create mode 100644 www/capi3ref.tcl diff --git a/main.mk b/main.mk index 7eacde21de..1b93b1de32 100644 --- a/main.mk +++ b/main.mk @@ -369,6 +369,9 @@ c_interface.html: $(TOP)/www/c_interface.tcl capi3.html: $(TOP)/www/capi3.tcl tclsh $(TOP)/www/capi3.tcl >capi3.html +capi3ref.html: $(TOP)/www/capi3ref.tcl + tclsh $(TOP)/www/capi3ref.tcl >capi3ref.html + changes.html: $(TOP)/www/changes.tcl tclsh $(TOP)/www/changes.tcl >changes.html @@ -455,6 +458,7 @@ DOC = \ arch.png \ c_interface.html \ capi3.html \ + capi3ref.html \ changes.html \ copyright.html \ copyright-release.html \ diff --git a/manifest b/manifest index 2f6d10ec23..094b974eb2 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Remove\sthe\ssqlite3_open_varargs()\sAPI.\s(CVS\s1515) -D 2004-06-01T00:03:53 +C Add\sthe\scapi3ref.html\spage\sto\sthe\swebsite.\s(CVS\s1516) +D 2004-06-01T01:22:38 F Makefile.in ab7b0d5118e2da97bac66be8684a1034e3500f5a F Makefile.linux-gcc b86a99c493a5bfb402d1d9178dcdc4bd4b32f906 F README f1de682fbbd94899d50aca13d387d1b3fd3be2dd @@ -16,8 +16,8 @@ F doc/lemon.html f0f682f50210928c07e562621c3b7e8ab912a538 F doc/report1.txt a031aaf37b185e4fa540223cb516d3bccec7eeac F install-sh 9d4de14ab9fb0facae2f48780b874848cbf2f895 F ltmain.sh f6b283068efa69f06eb8aa1fe4bddfdbdeb35826 -F main.mk 63b5680a8103b46481898d71c1c259b9f34e144a -F publish.sh 1cd5c982388560fa91eedf6a338e210f713b35c8 +F main.mk 0b231e6e257ab4d3a036510df1f636e9b75ffb3d +F publish.sh 2e579b7474d57b6debcead93c73a49eb8cb81718 F spec.template a38492f1c1dd349fc24cb0565e08afc53045304b F sqlite.1 83f4a9d37bdf2b7ef079a82d54eaf2e3509ee6ea F sqlite.def fc4f5734786fe4743cfe2aa98eb2da4b089edb5f @@ -185,6 +185,7 @@ F www/arch2.gif 49c6bb36160f03ca2b89eaa5bfb1f560c7d68ee7 F www/audit.tcl 90e09d580f79c7efec0c7d6f447b7ec5c2dce5c0 F www/c_interface.tcl 2176519fc2bd2d2cf6fe74fd806fc2d8362de2c8 F www/capi3.tcl 2825f418f5c5d8376d0e83474796363db1d9e875 +F www/capi3ref.tcl 4248a45a0fd21fe0c116326300408d0999a028b5 F www/changes.tcl 9d562205db584d26b358ebe93fb58039feefd1b8 F www/common.tcl f786e6be86fb2627ceb30e770e9efa83b9c67a3a F www/conflict.tcl fb8a2ba83746c7fdfd9e52fa7f6aaf5c422b8246 @@ -193,7 +194,7 @@ F www/copyright-release.pdf cfca3558fc97095e57c6117d08f1f5b80d95125a F www/copyright.tcl 82c9670c7ddb0311912ab7fe24703f33c531066c F www/datatype3.tcl ddfc758410109cb6a9bd617836b9334a7ddbd929 F www/datatypes.tcl 566004b81c36877397ddbe6e1907aae6065f6b41 -F www/docs.tcl 5ea8a84edd33030879725fca85905899c89c7075 +F www/docs.tcl 0dcbf954907bd5dbfb7f1e0220f4e50516e07cd3 F www/download.tcl 8c84f15695c92cb01486930055fdf5192995f474 F www/dynload.tcl 02eb8273aa78cfa9070dd4501dca937fb22b466c F www/faq.tcl 3a1776818d9bd973ab0c3048ec7ad6b1ad091ae5 @@ -212,7 +213,7 @@ F www/support.tcl 67682848d6ddd283370451dc3da2e56cded9fc9a F www/tclsqlite.tcl 19191cf2a1010eaeff74c51d83fd5f5a4d899075 F www/vdbe.tcl 59288db1ac5c0616296b26dce071c36cb611dfe9 F www/whentouse.tcl a8335bce47cc2fddb07f19052cb0cb4d9129a8e4 -P af8e2006d808031a040f293c44f3bfbe841b866b -R d1c59bd3cc6eefb8ae5de00c7e7fe30b -U danielk1977 -Z 968142c222e9046cd53636930b43cc0c +P 6902fb1b49fdf0e38265fa26198690243cdc2f58 +R d57cd331d29ed702de6a88d65460d891 +U drh +Z e3df5c47224ee70e358b0ca52ff2a388 diff --git a/manifest.uuid b/manifest.uuid index fdf3382536..33a7d60ee4 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -6902fb1b49fdf0e38265fa26198690243cdc2f58 \ No newline at end of file +89f54f1ffdddc99340777cda6d9b1d7446549fa2 \ No newline at end of file diff --git a/publish.sh b/publish.sh index d15e9bf703..171565e28b 100644 --- a/publish.sh +++ b/publish.sh @@ -80,50 +80,72 @@ mv tclsqlite.dll .. rm tclsqlite.o cat >sqlite.def <<\END_OF_FILE EXPORTS -sqlite_open -sqlite_close -sqlite_exec -sqlite_last_insert_rowid -sqlite_error_string -sqlite_interrupt -sqlite_complete -sqlite_busy_handler -sqlite_busy_timeout -sqlite_get_table -sqlite_free_table -sqlite_mprintf -sqlite_vmprintf -sqlite_exec_printf -sqlite_exec_vprintf -sqlite_get_table_printf -sqlite_get_table_vprintf -sqlite_freemem -sqlite_libversion -sqlite_libencoding -sqlite_changes -sqlite_create_function -sqlite_create_aggregate -sqlite_function_type -sqlite_user_data -sqlite_aggregate_context -sqlite_aggregate_count -sqlite_set_result_string -sqlite_set_result_int -sqlite_set_result_double -sqlite_set_result_error -sqliteMalloc -sqliteFree -sqliteRealloc -sqlite_set_authorizer -sqlite_trace -sqlite_compile -sqlite_step -sqlite_finalize -sqlite_reset -sqlite_bind -sqlite_last_statement_changes -sqlite_encode_binary -sqlite_decode_binary +sqlite3_aggregate_context +sqlite3_aggregate_count +sqlite3_bind_blob +sqlite3_bind_double +sqlite3_bind_int +sqlite3_bind_int64 +sqlite3_bind_null +sqlite3_bind_text +sqlite3_bind_text16 +sqlite3_busy_handler +sqlite3_busy_timeout +sqlite3_close +sqlite3_column_blob +sqlite3_column_bytes +sqlite3_column_bytes16 +sqlite3_column_count +sqlite3_column_decltype +sqlite3_column_decltype16 +sqlite3_column_double +sqlite3_column_int +sqlite3_column_int64 +sqlite3_column_name +sqlite3_column_name16 +sqlite3_column_text +sqlite3_column_text16 +sqlite3_column_type +sqlite3_complete +sqlite3_complete16 +sqlite3_create_function +sqlite3_create_function16 +sqlite3_errcode +sqlite3_errmsg +sqlite3_errmsg16 +sqlite3_finalize +sqlite3_free +sqlite3_interrupt +sqlite3_last_insert_rowid +sqlite3_mprintf +sqlite3_open +sqlite3_open16 +sqlite3_prepare +sqlite3_prepare16 +sqlite3_reset +sqlite3_result_blob +sqlite3_result_double +sqlite3_result_error +sqlite3_result_error16 +sqlite3_result_int +sqlite3_result_int64 +sqlite3_result_null +sqlite3_result_text +sqlite3_result_text16 +sqlite3_result_value +sqlite3_set_authorizer +sqlite3_step +sqlite3_user_data +sqlite3_value_blob +sqlite3_value_bytes +sqlite3_value_bytes16 +sqlite3_value_double +sqlite3_value_int +sqlite3_value_int64 +sqlite3_value_text +sqlite3_value_text16 +sqlite3_value_type +sqlite3_vmprintf END_OF_FILE i386-mingw32msvc-dllwrap \ --def sqlite.def -v --export-all \ diff --git a/www/capi3ref.tcl b/www/capi3ref.tcl new file mode 100644 index 0000000000..ce99c3e89c --- /dev/null +++ b/www/capi3ref.tcl @@ -0,0 +1,940 @@ +set rcsid {$Id: capi3ref.tcl,v 1.1 2004/06/01 01:22:38 drh Exp $} +source common.tcl +header {C/C++ Interface For SQLite Version 3} +puts { +

C/C++ Interface For SQLite Version 3

+} + +proc api {name prototype desc {notused x}} { + global apilist + if {$name==""} { + regsub -all {sqlite3_[a-z0-9_]+\(} $prototype \ + {[lappend name [string trimright & (]]} x1 + subst $x1 + } + lappend apilist [list $name $prototype $desc] +} + +api {result-codes} { +#define SQLITE_OK 0 /* Successful result */ +#define SQLITE_ERROR 1 /* SQL error or missing database */ +#define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */ +#define SQLITE_PERM 3 /* Access permission denied */ +#define SQLITE_ABORT 4 /* Callback routine requested an abort */ +#define SQLITE_BUSY 5 /* The database file is locked */ +#define SQLITE_LOCKED 6 /* A table in the database is locked */ +#define SQLITE_NOMEM 7 /* A malloc() failed */ +#define SQLITE_READONLY 8 /* Attempt to write a readonly database */ +#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite_interrupt() */ +#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ +#define SQLITE_CORRUPT 11 /* The database disk image is malformed */ +#define SQLITE_NOTFOUND 12 /* (Internal Only) Table or record not found */ +#define SQLITE_FULL 13 /* Insertion failed because database is full */ +#define SQLITE_CANTOPEN 14 /* Unable to open the database file */ +#define SQLITE_PROTOCOL 15 /* Database lock protocol error */ +#define SQLITE_EMPTY 16 /* (Internal Only) Database table is empty */ +#define SQLITE_SCHEMA 17 /* The database schema changed */ +#define SQLITE_TOOBIG 18 /* Too much data for one row of a table */ +#define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */ +#define SQLITE_MISMATCH 20 /* Data type mismatch */ +#define SQLITE_MISUSE 21 /* Library used incorrectly */ +#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ +#define SQLITE_AUTH 23 /* Authorization denied */ +#define SQLITE_ROW 100 /* sqlite_step() has another row ready */ +#define SQLITE_DONE 101 /* sqlite_step() has finished executing */ +} { +The sqlite3.h header file defines macros for the integer result codes +returned by many API functions. +} + +api {} { + void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); +} { + Aggregate functions use the following 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 + same aggregate instance) the same buffer is returned. The implementation + of the aggregate can use the returned buffer to accumulate data. + + The buffer allocated is freed automatically by SQLite. +} + +api {} { + int sqlite3_aggregate_count(sqlite3_context*); +} { + The next routine returns the number of calls to xStep for a particular + aggregate function instance. The current call to xStep counts so this + routine always returns at least 1. +} + +api {} { + int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, int eCopy); + int sqlite3_bind_double(sqlite3_stmt*, int, double); + int sqlite3_bind_int(sqlite3_stmt*, int, int); + int sqlite3_bind_int64(sqlite3_stmt*, int, long long int); + int sqlite3_bind_null(sqlite3_stmt*, int); + int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, int eCopy); + int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int n, int eCopy); +} { + 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. The value of these wildcard literals 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 "?" has an index of 1. ":N:" wildcards + use the index N. + + When the eCopy parameter is true, a copy of the value is made into + memory obtained and managed by SQLite. When eCopy is false, SQLite + assumes that the value is a constant and just stores a pointer to the + value without making a copy. + + The sqlite3_bind_*() routine 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. +} + +api {} { + void sqlite3_busy_handler(sqlite*, int(*)(void*,const char*,int), void*); +} { + This routine identifies a callback function that is invoked + whenever an attempt is made to open a database table that is + currently locked by another process or thread. If the busy callback + is NULL, then sqlite3_exec() returns SQLITE_BUSY immediately if + it finds a locked table. If the busy callback is not NULL, then + sqlite3_exec() invokes the callback with three arguments. The + second argument is the name of the locked table and the third + argument is the number of times the table has been busy. If the + busy callback returns 0, then sqlite3_exec() immediately returns + SQLITE_BUSY. If the callback returns non-zero, then sqlite3_exec() + tries to open the table again and the cycle repeats. + + The default busy callback is NULL. + + Sqlite is re-entrant, so the busy handler may start a new query. + (It is not clear why anyone would every want to do this, but it + is allowed, in theory.) But the busy handler may not close the + database. Closing the database from a busy handler will delete + data structures out from under the executing query and will + probably result in a coredump. +} + +api {} { + void sqlite3_busy_timeout(sqlite*, int ms); +} { + This routine sets a busy handler that sleeps for a while when a + table is locked. The handler will sleep multiple times until + at least "ms" milleseconds of sleeping have been done. After + "ms" milleseconds of sleeping, the handler returns 0 which + causes sqlite3_exec() to return SQLITE_BUSY. + + Calling this routine with an argument less than or equal to zero + turns off all busy handlers. +} + +api {} { +int sqlite3_changes(sqlite*); +} { + This function returns the number of database rows that were changed + (or inserted or deleted) by the most recent called sqlite3_exec(). + + All changes are counted, even if they were later undone by a + ROLLBACK or ABORT. Except, changes associated with creating and + dropping tables are not counted. + + If a callback invokes sqlite3_exec() recursively, then the changes + in the inner, recursive call are counted together with the changes + in the outer call. + + 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 + 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 + "DELETE FROM table WHERE 1" instead. +} + +api {} { + void sqlite3_close(sqlite *); +} { + Call this function with a pointer to a structure that was previously + returned from sqlite3_open() or sqlite3_open16() + and the corresponding database will by closed. +} + +api {} { +const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); +int sqlite3_column_bytes(sqlite3_stmt*, int iCol); +int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); +double sqlite3_column_double(sqlite3_stmt*, int iCol); +int sqlite3_column_int(sqlite3_stmt*, int iCol); +long long int sqlite3_column_int64(sqlite3_stmt*, int iCol); +const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); +const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); +int sqlite3_column_type(sqlite3_stmt*, int iCol); +#define SQLITE_INTEGER 1 +#define SQLITE_FLOAT 2 +#define SQLITE_TEXT 3 +#define SQLITE_BLOB 4 +#define SQLITE_NULL 5 +} { + These routines returns 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 + 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 + index of 0. + + If the SQL statement is not currently point to a valid row, or if the + the colulmn index is out of range, the result is undefined. + + These routines attempt to convert the value where appropriate. For + example, if the internal representation is FLOAT and a text result + is requested, sprintf() is used internally to do the conversion + automatically. The following table details the conversions that + are applied: + + + + + + + + + + + + + + + + + + + +
Internal TypeRequested TypeConversion
NULL INTEGERResult is 0
NULL FLOAT Result is 0.0
NULL TEXT Result is an empty string
NULL BLOB Result is a zero-length BLOB
INTEGER FLOAT Convert from integer to float
INTEGER TEXT ASCII rendering of the integer
INTEGER BLOB Same as for INTEGER->TEXT
FLOAT INTEGERConvert from float to integer
FLOAT TEXT ASCII rendering of the float
FLOAT BLOB Same as FLOAT->TEXT
TEXT INTEGERUse atoi()
TEXT FLOAT Use atof()
TEXT BLOB No change
BLOB INTEGERConvert to TEXT then use atoi()
BLOB FLOAT Convert to TEXT then use atof()
BLOB TEXT Add a \000 terminator if needed
+} + +api {} { +int sqlite3_column_count(sqlite3_stmt *pStmt); +} { + Return the number of columns in the result set returned by the compiled + SQL statement. This routine returns 0 if pStmt is an SQL statement + that does not return data (for example an UPDATE). +} + +api {} { +const char *sqlite3_column_decltype(sqlite3_stmt *, int i); +const void *sqlite3_column_decltype16(sqlite3_stmt*,int); +} { + The first parameter is a compiled 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 + column, then a NULL pointer is returned. The returned string is + UTF-8 encoded for sqlite3_column_decltype() and UTF-16 encoded + for sqlite3_column_decltype16(). + For example, in the database schema: + + 
+ CREATE TABLE t1(c1 INTEGER);
+
+ + And the following statement compiled: + + 
+ SELECT c1 + 1, 0 FROM t1;
+
+ + Then this routine would return the string "INTEGER" for the second + result column (i==1), and a NULL pointer for the first result column + (i==0). +} + +api {} { +const char *sqlite3_column_name(sqlite3_stmt*,int); +const void *sqlite3_column_name16(sqlite3_stmt*,int); +} { + The first parameter is a compiled 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 + sqlite3_column_name() and UTF-16 for sqlite3_column_name16(). +} + +api {} { +void *sqlite3_commit_hook(sqlite*, int(*)(void*), void*); +} { + This routine configures a callback function - the progress callback - that + is invoked periodically during long running calls to sqlite3_exec(), + sqlite3_step() and sqlite3_get_table(). + An example use for this API is to keep + a GUI updated during a large query. + + The progress callback is invoked once for every N virtual machine opcodes, + where N is the second argument to this function. The progress callback + itself is identified by the third argument to this function. The fourth + argument to this function is a void pointer passed to the progress callback + function each time it is invoked. + + If a call to sqlite3_exec(), sqlite3_step() or sqlite3_get_table() results + in less than N opcodes being executed, then the progress callback is not + invoked. + + To remove the progress callback altogether, pass NULL as the third + argument to this function. + + If the progress callback returns a result other than 0, then the current + query is immediately terminated and any database changes rolled back. If the + query was part of a larger transaction, then the transaction is not rolled + back and remains active. The sqlite3_exec() call returns SQLITE_ABORT. +} + +api {} { +int sqlite3_complete(const char *sql); +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() + 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 {} { +int sqlite3_create_function( + sqlite3 *, + const char *zFunctionName, + int nArg, + int eTextRep, + int iCollateArg, + void*, + void (*xFunc)(sqlite3_context*,int,sqlite3_value**), + void (*xStep)(sqlite3_context*,int,sqlite3_value**), + void (*xFinal)(sqlite3_context*) +); +int sqlite3_create_function16( + sqlite3*, + const void *zFunctionName, + int nArg, + int eTextRep, + int iCollateArg, + void*, + void (*xFunc)(sqlite3_context*,int,sqlite3_value**), + void (*xStep)(sqlite3_context*,int,sqlite3_value**), + void (*xFinal)(sqlite3_context*) +); +#define SQLITE3_UTF8 1 +#define SQLITE3_UTF16LE 2 +#define SQLITE3_UTF16BE 3 +#define SQLITE3_ANY 4 +} { + These two functions are used to add user functions or aggregates + implemented in C to the SQL langauge interpreted by SQLite. The + difference only between the two is that the second parameter, the + name of the (scalar) function or aggregate, is encoded in UTF-8 for + sqlite3_create_function() and UTF-16 for sqlite3_create_function16(). + + The first argument is the database handle that the new function or + aggregate is to be added to. If a single program uses more than one + database handle internally, then user functions or aggregates must + 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 negative, then the function or + aggregate may take any number of arguments. + + The seventh, eighth and ninth parameters, 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 + existing user function or aggregate, pass NULL for all three function + callback. Specifying an inconstent set of callback values, such as an + xFunc and an xFinal, or an xStep but no xFinal, SQLITE_ERROR is + returned. +} + +api {} { +int sqlite3_data_count(sqlite3_stmt *pStmt); +} { + Return the number of values in the current row of the result set. + + After a call to sqlite3_step() that returns SQLITE_ROW, this routine + will return the same value as the sqlite3_column_count() function. + After sqlite3_step() has returned an SQLITE_DONE, SQLITE_BUSY or + error code, or before sqlite3_step() has been called on a + compiled SQL statement, this routine returns zero. +} + +api {} { +int sqlite3_errcode(sqlite3 *db); +} { + Return the error code for the most recent sqlite3_* API call associated + with sqlite3 handle 'db'. SQLITE_OK is returned if the most recent + API call was successful. + + Calls to many sqlite3_* functions set the error code and string returned + by sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16() + (overwriting the previous values). Note that calls to sqlite3_errcode(), + sqlite3_errmsg() and sqlite3_errmsg16() themselves do not affect the + results of future invocations. + + Assuming no other intervening sqlite3_* API calls are made, the error + code returned by this function is associated with the same error as + the strings returned by sqlite3_errmsg() and sqlite3_errmsg16(). +} {} + +api {} { +const char *sqlite3_errmsg(sqlite3*); +const void *sqlite3_errmsg16(sqlite3*); +} { + Return a pointer to a UTF-8 encoded string (sqlite3_errmsg) + or a UTF-16 encoded string (sqlite3_errmsg16) describing in English the + error condition for the most recent sqlite3_* API call. The returned + string is always terminated by an 0x00 byte. + + The string "not an error" is returned when the most recent API call was + successful. +} + +api {} { +int sqlite3_exec( + sqlite*, /* An open database */ + const char *sql, /* SQL to be executed */ + sqlite_callback, /* Callback function */ + void *, /* 1st argument to callback function */ + char **errmsg /* Error msg written here */ +); +} { + 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 + 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 2nd parameter to the callback function is the number of + columns in the query result. The 3rd parameter 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 names of each column. + + The callback function may be NULL, even for queries. A NULL + callback is not an error. It just means that no callback + will be invoked. + + If an error occurs while parsing or evaluating the SQL (but + not while executing the callback) then an appropriate error + message is written into memory obtained from malloc() and + *errmsg is made to point to that message. The calling function + is responsible for freeing the memory that holds the error + message. Use sqlite3_free() for this. If errmsg==NULL, + then no error message is ever written. + + The return value is is SQLITE_OK if there are no errors and + some other return code if there is an error. The particular + return value depends on the type of error. + + If the query could not be executed because a database file is + locked or busy, then this function returns SQLITE_BUSY. (This + behavior can be modified somewhat using the sqlite3_busy_handler() + and sqlite3_busy_timeout() functions.) +} {} + +api {} { +int sqlite3_finalize(sqlite3_stmt *pStmt); +} { + The sqlite3_finalize() function is called to delete a compiled + SQL statement obtained by a previous call to sqlite3_prepare() + or sqlite3_prepare16(). If the statement was executed successfully, or + not executed at all, then SQLITE_OK is returned. If execution of the + statement failed then an error code is returned. + + This routine can be called at any point during the execution of the + virtual machine. If the virtual machine has not completed execution + when this routine is called, that is like encountering an error or + an interrupt. (See sqlite3_interrupt().) Incomplete updates may be + rolled back and transactions cancelled, depending on the circumstances, + and the result code returned will be SQLITE_ABORT. +} + +api {} { +void sqlite3_free(char *z); +} { + Use this routine to free memory obtained from + sqlite3_mprintf() or sqlite3_vmprintf(). +} + +api {} { +int sqlite3_get_table( + sqlite*, /* An open database */ + const char *sql, /* SQL to be executed */ + char ***resultp, /* Result written to a char *[] that this points to */ + int *nrow, /* Number of result rows written here */ + int *ncolumn, /* Number of result columns written here */ + char **errmsg /* Error msg written here */ +); +void sqlite3_free_table(char **result); +} { + This next routine is really just a wrapper around sqlite3_exec(). + Instead of invoking a user-supplied callback for each row of the + result, this routine remembers each row of the result in memory + obtained from malloc(), then returns all of the result after the + query has finished. + + As an example, suppose the query result where this table: + + 
+        Name        | Age
+        -----------------------
+        Alice       | 43
+        Bob         | 28
+        Cindy       | 21
+
+ + If the 3rd argument were &azResult then after the function returns + azResult will contain the following data: + + 
+        azResult[0] = "Name";
+        azResult[1] = "Age";
+        azResult[2] = "Alice";
+        azResult[3] = "43";
+        azResult[4] = "Bob";
+        azResult[5] = "28";
+        azResult[6] = "Cindy";
+        azResult[7] = "21";
+
+ + Notice that there is an extra row of data containing the column + headers. But the *nrow return value is still 3. *ncolumn is + set to 2. In general, the number of values inserted into azResult + will be ((*nrow) + 1)*(*ncolumn). + + After the calling function has finished using the result, it should + pass the result data pointer to sqlite3_free_table() in order to + release the memory that was malloc-ed. Because of the way the + malloc() happens, the calling function must not try to call + malloc() directly. Only sqlite3_free_table() is able to release + the memory properly and safely. + + The return value of this routine is the same as from sqlite3_exec(). +} + +api {sqlite3_interrupt} { + void sqlite3_interrupt(sqlite*); +} { + This function causes any pending database operation to abort and + return at its earliest opportunity. This routine is typically + called in response to a user action such as pressing "Cancel" + or Ctrl-C where the user wants a long query operation to halt + immediately. +} {} + +api {} { +int sqlite3_last_statement_changes(sqlite*); +} { +Experimental +} + +api {} { +long long int sqlite3_last_insert_rowid(sqlite*); +} { + 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 + returns the integer key of the most recent insert in the database. + + This function is similar to the mysql_insert_id() function from MySQL. +} {} + +api {} { +char *sqlite3_mprintf(const char*,...); +char *sqlite3_vmprintf(const char*, va_list); +} { + These routines are variants of the "sprintf()" from the + standard C library. The resulting string is written into memory + obtained from malloc() so that there is never a possiblity of buffer + overflow. These routines also implement some additional formatting + options that are useful for constructing SQL statements. + + The strings returned by these routines should be freed by calling + sqlite3_free(). + + All of the usual printf formatting options apply. In addition, there + is a "%q" option. %q works like %s in that it substitutes a null-terminated + string from the argument list. But %q also doubles every '\'' character. + %q is designed for use inside a string literal. By doubling each '\'' + character it escapes that character and allows it to be inserted into + the string. + + For example, so some string variable contains text as follows: + + 
+  char *zText = "It's a happy day!";
+
+ + One can use this text in an SQL statement as follows: + + 
+  sqlite3_exec_printf(db, "INSERT INTO table VALUES('%q')",
+       callback1, 0, 0, zText);
+
+ + Because the %q format string is used, the '\'' character in zText + is escaped and the SQL generated is as follows: + + 
+  INSERT INTO table1 VALUES('It''s a happy day!')
+
+ + This is correct. Had we used %s instead of %q, the generated SQL + would have looked like this: + + 
+  INSERT INTO table1 VALUES('It's a happy day!');
+
+ + This second example is an SQL syntax error. As a general rule you + should always use %q instead of %s when inserting text into a string + literal. +} {} + +api {} { +int sqlite3_open( + const char *filename, /* Database filename (UTF-8) */ + sqlite3 **ppDb, /* OUT: SQLite db handle */ + const char **args /* Null terminated array of option strings */ +); +int sqlite3_open16( + const void *filename, /* Database filename (UTF-16) */ + sqlite3 **ppDb, /* OUT: SQLite db handle */ + const char **args /* Null terminated array of option strings */ +); +} { + Open the sqlite database file "filename". The "filename" is UTF-8 + encoded for sqlite3_open() and UTF-16 encoded in the native byte order + for sqlite3_open16(). An sqlite3* handle is returned in *ppDb, even + if an error occurs. If the database is opened (or created) successfully, + then SQLITE_OK is returned. Otherwise an error code is returned. The + sqlite3_errmsg() or sqlite3_errmsg16() routines can be used to obtain + an English language description of the error. + + If the database file does not exist, then a new database is created. + The encoding for the database is UTF-8 if sqlite3_open() is called and + UTF-16 if sqlite3_open16 is used. + + Whether or not an error occurs when it is opened, resources associated + with the sqlite3* handle should be released by passing it to + sqlite3_close() when it is no longer required. +} + +api {} { +int sqlite3_prepare( + sqlite3 *db, /* Database handle */ + const char *zSql, /* SQL statement, UTF-8 encoded */ + int nBytes, /* Length of zSql in bytes. */ + sqlite3_stmt **ppStmt, /* OUT: Statement handle */ + const char **pzTail /* OUT: Pointer to unused portion of zSql */ +); +int sqlite3_prepare16( + sqlite3 *db, /* Database handle */ + const void *zSql, /* SQL statement, UTF-16 encoded */ + int nBytes, /* Length of zSql in bytes. */ + sqlite3_stmt **ppStmt, /* OUT: Statement handle */ + const void **pzTail /* OUT: Pointer to unused portion of zSql */ +); +} { + To execute an SQL query, it must first be compiled into a byte-code + program using one of the following routines. The only difference between + them is that the second argument, specifying the SQL statement to + 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 + 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). + + *pzTail is made to point to the first byte past the end of the first + SQL statement in zSql. This routine only compiles the first statement + in zSql, so *pzTail is left pointing to what remains uncompiled. + + *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. + + On success, SQLITE_OK is returned. Otherwise an error code is returned. +} + +api {} { +void sqlite3_progress_handler(sqlite*, int, int(*)(void*), void*); +} { + Experimental + + This routine configures a callback function - the progress callback - that + is invoked periodically during long running calls to sqlite3_exec(), + sqlite3_step() and sqlite3_get_table(). + An example use for this API is to keep + a GUI updated during a large query. + + The progress callback is invoked once for every N virtual machine opcodes, + where N is the second argument to this function. The progress callback + itself is identified by the third argument to this function. The fourth + argument to this function is a void pointer passed to the progress callback + function each time it is invoked. + + If a call to sqlite3_exec(), sqlite3_step() or sqlite3_get_table() results + in less than N opcodes being executed, then the progress callback is not + invoked. + + To remove the progress callback altogether, pass NULL as the third + argument to this function. + + If the progress callback returns a result other than 0, then the current + query is immediately terminated and any database changes rolled back. If the + query was part of a larger transaction, then the transaction is not rolled + back and remains active. The sqlite3_exec() call returns SQLITE_ABORT. + +} + +api {} { +int sqlite3_reset(sqlite3_stmt *pStmt); +} { + The sqlite3_reset() function is called to reset a compiled SQL + statement obtained by a previous call to sqlite3_prepare() or + sqlite3_prepare16() back to it's initial state, ready to be re-executed. + Any SQL statement variables that had values bound to them using + the sqlite3_bind_*() API retain their values. +} + +api {} { +void sqlite3_result_blob(sqlite3_context*, const void*, int n, int eCopy); +void sqlite3_result_double(sqlite3_context*, double); +void sqlite3_result_error(sqlite3_context*, const char*, int); +void sqlite3_result_error16(sqlite3_context*, const void*, int); +void sqlite3_result_int(sqlite3_context*, int); +void sqlite3_result_int64(sqlite3_context*, long long int); +void sqlite3_result_null(sqlite3_context*); +void sqlite3_result_text(sqlite3_context*, const char*, int n, int eCopy); +void sqlite3_result_text16(sqlite3_context*, const void*, int n, int eCopy); +void sqlite3_result_value(sqlite3_context*, sqlite3_value*); +} { + User-defined functions invoke the following 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. +} + +api {} { +int sqlite3_set_authorizer( + sqlite*, + int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), + void *pUserData +); +#define SQLITE_COPY 0 /* Table Name File Name */ +#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ +#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */ +#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */ +#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */ +#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */ +#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */ +#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */ +#define SQLITE_CREATE_VIEW 8 /* View Name NULL */ +#define SQLITE_DELETE 9 /* Table Name NULL */ +#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */ +#define SQLITE_DROP_TABLE 11 /* Table Name NULL */ +#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */ +#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */ +#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */ +#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */ +#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */ +#define SQLITE_DROP_VIEW 17 /* View Name NULL */ +#define SQLITE_INSERT 18 /* Table Name NULL */ +#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */ +#define SQLITE_READ 20 /* Table Name Column Name */ +#define SQLITE_SELECT 21 /* NULL NULL */ +#define SQLITE_TRANSACTION 22 /* NULL NULL */ +#define SQLITE_UPDATE 23 /* Table Name Column Name */ +#define SQLITE_ATTACH 24 /* Filename NULL */ +#define SQLITE_DETACH 25 /* Database Name NULL */ + +#define SQLITE_DENY 1 /* Abort the SQL statement with an error */ +#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ +} { + This routine registers a callback with the SQLite library. The + callback is invoked (at compile-time, not at run-time) for each + attempt to access a column of a table in the database. The callback + returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire + 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 + 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. + + The return value of the authorization function should be one of the + constants SQLITE_DENY or SQLITE_IGNORE. +} + +api {} { +int sqlite3_step(sqlite3_stmt*); +} { + After an SQL query has been compiled with a call to either + sqlite3_prepare() or sqlite3_prepare16(), then this function must be + called one or more times to execute the statement. + + The return value will be either SQLITE_BUSY, SQLITE_DONE, + SQLITE_ROW, SQLITE_ERROR, or SQLITE_MISUSE. + + SQLITE_BUSY means that the database engine attempted to open + a locked database and there is no busy callback registered. + Call sqlite3_step() again to retry the open. + + SQLITE_DONE means that the statement has finished executing + successfully. sqlite3_step() should not be called again on this virtual + machine. + + 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() + is called again to retrieve the next row of data. + + SQLITE_ERROR means that a run-time error (such as a constraint + violation) has occurred. sqlite3_step() should not be called again on + the VM. More information may be found by calling sqlite3_errmsg(). + + SQLITE_MISUSE means that the this routine was called inappropriately. + Perhaps it was called on a virtual machine that had already been + finalized or on one that had previously returned SQLITE_ERROR or + SQLITE_DONE. Or it could be the case the the same database connection + is being used simulataneously by two or more threads. +} + +api {} { +void *sqlite3_trace(sqlite*, void(*xTrace)(void*,const char*), void*); +} { + Register a function that is called at every invocation of sqlite3_exec() + or sqlite3_prepare(). This function can be used (for example) to generate + a log file of all SQL executed against a database. This is frequently + useful when debugging an application that uses SQLite. +} + +api {} { +void *sqlite3_user_data(sqlite3_context*); +} { + The pUserData parameter 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. +} + +api {} { +const void *sqlite3_value_blob(sqlite3_value*); +int sqlite3_value_bytes(sqlite3_value*); +int sqlite3_value_bytes16(sqlite3_value*); +double sqlite3_value_double(sqlite3_value*); +int sqlite3_value_int(sqlite3_value*); +long long int sqlite3_value_int64(sqlite3_value*); +const unsigned char *sqlite3_value_text(sqlite3_value*); +const void *sqlite3_value_text16(sqlite3_value*); +int sqlite3_value_type(sqlite3_value*); +} { + This group of routines returns information about parameters to + a user-defined function. Function implementations use these routines + to access their parameters. 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. +} + +set n 0 +set i 0 +foreach item $apilist { + set namelist [lindex $item 0] + foreach name $namelist { + set n_to_name($n) $name + set n_to_idx($n) $i + set name_to_idx($name) $i + incr n + } + incr i +} +set i 0 +foreach name [lsort [array names name_to_idx]] { + set sname($i) $name + incr i +} +puts {} +set nrow [expr {($n+2)/3}] +set i 0 +for {set j 0} {$j<3} {incr j} { + if {$j>0} {puts {}} + puts {} +} +puts "
} + set limit [expr {$i+$nrow}] + puts {
    } + while {$i<$limit && $i<$n} { + set name $sname($i) + puts "
  • $name
    • " + incr i + } + puts {
" + +proc resolve_name {ignore_list name} { + global name_to_idx + if {![info exists name_to_idx($name)] || [lsearch $ignore_list $name]>=0} { + return $name + } else { + return "$name" + } +} + +foreach name [lsort [array names name_to_idx]] { + set i $name_to_idx($name) + if {[info exists done($i)]} continue + set done($i) 1 + foreach {namelist prototype desc} [lindex $apilist $i] break + foreach name $namelist { + puts "" + } + puts "

" + puts "
"
+  regsub "^( *\n)+" $prototype {} p2
+  regsub "(\n *)+\$" $p2 {} p3
+  puts $p3
+  puts "
" + regsub -all {\[} $desc {\[} desc + regsub -all {sqlite3_[a-z0-9_]+} $desc "\[resolve_name $name &\]" d2 + regsub -all "\n( *\n)+" [subst $d2] "

\n\n

" d3 + puts "

$d3

" +} + +footer $rcsid diff --git a/www/docs.tcl b/www/docs.tcl index f54416a2ed..05c6a405a2 100644 --- a/www/docs.tcl +++ b/www/docs.tcl @@ -1,7 +1,7 @@ # This script generates the "docs.html" page that describes various # sources of documentation available for SQLite. # -set rcsid {$Id: docs.tcl,v 1.2 2004/05/31 18:22:26 drh Exp $} +set rcsid {$Id: docs.tcl,v 1.3 2004/06/01 01:22:38 drh Exp $} source common.tcl header {SQLite Documentation} puts { @@ -32,6 +32,9 @@ doc {Version 3 C/C++ API} {capi3.html} { A description of the C/C++ interface bindings for SQLite version 3.0.0 and following. } +doc {Version 3 C/C++ API
Reference} {capi3ref.html} { + This document describes each API function separately. +} doc {Tcl API} {tclsqlite.html} { A description of the TCL interface bindings for SQLite.