0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 ms copyright to
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a . In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d sing:.**.** M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 nd not evil..**
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 May you find
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 forgiveness for
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 give others..**
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aking more than
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 0a 2a 2a 0a 2a 2a 20 40 rograms..**.** @
01e0: 28 23 29 20 24 49 64 3a 20 73 71 6c 69 74 65 33 (#) $Id: sqlite3
01f0: 2e 68 2c 76 20 31 2e 31 35 20 32 30 30 36 2f 30 .h,v 1.15 2006/0
0200: 31 2f 31 32 20 32 30 3a 35 34 3a 30 37 20 72 6d 1/12 20:54:07 rm
0210: 73 69 6d 70 73 6f 6e 20 45 78 70 20 24 0a 2a 2f simpson Exp $.*/
0220: 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 .#ifndef _SQLITE
0230: 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 3_H_.#define _SQ
0240: 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 LITE3_H_.#includ
0250: 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 e <stdarg.h>
0260: 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 /* Needed for t
0270: 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 he definition of
0280: 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a va_list */../*.
0290: 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 ** Make sure we
02a0: 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 can call this st
02b0: 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f uff from C++..*/
02c0: 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 .#ifdef __cplusp
02d0: 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b lus.extern "C" {
02e0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 .#endif../*.** T
02f0: 68 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 he version of th
0300: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
0310: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 ..*/.#ifdef SQLI
0320: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 TE_VERSION.# und
0330: 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f ef SQLITE_VERSIO
0340: 4e 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 N.#endif.#define
0350: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 SQLITE_VERSION
0360: 20 20 20 20 20 20 20 20 22 33 2e 33 2e 30 22 0a "3.3.0".
0370: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 66 6f 72 6d 61 ./*.** The forma
0380: 74 20 6f 66 20 74 68 65 20 76 65 72 73 69 6f 6e t of the version
0390: 20 73 74 72 69 6e 67 20 69 73 20 22 58 2e 59 2e string is "X.Y.
03a0: 5a 3c 74 72 61 69 6c 69 6e 67 20 73 74 72 69 6e Z<trailing strin
03b0: 67 3e 22 2c 20 77 68 65 72 65 0a 2a 2a 20 58 20 g>", where.** X
03c0: 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 is the major ver
03d0: 73 69 6f 6e 20 6e 75 6d 62 65 72 2c 20 59 20 69 sion number, Y i
03e0: 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 s the minor vers
03f0: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a ion number and Z
0400: 0a 2a 2a 20 69 73 20 74 68 65 20 72 65 6c 65 61 .** is the relea
0410: 73 65 20 6e 75 6d 62 65 72 2e 20 54 68 65 20 74 se number. The t
0420: 72 61 69 6c 69 6e 67 20 73 74 72 69 6e 67 20 69 railing string i
0430: 73 20 6f 66 74 65 6e 20 22 61 6c 70 68 61 22 20 s often "alpha"
0440: 6f 72 20 22 62 65 74 61 22 2e 0a 2a 2a 20 46 6f or "beta"..** Fo
0450: 72 20 65 78 61 6d 70 6c 65 20 22 33 2e 31 2e 31 r example "3.1.1
0460: 62 65 74 61 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 beta"..**.** The
0470: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f SQLITE_VERSION_
0480: 4e 55 4d 42 45 52 20 69 73 20 61 6e 20 69 6e 74 NUMBER is an int
0490: 65 67 65 72 20 77 69 74 68 20 74 68 65 20 76 61 eger with the va
04a0: 6c 75 65 20 0a 2a 2a 20 28 58 2a 31 30 30 30 30 lue .** (X*10000
04b0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 2e 0 + Y*1000 + Z).
04c0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 66 6f For example, fo
04d0: 72 20 76 65 72 73 69 6f 6e 20 22 33 2e 31 2e 31 r version "3.1.1
04e0: 62 65 74 61 22 2c 20 0a 2a 2a 20 53 51 4c 49 54 beta", .** SQLIT
04f0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
0500: 20 69 73 20 73 65 74 20 74 6f 20 33 30 30 31 30 is set to 30010
0510: 30 31 2e 20 54 6f 20 64 65 74 65 63 74 20 69 66 01. To detect if
0520: 20 74 68 65 79 20 61 72 65 20 75 73 69 6e 67 20 they are using
0530: 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 31 2e .** version 3.1.
0540: 31 20 6f 72 20 67 72 65 61 74 65 72 20 61 74 20 1 or greater at
0550: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2c 20 70 72 compile time, pr
0560: 6f 67 72 61 6d 73 20 6d 61 79 20 75 73 65 20 74 ograms may use t
0570: 68 65 20 74 65 73 74 20 0a 2a 2a 20 28 53 51 4c he test .** (SQL
0580: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
0590: 45 52 3e 3d 33 30 30 31 30 30 31 29 2e 0a 2a 2f ER>=3001001)..*/
05a0: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 .#ifdef SQLITE_V
05b0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 ERSION_NUMBER.#
05c0: 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 undef SQLITE_VER
05d0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 SION_NUMBER.#end
05e0: 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 if.#define SQLIT
05f0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
0600: 20 33 30 30 33 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 3003000../*.**
0610: 54 68 65 20 76 65 72 73 69 6f 6e 20 73 74 72 69 The version stri
0620: 6e 67 20 69 73 20 61 6c 73 6f 20 63 6f 6d 70 69 ng is also compi
0630: 6c 65 64 20 69 6e 74 6f 20 74 68 65 20 6c 69 62 led into the lib
0640: 72 61 72 79 20 73 6f 20 74 68 61 74 20 61 20 70 rary so that a p
0650: 72 6f 67 72 61 6d 0a 2a 2a 20 63 61 6e 20 63 68 rogram.** can ch
0660: 65 63 6b 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 eck to make sure
0670: 20 74 68 61 74 20 74 68 65 20 6c 69 62 2a 2e 61 that the lib*.a
0680: 20 66 69 6c 65 20 61 6e 64 20 74 68 65 20 2a 2e file and the *.
0690: 68 20 66 69 6c 65 20 61 72 65 20 66 72 6f 6d 0a h file are from.
06a0: 2a 2a 20 74 68 65 20 73 61 6d 65 20 76 65 72 73 ** the same vers
06b0: 69 6f 6e 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ion. The sqlite
06c0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 3_libversion() f
06d0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
06e0: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 a pointer.** to
06f0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 the sqlite3_vers
0700: 69 6f 6e 20 76 61 72 69 61 62 6c 65 20 2d 20 75 ion variable - u
0710: 73 65 66 75 6c 20 69 6e 20 44 4c 4c 73 20 77 68 seful in DLLs wh
0720: 69 63 68 20 63 61 6e 6e 6f 74 20 61 63 63 65 73 ich cannot acces
0730: 73 0a 2a 2a 20 67 6c 6f 62 61 6c 20 76 61 72 69 s.** global vari
0740: 61 62 6c 65 73 2e 0a 2a 2f 0a 65 78 74 65 72 6e ables..*/.extern
0750: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 const char sqli
0760: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 te3_version[];.c
0770: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
0780: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f e3_libversion(vo
0790: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 52 65 74 75 id);../*.** Retu
07a0: 72 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 rn the value of
07b0: 74 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 the SQLITE_VERSI
07c0: 4f 4e 5f 4e 55 4d 42 45 52 20 6d 61 63 72 6f 20 ON_NUMBER macro
07d0: 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 69 62 72 when the.** libr
07e0: 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 ary was compiled
07f0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
0800: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
0810: 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a er(void);../*.**
0820: 20 45 61 63 68 20 6f 70 65 6e 20 73 71 6c 69 74 Each open sqlit
0830: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 e database is re
0840: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 6e 20 presented by an
0850: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 0a instance of the.
0860: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 6f 70 61 ** following opa
0870: 71 75 65 20 73 74 72 75 63 74 75 72 65 2e 0a 2a que structure..*
0880: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
0890: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 sqlite3 sqlite3
08a0: 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 53 6f 6d 65 20 63 ;.../*.** Some c
08b0: 6f 6d 70 69 6c 65 72 73 20 64 6f 20 6e 6f 74 20 ompilers do not
08c0: 73 75 70 70 6f 72 74 20 74 68 65 20 22 6c 6f 6e support the "lon
08d0: 67 20 6c 6f 6e 67 22 20 64 61 74 61 74 79 70 65 g long" datatype
08e0: 2e 20 20 53 6f 20 77 65 20 68 61 76 65 0a 2a 2a . So we have.**
08f0: 20 74 6f 20 64 6f 20 61 20 74 79 70 65 64 65 66 to do a typedef
0900: 20 74 68 61 74 20 66 6f 72 20 36 34 2d 62 69 74 that for 64-bit
0910: 20 69 6e 74 65 67 65 72 73 20 74 68 61 74 20 64 integers that d
0920: 65 70 65 6e 64 73 20 6f 6e 20 77 68 61 74 20 63 epends on what c
0930: 6f 6d 70 69 6c 65 72 0a 2a 2a 20 69 73 20 62 65 ompiler.** is be
0940: 69 6e 67 20 75 73 65 64 2e 0a 2a 2f 0a 23 69 66 ing used..*/.#if
0950: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 defined(_MSC_VE
0960: 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f R) || defined(__
0970: 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 BORLANDC__). ty
0980: 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 pedef __int64 sq
0990: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 lite_int64;. ty
09a0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f pedef unsigned _
09b0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 _int64 sqlite_ui
09c0: 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 nt64;.#else. ty
09d0: 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 pedef long long
09e0: 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 int sqlite_int64
09f0: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 ;. typedef unsi
0a00: 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 gned long long i
0a10: 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 nt sqlite_uint64
0a20: 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 ;.#endif../*.**
0a30: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 If compiling for
0a40: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 a processor tha
0a50: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 t lacks floating
0a60: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a point support,.
0a70: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e ** substitute in
0a80: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 teger for floati
0a90: 6e 67 2d 70 6f 69 6e 74 0a 2a 2f 0a 23 69 66 64 ng-point.*/.#ifd
0aa0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 ef SQLITE_OMIT_F
0ab0: 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 LOATING_POINT.#
0ac0: 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 define double sq
0ad0: 6c 69 74 65 5f 69 6e 74 36 34 0a 23 65 6e 64 69 lite_int64.#endi
0ae0: 66 0a 0a 2f 2a 0a 2a 2a 20 41 20 66 75 6e 63 74 f../*.** A funct
0af0: 69 6f 6e 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 ion to close the
0b00: 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a database..**.**
0b10: 20 43 61 6c 6c 20 74 68 69 73 20 66 75 6e 63 74 Call this funct
0b20: 69 6f 6e 20 77 69 74 68 20 61 20 70 6f 69 6e 74 ion with a point
0b30: 65 72 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 er to a structur
0b40: 65 20 74 68 61 74 20 77 61 73 20 70 72 65 76 69 e that was previ
0b50: 6f 75 73 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 ously.** returne
0b60: 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6f d from sqlite3_o
0b70: 70 65 6e 28 29 20 61 6e 64 20 74 68 65 20 63 6f pen() and the co
0b80: 72 72 65 73 70 6f 6e 64 69 6e 67 20 64 61 74 61 rresponding data
0b90: 62 61 73 65 20 77 69 6c 6c 20 62 79 20 63 6c 6f base will by clo
0ba0: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20 53 sed..**.** All S
0bb0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 72 QL statements pr
0bc0: 65 70 61 72 65 64 20 75 73 69 6e 67 20 73 71 6c epared using sql
0bd0: 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 6f ite3_prepare() o
0be0: 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 r.** sqlite3_pre
0bf0: 70 61 72 65 31 36 28 29 20 6d 75 73 74 20 62 65 pare16() must be
0c00: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 deallocated usi
0c10: 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c ng sqlite3_final
0c20: 69 7a 65 28 29 20 62 65 66 6f 72 65 0a 2a 2a 20 ize() before.**
0c30: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
0c40: 63 61 6c 6c 65 64 2e 20 4f 74 68 65 72 77 69 73 called. Otherwis
0c50: 65 2c 20 53 51 4c 49 54 45 5f 42 55 53 59 20 69 e, SQLITE_BUSY i
0c60: 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 s returned and t
0c70: 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 he.** database c
0c80: 6f 6e 6e 65 63 74 69 6f 6e 20 72 65 6d 61 69 6e onnection remain
0c90: 73 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 s open..*/.int s
0ca0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c qlite3_close(sql
0cb0: 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ite3 *);../*.**
0cc0: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 The type for a c
0cd0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
0ce0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 ..*/.typedef int
0cf0: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 (*sqlite3_callb
0d00: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 ack)(void*,int,c
0d10: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a har**, char**);.
0d20: 0a 2f 2a 0a 2a 2a 20 41 20 66 75 6e 63 74 69 6f ./*.** A functio
0d30: 6e 20 74 6f 20 65 78 65 63 75 74 65 73 20 6f 6e n to executes on
0d40: 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 65 6d e or more statem
0d50: 65 6e 74 73 20 6f 66 20 53 51 4c 2e 0a 2a 2a 0a ents of SQL..**.
0d60: 2a 2a 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 ** If one or mor
0d70: 65 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 e of the SQL sta
0d80: 74 65 6d 65 6e 74 73 20 61 72 65 20 71 75 65 72 tements are quer
0d90: 69 65 73 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 ies, then.** the
0da0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
0db0: 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 on specified by
0dc0: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
0dd0: 72 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 r is.** invoked
0de0: 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f once for each ro
0df0: 77 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 72 w of the query r
0e00: 65 73 75 6c 74 2e 20 20 54 68 69 73 20 63 61 6c esult. This cal
0e10: 6c 62 61 63 6b 0a 2a 2a 20 73 68 6f 75 6c 64 20 lback.** should
0e20: 6e 6f 72 6d 61 6c 6c 79 20 72 65 74 75 72 6e 20 normally return
0e30: 30 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62 0. If the callb
0e40: 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f ack returns a no
0e50: 6e 2d 7a 65 72 6f 0a 2a 2a 20 76 61 6c 75 65 20 n-zero.** value
0e60: 74 68 65 6e 20 74 68 65 20 71 75 65 72 79 20 69 then the query i
0e70: 73 20 61 62 6f 72 74 65 64 2c 20 61 6c 6c 20 73 s aborted, all s
0e80: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 ubsequent SQL st
0e90: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 72 65 20 atements.** are
0ea0: 73 6b 69 70 70 65 64 20 61 6e 64 20 74 68 65 20 skipped and the
0eb0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 66 sqlite3_exec() f
0ec0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
0ed0: 74 68 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 the SQLITE_ABORT
0ee0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 34 74 68 20 ..**.** The 4th
0ef0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 parameter is an
0f00: 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 arbitrary pointe
0f10: 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 r that is passed
0f20: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 .** to the callb
0f30: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 ack function as
0f40: 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 its first parame
0f50: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 32 ter..**.** The 2
0f60: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
0f70: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e the callback fun
0f80: 63 74 69 6f 6e 20 69 73 20 74 68 65 20 6e 75 6d ction is the num
0f90: 62 65 72 20 6f 66 0a 2a 2a 20 63 6f 6c 75 6d 6e ber of.** column
0fa0: 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 72 s in the query r
0fb0: 65 73 75 6c 74 2e 20 20 54 68 65 20 33 72 64 20 esult. The 3rd
0fc0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
0fd0: 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
0fe0: 61 6e 20 61 72 72 61 79 20 6f 66 20 73 74 72 69 an array of stri
0ff0: 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 20 ngs holding the
1000: 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68 20 values for each
1010: 63 6f 6c 75 6d 6e 2e 0a 2a 2a 20 54 68 65 20 34 column..** The 4
1020: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
1030: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
1040: 61 6e 20 61 72 72 61 79 20 6f 66 20 73 74 72 69 an array of stri
1050: 6e 67 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 74 ngs holding.** t
1060: 68 65 20 6e 61 6d 65 73 20 6f 66 20 65 61 63 68 he names of each
1070: 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 column..**.** T
1080: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
1090: 74 69 6f 6e 20 6d 61 79 20 62 65 20 4e 55 4c 4c tion may be NULL
10a0: 2c 20 65 76 65 6e 20 66 6f 72 20 71 75 65 72 69 , even for queri
10b0: 65 73 2e 20 20 41 20 4e 55 4c 4c 0a 2a 2a 20 63 es. A NULL.** c
10c0: 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 61 allback is not a
10d0: 6e 20 65 72 72 6f 72 2e 20 20 49 74 20 6a 75 73 n error. It jus
10e0: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 t means that no
10f0: 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 77 69 6c 6c callback.** will
1100: 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a be invoked..**.
1110: 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f ** If an error o
1120: 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 73 ccurs while pars
1130: 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e ing or evaluatin
1140: 67 20 74 68 65 20 53 51 4c 20 28 62 75 74 0a 2a g the SQL (but.*
1150: 2a 20 6e 6f 74 20 77 68 69 6c 65 20 65 78 65 63 * not while exec
1160: 75 74 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 uting the callba
1170: 63 6b 29 20 74 68 65 6e 20 61 6e 20 61 70 70 72 ck) then an appr
1180: 6f 70 72 69 61 74 65 20 65 72 72 6f 72 0a 2a 2a opriate error.**
1190: 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 message is writ
11a0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 ten into memory
11b0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61 obtained from ma
11c0: 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 2a 65 lloc() and.** *e
11d0: 72 72 6d 73 67 20 69 73 20 6d 61 64 65 20 74 6f rrmsg is made to
11e0: 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 20 6d point to that m
11f0: 65 73 73 61 67 65 2e 20 20 54 68 65 20 63 61 6c essage. The cal
1200: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a ling function.**
1210: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
1220: 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 for freeing the
1230: 6d 65 6d 6f 72 79 20 74 68 61 74 20 68 6f 6c 64 memory that hold
1240: 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d s the error.** m
1250: 65 73 73 61 67 65 2e 20 20 20 55 73 65 20 73 71 essage. Use sq
1260: 6c 69 74 65 33 5f 66 72 65 65 28 29 20 66 6f 72 lite3_free() for
1270: 20 74 68 69 73 2e 20 20 49 66 20 65 72 72 6d 73 this. If errms
1280: 67 3d 3d 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e g==NULL,.** then
1290: 20 6e 6f 20 65 72 72 6f 72 20 6d 65 73 73 61 67 no error messag
12a0: 65 20 69 73 20 65 76 65 72 20 77 72 69 74 74 65 e is ever writte
12b0: 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 n..**.** The ret
12c0: 75 72 6e 20 76 61 6c 75 65 20 69 73 20 69 73 20 urn value is is
12d0: 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 74 68 65 SQLITE_OK if the
12e0: 72 65 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 re are no errors
12f0: 20 61 6e 64 0a 2a 2a 20 73 6f 6d 65 20 6f 74 68 and.** some oth
1300: 65 72 20 72 65 74 75 72 6e 20 63 6f 64 65 20 69 er return code i
1310: 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 f there is an er
1320: 72 6f 72 2e 20 20 54 68 65 20 70 61 72 74 69 63 ror. The partic
1330: 75 6c 61 72 0a 2a 2a 20 72 65 74 75 72 6e 20 76 ular.** return v
1340: 61 6c 75 65 20 64 65 70 65 6e 64 73 20 6f 6e 20 alue depends on
1350: 74 68 65 20 74 79 70 65 20 6f 66 20 65 72 72 6f the type of erro
1360: 72 2e 20 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 r. .**.** If the
1370: 20 71 75 65 72 79 20 63 6f 75 6c 64 20 6e 6f 74 query could not
1380: 20 62 65 20 65 78 65 63 75 74 65 64 20 62 65 63 be executed bec
1390: 61 75 73 65 20 61 20 64 61 74 61 62 61 73 65 20 ause a database
13a0: 66 69 6c 65 20 69 73 0a 2a 2a 20 6c 6f 63 6b 65 file is.** locke
13b0: 64 20 6f 72 20 62 75 73 79 2c 20 74 68 65 6e 20 d or busy, then
13c0: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 this function re
13d0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 42 55 53 turns SQLITE_BUS
13e0: 59 2e 20 20 28 54 68 69 73 0a 2a 2a 20 62 65 68 Y. (This.** beh
13f0: 61 76 69 6f 72 20 63 61 6e 20 62 65 20 6d 6f 64 avior can be mod
1400: 69 66 69 65 64 20 73 6f 6d 65 77 68 61 74 20 75 ified somewhat u
1410: 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 sing the sqlite3
1420: 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 0a _busy_handler().
1430: 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 62 ** and sqlite3_b
1440: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 20 66 75 usy_timeout() fu
1450: 6e 63 74 69 6f 6e 73 20 62 65 6c 6f 77 2e 29 0a nctions below.).
1460: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 */.int sqlite3_e
1470: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c xec(. sqlite3*,
1480: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1490: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 /* An open
14a0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f database */. co
14b0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 nst char *sql,
14c0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
14d0: 51 4c 20 74 6f 20 62 65 20 65 78 65 63 75 74 65 QL to be execute
14e0: 64 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 63 d */. sqlite3_c
14f0: 61 6c 6c 62 61 63 6b 2c 20 20 20 20 20 20 20 20 allback,
1500: 20 20 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b /* Callback
1510: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 function */. v
1520: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 oid *,
1530: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
1540: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 1st argument to
1550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
1560: 6e 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 n */. char **er
1570: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 rmsg
1580: 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 /* Error ms
1590: 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a g written here *
15a0: 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 52 65 74 75 /.);../*.** Retu
15b0: 72 6e 20 76 61 6c 75 65 73 20 66 6f 72 20 73 71 rn values for sq
15c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 6e 64 lite3_exec() and
15d0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a sqlite3_step().
15e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
15f0: 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 E_OK 0
1600: 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c /* Successful
1610: 20 72 65 73 75 6c 74 20 2a 2f 0a 23 64 65 66 69 result */.#defi
1620: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 ne SQLITE_ERROR
1630: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 1 /* SQ
1640: 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 L error or missi
1650: 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 ng database */.#
1660: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
1670: 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f TERNAL 2 /
1680: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 49 6e 74 65 * NOT USED. Inte
1690: 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 rnal logic error
16a0: 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 in SQLite */.#d
16b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 efine SQLITE_PER
16c0: 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a M 3 /*
16d0: 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 Access permissi
16e0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 on denied */.#de
16f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 fine SQLITE_ABOR
1700: 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 T 4 /*
1710: 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 Callback routine
1720: 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 requested an ab
1730: 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ort */.#define S
1740: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 QLITE_BUSY
1750: 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 5 /* The da
1760: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c tabase file is l
1770: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 ocked */.#define
1780: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 SQLITE_LOCKED
1790: 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 6 /* A ta
17a0: 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 ble in the datab
17b0: 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f ase is locked */
17c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17d0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 NOMEM 7
17e0: 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 /* A malloc() f
17f0: 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 ailed */.#define
1800: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 SQLITE_READONLY
1810: 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 8 /* Atte
1820: 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 mpt to write a r
1830: 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 eadonly database
1840: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1850: 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 TE_INTERRUPT
1860: 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 9 /* Operation
1870: 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 terminated by s
1880: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1890: 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ()*/.#define SQL
18a0: 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 ITE_IOERR
18b0: 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 10 /* Some kin
18c0: 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 d of disk I/O er
18d0: 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a ror occurred */.
18e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
18f0: 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20 ORRUPT 11
1900: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 /* The database
1910: 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 disk image is ma
1920: 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 lformed */.#defi
1930: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 ne SQLITE_NOTFOU
1940: 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f ND 12 /* NO
1950: 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 T USED. Table or
1960: 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e record not foun
1970: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
1980: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 ITE_FULL
1990: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 13 /* Insertio
19a0: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 n failed because
19b0: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c database is ful
19c0: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
19d0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 ITE_CANTOPEN
19e0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 14 /* Unable t
19f0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 o open the datab
1a00: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 ase file */.#def
1a10: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f ine SQLITE_PROTO
1a20: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 COL 15 /* D
1a30: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f atabase lock pro
1a40: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 tocol error */.#
1a50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d define SQLITE_EM
1a60: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f PTY 16 /
1a70: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d * Database is em
1a80: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 pty */.#define S
1a90: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 QLITE_SCHEMA
1aa0: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 17 /* The da
1ab0: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 tabase schema ch
1ac0: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 anged */.#define
1ad0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 SQLITE_TOOBIG
1ae0: 20 20 20 20 31 38 20 20 20 2f 2a 20 4e 4f 54 20 18 /* NOT
1af0: 55 53 45 44 2e 20 54 6f 6f 20 6d 75 63 68 20 64 USED. Too much d
1b00: 61 74 61 20 66 6f 72 20 6f 6e 65 20 72 6f 77 20 ata for one row
1b10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1b20: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 E_CONSTRAINT 19
1b30: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 /* Abort due
1b40: 74 6f 20 63 6f 6e 74 72 61 69 6e 74 20 76 69 6f to contraint vio
1b50: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e lation */.#defin
1b60: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 e SQLITE_MISMATC
1b70: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 H 20 /* Dat
1b80: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 a type mismatch
1b90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1ba0: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 E_MISUSE 21
1bb0: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 /* Library us
1bc0: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a ed incorrectly *
1bd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1be0: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 _NOLFS 22
1bf0: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 /* Uses OS fea
1c00: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 tures not suppor
1c10: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 ted on host */.#
1c20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 define SQLITE_AU
1c30: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f TH 23 /
1c40: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 * Authorization
1c50: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e denied */.#defin
1c60: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 e SQLITE_FORMAT
1c70: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 24 /* Aux
1c80: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 iliary database
1c90: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a format error */.
1ca0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
1cb0: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 ANGE 25
1cc0: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 /* 2nd parameter
1cd0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
1ce0: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f out of range */
1cf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1d00: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 NOTADB 26
1d10: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 /* File opened
1d20: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 that is not a da
1d30: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 tabase file */.#
1d40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f define SQLITE_RO
1d50: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f W 100 /
1d60: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
1d70: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 has another row
1d80: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e ready */.#defin
1d90: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 e SQLITE_DONE
1da0: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 101 /* sql
1db0: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 ite3_step() has
1dc0: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 finished executi
1dd0: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d ng */./* end-of-
1de0: 72 65 74 75 72 6e 2d 63 6f 64 65 73 20 2a 2f 0a return-codes */.
1df0: 0a 2f 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 ./*.** Each entr
1e00: 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 y in an SQLite t
1e10: 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 able has a uniqu
1e20: 65 20 69 6e 74 65 67 65 72 20 6b 65 79 2e 20 20 e integer key.
1e30: 28 54 68 65 20 6b 65 79 20 69 73 0a 2a 2a 20 74 (The key is.** t
1e40: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
1e50: 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 INTEGER PRIMARY
1e60: 4b 45 59 20 63 6f 6c 75 6d 6e 20 69 66 20 74 68 KEY column if th
1e70: 65 72 65 20 69 73 20 73 75 63 68 20 61 20 63 6f ere is such a co
1e80: 6c 75 6d 6e 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 lumn,.** otherwi
1e90: 73 65 20 74 68 65 20 6b 65 79 20 69 73 20 67 65 se the key is ge
1ea0: 6e 65 72 61 74 65 64 20 61 74 20 72 61 6e 64 6f nerated at rando
1eb0: 6d 2e 20 20 54 68 65 20 75 6e 69 71 75 65 20 6b m. The unique k
1ec0: 65 79 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 ey is always.**
1ed0: 61 76 61 69 6c 61 62 6c 65 20 61 73 20 74 68 65 available as the
1ee0: 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 ROWID, OID, or
1ef0: 5f 52 4f 57 49 44 5f 20 63 6f 6c 75 6d 6e 2e 29 _ROWID_ column.)
1f00: 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 The following
1f10: 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 routine.** retur
1f20: 6e 73 20 74 68 65 20 69 6e 74 65 67 65 72 20 6b ns the integer k
1f30: 65 79 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 ey of the most r
1f40: 65 63 65 6e 74 20 69 6e 73 65 72 74 20 69 6e 20 ecent insert in
1f50: 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a the database..**
1f60: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
1f70: 6e 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 n is similar to
1f80: 74 68 65 20 6d 79 73 71 6c 5f 69 6e 73 65 72 74 the mysql_insert
1f90: 5f 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 _id() function f
1fa0: 72 6f 6d 20 4d 79 53 51 4c 2e 0a 2a 2f 0a 73 71 rom MySQL..*/.sq
1fb0: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 lite_int64 sqlit
1fc0: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
1fd0: 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a owid(sqlite3*);.
1fe0: 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 ./*.** This func
1ff0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
2000: 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 number of datab
2010: 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 ase rows that we
2020: 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 28 6f re changed.** (o
2030: 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 r inserted or de
2040: 6c 65 74 65 64 29 20 62 79 20 74 68 65 20 6d 6f leted) by the mo
2050: 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 65 64 st recent called
2060: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2e sqlite3_exec().
2070: 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20 63 68 61 6e 67 .**.** All chang
2080: 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2c 20 es are counted,
2090: 65 76 65 6e 20 69 66 20 74 68 65 79 20 77 65 72 even if they wer
20a0: 65 20 6c 61 74 65 72 20 75 6e 64 6f 6e 65 20 62 e later undone b
20b0: 79 20 61 0a 2a 2a 20 52 4f 4c 4c 42 41 43 4b 20 y a.** ROLLBACK
20c0: 6f 72 20 41 42 4f 52 54 2e 20 20 45 78 63 65 70 or ABORT. Excep
20d0: 74 2c 20 63 68 61 6e 67 65 73 20 61 73 73 6f 63 t, changes assoc
20e0: 69 61 74 65 64 20 77 69 74 68 20 63 72 65 61 74 iated with creat
20f0: 69 6e 67 20 61 6e 64 0a 2a 2a 20 64 72 6f 70 70 ing and.** dropp
2100: 69 6e 67 20 74 61 62 6c 65 73 20 61 72 65 20 6e ing tables are n
2110: 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a ot counted..**.*
2120: 2a 20 49 66 20 61 20 63 61 6c 6c 62 61 63 6b 20 * If a callback
2130: 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f invokes sqlite3_
2140: 65 78 65 63 28 29 20 72 65 63 75 72 73 69 76 65 exec() recursive
2150: 6c 79 2c 20 74 68 65 6e 20 74 68 65 20 63 68 61 ly, then the cha
2160: 6e 67 65 73 0a 2a 2a 20 69 6e 20 74 68 65 20 69 nges.** in the i
2170: 6e 6e 65 72 2c 20 72 65 63 75 72 73 69 76 65 20 nner, recursive
2180: 63 61 6c 6c 20 61 72 65 20 63 6f 75 6e 74 65 64 call are counted
2190: 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 together with t
21a0: 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e he changes.** in
21b0: 20 74 68 65 20 6f 75 74 65 72 20 63 61 6c 6c 2e the outer call.
21c0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d .**.** SQLite im
21d0: 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d plements the com
21e0: 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f mand "DELETE FRO
21f0: 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 M table" without
2200: 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a a WHERE clause.
2210: 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 ** by dropping a
2220: 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 nd recreating th
2230: 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 e table. (This
2240: 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 is much faster t
2250: 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 han going.** thr
2260: 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e ough and deletin
2270: 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 g individual ele
2280: 6d 65 6e 74 73 20 66 6f 72 6d 20 74 68 65 20 74 ments form the t
2290: 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 able.) Because
22a0: 6f 66 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d of.** this optim
22b0: 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 ization, the cha
22c0: 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 nge count for "D
22d0: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 ELETE FROM table
22e0: 22 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 " will be.** zer
22f0: 6f 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 o regardless of
2300: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c the number of el
2310: 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 ements that were
2320: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 originally in t
2330: 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 he.** table. To
2340: 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 get an accurate
2350: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d count of the num
2360: 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 ber of rows dele
2370: 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c ted, use.** "DEL
2380: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 ETE FROM table W
2390: 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e HERE 1" instead.
23a0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
23b0: 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a changes(sqlite3*
23c0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 66 );../*.** This f
23d0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
23e0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 the number of da
23f0: 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 tabase rows that
2400: 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 6d 6f have been.** mo
2410: 64 69 66 69 65 64 20 62 79 20 49 4e 53 45 52 54 dified by INSERT
2420: 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 , UPDATE or DELE
2430: 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 TE statements si
2440: 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 nce the database
2450: 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73 20 6f handle.** was o
2460: 70 65 6e 65 64 2e 20 54 68 69 73 20 69 6e 63 6c pened. This incl
2470: 75 64 65 73 20 55 50 44 41 54 45 2c 20 49 4e 53 udes UPDATE, INS
2480: 45 52 54 20 61 6e 64 20 44 45 4c 45 54 45 20 73 ERT and DELETE s
2490: 74 61 74 65 6d 65 6e 74 73 20 65 78 65 63 75 74 tatements execut
24a0: 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 ed.** as part of
24b0: 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d trigger program
24c0: 73 2e 20 41 6c 6c 20 63 68 61 6e 67 65 73 20 61 s. All changes a
24d0: 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f re counted as so
24e0: 6f 6e 20 61 73 20 74 68 65 0a 2a 2a 20 73 74 61 on as the.** sta
24f0: 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 tement that make
2500: 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 s them is comple
2510: 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 ted (when the st
2520: 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 atement handle i
2530: 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 73 s.** passed to s
2540: 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 6f qlite3_reset() o
2550: 72 20 73 71 6c 69 74 65 5f 66 69 6e 61 6c 69 73 r sqlite_finalis
2560: 65 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 e())..**.** SQLi
2570: 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 te implements th
2580: 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 e command "DELET
2590: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 E FROM table" wi
25a0: 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c thout a WHERE cl
25b0: 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 ause.** by dropp
25c0: 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 ing and recreati
25d0: 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 ng the table. (
25e0: 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 This is much fas
25f0: 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a ter than going.*
2600: 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 * through and de
2610: 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 leting individua
2620: 6c 20 65 6c 65 6d 65 6e 74 73 20 66 6f 72 6d 20 l elements form
2630: 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 the table.) Bec
2640: 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20 ause of.** this
2650: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 optimization, th
2660: 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 20 66 e change count f
2670: 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 or "DELETE FROM
2680: 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a table" will be.*
2690: 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 73 * zero regardles
26a0: 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 s of the number
26b0: 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 of elements that
26c0: 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 were originally
26d0: 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 in the.** table
26e0: 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 . To get an accu
26f0: 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 rate count of th
2700: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 e number of rows
2710: 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a deleted, use.**
2720: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 "DELETE FROM ta
2730: 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 ble WHERE 1" ins
2740: 74 65 61 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c tead..*/.int sql
2750: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
2760: 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
2770: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
2780: 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 causes any pendi
2790: 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 ng database oper
27a0: 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 ation to abort a
27b0: 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 nd.** return at
27c0: 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 its earliest opp
27d0: 6f 72 74 75 6e 69 74 79 2e 20 20 54 68 69 73 20 ortunity. This
27e0: 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 routine is typic
27f0: 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 ally.** called i
2800: 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 n response to a
2810: 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 user action such
2820: 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 as pressing "Ca
2830: 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c ncel".** or Ctrl
2840: 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 -C where the use
2850: 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 r wants a long q
2860: 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 uery operation t
2870: 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 o halt.** immedi
2880: 61 74 65 6c 79 2e 0a 2a 2f 0a 76 6f 69 64 20 73 ately..*/.void s
2890: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
28a0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 0a 2f 2a (sqlite3*);.../*
28b0: 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 These functions
28c0: 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 return true if
28d0: 74 68 65 20 67 69 76 65 6e 20 69 6e 70 75 74 20 the given input
28e0: 73 74 72 69 6e 67 20 63 6f 6d 70 72 69 73 65 73 string comprises
28f0: 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 .** one or more
2900: 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 complete SQL sta
2910: 74 65 6d 65 6e 74 73 2e 20 46 6f 72 20 74 68 65 tements. For the
2920: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
2930: 65 28 29 20 63 61 6c 6c 2c 0a 2a 2a 20 74 68 65 e() call,.** the
2940: 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 parameter must
2950: 62 65 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 be a nul-termina
2960: 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 ted UTF-8 string
2970: 2e 20 46 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 . For.** sqlite3
2980: 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2c 20 61 _complete16(), a
2990: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 20 nul-terminated
29a0: 6d 61 63 68 69 6e 65 20 62 79 74 65 20 6f 72 64 machine byte ord
29b0: 65 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 er UTF-16 string
29c0: 0a 2a 2a 20 69 73 20 72 65 71 75 69 72 65 64 2e .** is required.
29d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 6c 67 6f 72 .**.** The algor
29e0: 69 74 68 6d 20 69 73 20 73 69 6d 70 6c 65 2e 20 ithm is simple.
29f0: 20 49 66 20 74 68 65 20 6c 61 73 74 20 74 6f 6b If the last tok
2a00: 65 6e 20 6f 74 68 65 72 20 74 68 61 6e 20 73 70 en other than sp
2a10: 61 63 65 73 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d aces.** and comm
2a20: 65 6e 74 73 20 69 73 20 61 20 73 65 6d 69 63 6f ents is a semico
2a30: 6c 6f 6e 2c 20 74 68 65 6e 20 72 65 74 75 72 6e lon, then return
2a40: 20 74 72 75 65 2e 20 20 6f 74 68 65 72 77 69 73 true. otherwis
2a50: 65 20 72 65 74 75 72 6e 0a 2a 2a 20 66 61 6c 73 e return.** fals
2a60: 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 e..*/.int sqlite
2a70: 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 3_complete(const
2a80: 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 char *sql);.int
2a90: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
2aa0: 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a e16(const void *
2ab0: 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 sql);../*.** Thi
2ac0: 73 20 72 6f 75 74 69 6e 65 20 69 64 65 6e 74 69 s routine identi
2ad0: 66 69 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 fies a callback
2ae0: 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 function that is
2af0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e invoked.** when
2b00: 65 76 65 72 20 61 6e 20 61 74 74 65 6d 70 74 20 ever an attempt
2b10: 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 is made to open
2b20: 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
2b30: 20 74 68 61 74 20 69 73 0a 2a 2a 20 63 75 72 72 that is.** curr
2b40: 65 6e 74 6c 79 20 6c 6f 63 6b 65 64 20 62 79 20 ently locked by
2b50: 61 6e 6f 74 68 65 72 20 70 72 6f 63 65 73 73 20 another process
2b60: 6f 72 20 74 68 72 65 61 64 2e 20 20 49 66 20 74 or thread. If t
2b70: 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
2b80: 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 .** is NULL, the
2b90: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 n sqlite3_exec()
2ba0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
2bb0: 42 55 53 59 20 69 6d 6d 65 64 69 61 74 65 6c 79 BUSY immediately
2bc0: 20 69 66 0a 2a 2a 20 69 74 20 66 69 6e 64 73 20 if.** it finds
2bd0: 61 20 6c 6f 63 6b 65 64 20 74 61 62 6c 65 2e 20 a locked table.
2be0: 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c If the busy cal
2bf0: 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 4e 55 4c lback is not NUL
2c00: 4c 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 L, then.** sqlit
2c10: 65 33 5f 65 78 65 63 28 29 20 69 6e 76 6f 6b 65 e3_exec() invoke
2c20: 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 s the callback w
2c30: 69 74 68 20 74 68 72 65 65 20 61 72 67 75 6d 65 ith three argume
2c40: 6e 74 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 nts. The.** sec
2c50: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
2c60: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
2c70: 6c 6f 63 6b 65 64 20 74 61 62 6c 65 20 61 6e 64 locked table and
2c80: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 the third.** ar
2c90: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 gument is the nu
2ca0: 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 mber of times th
2cb0: 65 20 74 61 62 6c 65 20 68 61 73 20 62 65 65 6e e table has been
2cc0: 20 62 75 73 79 2e 20 20 49 66 20 74 68 65 0a 2a busy. If the.*
2cd0: 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 * busy callback
2ce0: 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 returns 0, then
2cf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
2d00: 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75 72 mmediately retur
2d10: 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 ns.** SQLITE_BUS
2d20: 59 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62 Y. If the callb
2d30: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ack returns non-
2d40: 7a 65 72 6f 2c 20 74 68 65 6e 20 73 71 6c 69 74 zero, then sqlit
2d50: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 74 72 69 e3_exec().** tri
2d60: 65 73 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 74 es to open the t
2d70: 61 62 6c 65 20 61 67 61 69 6e 20 61 6e 64 20 74 able again and t
2d80: 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 he cycle repeats
2d90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 ..**.** The defa
2da0: 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 ult busy callbac
2db0: 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a k is NULL..**.**
2dc0: 20 53 71 6c 69 74 65 20 69 73 20 72 65 2d 65 6e Sqlite is re-en
2dd0: 74 72 61 6e 74 2c 20 73 6f 20 74 68 65 20 62 75 trant, so the bu
2de0: 73 79 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 73 sy handler may s
2df0: 74 61 72 74 20 61 20 6e 65 77 20 71 75 65 72 79 tart a new query
2e00: 2e 20 0a 2a 2a 20 28 49 74 20 69 73 20 6e 6f 74 . .** (It is not
2e10: 20 63 6c 65 61 72 20 77 68 79 20 61 6e 79 6f 6e clear why anyon
2e20: 65 20 77 6f 75 6c 64 20 65 76 65 72 79 20 77 61 e would every wa
2e30: 6e 74 20 74 6f 20 64 6f 20 74 68 69 73 2c 20 62 nt to do this, b
2e40: 75 74 20 69 74 0a 2a 2a 20 69 73 20 61 6c 6c 6f ut it.** is allo
2e50: 77 65 64 2c 20 69 6e 20 74 68 65 6f 72 79 2e 29 wed, in theory.)
2e60: 20 20 42 75 74 20 74 68 65 20 62 75 73 79 20 68 But the busy h
2e70: 61 6e 64 6c 65 72 20 6d 61 79 20 6e 6f 74 20 63 andler may not c
2e80: 6c 6f 73 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 lose the.** data
2e90: 62 61 73 65 2e 20 20 43 6c 6f 73 69 6e 67 20 74 base. Closing t
2ea0: 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d he database from
2eb0: 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 a busy handler
2ec0: 77 69 6c 6c 20 64 65 6c 65 74 65 20 0a 2a 2a 20 will delete .**
2ed0: 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 data structures
2ee0: 6f 75 74 20 66 72 6f 6d 20 75 6e 64 65 72 20 74 out from under t
2ef0: 68 65 20 65 78 65 63 75 74 69 6e 67 20 71 75 65 he executing que
2f00: 72 79 20 61 6e 64 20 77 69 6c 6c 20 0a 2a 2a 20 ry and will .**
2f10: 70 72 6f 62 61 62 6c 79 20 72 65 73 75 6c 74 20 probably result
2f20: 69 6e 20 61 20 63 6f 72 65 64 75 6d 70 2e 0a 2a in a coredump..*
2f30: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 /.int sqlite3_bu
2f40: 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 sy_handler(sqlit
2f50: 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 e3*, int(*)(void
2f60: 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a *,int), void*);.
2f70: 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 ./*.** This rout
2f80: 69 6e 65 20 73 65 74 73 20 61 20 62 75 73 79 20 ine sets a busy
2f90: 68 61 6e 64 6c 65 72 20 74 68 61 74 20 73 6c 65 handler that sle
2fa0: 65 70 73 20 66 6f 72 20 61 20 77 68 69 6c 65 20 eps for a while
2fb0: 77 68 65 6e 20 61 0a 2a 2a 20 74 61 62 6c 65 20 when a.** table
2fc0: 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 is locked. The
2fd0: 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20 73 6c 65 handler will sle
2fe0: 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 ep multiple time
2ff0: 73 20 75 6e 74 69 6c 20 0a 2a 2a 20 61 74 20 6c s until .** at l
3000: 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 65 73 east "ms" milles
3010: 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
3020: 6e 67 20 68 61 76 65 20 62 65 65 6e 20 64 6f 6e ng have been don
3030: 65 2e 20 20 41 66 74 65 72 0a 2a 2a 20 22 6d 73 e. After.** "ms
3040: 22 20 6d 69 6c 6c 65 73 65 63 6f 6e 64 73 20 6f " milleseconds o
3050: 66 20 73 6c 65 65 70 69 6e 67 2c 20 74 68 65 20 f sleeping, the
3060: 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 handler returns
3070: 30 20 77 68 69 63 68 0a 2a 2a 20 63 61 75 73 65 0 which.** cause
3080: 73 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 s sqlite3_exec()
3090: 20 74 6f 20 72 65 74 75 72 6e 20 53 51 4c 49 54 to return SQLIT
30a0: 45 5f 42 55 53 59 2e 0a 2a 2a 0a 2a 2a 20 43 61 E_BUSY..**.** Ca
30b0: 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 lling this routi
30c0: 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d ne with an argum
30d0: 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 ent less than or
30e0: 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a equal to zero.*
30f0: 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 * turns off all
3100: 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a busy handlers..*
3110: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 /.int sqlite3_bu
3120: 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 sy_timeout(sqlit
3130: 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f e3*, int ms);../
3140: 2a 0a 2a 2a 20 54 68 69 73 20 6e 65 78 74 20 72 *.** This next r
3150: 6f 75 74 69 6e 65 20 69 73 20 72 65 61 6c 6c 79 outine is really
3160: 20 6a 75 73 74 20 61 20 77 72 61 70 70 65 72 20 just a wrapper
3170: 61 72 6f 75 6e 64 20 73 71 6c 69 74 65 33 5f 65 around sqlite3_e
3180: 78 65 63 28 29 2e 0a 2a 2a 20 49 6e 73 74 65 61 xec()..** Instea
3190: 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 61 20 d of invoking a
31a0: 75 73 65 72 2d 73 75 70 70 6c 69 65 64 20 63 61 user-supplied ca
31b0: 6c 6c 62 61 63 6b 20 66 6f 72 20 65 61 63 68 20 llback for each
31c0: 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 row of the.** re
31d0: 73 75 6c 74 2c 20 74 68 69 73 20 72 6f 75 74 69 sult, this routi
31e0: 6e 65 20 72 65 6d 65 6d 62 65 72 73 20 65 61 63 ne remembers eac
31f0: 68 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 h row of the res
3200: 75 6c 74 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a ult in memory.**
3210: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d obtained from m
3220: 61 6c 6c 6f 63 28 29 2c 20 74 68 65 6e 20 72 65 alloc(), then re
3230: 74 75 72 6e 73 20 61 6c 6c 20 6f 66 20 74 68 65 turns all of the
3240: 20 72 65 73 75 6c 74 20 61 66 74 65 72 20 74 68 result after th
3250: 65 0a 2a 2a 20 71 75 65 72 79 20 68 61 73 20 66 e.** query has f
3260: 69 6e 69 73 68 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 inished. .**.**
3270: 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 2c 20 73 As an example, s
3280: 75 70 70 6f 73 65 20 74 68 65 20 71 75 65 72 79 uppose the query
3290: 20 72 65 73 75 6c 74 20 77 68 65 72 65 20 74 68 result where th
32a0: 69 73 20 74 61 62 6c 65 3a 0a 2a 2a 0a 2a 2a 20 is table:.**.**
32b0: 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 Name
32c0: 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 | Age.**
32d0: 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d -------------
32e0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 ----------.**
32f0: 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 Alice
3300: 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 | 43.**
3310: 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 Bob | 28
3320: 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 .** Cindy
3330: 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 0a 2a | 21.**.*
3340: 2a 20 49 66 20 74 68 65 20 33 72 64 20 61 72 67 * If the 3rd arg
3350: 75 6d 65 6e 74 20 77 65 72 65 20 26 61 7a 52 65 ument were &azRe
3360: 73 75 6c 74 20 74 68 65 6e 20 61 66 74 65 72 20 sult then after
3370: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 the function ret
3380: 75 72 6e 73 0a 2a 2a 20 61 7a 52 65 73 75 6c 74 urns.** azResult
3390: 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 68 will contain th
33a0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 64 61 74 61 e following data
33b0: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20 61 :.**.** a
33c0: 7a 52 65 73 75 6c 74 5b 30 5d 20 3d 20 22 4e 61 zResult[0] = "Na
33d0: 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 me";.** a
33e0: 7a 52 65 73 75 6c 74 5b 31 5d 20 3d 20 22 41 67 zResult[1] = "Ag
33f0: 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a e";.** az
3400: 52 65 73 75 6c 74 5b 32 5d 20 3d 20 22 41 6c 69 Result[2] = "Ali
3410: 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 ce";.** a
3420: 7a 52 65 73 75 6c 74 5b 33 5d 20 3d 20 22 34 33 zResult[3] = "43
3430: 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
3440: 65 73 75 6c 74 5b 34 5d 20 3d 20 22 42 6f 62 22 esult[4] = "Bob"
3450: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
3460: 73 75 6c 74 5b 35 5d 20 3d 20 22 32 38 22 3b 0a sult[5] = "28";.
3470: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
3480: 6c 74 5b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b lt[6] = "Cindy";
3490: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
34a0: 75 6c 74 5b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a ult[7] = "21";.*
34b0: 2a 0a 2a 2a 20 4e 6f 74 69 63 65 20 74 68 61 74 *.** Notice that
34c0: 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 78 74 there is an ext
34d0: 72 61 20 72 6f 77 20 6f 66 20 64 61 74 61 20 63 ra row of data c
34e0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 63 6f ontaining the co
34f0: 6c 75 6d 6e 0a 2a 2a 20 68 65 61 64 65 72 73 2e lumn.** headers.
3500: 20 20 42 75 74 20 74 68 65 20 2a 6e 72 6f 77 20 But the *nrow
3510: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 20 return value is
3520: 73 74 69 6c 6c 20 33 2e 20 20 2a 6e 63 6f 6c 75 still 3. *ncolu
3530: 6d 6e 20 69 73 0a 2a 2a 20 73 65 74 20 74 6f 20 mn is.** set to
3540: 32 2e 20 20 49 6e 20 67 65 6e 65 72 61 6c 2c 20 2. In general,
3550: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 the number of va
3560: 6c 75 65 73 20 69 6e 73 65 72 74 65 64 20 69 6e lues inserted in
3570: 74 6f 20 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 77 to azResult.** w
3580: 69 6c 6c 20 62 65 20 28 28 2a 6e 72 6f 77 29 20 ill be ((*nrow)
3590: 2b 20 31 29 2a 28 2a 6e 63 6f 6c 75 6d 6e 29 2e + 1)*(*ncolumn).
35a0: 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 .**.** After the
35b0: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f calling functio
35c0: 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 n has finished u
35d0: 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c sing the result,
35e0: 20 69 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 it should .** p
35f0: 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 64 ass the result d
3600: 61 74 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 ata pointer to s
3610: 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
3620: 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 e() in order to
3630: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 .** release the
3640: 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 memory that was
3650: 6d 61 6c 6c 6f 63 2d 65 64 2e 20 20 42 65 63 61 malloc-ed. Beca
3660: 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 use of the way t
3670: 68 65 20 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 he .** malloc()
3680: 68 61 70 70 65 6e 73 2c 20 74 68 65 20 63 61 6c happens, the cal
3690: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 ling function mu
36a0: 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 st not try to ca
36b0: 6c 6c 20 0a 2a 2a 20 66 72 65 65 28 29 20 64 69 ll .** free() di
36c0: 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 20 73 71 rectly. Only sq
36d0: 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
36e0: 28 29 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 () is able to re
36f0: 6c 65 61 73 65 20 0a 2a 2a 20 74 68 65 20 6d 65 lease .** the me
3700: 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e mory properly an
3710: 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 d safely..**.**
3720: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 The return value
3730: 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 of this routine
3740: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 is the same as
3750: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 78 65 from sqlite3_exe
3760: 63 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 c()..*/.int sqli
3770: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 te3_get_table(.
3780: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 sqlite3*,
3790: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f /* An o
37a0: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a pen database */.
37b0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 const char *sq
37c0: 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
37d0: 74 6f 20 62 65 20 65 78 65 63 75 74 65 64 20 2a to be executed *
37e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 /. char ***resu
37f0: 6c 74 70 2c 20 20 20 20 20 20 20 2f 2a 20 52 65 ltp, /* Re
3800: 73 75 6c 74 20 77 72 69 74 74 65 6e 20 74 6f 20 sult written to
3810: 61 20 63 68 61 72 20 2a 5b 5d 20 20 74 68 61 74 a char *[] that
3820: 20 74 68 69 73 20 70 6f 69 6e 74 73 20 74 6f 20 this points to
3830: 2a 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20 */. int *nrow,
3840: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e /* N
3850: 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 umber of result
3860: 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 rows written her
3870: 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c e */. int *ncol
3880: 75 6d 6e 2c 20 20 20 20 20 20 20 20 20 20 2f 2a umn, /*
3890: 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c Number of resul
38a0: 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 t columns writte
38b0: 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 n here */. char
38c0: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 **errmsg
38d0: 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 /* Error msg
38e0: 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
38f0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 61 6c 6c 20 74 );../*.** Call t
3900: 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 66 his routine to f
3910: 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 ree the memory t
3920: 68 61 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f hat sqlite3_get_
3930: 74 61 62 6c 65 28 29 20 61 6c 6c 6f 63 61 74 65 table() allocate
3940: 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 d..*/.void sqlit
3950: 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 e3_free_table(ch
3960: 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f ar **result);../
3970: 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 *.** The followi
3980: 6e 67 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 ng routines are
3990: 76 61 72 69 61 6e 74 73 20 6f 66 20 74 68 65 20 variants of the
39a0: 22 73 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d "sprintf()" from
39b0: 20 74 68 65 0a 2a 2a 20 73 74 61 6e 64 61 72 64 the.** standard
39c0: 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 C library. The
39d0: 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e resulting strin
39e0: 67 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 g is written int
39f0: 6f 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 o memory.** obta
3a00: 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f 63 ined from malloc
3a10: 28 29 20 73 6f 20 74 68 61 74 20 74 68 65 72 65 () so that there
3a20: 20 69 73 20 6e 65 76 65 72 20 61 20 70 6f 73 73 is never a poss
3a30: 69 62 6c 69 74 79 20 6f 66 20 62 75 66 66 65 72 iblity of buffer
3a40: 0a 2a 2a 20 6f 76 65 72 66 6c 6f 77 2e 20 20 54 .** overflow. T
3a50: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c hese routines al
3a60: 73 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d so implement som
3a70: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 e additional for
3a80: 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f matting.** optio
3a90: 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 ns that are usef
3aa0: 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 ul for construct
3ab0: 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ing SQL statemen
3ac0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 74 ts..**.** The st
3ad0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 rings returned b
3ae0: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 y these routines
3af0: 20 73 68 6f 75 6c 64 20 62 65 20 66 72 65 65 64 should be freed
3b00: 20 62 79 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 by calling.** s
3b10: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a qlite3_free()..*
3b20: 2a 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 *.** All of the
3b30: 75 73 75 61 6c 20 70 72 69 6e 74 66 20 66 6f 72 usual printf for
3b40: 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 matting options
3b50: 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 apply. In addit
3b60: 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 ion, there.** is
3b70: 20 61 20 22 25 71 22 20 6f 70 74 69 6f 6e 2e 20 a "%q" option.
3b80: 20 25 71 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 %q works like %
3b90: 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 s in that it sub
3ba0: 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d stitutes a null-
3bb0: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 terminated.** st
3bc0: 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 ring from the ar
3bd0: 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 gument list. Bu
3be0: 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 t %q also double
3bf0: 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 s every '\'' cha
3c00: 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 racter..** %q is
3c10: 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 designed for us
3c20: 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e e inside a strin
3c30: 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 g literal. By d
3c40: 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 oubling each '\'
3c50: 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 '.** character i
3c60: 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 t escapes that c
3c70: 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c haracter and all
3c80: 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 ows it to be ins
3c90: 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 erted into.** th
3ca0: 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 e string..**.**
3cb0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 73 6f 20 For example, so
3cc0: 73 6f 6d 65 20 73 74 72 69 6e 67 20 76 61 72 69 some string vari
3cd0: 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74 65 able contains te
3ce0: 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a xt as follows:.*
3cf0: 2a 0a 2a 2a 20 20 20 20 20 20 63 68 61 72 20 2a *.** char *
3d00: 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 zText = "It's a
3d10: 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 0a happy day!";.**.
3d20: 2a 2a 20 57 65 20 63 61 6e 20 75 73 65 20 74 68 ** We can use th
3d30: 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 is text in an SQ
3d40: 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 L statement as f
3d50: 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 20 20 ollows:.**.**
3d60: 20 20 20 63 68 61 72 20 2a 7a 20 3d 20 73 71 6c char *z = sql
3d70: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e ite3_mprintf("IN
3d80: 53 45 52 54 20 49 4e 54 4f 20 54 41 42 4c 45 53 SERT INTO TABLES
3d90: 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b ('%q')", zText);
3da0: 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
3db0: 5f 65 78 65 63 28 64 62 2c 20 7a 2c 20 63 61 6c _exec(db, z, cal
3dc0: 6c 62 61 63 6b 31 2c 20 30 2c 20 30 29 3b 0a 2a lback1, 0, 0);.*
3dd0: 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 66 * sqlite3_f
3de0: 72 65 65 28 7a 29 3b 0a 2a 2a 0a 2a 2a 20 42 65 ree(z);.**.** Be
3df0: 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 cause the %q for
3e00: 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 mat string is us
3e10: 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 ed, the '\'' cha
3e20: 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a racter in zText.
3e30: 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e ** is escaped an
3e40: 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 d the SQL genera
3e50: 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 ted is as follow
3e60: 73 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 49 4e s:.**.** IN
3e70: 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 SERT INTO table1
3e80: 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 VALUES('It''s a
3e90: 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a happy day!').**
3ea0: 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 .** This is corr
3eb0: 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 ect. Had we use
3ec0: 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 d %s instead of
3ed0: 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 %q, the generate
3ee0: 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 d SQL.** would h
3ef0: 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 ave looked like
3f00: 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 this:.**.**
3f10: 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 INSERT INTO tab
3f20: 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 le1 VALUES('It's
3f30: 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b a happy day!');
3f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f .**.** This seco
3f50: 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e nd example is an
3f60: 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f SQL syntax erro
3f70: 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c r. As a general
3f80: 20 72 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 68 6f rule you.** sho
3f90: 75 6c 64 20 61 6c 77 61 79 73 20 75 73 65 20 25 uld always use %
3fa0: 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 q instead of %s
3fb0: 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 when inserting t
3fc0: 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e ext into a strin
3fd0: 67 20 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a 2a g .** literal..*
3fe0: 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f /.char *sqlite3_
3ff0: 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 mprintf(const ch
4000: 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a ar*,...);.char *
4010: 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
4020: 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 (const char*, va
4030: 5f 6c 69 73 74 29 3b 0a 76 6f 69 64 20 73 71 6c _list);.void sql
4040: 69 74 65 33 5f 66 72 65 65 28 63 68 61 72 20 2a ite3_free(char *
4050: 7a 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 z);.char *sqlite
4060: 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 3_snprintf(int,c
4070: 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
4080: 2c 20 2e 2e 2e 29 3b 0a 0a 23 69 66 6e 64 65 66 , ...);..#ifndef
4090: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 SQLITE_OMIT_AUT
40a0: 48 4f 52 49 5a 41 54 49 4f 4e 0a 2f 2a 0a 2a 2a HORIZATION./*.**
40b0: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 This routine re
40c0: 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 gisters a callba
40d0: 63 6b 20 77 69 74 68 20 74 68 65 20 53 51 4c 69 ck with the SQLi
40e0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 te library. The
40f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 .** callback is
4100: 69 6e 76 6f 6b 65 64 20 28 61 74 20 63 6f 6d 70 invoked (at comp
4110: 69 6c 65 2d 74 69 6d 65 2c 20 6e 6f 74 20 61 74 ile-time, not at
4120: 20 72 75 6e 2d 74 69 6d 65 29 20 66 6f 72 20 65 run-time) for e
4130: 61 63 68 0a 2a 2a 20 61 74 74 65 6d 70 74 20 74 ach.** attempt t
4140: 6f 20 61 63 63 65 73 73 20 61 20 63 6f 6c 75 6d o access a colum
4150: 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 69 6e 20 n of a table in
4160: 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 54 the database. T
4170: 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 72 he callback.** r
4180: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b eturns SQLITE_OK
4190: 20 69 66 20 61 63 63 65 73 73 20 69 73 20 61 6c if access is al
41a0: 6c 6f 77 65 64 2c 20 53 51 4c 49 54 45 5f 44 45 lowed, SQLITE_DE
41b0: 4e 59 20 69 66 20 74 68 65 20 65 6e 74 69 72 65 NY if the entire
41c0: 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
41d0: 74 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6f 72 t should be abor
41e0: 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f ted with an erro
41f0: 72 20 61 6e 64 20 53 51 4c 49 54 45 5f 49 47 4e r and SQLITE_IGN
4200: 4f 52 45 0a 2a 2a 20 69 66 20 74 68 65 20 63 6f ORE.** if the co
4210: 6c 75 6d 6e 20 73 68 6f 75 6c 64 20 62 65 20 74 lumn should be t
4220: 72 65 61 74 65 64 20 61 73 20 61 20 4e 55 4c 4c reated as a NULL
4230: 20 76 61 6c 75 65 2e 0a 2a 2f 0a 69 6e 74 20 73 value..*/.int s
4240: 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
4250: 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 rizer(. sqlite3
4260: 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 *,. int (*xAuth
4270: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
4280: 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
4290: 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
42a0: 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 const char*),.
42b0: 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a void *pUserData.
42c0: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a );.#endif../*.**
42d0: 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
42e0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 63 63 meter to the acc
42f0: 65 73 73 20 61 75 74 68 6f 72 69 7a 61 74 69 6f ess authorizatio
4300: 6e 20 66 75 6e 63 74 69 6f 6e 20 61 62 6f 76 65 n function above
4310: 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 6f 6e 65 20 will.** be one
4320: 6f 66 20 74 68 65 20 76 61 6c 75 65 73 20 62 65 of the values be
4330: 6c 6f 77 2e 20 20 54 68 65 73 65 20 76 61 6c 75 low. These valu
4340: 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 es signify what
4350: 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f kind of operatio
4360: 6e 0a 2a 2a 20 69 73 20 74 6f 20 62 65 20 61 75 n.** is to be au
4370: 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 thorized. The 3
4380: 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d rd and 4th param
4390: 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 eters to the aut
43a0: 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 66 75 horization.** fu
43b0: 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 nction will be p
43c0: 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c arameters or NUL
43d0: 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 L depending on w
43e0: 68 69 63 68 20 6f 66 20 74 68 65 20 66 6f 6c 6c hich of the foll
43f0: 6f 77 69 6e 67 0a 2a 2a 20 63 6f 64 65 73 20 69 owing.** codes i
4400: 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 s used as the se
4410: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 cond parameter.
4420: 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 The 5th paramet
4430: 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a er is the name.*
4440: 2a 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 * of the databas
4450: 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 e ("main", "temp
4460: 22 2c 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c ", etc.) if appl
4470: 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 icable. The 6th
4480: 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 parameter.** is
4490: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
44a0: 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 inner-most trig
44b0: 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 ger or view that
44c0: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
44d0: 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 for.** the acces
44e0: 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c s attempt or NUL
44f0: 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 L if this access
4500: 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 attempt is dire
4510: 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 69 6e ctly from .** in
4520: 70 75 74 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a put SQL code..**
4530: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 .**
4540: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4550: 20 20 20 20 20 20 20 20 20 20 20 20 20 41 72 67 Arg
4560: 2d 33 20 20 20 20 20 20 20 20 20 20 20 41 72 67 -3 Arg
4570: 2d 34 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 -4.*/.#define SQ
4580: 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 LITE_COPY
4590: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 0 /
45a0: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
45b0: 20 20 46 69 6c 65 20 4e 61 6d 65 20 20 20 20 20 File Name
45c0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
45d0: 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 ITE_CREATE_INDEX
45e0: 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 1 /*
45f0: 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
4600: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
4610: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4620: 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 TE_CREATE_TABLE
4630: 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 2 /*
4640: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
4650: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
4660: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4670: 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e E_CREATE_TEMP_IN
4680: 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 DEX 3 /* I
4690: 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
46a0: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
46b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
46c0: 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 _CREATE_TEMP_TAB
46d0: 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 LE 4 /* Ta
46e0: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
46f0: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
4700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4710: 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 CREATE_TEMP_TRIG
4720: 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 GER 5 /* Tri
4730: 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
4740: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
4750: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
4760: 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 REATE_TEMP_VIEW
4770: 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 6 /* View
4780: 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
4790: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
47a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
47b0: 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 EATE_TRIGGER
47c0: 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 7 /* Trigg
47d0: 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
47e0: 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
47f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
4800: 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 ATE_VIEW
4810: 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 8 /* View N
4820: 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
4830: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
4840: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 fine SQLITE_DELE
4850: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TE
4860: 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 9 /* Table N
4870: 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
4880: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
4890: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
48a0: 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 INDEX
48b0: 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 10 /* Index Na
48c0: 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
48d0: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
48e0: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
48f0: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 ABLE 1
4900: 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 1 /* Table Nam
4910: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
4920: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
4930: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
4940: 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 MP_INDEX 12
4950: 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
4960: 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
4970: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
4980: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
4990: 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 P_TABLE 13
49a0: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
49b0: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
49c0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
49d0: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
49e0: 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 _TRIGGER 14
49f0: 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
4a00: 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
4a10: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
4a20: 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
4a30: 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 VIEW 15
4a40: 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
4a50: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
4a60: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
4a70: 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 LITE_DROP_TRIGGE
4a80: 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f R 16 /
4a90: 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
4aa0: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
4ab0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
4ac0: 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 ITE_DROP_VIEW
4ad0: 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 17 /*
4ae0: 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
4af0: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
4b00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4b10: 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 TE_INSERT
4b20: 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 18 /*
4b30: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
4b40: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
4b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4b60: 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 E_PRAGMA
4b70: 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 19 /* P
4b80: 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 ragma Name 1
4b90: 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a st arg or NULL *
4ba0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4bb0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 _READ
4bc0: 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 20 /* Ta
4bd0: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f ble Name Co
4be0: 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f lumn Name */
4bf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4c00: 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 SELECT
4c10: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 21 /* NUL
4c20: 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c L NUL
4c30: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
4c40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
4c50: 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 RANSACTION
4c60: 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 22 /* NULL
4c70: 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c NULL
4c80: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
4c90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 define SQLITE_UP
4ca0: 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 DATE
4cb0: 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 23 /* Table
4cc0: 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d Name Colum
4cd0: 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 n Name */.#d
4ce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 efine SQLITE_ATT
4cf0: 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 ACH
4d00: 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 24 /* Filena
4d10: 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 me NULL
4d20: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
4d30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 fine SQLITE_DETA
4d40: 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CH
4d50: 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 25 /* Databas
4d60: 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 e Name NULL
4d70: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
4d80: 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 ine SQLITE_ALTER
4d90: 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
4da0: 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 26 /* Database
4db0: 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
4dc0: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 ne SQLITE_REINDE
4de0: 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 X 2
4df0: 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 7 /* Index Nam
4e00: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
4e10: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
4e20: 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 e SQLITE_ANALYZE
4e30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 28
4e40: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
4e50: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
4e60: 20 20 20 20 20 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a */.../*.**
4e70: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 The return valu
4e80: 65 20 6f 66 20 74 68 65 20 61 75 74 68 6f 72 69 e of the authori
4e90: 7a 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 zation function
4ea0: 73 68 6f 75 6c 64 20 62 65 20 6f 6e 65 20 6f 66 should be one of
4eb0: 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e the.** followin
4ec0: 67 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2f 0a g constants:.*/.
4ed0: 2f 2a 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 /* #define SQLIT
4ee0: 45 5f 4f 4b 20 20 30 20 20 20 2f 2f 20 41 6c 6c E_OK 0 // All
4ef0: 6f 77 20 61 63 63 65 73 73 20 28 54 68 69 73 20 ow access (This
4f00: 69 73 20 61 63 74 75 61 6c 6c 79 20 64 65 66 69 is actually defi
4f10: 6e 65 64 20 61 62 6f 76 65 29 20 2a 2f 0a 23 64 ned above) */.#d
4f20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e efine SQLITE_DEN
4f30: 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 Y 1 /* Abort
4f40: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
4f50: 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 nt with an error
4f60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4f70: 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a TE_IGNORE 2 /*
4f80: 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 Don't allow acc
4f90: 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 ess, but don't g
4fa0: 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 enerate an error
4fb0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 52 65 67 69 73 */../*.** Regis
4fc0: 74 65 72 20 61 20 66 75 6e 63 74 69 6f 6e 20 66 ter a function f
4fd0: 6f 72 20 74 72 61 63 69 6e 67 20 53 51 4c 20 63 or tracing SQL c
4fe0: 6f 6d 6d 61 6e 64 20 65 76 61 6c 75 61 74 69 6f ommand evaluatio
4ff0: 6e 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e n. The function
5000: 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 62 .** registered b
5010: 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 y sqlite3_trace(
5020: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 20 ) is invoked at
5030: 74 68 65 20 66 69 72 73 74 20 73 71 6c 69 74 65 the first sqlite
5040: 33 5f 73 74 65 70 28 29 0a 2a 2a 20 66 6f 72 20 3_step().** for
5050: 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f the evaluation o
5060: 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 f an SQL stateme
5070: 6e 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f nt. The functio
5080: 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 0a n registered by.
5090: 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 ** sqlite3_profi
50a0: 6c 65 28 29 20 72 75 6e 73 20 61 74 20 74 68 65 le() runs at the
50b0: 20 65 6e 64 20 6f 66 20 65 61 63 68 20 53 51 4c end of each SQL
50c0: 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 69 statement and i
50d0: 6e 63 6c 75 64 65 73 0a 2a 2a 20 69 6e 66 6f 72 ncludes.** infor
50e0: 6d 61 74 69 6f 6e 20 6f 6e 20 68 6f 77 20 6c 6f mation on how lo
50f0: 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e ng that statemen
5100: 74 20 72 61 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 t ran..**.** The
5110: 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 sqlite3_profile
5120: 28 29 20 41 50 49 20 69 73 20 63 75 72 72 65 6e () API is curren
5130: 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 20 65 tly considered e
5140: 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a xperimental and.
5150: 2a 2a 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f ** is subject to
5160: 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69 64 change..*/.void
5170: 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 *sqlite3_trace(
5180: 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a sqlite3*, void(*
5190: 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f xTrace)(void*,co
51a0: 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 nst char*), void
51b0: 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 *);.void *sqlite
51c0: 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 3_profile(sqlite
51d0: 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 3*,. void(*xPr
51e0: 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e ofile)(void*,con
51f0: 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 5f st char*,sqlite_
5200: 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b uint64), void*);
5210: 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ../*.** This rou
5220: 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 tine configures
5230: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
5240: 69 6f 6e 20 2d 20 74 68 65 20 70 72 6f 67 72 65 ion - the progre
5250: 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 ss callback - th
5260: 61 74 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 at.** is invoked
5270: 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 periodically du
5280: 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e ring long runnin
5290: 67 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 g calls to sqlit
52a0: 65 33 5f 65 78 65 63 28 29 2c 0a 2a 2a 20 73 71 e3_exec(),.** sq
52b0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 61 6e 64 lite3_step() and
52c0: 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
52d0: 6c 65 28 29 2e 20 41 6e 20 65 78 61 6d 70 6c 65 le(). An example
52e0: 20 75 73 65 20 66 6f 72 20 74 68 69 73 20 41 50 use for this AP
52f0: 49 20 69 73 20 74 6f 20 0a 2a 2a 20 6b 65 65 70 I is to .** keep
5300: 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 a GUI updated d
5310: 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 uring a large qu
5320: 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 ery..**.** The p
5330: 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b rogress callback
5340: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 is invoked once
5350: 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69 72 for every N vir
5360: 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 6f 70 63 tual machine opc
5370: 6f 64 65 73 2c 0a 2a 2a 20 77 68 65 72 65 20 4e odes,.** where N
5380: 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 is the second a
5390: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 rgument to this
53a0: 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 70 72 function. The pr
53b0: 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a ogress callback.
53c0: 2a 2a 20 69 74 73 65 6c 66 20 69 73 20 69 64 65 ** itself is ide
53d0: 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 74 ntified by the t
53e0: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f hird argument to
53f0: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 this function.
5400: 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 61 72 The fourth.** ar
5410: 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 gument to this f
5420: 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 76 6f 69 unction is a voi
5430: 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 d pointer passed
5440: 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73 to the progress
5450: 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e callback.** fun
5460: 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20 ction each time
5470: 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a it is invoked..*
5480: 2a 0a 2a 2a 20 49 66 20 61 20 63 61 6c 6c 20 74 *.** If a call t
5490: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
54a0: 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 , sqlite3_step()
54b0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 67 65 74 5f or sqlite3_get_
54c0: 74 61 62 6c 65 28 29 20 72 65 73 75 6c 74 73 20 table() results
54d0: 0a 2a 2a 20 69 6e 20 6c 65 73 73 20 74 68 61 6e .** in less than
54e0: 20 4e 20 6f 70 63 6f 64 65 73 20 62 65 69 6e 67 N opcodes being
54f0: 20 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e 20 executed, then
5500: 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c the progress cal
5510: 6c 62 61 63 6b 20 69 73 20 6e 6f 74 0a 2a 2a 20 lback is not.**
5520: 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 invoked..** .**
5530: 54 6f 20 72 65 6d 6f 76 65 20 74 68 65 20 70 72 To remove the pr
5540: 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 ogress callback
5550: 61 6c 74 6f 67 65 74 68 65 72 2c 20 70 61 73 73 altogether, pass
5560: 20 4e 55 4c 4c 20 61 73 20 74 68 65 20 74 68 69 NULL as the thi
5570: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 rd.** argument t
5580: 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e o this function.
5590: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 .**.** If the pr
55a0: 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 ogress callback
55b0: 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 returns a result
55c0: 20 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20 74 other than 0, t
55d0: 68 65 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 hen the current
55e0: 0a 2a 2a 20 71 75 65 72 79 20 69 73 20 69 6d 6d .** query is imm
55f0: 65 64 69 61 74 65 6c 79 20 74 65 72 6d 69 6e 61 ediately termina
5600: 74 65 64 20 61 6e 64 20 61 6e 79 20 64 61 74 61 ted and any data
5610: 62 61 73 65 20 63 68 61 6e 67 65 73 20 72 6f 6c base changes rol
5620: 6c 65 64 20 62 61 63 6b 2e 20 49 66 20 74 68 65 led back. If the
5630: 0a 2a 2a 20 71 75 65 72 79 20 77 61 73 20 70 61 .** query was pa
5640: 72 74 20 6f 66 20 61 20 6c 61 72 67 65 72 20 74 rt of a larger t
5650: 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e ransaction, then
5660: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
5670: 20 69 73 20 6e 6f 74 20 72 6f 6c 6c 65 64 0a 2a is not rolled.*
5680: 2a 20 62 61 63 6b 20 61 6e 64 20 72 65 6d 61 69 * back and remai
5690: 6e 73 20 61 63 74 69 76 65 2e 20 54 68 65 20 73 ns active. The s
56a0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 qlite3_exec() ca
56b0: 6c 6c 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 ll returns SQLIT
56c0: 45 5f 41 42 4f 52 54 2e 20 0a 2a 2a 0a 2a 2a 2a E_ABORT. .**.***
56d0: 2a 2a 2a 2a 20 54 48 49 53 20 49 53 20 41 4e 20 **** THIS IS AN
56e0: 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 41 50 49 EXPERIMENTAL API
56f0: 20 41 4e 44 20 49 53 20 53 55 42 4a 45 43 54 20 AND IS SUBJECT
5700: 54 4f 20 43 48 41 4e 47 45 20 2a 2a 2a 2a 2a 2a TO CHANGE ******
5710: 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 .*/.void sqlite3
5720: 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 _progress_handle
5730: 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c r(sqlite3*, int,
5740: 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 int(*)(void*),
5750: 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 52 void*);../*.** R
5760: 65 67 69 73 74 65 72 20 61 20 63 61 6c 6c 62 61 egister a callba
5770: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ck function to b
5780: 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 e invoked whenev
5790: 65 72 20 61 20 6e 65 77 20 74 72 61 6e 73 61 63 er a new transac
57a0: 74 69 6f 6e 0a 2a 2a 20 69 73 20 63 6f 6d 6d 69 tion.** is commi
57b0: 74 74 65 64 2e 20 20 54 68 65 20 70 41 72 67 20 tted. The pArg
57c0: 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 argument is pass
57d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 ed through to th
57e0: 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 63 e callback..** c
57f0: 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74 68 65 allback. If the
5800: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
5810: 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a on returns non-z
5820: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 63 6f ero, then the co
5830: 6d 6d 69 74 0a 2a 2a 20 69 73 20 63 6f 6e 76 65 mmit.** is conve
5840: 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c rted into a roll
5850: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 back..**.** If a
5860: 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 nother function
5870: 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 was previously r
5880: 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 egistered, its p
5890: 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 Arg value is ret
58a0: 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 urned..** Otherw
58b0: 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 ise NULL is retu
58c0: 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 rned..**.** Regi
58d0: 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 stering a NULL f
58e0: 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 unction disables
58f0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a the callback..*
5900: 2a 0a 2a 2a 2a 2a 2a 2a 2a 20 54 48 49 53 20 49 *.******* THIS I
5910: 53 20 41 4e 20 45 58 50 45 52 49 4d 45 4e 54 41 S AN EXPERIMENTA
5920: 4c 20 41 50 49 20 41 4e 44 20 49 53 20 53 55 42 L API AND IS SUB
5930: 4a 45 43 54 20 54 4f 20 43 48 41 4e 47 45 20 2a JECT TO CHANGE *
5940: 2a 2a 2a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 2a 73 *****.*/.void *s
5950: 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f qlite3_commit_ho
5960: 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ok(sqlite3*, int
5970: 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 (*)(void*), void
5980: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 4f 70 65 6e 20 *);../*.** Open
5990: 74 68 65 20 73 71 6c 69 74 65 20 64 61 74 61 62 the sqlite datab
59a0: 61 73 65 20 66 69 6c 65 20 22 66 69 6c 65 6e 61 ase file "filena
59b0: 6d 65 22 2e 20 20 54 68 65 20 22 66 69 6c 65 6e me". The "filen
59c0: 61 6d 65 22 20 69 73 20 55 54 46 2d 38 0a 2a 2a ame" is UTF-8.**
59d0: 20 65 6e 63 6f 64 65 64 20 66 6f 72 20 73 71 6c encoded for sql
59e0: 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
59f0: 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 69 UTF-16 encoded i
5a00: 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 n the native byt
5a10: 65 20 6f 72 64 65 72 0a 2a 2a 20 66 6f 72 20 73 e order.** for s
5a20: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e qlite3_open16().
5a30: 20 20 41 6e 20 73 71 6c 69 74 65 33 2a 20 68 61 An sqlite3* ha
5a40: 6e 64 6c 65 20 69 73 20 72 65 74 75 72 6e 65 64 ndle is returned
5a50: 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 0a in *ppDb, even.
5a60: 2a 2a 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f ** if an error o
5a70: 63 63 75 72 73 2e 20 49 66 20 74 68 65 20 64 61 ccurs. If the da
5a80: 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
5a90: 20 28 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 (or created) su
5aa0: 63 63 65 73 73 66 75 6c 6c 79 2c 0a 2a 2a 20 74 ccessfully,.** t
5ab0: 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 hen SQLITE_OK is
5ac0: 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 returned. Other
5ad0: 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 63 6f wise an error co
5ae0: 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 de is returned.
5af0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 The.** sqlite3_e
5b00: 72 72 6d 73 67 28 29 20 6f 72 20 73 71 6c 69 74 rrmsg() or sqlit
5b10: 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 20 72 e3_errmsg16() r
5b20: 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 outines can be u
5b30: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a sed to obtain.**
5b40: 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 an English lang
5b50: 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e uage description
5b60: 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a of the error..*
5b70: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 *.** If the data
5b80: 62 61 73 65 20 66 69 6c 65 20 64 6f 65 73 20 6e base file does n
5b90: 6f 74 20 65 78 69 73 74 2c 20 74 68 65 6e 20 61 ot exist, then a
5ba0: 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 69 73 new database is
5bb0: 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20 54 68 65 created..** The
5bc0: 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 encoding for th
5bd0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 55 54 e database is UT
5be0: 46 2d 38 20 69 66 20 73 71 6c 69 74 65 33 5f 6f F-8 if sqlite3_o
5bf0: 70 65 6e 28 29 20 69 73 20 63 61 6c 6c 65 64 20 pen() is called
5c00: 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 66 and.** UTF-16 if
5c10: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 20 sqlite3_open16
5c20: 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 is used..**.** W
5c30: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e hether or not an
5c40: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 error occurs wh
5c50: 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c en it is opened,
5c60: 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63 resources assoc
5c70: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 iated.** with th
5c80: 65 20 73 71 6c 69 74 65 33 2a 20 68 61 6e 64 6c e sqlite3* handl
5c90: 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 e should be rele
5ca0: 61 73 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 ased by passing
5cb0: 69 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 it to.** sqlite3
5cc0: 5f 63 6c 6f 73 65 28 29 20 77 68 65 6e 20 69 74 _close() when it
5cd0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 is no longer re
5ce0: 71 75 69 72 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 quired..*/.int s
5cf0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 qlite3_open(. c
5d00: 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e onst char *filen
5d10: 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
5d20: 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
5d30: 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 -8) */. sqlite3
5d40: 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 **ppDb
5d50: 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
5d60: 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a db handle */.);.
5d70: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e int sqlite3_open
5d80: 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 16(. const void
5d90: 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a *filename, /*
5da0: 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 Database filena
5db0: 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 me (UTF-16) */.
5dc0: 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 sqlite3 **ppDb
5dd0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
5de0: 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
5df0: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 52 e */.);../*.** R
5e00: 65 74 75 72 6e 20 74 68 65 20 65 72 72 6f 72 20 eturn the error
5e10: 63 6f 64 65 20 66 6f 72 20 74 68 65 20 6d 6f 73 code for the mos
5e20: 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 t recent sqlite3
5e30: 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f _* API call asso
5e40: 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 73 ciated.** with s
5e50: 71 6c 69 74 65 33 20 68 61 6e 64 6c 65 20 27 64 qlite3 handle 'd
5e60: 62 27 2e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 b'. SQLITE_OK is
5e70: 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 returned if the
5e80: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 0a 2a 2a most recent .**
5e90: 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75 API call was su
5ea0: 63 63 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 ccessful..**.**
5eb0: 43 61 6c 6c 73 20 74 6f 20 6d 61 6e 79 20 73 71 Calls to many sq
5ec0: 6c 69 74 65 33 5f 2a 20 66 75 6e 63 74 69 6f 6e lite3_* function
5ed0: 73 20 73 65 74 20 74 68 65 20 65 72 72 6f 72 20 s set the error
5ee0: 63 6f 64 65 20 61 6e 64 20 73 74 72 69 6e 67 20 code and string
5ef0: 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 returned.** by s
5f00: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
5f10: 2c 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 , sqlite3_errmsg
5f20: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 () and sqlite3_e
5f30: 72 72 6d 73 67 31 36 28 29 0a 2a 2a 20 28 6f 76 rrmsg16().** (ov
5f40: 65 72 77 72 69 74 69 6e 67 20 74 68 65 20 70 72 erwriting the pr
5f50: 65 76 69 6f 75 73 20 76 61 6c 75 65 73 29 2e 20 evious values).
5f60: 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 73 20 Note that calls
5f70: 74 6f 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f to sqlite3_errco
5f80: 64 65 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 de(),.** sqlite3
5f90: 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 _errmsg() and sq
5fa0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
5fb0: 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e themselves do n
5fc0: 6f 74 20 61 66 66 65 63 74 20 74 68 65 0a 2a 2a ot affect the.**
5fd0: 20 72 65 73 75 6c 74 73 20 6f 66 20 66 75 74 75 results of futu
5fe0: 72 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a re invocations..
5ff0: 2a 2a 0a 2a 2a 20 41 73 73 75 6d 69 6e 67 20 6e **.** Assuming n
6000: 6f 20 6f 74 68 65 72 20 69 6e 74 65 72 76 65 6e o other interven
6010: 69 6e 67 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 ing sqlite3_* AP
6020: 49 20 63 61 6c 6c 73 20 61 72 65 20 6d 61 64 65 I calls are made
6030: 2c 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 , the error.** c
6040: 6f 64 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 ode returned by
6050: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 this function is
6060: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
6070: 20 74 68 65 20 73 61 6d 65 20 65 72 72 6f 72 20 the same error
6080: 61 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 as.** the string
6090: 73 20 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 s returned by s
60a0: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 qlite3_errmsg()
60b0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d and sqlite3_errm
60c0: 73 67 31 36 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 sg16()..*/.int s
60d0: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 qlite3_errcode(s
60e0: 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 0a 2f 2a qlite3 *db);../*
60f0: 0a 2a 2a 20 52 65 74 75 72 6e 20 61 20 70 6f 69 .** Return a poi
6100: 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 20 nter to a UTF-8
6110: 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 20 64 encoded string d
6120: 65 73 63 72 69 62 69 6e 67 20 69 6e 20 65 6e 67 escribing in eng
6130: 6c 69 73 68 20 74 68 65 0a 2a 2a 20 65 72 72 6f lish the.** erro
6140: 72 20 63 6f 6e 64 69 74 69 6f 6e 20 66 6f 72 20 r condition for
6150: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
6160: 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 sqlite3_* API ca
6170: 6c 6c 2e 20 54 68 65 20 72 65 74 75 72 6e 65 64 ll. The returned
6180: 0a 2a 2a 20 73 74 72 69 6e 67 20 69 73 20 61 6c .** string is al
6190: 77 61 79 73 20 74 65 72 6d 69 6e 61 74 65 64 20 ways terminated
61a0: 62 79 20 61 6e 20 30 78 30 30 20 62 79 74 65 2e by an 0x00 byte.
61b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e .**.** The strin
61c0: 67 20 22 6e 6f 74 20 61 6e 20 65 72 72 6f 72 22 g "not an error"
61d0: 20 69 73 20 72 65 74 75 72 6e 65 64 20 77 68 65 is returned whe
61e0: 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e n the most recen
61f0: 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 0a 2a t API call was.*
6200: 2a 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f * successful..*/
6210: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
6220: 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 ite3_errmsg(sqli
6230: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 52 65 te3*);../*.** Re
6240: 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 turn a pointer t
6250: 6f 20 61 20 55 54 46 2d 31 36 20 6e 61 74 69 76 o a UTF-16 nativ
6260: 65 20 62 79 74 65 20 6f 72 64 65 72 20 65 6e 63 e byte order enc
6270: 6f 64 65 64 20 73 74 72 69 6e 67 20 64 65 73 63 oded string desc
6280: 72 69 62 69 6e 67 0a 2a 2a 20 69 6e 20 65 6e 67 ribing.** in eng
6290: 6c 69 73 68 20 74 68 65 20 65 72 72 6f 72 20 63 lish the error c
62a0: 6f 6e 64 69 74 69 6f 6e 20 66 6f 72 20 74 68 65 ondition for the
62b0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c most recent sql
62c0: 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 2e ite3_* API call.
62d0: 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 .** The returned
62e0: 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 string is alway
62f0: 73 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 s terminated by
6300: 61 20 70 61 69 72 20 6f 66 20 30 78 30 30 20 62 a pair of 0x00 b
6310: 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ytes..**.** The
6320: 73 74 72 69 6e 67 20 22 6e 6f 74 20 61 6e 20 65 string "not an e
6330: 72 72 6f 72 22 20 69 73 20 72 65 74 75 72 6e 65 rror" is returne
6340: 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 d when the most
6350: 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 recent API call
6360: 77 61 73 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 was.** successfu
6370: 6c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 l..*/.const void
6380: 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 *sqlite3_errmsg
6390: 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 16(sqlite3*);../
63a0: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
63b0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e of the followin
63c0: 67 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 g opaque structu
63d0: 72 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 re is used to re
63e0: 70 72 65 73 65 6e 74 0a 2a 2a 20 61 20 63 6f 6d present.** a com
63f0: 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 6d 65 piled SQL statme
6400: 6e 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 nt..*/.typedef s
6410: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 truct sqlite3_st
6420: 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b mt sqlite3_stmt;
6430: 0a 0a 2f 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 ../*.** To execu
6440: 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c te an SQL query,
6450: 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 it must first b
6460: 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 e compiled into
6470: 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 a byte-code.** p
6480: 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 rogram using one
6490: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e of the followin
64a0: 67 20 72 6f 75 74 69 6e 65 73 2e 20 54 68 65 20 g routines. The
64b0: 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 only difference
64c0: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 6d 20 between.** them
64d0: 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f is that the seco
64e0: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 73 70 65 nd argument, spe
64f0: 63 69 66 79 69 6e 67 20 74 68 65 20 53 51 4c 20 cifying the SQL
6500: 73 74 61 74 65 6d 65 6e 74 20 74 6f 0a 2a 2a 20 statement to.**
6510: 63 6f 6d 70 69 6c 65 2c 20 69 73 20 61 73 73 75 compile, is assu
6520: 6d 65 64 20 74 6f 20 62 65 20 65 6e 63 6f 64 65 med to be encode
6530: 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 74 d in UTF-8 for t
6540: 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 he sqlite3_prepa
6550: 72 65 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e re().** function
6560: 20 61 6e 64 20 55 54 46 2d 31 36 20 66 6f 72 20 and UTF-16 for
6570: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
6580: 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6()..**.** The f
6590: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 22 irst parameter "
65a0: 64 62 22 20 69 73 20 61 6e 20 53 51 4c 69 74 65 db" is an SQLite
65b0: 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 database handle
65c0: 2e 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 . The second.**
65d0: 70 61 72 61 6d 65 74 65 72 20 22 7a 53 71 6c 22 parameter "zSql"
65e0: 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e is the statemen
65f0: 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
6600: 2c 20 65 6e 63 6f 64 65 64 20 61 73 20 65 69 74 , encoded as eit
6610: 68 65 72 0a 2a 2a 20 55 54 46 2d 38 20 6f 72 20 her.** UTF-8 or
6620: 55 54 46 2d 31 36 20 28 73 65 65 20 61 62 6f 76 UTF-16 (see abov
6630: 65 29 2e 20 49 66 20 74 68 65 20 6e 65 78 74 20 e). If the next
6640: 70 61 72 61 6d 65 74 65 72 2c 20 22 6e 42 79 74 parameter, "nByt
6650: 65 73 22 2c 20 69 73 20 6c 65 73 73 0a 2a 2a 20 es", is less.**
6660: 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 than zero, then
6670: 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 zSql is read up
6680: 74 6f 20 74 68 65 20 66 69 72 73 74 20 6e 75 6c to the first nul
6690: 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 49 66 terminator. If
66a0: 0a 2a 2a 20 22 6e 42 79 74 65 73 22 20 69 73 20 .** "nBytes" is
66b0: 6e 6f 74 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 not less than ze
66c0: 72 6f 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 ro, then it is t
66d0: 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 he length of the
66e0: 20 73 74 72 69 6e 67 20 7a 53 71 6c 0a 2a 2a 20 string zSql.**
66f0: 69 6e 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 in bytes (not ch
6700: 61 72 61 63 74 65 72 73 29 2e 0a 2a 2a 0a 2a 2a aracters)..**.**
6710: 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 *pzTail is made
6720: 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 to point to the
6730: 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 first byte past
6740: 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 the end of the
6750: 66 69 72 73 74 0a 2a 2a 20 53 51 4c 20 73 74 61 first.** SQL sta
6760: 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 tement in zSql.
6770: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e This routine on
6780: 6c 79 20 63 6f 6d 70 69 6c 65 73 20 74 68 65 20 ly compiles the
6790: 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 0a first statement.
67a0: 2a 2a 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a ** in zSql, so *
67b0: 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 pzTail is left p
67c0: 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20 ointing to what
67d0: 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c remains uncompil
67e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d ed..**.** *ppStm
67f0: 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 t is left pointi
6800: 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 ng to a compiled
6810: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
6820: 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 hat can be.** ex
6830: 65 63 75 74 65 64 20 75 73 69 6e 67 20 73 71 6c ecuted using sql
6840: 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 4f 72 ite3_step(). Or
6850: 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 if there is an
6860: 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 6d error, *ppStmt m
6870: 61 79 20 62 65 0a 2a 2a 20 73 65 74 20 74 6f 20 ay be.** set to
6880: 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e NULL. If the in
6890: 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e put text contain
68a0: 65 64 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 ed no SQL (if th
68b0: 65 20 69 6e 70 75 74 20 69 73 20 61 6e 64 0a 2a e input is and.*
68c0: 2a 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f * empty string o
68d0: 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 r a comment) the
68e0: 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 n *ppStmt is set
68f0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 to NULL..**.**
6900: 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 On success, SQLI
6910: 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 TE_OK is returne
6920: 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e d. Otherwise an
6930: 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 error code is r
6940: 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 eturned..*/.int
6950: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
6960: 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
6970: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
6980: 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f tabase handle */
6990: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
69a0: 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 Sql, /* SQ
69b0: 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 L statement, UTF
69c0: 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 -8 encoded */.
69d0: 69 6e 74 20 6e 42 79 74 65 73 2c 20 20 20 20 20 int nBytes,
69e0: 20 20 20 20 20 20 20 20 2f 2a 20 4c 65 6e 67 74 /* Lengt
69f0: 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
6a00: 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
6a10: 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
6a20: 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
6a30: 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
6a40: 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 onst char **pzTa
6a50: 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
6a60: 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
6a70: 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
6a80: 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
6a90: 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 e3_prepare16(.
6aa0: 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
6ab0: 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
6ac0: 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
6ad0: 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c const void *zSql
6ae0: 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
6af0: 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 tatement, UTF-16
6b00: 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
6b10: 74 20 6e 42 79 74 65 73 2c 20 20 20 20 20 20 20 t nBytes,
6b20: 20 20 20 20 20 20 2f 2a 20 4c 65 6e 67 74 68 20 /* Length
6b30: 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
6b40: 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
6b50: 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
6b60: 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
6b70: 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
6b80: 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c st void **pzTail
6b90: 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
6ba0: 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
6bb0: 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
6bc0: 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 50 6f 69 6e /.);../*.** Poin
6bd0: 74 65 72 73 20 74 6f 20 74 68 65 20 66 6f 6c 6c ters to the foll
6be0: 6f 77 69 6e 67 20 74 77 6f 20 6f 70 61 71 75 65 owing two opaque
6bf0: 20 73 74 72 75 63 74 75 72 65 73 20 61 72 65 20 structures are
6c00: 75 73 65 64 20 74 6f 20 63 6f 6d 6d 75 6e 69 63 used to communic
6c10: 61 74 65 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ate.** with the
6c20: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
6c30: 6f 66 20 75 73 65 72 2d 64 65 66 69 6e 65 64 20 of user-defined
6c40: 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 functions..*/.ty
6c50: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
6c60: 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c ite3_context sql
6c70: 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 74 79 ite3_context;.ty
6c80: 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d pedef struct Mem
6c90: 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a sqlite3_value;.
6ca0: 0a 2f 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 ./*.** In the SQ
6cb0: 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 L strings input
6cc0: 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 to sqlite3_prepa
6cd0: 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 re() and sqlite3
6ce0: 5f 70 72 65 70 61 72 65 31 36 28 29 2c 0a 2a 2a _prepare16(),.**
6cf0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6c 69 74 one or more lit
6d00: 65 72 61 6c 73 20 63 61 6e 20 62 65 20 72 65 70 erals can be rep
6d10: 6c 61 63 65 20 62 79 20 70 61 72 61 6d 65 74 65 lace by paramete
6d20: 72 73 20 22 3f 22 20 6f 72 20 22 3a 41 41 41 22 rs "?" or ":AAA"
6d30: 20 6f 72 0a 2a 2a 20 22 24 56 56 56 22 20 77 68 or.** "$VVV" wh
6d40: 65 72 65 20 41 41 41 20 69 73 20 61 6e 20 69 64 ere AAA is an id
6d50: 65 6e 74 69 66 65 72 20 61 6e 64 20 56 56 56 20 entifer and VVV
6d60: 69 73 20 61 20 76 61 72 69 61 62 6c 65 20 6e 61 is a variable na
6d70: 6d 65 20 61 63 63 6f 72 64 69 6e 67 0a 2a 2a 20 me according.**
6d80: 74 6f 20 74 68 65 20 73 79 6e 74 61 78 20 72 75 to the syntax ru
6d90: 6c 65 73 20 6f 66 20 74 68 65 20 54 43 4c 20 70 les of the TCL p
6da0: 72 6f 67 72 61 6d 6d 69 6e 67 20 6c 61 6e 67 75 rogramming langu
6db0: 61 67 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 age..** The valu
6dc0: 65 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d e of these param
6dd0: 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c eters (also call
6de0: 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 ed "host paramet
6df0: 65 72 20 6e 61 6d 65 73 22 29 20 63 61 6e 0a 2a er names") can.*
6e00: 2a 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 * be set using t
6e10: 68 65 20 72 6f 75 74 69 6e 65 73 20 6c 69 73 74 he routines list
6e20: 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 0a 2a 2a 20 ed below..**.**
6e30: 49 6e 20 65 76 65 72 79 20 63 61 73 65 2c 20 74 In every case, t
6e40: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
6e50: 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 er is a pointer
6e60: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 to the sqlite3_s
6e70: 74 6d 74 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 tmt.** structure
6e80: 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 73 returned from s
6e90: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
6ea0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . The second pa
6eb0: 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
6ec0: 2a 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 70 * index of the p
6ed0: 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 66 arameter. The f
6ee0: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 irst parameter a
6ef0: 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e s an index of 1.
6f00: 20 20 46 6f 72 0a 2a 2a 20 6e 61 6d 65 64 20 70 For.** named p
6f10: 61 72 61 6d 65 74 65 72 73 20 28 22 3a 41 41 41 arameters (":AAA
6f20: 22 20 6f 72 20 22 24 56 56 56 22 29 20 79 6f 75 " or "$VVV") you
6f30: 20 63 61 6e 20 75 73 65 20 0a 2a 2a 20 73 71 6c can use .** sql
6f40: 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
6f50: 74 65 72 5f 69 6e 64 65 78 28 29 20 74 6f 20 67 ter_index() to g
6f60: 65 74 20 74 68 65 20 63 6f 72 72 65 63 74 20 69 et the correct i
6f70: 6e 64 65 78 20 76 61 6c 75 65 20 67 69 76 65 6e ndex value given
6f80: 0a 2a 2a 20 74 68 65 20 70 61 72 61 6d 65 74 65 .** the paramete
6f90: 72 73 20 6e 61 6d 65 2e 20 20 49 66 20 74 68 65 rs name. If the
6fa0: 20 73 61 6d 65 20 6e 61 6d 65 64 20 70 61 72 61 same named para
6fb0: 6d 65 74 65 72 20 6f 63 63 75 72 73 20 6d 6f 72 meter occurs mor
6fc0: 65 20 74 68 61 6e 0a 2a 2a 20 6f 6e 63 65 2c 20 e than.** once,
6fd0: 69 74 20 69 73 20 61 73 73 69 67 6e 65 64 20 74 it is assigned t
6fe0: 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 65 61 he same index ea
6ff0: 63 68 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 ch time..**.** T
7000: 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 he fifth paramet
7010: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 er to sqlite3_bi
7020: 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 nd_blob(), sqlit
7030: 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 e3_bind_text(),
7040: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 and.** sqlite3_b
7050: 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 ind_text16() is
7060: 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 a destructor use
7070: 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 d to dispose of
7080: 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 74 the BLOB or.** t
7090: 65 78 74 20 61 66 74 65 72 20 53 51 4c 69 74 65 ext after SQLite
70a0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
70b0: 74 68 20 69 74 2e 20 20 49 66 20 74 68 65 20 66 th it. If the f
70c0: 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 ifth argument is
70d0: 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 61 6c 20 the.** special
70e0: 76 61 6c 75 65 20 53 51 4c 49 54 45 5f 53 54 41 value SQLITE_STA
70f0: 54 49 43 2c 20 74 68 65 6e 20 74 68 65 20 6c 69 TIC, then the li
7100: 62 72 61 72 79 20 61 73 73 75 6d 65 73 20 74 68 brary assumes th
7110: 61 74 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 69 at the informati
7120: 6f 6e 0a 2a 2a 20 69 73 20 69 6e 20 73 74 61 74 on.** is in stat
7130: 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 ic, unmanaged sp
7140: 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 ace and does not
7150: 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 need to be free
7160: 64 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 66 69 d. If the.** fi
7170: 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 fth argument has
7180: 20 74 68 65 20 76 61 6c 75 65 20 53 51 4c 49 54 the value SQLIT
7190: 45 5f 54 52 41 4e 53 49 45 4e 54 2c 20 74 68 65 E_TRANSIENT, the
71a0: 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 n SQLite makes i
71b0: 74 73 0a 2a 2a 20 6f 77 6e 20 70 72 69 76 61 74 ts.** own privat
71c0: 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 e copy of the da
71d0: 74 61 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ta..**.** The sq
71e0: 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 lite3_bind_* rou
71f0: 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c tine must be cal
7200: 6c 65 64 20 62 65 66 6f 72 65 20 73 71 6c 69 74 led before sqlit
7210: 65 33 5f 73 74 65 70 28 29 20 61 66 74 65 72 0a e3_step() after.
7220: 2a 2a 20 61 6e 20 73 71 6c 69 74 65 33 5f 70 72 ** an sqlite3_pr
7230: 65 70 61 72 65 28 29 20 6f 72 20 73 71 6c 69 74 epare() or sqlit
7240: 65 33 5f 72 65 73 65 74 28 29 2e 20 20 55 6e 62 e3_reset(). Unb
7250: 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 73 ound parameterss
7260: 20 61 72 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 are.** interpre
7270: 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a ted as NULL..*/.
7280: 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
7290: 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 _blob(sqlite3_st
72a0: 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
72b0: 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f void*, int n, vo
72c0: 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 id(*)(void*));.i
72d0: 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
72e0: 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 double(sqlite3_s
72f0: 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c tmt*, int, doubl
7300: 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f e);.int sqlite3_
7310: 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 bind_int(sqlite3
7320: 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 _stmt*, int, int
7330: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
7340: 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 ind_int64(sqlite
7350: 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 3_stmt*, int, sq
7360: 6c 69 74 65 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 lite_int64);.int
7370: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 sqlite3_bind_nu
7380: 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ll(sqlite3_stmt*
7390: 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 , int);.int sqli
73a0: 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 te3_bind_text(sq
73b0: 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
73c0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 , const char*, i
73d0: 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f nt n, void(*)(vo
73e0: 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 id*));.int sqlit
73f0: 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 e3_bind_text16(s
7400: 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
7410: 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 t, const void*,
7420: 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 int, void(*)(voi
7430: 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 d*));.int sqlite
7440: 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 3_bind_value(sql
7450: 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
7460: 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 const sqlite3_v
7470: 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 52 alue*);../*.** R
7480: 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 eturn the number
7490: 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 69 of parameters i
74a0: 6e 20 61 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c n a compiled SQL
74b0: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 statement. Thi
74c0: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 61 73 s.** routine was
74d0: 20 61 64 64 65 64 20 74 6f 20 73 75 70 70 6f 72 added to suppor
74e0: 74 20 44 42 44 3a 3a 53 51 4c 69 74 65 2e 0a 2a t DBD::SQLite..*
74f0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 /.int sqlite3_bi
7500: 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
7510: 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a nt(sqlite3_stmt*
7520: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 52 65 74 75 72 6e );../*.** Return
7530: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
7540: 20 69 2d 74 68 20 70 61 72 61 6d 65 74 65 72 2e i-th parameter.
7550: 20 20 4f 72 64 69 6e 61 72 79 20 70 61 72 61 6d Ordinary param
7560: 65 74 65 72 73 20 22 3f 22 20 61 72 65 0a 2a 2a eters "?" are.**
7570: 20 6e 61 6d 65 6c 65 73 73 20 61 6e 64 20 61 20 nameless and a
7580: 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 NULL is returned
7590: 2e 20 20 46 6f 72 20 70 61 72 61 6d 65 74 65 72 . For parameter
75a0: 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 3a 41 s of the form :A
75b0: 41 41 20 6f 72 0a 2a 2a 20 24 56 56 56 20 74 68 AA or.** $VVV th
75c0: 65 20 63 6f 6d 70 6c 65 74 65 20 74 65 78 74 20 e complete text
75d0: 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 of the parameter
75e0: 20 6e 61 6d 65 20 69 73 20 72 65 74 75 72 6e 65 name is returne
75f0: 64 2c 20 69 6e 63 6c 75 64 69 6e 67 0a 2a 2a 20 d, including.**
7600: 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 the initial ":"
7610: 6f 72 20 22 24 22 2e 20 20 4e 55 4c 4c 20 69 73 or "$". NULL is
7620: 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 returned if the
7630: 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 index is out of
7640: 20 72 61 6e 67 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 range..*/.const
7650: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 char *sqlite3_b
7660: 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
7670: 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
7680: 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 52 , int);../*.** R
7690: 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 eturn the index
76a0: 6f 66 20 61 20 70 61 72 61 6d 65 74 65 72 20 77 of a parameter w
76b0: 69 74 68 20 74 68 65 20 67 69 76 65 6e 20 6e 61 ith the given na
76c0: 6d 65 2e 20 20 54 68 65 20 6e 61 6d 65 0a 2a 2a me. The name.**
76d0: 20 6d 75 73 74 20 6d 61 74 63 68 20 65 78 61 63 must match exac
76e0: 74 6c 79 2e 20 20 49 66 20 6e 6f 20 70 61 72 61 tly. If no para
76f0: 6d 65 74 65 72 20 77 69 74 68 20 74 68 65 20 67 meter with the g
7700: 69 76 65 6e 20 6e 61 6d 65 20 69 73 20 66 6f 75 iven name is fou
7710: 6e 64 2c 0a 2a 2a 20 72 65 74 75 72 6e 20 30 2e nd,.** return 0.
7720: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
7730: 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
7740: 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d ndex(sqlite3_stm
7750: 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a t*, const char *
7760: 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 zName);../*.** S
7770: 65 74 20 61 6c 6c 20 74 68 65 20 70 61 72 61 6d et all the param
7780: 65 74 65 72 73 20 69 6e 20 74 68 65 20 63 6f 6d eters in the com
7790: 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d piled SQL statem
77a0: 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a ent to NULL..*/.
77b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 int sqlite3_clea
77c0: 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
77d0: 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
77e0: 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d * Return the num
77f0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
7800: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 n the result set
7810: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
7820: 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c compiled.** SQL
7830: 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 69 73 statement. This
7840: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
7850: 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 0 if pStmt is a
7860: 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a n SQL statement.
7870: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 ** that does not
7880: 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f return data (fo
7890: 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 55 50 44 r example an UPD
78a0: 41 54 45 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ATE)..*/.int sql
78b0: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e ite3_column_coun
78c0: 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
78d0: 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 pStmt);../*.** T
78e0: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
78f0: 65 72 20 69 73 20 61 20 63 6f 6d 70 69 6c 65 64 er is a compiled
7900: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 SQL statement.
7910: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
7920: 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 63 6f 6c turns.** the col
7930: 75 6d 6e 20 68 65 61 64 69 6e 67 20 66 6f 72 20 umn heading for
7940: 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f the Nth column o
7950: 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 f that statement
7960: 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
7970: 0a 2a 2a 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 .** second funct
7980: 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 2e 20 20 ion parameter.
7990: 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 The string retur
79a0: 6e 65 64 20 69 73 20 55 54 46 2d 38 20 66 6f 72 ned is UTF-8 for
79b0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
79c0: 6d 6e 5f 6e 61 6d 65 28 29 20 61 6e 64 20 55 54 mn_name() and UT
79d0: 46 2d 31 36 20 66 6f 72 20 73 71 6c 69 74 65 33 F-16 for sqlite3
79e0: 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 _column_name16()
79f0: 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 ..*/.const char
7a00: 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
7a10: 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
7a20: 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 t*,int);.const v
7a30: 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
7a40: 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 umn_name16(sqlit
7a50: 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a e3_stmt*,int);..
7a60: 2f 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 /*.** The first
7a70: 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 63 parameter is a c
7a80: 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 ompiled SQL stat
7a90: 65 6d 65 6e 74 2e 20 49 66 20 74 68 69 73 20 73 ement. If this s
7aa0: 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 tatement.** is a
7ab0: 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e SELECT statemen
7ac0: 74 2c 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d t, the Nth colum
7ad0: 6e 20 6f 66 20 74 68 65 20 72 65 74 75 72 6e 65 n of the returne
7ae0: 64 20 72 65 73 75 6c 74 20 73 65 74 20 0a 2a 2a d result set .**
7af0: 20 6f 66 20 74 68 65 20 53 45 4c 45 43 54 20 69 of the SELECT i
7b00: 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e s a table column
7b10: 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 then the declar
7b20: 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 ed type of the t
7b30: 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 able.** column i
7b40: 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20 74 s returned. If t
7b50: 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
7b60: 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
7b70: 69 73 20 6e 6f 74 20 61 74 20 74 61 62 6c 65 0a is not at table.
7b80: 2a 2a 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 ** column, then
7b90: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
7ba0: 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 20 s returned. The
7bb0: 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
7bc0: 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 55 54 46 is always.** UTF
7bd0: 2d 38 20 65 6e 63 6f 64 65 64 2e 20 46 6f 72 20 -8 encoded. For
7be0: 65 78 61 6d 70 6c 65 2c 20 69 6e 20 74 68 65 20 example, in the
7bf0: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a database schema:
7c00: 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 .**.** CREATE TA
7c10: 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e BLE t1(c1 VARIAN
7c20: 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20 74 68 T);.**.** And th
7c30: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 e following stat
7c40: 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64 3a 0a ement compiled:.
7c50: 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 **.** SELECT c1
7c60: 2b 20 31 2c 20 30 20 46 52 4f 4d 20 74 31 3b 0a + 1, 0 FROM t1;.
7c70: 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68 69 73 20 **.** Then this
7c80: 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 routine would re
7c90: 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 turn the string
7ca0: 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 "VARIANT" for th
7cb0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 65 73 75 e second.** resu
7cc0: 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 lt column (i==1)
7cd0: 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 , and a NULL poi
7ce0: 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 nter for the fir
7cf0: 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e st result column
7d00: 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a 2f 0a 63 .** (i==0)..*/.c
7d10: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
7d20: 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
7d30: 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 pe(sqlite3_stmt
7d40: 2a 2c 20 69 6e 74 20 69 29 3b 0a 0a 2f 2a 0a 2a *, int i);../*.*
7d50: 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 * The first para
7d60: 6d 65 74 65 72 20 69 73 20 61 20 63 6f 6d 70 69 meter is a compi
7d70: 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e led SQL statemen
7d80: 74 2e 20 49 66 20 74 68 69 73 20 73 74 61 74 65 t. If this state
7d90: 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 20 53 45 4c ment.** is a SEL
7da0: 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 ECT statement, t
7db0: 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
7dc0: 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 72 65 the returned re
7dd0: 73 75 6c 74 20 73 65 74 20 0a 2a 2a 20 6f 66 20 sult set .** of
7de0: 74 68 65 20 53 45 4c 45 43 54 20 69 73 20 61 20 the SELECT is a
7df0: 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 65 table column the
7e00: 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 n the declared t
7e10: 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 ype of the table
7e20: 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 .** column is re
7e30: 74 75 72 6e 65 64 2e 20 49 66 20 74 68 65 20 4e turned. If the N
7e40: 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 th column of the
7e50: 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 6e result set is n
7e60: 6f 74 20 61 74 20 74 61 62 6c 65 0a 2a 2a 20 63 ot at table.** c
7e70: 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 61 20 4e 55 olumn, then a NU
7e80: 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 LL pointer is re
7e90: 74 75 72 6e 65 64 2e 20 54 68 65 20 72 65 74 75 turned. The retu
7ea0: 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 rned string is a
7eb0: 6c 77 61 79 73 0a 2a 2a 20 55 54 46 2d 31 36 20 lways.** UTF-16
7ec0: 65 6e 63 6f 64 65 64 2e 20 46 6f 72 20 65 78 61 encoded. For exa
7ed0: 6d 70 6c 65 2c 20 69 6e 20 74 68 65 20 64 61 74 mple, in the dat
7ee0: 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a abase schema:.**
7ef0: 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 .** CREATE TABLE
7f00: 20 74 31 28 63 31 20 49 4e 54 45 47 45 52 29 3b t1(c1 INTEGER);
7f10: 0a 2a 2a 0a 2a 2a 20 41 6e 64 20 74 68 65 20 66 .**.** And the f
7f20: 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 ollowing stateme
7f30: 6e 74 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a nt compiled:.**.
7f40: 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 ** SELECT c1 + 1
7f50: 2c 20 30 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a , 0 FROM t1;.**.
7f60: 2a 2a 20 54 68 65 6e 20 74 68 69 73 20 72 6f 75 ** Then this rou
7f70: 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 tine would retur
7f80: 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 49 4e n the string "IN
7f90: 54 45 47 45 52 22 20 66 6f 72 20 74 68 65 20 73 TEGER" for the s
7fa0: 65 63 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20 econd.** result
7fb0: 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 column (i==1), a
7fc0: 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 nd a NULL pointe
7fd0: 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 r for the first
7fe0: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a result column.**
7ff0: 20 28 69 3d 3d 30 29 2e 0a 2a 2f 0a 63 6f 6e 73 (i==0)..*/.cons
8000: 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
8010: 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 column_decltype1
8020: 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
8030: 69 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20 41 66 int);../* .** Af
8040: 74 65 72 20 61 6e 20 53 51 4c 20 71 75 65 72 79 ter an SQL query
8050: 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c has been compil
8060: 65 64 20 77 69 74 68 20 61 20 63 61 6c 6c 20 74 ed with a call t
8070: 6f 20 65 69 74 68 65 72 0a 2a 2a 20 73 71 6c 69 o either.** sqli
8080: 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 6f 72 te3_prepare() or
8090: 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
80a0: 31 36 28 29 2c 20 74 68 65 6e 20 74 68 69 73 20 16(), then this
80b0: 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 function must be
80c0: 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f .** called one o
80d0: 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 r more times to
80e0: 65 78 65 63 75 74 65 20 74 68 65 20 73 74 61 74 execute the stat
80f0: 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ement..**.** The
8100: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 return value wi
8110: 6c 6c 20 62 65 20 65 69 74 68 65 72 20 53 51 4c ll be either SQL
8120: 49 54 45 5f 42 55 53 59 2c 20 53 51 4c 49 54 45 ITE_BUSY, SQLITE
8130: 5f 44 4f 4e 45 2c 20 0a 2a 2a 20 53 51 4c 49 54 _DONE, .** SQLIT
8140: 45 5f 52 4f 57 2c 20 53 51 4c 49 54 45 5f 45 52 E_ROW, SQLITE_ER
8150: 52 4f 52 2c 20 6f 72 20 53 51 4c 49 54 45 5f 4d ROR, or SQLITE_M
8160: 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c ISUSE..**.** SQL
8170: 49 54 45 5f 42 55 53 59 20 6d 65 61 6e 73 20 74 ITE_BUSY means t
8180: 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 hat the database
8190: 20 65 6e 67 69 6e 65 20 61 74 74 65 6d 70 74 65 engine attempte
81a0: 64 20 74 6f 20 6f 70 65 6e 0a 2a 2a 20 61 20 6c d to open.** a l
81b0: 6f 63 6b 65 64 20 64 61 74 61 62 61 73 65 20 61 ocked database a
81c0: 6e 64 20 74 68 65 72 65 20 69 73 20 6e 6f 20 62 nd there is no b
81d0: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 usy callback reg
81e0: 69 73 74 65 72 65 64 2e 0a 2a 2a 20 43 61 6c 6c istered..** Call
81f0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
8200: 61 67 61 69 6e 20 74 6f 20 72 65 74 72 79 20 74 again to retry t
8210: 68 65 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a 2a 20 53 he open..**.** S
8220: 51 4c 49 54 45 5f 44 4f 4e 45 20 6d 65 61 6e 73 QLITE_DONE means
8230: 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d that the statem
8240: 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 ent has finished
8250: 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 executing.** su
8260: 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c ccessfully. sql
8270: 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 ite3_step() shou
8280: 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 ld not be called
8290: 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 again on this v
82a0: 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e irtual.** machin
82b0: 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 e..**.** If the
82c0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 SQL statement be
82d0: 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 ing executed ret
82e0: 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 urns any data, t
82f0: 68 65 6e 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 52 hen .** SQLITE_R
8300: 4f 57 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 OW is returned e
8310: 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 ach time a new r
8320: 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 ow of data is re
8330: 61 64 79 0a 2a 2a 20 66 6f 72 20 70 72 6f 63 65 ady.** for proce
8340: 73 73 69 6e 67 20 62 79 20 74 68 65 20 63 61 6c ssing by the cal
8350: 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 ler. The values
8360: 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 may be accessed
8370: 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 73 71 6c using.** the sql
8380: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 20 ite3_column_*()
8390: 66 75 6e 63 74 69 6f 6e 73 20 64 65 73 63 72 69 functions descri
83a0: 62 65 64 20 62 65 6c 6f 77 2e 20 73 71 6c 69 74 bed below. sqlit
83b0: 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 69 73 20 e3_step().** is
83c0: 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 called again to
83d0: 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 retrieve the nex
83e0: 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a t row of data..*
83f0: 2a 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 52 52 * .** SQLITE_ERR
8400: 4f 52 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 OR means that a
8410: 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 run-time error (
8420: 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 such as a constr
8430: 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f aint.** violatio
8440: 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e n) has occurred.
8450: 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 sqlite3_step()
8460: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 should not be c
8470: 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a alled again on.*
8480: 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 * the VM. More i
8490: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 nformation may b
84a0: 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 e found by calli
84b0: 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 ng sqlite3_errms
84c0: 67 28 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 49 54 g()..**.** SQLIT
84d0: 45 5f 4d 49 53 55 53 45 20 6d 65 61 6e 73 20 74 E_MISUSE means t
84e0: 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 hat the this rou
84f0: 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 tine was called
8500: 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e inappropriately.
8510: 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 .** Perhaps it w
8520: 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 76 as called on a v
8530: 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 irtual machine t
8540: 68 61 74 20 68 61 64 20 61 6c 72 65 61 64 79 20 hat had already
8550: 62 65 65 6e 0a 2a 2a 20 66 69 6e 61 6c 69 7a 65 been.** finalize
8560: 64 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 d or on one that
8570: 20 68 61 64 20 70 72 65 76 69 6f 75 73 6c 79 20 had previously
8580: 72 65 74 75 72 6e 65 64 20 53 51 4c 49 54 45 5f returned SQLITE_
8590: 45 52 52 4f 52 20 6f 72 0a 2a 2a 20 53 51 4c 49 ERROR or.** SQLI
85a0: 54 45 5f 44 4f 4e 45 2e 20 20 4f 72 20 69 74 20 TE_DONE. Or it
85b0: 63 6f 75 6c 64 20 62 65 20 74 68 65 20 63 61 73 could be the cas
85c0: 65 20 74 68 65 20 74 68 65 20 73 61 6d 65 20 64 e the the same d
85d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
85e0: 6f 6e 0a 2a 2a 20 69 73 20 62 65 69 6e 67 20 75 on.** is being u
85f0: 73 65 64 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 sed simulataneou
8600: 73 6c 79 20 62 79 20 74 77 6f 20 6f 72 20 6d 6f sly by two or mo
8610: 72 65 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 69 re threads..*/.i
8620: 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 nt sqlite3_step(
8630: 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
8640: 0a 2f 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 ./*.** Return th
8650: 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 e number of valu
8660: 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e es in the curren
8670: 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 t row of the res
8680: 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 41 ult set..**.** A
8690: 66 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 73 fter a call to s
86a0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 74 68 qlite3_step() th
86b0: 61 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 at returns SQLIT
86c0: 45 5f 52 4f 57 2c 20 74 68 69 73 20 72 6f 75 74 E_ROW, this rout
86d0: 69 6e 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 ine.** will retu
86e0: 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 rn the same valu
86f0: 65 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 e as the sqlite3
8700: 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 _column_count()
8710: 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 41 66 74 function..** Aft
8720: 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 er sqlite3_step(
8730: 29 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 ) has returned a
8740: 6e 20 53 51 4c 49 54 45 5f 44 4f 4e 45 2c 20 53 n SQLITE_DONE, S
8750: 51 4c 49 54 45 5f 42 55 53 59 20 6f 72 0a 2a 2a QLITE_BUSY or.**
8760: 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 6f 72 20 error code, or
8770: 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 before sqlite3_s
8780: 74 65 70 28 29 20 68 61 73 20 62 65 65 6e 20 63 tep() has been c
8790: 61 6c 6c 65 64 20 6f 6e 20 61 20 0a 2a 2a 20 63 alled on a .** c
87a0: 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 ompiled SQL stat
87b0: 65 6d 65 6e 74 2c 20 74 68 69 73 20 72 6f 75 74 ement, this rout
87c0: 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f ine returns zero
87d0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
87e0: 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 _data_count(sqli
87f0: 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
8800: 3b 0a 0a 2f 2a 0a 2a 2a 20 56 61 6c 75 65 73 20 ;../*.** Values
8810: 61 72 65 20 73 74 6f 72 65 64 20 69 6e 20 74 68 are stored in th
8820: 65 20 64 61 74 61 62 61 73 65 20 69 6e 20 6f 6e e database in on
8830: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
8840: 6e 67 20 66 75 6e 64 61 6d 65 6e 74 61 6c 0a 2a ng fundamental.*
8850: 2a 20 74 79 70 65 73 2e 0a 2a 2f 0a 23 64 65 66 * types..*/.#def
8860: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 ine SQLITE_INTEG
8870: 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 ER 1.#define SQ
8880: 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a LITE_FLOAT 2.
8890: 2f 2a 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 /* #define SQLIT
88a0: 45 5f 54 45 58 54 20 20 33 20 20 2f 2f 20 53 65 E_TEXT 3 // Se
88b0: 65 20 62 65 6c 6f 77 20 2a 2f 0a 23 64 65 66 69 e below */.#defi
88c0: 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 ne SQLITE_BLOB
88d0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
88e0: 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 0a ITE_NULL 5..
88f0: 2f 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 /*.** SQLite ver
8900: 73 69 6f 6e 20 32 20 64 65 66 69 6e 65 73 20 53 sion 2 defines S
8910: 51 4c 49 54 45 5f 54 45 58 54 20 64 69 66 66 65 QLITE_TEXT diffe
8920: 72 65 6e 74 6c 79 2e 20 20 54 6f 20 61 6c 6c 6f rently. To allo
8930: 77 20 62 6f 74 68 0a 2a 2a 20 76 65 72 73 69 6f w both.** versio
8940: 6e 20 32 20 61 6e 64 20 76 65 72 73 69 6f 6e 20 n 2 and version
8950: 33 20 74 6f 20 62 65 20 69 6e 63 6c 75 64 65 64 3 to be included
8960: 2c 20 75 6e 64 65 66 69 6e 65 20 74 68 65 6d 20 , undefine them
8970: 62 6f 74 68 20 69 66 20 61 0a 2a 2a 20 63 6f 6e both if a.** con
8980: 66 6c 69 63 74 20 69 73 20 73 65 65 6e 2e 20 20 flict is seen.
8990: 44 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 Define SQLITE3_T
89a0: 45 58 54 20 74 6f 20 62 65 20 74 68 65 20 76 65 EXT to be the ve
89b0: 72 73 69 6f 6e 20 33 20 76 61 6c 75 65 2e 0a 2a rsion 3 value..*
89c0: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f /.#ifdef SQLITE_
89d0: 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c TEXT.# undef SQL
89e0: 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 ITE_TEXT.#else.#
89f0: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 define SQLITE_T
8a00: 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 EXT 3.#endif
8a10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 .#define SQLITE3
8a20: 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a _TEXT 3../*.
8a30: 2a 2a 20 54 68 65 20 6e 65 78 74 20 67 72 6f 75 ** The next grou
8a40: 70 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 p of routines re
8a50: 74 75 72 6e 73 20 69 6e 66 6f 72 6d 61 74 69 6f turns informatio
8a60: 6e 20 61 62 6f 75 74 20 74 68 65 20 69 6e 66 6f n about the info
8a70: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 69 6e 20 61 20 rmation.** in a
8a80: 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 single column of
8a90: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73 the current res
8aa0: 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 ult row of a que
8ab0: 72 79 2e 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a ry. In every.**
8ac0: 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 case the first
8ad0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
8ae0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 53 51 ointer to the SQ
8af0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 L statement that
8b00: 20 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 78 65 is being.** exe
8b10: 63 75 74 65 64 20 28 74 68 65 20 73 71 6c 69 74 cuted (the sqlit
8b20: 65 5f 73 74 6d 74 2a 20 74 68 61 74 20 77 61 73 e_stmt* that was
8b30: 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 73 returned from s
8b40: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
8b50: 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20 73 65 63 ) and.** the sec
8b60: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
8b70: 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 the index of the
8b80: 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 column for whic
8b90: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a h information .*
8ba0: 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 * should be retu
8bb0: 72 6e 65 64 2e 20 20 69 43 6f 6c 20 69 73 20 7a rned. iCol is z
8bc0: 65 72 6f 2d 69 6e 64 65 78 65 64 2e 20 20 54 68 ero-indexed. Th
8bd0: 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 e left-most colu
8be0: 6d 6e 20 61 73 20 61 6e 0a 2a 2a 20 69 6e 64 65 mn as an.** inde
8bf0: 78 20 6f 66 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 x of 0..**.** If
8c00: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
8c10: 6e 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e nt is not curren
8c20: 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 tly point to a v
8c30: 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 alid row, or if
8c40: 74 68 65 0a 2a 2a 20 74 68 65 20 63 6f 6c 75 6c the.** the colul
8c50: 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 mn index is out
8c60: 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 of range, the re
8c70: 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 sult is undefine
8c80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 d..**.** These r
8c90: 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 outines attempt
8ca0: 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 to convert the v
8cb0: 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f alue where appro
8cc0: 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 priate. For.**
8cd0: 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 example, if the
8ce0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
8cf0: 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 ntation is FLOAT
8d00: 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 and a text resu
8d10: 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 lt.** is request
8d20: 65 64 2c 20 73 70 72 69 6e 74 66 28 29 20 69 73 ed, sprintf() is
8d30: 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 used internally
8d40: 20 74 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76 65 to do the conve
8d50: 72 73 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 rsion.** automat
8d60: 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c ically. The fol
8d70: 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 lowing table det
8d80: 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 ails the convers
8d90: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 ions that.** are
8da0: 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 applied:.**.**
8db0: 20 20 20 49 6e 74 65 72 6e 61 6c 20 54 79 70 65 Internal Type
8dc0: 20 20 20 20 52 65 71 75 65 73 74 65 64 20 54 79 Requested Ty
8dd0: 70 65 20 20 20 20 20 43 6f 6e 76 65 72 73 69 6f pe Conversio
8de0: 6e 0a 2a 2a 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d n.** --------
8df0: 2d 2d 2d 2d 2d 20 20 20 20 2d 2d 2d 2d 2d 2d 2d ----- -------
8e00: 2d 2d 2d 2d 2d 2d 2d 20 20 20 20 2d 2d 2d 2d 2d ------- -----
8e10: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
8e20: 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 4e -----.** N
8e30: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 ULL
8e40: 49 4e 54 45 47 45 52 20 20 20 20 20 20 20 20 20 INTEGER
8e50: 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 20 Result is 0.**
8e60: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
8e70: 20 20 20 20 20 20 46 4c 4f 41 54 20 20 20 20 20 FLOAT
8e80: 20 20 20 20 20 20 52 65 73 75 6c 74 20 69 73 20 Result is
8e90: 30 2e 30 0a 2a 2a 20 20 20 20 20 20 20 4e 55 4c 0.0.** NUL
8ea0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 54 45 L TE
8eb0: 58 54 20 20 20 20 20 20 20 20 20 20 20 20 52 65 XT Re
8ec0: 73 75 6c 74 20 69 73 20 61 6e 20 65 6d 70 74 79 sult is an empty
8ed0: 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 string.**
8ee0: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
8ef0: 20 20 42 4c 4f 42 20 20 20 20 20 20 20 20 20 20 BLOB
8f00: 20 20 52 65 73 75 6c 74 20 69 73 20 61 20 7a 65 Result is a ze
8f10: 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 0a 2a ro-length BLOB.*
8f20: 2a 20 20 20 20 20 20 20 49 4e 54 45 47 45 52 20 * INTEGER
8f30: 20 20 20 20 20 20 20 20 20 46 4c 4f 41 54 20 20 FLOAT
8f40: 20 20 20 20 20 20 20 20 20 43 6f 6e 76 65 72 74 Convert
8f50: 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f from integer to
8f60: 20 66 6c 6f 61 74 0a 2a 2a 20 20 20 20 20 20 20 float.**
8f70: 49 4e 54 45 47 45 52 20 20 20 20 20 20 20 20 20 INTEGER
8f80: 20 54 45 58 54 20 20 20 20 20 20 20 20 20 20 20 TEXT
8f90: 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 ASCII rendering
8fa0: 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a of the integer.
8fb0: 2a 2a 20 20 20 20 20 20 20 49 4e 54 45 47 45 52 ** INTEGER
8fc0: 20 20 20 20 20 20 20 20 20 20 42 4c 4f 42 20 20 BLOB
8fd0: 20 20 20 20 20 20 20 20 20 20 53 61 6d 65 20 61 Same a
8fe0: 73 20 66 6f 72 20 49 4e 54 45 47 45 52 2d 3e 54 s for INTEGER->T
8ff0: 45 58 54 0a 2a 2a 20 20 20 20 20 20 20 46 4c 4f EXT.** FLO
9000: 41 54 20 20 20 20 20 20 20 20 20 20 20 20 49 4e AT IN
9010: 54 45 47 45 52 20 20 20 20 20 20 20 20 20 43 6f TEGER Co
9020: 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 nvert from float
9030: 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 to integer.**
9040: 20 20 20 20 20 46 4c 4f 41 54 20 20 20 20 20 20 FLOAT
9050: 20 20 20 20 20 20 54 45 58 54 20 20 20 20 20 20 TEXT
9060: 20 20 20 20 20 20 41 53 43 49 49 20 72 65 6e 64 ASCII rend
9070: 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f ering of the flo
9080: 61 74 0a 2a 2a 20 20 20 20 20 20 20 46 4c 4f 41 at.** FLOA
9090: 54 20 20 20 20 20 20 20 20 20 20 20 20 42 4c 4f T BLO
90a0: 42 20 20 20 20 20 20 20 20 20 20 20 20 53 61 6d B Sam
90b0: 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 e as FLOAT->TEXT
90c0: 0a 2a 2a 20 20 20 20 20 20 20 54 45 58 54 20 20 .** TEXT
90d0: 20 20 20 20 20 20 20 20 20 20 20 49 4e 54 45 47 INTEG
90e0: 45 52 20 20 20 20 20 20 20 20 20 55 73 65 20 61 ER Use a
90f0: 74 6f 69 28 29 0a 2a 2a 20 20 20 20 20 20 20 54 toi().** T
9100: 45 58 54 20 20 20 20 20 20 20 20 20 20 20 20 20 EXT
9110: 46 4c 4f 41 54 20 20 20 20 20 20 20 20 20 20 20 FLOAT
9120: 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 20 20 Use atof().**
9130: 20 20 20 20 54 45 58 54 20 20 20 20 20 20 20 20 TEXT
9140: 20 20 20 20 20 42 4c 4f 42 20 20 20 20 20 20 20 BLOB
9150: 20 20 20 20 20 4e 6f 20 63 68 61 6e 67 65 0a 2a No change.*
9160: 2a 20 20 20 20 20 20 20 42 4c 4f 42 20 20 20 20 * BLOB
9170: 20 20 20 20 20 20 20 20 20 49 4e 54 45 47 45 52 INTEGER
9180: 20 20 20 20 20 20 20 20 20 43 6f 6e 76 65 72 74 Convert
9190: 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 to TEXT then us
91a0: 65 20 61 74 6f 69 28 29 0a 2a 2a 20 20 20 20 20 e atoi().**
91b0: 20 20 42 4c 4f 42 20 20 20 20 20 20 20 20 20 20 BLOB
91c0: 20 20 20 46 4c 4f 41 54 20 20 20 20 20 20 20 20 FLOAT
91d0: 20 20 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 Convert to TE
91e0: 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 XT then use atof
91f0: 28 29 0a 2a 2a 20 20 20 20 20 20 20 42 4c 4f 42 ().** BLOB
9200: 20 20 20 20 20 20 20 20 20 20 20 20 20 54 45 58 TEX
9210: 54 20 20 20 20 20 20 20 20 20 20 20 20 41 64 64 T Add
9220: 20 61 20 5c 30 30 30 20 74 65 72 6d 69 6e 61 74 a \000 terminat
9230: 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 0a or if needed.**.
9240: 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ** The following
9250: 20 61 63 63 65 73 73 20 72 6f 75 74 69 6e 65 73 access routines
9260: 20 61 72 65 20 70 72 6f 76 69 64 65 64 3a 0a 2a are provided:.*
9270: 2a 0a 2a 2a 20 5f 74 79 70 65 28 29 20 20 20 20 *.** _type()
9280: 20 52 65 74 75 72 6e 20 74 68 65 20 64 61 74 61 Return the data
9290: 74 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 type of the resu
92a0: 6c 74 2e 20 20 54 68 69 73 20 69 73 20 6f 6e 65 lt. This is one
92b0: 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 of.**
92c0: 20 20 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 SQLITE_INTEGE
92d0: 52 2c 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 2c R, SQLITE_FLOAT,
92e0: 20 53 51 4c 49 54 45 5f 54 45 58 54 2c 20 53 51 SQLITE_TEXT, SQ
92f0: 4c 49 54 45 5f 42 4c 4f 42 2c 0a 2a 2a 20 20 20 LITE_BLOB,.**
9300: 20 20 20 20 20 20 20 20 20 20 6f 72 20 53 51 4c or SQL
9310: 49 54 45 5f 4e 55 4c 4c 2e 0a 2a 2a 20 5f 62 6c ITE_NULL..** _bl
9320: 6f 62 28 29 20 20 20 20 20 52 65 74 75 72 6e 20 ob() Return
9330: 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 42 the value of a B
9340: 4c 4f 42 2e 0a 2a 2a 20 5f 62 79 74 65 73 28 29 LOB..** _bytes()
9350: 20 20 20 20 52 65 74 75 72 6e 20 74 68 65 20 6e Return the n
9360: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
9370: 6e 20 61 20 42 4c 4f 42 20 76 61 6c 75 65 20 6f n a BLOB value o
9380: 72 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 r the number.**
9390: 20 20 20 20 20 20 20 20 20 20 20 20 6f 66 20 62 of b
93a0: 79 74 65 73 20 69 6e 20 61 20 54 45 58 54 20 76 ytes in a TEXT v
93b0: 61 6c 75 65 20 72 65 70 72 65 73 65 6e 74 65 64 alue represented
93c0: 20 61 73 20 55 54 46 2d 38 2e 20 20 54 68 65 20 as UTF-8. The
93d0: 5c 30 30 30 0a 2a 2a 20 20 20 20 20 20 20 20 20 \000.**
93e0: 20 20 20 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 terminator i
93f0: 73 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 s included in th
9400: 65 20 62 79 74 65 20 63 6f 75 6e 74 20 66 6f 72 e byte count for
9410: 20 54 45 58 54 20 76 61 6c 75 65 73 2e 0a 2a 2a TEXT values..**
9420: 20 5f 62 79 74 65 73 31 36 28 29 20 20 52 65 74 _bytes16() Ret
9430: 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f urn the number o
9440: 66 20 62 79 74 65 73 20 69 6e 20 61 20 42 4c 4f f bytes in a BLO
9450: 42 20 76 61 6c 75 65 20 6f 72 20 74 68 65 20 6e B value or the n
9460: 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 umber.**
9470: 20 20 20 20 20 6f 66 20 62 79 74 65 73 20 69 6e of bytes in
9480: 20 61 20 54 45 58 54 20 76 61 6c 75 65 20 72 65 a TEXT value re
9490: 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 presented as UTF
94a0: 2d 31 36 2e 20 20 54 68 65 20 5c 75 30 30 30 30 -16. The \u0000
94b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 .**
94c0: 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 69 6e terminator is in
94d0: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 62 79 cluded in the by
94e0: 74 65 20 63 6f 75 6e 74 20 66 6f 72 20 54 45 58 te count for TEX
94f0: 54 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 5f 64 6f T values..** _do
9500: 75 62 6c 65 28 29 20 20 20 52 65 74 75 72 6e 20 uble() Return
9510: 61 20 46 4c 4f 41 54 20 76 61 6c 75 65 2e 0a 2a a FLOAT value..*
9520: 2a 20 5f 69 6e 74 28 29 20 20 20 20 20 20 52 65 * _int() Re
9530: 74 75 72 6e 20 61 6e 20 49 4e 54 45 47 45 52 20 turn an INTEGER
9540: 76 61 6c 75 65 20 69 6e 20 74 68 65 20 68 6f 73 value in the hos
9550: 74 20 63 6f 6d 70 75 74 65 72 27 73 20 6e 61 74 t computer's nat
9560: 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ive.**
9570: 20 20 20 69 6e 74 65 67 65 72 20 72 65 70 72 65 integer repre
9580: 73 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 69 73 sentation. This
9590: 20 6d 69 67 68 74 20 62 65 20 65 69 74 68 65 72 might be either
95a0: 20 61 20 33 32 2d 20 6f 72 20 36 34 2d 62 69 74 a 32- or 64-bit
95b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 .**
95c0: 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e integer dependin
95d0: 67 20 6f 6e 20 74 68 65 20 68 6f 73 74 2e 0a 2a g on the host..*
95e0: 2a 20 5f 69 6e 74 36 34 28 29 20 20 20 20 52 65 * _int64() Re
95f0: 74 75 72 6e 20 61 6e 20 49 4e 54 45 47 45 52 20 turn an INTEGER
9600: 76 61 6c 75 65 20 61 73 20 61 20 36 34 2d 62 69 value as a 64-bi
9610: 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 t signed integer
9620: 2e 0a 2a 2a 20 5f 74 65 78 74 28 29 20 20 20 20 ..** _text()
9630: 20 52 65 74 75 72 6e 20 74 68 65 20 76 61 6c 75 Return the valu
9640: 65 20 61 73 20 55 54 46 2d 38 20 74 65 78 74 2e e as UTF-8 text.
9650: 0a 2a 2a 20 5f 74 65 78 74 31 36 28 29 20 20 20 .** _text16()
9660: 52 65 74 75 72 6e 20 74 68 65 20 76 61 6c 75 65 Return the value
9670: 20 61 73 20 55 54 46 2d 31 36 20 74 65 78 74 2e as UTF-16 text.
9680: 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a .*/.const void *
9690: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
96a0: 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
96b0: 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e *, int iCol);.in
96c0: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
96d0: 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 _bytes(sqlite3_s
96e0: 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
96f0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
9700: 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 umn_bytes16(sqli
9710: 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
9720: 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c Col);.double sql
9730: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 ite3_column_doub
9740: 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
9750: 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 , int iCol);.int
9760: 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
9770: 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 int(sqlite3_stmt
9780: 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 *, int iCol);.sq
9790: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 lite_int64 sqlit
97a0: 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 e3_column_int64(
97b0: 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
97c0: 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 nt iCol);.const
97d0: 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 unsigned char *s
97e0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
97f0: 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a xt(sqlite3_stmt*
9800: 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e , int iCol);.con
9810: 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
9820: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 _column_text16(s
9830: 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
9840: 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c t iCol);.int sql
9850: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
9860: 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
9870: 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a int iCol);../*.*
9880: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 * The sqlite3_fi
9890: 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f nalize() functio
98a0: 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 n is called to d
98b0: 65 6c 65 74 65 20 61 20 63 6f 6d 70 69 6c 65 64 elete a compiled
98c0: 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
98d0: 74 20 6f 62 74 61 69 6e 65 64 20 62 79 20 61 20 t obtained by a
98e0: 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
98f0: 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
9900: 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
9910: 5f 70 72 65 70 61 72 65 31 36 28 29 2e 20 49 66 _prepare16(). If
9920: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 the statement w
9930: 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63 63 as executed succ
9940: 65 73 73 66 75 6c 6c 79 2c 20 6f 72 0a 2a 2a 20 essfully, or.**
9950: 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20 not executed at
9960: 61 6c 6c 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 all, then SQLITE
9970: 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e _OK is returned.
9980: 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 If execution of
9990: 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e the.** statemen
99a0: 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e t failed then an
99b0: 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 error code is r
99c0: 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 eturned. .**.**
99d0: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e This routine can
99e0: 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e be called at an
99f0: 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 y point during t
9a00: 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 he execution of
9a10: 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d the.** virtual m
9a20: 61 63 68 69 6e 65 2e 20 20 49 66 20 74 68 65 20 achine. If the
9a30: 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
9a40: 68 61 73 20 6e 6f 74 20 63 6f 6d 70 6c 65 74 65 has not complete
9a50: 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 77 d execution.** w
9a60: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 hen this routine
9a70: 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 is called, that
9a80: 20 69 73 20 6c 69 6b 65 20 65 6e 63 6f 75 6e 74 is like encount
9a90: 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f ering an error o
9aa0: 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72 75 70 r.** an interrup
9ab0: 74 2e 20 20 28 53 65 65 20 73 71 6c 69 74 65 33 t. (See sqlite3
9ac0: 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 29 20 20 _interrupt().)
9ad0: 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 Incomplete updat
9ae0: 65 73 20 6d 61 79 20 62 65 0a 2a 2a 20 72 6f 6c es may be.** rol
9af0: 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 led back and tra
9b00: 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c nsactions cancel
9b10: 6c 65 64 2c 20 20 64 65 70 65 6e 64 69 6e 67 20 led, depending
9b20: 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 on the circumsta
9b30: 6e 63 65 73 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 nces,.** and the
9b40: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 72 65 74 result code ret
9b50: 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 53 51 urned will be SQ
9b60: 4c 49 54 45 5f 41 42 4f 52 54 2e 0a 2a 2f 0a 69 LITE_ABORT..*/.i
9b70: 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c nt sqlite3_final
9b80: 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ize(sqlite3_stmt
9b90: 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
9ba0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
9bb0: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 et() function is
9bc0: 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 called to reset
9bd0: 20 61 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 0a a compiled SQL.
9be0: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 74 ** statement obt
9bf0: 61 69 6e 65 64 20 62 79 20 61 20 70 72 65 76 69 ained by a previ
9c00: 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ous call to sqli
9c10: 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 6f 72 te3_prepare() or
9c20: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 .** sqlite3_prep
9c30: 61 72 65 31 36 28 29 20 62 61 63 6b 20 74 6f 20 are16() back to
9c40: 69 74 27 73 20 69 6e 69 74 69 61 6c 20 73 74 61 it's initial sta
9c50: 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 te, ready to be
9c60: 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 re-executed..**
9c70: 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e Any SQL statemen
9c80: 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 t variables that
9c90: 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e had values boun
9ca0: 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a d to them using.
9cb0: 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ** the sqlite3_b
9cc0: 69 6e 64 5f 2a 28 29 20 41 50 49 20 72 65 74 61 ind_*() API reta
9cd0: 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e in their values.
9ce0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
9cf0: 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 reset(sqlite3_st
9d00: 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
9d10: 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ** The following
9d20: 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 61 two functions a
9d30: 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 75 re used to add u
9d40: 73 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 ser functions or
9d50: 20 61 67 67 72 65 67 61 74 65 73 0a 2a 2a 20 69 aggregates.** i
9d60: 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 43 20 mplemented in C
9d70: 74 6f 20 74 68 65 20 53 51 4c 20 6c 61 6e 67 61 to the SQL langa
9d80: 75 67 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 uge interpreted
9d90: 62 79 20 53 51 4c 69 74 65 2e 20 54 68 65 0a 2a by SQLite. The.*
9da0: 2a 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c * difference onl
9db0: 79 20 62 65 74 77 65 65 6e 20 74 68 65 20 74 77 y between the tw
9dc0: 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 o is that the se
9dd0: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 cond parameter,
9de0: 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 the.** name of t
9df0: 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 he (scalar) func
9e00: 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 tion or aggregat
9e10: 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e e, is encoded in
9e20: 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 UTF-8 for.** sq
9e30: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
9e40: 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d ction() and UTF-
9e50: 31 36 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 16 for sqlite3_c
9e60: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
9e70: 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 ()..**.** The fi
9e80: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
9e90: 74 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e the database han
9ea0: 64 6c 65 20 74 68 61 74 20 74 68 65 20 6e 65 77 dle that the new
9eb0: 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 function or.**
9ec0: 61 67 67 72 65 67 61 74 65 20 69 73 20 74 6f 20 aggregate is to
9ed0: 62 65 20 61 64 64 65 64 20 74 6f 2e 20 49 66 20 be added to. If
9ee0: 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d a single program
9ef0: 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 uses more than
9f00: 6f 6e 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 one.** database
9f10: 68 61 6e 64 6c 65 20 69 6e 74 65 72 6e 61 6c 6c handle internall
9f20: 79 2c 20 74 68 65 6e 20 75 73 65 72 20 66 75 6e y, then user fun
9f30: 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 ctions or aggreg
9f40: 61 74 65 73 20 6d 75 73 74 20 0a 2a 2a 20 62 65 ates must .** be
9f50: 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 added individua
9f60: 6c 6c 79 20 74 6f 20 65 61 63 68 20 64 61 74 61 lly to each data
9f70: 62 61 73 65 20 68 61 6e 64 6c 65 20 77 69 74 68 base handle with
9f80: 20 77 68 69 63 68 20 74 68 65 79 20 77 69 6c 6c which they will
9f90: 20 62 65 0a 2a 2a 20 75 73 65 64 2e 0a 2a 2a 0a be.** used..**.
9fa0: 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 72 ** The third par
9fb0: 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 75 ameter is the nu
9fc0: 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
9fd0: 73 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 s that the funct
9fe0: 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 ion or.** aggreg
9ff0: 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 ate takes. If th
a000: 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 is parameter is
a010: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 negative, then t
a020: 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a he function or.*
a030: 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 * aggregate may
a040: 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 take any number
a050: 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a of arguments..**
a060: 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 .** The fourth p
a070: 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 arameter is one
a080: 6f 66 20 53 51 4c 49 54 45 5f 55 54 46 2a 20 76 of SQLITE_UTF* v
a090: 61 6c 75 65 73 20 64 65 66 69 6e 65 64 20 62 65 alues defined be
a0a0: 6c 6f 77 2c 0a 2a 2a 20 69 6e 64 69 63 61 74 69 low,.** indicati
a0b0: 6e 67 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 ng the encoding
a0c0: 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f that the functio
a0d0: 6e 20 69 73 20 6d 6f 73 74 20 6c 69 6b 65 6c 79 n is most likely
a0e0: 20 74 6f 20 68 61 6e 64 6c 65 0a 2a 2a 20 76 61 to handle.** va
a0f0: 6c 75 65 73 20 69 6e 2e 20 20 54 68 69 73 20 64 lues in. This d
a100: 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 oes not change t
a110: 68 65 20 62 65 68 61 76 69 6f 75 72 20 6f 66 20 he behaviour of
a120: 74 68 65 20 70 72 6f 67 72 61 6d 6d 69 6e 67 0a the programming.
a130: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 48 6f ** interface. Ho
a140: 77 65 76 65 72 2c 20 69 66 20 74 77 6f 20 76 65 wever, if two ve
a150: 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 rsions of the sa
a160: 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 me function are
a170: 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 77 69 registered.** wi
a180: 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 th different enc
a190: 6f 64 69 6e 67 20 76 61 6c 75 65 73 2c 20 53 51 oding values, SQ
a1a0: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 Lite invokes the
a1b0: 20 76 65 72 73 69 6f 6e 20 6c 69 6b 65 6c 79 20 version likely
a1c0: 74 6f 0a 2a 2a 20 6d 69 6e 69 6d 69 7a 65 20 63 to.** minimize c
a1d0: 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 onversions betwe
a1e0: 65 6e 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 en text encoding
a1f0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 s..**.** The sev
a200: 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 enth, eighth and
a210: 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 ninth parameter
a220: 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 s, xFunc, xStep
a230: 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a and xFinal, are.
a240: 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 75 ** pointers to u
a250: 73 65 72 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 ser implemented
a260: 43 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 C functions that
a270: 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 75 implement the u
a280: 73 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ser.** function
a290: 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 or aggregate. A
a2a0: 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 20 scalar function
a2b0: 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c requires an impl
a2c0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a ementation of.**
a2d0: 20 74 68 65 20 78 46 75 6e 63 20 63 61 6c 6c 62 the xFunc callb
a2e0: 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 ack only, NULL p
a2f0: 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 ointers should b
a300: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
a310: 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 xStep.** and xFi
a320: 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 2e 20 nal parameters.
a330: 41 6e 20 61 67 67 72 65 67 61 74 65 20 66 75 6e An aggregate fun
a340: 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 ction requires a
a350: 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
a360: 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20 61 6e 64 .** of xStep and
a370: 20 78 46 69 6e 61 6c 2c 20 62 75 74 20 4e 55 4c xFinal, but NUL
a380: 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 L should be pass
a390: 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f ed for xFunc. To
a3a0: 20 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78 delete an.** ex
a3b0: 69 73 74 69 6e 67 20 75 73 65 72 20 66 75 6e 63 isting user func
a3c0: 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 tion or aggregat
a3d0: 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 e, pass NULL for
a3e0: 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 all three funct
a3f0: 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e ion.** callback.
a400: 20 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 69 Specifying an i
a410: 6e 63 6f 6e 73 74 65 6e 74 20 73 65 74 20 6f 66 nconstent set of
a420: 20 63 61 6c 6c 62 61 63 6b 20 76 61 6c 75 65 73 callback values
a430: 2c 20 73 75 63 68 20 61 73 20 61 6e 0a 2a 2a 20 , such as an.**
a440: 78 46 75 6e 63 20 61 6e 64 20 61 6e 20 78 46 69 xFunc and an xFi
a450: 6e 61 6c 2c 20 6f 72 20 61 6e 20 78 53 74 65 70 nal, or an xStep
a460: 20 62 75 74 20 6e 6f 20 78 46 69 6e 61 6c 2c 20 but no xFinal,
a470: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 0a SQLITE_ERROR is.
a480: 2a 2a 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a ** returned..*/.
a490: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
a4a0: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 te_function(. s
a4b0: 71 6c 69 74 65 33 20 2a 2c 0a 20 20 63 6f 6e 73 qlite3 *,. cons
a4c0: 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f t char *zFunctio
a4d0: 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
a4e0: 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
a4f0: 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f p,. void*,. vo
a500: 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 id (*xFunc)(sqli
a510: 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
a520: 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
a530: 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 ),. void (*xSte
a540: 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 p)(sqlite3_conte
a550: 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
a560: 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
a570: 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 (*xFinal)(sqlit
a580: 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a e3_context*).);.
a590: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
a5a0: 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 te_function16(.
a5b0: 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e sqlite3*,. con
a5c0: 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 st void *zFuncti
a5d0: 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 onName,. int nA
a5e0: 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 rg,. int eTextR
a5f0: 65 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 ep,. void*,. v
a600: 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c oid (*xFunc)(sql
a610: 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
a620: 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
a630: 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 *),. void (*xSt
a640: 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ep)(sqlite3_cont
a650: 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
a660: 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
a670: 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 d (*xFinal)(sqli
a680: 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b te3_context*).);
a690: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6e 65 78 74 ../*.** The next
a6a0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
a6b0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
a6c0: 61 6c 6c 73 20 74 6f 20 78 53 74 65 70 20 66 6f alls to xStep fo
a6d0: 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a r a particular.*
a6e0: 2a 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 * aggregate func
a6f0: 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2e 20 20 tion instance.
a700: 54 68 65 20 63 75 72 72 65 6e 74 20 63 61 6c 6c The current call
a710: 20 74 6f 20 78 53 74 65 70 20 63 6f 75 6e 74 73 to xStep counts
a720: 20 73 6f 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 so this.** rout
a730: 69 6e 65 20 61 6c 77 61 79 73 20 72 65 74 75 72 ine always retur
a740: 6e 73 20 61 74 20 6c 65 61 73 74 20 31 2e 0a 2a ns at least 1..*
a750: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 /.int sqlite3_ag
a760: 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 gregate_count(sq
a770: 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
a780: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6e 65 78 74 ../*.** The next
a790: 20 67 72 6f 75 70 20 6f 66 20 72 6f 75 74 69 6e group of routin
a7a0: 65 73 20 72 65 74 75 72 6e 73 20 69 6e 66 6f 72 es returns infor
a7b0: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 61 72 mation about par
a7c0: 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 61 20 ameters to.** a
a7d0: 75 73 65 72 2d 64 65 66 69 6e 65 64 20 66 75 6e user-defined fun
a7e0: 63 74 69 6f 6e 2e 20 20 46 75 6e 63 74 69 6f 6e ction. Function
a7f0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
a800: 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 use these routi
a810: 6e 65 73 0a 2a 2a 20 74 6f 20 61 63 63 65 73 73 nes.** to access
a820: 20 74 68 65 69 72 20 70 61 72 61 6d 65 74 65 72 their parameter
a830: 73 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e s. These routin
a840: 65 73 20 61 72 65 20 74 68 65 20 73 61 6d 65 20 es are the same
a850: 61 73 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 as the.** sqlite
a860: 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74 69 3_column_* routi
a870: 6e 65 73 20 65 78 63 65 70 74 20 74 68 61 74 20 nes except that
a880: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 these routines t
a890: 61 6b 65 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 ake a single.**
a8a0: 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20 70 sqlite3_value* p
a8b0: 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f ointer instead o
a8c0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 73 74 6d f an sqlite3_stm
a8d0: 74 2a 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 t* and an intege
a8e0: 72 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 r.** column numb
a8f0: 65 72 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 er..*/.const voi
a900: 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
a910: 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 _blob(sqlite3_va
a920: 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
a930: 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 e3_value_bytes(s
a940: 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
a950: 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
a960: 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 e_bytes16(sqlite
a970: 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 3_value*);.doubl
a980: 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
a990: 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 double(sqlite3_v
a9a0: 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 alue*);.int sqli
a9b0: 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 te3_value_int(sq
a9c0: 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 lite3_value*);.s
a9d0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 qlite_int64 sqli
a9e0: 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 te3_value_int64(
a9f0: 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
aa00: 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 .const unsigned
aa10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 char *sqlite3_va
aa20: 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 lue_text(sqlite3
aa30: 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 _value*);.const
aa40: 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 void *sqlite3_va
aa50: 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 lue_text16(sqlit
aa60: 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 e3_value*);.cons
aa70: 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
aa80: 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 value_text16le(s
aa90: 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
aaa0: 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
aab0: 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
aac0: 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 be(sqlite3_value
aad0: 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
aae0: 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 value_type(sqlit
aaf0: 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a e3_value*);../*.
ab00: 2a 2a 20 41 67 67 72 65 67 61 74 65 20 66 75 6e ** Aggregate fun
ab10: 63 74 69 6f 6e 73 20 75 73 65 20 74 68 65 20 66 ctions use the f
ab20: 6f 6c 6c 6f 77 69 6e 67 20 72 6f 75 74 69 6e 65 ollowing routine
ab30: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 to allocate.**
ab40: 61 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 a structure for
ab50: 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 storing their st
ab60: 61 74 65 2e 20 20 54 68 65 20 66 69 72 73 74 20 ate. The first
ab70: 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e time this routin
ab80: 65 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 20 66 e.** is called f
ab90: 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 or a particular
aba0: 61 67 67 72 65 67 61 74 65 2c 20 61 20 6e 65 77 aggregate, a new
abb0: 20 73 74 72 75 63 74 75 72 65 20 6f 66 20 73 69 structure of si
abc0: 7a 65 20 6e 42 79 74 65 73 0a 2a 2a 20 69 73 20 ze nBytes.** is
abd0: 61 6c 6c 6f 63 61 74 65 64 2c 20 7a 65 72 6f 65 allocated, zeroe
abe0: 64 2c 20 61 6e 64 20 72 65 74 75 72 6e 65 64 2e d, and returned.
abf0: 20 20 4f 6e 20 73 75 62 73 65 71 75 65 6e 74 20 On subsequent
ac00: 63 61 6c 6c 73 20 28 66 6f 72 20 74 68 65 0a 2a calls (for the.*
ac10: 2a 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 * same aggregate
ac20: 20 69 6e 73 74 61 6e 63 65 29 20 74 68 65 20 73 instance) the s
ac30: 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 ame buffer is re
ac40: 74 75 72 6e 65 64 2e 20 20 54 68 65 20 69 6d 70 turned. The imp
ac50: 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f lementation.** o
ac60: 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 f the aggregate
ac70: 63 61 6e 20 75 73 65 20 74 68 65 20 72 65 74 75 can use the retu
ac80: 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 rned buffer to a
ac90: 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a ccumulate data..
aca0: 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 66 66 65 72 **.** The buffer
acb0: 20 61 6c 6c 6f 63 61 74 65 64 20 69 73 20 66 72 allocated is fr
acc0: 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c eed automaticall
acd0: 79 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a y by SQLite..*/.
ace0: 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 void *sqlite3_ag
acf0: 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
ad00: 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
ad10: 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a , int nBytes);..
ad20: 2f 2a 0a 2a 2a 20 54 68 65 20 70 55 73 65 72 44 /*.** The pUserD
ad30: 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f ata parameter to
ad40: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 the sqlite3_cre
ad50: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 0a 2a ate_function().*
ad60: 2a 20 72 6f 75 74 69 6e 65 20 75 73 65 64 20 74 * routine used t
ad70: 6f 20 72 65 67 69 73 74 65 72 20 75 73 65 72 20 o register user
ad80: 66 75 6e 63 74 69 6f 6e 73 20 69 73 20 61 76 61 functions is ava
ad90: 69 6c 61 62 6c 65 20 74 6f 0a 2a 2a 20 74 68 65 ilable to.** the
ada0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
adb0: 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 of the function
adc0: 75 73 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e using this call.
add0: 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 .*/.void *sqlite
ade0: 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 3_user_data(sqli
adf0: 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a te3_context*);..
ae00: 2f 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 /*.** The follow
ae10: 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e ing two function
ae20: 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 s may be used by
ae30: 20 73 63 61 6c 61 72 20 75 73 65 72 20 66 75 6e scalar user fun
ae40: 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 ctions to.** ass
ae50: 6f 63 69 61 74 65 20 6d 65 74 61 2d 64 61 74 61 ociate meta-data
ae60: 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 with argument v
ae70: 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 alues. If the sa
ae80: 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 me value is pass
ae90: 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c ed to.** multipl
aea0: 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 e invocations of
aeb0: 20 74 68 65 20 75 73 65 72 2d 66 75 6e 63 74 69 the user-functi
aec0: 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 on during query
aed0: 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 execution, under
aee0: 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 .** some circums
aef0: 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 tances the assoc
af00: 69 61 74 65 64 20 6d 65 74 61 2d 64 61 74 61 20 iated meta-data
af10: 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 may be preserved
af20: 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 . This may.** be
af30: 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 used, for examp
af40: 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 le, to add a reg
af50: 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 ular-expression
af60: 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a matching scalar.
af70: 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 ** function. The
af80: 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f compiled versio
af90: 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 n of the regular
afa0: 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 expression is s
afb0: 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 tored as.** meta
afc0: 2d 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 -data associated
afd0: 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 with the SQL va
afe0: 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 lue passed as th
aff0: 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 e regular expres
b000: 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e sion.** pattern.
b010: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 .**.** Calling s
b020: 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
b030: 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 ta() returns a p
b040: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 ointer to the me
b050: 74 61 20 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 ta data.** assoc
b060: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 4e iated with the N
b070: 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 th argument valu
b080: 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 e to the current
b090: 20 75 73 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a user function.*
b0a0: 2a 20 63 61 6c 6c 2c 20 77 68 65 72 65 20 4e 20 * call, where N
b0b0: 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 is the second pa
b0c0: 72 61 6d 65 74 65 72 2e 20 49 66 20 6e 6f 20 6d rameter. If no m
b0d0: 65 74 61 2d 64 61 74 61 20 68 61 73 20 62 65 65 eta-data has bee
b0e0: 6e 20 73 65 74 20 66 6f 72 0a 2a 2a 20 74 68 61 n set for.** tha
b0f0: 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 20 t value, then a
b100: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 NULL pointer is
b110: 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
b120: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f The sqlite3_set_
b130: 61 75 78 64 61 74 61 28 29 20 69 73 20 75 73 65 auxdata() is use
b140: 64 20 74 6f 20 61 73 73 6f 63 69 61 74 65 20 6d d to associate m
b150: 65 74 61 20 64 61 74 61 20 77 69 74 68 20 61 20 eta data with a
b160: 75 73 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e user.** function
b170: 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 74 argument. The t
b180: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 hird parameter i
b190: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
b1a0: 68 65 20 6d 65 74 61 20 64 61 74 61 0a 2a 2a 20 he meta data.**
b1b0: 74 6f 20 62 65 20 61 73 73 6f 63 69 61 74 65 64 to be associated
b1c0: 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 75 73 with the Nth us
b1d0: 65 72 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 er function argu
b1e0: 6d 65 6e 74 20 76 61 6c 75 65 2e 20 54 68 65 20 ment value. The
b1f0: 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 fourth.** parame
b200: 74 65 72 20 73 70 65 63 69 66 69 65 73 20 61 20 ter specifies a
b210: 27 64 65 6c 65 74 65 20 66 75 6e 63 74 69 6f 6e 'delete function
b220: 27 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 63 ' that will be c
b230: 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 6d 65 74 alled on the met
b240: 61 0a 2a 2a 20 64 61 74 61 20 70 6f 69 6e 74 65 a.** data pointe
b250: 72 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 20 r to release it
b260: 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f when it is no lo
b270: 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 20 49 nger required. I
b280: 66 20 74 68 65 20 64 65 6c 65 74 65 0a 2a 2a 20 f the delete.**
b290: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 function pointer
b2a0: 20 69 73 20 4e 55 4c 4c 2c 20 69 74 20 69 73 20 is NULL, it is
b2b0: 6e 6f 74 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a not invoked..**.
b2c0: 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 ** In practice,
b2d0: 6d 65 74 61 2d 64 61 74 61 20 69 73 20 70 72 65 meta-data is pre
b2e0: 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 served between f
b2f0: 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f unction calls fo
b300: 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 r.** expressions
b310: 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 that are consta
b320: 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 nt at compile ti
b330: 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 me. This include
b340: 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c s literal.** val
b350: 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 ues and SQL vari
b360: 61 62 6c 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a ables..*/.void *
b370: 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
b380: 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ata(sqlite3_cont
b390: 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 ext*, int);.void
b3a0: 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
b3b0: 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e data(sqlite3_con
b3c0: 74 65 78 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 text*, int, void
b3d0: 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 *, void (*)(void
b3e0: 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 *));.../*.** The
b3f0: 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 se are special v
b400: 61 6c 75 65 20 66 6f 72 20 74 68 65 20 64 65 73 alue for the des
b410: 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 tructor that is
b420: 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 passed in as the
b430: 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 .** final argume
b440: 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c nt to routines l
b450: 69 6b 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 ike sqlite3_resu
b460: 6c 74 5f 62 6c 6f 62 28 29 2e 20 20 49 66 20 74 lt_blob(). If t
b470: 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a he destructor.**
b480: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c argument is SQL
b490: 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d ITE_STATIC, it m
b4a0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f eans that the co
b4b0: 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 ntent pointer is
b4c0: 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 constant.** and
b4d0: 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e will never chan
b4e0: 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 ge. It does not
b4f0: 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 need to be dest
b500: 72 6f 79 65 64 2e 20 20 54 68 65 20 0a 2a 2a 20 royed. The .**
b510: 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
b520: 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 value means tha
b530: 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 t the content wi
b540: 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 ll likely change
b550: 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 in.** the near
b560: 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 future and that
b570: 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 SQLite should ma
b580: 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 ke its own priva
b590: 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 te copy of.** th
b5a0: 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 e content before
b5b0: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 23 returning..*/.#
b5c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
b5d0: 41 54 49 43 20 20 20 20 20 20 28 28 76 6f 69 64 ATIC ((void
b5e0: 28 2a 29 28 76 6f 69 64 20 2a 29 29 30 29 0a 23 (*)(void *))0).#
b5f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 define SQLITE_TR
b600: 41 4e 53 49 45 4e 54 20 20 20 28 28 76 6f 69 64 ANSIENT ((void
b610: 28 2a 29 28 76 6f 69 64 20 2a 29 29 2d 31 29 0a (*)(void *))-1).
b620: 0a 2f 2a 0a 2a 2a 20 55 73 65 72 2d 64 65 66 69 ./*.** User-defi
b630: 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e ned functions in
b640: 76 6f 6b 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 voke the followi
b650: 6e 67 20 72 6f 75 74 69 6e 65 73 20 69 6e 20 6f ng routines in o
b660: 72 64 65 72 20 74 6f 0a 2a 2a 20 73 65 74 20 74 rder to.** set t
b670: 68 65 69 72 20 72 65 74 75 72 6e 20 76 61 6c 75 heir return valu
b680: 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 e..*/.void sqlit
b690: 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 e3_result_blob(s
b6a0: 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
b6b0: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
b6c0: 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
b6d0: 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
b6e0: 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 _result_double(s
b6f0: 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
b700: 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 double);.void s
b710: 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
b720: 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ror(sqlite3_cont
b730: 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 ext*, const char
b740: 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
b750: 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
b760: 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e or16(sqlite3_con
b770: 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
b780: 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 d*, int);.void s
b790: 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
b7a0: 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
b7b0: 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 t*, int);.void s
b7c0: 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
b7d0: 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 t64(sqlite3_cont
b7e0: 65 78 74 2a 2c 20 73 71 6c 69 74 65 5f 69 6e 74 ext*, sqlite_int
b7f0: 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 64);.void sqlite
b800: 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 3_result_null(sq
b810: 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
b820: 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
b830: 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 sult_text(sqlite
b840: 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
b850: 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f t char*, int, vo
b860: 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 id(*)(void*));.v
b870: 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
b880: 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 lt_text16(sqlite
b890: 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
b8a0: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f t void*, int, vo
b8b0: 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 id(*)(void*));.v
b8c0: 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
b8d0: 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 lt_text16le(sqli
b8e0: 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
b8f0: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 nst void*, int,v
b900: 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
b910: 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
b920: 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c ult_text16be(sql
b930: 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
b940: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
b950: 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
b960: 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
b970: 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 sult_value(sqlit
b980: 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c e3_context*, sql
b990: 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f ite3_value*);../
b9a0: 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 74 *.** These are t
b9b0: 68 65 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 he allowed value
b9c0: 73 20 66 6f 72 20 74 68 65 20 65 54 65 78 74 52 s for the eTextR
b9d0: 65 70 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a ep argument to.*
b9e0: 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
b9f0: 5f 63 6f 6c 6c 61 74 69 6f 6e 20 61 6e 64 20 73 _collation and s
ba00: 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
ba10: 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 nction..*/.#defi
ba20: 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 ne SQLITE_UTF8
ba30: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
ba40: 54 45 5f 55 54 46 31 36 4c 45 20 32 0a 23 64 65 TE_UTF16LE 2.#de
ba50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
ba60: 36 42 45 20 33 0a 23 64 65 66 69 6e 65 20 53 51 6BE 3.#define SQ
ba70: 4c 49 54 45 5f 55 54 46 31 36 20 20 20 34 20 20 LITE_UTF16 4
ba80: 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 /* Use native
ba90: 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 byte order */.#d
baa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 efine SQLITE_ANY
bab0: 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 5 /* sql
bac0: 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
bad0: 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a tion only */../*
bae0: 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20 66 75 .** These two fu
baf0: 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 nctions are used
bb00: 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c to add new coll
bb10: 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 ation sequences
bb20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 to the.** sqlite
bb30: 33 20 68 61 6e 64 6c 65 20 73 70 65 63 69 66 69 3 handle specifi
bb40: 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ed as the first
bb50: 61 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a argument. .**.**
bb60: 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 The name of the
bb70: 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 new collation s
bb80: 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 equence is speci
bb90: 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 fied as a UTF-8
bba0: 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 string.** for sq
bbb0: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
bbc0: 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 61 20 55 lation() and a U
bbd0: 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 TF-16 string for
bbe0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 .** sqlite3_crea
bbf0: 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 te_collation16()
bc00: 2e 20 49 6e 20 62 6f 74 68 20 63 61 73 65 73 20 . In both cases
bc10: 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 the name is pass
bc20: 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 73 65 63 ed as the.** sec
bc30: 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 ond function arg
bc40: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ument..**.** The
bc50: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
bc60: 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 must be one of t
bc70: 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 53 51 4c he constants SQL
bc80: 49 54 45 5f 55 54 46 38 2c 0a 2a 2a 20 53 51 4c ITE_UTF8,.** SQL
bc90: 49 54 45 5f 55 54 46 31 36 4c 45 20 6f 72 20 53 ITE_UTF16LE or S
bca0: 51 4c 49 54 45 5f 55 54 46 31 36 42 45 2c 20 69 QLITE_UTF16BE, i
bcb0: 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 ndicating that t
bcc0: 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 he user-supplied
bcd0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 .** routine expe
bce0: 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 cts to be passed
bcf0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
bd00: 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 ings encoded usi
bd10: 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 ng UTF-8,.** UTF
bd20: 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 -16 little-endia
bd30: 6e 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d n or UTF-16 big-
bd40: 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 endian respectiv
bd50: 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 ely..**.** A poi
bd60: 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72 nter to the user
bd70: 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e supplied routin
bd80: 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 e must be passed
bd90: 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a as the fifth.**
bda0: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 argument. If it
bdb0: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 is NULL, this i
bdc0: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 s the same as de
bdd0: 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 leting the colla
bde0: 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 tion.** sequence
bdf0: 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 (so that SQLite
be00: 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 cannot call it
be10: 61 6e 79 6d 6f 72 65 29 2e 20 45 61 63 68 20 74 anymore). Each t
be20: 69 6d 65 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 ime the user.**
be30: 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f supplied functio
be40: 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 n is invoked, it
be50: 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 is passed a cop
be60: 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 y of the void* p
be70: 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 assed as.** the
be80: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 fourth argument
be90: 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 to sqlite3_creat
bea0: 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 e_collation() or
beb0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 .** sqlite3_crea
bec0: 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 te_collation16()
bed0: 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 as its first pa
bee0: 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 rameter..**.** T
bef0: 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 he remaining arg
bf00: 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 75 73 uments to the us
bf10: 65 72 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 er-supplied rout
bf20: 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 ine are two stri
bf30: 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 ngs,.** each rep
bf40: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 5b 6c resented by a [l
bf50: 65 6e 67 74 68 2c 20 64 61 74 61 5d 20 70 61 69 ength, data] pai
bf60: 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e r and encoded in
bf70: 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a the encoding.**
bf80: 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64 that was passed
bf90: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72 as the third ar
bfa0: 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 gument when the
bfb0: 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
bfc0: 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 ce was.** regist
bfd0: 65 72 65 64 2e 20 54 68 65 20 75 73 65 72 20 72 ered. The user r
bfe0: 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 outine should re
bff0: 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a turn negative, z
c000: 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 ero or positive
c010: 69 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 if.** the first
c020: 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 string is less t
c030: 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f han, equal to, o
c040: 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 r greater than t
c050: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 73 74 72 he second.** str
c060: 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e ing. i.e. (STRIN
c070: 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a G1 - STRING2)..*
c080: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 /.int sqlite3_cr
c090: 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a eate_collation(.
c0a0: 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 sqlite3*, . c
c0b0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
c0c0: 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 , . int eTextRe
c0d0: 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 p, . void*,. i
c0e0: 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f nt(*xCompare)(vo
c0f0: 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
c100: 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
c110: 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 id*).);.int sqli
c120: 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
c130: 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 tion16(. sqlite
c140: 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 3*, . const cha
c150: 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 r *zName, . int
c160: 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f eTextRep, . vo
c170: 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d id*,. int(*xCom
c180: 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c pare)(void*,int,
c190: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c const void*,int,
c1a0: 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a const void*).);.
c1b0: 0a 2f 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 ./*.** To avoid
c1c0: 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 having to regist
c1d0: 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e er all collation
c1e0: 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 sequences befor
c1f0: 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 e a database.**
c200: 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 can be used, a s
c210: 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 ingle callback f
c220: 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 unction may be r
c230: 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 egistered with t
c240: 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 68 he.** database h
c250: 61 6e 64 6c 65 20 74 6f 20 62 65 20 63 61 6c 6c andle to be call
c260: 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 ed whenever an u
c270: 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 ndefined collati
c280: 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 0a 2a on sequence is.*
c290: 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a * required..**.*
c2a0: 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f * If the functio
c2b0: 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 n is registered
c2c0: 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 using the sqlite
c2d0: 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
c2e0: 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 ed() API,.** the
c2f0: 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 n it is passed t
c300: 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 he names of unde
c310: 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 fined collation
c320: 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 sequences as str
c330: 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 ings.** encoded
c340: 69 6e 20 55 54 46 2d 38 2e 20 49 66 20 73 71 6c in UTF-8. If sql
c350: 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
c360: 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 eeded16() is use
c370: 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a 20 d, the names.**
c380: 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 are passed as UT
c390: 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 F-16 in machine
c3a0: 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
c3b0: 72 2e 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 r. A call to eit
c3c0: 68 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 her.** function
c3d0: 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69 replaces any exi
c3e0: 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a sting callback..
c3f0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 75 **.** When the u
c400: 73 65 72 2d 66 75 6e 63 74 69 6f 6e 20 69 73 20 ser-function is
c410: 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 invoked, the fir
c420: 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 st argument pass
c430: 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 ed is a copy.**
c440: 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 of the second ar
c450: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
c460: 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
c470: 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 ed() or.** sqlit
c480: 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
c490: 64 65 64 31 36 28 29 2e 20 54 68 65 20 73 65 63 ded16(). The sec
c4a0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
c4b0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
c4c0: 68 61 6e 64 6c 65 2e 20 54 68 65 20 74 68 69 72 handle. The thir
c4d0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e d argument is on
c4e0: 65 20 6f 66 20 53 51 4c 49 54 45 5f 55 54 46 38 e of SQLITE_UTF8
c4f0: 2c 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 , SQLITE_UTF16BE
c500: 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 55 54 or.** SQLITE_UT
c510: 46 31 36 4c 45 2c 20 69 6e 64 69 63 61 74 69 6e F16LE, indicatin
c520: 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 g the most desir
c530: 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 able form of the
c540: 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 collation.** se
c550: 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 quence function
c560: 72 65 71 75 69 72 65 64 2e 20 54 68 65 20 66 6f required. The fo
c570: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
c580: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
c590: 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f e.** required co
c5a0: 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
c5b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c ..**.** The coll
c5c0: 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 ation sequence i
c5d0: 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 53 51 s returned to SQ
c5e0: 4c 69 74 65 20 62 79 20 61 20 63 6f 6c 6c 61 74 Lite by a collat
c5f0: 69 6f 6e 2d 6e 65 65 64 65 64 0a 2a 2a 20 63 61 ion-needed.** ca
c600: 6c 6c 62 61 63 6b 20 75 73 69 6e 67 20 74 68 65 llback using the
c610: 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
c620: 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 0a 2a collation() or.*
c630: 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
c640: 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 20 41 _collation16() A
c650: 50 49 73 2c 20 64 65 73 63 72 69 62 65 64 20 61 PIs, described a
c660: 62 6f 76 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c bove..*/.int sql
c670: 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
c680: 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 eeded(. sqlite3
c690: 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 *, . void*, .
c6a0: 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
c6b0: 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 lite3*,int eText
c6c0: 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 Rep,const char*)
c6d0: 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
c6e0: 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
c6f0: 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 16(. sqlite3*,
c700: 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 . void*,. void
c710: 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
c720: 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 3*,int eTextRep,
c730: 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a const void*).);.
c740: 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 ./*.** Specify t
c750: 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e he key for an en
c760: 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 crypted database
c770: 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 . This routine
c780: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c should be.** cal
c790: 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 led right after
c7a0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a sqlite3_open()..
c7b0: 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 **.** The code t
c7c0: 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 o implement this
c7d0: 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 API is not avai
c7e0: 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 lable in the pub
c7f0: 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f lic release.** o
c800: 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 f SQLite..*/.int
c810: 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 sqlite3_key(.
c820: 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
c830: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
c840: 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 * Database to be
c850: 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f rekeyed */. co
c860: 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 nst void *pKey,
c870: 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 int nKey /*
c880: 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f The key */.);../
c890: 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 *.** Change the
c8a0: 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 key on an open d
c8b0: 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 atabase. If the
c8c0: 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 current databas
c8d0: 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 e is not.** encr
c8e0: 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 ypted, this rout
c8f0: 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 ine will encrypt
c900: 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 it. If pNew==0
c910: 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 or nNew==0, the
c920: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 .** database is
c930: 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a decrypted..**.**
c940: 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 The code to imp
c950: 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 lement this API
c960: 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 is not available
c970: 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 in the public r
c980: 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c elease.** of SQL
c990: 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ite..*/.int sqli
c9a0: 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c te3_rekey(. sql
c9b0: 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
c9c0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
c9d0: 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 atabase to be re
c9e0: 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 keyed */. const
c9f0: 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 void *pKey, int
ca00: 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 nKey /* The
ca10: 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a new key */.);..
ca20: 2f 2a 0a 2a 2a 20 53 6c 65 65 70 20 66 6f 72 20 /*.** Sleep for
ca30: 61 20 6c 69 74 74 6c 65 20 77 68 69 6c 65 2e 20 a little while.
ca40: 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
ca50: 65 74 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 eter is the numb
ca60: 65 72 20 6f 66 0a 2a 2a 20 6d 69 6c 69 73 65 63 er of.** milisec
ca70: 6f 6e 64 73 20 74 6f 20 73 6c 65 65 70 20 66 6f onds to sleep fo
ca80: 72 2e 20 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 r. .**.** If the
ca90: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
caa0: 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f m does not suppo
cab0: 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 rt sleep request
cac0: 73 20 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 69 73 s with .** milis
cad0: 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c econd time resol
cae0: 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 ution, then the
caf0: 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 time will be rou
cb00: 6e 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74 nded up to .** t
cb10: 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e he nearest secon
cb20: 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 d. The number of
cb30: 20 6d 69 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 miliseconds of
cb40: 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 0a sleep actually .
cb50: 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f ** requested fro
cb60: 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 m the operating
cb70: 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e system is return
cb80: 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ed..*/.int sqlit
cb90: 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a e3_sleep(int);..
cba0: 2f 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 54 52 55 /*.** Return TRU
cbb0: 45 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 E (non-zero) if
cbc0: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 73 75 the statement su
cbd0: 70 70 6c 69 65 64 20 61 73 20 61 6e 20 61 72 67 pplied as an arg
cbe0: 75 6d 65 6e 74 20 6e 65 65 64 73 0a 2a 2a 20 74 ument needs.** t
cbf0: 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 2e o be recompiled.
cc00: 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 6e 65 A statement ne
cc10: 65 64 73 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 eds to be recomp
cc20: 69 6c 65 64 20 77 68 65 6e 65 76 65 72 20 74 68 iled whenever th
cc30: 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 65 e.** execution e
cc40: 6e 76 69 72 6f 6e 6d 65 6e 74 20 63 68 61 6e 67 nvironment chang
cc50: 65 73 20 69 6e 20 61 20 77 61 79 20 74 68 61 74 es in a way that
cc60: 20 77 6f 75 6c 64 20 61 6c 74 65 72 20 74 68 65 would alter the
cc70: 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 74 68 61 74 program.** that
cc80: 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
cc90: 28 29 20 67 65 6e 65 72 61 74 65 73 2e 20 20 46 () generates. F
cca0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 6e or example, if n
ccb0: 65 77 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 0a ew functions or.
ccc0: 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 ** collating seq
ccd0: 75 65 6e 63 65 73 20 61 72 65 20 72 65 67 69 73 uences are regis
cce0: 74 65 72 65 64 20 6f 72 20 69 66 20 61 6e 20 61 tered or if an a
ccf0: 75 74 68 6f 72 69 7a 65 72 20 66 75 6e 63 74 69 uthorizer functi
cd00: 6f 6e 20 69 73 0a 2a 2a 20 61 64 64 65 64 20 6f on is.** added o
cd10: 72 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2f r changed..**.*/
cd20: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 .int sqlite3_exp
cd30: 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d ired(sqlite3_stm
cd40: 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 4d 6f 76 65 t*);../*.** Move
cd50: 20 61 6c 6c 20 62 69 6e 64 69 6e 67 73 20 66 72 all bindings fr
cd60: 6f 6d 20 74 68 65 20 66 69 72 73 74 20 70 72 65 om the first pre
cd70: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
cd80: 6f 76 65 72 20 74 6f 20 74 68 65 20 73 65 63 6f over to the seco
cd90: 6e 64 2e 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 nd..** This rout
cda0: 69 6e 65 20 69 73 20 75 73 65 66 75 6c 2c 20 66 ine is useful, f
cdb0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 or example, if t
cdc0: 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65 he first prepare
cdd0: 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 d statement.** f
cde0: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 53 51 4c ails with an SQL
cdf0: 49 54 45 5f 53 43 48 45 4d 41 20 65 72 72 6f 72 ITE_SCHEMA error
ce00: 2e 20 20 54 68 65 20 73 61 6d 65 20 53 51 4c 20 . The same SQL
ce10: 63 61 6e 20 62 65 20 70 72 65 70 61 72 65 64 20 can be prepared
ce20: 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 65 63 6f into.** the seco
ce30: 6e 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 nd prepared stat
ce40: 65 6d 65 6e 74 20 74 68 65 6e 20 61 6c 6c 20 6f ement then all o
ce50: 66 20 74 68 65 20 62 69 6e 64 69 6e 67 73 20 74 f the bindings t
ce60: 72 61 6e 73 66 65 72 65 64 20 6f 76 65 72 0a 2a ransfered over.*
ce70: 2a 20 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 * to the second
ce80: 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 statement before
ce90: 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 the first state
cea0: 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 ment is finalize
ceb0: 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 d..*/.int sqlite
cec0: 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 3_transfer_bindi
ced0: 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ngs(sqlite3_stmt
cee0: 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a *, sqlite3_stmt*
cef0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 74 68 65 );../*.** If the
cf00: 20 66 6f 6c 6c 6f 77 69 6e 67 20 67 6c 6f 62 61 following globa
cf10: 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 l variable is ma
cf20: 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 de to point to a
cf30: 0a 2a 2a 20 73 74 72 69 6e 67 20 77 68 69 63 68 .** string which
cf40: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
cf50: 61 20 64 69 72 65 63 74 6f 72 79 2c 20 74 68 65 a directory, the
cf60: 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 n all temporary
cf70: 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 files.** created
cf80: 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 by SQLite will
cf90: 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 be placed in tha
cfa0: 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 t directory. If
cfb0: 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a this variable.*
cfc0: 2a 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 * is NULL pointe
cfd0: 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 64 r, then SQLite d
cfe0: 6f 65 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 oes a search for
cff0: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 an appropriate
d000: 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66 69 6c temporary.** fil
d010: 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a e directory..**.
d020: 2a 2a 20 4f 6e 63 65 20 73 71 6c 69 74 65 33 5f ** Once sqlite3_
d030: 6f 70 65 6e 28 29 20 68 61 73 20 62 65 65 6e 20 open() has been
d040: 63 61 6c 6c 65 64 2c 20 63 68 61 6e 67 69 6e 67 called, changing
d050: 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 77 this variable w
d060: 69 6c 6c 20 69 6e 76 61 6c 69 64 61 74 65 0a 2a ill invalidate.*
d070: 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 65 * the current te
d080: 6d 70 6f 72 61 72 79 20 64 61 74 61 62 61 73 65 mporary database
d090: 2c 20 69 66 20 61 6e 79 2e 0a 2a 2f 0a 65 78 74 , if any..*/.ext
d0a0: 65 72 6e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 ern char *sqlite
d0b0: 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3_temp_directory
d0c0: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 66 75 ;../*.** This fu
d0d0: 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 nction is called
d0e0: 20 74 6f 20 72 65 63 6f 76 65 72 20 66 72 6f 6d to recover from
d0f0: 20 61 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c a malloc() fail
d100: 75 72 65 20 74 68 61 74 20 6f 63 63 75 72 65 64 ure that occured
d110: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 53 .** within the S
d120: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 4e QLite library. N
d130: 6f 72 6d 61 6c 6c 79 2c 20 61 66 74 65 72 20 61 ormally, after a
d140: 20 73 69 6e 67 6c 65 20 6d 61 6c 6c 6f 63 28 29 single malloc()
d150: 20 66 61 69 6c 73 20 74 68 65 20 0a 2a 2a 20 6c fails the .** l
d160: 69 62 72 61 72 79 20 72 65 66 75 73 65 73 20 74 ibrary refuses t
d170: 6f 20 66 75 6e 63 74 69 6f 6e 20 28 61 6c 6c 20 o function (all
d180: 6d 61 6a 6f 72 20 63 61 6c 6c 73 20 72 65 74 75 major calls retu
d190: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 29 rn SQLITE_NOMEM)
d1a0: 2e 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 ..** This functi
d1b0: 6f 6e 20 72 65 73 74 6f 72 65 73 20 74 68 65 20 on restores the
d1c0: 6c 69 62 72 61 72 79 20 73 74 61 74 65 20 73 6f library state so
d1d0: 20 74 68 61 74 20 69 74 20 63 61 6e 20 62 65 20 that it can be
d1e0: 75 73 65 64 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a used again..**.*
d1f0: 2a 20 41 6c 6c 20 65 78 69 73 74 69 6e 67 20 73 * All existing s
d200: 74 61 74 65 6d 65 6e 74 73 20 28 73 71 6c 69 74 tatements (sqlit
d210: 65 33 5f 73 74 6d 74 20 70 6f 69 6e 74 65 72 73 e3_stmt pointers
d220: 29 20 6d 75 73 74 20 62 65 20 66 69 6e 61 6c 69 ) must be finali
d230: 7a 65 64 20 6f 72 0a 2a 2a 20 72 65 73 65 74 20 zed or.** reset
d240: 62 65 66 6f 72 65 20 74 68 69 73 20 63 61 6c 6c before this call
d250: 20 69 73 20 6d 61 64 65 2e 20 4f 74 68 65 72 77 is made. Otherw
d260: 69 73 65 2c 20 53 51 4c 49 54 45 5f 42 55 53 59 ise, SQLITE_BUSY
d270: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
d280: 20 49 66 20 61 6e 79 20 69 6e 2d 6d 65 6d 6f 72 If any in-memor
d290: 79 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20 y databases are
d2a0: 69 6e 20 75 73 65 2c 20 65 69 74 68 65 72 20 61 in use, either a
d2b0: 73 20 61 20 6d 61 69 6e 20 6f 72 20 54 45 4d 50 s a main or TEMP
d2c0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 53 51 .** database, SQ
d2d0: 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65 LITE_ERROR is re
d2e0: 74 75 72 6e 65 64 2e 20 49 6e 20 65 69 74 68 65 turned. In eithe
d2f0: 72 20 6f 66 20 74 68 65 73 65 20 63 61 73 65 73 r of these cases
d300: 2c 20 74 68 65 20 0a 2a 2a 20 6c 69 62 72 61 72 , the .** librar
d310: 79 20 69 73 20 6e 6f 74 20 72 65 73 65 74 20 61 y is not reset a
d320: 6e 64 20 72 65 6d 61 69 6e 73 20 75 6e 75 73 61 nd remains unusa
d330: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ble..**.** This
d340: 66 75 6e 63 74 69 6f 6e 20 69 73 20 2a 6e 6f 74 function is *not
d350: 2a 20 74 68 72 65 61 64 73 61 66 65 2e 20 43 61 * threadsafe. Ca
d360: 6c 6c 69 6e 67 20 74 68 69 73 20 66 72 6f 6d 20 lling this from
d370: 77 69 74 68 69 6e 20 61 20 74 68 72 65 61 64 65 within a threade
d380: 64 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e d.** application
d390: 20 77 68 65 6e 20 74 68 72 65 61 64 73 20 6f 74 when threads ot
d3a0: 68 65 72 20 74 68 61 6e 20 74 68 65 20 63 61 6c her than the cal
d3b0: 6c 65 72 20 68 61 76 65 20 75 73 65 64 20 53 51 ler have used SQ
d3c0: 4c 69 74 65 20 69 73 0a 2a 2a 20 64 61 6e 67 65 Lite is.** dange
d3d0: 72 6f 75 73 20 61 6e 64 20 77 69 6c 6c 20 61 6c rous and will al
d3e0: 6d 6f 73 74 20 63 65 72 74 61 69 6e 6c 79 20 72 most certainly r
d3f0: 65 73 75 6c 74 20 69 6e 20 6d 61 6c 66 75 6e 63 esult in malfunc
d400: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 tions..**.** Thi
d410: 73 20 66 75 6e 63 74 69 6f 6e 61 6c 69 74 79 20 s functionality
d420: 63 61 6e 20 62 65 20 6f 6d 69 74 74 65 64 20 66 can be omitted f
d430: 72 6f 6d 20 61 20 62 75 69 6c 64 20 62 79 20 64 rom a build by d
d440: 65 66 69 6e 69 6e 67 20 74 68 65 20 0a 2a 2a 20 efining the .**
d450: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 47 4c 4f 42 SQLITE_OMIT_GLOB
d460: 41 4c 52 45 43 4f 56 45 52 20 61 74 20 63 6f 6d ALRECOVER at com
d470: 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2f 0a 69 6e pile time..*/.in
d480: 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c t sqlite3_global
d490: 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a _recover(void);.
d4a0: 0a 2f 2a 0a 2a 2a 20 54 65 73 74 20 74 6f 20 73 ./*.** Test to s
d4b0: 65 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f ee whether or no
d4c0: 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 t the database c
d4d0: 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 onnection is in
d4e0: 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 6d 6f autocommit.** mo
d4f0: 64 65 2e 20 20 52 65 74 75 72 6e 20 54 52 55 45 de. Return TRUE
d500: 20 69 66 20 69 74 20 69 73 20 61 6e 64 20 46 41 if it is and FA
d510: 4c 53 45 20 69 66 20 6e 6f 74 2e 20 20 41 75 74 LSE if not. Aut
d520: 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 ocommit mode is
d530: 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 on.** by default
d540: 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 69 73 . Autocommit is
d550: 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 42 disabled by a B
d560: 45 47 49 4e 20 73 74 61 74 65 6d 65 6e 74 20 61 EGIN statement a
d570: 6e 64 20 72 65 65 6e 61 62 6c 65 64 0a 2a 2a 20 nd reenabled.**
d580: 62 79 20 74 68 65 20 6e 65 78 74 20 43 4f 4d 4d by the next COMM
d590: 49 54 20 6f 72 20 52 4f 4c 4c 42 41 43 4b 2e 0a IT or ROLLBACK..
d5a0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 */.int sqlite3_g
d5b0: 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 et_autocommit(sq
d5c0: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
d5d0: 52 65 74 75 72 6e 20 74 68 65 20 73 71 6c 69 74 Return the sqlit
d5e0: 65 33 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e e3* database han
d5f0: 64 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 dle to which the
d600: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
d610: 65 6e 74 20 67 69 76 65 6e 0a 2a 2a 20 69 6e 20 ent given.** in
d620: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 62 65 6c the argument bel
d630: 6f 6e 67 73 2e 20 20 54 68 69 73 20 69 73 20 74 ongs. This is t
d640: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
d650: 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77 61 73 handle that was
d660: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 61 72 .** the first ar
d670: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 gument to the sq
d680: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 lite3_prepare()
d690: 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f that was used to
d6a0: 20 63 72 65 61 74 65 0a 2a 2a 20 74 68 65 20 73 create.** the s
d6b0: 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 tatement in the
d6c0: 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a first place..*/.
d6d0: 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 sqlite3 *sqlite3
d6e0: 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 _db_handle(sqlit
d6f0: 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
d700: 2a 20 52 65 67 69 73 74 65 72 20 61 20 63 61 6c * Register a cal
d710: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 lback function w
d720: 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 ith the database
d730: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e connection iden
d740: 74 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a tified by the .*
d750: 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 * first argument
d760: 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
d770: 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 henever a row is
d780: 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 updated, insert
d790: 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a ed or deleted..*
d7a0: 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 * Any callback s
d7b0: 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 et by a previous
d7c0: 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 call to this fu
d7d0: 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 73 nction for the s
d7e0: 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 ame .** database
d7f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f connection is o
d800: 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a verridden..**.**
d810: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
d820: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
d830: 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f r to the functio
d840: 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e n to invoke when
d850: 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 a .** row is up
d860: 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 dated, inserted
d870: 6f 72 20 64 65 6c 65 74 65 64 2e 20 54 68 65 20 or deleted. The
d880: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
d890: 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 o the callback i
d8a0: 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 s.** a copy of t
d8b0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
d8c0: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 t to sqlite3_upd
d8d0: 61 74 65 5f 68 6f 6f 6b 2e 20 54 68 65 20 73 65 ate_hook. The se
d8e0: 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a 2a cond callback .*
d8f0: 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e * argument is on
d900: 65 20 6f 66 20 53 51 4c 49 54 45 5f 49 4e 53 45 e of SQLITE_INSE
d910: 52 54 2c 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 RT, SQLITE_DELET
d920: 45 20 6f 72 20 53 51 4c 49 54 45 5f 55 50 44 41 E or SQLITE_UPDA
d930: 54 45 2c 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a TE, depending.**
d940: 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f on the operatio
d950: 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 n that caused th
d960: 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 e callback to be
d970: 20 69 6e 76 6f 6b 65 64 2e 20 54 68 65 20 74 68 invoked. The th
d980: 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72 ird and .** four
d990: 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 th arguments to
d9a0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e the callback con
d9b0: 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f tain pointers to
d9c0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e the database an
d9d0: 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65 d .** table name
d9e0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
d9f0: 61 66 66 65 63 74 65 64 20 72 6f 77 2e 20 54 68 affected row. Th
da00: 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b e final callback
da10: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 0a 2a parameter is .*
da20: 2a 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 * the rowid of t
da30: 68 65 20 72 6f 77 2e 20 49 6e 20 74 68 65 20 63 he row. In the c
da40: 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 ase of an update
da50: 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 72 6f , this is the ro
da60: 77 69 64 20 61 66 74 65 72 20 0a 2a 2a 20 74 68 wid after .** th
da70: 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 e update takes p
da80: 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 lace..**.** The
da90: 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e update hook is n
daa0: 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 ot invoked when
dab0: 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 internal system
dac0: 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f tables are.** mo
dad0: 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c dified (i.e. sql
dae0: 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 ite_master and s
daf0: 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e qlite_sequence).
db00: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 .**.** If anothe
db10: 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 r function was p
db20: 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 reviously regist
db30: 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 ered, its pArg v
db40: 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 alue is returned
db50: 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 4e ..** Otherwise N
db60: 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e ULL is returned.
db70: 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 .*/.void *sqlite
db80: 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 3_update_hook(.
db90: 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f sqlite3*, . vo
dba0: 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 id(*)(void *,int
dbb0: 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 ,char const *,c
dbc0: 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 har const *,sqli
dbd0: 74 65 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 te_int64),. voi
dbe0: 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 52 65 67 d*.);../*.** Reg
dbf0: 69 73 74 65 72 20 61 20 63 61 6c 6c 62 61 63 6b ister a callback
dc00: 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
dc10: 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 henever a transa
dc20: 63 74 69 6f 6e 20 69 73 20 72 6f 6c 6c 65 64 0a ction is rolled.
dc30: 2a 2a 20 62 61 63 6b 2e 20 0a 2a 2a 0a 2a 2a 20 ** back. .**.**
dc40: 54 68 65 20 6e 65 77 20 63 61 6c 6c 62 61 63 6b The new callback
dc50: 20 66 75 6e 63 74 69 6f 6e 20 6f 76 65 72 72 69 function overri
dc60: 64 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 des any existing
dc70: 20 72 6f 6c 6c 62 61 63 6b 2d 68 6f 6f 6b 0a 2a rollback-hook.*
dc80: 2a 20 63 61 6c 6c 62 61 63 6b 2e 20 49 66 20 74 * callback. If t
dc90: 68 65 72 65 20 77 61 73 20 61 6e 20 65 78 69 73 here was an exis
dca0: 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2c 20 74 ting callback, t
dcb0: 68 65 6e 20 69 74 27 73 20 70 41 72 67 20 76 61 hen it's pArg va
dcc0: 6c 75 65 20 0a 2a 2a 20 28 74 68 65 20 74 68 69 lue .** (the thi
dcd0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 rd argument to s
dce0: 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f qlite3_rollback_
dcf0: 68 6f 6f 6b 28 29 20 77 68 65 6e 20 69 74 20 77 hook() when it w
dd00: 61 73 20 72 65 67 69 73 74 65 72 65 64 29 20 0a as registered) .
dd10: 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 ** is returned.
dd20: 4f 74 68 65 72 77 69 73 65 2c 20 4e 55 4c 4c 20 Otherwise, NULL
dd30: 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
dd40: 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f ** For the purpo
dd50: 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c ses of this API,
dd60: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
dd70: 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 s said to have b
dd80: 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 een .** rolled b
dd90: 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 ack if an explic
dda0: 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 it "ROLLBACK" st
ddb0: 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 atement is execu
ddc0: 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 ted, or.** an er
ddd0: 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e ror or constrain
dde0: 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c t causes an impl
ddf0: 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f icit rollback to
de00: 20 6f 63 63 75 72 2e 20 54 68 65 20 0a 2a 2a 20 occur. The .**
de10: 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 callback is not
de20: 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 invoked if a tra
de30: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f nsaction is auto
de40: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 matically rolled
de50: 0a 2a 2a 20 62 61 63 6b 20 62 65 63 61 75 73 65 .** back because
de60: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
de70: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 nnection is clos
de80: 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c ed..*/.void *sql
de90: 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f ite3_rollback_ho
dea0: 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 ok(sqlite3*, voi
deb0: 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f d(*)(void *), vo
dec0: 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 id*);../*.** Thi
ded0: 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6f 6e s function is on
dee0: 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 ly available if
def0: 74 68 65 20 6c 69 62 72 61 72 79 20 69 73 20 63 the library is c
df00: 6f 6d 70 69 6c 65 64 20 77 69 74 68 6f 75 74 0a ompiled without.
df10: 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d ** the SQLITE_OM
df20: 49 54 5f 53 48 41 52 45 44 5f 43 41 43 48 45 20 IT_SHARED_CACHE
df30: 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 49 macro defined. I
df40: 74 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 t is used to ena
df50: 62 6c 65 20 6f 72 0a 2a 2a 20 64 69 73 61 62 6c ble or.** disabl
df60: 65 20 28 69 66 20 74 68 65 20 61 72 67 75 6d 65 e (if the argume
df70: 6e 74 20 69 73 20 74 72 75 65 20 6f 72 20 66 61 nt is true or fa
df80: 6c 73 65 2c 20 72 65 73 70 65 63 74 69 76 65 6c lse, respectivel
df90: 79 29 20 74 68 65 20 0a 2a 2a 20 22 73 68 61 72 y) the .** "shar
dfa0: 65 64 20 70 61 67 65 72 22 20 66 65 61 74 75 72 ed pager" featur
dfb0: 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 e..*/.int sqlite
dfc0: 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 3_enable_shared_
dfd0: 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a cache(int);../*.
dfe0: 2a 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 66 72 ** Attempt to fr
dff0: 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65 ee N bytes of he
e000: 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 ap memory by dea
e010: 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 llocating non-es
e020: 73 65 6e 74 69 61 6c 0a 2a 2a 20 6d 65 6d 6f 72 sential.** memor
e030: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 y allocations he
e040: 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 ld by the databa
e050: 73 65 20 6c 69 62 72 61 72 79 20 28 65 78 61 6d se library (exam
e060: 70 6c 65 3a 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 ple: memory .**
e070: 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 used to cache da
e080: 74 61 62 61 73 65 20 70 61 67 65 73 20 74 6f 20 tabase pages to
e090: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 improve performa
e0a0: 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 nce)..**.** This
e0b0: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 function is not
e0c0: 20 61 20 70 61 72 74 20 6f 66 20 73 74 61 6e 64 a part of stand
e0d0: 61 72 64 20 62 75 69 6c 64 73 2e 20 20 49 74 20 ard builds. It
e0e0: 69 73 20 6f 6e 6c 79 20 63 72 65 61 74 65 64 0a is only created.
e0f0: 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 ** if SQLite is
e100: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
e110: 65 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f e SQLITE_ENABLE_
e120: 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e MEMORY_MANAGEMEN
e130: 54 20 6d 61 63 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 T macro..*/.int
e140: 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f sqlite3_release_
e150: 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a memory(int);../*
e160: 0a 2a 2a 20 50 6c 61 63 65 20 61 20 22 73 6f 66 .** Place a "sof
e170: 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 t" limit on the
e180: 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d amount of heap m
e190: 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 emory that may b
e1a0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a e allocated by.*
e1b0: 2a 20 53 51 4c 69 74 65 20 77 69 74 68 69 6e 20 * SQLite within
e1c0: 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 the current thre
e1d0: 61 64 2e 20 49 66 20 61 6e 20 69 6e 74 65 72 6e ad. If an intern
e1e0: 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 al allocation is
e1f0: 20 72 65 71 75 65 73 74 65 64 20 0a 2a 2a 20 74 requested .** t
e200: 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 hat would exceed
e210: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6c the specified l
e220: 69 6d 69 74 2c 20 73 71 6c 69 74 65 33 5f 72 65 imit, sqlite3_re
e230: 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 lease_memory() i
e240: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 6f 6e 65 s invoked.** one
e250: 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 or more times t
e260: 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 o free up some s
e270: 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 pace before the
e280: 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6d 61 allocation is ma
e290: 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 de..**.** The li
e2a0: 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 mit is called "s
e2b0: 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 69 66 oft", because if
e2c0: 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 sqlite3_release
e2d0: 5f 6d 65 6d 6f 72 79 28 29 20 63 61 6e 6e 6f 74 _memory() cannot
e2e0: 20 66 72 65 65 0a 2a 2a 20 73 75 66 66 69 63 69 free.** suffici
e2f0: 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 ent memory to pr
e300: 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 event the limit
e310: 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 from being excee
e320: 64 65 64 2c 20 74 68 65 20 6d 65 6d 6f 72 79 20 ded, the memory
e330: 69 73 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 is.** allocated
e340: 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 anyway and the c
e350: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e urrent operation
e360: 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a proceeds..**.**
e370: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 This function i
e380: 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 s only available
e390: 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 if the library
e3a0: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 was compiled wit
e3b0: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 h the .** SQLITE
e3c0: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d _ENABLE_MEMORY_M
e3d0: 41 4e 41 47 45 4d 45 4e 54 20 6f 70 74 69 6f 6e ANAGEMENT option
e3e0: 20 73 65 74 2e 0a 2a 2a 20 6d 65 6d 6f 72 79 2d set..** memory-
e3f0: 6d 61 6e 61 67 65 6d 65 6e 74 20 68 61 73 20 62 management has b
e400: 65 65 6e 20 65 6e 61 62 6c 65 64 2e 0a 2a 2f 0a een enabled..*/.
e410: 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 void sqlite3_sof
e420: 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 t_heap_limit(int
e430: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 );../*.** This r
e440: 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20 73 75 72 outine makes sur
e450: 65 20 74 68 61 74 20 61 6c 6c 20 74 68 72 65 61 e that all threa
e460: 64 2d 6c 6f 63 61 6c 20 73 74 6f 72 61 67 65 20 d-local storage
e470: 68 61 73 20 62 65 65 6e 0a 2a 2a 20 64 65 61 6c has been.** deal
e480: 6c 6f 63 61 74 65 64 20 66 6f 72 20 74 68 65 20 located for the
e490: 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 2e 0a current thread..
e4a0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
e4b0: 6e 65 20 69 73 20 6e 6f 74 20 74 65 63 68 6e 69 ne is not techni
e4c0: 63 61 6c 6c 79 20 6e 65 63 65 73 73 61 72 79 2e cally necessary.
e4d0: 20 20 41 6c 6c 20 74 68 72 65 61 64 2d 6c 6f 63 All thread-loc
e4e0: 61 6c 20 73 74 6f 72 61 67 65 0a 2a 2a 20 77 69 al storage.** wi
e4f0: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 ll be automatica
e500: 6c 6c 79 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 lly deallocated
e510: 6f 6e 63 65 20 6d 65 6d 6f 72 79 2d 6d 61 6e 61 once memory-mana
e520: 67 65 6d 65 6e 74 20 61 6e 64 0a 2a 2a 20 73 68 gement and.** sh
e530: 61 72 65 64 2d 63 61 63 68 65 20 61 72 65 20 64 ared-cache are d
e540: 69 73 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20 isabled and the
e550: 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 soft heap limit
e560: 68 61 73 20 62 65 65 6e 20 73 65 74 0a 2a 2a 20 has been set.**
e570: 74 6f 20 7a 65 72 6f 2e 20 20 54 68 69 73 20 72 to zero. This r
e580: 6f 75 74 69 6e 65 20 69 73 20 70 72 6f 76 69 64 outine is provid
e590: 65 64 20 61 73 20 61 20 63 6f 6e 76 65 6e 69 65 ed as a convenie
e5a0: 6e 63 65 20 66 6f 72 20 75 73 65 72 73 20 77 68 nce for users wh
e5b0: 6f 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 6d 61 6b o.** want to mak
e5c0: 65 20 61 62 73 6f 6c 75 74 65 6c 79 20 73 75 72 e absolutely sur
e5d0: 65 20 74 68 65 79 20 68 61 76 65 20 6e 6f 74 20 e they have not
e5e0: 66 6f 72 67 6f 74 74 65 6e 20 73 6f 6d 65 74 68 forgotten someth
e5f0: 69 6e 67 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 ing.** prior to
e600: 6b 69 6c 6c 69 6e 67 20 6f 66 66 20 61 20 74 68 killing off a th
e610: 72 65 61 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 read..*/.void sq
e620: 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 lite3_thread_cle
e630: 61 6e 75 70 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a anup(void);../*.
e640: 2a 2a 20 55 6e 64 6f 20 74 68 65 20 68 61 63 6b ** Undo the hack
e650: 20 74 68 61 74 20 63 6f 6e 76 65 72 74 73 20 66 that converts f
e660: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 loating point ty
e670: 70 65 73 20 74 6f 20 69 6e 74 65 67 65 72 20 66 pes to integer f
e680: 6f 72 0a 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 or.** builds on
e690: 70 72 6f 63 65 73 73 6f 72 73 20 77 69 74 68 6f processors witho
e6a0: 75 74 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e ut floating poin
e6b0: 74 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 t support..*/.#i
e6c0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 fdef SQLITE_OMIT
e6d0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a _FLOATING_POINT.
e6e0: 23 20 75 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 # undef double.#
e6f0: 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f endif..#ifdef __
e700: 63 70 6c 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 cplusplus.} /*
e710: 45 6e 64 20 6f 66 20 74 68 65 20 27 65 78 74 65 End of the 'exte
e720: 72 6e 20 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f rn "C"' block */
e730: 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a .#endif.#endif.