/ Hex Artifact Content
Login

Artifact b9271d44dcf147a93c98f8ecf28c927307abd6da:


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 38 20 32 30 30 33 2f 30 38 2f 31 39 20 31 34  .8 2003/08/19 14
0070: 3a 33 31 3a 30 32 20 64 72 68 20 45 78 70 20 24  :31:02 drh Exp $
0080: 7d 0a 0a 70 75 74 73 20 7b 3c 68 74 6d 6c 3e 0a  }..puts {<html>.
0090: 3c 68 65 61 64 3e 0a 20 20 3c 74 69 74 6c 65 3e  <head>.  <title>
00a0: 54 68 65 20 54 63 6c 20 69 6e 74 65 72 66 61 63  The Tcl interfac
00b0: 65 20 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20  e to the SQLite 
00c0: 6c 69 62 72 61 72 79 3c 2f 74 69 74 6c 65 3e 0a  library</title>.
00d0: 3c 2f 68 65 61 64 3e 0a 3c 62 6f 64 79 20 62 67  </head>.<body bg
00e0: 63 6f 6c 6f 72 3d 77 68 69 74 65 3e 0a 3c 68 31  color=white>.<h1
00f0: 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 3e 0a 54   align=center>.T
0100: 68 65 20 54 63 6c 20 69 6e 74 65 72 66 61 63 65  he Tcl interface
0110: 20 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   to the SQLite l
0120: 69 62 72 61 72 79 0a 3c 2f 68 31 3e 7d 0a 70 75  ibrary.</h1>}.pu
0130: 74 73 20 22 3c 70 20 61 6c 69 67 6e 3d 63 65 6e  ts "<p align=cen
0140: 74 65 72 3e 0a 28 54 68 69 73 20 70 61 67 65 20  ter>.(This page 
0150: 77 61 73 20 6c 61 73 74 20 6d 6f 64 69 66 69 65  was last modifie
0160: 64 20 6f 6e 20 5b 6c 72 61 6e 67 65 20 24 72 63  d on [lrange $rc
0170: 73 69 64 20 33 20 34 5d 20 55 54 43 29 0a 3c 2f  sid 3 4] UTC).</
0180: 70 3e 22 0a 0a 70 75 74 73 20 7b 0a 3c 70 3e 54  p>"..puts {.<p>T
0190: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01a0: 79 20 69 73 20 64 65 73 69 67 6e 65 64 20 74 6f  y is designed to
01b0: 20 62 65 20 76 65 72 79 20 65 61 73 79 20 74 6f   be very easy to
01c0: 20 75 73 65 20 66 72 6f 6d 0a 61 20 54 63 6c 20   use from.a Tcl 
01d0: 6f 72 20 54 63 6c 2f 54 6b 20 73 63 72 69 70 74  or Tcl/Tk script
01e0: 2e 20 20 54 68 69 73 20 64 6f 63 75 6d 65 6e 74  .  This document
01f0: 20 67 69 76 65 73 20 61 6e 20 6f 76 65 72 76 69   gives an overvi
0200: 65 77 20 6f 66 20 74 68 65 20 54 63 6c 0a 70 72  ew of the Tcl.pr
0210: 6f 67 72 61 6d 6d 69 6e 67 20 69 6e 74 65 72 66  ogramming interf
0220: 61 63 65 2e 3c 2f 70 3e 0a 0a 3c 68 32 3e 54 68  ace.</p>..<h2>Th
0230: 65 20 41 50 49 3c 2f 68 32 3e 0a 0a 3c 70 3e 54  e API</h2>..<p>T
0240: 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
0250: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
0260: 72 79 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 73  ry consists of s
0270: 69 6e 67 6c 65 0a 74 63 6c 20 63 6f 6d 6d 61 6e  ingle.tcl comman
0280: 64 20 6e 61 6d 65 64 20 3c 62 3e 73 71 6c 69 74  d named <b>sqlit
0290: 65 3c 2f 62 3e 2e 20 20 42 65 63 61 75 73 65 20  e</b>.  Because 
02a0: 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 74 68  there is only th
02b0: 69 73 0a 6f 6e 65 20 69 6e 74 65 72 66 61 63 65  is.one interface
02c0: 20 63 6f 6d 6d 61 6e 64 2c 20 74 68 65 20 69 6e   command, the in
02d0: 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 70  terface is not p
02e0: 6c 61 63 65 64 20 69 6e 20 61 20 73 65 70 61 72  laced in a separ
02f0: 61 74 65 0a 6e 61 6d 65 73 70 61 63 65 2e 3c 2f  ate.namespace.</
0300: 70 3e 0a 0a 3c 70 3e 54 68 65 20 3c 62 3e 73 71  p>..<p>The <b>sq
0310: 6c 69 74 65 3c 2f 62 3e 20 63 6f 6d 6d 61 6e 64  lite</b> command
0320: 20 69 73 20 75 73 65 64 20 61 73 20 66 6f 6c 6c   is used as foll
0330: 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b  ows:</p>..<block
0340: 71 75 6f 74 65 3e 0a 3c 62 3e 73 71 6c 69 74 65  quote>.<b>sqlite
0350: 3c 2f 62 3e 26 6e 62 73 70 3b 26 6e 62 73 70 3b  </b>&nbsp;&nbsp;
0360: 3c 69 3e 64 62 63 6d 64 26 6e 62 73 70 3b 26 6e  <i>dbcmd&nbsp;&n
0370: 62 73 70 3b 64 61 74 61 62 61 73 65 2d 6e 61 6d  bsp;database-nam
0380: 65 3c 2f 69 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f  e</i>.</blockquo
0390: 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65 20 3c 62 3e  te>..<p>.The <b>
03a0: 73 71 6c 69 74 65 3c 2f 62 3e 20 63 6f 6d 6d 61  sqlite</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 3c 2f 62 3e 20 63 6f 6d 6d  >sqlite</b> comm
0440: 61 6e 64 20 61 6c 73 6f 20 63 72 65 61 74 65 73  and also creates
0450: 20 61 20 6e 65 77 20 54 63 6c 0a 63 6f 6d 6d 61   a new Tcl.comma
0460: 6e 64 20 74 6f 20 63 6f 6e 74 72 6f 6c 20 74 68  nd to control th
0470: 65 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 65  e database.  The
0480: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77   name of the new
0490: 20 54 63 6c 20 63 6f 6d 6d 61 6e 64 0a 69 73 20   Tcl command.is 
04a0: 67 69 76 65 6e 20 62 79 20 74 68 65 20 66 69 72  given by the fir
04b0: 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  st argument.  Th
04c0: 69 73 20 61 70 70 72 6f 61 63 68 20 69 73 20 73  is approach is s
04d0: 69 6d 69 6c 61 72 20 74 6f 20 74 68 65 0a 77 61  imilar to the.wa
04e0: 79 20 77 69 64 67 65 74 73 20 61 72 65 20 63 72  y widgets are cr
04f0: 65 61 74 65 64 20 69 6e 20 54 6b 2e 0a 3c 2f 70  eated in Tk..</p
0500: 3e 0a 0a 3c 70 3e 0a 54 68 65 20 6e 61 6d 65 20  >..<p>.The name 
0510: 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
0520: 69 73 20 6a 75 73 74 20 74 68 65 20 6e 61 6d 65  is just the name
0530: 20 6f 66 20 61 20 64 69 73 6b 20 66 69 6c 65 20   of a disk file 
0540: 69 6e 20 77 68 69 63 68 0a 74 68 65 20 64 61 74  in which.the dat
0550: 61 62 61 73 65 20 69 73 20 73 74 6f 72 65 64 2e  abase is stored.
0560: 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 4f 6e 63 65 20  .</p>..<p>.Once 
0570: 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
0580: 73 65 20 69 73 20 6f 70 65 6e 2c 20 69 74 20 63  se is open, it c
0590: 61 6e 20 62 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  an be controlled
05a0: 20 75 73 69 6e 67 20 0a 6d 65 74 68 6f 64 73 20   using .methods 
05b0: 6f 66 20 74 68 65 20 3c 69 3e 64 62 63 6d 64 3c  of the <i>dbcmd<
05c0: 2f 69 3e 2e 20 20 54 68 65 72 65 20 61 72 65 20  /i>.  There are 
05d0: 63 75 72 72 65 6e 74 6c 79 20 37 20 6d 65 74 68  currently 7 meth
05e0: 6f 64 73 0a 64 65 66 69 6e 65 64 3a 3c 2f 70 3e  ods.defined:</p>
05f0: 0a 0a 3c 70 3e 0a 3c 75 6c 3e 0a 3c 6c 69 3e 20  ..<p>.<ul>.<li> 
0600: 62 75 73 79 0a 3c 6c 69 3e 20 63 68 61 6e 67 65  busy.<li> change
0610: 73 0a 3c 6c 69 3e 20 63 6c 6f 73 65 0a 3c 6c 69  s.<li> close.<li
0620: 3e 20 63 6f 6d 70 6c 65 74 65 0a 3c 6c 69 3e 20  > complete.<li> 
0630: 65 76 61 6c 0a 3c 6c 69 3e 20 6c 61 73 74 5f 69  eval.<li> last_i
0640: 6e 73 65 72 74 5f 72 6f 77 69 64 0a 3c 6c 69 3e  nsert_rowid.<li>
0650: 20 6f 6e 65 63 6f 6c 75 6d 6e 0a 3c 6c 69 3e 20   onecolumn.<li> 
0660: 74 69 6d 65 6f 75 74 0a 3c 2f 75 6c 3e 0a 3c 2f  timeout.</ul>.</
0670: 70 3e 0a 0a 3c 70 3e 57 65 20 77 69 6c 6c 20 65  p>..<p>We will e
0680: 78 70 6c 61 69 6e 20 61 6c 6c 20 6f 66 20 74 68  xplain all of th
0690: 65 73 65 20 6d 65 74 68 6f 64 73 2c 20 74 68 6f  ese methods, tho
06a0: 75 67 68 20 6e 6f 74 20 69 6e 20 74 68 61 74 20  ugh not in that 
06b0: 6f 72 64 65 72 2e 0a 57 65 20 77 69 6c 6c 20 62  order..We will b
06c0: 65 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  e begin with the
06d0: 20 22 63 6c 6f 73 65 22 20 6d 65 74 68 6f 64 2e   "close" method.
06e0: 3c 2f 70 3e 0a 0a 3c 68 32 3e 54 68 65 20 22 63  </p>..<h2>The "c
06f0: 6c 6f 73 65 22 20 6d 65 74 68 6f 64 3c 2f 68 32  lose" method</h2
0700: 3e 0a 0a 3c 70 3e 0a 41 73 20 69 74 73 20 6e 61  >..<p>.As its na
0710: 6d 65 20 73 75 67 67 65 73 74 73 2c 20 74 68 65  me suggests, the
0720: 20 22 63 6c 6f 73 65 22 20 6d 65 74 68 6f 64 20   "close" method 
0730: 74 6f 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  to an SQLite dat
0740: 61 62 61 73 65 20 6a 75 73 74 0a 63 6c 6f 73 65  abase just.close
0750: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
0760: 20 54 68 69 73 20 68 61 73 20 74 68 65 20 73 69   This has the si
0770: 64 65 2d 65 66 66 65 63 74 20 6f 66 20 64 65 6c  de-effect of del
0780: 65 74 69 6e 67 20 74 68 65 0a 3c 69 3e 64 62 63  eting the.<i>dbc
0790: 6d 64 3c 2f 69 3e 20 54 63 6c 20 63 6f 6d 6d 61  md</i> Tcl comma
07a0: 6e 64 2e 20 20 48 65 72 65 20 69 73 20 61 6e 20  nd.  Here is an 
07b0: 65 78 61 6d 70 6c 65 20 6f 66 20 6f 70 65 6e 69  example of openi
07c0: 6e 67 20 61 6e 64 20 74 68 65 6e 0a 69 6d 6d 65  ng and then.imme
07d0: 64 69 61 74 65 6c 79 20 63 6c 6f 73 69 6e 67 20  diately closing 
07e0: 61 20 64 61 74 61 62 61 73 65 3a 0a 3c 2f 70 3e  a database:.</p>
07f0: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c  ..<blockquote>.<
0800: 62 3e 73 71 6c 69 74 65 20 64 62 31 20 2e 2f 74  b>sqlite db1 ./t
0810: 65 73 74 64 62 3c 62 72 3e 0a 64 62 31 20 63 6c  estdb<br>.db1 cl
0820: 6f 73 65 3c 2f 62 3e 0a 3c 2f 62 6c 6f 63 6b 71  ose</b>.</blockq
0830: 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 49 66 20 79 6f  uote>..<p>.If yo
0840: 75 20 64 65 6c 65 74 65 20 74 68 65 20 3c 69 3e  u delete the <i>
0850: 64 62 63 6d 64 3c 2f 69 3e 20 64 69 72 65 63 74  dbcmd</i> direct
0860: 6c 79 2c 20 74 68 61 74 20 68 61 73 20 74 68 65  ly, that has the
0870: 20 73 61 6d 65 20 65 66 66 65 63 74 0a 61 73 20   same effect.as 
0880: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 22 63 6c  invoking the "cl
0890: 6f 73 65 22 20 6d 65 74 68 6f 64 2e 20 20 53 6f  ose" method.  So
08a0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
08b0: 6f 64 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ode is equivalen
08c0: 74 0a 74 6f 20 74 68 65 20 70 72 65 76 69 6f 75  t.to the previou
08d0: 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  s:</p>..<blockqu
08e0: 6f 74 65 3e 0a 3c 62 3e 73 71 6c 69 74 65 20 64  ote>.<b>sqlite d
08f0: 62 31 20 2e 2f 74 65 73 74 64 62 3c 62 72 3e 0a  b1 ./testdb<br>.
0900: 72 65 6e 61 6d 65 20 64 62 31 20 7b 7d 3c 2f 62  rename db1 {}</b
0910: 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  >.</blockquote>.
0920: 0a 3c 68 32 3e 54 68 65 20 22 65 76 61 6c 22 20  .<h2>The "eval" 
0930: 6d 65 74 68 6f 64 3c 2f 68 32 3e 0a 0a 3c 70 3e  method</h2>..<p>
0940: 0a 54 68 65 20 6d 6f 73 74 20 75 73 65 66 75 6c  .The most useful
0950: 20 3c 69 3e 64 62 63 6d 64 3c 2f 69 3e 20 6d 65   <i>dbcmd</i> me
0960: 74 68 6f 64 20 69 73 20 22 65 76 61 6c 22 2e 20  thod is "eval". 
0970: 20 54 68 65 20 65 76 61 6c 20 6d 65 74 68 6f 64   The eval method
0980: 20 69 73 20 75 73 65 64 0a 74 6f 20 65 78 65 63   is used.to exec
0990: 75 74 65 20 53 51 4c 20 6f 6e 20 74 68 65 20 64  ute SQL on the d
09a0: 61 74 61 62 61 73 65 2e 20 20 54 68 65 20 73 79  atabase.  The sy
09b0: 6e 74 61 78 20 6f 66 20 74 68 65 20 65 76 61 6c  ntax of the eval
09c0: 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a 6c 69   method looks.li
09d0: 6b 65 20 74 68 69 73 3a 3c 2f 70 3e 0a 0a 3c 62  ke this:</p>..<b
09e0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 69 3e 64 62  lockquote>.<i>db
09f0: 63 6d 64 3c 2f 69 3e 26 6e 62 73 70 3b 26 6e 62  cmd</i>&nbsp;&nb
0a00: 73 70 3b 3c 62 3e 65 76 61 6c 3c 2f 62 3e 26 6e  sp;<b>eval</b>&n
0a10: 62 73 70 3b 26 6e 62 73 70 3b 3c 69 3e 73 71 6c  bsp;&nbsp;<i>sql
0a20: 3c 2f 69 3e 0a 26 6e 62 73 70 3b 26 6e 62 73 70  </i>.&nbsp;&nbsp
0a30: 3b 3f 3c 69 3e 61 72 72 61 79 2d 6e 61 6d 65 26  ;?<i>array-name&
0a40: 6e 62 73 70 3b 26 6e 62 73 70 3b 73 63 72 69 70  nbsp;&nbsp;scrip
0a50: 74 3c 2f 69 3e 3f 0a 3c 2f 62 6c 6f 63 6b 71 75  t</i>?.</blockqu
0a60: 6f 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65 20 6a 6f  ote>..<p>.The jo
0a70: 62 20 6f 66 20 74 68 65 20 65 76 61 6c 20 6d 65  b of the eval me
0a80: 74 68 6f 64 20 69 73 20 74 6f 20 65 78 65 63 75  thod is to execu
0a90: 74 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  te the SQL state
0aa0: 6d 65 6e 74 20 6f 72 20 73 74 61 74 65 6d 65 6e  ment or statemen
0ab0: 74 73 0a 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ts.given in the 
0ac0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
0ad0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74    For example, t
0ae0: 6f 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  o create a new t
0af0: 61 62 6c 65 20 69 6e 0a 61 20 64 61 74 61 62 61  able in.a databa
0b00: 73 65 2c 20 79 6f 75 20 63 61 6e 20 64 6f 20 74  se, you can do t
0b10: 68 69 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b  his:</p>..<block
0b20: 71 75 6f 74 65 3e 0a 3c 62 3e 73 71 6c 69 74 65  quote>.<b>sqlite
0b30: 20 64 62 31 20 2e 2f 74 65 73 74 64 62 3c 62 72   db1 ./testdb<br
0b40: 3e 0a 64 62 31 20 65 76 61 6c 20 7b 43 52 45 41  >.db1 eval {CREA
0b50: 54 45 20 54 41 42 4c 45 20 74 31 28 61 20 69 6e  TE TABLE t1(a in
0b60: 74 2c 20 62 20 74 65 78 74 29 7d 3c 2f 62 3e 0a  t, b text)}</b>.
0b70: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
0b80: 70 3e 54 68 65 20 61 62 6f 76 65 20 63 6f 64 65  p>The above code
0b90: 20 63 72 65 61 74 65 73 20 61 20 6e 65 77 20 74   creates a new t
0ba0: 61 62 6c 65 20 6e 61 6d 65 64 20 3c 62 3e 74 31  able named <b>t1
0bb0: 3c 2f 62 3e 20 77 69 74 68 20 63 6f 6c 75 6d 6e  </b> with column
0bc0: 73 0a 3c 62 3e 61 3c 2f 62 3e 20 61 6e 64 20 3c  s.<b>a</b> and <
0bd0: 62 3e 62 3c 2f 62 3e 2e 20 20 57 68 61 74 20 63  b>b</b>.  What c
0be0: 6f 75 6c 64 20 62 65 20 73 69 6d 70 6c 65 72 3f  ould be simpler?
0bf0: 3c 2f 70 3e 0a 0a 3c 70 3e 51 75 65 72 79 20 72  </p>..<p>Query r
0c00: 65 73 75 6c 74 73 20 61 72 65 20 72 65 74 75 72  esults are retur
0c10: 6e 65 64 20 61 73 20 61 20 6c 69 73 74 20 6f 66  ned as a list of
0c20: 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 2e 20   column values. 
0c30: 20 49 66 20 61 0a 71 75 65 72 79 20 72 65 71 75   If a.query requ
0c40: 65 73 74 73 20 32 20 63 6f 6c 75 6d 6e 73 20 61  ests 2 columns a
0c50: 6e 64 20 74 68 65 72 65 20 61 72 65 20 33 20 72  nd there are 3 r
0c60: 6f 77 73 20 6d 61 74 63 68 69 6e 67 20 74 68 65  ows matching the
0c70: 20 71 75 65 72 79 2c 0a 74 68 65 6e 20 74 68 65   query,.then the
0c80: 20 72 65 74 75 72 6e 65 64 20 6c 69 73 74 20 77   returned list w
0c90: 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 36 20 65 6c  ill contain 6 el
0ca0: 65 6d 65 6e 74 73 2e 20 20 46 6f 72 20 65 78 61  ements.  For exa
0cb0: 6d 70 6c 65 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63  mple:</p>..<bloc
0cc0: 6b 71 75 6f 74 65 3e 0a 3c 62 3e 64 62 31 20 65  kquote>.<b>db1 e
0cd0: 76 61 6c 20 7b 49 4e 53 45 52 54 20 49 4e 54 4f  val {INSERT INTO
0ce0: 20 74 31 20 56 41 4c 55 45 53 28 31 2c 27 68 65   t1 VALUES(1,'he
0cf0: 6c 6c 6f 27 29 7d 3c 62 72 3e 0a 64 62 31 20 65  llo')}<br>.db1 e
0d00: 76 61 6c 20 7b 49 4e 53 45 52 54 20 49 4e 54 4f  val {INSERT INTO
0d10: 20 74 31 20 56 41 4c 55 45 53 28 32 2c 27 67 6f   t1 VALUES(2,'go
0d20: 6f 64 62 79 65 27 29 7d 3c 62 72 3e 0a 64 62 31  odbye')}<br>.db1
0d30: 20 65 76 61 6c 20 7b 49 4e 53 45 52 54 20 49 4e   eval {INSERT IN
0d40: 54 4f 20 74 31 20 56 41 4c 55 45 53 28 33 2c 27  TO t1 VALUES(3,'
0d50: 68 6f 77 64 79 21 27 29 7d 3c 62 72 3e 0a 73 65  howdy!')}<br>.se
0d60: 74 20 78 20 5b 64 62 31 20 65 76 61 6c 20 7b 53  t x [db1 eval {S
0d70: 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 74 31 20  ELECT * FROM t1 
0d80: 4f 52 44 45 52 20 42 59 20 61 7d 5d 3c 2f 62 3e  ORDER BY a}]</b>
0d90: 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  .</blockquote>..
0da0: 3c 70 3e 54 68 65 20 76 61 72 69 61 62 6c 65 20  <p>The variable 
0db0: 3c 62 3e 24 78 3c 2f 62 3e 20 69 73 20 73 65 74  <b>$x</b> is set
0dc0: 20 62 79 20 74 68 65 20 61 62 6f 76 65 20 63 6f   by the above co
0dd0: 64 65 20 74 6f 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63  de to</p>..<bloc
0de0: 6b 71 75 6f 74 65 3e 0a 3c 62 3e 31 20 68 65 6c  kquote>.<b>1 hel
0df0: 6c 6f 20 32 20 67 6f 6f 64 62 79 65 20 33 20 68  lo 2 goodbye 3 h
0e00: 6f 77 64 79 21 3c 2f 62 3e 0a 3c 2f 62 6c 6f 63  owdy!</b>.</bloc
0e10: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 59 6f 75 20  kquote>..<p>You 
0e20: 63 61 6e 20 61 6c 73 6f 20 70 72 6f 63 65 73 73  can also process
0e30: 20 74 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20   the results of 
0e40: 61 20 71 75 65 72 79 20 6f 6e 65 20 72 6f 77 20  a query one row 
0e50: 61 74 20 61 20 74 69 6d 65 0a 62 79 20 73 70 65  at a time.by spe
0e60: 63 69 66 79 69 6e 67 20 74 68 65 20 6e 61 6d 65  cifying the name
0e70: 20 6f 66 20 61 6e 20 61 72 72 61 79 20 76 61 72   of an array var
0e80: 69 61 62 6c 65 20 61 6e 64 20 61 20 73 63 72 69  iable and a scri
0e90: 70 74 20 66 6f 6c 6c 6f 77 69 6e 67 0a 74 68 65  pt following.the
0ea0: 20 53 51 4c 20 63 6f 64 65 2e 20 20 46 6f 72 20   SQL code.  For 
0eb0: 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20  each row of the 
0ec0: 71 75 65 72 79 20 72 65 73 75 6c 74 2c 20 74 68  query result, th
0ed0: 65 20 76 61 6c 75 65 20 6f 66 20 65 61 63 68 0a  e value of each.
0ee0: 63 6f 6c 75 6d 6e 20 77 69 6c 6c 20 62 65 20 69  column will be i
0ef0: 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 74 68 65  nserted into the
0f00: 20 61 72 72 61 79 20 76 61 72 69 61 62 6c 65 20   array variable 
0f10: 61 6e 64 20 74 68 65 20 73 63 72 69 70 74 20 77  and the script w
0f20: 69 6c 6c 0a 62 65 20 65 78 65 63 75 74 65 64 2e  ill.be executed.
0f30: 20 20 46 6f 72 20 69 6e 73 74 61 6e 63 65 3a 3c    For instance:<
0f40: 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  /p>..<blockquote
0f50: 3e 0a 3c 62 3e 64 62 31 20 65 76 61 6c 20 7b 53  >.<b>db1 eval {S
0f60: 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 74 31 20  ELECT * FROM t1 
0f70: 4f 52 44 45 52 20 42 59 20 61 7d 20 76 61 6c 75  ORDER BY a} valu
0f80: 65 73 20 7b 3c 62 72 3e 0a 26 6e 62 73 70 3b 26  es {<br>.&nbsp;&
0f90: 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70  nbsp;&nbsp;&nbsp
0fa0: 3b 70 61 72 72 61 79 20 76 61 6c 75 65 73 3c 62  ;parray values<b
0fb0: 72 3e 0a 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26  r>.&nbsp;&nbsp;&
0fc0: 6e 62 73 70 3b 26 6e 62 73 70 3b 70 75 74 73 20  nbsp;&nbsp;puts 
0fd0: 22 22 3c 62 72 3e 0a 7d 3c 2f 62 3e 0a 3c 2f 62  ""<br>.}</b>.</b
0fe0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54  lockquote>..<p>T
0ff0: 68 69 73 20 6c 61 73 74 20 63 6f 64 65 20 77 69  his last code wi
1000: 6c 6c 20 67 69 76 65 20 74 68 65 20 66 6f 6c 6c  ll give the foll
1010: 6f 77 69 6e 67 20 6f 75 74 70 75 74 3a 3c 2f 70  owing output:</p
1020: 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  >..<blockquote><
1030: 62 3e 0a 76 61 6c 75 65 73 28 2a 29 20 3d 20 61  b>.values(*) = a
1040: 20 62 3c 62 72 3e 0a 76 61 6c 75 65 73 28 61 29   b<br>.values(a)
1050: 20 3d 20 31 3c 62 72 3e 0a 76 61 6c 75 65 73 28   = 1<br>.values(
1060: 62 29 20 3d 20 68 65 6c 6c 6f 3c 70 3e 0a 0a 76  b) = hello<p>..v
1070: 61 6c 75 65 73 28 2a 29 20 3d 20 61 20 62 3c 62  alues(*) = a b<b
1080: 72 3e 0a 76 61 6c 75 65 73 28 61 29 20 3d 20 32  r>.values(a) = 2
1090: 3c 62 72 3e 0a 76 61 6c 75 65 73 28 62 29 20 3d  <br>.values(b) =
10a0: 20 67 6f 6f 64 62 79 65 3c 70 3e 0a 0a 76 61 6c   goodbye<p>..val
10b0: 75 65 73 28 2a 29 20 3d 20 61 20 62 3c 62 72 3e  ues(*) = a b<br>
10c0: 0a 76 61 6c 75 65 73 28 61 29 20 3d 20 33 3c 62  .values(a) = 3<b
10d0: 72 3e 0a 76 61 6c 75 65 73 28 62 29 20 3d 20 68  r>.values(b) = h
10e0: 6f 77 64 79 21 3c 2f 62 3e 0a 3c 2f 62 6c 6f 63  owdy!</b>.</bloc
10f0: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 46 6f 72  kquote>..<p>.For
1100: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e 20   each column in 
1110: 61 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  a row of the res
1120: 75 6c 74 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66  ult, the name of
1130: 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 69 73 20   that column.is 
1140: 75 73 65 64 20 61 73 20 61 6e 20 69 6e 64 65 78  used as an index
1150: 20 69 6e 20 74 6f 20 61 72 72 61 79 2e 20 20 54   in to array.  T
1160: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
1170: 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64  column is stored
1180: 0a 69 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  .in the correspo
1190: 6e 64 69 6e 67 20 61 72 72 61 79 20 65 6e 74 72  nding array entr
11a0: 79 2e 20 20 54 68 65 20 73 70 65 63 69 61 6c 20  y.  The special 
11b0: 61 72 72 61 79 20 69 6e 64 65 78 20 2a 20 69 73  array index * is
11c0: 0a 75 73 65 64 20 74 6f 20 73 74 6f 72 65 20 61  .used to store a
11d0: 20 6c 69 73 74 20 6f 66 20 63 6f 6c 75 6d 6e 20   list of column 
11e0: 6e 61 6d 65 73 20 69 6e 20 74 68 65 20 6f 72 64  names in the ord
11f0: 65 72 20 74 68 61 74 20 74 68 65 79 20 61 70 70  er that they app
1200: 65 61 72 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49  ear..</p>..<p>.I
1210: 66 20 74 68 65 20 61 72 72 61 79 20 76 61 72 69  f the array vari
1220: 61 62 6c 65 20 6e 61 6d 65 20 69 73 20 74 68 65  able name is the
1230: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
1240: 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  hen the value of
1250: 0a 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 73 20  .each column is 
1260: 73 74 6f 72 65 64 20 69 6e 20 61 20 76 61 72 69  stored in a vari
1270: 61 62 6c 65 20 77 69 74 68 20 74 68 65 20 73 61  able with the sa
1280: 6d 65 20 6e 61 6d 65 20 61 73 20 74 68 65 20 63  me name as the c
1290: 6f 6c 75 6d 6e 0a 69 74 73 65 6c 66 2e 20 20 46  olumn.itself.  F
12a0: 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 3c 2f 70 3e  or example:.</p>
12b0: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c  ..<blockquote>.<
12c0: 62 3e 64 62 31 20 65 76 61 6c 20 7b 53 45 4c 45  b>db1 eval {SELE
12d0: 43 54 20 2a 20 46 52 4f 4d 20 74 31 20 4f 52 44  CT * FROM t1 ORD
12e0: 45 52 20 42 59 20 61 7d 20 7b 7d 20 7b 3c 62 72  ER BY a} {} {<br
12f0: 3e 0a 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  >.&nbsp;&nbsp;&n
1300: 62 73 70 3b 26 6e 62 73 70 3b 70 75 74 73 20 22  bsp;&nbsp;puts "
1310: 61 3d 24 61 20 62 3d 24 62 22 3c 62 72 3e 0a 7d  a=$a b=$b"<br>.}
1320: 3c 2f 62 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74  </b>.</blockquot
1330: 65 3e 0a 0a 3c 70 3e 0a 46 72 6f 6d 20 74 68 69  e>..<p>.From thi
1340: 73 20 77 65 20 67 65 74 20 74 68 65 20 66 6f 6c  s we get the fol
1350: 6c 6f 77 69 6e 67 20 6f 75 74 70 75 74 0a 3c 2f  lowing output.</
1360: 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  p>..<blockquote>
1370: 3c 62 3e 0a 61 3d 31 20 62 3d 68 65 6c 6c 6f 3c  <b>.a=1 b=hello<
1380: 62 72 3e 0a 61 3d 32 20 62 3d 67 6f 6f 64 62 79  br>.a=2 b=goodby
1390: 65 3c 62 72 3e 0a 61 3d 33 20 62 3d 68 6f 77 64  e<br>.a=3 b=howd
13a0: 79 21 3c 2f 62 3e 0a 3c 2f 62 6c 6f 63 6b 71 75  y!</b>.</blockqu
13b0: 6f 74 65 3e 0a 0a 3c 68 32 3e 54 68 65 20 22 63  ote>..<h2>The "c
13c0: 6f 6d 70 6c 65 74 65 22 20 6d 65 74 68 6f 64 3c  omplete" method<
13d0: 2f 68 32 3e 0a 0a 3c 70 3e 0a 54 68 65 20 22 63  /h2>..<p>.The "c
13e0: 6f 6d 70 6c 65 74 65 22 20 6d 65 74 68 6f 64 20  omplete" method 
13f0: 74 61 6b 65 73 20 61 20 73 74 72 69 6e 67 20 6f  takes a string o
1400: 66 20 73 75 70 70 6f 73 65 64 20 53 51 4c 20 61  f supposed SQL a
1410: 73 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d  s its only argum
1420: 65 6e 74 2e 0a 49 74 20 72 65 74 75 72 6e 73 20  ent..It returns 
1430: 54 52 55 45 20 69 66 20 74 68 65 20 73 74 72 69  TRUE if the stri
1440: 6e 67 20 69 73 20 61 20 63 6f 6d 70 6c 65 74 65  ng is a complete
1450: 20 73 74 61 74 65 6d 65 6e 74 20 6f 66 20 53 51   statement of SQ
1460: 4c 20 61 6e 64 20 46 41 4c 53 45 20 69 66 0a 74  L and FALSE if.t
1470: 68 65 72 65 20 69 73 20 6d 6f 72 65 20 74 6f 20  here is more to 
1480: 62 65 20 65 6e 74 65 72 65 64 2e 3c 2f 70 3e 0a  be entered.</p>.
1490: 0a 3c 70 3e 54 68 65 20 22 63 6f 6d 70 6c 65 74  .<p>The "complet
14a0: 65 22 20 6d 65 74 68 6f 64 20 69 73 20 75 73 65  e" method is use
14b0: 66 75 6c 20 77 68 65 6e 20 62 75 69 6c 64 69 6e  ful when buildin
14c0: 67 20 69 6e 74 65 72 61 63 74 69 76 65 20 61 70  g interactive ap
14d0: 70 6c 69 63 61 74 69 6f 6e 73 0a 69 6e 20 6f 72  plications.in or
14e0: 64 65 72 20 74 6f 20 6b 6e 6f 77 20 77 68 65 6e  der to know when
14f0: 20 74 68 65 20 75 73 65 72 20 68 61 73 20 66 69   the user has fi
1500: 6e 69 73 68 65 64 20 65 6e 74 65 72 69 6e 67 20  nished entering 
1510: 61 20 6c 69 6e 65 20 6f 66 20 53 51 4c 20 63 6f  a line of SQL co
1520: 64 65 2e 0a 54 68 69 73 20 69 73 20 72 65 61 6c  de..This is real
1530: 6c 79 20 6a 75 73 74 20 61 6e 20 69 6e 74 65 72  ly just an inter
1540: 66 61 63 65 20 74 6f 20 74 68 65 20 3c 62 3e 73  face to the <b>s
1550: 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 65 28 29  qlite_complete()
1560: 3c 2f 62 3e 20 43 0a 66 75 6e 63 74 69 6f 6e 2e  </b> C.function.
1570: 20 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 3c    Refer to the <
1580: 61 20 68 72 65 66 3d 22 63 5f 69 6e 74 65 72 66  a href="c_interf
1590: 61 63 65 2e 68 74 6d 6c 22 3e 43 2f 43 2b 2b 20  ace.html">C/C++ 
15a0: 69 6e 74 65 72 66 61 63 65 3c 2f 61 3e 0a 73 70  interface</a>.sp
15b0: 65 63 69 66 69 63 61 74 69 6f 6e 20 66 6f 72 20  ecification for 
15c0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
15d0: 6d 61 74 69 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 68 32  mation.</p>..<h2
15e0: 3e 54 68 65 20 22 74 69 6d 65 6f 75 74 22 20 6d  >The "timeout" m
15f0: 65 74 68 6f 64 3c 2f 68 32 3e 0a 0a 3c 70 3e 54  ethod</h2>..<p>T
1600: 68 65 20 22 74 69 6d 65 6f 75 74 22 20 6d 65 74  he "timeout" met
1610: 68 6f 64 20 69 73 20 75 73 65 64 20 74 6f 20 63  hod is used to c
1620: 6f 6e 74 72 6f 6c 20 68 6f 77 20 6c 6f 6e 67 20  ontrol how long 
1630: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
1640: 72 79 0a 77 69 6c 6c 20 77 61 69 74 20 66 6f 72  ry.will wait for
1650: 20 6c 6f 63 6b 73 20 74 6f 20 63 6c 65 61 72 20   locks to clear 
1660: 62 65 66 6f 72 65 20 67 69 76 69 6e 67 20 75 70  before giving up
1670: 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   on a database t
1680: 72 61 6e 73 61 63 74 69 6f 6e 2e 0a 54 68 65 20  ransaction..The 
1690: 64 65 66 61 75 6c 74 20 74 69 6d 65 6f 75 74 20  default timeout 
16a0: 69 73 20 30 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  is 0 millisecond
16b0: 2e 20 20 28 49 6e 20 6f 74 68 65 72 20 77 6f 72  .  (In other wor
16c0: 64 73 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20  ds, the default 
16d0: 62 65 68 61 76 69 6f 72 0a 69 73 20 6e 6f 74 20  behavior.is not 
16e0: 74 6f 20 77 61 69 74 20 61 74 20 61 6c 6c 2e 29  to wait at all.)
16f0: 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 53 51 6c  </p>..<p>The SQl
1700: 69 74 65 20 64 61 74 61 62 61 73 65 20 61 6c 6c  ite database all
1710: 6f 77 73 20 6d 75 6c 74 69 70 6c 65 20 73 69 6d  ows multiple sim
1720: 75 6c 74 61 6e 65 6f 75 73 0a 72 65 61 64 65 72  ultaneous.reader
1730: 73 20 6f 72 20 61 20 73 69 6e 67 6c 65 20 77 72  s or a single wr
1740: 69 74 65 72 20 62 75 74 20 6e 6f 74 20 62 6f 74  iter but not bot
1750: 68 2e 20 20 49 66 20 61 6e 79 20 70 72 6f 63 65  h.  If any proce
1760: 73 73 20 69 73 20 77 72 69 74 69 6e 67 20 74 6f  ss is writing to
1770: 0a 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 6f  .the database no
1780: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 20 69   other process i
1790: 73 20 61 6c 6c 6f 77 73 20 74 6f 20 72 65 61 64  s allows to read
17a0: 20 6f 72 20 77 72 69 74 65 2e 20 20 49 66 20 61   or write.  If a
17b0: 6e 79 20 70 72 6f 63 65 73 73 0a 69 73 20 72 65  ny process.is re
17c0: 61 64 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  ading the databa
17d0: 73 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  se other process
17e0: 65 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 20 74  es are allowed t
17f0: 6f 20 72 65 61 64 20 62 75 74 20 6e 6f 74 20 77  o read but not w
1800: 72 69 74 65 2e 0a 54 68 65 20 65 6e 74 69 72 65  rite..The entire
1810: 20 64 61 74 61 62 61 73 65 20 73 68 61 72 65 64   database shared
1820: 20 61 20 73 69 6e 67 6c 65 20 6c 6f 63 6b 2e 3c   a single lock.<
1830: 2f 70 3e 0a 0a 3c 70 3e 57 68 65 6e 20 53 51 4c  /p>..<p>When SQL
1840: 69 74 65 20 74 72 69 65 73 20 74 6f 20 6f 70 65  ite tries to ope
1850: 6e 20 61 20 64 61 74 61 62 61 73 65 20 61 6e 64  n a database and
1860: 20 66 69 6e 64 73 20 74 68 61 74 20 69 74 20 69   finds that it i
1870: 73 20 6c 6f 63 6b 65 64 2c 20 69 74 0a 63 61 6e  s locked, it.can
1880: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 64 65 6c 61   optionally dela
1890: 79 20 66 6f 72 20 61 20 73 68 6f 72 74 20 77 68  y for a short wh
18a0: 69 6c 65 20 61 6e 64 20 74 72 79 20 74 6f 20 6f  ile and try to o
18b0: 70 65 6e 20 74 68 65 20 66 69 6c 65 20 61 67 61  pen the file aga
18c0: 69 6e 2e 0a 54 68 69 73 20 70 72 6f 63 65 73 73  in..This process
18d0: 20 72 65 70 65 61 74 73 20 75 6e 74 69 6c 20 74   repeats until t
18e0: 68 65 20 71 75 65 72 79 20 74 69 6d 65 73 20 6f  he query times o
18f0: 75 74 20 61 6e 64 20 53 51 4c 69 74 65 20 72 65  ut and SQLite re
1900: 74 75 72 6e 73 20 61 0a 66 61 69 6c 75 72 65 2e  turns a.failure.
1910: 20 20 54 68 65 20 74 69 6d 65 6f 75 74 20 69 73    The timeout is
1920: 20 61 64 6a 75 73 74 61 62 6c 65 2e 20 20 49 74   adjustable.  It
1930: 20 69 73 20 73 65 74 20 74 6f 20 30 20 62 79 20   is set to 0 by 
1940: 64 65 66 61 75 6c 74 20 73 6f 20 74 68 61 74 0a  default so that.
1950: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
1960: 69 73 20 6c 6f 63 6b 65 64 2c 20 74 68 65 20 53  is locked, the S
1970: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69  QL statement fai
1980: 6c 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 20  ls immediately. 
1990: 20 42 75 74 20 79 6f 75 0a 63 61 6e 20 75 73 65   But you.can use
19a0: 20 74 68 65 20 22 74 69 6d 65 6f 75 74 22 20 6d   the "timeout" m
19b0: 65 74 68 6f 64 20 74 6f 20 63 68 61 6e 67 65 20  ethod to change 
19c0: 74 68 65 20 74 69 6d 65 6f 75 74 20 76 61 6c 75  the timeout valu
19d0: 65 20 74 6f 20 61 20 70 6f 73 69 74 69 76 65 0a  e to a positive.
19e0: 6e 75 6d 62 65 72 2e 20 20 46 6f 72 20 65 78 61  number.  For exa
19f0: 6d 70 6c 65 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63  mple:</p>..<bloc
1a00: 6b 71 75 6f 74 65 3e 3c 62 3e 64 62 31 20 74 69  kquote><b>db1 ti
1a10: 6d 65 6f 75 74 20 32 30 30 30 3c 2f 62 3e 3c 2f  meout 2000</b></
1a20: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e  blockquote>..<p>
1a30: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  The argument to 
1a40: 74 68 65 20 74 69 6d 65 6f 75 74 20 6d 65 74 68  the timeout meth
1a50: 6f 64 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  od is the maximu
1a60: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  m number of mill
1a70: 69 73 65 63 6f 6e 64 73 0a 74 6f 20 77 61 69 74  iseconds.to wait
1a80: 20 66 6f 72 20 74 68 65 20 6c 6f 63 6b 20 74 6f   for the lock to
1a90: 20 63 6c 65 61 72 2e 20 20 53 6f 20 69 6e 20 74   clear.  So in t
1aa0: 68 65 20 65 78 61 6d 70 6c 65 20 61 62 6f 76 65  he example above
1ab0: 2c 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  , the maximum de
1ac0: 6c 61 79 0a 77 6f 75 6c 64 20 62 65 20 32 20 73  lay.would be 2 s
1ad0: 65 63 6f 6e 64 73 2e 3c 2f 70 3e 0a 0a 3c 68 32  econds.</p>..<h2
1ae0: 3e 54 68 65 20 22 62 75 73 79 22 20 6d 65 74 68  >The "busy" meth
1af0: 6f 64 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65 20  od</h2>..<p>The 
1b00: 22 62 75 73 79 22 20 6d 65 74 68 6f 64 2c 20 6c  "busy" method, l
1b10: 69 6b 65 20 22 74 69 6d 65 6f 75 74 22 2c 20 6f  ike "timeout", o
1b20: 6e 6c 79 20 63 6f 6d 65 73 20 69 6e 74 6f 20 70  nly comes into p
1b30: 6c 61 79 20 77 68 65 6e 20 74 68 65 0a 64 61 74  lay when the.dat
1b40: 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 2e  abase is locked.
1b50: 20 20 42 75 74 20 74 68 65 20 22 62 75 73 79 22    But the "busy"
1b60: 20 6d 65 74 68 6f 64 20 67 69 76 65 73 20 74 68   method gives th
1b70: 65 20 70 72 6f 67 72 61 6d 6d 65 72 20 6d 75 63  e programmer muc
1b80: 68 20 6d 6f 72 65 0a 63 6f 6e 74 72 6f 6c 20 6f  h more.control o
1b90: 76 65 72 20 77 68 61 74 20 61 63 74 69 6f 6e 20  ver what action 
1ba0: 74 6f 20 74 61 6b 65 2e 20 20 54 68 65 20 22 62  to take.  The "b
1bb0: 75 73 79 22 20 6d 65 74 68 6f 64 20 73 70 65 63  usy" method spec
1bc0: 69 66 69 65 73 20 61 20 63 61 6c 6c 62 61 63 6b  ifies a callback
1bd0: 0a 54 63 6c 20 70 72 6f 63 65 64 75 72 65 20 74  .Tcl procedure t
1be0: 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  hat is invoked w
1bf0: 68 65 6e 65 76 65 72 20 53 51 4c 69 74 65 20 74  henever SQLite t
1c00: 72 69 65 73 20 74 6f 20 6f 70 65 6e 20 61 20 6c  ries to open a l
1c10: 6f 63 6b 65 64 0a 64 61 74 61 62 61 73 65 2e 20  ocked.database. 
1c20: 20 54 68 69 73 20 63 61 6c 6c 62 61 63 6b 20 63   This callback c
1c30: 61 6e 20 64 6f 20 77 68 61 74 65 76 65 72 20 69  an do whatever i
1c40: 73 20 64 65 73 69 72 65 64 2e 20 20 50 72 65 73  s desired.  Pres
1c50: 75 6d 61 62 6c 79 2c 20 74 68 65 0a 63 61 6c 6c  umably, the.call
1c60: 62 61 63 6b 20 77 69 6c 6c 20 64 6f 20 73 6f 6d  back will do som
1c70: 65 20 6f 74 68 65 72 20 75 73 65 66 75 6c 20 77  e other useful w
1c80: 6f 72 6b 20 66 6f 72 20 61 20 73 68 6f 72 74 20  ork for a short 
1c90: 77 68 69 6c 65 20 74 68 65 6e 20 72 65 74 75 72  while then retur
1ca0: 6e 0a 73 6f 20 74 68 61 74 20 74 68 65 20 6c 6f  n.so that the lo
1cb0: 63 6b 20 63 61 6e 20 62 65 20 74 72 69 65 64 20  ck can be tried 
1cc0: 61 67 61 69 6e 2e 20 20 54 68 65 20 63 61 6c 6c  again.  The call
1cd0: 62 61 63 6b 20 70 72 6f 63 65 64 75 72 65 20 73  back procedure s
1ce0: 68 6f 75 6c 64 0a 72 65 74 75 72 6e 20 22 30 22  hould.return "0"
1cf0: 20 69 66 20 69 74 20 77 61 6e 74 73 20 53 51 4c   if it wants SQL
1d00: 69 74 65 20 74 6f 20 74 72 79 20 61 67 61 69 6e  ite to try again
1d10: 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
1d20: 61 62 61 73 65 20 61 6e 64 0a 73 68 6f 75 6c 64  abase and.should
1d30: 20 72 65 74 75 72 6e 20 22 31 22 20 69 66 20 69   return "1" if i
1d40: 74 20 77 61 6e 74 73 20 53 51 4c 69 74 65 20 74  t wants SQLite t
1d50: 6f 20 61 62 61 6e 64 6f 6e 20 74 68 65 20 63 75  o abandon the cu
1d60: 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e  rrent operation.
1d70: 0a 0a 3c 68 32 3e 54 68 65 20 22 6c 61 73 74 5f  ..<h2>The "last_
1d80: 69 6e 73 65 72 74 5f 72 6f 77 69 64 22 20 6d 65  insert_rowid" me
1d90: 74 68 6f 64 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68  thod</h2>..<p>Th
1da0: 65 20 22 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e "last_insert_r
1db0: 6f 77 69 64 22 20 6d 65 74 68 6f 64 20 72 65 74  owid" method ret
1dc0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
1dd0: 77 68 69 63 68 20 69 73 20 74 68 65 20 52 4f 57  which is the ROW
1de0: 49 44 0a 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  ID.of the most r
1df0: 65 63 65 6e 74 6c 79 20 69 6e 73 65 72 74 65 64  ecently inserted
1e00: 20 64 61 74 61 62 61 73 65 20 72 6f 77 2e 3c 2f   database row.</
1e10: 70 3e 0a 0a 3c 68 32 3e 54 68 65 20 22 6f 6e 65  p>..<h2>The "one
1e20: 63 6f 6c 75 6d 6e 22 20 6d 65 74 68 6f 64 3c 2f  column" method</
1e30: 68 32 3e 0a 0a 3c 70 3e 54 68 65 20 22 6f 6e 65  h2>..<p>The "one
1e40: 63 6f 6c 75 6d 6e 22 20 6d 65 74 68 6f 64 20 77  column" method w
1e50: 6f 72 6b 73 20 6c 69 6b 65 20 22 65 76 61 6c 22  orks like "eval"
1e60: 20 69 6e 20 74 68 61 74 20 69 74 20 65 76 61 6c   in that it eval
1e70: 75 61 74 65 73 20 74 68 65 0a 53 51 4c 20 71 75  uates the.SQL qu
1e80: 65 72 79 20 73 74 61 74 65 6d 65 6e 74 20 67 69  ery statement gi
1e90: 76 65 6e 20 61 73 20 69 74 73 20 61 72 67 75 6d  ven as its argum
1ea0: 65 6e 74 2e 20 20 54 68 65 20 64 69 66 66 65 72  ent.  The differ
1eb0: 65 6e 63 65 20 69 73 20 74 68 61 74 0a 22 6f 6e  ence is that."on
1ec0: 65 63 6f 6c 75 6d 6e 22 20 72 65 74 75 72 6e 73  ecolumn" returns
1ed0: 20 61 20 73 69 6e 67 6c 65 20 65 6c 65 6d 65 6e   a single elemen
1ee0: 74 20 77 68 69 63 68 20 69 73 20 74 68 65 20 66  t which is the f
1ef0: 69 72 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  irst column of t
1f00: 68 65 0a 66 69 72 73 74 20 72 6f 77 20 6f 66 20  he.first row of 
1f10: 74 68 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  the query result
1f20: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 69 73 20 69  .</p>..<p>This i
1f30: 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20  s a convenience 
1f40: 6d 65 74 68 6f 64 2e 20 20 49 74 20 73 61 76 65  method.  It save
1f50: 73 20 74 68 65 20 75 73 65 72 20 66 72 6f 6d 20  s the user from 
1f60: 68 61 76 69 6e 67 20 74 6f 0a 64 6f 20 61 20 22  having to.do a "
1f70: 3c 74 74 3e 5b 6c 69 6e 64 65 78 26 6e 62 73 70  <tt>[lindex&nbsp
1f80: 3b 2e 2e 2e 26 6e 62 73 70 3b 30 5d 3c 2f 74 74  ;...&nbsp;0]</tt
1f90: 3e 22 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74  >" on the result
1fa0: 73 20 6f 66 20 61 6e 20 22 65 76 61 6c 22 0a 69  s of an "eval".i
1fb0: 6e 20 6f 72 64 65 72 20 74 6f 20 65 78 74 72 61  n order to extra
1fc0: 63 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ct a single colu
1fd0: 6d 6e 20 72 65 73 75 6c 74 2e 3c 2f 70 3e 0a 0a  mn result.</p>..
1fe0: 3c 68 32 3e 54 68 65 20 22 63 68 61 6e 67 65 73  <h2>The "changes
1ff0: 22 20 6d 65 74 68 6f 64 3c 2f 68 32 3e 0a 0a 3c  " method</h2>..<
2000: 70 3e 54 68 65 20 22 63 68 61 6e 67 65 73 22 20  p>The "changes" 
2010: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
2020: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
2030: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
2040: 20 72 6f 77 73 0a 69 6e 20 74 68 65 20 64 61 74   rows.in the dat
2050: 61 62 61 73 65 20 74 68 61 74 20 77 65 72 65 20  abase that were 
2060: 69 6e 73 65 72 74 65 64 2c 20 64 65 6c 65 74 65  inserted, delete
2070: 64 2c 20 61 6e 64 2f 6f 72 20 6d 6f 64 69 66 69  d, and/or modifi
2080: 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 0a 72  ed by the most.r
2090: 65 63 65 6e 74 20 22 65 76 61 6c 22 20 6d 65 74  ecent "eval" met
20a0: 68 6f 64 2e 3c 2f 70 3e 0a 0a 7d 0a 0a 70 75 74  hod.</p>..}..put
20b0: 73 20 7b 0a 3c 70 3e 3c 68 72 20 2f 3e 3c 2f 70  s {.<p><hr /></p
20c0: 3e 0a 3c 70 3e 3c 61 20 68 72 65 66 3d 22 69 6e  >.<p><a href="in
20d0: 64 65 78 2e 68 74 6d 6c 22 3e 3c 69 6d 67 20 73  dex.html"><img s
20e0: 72 63 3d 22 2f 67 6f 62 61 63 6b 2e 6a 70 67 22  rc="/goback.jpg"
20f0: 20 62 6f 72 64 65 72 3d 30 20 2f 3e 0a 42 61 63   border=0 />.Bac
2100: 6b 20 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20  k to the SQLite 
2110: 48 6f 6d 65 20 50 61 67 65 3c 2f 61 3e 0a 3c 2f  Home Page</a>.</
2120: 70 3e 0a 0a 3c 2f 62 6f 64 79 3e 3c 2f 68 74 6d  p>..</body></htm
2130: 6c 3e 7d 0a                                      l>}.