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.in,v 1.50 2003/07/22 09:24:44 danielk1977 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 "--VERS--" 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_--ENCODING-- 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*,...); 394char *sqlite_vmprintf(const char*, va_list); 395 396/* 397** Windows systems should call this routine to free memory that 398** is returned in the in the errmsg parameter of sqlite_open() when 399** SQLite is a DLL. For some reason, it does not work to call free() 400** directly. 401*/ 402void sqlite_freemem(void *p); 403 404/* 405** Windows systems need functions to call to return the sqlite_version 406** and sqlite_encoding strings. 407*/ 408const char *sqlite_libversion(void); 409const char *sqlite_libencoding(void); 410 411/* 412** A pointer to the following structure is used to communicate with 413** the implementations of user-defined functions. 414*/ 415typedef struct sqlite_func sqlite_func; 416 417/* 418** Use the following routines to create new user-defined functions. See 419** the documentation for details. 420*/ 421int sqlite_create_function( 422 sqlite*, /* Database where the new function is registered */ 423 const char *zName, /* Name of the new function */ 424 int nArg, /* Number of arguments. -1 means any number */ 425 void (*xFunc)(sqlite_func*,int,const char**), /* C code to implement */ 426 void *pUserData /* Available via the sqlite_user_data() call */ 427); 428int sqlite_create_aggregate( 429 sqlite*, /* Database where the new function is registered */ 430 const char *zName, /* Name of the function */ 431 int nArg, /* Number of arguments */ 432 void (*xStep)(sqlite_func*,int,const char**), /* Called for each row */ 433 void (*xFinalize)(sqlite_func*), /* Called once to get final result */ 434 void *pUserData /* Available via the sqlite_user_data() call */ 435); 436 437/* 438** Use the following routine to define the datatype returned by a 439** user-defined function. The second argument can be one of the 440** constants SQLITE_NUMERIC, SQLITE_TEXT, or SQLITE_ARGS or it 441** can be an integer greater than or equal to zero. The datatype 442** will be numeric or text (the only two types supported) if the 443** argument is SQLITE_NUMERIC or SQLITE_TEXT. If the argument is 444** SQLITE_ARGS, then the datatype is numeric if any argument to the 445** function is numeric and is text otherwise. If the second argument 446** is an integer, then the datatype of the result is the same as the 447** parameter to the function that corresponds to that integer. 448*/ 449int sqlite_function_type( 450 sqlite *db, /* The database there the function is registered */ 451 const char *zName, /* Name of the function */ 452 int datatype /* The datatype for this function */ 453); 454#define SQLITE_NUMERIC (-1) 455#define SQLITE_TEXT (-2) 456#define SQLITE_ARGS (-3) 457 458/* 459** The user function implementations call one of the following four routines 460** in order to return their results. The first parameter to each of these 461** routines is a copy of the first argument to xFunc() or xFinialize(). 462** The second parameter to these routines is the result to be returned. 463** A NULL can be passed as the second parameter to sqlite_set_result_string() 464** in order to return a NULL result. 465** 466** The 3rd argument to _string and _error is the number of characters to 467** take from the string. If this argument is negative, then all characters 468** up to and including the first '\000' are used. 469** 470** The sqlite_set_result_string() function allocates a buffer to hold the 471** result and returns a pointer to this buffer. The calling routine 472** (that is, the implmentation of a user function) can alter the content 473** of this buffer if desired. 474*/ 475char *sqlite_set_result_string(sqlite_func*,const char*,int); 476void sqlite_set_result_int(sqlite_func*,int); 477void sqlite_set_result_double(sqlite_func*,double); 478void sqlite_set_result_error(sqlite_func*,const char*,int); 479 480/* 481** The pUserData parameter to the sqlite_create_function() and 482** sqlite_create_aggregate() routines used to register user functions 483** is available to the implementation of the function using this 484** call. 485*/ 486void *sqlite_user_data(sqlite_func*); 487 488/* 489** Aggregate functions use the following routine to allocate 490** a structure for storing their state. The first time this routine 491** is called for a particular aggregate, a new structure of size nBytes 492** is allocated, zeroed, and returned. On subsequent calls (for the 493** same aggregate instance) the same buffer is returned. The implementation 494** of the aggregate can use the returned buffer to accumulate data. 495** 496** The buffer allocated is freed automatically be SQLite. 497*/ 498void *sqlite_aggregate_context(sqlite_func*, int nBytes); 499 500/* 501** The next routine returns the number of calls to xStep for a particular 502** aggregate function instance. The current call to xStep counts so this 503** routine always returns at least 1. 504*/ 505int sqlite_aggregate_count(sqlite_func*); 506 507/* 508** This routine registers a callback with the SQLite library. The 509** callback is invoked (at compile-time, not at run-time) for each 510** attempt to access a column of a table in the database. The callback 511** returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire 512** SQL statement should be aborted with an error and SQLITE_IGNORE 513** if the column should be treated as a NULL value. 514*/ 515int sqlite_set_authorizer( 516 sqlite*, 517 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), 518 void *pUserData 519); 520 521/* 522** The second parameter to the access authorization function above will 523** be one of the values below. These values signify what kind of operation 524** is to be authorized. The 3rd and 4th parameters to the authorization 525** function will be parameters or NULL depending on which of the following 526** codes is used as the second parameter. The 5th parameter is the name 527** of the database ("main", "temp", etc.) if applicable. The 6th parameter 528** is the name of the inner-most trigger or view that is responsible for 529** the access attempt or NULL if this access attempt is directly from 530** input SQL code. 531** 532** Arg-3 Arg-4 533*/ 534#define SQLITE_COPY 0 /* Table Name File Name */ 535#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ 536#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */ 537#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */ 538#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */ 539#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */ 540#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */ 541#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */ 542#define SQLITE_CREATE_VIEW 8 /* View Name NULL */ 543#define SQLITE_DELETE 9 /* Table Name NULL */ 544#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */ 545#define SQLITE_DROP_TABLE 11 /* Table Name NULL */ 546#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */ 547#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */ 548#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */ 549#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */ 550#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */ 551#define SQLITE_DROP_VIEW 17 /* View Name NULL */ 552#define SQLITE_INSERT 18 /* Table Name NULL */ 553#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */ 554#define SQLITE_READ 20 /* Table Name Column Name */ 555#define SQLITE_SELECT 21 /* NULL NULL */ 556#define SQLITE_TRANSACTION 22 /* NULL NULL */ 557#define SQLITE_UPDATE 23 /* Table Name Column Name */ 558#define SQLITE_ATTACH 24 /* Filename NULL */ 559#define SQLITE_DETACH 25 /* Database Name NULL */ 560 561 562/* 563** The return value of the authorization function should be one of the 564** following constants: 565*/ 566/* #define SQLITE_OK 0 // Allow access (This is actually defined above) */ 567#define SQLITE_DENY 1 /* Abort the SQL statement with an error */ 568#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ 569 570/* 571** Register a function that is called at every invocation of sqlite_exec() 572** or sqlite_compile(). This function can be used (for example) to generate 573** a log file of all SQL executed against a database. 574*/ 575void *sqlite_trace(sqlite*, void(*xTrace)(void*,const char*), void*); 576 577/*** The Callback-Free API 578** 579** The following routines implement a new way to access SQLite that does not 580** involve the use of callbacks. 581** 582** An sqlite_vm is an opaque object that represents a single SQL statement 583** that is ready to be executed. 584*/ 585typedef struct sqlite_vm sqlite_vm; 586 587/* 588** To execute an SQLite query without the use of callbacks, you first have 589** to compile the SQL using this routine. The 1st parameter "db" is a pointer 590** to an sqlite object obtained from sqlite_open(). The 2nd parameter 591** "zSql" is the text of the SQL to be compiled. The remaining parameters 592** are all outputs. 593** 594** *pzTail is made to point to the first character past the end of the first 595** SQL statement in zSql. This routine only compiles the first statement 596** in zSql, so *pzTail is left pointing to what remains uncompiled. 597** 598** *ppVm is left pointing to a "virtual machine" that can be used to execute 599** the compiled statement. Or if there is an error, *ppVm may be set to NULL. 600** If the input text contained no SQL (if the input is and empty string or 601** a comment) then *ppVm is set to NULL. 602** 603** If any errors are detected during compilation, an error message is written 604** into space obtained from malloc() and *pzErrMsg is made to point to that 605** error message. The calling routine is responsible for freeing the text 606** of this message when it has finished with it. Use sqlite_freemem() to 607** free the message. pzErrMsg may be NULL in which case no error message 608** will be generated. 609** 610** On success, SQLITE_OK is returned. Otherwise and error code is returned. 611*/ 612int sqlite_compile( 613 sqlite *db, /* The open database */ 614 const char *zSql, /* SQL statement to be compiled */ 615 const char **pzTail, /* OUT: uncompiled tail of zSql */ 616 sqlite_vm **ppVm, /* OUT: the virtual machine to execute zSql */ 617 char **pzErrmsg /* OUT: Error message. */ 618); 619 620/* 621** After an SQL statement has been compiled, it is handed to this routine 622** to be executed. This routine executes the statement as far as it can 623** go then returns. The return value will be one of SQLITE_DONE, 624** SQLITE_ERROR, SQLITE_BUSY, SQLITE_ROW, or SQLITE_MISUSE. 625** 626** SQLITE_DONE means that the execute of the SQL statement is complete 627** an no errors have occurred. sqlite_step() should not be called again 628** for the same virtual machine. *pN is set to the number of columns in 629** the result set and *pazColName is set to an array of strings that 630** describe the column names and datatypes. The name of the i-th column 631** is (*pazColName)[i] and the datatype of the i-th column is 632** (*pazColName)[i+*pN]. *pazValue is set to NULL. 633** 634** SQLITE_ERROR means that the virtual machine encountered a run-time 635** error. sqlite_step() should not be called again for the same 636** virtual machine. *pN is set to 0 and *pazColName and *pazValue are set 637** to NULL. Use sqlite_finalize() to obtain the specific error code 638** and the error message text for the error. 639** 640** SQLITE_BUSY means that an attempt to open the database failed because 641** another thread or process is holding a lock. The calling routine 642** can try again to open the database by calling sqlite_step() again. 643** The return code will only be SQLITE_BUSY if no busy handler is registered 644** using the sqlite_busy_handler() or sqlite_busy_timeout() routines. If 645** a busy handler callback has been registered but returns 0, then this 646** routine will return SQLITE_ERROR and sqltie_finalize() will return 647** SQLITE_BUSY when it is called. 648** 649** SQLITE_ROW means that a single row of the result is now available. 650** The data is contained in *pazValue. The value of the i-th column is 651** (*azValue)[i]. *pN and *pazColName are set as described in SQLITE_DONE. 652** Invoke sqlite_step() again to advance to the next row. 653** 654** SQLITE_MISUSE is returned if sqlite_step() is called incorrectly. 655** For example, if you call sqlite_step() after the virtual machine 656** has halted (after a prior call to sqlite_step() has returned SQLITE_DONE) 657** or if you call sqlite_step() with an incorrectly initialized virtual 658** machine or a virtual machine that has been deleted or that is associated 659** with an sqlite structure that has been closed. 660*/ 661int sqlite_step( 662 sqlite_vm *pVm, /* The virtual machine to execute */ 663 int *pN, /* OUT: Number of columns in result */ 664 const char ***pazValue, /* OUT: Column data */ 665 const char ***pazColName /* OUT: Column names and datatypes */ 666); 667 668/* 669** This routine is called to delete a virtual machine after it has finished 670** executing. The return value is the result code. SQLITE_OK is returned 671** if the statement executed successfully and some other value is returned if 672** there was any kind of error. If an error occurred and pzErrMsg is not 673** NULL, then an error message is written into memory obtained from malloc() 674** and *pzErrMsg is made to point to that error message. The calling routine 675** should use sqlite_freemem() to delete this message when it has finished 676** with it. 677** 678** This routine can be called at any point during the execution of the 679** virtual machine. If the virtual machine has not completed execution 680** when this routine is called, that is like encountering an error or 681** an interrupt. (See sqlite_interrupt().) Incomplete updates may be 682** rolled back and transactions cancelled, depending on the circumstances, 683** and the result code returned will be SQLITE_ABORT. 684*/ 685int sqlite_finalize(sqlite_vm*, char **pzErrMsg); 686 687/* 688** This routine deletes the virtual machine, writes any error message to 689** *pzErrMsg and returns an SQLite return code in the same way as the 690** sqlite_finalize() function. 691** 692** Additionally, if ppVm is not NULL, *ppVm is left pointing to a new virtual 693** machine loaded with the compiled version of the original query ready for 694** execution. 695** 696** If sqlite_reset() returns SQLITE_SCHEMA, then *ppVm is set to NULL. 697** 698******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ****** 699*/ 700int sqlite_reset(sqlite_vm *, char **pzErrMsg, sqlite_vm **ppVm); 701 702#ifdef __cplusplus 703} /* End of the 'extern "C"' block */ 704#endif 705 706#endif /* _SQLITE_H_ */ 707