/ Hex Artifact Content
Login

Artifact e73f8f8e5f20e8277619433f7970060ab01088fc:


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 32 20 32 30 30 34 2f 31 32 2f 31 37 20 31  .12 2004/12/17 1
0070: 35 3a 34 31 3a 31 33 20 74 70 6f 69 6e 64 65 78  5:41:13 tpoindex
0080: 20 45 78 70 20 24 7d 0a 73 6f 75 72 63 65 20 63   Exp $}.source c
0090: 6f 6d 6d 6f 6e 2e 74 63 6c 0a 68 65 61 64 65 72  ommon.tcl.header
00a0: 20 7b 54 68 65 20 54 63 6c 20 69 6e 74 65 72 66   {The Tcl interf
00b0: 61 63 65 20 74 6f 20 74 68 65 20 53 51 4c 69 74  ace to the SQLit
00c0: 65 20 6c 69 62 72 61 72 79 7d 0a 70 72 6f 63 20  e library}.proc 
00d0: 4d 45 54 48 4f 44 20 7b 6e 61 6d 65 20 74 65 78  METHOD {name tex
00e0: 74 7d 20 7b 0a 20 20 70 75 74 73 20 22 3c 61 20  t} {.  puts "<a 
00f0: 6e 61 6d 65 3d 5c 22 24 6e 61 6d 65 5c 22 3e 5c  name=\"$name\">\
0100: 6e 3c 68 33 3e 54 68 65 20 5c 22 24 6e 61 6d 65  n<h3>The \"$name
0110: 5c 22 20 6d 65 74 68 6f 64 3c 2f 68 33 3e 5c 6e  \" method</h3>\n
0120: 22 0a 20 20 70 75 74 73 20 24 74 65 78 74 0a 7d  ".  puts $text.}
0130: 0a 70 75 74 73 20 7b 0a 3c 68 32 3e 54 68 65 20  .puts {.<h2>The 
0140: 54 63 6c 20 69 6e 74 65 72 66 61 63 65 20 74 6f  Tcl interface to
0150: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
0160: 61 72 79 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65  ary</h2>..<p>The
0170: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
0180: 69 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 62  is designed to b
0190: 65 20 76 65 72 79 20 65 61 73 79 20 74 6f 20 75  e very easy to u
01a0: 73 65 20 66 72 6f 6d 0a 61 20 54 63 6c 20 6f 72  se from.a Tcl or
01b0: 20 54 63 6c 2f 54 6b 20 73 63 72 69 70 74 2e 20   Tcl/Tk script. 
01c0: 20 54 68 69 73 20 64 6f 63 75 6d 65 6e 74 20 67   This document g
01d0: 69 76 65 73 20 61 6e 20 6f 76 65 72 76 69 65 77  ives an overview
01e0: 20 6f 66 20 74 68 65 20 54 63 6c 0a 70 72 6f 67   of the Tcl.prog
01f0: 72 61 6d 6d 69 6e 67 20 69 6e 74 65 72 66 61 63  ramming interfac
0200: 65 2e 3c 2f 70 3e 0a 0a 3c 68 33 3e 54 68 65 20  e.</p>..<h3>The 
0210: 41 50 49 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 68 65  API</h3>..<p>The
0220: 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
0230: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
0240: 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 73 69 6e   consists of sin
0250: 67 6c 65 0a 74 63 6c 20 63 6f 6d 6d 61 6e 64 20  gle.tcl command 
0260: 6e 61 6d 65 64 20 3c 62 3e 73 71 6c 69 74 65 3c  named <b>sqlite<
0270: 2f 62 3e 20 28 76 65 72 73 69 6f 6e 20 32 2e 38  /b> (version 2.8
0280: 29 20 6f 72 20 3c 62 3e 73 71 6c 69 74 65 33 3c  ) or <b>sqlite3<
0290: 2f 62 3e 0a 28 76 65 72 73 69 6f 6e 20 33 2e 30  /b>.(version 3.0
02a0: 29 2e 20 20 42 65 63 61 75 73 65 20 74 68 65 72  ).  Because ther
02b0: 65 20 69 73 20 6f 6e 6c 79 20 74 68 69 73 0a 6f  e is only this.o
02c0: 6e 65 20 63 6f 6d 6d 61 6e 64 2c 20 74 68 65 20  ne command, the 
02d0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
02e0: 20 70 6c 61 63 65 64 20 69 6e 20 61 20 73 65 70   placed in a sep
02f0: 61 72 61 74 65 0a 6e 61 6d 65 73 70 61 63 65 2e  arate.namespace.
0300: 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 3c 62 3e  </p>..<p>The <b>
0310: 73 71 6c 69 74 65 33 3c 2f 62 3e 20 63 6f 6d 6d  sqlite3</b> comm
0320: 61 6e 64 20 69 73 20 75 73 65 64 20 61 73 20 66  and is used as f
0330: 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c  ollows:</p>..<bl
0340: 6f 63 6b 71 75 6f 74 65 3e 0a 3c 62 3e 73 71 6c  ockquote>.<b>sql
0350: 69 74 65 33 3c 2f 62 3e 26 6e 62 73 70 3b 26 6e  ite3</b>&nbsp;&n
0360: 62 73 70 3b 3c 69 3e 64 62 63 6d 64 26 6e 62 73  bsp;<i>dbcmd&nbs
0370: 70 3b 26 6e 62 73 70 3b 64 61 74 61 62 61 73 65  p;&nbsp;database
0380: 2d 6e 61 6d 65 3c 2f 69 3e 0a 3c 2f 62 6c 6f 63  -name</i>.</bloc
0390: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65  kquote>..<p>.The
03a0: 20 3c 62 3e 73 71 6c 69 74 65 33 3c 2f 62 3e 20   <b>sqlite3</b> 
03b0: 63 6f 6d 6d 61 6e 64 20 6f 70 65 6e 73 20 74 68  command opens th
03c0: 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 64  e database named
03d0: 20 69 6e 20 74 68 65 20 73 65 63 6f 6e 64 0a 61   in the second.a
03e0: 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  rgument.  If the
03f0: 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
0400: 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
0410: 2c 20 69 74 20 69 73 0a 61 75 74 6f 6d 61 74 69  , it is.automati
0420: 63 61 6c 6c 79 20 63 72 65 61 74 65 64 2e 0a 54  cally created..T
0430: 68 65 20 3c 62 3e 73 71 6c 69 74 65 33 3c 2f 62  he <b>sqlite3</b
0440: 3e 20 63 6f 6d 6d 61 6e 64 20 61 6c 73 6f 20 63  > command also c
0450: 72 65 61 74 65 73 20 61 20 6e 65 77 20 54 63 6c  reates a new Tcl
0460: 0a 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 6f 6e 74  .command to cont
0470: 72 6f 6c 20 74 68 65 20 64 61 74 61 62 61 73 65  rol the database
0480: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  .  The name of t
0490: 68 65 20 6e 65 77 20 54 63 6c 20 63 6f 6d 6d 61  he new Tcl comma
04a0: 6e 64 0a 69 73 20 67 69 76 65 6e 20 62 79 20 74  nd.is given by t
04b0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
04c0: 74 2e 20 20 54 68 69 73 20 61 70 70 72 6f 61 63  t.  This approac
04d0: 68 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  h is similar to 
04e0: 74 68 65 0a 77 61 79 20 77 69 64 67 65 74 73 20  the.way widgets 
04f0: 61 72 65 20 63 72 65 61 74 65 64 20 69 6e 20 54  are created in T
0500: 6b 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65  k..</p>..<p>.The
0510: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
0520: 61 62 61 73 65 20 69 73 20 6a 75 73 74 20 74 68  abase is just th
0530: 65 20 6e 61 6d 65 20 6f 66 20 61 20 64 69 73 6b  e name of a disk
0540: 20 66 69 6c 65 20 69 6e 20 77 68 69 63 68 0a 74   file in which.t
0550: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 73  he database is s
0560: 74 6f 72 65 64 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e  tored..</p>..<p>
0570: 0a 4f 6e 63 65 20 61 6e 20 53 51 4c 69 74 65 20  .Once an SQLite 
0580: 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
0590: 2c 20 69 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  , it can be cont
05a0: 72 6f 6c 6c 65 64 20 75 73 69 6e 67 20 0a 6d 65  rolled using .me
05b0: 74 68 6f 64 73 20 6f 66 20 74 68 65 20 3c 69 3e  thods of the <i>
05c0: 64 62 63 6d 64 3c 2f 69 3e 2e 20 20 54 68 65 72  dbcmd</i>.  Ther
05d0: 65 20 61 72 65 20 63 75 72 72 65 6e 74 6c 79 20  e are currently 
05e0: 31 38 20 6d 65 74 68 6f 64 73 0a 64 65 66 69 6e  18 methods.defin
05f0: 65 64 3a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 3c 75 6c  ed:</p>..<p>.<ul
0600: 3e 0a 7d 0a 66 6f 72 65 61 63 68 20 6d 20 5b 6c  >.}.foreach m [l
0610: 73 6f 72 74 20 7b 0a 20 61 75 74 68 6f 72 69 7a  sort {. authoriz
0620: 65 72 0a 20 62 75 73 79 0a 20 63 68 61 6e 67 65  er. busy. change
0630: 73 0a 20 63 6c 6f 73 65 0a 20 63 6f 6c 6c 61 74  s. close. collat
0640: 65 0a 20 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e. collation_nee
0650: 64 65 64 0a 20 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ded. commit_hook
0660: 0a 20 63 6f 6d 70 6c 65 74 65 0a 20 63 6f 70 79  . complete. copy
0670: 0a 20 65 72 72 6f 72 63 6f 64 65 0a 20 65 76 61  . errorcode. eva
0680: 6c 0a 20 66 75 6e 63 74 69 6f 6e 0a 20 6c 61 73  l. function. las
0690: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 0a 20  t_insert_rowid. 
06a0: 6f 6e 65 63 6f 6c 75 6d 6e 0a 20 70 72 6f 67 72  onecolumn. progr
06b0: 65 73 73 0a 20 74 69 6d 65 6f 75 74 0a 20 74 6f  ess. timeout. to
06c0: 74 61 6c 5f 63 68 61 6e 67 65 73 0a 20 74 72 61  tal_changes. tra
06d0: 63 65 0a 7d 5d 20 7b 0a 20 70 75 74 73 20 22 3c  ce.}] {. puts "<
06e0: 6c 69 3e 3c 61 20 68 72 65 66 3d 5c 22 23 24 6d  li><a href=\"#$m
06f0: 5c 22 3e 24 6d 3c 2f 61 3e 3c 2f 6c 69 3e 22 0a  \">$m</a></li>".
0700: 7d 0a 70 75 74 73 20 7b 0a 3c 2f 75 6c 3e 0a 3c  }.puts {.</ul>.<
0710: 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 75 73 65 20  /p>..<p>The use 
0720: 6f 66 20 65 61 63 68 20 6f 66 20 74 68 65 73 65  of each of these
0730: 20 6d 65 74 68 6f 64 73 20 77 69 6c 6c 20 62 65   methods will be
0740: 20 65 78 70 6c 61 69 6e 65 64 20 69 6e 20 74 68   explained in th
0750: 65 20 73 65 71 75 65 6c 2c 20 74 68 6f 75 67 68  e sequel, though
0760: 0a 6e 6f 74 20 69 6e 20 74 68 65 20 6f 72 64 65  .not in the orde
0770: 72 20 73 68 6f 77 6e 20 61 62 6f 76 65 2e 3c 2f  r shown above.</
0780: 70 3e 0a 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23  p>..}..#########
0790: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
07a0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
07b0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
07c0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
07d0: 23 23 23 23 23 0a 4d 45 54 48 4f 44 20 63 6c 6f  #####.METHOD clo
07e0: 73 65 20 7b 0a 0a 3c 70 3e 0a 41 73 20 69 74 73  se {..<p>.As its
07f0: 20 6e 61 6d 65 20 73 75 67 67 65 73 74 73 2c 20   name suggests, 
0800: 74 68 65 20 22 63 6c 6f 73 65 22 20 6d 65 74 68  the "close" meth
0810: 6f 64 20 74 6f 20 61 6e 20 53 51 4c 69 74 65 20  od to an SQLite 
0820: 64 61 74 61 62 61 73 65 20 6a 75 73 74 0a 63 6c  database just.cl
0830: 6f 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  oses the databas
0840: 65 2e 20 20 54 68 69 73 20 68 61 73 20 74 68 65  e.  This has the
0850: 20 73 69 64 65 2d 65 66 66 65 63 74 20 6f 66 20   side-effect of 
0860: 64 65 6c 65 74 69 6e 67 20 74 68 65 0a 3c 69 3e  deleting the.<i>
0870: 64 62 63 6d 64 3c 2f 69 3e 20 54 63 6c 20 63 6f  dbcmd</i> Tcl co
0880: 6d 6d 61 6e 64 2e 20 20 48 65 72 65 20 69 73 20  mmand.  Here is 
0890: 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6f 70  an example of op
08a0: 65 6e 69 6e 67 20 61 6e 64 20 74 68 65 6e 0a 69  ening and then.i
08b0: 6d 6d 65 64 69 61 74 65 6c 79 20 63 6c 6f 73 69  mmediately closi
08c0: 6e 67 20 61 20 64 61 74 61 62 61 73 65 3a 0a 3c  ng a database:.<
08d0: 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  /p>..<blockquote
08e0: 3e 0a 3c 62 3e 73 71 6c 69 74 65 33 20 64 62 31  >.<b>sqlite3 db1
08f0: 20 2e 2f 74 65 73 74 64 62 3c 62 72 3e 0a 64 62   ./testdb<br>.db
0900: 31 20 63 6c 6f 73 65 3c 2f 62 3e 0a 3c 2f 62 6c  1 close</b>.</bl
0910: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 49  ockquote>..<p>.I
0920: 66 20 79 6f 75 20 64 65 6c 65 74 65 20 74 68 65  f you delete the
0930: 20 3c 69 3e 64 62 63 6d 64 3c 2f 69 3e 20 64 69   <i>dbcmd</i> di
0940: 72 65 63 74 6c 79 2c 20 74 68 61 74 20 68 61 73  rectly, that has
0950: 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 63 74   the same effect
0960: 0a 61 73 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  .as invoking the
0970: 20 22 63 6c 6f 73 65 22 20 6d 65 74 68 6f 64 2e   "close" method.
0980: 20 20 53 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69    So the followi
0990: 6e 67 20 63 6f 64 65 20 69 73 20 65 71 75 69 76  ng code is equiv
09a0: 61 6c 65 6e 74 0a 74 6f 20 74 68 65 20 70 72 65  alent.to the pre
09b0: 76 69 6f 75 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f  vious:</p>..<blo
09c0: 63 6b 71 75 6f 74 65 3e 0a 3c 62 3e 73 71 6c 69  ckquote>.<b>sqli
09d0: 74 65 33 20 64 62 31 20 2e 2f 74 65 73 74 64 62  te3 db1 ./testdb
09e0: 3c 62 72 3e 0a 72 65 6e 61 6d 65 20 64 62 31 20  <br>.rename db1 
09f0: 7b 7d 3c 2f 62 3e 0a 3c 2f 62 6c 6f 63 6b 71 75  {}</b>.</blockqu
0a00: 6f 74 65 3e 0a 7d 0a 0a 23 23 23 23 23 23 23 23  ote>.}..########
0a10: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
0a20: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
0a30: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
0a40: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
0a50: 23 23 23 23 23 23 0a 4d 45 54 48 4f 44 20 65 76  ######.METHOD ev
0a60: 61 6c 20 7b 0a 3c 70 3e 0a 54 68 65 20 6d 6f 73  al {.<p>.The mos
0a70: 74 20 75 73 65 66 75 6c 20 3c 69 3e 64 62 63 6d  t useful <i>dbcm
0a80: 64 3c 2f 69 3e 20 6d 65 74 68 6f 64 20 69 73 20  d</i> method is 
0a90: 22 65 76 61 6c 22 2e 20 20 54 68 65 20 65 76 61  "eval".  The eva
0aa0: 6c 20 6d 65 74 68 6f 64 20 69 73 20 75 73 65 64  l method is used
0ab0: 0a 74 6f 20 65 78 65 63 75 74 65 20 53 51 4c 20  .to execute SQL 
0ac0: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  on the database.
0ad0: 20 20 54 68 65 20 73 79 6e 74 61 78 20 6f 66 20    The syntax of 
0ae0: 74 68 65 20 65 76 61 6c 20 6d 65 74 68 6f 64 20  the eval method 
0af0: 6c 6f 6f 6b 73 0a 6c 69 6b 65 20 74 68 69 73 3a  looks.like this:
0b00: 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  </p>..<blockquot
0b10: 65 3e 0a 3c 69 3e 64 62 63 6d 64 3c 2f 69 3e 26  e>.<i>dbcmd</i>&
0b20: 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 62 3e 65 76  nbsp;&nbsp;<b>ev
0b30: 61 6c 3c 2f 62 3e 26 6e 62 73 70 3b 26 6e 62 73  al</b>&nbsp;&nbs
0b40: 70 3b 3c 69 3e 73 71 6c 3c 2f 69 3e 0a 26 6e 62  p;<i>sql</i>.&nb
0b50: 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26  sp;&nbsp;&nbsp;&
0b60: 6e 62 73 70 3b 3f 3c 69 3e 61 72 72 61 79 2d 6e  nbsp;?<i>array-n
0b70: 61 6d 65 26 6e 62 73 70 3b 3c 2f 69 3e 3f 26 6e  ame&nbsp;</i>?&n
0b80: 62 73 70 3b 3f 3c 69 3e 73 63 72 69 70 74 3c 2f  bsp;?<i>script</
0b90: 69 3e 3f 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  i>?.</blockquote
0ba0: 3e 0a 0a 3c 70 3e 0a 54 68 65 20 6a 6f 62 20 6f  >..<p>.The job o
0bb0: 66 20 74 68 65 20 65 76 61 6c 20 6d 65 74 68 6f  f the eval metho
0bc0: 64 20 69 73 20 74 6f 20 65 78 65 63 75 74 65 20  d is to execute 
0bd0: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
0be0: 74 20 6f 72 20 73 74 61 74 65 6d 65 6e 74 73 0a  t or statements.
0bf0: 67 69 76 65 6e 20 69 6e 20 74 68 65 20 73 65 63  given in the sec
0c00: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 20 46  ond argument.  F
0c10: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 63  or example, to c
0c20: 72 65 61 74 65 20 61 20 6e 65 77 20 74 61 62 6c  reate a new tabl
0c30: 65 20 69 6e 0a 61 20 64 61 74 61 62 61 73 65 2c  e in.a database,
0c40: 20 79 6f 75 20 63 61 6e 20 64 6f 20 74 68 69 73   you can do this
0c50: 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  :</p>..<blockquo
0c60: 74 65 3e 0a 3c 62 3e 73 71 6c 69 74 65 33 20 64  te>.<b>sqlite3 d
0c70: 62 31 20 2e 2f 74 65 73 74 64 62 3c 62 72 3e 0a  b1 ./testdb<br>.
0c80: 64 62 31 20 65 76 61 6c 20 7b 43 52 45 41 54 45  db1 eval {CREATE
0c90: 20 54 41 42 4c 45 20 74 31 28 61 20 69 6e 74 2c   TABLE t1(a int,
0ca0: 20 62 20 74 65 78 74 29 7d 3c 2f 62 3e 0a 3c 2f   b text)}</b>.</
0cb0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e  blockquote>..<p>
0cc0: 54 68 65 20 61 62 6f 76 65 20 63 6f 64 65 20 63  The above code c
0cd0: 72 65 61 74 65 73 20 61 20 6e 65 77 20 74 61 62  reates a new tab
0ce0: 6c 65 20 6e 61 6d 65 64 20 3c 62 3e 74 31 3c 2f  le named <b>t1</
0cf0: 62 3e 20 77 69 74 68 20 63 6f 6c 75 6d 6e 73 0a  b> with columns.
0d00: 3c 62 3e 61 3c 2f 62 3e 20 61 6e 64 20 3c 62 3e  <b>a</b> and <b>
0d10: 62 3c 2f 62 3e 2e 20 20 57 68 61 74 20 63 6f 75  b</b>.  What cou
0d20: 6c 64 20 62 65 20 73 69 6d 70 6c 65 72 3f 3c 2f  ld be simpler?</
0d30: 70 3e 0a 0a 3c 70 3e 51 75 65 72 79 20 72 65 73  p>..<p>Query res
0d40: 75 6c 74 73 20 61 72 65 20 72 65 74 75 72 6e 65  ults are returne
0d50: 64 20 61 73 20 61 20 6c 69 73 74 20 6f 66 20 63  d as a list of c
0d60: 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 2e 20 20 49  olumn values.  I
0d70: 66 20 61 0a 71 75 65 72 79 20 72 65 71 75 65 73  f a.query reques
0d80: 74 73 20 32 20 63 6f 6c 75 6d 6e 73 20 61 6e 64  ts 2 columns and
0d90: 20 74 68 65 72 65 20 61 72 65 20 33 20 72 6f 77   there are 3 row
0da0: 73 20 6d 61 74 63 68 69 6e 67 20 74 68 65 20 71  s matching the q
0db0: 75 65 72 79 2c 0a 74 68 65 6e 20 74 68 65 20 72  uery,.then the r
0dc0: 65 74 75 72 6e 65 64 20 6c 69 73 74 20 77 69 6c  eturned list wil
0dd0: 6c 20 63 6f 6e 74 61 69 6e 20 36 20 65 6c 65 6d  l contain 6 elem
0de0: 65 6e 74 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  ents.  For examp
0df0: 6c 65 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71  le:</p>..<blockq
0e00: 75 6f 74 65 3e 0a 3c 62 3e 64 62 31 20 65 76 61  uote>.<b>db1 eva
0e10: 6c 20 7b 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  l {INSERT INTO t
0e20: 31 20 56 41 4c 55 45 53 28 31 2c 27 68 65 6c 6c  1 VALUES(1,'hell
0e30: 6f 27 29 7d 3c 62 72 3e 0a 64 62 31 20 65 76 61  o')}<br>.db1 eva
0e40: 6c 20 7b 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  l {INSERT INTO t
0e50: 31 20 56 41 4c 55 45 53 28 32 2c 27 67 6f 6f 64  1 VALUES(2,'good
0e60: 62 79 65 27 29 7d 3c 62 72 3e 0a 64 62 31 20 65  bye')}<br>.db1 e
0e70: 76 61 6c 20 7b 49 4e 53 45 52 54 20 49 4e 54 4f  val {INSERT INTO
0e80: 20 74 31 20 56 41 4c 55 45 53 28 33 2c 27 68 6f   t1 VALUES(3,'ho
0e90: 77 64 79 21 27 29 7d 3c 62 72 3e 0a 73 65 74 20  wdy!')}<br>.set 
0ea0: 78 20 5b 64 62 31 20 65 76 61 6c 20 7b 53 45 4c  x [db1 eval {SEL
0eb0: 45 43 54 20 2a 20 46 52 4f 4d 20 74 31 20 4f 52  ECT * FROM t1 OR
0ec0: 44 45 52 20 42 59 20 61 7d 5d 3c 2f 62 3e 0a 3c  DER BY a}]</b>.<
0ed0: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70  /blockquote>..<p
0ee0: 3e 54 68 65 20 76 61 72 69 61 62 6c 65 20 3c 62  >The variable <b
0ef0: 3e 24 78 3c 2f 62 3e 20 69 73 20 73 65 74 20 62  >$x</b> is set b
0f00: 79 20 74 68 65 20 61 62 6f 76 65 20 63 6f 64 65  y the above code
0f10: 20 74 6f 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71   to</p>..<blockq
0f20: 75 6f 74 65 3e 0a 3c 62 3e 31 20 68 65 6c 6c 6f  uote>.<b>1 hello
0f30: 20 32 20 67 6f 6f 64 62 79 65 20 33 20 68 6f 77   2 goodbye 3 how
0f40: 64 79 21 3c 2f 62 3e 0a 3c 2f 62 6c 6f 63 6b 71  dy!</b>.</blockq
0f50: 75 6f 74 65 3e 0a 0a 3c 70 3e 59 6f 75 20 63 61  uote>..<p>You ca
0f60: 6e 20 61 6c 73 6f 20 70 72 6f 63 65 73 73 20 74  n also process t
0f70: 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20 61 20  he results of a 
0f80: 71 75 65 72 79 20 6f 6e 65 20 72 6f 77 20 61 74  query one row at
0f90: 20 61 20 74 69 6d 65 0a 62 79 20 73 70 65 63 69   a time.by speci
0fa0: 66 79 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f  fying the name o
0fb0: 66 20 61 6e 20 61 72 72 61 79 20 76 61 72 69 61  f an array varia
0fc0: 62 6c 65 20 61 6e 64 20 61 20 73 63 72 69 70 74  ble and a script
0fd0: 20 66 6f 6c 6c 6f 77 69 6e 67 0a 74 68 65 20 53   following.the S
0fe0: 51 4c 20 63 6f 64 65 2e 20 20 46 6f 72 20 65 61  QL code.  For ea
0ff0: 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20 71 75  ch row of the qu
1000: 65 72 79 20 72 65 73 75 6c 74 2c 20 74 68 65 20  ery result, the 
1010: 76 61 6c 75 65 73 20 6f 66 20 61 6c 6c 0a 63 6f  values of all.co
1020: 6c 75 6d 6e 73 20 77 69 6c 6c 20 62 65 20 69 6e  lumns will be in
1030: 73 65 72 74 65 64 20 69 6e 74 6f 20 74 68 65 20  serted into the 
1040: 61 72 72 61 79 20 76 61 72 69 61 62 6c 65 20 61  array variable a
1050: 6e 64 20 74 68 65 20 73 63 72 69 70 74 20 77 69  nd the script wi
1060: 6c 6c 0a 62 65 20 65 78 65 63 75 74 65 64 2e 20  ll.be executed. 
1070: 20 46 6f 72 20 69 6e 73 74 61 6e 63 65 3a 3c 2f   For instance:</
1080: 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  p>..<blockquote>
1090: 0a 3c 62 3e 64 62 31 20 65 76 61 6c 20 7b 53 45  .<b>db1 eval {SE
10a0: 4c 45 43 54 20 2a 20 46 52 4f 4d 20 74 31 20 4f  LECT * FROM t1 O
10b0: 52 44 45 52 20 42 59 20 61 7d 20 76 61 6c 75 65  RDER BY a} value
10c0: 73 20 7b 3c 62 72 3e 0a 26 6e 62 73 70 3b 26 6e  s {<br>.&nbsp;&n
10d0: 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b  bsp;&nbsp;&nbsp;
10e0: 70 61 72 72 61 79 20 76 61 6c 75 65 73 3c 62 72  parray values<br
10f0: 3e 0a 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  >.&nbsp;&nbsp;&n
1100: 62 73 70 3b 26 6e 62 73 70 3b 70 75 74 73 20 22  bsp;&nbsp;puts "
1110: 22 3c 62 72 3e 0a 7d 3c 2f 62 3e 0a 3c 2f 62 6c  "<br>.}</b>.</bl
1120: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68  ockquote>..<p>Th
1130: 69 73 20 6c 61 73 74 20 63 6f 64 65 20 77 69 6c  is last code wil
1140: 6c 20 67 69 76 65 20 74 68 65 20 66 6f 6c 6c 6f  l give the follo
1150: 77 69 6e 67 20 6f 75 74 70 75 74 3a 3c 2f 70 3e  wing output:</p>
1160: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 62  ..<blockquote><b
1170: 3e 0a 76 61 6c 75 65 73 28 2a 29 20 3d 20 61 20  >.values(*) = a 
1180: 62 3c 62 72 3e 0a 76 61 6c 75 65 73 28 61 29 20  b<br>.values(a) 
1190: 3d 20 31 3c 62 72 3e 0a 76 61 6c 75 65 73 28 62  = 1<br>.values(b
11a0: 29 20 3d 20 68 65 6c 6c 6f 3c 70 3e 0a 0a 76 61  ) = hello<p>..va
11b0: 6c 75 65 73 28 2a 29 20 3d 20 61 20 62 3c 62 72  lues(*) = a b<br
11c0: 3e 0a 76 61 6c 75 65 73 28 61 29 20 3d 20 32 3c  >.values(a) = 2<
11d0: 62 72 3e 0a 76 61 6c 75 65 73 28 62 29 20 3d 20  br>.values(b) = 
11e0: 67 6f 6f 64 62 79 65 3c 70 3e 0a 0a 76 61 6c 75  goodbye<p>..valu
11f0: 65 73 28 2a 29 20 3d 20 61 20 62 3c 62 72 3e 0a  es(*) = a b<br>.
1200: 76 61 6c 75 65 73 28 61 29 20 3d 20 33 3c 62 72  values(a) = 3<br
1210: 3e 0a 76 61 6c 75 65 73 28 62 29 20 3d 20 68 6f  >.values(b) = ho
1220: 77 64 79 21 3c 2f 62 3e 0a 3c 2f 62 6c 6f 63 6b  wdy!</b>.</block
1230: 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 46 6f 72 20  quote>..<p>.For 
1240: 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 61  each column in a
1250: 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
1260: 6c 74 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lt, the name of 
1270: 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 69 73 20 75  that column.is u
1280: 73 65 64 20 61 73 20 61 6e 20 69 6e 64 65 78 20  sed as an index 
1290: 69 6e 20 74 6f 20 61 72 72 61 79 2e 20 20 54 68  in to array.  Th
12a0: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 63  e value of the c
12b0: 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 0a  olumn is stored.
12c0: 69 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  in the correspon
12d0: 64 69 6e 67 20 61 72 72 61 79 20 65 6e 74 72 79  ding array entry
12e0: 2e 20 20 54 68 65 20 73 70 65 63 69 61 6c 20 61  .  The special a
12f0: 72 72 61 79 20 69 6e 64 65 78 20 2a 20 69 73 0a  rray index * is.
1300: 75 73 65 64 20 74 6f 20 73 74 6f 72 65 20 61 20  used to store a 
1310: 6c 69 73 74 20 6f 66 20 63 6f 6c 75 6d 6e 20 6e  list of column n
1320: 61 6d 65 73 20 69 6e 20 74 68 65 20 6f 72 64 65  ames in the orde
1330: 72 20 74 68 61 74 20 74 68 65 79 20 61 70 70 65  r that they appe
1340: 61 72 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49 66  ar..</p>..<p>.If
1350: 20 74 68 65 20 61 72 72 61 79 20 76 61 72 69 61   the array varia
1360: 62 6c 65 20 6e 61 6d 65 20 69 73 20 6f 6d 69 74  ble name is omit
1370: 74 65 64 20 6f 72 20 69 73 20 74 68 65 20 65 6d  ted or is the em
1380: 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
1390: 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 65 61   the value of.ea
13a0: 63 68 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f  ch column is sto
13b0: 72 65 64 20 69 6e 20 61 20 76 61 72 69 61 62 6c  red in a variabl
13c0: 65 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  e with the same 
13d0: 6e 61 6d 65 20 61 73 20 74 68 65 20 63 6f 6c 75  name as the colu
13e0: 6d 6e 0a 69 74 73 65 6c 66 2e 20 20 46 6f 72 20  mn.itself.  For 
13f0: 65 78 61 6d 70 6c 65 3a 0a 3c 2f 70 3e 0a 0a 3c  example:.</p>..<
1400: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 62 3e 64  blockquote>.<b>d
1410: 62 31 20 65 76 61 6c 20 7b 53 45 4c 45 43 54 20  b1 eval {SELECT 
1420: 2a 20 46 52 4f 4d 20 74 31 20 4f 52 44 45 52 20  * FROM t1 ORDER 
1430: 42 59 20 61 7d 20 7b 3c 62 72 3e 0a 26 6e 62 73  BY a} {<br>.&nbs
1440: 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  p;&nbsp;&nbsp;&n
1450: 62 73 70 3b 70 75 74 73 20 22 61 3d 24 61 20 62  bsp;puts "a=$a b
1460: 3d 24 62 22 3c 62 72 3e 0a 7d 3c 2f 62 3e 0a 3c  =$b"<br>.}</b>.<
1470: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70  /blockquote>..<p
1480: 3e 0a 46 72 6f 6d 20 74 68 69 73 20 77 65 20 67  >.From this we g
1490: 65 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  et the following
14a0: 20 6f 75 74 70 75 74 0a 3c 2f 70 3e 0a 0a 3c 62   output.</p>..<b
14b0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 62 3e 0a 61 3d  lockquote><b>.a=
14c0: 31 20 62 3d 68 65 6c 6c 6f 3c 62 72 3e 0a 61 3d  1 b=hello<br>.a=
14d0: 32 20 62 3d 67 6f 6f 64 62 79 65 3c 62 72 3e 0a  2 b=goodbye<br>.
14e0: 61 3d 33 20 62 3d 68 6f 77 64 79 21 3c 2f 62 3e  a=3 b=howdy!</b>
14f0: 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  .</blockquote>..
1500: 3c 70 3e 0a 54 63 6c 20 76 61 72 69 61 62 6c 65  <p>.Tcl variable
1510: 20 6e 61 6d 65 73 20 63 61 6e 20 61 70 70 65 61   names can appea
1520: 72 20 69 6e 20 74 68 65 20 53 51 4c 20 73 74 61  r in the SQL sta
1530: 74 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 73 65  tement of the se
1540: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 0a 69 6e  cond argument.in
1550: 20 61 6e 79 20 70 6f 73 69 74 69 6f 6e 20 77 68   any position wh
1560: 65 72 65 20 69 74 20 69 73 20 6c 65 67 61 6c 20  ere it is legal 
1570: 74 6f 20 70 75 74 20 61 20 73 74 72 69 6e 67 20  to put a string 
1580: 6f 72 20 6e 75 6d 62 65 72 20 6c 69 74 65 72 61  or number litera
1590: 6c 2e 20 20 54 68 65 0a 76 61 6c 75 65 20 6f 66  l.  The.value of
15a0: 20 74 68 65 20 76 61 72 69 61 62 6c 65 20 69 73   the variable is
15b0: 20 73 75 62 73 74 69 74 75 74 65 64 20 66 6f 72   substituted for
15c0: 20 74 68 65 20 76 61 72 69 61 62 6c 65 20 6e 61   the variable na
15d0: 6d 65 2e 20 20 49 66 20 74 68 65 0a 76 61 72 69  me.  If the.vari
15e0: 61 62 6c 65 20 64 6f 65 73 20 6e 6f 74 20 65 78  able does not ex
15f0: 69 73 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  ist a NULL value
1600: 73 20 69 73 20 75 73 65 64 2e 20 20 46 6f 72 20  s is used.  For 
1610: 65 78 61 6d 70 6c 65 3a 0a 3c 2f 70 3e 0a 0a 3c  example:.</p>..<
1620: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 62 3e 0a 64  blockquote><b>.d
1630: 62 31 20 65 76 61 6c 20 7b 49 4e 53 45 52 54 20  b1 eval {INSERT 
1640: 49 4e 54 4f 20 74 31 20 56 41 4c 55 45 53 28 35  INTO t1 VALUES(5
1650: 2c 24 62 69 67 62 6c 6f 62 29 7d 0a 3c 2f 62 3e  ,$bigblob)}.</b>
1660: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
1670: 70 3e 0a 4e 6f 74 65 20 74 68 61 74 20 69 74 20  p>.Note that it 
1680: 69 73 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  is not necessary
1690: 20 74 6f 20 71 75 6f 74 65 20 74 68 65 20 24 62   to quote the $b
16a0: 69 67 62 6c 6f 62 20 76 61 6c 75 65 2e 20 20 54  igblob value.  T
16b0: 68 61 74 20 68 61 70 70 65 6e 73 0a 61 75 74 6f  hat happens.auto
16c0: 6d 61 74 69 63 61 6c 6c 79 2e 20 20 49 66 20 24  matically.  If $
16d0: 62 69 67 62 6c 6f 62 20 69 73 20 61 20 6c 61 72  bigblob is a lar
16e0: 67 65 20 73 74 72 69 6e 67 20 6f 72 20 62 69 6e  ge string or bin
16f0: 61 72 79 20 6f 62 6a 65 63 74 2c 20 74 68 69 73  ary object, this
1700: 0a 74 65 63 68 6e 69 71 75 65 20 69 73 20 6e 6f  .technique is no
1710: 74 20 6f 6e 6c 79 20 65 61 73 69 65 72 20 74 6f  t only easier to
1720: 20 77 72 69 74 65 2c 20 69 74 20 69 73 20 61 6c   write, it is al
1730: 73 6f 20 6d 75 63 68 20 6d 6f 72 65 20 65 66 66  so much more eff
1740: 69 63 69 65 6e 74 0a 73 69 6e 63 65 20 69 74 20  icient.since it 
1750: 61 76 6f 69 64 73 20 6d 61 6b 69 6e 67 20 61 20  avoids making a 
1760: 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
1770: 65 6e 74 20 6f 66 20 24 62 69 67 62 6c 6f 62 2e  ent of $bigblob.
1780: 0a 3c 2f 70 3e 0a 0a 7d 0a 0a 23 23 23 23 23 23  .</p>..}..######
1790: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
17a0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
17b0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
17c0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
17d0: 23 23 23 23 23 23 23 23 0a 4d 45 54 48 4f 44 20  ########.METHOD 
17e0: 63 6f 6d 70 6c 65 74 65 20 7b 0a 0a 3c 70 3e 0a  complete {..<p>.
17f0: 54 68 65 20 22 63 6f 6d 70 6c 65 74 65 22 20 6d  The "complete" m
1800: 65 74 68 6f 64 20 74 61 6b 65 73 20 61 20 73 74  ethod takes a st
1810: 72 69 6e 67 20 6f 66 20 73 75 70 70 6f 73 65 64  ring of supposed
1820: 20 53 51 4c 20 61 73 20 69 74 73 20 6f 6e 6c 79   SQL as its only
1830: 20 61 72 67 75 6d 65 6e 74 2e 0a 49 74 20 72 65   argument..It re
1840: 74 75 72 6e 73 20 54 52 55 45 20 69 66 20 74 68  turns TRUE if th
1850: 65 20 73 74 72 69 6e 67 20 69 73 20 61 20 63 6f  e string is a co
1860: 6d 70 6c 65 74 65 20 73 74 61 74 65 6d 65 6e 74  mplete statement
1870: 20 6f 66 20 53 51 4c 20 61 6e 64 20 46 41 4c 53   of SQL and FALS
1880: 45 20 69 66 0a 74 68 65 72 65 20 69 73 20 6d 6f  E if.there is mo
1890: 72 65 20 74 6f 20 62 65 20 65 6e 74 65 72 65 64  re to be entered
18a0: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 22 63  .</p>..<p>The "c
18b0: 6f 6d 70 6c 65 74 65 22 20 6d 65 74 68 6f 64 20  omplete" method 
18c0: 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 62  is useful when b
18d0: 75 69 6c 64 69 6e 67 20 69 6e 74 65 72 61 63 74  uilding interact
18e0: 69 76 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ive applications
18f0: 0a 69 6e 20 6f 72 64 65 72 20 74 6f 20 6b 6e 6f  .in order to kno
1900: 77 20 77 68 65 6e 20 74 68 65 20 75 73 65 72 20  w when the user 
1910: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 6e 74  has finished ent
1920: 65 72 69 6e 67 20 61 20 6c 69 6e 65 20 6f 66 20  ering a line of 
1930: 53 51 4c 20 63 6f 64 65 2e 0a 54 68 69 73 20 69  SQL code..This i
1940: 73 20 72 65 61 6c 6c 79 20 6a 75 73 74 20 61 6e  s really just an
1950: 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
1960: 65 20 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6d  e <b>sqlite3_com
1970: 70 6c 65 74 65 28 29 3c 2f 62 3e 20 43 0a 66 75  plete()</b> C.fu
1980: 6e 63 74 69 6f 6e 2e 20 20 52 65 66 65 72 20 74  nction.  Refer t
1990: 6f 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 63  o the <a href="c
19a0: 5f 69 6e 74 65 72 66 61 63 65 2e 68 74 6d 6c 22  _interface.html"
19b0: 3e 43 2f 43 2b 2b 20 69 6e 74 65 72 66 61 63 65  >C/C++ interface
19c0: 3c 2f 61 3e 0a 73 70 65 63 69 66 69 63 61 74 69  </a>.specificati
19d0: 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
19e0: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f  l information.</
19f0: 70 3e 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23 23  p>.}..##########
1a00: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1a10: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1a20: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1a30: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1a40: 23 23 23 23 0a 4d 45 54 48 4f 44 20 63 6f 70 79  ####.METHOD copy
1a50: 20 7b 0a 0a 3c 70 3e 0a 54 68 65 20 22 63 6f 70   {..<p>.The "cop
1a60: 79 22 20 6d 65 74 68 6f 64 20 63 6f 70 69 65 73  y" method copies
1a70: 20 64 61 74 61 20 66 72 6f 6d 20 61 20 66 69 6c   data from a fil
1a80: 65 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 2e 0a  e into a table..
1a90: 49 74 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  It returns the n
1aa0: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 70 72  umber of rows pr
1ab0: 6f 63 65 73 73 65 64 20 73 75 63 63 65 73 73 66  ocessed successf
1ac0: 75 6c 6c 79 20 66 72 6f 6d 20 74 68 65 20 66 69  ully from the fi
1ad0: 6c 65 2e 0a 54 68 65 20 73 79 6e 74 61 78 20 6f  le..The syntax o
1ae0: 66 20 74 68 65 20 63 6f 70 79 20 6d 65 74 68 6f  f the copy metho
1af0: 64 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 74 68 69  d looks like thi
1b00: 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  s:</p>..<blockqu
1b10: 6f 74 65 3e 0a 3c 69 3e 64 62 63 6d 64 3c 2f 69  ote>.<i>dbcmd</i
1b20: 3e 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 62 3e  >&nbsp;&nbsp;<b>
1b30: 63 6f 70 79 3c 2f 62 3e 26 6e 62 73 70 3b 26 6e  copy</b>&nbsp;&n
1b40: 62 73 70 3b 3c 69 3e 63 6f 6e 66 6c 69 63 74 2d  bsp;<i>conflict-
1b50: 61 6c 67 6f 72 69 74 68 6d 3c 2f 69 3e 0a 26 6e  algorithm</i>.&n
1b60: 62 73 70 3b 26 6e 62 73 70 3b 3c 69 3e 74 61 62  bsp;&nbsp;<i>tab
1b70: 6c 65 2d 6e 61 6d 65 26 6e 62 73 70 3b 3c 2f 69  le-name&nbsp;</i
1b80: 3e 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 69 3e  >&nbsp;&nbsp;<i>
1b90: 66 69 6c 65 2d 6e 61 6d 65 26 6e 62 73 70 3b 3c  file-name&nbsp;<
1ba0: 2f 69 3e 0a 26 6e 62 73 70 3b 26 6e 62 73 70 3b  /i>.&nbsp;&nbsp;
1bb0: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3f 3c 69 3e  &nbsp;&nbsp;?<i>
1bc0: 63 6f 6c 75 6d 6e 2d 73 65 70 61 72 61 74 6f 72  column-separator
1bd0: 26 6e 62 73 70 3b 3c 2f 69 3e 3f 0a 26 6e 62 73  &nbsp;</i>?.&nbs
1be0: 70 3b 26 6e 62 73 70 3b 3f 3c 69 3e 6e 75 6c 6c  p;&nbsp;?<i>null
1bf0: 2d 69 6e 64 69 63 61 74 6f 72 3c 2f 69 3e 3f 0a  -indicator</i>?.
1c00: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
1c10: 70 3e 43 6f 6e 66 6c 69 63 74 2d 61 6c 6f 67 72  p>Conflict-alogr
1c20: 69 74 68 6d 20 6d 75 73 74 20 62 65 20 6f 6e 65  ithm must be one
1c30: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 63   of the SQLite c
1c40: 6f 6e 66 6c 69 63 74 20 61 6c 67 6f 72 69 74 68  onflict algorith
1c50: 6d 73 20 66 6f 72 0a 74 68 65 20 49 4e 53 45 52  ms for.the INSER
1c60: 54 20 73 74 61 74 65 6d 65 6e 74 3a 20 3c 69 3e  T statement: <i>
1c70: 72 6f 6c 6c 62 61 63 6b 3c 2f 69 3e 2c 20 3c 69  rollback</i>, <i
1c80: 3e 61 62 6f 72 74 3c 2f 69 3e 2c 0a 3c 69 3e 66  >abort</i>,.<i>f
1c90: 61 69 6c 3c 2f 69 3e 2c 3c 69 3e 69 67 6e 6f 72  ail</i>,<i>ignor
1ca0: 65 3c 2f 69 3e 2c 20 6f 72 20 3c 69 3e 72 65 70  e</i>, or <i>rep
1cb0: 6c 61 63 65 3c 2f 69 3e 2e 20 53 65 65 20 74 68  lace</i>. See th
1cc0: 65 20 53 51 4c 69 74 65 20 4c 61 6e 67 75 61 67  e SQLite Languag
1cd0: 65 0a 73 65 63 74 69 6f 6e 20 66 6f 72 20 3c 61  e.section for <a
1ce0: 20 68 72 65 66 3d 22 6c 61 6e 67 2e 68 74 6d 6c   href="lang.html
1cf0: 23 63 6f 6e 66 6c 69 63 74 22 3e 4f 4e 20 43 4f  #conflict">ON CO
1d00: 4e 46 4c 49 43 54 3c 2f 61 3e 20 66 6f 72 20 6d  NFLICT</a> for m
1d10: 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  ore information.
1d20: 0a 54 68 65 20 63 6f 6e 66 6c 69 63 74 2d 61 6c  .The conflict-al
1d30: 67 6f 72 69 74 68 6d 20 6d 75 73 74 20 62 65 20  gorithm must be 
1d40: 73 70 65 63 69 66 69 65 64 20 69 6e 20 6c 6f 77  specified in low
1d50: 65 72 20 63 61 73 65 2e 0a 3c 2f 70 3e 0a 0a 3c  er case..</p>..<
1d60: 70 3e 54 61 62 6c 65 2d 6e 61 6d 65 20 6d 75 73  p>Table-name mus
1d70: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
1d80: 20 61 73 20 61 20 74 61 62 6c 65 2e 20 20 46 69   as a table.  Fi
1d90: 6c 65 2d 6e 61 6d 65 20 6d 75 73 74 20 65 78 69  le-name must exi
1da0: 73 74 2c 20 61 6e 64 0a 65 61 63 68 20 72 6f 77  st, and.each row
1db0: 20 6d 75 73 74 20 63 6f 6e 74 61 69 6e 20 74 68   must contain th
1dc0: 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66  e same number of
1dd0: 20 63 6f 6c 75 6d 6e 73 20 61 73 20 64 65 66 69   columns as defi
1de0: 6e 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  ned in the table
1df0: 2e 0a 49 66 20 61 20 6c 69 6e 65 20 69 6e 20 74  ..If a line in t
1e00: 68 65 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  he file contains
1e10: 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68   more or less th
1e20: 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  an the number of
1e30: 20 63 6f 6c 75 6d 6e 73 20 64 65 66 69 6e 65 64   columns defined
1e40: 2c 0a 74 68 65 20 63 6f 70 79 20 6d 65 74 68 6f  ,.the copy metho
1e50: 64 20 72 6f 6c 6c 62 61 63 6b 73 20 61 6e 79 20  d rollbacks any 
1e60: 69 6e 73 65 72 74 73 2c 20 61 6e 64 20 72 65 74  inserts, and ret
1e70: 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 3c 2f  urns an error.</
1e80: 70 3e 0a 0a 3c 70 3e 43 6f 6c 75 6d 6e 2d 73 65  p>..<p>Column-se
1e90: 70 61 72 61 74 6f 72 20 69 73 20 61 6e 20 6f 70  parator is an op
1ea0: 74 69 6f 6e 61 6c 20 63 6f 6c 75 6d 6e 20 73 65  tional column se
1eb0: 70 61 72 61 74 6f 72 20 73 74 72 69 6e 67 2e 20  parator string. 
1ec0: 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 73 0a   The default is.
1ed0: 74 68 65 20 41 53 43 49 49 20 74 61 62 20 63 68  the ASCII tab ch
1ee0: 61 72 61 63 74 65 72 20 5c 74 2e 20 3c 2f 70 3e  aracter \t. </p>
1ef0: 0a 0a 3c 70 3e 4e 75 6c 6c 2d 69 6e 64 69 63 61  ..<p>Null-indica
1f00: 74 6f 72 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e  tor is an option
1f10: 61 6c 20 73 74 72 69 6e 67 20 74 68 61 74 20 69  al string that i
1f20: 6e 64 69 63 61 74 65 73 20 61 20 63 6f 6c 75 6d  ndicates a colum
1f30: 6e 20 76 61 6c 75 65 20 69 73 20 6e 75 6c 6c 2e  n value is null.
1f40: 0a 54 68 65 20 64 65 66 61 75 6c 74 20 69 73 20  .The default is 
1f50: 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
1f60: 20 20 4e 6f 74 65 20 74 68 61 74 20 63 6f 6c 75    Note that colu
1f70: 6d 6e 2d 73 65 70 61 72 61 74 6f 72 20 61 6e 64  mn-separator and
1f80: 0a 6e 75 6c 6c 2d 69 6e 64 69 63 61 74 6f 72 20  .null-indicator 
1f90: 61 72 65 20 6f 70 74 69 6f 6e 61 6c 20 70 6f 73  are optional pos
1fa0: 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
1fb0: 73 3b 20 69 66 20 6e 75 6c 6c 2d 69 6e 64 69 63  s; if null-indic
1fc0: 61 74 6f 72 0a 69 73 20 73 70 65 63 69 66 69 65  ator.is specifie
1fd0: 64 2c 20 61 20 63 6f 6c 75 6d 6e 2d 73 65 70 61  d, a column-sepa
1fe0: 72 61 74 6f 72 20 61 72 67 75 6d 65 6e 74 20 6d  rator argument m
1ff0: 75 73 74 20 62 65 20 73 70 65 63 69 66 65 64 20  ust be specifed 
2000: 61 6e 64 0a 70 72 65 63 65 64 65 20 74 68 65 20  and.precede the 
2010: 6e 75 6c 6c 2d 69 6e 64 69 63 61 74 6f 72 20 61  null-indicator a
2020: 72 67 75 6d 65 6e 74 2e 3c 2f 70 3e 0a 0a 3c 70  rgument.</p>..<p
2030: 3e 54 68 65 20 63 6f 70 79 20 6d 65 74 68 6f 64  >The copy method
2040: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 73 69 6d 69   implements simi
2050: 6c 61 72 20 66 75 6e 63 74 69 6f 6e 61 6c 69 74  lar functionalit
2060: 79 20 74 6f 20 74 68 65 20 3c 62 3e 2e 69 6d 70  y to the <b>.imp
2070: 6f 72 74 3c 2f 62 3e 0a 53 51 4c 69 74 65 20 73  ort</b>.SQLite s
2080: 68 65 6c 6c 20 63 6f 6d 6d 61 6e 64 2e 20 0a 54  hell command. .T
2090: 68 65 20 53 51 4c 69 74 65 20 32 2e 78 20 3c 61  he SQLite 2.x <a
20a0: 20 68 72 65 66 3d 22 6c 61 6e 67 2e 68 74 6d 6c   href="lang.html
20b0: 23 63 6f 70 79 22 3e 3c 62 3e 43 4f 50 59 3c 2f  #copy"><b>COPY</
20c0: 62 3e 3c 2f 61 3e 20 73 74 61 74 65 6d 65 6e 74  b></a> statement
20d0: 20 0a 28 75 73 69 6e 67 20 74 68 65 20 50 6f 73   .(using the Pos
20e0: 74 67 72 65 53 51 4c 20 43 4f 50 59 20 66 69 6c  tgreSQL COPY fil
20f0: 65 20 66 6f 72 6d 61 74 29 0a 63 61 6e 20 62 65  e format).can be
2100: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 77 69 74   implemented wit
2110: 68 20 74 68 69 73 20 6d 65 74 68 6f 64 20 61 73  h this method as
2120: 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  :</p>..<blockquo
2130: 74 65 3e 0a 64 62 63 6d 64 26 6e 62 73 70 3b 26  te>.dbcmd&nbsp;&
2140: 6e 62 73 70 3b 63 6f 70 79 26 6e 62 73 70 3b 26  nbsp;copy&nbsp;&
2150: 6e 62 73 70 3b 24 63 6f 6e 66 6c 69 63 74 61 6c  nbsp;$conflictal
2160: 67 6f 0a 26 6e 62 73 70 3b 26 6e 62 73 70 3b 24  go.&nbsp;&nbsp;$
2170: 74 61 62 6c 65 6e 61 6d 65 26 6e 62 73 70 3b 26  tablename&nbsp;&
2180: 6e 62 73 70 3b 26 6e 62 73 70 3b 24 66 69 6c 65  nbsp;&nbsp;$file
2190: 6e 61 6d 65 26 6e 62 73 70 3b 0a 26 6e 62 73 70  name&nbsp;.&nbsp
21a0: 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62  ;&nbsp;&nbsp;&nb
21b0: 73 70 3b 5c 74 26 6e 62 73 70 3b 0a 26 6e 62 73  sp;\t&nbsp;.&nbs
21c0: 70 3b 26 6e 62 73 70 3b 5c 5c 4e 0a 3c 2f 62 6c  p;&nbsp;\\N.</bl
21d0: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 7d 0a 0a 23 23  ockquote>..}..##
21e0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
21f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2200: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2210: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2220: 23 23 23 23 23 23 23 23 23 23 23 23 0a 4d 45 54  ############.MET
2230: 48 4f 44 20 74 69 6d 65 6f 75 74 20 7b 0a 0a 3c  HOD timeout {..<
2240: 70 3e 54 68 65 20 22 74 69 6d 65 6f 75 74 22 20  p>The "timeout" 
2250: 6d 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 74  method is used t
2260: 6f 20 63 6f 6e 74 72 6f 6c 20 68 6f 77 20 6c 6f  o control how lo
2270: 6e 67 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ng the SQLite li
2280: 62 72 61 72 79 0a 77 69 6c 6c 20 77 61 69 74 20  brary.will wait 
2290: 66 6f 72 20 6c 6f 63 6b 73 20 74 6f 20 63 6c 65  for locks to cle
22a0: 61 72 20 62 65 66 6f 72 65 20 67 69 76 69 6e 67  ar before giving
22b0: 20 75 70 20 6f 6e 20 61 20 64 61 74 61 62 61 73   up on a databas
22c0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 0a 54  e transaction..T
22d0: 68 65 20 64 65 66 61 75 6c 74 20 74 69 6d 65 6f  he default timeo
22e0: 75 74 20 69 73 20 30 20 6d 69 6c 6c 69 73 65 63  ut is 0 millisec
22f0: 6f 6e 64 2e 20 20 28 49 6e 20 6f 74 68 65 72 20  ond.  (In other 
2300: 77 6f 72 64 73 2c 20 74 68 65 20 64 65 66 61 75  words, the defau
2310: 6c 74 20 62 65 68 61 76 69 6f 72 0a 69 73 20 6e  lt behavior.is n
2320: 6f 74 20 74 6f 20 77 61 69 74 20 61 74 20 61 6c  ot to wait at al
2330: 6c 2e 29 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20  l.)</p>..<p>The 
2340: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
2350: 61 6c 6c 6f 77 73 20 6d 75 6c 74 69 70 6c 65 20  allows multiple 
2360: 73 69 6d 75 6c 74 61 6e 65 6f 75 73 0a 72 65 61  simultaneous.rea
2370: 64 65 72 73 20 6f 72 20 61 20 73 69 6e 67 6c 65  ders or a single
2380: 20 77 72 69 74 65 72 20 62 75 74 20 6e 6f 74 20   writer but not 
2390: 62 6f 74 68 2e 20 20 49 66 20 61 6e 79 20 70 72  both.  If any pr
23a0: 6f 63 65 73 73 20 69 73 20 77 72 69 74 69 6e 67  ocess is writing
23b0: 20 74 6f 0a 74 68 65 20 64 61 74 61 62 61 73 65   to.the database
23c0: 20 6e 6f 20 6f 74 68 65 72 20 70 72 6f 63 65 73   no other proces
23d0: 73 20 69 73 20 61 6c 6c 6f 77 73 20 74 6f 20 72  s is allows to r
23e0: 65 61 64 20 6f 72 20 77 72 69 74 65 2e 20 20 49  ead or write.  I
23f0: 66 20 61 6e 79 20 70 72 6f 63 65 73 73 0a 69 73  f any process.is
2400: 20 72 65 61 64 69 6e 67 20 74 68 65 20 64 61 74   reading the dat
2410: 61 62 61 73 65 20 6f 74 68 65 72 20 70 72 6f 63  abase other proc
2420: 65 73 73 65 73 20 61 72 65 20 61 6c 6c 6f 77 65  esses are allowe
2430: 64 20 74 6f 20 72 65 61 64 20 62 75 74 20 6e 6f  d to read but no
2440: 74 20 77 72 69 74 65 2e 0a 54 68 65 20 65 6e 74  t write..The ent
2450: 69 72 65 20 64 61 74 61 62 61 73 65 20 73 68 61  ire database sha
2460: 72 65 64 20 61 20 73 69 6e 67 6c 65 20 6c 6f 63  red a single loc
2470: 6b 2e 3c 2f 70 3e 0a 0a 3c 70 3e 57 68 65 6e 20  k.</p>..<p>When 
2480: 53 51 4c 69 74 65 20 74 72 69 65 73 20 74 6f 20  SQLite tries to 
2490: 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  open a database 
24a0: 61 6e 64 20 66 69 6e 64 73 20 74 68 61 74 20 69  and finds that i
24b0: 74 20 69 73 20 6c 6f 63 6b 65 64 2c 20 69 74 0a  t is locked, it.
24c0: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 64  can optionally d
24d0: 65 6c 61 79 20 66 6f 72 20 61 20 73 68 6f 72 74  elay for a short
24e0: 20 77 68 69 6c 65 20 61 6e 64 20 74 72 79 20 74   while and try t
24f0: 6f 20 6f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  o open the file 
2500: 61 67 61 69 6e 2e 0a 54 68 69 73 20 70 72 6f 63  again..This proc
2510: 65 73 73 20 72 65 70 65 61 74 73 20 75 6e 74 69  ess repeats unti
2520: 6c 20 74 68 65 20 71 75 65 72 79 20 74 69 6d 65  l the query time
2530: 73 20 6f 75 74 20 61 6e 64 20 53 51 4c 69 74 65  s out and SQLite
2540: 20 72 65 74 75 72 6e 73 20 61 0a 66 61 69 6c 75   returns a.failu
2550: 72 65 2e 20 20 54 68 65 20 74 69 6d 65 6f 75 74  re.  The timeout
2560: 20 69 73 20 61 64 6a 75 73 74 61 62 6c 65 2e 20   is adjustable. 
2570: 20 49 74 20 69 73 20 73 65 74 20 74 6f 20 30 20   It is set to 0 
2580: 62 79 20 64 65 66 61 75 6c 74 20 73 6f 20 74 68  by default so th
2590: 61 74 0a 69 66 20 74 68 65 20 64 61 74 61 62 61  at.if the databa
25a0: 73 65 20 69 73 20 6c 6f 63 6b 65 64 2c 20 74 68  se is locked, th
25b0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
25c0: 66 61 69 6c 73 20 69 6d 6d 65 64 69 61 74 65 6c  fails immediatel
25d0: 79 2e 20 20 42 75 74 20 79 6f 75 0a 63 61 6e 20  y.  But you.can 
25e0: 75 73 65 20 74 68 65 20 22 74 69 6d 65 6f 75 74  use the "timeout
25f0: 22 20 6d 65 74 68 6f 64 20 74 6f 20 63 68 61 6e  " method to chan
2600: 67 65 20 74 68 65 20 74 69 6d 65 6f 75 74 20 76  ge the timeout v
2610: 61 6c 75 65 20 74 6f 20 61 20 70 6f 73 69 74 69  alue to a positi
2620: 76 65 0a 6e 75 6d 62 65 72 2e 20 20 46 6f 72 20  ve.number.  For 
2630: 65 78 61 6d 70 6c 65 3a 3c 2f 70 3e 0a 0a 3c 62  example:</p>..<b
2640: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 62 3e 64 62 31  lockquote><b>db1
2650: 20 74 69 6d 65 6f 75 74 20 32 30 30 30 3c 2f 62   timeout 2000</b
2660: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  ></blockquote>..
2670: 3c 70 3e 54 68 65 20 61 72 67 75 6d 65 6e 74 20  <p>The argument 
2680: 74 6f 20 74 68 65 20 74 69 6d 65 6f 75 74 20 6d  to the timeout m
2690: 65 74 68 6f 64 20 69 73 20 74 68 65 20 6d 61 78  ethod is the max
26a0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 6d  imum number of m
26b0: 69 6c 6c 69 73 65 63 6f 6e 64 73 0a 74 6f 20 77  illiseconds.to w
26c0: 61 69 74 20 66 6f 72 20 74 68 65 20 6c 6f 63 6b  ait for the lock
26d0: 20 74 6f 20 63 6c 65 61 72 2e 20 20 53 6f 20 69   to clear.  So i
26e0: 6e 20 74 68 65 20 65 78 61 6d 70 6c 65 20 61 62  n the example ab
26f0: 6f 76 65 2c 20 74 68 65 20 6d 61 78 69 6d 75 6d  ove, the maximum
2700: 20 64 65 6c 61 79 0a 77 6f 75 6c 64 20 62 65 20   delay.would be 
2710: 32 20 73 65 63 6f 6e 64 73 2e 3c 2f 70 3e 0a 7d  2 seconds.</p>.}
2720: 0a 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ..##############
2730: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2740: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2750: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2760: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2770: 0a 4d 45 54 48 4f 44 20 62 75 73 79 20 7b 0a 0a  .METHOD busy {..
2780: 3c 70 3e 54 68 65 20 22 62 75 73 79 22 20 6d 65  <p>The "busy" me
2790: 74 68 6f 64 2c 20 6c 69 6b 65 20 22 74 69 6d 65  thod, like "time
27a0: 6f 75 74 22 2c 20 6f 6e 6c 79 20 63 6f 6d 65 73  out", only comes
27b0: 20 69 6e 74 6f 20 70 6c 61 79 20 77 68 65 6e 20   into play when 
27c0: 74 68 65 0a 64 61 74 61 62 61 73 65 20 69 73 20  the.database is 
27d0: 6c 6f 63 6b 65 64 2e 20 20 42 75 74 20 74 68 65  locked.  But the
27e0: 20 22 62 75 73 79 22 20 6d 65 74 68 6f 64 20 67   "busy" method g
27f0: 69 76 65 73 20 74 68 65 20 70 72 6f 67 72 61 6d  ives the program
2800: 6d 65 72 20 6d 75 63 68 20 6d 6f 72 65 0a 63 6f  mer much more.co
2810: 6e 74 72 6f 6c 20 6f 76 65 72 20 77 68 61 74 20  ntrol over what 
2820: 61 63 74 69 6f 6e 20 74 6f 20 74 61 6b 65 2e 20  action to take. 
2830: 20 54 68 65 20 22 62 75 73 79 22 20 6d 65 74 68   The "busy" meth
2840: 6f 64 20 73 70 65 63 69 66 69 65 73 20 61 20 63  od specifies a c
2850: 61 6c 6c 62 61 63 6b 0a 54 63 6c 20 70 72 6f 63  allback.Tcl proc
2860: 65 64 75 72 65 20 74 68 61 74 20 69 73 20 69 6e  edure that is in
2870: 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 53  voked whenever S
2880: 51 4c 69 74 65 20 74 72 69 65 73 20 74 6f 20 6f  QLite tries to o
2890: 70 65 6e 20 61 20 6c 6f 63 6b 65 64 0a 64 61 74  pen a locked.dat
28a0: 61 62 61 73 65 2e 20 20 54 68 69 73 20 63 61 6c  abase.  This cal
28b0: 6c 62 61 63 6b 20 63 61 6e 20 64 6f 20 77 68 61  lback can do wha
28c0: 74 65 76 65 72 20 69 73 20 64 65 73 69 72 65 64  tever is desired
28d0: 2e 20 20 50 72 65 73 75 6d 61 62 6c 79 2c 20 74  .  Presumably, t
28e0: 68 65 0a 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c  he.callback will
28f0: 20 64 6f 20 73 6f 6d 65 20 6f 74 68 65 72 20 75   do some other u
2900: 73 65 66 75 6c 20 77 6f 72 6b 20 66 6f 72 20 61  seful work for a
2910: 20 73 68 6f 72 74 20 77 68 69 6c 65 20 28 73 75   short while (su
2920: 63 68 20 61 73 20 73 65 72 76 69 63 65 0a 47 55  ch as service.GU
2930: 49 20 65 76 65 6e 74 73 29 20 74 68 65 6e 20 72  I events) then r
2940: 65 74 75 72 6e 0a 73 6f 20 74 68 61 74 20 74 68  eturn.so that th
2950: 65 20 6c 6f 63 6b 20 63 61 6e 20 62 65 20 74 72  e lock can be tr
2960: 69 65 64 20 61 67 61 69 6e 2e 20 20 54 68 65 20  ied again.  The 
2970: 63 61 6c 6c 62 61 63 6b 20 70 72 6f 63 65 64 75  callback procedu
2980: 72 65 20 73 68 6f 75 6c 64 0a 72 65 74 75 72 6e  re should.return
2990: 20 22 30 22 20 69 66 20 69 74 20 77 61 6e 74 73   "0" if it wants
29a0: 20 53 51 4c 69 74 65 20 74 6f 20 74 72 79 20 61   SQLite to try a
29b0: 67 61 69 6e 20 74 6f 20 6f 70 65 6e 20 74 68 65  gain to open the
29c0: 20 64 61 74 61 62 61 73 65 20 61 6e 64 0a 73 68   database and.sh
29d0: 6f 75 6c 64 20 72 65 74 75 72 6e 20 22 31 22 20  ould return "1" 
29e0: 69 66 20 69 74 20 77 61 6e 74 73 20 53 51 4c 69  if it wants SQLi
29f0: 74 65 20 74 6f 20 61 62 61 6e 64 6f 6e 20 74 68  te to abandon th
2a00: 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  e current operat
2a10: 69 6f 6e 2e 0a 7d 0a 0a 23 23 23 23 23 23 23 23  ion..}..########
2a20: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2a30: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2a40: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2a50: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2a60: 23 23 23 23 23 23 0a 4d 45 54 48 4f 44 20 6c 61  ######.METHOD la
2a70: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 20  st_insert_rowid 
2a80: 7b 0a 0a 3c 70 3e 54 68 65 20 22 6c 61 73 74 5f  {..<p>The "last_
2a90: 69 6e 73 65 72 74 5f 72 6f 77 69 64 22 20 6d 65  insert_rowid" me
2aa0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 6e 20  thod returns an 
2ab0: 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
2ac0: 20 74 68 65 20 52 4f 57 49 44 0a 6f 66 20 74 68   the ROWID.of th
2ad0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
2ae0: 69 6e 73 65 72 74 65 64 20 64 61 74 61 62 61 73  inserted databas
2af0: 65 20 72 6f 77 2e 3c 2f 70 3e 0a 7d 0a 0a 23 23  e row.</p>.}..##
2b00: 23 23 23 23 23 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 0a 4d 45 54  ############.MET
2b50: 48 4f 44 20 66 75 6e 63 74 69 6f 6e 20 7b 0a 0a  HOD function {..
2b60: 3c 70 3e 54 68 65 20 22 66 75 6e 63 74 69 6f 6e  <p>The "function
2b70: 22 20 6d 65 74 68 6f 64 20 72 65 67 69 73 74 65  " method registe
2b80: 72 73 20 6e 65 77 20 53 51 4c 20 66 75 6e 63 74  rs new SQL funct
2b90: 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 53 51  ions with the SQ
2ba0: 4c 69 74 65 20 65 6e 67 69 6e 65 2e 0a 54 68 65  Lite engine..The
2bb0: 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 74   arguments are t
2bc0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
2bd0: 65 77 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ew SQL function 
2be0: 61 6e 64 20 61 20 54 43 4c 20 63 6f 6d 6d 61 6e  and a TCL comman
2bf0: 64 20 74 68 61 74 0a 69 6d 70 6c 65 6d 65 6e 74  d that.implement
2c00: 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 2e  s that function.
2c10: 20 20 41 72 67 75 6d 65 6e 74 73 20 74 6f 20 74    Arguments to t
2c20: 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  he function are 
2c30: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 65 0a  appended to the.
2c40: 54 43 4c 20 63 6f 6d 6d 61 6e 64 20 62 65 66 6f  TCL command befo
2c50: 72 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64  re it is invoked
2c60: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 66  .</p>..<p>.The f
2c70: 6f 6c 6c 6f 77 69 6e 67 20 65 78 61 6d 70 6c 65  ollowing example
2c80: 20 63 72 65 61 74 65 73 20 61 20 6e 65 77 20 53   creates a new S
2c90: 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65  QL function name
2ca0: 64 20 22 68 65 78 22 20 74 68 61 74 20 63 6f 6e  d "hex" that con
2cb0: 76 65 72 74 73 0a 69 74 73 20 6e 75 6d 65 72 69  verts.its numeri
2cc0: 63 20 61 72 67 75 6d 65 6e 74 20 69 6e 20 74 6f  c argument in to
2cd0: 20 61 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   a hexadecimal e
2ce0: 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 3a 0a 3c  ncoded string:.<
2cf0: 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  /p>..<blockquote
2d00: 3e 3c 62 3e 0a 64 62 20 66 75 6e 63 74 69 6f 6e  ><b>.db function
2d10: 20 68 65 78 20 7b 66 6f 72 6d 61 74 20 30 78 25   hex {format 0x%
2d20: 58 7d 0a 3c 2f 62 3e 3c 2f 62 6c 6f 63 6b 71 75  X}.</b></blockqu
2d30: 6f 74 65 3e 0a 0a 7d 0a 0a 23 23 23 23 23 23 23  ote>..}..#######
2d40: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2d50: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2d60: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2d70: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2d80: 23 23 23 23 23 23 23 0a 4d 45 54 48 4f 44 20 6f  #######.METHOD o
2d90: 6e 65 63 6f 6c 75 6d 6e 20 7b 0a 0a 3c 70 3e 54  necolumn {..<p>T
2da0: 68 65 20 22 6f 6e 65 63 6f 6c 75 6d 6e 22 20 6d  he "onecolumn" m
2db0: 65 74 68 6f 64 20 77 6f 72 6b 73 20 6c 69 6b 65  ethod works like
2dc0: 20 22 65 76 61 6c 22 20 69 6e 20 74 68 61 74 20   "eval" in that 
2dd0: 69 74 20 65 76 61 6c 75 61 74 65 73 20 74 68 65  it evaluates the
2de0: 0a 53 51 4c 20 71 75 65 72 79 20 73 74 61 74 65  .SQL query state
2df0: 6d 65 6e 74 20 67 69 76 65 6e 20 61 73 20 69 74  ment given as it
2e00: 73 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65  s argument.  The
2e10: 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 74   difference is t
2e20: 68 61 74 0a 22 6f 6e 65 63 6f 6c 75 6d 6e 22 20  hat."onecolumn" 
2e30: 72 65 74 75 72 6e 73 20 61 20 73 69 6e 67 6c 65  returns a single
2e40: 20 65 6c 65 6d 65 6e 74 20 77 68 69 63 68 20 69   element which i
2e50: 73 20 74 68 65 20 66 69 72 73 74 20 63 6f 6c 75  s the first colu
2e60: 6d 6e 20 6f 66 20 74 68 65 0a 66 69 72 73 74 20  mn of the.first 
2e70: 72 6f 77 20 6f 66 20 74 68 65 20 71 75 65 72 79  row of the query
2e80: 20 72 65 73 75 6c 74 2e 3c 2f 70 3e 0a 0a 3c 70   result.</p>..<p
2e90: 3e 54 68 69 73 20 69 73 20 61 20 63 6f 6e 76 65  >This is a conve
2ea0: 6e 69 65 6e 63 65 20 6d 65 74 68 6f 64 2e 20 20  nience method.  
2eb0: 49 74 20 73 61 76 65 73 20 74 68 65 20 75 73 65  It saves the use
2ec0: 72 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f  r from having to
2ed0: 0a 64 6f 20 61 20 22 3c 74 74 3e 5b 6c 69 6e 64  .do a "<tt>[lind
2ee0: 65 78 26 6e 62 73 70 3b 2e 2e 2e 26 6e 62 73 70  ex&nbsp;...&nbsp
2ef0: 3b 30 5d 3c 2f 74 74 3e 22 20 6f 6e 20 74 68 65  ;0]</tt>" on the
2f00: 20 72 65 73 75 6c 74 73 20 6f 66 20 61 6e 20 22   results of an "
2f10: 65 76 61 6c 22 0a 69 6e 20 6f 72 64 65 72 20 74  eval".in order t
2f20: 6f 20 65 78 74 72 61 63 74 20 61 20 73 69 6e 67  o extract a sing
2f30: 6c 65 20 63 6f 6c 75 6d 6e 20 72 65 73 75 6c 74  le column result
2f40: 2e 3c 2f 70 3e 0a 7d 0a 0a 23 23 23 23 23 23 23  .</p>.}..#######
2f50: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2f60: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2f70: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2f80: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2f90: 23 23 23 23 23 23 23 0a 4d 45 54 48 4f 44 20 63  #######.METHOD c
2fa0: 68 61 6e 67 65 73 20 7b 0a 0a 3c 70 3e 54 68 65  hanges {..<p>The
2fb0: 20 22 63 68 61 6e 67 65 73 22 20 6d 65 74 68 6f   "changes" metho
2fc0: 64 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  d returns an int
2fd0: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74 68  eger which is th
2fe0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
2ff0: 0a 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  .in the database
3000: 20 74 68 61 74 20 77 65 72 65 20 69 6e 73 65 72   that were inser
3010: 74 65 64 2c 20 64 65 6c 65 74 65 64 2c 20 61 6e  ted, deleted, an
3020: 64 2f 6f 72 20 6d 6f 64 69 66 69 65 64 20 62 79  d/or modified by
3030: 20 74 68 65 20 6d 6f 73 74 0a 72 65 63 65 6e 74   the most.recent
3040: 20 22 65 76 61 6c 22 20 6d 65 74 68 6f 64 2e 3c   "eval" method.<
3050: 2f 70 3e 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23  /p>.}..#########
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 23 23 23 23 23 23 23 23 23  ################
30a0: 23 23 23 23 23 0a 4d 45 54 48 4f 44 20 74 6f 74  #####.METHOD tot
30b0: 61 6c 5f 63 68 61 6e 67 65 73 20 7b 0a 0a 3c 70  al_changes {..<p
30c0: 3e 54 68 65 20 22 74 6f 74 61 6c 5f 63 68 61 6e  >The "total_chan
30d0: 67 65 73 22 20 6d 65 74 68 6f 64 20 72 65 74 75  ges" method retu
30e0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
30f0: 68 69 63 68 20 69 73 20 74 68 65 20 6e 75 6d 62  hich is the numb
3100: 65 72 20 6f 66 20 72 6f 77 73 0a 69 6e 20 74 68  er of rows.in th
3110: 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 20  e database that 
3120: 77 65 72 65 20 69 6e 73 65 72 74 65 64 2c 20 64  were inserted, d
3130: 65 6c 65 74 65 64 2c 20 61 6e 64 2f 6f 72 20 6d  eleted, and/or m
3140: 6f 64 69 66 69 65 64 20 73 69 6e 63 65 20 74 68  odified since th
3150: 65 0a 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e.current databa
3160: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61  se connection wa
3170: 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 3c  s first opened.<
3180: 2f 70 3e 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23  /p>.}..#########
3190: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
31a0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
31b0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
31c0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
31d0: 23 23 23 23 23 0a 4d 45 54 48 4f 44 20 61 75 74  #####.METHOD aut
31e0: 68 6f 72 69 7a 65 72 20 7b 0a 0a 3c 70 3e 54 68  horizer {..<p>Th
31f0: 65 20 22 61 75 74 68 6f 72 69 7a 65 72 22 20 6d  e "authorizer" m
3200: 65 74 68 6f 64 20 70 72 6f 76 69 64 65 73 20 61  ethod provides a
3210: 63 63 65 73 73 20 74 6f 20 74 68 65 20 73 71 6c  ccess to the sql
3220: 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
3230: 7a 65 72 0a 43 2f 43 2b 2b 20 69 6e 74 65 72 66  zer.C/C++ interf
3240: 61 63 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ace.  The argume
3250: 6e 74 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 72  nt to authorizer
3260: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
3270: 61 20 70 72 6f 63 65 64 75 72 65 20 74 68 61 74  a procedure that
3280: 0a 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20  .is called when 
3290: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
32a0: 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
32b0: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 75  d in order to au
32c0: 74 68 6f 72 69 7a 65 0a 63 65 72 74 61 69 6e 20  thorize.certain 
32d0: 6f 70 65 72 61 74 69 6f 6e 73 2e 20 20 54 68 65  operations.  The
32e0: 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 63 65 64   callback proced
32f0: 75 72 65 20 74 61 6b 65 73 20 35 20 61 72 67 75  ure takes 5 argu
3300: 6d 65 6e 74 73 20 77 68 69 63 68 20 64 65 73 63  ments which desc
3310: 72 69 62 65 0a 74 68 65 20 6f 70 65 72 61 74 69  ribe.the operati
3320: 6f 6e 20 62 65 69 6e 67 20 63 6f 64 65 64 2e 20  on being coded. 
3330: 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
3340: 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 65 78   returns the tex
3350: 74 20 73 74 72 69 6e 67 0a 22 53 51 4c 49 54 45  t string."SQLITE
3360: 5f 4f 4b 22 2c 20 74 68 65 6e 20 74 68 65 20 6f  _OK", then the o
3370: 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f  peration is allo
3380: 77 65 64 2e 20 20 49 66 20 69 74 20 72 65 74 75  wed.  If it retu
3390: 72 6e 73 20 22 53 51 4c 49 54 45 5f 49 47 4e 4f  rns "SQLITE_IGNO
33a0: 52 45 22 2c 0a 74 68 65 6e 20 74 68 65 20 6f 70  RE",.then the op
33b0: 65 72 61 74 69 6f 6e 20 69 73 20 73 69 6c 65 6e  eration is silen
33c0: 74 6c 79 20 64 69 73 61 62 6c 65 64 2e 20 20 49  tly disabled.  I
33d0: 66 20 74 68 65 20 72 65 74 75 72 6e 20 69 73 20  f the return is 
33e0: 22 53 51 4c 49 54 45 5f 44 45 4e 59 22 0a 74 68  "SQLITE_DENY".th
33f0: 65 6e 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  en the compilati
3400: 6f 6e 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  on fails with an
3410: 20 65 72 72 6f 72 2e 0a 3c 2f 70 3e 0a 0a 3c 70   error..</p>..<p
3420: 3e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  >If the argument
3430: 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
3440: 69 6e 67 20 74 68 65 6e 20 74 68 65 20 61 75 74  ing then the aut
3450: 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
3460: 6c 65 64 2e 0a 49 66 20 74 68 65 20 61 72 67 75  led..If the argu
3470: 6d 65 6e 74 20 69 73 20 6f 6d 69 74 74 65 64 2c  ment is omitted,
3480: 20 74 68 65 6e 20 74 68 65 20 63 75 72 72 65 6e   then the curren
3490: 74 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  t authorizer is 
34a0: 72 65 74 75 72 6e 65 64 2e 3c 2f 70 3e 0a 7d 0a  returned.</p>.}.
34b0: 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  .###############
34c0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
34d0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
34e0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
34f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a  ###############.
3500: 4d 45 54 48 4f 44 20 70 72 6f 67 72 65 73 73 20  METHOD progress 
3510: 7b 0a 0a 3c 70 3e 54 68 69 73 20 6d 65 74 68 6f  {..<p>This metho
3520: 64 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  d registers a ca
3530: 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20 69  llback that is i
3540: 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
3550: 6c 6c 79 20 64 75 72 69 6e 67 0a 71 75 65 72 79  lly during.query
3560: 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68   processing.  Th
3570: 65 72 65 20 61 72 65 20 74 77 6f 20 61 72 67 75  ere are two argu
3580: 6d 65 6e 74 73 3a 20 74 68 65 20 6e 75 6d 62 65  ments: the numbe
3590: 72 20 6f 66 20 53 51 4c 69 74 65 20 76 69 72 74  r of SQLite virt
35a0: 75 61 6c 0a 6d 61 63 68 69 6e 65 20 6f 70 63 6f  ual.machine opco
35b0: 64 65 73 20 62 65 74 77 65 65 6e 20 69 6e 76 6f  des between invo
35c0: 63 61 74 69 6f 6e 73 2c 20 61 6e 64 20 74 68 65  cations, and the
35d0: 20 54 43 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20   TCL command to 
35e0: 69 6e 76 6f 6b 65 2e 0a 53 65 74 74 69 6e 67 20  invoke..Setting 
35f0: 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
3600: 6c 62 61 63 6b 20 74 6f 20 61 6e 20 65 6d 70 74  lback to an empt
3610: 79 20 73 74 72 69 6e 67 20 64 69 73 61 62 6c 65  y string disable
3620: 73 20 69 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68  s it.</p>..<p>Th
3630: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
3640: 61 63 6b 20 63 61 6e 20 62 65 20 75 73 65 64 20  ack can be used 
3650: 74 6f 20 64 69 73 70 6c 61 79 20 74 68 65 20 73  to display the s
3660: 74 61 74 75 73 20 6f 66 20 61 20 6c 65 6e 67 74  tatus of a lengt
3670: 68 79 0a 71 75 65 72 79 20 6f 72 20 74 6f 20 70  hy.query or to p
3680: 72 6f 63 65 73 73 20 47 55 49 20 65 76 65 6e 74  rocess GUI event
3690: 73 20 64 75 72 69 6e 67 20 61 20 6c 65 6e 67 74  s during a lengt
36a0: 68 79 20 71 75 65 72 79 2e 3c 2f 70 3e 0a 7d 0a  hy query.</p>.}.
36b0: 0a 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ..##############
36c0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
36d0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
36e0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
36f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3700: 0a 4d 45 54 48 4f 44 20 63 6f 6c 6c 61 74 65 20  .METHOD collate 
3710: 7b 0a 0a 3c 70 3e 54 68 69 73 20 6d 65 74 68 6f  {..<p>This metho
3720: 64 20 72 65 67 69 73 74 65 72 73 20 6e 65 77 20  d registers new 
3730: 74 65 78 74 20 63 6f 6c 6c 61 74 69 6e 67 20 73  text collating s
3740: 65 71 75 65 6e 63 65 73 2e 20 20 54 68 65 72 65  equences.  There
3750: 20 61 72 65 0a 74 77 6f 20 61 72 67 75 6d 65 6e   are.two argumen
3760: 74 73 3a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ts: the name of 
3770: 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65  the collating se
3780: 71 75 65 6e 63 65 20 61 6e 64 20 74 68 65 20 6e  quence and the n
3790: 61 6d 65 20 6f 66 20 61 0a 54 43 4c 20 70 72 6f  ame of a.TCL pro
37a0: 63 65 64 75 72 65 20 74 68 61 74 20 69 6d 70 6c  cedure that impl
37b0: 65 6d 65 6e 74 73 20 61 20 63 6f 6d 70 61 72 69  ements a compari
37c0: 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72  son function for
37d0: 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 0a 73   the collating.s
37e0: 65 71 75 65 6e 63 65 2e 0a 3c 2f 70 3e 0a 0a 3c  equence..</p>..<
37f0: 70 3e 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  p>For example, t
3800: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 64  he following cod
3810: 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 61 20 63  e implements a c
3820: 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63  ollating sequenc
3830: 65 20 63 61 6c 6c 65 64 0a 22 4e 4f 43 41 53 45  e called."NOCASE
3840: 22 20 74 68 61 74 20 73 6f 72 74 73 20 69 6e 20  " that sorts in 
3850: 74 65 78 74 20 6f 72 64 65 72 20 77 69 74 68 6f  text order witho
3860: 75 74 20 72 65 67 61 72 64 20 74 6f 20 63 61 73  ut regard to cas
3870: 65 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71  e:.</p>..<blockq
3880: 75 6f 74 65 3e 3c 62 3e 0a 70 72 6f 63 20 6e 6f  uote><b>.proc no
3890: 63 61 73 65 5f 63 6f 6d 70 61 72 65 20 7b 61 20  case_compare {a 
38a0: 62 7d 20 7b 3c 62 72 3e 0a 26 6e 62 73 70 3b 26  b} {<br>.&nbsp;&
38b0: 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70  nbsp;&nbsp;&nbsp
38c0: 3b 72 65 74 75 72 6e 20 5b 73 74 72 69 6e 67 20  ;return [string 
38d0: 63 6f 6d 70 61 72 65 20 5b 73 74 72 69 6e 67 20  compare [string 
38e0: 74 6f 6c 6f 77 65 72 20 24 61 5d 20 5b 73 74 72  tolower $a] [str
38f0: 69 6e 67 20 74 6f 6c 6f 77 65 72 20 24 62 5d 5d  ing tolower $b]]
3900: 3c 62 72 3e 0a 7d 3c 62 72 3e 0a 64 62 20 63 6f  <br>.}<br>.db co
3910: 6c 6c 61 74 65 20 4e 4f 43 41 53 45 20 6e 6f 63  llate NOCASE noc
3920: 61 73 65 5f 63 6f 6d 70 61 72 65 3c 62 72 3e 0a  ase_compare<br>.
3930: 3c 2f 62 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  </b></blockquote
3940: 3e 0a 7d 0a 0a 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 23 23 23 23 23 23 23 23 23 23 23 23  ################
3990: 23 23 23 0a 4d 45 54 48 4f 44 20 63 6f 6c 6c 61  ###.METHOD colla
39a0: 74 69 6f 6e 5f 6e 65 65 64 65 64 20 7b 0a 0a 3c  tion_needed {..<
39b0: 70 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 72 65  p>This method re
39c0: 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
39d0: 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
39e0: 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
39f0: 74 68 65 20 53 51 4c 69 74 65 0a 65 6e 67 69 6e  the SQLite.engin
3a00: 65 20 6e 65 65 64 73 20 61 20 70 61 72 74 69 63  e needs a partic
3a10: 75 6c 61 72 20 63 6f 6c 6c 61 74 69 6e 67 20 73  ular collating s
3a20: 65 71 75 65 6e 63 65 20 62 75 74 20 64 6f 65 73  equence but does
3a30: 20 6e 6f 74 20 68 61 76 65 20 74 68 61 74 0a 63   not have that.c
3a40: 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63  ollating sequenc
3a50: 65 20 72 65 67 69 73 74 65 72 65 64 2e 20 20 54  e registered.  T
3a60: 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20  he callback can 
3a70: 72 65 67 69 73 74 65 72 20 74 68 65 20 63 6f 6c  register the col
3a80: 6c 61 74 69 6e 67 0a 73 65 71 75 65 6e 63 65 2e  lating.sequence.
3a90: 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69    The callback i
3aa0: 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
3ab0: 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
3ac0: 72 20 77 68 69 63 68 20 69 73 20 74 68 65 0a 6e  r which is the.n
3ad0: 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 65 64 65  ame of the neede
3ae0: 64 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75  d collating sequ
3af0: 65 6e 63 65 2e 3c 2f 70 3e 0a 7d 0a 0a 23 23 23  ence.</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 23 0a 4d 45 54 48  ###########.METH
3b50: 4f 44 20 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 20 7b  OD commit_hook {
3b60: 0a 0a 3c 70 3e 54 68 69 73 20 6d 65 74 68 6f 64  ..<p>This method
3b70: 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
3b80: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
3b90: 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6a 75  at is invoked ju
3ba0: 73 74 20 62 65 66 6f 72 65 0a 53 51 4c 69 74 65  st before.SQLite
3bb0: 20 74 72 69 65 73 20 74 6f 20 63 6f 6d 6d 69 74   tries to commit
3bc0: 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 64 61   changes to a da
3bd0: 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
3be0: 63 61 6c 6c 62 61 63 6b 20 74 68 72 6f 77 73 0a  callback throws.
3bf0: 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 6f 72 20  an exception or 
3c00: 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
3c10: 72 6f 20 72 65 73 75 6c 74 2c 20 74 68 65 6e 20  ro result, then 
3c20: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
3c30: 72 6f 6c 6c 73 20 62 61 63 6b 0a 72 61 74 68 65  rolls back.rathe
3c40: 72 20 74 68 61 6e 20 63 6f 6d 6d 69 74 2e 3c 2f  r than commit.</
3c50: 70 3e 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23 23  p>.}..##########
3c60: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3c70: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3c80: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3c90: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3ca0: 23 23 23 23 0a 4d 45 54 48 4f 44 20 65 72 72 6f  ####.METHOD erro
3cb0: 72 63 6f 64 65 20 7b 0a 0a 3c 70 3e 54 68 69 73  rcode {..<p>This
3cc0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
3cd0: 74 68 65 20 6e 75 6d 65 72 69 63 20 65 72 72 6f  the numeric erro
3ce0: 72 20 63 6f 64 65 20 74 68 61 74 20 72 65 73 75  r code that resu
3cf0: 6c 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6d 6f  lted from the mo
3d00: 73 74 0a 72 65 63 65 6e 74 20 53 51 4c 69 74 65  st.recent SQLite
3d10: 20 6f 70 65 72 61 74 69 6f 6e 2e 3c 2f 70 3e 0a   operation.</p>.
3d20: 7d 0a 0a 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 23  ################
3d70: 23 0a 4d 45 54 48 4f 44 20 74 72 61 63 65 20 7b  #.METHOD trace {
3d80: 0a 0a 3c 70 3e 54 68 65 20 22 74 72 61 63 65 22  ..<p>The "trace"
3d90: 20 6d 65 74 68 6f 64 20 72 65 67 69 73 74 65 72   method register
3da0: 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 74 68 61  s a callback tha
3db0: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  t is invoked as 
3dc0: 65 61 63 68 20 53 51 4c 0a 73 74 61 74 65 6d 65  each SQL.stateme
3dd0: 6e 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 2e 20  nt is compiled. 
3de0: 20 54 68 65 20 74 65 78 74 20 6f 66 20 74 68 65   The text of the
3df0: 20 53 51 4c 20 69 73 20 61 70 70 65 6e 64 65 64   SQL is appended
3e00: 20 61 73 20 61 20 73 69 6e 67 6c 65 20 73 74 72   as a single str
3e10: 69 6e 67 0a 74 6f 20 74 68 65 20 63 6f 6d 6d 61  ing.to the comma
3e20: 6e 64 20 62 65 66 6f 72 65 20 69 74 20 69 73 20  nd before it is 
3e30: 69 6e 76 6f 6b 65 64 2e 20 20 54 68 69 73 20 63  invoked.  This c
3e40: 61 6e 20 62 65 20 75 73 65 64 20 28 66 6f 72 20  an be used (for 
3e50: 65 78 61 6d 70 6c 65 29 20 74 6f 0a 6b 65 65 70  example) to.keep
3e60: 20 61 20 6c 6f 67 20 6f 66 20 61 6c 6c 20 53 51   a log of all SQ
3e70: 4c 20 6f 70 65 72 61 74 69 6f 6e 73 20 74 68 61  L operations tha
3e80: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
3e90: 20 70 65 72 66 6f 72 6d 73 2e 0a 3c 2f 70 3e 0a   performs..</p>.
3ea0: 7d 0a 0a 0a 66 6f 6f 74 65 72 20 24 72 63 73 69  }...footer $rcsi
3eb0: 64 0a                                            d.