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: 32 32 20 32 30 30 31 2f 31 32 2f 32 32 20 31 39 22 2001/12/22 19
0070: 3a 32 37 3a 34 31 20 64 72 68 20 45 78 70 20 24 :27:41 drh Exp $
0080: 7d 0a 0a 70 75 74 73 20 7b 3c 68 74 6d 6c 3e 0a }..puts {<html>.
0090: 3c 68 65 61 64 3e 0a 20 20 3c 74 69 74 6c 65 3e <head>. <title>
00a0: 54 68 65 20 43 20 6c 61 6e 67 75 61 67 65 20 69 The C language i
00b0: 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 nterface to the
00c0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 3c 2f SQLite library</
00d0: 74 69 74 6c 65 3e 0a 3c 2f 68 65 61 64 3e 0a 3c title>.</head>.<
00e0: 62 6f 64 79 20 62 67 63 6f 6c 6f 72 3d 77 68 69 body bgcolor=whi
00f0: 74 65 3e 0a 3c 68 31 20 61 6c 69 67 6e 3d 63 65 te>.<h1 align=ce
0100: 6e 74 65 72 3e 0a 54 68 65 20 43 20 6c 61 6e 67 nter>.The C lang
0110: 75 61 67 65 20 69 6e 74 65 72 66 61 63 65 20 74 uage interface t
0120: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 o the SQLite lib
0130: 72 61 72 79 0a 3c 2f 68 31 3e 7d 0a 70 75 74 73 rary.</h1>}.puts
0140: 20 22 3c 70 20 61 6c 69 67 6e 3d 63 65 6e 74 65 "<p align=cente
0150: 72 3e 0a 28 54 68 69 73 20 70 61 67 65 20 77 61 r>.(This page wa
0160: 73 20 6c 61 73 74 20 6d 6f 64 69 66 69 65 64 20 s last modified
0170: 6f 6e 20 5b 6c 72 61 6e 67 65 20 24 72 63 73 69 on [lrange $rcsi
0180: 64 20 33 20 34 5d 20 55 54 43 29 0a 3c 2f 70 3e d 3 4] UTC).</p>
0190: 22 0a 0a 70 75 74 73 20 7b 0a 3c 70 3e 54 68 65 "..puts {.<p>The
01a0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 SQLite library
01b0: 69 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 62 is designed to b
01c0: 65 20 76 65 72 79 20 65 61 73 79 20 74 6f 20 75 e very easy to u
01d0: 73 65 20 66 72 6f 6d 0a 61 20 43 20 6f 72 20 43 se from.a C or C
01e0: 2b 2b 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 69 ++ program. Thi
01f0: 73 20 64 6f 63 75 6d 65 6e 74 20 67 69 76 65 73 s document gives
0200: 20 61 6e 20 6f 76 65 72 76 69 65 77 20 6f 66 20 an overview of
0210: 74 68 65 20 43 2f 43 2b 2b 0a 70 72 6f 67 72 61 the C/C++.progra
0220: 6d 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 2e mming interface.
0230: 3c 2f 70 3e 0a 0a 3c 68 32 3e 54 68 65 20 43 6f </p>..<h2>The Co
0240: 72 65 20 41 50 49 3c 2f 68 32 3e 0a 0a 3c 70 3e re API</h2>..<p>
0250: 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f The interface to
0260: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
0270: 61 72 79 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 ary consists of
0280: 74 68 72 65 65 20 63 6f 72 65 20 66 75 6e 63 74 three core funct
0290: 69 6f 6e 73 2c 0a 6f 6e 65 20 6f 70 61 71 75 65 ions,.one opaque
02a0: 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 2c data structure,
02b0: 20 61 6e 64 20 73 6f 6d 65 20 63 6f 6e 73 74 61 and some consta
02c0: 6e 74 73 20 75 73 65 64 20 61 73 20 72 65 74 75 nts used as retu
02d0: 72 6e 20 76 61 6c 75 65 73 2e 0a 54 68 65 20 63 rn values..The c
02e0: 6f 72 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 ore interface is
02f0: 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e as follows:</p>
0300: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 ..<blockquote><p
0310: 72 65 3e 0a 74 79 70 65 64 65 66 20 73 74 72 75 re>.typedef stru
0320: 63 74 20 73 71 6c 69 74 65 20 73 71 6c 69 74 65 ct sqlite sqlite
0330: 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ;.#define SQLITE
0340: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 _OK 0
0350: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 /* Successful
0360: 72 65 73 75 6c 74 20 2a 2f 0a 0a 73 71 6c 69 74 result */..sqlit
0370: 65 20 2a 73 71 6c 69 74 65 5f 6f 70 65 6e 28 63 e *sqlite_open(c
0380: 6f 6e 73 74 20 63 68 61 72 20 2a 64 62 6e 61 6d onst char *dbnam
0390: 65 2c 20 69 6e 74 20 6d 6f 64 65 2c 20 63 68 61 e, int mode, cha
03a0: 72 20 2a 2a 65 72 72 6d 73 67 29 3b 0a 0a 76 6f r **errmsg);..vo
03b0: 69 64 20 73 71 6c 69 74 65 5f 63 6c 6f 73 65 28 id sqlite_close(
03c0: 73 71 6c 69 74 65 2a 29 3b 0a 0a 69 6e 74 20 73 sqlite*);..int s
03d0: 71 6c 69 74 65 5f 65 78 65 63 28 0a 20 20 73 71 qlite_exec(. sq
03e0: 6c 69 74 65 2a 2c 0a 20 20 63 68 61 72 20 2a 73 lite*,. char *s
03f0: 71 6c 2c 0a 20 20 69 6e 74 20 28 2a 29 28 76 6f ql,. int (*)(vo
0400: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 id*,int,char**,c
0410: 68 61 72 2a 2a 29 2c 0a 20 20 76 6f 69 64 2a 2c har**),. void*,
0420: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 . char **errmsg
0430: 0a 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .);.</pre></bloc
0440: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65 kquote>..<p>.The
0450: 20 61 62 6f 76 65 20 69 73 20 61 6c 6c 20 79 6f above is all yo
0460: 75 20 72 65 61 6c 6c 79 20 6e 65 65 64 20 74 6f u really need to
0470: 20 6b 6e 6f 77 20 69 6e 20 6f 72 64 65 72 20 74 know in order t
0480: 6f 20 75 73 65 20 53 51 4c 69 74 65 0a 69 6e 20 o use SQLite.in
0490: 79 6f 75 72 20 43 20 6f 72 20 43 2b 2b 20 70 72 your C or C++ pr
04a0: 6f 67 72 61 6d 73 2e 20 20 54 68 65 72 65 20 61 ograms. There a
04b0: 72 65 20 6f 74 68 65 72 20 63 6f 6e 76 65 6e 69 re other conveni
04c0: 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 73 0a 61 ence functions.a
04d0: 76 61 69 6c 61 62 6c 65 20 28 61 6e 64 20 64 65 vailable (and de
04e0: 73 63 72 69 62 65 64 20 62 65 6c 6f 77 29 20 62 scribed below) b
04f0: 75 74 20 77 65 20 77 69 6c 6c 20 62 65 67 69 6e ut we will begin
0500: 20 62 79 20 64 65 73 63 72 69 62 69 6e 67 0a 74 by describing.t
0510: 68 65 20 63 6f 72 65 20 66 75 6e 63 74 69 6f 6e he core function
0520: 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2e 0a 3c s shown above..<
0530: 2f 70 3e 0a 3c 68 32 3e 4f 70 65 6e 69 6e 67 20 /p>.<h2>Opening
0540: 61 20 64 61 74 61 62 61 73 65 3c 2f 68 32 3e 0a a database</h2>.
0550: 0a 3c 70 3e 55 73 65 20 74 68 65 20 3c 62 3e 73 .<p>Use the <b>s
0560: 71 6c 69 74 65 5f 6f 70 65 6e 28 29 3c 2f 62 3e qlite_open()</b>
0570: 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 6f 70 65 function to ope
0580: 6e 20 61 6e 20 65 78 69 73 74 69 6e 67 20 53 51 n an existing SQ
0590: 4c 69 74 65 0a 64 61 74 61 62 61 73 65 20 6f 72 Lite.database or
05a0: 20 74 6f 20 63 72 65 61 74 65 20 61 20 6e 65 77 to create a new
05b0: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 SQLite database
05c0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 . The first arg
05d0: 75 6d 65 6e 74 0a 69 73 20 74 68 65 20 64 61 74 ument.is the dat
05e0: 61 62 61 73 65 20 6e 61 6d 65 2e 20 20 54 68 65 abase name. The
05f0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
0600: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 is intended to
0610: 73 69 67 6e 61 6c 0a 77 68 65 74 68 65 72 20 74 signal.whether t
0620: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 67 he database is g
0630: 6f 69 6e 67 20 74 6f 20 62 65 20 75 73 65 64 20 oing to be used
0640: 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
0650: 77 72 69 74 69 6e 67 0a 6f 72 20 6a 75 73 74 20 writing.or just
0660: 66 6f 72 20 72 65 61 64 69 6e 67 2e 20 20 42 75 for reading. Bu
0670: 74 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 t in the current
0680: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c implementation,
0690: 20 74 68 65 0a 73 65 63 6f 6e 64 20 61 72 67 75 the.second argu
06a0: 6d 65 6e 74 20 74 6f 20 3c 62 3e 73 71 6c 69 74 ment to <b>sqlit
06b0: 65 5f 6f 70 65 6e 3c 2f 62 3e 20 69 73 20 69 67 e_open</b> is ig
06c0: 6e 6f 72 65 64 2e 0a 54 68 65 20 74 68 69 72 64 nored..The third
06d0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
06e0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 ointer to a stri
06f0: 6e 67 20 70 6f 69 6e 74 65 72 2e 0a 49 66 20 74 ng pointer..If t
0700: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
0710: 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e t is not NULL an
0720: 64 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 d an error occur
0730: 73 0a 77 68 69 6c 65 20 74 72 79 69 6e 67 20 74 s.while trying t
0740: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 o open the datab
0750: 61 73 65 2c 20 74 68 65 6e 20 61 6e 20 65 72 72 ase, then an err
0760: 6f 72 20 6d 65 73 73 61 67 65 20 77 69 6c 6c 20 or message will
0770: 62 65 0a 77 72 69 74 74 65 6e 20 74 6f 20 6d 65 be.written to me
0780: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
0790: 6f 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 om malloc() and
07a0: 2a 65 72 72 6d 73 67 20 77 69 6c 6c 20 62 65 20 *errmsg will be
07b0: 6d 61 64 65 0a 74 6f 20 70 6f 69 6e 74 20 74 6f made.to point to
07c0: 20 74 68 69 73 20 65 72 72 6f 72 20 6d 65 73 73 this error mess
07d0: 61 67 65 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e age. The callin
07e0: 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 g function is re
07f0: 73 70 6f 6e 73 69 62 6c 65 0a 66 6f 72 20 66 72 sponsible.for fr
0800: 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 eeing the memory
0810: 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e when it has fin
0820: 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 3c 2f ished with it.</
0830: 70 3e 0a 0a 3c 70 3e 54 68 65 20 6e 61 6d 65 20 p>..<p>The name
0840: 6f 66 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 of an SQLite dat
0850: 61 62 61 73 65 20 69 73 20 74 68 65 20 6e 61 6d abase is the nam
0860: 65 20 6f 66 20 61 20 66 69 6c 65 20 74 68 61 74 e of a file that
0870: 20 77 69 6c 6c 0a 63 6f 6e 74 61 69 6e 20 74 68 will.contain th
0880: 65 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 e database. If
0890: 74 68 65 20 66 69 6c 65 20 64 6f 65 73 20 6e 6f the file does no
08a0: 74 20 65 78 69 73 74 2c 20 53 51 4c 69 74 65 20 t exist, SQLite
08b0: 61 74 74 65 6d 70 74 73 0a 74 6f 20 63 72 65 61 attempts.to crea
08c0: 74 65 20 61 6e 64 20 69 6e 69 74 69 61 6c 69 7a te and initializ
08d0: 65 20 69 74 2e 20 20 49 66 20 74 68 65 20 66 69 e it. If the fi
08e0: 6c 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 20 le is read-only
08f0: 28 64 75 65 20 74 6f 0a 70 65 72 6d 69 73 73 69 (due to.permissi
0900: 6f 6e 20 62 69 74 73 20 6f 72 20 62 65 63 61 75 on bits or becau
0910: 73 65 20 69 74 20 69 73 20 6c 6f 63 61 74 65 64 se it is located
0920: 20 6f 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 on read-only me
0930: 64 69 61 20 6c 69 6b 65 0a 61 20 43 44 2d 52 4f dia like.a CD-RO
0940: 4d 29 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6f M) then SQLite o
0950: 70 65 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 pens the databas
0960: 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e e for reading on
0970: 6c 79 2e 20 20 54 68 65 0a 65 6e 74 69 72 65 20 ly. The.entire
0980: 53 51 4c 20 64 61 74 61 62 61 73 65 20 69 73 20 SQL database is
0990: 73 74 6f 72 65 64 20 69 6e 20 61 20 73 69 6e 67 stored in a sing
09a0: 6c 65 20 66 69 6c 65 20 6f 6e 20 74 68 65 20 64 le file on the d
09b0: 69 73 6b 2e 20 20 42 75 74 0a 61 64 64 69 74 69 isk. But.additi
09c0: 6f 6e 61 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 onal temporary f
09d0: 69 6c 65 73 20 6d 61 79 20 62 65 20 63 72 65 61 iles may be crea
09e0: 74 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 65 ted during the e
09f0: 78 65 63 75 74 69 6f 6e 20 6f 66 0a 61 6e 20 53 xecution of.an S
0a00: 51 4c 20 63 6f 6d 6d 61 6e 64 20 69 6e 20 6f 72 QL command in or
0a10: 64 65 72 20 74 6f 20 73 74 6f 72 65 20 74 68 65 der to store the
0a20: 20 64 61 74 61 62 61 73 65 20 72 6f 6c 6c 62 61 database rollba
0a30: 63 6b 20 6a 6f 75 72 6e 61 6c 20 6f 72 0a 74 65 ck journal or.te
0a40: 6d 70 6f 72 61 72 79 20 61 6e 64 20 69 6e 74 65 mporary and inte
0a50: 72 6d 65 64 69 61 74 65 20 72 65 73 75 6c 74 73 rmediate results
0a60: 20 6f 66 20 61 20 71 75 65 72 79 2e 3c 2f 70 3e of a query.</p>
0a70: 0a 0a 3c 70 3e 54 68 65 20 72 65 74 75 72 6e 20 ..<p>The return
0a80: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 3c 62 3e value of the <b>
0a90: 73 71 6c 69 74 65 5f 6f 70 65 6e 28 29 3c 2f 62 sqlite_open()</b
0aa0: 3e 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 0a > function is a.
0ab0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6f 70 pointer to an op
0ac0: 61 71 75 65 20 3c 62 3e 73 71 6c 69 74 65 3c 2f aque <b>sqlite</
0ad0: 62 3e 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 b> structure. T
0ae0: 68 69 73 20 70 6f 69 6e 74 65 72 20 77 69 6c 6c his pointer will
0af0: 0a 62 65 20 74 68 65 20 66 69 72 73 74 20 61 72 .be the first ar
0b00: 67 75 6d 65 6e 74 20 74 6f 20 61 6c 6c 20 73 75 gument to all su
0b10: 62 73 65 71 75 65 6e 74 20 53 51 4c 69 74 65 20 bsequent SQLite
0b20: 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 74 function calls t
0b30: 68 61 74 0a 64 65 61 6c 20 77 69 74 68 20 74 68 hat.deal with th
0b40: 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e e same database.
0b50: 20 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e NULL is return
0b60: 65 64 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 ed if the open f
0b70: 61 69 6c 73 0a 66 6f 72 20 61 6e 79 20 72 65 61 ails.for any rea
0b80: 73 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 68 32 3e 43 6c son.</p>..<h2>Cl
0b90: 6f 73 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 osing the databa
0ba0: 73 65 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 6f 20 63 se</h2>..<p>To c
0bb0: 6c 6f 73 65 20 61 6e 20 53 51 4c 69 74 65 20 64 lose an SQLite d
0bc0: 61 74 61 62 61 73 65 2c 20 63 61 6c 6c 20 74 68 atabase, call th
0bd0: 65 20 3c 62 3e 73 71 6c 69 74 65 5f 63 6c 6f 73 e <b>sqlite_clos
0be0: 65 28 29 3c 2f 62 3e 0a 66 75 6e 63 74 69 6f 6e e()</b>.function
0bf0: 20 70 61 73 73 69 6e 67 20 69 74 20 74 68 65 20 passing it the
0c00: 73 71 6c 69 74 65 20 73 74 72 75 63 74 75 72 65 sqlite structure
0c10: 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 pointer that wa
0c20: 73 20 6f 62 74 61 69 6e 65 64 0a 66 72 6f 6d 20 s obtained.from
0c30: 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 a prior call to
0c40: 3c 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e 3c 2f <b>sqlite_open</
0c50: 62 3e 2e 0a 49 66 20 61 20 74 72 61 6e 73 61 63 b>..If a transac
0c60: 74 69 6f 6e 20 69 73 20 61 63 74 69 76 65 20 77 tion is active w
0c70: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
0c80: 20 69 73 20 63 6c 6f 73 65 64 2c 20 74 68 65 20 is closed, the
0c90: 74 72 61 6e 73 61 63 74 69 6f 6e 0a 69 73 20 72 transaction.is r
0ca0: 6f 6c 6c 65 64 20 62 61 63 6b 2e 3c 2f 70 3e 0a olled back.</p>.
0cb0: 0a 3c 68 32 3e 45 78 65 63 75 74 69 6e 67 20 53 .<h2>Executing S
0cc0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 3c 2f 68 QL statements</h
0cd0: 32 3e 0a 0a 3c 70 3e 54 68 65 20 3c 62 3e 73 71 2>..<p>The <b>sq
0ce0: 6c 69 74 65 5f 65 78 65 63 28 29 3c 2f 62 3e 20 lite_exec()</b>
0cf0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 function is used
0d00: 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 to process SQL
0d10: 73 74 61 74 65 6d 65 6e 74 73 0a 61 6e 64 20 71 statements.and q
0d20: 75 65 72 69 65 73 2e 20 20 54 68 69 73 20 66 75 ueries. This fu
0d30: 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
0d40: 35 20 70 61 72 61 6d 65 74 65 72 73 20 61 73 20 5 parameters as
0d50: 66 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c 6f follows:</p>..<o
0d60: 6c 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 70 6f 69 6e l>.<li><p>A poin
0d70: 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
0d80: 65 20 73 74 72 75 63 74 75 72 65 20 6f 62 74 61 e structure obta
0d90: 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f ined from a prio
0da0: 72 20 63 61 6c 6c 0a 20 20 20 20 20 20 20 74 6f r call. to
0db0: 20 3c 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e 28 <b>sqlite_open(
0dc0: 29 3c 2f 62 3e 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a )</b>.</p></li>.
0dd0: 3c 6c 69 3e 3c 70 3e 41 20 6e 75 6c 6c 2d 74 65 <li><p>A null-te
0de0: 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 rminated string
0df0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 containing the t
0e00: 65 78 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f ext of one or mo
0e10: 72 65 0a 20 20 20 20 20 20 20 53 51 4c 20 73 74 re. SQL st
0e20: 61 74 65 6d 65 6e 74 73 20 61 6e 64 2f 6f 72 20 atements and/or
0e30: 71 75 65 72 69 65 73 20 74 6f 20 62 65 20 70 72 queries to be pr
0e40: 6f 63 65 73 73 65 64 2e 3c 2f 70 3e 3c 2f 6c 69 ocessed.</p></li
0e50: 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 70 6f 69 6e 74 >.<li><p>A point
0e60: 65 72 20 74 6f 20 61 20 63 61 6c 6c 62 61 63 6b er to a callback
0e70: 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 function which
0e80: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 is invoked once
0e90: 66 6f 72 20 65 61 63 68 0a 20 20 20 20 20 20 20 for each.
0ea0: 72 6f 77 20 69 6e 20 74 68 65 20 72 65 73 75 6c row in the resul
0eb0: 74 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 54 t of a query. T
0ec0: 68 69 73 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 his argument may
0ed0: 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 be NULL, in whi
0ee0: 63 68 0a 20 20 20 20 20 20 20 63 61 73 65 20 6e ch. case n
0ef0: 6f 20 63 61 6c 6c 62 61 63 6b 73 20 77 69 6c 6c o callbacks will
0f00: 20 65 76 65 72 20 62 65 20 69 6e 76 6f 6b 65 64 ever be invoked
0f10: 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c .</p></li>.<li><
0f20: 70 3e 41 20 70 6f 69 6e 74 65 72 20 74 68 61 74 p>A pointer that
0f30: 20 69 73 20 66 6f 72 77 61 72 64 65 64 20 74 6f is forwarded to
0f40: 20 62 65 63 6f 6d 65 20 74 68 65 20 66 69 72 73 become the firs
0f50: 74 20 61 72 67 75 6d 65 6e 74 0a 20 20 20 20 20 t argument.
0f60: 20 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 to the callbac
0f70: 6b 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 70 3e 3c k function.</p><
0f80: 2f 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 70 6f /li>.<li><p>A po
0f90: 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 72 72 6f inter to an erro
0fa0: 72 20 73 74 72 69 6e 67 2e 20 20 45 72 72 6f 72 r string. Error
0fb0: 20 6d 65 73 73 61 67 65 73 20 61 72 65 20 77 72 messages are wr
0fc0: 69 74 74 65 6e 20 74 6f 20 73 70 61 63 65 0a 20 itten to space.
0fd0: 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 obtained f
0fe0: 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 rom malloc() and
0ff0: 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e the error strin
1000: 67 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 g is made to poi
1010: 6e 74 20 74 6f 0a 20 20 20 20 20 20 20 74 68 65 nt to. the
1020: 20 6d 61 6c 6c 6f 63 65 64 20 73 70 61 63 65 2e malloced space.
1030: 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 The calling fu
1040: 6e 63 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e nction is respon
1050: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e sible for freein
1060: 67 0a 20 20 20 20 20 20 20 74 68 69 73 20 73 70 g. this sp
1070: 61 63 65 20 77 68 65 6e 20 69 74 20 68 61 73 20 ace when it has
1080: 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 finished with it
1090: 2e 0a 20 20 20 20 20 20 20 54 68 69 73 20 61 72 .. This ar
10a0: 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55 gument may be NU
10b0: 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 LL, in which cas
10c0: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 e error messages
10d0: 20 61 72 65 20 6e 6f 74 0a 20 20 20 20 20 20 20 are not.
10e0: 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 74 6f reported back to
10f0: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e the calling fun
1100: 63 74 69 6f 6e 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a ction.</p></li>.
1110: 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 0a 54 68 65 20 63 </ol>..<p>.The c
1120: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
1130: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 63 65 is used to rece
1140: 69 76 65 20 74 68 65 20 72 65 73 75 6c 74 73 20 ive the results
1150: 6f 66 20 61 20 71 75 65 72 79 2e 20 20 41 0a 70 of a query. A.p
1160: 72 6f 74 6f 74 79 70 65 20 66 6f 72 20 74 68 65 rototype for the
1170: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
1180: 6f 6e 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 on is as follows
1190: 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f :</p>..<blockquo
11a0: 74 65 3e 3c 70 72 65 3e 0a 69 6e 74 20 43 61 6c te><pre>.int Cal
11b0: 6c 62 61 63 6b 28 76 6f 69 64 20 2a 70 41 72 67 lback(void *pArg
11c0: 2c 20 69 6e 74 20 61 72 67 63 2c 20 63 68 61 72 , int argc, char
11d0: 20 2a 2a 61 72 67 76 2c 20 63 68 61 72 20 2a 2a **argv, char **
11e0: 63 6f 6c 75 6d 6e 4e 61 6d 65 73 29 7b 0a 20 20 columnNames){.
11f0: 72 65 74 75 72 6e 20 30 3b 0a 7d 0a 3c 2f 70 72 return 0;.}.</pr
1200: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
1210: 0a 3c 70 3e 54 68 65 20 66 69 72 73 74 20 61 72 .<p>The first ar
1220: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 gument to the ca
1230: 6c 6c 62 61 63 6b 20 69 73 20 6a 75 73 74 20 61 llback is just a
1240: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 copy of the fou
1250: 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 74 6f 20 rth argument.to
1260: 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 28 29 <b>sqlite_exec()
1270: 3c 2f 62 3e 20 20 54 68 69 73 20 70 61 72 61 6d </b> This param
1280: 65 74 65 72 20 63 61 6e 20 62 65 20 75 73 65 64 eter can be used
1290: 20 74 6f 20 70 61 73 73 20 61 72 62 69 74 72 61 to pass arbitra
12a0: 72 79 0a 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 74 ry.information t
12b0: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 hrough to the ca
12c0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
12d0: 66 72 6f 6d 20 63 6c 69 65 6e 74 20 63 6f 64 65 from client code
12e0: 2e 0a 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 ..The second arg
12f0: 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d ument is the num
1300: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
1310: 6e 20 74 68 65 20 71 75 65 72 79 20 72 65 73 75 n the query resu
1320: 6c 74 2e 0a 54 68 65 20 74 68 69 72 64 20 61 72 lt..The third ar
1330: 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 61 72 72 gument is an arr
1340: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 ay of pointers t
1350: 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 o strings where
1360: 65 61 63 68 20 73 74 72 69 6e 67 0a 69 73 20 61 each string.is a
1370: 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f single column o
1380: 66 20 74 68 65 20 72 65 73 75 6c 74 20 66 6f 72 f the result for
1390: 20 74 68 61 74 20 72 65 63 6f 72 64 2e 20 20 4e that record. N
13a0: 6f 74 65 20 74 68 61 74 20 74 68 65 0a 63 61 6c ote that the.cal
13b0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 lback function r
13c0: 65 70 6f 72 74 73 20 61 20 4e 55 4c 4c 20 76 61 eports a NULL va
13d0: 6c 75 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 lue in the datab
13e0: 61 73 65 20 61 73 20 61 20 4e 55 4c 4c 20 70 6f ase as a NULL po
13f0: 69 6e 74 65 72 2c 0a 77 68 69 63 68 20 69 73 20 inter,.which is
1400: 76 65 72 79 20 64 69 66 66 65 72 65 6e 74 20 66 very different f
1410: 72 6f 6d 20 61 6e 20 65 6d 70 74 79 20 73 74 72 rom an empty str
1420: 69 6e 67 2e 20 20 49 66 20 74 68 65 20 69 2d 74 ing. If the i-t
1430: 68 20 70 61 72 61 6d 65 74 65 72 0a 69 73 20 61 h parameter.is a
1440: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 n empty string,
1450: 77 65 20 77 69 6c 6c 20 67 65 74 3a 3c 2f 70 3e we will get:</p>
1460: 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 .<blockquote><pr
1470: 65 3e 0a 61 72 67 76 5b 69 5d 5b 30 5d 20 3d 3d e>.argv[i][0] ==
1480: 20 30 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 0.</pre></block
1490: 71 75 6f 74 65 3e 0a 3c 70 3e 42 75 74 20 69 66 quote>.<p>But if
14a0: 20 74 68 65 20 69 2d 74 68 20 70 61 72 61 6d 65 the i-th parame
14b0: 74 65 72 20 69 73 20 4e 55 4c 4c 20 77 65 20 77 ter is NULL we w
14c0: 69 6c 6c 20 67 65 74 3a 3c 2f 70 3e 0a 3c 62 6c ill get:</p>.<bl
14d0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 61 ockquote><pre>.a
14e0: 72 67 76 5b 69 5d 20 3d 3d 20 30 0a 3c 2f 70 72 rgv[i] == 0.</pr
14f0: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
1500: 3c 70 3e 54 68 65 20 6e 61 6d 65 73 20 6f 66 20 <p>The names of
1510: 74 68 65 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20 the columns are
1520: 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 contained in the
1530: 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
1540: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 49 66 20 74 68 65 .</p>..<p>If the
1550: 20 45 4d 50 54 59 5f 52 45 53 55 4c 54 5f 43 41 EMPTY_RESULT_CA
1560: 4c 4c 42 41 43 4b 53 20 70 72 61 67 6d 61 20 69 LLBACKS pragma i
1570: 73 20 73 65 74 20 74 6f 20 4f 4e 20 61 6e 64 20 s set to ON and
1580: 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 61 20 the result of.a
1590: 71 75 65 72 79 20 69 73 20 61 6e 20 65 6d 70 74 query is an empt
15a0: 79 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 y set, then the
15b0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
15c0: 6b 65 64 20 6f 6e 63 65 20 77 69 74 68 20 74 68 ked once with th
15d0: 65 0a 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e.third paramete
15e0: 72 20 28 61 72 67 76 29 20 73 65 74 20 74 6f 20 r (argv) set to
15f0: 30 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 0. In other wor
1600: 64 73 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ds.<blockquote><
1610: 70 72 65 3e 0a 61 72 67 76 20 3d 3d 20 30 0a 3c pre>.argv == 0.<
1620: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1630: 65 3e 0a 54 68 65 20 73 65 63 6f 6e 64 20 70 61 e>.The second pa
1640: 72 61 6d 65 74 65 72 20 28 61 72 67 63 29 0a 61 rameter (argc).a
1650: 6e 64 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 nd the fourth pa
1660: 72 61 6d 65 74 65 72 20 28 63 6f 6c 75 6d 6e 4e rameter (columnN
1670: 61 6d 65 73 29 20 61 72 65 20 73 74 69 6c 6c 20 ames) are still
1680: 76 61 6c 69 64 0a 61 6e 64 20 63 61 6e 20 62 65 valid.and can be
1690: 20 75 73 65 64 20 74 6f 20 64 65 74 65 72 6d 69 used to determi
16a0: 6e 65 20 74 68 65 20 6e 75 6d 62 65 72 20 61 6e ne the number an
16b0: 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 72 d names of the r
16c0: 65 73 75 6c 74 0a 63 6f 6c 75 6d 6e 73 20 69 66 esult.columns if
16d0: 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 there had been
16e0: 61 20 72 65 73 75 6c 74 2e 0a 54 68 65 20 64 65 a result..The de
16f0: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 fault behavior i
1700: 73 20 6e 6f 74 20 74 6f 20 69 6e 76 6f 6b 65 20 s not to invoke
1710: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 74 20 the callback at
1720: 61 6c 6c 20 69 66 20 74 68 65 0a 72 65 73 75 6c all if the.resul
1730: 74 20 73 65 74 20 69 73 20 65 6d 70 74 79 2e 3c t set is empty.<
1740: 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 63 61 6c 6c /p>..<p>The call
1750: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 back function sh
1760: 6f 75 6c 64 20 6e 6f 72 6d 61 6c 6c 79 20 72 65 ould normally re
1770: 74 75 72 6e 20 30 2e 20 20 49 66 20 74 68 65 20 turn 0. If the
1780: 63 61 6c 6c 62 61 63 6b 0a 66 75 6e 63 74 69 6f callback.functio
1790: 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 n returns non-ze
17a0: 72 6f 2c 20 74 68 65 20 71 75 65 72 79 20 69 73 ro, the query is
17b0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 62 6f immediately abo
17c0: 72 74 65 64 20 61 6e 64 20 0a 3c 62 3e 73 71 6c rted and .<b>sql
17d0: 69 74 65 5f 65 78 65 63 28 29 3c 2f 62 3e 20 77 ite_exec()</b> w
17e0: 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 ill return SQLIT
17f0: 45 5f 41 42 4f 52 54 2e 3c 2f 70 3e 0a 0a 3c 68 E_ABORT.</p>..<h
1800: 32 3e 45 72 72 6f 72 20 43 6f 64 65 73 3c 2f 68 2>Error Codes</h
1810: 32 3e 0a 0a 3c 70 3e 0a 54 68 65 20 3c 62 3e 73 2>..<p>.The <b>s
1820: 71 6c 69 74 65 5f 65 78 65 63 28 29 3c 2f 62 3e qlite_exec()</b>
1830: 20 66 75 6e 63 74 69 6f 6e 20 6e 6f 72 6d 61 6c function normal
1840: 6c 79 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 ly returns SQLIT
1850: 45 5f 4f 4b 2e 20 20 42 75 74 0a 69 66 20 73 6f E_OK. But.if so
1860: 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f mething goes wro
1870: 6e 67 20 69 74 20 63 61 6e 20 72 65 74 75 72 6e ng it can return
1880: 20 61 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c a different val
1890: 75 65 20 74 6f 20 69 6e 64 69 63 61 74 65 0a 74 ue to indicate.t
18a0: 68 65 20 74 79 70 65 20 6f 66 20 65 72 72 6f 72 he type of error
18b0: 2e 20 20 48 65 72 65 20 69 73 20 61 20 63 6f 6d . Here is a com
18c0: 70 6c 65 74 65 20 6c 69 73 74 20 6f 66 20 74 68 plete list of th
18d0: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 73 3a 0a e return codes:.
18e0: 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 </p>..<blockquot
18f0: 65 3e 3c 70 72 65 3e 0a 23 64 65 66 69 6e 65 20 e><pre>.#define
1900: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 SQLITE_OK
1910: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 0 /* Succe
1920: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a ssful result */.
1930: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 #define SQLITE_E
1940: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 RROR 1
1950: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 /* SQL error or
1960: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 missing database
1970: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1980: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 TE_INTERNAL
1990: 32 20 20 20 2f 2a 20 41 6e 20 69 6e 74 65 72 6e 2 /* An intern
19a0: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 al logic error i
19b0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 n SQLite */.#def
19c0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 ine SQLITE_PERM
19d0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 3 /* A
19e0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e ccess permission
19f0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 denied */.#defi
1a00: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 ne SQLITE_ABORT
1a10: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 4 /* Ca
1a20: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 llback routine r
1a30: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 equested an abor
1a40: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
1a50: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 ITE_BUSY
1a60: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 5 /* The data
1a70: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 base file is loc
1a80: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ked */.#define S
1a90: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 QLITE_LOCKED
1aa0: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 6 /* A tabl
1ab0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 e in the databas
1ac0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 e is locked */.#
1ad0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
1ae0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f MEM 7 /
1af0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 * A malloc() fai
1b00: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 led */.#define S
1b10: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 QLITE_READONLY
1b20: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 8 /* Attemp
1b30: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 t to write a rea
1b40: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a donly database *
1b50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1b60: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 _INTERRUPT 9
1b70: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 /* Operation t
1b80: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c erminated by sql
1b90: 69 74 65 5f 69 6e 74 65 72 72 75 70 74 28 29 20 ite_interrupt()
1ba0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1bb0: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 E_IOERR 10
1bc0: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 /* Some kind
1bd0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f of disk I/O erro
1be0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 r occurred */.#d
1bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 efine SQLITE_COR
1c00: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a RUPT 11 /*
1c10: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 The database di
1c20: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 sk image is malf
1c30: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 ormed */.#define
1c40: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 SQLITE_NOTFOUND
1c50: 20 20 20 20 31 32 20 20 20 2f 2a 20 28 49 6e 74 12 /* (Int
1c60: 65 72 6e 61 6c 20 4f 6e 6c 79 29 20 54 61 62 6c ernal Only) Tabl
1c70: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 e or record not
1c80: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 found */.#define
1c90: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 SQLITE_FULL
1ca0: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 13 /* Inse
1cb0: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 rtion failed bec
1cc0: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 ause database is
1cd0: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 full */.#define
1ce0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
1cf0: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 14 /* Unab
1d00: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 le to open the d
1d10: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a atabase file */.
1d20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 #define SQLITE_P
1d30: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 ROTOCOL 15
1d40: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b /* Database lock
1d50: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 protocol error
1d60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1d70: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 E_EMPTY 16
1d80: 20 20 20 2f 2a 20 28 49 6e 74 65 72 6e 61 6c 20 /* (Internal
1d90: 4f 6e 6c 79 29 20 44 61 74 61 62 61 73 65 20 74 Only) Database t
1da0: 61 62 6c 65 20 69 73 20 65 6d 70 74 79 20 2a 2f able is empty */
1db0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1dc0: 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 SCHEMA 17
1dd0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
1de0: 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 schema changed
1df0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1e00: 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 E_TOOBIG 18
1e10: 20 20 20 2f 2a 20 54 6f 6f 20 6d 75 63 68 20 64 /* Too much d
1e20: 61 74 61 20 66 6f 72 20 6f 6e 65 20 72 6f 77 20 ata for one row
1e30: 6f 66 20 61 20 74 61 62 6c 65 20 2a 2f 0a 23 64 of a table */.#d
1e40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
1e50: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a STRAINT 19 /*
1e60: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f Abort due to co
1e70: 6e 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f ntraint violatio
1e80: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c n */.#define SQL
1e90: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 ITE_MISMATCH
1ea0: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 20 /* Data typ
1eb0: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 3c 2f e mismatch */.</
1ec0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1ed0: 3e 0a 0a 3c 70 3e 0a 54 68 65 20 6d 65 61 6e 69 >..<p>.The meani
1ee0: 6e 67 73 20 6f 66 20 74 68 65 73 65 20 76 61 72 ngs of these var
1ef0: 69 6f 75 73 20 72 65 74 75 72 6e 20 76 61 6c 75 ious return valu
1f00: 65 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 es are as follow
1f10: 73 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 s:.</p>..<blockq
1f20: 75 6f 74 65 3e 0a 3c 64 6c 3e 0a 3c 64 74 3e 53 uote>.<dl>.<dt>S
1f30: 51 4c 49 54 45 5f 4f 4b 3c 2f 64 74 3e 0a 3c 64 QLITE_OK</dt>.<d
1f40: 64 3e 3c 70 3e 54 68 69 73 20 76 61 6c 75 65 20 d><p>This value
1f50: 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 65 is returned if e
1f60: 76 65 72 79 74 68 69 6e 67 20 77 6f 72 6b 65 64 verything worked
1f70: 20 61 6e 64 20 74 68 65 72 65 20 77 65 72 65 20 and there were
1f80: 6e 6f 20 65 72 72 6f 72 73 2e 0a 3c 2f 70 3e 3c no errors..</p><
1f90: 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f /dd>.<dt>SQLITE_
1fa0: 49 4e 54 45 52 4e 41 4c 3c 2f 64 74 3e 0a 3c 64 INTERNAL</dt>.<d
1fb0: 64 3e 3c 70 3e 54 68 69 73 20 76 61 6c 75 65 20 d><p>This value
1fc0: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 61 indicates that a
1fd0: 6e 20 69 6e 74 65 72 6e 61 6c 20 63 6f 6e 73 69 n internal consi
1fe0: 73 74 65 6e 63 79 20 63 68 65 63 6b 20 77 69 74 stency check wit
1ff0: 68 69 6e 0a 74 68 65 20 53 51 4c 69 74 65 20 6c hin.the SQLite l
2000: 69 62 72 61 72 79 20 66 61 69 6c 65 64 2e 20 20 ibrary failed.
2010: 54 68 69 73 20 63 61 6e 20 6f 6e 6c 79 20 68 61 This can only ha
2020: 70 70 65 6e 20 69 66 20 74 68 65 72 65 20 69 73 ppen if there is
2030: 20 61 20 62 75 67 20 69 6e 0a 74 68 65 20 53 51 a bug in.the SQ
2040: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 49 Lite library. I
2050: 66 20 79 6f 75 20 65 76 65 72 20 67 65 74 20 61 f you ever get a
2060: 6e 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 n SQLITE_INTERNA
2070: 4c 20 72 65 70 6c 79 20 66 72 6f 6d 0a 61 6e 20 L reply from.an
2080: 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 28 29 <b>sqlite_exec()
2090: 3c 2f 62 3e 20 63 61 6c 6c 2c 20 70 6c 65 61 73 </b> call, pleas
20a0: 65 20 72 65 70 6f 72 74 20 74 68 65 20 70 72 6f e report the pro
20b0: 62 6c 65 6d 20 6f 6e 20 74 68 65 20 53 51 4c 69 blem on the SQLi
20c0: 74 65 0a 6d 61 69 6c 69 6e 67 20 6c 69 73 74 2e te.mailing list.
20d0: 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 .</p></dd>.<dt>S
20e0: 51 4c 49 54 45 5f 45 52 52 4f 52 3c 2f 64 74 3e QLITE_ERROR</dt>
20f0: 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 72 65 74 .<dd><p>This ret
2100: 75 72 6e 20 76 61 6c 75 65 20 69 6e 64 69 63 61 urn value indica
2110: 74 65 73 20 74 68 61 74 20 74 68 65 72 65 20 77 tes that there w
2120: 61 73 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 74 as an error in t
2130: 68 65 20 53 51 4c 0a 74 68 61 74 20 77 61 73 20 he SQL.that was
2140: 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 passed into the
2150: 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 28 29 <b>sqlite_exec()
2160: 3c 2f 62 3e 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a </b>..</p></dd>.
2170: 3c 64 74 3e 53 51 4c 49 54 45 5f 50 45 52 4d 3c <dt>SQLITE_PERM<
2180: 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 /dt>.<dd><p>This
2190: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 73 61 return value sa
21a0: 79 73 20 74 68 61 74 20 74 68 65 20 61 63 63 65 ys that the acce
21b0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 6f ss permissions o
21c0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 66 n the database.f
21d0: 69 6c 65 20 61 72 65 20 73 75 63 68 20 74 68 61 ile are such tha
21e0: 74 20 74 68 65 20 66 69 6c 65 20 63 61 6e 6e 6f t the file canno
21f0: 74 20 62 65 20 6f 70 65 6e 65 64 2e 0a 3c 2f 70 t be opened..</p
2200: 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 ></dd>.<dt>SQLIT
2210: 45 5f 41 42 4f 52 54 3c 2f 64 74 3e 0a 3c 64 64 E_ABORT</dt>.<dd
2220: 3e 3c 70 3e 54 68 69 73 20 76 61 6c 75 65 20 69 ><p>This value i
2230: 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 s returned if th
2240: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
2250: 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ion returns non-
2260: 7a 65 72 6f 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a zero..</p></dd>.
2270: 3c 64 74 3e 53 51 4c 49 54 45 5f 42 55 53 59 3c <dt>SQLITE_BUSY<
2280: 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 /dt>.<dd><p>This
2290: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 69 6e 64 return code ind
22a0: 69 63 61 74 65 73 20 74 68 61 74 20 61 6e 6f 74 icates that anot
22b0: 68 65 72 20 70 72 6f 67 72 61 6d 20 6f 72 20 74 her program or t
22c0: 68 72 65 61 64 20 68 61 73 0a 74 68 65 20 64 61 hread has.the da
22d0: 74 61 62 61 73 65 20 6c 6f 63 6b 65 64 2e 20 20 tabase locked.
22e0: 53 51 4c 69 74 65 20 61 6c 6c 6f 77 73 20 74 77 SQLite allows tw
22f0: 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 o or more thread
2300: 73 20 74 6f 20 72 65 61 64 20 74 68 65 0a 64 61 s to read the.da
2310: 74 61 62 61 73 65 20 61 74 20 74 68 65 20 73 61 tabase at the sa
2320: 6d 65 20 74 69 6d 65 2c 20 62 75 74 20 6f 6e 6c me time, but onl
2330: 79 20 6f 6e 65 20 74 68 72 65 61 64 20 63 61 6e y one thread can
2340: 20 68 61 76 65 20 74 68 65 20 64 61 74 61 62 61 have the databa
2350: 73 65 0a 6f 70 65 6e 20 66 6f 72 20 77 72 69 74 se.open for writ
2360: 69 6e 67 20 61 74 20 74 68 65 20 73 61 6d 65 20 ing at the same
2370: 74 69 6d 65 2e 20 20 4c 6f 63 6b 69 6e 67 20 69 time. Locking i
2380: 6e 20 53 51 4c 69 74 65 20 69 73 20 6f 6e 20 74 n SQLite is on t
2390: 68 65 0a 65 6e 74 69 72 65 20 64 61 74 61 62 61 he.entire databa
23a0: 73 65 2e 3c 2f 70 3e 0a 3c 2f 70 3e 3c 2f 64 64 se.</p>.</p></dd
23b0: 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 4f 43 >.<dt>SQLITE_LOC
23c0: 4b 45 44 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e KED</dt>.<dd><p>
23d0: 54 68 69 73 20 72 65 74 75 72 6e 20 63 6f 64 65 This return code
23e0: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 53 is similar to S
23f0: 51 4c 49 54 45 5f 42 55 53 59 20 69 6e 20 74 68 QLITE_BUSY in th
2400: 61 74 20 69 74 20 69 6e 64 69 63 61 74 65 73 0a at it indicates.
2410: 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 that the databas
2420: 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 42 75 e is locked. Bu
2430: 74 20 74 68 65 20 73 6f 75 72 63 65 20 6f 66 20 t the source of
2440: 74 68 65 20 6c 6f 63 6b 20 69 73 20 61 20 72 65 the lock is a re
2450: 63 75 72 73 69 76 65 0a 63 61 6c 6c 20 74 6f 20 cursive.call to
2460: 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 28 29 <b>sqlite_exec()
2470: 3c 2f 62 3e 2e 20 20 54 68 69 73 20 72 65 74 75 </b>. This retu
2480: 72 6e 20 63 61 6e 20 6f 6e 6c 79 20 6f 63 63 75 rn can only occu
2490: 72 20 69 66 20 79 6f 75 20 61 74 74 65 6d 70 74 r if you attempt
24a0: 0a 74 6f 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 .to invoke sqlit
24b0: 65 5f 65 78 65 63 28 29 20 66 72 6f 6d 20 77 69 e_exec() from wi
24c0: 74 68 69 6e 20 61 20 63 61 6c 6c 62 61 63 6b 20 thin a callback
24d0: 72 6f 75 74 69 6e 65 20 6f 66 20 61 20 71 75 65 routine of a que
24e0: 72 79 0a 66 72 6f 6d 20 61 20 70 72 69 6f 72 20 ry.from a prior
24f0: 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 73 71 invocation of sq
2500: 6c 69 74 65 5f 65 78 65 63 28 29 2e 20 20 52 65 lite_exec(). Re
2510: 63 75 72 73 69 76 65 20 63 61 6c 6c 73 20 74 6f cursive calls to
2520: 0a 73 71 6c 69 74 65 5f 65 78 65 63 28 29 20 61 .sqlite_exec() a
2530: 72 65 20 61 6c 6c 6f 77 65 64 20 61 73 20 6c 6f re allowed as lo
2540: 6e 67 20 61 73 20 74 68 65 79 20 64 6f 0a 6e 6f ng as they do.no
2550: 74 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72 69 t attempt to wri
2560: 74 65 20 74 68 65 20 73 61 6d 65 20 74 61 62 6c te the same tabl
2570: 65 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 e..</p></dd>.<dt
2580: 3e 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 3c 2f 64 >SQLITE_NOMEM</d
2590: 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 76 t>.<dd><p>This v
25a0: 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 alue is returned
25b0: 20 69 66 20 61 20 63 61 6c 6c 20 74 6f 20 3c 62 if a call to <b
25c0: 3e 6d 61 6c 6c 6f 63 28 29 3c 2f 62 3e 20 66 61 >malloc()</b> fa
25d0: 69 6c 73 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c ils..</p></dd>.<
25e0: 64 74 3e 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e dt>SQLITE_READON
25f0: 4c 59 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 LY</dt>.<dd><p>T
2600: 68 69 73 20 72 65 74 75 72 6e 20 63 6f 64 65 20 his return code
2610: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 61 indicates that a
2620: 6e 20 61 74 74 65 6d 70 74 20 77 61 73 20 6d 61 n attempt was ma
2630: 64 65 20 74 6f 20 77 72 69 74 65 20 74 6f 0a 61 de to write to.a
2640: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 database file t
2650: 68 61 74 20 69 73 20 6f 70 65 6e 65 64 20 66 6f hat is opened fo
2660: 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a r reading only..
2670: 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 </p></dd>.<dt>SQ
2680: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 3c 2f LITE_INTERRUPT</
2690: 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 dt>.<dd><p>This
26a0: 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 value is returne
26b0: 64 20 69 66 20 61 20 63 61 6c 6c 20 74 6f 20 3c d if a call to <
26c0: 62 3e 73 71 6c 69 74 65 5f 69 6e 74 65 72 72 75 b>sqlite_interru
26d0: 70 74 28 29 3c 2f 62 3e 0a 69 6e 74 65 72 72 75 pt()</b>.interru
26e0: 70 74 73 20 61 20 64 61 74 61 62 61 73 65 20 6f pts a database o
26f0: 70 65 72 61 74 69 6f 6e 20 69 6e 20 70 72 6f 67 peration in prog
2700: 72 65 73 73 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a ress..</p></dd>.
2710: 3c 64 74 3e 53 51 4c 49 54 45 5f 49 4f 45 52 52 <dt>SQLITE_IOERR
2720: 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 </dt>.<dd><p>Thi
2730: 73 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 s value is retur
2740: 6e 65 64 20 69 66 20 74 68 65 20 6f 70 65 72 61 ned if the opera
2750: 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 66 6f ting system info
2760: 72 6d 73 20 53 51 4c 69 74 65 0a 74 68 61 74 20 rms SQLite.that
2770: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 it is unable to
2780: 70 65 72 66 6f 72 6d 20 73 6f 6d 65 20 64 69 73 perform some dis
2790: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 2e k I/O operation.
27a0: 20 20 54 68 69 73 20 63 6f 75 6c 64 20 6d 65 61 This could mea
27b0: 6e 0a 74 68 61 74 20 74 68 65 72 65 20 69 73 20 n.that there is
27c0: 6e 6f 20 6d 6f 72 65 20 73 70 61 63 65 20 6c 65 no more space le
27d0: 66 74 20 6f 6e 20 74 68 65 20 64 69 73 6b 2e 0a ft on the disk..
27e0: 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 </p></dd>.<dt>SQ
27f0: 4c 49 54 45 5f 43 4f 52 52 55 50 54 3c 2f 64 74 LITE_CORRUPT</dt
2800: 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 76 61 >.<dd><p>This va
2810: 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 lue is returned
2820: 69 66 20 53 51 4c 69 74 65 20 64 65 74 65 63 74 if SQLite detect
2830: 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 s that the datab
2840: 61 73 65 20 69 74 20 69 73 0a 77 6f 72 6b 69 6e ase it is.workin
2850: 67 20 6f 6e 20 68 61 73 20 62 65 63 6f 6d 65 20 g on has become
2860: 63 6f 72 72 75 70 74 65 64 2e 20 20 43 6f 72 72 corrupted. Corr
2870: 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 6f 63 63 uption might occ
2880: 75 72 20 64 75 65 20 74 6f 20 61 20 72 6f 67 75 ur due to a rogu
2890: 65 0a 70 72 6f 63 65 73 73 20 77 72 69 74 69 6e e.process writin
28a0: 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 g to the databas
28b0: 65 20 66 69 6c 65 20 6f 72 20 69 74 20 6d 69 67 e file or it mig
28c0: 68 74 20 68 61 70 70 65 6e 20 64 75 65 20 74 6f ht happen due to
28d0: 20 61 6e 20 0a 70 65 72 76 69 6f 75 73 6c 79 20 an .perviously
28e0: 75 6e 64 65 74 65 63 74 65 64 20 6c 6f 67 69 63 undetected logic
28f0: 20 65 72 72 6f 72 20 69 6e 20 6f 66 20 53 51 4c error in of SQL
2900: 69 74 65 2e 20 54 68 69 73 20 76 61 6c 75 65 20 ite. This value
2910: 69 73 20 61 6c 73 6f 0a 72 65 74 75 72 6e 65 64 is also.returned
2920: 20 69 66 20 61 20 64 69 73 6b 20 49 2f 4f 20 65 if a disk I/O e
2930: 72 72 6f 72 20 6f 63 63 75 72 73 20 69 6e 20 73 rror occurs in s
2940: 75 63 68 20 61 20 77 61 79 20 74 68 61 74 20 53 uch a way that S
2950: 51 4c 69 74 65 20 69 73 20 66 6f 72 63 65 64 0a QLite is forced.
2960: 74 6f 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 to leave the dat
2970: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 61 20 abase file in a
2980: 63 6f 72 72 75 70 74 65 64 20 73 74 61 74 65 2e corrupted state.
2990: 20 20 54 68 65 20 6c 61 74 74 65 72 20 73 68 6f The latter sho
29a0: 75 6c 64 20 6f 6e 6c 79 0a 68 61 70 70 65 6e 20 uld only.happen
29b0: 64 75 65 20 74 6f 20 61 20 68 61 72 64 77 61 72 due to a hardwar
29c0: 65 20 6f 72 20 6f 70 65 72 61 74 69 6e 67 20 73 e or operating s
29d0: 79 73 74 65 6d 20 6d 61 6c 66 75 6e 63 74 69 6f ystem malfunctio
29e0: 6e 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 n..</p></dd>.<dt
29f0: 3e 53 51 4c 49 54 45 5f 46 55 4c 4c 3c 2f 64 74 >SQLITE_FULL</dt
2a00: 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 76 61 >.<dd><p>This va
2a10: 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 lue is returned
2a20: 69 66 20 61 6e 20 69 6e 73 65 72 74 69 6f 6e 20 if an insertion
2a30: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 74 failed because t
2a40: 68 65 72 65 20 69 73 0a 6e 6f 20 73 70 61 63 65 here is.no space
2a50: 20 6c 65 66 74 20 6f 6e 20 74 68 65 20 64 69 73 left on the dis
2a60: 6b 2c 20 6f 72 20 74 68 65 20 64 61 74 61 62 61 k, or the databa
2a70: 73 65 20 69 73 20 74 6f 6f 20 62 69 67 20 74 6f se is too big to
2a80: 20 68 6f 6c 64 20 61 6e 79 0a 6d 6f 72 65 20 69 hold any.more i
2a90: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 20 54 68 65 nformation. The
2aa0: 20 6c 61 74 74 65 72 20 63 61 73 65 20 73 68 6f latter case sho
2ab0: 75 6c 64 20 6f 6e 6c 79 20 6f 63 63 75 72 20 66 uld only occur f
2ac0: 6f 72 20 64 61 74 61 62 61 73 65 73 0a 74 68 61 or databases.tha
2ad0: 74 20 61 72 65 20 6c 61 72 67 65 72 20 74 68 61 t are larger tha
2ae0: 6e 20 32 47 42 20 69 6e 20 73 69 7a 65 2e 0a 3c n 2GB in size..<
2af0: 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c /p></dd>.<dt>SQL
2b00: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 3c 2f 64 74 ITE_CANTOPEN</dt
2b10: 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 76 61 >.<dd><p>This va
2b20: 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 lue is returned
2b30: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 if the database
2b40: 66 69 6c 65 20 63 6f 75 6c 64 20 6e 6f 74 20 62 file could not b
2b50: 65 20 6f 70 65 6e 65 64 0a 66 6f 72 20 73 6f 6d e opened.for som
2b60: 65 20 72 65 61 73 6f 6e 2e 0a 3c 2f 70 3e 3c 2f e reason..</p></
2b70: 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 50 dd>.<dt>SQLITE_P
2b80: 52 4f 54 4f 43 4f 4c 3c 2f 64 74 3e 0a 3c 64 64 ROTOCOL</dt>.<dd
2b90: 3e 3c 70 3e 54 68 69 73 20 76 61 6c 75 65 20 69 ><p>This value i
2ba0: 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 73 6f s returned if so
2bb0: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 me other process
2bc0: 20 69 73 20 6d 65 73 73 69 6e 67 20 77 69 74 68 is messing with
2bd0: 0a 66 69 6c 65 20 6c 6f 63 6b 73 20 61 6e 64 20 .file locks and
2be0: 68 61 73 20 76 69 6f 6c 61 74 65 64 20 74 68 65 has violated the
2bf0: 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 70 72 file locking pr
2c00: 6f 74 6f 63 6f 6c 20 74 68 61 74 20 53 51 4c 69 otocol that SQLi
2c10: 74 65 20 75 73 65 73 0a 6f 6e 20 69 74 73 20 72 te uses.on its r
2c20: 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 ollback journal
2c30: 66 69 6c 65 73 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e files..</p></dd>
2c40: 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 53 43 48 45 .<dt>SQLITE_SCHE
2c50: 4d 41 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 57 MA</dt>.<dd><p>W
2c60: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
2c70: 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2c 20 53 first opened, S
2c80: 51 4c 69 74 65 20 72 65 61 64 73 20 74 68 65 20 QLite reads the
2c90: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 0a database schema.
2ca0: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 61 6e 64 20 into memory and
2cb0: 75 73 65 73 20 74 68 61 74 20 73 63 68 65 6d 61 uses that schema
2cc0: 20 74 6f 20 70 61 72 73 65 20 6e 65 77 20 53 51 to parse new SQ
2cd0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 49 L statements. I
2ce0: 66 20 61 6e 6f 74 68 65 72 0a 70 72 6f 63 65 73 f another.proces
2cf0: 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 73 63 s changes the sc
2d00: 68 65 6d 61 2c 20 74 68 65 20 63 6f 6d 6d 61 6e hema, the comman
2d10: 64 20 63 75 72 72 65 6e 74 6c 79 20 62 65 69 6e d currently bein
2d20: 67 20 70 72 6f 63 65 73 73 65 64 20 77 69 6c 6c g processed will
2d30: 0a 61 62 6f 72 74 20 62 65 63 61 75 73 65 20 74 .abort because t
2d40: 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 he virtual machi
2d50: 6e 65 20 63 6f 64 65 20 67 65 6e 65 72 61 74 65 ne code generate
2d60: 64 20 61 73 73 75 6d 65 64 20 74 68 65 20 6f 6c d assumed the ol
2d70: 64 0a 73 63 68 65 6d 61 2e 20 20 54 68 69 73 20 d.schema. This
2d80: 69 73 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f is the return co
2d90: 64 65 20 66 6f 72 20 73 75 63 68 20 63 61 73 65 de for such case
2da0: 73 2e 20 20 52 65 74 72 79 69 6e 67 20 74 68 65 s. Retrying the
2db0: 0a 63 6f 6d 6d 61 6e 64 20 75 73 75 61 6c 6c 79 .command usually
2dc0: 20 77 69 6c 6c 20 63 6c 65 61 72 20 74 68 65 20 will clear the
2dd0: 70 72 6f 62 6c 65 6d 2e 0a 3c 2f 70 3e 3c 2f 64 problem..</p></d
2de0: 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 54 4f d>.<dt>SQLITE_TO
2df0: 4f 42 49 47 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 OBIG</dt>.<dd><p
2e00: 3e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 >SQLite will not
2e10: 20 73 74 6f 72 65 20 6d 6f 72 65 20 74 68 61 6e store more than
2e20: 20 61 62 6f 75 74 20 31 20 6d 65 67 61 62 79 74 about 1 megabyt
2e30: 65 20 6f 66 20 64 61 74 61 20 69 6e 20 61 20 73 e of data in a s
2e40: 69 6e 67 6c 65 0a 72 6f 77 20 6f 66 20 61 20 73 ingle.row of a s
2e50: 69 6e 67 6c 65 20 74 61 62 6c 65 2e 20 20 49 66 ingle table. If
2e60: 20 79 6f 75 20 61 74 74 65 6d 70 74 20 74 6f 20 you attempt to
2e70: 73 74 6f 72 65 20 6d 6f 72 65 20 74 68 61 6e 20 store more than
2e80: 31 20 6d 65 67 61 62 79 74 65 0a 69 6e 20 61 20 1 megabyte.in a
2e90: 73 69 6e 67 6c 65 20 72 6f 77 2c 20 74 68 69 73 single row, this
2ea0: 20 69 73 20 74 68 65 20 72 65 74 75 72 6e 20 63 is the return c
2eb0: 6f 64 65 20 79 6f 75 20 67 65 74 2e 0a 3c 2f 70 ode you get..</p
2ec0: 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 ></dd>.<dt>SQLIT
2ed0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 3c 2f 64 74 E_CONSTRAINT</dt
2ee0: 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 63 6f >.<dd><p>This co
2ef0: 6e 73 74 61 6e 74 20 69 73 20 72 65 74 75 72 6e nstant is return
2f00: 65 64 20 69 66 20 74 68 65 20 53 51 4c 20 73 74 ed if the SQL st
2f10: 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 20 68 61 atement would ha
2f20: 76 65 20 76 69 6f 6c 61 74 65 64 0a 61 20 64 61 ve violated.a da
2f30: 74 61 62 61 73 65 20 63 6f 6e 73 74 72 61 69 6e tabase constrain
2f40: 74 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 t..</p></dd>.<dt
2f50: 3e 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 >SQLITE_MISMATCH
2f60: 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 </dt>.<dd><p>Thi
2f70: 73 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 s error occurs w
2f80: 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 6e 20 hen there is an
2f90: 61 74 74 65 6d 70 74 20 74 6f 20 69 6e 73 65 72 attempt to inser
2fa0: 74 20 6e 6f 6e 2d 69 6e 74 65 67 65 72 0a 64 61 t non-integer.da
2fb0: 74 61 20 69 6e 74 6f 20 61 20 63 6f 6c 75 6d 6e ta into a column
2fc0: 20 6c 61 62 65 6c 65 64 20 49 4e 54 45 47 45 52 labeled INTEGER
2fd0: 20 50 52 49 4d 41 52 59 20 4b 45 59 2e 20 20 46 PRIMARY KEY. F
2fe0: 6f 72 20 6d 6f 73 74 20 63 6f 6c 75 6d 6e 73 2c or most columns,
2ff0: 20 53 51 4c 69 74 65 0a 69 67 6e 6f 72 65 73 20 SQLite.ignores
3000: 74 68 65 20 64 61 74 61 20 74 79 70 65 20 61 6e the data type an
3010: 64 20 61 6c 6c 6f 77 73 20 61 6e 79 20 6b 69 6e d allows any kin
3020: 64 20 6f 66 20 64 61 74 61 20 74 6f 20 62 65 20 d of data to be
3030: 73 74 6f 72 65 64 2e 20 20 42 75 74 0a 61 6e 20 stored. But.an
3040: 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 INTEGER PRIMARY
3050: 4b 45 59 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 6e KEY column is on
3060: 6c 79 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 74 ly allowed to st
3070: 6f 72 65 20 69 6e 74 65 67 65 72 20 64 61 74 61 ore integer data
3080: 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 2f 64 6c ..</p></dd>.</dl
3090: 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a >.</blockquote>.
30a0: 0a 3c 68 32 3e 54 68 65 20 45 78 74 65 6e 64 65 .<h2>The Extende
30b0: 64 20 41 50 49 3c 2f 68 32 3e 0a 0a 3c 70 3e 4f d API</h2>..<p>O
30c0: 6e 6c 79 20 74 68 65 20 74 68 72 65 65 20 63 6f nly the three co
30d0: 72 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 77 re routines show
30e0: 6e 20 61 62 6f 76 65 20 61 72 65 20 72 65 71 75 n above are requ
30f0: 69 72 65 64 20 74 6f 20 75 73 65 0a 53 51 4c 69 ired to use.SQLi
3100: 74 65 2e 20 20 42 75 74 20 74 68 65 72 65 20 61 te. But there a
3110: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 66 75 re many other fu
3120: 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 70 72 6f nctions that pro
3130: 76 69 64 65 20 0a 75 73 65 66 75 6c 20 69 6e 74 vide .useful int
3140: 65 72 66 61 63 65 73 2e 20 20 54 68 65 73 65 20 erfaces. These
3150: 65 78 74 65 6e 64 65 64 20 72 6f 75 74 69 6e 65 extended routine
3160: 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 s are as follows
3170: 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 :.</p>..<blockqu
3180: 6f 74 65 3e 3c 70 72 65 3e 0a 69 6e 74 20 73 71 ote><pre>.int sq
3190: 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 28 0a lite_get_table(.
31a0: 20 20 73 71 6c 69 74 65 2a 2c 0a 20 20 63 68 61 sqlite*,. cha
31b0: 72 20 2a 73 71 6c 2c 0a 20 20 63 68 61 72 20 2a r *sql,. char *
31c0: 2a 2a 72 65 73 75 6c 74 2c 0a 20 20 69 6e 74 20 **result,. int
31d0: 2a 6e 72 6f 77 2c 0a 20 20 69 6e 74 20 2a 6e 63 *nrow,. int *nc
31e0: 6f 6c 75 6d 6e 2c 0a 20 20 63 68 61 72 20 2a 2a olumn,. char **
31f0: 65 72 72 6d 73 67 0a 29 3b 0a 0a 76 6f 69 64 20 errmsg.);..void
3200: 73 71 6c 69 74 65 5f 66 72 65 65 5f 74 61 62 6c sqlite_free_tabl
3210: 65 28 63 68 61 72 2a 2a 29 3b 0a 0a 76 6f 69 64 e(char**);..void
3220: 20 73 71 6c 69 74 65 5f 69 6e 74 65 72 72 75 70 sqlite_interrup
3230: 74 28 73 71 6c 69 74 65 2a 29 3b 0a 0a 69 6e 74 t(sqlite*);..int
3240: 20 73 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 65 sqlite_complete
3250: 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c (const char *sql
3260: 29 3b 0a 0a 76 6f 69 64 20 73 71 6c 69 74 65 5f );..void sqlite_
3270: 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c busy_handler(sql
3280: 69 74 65 2a 2c 20 69 6e 74 20 28 2a 29 28 76 6f ite*, int (*)(vo
3290: 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c id*,const char*,
32a0: 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 76 int), void*);..v
32b0: 6f 69 64 20 73 71 6c 69 74 65 5f 62 75 73 79 5f oid sqlite_busy_
32c0: 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 2a 2c timeout(sqlite*,
32d0: 20 69 6e 74 20 6d 73 29 3b 0a 0a 63 6f 6e 73 74 int ms);..const
32e0: 20 63 68 61 72 20 73 71 6c 69 74 65 5f 76 65 72 char sqlite_ver
32f0: 73 69 6f 6e 5b 5d 3b 0a 0a 63 6f 6e 73 74 20 63 sion[];..const c
3300: 68 61 72 20 73 71 6c 69 74 65 5f 65 6e 63 6f 64 har sqlite_encod
3310: 69 6e 67 5b 5d 3b 0a 0a 69 6e 74 20 73 71 6c 69 ing[];..int sqli
3320: 74 65 5f 65 78 65 63 5f 70 72 69 6e 74 66 28 0a te_exec_printf(.
3330: 20 20 73 71 6c 69 74 65 2a 2c 0a 20 20 63 68 61 sqlite*,. cha
3340: 72 20 2a 73 71 6c 2c 0a 20 20 69 6e 74 20 28 2a r *sql,. int (*
3350: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 )(void*,int,char
3360: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 0a 20 20 76 6f **,char**),. vo
3370: 69 64 2a 2c 0a 20 20 63 68 61 72 20 2a 2a 65 72 id*,. char **er
3380: 72 6d 73 67 2c 0a 20 20 2e 2e 2e 0a 29 3b 0a 0a rmsg,. ....);..
3390: 69 6e 74 20 73 71 6c 69 74 65 5f 65 78 65 63 5f int sqlite_exec_
33a0: 76 70 72 69 6e 74 66 28 0a 20 20 73 71 6c 69 74 vprintf(. sqlit
33b0: 65 2a 2c 0a 20 20 63 68 61 72 20 2a 73 71 6c 2c e*,. char *sql,
33c0: 0a 20 20 69 6e 74 20 28 2a 29 28 76 6f 69 64 2a . int (*)(void*
33d0: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 ,int,char**,char
33e0: 2a 2a 29 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 **),. void*,.
33f0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 2c 0a 20 char **errmsg,.
3400: 20 76 61 5f 6c 69 73 74 0a 29 3b 0a 0a 69 6e 74 va_list.);..int
3410: 20 73 71 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c sqlite_get_tabl
3420: 65 5f 70 72 69 6e 74 66 28 0a 20 20 73 71 6c 69 e_printf(. sqli
3430: 74 65 2a 2c 0a 20 20 63 68 61 72 20 2a 73 71 6c te*,. char *sql
3440: 2c 0a 20 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 ,. char ***resu
3450: 6c 74 2c 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c lt,. int *nrow,
3460: 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c . int *ncolumn,
3470: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 . char **errmsg
3480: 2c 0a 20 20 2e 2e 2e 0a 29 3b 0a 0a 69 6e 74 20 ,. ....);..int
3490: 73 71 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 sqlite_get_table
34a0: 5f 76 70 72 69 6e 74 66 28 0a 20 20 73 71 6c 69 _vprintf(. sqli
34b0: 74 65 2a 2c 0a 20 20 63 68 61 72 20 2a 73 71 6c te*,. char *sql
34c0: 2c 0a 20 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 ,. char ***resu
34d0: 6c 74 2c 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c lt,. int *nrow,
34e0: 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c . int *ncolumn,
34f0: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 . char **errmsg
3500: 2c 0a 20 20 76 61 5f 6c 69 73 74 0a 29 3b 0a 0a ,. va_list.);..
3510: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
3520: 74 65 3e 0a 0a 3c 70 3e 41 6c 6c 20 6f 66 20 74 te>..<p>All of t
3530: 68 65 20 61 62 6f 76 65 20 64 65 66 69 6e 69 74 he above definit
3540: 69 6f 6e 73 20 61 72 65 20 69 6e 63 6c 75 64 65 ions are include
3550: 64 20 69 6e 20 74 68 65 20 22 73 71 6c 69 74 65 d in the "sqlite
3560: 2e 68 22 0a 68 65 61 64 65 72 20 66 69 6c 65 20 .h".header file
3570: 74 68 61 74 20 63 6f 6d 65 73 20 69 6e 20 74 68 that comes in th
3580: 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f e source tree.</
3590: 70 3e 0a 0a 3c 68 32 3e 51 75 65 72 79 69 6e 67 p>..<h2>Querying
35a0: 20 77 69 74 68 6f 75 74 20 75 73 69 6e 67 20 61 without using a
35b0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
35c0: 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65 20 on</h2>..<p>The
35d0: 3c 62 3e 73 71 6c 69 74 65 5f 67 65 74 5f 74 61 <b>sqlite_get_ta
35e0: 62 6c 65 28 29 3c 2f 62 3e 20 66 75 6e 63 74 69 ble()</b> functi
35f0: 6f 6e 20 69 73 20 61 20 77 72 61 70 70 65 72 20 on is a wrapper
3600: 61 72 6f 75 6e 64 0a 3c 62 3e 73 71 6c 69 74 65 around.<b>sqlite
3610: 5f 65 78 65 63 28 29 3c 2f 62 3e 20 74 68 61 74 _exec()</b> that
3620: 20 63 6f 6c 6c 65 63 74 73 20 61 6c 6c 20 74 68 collects all th
3630: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 66 72 e information fr
3640: 6f 6d 20 73 75 63 63 65 73 73 69 76 65 0a 63 61 om successive.ca
3650: 6c 6c 62 61 63 6b 73 20 61 6e 64 20 77 72 69 74 llbacks and writ
3660: 65 20 69 74 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 e it into memory
3670: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d obtained from m
3680: 61 6c 6c 6f 63 28 29 2e 20 20 54 68 69 73 0a 69 alloc(). This.i
3690: 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 s a convenience
36a0: 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 61 6c function that al
36b0: 6c 6f 77 73 20 74 68 65 20 61 70 70 6c 69 63 61 lows the applica
36c0: 74 69 6f 6e 20 74 6f 20 67 65 74 20 74 68 65 0a tion to get the.
36d0: 65 6e 74 69 72 65 20 72 65 73 75 6c 74 20 6f 66 entire result of
36e0: 20 61 20 64 61 74 61 62 61 73 65 20 71 75 65 72 a database quer
36f0: 79 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 y with a single
3700: 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 2e 3c 2f function call.</
3710: 70 3e 0a 0a 3c 70 3e 54 68 65 20 6d 61 69 6e 20 p>..<p>The main
3720: 72 65 73 75 6c 74 20 66 72 6f 6d 20 3c 62 3e 73 result from <b>s
3730: 71 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 28 qlite_get_table(
3740: 29 3c 2f 62 3e 20 69 73 20 61 6e 20 61 72 72 61 )</b> is an arra
3750: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 0a 74 6f y of pointers.to
3760: 20 73 74 72 69 6e 67 73 2e 20 20 54 68 65 72 65 strings. There
3770: 20 69 73 20 6f 6e 65 20 65 6c 65 6d 65 6e 74 20 is one element
3780: 69 6e 20 74 68 69 73 20 61 72 72 61 79 20 66 6f in this array fo
3790: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 6f 66 r each column of
37a0: 0a 65 61 63 68 20 72 6f 77 20 69 6e 20 74 68 65 .each row in the
37b0: 20 72 65 73 75 6c 74 2e 20 20 4e 55 4c 4c 20 72 result. NULL r
37c0: 65 73 75 6c 74 73 20 61 72 65 20 72 65 70 72 65 esults are repre
37d0: 73 65 6e 74 65 64 20 62 79 20 61 20 4e 55 4c 4c sented by a NULL
37e0: 0a 70 6f 69 6e 74 65 72 2e 20 49 6e 20 61 64 64 .pointer. In add
37f0: 69 74 69 6f 6e 20 74 6f 20 74 68 65 20 72 65 67 ition to the reg
3800: 75 6c 61 72 20 64 61 74 61 2c 20 74 68 65 72 65 ular data, there
3810: 20 69 73 20 61 6e 20 61 64 64 65 64 20 72 6f 77 is an added row
3820: 20 61 74 20 74 68 65 20 0a 62 65 67 69 6e 6e 69 at the .beginni
3830: 6e 67 20 6f 66 20 74 68 65 20 61 72 72 61 79 20 ng of the array
3840: 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 that contains th
3850: 65 20 6e 61 6d 65 73 20 6f 66 20 65 61 63 68 20 e names of each
3860: 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 72 65 column of the.re
3870: 73 75 6c 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e 41 73 sult.</p>..<p>As
3880: 20 61 6e 20 65 78 61 6d 70 6c 65 2c 20 63 6f 6e an example, con
3890: 73 69 64 65 72 20 74 68 65 20 66 6f 6c 6c 6f 77 sider the follow
38a0: 69 6e 67 20 71 75 65 72 79 3a 3c 2f 70 3e 0a 0a ing query:</p>..
38b0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 53 45 4c <blockquote>.SEL
38c0: 45 43 54 20 65 6d 70 6c 6f 79 65 65 5f 6e 61 6d ECT employee_nam
38d0: 65 2c 20 6c 6f 67 69 6e 2c 20 68 6f 73 74 20 46 e, login, host F
38e0: 52 4f 4d 20 75 73 65 72 73 20 57 48 45 52 45 20 ROM users WHERE
38f0: 6c 6f 67 69 63 20 4c 49 4b 45 20 27 64 25 27 3b logic LIKE 'd%';
3900: 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a .</blockquote>..
3910: 3c 70 3e 54 68 69 73 20 71 75 65 72 79 20 77 69 <p>This query wi
3920: 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 ll return the na
3930: 6d 65 2c 20 6c 6f 67 69 6e 20 61 6e 64 20 68 6f me, login and ho
3940: 73 74 20 63 6f 6d 70 75 74 65 72 20 6e 61 6d 65 st computer name
3950: 0a 66 6f 72 20 65 76 65 72 79 20 65 6d 70 6c 6f .for every emplo
3960: 79 65 65 20 77 68 6f 73 65 20 6c 6f 67 69 6e 20 yee whose login
3970: 62 65 67 69 6e 73 20 77 69 74 68 20 74 68 65 20 begins with the
3980: 6c 65 74 74 65 72 20 22 64 22 2e 20 20 49 66 20 letter "d". If
3990: 74 68 69 73 0a 71 75 65 72 79 20 69 73 20 73 75 this.query is su
39a0: 62 6d 69 74 74 65 64 20 74 6f 20 3c 62 3e 73 71 bmitted to <b>sq
39b0: 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 28 29 lite_get_table()
39c0: 3c 2f 62 3e 20 74 68 65 20 72 65 73 75 6c 74 20 </b> the result
39d0: 6d 69 67 68 74 0a 6c 6f 6f 6b 20 6c 69 6b 65 20 might.look like
39e0: 74 68 69 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 this:</p>..<bloc
39f0: 6b 71 75 6f 74 65 3e 0a 6e 72 6f 77 20 3d 20 32 kquote>.nrow = 2
3a00: 3c 62 72 3e 0a 6e 63 6f 6c 75 6d 6e 20 3d 20 33 <br>.ncolumn = 3
3a10: 3c 62 72 3e 0a 72 65 73 75 6c 74 5b 30 5d 20 3d <br>.result[0] =
3a20: 20 22 65 6d 70 6c 6f 79 65 65 5f 6e 61 6d 65 22 "employee_name"
3a30: 3c 62 72 3e 0a 72 65 73 75 6c 74 5b 31 5d 20 3d <br>.result[1] =
3a40: 20 22 6c 6f 67 69 6e 22 3c 62 72 3e 0a 72 65 73 "login"<br>.res
3a50: 75 6c 74 5b 32 5d 20 3d 20 22 68 6f 73 74 22 3c ult[2] = "host"<
3a60: 62 72 3e 0a 72 65 73 75 6c 74 5b 33 5d 20 3d 20 br>.result[3] =
3a70: 22 64 75 6d 6d 79 22 3c 62 72 3e 0a 72 65 73 75 "dummy"<br>.resu
3a80: 6c 74 5b 34 5d 20 3d 20 22 4e 6f 20 73 75 63 68 lt[4] = "No such
3a90: 20 75 73 65 72 22 3c 62 72 3e 0a 72 65 73 75 6c user"<br>.resul
3aa0: 74 5b 35 5d 20 3d 20 30 3c 62 72 3e 0a 72 65 73 t[5] = 0<br>.res
3ab0: 75 6c 74 5b 36 5d 20 3d 20 22 44 2e 20 52 69 63 ult[6] = "D. Ric
3ac0: 68 61 72 64 20 48 69 70 70 22 3c 62 72 3e 0a 72 hard Hipp"<br>.r
3ad0: 65 73 75 6c 74 5b 37 5d 20 3d 20 22 64 72 68 22 esult[7] = "drh"
3ae0: 3c 62 72 3e 0a 72 65 73 75 6c 74 5b 38 5d 20 3d <br>.result[8] =
3af0: 20 22 7a 61 64 6f 6b 22 0a 3c 2f 62 6c 6f 63 6b "zadok".</block
3b00: 71 75 6f 74 65 3e 0a 0a 3c 70 3e 4e 6f 74 69 63 quote>..<p>Notic
3b10: 65 20 74 68 61 74 20 74 68 65 20 22 68 6f 73 74 e that the "host
3b20: 22 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 " value for the
3b30: 22 64 75 6d 6d 79 22 20 72 65 63 6f 72 64 20 69 "dummy" record i
3b40: 73 20 4e 55 4c 4c 20 73 6f 0a 74 68 65 20 72 65 s NULL so.the re
3b50: 73 75 6c 74 5b 5d 20 61 72 72 61 79 20 63 6f 6e sult[] array con
3b60: 74 61 69 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 tains a NULL poi
3b70: 6e 74 65 72 20 61 74 20 74 68 61 74 20 73 6c 6f nter at that slo
3b80: 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e 49 66 20 74 68 t.</p>..<p>If th
3b90: 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 e result set of
3ba0: 61 20 71 75 65 72 79 20 69 73 20 65 6d 70 74 79 a query is empty
3bb0: 2c 20 74 68 65 6e 20 62 79 20 64 65 66 61 75 6c , then by defaul
3bc0: 74 0a 3c 62 3e 73 71 6c 69 74 65 5f 67 65 74 5f t.<b>sqlite_get_
3bd0: 74 61 62 6c 65 28 29 3c 2f 62 3e 20 77 69 6c 6c table()</b> will
3be0: 20 73 65 74 20 6e 72 6f 77 20 74 6f 20 30 20 61 set nrow to 0 a
3bf0: 6e 64 20 6c 65 61 76 65 20 69 74 73 0a 72 65 73 nd leave its.res
3c00: 75 6c 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 ult parameter is
3c10: 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 42 set to NULL. B
3c20: 75 74 20 69 66 20 74 68 65 20 45 4d 50 54 59 5f ut if the EMPTY_
3c30: 52 45 53 55 4c 54 5f 43 41 4c 4c 42 41 43 4b 53 RESULT_CALLBACKS
3c40: 0a 70 72 61 67 6d 61 20 69 73 20 4f 4e 20 74 68 .pragma is ON th
3c50: 65 6e 20 74 68 65 20 72 65 73 75 6c 74 20 70 61 en the result pa
3c60: 72 61 6d 65 74 65 72 20 69 73 20 69 6e 69 74 69 rameter is initi
3c70: 61 6c 69 7a 65 64 20 74 6f 20 74 68 65 20 6e 61 alized to the na
3c80: 6d 65 73 0a 6f 66 20 74 68 65 20 63 6f 6c 75 6d mes.of the colum
3c90: 6e 73 20 6f 6e 6c 79 2e 20 20 46 6f 72 20 65 78 ns only. For ex
3ca0: 61 6d 70 6c 65 2c 20 63 6f 6e 73 69 64 65 72 20 ample, consider
3cb0: 74 68 69 73 20 71 75 65 72 79 20 77 68 69 63 68 this query which
3cc0: 20 68 61 73 0a 61 6e 20 65 6d 70 74 79 20 72 65 has.an empty re
3cd0: 73 75 6c 74 20 73 65 74 3a 3c 2f 70 3e 0a 0a 3c sult set:</p>..<
3ce0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 53 45 4c 45 blockquote>.SELE
3cf0: 43 54 20 65 6d 70 6c 6f 79 65 65 5f 6e 61 6d 65 CT employee_name
3d00: 2c 20 6c 6f 67 69 6e 2c 20 68 6f 73 74 20 46 52 , login, host FR
3d10: 4f 4d 20 75 73 65 72 73 20 57 48 45 52 45 20 65 OM users WHERE e
3d20: 6d 70 6c 6f 79 65 65 5f 6e 61 6d 65 20 49 53 20 mployee_name IS
3d30: 4e 55 4c 4c 3b 0a 3c 2f 62 6c 6f 63 6b 71 75 6f NULL;.</blockquo
3d40: 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65 20 64 65 66 te>..<p>.The def
3d50: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 67 69 ault behavior gi
3d60: 76 65 73 20 74 68 69 73 20 72 65 73 75 6c 74 73 ves this results
3d70: 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 :.</p>..<blockqu
3d80: 6f 74 65 3e 0a 6e 72 6f 77 20 3d 20 30 3c 62 72 ote>.nrow = 0<br
3d90: 3e 0a 6e 63 6f 6c 75 6d 6e 20 3d 20 30 3c 62 72 >.ncolumn = 0<br
3da0: 3e 0a 72 65 73 75 6c 74 20 3d 20 30 3c 62 72 3e >.result = 0<br>
3db0: 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a .</blockquote>..
3dc0: 3c 70 3e 0a 42 75 74 20 69 66 20 74 68 65 20 45 <p>.But if the E
3dd0: 4d 50 54 59 5f 52 45 53 55 4c 54 5f 43 41 4c 4c MPTY_RESULT_CALL
3de0: 42 41 43 4b 53 20 70 72 61 67 6d 61 20 69 73 20 BACKS pragma is
3df0: 4f 4e 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c ON, then the fol
3e00: 6c 6f 77 69 6e 67 0a 69 73 20 72 65 74 75 72 6e lowing.is return
3e10: 65 64 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b ed:.</p>..<block
3e20: 71 75 6f 74 65 3e 0a 6e 72 6f 77 20 3d 20 30 3c quote>.nrow = 0<
3e30: 62 72 3e 0a 6e 63 6f 6c 75 6d 6e 20 3d 20 33 3c br>.ncolumn = 3<
3e40: 62 72 3e 0a 72 65 73 75 6c 74 5b 30 5d 20 3d 20 br>.result[0] =
3e50: 22 65 6d 70 6c 6f 79 65 65 5f 6e 61 6d 65 22 3c "employee_name"<
3e60: 62 72 3e 0a 72 65 73 75 6c 74 5b 31 5d 20 3d 20 br>.result[1] =
3e70: 22 6c 6f 67 69 6e 22 3c 62 72 3e 0a 72 65 73 75 "login"<br>.resu
3e80: 6c 74 5b 32 5d 20 3d 20 22 68 6f 73 74 22 3c 62 lt[2] = "host"<b
3e90: 72 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e r>.</blockquote>
3ea0: 0a 0a 3c 70 3e 4d 65 6d 6f 72 79 20 74 6f 20 68 ..<p>Memory to h
3eb0: 6f 6c 64 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 old the informat
3ec0: 69 6f 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 ion returned by
3ed0: 3c 62 3e 73 71 6c 69 74 65 5f 67 65 74 5f 74 61 <b>sqlite_get_ta
3ee0: 62 6c 65 28 29 3c 2f 62 3e 0a 69 73 20 6f 62 74 ble()</b>.is obt
3ef0: 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f ained from mallo
3f00: 63 28 29 2e 20 20 42 75 74 20 74 68 65 20 63 61 c(). But the ca
3f10: 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 lling function s
3f20: 68 6f 75 6c 64 20 6e 6f 74 20 74 72 79 0a 74 6f hould not try.to
3f30: 20 66 72 65 65 20 74 68 69 73 20 69 6e 66 6f 72 free this infor
3f40: 6d 61 74 69 6f 6e 20 64 69 72 65 63 74 6c 79 2e mation directly.
3f50: 20 20 49 6e 73 74 65 61 64 2c 20 70 61 73 73 20 Instead, pass
3f60: 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 74 61 62 the complete tab
3f70: 6c 65 0a 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f le.to <b>sqlite_
3f80: 66 72 65 65 5f 74 61 62 6c 65 28 29 3c 2f 62 3e free_table()</b>
3f90: 20 77 68 65 6e 20 74 68 65 20 74 61 62 6c 65 20 when the table
3fa0: 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 is no longer nee
3fb0: 64 65 64 2e 0a 49 74 20 69 73 20 73 61 66 65 20 ded..It is safe
3fc0: 74 6f 20 63 61 6c 6c 20 3c 62 3e 73 71 6c 69 74 to call <b>sqlit
3fd0: 65 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 3c 2f e_free_table()</
3fe0: 62 3e 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 b> with a NULL p
3ff0: 6f 69 6e 74 65 72 20 73 75 63 68 0a 61 73 20 77 ointer such.as w
4000: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
4010: 20 69 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 if the result s
4020: 65 74 20 69 73 20 65 6d 70 74 79 2e 3c 2f 70 3e et is empty.</p>
4030: 0a 0a 3c 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69 ..<p>The <b>sqli
4040: 74 65 5f 67 65 74 5f 74 61 62 6c 65 28 29 3c 2f te_get_table()</
4050: 62 3e 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 b> routine retur
4060: 6e 73 20 74 68 65 20 73 61 6d 65 20 69 6e 74 65 ns the same inte
4070: 67 65 72 0a 72 65 73 75 6c 74 20 63 6f 64 65 20 ger.result code
4080: 61 73 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 as <b>sqlite_exe
4090: 63 28 29 3c 2f 62 3e 2e 3c 2f 70 3e 0a 0a 3c 68 c()</b>.</p>..<h
40a0: 32 3e 49 6e 74 65 72 72 75 70 74 69 6e 67 20 61 2>Interrupting a
40b0: 6e 20 53 51 4c 69 74 65 20 6f 70 65 72 61 74 69 n SQLite operati
40c0: 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65 20 on</h2>..<p>The
40d0: 3c 62 3e 73 71 6c 69 74 65 5f 69 6e 74 65 72 72 <b>sqlite_interr
40e0: 75 70 74 28 29 3c 2f 62 3e 20 66 75 6e 63 74 69 upt()</b> functi
40f0: 6f 6e 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 on can be called
4100: 20 66 72 6f 6d 20 61 0a 64 69 66 66 65 72 65 6e from a.differen
4110: 74 20 74 68 72 65 61 64 20 6f 72 20 66 72 6f 6d t thread or from
4120: 20 61 20 73 69 67 6e 61 6c 20 68 61 6e 64 6c 65 a signal handle
4130: 72 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 63 r to cause the c
4140: 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 0a urrent database.
4150: 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 65 78 69 operation to exi
4160: 74 20 61 74 20 69 74 73 20 66 69 72 73 74 20 6f t at its first o
4170: 70 70 6f 72 74 75 6e 69 74 79 2e 20 20 57 68 65 pportunity. Whe
4180: 6e 20 74 68 69 73 20 68 61 70 70 65 6e 73 2c 0a n this happens,.
4190: 74 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 the <b>sqlite_ex
41a0: 65 63 28 29 3c 2f 62 3e 20 72 6f 75 74 69 6e 65 ec()</b> routine
41b0: 20 28 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c (or the equival
41c0: 65 6e 74 29 20 74 68 61 74 20 73 74 61 72 74 65 ent) that starte
41d0: 64 0a 74 68 65 20 64 61 74 61 62 61 73 65 20 6f d.the database o
41e0: 70 65 72 61 74 69 6f 6e 20 77 69 6c 6c 20 72 65 peration will re
41f0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 49 4e 54 45 turn SQLITE_INTE
4200: 52 52 55 50 54 2e 3c 2f 70 3e 0a 0a 3c 68 32 3e RRUPT.</p>..<h2>
4210: 54 65 73 74 69 6e 67 20 66 6f 72 20 61 20 63 6f Testing for a co
4220: 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 mplete SQL state
4230: 6d 65 6e 74 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 ment</h2>..<p>Th
4240: 65 20 6e 65 78 74 20 69 6e 74 65 72 66 61 63 65 e next interface
4250: 20 72 6f 75 74 69 6e 65 20 74 6f 20 53 51 4c 69 routine to SQLi
4260: 74 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 te is a convenie
4270: 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 75 73 65 nce function use
4280: 64 0a 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 d.to test whethe
4290: 72 20 6f 72 20 6e 6f 74 20 61 20 73 74 72 69 6e r or not a strin
42a0: 67 20 66 6f 72 6d 73 20 61 20 63 6f 6d 70 6c 65 g forms a comple
42b0: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 te SQL statement
42c0: 2e 0a 49 66 20 74 68 65 20 3c 62 3e 73 71 6c 69 ..If the <b>sqli
42d0: 74 65 5f 63 6f 6d 70 6c 65 74 65 28 29 3c 2f 62 te_complete()</b
42e0: 3e 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 > function retur
42f0: 6e 73 20 74 72 75 65 20 77 68 65 6e 20 69 74 73 ns true when its
4300: 20 69 6e 70 75 74 0a 69 73 20 61 20 73 74 72 69 input.is a stri
4310: 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 61 72 67 ng, then the arg
4320: 75 6d 65 6e 74 20 66 6f 72 6d 73 20 61 20 63 6f ument forms a co
4330: 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 mplete SQL state
4340: 6d 65 6e 74 2e 0a 54 68 65 72 65 20 61 72 65 20 ment..There are
4350: 6e 6f 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 no guarantees th
4360: 61 74 20 74 68 65 20 73 79 6e 74 61 78 20 6f 66 at the syntax of
4370: 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 that statement
4380: 69 73 20 63 6f 72 72 65 63 74 2c 0a 62 75 74 20 is correct,.but
4390: 77 65 20 61 74 20 6c 65 61 73 74 20 6b 6e 6f 77 we at least know
43a0: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
43b0: 73 20 63 6f 6d 70 6c 65 74 65 2e 20 20 49 66 20 s complete. If
43c0: 3c 62 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 <b>sqlite_comple
43d0: 74 65 28 29 3c 2f 62 3e 0a 72 65 74 75 72 6e 73 te()</b>.returns
43e0: 20 66 61 6c 73 65 2c 20 74 68 65 6e 20 6d 6f 72 false, then mor
43f0: 65 20 74 65 78 74 20 69 73 20 72 65 71 75 69 72 e text is requir
4400: 65 64 20 74 6f 20 63 6f 6d 70 6c 65 74 65 20 74 ed to complete t
4410: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
4420: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 46 6f 72 20 74 68 .</p>..<p>For th
4430: 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 65 e purpose of the
4440: 20 3c 62 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 6c <b>sqlite_compl
4450: 65 74 65 28 29 3c 2f 62 3e 20 66 75 6e 63 74 69 ete()</b> functi
4460: 6f 6e 2c 20 61 6e 20 53 51 4c 0a 73 74 61 74 65 on, an SQL.state
4470: 6d 65 6e 74 20 69 73 20 63 6f 6d 70 6c 65 74 65 ment is complete
4480: 20 69 66 20 69 74 20 65 6e 64 73 20 69 6e 20 61 if it ends in a
4490: 20 73 65 6d 69 63 6f 6c 6f 6e 2e 3c 2f 70 3e 0a semicolon.</p>.
44a0: 0a 3c 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69 74 .<p>The <b>sqlit
44b0: 65 3c 2f 62 3e 20 63 6f 6d 6d 61 6e 64 2d 6c 69 e</b> command-li
44c0: 6e 65 20 75 74 69 6c 69 74 79 20 75 73 65 73 20 ne utility uses
44d0: 74 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 63 6f the <b>sqlite_co
44e0: 6d 70 6c 65 74 65 28 29 3c 2f 62 3e 0a 66 75 6e mplete()</b>.fun
44f0: 63 74 69 6f 6e 20 74 6f 20 6b 6e 6f 77 20 77 68 ction to know wh
4500: 65 6e 20 69 74 20 6e 65 65 64 73 20 74 6f 20 63 en it needs to c
4510: 61 6c 6c 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 all <b>sqlite_ex
4520: 65 63 28 29 3c 2f 62 3e 2e 20 20 41 66 74 65 72 ec()</b>. After
4530: 20 65 61 63 68 0a 6c 69 6e 65 20 6f 66 20 69 6e each.line of in
4540: 70 75 74 20 69 73 20 72 65 63 65 69 76 65 64 2c put is received,
4550: 20 3c 62 3e 73 71 6c 69 74 65 3c 2f 62 3e 20 63 <b>sqlite</b> c
4560: 61 6c 6c 73 20 3c 62 3e 73 71 6c 69 74 65 5f 63 alls <b>sqlite_c
4570: 6f 6d 70 6c 65 74 65 28 29 3c 2f 62 3e 0a 6f 6e omplete()</b>.on
4580: 20 61 6c 6c 20 69 6e 70 75 74 20 69 6e 20 69 74 all input in it
4590: 73 20 62 75 66 66 65 72 2e 20 20 49 66 20 3c 62 s buffer. If <b
45a0: 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 65 >sqlite_complete
45b0: 28 29 3c 2f 62 3e 20 72 65 74 75 72 6e 73 20 74 ()</b> returns t
45c0: 72 75 65 2c 20 0a 74 68 65 6e 20 3c 62 3e 73 71 rue, .then <b>sq
45d0: 6c 69 74 65 5f 65 78 65 63 28 29 3c 2f 62 3e 20 lite_exec()</b>
45e0: 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 is called and th
45f0: 65 20 69 6e 70 75 74 20 62 75 66 66 65 72 20 69 e input buffer i
4600: 73 20 72 65 73 65 74 2e 20 20 49 66 0a 3c 62 3e s reset. If.<b>
4610: 73 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 65 28 sqlite_complete(
4620: 29 3c 2f 62 3e 20 72 65 74 75 72 6e 73 20 66 61 )</b> returns fa
4630: 6c 73 65 2c 20 74 68 65 6e 20 74 68 65 20 70 72 lse, then the pr
4640: 6f 6d 70 74 20 69 73 20 63 68 61 6e 67 65 64 20 ompt is changed
4650: 74 6f 0a 74 68 65 20 63 6f 6e 74 69 6e 75 61 74 to.the continuat
4660: 69 6f 6e 20 70 72 6f 6d 70 74 20 61 6e 64 20 61 ion prompt and a
4670: 6e 6f 74 68 65 72 20 6c 69 6e 65 20 6f 66 20 74 nother line of t
4680: 65 78 74 20 69 73 20 72 65 61 64 20 61 6e 64 20 ext is read and
4690: 61 64 64 65 64 20 74 6f 0a 74 68 65 20 69 6e 70 added to.the inp
46a0: 75 74 20 62 75 66 66 65 72 2e 3c 2f 70 3e 0a 0a ut buffer.</p>..
46b0: 3c 68 32 3e 4c 69 62 72 61 72 79 20 76 65 72 73 <h2>Library vers
46c0: 69 6f 6e 20 73 74 72 69 6e 67 3c 2f 68 32 3e 0a ion string</h2>.
46d0: 0a 3c 70 3e 54 68 65 20 53 51 4c 69 74 65 20 6c .<p>The SQLite l
46e0: 69 62 72 61 72 79 20 65 78 70 6f 72 74 73 20 74 ibrary exports t
46f0: 68 65 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 he string consta
4700: 6e 74 20 6e 61 6d 65 64 0a 3c 62 3e 73 71 6c 69 nt named.<b>sqli
4710: 74 65 5f 76 65 72 73 69 6f 6e 3c 2f 62 3e 20 77 te_version</b> w
4720: 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 hich contains th
4730: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 e version number
4740: 20 6f 66 20 74 68 65 0a 6c 69 62 72 61 72 79 2e of the.library.
4750: 20 20 54 68 65 20 68 65 61 64 65 72 20 66 69 6c The header fil
4760: 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 6d 61 63 e contains a mac
4770: 72 6f 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f ro SQLITE_VERSIO
4780: 4e 0a 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 N.with the same
4790: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 20 49 66 information. If
47a0: 20 64 65 73 69 72 65 64 2c 20 61 20 70 72 6f 67 desired, a prog
47b0: 72 61 6d 20 63 61 6e 20 63 6f 6d 70 61 72 65 0a ram can compare.
47c0: 74 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 the SQLITE_VERSI
47d0: 4f 4e 20 6d 61 63 72 6f 20 61 67 61 69 6e 73 74 ON macro against
47e0: 20 74 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 76 the <b>sqlite_v
47f0: 65 72 73 69 6f 6e 3c 2f 62 3e 0a 73 74 72 69 6e ersion</b>.strin
4800: 67 20 63 6f 6e 73 74 61 6e 74 20 74 6f 20 76 65 g constant to ve
4810: 72 69 66 79 20 74 68 61 74 20 74 68 65 20 76 65 rify that the ve
4820: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 6f 66 20 rsion number of
4830: 74 68 65 0a 68 65 61 64 65 72 20 66 69 6c 65 20 the.header file
4840: 61 6e 64 20 74 68 65 20 6c 69 62 72 61 72 79 20 and the library
4850: 6d 61 74 63 68 2e 3c 2f 70 3e 20 0a 0a 3c 68 32 match.</p> ..<h2
4860: 3e 4c 69 62 72 61 72 79 20 63 68 61 72 61 63 74 >Library charact
4870: 65 72 20 65 6e 63 6f 64 69 6e 67 3c 2f 68 32 3e er encoding</h2>
4880: 0a 0a 3c 70 3e 42 79 20 64 65 66 61 75 6c 74 2c ..<p>By default,
4890: 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 SQLite assumes
48a0: 74 68 61 74 20 61 6c 6c 20 64 61 74 61 20 75 73 that all data us
48b0: 65 73 20 61 20 66 69 78 65 64 2d 73 69 7a 65 0a es a fixed-size.
48c0: 38 2d 62 69 74 20 63 68 61 72 61 63 74 65 72 20 8-bit character
48d0: 28 69 73 6f 38 38 35 39 29 2e 20 20 42 75 74 20 (iso8859). But
48e0: 69 66 20 79 6f 75 20 67 69 76 65 20 74 68 65 20 if you give the
48f0: 2d 2d 65 6e 61 62 6c 65 2d 75 74 66 38 20 6f 70 --enable-utf8 op
4900: 74 69 6f 6e 0a 74 6f 20 74 68 65 20 63 6f 6e 66 tion.to the conf
4910: 69 67 75 72 65 20 73 63 72 69 70 74 2c 20 74 68 igure script, th
4920: 65 6e 20 74 68 65 20 6c 69 62 72 61 72 79 20 61 en the library a
4930: 73 73 75 6d 65 73 20 55 54 46 2d 38 20 76 61 72 ssumes UTF-8 var
4940: 69 61 62 6c 65 0a 73 69 7a 65 64 20 63 68 61 72 iable.sized char
4950: 61 63 74 65 72 73 2e 20 20 54 68 69 73 20 6d 61 acters. This ma
4960: 6b 65 73 20 61 20 64 69 66 66 65 72 65 6e 63 65 kes a difference
4970: 20 66 6f 72 20 74 68 65 20 4c 49 4b 45 20 61 6e for the LIKE an
4980: 64 20 47 4c 4f 42 0a 6f 70 65 72 61 74 6f 72 73 d GLOB.operators
4990: 20 61 6e 64 20 74 68 65 20 4c 45 4e 47 54 48 28 and the LENGTH(
49a0: 29 20 61 6e 64 20 53 55 42 53 54 52 28 29 20 66 ) and SUBSTR() f
49b0: 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 65 20 73 unctions. The s
49c0: 74 61 74 69 63 0a 73 74 72 69 6e 67 20 3c 62 3e tatic.string <b>
49d0: 73 71 6c 69 74 65 5f 65 6e 63 6f 64 69 6e 67 3c sqlite_encoding<
49e0: 2f 62 3e 20 77 69 6c 6c 20 62 65 20 73 65 74 20 /b> will be set
49f0: 74 6f 20 65 69 74 68 65 72 20 22 55 54 46 2d 38 to either "UTF-8
4a00: 22 20 6f 72 0a 22 69 73 6f 38 38 35 39 22 20 74 " or."iso8859" t
4a10: 6f 20 69 6e 64 69 63 61 74 65 20 68 6f 77 20 74 o indicate how t
4a20: 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 he library was c
4a30: 6f 6d 70 69 6c 65 64 2e 20 20 49 6e 20 61 64 64 ompiled. In add
4a40: 69 74 69 6f 6e 2c 0a 74 68 65 20 3c 62 3e 73 71 ition,.the <b>sq
4a50: 6c 69 74 65 2e 68 3c 2f 62 3e 20 68 65 61 64 65 lite.h</b> heade
4a60: 72 20 66 69 6c 65 20 77 69 6c 6c 20 64 65 66 69 r file will defi
4a70: 6e 65 20 6f 6e 65 20 6f 66 20 74 68 65 0a 6d 61 ne one of the.ma
4a80: 63 72 6f 73 20 3c 62 3e 53 51 4c 49 54 45 5f 55 cros <b>SQLITE_U
4a90: 54 46 38 3c 2f 62 3e 20 6f 72 20 3c 62 3e 53 51 TF8</b> or <b>SQ
4aa0: 4c 49 54 45 5f 49 53 4f 38 38 35 39 3c 2f 62 3e LITE_ISO8859</b>
4ab0: 2c 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 , as appropriate
4ac0: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 4e 6f 74 65 20 74 .</p>..<p>Note t
4ad0: 68 61 74 20 74 68 65 20 63 68 61 72 61 63 74 65 hat the characte
4ae0: 72 20 65 6e 63 6f 64 69 6e 67 20 6d 65 63 68 61 r encoding mecha
4af0: 6e 69 73 6d 20 75 73 65 64 20 62 79 20 53 51 4c nism used by SQL
4b00: 69 74 65 20 63 61 6e 6e 6f 74 0a 62 65 20 63 68 ite cannot.be ch
4b10: 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74 69 6d anged at run-tim
4b20: 65 2e 20 20 54 68 69 73 20 69 73 20 61 20 63 6f e. This is a co
4b30: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
4b40: 6e 20 6f 6e 6c 79 2e 20 20 54 68 65 0a 3c 62 3e n only. The.<b>
4b50: 73 71 6c 69 74 65 5f 65 6e 63 6f 64 69 6e 67 3c sqlite_encoding<
4b60: 2f 62 3e 20 63 68 61 72 61 63 74 65 72 20 73 74 /b> character st
4b70: 72 69 6e 67 20 6a 75 73 74 20 74 65 6c 6c 73 20 ring just tells
4b80: 79 6f 75 20 68 6f 77 20 74 68 65 20 6c 69 62 72 you how the libr
4b90: 61 72 79 0a 77 61 73 20 63 6f 6d 70 69 6c 65 64 ary.was compiled
4ba0: 2e 3c 2f 70 3e 0a 0a 3c 68 32 3e 43 68 61 6e 67 .</p>..<h2>Chang
4bb0: 69 6e 67 20 74 68 65 20 6c 69 62 72 61 72 79 27 ing the library'
4bc0: 73 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 6c 6f s response to lo
4bd0: 63 6b 65 64 20 66 69 6c 65 73 3c 2f 68 32 3e 0a cked files</h2>.
4be0: 0a 3c 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69 74 .<p>The <b>sqlit
4bf0: 65 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 e_busy_handler()
4c00: 3c 2f 62 3e 20 70 72 6f 63 65 64 75 72 65 20 63 </b> procedure c
4c10: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 an be used to re
4c20: 67 69 73 74 65 72 0a 61 20 62 75 73 79 20 63 61 gister.a busy ca
4c30: 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 6e 20 6f llback with an o
4c40: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 pen SQLite datab
4c50: 61 73 65 2e 20 20 54 68 65 20 62 75 73 79 20 63 ase. The busy c
4c60: 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 0a 62 65 20 allback will.be
4c70: 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
4c80: 20 53 51 4c 69 74 65 20 74 72 69 65 73 20 74 6f SQLite tries to
4c90: 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 access a databa
4ca0: 73 65 20 74 68 61 74 20 69 73 20 6c 6f 63 6b 65 se that is locke
4cb0: 64 2e 0a 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 d..The callback
4cc0: 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 64 will typically d
4cd0: 6f 20 73 6f 6d 65 20 6f 74 68 65 72 20 75 73 65 o some other use
4ce0: 66 75 6c 20 77 6f 72 6b 2c 20 6f 72 20 70 65 72 ful work, or per
4cf0: 68 61 70 73 20 73 6c 65 65 70 2c 0a 69 6e 20 6f haps sleep,.in o
4d00: 72 64 65 72 20 74 6f 20 67 69 76 65 20 74 68 65 rder to give the
4d10: 20 6c 6f 63 6b 20 61 20 63 68 61 6e 63 65 20 74 lock a chance t
4d20: 6f 20 63 6c 65 61 72 2e 20 20 49 66 20 74 68 65 o clear. If the
4d30: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
4d40: 73 0a 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e s.non-zero, then
4d50: 20 53 51 4c 69 74 65 20 74 72 69 65 73 20 61 67 SQLite tries ag
4d60: 61 69 6e 20 74 6f 20 61 63 63 65 73 73 20 74 68 ain to access th
4d70: 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 e database and t
4d80: 68 65 20 63 79 63 6c 65 0a 72 65 70 65 61 74 73 he cycle.repeats
4d90: 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 . If the callba
4da0: 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c ck returns zero,
4db0: 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 62 6f then SQLite abo
4dc0: 72 74 73 20 74 68 65 20 63 75 72 72 65 6e 74 0a rts the current.
4dd0: 6f 70 65 72 61 74 69 6f 6e 20 61 6e 64 20 72 65 operation and re
4de0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 42 55 53 turns SQLITE_BUS
4df0: 59 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 61 Y.</p>..<p>The a
4e00: 72 67 75 6d 65 6e 74 73 20 74 6f 20 3c 62 3e 73 rguments to <b>s
4e10: 71 6c 69 74 65 5f 62 75 73 79 5f 68 61 6e 64 6c qlite_busy_handl
4e20: 65 72 28 29 3c 2f 62 3e 20 61 72 65 20 74 68 65 er()</b> are the
4e30: 20 6f 70 61 71 75 65 0a 73 74 72 75 63 74 75 72 opaque.structur
4e40: 65 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 e returned from
4e50: 3c 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e 28 29 <b>sqlite_open()
4e60: 3c 2f 62 3e 2c 20 61 20 70 6f 69 6e 74 65 72 20 </b>, a pointer
4e70: 74 6f 20 74 68 65 20 62 75 73 79 0a 63 61 6c 6c to the busy.call
4e80: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2c 20 61 back function, a
4e90: 6e 64 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 nd a generic poi
4ea0: 6e 74 65 72 20 74 68 61 74 20 77 69 6c 6c 20 62 nter that will b
4eb0: 65 20 70 61 73 73 65 64 20 61 73 0a 74 68 65 20 e passed as.the
4ec0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
4ed0: 6f 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 o the busy callb
4ee0: 61 63 6b 2e 20 20 57 68 65 6e 20 53 51 4c 69 74 ack. When SQLit
4ef0: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 0a 62 75 e invokes the.bu
4f00: 73 79 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 sy callback, it
4f10: 73 65 6e 64 73 20 69 74 20 74 68 72 65 65 20 61 sends it three a
4f20: 72 67 75 6d 65 6e 74 73 3a 20 20 74 68 65 20 67 rguments: the g
4f30: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 0a 74 eneric pointer.t
4f40: 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20 69 hat was passed i
4f50: 6e 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61 n as the third a
4f60: 72 67 75 6d 65 6e 74 20 74 6f 20 3c 62 3e 73 71 rgument to <b>sq
4f70: 6c 69 74 65 5f 62 75 73 79 5f 68 61 6e 64 6c 65 lite_busy_handle
4f80: 72 3c 2f 62 3e 2c 0a 74 68 65 20 6e 61 6d 65 20 r</b>,.the name
4f90: 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
4fa0: 74 61 62 6c 65 20 6f 72 20 69 6e 64 65 78 20 74 table or index t
4fb0: 68 61 74 20 74 68 65 20 6c 69 62 72 61 72 79 20 hat the library
4fc0: 69 73 20 74 72 79 69 6e 67 0a 74 6f 20 61 63 63 is trying.to acc
4fd0: 65 73 73 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d ess, and the num
4fe0: 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 ber of times tha
4ff0: 74 20 74 68 65 20 6c 69 62 72 61 72 79 20 68 61 t the library ha
5000: 73 20 61 74 74 65 6d 70 74 65 64 20 74 6f 0a 61 s attempted to.a
5010: 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 ccess the databa
5020: 73 65 20 74 61 62 6c 65 20 6f 72 20 69 6e 64 65 se table or inde
5030: 78 2e 3c 2f 70 3e 0a 0a 3c 70 3e 46 6f 72 20 74 x.</p>..<p>For t
5040: 68 65 20 63 6f 6d 6d 6f 6e 20 63 61 73 65 20 77 he common case w
5050: 68 65 72 65 20 77 65 20 77 61 6e 74 20 74 68 65 here we want the
5060: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 74 busy callback t
5070: 6f 20 73 6c 65 65 70 2c 0a 74 68 65 20 53 51 4c o sleep,.the SQL
5080: 69 74 65 20 6c 69 62 72 61 72 79 20 70 72 6f 76 ite library prov
5090: 69 64 65 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e ides a convenien
50a0: 63 65 20 72 6f 75 74 69 6e 65 20 3c 62 3e 73 71 ce routine <b>sq
50b0: 6c 69 74 65 5f 62 75 73 79 5f 74 69 6d 65 6f 75 lite_busy_timeou
50c0: 74 28 29 3c 2f 62 3e 2e 0a 54 68 65 20 66 69 72 t()</b>..The fir
50d0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 3c st argument to <
50e0: 62 3e 73 71 6c 69 74 65 5f 62 75 73 79 5f 74 69 b>sqlite_busy_ti
50f0: 6d 65 6f 75 74 28 29 3c 2f 62 3e 20 69 73 20 61 meout()</b> is a
5100: 20 70 6f 69 6e 74 65 72 20 74 6f 0a 61 6e 20 6f pointer to.an o
5110: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 pen SQLite datab
5120: 61 73 65 20 61 6e 64 20 74 68 65 20 73 65 63 6f ase and the seco
5130: 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 nd argument is a
5140: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 number of milli
5150: 73 65 63 6f 6e 64 73 2e 0a 41 66 74 65 72 20 3c seconds..After <
5160: 62 3e 73 71 6c 69 74 65 5f 62 75 73 79 5f 74 69 b>sqlite_busy_ti
5170: 6d 65 6f 75 74 28 29 3c 2f 62 3e 20 68 61 73 20 meout()</b> has
5180: 62 65 65 6e 20 65 78 65 63 75 74 65 64 2c 20 74 been executed, t
5190: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
51a0: 79 0a 77 69 6c 6c 20 77 61 69 74 20 66 6f 72 20 y.will wait for
51b0: 74 68 65 20 6c 6f 63 6b 20 74 6f 20 63 6c 65 61 the lock to clea
51c0: 72 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 74 r for at least t
51d0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c he number of mil
51e0: 6c 69 73 65 63 6f 6e 64 73 20 0a 73 70 65 63 69 liseconds .speci
51f0: 66 69 65 64 20 62 65 66 6f 72 65 20 69 74 20 72 fied before it r
5200: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 42 55 eturns SQLITE_BU
5210: 53 59 2e 20 20 53 70 65 63 69 66 79 69 6e 67 20 SY. Specifying
5220: 7a 65 72 6f 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 zero millisecond
5230: 73 20 66 6f 72 0a 74 68 65 20 74 69 6d 65 6f 75 s for.the timeou
5240: 74 20 72 65 73 74 6f 72 65 73 20 74 68 65 20 64 t restores the d
5250: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 2e efault behavior.
5260: 3c 2f 70 3e 0a 0a 3c 68 32 3e 55 73 69 6e 67 20 </p>..<h2>Using
5270: 74 68 65 20 3c 74 74 3e 5f 70 72 69 6e 74 66 28 the <tt>_printf(
5280: 29 3c 2f 74 74 3e 20 77 72 61 70 70 65 72 20 66 )</tt> wrapper f
5290: 75 6e 63 74 69 6f 6e 73 3c 2f 68 32 3e 0a 0a 3c unctions</h2>..<
52a0: 70 3e 54 68 65 20 66 6f 75 72 20 75 74 69 6c 69 p>The four utili
52b0: 74 79 20 66 75 6e 63 74 69 6f 6e 73 3c 2f 70 3e ty functions</p>
52c0: 0a 0a 3c 70 3e 0a 3c 75 6c 3e 0a 3c 6c 69 3e 3c ..<p>.<ul>.<li><
52d0: 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 5f 70 72 b>sqlite_exec_pr
52e0: 69 6e 74 66 28 29 3c 2f 62 3e 3c 2f 6c 69 3e 0a intf()</b></li>.
52f0: 3c 6c 69 3e 3c 62 3e 73 71 6c 69 74 65 5f 65 78 <li><b>sqlite_ex
5300: 65 63 5f 76 70 72 69 6e 74 66 28 29 3c 2f 62 3e ec_vprintf()</b>
5310: 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c 62 3e 73 71 6c </li>.<li><b>sql
5320: 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 5f 70 72 ite_get_table_pr
5330: 69 6e 74 66 28 29 3c 2f 62 3e 3c 2f 6c 69 3e 0a intf()</b></li>.
5340: 3c 6c 69 3e 3c 62 3e 73 71 6c 69 74 65 5f 67 65 <li><b>sqlite_ge
5350: 74 5f 74 61 62 6c 65 5f 76 70 72 69 6e 74 66 28 t_table_vprintf(
5360: 29 3c 2f 62 3e 3c 2f 6c 69 3e 0a 3c 2f 75 6c 3e )</b></li>.</ul>
5370: 0a 3c 2f 70 3e 0a 0a 3c 70 3e 69 6d 70 6c 65 6d .</p>..<p>implem
5380: 65 6e 74 20 74 68 65 20 73 61 6d 65 20 71 75 65 ent the same que
5390: 72 79 20 66 75 6e 63 74 69 6f 6e 61 6c 69 74 79 ry functionality
53a0: 20 61 73 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 as <b>sqlite_ex
53b0: 65 63 28 29 3c 2f 62 3e 0a 61 6e 64 20 3c 62 3e ec()</b>.and <b>
53c0: 73 71 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 sqlite_get_table
53d0: 28 29 3c 2f 62 3e 2e 20 20 42 75 74 20 69 6e 73 ()</b>. But ins
53e0: 74 65 61 64 20 6f 66 20 74 61 6b 69 6e 67 20 61 tead of taking a
53f0: 20 63 6f 6d 70 6c 65 74 65 0a 53 51 4c 20 73 74 complete.SQL st
5400: 61 74 65 6d 65 6e 74 20 61 73 20 74 68 65 69 72 atement as their
5410: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
5420: 2c 20 74 68 65 20 66 6f 75 72 20 3c 62 3e 5f 70 , the four <b>_p
5430: 72 69 6e 74 66 3c 2f 62 3e 0a 72 6f 75 74 69 6e rintf</b>.routin
5440: 65 73 20 74 61 6b 65 20 61 20 70 72 69 6e 74 66 es take a printf
5450: 2d 73 74 79 6c 65 20 66 6f 72 6d 61 74 20 73 74 -style format st
5460: 72 69 6e 67 2e 20 20 54 68 65 20 53 51 4c 20 73 ring. The SQL s
5470: 74 61 74 65 6d 65 6e 74 20 74 6f 0a 62 65 20 65 tatement to.be e
5480: 78 65 63 75 74 65 64 20 69 73 20 67 65 6e 65 72 xecuted is gener
5490: 61 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 66 ated from this f
54a0: 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 61 6e 64 ormat string and
54b0: 20 66 72 6f 6d 20 77 68 61 74 65 76 65 72 0a 61 from whatever.a
54c0: 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 dditional argume
54d0: 6e 74 73 20 61 72 65 20 61 74 74 61 63 68 65 64 nts are attached
54e0: 20 74 6f 20 74 68 65 20 65 6e 64 20 6f 66 20 74 to the end of t
54f0: 68 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c he function call
5500: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 72 65 20 .</p>..<p>There
5510: 61 72 65 20 74 77 6f 20 61 64 76 61 6e 74 61 67 are two advantag
5520: 65 73 20 74 6f 20 75 73 69 6e 67 20 74 68 65 20 es to using the
5530: 53 51 4c 69 74 65 20 70 72 69 6e 74 66 0a 66 75 SQLite printf.fu
5540: 6e 63 74 69 6f 6e 73 20 69 6e 73 74 65 61 64 20 nctions instead
5550: 6f 66 20 3c 62 3e 73 70 72 69 6e 74 66 28 29 3c of <b>sprintf()<
5560: 2f 62 3e 2e 20 20 46 69 72 73 74 20 6f 66 20 61 /b>. First of a
5570: 6c 6c 2c 20 77 69 74 68 20 74 68 65 0a 53 51 4c ll, with the.SQL
5580: 69 74 65 20 70 72 69 6e 74 66 20 72 6f 75 74 69 ite printf routi
5590: 6e 65 73 2c 20 74 68 65 72 65 20 69 73 20 6e 65 nes, there is ne
55a0: 76 65 72 20 61 20 64 61 6e 67 65 72 20 6f 66 20 ver a danger of
55b0: 6f 76 65 72 66 6c 6f 77 69 6e 67 20 61 0a 73 74 overflowing a.st
55c0: 61 74 69 63 20 62 75 66 66 65 72 20 61 73 20 74 atic buffer as t
55d0: 68 65 72 65 20 69 73 20 77 69 74 68 20 3c 62 3e here is with <b>
55e0: 73 70 72 69 6e 74 66 28 29 3c 2f 62 3e 2e 20 20 sprintf()</b>.
55f0: 54 68 65 20 53 51 4c 69 74 65 0a 70 72 69 6e 74 The SQLite.print
5600: 66 20 72 6f 75 74 69 6e 65 73 20 61 75 74 6f 6d f routines autom
5610: 61 74 69 63 61 6c 6c 79 20 61 6c 6c 6f 63 61 74 atically allocat
5620: 65 20 28 61 6e 64 20 6c 61 74 65 72 20 66 72 65 e (and later fre
5630: 65 29 0a 61 73 20 6d 75 63 68 20 6d 65 6d 6f 72 e).as much memor
5640: 79 20 61 73 20 69 73 20 0a 6e 65 63 65 73 73 61 y as is .necessa
5650: 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 53 ry to hold the S
5660: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 67 65 QL statements ge
5670: 6e 65 72 61 74 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 nerated.</p>..<p
5680: 3e 54 68 65 20 73 65 63 6f 6e 64 20 61 64 76 61 >The second adva
5690: 6e 74 61 67 65 20 74 68 65 20 53 51 4c 69 74 65 ntage the SQLite
56a0: 20 70 72 69 6e 74 66 20 72 6f 75 74 69 6e 65 73 printf routines
56b0: 20 68 61 76 65 20 6f 76 65 72 0a 3c 62 3e 73 70 have over.<b>sp
56c0: 72 69 6e 74 66 28 29 3c 2f 62 3e 20 69 73 20 61 rintf()</b> is a
56d0: 20 6e 65 77 20 66 6f 72 6d 61 74 74 69 6e 67 20 new formatting
56e0: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 63 61 option specifica
56f0: 6c 6c 79 20 64 65 73 69 67 6e 65 64 0a 74 6f 20 lly designed.to
5700: 73 75 70 70 6f 72 74 20 73 74 72 69 6e 67 20 6c support string l
5710: 69 74 65 72 61 6c 73 20 69 6e 20 53 51 4c 2e 20 iterals in SQL.
5720: 20 57 69 74 68 69 6e 20 74 68 65 20 66 6f 72 6d Within the form
5730: 61 74 20 73 74 72 69 6e 67 2c 0a 74 68 65 20 25 at string,.the %
5740: 71 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 q formatting opt
5750: 69 6f 6e 20 77 6f 72 6b 73 20 76 65 72 79 20 6d ion works very m
5760: 75 63 68 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 uch like %s in t
5770: 68 61 74 20 69 74 0a 72 65 61 64 73 20 61 20 6e hat it.reads a n
5780: 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ull-terminated s
5790: 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 tring from the a
57a0: 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 61 6e 64 rgument list and
57b0: 20 69 6e 73 65 72 74 73 0a 69 74 20 69 6e 74 6f inserts.it into
57c0: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 42 75 the result. Bu
57d0: 74 20 25 71 20 74 72 61 6e 73 6c 61 74 65 73 20 t %q translates
57e0: 74 68 65 20 69 6e 73 65 72 74 65 64 20 73 74 72 the inserted str
57f0: 69 6e 67 20 62 79 0a 6d 61 6b 69 6e 67 20 74 77 ing by.making tw
5800: 6f 20 63 6f 70 69 65 73 20 6f 66 20 65 76 65 72 o copies of ever
5810: 79 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 20 28 y single-quote (
5820: 27 29 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 ') character in
5830: 74 68 65 0a 73 75 62 73 74 69 74 75 74 65 64 20 the.substituted
5840: 73 74 72 69 6e 67 2e 20 20 54 68 69 73 20 68 61 string. This ha
5850: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 s the effect of
5860: 65 73 63 61 70 69 6e 67 20 74 68 65 20 65 6e 64 escaping the end
5870: 2d 6f 66 2d 73 74 72 69 6e 67 0a 6d 65 61 6e 69 -of-string.meani
5880: 6e 67 20 6f 66 20 73 69 6e 67 6c 65 2d 71 75 6f ng of single-quo
5890: 74 65 20 77 69 74 68 69 6e 20 61 20 73 74 72 69 te within a stri
58a0: 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 3c 2f 70 3e ng literal..</p>
58b0: 0a 0a 3c 70 3e 43 6f 6e 73 69 64 65 72 20 61 6e ..<p>Consider an
58c0: 20 65 78 61 6d 70 6c 65 2e 20 20 53 75 70 70 6f example. Suppo
58d0: 73 65 20 79 6f 75 20 61 72 65 20 74 72 79 69 6e se you are tryin
58e0: 67 20 74 6f 20 69 6e 73 65 72 74 20 61 20 73 74 g to insert a st
58f0: 72 69 6e 67 0a 76 61 6c 75 65 20 69 6e 74 6f 20 ring.value into
5900: 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
5910: 20 77 68 65 72 65 20 74 68 65 20 73 74 72 69 6e where the strin
5920: 67 20 76 61 6c 75 65 20 77 61 73 20 6f 62 74 61 g value was obta
5930: 69 6e 65 64 20 66 72 6f 6d 0a 75 73 65 72 20 69 ined from.user i
5940: 6e 70 75 74 2e 20 20 53 75 70 70 6f 73 65 20 74 nput. Suppose t
5950: 68 65 20 73 74 72 69 6e 67 20 74 6f 20 62 65 20 he string to be
5960: 69 6e 73 65 72 74 65 64 20 69 73 20 73 74 6f 72 inserted is stor
5970: 65 64 20 69 6e 20 61 20 76 61 72 69 61 62 6c 65 ed in a variable
5980: 0a 6e 61 6d 65 64 20 7a 53 74 72 69 6e 67 2e 20 .named zString.
5990: 20 54 68 65 20 63 6f 64 65 20 74 6f 20 64 6f 20 The code to do
59a0: 74 68 65 20 69 6e 73 65 72 74 69 6f 6e 20 6d 69 the insertion mi
59b0: 67 68 74 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 ght look like th
59c0: 69 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 is:</p>..<blockq
59d0: 75 6f 74 65 3e 3c 70 72 65 3e 0a 73 71 6c 69 74 uote><pre>.sqlit
59e0: 65 5f 65 78 65 63 5f 70 72 69 6e 74 66 28 64 62 e_exec_printf(db
59f0: 2c 0a 20 20 22 49 4e 53 45 52 54 20 49 4e 54 4f ,. "INSERT INTO
5a00: 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 table1 VALUES('
5a10: 25 73 27 29 22 2c 0a 20 20 30 2c 20 30 2c 20 30 %s')",. 0, 0, 0
5a20: 2c 20 7a 53 74 72 69 6e 67 29 3b 0a 3c 2f 70 72 , zString);.</pr
5a30: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
5a40: 0a 3c 70 3e 49 66 20 74 68 65 20 7a 53 74 72 69 .<p>If the zStri
5a50: 6e 67 20 76 61 72 69 61 62 6c 65 20 68 6f 6c 64 ng variable hold
5a60: 73 20 74 65 78 74 20 6c 69 6b 65 20 22 48 65 6c s text like "Hel
5a70: 6c 6f 22 2c 20 74 68 65 6e 20 74 68 69 73 20 73 lo", then this s
5a80: 74 61 74 65 6d 65 6e 74 0a 77 69 6c 6c 20 77 6f tatement.will wo
5a90: 72 6b 20 6a 75 73 74 20 66 69 6e 65 2e 20 20 42 rk just fine. B
5aa0: 75 74 20 73 75 70 70 6f 73 65 20 74 68 65 20 75 ut suppose the u
5ab0: 73 65 72 20 65 6e 74 65 72 73 20 61 20 73 74 72 ser enters a str
5ac0: 69 6e 67 20 6c 69 6b 65 20 0a 22 48 69 20 79 27 ing like ."Hi y'
5ad0: 61 6c 6c 21 22 2e 20 20 54 68 65 20 53 51 4c 20 all!". The SQL
5ae0: 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 statement genera
5af0: 74 65 64 20 72 65 61 64 73 20 61 73 20 66 6f 6c ted reads as fol
5b00: 6c 6f 77 73 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f lows:..<blockquo
5b10: 74 65 3e 3c 70 72 65 3e 0a 49 4e 53 45 52 54 20 te><pre>.INSERT
5b20: 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 INTO table1 VALU
5b30: 45 53 28 27 48 69 20 79 27 61 6c 6c 27 29 0a 3c ES('Hi y'all').<
5b40: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
5b50: 65 3e 0a 0a 3c 70 3e 54 68 69 73 20 69 73 20 6e e>..<p>This is n
5b60: 6f 74 20 76 61 6c 69 64 20 53 51 4c 20 62 65 63 ot valid SQL bec
5b70: 61 75 73 65 20 6f 66 20 74 68 65 20 61 70 6f 73 ause of the apos
5b80: 74 72 6f 70 68 79 20 69 6e 20 74 68 65 20 77 6f trophy in the wo
5b90: 72 64 20 22 79 27 61 6c 6c 22 2e 0a 42 75 74 20 rd "y'all"..But
5ba0: 69 66 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 if the %q format
5bb0: 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 75 ting option is u
5bc0: 73 65 64 20 69 6e 73 74 65 61 64 20 6f 66 20 25 sed instead of %
5bd0: 73 2c 20 6c 69 6b 65 20 74 68 69 73 3a 3c 2f 70 s, like this:</p
5be0: 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c >..<blockquote><
5bf0: 70 72 65 3e 0a 73 71 6c 69 74 65 5f 65 78 65 63 pre>.sqlite_exec
5c00: 5f 70 72 69 6e 74 66 28 64 62 2c 0a 20 20 22 49 _printf(db,. "I
5c10: 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 NSERT INTO table
5c20: 31 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 1 VALUES('%q')",
5c30: 0a 20 20 30 2c 20 30 2c 20 30 2c 20 7a 53 74 72 . 0, 0, 0, zStr
5c40: 69 6e 67 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c ing);.</pre></bl
5c50: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 ockquote>..<p>Th
5c60: 65 6e 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 en the generated
5c70: 20 53 51 4c 20 77 69 6c 6c 20 6c 6f 6f 6b 20 6c SQL will look l
5c80: 69 6b 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e ike the followin
5c90: 67 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 g:</p>..<blockqu
5ca0: 6f 74 65 3e 3c 70 72 65 3e 0a 49 4e 53 45 52 54 ote><pre>.INSERT
5cb0: 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c INTO table1 VAL
5cc0: 55 45 53 28 27 48 69 20 79 27 27 61 6c 6c 27 29 UES('Hi y''all')
5cd0: 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 .</pre></blockqu
5ce0: 6f 74 65 3e 0a 0a 3c 70 3e 48 65 72 65 20 74 68 ote>..<p>Here th
5cf0: 65 20 61 70 6f 73 74 72 6f 70 68 79 20 68 61 73 e apostrophy has
5d00: 20 62 65 65 6e 20 65 73 63 61 70 65 64 20 61 6e been escaped an
5d10: 64 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d d the SQL statem
5d20: 65 6e 74 20 69 73 20 77 65 6c 6c 2d 66 6f 72 6d ent is well-form
5d30: 65 64 2e 0a 57 68 65 6e 20 67 65 6e 65 72 61 74 ed..When generat
5d40: 69 6e 67 20 53 51 4c 20 6f 6e 2d 74 68 65 2d 66 ing SQL on-the-f
5d50: 6c 79 20 66 72 6f 6d 20 64 61 74 61 20 74 68 61 ly from data tha
5d60: 74 20 6d 69 67 68 74 20 63 6f 6e 74 61 69 6e 20 t might contain
5d70: 61 0a 73 69 6e 67 6c 65 2d 71 75 6f 74 65 20 63 a.single-quote c
5d80: 68 61 72 61 63 74 65 72 20 28 27 29 2c 20 69 74 haracter ('), it
5d90: 20 69 73 20 61 6c 77 61 79 73 20 61 20 67 6f 6f is always a goo
5da0: 64 20 69 64 65 61 20 74 6f 20 75 73 65 20 74 68 d idea to use th
5db0: 65 0a 53 51 4c 69 74 65 20 70 72 69 6e 74 66 20 e.SQLite printf
5dc0: 72 6f 75 74 69 6e 65 73 20 61 6e 64 20 74 68 65 routines and the
5dd0: 20 25 71 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f %q formatting o
5de0: 70 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 ption instead of
5df0: 20 3c 62 3e 73 70 72 69 6e 74 66 3c 2f 62 3e 2e <b>sprintf</b>.
5e00: 0a 3c 2f 70 3e 0a 0a 3c 68 32 3e 55 73 61 67 65 .</p>..<h2>Usage
5e10: 20 45 78 61 6d 70 6c 65 73 3c 2f 68 32 3e 0a 0a Examples</h2>..
5e20: 3c 70 3e 46 6f 72 20 65 78 61 6d 70 6c 65 73 20 <p>For examples
5e30: 6f 66 20 68 6f 77 20 74 68 65 20 53 51 4c 69 74 of how the SQLit
5e40: 65 20 43 2f 43 2b 2b 20 69 6e 74 65 72 66 61 63 e C/C++ interfac
5e50: 65 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 72 e can be used,.r
5e60: 65 66 65 72 20 74 6f 20 74 68 65 20 73 6f 75 72 efer to the sour
5e70: 63 65 20 63 6f 64 65 20 66 6f 72 20 74 68 65 20 ce code for the
5e80: 3c 62 3e 73 71 6c 69 74 65 3c 2f 62 3e 20 70 72 <b>sqlite</b> pr
5e90: 6f 67 72 61 6d 20 69 6e 20 74 68 65 0a 66 69 6c ogram in the.fil
5ea0: 65 20 3c 62 3e 73 72 63 2f 73 68 65 6c 6c 2e 63 e <b>src/shell.c
5eb0: 3c 2f 62 3e 20 6f 66 20 74 68 65 20 73 6f 75 72 </b> of the sour
5ec0: 63 65 20 74 72 65 65 2e 0a 41 64 64 69 74 69 6f ce tree..Additio
5ed0: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 nal information
5ee0: 61 62 6f 75 74 20 73 71 6c 69 74 65 20 69 73 20 about sqlite is
5ef0: 61 76 61 69 6c 61 62 6c 65 20 61 74 0a 3c 61 20 available at.<a
5f00: 68 72 65 66 3d 22 73 71 6c 69 74 65 2e 68 74 6d href="sqlite.htm
5f10: 6c 22 3e 73 71 6c 69 74 65 2e 68 74 6d 6c 3c 2f l">sqlite.html</
5f20: 61 3e 2e 0a 53 65 65 20 61 6c 73 6f 20 74 68 65 a>..See also the
5f30: 20 73 6f 75 72 63 65 73 20 74 6f 20 74 68 65 20 sources to the
5f40: 54 63 6c 20 69 6e 74 65 72 66 61 63 65 20 66 6f Tcl interface fo
5f50: 72 20 53 51 4c 69 74 65 20 69 6e 0a 74 68 65 20 r SQLite in.the
5f60: 73 6f 75 72 63 65 20 66 69 6c 65 20 3c 62 3e 73 source file <b>s
5f70: 72 63 2f 74 63 6c 73 71 6c 69 74 65 2e 63 3c 2f rc/tclsqlite.c</
5f80: 62 3e 2e 3c 2f 70 3e 0a 7d 0a 0a 70 75 74 73 20 b>.</p>.}..puts
5f90: 7b 0a 3c 70 3e 3c 68 72 20 2f 3e 3c 2f 70 3e 0a {.<p><hr /></p>.
5fa0: 3c 70 3e 3c 61 20 68 72 65 66 3d 22 69 6e 64 65 <p><a href="inde
5fb0: 78 2e 68 74 6d 6c 22 3e 3c 69 6d 67 20 73 72 63 x.html"><img src
5fc0: 3d 22 2f 67 6f 62 61 63 6b 2e 6a 70 67 22 20 62 ="/goback.jpg" b
5fd0: 6f 72 64 65 72 3d 30 20 2f 3e 0a 42 61 63 6b 20 order=0 />.Back
5fe0: 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 48 6f to the SQLite Ho
5ff0: 6d 65 20 50 61 67 65 3c 2f 61 3e 0a 3c 2f 70 3e me Page</a>.</p>
6000: 0a 0a 3c 2f 62 6f 64 79 3e 3c 2f 68 74 6d 6c 3e ..</body></html>
6010: 7d 0a }.