0000: 23 0a 23 20 52 75 6e 20 74 68 69 73 20 54 63 6c #.# Run this Tcl
0010: 20 73 63 72 69 70 74 20 74 6f 20 67 65 6e 65 72 script to gener
0020: 61 74 65 20 74 68 65 20 73 71 6c 69 74 65 2e 68 ate the sqlite.h
0030: 74 6d 6c 20 66 69 6c 65 2e 0a 23 0a 73 65 74 20 tml file..#.set
0040: 72 63 73 69 64 20 7b 24 49 64 3a 20 63 5f 69 6e rcsid {$Id: c_in
0050: 74 65 72 66 61 63 65 2e 74 63 6c 2c 76 20 31 2e terface.tcl,v 1.
0060: 34 32 20 32 30 30 34 2f 31 31 2f 31 30 20 30 35 42 2004/11/10 05
0070: 3a 34 38 3a 35 37 20 64 61 6e 69 65 6c 6b 31 39 :48:57 danielk19
0080: 37 37 20 45 78 70 20 24 7d 0a 73 6f 75 72 63 65 77 Exp $}.source
0090: 20 63 6f 6d 6d 6f 6e 2e 74 63 6c 0a 68 65 61 64 common.tcl.head
00a0: 65 72 20 7b 54 68 65 20 43 20 6c 61 6e 67 75 61 er {The C langua
00b0: 67 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 ge interface to
00c0: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
00d0: 72 79 7d 0a 70 75 74 73 20 7b 0a 3c 68 32 3e 54 ry}.puts {.<h2>T
00e0: 68 65 20 43 20 6c 61 6e 67 75 61 67 65 20 69 6e he C language in
00f0: 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 53 terface to the S
0100: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 3c 2f 68 QLite library</h
0110: 32 3e 0a 0a 3c 70 3e 54 68 65 20 53 51 4c 69 74 2>..<p>The SQLit
0120: 65 20 6c 69 62 72 61 72 79 20 69 73 20 64 65 73 e library is des
0130: 69 67 6e 65 64 20 74 6f 20 62 65 20 76 65 72 79 igned to be very
0140: 20 65 61 73 79 20 74 6f 20 75 73 65 20 66 72 6f easy to use fro
0150: 6d 0a 61 20 43 20 6f 72 20 43 2b 2b 20 70 72 6f m.a C or C++ pro
0160: 67 72 61 6d 2e 20 20 54 68 69 73 20 64 6f 63 75 gram. This docu
0170: 6d 65 6e 74 20 67 69 76 65 73 20 61 6e 20 6f 76 ment gives an ov
0180: 65 72 76 69 65 77 20 6f 66 20 74 68 65 20 43 2f erview of the C/
0190: 43 2b 2b 0a 70 72 6f 67 72 61 6d 6d 69 6e 67 20 C++.programming
01a0: 69 6e 74 65 72 66 61 63 65 2e 3c 2f 70 3e 0a 0a interface.</p>..
01b0: 3c 68 33 3e 31 2e 30 20 54 68 65 20 43 6f 72 65 <h3>1.0 The Core
01c0: 20 41 50 49 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 68 API</h3>..<p>Th
01d0: 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 e interface to t
01e0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
01f0: 79 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 74 68 y consists of th
0200: 72 65 65 20 63 6f 72 65 20 66 75 6e 63 74 69 6f ree core functio
0210: 6e 73 2c 0a 6f 6e 65 20 6f 70 61 71 75 65 20 64 ns,.one opaque d
0220: 61 74 61 20 73 74 72 75 63 74 75 72 65 2c 20 61 ata structure, a
0230: 6e 64 20 73 6f 6d 65 20 63 6f 6e 73 74 61 6e 74 nd some constant
0240: 73 20 75 73 65 64 20 61 73 20 72 65 74 75 72 6e s used as return
0250: 20 76 61 6c 75 65 73 2e 0a 54 68 65 20 63 6f 72 values..The cor
0260: 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 e interface is a
0270: 73 20 66 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a s follows:</p>..
0280: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
0290: 3e 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 >.typedef struct
02a0: 20 73 71 6c 69 74 65 20 73 71 6c 69 74 65 3b 0a sqlite sqlite;.
02b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
02c0: 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 K 0
02d0: 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 /* Successful re
02e0: 73 75 6c 74 20 2a 2f 0a 0a 73 71 6c 69 74 65 20 sult */..sqlite
02f0: 2a 73 71 6c 69 74 65 5f 6f 70 65 6e 28 63 6f 6e *sqlite_open(con
0300: 73 74 20 63 68 61 72 20 2a 64 62 6e 61 6d 65 2c st char *dbname,
0310: 20 69 6e 74 20 6d 6f 64 65 2c 20 63 68 61 72 20 int mode, char
0320: 2a 2a 65 72 72 6d 73 67 29 3b 0a 0a 76 6f 69 64 **errmsg);..void
0330: 20 73 71 6c 69 74 65 5f 63 6c 6f 73 65 28 73 71 sqlite_close(sq
0340: 6c 69 74 65 20 2a 64 62 29 3b 0a 0a 69 6e 74 20 lite *db);..int
0350: 73 71 6c 69 74 65 5f 65 78 65 63 28 0a 20 20 73 sqlite_exec(. s
0360: 71 6c 69 74 65 20 2a 64 62 2c 0a 20 20 63 68 61 qlite *db,. cha
0370: 72 20 2a 73 71 6c 2c 0a 20 20 69 6e 74 20 28 2a r *sql,. int (*
0380: 78 43 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a xCallback)(void*
0390: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 ,int,char**,char
03a0: 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 41 72 **),. void *pAr
03b0: 67 2c 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d g,. char **errm
03c0: 73 67 0a 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c sg.);.</pre></bl
03d0: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 54 ockquote>..<p>.T
03e0: 68 65 20 61 62 6f 76 65 20 69 73 20 61 6c 6c 20 he above is all
03f0: 79 6f 75 20 72 65 61 6c 6c 79 20 6e 65 65 64 20 you really need
0400: 74 6f 20 6b 6e 6f 77 20 69 6e 20 6f 72 64 65 72 to know in order
0410: 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 0a 69 to use SQLite.i
0420: 6e 20 79 6f 75 72 20 43 20 6f 72 20 43 2b 2b 20 n your C or C++
0430: 70 72 6f 67 72 61 6d 73 2e 20 20 54 68 65 72 65 programs. There
0440: 20 61 72 65 20 6f 74 68 65 72 20 69 6e 74 65 72 are other inter
0450: 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 0a 61 face functions.a
0460: 76 61 69 6c 61 62 6c 65 20 28 61 6e 64 20 64 65 vailable (and de
0470: 73 63 72 69 62 65 64 20 62 65 6c 6f 77 29 20 62 scribed below) b
0480: 75 74 20 77 65 20 77 69 6c 6c 20 62 65 67 69 6e ut we will begin
0490: 20 62 79 20 64 65 73 63 72 69 62 69 6e 67 0a 74 by describing.t
04a0: 68 65 20 63 6f 72 65 20 66 75 6e 63 74 69 6f 6e he core function
04b0: 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2e 0a 3c s shown above..<
04c0: 2f 70 3e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 73 71 /p>..<a name="sq
04d0: 6c 69 74 65 5f 6f 70 65 6e 22 3e 0a 3c 68 34 3e lite_open">.<h4>
04e0: 31 2e 31 20 4f 70 65 6e 69 6e 67 20 61 20 64 61 1.1 Opening a da
04f0: 74 61 62 61 73 65 3c 2f 68 34 3e 0a 0a 3c 70 3e tabase</h4>..<p>
0500: 55 73 65 20 74 68 65 20 3c 62 3e 73 71 6c 69 74 Use the <b>sqlit
0510: 65 5f 6f 70 65 6e 3c 2f 62 3e 20 66 75 6e 63 74 e_open</b> funct
0520: 69 6f 6e 20 74 6f 20 6f 70 65 6e 20 61 6e 20 65 ion to open an e
0530: 78 69 73 74 69 6e 67 20 53 51 4c 69 74 65 0a 64 xisting SQLite.d
0540: 61 74 61 62 61 73 65 20 6f 72 20 74 6f 20 63 72 atabase or to cr
0550: 65 61 74 65 20 61 20 6e 65 77 20 53 51 4c 69 74 eate a new SQLit
0560: 65 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 65 e database. The
0570: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a first argument.
0580: 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 is the database
0590: 6e 61 6d 65 2e 20 20 54 68 65 20 73 65 63 6f 6e name. The secon
05a0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e d argument is in
05b0: 74 65 6e 64 65 64 20 74 6f 20 73 69 67 6e 61 6c tended to signal
05c0: 0a 77 68 65 74 68 65 72 20 74 68 65 20 64 61 74 .whether the dat
05d0: 61 62 61 73 65 20 69 73 20 67 6f 69 6e 67 20 74 abase is going t
05e0: 6f 20 62 65 20 75 73 65 64 20 66 6f 72 20 72 65 o be used for re
05f0: 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e ading and writin
0600: 67 0a 6f 72 20 6a 75 73 74 20 66 6f 72 20 72 65 g.or just for re
0610: 61 64 69 6e 67 2e 20 20 42 75 74 20 69 6e 20 74 ading. But in t
0620: 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 he current imple
0630: 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 0a 73 mentation, the.s
0640: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
0650: 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e o <b>sqlite_open
0660: 3c 2f 62 3e 20 69 73 20 69 67 6e 6f 72 65 64 2e </b> is ignored.
0670: 0a 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d .The third argum
0680: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
0690: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 70 6f 69 to a string poi
06a0: 6e 74 65 72 2e 0a 49 66 20 74 68 65 20 74 68 69 nter..If the thi
06b0: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e rd argument is n
06c0: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 61 6e 20 65 ot NULL and an e
06d0: 72 72 6f 72 20 6f 63 63 75 72 73 0a 77 68 69 6c rror occurs.whil
06e0: 65 20 74 72 79 69 6e 67 20 74 6f 20 6f 70 65 6e e trying to open
06f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 the database, t
0700: 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 hen an error mes
0710: 73 61 67 65 20 77 69 6c 6c 20 62 65 0a 77 72 69 sage will be.wri
0720: 74 74 65 6e 20 74 6f 20 6d 65 6d 6f 72 79 20 6f tten to memory o
0730: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c btained from mal
0740: 6c 6f 63 28 29 20 61 6e 64 20 2a 65 72 72 6d 73 loc() and *errms
0750: 67 20 77 69 6c 6c 20 62 65 20 6d 61 64 65 0a 74 g will be made.t
0760: 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 69 73 20 o point to this
0770: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 error message.
0780: 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 The calling func
0790: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 tion is responsi
07a0: 62 6c 65 0a 66 6f 72 20 66 72 65 65 69 6e 67 20 ble.for freeing
07b0: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 the memory when
07c0: 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 it has finished
07d0: 77 69 74 68 20 69 74 2e 3c 2f 70 3e 0a 0a 3c 70 with it.</p>..<p
07e0: 3e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 20 >The name of an
07f0: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 SQLite database
0800: 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 is the name of a
0810: 20 66 69 6c 65 20 74 68 61 74 20 77 69 6c 6c 0a file that will.
0820: 63 6f 6e 74 61 69 6e 20 74 68 65 20 64 61 74 61 contain the data
0830: 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 66 69 base. If the fi
0840: 6c 65 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 le does not exis
0850: 74 2c 20 53 51 4c 69 74 65 20 61 74 74 65 6d 70 t, SQLite attemp
0860: 74 73 0a 74 6f 20 63 72 65 61 74 65 20 61 6e 64 ts.to create and
0870: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 74 2e 20 initialize it.
0880: 20 49 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 If the file is
0890: 72 65 61 64 2d 6f 6e 6c 79 20 28 64 75 65 20 74 read-only (due t
08a0: 6f 0a 70 65 72 6d 69 73 73 69 6f 6e 20 62 69 74 o.permission bit
08b0: 73 20 6f 72 20 62 65 63 61 75 73 65 20 69 74 20 s or because it
08c0: 69 73 20 6c 6f 63 61 74 65 64 20 6f 6e 20 72 65 is located on re
08d0: 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 6c 69 ad-only media li
08e0: 6b 65 0a 61 20 43 44 2d 52 4f 4d 29 20 74 68 65 ke.a CD-ROM) the
08f0: 6e 20 53 51 4c 69 74 65 20 6f 70 65 6e 73 20 74 n SQLite opens t
0900: 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 he database for
0910: 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 20 20 54 reading only. T
0920: 68 65 0a 65 6e 74 69 72 65 20 53 51 4c 20 64 61 he.entire SQL da
0930: 74 61 62 61 73 65 20 69 73 20 73 74 6f 72 65 64 tabase is stored
0940: 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 66 69 6c in a single fil
0950: 65 20 6f 6e 20 74 68 65 20 64 69 73 6b 2e 20 20 e on the disk.
0960: 42 75 74 0a 61 64 64 69 74 69 6f 6e 61 6c 20 74 But.additional t
0970: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d emporary files m
0980: 61 79 20 62 65 20 63 72 65 61 74 65 64 20 64 75 ay be created du
0990: 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 ring the executi
09a0: 6f 6e 20 6f 66 0a 61 6e 20 53 51 4c 20 63 6f 6d on of.an SQL com
09b0: 6d 61 6e 64 20 69 6e 20 6f 72 64 65 72 20 74 6f mand in order to
09c0: 20 73 74 6f 72 65 20 74 68 65 20 64 61 74 61 62 store the datab
09d0: 61 73 65 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 ase rollback jou
09e0: 72 6e 61 6c 20 6f 72 0a 74 65 6d 70 6f 72 61 72 rnal or.temporar
09f0: 79 20 61 6e 64 20 69 6e 74 65 72 6d 65 64 69 61 y and intermedia
0a00: 74 65 20 72 65 73 75 6c 74 73 20 6f 66 20 61 20 te results of a
0a10: 71 75 65 72 79 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 query.</p>..<p>T
0a20: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
0a30: 6f 66 20 74 68 65 20 3c 62 3e 73 71 6c 69 74 65 of the <b>sqlite
0a40: 5f 6f 70 65 6e 3c 2f 62 3e 20 66 75 6e 63 74 69 _open</b> functi
0a50: 6f 6e 20 69 73 20 61 0a 70 6f 69 6e 74 65 72 20 on is a.pointer
0a60: 74 6f 20 61 6e 20 6f 70 61 71 75 65 20 3c 62 3e to an opaque <b>
0a70: 73 71 6c 69 74 65 3c 2f 62 3e 20 73 74 72 75 63 sqlite</b> struc
0a80: 74 75 72 65 2e 20 20 54 68 69 73 20 70 6f 69 6e ture. This poin
0a90: 74 65 72 20 77 69 6c 6c 0a 62 65 20 74 68 65 20 ter will.be the
0aa0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
0ab0: 6f 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 o all subsequent
0ac0: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e SQLite function
0ad0: 20 63 61 6c 6c 73 20 74 68 61 74 0a 64 65 61 6c calls that.deal
0ae0: 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 64 with the same d
0af0: 61 74 61 62 61 73 65 2e 20 20 4e 55 4c 4c 20 69 atabase. NULL i
0b00: 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 s returned if th
0b10: 65 20 6f 70 65 6e 20 66 61 69 6c 73 0a 66 6f 72 e open fails.for
0b20: 20 61 6e 79 20 72 65 61 73 6f 6e 2e 3c 2f 70 3e any reason.</p>
0b30: 0a 0a 3c 61 20 6e 61 6d 65 3d 22 73 71 6c 69 74 ..<a name="sqlit
0b40: 65 5f 63 6c 6f 73 65 22 3e 0a 3c 68 34 3e 31 2e e_close">.<h4>1.
0b50: 32 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 64 61 2 Closing the da
0b60: 74 61 62 61 73 65 3c 2f 68 34 3e 0a 0a 3c 70 3e tabase</h4>..<p>
0b70: 54 6f 20 63 6c 6f 73 65 20 61 6e 20 53 51 4c 69 To close an SQLi
0b80: 74 65 20 64 61 74 61 62 61 73 65 2c 20 63 61 6c te database, cal
0b90: 6c 20 74 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f l the <b>sqlite_
0ba0: 63 6c 6f 73 65 3c 2f 62 3e 0a 66 75 6e 63 74 69 close</b>.functi
0bb0: 6f 6e 20 70 61 73 73 69 6e 67 20 69 74 20 74 68 on passing it th
0bc0: 65 20 73 71 6c 69 74 65 20 73 74 72 75 63 74 75 e sqlite structu
0bd0: 72 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 re pointer that
0be0: 77 61 73 20 6f 62 74 61 69 6e 65 64 0a 66 72 6f was obtained.fro
0bf0: 6d 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 m a prior call t
0c00: 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e o <b>sqlite_open
0c10: 3c 2f 62 3e 2e 0a 49 66 20 61 20 74 72 61 6e 73 </b>..If a trans
0c20: 61 63 74 69 6f 6e 20 69 73 20 61 63 74 69 76 65 action is active
0c30: 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 when the databa
0c40: 73 65 20 69 73 20 63 6c 6f 73 65 64 2c 20 74 68 se is closed, th
0c50: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 69 73 e transaction.is
0c60: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 3c 2f 70 rolled back.</p
0c70: 3e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 73 71 6c 69 >..<a name="sqli
0c80: 74 65 5f 65 78 65 63 22 3e 0a 3c 68 34 3e 31 2e te_exec">.<h4>1.
0c90: 33 20 45 78 65 63 75 74 69 6e 67 20 53 51 4c 20 3 Executing SQL
0ca0: 73 74 61 74 65 6d 65 6e 74 73 3c 2f 68 34 3e 0a statements</h4>.
0cb0: 0a 3c 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69 74 .<p>The <b>sqlit
0cc0: 65 5f 65 78 65 63 3c 2f 62 3e 20 66 75 6e 63 74 e_exec</b> funct
0cd0: 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 70 ion is used to p
0ce0: 72 6f 63 65 73 73 20 53 51 4c 20 73 74 61 74 65 rocess SQL state
0cf0: 6d 65 6e 74 73 0a 61 6e 64 20 71 75 65 72 69 65 ments.and querie
0d00: 73 2e 20 20 54 68 69 73 20 66 75 6e 63 74 69 6f s. This functio
0d10: 6e 20 72 65 71 75 69 72 65 73 20 35 20 70 61 72 n requires 5 par
0d20: 61 6d 65 74 65 72 73 20 61 73 20 66 6f 6c 6c 6f ameters as follo
0d30: 77 73 3a 3c 2f 70 3e 0a 0a 3c 6f 6c 3e 0a 3c 6c ws:</p>..<ol>.<l
0d40: 69 3e 3c 70 3e 41 20 70 6f 69 6e 74 65 72 20 74 i><p>A pointer t
0d50: 6f 20 74 68 65 20 73 71 6c 69 74 65 20 73 74 72 o the sqlite str
0d60: 75 63 74 75 72 65 20 6f 62 74 61 69 6e 65 64 20 ucture obtained
0d70: 66 72 6f 6d 20 61 20 70 72 69 6f 72 20 63 61 6c from a prior cal
0d80: 6c 0a 20 20 20 20 20 20 20 74 6f 20 3c 62 3e 73 l. to <b>s
0d90: 71 6c 69 74 65 5f 6f 70 65 6e 3c 2f 62 3e 2e 3c qlite_open</b>.<
0da0: 2f 70 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e /p></li>.<li><p>
0db0: 41 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 A null-terminate
0dc0: 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e d string contain
0dd0: 69 6e 67 20 74 68 65 20 74 65 78 74 20 6f 66 20 ing the text of
0de0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 20 20 20 20 one or more.
0df0: 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 SQL statement
0e00: 73 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 s and/or queries
0e10: 20 74 6f 20 62 65 20 70 72 6f 63 65 73 73 65 64 to be processed
0e20: 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c .</p></li>.<li><
0e30: 70 3e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 p>A pointer to a
0e40: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
0e50: 6f 6e 20 77 68 69 63 68 20 69 73 20 69 6e 76 6f on which is invo
0e60: 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 ked once for eac
0e70: 68 0a 20 20 20 20 20 20 20 72 6f 77 20 69 6e 20 h. row in
0e80: 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 61 20 the result of a
0e90: 71 75 65 72 79 2e 20 20 54 68 69 73 20 61 72 67 query. This arg
0ea0: 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55 4c ument may be NUL
0eb0: 4c 2c 20 69 6e 20 77 68 69 63 68 0a 20 20 20 20 L, in which.
0ec0: 20 20 20 63 61 73 65 20 6e 6f 20 63 61 6c 6c 62 case no callb
0ed0: 61 63 6b 73 20 77 69 6c 6c 20 65 76 65 72 20 62 acks will ever b
0ee0: 65 20 69 6e 76 6f 6b 65 64 2e 3c 2f 70 3e 3c 2f e invoked.</p></
0ef0: 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 70 6f 69 li>.<li><p>A poi
0f00: 6e 74 65 72 20 74 68 61 74 20 69 73 20 66 6f 72 nter that is for
0f10: 77 61 72 64 65 64 20 74 6f 20 62 65 63 6f 6d 65 warded to become
0f20: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
0f30: 65 6e 74 0a 20 20 20 20 20 20 20 74 6f 20 74 68 ent. to th
0f40: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
0f50: 69 6f 6e 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 3c 6c ion.</p></li>.<l
0f60: 69 3e 3c 70 3e 41 20 70 6f 69 6e 74 65 72 20 74 i><p>A pointer t
0f70: 6f 20 61 6e 20 65 72 72 6f 72 20 73 74 72 69 6e o an error strin
0f80: 67 2e 20 20 45 72 72 6f 72 20 6d 65 73 73 61 67 g. Error messag
0f90: 65 73 20 61 72 65 20 77 72 69 74 74 65 6e 20 74 es are written t
0fa0: 6f 20 73 70 61 63 65 0a 20 20 20 20 20 20 20 6f o space. o
0fb0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c btained from mal
0fc0: 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 65 72 loc() and the er
0fd0: 72 6f 72 20 73 74 72 69 6e 67 20 69 73 20 6d 61 ror string is ma
0fe0: 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 0a 20 de to point to.
0ff0: 20 20 20 20 20 20 74 68 65 20 6d 61 6c 6c 6f 63 the malloc
1000: 65 64 20 73 70 61 63 65 2e 20 20 54 68 65 20 63 ed space. The c
1010: 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 alling function
1020: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
1030: 6f 72 20 66 72 65 65 69 6e 67 0a 20 20 20 20 20 or freeing.
1040: 20 20 74 68 69 73 20 73 70 61 63 65 20 77 68 65 this space whe
1050: 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 n it has finishe
1060: 64 20 77 69 74 68 20 69 74 2e 0a 20 20 20 20 20 d with it..
1070: 20 20 54 68 69 73 20 61 72 67 75 6d 65 6e 74 20 This argument
1080: 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 may be NULL, in
1090: 77 68 69 63 68 20 63 61 73 65 20 65 72 72 6f 72 which case error
10a0: 20 6d 65 73 73 61 67 65 73 20 61 72 65 20 6e 6f messages are no
10b0: 74 0a 20 20 20 20 20 20 20 72 65 70 6f 72 74 65 t. reporte
10c0: 64 20 62 61 63 6b 20 74 6f 20 74 68 65 20 63 61 d back to the ca
10d0: 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 3c lling function.<
10e0: 2f 70 3e 3c 2f 6c 69 3e 0a 3c 2f 6f 6c 3e 0a 0a /p></li>.</ol>..
10f0: 3c 70 3e 0a 54 68 65 20 63 61 6c 6c 62 61 63 6b <p>.The callback
1100: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 function is use
1110: 64 20 74 6f 20 72 65 63 65 69 76 65 20 74 68 65 d to receive the
1120: 20 72 65 73 75 6c 74 73 20 6f 66 20 61 20 71 75 results of a qu
1130: 65 72 79 2e 20 20 41 0a 70 72 6f 74 6f 74 79 70 ery. A.prototyp
1140: 65 20 66 6f 72 20 74 68 65 20 63 61 6c 6c 62 61 e for the callba
1150: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 ck function is a
1160: 73 20 66 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a s follows:</p>..
1170: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1180: 3e 0a 69 6e 74 20 43 61 6c 6c 62 61 63 6b 28 76 >.int Callback(v
1190: 6f 69 64 20 2a 70 41 72 67 2c 20 69 6e 74 20 61 oid *pArg, int a
11a0: 72 67 63 2c 20 63 68 61 72 20 2a 2a 61 72 67 76 rgc, char **argv
11b0: 2c 20 63 68 61 72 20 2a 2a 63 6f 6c 75 6d 6e 4e , char **columnN
11c0: 61 6d 65 73 29 7b 0a 20 20 72 65 74 75 72 6e 20 ames){. return
11d0: 30 3b 0a 7d 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 0;.}.</pre></blo
11e0: 63 6b 71 75 6f 74 65 3e 0a 0a 3c 61 20 6e 61 6d ckquote>..<a nam
11f0: 65 3d 22 63 61 6c 6c 62 61 63 6b 5f 72 6f 77 5f e="callback_row_
1200: 64 61 74 61 22 3e 0a 3c 70 3e 54 68 65 20 66 69 data">.<p>The fi
1210: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
1220: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
1230: 6a 75 73 74 20 61 20 63 6f 70 79 20 6f 66 20 74 just a copy of t
1240: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
1250: 6e 74 0a 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f nt.to <b>sqlite_
1260: 65 78 65 63 3c 2f 62 3e 20 20 54 68 69 73 20 70 exec</b> This p
1270: 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 arameter can be
1280: 75 73 65 64 20 74 6f 20 70 61 73 73 20 61 72 62 used to pass arb
1290: 69 74 72 61 72 79 0a 69 6e 66 6f 72 6d 61 74 69 itrary.informati
12a0: 6f 6e 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 on through to th
12b0: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
12c0: 69 6f 6e 20 66 72 6f 6d 20 63 6c 69 65 6e 74 20 ion from client
12d0: 63 6f 64 65 2e 0a 54 68 65 20 73 65 63 6f 6e 64 code..The second
12e0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
12f0: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
1300: 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 ns in the query
1310: 72 65 73 75 6c 74 2e 0a 54 68 65 20 74 68 69 72 result..The thir
1320: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e d argument is an
1330: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
1340: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 rs to strings wh
1350: 65 72 65 20 65 61 63 68 20 73 74 72 69 6e 67 0a ere each string.
1360: 69 73 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 is a single colu
1370: 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 mn of the result
1380: 20 66 6f 72 20 74 68 61 74 20 72 65 63 6f 72 64 for that record
1390: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 . Note that the
13a0: 0a 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 .callback functi
13b0: 6f 6e 20 72 65 70 6f 72 74 73 20 61 20 4e 55 4c on reports a NUL
13c0: 4c 20 76 61 6c 75 65 20 69 6e 20 74 68 65 20 64 L value in the d
13d0: 61 74 61 62 61 73 65 20 61 73 20 61 20 4e 55 4c atabase as a NUL
13e0: 4c 20 70 6f 69 6e 74 65 72 2c 0a 77 68 69 63 68 L pointer,.which
13f0: 20 69 73 20 76 65 72 79 20 64 69 66 66 65 72 65 is very differe
1400: 6e 74 20 66 72 6f 6d 20 61 6e 20 65 6d 70 74 79 nt from an empty
1410: 20 73 74 72 69 6e 67 2e 20 20 49 66 20 74 68 65 string. If the
1420: 20 69 2d 74 68 20 70 61 72 61 6d 65 74 65 72 0a i-th parameter.
1430: 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 is an empty stri
1440: 6e 67 2c 20 77 65 20 77 69 6c 6c 20 67 65 74 3a ng, we will get:
1450: 3c 2f 70 3e 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 </p>.<blockquote
1460: 3e 3c 70 72 65 3e 0a 61 72 67 76 5b 69 5d 5b 30 ><pre>.argv[i][0
1470: 5d 20 3d 3d 20 30 0a 3c 2f 70 72 65 3e 3c 2f 62 ] == 0.</pre></b
1480: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 70 3e 42 75 lockquote>.<p>Bu
1490: 74 20 69 66 20 74 68 65 20 69 2d 74 68 20 70 61 t if the i-th pa
14a0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 rameter is NULL
14b0: 77 65 20 77 69 6c 6c 20 67 65 74 3a 3c 2f 70 3e we will get:</p>
14c0: 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 .<blockquote><pr
14d0: 65 3e 0a 61 72 67 76 5b 69 5d 20 3d 3d 20 30 0a e>.argv[i] == 0.
14e0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
14f0: 74 65 3e 0a 0a 3c 70 3e 54 68 65 20 6e 61 6d 65 te>..<p>The name
1500: 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 s of the columns
1510: 20 61 72 65 20 63 6f 6e 74 61 69 6e 65 64 20 69 are contained i
1520: 6e 20 66 69 72 73 74 20 3c 69 3e 61 72 67 63 3c n first <i>argc<
1530: 2f 69 3e 0a 65 6e 74 72 69 65 73 20 6f 66 20 74 /i>.entries of t
1540: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
1550: 6e 74 2e 0a 49 66 20 74 68 65 20 3c 61 20 68 72 nt..If the <a hr
1560: 65 66 3d 22 70 72 61 67 6d 61 2e 68 74 6d 6c 23 ef="pragma.html#
1570: 70 72 61 67 6d 61 5f 73 68 6f 77 5f 64 61 74 61 pragma_show_data
1580: 74 79 70 65 73 22 3e 53 48 4f 57 5f 44 41 54 41 types">SHOW_DATA
1590: 54 59 50 45 53 3c 2f 61 3e 20 70 72 61 67 6d 61 TYPES</a> pragma
15a0: 0a 69 73 20 6f 6e 20 28 69 74 20 69 73 20 6f 66 .is on (it is of
15b0: 66 20 62 79 20 64 65 66 61 75 6c 74 29 20 74 68 f by default) th
15c0: 65 6e 0a 74 68 65 20 73 65 63 6f 6e 64 20 3c 69 en.the second <i
15d0: 3e 61 72 67 63 3c 2f 69 3e 20 65 6e 74 72 69 65 >argc</i> entrie
15e0: 73 20 69 6e 20 74 68 65 20 34 74 68 20 61 72 67 s in the 4th arg
15f0: 75 6d 65 6e 74 20 61 72 65 20 74 68 65 20 64 61 ument are the da
1600: 74 61 74 79 70 65 73 0a 66 6f 72 20 74 68 65 20 tatypes.for the
1610: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 63 6f corresponding co
1620: 6c 75 6d 6e 73 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e lumns..</p>..<p>
1630: 49 66 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 If the <a href="
1640: 70 72 61 67 6d 61 2e 68 74 6d 6c 23 70 72 61 67 pragma.html#prag
1650: 6d 61 5f 65 6d 70 74 79 5f 72 65 73 75 6c 74 5f ma_empty_result_
1660: 63 61 6c 6c 62 61 63 6b 73 22 3e 0a 45 4d 50 54 callbacks">.EMPT
1670: 59 5f 52 45 53 55 4c 54 5f 43 41 4c 4c 42 41 43 Y_RESULT_CALLBAC
1680: 4b 53 3c 2f 61 3e 20 70 72 61 67 6d 61 20 69 73 KS</a> pragma is
1690: 20 73 65 74 20 74 6f 20 4f 4e 20 61 6e 64 20 74 set to ON and t
16a0: 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 61 20 71 he result of.a q
16b0: 75 65 72 79 20 69 73 20 61 6e 20 65 6d 70 74 79 uery is an empty
16c0: 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 63 set, then the c
16d0: 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
16e0: 65 64 20 6f 6e 63 65 20 77 69 74 68 20 74 68 65 ed once with the
16f0: 0a 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 .third parameter
1700: 20 28 61 72 67 76 29 20 73 65 74 20 74 6f 20 30 (argv) set to 0
1710: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 . In other word
1720: 73 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 s.<blockquote><p
1730: 72 65 3e 0a 61 72 67 76 20 3d 3d 20 30 0a 3c 2f re>.argv == 0.</
1740: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1750: 3e 0a 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 >.The second par
1760: 61 6d 65 74 65 72 20 28 61 72 67 63 29 0a 61 6e ameter (argc).an
1770: 64 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 d the fourth par
1780: 61 6d 65 74 65 72 20 28 63 6f 6c 75 6d 6e 4e 61 ameter (columnNa
1790: 6d 65 73 29 20 61 72 65 20 73 74 69 6c 6c 20 76 mes) are still v
17a0: 61 6c 69 64 0a 61 6e 64 20 63 61 6e 20 62 65 20 alid.and can be
17b0: 75 73 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e used to determin
17c0: 65 20 74 68 65 20 6e 75 6d 62 65 72 20 61 6e 64 e the number and
17d0: 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 72 65 names of the re
17e0: 73 75 6c 74 0a 63 6f 6c 75 6d 6e 73 20 69 66 20 sult.columns if
17f0: 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 61 there had been a
1800: 20 72 65 73 75 6c 74 2e 0a 54 68 65 20 64 65 66 result..The def
1810: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 ault behavior is
1820: 20 6e 6f 74 20 74 6f 20 69 6e 76 6f 6b 65 20 74 not to invoke t
1830: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 74 20 61 he callback at a
1840: 6c 6c 20 69 66 20 74 68 65 0a 72 65 73 75 6c 74 ll if the.result
1850: 20 73 65 74 20 69 73 20 65 6d 70 74 79 2e 3c 2f set is empty.</
1860: 70 3e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 63 61 6c p>..<a name="cal
1870: 6c 62 61 63 6b 5f 72 65 74 75 72 6e 73 5f 6e 6f lback_returns_no
1880: 6e 7a 65 72 6f 22 3e 0a 3c 70 3e 54 68 65 20 63 nzero">.<p>The c
1890: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
18a0: 20 73 68 6f 75 6c 64 20 6e 6f 72 6d 61 6c 6c 79 should normally
18b0: 20 72 65 74 75 72 6e 20 30 2e 20 20 49 66 20 74 return 0. If t
18c0: 68 65 20 63 61 6c 6c 62 61 63 6b 0a 66 75 6e 63 he callback.func
18d0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e tion returns non
18e0: 2d 7a 65 72 6f 2c 20 74 68 65 20 71 75 65 72 79 -zero, the query
18f0: 20 69 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 is immediately
1900: 61 62 6f 72 74 65 64 20 61 6e 64 20 0a 3c 62 3e aborted and .<b>
1910: 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e 20 sqlite_exec</b>
1920: 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 will return SQLI
1930: 54 45 5f 41 42 4f 52 54 2e 3c 2f 70 3e 0a 0a 3c TE_ABORT.</p>..<
1940: 68 34 3e 31 2e 34 20 45 72 72 6f 72 20 43 6f 64 h4>1.4 Error Cod
1950: 65 73 3c 2f 68 34 3e 0a 0a 3c 70 3e 0a 54 68 65 es</h4>..<p>.The
1960: 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c <b>sqlite_exec<
1970: 2f 62 3e 20 66 75 6e 63 74 69 6f 6e 20 6e 6f 72 /b> function nor
1980: 6d 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 53 51 mally returns SQ
1990: 4c 49 54 45 5f 4f 4b 2e 20 20 42 75 74 0a 69 66 LITE_OK. But.if
19a0: 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 something goes
19b0: 77 72 6f 6e 67 20 69 74 20 63 61 6e 20 72 65 74 wrong it can ret
19c0: 75 72 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 urn a different
19d0: 76 61 6c 75 65 20 74 6f 20 69 6e 64 69 63 61 74 value to indicat
19e0: 65 0a 74 68 65 20 74 79 70 65 20 6f 66 20 65 72 e.the type of er
19f0: 72 6f 72 2e 20 20 48 65 72 65 20 69 73 20 61 20 ror. Here is a
1a00: 63 6f 6d 70 6c 65 74 65 20 6c 69 73 74 20 6f 66 complete list of
1a10: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 the return code
1a20: 73 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 s:.</p>..<blockq
1a30: 75 6f 74 65 3e 3c 70 72 65 3e 0a 23 64 65 66 69 uote><pre>.#defi
1a40: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 ne SQLITE_OK
1a50: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 0 /* Su
1a60: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 ccessful result
1a70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1a80: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 E_ERROR 1
1a90: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 /* SQL error
1aa0: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 or missing datab
1ab0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ase */.#define S
1ac0: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 QLITE_INTERNAL
1ad0: 20 20 20 32 20 20 20 2f 2a 20 41 6e 20 69 6e 74 2 /* An int
1ae0: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f ernal logic erro
1af0: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 r in SQLite */.#
1b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 define SQLITE_PE
1b10: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f RM 3 /
1b20: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 * Access permiss
1b30: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 ion denied */.#d
1b40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f efine SQLITE_ABO
1b50: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a RT 4 /*
1b60: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e Callback routin
1b70: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 e requested an a
1b80: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 bort */.#define
1b90: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 SQLITE_BUSY
1ba0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 5 /* The d
1bb0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 atabase file is
1bc0: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e locked */.#defin
1bd0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 e SQLITE_LOCKED
1be0: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 6 /* A t
1bf0: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 able in the data
1c00: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a base is locked *
1c10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1c20: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 _NOMEM 7
1c30: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 /* A malloc()
1c40: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e failed */.#defin
1c50: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
1c60: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 Y 8 /* Att
1c70: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 empt to write a
1c80: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 readonly databas
1c90: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
1ca0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 ITE_INTERRUPT
1cb0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 9 /* Operatio
1cc0: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 n terminated by
1cd0: 73 71 6c 69 74 65 5f 69 6e 74 65 72 72 75 70 74 sqlite_interrupt
1ce0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
1cf0: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 LITE_IOERR
1d00: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 10 /* Some ki
1d10: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 nd of disk I/O e
1d20: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f rror occurred */
1d30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1d40: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 CORRUPT 11
1d50: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
1d60: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d disk image is m
1d70: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 alformed */.#def
1d80: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f ine SQLITE_NOTFO
1d90: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 28 UND 12 /* (
1da0: 49 6e 74 65 72 6e 61 6c 20 4f 6e 6c 79 29 20 54 Internal Only) T
1db0: 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e able or record n
1dc0: 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 ot found */.#def
1dd0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 ine SQLITE_FULL
1de0: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 13 /* I
1df0: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 nsertion failed
1e00: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 because database
1e10: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 is full */.#def
1e20: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
1e30: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 PEN 14 /* U
1e40: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 nable to open th
1e50: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
1e60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1e70: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 E_PROTOCOL 15
1e80: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c /* Database l
1e90: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 ock protocol err
1ea0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
1eb0: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 LITE_EMPTY
1ec0: 20 31 36 20 20 20 2f 2a 20 28 49 6e 74 65 72 6e 16 /* (Intern
1ed0: 61 6c 20 4f 6e 6c 79 29 20 44 61 74 61 62 61 73 al Only) Databas
1ee0: 65 20 74 61 62 6c 65 20 69 73 20 65 6d 70 74 79 e table is empty
1ef0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1f00: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 TE_SCHEMA 1
1f10: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 7 /* The datab
1f20: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 ase schema chang
1f30: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
1f40: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 LITE_TOOBIG
1f50: 20 31 38 20 20 20 2f 2a 20 54 6f 6f 20 6d 75 63 18 /* Too muc
1f60: 68 20 64 61 74 61 20 66 6f 72 20 6f 6e 65 20 72 h data for one r
1f70: 6f 77 20 6f 66 20 61 20 74 61 62 6c 65 20 2a 2f ow of a table */
1f80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1f90: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 CONSTRAINT 19
1fa0: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f /* Abort due to
1fb0: 20 63 6f 6e 74 72 61 69 6e 74 20 76 69 6f 6c 61 contraint viola
1fc0: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 tion */.#define
1fd0: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 SQLITE_MISMATCH
1fe0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 20 /* Data
1ff0: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f type mismatch */
2000: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2010: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 MISUSE 21
2020: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 /* Library used
2030: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a incorrectly */.
2040: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
2050: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 OLFS 22
2060: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 /* Uses OS featu
2070: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 res not supporte
2080: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 d on host */.#de
2090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 fine SQLITE_AUTH
20a0: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 23 /*
20b0: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 Authorization de
20c0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nied */.#define
20d0: 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 SQLITE_ROW
20e0: 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 100 /* sqlit
20f0: 65 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f e_step() has ano
2100: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a ther row ready *
2110: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2120: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 _DONE 101
2130: 20 20 2f 2a 20 73 71 6c 69 74 65 5f 73 74 65 70 /* sqlite_step
2140: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 () has finished
2150: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 3c 2f 70 executing */.</p
2160: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
2170: 0a 0a 3c 70 3e 0a 54 68 65 20 6d 65 61 6e 69 6e ..<p>.The meanin
2180: 67 73 20 6f 66 20 74 68 65 73 65 20 76 61 72 69 gs of these vari
2190: 6f 75 73 20 72 65 74 75 72 6e 20 76 61 6c 75 65 ous return value
21a0: 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 s are as follows
21b0: 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 :.</p>..<blockqu
21c0: 6f 74 65 3e 0a 3c 64 6c 3e 0a 3c 64 74 3e 53 51 ote>.<dl>.<dt>SQ
21d0: 4c 49 54 45 5f 4f 4b 3c 2f 64 74 3e 0a 3c 64 64 LITE_OK</dt>.<dd
21e0: 3e 3c 70 3e 54 68 69 73 20 76 61 6c 75 65 20 69 ><p>This value i
21f0: 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 65 76 s returned if ev
2200: 65 72 79 74 68 69 6e 67 20 77 6f 72 6b 65 64 20 erything worked
2210: 61 6e 64 20 74 68 65 72 65 20 77 65 72 65 20 6e and there were n
2220: 6f 20 65 72 72 6f 72 73 2e 0a 3c 2f 70 3e 3c 2f o errors..</p></
2230: 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 49 dd>.<dt>SQLITE_I
2240: 4e 54 45 52 4e 41 4c 3c 2f 64 74 3e 0a 3c 64 64 NTERNAL</dt>.<dd
2250: 3e 3c 70 3e 54 68 69 73 20 76 61 6c 75 65 20 69 ><p>This value i
2260: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 61 6e ndicates that an
2270: 20 69 6e 74 65 72 6e 61 6c 20 63 6f 6e 73 69 73 internal consis
2280: 74 65 6e 63 79 20 63 68 65 63 6b 20 77 69 74 68 tency check with
2290: 69 6e 0a 74 68 65 20 53 51 4c 69 74 65 20 6c 69 in.the SQLite li
22a0: 62 72 61 72 79 20 66 61 69 6c 65 64 2e 20 20 54 brary failed. T
22b0: 68 69 73 20 63 61 6e 20 6f 6e 6c 79 20 68 61 70 his can only hap
22c0: 70 65 6e 20 69 66 20 74 68 65 72 65 20 69 73 20 pen if there is
22d0: 61 20 62 75 67 20 69 6e 0a 74 68 65 20 53 51 4c a bug in.the SQL
22e0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 49 66 ite library. If
22f0: 20 79 6f 75 20 65 76 65 72 20 67 65 74 20 61 6e you ever get an
2300: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c SQLITE_INTERNAL
2310: 20 72 65 70 6c 79 20 66 72 6f 6d 0a 61 6e 20 3c reply from.an <
2320: 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62 b>sqlite_exec</b
2330: 3e 20 63 61 6c 6c 2c 20 70 6c 65 61 73 65 20 72 > call, please r
2340: 65 70 6f 72 74 20 74 68 65 20 70 72 6f 62 6c 65 eport the proble
2350: 6d 20 6f 6e 20 74 68 65 20 53 51 4c 69 74 65 0a m on the SQLite.
2360: 6d 61 69 6c 69 6e 67 20 6c 69 73 74 2e 0a 3c 2f mailing list..</
2370: 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 p></dd>.<dt>SQLI
2380: 54 45 5f 45 52 52 4f 52 3c 2f 64 74 3e 0a 3c 64 TE_ERROR</dt>.<d
2390: 64 3e 3c 70 3e 54 68 69 73 20 72 65 74 75 72 6e d><p>This return
23a0: 20 76 61 6c 75 65 20 69 6e 64 69 63 61 74 65 73 value indicates
23b0: 20 74 68 61 74 20 74 68 65 72 65 20 77 61 73 20 that there was
23c0: 61 6e 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 an error in the
23d0: 53 51 4c 0a 74 68 61 74 20 77 61 73 20 70 61 73 SQL.that was pas
23e0: 73 65 64 20 69 6e 74 6f 20 74 68 65 20 3c 62 3e sed into the <b>
23f0: 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e 2e sqlite_exec</b>.
2400: 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 .</p></dd>.<dt>S
2410: 51 4c 49 54 45 5f 50 45 52 4d 3c 2f 64 74 3e 0a QLITE_PERM</dt>.
2420: 3c 64 64 3e 3c 70 3e 54 68 69 73 20 72 65 74 75 <dd><p>This retu
2430: 72 6e 20 76 61 6c 75 65 20 73 61 79 73 20 74 68 rn value says th
2440: 61 74 20 74 68 65 20 61 63 63 65 73 73 20 70 65 at the access pe
2450: 72 6d 69 73 73 69 6f 6e 73 20 6f 6e 20 74 68 65 rmissions on the
2460: 20 64 61 74 61 62 61 73 65 0a 66 69 6c 65 20 61 database.file a
2470: 72 65 20 73 75 63 68 20 74 68 61 74 20 74 68 65 re such that the
2480: 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 file cannot be
2490: 6f 70 65 6e 65 64 2e 0a 3c 2f 70 3e 3c 2f 64 64 opened..</p></dd
24a0: 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 41 42 4f >.<dt>SQLITE_ABO
24b0: 52 54 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 RT</dt>.<dd><p>T
24c0: 68 69 73 20 76 61 6c 75 65 20 69 73 20 72 65 74 his value is ret
24d0: 75 72 6e 65 64 20 69 66 20 74 68 65 20 63 61 6c urned if the cal
24e0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 lback function r
24f0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2e eturns non-zero.
2500: 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 .</p></dd>.<dt>S
2510: 51 4c 49 54 45 5f 42 55 53 59 3c 2f 64 74 3e 0a QLITE_BUSY</dt>.
2520: 3c 64 64 3e 3c 70 3e 54 68 69 73 20 72 65 74 75 <dd><p>This retu
2530: 72 6e 20 63 6f 64 65 20 69 6e 64 69 63 61 74 65 rn code indicate
2540: 73 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 70 s that another p
2550: 72 6f 67 72 61 6d 20 6f 72 20 74 68 72 65 61 64 rogram or thread
2560: 20 68 61 73 0a 74 68 65 20 64 61 74 61 62 61 73 has.the databas
2570: 65 20 6c 6f 63 6b 65 64 2e 20 20 53 51 4c 69 74 e locked. SQLit
2580: 65 20 61 6c 6c 6f 77 73 20 74 77 6f 20 6f 72 20 e allows two or
2590: 6d 6f 72 65 20 74 68 72 65 61 64 73 20 74 6f 20 more threads to
25a0: 72 65 61 64 20 74 68 65 0a 64 61 74 61 62 61 73 read the.databas
25b0: 65 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 e at the same ti
25c0: 6d 65 2c 20 62 75 74 20 6f 6e 6c 79 20 6f 6e 65 me, but only one
25d0: 20 74 68 72 65 61 64 20 63 61 6e 20 68 61 76 65 thread can have
25e0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 6f 70 the database.op
25f0: 65 6e 20 66 6f 72 20 77 72 69 74 69 6e 67 20 61 en for writing a
2600: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e t the same time.
2610: 20 20 4c 6f 63 6b 69 6e 67 20 69 6e 20 53 51 4c Locking in SQL
2620: 69 74 65 20 69 73 20 6f 6e 20 74 68 65 0a 65 6e ite is on the.en
2630: 74 69 72 65 20 64 61 74 61 62 61 73 65 2e 3c 2f tire database.</
2640: 70 3e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 p>.</p></dd>.<dt
2650: 3e 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 3c 2f >SQLITE_LOCKED</
2660: 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 dt>.<dd><p>This
2670: 72 65 74 75 72 6e 20 63 6f 64 65 20 69 73 20 73 return code is s
2680: 69 6d 69 6c 61 72 20 74 6f 20 53 51 4c 49 54 45 imilar to SQLITE
2690: 5f 42 55 53 59 20 69 6e 20 74 68 61 74 20 69 74 _BUSY in that it
26a0: 20 69 6e 64 69 63 61 74 65 73 0a 74 68 61 74 20 indicates.that
26b0: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
26c0: 6c 6f 63 6b 65 64 2e 20 20 42 75 74 20 74 68 65 locked. But the
26d0: 20 73 6f 75 72 63 65 20 6f 66 20 74 68 65 20 6c source of the l
26e0: 6f 63 6b 20 69 73 20 61 20 72 65 63 75 72 73 69 ock is a recursi
26f0: 76 65 0a 63 61 6c 6c 20 74 6f 20 3c 62 3e 73 71 ve.call to <b>sq
2700: 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e 2e 20 20 lite_exec</b>.
2710: 54 68 69 73 20 72 65 74 75 72 6e 20 63 61 6e 20 This return can
2720: 6f 6e 6c 79 20 6f 63 63 75 72 20 69 66 20 79 6f only occur if yo
2730: 75 20 61 74 74 65 6d 70 74 0a 74 6f 20 69 6e 76 u attempt.to inv
2740: 6f 6b 65 20 73 71 6c 69 74 65 5f 65 78 65 63 20 oke sqlite_exec
2750: 66 72 6f 6d 20 77 69 74 68 69 6e 20 61 20 63 61 from within a ca
2760: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 6f llback routine o
2770: 66 20 61 20 71 75 65 72 79 0a 66 72 6f 6d 20 61 f a query.from a
2780: 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f prior invocatio
2790: 6e 20 6f 66 20 73 71 6c 69 74 65 5f 65 78 65 63 n of sqlite_exec
27a0: 2e 20 20 52 65 63 75 72 73 69 76 65 20 63 61 6c . Recursive cal
27b0: 6c 73 20 74 6f 0a 73 71 6c 69 74 65 5f 65 78 65 ls to.sqlite_exe
27c0: 63 20 61 72 65 20 61 6c 6c 6f 77 65 64 20 61 73 c are allowed as
27d0: 20 6c 6f 6e 67 20 61 73 20 74 68 65 79 20 64 6f long as they do
27e0: 0a 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 .not attempt to
27f0: 77 72 69 74 65 20 74 68 65 20 73 61 6d 65 20 74 write the same t
2800: 61 62 6c 65 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a able..</p></dd>.
2810: 3c 64 74 3e 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d <dt>SQLITE_NOMEM
2820: 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 </dt>.<dd><p>Thi
2830: 73 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 s value is retur
2840: 6e 65 64 20 69 66 20 61 20 63 61 6c 6c 20 74 6f ned if a call to
2850: 20 3c 62 3e 6d 61 6c 6c 6f 63 3c 2f 62 3e 20 66 <b>malloc</b> f
2860: 61 69 6c 73 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a ails..</p></dd>.
2870: 3c 64 74 3e 53 51 4c 49 54 45 5f 52 45 41 44 4f <dt>SQLITE_READO
2880: 4e 4c 59 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e NLY</dt>.<dd><p>
2890: 54 68 69 73 20 72 65 74 75 72 6e 20 63 6f 64 65 This return code
28a0: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 indicates that
28b0: 61 6e 20 61 74 74 65 6d 70 74 20 77 61 73 20 6d an attempt was m
28c0: 61 64 65 20 74 6f 20 77 72 69 74 65 20 74 6f 0a ade to write to.
28d0: 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 a database file
28e0: 74 68 61 74 20 69 73 20 6f 70 65 6e 65 64 20 66 that is opened f
28f0: 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e or reading only.
2900: 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 .</p></dd>.<dt>S
2910: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 3c QLITE_INTERRUPT<
2920: 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 /dt>.<dd><p>This
2930: 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e value is return
2940: 65 64 20 69 66 20 61 20 63 61 6c 6c 20 74 6f 20 ed if a call to
2950: 3c 62 3e 73 71 6c 69 74 65 5f 69 6e 74 65 72 72 <b>sqlite_interr
2960: 75 70 74 3c 2f 62 3e 0a 69 6e 74 65 72 72 75 70 upt</b>.interrup
2970: 74 73 20 61 20 64 61 74 61 62 61 73 65 20 6f 70 ts a database op
2980: 65 72 61 74 69 6f 6e 20 69 6e 20 70 72 6f 67 72 eration in progr
2990: 65 73 73 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c ess..</p></dd>.<
29a0: 64 74 3e 53 51 4c 49 54 45 5f 49 4f 45 52 52 3c dt>SQLITE_IOERR<
29b0: 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 /dt>.<dd><p>This
29c0: 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e value is return
29d0: 65 64 20 69 66 20 74 68 65 20 6f 70 65 72 61 74 ed if the operat
29e0: 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 66 6f 72 ing system infor
29f0: 6d 73 20 53 51 4c 69 74 65 0a 74 68 61 74 20 69 ms SQLite.that i
2a00: 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 t is unable to p
2a10: 65 72 66 6f 72 6d 20 73 6f 6d 65 20 64 69 73 6b erform some disk
2a20: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 2e 20 I/O operation.
2a30: 20 54 68 69 73 20 63 6f 75 6c 64 20 6d 65 61 6e This could mean
2a40: 0a 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e .that there is n
2a50: 6f 20 6d 6f 72 65 20 73 70 61 63 65 20 6c 65 66 o more space lef
2a60: 74 20 6f 6e 20 74 68 65 20 64 69 73 6b 2e 0a 3c t on the disk..<
2a70: 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c /p></dd>.<dt>SQL
2a80: 49 54 45 5f 43 4f 52 52 55 50 54 3c 2f 64 74 3e ITE_CORRUPT</dt>
2a90: 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 76 61 6c .<dd><p>This val
2aa0: 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 ue is returned i
2ab0: 66 20 53 51 4c 69 74 65 20 64 65 74 65 63 74 73 f SQLite detects
2ac0: 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 that the databa
2ad0: 73 65 20 69 74 20 69 73 0a 77 6f 72 6b 69 6e 67 se it is.working
2ae0: 20 6f 6e 20 68 61 73 20 62 65 63 6f 6d 65 20 63 on has become c
2af0: 6f 72 72 75 70 74 65 64 2e 20 20 43 6f 72 72 75 orrupted. Corru
2b00: 70 74 69 6f 6e 20 6d 69 67 68 74 20 6f 63 63 75 ption might occu
2b10: 72 20 64 75 65 20 74 6f 20 61 20 72 6f 67 75 65 r due to a rogue
2b20: 0a 70 72 6f 63 65 73 73 20 77 72 69 74 69 6e 67 .process writing
2b30: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 to the database
2b40: 20 66 69 6c 65 20 6f 72 20 69 74 20 6d 69 67 68 file or it migh
2b50: 74 20 68 61 70 70 65 6e 20 64 75 65 20 74 6f 20 t happen due to
2b60: 61 6e 20 0a 70 65 72 76 69 6f 75 73 6c 79 20 75 an .perviously u
2b70: 6e 64 65 74 65 63 74 65 64 20 6c 6f 67 69 63 20 ndetected logic
2b80: 65 72 72 6f 72 20 69 6e 20 6f 66 20 53 51 4c 69 error in of SQLi
2b90: 74 65 2e 20 54 68 69 73 20 76 61 6c 75 65 20 69 te. This value i
2ba0: 73 20 61 6c 73 6f 0a 72 65 74 75 72 6e 65 64 20 s also.returned
2bb0: 69 66 20 61 20 64 69 73 6b 20 49 2f 4f 20 65 72 if a disk I/O er
2bc0: 72 6f 72 20 6f 63 63 75 72 73 20 69 6e 20 73 75 ror occurs in su
2bd0: 63 68 20 61 20 77 61 79 20 74 68 61 74 20 53 51 ch a way that SQ
2be0: 4c 69 74 65 20 69 73 20 66 6f 72 63 65 64 0a 74 Lite is forced.t
2bf0: 6f 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 o leave the data
2c00: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 61 20 63 base file in a c
2c10: 6f 72 72 75 70 74 65 64 20 73 74 61 74 65 2e 20 orrupted state.
2c20: 20 54 68 65 20 6c 61 74 74 65 72 20 73 68 6f 75 The latter shou
2c30: 6c 64 20 6f 6e 6c 79 0a 68 61 70 70 65 6e 20 64 ld only.happen d
2c40: 75 65 20 74 6f 20 61 20 68 61 72 64 77 61 72 65 ue to a hardware
2c50: 20 6f 72 20 6f 70 65 72 61 74 69 6e 67 20 73 79 or operating sy
2c60: 73 74 65 6d 20 6d 61 6c 66 75 6e 63 74 69 6f 6e stem malfunction
2c70: 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e ..</p></dd>.<dt>
2c80: 53 51 4c 49 54 45 5f 46 55 4c 4c 3c 2f 64 74 3e SQLITE_FULL</dt>
2c90: 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 76 61 6c .<dd><p>This val
2ca0: 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 ue is returned i
2cb0: 66 20 61 6e 20 69 6e 73 65 72 74 69 6f 6e 20 66 f an insertion f
2cc0: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 74 68 ailed because th
2cd0: 65 72 65 20 69 73 0a 6e 6f 20 73 70 61 63 65 20 ere is.no space
2ce0: 6c 65 66 74 20 6f 6e 20 74 68 65 20 64 69 73 6b left on the disk
2cf0: 2c 20 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 , or the databas
2d00: 65 20 69 73 20 74 6f 6f 20 62 69 67 20 74 6f 20 e is too big to
2d10: 68 6f 6c 64 20 61 6e 79 0a 6d 6f 72 65 20 69 6e hold any.more in
2d20: 66 6f 72 6d 61 74 69 6f 6e 2e 20 20 54 68 65 20 formation. The
2d30: 6c 61 74 74 65 72 20 63 61 73 65 20 73 68 6f 75 latter case shou
2d40: 6c 64 20 6f 6e 6c 79 20 6f 63 63 75 72 20 66 6f ld only occur fo
2d50: 72 20 64 61 74 61 62 61 73 65 73 0a 74 68 61 74 r databases.that
2d60: 20 61 72 65 20 6c 61 72 67 65 72 20 74 68 61 6e are larger than
2d70: 20 32 47 42 20 69 6e 20 73 69 7a 65 2e 0a 3c 2f 2GB in size..</
2d80: 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 p></dd>.<dt>SQLI
2d90: 54 45 5f 43 41 4e 54 4f 50 45 4e 3c 2f 64 74 3e TE_CANTOPEN</dt>
2da0: 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 76 61 6c .<dd><p>This val
2db0: 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 ue is returned i
2dc0: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 f the database f
2dd0: 69 6c 65 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 ile could not be
2de0: 20 6f 70 65 6e 65 64 0a 66 6f 72 20 73 6f 6d 65 opened.for some
2df0: 20 72 65 61 73 6f 6e 2e 0a 3c 2f 70 3e 3c 2f 64 reason..</p></d
2e00: 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 d>.<dt>SQLITE_PR
2e10: 4f 54 4f 43 4f 4c 3c 2f 64 74 3e 0a 3c 64 64 3e OTOCOL</dt>.<dd>
2e20: 3c 70 3e 54 68 69 73 20 76 61 6c 75 65 20 69 73 <p>This value is
2e30: 20 72 65 74 75 72 6e 65 64 20 69 66 20 73 6f 6d returned if som
2e40: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 20 e other process
2e50: 69 73 20 6d 65 73 73 69 6e 67 20 77 69 74 68 0a is messing with.
2e60: 66 69 6c 65 20 6c 6f 63 6b 73 20 61 6e 64 20 68 file locks and h
2e70: 61 73 20 76 69 6f 6c 61 74 65 64 20 74 68 65 20 as violated the
2e80: 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 70 72 6f file locking pro
2e90: 74 6f 63 6f 6c 20 74 68 61 74 20 53 51 4c 69 74 tocol that SQLit
2ea0: 65 20 75 73 65 73 0a 6f 6e 20 69 74 73 20 72 6f e uses.on its ro
2eb0: 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 66 llback journal f
2ec0: 69 6c 65 73 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a iles..</p></dd>.
2ed0: 3c 64 74 3e 53 51 4c 49 54 45 5f 53 43 48 45 4d <dt>SQLITE_SCHEM
2ee0: 41 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 57 68 A</dt>.<dd><p>Wh
2ef0: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
2f00: 66 69 72 73 74 20 6f 70 65 6e 65 64 2c 20 53 51 first opened, SQ
2f10: 4c 69 74 65 20 72 65 61 64 73 20 74 68 65 20 64 Lite reads the d
2f20: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 0a 69 atabase schema.i
2f30: 6e 74 6f 20 6d 65 6d 6f 72 79 20 61 6e 64 20 75 nto memory and u
2f40: 73 65 73 20 74 68 61 74 20 73 63 68 65 6d 61 20 ses that schema
2f50: 74 6f 20 70 61 72 73 65 20 6e 65 77 20 53 51 4c to parse new SQL
2f60: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 49 66 statements. If
2f70: 20 61 6e 6f 74 68 65 72 0a 70 72 6f 63 65 73 73 another.process
2f80: 20 63 68 61 6e 67 65 73 20 74 68 65 20 73 63 68 changes the sch
2f90: 65 6d 61 2c 20 74 68 65 20 63 6f 6d 6d 61 6e 64 ema, the command
2fa0: 20 63 75 72 72 65 6e 74 6c 79 20 62 65 69 6e 67 currently being
2fb0: 20 70 72 6f 63 65 73 73 65 64 20 77 69 6c 6c 0a processed will.
2fc0: 61 62 6f 72 74 20 62 65 63 61 75 73 65 20 74 68 abort because th
2fd0: 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e e virtual machin
2fe0: 65 20 63 6f 64 65 20 67 65 6e 65 72 61 74 65 64 e code generated
2ff0: 20 61 73 73 75 6d 65 64 20 74 68 65 20 6f 6c 64 assumed the old
3000: 0a 73 63 68 65 6d 61 2e 20 20 54 68 69 73 20 69 .schema. This i
3010: 73 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 s the return cod
3020: 65 20 66 6f 72 20 73 75 63 68 20 63 61 73 65 73 e for such cases
3030: 2e 20 20 52 65 74 72 79 69 6e 67 20 74 68 65 0a . Retrying the.
3040: 63 6f 6d 6d 61 6e 64 20 75 73 75 61 6c 6c 79 20 command usually
3050: 77 69 6c 6c 20 63 6c 65 61 72 20 74 68 65 20 70 will clear the p
3060: 72 6f 62 6c 65 6d 2e 0a 3c 2f 70 3e 3c 2f 64 64 roblem..</p></dd
3070: 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 54 4f 4f >.<dt>SQLITE_TOO
3080: 42 49 47 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e BIG</dt>.<dd><p>
3090: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 SQLite will not
30a0: 73 74 6f 72 65 20 6d 6f 72 65 20 74 68 61 6e 20 store more than
30b0: 61 62 6f 75 74 20 31 20 6d 65 67 61 62 79 74 65 about 1 megabyte
30c0: 20 6f 66 20 64 61 74 61 20 69 6e 20 61 20 73 69 of data in a si
30d0: 6e 67 6c 65 0a 72 6f 77 20 6f 66 20 61 20 73 69 ngle.row of a si
30e0: 6e 67 6c 65 20 74 61 62 6c 65 2e 20 20 49 66 20 ngle table. If
30f0: 79 6f 75 20 61 74 74 65 6d 70 74 20 74 6f 20 73 you attempt to s
3100: 74 6f 72 65 20 6d 6f 72 65 20 74 68 61 6e 20 31 tore more than 1
3110: 20 6d 65 67 61 62 79 74 65 0a 69 6e 20 61 20 73 megabyte.in a s
3120: 69 6e 67 6c 65 20 72 6f 77 2c 20 74 68 69 73 20 ingle row, this
3130: 69 73 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f is the return co
3140: 64 65 20 79 6f 75 20 67 65 74 2e 0a 3c 2f 70 3e de you get..</p>
3150: 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 </dd>.<dt>SQLITE
3160: 5f 43 4f 4e 53 54 52 41 49 4e 54 3c 2f 64 74 3e _CONSTRAINT</dt>
3170: 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 63 6f 6e .<dd><p>This con
3180: 73 74 61 6e 74 20 69 73 20 72 65 74 75 72 6e 65 stant is returne
3190: 64 20 69 66 20 74 68 65 20 53 51 4c 20 73 74 61 d if the SQL sta
31a0: 74 65 6d 65 6e 74 20 77 6f 75 6c 64 20 68 61 76 tement would hav
31b0: 65 20 76 69 6f 6c 61 74 65 64 0a 61 20 64 61 74 e violated.a dat
31c0: 61 62 61 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 abase constraint
31d0: 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e ..</p></dd>.<dt>
31e0: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 3c SQLITE_MISMATCH<
31f0: 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 /dt>.<dd><p>This
3200: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 error occurs wh
3210: 65 6e 20 74 68 65 72 65 20 69 73 20 61 6e 20 61 en there is an a
3220: 74 74 65 6d 70 74 20 74 6f 20 69 6e 73 65 72 74 ttempt to insert
3230: 20 6e 6f 6e 2d 69 6e 74 65 67 65 72 0a 64 61 74 non-integer.dat
3240: 61 20 69 6e 74 6f 20 61 20 63 6f 6c 75 6d 6e 20 a into a column
3250: 6c 61 62 65 6c 65 64 20 49 4e 54 45 47 45 52 20 labeled INTEGER
3260: 50 52 49 4d 41 52 59 20 4b 45 59 2e 20 20 46 6f PRIMARY KEY. Fo
3270: 72 20 6d 6f 73 74 20 63 6f 6c 75 6d 6e 73 2c 20 r most columns,
3280: 53 51 4c 69 74 65 0a 69 67 6e 6f 72 65 73 20 74 SQLite.ignores t
3290: 68 65 20 64 61 74 61 20 74 79 70 65 20 61 6e 64 he data type and
32a0: 20 61 6c 6c 6f 77 73 20 61 6e 79 20 6b 69 6e 64 allows any kind
32b0: 20 6f 66 20 64 61 74 61 20 74 6f 20 62 65 20 73 of data to be s
32c0: 74 6f 72 65 64 2e 20 20 42 75 74 0a 61 6e 20 49 tored. But.an I
32d0: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b NTEGER PRIMARY K
32e0: 45 59 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 6e 6c EY column is onl
32f0: 79 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 74 6f y allowed to sto
3300: 72 65 20 69 6e 74 65 67 65 72 20 64 61 74 61 2e re integer data.
3310: 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 .</p></dd>.<dt>S
3320: 51 4c 49 54 45 5f 4d 49 53 55 53 45 3c 2f 64 74 QLITE_MISUSE</dt
3330: 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 65 72 >.<dd><p>This er
3340: 72 6f 72 20 6d 69 67 68 74 20 6f 63 63 75 72 20 ror might occur
3350: 69 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f if one or more o
3360: 66 20 74 68 65 20 53 51 4c 69 74 65 20 41 50 49 f the SQLite API
3370: 20 72 6f 75 74 69 6e 65 73 0a 69 73 20 75 73 65 routines.is use
3380: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 2e 20 20 d incorrectly.
3390: 45 78 61 6d 70 6c 65 73 20 6f 66 20 69 6e 63 6f Examples of inco
33a0: 72 72 65 63 74 20 75 73 61 67 65 20 69 6e 63 6c rrect usage incl
33b0: 75 64 65 20 63 61 6c 6c 69 6e 67 0a 3c 62 3e 73 ude calling.<b>s
33c0: 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e 20 61 qlite_exec</b> a
33d0: 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61 73 fter the databas
33e0: 65 20 68 61 73 20 62 65 65 6e 20 63 6c 6f 73 65 e has been close
33f0: 64 20 75 73 69 6e 67 0a 3c 62 3e 73 71 6c 69 74 d using.<b>sqlit
3400: 65 5f 63 6c 6f 73 65 3c 2f 62 3e 20 6f 72 20 0a e_close</b> or .
3410: 63 61 6c 6c 69 6e 67 20 3c 62 3e 73 71 6c 69 74 calling <b>sqlit
3420: 65 5f 65 78 65 63 3c 2f 62 3e 20 77 69 74 68 20 e_exec</b> with
3430: 74 68 65 20 73 61 6d 65 0a 64 61 74 61 62 61 73 the same.databas
3440: 65 20 70 6f 69 6e 74 65 72 20 73 69 6d 75 6c 74 e pointer simult
3450: 61 6e 65 6f 75 73 6c 79 20 66 72 6f 6d 20 74 77 aneously from tw
3460: 6f 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 o separate threa
3470: 64 73 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 ds..</p></dd>.<d
3480: 74 3e 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 3c 2f t>SQLITE_NOLFS</
3490: 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 dt>.<dd><p>This
34a0: 65 72 72 6f 72 20 6d 65 61 6e 73 20 74 68 61 74 error means that
34b0: 20 79 6f 75 20 68 61 76 65 20 61 74 74 65 6d 70 you have attemp
34c0: 74 73 20 74 6f 20 63 72 65 61 74 65 20 6f 72 20 ts to create or
34d0: 61 63 63 65 73 73 20 61 20 66 69 6c 65 0a 64 61 access a file.da
34e0: 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 tabase file that
34f0: 20 69 73 20 6c 61 72 67 65 72 20 74 68 61 74 20 is larger that
3500: 32 47 42 20 6f 6e 20 61 20 6c 65 67 61 63 79 20 2GB on a legacy
3510: 55 6e 69 78 20 6d 61 63 68 69 6e 65 20 74 68 61 Unix machine tha
3520: 74 0a 6c 61 63 6b 73 20 6c 61 72 67 65 20 66 69 t.lacks large fi
3530: 6c 65 20 73 75 70 70 6f 72 74 2e 0a 3c 2f 70 3e le support..</p>
3540: 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 </dd>.<dt>SQLITE
3550: 5f 41 55 54 48 3c 2f 64 74 3e 0a 3c 64 64 3e 3c _AUTH</dt>.<dd><
3560: 70 3e 54 68 69 73 20 65 72 72 6f 72 20 69 6e 64 p>This error ind
3570: 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 icates that the
3580: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
3590: 61 63 6b 0a 68 61 73 20 64 69 73 61 6c 6c 6f 77 ack.has disallow
35a0: 65 64 20 74 68 65 20 53 51 4c 20 79 6f 75 20 61 ed the SQL you a
35b0: 72 65 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f re attempting to
35c0: 20 65 78 65 63 75 74 65 2e 0a 3c 2f 70 3e 3c 2f execute..</p></
35d0: 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 52 dd>.<dt>SQLITE_R
35e0: 4f 57 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 OW</dt>.<dd><p>T
35f0: 68 69 73 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 his is one of th
3600: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 73 20 66 e return codes f
3610: 72 6f 6d 20 74 68 65 0a 3c 62 3e 73 71 6c 69 74 rom the.<b>sqlit
3620: 65 5f 73 74 65 70 3c 2f 62 3e 20 72 6f 75 74 69 e_step</b> routi
3630: 6e 65 20 77 68 69 63 68 20 69 73 20 70 61 72 74 ne which is part
3640: 20 6f 66 20 74 68 65 20 6e 6f 6e 2d 63 61 6c 6c of the non-call
3650: 62 61 63 6b 20 41 50 49 2e 0a 49 74 20 69 6e 64 back API..It ind
3660: 69 63 61 74 65 73 20 74 68 61 74 20 61 6e 6f 74 icates that anot
3670: 68 65 72 20 72 6f 77 20 6f 66 20 72 65 73 75 6c her row of resul
3680: 74 20 64 61 74 61 20 69 73 20 61 76 61 69 6c 61 t data is availa
3690: 62 6c 65 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c ble..</p></dd>.<
36a0: 64 74 3e 53 51 4c 49 54 45 5f 44 4f 4e 45 3c 2f dt>SQLITE_DONE</
36b0: 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 dt>.<dd><p>This
36c0: 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 72 65 is one of the re
36d0: 74 75 72 6e 20 63 6f 64 65 73 20 66 72 6f 6d 20 turn codes from
36e0: 74 68 65 0a 3c 62 3e 73 71 6c 69 74 65 5f 73 74 the.<b>sqlite_st
36f0: 65 70 3c 2f 62 3e 20 72 6f 75 74 69 6e 65 20 77 ep</b> routine w
3700: 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 hich is part of
3710: 74 68 65 20 6e 6f 6e 2d 63 61 6c 6c 62 61 63 6b the non-callback
3720: 20 41 50 49 2e 0a 49 74 20 69 6e 64 69 63 61 74 API..It indicat
3730: 65 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 es that the SQL
3740: 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 62 65 statement has be
3750: 65 6e 20 63 6f 6d 70 6c 65 74 65 6c 79 20 65 78 en completely ex
3760: 65 63 75 74 65 64 20 61 6e 64 0a 74 68 65 20 3c ecuted and.the <
3770: 62 3e 73 71 6c 69 74 65 5f 66 69 6e 61 6c 69 7a b>sqlite_finaliz
3780: 65 3c 2f 62 3e 20 72 6f 75 74 69 6e 65 20 69 73 e</b> routine is
3790: 20 72 65 61 64 79 20 74 6f 20 62 65 20 63 61 6c ready to be cal
37a0: 6c 65 64 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c led..</p></dd>.<
37b0: 2f 64 6c 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /dl>.</blockquot
37c0: 65 3e 0a 0a 3c 68 33 3e 32 2e 30 20 41 63 63 65 e>..<h3>2.0 Acce
37d0: 73 73 69 6e 67 20 44 61 74 61 20 57 69 74 68 6f ssing Data Witho
37e0: 75 74 20 55 73 69 6e 67 20 41 20 43 61 6c 6c 62 ut Using A Callb
37f0: 61 63 6b 20 46 75 6e 63 74 69 6f 6e 3c 2f 68 33 ack Function</h3
3800: 3e 0a 0a 3c 70 3e 0a 54 68 65 20 3c 62 3e 73 71 >..<p>.The <b>sq
3810: 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e 20 72 6f lite_exec</b> ro
3820: 75 74 69 6e 65 20 64 65 73 63 72 69 62 65 64 20 utine described
3830: 61 62 6f 76 65 20 75 73 65 64 20 74 6f 20 62 65 above used to be
3840: 20 74 68 65 20 6f 6e 6c 79 0a 77 61 79 20 74 6f the only.way to
3850: 20 72 65 74 72 69 65 76 65 20 64 61 74 61 20 66 retrieve data f
3860: 72 6f 6d 20 61 6e 20 53 51 4c 69 74 65 20 64 61 rom an SQLite da
3870: 74 61 62 61 73 65 2e 20 20 42 75 74 20 6d 61 6e tabase. But man
3880: 79 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 66 6f y programmers fo
3890: 75 6e 64 0a 69 74 20 69 6e 63 6f 6e 76 65 6e 69 und.it inconveni
38a0: 65 6e 74 20 74 6f 20 75 73 65 20 61 20 63 61 6c ent to use a cal
38b0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 lback function t
38c0: 6f 20 6f 62 74 61 69 6e 20 72 65 73 75 6c 74 73 o obtain results
38d0: 2e 20 20 53 6f 20 62 65 67 69 6e 6e 69 6e 67 0a . So beginning.
38e0: 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 with SQLite vers
38f0: 69 6f 6e 20 32 2e 37 2e 37 2c 20 61 20 73 65 63 ion 2.7.7, a sec
3900: 6f 6e 64 20 61 63 63 65 73 73 20 69 6e 74 65 72 ond access inter
3910: 66 61 63 65 20 69 73 20 61 76 61 69 6c 61 62 6c face is availabl
3920: 65 20 74 68 61 74 0a 64 6f 65 73 20 6e 6f 74 20 e that.does not
3930: 75 73 65 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 3c use callbacks..<
3940: 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 6e 65 77 /p>..<p>.The new
3950: 20 69 6e 74 65 72 66 61 63 65 20 75 73 65 73 20 interface uses
3960: 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 66 three separate f
3970: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 72 65 70 6c unctions to repl
3980: 61 63 65 20 74 68 65 20 73 69 6e 67 6c 65 0a 3c ace the single.<
3990: 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62 b>sqlite_exec</b
39a0: 3e 20 66 75 6e 63 74 69 6f 6e 2e 0a 3c 2f 70 3e > function..</p>
39b0: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 ..<blockquote><p
39c0: 72 65 3e 0a 74 79 70 65 64 65 66 20 73 74 72 75 re>.typedef stru
39d0: 63 74 20 73 71 6c 69 74 65 5f 76 6d 20 73 71 6c ct sqlite_vm sql
39e0: 69 74 65 5f 76 6d 3b 0a 0a 69 6e 74 20 73 71 6c ite_vm;..int sql
39f0: 69 74 65 5f 63 6f 6d 70 69 6c 65 28 0a 20 20 73 ite_compile(. s
3a00: 71 6c 69 74 65 20 2a 64 62 2c 20 20 20 20 20 20 qlite *db,
3a10: 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 6f /* The o
3a20: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a pen database */.
3a30: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
3a40: 71 6c 2c 20 20 20 20 20 20 20 20 2f 2a 20 53 51 ql, /* SQ
3a50: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 L statement to b
3a60: 65 20 63 6f 6d 70 69 6c 65 64 20 2a 2f 0a 20 20 e compiled */.
3a70: 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 const char **pzT
3a80: 61 69 6c 2c 20 20 20 20 20 2f 2a 20 4f 55 54 3a ail, /* OUT:
3a90: 20 75 6e 63 6f 6d 70 69 6c 65 64 20 74 61 69 6c uncompiled tail
3aa0: 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 20 20 73 71 of zSql */. sq
3ab0: 6c 69 74 65 5f 76 6d 20 2a 2a 70 70 56 6d 2c 20 lite_vm **ppVm,
3ac0: 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 74 /* OUT: t
3ad0: 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 he virtual machi
3ae0: 6e 65 20 74 6f 20 65 78 65 63 75 74 65 20 7a 53 ne to execute zS
3af0: 71 6c 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 ql */. char **p
3b00: 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 zErrmsg
3b10: 20 2f 2a 20 4f 55 54 3a 20 45 72 72 6f 72 20 6d /* OUT: Error m
3b20: 65 73 73 61 67 65 2e 20 2a 2f 0a 29 3b 0a 0a 69 essage. */.);..i
3b30: 6e 74 20 73 71 6c 69 74 65 5f 73 74 65 70 28 0a nt sqlite_step(.
3b40: 20 20 73 71 6c 69 74 65 5f 76 6d 20 2a 70 56 6d sqlite_vm *pVm
3b50: 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68 , /* Th
3b60: 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e e virtual machin
3b70: 65 20 74 6f 20 65 78 65 63 75 74 65 20 2a 2f 0a e to execute */.
3b80: 20 20 69 6e 74 20 2a 70 4e 2c 20 20 20 20 20 20 int *pN,
3b90: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 /* OU
3ba0: 54 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c T: Number of col
3bb0: 75 6d 6e 73 20 69 6e 20 72 65 73 75 6c 74 20 2a umns in result *
3bc0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
3bd0: 2a 2a 70 61 7a 56 61 6c 75 65 2c 20 20 2f 2a 20 **pazValue, /*
3be0: 4f 55 54 3a 20 43 6f 6c 75 6d 6e 20 64 61 74 61 OUT: Column data
3bf0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
3c00: 20 2a 2a 2a 70 61 7a 43 6f 6c 4e 61 6d 65 20 2f ***pazColName /
3c10: 2a 20 4f 55 54 3a 20 43 6f 6c 75 6d 6e 20 6e 61 * OUT: Column na
3c20: 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 mes and datatype
3c30: 73 20 2a 2f 0a 29 3b 0a 0a 69 6e 74 20 73 71 6c s */.);..int sql
3c40: 69 74 65 5f 66 69 6e 61 6c 69 7a 65 28 0a 20 20 ite_finalize(.
3c50: 73 71 6c 69 74 65 5f 76 6d 20 2a 70 56 6d 2c 20 sqlite_vm *pVm,
3c60: 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 /* The
3c70: 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
3c80: 74 6f 20 62 65 20 66 69 6e 61 6c 69 7a 65 64 20 to be finalized
3c90: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 */. char **pzEr
3ca0: 72 4d 73 67 20 20 20 20 20 20 20 20 20 20 2f 2a rMsg /*
3cb0: 20 4f 55 54 3a 20 45 72 72 6f 72 20 6d 65 73 73 OUT: Error mess
3cc0: 61 67 65 20 2a 2f 0a 29 3b 0a 3c 2f 70 72 65 3e age */.);.</pre>
3cd0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c </blockquote>..<
3ce0: 70 3e 0a 54 68 65 20 73 74 72 61 74 65 67 79 20 p>.The strategy
3cf0: 69 73 20 74 6f 20 63 6f 6d 70 69 6c 65 20 61 20 is to compile a
3d00: 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 single SQL state
3d10: 6d 65 6e 74 20 75 73 69 6e 67 0a 3c 62 3e 73 71 ment using.<b>sq
3d20: 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 3c 2f 62 3e lite_compile</b>
3d30: 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 3c 62 3e then invoke <b>
3d40: 73 71 6c 69 74 65 5f 73 74 65 70 3c 2f 62 3e 20 sqlite_step</b>
3d50: 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 2c 0a multiple times,.
3d60: 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f once for each ro
3d70: 77 20 6f 66 20 6f 75 74 70 75 74 2c 20 61 6e 64 w of output, and
3d80: 20 66 69 6e 61 6c 6c 79 20 63 61 6c 6c 20 3c 62 finally call <b
3d90: 3e 73 71 6c 69 74 65 5f 66 69 6e 61 6c 69 7a 65 >sqlite_finalize
3da0: 3c 2f 62 3e 0a 74 6f 20 63 6c 65 61 6e 20 75 70 </b>.to clean up
3db0: 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 20 68 after the SQL h
3dc0: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 as finished exec
3dd0: 75 74 69 6f 6e 2e 0a 3c 2f 70 3e 0a 0a 3c 68 34 ution..</p>..<h4
3de0: 3e 32 2e 31 20 43 6f 6d 70 69 6c 69 6e 67 20 41 >2.1 Compiling A
3df0: 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 n SQL Statement
3e00: 49 6e 74 6f 20 41 20 56 69 72 74 75 61 6c 20 4d Into A Virtual M
3e10: 61 63 68 69 6e 65 3c 2f 68 34 3e 0a 0a 3c 70 3e achine</h4>..<p>
3e20: 0a 54 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 63 .The <b>sqlite_c
3e30: 6f 6d 70 69 6c 65 3c 2f 62 3e 20 22 63 6f 6d 70 ompile</b> "comp
3e40: 69 6c 65 73 22 20 61 20 73 69 6e 67 6c 65 20 53 iles" a single S
3e50: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 28 73 70 QL statement (sp
3e60: 65 63 69 66 69 65 64 0a 62 79 20 74 68 65 20 73 ecified.by the s
3e70: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 29 econd parameter)
3e80: 20 61 6e 64 20 67 65 6e 65 72 61 74 65 73 20 61 and generates a
3e90: 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 virtual machine
3ea0: 20 74 68 61 74 20 69 73 20 61 62 6c 65 0a 74 6f that is able.to
3eb0: 20 65 78 65 63 75 74 65 20 74 68 61 74 20 73 74 execute that st
3ec0: 61 74 65 6d 65 6e 74 2e 20 20 0a 41 73 20 77 69 atement. .As wi
3ed0: 74 68 20 6d 75 73 74 20 69 6e 74 65 72 66 61 63 th must interfac
3ee0: 65 20 72 6f 75 74 69 6e 65 73 2c 20 74 68 65 20 e routines, the
3ef0: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
3f00: 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 must be a pointe
3f10: 72 0a 74 6f 20 61 6e 20 73 71 6c 69 74 65 20 73 r.to an sqlite s
3f20: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 77 61 tructure that wa
3f30: 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 s obtained from
3f40: 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 0a a prior call to.
3f50: 3c 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e 3c 2f <b>sqlite_open</
3f60: 62 3e 2e 0a 0a 3c 70 3e 0a 41 20 70 6f 69 6e 74 b>...<p>.A point
3f70: 65 72 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 er to the virtua
3f80: 6c 20 6d 61 63 68 69 6e 65 20 69 73 20 73 74 6f l machine is sto
3f90: 72 65 64 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 red in a pointer
3fa0: 20 77 68 69 63 68 20 69 73 20 70 61 73 73 65 64 which is passed
3fb0: 0a 69 6e 20 61 73 20 74 68 65 20 34 74 68 20 70 .in as the 4th p
3fc0: 61 72 61 6d 65 74 65 72 2e 0a 53 70 61 63 65 20 arameter..Space
3fd0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 76 69 72 74 to hold the virt
3fe0: 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 73 20 64 ual machine is d
3ff0: 79 6e 61 6d 69 63 61 6c 6c 79 20 61 6c 6c 6f 63 ynamically alloc
4000: 61 74 65 64 2e 20 20 54 6f 20 61 76 6f 69 64 0a ated. To avoid.
4010: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 20 74 a memory leak, t
4020: 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 he calling funct
4030: 69 6f 6e 20 6d 75 73 74 20 69 6e 76 6f 6b 65 0a ion must invoke.
4040: 3c 62 3e 73 71 6c 69 74 65 5f 66 69 6e 61 6c 69 <b>sqlite_finali
4050: 7a 65 3c 2f 62 3e 20 6f 6e 20 74 68 65 20 76 69 ze</b> on the vi
4060: 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 61 66 rtual machine af
4070: 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 ter it has finis
4080: 68 65 64 0a 77 69 74 68 20 69 74 2e 0a 54 68 65 hed.with it..The
4090: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 4th parameter m
40a0: 61 79 20 62 65 20 73 65 74 20 74 6f 20 4e 55 4c ay be set to NUL
40b0: 4c 20 69 66 20 61 6e 20 65 72 72 6f 72 20 69 73 L if an error is
40c0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 64 75 72 encountered dur
40d0: 69 6e 67 0a 63 6f 6d 70 69 6c 61 74 69 6f 6e 2e ing.compilation.
40e0: 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49 66 20 61 6e .</p>..<p>.If an
40f0: 79 20 65 72 72 6f 72 73 20 61 72 65 20 65 6e 63 y errors are enc
4100: 6f 75 6e 74 65 72 65 64 20 64 75 72 69 6e 67 20 ountered during
4110: 63 6f 6d 70 69 6c 61 74 69 6f 6e 2c 20 61 6e 20 compilation, an
4120: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 error message is
4130: 0a 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 .written into me
4140: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
4150: 6f 6d 20 3c 62 3e 6d 61 6c 6c 6f 63 3c 2f 62 3e om <b>malloc</b>
4160: 20 61 6e 64 20 74 68 65 20 35 74 68 20 70 61 72 and the 5th par
4170: 61 6d 65 74 65 72 0a 69 73 20 6d 61 64 65 20 74 ameter.is made t
4180: 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 20 o point to that
4190: 6d 65 6d 6f 72 79 2e 20 20 49 66 20 74 68 65 20 memory. If the
41a0: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 5th parameter is
41b0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 6e 6f 20 65 NULL, then.no e
41c0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 rror message is
41d0: 67 65 6e 65 72 61 74 65 64 2e 20 20 49 66 20 74 generated. If t
41e0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
41f0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 is not NULL, th
4200: 65 6e 0a 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 en.the calling f
4210: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 64 unction should d
4220: 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 6d 65 ispose of the me
4230: 6d 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 mory containing
4240: 74 68 65 20 65 72 72 6f 72 0a 6d 65 73 73 61 67 the error.messag
4250: 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 3c 62 3e e by calling <b>
4260: 73 71 6c 69 74 65 5f 66 72 65 65 6d 65 6d 3c 2f sqlite_freemem</
4270: 62 3e 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49 66 b>..</p>..<p>.If
4280: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
4290: 65 72 20 61 63 74 75 61 6c 6c 79 20 63 6f 6e 74 er actually cont
42a0: 61 69 6e 73 20 74 77 6f 20 6f 72 20 6d 6f 72 65 ains two or more
42b0: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 statements of S
42c0: 51 4c 2c 0a 6f 6e 6c 79 20 74 68 65 20 66 69 72 QL,.only the fir
42d0: 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 st statement is
42e0: 63 6f 6d 70 69 6c 65 64 2e 20 20 28 54 68 69 73 compiled. (This
42f0: 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 is different fr
4300: 6f 6d 20 74 68 65 0a 62 65 68 61 76 69 6f 72 20 om the.behavior
4310: 6f 66 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 of <b>sqlite_exe
4320: 63 3c 2f 62 3e 20 77 68 69 63 68 20 65 78 65 63 c</b> which exec
4330: 75 74 65 73 20 61 6c 6c 20 53 51 4c 20 73 74 61 utes all SQL sta
4340: 74 65 6d 65 6e 74 73 0a 69 6e 20 69 74 73 20 69 tements.in its i
4350: 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 20 20 54 nput string.) T
4360: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
4370: 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 63 6f to <b>sqlite_co
4380: 6d 70 69 6c 65 3c 2f 62 3e 0a 69 73 20 6d 61 64 mpile</b>.is mad
4390: 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 e to point to th
43a0: 65 20 66 69 72 73 74 20 63 68 61 72 61 63 74 65 e first characte
43b0: 72 20 62 65 79 6f 6e 64 20 74 68 65 20 65 6e 64 r beyond the end
43c0: 20 6f 66 20 74 68 65 20 66 69 72 73 74 0a 73 74 of the first.st
43d0: 61 74 65 6d 65 6e 74 20 6f 66 20 53 51 4c 20 69 atement of SQL i
43e0: 6e 20 74 68 65 20 69 6e 70 75 74 2e 20 20 49 66 n the input. If
43f0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
4400: 65 72 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 er contains only
4410: 0a 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 .a single SQL st
4420: 61 74 65 6d 65 6e 74 2c 20 74 68 65 6e 20 74 68 atement, then th
4430: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
4440: 77 69 6c 6c 20 62 65 20 6d 61 64 65 20 74 6f 20 will be made to
4450: 70 6f 69 6e 74 0a 74 6f 20 74 68 65 20 27 5c 30 point.to the '\0
4460: 30 30 27 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 00' terminator a
4470: 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 t the end of the
4480: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2nd parameter..
4490: 3c 2f 70 3e 0a 0a 3c 70 3e 0a 4f 6e 20 73 75 63 </p>..<p>.On suc
44a0: 63 65 73 73 2c 20 3c 62 3e 73 71 6c 69 74 65 5f cess, <b>sqlite_
44b0: 63 6f 6d 70 69 6c 65 3c 2f 62 3e 20 72 65 74 75 compile</b> retu
44c0: 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 4f rns SQLITE_OK..O
44d0: 74 68 65 72 77 69 73 65 20 61 6e 64 20 65 72 72 therwise and err
44e0: 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 or code is retur
44f0: 6e 65 64 2e 0a 3c 2f 70 3e 0a 0a 3c 68 34 3e 32 ned..</p>..<h4>2
4500: 2e 32 20 53 74 65 70 2d 42 79 2d 53 74 65 70 20 .2 Step-By-Step
4510: 45 78 65 63 75 74 69 6f 6e 20 4f 66 20 41 6e 20 Execution Of An
4520: 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 3c 2f 68 SQL Statement</h
4530: 34 3e 0a 0a 3c 70 3e 0a 41 66 74 65 72 20 61 20 4>..<p>.After a
4540: 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
4550: 68 61 73 20 62 65 65 6e 20 67 65 6e 65 72 61 74 has been generat
4560: 65 64 20 75 73 69 6e 67 20 3c 62 3e 73 71 6c 69 ed using <b>sqli
4570: 74 65 5f 63 6f 6d 70 69 6c 65 3c 2f 62 3e 0a 69 te_compile</b>.i
4580: 74 20 69 73 20 65 78 65 63 75 74 65 64 20 62 79 t is executed by
4590: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c one or more cal
45a0: 6c 73 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f ls to <b>sqlite_
45b0: 73 74 65 70 3c 2f 62 3e 2e 20 20 45 61 63 68 0a step</b>. Each.
45c0: 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 3c 62 invocation of <b
45d0: 3e 73 71 6c 69 74 65 5f 73 74 65 70 3c 2f 62 3e >sqlite_step</b>
45e0: 2c 20 65 78 63 65 70 74 20 74 68 65 20 6c 61 73 , except the las
45f0: 74 20 6f 6e 65 2c 0a 72 65 74 75 72 6e 73 20 61 t one,.returns a
4600: 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 74 single row of t
4610: 68 65 20 72 65 73 75 6c 74 2e 0a 54 68 65 20 6e he result..The n
4620: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
4630: 20 69 6e 20 20 74 68 65 20 72 65 73 75 6c 74 20 in the result
4640: 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 is stored in the
4650: 20 69 6e 74 65 67 65 72 20 74 68 61 74 0a 74 68 integer that.th
4660: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
4670: 70 6f 69 6e 74 73 20 74 6f 2e 0a 54 68 65 20 70 points to..The p
4680: 6f 69 6e 74 65 72 20 73 70 65 63 69 66 69 65 64 ointer specified
4690: 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61 by the 3rd para
46a0: 6d 65 74 65 72 20 69 73 20 6d 61 64 65 20 74 6f meter is made to
46b0: 20 70 6f 69 6e 74 0a 74 6f 20 61 6e 20 61 72 72 point.to an arr
46c0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 ay of pointers t
46d0: 6f 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 2e o column values.
46e0: 0a 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 .The pointer in
46f0: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
4700: 72 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 r is made to poi
4710: 6e 74 20 74 6f 20 61 6e 20 61 72 72 61 79 0a 6f nt to an array.o
4720: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 63 6f f pointers to co
4730: 6c 75 6d 6e 20 6e 61 6d 65 73 20 61 6e 64 20 64 lumn names and d
4740: 61 74 61 74 79 70 65 73 2e 0a 54 68 65 20 32 6e atatypes..The 2n
4750: 64 20 74 68 72 6f 75 67 68 20 34 74 68 20 70 61 d through 4th pa
4760: 72 61 6d 65 74 65 72 73 20 74 6f 20 3c 62 3e 73 rameters to <b>s
4770: 71 6c 69 74 65 5f 73 74 65 70 3c 2f 62 3e 20 63 qlite_step</b> c
4780: 6f 6e 76 65 79 20 74 68 65 0a 73 61 6d 65 20 69 onvey the.same i
4790: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 nformation as th
47a0: 65 20 32 6e 64 20 74 68 72 6f 75 67 68 20 34 74 e 2nd through 4t
47b0: 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 h parameters of
47c0: 74 68 65 0a 3c 62 3e 63 61 6c 6c 62 61 63 6b 3c the.<b>callback<
47d0: 2f 62 3e 20 72 6f 75 74 69 6e 65 20 77 68 65 6e /b> routine when
47e0: 20 75 73 69 6e 67 0a 74 68 65 20 3c 62 3e 73 71 using.the <b>sq
47f0: 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e 20 69 6e lite_exec</b> in
4800: 74 65 72 66 61 63 65 2e 20 20 45 78 63 65 70 74 terface. Except
4810: 2c 20 77 69 74 68 20 3c 62 3e 73 71 6c 69 74 65 , with <b>sqlite
4820: 5f 73 74 65 70 3c 2f 62 3e 0a 74 68 65 20 63 6f _step</b>.the co
4830: 6c 75 6d 6e 20 64 61 74 61 74 79 70 65 20 69 6e lumn datatype in
4840: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 6c 77 formation is alw
4850: 61 79 73 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 ays included in
4860: 74 68 65 20 69 6e 20 74 68 65 0a 34 74 68 20 70 the in the.4th p
4870: 61 72 61 6d 65 74 65 72 20 72 65 67 61 72 64 6c arameter regardl
4880: 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
4890: 72 20 6e 6f 74 20 74 68 65 0a 3c 61 20 68 72 65 r not the.<a hre
48a0: 66 3d 22 6c 61 6e 67 2e 68 74 6d 6c 23 70 72 61 f="lang.html#pra
48b0: 67 6d 61 5f 73 68 6f 77 5f 64 61 74 61 74 79 70 gma_show_datatyp
48c0: 65 73 22 3e 53 48 4f 57 5f 44 41 54 41 54 59 50 es">SHOW_DATATYP
48d0: 45 53 3c 2f 61 3e 20 70 72 61 67 6d 61 0a 69 73 ES</a> pragma.is
48e0: 20 6f 6e 20 6f 72 20 6f 66 66 2e 0a 3c 2f 70 3e on or off..</p>
48f0: 0a 0a 3c 70 3e 0a 45 61 63 68 20 69 6e 76 6f 63 ..<p>.Each invoc
4900: 61 74 69 6f 6e 20 6f 66 20 3c 62 3e 73 71 6c 69 ation of <b>sqli
4910: 74 65 5f 73 74 65 70 3c 2f 62 3e 20 72 65 74 75 te_step</b> retu
4920: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 rns an integer c
4930: 6f 64 65 20 74 68 61 74 0a 69 6e 64 69 63 61 74 ode that.indicat
4940: 65 73 20 77 68 61 74 20 68 61 70 70 65 6e 65 64 es what happened
4950: 20 64 75 72 69 6e 67 20 74 68 61 74 20 73 74 65 during that ste
4960: 70 2e 20 20 54 68 69 73 20 63 6f 64 65 20 6d 61 p. This code ma
4970: 79 20 62 65 0a 53 51 4c 49 54 45 5f 42 55 53 59 y be.SQLITE_BUSY
4980: 2c 20 53 51 4c 49 54 45 5f 52 4f 57 2c 20 53 51 , SQLITE_ROW, SQ
4990: 4c 49 54 45 5f 44 4f 4e 45 2c 20 53 51 4c 49 54 LITE_DONE, SQLIT
49a0: 45 5f 45 52 52 4f 52 2c 20 6f 72 0a 53 51 4c 49 E_ERROR, or.SQLI
49b0: 54 45 5f 4d 49 53 55 53 45 2e 0a 3c 2f 70 3e 0a TE_MISUSE..</p>.
49c0: 0a 3c 70 3e 0a 49 66 20 74 68 65 20 76 69 72 74 .<p>.If the virt
49d0: 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 73 20 75 ual machine is u
49e0: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 nable to open th
49f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
4a00: 62 65 63 61 75 73 65 0a 69 74 20 69 73 20 6c 6f because.it is lo
4a10: 63 6b 65 64 20 62 79 20 61 6e 6f 74 68 65 72 20 cked by another
4a20: 74 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73 thread or proces
4a30: 73 2c 20 3c 62 3e 73 71 6c 69 74 65 5f 73 74 65 s, <b>sqlite_ste
4a40: 70 3c 2f 62 3e 0a 77 69 6c 6c 20 72 65 74 75 72 p</b>.will retur
4a50: 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 n SQLITE_BUSY.
4a60: 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 The calling func
4a70: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 64 6f 20 73 tion should do s
4a80: 6f 6d 65 20 6f 74 68 65 72 0a 61 63 74 69 76 69 ome other.activi
4a90: 74 79 2c 20 6f 72 20 73 6c 65 65 70 2c 20 66 6f ty, or sleep, fo
4aa0: 72 20 61 20 73 68 6f 72 74 20 61 6d 6f 75 6e 74 r a short amount
4ab0: 20 6f 66 20 74 69 6d 65 20 74 6f 20 67 69 76 65 of time to give
4ac0: 20 74 68 65 20 6c 6f 63 6b 20 61 0a 63 68 61 6e the lock a.chan
4ad0: 63 65 20 74 6f 20 63 6c 65 61 72 2c 20 74 68 65 ce to clear, the
4ae0: 6e 20 69 6e 76 6f 6b 65 20 3c 62 3e 73 71 6c 69 n invoke <b>sqli
4af0: 74 65 5f 73 74 65 70 3c 2f 62 3e 20 61 67 61 69 te_step</b> agai
4b00: 6e 2e 20 20 54 68 69 73 20 63 61 6e 0a 62 65 20 n. This can.be
4b10: 72 65 70 65 61 74 65 64 20 61 73 20 6d 61 6e 79 repeated as many
4b20: 20 74 69 6d 65 73 20 61 73 20 64 65 73 69 72 65 times as desire
4b30: 64 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 57 68 65 d..</p>..<p>.Whe
4b40: 6e 65 76 65 72 20 61 6e 6f 74 68 65 72 20 72 6f never another ro
4b50: 77 20 6f 66 20 72 65 73 75 6c 74 20 64 61 74 61 w of result data
4b60: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2c 0a 3c is available,.<
4b70: 62 3e 73 71 6c 69 74 65 5f 73 74 65 70 3c 2f 62 b>sqlite_step</b
4b80: 3e 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 > will return SQ
4b90: 4c 49 54 45 5f 52 4f 57 2e 20 20 54 68 65 20 72 LITE_ROW. The r
4ba0: 6f 77 20 64 61 74 61 20 69 73 0a 73 74 6f 72 65 ow data is.store
4bb0: 64 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6f 66 d in an array of
4bc0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
4bd0: 69 6e 67 73 20 61 6e 64 20 74 68 65 20 32 6e 64 ings and the 2nd
4be0: 20 70 61 72 61 6d 65 74 65 72 0a 69 73 20 6d 61 parameter.is ma
4bf0: 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 de to point to t
4c00: 68 69 73 20 61 72 72 61 79 2e 0a 3c 2f 70 3e 0a his array..</p>.
4c10: 0a 3c 70 3e 0a 57 68 65 6e 20 61 6c 6c 20 70 72 .<p>.When all pr
4c20: 6f 63 65 73 73 69 6e 67 20 69 73 20 63 6f 6d 70 ocessing is comp
4c30: 6c 65 74 65 2c 20 3c 62 3e 73 71 6c 69 74 65 5f lete, <b>sqlite_
4c40: 73 74 65 70 3c 2f 62 3e 20 77 69 6c 6c 20 72 65 step</b> will re
4c50: 74 75 72 6e 0a 65 69 74 68 65 72 20 53 51 4c 49 turn.either SQLI
4c60: 54 45 5f 44 4f 4e 45 20 6f 72 20 53 51 4c 49 54 TE_DONE or SQLIT
4c70: 45 5f 45 52 52 4f 52 2e 20 20 53 51 4c 49 54 45 E_ERROR. SQLITE
4c80: 5f 44 4f 4e 45 20 69 6e 64 69 63 61 74 65 73 20 _DONE indicates
4c90: 74 68 61 74 20 74 68 65 0a 73 74 61 74 65 6d 65 that the.stateme
4ca0: 6e 74 20 63 6f 6d 70 6c 65 74 65 64 20 73 75 63 nt completed suc
4cb0: 63 65 73 73 66 75 6c 6c 79 20 61 6e 64 20 53 51 cessfully and SQ
4cc0: 4c 49 54 45 5f 45 52 52 4f 52 20 69 6e 64 69 63 LITE_ERROR indic
4cd0: 61 74 65 73 20 74 68 61 74 20 74 68 65 72 65 0a ates that there.
4ce0: 77 61 73 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 was a run-time e
4cf0: 72 72 6f 72 2e 20 20 28 54 68 65 20 64 65 74 61 rror. (The deta
4d00: 69 6c 73 20 6f 66 20 74 68 65 20 65 72 72 6f 72 ils of the error
4d10: 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 66 72 are obtained fr
4d20: 6f 6d 0a 3c 62 3e 73 71 6c 69 74 65 5f 66 69 6e om.<b>sqlite_fin
4d30: 61 6c 69 7a 65 3c 2f 62 3e 2e 29 20 20 49 74 20 alize</b>.) It
4d40: 69 73 20 61 20 6d 69 73 75 73 65 20 6f 66 20 74 is a misuse of t
4d50: 68 65 20 6c 69 62 72 61 72 79 20 74 6f 20 61 74 he library to at
4d60: 74 65 6d 70 74 0a 74 6f 20 63 61 6c 6c 20 3c 62 tempt.to call <b
4d70: 3e 73 71 6c 69 74 65 5f 73 74 65 70 3c 2f 62 3e >sqlite_step</b>
4d80: 20 61 67 61 69 6e 20 61 66 74 65 72 20 69 74 20 again after it
4d90: 68 61 73 20 72 65 74 75 72 6e 65 64 20 53 51 4c has returned SQL
4da0: 49 54 45 5f 44 4f 4e 45 0a 6f 72 20 53 51 4c 49 ITE_DONE.or SQLI
4db0: 54 45 5f 45 52 52 4f 52 2e 0a 3c 2f 70 3e 0a 0a TE_ERROR..</p>..
4dc0: 3c 70 3e 0a 57 68 65 6e 20 3c 62 3e 73 71 6c 69 <p>.When <b>sqli
4dd0: 74 65 5f 73 74 65 70 3c 2f 62 3e 20 72 65 74 75 te_step</b> retu
4de0: 72 6e 73 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 rns SQLITE_DONE
4df0: 6f 72 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2c or SQLITE_ERROR,
4e00: 0a 74 68 65 20 2a 70 4e 20 61 6e 64 20 2a 70 61 .the *pN and *pa
4e10: 7a 43 6f 6c 4e 61 6d 65 20 76 61 6c 75 65 73 20 zColName values
4e20: 61 72 65 20 73 65 74 20 74 6f 20 74 68 65 20 6e are set to the n
4e30: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
4e40: 0a 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 .in the result s
4e50: 65 74 20 61 6e 64 20 74 6f 20 74 68 65 20 6e 61 et and to the na
4e60: 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d mes of the colum
4e70: 6e 73 2c 20 6a 75 73 74 20 61 73 20 74 68 65 79 ns, just as they
4e80: 0a 61 72 65 20 66 6f 72 20 61 6e 20 53 51 4c 49 .are for an SQLI
4e90: 54 45 5f 52 4f 57 20 72 65 74 75 72 6e 2e 20 20 TE_ROW return.
4ea0: 54 68 69 73 20 61 6c 6c 6f 77 73 20 74 68 65 20 This allows the
4eb0: 63 61 6c 6c 69 6e 67 20 63 6f 64 65 20 74 6f 0a calling code to.
4ec0: 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 find the number
4ed0: 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e of result column
4ee0: 73 20 61 6e 64 20 74 68 65 20 63 6f 6c 75 6d 6e s and the column
4ef0: 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 names and datat
4f00: 79 70 65 73 0a 65 76 65 6e 20 69 66 20 74 68 65 ypes.even if the
4f10: 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 65 result set is e
4f20: 6d 70 74 79 2e 20 20 54 68 65 20 2a 70 61 7a 56 mpty. The *pazV
4f30: 61 6c 75 65 20 70 61 72 61 6d 65 74 65 72 20 69 alue parameter i
4f40: 73 20 61 6c 77 61 79 73 0a 73 65 74 20 74 6f 20 s always.set to
4f50: 4e 55 4c 4c 20 77 68 65 6e 20 74 68 65 20 72 65 NULL when the re
4f60: 74 75 72 6e 20 63 6f 64 65 73 20 69 73 20 53 51 turn codes is SQ
4f70: 4c 49 54 45 5f 44 4f 4e 45 20 6f 72 20 53 51 4c LITE_DONE or SQL
4f80: 49 54 45 5f 45 52 52 4f 52 2e 0a 49 66 20 74 68 ITE_ERROR..If th
4f90: 65 20 53 51 4c 20 62 65 69 6e 67 20 65 78 65 63 e SQL being exec
4fa0: 75 74 65 64 20 69 73 20 61 20 73 74 61 74 65 6d uted is a statem
4fb0: 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f ent that does no
4fc0: 74 0a 72 65 74 75 72 6e 20 61 20 72 65 73 75 6c t.return a resul
4fd0: 74 20 28 73 75 63 68 20 61 73 20 61 6e 20 49 4e t (such as an IN
4fe0: 53 45 52 54 20 6f 72 20 61 6e 20 55 50 44 41 54 SERT or an UPDAT
4ff0: 45 29 20 74 68 65 6e 20 2a 70 4e 20 77 69 6c 6c E) then *pN will
5000: 0a 62 65 20 73 65 74 20 74 6f 20 7a 65 72 6f 20 .be set to zero
5010: 61 6e 64 20 2a 70 61 7a 43 6f 6c 4e 61 6d 65 20 and *pazColName
5020: 77 69 6c 6c 20 62 65 20 73 65 74 20 74 6f 20 4e will be set to N
5030: 55 4c 4c 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49 ULL..</p>..<p>.I
5040: 66 20 79 6f 75 20 61 62 75 73 65 20 74 68 65 20 f you abuse the
5050: 6c 69 62 72 61 72 79 20 62 79 20 74 72 79 69 6e library by tryin
5060: 67 20 74 6f 20 63 61 6c 6c 20 3c 62 3e 73 71 6c g to call <b>sql
5070: 69 74 65 5f 73 74 65 70 3c 2f 62 3e 0a 69 6e 61 ite_step</b>.ina
5080: 70 70 72 6f 70 72 69 61 74 65 6c 79 20 69 74 20 ppropriately it
5090: 77 69 6c 6c 20 61 74 74 65 6d 70 74 20 72 65 74 will attempt ret
50a0: 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 urn SQLITE_MISUS
50b0: 45 2e 0a 54 68 69 73 20 63 61 6e 20 68 61 70 70 E..This can happ
50c0: 65 6e 20 69 66 20 79 6f 75 20 63 61 6c 6c 20 73 en if you call s
50d0: 71 6c 69 74 65 5f 73 74 65 70 28 29 20 6f 6e 20 qlite_step() on
50e0: 74 68 65 20 73 61 6d 65 20 76 69 72 74 75 61 6c the same virtual
50f0: 20 6d 61 63 68 69 6e 65 0a 61 74 20 74 68 65 20 machine.at the
5100: 73 61 6d 65 0a 74 69 6d 65 20 66 72 6f 6d 20 74 same.time from t
5110: 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 wo or more threa
5120: 64 73 20 6f 72 20 69 66 20 79 6f 75 20 63 61 6c ds or if you cal
5130: 6c 20 73 71 6c 69 74 65 5f 73 74 65 70 28 29 0a l sqlite_step().
5140: 61 67 61 69 6e 20 61 66 74 65 72 20 69 74 20 72 again after it r
5150: 65 74 75 72 6e 65 64 20 53 51 4c 49 54 45 5f 44 eturned SQLITE_D
5160: 4f 4e 45 20 6f 72 20 53 51 4c 49 54 45 5f 45 52 ONE or SQLITE_ER
5170: 52 4f 52 20 6f 72 20 69 66 20 79 6f 75 0a 70 61 ROR or if you.pa
5180: 73 73 20 69 6e 20 61 6e 20 69 6e 76 61 6c 69 64 ss in an invalid
5190: 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 virtual machine
51a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 pointer to sqli
51b0: 74 65 5f 73 74 65 70 28 29 2e 0a 59 6f 75 20 73 te_step()..You s
51c0: 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 hould not depend
51d0: 20 6f 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 4d on the SQLITE_M
51e0: 49 53 55 53 45 20 72 65 74 75 72 6e 20 63 6f 64 ISUSE return cod
51f0: 65 20 74 6f 20 69 6e 64 69 63 61 74 65 0a 61 6e e to indicate.an
5200: 20 65 72 72 6f 72 2e 20 20 49 74 20 69 73 20 70 error. It is p
5210: 6f 73 73 69 62 6c 65 20 74 68 61 74 20 61 20 6d ossible that a m
5220: 69 73 75 73 65 20 6f 66 20 74 68 65 20 69 6e 74 isuse of the int
5230: 65 72 66 61 63 65 20 77 69 6c 6c 20 67 6f 0a 75 erface will go.u
5240: 6e 64 65 74 65 63 74 65 64 20 61 6e 64 20 72 65 ndetected and re
5250: 73 75 6c 74 20 69 6e 20 61 20 70 72 6f 67 72 61 sult in a progra
5260: 6d 20 63 72 61 73 68 2e 20 20 54 68 65 20 53 51 m crash. The SQ
5270: 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 0a 69 LITE_MISUSE is.i
5280: 6e 74 65 6e 64 65 64 20 61 73 20 61 20 64 65 62 ntended as a deb
5290: 75 67 67 69 6e 67 20 61 69 64 20 6f 6e 6c 79 20 ugging aid only
52a0: 2d 20 74 6f 20 68 65 6c 70 20 79 6f 75 20 64 65 - to help you de
52b0: 74 65 63 74 20 69 6e 63 6f 72 72 65 63 74 0a 75 tect incorrect.u
52c0: 73 61 67 65 20 70 72 69 6f 72 20 74 6f 20 61 20 sage prior to a
52d0: 6d 69 73 68 61 70 2e 20 20 54 68 65 20 6d 69 73 mishap. The mis
52e0: 75 73 65 20 64 65 74 65 63 74 69 6f 6e 20 6c 6f use detection lo
52f0: 67 69 63 20 69 73 20 6e 6f 74 20 67 75 61 72 61 gic is not guara
5300: 6e 74 65 65 64 0a 74 6f 20 77 6f 72 6b 20 69 6e nteed.to work in
5310: 20 65 76 65 72 79 20 63 61 73 65 2e 0a 3c 2f 70 every case..</p
5320: 3e 0a 0a 3c 68 34 3e 32 2e 33 20 44 65 6c 65 74 >..<h4>2.3 Delet
5330: 69 6e 67 20 41 20 56 69 72 74 75 61 6c 20 4d 61 ing A Virtual Ma
5340: 63 68 69 6e 65 3c 2f 68 34 3e 0a 0a 3c 70 3e 0a chine</h4>..<p>.
5350: 45 76 65 72 79 20 76 69 72 74 75 61 6c 20 6d 61 Every virtual ma
5360: 63 68 69 6e 65 20 74 68 61 74 20 3c 62 3e 73 71 chine that <b>sq
5370: 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 3c 2f 62 3e lite_compile</b>
5380: 20 63 72 65 61 74 65 73 20 73 68 6f 75 6c 64 0a creates should.
5390: 65 76 65 6e 74 75 61 6c 6c 79 20 62 65 20 68 61 eventually be ha
53a0: 6e 64 65 64 20 74 6f 20 3c 62 3e 73 71 6c 69 74 nded to <b>sqlit
53b0: 65 5f 66 69 6e 61 6c 69 7a 65 3c 2f 62 3e 2e 20 e_finalize</b>.
53c0: 20 54 68 65 20 73 71 6c 69 74 65 5f 66 69 6e 61 The sqlite_fina
53d0: 6c 69 7a 65 28 29 0a 70 72 6f 63 65 64 75 72 65 lize().procedure
53e0: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 74 68 65 deallocates the
53f0: 20 6d 65 6d 6f 72 79 20 61 6e 64 20 6f 74 68 65 memory and othe
5400: 72 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 r resources that
5410: 20 74 68 65 20 76 69 72 74 75 61 6c 0a 6d 61 63 the virtual.mac
5420: 68 69 6e 65 20 75 73 65 73 2e 20 20 46 61 69 6c hine uses. Fail
5430: 75 72 65 20 74 6f 20 63 61 6c 6c 20 73 71 6c 69 ure to call sqli
5440: 74 65 5f 66 69 6e 61 6c 69 7a 65 28 29 20 77 69 te_finalize() wi
5450: 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 0a 72 65 ll result in .re
5460: 73 6f 75 72 63 65 20 6c 65 61 6b 73 20 69 6e 20 source leaks in
5470: 79 6f 75 72 20 70 72 6f 67 72 61 6d 2e 0a 3c 2f your program..</
5480: 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 3c 62 3e 73 p>..<p>.The <b>s
5490: 71 6c 69 74 65 5f 66 69 6e 61 6c 69 7a 65 3c 2f qlite_finalize</
54a0: 62 3e 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 b> routine also
54b0: 72 65 74 75 72 6e 73 20 74 68 65 20 72 65 73 75 returns the resu
54c0: 6c 74 20 63 6f 64 65 0a 74 68 61 74 20 69 6e 64 lt code.that ind
54d0: 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f icates success o
54e0: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 r failure of the
54f0: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 SQL operation t
5500: 68 61 74 20 74 68 65 0a 76 69 72 74 75 61 6c 20 hat the.virtual
5510: 6d 61 63 68 69 6e 65 20 63 61 72 72 69 65 64 20 machine carried
5520: 6f 75 74 2e 0a 54 68 65 20 76 61 6c 75 65 20 72 out..The value r
5530: 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
5540: 65 5f 66 69 6e 61 6c 69 7a 65 28 29 20 77 69 6c e_finalize() wil
5550: 6c 20 62 65 20 74 68 65 20 73 61 6d 65 20 61 73 l be the same as
5560: 20 77 6f 75 6c 64 0a 68 61 76 65 20 62 65 65 6e would.have been
5570: 20 72 65 74 75 72 6e 65 64 20 68 61 64 20 74 68 returned had th
5580: 65 20 73 61 6d 65 20 53 51 4c 20 62 65 65 6e 20 e same SQL been
5590: 65 78 65 63 75 74 65 64 20 62 79 20 3c 62 3e 73 executed by <b>s
55a0: 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e 2e 0a qlite_exec</b>..
55b0: 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 The error messag
55c0: 65 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 e returned will
55d0: 61 6c 73 6f 20 62 65 20 74 68 65 20 73 61 6d 65 also be the same
55e0: 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49 74 20 69 ..</p>..<p>.It i
55f0: 73 20 61 63 63 65 70 74 61 62 6c 65 20 74 6f 20 s acceptable to
5600: 63 61 6c 6c 20 3c 62 3e 73 71 6c 69 74 65 5f 66 call <b>sqlite_f
5610: 69 6e 61 6c 69 7a 65 3c 2f 62 3e 20 6f 6e 20 61 inalize</b> on a
5620: 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 virtual machine
5630: 0a 62 65 66 6f 72 65 20 3c 62 3e 73 71 6c 69 74 .before <b>sqlit
5640: 65 5f 73 74 65 70 3c 2f 62 3e 20 68 61 73 20 72 e_step</b> has r
5650: 65 74 75 72 6e 65 64 20 53 51 4c 49 54 45 5f 44 eturned SQLITE_D
5660: 4f 4e 45 2e 20 20 44 6f 69 6e 67 20 73 6f 20 68 ONE. Doing so h
5670: 61 73 0a 74 68 65 20 65 66 66 65 63 74 20 6f 66 as.the effect of
5680: 20 69 6e 74 65 72 72 75 70 74 69 6e 67 20 74 68 interrupting th
5690: 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 6e 20 70 e operation in p
56a0: 72 6f 67 72 65 73 73 2e 20 20 50 61 72 74 69 61 rogress. Partia
56b0: 6c 6c 79 20 63 6f 6d 70 6c 65 74 65 64 0a 63 68 lly completed.ch
56c0: 61 6e 67 65 73 20 77 69 6c 6c 20 62 65 20 72 6f anges will be ro
56d0: 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 68 lled back and th
56e0: 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 e database will
56f0: 62 65 20 72 65 73 74 6f 72 65 64 20 74 6f 20 69 be restored to i
5700: 74 73 0a 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 ts.original stat
5710: 65 20 28 75 6e 6c 65 73 73 20 61 6e 20 61 6c 74 e (unless an alt
5720: 65 72 6e 61 74 69 76 65 20 72 65 63 6f 76 65 72 ernative recover
5730: 79 20 61 6c 67 6f 72 69 74 68 6d 20 69 73 20 73 y algorithm is s
5740: 65 6c 65 63 74 65 64 20 75 73 69 6e 67 0a 61 6e elected using.an
5750: 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 63 6c 61 ON CONFLICT cla
5760: 75 73 65 20 69 6e 20 74 68 65 20 53 51 4c 20 62 use in the SQL b
5770: 65 69 6e 67 20 65 78 65 63 75 74 65 64 2e 29 20 eing executed.)
5780: 20 54 68 65 20 65 66 66 65 63 74 20 69 73 20 74 The effect is t
5790: 68 65 0a 73 61 6d 65 20 61 73 20 69 66 20 61 20 he.same as if a
57a0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
57b0: 6e 20 6f 66 20 3c 62 3e 73 71 6c 69 74 65 5f 65 n of <b>sqlite_e
57c0: 78 65 63 3c 2f 62 3e 20 68 61 64 20 72 65 74 75 xec</b> had retu
57d0: 72 6e 65 64 0a 6e 6f 6e 2d 7a 65 72 6f 2e 0a 3c rned.non-zero..<
57e0: 2f 70 3e 0a 0a 3c 70 3e 0a 49 74 20 69 73 20 61 /p>..<p>.It is a
57f0: 6c 73 6f 20 61 63 63 65 70 74 61 62 6c 65 20 74 lso acceptable t
5800: 6f 20 63 61 6c 6c 20 3c 62 3e 73 71 6c 69 74 65 o call <b>sqlite
5810: 5f 66 69 6e 61 6c 69 7a 65 3c 2f 62 3e 20 6f 6e _finalize</b> on
5820: 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 a virtual machi
5830: 6e 65 0a 74 68 61 74 20 68 61 73 20 6e 65 76 65 ne.that has neve
5840: 72 20 62 65 65 6e 20 70 61 73 73 65 64 20 74 6f r been passed to
5850: 20 3c 62 3e 73 71 6c 69 74 65 5f 73 74 65 70 3c <b>sqlite_step<
5860: 2f 62 3e 20 65 76 65 6e 20 6f 6e 63 65 2e 0a 3c /b> even once..<
5870: 2f 70 3e 0a 0a 3c 68 33 3e 33 2e 30 20 54 68 65 /p>..<h3>3.0 The
5880: 20 45 78 74 65 6e 64 65 64 20 41 50 49 3c 2f 68 Extended API</h
5890: 33 3e 0a 0a 3c 70 3e 4f 6e 6c 79 20 74 68 65 20 3>..<p>Only the
58a0: 74 68 72 65 65 20 63 6f 72 65 20 72 6f 75 74 69 three core routi
58b0: 6e 65 73 20 64 65 73 63 72 69 62 65 64 20 69 6e nes described in
58c0: 20 73 65 63 74 69 6f 6e 20 31 2e 30 20 61 72 65 section 1.0 are
58d0: 20 72 65 71 75 69 72 65 64 20 74 6f 20 75 73 65 required to use
58e0: 0a 53 51 4c 69 74 65 2e 20 20 42 75 74 20 74 68 .SQLite. But th
58f0: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 ere are many oth
5900: 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 er functions tha
5910: 74 20 70 72 6f 76 69 64 65 20 0a 75 73 65 66 75 t provide .usefu
5920: 6c 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 54 l interfaces. T
5930: 68 65 73 65 20 65 78 74 65 6e 64 65 64 20 72 6f hese extended ro
5940: 75 74 69 6e 65 73 20 61 72 65 20 61 73 20 66 6f utines are as fo
5950: 6c 6c 6f 77 73 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c llows:.</p>..<bl
5960: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 69 ockquote><pre>.i
5970: 6e 74 20 73 71 6c 69 74 65 5f 6c 61 73 74 5f 69 nt sqlite_last_i
5980: 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 nsert_rowid(sqli
5990: 74 65 2a 29 3b 0a 0a 69 6e 74 20 73 71 6c 69 74 te*);..int sqlit
59a0: 65 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 e_changes(sqlite
59b0: 2a 29 3b 0a 0a 69 6e 74 20 73 71 6c 69 74 65 5f *);..int sqlite_
59c0: 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c get_table(. sql
59d0: 69 74 65 2a 2c 0a 20 20 63 68 61 72 20 2a 73 71 ite*,. char *sq
59e0: 6c 2c 0a 20 20 63 68 61 72 20 2a 2a 2a 72 65 73 l,. char ***res
59f0: 75 6c 74 2c 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 ult,. int *nrow
5a00: 2c 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e ,. int *ncolumn
5a10: 2c 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 ,. char **errms
5a20: 67 0a 29 3b 0a 0a 76 6f 69 64 20 73 71 6c 69 74 g.);..void sqlit
5a30: 65 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 e_free_table(cha
5a40: 72 2a 2a 29 3b 0a 0a 76 6f 69 64 20 73 71 6c 69 r**);..void sqli
5a50: 74 65 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c te_interrupt(sql
5a60: 69 74 65 2a 29 3b 0a 0a 69 6e 74 20 73 71 6c 69 ite*);..int sqli
5a70: 74 65 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 te_complete(cons
5a80: 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 0a 76 t char *sql);..v
5a90: 6f 69 64 20 73 71 6c 69 74 65 5f 62 75 73 79 5f oid sqlite_busy_
5aa0: 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 2a 2c handler(sqlite*,
5ab0: 20 69 6e 74 20 28 2a 29 28 76 6f 69 64 2a 2c 63 int (*)(void*,c
5ac0: 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 29 2c onst char*,int),
5ad0: 20 76 6f 69 64 2a 29 3b 0a 0a 76 6f 69 64 20 73 void*);..void s
5ae0: 71 6c 69 74 65 5f 62 75 73 79 5f 74 69 6d 65 6f qlite_busy_timeo
5af0: 75 74 28 73 71 6c 69 74 65 2a 2c 20 69 6e 74 20 ut(sqlite*, int
5b00: 6d 73 29 3b 0a 0a 63 6f 6e 73 74 20 63 68 61 72 ms);..const char
5b10: 20 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 5b sqlite_version[
5b20: 5d 3b 0a 0a 63 6f 6e 73 74 20 63 68 61 72 20 73 ];..const char s
5b30: 71 6c 69 74 65 5f 65 6e 63 6f 64 69 6e 67 5b 5d qlite_encoding[]
5b40: 3b 0a 0a 69 6e 74 20 73 71 6c 69 74 65 5f 65 78 ;..int sqlite_ex
5b50: 65 63 5f 70 72 69 6e 74 66 28 0a 20 20 73 71 6c ec_printf(. sql
5b60: 69 74 65 2a 2c 0a 20 20 63 68 61 72 20 2a 73 71 ite*,. char *sq
5b70: 6c 2c 0a 20 20 69 6e 74 20 28 2a 29 28 76 6f 69 l,. int (*)(voi
5b80: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 d*,int,char**,ch
5b90: 61 72 2a 2a 29 2c 0a 20 20 76 6f 69 64 2a 2c 0a ar**),. void*,.
5ba0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 2c char **errmsg,
5bb0: 0a 20 20 2e 2e 2e 0a 29 3b 0a 0a 69 6e 74 20 73 . ....);..int s
5bc0: 71 6c 69 74 65 5f 65 78 65 63 5f 76 70 72 69 6e qlite_exec_vprin
5bd0: 74 66 28 0a 20 20 73 71 6c 69 74 65 2a 2c 0a 20 tf(. sqlite*,.
5be0: 20 63 68 61 72 20 2a 73 71 6c 2c 0a 20 20 69 6e char *sql,. in
5bf0: 74 20 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c t (*)(void*,int,
5c00: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 0a char**,char**),.
5c10: 20 20 76 6f 69 64 2a 2c 0a 20 20 63 68 61 72 20 void*,. char
5c20: 2a 2a 65 72 72 6d 73 67 2c 0a 20 20 76 61 5f 6c **errmsg,. va_l
5c30: 69 73 74 0a 29 3b 0a 0a 69 6e 74 20 73 71 6c 69 ist.);..int sqli
5c40: 74 65 5f 67 65 74 5f 74 61 62 6c 65 5f 70 72 69 te_get_table_pri
5c50: 6e 74 66 28 0a 20 20 73 71 6c 69 74 65 2a 2c 0a ntf(. sqlite*,.
5c60: 20 20 63 68 61 72 20 2a 73 71 6c 2c 0a 20 20 63 char *sql,. c
5c70: 68 61 72 20 2a 2a 2a 72 65 73 75 6c 74 2c 0a 20 har ***result,.
5c80: 20 69 6e 74 20 2a 6e 72 6f 77 2c 0a 20 20 69 6e int *nrow,. in
5c90: 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 0a 20 20 63 68 t *ncolumn,. ch
5ca0: 61 72 20 2a 2a 65 72 72 6d 73 67 2c 0a 20 20 2e ar **errmsg,. .
5cb0: 2e 2e 0a 29 3b 0a 0a 69 6e 74 20 73 71 6c 69 74 ...);..int sqlit
5cc0: 65 5f 67 65 74 5f 74 61 62 6c 65 5f 76 70 72 69 e_get_table_vpri
5cd0: 6e 74 66 28 0a 20 20 73 71 6c 69 74 65 2a 2c 0a ntf(. sqlite*,.
5ce0: 20 20 63 68 61 72 20 2a 73 71 6c 2c 0a 20 20 63 char *sql,. c
5cf0: 68 61 72 20 2a 2a 2a 72 65 73 75 6c 74 2c 0a 20 har ***result,.
5d00: 20 69 6e 74 20 2a 6e 72 6f 77 2c 0a 20 20 69 6e int *nrow,. in
5d10: 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 0a 20 20 63 68 t *ncolumn,. ch
5d20: 61 72 20 2a 2a 65 72 72 6d 73 67 2c 0a 20 20 76 ar **errmsg,. v
5d30: 61 5f 6c 69 73 74 0a 29 3b 0a 0a 63 68 61 72 20 a_list.);..char
5d40: 2a 73 71 6c 69 74 65 5f 6d 70 72 69 6e 74 66 28 *sqlite_mprintf(
5d50: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 6f 72 const char *zFor
5d60: 6d 61 74 2c 20 2e 2e 2e 29 3b 0a 0a 63 68 61 72 mat, ...);..char
5d70: 20 2a 73 71 6c 69 74 65 5f 76 6d 70 72 69 6e 74 *sqlite_vmprint
5d80: 66 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 f(const char *zF
5d90: 6f 72 6d 61 74 2c 20 76 61 5f 6c 69 73 74 29 3b ormat, va_list);
5da0: 0a 0a 76 6f 69 64 20 73 71 6c 69 74 65 5f 66 72 ..void sqlite_fr
5db0: 65 65 6d 65 6d 28 63 68 61 72 2a 29 3b 0a 0a 76 eemem(char*);..v
5dc0: 6f 69 64 20 73 71 6c 69 74 65 5f 70 72 6f 67 72 oid sqlite_progr
5dd0: 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 ess_handler(sqli
5de0: 74 65 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 28 2a te*, int, int (*
5df0: 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 )(void*), void*)
5e00: 3b 0a 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ;..</pre></block
5e10: 71 75 6f 74 65 3e 0a 0a 3c 70 3e 41 6c 6c 20 6f quote>..<p>All o
5e20: 66 20 74 68 65 20 61 62 6f 76 65 20 64 65 66 69 f the above defi
5e30: 6e 69 74 69 6f 6e 73 20 61 72 65 20 69 6e 63 6c nitions are incl
5e40: 75 64 65 64 20 69 6e 20 74 68 65 20 22 73 71 6c uded in the "sql
5e50: 69 74 65 2e 68 22 0a 68 65 61 64 65 72 20 66 69 ite.h".header fi
5e60: 6c 65 20 74 68 61 74 20 63 6f 6d 65 73 20 69 6e le that comes in
5e70: 20 74 68 65 20 73 6f 75 72 63 65 20 74 72 65 65 the source tree
5e80: 2e 3c 2f 70 3e 0a 0a 3c 68 34 3e 33 2e 31 20 54 .</p>..<h4>3.1 T
5e90: 68 65 20 52 4f 57 49 44 20 6f 66 20 74 68 65 20 he ROWID of the
5ea0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 69 6e 73 65 most recent inse
5eb0: 72 74 3c 2f 68 34 3e 0a 0a 3c 70 3e 45 76 65 72 rt</h4>..<p>Ever
5ec0: 79 20 72 6f 77 20 6f 66 20 61 6e 20 53 51 4c 69 y row of an SQLi
5ed0: 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 te table has a u
5ee0: 6e 69 71 75 65 20 69 6e 74 65 67 65 72 20 6b 65 nique integer ke
5ef0: 79 2e 20 20 49 66 20 74 68 65 0a 74 61 62 6c 65 y. If the.table
5f00: 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6c 61 has a column la
5f10: 62 65 6c 65 64 20 49 4e 54 45 47 45 52 20 50 52 beled INTEGER PR
5f20: 49 4d 41 52 59 20 4b 45 59 2c 20 74 68 65 6e 20 IMARY KEY, then
5f30: 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 73 65 72 76 that column.serv
5f40: 65 73 20 61 73 20 74 68 65 20 6b 65 79 2e 20 20 es as the key.
5f50: 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 49 If there is no I
5f60: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b NTEGER PRIMARY K
5f70: 45 59 20 63 6f 6c 75 6d 6e 20 74 68 65 6e 0a 74 EY column then.t
5f80: 68 65 20 6b 65 79 20 69 73 20 61 20 75 6e 69 71 he key is a uniq
5f90: 75 65 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 ue integer. The
5fa0: 20 6b 65 79 20 66 6f 72 20 61 20 72 6f 77 20 63 key for a row c
5fb0: 61 6e 20 62 65 20 61 63 63 65 73 73 65 64 20 69 an be accessed i
5fc0: 6e 0a 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 n.a SELECT state
5fd0: 6d 65 6e 74 20 6f 72 20 75 73 65 64 20 69 6e 20 ment or used in
5fe0: 61 20 57 48 45 52 45 20 6f 72 20 4f 52 44 45 52 a WHERE or ORDER
5ff0: 20 42 59 20 63 6c 61 75 73 65 20 75 73 69 6e 67 BY clause using
6000: 20 61 6e 79 0a 6f 66 20 74 68 65 20 6e 61 6d 65 any.of the name
6010: 73 20 22 52 4f 57 49 44 22 2c 20 22 4f 49 44 22 s "ROWID", "OID"
6020: 2c 20 6f 72 20 22 5f 52 4f 57 49 44 5f 22 2e 3c , or "_ROWID_".<
6030: 2f 70 3e 0a 0a 3c 70 3e 57 68 65 6e 20 79 6f 75 /p>..<p>When you
6040: 20 64 6f 20 61 6e 20 69 6e 73 65 72 74 20 69 6e do an insert in
6050: 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 20 to a table that
6060: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 6e does not have an
6070: 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 INTEGER PRIMARY
6080: 0a 4b 45 59 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 .KEY column, or
6090: 69 66 20 74 68 65 20 74 61 62 6c 65 20 64 6f 65 if the table doe
60a0: 73 20 68 61 76 65 20 61 6e 20 49 4e 54 45 47 45 s have an INTEGE
60b0: 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 62 75 R PRIMARY KEY bu
60c0: 74 20 74 68 65 20 76 61 6c 75 65 0a 66 6f 72 20 t the value.for
60d0: 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e that column is n
60e0: 6f 74 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 ot specified in
60f0: 74 68 65 20 56 41 4c 55 45 53 20 63 6c 61 75 73 the VALUES claus
6100: 65 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 2c e of the insert,
6110: 20 74 68 65 6e 0a 74 68 65 20 6b 65 79 20 69 73 then.the key is
6120: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 67 automatically g
6130: 65 6e 65 72 61 74 65 64 2e 20 20 59 6f 75 20 63 enerated. You c
6140: 61 6e 20 66 69 6e 64 20 74 68 65 20 76 61 6c 75 an find the valu
6150: 65 20 6f 66 20 74 68 65 20 6b 65 79 0a 66 6f 72 e of the key.for
6160: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
6170: 20 49 4e 53 45 52 54 20 73 74 61 74 65 6d 65 6e INSERT statemen
6180: 74 20 75 73 69 6e 67 20 74 68 65 0a 3c 62 3e 73 t using the.<b>s
6190: 71 6c 69 74 65 5f 6c 61 73 74 5f 69 6e 73 65 72 qlite_last_inser
61a0: 74 5f 72 6f 77 69 64 3c 2f 62 3e 20 41 50 49 20 t_rowid</b> API
61b0: 66 75 6e 63 74 69 6f 6e 2e 3c 2f 70 3e 0a 0a 3c function.</p>..<
61c0: 68 34 3e 33 2e 32 20 54 68 65 20 6e 75 6d 62 65 h4>3.2 The numbe
61d0: 72 20 6f 66 20 72 6f 77 73 20 74 68 61 74 20 63 r of rows that c
61e0: 68 61 6e 67 65 64 3c 2f 68 34 3e 0a 0a 3c 70 3e hanged</h4>..<p>
61f0: 54 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 63 68 The <b>sqlite_ch
6200: 61 6e 67 65 73 3c 2f 62 3e 20 41 50 49 20 66 75 anges</b> API fu
6210: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 nction returns t
6220: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 he number of row
6230: 73 0a 74 68 61 74 20 68 61 76 65 20 62 65 65 6e s.that have been
6240: 20 69 6e 73 65 72 74 65 64 2c 20 64 65 6c 65 74 inserted, delet
6250: 65 64 2c 20 6f 72 20 6d 6f 64 69 66 69 65 64 20 ed, or modified
6260: 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 since the databa
6270: 73 65 20 77 61 73 0a 6c 61 73 74 20 71 75 69 65 se was.last quie
6280: 73 63 65 6e 74 2e 20 20 41 20 22 71 75 69 65 73 scent. A "quies
6290: 63 65 6e 74 22 20 64 61 74 61 62 61 73 65 20 69 cent" database i
62a0: 73 20 6f 6e 65 20 69 6e 20 77 68 69 63 68 20 74 s one in which t
62b0: 68 65 72 65 20 61 72 65 0a 6e 6f 20 6f 75 74 73 here are.no outs
62c0: 74 61 6e 64 69 6e 67 20 63 61 6c 6c 73 20 74 6f tanding calls to
62d0: 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c <b>sqlite_exec<
62e0: 2f 62 3e 20 61 6e 64 20 6e 6f 20 56 4d 73 20 63 /b> and no VMs c
62f0: 72 65 61 74 65 64 20 62 79 0a 3c 62 3e 73 71 6c reated by.<b>sql
6300: 69 74 65 5f 63 6f 6d 70 69 6c 65 3c 2f 62 3e 20 ite_compile</b>
6310: 74 68 61 74 20 68 61 76 65 20 6e 6f 74 20 62 65 that have not be
6320: 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 62 79 20 en finalized by
6330: 3c 62 3e 73 71 6c 69 74 65 5f 66 69 6e 61 6c 69 <b>sqlite_finali
6340: 7a 65 3c 2f 62 3e 2e 0a 49 6e 20 63 6f 6d 6d 6f ze</b>..In commo
6350: 6e 20 75 73 61 67 65 2c 20 3c 62 3e 73 71 6c 69 n usage, <b>sqli
6360: 74 65 5f 63 68 61 6e 67 65 73 3c 2f 62 3e 20 72 te_changes</b> r
6370: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
6380: 72 0a 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 r.of rows insert
6390: 65 64 2c 20 64 65 6c 65 74 65 64 2c 20 6f 72 20 ed, deleted, or
63a0: 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 modified by the
63b0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 3c 62 3e 73 most recent <b>s
63c0: 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e 0a 63 qlite_exec</b>.c
63d0: 61 6c 6c 20 6f 72 20 73 69 6e 63 65 20 74 68 65 all or since the
63e0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 3c 62 3e most recent <b>
63f0: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 3c 2f sqlite_compile</
6400: 62 3e 2e 20 20 42 75 74 20 69 66 20 79 6f 75 20 b>. But if you
6410: 68 61 76 65 0a 6e 65 73 74 65 64 20 63 61 6c 6c have.nested call
6420: 73 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 65 s to <b>sqlite_e
6430: 78 65 63 3c 2f 62 3e 20 28 74 68 61 74 20 69 73 xec</b> (that is
6440: 2c 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63 , if the callbac
6450: 6b 20 72 6f 75 74 69 6e 65 0a 6f 66 20 6f 6e 65 k routine.of one
6460: 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c <b>sqlite_exec<
6470: 2f 62 3e 20 69 6e 76 6f 6b 65 73 20 61 6e 6f 74 /b> invokes anot
6480: 68 65 72 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 her <b>sqlite_ex
6490: 65 63 3c 2f 62 3e 29 20 6f 72 20 69 66 0a 79 6f ec</b>) or if.yo
64a0: 75 20 69 6e 76 6f 6b 65 20 3c 62 3e 73 71 6c 69 u invoke <b>sqli
64b0: 74 65 5f 63 6f 6d 70 69 6c 65 3c 2f 62 3e 20 74 te_compile</b> t
64c0: 6f 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 56 o create a new V
64d0: 4d 20 77 68 69 6c 65 20 74 68 65 72 65 20 69 73 M while there is
64e0: 0a 73 74 69 6c 6c 20 61 6e 6f 74 68 65 72 20 56 .still another V
64f0: 4d 20 69 6e 20 65 78 69 73 74 61 6e 63 65 2c 20 M in existance,
6500: 74 68 65 6e 0a 74 68 65 20 6d 65 61 6e 69 6e 67 then.the meaning
6510: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 72 of the number r
6520: 65 74 75 72 6e 65 64 20 62 79 20 3c 62 3e 73 71 eturned by <b>sq
6530: 6c 69 74 65 5f 63 68 61 6e 67 65 73 3c 2f 62 3e lite_changes</b>
6540: 20 69 73 20 6d 6f 72 65 0a 63 6f 6d 70 6c 65 78 is more.complex
6550: 2e 0a 54 68 65 20 6e 75 6d 62 65 72 20 72 65 70 ..The number rep
6560: 6f 72 74 65 64 20 69 6e 63 6c 75 64 65 73 20 61 orted includes a
6570: 6e 79 20 63 68 61 6e 67 65 73 0a 74 68 61 74 20 ny changes.that
6580: 77 65 72 65 20 6c 61 74 65 72 20 75 6e 64 6f 6e were later undon
6590: 65 20 62 79 20 61 20 52 4f 4c 4c 42 41 43 4b 20 e by a ROLLBACK
65a0: 6f 72 20 41 42 4f 52 54 2e 20 20 42 75 74 20 72 or ABORT. But r
65b0: 6f 77 73 20 74 68 61 74 20 61 72 65 0a 64 65 6c ows that are.del
65c0: 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 eted because of
65d0: 61 20 44 52 4f 50 20 54 41 42 4c 45 20 61 72 65 a DROP TABLE are
65e0: 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 63 6f <em>not</em> co
65f0: 75 6e 74 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 53 unted.</p>..<p>S
6600: 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 QLite implements
6610: 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 3c 62 the command "<b
6620: 3e 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 >DELETE FROM tab
6630: 6c 65 3c 2f 62 3e 22 20 28 77 69 74 68 6f 75 74 le</b>" (without
6640: 0a 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 29 .a WHERE clause)
6650: 20 62 79 20 64 72 6f 70 70 69 6e 67 20 74 68 65 by dropping the
6660: 20 74 61 62 6c 65 20 74 68 65 6e 20 72 65 63 72 table then recr
6670: 65 61 74 69 6e 67 20 69 74 2e 20 20 0a 54 68 69 eating it. .Thi
6680: 73 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 s is much faster
6690: 20 74 68 61 6e 20 64 65 6c 65 74 69 6e 67 20 74 than deleting t
66a0: 68 65 20 65 6c 65 6d 65 6e 74 73 20 6f 66 20 74 he elements of t
66b0: 68 65 20 74 61 62 6c 65 20 69 6e 64 69 76 69 64 he table individ
66c0: 75 61 6c 6c 79 2e 0a 42 75 74 20 69 74 20 61 6c ually..But it al
66d0: 73 6f 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 so means that th
66e0: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
66f0: 20 66 72 6f 6d 20 3c 62 3e 73 71 6c 69 74 65 5f from <b>sqlite_
6700: 63 68 61 6e 67 65 73 3c 2f 62 3e 0a 77 69 6c 6c changes</b>.will
6710: 20 62 65 20 7a 65 72 6f 20 72 65 67 61 72 64 6c be zero regardl
6720: 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 ess of the numbe
6730: 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 r of elements th
6740: 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c at were original
6750: 6c 79 0a 69 6e 20 74 68 65 20 74 61 62 6c 65 2e ly.in the table.
6760: 20 20 49 66 20 61 6e 20 61 63 63 75 72 61 74 65 If an accurate
6770: 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 count of the nu
6780: 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 mber of elements
6790: 20 64 65 6c 65 74 65 64 0a 69 73 20 6e 65 63 65 deleted.is nece
67a0: 73 73 61 72 79 2c 20 75 73 65 20 22 3c 62 3e 44 ssary, use "<b>D
67b0: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 ELETE FROM table
67c0: 20 57 48 45 52 45 20 31 3c 2f 62 3e 22 20 69 6e WHERE 1</b>" in
67d0: 73 74 65 61 64 2e 3c 2f 70 3e 0a 0a 3c 68 34 3e stead.</p>..<h4>
67e0: 33 2e 33 20 51 75 65 72 79 69 6e 67 20 69 6e 74 3.3 Querying int
67f0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 o memory obtaine
6800: 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 3c d from malloc()<
6810: 2f 68 34 3e 0a 0a 3c 70 3e 54 68 65 20 3c 62 3e /h4>..<p>The <b>
6820: 73 71 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 sqlite_get_table
6830: 3c 2f 62 3e 20 66 75 6e 63 74 69 6f 6e 20 69 73 </b> function is
6840: 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e a wrapper aroun
6850: 64 0a 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 d.<b>sqlite_exec
6860: 3c 2f 62 3e 20 74 68 61 74 20 63 6f 6c 6c 65 63 </b> that collec
6870: 74 73 20 61 6c 6c 20 74 68 65 20 69 6e 66 6f 72 ts all the infor
6880: 6d 61 74 69 6f 6e 20 66 72 6f 6d 20 73 75 63 63 mation from succ
6890: 65 73 73 69 76 65 0a 63 61 6c 6c 62 61 63 6b 73 essive.callbacks
68a0: 20 61 6e 64 20 77 72 69 74 65 73 20 69 74 20 69 and writes it i
68b0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 nto memory obtai
68c0: 6e 65 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 ned from malloc(
68d0: 29 2e 20 20 54 68 69 73 0a 69 73 20 61 20 63 6f ). This.is a co
68e0: 6e 76 65 6e 69 65 6e 63 65 20 66 75 6e 63 74 69 nvenience functi
68f0: 6f 6e 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 74 on that allows t
6900: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 he application t
6910: 6f 20 67 65 74 20 74 68 65 0a 65 6e 74 69 72 65 o get the.entire
6920: 20 72 65 73 75 6c 74 20 6f 66 20 61 20 64 61 74 result of a dat
6930: 61 62 61 73 65 20 71 75 65 72 79 20 77 69 74 68 abase query with
6940: 20 61 20 73 69 6e 67 6c 65 20 66 75 6e 63 74 69 a single functi
6950: 6f 6e 20 63 61 6c 6c 2e 3c 2f 70 3e 0a 0a 3c 70 on call.</p>..<p
6960: 3e 54 68 65 20 6d 61 69 6e 20 72 65 73 75 6c 74 >The main result
6970: 20 66 72 6f 6d 20 3c 62 3e 73 71 6c 69 74 65 5f from <b>sqlite_
6980: 67 65 74 5f 74 61 62 6c 65 3c 2f 62 3e 20 69 73 get_table</b> is
6990: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 an array of poi
69a0: 6e 74 65 72 73 0a 74 6f 20 73 74 72 69 6e 67 73 nters.to strings
69b0: 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 . There is one
69c0: 65 6c 65 6d 65 6e 74 20 69 6e 20 74 68 69 73 20 element in this
69d0: 61 72 72 61 79 20 66 6f 72 20 65 61 63 68 20 63 array for each c
69e0: 6f 6c 75 6d 6e 20 6f 66 0a 65 61 63 68 20 72 6f olumn of.each ro
69f0: 77 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e w in the result.
6a00: 20 20 4e 55 4c 4c 20 72 65 73 75 6c 74 73 20 61 NULL results a
6a10: 72 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 re represented b
6a20: 79 20 61 20 4e 55 4c 4c 0a 70 6f 69 6e 74 65 72 y a NULL.pointer
6a30: 2e 20 49 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f . In addition to
6a40: 20 74 68 65 20 72 65 67 75 6c 61 72 20 64 61 74 the regular dat
6a50: 61 2c 20 74 68 65 72 65 20 69 73 20 61 6e 20 61 a, there is an a
6a60: 64 64 65 64 20 72 6f 77 20 61 74 20 74 68 65 20 dded row at the
6a70: 0a 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 74 68 .beginning of th
6a80: 65 20 61 72 72 61 79 20 74 68 61 74 20 63 6f 6e e array that con
6a90: 74 61 69 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f tains the name o
6aa0: 66 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 6f 66 f each column of
6ab0: 20 74 68 65 0a 72 65 73 75 6c 74 2e 3c 2f 70 3e the.result.</p>
6ac0: 0a 0a 3c 70 3e 41 73 20 61 6e 20 65 78 61 6d 70 ..<p>As an examp
6ad0: 6c 65 2c 20 63 6f 6e 73 69 64 65 72 20 74 68 65 le, consider the
6ae0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 following query
6af0: 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f :</p>..<blockquo
6b00: 74 65 3e 0a 53 45 4c 45 43 54 20 65 6d 70 6c 6f te>.SELECT emplo
6b10: 79 65 65 5f 6e 61 6d 65 2c 20 6c 6f 67 69 6e 2c yee_name, login,
6b20: 20 68 6f 73 74 20 46 52 4f 4d 20 75 73 65 72 73 host FROM users
6b30: 20 57 48 45 52 45 20 6c 6f 67 69 6e 20 4c 49 4b WHERE login LIK
6b40: 45 20 27 64 25 27 3b 0a 3c 2f 62 6c 6f 63 6b 71 E 'd%';.</blockq
6b50: 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 69 73 20 71 uote>..<p>This q
6b60: 75 65 72 79 20 77 69 6c 6c 20 72 65 74 75 72 6e uery will return
6b70: 20 74 68 65 20 6e 61 6d 65 2c 20 6c 6f 67 69 6e the name, login
6b80: 20 61 6e 64 20 68 6f 73 74 20 63 6f 6d 70 75 74 and host comput
6b90: 65 72 20 6e 61 6d 65 0a 66 6f 72 20 65 76 65 72 er name.for ever
6ba0: 79 20 65 6d 70 6c 6f 79 65 65 20 77 68 6f 73 65 y employee whose
6bb0: 20 6c 6f 67 69 6e 20 62 65 67 69 6e 73 20 77 69 login begins wi
6bc0: 74 68 20 74 68 65 20 6c 65 74 74 65 72 20 22 64 th the letter "d
6bd0: 22 2e 20 20 49 66 20 74 68 69 73 0a 71 75 65 72 ". If this.quer
6be0: 79 20 69 73 20 73 75 62 6d 69 74 74 65 64 20 74 y is submitted t
6bf0: 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 67 65 74 5f o <b>sqlite_get_
6c00: 74 61 62 6c 65 3c 2f 62 3e 20 74 68 65 20 72 65 table</b> the re
6c10: 73 75 6c 74 20 6d 69 67 68 74 0a 6c 6f 6f 6b 20 sult might.look
6c20: 6c 69 6b 65 20 74 68 69 73 3a 3c 2f 70 3e 0a 0a like this:</p>..
6c30: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 6e 72 6f <blockquote>.nro
6c40: 77 20 3d 20 32 3c 62 72 3e 0a 6e 63 6f 6c 75 6d w = 2<br>.ncolum
6c50: 6e 20 3d 20 33 3c 62 72 3e 0a 72 65 73 75 6c 74 n = 3<br>.result
6c60: 5b 30 5d 20 3d 20 22 65 6d 70 6c 6f 79 65 65 5f [0] = "employee_
6c70: 6e 61 6d 65 22 3c 62 72 3e 0a 72 65 73 75 6c 74 name"<br>.result
6c80: 5b 31 5d 20 3d 20 22 6c 6f 67 69 6e 22 3c 62 72 [1] = "login"<br
6c90: 3e 0a 72 65 73 75 6c 74 5b 32 5d 20 3d 20 22 68 >.result[2] = "h
6ca0: 6f 73 74 22 3c 62 72 3e 0a 72 65 73 75 6c 74 5b ost"<br>.result[
6cb0: 33 5d 20 3d 20 22 64 75 6d 6d 79 22 3c 62 72 3e 3] = "dummy"<br>
6cc0: 0a 72 65 73 75 6c 74 5b 34 5d 20 3d 20 22 4e 6f .result[4] = "No
6cd0: 20 73 75 63 68 20 75 73 65 72 22 3c 62 72 3e 0a such user"<br>.
6ce0: 72 65 73 75 6c 74 5b 35 5d 20 3d 20 30 3c 62 72 result[5] = 0<br
6cf0: 3e 0a 72 65 73 75 6c 74 5b 36 5d 20 3d 20 22 44 >.result[6] = "D
6d00: 2e 20 52 69 63 68 61 72 64 20 48 69 70 70 22 3c . Richard Hipp"<
6d10: 62 72 3e 0a 72 65 73 75 6c 74 5b 37 5d 20 3d 20 br>.result[7] =
6d20: 22 64 72 68 22 3c 62 72 3e 0a 72 65 73 75 6c 74 "drh"<br>.result
6d30: 5b 38 5d 20 3d 20 22 7a 61 64 6f 6b 22 0a 3c 2f [8] = "zadok".</
6d40: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e blockquote>..<p>
6d50: 4e 6f 74 69 63 65 20 74 68 61 74 20 74 68 65 20 Notice that the
6d60: 22 68 6f 73 74 22 20 76 61 6c 75 65 20 66 6f 72 "host" value for
6d70: 20 74 68 65 20 22 64 75 6d 6d 79 22 20 72 65 63 the "dummy" rec
6d80: 6f 72 64 20 69 73 20 4e 55 4c 4c 20 73 6f 0a 74 ord is NULL so.t
6d90: 68 65 20 72 65 73 75 6c 74 5b 5d 20 61 72 72 61 he result[] arra
6da0: 79 20 63 6f 6e 74 61 69 6e 73 20 61 20 4e 55 4c y contains a NUL
6db0: 4c 20 70 6f 69 6e 74 65 72 20 61 74 20 74 68 61 L pointer at tha
6dc0: 74 20 73 6c 6f 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e t slot.</p>..<p>
6dd0: 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 If the result se
6de0: 74 20 6f 66 20 61 20 71 75 65 72 79 20 69 73 20 t of a query is
6df0: 65 6d 70 74 79 2c 20 74 68 65 6e 20 62 79 20 64 empty, then by d
6e00: 65 66 61 75 6c 74 0a 3c 62 3e 73 71 6c 69 74 65 efault.<b>sqlite
6e10: 5f 67 65 74 5f 74 61 62 6c 65 3c 2f 62 3e 20 77 _get_table</b> w
6e20: 69 6c 6c 20 73 65 74 20 6e 72 6f 77 20 74 6f 20 ill set nrow to
6e30: 30 20 61 6e 64 20 6c 65 61 76 65 20 69 74 73 0a 0 and leave its.
6e40: 72 65 73 75 6c 74 20 70 61 72 61 6d 65 74 65 72 result parameter
6e50: 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e is set to NULL.
6e60: 20 20 42 75 74 20 69 66 20 74 68 65 20 45 4d 50 But if the EMP
6e70: 54 59 5f 52 45 53 55 4c 54 5f 43 41 4c 4c 42 41 TY_RESULT_CALLBA
6e80: 43 4b 53 0a 70 72 61 67 6d 61 20 69 73 20 4f 4e CKS.pragma is ON
6e90: 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
6ea0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e parameter is in
6eb0: 69 74 69 61 6c 69 7a 65 64 20 74 6f 20 74 68 65 itialized to the
6ec0: 20 6e 61 6d 65 73 0a 6f 66 20 74 68 65 20 63 6f names.of the co
6ed0: 6c 75 6d 6e 73 20 6f 6e 6c 79 2e 20 20 46 6f 72 lumns only. For
6ee0: 20 65 78 61 6d 70 6c 65 2c 20 63 6f 6e 73 69 64 example, consid
6ef0: 65 72 20 74 68 69 73 20 71 75 65 72 79 20 77 68 er this query wh
6f00: 69 63 68 20 68 61 73 0a 61 6e 20 65 6d 70 74 79 ich has.an empty
6f10: 20 72 65 73 75 6c 74 20 73 65 74 3a 3c 2f 70 3e result set:</p>
6f20: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 53 ..<blockquote>.S
6f30: 45 4c 45 43 54 20 65 6d 70 6c 6f 79 65 65 5f 6e ELECT employee_n
6f40: 61 6d 65 2c 20 6c 6f 67 69 6e 2c 20 68 6f 73 74 ame, login, host
6f50: 20 46 52 4f 4d 20 75 73 65 72 73 20 57 48 45 52 FROM users WHER
6f60: 45 20 65 6d 70 6c 6f 79 65 65 5f 6e 61 6d 65 20 E employee_name
6f70: 49 53 20 4e 55 4c 4c 3b 0a 3c 2f 62 6c 6f 63 6b IS NULL;.</block
6f80: 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65 20 quote>..<p>.The
6f90: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 default behavior
6fa0: 20 67 69 76 65 73 20 74 68 69 73 20 72 65 73 75 gives this resu
6fb0: 6c 74 73 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 lts:.</p>..<bloc
6fc0: 6b 71 75 6f 74 65 3e 0a 6e 72 6f 77 20 3d 20 30 kquote>.nrow = 0
6fd0: 3c 62 72 3e 0a 6e 63 6f 6c 75 6d 6e 20 3d 20 30 <br>.ncolumn = 0
6fe0: 3c 62 72 3e 0a 72 65 73 75 6c 74 20 3d 20 30 3c <br>.result = 0<
6ff0: 62 72 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 br>.</blockquote
7000: 3e 0a 0a 3c 70 3e 0a 42 75 74 20 69 66 20 74 68 >..<p>.But if th
7010: 65 20 45 4d 50 54 59 5f 52 45 53 55 4c 54 5f 43 e EMPTY_RESULT_C
7020: 41 4c 4c 42 41 43 4b 53 20 70 72 61 67 6d 61 20 ALLBACKS pragma
7030: 69 73 20 4f 4e 2c 20 74 68 65 6e 20 74 68 65 20 is ON, then the
7040: 66 6f 6c 6c 6f 77 69 6e 67 0a 69 73 20 72 65 74 following.is ret
7050: 75 72 6e 65 64 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c urned:.</p>..<bl
7060: 6f 63 6b 71 75 6f 74 65 3e 0a 6e 72 6f 77 20 3d ockquote>.nrow =
7070: 20 30 3c 62 72 3e 0a 6e 63 6f 6c 75 6d 6e 20 3d 0<br>.ncolumn =
7080: 20 33 3c 62 72 3e 0a 72 65 73 75 6c 74 5b 30 5d 3<br>.result[0]
7090: 20 3d 20 22 65 6d 70 6c 6f 79 65 65 5f 6e 61 6d = "employee_nam
70a0: 65 22 3c 62 72 3e 0a 72 65 73 75 6c 74 5b 31 5d e"<br>.result[1]
70b0: 20 3d 20 22 6c 6f 67 69 6e 22 3c 62 72 3e 0a 72 = "login"<br>.r
70c0: 65 73 75 6c 74 5b 32 5d 20 3d 20 22 68 6f 73 74 esult[2] = "host
70d0: 22 3c 62 72 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f "<br>.</blockquo
70e0: 74 65 3e 0a 0a 3c 70 3e 4d 65 6d 6f 72 79 20 74 te>..<p>Memory t
70f0: 6f 20 68 6f 6c 64 20 74 68 65 20 69 6e 66 6f 72 o hold the infor
7100: 6d 61 74 69 6f 6e 20 72 65 74 75 72 6e 65 64 20 mation returned
7110: 62 79 20 3c 62 3e 73 71 6c 69 74 65 5f 67 65 74 by <b>sqlite_get
7120: 5f 74 61 62 6c 65 3c 2f 62 3e 0a 69 73 20 6f 62 _table</b>.is ob
7130: 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c 6c tained from mall
7140: 6f 63 28 29 2e 20 20 42 75 74 20 74 68 65 20 63 oc(). But the c
7150: 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 alling function
7160: 73 68 6f 75 6c 64 20 6e 6f 74 20 74 72 79 0a 74 should not try.t
7170: 6f 20 66 72 65 65 20 74 68 69 73 20 69 6e 66 6f o free this info
7180: 72 6d 61 74 69 6f 6e 20 64 69 72 65 63 74 6c 79 rmation directly
7190: 2e 20 20 49 6e 73 74 65 61 64 2c 20 70 61 73 73 . Instead, pass
71a0: 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 74 61 the complete ta
71b0: 62 6c 65 0a 74 6f 20 3c 62 3e 73 71 6c 69 74 65 ble.to <b>sqlite
71c0: 5f 66 72 65 65 5f 74 61 62 6c 65 3c 2f 62 3e 20 _free_table</b>
71d0: 77 68 65 6e 20 74 68 65 20 74 61 62 6c 65 20 69 when the table i
71e0: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 s no longer need
71f0: 65 64 2e 0a 49 74 20 69 73 20 73 61 66 65 20 74 ed..It is safe t
7200: 6f 20 63 61 6c 6c 20 3c 62 3e 73 71 6c 69 74 65 o call <b>sqlite
7210: 5f 66 72 65 65 5f 74 61 62 6c 65 3c 2f 62 3e 20 _free_table</b>
7220: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e with a NULL poin
7230: 74 65 72 20 73 75 63 68 0a 61 73 20 77 6f 75 6c ter such.as woul
7240: 64 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 d be returned if
7250: 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
7260: 69 73 20 65 6d 70 74 79 2e 3c 2f 70 3e 0a 0a 3c is empty.</p>..<
7270: 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f p>The <b>sqlite_
7280: 67 65 74 5f 74 61 62 6c 65 3c 2f 62 3e 20 72 6f get_table</b> ro
7290: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
72a0: 65 20 73 61 6d 65 20 69 6e 74 65 67 65 72 0a 72 e same integer.r
72b0: 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20 3c 62 esult code as <b
72c0: 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e >sqlite_exec</b>
72d0: 2e 3c 2f 70 3e 0a 0a 3c 68 34 3e 33 2e 34 20 49 .</p>..<h4>3.4 I
72e0: 6e 74 65 72 72 75 70 74 69 6e 67 20 61 6e 20 53 nterrupting an S
72f0: 51 4c 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 3c QLite operation<
7300: 2f 68 34 3e 0a 0a 3c 70 3e 54 68 65 20 3c 62 3e /h4>..<p>The <b>
7310: 73 71 6c 69 74 65 5f 69 6e 74 65 72 72 75 70 74 sqlite_interrupt
7320: 3c 2f 62 3e 20 66 75 6e 63 74 69 6f 6e 20 63 61 </b> function ca
7330: 6e 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d n be called from
7340: 20 61 0a 64 69 66 66 65 72 65 6e 74 20 74 68 72 a.different thr
7350: 65 61 64 20 6f 72 20 66 72 6f 6d 20 61 20 73 69 ead or from a si
7360: 67 6e 61 6c 20 68 61 6e 64 6c 65 72 20 74 6f 20 gnal handler to
7370: 63 61 75 73 65 20 74 68 65 20 63 75 72 72 65 6e cause the curren
7380: 74 20 64 61 74 61 62 61 73 65 0a 6f 70 65 72 61 t database.opera
7390: 74 69 6f 6e 20 74 6f 20 65 78 69 74 20 61 74 20 tion to exit at
73a0: 69 74 73 20 66 69 72 73 74 20 6f 70 70 6f 72 74 its first opport
73b0: 75 6e 69 74 79 2e 20 20 57 68 65 6e 20 74 68 69 unity. When thi
73c0: 73 20 68 61 70 70 65 6e 73 2c 0a 74 68 65 20 3c s happens,.the <
73d0: 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62 b>sqlite_exec</b
73e0: 3e 20 72 6f 75 74 69 6e 65 20 28 6f 72 20 74 68 > routine (or th
73f0: 65 20 65 71 75 69 76 61 6c 65 6e 74 29 20 74 68 e equivalent) th
7400: 61 74 20 73 74 61 72 74 65 64 0a 74 68 65 20 64 at started.the d
7410: 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f atabase operatio
7420: 6e 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 n will return SQ
7430: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 2e 3c LITE_INTERRUPT.<
7440: 2f 70 3e 0a 0a 3c 68 34 3e 33 2e 35 20 54 65 73 /p>..<h4>3.5 Tes
7450: 74 69 6e 67 20 66 6f 72 20 61 20 63 6f 6d 70 6c ting for a compl
7460: 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ete SQL statemen
7470: 74 3c 2f 68 34 3e 0a 0a 3c 70 3e 54 68 65 20 6e t</h4>..<p>The n
7480: 65 78 74 20 69 6e 74 65 72 66 61 63 65 20 72 6f ext interface ro
7490: 75 74 69 6e 65 20 74 6f 20 53 51 4c 69 74 65 20 utine to SQLite
74a0: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 is a convenience
74b0: 20 66 75 6e 63 74 69 6f 6e 20 75 73 65 64 0a 74 function used.t
74c0: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 6f o test whether o
74d0: 72 20 6e 6f 74 20 61 20 73 74 72 69 6e 67 20 66 r not a string f
74e0: 6f 72 6d 73 20 61 20 63 6f 6d 70 6c 65 74 65 20 orms a complete
74f0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 49 SQL statement..I
7500: 66 20 74 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f f the <b>sqlite_
7510: 63 6f 6d 70 6c 65 74 65 3c 2f 62 3e 20 66 75 6e complete</b> fun
7520: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 72 ction returns tr
7530: 75 65 20 77 68 65 6e 20 69 74 73 20 69 6e 70 75 ue when its inpu
7540: 74 0a 69 73 20 61 20 73 74 72 69 6e 67 2c 20 74 t.is a string, t
7550: 68 65 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 hen the argument
7560: 20 66 6f 72 6d 73 20 61 20 63 6f 6d 70 6c 65 74 forms a complet
7570: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e e SQL statement.
7580: 0a 54 68 65 72 65 20 61 72 65 20 6e 6f 20 67 75 .There are no gu
7590: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 arantees that th
75a0: 65 20 73 79 6e 74 61 78 20 6f 66 20 74 68 61 74 e syntax of that
75b0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f statement is co
75c0: 72 72 65 63 74 2c 0a 62 75 74 20 77 65 20 61 74 rrect,.but we at
75d0: 20 6c 65 61 73 74 20 6b 6e 6f 77 20 74 68 65 20 least know the
75e0: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6d statement is com
75f0: 70 6c 65 74 65 2e 20 20 49 66 20 3c 62 3e 73 71 plete. If <b>sq
7600: 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 65 3c 2f 62 lite_complete</b
7610: 3e 0a 72 65 74 75 72 6e 73 20 66 61 6c 73 65 2c >.returns false,
7620: 20 74 68 65 6e 20 6d 6f 72 65 20 74 65 78 74 20 then more text
7630: 69 73 20 72 65 71 75 69 72 65 64 20 74 6f 20 63 is required to c
7640: 6f 6d 70 6c 65 74 65 20 74 68 65 20 53 51 4c 20 omplete the SQL
7650: 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 70 3e 0a 0a statement.</p>..
7660: 3c 70 3e 46 6f 72 20 74 68 65 20 70 75 72 70 6f <p>For the purpo
7670: 73 65 20 6f 66 20 74 68 65 20 3c 62 3e 73 71 6c se of the <b>sql
7680: 69 74 65 5f 63 6f 6d 70 6c 65 74 65 3c 2f 62 3e ite_complete</b>
7690: 20 66 75 6e 63 74 69 6f 6e 2c 20 61 6e 20 53 51 function, an SQ
76a0: 4c 0a 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 L.statement is c
76b0: 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e omplete if it en
76c0: 64 73 20 69 6e 20 61 20 73 65 6d 69 63 6f 6c 6f ds in a semicolo
76d0: 6e 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 3c n.</p>..<p>The <
76e0: 62 3e 73 71 6c 69 74 65 3c 2f 62 3e 20 63 6f 6d b>sqlite</b> com
76f0: 6d 61 6e 64 2d 6c 69 6e 65 20 75 74 69 6c 69 74 mand-line utilit
7700: 79 20 75 73 65 73 20 74 68 65 20 3c 62 3e 73 71 y uses the <b>sq
7710: 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 65 3c 2f 62 lite_complete</b
7720: 3e 0a 66 75 6e 63 74 69 6f 6e 20 74 6f 20 6b 6e >.function to kn
7730: 6f 77 20 77 68 65 6e 20 69 74 20 6e 65 65 64 73 ow when it needs
7740: 20 74 6f 20 63 61 6c 6c 20 3c 62 3e 73 71 6c 69 to call <b>sqli
7750: 74 65 5f 65 78 65 63 3c 2f 62 3e 2e 20 20 41 66 te_exec</b>. Af
7760: 74 65 72 20 65 61 63 68 0a 6c 69 6e 65 20 6f 66 ter each.line of
7770: 20 69 6e 70 75 74 20 69 73 20 72 65 63 65 69 76 input is receiv
7780: 65 64 2c 20 3c 62 3e 73 71 6c 69 74 65 3c 2f 62 ed, <b>sqlite</b
7790: 3e 20 63 61 6c 6c 73 20 3c 62 3e 73 71 6c 69 74 > calls <b>sqlit
77a0: 65 5f 63 6f 6d 70 6c 65 74 65 3c 2f 62 3e 0a 6f e_complete</b>.o
77b0: 6e 20 61 6c 6c 20 69 6e 70 75 74 20 69 6e 20 69 n all input in i
77c0: 74 73 20 62 75 66 66 65 72 2e 20 20 49 66 20 3c ts buffer. If <
77d0: 62 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 b>sqlite_complet
77e0: 65 3c 2f 62 3e 20 72 65 74 75 72 6e 73 20 74 72 e</b> returns tr
77f0: 75 65 2c 20 0a 74 68 65 6e 20 3c 62 3e 73 71 6c ue, .then <b>sql
7800: 69 74 65 5f 65 78 65 63 3c 2f 62 3e 20 69 73 20 ite_exec</b> is
7810: 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 65 20 69 called and the i
7820: 6e 70 75 74 20 62 75 66 66 65 72 20 69 73 20 72 nput buffer is r
7830: 65 73 65 74 2e 20 20 49 66 0a 3c 62 3e 73 71 6c eset. If.<b>sql
7840: 69 74 65 5f 63 6f 6d 70 6c 65 74 65 3c 2f 62 3e ite_complete</b>
7850: 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 2c 20 returns false,
7860: 74 68 65 6e 20 74 68 65 20 70 72 6f 6d 70 74 20 then the prompt
7870: 69 73 20 63 68 61 6e 67 65 64 20 74 6f 0a 74 68 is changed to.th
7880: 65 20 63 6f 6e 74 69 6e 75 61 74 69 6f 6e 20 70 e continuation p
7890: 72 6f 6d 70 74 20 61 6e 64 20 61 6e 6f 74 68 65 rompt and anothe
78a0: 72 20 6c 69 6e 65 20 6f 66 20 74 65 78 74 20 69 r line of text i
78b0: 73 20 72 65 61 64 20 61 6e 64 20 61 64 64 65 64 s read and added
78c0: 20 74 6f 0a 74 68 65 20 69 6e 70 75 74 20 62 75 to.the input bu
78d0: 66 66 65 72 2e 3c 2f 70 3e 0a 0a 3c 68 34 3e 33 ffer.</p>..<h4>3
78e0: 2e 36 20 4c 69 62 72 61 72 79 20 76 65 72 73 69 .6 Library versi
78f0: 6f 6e 20 73 74 72 69 6e 67 3c 2f 68 34 3e 0a 0a on string</h4>..
7900: 3c 70 3e 54 68 65 20 53 51 4c 69 74 65 20 6c 69 <p>The SQLite li
7910: 62 72 61 72 79 20 65 78 70 6f 72 74 73 20 74 68 brary exports th
7920: 65 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e e string constan
7930: 74 20 6e 61 6d 65 64 0a 3c 62 3e 73 71 6c 69 74 t named.<b>sqlit
7940: 65 5f 76 65 72 73 69 6f 6e 3c 2f 62 3e 20 77 68 e_version</b> wh
7950: 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 ich contains the
7960: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 version number
7970: 6f 66 20 74 68 65 0a 6c 69 62 72 61 72 79 2e 20 of the.library.
7980: 20 54 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 The header file
7990: 20 63 6f 6e 74 61 69 6e 73 20 61 20 6d 61 63 72 contains a macr
79a0: 6f 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e o SQLITE_VERSION
79b0: 0a 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 69 .with the same i
79c0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 20 49 66 20 nformation. If
79d0: 64 65 73 69 72 65 64 2c 20 61 20 70 72 6f 67 72 desired, a progr
79e0: 61 6d 20 63 61 6e 20 63 6f 6d 70 61 72 65 0a 74 am can compare.t
79f0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f he SQLITE_VERSIO
7a00: 4e 20 6d 61 63 72 6f 20 61 67 61 69 6e 73 74 20 N macro against
7a10: 74 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 76 65 the <b>sqlite_ve
7a20: 72 73 69 6f 6e 3c 2f 62 3e 0a 73 74 72 69 6e 67 rsion</b>.string
7a30: 20 63 6f 6e 73 74 61 6e 74 20 74 6f 20 76 65 72 constant to ver
7a40: 69 66 79 20 74 68 61 74 20 74 68 65 20 76 65 72 ify that the ver
7a50: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 6f 66 20 74 sion number of t
7a60: 68 65 0a 68 65 61 64 65 72 20 66 69 6c 65 20 61 he.header file a
7a70: 6e 64 20 74 68 65 20 6c 69 62 72 61 72 79 20 6d nd the library m
7a80: 61 74 63 68 2e 3c 2f 70 3e 20 0a 0a 3c 68 34 3e atch.</p> ..<h4>
7a90: 33 2e 37 20 4c 69 62 72 61 72 79 20 63 68 61 72 3.7 Library char
7aa0: 61 63 74 65 72 20 65 6e 63 6f 64 69 6e 67 3c 2f acter encoding</
7ab0: 68 34 3e 0a 0a 3c 70 3e 42 79 20 64 65 66 61 75 h4>..<p>By defau
7ac0: 6c 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d lt, SQLite assum
7ad0: 65 73 20 74 68 61 74 20 61 6c 6c 20 64 61 74 61 es that all data
7ae0: 20 75 73 65 73 20 61 20 66 69 78 65 64 2d 73 69 uses a fixed-si
7af0: 7a 65 0a 38 2d 62 69 74 20 63 68 61 72 61 63 74 ze.8-bit charact
7b00: 65 72 20 28 69 73 6f 38 38 35 39 29 2e 20 20 42 er (iso8859). B
7b10: 75 74 20 69 66 20 79 6f 75 20 67 69 76 65 20 74 ut if you give t
7b20: 68 65 20 2d 2d 65 6e 61 62 6c 65 2d 75 74 66 38 he --enable-utf8
7b30: 20 6f 70 74 69 6f 6e 0a 74 6f 20 74 68 65 20 63 option.to the c
7b40: 6f 6e 66 69 67 75 72 65 20 73 63 72 69 70 74 2c onfigure script,
7b50: 20 74 68 65 6e 20 74 68 65 20 6c 69 62 72 61 72 then the librar
7b60: 79 20 61 73 73 75 6d 65 73 20 55 54 46 2d 38 20 y assumes UTF-8
7b70: 76 61 72 69 61 62 6c 65 0a 73 69 7a 65 64 20 63 variable.sized c
7b80: 68 61 72 61 63 74 65 72 73 2e 20 20 54 68 69 73 haracters. This
7b90: 20 6d 61 6b 65 73 20 61 20 64 69 66 66 65 72 65 makes a differe
7ba0: 6e 63 65 20 66 6f 72 20 74 68 65 20 4c 49 4b 45 nce for the LIKE
7bb0: 20 61 6e 64 20 47 4c 4f 42 0a 6f 70 65 72 61 74 and GLOB.operat
7bc0: 6f 72 73 20 61 6e 64 20 74 68 65 20 4c 45 4e 47 ors and the LENG
7bd0: 54 48 28 29 20 61 6e 64 20 53 55 42 53 54 52 28 TH() and SUBSTR(
7be0: 29 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 ) functions. Th
7bf0: 65 20 73 74 61 74 69 63 0a 73 74 72 69 6e 67 20 e static.string
7c00: 3c 62 3e 73 71 6c 69 74 65 5f 65 6e 63 6f 64 69 <b>sqlite_encodi
7c10: 6e 67 3c 2f 62 3e 20 77 69 6c 6c 20 62 65 20 73 ng</b> will be s
7c20: 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 55 54 et to either "UT
7c30: 46 2d 38 22 20 6f 72 0a 22 69 73 6f 38 38 35 39 F-8" or."iso8859
7c40: 22 20 74 6f 20 69 6e 64 69 63 61 74 65 20 68 6f " to indicate ho
7c50: 77 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 w the library wa
7c60: 73 20 63 6f 6d 70 69 6c 65 64 2e 20 20 49 6e 20 s compiled. In
7c70: 61 64 64 69 74 69 6f 6e 2c 0a 74 68 65 20 3c 62 addition,.the <b
7c80: 3e 73 71 6c 69 74 65 2e 68 3c 2f 62 3e 20 68 65 >sqlite.h</b> he
7c90: 61 64 65 72 20 66 69 6c 65 20 77 69 6c 6c 20 64 ader file will d
7ca0: 65 66 69 6e 65 20 6f 6e 65 20 6f 66 20 74 68 65 efine one of the
7cb0: 0a 6d 61 63 72 6f 73 20 3c 62 3e 53 51 4c 49 54 .macros <b>SQLIT
7cc0: 45 5f 55 54 46 38 3c 2f 62 3e 20 6f 72 20 3c 62 E_UTF8</b> or <b
7cd0: 3e 53 51 4c 49 54 45 5f 49 53 4f 38 38 35 39 3c >SQLITE_ISO8859<
7ce0: 2f 62 3e 2c 20 61 73 20 61 70 70 72 6f 70 72 69 /b>, as appropri
7cf0: 61 74 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e 4e 6f 74 ate.</p>..<p>Not
7d00: 65 20 74 68 61 74 20 74 68 65 20 63 68 61 72 61 e that the chara
7d10: 63 74 65 72 20 65 6e 63 6f 64 69 6e 67 20 6d 65 cter encoding me
7d20: 63 68 61 6e 69 73 6d 20 75 73 65 64 20 62 79 20 chanism used by
7d30: 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 0a 62 65 SQLite cannot.be
7d40: 20 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d changed at run-
7d50: 74 69 6d 65 2e 20 20 54 68 69 73 20 69 73 20 61 time. This is a
7d60: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
7d70: 74 69 6f 6e 20 6f 6e 6c 79 2e 20 20 54 68 65 0a tion only. The.
7d80: 3c 62 3e 73 71 6c 69 74 65 5f 65 6e 63 6f 64 69 <b>sqlite_encodi
7d90: 6e 67 3c 2f 62 3e 20 63 68 61 72 61 63 74 65 72 ng</b> character
7da0: 20 73 74 72 69 6e 67 20 6a 75 73 74 20 74 65 6c string just tel
7db0: 6c 73 20 79 6f 75 20 68 6f 77 20 74 68 65 20 6c ls you how the l
7dc0: 69 62 72 61 72 79 0a 77 61 73 20 63 6f 6d 70 69 ibrary.was compi
7dd0: 6c 65 64 2e 3c 2f 70 3e 0a 0a 3c 68 34 3e 33 2e led.</p>..<h4>3.
7de0: 38 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 6c 8 Changing the l
7df0: 69 62 72 61 72 79 27 73 20 72 65 73 70 6f 6e 73 ibrary's respons
7e00: 65 20 74 6f 20 6c 6f 63 6b 65 64 20 66 69 6c 65 e to locked file
7e10: 73 3c 2f 68 34 3e 0a 0a 3c 70 3e 54 68 65 20 3c s</h4>..<p>The <
7e20: 62 3e 73 71 6c 69 74 65 5f 62 75 73 79 5f 68 61 b>sqlite_busy_ha
7e30: 6e 64 6c 65 72 3c 2f 62 3e 20 70 72 6f 63 65 64 ndler</b> proced
7e40: 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ure can be used
7e50: 74 6f 20 72 65 67 69 73 74 65 72 0a 61 20 62 75 to register.a bu
7e60: 73 79 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 sy callback with
7e70: 20 61 6e 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 an open SQLite
7e80: 64 61 74 61 62 61 73 65 2e 20 20 54 68 65 20 62 database. The b
7e90: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c usy callback wil
7ea0: 6c 0a 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 l.be invoked whe
7eb0: 6e 65 76 65 72 20 53 51 4c 69 74 65 20 74 72 69 never SQLite tri
7ec0: 65 73 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 es to access a d
7ed0: 61 74 61 62 61 73 65 20 74 68 61 74 20 69 73 20 atabase that is
7ee0: 6c 6f 63 6b 65 64 2e 0a 54 68 65 20 63 61 6c 6c locked..The call
7ef0: 62 61 63 6b 20 77 69 6c 6c 20 74 79 70 69 63 61 back will typica
7f00: 6c 6c 79 20 64 6f 20 73 6f 6d 65 20 6f 74 68 65 lly do some othe
7f10: 72 20 75 73 65 66 75 6c 20 77 6f 72 6b 2c 20 6f r useful work, o
7f20: 72 20 70 65 72 68 61 70 73 20 73 6c 65 65 70 2c r perhaps sleep,
7f30: 0a 69 6e 20 6f 72 64 65 72 20 74 6f 20 67 69 76 .in order to giv
7f40: 65 20 74 68 65 20 6c 6f 63 6b 20 61 20 63 68 61 e the lock a cha
7f50: 6e 63 65 20 74 6f 20 63 6c 65 61 72 2e 20 20 49 nce to clear. I
7f60: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 f the callback r
7f70: 65 74 75 72 6e 73 0a 6e 6f 6e 2d 7a 65 72 6f 2c eturns.non-zero,
7f80: 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 72 69 then SQLite tri
7f90: 65 73 20 61 67 61 69 6e 20 74 6f 20 61 63 63 65 es again to acce
7fa0: 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ss the database
7fb0: 61 6e 64 20 74 68 65 20 63 79 63 6c 65 0a 72 65 and the cycle.re
7fc0: 70 65 61 74 73 2e 20 20 49 66 20 74 68 65 20 63 peats. If the c
7fd0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
7fe0: 7a 65 72 6f 2c 20 74 68 65 6e 20 53 51 4c 69 74 zero, then SQLit
7ff0: 65 20 61 62 6f 72 74 73 20 74 68 65 20 63 75 72 e aborts the cur
8000: 72 65 6e 74 0a 6f 70 65 72 61 74 69 6f 6e 20 61 rent.operation a
8010: 6e 64 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 nd returns SQLIT
8020: 45 5f 42 55 53 59 2e 3c 2f 70 3e 0a 0a 3c 70 3e E_BUSY.</p>..<p>
8030: 54 68 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f The arguments to
8040: 20 3c 62 3e 73 71 6c 69 74 65 5f 62 75 73 79 5f <b>sqlite_busy_
8050: 68 61 6e 64 6c 65 72 3c 2f 62 3e 20 61 72 65 20 handler</b> are
8060: 74 68 65 20 6f 70 61 71 75 65 0a 73 74 72 75 63 the opaque.struc
8070: 74 75 72 65 20 72 65 74 75 72 6e 65 64 20 66 72 ture returned fr
8080: 6f 6d 20 3c 62 3e 73 71 6c 69 74 65 5f 6f 70 65 om <b>sqlite_ope
8090: 6e 3c 2f 62 3e 2c 20 61 20 70 6f 69 6e 74 65 72 n</b>, a pointer
80a0: 20 74 6f 20 74 68 65 20 62 75 73 79 0a 63 61 6c to the busy.cal
80b0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2c 20 lback function,
80c0: 61 6e 64 20 61 20 67 65 6e 65 72 69 63 20 70 6f and a generic po
80d0: 69 6e 74 65 72 20 74 68 61 74 20 77 69 6c 6c 20 inter that will
80e0: 62 65 20 70 61 73 73 65 64 20 61 73 0a 74 68 65 be passed as.the
80f0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
8100: 74 6f 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c to the busy call
8110: 62 61 63 6b 2e 20 20 57 68 65 6e 20 53 51 4c 69 back. When SQLi
8120: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 0a 62 te invokes the.b
8130: 75 73 79 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 usy callback, it
8140: 20 73 65 6e 64 73 20 69 74 20 74 68 72 65 65 20 sends it three
8150: 61 72 67 75 6d 65 6e 74 73 3a 20 20 74 68 65 20 arguments: the
8160: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 0a generic pointer.
8170: 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20 that was passed
8180: 69 6e 20 61 73 20 74 68 65 20 74 68 69 72 64 20 in as the third
8190: 61 72 67 75 6d 65 6e 74 20 74 6f 20 3c 62 3e 73 argument to <b>s
81a0: 71 6c 69 74 65 5f 62 75 73 79 5f 68 61 6e 64 6c qlite_busy_handl
81b0: 65 72 3c 2f 62 3e 2c 0a 74 68 65 20 6e 61 6d 65 er</b>,.the name
81c0: 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
81d0: 20 74 61 62 6c 65 20 6f 72 20 69 6e 64 65 78 20 table or index
81e0: 74 68 61 74 20 74 68 65 20 6c 69 62 72 61 72 79 that the library
81f0: 20 69 73 20 74 72 79 69 6e 67 0a 74 6f 20 61 63 is trying.to ac
8200: 63 65 73 73 2c 20 61 6e 64 20 74 68 65 20 6e 75 cess, and the nu
8210: 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 mber of times th
8220: 61 74 20 74 68 65 20 6c 69 62 72 61 72 79 20 68 at the library h
8230: 61 73 20 61 74 74 65 6d 70 74 65 64 20 74 6f 0a as attempted to.
8240: 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 access the datab
8250: 61 73 65 20 74 61 62 6c 65 20 6f 72 20 69 6e 64 ase table or ind
8260: 65 78 2e 3c 2f 70 3e 0a 0a 3c 70 3e 46 6f 72 20 ex.</p>..<p>For
8270: 74 68 65 20 63 6f 6d 6d 6f 6e 20 63 61 73 65 20 the common case
8280: 77 68 65 72 65 20 77 65 20 77 61 6e 74 20 74 68 where we want th
8290: 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 e busy callback
82a0: 74 6f 20 73 6c 65 65 70 2c 0a 74 68 65 20 53 51 to sleep,.the SQ
82b0: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 70 72 6f Lite library pro
82c0: 76 69 64 65 73 20 61 20 63 6f 6e 76 65 6e 69 65 vides a convenie
82d0: 6e 63 65 20 72 6f 75 74 69 6e 65 20 3c 62 3e 73 nce routine <b>s
82e0: 71 6c 69 74 65 5f 62 75 73 79 5f 74 69 6d 65 6f qlite_busy_timeo
82f0: 75 74 3c 2f 62 3e 2e 0a 54 68 65 20 66 69 72 73 ut</b>..The firs
8300: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 3c 62 t argument to <b
8310: 3e 73 71 6c 69 74 65 5f 62 75 73 79 5f 74 69 6d >sqlite_busy_tim
8320: 65 6f 75 74 3c 2f 62 3e 20 69 73 20 61 20 70 6f eout</b> is a po
8330: 69 6e 74 65 72 20 74 6f 0a 61 6e 20 6f 70 65 6e inter to.an open
8340: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 SQLite database
8350: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 and the second
8360: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 6e 75 argument is a nu
8370: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 mber of millisec
8380: 6f 6e 64 73 2e 0a 41 66 74 65 72 20 3c 62 3e 73 onds..After <b>s
8390: 71 6c 69 74 65 5f 62 75 73 79 5f 74 69 6d 65 6f qlite_busy_timeo
83a0: 75 74 3c 2f 62 3e 20 68 61 73 20 62 65 65 6e 20 ut</b> has been
83b0: 65 78 65 63 75 74 65 64 2c 20 74 68 65 20 53 51 executed, the SQ
83c0: 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 77 69 6c Lite library.wil
83d0: 6c 20 77 61 69 74 20 66 6f 72 20 74 68 65 20 6c l wait for the l
83e0: 6f 63 6b 20 74 6f 20 63 6c 65 61 72 20 66 6f 72 ock to clear for
83f0: 20 61 74 20 6c 65 61 73 74 20 74 68 65 20 6e 75 at least the nu
8400: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 mber of millisec
8410: 6f 6e 64 73 20 0a 73 70 65 63 69 66 69 65 64 20 onds .specified
8420: 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e before it return
8430: 73 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 s SQLITE_BUSY.
8440: 53 70 65 63 69 66 79 69 6e 67 20 7a 65 72 6f 20 Specifying zero
8450: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 66 6f 72 milliseconds for
8460: 0a 74 68 65 20 74 69 6d 65 6f 75 74 20 72 65 73 .the timeout res
8470: 74 6f 72 65 73 20 74 68 65 20 64 65 66 61 75 6c tores the defaul
8480: 74 20 62 65 68 61 76 69 6f 72 2e 3c 2f 70 3e 0a t behavior.</p>.
8490: 0a 3c 68 34 3e 33 2e 39 20 55 73 69 6e 67 20 74 .<h4>3.9 Using t
84a0: 68 65 20 3c 74 74 3e 5f 70 72 69 6e 74 66 28 29 he <tt>_printf()
84b0: 3c 2f 74 74 3e 20 77 72 61 70 70 65 72 20 66 75 </tt> wrapper fu
84c0: 6e 63 74 69 6f 6e 73 3c 2f 68 34 3e 0a 0a 3c 70 nctions</h4>..<p
84d0: 3e 54 68 65 20 66 6f 75 72 20 75 74 69 6c 69 74 >The four utilit
84e0: 79 20 66 75 6e 63 74 69 6f 6e 73 3c 2f 70 3e 0a y functions</p>.
84f0: 0a 3c 70 3e 0a 3c 75 6c 3e 0a 3c 6c 69 3e 3c 62 .<p>.<ul>.<li><b
8500: 3e 73 71 6c 69 74 65 5f 65 78 65 63 5f 70 72 69 >sqlite_exec_pri
8510: 6e 74 66 28 29 3c 2f 62 3e 3c 2f 6c 69 3e 0a 3c ntf()</b></li>.<
8520: 6c 69 3e 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 li><b>sqlite_exe
8530: 63 5f 76 70 72 69 6e 74 66 28 29 3c 2f 62 3e 3c c_vprintf()</b><
8540: 2f 6c 69 3e 0a 3c 6c 69 3e 3c 62 3e 73 71 6c 69 /li>.<li><b>sqli
8550: 74 65 5f 67 65 74 5f 74 61 62 6c 65 5f 70 72 69 te_get_table_pri
8560: 6e 74 66 28 29 3c 2f 62 3e 3c 2f 6c 69 3e 0a 3c ntf()</b></li>.<
8570: 6c 69 3e 3c 62 3e 73 71 6c 69 74 65 5f 67 65 74 li><b>sqlite_get
8580: 5f 74 61 62 6c 65 5f 76 70 72 69 6e 74 66 28 29 _table_vprintf()
8590: 3c 2f 62 3e 3c 2f 6c 69 3e 0a 3c 2f 75 6c 3e 0a </b></li>.</ul>.
85a0: 3c 2f 70 3e 0a 0a 3c 70 3e 69 6d 70 6c 65 6d 65 </p>..<p>impleme
85b0: 6e 74 20 74 68 65 20 73 61 6d 65 20 71 75 65 72 nt the same quer
85c0: 79 20 66 75 6e 63 74 69 6f 6e 61 6c 69 74 79 20 y functionality
85d0: 61 73 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 as <b>sqlite_exe
85e0: 63 3c 2f 62 3e 0a 61 6e 64 20 3c 62 3e 73 71 6c c</b>.and <b>sql
85f0: 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 3c 2f 62 ite_get_table</b
8600: 3e 2e 20 20 42 75 74 20 69 6e 73 74 65 61 64 20 >. But instead
8610: 6f 66 20 74 61 6b 69 6e 67 20 61 20 63 6f 6d 70 of taking a comp
8620: 6c 65 74 65 0a 53 51 4c 20 73 74 61 74 65 6d 65 lete.SQL stateme
8630: 6e 74 20 61 73 20 74 68 65 69 72 20 73 65 63 6f nt as their seco
8640: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 65 nd argument, the
8650: 20 66 6f 75 72 20 3c 62 3e 5f 70 72 69 6e 74 66 four <b>_printf
8660: 3c 2f 62 3e 0a 72 6f 75 74 69 6e 65 73 20 74 61 </b>.routines ta
8670: 6b 65 20 61 20 70 72 69 6e 74 66 2d 73 74 79 6c ke a printf-styl
8680: 65 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 2e e format string.
8690: 20 20 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d The SQL statem
86a0: 65 6e 74 20 74 6f 0a 62 65 20 65 78 65 63 75 74 ent to.be execut
86b0: 65 64 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 ed is generated
86c0: 66 72 6f 6d 20 74 68 69 73 20 66 6f 72 6d 61 74 from this format
86d0: 20 73 74 72 69 6e 67 20 61 6e 64 20 66 72 6f 6d string and from
86e0: 20 77 68 61 74 65 76 65 72 0a 61 64 64 69 74 69 whatever.additi
86f0: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 61 onal arguments a
8700: 72 65 20 61 74 74 61 63 68 65 64 20 74 6f 20 74 re attached to t
8710: 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75 he end of the fu
8720: 6e 63 74 69 6f 6e 20 63 61 6c 6c 2e 3c 2f 70 3e nction call.</p>
8730: 0a 0a 3c 70 3e 54 68 65 72 65 20 61 72 65 20 74 ..<p>There are t
8740: 77 6f 20 61 64 76 61 6e 74 61 67 65 73 20 74 6f wo advantages to
8750: 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 69 74 using the SQLit
8760: 65 20 70 72 69 6e 74 66 0a 66 75 6e 63 74 69 6f e printf.functio
8770: 6e 73 20 69 6e 73 74 65 61 64 20 6f 66 20 3c 62 ns instead of <b
8780: 3e 73 70 72 69 6e 74 66 3c 2f 62 3e 2e 20 20 46 >sprintf</b>. F
8790: 69 72 73 74 20 6f 66 20 61 6c 6c 2c 20 77 69 74 irst of all, wit
87a0: 68 20 74 68 65 0a 53 51 4c 69 74 65 20 70 72 69 h the.SQLite pri
87b0: 6e 74 66 20 72 6f 75 74 69 6e 65 73 2c 20 74 68 ntf routines, th
87c0: 65 72 65 20 69 73 20 6e 65 76 65 72 20 61 20 64 ere is never a d
87d0: 61 6e 67 65 72 20 6f 66 20 6f 76 65 72 66 6c 6f anger of overflo
87e0: 77 69 6e 67 20 61 0a 73 74 61 74 69 63 20 62 75 wing a.static bu
87f0: 66 66 65 72 20 61 73 20 74 68 65 72 65 20 69 73 ffer as there is
8800: 20 77 69 74 68 20 3c 62 3e 73 70 72 69 6e 74 66 with <b>sprintf
8810: 3c 2f 62 3e 2e 20 20 54 68 65 20 53 51 4c 69 74 </b>. The SQLit
8820: 65 0a 70 72 69 6e 74 66 20 72 6f 75 74 69 6e 65 e.printf routine
8830: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 s automatically
8840: 61 6c 6c 6f 63 61 74 65 20 28 61 6e 64 20 6c 61 allocate (and la
8850: 74 65 72 20 66 72 65 65 73 29 0a 61 73 20 6d 75 ter frees).as mu
8860: 63 68 20 6d 65 6d 6f 72 79 20 61 73 20 69 73 20 ch memory as is
8870: 0a 6e 65 63 65 73 73 61 72 79 20 74 6f 20 68 6f .necessary to ho
8880: 6c 64 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 ld the SQL state
8890: 6d 65 6e 74 73 20 67 65 6e 65 72 61 74 65 64 2e ments generated.
88a0: 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 73 65 63 </p>..<p>The sec
88b0: 6f 6e 64 20 61 64 76 61 6e 74 61 67 65 20 74 68 ond advantage th
88c0: 65 20 53 51 4c 69 74 65 20 70 72 69 6e 74 66 20 e SQLite printf
88d0: 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 6f 76 routines have ov
88e0: 65 72 0a 3c 62 3e 73 70 72 69 6e 74 66 3c 2f 62 er.<b>sprintf</b
88f0: 3e 20 61 72 65 20 74 77 6f 20 6e 65 77 20 66 6f > are two new fo
8900: 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 rmatting options
8910: 20 73 70 65 63 69 66 69 63 61 6c 6c 79 20 64 65 specifically de
8920: 73 69 67 6e 65 64 0a 74 6f 20 73 75 70 70 6f 72 signed.to suppor
8930: 74 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c t string literal
8940: 73 20 69 6e 20 53 51 4c 2e 20 20 57 69 74 68 69 s in SQL. Withi
8950: 6e 20 74 68 65 20 66 6f 72 6d 61 74 20 73 74 72 n the format str
8960: 69 6e 67 2c 0a 74 68 65 20 25 71 20 66 6f 72 6d ing,.the %q form
8970: 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f atting option wo
8980: 72 6b 73 20 76 65 72 79 20 6d 75 63 68 20 6c 69 rks very much li
8990: 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 ke %s in that it
89a0: 0a 72 65 61 64 73 20 61 20 6e 75 6c 6c 2d 74 65 .reads a null-te
89b0: 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 rminated string
89c0: 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e from the argumen
89d0: 74 20 6c 69 73 74 20 61 6e 64 20 69 6e 73 65 72 t list and inser
89e0: 74 73 0a 69 74 20 69 6e 74 6f 20 74 68 65 20 72 ts.it into the r
89f0: 65 73 75 6c 74 2e 20 20 42 75 74 20 25 71 20 74 esult. But %q t
8a00: 72 61 6e 73 6c 61 74 65 73 20 74 68 65 20 69 6e ranslates the in
8a10: 73 65 72 74 65 64 20 73 74 72 69 6e 67 20 62 79 serted string by
8a20: 0a 6d 61 6b 69 6e 67 20 74 77 6f 20 63 6f 70 69 .making two copi
8a30: 65 73 20 6f 66 20 65 76 65 72 79 20 73 69 6e 67 es of every sing
8a40: 6c 65 2d 71 75 6f 74 65 20 28 27 29 20 63 68 61 le-quote (') cha
8a50: 72 61 63 74 65 72 20 69 6e 20 74 68 65 0a 73 75 racter in the.su
8a60: 62 73 74 69 74 75 74 65 64 20 73 74 72 69 6e 67 bstituted string
8a70: 2e 20 20 54 68 69 73 20 68 61 73 20 74 68 65 20 . This has the
8a80: 65 66 66 65 63 74 20 6f 66 20 65 73 63 61 70 69 effect of escapi
8a90: 6e 67 20 74 68 65 20 65 6e 64 2d 6f 66 2d 73 74 ng the end-of-st
8aa0: 72 69 6e 67 0a 6d 65 61 6e 69 6e 67 20 6f 66 20 ring.meaning of
8ab0: 73 69 6e 67 6c 65 2d 71 75 6f 74 65 20 77 69 74 single-quote wit
8ac0: 68 69 6e 20 61 20 73 74 72 69 6e 67 20 6c 69 74 hin a string lit
8ad0: 65 72 61 6c 2e 20 54 68 65 20 25 51 20 66 6f 72 eral. The %Q for
8ae0: 6d 61 74 74 69 6e 67 0a 6f 70 74 69 6f 6e 20 77 matting.option w
8af0: 6f 72 6b 73 20 73 69 6d 69 6c 61 72 3b 20 69 74 orks similar; it
8b00: 20 74 72 61 6e 73 6c 61 74 65 73 20 74 68 65 20 translates the
8b10: 73 69 6e 67 6c 65 2d 71 75 6f 74 65 73 20 6c 69 single-quotes li
8b20: 6b 65 20 25 71 20 61 6e 64 0a 61 64 64 69 74 69 ke %q and.additi
8b30: 6f 6e 61 6c 6c 79 20 65 6e 63 6c 6f 73 65 73 20 onally encloses
8b40: 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 the resulting st
8b50: 72 69 6e 67 20 69 6e 20 73 69 6e 67 6c 65 2d 71 ring in single-q
8b60: 75 6f 74 65 73 2e 0a 49 66 20 74 68 65 20 61 72 uotes..If the ar
8b70: 67 75 6d 65 6e 74 20 66 6f 72 20 74 68 65 20 25 gument for the %
8b80: 51 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 Q formatting opt
8b90: 69 6f 6e 73 20 69 73 20 61 20 4e 55 4c 4c 20 70 ions is a NULL p
8ba0: 6f 69 6e 74 65 72 2c 0a 74 68 65 20 72 65 73 75 ointer,.the resu
8bb0: 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 69 73 20 lting string is
8bc0: 4e 55 4c 4c 20 77 69 74 68 6f 75 74 20 73 69 6e NULL without sin
8bd0: 67 6c 65 20 71 75 6f 74 65 73 2e 0a 3c 2f 70 3e gle quotes..</p>
8be0: 0a 0a 3c 70 3e 43 6f 6e 73 69 64 65 72 20 61 6e ..<p>Consider an
8bf0: 20 65 78 61 6d 70 6c 65 2e 20 20 53 75 70 70 6f example. Suppo
8c00: 73 65 20 79 6f 75 20 61 72 65 20 74 72 79 69 6e se you are tryin
8c10: 67 20 74 6f 20 69 6e 73 65 72 74 20 61 20 73 74 g to insert a st
8c20: 72 69 6e 67 0a 76 61 6c 75 65 20 69 6e 74 6f 20 ring.value into
8c30: 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
8c40: 20 77 68 65 72 65 20 74 68 65 20 73 74 72 69 6e where the strin
8c50: 67 20 76 61 6c 75 65 20 77 61 73 20 6f 62 74 61 g value was obta
8c60: 69 6e 65 64 20 66 72 6f 6d 0a 75 73 65 72 20 69 ined from.user i
8c70: 6e 70 75 74 2e 20 20 53 75 70 70 6f 73 65 20 74 nput. Suppose t
8c80: 68 65 20 73 74 72 69 6e 67 20 74 6f 20 62 65 20 he string to be
8c90: 69 6e 73 65 72 74 65 64 20 69 73 20 73 74 6f 72 inserted is stor
8ca0: 65 64 20 69 6e 20 61 20 76 61 72 69 61 62 6c 65 ed in a variable
8cb0: 0a 6e 61 6d 65 64 20 7a 53 74 72 69 6e 67 2e 20 .named zString.
8cc0: 20 54 68 65 20 63 6f 64 65 20 74 6f 20 64 6f 20 The code to do
8cd0: 74 68 65 20 69 6e 73 65 72 74 69 6f 6e 20 6d 69 the insertion mi
8ce0: 67 68 74 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 ght look like th
8cf0: 69 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 is:</p>..<blockq
8d00: 75 6f 74 65 3e 3c 70 72 65 3e 0a 73 71 6c 69 74 uote><pre>.sqlit
8d10: 65 5f 65 78 65 63 5f 70 72 69 6e 74 66 28 64 62 e_exec_printf(db
8d20: 2c 0a 20 20 22 49 4e 53 45 52 54 20 49 4e 54 4f ,. "INSERT INTO
8d30: 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 table1 VALUES('
8d40: 25 73 27 29 22 2c 0a 20 20 30 2c 20 30 2c 20 30 %s')",. 0, 0, 0
8d50: 2c 20 7a 53 74 72 69 6e 67 29 3b 0a 3c 2f 70 72 , zString);.</pr
8d60: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
8d70: 0a 3c 70 3e 49 66 20 74 68 65 20 7a 53 74 72 69 .<p>If the zStri
8d80: 6e 67 20 76 61 72 69 61 62 6c 65 20 68 6f 6c 64 ng variable hold
8d90: 73 20 74 65 78 74 20 6c 69 6b 65 20 22 48 65 6c s text like "Hel
8da0: 6c 6f 22 2c 20 74 68 65 6e 20 74 68 69 73 20 73 lo", then this s
8db0: 74 61 74 65 6d 65 6e 74 0a 77 69 6c 6c 20 77 6f tatement.will wo
8dc0: 72 6b 20 6a 75 73 74 20 66 69 6e 65 2e 20 20 42 rk just fine. B
8dd0: 75 74 20 73 75 70 70 6f 73 65 20 74 68 65 20 75 ut suppose the u
8de0: 73 65 72 20 65 6e 74 65 72 73 20 61 20 73 74 72 ser enters a str
8df0: 69 6e 67 20 6c 69 6b 65 20 0a 22 48 69 20 79 27 ing like ."Hi y'
8e00: 61 6c 6c 21 22 2e 20 20 54 68 65 20 53 51 4c 20 all!". The SQL
8e10: 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 statement genera
8e20: 74 65 64 20 72 65 61 64 73 20 61 73 20 66 6f 6c ted reads as fol
8e30: 6c 6f 77 73 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f lows:..<blockquo
8e40: 74 65 3e 3c 70 72 65 3e 0a 49 4e 53 45 52 54 20 te><pre>.INSERT
8e50: 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 INTO table1 VALU
8e60: 45 53 28 27 48 69 20 79 27 61 6c 6c 27 29 0a 3c ES('Hi y'all').<
8e70: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
8e80: 65 3e 0a 0a 3c 70 3e 54 68 69 73 20 69 73 20 6e e>..<p>This is n
8e90: 6f 74 20 76 61 6c 69 64 20 53 51 4c 20 62 65 63 ot valid SQL bec
8ea0: 61 75 73 65 20 6f 66 20 74 68 65 20 61 70 6f 73 ause of the apos
8eb0: 74 72 6f 70 68 79 20 69 6e 20 74 68 65 20 77 6f trophy in the wo
8ec0: 72 64 20 22 79 27 61 6c 6c 22 2e 0a 42 75 74 20 rd "y'all"..But
8ed0: 69 66 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 if the %q format
8ee0: 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 75 ting option is u
8ef0: 73 65 64 20 69 6e 73 74 65 61 64 20 6f 66 20 25 sed instead of %
8f00: 73 2c 20 6c 69 6b 65 20 74 68 69 73 3a 3c 2f 70 s, like this:</p
8f10: 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c >..<blockquote><
8f20: 70 72 65 3e 0a 73 71 6c 69 74 65 5f 65 78 65 63 pre>.sqlite_exec
8f30: 5f 70 72 69 6e 74 66 28 64 62 2c 0a 20 20 22 49 _printf(db,. "I
8f40: 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 NSERT INTO table
8f50: 31 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 1 VALUES('%q')",
8f60: 0a 20 20 30 2c 20 30 2c 20 30 2c 20 7a 53 74 72 . 0, 0, 0, zStr
8f70: 69 6e 67 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c ing);.</pre></bl
8f80: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 ockquote>..<p>Th
8f90: 65 6e 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 en the generated
8fa0: 20 53 51 4c 20 77 69 6c 6c 20 6c 6f 6f 6b 20 6c SQL will look l
8fb0: 69 6b 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e ike the followin
8fc0: 67 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 g:</p>..<blockqu
8fd0: 6f 74 65 3e 3c 70 72 65 3e 0a 49 4e 53 45 52 54 ote><pre>.INSERT
8fe0: 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c INTO table1 VAL
8ff0: 55 45 53 28 27 48 69 20 79 27 27 61 6c 6c 27 29 UES('Hi y''all')
9000: 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 .</pre></blockqu
9010: 6f 74 65 3e 0a 0a 3c 70 3e 48 65 72 65 20 74 68 ote>..<p>Here th
9020: 65 20 61 70 6f 73 74 72 6f 70 68 79 20 68 61 73 e apostrophy has
9030: 20 62 65 65 6e 20 65 73 63 61 70 65 64 20 61 6e been escaped an
9040: 64 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d d the SQL statem
9050: 65 6e 74 20 69 73 20 77 65 6c 6c 2d 66 6f 72 6d ent is well-form
9060: 65 64 2e 0a 57 68 65 6e 20 67 65 6e 65 72 61 74 ed..When generat
9070: 69 6e 67 20 53 51 4c 20 6f 6e 2d 74 68 65 2d 66 ing SQL on-the-f
9080: 6c 79 20 66 72 6f 6d 20 64 61 74 61 20 74 68 61 ly from data tha
9090: 74 20 6d 69 67 68 74 20 63 6f 6e 74 61 69 6e 20 t might contain
90a0: 61 0a 73 69 6e 67 6c 65 2d 71 75 6f 74 65 20 63 a.single-quote c
90b0: 68 61 72 61 63 74 65 72 20 28 27 29 2c 20 69 74 haracter ('), it
90c0: 20 69 73 20 61 6c 77 61 79 73 20 61 20 67 6f 6f is always a goo
90d0: 64 20 69 64 65 61 20 74 6f 20 75 73 65 20 74 68 d idea to use th
90e0: 65 0a 53 51 4c 69 74 65 20 70 72 69 6e 74 66 20 e.SQLite printf
90f0: 72 6f 75 74 69 6e 65 73 20 61 6e 64 20 74 68 65 routines and the
9100: 20 25 71 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f %q formatting o
9110: 70 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 ption instead of
9120: 20 3c 62 3e 73 70 72 69 6e 74 66 3c 2f 62 3e 2e <b>sprintf</b>.
9130: 0a 3c 2f 70 3e 0a 0a 3c 70 3e 49 66 20 74 68 65 .</p>..<p>If the
9140: 20 25 51 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f %Q formatting o
9150: 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 69 6e ption is used in
9160: 73 74 65 61 64 20 6f 66 20 25 71 2c 20 6c 69 6b stead of %q, lik
9170: 65 20 74 68 69 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c e this:</p>..<bl
9180: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 73 ockquote><pre>.s
9190: 71 6c 69 74 65 5f 65 78 65 63 5f 70 72 69 6e 74 qlite_exec_print
91a0: 66 28 64 62 2c 0a 20 20 22 49 4e 53 45 52 54 20 f(db,. "INSERT
91b0: 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 INTO table1 VALU
91c0: 45 53 28 25 51 29 22 2c 0a 20 20 30 2c 20 30 2c ES(%Q)",. 0, 0,
91d0: 20 30 2c 20 7a 53 74 72 69 6e 67 29 3b 0a 3c 2f 0, zString);.</
91e0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
91f0: 3e 0a 0a 3c 70 3e 54 68 65 6e 20 74 68 65 20 67 >..<p>Then the g
9200: 65 6e 65 72 61 74 65 64 20 53 51 4c 20 77 69 6c enerated SQL wil
9210: 6c 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 65 20 l look like the
9220: 66 6f 6c 6c 6f 77 69 6e 67 3a 3c 2f 70 3e 0a 0a following:</p>..
9230: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
9240: 3e 0a 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 >.INSERT INTO ta
9250: 62 6c 65 31 20 56 41 4c 55 45 53 28 27 48 69 20 ble1 VALUES('Hi
9260: 79 27 27 61 6c 6c 27 29 0a 3c 2f 70 72 65 3e 3c y''all').</pre><
9270: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 /blockquote>..<p
9280: 3e 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 >If the value of
9290: 20 74 68 65 20 7a 53 74 72 69 6e 67 20 76 61 72 the zString var
92a0: 69 61 62 6c 65 20 69 73 20 4e 55 4c 4c 2c 20 74 iable is NULL, t
92b0: 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c he generated SQL
92c0: 0a 77 69 6c 6c 20 6c 6f 6f 6b 20 6c 69 6b 65 20 .will look like
92d0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a 3c 2f the following:</
92e0: 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e p>..<blockquote>
92f0: 3c 70 72 65 3e 0a 49 4e 53 45 52 54 20 49 4e 54 <pre>.INSERT INT
9300: 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 O table1 VALUES(
9310: 4e 55 4c 4c 29 0a 3c 2f 70 72 65 3e 3c 2f 62 6c NULL).</pre></bl
9320: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 41 6c ockquote>..<p>Al
9330: 6c 20 6f 66 20 74 68 65 20 5f 70 72 69 6e 74 66 l of the _printf
9340: 28 29 20 72 6f 75 74 69 6e 65 73 20 61 62 6f 76 () routines abov
9350: 65 20 61 72 65 20 62 75 69 6c 74 20 61 72 6f 75 e are built arou
9360: 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 nd the following
9370: 0a 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 3a 3c .two functions:<
9380: 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 /p>..<blockquote
9390: 3e 3c 70 72 65 3e 0a 63 68 61 72 20 2a 73 71 6c ><pre>.char *sql
93a0: 69 74 65 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 ite_mprintf(cons
93b0: 74 20 63 68 61 72 20 2a 7a 46 6f 72 6d 61 74 2c t char *zFormat,
93c0: 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c ...);.char *sql
93d0: 69 74 65 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e ite_vmprintf(con
93e0: 73 74 20 63 68 61 72 20 2a 7a 46 6f 72 6d 61 74 st char *zFormat
93f0: 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 3c 2f 70 72 , va_list);.</pr
9400: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
9410: 0a 3c 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69 74 .<p>The <b>sqlit
9420: 65 5f 6d 70 72 69 6e 74 66 28 29 3c 2f 62 3e 20 e_mprintf()</b>
9430: 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6c 69 routine works li
9440: 6b 65 20 74 68 65 20 74 68 65 20 73 74 61 6e 64 ke the the stand
9450: 61 72 64 20 6c 69 62 72 61 72 79 0a 3c 62 3e 73 ard library.<b>s
9460: 70 72 69 6e 74 66 28 29 3c 2f 62 3e 20 65 78 63 printf()</b> exc
9470: 65 70 74 20 74 68 61 74 20 69 74 20 77 72 69 74 ept that it writ
9480: 65 73 20 69 74 73 20 72 65 73 75 6c 74 73 20 69 es its results i
9490: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 nto memory obtai
94a0: 6e 65 64 0a 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 ned.from malloc(
94b0: 29 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 ) and returns a
94c0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d pointer to the m
94d0: 61 6c 6c 6f 63 65 64 20 62 75 66 66 65 72 2e 20 alloced buffer.
94e0: 20 0a 3c 62 3e 73 71 6c 69 74 65 5f 6d 70 72 69 .<b>sqlite_mpri
94f0: 6e 74 66 28 29 3c 2f 62 3e 20 61 6c 73 6f 20 75 ntf()</b> also u
9500: 6e 64 65 72 73 74 61 6e 64 73 20 74 68 65 20 25 nderstands the %
9510: 71 20 61 6e 64 20 25 51 20 65 78 74 65 6e 73 69 q and %Q extensi
9520: 6f 6e 73 20 64 65 73 63 72 69 62 65 64 0a 61 62 ons described.ab
9530: 6f 76 65 2e 20 20 54 68 65 20 3c 62 3e 73 71 6c ove. The <b>sql
9540: 69 74 65 5f 76 6d 70 72 69 6e 74 66 28 29 3c 2f ite_vmprintf()</
9550: 62 3e 20 69 73 20 61 20 76 61 72 61 72 67 73 20 b> is a varargs
9560: 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 version of the s
9570: 61 6d 65 0a 72 6f 75 74 69 6e 65 2e 20 20 54 68 ame.routine. Th
9580: 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 e string pointer
9590: 20 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 that these rout
95a0: 69 6e 65 73 20 72 65 74 75 72 6e 20 73 68 6f 75 ines return shou
95b0: 6c 64 20 62 65 20 66 72 65 65 64 0a 62 79 20 70 ld be freed.by p
95c0: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 3c 62 3e assing it to <b>
95d0: 73 71 6c 69 74 65 5f 66 72 65 65 6d 65 6d 28 29 sqlite_freemem()
95e0: 3c 2f 62 3e 2e 0a 3c 2f 70 3e 0a 0a 3c 68 34 3e </b>..</p>..<h4>
95f0: 33 2e 31 30 20 50 65 72 66 6f 72 6d 69 6e 67 20 3.10 Performing
9600: 62 61 63 6b 67 72 6f 75 6e 64 20 6a 6f 62 73 20 background jobs
9610: 64 75 72 69 6e 67 20 6c 61 72 67 65 20 71 75 65 during large que
9620: 72 69 65 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 68 ries</h3>..<p>Th
9630: 65 20 3c 62 3e 73 71 6c 69 74 65 5f 70 72 6f 67 e <b>sqlite_prog
9640: 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 3c 2f ress_handler()</
9650: 62 3e 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 b> routine can b
9660: 65 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 e used to regist
9670: 65 72 20 61 0a 63 61 6c 6c 62 61 63 6b 20 72 6f er a.callback ro
9680: 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 53 51 utine with an SQ
9690: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 74 6f Lite database to
96a0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 be invoked peri
96b0: 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 odically during
96c0: 6c 6f 6e 67 0a 72 75 6e 6e 69 6e 67 20 63 61 6c long.running cal
96d0: 6c 73 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f ls to <b>sqlite_
96e0: 65 78 65 63 28 29 3c 2f 62 3e 2c 20 3c 62 3e 73 exec()</b>, <b>s
96f0: 71 6c 69 74 65 5f 73 74 65 70 28 29 3c 2f 62 3e qlite_step()</b>
9700: 20 61 6e 64 20 74 68 65 20 76 61 72 69 6f 75 73 and the various
9710: 0a 77 72 61 70 70 65 72 20 66 75 6e 63 74 69 6f .wrapper functio
9720: 6e 73 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 ns..</p>..<p>The
9730: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
9740: 6f 6b 65 64 20 65 76 65 72 79 20 4e 20 76 69 72 oked every N vir
9750: 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 6f 70 65 tual machine ope
9760: 72 61 74 69 6f 6e 73 2c 20 77 68 65 72 65 20 4e rations, where N
9770: 20 69 73 0a 73 75 70 70 6c 69 65 64 20 61 73 20 is.supplied as
9780: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
9790: 65 6e 74 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65 ent to <b>sqlite
97a0: 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 _progress_handle
97b0: 72 28 29 3c 2f 62 3e 2e 20 54 68 65 20 74 68 69 r()</b>. The thi
97c0: 72 64 0a 61 6e 64 20 66 6f 75 72 74 68 20 61 72 rd.and fourth ar
97d0: 67 75 6d 65 6e 74 73 20 74 6f 20 3c 62 3e 73 71 guments to <b>sq
97e0: 6c 69 74 65 5f 70 72 6f 67 72 65 73 73 5f 68 61 lite_progress_ha
97f0: 6e 64 6c 65 72 28 29 3c 2f 62 3e 20 61 72 65 20 ndler()</b> are
9800: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
9810: 0a 72 6f 75 74 69 6e 65 20 74 6f 20 62 65 20 69 .routine to be i
9820: 6e 76 6f 6b 65 64 20 61 6e 64 20 61 20 76 6f 69 nvoked and a voi
9830: 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 62 65 20 d pointer to be
9840: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
9850: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a rst argument to.
9860: 69 74 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 it..</p>..<p>The
9870: 20 74 69 6d 65 20 74 61 6b 65 6e 20 74 6f 20 65 time taken to e
9880: 78 65 63 75 74 65 20 65 61 63 68 20 76 69 72 74 xecute each virt
9890: 75 61 6c 20 6d 61 63 68 69 6e 65 20 6f 70 65 72 ual machine oper
98a0: 61 74 69 6f 6e 20 63 61 6e 20 76 61 72 79 20 62 ation can vary b
98b0: 61 73 65 64 20 6f 6e 0a 6d 61 6e 79 20 66 61 63 ased on.many fac
98c0: 74 6f 72 73 2e 20 20 41 20 74 79 70 69 63 61 6c tors. A typical
98d0: 20 76 61 6c 75 65 20 66 6f 72 20 61 20 31 20 47 value for a 1 G
98e0: 48 7a 20 50 43 20 69 73 20 62 65 74 77 65 65 6e Hz PC is between
98f0: 20 68 61 6c 66 20 61 6e 64 20 74 68 72 65 65 20 half and three
9900: 6d 69 6c 6c 69 6f 6e 0a 70 65 72 20 73 65 63 6f million.per seco
9910: 6e 64 20 62 75 74 20 6d 61 79 20 62 65 20 6d 75 nd but may be mu
9920: 63 68 20 68 69 67 68 65 72 20 6f 72 20 6c 6f 77 ch higher or low
9930: 65 72 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e er, depending on
9940: 20 74 68 65 20 71 75 65 72 79 2e 20 20 41 73 20 the query. As
9950: 73 75 63 68 20 69 74 0a 69 73 20 64 69 66 66 69 such it.is diffi
9960: 63 75 6c 74 20 74 6f 20 73 63 68 65 64 75 6c 65 cult to schedule
9970: 20 62 61 63 6b 67 72 6f 75 6e 64 20 6f 70 65 72 background oper
9980: 61 74 69 6f 6e 73 20 62 61 73 65 64 20 6f 6e 20 ations based on
9990: 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 0a virtual machine.
99a0: 6f 70 65 72 61 74 69 6f 6e 73 2e 20 49 6e 73 74 operations. Inst
99b0: 65 61 64 2c 20 69 74 20 69 73 20 72 65 63 6f 6d ead, it is recom
99c0: 6d 65 6e 64 65 64 20 74 68 61 74 20 61 20 63 61 mended that a ca
99d0: 6c 6c 62 61 63 6b 20 62 65 20 73 63 68 65 64 75 llback be schedu
99e0: 6c 65 64 20 72 65 6c 61 74 69 76 65 6c 79 0a 66 led relatively.f
99f0: 72 65 71 75 65 6e 74 6c 79 20 28 73 61 79 20 65 requently (say e
9a00: 76 65 72 79 20 31 30 30 30 20 69 6e 73 74 72 75 very 1000 instru
9a10: 63 74 69 6f 6e 73 29 20 61 6e 64 20 65 78 74 65 ctions) and exte
9a20: 72 6e 61 6c 20 74 69 6d 65 72 20 72 6f 75 74 69 rnal timer routi
9a30: 6e 65 73 20 75 73 65 64 20 74 6f 0a 64 65 74 65 nes used to.dete
9a40: 72 6d 69 6e 65 20 77 68 65 74 68 65 72 20 6f 72 rmine whether or
9a50: 20 6e 6f 74 20 62 61 63 6b 67 72 6f 75 6e 64 20 not background
9a60: 6a 6f 62 73 20 6e 65 65 64 20 74 6f 20 62 65 20 jobs need to be
9a70: 72 75 6e 2e 20 20 0a 3c 2f 70 3e 0a 0a 3c 61 20 run. .</p>..<a
9a80: 6e 61 6d 65 3d 22 63 66 75 6e 63 22 3e 0a 3c 68 name="cfunc">.<h
9a90: 33 3e 34 2e 30 20 41 64 64 69 6e 67 20 4e 65 77 3>4.0 Adding New
9aa0: 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 3c 2f SQL Functions</
9ab0: 68 33 3e 0a 0a 3c 70 3e 42 65 67 69 6e 6e 69 6e h3>..<p>Beginnin
9ac0: 67 20 77 69 74 68 20 76 65 72 73 69 6f 6e 20 32 g with version 2
9ad0: 2e 34 2e 30 2c 20 53 51 4c 69 74 65 20 61 6c 6c .4.0, SQLite all
9ae0: 6f 77 73 20 74 68 65 20 53 51 4c 20 6c 61 6e 67 ows the SQL lang
9af0: 75 61 67 65 20 74 6f 20 62 65 0a 65 78 74 65 6e uage to be.exten
9b00: 64 65 64 20 77 69 74 68 20 6e 65 77 20 66 75 6e ded with new fun
9b10: 63 74 69 6f 6e 73 20 69 6d 70 6c 65 6d 65 6e 74 ctions implement
9b20: 65 64 20 61 73 20 43 20 63 6f 64 65 2e 20 20 54 ed as C code. T
9b30: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 he following int
9b40: 65 72 66 61 63 65 0a 69 73 20 75 73 65 64 3a 0a erface.is used:.
9b50: 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 </p>..<blockquot
9b60: 65 3e 3c 70 72 65 3e 0a 74 79 70 65 64 65 66 20 e><pre>.typedef
9b70: 73 74 72 75 63 74 20 73 71 6c 69 74 65 5f 66 75 struct sqlite_fu
9b80: 6e 63 20 73 71 6c 69 74 65 5f 66 75 6e 63 3b 0a nc sqlite_func;.
9b90: 0a 69 6e 74 20 73 71 6c 69 74 65 5f 63 72 65 61 .int sqlite_crea
9ba0: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 te_function(. s
9bb0: 71 6c 69 74 65 20 2a 64 62 2c 0a 20 20 63 6f 6e qlite *db,. con
9bc0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a st char *zName,.
9bd0: 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 76 6f int nArg,. vo
9be0: 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 id (*xFunc)(sqli
9bf0: 74 65 5f 66 75 6e 63 2a 2c 69 6e 74 2c 63 6f 6e te_func*,int,con
9c00: 73 74 20 63 68 61 72 2a 2a 29 2c 0a 20 20 76 6f st char**),. vo
9c10: 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b id *pUserData.);
9c20: 0a 69 6e 74 20 73 71 6c 69 74 65 5f 63 72 65 61 .int sqlite_crea
9c30: 74 65 5f 61 67 67 72 65 67 61 74 65 28 0a 20 20 te_aggregate(.
9c40: 73 71 6c 69 74 65 20 2a 64 62 2c 0a 20 20 63 6f sqlite *db,. co
9c50: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
9c60: 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 76 . int nArg,. v
9c70: 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c oid (*xStep)(sql
9c80: 69 74 65 5f 66 75 6e 63 2a 2c 69 6e 74 2c 63 6f ite_func*,int,co
9c90: 6e 73 74 20 63 68 61 72 2a 2a 29 2c 0a 20 20 76 nst char**),. v
9ca0: 6f 69 64 20 28 2a 78 46 69 6e 61 6c 69 7a 65 29 oid (*xFinalize)
9cb0: 28 73 71 6c 69 74 65 5f 66 75 6e 63 2a 29 2c 0a (sqlite_func*),.
9cc0: 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 void *pUserDat
9cd0: 61 0a 29 3b 0a 0a 63 68 61 72 20 2a 73 71 6c 69 a.);..char *sqli
9ce0: 74 65 5f 73 65 74 5f 72 65 73 75 6c 74 5f 73 74 te_set_result_st
9cf0: 72 69 6e 67 28 73 71 6c 69 74 65 5f 66 75 6e 63 ring(sqlite_func
9d00: 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e *,const char*,in
9d10: 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 5f t);.void sqlite_
9d20: 73 65 74 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 set_result_int(s
9d30: 71 6c 69 74 65 5f 66 75 6e 63 2a 2c 69 6e 74 29 qlite_func*,int)
9d40: 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 5f 73 65 ;.void sqlite_se
9d50: 74 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 t_result_double(
9d60: 73 71 6c 69 74 65 5f 66 75 6e 63 2a 2c 64 6f 75 sqlite_func*,dou
9d70: 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 ble);.void sqlit
9d80: 65 5f 73 65 74 5f 72 65 73 75 6c 74 5f 65 72 72 e_set_result_err
9d90: 6f 72 28 73 71 6c 69 74 65 5f 66 75 6e 63 2a 2c or(sqlite_func*,
9da0: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 29 const char*,int)
9db0: 3b 0a 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 5f ;..void *sqlite_
9dc0: 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 user_data(sqlite
9dd0: 5f 66 75 6e 63 2a 29 3b 0a 76 6f 69 64 20 2a 73 _func*);.void *s
9de0: 71 6c 69 74 65 5f 61 67 67 72 65 67 61 74 65 5f qlite_aggregate_
9df0: 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 5f 66 context(sqlite_f
9e00: 75 6e 63 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 unc*, int nBytes
9e10: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 5f 61 67 );.int sqlite_ag
9e20: 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 gregate_count(sq
9e30: 6c 69 74 65 5f 66 75 6e 63 2a 29 3b 0a 3c 2f 70 lite_func*);.</p
9e40: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
9e50: 0a 0a 3c 70 3e 0a 54 68 65 20 3c 62 3e 73 71 6c ..<p>.The <b>sql
9e60: 69 74 65 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 ite_create_funct
9e70: 69 6f 6e 28 29 3c 2f 62 3e 20 69 6e 74 65 72 66 ion()</b> interf
9e80: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 ace is used to c
9e90: 72 65 61 74 65 20 0a 72 65 67 75 6c 61 72 20 66 reate .regular f
9ea0: 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 3c 62 3e unctions and <b>
9eb0: 73 71 6c 69 74 65 5f 63 72 65 61 74 65 5f 61 67 sqlite_create_ag
9ec0: 67 72 65 67 61 74 65 28 29 3c 2f 62 3e 20 69 73 gregate()</b> is
9ed0: 20 75 73 65 64 20 74 6f 0a 63 72 65 61 74 65 20 used to.create
9ee0: 6e 65 77 20 61 67 67 72 65 67 61 74 65 20 66 75 new aggregate fu
9ef0: 6e 63 74 69 6f 6e 73 2e 20 20 49 6e 20 62 6f 74 nctions. In bot
9f00: 68 20 63 61 73 65 73 2c 20 74 68 65 20 3c 62 3e h cases, the <b>
9f10: 64 62 3c 2f 62 3e 0a 70 61 72 61 6d 65 74 65 72 db</b>.parameter
9f20: 20 69 73 20 61 6e 20 6f 70 65 6e 20 53 51 4c 69 is an open SQLi
9f30: 74 65 20 64 61 74 61 62 61 73 65 20 6f 6e 20 77 te database on w
9f40: 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f hich the functio
9f50: 6e 73 20 73 68 6f 75 6c 64 0a 62 65 20 72 65 67 ns should.be reg
9f60: 69 73 74 65 72 65 64 2c 20 3c 62 3e 7a 4e 61 6d istered, <b>zNam
9f70: 65 3c 2f 62 3e 20 69 73 20 74 68 65 20 6e 61 6d e</b> is the nam
9f80: 65 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e e of the new fun
9f90: 63 74 69 6f 6e 2c 0a 3c 62 3e 6e 41 72 67 3c 2f ction,.<b>nArg</
9fa0: 62 3e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 b> is the number
9fb0: 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2c 20 61 of arguments, a
9fc0: 6e 64 20 3c 62 3e 70 55 73 65 72 44 61 74 61 3c nd <b>pUserData<
9fd0: 2f 62 3e 20 69 73 0a 61 20 70 6f 69 6e 74 65 72 /b> is.a pointer
9fe0: 20 77 68 69 63 68 20 69 73 20 70 61 73 73 65 64 which is passed
9ff0: 20 74 68 72 6f 75 67 68 20 75 6e 63 68 61 6e 67 through unchang
a000: 65 64 20 74 6f 20 74 68 65 20 43 20 69 6d 70 6c ed to the C impl
a010: 65 6d 65 6e 74 61 74 69 6f 6e 0a 6f 66 20 74 68 ementation.of th
a020: 65 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 6f 74 e function. Bot
a030: 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 h routines retur
a040: 6e 20 30 20 6f 6e 20 73 75 63 63 65 73 73 20 61 n 0 on success a
a050: 6e 64 20 6e 6f 6e 2d 7a 65 72 6f 0a 69 66 20 74 nd non-zero.if t
a060: 68 65 72 65 20 61 72 65 20 61 6e 79 20 65 72 72 here are any err
a070: 6f 72 73 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 ors..</p>..<p>.T
a080: 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 61 20 66 he length of a f
a090: 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 6d 61 79 unction name may
a0a0: 20 6e 6f 74 20 65 78 63 65 65 64 20 32 35 35 20 not exceed 255
a0b0: 63 68 61 72 61 63 74 65 72 73 2e 0a 41 6e 79 20 characters..Any
a0c0: 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 attempt to creat
a0d0: 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 6f e a function who
a0e0: 73 65 20 6e 61 6d 65 20 65 78 63 65 65 64 73 20 se name exceeds
a0f0: 32 35 35 20 63 68 61 72 61 63 74 65 72 73 0a 69 255 characters.i
a100: 6e 20 6c 65 6e 67 74 68 20 77 69 6c 6c 20 72 65 n length will re
a110: 73 75 6c 74 20 69 6e 20 61 6e 20 65 72 72 6f 72 sult in an error
a120: 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 46 6f 72 20 ..</p>..<p>.For
a130: 72 65 67 75 6c 61 72 20 66 75 6e 63 74 69 6f 6e regular function
a140: 73 2c 20 74 68 65 20 3c 62 3e 78 46 75 6e 63 3c s, the <b>xFunc<
a150: 2f 62 3e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 /b> callback is
a160: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 0a 66 6f 72 invoked once.for
a170: 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 63 each function c
a180: 61 6c 6c 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d all. The implem
a190: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 46 75 6e entation of xFun
a1a0: 63 20 73 68 6f 75 6c 64 20 63 61 6c 6c 0a 6f 6e c should call.on
a1b0: 65 20 6f 66 20 74 68 65 20 3c 62 3e 73 71 6c 69 e of the <b>sqli
a1c0: 74 65 5f 73 65 74 5f 72 65 73 75 6c 74 5f 2e 2e te_set_result_..
a1d0: 2e 3c 2f 62 3e 20 69 6e 74 65 72 66 61 63 65 73 .</b> interfaces
a1e0: 20 74 6f 20 72 65 74 75 72 6e 20 69 74 73 0a 72 to return its.r
a1f0: 65 73 75 6c 74 2e 20 20 54 68 65 20 3c 62 3e 73 esult. The <b>s
a200: 71 6c 69 74 65 5f 75 73 65 72 5f 64 61 74 61 28 qlite_user_data(
a210: 29 3c 2f 62 3e 20 72 6f 75 74 69 6e 65 20 63 61 )</b> routine ca
a220: 6e 20 62 65 20 75 73 65 64 20 74 6f 0a 72 65 74 n be used to.ret
a230: 72 69 65 76 65 20 74 68 65 20 3c 62 3e 70 55 73 rieve the <b>pUs
a240: 65 72 44 61 74 61 3c 2f 62 3e 20 70 6f 69 6e 74 erData</b> point
a250: 65 72 20 74 68 61 74 20 77 61 73 20 70 61 73 73 er that was pass
a260: 65 64 20 69 6e 20 77 68 65 6e 20 74 68 65 0a 66 ed in when the.f
a270: 75 6e 63 74 69 6f 6e 20 77 61 73 20 72 65 67 69 unction was regi
a280: 73 74 65 72 65 64 2e 0a 3c 2f 70 3e 0a 0a 3c 70 stered..</p>..<p
a290: 3e 0a 46 6f 72 20 61 67 67 72 65 67 61 74 65 20 >.For aggregate
a2a0: 66 75 6e 63 74 69 6f 6e 73 2c 20 74 68 65 20 3c functions, the <
a2b0: 62 3e 78 53 74 65 70 3c 2f 62 3e 20 63 61 6c 6c b>xStep</b> call
a2c0: 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
a2d0: 6f 6e 63 65 0a 66 6f 72 20 65 61 63 68 20 72 6f once.for each ro
a2e0: 77 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 w in the result
a2f0: 61 6e 64 20 74 68 65 6e 20 3c 62 3e 78 46 69 6e and then <b>xFin
a300: 61 6c 69 7a 65 3c 2f 62 3e 20 69 73 20 69 6e 76 alize</b> is inv
a310: 6f 6b 65 64 20 61 74 20 74 68 65 0a 65 6e 64 20 oked at the.end
a320: 74 6f 20 63 6f 6d 70 75 74 65 20 61 20 66 69 6e to compute a fin
a330: 61 6c 20 61 6e 73 77 65 72 2e 20 20 54 68 65 20 al answer. The
a340: 78 53 74 65 70 20 72 6f 75 74 69 6e 65 20 63 61 xStep routine ca
a350: 6e 20 75 73 65 20 74 68 65 0a 3c 62 3e 73 71 6c n use the.<b>sql
a360: 69 74 65 5f 61 67 67 72 65 67 61 74 65 5f 63 6f ite_aggregate_co
a370: 6e 74 65 78 74 28 29 3c 2f 62 3e 20 69 6e 74 65 ntext()</b> inte
a380: 72 66 61 63 65 20 74 6f 20 61 6c 6c 6f 63 61 74 rface to allocat
a390: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 0a 77 69 e memory that.wi
a3a0: 6c 6c 20 62 65 20 75 6e 69 71 75 65 20 74 6f 20 ll be unique to
a3b0: 74 68 61 74 20 70 61 72 74 69 63 75 6c 61 72 20 that particular
a3c0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
a3d0: 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 54 68 SQL function..Th
a3e0: 69 73 20 6d 65 6d 6f 72 79 20 77 69 6c 6c 20 62 is memory will b
a3f0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
a400: 64 65 6c 65 74 65 64 20 61 66 74 65 72 20 78 46 deleted after xF
a410: 69 6e 61 6c 69 7a 65 20 69 73 20 63 61 6c 6c 65 inalize is calle
a420: 64 2e 0a 54 68 65 20 3c 62 3e 73 71 6c 69 74 65 d..The <b>sqlite
a430: 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 _aggregate_count
a440: 28 29 3c 2f 62 3e 20 72 6f 75 74 69 6e 65 20 63 ()</b> routine c
a450: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 an be used to fi
a460: 6e 64 20 6f 75 74 0a 68 6f 77 20 6d 61 6e 79 20 nd out.how many
a470: 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 65 72 rows of data wer
a480: 65 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 e passed to the
a490: 61 67 67 72 65 67 61 74 65 2e 20 20 54 68 65 20 aggregate. The
a4a0: 78 46 69 6e 61 6c 69 7a 65 0a 63 61 6c 6c 62 61 xFinalize.callba
a4b0: 63 6b 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 ck should invoke
a4c0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 3c 62 3e 73 one of the <b>s
a4d0: 71 6c 69 74 65 5f 73 65 74 5f 72 65 73 75 6c 74 qlite_set_result
a4e0: 5f 2e 2e 2e 3c 2f 62 3e 0a 69 6e 74 65 72 66 61 _...</b>.interfa
a4f0: 63 65 73 20 74 6f 20 73 65 74 20 74 68 65 20 66 ces to set the f
a500: 69 6e 61 6c 20 72 65 73 75 6c 74 20 6f 66 20 74 inal result of t
a510: 68 65 20 61 67 67 72 65 67 61 74 65 2e 0a 3c 2f he aggregate..</
a520: 70 3e 0a 0a 3c 70 3e 0a 53 51 4c 69 74 65 20 6e p>..<p>.SQLite n
a530: 6f 77 20 69 6d 70 6c 65 6d 65 6e 74 73 20 61 6c ow implements al
a540: 6c 20 6f 66 20 69 74 73 20 62 75 69 6c 74 2d 69 l of its built-i
a550: 6e 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 69 6e n functions usin
a560: 67 20 74 68 69 73 0a 69 6e 74 65 72 66 61 63 65 g this.interface
a570: 2e 20 20 46 6f 72 20 61 64 64 69 74 69 6f 6e 61 . For additiona
a580: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 6e l information an
a590: 64 20 65 78 61 6d 70 6c 65 73 20 6f 6e 20 68 6f d examples on ho
a5a0: 77 20 74 6f 20 63 72 65 61 74 65 0a 6e 65 77 20 w to create.new
a5b0: 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 SQL functions, r
a5c0: 65 76 69 65 77 20 74 68 65 20 53 51 4c 69 74 65 eview the SQLite
a5d0: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 69 6e 20 source code in
a5e0: 74 68 65 20 66 69 6c 65 0a 3c 62 3e 66 75 6e 63 the file.<b>func
a5f0: 2e 63 3c 2f 62 3e 2e 0a 3c 2f 70 3e 0a 0a 3c 68 .c</b>..</p>..<h
a600: 33 3e 35 2e 30 20 4d 75 6c 74 69 2d 54 68 72 65 3>5.0 Multi-Thre
a610: 61 64 69 6e 67 20 41 6e 64 20 53 51 4c 69 74 65 ading And SQLite
a620: 3c 2f 68 33 3e 0a 0a 3c 70 3e 0a 49 66 20 53 51 </h3>..<p>.If SQ
a630: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
a640: 20 77 69 74 68 20 74 68 65 20 54 48 52 45 41 44 with the THREAD
a650: 53 41 46 45 20 70 72 65 70 72 6f 63 65 73 73 6f SAFE preprocesso
a660: 72 20 6d 61 63 72 6f 20 73 65 74 20 74 6f 20 31 r macro set to 1
a670: 2c 0a 74 68 65 6e 20 69 74 20 69 73 20 73 61 66 ,.then it is saf
a680: 65 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 e to use SQLite
a690: 66 72 6f 6d 20 74 77 6f 20 6f 72 20 6d 6f 72 65 from two or more
a6a0: 20 74 68 72 65 61 64 73 20 6f 66 20 74 68 65 20 threads of the
a6b0: 73 61 6d 65 20 70 72 6f 63 65 73 73 0a 61 74 20 same process.at
a6c0: 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 the same time.
a6d0: 42 75 74 20 65 61 63 68 20 74 68 72 65 61 64 20 But each thread
a6e0: 73 68 6f 75 6c 64 20 68 61 76 65 20 69 74 73 20 should have its
a6f0: 6f 77 6e 20 3c 62 3e 73 71 6c 69 74 65 2a 3c 2f own <b>sqlite*</
a700: 62 3e 0a 70 6f 69 6e 74 65 72 20 72 65 74 75 72 b>.pointer retur
a710: 6e 65 64 20 66 72 6f 6d 20 3c 62 3e 73 71 6c 69 ned from <b>sqli
a720: 74 65 5f 6f 70 65 6e 3c 2f 62 3e 2e 20 20 49 74 te_open</b>. It
a730: 20 69 73 20 6e 65 76 65 72 20 73 61 66 65 20 66 is never safe f
a740: 6f 72 20 74 77 6f 0a 6f 72 20 6d 6f 72 65 20 74 or two.or more t
a750: 68 72 65 61 64 73 20 74 6f 20 61 63 63 65 73 73 hreads to access
a760: 20 74 68 65 20 73 61 6d 65 20 3c 62 3e 73 71 6c the same <b>sql
a770: 69 74 65 2a 3c 2f 62 3e 20 70 6f 69 6e 74 65 72 ite*</b> pointer
a780: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
a790: 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49 6e 20 e..</p>..<p>.In
a7a0: 70 72 65 63 6f 6d 70 69 6c 65 64 20 53 51 4c 69 precompiled SQLi
a7b0: 74 65 20 6c 69 62 72 61 72 69 65 73 20 61 76 61 te libraries ava
a7c0: 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 77 65 ilable on the we
a7d0: 62 73 69 74 65 2c 20 74 68 65 20 55 6e 69 78 0a bsite, the Unix.
a7e0: 76 65 72 73 69 6f 6e 73 20 61 72 65 20 63 6f 6d versions are com
a7f0: 70 69 6c 65 64 20 77 69 74 68 20 54 48 52 45 41 piled with THREA
a800: 44 53 41 46 45 20 74 75 72 6e 65 64 20 6f 66 66 DSAFE turned off
a810: 20 62 75 74 20 74 68 65 20 77 69 6e 64 6f 77 73 but the windows
a820: 0a 76 65 72 73 69 6f 6e 73 20 61 72 65 20 63 6f .versions are co
a830: 6d 70 69 6c 65 64 20 77 69 74 68 20 54 48 52 45 mpiled with THRE
a840: 41 44 53 41 46 45 20 74 75 72 6e 65 64 20 6f 6e ADSAFE turned on
a850: 2e 20 20 49 66 20 79 6f 75 20 6e 65 65 64 20 73 . If you need s
a860: 6f 6d 65 74 68 69 6e 67 0a 64 69 66 66 65 72 65 omething.differe
a870: 6e 74 20 74 68 61 74 20 74 68 69 73 20 79 6f 75 nt that this you
a880: 20 77 69 6c 6c 20 68 61 76 65 20 74 6f 20 72 65 will have to re
a890: 63 6f 6d 70 69 6c 65 2e 0a 3c 2f 70 3e 0a 0a 3c compile..</p>..<
a8a0: 70 3e 0a 55 6e 64 65 72 20 55 6e 69 78 2c 20 61 p>.Under Unix, a
a8b0: 6e 20 3c 62 3e 73 71 6c 69 74 65 2a 3c 2f 62 3e n <b>sqlite*</b>
a8c0: 20 70 6f 69 6e 74 65 72 20 73 68 6f 75 6c 64 20 pointer should
a8d0: 6e 6f 74 20 62 65 20 63 61 72 72 69 65 64 20 61 not be carried a
a8e0: 63 72 6f 73 73 20 61 0a 3c 62 3e 66 6f 72 6b 28 cross a.<b>fork(
a8f0: 29 3c 2f 62 3e 20 73 79 73 74 65 6d 20 63 61 6c )</b> system cal
a900: 6c 20 69 6e 74 6f 20 74 68 65 20 63 68 69 6c 64 l into the child
a910: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 63 process. The c
a920: 68 69 6c 64 20 70 72 6f 63 65 73 73 0a 73 68 6f hild process.sho
a930: 75 6c 64 20 6f 70 65 6e 20 69 74 73 20 6f 77 6e uld open its own
a940: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 copy of the dat
a950: 61 62 61 73 65 20 61 66 74 65 72 20 74 68 65 20 abase after the
a960: 3c 62 3e 66 6f 72 6b 28 29 3c 2f 62 3e 2e 0a 3c <b>fork()</b>..<
a970: 2f 70 3e 0a 0a 3c 68 33 3e 36 2e 30 20 55 73 61 /p>..<h3>6.0 Usa
a980: 67 65 20 45 78 61 6d 70 6c 65 73 3c 2f 68 33 3e ge Examples</h3>
a990: 0a 0a 3c 70 3e 46 6f 72 20 65 78 61 6d 70 6c 65 ..<p>For example
a9a0: 73 20 6f 66 20 68 6f 77 20 74 68 65 20 53 51 4c s of how the SQL
a9b0: 69 74 65 20 43 2f 43 2b 2b 20 69 6e 74 65 72 66 ite C/C++ interf
a9c0: 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 2c ace can be used,
a9d0: 0a 72 65 66 65 72 20 74 6f 20 74 68 65 20 73 6f .refer to the so
a9e0: 75 72 63 65 20 63 6f 64 65 20 66 6f 72 20 74 68 urce code for th
a9f0: 65 20 3c 62 3e 73 71 6c 69 74 65 3c 2f 62 3e 20 e <b>sqlite</b>
aa00: 70 72 6f 67 72 61 6d 20 69 6e 20 74 68 65 0a 66 program in the.f
aa10: 69 6c 65 20 3c 62 3e 73 72 63 2f 73 68 65 6c 6c ile <b>src/shell
aa20: 2e 63 3c 2f 62 3e 20 6f 66 20 74 68 65 20 73 6f .c</b> of the so
aa30: 75 72 63 65 20 74 72 65 65 2e 0a 41 64 64 69 74 urce tree..Addit
aa40: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
aa50: 6e 20 61 62 6f 75 74 20 73 71 6c 69 74 65 20 69 n about sqlite i
aa60: 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 0a 3c s available at.<
aa70: 61 20 68 72 65 66 3d 22 73 71 6c 69 74 65 2e 68 a href="sqlite.h
aa80: 74 6d 6c 22 3e 73 71 6c 69 74 65 2e 68 74 6d 6c tml">sqlite.html
aa90: 3c 2f 61 3e 2e 0a 53 65 65 20 61 6c 73 6f 20 74 </a>..See also t
aaa0: 68 65 20 73 6f 75 72 63 65 73 20 74 6f 20 74 68 he sources to th
aab0: 65 20 54 63 6c 20 69 6e 74 65 72 66 61 63 65 20 e Tcl interface
aac0: 66 6f 72 20 53 51 4c 69 74 65 20 69 6e 0a 74 68 for SQLite in.th
aad0: 65 20 73 6f 75 72 63 65 20 66 69 6c 65 20 3c 62 e source file <b
aae0: 3e 73 72 63 2f 74 63 6c 73 71 6c 69 74 65 2e 63 >src/tclsqlite.c
aaf0: 3c 2f 62 3e 2e 3c 2f 70 3e 0a 7d 0a 66 6f 6f 74 </b>.</p>.}.foot
ab00: 65 72 20 24 72 63 73 69 64 0a er $rcsid.