/ Hex Artifact Content
Login

Artifact 83b39203e1ded4c2dab97f42edf31279a308efcb:


0000: 23 0a 23 20 52 75 6e 20 74 68 69 73 20 54 63 6c  #.# Run this Tcl
0010: 20 73 63 72 69 70 74 20 74 6f 20 67 65 6e 65 72   script to gener
0020: 61 74 65 20 74 68 65 20 73 71 6c 69 74 65 2e 68  ate the sqlite.h
0030: 74 6d 6c 20 66 69 6c 65 2e 0a 23 0a 73 65 74 20  tml file..#.set 
0040: 72 63 73 69 64 20 7b 24 49 64 3a 20 63 5f 69 6e  rcsid {$Id: c_in
0050: 74 65 72 66 61 63 65 2e 74 63 6c 2c 76 20 31 2e  terface.tcl,v 1.
0060: 34 31 20 32 30 30 34 2f 30 38 2f 33 30 20 31 34  41 2004/08/30 14
0070: 3a 35 38 3a 31 32 20 64 72 68 20 45 78 70 20 24  :58:12 drh Exp $
0080: 7d 0a 73 6f 75 72 63 65 20 63 6f 6d 6d 6f 6e 2e  }.source common.
0090: 74 63 6c 0a 68 65 61 64 65 72 20 7b 54 68 65 20  tcl.header {The 
00a0: 43 20 6c 61 6e 67 75 61 67 65 20 69 6e 74 65 72  C language inter
00b0: 66 61 63 65 20 74 6f 20 74 68 65 20 53 51 4c 69  face to the SQLi
00c0: 74 65 20 6c 69 62 72 61 72 79 7d 0a 70 75 74 73  te library}.puts
00d0: 20 7b 0a 3c 68 32 3e 54 68 65 20 43 20 6c 61 6e   {.<h2>The C lan
00e0: 67 75 61 67 65 20 69 6e 74 65 72 66 61 63 65 20  guage interface 
00f0: 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  to the SQLite li
0100: 62 72 61 72 79 3c 2f 68 32 3e 0a 0a 3c 70 3e 54  brary</h2>..<p>T
0110: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
0120: 79 20 69 73 20 64 65 73 69 67 6e 65 64 20 74 6f  y is designed to
0130: 20 62 65 20 76 65 72 79 20 65 61 73 79 20 74 6f   be very easy to
0140: 20 75 73 65 20 66 72 6f 6d 0a 61 20 43 20 6f 72   use from.a C or
0150: 20 43 2b 2b 20 70 72 6f 67 72 61 6d 2e 20 20 54   C++ program.  T
0160: 68 69 73 20 64 6f 63 75 6d 65 6e 74 20 67 69 76  his document giv
0170: 65 73 20 61 6e 20 6f 76 65 72 76 69 65 77 20 6f  es an overview o
0180: 66 20 74 68 65 20 43 2f 43 2b 2b 0a 70 72 6f 67  f the C/C++.prog
0190: 72 61 6d 6d 69 6e 67 20 69 6e 74 65 72 66 61 63  ramming interfac
01a0: 65 2e 3c 2f 70 3e 0a 0a 3c 68 33 3e 31 2e 30 20  e.</p>..<h3>1.0 
01b0: 54 68 65 20 43 6f 72 65 20 41 50 49 3c 2f 68 33  The Core API</h3
01c0: 3e 0a 0a 3c 70 3e 54 68 65 20 69 6e 74 65 72 66  >..<p>The interf
01d0: 61 63 65 20 74 6f 20 74 68 65 20 53 51 4c 69 74  ace to the SQLit
01e0: 65 20 6c 69 62 72 61 72 79 20 63 6f 6e 73 69 73  e library consis
01f0: 74 73 20 6f 66 20 74 68 72 65 65 20 63 6f 72 65  ts of three core
0200: 20 66 75 6e 63 74 69 6f 6e 73 2c 0a 6f 6e 65 20   functions,.one 
0210: 6f 70 61 71 75 65 20 64 61 74 61 20 73 74 72 75  opaque data stru
0220: 63 74 75 72 65 2c 20 61 6e 64 20 73 6f 6d 65 20  cture, and some 
0230: 63 6f 6e 73 74 61 6e 74 73 20 75 73 65 64 20 61  constants used a
0240: 73 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  s return values.
0250: 0a 54 68 65 20 63 6f 72 65 20 69 6e 74 65 72 66  .The core interf
0260: 61 63 65 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ace is as follow
0270: 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  s:</p>..<blockqu
0280: 6f 74 65 3e 3c 70 72 65 3e 0a 74 79 70 65 64 65  ote><pre>.typede
0290: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 20  f struct sqlite 
02a0: 73 71 6c 69 74 65 3b 0a 23 64 65 66 69 6e 65 20  sqlite;.#define 
02b0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
02c0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
02d0: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
02e0: 0a 73 71 6c 69 74 65 20 2a 73 71 6c 69 74 65 5f  .sqlite *sqlite_
02f0: 6f 70 65 6e 28 63 6f 6e 73 74 20 63 68 61 72 20  open(const char 
0300: 2a 64 62 6e 61 6d 65 2c 20 69 6e 74 20 6d 6f 64  *dbname, int mod
0310: 65 2c 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  e, char **errmsg
0320: 29 3b 0a 0a 76 6f 69 64 20 73 71 6c 69 74 65 5f  );..void sqlite_
0330: 63 6c 6f 73 65 28 73 71 6c 69 74 65 20 2a 64 62  close(sqlite *db
0340: 29 3b 0a 0a 69 6e 74 20 73 71 6c 69 74 65 5f 65  );..int sqlite_e
0350: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 20 2a 64  xec(.  sqlite *d
0360: 62 2c 0a 20 20 63 68 61 72 20 2a 73 71 6c 2c 0a  b,.  char *sql,.
0370: 20 20 69 6e 74 20 28 2a 78 43 61 6c 6c 62 61 63    int (*xCallbac
0380: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
0390: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 0a 20 20 76  r**,char**),.  v
03a0: 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 63 68 61  oid *pArg,.  cha
03b0: 72 20 2a 2a 65 72 72 6d 73 67 0a 29 3b 0a 3c 2f  r **errmsg.);.</
03c0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
03d0: 3e 0a 0a 3c 70 3e 0a 54 68 65 20 61 62 6f 76 65  >..<p>.The above
03e0: 20 69 73 20 61 6c 6c 20 79 6f 75 20 72 65 61 6c   is all you real
03f0: 6c 79 20 6e 65 65 64 20 74 6f 20 6b 6e 6f 77 20  ly need to know 
0400: 69 6e 20 6f 72 64 65 72 20 74 6f 20 75 73 65 20  in order to use 
0410: 53 51 4c 69 74 65 0a 69 6e 20 79 6f 75 72 20 43  SQLite.in your C
0420: 20 6f 72 20 43 2b 2b 20 70 72 6f 67 72 61 6d 73   or C++ programs
0430: 2e 20 20 54 68 65 72 65 20 61 72 65 20 6f 74 68  .  There are oth
0440: 65 72 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  er interface fun
0450: 63 74 69 6f 6e 73 0a 61 76 61 69 6c 61 62 6c 65  ctions.available
0460: 20 28 61 6e 64 20 64 65 73 63 72 69 62 65 64 20   (and described 
0470: 62 65 6c 6f 77 29 20 62 75 74 20 77 65 20 77 69  below) but we wi
0480: 6c 6c 20 62 65 67 69 6e 20 62 79 20 64 65 73 63  ll begin by desc
0490: 72 69 62 69 6e 67 0a 74 68 65 20 63 6f 72 65 20  ribing.the core 
04a0: 66 75 6e 63 74 69 6f 6e 73 20 73 68 6f 77 6e 20  functions shown 
04b0: 61 62 6f 76 65 2e 0a 3c 2f 70 3e 0a 0a 3c 61 20  above..</p>..<a 
04c0: 6e 61 6d 65 3d 22 73 71 6c 69 74 65 5f 6f 70 65  name="sqlite_ope
04d0: 6e 22 3e 0a 3c 68 34 3e 31 2e 31 20 4f 70 65 6e  n">.<h4>1.1 Open
04e0: 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 3c 2f  ing a database</
04f0: 68 34 3e 0a 0a 3c 70 3e 55 73 65 20 74 68 65 20  h4>..<p>Use the 
0500: 3c 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e 3c 2f  <b>sqlite_open</
0510: 62 3e 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 6f  b> function to o
0520: 70 65 6e 20 61 6e 20 65 78 69 73 74 69 6e 67 20  pen an existing 
0530: 53 51 4c 69 74 65 0a 64 61 74 61 62 61 73 65 20  SQLite.database 
0540: 6f 72 20 74 6f 20 63 72 65 61 74 65 20 61 20 6e  or to create a n
0550: 65 77 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  ew SQLite databa
0560: 73 65 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  se.  The first a
0570: 72 67 75 6d 65 6e 74 0a 69 73 20 74 68 65 20 64  rgument.is the d
0580: 61 74 61 62 61 73 65 20 6e 61 6d 65 2e 20 20 54  atabase name.  T
0590: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
05a0: 6e 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nt is intended t
05b0: 6f 20 73 69 67 6e 61 6c 0a 77 68 65 74 68 65 72  o signal.whether
05c0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
05d0: 20 67 6f 69 6e 67 20 74 6f 20 62 65 20 75 73 65   going to be use
05e0: 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
05f0: 64 20 77 72 69 74 69 6e 67 0a 6f 72 20 6a 75 73  d writing.or jus
0600: 74 20 66 6f 72 20 72 65 61 64 69 6e 67 2e 20 20  t for reading.  
0610: 42 75 74 20 69 6e 20 74 68 65 20 63 75 72 72 65  But in the curre
0620: 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
0630: 6e 2c 20 74 68 65 0a 73 65 63 6f 6e 64 20 61 72  n, the.second ar
0640: 67 75 6d 65 6e 74 20 74 6f 20 3c 62 3e 73 71 6c  gument to <b>sql
0650: 69 74 65 5f 6f 70 65 6e 3c 2f 62 3e 20 69 73 20  ite_open</b> is 
0660: 69 67 6e 6f 72 65 64 2e 0a 54 68 65 20 74 68 69  ignored..The thi
0670: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  rd argument is a
0680: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
0690: 72 69 6e 67 20 70 6f 69 6e 74 65 72 2e 0a 49 66  ring pointer..If
06a0: 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
06b0: 65 6e 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ent is not NULL 
06c0: 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  and an error occ
06d0: 75 72 73 0a 77 68 69 6c 65 20 74 72 79 69 6e 67  urs.while trying
06e0: 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
06f0: 61 62 61 73 65 2c 20 74 68 65 6e 20 61 6e 20 65  abase, then an e
0700: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77 69 6c  rror message wil
0710: 6c 20 62 65 0a 77 72 69 74 74 65 6e 20 74 6f 20  l be.written to 
0720: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
0730: 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  from malloc() an
0740: 64 20 2a 65 72 72 6d 73 67 20 77 69 6c 6c 20 62  d *errmsg will b
0750: 65 20 6d 61 64 65 0a 74 6f 20 70 6f 69 6e 74 20  e made.to point 
0760: 74 6f 20 74 68 69 73 20 65 72 72 6f 72 20 6d 65  to this error me
0770: 73 73 61 67 65 2e 20 20 54 68 65 20 63 61 6c 6c  ssage.  The call
0780: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
0790: 72 65 73 70 6f 6e 73 69 62 6c 65 0a 66 6f 72 20  responsible.for 
07a0: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
07b0: 72 79 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  ry when it has f
07c0: 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
07d0: 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 6e 61 6d  </p>..<p>The nam
07e0: 65 20 6f 66 20 61 6e 20 53 51 4c 69 74 65 20 64  e of an SQLite d
07f0: 61 74 61 62 61 73 65 20 69 73 20 74 68 65 20 6e  atabase is the n
0800: 61 6d 65 20 6f 66 20 61 20 66 69 6c 65 20 74 68  ame of a file th
0810: 61 74 20 77 69 6c 6c 0a 63 6f 6e 74 61 69 6e 20  at will.contain 
0820: 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 49  the database.  I
0830: 66 20 74 68 65 20 66 69 6c 65 20 64 6f 65 73 20  f the file does 
0840: 6e 6f 74 20 65 78 69 73 74 2c 20 53 51 4c 69 74  not exist, SQLit
0850: 65 20 61 74 74 65 6d 70 74 73 0a 74 6f 20 63 72  e attempts.to cr
0860: 65 61 74 65 20 61 6e 64 20 69 6e 69 74 69 61 6c  eate and initial
0870: 69 7a 65 20 69 74 2e 20 20 49 66 20 74 68 65 20  ize it.  If the 
0880: 66 69 6c 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c  file is read-onl
0890: 79 20 28 64 75 65 20 74 6f 0a 70 65 72 6d 69 73  y (due to.permis
08a0: 73 69 6f 6e 20 62 69 74 73 20 6f 72 20 62 65 63  sion bits or bec
08b0: 61 75 73 65 20 69 74 20 69 73 20 6c 6f 63 61 74  ause it is locat
08c0: 65 64 20 6f 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed on read-only 
08d0: 6d 65 64 69 61 20 6c 69 6b 65 0a 61 20 43 44 2d  media like.a CD-
08e0: 52 4f 4d 29 20 74 68 65 6e 20 53 51 4c 69 74 65  ROM) then SQLite
08f0: 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 62   opens the datab
0900: 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
0910: 6f 6e 6c 79 2e 20 20 54 68 65 0a 65 6e 74 69 72  only.  The.entir
0920: 65 20 53 51 4c 20 64 61 74 61 62 61 73 65 20 69  e SQL database i
0930: 73 20 73 74 6f 72 65 64 20 69 6e 20 61 20 73 69  s stored in a si
0940: 6e 67 6c 65 20 66 69 6c 65 20 6f 6e 20 74 68 65  ngle file on the
0950: 20 64 69 73 6b 2e 20 20 42 75 74 0a 61 64 64 69   disk.  But.addi
0960: 74 69 6f 6e 61 6c 20 74 65 6d 70 6f 72 61 72 79  tional temporary
0970: 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20 63 72   files may be cr
0980: 65 61 74 65 64 20 64 75 72 69 6e 67 20 74 68 65  eated during the
0990: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 0a 61 6e   execution of.an
09a0: 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 69 6e 20   SQL command in 
09b0: 6f 72 64 65 72 20 74 6f 20 73 74 6f 72 65 20 74  order to store t
09c0: 68 65 20 64 61 74 61 62 61 73 65 20 72 6f 6c 6c  he database roll
09d0: 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6f 72 0a  back journal or.
09e0: 74 65 6d 70 6f 72 61 72 79 20 61 6e 64 20 69 6e  temporary and in
09f0: 74 65 72 6d 65 64 69 61 74 65 20 72 65 73 75 6c  termediate resul
0a00: 74 73 20 6f 66 20 61 20 71 75 65 72 79 2e 3c 2f  ts of a query.</
0a10: 70 3e 0a 0a 3c 70 3e 54 68 65 20 72 65 74 75 72  p>..<p>The retur
0a20: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 3c  n value of the <
0a30: 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e 3c 2f 62  b>sqlite_open</b
0a40: 3e 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 0a  > function is a.
0a50: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6f 70  pointer to an op
0a60: 61 71 75 65 20 3c 62 3e 73 71 6c 69 74 65 3c 2f  aque <b>sqlite</
0a70: 62 3e 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  b> structure.  T
0a80: 68 69 73 20 70 6f 69 6e 74 65 72 20 77 69 6c 6c  his pointer will
0a90: 0a 62 65 20 74 68 65 20 66 69 72 73 74 20 61 72  .be the first ar
0aa0: 67 75 6d 65 6e 74 20 74 6f 20 61 6c 6c 20 73 75  gument to all su
0ab0: 62 73 65 71 75 65 6e 74 20 53 51 4c 69 74 65 20  bsequent SQLite 
0ac0: 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 74  function calls t
0ad0: 68 61 74 0a 64 65 61 6c 20 77 69 74 68 20 74 68  hat.deal with th
0ae0: 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e  e same database.
0af0: 20 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e    NULL is return
0b00: 65 64 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  ed if the open f
0b10: 61 69 6c 73 0a 66 6f 72 20 61 6e 79 20 72 65 61  ails.for any rea
0b20: 73 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 61 20 6e 61 6d  son.</p>..<a nam
0b30: 65 3d 22 73 71 6c 69 74 65 5f 63 6c 6f 73 65 22  e="sqlite_close"
0b40: 3e 0a 3c 68 34 3e 31 2e 32 20 43 6c 6f 73 69 6e  >.<h4>1.2 Closin
0b50: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 3c 2f  g the database</
0b60: 68 34 3e 0a 0a 3c 70 3e 54 6f 20 63 6c 6f 73 65  h4>..<p>To close
0b70: 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
0b80: 61 73 65 2c 20 63 61 6c 6c 20 74 68 65 20 3c 62  ase, call the <b
0b90: 3e 73 71 6c 69 74 65 5f 63 6c 6f 73 65 3c 2f 62  >sqlite_close</b
0ba0: 3e 0a 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 69  >.function passi
0bb0: 6e 67 20 69 74 20 74 68 65 20 73 71 6c 69 74 65  ng it the sqlite
0bc0: 20 73 74 72 75 63 74 75 72 65 20 70 6f 69 6e 74   structure point
0bd0: 65 72 20 74 68 61 74 20 77 61 73 20 6f 62 74 61  er that was obta
0be0: 69 6e 65 64 0a 66 72 6f 6d 20 61 20 70 72 69 6f  ined.from a prio
0bf0: 72 20 63 61 6c 6c 20 74 6f 20 3c 62 3e 73 71 6c  r call to <b>sql
0c00: 69 74 65 5f 6f 70 65 6e 3c 2f 62 3e 2e 0a 49 66  ite_open</b>..If
0c10: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
0c20: 73 20 61 63 74 69 76 65 20 77 68 65 6e 20 74 68  s active when th
0c30: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 63 6c  e database is cl
0c40: 6f 73 65 64 2c 20 74 68 65 20 74 72 61 6e 73 61  osed, the transa
0c50: 63 74 69 6f 6e 0a 69 73 20 72 6f 6c 6c 65 64 20  ction.is rolled 
0c60: 62 61 63 6b 2e 3c 2f 70 3e 0a 0a 3c 61 20 6e 61  back.</p>..<a na
0c70: 6d 65 3d 22 73 71 6c 69 74 65 5f 65 78 65 63 22  me="sqlite_exec"
0c80: 3e 0a 3c 68 34 3e 31 2e 33 20 45 78 65 63 75 74  >.<h4>1.3 Execut
0c90: 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
0ca0: 74 73 3c 2f 68 34 3e 0a 0a 3c 70 3e 54 68 65 20  ts</h4>..<p>The 
0cb0: 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f  <b>sqlite_exec</
0cc0: 62 3e 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  b> function is u
0cd0: 73 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  sed to process S
0ce0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 61 6e  QL statements.an
0cf0: 64 20 71 75 65 72 69 65 73 2e 20 20 54 68 69 73  d queries.  This
0d00: 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
0d10: 65 73 20 35 20 70 61 72 61 6d 65 74 65 72 73 20  es 5 parameters 
0d20: 61 73 20 66 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a  as follows:</p>.
0d30: 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 70  .<ol>.<li><p>A p
0d40: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71  ointer to the sq
0d50: 6c 69 74 65 20 73 74 72 75 63 74 75 72 65 20 6f  lite structure o
0d60: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
0d70: 72 69 6f 72 20 63 61 6c 6c 0a 20 20 20 20 20 20  rior call.      
0d80: 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 6f 70   to <b>sqlite_op
0d90: 65 6e 3c 2f 62 3e 2e 3c 2f 70 3e 3c 2f 6c 69 3e  en</b>.</p></li>
0da0: 0a 3c 6c 69 3e 3c 70 3e 41 20 6e 75 6c 6c 2d 74  .<li><p>A null-t
0db0: 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
0dc0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
0dd0: 74 65 78 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  text of one or m
0de0: 6f 72 65 0a 20 20 20 20 20 20 20 53 51 4c 20 73  ore.       SQL s
0df0: 74 61 74 65 6d 65 6e 74 73 20 61 6e 64 2f 6f 72  tatements and/or
0e00: 20 71 75 65 72 69 65 73 20 74 6f 20 62 65 20 70   queries to be p
0e10: 72 6f 63 65 73 73 65 64 2e 3c 2f 70 3e 3c 2f 6c  rocessed.</p></l
0e20: 69 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 70 6f 69 6e  i>.<li><p>A poin
0e30: 74 65 72 20 74 6f 20 61 20 63 61 6c 6c 62 61 63  ter to a callbac
0e40: 6b 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63 68  k function which
0e50: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   is invoked once
0e60: 20 66 6f 72 20 65 61 63 68 0a 20 20 20 20 20 20   for each.      
0e70: 20 72 6f 77 20 69 6e 20 74 68 65 20 72 65 73 75   row in the resu
0e80: 6c 74 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  lt of a query.  
0e90: 54 68 69 73 20 61 72 67 75 6d 65 6e 74 20 6d 61  This argument ma
0ea0: 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 77 68  y be NULL, in wh
0eb0: 69 63 68 0a 20 20 20 20 20 20 20 63 61 73 65 20  ich.       case 
0ec0: 6e 6f 20 63 61 6c 6c 62 61 63 6b 73 20 77 69 6c  no callbacks wil
0ed0: 6c 20 65 76 65 72 20 62 65 20 69 6e 76 6f 6b 65  l ever be invoke
0ee0: 64 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e  d.</p></li>.<li>
0ef0: 3c 70 3e 41 20 70 6f 69 6e 74 65 72 20 74 68 61  <p>A pointer tha
0f00: 74 20 69 73 20 66 6f 72 77 61 72 64 65 64 20 74  t is forwarded t
0f10: 6f 20 62 65 63 6f 6d 65 20 74 68 65 20 66 69 72  o become the fir
0f20: 73 74 20 61 72 67 75 6d 65 6e 74 0a 20 20 20 20  st argument.    
0f30: 20 20 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61     to the callba
0f40: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 70 3e  ck function.</p>
0f50: 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 70  </li>.<li><p>A p
0f60: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 72 72  ointer to an err
0f70: 6f 72 20 73 74 72 69 6e 67 2e 20 20 45 72 72 6f  or string.  Erro
0f80: 72 20 6d 65 73 73 61 67 65 73 20 61 72 65 20 77  r messages are w
0f90: 72 69 74 74 65 6e 20 74 6f 20 73 70 61 63 65 0a  ritten to space.
0fa0: 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20         obtained 
0fb0: 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  from malloc() an
0fc0: 64 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  d the error stri
0fd0: 6e 67 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  ng is made to po
0fe0: 69 6e 74 20 74 6f 0a 20 20 20 20 20 20 20 74 68  int to.       th
0ff0: 65 20 6d 61 6c 6c 6f 63 65 64 20 73 70 61 63 65  e malloced space
1000: 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66  .  The calling f
1010: 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  unction is respo
1020: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
1030: 6e 67 0a 20 20 20 20 20 20 20 74 68 69 73 20 73  ng.       this s
1040: 70 61 63 65 20 77 68 65 6e 20 69 74 20 68 61 73  pace when it has
1050: 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
1060: 74 2e 0a 20 20 20 20 20 20 20 54 68 69 73 20 61  t..       This a
1070: 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e  rgument may be N
1080: 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ULL, in which ca
1090: 73 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  se error message
10a0: 73 20 61 72 65 20 6e 6f 74 0a 20 20 20 20 20 20  s are not.      
10b0: 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 74   reported back t
10c0: 6f 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  o the calling fu
10d0: 6e 63 74 69 6f 6e 2e 3c 2f 70 3e 3c 2f 6c 69 3e  nction.</p></li>
10e0: 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 0a 54 68 65 20  .</ol>..<p>.The 
10f0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1100: 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 63  n is used to rec
1110: 65 69 76 65 20 74 68 65 20 72 65 73 75 6c 74 73  eive the results
1120: 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 41 0a   of a query.  A.
1130: 70 72 6f 74 6f 74 79 70 65 20 66 6f 72 20 74 68  prototype for th
1140: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1150: 69 6f 6e 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ion is as follow
1160: 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  s:</p>..<blockqu
1170: 6f 74 65 3e 3c 70 72 65 3e 0a 69 6e 74 20 43 61  ote><pre>.int Ca
1180: 6c 6c 62 61 63 6b 28 76 6f 69 64 20 2a 70 41 72  llback(void *pAr
1190: 67 2c 20 69 6e 74 20 61 72 67 63 2c 20 63 68 61  g, int argc, cha
11a0: 72 20 2a 2a 61 72 67 76 2c 20 63 68 61 72 20 2a  r **argv, char *
11b0: 2a 63 6f 6c 75 6d 6e 4e 61 6d 65 73 29 7b 0a 20  *columnNames){. 
11c0: 20 72 65 74 75 72 6e 20 30 3b 0a 7d 0a 3c 2f 70   return 0;.}.</p
11d0: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
11e0: 0a 0a 3c 61 20 6e 61 6d 65 3d 22 63 61 6c 6c 62  ..<a name="callb
11f0: 61 63 6b 5f 72 6f 77 5f 64 61 74 61 22 3e 0a 3c  ack_row_data">.<
1200: 70 3e 54 68 65 20 66 69 72 73 74 20 61 72 67 75  p>The first argu
1210: 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c  ment to the call
1220: 62 61 63 6b 20 69 73 20 6a 75 73 74 20 61 20 63  back is just a c
1230: 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74  opy of the fourt
1240: 68 20 61 72 67 75 6d 65 6e 74 0a 74 6f 20 3c 62  h argument.to <b
1250: 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e  >sqlite_exec</b>
1260: 20 20 54 68 69 73 20 70 61 72 61 6d 65 74 65 72    This parameter
1270: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1280: 70 61 73 73 20 61 72 62 69 74 72 61 72 79 0a 69  pass arbitrary.i
1290: 6e 66 6f 72 6d 61 74 69 6f 6e 20 74 68 72 6f 75  nformation throu
12a0: 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  gh to the callba
12b0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 66 72 6f 6d  ck function from
12c0: 20 63 6c 69 65 6e 74 20 63 6f 64 65 2e 0a 54 68   client code..Th
12d0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
12e0: 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  t is the number 
12f0: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
1300: 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 2e 0a  e query result..
1310: 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
1320: 6e 74 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  nt is an array o
1330: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
1340: 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68  rings where each
1350: 20 73 74 72 69 6e 67 0a 69 73 20 61 20 73 69 6e   string.is a sin
1360: 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
1370: 65 20 72 65 73 75 6c 74 20 66 6f 72 20 74 68 61  e result for tha
1380: 74 20 72 65 63 6f 72 64 2e 20 20 4e 6f 74 65 20  t record.  Note 
1390: 74 68 61 74 20 74 68 65 0a 63 61 6c 6c 62 61 63  that the.callbac
13a0: 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6f 72  k function repor
13b0: 74 73 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ts a NULL value 
13c0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
13d0: 61 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  as a NULL pointe
13e0: 72 2c 0a 77 68 69 63 68 20 69 73 20 76 65 72 79  r,.which is very
13f0: 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
1400: 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
1410: 20 20 49 66 20 74 68 65 20 69 2d 74 68 20 70 61    If the i-th pa
1420: 72 61 6d 65 74 65 72 0a 69 73 20 61 6e 20 65 6d  rameter.is an em
1430: 70 74 79 20 73 74 72 69 6e 67 2c 20 77 65 20 77  pty string, we w
1440: 69 6c 6c 20 67 65 74 3a 3c 2f 70 3e 0a 3c 62 6c  ill get:</p>.<bl
1450: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 61  ockquote><pre>.a
1460: 72 67 76 5b 69 5d 5b 30 5d 20 3d 3d 20 30 0a 3c  rgv[i][0] == 0.<
1470: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1480: 65 3e 0a 3c 70 3e 42 75 74 20 69 66 20 74 68 65  e>.<p>But if the
1490: 20 69 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   i-th parameter 
14a0: 69 73 20 4e 55 4c 4c 20 77 65 20 77 69 6c 6c 20  is NULL we will 
14b0: 67 65 74 3a 3c 2f 70 3e 0a 3c 62 6c 6f 63 6b 71  get:</p>.<blockq
14c0: 75 6f 74 65 3e 3c 70 72 65 3e 0a 61 72 67 76 5b  uote><pre>.argv[
14d0: 69 5d 20 3d 3d 20 30 0a 3c 2f 70 72 65 3e 3c 2f  i] == 0.</pre></
14e0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e  blockquote>..<p>
14f0: 54 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  The names of the
1500: 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20 63 6f 6e   columns are con
1510: 74 61 69 6e 65 64 20 69 6e 20 66 69 72 73 74 20  tained in first 
1520: 3c 69 3e 61 72 67 63 3c 2f 69 3e 0a 65 6e 74 72  <i>argc</i>.entr
1530: 69 65 73 20 6f 66 20 74 68 65 20 66 6f 75 72 74  ies of the fourt
1540: 68 20 61 72 67 75 6d 65 6e 74 2e 0a 49 66 20 74  h argument..If t
1550: 68 65 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67  he <a href="lang
1560: 2e 68 74 6d 6c 23 70 72 61 67 6d 61 5f 73 68 6f  .html#pragma_sho
1570: 77 5f 64 61 74 61 74 79 70 65 73 22 3e 53 48 4f  w_datatypes">SHO
1580: 57 5f 44 41 54 41 54 59 50 45 53 3c 2f 61 3e 20  W_DATATYPES</a> 
1590: 70 72 61 67 6d 61 0a 69 73 20 6f 6e 20 28 69 74  pragma.is on (it
15a0: 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75   is off by defau
15b0: 6c 74 29 20 74 68 65 6e 0a 74 68 65 20 73 65 63  lt) then.the sec
15c0: 6f 6e 64 20 3c 69 3e 61 72 67 63 3c 2f 69 3e 20  ond <i>argc</i> 
15d0: 65 6e 74 72 69 65 73 20 69 6e 20 74 68 65 20 34  entries in the 4
15e0: 74 68 20 61 72 67 75 6d 65 6e 74 20 61 72 65 20  th argument are 
15f0: 74 68 65 20 64 61 74 61 74 79 70 65 73 0a 66 6f  the datatypes.fo
1600: 72 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  r the correspond
1610: 69 6e 67 20 63 6f 6c 75 6d 6e 73 2e 0a 3c 2f 70  ing columns..</p
1620: 3e 0a 0a 3c 70 3e 49 66 20 74 68 65 20 3c 61 20  >..<p>If the <a 
1630: 68 72 65 66 3d 22 6c 61 6e 67 2e 68 74 6d 6c 23  href="lang.html#
1640: 70 72 61 67 6d 61 5f 65 6d 70 74 79 5f 72 65 73  pragma_empty_res
1650: 75 6c 74 5f 63 61 6c 6c 62 61 63 6b 73 22 3e 0a  ult_callbacks">.
1660: 45 4d 50 54 59 5f 52 45 53 55 4c 54 5f 43 41 4c  EMPTY_RESULT_CAL
1670: 4c 42 41 43 4b 53 3c 2f 61 3e 20 70 72 61 67 6d  LBACKS</a> pragm
1680: 61 20 69 73 20 73 65 74 20 74 6f 20 4f 4e 20 61  a is set to ON a
1690: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  nd the result of
16a0: 0a 61 20 71 75 65 72 79 20 69 73 20 61 6e 20 65  .a query is an e
16b0: 6d 70 74 79 20 73 65 74 2c 20 74 68 65 6e 20 74  mpty set, then t
16c0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
16d0: 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 77 69 74 68  nvoked once with
16e0: 20 74 68 65 0a 74 68 69 72 64 20 70 61 72 61 6d   the.third param
16f0: 65 74 65 72 20 28 61 72 67 76 29 20 73 65 74 20  eter (argv) set 
1700: 74 6f 20 30 2e 20 20 49 6e 20 6f 74 68 65 72 20  to 0.  In other 
1710: 77 6f 72 64 73 0a 3c 62 6c 6f 63 6b 71 75 6f 74  words.<blockquot
1720: 65 3e 3c 70 72 65 3e 0a 61 72 67 76 20 3d 3d 20  e><pre>.argv == 
1730: 30 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  0.</pre></blockq
1740: 75 6f 74 65 3e 0a 54 68 65 20 73 65 63 6f 6e 64  uote>.The second
1750: 20 70 61 72 61 6d 65 74 65 72 20 28 61 72 67 63   parameter (argc
1760: 29 0a 61 6e 64 20 74 68 65 20 66 6f 75 72 74 68  ).and the fourth
1770: 20 70 61 72 61 6d 65 74 65 72 20 28 63 6f 6c 75   parameter (colu
1780: 6d 6e 4e 61 6d 65 73 29 20 61 72 65 20 73 74 69  mnNames) are sti
1790: 6c 6c 20 76 61 6c 69 64 0a 61 6e 64 20 63 61 6e  ll valid.and can
17a0: 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 74 65   be used to dete
17b0: 72 6d 69 6e 65 20 74 68 65 20 6e 75 6d 62 65 72  rmine the number
17c0: 20 61 6e 64 20 6e 61 6d 65 73 20 6f 66 20 74 68   and names of th
17d0: 65 20 72 65 73 75 6c 74 0a 63 6f 6c 75 6d 6e 73  e result.columns
17e0: 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
17f0: 65 6e 20 61 20 72 65 73 75 6c 74 2e 0a 54 68 65  en a result..The
1800: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
1810: 72 20 69 73 20 6e 6f 74 20 74 6f 20 69 6e 76 6f  r is not to invo
1820: 6b 65 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ke the callback 
1830: 61 74 20 61 6c 6c 20 69 66 20 74 68 65 0a 72 65  at all if the.re
1840: 73 75 6c 74 20 73 65 74 20 69 73 20 65 6d 70 74  sult set is empt
1850: 79 2e 3c 2f 70 3e 0a 0a 3c 61 20 6e 61 6d 65 3d  y.</p>..<a name=
1860: 22 63 61 6c 6c 62 61 63 6b 5f 72 65 74 75 72 6e  "callback_return
1870: 73 5f 6e 6f 6e 7a 65 72 6f 22 3e 0a 3c 70 3e 54  s_nonzero">.<p>T
1880: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1890: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 72 6d  tion should norm
18a0: 61 6c 6c 79 20 72 65 74 75 72 6e 20 30 2e 20 20  ally return 0.  
18b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  If the callback.
18c0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
18d0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 71   non-zero, the q
18e0: 75 65 72 79 20 69 73 20 69 6d 6d 65 64 69 61 74  uery is immediat
18f0: 65 6c 79 20 61 62 6f 72 74 65 64 20 61 6e 64 20  ely aborted and 
1900: 0a 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c  .<b>sqlite_exec<
1910: 2f 62 3e 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  /b> will return 
1920: 53 51 4c 49 54 45 5f 41 42 4f 52 54 2e 3c 2f 70  SQLITE_ABORT.</p
1930: 3e 0a 0a 3c 68 34 3e 31 2e 34 20 45 72 72 6f 72  >..<h4>1.4 Error
1940: 20 43 6f 64 65 73 3c 2f 68 34 3e 0a 0a 3c 70 3e   Codes</h4>..<p>
1950: 0a 54 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 65  .The <b>sqlite_e
1960: 78 65 63 3c 2f 62 3e 20 66 75 6e 63 74 69 6f 6e  xec</b> function
1970: 20 6e 6f 72 6d 61 6c 6c 79 20 72 65 74 75 72 6e   normally return
1980: 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 42 75  s SQLITE_OK.  Bu
1990: 74 0a 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67  t.if something g
19a0: 6f 65 73 20 77 72 6f 6e 67 20 69 74 20 63 61 6e  oes wrong it can
19b0: 20 72 65 74 75 72 6e 20 61 20 64 69 66 66 65 72   return a differ
19c0: 65 6e 74 20 76 61 6c 75 65 20 74 6f 20 69 6e 64  ent value to ind
19d0: 69 63 61 74 65 0a 74 68 65 20 74 79 70 65 20 6f  icate.the type o
19e0: 66 20 65 72 72 6f 72 2e 20 20 48 65 72 65 20 69  f error.  Here i
19f0: 73 20 61 20 63 6f 6d 70 6c 65 74 65 20 6c 69 73  s a complete lis
1a00: 74 20 6f 66 20 74 68 65 20 72 65 74 75 72 6e 20  t of the return 
1a10: 63 6f 64 65 73 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c  codes:.</p>..<bl
1a20: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 23  ockquote><pre>.#
1a30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
1a40: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
1a50: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
1a60: 75 6c 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ult */.#define S
1a70: 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20  QLITE_ERROR     
1a80: 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72     1   /* SQL er
1a90: 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64  ror or missing d
1aa0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
1ab0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e  ne SQLITE_INTERN
1ac0: 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 41 6e  AL     2   /* An
1ad0: 20 69 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20   internal logic 
1ae0: 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20  error in SQLite 
1af0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b00: 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33  E_PERM         3
1b10: 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72     /* Access per
1b20: 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a  mission denied *
1b30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b40: 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20  _ABORT        4 
1b50: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f    /* Callback ro
1b60: 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20  utine requested 
1b70: 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66  an abort */.#def
1b80: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  ine SQLITE_BUSY 
1b90: 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54          5   /* T
1ba0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
1bb0: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
1bc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
1bd0: 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a  KED       6   /*
1be0: 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20   A table in the 
1bf0: 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b  database is lock
1c00: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
1c10: 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20  LITE_NOMEM      
1c20: 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f    7   /* A mallo
1c30: 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64  c() failed */.#d
1c40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
1c50: 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a  DONLY     8   /*
1c60: 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74   Attempt to writ
1c70: 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74  e a readonly dat
1c80: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65  abase */.#define
1c90: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50   SQLITE_INTERRUP
1ca0: 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72  T    9   /* Oper
1cb0: 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64  ation terminated
1cc0: 20 62 79 20 73 71 6c 69 74 65 5f 69 6e 74 65 72   by sqlite_inter
1cd0: 72 75 70 74 28 29 20 2a 2f 0a 23 64 65 66 69 6e  rupt() */.#defin
1ce0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20  e SQLITE_IOERR  
1cf0: 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d       10   /* Som
1d00: 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49  e kind of disk I
1d10: 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65  /O error occurre
1d20: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
1d30: 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20  ITE_CORRUPT     
1d40: 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  11   /* The data
1d50: 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20  base disk image 
1d60: 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a  is malformed */.
1d70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
1d80: 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20  OTFOUND    12   
1d90: 2f 2a 20 28 49 6e 74 65 72 6e 61 6c 20 4f 6e 6c  /* (Internal Onl
1da0: 79 29 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f  y) Table or reco
1db0: 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a  rd not found */.
1dc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
1dd0: 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20  ULL        13   
1de0: 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69  /* Insertion fai
1df0: 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61  led because data
1e00: 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a  base is full */.
1e10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1e20: 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20  ANTOPEN    14   
1e30: 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65  /* Unable to ope
1e40: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
1e50: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
1e60: 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20  QLITE_PROTOCOL  
1e70: 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61    15   /* Databa
1e80: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
1e90: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
1ea0: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
1eb0: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 28 49 6e       16   /* (In
1ec0: 74 65 72 6e 61 6c 20 4f 6e 6c 79 29 20 44 61 74  ternal Only) Dat
1ed0: 61 62 61 73 65 20 74 61 62 6c 65 20 69 73 20 65  abase table is e
1ee0: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  mpty */.#define 
1ef0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
1f00: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
1f10: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
1f20: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
1f30: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
1f40: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 6f 6f       18   /* Too
1f50: 20 6d 75 63 68 20 64 61 74 61 20 66 6f 72 20 6f   much data for o
1f60: 6e 65 20 72 6f 77 20 6f 66 20 61 20 74 61 62 6c  ne row of a tabl
1f70: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
1f80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
1f90: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
1fa0: 65 20 74 6f 20 63 6f 6e 74 72 61 69 6e 74 20 76  e to contraint v
1fb0: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
1fc0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
1fd0: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
1fe0: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
1ff0: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
2000: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
2010: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
2020: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
2030: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2040: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
2050: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
2060: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
2070: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
2080: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2090: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
20a0: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
20b0: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
20c0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
20d0: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
20e0: 71 6c 69 74 65 5f 73 74 65 70 28 29 20 68 61 73  qlite_step() has
20f0: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
2100: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
2110: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
2120: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 5f   101  /* sqlite_
2130: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
2140: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
2150: 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75  .</pre></blockqu
2160: 6f 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65 20 6d 65  ote>..<p>.The me
2170: 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 73 65 20  anings of these 
2180: 76 61 72 69 6f 75 73 20 72 65 74 75 72 6e 20 76  various return v
2190: 61 6c 75 65 73 20 61 72 65 20 61 73 20 66 6f 6c  alues are as fol
21a0: 6c 6f 77 73 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f  lows:.</p>..<blo
21b0: 63 6b 71 75 6f 74 65 3e 0a 3c 64 6c 3e 0a 3c 64  ckquote>.<dl>.<d
21c0: 74 3e 53 51 4c 49 54 45 5f 4f 4b 3c 2f 64 74 3e  t>SQLITE_OK</dt>
21d0: 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 76 61 6c  .<dd><p>This val
21e0: 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ue is returned i
21f0: 66 20 65 76 65 72 79 74 68 69 6e 67 20 77 6f 72  f everything wor
2200: 6b 65 64 20 61 6e 64 20 74 68 65 72 65 20 77 65  ked and there we
2210: 72 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 3c 2f  re no errors..</
2220: 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49  p></dd>.<dt>SQLI
2230: 54 45 5f 49 4e 54 45 52 4e 41 4c 3c 2f 64 74 3e  TE_INTERNAL</dt>
2240: 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 76 61 6c  .<dd><p>This val
2250: 75 65 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ue indicates tha
2260: 74 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 63 6f  t an internal co
2270: 6e 73 69 73 74 65 6e 63 79 20 63 68 65 63 6b 20  nsistency check 
2280: 77 69 74 68 69 6e 0a 74 68 65 20 53 51 4c 69 74  within.the SQLit
2290: 65 20 6c 69 62 72 61 72 79 20 66 61 69 6c 65 64  e library failed
22a0: 2e 20 20 54 68 69 73 20 63 61 6e 20 6f 6e 6c 79  .  This can only
22b0: 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 72 65   happen if there
22c0: 20 69 73 20 61 20 62 75 67 20 69 6e 0a 74 68 65   is a bug in.the
22d0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
22e0: 20 20 49 66 20 79 6f 75 20 65 76 65 72 20 67 65    If you ever ge
22f0: 74 20 61 6e 20 53 51 4c 49 54 45 5f 49 4e 54 45  t an SQLITE_INTE
2300: 52 4e 41 4c 20 72 65 70 6c 79 20 66 72 6f 6d 0a  RNAL reply from.
2310: 61 6e 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65  an <b>sqlite_exe
2320: 63 3c 2f 62 3e 20 63 61 6c 6c 2c 20 70 6c 65 61  c</b> call, plea
2330: 73 65 20 72 65 70 6f 72 74 20 74 68 65 20 70 72  se report the pr
2340: 6f 62 6c 65 6d 20 6f 6e 20 74 68 65 20 53 51 4c  oblem on the SQL
2350: 69 74 65 0a 6d 61 69 6c 69 6e 67 20 6c 69 73 74  ite.mailing list
2360: 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e  ..</p></dd>.<dt>
2370: 53 51 4c 49 54 45 5f 45 52 52 4f 52 3c 2f 64 74  SQLITE_ERROR</dt
2380: 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 72 65  >.<dd><p>This re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 69 6e 64 69 63  turn value indic
23a0: 61 74 65 73 20 74 68 61 74 20 74 68 65 72 65 20  ates that there 
23b0: 77 61 73 20 61 6e 20 65 72 72 6f 72 20 69 6e 20  was an error in 
23c0: 74 68 65 20 53 51 4c 0a 74 68 61 74 20 77 61 73  the SQL.that was
23d0: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
23e0: 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c   <b>sqlite_exec<
23f0: 2f 62 3e 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c  /b>..</p></dd>.<
2400: 64 74 3e 53 51 4c 49 54 45 5f 50 45 52 4d 3c 2f  dt>SQLITE_PERM</
2410: 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20  dt>.<dd><p>This 
2420: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 73 61 79  return value say
2430: 73 20 74 68 61 74 20 74 68 65 20 61 63 63 65 73  s that the acces
2440: 73 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 6f 6e  s permissions on
2450: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 66 69   the database.fi
2460: 6c 65 20 61 72 65 20 73 75 63 68 20 74 68 61 74  le are such that
2470: 20 74 68 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74   the file cannot
2480: 20 62 65 20 6f 70 65 6e 65 64 2e 0a 3c 2f 70 3e   be opened..</p>
2490: 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45  </dd>.<dt>SQLITE
24a0: 5f 41 42 4f 52 54 3c 2f 64 74 3e 0a 3c 64 64 3e  _ABORT</dt>.<dd>
24b0: 3c 70 3e 54 68 69 73 20 76 61 6c 75 65 20 69 73  <p>This value is
24c0: 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
24d0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
24e0: 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  on returns non-z
24f0: 65 72 6f 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c  ero..</p></dd>.<
2500: 64 74 3e 53 51 4c 49 54 45 5f 42 55 53 59 3c 2f  dt>SQLITE_BUSY</
2510: 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20  dt>.<dd><p>This 
2520: 72 65 74 75 72 6e 20 63 6f 64 65 20 69 6e 64 69  return code indi
2530: 63 61 74 65 73 20 74 68 61 74 20 61 6e 6f 74 68  cates that anoth
2540: 65 72 20 70 72 6f 67 72 61 6d 20 6f 72 20 74 68  er program or th
2550: 72 65 61 64 20 68 61 73 0a 74 68 65 20 64 61 74  read has.the dat
2560: 61 62 61 73 65 20 6c 6f 63 6b 65 64 2e 20 20 53  abase locked.  S
2570: 51 4c 69 74 65 20 61 6c 6c 6f 77 73 20 74 77 6f  QLite allows two
2580: 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
2590: 20 74 6f 20 72 65 61 64 20 74 68 65 0a 64 61 74   to read the.dat
25a0: 61 62 61 73 65 20 61 74 20 74 68 65 20 73 61 6d  abase at the sam
25b0: 65 20 74 69 6d 65 2c 20 62 75 74 20 6f 6e 6c 79  e time, but only
25c0: 20 6f 6e 65 20 74 68 72 65 61 64 20 63 61 6e 20   one thread can 
25d0: 68 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73  have the databas
25e0: 65 0a 6f 70 65 6e 20 66 6f 72 20 77 72 69 74 69  e.open for writi
25f0: 6e 67 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ng at the same t
2600: 69 6d 65 2e 20 20 4c 6f 63 6b 69 6e 67 20 69 6e  ime.  Locking in
2610: 20 53 51 4c 69 74 65 20 69 73 20 6f 6e 20 74 68   SQLite is on th
2620: 65 0a 65 6e 74 69 72 65 20 64 61 74 61 62 61 73  e.entire databas
2630: 65 2e 3c 2f 70 3e 0a 3c 2f 70 3e 3c 2f 64 64 3e  e.</p>.</p></dd>
2640: 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 4f 43 4b  .<dt>SQLITE_LOCK
2650: 45 44 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54  ED</dt>.<dd><p>T
2660: 68 69 73 20 72 65 74 75 72 6e 20 63 6f 64 65 20  his return code 
2670: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 53 51  is similar to SQ
2680: 4c 49 54 45 5f 42 55 53 59 20 69 6e 20 74 68 61  LITE_BUSY in tha
2690: 74 20 69 74 20 69 6e 64 69 63 61 74 65 73 0a 74  t it indicates.t
26a0: 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
26b0: 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 42 75 74   is locked.  But
26c0: 20 74 68 65 20 73 6f 75 72 63 65 20 6f 66 20 74   the source of t
26d0: 68 65 20 6c 6f 63 6b 20 69 73 20 61 20 72 65 63  he lock is a rec
26e0: 75 72 73 69 76 65 0a 63 61 6c 6c 20 74 6f 20 3c  ursive.call to <
26f0: 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62  b>sqlite_exec</b
2700: 3e 2e 20 20 54 68 69 73 20 72 65 74 75 72 6e 20  >.  This return 
2710: 63 61 6e 20 6f 6e 6c 79 20 6f 63 63 75 72 20 69  can only occur i
2720: 66 20 79 6f 75 20 61 74 74 65 6d 70 74 0a 74 6f  f you attempt.to
2730: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 5f 65   invoke sqlite_e
2740: 78 65 63 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  xec from within 
2750: 61 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  a callback routi
2760: 6e 65 20 6f 66 20 61 20 71 75 65 72 79 0a 66 72  ne of a query.fr
2770: 6f 6d 20 61 20 70 72 69 6f 72 20 69 6e 76 6f 63  om a prior invoc
2780: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 5f  ation of sqlite_
2790: 65 78 65 63 2e 20 20 52 65 63 75 72 73 69 76 65  exec.  Recursive
27a0: 20 63 61 6c 6c 73 20 74 6f 0a 73 71 6c 69 74 65   calls to.sqlite
27b0: 5f 65 78 65 63 20 61 72 65 20 61 6c 6c 6f 77 65  _exec are allowe
27c0: 64 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  d as long as the
27d0: 79 20 64 6f 0a 6e 6f 74 20 61 74 74 65 6d 70 74  y do.not attempt
27e0: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 73 61   to write the sa
27f0: 6d 65 20 74 61 62 6c 65 2e 0a 3c 2f 70 3e 3c 2f  me table..</p></
2800: 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 4e  dd>.<dt>SQLITE_N
2810: 4f 4d 45 4d 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70  OMEM</dt>.<dd><p
2820: 3e 54 68 69 73 20 76 61 6c 75 65 20 69 73 20 72  >This value is r
2830: 65 74 75 72 6e 65 64 20 69 66 20 61 20 63 61 6c  eturned if a cal
2840: 6c 20 74 6f 20 3c 62 3e 6d 61 6c 6c 6f 63 3c 2f  l to <b>malloc</
2850: 62 3e 20 66 61 69 6c 73 2e 0a 3c 2f 70 3e 3c 2f  b> fails..</p></
2860: 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 52  dd>.<dt>SQLITE_R
2870: 45 41 44 4f 4e 4c 59 3c 2f 64 74 3e 0a 3c 64 64  EADONLY</dt>.<dd
2880: 3e 3c 70 3e 54 68 69 73 20 72 65 74 75 72 6e 20  ><p>This return 
2890: 63 6f 64 65 20 69 6e 64 69 63 61 74 65 73 20 74  code indicates t
28a0: 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 77  hat an attempt w
28b0: 61 73 20 6d 61 64 65 20 74 6f 20 77 72 69 74 65  as made to write
28c0: 20 74 6f 0a 61 20 64 61 74 61 62 61 73 65 20 66   to.a database f
28d0: 69 6c 65 20 74 68 61 74 20 69 73 20 6f 70 65 6e  ile that is open
28e0: 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f  ed for reading o
28f0: 6e 6c 79 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c  nly..</p></dd>.<
2900: 64 74 3e 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  dt>SQLITE_INTERR
2910: 55 50 54 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e  UPT</dt>.<dd><p>
2920: 54 68 69 73 20 76 61 6c 75 65 20 69 73 20 72 65  This value is re
2930: 74 75 72 6e 65 64 20 69 66 20 61 20 63 61 6c 6c  turned if a call
2940: 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 69 6e   to <b>sqlite_in
2950: 74 65 72 72 75 70 74 3c 2f 62 3e 0a 69 6e 74 65  terrupt</b>.inte
2960: 72 72 75 70 74 73 20 61 20 64 61 74 61 62 61 73  rrupts a databas
2970: 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 6e 20 70  e operation in p
2980: 72 6f 67 72 65 73 73 2e 0a 3c 2f 70 3e 3c 2f 64  rogress..</p></d
2990: 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 49 4f  d>.<dt>SQLITE_IO
29a0: 45 52 52 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e  ERR</dt>.<dd><p>
29b0: 54 68 69 73 20 76 61 6c 75 65 20 69 73 20 72 65  This value is re
29c0: 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 6f 70  turned if the op
29d0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
29e0: 6e 66 6f 72 6d 73 20 53 51 4c 69 74 65 0a 74 68  nforms SQLite.th
29f0: 61 74 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  at it is unable 
2a00: 74 6f 20 70 65 72 66 6f 72 6d 20 73 6f 6d 65 20  to perform some 
2a10: 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69  disk I/O operati
2a20: 6f 6e 2e 20 20 54 68 69 73 20 63 6f 75 6c 64 20  on.  This could 
2a30: 6d 65 61 6e 0a 74 68 61 74 20 74 68 65 72 65 20  mean.that there 
2a40: 69 73 20 6e 6f 20 6d 6f 72 65 20 73 70 61 63 65  is no more space
2a50: 20 6c 65 66 74 20 6f 6e 20 74 68 65 20 64 69 73   left on the dis
2a60: 6b 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74  k..</p></dd>.<dt
2a70: 3e 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 3c  >SQLITE_CORRUPT<
2a80: 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73  /dt>.<dd><p>This
2a90: 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
2aa0: 65 64 20 69 66 20 53 51 4c 69 74 65 20 64 65 74  ed if SQLite det
2ab0: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 64 61  ects that the da
2ac0: 74 61 62 61 73 65 20 69 74 20 69 73 0a 77 6f 72  tabase it is.wor
2ad0: 6b 69 6e 67 20 6f 6e 20 68 61 73 20 62 65 63 6f  king on has beco
2ae0: 6d 65 20 63 6f 72 72 75 70 74 65 64 2e 20 20 43  me corrupted.  C
2af0: 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20  orruption might 
2b00: 6f 63 63 75 72 20 64 75 65 20 74 6f 20 61 20 72  occur due to a r
2b10: 6f 67 75 65 0a 70 72 6f 63 65 73 73 20 77 72 69  ogue.process wri
2b20: 74 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61  ting to the data
2b30: 62 61 73 65 20 66 69 6c 65 20 6f 72 20 69 74 20  base file or it 
2b40: 6d 69 67 68 74 20 68 61 70 70 65 6e 20 64 75 65  might happen due
2b50: 20 74 6f 20 61 6e 20 0a 70 65 72 76 69 6f 75 73   to an .pervious
2b60: 6c 79 20 75 6e 64 65 74 65 63 74 65 64 20 6c 6f  ly undetected lo
2b70: 67 69 63 20 65 72 72 6f 72 20 69 6e 20 6f 66 20  gic error in of 
2b80: 53 51 4c 69 74 65 2e 20 54 68 69 73 20 76 61 6c  SQLite. This val
2b90: 75 65 20 69 73 20 61 6c 73 6f 0a 72 65 74 75 72  ue is also.retur
2ba0: 6e 65 64 20 69 66 20 61 20 64 69 73 6b 20 49 2f  ned if a disk I/
2bb0: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 69  O error occurs i
2bc0: 6e 20 73 75 63 68 20 61 20 77 61 79 20 74 68 61  n such a way tha
2bd0: 74 20 53 51 4c 69 74 65 20 69 73 20 66 6f 72 63  t SQLite is forc
2be0: 65 64 0a 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ed.to leave the 
2bf0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e  database file in
2c00: 20 61 20 63 6f 72 72 75 70 74 65 64 20 73 74 61   a corrupted sta
2c10: 74 65 2e 20 20 54 68 65 20 6c 61 74 74 65 72 20  te.  The latter 
2c20: 73 68 6f 75 6c 64 20 6f 6e 6c 79 0a 68 61 70 70  should only.happ
2c30: 65 6e 20 64 75 65 20 74 6f 20 61 20 68 61 72 64  en due to a hard
2c40: 77 61 72 65 20 6f 72 20 6f 70 65 72 61 74 69 6e  ware or operatin
2c50: 67 20 73 79 73 74 65 6d 20 6d 61 6c 66 75 6e 63  g system malfunc
2c60: 74 69 6f 6e 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a  tion..</p></dd>.
2c70: 3c 64 74 3e 53 51 4c 49 54 45 5f 46 55 4c 4c 3c  <dt>SQLITE_FULL<
2c80: 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73  /dt>.<dd><p>This
2c90: 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
2ca0: 65 64 20 69 66 20 61 6e 20 69 6e 73 65 72 74 69  ed if an inserti
2cb0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
2cc0: 65 20 74 68 65 72 65 20 69 73 0a 6e 6f 20 73 70  e there is.no sp
2cd0: 61 63 65 20 6c 65 66 74 20 6f 6e 20 74 68 65 20  ace left on the 
2ce0: 64 69 73 6b 2c 20 6f 72 20 74 68 65 20 64 61 74  disk, or the dat
2cf0: 61 62 61 73 65 20 69 73 20 74 6f 6f 20 62 69 67  abase is too big
2d00: 20 74 6f 20 68 6f 6c 64 20 61 6e 79 0a 6d 6f 72   to hold any.mor
2d10: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 20  e information.  
2d20: 54 68 65 20 6c 61 74 74 65 72 20 63 61 73 65 20  The latter case 
2d30: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 6f 63 63 75  should only occu
2d40: 72 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a  r for databases.
2d50: 74 68 61 74 20 61 72 65 20 6c 61 72 67 65 72 20  that are larger 
2d60: 74 68 61 6e 20 32 47 42 20 69 6e 20 73 69 7a 65  than 2GB in size
2d70: 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e  ..</p></dd>.<dt>
2d80: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 3c  SQLITE_CANTOPEN<
2d90: 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73  /dt>.<dd><p>This
2da0: 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
2db0: 65 64 20 69 66 20 74 68 65 20 64 61 74 61 62 61  ed if the databa
2dc0: 73 65 20 66 69 6c 65 20 63 6f 75 6c 64 20 6e 6f  se file could no
2dd0: 74 20 62 65 20 6f 70 65 6e 65 64 0a 66 6f 72 20  t be opened.for 
2de0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 3c 2f 70  some reason..</p
2df0: 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54  ></dd>.<dt>SQLIT
2e00: 45 5f 50 52 4f 54 4f 43 4f 4c 3c 2f 64 74 3e 0a  E_PROTOCOL</dt>.
2e10: 3c 64 64 3e 3c 70 3e 54 68 69 73 20 76 61 6c 75  <dd><p>This valu
2e20: 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  e is returned if
2e30: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
2e40: 65 73 73 20 69 73 20 6d 65 73 73 69 6e 67 20 77  ess is messing w
2e50: 69 74 68 0a 66 69 6c 65 20 6c 6f 63 6b 73 20 61  ith.file locks a
2e60: 6e 64 20 68 61 73 20 76 69 6f 6c 61 74 65 64 20  nd has violated 
2e70: 74 68 65 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67  the file locking
2e80: 20 70 72 6f 74 6f 63 6f 6c 20 74 68 61 74 20 53   protocol that S
2e90: 51 4c 69 74 65 20 75 73 65 73 0a 6f 6e 20 69 74  QLite uses.on it
2ea0: 73 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e  s rollback journ
2eb0: 61 6c 20 66 69 6c 65 73 2e 0a 3c 2f 70 3e 3c 2f  al files..</p></
2ec0: 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 53  dd>.<dt>SQLITE_S
2ed0: 43 48 45 4d 41 3c 2f 64 74 3e 0a 3c 64 64 3e 3c  CHEMA</dt>.<dd><
2ee0: 70 3e 57 68 65 6e 20 74 68 65 20 64 61 74 61 62  p>When the datab
2ef0: 61 73 65 20 66 69 72 73 74 20 6f 70 65 6e 65 64  ase first opened
2f00: 2c 20 53 51 4c 69 74 65 20 72 65 61 64 73 20 74  , SQLite reads t
2f10: 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
2f20: 6d 61 0a 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 61  ma.into memory a
2f30: 6e 64 20 75 73 65 73 20 74 68 61 74 20 73 63 68  nd uses that sch
2f40: 65 6d 61 20 74 6f 20 70 61 72 73 65 20 6e 65 77  ema to parse new
2f50: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
2f60: 20 20 49 66 20 61 6e 6f 74 68 65 72 0a 70 72 6f    If another.pro
2f70: 63 65 73 73 20 63 68 61 6e 67 65 73 20 74 68 65  cess changes the
2f80: 20 73 63 68 65 6d 61 2c 20 74 68 65 20 63 6f 6d   schema, the com
2f90: 6d 61 6e 64 20 63 75 72 72 65 6e 74 6c 79 20 62  mand currently b
2fa0: 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 20 77  eing processed w
2fb0: 69 6c 6c 0a 61 62 6f 72 74 20 62 65 63 61 75 73  ill.abort becaus
2fc0: 65 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61  e the virtual ma
2fd0: 63 68 69 6e 65 20 63 6f 64 65 20 67 65 6e 65 72  chine code gener
2fe0: 61 74 65 64 20 61 73 73 75 6d 65 64 20 74 68 65  ated assumed the
2ff0: 20 6f 6c 64 0a 73 63 68 65 6d 61 2e 20 20 54 68   old.schema.  Th
3000: 69 73 20 69 73 20 74 68 65 20 72 65 74 75 72 6e  is is the return
3010: 20 63 6f 64 65 20 66 6f 72 20 73 75 63 68 20 63   code for such c
3020: 61 73 65 73 2e 20 20 52 65 74 72 79 69 6e 67 20  ases.  Retrying 
3030: 74 68 65 0a 63 6f 6d 6d 61 6e 64 20 75 73 75 61  the.command usua
3040: 6c 6c 79 20 77 69 6c 6c 20 63 6c 65 61 72 20 74  lly will clear t
3050: 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 3c 2f 70 3e  he problem..</p>
3060: 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45  </dd>.<dt>SQLITE
3070: 5f 54 4f 4f 42 49 47 3c 2f 64 74 3e 0a 3c 64 64  _TOOBIG</dt>.<dd
3080: 3e 3c 70 3e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ><p>SQLite will 
3090: 6e 6f 74 20 73 74 6f 72 65 20 6d 6f 72 65 20 74  not store more t
30a0: 68 61 6e 20 61 62 6f 75 74 20 31 20 6d 65 67 61  han about 1 mega
30b0: 62 79 74 65 20 6f 66 20 64 61 74 61 20 69 6e 20  byte of data in 
30c0: 61 20 73 69 6e 67 6c 65 0a 72 6f 77 20 6f 66 20  a single.row of 
30d0: 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 2e 20  a single table. 
30e0: 20 49 66 20 79 6f 75 20 61 74 74 65 6d 70 74 20   If you attempt 
30f0: 74 6f 20 73 74 6f 72 65 20 6d 6f 72 65 20 74 68  to store more th
3100: 61 6e 20 31 20 6d 65 67 61 62 79 74 65 0a 69 6e  an 1 megabyte.in
3110: 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 2c 20 74   a single row, t
3120: 68 69 73 20 69 73 20 74 68 65 20 72 65 74 75 72  his is the retur
3130: 6e 20 63 6f 64 65 20 79 6f 75 20 67 65 74 2e 0a  n code you get..
3140: 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51  </p></dd>.<dt>SQ
3150: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 3c  LITE_CONSTRAINT<
3160: 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73  /dt>.<dd><p>This
3170: 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 72 65 74   constant is ret
3180: 75 72 6e 65 64 20 69 66 20 74 68 65 20 53 51 4c  urned if the SQL
3190: 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
31a0: 20 68 61 76 65 20 76 69 6f 6c 61 74 65 64 0a 61   have violated.a
31b0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 73 74 72   database constr
31c0: 61 69 6e 74 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a  aint..</p></dd>.
31d0: 3c 64 74 3e 53 51 4c 49 54 45 5f 4d 49 53 4d 41  <dt>SQLITE_MISMA
31e0: 54 43 48 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e  TCH</dt>.<dd><p>
31f0: 54 68 69 73 20 65 72 72 6f 72 20 6f 63 63 75 72  This error occur
3200: 73 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  s when there is 
3210: 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 69 6e  an attempt to in
3220: 73 65 72 74 20 6e 6f 6e 2d 69 6e 74 65 67 65 72  sert non-integer
3230: 0a 64 61 74 61 20 69 6e 74 6f 20 61 20 63 6f 6c  .data into a col
3240: 75 6d 6e 20 6c 61 62 65 6c 65 64 20 49 4e 54 45  umn labeled INTE
3250: 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 2e  GER PRIMARY KEY.
3260: 20 20 46 6f 72 20 6d 6f 73 74 20 63 6f 6c 75 6d    For most colum
3270: 6e 73 2c 20 53 51 4c 69 74 65 0a 69 67 6e 6f 72  ns, SQLite.ignor
3280: 65 73 20 74 68 65 20 64 61 74 61 20 74 79 70 65  es the data type
3290: 20 61 6e 64 20 61 6c 6c 6f 77 73 20 61 6e 79 20   and allows any 
32a0: 6b 69 6e 64 20 6f 66 20 64 61 74 61 20 74 6f 20  kind of data to 
32b0: 62 65 20 73 74 6f 72 65 64 2e 20 20 42 75 74 0a  be stored.  But.
32c0: 61 6e 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41  an INTEGER PRIMA
32d0: 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 69 73  RY KEY column is
32e0: 20 6f 6e 6c 79 20 61 6c 6c 6f 77 65 64 20 74 6f   only allowed to
32f0: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 64   store integer d
3300: 61 74 61 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c  ata..</p></dd>.<
3310: 64 74 3e 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  dt>SQLITE_MISUSE
3320: 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69  </dt>.<dd><p>Thi
3330: 73 20 65 72 72 6f 72 20 6d 69 67 68 74 20 6f 63  s error might oc
3340: 63 75 72 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f  cur if one or mo
3350: 72 65 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  re of the SQLite
3360: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 0a 69 73   API routines.is
3370: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
3380: 79 2e 20 20 45 78 61 6d 70 6c 65 73 20 6f 66 20  y.  Examples of 
3390: 69 6e 63 6f 72 72 65 63 74 20 75 73 61 67 65 20  incorrect usage 
33a0: 69 6e 63 6c 75 64 65 20 63 61 6c 6c 69 6e 67 0a  include calling.
33b0: 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f  <b>sqlite_exec</
33c0: 62 3e 20 61 66 74 65 72 20 74 68 65 20 64 61 74  b> after the dat
33d0: 61 62 61 73 65 20 68 61 73 20 62 65 65 6e 20 63  abase has been c
33e0: 6c 6f 73 65 64 20 75 73 69 6e 67 0a 3c 62 3e 73  losed using.<b>s
33f0: 71 6c 69 74 65 5f 63 6c 6f 73 65 3c 2f 62 3e 20  qlite_close</b> 
3400: 6f 72 20 0a 63 61 6c 6c 69 6e 67 20 3c 62 3e 73  or .calling <b>s
3410: 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e 20 77  qlite_exec</b> w
3420: 69 74 68 20 74 68 65 20 73 61 6d 65 0a 64 61 74  ith the same.dat
3430: 61 62 61 73 65 20 70 6f 69 6e 74 65 72 20 73 69  abase pointer si
3440: 6d 75 6c 74 61 6e 65 6f 75 73 6c 79 20 66 72 6f  multaneously fro
3450: 6d 20 74 77 6f 20 73 65 70 61 72 61 74 65 20 74  m two separate t
3460: 68 72 65 61 64 73 2e 0a 3c 2f 70 3e 3c 2f 64 64  hreads..</p></dd
3470: 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 4e 4f 4c  >.<dt>SQLITE_NOL
3480: 46 53 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54  FS</dt>.<dd><p>T
3490: 68 69 73 20 65 72 72 6f 72 20 6d 65 61 6e 73 20  his error means 
34a0: 74 68 61 74 20 79 6f 75 20 68 61 76 65 20 61 74  that you have at
34b0: 74 65 6d 70 74 73 20 74 6f 20 63 72 65 61 74 65  tempts to create
34c0: 20 6f 72 20 61 63 63 65 73 73 20 61 20 66 69 6c   or access a fil
34d0: 65 0a 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e.database file 
34e0: 74 68 61 74 20 69 73 20 6c 61 72 67 65 72 20 74  that is larger t
34f0: 68 61 74 20 32 47 42 20 6f 6e 20 61 20 6c 65 67  hat 2GB on a leg
3500: 61 63 79 20 55 6e 69 78 20 6d 61 63 68 69 6e 65  acy Unix machine
3510: 20 74 68 61 74 0a 6c 61 63 6b 73 20 6c 61 72 67   that.lacks larg
3520: 65 20 66 69 6c 65 20 73 75 70 70 6f 72 74 2e 0a  e file support..
3530: 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51  </p></dd>.<dt>SQ
3540: 4c 49 54 45 5f 41 55 54 48 3c 2f 64 74 3e 0a 3c  LITE_AUTH</dt>.<
3550: 64 64 3e 3c 70 3e 54 68 69 73 20 65 72 72 6f 72  dd><p>This error
3560: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
3570: 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
3580: 61 6c 6c 62 61 63 6b 0a 68 61 73 20 64 69 73 61  allback.has disa
3590: 6c 6c 6f 77 65 64 20 74 68 65 20 53 51 4c 20 79  llowed the SQL y
35a0: 6f 75 20 61 72 65 20 61 74 74 65 6d 70 74 69 6e  ou are attemptin
35b0: 67 20 74 6f 20 65 78 65 63 75 74 65 2e 0a 3c 2f  g to execute..</
35c0: 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49  p></dd>.<dt>SQLI
35d0: 54 45 5f 52 4f 57 3c 2f 64 74 3e 0a 3c 64 64 3e  TE_ROW</dt>.<dd>
35e0: 3c 70 3e 54 68 69 73 20 69 73 20 6f 6e 65 20 6f  <p>This is one o
35f0: 66 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  f the return cod
3600: 65 73 20 66 72 6f 6d 20 74 68 65 0a 3c 62 3e 73  es from the.<b>s
3610: 71 6c 69 74 65 5f 73 74 65 70 3c 2f 62 3e 20 72  qlite_step</b> r
3620: 6f 75 74 69 6e 65 20 77 68 69 63 68 20 69 73 20  outine which is 
3630: 70 61 72 74 20 6f 66 20 74 68 65 20 6e 6f 6e 2d  part of the non-
3640: 63 61 6c 6c 62 61 63 6b 20 41 50 49 2e 0a 49 74  callback API..It
3650: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
3660: 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 72  another row of r
3670: 65 73 75 6c 74 20 64 61 74 61 20 69 73 20 61 76  esult data is av
3680: 61 69 6c 61 62 6c 65 2e 0a 3c 2f 70 3e 3c 2f 64  ailable..</p></d
3690: 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 44 4f  d>.<dt>SQLITE_DO
36a0: 4e 45 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54  NE</dt>.<dd><p>T
36b0: 68 69 73 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  his is one of th
36c0: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 73 20 66  e return codes f
36d0: 72 6f 6d 20 74 68 65 0a 3c 62 3e 73 71 6c 69 74  rom the.<b>sqlit
36e0: 65 5f 73 74 65 70 3c 2f 62 3e 20 72 6f 75 74 69  e_step</b> routi
36f0: 6e 65 20 77 68 69 63 68 20 69 73 20 70 61 72 74  ne which is part
3700: 20 6f 66 20 74 68 65 20 6e 6f 6e 2d 63 61 6c 6c   of the non-call
3710: 62 61 63 6b 20 41 50 49 2e 0a 49 74 20 69 6e 64  back API..It ind
3720: 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
3730: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 68 61  SQL statement ha
3740: 73 20 62 65 65 6e 20 63 6f 6d 70 6c 65 74 65 6c  s been completel
3750: 79 20 65 78 65 63 75 74 65 64 20 61 6e 64 0a 74  y executed and.t
3760: 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 66 69 6e  he <b>sqlite_fin
3770: 61 6c 69 7a 65 3c 2f 62 3e 20 72 6f 75 74 69 6e  alize</b> routin
3780: 65 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65  e is ready to be
3790: 20 63 61 6c 6c 65 64 2e 0a 3c 2f 70 3e 3c 2f 64   called..</p></d
37a0: 64 3e 0a 3c 2f 64 6c 3e 0a 3c 2f 62 6c 6f 63 6b  d>.</dl>.</block
37b0: 71 75 6f 74 65 3e 0a 0a 3c 68 33 3e 32 2e 30 20  quote>..<h3>2.0 
37c0: 41 63 63 65 73 73 69 6e 67 20 44 61 74 61 20 57  Accessing Data W
37d0: 69 74 68 6f 75 74 20 55 73 69 6e 67 20 41 20 43  ithout Using A C
37e0: 61 6c 6c 62 61 63 6b 20 46 75 6e 63 74 69 6f 6e  allback Function
37f0: 3c 2f 68 33 3e 0a 0a 3c 70 3e 0a 54 68 65 20 3c  </h3>..<p>.The <
3800: 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62  b>sqlite_exec</b
3810: 3e 20 72 6f 75 74 69 6e 65 20 64 65 73 63 72 69  > routine descri
3820: 62 65 64 20 61 62 6f 76 65 20 75 73 65 64 20 74  bed above used t
3830: 6f 20 62 65 20 74 68 65 20 6f 6e 6c 79 0a 77 61  o be the only.wa
3840: 79 20 74 6f 20 72 65 74 72 69 65 76 65 20 64 61  y to retrieve da
3850: 74 61 20 66 72 6f 6d 20 61 6e 20 53 51 4c 69 74  ta from an SQLit
3860: 65 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  e database.  But
3870: 20 6d 61 6e 79 20 70 72 6f 67 72 61 6d 6d 65 72   many programmer
3880: 73 20 66 6f 75 6e 64 0a 69 74 20 69 6e 63 6f 6e  s found.it incon
3890: 76 65 6e 69 65 6e 74 20 74 6f 20 75 73 65 20 61  venient to use a
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 74 6f 20 6f 62 74 61 69 6e 20 72 65 73  on to obtain res
38c0: 75 6c 74 73 2e 20 20 53 6f 20 62 65 67 69 6e 6e  ults.  So beginn
38d0: 69 6e 67 0a 77 69 74 68 20 53 51 4c 69 74 65 20  ing.with SQLite 
38e0: 76 65 72 73 69 6f 6e 20 32 2e 37 2e 37 2c 20 61  version 2.7.7, a
38f0: 20 73 65 63 6f 6e 64 20 61 63 63 65 73 73 20 69   second access i
3900: 6e 74 65 72 66 61 63 65 20 69 73 20 61 76 61 69  nterface is avai
3910: 6c 61 62 6c 65 20 74 68 61 74 0a 64 6f 65 73 20  lable that.does 
3920: 6e 6f 74 20 75 73 65 20 63 61 6c 6c 62 61 63 6b  not use callback
3930: 73 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65  s..</p>..<p>.The
3940: 20 6e 65 77 20 69 6e 74 65 72 66 61 63 65 20 75   new interface u
3950: 73 65 73 20 74 68 72 65 65 20 73 65 70 61 72 61  ses three separa
3960: 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20  te functions to 
3970: 72 65 70 6c 61 63 65 20 74 68 65 20 73 69 6e 67  replace the sing
3980: 6c 65 0a 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65  le.<b>sqlite_exe
3990: 63 3c 2f 62 3e 20 66 75 6e 63 74 69 6f 6e 2e 0a  c</b> function..
39a0: 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  </p>..<blockquot
39b0: 65 3e 3c 70 72 65 3e 0a 74 79 70 65 64 65 66 20  e><pre>.typedef 
39c0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 5f 76 6d  struct sqlite_vm
39d0: 20 73 71 6c 69 74 65 5f 76 6d 3b 0a 0a 69 6e 74   sqlite_vm;..int
39e0: 20 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 28   sqlite_compile(
39f0: 0a 20 20 73 71 6c 69 74 65 20 2a 64 62 2c 20 20  .  sqlite *db,  
3a00: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54              /* T
3a10: 68 65 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  he open database
3a20: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3a30: 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 20 2f   *zSql,        /
3a40: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
3a50: 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 2a  to be compiled *
3a60: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
3a70: 2a 70 7a 54 61 69 6c 2c 20 20 20 20 20 2f 2a 20  *pzTail,     /* 
3a80: 4f 55 54 3a 20 75 6e 63 6f 6d 70 69 6c 65 64 20  OUT: uncompiled 
3a90: 74 61 69 6c 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tail of zSql */.
3aa0: 20 20 73 71 6c 69 74 65 5f 76 6d 20 2a 2a 70 70    sqlite_vm **pp
3ab0: 56 6d 2c 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  Vm,        /* OU
3ac0: 54 3a 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d  T: the virtual m
3ad0: 61 63 68 69 6e 65 20 74 6f 20 65 78 65 63 75 74  achine to execut
3ae0: 65 20 7a 53 71 6c 20 2a 2f 0a 20 20 63 68 61 72  e zSql */.  char
3af0: 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
3b00: 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 45 72 72       /* OUT: Err
3b10: 6f 72 20 6d 65 73 73 61 67 65 2e 20 2a 2f 0a 29  or message. */.)
3b20: 3b 0a 0a 69 6e 74 20 73 71 6c 69 74 65 5f 73 74  ;..int sqlite_st
3b30: 65 70 28 0a 20 20 73 71 6c 69 74 65 5f 76 6d 20  ep(.  sqlite_vm 
3b40: 2a 70 56 6d 2c 20 20 20 20 20 20 20 20 20 20 2f  *pVm,          /
3b50: 2a 20 54 68 65 20 76 69 72 74 75 61 6c 20 6d 61  * The virtual ma
3b60: 63 68 69 6e 65 20 74 6f 20 65 78 65 63 75 74 65  chine to execute
3b70: 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 2c 20 20   */.  int *pN,  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3b90: 2a 20 4f 55 54 3a 20 4e 75 6d 62 65 72 20 6f 66  * OUT: Number of
3ba0: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 72 65 73 75   columns in resu
3bb0: 6c 74 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  lt */.  const ch
3bc0: 61 72 20 2a 2a 2a 70 61 7a 56 61 6c 75 65 2c 20  ar ***pazValue, 
3bd0: 20 2f 2a 20 4f 55 54 3a 20 43 6f 6c 75 6d 6e 20   /* OUT: Column 
3be0: 64 61 74 61 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  data */.  const 
3bf0: 63 68 61 72 20 2a 2a 2a 70 61 7a 43 6f 6c 4e 61  char ***pazColNa
3c00: 6d 65 20 2f 2a 20 4f 55 54 3a 20 43 6f 6c 75 6d  me /* OUT: Colum
3c10: 6e 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61  n names and data
3c20: 74 79 70 65 73 20 2a 2f 0a 29 3b 0a 0a 69 6e 74  types */.);..int
3c30: 20 73 71 6c 69 74 65 5f 66 69 6e 61 6c 69 7a 65   sqlite_finalize
3c40: 28 0a 20 20 73 71 6c 69 74 65 5f 76 6d 20 2a 70  (.  sqlite_vm *p
3c50: 56 6d 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  Vm,          /* 
3c60: 54 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68  The virtual mach
3c70: 69 6e 65 20 74 6f 20 62 65 20 66 69 6e 61 6c 69  ine to be finali
3c80: 7a 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  zed */.  char **
3c90: 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 20  pzErrMsg        
3ca0: 20 20 2f 2a 20 4f 55 54 3a 20 45 72 72 6f 72 20    /* OUT: Error 
3cb0: 6d 65 73 73 61 67 65 20 2a 2f 0a 29 3b 0a 3c 2f  message */.);.</
3cc0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
3cd0: 3e 0a 0a 3c 70 3e 0a 54 68 65 20 73 74 72 61 74  >..<p>.The strat
3ce0: 65 67 79 20 69 73 20 74 6f 20 63 6f 6d 70 69 6c  egy is to compil
3cf0: 65 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  e a single SQL s
3d00: 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 0a 3c  tatement using.<
3d10: 62 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65  b>sqlite_compile
3d20: 3c 2f 62 3e 20 74 68 65 6e 20 69 6e 76 6f 6b 65  </b> then invoke
3d30: 20 3c 62 3e 73 71 6c 69 74 65 5f 73 74 65 70 3c   <b>sqlite_step<
3d40: 2f 62 3e 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  /b> multiple tim
3d50: 65 73 2c 0a 6f 6e 63 65 20 66 6f 72 20 65 61 63  es,.once for eac
3d60: 68 20 72 6f 77 20 6f 66 20 6f 75 74 70 75 74 2c  h row of output,
3d70: 20 61 6e 64 20 66 69 6e 61 6c 6c 79 20 63 61 6c   and finally cal
3d80: 6c 20 3c 62 3e 73 71 6c 69 74 65 5f 66 69 6e 61  l <b>sqlite_fina
3d90: 6c 69 7a 65 3c 2f 62 3e 0a 74 6f 20 63 6c 65 61  lize</b>.to clea
3da0: 6e 20 75 70 20 61 66 74 65 72 20 74 68 65 20 53  n up after the S
3db0: 51 4c 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  QL has finished 
3dc0: 65 78 65 63 75 74 69 6f 6e 2e 0a 3c 2f 70 3e 0a  execution..</p>.
3dd0: 0a 3c 68 34 3e 32 2e 31 20 43 6f 6d 70 69 6c 69  .<h4>2.1 Compili
3de0: 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
3df0: 65 6e 74 20 49 6e 74 6f 20 41 20 56 69 72 74 75  ent Into A Virtu
3e00: 61 6c 20 4d 61 63 68 69 6e 65 3c 2f 68 34 3e 0a  al Machine</h4>.
3e10: 0a 3c 70 3e 0a 54 68 65 20 3c 62 3e 73 71 6c 69  .<p>.The <b>sqli
3e20: 74 65 5f 63 6f 6d 70 69 6c 65 3c 2f 62 3e 20 22  te_compile</b> "
3e30: 63 6f 6d 70 69 6c 65 73 22 20 61 20 73 69 6e 67  compiles" a sing
3e40: 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
3e50: 20 28 73 70 65 63 69 66 69 65 64 0a 62 79 20 74   (specified.by t
3e60: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
3e70: 74 65 72 29 20 61 6e 64 20 67 65 6e 65 72 61 74  ter) and generat
3e80: 65 73 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  es a virtual mac
3e90: 68 69 6e 65 20 74 68 61 74 20 69 73 20 61 62 6c  hine that is abl
3ea0: 65 0a 74 6f 20 65 78 65 63 75 74 65 20 74 68 61  e.to execute tha
3eb0: 74 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 0a 41  t statement.  .A
3ec0: 73 20 77 69 74 68 20 6d 75 73 74 20 69 6e 74 65  s with must inte
3ed0: 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 2c 20  rface routines, 
3ee0: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
3ef0: 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ter must be a po
3f00: 69 6e 74 65 72 0a 74 6f 20 61 6e 20 73 71 6c 69  inter.to an sqli
3f10: 74 65 20 73 74 72 75 63 74 75 72 65 20 74 68 61  te structure tha
3f20: 74 20 77 61 73 20 6f 62 74 61 69 6e 65 64 20 66  t was obtained f
3f30: 72 6f 6d 20 61 20 70 72 69 6f 72 20 63 61 6c 6c  rom a prior call
3f40: 20 74 6f 0a 3c 62 3e 73 71 6c 69 74 65 5f 6f 70   to.<b>sqlite_op
3f50: 65 6e 3c 2f 62 3e 2e 0a 0a 3c 70 3e 0a 41 20 70  en</b>...<p>.A p
3f60: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 76 69  ointer to the vi
3f70: 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 73  rtual machine is
3f80: 20 73 74 6f 72 65 64 20 69 6e 20 61 20 70 6f 69   stored in a poi
3f90: 6e 74 65 72 20 77 68 69 63 68 20 69 73 20 70 61  nter which is pa
3fa0: 73 73 65 64 0a 69 6e 20 61 73 20 74 68 65 20 34  ssed.in as the 4
3fb0: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 53 70  th parameter..Sp
3fc0: 61 63 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ace to hold the 
3fd0: 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
3fe0: 69 73 20 64 79 6e 61 6d 69 63 61 6c 6c 79 20 61  is dynamically a
3ff0: 6c 6c 6f 63 61 74 65 64 2e 20 20 54 6f 20 61 76  llocated.  To av
4000: 6f 69 64 0a 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid.a memory lea
4010: 6b 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  k, the calling f
4020: 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 69 6e 76  unction must inv
4030: 6f 6b 65 0a 3c 62 3e 73 71 6c 69 74 65 5f 66 69  oke.<b>sqlite_fi
4040: 6e 61 6c 69 7a 65 3c 2f 62 3e 20 6f 6e 20 74 68  nalize</b> on th
4050: 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  e virtual machin
4060: 65 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  e after it has f
4070: 69 6e 69 73 68 65 64 0a 77 69 74 68 20 69 74 2e  inished.with it.
4080: 0a 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74  .The 4th paramet
4090: 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
40a0: 20 4e 55 4c 4c 20 69 66 20 61 6e 20 65 72 72 6f   NULL if an erro
40b0: 72 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65 64  r is encountered
40c0: 20 64 75 72 69 6e 67 0a 63 6f 6d 70 69 6c 61 74   during.compilat
40d0: 69 6f 6e 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49  ion..</p>..<p>.I
40e0: 66 20 61 6e 79 20 65 72 72 6f 72 73 20 61 72 65  f any errors are
40f0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 64 75 72   encountered dur
4100: 69 6e 67 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 2c  ing compilation,
4110: 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
4120: 65 20 69 73 0a 77 72 69 74 74 65 6e 20 69 6e 74  e is.written int
4130: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
4140: 64 20 66 72 6f 6d 20 3c 62 3e 6d 61 6c 6c 6f 63  d from <b>malloc
4150: 3c 2f 62 3e 20 61 6e 64 20 74 68 65 20 35 74 68  </b> and the 5th
4160: 20 70 61 72 61 6d 65 74 65 72 0a 69 73 20 6d 61   parameter.is ma
4170: 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
4180: 68 61 74 20 6d 65 6d 6f 72 79 2e 20 20 49 66 20  hat memory.  If 
4190: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
41a0: 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a  r is NULL, then.
41b0: 6e 6f 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  no error message
41c0: 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 20 20   is generated.  
41d0: 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  If the 5th param
41e0: 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  eter is not NULL
41f0: 2c 20 74 68 65 6e 0a 74 68 65 20 63 61 6c 6c 69  , then.the calli
4200: 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ng function shou
4210: 6c 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  ld dispose of th
4220: 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 74 61 69 6e  e memory contain
4230: 69 6e 67 20 74 68 65 20 65 72 72 6f 72 0a 6d 65  ing the error.me
4240: 73 73 61 67 65 20 62 79 20 63 61 6c 6c 69 6e 67  ssage by calling
4250: 20 3c 62 3e 73 71 6c 69 74 65 5f 66 72 65 65 6d   <b>sqlite_freem
4260: 65 6d 3c 2f 62 3e 2e 0a 3c 2f 70 3e 0a 0a 3c 70  em</b>..</p>..<p
4270: 3e 0a 49 66 20 74 68 65 20 32 6e 64 20 70 61 72  >.If the 2nd par
4280: 61 6d 65 74 65 72 20 61 63 74 75 61 6c 6c 79 20  ameter actually 
4290: 63 6f 6e 74 61 69 6e 73 20 74 77 6f 20 6f 72 20  contains two or 
42a0: 6d 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 73 20  more statements 
42b0: 6f 66 20 53 51 4c 2c 0a 6f 6e 6c 79 20 74 68 65  of SQL,.only the
42c0: 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
42d0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 2e 20 20 28   is compiled.  (
42e0: 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e  This is differen
42f0: 74 20 66 72 6f 6d 20 74 68 65 0a 62 65 68 61 76  t from the.behav
4300: 69 6f 72 20 6f 66 20 3c 62 3e 73 71 6c 69 74 65  ior of <b>sqlite
4310: 5f 65 78 65 63 3c 2f 62 3e 20 77 68 69 63 68 20  _exec</b> which 
4320: 65 78 65 63 75 74 65 73 20 61 6c 6c 20 53 51 4c  executes all SQL
4330: 20 73 74 61 74 65 6d 65 6e 74 73 0a 69 6e 20 69   statements.in i
4340: 74 73 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  ts input string.
4350: 29 20 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  )  The 3rd param
4360: 65 74 65 72 20 74 6f 20 3c 62 3e 73 71 6c 69 74  eter to <b>sqlit
4370: 65 5f 63 6f 6d 70 69 6c 65 3c 2f 62 3e 0a 69 73  e_compile</b>.is
4380: 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
4390: 6f 20 74 68 65 20 66 69 72 73 74 20 63 68 61 72  o the first char
43a0: 61 63 74 65 72 20 62 65 79 6f 6e 64 20 74 68 65  acter beyond the
43b0: 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
43c0: 74 0a 73 74 61 74 65 6d 65 6e 74 20 6f 66 20 53  t.statement of S
43d0: 51 4c 20 69 6e 20 74 68 65 20 69 6e 70 75 74 2e  QL in the input.
43e0: 20 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72    If the 2nd par
43f0: 61 6d 65 74 65 72 20 63 6f 6e 74 61 69 6e 73 20  ameter contains 
4400: 6f 6e 6c 79 0a 61 20 73 69 6e 67 6c 65 20 53 51  only.a single SQ
4410: 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  L statement, the
4420: 6e 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  n the 3rd parame
4430: 74 65 72 20 77 69 6c 6c 20 62 65 20 6d 61 64 65  ter will be made
4440: 20 74 6f 20 70 6f 69 6e 74 0a 74 6f 20 74 68 65   to point.to the
4450: 20 27 5c 30 30 30 27 20 74 65 72 6d 69 6e 61 74   '\000' terminat
4460: 6f 72 20 61 74 20 74 68 65 20 65 6e 64 20 6f 66  or at the end of
4470: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4480: 65 72 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 4f 6e  er..</p>..<p>.On
4490: 20 73 75 63 63 65 73 73 2c 20 3c 62 3e 73 71 6c   success, <b>sql
44a0: 69 74 65 5f 63 6f 6d 70 69 6c 65 3c 2f 62 3e 20  ite_compile</b> 
44b0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
44c0: 4b 2e 0a 4f 74 68 65 72 77 69 73 65 20 61 6e 64  K..Otherwise and
44d0: 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
44e0: 65 74 75 72 6e 65 64 2e 0a 3c 2f 70 3e 0a 0a 3c  eturned..</p>..<
44f0: 68 34 3e 32 2e 32 20 53 74 65 70 2d 42 79 2d 53  h4>2.2 Step-By-S
4500: 74 65 70 20 45 78 65 63 75 74 69 6f 6e 20 4f 66  tep Execution Of
4510: 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
4520: 74 3c 2f 68 34 3e 0a 0a 3c 70 3e 0a 41 66 74 65  t</h4>..<p>.Afte
4530: 72 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  r a virtual mach
4540: 69 6e 65 20 68 61 73 20 62 65 65 6e 20 67 65 6e  ine has been gen
4550: 65 72 61 74 65 64 20 75 73 69 6e 67 20 3c 62 3e  erated using <b>
4560: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 3c 2f  sqlite_compile</
4570: 62 3e 0a 69 74 20 69 73 20 65 78 65 63 75 74 65  b>.it is execute
4580: 64 20 62 79 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  d by one or more
4590: 20 63 61 6c 6c 73 20 74 6f 20 3c 62 3e 73 71 6c   calls to <b>sql
45a0: 69 74 65 5f 73 74 65 70 3c 2f 62 3e 2e 20 20 45  ite_step</b>.  E
45b0: 61 63 68 0a 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ach.invocation o
45c0: 66 20 3c 62 3e 73 71 6c 69 74 65 5f 73 74 65 70  f <b>sqlite_step
45d0: 3c 2f 62 3e 2c 20 65 78 63 65 70 74 20 74 68 65  </b>, except the
45e0: 20 6c 61 73 74 20 6f 6e 65 2c 0a 72 65 74 75 72   last one,.retur
45f0: 6e 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  ns a single row 
4600: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 54  of the result..T
4610: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
4620: 75 6d 6e 73 20 69 6e 20 20 74 68 65 20 72 65 73  umns in  the res
4630: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ult is stored in
4640: 20 74 68 65 20 69 6e 74 65 67 65 72 20 74 68 61   the integer tha
4650: 74 0a 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  t.the 2nd parame
4660: 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 54  ter points to..T
4670: 68 65 20 70 6f 69 6e 74 65 72 20 73 70 65 63 69  he pointer speci
4680: 66 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20  fied by the 3rd 
4690: 70 61 72 61 6d 65 74 65 72 20 69 73 20 6d 61 64  parameter is mad
46a0: 65 20 74 6f 20 70 6f 69 6e 74 0a 74 6f 20 61 6e  e to point.to an
46b0: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
46c0: 72 73 20 74 6f 20 63 6f 6c 75 6d 6e 20 76 61 6c  rs to column val
46d0: 75 65 73 2e 0a 54 68 65 20 70 6f 69 6e 74 65 72  ues..The pointer
46e0: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
46f0: 6d 65 74 65 72 20 69 73 20 6d 61 64 65 20 74 6f  meter is made to
4700: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 72 72   point to an arr
4710: 61 79 0a 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay.of pointers t
4720: 6f 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 61  o column names a
4730: 6e 64 20 64 61 74 61 74 79 70 65 73 2e 0a 54 68  nd datatypes..Th
4740: 65 20 32 6e 64 20 74 68 72 6f 75 67 68 20 34 74  e 2nd through 4t
4750: 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
4760: 3c 62 3e 73 71 6c 69 74 65 5f 73 74 65 70 3c 2f  <b>sqlite_step</
4770: 62 3e 20 63 6f 6e 76 65 79 20 74 68 65 0a 73 61  b> convey the.sa
4780: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
4790: 73 20 74 68 65 20 32 6e 64 20 74 68 72 6f 75 67  s the 2nd throug
47a0: 68 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  h 4th parameters
47b0: 20 6f 66 20 74 68 65 0a 3c 62 3e 63 61 6c 6c 62   of the.<b>callb
47c0: 61 63 6b 3c 2f 62 3e 20 72 6f 75 74 69 6e 65 20  ack</b> routine 
47d0: 77 68 65 6e 20 75 73 69 6e 67 0a 74 68 65 20 3c  when using.the <
47e0: 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62  b>sqlite_exec</b
47f0: 3e 20 69 6e 74 65 72 66 61 63 65 2e 20 20 45 78  > interface.  Ex
4800: 63 65 70 74 2c 20 77 69 74 68 20 3c 62 3e 73 71  cept, with <b>sq
4810: 6c 69 74 65 5f 73 74 65 70 3c 2f 62 3e 0a 74 68  lite_step</b>.th
4820: 65 20 63 6f 6c 75 6d 6e 20 64 61 74 61 74 79 70  e column datatyp
4830: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
4840: 20 61 6c 77 61 79 73 20 69 6e 63 6c 75 64 65 64   always included
4850: 20 69 6e 20 74 68 65 20 69 6e 20 74 68 65 0a 34   in the in the.4
4860: 74 68 20 70 61 72 61 6d 65 74 65 72 20 72 65 67  th parameter reg
4870: 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
4880: 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 3c 61  er or not the.<a
4890: 20 68 72 65 66 3d 22 6c 61 6e 67 2e 68 74 6d 6c   href="lang.html
48a0: 23 70 72 61 67 6d 61 5f 73 68 6f 77 5f 64 61 74  #pragma_show_dat
48b0: 61 74 79 70 65 73 22 3e 53 48 4f 57 5f 44 41 54  atypes">SHOW_DAT
48c0: 41 54 59 50 45 53 3c 2f 61 3e 20 70 72 61 67 6d  ATYPES</a> pragm
48d0: 61 0a 69 73 20 6f 6e 20 6f 72 20 6f 66 66 2e 0a  a.is on or off..
48e0: 3c 2f 70 3e 0a 0a 3c 70 3e 0a 45 61 63 68 20 69  </p>..<p>.Each i
48f0: 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 3c 62 3e  nvocation of <b>
4900: 73 71 6c 69 74 65 5f 73 74 65 70 3c 2f 62 3e 20  sqlite_step</b> 
4910: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
4920: 65 72 20 63 6f 64 65 20 74 68 61 74 0a 69 6e 64  er code that.ind
4930: 69 63 61 74 65 73 20 77 68 61 74 20 68 61 70 70  icates what happ
4940: 65 6e 65 64 20 64 75 72 69 6e 67 20 74 68 61 74  ened during that
4950: 20 73 74 65 70 2e 20 20 54 68 69 73 20 63 6f 64   step.  This cod
4960: 65 20 6d 61 79 20 62 65 0a 53 51 4c 49 54 45 5f  e may be.SQLITE_
4970: 42 55 53 59 2c 20 53 51 4c 49 54 45 5f 52 4f 57  BUSY, SQLITE_ROW
4980: 2c 20 53 51 4c 49 54 45 5f 44 4f 4e 45 2c 20 53  , SQLITE_DONE, S
4990: 51 4c 49 54 45 5f 45 52 52 4f 52 2c 20 6f 72 0a  QLITE_ERROR, or.
49a0: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 3c  SQLITE_MISUSE..<
49b0: 2f 70 3e 0a 0a 3c 70 3e 0a 49 66 20 74 68 65 20  /p>..<p>.If the 
49c0: 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
49d0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 70 65  is unable to ope
49e0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
49f0: 69 6c 65 20 62 65 63 61 75 73 65 0a 69 74 20 69  ile because.it i
4a00: 73 20 6c 6f 63 6b 65 64 20 62 79 20 61 6e 6f 74  s locked by anot
4a10: 68 65 72 20 74 68 72 65 61 64 20 6f 72 20 70 72  her thread or pr
4a20: 6f 63 65 73 73 2c 20 3c 62 3e 73 71 6c 69 74 65  ocess, <b>sqlite
4a30: 5f 73 74 65 70 3c 2f 62 3e 0a 77 69 6c 6c 20 72  _step</b>.will r
4a40: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53  eturn SQLITE_BUS
4a50: 59 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  Y.  The calling 
4a60: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
4a70: 64 6f 20 73 6f 6d 65 20 6f 74 68 65 72 0a 61 63  do some other.ac
4a80: 74 69 76 69 74 79 2c 20 6f 72 20 73 6c 65 65 70  tivity, or sleep
4a90: 2c 20 66 6f 72 20 61 20 73 68 6f 72 74 20 61 6d  , for a short am
4aa0: 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 74 6f 20  ount of time to 
4ab0: 67 69 76 65 20 74 68 65 20 6c 6f 63 6b 20 61 0a  give the lock a.
4ac0: 63 68 61 6e 63 65 20 74 6f 20 63 6c 65 61 72 2c  chance to clear,
4ad0: 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 3c 62 3e   then invoke <b>
4ae0: 73 71 6c 69 74 65 5f 73 74 65 70 3c 2f 62 3e 20  sqlite_step</b> 
4af0: 61 67 61 69 6e 2e 20 20 54 68 69 73 20 63 61 6e  again.  This can
4b00: 0a 62 65 20 72 65 70 65 61 74 65 64 20 61 73 20  .be repeated as 
4b10: 6d 61 6e 79 20 74 69 6d 65 73 20 61 73 20 64 65  many times as de
4b20: 73 69 72 65 64 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e  sired..</p>..<p>
4b30: 0a 57 68 65 6e 65 76 65 72 20 61 6e 6f 74 68 65  .Whenever anothe
4b40: 72 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 20  r row of result 
4b50: 64 61 74 61 20 69 73 20 61 76 61 69 6c 61 62 6c  data is availabl
4b60: 65 2c 0a 3c 62 3e 73 71 6c 69 74 65 5f 73 74 65  e,.<b>sqlite_ste
4b70: 70 3c 2f 62 3e 20 77 69 6c 6c 20 72 65 74 75 72  p</b> will retur
4b80: 6e 20 53 51 4c 49 54 45 5f 52 4f 57 2e 20 20 54  n SQLITE_ROW.  T
4b90: 68 65 20 72 6f 77 20 64 61 74 61 20 69 73 0a 73  he row data is.s
4ba0: 74 6f 72 65 64 20 69 6e 20 61 6e 20 61 72 72 61  tored in an arra
4bb0: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
4bc0: 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
4bd0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 69   2nd parameter.i
4be0: 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
4bf0: 74 6f 20 74 68 69 73 20 61 72 72 61 79 2e 0a 3c  to this array..<
4c00: 2f 70 3e 0a 0a 3c 70 3e 0a 57 68 65 6e 20 61 6c  /p>..<p>.When al
4c10: 6c 20 70 72 6f 63 65 73 73 69 6e 67 20 69 73 20  l processing is 
4c20: 63 6f 6d 70 6c 65 74 65 2c 20 3c 62 3e 73 71 6c  complete, <b>sql
4c30: 69 74 65 5f 73 74 65 70 3c 2f 62 3e 20 77 69 6c  ite_step</b> wil
4c40: 6c 20 72 65 74 75 72 6e 0a 65 69 74 68 65 72 20  l return.either 
4c50: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 6f 72 20 53  SQLITE_DONE or S
4c60: 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 53 51  QLITE_ERROR.  SQ
4c70: 4c 49 54 45 5f 44 4f 4e 45 20 69 6e 64 69 63 61  LITE_DONE indica
4c80: 74 65 73 20 74 68 61 74 20 74 68 65 0a 73 74 61  tes that the.sta
4c90: 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 64  tement completed
4ca0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 6e   successfully an
4cb0: 64 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69  d SQLITE_ERROR i
4cc0: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
4cd0: 65 72 65 0a 77 61 73 20 61 20 72 75 6e 2d 74 69  ere.was a run-ti
4ce0: 6d 65 20 65 72 72 6f 72 2e 20 20 28 54 68 65 20  me error.  (The 
4cf0: 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 65  details of the e
4d00: 72 72 6f 72 20 61 72 65 20 6f 62 74 61 69 6e 65  rror are obtaine
4d10: 64 20 66 72 6f 6d 0a 3c 62 3e 73 71 6c 69 74 65  d from.<b>sqlite
4d20: 5f 66 69 6e 61 6c 69 7a 65 3c 2f 62 3e 2e 29 20  _finalize</b>.) 
4d30: 20 49 74 20 69 73 20 61 20 6d 69 73 75 73 65 20   It is a misuse 
4d40: 6f 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 74  of the library t
4d50: 6f 20 61 74 74 65 6d 70 74 0a 74 6f 20 63 61 6c  o attempt.to cal
4d60: 6c 20 3c 62 3e 73 71 6c 69 74 65 5f 73 74 65 70  l <b>sqlite_step
4d70: 3c 2f 62 3e 20 61 67 61 69 6e 20 61 66 74 65 72  </b> again after
4d80: 20 69 74 20 68 61 73 20 72 65 74 75 72 6e 65 64   it has returned
4d90: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 0a 6f 72 20   SQLITE_DONE.or 
4da0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 3c 2f  SQLITE_ERROR..</
4db0: 70 3e 0a 0a 3c 70 3e 0a 57 68 65 6e 20 3c 62 3e  p>..<p>.When <b>
4dc0: 73 71 6c 69 74 65 5f 73 74 65 70 3c 2f 62 3e 20  sqlite_step</b> 
4dd0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 44  returns SQLITE_D
4de0: 4f 4e 45 20 6f 72 20 53 51 4c 49 54 45 5f 45 52  ONE or SQLITE_ER
4df0: 52 4f 52 2c 0a 74 68 65 20 2a 70 4e 20 61 6e 64  ROR,.the *pN and
4e00: 20 2a 70 61 7a 43 6f 6c 4e 61 6d 65 20 76 61 6c   *pazColName val
4e10: 75 65 73 20 61 72 65 20 73 65 74 20 74 6f 20 74  ues are set to t
4e20: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
4e30: 75 6d 6e 73 0a 69 6e 20 74 68 65 20 72 65 73 75  umns.in the resu
4e40: 6c 74 20 73 65 74 20 61 6e 64 20 74 6f 20 74 68  lt set and to th
4e50: 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
4e60: 6f 6c 75 6d 6e 73 2c 20 6a 75 73 74 20 61 73 20  olumns, just as 
4e70: 74 68 65 79 0a 61 72 65 20 66 6f 72 20 61 6e 20  they.are for an 
4e80: 53 51 4c 49 54 45 5f 52 4f 57 20 72 65 74 75 72  SQLITE_ROW retur
4e90: 6e 2e 20 20 54 68 69 73 20 61 6c 6c 6f 77 73 20  n.  This allows 
4ea0: 74 68 65 20 63 61 6c 6c 69 6e 67 20 63 6f 64 65  the calling code
4eb0: 20 74 6f 0a 66 69 6e 64 20 74 68 65 20 6e 75 6d   to.find the num
4ec0: 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
4ed0: 6c 75 6d 6e 73 20 61 6e 64 20 74 68 65 20 63 6f  lumns and the co
4ee0: 6c 75 6d 6e 20 6e 61 6d 65 73 20 61 6e 64 20 64  lumn names and d
4ef0: 61 74 61 74 79 70 65 73 0a 65 76 65 6e 20 69 66  atatypes.even if
4f00: 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
4f10: 69 73 20 65 6d 70 74 79 2e 20 20 54 68 65 20 2a  is empty.  The *
4f20: 70 61 7a 56 61 6c 75 65 20 70 61 72 61 6d 65 74  pazValue paramet
4f30: 65 72 20 69 73 20 61 6c 77 61 79 73 0a 73 65 74  er is always.set
4f40: 20 74 6f 20 4e 55 4c 4c 20 77 68 65 6e 20 74 68   to NULL when th
4f50: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 73 20 69  e return codes i
4f60: 73 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 6f 72  s SQLITE_DONE or
4f70: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 49   SQLITE_ERROR..I
4f80: 66 20 74 68 65 20 53 51 4c 20 62 65 69 6e 67 20  f the SQL being 
4f90: 65 78 65 63 75 74 65 64 20 69 73 20 61 20 73 74  executed is a st
4fa0: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
4fb0: 73 20 6e 6f 74 0a 72 65 74 75 72 6e 20 61 20 72  s not.return a r
4fc0: 65 73 75 6c 74 20 28 73 75 63 68 20 61 73 20 61  esult (such as a
4fd0: 6e 20 49 4e 53 45 52 54 20 6f 72 20 61 6e 20 55  n INSERT or an U
4fe0: 50 44 41 54 45 29 20 74 68 65 6e 20 2a 70 4e 20  PDATE) then *pN 
4ff0: 77 69 6c 6c 0a 62 65 20 73 65 74 20 74 6f 20 7a  will.be set to z
5000: 65 72 6f 20 61 6e 64 20 2a 70 61 7a 43 6f 6c 4e  ero and *pazColN
5010: 61 6d 65 20 77 69 6c 6c 20 62 65 20 73 65 74 20  ame will be set 
5020: 74 6f 20 4e 55 4c 4c 2e 0a 3c 2f 70 3e 0a 0a 3c  to NULL..</p>..<
5030: 70 3e 0a 49 66 20 79 6f 75 20 61 62 75 73 65 20  p>.If you abuse 
5040: 74 68 65 20 6c 69 62 72 61 72 79 20 62 79 20 74  the library by t
5050: 72 79 69 6e 67 20 74 6f 20 63 61 6c 6c 20 3c 62  rying to call <b
5060: 3e 73 71 6c 69 74 65 5f 73 74 65 70 3c 2f 62 3e  >sqlite_step</b>
5070: 0a 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79  .inappropriately
5080: 20 69 74 20 77 69 6c 6c 20 61 74 74 65 6d 70 74   it will attempt
5090: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
50a0: 49 53 55 53 45 2e 0a 54 68 69 73 20 63 61 6e 20  ISUSE..This can 
50b0: 68 61 70 70 65 6e 20 69 66 20 79 6f 75 20 63 61  happen if you ca
50c0: 6c 6c 20 73 71 6c 69 74 65 5f 73 74 65 70 28 29  ll sqlite_step()
50d0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 76 69 72   on the same vir
50e0: 74 75 61 6c 20 6d 61 63 68 69 6e 65 0a 61 74 20  tual machine.at 
50f0: 74 68 65 20 73 61 6d 65 0a 74 69 6d 65 20 66 72  the same.time fr
5100: 6f 6d 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  om two or more t
5110: 68 72 65 61 64 73 20 6f 72 20 69 66 20 79 6f 75  hreads or if you
5120: 20 63 61 6c 6c 20 73 71 6c 69 74 65 5f 73 74 65   call sqlite_ste
5130: 70 28 29 0a 61 67 61 69 6e 20 61 66 74 65 72 20  p().again after 
5140: 69 74 20 72 65 74 75 72 6e 65 64 20 53 51 4c 49  it returned SQLI
5150: 54 45 5f 44 4f 4e 45 20 6f 72 20 53 51 4c 49 54  TE_DONE or SQLIT
5160: 45 5f 45 52 52 4f 52 20 6f 72 20 69 66 20 79 6f  E_ERROR or if yo
5170: 75 0a 70 61 73 73 20 69 6e 20 61 6e 20 69 6e 76  u.pass in an inv
5180: 61 6c 69 64 20 76 69 72 74 75 61 6c 20 6d 61 63  alid virtual mac
5190: 68 69 6e 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  hine pointer to 
51a0: 73 71 6c 69 74 65 5f 73 74 65 70 28 29 2e 0a 59  sqlite_step()..Y
51b0: 6f 75 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65  ou should not de
51c0: 70 65 6e 64 20 6f 6e 20 74 68 65 20 53 51 4c 49  pend on the SQLI
51d0: 54 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e  TE_MISUSE return
51e0: 20 63 6f 64 65 20 74 6f 20 69 6e 64 69 63 61 74   code to indicat
51f0: 65 0a 61 6e 20 65 72 72 6f 72 2e 20 20 49 74 20  e.an error.  It 
5200: 69 73 20 70 6f 73 73 69 62 6c 65 20 74 68 61 74  is possible that
5210: 20 61 20 6d 69 73 75 73 65 20 6f 66 20 74 68 65   a misuse of the
5220: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
5230: 67 6f 0a 75 6e 64 65 74 65 63 74 65 64 20 61 6e  go.undetected an
5240: 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 70 72  d result in a pr
5250: 6f 67 72 61 6d 20 63 72 61 73 68 2e 20 20 54 68  ogram crash.  Th
5260: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
5270: 69 73 0a 69 6e 74 65 6e 64 65 64 20 61 73 20 61  is.intended as a
5280: 20 64 65 62 75 67 67 69 6e 67 20 61 69 64 20 6f   debugging aid o
5290: 6e 6c 79 20 2d 20 74 6f 20 68 65 6c 70 20 79 6f  nly - to help yo
52a0: 75 20 64 65 74 65 63 74 20 69 6e 63 6f 72 72 65  u detect incorre
52b0: 63 74 0a 75 73 61 67 65 20 70 72 69 6f 72 20 74  ct.usage prior t
52c0: 6f 20 61 20 6d 69 73 68 61 70 2e 20 20 54 68 65  o a mishap.  The
52d0: 20 6d 69 73 75 73 65 20 64 65 74 65 63 74 69 6f   misuse detectio
52e0: 6e 20 6c 6f 67 69 63 20 69 73 20 6e 6f 74 20 67  n logic is not g
52f0: 75 61 72 61 6e 74 65 65 64 0a 74 6f 20 77 6f 72  uaranteed.to wor
5300: 6b 20 69 6e 20 65 76 65 72 79 20 63 61 73 65 2e  k in every case.
5310: 0a 3c 2f 70 3e 0a 0a 3c 68 34 3e 32 2e 33 20 44  .</p>..<h4>2.3 D
5320: 65 6c 65 74 69 6e 67 20 41 20 56 69 72 74 75 61  eleting A Virtua
5330: 6c 20 4d 61 63 68 69 6e 65 3c 2f 68 34 3e 0a 0a  l Machine</h4>..
5340: 3c 70 3e 0a 45 76 65 72 79 20 76 69 72 74 75 61  <p>.Every virtua
5350: 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 3c  l machine that <
5360: 62 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65  b>sqlite_compile
5370: 3c 2f 62 3e 20 63 72 65 61 74 65 73 20 73 68 6f  </b> creates sho
5380: 75 6c 64 0a 65 76 65 6e 74 75 61 6c 6c 79 20 62  uld.eventually b
5390: 65 20 68 61 6e 64 65 64 20 74 6f 20 3c 62 3e 73  e handed to <b>s
53a0: 71 6c 69 74 65 5f 66 69 6e 61 6c 69 7a 65 3c 2f  qlite_finalize</
53b0: 62 3e 2e 20 20 54 68 65 20 73 71 6c 69 74 65 5f  b>.  The sqlite_
53c0: 66 69 6e 61 6c 69 7a 65 28 29 0a 70 72 6f 63 65  finalize().proce
53d0: 64 75 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 73  dure deallocates
53e0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6e 64 20   the memory and 
53f0: 6f 74 68 65 72 20 72 65 73 6f 75 72 63 65 73 20  other resources 
5400: 74 68 61 74 20 74 68 65 20 76 69 72 74 75 61 6c  that the virtual
5410: 0a 6d 61 63 68 69 6e 65 20 75 73 65 73 2e 20 20  .machine uses.  
5420: 46 61 69 6c 75 72 65 20 74 6f 20 63 61 6c 6c 20  Failure to call 
5430: 73 71 6c 69 74 65 5f 66 69 6e 61 6c 69 7a 65 28  sqlite_finalize(
5440: 29 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  ) will result in
5450: 20 0a 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73   .resource leaks
5460: 20 69 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d   in your program
5470: 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20  ..</p>..<p>.The 
5480: 3c 62 3e 73 71 6c 69 74 65 5f 66 69 6e 61 6c 69  <b>sqlite_finali
5490: 7a 65 3c 2f 62 3e 20 72 6f 75 74 69 6e 65 20 61  ze</b> routine a
54a0: 6c 73 6f 20 72 65 74 75 72 6e 73 20 74 68 65 20  lso returns the 
54b0: 72 65 73 75 6c 74 20 63 6f 64 65 0a 74 68 61 74  result code.that
54c0: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
54d0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ss or failure of
54e0: 20 74 68 65 20 53 51 4c 20 6f 70 65 72 61 74 69   the SQL operati
54f0: 6f 6e 20 74 68 61 74 20 74 68 65 0a 76 69 72 74  on that the.virt
5500: 75 61 6c 20 6d 61 63 68 69 6e 65 20 63 61 72 72  ual machine carr
5510: 69 65 64 20 6f 75 74 2e 0a 54 68 65 20 76 61 6c  ied out..The val
5520: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
5530: 71 6c 69 74 65 5f 66 69 6e 61 6c 69 7a 65 28 29  qlite_finalize()
5540: 20 77 69 6c 6c 20 62 65 20 74 68 65 20 73 61 6d   will be the sam
5550: 65 20 61 73 20 77 6f 75 6c 64 0a 68 61 76 65 20  e as would.have 
5560: 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 68 61  been returned ha
5570: 64 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 62  d the same SQL b
5580: 65 65 6e 20 65 78 65 63 75 74 65 64 20 62 79 20  een executed by 
5590: 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f  <b>sqlite_exec</
55a0: 62 3e 2e 0a 54 68 65 20 65 72 72 6f 72 20 6d 65  b>..The error me
55b0: 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 77  ssage returned w
55c0: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
55d0: 73 61 6d 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a  same..</p>..<p>.
55e0: 49 74 20 69 73 20 61 63 63 65 70 74 61 62 6c 65  It is acceptable
55f0: 20 74 6f 20 63 61 6c 6c 20 3c 62 3e 73 71 6c 69   to call <b>sqli
5600: 74 65 5f 66 69 6e 61 6c 69 7a 65 3c 2f 62 3e 20  te_finalize</b> 
5610: 6f 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  on a virtual mac
5620: 68 69 6e 65 0a 62 65 66 6f 72 65 20 3c 62 3e 73  hine.before <b>s
5630: 71 6c 69 74 65 5f 73 74 65 70 3c 2f 62 3e 20 68  qlite_step</b> h
5640: 61 73 20 72 65 74 75 72 6e 65 64 20 53 51 4c 49  as returned SQLI
5650: 54 45 5f 44 4f 4e 45 2e 20 20 44 6f 69 6e 67 20  TE_DONE.  Doing 
5660: 73 6f 20 68 61 73 0a 74 68 65 20 65 66 66 65 63  so has.the effec
5670: 74 20 6f 66 20 69 6e 74 65 72 72 75 70 74 69 6e  t of interruptin
5680: 67 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  g the operation 
5690: 69 6e 20 70 72 6f 67 72 65 73 73 2e 20 20 50 61  in progress.  Pa
56a0: 72 74 69 61 6c 6c 79 20 63 6f 6d 70 6c 65 74 65  rtially complete
56b0: 64 0a 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 62  d.changes will b
56c0: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e  e rolled back an
56d0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  d the database w
56e0: 69 6c 6c 20 62 65 20 72 65 73 74 6f 72 65 64 20  ill be restored 
56f0: 74 6f 20 69 74 73 0a 6f 72 69 67 69 6e 61 6c 20  to its.original 
5700: 73 74 61 74 65 20 28 75 6e 6c 65 73 73 20 61 6e  state (unless an
5710: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 72 65 63   alternative rec
5720: 6f 76 65 72 79 20 61 6c 67 6f 72 69 74 68 6d 20  overy algorithm 
5730: 69 73 20 73 65 6c 65 63 74 65 64 20 75 73 69 6e  is selected usin
5740: 67 0a 61 6e 20 4f 4e 20 43 4f 4e 46 4c 49 43 54  g.an ON CONFLICT
5750: 20 63 6c 61 75 73 65 20 69 6e 20 74 68 65 20 53   clause in the S
5760: 51 4c 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  QL being execute
5770: 64 2e 29 20 20 54 68 65 20 65 66 66 65 63 74 20  d.)  The effect 
5780: 69 73 20 74 68 65 0a 73 61 6d 65 20 61 73 20 69  is the.same as i
5790: 66 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  f a callback fun
57a0: 63 74 69 6f 6e 20 6f 66 20 3c 62 3e 73 71 6c 69  ction of <b>sqli
57b0: 74 65 5f 65 78 65 63 3c 2f 62 3e 20 68 61 64 20  te_exec</b> had 
57c0: 72 65 74 75 72 6e 65 64 0a 6e 6f 6e 2d 7a 65 72  returned.non-zer
57d0: 6f 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49 74 20  o..</p>..<p>.It 
57e0: 69 73 20 61 6c 73 6f 20 61 63 63 65 70 74 61 62  is also acceptab
57f0: 6c 65 20 74 6f 20 63 61 6c 6c 20 3c 62 3e 73 71  le to call <b>sq
5800: 6c 69 74 65 5f 66 69 6e 61 6c 69 7a 65 3c 2f 62  lite_finalize</b
5810: 3e 20 6f 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  > on a virtual m
5820: 61 63 68 69 6e 65 0a 74 68 61 74 20 68 61 73 20  achine.that has 
5830: 6e 65 76 65 72 20 62 65 65 6e 20 70 61 73 73 65  never been passe
5840: 64 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 73  d to <b>sqlite_s
5850: 74 65 70 3c 2f 62 3e 20 65 76 65 6e 20 6f 6e 63  tep</b> even onc
5860: 65 2e 0a 3c 2f 70 3e 0a 0a 3c 68 33 3e 33 2e 30  e..</p>..<h3>3.0
5870: 20 54 68 65 20 45 78 74 65 6e 64 65 64 20 41 50   The Extended AP
5880: 49 3c 2f 68 33 3e 0a 0a 3c 70 3e 4f 6e 6c 79 20  I</h3>..<p>Only 
5890: 74 68 65 20 74 68 72 65 65 20 63 6f 72 65 20 72  the three core r
58a0: 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65  outines describe
58b0: 64 20 69 6e 20 73 65 63 74 69 6f 6e 20 31 2e 30  d in section 1.0
58c0: 20 61 72 65 20 72 65 71 75 69 72 65 64 20 74 6f   are required to
58d0: 20 75 73 65 0a 53 51 4c 69 74 65 2e 20 20 42 75   use.SQLite.  Bu
58e0: 74 20 74 68 65 72 65 20 61 72 65 20 6d 61 6e 79  t there are many
58f0: 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
5900: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 0a 75   that provide .u
5910: 73 65 66 75 6c 20 69 6e 74 65 72 66 61 63 65 73  seful interfaces
5920: 2e 20 20 54 68 65 73 65 20 65 78 74 65 6e 64 65  .  These extende
5930: 64 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 61  d routines are a
5940: 73 20 66 6f 6c 6c 6f 77 73 3a 0a 3c 2f 70 3e 0a  s follows:.</p>.
5950: 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72  .<blockquote><pr
5960: 65 3e 0a 69 6e 74 20 73 71 6c 69 74 65 5f 6c 61  e>.int sqlite_la
5970: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
5980: 73 71 6c 69 74 65 2a 29 3b 0a 0a 69 6e 74 20 73  sqlite*);..int s
5990: 71 6c 69 74 65 5f 63 68 61 6e 67 65 73 28 73 71  qlite_changes(sq
59a0: 6c 69 74 65 2a 29 3b 0a 0a 69 6e 74 20 73 71 6c  lite*);..int sql
59b0: 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  ite_get_table(. 
59c0: 20 73 71 6c 69 74 65 2a 2c 0a 20 20 63 68 61 72   sqlite*,.  char
59d0: 20 2a 73 71 6c 2c 0a 20 20 63 68 61 72 20 2a 2a   *sql,.  char **
59e0: 2a 72 65 73 75 6c 74 2c 0a 20 20 69 6e 74 20 2a  *result,.  int *
59f0: 6e 72 6f 77 2c 0a 20 20 69 6e 74 20 2a 6e 63 6f  nrow,.  int *nco
5a00: 6c 75 6d 6e 2c 0a 20 20 63 68 61 72 20 2a 2a 65  lumn,.  char **e
5a10: 72 72 6d 73 67 0a 29 3b 0a 0a 76 6f 69 64 20 73  rrmsg.);..void s
5a20: 71 6c 69 74 65 5f 66 72 65 65 5f 74 61 62 6c 65  qlite_free_table
5a30: 28 63 68 61 72 2a 2a 29 3b 0a 0a 76 6f 69 64 20  (char**);..void 
5a40: 73 71 6c 69 74 65 5f 69 6e 74 65 72 72 75 70 74  sqlite_interrupt
5a50: 28 73 71 6c 69 74 65 2a 29 3b 0a 0a 69 6e 74 20  (sqlite*);..int 
5a60: 73 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 65 28  sqlite_complete(
5a70: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
5a80: 3b 0a 0a 76 6f 69 64 20 73 71 6c 69 74 65 5f 62  ;..void sqlite_b
5a90: 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
5aa0: 74 65 2a 2c 20 69 6e 74 20 28 2a 29 28 76 6f 69  te*, int (*)(voi
5ab0: 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69  d*,const char*,i
5ac0: 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 76 6f  nt), void*);..vo
5ad0: 69 64 20 73 71 6c 69 74 65 5f 62 75 73 79 5f 74  id sqlite_busy_t
5ae0: 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 2a 2c 20  imeout(sqlite*, 
5af0: 69 6e 74 20 6d 73 29 3b 0a 0a 63 6f 6e 73 74 20  int ms);..const 
5b00: 63 68 61 72 20 73 71 6c 69 74 65 5f 76 65 72 73  char sqlite_vers
5b10: 69 6f 6e 5b 5d 3b 0a 0a 63 6f 6e 73 74 20 63 68  ion[];..const ch
5b20: 61 72 20 73 71 6c 69 74 65 5f 65 6e 63 6f 64 69  ar sqlite_encodi
5b30: 6e 67 5b 5d 3b 0a 0a 69 6e 74 20 73 71 6c 69 74  ng[];..int sqlit
5b40: 65 5f 65 78 65 63 5f 70 72 69 6e 74 66 28 0a 20  e_exec_printf(. 
5b50: 20 73 71 6c 69 74 65 2a 2c 0a 20 20 63 68 61 72   sqlite*,.  char
5b60: 20 2a 73 71 6c 2c 0a 20 20 69 6e 74 20 28 2a 29   *sql,.  int (*)
5b70: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
5b80: 2a 2c 63 68 61 72 2a 2a 29 2c 0a 20 20 76 6f 69  *,char**),.  voi
5b90: 64 2a 2c 0a 20 20 63 68 61 72 20 2a 2a 65 72 72  d*,.  char **err
5ba0: 6d 73 67 2c 0a 20 20 2e 2e 2e 0a 29 3b 0a 0a 69  msg,.  ....);..i
5bb0: 6e 74 20 73 71 6c 69 74 65 5f 65 78 65 63 5f 76  nt sqlite_exec_v
5bc0: 70 72 69 6e 74 66 28 0a 20 20 73 71 6c 69 74 65  printf(.  sqlite
5bd0: 2a 2c 0a 20 20 63 68 61 72 20 2a 73 71 6c 2c 0a  *,.  char *sql,.
5be0: 20 20 69 6e 74 20 28 2a 29 28 76 6f 69 64 2a 2c    int (*)(void*,
5bf0: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
5c00: 2a 29 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 63  *),.  void*,.  c
5c10: 68 61 72 20 2a 2a 65 72 72 6d 73 67 2c 0a 20 20  har **errmsg,.  
5c20: 76 61 5f 6c 69 73 74 0a 29 3b 0a 0a 69 6e 74 20  va_list.);..int 
5c30: 73 71 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65  sqlite_get_table
5c40: 5f 70 72 69 6e 74 66 28 0a 20 20 73 71 6c 69 74  _printf(.  sqlit
5c50: 65 2a 2c 0a 20 20 63 68 61 72 20 2a 73 71 6c 2c  e*,.  char *sql,
5c60: 0a 20 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 6c  .  char ***resul
5c70: 74 2c 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 0a  t,.  int *nrow,.
5c80: 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 0a    int *ncolumn,.
5c90: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 2c    char **errmsg,
5ca0: 0a 20 20 2e 2e 2e 0a 29 3b 0a 0a 69 6e 74 20 73  .  ....);..int s
5cb0: 71 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 5f  qlite_get_table_
5cc0: 76 70 72 69 6e 74 66 28 0a 20 20 73 71 6c 69 74  vprintf(.  sqlit
5cd0: 65 2a 2c 0a 20 20 63 68 61 72 20 2a 73 71 6c 2c  e*,.  char *sql,
5ce0: 0a 20 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 6c  .  char ***resul
5cf0: 74 2c 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 0a  t,.  int *nrow,.
5d00: 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 0a    int *ncolumn,.
5d10: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 2c    char **errmsg,
5d20: 0a 20 20 76 61 5f 6c 69 73 74 0a 29 3b 0a 0a 63  .  va_list.);..c
5d30: 68 61 72 20 2a 73 71 6c 69 74 65 5f 6d 70 72 69  har *sqlite_mpri
5d40: 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ntf(const char *
5d50: 7a 46 6f 72 6d 61 74 2c 20 2e 2e 2e 29 3b 0a 0a  zFormat, ...);..
5d60: 63 68 61 72 20 2a 73 71 6c 69 74 65 5f 76 6d 70  char *sqlite_vmp
5d70: 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
5d80: 20 2a 7a 46 6f 72 6d 61 74 2c 20 76 61 5f 6c 69   *zFormat, va_li
5d90: 73 74 29 3b 0a 0a 76 6f 69 64 20 73 71 6c 69 74  st);..void sqlit
5da0: 65 5f 66 72 65 65 6d 65 6d 28 63 68 61 72 2a 29  e_freemem(char*)
5db0: 3b 0a 0a 76 6f 69 64 20 73 71 6c 69 74 65 5f 70  ;..void sqlite_p
5dc0: 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
5dd0: 73 71 6c 69 74 65 2a 2c 20 69 6e 74 2c 20 69 6e  sqlite*, int, in
5de0: 74 20 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  t (*)(void*), vo
5df0: 69 64 2a 29 3b 0a 0a 3c 2f 70 72 65 3e 3c 2f 62  id*);..</pre></b
5e00: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 41  lockquote>..<p>A
5e10: 6c 6c 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20  ll of the above 
5e20: 64 65 66 69 6e 69 74 69 6f 6e 73 20 61 72 65 20  definitions are 
5e30: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
5e40: 22 73 71 6c 69 74 65 2e 68 22 0a 68 65 61 64 65  "sqlite.h".heade
5e50: 72 20 66 69 6c 65 20 74 68 61 74 20 63 6f 6d 65  r file that come
5e60: 73 20 69 6e 20 74 68 65 20 73 6f 75 72 63 65 20  s in the source 
5e70: 74 72 65 65 2e 3c 2f 70 3e 0a 0a 3c 68 34 3e 33  tree.</p>..<h4>3
5e80: 2e 31 20 54 68 65 20 52 4f 57 49 44 20 6f 66 20  .1 The ROWID of 
5e90: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
5ea0: 69 6e 73 65 72 74 3c 2f 68 34 3e 0a 0a 3c 70 3e  insert</h4>..<p>
5eb0: 45 76 65 72 79 20 72 6f 77 20 6f 66 20 61 6e 20  Every row of an 
5ec0: 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73  SQLite table has
5ed0: 20 61 20 75 6e 69 71 75 65 20 69 6e 74 65 67 65   a unique intege
5ee0: 72 20 6b 65 79 2e 20 20 49 66 20 74 68 65 0a 74  r key.  If the.t
5ef0: 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
5f00: 6e 20 6c 61 62 65 6c 65 64 20 49 4e 54 45 47 45  n labeled INTEGE
5f10: 52 20 50 52 49 4d 41 52 59 20 4b 45 59 2c 20 74  R PRIMARY KEY, t
5f20: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
5f30: 73 65 72 76 65 73 20 61 73 20 74 68 65 20 6b 65  serves as the ke
5f40: 79 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  y.  If there is 
5f50: 6e 6f 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41  no INTEGER PRIMA
5f60: 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 74 68  RY KEY column th
5f70: 65 6e 0a 74 68 65 20 6b 65 79 20 69 73 20 61 20  en.the key is a 
5f80: 75 6e 69 71 75 65 20 69 6e 74 65 67 65 72 2e 20  unique integer. 
5f90: 20 54 68 65 20 6b 65 79 20 66 6f 72 20 61 20 72   The key for a r
5fa0: 6f 77 20 63 61 6e 20 62 65 20 61 63 63 65 73 73  ow can be access
5fb0: 65 64 20 69 6e 0a 61 20 53 45 4c 45 43 54 20 73  ed in.a SELECT s
5fc0: 74 61 74 65 6d 65 6e 74 20 6f 72 20 75 73 65 64  tatement or used
5fd0: 20 69 6e 20 61 20 57 48 45 52 45 20 6f 72 20 4f   in a WHERE or O
5fe0: 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 75  RDER BY clause u
5ff0: 73 69 6e 67 20 61 6e 79 0a 6f 66 20 74 68 65 20  sing any.of the 
6000: 6e 61 6d 65 73 20 22 52 4f 57 49 44 22 2c 20 22  names "ROWID", "
6010: 4f 49 44 22 2c 20 6f 72 20 22 5f 52 4f 57 49 44  OID", or "_ROWID
6020: 5f 22 2e 3c 2f 70 3e 0a 0a 3c 70 3e 57 68 65 6e  _".</p>..<p>When
6030: 20 79 6f 75 20 64 6f 20 61 6e 20 69 6e 73 65 72   you do an inser
6040: 74 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  t into a table t
6050: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hat does not hav
6060: 65 20 61 6e 20 49 4e 54 45 47 45 52 20 50 52 49  e an INTEGER PRI
6070: 4d 41 52 59 0a 4b 45 59 20 63 6f 6c 75 6d 6e 2c  MARY.KEY column,
6080: 20 6f 72 20 69 66 20 74 68 65 20 74 61 62 6c 65   or if the table
6090: 20 64 6f 65 73 20 68 61 76 65 20 61 6e 20 49 4e   does have an IN
60a0: 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
60b0: 59 20 62 75 74 20 74 68 65 20 76 61 6c 75 65 0a  Y but the value.
60c0: 66 6f 72 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20  for that column 
60d0: 69 73 20 6e 6f 74 20 73 70 65 63 69 66 69 65 64  is not specified
60e0: 20 69 6e 20 74 68 65 20 56 41 4c 55 45 53 20 63   in the VALUES c
60f0: 6c 61 75 73 65 20 6f 66 20 74 68 65 20 69 6e 73  lause of the ins
6100: 65 72 74 2c 20 74 68 65 6e 0a 74 68 65 20 6b 65  ert, then.the ke
6110: 79 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  y is automatical
6120: 6c 79 20 67 65 6e 65 72 61 74 65 64 2e 20 20 59  ly generated.  Y
6130: 6f 75 20 63 61 6e 20 66 69 6e 64 20 74 68 65 20  ou can find the 
6140: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6b 65 79  value of the key
6150: 0a 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65  .for the most re
6160: 63 65 6e 74 20 49 4e 53 45 52 54 20 73 74 61 74  cent INSERT stat
6170: 65 6d 65 6e 74 20 75 73 69 6e 67 20 74 68 65 0a  ement using the.
6180: 3c 62 3e 73 71 6c 69 74 65 5f 6c 61 73 74 5f 69  <b>sqlite_last_i
6190: 6e 73 65 72 74 5f 72 6f 77 69 64 3c 2f 62 3e 20  nsert_rowid</b> 
61a0: 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 70  API function.</p
61b0: 3e 0a 0a 3c 68 34 3e 33 2e 32 20 54 68 65 20 6e  >..<h4>3.2 The n
61c0: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 74 68  umber of rows th
61d0: 61 74 20 63 68 61 6e 67 65 64 3c 2f 68 34 3e 0a  at changed</h4>.
61e0: 0a 3c 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69 74  .<p>The <b>sqlit
61f0: 65 5f 63 68 61 6e 67 65 73 3c 2f 62 3e 20 41 50  e_changes</b> AP
6200: 49 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  I function retur
6210: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
6220: 20 72 6f 77 73 0a 74 68 61 74 20 68 61 76 65 20   rows.that have 
6230: 62 65 65 6e 20 69 6e 73 65 72 74 65 64 2c 20 64  been inserted, d
6240: 65 6c 65 74 65 64 2c 20 6f 72 20 6d 6f 64 69 66  eleted, or modif
6250: 69 65 64 20 73 69 6e 63 65 20 74 68 65 20 64 61  ied since the da
6260: 74 61 62 61 73 65 20 77 61 73 0a 6c 61 73 74 20  tabase was.last 
6270: 71 75 69 65 73 63 65 6e 74 2e 20 20 41 20 22 71  quiescent.  A "q
6280: 75 69 65 73 63 65 6e 74 22 20 64 61 74 61 62 61  uiescent" databa
6290: 73 65 20 69 73 20 6f 6e 65 20 69 6e 20 77 68 69  se is one in whi
62a0: 63 68 20 74 68 65 72 65 20 61 72 65 0a 6e 6f 20  ch there are.no 
62b0: 6f 75 74 73 74 61 6e 64 69 6e 67 20 63 61 6c 6c  outstanding call
62c0: 73 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 65  s to <b>sqlite_e
62d0: 78 65 63 3c 2f 62 3e 20 61 6e 64 20 6e 6f 20 56  xec</b> and no V
62e0: 4d 73 20 63 72 65 61 74 65 64 20 62 79 0a 3c 62  Ms created by.<b
62f0: 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 3c  >sqlite_compile<
6300: 2f 62 3e 20 74 68 61 74 20 68 61 76 65 20 6e 6f  /b> that have no
6310: 74 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  t been finalized
6320: 20 62 79 20 3c 62 3e 73 71 6c 69 74 65 5f 66 69   by <b>sqlite_fi
6330: 6e 61 6c 69 7a 65 3c 2f 62 3e 2e 0a 49 6e 20 63  nalize</b>..In c
6340: 6f 6d 6d 6f 6e 20 75 73 61 67 65 2c 20 3c 62 3e  ommon usage, <b>
6350: 73 71 6c 69 74 65 5f 63 68 61 6e 67 65 73 3c 2f  sqlite_changes</
6360: 62 3e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  b> returns the n
6370: 75 6d 62 65 72 0a 6f 66 20 72 6f 77 73 20 69 6e  umber.of rows in
6380: 73 65 72 74 65 64 2c 20 64 65 6c 65 74 65 64 2c  serted, deleted,
6390: 20 6f 72 20 6d 6f 64 69 66 69 65 64 20 62 79 20   or modified by 
63a0: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
63b0: 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f  <b>sqlite_exec</
63c0: 62 3e 0a 63 61 6c 6c 20 6f 72 20 73 69 6e 63 65  b>.call or since
63d0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
63e0: 20 3c 62 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 69   <b>sqlite_compi
63f0: 6c 65 3c 2f 62 3e 2e 20 20 42 75 74 20 69 66 20  le</b>.  But if 
6400: 79 6f 75 20 68 61 76 65 0a 6e 65 73 74 65 64 20  you have.nested 
6410: 63 61 6c 6c 73 20 74 6f 20 3c 62 3e 73 71 6c 69  calls to <b>sqli
6420: 74 65 5f 65 78 65 63 3c 2f 62 3e 20 28 74 68 61  te_exec</b> (tha
6430: 74 20 69 73 2c 20 69 66 20 74 68 65 20 63 61 6c  t is, if the cal
6440: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 0a 6f 66  lback routine.of
6450: 20 6f 6e 65 20 3c 62 3e 73 71 6c 69 74 65 5f 65   one <b>sqlite_e
6460: 78 65 63 3c 2f 62 3e 20 69 6e 76 6f 6b 65 73 20  xec</b> invokes 
6470: 61 6e 6f 74 68 65 72 20 3c 62 3e 73 71 6c 69 74  another <b>sqlit
6480: 65 5f 65 78 65 63 3c 2f 62 3e 29 20 6f 72 20 69  e_exec</b>) or i
6490: 66 0a 79 6f 75 20 69 6e 76 6f 6b 65 20 3c 62 3e  f.you invoke <b>
64a0: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 3c 2f  sqlite_compile</
64b0: 62 3e 20 74 6f 20 63 72 65 61 74 65 20 61 20 6e  b> to create a n
64c0: 65 77 20 56 4d 20 77 68 69 6c 65 20 74 68 65 72  ew VM while ther
64d0: 65 20 69 73 0a 73 74 69 6c 6c 20 61 6e 6f 74 68  e is.still anoth
64e0: 65 72 20 56 4d 20 69 6e 20 65 78 69 73 74 61 6e  er VM in existan
64f0: 63 65 2c 20 74 68 65 6e 0a 74 68 65 20 6d 65 61  ce, then.the mea
6500: 6e 69 6e 67 20 6f 66 20 74 68 65 20 6e 75 6d 62  ning of the numb
6510: 65 72 20 72 65 74 75 72 6e 65 64 20 62 79 20 3c  er returned by <
6520: 62 3e 73 71 6c 69 74 65 5f 63 68 61 6e 67 65 73  b>sqlite_changes
6530: 3c 2f 62 3e 20 69 73 20 6d 6f 72 65 0a 63 6f 6d  </b> is more.com
6540: 70 6c 65 78 2e 0a 54 68 65 20 6e 75 6d 62 65 72  plex..The number
6550: 20 72 65 70 6f 72 74 65 64 20 69 6e 63 6c 75 64   reported includ
6560: 65 73 20 61 6e 79 20 63 68 61 6e 67 65 73 0a 74  es any changes.t
6570: 68 61 74 20 77 65 72 65 20 6c 61 74 65 72 20 75  hat were later u
6580: 6e 64 6f 6e 65 20 62 79 20 61 20 52 4f 4c 4c 42  ndone by a ROLLB
6590: 41 43 4b 20 6f 72 20 41 42 4f 52 54 2e 20 20 42  ACK or ABORT.  B
65a0: 75 74 20 72 6f 77 73 20 74 68 61 74 20 61 72 65  ut rows that are
65b0: 0a 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 65  .deleted because
65c0: 20 6f 66 20 61 20 44 52 4f 50 20 54 41 42 4c 45   of a DROP TABLE
65d0: 20 61 72 65 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d   are <em>not</em
65e0: 3e 20 63 6f 75 6e 74 65 64 2e 3c 2f 70 3e 0a 0a  > counted.</p>..
65f0: 3c 70 3e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  <p>SQLite implem
6600: 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64  ents the command
6610: 20 22 3c 62 3e 44 45 4c 45 54 45 20 46 52 4f 4d   "<b>DELETE FROM
6620: 20 74 61 62 6c 65 3c 2f 62 3e 22 20 28 77 69 74   table</b>" (wit
6630: 68 6f 75 74 0a 61 20 57 48 45 52 45 20 63 6c 61  hout.a WHERE cla
6640: 75 73 65 29 20 62 79 20 64 72 6f 70 70 69 6e 67  use) by dropping
6650: 20 74 68 65 20 74 61 62 6c 65 20 74 68 65 6e 20   the table then 
6660: 72 65 63 72 65 61 74 69 6e 67 20 69 74 2e 20 20  recreating it.  
6670: 0a 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61  .This is much fa
6680: 73 74 65 72 20 74 68 61 6e 20 64 65 6c 65 74 69  ster than deleti
6690: 6e 67 20 74 68 65 20 65 6c 65 6d 65 6e 74 73 20  ng the elements 
66a0: 6f 66 20 74 68 65 20 74 61 62 6c 65 20 69 6e 64  of the table ind
66b0: 69 76 69 64 75 61 6c 6c 79 2e 0a 42 75 74 20 69  ividually..But i
66c0: 74 20 61 6c 73 6f 20 6d 65 61 6e 73 20 74 68 61  t also means tha
66d0: 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  t the value retu
66e0: 72 6e 65 64 20 66 72 6f 6d 20 3c 62 3e 73 71 6c  rned from <b>sql
66f0: 69 74 65 5f 63 68 61 6e 67 65 73 3c 2f 62 3e 0a  ite_changes</b>.
6700: 77 69 6c 6c 20 62 65 20 7a 65 72 6f 20 72 65 67  will be zero reg
6710: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e  ardless of the n
6720: 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74  umber of element
6730: 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67  s that were orig
6740: 69 6e 61 6c 6c 79 0a 69 6e 20 74 68 65 20 74 61  inally.in the ta
6750: 62 6c 65 2e 20 20 49 66 20 61 6e 20 61 63 63 75  ble.  If an accu
6760: 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68  rate count of th
6770: 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d  e number of elem
6780: 65 6e 74 73 20 64 65 6c 65 74 65 64 0a 69 73 20  ents deleted.is 
6790: 6e 65 63 65 73 73 61 72 79 2c 20 75 73 65 20 22  necessary, use "
67a0: 3c 62 3e 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  <b>DELETE FROM t
67b0: 61 62 6c 65 20 57 48 45 52 45 20 31 3c 2f 62 3e  able WHERE 1</b>
67c0: 22 20 69 6e 73 74 65 61 64 2e 3c 2f 70 3e 0a 0a  " instead.</p>..
67d0: 3c 68 34 3e 33 2e 33 20 51 75 65 72 79 69 6e 67  <h4>3.3 Querying
67e0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
67f0: 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f  ained from mallo
6800: 63 28 29 3c 2f 68 34 3e 0a 0a 3c 70 3e 54 68 65  c()</h4>..<p>The
6810: 20 3c 62 3e 73 71 6c 69 74 65 5f 67 65 74 5f 74   <b>sqlite_get_t
6820: 61 62 6c 65 3c 2f 62 3e 20 66 75 6e 63 74 69 6f  able</b> functio
6830: 6e 20 69 73 20 61 20 77 72 61 70 70 65 72 20 61  n is a wrapper a
6840: 72 6f 75 6e 64 0a 3c 62 3e 73 71 6c 69 74 65 5f  round.<b>sqlite_
6850: 65 78 65 63 3c 2f 62 3e 20 74 68 61 74 20 63 6f  exec</b> that co
6860: 6c 6c 65 63 74 73 20 61 6c 6c 20 74 68 65 20 69  llects all the i
6870: 6e 66 6f 72 6d 61 74 69 6f 6e 20 66 72 6f 6d 20  nformation from 
6880: 73 75 63 63 65 73 73 69 76 65 0a 63 61 6c 6c 62  successive.callb
6890: 61 63 6b 73 20 61 6e 64 20 77 72 69 74 65 73 20  acks and writes 
68a0: 69 74 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  it into memory o
68b0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c  btained from mal
68c0: 6c 6f 63 28 29 2e 20 20 54 68 69 73 0a 69 73 20  loc().  This.is 
68d0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 66 75  a convenience fu
68e0: 6e 63 74 69 6f 6e 20 74 68 61 74 20 61 6c 6c 6f  nction that allo
68f0: 77 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ws the applicati
6900: 6f 6e 20 74 6f 20 67 65 74 20 74 68 65 0a 65 6e  on to get the.en
6910: 74 69 72 65 20 72 65 73 75 6c 74 20 6f 66 20 61  tire result of a
6920: 20 64 61 74 61 62 61 73 65 20 71 75 65 72 79 20   database query 
6930: 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 66 75  with a single fu
6940: 6e 63 74 69 6f 6e 20 63 61 6c 6c 2e 3c 2f 70 3e  nction call.</p>
6950: 0a 0a 3c 70 3e 54 68 65 20 6d 61 69 6e 20 72 65  ..<p>The main re
6960: 73 75 6c 74 20 66 72 6f 6d 20 3c 62 3e 73 71 6c  sult from <b>sql
6970: 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 3c 2f 62  ite_get_table</b
6980: 3e 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  > is an array of
6990: 20 70 6f 69 6e 74 65 72 73 0a 74 6f 20 73 74 72   pointers.to str
69a0: 69 6e 67 73 2e 20 20 54 68 65 72 65 20 69 73 20  ings.  There is 
69b0: 6f 6e 65 20 65 6c 65 6d 65 6e 74 20 69 6e 20 74  one element in t
69c0: 68 69 73 20 61 72 72 61 79 20 66 6f 72 20 65 61  his array for ea
69d0: 63 68 20 63 6f 6c 75 6d 6e 20 6f 66 0a 65 61 63  ch column of.eac
69e0: 68 20 72 6f 77 20 69 6e 20 74 68 65 20 72 65 73  h row in the res
69f0: 75 6c 74 2e 20 20 4e 55 4c 4c 20 72 65 73 75 6c  ult.  NULL resul
6a00: 74 73 20 61 72 65 20 72 65 70 72 65 73 65 6e 74  ts are represent
6a10: 65 64 20 62 79 20 61 20 4e 55 4c 4c 0a 70 6f 69  ed by a NULL.poi
6a20: 6e 74 65 72 2e 20 49 6e 20 61 64 64 69 74 69 6f  nter. In additio
6a30: 6e 20 74 6f 20 74 68 65 20 72 65 67 75 6c 61 72  n to the regular
6a40: 20 64 61 74 61 2c 20 74 68 65 72 65 20 69 73 20   data, there is 
6a50: 61 6e 20 61 64 64 65 64 20 72 6f 77 20 61 74 20  an added row at 
6a60: 74 68 65 20 0a 62 65 67 69 6e 6e 69 6e 67 20 6f  the .beginning o
6a70: 66 20 74 68 65 20 61 72 72 61 79 20 74 68 61 74  f the array that
6a80: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 6e 61   contains the na
6a90: 6d 65 20 6f 66 20 65 61 63 68 20 63 6f 6c 75 6d  me of each colum
6aa0: 6e 20 6f 66 20 74 68 65 0a 72 65 73 75 6c 74 2e  n of the.result.
6ab0: 3c 2f 70 3e 0a 0a 3c 70 3e 41 73 20 61 6e 20 65  </p>..<p>As an e
6ac0: 78 61 6d 70 6c 65 2c 20 63 6f 6e 73 69 64 65 72  xample, consider
6ad0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 71   the following q
6ae0: 75 65 72 79 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63  uery:</p>..<bloc
6af0: 6b 71 75 6f 74 65 3e 0a 53 45 4c 45 43 54 20 65  kquote>.SELECT e
6b00: 6d 70 6c 6f 79 65 65 5f 6e 61 6d 65 2c 20 6c 6f  mployee_name, lo
6b10: 67 69 6e 2c 20 68 6f 73 74 20 46 52 4f 4d 20 75  gin, host FROM u
6b20: 73 65 72 73 20 57 48 45 52 45 20 6c 6f 67 69 6e  sers WHERE login
6b30: 20 4c 49 4b 45 20 27 64 25 27 3b 0a 3c 2f 62 6c   LIKE 'd%';.</bl
6b40: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68  ockquote>..<p>Th
6b50: 69 73 20 71 75 65 72 79 20 77 69 6c 6c 20 72 65  is query will re
6b60: 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 2c 20 6c  turn the name, l
6b70: 6f 67 69 6e 20 61 6e 64 20 68 6f 73 74 20 63 6f  ogin and host co
6b80: 6d 70 75 74 65 72 20 6e 61 6d 65 0a 66 6f 72 20  mputer name.for 
6b90: 65 76 65 72 79 20 65 6d 70 6c 6f 79 65 65 20 77  every employee w
6ba0: 68 6f 73 65 20 6c 6f 67 69 6e 20 62 65 67 69 6e  hose login begin
6bb0: 73 20 77 69 74 68 20 74 68 65 20 6c 65 74 74 65  s with the lette
6bc0: 72 20 22 64 22 2e 20 20 49 66 20 74 68 69 73 0a  r "d".  If this.
6bd0: 71 75 65 72 79 20 69 73 20 73 75 62 6d 69 74 74  query is submitt
6be0: 65 64 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f  ed to <b>sqlite_
6bf0: 67 65 74 5f 74 61 62 6c 65 3c 2f 62 3e 20 74 68  get_table</b> th
6c00: 65 20 72 65 73 75 6c 74 20 6d 69 67 68 74 0a 6c  e result might.l
6c10: 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 3c 2f  ook like this:</
6c20: 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  p>..<blockquote>
6c30: 0a 6e 72 6f 77 20 3d 20 32 3c 62 72 3e 0a 6e 63  .nrow = 2<br>.nc
6c40: 6f 6c 75 6d 6e 20 3d 20 33 3c 62 72 3e 0a 72 65  olumn = 3<br>.re
6c50: 73 75 6c 74 5b 30 5d 20 3d 20 22 65 6d 70 6c 6f  sult[0] = "emplo
6c60: 79 65 65 5f 6e 61 6d 65 22 3c 62 72 3e 0a 72 65  yee_name"<br>.re
6c70: 73 75 6c 74 5b 31 5d 20 3d 20 22 6c 6f 67 69 6e  sult[1] = "login
6c80: 22 3c 62 72 3e 0a 72 65 73 75 6c 74 5b 32 5d 20  "<br>.result[2] 
6c90: 3d 20 22 68 6f 73 74 22 3c 62 72 3e 0a 72 65 73  = "host"<br>.res
6ca0: 75 6c 74 5b 33 5d 20 3d 20 22 64 75 6d 6d 79 22  ult[3] = "dummy"
6cb0: 3c 62 72 3e 0a 72 65 73 75 6c 74 5b 34 5d 20 3d  <br>.result[4] =
6cc0: 20 22 4e 6f 20 73 75 63 68 20 75 73 65 72 22 3c   "No such user"<
6cd0: 62 72 3e 0a 72 65 73 75 6c 74 5b 35 5d 20 3d 20  br>.result[5] = 
6ce0: 30 3c 62 72 3e 0a 72 65 73 75 6c 74 5b 36 5d 20  0<br>.result[6] 
6cf0: 3d 20 22 44 2e 20 52 69 63 68 61 72 64 20 48 69  = "D. Richard Hi
6d00: 70 70 22 3c 62 72 3e 0a 72 65 73 75 6c 74 5b 37  pp"<br>.result[7
6d10: 5d 20 3d 20 22 64 72 68 22 3c 62 72 3e 0a 72 65  ] = "drh"<br>.re
6d20: 73 75 6c 74 5b 38 5d 20 3d 20 22 7a 61 64 6f 6b  sult[8] = "zadok
6d30: 22 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ".</blockquote>.
6d40: 0a 3c 70 3e 4e 6f 74 69 63 65 20 74 68 61 74 20  .<p>Notice that 
6d50: 74 68 65 20 22 68 6f 73 74 22 20 76 61 6c 75 65  the "host" value
6d60: 20 66 6f 72 20 74 68 65 20 22 64 75 6d 6d 79 22   for the "dummy"
6d70: 20 72 65 63 6f 72 64 20 69 73 20 4e 55 4c 4c 20   record is NULL 
6d80: 73 6f 0a 74 68 65 20 72 65 73 75 6c 74 5b 5d 20  so.the result[] 
6d90: 61 72 72 61 79 20 63 6f 6e 74 61 69 6e 73 20 61  array contains a
6da0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 74   NULL pointer at
6db0: 20 74 68 61 74 20 73 6c 6f 74 2e 3c 2f 70 3e 0a   that slot.</p>.
6dc0: 0a 3c 70 3e 49 66 20 74 68 65 20 72 65 73 75 6c  .<p>If the resul
6dd0: 74 20 73 65 74 20 6f 66 20 61 20 71 75 65 72 79  t set of a query
6de0: 20 69 73 20 65 6d 70 74 79 2c 20 74 68 65 6e 20   is empty, then 
6df0: 62 79 20 64 65 66 61 75 6c 74 0a 3c 62 3e 73 71  by default.<b>sq
6e00: 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 3c 2f  lite_get_table</
6e10: 62 3e 20 77 69 6c 6c 20 73 65 74 20 6e 72 6f 77  b> will set nrow
6e20: 20 74 6f 20 30 20 61 6e 64 20 6c 65 61 76 65 20   to 0 and leave 
6e30: 69 74 73 0a 72 65 73 75 6c 74 20 70 61 72 61 6d  its.result param
6e40: 65 74 65 72 20 69 73 20 73 65 74 20 74 6f 20 4e  eter is set to N
6e50: 55 4c 4c 2e 20 20 42 75 74 20 69 66 20 74 68 65  ULL.  But if the
6e60: 20 45 4d 50 54 59 5f 52 45 53 55 4c 54 5f 43 41   EMPTY_RESULT_CA
6e70: 4c 4c 42 41 43 4b 53 0a 70 72 61 67 6d 61 20 69  LLBACKS.pragma i
6e80: 73 20 4f 4e 20 74 68 65 6e 20 74 68 65 20 72 65  s ON then the re
6e90: 73 75 6c 74 20 70 61 72 61 6d 65 74 65 72 20 69  sult parameter i
6ea0: 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 74 6f  s initialized to
6eb0: 20 74 68 65 20 6e 61 6d 65 73 0a 6f 66 20 74 68   the names.of th
6ec0: 65 20 63 6f 6c 75 6d 6e 73 20 6f 6e 6c 79 2e 20  e columns only. 
6ed0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 63 6f   For example, co
6ee0: 6e 73 69 64 65 72 20 74 68 69 73 20 71 75 65 72  nsider this quer
6ef0: 79 20 77 68 69 63 68 20 68 61 73 0a 61 6e 20 65  y which has.an e
6f00: 6d 70 74 79 20 72 65 73 75 6c 74 20 73 65 74 3a  mpty result set:
6f10: 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  </p>..<blockquot
6f20: 65 3e 0a 53 45 4c 45 43 54 20 65 6d 70 6c 6f 79  e>.SELECT employ
6f30: 65 65 5f 6e 61 6d 65 2c 20 6c 6f 67 69 6e 2c 20  ee_name, login, 
6f40: 68 6f 73 74 20 46 52 4f 4d 20 75 73 65 72 73 20  host FROM users 
6f50: 57 48 45 52 45 20 65 6d 70 6c 6f 79 65 65 5f 6e  WHERE employee_n
6f60: 61 6d 65 20 49 53 20 4e 55 4c 4c 3b 0a 3c 2f 62  ame IS NULL;.</b
6f70: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a  lockquote>..<p>.
6f80: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
6f90: 76 69 6f 72 20 67 69 76 65 73 20 74 68 69 73 20  vior gives this 
6fa0: 72 65 73 75 6c 74 73 3a 0a 3c 2f 70 3e 0a 0a 3c  results:.</p>..<
6fb0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 6e 72 6f 77  blockquote>.nrow
6fc0: 20 3d 20 30 3c 62 72 3e 0a 6e 63 6f 6c 75 6d 6e   = 0<br>.ncolumn
6fd0: 20 3d 20 30 3c 62 72 3e 0a 72 65 73 75 6c 74 20   = 0<br>.result 
6fe0: 3d 20 30 3c 62 72 3e 0a 3c 2f 62 6c 6f 63 6b 71  = 0<br>.</blockq
6ff0: 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 42 75 74 20 69  uote>..<p>.But i
7000: 66 20 74 68 65 20 45 4d 50 54 59 5f 52 45 53 55  f the EMPTY_RESU
7010: 4c 54 5f 43 41 4c 4c 42 41 43 4b 53 20 70 72 61  LT_CALLBACKS pra
7020: 67 6d 61 20 69 73 20 4f 4e 2c 20 74 68 65 6e 20  gma is ON, then 
7030: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 69 73  the following.is
7040: 20 72 65 74 75 72 6e 65 64 3a 0a 3c 2f 70 3e 0a   returned:.</p>.
7050: 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 6e 72  .<blockquote>.nr
7060: 6f 77 20 3d 20 30 3c 62 72 3e 0a 6e 63 6f 6c 75  ow = 0<br>.ncolu
7070: 6d 6e 20 3d 20 33 3c 62 72 3e 0a 72 65 73 75 6c  mn = 3<br>.resul
7080: 74 5b 30 5d 20 3d 20 22 65 6d 70 6c 6f 79 65 65  t[0] = "employee
7090: 5f 6e 61 6d 65 22 3c 62 72 3e 0a 72 65 73 75 6c  _name"<br>.resul
70a0: 74 5b 31 5d 20 3d 20 22 6c 6f 67 69 6e 22 3c 62  t[1] = "login"<b
70b0: 72 3e 0a 72 65 73 75 6c 74 5b 32 5d 20 3d 20 22  r>.result[2] = "
70c0: 68 6f 73 74 22 3c 62 72 3e 0a 3c 2f 62 6c 6f 63  host"<br>.</bloc
70d0: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 4d 65 6d 6f  kquote>..<p>Memo
70e0: 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 69  ry to hold the i
70f0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 72 65 74 75 72  nformation retur
7100: 6e 65 64 20 62 79 20 3c 62 3e 73 71 6c 69 74 65  ned by <b>sqlite
7110: 5f 67 65 74 5f 74 61 62 6c 65 3c 2f 62 3e 0a 69  _get_table</b>.i
7120: 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
7130: 6d 61 6c 6c 6f 63 28 29 2e 20 20 42 75 74 20 74  malloc().  But t
7140: 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
7150: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ion should not t
7160: 72 79 0a 74 6f 20 66 72 65 65 20 74 68 69 73 20  ry.to free this 
7170: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 64 69 72 65  information dire
7180: 63 74 6c 79 2e 20 20 49 6e 73 74 65 61 64 2c 20  ctly.  Instead, 
7190: 70 61 73 73 20 74 68 65 20 63 6f 6d 70 6c 65 74  pass the complet
71a0: 65 20 74 61 62 6c 65 0a 74 6f 20 3c 62 3e 73 71  e table.to <b>sq
71b0: 6c 69 74 65 5f 66 72 65 65 5f 74 61 62 6c 65 3c  lite_free_table<
71c0: 2f 62 3e 20 77 68 65 6e 20 74 68 65 20 74 61 62  /b> when the tab
71d0: 6c 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  le is no longer 
71e0: 6e 65 65 64 65 64 2e 0a 49 74 20 69 73 20 73 61  needed..It is sa
71f0: 66 65 20 74 6f 20 63 61 6c 6c 20 3c 62 3e 73 71  fe to call <b>sq
7200: 6c 69 74 65 5f 66 72 65 65 5f 74 61 62 6c 65 3c  lite_free_table<
7210: 2f 62 3e 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  /b> with a NULL 
7220: 70 6f 69 6e 74 65 72 20 73 75 63 68 0a 61 73 20  pointer such.as 
7230: 77 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  would be returne
7240: 64 20 69 66 20 74 68 65 20 72 65 73 75 6c 74 20  d if the result 
7250: 73 65 74 20 69 73 20 65 6d 70 74 79 2e 3c 2f 70  set is empty.</p
7260: 3e 0a 0a 3c 70 3e 54 68 65 20 3c 62 3e 73 71 6c  >..<p>The <b>sql
7270: 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 3c 2f 62  ite_get_table</b
7280: 3e 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  > routine return
7290: 73 20 74 68 65 20 73 61 6d 65 20 69 6e 74 65 67  s the same integ
72a0: 65 72 0a 72 65 73 75 6c 74 20 63 6f 64 65 20 61  er.result code a
72b0: 73 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63  s <b>sqlite_exec
72c0: 3c 2f 62 3e 2e 3c 2f 70 3e 0a 0a 3c 68 34 3e 33  </b>.</p>..<h4>3
72d0: 2e 34 20 49 6e 74 65 72 72 75 70 74 69 6e 67 20  .4 Interrupting 
72e0: 61 6e 20 53 51 4c 69 74 65 20 6f 70 65 72 61 74  an SQLite operat
72f0: 69 6f 6e 3c 2f 68 34 3e 0a 0a 3c 70 3e 54 68 65  ion</h4>..<p>The
7300: 20 3c 62 3e 73 71 6c 69 74 65 5f 69 6e 74 65 72   <b>sqlite_inter
7310: 72 75 70 74 3c 2f 62 3e 20 66 75 6e 63 74 69 6f  rupt</b> functio
7320: 6e 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  n can be called 
7330: 66 72 6f 6d 20 61 0a 64 69 66 66 65 72 65 6e 74  from a.different
7340: 20 74 68 72 65 61 64 20 6f 72 20 66 72 6f 6d 20   thread or from 
7350: 61 20 73 69 67 6e 61 6c 20 68 61 6e 64 6c 65 72  a signal handler
7360: 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 63 75   to cause the cu
7370: 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 0a 6f  rrent database.o
7380: 70 65 72 61 74 69 6f 6e 20 74 6f 20 65 78 69 74  peration to exit
7390: 20 61 74 20 69 74 73 20 66 69 72 73 74 20 6f 70   at its first op
73a0: 70 6f 72 74 75 6e 69 74 79 2e 20 20 57 68 65 6e  portunity.  When
73b0: 20 74 68 69 73 20 68 61 70 70 65 6e 73 2c 0a 74   this happens,.t
73c0: 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65  he <b>sqlite_exe
73d0: 63 3c 2f 62 3e 20 72 6f 75 74 69 6e 65 20 28 6f  c</b> routine (o
73e0: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
73f0: 29 20 74 68 61 74 20 73 74 61 72 74 65 64 0a 74  ) that started.t
7400: 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
7410: 61 74 69 6f 6e 20 77 69 6c 6c 20 72 65 74 75 72  ation will retur
7420: 6e 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55  n SQLITE_INTERRU
7430: 50 54 2e 3c 2f 70 3e 0a 0a 3c 68 34 3e 33 2e 35  PT.</p>..<h4>3.5
7440: 20 54 65 73 74 69 6e 67 20 66 6f 72 20 61 20 63   Testing for a c
7450: 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
7460: 65 6d 65 6e 74 3c 2f 68 34 3e 0a 0a 3c 70 3e 54  ement</h4>..<p>T
7470: 68 65 20 6e 65 78 74 20 69 6e 74 65 72 66 61 63  he next interfac
7480: 65 20 72 6f 75 74 69 6e 65 20 74 6f 20 53 51 4c  e routine to SQL
7490: 69 74 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69  ite is a conveni
74a0: 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 75 73  ence function us
74b0: 65 64 0a 74 6f 20 74 65 73 74 20 77 68 65 74 68  ed.to test wheth
74c0: 65 72 20 6f 72 20 6e 6f 74 20 61 20 73 74 72 69  er or not a stri
74d0: 6e 67 20 66 6f 72 6d 73 20 61 20 63 6f 6d 70 6c  ng forms a compl
74e0: 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
74f0: 74 2e 0a 49 66 20 74 68 65 20 3c 62 3e 73 71 6c  t..If the <b>sql
7500: 69 74 65 5f 63 6f 6d 70 6c 65 74 65 3c 2f 62 3e  ite_complete</b>
7510: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
7520: 73 20 74 72 75 65 20 77 68 65 6e 20 69 74 73 20  s true when its 
7530: 69 6e 70 75 74 0a 69 73 20 61 20 73 74 72 69 6e  input.is a strin
7540: 67 2c 20 74 68 65 6e 20 74 68 65 20 61 72 67 75  g, then the argu
7550: 6d 65 6e 74 20 66 6f 72 6d 73 20 61 20 63 6f 6d  ment forms a com
7560: 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
7570: 65 6e 74 2e 0a 54 68 65 72 65 20 61 72 65 20 6e  ent..There are n
7580: 6f 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  o guarantees tha
7590: 74 20 74 68 65 20 73 79 6e 74 61 78 20 6f 66 20  t the syntax of 
75a0: 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 69  that statement i
75b0: 73 20 63 6f 72 72 65 63 74 2c 0a 62 75 74 20 77  s correct,.but w
75c0: 65 20 61 74 20 6c 65 61 73 74 20 6b 6e 6f 77 20  e at least know 
75d0: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
75e0: 20 63 6f 6d 70 6c 65 74 65 2e 20 20 49 66 20 3c   complete.  If <
75f0: 62 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 74  b>sqlite_complet
7600: 65 3c 2f 62 3e 0a 72 65 74 75 72 6e 73 20 66 61  e</b>.returns fa
7610: 6c 73 65 2c 20 74 68 65 6e 20 6d 6f 72 65 20 74  lse, then more t
7620: 65 78 74 20 69 73 20 72 65 71 75 69 72 65 64 20  ext is required 
7630: 74 6f 20 63 6f 6d 70 6c 65 74 65 20 74 68 65 20  to complete the 
7640: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  SQL statement.</
7650: 70 3e 0a 0a 3c 70 3e 46 6f 72 20 74 68 65 20 70  p>..<p>For the p
7660: 75 72 70 6f 73 65 20 6f 66 20 74 68 65 20 3c 62  urpose of the <b
7670: 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 65  >sqlite_complete
7680: 3c 2f 62 3e 20 66 75 6e 63 74 69 6f 6e 2c 20 61  </b> function, a
7690: 6e 20 53 51 4c 0a 73 74 61 74 65 6d 65 6e 74 20  n SQL.statement 
76a0: 69 73 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  is complete if i
76b0: 74 20 65 6e 64 73 20 69 6e 20 61 20 73 65 6d 69  t ends in a semi
76c0: 63 6f 6c 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54  colon.</p>..<p>T
76d0: 68 65 20 3c 62 3e 73 71 6c 69 74 65 3c 2f 62 3e  he <b>sqlite</b>
76e0: 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 75 74   command-line ut
76f0: 69 6c 69 74 79 20 75 73 65 73 20 74 68 65 20 3c  ility uses the <
7700: 62 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 74  b>sqlite_complet
7710: 65 3c 2f 62 3e 0a 66 75 6e 63 74 69 6f 6e 20 74  e</b>.function t
7720: 6f 20 6b 6e 6f 77 20 77 68 65 6e 20 69 74 20 6e  o know when it n
7730: 65 65 64 73 20 74 6f 20 63 61 6c 6c 20 3c 62 3e  eeds to call <b>
7740: 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e 2e  sqlite_exec</b>.
7750: 20 20 41 66 74 65 72 20 65 61 63 68 0a 6c 69 6e    After each.lin
7760: 65 20 6f 66 20 69 6e 70 75 74 20 69 73 20 72 65  e of input is re
7770: 63 65 69 76 65 64 2c 20 3c 62 3e 73 71 6c 69 74  ceived, <b>sqlit
7780: 65 3c 2f 62 3e 20 63 61 6c 6c 73 20 3c 62 3e 73  e</b> calls <b>s
7790: 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 65 3c 2f  qlite_complete</
77a0: 62 3e 0a 6f 6e 20 61 6c 6c 20 69 6e 70 75 74 20  b>.on all input 
77b0: 69 6e 20 69 74 73 20 62 75 66 66 65 72 2e 20 20  in its buffer.  
77c0: 49 66 20 3c 62 3e 73 71 6c 69 74 65 5f 63 6f 6d  If <b>sqlite_com
77d0: 70 6c 65 74 65 3c 2f 62 3e 20 72 65 74 75 72 6e  plete</b> return
77e0: 73 20 74 72 75 65 2c 20 0a 74 68 65 6e 20 3c 62  s true, .then <b
77f0: 3e 73 71 6c 69 74 65 5f 65 78 65 63 3c 2f 62 3e  >sqlite_exec</b>
7800: 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 20 74   is called and t
7810: 68 65 20 69 6e 70 75 74 20 62 75 66 66 65 72 20  he input buffer 
7820: 69 73 20 72 65 73 65 74 2e 20 20 49 66 0a 3c 62  is reset.  If.<b
7830: 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 65  >sqlite_complete
7840: 3c 2f 62 3e 20 72 65 74 75 72 6e 73 20 66 61 6c  </b> returns fal
7850: 73 65 2c 20 74 68 65 6e 20 74 68 65 20 70 72 6f  se, then the pro
7860: 6d 70 74 20 69 73 20 63 68 61 6e 67 65 64 20 74  mpt is changed t
7870: 6f 0a 74 68 65 20 63 6f 6e 74 69 6e 75 61 74 69  o.the continuati
7880: 6f 6e 20 70 72 6f 6d 70 74 20 61 6e 64 20 61 6e  on prompt and an
7890: 6f 74 68 65 72 20 6c 69 6e 65 20 6f 66 20 74 65  other line of te
78a0: 78 74 20 69 73 20 72 65 61 64 20 61 6e 64 20 61  xt is read and a
78b0: 64 64 65 64 20 74 6f 0a 74 68 65 20 69 6e 70 75  dded to.the inpu
78c0: 74 20 62 75 66 66 65 72 2e 3c 2f 70 3e 0a 0a 3c  t buffer.</p>..<
78d0: 68 34 3e 33 2e 36 20 4c 69 62 72 61 72 79 20 76  h4>3.6 Library v
78e0: 65 72 73 69 6f 6e 20 73 74 72 69 6e 67 3c 2f 68  ersion string</h
78f0: 34 3e 0a 0a 3c 70 3e 54 68 65 20 53 51 4c 69 74  4>..<p>The SQLit
7900: 65 20 6c 69 62 72 61 72 79 20 65 78 70 6f 72 74  e library export
7910: 73 20 74 68 65 20 73 74 72 69 6e 67 20 63 6f 6e  s the string con
7920: 73 74 61 6e 74 20 6e 61 6d 65 64 0a 3c 62 3e 73  stant named.<b>s
7930: 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 3c 2f 62  qlite_version</b
7940: 3e 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  > which contains
7950: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
7960: 62 65 72 20 6f 66 20 74 68 65 0a 6c 69 62 72 61  ber of the.libra
7970: 72 79 2e 20 20 54 68 65 20 68 65 61 64 65 72 20  ry.  The header 
7980: 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  file contains a 
7990: 6d 61 63 72 6f 20 53 51 4c 49 54 45 5f 56 45 52  macro SQLITE_VER
79a0: 53 49 4f 4e 0a 77 69 74 68 20 74 68 65 20 73 61  SION.with the sa
79b0: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20  me information. 
79c0: 20 49 66 20 64 65 73 69 72 65 64 2c 20 61 20 70   If desired, a p
79d0: 72 6f 67 72 61 6d 20 63 61 6e 20 63 6f 6d 70 61  rogram can compa
79e0: 72 65 0a 74 68 65 20 53 51 4c 49 54 45 5f 56 45  re.the SQLITE_VE
79f0: 52 53 49 4f 4e 20 6d 61 63 72 6f 20 61 67 61 69  RSION macro agai
7a00: 6e 73 74 20 74 68 65 20 3c 62 3e 73 71 6c 69 74  nst the <b>sqlit
7a10: 65 5f 76 65 72 73 69 6f 6e 3c 2f 62 3e 0a 73 74  e_version</b>.st
7a20: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 74 6f  ring constant to
7a30: 20 76 65 72 69 66 79 20 74 68 61 74 20 74 68 65   verify that the
7a40: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
7a50: 6f 66 20 74 68 65 0a 68 65 61 64 65 72 20 66 69  of the.header fi
7a60: 6c 65 20 61 6e 64 20 74 68 65 20 6c 69 62 72 61  le and the libra
7a70: 72 79 20 6d 61 74 63 68 2e 3c 2f 70 3e 20 0a 0a  ry match.</p> ..
7a80: 3c 68 34 3e 33 2e 37 20 4c 69 62 72 61 72 79 20  <h4>3.7 Library 
7a90: 63 68 61 72 61 63 74 65 72 20 65 6e 63 6f 64 69  character encodi
7aa0: 6e 67 3c 2f 68 34 3e 0a 0a 3c 70 3e 42 79 20 64  ng</h4>..<p>By d
7ab0: 65 66 61 75 6c 74 2c 20 53 51 4c 69 74 65 20 61  efault, SQLite a
7ac0: 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c 6c 20  ssumes that all 
7ad0: 64 61 74 61 20 75 73 65 73 20 61 20 66 69 78 65  data uses a fixe
7ae0: 64 2d 73 69 7a 65 0a 38 2d 62 69 74 20 63 68 61  d-size.8-bit cha
7af0: 72 61 63 74 65 72 20 28 69 73 6f 38 38 35 39 29  racter (iso8859)
7b00: 2e 20 20 42 75 74 20 69 66 20 79 6f 75 20 67 69  .  But if you gi
7b10: 76 65 20 74 68 65 20 2d 2d 65 6e 61 62 6c 65 2d  ve the --enable-
7b20: 75 74 66 38 20 6f 70 74 69 6f 6e 0a 74 6f 20 74  utf8 option.to t
7b30: 68 65 20 63 6f 6e 66 69 67 75 72 65 20 73 63 72  he configure scr
7b40: 69 70 74 2c 20 74 68 65 6e 20 74 68 65 20 6c 69  ipt, then the li
7b50: 62 72 61 72 79 20 61 73 73 75 6d 65 73 20 55 54  brary assumes UT
7b60: 46 2d 38 20 76 61 72 69 61 62 6c 65 0a 73 69 7a  F-8 variable.siz
7b70: 65 64 20 63 68 61 72 61 63 74 65 72 73 2e 20 20  ed characters.  
7b80: 54 68 69 73 20 6d 61 6b 65 73 20 61 20 64 69 66  This makes a dif
7b90: 66 65 72 65 6e 63 65 20 66 6f 72 20 74 68 65 20  ference for the 
7ba0: 4c 49 4b 45 20 61 6e 64 20 47 4c 4f 42 0a 6f 70  LIKE and GLOB.op
7bb0: 65 72 61 74 6f 72 73 20 61 6e 64 20 74 68 65 20  erators and the 
7bc0: 4c 45 4e 47 54 48 28 29 20 61 6e 64 20 53 55 42  LENGTH() and SUB
7bd0: 53 54 52 28 29 20 66 75 6e 63 74 69 6f 6e 73 2e  STR() functions.
7be0: 20 20 54 68 65 20 73 74 61 74 69 63 0a 73 74 72    The static.str
7bf0: 69 6e 67 20 3c 62 3e 73 71 6c 69 74 65 5f 65 6e  ing <b>sqlite_en
7c00: 63 6f 64 69 6e 67 3c 2f 62 3e 20 77 69 6c 6c 20  coding</b> will 
7c10: 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
7c20: 20 22 55 54 46 2d 38 22 20 6f 72 0a 22 69 73 6f   "UTF-8" or."iso
7c30: 38 38 35 39 22 20 74 6f 20 69 6e 64 69 63 61 74  8859" to indicat
7c40: 65 20 68 6f 77 20 74 68 65 20 6c 69 62 72 61 72  e how the librar
7c50: 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 2e 20  y was compiled. 
7c60: 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 0a 74 68   In addition,.th
7c70: 65 20 3c 62 3e 73 71 6c 69 74 65 2e 68 3c 2f 62  e <b>sqlite.h</b
7c80: 3e 20 68 65 61 64 65 72 20 66 69 6c 65 20 77 69  > header file wi
7c90: 6c 6c 20 64 65 66 69 6e 65 20 6f 6e 65 20 6f 66  ll define one of
7ca0: 20 74 68 65 0a 6d 61 63 72 6f 73 20 3c 62 3e 53   the.macros <b>S
7cb0: 51 4c 49 54 45 5f 55 54 46 38 3c 2f 62 3e 20 6f  QLITE_UTF8</b> o
7cc0: 72 20 3c 62 3e 53 51 4c 49 54 45 5f 49 53 4f 38  r <b>SQLITE_ISO8
7cd0: 38 35 39 3c 2f 62 3e 2c 20 61 73 20 61 70 70 72  859</b>, as appr
7ce0: 6f 70 72 69 61 74 65 2e 3c 2f 70 3e 0a 0a 3c 70  opriate.</p>..<p
7cf0: 3e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 63  >Note that the c
7d00: 68 61 72 61 63 74 65 72 20 65 6e 63 6f 64 69 6e  haracter encodin
7d10: 67 20 6d 65 63 68 61 6e 69 73 6d 20 75 73 65 64  g mechanism used
7d20: 20 62 79 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f   by SQLite canno
7d30: 74 0a 62 65 20 63 68 61 6e 67 65 64 20 61 74 20  t.be changed at 
7d40: 72 75 6e 2d 74 69 6d 65 2e 20 20 54 68 69 73 20  run-time.  This 
7d50: 69 73 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  is a compile-tim
7d60: 65 20 6f 70 74 69 6f 6e 20 6f 6e 6c 79 2e 20 20  e option only.  
7d70: 54 68 65 0a 3c 62 3e 73 71 6c 69 74 65 5f 65 6e  The.<b>sqlite_en
7d80: 63 6f 64 69 6e 67 3c 2f 62 3e 20 63 68 61 72 61  coding</b> chara
7d90: 63 74 65 72 20 73 74 72 69 6e 67 20 6a 75 73 74  cter string just
7da0: 20 74 65 6c 6c 73 20 79 6f 75 20 68 6f 77 20 74   tells you how t
7db0: 68 65 20 6c 69 62 72 61 72 79 0a 77 61 73 20 63  he library.was c
7dc0: 6f 6d 70 69 6c 65 64 2e 3c 2f 70 3e 0a 0a 3c 68  ompiled.</p>..<h
7dd0: 34 3e 33 2e 38 20 43 68 61 6e 67 69 6e 67 20 74  4>3.8 Changing t
7de0: 68 65 20 6c 69 62 72 61 72 79 27 73 20 72 65 73  he library's res
7df0: 70 6f 6e 73 65 20 74 6f 20 6c 6f 63 6b 65 64 20  ponse to locked 
7e00: 66 69 6c 65 73 3c 2f 68 34 3e 0a 0a 3c 70 3e 54  files</h4>..<p>T
7e10: 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 62 75 73  he <b>sqlite_bus
7e20: 79 5f 68 61 6e 64 6c 65 72 3c 2f 62 3e 20 70 72  y_handler</b> pr
7e30: 6f 63 65 64 75 72 65 20 63 61 6e 20 62 65 20 75  ocedure can be u
7e40: 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 0a  sed to register.
7e50: 61 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  a busy callback 
7e60: 77 69 74 68 20 61 6e 20 6f 70 65 6e 20 53 51 4c  with an open SQL
7e70: 69 74 65 20 64 61 74 61 62 61 73 65 2e 20 20 54  ite database.  T
7e80: 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
7e90: 20 77 69 6c 6c 0a 62 65 20 69 6e 76 6f 6b 65 64   will.be invoked
7ea0: 20 77 68 65 6e 65 76 65 72 20 53 51 4c 69 74 65   whenever SQLite
7eb0: 20 74 72 69 65 73 20 74 6f 20 61 63 63 65 73 73   tries to access
7ec0: 20 61 20 64 61 74 61 62 61 73 65 20 74 68 61 74   a database that
7ed0: 20 69 73 20 6c 6f 63 6b 65 64 2e 0a 54 68 65 20   is locked..The 
7ee0: 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 74 79  callback will ty
7ef0: 70 69 63 61 6c 6c 79 20 64 6f 20 73 6f 6d 65 20  pically do some 
7f00: 6f 74 68 65 72 20 75 73 65 66 75 6c 20 77 6f 72  other useful wor
7f10: 6b 2c 20 6f 72 20 70 65 72 68 61 70 73 20 73 6c  k, or perhaps sl
7f20: 65 65 70 2c 0a 69 6e 20 6f 72 64 65 72 20 74 6f  eep,.in order to
7f30: 20 67 69 76 65 20 74 68 65 20 6c 6f 63 6b 20 61   give the lock a
7f40: 20 63 68 61 6e 63 65 20 74 6f 20 63 6c 65 61 72   chance to clear
7f50: 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  .  If the callba
7f60: 63 6b 20 72 65 74 75 72 6e 73 0a 6e 6f 6e 2d 7a  ck returns.non-z
7f70: 65 72 6f 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ero, then SQLite
7f80: 20 74 72 69 65 73 20 61 67 61 69 6e 20 74 6f 20   tries again to 
7f90: 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
7fa0: 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ase and the cycl
7fb0: 65 0a 72 65 70 65 61 74 73 2e 20 20 49 66 20 74  e.repeats.  If t
7fc0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
7fd0: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 53  rns zero, then S
7fe0: 51 4c 69 74 65 20 61 62 6f 72 74 73 20 74 68 65  QLite aborts the
7ff0: 20 63 75 72 72 65 6e 74 0a 6f 70 65 72 61 74 69   current.operati
8000: 6f 6e 20 61 6e 64 20 72 65 74 75 72 6e 73 20 53  on and returns S
8010: 51 4c 49 54 45 5f 42 55 53 59 2e 3c 2f 70 3e 0a  QLITE_BUSY.</p>.
8020: 0a 3c 70 3e 54 68 65 20 61 72 67 75 6d 65 6e 74  .<p>The argument
8030: 73 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 62  s to <b>sqlite_b
8040: 75 73 79 5f 68 61 6e 64 6c 65 72 3c 2f 62 3e 20  usy_handler</b> 
8050: 61 72 65 20 74 68 65 20 6f 70 61 71 75 65 0a 73  are the opaque.s
8060: 74 72 75 63 74 75 72 65 20 72 65 74 75 72 6e 65  tructure returne
8070: 64 20 66 72 6f 6d 20 3c 62 3e 73 71 6c 69 74 65  d from <b>sqlite
8080: 5f 6f 70 65 6e 3c 2f 62 3e 2c 20 61 20 70 6f 69  _open</b>, a poi
8090: 6e 74 65 72 20 74 6f 20 74 68 65 20 62 75 73 79  nter to the busy
80a0: 0a 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69  .callback functi
80b0: 6f 6e 2c 20 61 6e 64 20 61 20 67 65 6e 65 72 69  on, and a generi
80c0: 63 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  c pointer that w
80d0: 69 6c 6c 20 62 65 20 70 61 73 73 65 64 20 61 73  ill be passed as
80e0: 0a 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  .the first argum
80f0: 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
8100: 63 61 6c 6c 62 61 63 6b 2e 20 20 57 68 65 6e 20  callback.  When 
8110: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
8120: 68 65 0a 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he.busy callback
8130: 2c 20 69 74 20 73 65 6e 64 73 20 69 74 20 74 68  , it sends it th
8140: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20  ree arguments:  
8150: 74 68 65 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  the generic poin
8160: 74 65 72 0a 74 68 61 74 20 77 61 73 20 70 61 73  ter.that was pas
8170: 73 65 64 20 69 6e 20 61 73 20 74 68 65 20 74 68  sed in as the th
8180: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
8190: 3c 62 3e 73 71 6c 69 74 65 5f 62 75 73 79 5f 68  <b>sqlite_busy_h
81a0: 61 6e 64 6c 65 72 3c 2f 62 3e 2c 0a 74 68 65 20  andler</b>,.the 
81b0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
81c0: 62 61 73 65 20 74 61 62 6c 65 20 6f 72 20 69 6e  base table or in
81d0: 64 65 78 20 74 68 61 74 20 74 68 65 20 6c 69 62  dex that the lib
81e0: 72 61 72 79 20 69 73 20 74 72 79 69 6e 67 0a 74  rary is trying.t
81f0: 6f 20 61 63 63 65 73 73 2c 20 61 6e 64 20 74 68  o access, and th
8200: 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
8210: 73 20 74 68 61 74 20 74 68 65 20 6c 69 62 72 61  s that the libra
8220: 72 79 20 68 61 73 20 61 74 74 65 6d 70 74 65 64  ry has attempted
8230: 20 74 6f 0a 61 63 63 65 73 73 20 74 68 65 20 64   to.access the d
8240: 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 6f 72  atabase table or
8250: 20 69 6e 64 65 78 2e 3c 2f 70 3e 0a 0a 3c 70 3e   index.</p>..<p>
8260: 46 6f 72 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 63  For the common c
8270: 61 73 65 20 77 68 65 72 65 20 77 65 20 77 61 6e  ase where we wan
8280: 74 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  t the busy callb
8290: 61 63 6b 20 74 6f 20 73 6c 65 65 70 2c 0a 74 68  ack to sleep,.th
82a0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
82b0: 20 70 72 6f 76 69 64 65 73 20 61 20 63 6f 6e 76   provides a conv
82c0: 65 6e 69 65 6e 63 65 20 72 6f 75 74 69 6e 65 20  enience routine 
82d0: 3c 62 3e 73 71 6c 69 74 65 5f 62 75 73 79 5f 74  <b>sqlite_busy_t
82e0: 69 6d 65 6f 75 74 3c 2f 62 3e 2e 0a 54 68 65 20  imeout</b>..The 
82f0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
8300: 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 62 75 73 79  o <b>sqlite_busy
8310: 5f 74 69 6d 65 6f 75 74 3c 2f 62 3e 20 69 73 20  _timeout</b> is 
8320: 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 61 6e 20  a pointer to.an 
8330: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61  open SQLite data
8340: 62 61 73 65 20 61 6e 64 20 74 68 65 20 73 65 63  base and the sec
8350: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
8360: 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  a number of mill
8370: 69 73 65 63 6f 6e 64 73 2e 0a 41 66 74 65 72 20  iseconds..After 
8380: 3c 62 3e 73 71 6c 69 74 65 5f 62 75 73 79 5f 74  <b>sqlite_busy_t
8390: 69 6d 65 6f 75 74 3c 2f 62 3e 20 68 61 73 20 62  imeout</b> has b
83a0: 65 65 6e 20 65 78 65 63 75 74 65 64 2c 20 74 68  een executed, th
83b0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
83c0: 0a 77 69 6c 6c 20 77 61 69 74 20 66 6f 72 20 74  .will wait for t
83d0: 68 65 20 6c 6f 63 6b 20 74 6f 20 63 6c 65 61 72  he lock to clear
83e0: 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 74 68   for at least th
83f0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
8400: 69 73 65 63 6f 6e 64 73 20 0a 73 70 65 63 69 66  iseconds .specif
8410: 69 65 64 20 62 65 66 6f 72 65 20 69 74 20 72 65  ied before it re
8420: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 42 55 53  turns SQLITE_BUS
8430: 59 2e 20 20 53 70 65 63 69 66 79 69 6e 67 20 7a  Y.  Specifying z
8440: 65 72 6f 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ero milliseconds
8450: 20 66 6f 72 0a 74 68 65 20 74 69 6d 65 6f 75 74   for.the timeout
8460: 20 72 65 73 74 6f 72 65 73 20 74 68 65 20 64 65   restores the de
8470: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 2e 3c  fault behavior.<
8480: 2f 70 3e 0a 0a 3c 68 34 3e 33 2e 39 20 55 73 69  /p>..<h4>3.9 Usi
8490: 6e 67 20 74 68 65 20 3c 74 74 3e 5f 70 72 69 6e  ng the <tt>_prin
84a0: 74 66 28 29 3c 2f 74 74 3e 20 77 72 61 70 70 65  tf()</tt> wrappe
84b0: 72 20 66 75 6e 63 74 69 6f 6e 73 3c 2f 68 34 3e  r functions</h4>
84c0: 0a 0a 3c 70 3e 54 68 65 20 66 6f 75 72 20 75 74  ..<p>The four ut
84d0: 69 6c 69 74 79 20 66 75 6e 63 74 69 6f 6e 73 3c  ility functions<
84e0: 2f 70 3e 0a 0a 3c 70 3e 0a 3c 75 6c 3e 0a 3c 6c  /p>..<p>.<ul>.<l
84f0: 69 3e 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63  i><b>sqlite_exec
8500: 5f 70 72 69 6e 74 66 28 29 3c 2f 62 3e 3c 2f 6c  _printf()</b></l
8510: 69 3e 0a 3c 6c 69 3e 3c 62 3e 73 71 6c 69 74 65  i>.<li><b>sqlite
8520: 5f 65 78 65 63 5f 76 70 72 69 6e 74 66 28 29 3c  _exec_vprintf()<
8530: 2f 62 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c 62 3e  /b></li>.<li><b>
8540: 73 71 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65  sqlite_get_table
8550: 5f 70 72 69 6e 74 66 28 29 3c 2f 62 3e 3c 2f 6c  _printf()</b></l
8560: 69 3e 0a 3c 6c 69 3e 3c 62 3e 73 71 6c 69 74 65  i>.<li><b>sqlite
8570: 5f 67 65 74 5f 74 61 62 6c 65 5f 76 70 72 69 6e  _get_table_vprin
8580: 74 66 28 29 3c 2f 62 3e 3c 2f 6c 69 3e 0a 3c 2f  tf()</b></li>.</
8590: 75 6c 3e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 69 6d 70  ul>.</p>..<p>imp
85a0: 6c 65 6d 65 6e 74 20 74 68 65 20 73 61 6d 65 20  lement the same 
85b0: 71 75 65 72 79 20 66 75 6e 63 74 69 6f 6e 61 6c  query functional
85c0: 69 74 79 20 61 73 20 3c 62 3e 73 71 6c 69 74 65  ity as <b>sqlite
85d0: 5f 65 78 65 63 3c 2f 62 3e 0a 61 6e 64 20 3c 62  _exec</b>.and <b
85e0: 3e 73 71 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c  >sqlite_get_tabl
85f0: 65 3c 2f 62 3e 2e 20 20 42 75 74 20 69 6e 73 74  e</b>.  But inst
8600: 65 61 64 20 6f 66 20 74 61 6b 69 6e 67 20 61 20  ead of taking a 
8610: 63 6f 6d 70 6c 65 74 65 0a 53 51 4c 20 73 74 61  complete.SQL sta
8620: 74 65 6d 65 6e 74 20 61 73 20 74 68 65 69 72 20  tement as their 
8630: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
8640: 20 74 68 65 20 66 6f 75 72 20 3c 62 3e 5f 70 72   the four <b>_pr
8650: 69 6e 74 66 3c 2f 62 3e 0a 72 6f 75 74 69 6e 65  intf</b>.routine
8660: 73 20 74 61 6b 65 20 61 20 70 72 69 6e 74 66 2d  s take a printf-
8670: 73 74 79 6c 65 20 66 6f 72 6d 61 74 20 73 74 72  style format str
8680: 69 6e 67 2e 20 20 54 68 65 20 53 51 4c 20 73 74  ing.  The SQL st
8690: 61 74 65 6d 65 6e 74 20 74 6f 0a 62 65 20 65 78  atement to.be ex
86a0: 65 63 75 74 65 64 20 69 73 20 67 65 6e 65 72 61  ecuted is genera
86b0: 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 66 6f  ted from this fo
86c0: 72 6d 61 74 20 73 74 72 69 6e 67 20 61 6e 64 20  rmat string and 
86d0: 66 72 6f 6d 20 77 68 61 74 65 76 65 72 0a 61 64  from whatever.ad
86e0: 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
86f0: 74 73 20 61 72 65 20 61 74 74 61 63 68 65 64 20  ts are attached 
8700: 74 6f 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  to the end of th
8710: 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 2e  e function call.
8720: 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 72 65 20 61  </p>..<p>There a
8730: 72 65 20 74 77 6f 20 61 64 76 61 6e 74 61 67 65  re two advantage
8740: 73 20 74 6f 20 75 73 69 6e 67 20 74 68 65 20 53  s to using the S
8750: 51 4c 69 74 65 20 70 72 69 6e 74 66 0a 66 75 6e  QLite printf.fun
8760: 63 74 69 6f 6e 73 20 69 6e 73 74 65 61 64 20 6f  ctions instead o
8770: 66 20 3c 62 3e 73 70 72 69 6e 74 66 3c 2f 62 3e  f <b>sprintf</b>
8780: 2e 20 20 46 69 72 73 74 20 6f 66 20 61 6c 6c 2c  .  First of all,
8790: 20 77 69 74 68 20 74 68 65 0a 53 51 4c 69 74 65   with the.SQLite
87a0: 20 70 72 69 6e 74 66 20 72 6f 75 74 69 6e 65 73   printf routines
87b0: 2c 20 74 68 65 72 65 20 69 73 20 6e 65 76 65 72  , there is never
87c0: 20 61 20 64 61 6e 67 65 72 20 6f 66 20 6f 76 65   a danger of ove
87d0: 72 66 6c 6f 77 69 6e 67 20 61 0a 73 74 61 74 69  rflowing a.stati
87e0: 63 20 62 75 66 66 65 72 20 61 73 20 74 68 65 72  c buffer as ther
87f0: 65 20 69 73 20 77 69 74 68 20 3c 62 3e 73 70 72  e is with <b>spr
8800: 69 6e 74 66 3c 2f 62 3e 2e 20 20 54 68 65 20 53  intf</b>.  The S
8810: 51 4c 69 74 65 0a 70 72 69 6e 74 66 20 72 6f 75  QLite.printf rou
8820: 74 69 6e 65 73 20 61 75 74 6f 6d 61 74 69 63 61  tines automatica
8830: 6c 6c 79 20 61 6c 6c 6f 63 61 74 65 20 28 61 6e  lly allocate (an
8840: 64 20 6c 61 74 65 72 20 66 72 65 65 73 29 0a 61  d later frees).a
8850: 73 20 6d 75 63 68 20 6d 65 6d 6f 72 79 20 61 73  s much memory as
8860: 20 69 73 20 0a 6e 65 63 65 73 73 61 72 79 20 74   is .necessary t
8870: 6f 20 68 6f 6c 64 20 74 68 65 20 53 51 4c 20 73  o hold the SQL s
8880: 74 61 74 65 6d 65 6e 74 73 20 67 65 6e 65 72 61  tatements genera
8890: 74 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65  ted.</p>..<p>The
88a0: 20 73 65 63 6f 6e 64 20 61 64 76 61 6e 74 61 67   second advantag
88b0: 65 20 74 68 65 20 53 51 4c 69 74 65 20 70 72 69  e the SQLite pri
88c0: 6e 74 66 20 72 6f 75 74 69 6e 65 73 20 68 61 76  ntf routines hav
88d0: 65 20 6f 76 65 72 0a 3c 62 3e 73 70 72 69 6e 74  e over.<b>sprint
88e0: 66 3c 2f 62 3e 20 61 72 65 20 74 77 6f 20 6e 65  f</b> are two ne
88f0: 77 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  w formatting opt
8900: 69 6f 6e 73 20 73 70 65 63 69 66 69 63 61 6c 6c  ions specificall
8910: 79 20 64 65 73 69 67 6e 65 64 0a 74 6f 20 73 75  y designed.to su
8920: 70 70 6f 72 74 20 73 74 72 69 6e 67 20 6c 69 74  pport string lit
8930: 65 72 61 6c 73 20 69 6e 20 53 51 4c 2e 20 20 57  erals in SQL.  W
8940: 69 74 68 69 6e 20 74 68 65 20 66 6f 72 6d 61 74  ithin the format
8950: 20 73 74 72 69 6e 67 2c 0a 74 68 65 20 25 71 20   string,.the %q 
8960: 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
8970: 6e 20 77 6f 72 6b 73 20 76 65 72 79 20 6d 75 63  n works very muc
8980: 68 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  h like %s in tha
8990: 74 20 69 74 0a 72 65 61 64 73 20 61 20 6e 75 6c  t it.reads a nul
89a0: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  l-terminated str
89b0: 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
89c0: 75 6d 65 6e 74 20 6c 69 73 74 20 61 6e 64 20 69  ument list and i
89d0: 6e 73 65 72 74 73 0a 69 74 20 69 6e 74 6f 20 74  nserts.it into t
89e0: 68 65 20 72 65 73 75 6c 74 2e 20 20 42 75 74 20  he result.  But 
89f0: 25 71 20 74 72 61 6e 73 6c 61 74 65 73 20 74 68  %q translates th
8a00: 65 20 69 6e 73 65 72 74 65 64 20 73 74 72 69 6e  e inserted strin
8a10: 67 20 62 79 0a 6d 61 6b 69 6e 67 20 74 77 6f 20  g by.making two 
8a20: 63 6f 70 69 65 73 20 6f 66 20 65 76 65 72 79 20  copies of every 
8a30: 73 69 6e 67 6c 65 2d 71 75 6f 74 65 20 28 27 29  single-quote (')
8a40: 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 74 68   character in th
8a50: 65 0a 73 75 62 73 74 69 74 75 74 65 64 20 73 74  e.substituted st
8a60: 72 69 6e 67 2e 20 20 54 68 69 73 20 68 61 73 20  ring.  This has 
8a70: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 65 73  the effect of es
8a80: 63 61 70 69 6e 67 20 74 68 65 20 65 6e 64 2d 6f  caping the end-o
8a90: 66 2d 73 74 72 69 6e 67 0a 6d 65 61 6e 69 6e 67  f-string.meaning
8aa0: 20 6f 66 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65   of single-quote
8ab0: 20 77 69 74 68 69 6e 20 61 20 73 74 72 69 6e 67   within a string
8ac0: 20 6c 69 74 65 72 61 6c 2e 20 54 68 65 20 25 51   literal. The %Q
8ad0: 20 66 6f 72 6d 61 74 74 69 6e 67 0a 6f 70 74 69   formatting.opti
8ae0: 6f 6e 20 77 6f 72 6b 73 20 73 69 6d 69 6c 61 72  on works similar
8af0: 3b 20 69 74 20 74 72 61 6e 73 6c 61 74 65 73 20  ; it translates 
8b00: 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65  the single-quote
8b10: 73 20 6c 69 6b 65 20 25 71 20 61 6e 64 0a 61 64  s like %q and.ad
8b20: 64 69 74 69 6f 6e 61 6c 6c 79 20 65 6e 63 6c 6f  ditionally enclo
8b30: 73 65 73 20 74 68 65 20 72 65 73 75 6c 74 69 6e  ses the resultin
8b40: 67 20 73 74 72 69 6e 67 20 69 6e 20 73 69 6e 67  g string in sing
8b50: 6c 65 2d 71 75 6f 74 65 73 2e 0a 49 66 20 74 68  le-quotes..If th
8b60: 65 20 61 72 67 75 6d 65 6e 74 20 66 6f 72 20 74  e argument for t
8b70: 68 65 20 25 51 20 66 6f 72 6d 61 74 74 69 6e 67  he %Q formatting
8b80: 20 6f 70 74 69 6f 6e 73 20 69 73 20 61 20 4e 55   options is a NU
8b90: 4c 4c 20 70 6f 69 6e 74 65 72 2c 0a 74 68 65 20  LL pointer,.the 
8ba0: 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
8bb0: 20 69 73 20 4e 55 4c 4c 20 77 69 74 68 6f 75 74   is NULL without
8bc0: 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2e 0a   single quotes..
8bd0: 3c 2f 70 3e 0a 0a 3c 70 3e 43 6f 6e 73 69 64 65  </p>..<p>Conside
8be0: 72 20 61 6e 20 65 78 61 6d 70 6c 65 2e 20 20 53  r an example.  S
8bf0: 75 70 70 6f 73 65 20 79 6f 75 20 61 72 65 20 74  uppose you are t
8c00: 72 79 69 6e 67 20 74 6f 20 69 6e 73 65 72 74 20  rying to insert 
8c10: 61 20 73 74 72 69 6e 67 0a 76 61 6c 75 65 20 69  a string.value i
8c20: 6e 74 6f 20 61 20 64 61 74 61 62 61 73 65 20 74  nto a database t
8c30: 61 62 6c 65 20 77 68 65 72 65 20 74 68 65 20 73  able where the s
8c40: 74 72 69 6e 67 20 76 61 6c 75 65 20 77 61 73 20  tring value was 
8c50: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 75 73  obtained from.us
8c60: 65 72 20 69 6e 70 75 74 2e 20 20 53 75 70 70 6f  er input.  Suppo
8c70: 73 65 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  se the string to
8c80: 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 73 20   be inserted is 
8c90: 73 74 6f 72 65 64 20 69 6e 20 61 20 76 61 72 69  stored in a vari
8ca0: 61 62 6c 65 0a 6e 61 6d 65 64 20 7a 53 74 72 69  able.named zStri
8cb0: 6e 67 2e 20 20 54 68 65 20 63 6f 64 65 20 74 6f  ng.  The code to
8cc0: 20 64 6f 20 74 68 65 20 69 6e 73 65 72 74 69 6f   do the insertio
8cd0: 6e 20 6d 69 67 68 74 20 6c 6f 6f 6b 20 6c 69 6b  n might look lik
8ce0: 65 20 74 68 69 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c  e this:</p>..<bl
8cf0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 73  ockquote><pre>.s
8d00: 71 6c 69 74 65 5f 65 78 65 63 5f 70 72 69 6e 74  qlite_exec_print
8d10: 66 28 64 62 2c 0a 20 20 22 49 4e 53 45 52 54 20  f(db,.  "INSERT 
8d20: 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
8d30: 45 53 28 27 25 73 27 29 22 2c 0a 20 20 30 2c 20  ES('%s')",.  0, 
8d40: 30 2c 20 30 2c 20 7a 53 74 72 69 6e 67 29 3b 0a  0, 0, zString);.
8d50: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
8d60: 74 65 3e 0a 0a 3c 70 3e 49 66 20 74 68 65 20 7a  te>..<p>If the z
8d70: 53 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  String variable 
8d80: 68 6f 6c 64 73 20 74 65 78 74 20 6c 69 6b 65 20  holds text like 
8d90: 22 48 65 6c 6c 6f 22 2c 20 74 68 65 6e 20 74 68  "Hello", then th
8da0: 69 73 20 73 74 61 74 65 6d 65 6e 74 0a 77 69 6c  is statement.wil
8db0: 6c 20 77 6f 72 6b 20 6a 75 73 74 20 66 69 6e 65  l work just fine
8dc0: 2e 20 20 42 75 74 20 73 75 70 70 6f 73 65 20 74  .  But suppose t
8dd0: 68 65 20 75 73 65 72 20 65 6e 74 65 72 73 20 61  he user enters a
8de0: 20 73 74 72 69 6e 67 20 6c 69 6b 65 20 0a 22 48   string like ."H
8df0: 69 20 79 27 61 6c 6c 21 22 2e 20 20 54 68 65 20  i y'all!".  The 
8e00: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 67 65  SQL statement ge
8e10: 6e 65 72 61 74 65 64 20 72 65 61 64 73 20 61 73  nerated reads as
8e20: 20 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c 62 6c 6f 63   follows:..<bloc
8e30: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 49 4e 53  kquote><pre>.INS
8e40: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
8e50: 56 41 4c 55 45 53 28 27 48 69 20 79 27 61 6c 6c  VALUES('Hi y'all
8e60: 27 29 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ').</pre></block
8e70: 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 69 73 20  quote>..<p>This 
8e80: 69 73 20 6e 6f 74 20 76 61 6c 69 64 20 53 51 4c  is not valid SQL
8e90: 20 62 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   because of the 
8ea0: 61 70 6f 73 74 72 6f 70 68 79 20 69 6e 20 74 68  apostrophy in th
8eb0: 65 20 77 6f 72 64 20 22 79 27 61 6c 6c 22 2e 0a  e word "y'all"..
8ec0: 42 75 74 20 69 66 20 74 68 65 20 25 71 20 66 6f  But if the %q fo
8ed0: 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
8ee0: 69 73 20 75 73 65 64 20 69 6e 73 74 65 61 64 20  is used instead 
8ef0: 6f 66 20 25 73 2c 20 6c 69 6b 65 20 74 68 69 73  of %s, like this
8f00: 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  :</p>..<blockquo
8f10: 74 65 3e 3c 70 72 65 3e 0a 73 71 6c 69 74 65 5f  te><pre>.sqlite_
8f20: 65 78 65 63 5f 70 72 69 6e 74 66 28 64 62 2c 0a  exec_printf(db,.
8f30: 20 20 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74    "INSERT INTO t
8f40: 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 25 71  able1 VALUES('%q
8f50: 27 29 22 2c 0a 20 20 30 2c 20 30 2c 20 30 2c 20  ')",.  0, 0, 0, 
8f60: 7a 53 74 72 69 6e 67 29 3b 0a 3c 2f 70 72 65 3e  zString);.</pre>
8f70: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
8f80: 70 3e 54 68 65 6e 20 74 68 65 20 67 65 6e 65 72  p>Then the gener
8f90: 61 74 65 64 20 53 51 4c 20 77 69 6c 6c 20 6c 6f  ated SQL will lo
8fa0: 6f 6b 20 6c 69 6b 65 20 74 68 65 20 66 6f 6c 6c  ok like the foll
8fb0: 6f 77 69 6e 67 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f  owing:</p>..<blo
8fc0: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 49 4e  ckquote><pre>.IN
8fd0: 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
8fe0: 20 56 41 4c 55 45 53 28 27 48 69 20 79 27 27 61   VALUES('Hi y''a
8ff0: 6c 6c 27 29 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ll').</pre></blo
9000: 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 48 65 72  ckquote>..<p>Her
9010: 65 20 74 68 65 20 61 70 6f 73 74 72 6f 70 68 79  e the apostrophy
9020: 20 68 61 73 20 62 65 65 6e 20 65 73 63 61 70 65   has been escape
9030: 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 73 74  d and the SQL st
9040: 61 74 65 6d 65 6e 74 20 69 73 20 77 65 6c 6c 2d  atement is well-
9050: 66 6f 72 6d 65 64 2e 0a 57 68 65 6e 20 67 65 6e  formed..When gen
9060: 65 72 61 74 69 6e 67 20 53 51 4c 20 6f 6e 2d 74  erating SQL on-t
9070: 68 65 2d 66 6c 79 20 66 72 6f 6d 20 64 61 74 61  he-fly from data
9080: 20 74 68 61 74 20 6d 69 67 68 74 20 63 6f 6e 74   that might cont
9090: 61 69 6e 20 61 0a 73 69 6e 67 6c 65 2d 71 75 6f  ain a.single-quo
90a0: 74 65 20 63 68 61 72 61 63 74 65 72 20 28 27 29  te character (')
90b0: 2c 20 69 74 20 69 73 20 61 6c 77 61 79 73 20 61  , it is always a
90c0: 20 67 6f 6f 64 20 69 64 65 61 20 74 6f 20 75 73   good idea to us
90d0: 65 20 74 68 65 0a 53 51 4c 69 74 65 20 70 72 69  e the.SQLite pri
90e0: 6e 74 66 20 72 6f 75 74 69 6e 65 73 20 61 6e 64  ntf routines and
90f0: 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 74 69   the %q formatti
9100: 6e 67 20 6f 70 74 69 6f 6e 20 69 6e 73 74 65 61  ng option instea
9110: 64 20 6f 66 20 3c 62 3e 73 70 72 69 6e 74 66 3c  d of <b>sprintf<
9120: 2f 62 3e 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 49 66  /b>..</p>..<p>If
9130: 20 74 68 65 20 25 51 20 66 6f 72 6d 61 74 74 69   the %Q formatti
9140: 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ng option is use
9150: 64 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  d instead of %q,
9160: 20 6c 69 6b 65 20 74 68 69 73 3a 3c 2f 70 3e 0a   like this:</p>.
9170: 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72  .<blockquote><pr
9180: 65 3e 0a 73 71 6c 69 74 65 5f 65 78 65 63 5f 70  e>.sqlite_exec_p
9190: 72 69 6e 74 66 28 64 62 2c 0a 20 20 22 49 4e 53  rintf(db,.  "INS
91a0: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
91b0: 56 41 4c 55 45 53 28 25 51 29 22 2c 0a 20 20 30  VALUES(%Q)",.  0
91c0: 2c 20 30 2c 20 30 2c 20 7a 53 74 72 69 6e 67 29  , 0, 0, zString)
91d0: 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  ;.</pre></blockq
91e0: 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 6e 20 74  uote>..<p>Then t
91f0: 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
9200: 20 77 69 6c 6c 20 6c 6f 6f 6b 20 6c 69 6b 65 20   will look like 
9210: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a 3c 2f  the following:</
9220: 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  p>..<blockquote>
9230: 3c 70 72 65 3e 0a 49 4e 53 45 52 54 20 49 4e 54  <pre>.INSERT INT
9240: 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
9250: 27 48 69 20 79 27 27 61 6c 6c 27 29 0a 3c 2f 70  'Hi y''all').</p
9260: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
9270: 0a 0a 3c 70 3e 49 66 20 74 68 65 20 76 61 6c 75  ..<p>If the valu
9280: 65 20 6f 66 20 74 68 65 20 7a 53 74 72 69 6e 67  e of the zString
9290: 20 76 61 72 69 61 62 6c 65 20 69 73 20 4e 55 4c   variable is NUL
92a0: 4c 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  L, the generated
92b0: 20 53 51 4c 0a 77 69 6c 6c 20 6c 6f 6f 6b 20 6c   SQL.will look l
92c0: 69 6b 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ike the followin
92d0: 67 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  g:</p>..<blockqu
92e0: 6f 74 65 3e 3c 70 72 65 3e 0a 49 4e 53 45 52 54  ote><pre>.INSERT
92f0: 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
9300: 55 45 53 28 4e 55 4c 4c 29 0a 3c 2f 70 72 65 3e  UES(NULL).</pre>
9310: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
9320: 70 3e 41 6c 6c 20 6f 66 20 74 68 65 20 5f 70 72  p>All of the _pr
9330: 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
9340: 61 62 6f 76 65 20 61 72 65 20 62 75 69 6c 74 20  above are built 
9350: 61 72 6f 75 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  around the follo
9360: 77 69 6e 67 0a 74 77 6f 20 66 75 6e 63 74 69 6f  wing.two functio
9370: 6e 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71  ns:</p>..<blockq
9380: 75 6f 74 65 3e 3c 70 72 65 3e 0a 63 68 61 72 20  uote><pre>.char 
9390: 2a 73 71 6c 69 74 65 5f 6d 70 72 69 6e 74 66 28  *sqlite_mprintf(
93a0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 6f 72  const char *zFor
93b0: 6d 61 74 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20  mat, ...);.char 
93c0: 2a 73 71 6c 69 74 65 5f 76 6d 70 72 69 6e 74 66  *sqlite_vmprintf
93d0: 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 6f  (const char *zFo
93e0: 72 6d 61 74 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  rmat, va_list);.
93f0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
9400: 74 65 3e 0a 0a 3c 70 3e 54 68 65 20 3c 62 3e 73  te>..<p>The <b>s
9410: 71 6c 69 74 65 5f 6d 70 72 69 6e 74 66 28 29 3c  qlite_mprintf()<
9420: 2f 62 3e 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b  /b> routine work
9430: 73 20 6c 69 6b 65 20 74 68 65 20 74 68 65 20 73  s like the the s
9440: 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 0a  tandard library.
9450: 3c 62 3e 73 70 72 69 6e 74 66 28 29 3c 2f 62 3e  <b>sprintf()</b>
9460: 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
9470: 77 72 69 74 65 73 20 69 74 73 20 72 65 73 75 6c  writes its resul
9480: 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
9490: 62 74 61 69 6e 65 64 0a 66 72 6f 6d 20 6d 61 6c  btained.from mal
94a0: 6c 6f 63 28 29 20 61 6e 64 20 72 65 74 75 72 6e  loc() and return
94b0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
94c0: 68 65 20 6d 61 6c 6c 6f 63 65 64 20 62 75 66 66  he malloced buff
94d0: 65 72 2e 20 20 0a 3c 62 3e 73 71 6c 69 74 65 5f  er.  .<b>sqlite_
94e0: 6d 70 72 69 6e 74 66 28 29 3c 2f 62 3e 20 61 6c  mprintf()</b> al
94f0: 73 6f 20 75 6e 64 65 72 73 74 61 6e 64 73 20 74  so understands t
9500: 68 65 20 25 71 20 61 6e 64 20 25 51 20 65 78 74  he %q and %Q ext
9510: 65 6e 73 69 6f 6e 73 20 64 65 73 63 72 69 62 65  ensions describe
9520: 64 0a 61 62 6f 76 65 2e 20 20 54 68 65 20 3c 62  d.above.  The <b
9530: 3e 73 71 6c 69 74 65 5f 76 6d 70 72 69 6e 74 66  >sqlite_vmprintf
9540: 28 29 3c 2f 62 3e 20 69 73 20 61 20 76 61 72 61  ()</b> is a vara
9550: 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  rgs version of t
9560: 68 65 20 73 61 6d 65 0a 72 6f 75 74 69 6e 65 2e  he same.routine.
9570: 20 20 54 68 65 20 73 74 72 69 6e 67 20 70 6f 69    The string poi
9580: 6e 74 65 72 20 74 68 61 74 20 74 68 65 73 65 20  nter that these 
9590: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
95a0: 73 68 6f 75 6c 64 20 62 65 20 66 72 65 65 64 0a  should be freed.
95b0: 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  by passing it to
95c0: 20 3c 62 3e 73 71 6c 69 74 65 5f 66 72 65 65 6d   <b>sqlite_freem
95d0: 65 6d 28 29 3c 2f 62 3e 2e 0a 3c 2f 70 3e 0a 0a  em()</b>..</p>..
95e0: 3c 68 34 3e 33 2e 31 30 20 50 65 72 66 6f 72 6d  <h4>3.10 Perform
95f0: 69 6e 67 20 62 61 63 6b 67 72 6f 75 6e 64 20 6a  ing background j
9600: 6f 62 73 20 64 75 72 69 6e 67 20 6c 61 72 67 65  obs during large
9610: 20 71 75 65 72 69 65 73 3c 2f 68 33 3e 0a 0a 3c   queries</h3>..<
9620: 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f  p>The <b>sqlite_
9630: 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
9640: 28 29 3c 2f 62 3e 20 72 6f 75 74 69 6e 65 20 63  ()</b> routine c
9650: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
9660: 67 69 73 74 65 72 20 61 0a 63 61 6c 6c 62 61 63  gister a.callbac
9670: 6b 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  k routine with a
9680: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
9690: 65 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  e to be invoked 
96a0: 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
96b0: 69 6e 67 20 6c 6f 6e 67 0a 72 75 6e 6e 69 6e 67  ing long.running
96c0: 20 63 61 6c 6c 73 20 74 6f 20 3c 62 3e 73 71 6c   calls to <b>sql
96d0: 69 74 65 5f 65 78 65 63 28 29 3c 2f 62 3e 2c 20  ite_exec()</b>, 
96e0: 3c 62 3e 73 71 6c 69 74 65 5f 73 74 65 70 28 29  <b>sqlite_step()
96f0: 3c 2f 62 3e 20 61 6e 64 20 74 68 65 20 76 61 72  </b> and the var
9700: 69 6f 75 73 0a 77 72 61 70 70 65 72 20 66 75 6e  ious.wrapper fun
9710: 63 74 69 6f 6e 73 2e 0a 3c 2f 70 3e 0a 0a 3c 70  ctions..</p>..<p
9720: 3e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  >The callback is
9730: 20 69 6e 76 6f 6b 65 64 20 65 76 65 72 79 20 4e   invoked every N
9740: 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
9750: 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77 68 65   operations, whe
9760: 72 65 20 4e 20 69 73 0a 73 75 70 70 6c 69 65 64  re N is.supplied
9770: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
9780: 72 67 75 6d 65 6e 74 20 74 6f 20 3c 62 3e 73 71  rgument to <b>sq
9790: 6c 69 74 65 5f 70 72 6f 67 72 65 73 73 5f 68 61  lite_progress_ha
97a0: 6e 64 6c 65 72 28 29 3c 2f 62 3e 2e 20 54 68 65  ndler()</b>. The
97b0: 20 74 68 69 72 64 0a 61 6e 64 20 66 6f 75 72 74   third.and fourt
97c0: 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 3c  h arguments to <
97d0: 62 3e 73 71 6c 69 74 65 5f 70 72 6f 67 72 65 73  b>sqlite_progres
97e0: 73 5f 68 61 6e 64 6c 65 72 28 29 3c 2f 62 3e 20  s_handler()</b> 
97f0: 61 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  are a pointer to
9800: 20 74 68 65 0a 72 6f 75 74 69 6e 65 20 74 6f 20   the.routine to 
9810: 62 65 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 61  be invoked and a
9820: 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 6f   void pointer to
9830: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
9840: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
9850: 20 74 6f 0a 69 74 2e 0a 3c 2f 70 3e 0a 0a 3c 70   to.it..</p>..<p
9860: 3e 54 68 65 20 74 69 6d 65 20 74 61 6b 65 6e 20  >The time taken 
9870: 74 6f 20 65 78 65 63 75 74 65 20 65 61 63 68 20  to execute each 
9880: 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
9890: 6f 70 65 72 61 74 69 6f 6e 20 63 61 6e 20 76 61  operation can va
98a0: 72 79 20 62 61 73 65 64 20 6f 6e 0a 6d 61 6e 79  ry based on.many
98b0: 20 66 61 63 74 6f 72 73 2e 20 20 41 20 74 79 70   factors.  A typ
98c0: 69 63 61 6c 20 76 61 6c 75 65 20 66 6f 72 20 61  ical value for a
98d0: 20 31 20 47 48 7a 20 50 43 20 69 73 20 62 65 74   1 GHz PC is bet
98e0: 77 65 65 6e 20 68 61 6c 66 20 61 6e 64 20 74 68  ween half and th
98f0: 72 65 65 20 6d 69 6c 6c 69 6f 6e 0a 70 65 72 20  ree million.per 
9900: 73 65 63 6f 6e 64 20 62 75 74 20 6d 61 79 20 62  second but may b
9910: 65 20 6d 75 63 68 20 68 69 67 68 65 72 20 6f 72  e much higher or
9920: 20 6c 6f 77 65 72 2c 20 64 65 70 65 6e 64 69 6e   lower, dependin
9930: 67 20 6f 6e 20 74 68 65 20 71 75 65 72 79 2e 20  g on the query. 
9940: 20 41 73 20 73 75 63 68 20 69 74 0a 69 73 20 64   As such it.is d
9950: 69 66 66 69 63 75 6c 74 20 74 6f 20 73 63 68 65  ifficult to sche
9960: 64 75 6c 65 20 62 61 63 6b 67 72 6f 75 6e 64 20  dule background 
9970: 6f 70 65 72 61 74 69 6f 6e 73 20 62 61 73 65 64  operations based
9980: 20 6f 6e 20 76 69 72 74 75 61 6c 20 6d 61 63 68   on virtual mach
9990: 69 6e 65 0a 6f 70 65 72 61 74 69 6f 6e 73 2e 20  ine.operations. 
99a0: 49 6e 73 74 65 61 64 2c 20 69 74 20 69 73 20 72  Instead, it is r
99b0: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
99c0: 61 20 63 61 6c 6c 62 61 63 6b 20 62 65 20 73 63  a callback be sc
99d0: 68 65 64 75 6c 65 64 20 72 65 6c 61 74 69 76 65  heduled relative
99e0: 6c 79 0a 66 72 65 71 75 65 6e 74 6c 79 20 28 73  ly.frequently (s
99f0: 61 79 20 65 76 65 72 79 20 31 30 30 30 20 69 6e  ay every 1000 in
9a00: 73 74 72 75 63 74 69 6f 6e 73 29 20 61 6e 64 20  structions) and 
9a10: 65 78 74 65 72 6e 61 6c 20 74 69 6d 65 72 20 72  external timer r
9a20: 6f 75 74 69 6e 65 73 20 75 73 65 64 20 74 6f 0a  outines used to.
9a30: 64 65 74 65 72 6d 69 6e 65 20 77 68 65 74 68 65  determine whethe
9a40: 72 20 6f 72 20 6e 6f 74 20 62 61 63 6b 67 72 6f  r or not backgro
9a50: 75 6e 64 20 6a 6f 62 73 20 6e 65 65 64 20 74 6f  und jobs need to
9a60: 20 62 65 20 72 75 6e 2e 20 20 0a 3c 2f 70 3e 0a   be run.  .</p>.
9a70: 0a 3c 61 20 6e 61 6d 65 3d 22 63 66 75 6e 63 22  .<a name="cfunc"
9a80: 3e 0a 3c 68 33 3e 34 2e 30 20 41 64 64 69 6e 67  >.<h3>4.0 Adding
9a90: 20 4e 65 77 20 53 51 4c 20 46 75 6e 63 74 69 6f   New SQL Functio
9aa0: 6e 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 42 65 67 69  ns</h3>..<p>Begi
9ab0: 6e 6e 69 6e 67 20 77 69 74 68 20 76 65 72 73 69  nning with versi
9ac0: 6f 6e 20 32 2e 34 2e 30 2c 20 53 51 4c 69 74 65  on 2.4.0, SQLite
9ad0: 20 61 6c 6c 6f 77 73 20 74 68 65 20 53 51 4c 20   allows the SQL 
9ae0: 6c 61 6e 67 75 61 67 65 20 74 6f 20 62 65 0a 65  language to be.e
9af0: 78 74 65 6e 64 65 64 20 77 69 74 68 20 6e 65 77  xtended with new
9b00: 20 66 75 6e 63 74 69 6f 6e 73 20 69 6d 70 6c 65   functions imple
9b10: 6d 65 6e 74 65 64 20 61 73 20 43 20 63 6f 64 65  mented as C code
9b20: 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  .  The following
9b30: 20 69 6e 74 65 72 66 61 63 65 0a 69 73 20 75 73   interface.is us
9b40: 65 64 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b  ed:.</p>..<block
9b50: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 74 79 70 65  quote><pre>.type
9b60: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
9b70: 65 5f 66 75 6e 63 20 73 71 6c 69 74 65 5f 66 75  e_func sqlite_fu
9b80: 6e 63 3b 0a 0a 69 6e 74 20 73 71 6c 69 74 65 5f  nc;..int sqlite_
9b90: 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
9ba0: 0a 20 20 73 71 6c 69 74 65 20 2a 64 62 2c 0a 20  .  sqlite *db,. 
9bb0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
9bc0: 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
9bd0: 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
9be0: 73 71 6c 69 74 65 5f 66 75 6e 63 2a 2c 69 6e 74  sqlite_func*,int
9bf0: 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2a 29 2c 0a  ,const char**),.
9c00: 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
9c10: 61 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 5f  a.);.int sqlite_
9c20: 63 72 65 61 74 65 5f 61 67 67 72 65 67 61 74 65  create_aggregate
9c30: 28 0a 20 20 73 71 6c 69 74 65 20 2a 64 62 2c 0a  (.  sqlite *db,.
9c40: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
9c50: 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
9c60: 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
9c70: 28 73 71 6c 69 74 65 5f 66 75 6e 63 2a 2c 69 6e  (sqlite_func*,in
9c80: 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2a 29 2c  t,const char**),
9c90: 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
9ca0: 69 7a 65 29 28 73 71 6c 69 74 65 5f 66 75 6e 63  ize)(sqlite_func
9cb0: 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
9cc0: 72 44 61 74 61 0a 29 3b 0a 0a 63 68 61 72 20 2a  rData.);..char *
9cd0: 73 71 6c 69 74 65 5f 73 65 74 5f 72 65 73 75 6c  sqlite_set_resul
9ce0: 74 5f 73 74 72 69 6e 67 28 73 71 6c 69 74 65 5f  t_string(sqlite_
9cf0: 66 75 6e 63 2a 2c 63 6f 6e 73 74 20 63 68 61 72  func*,const char
9d00: 2a 2c 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  *,int);.void sql
9d10: 69 74 65 5f 73 65 74 5f 72 65 73 75 6c 74 5f 69  ite_set_result_i
9d20: 6e 74 28 73 71 6c 69 74 65 5f 66 75 6e 63 2a 2c  nt(sqlite_func*,
9d30: 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
9d40: 65 5f 73 65 74 5f 72 65 73 75 6c 74 5f 64 6f 75  e_set_result_dou
9d50: 62 6c 65 28 73 71 6c 69 74 65 5f 66 75 6e 63 2a  ble(sqlite_func*
9d60: 2c 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73  ,double);.void s
9d70: 71 6c 69 74 65 5f 73 65 74 5f 72 65 73 75 6c 74  qlite_set_result
9d80: 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 5f 66 75  _error(sqlite_fu
9d90: 6e 63 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nc*,const char*,
9da0: 69 6e 74 29 3b 0a 0a 76 6f 69 64 20 2a 73 71 6c  int);..void *sql
9db0: 69 74 65 5f 75 73 65 72 5f 64 61 74 61 28 73 71  ite_user_data(sq
9dc0: 6c 69 74 65 5f 66 75 6e 63 2a 29 3b 0a 76 6f 69  lite_func*);.voi
9dd0: 64 20 2a 73 71 6c 69 74 65 5f 61 67 67 72 65 67  d *sqlite_aggreg
9de0: 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
9df0: 74 65 5f 66 75 6e 63 2a 2c 20 69 6e 74 20 6e 42  te_func*, int nB
9e00: 79 74 65 73 29 3b 0a 69 6e 74 20 73 71 6c 69 74  ytes);.int sqlit
9e10: 65 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  e_aggregate_coun
9e20: 74 28 73 71 6c 69 74 65 5f 66 75 6e 63 2a 29 3b  t(sqlite_func*);
9e30: 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75  .</pre></blockqu
9e40: 6f 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65 20 3c 62  ote>..<p>.The <b
9e50: 3e 73 71 6c 69 74 65 5f 63 72 65 61 74 65 5f 66  >sqlite_create_f
9e60: 75 6e 63 74 69 6f 6e 28 29 3c 2f 62 3e 20 69 6e  unction()</b> in
9e70: 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
9e80: 74 6f 20 63 72 65 61 74 65 20 0a 72 65 67 75 6c  to create .regul
9e90: 61 72 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  ar functions and
9ea0: 20 3c 62 3e 73 71 6c 69 74 65 5f 63 72 65 61 74   <b>sqlite_creat
9eb0: 65 5f 61 67 67 72 65 67 61 74 65 28 29 3c 2f 62  e_aggregate()</b
9ec0: 3e 20 69 73 20 75 73 65 64 20 74 6f 0a 63 72 65  > is used to.cre
9ed0: 61 74 65 20 6e 65 77 20 61 67 67 72 65 67 61 74  ate new aggregat
9ee0: 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 6e  e functions.  In
9ef0: 20 62 6f 74 68 20 63 61 73 65 73 2c 20 74 68 65   both cases, the
9f00: 20 3c 62 3e 64 62 3c 2f 62 3e 0a 70 61 72 61 6d   <b>db</b>.param
9f10: 65 74 65 72 20 69 73 20 61 6e 20 6f 70 65 6e 20  eter is an open 
9f20: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
9f30: 6f 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  on which the fun
9f40: 63 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 62 65  ctions should.be
9f50: 20 72 65 67 69 73 74 65 72 65 64 2c 20 3c 62 3e   registered, <b>
9f60: 7a 4e 61 6d 65 3c 2f 62 3e 20 69 73 20 74 68 65  zName</b> is the
9f70: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77   name of the new
9f80: 20 66 75 6e 63 74 69 6f 6e 2c 0a 3c 62 3e 6e 41   function,.<b>nA
9f90: 72 67 3c 2f 62 3e 20 69 73 20 74 68 65 20 6e 75  rg</b> is the nu
9fa0: 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
9fb0: 73 2c 20 61 6e 64 20 3c 62 3e 70 55 73 65 72 44  s, and <b>pUserD
9fc0: 61 74 61 3c 2f 62 3e 20 69 73 0a 61 20 70 6f 69  ata</b> is.a poi
9fd0: 6e 74 65 72 20 77 68 69 63 68 20 69 73 20 70 61  nter which is pa
9fe0: 73 73 65 64 20 74 68 72 6f 75 67 68 20 75 6e 63  ssed through unc
9ff0: 68 61 6e 67 65 64 20 74 6f 20 74 68 65 20 43 20  hanged to the C 
a000: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 6f  implementation.o
a010: 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2e 20  f the function. 
a020: 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72   Both routines r
a030: 65 74 75 72 6e 20 30 20 6f 6e 20 73 75 63 63 65  eturn 0 on succe
a040: 73 73 20 61 6e 64 20 6e 6f 6e 2d 7a 65 72 6f 0a  ss and non-zero.
a050: 69 66 20 74 68 65 72 65 20 61 72 65 20 61 6e 79  if there are any
a060: 20 65 72 72 6f 72 73 2e 0a 3c 2f 70 3e 0a 0a 3c   errors..</p>..<
a070: 70 3e 0a 54 68 65 20 6c 65 6e 67 74 68 20 6f 66  p>.The length of
a080: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65   a function name
a090: 20 6d 61 79 20 6e 6f 74 20 65 78 63 65 65 64 20   may not exceed 
a0a0: 32 35 35 20 63 68 61 72 61 63 74 65 72 73 2e 0a  255 characters..
a0b0: 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
a0c0: 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e  reate a function
a0d0: 20 77 68 6f 73 65 20 6e 61 6d 65 20 65 78 63 65   whose name exce
a0e0: 65 64 73 20 32 35 35 20 63 68 61 72 61 63 74 65  eds 255 characte
a0f0: 72 73 0a 69 6e 20 6c 65 6e 67 74 68 20 77 69 6c  rs.in length wil
a100: 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 65  l result in an e
a110: 72 72 6f 72 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a  rror..</p>..<p>.
a120: 46 6f 72 20 72 65 67 75 6c 61 72 20 66 75 6e 63  For regular func
a130: 74 69 6f 6e 73 2c 20 74 68 65 20 3c 62 3e 78 46  tions, the <b>xF
a140: 75 6e 63 3c 2f 62 3e 20 63 61 6c 6c 62 61 63 6b  unc</b> callback
a150: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   is invoked once
a160: 0a 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69  .for each functi
a170: 6f 6e 20 63 61 6c 6c 2e 20 20 54 68 65 20 69 6d  on call.  The im
a180: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
a190: 78 46 75 6e 63 20 73 68 6f 75 6c 64 20 63 61 6c  xFunc should cal
a1a0: 6c 0a 6f 6e 65 20 6f 66 20 74 68 65 20 3c 62 3e  l.one of the <b>
a1b0: 73 71 6c 69 74 65 5f 73 65 74 5f 72 65 73 75 6c  sqlite_set_resul
a1c0: 74 5f 2e 2e 2e 3c 2f 62 3e 20 69 6e 74 65 72 66  t_...</b> interf
a1d0: 61 63 65 73 20 74 6f 20 72 65 74 75 72 6e 20 69  aces to return i
a1e0: 74 73 0a 72 65 73 75 6c 74 2e 20 20 54 68 65 20  ts.result.  The 
a1f0: 3c 62 3e 73 71 6c 69 74 65 5f 75 73 65 72 5f 64  <b>sqlite_user_d
a200: 61 74 61 28 29 3c 2f 62 3e 20 72 6f 75 74 69 6e  ata()</b> routin
a210: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
a220: 0a 72 65 74 72 69 65 76 65 20 74 68 65 20 3c 62  .retrieve the <b
a230: 3e 70 55 73 65 72 44 61 74 61 3c 2f 62 3e 20 70  >pUserData</b> p
a240: 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
a250: 70 61 73 73 65 64 20 69 6e 20 77 68 65 6e 20 74  passed in when t
a260: 68 65 0a 66 75 6e 63 74 69 6f 6e 20 77 61 73 20  he.function was 
a270: 72 65 67 69 73 74 65 72 65 64 2e 0a 3c 2f 70 3e  registered..</p>
a280: 0a 0a 3c 70 3e 0a 46 6f 72 20 61 67 67 72 65 67  ..<p>.For aggreg
a290: 61 74 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 74  ate functions, t
a2a0: 68 65 20 3c 62 3e 78 53 74 65 70 3c 2f 62 3e 20  he <b>xStep</b> 
a2b0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
a2c0: 6b 65 64 20 6f 6e 63 65 0a 66 6f 72 20 65 61 63  ked once.for eac
a2d0: 68 20 72 6f 77 20 69 6e 20 74 68 65 20 72 65 73  h row in the res
a2e0: 75 6c 74 20 61 6e 64 20 74 68 65 6e 20 3c 62 3e  ult and then <b>
a2f0: 78 46 69 6e 61 6c 69 7a 65 3c 2f 62 3e 20 69 73  xFinalize</b> is
a300: 20 69 6e 76 6f 6b 65 64 20 61 74 20 74 68 65 0a   invoked at the.
a310: 65 6e 64 20 74 6f 20 63 6f 6d 70 75 74 65 20 61  end to compute a
a320: 20 66 69 6e 61 6c 20 61 6e 73 77 65 72 2e 20 20   final answer.  
a330: 54 68 65 20 78 53 74 65 70 20 72 6f 75 74 69 6e  The xStep routin
a340: 65 20 63 61 6e 20 75 73 65 20 74 68 65 0a 3c 62  e can use the.<b
a350: 3e 73 71 6c 69 74 65 5f 61 67 67 72 65 67 61 74  >sqlite_aggregat
a360: 65 5f 63 6f 6e 74 65 78 74 28 29 3c 2f 62 3e 20  e_context()</b> 
a370: 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 6c 6c  interface to all
a380: 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 68 61  ocate memory tha
a390: 74 0a 77 69 6c 6c 20 62 65 20 75 6e 69 71 75 65  t.will be unique
a3a0: 20 74 6f 20 74 68 61 74 20 70 61 72 74 69 63 75   to that particu
a3b0: 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  lar instance of 
a3c0: 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
a3d0: 2e 0a 54 68 69 73 20 6d 65 6d 6f 72 79 20 77 69  ..This memory wi
a3e0: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
a3f0: 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 66 74 65  lly deleted afte
a400: 72 20 78 46 69 6e 61 6c 69 7a 65 20 69 73 20 63  r xFinalize is c
a410: 61 6c 6c 65 64 2e 0a 54 68 65 20 3c 62 3e 73 71  alled..The <b>sq
a420: 6c 69 74 65 5f 61 67 67 72 65 67 61 74 65 5f 63  lite_aggregate_c
a430: 6f 75 6e 74 28 29 3c 2f 62 3e 20 72 6f 75 74 69  ount()</b> routi
a440: 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
a450: 6f 20 66 69 6e 64 20 6f 75 74 0a 68 6f 77 20 6d  o find out.how m
a460: 61 6e 79 20 72 6f 77 73 20 6f 66 20 64 61 74 61  any rows of data
a470: 20 77 65 72 65 20 70 61 73 73 65 64 20 74 6f 20   were passed to 
a480: 74 68 65 20 61 67 67 72 65 67 61 74 65 2e 20 20  the aggregate.  
a490: 54 68 65 20 78 46 69 6e 61 6c 69 7a 65 0a 63 61  The xFinalize.ca
a4a0: 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 69 6e  llback should in
a4b0: 76 6f 6b 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  voke one of the 
a4c0: 3c 62 3e 73 71 6c 69 74 65 5f 73 65 74 5f 72 65  <b>sqlite_set_re
a4d0: 73 75 6c 74 5f 2e 2e 2e 3c 2f 62 3e 0a 69 6e 74  sult_...</b>.int
a4e0: 65 72 66 61 63 65 73 20 74 6f 20 73 65 74 20 74  erfaces to set t
a4f0: 68 65 20 66 69 6e 61 6c 20 72 65 73 75 6c 74 20  he final result 
a500: 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
a510: 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 53 51 4c 69  ..</p>..<p>.SQLi
a520: 74 65 20 6e 6f 77 20 69 6d 70 6c 65 6d 65 6e 74  te now implement
a530: 73 20 61 6c 6c 20 6f 66 20 69 74 73 20 62 75 69  s all of its bui
a540: 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
a550: 75 73 69 6e 67 20 74 68 69 73 0a 69 6e 74 65 72  using this.inter
a560: 66 61 63 65 2e 20 20 46 6f 72 20 61 64 64 69 74  face.  For addit
a570: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
a580: 6e 20 61 6e 64 20 65 78 61 6d 70 6c 65 73 20 6f  n and examples o
a590: 6e 20 68 6f 77 20 74 6f 20 63 72 65 61 74 65 0a  n how to create.
a5a0: 6e 65 77 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  new SQL function
a5b0: 73 2c 20 72 65 76 69 65 77 20 74 68 65 20 53 51  s, review the SQ
a5c0: 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65  Lite source code
a5d0: 20 69 6e 20 74 68 65 20 66 69 6c 65 0a 3c 62 3e   in the file.<b>
a5e0: 66 75 6e 63 2e 63 3c 2f 62 3e 2e 0a 3c 2f 70 3e  func.c</b>..</p>
a5f0: 0a 0a 3c 68 33 3e 35 2e 30 20 4d 75 6c 74 69 2d  ..<h3>5.0 Multi-
a600: 54 68 72 65 61 64 69 6e 67 20 41 6e 64 20 53 51  Threading And SQ
a610: 4c 69 74 65 3c 2f 68 33 3e 0a 0a 3c 70 3e 0a 49  Lite</h3>..<p>.I
a620: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
a630: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 54 48  iled with the TH
a640: 52 45 41 44 53 41 46 45 20 70 72 65 70 72 6f 63  READSAFE preproc
a650: 65 73 73 6f 72 20 6d 61 63 72 6f 20 73 65 74 20  essor macro set 
a660: 74 6f 20 31 2c 0a 74 68 65 6e 20 69 74 20 69 73  to 1,.then it is
a670: 20 73 61 66 65 20 74 6f 20 75 73 65 20 53 51 4c   safe to use SQL
a680: 69 74 65 20 66 72 6f 6d 20 74 77 6f 20 6f 72 20  ite from two or 
a690: 6d 6f 72 65 20 74 68 72 65 61 64 73 20 6f 66 20  more threads of 
a6a0: 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
a6b0: 0a 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d  .at the same tim
a6c0: 65 2e 20 20 42 75 74 20 65 61 63 68 20 74 68 72  e.  But each thr
a6d0: 65 61 64 20 73 68 6f 75 6c 64 20 68 61 76 65 20  ead should have 
a6e0: 69 74 73 20 6f 77 6e 20 3c 62 3e 73 71 6c 69 74  its own <b>sqlit
a6f0: 65 2a 3c 2f 62 3e 0a 70 6f 69 6e 74 65 72 20 72  e*</b>.pointer r
a700: 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 3c 62 3e  eturned from <b>
a710: 73 71 6c 69 74 65 5f 6f 70 65 6e 3c 2f 62 3e 2e  sqlite_open</b>.
a720: 20 20 49 74 20 69 73 20 6e 65 76 65 72 20 73 61    It is never sa
a730: 66 65 20 66 6f 72 20 74 77 6f 0a 6f 72 20 6d 6f  fe for two.or mo
a740: 72 65 20 74 68 72 65 61 64 73 20 74 6f 20 61 63  re threads to ac
a750: 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 3c 62  cess the same <b
a760: 3e 73 71 6c 69 74 65 2a 3c 2f 62 3e 20 70 6f 69  >sqlite*</b> poi
a770: 6e 74 65 72 20 61 74 20 74 68 65 20 73 61 6d 65  nter at the same
a780: 20 74 69 6d 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e   time..</p>..<p>
a790: 0a 49 6e 20 70 72 65 63 6f 6d 70 69 6c 65 64 20  .In precompiled 
a7a0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 69 65 73  SQLite libraries
a7b0: 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68   available on th
a7c0: 65 20 77 65 62 73 69 74 65 2c 20 74 68 65 20 55  e website, the U
a7d0: 6e 69 78 0a 76 65 72 73 69 6f 6e 73 20 61 72 65  nix.versions are
a7e0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 54   compiled with T
a7f0: 48 52 45 41 44 53 41 46 45 20 74 75 72 6e 65 64  HREADSAFE turned
a800: 20 6f 66 66 20 62 75 74 20 74 68 65 20 77 69 6e   off but the win
a810: 64 6f 77 73 0a 76 65 72 73 69 6f 6e 73 20 61 72  dows.versions ar
a820: 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  e compiled with 
a830: 54 48 52 45 41 44 53 41 46 45 20 74 75 72 6e 65  THREADSAFE turne
a840: 64 20 6f 6e 2e 20 20 49 66 20 79 6f 75 20 6e 65  d on.  If you ne
a850: 65 64 20 73 6f 6d 65 74 68 69 6e 67 0a 64 69 66  ed something.dif
a860: 66 65 72 65 6e 74 20 74 68 61 74 20 74 68 69 73  ferent that this
a870: 20 79 6f 75 20 77 69 6c 6c 20 68 61 76 65 20 74   you will have t
a880: 6f 20 72 65 63 6f 6d 70 69 6c 65 2e 0a 3c 2f 70  o recompile..</p
a890: 3e 0a 0a 3c 70 3e 0a 55 6e 64 65 72 20 55 6e 69  >..<p>.Under Uni
a8a0: 78 2c 20 61 6e 20 3c 62 3e 73 71 6c 69 74 65 2a  x, an <b>sqlite*
a8b0: 3c 2f 62 3e 20 70 6f 69 6e 74 65 72 20 73 68 6f  </b> pointer sho
a8c0: 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 72 72 69  uld not be carri
a8d0: 65 64 20 61 63 72 6f 73 73 20 61 0a 3c 62 3e 66  ed across a.<b>f
a8e0: 6f 72 6b 28 29 3c 2f 62 3e 20 73 79 73 74 65 6d  ork()</b> system
a8f0: 20 63 61 6c 6c 20 69 6e 74 6f 20 74 68 65 20 63   call into the c
a900: 68 69 6c 64 20 70 72 6f 63 65 73 73 2e 20 20 54  hild process.  T
a910: 68 65 20 63 68 69 6c 64 20 70 72 6f 63 65 73 73  he child process
a920: 0a 73 68 6f 75 6c 64 20 6f 70 65 6e 20 69 74 73  .should open its
a930: 20 6f 77 6e 20 63 6f 70 79 20 6f 66 20 74 68 65   own copy of the
a940: 20 64 61 74 61 62 61 73 65 20 61 66 74 65 72 20   database after 
a950: 74 68 65 20 3c 62 3e 66 6f 72 6b 28 29 3c 2f 62  the <b>fork()</b
a960: 3e 2e 0a 3c 2f 70 3e 0a 0a 3c 68 33 3e 36 2e 30  >..</p>..<h3>6.0
a970: 20 55 73 61 67 65 20 45 78 61 6d 70 6c 65 73 3c   Usage Examples<
a980: 2f 68 33 3e 0a 0a 3c 70 3e 46 6f 72 20 65 78 61  /h3>..<p>For exa
a990: 6d 70 6c 65 73 20 6f 66 20 68 6f 77 20 74 68 65  mples of how the
a9a0: 20 53 51 4c 69 74 65 20 43 2f 43 2b 2b 20 69 6e   SQLite C/C++ in
a9b0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
a9c0: 73 65 64 2c 0a 72 65 66 65 72 20 74 6f 20 74 68  sed,.refer to th
a9d0: 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 66 6f  e source code fo
a9e0: 72 20 74 68 65 20 3c 62 3e 73 71 6c 69 74 65 3c  r the <b>sqlite<
a9f0: 2f 62 3e 20 70 72 6f 67 72 61 6d 20 69 6e 20 74  /b> program in t
aa00: 68 65 0a 66 69 6c 65 20 3c 62 3e 73 72 63 2f 73  he.file <b>src/s
aa10: 68 65 6c 6c 2e 63 3c 2f 62 3e 20 6f 66 20 74 68  hell.c</b> of th
aa20: 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 41  e source tree..A
aa30: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
aa40: 61 74 69 6f 6e 20 61 62 6f 75 74 20 73 71 6c 69  ation about sqli
aa50: 74 65 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  te is available 
aa60: 61 74 0a 3c 61 20 68 72 65 66 3d 22 73 71 6c 69  at.<a href="sqli
aa70: 74 65 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 2e  te.html">sqlite.
aa80: 68 74 6d 6c 3c 2f 61 3e 2e 0a 53 65 65 20 61 6c  html</a>..See al
aa90: 73 6f 20 74 68 65 20 73 6f 75 72 63 65 73 20 74  so the sources t
aaa0: 6f 20 74 68 65 20 54 63 6c 20 69 6e 74 65 72 66  o the Tcl interf
aab0: 61 63 65 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ace for SQLite i
aac0: 6e 0a 74 68 65 20 73 6f 75 72 63 65 20 66 69 6c  n.the source fil
aad0: 65 20 3c 62 3e 73 72 63 2f 74 63 6c 73 71 6c 69  e <b>src/tclsqli
aae0: 74 65 2e 63 3c 2f 62 3e 2e 3c 2f 70 3e 0a 7d 0a  te.c</b>.</p>.}.
aaf0: 66 6f 6f 74 65 72 20 24 72 63 73 69 64 0a        footer $rcsid.