-C :-)\s(CVS\s2)
-D 2000-05-29T17:44:25
+C :-)\s(CVS\s3)
+D 2000-05-29T18:20:15
F Makefile.in bab6ff58d847d1b9eb25d4cbf671e4ebd0c74256
F configure 8faba4d0194321e5f61a64e842c65eab0f68e6d8 x
F configure.in 4fc2947d631037bd340b112d6193847d7ac827ae
F tool/opNames.awk 2bd9071a138e4e2be13dc98fe066398a61219e1e
F tool/opcodeDoc.awk b3a2a3d5d3075b8bd90b7afe24283efdd586659c
F tool/renumberOps.awk 6d067177ad5f8d711b79577b462da9b3634bd0a9
-F www/index.tcl 3785d894fe5fc0976bb7400ab307b4aef34fbf60
-F www/sqlite.tcl c24416391358ade2e74fffeaca8eb0b0e8b1d1ac
-P 6f3655f79f9b6fc9fb7baaa10a7e0f2b6a512dfa
-R 6b1f63772187c94801897db097691461
+F www/c_interface.tcl 851921790368665e040d15eb33a3ca569de97643
+F www/index.tcl c10c625192ee9f19f186f65b90196c9cabe30936
+F www/sqlite.tcl 69674d9b8344870de7a6f059169311ebc54111f8
+P 53841c66c699665e83c933627bbe7a193cfccb6b
+R 43b99c48908500b05b2ba1dbbc4bcfec
U drh
-Z 084e3a79b4f63a91b5e2b285235fe69b
+Z 1a9f5aa38de8d4363998964e8afa6610
-53841c66c699665e83c933627bbe7a193cfccb6b
\ No newline at end of file
+9e36a6014b9e8298d8fff71f0f1e3fd5610c30bd
\ No newline at end of file
--- /dev/null
+#
+# Run this Tcl script to generate the sqlite.html file.
+#
+set rcsid {$Id: c_interface.tcl,v 1.1 2000/05/29 18:20:15 drh Exp $}
+
+puts {<html>
+<head>
+ <title>The C language interface to the SQLite library</title>
+</head>
+<body bgcolor=white>
+<h1 align=center>
+The C language interface to the SQLite library
+</h1>}
+puts "<p align=center>
+(This page was last modified on [lrange $rcsid 3 4] GMT)
+</p>"
+
+puts {
+<p>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.</p>
+
+<p>The interface to the SQLite library consists of 4 functions
+and one opaque data structure.</p>
+
+<blockquote><pre>
+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);
+</pre></blockquote>
+
+<p>All of the above definitions are included in the "sqlite.h"
+header file that comes in the source tree.</p>
+
+<h2>Opening a database</h2>
+
+<p>Use the <b>sqlite_open</b> 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.</p>
+
+<p>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 <b>sqlite_master</b>
+stored in its own GDBM file. This special table records the database
+schema.</p>
+
+<p>To create a new SQLite database, all you have to do is call
+<b>sqlite_open()</b> with the first parameter set to the name of
+an empty directory and the second parameter set to 0666.</p>
+
+<p>The return value of the <b>sqlite_open()</b> function is a
+pointer to an opaque <b>sqlite</b> structure. This pointer will
+be the first argument to all subsequent SQLite function calls that
+deal with the same database.</p>
+
+<h2>Closing the database</h2>
+
+<p>To close an SQLite database, just call the <b>sqlite_close()</b>
+function passing it the sqlite structure pointer that was obtained
+from a prior call to <b>sqlite_open</b>.
+
+<h2>Executing SQL statements</h2>
+
+<p>The <b>sqlite_exec()</b> function is used to process SQL statements
+and queries. This function requires 5 parameters as follows:</p>
+
+<ol>
+<li><p>A pointer to the sqlite structure obtained from a prior call
+ to <b>sqlite_open()</b>.</p></li>
+<li><p>A null-terminated string containing the text of the SQL statements
+ and/or queries to be processed.</p></li>
+<li><p>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.</p></li>
+<li><p>A pointer to anything that is forward to become the first argument
+ to the callback function.</p></li>
+<li><p>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.</p></li>
+</ol>
+
+<p>
+The callback function is used to receive the results of a query. A
+prototype for the callback function is as follows:</p>
+
+<blockquote><pre>
+int Callback(void *pArg, int argc, char **argv, char **columnNames){
+ return 0;
+}
+</pre></blockquote>
+
+<p>The first argument to the callback is just a copy of the fourth argument
+to <b>sqlite_exec()</b> 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.</p>
+
+<p>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 <b>sqlite_exec()</b>.
+
+<h2>Testing for a complete SQL statement</h2>
+
+<p>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 <b>sqlite_complete</b> 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 <b>sqlite_complete</b>
+returns false, then more text is required to complete the SQL statement.</p>
+
+<p>For the purpose of the <b>sqlite_complete()</b> function, an SQL
+statement is complete if it ends in a semicolon.</p>
+
+puts {
+<p><hr /></p>
+<p><a href="index.html"><img src="/goback.jpg" border=0 />
+Back to the SQLite Home Page</a>
+</p>
+
+</body></html>}
#
# Run this TCL script to generate HTML for the index.html file.
#
-set rcsid {$Id: index.tcl,v 1.1 2000/05/29 17:44:25 drh Exp $}
+set rcsid {$Id: index.tcl,v 1.2 2000/05/29 18:20:15 drh Exp $}
puts {<html>
<head><title>SQLite: An SQL Frontend For GDBM</title></head>
<body bgcolor=white>
<h1 align=center>SQLite: An SQL Frontend For GDBM</h1>
<p align=center>}
-puts "Version 0.1 (alpha)<br />"
-puts "Last modified [lrange $rcsid 3 4]"
+puts "Last modified [lrange $rcsid 3 4] GMT"
puts {</p>}
puts {<h2>Introduction</h2>
SQL RDBMS.</p>
<p>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 <a href="c_interface.html">c_interface.html</a> 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.</p>
<p>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.</p>
+library. For more information on the sqlite program,
+see <a href="sqlite.html">sqlite.html</a>.</p>
<p>SQLite does not try to implement every feature of SQL. But it
does strive to implement to most commonly used features. SQLite
</ul>
</p>
-<p>SQLite does not (at present) implement any of these features:</p>
+<p>Some the many SQL features that SQLite does not (currently)
+implement are as follows:</p>
<p>
<ul>
<li>ALTER TABLE</li>
<li>The GROUP BY or HAVING clauses of a SELECT</li>
-<li>The LIKE or IN operators of expressions</li>
+<li>The LIKE or IN</li>
<li>Constraints</li>
+<li>Nested queries</li>
<li>Transactions or rollback</li>
</ul>
</p>
puts {<h2>Download</h2>
-<p>You can download a tarball containing complete SQLite source
-code at <a href="sqlite.tar.gz">sqlite.tar.gz</a>.}
+<p>You can download a tarball containing all C source
+code
for SQLite at <a href="sqlite.tar.gz">sqlite.tar.gz</a>.}
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 {</p>}
+puts {</p>
+
+<p>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 <a href="all.tar.gz">all.tar.gz</a>.}
+puts "This is a [file size all.tar.gz] byte download and was
+was last modified at [clock format [file mtime sqlite.tar.gz]]</p>"
puts {<h2>Related Sites</h2>
<ul>
-<li><p>The cannonical site for GDBM is
+<li><p>The canonical site for GDBM is
<a href="http://www.gnu.org/software/gdbm/gdbm.html">
http://www.gnu.org/software/gdbm/gdbm.html</a></p></li>
#
# Run this Tcl script to generate the sqlite.html file.
#
-set rcsid {$Id: sqlite.tcl,v 1.1 2000/05/29 17:44:26 drh Exp $}
+set rcsid {$Id: sqlite.tcl,v 1.2 2000/05/29 18:20:15 drh Exp $}
puts {<html>
<head>
</head>
<body bgcolor=white>
<h1 align=center>
-<tt>sqlite</tt>: A program to administer SQLite databases
+sqlite: A program to administer SQLite databases
</h1>}
-puts "<p align=center>(This page was last modified on [lrange $rcsid 3 4])</p>"
+puts "<p align=center>
+(This page was last modified on [lrange $rcsid 3 4] GMT)
+</p>"
puts {
<p>The SQLite library includes a simple command-line utility named
puts {
<p>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:</p>}
Code {
<p>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.</p>}
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:</p>}
projects / thirdparty / sqlite.git / commitdiff
