/ Hex Artifact Content
Login

Artifact bb0d1357328a42b1993d78573e587c6dcbc964b9:


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 74 63 6c 73 71 6c 69 74  ate the tclsqlit
0030: 65 2e 68 74 6d 6c 20 66 69 6c 65 2e 0a 23 0a 73  e.html file..#.s
0040: 65 74 20 72 63 73 69 64 20 7b 24 49 64 3a 20 74  et rcsid {$Id: t
0050: 63 6c 73 71 6c 69 74 65 2e 74 63 6c 2c 76 20 31  clsqlite.tcl,v 1
0060: 2e 31 36 20 32 30 30 36 2f 30 31 2f 30 35 20 31  .16 2006/01/05 1
0070: 35 3a 35 30 3a 30 37 20 64 72 68 20 45 78 70 20  5:50:07 drh Exp 
0080: 24 7d 0a 73 6f 75 72 63 65 20 63 6f 6d 6d 6f 6e  $}.source common
0090: 2e 74 63 6c 0a 68 65 61 64 65 72 20 7b 54 68 65  .tcl.header {The
00a0: 20 54 63 6c 20 69 6e 74 65 72 66 61 63 65 20 74   Tcl interface t
00b0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
00c0: 72 61 72 79 7d 0a 70 72 6f 63 20 4d 45 54 48 4f  rary}.proc METHO
00d0: 44 20 7b 6e 61 6d 65 20 74 65 78 74 7d 20 7b 0a  D {name text} {.
00e0: 20 20 70 75 74 73 20 22 3c 61 20 6e 61 6d 65 3d    puts "<a name=
00f0: 5c 22 24 6e 61 6d 65 5c 22 3e 5c 6e 3c 68 33 3e  \"$name\">\n<h3>
0100: 54 68 65 20 5c 22 24 6e 61 6d 65 5c 22 20 6d 65  The \"$name\" me
0110: 74 68 6f 64 3c 2f 68 33 3e 5c 6e 22 0a 20 20 70  thod</h3>\n".  p
0120: 75 74 73 20 24 74 65 78 74 0a 7d 0a 70 75 74 73  uts $text.}.puts
0130: 20 7b 0a 3c 68 32 3e 54 68 65 20 54 63 6c 20 69   {.<h2>The Tcl i
0140: 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
0150: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 3c 2f  SQLite library</
0160: 68 32 3e 0a 0a 3c 70 3e 54 68 65 20 53 51 4c 69  h2>..<p>The SQLi
0170: 74 65 20 6c 69 62 72 61 72 79 20 69 73 20 64 65  te library is de
0180: 73 69 67 6e 65 64 20 74 6f 20 62 65 20 76 65 72  signed to be ver
0190: 79 20 65 61 73 79 20 74 6f 20 75 73 65 20 66 72  y easy to use fr
01a0: 6f 6d 0a 61 20 54 63 6c 20 6f 72 20 54 63 6c 2f  om.a Tcl or Tcl/
01b0: 54 6b 20 73 63 72 69 70 74 2e 20 20 54 68 69 73  Tk script.  This
01c0: 20 64 6f 63 75 6d 65 6e 74 20 67 69 76 65 73 20   document gives 
01d0: 61 6e 20 6f 76 65 72 76 69 65 77 20 6f 66 20 74  an overview of t
01e0: 68 65 20 54 63 6c 0a 70 72 6f 67 72 61 6d 6d 69  he Tcl.programmi
01f0: 6e 67 20 69 6e 74 65 72 66 61 63 65 2e 3c 2f 70  ng interface.</p
0200: 3e 0a 0a 3c 68 33 3e 54 68 65 20 41 50 49 3c 2f  >..<h3>The API</
0210: 68 33 3e 0a 0a 3c 70 3e 54 68 65 20 69 6e 74 65  h3>..<p>The inte
0220: 72 66 61 63 65 20 74 6f 20 74 68 65 20 53 51 4c  rface to the SQL
0230: 69 74 65 20 6c 69 62 72 61 72 79 20 63 6f 6e 73  ite library cons
0240: 69 73 74 73 20 6f 66 20 73 69 6e 67 6c 65 0a 74  ists of single.t
0250: 63 6c 20 63 6f 6d 6d 61 6e 64 20 6e 61 6d 65 64  cl command named
0260: 20 3c 62 3e 73 71 6c 69 74 65 3c 2f 62 3e 20 28   <b>sqlite</b> (
0270: 76 65 72 73 69 6f 6e 20 32 2e 38 29 20 6f 72 20  version 2.8) or 
0280: 3c 62 3e 73 71 6c 69 74 65 33 3c 2f 62 3e 0a 28  <b>sqlite3</b>.(
0290: 76 65 72 73 69 6f 6e 20 33 2e 30 29 2e 20 20 42  version 3.0).  B
02a0: 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20  ecause there is 
02b0: 6f 6e 6c 79 20 74 68 69 73 0a 6f 6e 65 20 63 6f  only this.one co
02c0: 6d 6d 61 6e 64 2c 20 74 68 65 20 69 6e 74 65 72  mmand, the inter
02d0: 66 61 63 65 20 69 73 20 6e 6f 74 20 70 6c 61 63  face is not plac
02e0: 65 64 20 69 6e 20 61 20 73 65 70 61 72 61 74 65  ed in a separate
02f0: 0a 6e 61 6d 65 73 70 61 63 65 2e 3c 2f 70 3e 0a  .namespace.</p>.
0300: 0a 3c 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69 74  .<p>The <b>sqlit
0310: 65 33 3c 2f 62 3e 20 63 6f 6d 6d 61 6e 64 20 69  e3</b> command i
0320: 73 20 75 73 65 64 20 61 73 20 66 6f 6c 6c 6f 77  s used as follow
0330: 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  s:</p>..<blockqu
0340: 6f 74 65 3e 0a 3c 62 3e 73 71 6c 69 74 65 33 3c  ote>.<b>sqlite3<
0350: 2f 62 3e 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c  /b>&nbsp;&nbsp;<
0360: 69 3e 64 62 63 6d 64 26 6e 62 73 70 3b 26 6e 62  i>dbcmd&nbsp;&nb
0370: 73 70 3b 64 61 74 61 62 61 73 65 2d 6e 61 6d 65  sp;database-name
0380: 3c 2f 69 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74  </i>.</blockquot
0390: 65 3e 0a 0a 3c 70 3e 0a 54 68 65 20 3c 62 3e 73  e>..<p>.The <b>s
03a0: 71 6c 69 74 65 33 3c 2f 62 3e 20 63 6f 6d 6d 61  qlite3</b> comma
03b0: 6e 64 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74  nd opens the dat
03c0: 61 62 61 73 65 20 6e 61 6d 65 64 20 69 6e 20 74  abase named in t
03d0: 68 65 20 73 65 63 6f 6e 64 0a 61 72 67 75 6d 65  he second.argume
03e0: 6e 74 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  nt.  If the data
03f0: 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 20 61 6c  base does not al
0400: 72 65 61 64 79 20 65 78 69 73 74 2c 20 69 74 20  ready exist, it 
0410: 69 73 0a 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is.automatically
0420: 20 63 72 65 61 74 65 64 2e 0a 54 68 65 20 3c 62   created..The <b
0430: 3e 73 71 6c 69 74 65 33 3c 2f 62 3e 20 63 6f 6d  >sqlite3</b> com
0440: 6d 61 6e 64 20 61 6c 73 6f 20 63 72 65 61 74 65  mand also create
0450: 73 20 61 20 6e 65 77 20 54 63 6c 0a 63 6f 6d 6d  s a new Tcl.comm
0460: 61 6e 64 20 74 6f 20 63 6f 6e 74 72 6f 6c 20 74  and to control t
0470: 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  he database.  Th
0480: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65  e name of the ne
0490: 77 20 54 63 6c 20 63 6f 6d 6d 61 6e 64 0a 69 73  w Tcl command.is
04a0: 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 66 69   given by the fi
04b0: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  rst argument.  T
04c0: 68 69 73 20 61 70 70 72 6f 61 63 68 20 69 73 20  his approach is 
04d0: 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 65 0a 77  similar to the.w
04e0: 61 79 20 77 69 64 67 65 74 73 20 61 72 65 20 63  ay widgets are c
04f0: 72 65 61 74 65 64 20 69 6e 20 54 6b 2e 0a 3c 2f  reated in Tk..</
0500: 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 6e 61 6d 65  p>..<p>.The name
0510: 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
0520: 20 69 73 20 6a 75 73 74 20 74 68 65 20 6e 61 6d   is just the nam
0530: 65 20 6f 66 20 61 20 64 69 73 6b 20 66 69 6c 65  e of a disk file
0540: 20 69 6e 20 77 68 69 63 68 0a 74 68 65 20 64 61   in which.the da
0550: 74 61 62 61 73 65 20 69 73 20 73 74 6f 72 65 64  tabase is stored
0560: 2e 20 20 49 66 20 74 68 65 20 6e 61 6d 65 20 6f  .  If the name o
0570: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
0580: 73 20 61 6e 20 65 6d 70 74 79 0a 73 74 72 69 6e  s an empty.strin
0590: 67 20 6f 72 20 74 68 65 20 73 70 65 63 69 61 6c  g or the special
05a0: 20 6e 61 6d 65 20 22 3a 6d 65 6d 6f 72 79 3a 22   name ":memory:"
05b0: 20 74 68 65 6e 20 61 20 6e 65 77 20 64 61 74 61   then a new data
05c0: 62 61 73 65 20 69 73 20 63 72 65 61 74 65 64 0a  base is created.
05d0: 69 6e 20 6d 65 6d 6f 72 79 2e 0a 3c 2f 70 3e 0a  in memory..</p>.
05e0: 0a 3c 70 3e 0a 4f 6e 63 65 20 61 6e 20 53 51 4c  .<p>.Once an SQL
05f0: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
0600: 6f 70 65 6e 2c 20 69 74 20 63 61 6e 20 62 65 20  open, it can be 
0610: 63 6f 6e 74 72 6f 6c 6c 65 64 20 75 73 69 6e 67  controlled using
0620: 20 0a 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65   .methods of the
0630: 20 3c 69 3e 64 62 63 6d 64 3c 2f 69 3e 2e 20 20   <i>dbcmd</i>.  
0640: 54 68 65 72 65 20 61 72 65 20 63 75 72 72 65 6e  There are curren
0650: 74 6c 79 20 32 31 20 6d 65 74 68 6f 64 73 0a 64  tly 21 methods.d
0660: 65 66 69 6e 65 64 3a 3c 2f 70 3e 0a 0a 3c 70 3e  efined:</p>..<p>
0670: 54 68 65 20 3c 62 3e 73 71 6c 69 74 65 33 3c 2f  The <b>sqlite3</
0680: 62 3e 20 61 6c 73 6f 20 61 63 63 65 70 74 73 20  b> also accepts 
0690: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 74 68 69 72  an optional thir
06a0: 64 20 61 72 67 75 6d 65 6e 74 20 63 61 6c 6c 65  d argument calle
06b0: 64 0a 74 68 65 20 22 6d 6f 64 65 22 2e 20 20 54  d.the "mode".  T
06c0: 68 69 73 20 61 72 67 75 6d 65 6e 74 20 69 73 20  his argument is 
06d0: 61 20 6c 65 67 61 63 79 20 66 72 6f 6d 20 53 51  a legacy from SQ
06e0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
06f0: 6e 64 20 69 73 0a 63 75 72 72 65 6e 74 6c 79 20  nd is.currently 
0700: 69 67 6e 6f 72 65 64 2e 3c 2f 70 3e 0a 0a 3c 70  ignored.</p>..<p
0710: 3e 0a 3c 75 6c 3e 0a 7d 0a 66 6f 72 65 61 63 68  >.<ul>.}.foreach
0720: 20 6d 20 5b 6c 73 6f 72 74 20 7b 0a 20 61 75 74   m [lsort {. aut
0730: 68 6f 72 69 7a 65 72 0a 20 62 75 73 79 0a 20 63  horizer. busy. c
0740: 61 63 68 65 0a 20 63 68 61 6e 67 65 73 0a 20 63  ache. changes. c
0750: 6c 6f 73 65 0a 20 63 6f 6c 6c 61 74 65 0a 20 63  lose. collate. c
0760: 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 0a  ollation_needed.
0770: 20 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 0a 20 63 6f   commit_hook. co
0780: 6d 70 6c 65 74 65 0a 20 63 6f 70 79 0a 20 65 72  mplete. copy. er
0790: 72 6f 72 63 6f 64 65 0a 20 65 76 61 6c 0a 20 65  rorcode. eval. e
07a0: 78 69 73 74 73 0a 20 66 75 6e 63 74 69 6f 6e 0a  xists. function.
07b0: 20 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77   last_insert_row
07c0: 69 64 0a 20 6e 75 6c 6c 76 61 6c 75 65 0a 20 6f  id. nullvalue. o
07d0: 6e 65 63 6f 6c 75 6d 6e 0a 20 70 72 6f 67 72 65  necolumn. progre
07e0: 73 73 0a 20 74 69 6d 65 6f 75 74 0a 20 74 6f 74  ss. timeout. tot
07f0: 61 6c 5f 63 68 61 6e 67 65 73 0a 20 74 72 61 63  al_changes. trac
0800: 65 0a 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 7d  e. transaction.}
0810: 5d 20 7b 0a 20 70 75 74 73 20 22 3c 6c 69 3e 3c  ] {. puts "<li><
0820: 61 20 68 72 65 66 3d 5c 22 23 24 6d 5c 22 3e 24  a href=\"#$m\">$
0830: 6d 3c 2f 61 3e 3c 2f 6c 69 3e 22 0a 7d 0a 70 75  m</a></li>".}.pu
0840: 74 73 20 7b 0a 3c 2f 75 6c 3e 0a 3c 2f 70 3e 0a  ts {.</ul>.</p>.
0850: 0a 3c 70 3e 54 68 65 20 75 73 65 20 6f 66 20 65  .<p>The use of e
0860: 61 63 68 20 6f 66 20 74 68 65 73 65 20 6d 65 74  ach of these met
0870: 68 6f 64 73 20 77 69 6c 6c 20 62 65 20 65 78 70  hods will be exp
0880: 6c 61 69 6e 65 64 20 69 6e 20 74 68 65 20 73 65  lained in the se
0890: 71 75 65 6c 2c 20 74 68 6f 75 67 68 0a 6e 6f 74  quel, though.not
08a0: 20 69 6e 20 74 68 65 20 6f 72 64 65 72 20 73 68   in the order sh
08b0: 6f 77 6e 20 61 62 6f 76 65 2e 3c 2f 70 3e 0a 0a  own above.</p>..
08c0: 7d 0a 0a 23 23 23 23 23 23 23 23 23 23 23 23 23  }..#############
08d0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
08e0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
08f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
0900: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
0910: 23 0a 4d 45 54 48 4f 44 20 65 76 61 6c 20 7b 0a  #.METHOD eval {.
0920: 3c 70 3e 0a 54 68 65 20 6d 6f 73 74 20 75 73 65  <p>.The most use
0930: 66 75 6c 20 3c 69 3e 64 62 63 6d 64 3c 2f 69 3e  ful <i>dbcmd</i>
0940: 20 6d 65 74 68 6f 64 20 69 73 20 22 65 76 61 6c   method is "eval
0950: 22 2e 20 20 54 68 65 20 65 76 61 6c 20 6d 65 74  ".  The eval met
0960: 68 6f 64 20 69 73 20 75 73 65 64 0a 74 6f 20 65  hod is used.to e
0970: 78 65 63 75 74 65 20 53 51 4c 20 6f 6e 20 74 68  xecute SQL on th
0980: 65 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 65  e database.  The
0990: 20 73 79 6e 74 61 78 20 6f 66 20 74 68 65 20 65   syntax of the e
09a0: 76 61 6c 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73  val method looks
09b0: 0a 6c 69 6b 65 20 74 68 69 73 3a 3c 2f 70 3e 0a  .like this:</p>.
09c0: 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 69  .<blockquote>.<i
09d0: 3e 64 62 63 6d 64 3c 2f 69 3e 26 6e 62 73 70 3b  >dbcmd</i>&nbsp;
09e0: 26 6e 62 73 70 3b 3c 62 3e 65 76 61 6c 3c 2f 62  &nbsp;<b>eval</b
09f0: 3e 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 69 3e  >&nbsp;&nbsp;<i>
0a00: 73 71 6c 3c 2f 69 3e 0a 26 6e 62 73 70 3b 26 6e  sql</i>.&nbsp;&n
0a10: 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b  bsp;&nbsp;&nbsp;
0a20: 3f 3c 69 3e 61 72 72 61 79 2d 6e 61 6d 65 26 6e  ?<i>array-name&n
0a30: 62 73 70 3b 3c 2f 69 3e 3f 26 6e 62 73 70 3b 3f  bsp;</i>?&nbsp;?
0a40: 3c 69 3e 73 63 72 69 70 74 3c 2f 69 3e 3f 0a 3c  <i>script</i>?.<
0a50: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70  /blockquote>..<p
0a60: 3e 0a 54 68 65 20 6a 6f 62 20 6f 66 20 74 68 65  >.The job of the
0a70: 20 65 76 61 6c 20 6d 65 74 68 6f 64 20 69 73 20   eval method is 
0a80: 74 6f 20 65 78 65 63 75 74 65 20 74 68 65 20 53  to execute the S
0a90: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20  QL statement or 
0aa0: 73 74 61 74 65 6d 65 6e 74 73 0a 67 69 76 65 6e  statements.given
0ab0: 20 69 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 61   in the second a
0ac0: 72 67 75 6d 65 6e 74 2e 20 20 46 6f 72 20 65 78  rgument.  For ex
0ad0: 61 6d 70 6c 65 2c 20 74 6f 20 63 72 65 61 74 65  ample, to create
0ae0: 20 61 20 6e 65 77 20 74 61 62 6c 65 20 69 6e 0a   a new table in.
0af0: 61 20 64 61 74 61 62 61 73 65 2c 20 79 6f 75 20  a database, you 
0b00: 63 61 6e 20 64 6f 20 74 68 69 73 3a 3c 2f 70 3e  can do this:</p>
0b10: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c  ..<blockquote>.<
0b20: 62 3e 73 71 6c 69 74 65 33 20 64 62 31 20 2e 2f  b>sqlite3 db1 ./
0b30: 74 65 73 74 64 62 3c 62 72 3e 0a 64 62 31 20 65  testdb<br>.db1 e
0b40: 76 61 6c 20 7b 43 52 45 41 54 45 20 54 41 42 4c  val {CREATE TABL
0b50: 45 20 74 31 28 61 20 69 6e 74 2c 20 62 20 74 65  E t1(a int, b te
0b60: 78 74 29 7d 3c 2f 62 3e 0a 3c 2f 62 6c 6f 63 6b  xt)}</b>.</block
0b70: 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 20 61  quote>..<p>The a
0b80: 62 6f 76 65 20 63 6f 64 65 20 63 72 65 61 74 65  bove code create
0b90: 73 20 61 20 6e 65 77 20 74 61 62 6c 65 20 6e 61  s a new table na
0ba0: 6d 65 64 20 3c 62 3e 74 31 3c 2f 62 3e 20 77 69  med <b>t1</b> wi
0bb0: 74 68 20 63 6f 6c 75 6d 6e 73 0a 3c 62 3e 61 3c  th columns.<b>a<
0bc0: 2f 62 3e 20 61 6e 64 20 3c 62 3e 62 3c 2f 62 3e  /b> and <b>b</b>
0bd0: 2e 20 20 57 68 61 74 20 63 6f 75 6c 64 20 62 65  .  What could be
0be0: 20 73 69 6d 70 6c 65 72 3f 3c 2f 70 3e 0a 0a 3c   simpler?</p>..<
0bf0: 70 3e 51 75 65 72 79 20 72 65 73 75 6c 74 73 20  p>Query results 
0c00: 61 72 65 20 72 65 74 75 72 6e 65 64 20 61 73 20  are returned as 
0c10: 61 20 6c 69 73 74 20 6f 66 20 63 6f 6c 75 6d 6e  a list of column
0c20: 20 76 61 6c 75 65 73 2e 20 20 49 66 20 61 0a 71   values.  If a.q
0c30: 75 65 72 79 20 72 65 71 75 65 73 74 73 20 32 20  uery requests 2 
0c40: 63 6f 6c 75 6d 6e 73 20 61 6e 64 20 74 68 65 72  columns and ther
0c50: 65 20 61 72 65 20 33 20 72 6f 77 73 20 6d 61 74  e are 3 rows mat
0c60: 63 68 69 6e 67 20 74 68 65 20 71 75 65 72 79 2c  ching the query,
0c70: 0a 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e  .then the return
0c80: 65 64 20 6c 69 73 74 20 77 69 6c 6c 20 63 6f 6e  ed list will con
0c90: 74 61 69 6e 20 36 20 65 6c 65 6d 65 6e 74 73 2e  tain 6 elements.
0ca0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 3c 2f    For example:</
0cb0: 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  p>..<blockquote>
0cc0: 0a 3c 62 3e 64 62 31 20 65 76 61 6c 20 7b 49 4e  .<b>db1 eval {IN
0cd0: 53 45 52 54 20 49 4e 54 4f 20 74 31 20 56 41 4c  SERT INTO t1 VAL
0ce0: 55 45 53 28 31 2c 27 68 65 6c 6c 6f 27 29 7d 3c  UES(1,'hello')}<
0cf0: 62 72 3e 0a 64 62 31 20 65 76 61 6c 20 7b 49 4e  br>.db1 eval {IN
0d00: 53 45 52 54 20 49 4e 54 4f 20 74 31 20 56 41 4c  SERT INTO t1 VAL
0d10: 55 45 53 28 32 2c 27 67 6f 6f 64 62 79 65 27 29  UES(2,'goodbye')
0d20: 7d 3c 62 72 3e 0a 64 62 31 20 65 76 61 6c 20 7b  }<br>.db1 eval {
0d30: 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 31 20 56  INSERT INTO t1 V
0d40: 41 4c 55 45 53 28 33 2c 27 68 6f 77 64 79 21 27  ALUES(3,'howdy!'
0d50: 29 7d 3c 62 72 3e 0a 73 65 74 20 78 20 5b 64 62  )}<br>.set x [db
0d60: 31 20 65 76 61 6c 20 7b 53 45 4c 45 43 54 20 2a  1 eval {SELECT *
0d70: 20 46 52 4f 4d 20 74 31 20 4f 52 44 45 52 20 42   FROM t1 ORDER B
0d80: 59 20 61 7d 5d 3c 2f 62 3e 0a 3c 2f 62 6c 6f 63  Y a}]</b>.</bloc
0d90: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 20  kquote>..<p>The 
0da0: 76 61 72 69 61 62 6c 65 20 3c 62 3e 24 78 3c 2f  variable <b>$x</
0db0: 62 3e 20 69 73 20 73 65 74 20 62 79 20 74 68 65  b> is set by the
0dc0: 20 61 62 6f 76 65 20 63 6f 64 65 20 74 6f 3c 2f   above code to</
0dd0: 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  p>..<blockquote>
0de0: 0a 3c 62 3e 31 20 68 65 6c 6c 6f 20 32 20 67 6f  .<b>1 hello 2 go
0df0: 6f 64 62 79 65 20 33 20 68 6f 77 64 79 21 3c 2f  odbye 3 howdy!</
0e00: 62 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  b>.</blockquote>
0e10: 0a 0a 3c 70 3e 59 6f 75 20 63 61 6e 20 61 6c 73  ..<p>You can als
0e20: 6f 20 70 72 6f 63 65 73 73 20 74 68 65 20 72 65  o process the re
0e30: 73 75 6c 74 73 20 6f 66 20 61 20 71 75 65 72 79  sults of a query
0e40: 20 6f 6e 65 20 72 6f 77 20 61 74 20 61 20 74 69   one row at a ti
0e50: 6d 65 0a 62 79 20 73 70 65 63 69 66 79 69 6e 67  me.by specifying
0e60: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 20   the name of an 
0e70: 61 72 72 61 79 20 76 61 72 69 61 62 6c 65 20 61  array variable a
0e80: 6e 64 20 61 20 73 63 72 69 70 74 20 66 6f 6c 6c  nd a script foll
0e90: 6f 77 69 6e 67 0a 74 68 65 20 53 51 4c 20 63 6f  owing.the SQL co
0ea0: 64 65 2e 20 20 46 6f 72 20 65 61 63 68 20 72 6f  de.  For each ro
0eb0: 77 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 72  w of the query r
0ec0: 65 73 75 6c 74 2c 20 74 68 65 20 76 61 6c 75 65  esult, the value
0ed0: 73 20 6f 66 20 61 6c 6c 0a 63 6f 6c 75 6d 6e 73  s of all.columns
0ee0: 20 77 69 6c 6c 20 62 65 20 69 6e 73 65 72 74 65   will be inserte
0ef0: 64 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79  d into the array
0f00: 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 74 68   variable and th
0f10: 65 20 73 63 72 69 70 74 20 77 69 6c 6c 0a 62 65  e script will.be
0f20: 20 65 78 65 63 75 74 65 64 2e 20 20 46 6f 72 20   executed.  For 
0f30: 69 6e 73 74 61 6e 63 65 3a 3c 2f 70 3e 0a 0a 3c  instance:</p>..<
0f40: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 62 3e 64  blockquote>.<b>d
0f50: 62 31 20 65 76 61 6c 20 7b 53 45 4c 45 43 54 20  b1 eval {SELECT 
0f60: 2a 20 46 52 4f 4d 20 74 31 20 4f 52 44 45 52 20  * FROM t1 ORDER 
0f70: 42 59 20 61 7d 20 76 61 6c 75 65 73 20 7b 3c 62  BY a} values {<b
0f80: 72 3e 0a 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26  r>.&nbsp;&nbsp;&
0f90: 6e 62 73 70 3b 26 6e 62 73 70 3b 70 61 72 72 61  nbsp;&nbsp;parra
0fa0: 79 20 76 61 6c 75 65 73 3c 62 72 3e 0a 26 6e 62  y values<br>.&nb
0fb0: 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26  sp;&nbsp;&nbsp;&
0fc0: 6e 62 73 70 3b 70 75 74 73 20 22 22 3c 62 72 3e  nbsp;puts ""<br>
0fd0: 0a 7d 3c 2f 62 3e 0a 3c 2f 62 6c 6f 63 6b 71 75  .}</b>.</blockqu
0fe0: 6f 74 65 3e 0a 0a 3c 70 3e 54 68 69 73 20 6c 61  ote>..<p>This la
0ff0: 73 74 20 63 6f 64 65 20 77 69 6c 6c 20 67 69 76  st code will giv
1000: 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  e the following 
1010: 6f 75 74 70 75 74 3a 3c 2f 70 3e 0a 0a 3c 62 6c  output:</p>..<bl
1020: 6f 63 6b 71 75 6f 74 65 3e 3c 62 3e 0a 76 61 6c  ockquote><b>.val
1030: 75 65 73 28 2a 29 20 3d 20 61 20 62 3c 62 72 3e  ues(*) = a b<br>
1040: 0a 76 61 6c 75 65 73 28 61 29 20 3d 20 31 3c 62  .values(a) = 1<b
1050: 72 3e 0a 76 61 6c 75 65 73 28 62 29 20 3d 20 68  r>.values(b) = h
1060: 65 6c 6c 6f 3c 70 3e 0a 0a 76 61 6c 75 65 73 28  ello<p>..values(
1070: 2a 29 20 3d 20 61 20 62 3c 62 72 3e 0a 76 61 6c  *) = a b<br>.val
1080: 75 65 73 28 61 29 20 3d 20 32 3c 62 72 3e 0a 76  ues(a) = 2<br>.v
1090: 61 6c 75 65 73 28 62 29 20 3d 20 67 6f 6f 64 62  alues(b) = goodb
10a0: 79 65 3c 70 3e 0a 0a 76 61 6c 75 65 73 28 2a 29  ye<p>..values(*)
10b0: 20 3d 20 61 20 62 3c 62 72 3e 0a 76 61 6c 75 65   = a b<br>.value
10c0: 73 28 61 29 20 3d 20 33 3c 62 72 3e 0a 76 61 6c  s(a) = 3<br>.val
10d0: 75 65 73 28 62 29 20 3d 20 68 6f 77 64 79 21 3c  ues(b) = howdy!<
10e0: 2f 62 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  /b>.</blockquote
10f0: 3e 0a 0a 3c 70 3e 0a 46 6f 72 20 65 61 63 68 20  >..<p>.For each 
1100: 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 72 6f 77 20  column in a row 
1110: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2c 20 74  of the result, t
1120: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 61 74 20  he name of that 
1130: 63 6f 6c 75 6d 6e 0a 69 73 20 75 73 65 64 20 61  column.is used a
1140: 73 20 61 6e 20 69 6e 64 65 78 20 69 6e 20 74 6f  s an index in to
1150: 20 61 72 72 61 79 2e 20 20 54 68 65 20 76 61 6c   array.  The val
1160: 75 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ue of the column
1170: 20 69 73 20 73 74 6f 72 65 64 0a 69 6e 20 74 68   is stored.in th
1180: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
1190: 61 72 72 61 79 20 65 6e 74 72 79 2e 20 20 54 68  array entry.  Th
11a0: 65 20 73 70 65 63 69 61 6c 20 61 72 72 61 79 20  e special array 
11b0: 69 6e 64 65 78 20 2a 20 69 73 0a 75 73 65 64 20  index * is.used 
11c0: 74 6f 20 73 74 6f 72 65 20 61 20 6c 69 73 74 20  to store a list 
11d0: 6f 66 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20  of column names 
11e0: 69 6e 20 74 68 65 20 6f 72 64 65 72 20 74 68 61  in the order tha
11f0: 74 20 74 68 65 79 20 61 70 70 65 61 72 2e 0a 3c  t they appear..<
1200: 2f 70 3e 0a 0a 3c 70 3e 0a 49 66 20 74 68 65 20  /p>..<p>.If the 
1210: 61 72 72 61 79 20 76 61 72 69 61 62 6c 65 20 6e  array variable n
1220: 61 6d 65 20 69 73 20 6f 6d 69 74 74 65 64 20 6f  ame is omitted o
1230: 72 20 69 73 20 74 68 65 20 65 6d 70 74 79 20 73  r is the empty s
1240: 74 72 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  tring, then the 
1250: 76 61 6c 75 65 20 6f 66 0a 65 61 63 68 20 63 6f  value of.each co
1260: 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69  lumn is stored i
1270: 6e 20 61 20 76 61 72 69 61 62 6c 65 20 77 69 74  n a variable wit
1280: 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
1290: 61 73 20 74 68 65 20 63 6f 6c 75 6d 6e 0a 69 74  as the column.it
12a0: 73 65 6c 66 2e 20 20 46 6f 72 20 65 78 61 6d 70  self.  For examp
12b0: 6c 65 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b  le:.</p>..<block
12c0: 71 75 6f 74 65 3e 0a 3c 62 3e 64 62 31 20 65 76  quote>.<b>db1 ev
12d0: 61 6c 20 7b 53 45 4c 45 43 54 20 2a 20 46 52 4f  al {SELECT * FRO
12e0: 4d 20 74 31 20 4f 52 44 45 52 20 42 59 20 61 7d  M t1 ORDER BY a}
12f0: 20 7b 3c 62 72 3e 0a 26 6e 62 73 70 3b 26 6e 62   {<br>.&nbsp;&nb
1300: 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 70  sp;&nbsp;&nbsp;p
1310: 75 74 73 20 22 61 3d 24 61 20 62 3d 24 62 22 3c  uts "a=$a b=$b"<
1320: 62 72 3e 0a 7d 3c 2f 62 3e 0a 3c 2f 62 6c 6f 63  br>.}</b>.</bloc
1330: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 46 72 6f  kquote>..<p>.Fro
1340: 6d 20 74 68 69 73 20 77 65 20 67 65 74 20 74 68  m this we get th
1350: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6f 75 74 70  e following outp
1360: 75 74 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71  ut.</p>..<blockq
1370: 75 6f 74 65 3e 3c 62 3e 0a 61 3d 31 20 62 3d 68  uote><b>.a=1 b=h
1380: 65 6c 6c 6f 3c 62 72 3e 0a 61 3d 32 20 62 3d 67  ello<br>.a=2 b=g
1390: 6f 6f 64 62 79 65 3c 62 72 3e 0a 61 3d 33 20 62  oodbye<br>.a=3 b
13a0: 3d 68 6f 77 64 79 21 3c 2f 62 3e 0a 3c 2f 62 6c  =howdy!</b>.</bl
13b0: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 54  ockquote>..<p>.T
13c0: 63 6c 20 76 61 72 69 61 62 6c 65 20 6e 61 6d 65  cl variable name
13d0: 73 20 63 61 6e 20 61 70 70 65 61 72 20 69 6e 20  s can appear in 
13e0: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
13f0: 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
1400: 61 72 67 75 6d 65 6e 74 0a 69 6e 20 61 6e 79 20  argument.in any 
1410: 70 6f 73 69 74 69 6f 6e 20 77 68 65 72 65 20 69  position where i
1420: 74 20 69 73 20 6c 65 67 61 6c 20 74 6f 20 70 75  t is legal to pu
1430: 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 6e 75  t a string or nu
1440: 6d 62 65 72 20 6c 69 74 65 72 61 6c 2e 20 20 54  mber literal.  T
1450: 68 65 0a 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he.value of the 
1460: 76 61 72 69 61 62 6c 65 20 69 73 20 73 75 62 73  variable is subs
1470: 74 69 74 75 74 65 64 20 66 6f 72 20 74 68 65 20  tituted for the 
1480: 76 61 72 69 61 62 6c 65 20 6e 61 6d 65 2e 20 20  variable name.  
1490: 49 66 20 74 68 65 0a 76 61 72 69 61 62 6c 65 20  If the.variable 
14a0: 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 61  does not exist a
14b0: 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 69 73 20   NULL values is 
14c0: 75 73 65 64 2e 20 20 46 6f 72 20 65 78 61 6d 70  used.  For examp
14d0: 6c 65 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b  le:.</p>..<block
14e0: 71 75 6f 74 65 3e 3c 62 3e 0a 64 62 31 20 65 76  quote><b>.db1 ev
14f0: 61 6c 20 7b 49 4e 53 45 52 54 20 49 4e 54 4f 20  al {INSERT INTO 
1500: 74 31 20 56 41 4c 55 45 53 28 35 2c 24 62 69 67  t1 VALUES(5,$big
1510: 62 6c 6f 62 29 7d 0a 3c 2f 62 3e 3c 2f 62 6c 6f  blob)}.</b></blo
1520: 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 4e 6f  ckquote>..<p>.No
1530: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6e 6f  te that it is no
1540: 74 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 71  t necessary to q
1550: 75 6f 74 65 20 74 68 65 20 24 62 69 67 62 6c 6f  uote the $bigblo
1560: 62 20 76 61 6c 75 65 2e 20 20 54 68 61 74 20 68  b value.  That h
1570: 61 70 70 65 6e 73 0a 61 75 74 6f 6d 61 74 69 63  appens.automatic
1580: 61 6c 6c 79 2e 20 20 49 66 20 24 62 69 67 62 6c  ally.  If $bigbl
1590: 6f 62 20 69 73 20 61 20 6c 61 72 67 65 20 73 74  ob is a large st
15a0: 72 69 6e 67 20 6f 72 20 62 69 6e 61 72 79 20 6f  ring or binary o
15b0: 62 6a 65 63 74 2c 20 74 68 69 73 0a 74 65 63 68  bject, this.tech
15c0: 6e 69 71 75 65 20 69 73 20 6e 6f 74 20 6f 6e 6c  nique is not onl
15d0: 79 20 65 61 73 69 65 72 20 74 6f 20 77 72 69 74  y easier to writ
15e0: 65 2c 20 69 74 20 69 73 20 61 6c 73 6f 20 6d 75  e, it is also mu
15f0: 63 68 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e  ch more efficien
1600: 74 0a 73 69 6e 63 65 20 69 74 20 61 76 6f 69 64  t.since it avoid
1610: 73 20 6d 61 6b 69 6e 67 20 61 20 63 6f 70 79 20  s making a copy 
1620: 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
1630: 66 20 24 62 69 67 62 6c 6f 62 2e 0a 3c 2f 70 3e  f $bigblob..</p>
1640: 0a 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23 23 23  ..}..###########
1650: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1660: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1670: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1680: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1690: 23 23 23 0a 4d 45 54 48 4f 44 20 63 6c 6f 73 65  ###.METHOD close
16a0: 20 7b 0a 0a 3c 70 3e 0a 41 73 20 69 74 73 20 6e   {..<p>.As its n
16b0: 61 6d 65 20 73 75 67 67 65 73 74 73 2c 20 74 68  ame suggests, th
16c0: 65 20 22 63 6c 6f 73 65 22 20 6d 65 74 68 6f 64  e "close" method
16d0: 20 74 6f 20 61 6e 20 53 51 4c 69 74 65 20 64 61   to an SQLite da
16e0: 74 61 62 61 73 65 20 6a 75 73 74 0a 63 6c 6f 73  tabase just.clos
16f0: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  es the database.
1700: 20 20 54 68 69 73 20 68 61 73 20 74 68 65 20 73    This has the s
1710: 69 64 65 2d 65 66 66 65 63 74 20 6f 66 20 64 65  ide-effect of de
1720: 6c 65 74 69 6e 67 20 74 68 65 0a 3c 69 3e 64 62  leting the.<i>db
1730: 63 6d 64 3c 2f 69 3e 20 54 63 6c 20 63 6f 6d 6d  cmd</i> Tcl comm
1740: 61 6e 64 2e 20 20 48 65 72 65 20 69 73 20 61 6e  and.  Here is an
1750: 20 65 78 61 6d 70 6c 65 20 6f 66 20 6f 70 65 6e   example of open
1760: 69 6e 67 20 61 6e 64 20 74 68 65 6e 0a 69 6d 6d  ing and then.imm
1770: 65 64 69 61 74 65 6c 79 20 63 6c 6f 73 69 6e 67  ediately closing
1780: 20 61 20 64 61 74 61 62 61 73 65 3a 0a 3c 2f 70   a database:.</p
1790: 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  >..<blockquote>.
17a0: 3c 62 3e 73 71 6c 69 74 65 33 20 64 62 31 20 2e  <b>sqlite3 db1 .
17b0: 2f 74 65 73 74 64 62 3c 62 72 3e 0a 64 62 31 20  /testdb<br>.db1 
17c0: 63 6c 6f 73 65 3c 2f 62 3e 0a 3c 2f 62 6c 6f 63  close</b>.</bloc
17d0: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 49 66 20  kquote>..<p>.If 
17e0: 79 6f 75 20 64 65 6c 65 74 65 20 74 68 65 20 3c  you delete the <
17f0: 69 3e 64 62 63 6d 64 3c 2f 69 3e 20 64 69 72 65  i>dbcmd</i> dire
1800: 63 74 6c 79 2c 20 74 68 61 74 20 68 61 73 20 74  ctly, that has t
1810: 68 65 20 73 61 6d 65 20 65 66 66 65 63 74 0a 61  he same effect.a
1820: 73 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 22  s invoking the "
1830: 63 6c 6f 73 65 22 20 6d 65 74 68 6f 64 2e 20 20  close" method.  
1840: 53 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  So the following
1850: 20 63 6f 64 65 20 69 73 20 65 71 75 69 76 61 6c   code is equival
1860: 65 6e 74 0a 74 6f 20 74 68 65 20 70 72 65 76 69  ent.to the previ
1870: 6f 75 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b  ous:</p>..<block
1880: 71 75 6f 74 65 3e 0a 3c 62 3e 73 71 6c 69 74 65  quote>.<b>sqlite
1890: 33 20 64 62 31 20 2e 2f 74 65 73 74 64 62 3c 62  3 db1 ./testdb<b
18a0: 72 3e 0a 72 65 6e 61 6d 65 20 64 62 31 20 7b 7d  r>.rename db1 {}
18b0: 3c 2f 62 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74  </b>.</blockquot
18c0: 65 3e 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23 23  e>.}..##########
18d0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
18e0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
18f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1900: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1910: 23 23 23 23 0a 4d 45 54 48 4f 44 20 74 72 61 6e  ####.METHOD tran
1920: 73 61 63 74 69 6f 6e 20 7b 0a 0a 3c 70 3e 0a 54  saction {..<p>.T
1930: 68 65 20 22 74 72 61 6e 73 61 63 74 69 6f 6e 22  he "transaction"
1940: 20 6d 65 74 68 6f 64 20 69 73 20 75 73 65 64 20   method is used 
1950: 74 6f 20 65 78 65 63 75 74 65 20 61 20 54 43 4c  to execute a TCL
1960: 20 73 63 72 69 70 74 20 69 6e 73 69 64 65 20 61   script inside a
1970: 6e 20 53 51 4c 69 74 65 0a 64 61 74 61 62 61 73  n SQLite.databas
1980: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  e transaction.  
1990: 54 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  The transaction 
19a0: 69 73 20 63 6f 6d 6d 69 74 74 65 64 20 77 68 65  is committed whe
19b0: 6e 20 74 68 65 20 73 63 72 69 70 74 20 63 6f 6d  n the script com
19c0: 70 6c 65 74 65 73 2c 0a 6f 72 20 69 74 20 72 6f  pletes,.or it ro
19d0: 6c 6c 73 20 62 61 63 6b 20 69 66 20 74 68 65 20  lls back if the 
19e0: 73 63 72 69 70 74 20 66 61 69 6c 73 2e 20 20 49  script fails.  I
19f0: 66 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  f the transactio
1a00: 6e 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 0a  n occurs within.
1a10: 61 6e 6f 74 68 65 72 20 74 72 61 6e 73 61 63 74  another transact
1a20: 69 6f 6e 20 28 65 76 65 6e 20 6f 6e 65 20 74 68  ion (even one th
1a30: 61 74 20 69 73 20 73 74 61 72 74 65 64 20 6d 61  at is started ma
1a40: 6e 75 61 6c 6c 79 20 75 73 69 6e 67 20 42 45 47  nually using BEG
1a50: 49 4e 29 20 69 74 0a 69 73 20 61 20 6e 6f 2d 6f  IN) it.is a no-o
1a60: 70 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65  p..</p>..<p>.The
1a70: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d   transaction com
1a80: 6d 61 6e 64 20 63 61 6e 20 62 65 20 75 73 65 64  mand can be used
1a90: 20 74 6f 20 67 72 6f 75 70 20 74 6f 67 65 74 68   to group togeth
1aa0: 65 72 20 73 65 76 65 72 61 6c 20 53 51 4c 69 74  er several SQLit
1ab0: 65 0a 63 6f 6d 6d 61 6e 64 73 20 69 6e 20 61 20  e.commands in a 
1ac0: 73 61 66 65 20 77 61 79 2e 20 20 59 6f 75 20 63  safe way.  You c
1ad0: 61 6e 20 61 6c 77 61 79 73 20 73 74 61 72 74 20  an always start 
1ae0: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 6e  transactions man
1af0: 75 61 6c 6c 79 20 75 73 69 6e 67 0a 42 45 47 49  ually using.BEGI
1b00: 4e 2c 20 6f 66 0a 63 6f 75 72 73 65 2e 20 20 42  N, of.course.  B
1b10: 75 74 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  ut if an error o
1b20: 63 63 75 72 73 20 73 6f 20 74 68 61 74 20 74 68  ccurs so that th
1b30: 65 20 43 4f 4d 4d 49 54 20 6f 72 20 52 4f 4c 4c  e COMMIT or ROLL
1b40: 42 41 43 4b 20 61 72 65 20 6e 65 76 65 72 0a 72  BACK are never.r
1b50: 75 6e 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  un, then the dat
1b60: 61 62 61 73 65 20 77 69 6c 6c 20 72 65 6d 61 69  abase will remai
1b70: 6e 20 6c 6f 63 6b 65 64 20 69 6e 64 65 66 69 6e  n locked indefin
1b80: 69 74 65 6c 79 2e 20 20 41 6c 73 6f 2c 20 42 45  itely.  Also, BE
1b90: 47 49 4e 0a 64 6f 65 73 20 6e 6f 74 20 6e 65 73  GIN.does not nes
1ba0: 74 2c 20 73 6f 20 79 6f 75 20 68 61 76 65 20 74  t, so you have t
1bb0: 6f 20 6d 61 6b 65 20 73 75 72 65 20 6e 6f 20 6f  o make sure no o
1bc0: 74 68 65 72 20 74 72 61 6e 73 61 63 74 69 6f 6e  ther transaction
1bd0: 73 20 61 72 65 20 61 63 74 69 76 65 0a 62 65 66  s are active.bef
1be0: 6f 72 65 20 73 74 61 72 74 69 6e 67 20 61 20 6e  ore starting a n
1bf0: 65 77 20 6f 6e 65 2e 20 20 54 68 65 20 22 74 72  ew one.  The "tr
1c00: 61 6e 73 61 63 74 69 6f 6e 22 20 6d 65 74 68 6f  ansaction" metho
1c10: 64 20 74 61 6b 65 73 20 63 61 72 65 20 6f 66 0a  d takes care of.
1c20: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 64 65 74  all of these det
1c30: 61 69 6c 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  ails automatical
1c40: 6c 79 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68  ly..</p>..<p>.Th
1c50: 65 20 73 79 6e 74 61 78 20 6c 6f 6f 6b 73 20 6c  e syntax looks l
1c60: 69 6b 65 20 74 68 69 73 3a 0a 3c 2f 70 3e 0a 0a  ike this:.</p>..
1c70: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 69 3e  <blockquote>.<i>
1c80: 64 62 63 6d 64 3c 2f 69 3e 26 6e 62 73 70 3b 26  dbcmd</i>&nbsp;&
1c90: 6e 62 73 70 3b 3c 62 3e 74 72 61 6e 73 61 63 74  nbsp;<b>transact
1ca0: 69 6f 6e 3c 2f 62 3e 26 6e 62 73 70 3b 26 6e 62  ion</b>&nbsp;&nb
1cb0: 73 70 3b 3c 69 3e 3f 74 72 61 6e 73 61 63 74 69  sp;<i>?transacti
1cc0: 6f 6e 2d 74 79 70 65 3f 3c 2f 69 3e 0a 26 6e 62  on-type?</i>.&nb
1cd0: 73 70 3b 26 6e 62 73 70 3b 3c 69 3e 53 43 52 49  sp;&nbsp;<i>SCRI
1ce0: 50 54 2c 3c 2f 69 3e 0a 3c 2f 62 6c 6f 63 6b 71  PT,</i>.</blockq
1cf0: 75 6f 74 65 3e 0a 0a 0a 3c 70 3e 0a 54 68 65 20  uote>...<p>.The 
1d00: 3c 69 3e 74 72 61 6e 73 61 63 74 69 6f 6e 2d 74  <i>transaction-t
1d10: 79 70 65 3c 2f 69 3e 20 63 61 6e 20 62 65 20 6f  ype</i> can be o
1d20: 6e 65 20 6f 66 20 3c 62 3e 64 65 66 65 72 72 65  ne of <b>deferre
1d30: 64 3c 2f 62 3e 2c 0a 3c 62 3e 65 78 63 6c 75 73  d</b>,.<b>exclus
1d40: 69 76 65 3c 2f 62 3e 20 6f 72 20 3c 62 3e 69 6d  ive</b> or <b>im
1d50: 6d 65 64 69 61 74 65 3c 2f 62 3e 2e 20 20 54 68  mediate</b>.  Th
1d60: 65 20 64 65 66 61 75 6c 74 20 69 73 20 64 65 66  e default is def
1d70: 65 72 72 65 64 2e 0a 3c 2f 70 3e 0a 7d 0a 0a 23  erred..</p>.}..#
1d80: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1d90: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1da0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1db0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1dc0: 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 4d 45  #############.ME
1dd0: 54 48 4f 44 20 63 61 63 68 65 20 7b 0a 0a 3c 70  THOD cache {..<p
1de0: 3e 0a 54 68 65 20 22 65 76 61 6c 22 20 6d 65 74  >.The "eval" met
1df0: 68 6f 64 20 64 65 73 63 72 69 62 65 64 20 3c 61  hod described <a
1e00: 20 68 72 65 66 3d 22 23 65 76 61 6c 22 3e 61 62   href="#eval">ab
1e10: 6f 76 65 3c 2f 61 3e 20 6b 65 65 70 73 20 61 20  ove</a> keeps a 
1e20: 63 61 63 68 65 20 6f 66 0a 3c 61 20 68 72 65 66  cache of.<a href
1e30: 3d 22 63 61 70 69 33 72 65 66 2e 68 74 6d 6c 23  ="capi3ref.html#
1e40: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 22  sqlite3_prepare"
1e50: 3e 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  >prepared statem
1e60: 65 6e 74 73 3c 2f 61 3e 0a 66 6f 72 20 72 65 63  ents</a>.for rec
1e70: 65 6e 74 6c 79 20 65 76 61 6c 75 61 74 65 64 20  ently evaluated 
1e80: 53 51 4c 20 63 6f 6d 6d 61 6e 64 73 2e 20 20 0a  SQL commands.  .
1e90: 54 68 65 20 22 63 61 63 68 65 22 20 6d 65 74 68  The "cache" meth
1ea0: 6f 64 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  od is used to co
1eb0: 6e 74 72 6f 6c 20 74 68 69 73 20 63 61 63 68 65  ntrol this cache
1ec0: 2e 0a 54 68 65 20 66 69 72 73 74 20 66 6f 72 6d  ..The first form
1ed0: 20 6f 66 20 74 68 69 73 20 63 6f 6d 6d 61 6e 64   of this command
1ee0: 20 69 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b   is:</p>..<block
1ef0: 71 75 6f 74 65 3e 0a 3c 69 3e 64 62 63 6d 64 3c  quote>.<i>dbcmd<
1f00: 2f 69 3e 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c  /i>&nbsp;&nbsp;<
1f10: 62 3e 63 61 63 68 65 20 73 69 7a 65 3c 2f 62 3e  b>cache size</b>
1f20: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 69 3e 4e  &nbsp;&nbsp;<i>N
1f30: 3c 2f 69 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74  </i>.</blockquot
1f40: 65 3e 0a 0a 3c 70 3e 54 68 69 73 20 73 65 74 73  e>..<p>This sets
1f50: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
1f60: 62 65 72 20 6f 66 20 73 74 61 74 65 6d 65 6e 74  ber of statement
1f70: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 61  s that can be ca
1f80: 63 68 65 64 2e 0a 54 68 65 20 75 70 70 65 72 20  ched..The upper 
1f90: 6c 69 6d 69 74 20 69 73 20 31 30 30 2e 20 20 54  limit is 100.  T
1fa0: 68 65 20 64 65 66 61 75 6c 74 20 69 73 20 31 30  he default is 10
1fb0: 2e 20 20 49 66 20 79 6f 75 20 73 65 74 20 74 68  .  If you set th
1fc0: 65 20 63 61 63 68 65 20 73 69 7a 65 0a 74 6f 20  e cache size.to 
1fd0: 30 2c 20 6e 6f 20 63 61 63 68 69 6e 67 20 69 73  0, no caching is
1fe0: 20 64 6f 6e 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54   done.</p>..<p>T
1ff0: 68 65 20 73 65 63 6f 6e 64 20 66 6f 72 6d 20 6f  he second form o
2000: 66 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 69 73  f the command is
2010: 20 74 68 69 73 3a 3c 2f 70 3e 0a 0a 0a 3c 62 6c   this:</p>...<bl
2020: 6f 63 6b 71 75 6f 74 65 3e 0a 3c 69 3e 64 62 63  ockquote>.<i>dbc
2030: 6d 64 3c 2f 69 3e 26 6e 62 73 70 3b 26 6e 62 73  md</i>&nbsp;&nbs
2040: 70 3b 3c 62 3e 63 61 63 68 65 20 66 6c 75 73 68  p;<b>cache flush
2050: 3c 2f 62 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74  </b>.</blockquot
2060: 65 3e 0a 0a 3c 70 3e 54 68 65 20 63 61 63 68 65  e>..<p>The cache
2070: 2d 66 6c 75 73 68 20 6d 65 74 68 6f 64 20 0a 3c  -flush method .<
2080: 61 20 68 72 65 66 3d 22 63 61 70 69 33 72 65 66  a href="capi3ref
2090: 2e 68 74 6d 6c 23 73 71 6c 69 74 65 33 5f 66 69  .html#sqlite3_fi
20a0: 6e 61 6c 69 7a 65 22 3e 66 69 6e 61 6c 69 7a 65  nalize">finalize
20b0: 73 3c 2f 61 3e 0a 61 6c 6c 20 70 72 65 70 61 72  s</a>.all prepar
20c0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 63 75  ed statements cu
20d0: 72 72 65 6e 74 6c 79 0a 69 6e 20 74 68 65 20 63  rrently.in the c
20e0: 61 63 68 65 2e 3c 2f 70 3e 0a 0a 7d 0a 0a 23 23  ache.</p>..}..##
20f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2100: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2110: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2120: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2130: 23 23 23 23 23 23 23 23 23 23 23 23 0a 4d 45 54  ############.MET
2140: 48 4f 44 20 63 6f 6d 70 6c 65 74 65 20 7b 0a 0a  HOD complete {..
2150: 3c 70 3e 0a 54 68 65 20 22 63 6f 6d 70 6c 65 74  <p>.The "complet
2160: 65 22 20 6d 65 74 68 6f 64 20 74 61 6b 65 73 20  e" method takes 
2170: 61 20 73 74 72 69 6e 67 20 6f 66 20 73 75 70 70  a string of supp
2180: 6f 73 65 64 20 53 51 4c 20 61 73 20 69 74 73 20  osed SQL as its 
2190: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 0a 49  only argument..I
21a0: 74 20 72 65 74 75 72 6e 73 20 54 52 55 45 20 69  t returns TRUE i
21b0: 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 20  f the string is 
21c0: 61 20 63 6f 6d 70 6c 65 74 65 20 73 74 61 74 65  a complete state
21d0: 6d 65 6e 74 20 6f 66 20 53 51 4c 20 61 6e 64 20  ment of SQL and 
21e0: 46 41 4c 53 45 20 69 66 0a 74 68 65 72 65 20 69  FALSE if.there i
21f0: 73 20 6d 6f 72 65 20 74 6f 20 62 65 20 65 6e 74  s more to be ent
2200: 65 72 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68  ered.</p>..<p>Th
2210: 65 20 22 63 6f 6d 70 6c 65 74 65 22 20 6d 65 74  e "complete" met
2220: 68 6f 64 20 69 73 20 75 73 65 66 75 6c 20 77 68  hod is useful wh
2230: 65 6e 20 62 75 69 6c 64 69 6e 67 20 69 6e 74 65  en building inte
2240: 72 61 63 74 69 76 65 20 61 70 70 6c 69 63 61 74  ractive applicat
2250: 69 6f 6e 73 0a 69 6e 20 6f 72 64 65 72 20 74 6f  ions.in order to
2260: 20 6b 6e 6f 77 20 77 68 65 6e 20 74 68 65 20 75   know when the u
2270: 73 65 72 20 68 61 73 20 66 69 6e 69 73 68 65 64  ser has finished
2280: 20 65 6e 74 65 72 69 6e 67 20 61 20 6c 69 6e 65   entering a line
2290: 20 6f 66 20 53 51 4c 20 63 6f 64 65 2e 0a 54 68   of SQL code..Th
22a0: 69 73 20 69 73 20 72 65 61 6c 6c 79 20 6a 75 73  is is really jus
22b0: 74 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 74  t an interface t
22c0: 6f 20 74 68 65 20 0a 3c 61 20 68 72 65 66 3d 22  o the .<a href="
22d0: 63 61 70 69 33 72 65 66 2e 68 74 6d 6c 23 73 71  capi3ref.html#sq
22e0: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 22 3e  lite3_complete">
22f0: 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  <b>sqlite3_compl
2300: 65 74 65 28 29 3c 2f 62 3e 3c 2f 61 3e 20 43 0a  ete()</b></a> C.
2310: 66 75 6e 63 74 69 6f 6e 2e 0a 7d 0a 0a 23 23 23  function..}..###
2320: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2330: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2340: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2350: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2360: 23 23 23 23 23 23 23 23 23 23 23 0a 4d 45 54 48  ###########.METH
2370: 4f 44 20 63 6f 70 79 20 7b 0a 0a 3c 70 3e 0a 54  OD copy {..<p>.T
2380: 68 65 20 22 63 6f 70 79 22 20 6d 65 74 68 6f 64  he "copy" method
2390: 20 63 6f 70 69 65 73 20 64 61 74 61 20 66 72 6f   copies data fro
23a0: 6d 20 61 20 66 69 6c 65 20 69 6e 74 6f 20 61 20  m a file into a 
23b0: 74 61 62 6c 65 2e 0a 49 74 20 72 65 74 75 72 6e  table..It return
23c0: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
23d0: 72 6f 77 73 20 70 72 6f 63 65 73 73 65 64 20 73  rows processed s
23e0: 75 63 63 65 73 73 66 75 6c 6c 79 20 66 72 6f 6d  uccessfully from
23f0: 20 74 68 65 20 66 69 6c 65 2e 0a 54 68 65 20 73   the file..The s
2400: 79 6e 74 61 78 20 6f 66 20 74 68 65 20 63 6f 70  yntax of the cop
2410: 79 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73 20 6c  y method looks l
2420: 69 6b 65 20 74 68 69 73 3a 3c 2f 70 3e 0a 0a 3c  ike this:</p>..<
2430: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 69 3e 64  blockquote>.<i>d
2440: 62 63 6d 64 3c 2f 69 3e 26 6e 62 73 70 3b 26 6e  bcmd</i>&nbsp;&n
2450: 62 73 70 3b 3c 62 3e 63 6f 70 79 3c 2f 62 3e 26  bsp;<b>copy</b>&
2460: 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 69 3e 63 6f  nbsp;&nbsp;<i>co
2470: 6e 66 6c 69 63 74 2d 61 6c 67 6f 72 69 74 68 6d  nflict-algorithm
2480: 3c 2f 69 3e 0a 26 6e 62 73 70 3b 26 6e 62 73 70  </i>.&nbsp;&nbsp
2490: 3b 3c 69 3e 74 61 62 6c 65 2d 6e 61 6d 65 26 6e  ;<i>table-name&n
24a0: 62 73 70 3b 3c 2f 69 3e 26 6e 62 73 70 3b 26 6e  bsp;</i>&nbsp;&n
24b0: 62 73 70 3b 3c 69 3e 66 69 6c 65 2d 6e 61 6d 65  bsp;<i>file-name
24c0: 26 6e 62 73 70 3b 3c 2f 69 3e 0a 26 6e 62 73 70  &nbsp;</i>.&nbsp
24d0: 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62  ;&nbsp;&nbsp;&nb
24e0: 73 70 3b 3f 3c 69 3e 63 6f 6c 75 6d 6e 2d 73 65  sp;?<i>column-se
24f0: 70 61 72 61 74 6f 72 26 6e 62 73 70 3b 3c 2f 69  parator&nbsp;</i
2500: 3e 3f 0a 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3f  >?.&nbsp;&nbsp;?
2510: 3c 69 3e 6e 75 6c 6c 2d 69 6e 64 69 63 61 74 6f  <i>null-indicato
2520: 72 3c 2f 69 3e 3f 0a 3c 2f 62 6c 6f 63 6b 71 75  r</i>?.</blockqu
2530: 6f 74 65 3e 0a 0a 3c 70 3e 43 6f 6e 66 6c 69 63  ote>..<p>Conflic
2540: 74 2d 61 6c 6f 67 72 69 74 68 6d 20 6d 75 73 74  t-alogrithm must
2550: 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 53   be one of the S
2560: 51 4c 69 74 65 20 63 6f 6e 66 6c 69 63 74 20 61  QLite conflict a
2570: 6c 67 6f 72 69 74 68 6d 73 20 66 6f 72 0a 74 68  lgorithms for.th
2580: 65 20 49 4e 53 45 52 54 20 73 74 61 74 65 6d 65  e INSERT stateme
2590: 6e 74 3a 20 3c 69 3e 72 6f 6c 6c 62 61 63 6b 3c  nt: <i>rollback<
25a0: 2f 69 3e 2c 20 3c 69 3e 61 62 6f 72 74 3c 2f 69  /i>, <i>abort</i
25b0: 3e 2c 0a 3c 69 3e 66 61 69 6c 3c 2f 69 3e 2c 3c  >,.<i>fail</i>,<
25c0: 69 3e 69 67 6e 6f 72 65 3c 2f 69 3e 2c 20 6f 72  i>ignore</i>, or
25d0: 20 3c 69 3e 72 65 70 6c 61 63 65 3c 2f 69 3e 2e   <i>replace</i>.
25e0: 20 53 65 65 20 74 68 65 20 53 51 4c 69 74 65 20   See the SQLite 
25f0: 4c 61 6e 67 75 61 67 65 0a 73 65 63 74 69 6f 6e  Language.section
2600: 20 66 6f 72 20 3c 61 20 68 72 65 66 3d 22 6c 61   for <a href="la
2610: 6e 67 2e 68 74 6d 6c 23 63 6f 6e 66 6c 69 63 74  ng.html#conflict
2620: 22 3e 4f 4e 20 43 4f 4e 46 4c 49 43 54 3c 2f 61  ">ON CONFLICT</a
2630: 3e 20 66 6f 72 20 6d 6f 72 65 20 69 6e 66 6f 72  > for more infor
2640: 6d 61 74 69 6f 6e 2e 0a 54 68 65 20 63 6f 6e 66  mation..The conf
2650: 6c 69 63 74 2d 61 6c 67 6f 72 69 74 68 6d 20 6d  lict-algorithm m
2660: 75 73 74 20 62 65 20 73 70 65 63 69 66 69 65 64  ust be specified
2670: 20 69 6e 20 6c 6f 77 65 72 20 63 61 73 65 2e 0a   in lower case..
2680: 3c 2f 70 3e 0a 0a 3c 70 3e 54 61 62 6c 65 2d 6e  </p>..<p>Table-n
2690: 61 6d 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ame must already
26a0: 20 65 78 69 73 74 73 20 61 73 20 61 20 74 61 62   exists as a tab
26b0: 6c 65 2e 20 20 46 69 6c 65 2d 6e 61 6d 65 20 6d  le.  File-name m
26c0: 75 73 74 20 65 78 69 73 74 2c 20 61 6e 64 0a 65  ust exist, and.e
26d0: 61 63 68 20 72 6f 77 20 6d 75 73 74 20 63 6f 6e  ach row must con
26e0: 74 61 69 6e 20 74 68 65 20 73 61 6d 65 20 6e 75  tain the same nu
26f0: 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2700: 61 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68  as defined in th
2710: 65 20 74 61 62 6c 65 2e 0a 49 66 20 61 20 6c 69  e table..If a li
2720: 6e 65 20 69 6e 20 74 68 65 20 66 69 6c 65 20 63  ne in the file c
2730: 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20 6f 72 20  ontains more or 
2740: 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 6e 75  less than the nu
2750: 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2760: 64 65 66 69 6e 65 64 2c 0a 74 68 65 20 63 6f 70  defined,.the cop
2770: 79 20 6d 65 74 68 6f 64 20 72 6f 6c 6c 62 61 63  y method rollbac
2780: 6b 73 20 61 6e 79 20 69 6e 73 65 72 74 73 2c 20  ks any inserts, 
2790: 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65  and returns an e
27a0: 72 72 6f 72 2e 3c 2f 70 3e 0a 0a 3c 70 3e 43 6f  rror.</p>..<p>Co
27b0: 6c 75 6d 6e 2d 73 65 70 61 72 61 74 6f 72 20 69  lumn-separator i
27c0: 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63 6f  s an optional co
27d0: 6c 75 6d 6e 20 73 65 70 61 72 61 74 6f 72 20 73  lumn separator s
27e0: 74 72 69 6e 67 2e 20 20 54 68 65 20 64 65 66 61  tring.  The defa
27f0: 75 6c 74 20 69 73 0a 74 68 65 20 41 53 43 49 49  ult is.the ASCII
2800: 20 74 61 62 20 63 68 61 72 61 63 74 65 72 20 5c   tab character \
2810: 74 2e 20 3c 2f 70 3e 0a 0a 3c 70 3e 4e 75 6c 6c  t. </p>..<p>Null
2820: 2d 69 6e 64 69 63 61 74 6f 72 20 69 73 20 61 6e  -indicator is an
2830: 20 6f 70 74 69 6f 6e 61 6c 20 73 74 72 69 6e 67   optional string
2840: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
2850: 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 20 69  a column value i
2860: 73 20 6e 75 6c 6c 2e 0a 54 68 65 20 64 65 66 61  s null..The defa
2870: 75 6c 74 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ult is an empty 
2880: 73 74 72 69 6e 67 2e 20 20 4e 6f 74 65 20 74 68  string.  Note th
2890: 61 74 20 63 6f 6c 75 6d 6e 2d 73 65 70 61 72 61  at column-separa
28a0: 74 6f 72 20 61 6e 64 0a 6e 75 6c 6c 2d 69 6e 64  tor and.null-ind
28b0: 69 63 61 74 6f 72 20 61 72 65 20 6f 70 74 69 6f  icator are optio
28c0: 6e 61 6c 20 70 6f 73 69 74 69 6f 6e 61 6c 20 61  nal positional a
28d0: 72 67 75 6d 65 6e 74 73 3b 20 69 66 20 6e 75 6c  rguments; if nul
28e0: 6c 2d 69 6e 64 69 63 61 74 6f 72 0a 69 73 20 73  l-indicator.is s
28f0: 70 65 63 69 66 69 65 64 2c 20 61 20 63 6f 6c 75  pecified, a colu
2900: 6d 6e 2d 73 65 70 61 72 61 74 6f 72 20 61 72 67  mn-separator arg
2910: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 73 70  ument must be sp
2920: 65 63 69 66 65 64 20 61 6e 64 0a 70 72 65 63 65  ecifed and.prece
2930: 64 65 20 74 68 65 20 6e 75 6c 6c 2d 69 6e 64 69  de the null-indi
2940: 63 61 74 6f 72 20 61 72 67 75 6d 65 6e 74 2e 3c  cator argument.<
2950: 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 63 6f 70 79  /p>..<p>The copy
2960: 20 6d 65 74 68 6f 64 20 69 6d 70 6c 65 6d 65 6e   method implemen
2970: 74 73 20 73 69 6d 69 6c 61 72 20 66 75 6e 63 74  ts similar funct
2980: 69 6f 6e 61 6c 69 74 79 20 74 6f 20 74 68 65 20  ionality to the 
2990: 3c 62 3e 2e 69 6d 70 6f 72 74 3c 2f 62 3e 0a 53  <b>.import</b>.S
29a0: 51 4c 69 74 65 20 73 68 65 6c 6c 20 63 6f 6d 6d  QLite shell comm
29b0: 61 6e 64 2e 20 0a 54 68 65 20 53 51 4c 69 74 65  and. .The SQLite
29c0: 20 32 2e 78 20 3c 61 20 68 72 65 66 3d 22 6c 61   2.x <a href="la
29d0: 6e 67 2e 68 74 6d 6c 23 63 6f 70 79 22 3e 3c 62  ng.html#copy"><b
29e0: 3e 43 4f 50 59 3c 2f 62 3e 3c 2f 61 3e 20 73 74  >COPY</b></a> st
29f0: 61 74 65 6d 65 6e 74 20 0a 28 75 73 69 6e 67 20  atement .(using 
2a00: 74 68 65 20 50 6f 73 74 67 72 65 53 51 4c 20 43  the PostgreSQL C
2a10: 4f 50 59 20 66 69 6c 65 20 66 6f 72 6d 61 74 29  OPY file format)
2a20: 0a 63 61 6e 20 62 65 20 69 6d 70 6c 65 6d 65 6e  .can be implemen
2a30: 74 65 64 20 77 69 74 68 20 74 68 69 73 20 6d 65  ted with this me
2a40: 74 68 6f 64 20 61 73 3a 3c 2f 70 3e 0a 0a 3c 62  thod as:</p>..<b
2a50: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 64 62 63 6d 64  lockquote>.dbcmd
2a60: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 63 6f 70 79  &nbsp;&nbsp;copy
2a70: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 24 63 6f 6e  &nbsp;&nbsp;$con
2a80: 66 6c 69 63 74 61 6c 67 6f 0a 26 6e 62 73 70 3b  flictalgo.&nbsp;
2a90: 26 6e 62 73 70 3b 24 74 61 62 6c 65 6e 61 6d 65  &nbsp;$tablename
2aa0: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73  &nbsp;&nbsp;&nbs
2ab0: 70 3b 24 66 69 6c 65 6e 61 6d 65 26 6e 62 73 70  p;$filename&nbsp
2ac0: 3b 0a 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  ;.&nbsp;&nbsp;&n
2ad0: 62 73 70 3b 26 6e 62 73 70 3b 5c 74 26 6e 62 73  bsp;&nbsp;\t&nbs
2ae0: 70 3b 0a 26 6e 62 73 70 3b 26 6e 62 73 70 3b 5c  p;.&nbsp;&nbsp;\
2af0: 5c 4e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  \N.</blockquote>
2b00: 0a 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23 23 23  ..}..###########
2b10: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2b20: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2b30: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2b40: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2b50: 23 23 23 0a 4d 45 54 48 4f 44 20 74 69 6d 65 6f  ###.METHOD timeo
2b60: 75 74 20 7b 0a 0a 3c 70 3e 54 68 65 20 22 74 69  ut {..<p>The "ti
2b70: 6d 65 6f 75 74 22 20 6d 65 74 68 6f 64 20 69 73  meout" method is
2b80: 20 75 73 65 64 20 74 6f 20 63 6f 6e 74 72 6f 6c   used to control
2b90: 20 68 6f 77 20 6c 6f 6e 67 20 74 68 65 20 53 51   how long the SQ
2ba0: 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 77 69 6c  Lite library.wil
2bb0: 6c 20 77 61 69 74 20 66 6f 72 20 6c 6f 63 6b 73  l wait for locks
2bc0: 20 74 6f 20 63 6c 65 61 72 20 62 65 66 6f 72 65   to clear before
2bd0: 20 67 69 76 69 6e 67 20 75 70 20 6f 6e 20 61 20   giving up on a 
2be0: 64 61 74 61 62 61 73 65 20 74 72 61 6e 73 61 63  database transac
2bf0: 74 69 6f 6e 2e 0a 54 68 65 20 64 65 66 61 75 6c  tion..The defaul
2c00: 74 20 74 69 6d 65 6f 75 74 20 69 73 20 30 20 6d  t timeout is 0 m
2c10: 69 6c 6c 69 73 65 63 6f 6e 64 2e 20 20 28 49 6e  illisecond.  (In
2c20: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2c30: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  e default behavi
2c40: 6f 72 0a 69 73 20 6e 6f 74 20 74 6f 20 77 61 69  or.is not to wai
2c50: 74 20 61 74 20 61 6c 6c 2e 29 3c 2f 70 3e 0a 0a  t at all.)</p>..
2c60: 3c 70 3e 54 68 65 20 53 51 4c 69 74 65 20 64 61  <p>The SQLite da
2c70: 74 61 62 61 73 65 20 61 6c 6c 6f 77 73 20 6d 75  tabase allows mu
2c80: 6c 74 69 70 6c 65 20 73 69 6d 75 6c 74 61 6e 65  ltiple simultane
2c90: 6f 75 73 0a 72 65 61 64 65 72 73 20 6f 72 20 61  ous.readers or a
2ca0: 20 73 69 6e 67 6c 65 20 77 72 69 74 65 72 20 62   single writer b
2cb0: 75 74 20 6e 6f 74 20 62 6f 74 68 2e 20 20 49 66  ut not both.  If
2cc0: 20 61 6e 79 20 70 72 6f 63 65 73 73 20 69 73 20   any process is 
2cd0: 77 72 69 74 69 6e 67 20 74 6f 0a 74 68 65 20 64  writing to.the d
2ce0: 61 74 61 62 61 73 65 20 6e 6f 20 6f 74 68 65 72  atabase no other
2cf0: 20 70 72 6f 63 65 73 73 20 69 73 20 61 6c 6c 6f   process is allo
2d00: 77 73 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72  ws to read or wr
2d10: 69 74 65 2e 20 20 49 66 20 61 6e 79 20 70 72 6f  ite.  If any pro
2d20: 63 65 73 73 0a 69 73 20 72 65 61 64 69 6e 67 20  cess.is reading 
2d30: 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 74 68  the database oth
2d40: 65 72 20 70 72 6f 63 65 73 73 65 73 20 61 72 65  er processes are
2d50: 20 61 6c 6c 6f 77 65 64 20 74 6f 20 72 65 61 64   allowed to read
2d60: 20 62 75 74 20 6e 6f 74 20 77 72 69 74 65 2e 0a   but not write..
2d70: 54 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  The entire datab
2d80: 61 73 65 20 73 68 61 72 65 64 20 61 20 73 69 6e  ase shared a sin
2d90: 67 6c 65 20 6c 6f 63 6b 2e 3c 2f 70 3e 0a 0a 3c  gle lock.</p>..<
2da0: 70 3e 57 68 65 6e 20 53 51 4c 69 74 65 20 74 72  p>When SQLite tr
2db0: 69 65 73 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ies to open a da
2dc0: 74 61 62 61 73 65 20 61 6e 64 20 66 69 6e 64 73  tabase and finds
2dd0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 6f 63 6b   that it is lock
2de0: 65 64 2c 20 69 74 0a 63 61 6e 20 6f 70 74 69 6f  ed, it.can optio
2df0: 6e 61 6c 6c 79 20 64 65 6c 61 79 20 66 6f 72 20  nally delay for 
2e00: 61 20 73 68 6f 72 74 20 77 68 69 6c 65 20 61 6e  a short while an
2e10: 64 20 74 72 79 20 74 6f 20 6f 70 65 6e 20 74 68  d try to open th
2e20: 65 20 66 69 6c 65 20 61 67 61 69 6e 2e 0a 54 68  e file again..Th
2e30: 69 73 20 70 72 6f 63 65 73 73 20 72 65 70 65 61  is process repea
2e40: 74 73 20 75 6e 74 69 6c 20 74 68 65 20 71 75 65  ts until the que
2e50: 72 79 20 74 69 6d 65 73 20 6f 75 74 20 61 6e 64  ry times out and
2e60: 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
2e70: 61 0a 66 61 69 6c 75 72 65 2e 20 20 54 68 65 20  a.failure.  The 
2e80: 74 69 6d 65 6f 75 74 20 69 73 20 61 64 6a 75 73  timeout is adjus
2e90: 74 61 62 6c 65 2e 20 20 49 74 20 69 73 20 73 65  table.  It is se
2ea0: 74 20 74 6f 20 30 20 62 79 20 64 65 66 61 75 6c  t to 0 by defaul
2eb0: 74 20 73 6f 20 74 68 61 74 0a 69 66 20 74 68 65  t so that.if the
2ec0: 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63   database is loc
2ed0: 6b 65 64 2c 20 74 68 65 20 53 51 4c 20 73 74 61  ked, the SQL sta
2ee0: 74 65 6d 65 6e 74 20 66 61 69 6c 73 20 69 6d 6d  tement fails imm
2ef0: 65 64 69 61 74 65 6c 79 2e 20 20 42 75 74 20 79  ediately.  But y
2f00: 6f 75 0a 63 61 6e 20 75 73 65 20 74 68 65 20 22  ou.can use the "
2f10: 74 69 6d 65 6f 75 74 22 20 6d 65 74 68 6f 64 20  timeout" method 
2f20: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 74 69  to change the ti
2f30: 6d 65 6f 75 74 20 76 61 6c 75 65 20 74 6f 20 61  meout value to a
2f40: 20 70 6f 73 69 74 69 76 65 0a 6e 75 6d 62 65 72   positive.number
2f50: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 3c  .  For example:<
2f60: 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  /p>..<blockquote
2f70: 3e 3c 62 3e 64 62 31 20 74 69 6d 65 6f 75 74 20  ><b>db1 timeout 
2f80: 32 30 30 30 3c 2f 62 3e 3c 2f 62 6c 6f 63 6b 71  2000</b></blockq
2f90: 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 20 61 72  uote>..<p>The ar
2fa0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 69  gument to the ti
2fb0: 6d 65 6f 75 74 20 6d 65 74 68 6f 64 20 69 73 20  meout method is 
2fc0: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
2fd0: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
2fe0: 64 73 0a 74 6f 20 77 61 69 74 20 66 6f 72 20 74  ds.to wait for t
2ff0: 68 65 20 6c 6f 63 6b 20 74 6f 20 63 6c 65 61 72  he lock to clear
3000: 2e 20 20 53 6f 20 69 6e 20 74 68 65 20 65 78 61  .  So in the exa
3010: 6d 70 6c 65 20 61 62 6f 76 65 2c 20 74 68 65 20  mple above, the 
3020: 6d 61 78 69 6d 75 6d 20 64 65 6c 61 79 0a 77 6f  maximum delay.wo
3030: 75 6c 64 20 62 65 20 32 20 73 65 63 6f 6e 64 73  uld be 2 seconds
3040: 2e 3c 2f 70 3e 0a 7d 0a 0a 23 23 23 23 23 23 23  .</p>.}..#######
3050: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3060: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3070: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3080: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3090: 23 23 23 23 23 23 23 0a 4d 45 54 48 4f 44 20 62  #######.METHOD b
30a0: 75 73 79 20 7b 0a 0a 3c 70 3e 54 68 65 20 22 62  usy {..<p>The "b
30b0: 75 73 79 22 20 6d 65 74 68 6f 64 2c 20 6c 69 6b  usy" method, lik
30c0: 65 20 22 74 69 6d 65 6f 75 74 22 2c 20 6f 6e 6c  e "timeout", onl
30d0: 79 20 63 6f 6d 65 73 20 69 6e 74 6f 20 70 6c 61  y comes into pla
30e0: 79 20 77 68 65 6e 20 74 68 65 0a 64 61 74 61 62  y when the.datab
30f0: 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ase is locked.  
3100: 42 75 74 20 74 68 65 20 22 62 75 73 79 22 20 6d  But the "busy" m
3110: 65 74 68 6f 64 20 67 69 76 65 73 20 74 68 65 20  ethod gives the 
3120: 70 72 6f 67 72 61 6d 6d 65 72 20 6d 75 63 68 20  programmer much 
3130: 6d 6f 72 65 0a 63 6f 6e 74 72 6f 6c 20 6f 76 65  more.control ove
3140: 72 20 77 68 61 74 20 61 63 74 69 6f 6e 20 74 6f  r what action to
3150: 20 74 61 6b 65 2e 20 20 54 68 65 20 22 62 75 73   take.  The "bus
3160: 79 22 20 6d 65 74 68 6f 64 20 73 70 65 63 69 66  y" method specif
3170: 69 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 54  ies a callback.T
3180: 63 6c 20 70 72 6f 63 65 64 75 72 65 20 74 68 61  cl procedure tha
3190: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  t is invoked whe
31a0: 6e 65 76 65 72 20 53 51 4c 69 74 65 20 74 72 69  never SQLite tri
31b0: 65 73 20 74 6f 20 6f 70 65 6e 20 61 20 6c 6f 63  es to open a loc
31c0: 6b 65 64 0a 64 61 74 61 62 61 73 65 2e 20 20 54  ked.database.  T
31d0: 68 69 73 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e  his callback can
31e0: 20 64 6f 20 77 68 61 74 65 76 65 72 20 69 73 20   do whatever is 
31f0: 64 65 73 69 72 65 64 2e 20 20 50 72 65 73 75 6d  desired.  Presum
3200: 61 62 6c 79 2c 20 74 68 65 0a 63 61 6c 6c 62 61  ably, the.callba
3210: 63 6b 20 77 69 6c 6c 20 64 6f 20 73 6f 6d 65 20  ck will do some 
3220: 6f 74 68 65 72 20 75 73 65 66 75 6c 20 77 6f 72  other useful wor
3230: 6b 20 66 6f 72 20 61 20 73 68 6f 72 74 20 77 68  k for a short wh
3240: 69 6c 65 20 28 73 75 63 68 20 61 73 20 73 65 72  ile (such as ser
3250: 76 69 63 65 0a 47 55 49 20 65 76 65 6e 74 73 29  vice.GUI events)
3260: 20 74 68 65 6e 20 72 65 74 75 72 6e 0a 73 6f 20   then return.so 
3270: 74 68 61 74 20 74 68 65 20 6c 6f 63 6b 20 63 61  that the lock ca
3280: 6e 20 62 65 20 74 72 69 65 64 20 61 67 61 69 6e  n be tried again
3290: 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  .  The callback 
32a0: 70 72 6f 63 65 64 75 72 65 20 73 68 6f 75 6c 64  procedure should
32b0: 0a 72 65 74 75 72 6e 20 22 30 22 20 69 66 20 69  .return "0" if i
32c0: 74 20 77 61 6e 74 73 20 53 51 4c 69 74 65 20 74  t wants SQLite t
32d0: 6f 20 74 72 79 20 61 67 61 69 6e 20 74 6f 20 6f  o try again to o
32e0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
32f0: 20 61 6e 64 0a 73 68 6f 75 6c 64 20 72 65 74 75   and.should retu
3300: 72 6e 20 22 31 22 20 69 66 20 69 74 20 77 61 6e  rn "1" if it wan
3310: 74 73 20 53 51 4c 69 74 65 20 74 6f 20 61 62 61  ts SQLite to aba
3320: 6e 64 6f 6e 20 74 68 65 20 63 75 72 72 65 6e 74  ndon the current
3330: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 7d 0a 0a 23   operation..}..#
3340: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3350: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3360: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3370: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3380: 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 4d 45  #############.ME
3390: 54 48 4f 44 20 65 78 69 73 74 73 20 7b 0a 0a 3c  THOD exists {..<
33a0: 70 3e 54 68 65 20 22 65 78 69 73 74 73 22 20 6d  p>The "exists" m
33b0: 65 74 68 6f 64 20 69 73 20 73 69 6d 69 6c 61 72  ethod is similar
33c0: 20 74 6f 20 22 6f 6e 65 63 6f 6c 75 6d 6e 22 20   to "onecolumn" 
33d0: 61 6e 64 20 22 65 76 61 6c 22 20 69 6e 20 74 68  and "eval" in th
33e0: 61 74 0a 69 74 20 65 78 65 63 75 74 65 73 20 53  at.it executes S
33f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3400: 54 68 65 20 64 69 66 66 65 72 65 6e 63 65 20 69  The difference i
3410: 73 20 74 68 61 74 20 74 68 65 20 22 65 78 69 73  s that the "exis
3420: 74 73 22 20 6d 65 74 68 6f 64 0a 61 6c 77 61 79  ts" method.alway
3430: 73 20 72 65 74 75 72 6e 73 20 61 20 62 6f 6f 6c  s returns a bool
3440: 65 61 6e 20 76 61 6c 75 65 20 77 68 69 63 68 20  ean value which 
3450: 69 73 20 54 52 55 45 20 69 66 20 61 20 71 75 65  is TRUE if a que
3460: 72 79 20 69 6e 20 74 68 65 20 53 51 4c 0a 73 74  ry in the SQL.st
3470: 61 74 65 6d 65 6e 74 20 69 74 20 65 78 65 63 75  atement it execu
3480: 74 65 73 20 72 65 74 75 72 6e 73 20 6f 6e 65 20  tes returns one 
3490: 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 61 6e 64  or more rows and
34a0: 20 46 41 4c 53 45 20 69 66 20 74 68 65 20 53 51   FALSE if the SQ
34b0: 4c 0a 72 65 74 75 72 6e 73 20 61 6e 20 65 6d 70  L.returns an emp
34c0: 74 79 20 73 65 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e  ty set.</p>..<p>
34d0: 54 68 65 20 22 65 78 69 73 74 73 22 20 6d 65 74  The "exists" met
34e0: 68 6f 64 20 69 73 20 6f 66 74 65 6e 20 75 73 65  hod is often use
34f0: 64 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  d to test for th
3500: 65 20 65 78 69 73 74 61 6e 63 65 20 6f 66 0a 72  e existance of.r
3510: 6f 77 73 20 69 6e 20 61 20 74 61 62 6c 65 2e 20  ows in a table. 
3520: 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 3c 2f 70   For example:</p
3530: 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  >..<blockquote><
3540: 62 3e 0a 69 66 20 7b 5b 64 62 20 65 78 69 73 74  b>.if {[db exist
3550: 73 20 7b 53 45 4c 45 43 54 20 31 20 46 52 4f 4d  s {SELECT 1 FROM
3560: 20 74 61 62 6c 65 31 20 57 48 45 52 45 20 75 73   table1 WHERE us
3570: 65 72 3d 24 75 73 65 72 7d 5d 7d 20 7b 3c 62 72  er=$user}]} {<br
3580: 3e 0a 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  >.&nbsp;&nbsp;&n
3590: 62 73 70 3b 23 20 50 72 6f 63 65 73 73 69 6e 67  bsp;# Processing
35a0: 20 69 66 20 24 75 73 65 72 20 65 78 69 73 74 73   if $user exists
35b0: 3c 62 72 3e 0a 7d 20 65 6c 73 65 20 7b 3c 62 72  <br>.} else {<br
35c0: 3e 0a 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  >.&nbsp;&nbsp;&n
35d0: 62 73 70 3b 23 20 50 72 6f 63 65 73 73 69 6e 67  bsp;# Processing
35e0: 20 69 66 20 24 75 73 65 72 20 64 6f 65 73 20 6e   if $user does n
35f0: 6f 74 20 65 78 69 73 74 3c 62 72 3e 0a 7d 0a 3c  ot exist<br>.}.<
3600: 2f 62 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  /b></blockquote>
3610: 0a 7d 0a 0a 0a 23 23 23 23 23 23 23 23 23 23 23  .}...###########
3620: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3630: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3640: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3650: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3660: 23 23 23 0a 4d 45 54 48 4f 44 20 6c 61 73 74 5f  ###.METHOD last_
3670: 69 6e 73 65 72 74 5f 72 6f 77 69 64 20 7b 0a 0a  insert_rowid {..
3680: 3c 70 3e 54 68 65 20 22 6c 61 73 74 5f 69 6e 73  <p>The "last_ins
3690: 65 72 74 5f 72 6f 77 69 64 22 20 6d 65 74 68 6f  ert_rowid" metho
36a0: 64 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  d returns an int
36b0: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74 68  eger which is th
36c0: 65 20 52 4f 57 49 44 0a 6f 66 20 74 68 65 20 6d  e ROWID.of the m
36d0: 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 69 6e 73  ost recently ins
36e0: 65 72 74 65 64 20 64 61 74 61 62 61 73 65 20 72  erted database r
36f0: 6f 77 2e 3c 2f 70 3e 0a 7d 0a 0a 23 23 23 23 23  ow.</p>.}..#####
3700: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3710: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3720: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3730: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3740: 23 23 23 23 23 23 23 23 23 0a 4d 45 54 48 4f 44  #########.METHOD
3750: 20 66 75 6e 63 74 69 6f 6e 20 7b 0a 0a 3c 70 3e   function {..<p>
3760: 54 68 65 20 22 66 75 6e 63 74 69 6f 6e 22 20 6d  The "function" m
3770: 65 74 68 6f 64 20 72 65 67 69 73 74 65 72 73 20  ethod registers 
3780: 6e 65 77 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  new SQL function
3790: 73 20 77 69 74 68 20 74 68 65 20 53 51 4c 69 74  s with the SQLit
37a0: 65 20 65 6e 67 69 6e 65 2e 0a 54 68 65 20 61 72  e engine..The ar
37b0: 67 75 6d 65 6e 74 73 20 61 72 65 20 74 68 65 20  guments are the 
37c0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20  name of the new 
37d0: 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 6e 64  SQL function and
37e0: 20 61 20 54 43 4c 20 63 6f 6d 6d 61 6e 64 20 74   a TCL command t
37f0: 68 61 74 0a 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat.implements t
3800: 68 61 74 20 66 75 6e 63 74 69 6f 6e 2e 20 20 41  hat function.  A
3810: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
3820: 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 70 70  function are app
3830: 65 6e 64 65 64 20 74 6f 20 74 68 65 0a 54 43 4c  ended to the.TCL
3840: 20 63 6f 6d 6d 61 6e 64 20 62 65 66 6f 72 65 20   command before 
3850: 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 3c 2f  it is invoked.</
3860: 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 66 6f 6c 6c  p>..<p>.The foll
3870: 6f 77 69 6e 67 20 65 78 61 6d 70 6c 65 20 63 72  owing example cr
3880: 65 61 74 65 73 20 61 20 6e 65 77 20 53 51 4c 20  eates a new SQL 
3890: 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 22  function named "
38a0: 68 65 78 22 20 74 68 61 74 20 63 6f 6e 76 65 72  hex" that conver
38b0: 74 73 0a 69 74 73 20 6e 75 6d 65 72 69 63 20 61  ts.its numeric a
38c0: 72 67 75 6d 65 6e 74 20 69 6e 20 74 6f 20 61 20  rgument in to a 
38d0: 68 65 78 61 64 65 63 69 6d 61 6c 20 65 6e 63 6f  hexadecimal enco
38e0: 64 65 64 20 73 74 72 69 6e 67 3a 0a 3c 2f 70 3e  ded string:.</p>
38f0: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 62  ..<blockquote><b
3900: 3e 0a 64 62 20 66 75 6e 63 74 69 6f 6e 20 68 65  >.db function he
3910: 78 20 7b 66 6f 72 6d 61 74 20 30 78 25 58 7d 0a  x {format 0x%X}.
3920: 3c 2f 62 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  </b></blockquote
3930: 3e 0a 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23 23  >..}..##########
3940: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3950: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3960: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3970: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3980: 23 23 23 23 0a 4d 45 54 48 4f 44 20 6e 75 6c 6c  ####.METHOD null
3990: 76 61 6c 75 65 20 7b 0a 0a 3c 70 3e 0a 54 68 65  value {..<p>.The
39a0: 20 22 6e 75 6c 6c 76 61 6c 75 65 22 20 6d 65 74   "nullvalue" met
39b0: 68 6f 64 20 63 68 61 6e 67 65 73 20 74 68 65 20  hod changes the 
39c0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 66  representation f
39d0: 6f 72 20 4e 55 4c 4c 20 72 65 74 75 72 6e 65 64  or NULL returned
39e0: 0a 61 73 20 72 65 73 75 6c 74 20 6f 66 20 74 68  .as result of th
39f0: 65 20 22 65 76 61 6c 22 20 6d 65 74 68 6f 64 2e  e "eval" method.
3a00: 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  </p>..<blockquot
3a10: 65 3e 3c 62 3e 0a 64 62 31 20 6e 75 6c 6c 76 61  e><b>.db1 nullva
3a20: 6c 75 65 20 4e 55 4c 4c 0a 3c 2f 62 3e 3c 2f 62  lue NULL.</b></b
3a30: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54  lockquote>..<p>T
3a40: 68 65 20 22 6e 75 6c 6c 76 61 6c 75 65 22 20 6d  he "nullvalue" m
3a50: 65 74 68 6f 64 20 69 73 20 75 73 65 66 75 6c 20  ethod is useful 
3a60: 74 6f 20 64 69 66 66 65 72 20 62 65 74 77 65 65  to differ betwee
3a70: 6e 20 4e 55 4c 4c 20 61 6e 64 20 65 6d 70 74 79  n NULL and empty
3a80: 0a 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61  .column values a
3a90: 73 20 54 63 6c 20 6c 61 63 6b 73 20 61 20 4e 55  s Tcl lacks a NU
3aa0: 4c 4c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  LL representatio
3ab0: 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 0a  n.  The default.
3ac0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 66  representation f
3ad0: 6f 72 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 69  or NULL values i
3ae0: 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
3af0: 67 2e 3c 2f 70 3e 0a 7d 0a 0a 0a 0a 23 23 23 23  g.</p>.}....####
3b00: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3b10: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3b20: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3b30: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3b40: 23 23 23 23 23 23 23 23 23 23 0a 4d 45 54 48 4f  ##########.METHO
3b50: 44 20 6f 6e 65 63 6f 6c 75 6d 6e 20 7b 0a 0a 3c  D onecolumn {..<
3b60: 70 3e 54 68 65 20 22 6f 6e 65 63 6f 6c 75 6d 6e  p>The "onecolumn
3b70: 22 20 6d 65 74 68 6f 64 20 77 6f 72 6b 73 20 6c  " method works l
3b80: 69 6b 65 20 0a 22 3c 61 20 68 72 65 66 3d 22 23  ike ."<a href="#
3b90: 65 76 61 6c 22 3e 65 76 61 6c 3c 2f 61 3e 22 20  eval">eval</a>" 
3ba0: 69 6e 20 74 68 61 74 20 69 74 20 65 76 61 6c 75  in that it evalu
3bb0: 61 74 65 73 20 74 68 65 0a 53 51 4c 20 71 75 65  ates the.SQL que
3bc0: 72 79 20 73 74 61 74 65 6d 65 6e 74 20 67 69 76  ry statement giv
3bd0: 65 6e 20 61 73 20 69 74 73 20 61 72 67 75 6d 65  en as its argume
3be0: 6e 74 2e 20 20 54 68 65 20 64 69 66 66 65 72 65  nt.  The differe
3bf0: 6e 63 65 20 69 73 20 74 68 61 74 0a 22 6f 6e 65  nce is that."one
3c00: 63 6f 6c 75 6d 6e 22 20 72 65 74 75 72 6e 73 20  column" returns 
3c10: 61 20 73 69 6e 67 6c 65 20 65 6c 65 6d 65 6e 74  a single element
3c20: 20 77 68 69 63 68 20 69 73 20 74 68 65 20 66 69   which is the fi
3c30: 72 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  rst column of th
3c40: 65 0a 66 69 72 73 74 20 72 6f 77 20 6f 66 20 74  e.first row of t
3c50: 68 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 2e  he query result.
3c60: 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 69 73 20 69 73  </p>..<p>This is
3c70: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 6d   a convenience m
3c80: 65 74 68 6f 64 2e 20 20 49 74 20 73 61 76 65 73  ethod.  It saves
3c90: 20 74 68 65 20 75 73 65 72 20 66 72 6f 6d 20 68   the user from h
3ca0: 61 76 69 6e 67 20 74 6f 0a 64 6f 20 61 20 22 3c  aving to.do a "<
3cb0: 74 74 3e 5b 6c 69 6e 64 65 78 26 6e 62 73 70 3b  tt>[lindex&nbsp;
3cc0: 2e 2e 2e 26 6e 62 73 70 3b 30 5d 3c 2f 74 74 3e  ...&nbsp;0]</tt>
3cd0: 22 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 73  " on the results
3ce0: 20 6f 66 20 61 6e 20 22 65 76 61 6c 22 0a 69 6e   of an "eval".in
3cf0: 20 6f 72 64 65 72 20 74 6f 20 65 78 74 72 61 63   order to extrac
3d00: 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
3d10: 6e 20 72 65 73 75 6c 74 2e 3c 2f 70 3e 0a 7d 0a  n result.</p>.}.
3d20: 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  .###############
3d30: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3d40: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3d50: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3d60: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a  ###############.
3d70: 4d 45 54 48 4f 44 20 63 68 61 6e 67 65 73 20 7b  METHOD changes {
3d80: 0a 0a 3c 70 3e 54 68 65 20 22 63 68 61 6e 67 65  ..<p>The "change
3d90: 73 22 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  s" method return
3da0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
3db0: 63 68 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ch is the number
3dc0: 20 6f 66 20 72 6f 77 73 0a 69 6e 20 74 68 65 20   of rows.in the 
3dd0: 64 61 74 61 62 61 73 65 20 74 68 61 74 20 77 65  database that we
3de0: 72 65 20 69 6e 73 65 72 74 65 64 2c 20 64 65 6c  re inserted, del
3df0: 65 74 65 64 2c 20 61 6e 64 2f 6f 72 20 6d 6f 64  eted, and/or mod
3e00: 69 66 69 65 64 20 62 79 20 74 68 65 20 6d 6f 73  ified by the mos
3e10: 74 0a 72 65 63 65 6e 74 20 22 65 76 61 6c 22 20  t.recent "eval" 
3e20: 6d 65 74 68 6f 64 2e 3c 2f 70 3e 0a 7d 0a 0a 23  method.</p>.}..#
3e30: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3e40: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3e50: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3e60: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3e70: 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 4d 45  #############.ME
3e80: 54 48 4f 44 20 74 6f 74 61 6c 5f 63 68 61 6e 67  THOD total_chang
3e90: 65 73 20 7b 0a 0a 3c 70 3e 54 68 65 20 22 74 6f  es {..<p>The "to
3ea0: 74 61 6c 5f 63 68 61 6e 67 65 73 22 20 6d 65 74  tal_changes" met
3eb0: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 6e 20 69  hod returns an i
3ec0: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
3ed0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
3ee0: 77 73 0a 69 6e 20 74 68 65 20 64 61 74 61 62 61  ws.in the databa
3ef0: 73 65 20 74 68 61 74 20 77 65 72 65 20 69 6e 73  se that were ins
3f00: 65 72 74 65 64 2c 20 64 65 6c 65 74 65 64 2c 20  erted, deleted, 
3f10: 61 6e 64 2f 6f 72 20 6d 6f 64 69 66 69 65 64 20  and/or modified 
3f20: 73 69 6e 63 65 20 74 68 65 0a 63 75 72 72 65 6e  since the.curren
3f30: 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  t database conne
3f40: 63 74 69 6f 6e 20 77 61 73 20 66 69 72 73 74 20  ction was first 
3f50: 6f 70 65 6e 65 64 2e 3c 2f 70 3e 0a 7d 0a 0a 23  opened.</p>.}..#
3f60: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3f70: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3f80: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3f90: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3fa0: 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 4d 45  #############.ME
3fb0: 54 48 4f 44 20 61 75 74 68 6f 72 69 7a 65 72 20  THOD authorizer 
3fc0: 7b 0a 0a 3c 70 3e 54 68 65 20 22 61 75 74 68 6f  {..<p>The "autho
3fd0: 72 69 7a 65 72 22 20 6d 65 74 68 6f 64 20 70 72  rizer" method pr
3fe0: 6f 76 69 64 65 73 20 61 63 63 65 73 73 20 74 6f  ovides access to
3ff0: 20 74 68 65 20 0a 3c 61 20 68 72 65 66 3d 22 63   the .<a href="c
4000: 61 70 69 33 72 65 66 2e 68 74 6d 6c 23 73 71 6c  api3ref.html#sql
4010: 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
4020: 7a 65 72 22 3e 73 71 6c 69 74 65 33 5f 73 65 74  zer">sqlite3_set
4030: 5f 61 75 74 68 6f 72 69 7a 65 72 3c 2f 61 3e 0a  _authorizer</a>.
4040: 43 2f 43 2b 2b 20 69 6e 74 65 72 66 61 63 65 2e  C/C++ interface.
4050: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 74    The argument t
4060: 6f 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  o authorizer is 
4070: 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 70 72  the name of a pr
4080: 6f 63 65 64 75 72 65 20 74 68 61 74 0a 69 73 20  ocedure that.is 
4090: 63 61 6c 6c 65 64 20 77 68 65 6e 20 53 51 4c 20  called when SQL 
40a0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
40b0: 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 20 69 6e  eing compiled in
40c0: 20 6f 72 64 65 72 20 74 6f 20 61 75 74 68 6f 72   order to author
40d0: 69 7a 65 0a 63 65 72 74 61 69 6e 20 6f 70 65 72  ize.certain oper
40e0: 61 74 69 6f 6e 73 2e 20 20 54 68 65 20 63 61 6c  ations.  The cal
40f0: 6c 62 61 63 6b 20 70 72 6f 63 65 64 75 72 65 20  lback procedure 
4100: 74 61 6b 65 73 20 35 20 61 72 67 75 6d 65 6e 74  takes 5 argument
4110: 73 20 77 68 69 63 68 20 64 65 73 63 72 69 62 65  s which describe
4120: 0a 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 62  .the operation b
4130: 65 69 6e 67 20 63 6f 64 65 64 2e 20 20 49 66 20  eing coded.  If 
4140: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
4150: 75 72 6e 73 20 74 68 65 20 74 65 78 74 20 73 74  urns the text st
4160: 72 69 6e 67 0a 22 53 51 4c 49 54 45 5f 4f 4b 22  ring."SQLITE_OK"
4170: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61  , then the opera
4180: 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 2e  tion is allowed.
4190: 20 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20    If it returns 
41a0: 22 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 22 2c  "SQLITE_IGNORE",
41b0: 0a 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74  .then the operat
41c0: 69 6f 6e 20 69 73 20 73 69 6c 65 6e 74 6c 79 20  ion is silently 
41d0: 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68  disabled.  If th
41e0: 65 20 72 65 74 75 72 6e 20 69 73 20 22 53 51 4c  e return is "SQL
41f0: 49 54 45 5f 44 45 4e 59 22 0a 74 68 65 6e 20 74  ITE_DENY".then t
4200: 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 66  he compilation f
4210: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
4220: 6f 72 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 49 66 20  or..</p>..<p>If 
4230: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
4240: 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
4250: 74 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69  then the authori
4260: 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e  zer is disabled.
4270: 0a 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  .If the argument
4280: 20 69 73 20 6f 6d 69 74 74 65 64 2c 20 74 68 65   is omitted, the
4290: 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 61 75  n the current au
42a0: 74 68 6f 72 69 7a 65 72 20 69 73 20 72 65 74 75  thorizer is retu
42b0: 72 6e 65 64 2e 3c 2f 70 3e 0a 7d 0a 0a 23 23 23  rned.</p>.}..###
42c0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
42d0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
42e0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
42f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4300: 23 23 23 23 23 23 23 23 23 23 23 0a 4d 45 54 48  ###########.METH
4310: 4f 44 20 70 72 6f 67 72 65 73 73 20 7b 0a 0a 3c  OD progress {..<
4320: 70 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 72 65  p>This method re
4330: 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
4340: 63 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ck that is invok
4350: 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
4360: 64 75 72 69 6e 67 0a 71 75 65 72 79 20 70 72 6f  during.query pro
4370: 63 65 73 73 69 6e 67 2e 20 20 54 68 65 72 65 20  cessing.  There 
4380: 61 72 65 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  are two argument
4390: 73 3a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  s: the number of
43a0: 20 53 51 4c 69 74 65 20 76 69 72 74 75 61 6c 0a   SQLite virtual.
43b0: 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 20  machine opcodes 
43c0: 62 65 74 77 65 65 6e 20 69 6e 76 6f 63 61 74 69  between invocati
43d0: 6f 6e 73 2c 20 61 6e 64 20 74 68 65 20 54 43 4c  ons, and the TCL
43e0: 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 69 6e 76 6f   command to invo
43f0: 6b 65 2e 0a 53 65 74 74 69 6e 67 20 74 68 65 20  ke..Setting the 
4400: 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
4410: 6b 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  k to an empty st
4420: 72 69 6e 67 20 64 69 73 61 62 6c 65 73 20 69 74  ring disables it
4430: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 70 72  .</p>..<p>The pr
4440: 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
4450: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
4460: 69 73 70 6c 61 79 20 74 68 65 20 73 74 61 74 75  isplay the statu
4470: 73 20 6f 66 20 61 20 6c 65 6e 67 74 68 79 0a 71  s of a lengthy.q
4480: 75 65 72 79 20 6f 72 20 74 6f 20 70 72 6f 63 65  uery or to proce
4490: 73 73 20 47 55 49 20 65 76 65 6e 74 73 20 64 75  ss GUI events du
44a0: 72 69 6e 67 20 61 20 6c 65 6e 67 74 68 79 20 71  ring a lengthy q
44b0: 75 65 72 79 2e 3c 2f 70 3e 0a 7d 0a 0a 0a 23 23  uery.</p>.}...##
44c0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
44d0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
44e0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
44f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4500: 23 23 23 23 23 23 23 23 23 23 23 23 0a 4d 45 54  ############.MET
4510: 48 4f 44 20 63 6f 6c 6c 61 74 65 20 7b 0a 0a 3c  HOD collate {..<
4520: 70 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 72 65  p>This method re
4530: 67 69 73 74 65 72 73 20 6e 65 77 20 74 65 78 74  gisters new text
4540: 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
4550: 6e 63 65 73 2e 20 20 54 68 65 72 65 20 61 72 65  nces.  There are
4560: 0a 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20  .two arguments: 
4570: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
4580: 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
4590: 63 65 20 61 6e 64 20 74 68 65 20 6e 61 6d 65 20  ce and the name 
45a0: 6f 66 20 61 0a 54 43 4c 20 70 72 6f 63 65 64 75  of a.TCL procedu
45b0: 72 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  re that implemen
45c0: 74 73 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20  ts a comparison 
45d0: 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65  function for the
45e0: 20 63 6f 6c 6c 61 74 69 6e 67 0a 73 65 71 75 65   collating.seque
45f0: 6e 63 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 46 6f  nce..</p>..<p>Fo
4600: 72 20 65 78 61 6d 70 6c 65 2c 20 74 68 65 20 66  r example, the f
4610: 6f 6c 6c 6f 77 69 6e 67 20 63 6f 64 65 20 69 6d  ollowing code im
4620: 70 6c 65 6d 65 6e 74 73 20 61 20 63 6f 6c 6c 61  plements a colla
4630: 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 63 61  ting sequence ca
4640: 6c 6c 65 64 0a 22 4e 4f 43 41 53 45 22 20 74 68  lled."NOCASE" th
4650: 61 74 20 73 6f 72 74 73 20 69 6e 20 74 65 78 74  at sorts in text
4660: 20 6f 72 64 65 72 20 77 69 74 68 6f 75 74 20 72   order without r
4670: 65 67 61 72 64 20 74 6f 20 63 61 73 65 3a 0a 3c  egard to case:.<
4680: 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  /p>..<blockquote
4690: 3e 3c 62 3e 0a 70 72 6f 63 20 6e 6f 63 61 73 65  ><b>.proc nocase
46a0: 5f 63 6f 6d 70 61 72 65 20 7b 61 20 62 7d 20 7b  _compare {a b} {
46b0: 3c 62 72 3e 0a 26 6e 62 73 70 3b 26 6e 62 73 70  <br>.&nbsp;&nbsp
46c0: 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 72 65 74  ;&nbsp;&nbsp;ret
46d0: 75 72 6e 20 5b 73 74 72 69 6e 67 20 63 6f 6d 70  urn [string comp
46e0: 61 72 65 20 5b 73 74 72 69 6e 67 20 74 6f 6c 6f  are [string tolo
46f0: 77 65 72 20 24 61 5d 20 5b 73 74 72 69 6e 67 20  wer $a] [string 
4700: 74 6f 6c 6f 77 65 72 20 24 62 5d 5d 3c 62 72 3e  tolower $b]]<br>
4710: 0a 7d 3c 62 72 3e 0a 64 62 20 63 6f 6c 6c 61 74  .}<br>.db collat
4720: 65 20 4e 4f 43 41 53 45 20 6e 6f 63 61 73 65 5f  e NOCASE nocase_
4730: 63 6f 6d 70 61 72 65 3c 62 72 3e 0a 3c 2f 62 3e  compare<br>.</b>
4740: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 7d 0a  </blockquote>.}.
4750: 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  .###############
4760: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4770: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4780: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4790: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a  ###############.
47a0: 4d 45 54 48 4f 44 20 63 6f 6c 6c 61 74 69 6f 6e  METHOD collation
47b0: 5f 6e 65 65 64 65 64 20 7b 0a 0a 3c 70 3e 54 68  _needed {..<p>Th
47c0: 69 73 20 6d 65 74 68 6f 64 20 72 65 67 69 73 74  is method regist
47d0: 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 72  ers a callback r
47e0: 6f 75 74 69 6e 65 20 74 68 61 74 20 69 73 20 69  outine that is i
47f0: 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
4800: 53 51 4c 69 74 65 0a 65 6e 67 69 6e 65 20 6e 65  SQLite.engine ne
4810: 65 64 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  eds a particular
4820: 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
4830: 6e 63 65 20 62 75 74 20 64 6f 65 73 20 6e 6f 74  nce but does not
4840: 20 68 61 76 65 20 74 68 61 74 0a 63 6f 6c 6c 61   have that.colla
4850: 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 72 65  ting sequence re
4860: 67 69 73 74 65 72 65 64 2e 20 20 54 68 65 20 63  gistered.  The c
4870: 61 6c 6c 62 61 63 6b 20 63 61 6e 20 72 65 67 69  allback can regi
4880: 73 74 65 72 20 74 68 65 20 63 6f 6c 6c 61 74 69  ster the collati
4890: 6e 67 0a 73 65 71 75 65 6e 63 65 2e 20 20 54 68  ng.sequence.  Th
48a0: 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
48b0: 76 6f 6b 65 64 20 77 69 74 68 20 61 20 73 69 6e  voked with a sin
48c0: 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
48d0: 69 63 68 20 69 73 20 74 68 65 0a 6e 61 6d 65 20  ich is the.name 
48e0: 6f 66 20 74 68 65 20 6e 65 65 64 65 64 20 63 6f  of the needed co
48f0: 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65  llating sequence
4900: 2e 3c 2f 70 3e 0a 7d 0a 0a 23 23 23 23 23 23 23  .</p>.}..#######
4910: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4920: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4930: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4940: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4950: 23 23 23 23 23 23 23 0a 4d 45 54 48 4f 44 20 63  #######.METHOD c
4960: 6f 6d 6d 69 74 5f 68 6f 6f 6b 20 7b 0a 0a 3c 70  ommit_hook {..<p
4970: 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 72 65 67  >This method reg
4980: 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
4990: 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
49a0: 73 20 69 6e 76 6f 6b 65 64 20 6a 75 73 74 20 62  s invoked just b
49b0: 65 66 6f 72 65 0a 53 51 4c 69 74 65 20 74 72 69  efore.SQLite tri
49c0: 65 73 20 74 6f 20 63 6f 6d 6d 69 74 20 63 68 61  es to commit cha
49d0: 6e 67 65 73 20 74 6f 20 61 20 64 61 74 61 62 61  nges to a databa
49e0: 73 65 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c  se.  If the call
49f0: 62 61 63 6b 20 74 68 72 6f 77 73 0a 61 6e 20 65  back throws.an e
4a00: 78 63 65 70 74 69 6f 6e 20 6f 72 20 72 65 74 75  xception or retu
4a10: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72  rns a non-zero r
4a20: 65 73 75 6c 74 2c 20 74 68 65 6e 20 74 68 65 20  esult, then the 
4a30: 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c  transaction roll
4a40: 73 20 62 61 63 6b 0a 72 61 74 68 65 72 20 74 68  s back.rather th
4a50: 61 6e 20 63 6f 6d 6d 69 74 2e 3c 2f 70 3e 0a 7d  an commit.</p>.}
4a60: 0a 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ..##############
4a70: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4a80: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4a90: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4aa0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4ab0: 0a 4d 45 54 48 4f 44 20 65 72 72 6f 72 63 6f 64  .METHOD errorcod
4ac0: 65 20 7b 0a 0a 3c 70 3e 54 68 69 73 20 6d 65 74  e {..<p>This met
4ad0: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
4ae0: 6e 75 6d 65 72 69 63 20 65 72 72 6f 72 20 63 6f  numeric error co
4af0: 64 65 20 74 68 61 74 20 72 65 73 75 6c 74 65 64  de that resulted
4b00: 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 0a 72   from the most.r
4b10: 65 63 65 6e 74 20 53 51 4c 69 74 65 20 6f 70 65  ecent SQLite ope
4b20: 72 61 74 69 6f 6e 2e 3c 2f 70 3e 0a 7d 0a 0a 23  ration.</p>.}..#
4b30: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4b40: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4b50: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4b60: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4b70: 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 4d 45  #############.ME
4b80: 54 48 4f 44 20 74 72 61 63 65 20 7b 0a 0a 3c 70  THOD trace {..<p
4b90: 3e 54 68 65 20 22 74 72 61 63 65 22 20 6d 65 74  >The "trace" met
4ba0: 68 6f 64 20 72 65 67 69 73 74 65 72 73 20 61 20  hod registers a 
4bb0: 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73  callback that is
4bc0: 20 69 6e 76 6f 6b 65 64 20 61 73 20 65 61 63 68   invoked as each
4bd0: 20 53 51 4c 0a 73 74 61 74 65 6d 65 6e 74 20 69   SQL.statement i
4be0: 73 20 63 6f 6d 70 69 6c 65 64 2e 20 20 54 68 65  s compiled.  The
4bf0: 20 74 65 78 74 20 6f 66 20 74 68 65 20 53 51 4c   text of the SQL
4c00: 20 69 73 20 61 70 70 65 6e 64 65 64 20 61 73 20   is appended as 
4c10: 61 20 73 69 6e 67 6c 65 20 73 74 72 69 6e 67 0a  a single string.
4c20: 74 6f 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 62  to the command b
4c30: 65 66 6f 72 65 20 69 74 20 69 73 20 69 6e 76 6f  efore it is invo
4c40: 6b 65 64 2e 20 20 54 68 69 73 20 63 61 6e 20 62  ked.  This can b
4c50: 65 20 75 73 65 64 20 28 66 6f 72 20 65 78 61 6d  e used (for exam
4c60: 70 6c 65 29 20 74 6f 0a 6b 65 65 70 20 61 20 6c  ple) to.keep a l
4c70: 6f 67 20 6f 66 20 61 6c 6c 20 53 51 4c 20 6f 70  og of all SQL op
4c80: 65 72 61 74 69 6f 6e 73 20 74 68 61 74 20 61 6e  erations that an
4c90: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 65 72   application per
4ca0: 66 6f 72 6d 73 2e 0a 3c 2f 70 3e 0a 7d 0a 0a 0a  forms..</p>.}...
4cb0: 66 6f 6f 74 65 72 20 24 72 63 73 69 64 0a        footer $rcsid.