} api {} { int sqlite3_column_count(sqlite3_stmt *pStmt); } { Return the number of columns in the result set returned by the prepared SQL statement. This routine returns 0 if pStmt is an SQL statement that does not return data (for example an UPDATE). See also sqlite3_data_count(). } api {} { const char *sqlite3_column_decltype(sqlite3_stmt *, int i); const void *sqlite3_column_decltype16(sqlite3_stmt*,int); } { 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 a 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:
Internal Type Requested Type Conversion NULL INTEGER Result is 0 NULL FLOAT Result is 0.0 NULL TEXT Result is NULL pointer NULL BLOB Result is NULL pointer INTEGER FLOAT Convert from integer to float INTEGER TEXT ASCII rendering of the integer INTEGER BLOB Same as for INTEGER->TEXT FLOAT INTEGER Convert from float to integer FLOAT TEXT ASCII rendering of the float FLOAT BLOB Same as FLOAT->TEXT TEXT INTEGER Use atoi() TEXT FLOAT Use atof() TEXT BLOB No change BLOB INTEGER Convert to TEXT then use atoi() BLOB FLOAT Convert to TEXT then use atof() BLOB TEXT Add a \\000 terminator if needed
And the following statement compiled:CREATE TABLE t1(c1 INTEGER);
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). If the following statements were compiled then this routine would return "INTEGER" for the first (only) result column.SELECT c1 + 1, c1 FROM t1;
} api {} { int sqlite3_table_column_metadata( sqlite3 *db, /* Connection handle */ const char *zDbName, /* Database name or NULL */ const char *zTableName, /* Table name */ const char *zColumnName, /* Column name */ char const **pzDataType, /* OUTPUT: Declared data type */ char const **pzCollSeq, /* OUTPUT: Collation sequence name */ int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ int *pPrimaryKey, /* OUTPUT: True if column part of PK */ int *pAutoinc /* OUTPUT: True if colums is auto-increment */ ); } { This routine is used to obtain meta information about a specific column of a specific database table accessible using the connection handle passed as the first function argument. The column is identified by the second, third and fourth parameters to this function. The second parameter is either the name of the database (i.e. "main", "temp" or an attached database) containing the specified table or NULL. If it is NULL, then all attached databases are searched for the table using the same algorithm as the database engine uses to resolve unqualified table references. The third and fourth parameters to this function are the table and column name of the desired column, respectively. Neither of these parameters may be NULL. Meta information is returned by writing to the memory locations passed as the 5th and subsequent parameters to this function. Any of these arguments may be NULL, in which case the corresponding element of meta information is ommitted.SELECT (SELECT c1) FROM t1; SELECT (SELECT c1 FROM t1); SELECT c1 FROM (SELECT c1 FROM t1); SELECT * FROM (SELECT c1 FROM t1); SELECT * FROM (SELECT * FROM t1);
Parameter Output Type Description ----------------------------------- 5th const char* Declared data type 6th const char* Name of the columns default collation sequence 7th int True if the column has a NOT NULL constraint 8th int True if the column is part of the PRIMARY KEY 9th int True if the column is AUTOINCREMENTThe memory pointed to by the character pointers returned for the declaration type and collation sequence is valid only until the next call to any sqlite API function. This function may load one or more schemas from database files. If an error occurs during this process, or if the requested table or column cannot be found, an SQLITE error code is returned and an error message left in the database handle (to be retrieved using sqlite3_errmsg()). Specifying an SQL view instead of a table as the third argument is also considered an error. If the specified column is "rowid", "oid" or "_rowid_" and an INTEGER PRIMARY KEY column has been explicitly declared, then the output parameters are set for the explicitly declared column. If there is no explicitly declared IPK column, then the data-type is "INTEGER", the collation sequence "BINARY" and the primary-key flag is set. Both the not-null and auto-increment flags are clear. This API is only available if the library was compiled with the SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. } api {} { const char *sqlite3_column_database_name(sqlite3_stmt *pStmt, int N); const void *sqlite3_column_database_name16(sqlite3_stmt *pStmt, int N); } { If the Nth column returned by statement pStmt is a column reference, these functions may be used to access the name of the database (either "main", "temp" or the name of an attached database) that contains the column. If the Nth column is not a column reference, NULL is returned. See the description of function sqlite3_column_decltype() for a description of exactly which expressions are considered column references. Function sqlite3_column_database_name() returns a pointer to a UTF-8 encoded string. sqlite3_column_database_name16() returns a pointer to a UTF-16 encoded string. } api {} { const char *sqlite3_column_origin_name(sqlite3_stmt *pStmt, int N); const void *sqlite3_column_origin_name16(sqlite3_stmt *pStmt, int N); } { If the Nth column returned by statement pStmt is a column reference, these functions may be used to access the schema name of the referenced column in the database schema. If the Nth column is not a column reference, NULL is returned. See the description of function sqlite3_column_decltype() for a description of exactly which expressions are considered column references. Function sqlite3_column_origin_name() returns a pointer to a UTF-8 encoded string. sqlite3_column_origin_name16() returns a pointer to a UTF-16 encoded string. } api {} { const char *sqlite3_column_table_name(sqlite3_stmt *pStmt, int N); const void *sqlite3_column_table_name16(sqlite3_stmt *pStmt, int N); } { If the Nth column returned by statement pStmt is a column reference, these functions may be used to access the name of the table that contains the column. If the Nth column is not a column reference, NULL is returned. See the description of function sqlite3_column_decltype() for a description of exactly which expressions are considered column references. Function sqlite3_column_table_name() returns a pointer to a UTF-8 encoded string. sqlite3_column_table_name16() returns a pointer to a UTF-16 encoded string. } api {} { const char *sqlite3_column_name(sqlite3_stmt*,int); const void *sqlite3_column_name16(sqlite3_stmt*,int); } { 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 argument. The string returned is UTF-8 for sqlite3_column_name() and UTF-16 for sqlite3_column_name16(). } api {} { void *sqlite3_commit_hook(sqlite3*, int(*xCallback)(void*), void *pArg); } { Experimental Register a callback function to be invoked whenever a new transaction is committed. The pArg argument is passed through to the callback. callback. If the callback function returns non-zero, then the commit is converted into a rollback. If another function was previously registered, its pArg value is returned. Otherwise NULL is returned. Registering a NULL function disables the callback. Only a single commit hook callback can be registered at a time. } 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 argument must be a nul-terminated UTF-8 string for sqlite3_complete() and a nul-terminated UTF-16 string for sqlite3_complete16(). } {} api {} { int sqlite3_create_collation( sqlite3*, const char *zName, int pref16, void*, int(*xCompare)(void*,int,const void*,int,const void*) ); int sqlite3_create_collation16( sqlite3*, const char *zName, int pref16, void*, int(*xCompare)(void*,int,const void*,int,const void*) ); #define SQLITE_UTF8 1 #define SQLITE_UTF16BE 2 #define SQLITE_UTF16LE 3 #define SQLITE_UTF16 4 } { These two functions are used to add new collation sequences to the sqlite3 handle specified as the first argument. The name of the new collation sequence is specified as a UTF-8 string for sqlite3_create_collation() and a UTF-16 string for sqlite3_create_collation16(). In both cases the name is passed as the second function argument. The third argument must be one of the constants SQLITE_UTF8, SQLITE_UTF16LE or SQLITE_UTF16BE, indicating that the user-supplied routine expects to be passed pointers to strings encoded using UTF-8, UTF-16 little-endian or UTF-16 big-endian respectively. The SQLITE_UTF16 constant indicates that text strings are expected in UTF-16 in the native byte order of the host machine. A pointer to the user supplied routine must be passed as the fifth argument. If it is NULL, this is the same as deleting the collation 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 argument. The remaining arguments to the user-supplied routine are two strings, each represented by a [length, data] pair and encoded in the encoding that was passed as the third argument when the collation sequence was registered. The user routine should return negative, zero or positive if the first string is less than, equal to, or greater than the second string. i.e. (STRING1 - STRING2). } api {} { int sqlite3_collation_needed( sqlite3*, void*, void(*)(void*,sqlite3*,int eTextRep,const char*) ); int sqlite3_collation_needed16( sqlite3*, void*, void(*)(void*,sqlite3*,int eTextRep,const void*) ); } { To avoid having to register all collation sequences before a database can be used, a single callback function may be registered with the database handle to be called whenever an undefined collation sequence is required. If the function is registered using the sqlite3_collation_needed() API, then it is passed the names of undefined collation sequences as strings encoded in UTF-8. If sqlite3_collation_needed16() is used, the names are passed as UTF-16 in machine native byte order. A call to either function replaces any existing callback. When the user-function is invoked, the first argument passed is a copy of the second argument to sqlite3_collation_needed() or 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 argument is the name of the required collation sequence. The collation sequence is returned to SQLite by a collation-needed callback using the sqlite3_create_collation() or sqlite3_create_collation16() APIs, described above. } api {} { int sqlite3_create_function( sqlite3 *, const char *zFunctionName, int nArg, int eTextRep, void *pUserData, 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, void *pUserData, void (*xFunc)(sqlite3_context*,int,sqlite3_value**), void (*xStep)(sqlite3_context*,int,sqlite3_value**), void (*xFinal)(sqlite3_context*) ); #define SQLITE_UTF8 1 #define SQLITE_UTF16 2 #define SQLITE_UTF16BE 3 #define SQLITE_UTF16LE 4 #define SQLITE_ANY 5 } { 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(). The length of the name is limited to 255 bytes, exclusive of the zero-terminator. Note that the name length limit is in bytes, not characters. Any attempt to create a function with a longer name will result in an SQLITE_ERROR error. 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 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 maximum number of arguments to a new SQL function is 127. A number larger than 127 for the third argument results in an SQLITE_ERROR error. 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 to specify separate implementations for the same function which are called 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 argument should be SQLITE_ANY. 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 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 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 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 {} { 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 prepared SQL statement, this routine returns zero. } api {} { int sqlite3_errcode(sqlite3 *db); } { Return the error code for the most recent failed sqlite3_* API call associated with sqlite3 handle 'db'. If a prior API call failed but the most recent API call succeeded, the return value from this routine is undefined. 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. Calls to API routines that do not return an error code (examples: sqlite3_data_count() or sqlite3_mprintf()) do not change the error code returned by this routine. 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( sqlite3*, /* 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 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 argument is an arbitrary pointer that is passed to the callback function as its first argument. 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 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 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 prepared 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. All prepared statements must finalized before sqlite3_close() is called or else the close will fail with a return code of SQLITE_BUSY. 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 canceled, depending on the circumstances, and the result code returned will be SQLITE_ABORT. } api {} { void *sqlite3_malloc(int); void *sqlite3_realloc(void*, int); void sqlite3_free(void*); } { These routines provide access to the memory allocator used by SQLite. Depending on how SQLite has been compiled and the OS-layer backend, the memory allocator used by SQLite might be the standard system malloc()/realloc()/free(), or it might be something different. With certain compile-time flags, SQLite will add wrapper logic around the memory allocator to add memory leak and buffer overrun detection. The OS layer might substitute a completely different memory allocator. Use these APIs to be sure you are always using the correct memory allocator. The sqlite3_free() API, not the standard free() from the system library, should always be used to free the memory buffer returned by sqlite3_mprintf() or sqlite3_vmprintf() and to free the error message string returned by sqlite3_exec(). Using free() instead of sqlite3_free() might accidentally work on some systems and build configurations but will fail on others. Compatibility Note: Prior to version 3.4.0, the sqlite3_free API was prototyped to take a char* parameter rather than void*. Like this:
The change to using void* might cause warnings when compiling older code against newer libraries, but everything should still work correctly. } api {} { int sqlite3_get_table( sqlite3*, /* 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:void sqlite3_free(char*);
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(sqlite3*);
} {
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 {} {
long long int sqlite3_last_insert_rowid(sqlite3*);
} {
Each entry in an SQLite table has a unique integer key called the "rowid".
The rowid is always available as an undeclared column
named ROWID, OID, or _ROWID_.
If the table has a column of type INTEGER PRIMARY KEY then that column
is another an alias for the rowid.
This routine
returns the rowid of the most recent INSERT into the database
from the database connection given in the first argument. If
no inserts have ever occurred on this database connection, zero
is returned.
If an INSERT occurs within a trigger, then the rowid of the
inserted row is returned by this routine as long as the trigger
is running. But once the trigger terminates, the value returned
by this routine reverts to the last value inserted before the
trigger fired.
} {}
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 possibility 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:
One can use this text in an SQL statement as follows:char *zText = "It's a happy day!";
sqlite3_exec_printf(db, "INSERT INTO table VALUES('%q')",
callback1, 0, 0, zText);
INSERT INTO table1 VALUES('It''s a happy day!')
INSERT INTO table1 VALUES('It's a happy day!');
| }} puts { | }
set limit [expr {$i+$nrow}]
puts {
| }
}
puts "
"
regsub "^( *\n)+" $prototype {} p2
regsub "(\n *)+\$" $p2 {} p3
puts $p3
puts "" d3 puts "
$d3
" } footer $rcsid