+Back to the SQLite Home Page
++(This page was last modified on [lrange $rcsid 3 4] GMT) +
" + +puts { +The SQLite library is designed to be very easy to use from +a C or C++ program. This document gives an overview of the C/C++ +programming interface.
+ +The interface to the SQLite library consists of 4 functions +and one opaque data structure.
+ ++ ++typedef struct sqlite sqlite; +sqlite *sqlite_open(const char *filename, int mode, char **errmsg); +void sqlite_close(sqlite*); +int sqlite_exec( + sqlite*, + char *sql, + int (*)(void*,int,char**,char**), + void*, + char **errmsg +); +int sqlite_complete(const char *sql); +
All of the above definitions are included in the "sqlite.h" +header file that comes in the source tree.
+ +Use the sqlite_open function to open an existing SQLite +database or to create a new SQLite database. The first argument +is the database name. The second argument is a constant 0666 to +open the database for reading and writing and 0444 to open the +database read only. The third argument is a pointer to a string +pointer. If the third argument is not NULL and an error occurs +while trying to open the database, then an error message will be +written to memory obtained from malloc() and *errmsg will be made +to point to this error message. The calling function is responsible +for freeing the memory when it has finished with it.
+ +An SQLite database is just a directory containing a collection of +GDBM files. There is one GDBM file for each table and index in the +database. All GDBM files end with the ".tbl" suffix. Every SQLite +database also contains a special database table named sqlite_master +stored in its own GDBM file. This special table records the database +schema.
+ +To create a new SQLite database, all you have to do is call +sqlite_open() with the first parameter set to the name of +an empty directory and the second parameter set to 0666.
+ +The return value of the sqlite_open() function is a +pointer to an opaque sqlite structure. This pointer will +be the first argument to all subsequent SQLite function calls that +deal with the same database.
+ +To close an SQLite database, just call the sqlite_close() +function passing it the sqlite structure pointer that was obtained +from a prior call to sqlite_open. + +
The sqlite_exec() function is used to process SQL statements +and queries. This function requires 5 parameters as follows:
+ +A pointer to the sqlite structure obtained from a prior call + to sqlite_open().
A null-terminated string containing the text of the SQL statements + and/or queries to be processed.
A pointer to a callback function which is invoked once for each + row in the result of a query. This argument may be NULL, in which + case no callbacks will ever be invoked.
A pointer to anything that is forward to become the first argument + to the callback function.
A pointer to a string pointer into which error messages are written. + This argument may be NULL, in which case error messages are not + reported back to the calling function.
+The callback function is used to receive the results of a query. A +prototype for the callback function is as follows:
+ +
+int Callback(void *pArg, int argc, char **argv, char **columnNames){
+ return 0;
+}
+The first argument to the callback is just a copy of the fourth argument +to sqlite_exec() This parameter can be used to pass arbitrary +information through to the callback function from client code. +The second argument is the number columns in the query result. +The third argument is an array of pointers to string where each string +is a single column of the result for that record. The names of the +columns are contained in the fourth argument.
+ +The callback function should normally return 0. If the callback +function returns non-zero, the query is immediately aborted and the +return value of the callback is returned from sqlite_exec(). + +
The last interface routine to SQLite is a convenience function used +to test whether or not a string forms a complete SQL statement. +If the sqlite_complete function returns true when its input +is a string, then the argument forms a complete SQL statement. +There are no guarantees that the syntax of that statement is correct, +but we at least know the statement is complete. If sqlite_complete +returns false, then more text is required to complete the SQL statement.
+ +For the purpose of the sqlite_complete() function, an SQL +statement is complete if it ends in a semicolon.
+ +puts { +
+Back to the SQLite Home Page
+
}
-puts "Version 0.1 (alpha)
"
-puts "Last modified [lrange $rcsid 3 4]"
+puts "Last modified [lrange $rcsid 3 4] GMT"
puts {
The C interface to SQLite is very simple, consisting of only -four functions and a single opaque data structure. A Tcl interface +four functions and a single opaque data structure. +See c_interface.html for details. +A Tcl interface to SQLite is also available and is included in the source tree. +Documentation on the Tcl interface is pending. Interfaces for perl and python may be supplied in future releases.
There is a standalone C program named "sqlite" that can be used to interactively create, update and/or query an SQLite database. The sources to the sqlite program are part of the source tree and can be used as an example of how to interact with the SQLite C -library.
+library. For more information on the sqlite program, +see sqlite.html.SQLite does not try to implement every feature of SQL. But it does strive to implement to most commonly used features. SQLite @@ -47,14 +50,16 @@ currently understands the following SQL commands:
-SQLite does not (at present) implement any of these features:
+Some the many SQL features that SQLite does not (currently) +implement are as follows:
You can download a tarball containing complete SQLite source -code at sqlite.tar.gz.} +
You can download a tarball containing all C source +code for SQLite at sqlite.tar.gz.} puts "This is a [file size sqlite.tar.gz] byte download. The tarball was last modified at [clock format [file mtime sqlite.tar.gz]]" -puts {
} +puts { + +You can also download a larger tarball that contains everything +in the source tarball plus all of the sources for the text that +appears on this website, and other miscellaneous files. The +complete tarball is found at all.tar.gz.} +puts "This is a [file size all.tar.gz] byte download and was +was last modified at [clock format [file mtime sqlite.tar.gz]]
" puts {The cannonical site for GDBM is +
The canonical site for GDBM is http://www.gnu.org/software/gdbm/gdbm.html
(This page was last modified on [lrange $rcsid 3 4])
" +puts "+(This page was last modified on [lrange $rcsid 3 4] GMT) +
" puts {The SQLite library includes a simple command-line utility named @@ -200,7 +202,7 @@ sql> puts {
By default, each column is 10 characters wide. -Data that is too wide to fit in a column is trucated. You can +Data that is too wide to fit in a column is truncated. You can adjust the column widths using the ".width" command. Like this:
} Code { @@ -237,7 +239,7 @@ puts {The third output mode supported by sqlite is called "list". In list mode, each record of a query result is written on one line of output and each field within that record is separated by a specific -separator string. The default separator is a pipe symbolc ("|"). +separator string. The default separator is a pipe symbol ("|"). List mode is especially useful when you are going to send the output of a query to another program (such as AWK) for additional process.
} @@ -359,7 +361,7 @@ to "column" and to set the column widths to values that are reasonable for looking at the output of an EXPLAIN command. The EXPLAIN command is an SQLite-specific command that is useful for debugging. If any regular SQL is prefaced by EXPLAIN, then the SQL command is parsed and -analyized but is not executed. Instead, the sequence of virtual machine +analyzed but is not executed. Instead, the sequence of virtual machine instructions that would have been used to execute the SQL command are returned like a query result. For example:}