Documentation Source Text

Hex Artifact Content
Login

Artifact 2524a93030a47da746c413f12a3993661684c3c4:


0000: 3c 74 69 74 6c 65 3e 43 2f 43 2b 2b 20 49 6e 74  <title>C/C++ Int
0010: 65 72 66 61 63 65 20 46 6f 72 20 53 51 4c 69 74  erface For SQLit
0020: 65 20 56 65 72 73 69 6f 6e 20 33 20 28 6f 6c 64  e Version 3 (old
0030: 29 3c 2f 74 69 74 6c 65 3e 0a 0a 0a 3c 66 6f 6e  )</title>...<fon
0040: 74 20 63 6f 6c 6f 72 3d 22 23 37 66 30 30 31 66  t color="#7f001f
0050: 22 3e 3c 70 3e 0a 3c 62 3e 4e 6f 74 65 3a 3c 2f  "><p>.<b>Note:</
0060: 62 3e 0a 54 68 69 73 20 64 6f 63 75 6d 65 6e 74  b>.This document
0070: 20 77 61 73 20 77 72 69 74 74 65 6e 20 69 6e 20   was written in 
0080: 32 30 30 34 20 61 73 20 61 20 67 75 69 64 65 20  2004 as a guide 
0090: 74 6f 20 68 65 6c 70 69 6e 67 20 70 72 6f 67 72  to helping progr
00a0: 61 6d 6d 65 72 73 0a 6d 6f 76 65 20 66 72 6f 6d  ammers.move from
00b0: 20 75 73 69 6e 67 20 53 51 4c 69 74 65 20 76 65   using SQLite ve
00c0: 72 73 69 6f 6e 20 32 20 74 6f 20 53 51 4c 69 74  rsion 2 to SQLit
00d0: 65 20 76 65 72 73 69 6f 6e 20 33 2e 20 20 54 68  e version 3.  Th
00e0: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 69 6e  e information.in
00f0: 20 74 68 69 73 20 64 6f 63 75 6d 65 6e 74 20 69   this document i
0100: 73 20 73 74 69 6c 6c 20 65 73 73 65 6e 74 69 61  s still essentia
0110: 6c 6c 79 20 63 6f 72 72 65 63 74 2c 20 68 6f 77  lly correct, how
0120: 65 76 65 72 20 74 68 65 72 65 20 68 61 76 65 20  ever there have 
0130: 62 65 65 6e 0a 6d 61 6e 79 20 63 68 61 6e 67 65  been.many change
0140: 73 20 61 6e 64 20 65 6e 68 61 6e 63 65 6d 65 6e  s and enhancemen
0150: 74 73 20 6f 76 65 72 20 74 68 65 20 79 65 61 72  ts over the year
0160: 73 2e 20 20 57 65 20 72 65 63 6f 6d 6d 65 6e 64  s.  We recommend
0170: 20 74 68 61 74 20 74 68 65 0a 66 6f 6c 6c 6f 77   that the.follow
0180: 69 6e 67 20 64 6f 63 75 6d 65 6e 74 73 20 62 65  ing documents be
0190: 20 75 73 65 64 20 69 6e 73 74 65 61 64 3a 0a 3c   used instead:.<
01a0: 75 6c 3e 0a 3c 6c 69 3e 3c 61 20 68 72 65 66 3d  ul>.<li><a href=
01b0: 22 63 69 6e 74 72 6f 2e 68 74 6d 6c 22 3e 41 6e  "cintro.html">An
01c0: 20 49 6e 74 72 6f 64 75 63 74 69 6f 6e 20 54 6f   Introduction To
01d0: 20 54 68 65 20 53 51 4c 69 74 65 20 43 2f 43 2b   The SQLite C/C+
01e0: 2b 20 49 6e 74 65 72 66 61 63 65 3c 2f 61 3e 3c  + Interface</a><
01f0: 2f 6c 69 3e 0a 3c 6c 69 3e 3c 61 20 68 72 65 66  /li>.<li><a href
0200: 3d 22 63 33 72 65 66 2f 69 6e 74 72 6f 2e 68 74  ="c3ref/intro.ht
0210: 6d 6c 22 3e 53 51 4c 69 74 65 20 43 2f 43 2b 2b  ml">SQLite C/C++
0220: 20 52 65 66 65 72 65 6e 63 65 20 47 75 69 64 65   Reference Guide
0230: 3c 2f 61 3e 3c 2f 6c 69 3e 0a 3c 2f 75 6c 3e 0a  </a></li>.</ul>.
0240: 3c 2f 70 3e 0a 3c 2f 66 6f 6e 74 3e 0a 0a 3c 68  </p>.</font>..<h
0250: 32 3e 43 2f 43 2b 2b 20 49 6e 74 65 72 66 61 63  2>C/C++ Interfac
0260: 65 20 46 6f 72 20 53 51 4c 69 74 65 20 56 65 72  e For SQLite Ver
0270: 73 69 6f 6e 20 33 3c 2f 68 32 3e 0a 0a 3c 68 33  sion 3</h2>..<h3
0280: 3e 31 2e 30 20 4f 76 65 72 76 69 65 77 3c 2f 68  >1.0 Overview</h
0290: 33 3e 0a 0a 3c 70 3e 0a 53 51 4c 69 74 65 20 76  3>..<p>.SQLite v
02a0: 65 72 73 69 6f 6e 20 33 2e 30 20 69 73 20 61 20  ersion 3.0 is a 
02b0: 6e 65 77 20 76 65 72 73 69 6f 6e 20 6f 66 20 53  new version of S
02c0: 51 4c 69 74 65 2c 20 64 65 72 69 76 65 64 20 66  QLite, derived f
02d0: 72 6f 6d 0a 74 68 65 20 53 51 4c 69 74 65 20 32  rom.the SQLite 2
02e0: 2e 38 2e 31 33 20 63 6f 64 65 20 62 61 73 65 2c  .8.13 code base,
02f0: 20 62 75 74 20 77 69 74 68 20 61 6e 20 69 6e 63   but with an inc
0300: 6f 6d 70 61 74 69 62 6c 65 20 66 69 6c 65 20 66  ompatible file f
0310: 6f 72 6d 61 74 0a 61 6e 64 20 41 50 49 2e 0a 53  ormat.and API..S
0320: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
0330: 30 20 77 61 73 20 63 72 65 61 74 65 64 20 74 6f  0 was created to
0340: 20 61 6e 73 77 65 72 20 64 65 6d 61 6e 64 20 66   answer demand f
0350: 6f 72 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  or the following
0360: 20 66 65 61 74 75 72 65 73 3a 0a 3c 2f 70 3e 0a   features:.</p>.
0370: 0a 3c 75 6c 3e 0a 3c 6c 69 3e 53 75 70 70 6f 72  .<ul>.<li>Suppor
0380: 74 20 66 6f 72 20 55 54 46 2d 31 36 2e 3c 2f 6c  t for UTF-16.</l
0390: 69 3e 0a 3c 6c 69 3e 55 73 65 72 2d 64 65 66 69  i>.<li>User-defi
03a0: 6e 61 62 6c 65 20 74 65 78 74 20 63 6f 6c 6c 61  nable text colla
03b0: 74 69 6e 67 20 73 65 71 75 65 6e 63 65 73 2e 3c  ting sequences.<
03c0: 2f 6c 69 3e 0a 3c 6c 69 3e 54 68 65 20 61 62 69  /li>.<li>The abi
03d0: 6c 69 74 79 20 74 6f 20 73 74 6f 72 65 20 42 4c  lity to store BL
03e0: 4f 42 73 20 69 6e 20 69 6e 64 65 78 65 64 20 63  OBs in indexed c
03f0: 6f 6c 75 6d 6e 73 2e 3c 2f 6c 69 3e 0a 3c 2f 75  olumns.</li>.</u
0400: 6c 3e 0a 0a 3c 70 3e 0a 49 74 20 77 61 73 20 6e  l>..<p>.It was n
0410: 65 63 65 73 73 61 72 79 20 74 6f 20 6d 6f 76 65  ecessary to move
0420: 20 74 6f 20 76 65 72 73 69 6f 6e 20 33 2e 30 20   to version 3.0 
0430: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  to implement the
0440: 73 65 20 66 65 61 74 75 72 65 73 20 62 65 63 61  se features beca
0450: 75 73 65 0a 65 61 63 68 20 72 65 71 75 69 72 65  use.each require
0460: 73 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 63  s incompatible c
0470: 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 64 61  hanges to the da
0480: 74 61 62 61 73 65 20 66 69 6c 65 20 66 6f 72 6d  tabase file form
0490: 61 74 2e 20 20 4f 74 68 65 72 0a 69 6e 63 6f 6d  at.  Other.incom
04a0: 70 61 74 69 62 6c 65 20 63 68 61 6e 67 65 73 2c  patible changes,
04b0: 20 73 75 63 68 20 61 73 20 61 20 63 6c 65 61 6e   such as a clean
04c0: 75 70 20 6f 66 20 74 68 65 20 41 50 49 2c 20 77  up of the API, w
04d0: 65 72 65 20 69 6e 74 72 6f 64 75 63 65 64 20 61  ere introduced a
04e0: 74 20 74 68 65 0a 73 61 6d 65 20 74 69 6d 65 20  t the.same time 
04f0: 75 6e 64 65 72 20 74 68 65 20 74 68 65 6f 72 79  under the theory
0500: 20 74 68 61 74 20 69 74 20 69 73 20 62 65 73 74   that it is best
0510: 20 74 6f 20 67 65 74 20 79 6f 75 72 20 69 6e 63   to get your inc
0520: 6f 6d 70 61 74 69 62 6c 65 20 63 68 61 6e 67 65  ompatible change
0530: 73 0a 6f 75 74 20 6f 66 20 74 68 65 20 77 61 79  s.out of the way
0540: 20 61 6c 6c 20 61 74 20 6f 6e 63 65 2e 20 20 0a   all at once.  .
0550: 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 41 50  </p>..<p>.The AP
0560: 49 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 2e  I for version 3.
0570: 30 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  0 is similar to 
0580: 74 68 65 20 76 65 72 73 69 6f 6e 20 32 2e 58 20  the version 2.X 
0590: 41 50 49 2c 0a 62 75 74 20 77 69 74 68 20 73 6f  API,.but with so
05a0: 6d 65 20 69 6d 70 6f 72 74 61 6e 74 20 63 68 61  me important cha
05b0: 6e 67 65 73 2e 20 20 4d 6f 73 74 20 6e 6f 74 69  nges.  Most noti
05c0: 63 65 61 62 6c 79 2c 20 74 68 65 20 22 3c 74 74  ceably, the "<tt
05d0: 3e 73 71 6c 69 74 65 5f 3c 2f 74 74 3e 22 0a 70  >sqlite_</tt>".p
05e0: 72 65 66 69 78 20 74 68 61 74 20 6f 63 63 75 72  refix that occur
05f0: 73 20 6f 6e 20 74 68 65 20 62 65 67 69 6e 6e 69  s on the beginni
0600: 6e 67 20 6f 66 20 61 6c 6c 20 41 50 49 20 66 75  ng of all API fu
0610: 6e 63 74 69 6f 6e 73 20 61 6e 64 20 64 61 74 61  nctions and data
0620: 0a 73 74 72 75 63 74 75 72 65 73 20 61 72 65 20  .structures are 
0630: 63 68 61 6e 67 65 64 20 74 6f 20 22 3c 74 74 3e  changed to "<tt>
0640: 73 71 6c 69 74 65 33 5f 3c 2f 74 74 3e 22 2e 20  sqlite3_</tt>". 
0650: 20 0a 54 68 69 73 20 61 76 6f 69 64 73 20 63 6f   .This avoids co
0660: 6e 66 75 73 69 6f 6e 20 62 65 74 77 65 65 6e 20  nfusion between 
0670: 74 68 65 20 74 77 6f 20 41 50 49 73 20 61 6e 64  the two APIs and
0680: 20 61 6c 6c 6f 77 73 20 6c 69 6e 6b 69 6e 67 20   allows linking 
0690: 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 53 51 4c  against both.SQL
06a0: 69 74 65 20 32 2e 58 20 61 6e 64 20 53 51 4c 69  ite 2.X and SQLi
06b0: 74 65 20 33 2e 30 20 61 74 20 74 68 65 20 73 61  te 3.0 at the sa
06c0: 6d 65 20 74 69 6d 65 2e 0a 3c 2f 70 3e 0a 0a 3c  me time..</p>..<
06d0: 70 3e 0a 54 68 65 72 65 20 69 73 20 6e 6f 20 61  p>.There is no a
06e0: 67 72 65 65 6d 65 6e 74 20 6f 6e 20 77 68 61 74  greement on what
06f0: 20 74 68 65 20 43 20 64 61 74 61 74 79 70 65 20   the C datatype 
0700: 66 6f 72 20 61 20 55 54 46 2d 31 36 0a 73 74 72  for a UTF-16.str
0710: 69 6e 67 20 73 68 6f 75 6c 64 20 62 65 2e 20 20  ing should be.  
0720: 54 68 65 72 65 66 6f 72 65 2c 20 53 51 4c 69 74  Therefore, SQLit
0730: 65 20 75 73 65 73 20 61 20 67 65 6e 65 72 69 63  e uses a generic
0740: 20 74 79 70 65 20 6f 66 20 76 6f 69 64 2a 0a 74   type of void*.t
0750: 6f 20 72 65 66 65 72 20 74 6f 20 55 54 46 2d 31  o refer to UTF-1
0760: 36 20 73 74 72 69 6e 67 73 2e 20 20 43 6c 69 65  6 strings.  Clie
0770: 6e 74 20 73 6f 66 74 77 61 72 65 20 63 61 6e 20  nt software can 
0780: 63 61 73 74 20 74 68 65 20 76 6f 69 64 2a 20 0a  cast the void* .
0790: 74 6f 20 77 68 61 74 65 76 65 72 20 64 61 74 61  to whatever data
07a0: 74 79 70 65 20 69 73 20 61 70 70 72 6f 70 72 69  type is appropri
07b0: 61 74 65 20 66 6f 72 20 74 68 65 69 72 20 73 79  ate for their sy
07c0: 73 74 65 6d 2e 0a 3c 2f 70 3e 0a 0a 3c 68 33 3e  stem..</p>..<h3>
07d0: 32 2e 30 20 43 2f 43 2b 2b 20 49 6e 74 65 72 66  2.0 C/C++ Interf
07e0: 61 63 65 3c 2f 68 33 3e 0a 0a 3c 70 3e 0a 54 68  ace</h3>..<p>.Th
07f0: 65 20 41 50 49 20 66 6f 72 20 53 51 4c 69 74 65  e API for SQLite
0800: 20 33 2e 30 20 69 6e 63 6c 75 64 65 73 20 38 33   3.0 includes 83
0810: 20 73 65 70 61 72 61 74 65 20 66 75 6e 63 74 69   separate functi
0820: 6f 6e 73 20 69 6e 20 61 64 64 69 74 69 6f 6e 0a  ons in addition.
0830: 74 6f 20 73 65 76 65 72 61 6c 20 64 61 74 61 20  to several data 
0840: 73 74 72 75 63 74 75 72 65 73 20 61 6e 64 20 23  structures and #
0850: 64 65 66 69 6e 65 73 2e 20 20 28 41 20 63 6f 6d  defines.  (A com
0860: 70 6c 65 74 65 0a 3c 61 20 68 72 65 66 3d 22 63  plete.<a href="c
0870: 33 72 65 66 2f 69 6e 74 72 6f 2e 68 74 6d 6c 22  3ref/intro.html"
0880: 3e 41 50 49 20 72 65 66 65 72 65 6e 63 65 3c 2f  >API reference</
0890: 61 3e 20 69 73 20 70 72 6f 76 69 64 65 64 20 61  a> is provided a
08a0: 73 20 61 20 73 65 70 61 72 61 74 65 20 0a 64 6f  s a separate .do
08b0: 63 75 6d 65 6e 74 2e 29 0a 46 6f 72 74 75 6e 61  cument.).Fortuna
08c0: 74 65 6c 79 2c 20 74 68 65 20 69 6e 74 65 72 66  tely, the interf
08d0: 61 63 65 20 69 73 20 6e 6f 74 20 6e 65 61 72 6c  ace is not nearl
08e0: 79 20 61 73 20 63 6f 6d 70 6c 65 78 20 61 73 20  y as complex as 
08f0: 69 74 73 20 73 69 7a 65 20 69 6d 70 6c 69 65 73  its size implies
0900: 2e 0a 53 69 6d 70 6c 65 20 70 72 6f 67 72 61 6d  ..Simple program
0910: 73 20 63 61 6e 20 73 74 69 6c 6c 20 6d 61 6b 65  s can still make
0920: 20 64 6f 20 77 69 74 68 20 6f 6e 6c 79 20 33 20   do with only 3 
0930: 66 75 6e 63 74 69 6f 6e 73 3a 0a 5b 73 71 6c 69  functions:.[sqli
0940: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
0950: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 61  lite3_exec()], a
0960: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
0970: 65 28 29 5d 2e 0a 4d 6f 72 65 20 63 6f 6e 74 72  e()]..More contr
0980: 6f 6c 20 6f 76 65 72 20 74 68 65 20 65 78 65 63  ol over the exec
0990: 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 64 61 74  ution of the dat
09a0: 61 62 61 73 65 20 65 6e 67 69 6e 65 20 69 73 20  abase engine is 
09b0: 70 72 6f 76 69 64 65 64 0a 75 73 69 6e 67 20 5b  provided.using [
09c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
09d0: 76 32 28 29 5d 0a 74 6f 20 63 6f 6d 70 69 6c 65  v2()].to compile
09e0: 20 61 6e 20 53 51 4c 69 74 65 20 73 74 61 74 65   an SQLite state
09f0: 6d 65 6e 74 20 69 6e 74 6f 20 62 79 74 65 20 63  ment into byte c
0a00: 6f 64 65 20 61 6e 64 0a 5b 73 71 6c 69 74 65 33  ode and.[sqlite3
0a10: 5f 73 74 65 70 28 29 5d 20 74 6f 20 65 78 65 63  _step()] to exec
0a20: 75 74 65 20 74 68 61 74 20 62 79 74 65 63 6f 64  ute that bytecod
0a30: 65 2e 0a 41 20 66 61 6d 69 6c 79 20 6f 66 20 72  e..A family of r
0a40: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 6e 61 6d  outines with nam
0a50: 65 73 20 62 65 67 69 6e 6e 69 6e 67 20 77 69 74  es beginning wit
0a60: 68 20 0a 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  h .[sqlite3_colu
0a70: 6d 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  mn_blob | sqlite
0a80: 33 5f 63 6f 6c 75 6d 6e 5f 5d 0a 69 73 20 75 73  3_column_].is us
0a90: 65 64 20 74 6f 20 65 78 74 72 61 63 74 20 69 6e  ed to extract in
0aa0: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
0ab0: 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
0ac0: 66 20 61 20 71 75 65 72 79 2e 0a 4d 61 6e 79 20  f a query..Many 
0ad0: 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
0ae0: 6f 6e 73 20 63 6f 6d 65 20 69 6e 20 70 61 69 72  ons come in pair
0af0: 73 2c 20 77 69 74 68 20 62 6f 74 68 20 61 20 55  s, with both a U
0b00: 54 46 2d 38 20 61 6e 64 0a 55 54 46 2d 31 36 20  TF-8 and.UTF-16 
0b10: 76 65 72 73 69 6f 6e 2e 20 20 41 6e 64 20 74 68  version.  And th
0b20: 65 72 65 20 69 73 20 61 20 63 6f 6c 6c 65 63 74  ere is a collect
0b30: 69 6f 6e 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a  ion of routines.
0b40: 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
0b50: 74 20 75 73 65 72 2d 64 65 66 69 6e 65 64 20 53  t user-defined S
0b60: 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
0b70: 20 75 73 65 72 2d 64 65 66 69 6e 65 64 0a 74 65   user-defined.te
0b80: 78 74 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71  xt collating seq
0b90: 75 65 6e 63 65 73 2e 0a 3c 2f 70 3e 0a 0a 0a 3c  uences..</p>...<
0ba0: 68 34 3e 32 2e 31 20 4f 70 65 6e 69 6e 67 20 61  h4>2.1 Opening a
0bb0: 6e 64 20 63 6c 6f 73 69 6e 67 20 61 20 64 61 74  nd closing a dat
0bc0: 61 62 61 73 65 3c 2f 68 34 3e 0a 0a 3c 62 6c 6f  abase</h4>..<blo
0bd0: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 20 20  ckquote><pre>.  
0be0: 20 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20   typedef struct 
0bf0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
0c00: 0a 20 20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  .   int sqlite3_
0c10: 6f 70 65 6e 28 63 6f 6e 73 74 20 63 68 61 72 2a  open(const char*
0c20: 2c 20 73 71 6c 69 74 65 33 2a 2a 29 3b 0a 20 20  , sqlite3**);.  
0c30: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65   int sqlite3_ope
0c40: 6e 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  n16(const void*,
0c50: 20 73 71 6c 69 74 65 33 2a 2a 29 3b 0a 20 20 20   sqlite3**);.   
0c60: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
0c70: 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 20 20 20  e(sqlite3*);.   
0c80: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
0c90: 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
0ca0: 65 33 2a 29 3b 0a 20 20 20 63 6f 6e 73 74 20 76  e3*);.   const v
0cb0: 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
0cc0: 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
0cd0: 0a 20 20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  .   int sqlite3_
0ce0: 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 2a  errcode(sqlite3*
0cf0: 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  );.</pre></block
0d00: 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65 20  quote>..<p>.The 
0d10: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
0d20: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
0d30: 6e 20 69 6e 74 65 67 65 72 20 65 72 72 6f 72 20  n integer error 
0d40: 63 6f 64 65 20 72 61 74 68 65 72 20 74 68 61 6e  code rather than
0d50: 0a 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  .a pointer to th
0d60: 65 20 73 71 6c 69 74 65 33 20 73 74 72 75 63 74  e sqlite3 struct
0d70: 75 72 65 20 61 73 20 74 68 65 20 76 65 72 73 69  ure as the versi
0d80: 6f 6e 20 32 20 69 6e 74 65 72 66 61 63 65 20 64  on 2 interface d
0d90: 69 64 2e 0a 54 68 65 20 64 69 66 66 65 72 65 6e  id..The differen
0da0: 63 65 20 62 65 74 77 65 65 6e 20 73 71 6c 69 74  ce between sqlit
0db0: 65 33 5f 6f 70 65 6e 28 29 0a 61 6e 64 20 73 71  e3_open().and sq
0dc0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69  lite3_open16() i
0dd0: 73 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 6f  s that sqlite3_o
0de0: 70 65 6e 31 36 28 29 20 74 61 6b 65 73 20 55 54  pen16() takes UT
0df0: 46 2d 31 36 20 28 69 6e 20 68 6f 73 74 20 6e 61  F-16 (in host na
0e00: 74 69 76 65 0a 62 79 74 65 20 6f 72 64 65 72 29  tive.byte order)
0e10: 20 66 6f 72 20 74 68 65 20 6e 61 6d 65 20 6f 66   for the name of
0e20: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
0e30: 6c 65 2e 20 20 49 66 20 61 20 6e 65 77 20 64 61  le.  If a new da
0e40: 74 61 62 61 73 65 20 66 69 6c 65 0a 6e 65 65 64  tabase file.need
0e50: 73 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 2c  s to be created,
0e60: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6f 70   then sqlite3_op
0e70: 65 6e 31 36 28 29 20 73 65 74 73 20 74 68 65 20  en16() sets the 
0e80: 69 6e 74 65 72 6e 61 6c 20 74 65 78 74 0a 72 65  internal text.re
0e90: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 74 6f 20  presentation to 
0ea0: 55 54 46 2d 31 36 20 77 68 65 72 65 61 73 20 73  UTF-16 whereas s
0eb0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 73 65  qlite3_open() se
0ec0: 74 73 20 74 68 65 20 74 65 78 74 0a 72 65 70 72  ts the text.repr
0ed0: 65 73 65 6e 74 61 74 69 6f 6e 20 74 6f 20 55 54  esentation to UT
0ee0: 46 2d 38 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54  F-8..</p>..<p>.T
0ef0: 68 65 20 6f 70 65 6e 69 6e 67 20 61 6e 64 2f 6f  he opening and/o
0f00: 72 20 63 72 65 61 74 69 6e 67 20 6f 66 20 74 68  r creating of th
0f10: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
0f20: 69 73 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  is deferred unti
0f30: 6c 20 74 68 65 0a 66 69 6c 65 20 69 73 20 61 63  l the.file is ac
0f40: 74 75 61 6c 6c 79 20 6e 65 65 64 65 64 2e 20 20  tually needed.  
0f50: 54 68 69 73 20 61 6c 6c 6f 77 73 20 6f 70 74 69  This allows opti
0f60: 6f 6e 73 20 61 6e 64 20 70 61 72 61 6d 65 74 65  ons and paramete
0f70: 72 73 2c 20 73 75 63 68 0a 61 73 20 74 68 65 20  rs, such.as the 
0f80: 6e 61 74 69 76 65 20 74 65 78 74 20 72 65 70 72  native text repr
0f90: 65 73 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 64  esentation and d
0fa0: 65 66 61 75 6c 74 20 70 61 67 65 20 73 69 7a 65  efault page size
0fb0: 2c 20 74 6f 20 62 65 0a 73 65 74 20 75 73 69 6e  , to be.set usin
0fc0: 67 20 50 52 41 47 4d 41 20 73 74 61 74 65 6d 65  g PRAGMA stateme
0fd0: 6e 74 73 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54  nts..</p>..<p>.T
0fe0: 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
0ff0: 64 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  de() routine ret
1000: 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 63 6f  urns a result co
1010: 64 65 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 0a  de for the most.
1020: 72 65 63 65 6e 74 20 6d 61 6a 6f 72 20 41 50 49  recent major API
1030: 20 63 61 6c 6c 2e 20 20 73 71 6c 69 74 65 33 5f   call.  sqlite3_
1040: 65 72 72 6d 73 67 28 29 20 72 65 74 75 72 6e 73  errmsg() returns
1050: 20 61 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67   an English-lang
1060: 75 61 67 65 0a 74 65 78 74 20 65 72 72 6f 72 20  uage.text error 
1070: 6d 65 73 73 61 67 65 20 66 6f 72 20 74 68 65 20  message for the 
1080: 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f  most recent erro
1090: 72 2e 20 20 54 68 65 20 65 72 72 6f 72 20 6d 65  r.  The error me
10a0: 73 73 61 67 65 20 69 73 0a 72 65 70 72 65 73 65  ssage is.represe
10b0: 6e 74 65 64 20 69 6e 20 55 54 46 2d 38 20 61 6e  nted in UTF-8 an
10c0: 64 20 77 69 6c 6c 20 62 65 20 65 70 68 65 6d 65  d will be epheme
10d0: 72 61 6c 20 2d 20 69 74 20 63 6f 75 6c 64 20 64  ral - it could d
10e0: 69 73 61 70 70 65 61 72 20 6f 6e 0a 74 68 65 20  isappear on.the 
10f0: 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 61 6e 79  next call to any
1100: 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63   SQLite API func
1110: 74 69 6f 6e 2e 20 20 73 71 6c 69 74 65 33 5f 65  tion.  sqlite3_e
1120: 72 72 6d 73 67 31 36 28 29 20 77 6f 72 6b 73 20  rrmsg16() works 
1130: 6c 69 6b 65 0a 73 71 6c 69 74 65 33 5f 65 72 72  like.sqlite3_err
1140: 6d 73 67 28 29 20 65 78 63 65 70 74 20 74 68 61  msg() except tha
1150: 74 20 69 74 20 72 65 74 75 72 6e 73 20 74 68 65  t it returns the
1160: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 72   error message r
1170: 65 70 72 65 73 65 6e 74 65 64 0a 61 73 20 55 54  epresented.as UT
1180: 46 2d 31 36 20 69 6e 20 68 6f 73 74 20 6e 61 74  F-16 in host nat
1190: 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
11a0: 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 65 72  </p>..<p>.The er
11b0: 72 6f 72 20 63 6f 64 65 73 20 66 6f 72 20 53 51  ror codes for SQ
11c0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 61  Lite version 3 a
11d0: 72 65 20 75 6e 63 68 61 6e 67 65 64 20 66 72 6f  re unchanged fro
11e0: 6d 20 76 65 72 73 69 6f 6e 20 32 2e 0a 54 68 65  m version 2..The
11f0: 79 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73  y are as follows
1200: 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  :.</p>..<blockqu
1210: 6f 74 65 3e 3c 70 72 65 3e 0a 23 64 65 66 69 6e  ote><pre>.#defin
1220: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
1230: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
1240: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
1250: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1260: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20  _ERROR        1 
1270: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
1280: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
1290: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
12a0: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20  LITE_INTERNAL   
12b0: 20 20 32 20 20 20 2f 2a 20 41 6e 20 69 6e 74 65    2   /* An inte
12c0: 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72  rnal logic error
12d0: 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64   in SQLite */.#d
12e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52  efine SQLITE_PER
12f0: 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a  M         3   /*
1300: 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69   Access permissi
1310: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
1320: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
1330: 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20  T        4   /* 
1340: 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  Callback routine
1350: 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62   requested an ab
1360: 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ort */.#define S
1370: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20  QLITE_BUSY      
1380: 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61     5   /* The da
1390: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c  tabase file is l
13a0: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
13b0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20   SQLITE_LOCKED  
13c0: 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61       6   /* A ta
13d0: 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62  ble in the datab
13e0: 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ase is locked */
13f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1400: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20  NOMEM        7  
1410: 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66   /* A malloc() f
1420: 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ailed */.#define
1430: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
1440: 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65       8   /* Atte
1450: 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72  mpt to write a r
1460: 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65  eadonly database
1470: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1480: 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20  TE_INTERRUPT    
1490: 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  9   /* Operation
14a0: 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73   terminated by s
14b0: 71 6c 69 74 65 5f 69 6e 74 65 72 72 75 70 74 28  qlite_interrupt(
14c0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
14d0: 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20  ITE_IOERR       
14e0: 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e  10   /* Some kin
14f0: 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72  d of disk I/O er
1500: 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a  ror occurred */.
1510: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1520: 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20  ORRUPT     11   
1530: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
1540: 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61  disk image is ma
1550: 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69  lformed */.#defi
1560: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  ne SQLITE_NOTFOU
1570: 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 28 49  ND    12   /* (I
1580: 6e 74 65 72 6e 61 6c 20 4f 6e 6c 79 29 20 54 61  nternal Only) Ta
1590: 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f  ble or record no
15a0: 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69  t found */.#defi
15b0: 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20  ne SQLITE_FULL  
15c0: 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e        13   /* In
15d0: 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62  sertion failed b
15e0: 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20  ecause database 
15f0: 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69  is full */.#defi
1600: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
1610: 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e  EN    14   /* Un
1620: 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  able to open the
1630: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
1640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1650: 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20  _PROTOCOL    15 
1660: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f    /* Database lo
1670: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f  ck protocol erro
1680: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1690: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20  ITE_EMPTY       
16a0: 31 36 20 20 20 2f 2a 20 28 49 6e 74 65 72 6e 61  16   /* (Interna
16b0: 6c 20 4f 6e 6c 79 29 20 44 61 74 61 62 61 73 65  l Only) Database
16c0: 20 74 61 62 6c 65 20 69 73 20 65 6d 70 74 79 20   table is empty 
16d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16e0: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
16f0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
1700: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
1710: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
1720: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
1730: 31 38 20 20 20 2f 2a 20 54 6f 6f 20 6d 75 63 68  18   /* Too much
1740: 20 64 61 74 61 20 66 6f 72 20 6f 6e 65 20 72 6f   data for one ro
1750: 77 20 6f 66 20 61 20 74 61 62 6c 65 20 2a 2f 0a  w of a table */.
1760: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1770: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
1780: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
1790: 63 6f 6e 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  contraint violat
17a0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
17b0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
17c0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
17d0: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
17e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
17f0: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
1800: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
1810: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
1820: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
1830: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
1840: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
1850: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
1860: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
1870: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
1880: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
1890: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
18a0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
18b0: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
18c0: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
18d0: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
18e0: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
18f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1900: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
1910: 20 2f 2a 20 73 71 6c 69 74 65 5f 73 74 65 70 28   /* sqlite_step(
1920: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
1930: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 3c 2f 70 72  xecuting */.</pr
1940: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1950: 0a 3c 68 34 3e 32 2e 32 20 45 78 65 63 75 74 69  .<h4>2.2 Executi
1960: 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
1970: 73 3c 2f 68 34 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  s</h4>..<blockqu
1980: 6f 74 65 3e 3c 70 72 65 3e 0a 20 20 20 74 79 70  ote><pre>.   typ
1990: 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74  edef int (*sqlit
19a0: 65 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  e_callback)(void
19b0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
19c0: 61 72 2a 2a 29 3b 0a 20 20 20 69 6e 74 20 73 71  ar**);.   int sq
19d0: 6c 69 74 65 33 5f 65 78 65 63 28 73 71 6c 69 74  lite3_exec(sqlit
19e0: 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
19f0: 2a 73 71 6c 2c 20 73 71 6c 69 74 65 5f 63 61 6c  *sql, sqlite_cal
1a00: 6c 62 61 63 6b 2c 20 76 6f 69 64 2a 2c 20 63 68  lback, void*, ch
1a10: 61 72 2a 2a 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62  ar**);.</pre></b
1a20: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a  lockquote>..<p>.
1a30: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
1a40: 63 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 6f  c()] function wo
1a50: 72 6b 73 20 6d 75 63 68 20 61 73 20 69 74 20 64  rks much as it d
1a60: 69 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  id in SQLite ver
1a70: 73 69 6f 6e 20 32 2e 0a 5a 65 72 6f 20 6f 72 20  sion 2..Zero or 
1a80: 6d 6f 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  more SQL stateme
1a90: 6e 74 73 20 73 70 65 63 69 66 69 65 64 20 69 6e  nts specified in
1aa0: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1ab0: 6d 65 74 65 72 20 61 72 65 20 63 6f 6d 70 69 6c  meter are compil
1ac0: 65 64 0a 61 6e 64 20 65 78 65 63 75 74 65 64 2e  ed.and executed.
1ad0: 20 20 51 75 65 72 79 20 72 65 73 75 6c 74 73 20    Query results 
1ae0: 61 72 65 20 72 65 74 75 72 6e 65 64 20 74 6f 20  are returned to 
1af0: 61 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  a callback routi
1b00: 6e 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49 6e  ne..</p>..<p>.In
1b10: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1b20: 33 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  3, the sqlite3_e
1b30: 78 65 63 20 72 6f 75 74 69 6e 65 20 69 73 20 6a  xec routine is j
1b40: 75 73 74 20 61 20 77 72 61 70 70 65 72 20 61 72  ust a wrapper ar
1b50: 6f 75 6e 64 0a 63 61 6c 6c 73 20 74 6f 20 74 68  ound.calls to th
1b60: 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
1b70: 6d 65 6e 74 20 69 6e 74 65 72 66 61 63 65 2e 0a  ment interface..
1b80: 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  </p>..<blockquot
1b90: 65 3e 3c 70 72 65 3e 0a 20 20 20 74 79 70 65 64  e><pre>.   typed
1ba0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1bb0: 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
1bc0: 74 6d 74 3b 0a 20 20 20 69 6e 74 20 73 71 6c 69  tmt;.   int sqli
1bd0: 74 65 33 5f 70 72 65 70 61 72 65 28 73 71 6c 69  te3_prepare(sqli
1be0: 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  te3*, const char
1bf0: 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
1c00: 73 74 6d 74 2a 2a 2c 20 63 6f 6e 73 74 20 63 68  stmt**, const ch
1c10: 61 72 2a 2a 29 3b 0a 20 20 20 69 6e 74 20 73 71  ar**);.   int sq
1c20: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1c30: 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
1c40: 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  void*, int, sqli
1c50: 74 65 33 5f 73 74 6d 74 2a 2a 2c 20 63 6f 6e 73  te3_stmt**, cons
1c60: 74 20 76 6f 69 64 2a 2a 29 3b 0a 20 20 20 69 6e  t void**);.   in
1c70: 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
1c80: 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ze(sqlite3_stmt*
1c90: 29 3b 0a 20 20 20 69 6e 74 20 73 71 6c 69 74 65  );.   int sqlite
1ca0: 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
1cb0: 73 74 6d 74 2a 29 3b 0a 3c 2f 70 72 65 3e 3c 2f  stmt*);.</pre></
1cc0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e  blockquote>..<p>
1cd0: 0a 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65  .The sqlite3_pre
1ce0: 70 61 72 65 20 69 6e 74 65 72 66 61 63 65 20 63  pare interface c
1cf0: 6f 6d 70 69 6c 65 73 20 61 20 73 69 6e 67 6c 65  ompiles a single
1d00: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1d10: 6e 74 6f 20 62 79 74 65 20 63 6f 64 65 0a 66 6f  nto byte code.fo
1d20: 72 20 6c 61 74 65 72 20 65 78 65 63 75 74 69 6f  r later executio
1d30: 6e 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  n.  This interfa
1d40: 63 65 20 69 73 20 6e 6f 77 20 74 68 65 20 70 72  ce is now the pr
1d50: 65 66 65 72 72 65 64 20 77 61 79 20 6f 66 20 61  eferred way of a
1d60: 63 63 65 73 73 69 6e 67 0a 74 68 65 20 64 61 74  ccessing.the dat
1d70: 61 62 61 73 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e  abase..</p>..<p>
1d80: 0a 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65  .The SQL stateme
1d90: 6e 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  nt is a UTF-8 st
1da0: 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33  ring for sqlite3
1db0: 5f 70 72 65 70 61 72 65 28 29 2e 0a 54 68 65 20  _prepare()..The 
1dc0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1dd0: 36 28 29 20 77 6f 72 6b 73 20 74 68 65 20 73 61  6() works the sa
1de0: 6d 65 20 77 61 79 20 65 78 63 65 70 74 0a 74 68  me way except.th
1df0: 61 74 20 69 74 20 65 78 70 65 63 74 73 20 61 20  at it expects a 
1e00: 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 73  UTF-16 string as
1e10: 20 53 51 4c 20 69 6e 70 75 74 2e 0a 4f 6e 6c 79   SQL input..Only
1e20: 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
1e30: 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
1e40: 69 6e 70 75 74 20 73 74 72 69 6e 67 20 69 73 20  input string is 
1e50: 63 6f 6d 70 69 6c 65 64 2e 0a 54 68 65 20 66 69  compiled..The fi
1e60: 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
1e70: 20 66 69 6c 6c 65 64 20 69 6e 20 77 69 74 68 20   filled in with 
1e80: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1e90: 20 6e 65 78 74 20 28 75 6e 63 6f 6d 70 69 6c 65   next (uncompile
1ea0: 64 29 0a 53 51 4c 69 74 65 20 73 74 61 74 65 6d  d).SQLite statem
1eb0: 65 6e 74 20 69 6e 20 74 68 65 20 69 6e 70 75 74  ent in the input
1ec0: 20 73 74 72 69 6e 67 2c 20 69 66 20 61 6e 79 2e   string, if any.
1ed0: 0a 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  .The sqlite3_fin
1ee0: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
1ef0: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72  deallocates a pr
1f00: 65 70 61 72 65 64 20 53 51 4c 20 73 74 61 74 65  epared SQL state
1f10: 6d 65 6e 74 2e 0a 41 6c 6c 20 70 72 65 70 61 72  ment..All prepar
1f20: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 75  ed statements mu
1f30: 73 74 20 62 65 20 66 69 6e 61 6c 69 7a 65 64 20  st be finalized 
1f40: 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62  before the datab
1f50: 61 73 65 20 63 61 6e 20 62 65 0a 63 6c 6f 73 65  ase can be.close
1f60: 64 2e 0a 54 68 65 20 73 71 6c 69 74 65 33 5f 72  d..The sqlite3_r
1f70: 65 73 65 74 28 29 20 72 6f 75 74 69 6e 65 20 72  eset() routine r
1f80: 65 73 65 74 73 20 61 20 70 72 65 70 61 72 65 64  esets a prepared
1f90: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 73   SQL statement s
1fa0: 6f 20 74 68 61 74 20 69 74 0a 63 61 6e 20 62 65  o that it.can be
1fb0: 20 65 78 65 63 75 74 65 64 20 61 67 61 69 6e 2e   executed again.
1fc0: 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 53  .</p>..<p>.The S
1fd0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 79  QL statement may
1fe0: 20 63 6f 6e 74 61 69 6e 20 74 6f 6b 65 6e 73 20   contain tokens 
1ff0: 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
2000: 6f 72 20 22 3f 6e 6e 6e 22 20 6f 72 20 22 3a 61  or "?nnn" or ":a
2010: 61 61 22 0a 77 68 65 72 65 20 22 6e 6e 6e 22 20  aa".where "nnn" 
2020: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  is an integer an
2030: 64 20 22 61 61 61 22 20 69 73 20 61 6e 20 69 64  d "aaa" is an id
2040: 65 6e 74 69 66 69 65 72 2e 0a 53 75 63 68 20 74  entifier..Such t
2050: 6f 6b 65 6e 73 20 72 65 70 72 65 73 65 6e 74 20  okens represent 
2060: 75 6e 73 70 65 63 69 66 69 65 64 20 6c 69 74 65  unspecified lite
2070: 72 61 6c 20 76 61 6c 75 65 73 20 28 6f 72 20 22  ral values (or "
2080: 77 69 6c 64 63 61 72 64 73 22 29 0a 74 6f 20 62  wildcards").to b
2090: 65 20 66 69 6c 6c 65 64 20 69 6e 20 6c 61 74 65  e filled in late
20a0: 72 20 62 79 20 74 68 65 20 0a 5b 73 71 6c 69 74  r by the .[sqlit
20b0: 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
20c0: 69 74 65 33 5f 62 69 6e 64 5d 20 69 6e 74 65 72  ite3_bind] inter
20d0: 66 61 63 65 2e 0a 45 61 63 68 20 77 69 6c 64 63  face..Each wildc
20e0: 61 72 64 20 68 61 73 20 61 6e 20 61 73 73 6f 63  ard has an assoc
20f0: 69 61 74 65 64 20 6e 75 6d 62 65 72 20 77 68 69  iated number whi
2100: 63 68 20 69 73 20 69 74 73 20 73 65 71 75 65 6e  ch is its sequen
2110: 63 65 20 69 6e 20 74 68 65 0a 73 74 61 74 65 6d  ce in the.statem
2120: 65 6e 74 20 6f 72 20 74 68 65 20 22 6e 6e 6e 22  ent or the "nnn"
2130: 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
2140: 61 20 22 3f 6e 6e 6e 22 20 66 6f 72 6d 2e 20 0a  a "?nnn" form. .
2150: 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 66 6f  It is allowed fo
2160: 72 20 74 68 65 20 73 61 6d 65 20 77 69 6c 64 63  r the same wildc
2170: 61 72 64 0a 74 6f 20 6f 63 63 75 72 20 6d 6f 72  ard.to occur mor
2180: 65 20 74 68 61 6e 20 6f 6e 63 65 20 69 6e 20 74  e than once in t
2190: 68 65 20 73 61 6d 65 20 53 51 4c 20 73 74 61 74  he same SQL stat
21a0: 65 6d 65 6e 74 2c 20 69 6e 20 77 68 69 63 68 20  ement, in which 
21b0: 63 61 73 65 0a 61 6c 6c 20 69 6e 73 74 61 6e 63  case.all instanc
21c0: 65 20 6f 66 20 74 68 61 74 20 77 69 6c 64 63 61  e of that wildca
21d0: 72 64 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65  rd will be fille
21e0: 64 20 69 6e 20 77 69 74 68 20 74 68 65 20 73 61  d in with the sa
21f0: 6d 65 20 76 61 6c 75 65 2e 0a 55 6e 62 6f 75 6e  me value..Unboun
2200: 64 20 77 69 6c 64 63 61 72 64 73 20 68 61 76 65  d wildcards have
2210: 20 61 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c   a value of NULL
2220: 2e 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  ..</p>..<blockqu
2230: 6f 74 65 3e 3c 70 72 65 3e 0a 20 20 20 69 6e 74  ote><pre>.   int
2240: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2250: 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2260: 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2270: 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
2280: 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 20 20 20 69  *)(void*));.   i
2290: 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
22a0: 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
22b0: 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
22c0: 65 29 3b 0a 20 20 20 69 6e 74 20 73 71 6c 69 74  e);.   int sqlit
22d0: 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
22e0: 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
22f0: 69 6e 74 29 3b 0a 20 20 20 69 6e 74 20 73 71 6c  int);.   int sql
2300: 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
2310: 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2320: 6e 74 2c 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  nt, long long in
2330: 74 29 3b 0a 20 20 20 69 6e 74 20 73 71 6c 69 74  t);.   int sqlit
2340: 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
2350: 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
2360: 3b 0a 20 20 20 69 6e 74 20 73 71 6c 69 74 65 33  ;.   int sqlite3
2370: 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
2380: 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2390: 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
23a0: 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
23b0: 29 29 3b 0a 20 20 20 69 6e 74 20 73 71 6c 69 74  ));.   int sqlit
23c0: 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
23d0: 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23e0: 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
23f0: 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
2400: 6f 69 64 2a 29 29 3b 0a 20 20 20 69 6e 74 20 73  oid*));.   int s
2410: 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2420: 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2430: 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
2440: 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 3c 2f 70  te3_value*);.</p
2450: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
2460: 0a 0a 3c 70 3e 0a 54 68 65 72 65 20 69 73 20 61  ..<p>.There is a
2470: 6e 20 61 73 73 6f 72 74 6d 65 6e 74 20 6f 66 20  n assortment of 
2480: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 72 6f 75  sqlite3_bind rou
2490: 74 69 6e 65 73 20 75 73 65 64 20 74 6f 20 61 73  tines used to as
24a0: 73 69 67 6e 20 76 61 6c 75 65 73 0a 74 6f 20 77  sign values.to w
24b0: 69 6c 64 63 61 72 64 73 20 69 6e 20 61 20 70 72  ildcards in a pr
24c0: 65 70 61 72 65 64 20 53 51 4c 20 73 74 61 74 65  epared SQL state
24d0: 6d 65 6e 74 2e 20 20 55 6e 62 6f 75 6e 64 20 77  ment.  Unbound w
24e0: 69 6c 64 63 61 72 64 73 0a 61 72 65 20 69 6e 74  ildcards.are int
24f0: 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
2500: 73 2e 20 20 42 69 6e 64 69 6e 67 73 20 61 72 65  s.  Bindings are
2510: 20 6e 6f 74 20 72 65 73 65 74 20 62 79 20 73 71   not reset by sq
2520: 6c 69 74 65 33 5f 72 65 73 65 74 28 29 2e 0a 42  lite3_reset()..B
2530: 75 74 20 77 69 6c 64 63 61 72 64 73 20 63 61 6e  ut wildcards can
2540: 20 62 65 20 72 65 62 6f 75 6e 64 20 74 6f 20 6e   be rebound to n
2550: 65 77 20 76 61 6c 75 65 73 20 61 66 74 65 72 20  ew values after 
2560: 61 6e 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  an sqlite3_reset
2570: 28 29 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 41 66  ()..</p>..<p>.Af
2580: 74 65 72 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ter an SQL state
2590: 6d 65 6e 74 20 68 61 73 20 62 65 65 6e 20 70 72  ment has been pr
25a0: 65 70 61 72 65 64 20 28 61 6e 64 20 6f 70 74 69  epared (and opti
25b0: 6f 6e 61 6c 6c 79 20 62 6f 75 6e 64 29 2c 20 69  onally bound), i
25c0: 74 0a 69 73 20 65 78 65 63 75 74 65 64 20 75 73  t.is executed us
25d0: 69 6e 67 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63  ing:.</p>..<bloc
25e0: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 20 20 20  kquote><pre>.   
25f0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
2600: 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2610: 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75  .</pre></blockqu
2620: 6f 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65 20 73 71  ote>..<p>.The sq
2630: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 6f 75  lite3_step() rou
2640: 74 69 6e 65 20 72 65 74 75 72 6e 20 53 51 4c 49  tine return SQLI
2650: 54 45 5f 52 4f 57 20 69 66 20 69 74 20 69 73 20  TE_ROW if it is 
2660: 72 65 74 75 72 6e 69 6e 67 20 61 20 73 69 6e 67  returning a sing
2670: 6c 65 0a 72 6f 77 20 6f 66 20 74 68 65 20 72 65  le.row of the re
2680: 73 75 6c 74 20 73 65 74 2c 20 6f 72 20 53 51 4c  sult set, or SQL
2690: 49 54 45 5f 44 4f 4e 45 20 69 66 20 65 78 65 63  ITE_DONE if exec
26a0: 75 74 69 6f 6e 20 68 61 73 20 63 6f 6d 70 6c 65  ution has comple
26b0: 74 65 64 2c 20 65 69 74 68 65 72 0a 6e 6f 72 6d  ted, either.norm
26c0: 61 6c 6c 79 20 6f 72 20 64 75 65 20 74 6f 20 61  ally or due to a
26d0: 6e 20 65 72 72 6f 72 2e 20 20 49 74 20 6d 69 67  n error.  It mig
26e0: 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 53  ht also return S
26f0: 51 4c 49 54 45 5f 42 55 53 59 20 69 66 20 69 74  QLITE_BUSY if it
2700: 20 69 73 0a 75 6e 61 62 6c 65 20 74 6f 20 6f 70   is.unable to op
2710: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2720: 66 69 6c 65 2e 20 20 49 66 20 74 68 65 20 72 65  file.  If the re
2730: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 20 53 51  turn value is SQ
2740: 4c 49 54 45 5f 52 4f 57 2c 20 74 68 65 6e 0a 74  LITE_ROW, then.t
2750: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 72 6f 75  he following rou
2760: 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
2770: 64 20 74 6f 20 65 78 74 72 61 63 74 20 69 6e 66  d to extract inf
2780: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
2790: 68 61 74 20 72 6f 77 0a 6f 66 20 74 68 65 20 72  hat row.of the r
27a0: 65 73 75 6c 74 20 73 65 74 3a 0a 3c 2f 70 3e 0a  esult set:.</p>.
27b0: 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72  .<blockquote><pr
27c0: 65 3e 0a 20 20 20 63 6f 6e 73 74 20 76 6f 69 64  e>.   const void
27d0: 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
27e0: 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
27f0: 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2800: 20 20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63     int sqlite3_c
2810: 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
2820: 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2830: 43 6f 6c 29 3b 0a 20 20 20 69 6e 74 20 73 71 6c  Col);.   int sql
2840: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2850: 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
2860: 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 20 20  *, int iCol);.  
2870: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2880: 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
2890: 33 5f 73 74 6d 74 2a 29 3b 0a 20 20 20 63 6f 6e  3_stmt*);.   con
28a0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
28b0: 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
28c0: 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2c  (sqlite3_stmt *,
28d0: 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 20 20 20 63   int iCol);.   c
28e0: 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
28f0: 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2900: 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
2910: 74 20 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  t *, int iCol);.
2920: 20 20 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65     double sqlite
2930: 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
2940: 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2950: 6e 74 20 69 43 6f 6c 29 3b 0a 20 20 20 69 6e 74  nt iCol);.   int
2960: 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2970: 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2980: 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 20 20  *, int iCol);.  
2990: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
29a0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
29b0: 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
29c0: 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 20 20  *, int iCol);.  
29d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
29e0: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
29f0: 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a00: 69 6e 74 20 69 43 6f 6c 29 3b 0a 20 20 20 63 6f  int iCol);.   co
2a10: 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2a20: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2a30: 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a40: 6e 74 20 69 43 6f 6c 29 3b 0a 20 20 20 63 6f 6e  nt iCol);.   con
2a50: 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
2a60: 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2a70: 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2a80: 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a90: 20 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73     const void *s
2aa0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2ab0: 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2ac0: 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 20  t*, int iCol);. 
2ad0: 20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f    int sqlite3_co
2ae0: 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
2af0: 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2b00: 6c 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  l);.</pre></bloc
2b10: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65  kquote>..<p>.The
2b20: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2b30: 5f 63 6f 75 6e 74 28 29 5d 0a 66 75 6e 63 74 69  _count()].functi
2b40: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
2b50: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2b60: 20 69 6e 0a 74 68 65 20 72 65 73 75 6c 74 73 20   in.the results 
2b70: 73 65 74 2e 20 20 73 71 6c 69 74 65 33 5f 63 6f  set.  sqlite3_co
2b80: 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 63 61 6e  lumn_count() can
2b90: 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
2ba0: 79 20 74 69 6d 65 20 61 66 74 65 72 0a 5b 73 71  y time after.[sq
2bb0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2bc0: 28 29 5d 2e 20 20 5b 73 71 6c 69 74 65 33 5f 64  ()].  [sqlite3_d
2bd0: 61 74 61 5f 63 6f 75 6e 74 28 29 5d 20 77 6f 72  ata_count()] wor
2be0: 6b 73 20 73 69 6d 69 6c 61 72 6c 79 20 74 6f 0a  ks similarly to.
2bf0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2c00: 63 6f 75 6e 74 28 29 5d 20 65 78 63 65 70 74 20  count()] except 
2c10: 74 68 61 74 20 69 74 20 6f 6e 6c 79 20 77 6f 72  that it only wor
2c20: 6b 73 20 66 6f 6c 6c 6f 77 69 6e 67 20 5b 73 71  ks following [sq
2c30: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 49  lite3_step()]..I
2c40: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
2c50: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2c60: 73 74 65 70 28 29 5d 20 72 65 74 75 72 6e 65 64  step()] returned
2c70: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 6f 72 20   SQLITE_DONE or 
2c80: 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a 74  an error code,.t
2c90: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  hen [sqlite3_dat
2ca0: 61 5f 63 6f 75 6e 74 28 29 5d 20 77 69 6c 6c 20  a_count()] will 
2cb0: 72 65 74 75 72 6e 20 30 20 77 68 65 72 65 61 73  return 0 whereas
2cc0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2cd0: 5f 63 6f 75 6e 74 28 29 5d 20 77 69 6c 6c 0a 63  _count()] will.c
2ce0: 6f 6e 74 69 6e 75 65 20 74 6f 20 72 65 74 75 72  ontinue to retur
2cf0: 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
2d00: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2d10: 65 73 75 6c 74 20 73 65 74 2e 0a 3c 2f 70 3e 0a  esult set..</p>.
2d20: 0a 3c 70 3e 52 65 74 75 72 6e 65 64 20 64 61 74  .<p>Returned dat
2d30: 61 20 69 73 20 65 78 61 6d 69 6e 65 64 20 75 73  a is examined us
2d40: 69 6e 67 20 74 68 65 20 6f 74 68 65 72 20 0a 5b  ing the other .[
2d50: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d60: 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 63 6f 6c 75  lob|sqlite3_colu
2d70: 6d 6e 5f 2a 2a 2a 28 29 5d 20 66 75 6e 63 74 69  mn_***()] functi
2d80: 6f 6e 73 2c 20 0a 61 6c 6c 20 6f 66 20 77 68 69  ons, .all of whi
2d90: 63 68 20 74 61 6b 65 20 61 20 63 6f 6c 75 6d 6e  ch take a column
2da0: 20 6e 75 6d 62 65 72 20 61 73 20 74 68 65 69 72   number as their
2db0: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2dc0: 72 2e 20 43 6f 6c 75 6d 6e 73 20 61 72 65 0a 7a  r. Columns are.z
2dd0: 65 72 6f 2d 69 6e 64 65 78 65 64 20 66 72 6f 6d  ero-indexed from
2de0: 20 6c 65 66 74 20 74 6f 20 72 69 67 68 74 2e 20   left to right. 
2df0: 4e 6f 74 65 20 74 68 61 74 20 74 68 69 73 20 69  Note that this i
2e00: 73 20 64 69 66 66 65 72 65 6e 74 20 74 6f 20 70  s different to p
2e10: 61 72 61 6d 65 74 65 72 73 2c 0a 77 68 69 63 68  arameters,.which
2e20: 20 61 72 65 20 69 6e 64 65 78 65 64 20 73 74 61   are indexed sta
2e30: 72 74 69 6e 67 20 61 74 20 6f 6e 65 2e 0a 3c 2f  rting at one..</
2e40: 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 5b 73 71 6c  p>..<p>.The [sql
2e50: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2e60: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ()] function ret
2e70: 75 72 6e 73 20 74 68 65 0a 64 61 74 61 74 79 70  urns the.datatyp
2e80: 65 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 20  e for the value 
2e90: 69 6e 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  in the Nth colum
2ea0: 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  n.  The return v
2eb0: 61 6c 75 65 20 69 73 20 6f 6e 65 0a 6f 66 20 74  alue is one.of t
2ec0: 68 65 73 65 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f  hese:.</p>..<blo
2ed0: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 20 20  ckquote><pre>.  
2ee0: 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f   #define SQLITE_
2ef0: 49 4e 54 45 47 45 52 20 20 31 0a 20 20 20 23 64  INTEGER  1.   #d
2f00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
2f10: 41 54 20 20 20 20 32 0a 20 20 20 23 64 65 66 69  AT    2.   #defi
2f20: 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
2f30: 20 20 20 33 0a 20 20 20 23 64 65 66 69 6e 65 20     3.   #define 
2f40: 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
2f50: 34 0a 20 20 20 23 64 65 66 69 6e 65 20 53 51 4c  4.   #define SQL
2f60: 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 3c  ITE_NULL     5.<
2f70: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
2f80: 65 3e 0a 0a 3c 70 3e 0a 54 68 65 20 73 71 6c 69  e>..<p>.The sqli
2f90: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2fa0: 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
2fb0: 74 75 72 6e 73 20 74 65 78 74 20 77 68 69 63 68  turns text which
2fc0: 20 69 73 20 74 68 65 0a 64 65 63 6c 61 72 65 64   is the.declared
2fd0: 20 74 79 70 65 20 6f 66 20 74 68 65 20 63 6f 6c   type of the col
2fe0: 75 6d 6e 20 69 6e 20 74 68 65 20 43 52 45 41 54  umn in the CREAT
2ff0: 45 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65 6e  E TABLE statemen
3000: 74 2e 20 20 46 6f 72 20 61 6e 0a 65 78 70 72 65  t.  For an.expre
3010: 73 73 69 6f 6e 2c 20 74 68 65 20 72 65 74 75 72  ssion, the retur
3020: 6e 20 74 79 70 65 20 69 73 20 61 6e 20 65 6d 70  n type is an emp
3030: 74 79 20 73 74 72 69 6e 67 2e 20 20 73 71 6c 69  ty string.  sqli
3040: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
3050: 29 0a 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61  ).returns the na
3060: 6d 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f  me of the Nth co
3070: 6c 75 6d 6e 2e 20 20 73 71 6c 69 74 65 33 5f 63  lumn.  sqlite3_c
3080: 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
3090: 74 75 72 6e 73 0a 74 68 65 20 6e 75 6d 62 65 72  turns.the number
30a0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 61 20 63   of bytes in a c
30b0: 6f 6c 75 6d 6e 20 74 68 61 74 20 68 61 73 20 74  olumn that has t
30c0: 79 70 65 20 42 4c 4f 42 20 6f 72 20 74 68 65 20  ype BLOB or the 
30d0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
30e0: 69 6e 20 61 20 54 45 58 54 20 73 74 72 69 6e 67  in a TEXT string
30f0: 20 77 69 74 68 20 55 54 46 2d 38 20 65 6e 63 6f   with UTF-8 enco
3100: 64 69 6e 67 2e 20 20 73 71 6c 69 74 65 33 5f 63  ding.  sqlite3_c
3110: 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
3120: 72 65 74 75 72 6e 73 0a 74 68 65 20 73 61 6d 65  returns.the same
3130: 20 76 61 6c 75 65 20 66 6f 72 20 42 4c 4f 42 73   value for BLOBs
3140: 20 62 75 74 20 66 6f 72 20 54 45 58 54 20 73 74   but for TEXT st
3150: 72 69 6e 67 73 20 72 65 74 75 72 6e 73 20 74 68  rings returns th
3160: 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
3170: 73 0a 69 6e 20 61 20 55 54 46 2d 31 36 20 65 6e  s.in a UTF-16 en
3180: 63 6f 64 69 6e 67 2e 0a 73 71 6c 69 74 65 33 5f  coding..sqlite3_
3190: 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 72 65  column_blob() re
31a0: 74 75 72 6e 20 42 4c 4f 42 20 64 61 74 61 2e 20  turn BLOB data. 
31b0: 20 0a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   .sqlite3_column
31c0: 5f 74 65 78 74 28 29 20 72 65 74 75 72 6e 20 54  _text() return T
31d0: 45 58 54 20 64 61 74 61 20 61 73 20 55 54 46 2d  EXT data as UTF-
31e0: 38 2e 0a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  8..sqlite3_colum
31f0: 6e 5f 74 65 78 74 31 36 28 29 20 72 65 74 75 72  n_text16() retur
3200: 6e 20 54 45 58 54 20 64 61 74 61 20 61 73 20 55  n TEXT data as U
3210: 54 46 2d 31 36 2e 0a 73 71 6c 69 74 65 33 5f 63  TF-16..sqlite3_c
3220: 6f 6c 75 6d 6e 5f 69 6e 74 28 29 20 72 65 74 75  olumn_int() retu
3230: 72 6e 20 49 4e 54 45 47 45 52 20 64 61 74 61 20  rn INTEGER data 
3240: 69 6e 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  in the host mach
3250: 69 6e 65 73 20 6e 61 74 69 76 65 0a 69 6e 74 65  ines native.inte
3260: 67 65 72 20 66 6f 72 6d 61 74 2e 0a 73 71 6c 69  ger format..sqli
3270: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
3280: 28 29 20 72 65 74 75 72 6e 73 20 36 34 2d 62 69  () returns 64-bi
3290: 74 20 49 4e 54 45 47 45 52 20 64 61 74 61 2e 0a  t INTEGER data..
32a0: 46 69 6e 61 6c 6c 79 2c 20 73 71 6c 69 74 65 33  Finally, sqlite3
32b0: 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 29  _column_double()
32c0: 20 72 65 74 75 72 6e 20 66 6c 6f 61 74 69 6e 67   return floating
32d0: 20 70 6f 69 6e 74 20 64 61 74 61 2e 0a 3c 2f 70   point data..</p
32e0: 3e 0a 0a 3c 70 3e 0a 49 74 20 69 73 20 6e 6f 74  >..<p>.It is not
32f0: 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 72 65   necessary to re
3300: 74 72 69 65 76 65 20 64 61 74 61 20 69 6e 20 74  trieve data in t
3310: 68 65 20 66 6f 72 6d 61 74 20 73 70 65 63 69 66  he format specif
3320: 79 20 62 79 0a 73 71 6c 69 74 65 33 5f 63 6f 6c  y by.sqlite3_col
3330: 75 6d 6e 5f 74 79 70 65 28 29 2e 20 20 49 66 20  umn_type().  If 
3340: 61 20 64 69 66 66 65 72 65 6e 74 20 66 6f 72 6d  a different form
3350: 61 74 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  at is requested,
3360: 20 74 68 65 20 64 61 74 61 0a 69 73 20 63 6f 6e   the data.is con
3370: 76 65 72 74 65 64 20 61 75 74 6f 6d 61 74 69 63  verted automatic
3380: 61 6c 6c 79 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a  ally..</p>..<p>.
3390: 44 61 74 61 20 66 6f 72 6d 61 74 20 63 6f 6e 76  Data format conv
33a0: 65 72 73 69 6f 6e 73 20 63 61 6e 20 69 6e 76 61  ersions can inva
33b0: 6c 69 64 61 74 65 20 74 68 65 20 70 6f 69 6e 74  lidate the point
33c0: 65 72 20 72 65 74 75 72 6e 65 64 20 62 79 0a 70  er returned by.p
33d0: 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71  rior calls to sq
33e0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
33f0: 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
3400: 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
3410: 6f 72 0a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or.sqlite3_colum
3420: 6e 5f 74 65 78 74 31 36 28 29 2e 20 20 50 6f 69  n_text16().  Poi
3430: 6e 74 65 72 73 20 6d 69 67 68 74 20 62 65 20 69  nters might be i
3440: 6e 76 61 6c 69 64 65 64 20 69 6e 20 74 68 65 20  nvalided in the 
3450: 66 6f 6c 6c 6f 77 69 6e 67 0a 63 61 73 65 73 3a  following.cases:
3460: 0a 3c 2f 70 3e 0a 3c 75 6c 3e 0a 3c 6c 69 3e 3c  .</p>.<ul>.<li><
3470: 70 3e 0a 54 68 65 20 69 6e 69 74 69 61 6c 20 63  p>.The initial c
3480: 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
3490: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
34a0: 75 6d 6e 5f 74 65 78 74 28 29 20 0a 6f 72 20 73  umn_text() .or s
34b0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
34c0: 78 74 31 36 28 29 0a 69 73 20 63 61 6c 6c 65 64  xt16().is called
34d0: 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
34e0: 61 74 6f 72 20 6d 69 67 68 74 20 6e 65 65 64 20  ator might need 
34f0: 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
3500: 68 65 20 73 74 72 69 6e 67 2e 0a 3c 2f 70 3e 3c  he string..</p><
3510: 2f 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e 0a 54 68 65  /li>.<li><p>.The
3520: 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
3530: 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
3540: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
3550: 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 73  n_bytes16() or.s
3560: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
3570: 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
3580: 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
3590: 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
35a0: 20 74 6f 20 55 54 46 2d 31 36 2e 0a 3c 2f 70 3e   to UTF-16..</p>
35b0: 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e 0a 54 68  </li>.<li><p>.Th
35c0: 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
35d0: 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
35e0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
35f0: 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 73  umn_bytes() or.s
3600: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
3610: 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
3620: 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
3630: 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
3640: 6f 20 55 54 46 2d 38 2e 0a 3c 2f 70 3e 3c 2f 6c  o UTF-8..</p></l
3650: 69 3e 0a 3c 2f 75 6c 3e 0a 3c 70 3e 0a 4e 6f 74  i>.</ul>.<p>.Not
3660: 65 20 74 68 61 74 20 63 6f 6e 76 65 72 73 69 6f  e that conversio
3670: 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
3680: 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
3690: 20 0a 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e   .are always don
36a0: 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
36b0: 6f 0a 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  o.not invalidate
36c0: 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
36d0: 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
36e0: 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
36f0: 66 20 74 68 65 20 62 75 66 66 65 72 0a 74 68 61  f the buffer.tha
3700: 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
3710: 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69  ter points to wi
3720: 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
3730: 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
3740: 6e 64 73 0a 6f 66 20 63 6f 6e 76 65 72 73 69 6f  nds.of conversio
3750: 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
3760: 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
3770: 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
3780: 65 74 69 6d 65 20 69 74 20 69 73 0a 6e 6f 74 20  etime it is.not 
3790: 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
37a0: 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
37b0: 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
37c0: 6e 76 61 6c 69 64 61 74 65 64 2e 20 20 0a 3c 2f  nvalidated.  .</
37d0: 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 73 61 66 65  p>..<p>.The safe
37e0: 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
37f0: 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
3800: 79 20 69 73 20 74 68 69 73 3a 20 61 73 73 75 6d  y is this: assum
3810: 65 20 74 68 61 74 20 61 6e 79 0a 72 65 73 75 6c  e that any.resul
3820: 74 20 66 72 6f 6d 0a 3c 75 6c 3e 0a 3c 6c 69 3e  t from.<ul>.<li>
3830: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
3840: 6c 6f 62 28 29 2c 3c 2f 6c 69 3e 0a 3c 6c 69 3e  lob(),</li>.<li>
3850: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3860: 65 78 74 28 29 2c 20 6f 72 3c 2f 6c 69 3e 0a 3c  ext(), or</li>.<
3870: 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
3880: 6e 5f 74 65 78 74 31 36 28 29 3c 2f 6c 69 3e 0a  n_text16()</li>.
3890: 3c 2f 75 6c 3e 0a 69 73 20 69 6e 76 61 6c 69 64  </ul>.is invalid
38a0: 65 64 20 62 79 20 73 75 62 73 65 71 75 65 6e 74  ed by subsequent
38b0: 20 63 61 6c 6c 73 20 74 6f 20 0a 3c 75 6c 3e 0a   calls to .<ul>.
38c0: 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
38d0: 6d 6e 5f 62 79 74 65 73 28 29 2c 3c 2f 6c 69 3e  mn_bytes(),</li>
38e0: 0a 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  .<li>sqlite3_col
38f0: 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 3c 2f  umn_bytes16(),</
3900: 6c 69 3e 0a 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  li>.<li>sqlite3_
3910: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 6f  column_text(), o
3920: 72 3c 2f 6c 69 3e 0a 3c 6c 69 3e 73 71 6c 69 74  r</li>.<li>sqlit
3930: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
3940: 28 29 2e 3c 2f 6c 69 3e 0a 3c 2f 75 6c 3e 0a 54  ().</li>.</ul>.T
3950: 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 79  his means that y
3960: 6f 75 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  ou should always
3970: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
3980: 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
3990: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
39a0: 79 74 65 73 31 36 28 29 20 3c 75 3e 62 65 66 6f  ytes16() <u>befo
39b0: 72 65 3c 2f 75 3e 20 63 61 6c 6c 69 6e 67 20 73  re</u> calling s
39c0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
39d0: 6f 62 28 29 2c 0a 73 71 6c 69 74 65 33 5f 63 6f  ob(),.sqlite3_co
39e0: 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 6f 72 20  lumn_text(), or 
39f0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3a00: 65 78 74 31 36 28 29 2e 0a 3c 2f 70 3e 0a 0a 3c  ext16()..</p>..<
3a10: 68 34 3e 32 2e 33 20 55 73 65 72 2d 64 65 66 69  h4>2.3 User-defi
3a20: 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 3c 2f 68  ned functions</h
3a30: 34 3e 0a 0a 3c 70 3e 0a 55 73 65 72 20 64 65 66  4>..<p>.User def
3a40: 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 63  ined functions c
3a50: 61 6e 20 62 65 20 63 72 65 61 74 65 64 20 75 73  an be created us
3a60: 69 6e 67 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ing the followin
3a70: 67 20 72 6f 75 74 69 6e 65 3a 0a 3c 2f 70 3e 0a  g routine:.</p>.
3a80: 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72  .<blockquote><pr
3a90: 65 3e 0a 20 20 20 74 79 70 65 64 65 66 20 73 74  e>.   typedef st
3aa0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  ruct sqlite3_val
3ab0: 75 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ue sqlite3_value
3ac0: 3b 0a 20 20 20 69 6e 74 20 73 71 6c 69 74 65 33  ;.   int sqlite3
3ad0: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
3ae0: 28 0a 20 20 20 20 20 73 71 6c 69 74 65 33 20 2a  (.     sqlite3 *
3af0: 2c 0a 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61  ,.     const cha
3b00: 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
3b10: 2c 0a 20 20 20 20 20 69 6e 74 20 6e 41 72 67 2c  ,.     int nArg,
3b20: 0a 20 20 20 20 20 69 6e 74 20 65 54 65 78 74 52  .     int eTextR
3b30: 65 70 2c 0a 20 20 20 20 20 76 6f 69 64 2a 2c 0a  ep,.     void*,.
3b40: 20 20 20 20 20 76 6f 69 64 20 28 2a 78 46 75 6e       void (*xFun
3b50: 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
3b60: 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
3b70: 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 76  value**),.     v
3b80: 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
3b90: 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
3ba0: 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
3bb0: 2a 29 2c 0a 20 20 20 20 20 76 6f 69 64 20 28 2a  *),.     void (*
3bc0: 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
3bd0: 63 6f 6e 74 65 78 74 2a 29 0a 20 20 20 29 3b 0a  context*).   );.
3be0: 20 20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63     int sqlite3_c
3bf0: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
3c00: 28 0a 20 20 20 20 20 73 71 6c 69 74 65 33 2a 2c  (.     sqlite3*,
3c10: 0a 20 20 20 20 20 63 6f 6e 73 74 20 76 6f 69 64  .     const void
3c20: 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
3c30: 0a 20 20 20 20 20 69 6e 74 20 6e 41 72 67 2c 0a  .     int nArg,.
3c40: 20 20 20 20 20 69 6e 74 20 65 54 65 78 74 52 65       int eTextRe
3c50: 70 2c 0a 20 20 20 20 20 76 6f 69 64 2a 2c 0a 20  p,.     void*,. 
3c60: 20 20 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63      void (*xFunc
3c70: 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
3c80: 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
3c90: 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 76 6f  alue**),.     vo
3ca0: 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
3cb0: 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
3cc0: 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
3cd0: 29 2c 0a 20 20 20 20 20 76 6f 69 64 20 28 2a 78  ),.     void (*x
3ce0: 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
3cf0: 6f 6e 74 65 78 74 2a 29 0a 20 20 20 29 3b 0a 20  ontext*).   );. 
3d00: 20 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45    #define SQLITE
3d10: 5f 55 54 46 38 20 20 20 20 20 31 0a 20 20 20 23  _UTF8     1.   #
3d20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
3d30: 46 31 36 20 20 20 20 32 0a 20 20 20 23 64 65 66  F16    2.   #def
3d40: 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
3d50: 42 45 20 20 33 0a 20 20 20 23 64 65 66 69 6e 65  BE  3.   #define
3d60: 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
3d70: 20 34 0a 20 20 20 23 64 65 66 69 6e 65 20 53 51   4.   #define SQ
3d80: 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 35 0a  LITE_ANY      5.
3d90: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
3da0: 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65 20 6e 41 72  te>..<p>.The nAr
3db0: 67 20 70 61 72 61 6d 65 74 65 72 20 73 70 65 63  g parameter spec
3dc0: 69 66 69 65 73 20 74 68 65 20 6e 75 6d 62 65 72  ifies the number
3dd0: 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   of arguments to
3de0: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 41   the function..A
3df0: 20 76 61 6c 75 65 20 6f 66 20 30 20 69 6e 64 69   value of 0 indi
3e00: 63 61 74 65 73 20 74 68 61 74 20 61 6e 79 20 6e  cates that any n
3e10: 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
3e20: 74 73 20 69 73 20 61 6c 6c 6f 77 65 64 2e 20 20  ts is allowed.  
3e30: 54 68 65 0a 65 54 65 78 74 52 65 70 20 70 61 72  The.eTextRep par
3e40: 61 6d 65 74 65 72 20 73 70 65 63 69 66 69 65 73  ameter specifies
3e50: 20 77 68 61 74 20 72 65 70 72 65 73 65 6e 74 61   what representa
3e60: 74 69 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73  tion text values
3e70: 20 61 72 65 20 65 78 70 65 63 74 65 64 0a 74 6f   are expected.to
3e80: 20 62 65 20 69 6e 20 66 6f 72 20 61 72 67 75 6d   be in for argum
3e90: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ents to this fun
3ea0: 63 74 69 6f 6e 2e 20 20 54 68 65 20 76 61 6c 75  ction.  The valu
3eb0: 65 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d 65  e of this parame
3ec0: 74 65 72 20 73 68 6f 75 6c 64 0a 62 65 20 6f 6e  ter should.be on
3ed0: 65 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  e of the paramet
3ee0: 65 72 73 20 64 65 66 69 6e 65 64 20 61 62 6f 76  ers defined abov
3ef0: 65 2e 20 20 53 51 4c 69 74 65 20 76 65 72 73 69  e.  SQLite versi
3f00: 6f 6e 20 33 20 61 6c 6c 6f 77 73 20 6d 75 6c 74  on 3 allows mult
3f10: 69 70 6c 65 0a 69 6d 70 6c 65 6d 65 6e 74 61 74  iple.implementat
3f20: 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
3f30: 20 66 75 6e 63 74 69 6f 6e 20 75 73 69 6e 67 20   function using 
3f40: 64 69 66 66 65 72 65 6e 74 20 74 65 78 74 20 72  different text r
3f50: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 73 2e 0a  epresentations..
3f60: 54 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  The database eng
3f70: 69 6e 65 20 63 68 6f 6f 73 65 73 20 74 68 65 20  ine chooses the 
3f80: 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
3f90: 6e 69 6d 69 7a 61 74 69 6f 6e 20 74 68 65 20 6e  nimization the n
3fa0: 75 6d 62 65 72 0a 6f 66 20 74 65 78 74 20 63 6f  umber.of text co
3fb0: 6e 76 65 72 73 69 6f 6e 73 20 72 65 71 75 69 72  nversions requir
3fc0: 65 64 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 4e 6f  ed..</p>..<p>.No
3fd0: 72 6d 61 6c 20 66 75 6e 63 74 69 6f 6e 73 20 73  rmal functions s
3fe0: 70 65 63 69 66 79 20 6f 6e 6c 79 20 78 46 75 6e  pecify only xFun
3ff0: 63 20 61 6e 64 20 6c 65 61 76 65 20 78 53 74 65  c and leave xSte
4000: 70 20 61 6e 64 20 78 46 69 6e 61 6c 20 73 65 74  p and xFinal set
4010: 20 74 6f 20 4e 55 4c 4c 2e 0a 41 67 67 72 65 67   to NULL..Aggreg
4020: 61 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 73 70  ate functions sp
4030: 65 63 69 66 79 20 78 53 74 65 70 20 61 6e 64 20  ecify xStep and 
4040: 78 46 69 6e 61 6c 20 61 6e 64 20 6c 65 61 76 65  xFinal and leave
4050: 20 78 46 75 6e 63 20 73 65 74 20 74 6f 20 4e 55   xFunc set to NU
4060: 4c 4c 2e 0a 54 68 65 72 65 20 69 73 20 6e 6f 20  LL..There is no 
4070: 73 65 70 61 72 61 74 65 20 73 71 6c 69 74 65 33  separate sqlite3
4080: 5f 63 72 65 61 74 65 5f 61 67 67 72 65 67 61 74  _create_aggregat
4090: 65 28 29 20 41 50 49 2e 0a 3c 2f 70 3e 0a 0a 3c  e() API..</p>..<
40a0: 70 3e 0a 54 68 65 20 66 75 6e 63 74 69 6f 6e 20  p>.The function 
40b0: 6e 61 6d 65 20 69 73 20 73 70 65 63 69 66 69 65  name is specifie
40c0: 64 20 69 6e 20 55 54 46 2d 38 2e 20 20 41 20 73  d in UTF-8.  A s
40d0: 65 70 61 72 61 74 65 20 73 71 6c 69 74 65 33 5f  eparate sqlite3_
40e0: 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
40f0: 36 28 29 0a 41 50 49 20 77 6f 72 6b 73 20 74 68  6().API works th
4100: 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65  e same as sqlite
4110: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
4120: 28 29 0a 65 78 63 65 70 74 20 74 68 61 74 20 74  ().except that t
4130: 68 65 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65  he function name
4140: 20 69 73 20 73 70 65 63 69 66 69 65 64 20 69 6e   is specified in
4150: 20 55 54 46 2d 31 36 20 68 6f 73 74 20 62 79 74   UTF-16 host byt
4160: 65 20 6f 72 64 65 72 2e 0a 3c 2f 70 3e 0a 0a 3c  e order..</p>..<
4170: 70 3e 0a 4e 6f 74 69 63 65 20 74 68 61 74 20 74  p>.Notice that t
4180: 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  he parameters to
4190: 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 6e   functions are n
41a0: 6f 77 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ow pointers to s
41b0: 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 73 74 72  qlite3_value.str
41c0: 75 63 74 75 72 65 73 20 69 6e 73 74 65 61 64 20  uctures instead 
41d0: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
41e0: 74 72 69 6e 67 73 20 61 73 20 69 6e 20 53 51 4c  trings as in SQL
41f0: 69 74 65 20 76 65 72 73 69 6f 6e 20 32 2e 58 2e  ite version 2.X.
4200: 0a 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 72  .The following r
4210: 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
4220: 20 74 6f 20 65 78 74 72 61 63 74 20 75 73 65 66   to extract usef
4230: 75 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 66  ul information f
4240: 72 6f 6d 20 74 68 65 73 65 0a 22 76 61 6c 75 65  rom these."value
4250: 73 22 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b  s":.</p>..<block
4260: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 20 20 20 63  quote><pre>.   c
4270: 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
4280: 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
4290: 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 20  lite3_value*);. 
42a0: 20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61    int sqlite3_va
42b0: 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
42c0: 33 5f 76 61 6c 75 65 2a 29 3b 0a 20 20 20 69 6e  3_value*);.   in
42d0: 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
42e0: 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
42f0: 76 61 6c 75 65 2a 29 3b 0a 20 20 20 64 6f 75 62  value*);.   doub
4300: 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
4310: 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
4320: 76 61 6c 75 65 2a 29 3b 0a 20 20 20 69 6e 74 20  value*);.   int 
4330: 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
4340: 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
4350: 29 3b 0a 20 20 20 6c 6f 6e 67 20 6c 6f 6e 67 20  );.   long long 
4360: 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
4370: 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
4380: 76 61 6c 75 65 2a 29 3b 0a 20 20 20 63 6f 6e 73  value*);.   cons
4390: 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
43a0: 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
43b0: 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
43c0: 65 2a 29 3b 0a 20 20 20 63 6f 6e 73 74 20 76 6f  e*);.   const vo
43d0: 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
43e0: 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
43f0: 5f 76 61 6c 75 65 2a 29 3b 0a 20 20 20 69 6e 74  _value*);.   int
4400: 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
4410: 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
4420: 65 2a 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  e*);.</pre></blo
4430: 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 46 75  ckquote>..<p>.Fu
4440: 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
4450: 61 74 69 6f 6e 73 20 75 73 65 20 74 68 65 20 66  ations use the f
4460: 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 73 20 74 6f  ollowing APIs to
4470: 20 61 63 71 75 69 72 65 20 63 6f 6e 74 65 78 74   acquire context
4480: 20 61 6e 64 0a 74 6f 20 72 65 70 6f 72 74 20 72   and.to report r
4490: 65 73 75 6c 74 73 3a 0a 3c 2f 70 3e 0a 0a 3c 62  esults:.</p>..<b
44a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
44b0: 20 20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33     void *sqlite3
44c0: 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
44d0: 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
44e0: 78 74 2a 2c 20 69 6e 74 20 6e 62 79 74 65 29 3b  xt*, int nbyte);
44f0: 0a 20 20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  .   void *sqlite
4500: 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
4510: 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 20  te3_context*);. 
4520: 20 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72    void sqlite3_r
4530: 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
4540: 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
4550: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
4560: 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
4570: 3b 0a 20 20 20 76 6f 69 64 20 73 71 6c 69 74 65  ;.   void sqlite
4580: 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
4590: 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
45a0: 2c 20 64 6f 75 62 6c 65 29 3b 0a 20 20 20 76 6f  , double);.   vo
45b0: 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
45c0: 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
45d0: 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
45e0: 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 20 20 20  char*, int);.   
45f0: 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
4600: 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69  ult_error16(sqli
4610: 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
4620: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  nst void*, int);
4630: 0a 20 20 20 76 6f 69 64 20 73 71 6c 69 74 65 33  .   void sqlite3
4640: 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
4650: 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
4660: 74 29 3b 0a 20 20 20 76 6f 69 64 20 73 71 6c 69  t);.   void sqli
4670: 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
4680: 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
4690: 2a 2c 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  *, long long int
46a0: 29 3b 0a 20 20 20 76 6f 69 64 20 73 71 6c 69 74  );.   void sqlit
46b0: 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
46c0: 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
46d0: 3b 0a 20 20 20 76 6f 69 64 20 73 71 6c 69 74 65  ;.   void sqlite
46e0: 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
46f0: 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
4700: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
4710: 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
4720: 2a 29 29 3b 0a 20 20 20 76 6f 69 64 20 73 71 6c  *));.   void sql
4730: 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
4740: 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
4750: 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
4760: 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
4770: 28 76 6f 69 64 2a 29 29 3b 0a 20 20 20 76 6f 69  (void*));.   voi
4780: 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
4790: 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63  _value(sqlite3_c
47a0: 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
47b0: 5f 76 61 6c 75 65 2a 29 3b 0a 20 20 20 76 6f 69  _value*);.   voi
47c0: 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
47d0: 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
47e0: 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20  ontext*, int);. 
47f0: 20 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73    void sqlite3_s
4800: 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
4810: 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
4820: 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
4830: 29 28 76 6f 69 64 2a 29 29 3b 0a 3c 2f 70 72 65  )(void*));.</pre
4840: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  ></blockquote>..
4850: 3c 68 34 3e 32 2e 34 20 55 73 65 72 2d 64 65 66  <h4>2.4 User-def
4860: 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 73  ined collating s
4870: 65 71 75 65 6e 63 65 73 3c 2f 68 34 3e 0a 0a 3c  equences</h4>..<
4880: 70 3e 0a 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  p>.The following
4890: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
48a0: 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
48b0: 75 73 65 72 2d 64 65 66 69 6e 65 64 0a 63 6f 6c  user-defined.col
48c0: 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 73  lating sequences
48d0: 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  :.</p>..<blockqu
48e0: 6f 74 65 3e 3c 70 72 65 3e 0a 20 20 20 73 71 6c  ote><pre>.   sql
48f0: 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
4900: 61 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20  ation(sqlite3*, 
4910: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
4920: 65 2c 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  e, int eTextRep,
4930: 20 76 6f 69 64 2a 2c 0a 20 20 20 20 20 20 69 6e   void*,.      in
4940: 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
4950: 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
4960: 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
4970: 64 2a 29 29 3b 0a 20 20 20 73 71 6c 69 74 65 33  d*));.   sqlite3
4980: 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
4990: 6e 31 36 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f  n16(sqlite3*, co
49a0: 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
49b0: 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 76   int eTextRep, v
49c0: 6f 69 64 2a 2c 0a 20 20 20 20 20 20 69 6e 74 28  oid*,.      int(
49d0: 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
49e0: 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
49f0: 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
4a00: 29 29 3b 0a 20 20 20 73 71 6c 69 74 65 33 5f 63  ));.   sqlite3_c
4a10: 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
4a20: 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 2a 2c  sqlite3*, void*,
4a30: 20 0a 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28   .      void(*)(
4a40: 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
4a50: 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
4a60: 74 20 63 68 61 72 2a 29 29 3b 0a 20 20 20 73 71  t char*));.   sq
4a70: 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
4a80: 6e 65 65 64 65 64 31 36 28 73 71 6c 69 74 65 33  needed16(sqlite3
4a90: 2a 2c 20 76 6f 69 64 2a 2c 0a 20 20 20 20 20 20  *, void*,.      
4aa0: 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
4ab0: 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
4ac0: 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
4ad0: 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  );.</pre></block
4ae0: 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65 20  quote>..<p>.The 
4af0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
4b00: 6f 6c 6c 61 74 69 6f 6e 28 29 20 66 75 6e 63 74  ollation() funct
4b10: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
4b20: 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
4b30: 63 65 20 6e 61 6d 65 0a 61 6e 64 20 61 20 63 6f  ce name.and a co
4b40: 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
4b50: 6e 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  n to implement t
4b60: 68 61 74 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65  hat collating se
4b70: 71 75 65 6e 63 65 2e 20 20 54 68 65 0a 63 6f 6d  quence.  The.com
4b80: 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e  parison function
4b90: 20 69 73 20 6f 6e 6c 79 20 75 73 65 64 20 66 6f   is only used fo
4ba0: 72 20 63 6f 6d 70 61 72 69 6e 67 20 74 65 78 74  r comparing text
4bb0: 20 76 61 6c 75 65 73 2e 20 20 54 68 65 20 65 54   values.  The eT
4bc0: 65 78 74 52 65 70 0a 70 61 72 61 6d 65 74 65 72  extRep.parameter
4bd0: 20 69 73 20 6f 6e 65 20 6f 66 20 53 51 4c 49 54   is one of SQLIT
4be0: 45 5f 55 54 46 38 2c 20 53 51 4c 49 54 45 5f 55  E_UTF8, SQLITE_U
4bf0: 54 46 31 36 4c 45 2c 20 53 51 4c 49 54 45 5f 55  TF16LE, SQLITE_U
4c00: 54 46 31 36 42 45 2c 20 6f 72 0a 53 51 4c 49 54  TF16BE, or.SQLIT
4c10: 45 5f 41 4e 59 20 74 6f 20 73 70 65 63 69 66 79  E_ANY to specify
4c20: 20 77 68 69 63 68 20 74 65 78 74 20 72 65 70 72   which text repr
4c30: 65 73 65 6e 74 61 74 69 6f 6e 20 74 68 65 20 63  esentation the c
4c40: 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
4c50: 6f 6e 20 77 6f 72 6b 73 0a 77 69 74 68 2e 20 20  on works.with.  
4c60: 53 65 70 61 72 61 74 65 20 63 6f 6d 70 61 72 69  Separate compari
4c70: 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 63 61  son functions ca
4c80: 6e 20 65 78 69 73 74 20 66 6f 72 20 74 68 65 20  n exist for the 
4c90: 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6e 67 0a 73  same collating.s
4ca0: 65 71 75 65 6e 63 65 20 66 6f 72 20 65 61 63 68  equence for each
4cb0: 20 6f 66 20 74 68 65 20 55 54 46 2d 38 2c 20 55   of the UTF-8, U
4cc0: 54 46 2d 31 36 4c 45 20 61 6e 64 20 55 54 46 2d  TF-16LE and UTF-
4cd0: 31 36 42 45 20 74 65 78 74 20 72 65 70 72 65 73  16BE text repres
4ce0: 65 6e 74 61 74 69 6f 6e 73 2e 0a 54 68 65 20 73  entations..The s
4cf0: 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
4d00: 6c 6c 61 74 69 6f 6e 31 36 28 29 20 77 6f 72 6b  llation16() work
4d10: 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
4d20: 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
4d30: 29 20 65 78 63 65 70 74 0a 74 68 61 74 20 74 68  ) except.that th
4d40: 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65  e collation name
4d50: 20 69 73 20 73 70 65 63 69 66 69 65 64 20 69 6e   is specified in
4d60: 20 55 54 46 2d 31 36 20 68 6f 73 74 20 62 79 74   UTF-16 host byt
4d70: 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20  e order instead 
4d80: 6f 66 0a 69 6e 20 55 54 46 2d 38 2e 0a 3c 2f 70  of.in UTF-8..</p
4d90: 3e 0a 0a 3c 70 3e 0a 54 68 65 20 73 71 6c 69 74  >..<p>.The sqlit
4da0: 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
4db0: 64 65 64 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ded() routine re
4dc0: 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
4dd0: 63 6b 20 77 68 69 63 68 20 74 68 65 0a 64 61 74  ck which the.dat
4de0: 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 69 6c  abase engine wil
4df0: 6c 20 69 6e 76 6f 6b 65 20 69 66 20 69 74 20 65  l invoke if it e
4e00: 6e 63 6f 75 6e 74 65 72 73 20 61 6e 20 75 6e 6b  ncounters an unk
4e10: 6e 6f 77 6e 20 63 6f 6c 6c 61 74 69 6e 67 20 73  nown collating s
4e20: 65 71 75 65 6e 63 65 2e 0a 54 68 65 20 63 61 6c  equence..The cal
4e30: 6c 62 61 63 6b 20 63 61 6e 20 6c 6f 6f 6b 75 70  lback can lookup
4e40: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
4e50: 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
4e60: 69 6f 6e 20 61 6e 64 20 69 6e 76 6f 6b 65 0a 73  ion and invoke.s
4e70: 71 6c 69 74 65 5f 33 5f 63 72 65 61 74 65 5f 63  qlite_3_create_c
4e80: 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 73 20 6e 65  ollation() as ne
4e90: 65 64 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  eded.  The fourt
4ea0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
4eb0: 68 65 20 63 61 6c 6c 62 61 63 6b 0a 69 73 20 74  he callback.is t
4ec0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
4ed0: 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63  ollating sequenc
4ee0: 65 20 69 6e 20 55 54 46 2d 38 2e 20 20 46 6f 72  e in UTF-8.  For
4ef0: 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
4f00: 6f 6e 5f 6e 65 65 64 31 36 28 29 0a 74 68 65 20  on_need16().the 
4f10: 63 61 6c 6c 62 61 63 6b 20 73 65 6e 64 73 20 74  callback sends t
4f20: 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71  he collating seq
4f30: 75 65 6e 63 65 20 6e 61 6d 65 20 69 6e 20 55 54  uence name in UT
4f40: 46 2d 31 36 20 68 6f 73 74 20 62 79 74 65 20 6f  F-16 host byte o
4f50: 72 64 65 72 2e 0a 3c 2f 70 3e 0a                 rder..</p>.