monotone

monotone Mtn Source Tree

Root/sqlite/sqlite.h

1/*
2** 2001 September 15
3**
4** The author disclaims copyright to this source code. In place of
5** a legal notice, here is a blessing:
6**
7** May you do good and not evil.
8** May you find forgiveness for yourself and forgive others.
9** May you share freely, never taking more than you give.
10**
11*************************************************************************
12** This header file defines the interface that the SQLite library
13** presents to client programs.
14**
15** @(#) $Id: sqlite.h,v 1.1 2003/08/05 23:03:07 graydon Exp $
16*/
17#ifndef _SQLITE_H_
18#define _SQLITE_H_
19#include <stdarg.h> /* Needed for the definition of va_list */
20
21/*
22** Make sure we can call this stuff from C++.
23*/
24#ifdef __cplusplus
25extern "C" {
26#endif
27
28/*
29** The version of the SQLite library.
30*/
31#define SQLITE_VERSION "2.8.3"
32
33/*
34** The version string is also compiled into the library so that a program
35** can check to make sure that the lib*.a file and the *.h file are from
36** the same version.
37*/
38extern const char sqlite_version[];
39
40/*
41** The SQLITE_UTF8 macro is defined if the library expects to see
42** UTF-8 encoded data. The SQLITE_ISO8859 macro is defined if the
43** iso8859 encoded should be used.
44*/
45#define SQLITE_ISO8859 1
46
47/*
48** The following constant holds one of two strings, "UTF-8" or "iso8859",
49** depending on which character encoding the SQLite library expects to
50** see. The character encoding makes a difference for the LIKE and GLOB
51** operators and for the LENGTH() and SUBSTR() functions.
52*/
53extern const char sqlite_encoding[];
54
55/*
56** Each open sqlite database is represented by an instance of the
57** following opaque structure.
58*/
59typedef struct sqlite sqlite;
60
61/*
62** A function to open a new sqlite database.
63**
64** If the database does not exist and mode indicates write
65** permission, then a new database is created. If the database
66** does not exist and mode does not indicate write permission,
67** then the open fails, an error message generated (if errmsg!=0)
68** and the function returns 0.
69**
70** If mode does not indicates user write permission, then the
71** database is opened read-only.
72**
73** The Truth: As currently implemented, all databases are opened
74** for writing all the time. Maybe someday we will provide the
75** ability to open a database readonly. The mode parameters is
76** provided in anticipation of that enhancement.
77*/
78sqlite *sqlite_open(const char *filename, int mode, char **errmsg);
79
80/*
81** A function to close the database.
82**
83** Call this function with a pointer to a structure that was previously
84** returned from sqlite_open() and the corresponding database will by closed.
85*/
86void sqlite_close(sqlite *);
87
88/*
89** The type for a callback function.
90*/
91typedef int (*sqlite_callback)(void*,int,char**, char**);
92
93/*
94** A function to executes one or more statements of SQL.
95**
96** If one or more of the SQL statements are queries, then
97** the callback function specified by the 3rd parameter is
98** invoked once for each row of the query result. This callback
99** should normally return 0. If the callback returns a non-zero
100** value then the query is aborted, all subsequent SQL statements
101** are skipped and the sqlite_exec() function returns the SQLITE_ABORT.
102**
103** The 4th parameter is an arbitrary pointer that is passed
104** to the callback function as its first parameter.
105**
106** The 2nd parameter to the callback function is the number of
107** columns in the query result. The 3rd parameter to the callback
108** is an array of strings holding the values for each column.
109** The 4th parameter to the callback is an array of strings holding
110** the names of each column.
111**
112** The callback function may be NULL, even for queries. A NULL
113** callback is not an error. It just means that no callback
114** will be invoked.
115**
116** If an error occurs while parsing or evaluating the SQL (but
117** not while executing the callback) then an appropriate error
118** message is written into memory obtained from malloc() and
119** *errmsg is made to point to that message. The calling function
120** is responsible for freeing the memory that holds the error
121** message. Use sqlite_freemem() for this. If errmsg==NULL,
122** then no error message is ever written.
123**
124** The return value is is SQLITE_OK if there are no errors and
125** some other return code if there is an error. The particular
126** return value depends on the type of error.
127**
128** If the query could not be executed because a database file is
129** locked or busy, then this function returns SQLITE_BUSY. (This
130** behavior can be modified somewhat using the sqlite_busy_handler()
131** and sqlite_busy_timeout() functions below.)
132*/
133int sqlite_exec(
134 sqlite*, /* An open database */
135 const char *sql, /* SQL to be executed */
136 sqlite_callback, /* Callback function */
137 void *, /* 1st argument to callback function */
138 char **errmsg /* Error msg written here */
139);
140
141/*
142** Return values for sqlite_exec() and sqlite_step()
143*/
144#define SQLITE_OK 0 /* Successful result */
145#define SQLITE_ERROR 1 /* SQL error or missing database */
146#define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */
147#define SQLITE_PERM 3 /* Access permission denied */
148#define SQLITE_ABORT 4 /* Callback routine requested an abort */
149#define SQLITE_BUSY 5 /* The database file is locked */
150#define SQLITE_LOCKED 6 /* A table in the database is locked */
151#define SQLITE_NOMEM 7 /* A malloc() failed */
152#define SQLITE_READONLY 8 /* Attempt to write a readonly database */
153#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite_interrupt() */
154#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
155#define SQLITE_CORRUPT 11 /* The database disk image is malformed */
156#define SQLITE_NOTFOUND 12 /* (Internal Only) Table or record not found */
157#define SQLITE_FULL 13 /* Insertion failed because database is full */
158#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
159#define SQLITE_PROTOCOL 15 /* Database lock protocol error */
160#define SQLITE_EMPTY 16 /* (Internal Only) Database table is empty */
161#define SQLITE_SCHEMA 17 /* The database schema changed */
162#define SQLITE_TOOBIG 18 /* Too much data for one row of a table */
163#define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */
164#define SQLITE_MISMATCH 20 /* Data type mismatch */
165#define SQLITE_MISUSE 21 /* Library used incorrectly */
166#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
167#define SQLITE_AUTH 23 /* Authorization denied */
168#define SQLITE_FORMAT 24 /* Auxiliary database format error */
169#define SQLITE_ROW 100 /* sqlite_step() has another row ready */
170#define SQLITE_DONE 101 /* sqlite_step() has finished executing */
171
172/*
173** Each entry in an SQLite table has a unique integer key. (The key is
174** the value of the INTEGER PRIMARY KEY column if there is such a column,
175** otherwise the key is generated at random. The unique key is always
176** available as the ROWID, OID, or _ROWID_ column.) The following routine
177** returns the integer key of the most recent insert in the database.
178**
179** This function is similar to the mysql_insert_id() function from MySQL.
180*/
181int sqlite_last_insert_rowid(sqlite*);
182
183/*
184** This function returns the number of database rows that were changed
185** (or inserted or deleted) by the most recent called sqlite_exec().
186**
187** All changes are counted, even if they were later undone by a
188** ROLLBACK or ABORT. Except, changes associated with creating and
189** dropping tables are not counted.
190**
191** If a callback invokes sqlite_exec() recursively, then the changes
192** in the inner, recursive call are counted together with the changes
193** in the outer call.
194**
195** SQLite implements the command "DELETE FROM table" without a WHERE clause
196** by dropping and recreating the table. (This is much faster than going
197** through and deleting individual elements form the table.) Because of
198** this optimization, the change count for "DELETE FROM table" will be
199** zero regardless of the number of elements that were originally in the
200** table. To get an accurate count of the number of rows deleted, use
201** "DELETE FROM table WHERE 1" instead.
202*/
203int sqlite_changes(sqlite*);
204
205/* If the parameter to this routine is one of the return value constants
206** defined above, then this routine returns a constant text string which
207** descripts (in English) the meaning of the return value.
208*/
209const char *sqlite_error_string(int);
210#define sqliteErrStr sqlite_error_string /* Legacy. Do not use in new code. */
211
212/* This function causes any pending database operation to abort and
213** return at its earliest opportunity. This routine is typically
214** called in response to a user action such as pressing "Cancel"
215** or Ctrl-C where the user wants a long query operation to halt
216** immediately.
217*/
218void sqlite_interrupt(sqlite*);
219
220
221/* This function returns true if the given input string comprises
222** one or more complete SQL statements.
223**
224** The algorithm is simple. If the last token other than spaces
225** and comments is a semicolon, then return true. otherwise return
226** false.
227*/
228int sqlite_complete(const char *sql);
229
230/*
231** This routine identifies a callback function that is invoked
232** whenever an attempt is made to open a database table that is
233** currently locked by another process or thread. If the busy callback
234** is NULL, then sqlite_exec() returns SQLITE_BUSY immediately if
235** it finds a locked table. If the busy callback is not NULL, then
236** sqlite_exec() invokes the callback with three arguments. The
237** second argument is the name of the locked table and the third
238** argument is the number of times the table has been busy. If the
239** busy callback returns 0, then sqlite_exec() immediately returns
240** SQLITE_BUSY. If the callback returns non-zero, then sqlite_exec()
241** tries to open the table again and the cycle repeats.
242**
243** The default busy callback is NULL.
244**
245** Sqlite is re-entrant, so the busy handler may start a new query.
246** (It is not clear why anyone would every want to do this, but it
247** is allowed, in theory.) But the busy handler may not close the
248** database. Closing the database from a busy handler will delete
249** data structures out from under the executing query and will
250** probably result in a coredump.
251*/
252void sqlite_busy_handler(sqlite*, int(*)(void*,const char*,int), void*);
253
254/*
255** This routine sets a busy handler that sleeps for a while when a
256** table is locked. The handler will sleep multiple times until
257** at least "ms" milleseconds of sleeping have been done. After
258** "ms" milleseconds of sleeping, the handler returns 0 which
259** causes sqlite_exec() to return SQLITE_BUSY.
260**
261** Calling this routine with an argument less than or equal to zero
262** turns off all busy handlers.
263*/
264void sqlite_busy_timeout(sqlite*, int ms);
265
266/*
267** This next routine is really just a wrapper around sqlite_exec().
268** Instead of invoking a user-supplied callback for each row of the
269** result, this routine remembers each row of the result in memory
270** obtained from malloc(), then returns all of the result after the
271** query has finished.
272**
273** As an example, suppose the query result where this table:
274**
275** Name | Age
276** -----------------------
277** Alice | 43
278** Bob | 28
279** Cindy | 21
280**
281** If the 3rd argument were &azResult then after the function returns
282** azResult will contain the following data:
283**
284** azResult[0] = "Name";
285** azResult[1] = "Age";
286** azResult[2] = "Alice";
287** azResult[3] = "43";
288** azResult[4] = "Bob";
289** azResult[5] = "28";
290** azResult[6] = "Cindy";
291** azResult[7] = "21";
292**
293** Notice that there is an extra row of data containing the column
294** headers. But the *nrow return value is still 3. *ncolumn is
295** set to 2. In general, the number of values inserted into azResult
296** will be ((*nrow) + 1)*(*ncolumn).
297**
298** After the calling function has finished using the result, it should
299** pass the result data pointer to sqlite_free_table() in order to
300** release the memory that was malloc-ed. Because of the way the
301** malloc() happens, the calling function must not try to call
302** malloc() directly. Only sqlite_free_table() is able to release
303** the memory properly and safely.
304**
305** The return value of this routine is the same as from sqlite_exec().
306*/
307int sqlite_get_table(
308 sqlite*, /* An open database */
309 const char *sql, /* SQL to be executed */
310 char ***resultp, /* Result written to a char *[] that this points to */
311 int *nrow, /* Number of result rows written here */
312 int *ncolumn, /* Number of result columns written here */
313 char **errmsg /* Error msg written here */
314);
315
316/*
317** Call this routine to free the memory that sqlite_get_table() allocated.
318*/
319void sqlite_free_table(char **result);
320
321/*
322** The following routines are wrappers around sqlite_exec() and
323** sqlite_get_table(). The only difference between the routines that
324** follow and the originals is that the second argument to the
325** routines that follow is really a printf()-style format
326** string describing the SQL to be executed. Arguments to the format
327** string appear at the end of the argument list.
328**
329** All of the usual printf formatting options apply. In addition, there
330** is a "%q" option. %q works like %s in that it substitutes a null-terminated
331** string from the argument list. But %q also doubles every '\'' character.
332** %q is designed for use inside a string literal. By doubling each '\''
333** character it escapes that character and allows it to be inserted into
334** the string.
335**
336** For example, so some string variable contains text as follows:
337**
338** char *zText = "It's a happy day!";
339**
340** We can use this text in an SQL statement as follows:
341**
342** sqlite_exec_printf(db, "INSERT INTO table VALUES('%q')",
343** callback1, 0, 0, zText);
344**
345** Because the %q format string is used, the '\'' character in zText
346** is escaped and the SQL generated is as follows:
347**
348** INSERT INTO table1 VALUES('It''s a happy day!')
349**
350** This is correct. Had we used %s instead of %q, the generated SQL
351** would have looked like this:
352**
353** INSERT INTO table1 VALUES('It's a happy day!');
354**
355** This second example is an SQL syntax error. As a general rule you
356** should always use %q instead of %s when inserting text into a string
357** literal.
358*/
359int sqlite_exec_printf(
360 sqlite*, /* An open database */
361 const char *sqlFormat, /* printf-style format string for the SQL */
362 sqlite_callback, /* Callback function */
363 void *, /* 1st argument to callback function */
364 char **errmsg, /* Error msg written here */
365 ... /* Arguments to the format string. */
366);
367int sqlite_exec_vprintf(
368 sqlite*, /* An open database */
369 const char *sqlFormat, /* printf-style format string for the SQL */
370 sqlite_callback, /* Callback function */
371 void *, /* 1st argument to callback function */
372 char **errmsg, /* Error msg written here */
373 va_list ap /* Arguments to the format string. */
374);
375int sqlite_get_table_printf(
376 sqlite*, /* An open database */
377 const char *sqlFormat, /* printf-style format string for the SQL */
378 char ***resultp, /* Result written to a char *[] that this points to */
379 int *nrow, /* Number of result rows written here */
380 int *ncolumn, /* Number of result columns written here */
381 char **errmsg, /* Error msg written here */
382 ... /* Arguments to the format string */
383);
384int sqlite_get_table_vprintf(
385 sqlite*, /* An open database */
386 const char *sqlFormat, /* printf-style format string for the SQL */
387 char ***resultp, /* Result written to a char *[] that this points to */
388 int *nrow, /* Number of result rows written here */
389 int *ncolumn, /* Number of result columns written here */
390 char **errmsg, /* Error msg written here */
391 va_list ap /* Arguments to the format string */
392);
393char *sqlite_mprintf(const char*,...);
394
395/*
396** Windows systems should call this routine to free memory that
397** is returned in the in the errmsg parameter of sqlite_open() when
398** SQLite is a DLL. For some reason, it does not work to call free()
399** directly.
400*/
401void sqlite_freemem(void *p);
402
403/*
404** Windows systems need functions to call to return the sqlite_version
405** and sqlite_encoding strings.
406*/
407const char *sqlite_libversion(void);
408const char *sqlite_libencoding(void);
409
410/*
411** A pointer to the following structure is used to communicate with
412** the implementations of user-defined functions.
413*/
414typedef struct sqlite_func sqlite_func;
415
416/*
417** Use the following routines to create new user-defined functions. See
418** the documentation for details.
419*/
420int sqlite_create_function(
421 sqlite*, /* Database where the new function is registered */
422 const char *zName, /* Name of the new function */
423 int nArg, /* Number of arguments. -1 means any number */
424 void (*xFunc)(sqlite_func*,int,const char**), /* C code to implement */
425 void *pUserData /* Available via the sqlite_user_data() call */
426);
427int sqlite_create_aggregate(
428 sqlite*, /* Database where the new function is registered */
429 const char *zName, /* Name of the function */
430 int nArg, /* Number of arguments */
431 void (*xStep)(sqlite_func*,int,const char**), /* Called for each row */
432 void (*xFinalize)(sqlite_func*), /* Called once to get final result */
433 void *pUserData /* Available via the sqlite_user_data() call */
434);
435
436/*
437** Use the following routine to define the datatype returned by a
438** user-defined function. The second argument can be one of the
439** constants SQLITE_NUMERIC, SQLITE_TEXT, or SQLITE_ARGS or it
440** can be an integer greater than or equal to zero. The datatype
441** will be numeric or text (the only two types supported) if the
442** argument is SQLITE_NUMERIC or SQLITE_TEXT. If the argument is
443** SQLITE_ARGS, then the datatype is numeric if any argument to the
444** function is numeric and is text otherwise. If the second argument
445** is an integer, then the datatype of the result is the same as the
446** parameter to the function that corresponds to that integer.
447*/
448int sqlite_function_type(
449 sqlite *db, /* The database there the function is registered */
450 const char *zName, /* Name of the function */
451 int datatype /* The datatype for this function */
452);
453#define SQLITE_NUMERIC (-1)
454#define SQLITE_TEXT (-2)
455#define SQLITE_ARGS (-3)
456
457/*
458** The user function implementations call one of the following four routines
459** in order to return their results. The first parameter to each of these
460** routines is a copy of the first argument to xFunc() or xFinialize().
461** The second parameter to these routines is the result to be returned.
462** A NULL can be passed as the second parameter to sqlite_set_result_string()
463** in order to return a NULL result.
464**
465** The 3rd argument to _string and _error is the number of characters to
466** take from the string. If this argument is negative, then all characters
467** up to and including the first '\000' are used.
468**
469** The sqlite_set_result_string() function allocates a buffer to hold the
470** result and returns a pointer to this buffer. The calling routine
471** (that is, the implmentation of a user function) can alter the content
472** of this buffer if desired.
473*/
474char *sqlite_set_result_string(sqlite_func*,const char*,int);
475void sqlite_set_result_int(sqlite_func*,int);
476void sqlite_set_result_double(sqlite_func*,double);
477void sqlite_set_result_error(sqlite_func*,const char*,int);
478
479/*
480** The pUserData parameter to the sqlite_create_function() and
481** sqlite_create_aggregate() routines used to register user functions
482** is available to the implementation of the function using this
483** call.
484*/
485void *sqlite_user_data(sqlite_func*);
486
487/*
488** Aggregate functions use the following routine to allocate
489** a structure for storing their state. The first time this routine
490** is called for a particular aggregate, a new structure of size nBytes
491** is allocated, zeroed, and returned. On subsequent calls (for the
492** same aggregate instance) the same buffer is returned. The implementation
493** of the aggregate can use the returned buffer to accumulate data.
494**
495** The buffer allocated is freed automatically be SQLite.
496*/
497void *sqlite_aggregate_context(sqlite_func*, int nBytes);
498
499/*
500** The next routine returns the number of calls to xStep for a particular
501** aggregate function instance. The current call to xStep counts so this
502** routine always returns at least 1.
503*/
504int sqlite_aggregate_count(sqlite_func*);
505
506/*
507** This routine registers a callback with the SQLite library. The
508** callback is invoked (at compile-time, not at run-time) for each
509** attempt to access a column of a table in the database. The callback
510** returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire
511** SQL statement should be aborted with an error and SQLITE_IGNORE
512** if the column should be treated as a NULL value.
513*/
514int sqlite_set_authorizer(
515 sqlite*,
516 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
517 void *pUserData
518);
519
520/*
521** The second parameter to the access authorization function above will
522** be one of the values below. These values signify what kind of operation
523** is to be authorized. The 3rd and 4th parameters to the authorization
524** function will be parameters or NULL depending on which of the following
525** codes is used as the second parameter. The 5th parameter is the name
526** of the database ("main", "temp", etc.) if applicable. The 6th parameter
527** is the name of the inner-most trigger or view that is responsible for
528** the access attempt or NULL if this access attempt is directly from
529** input SQL code.
530**
531** Arg-3 Arg-4
532*/
533#define SQLITE_COPY 0 /* Table Name File Name */
534#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
535#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
536#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
537#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
538#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
539#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
540#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
541#define SQLITE_CREATE_VIEW 8 /* View Name NULL */
542#define SQLITE_DELETE 9 /* Table Name NULL */
543#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
544#define SQLITE_DROP_TABLE 11 /* Table Name NULL */
545#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
546#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
547#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
548#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
549#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
550#define SQLITE_DROP_VIEW 17 /* View Name NULL */
551#define SQLITE_INSERT 18 /* Table Name NULL */
552#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
553#define SQLITE_READ 20 /* Table Name Column Name */
554#define SQLITE_SELECT 21 /* NULL NULL */
555#define SQLITE_TRANSACTION 22 /* NULL NULL */
556#define SQLITE_UPDATE 23 /* Table Name Column Name */
557
558/*
559** The return value of the authorization function should be one of the
560** following constants:
561*/
562/* #define SQLITE_OK 0 // Allow access (This is actually defined above) */
563#define SQLITE_DENY 1 /* Abort the SQL statement with an error */
564#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
565
566/*
567** Register a function that is called at every invocation of sqlite_exec()
568** or sqlite_compile(). This function can be used (for example) to generate
569** a log file of all SQL executed against a database.
570*/
571void *sqlite_trace(sqlite*, void(*xTrace)(void*,const char*), void*);
572
573/*** The Callback-Free API
574**
575** The following routines implement a new way to access SQLite that does not
576** involve the use of callbacks.
577**
578** An sqlite_vm is an opaque object that represents a single SQL statement
579** that is ready to be executed.
580*/
581typedef struct sqlite_vm sqlite_vm;
582
583/*
584** To execute an SQLite query without the use of callbacks, you first have
585** to compile the SQL using this routine. The 1st parameter "db" is a pointer
586** to an sqlite object obtained from sqlite_open(). The 2nd parameter
587** "zSql" is the text of the SQL to be compiled. The remaining parameters
588** are all outputs.
589**
590** *pzTail is made to point to the first character past the end of the first
591** SQL statement in zSql. This routine only compiles the first statement
592** in zSql, so *pzTail is left pointing to what remains uncompiled.
593**
594** *ppVm is left pointing to a "virtual machine" that can be used to execute
595** the compiled statement. Or if there is an error, *ppVm may be set to NULL.
596** If the input text contained no SQL (if the input is and empty string or
597** a comment) then *ppVm is set to NULL.
598**
599** If any errors are detected during compilation, an error message is written
600** into space obtained from malloc() and *pzErrMsg is made to point to that
601** error message. The calling routine is responsible for freeing the text
602** of this message when it has finished with it. Use sqlite_freemem() to
603** free the message. pzErrMsg may be NULL in which case no error message
604** will be generated.
605**
606** On success, SQLITE_OK is returned. Otherwise and error code is returned.
607*/
608int sqlite_compile(
609 sqlite *db, /* The open database */
610 const char *zSql, /* SQL statement to be compiled */
611 const char **pzTail, /* OUT: uncompiled tail of zSql */
612 sqlite_vm **ppVm, /* OUT: the virtual machine to execute zSql */
613 char **pzErrmsg /* OUT: Error message. */
614);
615
616/*
617** After an SQL statement has been compiled, it is handed to this routine
618** to be executed. This routine executes the statement as far as it can
619** go then returns. The return value will be one of SQLITE_DONE,
620** SQLITE_ERROR, SQLITE_BUSY, SQLITE_ROW, or SQLITE_MISUSE.
621**
622** SQLITE_DONE means that the execute of the SQL statement is complete
623** an no errors have occurred. sqlite_step() should not be called again
624** for the same virtual machine. *pN is set to the number of columns in
625** the result set and *pazColName is set to an array of strings that
626** describe the column names and datatypes. The name of the i-th column
627** is (*pazColName)[i] and the datatype of the i-th column is
628** (*pazColName)[i+*pN]. *pazValue is set to NULL.
629**
630** SQLITE_ERROR means that the virtual machine encountered a run-time
631** error. sqlite_step() should not be called again for the same
632** virtual machine. *pN is set to 0 and *pazColName and *pazValue are set
633** to NULL. Use sqlite_finalize() to obtain the specific error code
634** and the error message text for the error.
635**
636** SQLITE_BUSY means that an attempt to open the database failed because
637** another thread or process is holding a lock. The calling routine
638** can try again to open the database by calling sqlite_step() again.
639** The return code will only be SQLITE_BUSY if no busy handler is registered
640** using the sqlite_busy_handler() or sqlite_busy_timeout() routines. If
641** a busy handler callback has been registered but returns 0, then this
642** routine will return SQLITE_ERROR and sqltie_finalize() will return
643** SQLITE_BUSY when it is called.
644**
645** SQLITE_ROW means that a single row of the result is now available.
646** The data is contained in *pazValue. The value of the i-th column is
647** (*azValue)[i]. *pN and *pazColName are set as described in SQLITE_DONE.
648** Invoke sqlite_step() again to advance to the next row.
649**
650** SQLITE_MISUSE is returned if sqlite_step() is called incorrectly.
651** For example, if you call sqlite_step() after the virtual machine
652** has halted (after a prior call to sqlite_step() has returned SQLITE_DONE)
653** or if you call sqlite_step() with an incorrectly initialized virtual
654** machine or a virtual machine that has been deleted or that is associated
655** with an sqlite structure that has been closed.
656*/
657int sqlite_step(
658 sqlite_vm *pVm, /* The virtual machine to execute */
659 int *pN, /* OUT: Number of columns in result */
660 const char ***pazValue, /* OUT: Column data */
661 const char ***pazColName /* OUT: Column names and datatypes */
662);
663
664/*
665** This routine is called to delete a virtual machine after it has finished
666** executing. The return value is the result code. SQLITE_OK is returned
667** if the statement executed successfully and some other value is returned if
668** there was any kind of error. If an error occurred and pzErrMsg is not
669** NULL, then an error message is written into memory obtained from malloc()
670** and *pzErrMsg is made to point to that error message. The calling routine
671** should use sqlite_freemem() to delete this message when it has finished
672** with it.
673**
674** This routine can be called at any point during the execution of the
675** virtual machine. If the virtual machine has not completed execution
676** when this routine is called, that is like encountering an error or
677** an interrupt. (See sqlite_interrupt().) Incomplete updates may be
678** rolled back and transactions cancelled, depending on the circumstances,
679** and the result code returned will be SQLITE_ABORT.
680*/
681int sqlite_finalize(sqlite_vm*, char **pzErrMsg);
682
683#ifdef __cplusplus
684} /* End of the 'extern "C"' block */
685#endif
686
687#endif /* _SQLITE_H_ */

Archive Download this file

Branches

Tags

Quick Links:     www.monotone.ca    -     Downloads    -     Documentation    -     Wiki    -     Code Forge    -     Build Status