Documentation Source Text

Hex Artifact Content
Login

Artifact 2099d0357917d5f4fd88b7ab22a38ecdfb6632419f20c4e874ccc8565058369e:


0000: 3c 74 69 74 6c 65 3e 54 68 65 20 54 63 6c 20 69  <title>The Tcl i
0010: 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
0020: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 3c 2f  SQLite library</
0030: 74 69 74 6c 65 3e 0a 3c 74 63 6c 3e 0a 68 64 5f  title>.<tcl>.hd_
0040: 6b 65 79 77 6f 72 64 73 20 7b 54 63 6c 20 65 78  keywords {Tcl ex
0050: 74 65 6e 73 69 6f 6e 7d 20 7b 54 43 4c 20 49 6e  tension} {TCL In
0060: 74 65 72 66 61 63 65 7d 0a 70 72 6f 63 20 4d 45  terface}.proc ME
0070: 54 48 4f 44 20 7b 6e 61 6d 65 20 74 65 78 74 7d  THOD {name text}
0080: 20 7b 0a 20 20 68 64 5f 66 72 61 67 6d 65 6e 74   {.  hd_fragment
0090: 20 24 6e 61 6d 65 20 5b 6c 69 73 74 20 24 6e 61   $name [list $na
00a0: 6d 65 20 6d 65 74 68 6f 64 5d 20 5b 6c 69 73 74  me method] [list
00b0: 20 54 43 4c 20 69 6e 74 65 72 66 61 63 65 20 24   TCL interface $
00c0: 6e 61 6d 65 20 6d 65 74 68 6f 64 5d 0a 20 20 68  name method].  h
00d0: 64 5f 70 75 74 73 20 22 3c 68 33 3e 54 68 65 20  d_puts "<h3>The 
00e0: 5c 22 24 6e 61 6d 65 5c 22 20 6d 65 74 68 6f 64  \"$name\" method
00f0: 3c 2f 68 33 3e 5c 6e 22 0a 20 20 68 64 5f 72 65  </h3>\n".  hd_re
0100: 73 6f 6c 76 65 20 24 74 65 78 74 0a 7d 0a 3c 2f  solve $text.}.</
0110: 74 63 6c 3e 0a 0a 3c 68 31 20 61 6c 69 67 6e 3d  tcl>..<h1 align=
0120: 63 65 6e 74 65 72 3e 54 68 65 20 54 63 6c 20 69  center>The Tcl i
0130: 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
0140: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 3c 2f  SQLite library</
0150: 68 31 3e 0a 0a 3c 70 3e 54 68 65 20 53 51 4c 69  h1>..<p>The SQLi
0160: 74 65 20 6c 69 62 72 61 72 79 20 69 73 20 64 65  te library is de
0170: 73 69 67 6e 65 64 20 74 6f 20 62 65 20 76 65 72  signed to be ver
0180: 79 20 65 61 73 79 20 74 6f 20 75 73 65 20 66 72  y easy to use fr
0190: 6f 6d 0a 61 20 5b 68 74 74 70 3a 2f 2f 77 77 77  om.a [http://www
01a0: 2e 74 63 6c 2d 6c 61 6e 67 2e 6f 72 67 20 7c 20  .tcl-lang.org | 
01b0: 54 63 6c 20 6f 72 20 54 63 6c 2f 54 6b 5d 20 73  Tcl or Tcl/Tk] s
01c0: 63 72 69 70 74 2e 20 20 53 51 4c 69 74 65 0a 62  cript.  SQLite.b
01d0: 65 67 61 6e 20 61 73 20 61 20 5b 68 74 74 70 3a  egan as a [http:
01e0: 2f 2f 77 77 77 2e 74 63 6c 2d 6c 61 6e 67 2e 6f  //www.tcl-lang.o
01f0: 72 67 2f 64 6f 63 2f 74 65 61 2f 20 7c 20 54 63  rg/doc/tea/ | Tc
0200: 6c 20 65 78 74 65 6e 73 69 6f 6e 5d 0a 61 6e 64  l extension].and
0210: 20 74 68 65 20 70 72 69 6d 61 72 79 20 5b 74 65   the primary [te
0220: 73 74 20 73 75 69 74 65 5d 20 66 6f 72 20 53 51  st suite] for SQ
0230: 4c 69 74 65 20 69 73 20 77 72 69 74 74 65 6e 20  Lite is written 
0240: 69 6e 20 54 43 4c 2e 20 20 53 51 4c 69 74 65 0a  in TCL.  SQLite.
0250: 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
0260: 20 61 6e 79 20 70 72 6f 67 72 61 6d 6d 69 6e 67   any programming
0270: 20 6c 61 6e 67 75 61 67 65 2c 20 62 75 74 20 69   language, but i
0280: 74 73 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74  ts connections t
0290: 6f 0a 54 43 4c 20 72 75 6e 20 64 65 65 70 2e 3c  o.TCL run deep.<
02a0: 2f 70 3e 0a 0a 3c 70 3e 54 68 69 73 20 64 6f 63  /p>..<p>This doc
02b0: 75 6d 65 6e 74 20 67 69 76 65 73 20 61 6e 20 6f  ument gives an o
02c0: 76 65 72 76 69 65 77 20 6f 66 20 74 68 65 20 54  verview of the T
02d0: 63 6c 0a 70 72 6f 67 72 61 6d 6d 69 6e 67 20 69  cl.programming i
02e0: 6e 74 65 72 66 61 63 65 20 66 6f 72 20 53 51 4c  nterface for SQL
02f0: 69 74 65 2e 3c 2f 70 3e 0a 0a 3c 68 33 3e 54 68  ite.</p>..<h3>Th
0300: 65 20 41 50 49 3c 2f 68 33 3e 0a 0a 3c 70 3e 54  e API</h3>..<p>T
0310: 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
0320: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
0330: 72 79 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 73  ry consists of s
0340: 69 6e 67 6c 65 0a 74 63 6c 20 63 6f 6d 6d 61 6e  ingle.tcl comman
0350: 64 20 6e 61 6d 65 64 20 3c 62 3e 73 71 6c 69 74  d named <b>sqlit
0360: 65 33 3c 2f 62 3e 0a 42 65 63 61 75 73 65 20 74  e3</b>.Because t
0370: 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 74 68 69  here is only thi
0380: 73 0a 6f 6e 65 20 63 6f 6d 6d 61 6e 64 2c 20 74  s.one command, t
0390: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
03a0: 6e 6f 74 20 70 6c 61 63 65 64 20 69 6e 20 61 20  not placed in a 
03b0: 73 65 70 61 72 61 74 65 0a 6e 61 6d 65 73 70 61  separate.namespa
03c0: 63 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20  ce.</p>..<p>The 
03d0: 3c 62 3e 73 71 6c 69 74 65 33 3c 2f 62 3e 20 63  <b>sqlite3</b> c
03e0: 6f 6d 6d 61 6e 64 20 69 73 20 75 73 65 64 20 61  ommand is used a
03f0: 73 20 66 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a  s follows:</p>..
0400: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 62 3e  <blockquote>.<b>
0410: 73 71 6c 69 74 65 33 3c 2f 62 3e 26 6e 62 73 70  sqlite3</b>&nbsp
0420: 3b 26 6e 62 73 70 3b 3c 69 3e 64 62 63 6d 64 26  ;&nbsp;<i>dbcmd&
0430: 6e 62 73 70 3b 26 6e 62 73 70 3b 64 61 74 61 62  nbsp;&nbsp;datab
0440: 61 73 65 2d 6e 61 6d 65 26 6e 62 73 70 3b 26 6e  ase-name&nbsp;&n
0450: 62 73 70 3b 3f 6f 70 74 69 6f 6e 73 3f 3c 2f 69  bsp;?options?</i
0460: 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  >.</blockquote>.
0470: 0a 3c 70 3e 0a 54 68 65 20 3c 62 3e 73 71 6c 69  .<p>.The <b>sqli
0480: 74 65 33 3c 2f 62 3e 20 63 6f 6d 6d 61 6e 64 20  te3</b> command 
0490: 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 62 61  opens the databa
04a0: 73 65 20 6e 61 6d 65 64 20 69 6e 20 74 68 65 20  se named in the 
04b0: 73 65 63 6f 6e 64 0a 61 72 67 75 6d 65 6e 74 2e  second.argument.
04c0: 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
04d0: 65 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  e does not alrea
04e0: 64 79 20 65 78 69 73 74 2c 20 74 68 65 20 64 65  dy exist, the de
04f0: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 0a 69  fault behavior.i
0500: 73 20 66 6f 72 20 69 74 20 74 6f 20 62 65 20 63  s for it to be c
0510: 72 65 61 74 65 64 20 61 75 74 6f 6d 61 74 69 63  reated automatic
0520: 61 6c 6c 79 20 28 74 68 6f 75 67 68 20 74 68 69  ally (though thi
0530: 73 20 63 61 6e 20 62 65 20 63 68 61 6e 67 65 64  s can be changed
0540: 20 62 79 0a 75 73 69 6e 67 20 74 68 65 20 22 3c   by.using the "<
0550: 62 3e 2d 63 72 65 61 74 65 20 66 61 6c 73 65 3c  b>-create false<
0560: 2f 62 3e 22 20 6f 70 74 69 6f 6e 29 2e 0a 54 68  /b>" option)..Th
0570: 65 20 3c 62 3e 73 71 6c 69 74 65 33 3c 2f 62 3e  e <b>sqlite3</b>
0580: 20 63 6f 6d 6d 61 6e 64 20 61 6c 77 61 79 73 20   command always 
0590: 63 72 65 61 74 65 73 20 61 20 6e 65 77 20 54 63  creates a new Tc
05a0: 6c 0a 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 6f 6e  l.command to con
05b0: 74 72 6f 6c 20 74 68 65 20 64 61 74 61 62 61 73  trol the databas
05c0: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  e.  The name of 
05d0: 74 68 65 20 6e 65 77 20 54 63 6c 20 63 6f 6d 6d  the new Tcl comm
05e0: 61 6e 64 0a 69 73 20 67 69 76 65 6e 20 62 79 20  and.is given by 
05f0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
0600: 6e 74 2e 20 20 54 68 69 73 20 61 70 70 72 6f 61  nt.  This approa
0610: 63 68 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ch is similar to
0620: 20 74 68 65 0a 77 61 79 20 77 69 64 67 65 74 73   the.way widgets
0630: 20 61 72 65 20 63 72 65 61 74 65 64 20 69 6e 20   are created in 
0640: 54 6b 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68  Tk..</p>..<p>.Th
0650: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
0660: 74 61 62 61 73 65 20 69 73 20 75 73 75 61 6c 6c  tabase is usuall
0670: 79 20 6a 75 73 74 20 74 68 65 20 6e 61 6d 65 20  y just the name 
0680: 6f 66 20 61 20 64 69 73 6b 20 66 69 6c 65 20 69  of a disk file i
0690: 6e 20 77 68 69 63 68 0a 74 68 65 20 64 61 74 61  n which.the data
06a0: 62 61 73 65 20 69 73 20 73 74 6f 72 65 64 2e 20  base is stored. 
06b0: 20 49 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   If the name of 
06c0: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
06d0: 0a 74 68 65 20 73 70 65 63 69 61 6c 20 6e 61 6d  .the special nam
06e0: 65 20 22 5b 3a 6d 65 6d 6f 72 79 3a 5d 22 20 74  e "[:memory:]" t
06f0: 68 65 6e 20 61 20 6e 65 77 20 64 61 74 61 62 61  hen a new databa
0700: 73 65 20 69 73 20 63 72 65 61 74 65 64 0a 69 6e  se is created.in
0710: 20 6d 65 6d 6f 72 79 2e 20 20 49 66 20 74 68 65   memory.  If the
0720: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
0730: 61 62 61 73 65 20 69 73 20 61 6e 20 65 6d 70 74  abase is an empt
0740: 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 0a 74  y string, then.t
0750: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 63  he database is c
0760: 72 65 61 74 65 64 20 69 6e 20 61 6e 20 65 6d 70  reated in an emp
0770: 74 79 20 66 69 6c 65 20 74 68 61 74 20 69 73 20  ty file that is 
0780: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
0790: 6c 65 74 65 64 0a 77 68 65 6e 20 74 68 65 20 64  leted.when the d
07a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
07b0: 6f 6e 20 63 6c 6f 73 65 73 2e 20 20 5b 55 52 49  on closes.  [URI
07c0: 20 66 69 6c 65 6e 61 6d 65 73 5d 20 63 61 6e 20   filenames] can 
07d0: 62 65 20 75 73 65 64 20 69 66 0a 74 68 65 20 22  be used if.the "
07e0: 3c 62 3e 2d 75 72 69 20 79 65 73 3c 2f 62 3e 22  <b>-uri yes</b>"
07f0: 20 6f 70 74 69 6f 6e 20 69 73 20 73 75 70 70 6c   option is suppl
0800: 69 65 64 20 6f 6e 20 74 68 65 20 3c 62 3e 73 71  ied on the <b>sq
0810: 6c 69 74 65 33 3c 2f 62 3e 20 63 6f 6d 6d 61 6e  lite3</b> comman
0820: 64 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 4f 70 74  d..</p>..<p>.Opt
0830: 69 6f 6e 73 20 75 6e 64 65 72 73 74 6f 6f 64 20  ions understood 
0840: 62 79 20 74 68 65 20 3c 62 3e 73 71 6c 69 74 65  by the <b>sqlite
0850: 33 3c 2f 62 3e 20 63 6f 6d 6d 61 6e 64 20 69 6e  3</b> command in
0860: 63 6c 75 64 65 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c  clude:.</p>..<bl
0870: 6f 63 6b 71 75 6f 74 65 3e 0a 3c 64 6c 3e 0a 0a  ockquote>.<dl>..
0880: 3c 64 74 3e 3c 62 3e 2d 63 72 65 61 74 65 3c 2f  <dt><b>-create</
0890: 62 3e 20 3c 69 3e 42 4f 4f 4c 45 41 4e 3c 2f 69  b> <i>BOOLEAN</i
08a0: 3e 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 0a 49  ></dt>.<dd><p>.I
08b0: 66 20 74 72 75 65 2c 20 74 68 65 6e 20 61 20 6e  f true, then a n
08c0: 65 77 20 64 61 74 61 62 61 73 65 20 69 73 20 63  ew database is c
08d0: 72 65 61 74 65 64 20 69 66 20 6f 6e 65 20 64 6f  reated if one do
08e0: 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
08f0: 78 69 73 74 2e 0a 49 66 20 66 61 6c 73 65 2c 20  xist..If false, 
0900: 74 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 74 20  then an attempt 
0910: 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
0920: 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65  se file that doe
0930: 73 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79  s not previously
0940: 0a 65 78 69 73 74 20 72 61 69 73 65 73 20 61 6e  .exist raises an
0950: 20 65 72 72 6f 72 2e 20 20 54 68 65 20 64 65 66   error.  The def
0960: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73  ault behavior is
0970: 20 22 74 72 75 65 22 2e 0a 3c 2f 70 3e 3c 2f 64   "true"..</p></d
0980: 64 3e 0a 0a 3c 64 74 3e 3c 62 3e 2d 6e 6f 6d 75  d>..<dt><b>-nomu
0990: 74 65 78 3c 2f 62 3e 20 3c 69 3e 42 4f 4f 4c 45  tex</b> <i>BOOLE
09a0: 41 4e 3c 2f 69 3e 3c 2f 64 74 3e 0a 3c 64 64 3e  AN</i></dt>.<dd>
09b0: 3c 70 3e 0a 49 66 20 74 72 75 65 2c 20 74 68 65  <p>.If true, the
09c0: 6e 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 66 6f  n all mutexes fo
09d0: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  r the database c
09e0: 6f 6e 6e 65 63 74 69 6f 6e 20 61 72 65 20 64 69  onnection are di
09f0: 73 61 62 6c 65 64 2e 0a 54 68 69 73 20 70 72 6f  sabled..This pro
0a00: 76 69 64 65 73 20 61 20 73 6d 61 6c 6c 20 70 65  vides a small pe
0a10: 72 66 6f 72 6d 61 6e 63 65 20 62 6f 6f 73 74 20  rformance boost 
0a20: 69 6e 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  in single-thread
0a30: 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 2e  ed applications.
0a40: 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 0a 3c 64 74 3e  .</p></dd>..<dt>
0a50: 3c 62 3e 2d 72 65 61 64 6f 6e 6c 79 3c 2f 62 3e  <b>-readonly</b>
0a60: 20 3c 69 3e 42 4f 4f 4c 45 41 4e 3c 2f 69 3e 3c   <i>BOOLEAN</i><
0a70: 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 0a 49 66 20  /dt>.<dd><p>.If 
0a80: 74 72 75 65 2c 20 74 68 65 6e 20 6f 70 65 6e 20  true, then open 
0a90: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
0aa0: 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 49 66  e read-only.  If
0ab0: 20 66 61 6c 73 65 2c 20 74 68 65 6e 20 74 68 65   false, then the
0ac0: 0a 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65  .database is ope
0ad0: 6e 65 64 20 66 6f 72 20 62 6f 74 68 20 72 65 61  ned for both rea
0ae0: 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
0af0: 20 69 66 20 66 69 6c 65 73 79 73 74 65 6d 20 70   if filesystem p
0b00: 65 72 6d 69 73 73 69 6f 6e 73 0a 61 6c 6c 6f 77  ermissions.allow
0b10: 2c 20 6f 72 20 66 6f 72 20 72 65 61 64 69 6e 67  , or for reading
0b20: 20 6f 6e 6c 79 20 69 66 20 66 69 6c 65 73 79 73   only if filesys
0b30: 74 65 6d 20 77 72 69 74 65 20 70 65 72 6d 69 73  tem write permis
0b40: 73 69 6f 6e 20 69 73 20 64 65 6e 69 65 64 0a 62  sion is denied.b
0b50: 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
0b60: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 64 65 66  system.  The def
0b70: 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20  ault setting is 
0b80: 22 66 61 6c 73 65 22 2e 20 20 4e 6f 74 65 20 74  "false".  Note t
0b90: 68 61 74 0a 69 66 20 74 68 65 20 70 72 65 76 69  hat.if the previ
0ba0: 6f 75 73 20 70 72 6f 63 65 73 73 20 74 6f 20 68  ous process to h
0bb0: 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ave the database
0bc0: 20 64 69 64 20 6e 6f 74 20 65 78 69 74 20 63 6c   did not exit cl
0bd0: 65 61 6e 6c 79 0a 61 6e 64 20 6c 65 66 74 20 62  eanly.and left b
0be0: 65 68 69 6e 64 20 61 20 5b 68 6f 74 20 6a 6f 75  ehind a [hot jou
0bf0: 72 6e 61 6c 5d 2c 20 74 68 65 6e 20 74 68 65 20  rnal], then the 
0c00: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e  write permission
0c10: 20 69 73 20 72 65 71 75 69 72 65 64 0a 74 6f 20   is required.to 
0c20: 72 65 63 6f 76 65 72 20 74 68 65 20 64 61 74 61  recover the data
0c30: 62 61 73 65 20 61 66 74 65 72 20 6f 70 65 6e 69  base after openi
0c40: 6e 67 2c 20 61 6e 64 20 74 68 65 20 64 61 74 61  ng, and the data
0c50: 62 61 73 65 20 63 61 6e 6e 6f 74 20 62 65 0a 6f  base cannot be.o
0c60: 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 2e  pened read-only.
0c70: 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 0a 3c 64 74 3e  .</p></dd>..<dt>
0c80: 3c 62 3e 2d 75 72 69 3c 2f 62 3e 20 3c 69 3e 42  <b>-uri</b> <i>B
0c90: 4f 4f 4c 45 41 4e 3c 2f 69 3e 3c 2f 64 74 3e 0a  OOLEAN</i></dt>.
0ca0: 3c 64 64 3e 3c 70 3e 0a 49 66 20 74 72 75 65 2c  <dd><p>.If true,
0cb0: 20 74 68 65 6e 20 69 6e 74 65 72 70 72 65 74 20   then interpret 
0cc0: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
0cd0: 75 6d 65 6e 74 20 61 73 20 61 20 5b 55 52 49 20  ument as a [URI 
0ce0: 66 69 6c 65 6e 61 6d 65 5d 2e 20 20 49 66 0a 66  filename].  If.f
0cf0: 61 6c 73 65 2c 20 74 68 65 6e 20 74 68 65 20 61  alse, then the a
0d00: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 6c 69 74  rgument is a lit
0d10: 65 72 61 6c 20 66 69 6c 65 6e 61 6d 65 2e 20 20  eral filename.  
0d20: 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
0d30: 65 20 69 73 0a 22 66 61 6c 73 65 22 2e 0a 3c 2f  e is."false"..</
0d40: 70 3e 3c 2f 64 64 3e 0a 0a 3c 64 74 3e 3c 62 3e  p></dd>..<dt><b>
0d50: 2d 76 66 73 3c 2f 62 3e 20 3c 69 3e 56 46 53 4e  -vfs</b> <i>VFSN
0d60: 41 4d 45 3c 2f 69 3e 3c 2f 64 74 3e 0a 3c 64 64  AME</i></dt>.<dd
0d70: 3e 3c 70 3e 0a 55 73 65 20 61 6e 20 61 6c 74 65  ><p>.Use an alte
0d80: 72 6e 61 74 69 76 65 20 5b 56 46 53 5d 20 6e 61  rnative [VFS] na
0d90: 6d 65 64 20 62 79 20 74 68 65 20 61 72 67 75 6d  med by the argum
0da0: 65 6e 74 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 0a  ent..</p></dd>..
0db0: 3c 2f 64 6c 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f  </dl>.</blockquo
0dc0: 74 65 3e 0a 0a 3c 74 63 6c 3e 0a 73 65 74 20 6d  te>..<tcl>.set m
0dd0: 65 74 68 6f 64 5f 6c 69 73 74 20 5b 6c 73 6f 72  ethod_list [lsor
0de0: 74 20 7b 0a 20 61 75 74 68 6f 72 69 7a 65 72 0a  t {. authorizer.
0df0: 20 62 61 63 6b 75 70 0a 20 62 69 6e 64 5f 66 61   backup. bind_fa
0e00: 6c 6c 62 61 63 6b 0a 20 62 75 73 79 0a 20 63 61  llback. busy. ca
0e10: 63 68 65 0a 20 63 68 61 6e 67 65 73 0a 20 63 6c  che. changes. cl
0e20: 6f 73 65 0a 20 63 6f 6c 6c 61 74 65 0a 20 63 6f  ose. collate. co
0e30: 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 0a 20  llation_needed. 
0e40: 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 0a 20 63 6f 6d  commit_hook. com
0e50: 70 6c 65 74 65 0a 20 63 6f 70 79 0a 20 64 65 73  plete. copy. des
0e60: 65 72 69 61 6c 69 7a 65 0a 20 65 6e 61 62 6c 65  erialize. enable
0e70: 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 0a  _load_extension.
0e80: 20 65 72 72 6f 72 63 6f 64 65 0a 20 65 76 61 6c   errorcode. eval
0e90: 0a 20 65 78 69 73 74 73 0a 20 66 75 6e 63 74 69  . exists. functi
0ea0: 6f 6e 0a 20 69 6e 63 72 62 6c 6f 62 0a 20 69 6e  on. incrblob. in
0eb0: 74 65 72 72 75 70 74 0a 20 6c 61 73 74 5f 69 6e  terrupt. last_in
0ec0: 73 65 72 74 5f 72 6f 77 69 64 0a 20 6e 75 6c 6c  sert_rowid. null
0ed0: 76 61 6c 75 65 0a 20 6f 6e 65 63 6f 6c 75 6d 6e  value. onecolumn
0ee0: 0a 20 70 72 65 75 70 64 61 74 65 0a 20 70 72 6f  . preupdate. pro
0ef0: 66 69 6c 65 0a 20 70 72 6f 67 72 65 73 73 0a 20  file. progress. 
0f00: 72 65 73 74 6f 72 65 0a 20 72 6f 6c 6c 62 61 63  restore. rollbac
0f10: 6b 5f 68 6f 6f 6b 0a 20 73 65 72 69 61 6c 69 7a  k_hook. serializ
0f20: 65 0a 20 73 74 61 74 75 73 0a 20 74 69 6d 65 6f  e. status. timeo
0f30: 75 74 0a 20 74 6f 74 61 6c 5f 63 68 61 6e 67 65  ut. total_change
0f40: 73 0a 20 74 72 61 63 65 0a 20 74 72 61 63 65 5f  s. trace. trace_
0f50: 76 32 0a 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  v2. transaction.
0f60: 20 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 0a 20   unlock_notify. 
0f70: 75 70 64 61 74 65 5f 68 6f 6f 6b 0a 20 76 65 72  update_hook. ver
0f80: 73 69 6f 6e 0a 20 77 61 6c 5f 68 6f 6f 6b 0a 7d  sion. wal_hook.}
0f90: 5d 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 0a 4f 6e  ].</tcl>..<p>.On
0fa0: 63 65 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  ce an SQLite dat
0fb0: 61 62 61 73 65 20 69 73 20 6f 70 65 6e 2c 20 69  abase is open, i
0fc0: 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 72 6f 6c  t can be control
0fd0: 6c 65 64 20 75 73 69 6e 67 20 0a 6d 65 74 68 6f  led using .metho
0fe0: 64 73 20 6f 66 20 74 68 65 20 3c 69 3e 64 62 63  ds of the <i>dbc
0ff0: 6d 64 3c 2f 69 3e 2e 0a 3c 74 63 6c 3e 0a 68 64  md</i>..<tcl>.hd
1000: 5f 70 75 74 73 20 22 54 68 65 72 65 20 61 72 65  _puts "There are
1010: 20 63 75 72 72 65 6e 74 6c 79 20 5b 6c 6c 65 6e   currently [llen
1020: 67 74 68 20 24 6d 65 74 68 6f 64 5f 6c 69 73 74  gth $method_list
1030: 5d 20 6d 65 74 68 6f 64 73 5c 6e 22 0a 68 64 5f  ] methods\n".hd_
1040: 70 75 74 73 20 22 64 65 66 69 6e 65 64 2e 3c 2f  puts "defined.</
1050: 70 3e 5c 6e 22 0a 3c 2f 74 63 6c 3e 0a 0a 3c 74  p>\n".</tcl>..<t
1060: 61 62 6c 65 20 62 6f 72 64 65 72 3d 30 20 63 65  able border=0 ce
1070: 6c 6c 70 61 64 64 69 6e 67 3d 31 30 20 77 69 64  llpadding=10 wid
1080: 74 68 3d 27 31 30 30 25 27 3e 0a 3c 74 72 3e 3c  th='100%'>.<tr><
1090: 74 64 20 76 61 6c 69 67 6e 3d 27 74 6f 70 27 3e  td valign='top'>
10a0: 3c 75 6c 3e 0a 3c 74 63 6c 3e 0a 73 65 74 20 6e  <ul>.<tcl>.set n
10b0: 62 72 20 5b 65 78 70 72 20 7b 69 6e 74 28 28 5b  br [expr {int(([
10c0: 6c 6c 65 6e 67 74 68 20 24 6d 65 74 68 6f 64 5f  llength $method_
10d0: 6c 69 73 74 5d 2b 32 29 2f 33 29 7d 5d 0a 73 65  list]+2)/3)}].se
10e0: 74 20 69 20 2d 31 0a 66 6f 72 65 61 63 68 20 6d  t i -1.foreach m
10f0: 20 24 6d 65 74 68 6f 64 5f 6c 69 73 74 20 7b 0a   $method_list {.
1100: 20 20 69 6e 63 72 20 69 0a 20 20 69 66 20 7b 24    incr i.  if {$
1110: 69 3d 3d 24 6e 62 72 7d 20 7b 0a 20 20 20 20 68  i==$nbr} {.    h
1120: 64 5f 70 75 74 73 20 22 3c 2f 75 6c 3e 3c 2f 74  d_puts "</ul></t
1130: 64 3e 5c 6e 3c 74 64 20 76 61 6c 69 67 6e 3d 27  d>\n<td valign='
1140: 74 6f 70 27 3e 3c 75 6c 3e 5c 6e 22 0a 20 20 20  top'><ul>\n".   
1150: 20 73 65 74 20 69 20 30 0a 20 20 7d 0a 20 20 68   set i 0.  }.  h
1160: 64 5f 70 75 74 73 20 22 3c 6c 69 3e 3c 61 20 68  d_puts "<li><a h
1170: 72 65 66 3d 5c 22 23 24 6d 5c 22 3e 24 6d 3c 2f  ref=\"#$m\">$m</
1180: 61 3e 3c 2f 6c 69 3e 5c 6e 22 0a 7d 0a 3c 2f 74  a></li>\n".}.</t
1190: 63 6c 3e 0a 3c 2f 75 6c 3e 3c 2f 74 64 3e 3c 2f  cl>.</ul></td></
11a0: 74 72 3e 0a 3c 2f 74 61 62 6c 65 3e 0a 0a 0a 3c  tr>.</table>...<
11b0: 70 3e 54 68 65 20 75 73 65 20 6f 66 20 65 61 63  p>The use of eac
11c0: 68 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f  h of these metho
11d0: 64 73 20 77 69 6c 6c 20 62 65 20 65 78 70 6c 61  ds will be expla
11e0: 69 6e 65 64 20 69 6e 20 74 68 65 20 73 65 71 75  ined in the sequ
11f0: 65 6c 2c 20 74 68 6f 75 67 68 0a 6e 6f 74 20 69  el, though.not i
1200: 6e 20 74 68 65 20 6f 72 64 65 72 20 73 68 6f 77  n the order show
1210: 6e 20 61 62 6f 76 65 2e 3c 2f 70 3e 0a 0a 3c 74  n above.</p>..<t
1220: 63 6c 3e 0a 23 23 23 23 23 23 23 23 23 23 23 23  cl>.############
1230: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1240: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1250: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1260: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1270: 23 23 0a 4d 45 54 48 4f 44 20 65 76 61 6c 20 7b  ##.METHOD eval {
1280: 0a 3c 70 3e 0a 54 68 65 20 6d 6f 73 74 20 75 73  .<p>.The most us
1290: 65 66 75 6c 20 3c 69 3e 64 62 63 6d 64 3c 2f 69  eful <i>dbcmd</i
12a0: 3e 20 6d 65 74 68 6f 64 20 69 73 20 22 65 76 61  > method is "eva
12b0: 6c 22 2e 20 20 54 68 65 20 65 76 61 6c 20 6d 65  l".  The eval me
12c0: 74 68 6f 64 20 69 73 20 75 73 65 64 0a 74 6f 20  thod is used.to 
12d0: 65 78 65 63 75 74 65 20 53 51 4c 20 6f 6e 20 74  execute SQL on t
12e0: 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  he database.  Th
12f0: 65 20 73 79 6e 74 61 78 20 6f 66 20 74 68 65 20  e syntax of the 
1300: 65 76 61 6c 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b  eval method look
1310: 73 0a 6c 69 6b 65 20 74 68 69 73 3a 3c 2f 70 3e  s.like this:</p>
1320: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c  ..<blockquote>.<
1330: 69 3e 64 62 63 6d 64 3c 2f 69 3e 26 6e 62 73 70  i>dbcmd</i>&nbsp
1340: 3b 26 6e 62 73 70 3b 3c 62 3e 65 76 61 6c 3c 2f  ;&nbsp;<b>eval</
1350: 62 3e 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3f 3c  b>&nbsp;&nbsp;?<
1360: 69 3e 6f 70 74 69 6f 6e 73 3c 2f 69 3e 3f 26 6e  i>options</i>?&n
1370: 62 73 70 3b 26 6e 62 73 70 3b 3c 69 3e 73 71 6c  bsp;&nbsp;<i>sql
1380: 3c 2f 69 3e 0a 26 6e 62 73 70 3b 26 6e 62 73 70  </i>.&nbsp;&nbsp
1390: 3b 3f 3c 69 3e 61 72 72 61 79 2d 6e 61 6d 65 3c  ;?<i>array-name<
13a0: 2f 69 3e 3f 26 6e 62 73 70 3b 26 6e 62 73 70 3b  /i>?&nbsp;&nbsp;
13b0: 3f 3c 69 3e 73 63 72 69 70 74 3c 2f 69 3e 3f 0a  ?<i>script</i>?.
13c0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
13d0: 70 3e 0a 54 68 65 20 6a 6f 62 20 6f 66 20 74 68  p>.The job of th
13e0: 65 20 65 76 61 6c 20 6d 65 74 68 6f 64 20 69 73  e eval method is
13f0: 20 74 6f 20 65 78 65 63 75 74 65 20 74 68 65 20   to execute the 
1400: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
1410: 20 73 74 61 74 65 6d 65 6e 74 73 0a 67 69 76 65   statements.give
1420: 6e 20 69 6e 20 74 68 65 20 73 65 63 6f 6e 64 20  n in the second 
1430: 61 72 67 75 6d 65 6e 74 2e 20 20 46 6f 72 20 65  argument.  For e
1440: 78 61 6d 70 6c 65 2c 20 74 6f 20 63 72 65 61 74  xample, to creat
1450: 65 20 61 20 6e 65 77 20 74 61 62 6c 65 20 69 6e  e a new table in
1460: 0a 61 20 64 61 74 61 62 61 73 65 2c 20 79 6f 75  .a database, you
1470: 20 63 61 6e 20 64 6f 20 74 68 69 73 3a 3c 2f 70   can do this:</p
1480: 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  >..<blockquote>.
1490: 3c 62 3e 73 71 6c 69 74 65 33 20 64 62 31 20 2e  <b>sqlite3 db1 .
14a0: 2f 74 65 73 74 64 62 3c 62 72 3e 0a 64 62 31 20  /testdb<br>.db1 
14b0: 65 76 61 6c 20 7b 43 52 45 41 54 45 20 54 41 42  eval {CREATE TAB
14c0: 4c 45 20 74 31 28 61 20 69 6e 74 2c 20 62 20 74  LE t1(a int, b t
14d0: 65 78 74 29 7d 3c 2f 62 3e 0a 3c 2f 62 6c 6f 63  ext)}</b>.</bloc
14e0: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 20  kquote>..<p>The 
14f0: 61 62 6f 76 65 20 63 6f 64 65 20 63 72 65 61 74  above code creat
1500: 65 73 20 61 20 6e 65 77 20 74 61 62 6c 65 20 6e  es a new table n
1510: 61 6d 65 64 20 3c 62 3e 74 31 3c 2f 62 3e 20 77  amed <b>t1</b> w
1520: 69 74 68 20 63 6f 6c 75 6d 6e 73 0a 3c 62 3e 61  ith columns.<b>a
1530: 3c 2f 62 3e 20 61 6e 64 20 3c 62 3e 62 3c 2f 62  </b> and <b>b</b
1540: 3e 2e 20 20 57 68 61 74 20 63 6f 75 6c 64 20 62  >.  What could b
1550: 65 20 73 69 6d 70 6c 65 72 3f 3c 2f 70 3e 0a 0a  e simpler?</p>..
1560: 3c 70 3e 51 75 65 72 79 20 72 65 73 75 6c 74 73  <p>Query results
1570: 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 61 73   are returned as
1580: 20 61 20 6c 69 73 74 20 6f 66 20 63 6f 6c 75 6d   a list of colum
1590: 6e 20 76 61 6c 75 65 73 2e 20 20 49 66 20 61 0a  n values.  If a.
15a0: 71 75 65 72 79 20 72 65 71 75 65 73 74 73 20 32  query requests 2
15b0: 20 63 6f 6c 75 6d 6e 73 20 61 6e 64 20 74 68 65   columns and the
15c0: 72 65 20 61 72 65 20 33 20 72 6f 77 73 20 6d 61  re are 3 rows ma
15d0: 74 63 68 69 6e 67 20 74 68 65 20 71 75 65 72 79  tching the query
15e0: 2c 0a 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  ,.then the retur
15f0: 6e 65 64 20 6c 69 73 74 20 77 69 6c 6c 20 63 6f  ned list will co
1600: 6e 74 61 69 6e 20 36 20 65 6c 65 6d 65 6e 74 73  ntain 6 elements
1610: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 3c  .  For example:<
1620: 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  /p>..<blockquote
1630: 3e 0a 3c 62 3e 64 62 31 20 65 76 61 6c 20 7b 49  >.<b>db1 eval {I
1640: 4e 53 45 52 54 20 49 4e 54 4f 20 74 31 20 56 41  NSERT INTO t1 VA
1650: 4c 55 45 53 28 31 2c 27 68 65 6c 6c 6f 27 29 7d  LUES(1,'hello')}
1660: 3c 62 72 3e 0a 64 62 31 20 65 76 61 6c 20 7b 49  <br>.db1 eval {I
1670: 4e 53 45 52 54 20 49 4e 54 4f 20 74 31 20 56 41  NSERT INTO t1 VA
1680: 4c 55 45 53 28 32 2c 27 67 6f 6f 64 62 79 65 27  LUES(2,'goodbye'
1690: 29 7d 3c 62 72 3e 0a 64 62 31 20 65 76 61 6c 20  )}<br>.db1 eval 
16a0: 7b 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 31 20  {INSERT INTO t1 
16b0: 56 41 4c 55 45 53 28 33 2c 27 68 6f 77 64 79 21  VALUES(3,'howdy!
16c0: 27 29 7d 3c 62 72 3e 0a 73 65 74 20 78 20 26 23  ')}<br>.set x &#
16d0: 39 31 3b 64 62 31 20 65 76 61 6c 20 7b 53 45 4c  91;db1 eval {SEL
16e0: 45 43 54 20 2a 20 46 52 4f 4d 20 74 31 20 4f 52  ECT * FROM t1 OR
16f0: 44 45 52 20 42 59 20 61 7d 26 23 39 33 3b 3c 2f  DER BY a}&#93;</
1700: 62 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  b>.</blockquote>
1710: 0a 0a 3c 70 3e 54 68 65 20 76 61 72 69 61 62 6c  ..<p>The variabl
1720: 65 20 3c 62 3e 24 78 3c 2f 62 3e 20 69 73 20 73  e <b>$x</b> is s
1730: 65 74 20 62 79 20 74 68 65 20 61 62 6f 76 65 20  et by the above 
1740: 63 6f 64 65 20 74 6f 3c 2f 70 3e 0a 0a 3c 62 6c  code to</p>..<bl
1750: 6f 63 6b 71 75 6f 74 65 3e 0a 3c 62 3e 31 20 68  ockquote>.<b>1 h
1760: 65 6c 6c 6f 20 32 20 67 6f 6f 64 62 79 65 20 33  ello 2 goodbye 3
1770: 20 68 6f 77 64 79 21 3c 2f 62 3e 0a 3c 2f 62 6c   howdy!</b>.</bl
1780: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 59 6f  ockquote>..<p>Yo
1790: 75 20 63 61 6e 20 61 6c 73 6f 20 70 72 6f 63 65  u can also proce
17a0: 73 73 20 74 68 65 20 72 65 73 75 6c 74 73 20 6f  ss the results o
17b0: 66 20 61 20 71 75 65 72 79 20 6f 6e 65 20 72 6f  f a query one ro
17c0: 77 20 61 74 20 61 20 74 69 6d 65 0a 62 79 20 73  w at a time.by s
17d0: 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 6e 61  pecifying the na
17e0: 6d 65 20 6f 66 20 61 6e 20 61 72 72 61 79 20 76  me of an array v
17f0: 61 72 69 61 62 6c 65 20 61 6e 64 20 61 20 73 63  ariable and a sc
1800: 72 69 70 74 20 66 6f 6c 6c 6f 77 69 6e 67 0a 74  ript following.t
1810: 68 65 20 53 51 4c 20 63 6f 64 65 2e 20 20 46 6f  he SQL code.  Fo
1820: 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68  r each row of th
1830: 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 2c 20  e query result, 
1840: 74 68 65 20 76 61 6c 75 65 73 20 6f 66 20 61 6c  the values of al
1850: 6c 0a 63 6f 6c 75 6d 6e 73 20 77 69 6c 6c 20 62  l.columns will b
1860: 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20  e inserted into 
1870: 74 68 65 20 61 72 72 61 79 20 76 61 72 69 61 62  the array variab
1880: 6c 65 20 61 6e 64 20 74 68 65 20 73 63 72 69 70  le and the scrip
1890: 74 20 77 69 6c 6c 0a 62 65 20 65 78 65 63 75 74  t will.be execut
18a0: 65 64 2e 20 20 46 6f 72 20 69 6e 73 74 61 6e 63  ed.  For instanc
18b0: 65 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  e:</p>..<blockqu
18c0: 6f 74 65 3e 0a 3c 62 3e 64 62 31 20 65 76 61 6c  ote>.<b>db1 eval
18d0: 20 7b 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20   {SELECT * FROM 
18e0: 74 31 20 4f 52 44 45 52 20 42 59 20 61 7d 20 76  t1 ORDER BY a} v
18f0: 61 6c 75 65 73 20 7b 3c 62 72 3e 0a 26 6e 62 73  alues {<br>.&nbs
1900: 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  p;&nbsp;&nbsp;&n
1910: 62 73 70 3b 70 61 72 72 61 79 20 76 61 6c 75 65  bsp;parray value
1920: 73 3c 62 72 3e 0a 26 6e 62 73 70 3b 26 6e 62 73  s<br>.&nbsp;&nbs
1930: 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 70 75  p;&nbsp;&nbsp;pu
1940: 74 73 20 22 22 3c 62 72 3e 0a 7d 3c 2f 62 3e 0a  ts ""<br>.}</b>.
1950: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
1960: 70 3e 54 68 69 73 20 6c 61 73 74 20 63 6f 64 65  p>This last code
1970: 20 77 69 6c 6c 20 67 69 76 65 20 74 68 65 20 66   will give the f
1980: 6f 6c 6c 6f 77 69 6e 67 20 6f 75 74 70 75 74 3a  ollowing output:
1990: 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  </p>..<blockquot
19a0: 65 3e 3c 62 3e 0a 76 61 6c 75 65 73 28 2a 29 20  e><b>.values(*) 
19b0: 3d 20 61 20 62 3c 62 72 3e 0a 76 61 6c 75 65 73  = a b<br>.values
19c0: 28 61 29 20 3d 20 31 3c 62 72 3e 0a 76 61 6c 75  (a) = 1<br>.valu
19d0: 65 73 28 62 29 20 3d 20 68 65 6c 6c 6f 3c 70 3e  es(b) = hello<p>
19e0: 0a 0a 76 61 6c 75 65 73 28 2a 29 20 3d 20 61 20  ..values(*) = a 
19f0: 62 3c 62 72 3e 0a 76 61 6c 75 65 73 28 61 29 20  b<br>.values(a) 
1a00: 3d 20 32 3c 62 72 3e 0a 76 61 6c 75 65 73 28 62  = 2<br>.values(b
1a10: 29 20 3d 20 67 6f 6f 64 62 79 65 3c 70 3e 0a 0a  ) = goodbye<p>..
1a20: 76 61 6c 75 65 73 28 2a 29 20 3d 20 61 20 62 3c  values(*) = a b<
1a30: 62 72 3e 0a 76 61 6c 75 65 73 28 61 29 20 3d 20  br>.values(a) = 
1a40: 33 3c 62 72 3e 0a 76 61 6c 75 65 73 28 62 29 20  3<br>.values(b) 
1a50: 3d 20 68 6f 77 64 79 21 3c 2f 62 3e 0a 3c 2f 62  = howdy!</b>.</b
1a60: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a  lockquote>..<p>.
1a70: 46 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20  For each column 
1a80: 69 6e 20 61 20 72 6f 77 20 6f 66 20 74 68 65 20  in a row of the 
1a90: 72 65 73 75 6c 74 2c 20 74 68 65 20 6e 61 6d 65  result, the name
1aa0: 20 6f 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a   of that column.
1ab0: 69 73 20 75 73 65 64 20 61 73 20 61 6e 20 69 6e  is used as an in
1ac0: 64 65 78 20 69 6e 20 74 6f 20 61 72 72 61 79 20  dex in to array 
1ad0: 61 6e 64 20 74 68 65 20 76 61 6c 75 65 20 6f 66  and the value of
1ae0: 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73   the column is s
1af0: 74 6f 72 65 64 0a 69 6e 20 74 68 65 20 63 6f 72  tored.in the cor
1b00: 72 65 73 70 6f 6e 64 69 6e 67 20 61 72 72 61 79  responding array
1b10: 20 65 6e 74 72 79 2e 20 20 28 43 61 75 74 69 6f   entry.  (Cautio
1b20: 6e 3a 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  n:  If two or mo
1b30: 72 65 20 63 6f 6c 75 6d 6e 73 0a 69 6e 20 74 68  re columns.in th
1b40: 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
1b50: 61 20 71 75 65 72 79 20 68 61 76 65 20 74 68 65  a query have the
1b60: 20 73 61 6d 65 20 6e 61 6d 65 2c 20 74 68 65 6e   same name, then
1b70: 20 74 68 65 20 6c 61 73 74 20 63 6f 6c 75 6d 6e   the last column
1b80: 0a 77 69 74 68 20 74 68 61 74 20 6e 61 6d 65 20  .with that name 
1b90: 77 69 6c 6c 20 6f 76 65 72 77 72 69 74 65 20 70  will overwrite p
1ba0: 72 69 6f 72 20 76 61 6c 75 65 73 20 61 6e 64 20  rior values and 
1bb0: 65 61 72 6c 69 65 72 20 63 6f 6c 75 6d 6e 73 20  earlier columns 
1bc0: 77 69 74 68 20 74 68 65 0a 73 61 6d 65 20 6e 61  with the.same na
1bd0: 6d 65 20 77 69 6c 6c 20 62 65 20 69 6e 61 63 63  me will be inacc
1be0: 65 73 73 69 62 6c 65 2e 29 20 54 68 65 20 73 70  essible.) The sp
1bf0: 65 63 69 61 6c 20 61 72 72 61 79 20 69 6e 64 65  ecial array inde
1c00: 78 20 2a 20 69 73 0a 75 73 65 64 20 74 6f 20 73  x * is.used to s
1c10: 74 6f 72 65 20 61 20 6c 69 73 74 20 6f 66 20 63  tore a list of c
1c20: 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 20 74  olumn names in t
1c30: 68 65 20 6f 72 64 65 72 20 74 68 61 74 20 74 68  he order that th
1c40: 65 79 20 61 70 70 65 61 72 2e 0a 3c 2f 70 3e 0a  ey appear..</p>.
1c50: 0a 3c 70 3e 0a 4e 6f 72 6d 61 6c 6c 79 2c 20 4e  .<p>.Normally, N
1c60: 55 4c 4c 20 53 51 4c 20 72 65 73 75 6c 74 73 20  ULL SQL results 
1c70: 61 72 65 20 73 74 6f 72 65 64 20 69 6e 20 74 68  are stored in th
1c80: 65 20 61 72 72 61 79 20 75 73 69 6e 67 20 74 68  e array using th
1c90: 65 0a 3c 61 20 68 72 65 66 3d 22 23 6e 75 6c 6c  e.<a href="#null
1ca0: 76 61 6c 75 65 22 3e 6e 75 6c 6c 76 61 6c 75 65  value">nullvalue
1cb0: 3c 2f 61 3e 20 73 65 74 74 69 6e 67 2e 20 20 48  </a> setting.  H
1cc0: 6f 77 65 76 65 72 2c 20 69 66 0a 74 68 65 20 3c  owever, if.the <
1cd0: 62 3e 2d 77 69 74 68 6f 75 74 6e 75 6c 6c 73 3c  b>-withoutnulls<
1ce0: 2f 62 3e 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  /b> option is us
1cf0: 65 64 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 53 51  ed, then NULL SQ
1d00: 4c 20 76 61 6c 75 65 73 0a 63 61 75 73 65 20 74  L values.cause t
1d10: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
1d20: 20 61 72 72 61 79 20 65 6c 65 6d 65 6e 74 20 74   array element t
1d30: 6f 20 62 65 20 75 6e 73 65 74 20 69 6e 73 74 65  o be unset inste
1d40: 61 64 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49 66  ad..</p>..<p>.If
1d50: 20 74 68 65 20 61 72 72 61 79 20 76 61 72 69 61   the array varia
1d60: 62 6c 65 20 6e 61 6d 65 20 69 73 20 6f 6d 69 74  ble name is omit
1d70: 74 65 64 20 6f 72 20 69 73 20 74 68 65 20 65 6d  ted or is the em
1d80: 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
1d90: 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 65 61   the value of.ea
1da0: 63 68 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f  ch column is sto
1db0: 72 65 64 20 69 6e 20 61 20 76 61 72 69 61 62 6c  red in a variabl
1dc0: 65 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  e with the same 
1dd0: 6e 61 6d 65 20 61 73 20 74 68 65 20 63 6f 6c 75  name as the colu
1de0: 6d 6e 0a 69 74 73 65 6c 66 2e 20 20 46 6f 72 20  mn.itself.  For 
1df0: 65 78 61 6d 70 6c 65 3a 0a 3c 2f 70 3e 0a 0a 3c  example:.</p>..<
1e00: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 62 3e 64  blockquote>.<b>d
1e10: 62 31 20 65 76 61 6c 20 7b 53 45 4c 45 43 54 20  b1 eval {SELECT 
1e20: 2a 20 46 52 4f 4d 20 74 31 20 4f 52 44 45 52 20  * FROM t1 ORDER 
1e30: 42 59 20 61 7d 20 7b 3c 62 72 3e 0a 26 6e 62 73  BY a} {<br>.&nbs
1e40: 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  p;&nbsp;&nbsp;&n
1e50: 62 73 70 3b 70 75 74 73 20 22 61 3d 24 61 20 62  bsp;puts "a=$a b
1e60: 3d 24 62 22 3c 62 72 3e 0a 7d 3c 2f 62 3e 0a 3c  =$b"<br>.}</b>.<
1e70: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70  /blockquote>..<p
1e80: 3e 0a 46 72 6f 6d 20 74 68 69 73 20 77 65 20 67  >.From this we g
1e90: 65 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  et the following
1ea0: 20 6f 75 74 70 75 74 0a 3c 2f 70 3e 0a 0a 3c 62   output.</p>..<b
1eb0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 62 3e 0a 61 3d  lockquote><b>.a=
1ec0: 31 20 62 3d 68 65 6c 6c 6f 3c 62 72 3e 0a 61 3d  1 b=hello<br>.a=
1ed0: 32 20 62 3d 67 6f 6f 64 62 79 65 3c 62 72 3e 0a  2 b=goodbye<br>.
1ee0: 61 3d 33 20 62 3d 68 6f 77 64 79 21 3c 2f 62 3e  a=3 b=howdy!</b>
1ef0: 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  .</blockquote>..
1f00: 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
1f10: 20 76 61 72 73 75 62 73 74 20 7b 54 43 4c 20 76   varsubst {TCL v
1f20: 61 72 69 61 62 6c 65 20 73 75 62 73 74 69 74 75  ariable substitu
1f30: 74 69 6f 6e 7d 3c 2f 74 63 6c 3e 0a 3c 70 3e 0a  tion}</tcl>.<p>.
1f40: 54 63 6c 20 76 61 72 69 61 62 6c 65 20 6e 61 6d  Tcl variable nam
1f50: 65 73 20 63 61 6e 20 61 70 70 65 61 72 20 69 6e  es can appear in
1f60: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1f70: 6e 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  nt of the second
1f80: 20 61 72 67 75 6d 65 6e 74 0a 69 6e 20 61 6e 79   argument.in any
1f90: 20 70 6f 73 69 74 69 6f 6e 20 77 68 65 72 65 20   position where 
1fa0: 69 74 20 69 73 20 6c 65 67 61 6c 20 74 6f 20 70  it is legal to p
1fb0: 75 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 6e  ut a string or n
1fc0: 75 6d 62 65 72 20 6c 69 74 65 72 61 6c 2e 20 20  umber literal.  
1fd0: 54 68 65 0a 76 61 6c 75 65 20 6f 66 20 74 68 65  The.value of the
1fe0: 20 76 61 72 69 61 62 6c 65 20 69 73 20 73 75 62   variable is sub
1ff0: 73 74 69 74 75 74 65 64 20 66 6f 72 20 74 68 65  stituted for the
2000: 20 76 61 72 69 61 62 6c 65 20 6e 61 6d 65 2e 20   variable name. 
2010: 20 49 66 20 74 68 65 0a 76 61 72 69 61 62 6c 65   If the.variable
2020: 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20   does not exist 
2030: 61 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 69 73  a NULL values is
2040: 20 75 73 65 64 2e 20 20 46 6f 72 20 65 78 61 6d   used.  For exam
2050: 70 6c 65 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63  ple:.</p>..<bloc
2060: 6b 71 75 6f 74 65 3e 3c 62 3e 0a 64 62 31 20 65  kquote><b>.db1 e
2070: 76 61 6c 20 7b 49 4e 53 45 52 54 20 49 4e 54 4f  val {INSERT INTO
2080: 20 74 31 20 56 41 4c 55 45 53 28 35 2c 24 62 69   t1 VALUES(5,$bi
2090: 67 73 74 72 69 6e 67 29 7d 0a 3c 2f 62 3e 3c 2f  gstring)}.</b></
20a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e  blockquote>..<p>
20b0: 0a 4e 6f 74 65 20 74 68 61 74 20 69 74 20 69 73  .Note that it is
20c0: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 20 74   not necessary t
20d0: 6f 20 71 75 6f 74 65 20 74 68 65 20 24 62 69 67  o quote the $big
20e0: 73 74 72 69 6e 67 20 76 61 6c 75 65 2e 20 20 54  string value.  T
20f0: 68 61 74 20 68 61 70 70 65 6e 73 0a 61 75 74 6f  hat happens.auto
2100: 6d 61 74 69 63 61 6c 6c 79 2e 20 20 49 66 20 24  matically.  If $
2110: 62 69 67 73 74 72 69 6e 67 20 69 73 20 61 20 6c  bigstring is a l
2120: 61 72 67 65 20 73 74 72 69 6e 67 20 6f 72 20 62  arge string or b
2130: 69 6e 61 72 79 20 6f 62 6a 65 63 74 2c 20 74 68  inary object, th
2140: 69 73 0a 74 65 63 68 6e 69 71 75 65 20 69 73 20  is.technique is 
2150: 6e 6f 74 20 6f 6e 6c 79 20 65 61 73 69 65 72 20  not only easier 
2160: 74 6f 20 77 72 69 74 65 2c 20 69 74 20 69 73 20  to write, it is 
2170: 61 6c 73 6f 20 6d 75 63 68 20 6d 6f 72 65 20 65  also much more e
2180: 66 66 69 63 69 65 6e 74 0a 73 69 6e 63 65 20 69  fficient.since i
2190: 74 20 61 76 6f 69 64 73 20 6d 61 6b 69 6e 67 20  t avoids making 
21a0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  a copy of the co
21b0: 6e 74 65 6e 74 20 6f 66 20 24 62 69 67 73 74 72  ntent of $bigstr
21c0: 69 6e 67 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49  ing..</p>..<p>.I
21d0: 66 20 74 68 65 20 24 62 69 67 73 74 72 69 6e 67  f the $bigstring
21e0: 20 76 61 72 69 61 62 6c 65 20 68 61 73 20 62 6f   variable has bo
21f0: 74 68 20 61 20 73 74 72 69 6e 67 20 61 6e 64 20  th a string and 
2200: 61 20 22 62 79 74 65 61 72 72 61 79 22 20 72 65  a "bytearray" re
2210: 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 0a 74 68  presentation,.th
2220: 65 6e 20 54 43 4c 20 69 6e 73 65 72 74 73 20 74  en TCL inserts t
2230: 68 65 20 76 61 6c 75 65 20 61 73 20 61 20 73 74  he value as a st
2240: 72 69 6e 67 2e 20 20 49 66 20 69 74 20 68 61 73  ring.  If it has
2250: 20 6f 6e 6c 79 20 61 20 22 62 79 74 65 61 72 72   only a "bytearr
2260: 61 79 22 0a 72 65 70 72 65 73 65 6e 74 61 74 69  ay".representati
2270: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 76 61 6c  on, then the val
2280: 75 65 20 69 73 20 69 6e 73 65 72 74 65 64 20 61  ue is inserted a
2290: 73 20 61 20 42 4c 4f 42 2e 20 20 54 6f 20 66 6f  s a BLOB.  To fo
22a0: 72 63 65 20 61 0a 76 61 6c 75 65 20 74 6f 20 62  rce a.value to b
22b0: 65 20 69 6e 73 65 72 74 65 64 20 61 73 20 61 20  e inserted as a 
22c0: 42 4c 4f 42 20 65 76 65 6e 20 69 66 20 69 74 20  BLOB even if it 
22d0: 61 6c 73 6f 20 68 61 73 20 61 20 74 65 78 74 20  also has a text 
22e0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 0a  representation,.
22f0: 75 73 65 20 61 20 22 40 22 20 63 68 61 72 61 63  use a "@" charac
2300: 74 65 72 20 74 6f 20 69 6e 20 70 6c 61 63 65 20  ter to in place 
2310: 6f 66 20 74 68 65 20 22 24 22 2e 20 20 4c 69 6b  of the "$".  Lik
2320: 65 20 74 68 69 73 3a 0a 3c 2f 70 3e 0a 0a 3c 62  e this:.</p>..<b
2330: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 62 3e 0a 64 62  lockquote><b>.db
2340: 31 20 65 76 61 6c 20 7b 49 4e 53 45 52 54 20 49  1 eval {INSERT I
2350: 4e 54 4f 20 74 31 20 56 41 4c 55 45 53 28 35 2c  NTO t1 VALUES(5,
2360: 40 62 69 67 73 74 72 69 6e 67 29 7d 0a 3c 2f 62  @bigstring)}.</b
2370: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  ></blockquote>..
2380: 3c 70 3e 0a 49 66 20 74 68 65 20 76 61 72 69 61  <p>.If the varia
2390: 62 6c 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ble does not hav
23a0: 65 20 61 20 62 79 74 65 61 72 72 61 79 20 72 65  e a bytearray re
23b0: 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 74 68  presentation, th
23c0: 65 6e 20 22 40 22 20 77 6f 72 6b 73 0a 6a 75 73  en "@" works.jus
23d0: 74 20 6c 69 6b 65 20 22 24 22 2e 20 20 4e 6f 74  t like "$".  Not
23e0: 65 20 74 68 61 74 20 22 3a 22 20 77 6f 72 6b 73  e that ":" works
23f0: 20 6c 69 6b 65 20 22 24 22 20 69 6e 20 61 6c 6c   like "$" in all
2400: 20 63 61 73 65 73 20 73 6f 20 74 68 65 20 66 6f   cases so the fo
2410: 6c 6c 6f 77 69 6e 67 0a 69 73 20 61 6e 6f 74 68  llowing.is anoth
2420: 65 72 20 77 61 79 20 74 6f 20 65 78 70 72 65 73  er way to expres
2430: 73 20 74 68 65 20 73 61 6d 65 20 73 74 61 74 65  s the same state
2440: 6d 65 6e 74 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f  ment:.</p>..<blo
2450: 63 6b 71 75 6f 74 65 3e 3c 62 3e 0a 64 62 31 20  ckquote><b>.db1 
2460: 65 76 61 6c 20 7b 49 4e 53 45 52 54 20 49 4e 54  eval {INSERT INT
2470: 4f 20 74 31 20 56 41 4c 55 45 53 28 35 2c 3a 62  O t1 VALUES(5,:b
2480: 69 67 73 74 72 69 6e 67 29 7d 0a 3c 2f 62 3e 3c  igstring)}.</b><
2490: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70  /blockquote>..<p
24a0: 3e 54 68 65 20 75 73 65 20 6f 66 20 22 3a 22 20  >The use of ":" 
24b0: 69 6e 73 74 65 61 64 20 6f 66 20 22 24 22 20 62  instead of "$" b
24c0: 65 66 6f 72 65 20 74 68 65 20 6e 61 6d 65 20 6f  efore the name o
24d0: 66 20 61 20 76 61 72 69 61 62 6c 65 20 63 61 6e  f a variable can
24e0: 20 0a 73 6f 6d 65 74 69 6d 65 73 20 62 65 20 75   .sometimes be u
24f0: 73 65 66 75 6c 20 69 66 20 74 68 65 20 53 51 4c  seful if the SQL
2500: 20 74 65 78 74 20 69 73 20 65 6e 63 6c 6f 73 65   text is enclose
2510: 64 20 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74  d in double-quot
2520: 65 73 20 22 2e 2e 2e 22 0a 69 6e 73 74 65 61 64  es "...".instead
2530: 20 6f 66 20 63 75 72 6c 79 2d 62 72 61 63 65 73   of curly-braces
2540: 20 7b 2e 2e 2e 7d 2e 20 20 0a 57 68 65 6e 20 74   {...}.  .When t
2550: 68 65 20 53 51 4c 20 69 73 20 63 6f 6e 74 61 69  he SQL is contai
2560: 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c  ned within doubl
2570: 65 2d 71 75 6f 74 65 73 20 22 2e 2e 2e 22 20 74  e-quotes "..." t
2580: 68 65 6e 20 54 43 4c 20 77 69 6c 6c 20 64 6f 0a  hen TCL will do.
2590: 74 68 65 20 73 75 62 73 74 69 74 75 74 69 6f 6e  the substitution
25a0: 20 6f 66 20 24 2d 76 61 72 69 61 62 6c 65 73 2c   of $-variables,
25b0: 20 77 68 69 63 68 20 63 61 6e 20 6c 65 61 64 20   which can lead 
25c0: 74 6f 20 53 51 4c 20 69 6e 6a 65 63 74 69 6f 6e  to SQL injection
25d0: 20 69 66 0a 65 78 74 72 65 6d 65 20 63 61 72 65   if.extreme care
25e0: 20 69 73 20 6e 6f 74 20 75 73 65 64 2e 20 20 42   is not used.  B
25f0: 75 74 20 54 43 4c 20 77 69 6c 6c 20 6e 65 76 65  ut TCL will neve
2600: 72 20 73 75 62 73 74 69 74 75 74 65 20 61 20 3a  r substitute a :
2610: 2d 76 61 72 69 61 62 6c 65 0a 72 65 67 61 72 64  -variable.regard
2620: 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
2630: 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 22 2e  double-quotes ".
2640: 2e 2e 22 20 6f 72 20 63 75 72 6c 79 2d 62 72 61  .." or curly-bra
2650: 63 65 73 20 7b 2e 2e 2e 7d 20 61 72 65 20 0a 75  ces {...} are .u
2660: 73 65 64 20 74 6f 20 65 6e 63 6c 6f 73 65 20 74  sed to enclose t
2670: 68 65 20 53 51 4c 2c 20 73 6f 20 74 68 65 20 75  he SQL, so the u
2680: 73 65 20 6f 66 20 3a 2d 76 61 72 69 61 62 6c 65  se of :-variable
2690: 73 20 61 64 64 73 20 61 6e 20 65 78 74 72 61 20  s adds an extra 
26a0: 0a 6d 65 61 73 75 72 65 20 6f 66 20 64 65 66 65  .measure of defe
26b0: 6e 73 65 20 61 67 61 69 6e 73 74 20 53 51 4c 0a  nse against SQL.
26c0: 69 6e 6a 65 63 74 69 6f 6e 2e 0a 3c 2f 70 3e 0a  injection..</p>.
26d0: 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23 23 23 23  .}..############
26e0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
26f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2700: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2710: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2720: 23 23 0a 4d 45 54 48 4f 44 20 63 6c 6f 73 65 20  ##.METHOD close 
2730: 7b 0a 0a 3c 70 3e 0a 41 73 20 69 74 73 20 6e 61  {..<p>.As its na
2740: 6d 65 20 73 75 67 67 65 73 74 73 2c 20 74 68 65  me suggests, the
2750: 20 22 63 6c 6f 73 65 22 20 6d 65 74 68 6f 64 20   "close" method 
2760: 74 6f 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  to an SQLite dat
2770: 61 62 61 73 65 20 6a 75 73 74 0a 63 6c 6f 73 65  abase just.close
2780: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
2790: 20 54 68 69 73 20 68 61 73 20 74 68 65 20 73 69   This has the si
27a0: 64 65 2d 65 66 66 65 63 74 20 6f 66 20 64 65 6c  de-effect of del
27b0: 65 74 69 6e 67 20 74 68 65 0a 3c 69 3e 64 62 63  eting the.<i>dbc
27c0: 6d 64 3c 2f 69 3e 20 54 63 6c 20 63 6f 6d 6d 61  md</i> Tcl comma
27d0: 6e 64 2e 20 20 48 65 72 65 20 69 73 20 61 6e 20  nd.  Here is an 
27e0: 65 78 61 6d 70 6c 65 20 6f 66 20 6f 70 65 6e 69  example of openi
27f0: 6e 67 20 61 6e 64 20 74 68 65 6e 0a 69 6d 6d 65  ng and then.imme
2800: 64 69 61 74 65 6c 79 20 63 6c 6f 73 69 6e 67 20  diately closing 
2810: 61 20 64 61 74 61 62 61 73 65 3a 0a 3c 2f 70 3e  a database:.</p>
2820: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c  ..<blockquote>.<
2830: 62 3e 73 71 6c 69 74 65 33 20 64 62 31 20 2e 2f  b>sqlite3 db1 ./
2840: 74 65 73 74 64 62 3c 62 72 3e 0a 64 62 31 20 63  testdb<br>.db1 c
2850: 6c 6f 73 65 3c 2f 62 3e 0a 3c 2f 62 6c 6f 63 6b  lose</b>.</block
2860: 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 49 66 20 79  quote>..<p>.If y
2870: 6f 75 20 64 65 6c 65 74 65 20 74 68 65 20 3c 69  ou delete the <i
2880: 3e 64 62 63 6d 64 3c 2f 69 3e 20 64 69 72 65 63  >dbcmd</i> direc
2890: 74 6c 79 2c 20 74 68 61 74 20 68 61 73 20 74 68  tly, that has th
28a0: 65 20 73 61 6d 65 20 65 66 66 65 63 74 0a 61 73  e same effect.as
28b0: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 22 63   invoking the "c
28c0: 6c 6f 73 65 22 20 6d 65 74 68 6f 64 2e 20 20 53  lose" method.  S
28d0: 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  o the following 
28e0: 63 6f 64 65 20 69 73 20 65 71 75 69 76 61 6c 65  code is equivale
28f0: 6e 74 0a 74 6f 20 74 68 65 20 70 72 65 76 69 6f  nt.to the previo
2900: 75 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71  us:</p>..<blockq
2910: 75 6f 74 65 3e 0a 3c 62 3e 73 71 6c 69 74 65 33  uote>.<b>sqlite3
2920: 20 64 62 31 20 2e 2f 74 65 73 74 64 62 3c 62 72   db1 ./testdb<br
2930: 3e 0a 72 65 6e 61 6d 65 20 64 62 31 20 7b 7d 3c  >.rename db1 {}<
2940: 2f 62 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  /b>.</blockquote
2950: 3e 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23 23 23  >.}..###########
2960: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2970: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2980: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2990: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
29a0: 23 23 23 0a 4d 45 54 48 4f 44 20 74 72 61 6e 73  ###.METHOD trans
29b0: 61 63 74 69 6f 6e 20 7b 0a 0a 3c 70 3e 0a 54 68  action {..<p>.Th
29c0: 65 20 22 74 72 61 6e 73 61 63 74 69 6f 6e 22 20  e "transaction" 
29d0: 6d 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 74  method is used t
29e0: 6f 20 65 78 65 63 75 74 65 20 61 20 54 43 4c 20  o execute a TCL 
29f0: 73 63 72 69 70 74 20 69 6e 73 69 64 65 20 61 6e  script inside an
2a00: 20 53 51 4c 69 74 65 0a 64 61 74 61 62 61 73 65   SQLite.database
2a10: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
2a20: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
2a30: 73 20 63 6f 6d 6d 69 74 74 65 64 20 77 68 65 6e  s committed when
2a40: 20 74 68 65 20 73 63 72 69 70 74 20 63 6f 6d 70   the script comp
2a50: 6c 65 74 65 73 2c 0a 6f 72 20 69 74 20 72 6f 6c  letes,.or it rol
2a60: 6c 73 20 62 61 63 6b 20 69 66 20 74 68 65 20 73  ls back if the s
2a70: 63 72 69 70 74 20 66 61 69 6c 73 2e 20 20 49 66  cript fails.  If
2a80: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2a90: 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 0a 61   occurs within.a
2aa0: 6e 6f 74 68 65 72 20 74 72 61 6e 73 61 63 74 69  nother transacti
2ab0: 6f 6e 20 28 65 76 65 6e 20 6f 6e 65 20 74 68 61  on (even one tha
2ac0: 74 20 69 73 20 73 74 61 72 74 65 64 20 6d 61 6e  t is started man
2ad0: 75 61 6c 6c 79 20 75 73 69 6e 67 20 42 45 47 49  ually using BEGI
2ae0: 4e 29 20 69 74 0a 69 73 20 61 20 6e 6f 2d 6f 70  N) it.is a no-op
2af0: 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20  ..</p>..<p>.The 
2b00: 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d  transaction comm
2b10: 61 6e 64 20 63 61 6e 20 62 65 20 75 73 65 64 20  and can be used 
2b20: 74 6f 20 67 72 6f 75 70 20 74 6f 67 65 74 68 65  to group togethe
2b30: 72 20 73 65 76 65 72 61 6c 20 53 51 4c 69 74 65  r several SQLite
2b40: 0a 63 6f 6d 6d 61 6e 64 73 20 69 6e 20 61 20 73  .commands in a s
2b50: 61 66 65 20 77 61 79 2e 20 20 59 6f 75 20 63 61  afe way.  You ca
2b60: 6e 20 61 6c 77 61 79 73 20 73 74 61 72 74 20 74  n always start t
2b70: 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 6e 75  ransactions manu
2b80: 61 6c 6c 79 20 75 73 69 6e 67 0a 42 45 47 49 4e  ally using.BEGIN
2b90: 2c 20 6f 66 0a 63 6f 75 72 73 65 2e 20 20 42 75  , of.course.  Bu
2ba0: 74 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  t if an error oc
2bb0: 63 75 72 73 20 73 6f 20 74 68 61 74 20 74 68 65  curs so that the
2bc0: 20 43 4f 4d 4d 49 54 20 6f 72 20 52 4f 4c 4c 42   COMMIT or ROLLB
2bd0: 41 43 4b 20 61 72 65 20 6e 65 76 65 72 0a 72 75  ACK are never.ru
2be0: 6e 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  n, then the data
2bf0: 62 61 73 65 20 77 69 6c 6c 20 72 65 6d 61 69 6e  base will remain
2c00: 20 6c 6f 63 6b 65 64 20 69 6e 64 65 66 69 6e 69   locked indefini
2c10: 74 65 6c 79 2e 20 20 41 6c 73 6f 2c 20 42 45 47  tely.  Also, BEG
2c20: 49 4e 0a 64 6f 65 73 20 6e 6f 74 20 6e 65 73 74  IN.does not nest
2c30: 2c 20 73 6f 20 79 6f 75 20 68 61 76 65 20 74 6f  , so you have to
2c40: 20 6d 61 6b 65 20 73 75 72 65 20 6e 6f 20 6f 74   make sure no ot
2c50: 68 65 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  her transactions
2c60: 20 61 72 65 20 61 63 74 69 76 65 0a 62 65 66 6f   are active.befo
2c70: 72 65 20 73 74 61 72 74 69 6e 67 20 61 20 6e 65  re starting a ne
2c80: 77 20 6f 6e 65 2e 20 20 54 68 65 20 22 74 72 61  w one.  The "tra
2c90: 6e 73 61 63 74 69 6f 6e 22 20 6d 65 74 68 6f 64  nsaction" method
2ca0: 20 74 61 6b 65 73 20 63 61 72 65 20 6f 66 0a 61   takes care of.a
2cb0: 6c 6c 20 6f 66 20 74 68 65 73 65 20 64 65 74 61  ll of these deta
2cc0: 69 6c 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ils automaticall
2cd0: 79 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65  y..</p>..<p>.The
2ce0: 20 73 79 6e 74 61 78 20 6c 6f 6f 6b 73 20 6c 69   syntax looks li
2cf0: 6b 65 20 74 68 69 73 3a 0a 3c 2f 70 3e 0a 0a 3c  ke this:.</p>..<
2d00: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 69 3e 64  blockquote>.<i>d
2d10: 62 63 6d 64 3c 2f 69 3e 26 6e 62 73 70 3b 26 6e  bcmd</i>&nbsp;&n
2d20: 62 73 70 3b 3c 62 3e 74 72 61 6e 73 61 63 74 69  bsp;<b>transacti
2d30: 6f 6e 3c 2f 62 3e 26 6e 62 73 70 3b 26 6e 62 73  on</b>&nbsp;&nbs
2d40: 70 3b 3c 69 3e 3f 74 72 61 6e 73 61 63 74 69 6f  p;<i>?transactio
2d50: 6e 2d 74 79 70 65 3f 3c 2f 69 3e 0a 26 6e 62 73  n-type?</i>.&nbs
2d60: 70 3b 26 6e 62 73 70 3b 3c 69 3e 73 63 72 69 70  p;&nbsp;<i>scrip
2d70: 74 3c 2f 69 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f  t</i>.</blockquo
2d80: 74 65 3e 0a 0a 0a 3c 70 3e 0a 54 68 65 20 3c 69  te>...<p>.The <i
2d90: 3e 74 72 61 6e 73 61 63 74 69 6f 6e 2d 74 79 70  >transaction-typ
2da0: 65 3c 2f 69 3e 20 63 61 6e 20 62 65 20 6f 6e 65  e</i> can be one
2db0: 20 6f 66 20 3c 62 3e 64 65 66 65 72 72 65 64 3c   of <b>deferred<
2dc0: 2f 62 3e 2c 0a 3c 62 3e 65 78 63 6c 75 73 69 76  /b>,.<b>exclusiv
2dd0: 65 3c 2f 62 3e 20 6f 72 20 3c 62 3e 69 6d 6d 65  e</b> or <b>imme
2de0: 64 69 61 74 65 3c 2f 62 3e 2e 20 20 54 68 65 20  diate</b>.  The 
2df0: 64 65 66 61 75 6c 74 20 69 73 20 64 65 66 65 72  default is defer
2e00: 72 65 64 2e 0a 3c 2f 70 3e 0a 7d 0a 0a 23 23 23  red..</p>.}..###
2e10: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2e20: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2e30: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2e40: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2e50: 23 23 23 23 23 23 23 23 23 23 23 0a 4d 45 54 48  ###########.METH
2e60: 4f 44 20 63 61 63 68 65 20 7b 0a 0a 3c 70 3e 0a  OD cache {..<p>.
2e70: 54 68 65 20 22 65 76 61 6c 22 20 6d 65 74 68 6f  The "eval" metho
2e80: 64 20 64 65 73 63 72 69 62 65 64 20 3c 61 20 68  d described <a h
2e90: 72 65 66 3d 22 23 65 76 61 6c 22 3e 61 62 6f 76  ref="#eval">abov
2ea0: 65 3c 2f 61 3e 20 6b 65 65 70 73 20 61 20 63 61  e</a> keeps a ca
2eb0: 63 68 65 20 6f 66 0a 3c 61 20 68 72 65 66 3d 22  che of.<a href="
2ec0: 63 33 72 65 66 2f 70 72 65 70 61 72 65 2e 68 74  c3ref/prepare.ht
2ed0: 6d 6c 22 3e 70 72 65 70 61 72 65 64 20 73 74 61  ml">prepared sta
2ee0: 74 65 6d 65 6e 74 73 3c 2f 61 3e 0a 66 6f 72 20  tements</a>.for 
2ef0: 72 65 63 65 6e 74 6c 79 20 65 76 61 6c 75 61 74  recently evaluat
2f00: 65 64 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 73 2e  ed SQL commands.
2f10: 20 20 0a 54 68 65 20 22 63 61 63 68 65 22 20 6d    .The "cache" m
2f20: 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 6f  ethod is used to
2f30: 20 63 6f 6e 74 72 6f 6c 20 74 68 69 73 20 63 61   control this ca
2f40: 63 68 65 2e 0a 54 68 65 20 66 69 72 73 74 20 66  che..The first f
2f50: 6f 72 6d 20 6f 66 20 74 68 69 73 20 63 6f 6d 6d  orm of this comm
2f60: 61 6e 64 20 69 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c  and is:</p>..<bl
2f70: 6f 63 6b 71 75 6f 74 65 3e 0a 3c 69 3e 64 62 63  ockquote>.<i>dbc
2f80: 6d 64 3c 2f 69 3e 26 6e 62 73 70 3b 26 6e 62 73  md</i>&nbsp;&nbs
2f90: 70 3b 3c 62 3e 63 61 63 68 65 20 73 69 7a 65 3c  p;<b>cache size<
2fa0: 2f 62 3e 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c  /b>&nbsp;&nbsp;<
2fb0: 69 3e 4e 3c 2f 69 3e 0a 3c 2f 62 6c 6f 63 6b 71  i>N</i>.</blockq
2fc0: 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 69 73 20 73  uote>..<p>This s
2fd0: 65 74 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  ets the maximum 
2fe0: 6e 75 6d 62 65 72 20 6f 66 20 73 74 61 74 65 6d  number of statem
2ff0: 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62 65  ents that can be
3000: 20 63 61 63 68 65 64 2e 0a 54 68 65 20 75 70 70   cached..The upp
3010: 65 72 20 6c 69 6d 69 74 20 69 73 20 31 30 30 2e  er limit is 100.
3020: 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 73    The default is
3030: 20 31 30 2e 20 20 49 66 20 79 6f 75 20 73 65 74   10.  If you set
3040: 20 74 68 65 20 63 61 63 68 65 20 73 69 7a 65 0a   the cache size.
3050: 74 6f 20 30 2c 20 6e 6f 20 63 61 63 68 69 6e 67  to 0, no caching
3060: 20 69 73 20 64 6f 6e 65 2e 3c 2f 70 3e 0a 0a 3c   is done.</p>..<
3070: 70 3e 54 68 65 20 73 65 63 6f 6e 64 20 66 6f 72  p>The second for
3080: 6d 20 6f 66 20 74 68 65 20 63 6f 6d 6d 61 6e 64  m of the command
3090: 20 69 73 20 74 68 69 73 3a 3c 2f 70 3e 0a 0a 0a   is this:</p>...
30a0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 69 3e  <blockquote>.<i>
30b0: 64 62 63 6d 64 3c 2f 69 3e 26 6e 62 73 70 3b 26  dbcmd</i>&nbsp;&
30c0: 6e 62 73 70 3b 3c 62 3e 63 61 63 68 65 20 66 6c  nbsp;<b>cache fl
30d0: 75 73 68 3c 2f 62 3e 0a 3c 2f 62 6c 6f 63 6b 71  ush</b>.</blockq
30e0: 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 20 63 61  uote>..<p>The ca
30f0: 63 68 65 2d 66 6c 75 73 68 20 6d 65 74 68 6f 64  che-flush method
3100: 20 0a 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66   .<a href="c3ref
3110: 2f 66 69 6e 61 6c 69 7a 65 2e 68 74 6d 6c 22 3e  /finalize.html">
3120: 66 69 6e 61 6c 69 7a 65 73 3c 2f 61 3e 0a 61 6c  finalizes</a>.al
3130: 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  l prepared state
3140: 6d 65 6e 74 73 20 63 75 72 72 65 6e 74 6c 79 0a  ments currently.
3150: 69 6e 20 74 68 65 20 63 61 63 68 65 2e 3c 2f 70  in the cache.</p
3160: 3e 0a 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23 23  >..}..##########
3170: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3180: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
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 0a 4d 45 54 48 4f 44 20 63 6f 6d 70  ####.METHOD comp
31c0: 6c 65 74 65 20 7b 0a 0a 3c 70 3e 0a 54 68 65 20  lete {..<p>.The 
31d0: 22 63 6f 6d 70 6c 65 74 65 22 20 6d 65 74 68 6f  "complete" metho
31e0: 64 20 74 61 6b 65 73 20 61 20 73 74 72 69 6e 67  d takes a string
31f0: 20 6f 66 20 73 75 70 70 6f 73 65 64 20 53 51 4c   of supposed SQL
3200: 20 61 73 20 69 74 73 20 6f 6e 6c 79 20 61 72 67   as its only arg
3210: 75 6d 65 6e 74 2e 0a 49 74 20 72 65 74 75 72 6e  ument..It return
3220: 73 20 54 52 55 45 20 69 66 20 74 68 65 20 73 74  s TRUE if the st
3230: 72 69 6e 67 20 69 73 20 61 20 63 6f 6d 70 6c 65  ring is a comple
3240: 74 65 20 73 74 61 74 65 6d 65 6e 74 20 6f 66 20  te statement of 
3250: 53 51 4c 20 61 6e 64 20 46 41 4c 53 45 20 69 66  SQL and FALSE if
3260: 0a 74 68 65 72 65 20 69 73 20 6d 6f 72 65 20 74  .there is more t
3270: 6f 20 62 65 20 65 6e 74 65 72 65 64 2e 3c 2f 70  o be entered.</p
3280: 3e 0a 0a 3c 70 3e 54 68 65 20 22 63 6f 6d 70 6c  >..<p>The "compl
3290: 65 74 65 22 20 6d 65 74 68 6f 64 20 69 73 20 75  ete" method is u
32a0: 73 65 66 75 6c 20 77 68 65 6e 20 62 75 69 6c 64  seful when build
32b0: 69 6e 67 20 69 6e 74 65 72 61 63 74 69 76 65 20  ing interactive 
32c0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 69 6e 20  applications.in 
32d0: 6f 72 64 65 72 20 74 6f 20 6b 6e 6f 77 20 77 68  order to know wh
32e0: 65 6e 20 74 68 65 20 75 73 65 72 20 68 61 73 20  en the user has 
32f0: 66 69 6e 69 73 68 65 64 20 65 6e 74 65 72 69 6e  finished enterin
3300: 67 20 61 20 6c 69 6e 65 20 6f 66 20 53 51 4c 20  g a line of SQL 
3310: 63 6f 64 65 2e 0a 54 68 69 73 20 69 73 20 72 65  code..This is re
3320: 61 6c 6c 79 20 6a 75 73 74 20 61 6e 20 69 6e 74  ally just an int
3330: 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 0a 3c  erface to the .<
3340: 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 63 6f  a href="c3ref/co
3350: 6d 70 6c 65 74 65 2e 68 74 6d 6c 22 3e 3c 62 3e  mplete.html"><b>
3360: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
3370: 28 29 3c 2f 62 3e 3c 2f 61 3e 20 43 0a 66 75 6e  ()</b></a> C.fun
3380: 63 74 69 6f 6e 2e 0a 7d 0a 0a 23 23 23 23 23 23  ction..}..######
3390: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
33a0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
33b0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
33c0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
33d0: 23 23 23 23 23 23 23 23 0a 4d 45 54 48 4f 44 20  ########.METHOD 
33e0: 63 6f 70 79 20 7b 0a 0a 3c 70 3e 0a 54 68 65 20  copy {..<p>.The 
33f0: 22 63 6f 70 79 22 20 6d 65 74 68 6f 64 20 63 6f  "copy" method co
3400: 70 69 65 73 20 64 61 74 61 20 66 72 6f 6d 20 61  pies data from a
3410: 20 66 69 6c 65 20 69 6e 74 6f 20 61 20 74 61 62   file into a tab
3420: 6c 65 2e 0a 49 74 20 72 65 74 75 72 6e 73 20 74  le..It returns t
3430: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
3440: 73 20 70 72 6f 63 65 73 73 65 64 20 73 75 63 63  s processed succ
3450: 65 73 73 66 75 6c 6c 79 20 66 72 6f 6d 20 74 68  essfully from th
3460: 65 20 66 69 6c 65 2e 0a 54 68 65 20 73 79 6e 74  e file..The synt
3470: 61 78 20 6f 66 20 74 68 65 20 63 6f 70 79 20 6d  ax of the copy m
3480: 65 74 68 6f 64 20 6c 6f 6f 6b 73 20 6c 69 6b 65  ethod looks like
3490: 20 74 68 69 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f   this:</p>..<blo
34a0: 63 6b 71 75 6f 74 65 3e 0a 3c 69 3e 64 62 63 6d  ckquote>.<i>dbcm
34b0: 64 3c 2f 69 3e 26 6e 62 73 70 3b 26 6e 62 73 70  d</i>&nbsp;&nbsp
34c0: 3b 3c 62 3e 63 6f 70 79 3c 2f 62 3e 26 6e 62 73  ;<b>copy</b>&nbs
34d0: 70 3b 26 6e 62 73 70 3b 3c 69 3e 63 6f 6e 66 6c  p;&nbsp;<i>confl
34e0: 69 63 74 2d 61 6c 67 6f 72 69 74 68 6d 3c 2f 69  ict-algorithm</i
34f0: 3e 0a 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 69  >.&nbsp;&nbsp;<i
3500: 3e 74 61 62 6c 65 2d 6e 61 6d 65 26 6e 62 73 70  >table-name&nbsp
3510: 3b 3c 2f 69 3e 26 6e 62 73 70 3b 26 6e 62 73 70  ;</i>&nbsp;&nbsp
3520: 3b 3c 69 3e 66 69 6c 65 2d 6e 61 6d 65 26 6e 62  ;<i>file-name&nb
3530: 73 70 3b 3c 2f 69 3e 0a 26 6e 62 73 70 3b 26 6e  sp;</i>.&nbsp;&n
3540: 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b  bsp;&nbsp;&nbsp;
3550: 3f 3c 69 3e 63 6f 6c 75 6d 6e 2d 73 65 70 61 72  ?<i>column-separ
3560: 61 74 6f 72 3c 2f 69 3e 3f 0a 26 6e 62 73 70 3b  ator</i>?.&nbsp;
3570: 26 6e 62 73 70 3b 3f 3c 69 3e 6e 75 6c 6c 2d 69  &nbsp;?<i>null-i
3580: 6e 64 69 63 61 74 6f 72 3c 2f 69 3e 3f 0a 3c 2f  ndicator</i>?.</
3590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e  blockquote>..<p>
35a0: 43 6f 6e 66 6c 69 63 74 2d 61 6c 67 6f 72 69 74  Conflict-algorit
35b0: 68 6d 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f  hm must be one o
35c0: 66 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 6e  f the SQLite con
35d0: 66 6c 69 63 74 20 61 6c 67 6f 72 69 74 68 6d 73  flict algorithms
35e0: 20 66 6f 72 0a 74 68 65 20 49 4e 53 45 52 54 20   for.the INSERT 
35f0: 73 74 61 74 65 6d 65 6e 74 3a 20 3c 69 3e 72 6f  statement: <i>ro
3600: 6c 6c 62 61 63 6b 3c 2f 69 3e 2c 20 3c 69 3e 61  llback</i>, <i>a
3610: 62 6f 72 74 3c 2f 69 3e 2c 0a 3c 69 3e 66 61 69  bort</i>,.<i>fai
3620: 6c 3c 2f 69 3e 2c 3c 69 3e 69 67 6e 6f 72 65 3c  l</i>,<i>ignore<
3630: 2f 69 3e 2c 20 6f 72 20 3c 69 3e 72 65 70 6c 61  /i>, or <i>repla
3640: 63 65 3c 2f 69 3e 2e 20 53 65 65 20 74 68 65 20  ce</i>. See the 
3650: 53 51 4c 69 74 65 20 4c 61 6e 67 75 61 67 65 0a  SQLite Language.
3660: 73 65 63 74 69 6f 6e 20 66 6f 72 20 3c 61 20 68  section for <a h
3670: 72 65 66 3d 22 6c 61 6e 67 2e 68 74 6d 6c 23 63  ref="lang.html#c
3680: 6f 6e 66 6c 69 63 74 22 3e 4f 4e 20 43 4f 4e 46  onflict">ON CONF
3690: 4c 49 43 54 3c 2f 61 3e 20 66 6f 72 20 6d 6f 72  LICT</a> for mor
36a0: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 54  e information..T
36b0: 68 65 20 63 6f 6e 66 6c 69 63 74 2d 61 6c 67 6f  he conflict-algo
36c0: 72 69 74 68 6d 20 6d 75 73 74 20 62 65 20 73 70  rithm must be sp
36d0: 65 63 69 66 69 65 64 20 69 6e 20 6c 6f 77 65 72  ecified in lower
36e0: 20 63 61 73 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e   case..</p>..<p>
36f0: 54 61 62 6c 65 2d 6e 61 6d 65 20 6d 75 73 74 20  Table-name must 
3700: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 20 61  already exists a
3710: 73 20 61 20 74 61 62 6c 65 2e 20 20 46 69 6c 65  s a table.  File
3720: 2d 6e 61 6d 65 20 6d 75 73 74 20 65 78 69 73 74  -name must exist
3730: 2c 20 61 6e 64 0a 65 61 63 68 20 72 6f 77 20 6d  , and.each row m
3740: 75 73 74 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  ust contain the 
3750: 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  same number of c
3760: 6f 6c 75 6d 6e 73 20 61 73 20 64 65 66 69 6e 65  olumns as define
3770: 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 0a  d in the table..
3780: 49 66 20 61 20 6c 69 6e 65 20 69 6e 20 74 68 65  If a line in the
3790: 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 6d   file contains m
37a0: 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e  ore or less than
37b0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
37c0: 6f 6c 75 6d 6e 73 20 64 65 66 69 6e 65 64 2c 0a  olumns defined,.
37d0: 74 68 65 20 63 6f 70 79 20 6d 65 74 68 6f 64 20  the copy method 
37e0: 72 6f 6c 6c 62 61 63 6b 73 20 61 6e 79 20 69 6e  rollbacks any in
37f0: 73 65 72 74 73 2c 20 61 6e 64 20 72 65 74 75 72  serts, and retur
3800: 6e 73 20 61 6e 20 65 72 72 6f 72 2e 3c 2f 70 3e  ns an error.</p>
3810: 0a 0a 3c 70 3e 43 6f 6c 75 6d 6e 2d 73 65 70 61  ..<p>Column-sepa
3820: 72 61 74 6f 72 20 69 73 20 61 6e 20 6f 70 74 69  rator is an opti
3830: 6f 6e 61 6c 20 63 6f 6c 75 6d 6e 20 73 65 70 61  onal column sepa
3840: 72 61 74 6f 72 20 73 74 72 69 6e 67 2e 20 20 54  rator string.  T
3850: 68 65 20 64 65 66 61 75 6c 74 20 69 73 0a 74 68  he default is.th
3860: 65 20 41 53 43 49 49 20 74 61 62 20 63 68 61 72  e ASCII tab char
3870: 61 63 74 65 72 20 5c 74 2e 20 3c 2f 70 3e 0a 0a  acter \t. </p>..
3880: 3c 70 3e 4e 75 6c 6c 2d 69 6e 64 69 63 61 74 6f  <p>Null-indicato
3890: 72 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  r is an optional
38a0: 20 73 74 72 69 6e 67 20 74 68 61 74 20 69 6e 64   string that ind
38b0: 69 63 61 74 65 73 20 61 20 63 6f 6c 75 6d 6e 20  icates a column 
38c0: 76 61 6c 75 65 20 69 73 20 6e 75 6c 6c 2e 0a 54  value is null..T
38d0: 68 65 20 64 65 66 61 75 6c 74 20 69 73 20 61 6e  he default is an
38e0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 20 20   empty string.  
38f0: 4e 6f 74 65 20 74 68 61 74 20 63 6f 6c 75 6d 6e  Note that column
3900: 2d 73 65 70 61 72 61 74 6f 72 20 61 6e 64 0a 6e  -separator and.n
3910: 75 6c 6c 2d 69 6e 64 69 63 61 74 6f 72 20 61 72  ull-indicator ar
3920: 65 20 6f 70 74 69 6f 6e 61 6c 20 70 6f 73 69 74  e optional posit
3930: 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 3b  ional arguments;
3940: 20 69 66 20 6e 75 6c 6c 2d 69 6e 64 69 63 61 74   if null-indicat
3950: 6f 72 0a 69 73 20 73 70 65 63 69 66 69 65 64 2c  or.is specified,
3960: 20 61 20 63 6f 6c 75 6d 6e 2d 73 65 70 61 72 61   a column-separa
3970: 74 6f 72 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  tor argument mus
3980: 74 20 62 65 20 73 70 65 63 69 66 69 65 64 20 61  t be specified a
3990: 6e 64 0a 70 72 65 63 65 64 65 20 74 68 65 20 6e  nd.precede the n
39a0: 75 6c 6c 2d 69 6e 64 69 63 61 74 6f 72 20 61 72  ull-indicator ar
39b0: 67 75 6d 65 6e 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e  gument.</p>..<p>
39c0: 54 68 65 20 63 6f 70 79 20 6d 65 74 68 6f 64 20  The copy method 
39d0: 69 6d 70 6c 65 6d 65 6e 74 73 20 73 69 6d 69 6c  implements simil
39e0: 61 72 20 66 75 6e 63 74 69 6f 6e 61 6c 69 74 79  ar functionality
39f0: 20 74 6f 20 74 68 65 20 3c 62 3e 2e 69 6d 70 6f   to the <b>.impo
3a00: 72 74 3c 2f 62 3e 0a 53 51 4c 69 74 65 20 73 68  rt</b>.SQLite sh
3a10: 65 6c 6c 20 63 6f 6d 6d 61 6e 64 2e 20 0a 7d 0a  ell command. .}.
3a20: 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  .###############
3a30: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3a40: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3a50: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3a60: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a  ###############.
3a70: 4d 45 54 48 4f 44 20 74 69 6d 65 6f 75 74 20 7b  METHOD timeout {
3a80: 0a 0a 3c 70 3e 54 68 65 20 22 74 69 6d 65 6f 75  ..<p>The "timeou
3a90: 74 22 20 6d 65 74 68 6f 64 20 69 73 20 75 73 65  t" method is use
3aa0: 64 20 74 6f 20 63 6f 6e 74 72 6f 6c 20 68 6f 77  d to control how
3ab0: 20 6c 6f 6e 67 20 74 68 65 20 53 51 4c 69 74 65   long the SQLite
3ac0: 20 6c 69 62 72 61 72 79 0a 77 69 6c 6c 20 77 61   library.will wa
3ad0: 69 74 20 66 6f 72 20 6c 6f 63 6b 73 20 74 6f 20  it for locks to 
3ae0: 63 6c 65 61 72 20 62 65 66 6f 72 65 20 67 69 76  clear before giv
3af0: 69 6e 67 20 75 70 20 6f 6e 20 61 20 64 61 74 61  ing up on a data
3b00: 62 61 73 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  base transaction
3b10: 2e 0a 54 68 65 20 64 65 66 61 75 6c 74 20 74 69  ..The default ti
3b20: 6d 65 6f 75 74 20 69 73 20 30 20 6d 69 6c 6c 69  meout is 0 milli
3b30: 73 65 63 6f 6e 64 2e 20 20 28 49 6e 20 6f 74 68  second.  (In oth
3b40: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 64 65  er words, the de
3b50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 0a 69  fault behavior.i
3b60: 73 20 6e 6f 74 20 74 6f 20 77 61 69 74 20 61 74  s not to wait at
3b70: 20 61 6c 6c 2e 29 3c 2f 70 3e 0a 0a 3c 70 3e 54   all.)</p>..<p>T
3b80: 68 65 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  he SQLite databa
3b90: 73 65 20 61 6c 6c 6f 77 73 20 6d 75 6c 74 69 70  se allows multip
3ba0: 6c 65 20 73 69 6d 75 6c 74 61 6e 65 6f 75 73 0a  le simultaneous.
3bb0: 72 65 61 64 65 72 73 20 6f 72 20 61 20 73 69 6e  readers or a sin
3bc0: 67 6c 65 20 77 72 69 74 65 72 20 62 75 74 20 6e  gle writer but n
3bd0: 6f 74 20 62 6f 74 68 2e 20 20 49 66 20 61 6e 79  ot both.  If any
3be0: 20 70 72 6f 63 65 73 73 20 69 73 20 77 72 69 74   process is writ
3bf0: 69 6e 67 20 74 6f 0a 74 68 65 20 64 61 74 61 62  ing to.the datab
3c00: 61 73 65 20 6e 6f 20 6f 74 68 65 72 20 70 72 6f  ase no other pro
3c10: 63 65 73 73 20 69 73 20 61 6c 6c 6f 77 73 20 74  cess is allows t
3c20: 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 2e  o read or write.
3c30: 20 20 49 66 20 61 6e 79 20 70 72 6f 63 65 73 73    If any process
3c40: 0a 69 73 20 72 65 61 64 69 6e 67 20 74 68 65 20  .is reading the 
3c50: 64 61 74 61 62 61 73 65 20 6f 74 68 65 72 20 70  database other p
3c60: 72 6f 63 65 73 73 65 73 20 61 72 65 20 61 6c 6c  rocesses are all
3c70: 6f 77 65 64 20 74 6f 20 72 65 61 64 20 62 75 74  owed to read but
3c80: 20 6e 6f 74 20 77 72 69 74 65 2e 0a 54 68 65 20   not write..The 
3c90: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20  entire database 
3ca0: 73 68 61 72 65 64 20 61 20 73 69 6e 67 6c 65 20  shared a single 
3cb0: 6c 6f 63 6b 2e 3c 2f 70 3e 0a 0a 3c 70 3e 57 68  lock.</p>..<p>Wh
3cc0: 65 6e 20 53 51 4c 69 74 65 20 74 72 69 65 73 20  en SQLite tries 
3cd0: 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
3ce0: 73 65 20 61 6e 64 20 66 69 6e 64 73 20 74 68 61  se and finds tha
3cf0: 74 20 69 74 20 69 73 20 6c 6f 63 6b 65 64 2c 20  t it is locked, 
3d00: 69 74 0a 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c  it.can optionall
3d10: 79 20 64 65 6c 61 79 20 66 6f 72 20 61 20 73 68  y delay for a sh
3d20: 6f 72 74 20 77 68 69 6c 65 20 61 6e 64 20 74 72  ort while and tr
3d30: 79 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 66 69  y to open the fi
3d40: 6c 65 20 61 67 61 69 6e 2e 0a 54 68 69 73 20 70  le again..This p
3d50: 72 6f 63 65 73 73 20 72 65 70 65 61 74 73 20 75  rocess repeats u
3d60: 6e 74 69 6c 20 74 68 65 20 71 75 65 72 79 20 74  ntil the query t
3d70: 69 6d 65 73 20 6f 75 74 20 61 6e 64 20 53 51 4c  imes out and SQL
3d80: 69 74 65 20 72 65 74 75 72 6e 73 20 61 0a 66 61  ite returns a.fa
3d90: 69 6c 75 72 65 2e 20 20 54 68 65 20 74 69 6d 65  ilure.  The time
3da0: 6f 75 74 20 69 73 20 61 64 6a 75 73 74 61 62 6c  out is adjustabl
3db0: 65 2e 20 20 49 74 20 69 73 20 73 65 74 20 74 6f  e.  It is set to
3dc0: 20 30 20 62 79 20 64 65 66 61 75 6c 74 20 73 6f   0 by default so
3dd0: 20 74 68 61 74 0a 69 66 20 74 68 65 20 64 61 74   that.if the dat
3de0: 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 2c  abase is locked,
3df0: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3e00: 6e 74 20 66 61 69 6c 73 20 69 6d 6d 65 64 69 61  nt fails immedia
3e10: 74 65 6c 79 2e 20 20 42 75 74 20 79 6f 75 0a 63  tely.  But you.c
3e20: 61 6e 20 75 73 65 20 74 68 65 20 22 74 69 6d 65  an use the "time
3e30: 6f 75 74 22 20 6d 65 74 68 6f 64 20 74 6f 20 63  out" method to c
3e40: 68 61 6e 67 65 20 74 68 65 20 74 69 6d 65 6f 75  hange the timeou
3e50: 74 20 76 61 6c 75 65 20 74 6f 20 61 20 70 6f 73  t value to a pos
3e60: 69 74 69 76 65 0a 6e 75 6d 62 65 72 2e 20 20 46  itive.number.  F
3e70: 6f 72 20 65 78 61 6d 70 6c 65 3a 3c 2f 70 3e 0a  or example:</p>.
3e80: 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 62 3e  .<blockquote><b>
3e90: 64 62 31 20 74 69 6d 65 6f 75 74 20 32 30 30 30  db1 timeout 2000
3ea0: 3c 2f 62 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  </b></blockquote
3eb0: 3e 0a 0a 3c 70 3e 54 68 65 20 61 72 67 75 6d 65  >..<p>The argume
3ec0: 6e 74 20 74 6f 20 74 68 65 20 74 69 6d 65 6f 75  nt to the timeou
3ed0: 74 20 6d 65 74 68 6f 64 20 69 73 20 74 68 65 20  t method is the 
3ee0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
3ef0: 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 0a 74  f milliseconds.t
3f00: 6f 20 77 61 69 74 20 66 6f 72 20 74 68 65 20 6c  o wait for the l
3f10: 6f 63 6b 20 74 6f 20 63 6c 65 61 72 2e 20 20 53  ock to clear.  S
3f20: 6f 20 69 6e 20 74 68 65 20 65 78 61 6d 70 6c 65  o in the example
3f30: 20 61 62 6f 76 65 2c 20 74 68 65 20 6d 61 78 69   above, the maxi
3f40: 6d 75 6d 20 64 65 6c 61 79 0a 77 6f 75 6c 64 20  mum delay.would 
3f50: 62 65 20 32 20 73 65 63 6f 6e 64 73 2e 3c 2f 70  be 2 seconds.</p
3f60: 3e 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23 23 23  >.}..###########
3f70: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3f80: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3f90: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3fa0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3fb0: 23 23 23 0a 4d 45 54 48 4f 44 20 62 75 73 79 20  ###.METHOD busy 
3fc0: 7b 0a 0a 3c 70 3e 54 68 65 20 22 62 75 73 79 22  {..<p>The "busy"
3fd0: 20 6d 65 74 68 6f 64 2c 20 6c 69 6b 65 20 22 74   method, like "t
3fe0: 69 6d 65 6f 75 74 22 2c 20 6f 6e 6c 79 20 63 6f  imeout", only co
3ff0: 6d 65 73 20 69 6e 74 6f 20 70 6c 61 79 20 77 68  mes into play wh
4000: 65 6e 20 74 68 65 0a 64 61 74 61 62 61 73 65 20  en the.database 
4010: 69 73 20 6c 6f 63 6b 65 64 2e 20 20 42 75 74 20  is locked.  But 
4020: 74 68 65 20 22 62 75 73 79 22 20 6d 65 74 68 6f  the "busy" metho
4030: 64 20 67 69 76 65 73 20 74 68 65 20 70 72 6f 67  d gives the prog
4040: 72 61 6d 6d 65 72 20 6d 75 63 68 20 6d 6f 72 65  rammer much more
4050: 0a 63 6f 6e 74 72 6f 6c 20 6f 76 65 72 20 77 68  .control over wh
4060: 61 74 20 61 63 74 69 6f 6e 20 74 6f 20 74 61 6b  at action to tak
4070: 65 2e 20 20 54 68 65 20 22 62 75 73 79 22 20 6d  e.  The "busy" m
4080: 65 74 68 6f 64 20 73 70 65 63 69 66 69 65 73 20  ethod specifies 
4090: 61 20 63 61 6c 6c 62 61 63 6b 0a 54 63 6c 20 70  a callback.Tcl p
40a0: 72 6f 63 65 64 75 72 65 20 74 68 61 74 20 69 73  rocedure that is
40b0: 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
40c0: 72 20 53 51 4c 69 74 65 20 74 72 69 65 73 20 74  r SQLite tries t
40d0: 6f 20 6f 70 65 6e 20 61 20 6c 6f 63 6b 65 64 0a  o open a locked.
40e0: 64 61 74 61 62 61 73 65 2e 20 20 41 20 73 69 6e  database.  A sin
40f0: 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75  gle integer argu
4100: 6d 65 6e 74 20 69 73 20 61 70 70 65 6e 64 65 64  ment is appended
4110: 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
4120: 20 62 65 66 6f 72 65 0a 69 74 20 69 73 20 69 6e   before.it is in
4130: 76 6f 6b 65 2e 20 20 54 68 65 20 61 72 67 75 6d  voke.  The argum
4140: 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
4150: 72 20 6f 66 20 70 72 69 6f 72 20 63 61 6c 6c 73  r of prior calls
4160: 20 74 6f 20 74 68 65 20 62 75 73 79 0a 63 61 6c   to the busy.cal
4170: 6c 62 61 63 6b 20 66 6f 72 20 74 68 65 20 63 75  lback for the cu
4180: 72 72 65 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76  rrent locking ev
4190: 65 6e 74 2e 20 20 49 74 20 69 73 20 69 6e 74 65  ent.  It is inte
41a0: 6e 64 65 64 20 74 68 61 74 0a 74 68 65 20 63 61  nded that.the ca
41b0: 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 64 6f 20 73  llback will do s
41c0: 6f 6d 65 20 6f 74 68 65 72 20 75 73 65 66 75 6c  ome other useful
41d0: 20 77 6f 72 6b 20 66 6f 72 20 61 20 73 68 6f 72   work for a shor
41e0: 74 20 77 68 69 6c 65 20 0a 28 73 75 63 68 20 61  t while .(such a
41f0: 73 20 73 65 72 76 69 63 65 20 47 55 49 20 65 76  s service GUI ev
4200: 65 6e 74 73 29 20 74 68 65 6e 20 72 65 74 75 72  ents) then retur
4210: 6e 0a 73 6f 20 74 68 61 74 20 74 68 65 20 6c 6f  n.so that the lo
4220: 63 6b 20 63 61 6e 20 62 65 20 74 72 69 65 64 20  ck can be tried 
4230: 61 67 61 69 6e 2e 20 20 54 68 65 20 63 61 6c 6c  again.  The call
4240: 62 61 63 6b 20 70 72 6f 63 65 64 75 72 65 20 73  back procedure s
4250: 68 6f 75 6c 64 0a 72 65 74 75 72 6e 20 22 30 22  hould.return "0"
4260: 20 69 66 20 69 74 20 77 61 6e 74 73 20 53 51 4c   if it wants SQL
4270: 69 74 65 20 74 6f 20 74 72 79 20 61 67 61 69 6e  ite to try again
4280: 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
4290: 61 62 61 73 65 20 61 6e 64 0a 73 68 6f 75 6c 64  abase and.should
42a0: 20 72 65 74 75 72 6e 20 22 31 22 20 69 66 20 69   return "1" if i
42b0: 74 20 77 61 6e 74 73 20 53 51 4c 69 74 65 20 74  t wants SQLite t
42c0: 6f 20 61 62 61 6e 64 6f 6e 20 74 68 65 20 63 75  o abandon the cu
42d0: 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e  rrent operation.
42e0: 0a 3c 70 3e 0a 49 66 20 74 68 65 20 62 75 73 79  .<p>.If the busy
42f0: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
4300: 65 64 20 77 69 74 68 6f 75 74 20 61 6e 20 61 72  ed without an ar
4310: 67 75 6d 65 6e 74 2c 20 74 68 65 20 6e 61 6d 65  gument, the name
4320: 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
4330: 0a 70 72 6f 63 65 64 75 72 65 20 6c 61 73 74 20  .procedure last 
4340: 73 65 74 20 62 79 20 74 68 65 20 62 75 73 79 20  set by the busy 
4350: 6d 65 74 68 6f 64 20 69 73 20 72 65 74 75 72 6e  method is return
4360: 65 64 2e 20 20 49 66 20 6e 6f 20 63 61 6c 6c 62  ed.  If no callb
4370: 61 63 6b 20 70 72 6f 63 65 64 75 72 65 0a 68 61  ack procedure.ha
4380: 73 20 62 65 65 6e 20 73 65 74 2c 20 61 6e 20 65  s been set, an e
4390: 6d 70 74 79 20 73 74 72 69 6e 67 20 69 73 20 72  mpty string is r
43a0: 65 74 75 72 6e 65 64 2e 0a 7d 0a 0a 23 23 23 23  eturned..}..####
43b0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
43c0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
43d0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
43e0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
43f0: 23 23 23 23 23 23 23 23 23 23 0a 4d 45 54 48 4f  ##########.METHO
4400: 44 20 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  D enable_load_ex
4410: 74 65 6e 73 69 6f 6e 20 7b 0a 0a 3c 70 3e 54 68  tension {..<p>Th
4420: 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  e extension load
4430: 69 6e 67 20 6d 65 63 68 61 6e 69 73 6d 20 6f 66  ing mechanism of
4440: 20 53 51 4c 69 74 65 20 28 61 63 63 65 73 73 65   SQLite (accesse
4450: 64 20 75 73 69 6e 67 20 74 68 65 0a 5b 6c 6f 61  d using the.[loa
4460: 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53  d_extension()] S
4470: 51 4c 20 66 75 6e 63 74 69 6f 6e 29 20 69 73 20  QL function) is 
4480: 74 75 72 6e 65 64 20 6f 66 66 20 62 79 20 64 65  turned off by de
4490: 66 61 75 6c 74 2e 20 20 54 68 69 73 20 69 73 0a  fault.  This is.
44a0: 61 20 73 65 63 75 72 69 74 79 20 70 72 65 63 61  a security preca
44b0: 75 74 69 6f 6e 2e 20 20 49 66 20 61 6e 20 61 70  ution.  If an ap
44c0: 70 6c 69 63 61 74 69 6f 6e 20 77 61 6e 74 73 20  plication wants 
44d0: 74 6f 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 74  to make use of t
44e0: 68 65 0a 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69  he.[load_extensi
44f0: 6f 6e 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 69  on()] function i
4500: 74 20 6d 75 73 74 20 66 69 72 73 74 20 74 75 72  t must first tur
4510: 6e 20 74 68 65 20 63 61 70 61 62 69 6c 69 74 79  n the capability
4520: 20 6f 6e 20 75 73 69 6e 67 0a 74 68 69 73 20 6d   on using.this m
4530: 65 74 68 6f 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54  ethod.</p>..<p>T
4540: 68 69 73 20 6d 65 74 68 6f 64 20 74 61 6b 65 73  his method takes
4550: 20 61 20 73 69 6e 67 6c 65 20 62 6f 6f 6c 65 61   a single boolea
4560: 6e 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  n argument which
4570: 20 77 69 6c 6c 20 74 75 72 6e 20 74 68 65 0a 65   will turn the.e
4580: 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
4590: 20 66 75 6e 63 74 69 6f 6e 61 6c 69 74 79 20 6f   functionality o
45a0: 6e 20 6f 72 20 6f 66 66 2e 3c 2f 70 3e 0a 0a 3c  n or off.</p>..<
45b0: 70 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 6d 61  p>This method ma
45c0: 70 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ps to the [sqlit
45d0: 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
45e0: 78 74 65 6e 73 69 6f 6e 28 29 5d 20 43 2f 43 2b  xtension()] C/C+
45f0: 2b 0a 69 6e 74 65 72 66 61 63 65 2e 3c 2f 70 3e  +.interface.</p>
4600: 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23 23 23 23  .}..############
4610: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4620: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4630: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4640: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4650: 23 23 0a 4d 45 54 48 4f 44 20 65 78 69 73 74 73  ##.METHOD exists
4660: 20 7b 0a 0a 3c 70 3e 54 68 65 20 22 65 78 69 73   {..<p>The "exis
4670: 74 73 22 20 6d 65 74 68 6f 64 20 69 73 20 73 69  ts" method is si
4680: 6d 69 6c 61 72 20 74 6f 20 22 6f 6e 65 63 6f 6c  milar to "onecol
4690: 75 6d 6e 22 20 61 6e 64 20 22 65 76 61 6c 22 20  umn" and "eval" 
46a0: 69 6e 20 74 68 61 74 0a 69 74 20 65 78 65 63 75  in that.it execu
46b0: 74 65 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  tes SQL statemen
46c0: 74 73 2e 20 20 54 68 65 20 64 69 66 66 65 72 65  ts.  The differe
46d0: 6e 63 65 20 69 73 20 74 68 61 74 20 74 68 65 20  nce is that the 
46e0: 22 65 78 69 73 74 73 22 20 6d 65 74 68 6f 64 0a  "exists" method.
46f0: 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
4700: 20 62 6f 6f 6c 65 61 6e 20 76 61 6c 75 65 20 77   boolean value w
4710: 68 69 63 68 20 69 73 20 54 52 55 45 20 69 66 20  hich is TRUE if 
4720: 61 20 71 75 65 72 79 20 69 6e 20 74 68 65 20 53  a query in the S
4730: 51 4c 0a 73 74 61 74 65 6d 65 6e 74 20 69 74 20  QL.statement it 
4740: 65 78 65 63 75 74 65 73 20 72 65 74 75 72 6e 73  executes returns
4750: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77   one or more row
4760: 73 20 61 6e 64 20 46 41 4c 53 45 20 69 66 20 74  s and FALSE if t
4770: 68 65 20 53 51 4c 0a 72 65 74 75 72 6e 73 20 61  he SQL.returns a
4780: 6e 20 65 6d 70 74 79 20 73 65 74 2e 3c 2f 70 3e  n empty set.</p>
4790: 0a 0a 3c 70 3e 54 68 65 20 22 65 78 69 73 74 73  ..<p>The "exists
47a0: 22 20 6d 65 74 68 6f 64 20 69 73 20 6f 66 74 65  " method is ofte
47b0: 6e 20 75 73 65 64 20 74 6f 20 74 65 73 74 20 66  n used to test f
47c0: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
47d0: 20 6f 66 0a 72 6f 77 73 20 69 6e 20 61 20 74 61   of.rows in a ta
47e0: 62 6c 65 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  ble.  For exampl
47f0: 65 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  e:</p>..<blockqu
4800: 6f 74 65 3e 3c 62 3e 0a 69 66 20 7b 26 23 39 31  ote><b>.if {&#91
4810: 3b 64 62 20 65 78 69 73 74 73 20 7b 53 45 4c 45  ;db exists {SELE
4820: 43 54 20 31 20 46 52 4f 4d 20 74 61 62 6c 65 31  CT 1 FROM table1
4830: 20 57 48 45 52 45 20 75 73 65 72 3d 24 75 73 65   WHERE user=$use
4840: 72 7d 26 23 39 33 3b 7d 20 7b 3c 62 72 3e 0a 26  r}&#93;} {<br>.&
4850: 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70  nbsp;&nbsp;&nbsp
4860: 3b 23 20 50 72 6f 63 65 73 73 69 6e 67 20 69 66  ;# Processing if
4870: 20 24 75 73 65 72 20 65 78 69 73 74 73 3c 62 72   $user exists<br
4880: 3e 0a 7d 20 65 6c 73 65 20 7b 3c 62 72 3e 0a 26  >.} else {<br>.&
4890: 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70  nbsp;&nbsp;&nbsp
48a0: 3b 23 20 50 72 6f 63 65 73 73 69 6e 67 20 69 66  ;# Processing if
48b0: 20 24 75 73 65 72 20 64 6f 65 73 20 6e 6f 74 20   $user does not 
48c0: 65 78 69 73 74 3c 62 72 3e 0a 7d 0a 3c 2f 62 3e  exist<br>.}.</b>
48d0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 7d 0a  </blockquote>.}.
48e0: 0a 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ..##############
48f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4900: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4910: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4920: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4930: 0a 4d 45 54 48 4f 44 20 6c 61 73 74 5f 69 6e 73  .METHOD last_ins
4940: 65 72 74 5f 72 6f 77 69 64 20 7b 0a 0a 3c 70 3e  ert_rowid {..<p>
4950: 54 68 65 20 22 6c 61 73 74 5f 69 6e 73 65 72 74  The "last_insert
4960: 5f 72 6f 77 69 64 22 20 6d 65 74 68 6f 64 20 72  _rowid" method r
4970: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
4980: 72 20 77 68 69 63 68 20 69 73 20 74 68 65 20 52  r which is the R
4990: 4f 57 49 44 0a 6f 66 20 74 68 65 20 6d 6f 73 74  OWID.of the most
49a0: 20 72 65 63 65 6e 74 6c 79 20 69 6e 73 65 72 74   recently insert
49b0: 65 64 20 64 61 74 61 62 61 73 65 20 72 6f 77 2e  ed database row.
49c0: 3c 2f 70 3e 0a 7d 0a 0a 23 23 23 23 23 23 23 23  </p>.}..########
49d0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
49e0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
49f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4a00: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4a10: 23 23 23 23 23 23 0a 4d 45 54 48 4f 44 20 66 75  ######.METHOD fu
4a20: 6e 63 74 69 6f 6e 20 7b 0a 0a 3c 70 3e 54 68 65  nction {..<p>The
4a30: 20 22 66 75 6e 63 74 69 6f 6e 22 20 6d 65 74 68   "function" meth
4a40: 6f 64 20 72 65 67 69 73 74 65 72 73 20 6e 65 77  od registers new
4a50: 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 77   SQL functions w
4a60: 69 74 68 20 74 68 65 20 53 51 4c 69 74 65 20 65  ith the SQLite e
4a70: 6e 67 69 6e 65 2e 0a 54 68 65 20 61 72 67 75 6d  ngine..The argum
4a80: 65 6e 74 73 20 61 72 65 20 74 68 65 20 6e 61 6d  ents are the nam
4a90: 65 20 6f 66 20 74 68 65 20 6e 65 77 20 53 51 4c  e of the new SQL
4aa0: 20 66 75 6e 63 74 69 6f 6e 20 61 6e 64 20 61 20   function and a 
4ab0: 54 43 4c 20 63 6f 6d 6d 61 6e 64 20 74 68 61 74  TCL command that
4ac0: 0a 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 61 74  .implements that
4ad0: 20 66 75 6e 63 74 69 6f 6e 2e 20 20 41 72 67 75   function.  Argu
4ae0: 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 66 75 6e  ments to the fun
4af0: 63 74 69 6f 6e 20 61 72 65 20 61 70 70 65 6e 64  ction are append
4b00: 65 64 20 74 6f 20 74 68 65 0a 54 43 4c 20 63 6f  ed to the.TCL co
4b10: 6d 6d 61 6e 64 20 62 65 66 6f 72 65 20 69 74 20  mmand before it 
4b20: 69 73 20 69 6e 76 6f 6b 65 64 2e 3c 2f 70 3e 0a  is invoked.</p>.
4b30: 0a 3c 70 3e 0a 54 68 65 20 66 6f 6c 6c 6f 77 69  .<p>.The followi
4b40: 6e 67 20 65 78 61 6d 70 6c 65 20 63 72 65 61 74  ng example creat
4b50: 65 73 20 61 20 6e 65 77 20 53 51 4c 20 66 75 6e  es a new SQL fun
4b60: 63 74 69 6f 6e 20 6e 61 6d 65 64 20 22 68 65 78  ction named "hex
4b70: 22 20 74 68 61 74 20 63 6f 6e 76 65 72 74 73 0a  " that converts.
4b80: 69 74 73 20 6e 75 6d 65 72 69 63 20 61 72 67 75  its numeric argu
4b90: 6d 65 6e 74 20 69 6e 20 74 6f 20 61 20 68 65 78  ment in to a hex
4ba0: 61 64 65 63 69 6d 61 6c 20 65 6e 63 6f 64 65 64  adecimal encoded
4bb0: 20 73 74 72 69 6e 67 3a 0a 3c 2f 70 3e 0a 0a 3c   string:.</p>..<
4bc0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 62 3e 0a 64  blockquote><b>.d
4bd0: 62 20 66 75 6e 63 74 69 6f 6e 20 68 65 78 20 7b  b function hex {
4be0: 66 6f 72 6d 61 74 20 30 78 25 58 7d 0a 3c 2f 62  format 0x%X}.</b
4bf0: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  ></blockquote>..
4c00: 3c 70 3e 54 68 65 20 22 66 75 6e 63 74 69 6f 6e  <p>The "function
4c10: 22 20 6d 65 74 68 6f 64 20 61 63 63 65 70 74 73  " method accepts
4c20: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6f   the following o
4c30: 70 74 69 6f 6e 73 3a 0a 3c 62 6c 6f 63 6b 71 75  ptions:.<blockqu
4c40: 6f 74 65 3e 0a 3c 64 6c 3e 0a 0a 3c 64 74 3e 3c  ote>.<dl>..<dt><
4c50: 62 3e 2d 61 72 67 63 6f 75 6e 74 3c 2f 62 3e 20  b>-argcount</b> 
4c60: 3c 69 3e 49 4e 54 45 47 45 52 3c 2f 69 3e 3c 2f  <i>INTEGER</i></
4c70: 64 74 3e 0a 3c 64 64 3e 3c 70 3e 0a 53 70 65 63  dt>.<dd><p>.Spec
4c80: 69 66 79 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ify the number o
4c90: 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
4ca0: 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
4cb0: 6e 20 61 63 63 65 70 74 73 2e 20 20 54 68 65 20  n accepts.  The 
4cc0: 64 65 66 61 75 6c 74 0a 76 61 6c 75 65 20 6f 66  default.value of
4cd0: 20 2d 31 20 6d 65 61 6e 73 20 61 6e 79 20 6e 75   -1 means any nu
4ce0: 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
4cf0: 73 2e 0a 0a 3c 64 74 3e 3c 62 3e 2d 64 65 74 65  s...<dt><b>-dete
4d00: 72 6d 69 6e 69 73 74 69 63 3c 2f 62 3e 0a 3c 64  rministic</b>.<d
4d10: 64 3e 3c 70 3e 0a 54 68 69 73 20 6f 70 74 69 6f  d><p>.This optio
4d20: 6e 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  n indicates that
4d30: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69   the function wi
4d40: 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
4d50: 20 74 68 65 20 73 61 6d 65 0a 61 6e 73 77 65 72   the same.answer
4d60: 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20   given the same 
4d70: 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
4d80: 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65    The SQLite que
4d90: 72 79 20 6f 70 74 69 6d 69 7a 65 72 0a 75 73 65  ry optimizer.use
4da0: 73 20 74 68 69 73 20 69 6e 66 6f 72 6d 61 74 69  s this informati
4db0: 6f 6e 20 74 6f 20 63 61 63 68 65 20 61 6e 73 77  on to cache answ
4dc0: 65 72 73 20 66 72 6f 6d 20 66 75 6e 63 74 69 6f  ers from functio
4dd0: 6e 20 63 61 6c 6c 73 20 77 69 74 68 20 0a 63 6f  n calls with .co
4de0: 6e 73 74 61 6e 74 20 69 6e 70 75 74 73 20 61 6e  nstant inputs an
4df0: 64 20 72 65 75 73 65 20 74 68 65 20 72 65 73 75  d reuse the resu
4e00: 6c 74 20 72 61 74 68 65 72 20 74 68 61 6e 20 69  lt rather than i
4e10: 6e 76 6f 6b 65 20 74 68 65 20 66 75 6e 63 74 69  nvoke the functi
4e20: 6f 6e 0a 72 65 70 65 61 74 65 64 6c 79 2e 0a 3c  on.repeatedly..<
4e30: 2f 64 6c 3e 0a 0a 3c 64 74 3e 3c 62 3e 2d 72 65  /dl>..<dt><b>-re
4e40: 74 75 72 6e 74 79 70 65 20 69 6e 74 65 67 65 72  turntype integer
4e50: 7c 72 65 61 6c 7c 74 65 78 74 7c 62 6c 6f 62 7c  |real|text|blob|
4e60: 61 6e 79 3c 2f 62 3e 0a 3c 64 64 3e 3c 70 3e 0a  any</b>.<dd><p>.
4e70: 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
4e80: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
4e90: 20 74 68 65 20 74 79 70 65 20 6f 66 20 74 68 65   the type of the
4ea0: 20 72 65 73 75 6c 74 20 72 65 74 75 72 6e 65 64   result returned
4eb0: 20 62 79 20 74 68 65 0a 66 75 6e 63 74 69 6f 6e   by the.function
4ec0: 2e 20 20 49 66 20 74 68 69 73 20 6f 70 74 69 6f  .  If this optio
4ed0: 6e 20 69 73 20 73 65 74 20 74 6f 20 22 61 6e 79  n is set to "any
4ee0: 22 20 28 74 68 65 20 64 65 66 61 75 6c 74 29 2c  " (the default),
4ef0: 20 53 51 4c 69 74 65 20 61 74 74 65 6d 70 74 73   SQLite attempts
4f00: 20 74 6f 0a 64 65 74 65 72 6d 69 6e 65 20 74 68   to.determine th
4f10: 65 20 74 79 70 65 20 6f 66 20 65 61 63 68 20 76  e type of each v
4f20: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
4f30: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d   the function im
4f40: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 62 61 73  plementation bas
4f50: 65 64 0a 6f 6e 20 74 68 65 20 54 63 6c 20 76 61  ed.on the Tcl va
4f60: 6c 75 65 27 73 20 69 6e 74 65 72 6e 61 6c 20 74  lue's internal t
4f70: 79 70 65 2e 20 4f 72 2c 20 69 66 20 69 74 20 69  ype. Or, if it i
4f80: 73 20 73 65 74 20 74 6f 20 22 74 65 78 74 22 20  s set to "text" 
4f90: 6f 72 20 22 62 6c 6f 62 22 2c 20 74 68 65 0a 72  or "blob", the.r
4fa0: 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
4fb0: 20 61 6c 77 61 79 73 20 61 20 74 65 78 74 20 6f   always a text o
4fc0: 72 20 62 6c 6f 62 20 76 61 6c 75 65 2c 20 72 65  r blob value, re
4fd0: 73 70 65 63 74 69 76 65 6c 79 2e 20 49 66 20 74  spectively. If t
4fe0: 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 0a 73 65  his option is.se
4ff0: 74 20 74 6f 20 22 69 6e 74 65 67 65 72 22 2c 20  t to "integer", 
5000: 53 51 4c 69 74 65 20 61 74 74 65 6d 70 74 73 20  SQLite attempts 
5010: 74 6f 20 63 6f 65 72 63 65 20 74 68 65 20 76 61  to coerce the va
5020: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
5030: 74 68 65 20 66 75 6e 63 74 69 6f 6e 0a 74 6f 20  the function.to 
5040: 61 6e 20 69 6e 74 65 67 65 72 2e 20 49 66 20 74  an integer. If t
5050: 68 69 73 20 69 73 20 6e 6f 74 20 70 6f 73 73 69  his is not possi
5060: 62 6c 65 20 77 69 74 68 6f 75 74 20 64 61 74 61  ble without data
5070: 20 6c 6f 73 73 2c 20 69 74 20 61 74 74 65 6d 70   loss, it attemp
5080: 74 73 20 74 6f 20 63 6f 65 72 63 65 0a 69 74 20  ts to coerce.it 
5090: 74 6f 20 61 20 72 65 61 6c 20 76 61 6c 75 65 2c  to a real value,
50a0: 20 61 6e 64 20 66 69 6e 61 6c 6c 79 20 66 61 6c   and finally fal
50b0: 6c 73 20 62 61 63 6b 20 74 6f 20 74 65 78 74 2e  ls back to text.
50c0: 20 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20   If this option 
50d0: 69 73 20 73 65 74 20 74 6f 0a 22 72 65 61 6c 22  is set to."real"
50e0: 2c 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  , an attempt is 
50f0: 6d 61 64 65 20 74 6f 20 72 65 74 75 72 6e 20 61  made to return a
5100: 20 72 65 61 6c 20 76 61 6c 75 65 2c 20 66 61 6c   real value, fal
5110: 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 74 65 78  ling back to tex
5120: 74 20 69 66 20 74 68 69 73 0a 69 73 20 6e 6f 74  t if this.is not
5130: 20 70 6f 73 73 69 62 6c 65 2e 0a 0a 3c 2f 64 6c   possible...</dl
5140: 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  >.</blockquote>.
5150: 7d 0a 0a 23 23 23 23 23 23 23 23 23 23 23 23 23  }..#############
5160: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5170: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5180: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5190: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
51a0: 23 0a 4d 45 54 48 4f 44 20 6e 75 6c 6c 76 61 6c  #.METHOD nullval
51b0: 75 65 20 7b 0a 0a 3c 70 3e 0a 54 68 65 20 22 6e  ue {..<p>.The "n
51c0: 75 6c 6c 76 61 6c 75 65 22 20 6d 65 74 68 6f 64  ullvalue" method
51d0: 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 70   changes the rep
51e0: 72 65 73 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  resentation for 
51f0: 4e 55 4c 4c 20 72 65 74 75 72 6e 65 64 0a 61 73  NULL returned.as
5200: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 22   result of the "
5210: 65 76 61 6c 22 20 6d 65 74 68 6f 64 2e 3c 2f 70  eval" method.</p
5220: 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  >..<blockquote><
5230: 62 3e 0a 64 62 31 20 6e 75 6c 6c 76 61 6c 75 65  b>.db1 nullvalue
5240: 20 4e 55 4c 4c 0a 3c 2f 62 3e 3c 2f 62 6c 6f 63   NULL.</b></bloc
5250: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 20  kquote>..<p>The 
5260: 22 6e 75 6c 6c 76 61 6c 75 65 22 20 6d 65 74 68  "nullvalue" meth
5270: 6f 64 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  od is useful to 
5280: 64 69 66 66 65 72 20 62 65 74 77 65 65 6e 20 4e  differ between N
5290: 55 4c 4c 20 61 6e 64 20 65 6d 70 74 79 0a 63 6f  ULL and empty.co
52a0: 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 73 20 54  lumn values as T
52b0: 63 6c 20 6c 61 63 6b 73 20 61 20 4e 55 4c 4c 20  cl lacks a NULL 
52c0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2e 20  representation. 
52d0: 20 54 68 65 20 64 65 66 61 75 6c 74 0a 72 65 70   The default.rep
52e0: 72 65 73 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  resentation for 
52f0: 4e 55 4c 4c 20 76 61 6c 75 65 73 20 69 73 20 61  NULL values is a
5300: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 3c  n empty string.<
5310: 2f 70 3e 0a 7d 0a 0a 0a 0a 23 23 23 23 23 23 23  /p>.}....#######
5320: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5330: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5340: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5350: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5360: 23 23 23 23 23 23 23 0a 4d 45 54 48 4f 44 20 6f  #######.METHOD o
5370: 6e 65 63 6f 6c 75 6d 6e 20 7b 0a 0a 3c 70 3e 54  necolumn {..<p>T
5380: 68 65 20 22 6f 6e 65 63 6f 6c 75 6d 6e 22 20 6d  he "onecolumn" m
5390: 65 74 68 6f 64 20 77 6f 72 6b 73 20 6c 69 6b 65  ethod works like
53a0: 20 0a 22 3c 61 20 68 72 65 66 3d 22 23 65 76 61   ."<a href="#eva
53b0: 6c 22 3e 65 76 61 6c 3c 2f 61 3e 22 20 69 6e 20  l">eval</a>" in 
53c0: 74 68 61 74 20 69 74 20 65 76 61 6c 75 61 74 65  that it evaluate
53d0: 73 20 74 68 65 0a 53 51 4c 20 71 75 65 72 79 20  s the.SQL query 
53e0: 73 74 61 74 65 6d 65 6e 74 20 67 69 76 65 6e 20  statement given 
53f0: 61 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 2e  as its argument.
5400: 20 20 54 68 65 20 64 69 66 66 65 72 65 6e 63 65    The difference
5410: 20 69 73 20 74 68 61 74 0a 22 6f 6e 65 63 6f 6c   is that."onecol
5420: 75 6d 6e 22 20 72 65 74 75 72 6e 73 20 61 20 73  umn" returns a s
5430: 69 6e 67 6c 65 20 65 6c 65 6d 65 6e 74 20 77 68  ingle element wh
5440: 69 63 68 20 69 73 20 74 68 65 20 66 69 72 73 74  ich is the first
5450: 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 66   column of the.f
5460: 69 72 73 74 20 72 6f 77 20 6f 66 20 74 68 65 20  irst row of the 
5470: 71 75 65 72 79 20 72 65 73 75 6c 74 2e 3c 2f 70  query result.</p
5480: 3e 0a 0a 3c 70 3e 54 68 69 73 20 69 73 20 61 20  >..<p>This is a 
5490: 63 6f 6e 76 65 6e 69 65 6e 63 65 20 6d 65 74 68  convenience meth
54a0: 6f 64 2e 20 20 49 74 20 73 61 76 65 73 20 74 68  od.  It saves th
54b0: 65 20 75 73 65 72 20 66 72 6f 6d 20 68 61 76 69  e user from havi
54c0: 6e 67 20 74 6f 0a 64 6f 20 61 20 22 3c 74 74 3e  ng to.do a "<tt>
54d0: 26 23 39 31 3b 6c 69 6e 64 65 78 26 6e 62 73 70  &#91;lindex&nbsp
54e0: 3b 2e 2e 2e 26 6e 62 73 70 3b 30 26 23 39 33 3b  ;...&nbsp;0&#93;
54f0: 3c 2f 74 74 3e 22 20 6f 6e 20 74 68 65 20 72 65  </tt>" on the re
5500: 73 75 6c 74 73 20 6f 66 20 61 6e 20 22 65 76 61  sults of an "eva
5510: 6c 22 0a 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  l".in order to e
5520: 78 74 72 61 63 74 20 61 20 73 69 6e 67 6c 65 20  xtract a single 
5530: 63 6f 6c 75 6d 6e 20 72 65 73 75 6c 74 2e 3c 2f  column result.</
5540: 70 3e 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23 23  p>.}..##########
5550: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5560: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5570: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5580: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5590: 23 23 23 23 0a 4d 45 54 48 4f 44 20 63 68 61 6e  ####.METHOD chan
55a0: 67 65 73 20 7b 0a 0a 3c 70 3e 54 68 65 20 22 63  ges {..<p>The "c
55b0: 68 61 6e 67 65 73 22 20 6d 65 74 68 6f 64 20 72  hanges" method r
55c0: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
55d0: 72 20 77 68 69 63 68 20 69 73 20 74 68 65 20 6e  r which is the n
55e0: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 69 6e  umber of rows.in
55f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68   the database th
5600: 61 74 20 77 65 72 65 20 69 6e 73 65 72 74 65 64  at were inserted
5610: 2c 20 64 65 6c 65 74 65 64 2c 20 61 6e 64 2f 6f  , deleted, and/o
5620: 72 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68  r modified by th
5630: 65 20 6d 6f 73 74 0a 72 65 63 65 6e 74 20 22 65  e most.recent "e
5640: 76 61 6c 22 20 6d 65 74 68 6f 64 2e 3c 2f 70 3e  val" method.</p>
5650: 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23 23 23 23  .}..############
5660: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5670: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5680: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5690: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
56a0: 23 23 0a 4d 45 54 48 4f 44 20 74 6f 74 61 6c 5f  ##.METHOD total_
56b0: 63 68 61 6e 67 65 73 20 7b 0a 0a 3c 70 3e 54 68  changes {..<p>Th
56c0: 65 20 22 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e "total_changes
56d0: 22 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  " method returns
56e0: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
56f0: 68 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  h is the number 
5700: 6f 66 20 72 6f 77 73 0a 69 6e 20 74 68 65 20 64  of rows.in the d
5710: 61 74 61 62 61 73 65 20 74 68 61 74 20 77 65 72  atabase that wer
5720: 65 20 69 6e 73 65 72 74 65 64 2c 20 64 65 6c 65  e inserted, dele
5730: 74 65 64 2c 20 61 6e 64 2f 6f 72 20 6d 6f 64 69  ted, and/or modi
5740: 66 69 65 64 20 73 69 6e 63 65 20 74 68 65 0a 63  fied since the.c
5750: 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
5760: 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 66  connection was f
5770: 69 72 73 74 20 6f 70 65 6e 65 64 2e 3c 2f 70 3e  irst opened.</p>
5780: 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23 23 23 23  .}..############
5790: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
57a0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
57b0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
57c0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
57d0: 23 23 0a 4d 45 54 48 4f 44 20 61 75 74 68 6f 72  ##.METHOD author
57e0: 69 7a 65 72 20 7b 0a 0a 3c 70 3e 54 68 65 20 22  izer {..<p>The "
57f0: 61 75 74 68 6f 72 69 7a 65 72 22 20 6d 65 74 68  authorizer" meth
5800: 6f 64 20 70 72 6f 76 69 64 65 73 20 61 63 63 65  od provides acce
5810: 73 73 20 74 6f 20 74 68 65 20 0a 3c 61 20 68 72  ss to the .<a hr
5820: 65 66 3d 22 63 33 72 65 66 2f 73 65 74 5f 61 75  ef="c3ref/set_au
5830: 74 68 6f 72 69 7a 65 72 2e 68 74 6d 6c 22 3e 73  thorizer.html">s
5840: 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
5850: 72 69 7a 65 72 3c 2f 61 3e 0a 43 2f 43 2b 2b 20  rizer</a>.C/C++ 
5860: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
5870: 61 72 67 75 6d 65 6e 74 20 74 6f 20 61 75 74 68  argument to auth
5880: 6f 72 69 7a 65 72 20 69 73 20 74 68 65 20 6e 61  orizer is the na
5890: 6d 65 20 6f 66 20 61 20 70 72 6f 63 65 64 75 72  me of a procedur
58a0: 65 20 74 68 61 74 0a 69 73 20 63 61 6c 6c 65 64  e that.is called
58b0: 20 77 68 65 6e 20 53 51 4c 20 73 74 61 74 65 6d   when SQL statem
58c0: 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
58d0: 6f 6d 70 69 6c 65 64 20 69 6e 20 6f 72 64 65 72  ompiled in order
58e0: 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 0a 63 65   to authorize.ce
58f0: 72 74 61 69 6e 20 6f 70 65 72 61 74 69 6f 6e 73  rtain operations
5900: 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  .  The callback 
5910: 70 72 6f 63 65 64 75 72 65 20 74 61 6b 65 73 20  procedure takes 
5920: 35 20 61 72 67 75 6d 65 6e 74 73 20 77 68 69 63  5 arguments whic
5930: 68 20 64 65 73 63 72 69 62 65 0a 74 68 65 20 6f  h describe.the o
5940: 70 65 72 61 74 69 6f 6e 20 62 65 69 6e 67 20 63  peration being c
5950: 6f 64 65 64 2e 20 20 49 66 20 74 68 65 20 63 61  oded.  If the ca
5960: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 74  llback returns t
5970: 68 65 20 74 65 78 74 20 73 74 72 69 6e 67 0a 22  he text string."
5980: 53 51 4c 49 54 45 5f 4f 4b 22 2c 20 74 68 65 6e  SQLITE_OK", then
5990: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
59a0: 73 20 61 6c 6c 6f 77 65 64 2e 20 20 49 66 20 69  s allowed.  If i
59b0: 74 20 72 65 74 75 72 6e 73 20 22 53 51 4c 49 54  t returns "SQLIT
59c0: 45 5f 49 47 4e 4f 52 45 22 2c 0a 74 68 65 6e 20  E_IGNORE",.then 
59d0: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
59e0: 20 73 69 6c 65 6e 74 6c 79 20 64 69 73 61 62 6c   silently disabl
59f0: 65 64 2e 20 20 49 66 20 74 68 65 20 72 65 74 75  ed.  If the retu
5a00: 72 6e 20 69 73 20 22 53 51 4c 49 54 45 5f 44 45  rn is "SQLITE_DE
5a10: 4e 59 22 0a 74 68 65 6e 20 74 68 65 20 63 6f 6d  NY".then the com
5a20: 70 69 6c 61 74 69 6f 6e 20 66 61 69 6c 73 20 77  pilation fails w
5a30: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 0a 3c 2f  ith an error..</
5a40: 70 3e 0a 0a 3c 70 3e 49 66 20 74 68 65 20 61 72  p>..<p>If the ar
5a50: 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 65 6d 70  gument is an emp
5a60: 74 79 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  ty string then t
5a70: 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
5a80: 20 64 69 73 61 62 6c 65 64 2e 0a 49 66 20 74 68   disabled..If th
5a90: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6d  e argument is om
5aa0: 69 74 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20  itted, then the 
5ab0: 63 75 72 72 65 6e 74 20 61 75 74 68 6f 72 69 7a  current authoriz
5ac0: 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  er is returned.<
5ad0: 2f 70 3e 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23  /p>.}..#########
5ae0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5af0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5b00: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5b10: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5b20: 23 23 23 23 23 0a 4d 45 54 48 4f 44 20 62 69 6e  #####.METHOD bin
5b30: 64 5f 66 61 6c 6c 62 61 63 6b 20 7b 0a 0a 3c 70  d_fallback {..<p
5b40: 3e 54 68 65 20 22 62 69 6e 64 5f 66 61 6c 6c 62  >The "bind_fallb
5b50: 61 63 6b 22 20 6d 65 74 68 6f 64 20 67 69 76 65  ack" method give
5b60: 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
5b70: 6e 20 63 6f 6e 74 72 6f 6c 20 6f 76 65 72 20 68  n control over h
5b80: 6f 77 20 74 6f 0a 68 61 6e 64 6c 65 20 70 61 72  ow to.handle par
5b90: 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 20 77  ameter binding w
5ba0: 68 65 6e 20 6e 6f 20 54 43 4c 20 76 61 72 69 61  hen no TCL varia
5bb0: 62 6c 65 20 6d 61 74 63 68 65 73 20 74 68 65 20  ble matches the 
5bc0: 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 0a  parameter name..
5bd0: 0a 3c 70 3e 57 68 65 6e 20 74 68 65 20 3c 61 20  .<p>When the <a 
5be0: 68 72 65 66 3d 22 23 65 76 61 6c 22 3e 65 76 61  href="#eval">eva
5bf0: 6c 20 6d 65 74 68 6f 64 3c 2f 61 3e 20 73 65 65  l method</a> see
5c00: 73 20 61 20 6e 61 6d 65 64 20 53 51 4c 0a 70 61  s a named SQL.pa
5c10: 72 61 6d 65 74 65 72 20 73 75 63 68 20 61 73 20  rameter such as 
5c20: 22 24 61 62 63 22 20 6f 72 20 22 3a 64 65 66 22  "$abc" or ":def"
5c30: 20 6f 72 20 22 40 67 68 69 22 20 69 6e 20 61 6e   or "@ghi" in an
5c40: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
5c50: 69 74 20 74 72 69 65 73 0a 74 6f 20 6c 6f 6f 6b  it tries.to look
5c60: 20 75 70 20 61 20 54 43 4c 20 76 61 72 69 61 62   up a TCL variab
5c70: 6c 65 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  le with the same
5c80: 20 6e 61 6d 65 2c 20 61 6e 64 20 69 74 20 62 69   name, and it bi
5c90: 6e 64 73 20 74 68 65 20 76 61 6c 75 65 0a 6f 66  nds the value.of
5ca0: 20 74 68 61 74 20 54 43 4c 20 76 61 72 69 61 62   that TCL variab
5cb0: 6c 65 20 74 6f 20 74 68 65 20 53 51 4c 20 70 61  le to the SQL pa
5cc0: 72 61 6d 65 74 65 72 2e 20 20 49 66 20 6e 6f 20  rameter.  If no 
5cd0: 73 75 63 68 20 54 43 4c 20 76 61 72 69 61 62 6c  such TCL variabl
5ce0: 65 20 65 78 69 73 74 73 2c 0a 74 68 65 20 64 65  e exists,.the de
5cf0: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
5d00: 73 20 74 6f 20 62 69 6e 64 20 61 6e 20 53 51 4c  s to bind an SQL
5d10: 20 4e 55 4c 4c 20 76 61 6c 75 65 20 74 6f 20 74   NULL value to t
5d20: 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 48  he parameter.  H
5d30: 6f 77 65 76 65 72 2c 0a 69 66 20 61 20 62 69 6e  owever,.if a bin
5d40: 64 5f 66 61 6c 6c 62 61 63 6b 20 70 72 6f 63 20  d_fallback proc 
5d50: 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
5d60: 65 6e 20 74 68 61 74 20 70 72 6f 63 20 69 73 20  en that proc is 
5d70: 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65  invoked with the
5d80: 0a 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c  .name of the SQL
5d90: 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 74   parameter and t
5da0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
5db0: 66 72 6f 6d 20 74 68 65 20 70 72 6f 63 20 69 73  from the proc is
5dc0: 20 62 6f 75 6e 64 20 74 6f 0a 74 68 65 20 53 51   bound to.the SQ
5dd0: 4c 20 70 61 72 61 6d 65 74 65 72 2e 20 20 4f 72  L parameter.  Or
5de0: 20 69 66 20 74 68 65 20 70 72 6f 63 20 72 65 74   if the proc ret
5df0: 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2c 20 74  urns an error, t
5e00: 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
5e10: 65 6d 65 6e 74 0a 61 62 6f 72 74 73 20 77 69 74  ement.aborts wit
5e20: 68 20 74 68 61 74 20 65 72 72 6f 72 2e 20 20 49  h that error.  I
5e30: 66 20 74 68 65 20 70 72 6f 63 20 72 65 74 75 72  f the proc retur
5e40: 6e 73 20 77 69 74 68 20 73 6f 6d 65 20 63 6f 64  ns with some cod
5e50: 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 54 43 4c  e other than.TCL
5e60: 5f 4f 4b 20 6f 72 20 54 43 4c 5f 45 52 52 4f 52  _OK or TCL_ERROR
5e70: 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 70  , then the SQL p
5e80: 61 72 61 6d 65 74 65 72 20 69 73 20 62 6f 75 6e  arameter is boun
5e90: 64 20 74 6f 20 4e 55 4c 4c 2c 20 61 73 20 69 74  d to NULL, as it
5ea0: 20 77 6f 75 6c 64 0a 62 65 20 62 79 20 64 65 66   would.be by def
5eb0: 61 75 6c 74 2e 0a 0a 3c 70 3e 54 68 65 20 22 62  ault...<p>The "b
5ec0: 69 6e 64 5f 66 61 6c 6c 62 61 63 6b 22 20 6d 65  ind_fallback" me
5ed0: 74 68 6f 64 20 68 61 73 20 61 20 73 69 6e 67 6c  thod has a singl
5ee0: 65 20 6f 70 74 69 6f 6e 61 6c 20 61 72 67 75 6d  e optional argum
5ef0: 65 6e 74 2e 20 20 49 66 20 74 68 65 20 61 72 67  ent.  If the arg
5f00: 75 6d 65 6e 74 0a 69 73 20 61 6e 20 65 6d 70 74  ument.is an empt
5f10: 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 74  y string, then t
5f20: 68 65 20 62 69 6e 64 5f 66 61 6c 6c 62 61 63 6b  he bind_fallback
5f30: 20 69 73 20 63 61 6e 63 65 6c 6c 65 64 20 61 6e   is cancelled an
5f40: 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 62 65  d the default be
5f50: 68 61 76 69 6f 72 0a 69 73 20 72 65 73 74 6f 72  havior.is restor
5f60: 65 64 2e 20 20 49 66 20 74 68 65 20 61 72 67 75  ed.  If the argu
5f70: 6d 65 6e 74 20 69 73 20 61 20 6e 6f 6e 2d 65 6d  ment is a non-em
5f80: 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
5f90: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   the argument is
5fa0: 20 61 0a 54 43 4c 20 63 6f 6d 6d 61 6e 64 20 28   a.TCL command (
5fb0: 75 73 75 61 6c 6c 79 20 74 68 65 20 6e 61 6d 65  usually the name
5fc0: 20 6f 66 20 61 20 70 72 6f 63 29 20 74 6f 20 69   of a proc) to i
5fd0: 6e 76 6f 6b 65 20 77 68 65 6e 65 76 65 72 20 61  nvoke whenever a
5fe0: 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
5ff0: 0a 69 73 20 73 65 65 6e 20 74 68 61 74 20 64 6f  .is seen that do
6000: 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
6010: 20 54 43 4c 20 76 61 72 69 61 62 6c 65 2e 20 20   TCL variable.  
6020: 49 66 20 74 68 65 20 22 62 69 6e 64 5f 66 61 6c  If the "bind_fal
6030: 6c 62 61 63 6b 22 20 6d 65 74 68 6f 64 20 0a 69  lback" method .i
6040: 73 20 67 69 76 65 6e 20 6e 6f 20 61 72 67 75 6d  s given no argum
6050: 65 6e 74 73 2c 20 74 68 65 6e 20 74 68 65 20 63  ents, then the c
6060: 75 72 72 65 6e 74 20 62 69 6e 64 5f 66 61 6c 6c  urrent bind_fall
6070: 62 61 63 6b 20 63 6f 6d 6d 61 6e 64 20 69 73 20  back command is 
6080: 72 65 74 75 72 6e 65 64 2e 0a 0a 3c 70 3e 41 73  returned...<p>As
6090: 20 61 6e 20 65 78 61 6d 70 6c 65 2c 20 74 68 65   an example, the
60a0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65 74 75 70   following setup
60b0: 20 63 61 75 73 65 73 20 54 43 4c 20 74 6f 20 74   causes TCL to t
60c0: 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 20 69 66  hrow an error if
60d0: 0a 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .an SQL statemen
60e0: 74 20 63 6f 6e 74 61 69 6e 73 20 61 6e 20 70 61  t contains an pa
60f0: 72 61 6d 65 74 65 72 20 74 68 61 74 20 64 6f 65  rameter that doe
6100: 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20  s not match any 
6110: 67 6c 6f 62 61 6c 0a 54 43 4c 20 76 61 72 69 61  global.TCL varia
6120: 62 6c 65 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  ble:..<blockquot
6130: 65 3e 3c 70 72 65 3e 3c 62 3e 0a 70 72 6f 63 20  e><pre><b>.proc 
6140: 62 69 6e 64 5f 65 72 72 6f 72 20 7b 6e 6d 7d 20  bind_error {nm} 
6150: 7b 0a 20 20 65 72 72 6f 72 20 22 6e 6f 20 73 75  {.  error "no su
6160: 63 68 20 76 61 72 69 61 62 6c 65 3a 20 24 6e 6d  ch variable: $nm
6170: 22 0a 7d 0a 64 62 20 62 69 6e 64 5f 66 61 6c 6c  ".}.db bind_fall
6180: 62 61 63 6b 20 62 69 6e 64 5f 65 72 72 6f 72 0a  back bind_error.
6190: 3c 2f 62 3e 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  </b></pre></bloc
61a0: 6b 71 75 6f 74 65 3e 0a 7d 0a 0a 0a 23 23 23 23  kquote>.}...####
61b0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
61c0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
61d0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
61e0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
61f0: 23 23 23 23 23 23 23 23 23 23 0a 4d 45 54 48 4f  ##########.METHO
6200: 44 20 70 72 6f 67 72 65 73 73 20 7b 0a 0a 3c 70  D progress {..<p
6210: 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 72 65 67  >This method reg
6220: 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
6230: 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  k that is invoke
6240: 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
6250: 75 72 69 6e 67 0a 71 75 65 72 79 20 70 72 6f 63  uring.query proc
6260: 65 73 73 69 6e 67 2e 20 20 54 68 65 72 65 20 61  essing.  There a
6270: 72 65 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  re two arguments
6280: 3a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  : the number of 
6290: 53 51 4c 69 74 65 20 76 69 72 74 75 61 6c 0a 6d  SQLite virtual.m
62a0: 61 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 20 62  achine opcodes b
62b0: 65 74 77 65 65 6e 20 69 6e 76 6f 63 61 74 69 6f  etween invocatio
62c0: 6e 73 2c 20 61 6e 64 20 74 68 65 20 54 43 4c 20  ns, and the TCL 
62d0: 63 6f 6d 6d 61 6e 64 20 74 6f 20 69 6e 76 6f 6b  command to invok
62e0: 65 2e 0a 53 65 74 74 69 6e 67 20 74 68 65 20 70  e..Setting the p
62f0: 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
6300: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
6310: 69 6e 67 20 64 69 73 61 62 6c 65 73 20 69 74 2e  ing disables it.
6320: 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 70 72 6f  </p>..<p>The pro
6330: 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 63  gress callback c
6340: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 69  an be used to di
6350: 73 70 6c 61 79 20 74 68 65 20 73 74 61 74 75 73  splay the status
6360: 20 6f 66 20 61 20 6c 65 6e 67 74 68 79 0a 71 75   of a lengthy.qu
6370: 65 72 79 20 6f 72 20 74 6f 20 70 72 6f 63 65 73  ery or to proces
6380: 73 20 47 55 49 20 65 76 65 6e 74 73 20 64 75 72  s GUI events dur
6390: 69 6e 67 20 61 20 6c 65 6e 67 74 68 79 20 71 75  ing a lengthy qu
63a0: 65 72 79 2e 3c 2f 70 3e 0a 7d 0a 0a 0a 23 23 23  ery.</p>.}...###
63b0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
63c0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
63d0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
63e0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
63f0: 23 23 23 23 23 23 23 23 23 23 23 0a 4d 45 54 48  ###########.METH
6400: 4f 44 20 63 6f 6c 6c 61 74 65 20 7b 0a 0a 3c 70  OD collate {..<p
6410: 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 72 65 67  >This method reg
6420: 69 73 74 65 72 73 20 6e 65 77 20 74 65 78 74 20  isters new text 
6430: 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
6440: 63 65 73 2e 20 20 54 68 65 72 65 20 61 72 65 0a  ces.  There are.
6450: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 74  two arguments: t
6460: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
6470: 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63  ollating sequenc
6480: 65 20 61 6e 64 20 74 68 65 20 6e 61 6d 65 20 6f  e and the name o
6490: 66 20 61 0a 54 43 4c 20 70 72 6f 63 65 64 75 72  f a.TCL procedur
64a0: 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
64b0: 73 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66  s a comparison f
64c0: 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  unction for the 
64d0: 63 6f 6c 6c 61 74 69 6e 67 0a 73 65 71 75 65 6e  collating.sequen
64e0: 63 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 46 6f 72  ce..</p>..<p>For
64f0: 20 65 78 61 6d 70 6c 65 2c 20 74 68 65 20 66 6f   example, the fo
6500: 6c 6c 6f 77 69 6e 67 20 63 6f 64 65 20 69 6d 70  llowing code imp
6510: 6c 65 6d 65 6e 74 73 20 61 20 63 6f 6c 6c 61 74  lements a collat
6520: 69 6e 67 20 73 65 71 75 65 6e 63 65 20 63 61 6c  ing sequence cal
6530: 6c 65 64 0a 22 4e 4f 43 41 53 45 22 20 74 68 61  led."NOCASE" tha
6540: 74 20 73 6f 72 74 73 20 69 6e 20 74 65 78 74 20  t sorts in text 
6550: 6f 72 64 65 72 20 77 69 74 68 6f 75 74 20 72 65  order without re
6560: 67 61 72 64 20 74 6f 20 63 61 73 65 3a 0a 3c 2f  gard to case:.</
6570: 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  p>..<blockquote>
6580: 3c 70 72 65 3e 3c 62 3e 0a 70 72 6f 63 20 6e 6f  <pre><b>.proc no
6590: 63 61 73 65 5f 63 6f 6d 70 61 72 65 20 7b 61 20  case_compare {a 
65a0: 62 7d 20 7b 0a 20 20 72 65 74 75 72 6e 20 26 23  b} {.  return &#
65b0: 39 31 3b 73 74 72 69 6e 67 20 63 6f 6d 70 61 72  91;string compar
65c0: 65 20 26 23 39 31 3b 73 74 72 69 6e 67 20 74 6f  e &#91;string to
65d0: 6c 6f 77 65 72 20 24 61 5d 20 26 23 39 31 3b 73  lower $a] &#91;s
65e0: 74 72 69 6e 67 20 74 6f 6c 6f 77 65 72 20 24 62  tring tolower $b
65f0: 5d 5d 0a 7d 0a 64 62 20 63 6f 6c 6c 61 74 65 20  ]].}.db collate 
6600: 4e 4f 43 41 53 45 20 6e 6f 63 61 73 65 5f 63 6f  NOCASE nocase_co
6610: 6d 70 61 72 65 0a 3c 2f 62 3e 3c 2f 70 72 65 3e  mpare.</b></pre>
6620: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 7d 0a  </blockquote>.}.
6630: 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  .###############
6640: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6650: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6660: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6670: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a  ###############.
6680: 4d 45 54 48 4f 44 20 63 6f 6c 6c 61 74 69 6f 6e  METHOD collation
6690: 5f 6e 65 65 64 65 64 20 7b 0a 0a 3c 70 3e 54 68  _needed {..<p>Th
66a0: 69 73 20 6d 65 74 68 6f 64 20 72 65 67 69 73 74  is method regist
66b0: 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 72  ers a callback r
66c0: 6f 75 74 69 6e 65 20 74 68 61 74 20 69 73 20 69  outine that is i
66d0: 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
66e0: 53 51 4c 69 74 65 0a 65 6e 67 69 6e 65 20 6e 65  SQLite.engine ne
66f0: 65 64 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  eds a particular
6700: 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
6710: 6e 63 65 20 62 75 74 20 64 6f 65 73 20 6e 6f 74  nce but does not
6720: 20 68 61 76 65 20 74 68 61 74 0a 63 6f 6c 6c 61   have that.colla
6730: 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 72 65  ting sequence re
6740: 67 69 73 74 65 72 65 64 2e 20 20 54 68 65 20 63  gistered.  The c
6750: 61 6c 6c 62 61 63 6b 20 63 61 6e 20 72 65 67 69  allback can regi
6760: 73 74 65 72 20 74 68 65 20 63 6f 6c 6c 61 74 69  ster the collati
6770: 6e 67 0a 73 65 71 75 65 6e 63 65 2e 20 20 54 68  ng.sequence.  Th
6780: 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
6790: 76 6f 6b 65 64 20 77 69 74 68 20 61 20 73 69 6e  voked with a sin
67a0: 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
67b0: 69 63 68 20 69 73 20 74 68 65 0a 6e 61 6d 65 20  ich is the.name 
67c0: 6f 66 20 74 68 65 20 6e 65 65 64 65 64 20 63 6f  of the needed co
67d0: 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65  llating sequence
67e0: 2e 3c 2f 70 3e 0a 7d 0a 0a 23 23 23 23 23 23 23  .</p>.}..#######
67f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6800: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6810: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6820: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6830: 23 23 23 23 23 23 23 0a 4d 45 54 48 4f 44 20 63  #######.METHOD c
6840: 6f 6d 6d 69 74 5f 68 6f 6f 6b 20 7b 0a 0a 3c 70  ommit_hook {..<p
6850: 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 72 65 67  >This method reg
6860: 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
6870: 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
6880: 73 20 69 6e 76 6f 6b 65 64 20 6a 75 73 74 20 62  s invoked just b
6890: 65 66 6f 72 65 0a 53 51 4c 69 74 65 20 74 72 69  efore.SQLite tri
68a0: 65 73 20 74 6f 20 63 6f 6d 6d 69 74 20 63 68 61  es to commit cha
68b0: 6e 67 65 73 20 74 6f 20 61 20 64 61 74 61 62 61  nges to a databa
68c0: 73 65 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c  se.  If the call
68d0: 62 61 63 6b 20 74 68 72 6f 77 73 0a 61 6e 20 65  back throws.an e
68e0: 78 63 65 70 74 69 6f 6e 20 6f 72 20 72 65 74 75  xception or retu
68f0: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72  rns a non-zero r
6900: 65 73 75 6c 74 2c 20 74 68 65 6e 20 74 68 65 20  esult, then the 
6910: 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c  transaction roll
6920: 73 20 62 61 63 6b 0a 72 61 74 68 65 72 20 74 68  s back.rather th
6930: 61 6e 20 63 6f 6d 6d 69 74 2e 3c 2f 70 3e 0a 7d  an commit.</p>.}
6940: 0a 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ..##############
6950: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6960: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6970: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6980: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6990: 0a 4d 45 54 48 4f 44 20 72 6f 6c 6c 62 61 63 6b  .METHOD rollback
69a0: 5f 68 6f 6f 6b 20 7b 0a 0a 3c 70 3e 54 68 69 73  _hook {..<p>This
69b0: 20 6d 65 74 68 6f 64 20 72 65 67 69 73 74 65 72   method register
69c0: 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  s a callback rou
69d0: 74 69 6e 65 20 74 68 61 74 20 69 73 20 69 6e 76  tine that is inv
69e0: 6f 6b 65 64 20 6a 75 73 74 20 62 65 66 6f 72 65  oked just before
69f0: 0a 53 51 4c 69 74 65 20 74 72 69 65 73 20 74 6f  .SQLite tries to
6a00: 20 64 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 20   do a rollback. 
6a10: 20 54 68 65 20 73 63 72 69 70 74 20 61 72 67 75   The script argu
6a20: 6d 65 6e 74 20 69 73 20 72 75 6e 20 77 69 74 68  ment is run with
6a30: 6f 75 74 20 63 68 61 6e 67 65 2e 3c 2f 70 3e 0a  out change.</p>.
6a40: 7d 0a 0a 23 23 23 23 23 23 23 23 23 23 23 23 23  }..#############
6a50: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6a60: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6a70: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6a80: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6a90: 23 0a 4d 45 54 48 4f 44 20 73 74 61 74 75 73 20  #.METHOD status 
6aa0: 7b 0a 3c 70 3e 54 68 69 73 20 6d 65 74 68 6f 64  {.<p>This method
6ab0: 20 72 65 74 75 72 6e 73 20 73 74 61 74 75 73 20   returns status 
6ac0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 66 72 6f 6d  information from
6ad0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
6ae0: 6c 79 20 65 76 61 6c 75 61 74 65 64 0a 53 51 4c  ly evaluated.SQL
6af0: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65   statement.  The
6b00: 20 73 74 61 74 75 73 20 6d 65 74 68 6f 64 20 74   status method t
6b10: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
6b20: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 73 68 6f  gument which sho
6b30: 75 6c 64 20 62 65 0a 65 69 74 68 65 72 20 22 73  uld be.either "s
6b40: 74 65 70 73 22 20 6f 72 20 22 73 6f 72 74 73 22  teps" or "sorts"
6b50: 2e 20 20 49 66 20 74 68 65 20 61 72 67 75 6d 65  .  If the argume
6b60: 6e 74 20 69 73 20 22 73 74 65 70 73 22 2c 20 74  nt is "steps", t
6b70: 68 65 6e 20 74 68 65 20 6d 65 74 68 6f 64 0a 72  hen the method.r
6b80: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
6b90: 72 20 6f 66 20 66 75 6c 6c 20 74 61 62 6c 65 20  r of full table 
6ba0: 73 63 61 6e 20 73 74 65 70 73 20 74 68 61 74 20  scan steps that 
6bb0: 74 68 65 20 70 72 65 76 69 6f 75 73 20 53 51 4c  the previous SQL
6bc0: 20 73 74 61 74 65 6d 65 6e 74 0a 65 76 61 6c 75   statement.evalu
6bd0: 61 74 65 64 2e 20 20 49 66 20 74 68 65 20 61 72  ated.  If the ar
6be0: 67 75 6d 65 6e 74 20 69 73 20 22 73 6f 72 74 73  gument is "sorts
6bf0: 22 2c 20 74 68 65 20 6d 65 74 68 6f 64 20 72 65  ", the method re
6c00: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
6c10: 20 6f 66 0a 73 6f 72 74 20 6f 70 65 72 61 74 69   of.sort operati
6c20: 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 66 6f 72  ons.  This infor
6c30: 6d 61 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  mation can be us
6c40: 65 64 20 74 6f 20 64 65 74 65 63 74 20 71 75 65  ed to detect que
6c50: 72 69 65 73 20 74 68 61 74 20 61 72 65 0a 6e 6f  ries that are.no
6c60: 74 20 75 73 69 6e 67 20 69 6e 64 69 63 65 73 20  t using indices 
6c70: 74 6f 20 73 70 65 65 64 20 73 65 61 72 63 68 20  to speed search 
6c80: 6f 72 20 73 6f 72 74 69 6e 67 2e 3c 2f 70 3e 0a  or sorting.</p>.
6c90: 0a 3c 70 3e 54 68 65 20 73 74 61 74 75 73 20 6d  .<p>The status m
6ca0: 65 74 68 6f 64 20 69 73 20 62 61 73 69 63 61 6c  ethod is basical
6cb0: 6c 79 20 61 20 77 72 61 70 70 65 72 20 6f 6e 20  ly a wrapper on 
6cc0: 74 68 65 0a 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the.[sqlite3_stm
6cd0: 74 5f 73 74 61 74 75 73 28 29 5d 20 43 2d 6c 61  t_status()] C-la
6ce0: 6e 67 75 61 67 65 20 69 6e 74 65 72 66 61 63 65  nguage interface
6cf0: 2e 3c 2f 70 3e 0a 7d 0a 0a 0a 23 23 23 23 23 23  .</p>.}...######
6d00: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6d10: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6d20: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6d30: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6d40: 23 23 23 23 23 23 23 23 0a 4d 45 54 48 4f 44 20  ########.METHOD 
6d50: 75 70 64 61 74 65 5f 68 6f 6f 6b 20 7b 0a 0a 3c  update_hook {..<
6d60: 70 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 72 65  p>This method re
6d70: 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
6d80: 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
6d90: 69 73 20 69 6e 76 6f 6b 65 64 20 6a 75 73 74 20  is invoked just 
6da0: 62 65 66 6f 72 65 0a 65 61 63 68 20 72 6f 77 20  before.each row 
6db0: 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61  is modified by a
6dc0: 6e 20 55 50 44 41 54 45 2c 20 49 4e 53 45 52 54  n UPDATE, INSERT
6dd0: 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
6de0: 65 6d 65 6e 74 2e 20 20 46 6f 75 72 0a 61 72 67  ement.  Four.arg
6df0: 75 6d 65 6e 74 73 20 61 72 65 20 61 70 70 65 6e  uments are appen
6e00: 64 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ded to the callb
6e10: 61 63 6b 20 62 65 66 6f 72 65 20 69 74 20 69 73  ack before it is
6e20: 20 69 6e 76 6f 6b 65 64 3a 3c 2f 70 3e 0a 0a 3c   invoked:</p>..<
6e30: 75 6c 3e 0a 3c 6c 69 3e 54 68 65 20 6b 65 79 77  ul>.<li>The keyw
6e40: 6f 72 64 20 22 49 4e 53 45 52 54 22 2c 20 22 55  ord "INSERT", "U
6e50: 50 44 41 54 45 22 2c 20 6f 72 20 22 44 45 4c 45  PDATE", or "DELE
6e60: 54 45 22 2c 20 61 73 20 61 70 70 72 6f 70 72 69  TE", as appropri
6e70: 61 74 65 3c 2f 6c 69 3e 0a 3c 6c 69 3e 54 68 65  ate</li>.<li>The
6e80: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
6e90: 61 62 61 73 65 20 77 68 69 63 68 20 69 73 20 62  abase which is b
6ea0: 65 69 6e 67 20 63 68 61 6e 67 65 64 3c 2f 6c 69  eing changed</li
6eb0: 3e 0a 3c 6c 69 3e 54 68 65 20 74 61 62 6c 65 20  >.<li>The table 
6ec0: 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 63 68  that is being ch
6ed0: 61 6e 67 65 64 3c 2f 6c 69 3e 0a 3c 6c 69 3e 54  anged</li>.<li>T
6ee0: 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20  he rowid of the 
6ef0: 72 6f 77 20 69 6e 20 74 68 65 20 74 61 62 6c 65  row in the table
6f00: 20 62 65 69 6e 67 20 63 68 61 6e 67 65 64 3c 2f   being changed</
6f10: 6c 69 3e 0a 3c 2f 75 6c 3e 0a 7d 0a 0a 23 23 23  li>.</ul>.}..###
6f20: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6f30: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6f40: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6f50: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6f60: 23 23 23 23 23 23 23 23 23 23 23 0a 4d 45 54 48  ###########.METH
6f70: 4f 44 20 77 61 6c 5f 68 6f 6f 6b 20 7b 0a 0a 3c  OD wal_hook {..<
6f80: 70 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 72 65  p>This method re
6f90: 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
6fa0: 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
6fb0: 69 73 20 69 6e 76 6f 6b 65 64 20 61 66 74 65 72  is invoked after
6fc0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 63 6f 6d   transaction.com
6fd0: 6d 69 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  mit when the dat
6fe0: 61 62 61 73 65 20 69 73 20 69 6e 20 5b 57 41 4c  abase is in [WAL
6ff0: 20 6d 6f 64 65 5d 2e 20 20 54 77 6f 20 61 72 67   mode].  Two arg
7000: 75 6d 65 6e 74 73 20 61 72 65 20 61 70 70 65 6e  uments are appen
7010: 64 65 64 20 74 6f 20 74 68 65 0a 63 61 6c 6c 62  ded to the.callb
7020: 61 63 6b 20 63 6f 6d 6d 61 6e 64 20 62 65 66 6f  ack command befo
7030: 72 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64  re it is invoked
7040: 3a 3c 2f 70 3e 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e  :</p>..<ul>.<li>
7050: 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
7060: 64 61 74 61 62 61 73 65 20 6f 6e 20 77 68 69 63  database on whic
7070: 68 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  h the transactio
7080: 6e 20 77 61 73 20 63 6f 6d 6d 69 74 74 65 64 0a  n was committed.
7090: 3c 6c 69 3e 54 68 65 20 6e 75 6d 62 65 72 20 6f  <li>The number o
70a0: 66 20 65 6e 74 72 69 65 73 20 69 6e 20 74 68 65  f entries in the
70b0: 20 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67   write-ahead log
70c0: 20 28 57 41 4c 29 20 66 69 6c 65 20 66 6f 72 20   (WAL) file for 
70d0: 74 68 61 74 20 64 61 74 61 62 61 73 65 0a 3c 2f  that database.</
70e0: 75 6c 3e 0a 0a 3c 70 3e 54 68 69 73 20 6d 65 74  ul>..<p>This met
70f0: 68 6f 64 20 6d 69 67 68 74 20 64 65 63 69 64 65  hod might decide
7100: 20 74 6f 20 72 75 6e 20 61 20 5b 63 68 65 63 6b   to run a [check
7110: 70 6f 69 6e 74 5d 20 65 69 74 68 65 72 20 69 74  point] either it
7120: 73 65 6c 66 20 6f 72 20 61 73 20 61 0a 73 75 62  self or as a.sub
7130: 73 65 71 75 65 6e 74 20 69 64 6c 65 20 63 61 6c  sequent idle cal
7140: 6c 62 61 63 6b 2e 20 20 4e 6f 74 65 20 74 68 61  lback.  Note tha
7150: 74 20 53 51 4c 69 74 65 20 6f 6e 6c 79 20 61 6c  t SQLite only al
7160: 6c 6f 77 73 20 61 20 73 69 6e 67 6c 65 20 57 41  lows a single WA
7170: 4c 20 68 6f 6f 6b 2e 0a 42 79 20 64 65 66 61 75  L hook..By defau
7180: 6c 74 20 74 68 69 73 20 73 69 6e 67 6c 65 20 57  lt this single W
7190: 41 4c 20 68 6f 6f 6b 20 69 73 20 75 73 65 64 20  AL hook is used 
71a0: 66 6f 72 20 74 68 65 20 61 75 74 6f 2d 63 68 65  for the auto-che
71b0: 63 6b 70 6f 69 6e 74 69 6e 67 2e 20 20 49 66 20  ckpointing.  If 
71c0: 79 6f 75 0a 73 65 74 20 75 70 20 61 6e 20 65 78  you.set up an ex
71d0: 70 6c 69 63 69 74 20 57 41 4c 20 68 6f 6f 6b 2c  plicit WAL hook,
71e0: 20 74 68 65 6e 20 74 68 61 74 20 6f 6e 65 20 57   then that one W
71f0: 41 4c 20 68 6f 6f 6b 20 6d 75 73 74 20 65 6e 73  AL hook must ens
7200: 75 72 65 20 74 68 61 74 20 63 68 65 63 6b 70 6f  ure that checkpo
7210: 69 6e 74 73 0a 61 72 65 20 6f 63 63 75 72 72 69  ints.are occurri
7220: 6e 67 20 73 69 6e 63 65 20 74 68 65 20 61 75 74  ng since the aut
7230: 6f 2d 63 68 65 63 6b 70 6f 69 6e 74 69 6e 67 20  o-checkpointing 
7240: 6d 65 63 68 61 6e 69 73 6d 20 77 69 6c 6c 20 62  mechanism will b
7250: 65 20 64 69 73 61 62 6c 65 64 2e 3c 2f 70 3e 0a  e disabled.</p>.
7260: 0a 3c 70 3e 54 68 69 73 20 6d 65 74 68 6f 64 20  .<p>This method 
7270: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 61 6e  should return an
7280: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 74   integer value t
7290: 68 61 74 20 69 73 20 65 71 75 69 76 61 6c 65 6e  hat is equivalen
72a0: 74 20 74 6f 20 61 6e 20 0a 53 51 4c 69 74 65 20  t to an .SQLite 
72b0: 65 72 72 6f 72 20 63 6f 64 65 20 28 75 73 75 61  error code (usua
72c0: 6c 6c 79 20 30 20 66 6f 72 20 53 51 4c 49 54 45  lly 0 for SQLITE
72d0: 5f 4f 4b 20 69 6e 20 74 68 65 20 63 61 73 65 20  _OK in the case 
72e0: 6f 66 20 73 75 63 63 65 73 73 20 6f 72 20 31 20  of success or 1 
72f0: 66 6f 72 0a 53 51 4c 49 54 45 5f 45 52 52 4f 52  for.SQLITE_ERROR
7300: 20 69 66 20 73 6f 6d 65 20 65 72 72 6f 72 20 6f   if some error o
7310: 63 63 75 72 73 29 2e 20 41 73 20 69 6e 20 5b 73  ccurs). As in [s
7320: 71 6c 69 74 65 33 5f 77 61 6c 5f 68 6f 6f 6b 28  qlite3_wal_hook(
7330: 29 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  )], the results 
7340: 6f 66 0a 72 65 74 75 72 6e 69 6e 67 20 61 6e 20  of.returning an 
7350: 69 6e 74 65 67 65 72 20 74 68 61 74 20 64 6f 65  integer that doe
7360: 73 20 6e 6f 74 20 63 6f 72 72 65 73 70 6f 6e 64  s not correspond
7370: 20 74 6f 20 61 6e 20 53 51 4c 69 74 65 20 65 72   to an SQLite er
7380: 72 6f 72 20 63 6f 64 65 20 61 72 65 0a 75 6e 64  ror code are.und
7390: 65 66 69 6e 65 64 2e 20 49 66 20 74 68 65 20 76  efined. If the v
73a0: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
73b0: 20 74 68 65 20 73 63 72 69 70 74 20 63 61 6e 6e   the script cann
73c0: 6f 74 20 62 65 20 69 6e 74 65 72 70 72 65 74 65  ot be interprete
73d0: 64 20 61 73 20 61 6e 0a 69 6e 74 65 67 65 72 20  d as an.integer 
73e0: 76 61 6c 75 65 2c 20 6f 72 20 69 66 20 74 68 65  value, or if the
73f0: 20 73 63 72 69 70 74 20 74 68 72 6f 77 73 20 61   script throws a
7400: 20 54 63 6c 20 65 78 63 65 70 74 69 6f 6e 2c 20   Tcl exception, 
7410: 6e 6f 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  no error is retu
7420: 72 6e 65 64 20 74 6f 0a 53 51 4c 69 74 65 20 62  rned to.SQLite b
7430: 75 74 20 61 20 54 63 6c 20 62 61 63 6b 67 72 6f  ut a Tcl backgro
7440: 75 6e 64 2d 65 72 72 6f 72 20 69 73 20 72 61 69  und-error is rai
7450: 73 65 64 2e 0a 7d 0a 0a 23 23 23 23 23 23 23 23  sed..}..########
7460: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
7470: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
7480: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
7490: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
74a0: 23 23 23 23 23 23 0a 4d 45 54 48 4f 44 20 69 6e  ######.METHOD in
74b0: 63 72 62 6c 6f 62 20 7b 0a 0a 3c 70 3e 54 68 69  crblob {..<p>Thi
74c0: 73 20 6d 65 74 68 6f 64 20 6f 70 65 6e 73 20 61  s method opens a
74d0: 20 54 43 4c 20 63 68 61 6e 6e 65 6c 20 74 68 61   TCL channel tha
74e0: 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  t can be used to
74f0: 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 0a 69   read or write.i
7500: 6e 74 6f 20 61 20 70 72 65 65 78 69 73 74 69 6e  nto a preexistin
7510: 67 20 42 4c 4f 42 20 69 6e 20 74 68 65 20 64 61  g BLOB in the da
7520: 74 61 62 61 73 65 2e 20 20 54 68 65 20 73 79 6e  tabase.  The syn
7530: 74 61 78 20 69 73 20 6c 69 6b 65 20 74 68 69 73  tax is like this
7540: 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  :</p>..<blockquo
7550: 74 65 3e 0a 3c 69 3e 64 62 63 6d 64 3c 2f 69 3e  te>.<i>dbcmd</i>
7560: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 62 3e 69  &nbsp;&nbsp;<b>i
7570: 6e 63 72 62 6c 6f 62 3c 2f 62 3e 26 6e 62 73 70  ncrblob</b>&nbsp
7580: 3b 26 6e 62 73 70 3b 3c 62 3e 3f 2d 72 65 61 64  ;&nbsp;<b>?-read
7590: 6f 6e 6c 79 3f 3c 2f 62 3e 0a 26 6e 62 73 70 3b  only?</b>.&nbsp;
75a0: 26 6e 62 73 70 3b 3c 69 3e 3f 44 42 3f 26 6e 62  &nbsp;<i>?DB?&nb
75b0: 73 70 3b 26 6e 62 73 70 3b 54 41 42 4c 45 26 6e  sp;&nbsp;TABLE&n
75c0: 62 73 70 3b 26 6e 62 73 70 3b 43 4f 4c 55 4d 4e  bsp;&nbsp;COLUMN
75d0: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 52 4f 57 49  &nbsp;&nbsp;ROWI
75e0: 44 3c 2f 69 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f  D</i>.</blockquo
75f0: 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65 20 63 6f 6d  te>..<p>.The com
7600: 6d 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 6e  mand returns a n
7610: 65 77 20 54 43 4c 20 63 68 61 6e 6e 65 6c 20 66  ew TCL channel f
7620: 6f 72 20 72 65 61 64 69 6e 67 20 6f 72 20 77 72  or reading or wr
7630: 69 74 69 6e 67 20 74 6f 20 74 68 65 20 42 4c 4f  iting to the BLO
7640: 42 2e 0a 54 68 65 20 63 68 61 6e 6e 65 6c 20 69  B..The channel i
7650: 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 20 74  s opened using t
7660: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 0a 3c  he underlying .<
7670: 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 62 6c  a href="c3ref/bl
7680: 6f 62 5f 6f 70 65 6e 2e 68 74 6d 6c 22 3e 73 71  ob_open.html">sq
7690: 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
76a0: 29 3c 2f 61 3e 20 43 2d 6c 61 6e 67 75 61 67 65  )</a> C-language
76b0: 0a 69 6e 74 65 72 66 61 63 65 2e 20 20 43 6c 6f  .interface.  Clo
76c0: 73 65 20 74 68 65 20 63 68 61 6e 6e 65 6c 20 75  se the channel u
76d0: 73 69 6e 67 20 74 68 65 20 3c 62 3e 63 6c 6f 73  sing the <b>clos
76e0: 65 3c 2f 62 3e 20 63 6f 6d 6d 61 6e 64 20 6f 66  e</b> command of
76f0: 20 54 43 4c 2e 0a 3c 2f 70 3e 0a 7d 0a 0a 23 23   TCL..</p>.}..##
7700: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
7710: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
7720: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
7730: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
7740: 23 23 23 23 23 23 23 23 23 23 23 23 0a 4d 45 54  ############.MET
7750: 48 4f 44 20 65 72 72 6f 72 63 6f 64 65 20 7b 0a  HOD errorcode {.
7760: 0a 3c 70 3e 54 68 69 73 20 6d 65 74 68 6f 64 20  .<p>This method 
7770: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
7780: 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 74  ric error code t
7790: 68 61 74 20 72 65 73 75 6c 74 65 64 20 66 72 6f  hat resulted fro
77a0: 6d 20 74 68 65 20 6d 6f 73 74 0a 72 65 63 65 6e  m the most.recen
77b0: 74 20 53 51 4c 69 74 65 20 6f 70 65 72 61 74 69  t SQLite operati
77c0: 6f 6e 2e 3c 2f 70 3e 0a 7d 0a 0a 23 23 23 23 23  on.</p>.}..#####
77d0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
77e0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
77f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
7800: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
7810: 23 23 23 23 23 23 23 23 23 0a 4d 45 54 48 4f 44  #########.METHOD
7820: 20 74 72 61 63 65 20 7b 0a 0a 3c 70 3e 54 68 65   trace {..<p>The
7830: 20 22 74 72 61 63 65 22 20 6d 65 74 68 6f 64 20   "trace" method 
7840: 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
7850: 62 61 63 6b 20 74 68 61 74 20 69 73 20 69 6e 76  back that is inv
7860: 6f 6b 65 64 20 61 73 20 65 61 63 68 20 53 51 4c  oked as each SQL
7870: 0a 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f  .statement is co
7880: 6d 70 69 6c 65 64 2e 20 20 54 68 65 20 74 65 78  mpiled.  The tex
7890: 74 20 6f 66 20 74 68 65 20 53 51 4c 20 69 73 20  t of the SQL is 
78a0: 61 70 70 65 6e 64 65 64 20 61 73 20 61 20 73 69  appended as a si
78b0: 6e 67 6c 65 20 73 74 72 69 6e 67 0a 74 6f 20 74  ngle string.to t
78c0: 68 65 20 63 6f 6d 6d 61 6e 64 20 62 65 66 6f 72  he command befor
78d0: 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e  e it is invoked.
78e0: 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73    This can be us
78f0: 65 64 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 29  ed (for example)
7900: 20 74 6f 0a 6b 65 65 70 20 61 20 6c 6f 67 20 6f   to.keep a log o
7910: 66 20 61 6c 6c 20 53 51 4c 20 6f 70 65 72 61 74  f all SQL operat
7920: 69 6f 6e 73 20 74 68 61 74 20 61 6e 20 61 70 70  ions that an app
7930: 6c 69 63 61 74 69 6f 6e 20 70 65 72 66 6f 72 6d  lication perform
7940: 73 2e 0a 3c 2f 70 3e 0a 7d 0a 0a 23 23 23 23 23  s..</p>.}..#####
7950: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
7960: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
7970: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
7980: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
7990: 23 23 23 23 23 23 23 23 23 0a 4d 45 54 48 4f 44  #########.METHOD
79a0: 20 74 72 61 63 65 5f 76 32 20 7b 0a 0a 3c 70 3e   trace_v2 {..<p>
79b0: 54 68 65 20 22 74 72 61 63 65 5f 76 32 22 20 6d  The "trace_v2" m
79c0: 65 74 68 6f 64 20 72 65 67 69 73 74 65 72 73 20  ethod registers 
79d0: 61 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20  a callback that 
79e0: 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 65 61  is invoked as ea
79f0: 63 68 20 53 51 4c 0a 73 74 61 74 65 6d 65 6e 74  ch SQL.statement
7a00: 20 69 73 20 63 6f 6d 70 69 6c 65 64 2e 20 54 68   is compiled. Th
7a10: 65 20 73 79 6e 74 61 78 20 69 73 20 61 73 20 66  e syntax is as f
7a20: 6f 6c 6c 6f 77 73 3a 0a 0a 0a 3c 62 6c 6f 63 6b  ollows:...<block
7a30: 71 75 6f 74 65 3e 0a 3c 69 3e 64 62 63 6d 64 3c  quote>.<i>dbcmd<
7a40: 2f 69 3e 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c  /i>&nbsp;&nbsp;<
7a50: 62 3e 74 72 61 63 65 5f 76 32 3c 2f 62 3e 26 6e  b>trace_v2</b>&n
7a60: 62 73 70 3b 26 6e 62 73 70 3b 3f 3c 69 3e 63 61  bsp;&nbsp;?<i>ca
7a70: 6c 6c 62 61 63 6b 3c 2f 69 3e 3f 26 6e 62 73 70  llback</i>?&nbsp
7a80: 3b 26 6e 62 73 70 3b 3f 3c 69 3e 6d 61 73 6b 3c  ;&nbsp;?<i>mask<
7a90: 2f 69 3e 3f 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /i>?.</blockquot
7aa0: 65 3e 0a 0a 3c 70 3e 54 68 69 73 20 63 6f 6d 6d  e>..<p>This comm
7ab0: 61 6e 64 20 63 61 75 73 65 73 20 74 68 65 20 22  and causes the "
7ac0: 63 61 6c 6c 62 61 63 6b 22 20 73 63 72 69 70 74  callback" script
7ad0: 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
7ae0: 68 65 6e 65 76 65 72 0a 63 65 72 74 61 69 6e 20  henever.certain 
7af0: 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 63 63 75 72  conditions occur
7b00: 73 2e 20 20 54 68 65 20 63 6f 6e 64 69 74 69 6f  s.  The conditio
7b10: 6e 73 20 61 72 65 20 64 65 74 65 72 6d 69 6e 65  ns are determine
7b20: 64 20 62 79 20 74 68 65 20 3c 69 3e 6d 61 73 6b  d by the <i>mask
7b30: 3c 2f 69 3e 0a 61 72 67 75 6d 65 6e 74 2c 20 77  </i>.argument, w
7b40: 68 69 63 68 20 73 68 6f 75 6c 64 20 62 65 20 61  hich should be a
7b50: 20 54 43 4c 2d 6c 69 73 74 20 6f 66 20 7a 65 72   TCL-list of zer
7b60: 6f 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  o or more of the
7b70: 20 66 6f 6c 6c 6f 77 69 6e 67 0a 6b 65 79 77 6f   following.keywo
7b80: 72 64 73 3a 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e 20  rds:..<ul>.<li> 
7b90: 3c 62 3e 73 74 61 74 65 6d 65 6e 74 3c 2f 62 3e  <b>statement</b>
7ba0: 0a 3c 6c 69 3e 20 3c 62 3e 70 72 6f 66 69 6c 65  .<li> <b>profile
7bb0: 3c 2f 62 3e 0a 3c 6c 69 3e 20 3c 62 3e 72 6f 77  </b>.<li> <b>row
7bc0: 3c 2f 62 3e 0a 3c 6c 69 3e 20 3c 62 3e 63 6c 6f  </b>.<li> <b>clo
7bd0: 73 65 3c 2f 62 3e 0a 3c 2f 75 6c 3e 0a 0a 3c 70  se</b>.</ul>..<p
7be0: 3e 54 72 61 63 65 73 20 66 6f 72 20 3c 62 3e 73  >Traces for <b>s
7bf0: 74 61 74 65 6d 65 6e 74 3c 2f 62 3e 20 69 6e 76  tatement</b> inv
7c00: 6f 6b 65 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  oke the callback
7c10: 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
7c20: 6e 74 73 0a 77 68 65 6e 65 76 65 72 20 61 20 6e  nts.whenever a n
7c30: 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
7c40: 20 69 73 20 72 75 6e 2e 0a 54 68 65 20 66 69 72   is run..The fir
7c50: 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
7c60: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
7c70: 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
7c80: 74 68 65 20 70 6f 69 6e 74 65 72 0a 74 6f 20 74  the pointer.to t
7c90: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 5b 73  he underlying [s
7ca0: 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
7cb0: 65 63 74 2e 20 20 54 68 69 73 20 69 6e 74 65 67  ect.  This integ
7cc0: 65 72 20 63 61 6e 20 62 65 20 75 73 65 64 0a 74  er can be used.t
7cd0: 6f 20 63 6f 72 72 65 6c 61 74 65 20 53 51 4c 20  o correlate SQL 
7ce0: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 77  statement text w
7cf0: 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ith the result o
7d00: 66 20 61 20 3c 62 3e 70 72 6f 66 69 6c 65 3c 2f  f a <b>profile</
7d10: 62 3e 0a 6f 72 20 3c 62 3e 72 6f 77 3c 2f 62 3e  b>.or <b>row</b>
7d20: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 73   callback. The s
7d30: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
7d40: 73 20 74 68 65 0a 75 6e 65 78 70 61 6e 64 65 64  s the.unexpanded
7d50: 20 74 65 78 74 20 6f 66 20 74 68 65 20 53 51 4c   text of the SQL
7d60: 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
7d70: 20 72 75 6e 2e 20 20 42 79 20 22 75 6e 65 78 70   run.  By "unexp
7d80: 61 6e 64 65 64 22 2c 20 77 65 0a 6d 65 61 6e 20  anded", we.mean 
7d90: 74 68 61 74 20 76 61 72 69 61 62 6c 65 20 73 75  that variable su
7da0: 62 73 74 69 74 75 74 69 6f 6e 73 20 69 6e 20 74  bstitutions in t
7db0: 68 65 20 74 65 78 74 20 61 72 65 20 6e 6f 74 20  he text are not 
7dc0: 65 78 70 61 6e 64 65 64 20 69 6e 74 6f 20 74 68  expanded into th
7dd0: 65 0a 76 61 72 69 61 62 6c 65 20 76 61 6c 75 65  e.variable value
7de0: 73 2e 20 20 54 68 69 73 20 69 73 20 64 69 66 66  s.  This is diff
7df0: 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 62  erent from the b
7e00: 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 22  ehavior of the "
7e10: 74 72 61 63 65 22 0a 6d 65 74 68 6f 64 20 77 68  trace".method wh
7e20: 69 63 68 20 64 6f 65 73 20 65 78 70 61 6e 64 20  ich does expand 
7e30: 76 61 72 69 61 62 6c 65 20 73 75 62 73 74 69 74  variable substit
7e40: 75 74 69 6f 6e 73 2e 0a 0a 3c 70 3e 54 72 61 63  utions...<p>Trac
7e50: 65 73 20 66 6f 72 20 3c 62 3e 70 72 6f 66 69 6c  es for <b>profil
7e60: 65 3c 2f 62 3e 20 69 6e 76 6f 6b 65 20 74 68 65  e</b> invoke the
7e70: 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 74   callback with t
7e80: 77 6f 20 61 72 67 75 6d 65 6e 74 73 0a 61 73 20  wo arguments.as 
7e90: 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
7ea0: 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68  nt finishes.  Th
7eb0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
7ec0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
7ed0: 68 69 63 68 0a 69 73 20 74 68 65 20 76 61 6c 75  hich.is the valu
7ee0: 65 20 6f 66 20 74 68 65 20 75 6e 64 65 72 6c 79  e of the underly
7ef0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  ing [sqlite3_stm
7f00: 74 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  t] object.  The 
7f10: 73 65 63 6f 6e 64 0a 61 72 67 75 6d 65 6e 74 20  second.argument 
7f20: 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61  is the approxima
7f30: 74 65 20 72 75 6e 2d 74 69 6d 65 20 66 6f 72 20  te run-time for 
7f40: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  the statement in
7f50: 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2e 0a 54 68   nanoseconds..Th
7f60: 65 20 72 75 6e 2d 74 69 6d 65 20 69 73 20 74 68  e run-time is th
7f70: 65 20 62 65 73 74 20 65 73 74 69 6d 61 74 65 20  e best estimate 
7f80: 61 76 61 69 6c 61 62 6c 65 20 64 65 70 65 6e 64  available depend
7f90: 69 6e 67 20 6f 6e 20 74 68 65 20 63 61 70 61 62  ing on the capab
7fa0: 69 6c 69 74 69 65 73 0a 6f 66 20 74 68 65 20 70  ilities.of the p
7fb0: 6c 61 74 66 6f 72 6d 20 6f 6e 20 77 68 69 63 68  latform on which
7fc0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
7fd0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 0a 3c 70   is running...<p
7fe0: 3e 54 72 61 63 65 73 20 66 6f 72 20 3c 62 3e 72  >Traces for <b>r
7ff0: 6f 77 3c 2f 62 3e 20 69 6e 76 6f 6b 65 20 74 68  ow</b> invoke th
8000: 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  e callback with 
8010: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
8020: 74 0a 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77  t.whenever a new
8030: 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 61   result row is a
8040: 76 61 69 6c 61 62 6c 65 20 66 72 6f 6d 20 61 6e  vailable from an
8050: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
8060: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
8070: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
8080: 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
8090: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a   the underlying.
80a0: 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
80b0: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 2e 0a 0a  bject pointer...
80c0: 3c 70 3e 54 72 61 63 65 73 20 66 6f 72 20 3c 62  <p>Traces for <b
80d0: 3e 63 6c 6f 73 65 3c 2f 62 3e 20 69 6e 76 6f 6b  >close</b> invok
80e0: 65 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77  e the callback w
80f0: 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67  ith a single arg
8100: 75 6d 65 6e 74 0a 61 73 20 74 68 65 20 64 61 74  ument.as the dat
8110: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8120: 20 69 73 20 63 6c 6f 73 69 6e 67 2e 20 20 54 68   is closing.  Th
8130: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  e argument is an
8140: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 0a 69   integer which.i
8150: 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61  s the value of a
8160: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
8170: 75 6e 64 65 72 6c 79 69 6e 67 20 5b 73 71 6c 69  underlying [sqli
8180: 74 65 33 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  te3] object that
8190: 20 69 73 0a 63 6c 6f 73 69 6e 67 2e 0a 0a 3c 70   is.closing...<p
81a0: 3e 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  >There can only 
81b0: 62 65 20 61 20 73 69 6e 67 6c 65 20 74 72 61 63  be a single trac
81c0: 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 69 73  e callback regis
81d0: 74 65 72 65 64 20 6f 6e 20 61 20 64 61 74 61 62  tered on a datab
81e0: 61 73 65 0a 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase.connection. 
81f0: 20 45 61 63 68 20 75 73 65 20 6f 66 20 22 74 72   Each use of "tr
8200: 61 63 65 22 20 6f 72 20 22 74 72 61 63 65 5f 76  ace" or "trace_v
8210: 32 22 20 63 61 6e 63 65 6c 73 20 61 6c 6c 20 70  2" cancels all p
8220: 72 69 6f 72 0a 74 72 61 63 65 20 63 61 6c 6c 62  rior.trace callb
8230: 61 63 6b 2e 0a 7d 0a 0a 23 23 23 23 23 23 23 23  ack..}..########
8240: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8250: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8260: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8270: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8280: 23 23 23 23 23 23 0a 4d 45 54 48 4f 44 20 62 61  ######.METHOD ba
8290: 63 6b 75 70 20 7b 0a 0a 3c 70 3e 54 68 65 20 22  ckup {..<p>The "
82a0: 62 61 63 6b 75 70 22 20 6d 65 74 68 6f 64 20 6d  backup" method m
82b0: 61 6b 65 73 20 61 20 62 61 63 6b 75 70 20 63 6f  akes a backup co
82c0: 70 79 20 6f 66 20 61 20 6c 69 76 65 20 64 61 74  py of a live dat
82d0: 61 62 61 73 65 2e 20 20 54 68 65 0a 63 6f 6d 6d  abase.  The.comm
82e0: 61 6e 64 20 73 79 6e 74 61 78 20 69 73 20 6c 69  and syntax is li
82f0: 6b 65 20 74 68 69 73 3a 3c 2f 70 3e 0a 0a 3c 62  ke this:</p>..<b
8300: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 69 3e 64 62  lockquote>.<i>db
8310: 63 6d 64 3c 2f 69 3e 26 6e 62 73 70 3b 26 6e 62  cmd</i>&nbsp;&nb
8320: 73 70 3b 3c 62 3e 62 61 63 6b 75 70 3c 2f 62 3e  sp;<b>backup</b>
8330: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3f 3c 69 3e  &nbsp;&nbsp;?<i>
8340: 73 6f 75 72 63 65 2d 64 61 74 61 62 61 73 65 3c  source-database<
8350: 2f 69 3e 3f 26 6e 62 73 70 3b 26 6e 62 73 70 3b  /i>?&nbsp;&nbsp;
8360: 3c 69 3e 62 61 63 6b 75 70 2d 66 69 6c 65 6e 61  <i>backup-filena
8370: 6d 65 3c 2f 69 3e 0a 3c 2f 62 6c 6f 63 6b 71 75  me</i>.</blockqu
8380: 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 20 6f 70 74  ote>..<p>The opt
8390: 69 6f 6e 61 6c 20 3c 69 3e 73 6f 75 72 63 65 2d  ional <i>source-
83a0: 64 61 74 61 62 61 73 65 3c 2f 69 3e 20 61 72 67  database</i> arg
83b0: 75 6d 65 6e 74 20 74 65 6c 6c 73 20 77 68 69 63  ument tells whic
83c0: 68 20 64 61 74 61 62 61 73 65 20 69 6e 0a 74 68  h database in.th
83d0: 65 20 63 75 72 72 65 6e 74 20 63 6f 6e 6e 65 63  e current connec
83e0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 62  tion should be b
83f0: 61 63 6b 65 64 20 75 70 2e 20 20 54 68 65 20 64  acked up.  The d
8400: 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
8410: 3c 62 3e 6d 61 69 6e 3c 2f 62 3e 0a 28 6f 72 2c  <b>main</b>.(or,
8420: 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   in other words,
8430: 20 74 68 65 20 70 72 69 6d 61 72 79 20 64 61 74   the primary dat
8440: 61 62 61 73 65 20 66 69 6c 65 29 2e 20 20 54 6f  abase file).  To
8450: 20 62 61 63 6b 20 75 70 20 54 45 4d 50 20 74 61   back up TEMP ta
8460: 62 6c 65 73 0a 75 73 65 20 3c 62 3e 74 65 6d 70  bles.use <b>temp
8470: 3c 2f 62 3e 2e 20 20 54 6f 20 62 61 63 6b 75 70  </b>.  To backup
8480: 20 61 6e 20 61 75 78 69 6c 69 61 72 79 20 64 61   an auxiliary da
8490: 74 61 62 61 73 65 20 61 64 64 65 64 20 74 6f 20  tabase added to 
84a0: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 75  the connection.u
84b0: 73 69 6e 67 20 74 68 65 20 5b 41 54 54 41 43 48  sing the [ATTACH
84c0: 5d 20 63 6f 6d 6d 61 6e 64 2c 20 75 73 65 20 74  ] command, use t
84d0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 61 74 20  he name of that 
84e0: 64 61 74 61 62 61 73 65 20 61 73 20 69 74 20 77  database as it w
84f0: 61 73 20 61 73 73 69 67 6e 65 64 0a 69 6e 20 74  as assigned.in t
8500: 68 65 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d  he [ATTACH] comm
8510: 61 6e 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65  and.</p>..<p>The
8520: 20 3c 69 3e 62 61 63 6b 75 70 2d 66 69 6c 65 6e   <i>backup-filen
8530: 61 6d 65 3c 2f 69 3e 20 69 73 20 74 68 65 20 6e  ame</i> is the n
8540: 61 6d 65 20 6f 66 20 61 20 66 69 6c 65 20 69 6e  ame of a file in
8550: 74 6f 20 77 68 69 63 68 20 74 68 65 20 62 61 63  to which the bac
8560: 6b 75 70 20 69 73 0a 77 72 69 74 74 65 6e 2e 20  kup is.written. 
8570: 20 3c 69 3e 42 61 63 6b 75 70 2d 66 69 6c 65 6e   <i>Backup-filen
8580: 61 6d 65 3c 2f 69 3e 20 64 6f 65 73 20 6e 6f 74  ame</i> does not
8590: 20 68 61 76 65 20 74 6f 20 65 78 69 73 74 20 61   have to exist a
85a0: 68 65 61 64 20 6f 66 20 74 69 6d 65 2c 20 62 75  head of time, bu
85b0: 74 20 69 66 0a 69 74 20 64 6f 65 73 2c 20 69 74  t if.it does, it
85c0: 20 6d 75 73 74 20 62 65 20 61 20 77 65 6c 6c 2d   must be a well-
85d0: 66 6f 72 6d 65 64 20 53 51 4c 69 74 65 20 64 61  formed SQLite da
85e0: 74 61 62 61 73 65 2e 3c 2f 70 3e 0a 7d 0a 0a 23  tabase.</p>.}..#
85f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8600: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8610: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8620: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8630: 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 4d 45  #############.ME
8640: 54 48 4f 44 20 72 65 73 74 6f 72 65 20 7b 0a 0a  THOD restore {..
8650: 3c 70 3e 54 68 65 20 22 72 65 73 74 6f 72 65 22  <p>The "restore"
8660: 20 6d 65 74 68 6f 64 20 63 6f 70 69 65 73 20 74   method copies t
8670: 68 65 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20  he content from 
8680: 61 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  a separate datab
8690: 61 73 65 20 66 69 6c 65 20 0a 69 6e 74 6f 20 74  ase file .into t
86a0: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62  he current datab
86b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
86c0: 6f 76 65 72 77 72 69 74 69 6e 67 20 61 6e 79 20  overwriting any 
86d0: 70 72 65 65 78 69 73 74 69 6e 67 20 63 6f 6e 74  preexisting cont
86e0: 65 6e 74 2e 0a 54 68 65 20 63 6f 6d 6d 61 6e 64  ent..The command
86f0: 20 73 79 6e 74 61 78 20 69 73 20 6c 69 6b 65 20   syntax is like 
8700: 74 68 69 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63  this:</p>..<bloc
8710: 6b 71 75 6f 74 65 3e 0a 3c 69 3e 64 62 63 6d 64  kquote>.<i>dbcmd
8720: 3c 2f 69 3e 26 6e 62 73 70 3b 26 6e 62 73 70 3b  </i>&nbsp;&nbsp;
8730: 3c 62 3e 72 65 73 74 6f 72 65 3c 2f 62 3e 26 6e  <b>restore</b>&n
8740: 62 73 70 3b 26 6e 62 73 70 3b 3f 3c 69 3e 74 61  bsp;&nbsp;?<i>ta
8750: 72 67 65 74 2d 64 61 74 61 62 61 73 65 3c 2f 69  rget-database</i
8760: 3e 3f 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 69  >?&nbsp;&nbsp;<i
8770: 3e 73 6f 75 72 63 65 2d 66 69 6c 65 6e 61 6d 65  >source-filename
8780: 3c 2f 69 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74  </i>.</blockquot
8790: 65 3e 0a 0a 3c 70 3e 54 68 65 20 6f 70 74 69 6f  e>..<p>The optio
87a0: 6e 61 6c 20 3c 69 3e 74 61 72 67 65 74 2d 64 61  nal <i>target-da
87b0: 74 61 62 61 73 65 3c 2f 69 3e 20 61 72 67 75 6d  tabase</i> argum
87c0: 65 6e 74 20 74 65 6c 6c 73 20 77 68 69 63 68 20  ent tells which 
87d0: 64 61 74 61 62 61 73 65 20 69 6e 0a 74 68 65 20  database in.the 
87e0: 63 75 72 72 65 6e 74 20 63 6f 6e 6e 65 63 74 69  current connecti
87f0: 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 6f 76 65  on should be ove
8800: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 6e 65  rwritten with ne
8810: 77 20 63 6f 6e 74 65 6e 74 2e 20 20 0a 54 68 65  w content.  .The
8820: 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
8830: 73 20 3c 62 3e 6d 61 69 6e 3c 2f 62 3e 20 0a 28  s <b>main</b> .(
8840: 6f 72 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f 72  or, in other wor
8850: 64 73 2c 20 74 68 65 20 70 72 69 6d 61 72 79 20  ds, the primary 
8860: 64 61 74 61 62 61 73 65 20 66 69 6c 65 29 2e 20  database file). 
8870: 20 54 6f 20 72 65 70 6f 70 75 6c 61 74 65 20 74   To repopulate t
8880: 68 65 20 54 45 4d 50 20 74 61 62 6c 65 73 0a 75  he TEMP tables.u
8890: 73 65 20 3c 62 3e 74 65 6d 70 3c 2f 62 3e 2e 20  se <b>temp</b>. 
88a0: 20 54 6f 20 6f 76 65 72 77 72 69 74 65 20 61 6e   To overwrite an
88b0: 20 61 75 78 69 6c 69 61 72 79 20 64 61 74 61 62   auxiliary datab
88c0: 61 73 65 20 61 64 64 65 64 20 74 6f 20 74 68 65  ase added to the
88d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 75 73 69 6e   connection.usin
88e0: 67 20 74 68 65 20 5b 41 54 54 41 43 48 5d 20 63  g the [ATTACH] c
88f0: 6f 6d 6d 61 6e 64 2c 20 75 73 65 20 74 68 65 20  ommand, use the 
8900: 6e 61 6d 65 20 6f 66 20 74 68 61 74 20 64 61 74  name of that dat
8910: 61 62 61 73 65 20 61 73 20 69 74 20 77 61 73 20  abase as it was 
8920: 61 73 73 69 67 6e 65 64 0a 69 6e 20 74 68 65 20  assigned.in the 
8930: 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
8940: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 3c 69  .</p>..<p>The <i
8950: 3e 73 6f 75 72 63 65 2d 66 69 6c 65 6e 61 6d 65  >source-filename
8960: 3c 2f 69 3e 20 69 73 20 74 68 65 20 6e 61 6d 65  </i> is the name
8970: 20 6f 66 20 61 6e 20 65 78 69 73 74 69 6e 67 20   of an existing 
8980: 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 53 51 4c 69  well-formed SQLi
8990: 74 65 0a 64 61 74 61 62 61 73 65 20 66 69 6c 65  te.database file
89a0: 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
89b0: 63 6f 6e 74 65 6e 74 20 69 73 20 65 78 74 72 61  content is extra
89c0: 63 74 65 64 2e 3c 2f 70 3e 0a 7d 0a 0a 23 23 23  cted.</p>.}..###
89d0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
89e0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
89f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8a00: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8a10: 23 23 23 23 23 23 23 23 23 23 23 0a 4d 45 54 48  ###########.METH
8a20: 4f 44 20 73 65 72 69 61 6c 69 7a 65 20 7b 0a 0a  OD serialize {..
8a30: 3c 70 3e 54 68 65 20 22 73 65 72 69 61 6c 69 7a  <p>The "serializ
8a40: 65 22 20 6d 65 74 68 6f 64 20 63 72 65 61 74 65  e" method create
8a50: 73 20 61 20 42 4c 4f 42 20 77 68 69 63 68 20 69  s a BLOB which i
8a60: 73 20 61 20 63 6f 6d 70 6c 65 74 65 20 63 6f 70  s a complete cop
8a70: 79 20 6f 66 20 61 6e 0a 75 6e 64 65 72 6c 79 69  y of an.underlyi
8a80: 6e 67 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ng database.  Th
8a90: 65 20 73 79 6e 74 61 78 20 69 73 20 6c 69 6b 65  e syntax is like
8aa0: 20 74 68 69 73 3a 0a 0a 3c 62 6c 6f 63 6b 71 75   this:..<blockqu
8ab0: 6f 74 65 3e 0a 3c 69 3e 64 62 63 6d 64 3c 2f 69  ote>.<i>dbcmd</i
8ac0: 3e 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 62 3e  >&nbsp;&nbsp;<b>
8ad0: 73 65 72 69 61 6c 69 7a 65 3c 2f 62 3e 26 6e 62  serialize</b>&nb
8ae0: 73 70 3b 26 6e 62 73 70 3b 3f 3c 69 3e 64 61 74  sp;&nbsp;?<i>dat
8af0: 61 62 61 73 65 3c 2f 69 3e 3f 0a 3c 2f 62 6c 6f  abase</i>?.</blo
8b00: 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65  ckquote>..<p>The
8b10: 20 6f 70 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65   optional argume
8b20: 6e 74 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  nt is the name o
8b30: 66 20 74 68 65 20 73 63 68 65 6d 61 20 6f 72 20  f the schema or 
8b40: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 73  database to be s
8b50: 65 72 69 61 6c 69 7a 65 64 2e 0a 54 68 65 20 64  erialized..The d
8b60: 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
8b70: 22 6d 61 69 6e 22 2e 0a 0a 3c 70 3e 54 68 69 73  "main"...<p>This
8b80: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
8b90: 20 61 20 54 43 4c 20 62 79 74 65 2d 61 72 72 61   a TCL byte-arra
8ba0: 79 20 74 68 61 74 20 69 73 20 74 68 65 20 63 6f  y that is the co
8bb0: 6d 70 6c 65 74 65 20 63 6f 6e 74 65 6e 74 20 6f  mplete content o
8bc0: 66 0a 74 68 65 20 69 64 65 6e 74 69 66 69 65 64  f.the identified
8bd0: 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73   database.  This
8be0: 20 62 79 74 65 2d 61 72 72 61 79 20 63 61 6e 20   byte-array can 
8bf0: 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
8c00: 61 20 66 69 6c 65 20 61 6e 64 0a 74 68 65 6e 20  a file and.then 
8c10: 75 73 65 64 20 61 73 20 61 6e 20 6f 72 64 69 6e  used as an ordin
8c20: 61 72 79 20 53 51 4c 69 74 65 20 64 61 74 61 62  ary SQLite datab
8c30: 61 73 65 2c 20 6f 72 20 69 74 20 63 61 6e 20 62  ase, or it can b
8c40: 65 20 73 65 6e 74 20 6f 76 65 72 20 61 20 54 43  e sent over a TC
8c50: 50 2f 49 50 0a 63 6f 6e 6e 65 63 74 69 6f 6e 20  P/IP.connection 
8c60: 74 6f 20 73 6f 6d 65 20 6f 74 68 65 72 20 61 70  to some other ap
8c70: 70 6c 69 63 61 74 69 6f 6e 2c 20 6f 72 20 70 61  plication, or pa
8c80: 73 73 65 64 20 74 6f 20 74 68 65 20 22 64 65 73  ssed to the "des
8c90: 65 72 69 61 6c 69 7a 65 22 20 6d 65 74 68 6f 64  erialize" method
8ca0: 0a 6f 66 20 61 6e 6f 74 68 65 72 20 64 61 74 61  .of another data
8cb0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
8cc0: 0a 0a 3c 70 3e 54 68 69 73 20 6d 65 74 68 6f 64  ..<p>This method
8cd0: 20 6f 6e 6c 79 20 66 75 6e 63 74 69 6f 6e 73 20   only functions 
8ce0: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
8cf0: 70 69 6c 65 64 20 77 69 74 68 20 2d 44 53 51 4c  piled with -DSQL
8d00: 49 54 45 5f 45 4e 41 42 4c 45 5f 44 45 53 45 52  ITE_ENABLE_DESER
8d10: 49 41 4c 49 5a 45 0a 7d 0a 0a 23 23 23 23 23 23  IALIZE.}..######
8d20: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8d30: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8d40: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8d50: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8d60: 23 23 23 23 23 23 23 23 0a 4d 45 54 48 4f 44 20  ########.METHOD 
8d70: 64 65 73 65 72 69 61 6c 69 7a 65 20 7b 0a 3c 70  deserialize {.<p
8d80: 3e 54 68 65 20 22 64 65 73 65 72 69 61 6c 69 7a  >The "deserializ
8d90: 65 22 20 6d 65 74 68 6f 64 20 74 61 6b 65 73 20  e" method takes 
8da0: 61 20 54 43 4c 20 62 79 74 65 2d 61 72 72 61 79  a TCL byte-array
8db0: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 61   that contains a
8dc0: 6e 20 53 51 4c 69 74 65 0a 64 61 74 61 62 61 73  n SQLite.databas
8dd0: 65 20 66 69 6c 65 20 61 6e 64 20 61 64 64 73 20  e file and adds 
8de0: 69 74 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  it to the databa
8df0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
8e00: 54 68 65 20 73 79 6e 74 61 78 20 69 73 3a 0a 0a  The syntax is:..
8e10: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 69 3e  <blockquote>.<i>
8e20: 64 62 63 6d 64 3c 2f 69 3e 26 6e 62 73 70 3b 26  dbcmd</i>&nbsp;&
8e30: 6e 62 73 70 3b 3c 62 3e 64 65 73 65 72 69 61 6c  nbsp;<b>deserial
8e40: 69 7a 65 3c 2f 62 3e 26 6e 62 73 70 3b 26 6e 62  ize</b>&nbsp;&nb
8e50: 73 70 3b 3f 3c 69 3e 64 61 74 61 62 61 73 65 3c  sp;?<i>database<
8e60: 2f 69 3e 3f 26 6e 62 73 70 3b 26 6e 62 73 70 3b  /i>?&nbsp;&nbsp;
8e70: 3c 69 3e 76 61 6c 75 65 3c 2f 69 3e 0a 3c 2f 62  <i>value</i>.</b
8e80: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54  lockquote>..<p>T
8e90: 68 65 20 6f 70 74 69 6f 6e 20 3c 69 3e 64 61 74  he option <i>dat
8ea0: 61 62 61 73 65 3c 2f 69 3e 20 61 72 67 75 6d 65  abase</i> argume
8eb0: 6e 74 20 69 64 65 6e 74 69 66 69 65 73 20 77 68  nt identifies wh
8ec0: 69 63 68 20 61 74 74 61 63 68 65 64 20 64 61 74  ich attached dat
8ed0: 61 62 61 73 65 0a 73 68 6f 75 6c 64 20 72 65 63  abase.should rec
8ee0: 65 69 76 65 20 74 68 65 20 64 65 73 65 72 69 61  eive the deseria
8ef0: 6c 69 7a 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lization.  The d
8f00: 65 66 61 75 6c 74 20 69 73 20 22 6d 61 69 6e 22  efault is "main"
8f10: 2e 0a 0a 3c 70 3e 54 68 69 73 20 63 6f 6d 6d 61  ...<p>This comma
8f20: 6e 64 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  nd causes SQLite
8f30: 20 74 6f 20 64 69 73 63 6f 6e 6e 65 63 74 20 66   to disconnect f
8f40: 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
8f50: 20 64 61 74 61 62 61 73 65 20 61 6e 64 0a 72 65   database and.re
8f60: 61 74 74 61 63 68 20 74 6f 20 61 6e 20 69 6e 2d  attach to an in-
8f70: 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
8f80: 77 69 74 68 20 74 68 65 20 63 6f 6e 74 65 6e 74  with the content
8f90: 20 69 6e 20 3c 69 3e 76 61 6c 75 65 3c 2f 69 3e   in <i>value</i>
8fa0: 2e 20 20 49 66 20 3c 69 3e 76 61 6c 75 65 3c 2f  .  If <i>value</
8fb0: 69 3e 0a 69 73 20 6e 6f 74 20 61 20 62 79 74 65  i>.is not a byte
8fc0: 2d 61 72 72 61 79 20 63 6f 6e 74 61 69 6e 69 6e  -array containin
8fd0: 67 20 61 20 77 65 6c 6c 2d 64 65 66 69 6e 65 64  g a well-defined
8fe0: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
8ff0: 2c 20 74 68 65 6e 20 73 75 62 73 65 71 75 65 6e  , then subsequen
9000: 74 0a 63 6f 6d 6d 61 6e 64 73 20 77 69 6c 6c 20  t.commands will 
9010: 6c 69 6b 65 6c 79 20 72 65 74 75 72 6e 20 5b 53  likely return [S
9020: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65  QLITE_CORRUPT] e
9030: 72 72 6f 72 73 2e 0a 0a 3c 70 3e 54 68 69 73 20  rrors...<p>This 
9040: 6d 65 74 68 6f 64 20 6f 6e 6c 79 20 66 75 6e 63  method only func
9050: 74 69 6f 6e 73 20 69 66 20 53 51 4c 69 74 65 20  tions if SQLite 
9060: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
9070: 20 2d 44 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45   -DSQLITE_ENABLE
9080: 5f 44 45 53 45 52 49 41 4c 49 5a 45 0a 7d 0a 0a  _DESERIALIZE.}..
9090: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
90a0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
90b0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
90c0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
90d0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 4d  ##############.M
90e0: 45 54 48 4f 44 20 69 6e 74 65 72 72 75 70 74 20  ETHOD interrupt 
90f0: 7b 0a 3c 70 3e 54 68 65 20 22 69 6e 74 65 72 72  {.<p>The "interr
9100: 75 70 74 22 20 6d 65 74 68 6f 64 20 69 6e 76 6f  upt" method invo
9110: 6b 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  kes the [sqlite3
9120: 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 69 6e  _interrupt()] in
9130: 74 65 72 66 61 63 65 2c 20 63 61 75 73 69 6e 67  terface, causing
9140: 0a 61 6e 79 20 70 65 6e 64 69 6e 67 20 71 75 65  .any pending que
9150: 72 69 65 73 20 74 6f 20 68 61 6c 74 2e 0a 7d 0a  ries to halt..}.
9160: 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  .###############
9170: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9180: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9190: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
91a0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a  ###############.
91b0: 4d 45 54 48 4f 44 20 76 65 72 73 69 6f 6e 20 7b  METHOD version {
91c0: 0a 20 20 52 65 74 75 72 6e 20 74 68 65 20 63 75  .  Return the cu
91d0: 72 72 65 6e 74 20 6c 69 62 72 61 72 79 20 76 65  rrent library ve
91e0: 72 73 69 6f 6e 2e 20 46 6f 72 20 65 78 61 6d 70  rsion. For examp
91f0: 6c 65 2c 20 22 33 2e 32 33 2e 30 22 2e 0a 7d 0a  le, "3.23.0"..}.
9200: 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  .###############
9210: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9220: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9230: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9240: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a  ###############.
9250: 4d 45 54 48 4f 44 20 70 72 6f 66 69 6c 65 20 7b  METHOD profile {
9260: 0a 3c 70 3e 54 68 69 73 20 6d 65 74 68 6f 64 20  .<p>This method 
9270: 69 73 20 75 73 65 64 20 74 6f 20 70 72 6f 66 69  is used to profi
9280: 6c 65 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  le the execution
9290: 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
92a0: 74 73 20 72 75 6e 20 62 79 0a 20 20 20 74 68 65  ts run by.   the
92b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 54 68   application. Th
92c0: 65 20 73 79 6e 74 61 78 20 69 73 20 61 73 20 66  e syntax is as f
92d0: 6f 6c 6c 6f 77 73 3a 0a 3c 2f 70 3e 0a 0a 3c 62  ollows:.</p>..<b
92e0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 69 3e 64 62  lockquote>.<i>db
92f0: 63 6d 64 3c 2f 69 3e 26 6e 62 73 70 3b 26 6e 62  cmd</i>&nbsp;&nb
9300: 73 70 3b 3c 62 3e 70 72 6f 66 69 6c 65 3c 2f 62  sp;<b>profile</b
9310: 3e 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3f 3c 69  >&nbsp;&nbsp;?<i
9320: 3e 73 63 72 69 70 74 3c 2f 69 3e 3f 0a 3c 2f 62  >script</i>?.</b
9330: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 55  lockquote>..<p>U
9340: 6e 6c 65 73 73 20 3c 69 3e 73 63 72 69 70 74 3c  nless <i>script<
9350: 2f 69 3e 20 69 73 20 61 6e 20 65 6d 70 74 79 20  /i> is an empty 
9360: 73 74 72 69 6e 67 2c 20 74 68 69 73 20 6d 65 74  string, this met
9370: 68 6f 64 20 61 72 72 61 6e 67 65 73 20 66 6f 72  hod arranges for
9380: 20 74 68 65 0a 3c 69 3e 73 63 72 69 70 74 3c 2f   the.<i>script</
9390: 69 3e 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  i> to be evaluat
93a0: 65 64 20 61 66 74 65 72 20 74 68 65 20 65 78 65  ed after the exe
93b0: 63 75 74 69 6f 6e 20 6f 66 20 65 61 63 68 20 53  cution of each S
93c0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 54 77  QL statement..Tw
93d0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20  o arguments are 
93e0: 61 70 70 65 6e 64 65 64 20 74 6f 20 3c 69 3e 73  appended to <i>s
93f0: 63 72 69 70 74 3c 2f 69 3e 20 62 65 66 6f 72 65  cript</i> before
9400: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 3a 20   it is invoked: 
9410: 74 68 65 0a 74 65 78 74 20 6f 66 20 74 68 65 20  the.text of the 
9420: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 65 78  SQL statement ex
9430: 65 63 75 74 65 64 20 61 6e 64 20 74 68 65 20 74  ecuted and the t
9440: 69 6d 65 20 65 6c 61 70 73 65 64 20 77 68 69 6c  ime elapsed whil
9450: 65 20 65 78 65 63 75 74 69 6e 67 0a 74 68 65 20  e executing.the 
9460: 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 6e 61  statement, in na
9470: 6e 6f 73 65 63 6f 6e 64 73 2e 0a 3c 2f 70 3e 0a  noseconds..</p>.
9480: 3c 70 3e 41 20 64 61 74 61 62 61 73 65 20 68 61  <p>A database ha
9490: 6e 64 6c 65 20 6d 61 79 20 6f 6e 6c 79 20 68 61  ndle may only ha
94a0: 76 65 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 66  ve a single prof
94b0: 69 6c 65 20 73 63 72 69 70 74 20 72 65 67 69 73  ile script regis
94c0: 74 65 72 65 64 20 61 74 0a 61 6e 79 20 74 69 6d  tered at.any tim
94d0: 65 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 61  e. If there is a
94e0: 6c 72 65 61 64 79 20 61 20 73 63 72 69 70 74 20  lready a script 
94f0: 72 65 67 69 73 74 65 72 65 64 20 77 68 65 6e 20  registered when 
9500: 74 68 65 20 70 72 6f 66 69 6c 65 20 6d 65 74 68  the profile meth
9510: 6f 64 0a 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  od.is invoked, t
9520: 68 65 20 70 72 65 76 69 6f 75 73 20 70 72 6f 66  he previous prof
9530: 69 6c 65 20 73 63 72 69 70 74 20 69 73 20 72 65  ile script is re
9540: 70 6c 61 63 65 64 20 62 79 20 74 68 65 20 6e 65  placed by the ne
9550: 77 20 6f 6e 65 2e 20 49 66 20 74 68 65 20 0a 3c  w one. If the .<
9560: 69 3e 73 63 72 69 70 74 3c 2f 69 3e 20 61 72 67  i>script</i> arg
9570: 75 6d 65 6e 74 20 69 73 20 61 6e 20 65 6d 70 74  ument is an empt
9580: 79 20 73 74 72 69 6e 67 2c 20 61 6e 79 20 70 72  y string, any pr
9590: 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
95a0: 72 65 64 20 0a 70 72 6f 66 69 6c 65 20 63 61 6c  red .profile cal
95b0: 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 65  lback is cancele
95c0: 64 20 62 75 74 20 6e 6f 20 6e 65 77 20 70 72 6f  d but no new pro
95d0: 66 69 6c 65 20 73 63 72 69 70 74 20 69 73 20 72  file script is r
95e0: 65 67 69 73 74 65 72 65 64 2e 0a 3c 2f 70 3e 0a  egistered..</p>.
95f0: 7d 0a 0a 23 23 23 23 23 23 23 23 23 23 23 23 23  }..#############
9600: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9610: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9620: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9630: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9640: 23 0a 4d 45 54 48 4f 44 20 75 6e 6c 6f 63 6b 5f  #.METHOD unlock_
9650: 6e 6f 74 69 66 79 20 7b 0a 3c 70 3e 54 68 65 20  notify {.<p>The 
9660: 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 20 6d 65  unlock_notify me
9670: 74 68 6f 64 20 69 73 20 75 73 65 64 20 61 63 63  thod is used acc
9680: 65 73 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ess the [sqlite3
9690: 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29  _unlock_notify()
96a0: 5d 0a 20 20 20 69 6e 74 65 72 66 61 63 65 20 74  ].   interface t
96b0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  o the SQLite cor
96c0: 65 20 6c 69 62 72 61 72 79 20 66 6f 72 20 74 65  e library for te
96d0: 73 74 69 6e 67 20 70 75 72 70 6f 73 65 73 2e 20  sting purposes. 
96e0: 20 54 68 65 20 75 73 65 20 6f 66 0a 20 20 20 74   The use of.   t
96f0: 68 69 73 20 6d 65 74 68 6f 64 20 62 79 20 61 70  his method by ap
9700: 70 6c 69 63 61 74 69 6f 6e 73 20 69 73 20 64 69  plications is di
9710: 73 63 6f 75 72 61 67 65 64 2e 0a 3c 2f 70 3e 0a  scouraged..</p>.
9720: 7d 0a 0a 0a 0a 3c 2f 74 63 6c 3e 0a              }....</tcl>.