database/sqlite
1
0
Fork 0
mirror of https://github.com/sqlite/sqlite.git synced 2025-11-16 23:02:26 +03:00
Code Activity

Updates to API documentation and comments in sqlite3.h. (CVS 2155)

Browse Source 
FossilOrigin-Name: 46584348f3cc10c0c6e9ba42110a6c03caf1497e
This commit is contained in:
drh
2004-12-07 02:14:51 +00:00
parent 61212b69c1
commit 32c0d4f17b
4 changed files with 105 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
manifest
View File

@@ -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

2
manifest.uuid
View File

@@ -1 +1 @@
f7415a0d6433980ff6c25cf2238f5e9881c38873
46584348f3cc10c0c6e9ba42110a6c03caf1497e

31
src/sqlite.h.in
View File

@@ -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);

151
www/capi3ref.tcl
View File

@@ -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.
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 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 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 parameter to sqlite3_bind_blob(), sqlite3_bind_text(), and
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.