/ Hex Artifact Content
Login

Artifact ea5a73b330a7006df87d0a4029569301bbd72029:


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