source: project/release/4/sqlite3/trunk/sqlite3.html @ 15334

Last change on this file since 15334 was 15334, checked in by Thomas Chust, 11 years ago

[sqlite3] Merged CHICKEN 4 specific local changes back into Subversion.

File size: 30.2 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2<!-- Generated by eggdoc Revision: 1.20  -->
3<html>
4<head>
5<title>Eggs Unlimited - sqlite3</title><style type="text/css"><!--
6       CODE {
7             color: #666666;
8           }
9 /*   DT.definition EM { font-weight: bold; font-style: normal; } */
10;      DT.definition { 
11                    background: #eee;
12                   color: black;
13                   padding: 0.2em 1em 0.2em 0.7em;
14                   margin-left: 0.2em;
15border: 1px solid #bbc;
16                   font-family: "Andale Mono", monospace;
17                   /* font-size: 1.2em; */
18                   
19                 }
20     DD {
21                   margin-top: 0.8em;
22                   margin-bottom: 0.8em;
23     }
24     DIV.subsection {
25                    border-top: 1px solid #448;
26                    padding-left: 1em;
27                    margin-bottom: 1.2em;
28     }
29     DIV.subsubsection {
30                    border-top: 1px dotted #99c;
31                    /* border-left: 1px solid #99c; */
32                    padding-left: 1em;
33                    margin-bottom: 1.2em;
34     }
35     DIV.subsubsubsection {
36                    border-top: 1px solid #ddf;
37                    padding-left: 1em;
38                    margin-bottom: 1.2em;
39     }
40
41         DIV.section {
42                 margin-bottom: 1.5em;
43         }
44         a:link {
45                 color: #336;
46         }
47         a:visited { color: #666; }
48         a:active  { color: #966; }
49         a:hover   { color: #669; }
50         body { margin: 0; padding: 0; background: #fff; color: #000; font: 9pt "Lucida Grande", "Verdana", sans-serif; }
51         H2 {
52                 background: #336;
53                 color: #fff;
54                 padding-top: 0.5em;
55                 padding-bottom: 0.5em;
56                 padding-left: 16px;
57                 margin: 0 0 1em 0;
58        }
59        UL LI {
60                list-style: none;
61        }
62        TT {
63                font-family: "Andale Mono", monospace;
64                /* font-size: 1.2em; */
65        }
66        H3 {
67                color: #113;
68                margin-bottom: 0.5em;
69        }
70        H4, H5, H6 {
71                color: #113;
72                margin-bottom: 1.0em;
73        }
74        H5 {
75                font-weight: normal;
76                font-style: italic;
77                font-size: 100%;
78                margin-top: 1.2em;
79        }
80        H6 {
81                font-weight: bold;
82                font-size: 85%;
83                margin-top: 1.2em;
84        }
85     DIV#eggheader {
86         text-align: center;
87                 float: right;
88                 margin-right: 2em;
89     }
90     DIV#header IMG {
91            /* display: block; margin-left: auto; margin-right: auto;  */
92            /* float: right; */
93            border: none;  /* firefox */
94     }
95     DIV#footer {
96                background: #bbd;
97                padding: 0.7em ;
98                border-top: 1px solid #cce;
99     }
100     DIV#footer hr {
101                display: none;
102     }
103     DIV#footer a {
104                float: left;
105     }
106     DIV#revision-history {
107         float: right;
108     }
109     
110     DIV#body {
111                 margin: 1em 1em 1em 16px;
112         }
113
114     DIV#examples PRE {
115       background: #eef;
116       padding: 0.1em;
117       border: 1px solid #aac;
118     }
119     PRE#license, DIV#examples PRE {
120       padding: 0.5em;
121     }
122     DIV#examples PRE {
123       /* font-size: 85%; */
124     }
125     PRE { font-family: "Andale Mono", monospace; }
126     TABLE {
127       background: #eef;
128       padding: 0.2em;
129       border: 1px solid #aac;
130       border-collapse: collapse;
131       width: 100%;
132     }
133     TABLE.symbol-table TD.symbol {
134          width: 15em;
135          font-family: "Andale Mono", monospace;
136          /* font-size: 1.2em; */
137     }
138     TH {
139       text-align: left;
140       border-bottom: 1px solid #aac;
141       padding: 0.25em 0.5em 0.25em 0.5em;
142     } 
143     TD { padding: 0.25em 0.5em 0.25em 0.5em; }
144     --></style></head>
145<body>
146<div id="header">
147<h2>sqlite3</h2>
148<div id="eggheader"><a href="index.html">
149<img src="egg.jpg" alt="[Picture of an egg]" /></a></div></div>
150<div id="body">
151<div class="section">
152<h3>Description</h3>
153<p>Bindings to version 3.x of the SQLite API.</p></div>
154<div class="section">
155<h3>Author</h3><a href="http://www.chust.org/">Thomas Chust</a></div>
156<div class="section">
157<h3>Usage</h3><tt>(require-extension sqlite3)</tt></div>
158<div class="section">
159<h3>Download</h3><a href="sqlite3.egg">sqlite3.egg</a></div>
160<div class="section">
161<h3>Requires</h3>
162<ul>
163<li>check-errors</li>
164<li>synch</li>
165<li>miscmacros</li>
166<li>matchable</li></ul></div>
167<div class="section">
168<h3>Documentation</h3>
169<p>The API of SQLite changed significantly from version 2.x to 3.x. These are new bindings to the modified API, which are reasonably complete -- most procedures that take callback arguments are missing, though.</p>
170<p>For in-depth information on the functionality of the routines and general information you should consult the <a href="http://www.sqlite.org/">SQLite documentation</a> as well as this manual.</p>
171<div class="subsection">
172<h4>Exceptions</h4>
173<p>Unless otherwise indicated, all procedures and methods in this egg may throw an exception of the kind <tt>(exn sqlite3)</tt> if something goes wrong. This exception will contain a <tt>status</tt> property indicating the return value of the operation that failed:
174<table>
175<tr>
176<th>Symbol</th>
177<th>Meaning</th></tr>
178<tr>
179<td><tt>error</tt></td>
180<td>SQL error or missing database </td></tr>
181<tr>
182<td><tt>internal</tt></td>
183<td>An internal logic error in SQLite </td></tr>
184<tr>
185<td><tt>permission</tt></td>
186<td>Access permission denied </td></tr>
187<tr>
188<td><tt>abort</tt></td>
189<td>Callback routine requested an abort </td></tr>
190<tr>
191<td><tt>busy</tt></td>
192<td>The database file is locked </td></tr>
193<tr>
194<td><tt>locked</tt></td>
195<td>A table in the database is locked </td></tr>
196<tr>
197<td><tt>no-memory</tt></td>
198<td>A malloc() failed </td></tr>
199<tr>
200<td><tt>read-only</tt></td>
201<td>Attempt to write a readonly database </td></tr>
202<tr>
203<td><tt>interrupt</tt></td>
204<td>Operation terminated by sqlite-interrupt() </td></tr>
205<tr>
206<td><tt>io-error</tt></td>
207<td>Some kind of disk I/O error occurred </td></tr>
208<tr>
209<td><tt>corrupt</tt></td>
210<td>The database disk image is malformed </td></tr>
211<tr>
212<td><tt>not-found</tt></td>
213<td>(Internal Only) Table or record not found </td></tr>
214<tr>
215<td><tt>full</tt></td>
216<td>Insertion failed because database is full </td></tr>
217<tr>
218<td><tt>cant-open</tt></td>
219<td>Unable to open the database file </td></tr>
220<tr>
221<td><tt>protocol</tt></td>
222<td>Database lock protocol error </td></tr>
223<tr>
224<td><tt>empty</tt></td>
225<td>(Internal Only) Database table is empty </td></tr>
226<tr>
227<td><tt>schema</tt></td>
228<td>The database schema changed </td></tr>
229<tr>
230<td><tt>too-big</tt></td>
231<td>Too much data for one row of a table </td></tr>
232<tr>
233<td><tt>constraint</tt></td>
234<td>Abort due to contraint violation </td></tr>
235<tr>
236<td><tt>mismatch</tt></td>
237<td>Data type mismatch </td></tr>
238<tr>
239<td><tt>misuse</tt></td>
240<td>Library used incorrectly </td></tr>
241<tr>
242<td><tt>no-lfs</tt></td>
243<td>Uses OS features not supported on host </td></tr>
244<tr>
245<td><tt>authorization</tt></td>
246<td> Authorization denied</td></tr>
247<tr>
248<td><tt>done</tt></td>
249<td><tt>step!</tt> has finished executing, so no further data is ready</td></tr></table></p></div>
250<div class="subsection">
251<h4>Abstract data types</h4>
252<dt class="definition"><strong>procedure:</strong> (database? OBJECT) &rArr; BOOLEAN</dt>
253<dd>
254<p>Checks whether a value represents an SQLite database.</p></dd>
255<dt class="definition"><strong>procedure:</strong> (error-database LOCATION OBJECT [ARGUMENT-NAME]) &rArr; VOID</dt>
256<dd>
257<p>Raises a type error saying that a database was expected instead of the given value.</p></dd>
258<dt class="definition"><strong>procedure:</strong> (check-database LOCATION OBJECT [ARGUMENT-NAME]) &rArr; VOID</dt>
259<dd>
260<p>Raises a type error like <tt>error-database</tt> does, unless the given value satisfies <tt>database?</tt></p></dd>
261<dt class="definition"><strong>procedure:</strong> (statement? OBJECT) &rArr; BOOLEAN</dt>
262<dd>
263<p>Checks whether the value <tt>v</tt> represents an SQL statement.</p></dd>
264<dt class="definition"><strong>procedure:</strong> (error-statement LOCATION OBJECT [ARGUMENT-NAME]) &rArr; VOID</dt>
265<dd>
266<p>Raises a type error saying that a statement was expected instead of the given value.</p></dd>
267<dt class="definition"><strong>procedure:</strong> (check-statement LOCATION OBJECT [ARGUMENT-NAME]) &rArr; VOID</dt>
268<dd>
269<p>Raises a type error like <tt>error-statement</tt> does, unless the given value satisfies <tt>statement?</tt></p></dd></div>
270<div class="subsection">
271<h4>Managing databases</h4>
272<dt class="definition"><strong>procedure:</strong> (open-database PATH) &rArr; DATABASE</dt>
273<dd>
274<p>Opens the indicated database file and returns a database object for it.</p>
275<p>The given path is subject to the same special expansion as paths passed to <tt>open-input-file</tt> and similar procedures.</p></dd>
276<dt class="definition"><strong>procedure:</strong> (define-collation DATABASE NAME [PROC]) &rArr; VOID</dt>
277<dd>
278<p>If a procedure is given, registers a new collation sequence identified by <tt>name</tt> for use in the context of database handle <tt>db</tt>. If no procedure is passed, the collation sequence with the given name is removed.</p>
279<p><tt>PROC</tt> should have the signature <tt>(PROC STRING STRING) &rArr; FIXNUM</tt>. It should return a negative number if the first argument sorts before the second, a positive number if the second sorts before the first and zero if they are equal.</p>
280<p>As <tt>PROC</tt> will be called in a callback context from within <tt>step!</tt>, safety measures are installed to avoid throwing any exceptions, invoking continuations or returning invalid values from it. Attempts to do so will result in a <tt>0</tt> return value and warning messages.</p></dd>
281<dt class="definition"><strong>procedure:</strong> (define-function DATABASE NAME N PROC) &rArr; VOID
282<br /><strong>procedure:</strong> (define-function DATABASE NAME N STEP-PROC SEED [FINAL-PROC]) &rArr; VOID</dt>
283<dd>
284<p>Registers a new SQL function identified by <tt>NAME</tt> for use in the context of the given database handle. If <tt>STEP-PROC</tt> and <tt>SEED</tt> are given, the new function becomes an aggregate function. Once registered, functions cannot be deleted.</p>
285<p><tt>N</tt> is the number of parameters the new SQL function takes or <tt>-1</tt> to allow any number of arguments.</p>
286<p><tt>PROC</tt> should have the signature <tt>(PROC . PARAMS) &rArr; OBJECT</tt>. It is called with the <tt>N</tt> parameters given to the SQL function converted into Scheme objects like by <tt>column-data</tt>. The return value is converted into an SQLite data object like by <tt>bind!</tt>. A return value of <tt>(void)</tt> corresponds to <tt>NULL</tt> in SQLite.</p>
287<p><tt>STEP-PROC</tt> should have the signature <tt>(STEP-PROC SEED . PARAMS) &rArr; SEED</tt>. It is called with the parameters given to the SQL function for every row being processed. The seed value passed is initially the one given as an argument to <tt>define-function</tt>; for subsequent calls it is the last value returned by <tt>STEP-PROC</tt> and after completion of <tt>FINAL-PROC</tt> it will be the initial value again.</p>
288<p><tt>FINAL-PROC</tt> should have the signature <tt>(FINAL-PROC SEED) &rArr; OBJECT</tt> and transforms the last seed value into the value to be returned from the aggregate function. If it is not explicitly specified, <tt>STEP-PROC</tt> defaults to the identity function.</p>
289<p>As <tt>PROC</tt>, <tt>STEP-PROC</tt> and <tt>FINAL-PROC</tt> will be called in a callback context from within <tt>step!</tt>, safety measures are installed to avoid throwing any exceptions, invoking continuations or returning invalid values from them. Attempts to do such things will result in <tt>NULL</tt> return values and warning messages.</p></dd>
290<dt class="definition"><strong>procedure:</strong> (set-busy-handler! DATABASE PROC) &rArr; VOID</dt>
291<dd>
292<p>Installs the supplied procedure as the application's busy handler, or removes it if <tt>#f</tt>.  When the database returns a busy error code, the egg will invoke this handler repeatedly until it returns <tt>#f</tt>.  The handler will be called with arguments <tt>DATABASE</tt> and <tt>COUNT</tt> (number of times invoked for the same operation).</p>
293<p>As <tt>PROC</tt> is not called in a callback context, it is legal to invoke captured continuations, and it is safe in the presence of multiple threads.  In general, this handler should give up at some point to avoid possible deadlock.</p>
294<p>For an example handler, see the code of <tt>make-busy-timeout</tt>.</p></dd>
295<dt class="definition"><strong>procedure:</strong> (make-busy-timeout MS) &rArr; PROC</dt>
296<dd>
297<p>Returns a handler suitable for use with <tt>set-busy-handler!</tt>. It polls in increasing intervals until the timeout in milliseconds is reached. The handler is non-blocking.</p>
298<pre>;; Example:
299(define open-database/timeout
300  (let ((handler (make-busy-timeout 2000)))
301    (lambda (db-name)
302      (let ((db (open-database db-name)))
303  (set-busy-handler! db handler)
304  db))))</pre></dd>
305<dt class="definition"><strong>procedure:</strong> (interrupt! DATABASE) &rArr; VOID</dt>
306<dd>
307<p>Cancels any running database operation as soon as possible.</p>
308<p>This function is always successful and never throws an exception.</p></dd>
309<dt class="definition"><strong>procedure:</strong> (auto-committing? DATABASE) &rArr; BOOLEAN</dt>
310<dd>
311<p>Checks whether the database is currently in auto committing mode, i.e. no transaction is currently active.</p>
312<p>This function always returns a state and never throws an exception.</p></dd>
313<dt class="definition"><strong>procedure:</strong> (change-count DATABASE [TOTAL]) &rArr; CARDINAL-INTEGER</dt>
314<dd>
315<p>Returns the number of rows changed by the last statement (if <tt>(not TOTAL)</tt>, which is the default) or since the database was opened (if <tt>TOTAL</tt>).</p>
316<p>This function always returns a count and never throws an exception.</p></dd>
317<dt class="definition"><strong>procedure:</strong> (last-insert-rowid DATABASE) &rArr; INTEGER</dt>
318<dd>
319<p>Returns the row ID of the last row inserted in <tt>db</tt>.</p>
320<p>This function always returns a number and never throws an exception.</p></dd>
321<dt class="definition"><strong>procedure:</strong> (finalize! DATABASE-OR-STATEMENT) &rArr; VOID</dt>
322<dd>
323<p>Closes the given database or finalizes the given statement.</p>
324<p>Every statement must be finalized to free its resources and discard it before the database itself can be finalized.</p></dd></div>
325<div class="subsection">
326<h4>Managing statements</h4>
327<dt class="definition"><strong>procedure:</strong> (prepare DATABASE SQL) &rArr; STATEMENT, SQL</dt>
328<dd>
329<p>Compiles the first SQL statement in <tt>SQL</tt> and returns a statement and the tail of the SQL code, which was not compiled (or an empty string).</p></dd>
330<dt class="definition"><strong>procedure:</strong> (repair! STATEMENT) &rArr; VOID</dt>
331<dd>
332<p>Recompiles the SQL code used to create the statement, transfers all existing bindings from the old statement handle to the new one and destructively modifies <tt>STATEMENT</tt> to point to the new statement handle.</p>
333<p>If the operation is successful, the old handle is finalized, in case of error, the new handle is finalized and the old one stays untouched.</p>
334<p>Usually you should not have to call this routine by hand. It is invoked by <tt>step!</tt> to automagically repair a stale statement handle after a database schema change.</p></dd>
335<dt class="definition"><strong>procedure:</strong> (column-count STATEMENT) &rArr; CARDINAL-INTEGER</dt>
336<dd>
337<p>Can be applied to any statement and returns the number of columns it will return as results.</p>
338<p>This procedure always succeeds and never throws an exception.</p></dd>
339<dt class="definition"><strong>procedure:</strong> (column-name STATEMENT I) &rArr; STRING</dt>
340<dd>
341<p>Can be applied to any statement and returns the name of the column number <tt>I</tt> (counting from 0) as a string or <tt>#f</tt> if the column has no name.</p>
342<p>This procedure always succeeds and never throws an exception.</p></dd>
343<dt class="definition"><strong>procedure:</strong> (column-declared-type STATEMENT I) &rArr; STRING</dt>
344<dd>
345<p>Can be applied to any statement and returns the declared type (as given in the <tt>CREATE</tt> statement) of the column number <tt>I</tt> (counting from 0) as a string or <tt>#f</tt> if the column has no declared type.</p>
346<p>This procedure always succeeds and never throws an exception.</p></dd>
347<dt class="definition"><strong>procedure:</strong> (bind-parameter-count STATEMENT) &rArr; CARDINAL-INTEGER</dt>
348<dd>
349<p>Can be applied to any statement and returns the number of free parameters that can be bound in the statement.</p>
350<p>This procedure always succeeds and never throws an exception.</p></dd>
351<dt class="definition"><strong>procedure:</strong> (bind-parameter-index STATEMENT NAME) &rArr; CARDINAL-INTEGER</dt>
352<dd>
353<p>Can be applied to any statement and returns the index of the bindable parameter called <tt>NAME</tt> or <tt>#f</tt> if no such parameter exists.</p>
354<p>This procedure always succeeds and never throws an exception.</p></dd>
355<dt class="definition"><strong>procedure:</strong> (bind-parameter-name STATEMENT I) &rArr; STRING</dt>
356<dd>
357<p>Can be applied to any statement and returns the name of the bindable parameter number <tt>I</tt> (counting from 0) or <tt>#f</tt> if no such parameter exists or the parameter has no name.</p>
358<p>This procedure always succeeds and never throws an exception.</p></dd>
359<dt class="definition"><strong>procedure:</strong> (bind! STATEMENT I OBJECT) &rArr; VOID</dt>
360<dd>
361<p>Can be applied to any statement to bind its free parameter number <tt>I</tt> (counting from 0) to the given value. Scheme types of the value map to SQLite types as follows:
362<table>
363<tr>
364<th>Scheme type</th>
365<th>SQLite type</th></tr>
366<tr>
367<td><tt>boolean?</tt></td>
368<td><tt>integer: #t = 1, #f = 0</tt></td></tr>
369<tr>
370<td><tt>fixnum?</tt></td>
371<td><tt>integer</tt></td></tr>
372<tr>
373<td><tt>real?</tt></td>
374<td><tt>float</tt></td></tr>
375<tr>
376<td><tt>string?</tt></td>
377<td><tt>text</tt></td></tr>
378<tr>
379<td><tt>blob?</tt></td>
380<td><tt>blob</tt></td></tr>
381<tr>
382<td><tt>(void)</tt></td>
383<td><tt>null</tt></td></tr></table></p>
384<p>Unless there is internal trouble in SQLite, this method should always succeeds and never throw an exception. For invalid parameter indices the method just silently does nothing.</p></dd>
385<dt class="definition"><strong>procedure:</strong> (bind-parameters! STATEMENT . PARAMETERS) &rArr; VOID</dt>
386<dd>
387<p>Resets the statement and binds all its free parameters.</p>
388<p>In addition to just listing the values to bind to the statement's parameters in sequence, you may specify parameters prefixed by keywords that are resolved to parameter indices by prefixing their names with <tt>&quot;:&quot;</tt> and resolving them using <tt>bind-parameter-index</tt>.</p></dd>
389<dt class="definition"><strong>procedure:</strong> (step! STATEMENT) &rArr; BOOLEAN</dt>
390<dd>
391<p>Single-steps the execution of <tt>STATEMENT</tt> and returns <tt>#t</tt> if a result row was produced, <tt>#f</tt> if no further results are available as the statement has been stepped through. This procedure must be called at least once before any results can be retrieved from the statement.</p></dd>
392<dt class="definition"><strong>procedure:</strong> (column-type STATEMENT I) &rArr; SYMBOL</dt>
393<dd>
394<p>Can be applied to a statement that has just been stepped (otherwise it returns <tt>#f</tt>) and returns the SQLite type of the result column number <tt>I</tt> (counting from 0) as a symbol.</p>
395<p>The return value can be one of the symbols <tt>null</tt>, <tt>integer</tt>, <tt>float</tt>, <tt>text</tt> or <tt>blob</tt>.</p>
396<p>This procedure always succeeds and never throws an exception.</p></dd>
397<dt class="definition"><strong>procedure:</strong> (column-data STATEMENT I) &rArr; OBJECT</dt>
398<dd>
399<p>Can be applied to a statement that has just been stepped. Consults <tt>column-type</tt> and <tt>column-declared-type</tt> to determine the type of the indicated column and to return its data as an appropriate Scheme object:
400<table>
401<tr>
402<th>SQLite type</th>
403<th>Scheme type</th></tr>
404<tr>
405<td><tt>integer</tt>, declared <tt>&quot;bool&quot;</tt></td>
406<td><tt>boolean?</tt></td></tr>
407<tr>
408<td><tt>integer</tt></td>
409<td><tt>integer?</tt></td></tr>
410<tr>
411<td><tt>float</tt></td>
412<td><tt>real?</tt></td></tr>
413<tr>
414<td><tt>text</tt></td>
415<td><tt>string?</tt></td></tr>
416<tr>
417<td><tt>blob</tt></td>
418<td><tt>blob?</tt></td></tr>
419<tr>
420<td><tt>null</tt></td>
421<td><tt>(void)</tt></td></tr></table></p>
422<p>The declared type of a column is considered to be boolean if the type declaration contains the character sequence &quot;bool&quot; anywhere, ignoring case.</p>
423<p>This procedure always succeeds and never throws an exception.</p></dd>
424<dt class="definition"><strong>procedure:</strong> (reset! STATEMENT) &rArr; VOID</dt>
425<dd>
426<p>Can be applied to any statement and resets it such that execution using <tt>step!</tt> will perform all operations of the statement again.</p></dd></div>
427<div class="subsection">
428<h4>Simple statement interface</h4>
429<dt class="definition"><strong>procedure:</strong> (call-with-temporary-statements PROC DATABASE . SQLS) &rArr; OBJECT</dt>
430<dd>
431<p>Compiles the SQL sources into statements in the context of <tt>DATABASE</tt>, applies <tt>PROC</tt> to these statements and returns <tt>PROC</tt>'s result. The statements are created and finalized in <tt>dynamic-wind</tt> entry and exit blocks around the application of <tt>PROC</tt>.</p></dd>
432<dt class="definition"><strong>procedure:</strong> (execute STATEMENT . PARAMETERS) &rArr; VOID
433<br /><strong>procedure:</strong> (execute DATABASE SQL . PARAMETERS) &rArr; VOID</dt>
434<dd>
435<p>(Compiles the given SQL), resets the statement, binds the statement's free parameters and executes the statement ignoring possible results from it.</p></dd>
436<dt class="definition"><strong>procedure:</strong> (update STATEMENT . PARAMETERS) &rArr; CARDINAL-INTEGER
437<br /><strong>procedure:</strong> (update DATABASE SQL . PARAMETERS) &rArr; CARDINAL-INTEGER</dt>
438<dd>
439<p>(Compiles the given SQL), resets the statement, binds the statement's free parameters and executes the specified statement ignoring possible results from it, returning the result of applying <tt>change-count</tt> to the affected database after the execution of the statement instead.</p></dd>
440<dt class="definition"><strong>procedure:</strong> (first-result STATEMENT . PARAMETERS) &rArr; OBJECT
441<br /><strong>procedure:</strong> (first-result DATABASE SQL . PARAMETERS) &rArr; OBJECT</dt>
442<dd>
443<p>(Compiles the given SQL), resets the statement, binds the statement's free parameters and single-steps the statement once returning the value of the first column in the first result row. Resets the statement again just before returning.</p>
444<p>If the given statement does not yield any results, an <tt>(exn sqlite3)</tt> is thrown with the <tt>status</tt>-property set to <tt>done</tt>.</p></dd>
445<dt class="definition"><strong>procedure:</strong> (first-row STATEMENT . PARAMETERS) &rArr; LIST
446<br /><strong>procedure:</strong> (first-row DATABASE SQL . PARAMETERS) &rArr; LIST</dt>
447<dd>
448<p>(Compiles the given SQL), resets the statement, binds the statement's free parameters and single-steps the statement once returning all columns in the first result row as a list.</p>
449<p>If the given statement does not yield any results, an <tt>(exn sqlite3)</tt> is thrown with the <tt>status</tt>-property set to <tt>done</tt>.</p></dd>
450<dt class="definition"><strong>procedure:</strong> (fold-row PROC INIT STATEMENT . PARAMETERS) &rArr; OBJECT
451<br /><strong>procedure:</strong> (fold-row PROC INIT DATABASE SQL . PARAMETERS) &rArr; OBJECT</dt>
452<dd>
453<p>(Compiles the given SQL), resets the statement, binds the statement's free parameters and executes it step by step. After each step, the column values of the current result row are retrieved and <tt>PROC</tt> is applied to the current folded value, set to <tt>INIT</tt> in the first step, and the column values. The result of the application becomes the new folded value.</p></dd>
454<dt class="definition"><strong>procedure:</strong> (for-each-row PROC STATEMENT . PARAMETERS) &rArr; VOID
455<br /><strong>procedure:</strong> (for-each-row PROC DATABASE SQL . PARAMETERS) &rArr; VOID</dt>
456<dd>
457<p>(Compiles the given SQL), resets the statement, binds the statement's free parameters and executes it step by step. After each step, the column values of the current result row are retrieved and <tt>PROC</tt> is applied to them. The results of this application are discarded.</p></dd>
458<dt class="definition"><strong>procedure:</strong> (map-row PROC STATEMENT . PARAMETERS) &rArr; LIST
459<br /><strong>procedure:</strong> (map-row PROC DATABASE SQL . PARAMETERS) &rArr; LIST</dt>
460<dd>
461<p>(Compiles the given SQL), resets the statement, binds the statement's free parameters and executes it step by step. After each step, the column values of the current result row are retrieved and <tt>PROC</tt> is applied to them. The results of these applications are collected into a list.</p></dd>
462<div class="subsection">
463<h4>Utility functions</h4>
464<dt class="definition"><strong>procedure:</strong> (with-transaction DATABASE THUNK [TYPE]) &rArr; OBJECT</dt>
465<dd>
466<p>Runs <tt>THUNK</tt> within the scope of a transaction on the database and returns the return value from <tt>THUNK</tt>.</p>
467<p>The transaction is committed upon exit from <tt>THUNK</tt> if <tt>THUNK</tt> returns a true value. If <tt>THUNK</tt> returns a false value or throws an exception, the transaction is rolled back.</p>
468<p>The <tt>TYPE</tt> of the transaction can be specified as one of the symbols <tt>deferred</tt>(the default), <tt>immediate</tt> or <tt>exclusive</tt>.</p></dd>
469<dt class="definition"><strong>procedure:</strong> (sql-complete? SQL) &rArr; BOOLEAN</dt>
470<dd>
471<p>Checks whether <tt>SQL</tt> comprises at least one complete SQL statement.</p></dd>
472<dt class="definition"><strong>procedure:</strong> (enable-shared-cache! BOOLEAN) &rArr; VOID</dt>
473<dd>
474<p>Enables (or disables) the sharing of the database cache and schema data structures between connections to the same database.</p></dd>
475<dt class="definition"><strong>procedure:</strong> (database-version) &rArr; STRING</dt>
476<dd>
477<p>Returns a string identifying the version of SQLite in use.</p></dd></div></div></div>
478<div class="section">
479<h3>Version</h3>
480<ul>
481<li>3.2.1 Added a test suite</li>
482<li>3.2.0 Removed the unsafe busy handler and timeout APIs, since a safe API exists</li>
483<li>3.1.0 <tt>bind-parameters!</tt> can now handle keyword arguments</li>
484<li>3.0.0 Ported to CHICKEN 4, removed dependencies on TinyCLOS and EasyFFI</li>
485<li>2.0.8 Add busy handler callbacks; ensure finalize! is called on exception. [Jim Ursetto]</li>
486<li>2.0.7 Restore error reporting. [Jim Ursetto]</li>
487<li>2.0.6 Add <tt>enable-shared-cache!</tt>, requires 3.3.0 or later. [Jim Ursetto]</li>
488<li>2.0.5 Added some &lt;boolean&gt; support. Change for NULL (&lt;void&gt;) handling. [Kon Lovett]</li>
489<li>2.0.4 Added <code>sqlite3:fold-row</code> &amp; <code>sqlite3:bind-parameters!</code>. Fix for introduced bug in <code>sqlite3:changes</code>. [Kon Lovett]</li>
490<li>2.0.3 Added <code>sqlite3:null-value</code>, <code>sqlite3:null-value?</code>, and <code>sqlite3:null</code>. [Kon Lovett]</li>
491<li>2.0.2 Use of extended <tt>define-foreign-enum</tt>. Removed deprecated <tt>pointer</tt> use. [Kon Lovett]</li>
492<li>2.0.1 Deprecated <tt>&lt;byte-vector&gt;</tt>, use <tt>&lt;blob&gt;</tt> [Kon Lovett]</li>
493<li>2.0.0 Now using <tt>(void)</tt> to represent <tt>NULL</tt></li>
494<li>1.5.9 dll extension not used anymore in newer chickens [felix]</li>
495<li>1.5.8 Update for synch 1.3 [Kon Lovett]</li>
496<li>1.5.7 Updated compiler flags to pull in tinyclos and easyffi</li>
497<li>1.5.6 Replaced deprecated synch operations [Kon Lovett]</li>
498<li>1.5.5 Correction in the documentation, added sqlite3:with-transaction</li>
499<li>1.5.4 Typo fixed thanks to the new imports checking code</li>
500<li>1.5.3 Proper multithreading locks for the callback code</li>
501<li>1.5.2 Code cleanups</li>
502<li>1.5.1 Potential memory leaks removed</li>
503<li>1.5.0 Support for user defined collation sequences and functions has been added</li>
504<li>1.4.0 Stale statement handles due to schema changes are now automagically recompiled to keep them valid</li>
505<li>1.3.1 Several small routines added</li>
506<li>1.3.0 Special hacks removed as CVS version of SQLite3.3.4 has been fixed</li>
507<li>1.2.0 Special hacks to deal with &quot;valid&quot; <tt>NULL</tt> statements</li>
508<li>1.1.4 Tightened security measures against <tt>#f</tt> pointers</li>
509<li>1.1.3 Integers not fitting in a fixnum are now read correctly from the database [thanks to Zbigniew]</li>
510<li>1.1.2 Setup file patched to call compiled output .dll on Windows</li>
511<li>1.1.1 All procedures now reset prepared statements where you would do that by hand anyway</li>
512<li>1.1.0 Promoted <tt>sqlite3:call-with-temporary-statement</tt> to <tt>sqlite3:call-with-temporary-statements</tt> and fixed a really stupid coding mistake in <tt>sqlite3:changes</tt></li>
513<li>1.0.3 Fixed C compiler warnings</li>
514<li>1.0.2 Added a typecheck for increased safety</li>
515<li>1.0.1 Fixed type mistakes in the source</li>
516<li>1.0.0 Initial release</li></ul></div>
517<div class="section">
518<h3>License</h3>
519<pre id="license">Copyright (c) 2005-2009, Thomas Chust &lt;chust@web.de&gt;.  All rights reserved.
520
521Redistribution and use in source and binary forms, with or without
522modification, are permitted provided that the following conditions are met:
523
524  Redistributions of source code must retain the above copyright notice,
525  this list of conditions and the following disclaimer. Redistributions in
526  binary form must reproduce the above copyright notice, this list of
527  conditions and the following disclaimer in the documentation and/or
528  other materials provided with the distribution. Neither the name of the
529  author nor the names of its contributors may be used to endorse or
530  promote products derived from this software without specific prior
531  written permission.
532
533THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS &quot;AS
534IS&quot; AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
535THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
536PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
537CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
538EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
539PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
540PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
541LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
542NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
543SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</pre></div></div>
544<div id="footer">
545<hr /><a href="index.html">&lt; Egg index</a>
546<div id="revision-history">$Revision$ $Date$</div>&nbsp;</div></body></html>
Note: See TracBrowser for help on using the repository browser.