From dd1dcd511b5fa65b54805d64cf43545bf3ff6ba2 Mon Sep 17 00:00:00 2001 From: drh Date: Mon, 29 May 2000 18:20:15 +0000 Subject: [PATCH] :-) (CVS 3) FossilOrigin-Name: 9e36a6014b9e8298d8fff71f0f1e3fd5610c30bd --- manifest | 15 ++--- manifest.uuid | 2 +- www/c_interface.tcl | 139 ++++++++++++++++++++++++++++++++++++++++++++ www/index.tcl | 34 +++++++---- www/sqlite.tcl | 14 +++-- 5 files changed, 179 insertions(+), 25 deletions(-) create mode 100644 www/c_interface.tcl diff --git a/manifest b/manifest index 0c0a0a7dcb..518db14eec 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -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 @@ -23,9 +23,10 @@ F tool/lempar.c a1eec94d6eacc12332368660ec65f3b248853833 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 diff --git a/manifest.uuid b/manifest.uuid index 6a33114508..38a14da1b4 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -53841c66c699665e83c933627bbe7a193cfccb6b \ No newline at end of file +9e36a6014b9e8298d8fff71f0f1e3fd5610c30bd \ No newline at end of file diff --git a/www/c_interface.tcl b/www/c_interface.tcl new file mode 100644 index 0000000000..013072c069 --- /dev/null +++ b/www/c_interface.tcl @@ -0,0 +1,139 @@ +# +# 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 { + + The C language interface to the SQLite library + + +

+The C language interface to the SQLite library +

} +puts "

+(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.

+ +

Opening a database

+ +

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.

+ +

Closing the 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. + +

Executing SQL statements

+ +

The sqlite_exec() function is used to process SQL statements +and queries. This function requires 5 parameters as follows:

+ +
    +

  1. A pointer to the sqlite structure obtained from a prior call + to sqlite_open().

    2. +

  2. A null-terminated string containing the text of the SQL statements + and/or queries to be processed.

    3. +

  3. 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.

    4. +

  4. A pointer to anything that is forward to become the first argument + to the callback function.

    5. +

  5. 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.

    6. +
+ +

+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(). + +

Testing for a complete SQL statement

+ +

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 +

+ +} diff --git a/www/index.tcl b/www/index.tcl index 082d0a5521..235611a923 100644 --- a/www/index.tcl +++ b/www/index.tcl @@ -1,15 +1,14 @@ # # 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 { SQLite: An SQL Frontend For GDBM

SQLite: An SQL Frontend For GDBM

} -puts "Version 0.1 (alpha)
" -puts "Last modified [lrange $rcsid 3 4]" +puts "Last modified [lrange $rcsid 3 4] GMT" puts {

} puts {

Introduction

@@ -20,15 +19,19 @@ to use an SQL database but which do not have access to a full-blown SQL RDBMS.

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:

@@ -88,16 +93,23 @@ Click to subscribe to sqlite puts {

Download

-

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 {

Related Sites