/ Hex Artifact Content
Login

Artifact 5c1cb163f4d2a54e2d0e22dcc399dd71245c8b89:


0000: 73 65 74 20 72 63 73 69 64 20 7b 24 49 64 3a 20  set rcsid {$Id: 
0010: 63 61 70 69 33 2e 74 63 6c 2c 76 20 31 2e 36 20  capi3.tcl,v 1.6 
0020: 32 30 30 34 2f 30 36 2f 33 30 20 31 33 3a 32 38  2004/06/30 13:28
0030: 3a 33 33 20 64 61 6e 69 65 6c 6b 31 39 37 37 20  :33 danielk1977 
0040: 45 78 70 20 24 7d 0a 73 6f 75 72 63 65 20 63 6f  Exp $}.source co
0050: 6d 6d 6f 6e 2e 74 63 6c 0a 68 65 61 64 65 72 20  mmon.tcl.header 
0060: 7b 43 2f 43 2b 2b 20 49 6e 74 65 72 66 61 63 65  {C/C++ Interface
0070: 20 46 6f 72 20 53 51 4c 69 74 65 20 56 65 72 73   For SQLite Vers
0080: 69 6f 6e 20 33 7d 0a 70 75 74 73 20 7b 0a 3c 68  ion 3}.puts {.<h
0090: 32 3e 43 2f 43 2b 2b 20 49 6e 74 65 72 66 61 63  2>C/C++ Interfac
00a0: 65 20 46 6f 72 20 53 51 4c 69 74 65 20 56 65 72  e For SQLite Ver
00b0: 73 69 6f 6e 20 33 3c 2f 68 32 3e 0a 0a 3c 68 33  sion 3</h2>..<h3
00c0: 3e 31 2e 30 20 4f 76 65 72 76 69 65 77 3c 2f 68  >1.0 Overview</h
00d0: 33 3e 0a 0a 3c 70 3e 0a 53 51 4c 69 74 65 20 76  3>..<p>.SQLite v
00e0: 65 72 73 69 6f 6e 20 33 2e 30 20 69 73 20 61 20  ersion 3.0 is a 
00f0: 6e 65 77 20 76 65 72 73 69 6f 6e 20 6f 66 20 53  new version of S
0100: 51 4c 69 74 65 2c 20 64 65 72 69 76 65 64 20 66  QLite, derived f
0110: 72 6f 6d 0a 74 68 65 20 53 51 4c 69 74 65 20 32  rom.the SQLite 2
0120: 2e 38 2e 31 33 20 63 6f 64 65 20 62 61 73 65 2c  .8.13 code base,
0130: 20 62 75 74 20 77 69 74 68 20 61 6e 20 69 6e 63   but with an inc
0140: 6f 6d 70 61 74 69 62 6c 65 20 66 69 6c 65 20 66  ompatible file f
0150: 6f 72 6d 61 74 0a 61 6e 64 20 41 50 49 2e 0a 53  ormat.and API..S
0160: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
0170: 30 20 77 61 73 20 63 72 65 61 74 65 64 20 74 6f  0 was created to
0180: 20 61 6e 73 77 65 72 20 64 65 6d 61 6e 64 20 66   answer demand f
0190: 6f 72 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  or the following
01a0: 20 66 65 61 74 75 72 65 73 3a 0a 3c 2f 70 3e 0a   features:.</p>.
01b0: 0a 3c 75 6c 3e 0a 3c 6c 69 3e 53 75 70 70 6f 72  .<ul>.<li>Suppor
01c0: 74 20 66 6f 72 20 55 54 46 2d 31 36 2e 3c 2f 6c  t for UTF-16.</l
01d0: 69 3e 0a 3c 6c 69 3e 55 73 65 72 2d 64 65 66 69  i>.<li>User-defi
01e0: 6e 61 62 6c 65 20 74 65 78 74 20 63 6f 6c 6c 61  nable text colla
01f0: 74 69 6e 67 20 73 65 71 75 65 6e 63 65 73 2e 3c  ting sequences.<
0200: 2f 6c 69 3e 0a 3c 6c 69 3e 54 68 65 20 61 62 69  /li>.<li>The abi
0210: 6c 69 74 79 20 74 6f 20 73 74 6f 72 65 20 42 4c  lity to store BL
0220: 4f 42 73 20 69 6e 20 69 6e 64 65 78 65 64 20 63  OBs in indexed c
0230: 6f 6c 75 6d 6e 73 2e 3c 2f 6c 69 3e 0a 3c 2f 75  olumns.</li>.</u
0240: 6c 3e 0a 0a 3c 70 3e 0a 49 74 20 77 61 73 20 6e  l>..<p>.It was n
0250: 65 63 65 73 73 61 72 79 20 74 6f 20 6d 6f 76 65  ecessary to move
0260: 20 74 6f 20 76 65 72 73 69 6f 6e 20 33 2e 30 20   to version 3.0 
0270: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  to implement the
0280: 73 65 20 66 65 61 74 75 72 65 73 20 62 65 63 61  se features beca
0290: 75 73 65 0a 65 61 63 68 20 72 65 71 75 69 72 65  use.each require
02a0: 73 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 63  s incompatible c
02b0: 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 64 61  hanges to the da
02c0: 74 61 62 61 73 65 20 66 69 6c 65 20 66 6f 72 6d  tabase file form
02d0: 61 74 2e 20 20 4f 74 68 65 72 0a 69 6e 63 6f 6d  at.  Other.incom
02e0: 70 61 74 69 62 6c 65 20 63 68 61 6e 67 65 73 2c  patible changes,
02f0: 20 73 75 63 68 20 61 73 20 61 20 63 6c 65 61 6e   such as a clean
0300: 75 70 20 6f 66 20 74 68 65 20 41 50 49 2c 20 77  up of the API, w
0310: 65 72 65 20 69 6e 74 72 6f 64 75 63 65 64 20 61  ere introduced a
0320: 74 20 74 68 65 0a 73 61 6d 65 20 74 69 6d 65 20  t the.same time 
0330: 75 6e 64 65 72 20 74 68 65 20 74 68 65 6f 72 79  under the theory
0340: 20 74 68 61 74 20 69 74 20 69 73 20 62 65 73 74   that it is best
0350: 20 74 6f 20 67 65 74 20 79 6f 75 72 20 69 6e 63   to get your inc
0360: 6f 6d 70 61 74 69 62 6c 65 20 63 68 61 6e 67 65  ompatible change
0370: 73 0a 6f 75 74 20 6f 66 20 74 68 65 20 77 61 79  s.out of the way
0380: 20 61 6c 6c 20 61 74 20 6f 6e 63 65 2e 20 20 0a   all at once.  .
0390: 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 41 50  </p>..<p>.The AP
03a0: 49 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 2e  I for version 3.
03b0: 30 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  0 is similar to 
03c0: 74 68 65 20 76 65 72 73 69 6f 6e 20 32 2e 58 20  the version 2.X 
03d0: 41 50 49 2c 0a 62 75 74 20 77 69 74 68 20 73 6f  API,.but with so
03e0: 6d 65 20 69 6d 70 6f 72 74 61 6e 74 20 63 68 61  me important cha
03f0: 6e 67 65 73 2e 20 20 4d 6f 73 74 20 6e 6f 74 69  nges.  Most noti
0400: 63 65 61 62 6c 79 2c 20 74 68 65 20 22 3c 74 74  ceably, the "<tt
0410: 3e 73 71 6c 69 74 65 5f 3c 2f 74 74 3e 22 0a 70  >sqlite_</tt>".p
0420: 72 65 66 69 78 20 74 68 61 74 20 6f 63 63 75 72  refix that occur
0430: 73 20 6f 6e 20 74 68 65 20 62 65 67 69 6e 6e 69  s on the beginni
0440: 6e 67 20 6f 66 20 61 6c 6c 20 41 50 49 20 66 75  ng of all API fu
0450: 6e 63 74 69 6f 6e 73 20 61 6e 64 20 64 61 74 61  nctions and data
0460: 0a 73 74 72 75 63 74 75 72 65 73 20 61 72 65 20  .structures are 
0470: 63 68 61 6e 67 65 64 20 74 6f 20 22 3c 74 74 3e  changed to "<tt>
0480: 73 71 6c 69 74 65 33 5f 3c 2f 74 74 3e 22 2e 20  sqlite3_</tt>". 
0490: 20 0a 54 68 69 73 20 61 76 6f 69 64 73 20 63 6f   .This avoids co
04a0: 6e 66 75 73 69 6f 6e 20 62 65 74 77 65 65 6e 20  nfusion between 
04b0: 74 68 65 20 74 77 6f 20 41 50 49 73 20 61 6e 64  the two APIs and
04c0: 20 61 6c 6c 6f 77 73 20 6c 69 6e 6b 69 6e 67 20   allows linking 
04d0: 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 53 51 4c  against both.SQL
04e0: 69 74 65 20 32 2e 58 20 61 6e 64 20 53 51 4c 69  ite 2.X and SQLi
04f0: 74 65 20 33 2e 30 20 61 74 20 74 68 65 20 73 61  te 3.0 at the sa
0500: 6d 65 20 74 69 6d 65 2e 0a 3c 2f 70 3e 0a 0a 3c  me time..</p>..<
0510: 70 3e 0a 54 68 65 72 65 20 69 73 20 6e 6f 20 61  p>.There is no a
0520: 67 72 65 65 6d 65 6e 74 20 6f 6e 20 77 68 61 74  greement on what
0530: 20 74 68 65 20 43 20 64 61 74 61 74 79 70 65 20   the C datatype 
0540: 66 6f 72 20 61 20 55 54 46 2d 31 36 0a 73 74 72  for a UTF-16.str
0550: 69 6e 67 20 73 68 6f 75 6c 64 20 62 65 2e 20 20  ing should be.  
0560: 54 68 65 72 65 66 6f 72 65 2c 20 53 51 4c 69 74  Therefore, SQLit
0570: 65 20 75 73 65 73 20 61 20 67 65 6e 65 72 69 63  e uses a generic
0580: 20 74 79 70 65 20 6f 66 20 76 6f 69 64 2a 0a 74   type of void*.t
0590: 6f 20 72 65 66 65 72 20 74 6f 20 55 54 46 2d 31  o refer to UTF-1
05a0: 36 20 73 74 72 69 6e 67 73 2e 20 20 43 6c 69 65  6 strings.  Clie
05b0: 6e 74 20 73 6f 66 74 77 61 72 65 20 63 61 6e 20  nt software can 
05c0: 63 61 73 74 20 74 68 65 20 76 6f 69 64 2a 20 0a  cast the void* .
05d0: 74 6f 20 77 68 61 74 65 76 65 72 20 64 61 74 61  to whatever data
05e0: 74 79 70 65 20 69 73 20 61 70 70 72 6f 70 72 69  type is appropri
05f0: 61 74 65 20 66 6f 72 20 74 68 65 69 72 20 73 79  ate for their sy
0600: 73 74 65 6d 2e 0a 3c 2f 70 3e 0a 0a 3c 68 33 3e  stem..</p>..<h3>
0610: 32 2e 30 20 43 2f 43 2b 2b 20 49 6e 74 65 72 66  2.0 C/C++ Interf
0620: 61 63 65 3c 2f 68 33 3e 0a 0a 3c 70 3e 0a 54 68  ace</h3>..<p>.Th
0630: 65 20 41 50 49 20 66 6f 72 20 53 51 4c 69 74 65  e API for SQLite
0640: 20 33 2e 30 20 69 6e 63 6c 75 64 65 73 20 38 33   3.0 includes 83
0650: 20 73 65 70 61 72 61 74 65 20 66 75 6e 63 74 69   separate functi
0660: 6f 6e 73 20 69 6e 20 61 64 64 69 74 69 6f 6e 0a  ons in addition.
0670: 74 6f 20 73 65 76 65 72 61 6c 20 64 61 74 61 20  to several data 
0680: 73 74 72 75 63 74 75 72 65 73 20 61 6e 64 20 23  structures and #
0690: 64 65 66 69 6e 65 73 2e 20 20 28 41 20 63 6f 6d  defines.  (A com
06a0: 70 6c 65 74 65 0a 3c 61 20 68 72 65 66 3d 22 63  plete.<a href="c
06b0: 61 70 69 33 72 65 66 2e 68 74 6d 6c 22 3e 41 50  api3ref.html">AP
06c0: 49 20 72 65 66 65 72 65 6e 63 65 3c 2f 61 3e 20  I reference</a> 
06d0: 69 73 20 70 72 6f 76 69 64 65 64 20 61 73 20 61  is provided as a
06e0: 20 73 65 70 61 72 61 74 65 20 64 6f 63 75 6d 65   separate docume
06f0: 6e 74 2e 29 0a 46 6f 72 74 75 6e 61 74 65 6c 79  nt.).Fortunately
0700: 2c 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  , the interface 
0710: 69 73 20 6e 6f 74 20 6e 65 61 72 6c 79 20 61 73  is not nearly as
0720: 20 63 6f 6d 70 6c 65 78 20 61 73 20 69 74 73 20   complex as its 
0730: 73 69 7a 65 20 69 6d 70 6c 69 65 73 2e 0a 53 69  size implies..Si
0740: 6d 70 6c 65 20 70 72 6f 67 72 61 6d 73 20 63 61  mple programs ca
0750: 6e 20 73 74 69 6c 6c 20 6d 61 6b 65 20 64 6f 20  n still make do 
0760: 77 69 74 68 20 6f 6e 6c 79 20 33 20 66 75 6e 63  with only 3 func
0770: 74 69 6f 6e 73 3a 0a 3c 61 20 68 72 65 66 3d 22  tions:.<a href="
0780: 63 61 70 69 33 72 65 66 2e 68 74 6d 6c 23 73 71  capi3ref.html#sq
0790: 6c 69 74 65 33 5f 6f 70 65 6e 22 3e 73 71 6c 69  lite3_open">sqli
07a0: 74 65 33 5f 6f 70 65 6e 28 29 3c 2f 61 3e 2c 0a  te3_open()</a>,.
07b0: 3c 61 20 68 72 65 66 3d 22 63 61 70 69 33 72 65  <a href="capi3re
07c0: 66 2e 68 74 6d 6c 23 73 71 6c 69 74 65 33 5f 65  f.html#sqlite3_e
07d0: 78 65 63 22 3e 73 71 6c 69 74 65 33 5f 65 78 65  xec">sqlite3_exe
07e0: 63 28 29 3c 2f 61 3e 2c 20 61 6e 64 0a 3c 61 20  c()</a>, and.<a 
07f0: 68 72 65 66 3d 22 63 61 70 69 33 72 65 66 2e 68  href="capi3ref.h
0800: 74 6d 6c 23 73 71 6c 69 74 65 33 5f 63 6c 6f 73  tml#sqlite3_clos
0810: 65 22 3e 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  e">sqlite3_close
0820: 28 29 3c 2f 61 3e 2e 0a 4d 6f 72 65 20 63 6f 6e  ()</a>..More con
0830: 74 72 6f 6c 20 6f 76 65 72 20 74 68 65 20 65 78  trol over the ex
0840: 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 64  ecution of the d
0850: 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 69  atabase engine i
0860: 73 20 70 72 6f 76 69 64 65 64 0a 75 73 69 6e 67  s provided.using
0870: 0a 3c 61 20 68 72 65 66 3d 22 63 61 70 69 33 72  .<a href="capi3r
0880: 65 66 2e 68 74 6d 6c 23 73 71 6c 69 74 65 33 5f  ef.html#sqlite3_
0890: 70 72 65 70 61 72 65 22 3e 73 71 6c 69 74 65 33  prepare">sqlite3
08a0: 5f 70 72 65 70 61 72 65 28 29 3c 2f 61 3e 0a 74  _prepare()</a>.t
08b0: 6f 20 63 6f 6d 70 69 6c 65 20 61 6e 20 53 51 4c  o compile an SQL
08c0: 69 74 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  ite statement in
08d0: 74 6f 20 62 79 74 65 20 63 6f 64 65 20 61 6e 64  to byte code and
08e0: 0a 3c 61 20 68 72 65 66 3d 22 63 61 70 69 33 72  .<a href="capi3r
08f0: 65 66 2e 68 74 6d 6c 23 73 71 6c 69 74 65 33 5f  ef.html#sqlite3_
0900: 70 72 65 70 61 72 65 22 3e 73 71 6c 69 74 65 33  prepare">sqlite3
0910: 5f 73 74 65 70 28 29 3c 2f 61 3e 0a 74 6f 20 65  _step()</a>.to e
0920: 78 65 63 75 74 65 20 74 68 61 74 20 62 79 74 65  xecute that byte
0930: 63 6f 64 65 2e 0a 41 20 66 61 6d 69 6c 79 20 6f  code..A family o
0940: 66 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  f routines with 
0950: 6e 61 6d 65 73 20 62 65 67 69 6e 6e 69 6e 67 20  names beginning 
0960: 77 69 74 68 20 0a 3c 61 20 68 72 65 66 3d 22 63  with .<a href="c
0970: 61 70 69 33 72 65 66 2e 68 74 6d 6c 23 73 71 6c  api3ref.html#sql
0980: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
0990: 22 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  ">sqlite3_column
09a0: 5f 3c 2f 61 3e 0a 69 73 20 75 73 65 64 20 74 6f  _</a>.is used to
09b0: 20 65 78 74 72 61 63 74 20 69 6e 66 6f 72 6d 61   extract informa
09c0: 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 72  tion about the r
09d0: 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 71  esult set of a q
09e0: 75 65 72 79 2e 0a 4d 61 6e 79 20 69 6e 74 65 72  uery..Many inter
09f0: 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  face functions c
0a00: 6f 6d 65 20 69 6e 20 70 61 69 72 73 2c 20 77 69  ome in pairs, wi
0a10: 74 68 20 62 6f 74 68 20 61 20 55 54 46 2d 38 20  th both a UTF-8 
0a20: 61 6e 64 0a 55 54 46 2d 31 36 20 76 65 72 73 69  and.UTF-16 versi
0a30: 6f 6e 2e 20 20 41 6e 64 20 74 68 65 72 65 20 69  on.  And there i
0a40: 73 20 61 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  s a collection o
0a50: 66 20 72 6f 75 74 69 6e 65 73 0a 75 73 65 64 20  f routines.used 
0a60: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 75 73 65  to implement use
0a70: 72 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  r-defined SQL fu
0a80: 6e 63 74 69 6f 6e 73 20 61 6e 64 20 75 73 65 72  nctions and user
0a90: 2d 64 65 66 69 6e 65 64 0a 74 65 78 74 20 63 6f  -defined.text co
0aa0: 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65  llating sequence
0ab0: 73 2e 0a 3c 2f 70 3e 0a 0a 0a 3c 68 34 3e 32 2e  s..</p>...<h4>2.
0ac0: 31 20 4f 70 65 6e 69 6e 67 20 61 6e 64 20 63 6c  1 Opening and cl
0ad0: 6f 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65  osing a database
0ae0: 3c 2f 68 34 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  </h4>..<blockquo
0af0: 74 65 3e 3c 70 72 65 3e 0a 20 20 20 74 79 70 65  te><pre>.   type
0b00: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
0b10: 65 33 20 73 71 6c 69 74 65 33 3b 0a 20 20 20 69  e3 sqlite3;.   i
0b20: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
0b30: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
0b40: 69 74 65 33 2a 2a 29 3b 0a 20 20 20 69 6e 74 20  ite3**);.   int 
0b50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 63  sqlite3_open16(c
0b60: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69  onst void*, sqli
0b70: 74 65 33 2a 2a 29 3b 0a 20 20 20 69 6e 74 20 73  te3**);.   int s
0b80: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c  qlite3_close(sql
0b90: 69 74 65 33 2a 29 3b 0a 20 20 20 63 6f 6e 73 74  ite3*);.   const
0ba0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
0bb0: 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
0bc0: 0a 20 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .   const void *
0bd0: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
0be0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 20 20 20 69  (sqlite3*);.   i
0bf0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
0c00: 64 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 3c 2f  de(sqlite3*);.</
0c10: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
0c20: 3e 0a 0a 3c 70 3e 0a 54 68 65 20 73 71 6c 69 74  >..<p>.The sqlit
0c30: 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
0c40: 65 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  e returns an int
0c50: 65 67 65 72 20 65 72 72 6f 72 20 63 6f 64 65 20  eger error code 
0c60: 72 61 74 68 65 72 20 74 68 61 6e 0a 61 20 70 6f  rather than.a po
0c70: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  inter to the sql
0c80: 69 74 65 33 20 73 74 72 75 63 74 75 72 65 20 61  ite3 structure a
0c90: 73 20 74 68 65 20 76 65 72 73 69 6f 6e 20 32 20  s the version 2 
0ca0: 69 6e 74 65 72 66 61 63 65 20 64 69 64 2e 0a 54  interface did..T
0cb0: 68 65 20 64 69 66 66 65 72 65 6e 63 65 20 62 65  he difference be
0cc0: 74 77 65 65 6e 20 73 71 6c 69 74 65 33 5f 6f 70  tween sqlite3_op
0cd0: 65 6e 28 29 0a 61 6e 64 20 73 71 6c 69 74 65 33  en().and sqlite3
0ce0: 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 74 68 61  _open16() is tha
0cf0: 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
0d00: 28 29 20 74 61 6b 65 73 20 55 54 46 2d 31 36 20  () takes UTF-16 
0d10: 28 69 6e 20 68 6f 73 74 20 6e 61 74 69 76 65 0a  (in host native.
0d20: 62 79 74 65 20 6f 72 64 65 72 29 20 66 6f 72 20  byte order) for 
0d30: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
0d40: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 20  database file.  
0d50: 49 66 20 61 20 6e 65 77 20 64 61 74 61 62 61 73  If a new databas
0d60: 65 20 66 69 6c 65 0a 6e 65 65 64 73 20 74 6f 20  e file.needs to 
0d70: 62 65 20 63 72 65 61 74 65 64 2c 20 74 68 65 6e  be created, then
0d80: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
0d90: 29 20 73 65 74 73 20 74 68 65 20 69 6e 74 65 72  ) sets the inter
0da0: 6e 61 6c 20 74 65 78 74 0a 72 65 70 72 65 73 65  nal text.represe
0db0: 6e 74 61 74 69 6f 6e 20 74 6f 20 55 54 46 2d 31  ntation to UTF-1
0dc0: 36 20 77 68 65 72 65 61 73 20 73 71 6c 69 74 65  6 whereas sqlite
0dd0: 33 5f 6f 70 65 6e 28 29 20 73 65 74 73 20 74 68  3_open() sets th
0de0: 65 20 74 65 78 74 0a 72 65 70 72 65 73 65 6e 74  e text.represent
0df0: 61 74 69 6f 6e 20 74 6f 20 55 54 46 2d 38 2e 0a  ation to UTF-8..
0e00: 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 6f 70  </p>..<p>.The op
0e10: 65 6e 69 6e 67 20 61 6e 64 2f 6f 72 20 63 72 65  ening and/or cre
0e20: 61 74 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74  ating of the dat
0e30: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 64 65  abase file is de
0e40: 66 65 72 72 65 64 20 75 6e 74 69 6c 20 74 68 65  ferred until the
0e50: 0a 66 69 6c 65 20 69 73 20 61 63 74 75 61 6c 6c  .file is actuall
0e60: 79 20 6e 65 65 64 65 64 2e 20 20 54 68 69 73 20  y needed.  This 
0e70: 61 6c 6c 6f 77 73 20 6f 70 74 69 6f 6e 73 20 61  allows options a
0e80: 6e 64 20 70 61 72 61 6d 65 74 65 72 73 2c 20 73  nd parameters, s
0e90: 75 63 68 0a 61 73 20 74 68 65 20 6e 61 74 69 76  uch.as the nativ
0ea0: 65 20 74 65 78 74 20 72 65 70 72 65 73 65 6e 74  e text represent
0eb0: 61 74 69 6f 6e 20 61 6e 64 20 64 65 66 61 75 6c  ation and defaul
0ec0: 74 20 70 61 67 65 20 73 69 7a 65 2c 20 74 6f 20  t page size, to 
0ed0: 62 65 0a 73 65 74 20 75 73 69 6e 67 20 50 52 41  be.set using PRA
0ee0: 47 4d 41 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  GMA statements..
0ef0: 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 73 71  </p>..<p>.The sq
0f00: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
0f10: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
0f20: 61 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 6f  a result code fo
0f30: 72 20 74 68 65 20 6d 6f 73 74 0a 72 65 63 65 6e  r the most.recen
0f40: 74 20 6d 61 6a 6f 72 20 41 50 49 20 63 61 6c 6c  t major API call
0f50: 2e 20 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  .  sqlite3_errms
0f60: 67 28 29 20 72 65 74 75 72 6e 73 20 61 6e 20 45  g() returns an E
0f70: 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
0f80: 74 65 78 74 20 65 72 72 6f 72 20 6d 65 73 73 61  text error messa
0f90: 67 65 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  ge for the most 
0fa0: 72 65 63 65 6e 74 20 65 72 72 6f 72 2e 20 20 54  recent error.  T
0fb0: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
0fc0: 20 69 73 0a 72 65 70 72 65 73 65 6e 74 65 64 20   is.represented 
0fd0: 69 6e 20 55 54 46 2d 38 20 61 6e 64 20 77 69 6c  in UTF-8 and wil
0fe0: 6c 20 62 65 20 65 70 68 65 6d 65 72 61 6c 20 2d  l be ephemeral -
0ff0: 20 69 74 20 63 6f 75 6c 64 20 64 69 73 61 70 70   it could disapp
1000: 65 61 72 20 6f 6e 0a 74 68 65 20 6e 65 78 74 20  ear on.the next 
1010: 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69  call to any SQLi
1020: 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e  te API function.
1030: 20 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67    sqlite3_errmsg
1040: 31 36 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 0a  16() works like.
1050: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1060: 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
1070: 72 65 74 75 72 6e 73 20 74 68 65 20 65 72 72 6f  returns the erro
1080: 72 20 6d 65 73 73 61 67 65 20 72 65 70 72 65 73  r message repres
1090: 65 6e 74 65 64 0a 61 73 20 55 54 46 2d 31 36 20  ented.as UTF-16 
10a0: 69 6e 20 68 6f 73 74 20 6e 61 74 69 76 65 20 62  in host native b
10b0: 79 74 65 20 6f 72 64 65 72 2e 0a 3c 2f 70 3e 0a  yte order..</p>.
10c0: 0a 3c 70 3e 0a 54 68 65 20 65 72 72 6f 72 20 63  .<p>.The error c
10d0: 6f 64 65 73 20 66 6f 72 20 53 51 4c 69 74 65 20  odes for SQLite 
10e0: 76 65 72 73 69 6f 6e 20 33 20 61 72 65 20 75 6e  version 3 are un
10f0: 63 68 61 6e 67 65 64 20 66 72 6f 6d 20 76 65 72  changed from ver
1100: 73 69 6f 6e 20 32 2e 0a 54 68 65 79 20 61 72 65  sion 2..They are
1110: 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 3c 2f 70   as follows:.</p
1120: 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  >..<blockquote><
1130: 70 72 65 3e 0a 23 64 65 66 69 6e 65 20 53 51 4c  pre>.#define SQL
1140: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
1150: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
1160: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 23 64 65  ul result */.#de
1170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
1180: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
1190: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
11a0: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
11b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11c0: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
11d0: 20 2f 2a 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20   /* An internal 
11e0: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
11f0: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
1200: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
1210: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
1220: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
1230: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
1240: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
1250: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
1260: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
1270: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
1280: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1290: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
12a0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
12b0: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
12c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
12d0: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
12e0: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
12f0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
1300: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
1310: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
1320: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
1330: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
1340: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1350: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
1360: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
1370: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
1380: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
1390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
13a0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
13b0: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
13c0: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
13d0: 5f 69 6e 74 65 72 72 75 70 74 28 29 20 2a 2f 0a  _interrupt() */.
13e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
13f0: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
1400: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
1410: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
1420: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
1430: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
1440: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
1450: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
1460: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
1470: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
1480: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
1490: 20 31 32 20 20 20 2f 2a 20 28 49 6e 74 65 72 6e   12   /* (Intern
14a0: 61 6c 20 4f 6e 6c 79 29 20 54 61 62 6c 65 20 6f  al Only) Table o
14b0: 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75  r record not fou
14c0: 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nd */.#define SQ
14d0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
14e0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
14f0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
1500: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
1510: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
1520: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
1530: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
1540: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
1550: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
1560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
1570: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
1580: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
1590: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
15a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
15b0: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
15c0: 2f 2a 20 28 49 6e 74 65 72 6e 61 6c 20 4f 6e 6c  /* (Internal Onl
15d0: 79 29 20 44 61 74 61 62 61 73 65 20 74 61 62 6c  y) Database tabl
15e0: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
15f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
1600: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
1610: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
1620: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
1630: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
1640: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
1650: 2f 2a 20 54 6f 6f 20 6d 75 63 68 20 64 61 74 61  /* Too much data
1660: 20 66 6f 72 20 6f 6e 65 20 72 6f 77 20 6f 66 20   for one row of 
1670: 61 20 74 61 62 6c 65 20 2a 2f 0a 23 64 65 66 69  a table */.#defi
1680: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
1690: 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62  AINT  19   /* Ab
16a0: 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 74 72  ort due to contr
16b0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
16c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16d0: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
16e0: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
16f0: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
1700: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
1710: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
1720: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
1730: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
1740: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
1750: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
1760: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
1770: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
1780: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
1790: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
17a0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
17b0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
17c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17d0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
17e0: 20 20 2f 2a 20 73 71 6c 69 74 65 5f 73 74 65 70    /* sqlite_step
17f0: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72  () has another r
1800: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66  ow ready */.#def
1810: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20  ine SQLITE_DONE 
1820: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73         101  /* s
1830: 71 6c 69 74 65 5f 73 74 65 70 28 29 20 68 61 73  qlite_step() has
1840: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
1850: 69 6e 67 20 2a 2f 0a 3c 2f 70 72 65 3e 3c 2f 62  ing */.</pre></b
1860: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 68 34 3e  lockquote>..<h4>
1870: 32 2e 32 20 45 78 65 63 75 74 69 6e 67 20 53 51  2.2 Executing SQ
1880: 4c 20 73 74 61 74 65 6d 65 6e 74 73 3c 2f 68 34  L statements</h4
1890: 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  >..<blockquote><
18a0: 70 72 65 3e 0a 20 20 20 74 79 70 65 64 65 66 20  pre>.   typedef 
18b0: 69 6e 74 20 28 2a 73 71 6c 69 74 65 5f 63 61 6c  int (*sqlite_cal
18c0: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
18d0: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29  ,char**, char**)
18e0: 3b 0a 20 20 20 69 6e 74 20 73 71 6c 69 74 65 33  ;.   int sqlite3
18f0: 5f 65 78 65 63 28 73 71 6c 69 74 65 33 2a 2c 20  _exec(sqlite3*, 
1900: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c  const char *sql,
1910: 20 73 71 6c 69 74 65 5f 63 61 6c 6c 62 61 63 6b   sqlite_callback
1920: 2c 20 76 6f 69 64 2a 2c 20 63 68 61 72 2a 2a 29  , void*, char**)
1930: 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  ;.</pre></blockq
1940: 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65 20 73  uote>..<p>.The s
1950: 71 6c 69 74 65 33 5f 65 78 65 63 20 66 75 6e 63  qlite3_exec func
1960: 74 69 6f 6e 20 77 6f 72 6b 73 20 6d 75 63 68 20  tion works much 
1970: 61 73 20 69 74 20 64 69 64 20 69 6e 20 53 51 4c  as it did in SQL
1980: 69 74 65 20 76 65 72 73 69 6f 6e 20 32 2e 0a 5a  ite version 2..Z
1990: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 20  ero or more SQL 
19a0: 73 74 61 74 65 6d 65 6e 74 73 20 73 70 65 63 69  statements speci
19b0: 66 69 65 64 20 69 6e 20 74 68 65 20 73 65 63 6f  fied in the seco
19c0: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
19d0: 20 63 6f 6d 70 69 6c 65 64 0a 61 6e 64 20 65 78   compiled.and ex
19e0: 65 63 75 74 65 64 2e 20 20 51 75 65 72 79 20 72  ecuted.  Query r
19f0: 65 73 75 6c 74 73 20 61 72 65 20 72 65 74 75 72  esults are retur
1a00: 6e 65 64 20 74 6f 20 61 20 63 61 6c 6c 62 61 63  ned to a callbac
1a10: 6b 20 72 6f 75 74 69 6e 65 2e 0a 53 65 65 20 74  k routine..See t
1a20: 68 65 20 3c 61 20 68 72 65 66 3d 22 63 61 70 69  he <a href="capi
1a30: 33 72 65 66 2e 68 74 6d 6c 23 73 71 6c 69 74 65  3ref.html#sqlite
1a40: 33 5f 65 78 65 63 22 3e 41 50 49 20 72 65 66 65  3_exec">API refe
1a50: 72 65 6e 63 65 3c 2f 61 3e 20 66 6f 72 20 61 64  rence</a> for ad
1a60: 64 69 74 69 6f 6e 61 6c 0a 69 6e 66 6f 72 6d 61  ditional.informa
1a70: 74 69 6f 6e 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a  tion..</p>..<p>.
1a80: 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
1a90: 6e 20 33 2c 20 74 68 65 20 73 71 6c 69 74 65 33  n 3, the sqlite3
1aa0: 5f 65 78 65 63 20 72 6f 75 74 69 6e 65 20 69 73  _exec routine is
1ab0: 20 6a 75 73 74 20 61 20 77 72 61 70 70 65 72 20   just a wrapper 
1ac0: 61 72 6f 75 6e 64 0a 63 61 6c 6c 73 20 74 6f 20  around.calls to 
1ad0: 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
1ae0: 74 65 6d 65 6e 74 20 69 6e 74 65 72 66 61 63 65  tement interface
1af0: 2e 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  ..</p>..<blockqu
1b00: 6f 74 65 3e 3c 70 72 65 3e 0a 20 20 20 74 79 70  ote><pre>.   typ
1b10: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
1b20: 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
1b30: 5f 73 74 6d 74 3b 0a 20 20 20 69 6e 74 20 73 71  _stmt;.   int sq
1b40: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 73 71  lite3_prepare(sq
1b50: 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
1b60: 61 72 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  ar*, int, sqlite
1b70: 33 5f 73 74 6d 74 2a 2a 2c 20 63 6f 6e 73 74 20  3_stmt**, const 
1b80: 63 68 61 72 2a 2a 29 3b 0a 20 20 20 69 6e 74 20  char**);.   int 
1b90: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1ba0: 36 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73  6(sqlite3*, cons
1bb0: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 73 71  t void*, int, sq
1bc0: 6c 69 74 65 33 5f 73 74 6d 74 2a 2a 2c 20 63 6f  lite3_stmt**, co
1bd0: 6e 73 74 20 76 6f 69 64 2a 2a 29 3b 0a 20 20 20  nst void**);.   
1be0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
1bf0: 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
1c00: 74 2a 29 3b 0a 20 20 20 69 6e 74 20 73 71 6c 69  t*);.   int sqli
1c10: 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
1c20: 33 5f 73 74 6d 74 2a 29 3b 0a 3c 2f 70 72 65 3e  3_stmt*);.</pre>
1c30: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
1c40: 70 3e 0a 54 68 65 20 73 71 6c 69 74 65 33 5f 70  p>.The sqlite3_p
1c50: 72 65 70 61 72 65 20 69 6e 74 65 72 66 61 63 65  repare interface
1c60: 20 63 6f 6d 70 69 6c 65 73 20 61 20 73 69 6e 67   compiles a sing
1c70: 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
1c80: 20 69 6e 74 6f 20 62 79 74 65 20 63 6f 64 65 0a   into byte code.
1c90: 66 6f 72 20 6c 61 74 65 72 20 65 78 65 63 75 74  for later execut
1ca0: 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ion.  This inter
1cb0: 66 61 63 65 20 69 73 20 6e 6f 77 20 74 68 65 20  face is now the 
1cc0: 70 72 65 66 65 72 72 65 64 20 77 61 79 20 6f 66  preferred way of
1cd0: 20 61 63 63 65 73 73 69 6e 67 0a 74 68 65 20 64   accessing.the d
1ce0: 61 74 61 62 61 73 65 2e 0a 3c 2f 70 3e 0a 0a 3c  atabase..</p>..<
1cf0: 70 3e 0a 54 68 65 20 53 51 4c 20 73 74 61 74 65  p>.The SQL state
1d00: 6d 65 6e 74 20 69 73 20 61 20 55 54 46 2d 38 20  ment is a UTF-8 
1d10: 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74  string for sqlit
1d20: 65 33 5f 70 72 65 70 61 72 65 28 29 2e 0a 54 68  e3_prepare()..Th
1d30: 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
1d40: 65 31 36 28 29 20 77 6f 72 6b 73 20 74 68 65 20  e16() works the 
1d50: 73 61 6d 65 20 77 61 79 20 65 78 63 65 70 74 0a  same way except.
1d60: 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73 20  that it expects 
1d70: 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
1d80: 61 73 20 53 51 4c 20 69 6e 70 75 74 2e 0a 4f 6e  as SQL input..On
1d90: 6c 79 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  ly the first SQL
1da0: 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
1db0: 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 69  e input string i
1dc0: 73 20 63 6f 6d 70 69 6c 65 64 2e 0a 54 68 65 20  s compiled..The 
1dd0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1de0: 20 69 73 20 66 69 6c 6c 65 64 20 69 6e 20 77 69   is filled in wi
1df0: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  th a pointer to 
1e00: 74 68 65 20 6e 65 78 74 20 28 75 6e 63 6f 6d 70  the next (uncomp
1e10: 69 6c 65 64 29 0a 53 51 4c 69 74 65 20 73 74 61  iled).SQLite sta
1e20: 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 69 6e  tement in the in
1e30: 70 75 74 20 73 74 72 69 6e 67 2c 20 69 66 20 61  put string, if a
1e40: 6e 79 2e 0a 54 68 65 20 73 71 6c 69 74 65 33 5f  ny..The sqlite3_
1e50: 66 69 6e 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  finalize() routi
1e60: 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ne deallocates a
1e70: 20 70 72 65 70 61 72 65 64 20 53 51 4c 20 73 74   prepared SQL st
1e80: 61 74 65 6d 65 6e 74 2e 0a 41 6c 6c 20 70 72 65  atement..All pre
1e90: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1ea0: 20 6d 75 73 74 20 62 65 20 66 69 6e 61 6c 69 7a   must be finaliz
1eb0: 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 64 61  ed before the da
1ec0: 74 61 62 61 73 65 20 63 61 6e 20 62 65 0a 63 6c  tabase can be.cl
1ed0: 6f 73 65 64 2e 0a 54 68 65 20 73 71 6c 69 74 65  osed..The sqlite
1ee0: 33 5f 72 65 73 65 74 28 29 20 72 6f 75 74 69 6e  3_reset() routin
1ef0: 65 20 72 65 73 65 74 73 20 61 20 70 72 65 70 61  e resets a prepa
1f00: 72 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  red SQL statemen
1f10: 74 20 73 6f 20 74 68 61 74 20 69 74 0a 63 61 6e  t so that it.can
1f20: 20 62 65 20 65 78 65 63 75 74 65 64 20 61 67 61   be executed aga
1f30: 69 6e 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68  in..</p>..<p>.Th
1f40: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1f50: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 74 6f 6b 65  may contain toke
1f60: 6e 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ns of the form "
1f70: 3f 22 20 6f 72 20 22 3f 6e 6e 6e 22 20 6f 72 20  ?" or "?nnn" or 
1f80: 22 3a 6e 6e 6e 3a 22 0a 77 68 65 72 65 20 22 6e  ":nnn:".where "n
1f90: 6e 6e 22 20 69 73 20 61 6e 20 69 6e 74 65 67 65  nn" is an intege
1fa0: 72 2e 20 20 53 75 63 68 20 74 6f 6b 65 6e 73 20  r.  Such tokens 
1fb0: 72 65 70 72 65 73 65 6e 74 20 75 6e 73 70 65 63  represent unspec
1fc0: 69 66 69 65 64 20 6c 69 74 65 72 61 6c 20 76 61  ified literal va
1fd0: 6c 75 65 73 0a 28 6f 72 20 77 69 6c 64 63 61 72  lues.(or wildcar
1fe0: 64 73 29 20 74 6f 20 62 65 20 66 69 6c 6c 65 64  ds) to be filled
1ff0: 20 69 6e 20 6c 61 74 65 72 20 62 79 20 74 68 65   in later by the
2000: 20 0a 3c 61 20 68 72 65 66 3d 22 63 61 70 69 33   .<a href="capi3
2010: 72 65 66 2e 68 74 6d 6c 23 73 71 6c 69 74 65 33  ref.html#sqlite3
2020: 5f 62 69 6e 64 5f 62 6c 6f 62 22 3e 73 71 6c 69  _bind_blob">sqli
2030: 74 65 33 5f 62 69 6e 64 3c 2f 61 3e 20 69 6e 74  te3_bind</a> int
2040: 65 72 66 61 63 65 2e 0a 45 61 63 68 20 77 69 6c  erface..Each wil
2050: 64 63 61 72 64 20 61 73 20 61 6e 20 61 73 73 6f  dcard as an asso
2060: 63 69 61 74 65 64 20 6e 75 6d 62 65 72 20 67 69  ciated number gi
2070: 76 65 6e 0a 62 79 20 74 68 65 20 22 6e 6e 6e 22  ven.by the "nnn"
2080: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 73 20 74 68   that follows th
2090: 65 20 22 3f 22 2e 20 20 49 66 20 74 68 65 20 22  e "?".  If the "
20a0: 3f 22 20 69 73 20 6e 6f 74 20 66 6f 6c 6c 6f 77  ?" is not follow
20b0: 65 64 20 62 79 20 61 6e 0a 69 6e 74 65 67 65 72  ed by an.integer
20c0: 2c 20 74 68 65 6e 20 69 74 73 20 6e 75 6d 62 65  , then its numbe
20d0: 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20  r one more than 
20e0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 72  the number of pr
20f0: 69 6f 72 20 77 69 6c 64 63 61 72 64 73 0a 69 6e  ior wildcards.in
2100: 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 73 74   the same SQL st
2110: 61 74 65 6d 65 6e 74 2e 20 20 49 74 20 69 73 20  atement.  It is 
2120: 61 6c 6c 6f 77 65 64 20 66 6f 72 20 74 68 65 20  allowed for the 
2130: 73 61 6d 65 20 77 69 6c 64 63 61 72 64 0a 74 6f  same wildcard.to
2140: 20 6f 63 63 75 72 20 6d 6f 72 65 20 74 68 61 6e   occur more than
2150: 20 6f 6e 63 65 20 69 6e 20 74 68 65 20 73 61 6d   once in the sam
2160: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  e SQL statement,
2170: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 0a 61   in which case.a
2180: 6c 6c 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ll instance of t
2190: 68 61 74 20 77 69 6c 64 63 61 72 64 20 77 69 6c  hat wildcard wil
21a0: 6c 20 62 65 20 66 69 6c 6c 65 64 20 69 6e 20 77  l be filled in w
21b0: 69 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c  ith the same val
21c0: 75 65 2e 0a 55 6e 62 6f 75 6e 64 20 77 69 6c 64  ue..Unbound wild
21d0: 63 61 72 64 73 20 68 61 76 65 20 61 20 76 61 6c  cards have a val
21e0: 75 65 20 6f 66 20 4e 55 4c 4c 2e 0a 3c 2f 70 3e  ue of NULL..</p>
21f0: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  ..<blockquote><p
2200: 72 65 3e 0a 20 20 20 69 6e 74 20 73 71 6c 69 74  re>.   int sqlit
2210: 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
2220: 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2230: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2240: 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
2250: 64 2a 29 29 3b 0a 20 20 20 69 6e 74 20 73 71 6c  d*));.   int sql
2260: 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
2270: 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2280: 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 20 20  int, double);.  
2290: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
22a0: 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
22b0: 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
22c0: 20 20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62     int sqlite3_b
22d0: 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
22e0: 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 6c 6f  3_stmt*, int, lo
22f0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 29 3b 0a 20 20  ng long int);.  
2300: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2310: 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
2320: 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 20 69  tmt*, int);.   i
2330: 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2340: 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
2350: 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
2360: 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  har*, int n, voi
2370: 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 20 20  d(*)(void*));.  
2380: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2390: 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
23a0: 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
23b0: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
23c0: 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
23d0: 3b 0a 20 20 20 69 6e 74 20 73 71 6c 69 74 65 33  ;.   int sqlite3
23e0: 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
23f0: 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2400: 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
2410: 6c 75 65 2a 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62  lue*);.</pre></b
2420: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a  lockquote>..<p>.
2430: 54 68 65 72 65 20 69 73 20 61 6e 20 61 73 73 6f  There is an asso
2440: 72 74 6d 65 6e 74 20 6f 66 20 73 71 6c 69 74 65  rtment of sqlite
2450: 33 5f 62 69 6e 64 20 72 6f 75 74 69 6e 65 73 20  3_bind routines 
2460: 75 73 65 64 20 74 6f 20 61 73 73 69 67 6e 20 76  used to assign v
2470: 61 6c 75 65 73 0a 74 6f 20 77 69 6c 64 63 61 72  alues.to wildcar
2480: 64 73 20 69 6e 20 61 20 70 72 65 70 61 72 65 64  ds in a prepared
2490: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
24a0: 20 55 6e 62 6f 75 6e 64 20 77 69 6c 64 63 61 72   Unbound wildcar
24b0: 64 73 0a 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds.are interpret
24c0: 65 64 20 61 73 20 4e 55 4c 4c 73 2e 20 20 42 69  ed as NULLs.  Bi
24d0: 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 72  ndings are not r
24e0: 65 73 65 74 20 62 79 20 73 71 6c 69 74 65 33 5f  eset by sqlite3_
24f0: 72 65 73 65 74 28 29 2e 0a 42 75 74 20 77 69 6c  reset()..But wil
2500: 64 63 61 72 64 73 20 63 61 6e 20 62 65 20 72 65  dcards can be re
2510: 62 6f 75 6e 64 20 74 6f 20 6e 65 77 20 76 61 6c  bound to new val
2520: 75 65 73 20 61 66 74 65 72 20 61 6e 20 73 71 6c  ues after an sql
2530: 69 74 65 33 5f 72 65 73 65 74 28 29 2e 0a 3c 2f  ite3_reset()..</
2540: 70 3e 0a 0a 3c 70 3e 0a 41 66 74 65 72 20 61 6e  p>..<p>.After an
2550: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 68   SQL statement h
2560: 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
2570: 20 28 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c 79   (and optionally
2580: 20 62 6f 75 6e 64 29 2c 20 69 74 0a 69 73 20 65   bound), it.is e
2590: 78 65 63 75 74 65 64 20 75 73 69 6e 67 3a 0a 3c  xecuted using:.<
25a0: 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  /p>..<blockquote
25b0: 3e 3c 70 72 65 3e 0a 20 20 20 69 6e 74 20 73 71  ><pre>.   int sq
25c0: 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
25d0: 65 33 5f 73 74 6d 74 2a 29 3b 0a 3c 2f 70 72 65  e3_stmt*);.</pre
25e0: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  ></blockquote>..
25f0: 3c 70 3e 0a 54 68 65 20 73 71 6c 69 74 65 33 5f  <p>.The sqlite3_
2600: 73 74 65 70 28 29 20 72 6f 75 74 69 6e 65 20 72  step() routine r
2610: 65 74 75 72 6e 20 53 51 4c 49 54 45 33 5f 52 4f  eturn SQLITE3_RO
2620: 57 20 69 66 20 69 74 20 69 73 20 72 65 74 75 72  W if it is retur
2630: 6e 69 6e 67 20 61 20 73 69 6e 67 6c 65 0a 72 6f  ning a single.ro
2640: 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2650: 73 65 74 2c 20 6f 72 20 53 51 4c 49 54 45 33 5f  set, or SQLITE3_
2660: 44 4f 4e 45 20 69 66 20 65 78 65 63 75 74 69 6f  DONE if executio
2670: 6e 20 68 61 73 20 63 6f 6d 70 6c 65 74 65 64 2c  n has completed,
2680: 20 65 69 74 68 65 72 0a 6e 6f 72 6d 61 6c 6c 79   either.normally
2690: 20 6f 72 20 64 75 65 20 74 6f 20 61 6e 20 65 72   or due to an er
26a0: 72 6f 72 2e 20 20 49 74 20 6d 69 67 68 74 20 61  ror.  It might a
26b0: 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 4c 49 54  lso return SQLIT
26c0: 45 33 5f 42 55 53 59 20 69 66 20 69 74 20 69 73  E3_BUSY if it is
26d0: 0a 75 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20  .unable to open 
26e0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
26f0: 65 2e 20 20 49 66 20 74 68 65 20 72 65 74 75 72  e.  If the retur
2700: 6e 20 76 61 6c 75 65 20 69 73 20 53 51 4c 49 54  n value is SQLIT
2710: 45 33 5f 52 4f 57 2c 20 74 68 65 6e 0a 74 68 65  E3_ROW, then.the
2720: 20 66 6f 6c 6c 6f 77 69 6e 67 20 72 6f 75 74 69   following routi
2730: 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
2740: 74 6f 20 65 78 74 72 61 63 74 20 69 6e 66 6f 72  to extract infor
2750: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 61  mation about tha
2760: 74 20 72 6f 77 0a 6f 66 20 74 68 65 20 72 65 73  t row.of the res
2770: 75 6c 74 20 73 65 74 3a 0a 3c 2f 70 3e 0a 0a 3c  ult set:.</p>..<
2780: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
2790: 0a 20 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .   const void *
27a0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27b0: 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
27c0: 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 20 20  *, int iCol);.  
27d0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
27e0: 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
27f0: 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2800: 6c 29 3b 0a 20 20 20 69 6e 74 20 73 71 6c 69 74  l);.   int sqlit
2810: 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2820: 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2830: 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 20 20 20 69   int iCol);.   i
2840: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2850: 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
2860: 73 74 6d 74 2a 29 3b 0a 20 20 20 63 6f 6e 73 74  stmt*);.   const
2870: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2880: 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
2890: 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2c 20 69  qlite3_stmt *, i
28a0: 6e 74 20 69 43 6f 6c 29 3b 0a 20 20 20 63 6f 6e  nt iCol);.   con
28b0: 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
28c0: 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
28d0: 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  16(sqlite3_stmt 
28e0: 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 20 20  *, int iCol);.  
28f0: 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
2900: 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
2910: 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2920: 20 69 43 6f 6c 29 3b 0a 20 20 20 69 6e 74 20 73   iCol);.   int s
2930: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2940: 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2950: 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 20 20 20 6c   int iCol);.   l
2960: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2970: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
2980: 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2990: 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 20 20 20 63   int iCol);.   c
29a0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
29b0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
29c0: 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29d0: 74 20 69 43 6f 6c 29 3b 0a 20 20 20 63 6f 6e 73  t iCol);.   cons
29e0: 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
29f0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
2a00: 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a10: 20 69 43 6f 6c 29 3b 0a 20 20 20 63 6f 6e 73 74   iCol);.   const
2a20: 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2a30: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a40: 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2a50: 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 20 20  *, int iCol);.  
2a60: 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2a70: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a80: 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2a90: 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 20 20 20  , int iCol);.   
2aa0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2ab0: 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
2ac0: 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2ad0: 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  ;.</pre></blockq
2ae0: 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65 20 0a  uote>..<p>.The .
2af0: 3c 61 20 68 72 65 66 3d 22 63 61 70 69 33 72 65  <a href="capi3re
2b00: 66 2e 68 74 6d 6c 23 73 71 6c 69 74 65 33 5f 63  f.html#sqlite3_c
2b10: 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 22 3e 73 71 6c  olumn_count">sql
2b20: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2b30: 74 28 29 3c 2f 61 3e 0a 66 75 6e 63 74 69 6f 6e  t()</a>.function
2b40: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2b50: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2b60: 6e 0a 74 68 65 20 72 65 73 75 6c 74 73 20 73 65  n.the results se
2b70: 74 2e 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t.  sqlite3_colu
2b80: 6d 6e 5f 63 6f 75 6e 74 28 29 20 63 61 6e 20 62  mn_count() can b
2b90: 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
2ba0: 74 69 6d 65 20 61 66 74 65 72 0a 73 71 6c 69 74  time after.sqlit
2bb0: 65 33 5f 70 72 65 70 61 72 65 28 29 2e 20 20 0a  e3_prepare().  .
2bc0: 3c 61 20 68 72 65 66 3d 22 63 61 70 69 33 72 65  <a href="capi3re
2bd0: 66 2e 68 74 6d 6c 23 73 71 6c 69 74 65 33 5f 64  f.html#sqlite3_d
2be0: 61 74 61 5f 63 6f 75 6e 74 22 3e 73 71 6c 69 74  ata_count">sqlit
2bf0: 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 3c  e3_data_count()<
2c00: 2f 61 3e 0a 77 6f 72 6b 73 20 73 69 6d 69 6c 61  /a>.works simila
2c10: 72 6c 79 20 74 6f 0a 73 71 6c 69 74 65 33 5f 63  rly to.sqlite3_c
2c20: 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 65 78  olumn_count() ex
2c30: 63 65 70 74 20 74 68 61 74 20 69 74 20 6f 6e 6c  cept that it onl
2c40: 79 20 77 6f 72 6b 73 20 66 6f 6c 6c 6f 77 69 6e  y works followin
2c50: 67 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  g sqlite3_step()
2c60: 2e 0a 49 66 20 74 68 65 20 70 72 65 76 69 6f 75  ..If the previou
2c70: 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
2c80: 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
2c90: 64 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 6f 72  d SQLITE_DONE or
2ca0: 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a   an error code,.
2cb0: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
2cc0: 61 5f 63 6f 75 6e 74 28 29 20 77 69 6c 6c 20 72  a_count() will r
2cd0: 65 74 75 72 6e 20 30 20 77 68 65 72 65 61 73 20  eturn 0 whereas 
2ce0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2cf0: 6f 75 6e 74 28 29 20 77 69 6c 6c 0a 63 6f 6e 74  ount() will.cont
2d00: 69 6e 75 65 20 74 6f 20 72 65 74 75 72 6e 20 74  inue to return t
2d10: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2d20: 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2d30: 6c 74 20 73 65 74 2e 0a 3c 2f 70 3e 0a 0a 3c 70  lt set..</p>..<p
2d40: 3e 0a 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  >.The sqlite3_co
2d50: 6c 75 6d 6e 5f 74 79 70 65 28 29 20 66 75 6e 63  lumn_type() func
2d60: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
2d70: 0a 64 61 74 61 74 79 70 65 20 66 6f 72 20 74 68  .datatype for th
2d80: 65 20 76 61 6c 75 65 20 69 6e 20 74 68 65 20 4e  e value in the N
2d90: 74 68 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20  th column.  The 
2da0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 20  return value is 
2db0: 6f 6e 65 0a 6f 66 20 74 68 65 73 65 3a 0a 3c 2f  one.of these:.</
2dc0: 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  p>..<blockquote>
2dd0: 3c 70 72 65 3e 0a 20 20 20 23 64 65 66 69 6e 65  <pre>.   #define
2de0: 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
2df0: 20 31 0a 20 20 20 23 64 65 66 69 6e 65 20 53 51   1.   #define SQ
2e00: 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
2e10: 20 20 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54     #define SQLIT
2e20: 45 5f 54 45 58 54 20 20 20 20 20 33 0a 20 20 20  E_TEXT     3.   
2e30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
2e40: 4c 4f 42 20 20 20 20 20 34 0a 20 20 20 23 64 65  LOB     4.   #de
2e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
2e60: 20 20 20 20 20 35 0a 3c 2f 70 72 65 3e 3c 2f 62       5.</pre></b
2e70: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a  lockquote>..<p>.
2e80: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
2e90: 6d 6e 5f 64 65 63 6c 74 79 70 65 28 29 20 72 6f  mn_decltype() ro
2ea0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 65  utine returns te
2eb0: 78 74 20 77 68 69 63 68 20 69 73 20 74 68 65 0a  xt which is the.
2ec0: 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
2ed0: 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   the column in t
2ee0: 68 65 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  he CREATE TABLE 
2ef0: 73 74 61 74 65 6d 65 6e 74 2e 20 20 46 6f 72 20  statement.  For 
2f00: 61 6e 0a 65 78 70 72 65 73 73 69 6f 6e 2c 20 74  an.expression, t
2f10: 68 65 20 72 65 74 75 72 6e 20 74 79 70 65 20 69  he return type i
2f20: 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
2f30: 67 2e 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  g.  sqlite3_colu
2f40: 6d 6e 5f 6e 61 6d 65 28 29 0a 72 65 74 75 72 6e  mn_name().return
2f50: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
2f60: 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 2e 20 20 73  e Nth column.  s
2f70: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f80: 74 65 73 28 29 20 72 65 74 75 72 6e 73 0a 74 68  tes() returns.th
2f90: 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2fa0: 73 20 69 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68  s in a column th
2fb0: 61 74 20 68 61 73 20 74 79 70 65 20 42 4c 4f 42  at has type BLOB
2fc0: 20 6f 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   or the number o
2fd0: 66 20 62 79 74 65 73 0a 69 6e 20 61 20 54 45 58  f bytes.in a TEX
2fe0: 54 20 73 74 72 69 6e 67 20 77 69 74 68 20 55 54  T string with UT
2ff0: 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2e 20 20 73  F-8 encoding.  s
3000: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
3010: 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 0a  tes16() returns.
3020: 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 66  the same value f
3030: 6f 72 20 42 4c 4f 42 73 20 62 75 74 20 66 6f 72  or BLOBs but for
3040: 20 54 45 58 54 20 73 74 72 69 6e 67 73 20 72 65   TEXT strings re
3050: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
3060: 20 6f 66 20 62 79 74 65 73 0a 69 6e 20 61 20 55   of bytes.in a U
3070: 54 46 2d 31 36 20 65 6e 63 6f 64 69 6e 67 2e 0a  TF-16 encoding..
3080: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
3090: 6c 6f 62 28 29 20 72 65 74 75 72 6e 20 42 4c 4f  lob() return BLO
30a0: 42 20 64 61 74 61 2e 20 20 0a 73 71 6c 69 74 65  B data.  .sqlite
30b0: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
30c0: 72 65 74 75 72 6e 20 54 45 58 54 20 64 61 74 61  return TEXT data
30d0: 20 61 73 20 55 54 46 2d 38 2e 0a 73 71 6c 69 74   as UTF-8..sqlit
30e0: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30f0: 28 29 20 72 65 74 75 72 6e 20 54 45 58 54 20 64  () return TEXT d
3100: 61 74 61 20 61 73 20 55 54 46 2d 31 36 2e 0a 73  ata as UTF-16..s
3110: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
3120: 74 28 29 20 72 65 74 75 72 6e 20 49 4e 54 45 47  t() return INTEG
3130: 45 52 20 64 61 74 61 20 69 6e 20 74 68 65 20 68  ER data in the h
3140: 6f 73 74 20 6d 61 63 68 69 6e 65 73 20 6e 61 74  ost machines nat
3150: 69 76 65 0a 69 6e 74 65 67 65 72 20 66 6f 72 6d  ive.integer form
3160: 61 74 2e 0a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  at..sqlite3_colu
3170: 6d 6e 5f 69 6e 74 36 34 28 29 20 72 65 74 75 72  mn_int64() retur
3180: 6e 73 20 36 34 2d 62 69 74 20 49 4e 54 45 47 45  ns 64-bit INTEGE
3190: 52 20 64 61 74 61 2e 0a 46 69 6e 61 6c 6c 79 2c  R data..Finally,
31a0: 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31b0: 64 6f 75 62 6c 65 28 29 20 72 65 74 75 72 6e 20  double() return 
31c0: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 64  floating point d
31d0: 61 74 61 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49  ata..</p>..<p>.I
31e0: 74 20 69 73 20 6e 6f 74 20 6e 65 63 65 73 73 61  t is not necessa
31f0: 72 79 20 74 6f 20 72 65 74 72 69 65 76 65 20 64  ry to retrieve d
3200: 61 74 61 20 69 6e 20 74 68 65 20 66 6f 72 6d 61  ata in the forma
3210: 74 20 73 70 65 63 69 66 79 20 62 79 0a 73 71 6c  t specify by.sql
3220: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
3230: 28 29 2e 20 20 49 66 20 61 20 64 69 66 66 65 72  ().  If a differ
3240: 65 6e 74 20 66 6f 72 6d 61 74 20 69 73 20 72 65  ent format is re
3250: 71 75 65 73 74 65 64 2c 20 74 68 65 20 64 61 74  quested, the dat
3260: 61 0a 69 73 20 63 6f 6e 76 65 72 74 65 64 20 61  a.is converted a
3270: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 3c 2f  utomatically..</
3280: 70 3e 0a 0a 3c 68 34 3e 32 2e 33 20 55 73 65 72  p>..<h4>2.3 User
3290: 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
32a0: 6e 73 3c 2f 68 34 3e 0a 0a 3c 70 3e 0a 55 73 65  ns</h4>..<p>.Use
32b0: 72 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  r defined functi
32c0: 6f 6e 73 20 63 61 6e 20 62 65 20 63 72 65 61 74  ons can be creat
32d0: 65 64 20 75 73 69 6e 67 20 74 68 65 20 66 6f 6c  ed using the fol
32e0: 6c 6f 77 69 6e 67 20 72 6f 75 74 69 6e 65 3a 0a  lowing routine:.
32f0: 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  </p>..<blockquot
3300: 65 3e 3c 70 72 65 3e 0a 20 20 20 74 79 70 65 64  e><pre>.   typed
3310: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
3320: 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f  3_value sqlite3_
3330: 76 61 6c 75 65 3b 0a 20 20 20 69 6e 74 20 73 71  value;.   int sq
3340: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
3350: 63 74 69 6f 6e 28 0a 20 20 20 20 20 73 71 6c 69  ction(.     sqli
3360: 74 65 33 20 2a 2c 0a 20 20 20 20 20 63 6f 6e 73  te3 *,.     cons
3370: 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
3380: 6e 4e 61 6d 65 2c 0a 20 20 20 20 20 69 6e 74 20  nName,.     int 
3390: 6e 41 72 67 2c 0a 20 20 20 20 20 69 6e 74 20 65  nArg,.     int e
33a0: 54 65 78 74 52 65 70 2c 0a 20 20 20 20 20 76 6f  TextRep,.     vo
33b0: 69 64 2a 2c 0a 20 20 20 20 20 76 6f 69 64 20 28  id*,.     void (
33c0: 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
33d0: 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
33e0: 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
33f0: 20 20 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70      void (*xStep
3400: 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
3410: 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
3420: 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 76 6f  alue**),.     vo
3430: 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
3440: 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 20  ite3_context*). 
3450: 20 20 29 3b 0a 20 20 20 69 6e 74 20 73 71 6c 69    );.   int sqli
3460: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
3470: 69 6f 6e 31 36 28 0a 20 20 20 20 20 73 71 6c 69  ion16(.     sqli
3480: 74 65 33 2a 2c 0a 20 20 20 20 20 63 6f 6e 73 74  te3*,.     const
3490: 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e   void *zFunction
34a0: 4e 61 6d 65 2c 0a 20 20 20 20 20 69 6e 74 20 6e  Name,.     int n
34b0: 41 72 67 2c 0a 20 20 20 20 20 69 6e 74 20 65 54  Arg,.     int eT
34c0: 65 78 74 52 65 70 2c 0a 20 20 20 20 20 76 6f 69  extRep,.     voi
34d0: 64 2a 2c 0a 20 20 20 20 20 76 6f 69 64 20 28 2a  d*,.     void (*
34e0: 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
34f0: 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
3500: 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
3510: 20 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29     void (*xStep)
3520: 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
3530: 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
3540: 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 76 6f 69  lue**),.     voi
3550: 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
3560: 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 20 20  te3_context*).  
3570: 20 29 3b 0a 20 20 20 23 64 65 66 69 6e 65 20 53   );.   #define S
3580: 51 4c 49 54 45 33 5f 55 54 46 38 20 20 20 20 20  QLITE3_UTF8     
3590: 31 0a 20 20 20 23 64 65 66 69 6e 65 20 53 51 4c  1.   #define SQL
35a0: 49 54 45 33 5f 55 54 46 31 36 20 20 20 20 32 0a  ITE3_UTF16    2.
35b0: 20 20 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54     #define SQLIT
35c0: 45 33 5f 55 54 46 31 36 42 45 20 20 33 0a 20 20  E3_UTF16BE  3.  
35d0: 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33   #define SQLITE3
35e0: 5f 55 54 46 31 36 4c 45 20 20 34 0a 20 20 20 23  _UTF16LE  4.   #
35f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 41  define SQLITE3_A
3600: 4e 59 20 20 20 20 20 20 35 0a 3c 2f 70 72 65 3e  NY      5.</pre>
3610: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
3620: 70 3e 0a 54 68 65 20 6e 41 72 67 20 70 61 72 61  p>.The nArg para
3630: 6d 65 74 65 72 20 73 70 65 63 69 66 69 65 73 20  meter specifies 
3640: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
3650: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 66  guments to the f
3660: 75 6e 63 74 69 6f 6e 2e 0a 41 20 76 61 6c 75 65  unction..A value
3670: 20 6f 66 20 30 20 69 6e 64 69 63 61 74 65 73 20   of 0 indicates 
3680: 74 68 61 74 20 61 6e 79 20 6e 75 6d 62 65 72 20  that any number 
3690: 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 69 73 20  of arguments is 
36a0: 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 0a 65 54  allowed.  The.eT
36b0: 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72  extRep parameter
36c0: 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 20   specifies what 
36d0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 74  representation t
36e0: 65 78 74 20 76 61 6c 75 65 73 20 61 72 65 20 65  ext values are e
36f0: 78 70 65 63 74 65 64 0a 74 6f 20 62 65 20 69 6e  xpected.to be in
3700: 20 66 6f 72 20 61 72 67 75 6d 65 6e 74 73 20 74   for arguments t
3710: 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
3720: 20 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74    The value of t
3730: 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 73 68  his parameter sh
3740: 6f 75 6c 64 0a 62 65 20 6f 6e 65 20 6f 66 20 74  ould.be one of t
3750: 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 64 65  he parameters de
3760: 66 69 6e 65 64 20 61 62 6f 76 65 2e 20 20 53 51  fined above.  SQ
3770: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 61  Lite version 3 a
3780: 6c 6c 6f 77 73 20 6d 75 6c 74 69 70 6c 65 0a 69  llows multiple.i
3790: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
37a0: 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
37b0: 69 6f 6e 20 75 73 69 6e 67 20 64 69 66 66 65 72  ion using differ
37c0: 65 6e 74 20 74 65 78 74 20 72 65 70 72 65 73 65  ent text represe
37d0: 6e 74 61 74 69 6f 6e 73 2e 0a 54 68 65 20 64 61  ntations..The da
37e0: 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 63 68  tabase engine ch
37f0: 6f 6f 73 65 73 20 74 68 65 20 66 75 6e 63 74 69  ooses the functi
3800: 6f 6e 20 74 68 61 74 20 6d 69 6e 69 6d 69 7a 61  on that minimiza
3810: 74 69 6f 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a  tion the number.
3820: 6f 66 20 74 65 78 74 20 63 6f 6e 76 65 72 73 69  of text conversi
3830: 6f 6e 73 20 72 65 71 75 69 72 65 64 2e 0a 3c 2f  ons required..</
3840: 70 3e 0a 0a 3c 70 3e 0a 4e 6f 72 6d 61 6c 20 66  p>..<p>.Normal f
3850: 75 6e 63 74 69 6f 6e 73 20 73 70 65 63 69 66 79  unctions specify
3860: 20 6f 6e 6c 79 20 78 46 75 6e 63 20 61 6e 64 20   only xFunc and 
3870: 6c 65 61 76 65 20 78 53 74 65 70 20 61 6e 64 20  leave xStep and 
3880: 78 46 69 6e 61 6c 20 73 65 74 20 74 6f 20 4e 55  xFinal set to NU
3890: 4c 4c 2e 0a 41 67 67 72 65 67 61 74 65 20 66 75  LL..Aggregate fu
38a0: 6e 63 74 69 6f 6e 73 20 73 70 65 63 69 66 79 20  nctions specify 
38b0: 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
38c0: 20 61 6e 64 20 6c 65 61 76 65 20 78 46 75 6e 63   and leave xFunc
38d0: 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 54 68   set to NULL..Th
38e0: 65 72 65 20 69 73 20 6e 6f 20 73 65 70 61 72 61  ere is no separa
38f0: 74 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  te sqlite3_creat
3900: 65 5f 61 67 67 72 65 67 61 74 65 28 29 20 41 50  e_aggregate() AP
3910: 49 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65  I..</p>..<p>.The
3920: 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 69   function name i
3930: 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 55  s specified in U
3940: 54 46 2d 38 2e 20 20 41 20 73 65 70 61 72 61 74  TF-8.  A separat
3950: 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
3960: 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 0a 41 50  _function16().AP
3970: 49 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  I works the same
3980: 20 61 73 20 73 71 6c 69 74 65 5f 63 72 65 61 74   as sqlite_creat
3990: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 0a 65 78 63  e_function().exc
39a0: 65 70 74 20 74 68 61 74 20 74 68 65 20 66 75 6e  ept that the fun
39b0: 63 74 69 6f 6e 20 6e 61 6d 65 20 69 73 20 73 70  ction name is sp
39c0: 65 63 69 66 69 65 64 20 69 6e 20 55 54 46 2d 31  ecified in UTF-1
39d0: 36 20 68 6f 73 74 20 62 79 74 65 20 6f 72 64 65  6 host byte orde
39e0: 72 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 4e 6f 74  r..</p>..<p>.Not
39f0: 69 63 65 20 74 68 61 74 20 74 68 65 20 70 61 72  ice that the par
3a00: 61 6d 65 74 65 72 73 20 74 6f 20 66 75 6e 63 74  ameters to funct
3a10: 69 6f 6e 73 20 61 72 65 20 6e 6f 77 20 70 6f 69  ions are now poi
3a20: 6e 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33  nters to sqlite3
3a30: 5f 76 61 6c 75 65 0a 73 74 72 75 63 74 75 72 65  _value.structure
3a40: 73 20 69 6e 73 74 65 61 64 20 6f 66 20 70 6f 69  s instead of poi
3a50: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3a60: 20 61 73 20 69 6e 20 53 51 4c 69 74 65 20 76 65   as in SQLite ve
3a70: 72 73 69 6f 6e 20 32 2e 58 2e 0a 54 68 65 20 66  rsion 2.X..The f
3a80: 6f 6c 6c 6f 77 69 6e 67 20 72 6f 75 74 69 6e 65  ollowing routine
3a90: 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 65 78  s are used to ex
3aa0: 74 72 61 63 74 20 75 73 65 66 75 6c 20 69 6e 66  tract useful inf
3ab0: 6f 72 6d 61 74 69 6f 6e 20 66 72 6f 6d 20 74 68  ormation from th
3ac0: 65 73 65 0a 22 76 61 6c 75 65 73 22 3a 0a 3c 2f  ese."values":.</
3ad0: 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  p>..<blockquote>
3ae0: 3c 70 72 65 3e 0a 20 20 20 63 6f 6e 73 74 20 76  <pre>.   const v
3af0: 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
3b00: 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
3b10: 76 61 6c 75 65 2a 29 3b 0a 20 20 20 69 6e 74 20  value*);.   int 
3b20: 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
3b30: 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
3b40: 65 2a 29 3b 0a 20 20 20 69 6e 74 20 73 71 6c 69  e*);.   int sqli
3b50: 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
3b60: 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
3b70: 29 3b 0a 20 20 20 64 6f 75 62 6c 65 20 73 71 6c  );.   double sql
3b80: 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
3b90: 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
3ba0: 29 3b 0a 20 20 20 69 6e 74 20 73 71 6c 69 74 65  );.   int sqlite
3bb0: 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69  3_value_int(sqli
3bc0: 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 20 20 20  te3_value*);.   
3bd0: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
3be0: 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
3bf0: 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
3c00: 29 3b 0a 20 20 20 63 6f 6e 73 74 20 75 6e 73 69  );.   const unsi
3c10: 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
3c20: 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
3c30: 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 20  lite3_value*);. 
3c40: 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71    const void *sq
3c50: 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
3c60: 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
3c70: 2a 29 3b 0a 20 20 20 69 6e 74 20 73 71 6c 69 74  *);.   int sqlit
3c80: 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
3c90: 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 3c  lite3_value*);.<
3ca0: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
3cb0: 65 3e 0a 0a 3c 70 3e 0a 46 75 6e 63 74 69 6f 6e  e>..<p>.Function
3cc0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
3cd0: 20 75 73 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69   use the followi
3ce0: 6e 67 20 41 50 49 73 20 74 6f 20 61 63 71 75 69  ng APIs to acqui
3cf0: 72 65 20 63 6f 6e 74 65 78 74 20 61 6e 64 0a 74  re context and.t
3d00: 6f 20 72 65 70 6f 72 74 20 72 65 73 75 6c 74 73  o report results
3d10: 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  :.</p>..<blockqu
3d20: 6f 74 65 3e 3c 70 72 65 3e 0a 20 20 20 76 6f 69  ote><pre>.   voi
3d30: 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
3d40: 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
3d50: 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
3d60: 6e 74 20 6e 62 79 74 65 29 3b 0a 20 20 20 76 6f  nt nbyte);.   vo
3d70: 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
3d80: 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
3d90: 6e 74 65 78 74 2a 29 3b 0a 20 20 20 76 6f 69 64  ntext*);.   void
3da0: 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
3db0: 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
3dc0: 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
3dd0: 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
3de0: 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 20 20 20 76  *)(void*));.   v
3df0: 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
3e00: 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
3e10: 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
3e20: 6c 65 29 3b 0a 20 20 20 76 6f 69 64 20 73 71 6c  le);.   void sql
3e30: 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
3e40: 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
3e50: 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
3e60: 20 69 6e 74 29 3b 0a 20 20 20 76 6f 69 64 20 73   int);.   void s
3e70: 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
3e80: 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
3e90: 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
3ea0: 69 64 2a 2c 20 69 6e 74 29 3b 0a 20 20 20 76 6f  id*, int);.   vo
3eb0: 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
3ec0: 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
3ed0: 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20  ntext*, int);.  
3ee0: 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
3ef0: 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
3f00: 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 6c 6f 6e  e3_context*, lon
3f10: 67 20 6c 6f 6e 67 20 69 6e 74 29 3b 0a 20 20 20  g long int);.   
3f20: 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
3f30: 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
3f40: 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 20 20 20 76  _context*);.   v
3f50: 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
3f60: 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
3f70: 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
3f80: 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
3f90: 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 20  id(*)(void*));. 
3fa0: 20 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72    void sqlite3_r
3fb0: 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
3fc0: 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
3fd0: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
3fe0: 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
3ff0: 29 29 3b 0a 20 20 20 76 6f 69 64 20 73 71 6c 69  ));.   void sqli
4000: 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
4010: 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
4020: 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
4030: 2a 29 3b 0a 20 20 20 76 6f 69 64 20 2a 73 71 6c  *);.   void *sql
4040: 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
4050: 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
4060: 2a 2c 20 69 6e 74 29 3b 0a 20 20 20 76 6f 69 64  *, int);.   void
4070: 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
4080: 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
4090: 74 65 78 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  text*, int, void
40a0: 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
40b0: 2a 29 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  *));.</pre></blo
40c0: 63 6b 71 75 6f 74 65 3e 0a 0a 3c 68 34 3e 32 2e  ckquote>..<h4>2.
40d0: 34 20 55 73 65 72 2d 64 65 66 69 6e 65 64 20 63  4 User-defined c
40e0: 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63  ollating sequenc
40f0: 65 73 3c 2f 68 34 3e 0a 0a 3c 70 3e 0a 54 68 65  es</h4>..<p>.The
4100: 20 66 6f 6c 6c 6f 77 69 6e 67 20 72 6f 75 74 69   following routi
4110: 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  nes are used to 
4120: 69 6d 70 6c 65 6d 65 6e 74 20 75 73 65 72 2d 64  implement user-d
4130: 65 66 69 6e 65 64 0a 63 6f 6c 6c 61 74 69 6e 67  efined.collating
4140: 20 73 65 71 75 65 6e 63 65 73 3a 0a 3c 2f 70 3e   sequences:.</p>
4150: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  ..<blockquote><p
4160: 72 65 3e 0a 20 20 20 73 71 6c 69 74 65 33 5f 63  re>.   sqlite3_c
4170: 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
4180: 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
4190: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
41a0: 20 65 54 65 78 74 52 65 70 2c 20 76 6f 69 64 2a   eTextRep, void*
41b0: 2c 0a 20 20 20 20 20 20 69 6e 74 28 2a 78 43 6f  ,.      int(*xCo
41c0: 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
41d0: 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
41e0: 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 29 3b 0a  ,const void*));.
41f0: 20 20 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74     sqlite3_creat
4200: 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 73 71  e_collation16(sq
4210: 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 76 6f  lite3*, const vo
4220: 69 64 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 65  id *zName, int e
4230: 54 65 78 74 52 65 70 2c 20 76 6f 69 64 2a 2c 0a  TextRep, void*,.
4240: 20 20 20 20 20 20 69 6e 74 28 2a 78 43 6f 6d 70        int(*xComp
4250: 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
4260: 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
4270: 6f 6e 73 74 20 76 6f 69 64 2a 29 29 3b 0a 20 20  onst void*));.  
4280: 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
4290: 6f 6e 5f 6e 65 65 64 65 64 28 73 71 6c 69 74 65  on_needed(sqlite
42a0: 33 2a 2c 20 76 6f 69 64 2a 2c 20 0a 20 20 20 20  3*, void*, .    
42b0: 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
42c0: 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
42d0: 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
42e0: 2a 29 29 3b 0a 20 20 20 73 71 6c 69 74 65 33 5f  *));.   sqlite3_
42f0: 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
4300: 31 36 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  16(sqlite3*, voi
4310: 64 2a 2c 0a 20 20 20 20 20 20 76 6f 69 64 28 2a  d*,.      void(*
4320: 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
4330: 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
4340: 6e 73 74 20 76 6f 69 64 2a 29 29 3b 0a 3c 2f 70  nst void*));.</p
4350: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
4360: 0a 0a 3c 70 3e 0a 54 68 65 20 73 71 6c 69 74 65  ..<p>.The sqlite
4370: 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
4380: 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 70  on() function sp
4390: 65 63 69 66 69 65 73 20 61 20 63 6f 6c 6c 61 74  ecifies a collat
43a0: 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d  ing sequence nam
43b0: 65 0a 61 6e 64 20 61 20 63 6f 6d 70 61 72 69 73  e.and a comparis
43c0: 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69  on function to i
43d0: 6d 70 6c 65 6d 65 6e 74 20 74 68 61 74 20 63 6f  mplement that co
43e0: 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65  llating sequence
43f0: 2e 20 20 54 68 65 0a 63 6f 6d 70 61 72 69 73 6f  .  The.compariso
4400: 6e 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6f 6e  n function is on
4410: 6c 79 20 75 73 65 64 20 66 6f 72 20 63 6f 6d 70  ly used for comp
4420: 61 72 69 6e 67 20 74 65 78 74 20 76 61 6c 75 65  aring text value
4430: 73 2e 20 20 54 68 65 20 65 54 65 78 74 52 65 70  s.  The eTextRep
4440: 0a 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e  .parameter is on
4450: 65 20 6f 66 20 53 51 4c 49 54 45 33 5f 55 54 46  e of SQLITE3_UTF
4460: 38 2c 20 53 51 4c 49 54 45 33 5f 55 54 46 31 36  8, SQLITE3_UTF16
4470: 4c 45 2c 20 53 51 4c 49 54 45 33 5f 55 54 46 31  LE, SQLITE3_UTF1
4480: 36 42 45 2c 20 6f 72 0a 53 51 4c 49 54 45 33 5f  6BE, or.SQLITE3_
4490: 41 4e 59 20 74 6f 20 73 70 65 63 69 66 79 20 77  ANY to specify w
44a0: 68 69 63 68 20 74 65 78 74 20 72 65 70 72 65 73  hich text repres
44b0: 65 6e 74 61 74 69 6f 6e 20 74 68 65 20 63 6f 6d  entation the com
44c0: 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e  parison function
44d0: 20 77 6f 72 6b 73 0a 77 69 74 68 2e 20 20 53 65   works.with.  Se
44e0: 70 61 72 61 74 65 20 63 6f 6d 70 61 72 69 73 6f  parate compariso
44f0: 6e 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20  n functions can 
4500: 65 78 69 73 74 20 66 6f 72 20 74 68 65 20 73 61  exist for the sa
4510: 6d 65 20 63 6f 6c 6c 61 74 69 6e 67 0a 73 65 71  me collating.seq
4520: 75 65 6e 63 65 20 66 6f 72 20 65 61 63 68 20 6f  uence for each o
4530: 66 20 74 68 65 20 55 54 46 2d 38 2c 20 55 54 46  f the UTF-8, UTF
4540: 2d 31 36 4c 45 20 61 6e 64 20 55 54 46 2d 31 36  -16LE and UTF-16
4550: 42 45 20 74 65 78 74 20 72 65 70 72 65 73 65 6e  BE text represen
4560: 74 61 74 69 6f 6e 73 2e 0a 54 68 65 20 73 71 6c  tations..The sql
4570: 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
4580: 61 74 69 6f 6e 31 36 28 29 20 77 6f 72 6b 73 20  ation16() works 
4590: 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
45a0: 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
45b0: 65 78 63 65 70 74 0a 74 68 61 74 20 74 68 65 20  except.that the 
45c0: 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 69  collation name i
45d0: 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 55  s specified in U
45e0: 54 46 2d 31 36 20 68 6f 73 74 20 62 79 74 65 20  TF-16 host byte 
45f0: 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66  order instead of
4600: 0a 69 6e 20 55 54 46 2d 38 2e 0a 3c 2f 70 3e 0a  .in UTF-8..</p>.
4610: 0a 3c 70 3e 0a 54 68 65 20 73 71 6c 69 74 65 33  .<p>.The sqlite3
4620: 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
4630: 64 28 29 20 72 6f 75 74 69 6e 65 20 72 65 67 69  d() routine regi
4640: 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
4650: 20 77 68 69 63 68 20 74 68 65 0a 64 61 74 61 62   which the.datab
4660: 61 73 65 20 65 6e 67 69 6e 65 20 77 69 6c 6c 20  ase engine will 
4670: 69 6e 76 6f 6b 65 20 69 66 20 69 74 20 65 6e 63  invoke if it enc
4680: 6f 75 6e 74 65 72 73 20 61 6e 20 75 6e 6b 6e 6f  ounters an unkno
4690: 77 6e 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71  wn collating seq
46a0: 75 65 6e 63 65 2e 0a 54 68 65 20 63 61 6c 6c 62  uence..The callb
46b0: 61 63 6b 20 63 61 6e 20 6c 6f 6f 6b 75 70 20 61  ack can lookup a
46c0: 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 63 6f  n appropriate co
46d0: 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
46e0: 6e 20 61 6e 64 20 69 6e 76 6f 6b 65 0a 73 71 6c  n and invoke.sql
46f0: 69 74 65 5f 33 5f 63 72 65 61 74 65 5f 63 6f 6c  ite_3_create_col
4700: 6c 61 74 69 6f 6e 28 29 20 61 73 20 6e 65 65 64  lation() as need
4710: 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
4720: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
4730: 20 63 61 6c 6c 62 61 63 6b 0a 69 73 20 74 68 65   callback.is the
4740: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
4750: 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20  lating sequence 
4760: 69 6e 20 55 54 46 2d 38 2e 20 20 46 6f 72 20 73  in UTF-8.  For s
4770: 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
4780: 5f 6e 65 65 64 31 36 28 29 0a 74 68 65 20 63 61  _need16().the ca
4790: 6c 6c 62 61 63 6b 20 73 65 6e 64 73 20 74 68 65  llback sends the
47a0: 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
47b0: 6e 63 65 20 6e 61 6d 65 20 69 6e 20 55 54 46 2d  nce name in UTF-
47c0: 31 36 20 68 6f 73 74 20 62 79 74 65 20 6f 72 64  16 host byte ord
47d0: 65 72 2e 0a 3c 2f 70 3e 0a 7d 0a 66 6f 6f 74 65  er..</p>.}.foote
47e0: 72 20 24 72 63 73 69 64 0a                       r $rcsid.