/ Hex Artifact Content
Login

Artifact 17d8bd9e7b4fbdca47c30c8b9bcb728c351d55c0:


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: 33 39 20 32 30 30 33 2f 31 30 2f 31 38 20 30 39  39 2003/10/18 09
0070: 3a 33 37 3a 32 37 20 64 61 6e 69 65 6c 6b 31 39  :37:27 danielk19
0080: 37 37 20 45 78 70 20 24 7d 0a 0a 70 75 74 73 20  77 Exp $}..puts 
0090: 7b 3c 68 74 6d 6c 3e 0a 3c 68 65 61 64 3e 0a 20  {<html>.<head>. 
00a0: 20 3c 74 69 74 6c 65 3e 54 68 65 20 43 20 6c 61   <title>The C la
00b0: 6e 67 75 61 67 65 20 69 6e 74 65 72 66 61 63 65  nguage interface
00c0: 20 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   to the SQLite l
00d0: 69 62 72 61 72 79 3c 2f 74 69 74 6c 65 3e 0a 3c  ibrary</title>.<
00e0: 2f 68 65 61 64 3e 0a 3c 62 6f 64 79 20 62 67 63  /head>.<body bgc
00f0: 6f 6c 6f 72 3d 77 68 69 74 65 3e 0a 3c 68 31 20  olor=white>.<h1 
0100: 61 6c 69 67 6e 3d 63 65 6e 74 65 72 3e 0a 54 68  align=center>.Th
0110: 65 20 43 20 6c 61 6e 67 75 61 67 65 20 69 6e 74  e C language int
0120: 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 53 51  erface to the SQ
0130: 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 3c 2f 68  Lite library.</h
0140: 31 3e 7d 0a 70 75 74 73 20 22 3c 70 20 61 6c 69  1>}.puts "<p ali
0150: 67 6e 3d 63 65 6e 74 65 72 3e 0a 28 54 68 69 73  gn=center>.(This
0160: 20 70 61 67 65 20 77 61 73 20 6c 61 73 74 20 6d   page was last m
0170: 6f 64 69 66 69 65 64 20 6f 6e 20 5b 6c 72 61 6e  odified on [lran
0180: 67 65 20 24 72 63 73 69 64 20 33 20 34 5d 20 55  ge $rcsid 3 4] U
0190: 54 43 29 0a 3c 2f 70 3e 22 0a 0a 70 75 74 73 20  TC).</p>"..puts 
01a0: 7b 0a 3c 70 3e 54 68 65 20 53 51 4c 69 74 65 20  {.<p>The SQLite 
01b0: 6c 69 62 72 61 72 79 20 69 73 20 64 65 73 69 67  library is desig
01c0: 6e 65 64 20 74 6f 20 62 65 20 76 65 72 79 20 65  ned to be very e
01d0: 61 73 79 20 74 6f 20 75 73 65 20 66 72 6f 6d 0a  asy to use from.
01e0: 61 20 43 20 6f 72 20 43 2b 2b 20 70 72 6f 67 72  a C or C++ progr
01f0: 61 6d 2e 20 20 54 68 69 73 20 64 6f 63 75 6d 65  am.  This docume
0200: 6e 74 20 67 69 76 65 73 20 61 6e 20 6f 76 65 72  nt gives an over
0210: 76 69 65 77 20 6f 66 20 74 68 65 20 43 2f 43 2b  view of the C/C+
0220: 2b 0a 70 72 6f 67 72 61 6d 6d 69 6e 67 20 69 6e  +.programming in
0230: 74 65 72 66 61 63 65 2e 3c 2f 70 3e 0a 0a 3c 68  terface.</p>..<h
0240: 32 3e 31 2e 30 20 54 68 65 20 43 6f 72 65 20 41  2>1.0 The Core A
0250: 50 49 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65 20  PI</h2>..<p>The 
0260: 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
0270: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
0280: 63 6f 6e 73 69 73 74 73 20 6f 66 20 74 68 72 65  consists of thre
0290: 65 20 63 6f 72 65 20 66 75 6e 63 74 69 6f 6e 73  e core functions
02a0: 2c 0a 6f 6e 65 20 6f 70 61 71 75 65 20 64 61 74  ,.one opaque dat
02b0: 61 20 73 74 72 75 63 74 75 72 65 2c 20 61 6e 64  a structure, and
02c0: 20 73 6f 6d 65 20 63 6f 6e 73 74 61 6e 74 73 20   some constants 
02d0: 75 73 65 64 20 61 73 20 72 65 74 75 72 6e 20 76  used as return v
02e0: 61 6c 75 65 73 2e 0a 54 68 65 20 63 6f 72 65 20  alues..The core 
02f0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 73 20  interface is as 
0300: 66 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c 62  follows:</p>..<b
0310: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
0320: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
0330: 71 6c 69 74 65 20 73 71 6c 69 74 65 3b 0a 23 64  qlite sqlite;.#d
0340: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20  efine SQLITE_OK 
0350: 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
0360: 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75   Successful resu
0370: 6c 74 20 2a 2f 0a 0a 73 71 6c 69 74 65 20 2a 73  lt */..sqlite *s
0380: 71 6c 69 74 65 5f 6f 70 65 6e 28 63 6f 6e 73 74  qlite_open(const
0390: 20 63 68 61 72 20 2a 64 62 6e 61 6d 65 2c 20 69   char *dbname, i
03a0: 6e 74 20 6d 6f 64 65 2c 20 63 68 61 72 20 2a 2a  nt mode, char **
03b0: 65 72 72 6d 73 67 29 3b 0a 0a 76 6f 69 64 20 73  errmsg);..void s
03c0: 71 6c 69 74 65 5f 63 6c 6f 73 65 28 73 71 6c 69  qlite_close(sqli
03d0: 74 65 20 2a 64 62 29 3b 0a 0a 69 6e 74 20 73 71  te *db);..int sq
03e0: 6c 69 74 65 5f 65 78 65 63 28 0a 20 20 73 71 6c  lite_exec(.  sql
03f0: 69 74 65 20 2a 64 62 2c 0a 20 20 63 68 61 72 20  ite *db,.  char 
0400: 2a 73 71 6c 2c 0a 20 20 69 6e 74 20 28 2a 78 43  *sql,.  int (*xC
0410: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
0420: 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a  nt,char**,char**
0430: 29 2c 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  ),.  void *pArg,
0440: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
0450: 0a 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .);.</pre></bloc
0460: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65  kquote>..<p>.The
0470: 20 61 62 6f 76 65 20 69 73 20 61 6c 6c 20 79 6f   above is all yo
0480: 75 20 72 65 61 6c 6c 79 20 6e 65 65 64 20 74 6f  u really need to
0490: 20 6b 6e 6f 77 20 69 6e 20 6f 72 64 65 72 20 74   know in order t
04a0: 6f 20 75 73 65 20 53 51 4c 69 74 65 0a 69 6e 20  o use SQLite.in 
04b0: 79 6f 75 72 20 43 20 6f 72 20 43 2b 2b 20 70 72  your C or C++ pr
04c0: 6f 67 72 61 6d 73 2e 20 20 54 68 65 72 65 20 61  ograms.  There a
04d0: 72 65 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61  re other interfa
04e0: 63 65 20 66 75 6e 63 74 69 6f 6e 73 0a 61 76 61  ce functions.ava
04f0: 69 6c 61 62 6c 65 20 28 61 6e 64 20 64 65 73 63  ilable (and desc
0500: 72 69 62 65 64 20 62 65 6c 6f 77 29 20 62 75 74  ribed below) but
0510: 20 77 65 20 77 69 6c 6c 20 62 65 67 69 6e 20 62   we will begin b
0520: 79 20 64 65 73 63 72 69 62 69 6e 67 0a 74 68 65  y describing.the
0530: 20 63 6f 72 65 20 66 75 6e 63 74 69 6f 6e 73 20   core functions 
0540: 73 68 6f 77 6e 20 61 62 6f 76 65 2e 0a 3c 2f 70  shown above..</p
0550: 3e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 73 71 6c 69  >..<a name="sqli
0560: 74 65 5f 6f 70 65 6e 22 3e 0a 3c 68 33 3e 31 2e  te_open">.<h3>1.
0570: 31 20 4f 70 65 6e 69 6e 67 20 61 20 64 61 74 61  1 Opening a data
0580: 62 61 73 65 3c 2f 68 33 3e 0a 0a 3c 70 3e 55 73  base</h3>..<p>Us
0590: 65 20 74 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f  e the <b>sqlite_
05a0: 6f 70 65 6e 3c 2f 62 3e 20 66 75 6e 63 74 69 6f  open</b> functio
05b0: 6e 20 74 6f 20 6f 70 65 6e 20 61 6e 20 65 78 69  n to open an exi
05c0: 73 74 69 6e 67 20 53 51 4c 69 74 65 0a 64 61 74  sting SQLite.dat
05d0: 61 62 61 73 65 20 6f 72 20 74 6f 20 63 72 65 61  abase or to crea
05e0: 74 65 20 61 20 6e 65 77 20 53 51 4c 69 74 65 20  te a new SQLite 
05f0: 64 61 74 61 62 61 73 65 2e 20 20 54 68 65 20 66  database.  The f
0600: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 69 73  irst argument.is
0610: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
0620: 6d 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  me.  The second 
0630: 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
0640: 6e 64 65 64 20 74 6f 20 73 69 67 6e 61 6c 0a 77  nded to signal.w
0650: 68 65 74 68 65 72 20 74 68 65 20 64 61 74 61 62  hether the datab
0660: 61 73 65 20 69 73 20 67 6f 69 6e 67 20 74 6f 20  ase is going to 
0670: 62 65 20 75 73 65 64 20 66 6f 72 20 72 65 61 64  be used for read
0680: 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 0a  ing and writing.
0690: 6f 72 20 6a 75 73 74 20 66 6f 72 20 72 65 61 64  or just for read
06a0: 69 6e 67 2e 20 20 42 75 74 20 69 6e 20 74 68 65  ing.  But in the
06b0: 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
06c0: 6e 74 61 74 69 6f 6e 2c 20 74 68 65 0a 73 65 63  ntation, the.sec
06d0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
06e0: 3c 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e 3c 2f  <b>sqlite_open</
06f0: 62 3e 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 54  b> is ignored..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 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
0720: 6f 20 61 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  o a string point
0730: 65 72 2e 0a 49 66 20 74 68 65 20 74 68 69 72 64  er..If the third
0740: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 6f 74   argument is not
0750: 20 4e 55 4c 4c 20 61 6e 64 20 61 6e 20 65 72 72   NULL and an err
0760: 6f 72 20 6f 63 63 75 72 73 0a 77 68 69 6c 65 20  or occurs.while 
0770: 74 72 79 69 6e 67 20 74 6f 20 6f 70 65 6e 20 74  trying to open t
0780: 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 68 65  he database, the
0790: 6e 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  n an error messa
07a0: 67 65 20 77 69 6c 6c 20 62 65 0a 77 72 69 74 74  ge will be.writt
07b0: 65 6e 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  en to memory obt
07c0: 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f  ained from mallo
07d0: 63 28 29 20 61 6e 64 20 2a 65 72 72 6d 73 67 20  c() and *errmsg 
07e0: 77 69 6c 6c 20 62 65 20 6d 61 64 65 0a 74 6f 20  will be made.to 
07f0: 70 6f 69 6e 74 20 74 6f 20 74 68 69 73 20 65 72  point to this er
0800: 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 54 68  ror message.  Th
0810: 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
0820: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
0830: 65 0a 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e.for freeing th
0840: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 69 74  e memory when it
0850: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
0860: 74 68 20 69 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54  th it.</p>..<p>T
0870: 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 20 53 51  he name of an SQ
0880: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
0890: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
08a0: 69 6c 65 20 74 68 61 74 20 77 69 6c 6c 0a 63 6f  ile that will.co
08b0: 6e 74 61 69 6e 20 74 68 65 20 64 61 74 61 62 61  ntain the databa
08c0: 73 65 2e 20 20 49 66 20 74 68 65 20 66 69 6c 65  se.  If the file
08d0: 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2c   does not exist,
08e0: 20 53 51 4c 69 74 65 20 61 74 74 65 6d 70 74 73   SQLite attempts
08f0: 0a 74 6f 20 63 72 65 61 74 65 20 61 6e 64 20 69  .to create and i
0900: 6e 69 74 69 61 6c 69 7a 65 20 69 74 2e 20 20 49  nitialize it.  I
0910: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  f the file is re
0920: 61 64 2d 6f 6e 6c 79 20 28 64 75 65 20 74 6f 0a  ad-only (due to.
0930: 70 65 72 6d 69 73 73 69 6f 6e 20 62 69 74 73 20  permission bits 
0940: 6f 72 20 62 65 63 61 75 73 65 20 69 74 20 69 73  or because it is
0950: 20 6c 6f 63 61 74 65 64 20 6f 6e 20 72 65 61 64   located on read
0960: 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 6c 69 6b 65  -only media like
0970: 0a 61 20 43 44 2d 52 4f 4d 29 20 74 68 65 6e 20  .a CD-ROM) then 
0980: 53 51 4c 69 74 65 20 6f 70 65 6e 73 20 74 68 65  SQLite opens the
0990: 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
09a0: 61 64 69 6e 67 20 6f 6e 6c 79 2e 20 20 54 68 65  ading only.  The
09b0: 0a 65 6e 74 69 72 65 20 53 51 4c 20 64 61 74 61  .entire SQL data
09c0: 62 61 73 65 20 69 73 20 73 74 6f 72 65 64 20 69  base is stored i
09d0: 6e 20 61 20 73 69 6e 67 6c 65 20 66 69 6c 65 20  n a single file 
09e0: 6f 6e 20 74 68 65 20 64 69 73 6b 2e 20 20 42 75  on the disk.  Bu
09f0: 74 0a 61 64 64 69 74 69 6f 6e 61 6c 20 74 65 6d  t.additional tem
0a00: 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
0a10: 20 62 65 20 63 72 65 61 74 65 64 20 64 75 72 69   be created duri
0a20: 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
0a30: 20 6f 66 0a 61 6e 20 53 51 4c 20 63 6f 6d 6d 61   of.an SQL comma
0a40: 6e 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  nd in order to s
0a50: 74 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  tore the databas
0a60: 65 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e  e rollback journ
0a70: 61 6c 20 6f 72 0a 74 65 6d 70 6f 72 61 72 79 20  al or.temporary 
0a80: 61 6e 64 20 69 6e 74 65 72 6d 65 64 69 61 74 65  and intermediate
0a90: 20 72 65 73 75 6c 74 73 20 6f 66 20 61 20 71 75   results of a qu
0aa0: 65 72 79 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65  ery.</p>..<p>The
0ab0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
0ac0: 20 74 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 6f   the <b>sqlite_o
0ad0: 70 65 6e 3c 2f 62 3e 20 66 75 6e 63 74 69 6f 6e  pen</b> function
0ae0: 20 69 73 20 61 0a 70 6f 69 6e 74 65 72 20 74 6f   is a.pointer to
0af0: 20 61 6e 20 6f 70 61 71 75 65 20 3c 62 3e 73 71   an opaque <b>sq
0b00: 6c 69 74 65 3c 2f 62 3e 20 73 74 72 75 63 74 75  lite</b> structu
0b10: 72 65 2e 20 20 54 68 69 73 20 70 6f 69 6e 74 65  re.  This pointe
0b20: 72 20 77 69 6c 6c 0a 62 65 20 74 68 65 20 66 69  r will.be the fi
0b30: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
0b40: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53  all subsequent S
0b50: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 20 63  QLite function c
0b60: 61 6c 6c 73 20 74 68 61 74 0a 64 65 61 6c 20 77  alls that.deal w
0b70: 69 74 68 20 74 68 65 20 73 61 6d 65 20 64 61 74  ith the same dat
0b80: 61 62 61 73 65 2e 20 20 4e 55 4c 4c 20 69 73 20  abase.  NULL is 
0b90: 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
0ba0: 6f 70 65 6e 20 66 61 69 6c 73 0a 66 6f 72 20 61  open fails.for a
0bb0: 6e 79 20 72 65 61 73 6f 6e 2e 3c 2f 70 3e 0a 0a  ny reason.</p>..
0bc0: 3c 61 20 6e 61 6d 65 3d 22 73 71 6c 69 74 65 5f  <a name="sqlite_
0bd0: 63 6c 6f 73 65 22 3e 0a 3c 68 33 3e 31 2e 32 20  close">.<h3>1.2 
0be0: 43 6c 6f 73 69 6e 67 20 74 68 65 20 64 61 74 61  Closing the data
0bf0: 62 61 73 65 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 6f  base</h3>..<p>To
0c00: 20 63 6c 6f 73 65 20 61 6e 20 53 51 4c 69 74 65   close an SQLite
0c10: 20 64 61 74 61 62 61 73 65 2c 20 63 61 6c 6c 20   database, call 
0c20: 74 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 63 6c  the <b>sqlite_cl
0c30: 6f 73 65 3c 2f 62 3e 0a 66 75 6e 63 74 69 6f 6e  ose</b>.function
0c40: 20 70 61 73 73 69 6e 67 20 69 74 20 74 68 65 20   passing it the 
0c50: 73 71 6c 69 74 65 20 73 74 72 75 63 74 75 72 65  sqlite structure
0c60: 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
0c70: 73 20 6f 62 74 61 69 6e 65 64 0a 66 72 6f 6d 20  s obtained.from 
0c80: 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
0c90: 3c 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e 3c 2f  <b>sqlite_open</
0ca0: 62 3e 2e 0a 49 66 20 61 20 74 72 61 6e 73 61 63  b>..If a transac
0cb0: 74 69 6f 6e 20 69 73 20 61 63 74 69 76 65 20 77  tion is active w
0cc0: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
0cd0: 20 69 73 20 63 6c 6f 73 65 64 2c 20 74 68 65 20   is closed, the 
0ce0: 74 72 61 6e 73 61 63 74 69 6f 6e 0a 69 73 20 72  transaction.is r
0cf0: 6f 6c 6c 65 64 20 62 61 63 6b 2e 3c 2f 70 3e 0a  olled back.</p>.
0d00: 0a 3c 61 20 6e 61 6d 65 3d 22 73 71 6c 69 74 65  .<a name="sqlite
0d10: 5f 65 78 65 63 22 3e 0a 3c 68 33 3e 31 2e 33 20  _exec">.<h3>1.3 
0d20: 45 78 65 63 75 74 69 6e 67 20 53 51 4c 20 73 74  Executing SQL st
0d30: 61 74 65 6d 65 6e 74 73 3c 2f 68 33 3e 0a 0a 3c  atements</h3>..<
0d40: 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f  p>The <b>sqlite_
0d50: 65 78 65 63 3c 2f 62 3e 20 66 75 6e 63 74 69 6f  exec</b> functio
0d60: 6e 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 6f  n is used to pro
0d70: 63 65 73 73 20 53 51 4c 20 73 74 61 74 65 6d 65  cess SQL stateme
0d80: 6e 74 73 0a 61 6e 64 20 71 75 65 72 69 65 73 2e  nts.and queries.
0d90: 20 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20    This function 
0da0: 72 65 71 75 69 72 65 73 20 35 20 70 61 72 61 6d  requires 5 param
0db0: 65 74 65 72 73 20 61 73 20 66 6f 6c 6c 6f 77 73  eters as follows
0dc0: 3a 3c 2f 70 3e 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e  :</p>..<ol>.<li>
0dd0: 3c 70 3e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  <p>A pointer to 
0de0: 74 68 65 20 73 71 6c 69 74 65 20 73 74 72 75 63  the sqlite struc
0df0: 74 75 72 65 20 6f 62 74 61 69 6e 65 64 20 66 72  ture obtained fr
0e00: 6f 6d 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 0a  om a prior call.
0e10: 20 20 20 20 20 20 20 74 6f 20 3c 62 3e 73 71 6c         to <b>sql
0e20: 69 74 65 5f 6f 70 65 6e 3c 2f 62 3e 2e 3c 2f 70  ite_open</b>.</p
0e30: 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e 41 20  ></li>.<li><p>A 
0e40: 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 20  null-terminated 
0e50: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
0e60: 67 20 74 68 65 20 74 65 78 74 20 6f 66 20 6f 6e  g the text of on
0e70: 65 20 6f 72 20 6d 6f 72 65 0a 20 20 20 20 20 20  e or more.      
0e80: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
0e90: 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20 74  and/or queries t
0ea0: 6f 20 62 65 20 70 72 6f 63 65 73 73 65 64 2e 3c  o be processed.<
0eb0: 2f 70 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e  /p></li>.<li><p>
0ec0: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63  A pointer to a c
0ed0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
0ee0: 20 77 68 69 63 68 20 69 73 20 69 6e 76 6f 6b 65   which is invoke
0ef0: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 0a  d once for each.
0f00: 20 20 20 20 20 20 20 72 6f 77 20 69 6e 20 74 68         row in th
0f10: 65 20 72 65 73 75 6c 74 20 6f 66 20 61 20 71 75  e result of a qu
0f20: 65 72 79 2e 20 20 54 68 69 73 20 61 72 67 75 6d  ery.  This argum
0f30: 65 6e 74 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c  ent may be NULL,
0f40: 20 69 6e 20 77 68 69 63 68 0a 20 20 20 20 20 20   in which.      
0f50: 20 63 61 73 65 20 6e 6f 20 63 61 6c 6c 62 61 63   case no callbac
0f60: 6b 73 20 77 69 6c 6c 20 65 76 65 72 20 62 65 20  ks will ever be 
0f70: 69 6e 76 6f 6b 65 64 2e 3c 2f 70 3e 3c 2f 6c 69  invoked.</p></li
0f80: 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 70 6f 69 6e 74  >.<li><p>A point
0f90: 65 72 20 74 68 61 74 20 69 73 20 66 6f 72 77 61  er that is forwa
0fa0: 72 64 65 64 20 74 6f 20 62 65 63 6f 6d 65 20 74  rded to become t
0fb0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
0fc0: 74 0a 20 20 20 20 20 20 20 74 6f 20 74 68 65 20  t.       to the 
0fd0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
0fe0: 6e 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e  n.</p></li>.<li>
0ff0: 3c 70 3e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  <p>A pointer to 
1000: 61 6e 20 65 72 72 6f 72 20 73 74 72 69 6e 67 2e  an error string.
1010: 20 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 73    Error messages
1020: 20 61 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20   are written to 
1030: 73 70 61 63 65 0a 20 20 20 20 20 20 20 6f 62 74  space.       obt
1040: 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f  ained from mallo
1050: 63 28 29 20 61 6e 64 20 74 68 65 20 65 72 72 6f  c() and the erro
1060: 72 20 73 74 72 69 6e 67 20 69 73 20 6d 61 64 65  r string is made
1070: 20 74 6f 20 70 6f 69 6e 74 20 74 6f 0a 20 20 20   to point to.   
1080: 20 20 20 20 74 68 65 20 6d 61 6c 6c 6f 63 65 64      the malloced
1090: 20 73 70 61 63 65 2e 20 20 54 68 65 20 63 61 6c   space.  The cal
10a0: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ling function is
10b0: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
10c0: 20 66 72 65 65 69 6e 67 0a 20 20 20 20 20 20 20   freeing.       
10d0: 74 68 69 73 20 73 70 61 63 65 20 77 68 65 6e 20  this space when 
10e0: 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
10f0: 77 69 74 68 20 69 74 2e 0a 20 20 20 20 20 20 20  with it..       
1100: 54 68 69 73 20 61 72 67 75 6d 65 6e 74 20 6d 61  This argument ma
1110: 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 77 68  y be NULL, in wh
1120: 69 63 68 20 63 61 73 65 20 65 72 72 6f 72 20 6d  ich case error m
1130: 65 73 73 61 67 65 73 20 61 72 65 20 6e 6f 74 0a  essages are not.
1140: 20 20 20 20 20 20 20 72 65 70 6f 72 74 65 64 20         reported 
1150: 62 61 63 6b 20 74 6f 20 74 68 65 20 63 61 6c 6c  back to the call
1160: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 70  ing function.</p
1170: 3e 3c 2f 6c 69 3e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70  ></li>.</ol>..<p
1180: 3e 0a 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  >.The callback f
1190: 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20  unction is used 
11a0: 74 6f 20 72 65 63 65 69 76 65 20 74 68 65 20 72  to receive the r
11b0: 65 73 75 6c 74 73 20 6f 66 20 61 20 71 75 65 72  esults of a quer
11c0: 79 2e 20 20 41 0a 70 72 6f 74 6f 74 79 70 65 20  y.  A.prototype 
11d0: 66 6f 72 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  for the callback
11e0: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 73 20   function is as 
11f0: 66 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c 62  follows:</p>..<b
1200: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1210: 69 6e 74 20 43 61 6c 6c 62 61 63 6b 28 76 6f 69  int Callback(voi
1220: 64 20 2a 70 41 72 67 2c 20 69 6e 74 20 61 72 67  d *pArg, int arg
1230: 63 2c 20 63 68 61 72 20 2a 2a 61 72 67 76 2c 20  c, char **argv, 
1240: 63 68 61 72 20 2a 2a 63 6f 6c 75 6d 6e 4e 61 6d  char **columnNam
1250: 65 73 29 7b 0a 20 20 72 65 74 75 72 6e 20 30 3b  es){.  return 0;
1260: 0a 7d 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  .}.</pre></block
1270: 71 75 6f 74 65 3e 0a 0a 3c 61 20 6e 61 6d 65 3d  quote>..<a name=
1280: 22 63 61 6c 6c 62 61 63 6b 5f 72 6f 77 5f 64 61  "callback_row_da
1290: 74 61 22 3e 0a 3c 70 3e 54 68 65 20 66 69 72 73  ta">.<p>The firs
12a0: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
12b0: 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6a 75  e callback is ju
12c0: 73 74 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  st a copy of the
12d0: 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
12e0: 0a 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78  .to <b>sqlite_ex
12f0: 65 63 3c 2f 62 3e 20 20 54 68 69 73 20 70 61 72  ec</b>  This par
1300: 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 75 73  ameter can be us
1310: 65 64 20 74 6f 20 70 61 73 73 20 61 72 62 69 74  ed to pass arbit
1320: 72 61 72 79 0a 69 6e 66 6f 72 6d 61 74 69 6f 6e  rary.information
1330: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
1340: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1350: 6e 20 66 72 6f 6d 20 63 6c 69 65 6e 74 20 63 6f  n from client co
1360: 64 65 2e 0a 54 68 65 20 73 65 63 6f 6e 64 20 61  de..The second a
1370: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
1380: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1390: 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 72 65   in the query re
13a0: 73 75 6c 74 2e 0a 54 68 65 20 74 68 69 72 64 20  sult..The third 
13b0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 61  argument is an a
13c0: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
13d0: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
13e0: 65 20 65 61 63 68 20 73 74 72 69 6e 67 0a 69 73  e each string.is
13f0: 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
1400: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 66   of the result f
1410: 6f 72 20 74 68 61 74 20 72 65 63 6f 72 64 2e 20  or that record. 
1420: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 0a 63   Note that the.c
1430: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1440: 20 72 65 70 6f 72 74 73 20 61 20 4e 55 4c 4c 20   reports a NULL 
1450: 76 61 6c 75 65 20 69 6e 20 74 68 65 20 64 61 74  value in the dat
1460: 61 62 61 73 65 20 61 73 20 61 20 4e 55 4c 4c 20  abase as a NULL 
1470: 70 6f 69 6e 74 65 72 2c 0a 77 68 69 63 68 20 69  pointer,.which i
1480: 73 20 76 65 72 79 20 64 69 66 66 65 72 65 6e 74  s very different
1490: 20 66 72 6f 6d 20 61 6e 20 65 6d 70 74 79 20 73   from an empty s
14a0: 74 72 69 6e 67 2e 20 20 49 66 20 74 68 65 20 69  tring.  If the i
14b0: 2d 74 68 20 70 61 72 61 6d 65 74 65 72 0a 69 73  -th parameter.is
14c0: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
14d0: 2c 20 77 65 20 77 69 6c 6c 20 67 65 74 3a 3c 2f  , we will get:</
14e0: 70 3e 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  p>.<blockquote><
14f0: 70 72 65 3e 0a 61 72 67 76 5b 69 5d 5b 30 5d 20  pre>.argv[i][0] 
1500: 3d 3d 20 30 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  == 0.</pre></blo
1510: 63 6b 71 75 6f 74 65 3e 0a 3c 70 3e 42 75 74 20  ckquote>.<p>But 
1520: 69 66 20 74 68 65 20 69 2d 74 68 20 70 61 72 61  if the i-th para
1530: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 77 65  meter is NULL we
1540: 20 77 69 6c 6c 20 67 65 74 3a 3c 2f 70 3e 0a 3c   will get:</p>.<
1550: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1560: 0a 61 72 67 76 5b 69 5d 20 3d 3d 20 30 0a 3c 2f  .argv[i] == 0.</
1570: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1580: 3e 0a 0a 3c 70 3e 54 68 65 20 6e 61 6d 65 73 20  >..<p>The names 
1590: 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 20 61  of the columns a
15a0: 72 65 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20  re contained in 
15b0: 66 69 72 73 74 20 3c 69 3e 61 72 67 63 3c 2f 69  first <i>argc</i
15c0: 3e 0a 65 6e 74 72 69 65 73 20 6f 66 20 74 68 65  >.entries of the
15d0: 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
15e0: 2e 0a 49 66 20 74 68 65 20 3c 61 20 68 72 65 66  ..If the <a href
15f0: 3d 22 6c 61 6e 67 2e 68 74 6d 6c 23 70 72 61 67  ="lang.html#prag
1600: 6d 61 5f 73 68 6f 77 5f 64 61 74 61 74 79 70 65  ma_show_datatype
1610: 73 22 3e 53 48 4f 57 5f 44 41 54 41 54 59 50 45  s">SHOW_DATATYPE
1620: 53 3c 2f 61 3e 20 70 72 61 67 6d 61 0a 69 73 20  S</a> pragma.is 
1630: 6f 6e 20 28 69 74 20 69 73 20 6f 66 66 20 62 79  on (it is off by
1640: 20 64 65 66 61 75 6c 74 29 20 74 68 65 6e 0a 74   default) then.t
1650: 68 65 20 73 65 63 6f 6e 64 20 3c 69 3e 61 72 67  he second <i>arg
1660: 63 3c 2f 69 3e 20 65 6e 74 72 69 65 73 20 69 6e  c</i> entries in
1670: 20 74 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e   the 4th argumen
1680: 74 20 61 72 65 20 74 68 65 20 64 61 74 61 74 79  t are the dataty
1690: 70 65 73 0a 66 6f 72 20 74 68 65 20 63 6f 72 72  pes.for the corr
16a0: 65 73 70 6f 6e 64 69 6e 67 20 63 6f 6c 75 6d 6e  esponding column
16b0: 73 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 49 66 20 74  s..</p>..<p>If t
16c0: 68 65 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67  he <a href="lang
16d0: 2e 68 74 6d 6c 23 70 72 61 67 6d 61 5f 65 6d 70  .html#pragma_emp
16e0: 74 79 5f 72 65 73 75 6c 74 5f 63 61 6c 6c 62 61  ty_result_callba
16f0: 63 6b 73 22 3e 0a 45 4d 50 54 59 5f 52 45 53 55  cks">.EMPTY_RESU
1700: 4c 54 5f 43 41 4c 4c 42 41 43 4b 53 3c 2f 61 3e  LT_CALLBACKS</a>
1710: 20 70 72 61 67 6d 61 20 69 73 20 73 65 74 20 74   pragma is set t
1720: 6f 20 4f 4e 20 61 6e 64 20 74 68 65 20 72 65 73  o ON and the res
1730: 75 6c 74 20 6f 66 0a 61 20 71 75 65 72 79 20 69  ult of.a query i
1740: 73 20 61 6e 20 65 6d 70 74 79 20 73 65 74 2c 20  s an empty set, 
1750: 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
1760: 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  k is invoked onc
1770: 65 20 77 69 74 68 20 74 68 65 0a 74 68 69 72 64  e with the.third
1780: 20 70 61 72 61 6d 65 74 65 72 20 28 61 72 67 76   parameter (argv
1790: 29 20 73 65 74 20 74 6f 20 30 2e 20 20 49 6e 20  ) set to 0.  In 
17a0: 6f 74 68 65 72 20 77 6f 72 64 73 0a 3c 62 6c 6f  other words.<blo
17b0: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 61 72  ckquote><pre>.ar
17c0: 67 76 20 3d 3d 20 30 0a 3c 2f 70 72 65 3e 3c 2f  gv == 0.</pre></
17d0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 54 68 65 20  blockquote>.The 
17e0: 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17f0: 20 28 61 72 67 63 29 0a 61 6e 64 20 74 68 65 20   (argc).and the 
1800: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1810: 20 28 63 6f 6c 75 6d 6e 4e 61 6d 65 73 29 20 61   (columnNames) a
1820: 72 65 20 73 74 69 6c 6c 20 76 61 6c 69 64 0a 61  re still valid.a
1830: 6e 64 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  nd can be used t
1840: 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
1850: 6e 75 6d 62 65 72 20 61 6e 64 20 6e 61 6d 65 73  number and names
1860: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a 63   of the result.c
1870: 6f 6c 75 6d 6e 73 20 69 66 20 74 68 65 72 65 20  olumns if there 
1880: 68 61 64 20 62 65 65 6e 20 61 20 72 65 73 75 6c  had been a resul
1890: 74 2e 0a 54 68 65 20 64 65 66 61 75 6c 74 20 62  t..The default b
18a0: 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74  ehavior is not t
18b0: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 61 6c  o invoke the cal
18c0: 6c 62 61 63 6b 20 61 74 20 61 6c 6c 20 69 66 20  lback at all if 
18d0: 74 68 65 0a 72 65 73 75 6c 74 20 73 65 74 20 69  the.result set i
18e0: 73 20 65 6d 70 74 79 2e 3c 2f 70 3e 0a 0a 3c 61  s empty.</p>..<a
18f0: 20 6e 61 6d 65 3d 22 63 61 6c 6c 62 61 63 6b 5f   name="callback_
1900: 72 65 74 75 72 6e 73 5f 6e 6f 6e 7a 65 72 6f 22  returns_nonzero"
1910: 3e 0a 3c 70 3e 54 68 65 20 63 61 6c 6c 62 61 63  >.<p>The callbac
1920: 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
1930: 64 20 6e 6f 72 6d 61 6c 6c 79 20 72 65 74 75 72  d normally retur
1940: 6e 20 30 2e 20 20 49 66 20 74 68 65 20 63 61 6c  n 0.  If the cal
1950: 6c 62 61 63 6b 0a 66 75 6e 63 74 69 6f 6e 20 72  lback.function r
1960: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1970: 20 74 68 65 20 71 75 65 72 79 20 69 73 20 69 6d   the query is im
1980: 6d 65 64 69 61 74 65 6c 79 20 61 62 6f 72 74 65  mediately aborte
1990: 64 20 61 6e 64 20 0a 3c 62 3e 73 71 6c 69 74 65  d and .<b>sqlite
19a0: 5f 65 78 65 63 3c 2f 62 3e 20 77 69 6c 6c 20 72  _exec</b> will r
19b0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 41 42 4f  eturn SQLITE_ABO
19c0: 52 54 2e 3c 2f 70 3e 0a 0a 3c 68 33 3e 31 2e 34  RT.</p>..<h3>1.4
19d0: 20 45 72 72 6f 72 20 43 6f 64 65 73 3c 2f 68 33   Error Codes</h3
19e0: 3e 0a 0a 3c 70 3e 0a 54 68 65 20 3c 62 3e 73 71  >..<p>.The <b>sq
19f0: 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e 20 66 75  lite_exec</b> fu
1a00: 6e 63 74 69 6f 6e 20 6e 6f 72 6d 61 6c 6c 79 20  nction normally 
1a10: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
1a20: 4b 2e 20 20 42 75 74 0a 69 66 20 73 6f 6d 65 74  K.  But.if somet
1a30: 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 20  hing goes wrong 
1a40: 69 74 20 63 61 6e 20 72 65 74 75 72 6e 20 61 20  it can return a 
1a50: 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 20  different value 
1a60: 74 6f 20 69 6e 64 69 63 61 74 65 0a 74 68 65 20  to indicate.the 
1a70: 74 79 70 65 20 6f 66 20 65 72 72 6f 72 2e 20 20  type of error.  
1a80: 48 65 72 65 20 69 73 20 61 20 63 6f 6d 70 6c 65  Here is a comple
1a90: 74 65 20 6c 69 73 74 20 6f 66 20 74 68 65 20 72  te list of the r
1aa0: 65 74 75 72 6e 20 63 6f 64 65 73 3a 0a 3c 2f 70  eturn codes:.</p
1ab0: 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  >..<blockquote><
1ac0: 70 72 65 3e 0a 23 64 65 66 69 6e 65 20 53 51 4c  pre>.#define SQL
1ad0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
1ae0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
1af0: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 23 64 65  ul result */.#de
1b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
1b10: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
1b20: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
1b30: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
1b40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b50: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
1b60: 20 2f 2a 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20   /* An internal 
1b70: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
1b80: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
1b90: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
1ba0: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
1bb0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
1bc0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
1bd0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
1be0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
1bf0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
1c00: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
1c10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c20: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
1c30: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
1c40: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
1c50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c60: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
1c70: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
1c80: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
1c90: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
1ca0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
1cb0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
1cc0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
1cd0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ce0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
1cf0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
1d00: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
1d10: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
1d20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
1d30: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
1d40: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
1d50: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
1d60: 5f 69 6e 74 65 72 72 75 70 74 28 29 20 2a 2f 0a  _interrupt() */.
1d70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1d80: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
1d90: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
1da0: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
1db0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
1dc0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
1dd0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
1de0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
1df0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
1e00: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
1e10: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
1e20: 20 31 32 20 20 20 2f 2a 20 28 49 6e 74 65 72 6e   12   /* (Intern
1e30: 61 6c 20 4f 6e 6c 79 29 20 54 61 62 6c 65 20 6f  al Only) Table o
1e40: 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75  r record not fou
1e50: 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nd */.#define SQ
1e60: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
1e70: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
1e80: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
1e90: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
1ea0: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
1eb0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
1ec0: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
1ed0: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
1ee0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
1ef0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
1f00: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
1f10: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
1f20: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
1f30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
1f40: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
1f50: 2f 2a 20 28 49 6e 74 65 72 6e 61 6c 20 4f 6e 6c  /* (Internal Onl
1f60: 79 29 20 44 61 74 61 62 61 73 65 20 74 61 62 6c  y) Database tabl
1f70: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
1f80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
1f90: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
1fa0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
1fb0: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
1fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
1fd0: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
1fe0: 2f 2a 20 54 6f 6f 20 6d 75 63 68 20 64 61 74 61  /* Too much data
1ff0: 20 66 6f 72 20 6f 6e 65 20 72 6f 77 20 6f 66 20   for one row of 
2000: 61 20 74 61 62 6c 65 20 2a 2f 0a 23 64 65 66 69  a table */.#defi
2010: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
2020: 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62  AINT  19   /* Ab
2030: 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 74 72  ort due to contr
2040: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
2050: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2060: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
2070: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
2080: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
2090: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
20a0: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
20b0: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
20c0: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
20d0: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
20e0: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
20f0: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
2100: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
2110: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
2120: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
2130: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
2140: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
2150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2160: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
2170: 20 20 2f 2a 20 73 71 6c 69 74 65 5f 73 74 65 70    /* sqlite_step
2180: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72  () has another r
2190: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66  ow ready */.#def
21a0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20  ine SQLITE_DONE 
21b0: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73         101  /* s
21c0: 71 6c 69 74 65 5f 73 74 65 70 28 29 20 68 61 73  qlite_step() has
21d0: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
21e0: 69 6e 67 20 2a 2f 0a 3c 2f 70 72 65 3e 3c 2f 62  ing */.</pre></b
21f0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a  lockquote>..<p>.
2200: 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  The meanings of 
2210: 74 68 65 73 65 20 76 61 72 69 6f 75 73 20 72 65  these various re
2220: 74 75 72 6e 20 76 61 6c 75 65 73 20 61 72 65 20  turn values are 
2230: 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 3c 2f 70 3e  as follows:.</p>
2240: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c  ..<blockquote>.<
2250: 64 6c 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 4f  dl>.<dt>SQLITE_O
2260: 4b 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68  K</dt>.<dd><p>Th
2270: 69 73 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  is value is retu
2280: 72 6e 65 64 20 69 66 20 65 76 65 72 79 74 68 69  rned if everythi
2290: 6e 67 20 77 6f 72 6b 65 64 20 61 6e 64 20 74 68  ng worked and th
22a0: 65 72 65 20 77 65 72 65 20 6e 6f 20 65 72 72 6f  ere were no erro
22b0: 72 73 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64  rs..</p></dd>.<d
22c0: 74 3e 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  t>SQLITE_INTERNA
22d0: 4c 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68  L</dt>.<dd><p>Th
22e0: 69 73 20 76 61 6c 75 65 20 69 6e 64 69 63 61 74  is value indicat
22f0: 65 73 20 74 68 61 74 20 61 6e 20 69 6e 74 65 72  es that an inter
2300: 6e 61 6c 20 63 6f 6e 73 69 73 74 65 6e 63 79 20  nal consistency 
2310: 63 68 65 63 6b 20 77 69 74 68 69 6e 0a 74 68 65  check within.the
2320: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
2330: 66 61 69 6c 65 64 2e 20 20 54 68 69 73 20 63 61  failed.  This ca
2340: 6e 20 6f 6e 6c 79 20 68 61 70 70 65 6e 20 69 66  n only happen if
2350: 20 74 68 65 72 65 20 69 73 20 61 20 62 75 67 20   there is a bug 
2360: 69 6e 0a 74 68 65 20 53 51 4c 69 74 65 20 6c 69  in.the SQLite li
2370: 62 72 61 72 79 2e 20 20 49 66 20 79 6f 75 20 65  brary.  If you e
2380: 76 65 72 20 67 65 74 20 61 6e 20 53 51 4c 49 54  ver get an SQLIT
2390: 45 5f 49 4e 54 45 52 4e 41 4c 20 72 65 70 6c 79  E_INTERNAL reply
23a0: 20 66 72 6f 6d 0a 61 6e 20 3c 62 3e 73 71 6c 69   from.an <b>sqli
23b0: 74 65 5f 65 78 65 63 3c 2f 62 3e 20 63 61 6c 6c  te_exec</b> call
23c0: 2c 20 70 6c 65 61 73 65 20 72 65 70 6f 72 74 20  , please report 
23d0: 74 68 65 20 70 72 6f 62 6c 65 6d 20 6f 6e 20 74  the problem on t
23e0: 68 65 20 53 51 4c 69 74 65 0a 6d 61 69 6c 69 6e  he SQLite.mailin
23f0: 67 20 6c 69 73 74 2e 0a 3c 2f 70 3e 3c 2f 64 64  g list..</p></dd
2400: 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 45 52 52  >.<dt>SQLITE_ERR
2410: 4f 52 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54  OR</dt>.<dd><p>T
2420: 68 69 73 20 72 65 74 75 72 6e 20 76 61 6c 75 65  his return value
2430: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
2440: 74 68 65 72 65 20 77 61 73 20 61 6e 20 65 72 72  there was an err
2450: 6f 72 20 69 6e 20 74 68 65 20 53 51 4c 0a 74 68  or in the SQL.th
2460: 61 74 20 77 61 73 20 70 61 73 73 65 64 20 69 6e  at was passed in
2470: 74 6f 20 74 68 65 20 3c 62 3e 73 71 6c 69 74 65  to the <b>sqlite
2480: 5f 65 78 65 63 3c 2f 62 3e 2e 0a 3c 2f 70 3e 3c  _exec</b>..</p><
2490: 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f  /dd>.<dt>SQLITE_
24a0: 50 45 52 4d 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70  PERM</dt>.<dd><p
24b0: 3e 54 68 69 73 20 72 65 74 75 72 6e 20 76 61 6c  >This return val
24c0: 75 65 20 73 61 79 73 20 74 68 61 74 20 74 68 65  ue says that the
24d0: 20 61 63 63 65 73 73 20 70 65 72 6d 69 73 73 69   access permissi
24e0: 6f 6e 73 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ons on the datab
24f0: 61 73 65 0a 66 69 6c 65 20 61 72 65 20 73 75 63  ase.file are suc
2500: 68 20 74 68 61 74 20 74 68 65 20 66 69 6c 65 20  h that the file 
2510: 63 61 6e 6e 6f 74 20 62 65 20 6f 70 65 6e 65 64  cannot be opened
2520: 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e  ..</p></dd>.<dt>
2530: 53 51 4c 49 54 45 5f 41 42 4f 52 54 3c 2f 64 74  SQLITE_ABORT</dt
2540: 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 76 61  >.<dd><p>This va
2550: 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  lue is returned 
2560: 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  if the callback 
2570: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
2580: 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 3c 2f 70 3e 3c   non-zero..</p><
2590: 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f  /dd>.<dt>SQLITE_
25a0: 42 55 53 59 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70  BUSY</dt>.<dd><p
25b0: 3e 54 68 69 73 20 72 65 74 75 72 6e 20 63 6f 64  >This return cod
25c0: 65 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  e indicates that
25d0: 20 61 6e 6f 74 68 65 72 20 70 72 6f 67 72 61 6d   another program
25e0: 20 6f 72 20 74 68 72 65 61 64 20 68 61 73 0a 74   or thread has.t
25f0: 68 65 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  he database lock
2600: 65 64 2e 20 20 53 51 4c 69 74 65 20 61 6c 6c 6f  ed.  SQLite allo
2610: 77 73 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  ws two or more t
2620: 68 72 65 61 64 73 20 74 6f 20 72 65 61 64 20 74  hreads to read t
2630: 68 65 0a 64 61 74 61 62 61 73 65 20 61 74 20 74  he.database at t
2640: 68 65 20 73 61 6d 65 20 74 69 6d 65 2c 20 62 75  he same time, bu
2650: 74 20 6f 6e 6c 79 20 6f 6e 65 20 74 68 72 65 61  t only one threa
2660: 64 20 63 61 6e 20 68 61 76 65 20 74 68 65 20 64  d can have the d
2670: 61 74 61 62 61 73 65 0a 6f 70 65 6e 20 66 6f 72  atabase.open for
2680: 20 77 72 69 74 69 6e 67 20 61 74 20 74 68 65 20   writing at the 
2690: 73 61 6d 65 20 74 69 6d 65 2e 20 20 4c 6f 63 6b  same time.  Lock
26a0: 69 6e 67 20 69 6e 20 53 51 4c 69 74 65 20 69 73  ing in SQLite is
26b0: 20 6f 6e 20 74 68 65 0a 65 6e 74 69 72 65 20 64   on the.entire d
26c0: 61 74 61 62 61 73 65 2e 3c 2f 70 3e 0a 3c 2f 70  atabase.</p>.</p
26d0: 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54  ></dd>.<dt>SQLIT
26e0: 45 5f 4c 4f 43 4b 45 44 3c 2f 64 74 3e 0a 3c 64  E_LOCKED</dt>.<d
26f0: 64 3e 3c 70 3e 54 68 69 73 20 72 65 74 75 72 6e  d><p>This return
2700: 20 63 6f 64 65 20 69 73 20 73 69 6d 69 6c 61 72   code is similar
2710: 20 74 6f 20 53 51 4c 49 54 45 5f 42 55 53 59 20   to SQLITE_BUSY 
2720: 69 6e 20 74 68 61 74 20 69 74 20 69 6e 64 69 63  in that it indic
2730: 61 74 65 73 0a 74 68 61 74 20 74 68 65 20 64 61  ates.that the da
2740: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
2750: 2e 20 20 42 75 74 20 74 68 65 20 73 6f 75 72 63  .  But the sourc
2760: 65 20 6f 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  e of the lock is
2770: 20 61 20 72 65 63 75 72 73 69 76 65 0a 63 61 6c   a recursive.cal
2780: 6c 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 65  l to <b>sqlite_e
2790: 78 65 63 3c 2f 62 3e 2e 20 20 54 68 69 73 20 72  xec</b>.  This r
27a0: 65 74 75 72 6e 20 63 61 6e 20 6f 6e 6c 79 20 6f  eturn can only o
27b0: 63 63 75 72 20 69 66 20 79 6f 75 20 61 74 74 65  ccur if you atte
27c0: 6d 70 74 0a 74 6f 20 69 6e 76 6f 6b 65 20 73 71  mpt.to invoke sq
27d0: 6c 69 74 65 5f 65 78 65 63 20 66 72 6f 6d 20 77  lite_exec from w
27e0: 69 74 68 69 6e 20 61 20 63 61 6c 6c 62 61 63 6b  ithin a callback
27f0: 20 72 6f 75 74 69 6e 65 20 6f 66 20 61 20 71 75   routine of a qu
2800: 65 72 79 0a 66 72 6f 6d 20 61 20 70 72 69 6f 72  ery.from a prior
2810: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 73   invocation of s
2820: 71 6c 69 74 65 5f 65 78 65 63 2e 20 20 52 65 63  qlite_exec.  Rec
2830: 75 72 73 69 76 65 20 63 61 6c 6c 73 20 74 6f 0a  ursive calls to.
2840: 73 71 6c 69 74 65 5f 65 78 65 63 20 61 72 65 20  sqlite_exec are 
2850: 61 6c 6c 6f 77 65 64 20 61 73 20 6c 6f 6e 67 20  allowed as long 
2860: 61 73 20 74 68 65 79 20 64 6f 0a 6e 6f 74 20 61  as they do.not a
2870: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
2880: 74 68 65 20 73 61 6d 65 20 74 61 62 6c 65 2e 0a  the same table..
2890: 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51  </p></dd>.<dt>SQ
28a0: 4c 49 54 45 5f 4e 4f 4d 45 4d 3c 2f 64 74 3e 0a  LITE_NOMEM</dt>.
28b0: 3c 64 64 3e 3c 70 3e 54 68 69 73 20 76 61 6c 75  <dd><p>This valu
28c0: 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  e is returned if
28d0: 20 61 20 63 61 6c 6c 20 74 6f 20 3c 62 3e 6d 61   a call to <b>ma
28e0: 6c 6c 6f 63 3c 2f 62 3e 20 66 61 69 6c 73 2e 0a  lloc</b> fails..
28f0: 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51  </p></dd>.<dt>SQ
2900: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 3c 2f 64  LITE_READONLY</d
2910: 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 72  t>.<dd><p>This r
2920: 65 74 75 72 6e 20 63 6f 64 65 20 69 6e 64 69 63  eturn code indic
2930: 61 74 65 73 20 74 68 61 74 20 61 6e 20 61 74 74  ates that an att
2940: 65 6d 70 74 20 77 61 73 20 6d 61 64 65 20 74 6f  empt was made to
2950: 20 77 72 69 74 65 20 74 6f 0a 61 20 64 61 74 61   write to.a data
2960: 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 69  base file that i
2970: 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
2980: 64 69 6e 67 20 6f 6e 6c 79 2e 0a 3c 2f 70 3e 3c  ding only..</p><
2990: 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f  /dd>.<dt>SQLITE_
29a0: 49 4e 54 45 52 52 55 50 54 3c 2f 64 74 3e 0a 3c  INTERRUPT</dt>.<
29b0: 64 64 3e 3c 70 3e 54 68 69 73 20 76 61 6c 75 65  dd><p>This value
29c0: 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
29d0: 61 20 63 61 6c 6c 20 74 6f 20 3c 62 3e 73 71 6c  a call to <b>sql
29e0: 69 74 65 5f 69 6e 74 65 72 72 75 70 74 3c 2f 62  ite_interrupt</b
29f0: 3e 0a 69 6e 74 65 72 72 75 70 74 73 20 61 20 64  >.interrupts a d
2a00: 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
2a10: 6e 20 69 6e 20 70 72 6f 67 72 65 73 73 2e 0a 3c  n in progress..<
2a20: 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c  /p></dd>.<dt>SQL
2a30: 49 54 45 5f 49 4f 45 52 52 3c 2f 64 74 3e 0a 3c  ITE_IOERR</dt>.<
2a40: 64 64 3e 3c 70 3e 54 68 69 73 20 76 61 6c 75 65  dd><p>This value
2a50: 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2a60: 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
2a70: 73 74 65 6d 20 69 6e 66 6f 72 6d 73 20 53 51 4c  stem informs SQL
2a80: 69 74 65 0a 74 68 61 74 20 69 74 20 69 73 20 75  ite.that it is u
2a90: 6e 61 62 6c 65 20 74 6f 20 70 65 72 66 6f 72 6d  nable to perform
2aa0: 20 73 6f 6d 65 20 64 69 73 6b 20 49 2f 4f 20 6f   some disk I/O o
2ab0: 70 65 72 61 74 69 6f 6e 2e 20 20 54 68 69 73 20  peration.  This 
2ac0: 63 6f 75 6c 64 20 6d 65 61 6e 0a 74 68 61 74 20  could mean.that 
2ad0: 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 6f 72 65  there is no more
2ae0: 20 73 70 61 63 65 20 6c 65 66 74 20 6f 6e 20 74   space left on t
2af0: 68 65 20 64 69 73 6b 2e 0a 3c 2f 70 3e 3c 2f 64  he disk..</p></d
2b00: 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  d>.<dt>SQLITE_CO
2b10: 52 52 55 50 54 3c 2f 64 74 3e 0a 3c 64 64 3e 3c  RRUPT</dt>.<dd><
2b20: 70 3e 54 68 69 73 20 76 61 6c 75 65 20 69 73 20  p>This value is 
2b30: 72 65 74 75 72 6e 65 64 20 69 66 20 53 51 4c 69  returned if SQLi
2b40: 74 65 20 64 65 74 65 63 74 73 20 74 68 61 74 20  te detects that 
2b50: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 74 20  the database it 
2b60: 69 73 0a 77 6f 72 6b 69 6e 67 20 6f 6e 20 68 61  is.working on ha
2b70: 73 20 62 65 63 6f 6d 65 20 63 6f 72 72 75 70 74  s become corrupt
2b80: 65 64 2e 20 20 43 6f 72 72 75 70 74 69 6f 6e 20  ed.  Corruption 
2b90: 6d 69 67 68 74 20 6f 63 63 75 72 20 64 75 65 20  might occur due 
2ba0: 74 6f 20 61 20 72 6f 67 75 65 0a 70 72 6f 63 65  to a rogue.proce
2bb0: 73 73 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68  ss writing to th
2bc0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
2bd0: 6f 72 20 69 74 20 6d 69 67 68 74 20 68 61 70 70  or it might happ
2be0: 65 6e 20 64 75 65 20 74 6f 20 61 6e 20 0a 70 65  en due to an .pe
2bf0: 72 76 69 6f 75 73 6c 79 20 75 6e 64 65 74 65 63  rviously undetec
2c00: 74 65 64 20 6c 6f 67 69 63 20 65 72 72 6f 72 20  ted logic error 
2c10: 69 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 54 68  in of SQLite. Th
2c20: 69 73 20 76 61 6c 75 65 20 69 73 20 61 6c 73 6f  is value is also
2c30: 0a 72 65 74 75 72 6e 65 64 20 69 66 20 61 20 64  .returned if a d
2c40: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
2c50: 63 75 72 73 20 69 6e 20 73 75 63 68 20 61 20 77  curs in such a w
2c60: 61 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 69  ay that SQLite i
2c70: 73 20 66 6f 72 63 65 64 0a 74 6f 20 6c 65 61 76  s forced.to leav
2c80: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
2c90: 69 6c 65 20 69 6e 20 61 20 63 6f 72 72 75 70 74  ile in a corrupt
2ca0: 65 64 20 73 74 61 74 65 2e 20 20 54 68 65 20 6c  ed state.  The l
2cb0: 61 74 74 65 72 20 73 68 6f 75 6c 64 20 6f 6e 6c  atter should onl
2cc0: 79 0a 68 61 70 70 65 6e 20 64 75 65 20 74 6f 20  y.happen due to 
2cd0: 61 20 68 61 72 64 77 61 72 65 20 6f 72 20 6f 70  a hardware or op
2ce0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 6d  erating system m
2cf0: 61 6c 66 75 6e 63 74 69 6f 6e 2e 0a 3c 2f 70 3e  alfunction..</p>
2d00: 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45  </dd>.<dt>SQLITE
2d10: 5f 46 55 4c 4c 3c 2f 64 74 3e 0a 3c 64 64 3e 3c  _FULL</dt>.<dd><
2d20: 70 3e 54 68 69 73 20 76 61 6c 75 65 20 69 73 20  p>This value is 
2d30: 72 65 74 75 72 6e 65 64 20 69 66 20 61 6e 20 69  returned if an i
2d40: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20  nsertion failed 
2d50: 62 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  because there is
2d60: 0a 6e 6f 20 73 70 61 63 65 20 6c 65 66 74 20 6f  .no space left o
2d70: 6e 20 74 68 65 20 64 69 73 6b 2c 20 6f 72 20 74  n the disk, or t
2d80: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 74  he database is t
2d90: 6f 6f 20 62 69 67 20 74 6f 20 68 6f 6c 64 20 61  oo big to hold a
2da0: 6e 79 0a 6d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  ny.more informat
2db0: 69 6f 6e 2e 20 20 54 68 65 20 6c 61 74 74 65 72  ion.  The latter
2dc0: 20 63 61 73 65 20 73 68 6f 75 6c 64 20 6f 6e 6c   case should onl
2dd0: 79 20 6f 63 63 75 72 20 66 6f 72 20 64 61 74 61  y occur for data
2de0: 62 61 73 65 73 0a 74 68 61 74 20 61 72 65 20 6c  bases.that are l
2df0: 61 72 67 65 72 20 74 68 61 6e 20 32 47 42 20 69  arger than 2GB i
2e00: 6e 20 73 69 7a 65 2e 0a 3c 2f 70 3e 3c 2f 64 64  n size..</p></dd
2e10: 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 43 41 4e  >.<dt>SQLITE_CAN
2e20: 54 4f 50 45 4e 3c 2f 64 74 3e 0a 3c 64 64 3e 3c  TOPEN</dt>.<dd><
2e30: 70 3e 54 68 69 73 20 76 61 6c 75 65 20 69 73 20  p>This value is 
2e40: 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
2e50: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 6f  database file co
2e60: 75 6c 64 20 6e 6f 74 20 62 65 20 6f 70 65 6e 65  uld not be opene
2e70: 64 0a 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  d.for some reaso
2e80: 6e 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74  n..</p></dd>.<dt
2e90: 3e 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c  >SQLITE_PROTOCOL
2ea0: 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69  </dt>.<dd><p>Thi
2eb0: 73 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  s value is retur
2ec0: 6e 65 64 20 69 66 20 73 6f 6d 65 20 6f 74 68 65  ned if some othe
2ed0: 72 20 70 72 6f 63 65 73 73 20 69 73 20 6d 65 73  r process is mes
2ee0: 73 69 6e 67 20 77 69 74 68 0a 66 69 6c 65 20 6c  sing with.file l
2ef0: 6f 63 6b 73 20 61 6e 64 20 68 61 73 20 76 69 6f  ocks and has vio
2f00: 6c 61 74 65 64 20 74 68 65 20 66 69 6c 65 20 6c  lated the file l
2f10: 6f 63 6b 69 6e 67 20 70 72 6f 74 6f 63 6f 6c 20  ocking protocol 
2f20: 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73  that SQLite uses
2f30: 0a 6f 6e 20 69 74 73 20 72 6f 6c 6c 62 61 63 6b  .on its rollback
2f40: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 73 2e 0a   journal files..
2f50: 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51  </p></dd>.<dt>SQ
2f60: 4c 49 54 45 5f 53 43 48 45 4d 41 3c 2f 64 74 3e  LITE_SCHEMA</dt>
2f70: 0a 3c 64 64 3e 3c 70 3e 57 68 65 6e 20 74 68 65  .<dd><p>When the
2f80: 20 64 61 74 61 62 61 73 65 20 66 69 72 73 74 20   database first 
2f90: 6f 70 65 6e 65 64 2c 20 53 51 4c 69 74 65 20 72  opened, SQLite r
2fa0: 65 61 64 73 20 74 68 65 20 64 61 74 61 62 61 73  eads the databas
2fb0: 65 20 73 63 68 65 6d 61 0a 69 6e 74 6f 20 6d 65  e schema.into me
2fc0: 6d 6f 72 79 20 61 6e 64 20 75 73 65 73 20 74 68  mory and uses th
2fd0: 61 74 20 73 63 68 65 6d 61 20 74 6f 20 70 61 72  at schema to par
2fe0: 73 65 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  se new SQL state
2ff0: 6d 65 6e 74 73 2e 20 20 49 66 20 61 6e 6f 74 68  ments.  If anoth
3000: 65 72 0a 70 72 6f 63 65 73 73 20 63 68 61 6e 67  er.process chang
3010: 65 73 20 74 68 65 20 73 63 68 65 6d 61 2c 20 74  es the schema, t
3020: 68 65 20 63 6f 6d 6d 61 6e 64 20 63 75 72 72 65  he command curre
3030: 6e 74 6c 79 20 62 65 69 6e 67 20 70 72 6f 63 65  ntly being proce
3040: 73 73 65 64 20 77 69 6c 6c 0a 61 62 6f 72 74 20  ssed will.abort 
3050: 62 65 63 61 75 73 65 20 74 68 65 20 76 69 72 74  because the virt
3060: 75 61 6c 20 6d 61 63 68 69 6e 65 20 63 6f 64 65  ual machine code
3070: 20 67 65 6e 65 72 61 74 65 64 20 61 73 73 75 6d   generated assum
3080: 65 64 20 74 68 65 20 6f 6c 64 0a 73 63 68 65 6d  ed the old.schem
3090: 61 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  a.  This is the 
30a0: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 6f 72 20  return code for 
30b0: 73 75 63 68 20 63 61 73 65 73 2e 20 20 52 65 74  such cases.  Ret
30c0: 72 79 69 6e 67 20 74 68 65 0a 63 6f 6d 6d 61 6e  rying the.comman
30d0: 64 20 75 73 75 61 6c 6c 79 20 77 69 6c 6c 20 63  d usually will c
30e0: 6c 65 61 72 20 74 68 65 20 70 72 6f 62 6c 65 6d  lear the problem
30f0: 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e  ..</p></dd>.<dt>
3100: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 3c 2f 64  SQLITE_TOOBIG</d
3110: 74 3e 0a 3c 64 64 3e 3c 70 3e 53 51 4c 69 74 65  t>.<dd><p>SQLite
3120: 20 77 69 6c 6c 20 6e 6f 74 20 73 74 6f 72 65 20   will not store 
3130: 6d 6f 72 65 20 74 68 61 6e 20 61 62 6f 75 74 20  more than about 
3140: 31 20 6d 65 67 61 62 79 74 65 20 6f 66 20 64 61  1 megabyte of da
3150: 74 61 20 69 6e 20 61 20 73 69 6e 67 6c 65 0a 72  ta in a single.r
3160: 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
3170: 61 62 6c 65 2e 20 20 49 66 20 79 6f 75 20 61 74  able.  If you at
3180: 74 65 6d 70 74 20 74 6f 20 73 74 6f 72 65 20 6d  tempt to store m
3190: 6f 72 65 20 74 68 61 6e 20 31 20 6d 65 67 61 62  ore than 1 megab
31a0: 79 74 65 0a 69 6e 20 61 20 73 69 6e 67 6c 65 20  yte.in a single 
31b0: 72 6f 77 2c 20 74 68 69 73 20 69 73 20 74 68 65  row, this is the
31c0: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 79 6f 75   return code you
31d0: 20 67 65 74 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a   get..</p></dd>.
31e0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 53 54  <dt>SQLITE_CONST
31f0: 52 41 49 4e 54 3c 2f 64 74 3e 0a 3c 64 64 3e 3c  RAINT</dt>.<dd><
3200: 70 3e 54 68 69 73 20 63 6f 6e 73 74 61 6e 74 20  p>This constant 
3210: 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
3220: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3230: 20 77 6f 75 6c 64 20 68 61 76 65 20 76 69 6f 6c   would have viol
3240: 61 74 65 64 0a 61 20 64 61 74 61 62 61 73 65 20  ated.a database 
3250: 63 6f 6e 73 74 72 61 69 6e 74 2e 0a 3c 2f 70 3e  constraint..</p>
3260: 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45  </dd>.<dt>SQLITE
3270: 5f 4d 49 53 4d 41 54 43 48 3c 2f 64 74 3e 0a 3c  _MISMATCH</dt>.<
3280: 64 64 3e 3c 70 3e 54 68 69 73 20 65 72 72 6f 72  dd><p>This error
3290: 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
32a0: 72 65 20 69 73 20 61 6e 20 61 74 74 65 6d 70 74  re is an attempt
32b0: 20 74 6f 20 69 6e 73 65 72 74 20 6e 6f 6e 2d 69   to insert non-i
32c0: 6e 74 65 67 65 72 0a 64 61 74 61 20 69 6e 74 6f  nteger.data into
32d0: 20 61 20 63 6f 6c 75 6d 6e 20 6c 61 62 65 6c 65   a column labele
32e0: 64 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52  d INTEGER PRIMAR
32f0: 59 20 4b 45 59 2e 20 20 46 6f 72 20 6d 6f 73 74  Y KEY.  For most
3300: 20 63 6f 6c 75 6d 6e 73 2c 20 53 51 4c 69 74 65   columns, SQLite
3310: 0a 69 67 6e 6f 72 65 73 20 74 68 65 20 64 61 74  .ignores the dat
3320: 61 20 74 79 70 65 20 61 6e 64 20 61 6c 6c 6f 77  a type and allow
3330: 73 20 61 6e 79 20 6b 69 6e 64 20 6f 66 20 64 61  s any kind of da
3340: 74 61 20 74 6f 20 62 65 20 73 74 6f 72 65 64 2e  ta to be stored.
3350: 20 20 42 75 74 0a 61 6e 20 49 4e 54 45 47 45 52    But.an INTEGER
3360: 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c   PRIMARY KEY col
3370: 75 6d 6e 20 69 73 20 6f 6e 6c 79 20 61 6c 6c 6f  umn is only allo
3380: 77 65 64 20 74 6f 20 73 74 6f 72 65 20 69 6e 74  wed to store int
3390: 65 67 65 72 20 64 61 74 61 2e 0a 3c 2f 70 3e 3c  eger data..</p><
33a0: 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f  /dd>.<dt>SQLITE_
33b0: 4d 49 53 55 53 45 3c 2f 64 74 3e 0a 3c 64 64 3e  MISUSE</dt>.<dd>
33c0: 3c 70 3e 54 68 69 73 20 65 72 72 6f 72 20 6d 69  <p>This error mi
33d0: 67 68 74 20 6f 63 63 75 72 20 69 66 20 6f 6e 65  ght occur if one
33e0: 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20   or more of the 
33f0: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69  SQLite API routi
3400: 6e 65 73 0a 69 73 20 75 73 65 64 20 69 6e 63 6f  nes.is used inco
3410: 72 72 65 63 74 6c 79 2e 20 20 45 78 61 6d 70 6c  rrectly.  Exampl
3420: 65 73 20 6f 66 20 69 6e 63 6f 72 72 65 63 74 20  es of incorrect 
3430: 75 73 61 67 65 20 69 6e 63 6c 75 64 65 20 63 61  usage include ca
3440: 6c 6c 69 6e 67 0a 3c 62 3e 73 71 6c 69 74 65 5f  lling.<b>sqlite_
3450: 65 78 65 63 3c 2f 62 3e 20 61 66 74 65 72 20 74  exec</b> after t
3460: 68 65 20 64 61 74 61 62 61 73 65 20 68 61 73 20  he database has 
3470: 62 65 65 6e 20 63 6c 6f 73 65 64 20 75 73 69 6e  been closed usin
3480: 67 0a 3c 62 3e 73 71 6c 69 74 65 5f 63 6c 6f 73  g.<b>sqlite_clos
3490: 65 3c 2f 62 3e 20 6f 72 20 0a 63 61 6c 6c 69 6e  e</b> or .callin
34a0: 67 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63  g <b>sqlite_exec
34b0: 3c 2f 62 3e 20 77 69 74 68 20 74 68 65 20 73 61  </b> with the sa
34c0: 6d 65 0a 64 61 74 61 62 61 73 65 20 70 6f 69 6e  me.database poin
34d0: 74 65 72 20 73 69 6d 75 6c 74 61 6e 65 6f 75 73  ter simultaneous
34e0: 6c 79 20 66 72 6f 6d 20 74 77 6f 20 73 65 70 61  ly from two sepa
34f0: 72 61 74 65 20 74 68 72 65 61 64 73 2e 0a 3c 2f  rate threads..</
3500: 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49  p></dd>.<dt>SQLI
3510: 54 45 5f 4e 4f 4c 46 53 3c 2f 64 74 3e 0a 3c 64  TE_NOLFS</dt>.<d
3520: 64 3e 3c 70 3e 54 68 69 73 20 65 72 72 6f 72 20  d><p>This error 
3530: 6d 65 61 6e 73 20 74 68 61 74 20 79 6f 75 20 68  means that you h
3540: 61 76 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ave attempts to 
3550: 63 72 65 61 74 65 20 6f 72 20 61 63 63 65 73 73  create or access
3560: 20 61 20 66 69 6c 65 0a 64 61 74 61 62 61 73 65   a file.database
3570: 20 66 69 6c 65 20 74 68 61 74 20 69 73 20 6c 61   file that is la
3580: 72 67 65 72 20 74 68 61 74 20 32 47 42 20 6f 6e  rger that 2GB on
3590: 20 61 20 6c 65 67 61 63 79 20 55 6e 69 78 20 6d   a legacy Unix m
35a0: 61 63 68 69 6e 65 20 74 68 61 74 0a 6c 61 63 6b  achine that.lack
35b0: 73 20 6c 61 72 67 65 20 66 69 6c 65 20 73 75 70  s large file sup
35c0: 70 6f 72 74 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a  port..</p></dd>.
35d0: 3c 64 74 3e 53 51 4c 49 54 45 5f 41 55 54 48 3c  <dt>SQLITE_AUTH<
35e0: 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73  /dt>.<dd><p>This
35f0: 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 65 73   error indicates
3600: 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
3610: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 68 61  izer callback.ha
3620: 73 20 64 69 73 61 6c 6c 6f 77 65 64 20 74 68 65  s disallowed the
3630: 20 53 51 4c 20 79 6f 75 20 61 72 65 20 61 74 74   SQL you are att
3640: 65 6d 70 74 69 6e 67 20 74 6f 20 65 78 65 63 75  empting to execu
3650: 74 65 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64  te..</p></dd>.<d
3660: 74 3e 53 51 4c 49 54 45 5f 52 4f 57 3c 2f 64 74  t>SQLITE_ROW</dt
3670: 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 69 73  >.<dd><p>This is
3680: 20 6f 6e 65 20 6f 66 20 74 68 65 20 72 65 74 75   one of the retu
3690: 72 6e 20 63 6f 64 65 73 20 66 72 6f 6d 20 74 68  rn codes from th
36a0: 65 0a 3c 62 3e 73 71 6c 69 74 65 5f 73 74 65 70  e.<b>sqlite_step
36b0: 3c 2f 62 3e 20 72 6f 75 74 69 6e 65 20 77 68 69  </b> routine whi
36c0: 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  ch is part of th
36d0: 65 20 6e 6f 6e 2d 63 61 6c 6c 62 61 63 6b 20 41  e non-callback A
36e0: 50 49 2e 0a 49 74 20 69 6e 64 69 63 61 74 65 73  PI..It indicates
36f0: 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 72 6f   that another ro
3700: 77 20 6f 66 20 72 65 73 75 6c 74 20 64 61 74 61  w of result data
3710: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 3c   is available..<
3720: 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c  /p></dd>.<dt>SQL
3730: 49 54 45 5f 44 4f 4e 45 3c 2f 64 74 3e 0a 3c 64  ITE_DONE</dt>.<d
3740: 64 3e 3c 70 3e 54 68 69 73 20 69 73 20 6f 6e 65  d><p>This is one
3750: 20 6f 66 20 74 68 65 20 72 65 74 75 72 6e 20 63   of the return c
3760: 6f 64 65 73 20 66 72 6f 6d 20 74 68 65 0a 3c 62  odes from the.<b
3770: 3e 73 71 6c 69 74 65 5f 73 74 65 70 3c 2f 62 3e  >sqlite_step</b>
3780: 20 72 6f 75 74 69 6e 65 20 77 68 69 63 68 20 69   routine which i
3790: 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 6f  s part of the no
37a0: 6e 2d 63 61 6c 6c 62 61 63 6b 20 41 50 49 2e 0a  n-callback API..
37b0: 49 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  It indicates tha
37c0: 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
37d0: 65 6e 74 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  ent has been com
37e0: 70 6c 65 74 65 6c 79 20 65 78 65 63 75 74 65 64  pletely executed
37f0: 20 61 6e 64 0a 74 68 65 20 3c 62 3e 73 71 6c 69   and.the <b>sqli
3800: 74 65 5f 66 69 6e 61 6c 69 7a 65 3c 2f 62 3e 20  te_finalize</b> 
3810: 72 6f 75 74 69 6e 65 20 69 73 20 72 65 61 64 79  routine is ready
3820: 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 2e 0a 3c   to be called..<
3830: 2f 70 3e 3c 2f 64 64 3e 0a 3c 2f 64 6c 3e 0a 3c  /p></dd>.</dl>.<
3840: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 68  /blockquote>..<h
3850: 32 3e 32 2e 30 20 41 63 63 65 73 73 69 6e 67 20  2>2.0 Accessing 
3860: 44 61 74 61 20 57 69 74 68 6f 75 74 20 55 73 69  Data Without Usi
3870: 6e 67 20 41 20 43 61 6c 6c 62 61 63 6b 20 46 75  ng A Callback Fu
3880: 6e 63 74 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e  nction</h2>..<p>
3890: 0a 54 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 65  .The <b>sqlite_e
38a0: 78 65 63 3c 2f 62 3e 20 72 6f 75 74 69 6e 65 20  xec</b> routine 
38b0: 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 20  described above 
38c0: 75 73 65 64 20 74 6f 20 62 65 20 74 68 65 20 6f  used to be the o
38d0: 6e 6c 79 0a 77 61 79 20 74 6f 20 72 65 74 72 69  nly.way to retri
38e0: 65 76 65 20 64 61 74 61 20 66 72 6f 6d 20 61 6e  eve data from an
38f0: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
3900: 2e 20 20 42 75 74 20 6d 61 6e 79 20 70 72 6f 67  .  But many prog
3910: 72 61 6d 6d 65 72 73 20 66 6f 75 6e 64 0a 69 74  rammers found.it
3920: 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 74 20 74 6f   inconvenient to
3930: 20 75 73 65 20 61 20 63 61 6c 6c 62 61 63 6b 20   use a callback 
3940: 66 75 6e 63 74 69 6f 6e 20 74 6f 20 6f 62 74 61  function to obta
3950: 69 6e 20 72 65 73 75 6c 74 73 2e 20 20 53 6f 20  in results.  So 
3960: 62 65 67 69 6e 6e 69 6e 67 0a 77 69 74 68 20 53  beginning.with S
3970: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 2e  QLite version 2.
3980: 37 2e 37 2c 20 61 20 73 65 63 6f 6e 64 20 61 63  7.7, a second ac
3990: 63 65 73 73 20 69 6e 74 65 72 66 61 63 65 20 69  cess interface i
39a0: 73 20 61 76 61 69 6c 61 62 6c 65 20 74 68 61 74  s available that
39b0: 0a 64 6f 65 73 20 6e 6f 74 20 75 73 65 20 63 61  .does not use ca
39c0: 6c 6c 62 61 63 6b 73 2e 0a 3c 2f 70 3e 0a 0a 3c  llbacks..</p>..<
39d0: 70 3e 0a 54 68 65 20 6e 65 77 20 69 6e 74 65 72  p>.The new inter
39e0: 66 61 63 65 20 75 73 65 73 20 74 68 72 65 65 20  face uses three 
39f0: 73 65 70 61 72 61 74 65 20 66 75 6e 63 74 69 6f  separate functio
3a00: 6e 73 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68  ns to replace th
3a10: 65 20 73 69 6e 67 6c 65 0a 3c 62 3e 73 71 6c 69  e single.<b>sqli
3a20: 74 65 5f 65 78 65 63 3c 2f 62 3e 20 66 75 6e 63  te_exec</b> func
3a30: 74 69 6f 6e 2e 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f  tion..</p>..<blo
3a40: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 74 79  ckquote><pre>.ty
3a50: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
3a60: 69 74 65 5f 76 6d 20 73 71 6c 69 74 65 5f 76 6d  ite_vm sqlite_vm
3a70: 3b 0a 0a 69 6e 74 20 73 71 6c 69 74 65 5f 63 6f  ;..int sqlite_co
3a80: 6d 70 69 6c 65 28 0a 20 20 73 71 6c 69 74 65 20  mpile(.  sqlite 
3a90: 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
3aa0: 20 20 2f 2a 20 54 68 65 20 6f 70 65 6e 20 64 61    /* The open da
3ab0: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
3ac0: 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
3ad0: 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
3ae0: 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
3af0: 69 6c 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  iled */.  const 
3b00: 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 2c 20 20  char **pzTail,  
3b10: 20 20 20 2f 2a 20 4f 55 54 3a 20 75 6e 63 6f 6d     /* OUT: uncom
3b20: 70 69 6c 65 64 20 74 61 69 6c 20 6f 66 20 7a 53  piled tail of zS
3b30: 71 6c 20 2a 2f 0a 20 20 73 71 6c 69 74 65 5f 76  ql */.  sqlite_v
3b40: 6d 20 2a 2a 70 70 56 6d 2c 20 20 20 20 20 20 20  m **ppVm,       
3b50: 20 2f 2a 20 4f 55 54 3a 20 74 68 65 20 76 69 72   /* OUT: the vir
3b60: 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 6f 20  tual machine to 
3b70: 65 78 65 63 75 74 65 20 7a 53 71 6c 20 2a 2f 0a  execute zSql */.
3b80: 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
3b90: 67 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  g          /* OU
3ba0: 54 3a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65  T: Error message
3bb0: 2e 20 2a 2f 0a 29 3b 0a 0a 69 6e 74 20 73 71 6c  . */.);..int sql
3bc0: 69 74 65 5f 73 74 65 70 28 0a 20 20 73 71 6c 69  ite_step(.  sqli
3bd0: 74 65 5f 76 6d 20 2a 70 56 6d 2c 20 20 20 20 20  te_vm *pVm,     
3be0: 20 20 20 20 20 2f 2a 20 54 68 65 20 76 69 72 74       /* The virt
3bf0: 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 6f 20 65  ual machine to e
3c00: 78 65 63 75 74 65 20 2a 2f 0a 20 20 69 6e 74 20  xecute */.  int 
3c10: 2a 70 4e 2c 20 20 20 20 20 20 20 20 20 20 20 20  *pN,            
3c20: 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 4e 75 6d       /* OUT: Num
3c30: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
3c40: 6e 20 72 65 73 75 6c 74 20 2a 2f 0a 20 20 63 6f  n result */.  co
3c50: 6e 73 74 20 63 68 61 72 20 2a 2a 2a 70 61 7a 56  nst char ***pazV
3c60: 61 6c 75 65 2c 20 20 2f 2a 20 4f 55 54 3a 20 43  alue,  /* OUT: C
3c70: 6f 6c 75 6d 6e 20 64 61 74 61 20 2a 2f 0a 20 20  olumn data */.  
3c80: 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 2a 70 61  const char ***pa
3c90: 7a 43 6f 6c 4e 61 6d 65 20 2f 2a 20 4f 55 54 3a  zColName /* OUT:
3ca0: 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 61 6e   Column names an
3cb0: 64 20 64 61 74 61 74 79 70 65 73 20 2a 2f 0a 29  d datatypes */.)
3cc0: 3b 0a 0a 69 6e 74 20 73 71 6c 69 74 65 5f 66 69  ;..int sqlite_fi
3cd0: 6e 61 6c 69 7a 65 28 0a 20 20 73 71 6c 69 74 65  nalize(.  sqlite
3ce0: 5f 76 6d 20 2a 70 56 6d 2c 20 20 20 20 20 20 20  _vm *pVm,       
3cf0: 20 20 20 2f 2a 20 54 68 65 20 76 69 72 74 75 61     /* The virtua
3d00: 6c 20 6d 61 63 68 69 6e 65 20 74 6f 20 62 65 20  l machine to be 
3d10: 66 69 6e 61 6c 69 7a 65 64 20 2a 2f 0a 20 20 63  finalized */.  c
3d20: 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20  har **pzErrMsg  
3d30: 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
3d40: 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 2a 2f  Error message */
3d50: 0a 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .);.</pre></bloc
3d60: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65  kquote>..<p>.The
3d70: 20 73 74 72 61 74 65 67 79 20 69 73 20 74 6f 20   strategy is to 
3d80: 63 6f 6d 70 69 6c 65 20 61 20 73 69 6e 67 6c 65  compile a single
3d90: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
3da0: 73 69 6e 67 0a 3c 62 3e 73 71 6c 69 74 65 5f 63  sing.<b>sqlite_c
3db0: 6f 6d 70 69 6c 65 3c 2f 62 3e 20 74 68 65 6e 20  ompile</b> then 
3dc0: 69 6e 76 6f 6b 65 20 3c 62 3e 73 71 6c 69 74 65  invoke <b>sqlite
3dd0: 5f 73 74 65 70 3c 2f 62 3e 20 6d 75 6c 74 69 70  _step</b> multip
3de0: 6c 65 20 74 69 6d 65 73 2c 0a 6f 6e 63 65 20 66  le times,.once f
3df0: 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 6f  or each row of o
3e00: 75 74 70 75 74 2c 20 61 6e 64 20 66 69 6e 61 6c  utput, and final
3e10: 6c 79 20 63 61 6c 6c 20 3c 62 3e 73 71 6c 69 74  ly call <b>sqlit
3e20: 65 5f 66 69 6e 61 6c 69 7a 65 3c 2f 62 3e 0a 74  e_finalize</b>.t
3e30: 6f 20 63 6c 65 61 6e 20 75 70 20 61 66 74 65 72  o clean up after
3e40: 20 74 68 65 20 53 51 4c 20 68 61 73 20 66 69 6e   the SQL has fin
3e50: 69 73 68 65 64 20 65 78 65 63 75 74 69 6f 6e 2e  ished execution.
3e60: 0a 3c 2f 70 3e 0a 0a 3c 68 33 3e 32 2e 31 20 43  .</p>..<h3>2.1 C
3e70: 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
3e80: 53 74 61 74 65 6d 65 6e 74 20 49 6e 74 6f 20 41  Statement Into A
3e90: 20 56 69 72 74 75 61 6c 20 4d 61 63 68 69 6e 65   Virtual Machine
3ea0: 3c 2f 68 33 3e 0a 0a 3c 70 3e 0a 54 68 65 20 3c  </h3>..<p>.The <
3eb0: 62 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65  b>sqlite_compile
3ec0: 3c 2f 62 3e 20 22 63 6f 6d 70 69 6c 65 73 22 20  </b> "compiles" 
3ed0: 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
3ee0: 74 65 6d 65 6e 74 20 28 73 70 65 63 69 66 69 65  tement (specifie
3ef0: 64 0a 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d.by the second 
3f00: 70 61 72 61 6d 65 74 65 72 29 20 61 6e 64 20 67  parameter) and g
3f10: 65 6e 65 72 61 74 65 73 20 61 20 76 69 72 74 75  enerates a virtu
3f20: 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20  al machine that 
3f30: 69 73 20 61 62 6c 65 0a 74 6f 20 65 78 65 63 75  is able.to execu
3f40: 74 65 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  te that statemen
3f50: 74 2e 20 20 0a 41 73 20 77 69 74 68 20 6d 75 73  t.  .As with mus
3f60: 74 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  t interface rout
3f70: 69 6e 65 73 2c 20 74 68 65 20 66 69 72 73 74 20  ines, the first 
3f80: 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
3f90: 65 20 61 20 70 6f 69 6e 74 65 72 0a 74 6f 20 61  e a pointer.to a
3fa0: 6e 20 73 71 6c 69 74 65 20 73 74 72 75 63 74 75  n sqlite structu
3fb0: 72 65 20 74 68 61 74 20 77 61 73 20 6f 62 74 61  re that was obta
3fc0: 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
3fd0: 72 20 63 61 6c 6c 20 74 6f 0a 3c 62 3e 73 71 6c  r call to.<b>sql
3fe0: 69 74 65 5f 6f 70 65 6e 3c 2f 62 3e 2e 0a 0a 3c  ite_open</b>...<
3ff0: 70 3e 0a 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  p>.A pointer to 
4000: 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68  the virtual mach
4010: 69 6e 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ine is stored in
4020: 20 61 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68   a pointer which
4030: 20 69 73 20 70 61 73 73 65 64 0a 69 6e 20 61 73   is passed.in as
4040: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
4050: 65 72 2e 0a 53 70 61 63 65 20 74 6f 20 68 6f 6c  er..Space to hol
4060: 64 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61  d the virtual ma
4070: 63 68 69 6e 65 20 69 73 20 64 79 6e 61 6d 69 63  chine is dynamic
4080: 61 6c 6c 79 20 61 6c 6c 6f 63 61 74 65 64 2e 20  ally allocated. 
4090: 20 54 6f 20 61 76 6f 69 64 0a 61 20 6d 65 6d 6f   To avoid.a memo
40a0: 72 79 20 6c 65 61 6b 2c 20 74 68 65 20 63 61 6c  ry leak, the cal
40b0: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ling function mu
40c0: 73 74 20 69 6e 76 6f 6b 65 0a 3c 62 3e 73 71 6c  st invoke.<b>sql
40d0: 69 74 65 5f 66 69 6e 61 6c 69 7a 65 3c 2f 62 3e  ite_finalize</b>
40e0: 20 6f 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20   on the virtual 
40f0: 6d 61 63 68 69 6e 65 20 61 66 74 65 72 20 69 74  machine after it
4100: 20 68 61 73 20 66 69 6e 69 73 68 65 64 0a 77 69   has finished.wi
4110: 74 68 20 69 74 2e 0a 54 68 65 20 34 74 68 20 70  th it..The 4th p
4120: 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
4130: 73 65 74 20 74 6f 20 4e 55 4c 4c 20 69 66 20 61  set to NULL if a
4140: 6e 20 65 72 72 6f 72 20 69 73 20 65 6e 63 6f 75  n error is encou
4150: 6e 74 65 72 65 64 20 64 75 72 69 6e 67 0a 63 6f  ntered during.co
4160: 6d 70 69 6c 61 74 69 6f 6e 2e 0a 3c 2f 70 3e 0a  mpilation..</p>.
4170: 0a 3c 70 3e 0a 49 66 20 61 6e 79 20 65 72 72 6f  .<p>.If any erro
4180: 72 73 20 61 72 65 20 65 6e 63 6f 75 6e 74 65 72  rs are encounter
4190: 65 64 20 64 75 72 69 6e 67 20 63 6f 6d 70 69 6c  ed during compil
41a0: 61 74 69 6f 6e 2c 20 61 6e 20 65 72 72 6f 72 20  ation, an error 
41b0: 6d 65 73 73 61 67 65 20 69 73 0a 77 72 69 74 74  message is.writt
41c0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
41d0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 3c 62 3e  btained from <b>
41e0: 6d 61 6c 6c 6f 63 3c 2f 62 3e 20 61 6e 64 20 74  malloc</b> and t
41f0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
4200: 0a 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e  .is made to poin
4210: 74 20 74 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79  t to that memory
4220: 2e 20 20 49 66 20 74 68 65 20 35 74 68 20 70 61  .  If the 5th pa
4230: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 2c  rameter is NULL,
4240: 20 74 68 65 6e 0a 6e 6f 20 65 72 72 6f 72 20 6d   then.no error m
4250: 65 73 73 61 67 65 20 69 73 20 67 65 6e 65 72 61  essage is genera
4260: 74 65 64 2e 20 20 49 66 20 74 68 65 20 35 74 68  ted.  If the 5th
4270: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
4280: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 74 68 65  t NULL, then.the
4290: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
42a0: 6e 20 73 68 6f 75 6c 64 20 64 69 73 70 6f 73 65  n should dispose
42b0: 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 63   of the memory c
42c0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 65 72  ontaining the er
42d0: 72 6f 72 0a 6d 65 73 73 61 67 65 20 62 79 20 63  ror.message by c
42e0: 61 6c 6c 69 6e 67 20 3c 62 3e 73 71 6c 69 74 65  alling <b>sqlite
42f0: 5f 66 72 65 65 6d 65 6d 3c 2f 62 3e 2e 0a 3c 2f  _freemem</b>..</
4300: 70 3e 0a 0a 3c 70 3e 0a 49 66 20 74 68 65 20 32  p>..<p>.If the 2
4310: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 63 74  nd parameter act
4320: 75 61 6c 6c 79 20 63 6f 6e 74 61 69 6e 73 20 74  ually contains t
4330: 77 6f 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 65  wo or more state
4340: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 2c 0a 6f 6e  ments of SQL,.on
4350: 6c 79 20 74 68 65 20 66 69 72 73 74 20 73 74 61  ly the first sta
4360: 74 65 6d 65 6e 74 20 69 73 20 63 6f 6d 70 69 6c  tement is compil
4370: 65 64 2e 20 20 28 54 68 69 73 20 69 73 20 64 69  ed.  (This is di
4380: 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
4390: 0a 62 65 68 61 76 69 6f 72 20 6f 66 20 3c 62 3e  .behavior of <b>
43a0: 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e 20  sqlite_exec</b> 
43b0: 77 68 69 63 68 20 65 78 65 63 75 74 65 73 20 61  which executes a
43c0: 6c 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ll SQL statement
43d0: 73 0a 69 6e 20 69 74 73 20 69 6e 70 75 74 20 73  s.in its input s
43e0: 74 72 69 6e 67 2e 29 20 20 54 68 65 20 33 72 64  tring.)  The 3rd
43f0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 3c 62   parameter to <b
4400: 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 3c  >sqlite_compile<
4410: 2f 62 3e 0a 69 73 20 6d 61 64 65 20 74 6f 20 70  /b>.is made to p
4420: 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
4430: 74 20 63 68 61 72 61 63 74 65 72 20 62 65 79 6f  t character beyo
4440: 6e 64 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  nd the end of th
4450: 65 20 66 69 72 73 74 0a 73 74 61 74 65 6d 65 6e  e first.statemen
4460: 74 20 6f 66 20 53 51 4c 20 69 6e 20 74 68 65 20  t of SQL in the 
4470: 69 6e 70 75 74 2e 20 20 49 66 20 74 68 65 20 32  input.  If the 2
4480: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 63 6f 6e  nd parameter con
4490: 74 61 69 6e 73 20 6f 6e 6c 79 0a 61 20 73 69 6e  tains only.a sin
44a0: 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
44b0: 74 2c 20 74 68 65 6e 20 74 68 65 20 33 72 64 20  t, then the 3rd 
44c0: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 62  parameter will b
44d0: 65 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 0a  e made to point.
44e0: 74 6f 20 74 68 65 20 27 5c 30 30 30 27 20 74 65  to the '\000' te
44f0: 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20  rminator at the 
4500: 65 6e 64 20 6f 66 20 74 68 65 20 32 6e 64 20 70  end of the 2nd p
4510: 61 72 61 6d 65 74 65 72 2e 0a 3c 2f 70 3e 0a 0a  arameter..</p>..
4520: 3c 70 3e 0a 4f 6e 20 73 75 63 63 65 73 73 2c 20  <p>.On success, 
4530: 3c 62 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c  <b>sqlite_compil
4540: 65 3c 2f 62 3e 20 72 65 74 75 72 6e 73 20 53 51  e</b> returns SQ
4550: 4c 49 54 45 5f 4f 4b 2e 0a 4f 74 68 65 72 77 69  LITE_OK..Otherwi
4560: 73 65 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 64  se and error cod
4570: 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 3c  e is returned..<
4580: 2f 70 3e 0a 0a 3c 68 33 3e 32 2e 32 20 53 74 65  /p>..<h3>2.2 Ste
4590: 70 2d 42 79 2d 53 74 65 70 20 45 78 65 63 75 74  p-By-Step Execut
45a0: 69 6f 6e 20 4f 66 20 41 6e 20 53 51 4c 20 53 74  ion Of An SQL St
45b0: 61 74 65 6d 65 6e 74 3c 2f 68 33 3e 0a 0a 3c 70  atement</h3>..<p
45c0: 3e 0a 41 66 74 65 72 20 61 20 76 69 72 74 75 61  >.After a virtua
45d0: 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 62 65  l machine has be
45e0: 65 6e 20 67 65 6e 65 72 61 74 65 64 20 75 73 69  en generated usi
45f0: 6e 67 20 3c 62 3e 73 71 6c 69 74 65 5f 63 6f 6d  ng <b>sqlite_com
4600: 70 69 6c 65 3c 2f 62 3e 0a 69 74 20 69 73 20 65  pile</b>.it is e
4610: 78 65 63 75 74 65 64 20 62 79 20 6f 6e 65 20 6f  xecuted by one o
4620: 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
4630: 3c 62 3e 73 71 6c 69 74 65 5f 73 74 65 70 3c 2f  <b>sqlite_step</
4640: 62 3e 2e 20 20 45 61 63 68 0a 69 6e 76 6f 63 61  b>.  Each.invoca
4650: 74 69 6f 6e 20 6f 66 20 3c 62 3e 73 71 6c 69 74  tion of <b>sqlit
4660: 65 5f 73 74 65 70 3c 2f 62 3e 2c 20 65 78 63 65  e_step</b>, exce
4670: 70 74 20 74 68 65 20 6c 61 73 74 20 6f 6e 65 2c  pt the last one,
4680: 0a 72 65 74 75 72 6e 73 20 61 20 73 69 6e 67 6c  .returns a singl
4690: 65 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  e row of the res
46a0: 75 6c 74 2e 0a 54 68 65 20 6e 75 6d 62 65 72 20  ult..The number 
46b0: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 20 74  of columns in  t
46c0: 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f  he result is sto
46d0: 72 65 64 20 69 6e 20 74 68 65 20 69 6e 74 65 67  red in the integ
46e0: 65 72 20 74 68 61 74 0a 74 68 65 20 32 6e 64 20  er that.the 2nd 
46f0: 70 61 72 61 6d 65 74 65 72 20 70 6f 69 6e 74 73  parameter points
4700: 20 74 6f 2e 0a 54 68 65 20 70 6f 69 6e 74 65 72   to..The pointer
4710: 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
4720: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
4730: 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
4740: 0a 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20  .to an array of 
4750: 70 6f 69 6e 74 65 72 73 20 74 6f 20 63 6f 6c 75  pointers to colu
4760: 6d 6e 20 76 61 6c 75 65 73 2e 0a 54 68 65 20 70  mn values..The p
4770: 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 34 74  ointer in the 4t
4780: 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6d  h parameter is m
4790: 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
47a0: 61 6e 20 61 72 72 61 79 0a 6f 66 20 70 6f 69 6e  an array.of poin
47b0: 74 65 72 73 20 74 6f 20 63 6f 6c 75 6d 6e 20 6e  ters to column n
47c0: 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70  ames and datatyp
47d0: 65 73 2e 0a 54 68 65 20 32 6e 64 20 74 68 72 6f  es..The 2nd thro
47e0: 75 67 68 20 34 74 68 20 70 61 72 61 6d 65 74 65  ugh 4th paramete
47f0: 72 73 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f  rs to <b>sqlite_
4800: 73 74 65 70 3c 2f 62 3e 20 63 6f 6e 76 65 79 20  step</b> convey 
4810: 74 68 65 0a 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the.same informa
4820: 74 69 6f 6e 20 61 73 20 74 68 65 20 32 6e 64 20  tion as the 2nd 
4830: 74 68 72 6f 75 67 68 20 34 74 68 20 70 61 72 61  through 4th para
4840: 6d 65 74 65 72 73 20 6f 66 20 74 68 65 0a 3c 62  meters of the.<b
4850: 3e 63 61 6c 6c 62 61 63 6b 3c 2f 62 3e 20 72 6f  >callback</b> ro
4860: 75 74 69 6e 65 20 77 68 65 6e 20 75 73 69 6e 67  utine when using
4870: 0a 74 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 65  .the <b>sqlite_e
4880: 78 65 63 3c 2f 62 3e 20 69 6e 74 65 72 66 61 63  xec</b> interfac
4890: 65 2e 20 20 45 78 63 65 70 74 2c 20 77 69 74 68  e.  Except, with
48a0: 20 3c 62 3e 73 71 6c 69 74 65 5f 73 74 65 70 3c   <b>sqlite_step<
48b0: 2f 62 3e 0a 74 68 65 20 63 6f 6c 75 6d 6e 20 64  /b>.the column d
48c0: 61 74 61 74 79 70 65 20 69 6e 66 6f 72 6d 61 74  atatype informat
48d0: 69 6f 6e 20 69 73 20 61 6c 77 61 79 73 20 69 6e  ion is always in
48e0: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 69 6e  cluded in the in
48f0: 20 74 68 65 0a 34 74 68 20 70 61 72 61 6d 65 74   the.4th paramet
4900: 65 72 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  er regardless of
4910: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
4920: 74 68 65 0a 3c 61 20 68 72 65 66 3d 22 6c 61 6e  the.<a href="lan
4930: 67 2e 68 74 6d 6c 23 70 72 61 67 6d 61 5f 73 68  g.html#pragma_sh
4940: 6f 77 5f 64 61 74 61 74 79 70 65 73 22 3e 53 48  ow_datatypes">SH
4950: 4f 57 5f 44 41 54 41 54 59 50 45 53 3c 2f 61 3e  OW_DATATYPES</a>
4960: 20 70 72 61 67 6d 61 0a 69 73 20 6f 6e 20 6f 72   pragma.is on or
4970: 20 6f 66 66 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a   off..</p>..<p>.
4980: 45 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  Each invocation 
4990: 6f 66 20 3c 62 3e 73 71 6c 69 74 65 5f 73 74 65  of <b>sqlite_ste
49a0: 70 3c 2f 62 3e 20 72 65 74 75 72 6e 73 20 61 6e  p</b> returns an
49b0: 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
49c0: 61 74 0a 69 6e 64 69 63 61 74 65 73 20 77 68 61  at.indicates wha
49d0: 74 20 68 61 70 70 65 6e 65 64 20 64 75 72 69 6e  t happened durin
49e0: 67 20 74 68 61 74 20 73 74 65 70 2e 20 20 54 68  g that step.  Th
49f0: 69 73 20 63 6f 64 65 20 6d 61 79 20 62 65 0a 53  is code may be.S
4a00: 51 4c 49 54 45 5f 42 55 53 59 2c 20 53 51 4c 49  QLITE_BUSY, SQLI
4a10: 54 45 5f 52 4f 57 2c 20 53 51 4c 49 54 45 5f 44  TE_ROW, SQLITE_D
4a20: 4f 4e 45 2c 20 53 51 4c 49 54 45 5f 45 52 52 4f  ONE, SQLITE_ERRO
4a30: 52 2c 20 6f 72 0a 53 51 4c 49 54 45 5f 4d 49 53  R, or.SQLITE_MIS
4a40: 55 53 45 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49  USE..</p>..<p>.I
4a50: 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61  f the virtual ma
4a60: 63 68 69 6e 65 20 69 73 20 75 6e 61 62 6c 65 20  chine is unable 
4a70: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
4a80: 62 61 73 65 20 66 69 6c 65 20 62 65 63 61 75 73  base file becaus
4a90: 65 0a 69 74 20 69 73 20 6c 6f 63 6b 65 64 20 62  e.it is locked b
4aa0: 79 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  y another thread
4ab0: 20 6f 72 20 70 72 6f 63 65 73 73 2c 20 3c 62 3e   or process, <b>
4ac0: 73 71 6c 69 74 65 5f 73 74 65 70 3c 2f 62 3e 0a  sqlite_step</b>.
4ad0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
4ae0: 54 45 5f 42 55 53 59 2e 20 20 54 68 65 20 63 61  TE_BUSY.  The ca
4af0: 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73  lling function s
4b00: 68 6f 75 6c 64 20 64 6f 20 73 6f 6d 65 20 6f 74  hould do some ot
4b10: 68 65 72 0a 61 63 74 69 76 69 74 79 2c 20 6f 72  her.activity, or
4b20: 20 73 6c 65 65 70 2c 20 66 6f 72 20 61 20 73 68   sleep, for a sh
4b30: 6f 72 74 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ort amount of ti
4b40: 6d 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 6c  me to give the l
4b50: 6f 63 6b 20 61 0a 63 68 61 6e 63 65 20 74 6f 20  ock a.chance to 
4b60: 63 6c 65 61 72 2c 20 74 68 65 6e 20 69 6e 76 6f  clear, then invo
4b70: 6b 65 20 3c 62 3e 73 71 6c 69 74 65 5f 73 74 65  ke <b>sqlite_ste
4b80: 70 3c 2f 62 3e 20 61 67 61 69 6e 2e 20 20 54 68  p</b> again.  Th
4b90: 69 73 20 63 61 6e 0a 62 65 20 72 65 70 65 61 74  is can.be repeat
4ba0: 65 64 20 61 73 20 6d 61 6e 79 20 74 69 6d 65 73  ed as many times
4bb0: 20 61 73 20 64 65 73 69 72 65 64 2e 0a 3c 2f 70   as desired..</p
4bc0: 3e 0a 0a 3c 70 3e 0a 57 68 65 6e 65 76 65 72 20  >..<p>.Whenever 
4bd0: 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 72  another row of r
4be0: 65 73 75 6c 74 20 64 61 74 61 20 69 73 20 61 76  esult data is av
4bf0: 61 69 6c 61 62 6c 65 2c 0a 3c 62 3e 73 71 6c 69  ailable,.<b>sqli
4c00: 74 65 5f 73 74 65 70 3c 2f 62 3e 20 77 69 6c 6c  te_step</b> will
4c10: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 52   return SQLITE_R
4c20: 4f 57 2e 20 20 54 68 65 20 72 6f 77 20 64 61 74  OW.  The row dat
4c30: 61 20 69 73 0a 73 74 6f 72 65 64 20 69 6e 20 61  a is.stored in a
4c40: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
4c50: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 61  ers to strings a
4c60: 6e 64 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  nd the 2nd param
4c70: 65 74 65 72 0a 69 73 20 6d 61 64 65 20 74 6f 20  eter.is made to 
4c80: 70 6f 69 6e 74 20 74 6f 20 74 68 69 73 20 61 72  point to this ar
4c90: 72 61 79 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 57  ray..</p>..<p>.W
4ca0: 68 65 6e 20 61 6c 6c 20 70 72 6f 63 65 73 73 69  hen all processi
4cb0: 6e 67 20 69 73 20 63 6f 6d 70 6c 65 74 65 2c 20  ng is complete, 
4cc0: 3c 62 3e 73 71 6c 69 74 65 5f 73 74 65 70 3c 2f  <b>sqlite_step</
4cd0: 62 3e 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 65  b> will return.e
4ce0: 69 74 68 65 72 20 53 51 4c 49 54 45 5f 44 4f 4e  ither SQLITE_DON
4cf0: 45 20 6f 72 20 53 51 4c 49 54 45 5f 45 52 52 4f  E or SQLITE_ERRO
4d00: 52 2e 20 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20  R.  SQLITE_DONE 
4d10: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
4d20: 68 65 0a 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  he.statement com
4d30: 70 6c 65 74 65 64 20 73 75 63 63 65 73 73 66 75  pleted successfu
4d40: 6c 6c 79 20 61 6e 64 20 53 51 4c 49 54 45 5f 45  lly and SQLITE_E
4d50: 52 52 4f 52 20 69 6e 64 69 63 61 74 65 73 20 74  RROR indicates t
4d60: 68 61 74 20 74 68 65 72 65 0a 77 61 73 20 61 20  hat there.was a 
4d70: 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2e 20  run-time error. 
4d80: 20 28 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66   (The details of
4d90: 20 74 68 65 20 65 72 72 6f 72 20 61 72 65 20 6f   the error are o
4da0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 3c 62 3e  btained from.<b>
4db0: 73 71 6c 69 74 65 5f 66 69 6e 61 6c 69 7a 65 3c  sqlite_finalize<
4dc0: 2f 62 3e 2e 29 20 20 49 74 20 69 73 20 61 20 6d  /b>.)  It is a m
4dd0: 69 73 75 73 65 20 6f 66 20 74 68 65 20 6c 69 62  isuse of the lib
4de0: 72 61 72 79 20 74 6f 20 61 74 74 65 6d 70 74 0a  rary to attempt.
4df0: 74 6f 20 63 61 6c 6c 20 3c 62 3e 73 71 6c 69 74  to call <b>sqlit
4e00: 65 5f 73 74 65 70 3c 2f 62 3e 20 61 67 61 69 6e  e_step</b> again
4e10: 20 61 66 74 65 72 20 69 74 20 68 61 73 20 72 65   after it has re
4e20: 74 75 72 6e 65 64 20 53 51 4c 49 54 45 5f 44 4f  turned SQLITE_DO
4e30: 4e 45 0a 6f 72 20 53 51 4c 49 54 45 5f 45 52 52  NE.or SQLITE_ERR
4e40: 4f 52 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 57 68  OR..</p>..<p>.Wh
4e50: 65 6e 20 3c 62 3e 73 71 6c 69 74 65 5f 73 74 65  en <b>sqlite_ste
4e60: 70 3c 2f 62 3e 20 72 65 74 75 72 6e 73 20 53 51  p</b> returns SQ
4e70: 4c 49 54 45 5f 44 4f 4e 45 20 6f 72 20 53 51 4c  LITE_DONE or SQL
4e80: 49 54 45 5f 45 52 52 4f 52 2c 0a 74 68 65 20 2a  ITE_ERROR,.the *
4e90: 70 4e 20 61 6e 64 20 2a 70 61 7a 43 6f 6c 4e 61  pN and *pazColNa
4ea0: 6d 65 20 76 61 6c 75 65 73 20 61 72 65 20 73 65  me values are se
4eb0: 74 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  t to the number 
4ec0: 6f 66 20 63 6f 6c 75 6d 6e 73 0a 69 6e 20 74 68  of columns.in th
4ed0: 65 20 72 65 73 75 6c 74 20 73 65 74 20 61 6e 64  e result set and
4ee0: 20 74 6f 20 74 68 65 20 6e 61 6d 65 73 20 6f 66   to the names of
4ef0: 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2c 20 6a 75   the columns, ju
4f00: 73 74 20 61 73 20 74 68 65 79 0a 61 72 65 20 66  st as they.are f
4f10: 6f 72 20 61 6e 20 53 51 4c 49 54 45 5f 52 4f 57  or an SQLITE_ROW
4f20: 20 72 65 74 75 72 6e 2e 20 20 54 68 69 73 20 61   return.  This a
4f30: 6c 6c 6f 77 73 20 74 68 65 20 63 61 6c 6c 69 6e  llows the callin
4f40: 67 20 63 6f 64 65 20 74 6f 0a 66 69 6e 64 20 74  g code to.find t
4f50: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 65 73  he number of res
4f60: 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 61 6e 64 20  ult columns and 
4f70: 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73  the column names
4f80: 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 0a 65   and datatypes.e
4f90: 76 65 6e 20 69 66 20 74 68 65 20 72 65 73 75 6c  ven if the resul
4fa0: 74 20 73 65 74 20 69 73 20 65 6d 70 74 79 2e 20  t set is empty. 
4fb0: 20 54 68 65 20 2a 70 61 7a 56 61 6c 75 65 20 70   The *pazValue p
4fc0: 61 72 61 6d 65 74 65 72 20 69 73 20 61 6c 77 61  arameter is alwa
4fd0: 79 73 0a 73 65 74 20 74 6f 20 4e 55 4c 4c 20 77  ys.set to NULL w
4fe0: 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 63  hen the return c
4ff0: 6f 64 65 73 20 69 73 20 53 51 4c 49 54 45 5f 44  odes is SQLITE_D
5000: 4f 4e 45 20 6f 72 20 53 51 4c 49 54 45 5f 45 52  ONE or SQLITE_ER
5010: 52 4f 52 2e 0a 49 66 20 74 68 65 20 53 51 4c 20  ROR..If the SQL 
5020: 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 69  being executed i
5030: 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 68  s a statement th
5040: 61 74 20 64 6f 65 73 20 6e 6f 74 0a 72 65 74 75  at does not.retu
5050: 72 6e 20 61 20 72 65 73 75 6c 74 20 28 73 75 63  rn a result (suc
5060: 68 20 61 73 20 61 6e 20 49 4e 53 45 52 54 20 6f  h as an INSERT o
5070: 72 20 61 6e 20 55 50 44 41 54 45 29 20 74 68 65  r an UPDATE) the
5080: 6e 20 2a 70 4e 20 77 69 6c 6c 0a 62 65 20 73 65  n *pN will.be se
5090: 74 20 74 6f 20 7a 65 72 6f 20 61 6e 64 20 2a 70  t to zero and *p
50a0: 61 7a 43 6f 6c 4e 61 6d 65 20 77 69 6c 6c 20 62  azColName will b
50b0: 65 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 3c  e set to NULL..<
50c0: 2f 70 3e 0a 0a 3c 70 3e 0a 49 66 20 79 6f 75 20  /p>..<p>.If you 
50d0: 61 62 75 73 65 20 74 68 65 20 6c 69 62 72 61 72  abuse the librar
50e0: 79 20 62 79 20 74 72 79 69 6e 67 20 74 6f 20 63  y by trying to c
50f0: 61 6c 6c 20 3c 62 3e 73 71 6c 69 74 65 5f 73 74  all <b>sqlite_st
5100: 65 70 3c 2f 62 3e 0a 69 6e 61 70 70 72 6f 70 72  ep</b>.inappropr
5110: 69 61 74 65 6c 79 20 69 74 20 77 69 6c 6c 20 61  iately it will a
5120: 74 74 65 6d 70 74 20 72 65 74 75 72 6e 20 53 51  ttempt return SQ
5130: 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 54 68 69  LITE_MISUSE..Thi
5140: 73 20 63 61 6e 20 68 61 70 70 65 6e 20 69 66 20  s can happen if 
5150: 79 6f 75 20 63 61 6c 6c 20 73 71 6c 69 74 65 5f  you call sqlite_
5160: 73 74 65 70 28 29 20 6f 6e 20 74 68 65 20 73 61  step() on the sa
5170: 6d 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69  me virtual machi
5180: 6e 65 0a 61 74 20 74 68 65 20 73 61 6d 65 0a 74  ne.at the same.t
5190: 69 6d 65 20 66 72 6f 6d 20 74 77 6f 20 6f 72 20  ime from two or 
51a0: 6d 6f 72 65 20 74 68 72 65 61 64 73 20 6f 72 20  more threads or 
51b0: 69 66 20 79 6f 75 20 63 61 6c 6c 20 73 71 6c 69  if you call sqli
51c0: 74 65 5f 73 74 65 70 28 29 0a 61 67 61 69 6e 20  te_step().again 
51d0: 61 66 74 65 72 20 69 74 20 72 65 74 75 72 6e 65  after it returne
51e0: 64 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 6f 72  d SQLITE_DONE or
51f0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 6f 72   SQLITE_ERROR or
5200: 20 69 66 20 79 6f 75 0a 70 61 73 73 20 69 6e 20   if you.pass in 
5210: 61 6e 20 69 6e 76 61 6c 69 64 20 76 69 72 74 75  an invalid virtu
5220: 61 6c 20 6d 61 63 68 69 6e 65 20 70 6f 69 6e 74  al machine point
5230: 65 72 20 74 6f 20 73 71 6c 69 74 65 5f 73 74 65  er to sqlite_ste
5240: 70 28 29 2e 0a 59 6f 75 20 73 68 6f 75 6c 64 20  p()..You should 
5250: 6e 6f 74 20 64 65 70 65 6e 64 20 6f 6e 20 74 68  not depend on th
5260: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
5270: 72 65 74 75 72 6e 20 63 6f 64 65 20 74 6f 20 69  return code to i
5280: 6e 64 69 63 61 74 65 0a 61 6e 20 65 72 72 6f 72  ndicate.an error
5290: 2e 20 20 49 74 20 69 73 20 70 6f 73 73 69 62 6c  .  It is possibl
52a0: 65 20 74 68 61 74 20 61 20 6d 69 73 75 73 65 20  e that a misuse 
52b0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
52c0: 20 77 69 6c 6c 20 67 6f 0a 75 6e 64 65 74 65 63   will go.undetec
52d0: 74 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 69  ted and result i
52e0: 6e 20 61 20 70 72 6f 67 72 61 6d 20 63 72 61 73  n a program cras
52f0: 68 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4d  h.  The SQLITE_M
5300: 49 53 55 53 45 20 69 73 0a 69 6e 74 65 6e 64 65  ISUSE is.intende
5310: 64 20 61 73 20 61 20 64 65 62 75 67 67 69 6e 67  d as a debugging
5320: 20 61 69 64 20 6f 6e 6c 79 20 2d 20 74 6f 20 68   aid only - to h
5330: 65 6c 70 20 79 6f 75 20 64 65 74 65 63 74 20 69  elp you detect i
5340: 6e 63 6f 72 72 65 63 74 0a 75 73 61 67 65 20 70  ncorrect.usage p
5350: 72 69 6f 72 20 74 6f 20 61 20 6d 69 73 68 61 70  rior to a mishap
5360: 2e 20 20 54 68 65 20 6d 69 73 75 73 65 20 64 65  .  The misuse de
5370: 74 65 63 74 69 6f 6e 20 6c 6f 67 69 63 20 69 73  tection logic is
5380: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 0a   not guaranteed.
5390: 74 6f 20 77 6f 72 6b 20 69 6e 20 65 76 65 72 79  to work in every
53a0: 20 63 61 73 65 2e 0a 3c 2f 70 3e 0a 0a 3c 68 33   case..</p>..<h3
53b0: 3e 32 2e 33 20 44 65 6c 65 74 69 6e 67 20 41 20  >2.3 Deleting A 
53c0: 56 69 72 74 75 61 6c 20 4d 61 63 68 69 6e 65 3c  Virtual Machine<
53d0: 2f 68 33 3e 0a 0a 3c 70 3e 0a 45 76 65 72 79 20  /h3>..<p>.Every 
53e0: 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
53f0: 74 68 61 74 20 3c 62 3e 73 71 6c 69 74 65 5f 63  that <b>sqlite_c
5400: 6f 6d 70 69 6c 65 3c 2f 62 3e 20 63 72 65 61 74  ompile</b> creat
5410: 65 73 20 73 68 6f 75 6c 64 0a 65 76 65 6e 74 75  es should.eventu
5420: 61 6c 6c 79 20 62 65 20 68 61 6e 64 65 64 20 74  ally be handed t
5430: 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 66 69 6e 61  o <b>sqlite_fina
5440: 6c 69 7a 65 3c 2f 62 3e 2e 20 20 54 68 65 20 73  lize</b>.  The s
5450: 71 6c 69 74 65 5f 66 69 6e 61 6c 69 7a 65 28 29  qlite_finalize()
5460: 0a 70 72 6f 63 65 64 75 72 65 20 64 65 61 6c 6c  .procedure deall
5470: 6f 63 61 74 65 73 20 74 68 65 20 6d 65 6d 6f 72  ocates the memor
5480: 79 20 61 6e 64 20 6f 74 68 65 72 20 72 65 73 6f  y and other reso
5490: 75 72 63 65 73 20 74 68 61 74 20 74 68 65 20 76  urces that the v
54a0: 69 72 74 75 61 6c 0a 6d 61 63 68 69 6e 65 20 75  irtual.machine u
54b0: 73 65 73 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  ses.  Failure to
54c0: 20 63 61 6c 6c 20 73 71 6c 69 74 65 5f 66 69 6e   call sqlite_fin
54d0: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 72 65 73  alize() will res
54e0: 75 6c 74 20 69 6e 20 0a 72 65 73 6f 75 72 63 65  ult in .resource
54f0: 20 6c 65 61 6b 73 20 69 6e 20 79 6f 75 72 20 70   leaks in your p
5500: 72 6f 67 72 61 6d 2e 0a 3c 2f 70 3e 0a 0a 3c 70  rogram..</p>..<p
5510: 3e 0a 54 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f  >.The <b>sqlite_
5520: 66 69 6e 61 6c 69 7a 65 3c 2f 62 3e 20 72 6f 75  finalize</b> rou
5530: 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
5540: 73 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 64  s the result cod
5550: 65 0a 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  e.that indicates
5560: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
5570: 75 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20 6f  ure of the SQL o
5580: 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 74 68  peration that th
5590: 65 0a 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  e.virtual machin
55a0: 65 20 63 61 72 72 69 65 64 20 6f 75 74 2e 0a 54  e carried out..T
55b0: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
55c0: 64 20 62 79 20 73 71 6c 69 74 65 5f 66 69 6e 61  d by sqlite_fina
55d0: 6c 69 7a 65 28 29 20 77 69 6c 6c 20 62 65 20 74  lize() will be t
55e0: 68 65 20 73 61 6d 65 20 61 73 20 77 6f 75 6c 64  he same as would
55f0: 0a 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 72  .have been retur
5600: 6e 65 64 20 68 61 64 20 74 68 65 20 73 61 6d 65  ned had the same
5610: 20 53 51 4c 20 62 65 65 6e 20 65 78 65 63 75 74   SQL been execut
5620: 65 64 20 62 79 20 3c 62 3e 73 71 6c 69 74 65 5f  ed by <b>sqlite_
5630: 65 78 65 63 3c 2f 62 3e 2e 0a 54 68 65 20 65 72  exec</b>..The er
5640: 72 6f 72 20 6d 65 73 73 61 67 65 20 72 65 74 75  ror message retu
5650: 72 6e 65 64 20 77 69 6c 6c 20 61 6c 73 6f 20 62  rned will also b
5660: 65 20 74 68 65 20 73 61 6d 65 2e 0a 3c 2f 70 3e  e the same..</p>
5670: 0a 0a 3c 70 3e 0a 49 74 20 69 73 20 61 63 63 65  ..<p>.It is acce
5680: 70 74 61 62 6c 65 20 74 6f 20 63 61 6c 6c 20 3c  ptable to call <
5690: 62 3e 73 71 6c 69 74 65 5f 66 69 6e 61 6c 69 7a  b>sqlite_finaliz
56a0: 65 3c 2f 62 3e 20 6f 6e 20 61 20 76 69 72 74 75  e</b> on a virtu
56b0: 61 6c 20 6d 61 63 68 69 6e 65 0a 62 65 66 6f 72  al machine.befor
56c0: 65 20 3c 62 3e 73 71 6c 69 74 65 5f 73 74 65 70  e <b>sqlite_step
56d0: 3c 2f 62 3e 20 68 61 73 20 72 65 74 75 72 6e 65  </b> has returne
56e0: 64 20 53 51 4c 49 54 45 5f 44 4f 4e 45 2e 20 20  d SQLITE_DONE.  
56f0: 44 6f 69 6e 67 20 73 6f 20 68 61 73 0a 74 68 65  Doing so has.the
5700: 20 65 66 66 65 63 74 20 6f 66 20 69 6e 74 65 72   effect of inter
5710: 72 75 70 74 69 6e 67 20 74 68 65 20 6f 70 65 72  rupting the oper
5720: 61 74 69 6f 6e 20 69 6e 20 70 72 6f 67 72 65 73  ation in progres
5730: 73 2e 20 20 50 61 72 74 69 61 6c 6c 79 20 63 6f  s.  Partially co
5740: 6d 70 6c 65 74 65 64 0a 63 68 61 6e 67 65 73 20  mpleted.changes 
5750: 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
5760: 61 63 6b 20 61 6e 64 20 74 68 65 20 64 61 74 61  ack and the data
5770: 62 61 73 65 20 77 69 6c 6c 20 62 65 20 72 65 73  base will be res
5780: 74 6f 72 65 64 20 74 6f 20 69 74 73 0a 6f 72 69  tored to its.ori
5790: 67 69 6e 61 6c 20 73 74 61 74 65 20 28 75 6e 6c  ginal state (unl
57a0: 65 73 73 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ess an alternati
57b0: 76 65 20 72 65 63 6f 76 65 72 79 20 61 6c 67 6f  ve recovery algo
57c0: 72 69 74 68 6d 20 69 73 20 73 65 6c 65 63 74 65  rithm is selecte
57d0: 64 20 75 73 69 6e 67 0a 61 6e 20 4f 4e 20 43 4f  d using.an ON CO
57e0: 4e 46 4c 49 43 54 20 63 6c 61 75 73 65 20 69 6e  NFLICT clause in
57f0: 20 74 68 65 20 53 51 4c 20 62 65 69 6e 67 20 65   the SQL being e
5800: 78 65 63 75 74 65 64 2e 29 20 20 54 68 65 20 65  xecuted.)  The e
5810: 66 66 65 63 74 20 69 73 20 74 68 65 0a 73 61 6d  ffect is the.sam
5820: 65 20 61 73 20 69 66 20 61 20 63 61 6c 6c 62 61  e as if a callba
5830: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 3c  ck function of <
5840: 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62  b>sqlite_exec</b
5850: 3e 20 68 61 64 20 72 65 74 75 72 6e 65 64 0a 6e  > had returned.n
5860: 6f 6e 2d 7a 65 72 6f 2e 0a 3c 2f 70 3e 0a 0a 3c  on-zero..</p>..<
5870: 70 3e 0a 49 74 20 69 73 20 61 6c 73 6f 20 61 63  p>.It is also ac
5880: 63 65 70 74 61 62 6c 65 20 74 6f 20 63 61 6c 6c  ceptable to call
5890: 20 3c 62 3e 73 71 6c 69 74 65 5f 66 69 6e 61 6c   <b>sqlite_final
58a0: 69 7a 65 3c 2f 62 3e 20 6f 6e 20 61 20 76 69 72  ize</b> on a vir
58b0: 74 75 61 6c 20 6d 61 63 68 69 6e 65 0a 74 68 61  tual machine.tha
58c0: 74 20 68 61 73 20 6e 65 76 65 72 20 62 65 65 6e  t has never been
58d0: 20 70 61 73 73 65 64 20 74 6f 20 3c 62 3e 73 71   passed to <b>sq
58e0: 6c 69 74 65 5f 73 74 65 70 3c 2f 62 3e 20 65 76  lite_step</b> ev
58f0: 65 6e 20 6f 6e 63 65 2e 0a 3c 2f 70 3e 0a 0a 3c  en once..</p>..<
5900: 68 32 3e 33 2e 30 20 54 68 65 20 45 78 74 65 6e  h2>3.0 The Exten
5910: 64 65 64 20 41 50 49 3c 2f 68 32 3e 0a 0a 3c 70  ded API</h2>..<p
5920: 3e 4f 6e 6c 79 20 74 68 65 20 74 68 72 65 65 20  >Only the three 
5930: 63 6f 72 65 20 72 6f 75 74 69 6e 65 73 20 64 65  core routines de
5940: 73 63 72 69 62 65 64 20 69 6e 20 73 65 63 74 69  scribed in secti
5950: 6f 6e 20 31 2e 30 20 61 72 65 20 72 65 71 75 69  on 1.0 are requi
5960: 72 65 64 20 74 6f 20 75 73 65 0a 53 51 4c 69 74  red to use.SQLit
5970: 65 2e 20 20 42 75 74 20 74 68 65 72 65 20 61 72  e.  But there ar
5980: 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 66 75 6e  e many other fun
5990: 63 74 69 6f 6e 73 20 74 68 61 74 20 70 72 6f 76  ctions that prov
59a0: 69 64 65 20 0a 75 73 65 66 75 6c 20 69 6e 74 65  ide .useful inte
59b0: 72 66 61 63 65 73 2e 20 20 54 68 65 73 65 20 65  rfaces.  These e
59c0: 78 74 65 6e 64 65 64 20 72 6f 75 74 69 6e 65 73  xtended routines
59d0: 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a   are as follows:
59e0: 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  .</p>..<blockquo
59f0: 74 65 3e 3c 70 72 65 3e 0a 69 6e 74 20 73 71 6c  te><pre>.int sql
5a00: 69 74 65 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ite_last_insert_
5a10: 72 6f 77 69 64 28 73 71 6c 69 74 65 2a 29 3b 0a  rowid(sqlite*);.
5a20: 0a 69 6e 74 20 73 71 6c 69 74 65 5f 63 68 61 6e  .int sqlite_chan
5a30: 67 65 73 28 73 71 6c 69 74 65 2a 29 3b 0a 0a 69  ges(sqlite*);..i
5a40: 6e 74 20 73 71 6c 69 74 65 5f 67 65 74 5f 74 61  nt sqlite_get_ta
5a50: 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 2a 2c 0a  ble(.  sqlite*,.
5a60: 20 20 63 68 61 72 20 2a 73 71 6c 2c 0a 20 20 63    char *sql,.  c
5a70: 68 61 72 20 2a 2a 2a 72 65 73 75 6c 74 2c 0a 20  har ***result,. 
5a80: 20 69 6e 74 20 2a 6e 72 6f 77 2c 0a 20 20 69 6e   int *nrow,.  in
5a90: 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 0a 20 20 63 68  t *ncolumn,.  ch
5aa0: 61 72 20 2a 2a 65 72 72 6d 73 67 0a 29 3b 0a 0a  ar **errmsg.);..
5ab0: 76 6f 69 64 20 73 71 6c 69 74 65 5f 66 72 65 65  void sqlite_free
5ac0: 5f 74 61 62 6c 65 28 63 68 61 72 2a 2a 29 3b 0a  _table(char**);.
5ad0: 0a 76 6f 69 64 20 73 71 6c 69 74 65 5f 69 6e 74  .void sqlite_int
5ae0: 65 72 72 75 70 74 28 73 71 6c 69 74 65 2a 29 3b  errupt(sqlite*);
5af0: 0a 0a 69 6e 74 20 73 71 6c 69 74 65 5f 63 6f 6d  ..int sqlite_com
5b00: 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
5b10: 20 2a 73 71 6c 29 3b 0a 0a 76 6f 69 64 20 73 71   *sql);..void sq
5b20: 6c 69 74 65 5f 62 75 73 79 5f 68 61 6e 64 6c 65  lite_busy_handle
5b30: 72 28 73 71 6c 69 74 65 2a 2c 20 69 6e 74 20 28  r(sqlite*, int (
5b40: 2a 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  *)(void*,const c
5b50: 68 61 72 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a  har*,int), void*
5b60: 29 3b 0a 0a 76 6f 69 64 20 73 71 6c 69 74 65 5f  );..void sqlite_
5b70: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
5b80: 69 74 65 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  ite*, int ms);..
5b90: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
5ba0: 65 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 0a 63 6f  e_version[];..co
5bb0: 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 5f  nst char sqlite_
5bc0: 65 6e 63 6f 64 69 6e 67 5b 5d 3b 0a 0a 69 6e 74  encoding[];..int
5bd0: 20 73 71 6c 69 74 65 5f 65 78 65 63 5f 70 72 69   sqlite_exec_pri
5be0: 6e 74 66 28 0a 20 20 73 71 6c 69 74 65 2a 2c 0a  ntf(.  sqlite*,.
5bf0: 20 20 63 68 61 72 20 2a 73 71 6c 2c 0a 20 20 69    char *sql,.  i
5c00: 6e 74 20 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  nt (*)(void*,int
5c10: 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c  ,char**,char**),
5c20: 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 63 68 61 72  .  void*,.  char
5c30: 20 2a 2a 65 72 72 6d 73 67 2c 0a 20 20 2e 2e 2e   **errmsg,.  ...
5c40: 0a 29 3b 0a 0a 69 6e 74 20 73 71 6c 69 74 65 5f  .);..int sqlite_
5c50: 65 78 65 63 5f 76 70 72 69 6e 74 66 28 0a 20 20  exec_vprintf(.  
5c60: 73 71 6c 69 74 65 2a 2c 0a 20 20 63 68 61 72 20  sqlite*,.  char 
5c70: 2a 73 71 6c 2c 0a 20 20 69 6e 74 20 28 2a 29 28  *sql,.  int (*)(
5c80: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
5c90: 2c 63 68 61 72 2a 2a 29 2c 0a 20 20 76 6f 69 64  ,char**),.  void
5ca0: 2a 2c 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  *,.  char **errm
5cb0: 73 67 2c 0a 20 20 76 61 5f 6c 69 73 74 0a 29 3b  sg,.  va_list.);
5cc0: 0a 0a 69 6e 74 20 73 71 6c 69 74 65 5f 67 65 74  ..int sqlite_get
5cd0: 5f 74 61 62 6c 65 5f 70 72 69 6e 74 66 28 0a 20  _table_printf(. 
5ce0: 20 73 71 6c 69 74 65 2a 2c 0a 20 20 63 68 61 72   sqlite*,.  char
5cf0: 20 2a 73 71 6c 2c 0a 20 20 63 68 61 72 20 2a 2a   *sql,.  char **
5d00: 2a 72 65 73 75 6c 74 2c 0a 20 20 69 6e 74 20 2a  *result,.  int *
5d10: 6e 72 6f 77 2c 0a 20 20 69 6e 74 20 2a 6e 63 6f  nrow,.  int *nco
5d20: 6c 75 6d 6e 2c 0a 20 20 63 68 61 72 20 2a 2a 65  lumn,.  char **e
5d30: 72 72 6d 73 67 2c 0a 20 20 2e 2e 2e 0a 29 3b 0a  rrmsg,.  ....);.
5d40: 0a 69 6e 74 20 73 71 6c 69 74 65 5f 67 65 74 5f  .int sqlite_get_
5d50: 74 61 62 6c 65 5f 76 70 72 69 6e 74 66 28 0a 20  table_vprintf(. 
5d60: 20 73 71 6c 69 74 65 2a 2c 0a 20 20 63 68 61 72   sqlite*,.  char
5d70: 20 2a 73 71 6c 2c 0a 20 20 63 68 61 72 20 2a 2a   *sql,.  char **
5d80: 2a 72 65 73 75 6c 74 2c 0a 20 20 69 6e 74 20 2a  *result,.  int *
5d90: 6e 72 6f 77 2c 0a 20 20 69 6e 74 20 2a 6e 63 6f  nrow,.  int *nco
5da0: 6c 75 6d 6e 2c 0a 20 20 63 68 61 72 20 2a 2a 65  lumn,.  char **e
5db0: 72 72 6d 73 67 2c 0a 20 20 76 61 5f 6c 69 73 74  rrmsg,.  va_list
5dc0: 0a 29 3b 0a 0a 63 68 61 72 20 2a 73 71 6c 69 74  .);..char *sqlit
5dd0: 65 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  e_mprintf(const 
5de0: 63 68 61 72 20 2a 7a 46 6f 72 6d 61 74 2c 20 2e  char *zFormat, .
5df0: 2e 2e 29 3b 0a 0a 63 68 61 72 20 2a 73 71 6c 69  ..);..char *sqli
5e00: 74 65 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te_vmprintf(cons
5e10: 74 20 63 68 61 72 20 2a 7a 46 6f 72 6d 61 74 2c  t char *zFormat,
5e20: 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 76 6f 69 64   va_list);..void
5e30: 20 73 71 6c 69 74 65 5f 66 72 65 65 6d 65 6d 28   sqlite_freemem(
5e40: 63 68 61 72 2a 29 3b 0a 0a 76 6f 69 64 20 73 71  char*);..void sq
5e50: 6c 69 74 65 5f 70 72 6f 67 72 65 73 73 5f 68 61  lite_progress_ha
5e60: 6e 64 6c 65 72 28 73 71 6c 69 74 65 2a 2c 20 69  ndler(sqlite*, i
5e70: 6e 74 2c 20 69 6e 74 20 28 2a 29 28 76 6f 69 64  nt, int (*)(void
5e80: 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 3c 2f 70  *), void*);..</p
5e90: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
5ea0: 0a 0a 3c 70 3e 41 6c 6c 20 6f 66 20 74 68 65 20  ..<p>All of the 
5eb0: 61 62 6f 76 65 20 64 65 66 69 6e 69 74 69 6f 6e  above definition
5ec0: 73 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69  s are included i
5ed0: 6e 20 74 68 65 20 22 73 71 6c 69 74 65 2e 68 22  n the "sqlite.h"
5ee0: 0a 68 65 61 64 65 72 20 66 69 6c 65 20 74 68 61  .header file tha
5ef0: 74 20 63 6f 6d 65 73 20 69 6e 20 74 68 65 20 73  t comes in the s
5f00: 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 70 3e 0a  ource tree.</p>.
5f10: 0a 3c 68 33 3e 33 2e 31 20 54 68 65 20 52 4f 57  .<h3>3.1 The ROW
5f20: 49 44 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  ID of the most r
5f30: 65 63 65 6e 74 20 69 6e 73 65 72 74 3c 2f 68 33  ecent insert</h3
5f40: 3e 0a 0a 3c 70 3e 45 76 65 72 79 20 72 6f 77 20  >..<p>Every row 
5f50: 6f 66 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  of an SQLite tab
5f60: 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
5f70: 69 6e 74 65 67 65 72 20 6b 65 79 2e 20 20 49 66  integer key.  If
5f80: 20 74 68 65 0a 74 61 62 6c 65 20 68 61 73 20 61   the.table has a
5f90: 20 63 6f 6c 75 6d 6e 20 6c 61 62 65 6c 65 64 20   column labeled 
5fa0: 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
5fb0: 4b 45 59 2c 20 74 68 65 6e 20 74 68 61 74 20 63  KEY, then that c
5fc0: 6f 6c 75 6d 6e 0a 73 65 72 76 65 73 20 61 73 20  olumn.serves as 
5fd0: 74 68 65 20 6b 65 79 2e 20 20 49 66 20 74 68 65  the key.  If the
5fe0: 72 65 20 69 73 20 6e 6f 20 49 4e 54 45 47 45 52  re is no INTEGER
5ff0: 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c   PRIMARY KEY col
6000: 75 6d 6e 20 74 68 65 6e 0a 74 68 65 20 6b 65 79  umn then.the key
6010: 20 69 73 20 61 20 75 6e 69 71 75 65 20 69 6e 74   is a unique int
6020: 65 67 65 72 2e 20 20 54 68 65 20 6b 65 79 20 66  eger.  The key f
6030: 6f 72 20 61 20 72 6f 77 20 63 61 6e 20 62 65 20  or a row can be 
6040: 61 63 63 65 73 73 65 64 20 69 6e 0a 61 20 53 45  accessed in.a SE
6050: 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 6f  LECT statement o
6060: 72 20 75 73 65 64 20 69 6e 20 61 20 57 48 45 52  r used in a WHER
6070: 45 20 6f 72 20 4f 52 44 45 52 20 42 59 20 63 6c  E or ORDER BY cl
6080: 61 75 73 65 20 75 73 69 6e 67 20 61 6e 79 0a 6f  ause using any.o
6090: 66 20 74 68 65 20 6e 61 6d 65 73 20 22 52 4f 57  f the names "ROW
60a0: 49 44 22 2c 20 22 4f 49 44 22 2c 20 6f 72 20 22  ID", "OID", or "
60b0: 5f 52 4f 57 49 44 5f 22 2e 3c 2f 70 3e 0a 0a 3c  _ROWID_".</p>..<
60c0: 70 3e 57 68 65 6e 20 79 6f 75 20 64 6f 20 61 6e  p>When you do an
60d0: 20 69 6e 73 65 72 74 20 69 6e 74 6f 20 61 20 74   insert into a t
60e0: 61 62 6c 65 20 74 68 61 74 20 64 6f 65 73 20 6e  able that does n
60f0: 6f 74 20 68 61 76 65 20 61 6e 20 49 4e 54 45 47  ot have an INTEG
6100: 45 52 20 50 52 49 4d 41 52 59 0a 4b 45 59 20 63  ER PRIMARY.KEY c
6110: 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 74 68 65  olumn, or if the
6120: 20 74 61 62 6c 65 20 64 6f 65 73 20 68 61 76 65   table does have
6130: 20 61 6e 20 49 4e 54 45 47 45 52 20 50 52 49 4d   an INTEGER PRIM
6140: 41 52 59 20 4b 45 59 20 62 75 74 20 74 68 65 20  ARY KEY but the 
6150: 76 61 6c 75 65 0a 66 6f 72 20 74 68 61 74 20 63  value.for that c
6160: 6f 6c 75 6d 6e 20 69 73 20 6e 6f 74 20 73 70 65  olumn is not spe
6170: 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 56 41  cified in the VA
6180: 4c 55 45 53 20 63 6c 61 75 73 65 20 6f 66 20 74  LUES clause of t
6190: 68 65 20 69 6e 73 65 72 74 2c 20 74 68 65 6e 0a  he insert, then.
61a0: 74 68 65 20 6b 65 79 20 69 73 20 61 75 74 6f 6d  the key is autom
61b0: 61 74 69 63 61 6c 6c 79 20 67 65 6e 65 72 61 74  atically generat
61c0: 65 64 2e 20 20 59 6f 75 20 63 61 6e 20 66 69 6e  ed.  You can fin
61d0: 64 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  d the value of t
61e0: 68 65 20 6b 65 79 0a 66 6f 72 20 74 68 65 20 6d  he key.for the m
61f0: 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
6200: 54 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  T statement usin
6210: 67 20 74 68 65 0a 3c 62 3e 73 71 6c 69 74 65 5f  g the.<b>sqlite_
6220: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
6230: 64 3c 2f 62 3e 20 41 50 49 20 66 75 6e 63 74 69  d</b> API functi
6240: 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 68 33 3e 33 2e 32  on.</p>..<h3>3.2
6250: 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   The number of r
6260: 6f 77 73 20 74 68 61 74 20 63 68 61 6e 67 65 64  ows that changed
6270: 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 68 65 20 3c 62  </h3>..<p>The <b
6280: 3e 73 71 6c 69 74 65 5f 63 68 61 6e 67 65 73 3c  >sqlite_changes<
6290: 2f 62 3e 20 41 50 49 20 66 75 6e 63 74 69 6f 6e  /b> API function
62a0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
62b0: 62 65 72 20 6f 66 20 72 6f 77 73 0a 74 68 61 74  ber of rows.that
62c0: 20 68 61 76 65 20 62 65 65 6e 20 69 6e 73 65 72   have been inser
62d0: 74 65 64 2c 20 64 65 6c 65 74 65 64 2c 20 6f 72  ted, deleted, or
62e0: 20 6d 6f 64 69 66 69 65 64 20 73 69 6e 63 65 20   modified since 
62f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 77 61 73  the database was
6300: 0a 6c 61 73 74 20 71 75 69 65 73 63 65 6e 74 2e  .last quiescent.
6310: 20 20 41 20 22 71 75 69 65 73 63 65 6e 74 22 20    A "quiescent" 
6320: 64 61 74 61 62 61 73 65 20 69 73 20 6f 6e 65 20  database is one 
6330: 69 6e 20 77 68 69 63 68 20 74 68 65 72 65 20 61  in which there a
6340: 72 65 0a 6e 6f 20 6f 75 74 73 74 61 6e 64 69 6e  re.no outstandin
6350: 67 20 63 61 6c 6c 73 20 74 6f 20 3c 62 3e 73 71  g calls to <b>sq
6360: 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e 20 61 6e  lite_exec</b> an
6370: 64 20 6e 6f 20 56 4d 73 20 63 72 65 61 74 65 64  d no VMs created
6380: 20 62 79 0a 3c 62 3e 73 71 6c 69 74 65 5f 63 6f   by.<b>sqlite_co
6390: 6d 70 69 6c 65 3c 2f 62 3e 20 74 68 61 74 20 68  mpile</b> that h
63a0: 61 76 65 20 6e 6f 74 20 62 65 65 6e 20 66 69 6e  ave not been fin
63b0: 61 6c 69 7a 65 64 20 62 79 20 3c 62 3e 73 71 6c  alized by <b>sql
63c0: 69 74 65 5f 66 69 6e 61 6c 69 7a 65 3c 2f 62 3e  ite_finalize</b>
63d0: 2e 0a 49 6e 20 63 6f 6d 6d 6f 6e 20 75 73 61 67  ..In common usag
63e0: 65 2c 20 3c 62 3e 73 71 6c 69 74 65 5f 63 68 61  e, <b>sqlite_cha
63f0: 6e 67 65 73 3c 2f 62 3e 20 72 65 74 75 72 6e 73  nges</b> returns
6400: 20 74 68 65 20 6e 75 6d 62 65 72 0a 6f 66 20 72   the number.of r
6410: 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 64 65  ows inserted, de
6420: 6c 65 74 65 64 2c 20 6f 72 20 6d 6f 64 69 66 69  leted, or modifi
6430: 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
6440: 65 63 65 6e 74 20 3c 62 3e 73 71 6c 69 74 65 5f  ecent <b>sqlite_
6450: 65 78 65 63 3c 2f 62 3e 0a 63 61 6c 6c 20 6f 72  exec</b>.call or
6460: 20 73 69 6e 63 65 20 74 68 65 20 6d 6f 73 74 20   since the most 
6470: 72 65 63 65 6e 74 20 3c 62 3e 73 71 6c 69 74 65  recent <b>sqlite
6480: 5f 63 6f 6d 70 69 6c 65 3c 2f 62 3e 2e 20 20 42  _compile</b>.  B
6490: 75 74 20 69 66 20 79 6f 75 20 68 61 76 65 0a 6e  ut if you have.n
64a0: 65 73 74 65 64 20 63 61 6c 6c 73 20 74 6f 20 3c  ested calls to <
64b0: 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62  b>sqlite_exec</b
64c0: 3e 20 28 74 68 61 74 20 69 73 2c 20 69 66 20 74  > (that is, if t
64d0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  he callback rout
64e0: 69 6e 65 0a 6f 66 20 6f 6e 65 20 3c 62 3e 73 71  ine.of one <b>sq
64f0: 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e 20 69 6e  lite_exec</b> in
6500: 76 6f 6b 65 73 20 61 6e 6f 74 68 65 72 20 3c 62  vokes another <b
6510: 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e  >sqlite_exec</b>
6520: 29 20 6f 72 20 69 66 0a 79 6f 75 20 69 6e 76 6f  ) or if.you invo
6530: 6b 65 20 3c 62 3e 73 71 6c 69 74 65 5f 63 6f 6d  ke <b>sqlite_com
6540: 70 69 6c 65 3c 2f 62 3e 20 74 6f 20 63 72 65 61  pile</b> to crea
6550: 74 65 20 61 20 6e 65 77 20 56 4d 20 77 68 69 6c  te a new VM whil
6560: 65 20 74 68 65 72 65 20 69 73 0a 73 74 69 6c 6c  e there is.still
6570: 20 61 6e 6f 74 68 65 72 20 56 4d 20 69 6e 20 65   another VM in e
6580: 78 69 73 74 61 6e 63 65 2c 20 74 68 65 6e 0a 74  xistance, then.t
6590: 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 74 68  he meaning of th
65a0: 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
65b0: 64 20 62 79 20 3c 62 3e 73 71 6c 69 74 65 5f 63  d by <b>sqlite_c
65c0: 68 61 6e 67 65 73 3c 2f 62 3e 20 69 73 20 6d 6f  hanges</b> is mo
65d0: 72 65 0a 63 6f 6d 70 6c 65 78 2e 0a 54 68 65 20  re.complex..The 
65e0: 6e 75 6d 62 65 72 20 72 65 70 6f 72 74 65 64 20  number reported 
65f0: 69 6e 63 6c 75 64 65 73 20 61 6e 79 20 63 68 61  includes any cha
6600: 6e 67 65 73 0a 74 68 61 74 20 77 65 72 65 20 6c  nges.that were l
6610: 61 74 65 72 20 75 6e 64 6f 6e 65 20 62 79 20 61  ater undone by a
6620: 20 52 4f 4c 4c 42 41 43 4b 20 6f 72 20 41 42 4f   ROLLBACK or ABO
6630: 52 54 2e 20 20 42 75 74 20 72 6f 77 73 20 74 68  RT.  But rows th
6640: 61 74 20 61 72 65 0a 64 65 6c 65 74 65 64 20 62  at are.deleted b
6650: 65 63 61 75 73 65 20 6f 66 20 61 20 44 52 4f 50  ecause of a DROP
6660: 20 54 41 42 4c 45 20 61 72 65 20 3c 65 6d 3e 6e   TABLE are <em>n
6670: 6f 74 3c 2f 65 6d 3e 20 63 6f 75 6e 74 65 64 2e  ot</em> counted.
6680: 3c 2f 70 3e 0a 0a 3c 70 3e 53 51 4c 69 74 65 20  </p>..<p>SQLite 
6690: 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63  implements the c
66a0: 6f 6d 6d 61 6e 64 20 22 3c 62 3e 44 45 4c 45 54  ommand "<b>DELET
66b0: 45 20 46 52 4f 4d 20 74 61 62 6c 65 3c 2f 62 3e  E FROM table</b>
66c0: 22 20 28 77 69 74 68 6f 75 74 0a 61 20 57 48 45  " (without.a WHE
66d0: 52 45 20 63 6c 61 75 73 65 29 20 62 79 20 64 72  RE clause) by dr
66e0: 6f 70 70 69 6e 67 20 74 68 65 20 74 61 62 6c 65  opping the table
66f0: 20 74 68 65 6e 20 72 65 63 72 65 61 74 69 6e 67   then recreating
6700: 20 69 74 2e 20 20 0a 54 68 69 73 20 69 73 20 6d   it.  .This is m
6710: 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20  uch faster than 
6720: 64 65 6c 65 74 69 6e 67 20 74 68 65 20 65 6c 65  deleting the ele
6730: 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 74 61 62  ments of the tab
6740: 6c 65 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  le individually.
6750: 0a 42 75 74 20 69 74 20 61 6c 73 6f 20 6d 65 61  .But it also mea
6760: 6e 73 20 74 68 61 74 20 74 68 65 20 76 61 6c 75  ns that the valu
6770: 65 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  e returned from 
6780: 3c 62 3e 73 71 6c 69 74 65 5f 63 68 61 6e 67 65  <b>sqlite_change
6790: 73 3c 2f 62 3e 0a 77 69 6c 6c 20 62 65 20 7a 65  s</b>.will be ze
67a0: 72 6f 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ro regardless of
67b0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
67c0: 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72  lements that wer
67d0: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 69 6e 20  e originally.in 
67e0: 74 68 65 20 74 61 62 6c 65 2e 20 20 49 66 20 61  the table.  If a
67f0: 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74  n accurate count
6800: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
6810: 66 20 65 6c 65 6d 65 6e 74 73 20 64 65 6c 65 74  f elements delet
6820: 65 64 0a 69 73 20 6e 65 63 65 73 73 61 72 79 2c  ed.is necessary,
6830: 20 75 73 65 20 22 3c 62 3e 44 45 4c 45 54 45 20   use "<b>DELETE 
6840: 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45  FROM table WHERE
6850: 20 31 3c 2f 62 3e 22 20 69 6e 73 74 65 61 64 2e   1</b>" instead.
6860: 3c 2f 70 3e 0a 0a 3c 68 33 3e 33 2e 33 20 51 75  </p>..<h3>3.3 Qu
6870: 65 72 79 69 6e 67 20 69 6e 74 6f 20 6d 65 6d 6f  erying into memo
6880: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
6890: 20 6d 61 6c 6c 6f 63 28 29 3c 2f 68 33 3e 0a 0a   malloc()</h3>..
68a0: 3c 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69 74 65  <p>The <b>sqlite
68b0: 5f 67 65 74 5f 74 61 62 6c 65 3c 2f 62 3e 20 66  _get_table</b> f
68c0: 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 77 72 61  unction is a wra
68d0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 3c 62 3e 73  pper around.<b>s
68e0: 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e 20 74  qlite_exec</b> t
68f0: 68 61 74 20 63 6f 6c 6c 65 63 74 73 20 61 6c 6c  hat collects all
6900: 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e   the information
6910: 20 66 72 6f 6d 20 73 75 63 63 65 73 73 69 76 65   from successive
6920: 0a 63 61 6c 6c 62 61 63 6b 73 20 61 6e 64 20 77  .callbacks and w
6930: 72 69 74 65 73 20 69 74 20 69 6e 74 6f 20 6d 65  rites it into me
6940: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
6950: 6f 6d 20 6d 61 6c 6c 6f 63 28 29 2e 20 20 54 68  om malloc().  Th
6960: 69 73 0a 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  is.is a convenie
6970: 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  nce function tha
6980: 74 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 70 70  t allows the app
6990: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 67 65 74 20  lication to get 
69a0: 74 68 65 0a 65 6e 74 69 72 65 20 72 65 73 75 6c  the.entire resul
69b0: 74 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  t of a database 
69c0: 71 75 65 72 79 20 77 69 74 68 20 61 20 73 69 6e  query with a sin
69d0: 67 6c 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  gle function cal
69e0: 6c 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 6d  l.</p>..<p>The m
69f0: 61 69 6e 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ain result from 
6a00: 3c 62 3e 73 71 6c 69 74 65 5f 67 65 74 5f 74 61  <b>sqlite_get_ta
6a10: 62 6c 65 3c 2f 62 3e 20 69 73 20 61 6e 20 61 72  ble</b> is an ar
6a20: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 0a  ray of pointers.
6a30: 74 6f 20 73 74 72 69 6e 67 73 2e 20 20 54 68 65  to strings.  The
6a40: 72 65 20 69 73 20 6f 6e 65 20 65 6c 65 6d 65 6e  re is one elemen
6a50: 74 20 69 6e 20 74 68 69 73 20 61 72 72 61 79 20  t in this array 
6a60: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20  for each column 
6a70: 6f 66 0a 65 61 63 68 20 72 6f 77 20 69 6e 20 74  of.each row in t
6a80: 68 65 20 72 65 73 75 6c 74 2e 20 20 4e 55 4c 4c  he result.  NULL
6a90: 20 72 65 73 75 6c 74 73 20 61 72 65 20 72 65 70   results are rep
6aa0: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 4e 55  resented by a NU
6ab0: 4c 4c 0a 70 6f 69 6e 74 65 72 2e 20 49 6e 20 61  LL.pointer. In a
6ac0: 64 64 69 74 69 6f 6e 20 74 6f 20 74 68 65 20 72  ddition to the r
6ad0: 65 67 75 6c 61 72 20 64 61 74 61 2c 20 74 68 65  egular data, the
6ae0: 72 65 20 69 73 20 61 6e 20 61 64 64 65 64 20 72  re is an added r
6af0: 6f 77 20 61 74 20 74 68 65 20 0a 62 65 67 69 6e  ow at the .begin
6b00: 6e 69 6e 67 20 6f 66 20 74 68 65 20 61 72 72 61  ning of the arra
6b10: 79 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  y that contains 
6b20: 74 68 65 20 6e 61 6d 65 20 6f 66 20 65 61 63 68  the name of each
6b30: 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 72   column of the.r
6b40: 65 73 75 6c 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e 41  esult.</p>..<p>A
6b50: 73 20 61 6e 20 65 78 61 6d 70 6c 65 2c 20 63 6f  s an example, co
6b60: 6e 73 69 64 65 72 20 74 68 65 20 66 6f 6c 6c 6f  nsider the follo
6b70: 77 69 6e 67 20 71 75 65 72 79 3a 3c 2f 70 3e 0a  wing query:</p>.
6b80: 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 53 45  .<blockquote>.SE
6b90: 4c 45 43 54 20 65 6d 70 6c 6f 79 65 65 5f 6e 61  LECT employee_na
6ba0: 6d 65 2c 20 6c 6f 67 69 6e 2c 20 68 6f 73 74 20  me, login, host 
6bb0: 46 52 4f 4d 20 75 73 65 72 73 20 57 48 45 52 45  FROM users WHERE
6bc0: 20 6c 6f 67 69 63 20 4c 49 4b 45 20 27 64 25 27   logic LIKE 'd%'
6bd0: 3b 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ;.</blockquote>.
6be0: 0a 3c 70 3e 54 68 69 73 20 71 75 65 72 79 20 77  .<p>This query w
6bf0: 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 6e  ill return the n
6c00: 61 6d 65 2c 20 6c 6f 67 69 6e 20 61 6e 64 20 68  ame, login and h
6c10: 6f 73 74 20 63 6f 6d 70 75 74 65 72 20 6e 61 6d  ost computer nam
6c20: 65 0a 66 6f 72 20 65 76 65 72 79 20 65 6d 70 6c  e.for every empl
6c30: 6f 79 65 65 20 77 68 6f 73 65 20 6c 6f 67 69 6e  oyee whose login
6c40: 20 62 65 67 69 6e 73 20 77 69 74 68 20 74 68 65   begins with the
6c50: 20 6c 65 74 74 65 72 20 22 64 22 2e 20 20 49 66   letter "d".  If
6c60: 20 74 68 69 73 0a 71 75 65 72 79 20 69 73 20 73   this.query is s
6c70: 75 62 6d 69 74 74 65 64 20 74 6f 20 3c 62 3e 73  ubmitted to <b>s
6c80: 71 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 3c  qlite_get_table<
6c90: 2f 62 3e 20 74 68 65 20 72 65 73 75 6c 74 20 6d  /b> the result m
6ca0: 69 67 68 74 0a 6c 6f 6f 6b 20 6c 69 6b 65 20 74  ight.look like t
6cb0: 68 69 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b  his:</p>..<block
6cc0: 71 75 6f 74 65 3e 0a 6e 72 6f 77 20 3d 20 32 3c  quote>.nrow = 2<
6cd0: 62 72 3e 0a 6e 63 6f 6c 75 6d 6e 20 3d 20 33 3c  br>.ncolumn = 3<
6ce0: 62 72 3e 0a 72 65 73 75 6c 74 5b 30 5d 20 3d 20  br>.result[0] = 
6cf0: 22 65 6d 70 6c 6f 79 65 65 5f 6e 61 6d 65 22 3c  "employee_name"<
6d00: 62 72 3e 0a 72 65 73 75 6c 74 5b 31 5d 20 3d 20  br>.result[1] = 
6d10: 22 6c 6f 67 69 6e 22 3c 62 72 3e 0a 72 65 73 75  "login"<br>.resu
6d20: 6c 74 5b 32 5d 20 3d 20 22 68 6f 73 74 22 3c 62  lt[2] = "host"<b
6d30: 72 3e 0a 72 65 73 75 6c 74 5b 33 5d 20 3d 20 22  r>.result[3] = "
6d40: 64 75 6d 6d 79 22 3c 62 72 3e 0a 72 65 73 75 6c  dummy"<br>.resul
6d50: 74 5b 34 5d 20 3d 20 22 4e 6f 20 73 75 63 68 20  t[4] = "No such 
6d60: 75 73 65 72 22 3c 62 72 3e 0a 72 65 73 75 6c 74  user"<br>.result
6d70: 5b 35 5d 20 3d 20 30 3c 62 72 3e 0a 72 65 73 75  [5] = 0<br>.resu
6d80: 6c 74 5b 36 5d 20 3d 20 22 44 2e 20 52 69 63 68  lt[6] = "D. Rich
6d90: 61 72 64 20 48 69 70 70 22 3c 62 72 3e 0a 72 65  ard Hipp"<br>.re
6da0: 73 75 6c 74 5b 37 5d 20 3d 20 22 64 72 68 22 3c  sult[7] = "drh"<
6db0: 62 72 3e 0a 72 65 73 75 6c 74 5b 38 5d 20 3d 20  br>.result[8] = 
6dc0: 22 7a 61 64 6f 6b 22 0a 3c 2f 62 6c 6f 63 6b 71  "zadok".</blockq
6dd0: 75 6f 74 65 3e 0a 0a 3c 70 3e 4e 6f 74 69 63 65  uote>..<p>Notice
6de0: 20 74 68 61 74 20 74 68 65 20 22 68 6f 73 74 22   that the "host"
6df0: 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 22   value for the "
6e00: 64 75 6d 6d 79 22 20 72 65 63 6f 72 64 20 69 73  dummy" record is
6e10: 20 4e 55 4c 4c 20 73 6f 0a 74 68 65 20 72 65 73   NULL so.the res
6e20: 75 6c 74 5b 5d 20 61 72 72 61 79 20 63 6f 6e 74  ult[] array cont
6e30: 61 69 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ains a NULL poin
6e40: 74 65 72 20 61 74 20 74 68 61 74 20 73 6c 6f 74  ter at that slot
6e50: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 49 66 20 74 68 65  .</p>..<p>If the
6e60: 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
6e70: 20 71 75 65 72 79 20 69 73 20 65 6d 70 74 79 2c   query is empty,
6e80: 20 74 68 65 6e 20 62 79 20 64 65 66 61 75 6c 74   then by default
6e90: 0a 3c 62 3e 73 71 6c 69 74 65 5f 67 65 74 5f 74  .<b>sqlite_get_t
6ea0: 61 62 6c 65 3c 2f 62 3e 20 77 69 6c 6c 20 73 65  able</b> will se
6eb0: 74 20 6e 72 6f 77 20 74 6f 20 30 20 61 6e 64 20  t nrow to 0 and 
6ec0: 6c 65 61 76 65 20 69 74 73 0a 72 65 73 75 6c 74  leave its.result
6ed0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 73 65   parameter is se
6ee0: 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 42 75 74 20  t to NULL.  But 
6ef0: 69 66 20 74 68 65 20 45 4d 50 54 59 5f 52 45 53  if the EMPTY_RES
6f00: 55 4c 54 5f 43 41 4c 4c 42 41 43 4b 53 0a 70 72  ULT_CALLBACKS.pr
6f10: 61 67 6d 61 20 69 73 20 4f 4e 20 74 68 65 6e 20  agma is ON then 
6f20: 74 68 65 20 72 65 73 75 6c 74 20 70 61 72 61 6d  the result param
6f30: 65 74 65 72 20 69 73 20 69 6e 69 74 69 61 6c 69  eter is initiali
6f40: 7a 65 64 20 74 6f 20 74 68 65 20 6e 61 6d 65 73  zed to the names
6f50: 0a 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 20  .of the columns 
6f60: 6f 6e 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  only.  For examp
6f70: 6c 65 2c 20 63 6f 6e 73 69 64 65 72 20 74 68 69  le, consider thi
6f80: 73 20 71 75 65 72 79 20 77 68 69 63 68 20 68 61  s query which ha
6f90: 73 0a 61 6e 20 65 6d 70 74 79 20 72 65 73 75 6c  s.an empty resul
6fa0: 74 20 73 65 74 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f  t set:</p>..<blo
6fb0: 63 6b 71 75 6f 74 65 3e 0a 53 45 4c 45 43 54 20  ckquote>.SELECT 
6fc0: 65 6d 70 6c 6f 79 65 65 5f 6e 61 6d 65 2c 20 6c  employee_name, l
6fd0: 6f 67 69 6e 2c 20 68 6f 73 74 20 46 52 4f 4d 20  ogin, host FROM 
6fe0: 75 73 65 72 73 20 57 48 45 52 45 20 65 6d 70 6c  users WHERE empl
6ff0: 6f 79 65 65 5f 6e 61 6d 65 20 49 53 20 4e 55 4c  oyee_name IS NUL
7000: 4c 3b 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  L;.</blockquote>
7010: 0a 0a 3c 70 3e 0a 54 68 65 20 64 65 66 61 75 6c  ..<p>.The defaul
7020: 74 20 62 65 68 61 76 69 6f 72 20 67 69 76 65 73  t behavior gives
7030: 20 74 68 69 73 20 72 65 73 75 6c 74 73 3a 0a 3c   this results:.<
7040: 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  /p>..<blockquote
7050: 3e 0a 6e 72 6f 77 20 3d 20 30 3c 62 72 3e 0a 6e  >.nrow = 0<br>.n
7060: 63 6f 6c 75 6d 6e 20 3d 20 30 3c 62 72 3e 0a 72  column = 0<br>.r
7070: 65 73 75 6c 74 20 3d 20 30 3c 62 72 3e 0a 3c 2f  esult = 0<br>.</
7080: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e  blockquote>..<p>
7090: 0a 42 75 74 20 69 66 20 74 68 65 20 45 4d 50 54  .But if the EMPT
70a0: 59 5f 52 45 53 55 4c 54 5f 43 41 4c 4c 42 41 43  Y_RESULT_CALLBAC
70b0: 4b 53 20 70 72 61 67 6d 61 20 69 73 20 4f 4e 2c  KS pragma is ON,
70c0: 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
70d0: 69 6e 67 0a 69 73 20 72 65 74 75 72 6e 65 64 3a  ing.is returned:
70e0: 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  .</p>..<blockquo
70f0: 74 65 3e 0a 6e 72 6f 77 20 3d 20 30 3c 62 72 3e  te>.nrow = 0<br>
7100: 0a 6e 63 6f 6c 75 6d 6e 20 3d 20 33 3c 62 72 3e  .ncolumn = 3<br>
7110: 0a 72 65 73 75 6c 74 5b 30 5d 20 3d 20 22 65 6d  .result[0] = "em
7120: 70 6c 6f 79 65 65 5f 6e 61 6d 65 22 3c 62 72 3e  ployee_name"<br>
7130: 0a 72 65 73 75 6c 74 5b 31 5d 20 3d 20 22 6c 6f  .result[1] = "lo
7140: 67 69 6e 22 3c 62 72 3e 0a 72 65 73 75 6c 74 5b  gin"<br>.result[
7150: 32 5d 20 3d 20 22 68 6f 73 74 22 3c 62 72 3e 0a  2] = "host"<br>.
7160: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
7170: 70 3e 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  p>Memory to hold
7180: 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e   the information
7190: 20 72 65 74 75 72 6e 65 64 20 62 79 20 3c 62 3e   returned by <b>
71a0: 73 71 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65  sqlite_get_table
71b0: 3c 2f 62 3e 0a 69 73 20 6f 62 74 61 69 6e 65 64  </b>.is obtained
71c0: 20 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 2e 20   from malloc(). 
71d0: 20 42 75 74 20 74 68 65 20 63 61 6c 6c 69 6e 67   But the calling
71e0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
71f0: 20 6e 6f 74 20 74 72 79 0a 74 6f 20 66 72 65 65   not try.to free
7200: 20 74 68 69 73 20 69 6e 66 6f 72 6d 61 74 69 6f   this informatio
7210: 6e 20 64 69 72 65 63 74 6c 79 2e 20 20 49 6e 73  n directly.  Ins
7220: 74 65 61 64 2c 20 70 61 73 73 20 74 68 65 20 63  tead, pass the c
7230: 6f 6d 70 6c 65 74 65 20 74 61 62 6c 65 0a 74 6f  omplete table.to
7240: 20 3c 62 3e 73 71 6c 69 74 65 5f 66 72 65 65 5f   <b>sqlite_free_
7250: 74 61 62 6c 65 3c 2f 62 3e 20 77 68 65 6e 20 74  table</b> when t
7260: 68 65 20 74 61 62 6c 65 20 69 73 20 6e 6f 20 6c  he table is no l
7270: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 49 74  onger needed..It
7280: 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
7290: 20 3c 62 3e 73 71 6c 69 74 65 5f 66 72 65 65 5f   <b>sqlite_free_
72a0: 74 61 62 6c 65 3c 2f 62 3e 20 77 69 74 68 20 61  table</b> with a
72b0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73 75   NULL pointer su
72c0: 63 68 0a 61 73 20 77 6f 75 6c 64 20 62 65 20 72  ch.as would be r
72d0: 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 72  eturned if the r
72e0: 65 73 75 6c 74 20 73 65 74 20 69 73 20 65 6d 70  esult set is emp
72f0: 74 79 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20  ty.</p>..<p>The 
7300: 3c 62 3e 73 71 6c 69 74 65 5f 67 65 74 5f 74 61  <b>sqlite_get_ta
7310: 62 6c 65 3c 2f 62 3e 20 72 6f 75 74 69 6e 65 20  ble</b> routine 
7320: 72 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65  returns the same
7330: 20 69 6e 74 65 67 65 72 0a 72 65 73 75 6c 74 20   integer.result 
7340: 63 6f 64 65 20 61 73 20 3c 62 3e 73 71 6c 69 74  code as <b>sqlit
7350: 65 5f 65 78 65 63 3c 2f 62 3e 2e 3c 2f 70 3e 0a  e_exec</b>.</p>.
7360: 0a 3c 68 33 3e 33 2e 34 20 49 6e 74 65 72 72 75  .<h3>3.4 Interru
7370: 70 74 69 6e 67 20 61 6e 20 53 51 4c 69 74 65 20  pting an SQLite 
7380: 6f 70 65 72 61 74 69 6f 6e 3c 2f 68 33 3e 0a 0a  operation</h3>..
7390: 3c 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69 74 65  <p>The <b>sqlite
73a0: 5f 69 6e 74 65 72 72 75 70 74 3c 2f 62 3e 20 66  _interrupt</b> f
73b0: 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 63  unction can be c
73c0: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 64 69 66  alled from a.dif
73d0: 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 6f 72  ferent thread or
73e0: 20 66 72 6f 6d 20 61 20 73 69 67 6e 61 6c 20 68   from a signal h
73f0: 61 6e 64 6c 65 72 20 74 6f 20 63 61 75 73 65 20  andler to cause 
7400: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
7410: 62 61 73 65 0a 6f 70 65 72 61 74 69 6f 6e 20 74  base.operation t
7420: 6f 20 65 78 69 74 20 61 74 20 69 74 73 20 66 69  o exit at its fi
7430: 72 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  rst opportunity.
7440: 20 20 57 68 65 6e 20 74 68 69 73 20 68 61 70 70    When this happ
7450: 65 6e 73 2c 0a 74 68 65 20 3c 62 3e 73 71 6c 69  ens,.the <b>sqli
7460: 74 65 5f 65 78 65 63 3c 2f 62 3e 20 72 6f 75 74  te_exec</b> rout
7470: 69 6e 65 20 28 6f 72 20 74 68 65 20 65 71 75 69  ine (or the equi
7480: 76 61 6c 65 6e 74 29 20 74 68 61 74 20 73 74 61  valent) that sta
7490: 72 74 65 64 0a 74 68 65 20 64 61 74 61 62 61 73  rted.the databas
74a0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 77 69 6c 6c  e operation will
74b0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 49   return SQLITE_I
74c0: 4e 54 45 52 52 55 50 54 2e 3c 2f 70 3e 0a 0a 3c  NTERRUPT.</p>..<
74d0: 68 33 3e 33 2e 35 20 54 65 73 74 69 6e 67 20 66  h3>3.5 Testing f
74e0: 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  or a complete SQ
74f0: 4c 20 73 74 61 74 65 6d 65 6e 74 3c 2f 68 33 3e  L statement</h3>
7500: 0a 0a 3c 70 3e 54 68 65 20 6e 65 78 74 20 69 6e  ..<p>The next in
7510: 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 20  terface routine 
7520: 74 6f 20 53 51 4c 69 74 65 20 69 73 20 61 20 63  to SQLite is a c
7530: 6f 6e 76 65 6e 69 65 6e 63 65 20 66 75 6e 63 74  onvenience funct
7540: 69 6f 6e 20 75 73 65 64 0a 74 6f 20 74 65 73 74  ion used.to test
7550: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
7560: 61 20 73 74 72 69 6e 67 20 66 6f 72 6d 73 20 61  a string forms a
7570: 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
7580: 61 74 65 6d 65 6e 74 2e 0a 49 66 20 74 68 65 20  atement..If the 
7590: 3c 62 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 6c 65  <b>sqlite_comple
75a0: 74 65 3c 2f 62 3e 20 66 75 6e 63 74 69 6f 6e 20  te</b> function 
75b0: 72 65 74 75 72 6e 73 20 74 72 75 65 20 77 68 65  returns true whe
75c0: 6e 20 69 74 73 20 69 6e 70 75 74 0a 69 73 20 61  n its input.is a
75d0: 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 74 68   string, then th
75e0: 65 20 61 72 67 75 6d 65 6e 74 20 66 6f 72 6d 73  e argument forms
75f0: 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
7600: 73 74 61 74 65 6d 65 6e 74 2e 0a 54 68 65 72 65  statement..There
7610: 20 61 72 65 20 6e 6f 20 67 75 61 72 61 6e 74 65   are no guarante
7620: 65 73 20 74 68 61 74 20 74 68 65 20 73 79 6e 74  es that the synt
7630: 61 78 20 6f 66 20 74 68 61 74 20 73 74 61 74 65  ax of that state
7640: 6d 65 6e 74 20 69 73 20 63 6f 72 72 65 63 74 2c  ment is correct,
7650: 0a 62 75 74 20 77 65 20 61 74 20 6c 65 61 73 74  .but we at least
7660: 20 6b 6e 6f 77 20 74 68 65 20 73 74 61 74 65 6d   know the statem
7670: 65 6e 74 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  ent is complete.
7680: 20 20 49 66 20 3c 62 3e 73 71 6c 69 74 65 5f 63    If <b>sqlite_c
7690: 6f 6d 70 6c 65 74 65 3c 2f 62 3e 0a 72 65 74 75  omplete</b>.retu
76a0: 72 6e 73 20 66 61 6c 73 65 2c 20 74 68 65 6e 20  rns false, then 
76b0: 6d 6f 72 65 20 74 65 78 74 20 69 73 20 72 65 71  more text is req
76c0: 75 69 72 65 64 20 74 6f 20 63 6f 6d 70 6c 65 74  uired to complet
76d0: 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
76e0: 65 6e 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e 46 6f 72  ent.</p>..<p>For
76f0: 20 74 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20   the purpose of 
7700: 74 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 63 6f  the <b>sqlite_co
7710: 6d 70 6c 65 74 65 3c 2f 62 3e 20 66 75 6e 63 74  mplete</b> funct
7720: 69 6f 6e 2c 20 61 6e 20 53 51 4c 0a 73 74 61 74  ion, an SQL.stat
7730: 65 6d 65 6e 74 20 69 73 20 63 6f 6d 70 6c 65 74  ement is complet
7740: 65 20 69 66 20 69 74 20 65 6e 64 73 20 69 6e 20  e if it ends in 
7750: 61 20 73 65 6d 69 63 6f 6c 6f 6e 2e 3c 2f 70 3e  a semicolon.</p>
7760: 0a 0a 3c 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69  ..<p>The <b>sqli
7770: 74 65 3c 2f 62 3e 20 63 6f 6d 6d 61 6e 64 2d 6c  te</b> command-l
7780: 69 6e 65 20 75 74 69 6c 69 74 79 20 75 73 65 73  ine utility uses
7790: 20 74 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 63   the <b>sqlite_c
77a0: 6f 6d 70 6c 65 74 65 3c 2f 62 3e 0a 66 75 6e 63  omplete</b>.func
77b0: 74 69 6f 6e 20 74 6f 20 6b 6e 6f 77 20 77 68 65  tion to know whe
77c0: 6e 20 69 74 20 6e 65 65 64 73 20 74 6f 20 63 61  n it needs to ca
77d0: 6c 6c 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65  ll <b>sqlite_exe
77e0: 63 3c 2f 62 3e 2e 20 20 41 66 74 65 72 20 65 61  c</b>.  After ea
77f0: 63 68 0a 6c 69 6e 65 20 6f 66 20 69 6e 70 75 74  ch.line of input
7800: 20 69 73 20 72 65 63 65 69 76 65 64 2c 20 3c 62   is received, <b
7810: 3e 73 71 6c 69 74 65 3c 2f 62 3e 20 63 61 6c 6c  >sqlite</b> call
7820: 73 20 3c 62 3e 73 71 6c 69 74 65 5f 63 6f 6d 70  s <b>sqlite_comp
7830: 6c 65 74 65 3c 2f 62 3e 0a 6f 6e 20 61 6c 6c 20  lete</b>.on all 
7840: 69 6e 70 75 74 20 69 6e 20 69 74 73 20 62 75 66  input in its buf
7850: 66 65 72 2e 20 20 49 66 20 3c 62 3e 73 71 6c 69  fer.  If <b>sqli
7860: 74 65 5f 63 6f 6d 70 6c 65 74 65 3c 2f 62 3e 20  te_complete</b> 
7870: 72 65 74 75 72 6e 73 20 74 72 75 65 2c 20 0a 74  returns true, .t
7880: 68 65 6e 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78  hen <b>sqlite_ex
7890: 65 63 3c 2f 62 3e 20 69 73 20 63 61 6c 6c 65 64  ec</b> is called
78a0: 20 61 6e 64 20 74 68 65 20 69 6e 70 75 74 20 62   and the input b
78b0: 75 66 66 65 72 20 69 73 20 72 65 73 65 74 2e 20  uffer is reset. 
78c0: 20 49 66 0a 3c 62 3e 73 71 6c 69 74 65 5f 63 6f   If.<b>sqlite_co
78d0: 6d 70 6c 65 74 65 3c 2f 62 3e 20 72 65 74 75 72  mplete</b> retur
78e0: 6e 73 20 66 61 6c 73 65 2c 20 74 68 65 6e 20 74  ns false, then t
78f0: 68 65 20 70 72 6f 6d 70 74 20 69 73 20 63 68 61  he prompt is cha
7900: 6e 67 65 64 20 74 6f 0a 74 68 65 20 63 6f 6e 74  nged to.the cont
7910: 69 6e 75 61 74 69 6f 6e 20 70 72 6f 6d 70 74 20  inuation prompt 
7920: 61 6e 64 20 61 6e 6f 74 68 65 72 20 6c 69 6e 65  and another line
7930: 20 6f 66 20 74 65 78 74 20 69 73 20 72 65 61 64   of text is read
7940: 20 61 6e 64 20 61 64 64 65 64 20 74 6f 0a 74 68   and added to.th
7950: 65 20 69 6e 70 75 74 20 62 75 66 66 65 72 2e 3c  e input buffer.<
7960: 2f 70 3e 0a 0a 3c 68 33 3e 33 2e 36 20 4c 69 62  /p>..<h3>3.6 Lib
7970: 72 61 72 79 20 76 65 72 73 69 6f 6e 20 73 74 72  rary version str
7980: 69 6e 67 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 68 65  ing</h3>..<p>The
7990: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
79a0: 65 78 70 6f 72 74 73 20 74 68 65 20 73 74 72 69  exports the stri
79b0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 6e 61 6d 65  ng constant name
79c0: 64 0a 3c 62 3e 73 71 6c 69 74 65 5f 76 65 72 73  d.<b>sqlite_vers
79d0: 69 6f 6e 3c 2f 62 3e 20 77 68 69 63 68 20 63 6f  ion</b> which co
79e0: 6e 74 61 69 6e 73 20 74 68 65 20 76 65 72 73 69  ntains the versi
79f0: 6f 6e 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 65  on number of the
7a00: 0a 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 68  .library.  The h
7a10: 65 61 64 65 72 20 66 69 6c 65 20 63 6f 6e 74 61  eader file conta
7a20: 69 6e 73 20 61 20 6d 61 63 72 6f 20 53 51 4c 49  ins a macro SQLI
7a30: 54 45 5f 56 45 52 53 49 4f 4e 0a 77 69 74 68 20  TE_VERSION.with 
7a40: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
7a50: 74 69 6f 6e 2e 20 20 49 66 20 64 65 73 69 72 65  tion.  If desire
7a60: 64 2c 20 61 20 70 72 6f 67 72 61 6d 20 63 61 6e  d, a program can
7a70: 20 63 6f 6d 70 61 72 65 0a 74 68 65 20 53 51 4c   compare.the SQL
7a80: 49 54 45 5f 56 45 52 53 49 4f 4e 20 6d 61 63 72  ITE_VERSION macr
7a90: 6f 20 61 67 61 69 6e 73 74 20 74 68 65 20 3c 62  o against the <b
7aa0: 3e 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 3c  >sqlite_version<
7ab0: 2f 62 3e 0a 73 74 72 69 6e 67 20 63 6f 6e 73 74  /b>.string const
7ac0: 61 6e 74 20 74 6f 20 76 65 72 69 66 79 20 74 68  ant to verify th
7ad0: 61 74 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e  at the version n
7ae0: 75 6d 62 65 72 20 6f 66 20 74 68 65 0a 68 65 61  umber of the.hea
7af0: 64 65 72 20 66 69 6c 65 20 61 6e 64 20 74 68 65  der file and the
7b00: 20 6c 69 62 72 61 72 79 20 6d 61 74 63 68 2e 3c   library match.<
7b10: 2f 70 3e 20 0a 0a 3c 68 33 3e 33 2e 37 20 4c 69  /p> ..<h3>3.7 Li
7b20: 62 72 61 72 79 20 63 68 61 72 61 63 74 65 72 20  brary character 
7b30: 65 6e 63 6f 64 69 6e 67 3c 2f 68 33 3e 0a 0a 3c  encoding</h3>..<
7b40: 70 3e 42 79 20 64 65 66 61 75 6c 74 2c 20 53 51  p>By default, SQ
7b50: 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
7b60: 74 20 61 6c 6c 20 64 61 74 61 20 75 73 65 73 20  t all data uses 
7b70: 61 20 66 69 78 65 64 2d 73 69 7a 65 0a 38 2d 62  a fixed-size.8-b
7b80: 69 74 20 63 68 61 72 61 63 74 65 72 20 28 69 73  it character (is
7b90: 6f 38 38 35 39 29 2e 20 20 42 75 74 20 69 66 20  o8859).  But if 
7ba0: 79 6f 75 20 67 69 76 65 20 74 68 65 20 2d 2d 65  you give the --e
7bb0: 6e 61 62 6c 65 2d 75 74 66 38 20 6f 70 74 69 6f  nable-utf8 optio
7bc0: 6e 0a 74 6f 20 74 68 65 20 63 6f 6e 66 69 67 75  n.to the configu
7bd0: 72 65 20 73 63 72 69 70 74 2c 20 74 68 65 6e 20  re script, then 
7be0: 74 68 65 20 6c 69 62 72 61 72 79 20 61 73 73 75  the library assu
7bf0: 6d 65 73 20 55 54 46 2d 38 20 76 61 72 69 61 62  mes UTF-8 variab
7c00: 6c 65 0a 73 69 7a 65 64 20 63 68 61 72 61 63 74  le.sized charact
7c10: 65 72 73 2e 20 20 54 68 69 73 20 6d 61 6b 65 73  ers.  This makes
7c20: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 66 6f   a difference fo
7c30: 72 20 74 68 65 20 4c 49 4b 45 20 61 6e 64 20 47  r the LIKE and G
7c40: 4c 4f 42 0a 6f 70 65 72 61 74 6f 72 73 20 61 6e  LOB.operators an
7c50: 64 20 74 68 65 20 4c 45 4e 47 54 48 28 29 20 61  d the LENGTH() a
7c60: 6e 64 20 53 55 42 53 54 52 28 29 20 66 75 6e 63  nd SUBSTR() func
7c70: 74 69 6f 6e 73 2e 20 20 54 68 65 20 73 74 61 74  tions.  The stat
7c80: 69 63 0a 73 74 72 69 6e 67 20 3c 62 3e 73 71 6c  ic.string <b>sql
7c90: 69 74 65 5f 65 6e 63 6f 64 69 6e 67 3c 2f 62 3e  ite_encoding</b>
7ca0: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 74 6f 20   will be set to 
7cb0: 65 69 74 68 65 72 20 22 55 54 46 2d 38 22 20 6f  either "UTF-8" o
7cc0: 72 0a 22 69 73 6f 38 38 35 39 22 20 74 6f 20 69  r."iso8859" to i
7cd0: 6e 64 69 63 61 74 65 20 68 6f 77 20 74 68 65 20  ndicate how the 
7ce0: 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
7cf0: 69 6c 65 64 2e 20 20 49 6e 20 61 64 64 69 74 69  iled.  In additi
7d00: 6f 6e 2c 0a 74 68 65 20 3c 62 3e 73 71 6c 69 74  on,.the <b>sqlit
7d10: 65 2e 68 3c 2f 62 3e 20 68 65 61 64 65 72 20 66  e.h</b> header f
7d20: 69 6c 65 20 77 69 6c 6c 20 64 65 66 69 6e 65 20  ile will define 
7d30: 6f 6e 65 20 6f 66 20 74 68 65 0a 6d 61 63 72 6f  one of the.macro
7d40: 73 20 3c 62 3e 53 51 4c 49 54 45 5f 55 54 46 38  s <b>SQLITE_UTF8
7d50: 3c 2f 62 3e 20 6f 72 20 3c 62 3e 53 51 4c 49 54  </b> or <b>SQLIT
7d60: 45 5f 49 53 4f 38 38 35 39 3c 2f 62 3e 2c 20 61  E_ISO8859</b>, a
7d70: 73 20 61 70 70 72 6f 70 72 69 61 74 65 2e 3c 2f  s appropriate.</
7d80: 70 3e 0a 0a 3c 70 3e 4e 6f 74 65 20 74 68 61 74  p>..<p>Note that
7d90: 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20 65   the character e
7da0: 6e 63 6f 64 69 6e 67 20 6d 65 63 68 61 6e 69 73  ncoding mechanis
7db0: 6d 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  m used by SQLite
7dc0: 20 63 61 6e 6e 6f 74 0a 62 65 20 63 68 61 6e 67   cannot.be chang
7dd0: 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 2e 20  ed at run-time. 
7de0: 20 54 68 69 73 20 69 73 20 61 20 63 6f 6d 70 69   This is a compi
7df0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6f  le-time option o
7e00: 6e 6c 79 2e 20 20 54 68 65 0a 3c 62 3e 73 71 6c  nly.  The.<b>sql
7e10: 69 74 65 5f 65 6e 63 6f 64 69 6e 67 3c 2f 62 3e  ite_encoding</b>
7e20: 20 63 68 61 72 61 63 74 65 72 20 73 74 72 69 6e   character strin
7e30: 67 20 6a 75 73 74 20 74 65 6c 6c 73 20 79 6f 75  g just tells you
7e40: 20 68 6f 77 20 74 68 65 20 6c 69 62 72 61 72 79   how the library
7e50: 0a 77 61 73 20 63 6f 6d 70 69 6c 65 64 2e 3c 2f  .was compiled.</
7e60: 70 3e 0a 0a 3c 68 33 3e 33 2e 38 20 43 68 61 6e  p>..<h3>3.8 Chan
7e70: 67 69 6e 67 20 74 68 65 20 6c 69 62 72 61 72 79  ging the library
7e80: 27 73 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 6c  's response to l
7e90: 6f 63 6b 65 64 20 66 69 6c 65 73 3c 2f 68 33 3e  ocked files</h3>
7ea0: 0a 0a 3c 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69  ..<p>The <b>sqli
7eb0: 74 65 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 3c  te_busy_handler<
7ec0: 2f 62 3e 20 70 72 6f 63 65 64 75 72 65 20 63 61  /b> procedure ca
7ed0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 67  n be used to reg
7ee0: 69 73 74 65 72 0a 61 20 62 75 73 79 20 63 61 6c  ister.a busy cal
7ef0: 6c 62 61 63 6b 20 77 69 74 68 20 61 6e 20 6f 70  lback with an op
7f00: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
7f10: 73 65 2e 20 20 54 68 65 20 62 75 73 79 20 63 61  se.  The busy ca
7f20: 6c 6c 62 61 63 6b 20 77 69 6c 6c 0a 62 65 20 69  llback will.be i
7f30: 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
7f40: 53 51 4c 69 74 65 20 74 72 69 65 73 20 74 6f 20  SQLite tries to 
7f50: 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73  access a databas
7f60: 65 20 74 68 61 74 20 69 73 20 6c 6f 63 6b 65 64  e that is locked
7f70: 2e 0a 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 77  ..The callback w
7f80: 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 64 6f  ill typically do
7f90: 20 73 6f 6d 65 20 6f 74 68 65 72 20 75 73 65 66   some other usef
7fa0: 75 6c 20 77 6f 72 6b 2c 20 6f 72 20 70 65 72 68  ul work, or perh
7fb0: 61 70 73 20 73 6c 65 65 70 2c 0a 69 6e 20 6f 72  aps sleep,.in or
7fc0: 64 65 72 20 74 6f 20 67 69 76 65 20 74 68 65 20  der to give the 
7fd0: 6c 6f 63 6b 20 61 20 63 68 61 6e 63 65 20 74 6f  lock a chance to
7fe0: 20 63 6c 65 61 72 2e 20 20 49 66 20 74 68 65 20   clear.  If the 
7ff0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
8000: 0a 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20  .non-zero, then 
8010: 53 51 4c 69 74 65 20 74 72 69 65 73 20 61 67 61  SQLite tries aga
8020: 69 6e 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  in to access the
8030: 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68   database and th
8040: 65 20 63 79 63 6c 65 0a 72 65 70 65 61 74 73 2e  e cycle.repeats.
8050: 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63    If the callbac
8060: 6b 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  k returns zero, 
8070: 74 68 65 6e 20 53 51 4c 69 74 65 20 61 62 6f 72  then SQLite abor
8080: 74 73 20 74 68 65 20 63 75 72 72 65 6e 74 0a 6f  ts the current.o
8090: 70 65 72 61 74 69 6f 6e 20 61 6e 64 20 72 65 74  peration and ret
80a0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 42 55 53 59  urns SQLITE_BUSY
80b0: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 61 72  .</p>..<p>The ar
80c0: 67 75 6d 65 6e 74 73 20 74 6f 20 3c 62 3e 73 71  guments to <b>sq
80d0: 6c 69 74 65 5f 62 75 73 79 5f 68 61 6e 64 6c 65  lite_busy_handle
80e0: 72 3c 2f 62 3e 20 61 72 65 20 74 68 65 20 6f 70  r</b> are the op
80f0: 61 71 75 65 0a 73 74 72 75 63 74 75 72 65 20 72  aque.structure r
8100: 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 3c 62 3e  eturned from <b>
8110: 73 71 6c 69 74 65 5f 6f 70 65 6e 3c 2f 62 3e 2c  sqlite_open</b>,
8120: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
8130: 65 20 62 75 73 79 0a 63 61 6c 6c 62 61 63 6b 20  e busy.callback 
8140: 66 75 6e 63 74 69 6f 6e 2c 20 61 6e 64 20 61 20  function, and a 
8150: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
8160: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 70 61 73  that will be pas
8170: 73 65 64 20 61 73 0a 74 68 65 20 66 69 72 73 74  sed as.the first
8180: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
8190: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 2e 20   busy callback. 
81a0: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
81b0: 6f 6b 65 73 20 74 68 65 0a 62 75 73 79 20 63 61  okes the.busy ca
81c0: 6c 6c 62 61 63 6b 2c 20 69 74 20 73 65 6e 64 73  llback, it sends
81d0: 20 69 74 20 74 68 72 65 65 20 61 72 67 75 6d 65   it three argume
81e0: 6e 74 73 3a 20 20 74 68 65 20 67 65 6e 65 72 69  nts:  the generi
81f0: 63 20 70 6f 69 6e 74 65 72 0a 74 68 61 74 20 77  c pointer.that w
8200: 61 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  as passed in as 
8210: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
8220: 6e 74 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f  nt to <b>sqlite_
8230: 62 75 73 79 5f 68 61 6e 64 6c 65 72 3c 2f 62 3e  busy_handler</b>
8240: 2c 0a 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  ,.the name of th
8250: 65 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  e database table
8260: 20 6f 72 20 69 6e 64 65 78 20 74 68 61 74 20 74   or index that t
8270: 68 65 20 6c 69 62 72 61 72 79 20 69 73 20 74 72  he library is tr
8280: 79 69 6e 67 0a 74 6f 20 61 63 63 65 73 73 2c 20  ying.to access, 
8290: 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
82a0: 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
82b0: 20 6c 69 62 72 61 72 79 20 68 61 73 20 61 74 74   library has att
82c0: 65 6d 70 74 65 64 20 74 6f 0a 61 63 63 65 73 73  empted to.access
82d0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 61   the database ta
82e0: 62 6c 65 20 6f 72 20 69 6e 64 65 78 2e 3c 2f 70  ble or index.</p
82f0: 3e 0a 0a 3c 70 3e 46 6f 72 20 74 68 65 20 63 6f  >..<p>For the co
8300: 6d 6d 6f 6e 20 63 61 73 65 20 77 68 65 72 65 20  mmon case where 
8310: 77 65 20 77 61 6e 74 20 74 68 65 20 62 75 73 79  we want the busy
8320: 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 73 6c 65   callback to sle
8330: 65 70 2c 0a 74 68 65 20 53 51 4c 69 74 65 20 6c  ep,.the SQLite l
8340: 69 62 72 61 72 79 20 70 72 6f 76 69 64 65 73 20  ibrary provides 
8350: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 72 6f  a convenience ro
8360: 75 74 69 6e 65 20 3c 62 3e 73 71 6c 69 74 65 5f  utine <b>sqlite_
8370: 62 75 73 79 5f 74 69 6d 65 6f 75 74 3c 2f 62 3e  busy_timeout</b>
8380: 2e 0a 54 68 65 20 66 69 72 73 74 20 61 72 67 75  ..The first argu
8390: 6d 65 6e 74 20 74 6f 20 3c 62 3e 73 71 6c 69 74  ment to <b>sqlit
83a0: 65 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 3c 2f  e_busy_timeout</
83b0: 62 3e 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  b> is a pointer 
83c0: 74 6f 0a 61 6e 20 6f 70 65 6e 20 53 51 4c 69 74  to.an open SQLit
83d0: 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  e database and t
83e0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
83f0: 6e 74 20 69 73 20 61 20 6e 75 6d 62 65 72 20 6f  nt is a number o
8400: 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a  f milliseconds..
8410: 41 66 74 65 72 20 3c 62 3e 73 71 6c 69 74 65 5f  After <b>sqlite_
8420: 62 75 73 79 5f 74 69 6d 65 6f 75 74 3c 2f 62 3e  busy_timeout</b>
8430: 20 68 61 73 20 62 65 65 6e 20 65 78 65 63 75 74   has been execut
8440: 65 64 2c 20 74 68 65 20 53 51 4c 69 74 65 20 6c  ed, the SQLite l
8450: 69 62 72 61 72 79 0a 77 69 6c 6c 20 77 61 69 74  ibrary.will wait
8460: 20 66 6f 72 20 74 68 65 20 6c 6f 63 6b 20 74 6f   for the lock to
8470: 20 63 6c 65 61 72 20 66 6f 72 20 61 74 20 6c 65   clear for at le
8480: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
8490: 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 0a  f milliseconds .
84a0: 73 70 65 63 69 66 69 65 64 20 62 65 66 6f 72 65  specified before
84b0: 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49   it returns SQLI
84c0: 54 45 5f 42 55 53 59 2e 20 20 53 70 65 63 69 66  TE_BUSY.  Specif
84d0: 79 69 6e 67 20 7a 65 72 6f 20 6d 69 6c 6c 69 73  ying zero millis
84e0: 65 63 6f 6e 64 73 20 66 6f 72 0a 74 68 65 20 74  econds for.the t
84f0: 69 6d 65 6f 75 74 20 72 65 73 74 6f 72 65 73 20  imeout restores 
8500: 74 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  the default beha
8510: 76 69 6f 72 2e 3c 2f 70 3e 0a 0a 3c 68 33 3e 33  vior.</p>..<h3>3
8520: 2e 39 20 55 73 69 6e 67 20 74 68 65 20 3c 74 74  .9 Using the <tt
8530: 3e 5f 70 72 69 6e 74 66 28 29 3c 2f 74 74 3e 20  >_printf()</tt> 
8540: 77 72 61 70 70 65 72 20 66 75 6e 63 74 69 6f 6e  wrapper function
8550: 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 68 65 20 66  s</h3>..<p>The f
8560: 6f 75 72 20 75 74 69 6c 69 74 79 20 66 75 6e 63  our utility func
8570: 74 69 6f 6e 73 3c 2f 70 3e 0a 0a 3c 70 3e 0a 3c  tions</p>..<p>.<
8580: 75 6c 3e 0a 3c 6c 69 3e 3c 62 3e 73 71 6c 69 74  ul>.<li><b>sqlit
8590: 65 5f 65 78 65 63 5f 70 72 69 6e 74 66 28 29 3c  e_exec_printf()<
85a0: 2f 62 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c 62 3e  /b></li>.<li><b>
85b0: 73 71 6c 69 74 65 5f 65 78 65 63 5f 76 70 72 69  sqlite_exec_vpri
85c0: 6e 74 66 28 29 3c 2f 62 3e 3c 2f 6c 69 3e 0a 3c  ntf()</b></li>.<
85d0: 6c 69 3e 3c 62 3e 73 71 6c 69 74 65 5f 67 65 74  li><b>sqlite_get
85e0: 5f 74 61 62 6c 65 5f 70 72 69 6e 74 66 28 29 3c  _table_printf()<
85f0: 2f 62 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c 62 3e  /b></li>.<li><b>
8600: 73 71 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65  sqlite_get_table
8610: 5f 76 70 72 69 6e 74 66 28 29 3c 2f 62 3e 3c 2f  _vprintf()</b></
8620: 6c 69 3e 0a 3c 2f 75 6c 3e 0a 3c 2f 70 3e 0a 0a  li>.</ul>.</p>..
8630: 3c 70 3e 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  <p>implement the
8640: 20 73 61 6d 65 20 71 75 65 72 79 20 66 75 6e 63   same query func
8650: 74 69 6f 6e 61 6c 69 74 79 20 61 73 20 3c 62 3e  tionality as <b>
8660: 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e 0a  sqlite_exec</b>.
8670: 61 6e 64 20 3c 62 3e 73 71 6c 69 74 65 5f 67 65  and <b>sqlite_ge
8680: 74 5f 74 61 62 6c 65 3c 2f 62 3e 2e 20 20 42 75  t_table</b>.  Bu
8690: 74 20 69 6e 73 74 65 61 64 20 6f 66 20 74 61 6b  t instead of tak
86a0: 69 6e 67 20 61 20 63 6f 6d 70 6c 65 74 65 0a 53  ing a complete.S
86b0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
86c0: 74 68 65 69 72 20 73 65 63 6f 6e 64 20 61 72 67  their second arg
86d0: 75 6d 65 6e 74 2c 20 74 68 65 20 66 6f 75 72 20  ument, the four 
86e0: 3c 62 3e 5f 70 72 69 6e 74 66 3c 2f 62 3e 0a 72  <b>_printf</b>.r
86f0: 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 70  outines take a p
8700: 72 69 6e 74 66 2d 73 74 79 6c 65 20 66 6f 72 6d  rintf-style form
8710: 61 74 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20  at string.  The 
8720: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
8730: 0a 62 65 20 65 78 65 63 75 74 65 64 20 69 73 20  .be executed is 
8740: 67 65 6e 65 72 61 74 65 64 20 66 72 6f 6d 20 74  generated from t
8750: 68 69 73 20 66 6f 72 6d 61 74 20 73 74 72 69 6e  his format strin
8760: 67 20 61 6e 64 20 66 72 6f 6d 20 77 68 61 74 65  g and from whate
8770: 76 65 72 0a 61 64 64 69 74 69 6f 6e 61 6c 20 61  ver.additional a
8780: 72 67 75 6d 65 6e 74 73 20 61 72 65 20 61 74 74  rguments are att
8790: 61 63 68 65 64 20 74 6f 20 74 68 65 20 65 6e 64  ached to the end
87a0: 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
87b0: 20 63 61 6c 6c 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54   call.</p>..<p>T
87c0: 68 65 72 65 20 61 72 65 20 74 77 6f 20 61 64 76  here are two adv
87d0: 61 6e 74 61 67 65 73 20 74 6f 20 75 73 69 6e 67  antages to using
87e0: 20 74 68 65 20 53 51 4c 69 74 65 20 70 72 69 6e   the SQLite prin
87f0: 74 66 0a 66 75 6e 63 74 69 6f 6e 73 20 69 6e 73  tf.functions ins
8800: 74 65 61 64 20 6f 66 20 3c 62 3e 73 70 72 69 6e  tead of <b>sprin
8810: 74 66 3c 2f 62 3e 2e 20 20 46 69 72 73 74 20 6f  tf</b>.  First o
8820: 66 20 61 6c 6c 2c 20 77 69 74 68 20 74 68 65 0a  f all, with the.
8830: 53 51 4c 69 74 65 20 70 72 69 6e 74 66 20 72 6f  SQLite printf ro
8840: 75 74 69 6e 65 73 2c 20 74 68 65 72 65 20 69 73  utines, there is
8850: 20 6e 65 76 65 72 20 61 20 64 61 6e 67 65 72 20   never a danger 
8860: 6f 66 20 6f 76 65 72 66 6c 6f 77 69 6e 67 20 61  of overflowing a
8870: 0a 73 74 61 74 69 63 20 62 75 66 66 65 72 20 61  .static buffer a
8880: 73 20 74 68 65 72 65 20 69 73 20 77 69 74 68 20  s there is with 
8890: 3c 62 3e 73 70 72 69 6e 74 66 3c 2f 62 3e 2e 20  <b>sprintf</b>. 
88a0: 20 54 68 65 20 53 51 4c 69 74 65 0a 70 72 69 6e   The SQLite.prin
88b0: 74 66 20 72 6f 75 74 69 6e 65 73 20 61 75 74 6f  tf routines auto
88c0: 6d 61 74 69 63 61 6c 6c 79 20 61 6c 6c 6f 63 61  matically alloca
88d0: 74 65 20 28 61 6e 64 20 6c 61 74 65 72 20 66 72  te (and later fr
88e0: 65 65 73 29 0a 61 73 20 6d 75 63 68 20 6d 65 6d  ees).as much mem
88f0: 6f 72 79 20 61 73 20 69 73 20 0a 6e 65 63 65 73  ory as is .neces
8900: 73 61 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  sary to hold the
8910: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
8920: 67 65 6e 65 72 61 74 65 64 2e 3c 2f 70 3e 0a 0a  generated.</p>..
8930: 3c 70 3e 54 68 65 20 73 65 63 6f 6e 64 20 61 64  <p>The second ad
8940: 76 61 6e 74 61 67 65 20 74 68 65 20 53 51 4c 69  vantage the SQLi
8950: 74 65 20 70 72 69 6e 74 66 20 72 6f 75 74 69 6e  te printf routin
8960: 65 73 20 68 61 76 65 20 6f 76 65 72 0a 3c 62 3e  es have over.<b>
8970: 73 70 72 69 6e 74 66 3c 2f 62 3e 20 61 72 65 20  sprintf</b> are 
8980: 74 77 6f 20 6e 65 77 20 66 6f 72 6d 61 74 74 69  two new formatti
8990: 6e 67 20 6f 70 74 69 6f 6e 73 20 73 70 65 63 69  ng options speci
89a0: 66 69 63 61 6c 6c 79 20 64 65 73 69 67 6e 65 64  fically designed
89b0: 0a 74 6f 20 73 75 70 70 6f 72 74 20 73 74 72 69  .to support stri
89c0: 6e 67 20 6c 69 74 65 72 61 6c 73 20 69 6e 20 53  ng literals in S
89d0: 51 4c 2e 20 20 57 69 74 68 69 6e 20 74 68 65 20  QL.  Within the 
89e0: 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 2c 0a 74  format string,.t
89f0: 68 65 20 25 71 20 66 6f 72 6d 61 74 74 69 6e 67  he %q formatting
8a00: 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 76 65   option works ve
8a10: 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 25 73 20  ry much like %s 
8a20: 69 6e 20 74 68 61 74 20 69 74 0a 72 65 61 64 73  in that it.reads
8a30: 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74   a null-terminat
8a40: 65 64 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ed string from t
8a50: 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
8a60: 20 61 6e 64 20 69 6e 73 65 72 74 73 0a 69 74 20   and inserts.it 
8a70: 69 6e 74 6f 20 74 68 65 20 72 65 73 75 6c 74 2e  into the result.
8a80: 20 20 42 75 74 20 25 71 20 74 72 61 6e 73 6c 61    But %q transla
8a90: 74 65 73 20 74 68 65 20 69 6e 73 65 72 74 65 64  tes the inserted
8aa0: 20 73 74 72 69 6e 67 20 62 79 0a 6d 61 6b 69 6e   string by.makin
8ab0: 67 20 74 77 6f 20 63 6f 70 69 65 73 20 6f 66 20  g two copies of 
8ac0: 65 76 65 72 79 20 73 69 6e 67 6c 65 2d 71 75 6f  every single-quo
8ad0: 74 65 20 28 27 29 20 63 68 61 72 61 63 74 65 72  te (') character
8ae0: 20 69 6e 20 74 68 65 0a 73 75 62 73 74 69 74 75   in the.substitu
8af0: 74 65 64 20 73 74 72 69 6e 67 2e 20 20 54 68 69  ted string.  Thi
8b00: 73 20 68 61 73 20 74 68 65 20 65 66 66 65 63 74  s has the effect
8b10: 20 6f 66 20 65 73 63 61 70 69 6e 67 20 74 68 65   of escaping the
8b20: 20 65 6e 64 2d 6f 66 2d 73 74 72 69 6e 67 0a 6d   end-of-string.m
8b30: 65 61 6e 69 6e 67 20 6f 66 20 73 69 6e 67 6c 65  eaning of single
8b40: 2d 71 75 6f 74 65 20 77 69 74 68 69 6e 20 61 20  -quote within a 
8b50: 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20  string literal. 
8b60: 54 68 65 20 25 51 20 66 6f 72 6d 61 74 74 69 6e  The %Q formattin
8b70: 67 0a 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 73  g.option works s
8b80: 69 6d 69 6c 61 72 3b 20 69 74 20 74 72 61 6e 73  imilar; it trans
8b90: 6c 61 74 65 73 20 74 68 65 20 73 69 6e 67 6c 65  lates the single
8ba0: 2d 71 75 6f 74 65 73 20 6c 69 6b 65 20 25 71 20  -quotes like %q 
8bb0: 61 6e 64 0a 61 64 64 69 74 69 6f 6e 61 6c 6c 79  and.additionally
8bc0: 20 65 6e 63 6c 6f 73 65 73 20 74 68 65 20 72 65   encloses the re
8bd0: 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 69  sulting string i
8be0: 6e 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 73 2e  n single-quotes.
8bf0: 0a 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  .If the argument
8c00: 20 66 6f 72 20 74 68 65 20 25 51 20 66 6f 72 6d   for the %Q form
8c10: 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 69  atting options i
8c20: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
8c30: 2c 0a 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  ,.the resulting 
8c40: 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c 20 77  string is NULL w
8c50: 69 74 68 6f 75 74 20 73 69 6e 67 6c 65 20 71 75  ithout single qu
8c60: 6f 74 65 73 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 43  otes..</p>..<p>C
8c70: 6f 6e 73 69 64 65 72 20 61 6e 20 65 78 61 6d 70  onsider an examp
8c80: 6c 65 2e 20 20 53 75 70 70 6f 73 65 20 79 6f 75  le.  Suppose you
8c90: 20 61 72 65 20 74 72 79 69 6e 67 20 74 6f 20 69   are trying to i
8ca0: 6e 73 65 72 74 20 61 20 73 74 72 69 6e 67 0a 76  nsert a string.v
8cb0: 61 6c 75 65 20 69 6e 74 6f 20 61 20 64 61 74 61  alue into a data
8cc0: 62 61 73 65 20 74 61 62 6c 65 20 77 68 65 72 65  base table where
8cd0: 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 6c 75   the string valu
8ce0: 65 20 77 61 73 20 6f 62 74 61 69 6e 65 64 20 66  e was obtained f
8cf0: 72 6f 6d 0a 75 73 65 72 20 69 6e 70 75 74 2e 20  rom.user input. 
8d00: 20 53 75 70 70 6f 73 65 20 74 68 65 20 73 74 72   Suppose the str
8d10: 69 6e 67 20 74 6f 20 62 65 20 69 6e 73 65 72 74  ing to be insert
8d20: 65 64 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  ed is stored in 
8d30: 61 20 76 61 72 69 61 62 6c 65 0a 6e 61 6d 65 64  a variable.named
8d40: 20 7a 53 74 72 69 6e 67 2e 20 20 54 68 65 20 63   zString.  The c
8d50: 6f 64 65 20 74 6f 20 64 6f 20 74 68 65 20 69 6e  ode to do the in
8d60: 73 65 72 74 69 6f 6e 20 6d 69 67 68 74 20 6c 6f  sertion might lo
8d70: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 3c 2f 70  ok like this:</p
8d80: 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  >..<blockquote><
8d90: 70 72 65 3e 0a 73 71 6c 69 74 65 5f 65 78 65 63  pre>.sqlite_exec
8da0: 5f 70 72 69 6e 74 66 28 64 62 2c 0a 20 20 22 49  _printf(db,.  "I
8db0: 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
8dc0: 31 20 56 41 4c 55 45 53 28 27 25 73 27 29 22 2c  1 VALUES('%s')",
8dd0: 0a 20 20 30 2c 20 30 2c 20 30 2c 20 7a 53 74 72  .  0, 0, 0, zStr
8de0: 69 6e 67 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c  ing);.</pre></bl
8df0: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 49 66  ockquote>..<p>If
8e00: 20 74 68 65 20 7a 53 74 72 69 6e 67 20 76 61 72   the zString var
8e10: 69 61 62 6c 65 20 68 6f 6c 64 73 20 74 65 78 74  iable holds text
8e20: 20 6c 69 6b 65 20 22 48 65 6c 6c 6f 22 2c 20 74   like "Hello", t
8e30: 68 65 6e 20 74 68 69 73 20 73 74 61 74 65 6d 65  hen this stateme
8e40: 6e 74 0a 77 69 6c 6c 20 77 6f 72 6b 20 6a 75 73  nt.will work jus
8e50: 74 20 66 69 6e 65 2e 20 20 42 75 74 20 73 75 70  t fine.  But sup
8e60: 70 6f 73 65 20 74 68 65 20 75 73 65 72 20 65 6e  pose the user en
8e70: 74 65 72 73 20 61 20 73 74 72 69 6e 67 20 6c 69  ters a string li
8e80: 6b 65 20 0a 22 48 69 20 79 27 61 6c 6c 21 22 2e  ke ."Hi y'all!".
8e90: 20 20 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d    The SQL statem
8ea0: 65 6e 74 20 67 65 6e 65 72 61 74 65 64 20 72 65  ent generated re
8eb0: 61 64 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ads as follows:.
8ec0: 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72  .<blockquote><pr
8ed0: 65 3e 0a 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  e>.INSERT INTO t
8ee0: 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 48 69  able1 VALUES('Hi
8ef0: 20 79 27 61 6c 6c 27 29 0a 3c 2f 70 72 65 3e 3c   y'all').</pre><
8f00: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70  /blockquote>..<p
8f10: 3e 54 68 69 73 20 69 73 20 6e 6f 74 20 76 61 6c  >This is not val
8f20: 69 64 20 53 51 4c 20 62 65 63 61 75 73 65 20 6f  id SQL because o
8f30: 66 20 74 68 65 20 61 70 6f 73 74 72 6f 70 68 79  f the apostrophy
8f40: 20 69 6e 20 74 68 65 20 77 6f 72 64 20 22 79 27   in the word "y'
8f50: 61 6c 6c 22 2e 0a 42 75 74 20 69 66 20 74 68 65  all"..But if the
8f60: 20 25 71 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f   %q formatting o
8f70: 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 69 6e  ption is used in
8f80: 73 74 65 61 64 20 6f 66 20 25 73 2c 20 6c 69 6b  stead of %s, lik
8f90: 65 20 74 68 69 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c  e this:</p>..<bl
8fa0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 73  ockquote><pre>.s
8fb0: 71 6c 69 74 65 5f 65 78 65 63 5f 70 72 69 6e 74  qlite_exec_print
8fc0: 66 28 64 62 2c 0a 20 20 22 49 4e 53 45 52 54 20  f(db,.  "INSERT 
8fd0: 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
8fe0: 45 53 28 27 25 71 27 29 22 2c 0a 20 20 30 2c 20  ES('%q')",.  0, 
8ff0: 30 2c 20 30 2c 20 7a 53 74 72 69 6e 67 29 3b 0a  0, 0, zString);.
9000: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
9010: 74 65 3e 0a 0a 3c 70 3e 54 68 65 6e 20 74 68 65  te>..<p>Then the
9020: 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 20 77   generated SQL w
9030: 69 6c 6c 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68  ill look like th
9040: 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a 3c 2f 70 3e  e following:</p>
9050: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  ..<blockquote><p
9060: 72 65 3e 0a 49 4e 53 45 52 54 20 49 4e 54 4f 20  re>.INSERT INTO 
9070: 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 48  table1 VALUES('H
9080: 69 20 79 27 27 61 6c 6c 27 29 0a 3c 2f 70 72 65  i y''all').</pre
9090: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  ></blockquote>..
90a0: 3c 70 3e 48 65 72 65 20 74 68 65 20 61 70 6f 73  <p>Here the apos
90b0: 74 72 6f 70 68 79 20 68 61 73 20 62 65 65 6e 20  trophy has been 
90c0: 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
90d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
90e0: 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 2e 0a 57 68   well-formed..Wh
90f0: 65 6e 20 67 65 6e 65 72 61 74 69 6e 67 20 53 51  en generating SQ
9100: 4c 20 6f 6e 2d 74 68 65 2d 66 6c 79 20 66 72 6f  L on-the-fly fro
9110: 6d 20 64 61 74 61 20 74 68 61 74 20 6d 69 67 68  m data that migh
9120: 74 20 63 6f 6e 74 61 69 6e 20 61 0a 73 69 6e 67  t contain a.sing
9130: 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74  le-quote charact
9140: 65 72 20 28 27 29 2c 20 69 74 20 69 73 20 61 6c  er ('), it is al
9150: 77 61 79 73 20 61 20 67 6f 6f 64 20 69 64 65 61  ways a good idea
9160: 20 74 6f 20 75 73 65 20 74 68 65 0a 53 51 4c 69   to use the.SQLi
9170: 74 65 20 70 72 69 6e 74 66 20 72 6f 75 74 69 6e  te printf routin
9180: 65 73 20 61 6e 64 20 74 68 65 20 25 71 20 66 6f  es and the %q fo
9190: 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
91a0: 69 6e 73 74 65 61 64 20 6f 66 20 3c 62 3e 73 70  instead of <b>sp
91b0: 72 69 6e 74 66 3c 2f 62 3e 2e 0a 3c 2f 70 3e 0a  rintf</b>..</p>.
91c0: 0a 3c 70 3e 49 66 20 74 68 65 20 25 51 20 66 6f  .<p>If the %Q fo
91d0: 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
91e0: 69 73 20 75 73 65 64 20 69 6e 73 74 65 61 64 20  is used instead 
91f0: 6f 66 20 25 71 2c 20 6c 69 6b 65 20 74 68 69 73  of %q, like this
9200: 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  :</p>..<blockquo
9210: 74 65 3e 3c 70 72 65 3e 0a 73 71 6c 69 74 65 5f  te><pre>.sqlite_
9220: 65 78 65 63 5f 70 72 69 6e 74 66 28 64 62 2c 0a  exec_printf(db,.
9230: 20 20 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74    "INSERT INTO t
9240: 61 62 6c 65 31 20 56 41 4c 55 45 53 28 25 51 29  able1 VALUES(%Q)
9250: 22 2c 0a 20 20 30 2c 20 30 2c 20 30 2c 20 7a 53  ",.  0, 0, 0, zS
9260: 74 72 69 6e 67 29 3b 0a 3c 2f 70 72 65 3e 3c 2f  tring);.</pre></
9270: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e  blockquote>..<p>
9280: 54 68 65 6e 20 74 68 65 20 67 65 6e 65 72 61 74  Then the generat
9290: 65 64 20 53 51 4c 20 77 69 6c 6c 20 6c 6f 6f 6b  ed SQL will look
92a0: 20 6c 69 6b 65 20 74 68 65 20 66 6f 6c 6c 6f 77   like the follow
92b0: 69 6e 67 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b  ing:</p>..<block
92c0: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 49 4e 53 45  quote><pre>.INSE
92d0: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
92e0: 41 4c 55 45 53 28 27 48 69 20 79 27 27 61 6c 6c  ALUES('Hi y''all
92f0: 27 29 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ').</pre></block
9300: 71 75 6f 74 65 3e 0a 0a 3c 70 3e 49 66 20 74 68  quote>..<p>If th
9310: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 7a  e value of the z
9320: 53 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  String variable 
9330: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 67 65 6e  is NULL, the gen
9340: 65 72 61 74 65 64 20 53 51 4c 0a 77 69 6c 6c 20  erated SQL.will 
9350: 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 65 20 66 6f  look like the fo
9360: 6c 6c 6f 77 69 6e 67 3a 3c 2f 70 3e 0a 0a 3c 62  llowing:</p>..<b
9370: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
9380: 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
9390: 65 31 20 56 41 4c 55 45 53 28 4e 55 4c 4c 29 0a  e1 VALUES(NULL).
93a0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
93b0: 74 65 3e 0a 0a 3c 70 3e 41 6c 6c 20 6f 66 20 74  te>..<p>All of t
93c0: 68 65 20 5f 70 72 69 6e 74 66 28 29 20 72 6f 75  he _printf() rou
93d0: 74 69 6e 65 73 20 61 62 6f 76 65 20 61 72 65 20  tines above are 
93e0: 62 75 69 6c 74 20 61 72 6f 75 6e 64 20 74 68 65  built around the
93f0: 20 66 6f 6c 6c 6f 77 69 6e 67 0a 74 77 6f 20 66   following.two f
9400: 75 6e 63 74 69 6f 6e 73 3a 3c 2f 70 3e 0a 0a 3c  unctions:</p>..<
9410: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
9420: 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 5f 6d 70  .char *sqlite_mp
9430: 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
9440: 20 2a 7a 46 6f 72 6d 61 74 2c 20 2e 2e 2e 29 3b   *zFormat, ...);
9450: 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 5f 76 6d  .char *sqlite_vm
9460: 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
9470: 72 20 2a 7a 46 6f 72 6d 61 74 2c 20 76 61 5f 6c  r *zFormat, va_l
9480: 69 73 74 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c  ist);.</pre></bl
9490: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68  ockquote>..<p>Th
94a0: 65 20 3c 62 3e 73 71 6c 69 74 65 5f 6d 70 72 69  e <b>sqlite_mpri
94b0: 6e 74 66 28 29 3c 2f 62 3e 20 72 6f 75 74 69 6e  ntf()</b> routin
94c0: 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 74 68 65  e works like the
94d0: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69   the standard li
94e0: 62 72 61 72 79 0a 3c 62 3e 73 70 72 69 6e 74 66  brary.<b>sprintf
94f0: 28 29 3c 2f 62 3e 20 65 78 63 65 70 74 20 74 68  ()</b> except th
9500: 61 74 20 69 74 20 77 72 69 74 65 73 20 69 74 73  at it writes its
9510: 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
9520: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 66 72  mory obtained.fr
9530: 6f 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  om malloc() and 
9540: 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
9550: 72 20 74 6f 20 74 68 65 20 6d 61 6c 6c 6f 63 65  r to the malloce
9560: 64 20 62 75 66 66 65 72 2e 20 20 0a 3c 62 3e 73  d buffer.  .<b>s
9570: 71 6c 69 74 65 5f 6d 70 72 69 6e 74 66 28 29 3c  qlite_mprintf()<
9580: 2f 62 3e 20 61 6c 73 6f 20 75 6e 64 65 72 73 74  /b> also underst
9590: 61 6e 64 73 20 74 68 65 20 25 71 20 61 6e 64 20  ands the %q and 
95a0: 25 51 20 65 78 74 65 6e 73 69 6f 6e 73 20 64 65  %Q extensions de
95b0: 73 63 72 69 62 65 64 0a 61 62 6f 76 65 2e 20 20  scribed.above.  
95c0: 54 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 76 6d  The <b>sqlite_vm
95d0: 70 72 69 6e 74 66 28 29 3c 2f 62 3e 20 69 73 20  printf()</b> is 
95e0: 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
95f0: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 72 6f  n of the same.ro
9600: 75 74 69 6e 65 2e 20 20 54 68 65 20 73 74 72 69  utine.  The stri
9610: 6e 67 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ng pointer that 
9620: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  these routines r
9630: 65 74 75 72 6e 20 73 68 6f 75 6c 64 20 62 65 20  eturn should be 
9640: 66 72 65 65 64 0a 62 79 20 70 61 73 73 69 6e 67  freed.by passing
9650: 20 69 74 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65   it to <b>sqlite
9660: 5f 66 72 65 65 6d 65 6d 28 29 3c 2f 62 3e 2e 0a  _freemem()</b>..
9670: 3c 2f 70 3e 0a 0a 3c 68 33 3e 33 2e 31 30 20 50  </p>..<h3>3.10 P
9680: 65 72 66 6f 72 6d 69 6e 67 20 62 61 63 6b 67 72  erforming backgr
9690: 6f 75 6e 64 20 6a 6f 62 73 20 64 75 72 69 6e 67  ound jobs during
96a0: 20 6c 61 72 67 65 20 71 75 65 72 69 65 73 20 3c   large queries <
96b0: 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65 20 3c 62 3e  /h2>..<p>The <b>
96c0: 73 71 6c 69 74 65 5f 70 72 6f 67 72 65 73 73 5f  sqlite_progress_
96d0: 68 61 6e 64 6c 65 72 28 29 3c 2f 62 3e 20 72 6f  handler()</b> ro
96e0: 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
96f0: 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 0a  d to register a.
9700: 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
9710: 20 77 69 74 68 20 61 6e 20 53 51 4c 69 74 65 20   with an SQLite 
9720: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 69  database to be i
9730: 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
9740: 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a  lly during long.
9750: 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
9760: 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 28   <b>sqlite_exec(
9770: 29 3c 2f 62 3e 2c 20 3c 62 3e 73 71 6c 69 74 65  )</b>, <b>sqlite
9780: 5f 73 74 65 70 28 29 3c 2f 62 3e 20 61 6e 64 20  _step()</b> and 
9790: 74 68 65 20 76 61 72 69 6f 75 73 0a 77 72 61 70  the various.wrap
97a0: 70 65 72 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 3c  per functions..<
97b0: 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 63 61 6c 6c  /p>..<p>The call
97c0: 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
97d0: 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c 20  every N virtual 
97e0: 6d 61 63 68 69 6e 65 20 6f 70 65 72 61 74 69 6f  machine operatio
97f0: 6e 73 2c 20 77 68 65 72 65 20 4e 20 69 73 0a 73  ns, where N is.s
9800: 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
9810: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
9820: 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 70 72 6f 67  o <b>sqlite_prog
9830: 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 3c 2f  ress_handler()</
9840: 62 3e 2e 20 54 68 65 20 74 68 69 72 64 0a 61 6e  b>. The third.an
9850: 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  d fourth argumen
9860: 74 73 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f  ts to <b>sqlite_
9870: 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
9880: 28 29 3c 2f 62 3e 20 61 72 65 20 61 20 70 6f 69  ()</b> are a poi
9890: 6e 74 65 72 20 74 6f 20 74 68 65 0a 72 6f 75 74  nter to the.rout
98a0: 69 6e 65 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ine to be invoke
98b0: 64 20 61 6e 64 20 61 20 76 6f 69 64 20 70 6f 69  d and a void poi
98c0: 6e 74 65 72 20 74 6f 20 62 65 20 70 61 73 73 65  nter to be passe
98d0: 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
98e0: 72 67 75 6d 65 6e 74 20 74 6f 0a 69 74 2e 0a 3c  rgument to.it..<
98f0: 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 74 69 6d 65  /p>..<p>The time
9900: 20 74 61 6b 65 6e 20 74 6f 20 65 78 65 63 75 74   taken to execut
9910: 65 20 65 61 63 68 20 76 69 72 74 75 61 6c 20 6d  e each virtual m
9920: 61 63 68 69 6e 65 20 6f 70 65 72 61 74 69 6f 6e  achine operation
9930: 20 63 61 6e 20 76 61 72 79 20 62 61 73 65 64 20   can vary based 
9940: 6f 6e 0a 6d 61 6e 79 20 66 61 63 74 6f 72 73 2e  on.many factors.
9950: 20 20 41 20 74 79 70 69 63 61 6c 20 76 61 6c 75    A typical valu
9960: 65 20 66 6f 72 20 61 20 31 20 47 48 7a 20 50 43  e for a 1 GHz PC
9970: 20 69 73 20 62 65 74 77 65 65 6e 20 68 61 6c 66   is between half
9980: 20 61 6e 64 20 74 68 72 65 65 20 6d 69 6c 6c 69   and three milli
9990: 6f 6e 0a 70 65 72 20 73 65 63 6f 6e 64 20 62 75  on.per second bu
99a0: 74 20 6d 61 79 20 62 65 20 6d 75 63 68 20 68 69  t may be much hi
99b0: 67 68 65 72 20 6f 72 20 6c 6f 77 65 72 2c 20 64  gher or lower, d
99c0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
99d0: 71 75 65 72 79 2e 20 20 41 73 20 73 75 63 68 20  query.  As such 
99e0: 69 74 0a 69 73 20 64 69 66 66 69 63 75 6c 74 20  it.is difficult 
99f0: 74 6f 20 73 63 68 65 64 75 6c 65 20 62 61 63 6b  to schedule back
9a00: 67 72 6f 75 6e 64 20 6f 70 65 72 61 74 69 6f 6e  ground operation
9a10: 73 20 62 61 73 65 64 20 6f 6e 20 76 69 72 74 75  s based on virtu
9a20: 61 6c 20 6d 61 63 68 69 6e 65 0a 6f 70 65 72 61  al machine.opera
9a30: 74 69 6f 6e 73 2e 20 49 6e 73 74 65 61 64 2c 20  tions. Instead, 
9a40: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
9a50: 64 20 74 68 61 74 20 61 20 63 61 6c 6c 62 61 63  d that a callbac
9a60: 6b 20 62 65 20 73 63 68 65 64 75 6c 65 64 20 72  k be scheduled r
9a70: 65 6c 61 74 69 76 65 6c 79 0a 66 72 65 71 75 65  elatively.freque
9a80: 6e 74 6c 79 20 28 73 61 79 20 65 76 65 72 79 20  ntly (say every 
9a90: 31 30 30 30 20 69 6e 73 74 72 75 63 74 69 6f 6e  1000 instruction
9aa0: 73 29 20 61 6e 64 20 65 78 74 65 72 6e 61 6c 20  s) and external 
9ab0: 74 69 6d 65 72 20 72 6f 75 74 69 6e 65 73 20 75  timer routines u
9ac0: 73 65 64 20 74 6f 0a 64 65 74 65 72 6d 69 6e 65  sed to.determine
9ad0: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
9ae0: 62 61 63 6b 67 72 6f 75 6e 64 20 6a 6f 62 73 20  background jobs 
9af0: 6e 65 65 64 20 74 6f 20 62 65 20 72 75 6e 2e 20  need to be run. 
9b00: 20 0a 3c 2f 70 3e 0a 0a 3c 61 20 6e 61 6d 65 3d   .</p>..<a name=
9b10: 22 63 66 75 6e 63 22 3e 0a 3c 68 32 3e 34 2e 30  "cfunc">.<h2>4.0
9b20: 20 41 64 64 69 6e 67 20 4e 65 77 20 53 51 4c 20   Adding New SQL 
9b30: 46 75 6e 63 74 69 6f 6e 73 3c 2f 68 32 3e 0a 0a  Functions</h2>..
9b40: 3c 70 3e 42 65 67 69 6e 6e 69 6e 67 20 77 69 74  <p>Beginning wit
9b50: 68 20 76 65 72 73 69 6f 6e 20 32 2e 34 2e 30 2c  h version 2.4.0,
9b60: 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 73 20 74   SQLite allows t
9b70: 68 65 20 53 51 4c 20 6c 61 6e 67 75 61 67 65 20  he SQL language 
9b80: 74 6f 20 62 65 0a 65 78 74 65 6e 64 65 64 20 77  to be.extended w
9b90: 69 74 68 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  ith new function
9ba0: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
9bb0: 20 43 20 63 6f 64 65 2e 20 20 54 68 65 20 66 6f   C code.  The fo
9bc0: 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63  llowing interfac
9bd0: 65 0a 69 73 20 75 73 65 64 3a 0a 3c 2f 70 3e 0a  e.is used:.</p>.
9be0: 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72  .<blockquote><pr
9bf0: 65 3e 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  e>.typedef struc
9c00: 74 20 73 71 6c 69 74 65 5f 66 75 6e 63 20 73 71  t sqlite_func sq
9c10: 6c 69 74 65 5f 66 75 6e 63 3b 0a 0a 69 6e 74 20  lite_func;..int 
9c20: 73 71 6c 69 74 65 5f 63 72 65 61 74 65 5f 66 75  sqlite_create_fu
9c30: 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
9c40: 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
9c50: 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74  ar *zName,.  int
9c60: 20 6e 41 72 67 2c 0a 20 20 76 6f 69 64 20 28 2a   nArg,.  void (*
9c70: 78 46 75 6e 63 29 28 73 71 6c 69 74 65 5f 66 75  xFunc)(sqlite_fu
9c80: 6e 63 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  nc*,int,const ch
9c90: 61 72 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  ar**),.  void *p
9ca0: 55 73 65 72 44 61 74 61 0a 29 3b 0a 69 6e 74 20  UserData.);.int 
9cb0: 73 71 6c 69 74 65 5f 63 72 65 61 74 65 5f 61 67  sqlite_create_ag
9cc0: 67 72 65 67 61 74 65 28 0a 20 20 73 71 6c 69 74  gregate(.  sqlit
9cd0: 65 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  e *db,.  const c
9ce0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e  har *zName,.  in
9cf0: 74 20 6e 41 72 67 2c 0a 20 20 76 6f 69 64 20 28  t nArg,.  void (
9d00: 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 5f 66  *xStep)(sqlite_f
9d10: 75 6e 63 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  unc*,int,const c
9d20: 68 61 72 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  har**),.  void (
9d30: 2a 78 46 69 6e 61 6c 69 7a 65 29 28 73 71 6c 69  *xFinalize)(sqli
9d40: 74 65 5f 66 75 6e 63 2a 29 2c 0a 20 20 76 6f 69  te_func*),.  voi
9d50: 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
9d60: 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 5f 73 65  .char *sqlite_se
9d70: 74 5f 72 65 73 75 6c 74 5f 73 74 72 69 6e 67 28  t_result_string(
9d80: 73 71 6c 69 74 65 5f 66 75 6e 63 2a 2c 63 6f 6e  sqlite_func*,con
9d90: 73 74 20 63 68 61 72 2a 2c 69 6e 74 29 3b 0a 76  st char*,int);.v
9da0: 6f 69 64 20 73 71 6c 69 74 65 5f 73 65 74 5f 72  oid sqlite_set_r
9db0: 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
9dc0: 5f 66 75 6e 63 2a 2c 69 6e 74 29 3b 0a 76 6f 69  _func*,int);.voi
9dd0: 64 20 73 71 6c 69 74 65 5f 73 65 74 5f 72 65 73  d sqlite_set_res
9de0: 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
9df0: 65 5f 66 75 6e 63 2a 2c 64 6f 75 62 6c 65 29 3b  e_func*,double);
9e00: 0a 76 6f 69 64 20 73 71 6c 69 74 65 5f 73 65 74  .void sqlite_set
9e10: 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
9e20: 6c 69 74 65 5f 66 75 6e 63 2a 2c 63 6f 6e 73 74  lite_func*,const
9e30: 20 63 68 61 72 2a 2c 69 6e 74 29 3b 0a 0a 76 6f   char*,int);..vo
9e40: 69 64 20 2a 73 71 6c 69 74 65 5f 75 73 65 72 5f  id *sqlite_user_
9e50: 64 61 74 61 28 73 71 6c 69 74 65 5f 66 75 6e 63  data(sqlite_func
9e60: 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
9e70: 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
9e80: 78 74 28 73 71 6c 69 74 65 5f 66 75 6e 63 2a 2c  xt(sqlite_func*,
9e90: 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 69 6e   int nBytes);.in
9ea0: 74 20 73 71 6c 69 74 65 5f 61 67 67 72 65 67 61  t sqlite_aggrega
9eb0: 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 5f  te_count(sqlite_
9ec0: 66 75 6e 63 2a 29 3b 0a 3c 2f 70 72 65 3e 3c 2f  func*);.</pre></
9ed0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e  blockquote>..<p>
9ee0: 0a 54 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 63  .The <b>sqlite_c
9ef0: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
9f00: 3c 2f 62 3e 20 69 6e 74 65 72 66 61 63 65 20 69  </b> interface i
9f10: 73 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  s used to create
9f20: 20 0a 72 65 67 75 6c 61 72 20 66 75 6e 63 74 69   .regular functi
9f30: 6f 6e 73 20 61 6e 64 20 3c 62 3e 73 71 6c 69 74  ons and <b>sqlit
9f40: 65 5f 63 72 65 61 74 65 5f 61 67 67 72 65 67 61  e_create_aggrega
9f50: 74 65 28 29 3c 2f 62 3e 20 69 73 20 75 73 65 64  te()</b> is used
9f60: 20 74 6f 0a 63 72 65 61 74 65 20 6e 65 77 20 61   to.create new a
9f70: 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
9f80: 6e 73 2e 20 20 49 6e 20 62 6f 74 68 20 63 61 73  ns.  In both cas
9f90: 65 73 2c 20 74 68 65 20 3c 62 3e 64 62 3c 2f 62  es, the <b>db</b
9fa0: 3e 0a 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  >.parameter is a
9fb0: 6e 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61  n open SQLite da
9fc0: 74 61 62 61 73 65 20 6f 6e 20 77 68 69 63 68 20  tabase on which 
9fd0: 74 68 65 20 66 75 6e 63 74 69 6f 6e 73 20 73 68  the functions sh
9fe0: 6f 75 6c 64 0a 62 65 20 72 65 67 69 73 74 65 72  ould.be register
9ff0: 65 64 2c 20 3c 62 3e 7a 4e 61 6d 65 3c 2f 62 3e  ed, <b>zName</b>
a000: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
a010: 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  the new function
a020: 2c 0a 3c 62 3e 6e 41 72 67 3c 2f 62 3e 20 69 73  ,.<b>nArg</b> is
a030: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
a040: 72 67 75 6d 65 6e 74 73 2c 20 61 6e 64 20 3c 62  rguments, and <b
a050: 3e 70 55 73 65 72 44 61 74 61 3c 2f 62 3e 20 69  >pUserData</b> i
a060: 73 0a 61 20 70 6f 69 6e 74 65 72 20 77 68 69 63  s.a pointer whic
a070: 68 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  h is passed thro
a080: 75 67 68 20 75 6e 63 68 61 6e 67 65 64 20 74 6f  ugh unchanged to
a090: 20 74 68 65 20 43 20 69 6d 70 6c 65 6d 65 6e 74   the C implement
a0a0: 61 74 69 6f 6e 0a 6f 66 20 74 68 65 20 66 75 6e  ation.of the fun
a0b0: 63 74 69 6f 6e 2e 20 20 42 6f 74 68 20 72 6f 75  ction.  Both rou
a0c0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 6f  tines return 0 o
a0d0: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 6e 6f  n success and no
a0e0: 6e 2d 7a 65 72 6f 0a 69 66 20 74 68 65 72 65 20  n-zero.if there 
a0f0: 61 72 65 20 61 6e 79 20 65 72 72 6f 72 73 2e 0a  are any errors..
a100: 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 6c 65  </p>..<p>.The le
a110: 6e 67 74 68 20 6f 66 20 61 20 66 75 6e 63 74 69  ngth of a functi
a120: 6f 6e 20 6e 61 6d 65 20 6d 61 79 20 6e 6f 74 20  on name may not 
a130: 65 78 63 65 65 64 20 32 35 35 20 63 68 61 72 61  exceed 255 chara
a140: 63 74 65 72 73 2e 0a 41 6e 79 20 61 74 74 65 6d  cters..Any attem
a150: 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
a160: 75 6e 63 74 69 6f 6e 20 77 68 6f 73 65 20 6e 61  unction whose na
a170: 6d 65 20 65 78 63 65 65 64 73 20 32 35 35 20 63  me exceeds 255 c
a180: 68 61 72 61 63 74 65 72 73 0a 69 6e 20 6c 65 6e  haracters.in len
a190: 67 74 68 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  gth will result 
a1a0: 69 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 3c 2f 70  in an error..</p
a1b0: 3e 0a 0a 3c 70 3e 0a 46 6f 72 20 72 65 67 75 6c  >..<p>.For regul
a1c0: 61 72 20 66 75 6e 63 74 69 6f 6e 73 2c 20 74 68  ar functions, th
a1d0: 65 20 3c 62 3e 78 46 75 6e 63 3c 2f 62 3e 20 63  e <b>xFunc</b> c
a1e0: 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
a1f0: 65 64 20 6f 6e 63 65 0a 66 6f 72 20 65 61 63 68  ed once.for each
a200: 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 2e 20   function call. 
a210: 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
a220: 69 6f 6e 20 6f 66 20 78 46 75 6e 63 20 73 68 6f  ion of xFunc sho
a230: 75 6c 64 20 63 61 6c 6c 0a 6f 6e 65 20 6f 66 20  uld call.one of 
a240: 74 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 73 65  the <b>sqlite_se
a250: 74 5f 72 65 73 75 6c 74 5f 2e 2e 2e 3c 2f 62 3e  t_result_...</b>
a260: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 72   interfaces to r
a270: 65 74 75 72 6e 20 69 74 73 0a 72 65 73 75 6c 74  eturn its.result
a280: 2e 20 20 54 68 65 20 3c 62 3e 73 71 6c 69 74 65  .  The <b>sqlite
a290: 5f 75 73 65 72 5f 64 61 74 61 28 29 3c 2f 62 3e  _user_data()</b>
a2a0: 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
a2b0: 75 73 65 64 20 74 6f 0a 72 65 74 72 69 65 76 65  used to.retrieve
a2c0: 20 74 68 65 20 3c 62 3e 70 55 73 65 72 44 61 74   the <b>pUserDat
a2d0: 61 3c 2f 62 3e 20 70 6f 69 6e 74 65 72 20 74 68  a</b> pointer th
a2e0: 61 74 20 77 61 73 20 70 61 73 73 65 64 20 69 6e  at was passed in
a2f0: 20 77 68 65 6e 20 74 68 65 0a 66 75 6e 63 74 69   when the.functi
a300: 6f 6e 20 77 61 73 20 72 65 67 69 73 74 65 72 65  on was registere
a310: 64 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 46 6f 72  d..</p>..<p>.For
a320: 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
a330: 69 6f 6e 73 2c 20 74 68 65 20 3c 62 3e 78 53 74  ions, the <b>xSt
a340: 65 70 3c 2f 62 3e 20 63 61 6c 6c 62 61 63 6b 20  ep</b> callback 
a350: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 0a  is invoked once.
a360: 66 6f 72 20 65 61 63 68 20 72 6f 77 20 69 6e 20  for each row in 
a370: 74 68 65 20 72 65 73 75 6c 74 20 61 6e 64 20 74  the result and t
a380: 68 65 6e 20 3c 62 3e 78 46 69 6e 61 6c 69 7a 65  hen <b>xFinalize
a390: 3c 2f 62 3e 20 69 73 20 69 6e 76 6f 6b 65 64 20  </b> is invoked 
a3a0: 61 74 20 74 68 65 0a 65 6e 64 20 74 6f 20 63 6f  at the.end to co
a3b0: 6d 70 75 74 65 20 61 20 66 69 6e 61 6c 20 61 6e  mpute a final an
a3c0: 73 77 65 72 2e 20 20 54 68 65 20 78 53 74 65 70  swer.  The xStep
a3d0: 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 75 73 65   routine can use
a3e0: 20 74 68 65 0a 3c 62 3e 73 71 6c 69 74 65 5f 61   the.<b>sqlite_a
a3f0: 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
a400: 28 29 3c 2f 62 3e 20 69 6e 74 65 72 66 61 63 65  ()</b> interface
a410: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
a420: 6f 72 79 20 74 68 61 74 0a 77 69 6c 6c 20 62 65  ory that.will be
a430: 20 75 6e 69 71 75 65 20 74 6f 20 74 68 61 74 20   unique to that 
a440: 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61  particular insta
a450: 6e 63 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  nce of the SQL f
a460: 75 6e 63 74 69 6f 6e 2e 0a 54 68 69 73 20 6d 65  unction..This me
a470: 6d 6f 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74  mory will be aut
a480: 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
a490: 65 64 20 61 66 74 65 72 20 78 46 69 6e 61 6c 69  ed after xFinali
a4a0: 7a 65 20 69 73 20 63 61 6c 6c 65 64 2e 0a 54 68  ze is called..Th
a4b0: 65 20 3c 62 3e 73 71 6c 69 74 65 5f 61 67 67 72  e <b>sqlite_aggr
a4c0: 65 67 61 74 65 5f 63 6f 75 6e 74 28 29 3c 2f 62  egate_count()</b
a4d0: 3e 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  > routine can be
a4e0: 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 6f 75   used to find ou
a4f0: 74 0a 68 6f 77 20 6d 61 6e 79 20 72 6f 77 73 20  t.how many rows 
a500: 6f 66 20 64 61 74 61 20 77 65 72 65 20 70 61 73  of data were pas
a510: 73 65 64 20 74 6f 20 74 68 65 20 61 67 67 72 65  sed to the aggre
a520: 67 61 74 65 2e 20 20 54 68 65 20 78 46 69 6e 61  gate.  The xFina
a530: 6c 69 7a 65 0a 63 61 6c 6c 62 61 63 6b 20 73 68  lize.callback sh
a540: 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 6f 6e 65 20  ould invoke one 
a550: 6f 66 20 74 68 65 20 3c 62 3e 73 71 6c 69 74 65  of the <b>sqlite
a560: 5f 73 65 74 5f 72 65 73 75 6c 74 5f 2e 2e 2e 3c  _set_result_...<
a570: 2f 62 3e 0a 69 6e 74 65 72 66 61 63 65 73 20 74  /b>.interfaces t
a580: 6f 20 73 65 74 20 74 68 65 20 66 69 6e 61 6c 20  o set the final 
a590: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 61 67  result of the ag
a5a0: 67 72 65 67 61 74 65 2e 0a 3c 2f 70 3e 0a 0a 3c  gregate..</p>..<
a5b0: 70 3e 0a 53 51 4c 69 74 65 20 6e 6f 77 20 69 6d  p>.SQLite now im
a5c0: 70 6c 65 6d 65 6e 74 73 20 61 6c 6c 20 6f 66 20  plements all of 
a5d0: 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e  its built-in fun
a5e0: 63 74 69 6f 6e 73 20 75 73 69 6e 67 20 74 68 69  ctions using thi
a5f0: 73 0a 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  s.interface.  Fo
a600: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
a610: 6f 72 6d 61 74 69 6f 6e 20 61 6e 64 20 65 78 61  ormation and exa
a620: 6d 70 6c 65 73 20 6f 6e 20 68 6f 77 20 74 6f 20  mples on how to 
a630: 63 72 65 61 74 65 0a 6e 65 77 20 53 51 4c 20 66  create.new SQL f
a640: 75 6e 63 74 69 6f 6e 73 2c 20 72 65 76 69 65 77  unctions, review
a650: 20 74 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72   the SQLite sour
a660: 63 65 20 63 6f 64 65 20 69 6e 20 74 68 65 20 66  ce code in the f
a670: 69 6c 65 0a 3c 62 3e 66 75 6e 63 2e 63 3c 2f 62  ile.<b>func.c</b
a680: 3e 2e 0a 3c 2f 70 3e 0a 0a 3c 68 32 3e 35 2e 30  >..</p>..<h2>5.0
a690: 20 4d 75 6c 74 69 2d 54 68 72 65 61 64 69 6e 67   Multi-Threading
a6a0: 20 41 6e 64 20 53 51 4c 69 74 65 3c 2f 68 32 3e   And SQLite</h2>
a6b0: 0a 0a 3c 70 3e 0a 49 66 20 53 51 4c 69 74 65 20  ..<p>.If SQLite 
a6c0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
a6d0: 20 74 68 65 20 54 48 52 45 41 44 53 41 46 45 20   the THREADSAFE 
a6e0: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
a6f0: 72 6f 20 73 65 74 20 74 6f 20 31 2c 0a 74 68 65  ro set to 1,.the
a700: 6e 20 69 74 20 69 73 20 73 61 66 65 20 74 6f 20  n it is safe to 
a710: 75 73 65 20 53 51 4c 69 74 65 20 66 72 6f 6d 20  use SQLite from 
a720: 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
a730: 61 64 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ads of the same 
a740: 70 72 6f 63 65 73 73 0a 61 74 20 74 68 65 20 73  process.at the s
a750: 61 6d 65 20 74 69 6d 65 2e 20 20 42 75 74 20 65  ame time.  But e
a760: 61 63 68 20 74 68 72 65 61 64 20 73 68 6f 75 6c  ach thread shoul
a770: 64 20 68 61 76 65 20 69 74 73 20 6f 77 6e 20 3c  d have its own <
a780: 62 3e 73 71 6c 69 74 65 2a 3c 2f 62 3e 0a 70 6f  b>sqlite*</b>.po
a790: 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 20 66  inter returned f
a7a0: 72 6f 6d 20 3c 62 3e 73 71 6c 69 74 65 5f 6f 70  rom <b>sqlite_op
a7b0: 65 6e 3c 2f 62 3e 2e 20 20 49 74 20 69 73 20 6e  en</b>.  It is n
a7c0: 65 76 65 72 20 73 61 66 65 20 66 6f 72 20 74 77  ever safe for tw
a7d0: 6f 0a 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o.or more thread
a7e0: 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
a7f0: 73 61 6d 65 20 3c 62 3e 73 71 6c 69 74 65 2a 3c  same <b>sqlite*<
a800: 2f 62 3e 20 70 6f 69 6e 74 65 72 20 61 74 20 74  /b> pointer at t
a810: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 3c 2f  he same time..</
a820: 70 3e 0a 0a 3c 70 3e 0a 49 6e 20 70 72 65 63 6f  p>..<p>.In preco
a830: 6d 70 69 6c 65 64 20 53 51 4c 69 74 65 20 6c 69  mpiled SQLite li
a840: 62 72 61 72 69 65 73 20 61 76 61 69 6c 61 62 6c  braries availabl
a850: 65 20 6f 6e 20 74 68 65 20 77 65 62 73 69 74 65  e on the website
a860: 2c 20 74 68 65 20 55 6e 69 78 0a 76 65 72 73 69  , the Unix.versi
a870: 6f 6e 73 20 61 72 65 20 63 6f 6d 70 69 6c 65 64  ons are compiled
a880: 20 77 69 74 68 20 54 48 52 45 41 44 53 41 46 45   with THREADSAFE
a890: 20 74 75 72 6e 65 64 20 6f 66 66 20 62 75 74 20   turned off but 
a8a0: 74 68 65 20 77 69 6e 64 6f 77 73 0a 76 65 72 73  the windows.vers
a8b0: 69 6f 6e 73 20 61 72 65 20 63 6f 6d 70 69 6c 65  ions are compile
a8c0: 64 20 77 69 74 68 20 54 48 52 45 41 44 53 41 46  d with THREADSAF
a8d0: 45 20 74 75 72 6e 65 64 20 6f 6e 2e 20 20 49 66  E turned on.  If
a8e0: 20 79 6f 75 20 6e 65 65 64 20 73 6f 6d 65 74 68   you need someth
a8f0: 69 6e 67 0a 64 69 66 66 65 72 65 6e 74 20 74 68  ing.different th
a900: 61 74 20 74 68 69 73 20 79 6f 75 20 77 69 6c 6c  at this you will
a910: 20 68 61 76 65 20 74 6f 20 72 65 63 6f 6d 70 69   have to recompi
a920: 6c 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 55 6e  le..</p>..<p>.Un
a930: 64 65 72 20 55 6e 69 78 2c 20 61 6e 20 3c 62 3e  der Unix, an <b>
a940: 73 71 6c 69 74 65 2a 3c 2f 62 3e 20 70 6f 69 6e  sqlite*</b> poin
a950: 74 65 72 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  ter should not b
a960: 65 20 63 61 72 72 69 65 64 20 61 63 72 6f 73 73  e carried across
a970: 20 61 0a 3c 62 3e 66 6f 72 6b 28 29 3c 2f 62 3e   a.<b>fork()</b>
a980: 20 73 79 73 74 65 6d 20 63 61 6c 6c 20 69 6e 74   system call int
a990: 6f 20 74 68 65 20 63 68 69 6c 64 20 70 72 6f 63  o the child proc
a9a0: 65 73 73 2e 20 20 54 68 65 20 63 68 69 6c 64 20  ess.  The child 
a9b0: 70 72 6f 63 65 73 73 0a 73 68 6f 75 6c 64 20 6f  process.should o
a9c0: 70 65 6e 20 69 74 73 20 6f 77 6e 20 63 6f 70 79  pen its own copy
a9d0: 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
a9e0: 20 61 66 74 65 72 20 74 68 65 20 3c 62 3e 66 6f   after the <b>fo
a9f0: 72 6b 28 29 3c 2f 62 3e 2e 0a 3c 2f 70 3e 0a 0a  rk()</b>..</p>..
aa00: 3c 68 32 3e 36 2e 30 20 55 73 61 67 65 20 45 78  <h2>6.0 Usage Ex
aa10: 61 6d 70 6c 65 73 3c 2f 68 32 3e 0a 0a 3c 70 3e  amples</h2>..<p>
aa20: 46 6f 72 20 65 78 61 6d 70 6c 65 73 20 6f 66 20  For examples of 
aa30: 68 6f 77 20 74 68 65 20 53 51 4c 69 74 65 20 43  how the SQLite C
aa40: 2f 43 2b 2b 20 69 6e 74 65 72 66 61 63 65 20 63  /C++ interface c
aa50: 61 6e 20 62 65 20 75 73 65 64 2c 0a 72 65 66 65  an be used,.refe
aa60: 72 20 74 6f 20 74 68 65 20 73 6f 75 72 63 65 20  r to the source 
aa70: 63 6f 64 65 20 66 6f 72 20 74 68 65 20 3c 62 3e  code for the <b>
aa80: 73 71 6c 69 74 65 3c 2f 62 3e 20 70 72 6f 67 72  sqlite</b> progr
aa90: 61 6d 20 69 6e 20 74 68 65 0a 66 69 6c 65 20 3c  am in the.file <
aaa0: 62 3e 73 72 63 2f 73 68 65 6c 6c 2e 63 3c 2f 62  b>src/shell.c</b
aab0: 3e 20 6f 66 20 74 68 65 20 73 6f 75 72 63 65 20  > of the source 
aac0: 74 72 65 65 2e 0a 41 64 64 69 74 69 6f 6e 61 6c  tree..Additional
aad0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
aae0: 75 74 20 73 71 6c 69 74 65 20 69 73 20 61 76 61  ut sqlite is ava
aaf0: 69 6c 61 62 6c 65 20 61 74 0a 3c 61 20 68 72 65  ilable at.<a hre
ab00: 66 3d 22 73 71 6c 69 74 65 2e 68 74 6d 6c 22 3e  f="sqlite.html">
ab10: 73 71 6c 69 74 65 2e 68 74 6d 6c 3c 2f 61 3e 2e  sqlite.html</a>.
ab20: 0a 53 65 65 20 61 6c 73 6f 20 74 68 65 20 73 6f  .See also the so
ab30: 75 72 63 65 73 20 74 6f 20 74 68 65 20 54 63 6c  urces to the Tcl
ab40: 20 69 6e 74 65 72 66 61 63 65 20 66 6f 72 20 53   interface for S
ab50: 51 4c 69 74 65 20 69 6e 0a 74 68 65 20 73 6f 75  QLite in.the sou
ab60: 72 63 65 20 66 69 6c 65 20 3c 62 3e 73 72 63 2f  rce file <b>src/
ab70: 74 63 6c 73 71 6c 69 74 65 2e 63 3c 2f 62 3e 2e  tclsqlite.c</b>.
ab80: 3c 2f 70 3e 0a 7d 0a 0a 70 75 74 73 20 7b 0a 3c  </p>.}..puts {.<
ab90: 70 3e 3c 68 72 20 2f 3e 3c 2f 70 3e 0a 3c 70 3e  p><hr /></p>.<p>
aba0: 3c 61 20 68 72 65 66 3d 22 69 6e 64 65 78 2e 68  <a href="index.h
abb0: 74 6d 6c 22 3e 3c 69 6d 67 20 73 72 63 3d 22 2f  tml"><img src="/
abc0: 67 6f 62 61 63 6b 2e 6a 70 67 22 20 62 6f 72 64  goback.jpg" bord
abd0: 65 72 3d 30 20 2f 3e 0a 42 61 63 6b 20 74 6f 20  er=0 />.Back to 
abe0: 74 68 65 20 53 51 4c 69 74 65 20 48 6f 6d 65 20  the SQLite Home 
abf0: 50 61 67 65 3c 2f 61 3e 0a 3c 2f 70 3e 0a 0a 3c  Page</a>.</p>..<
ac00: 2f 62 6f 64 79 3e 3c 2f 68 74 6d 6c 3e 7d 0a     /body></html>}.