System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 43f4a0fe402029472876a27fbbc49695401f3349:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 74 6f  e changes .** to
0390: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   experimental in
03a0: 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73  terfaces but res
03b0: 65 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e  erve to make min
03c0: 6f 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a  or changes if.**
03d0: 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d   experience from
03e0: 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c   use "in the wil
03f0: 64 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20  d" suggest such 
0400: 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64  changes are prud
0410: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  ent..**.** The o
0420: 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61  fficial C-langua
0430: 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61  ge API documenta
0440: 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20  tion for SQLite 
0450: 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72  is derived.** fr
0460: 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74  om comments in t
0470: 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20  his file.  This 
0480: 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68  file is the auth
0490: 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65  oritative source
04a0: 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74  .** on how SQLit
04b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
04c0: 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72   suppose to oper
04d0: 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ate..**.** The n
04e0: 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ame of this file
04f0: 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61   under configura
0500: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
0510: 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22  is "sqlite.h.in"
0520: 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c  ..** The makefil
0530: 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e  e makes some min
0540: 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  or changes to th
0550: 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73  is file (such as
0560: 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68   inserting.** th
0570: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
0580: 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74  ) and changes it
0590: 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74  s name to "sqlit
05a0: 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74  e3.h" as.** part
05b0: 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72   of the build pr
05c0: 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23  ocess..**.** @(#
05d0: 29 20 24 49 64 3a 20 73 71 6c 69 74 65 33 2e 68  ) $Id: sqlite3.h
05e0: 2c 76 20 31 2e 33 30 20 32 30 30 37 2f 30 36 2f  ,v 1.30 2007/06/
05f0: 31 39 20 32 32 3a 34 33 3a 32 34 20 72 6d 73 69  19 22:43:24 rmsi
0600: 6d 70 73 6f 6e 20 45 78 70 20 24 0a 2a 2f 0a 23  mpson Exp $.*/.#
0610: 69 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f  ifndef _SQLITE3_
0620: 48 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49  H_.#define _SQLI
0630: 54 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20  TE3_H_.#include 
0640: 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f  <stdarg.h>     /
0650: 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65  * Needed for the
0660: 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76   definition of v
0670: 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  a_list */../*.**
0680: 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63 61   Make sure we ca
0690: 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66  n call this stuf
06a0: 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23  f from C++..*/.#
06b0: 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75  ifdef __cplusplu
06c0: 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23  s.extern "C" {.#
06d0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  endif../*.** Mak
06e0: 65 20 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  e sure these sym
06f0: 62 6f 6c 73 20 77 68 65 72 65 20 6e 6f 74 20 64  bols where not d
0700: 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70  efined by some p
0710: 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 0a 2a  revious header.*
0720: 2a 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  * file..*/.#ifde
0730: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0740: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0750: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0760: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0770: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0780: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0790: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
07a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
07b0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
07c0: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
07d0: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  umbers.**.** The
07e0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
07f0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69  SQLite library i
0800: 73 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74  s contained in t
0810: 68 65 20 73 71 6c 69 74 65 33 2e 68 0a 2a 2a 20  he sqlite3.h.** 
0820: 68 65 61 64 65 72 20 66 69 6c 65 20 69 6e 20 61  header file in a
0830: 20 23 64 65 66 69 6e 65 20 6e 61 6d 65 64 20 53   #define named S
0840: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 2e 20 20  QLITE_VERSION.  
0850: 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  The SQLITE_VERSI
0860: 4f 4e 0a 2a 2a 20 6d 61 63 72 6f 20 72 65 73 6f  ON.** macro reso
0870: 6c 76 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67  lves to a string
0880: 20 63 6f 6e 73 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a   constant..**.**
0890: 20 54 68 65 20 66 6f 72 6d 61 74 20 6f 66 20 74   The format of t
08a0: 68 65 20 76 65 72 73 69 6f 6e 20 73 74 72 69 6e  he version strin
08b0: 67 20 69 73 20 22 58 2e 59 2e 5a 22 2c 20 77 68  g is "X.Y.Z", wh
08c0: 65 72 65 0a 2a 2a 20 58 20 69 73 20 74 68 65 20  ere.** X is the 
08d0: 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75  major version nu
08e0: 6d 62 65 72 2c 20 59 20 69 73 20 74 68 65 20 6d  mber, Y is the m
08f0: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  inor version num
0900: 62 65 72 20 61 6e 64 20 5a 0a 2a 2a 20 69 73 20  ber and Z.** is 
0910: 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62  the release numb
0920: 65 72 2e 20 20 54 68 65 20 58 2e 59 2e 5a 20 6d  er.  The X.Y.Z m
0930: 69 67 68 74 20 62 65 20 66 6f 6c 6c 6f 77 65 64  ight be followed
0940: 20 62 79 20 22 61 6c 70 68 61 22 20 6f 72 20 22   by "alpha" or "
0950: 62 65 74 61 22 2e 0a 2a 2a 20 46 6f 72 20 65 78  beta"..** For ex
0960: 61 6d 70 6c 65 20 22 33 2e 31 2e 31 62 65 74 61  ample "3.1.1beta
0970: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 58 20 76  "..**.** The X v
0980: 61 6c 75 65 20 69 73 20 61 6c 77 61 79 73 20 33  alue is always 3
0990: 20 69 6e 20 53 51 4c 69 74 65 2e 20 20 54 68 65   in SQLite.  The
09a0: 20 58 20 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68   X value only ch
09b0: 61 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20 62 61  anges when.** ba
09c0: 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
09d0: 69 6c 69 74 79 20 69 73 20 62 72 6f 6b 65 6e 20  ility is broken 
09e0: 61 6e 64 20 77 65 20 69 6e 74 65 6e 64 20 74 6f  and we intend to
09f0: 20 6e 65 76 65 72 20 62 72 65 61 6b 0a 2a 2a 20   never break.** 
0a00: 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
0a10: 69 62 69 6c 69 74 79 2e 20 20 54 68 65 20 59 20  ibility.  The Y 
0a20: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67  value only chang
0a30: 65 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65  es when.** there
0a40: 20 61 72 65 20 6d 61 6a 6f 72 20 66 65 61 74 75   are major featu
0a50: 72 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20  re enhancements 
0a60: 74 68 61 74 20 61 72 65 20 66 6f 72 77 61 72 64  that are forward
0a70: 73 20 63 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20  s compatible.** 
0a80: 62 75 74 20 6e 6f 74 20 62 61 63 6b 77 61 72 64  but not backward
0a90: 73 20 63 6f 6d 70 61 74 69 62 6c 65 2e 20 20 54  s compatible.  T
0aa0: 68 65 20 5a 20 76 61 6c 75 65 20 69 73 20 69 6e  he Z value is in
0ab0: 63 72 65 6d 65 6e 74 65 64 20 77 69 74 68 0a 2a  cremented with.*
0ac0: 2a 20 65 61 63 68 20 72 65 6c 65 61 73 65 20 62  * each release b
0ad0: 75 74 20 72 65 73 65 74 73 20 62 61 63 6b 20 74  ut resets back t
0ae0: 6f 20 30 20 77 68 65 6e 20 59 20 69 73 20 69 6e  o 0 when Y is in
0af0: 63 72 65 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  cremented..**.**
0b00: 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53   The SQLITE_VERS
0b10: 49 4f 4e 5f 4e 55 4d 42 45 52 20 69 73 20 61 6e  ION_NUMBER is an
0b20: 20 69 6e 74 65 67 65 72 20 77 69 74 68 20 74 68   integer with th
0b30: 65 20 76 61 6c 75 65 20 0a 2a 2a 20 28 58 2a 31  e value .** (X*1
0b40: 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20  000000 + Y*1000 
0b50: 2b 20 5a 29 2e 20 46 6f 72 20 65 78 61 6d 70 6c  + Z). For exampl
0b60: 65 2c 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 22  e, for version "
0b70: 33 2e 31 2e 31 62 65 74 61 22 2c 20 0a 2a 2a 20  3.1.1beta", .** 
0b80: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0b90: 55 4d 42 45 52 20 69 73 20 73 65 74 20 74 6f 20  UMBER is set to 
0ba0: 33 30 30 31 30 30 31 2e 20 54 6f 20 64 65 74 65  3001001. To dete
0bb0: 63 74 20 69 66 20 74 68 65 79 20 61 72 65 20 75  ct if they are u
0bc0: 73 69 6e 67 20 0a 2a 2a 20 76 65 72 73 69 6f 6e  sing .** version
0bd0: 20 33 2e 31 2e 31 20 6f 72 20 67 72 65 61 74 65   3.1.1 or greate
0be0: 72 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  r at compile tim
0bf0: 65 2c 20 70 72 6f 67 72 61 6d 73 20 6d 61 79 20  e, programs may 
0c00: 75 73 65 20 74 68 65 20 74 65 73 74 20 0a 2a 2a  use the test .**
0c10: 20 28 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   (SQLITE_VERSION
0c20: 5f 4e 55 4d 42 45 52 3e 3d 33 30 30 31 30 30 31  _NUMBER>=3001001
0c30: 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
0c40: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
0c50: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
0c60: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
0c70: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2f 0a  n_number()]..*/.
0c80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0c90: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 20 22  ERSION         "
0ca0: 33 2e 34 2e 30 22 0a 23 64 65 66 69 6e 65 20 53  3.4.0".#define S
0cb0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0cc0: 4d 42 45 52 20 33 30 30 34 30 30 30 0a 0a 2f 2a  MBER 3004000../*
0cd0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
0ce0: 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56  n-Time Library V
0cf0: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a  ersion Numbers.*
0d00: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
0d10: 6e 65 73 20 72 65 74 75 72 6e 20 76 61 6c 75 65  nes return value
0d20: 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
0d30: 74 68 65 20 68 65 61 64 65 72 20 63 6f 6e 73 74  the header const
0d40: 61 6e 74 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ants.** [SQLITE_
0d50: 56 45 52 53 49 4f 4e 5d 20 61 6e 64 20 5b 53 51  VERSION] and [SQ
0d60: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
0d70: 42 45 52 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  BER].  The value
0d80: 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  s returned.** by
0d90: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73 20 73   this routines s
0da0: 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 64 69  hould only be di
0db0: 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
0dc0: 20 68 65 61 64 65 72 20 76 61 6c 75 65 73 0a 2a   header values.*
0dd0: 2a 20 69 66 20 79 6f 75 20 63 6f 6d 70 69 6c 65  * if you compile
0de0: 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 75 73   your program us
0df0: 69 6e 67 20 61 6e 20 73 71 6c 69 74 65 33 2e 68  ing an sqlite3.h
0e00: 20 68 65 61 64 65 72 20 66 72 6f 6d 20 61 0a 2a   header from a.*
0e10: 2a 20 64 69 66 66 65 72 65 6e 74 20 76 65 72 73  * different vers
0e20: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68  ion of SQLite th
0e30: 61 74 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f  at the version o
0e40: 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 79 6f  f the library yo
0e50: 75 0a 2a 2a 20 6c 69 6e 6b 20 61 67 61 69 6e 73  u.** link agains
0e60: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  t..**.** The sql
0e70: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
0e80: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63  tring constant c
0e90: 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74  ontains the text
0ea0: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   of the.** [SQLI
0eb0: 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73 74 72 69  TE_VERSION] stri
0ec0: 6e 67 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ng.  The sqlite3
0ed0: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75  _libversion() fu
0ee0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a  nction returns.*
0ef0: 2a 20 61 20 70 6f 69 6e 65 72 20 74 6f 20 74 68  * a poiner to th
0f00: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
0f10: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
0f20: 61 6e 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69  ant.  The functi
0f30: 6f 6e 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65  on.** is provide
0f40: 64 20 66 6f 72 20 44 4c 4c 20 75 73 65 72 73 20  d for DLL users 
0f50: 77 68 6f 20 63 61 6e 20 6f 6e 6c 79 20 61 63 63  who can only acc
0f60: 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  ess functions an
0f70: 64 20 6e 6f 74 0a 2a 2a 20 63 6f 6e 73 74 61 6e  d not.** constan
0f80: 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c  ts within the DL
0f90: 4c 2e 0a 2a 2f 0a 65 78 74 65 72 6e 20 63 6f 6e  L..*/.extern con
0fa0: 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f  st char sqlite3_
0fb0: 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74  version[];.const
0fc0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c   char *sqlite3_l
0fd0: 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b  ibversion(void);
0fe0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62  .int sqlite3_lib
0ff0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
1000: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
1010: 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
1020: 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c  Connection Handl
1030: 65 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65  e.**.** Each ope
1040: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
1050: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  e is represented
1060: 20 62 79 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   by pointer to a
1070: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
1080: 65 0a 2a 2a 20 6f 70 61 71 75 65 20 73 74 72 75  e.** opaque stru
1090: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c  cture named "sql
10a0: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73  ite3".  It is us
10b0: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66  eful to think of
10c0: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70   an sqlite3.** p
10d0: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a  ointer as an obj
10e0: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ect.  The [sqlit
10f0: 65 33 5f 6f 70 65 6e 5d 20 69 6e 74 65 72 66 61  e3_open] interfa
1100: 63 65 20 69 73 20 69 74 73 20 63 6f 6e 73 74 72  ce is its constr
1110: 75 63 74 6f 72 0a 2a 2a 20 61 6e 64 20 5b 73 71  uctor.** and [sq
1120: 6c 69 74 65 33 5f 63 6c 6f 73 65 5d 20 69 73 20  lite3_close] is 
1130: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e 20  its destructor. 
1140: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
1150: 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  other interfaces
1160: 0a 2a 2a 20 28 73 75 63 68 20 61 73 20 5b 73 71  .** (such as [sq
1170: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1180: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
1190: 74 65 5f 66 75 6e 63 74 69 6f 6e 5d 2c 20 61 6e  te_function], an
11a0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
11b0: 73 79 5f 74 69 6d 65 6f 75 74 5d 20 74 6f 20 6e  sy_timeout] to n
11c0: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
11d0: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
11e0: 6f 6e 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  on this.** objec
11f0: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
1200: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c  ruct sqlite3 sql
1210: 69 74 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  ite3;.../*.** CA
1220: 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49  PI3REF: 64-Bit I
1230: 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 0a  nteger Types.**.
1240: 2a 2a 20 53 6f 6d 65 20 63 6f 6d 70 69 6c 65 72  ** Some compiler
1250: 73 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74  s do not support
1260: 20 74 68 65 20 22 6c 6f 6e 67 20 6c 6f 6e 67 22   the "long long"
1270: 20 64 61 74 61 74 79 70 65 2e 20 20 53 6f 20 77   datatype.  So w
1280: 65 20 68 61 76 65 0a 2a 2a 20 74 6f 20 64 6f 20  e have.** to do 
1290: 63 6f 6d 70 69 6c 65 72 2d 73 70 65 63 69 66 69  compiler-specifi
12a0: 63 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36  c typedefs for 6
12b0: 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64  4-bit signed and
12c0: 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
12d0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  rs..**.** Many S
12e0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
12f0: 66 75 6e 63 74 69 6f 6e 73 20 72 65 71 75 69 72  functions requir
1300: 65 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67  e a 64-bit integ
1310: 65 72 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  er arguments..**
1320: 20 54 68 6f 73 65 20 69 6e 74 65 72 66 61 63 65   Those interface
1330: 73 20 61 72 65 20 64 65 63 6c 61 72 65 64 20 75  s are declared u
1340: 73 69 6e 67 20 74 68 69 73 20 74 79 70 65 64 65  sing this typede
1350: 66 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  f..*/.#ifdef SQL
1360: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
1370: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
1380: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
1390: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
13a0: 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49  ef unsigned SQLI
13b0: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
13c0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
13d0: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f  if defined(_MSC_
13e0: 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28  VER) || defined(
13f0: 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20  __BORLANDC__).  
1400: 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20  typedef __int64 
1410: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
1420: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
1430: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
1440: 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20  uint64;.#else.  
1450: 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e  typedef long lon
1460: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74  g int sqlite_int
1470: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
1480: 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67  signed long long
1490: 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74   int sqlite_uint
14a0: 36 34 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  64;.#endif../*.*
14b0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
14c0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
14d0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
14e0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
14f0: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
1500: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
1510: 74 69 6e 67 2d 70 6f 69 6e 74 0a 2a 2f 0a 23 69  ting-point.*/.#i
1520: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
1530: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
1540: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
1550: 73 71 6c 69 74 65 5f 69 6e 74 36 34 0a 23 65 6e  sqlite_int64.#en
1560: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
1570: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44  REF: Closing A D
1580: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
1590: 6f 6e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 20 74 68  on.**.** Call th
15a0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  is function with
15b0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
15c0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 77  structure that w
15d0: 61 73 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a  as previously.**
15e0: 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
15f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
1600: 61 6e 64 20 74 68 65 20 63 6f 72 72 65 73 70 6f  and the correspo
1610: 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 77  nding database w
1620: 69 6c 6c 20 62 79 0a 2a 2a 20 63 6c 6f 73 65 64  ill by.** closed
1630: 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20 53 51 4c 20  ..**.** All SQL 
1640: 73 74 61 74 65 6d 65 6e 74 73 20 70 72 65 70 61  statements prepa
1650: 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  red using [sqlit
1660: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1670: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1680: 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
1690: 6d 75 73 74 20 62 65 20 64 65 73 74 72 6f 79 65  must be destroye
16a0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
16b0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
16c0: 62 65 66 6f 72 65 20 74 68 69 73 20 72 6f 75 74  before this rout
16d0: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2e 20 4f  ine is called. O
16e0: 74 68 65 72 77 69 73 65 2c 20 53 51 4c 49 54 45  therwise, SQLITE
16f0: 5f 42 55 53 59 20 69 73 20 72 65 74 75 72 6e 65  _BUSY is returne
1700: 64 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74  d and the.** dat
1710: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1720: 20 72 65 6d 61 69 6e 73 20 6f 70 65 6e 2e 0a 2a   remains open..*
1730: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
1740: 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a  ose(sqlite3 *);.
1750: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20  ./*.** The type 
1760: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  for a callback f
1770: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73  unction..** This
1780: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64   is legacy and d
1790: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69  eprecated.  It i
17a0: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68  s included for h
17b0: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d  istorical.** com
17c0: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69  patibility and i
17d0: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64  s not documented
17e0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74  ..*/.typedef int
17f0: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62   (*sqlite3_callb
1800: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
1810: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a  har**, char**);.
1820: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1830: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20   One-Step Query 
1840: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66  Execution Interf
1850: 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ace.**.** This i
1860: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
1870: 20 74 6f 20 64 6f 20 61 20 6f 6e 65 2d 74 69 6d   to do a one-tim
1880: 65 20 65 76 61 6c 75 61 74 61 74 69 6f 6e 20 6f  e evaluatation o
1890: 66 20 7a 65 72 6f 0a 2a 2a 20 6f 72 20 6d 6f 72  f zero.** or mor
18a0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
18b0: 2e 20 20 55 54 46 2d 38 20 74 65 78 74 20 6f 66  .  UTF-8 text of
18c0: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
18d0: 6e 74 73 20 74 6f 0a 2a 2a 20 62 65 20 65 76 61  nts to.** be eva
18e0: 6c 75 74 65 64 20 69 73 20 70 61 73 73 65 64 20  luted is passed 
18f0: 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  in as the second
1900: 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
1910: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
1920: 72 65 20 70 72 65 70 61 72 65 64 20 6f 6e 65 20  re prepared one 
1930: 62 79 20 6f 6e 65 20 75 73 69 6e 67 20 5b 73 71  by one using [sq
1940: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1950: 2c 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 75  , evaluated.** u
1960: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
1970: 65 70 28 29 5d 2c 20 74 68 65 6e 20 64 65 73 74  ep()], then dest
1980: 72 6f 79 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  royed using [sql
1990: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
19a0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 6e 65 20 6f  ..**.** If one o
19b0: 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 53 51  r more of the SQ
19c0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
19d0: 20 71 75 65 72 69 65 73 2c 20 74 68 65 6e 0a 2a   queries, then.*
19e0: 2a 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * the callback f
19f0: 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65  unction specifie
1a00: 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72  d by the 3rd par
1a10: 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 69 6e 76  ameter is.** inv
1a20: 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  oked once for ea
1a30: 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20 71 75  ch row of the qu
1a40: 65 72 79 20 72 65 73 75 6c 74 2e 20 20 54 68 69  ery result.  Thi
1a50: 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 73 68  s callback.** sh
1a60: 6f 75 6c 64 20 6e 6f 72 6d 61 6c 6c 79 20 72 65  ould normally re
1a70: 74 75 72 6e 20 30 2e 20 20 49 66 20 74 68 65 20  turn 0.  If the 
1a80: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1a90: 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 76   a non-zero.** v
1aa0: 61 6c 75 65 20 74 68 65 6e 20 74 68 65 20 71 75  alue then the qu
1ab0: 65 72 79 20 69 73 20 61 62 6f 72 74 65 64 2c 20  ery is aborted, 
1ac0: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53  all subsequent S
1ad0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1ae0: 20 61 72 65 20 73 6b 69 70 70 65 64 20 61 6e 64   are skipped and
1af0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
1b00: 63 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  c() function ret
1b10: 75 72 6e 73 20 74 68 65 20 53 51 4c 49 54 45 5f  urns the SQLITE_
1b20: 41 42 4f 52 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ABORT..**.** The
1b30: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
1b40: 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  o this interface
1b50: 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
1b60: 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
1b70: 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75  .** passed throu
1b80: 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  gh to the callba
1b90: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 69  ck function as i
1ba0: 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ts first paramet
1bb0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 32 6e  er..**.** The 2n
1bc0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
1bd0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1be0: 74 69 6f 6e 20 69 73 20 74 68 65 20 6e 75 6d 62  tion is the numb
1bf0: 65 72 20 6f 66 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  er of.** columns
1c00: 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 72 65   in the query re
1c10: 73 75 6c 74 2e 20 20 54 68 65 20 33 72 64 20 70  sult.  The 3rd p
1c20: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1c30: 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 61  callback.** is a
1c40: 6e 20 61 72 72 61 79 20 6f 66 20 73 74 72 69 6e  n array of strin
1c50: 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 20 76  gs holding the v
1c60: 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68 20 63  alues for each c
1c70: 6f 6c 75 6d 6e 0a 2a 2a 20 61 73 20 65 78 74 72  olumn.** as extr
1c80: 61 63 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  acted using [sql
1c90: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
1ca0: 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20  ()]..** The 4th 
1cb0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1cc0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1cd0: 61 72 72 61 79 20 6f 66 20 73 74 72 69 6e 67 73  array of strings
1ce0: 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 75 73 69  .** obtained usi
1cf0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ng [sqlite3_colu
1d00: 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 68  mn_name()] and h
1d10: 6f 6c 64 69 6e 67 0a 2a 2a 20 74 68 65 20 6e 61  olding.** the na
1d20: 6d 65 73 20 6f 66 20 65 61 63 68 20 63 6f 6c 75  mes of each colu
1d30: 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  mn..**.** The ca
1d40: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1d50: 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 65 76 65  may be NULL, eve
1d60: 6e 20 66 6f 72 20 71 75 65 72 69 65 73 2e 20 20  n for queries.  
1d70: 41 20 4e 55 4c 4c 0a 2a 2a 20 63 61 6c 6c 62 61  A NULL.** callba
1d80: 63 6b 20 69 73 20 6e 6f 74 20 61 6e 20 65 72 72  ck is not an err
1d90: 6f 72 2e 20 20 49 74 20 6a 75 73 74 20 6d 65 61  or.  It just mea
1da0: 6e 73 20 74 68 61 74 20 6e 6f 20 63 61 6c 6c 62  ns that no callb
1db0: 61 63 6b 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 69  ack.** will be i
1dc0: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  nvoked..**.** If
1dd0: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1de0: 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f   while parsing o
1df0: 72 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  r evaluating the
1e00: 20 53 51 4c 20 28 62 75 74 0a 2a 2a 20 6e 6f 74   SQL (but.** not
1e10: 20 77 68 69 6c 65 20 65 78 65 63 75 74 69 6e 67   while executing
1e20: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 29 20 74   the callback) t
1e30: 68 65 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61  hen an appropria
1e40: 74 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  te error.** mess
1e50: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  age is written i
1e60: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
1e70: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
1e80: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 0a  3_malloc()] and.
1e90: 2a 2a 20 2a 65 72 72 6d 73 67 20 69 73 20 6d 61  ** *errmsg is ma
1ea0: 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
1eb0: 68 61 74 20 6d 65 73 73 61 67 65 2e 20 20 54 68  hat message.  Th
1ec0: 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
1ed0: 6f 6e 0a 2a 2a 20 69 73 20 72 65 73 70 6f 6e 73  on.** is respons
1ee0: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67  ible for freeing
1ef0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
1f00: 20 68 6f 6c 64 73 20 74 68 65 20 65 72 72 6f 72   holds the error
1f10: 0a 2a 2a 20 6d 65 73 73 61 67 65 2e 20 20 20 55  .** message.   U
1f20: 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  se [sqlite3_free
1f30: 28 29 5d 20 66 6f 72 20 74 68 69 73 2e 20 20 49  ()] for this.  I
1f40: 66 20 65 72 72 6d 73 67 3d 3d 4e 55 4c 4c 2c 0a  f errmsg==NULL,.
1f50: 2a 2a 20 74 68 65 6e 20 6e 6f 20 65 72 72 6f 72  ** then no error
1f60: 20 6d 65 73 73 61 67 65 20 69 73 20 65 76 65 72   message is ever
1f70: 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20   written..**.** 
1f80: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
1f90: 20 69 73 20 69 73 20 53 51 4c 49 54 45 5f 4f 4b   is is SQLITE_OK
1fa0: 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f   if there are no
1fb0: 20 65 72 72 6f 72 73 20 61 6e 64 0a 2a 2a 20 73   errors and.** s
1fc0: 6f 6d 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54  ome other [SQLIT
1fd0: 45 5f 4f 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f  E_OK | return co
1fe0: 64 65 5d 20 69 66 20 74 68 65 72 65 20 69 73 20  de] if there is 
1ff0: 61 6e 20 65 72 72 6f 72 2e 20 20 0a 2a 2a 20 54  an error.  .** T
2000: 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 72 65  he particular re
2010: 74 75 72 6e 20 76 61 6c 75 65 20 64 65 70 65 6e  turn value depen
2020: 64 73 20 6f 6e 20 74 68 65 20 74 79 70 65 20 6f  ds on the type o
2030: 66 20 65 72 72 6f 72 2e 20 0a 2a 2a 0a 2a 2f 0a  f error. .**.*/.
2040: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
2050: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
2060: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2080: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
2090: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
20a0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
20b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20c0: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
20d0: 65 76 61 6c 75 74 65 64 20 2a 2f 0a 20 20 69 6e  evaluted */.  in
20e0: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
20f0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
2100: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
2110: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
2120: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
2130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2150: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
2160: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
2170: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
2180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2190: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
21a0: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
21b0: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
21c0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
21d0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
21e0: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a  RDS: SQLITE_OK.*
21f0: 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65  *.** Many SQLite
2200: 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2210: 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73  n an integer res
2220: 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68  ult code from th
2230: 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 61  e set shown.** a
2240: 62 6f 76 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  bove in order to
2250: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
2260: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
2270: 2a 0a 2a 2a 20 54 68 65 20 72 65 73 75 6c 74 20  *.** The result 
2280: 63 6f 64 65 73 20 61 62 6f 76 65 20 61 72 65 20  codes above are 
2290: 74 68 65 20 6f 6e 6c 79 20 6f 6e 65 73 20 72 65  the only ones re
22a0: 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
22b0: 20 69 6e 20 69 74 73 0a 2a 2a 20 64 65 66 61 75   in its.** defau
22c0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
22d0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  .  However, the 
22e0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
22f0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
2300: 5d 0a 2a 2a 20 41 50 49 20 63 61 6e 20 62 65 20  ].** API can be 
2310: 75 73 65 64 20 74 6f 20 73 65 74 20 61 20 64 61  used to set a da
2320: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 6f 69  tabase connectoi
2330: 6e 20 74 6f 20 72 65 74 75 72 6e 20 6d 6f 72 65  n to return more
2340: 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 72 65 73   detailed.** res
2350: 75 6c 74 20 63 6f 64 65 73 2e 0a 2a 2a 0a 2a 2a  ult codes..**.**
2360: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
2370: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
2380: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
2390: 63 6f 64 65 73 5d 0a 2a 2a 0a 2a 2f 0a 23 64 65  codes].**.*/.#de
23a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20  fine SQLITE_OK  
23b0: 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
23c0: 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c  Successful resul
23d0: 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e  t */./* beginnin
23e0: 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73  g-of-error-codes
23f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2400: 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20  TE_ERROR        
2410: 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72  1   /* SQL error
2420: 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61   or missing data
2430: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
2440: 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20  SQLITE_INTERNAL 
2450: 20 20 20 20 32 20 20 20 2f 2a 20 4e 4f 54 20 55      2   /* NOT U
2460: 53 45 44 2e 20 49 6e 74 65 72 6e 61 6c 20 6c 6f  SED. Internal lo
2470: 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c  gic error in SQL
2480: 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ite */.#define S
2490: 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20  QLITE_PERM      
24a0: 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73     3   /* Access
24b0: 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69   permission deni
24c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
24d0: 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20  LITE_ABORT      
24e0: 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63    4   /* Callbac
24f0: 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73  k routine reques
2500: 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a  ted an abort */.
2510: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
2520: 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20  USY         5   
2530: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
2540: 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  file is locked *
2550: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2560: 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20  _LOCKED       6 
2570: 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20    /* A table in 
2580: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
2590: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
25a0: 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20  e SQLITE_NOMEM  
25b0: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d        7   /* A m
25c0: 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a  alloc() failed *
25d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
25e0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20  _READONLY     8 
25f0: 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20    /* Attempt to 
2600: 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79  write a readonly
2610: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
2620: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
2630: 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20  RRUPT    9   /* 
2640: 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e  Operation termin
2650: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
2660: 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64  interrupt()*/.#d
2670: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
2680: 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a  RR       10   /*
2690: 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69   Some kind of di
26a0: 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63  sk I/O error occ
26b0: 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  urred */.#define
26c0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20   SQLITE_CORRUPT 
26d0: 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20      11   /* The 
26e0: 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d  database disk im
26f0: 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64  age is malformed
2700: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2710: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31  TE_NOTFOUND    1
2720: 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e  2   /* NOT USED.
2730: 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64   Table or record
2740: 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64   not found */.#d
2750: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
2760: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
2770: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
2780: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
2790: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
27a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
27b0: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
27c0: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
27d0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
27e0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
27f0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
2800: 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44  15   /* NOT USED
2810: 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  . Database lock 
2820: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
2830: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2840: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
2850: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
2860: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
2870: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
2880: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
2890: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
28a0: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
28b0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
28c0: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
28d0: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
28e0: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
28f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2900: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
2910: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
2920: 20 74 6f 20 63 6f 6e 74 72 61 69 6e 74 20 76 69   to contraint vi
2930: 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69  olation */.#defi
2940: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54  ne SQLITE_MISMAT
2950: 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61  CH    20   /* Da
2960: 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68  ta type mismatch
2970: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2980: 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32  TE_MISUSE      2
2990: 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75  1   /* Library u
29a0: 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  sed incorrectly 
29b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
29c0: 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32  E_NOLFS       22
29d0: 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65     /* Uses OS fe
29e0: 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f  atures not suppo
29f0: 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a  rted on host */.
2a00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
2a10: 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20  UTH        23   
2a20: 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  /* Authorization
2a30: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
2a40: 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54  ne SQLITE_FORMAT
2a50: 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75        24   /* Au
2a60: 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65  xiliary database
2a70: 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f   format error */
2a80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a90: 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20  RANGE       25  
2aa0: 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65   /* 2nd paramete
2ab0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2ac0: 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a  d out of range *
2ad0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2ae0: 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20  _NOTADB      26 
2af0: 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64    /* File opened
2b00: 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64   that is not a d
2b10: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
2b20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
2b30: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
2b40: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
2b50: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
2b60: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
2b70: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
2b80: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
2b90: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
2ba0: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
2bb0: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
2bc0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
2bd0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2be0: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
2bf0: 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 49 6e 20   Codes.**.** In 
2c00: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
2c10: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
2c20: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
2c30: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
2c40: 69 6e 74 65 67 65 72 0a 2a 2a 20 72 65 73 75 6c  integer.** resul
2c50: 74 20 63 6f 64 65 73 20 64 65 73 63 72 69 62 65  t codes describe
2c60: 64 20 61 74 20 72 65 73 75 6c 74 2d 63 6f 64 65  d at result-code
2c70: 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  s.  However, exp
2c80: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
2c90: 6e 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20 6f  n that.** many o
2ca0: 66 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  f these result c
2cb0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 75  odes are too cou
2cc0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
2cd0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
2ce0: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
2cf0: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
2d00: 72 6f 62 6c 65 6d 73 20 61 73 20 75 73 65 72 73  roblems as users
2d10: 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e   might like.  In
2d20: 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a   an effort to.**
2d30: 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e   address this, n
2d40: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
2d50: 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e   SQLite (version
2d60: 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72   3.3.8 and later
2d70: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
2d80: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
2d90: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
2da0: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
2db0: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
2dc0: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
2dd0: 20 65 72 72 6f 72 73 2e 20 20 54 68 65 20 65 78   errors.  The ex
2de0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
2df0: 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  des are enabled 
2e00: 28 6f 72 20 64 69 73 61 62 6c 65 64 29 20 66 6f  (or disabled) fo
2e10: 72 20 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62  r .** each datab
2e20: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2e30: 6e 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  n using the [sql
2e40: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
2e50: 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50  sult_codes()] AP
2e60: 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20 6f  I..** .** Some o
2e70: 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  f the available 
2e80: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
2e90: 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64  codes are listed
2ea0: 20 61 62 6f 76 65 2e 0a 2a 2a 20 57 65 20 65 78   above..** We ex
2eb0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
2ec0: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
2ed0: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
2ee0: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
2ef0: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
2f00: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
2f10: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
2f20: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
2f30: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
2f40: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
2f50: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
2f60: 51 4c 69 74 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68  QLite..** .** Th
2f70: 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20  e symbolic name 
2f80: 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64 20  for an extended 
2f90: 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6c 77 61  result code alwa
2fa0: 79 73 20 63 6f 6e 74 61 69 6e 73 20 61 20 72 65  ys contains a re
2fb0: 6c 61 74 65 64 0a 2a 2a 20 70 72 69 6d 61 72 79  lated.** primary
2fc0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20   result code as 
2fd0: 61 20 70 72 65 66 69 78 2e 20 20 50 72 69 6d 61  a prefix.  Prima
2fe0: 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ry result codes 
2ff0: 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c 65  contain a single
3000: 0a 2a 2a 20 22 5f 22 20 63 68 61 72 61 63 74 65  .** "_" characte
3010: 72 2e 20 20 45 78 74 65 6e 64 65 64 20 72 65 73  r.  Extended res
3020: 75 6c 74 20 63 6f 64 65 73 20 63 6f 6e 74 61 69  ult codes contai
3030: 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f  n two or more "_
3040: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
3050: 20 54 68 65 20 6e 75 6d 65 72 69 63 20 76 61 6c   The numeric val
3060: 75 65 20 6f 66 20 61 6e 20 65 78 74 65 6e 64 65  ue of an extende
3070: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 63 61  d result code ca
3080: 6e 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  n be converted t
3090: 6f 20 69 74 73 0a 2a 2a 20 63 6f 72 72 65 73 70  o its.** corresp
30a0: 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72  onding primary r
30b0: 65 73 75 6c 74 20 63 6f 64 65 20 62 79 20 6d 61  esult code by ma
30c0: 73 6b 69 6e 67 20 6f 66 66 20 74 68 65 20 6c 6f  sking off the lo
30d0: 77 65 72 20 38 20 62 79 74 65 73 2e 0a 2a 2a 0a  wer 8 bytes..**.
30e0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b  ** The SQLITE_OK
30f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c   result code wil
3100: 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e  l never be exten
3110: 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c  ded.  It will al
3120: 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74  ways.** be exact
3130: 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66  ly zero..*/.#def
3140: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3150: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 28  _READ          (
3160: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
3170: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
3180: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
3190: 54 5f 52 45 41 44 20 20 20 20 28 53 51 4c 49 54  T_READ    (SQLIT
31a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
31b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
31c0: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
31d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
31e0: 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  RR | (3<<8)).#de
31f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3200: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
3210: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
3220: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
3230: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
3240: 5f 46 53 59 4e 43 20 20 20 20 20 28 53 51 4c 49  _FSYNC     (SQLI
3250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
3260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3270: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
3280: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
3290: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
32a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
32b0: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
32c0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
32d0: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
32e0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e   SQLITE_IOERR_UN
32f0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  LOCK        (SQL
3300: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
3310: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3320: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
3330: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
3340: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
3350: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3360: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
3370: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
3380: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
3390: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
33a0: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 28 53  BLOCKED       (S
33b0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
33c0: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  1<<8))../*.** CA
33d0: 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
33e0: 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
33f0: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
3400: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
3410: 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
3420: 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 53  sables the.** [S
3430: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
3440: 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
3450: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
3460: 65 2e 0a 2a 2a 20 42 79 20 64 65 66 61 75 6c 74  e..** By default
3470: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
3480: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
3490: 20 6f 66 20 6f 6e 6c 79 20 32 36 20 69 6e 74 65   of only 26 inte
34a0: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
34b0: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
34c0: 5d 2e 20 20 57 68 65 6e 20 65 78 74 65 6e 64 65  ].  When extende
34d0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 0a 2a  d result codes.*
34e0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  * are enabled by
34f0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
3500: 68 65 20 72 65 70 65 74 6f 69 72 65 20 6f 66 20  he repetoire of 
3510: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 63 61 6e  result codes can
3520: 20 62 65 0a 2a 2a 20 6d 75 63 68 20 6c 61 72 67   be.** much larg
3530: 65 72 20 61 6e 64 20 63 61 6e 20 28 68 6f 70 65  er and can (hope
3540: 66 75 6c 6c 79 29 20 70 72 6f 76 69 64 65 20 6d  fully) provide m
3550: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
3560: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
3570: 74 20 74 68 65 20 63 61 75 73 65 20 6f 66 20 61  t the cause of a
3580: 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  n error..**.** T
3590: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
35a0: 6e 74 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  nt is a boolean 
35b0: 76 61 6c 75 65 20 74 68 61 74 20 74 75 72 6e 73  value that turns
35c0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
35d0: 0a 2a 2a 20 63 6f 64 65 73 20 6f 6e 20 61 6e 64  .** codes on and
35e0: 20 6f 66 66 2e 20 20 45 78 74 65 6e 64 65 64 20   off.  Extended 
35f0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
3600: 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 20   off by default 
3610: 66 6f 72 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  for.** backwards
3620: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
3630: 69 74 68 20 6f 6c 64 65 72 20 76 65 72 73 69 6f  ith older versio
3640: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
3650: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
3660: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
3670: 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
3680: 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
3690: 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
36a0: 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a  nsert Rowid.**.*
36b0: 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20  * Each entry in 
36c0: 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
36d0: 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
36e0: 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
36f0: 65 72 20 6b 65 79 0a 2a 2a 20 63 61 6c 6c 65 64  er key.** called
3700: 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68   the "rowid". Th
3710: 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
3720: 73 20 61 76 61 69 6c 61 62 6c 65 20 61 73 20 61  s available as a
3730: 6e 20 75 6e 64 65 63 6c 61 72 65 64 0a 2a 2a 20  n undeclared.** 
3740: 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
3750: 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
3760: 49 44 5f 2e 20 20 49 66 20 74 68 65 20 74 61 62  ID_.  If the tab
3770: 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
3780: 6f 66 0a 2a 2a 20 74 79 70 65 20 49 4e 54 45 47  of.** type INTEG
3790: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74  ER PRIMARY KEY t
37a0: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20  hen that column 
37b0: 69 73 20 61 6e 6f 74 68 65 72 20 61 6e 20 61 6c  is another an al
37c0: 69 61 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 72  ias for the.** r
37d0: 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  owid..**.** This
37e0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
37f0: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
3800: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
3810: 53 45 52 54 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  SERT into.** the
3820: 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
3830: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
3840: 65 63 74 69 6f 6e 20 67 69 76 65 6e 20 69 6e 20  ection given in 
3850: 74 68 65 20 66 69 72 73 74 20 0a 2a 2a 20 61 72  the first .** ar
3860: 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 69  gument.  If no i
3870: 6e 73 65 72 74 73 20 68 61 76 65 20 65 76 65 72  nserts have ever
3880: 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 69   occurred on thi
3890: 73 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  s database.** co
38a0: 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69  nnection, zero i
38b0: 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
38c0: 2a 20 49 66 20 61 6e 20 49 4e 53 45 52 54 20 6f  * If an INSERT o
38d0: 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
38e0: 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65  rigger, then the
38f0: 20 72 6f 77 69 64 20 6f 66 20 74 68 65 0a 2a 2a   rowid of the.**
3900: 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 69 73   inserted row is
3910: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
3920: 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e  s routine as lon
3930: 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
3940: 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  .** is running. 
3950: 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
3960: 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73  igger terminates
3970: 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
3980: 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20  rned.** by this 
3990: 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
39a0: 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75  to the last valu
39b0: 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72  e inserted befor
39c0: 65 20 74 68 65 0a 2a 2a 20 74 72 69 67 67 65 72  e the.** trigger
39d0: 20 66 69 72 65 64 2e 0a 2a 2f 0a 73 71 6c 69 74   fired..*/.sqlit
39e0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  e_int64 sqlite3_
39f0: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
3a00: 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
3a10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
3a20: 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
3a30: 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
3a40: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
3a50: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
3a60: 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
3a70: 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
3a80: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 28 6f 72  e changed.** (or
3a90: 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
3aa0: 65 74 65 64 29 20 62 79 20 74 68 65 20 6d 6f 73  eted) by the mos
3ab0: 74 20 72 65 63 65 6e 74 20 53 51 4c 20 73 74 61  t recent SQL sta
3ac0: 74 65 6d 65 6e 74 2e 20 20 4f 6e 6c 79 0a 2a 2a  tement.  Only.**
3ad0: 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
3ae0: 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
3af0: 66 69 65 64 20 62 79 20 74 68 65 20 49 4e 53 45  fied by the INSE
3b00: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 0a 2a  RT, UPDATE, or.*
3b10: 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
3b20: 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
3b30: 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
3b40: 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
3b50: 74 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74  triggers are not
3b60: 20 63 6f 75 6e 74 65 64 2e 20 20 55 73 65 20 74   counted.  Use t
3b70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
3b80: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
3b90: 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64  ction.** to find
3ba0: 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
3bb0: 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63  r of changes inc
3bc0: 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
3bd0: 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
3be0: 73 2e 0a 2a 2a 0a 2a 2a 20 57 69 74 68 69 6e 20  s..**.** Within 
3bf0: 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72  the body of a tr
3c00: 69 67 67 65 72 2c 20 74 68 65 20 73 71 6c 69 74  igger, the sqlit
3c10: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74  e3_changes() int
3c20: 65 72 66 61 63 65 20 63 61 6e 20 62 65 0a 2a 2a  erface can be.**
3c30: 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20   called to find 
3c40: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
3c50: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
3c60: 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
3c70: 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
3c80: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
3c90: 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77  E.** statement w
3ca0: 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
3cb0: 66 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a  f the trigger..*
3cc0: 2a 0a 2a 2a 20 41 6c 6c 20 63 68 61 6e 67 65 73  *.** All changes
3cd0: 20 61 72 65 20 63 6f 75 6e 74 65 64 2c 20 65 76   are counted, ev
3ce0: 65 6e 20 69 66 20 74 68 65 79 20 77 65 72 65 20  en if they were 
3cf0: 6c 61 74 65 72 20 75 6e 64 6f 6e 65 20 62 79 20  later undone by 
3d00: 61 0a 2a 2a 20 52 4f 4c 4c 42 41 43 4b 20 6f 72  a.** ROLLBACK or
3d10: 20 41 42 4f 52 54 2e 20 20 45 78 63 65 70 74 2c   ABORT.  Except,
3d20: 20 63 68 61 6e 67 65 73 20 61 73 73 6f 63 69 61   changes associa
3d30: 74 65 64 20 77 69 74 68 20 63 72 65 61 74 69 6e  ted with creatin
3d40: 67 20 61 6e 64 0a 2a 2a 20 64 72 6f 70 70 69 6e  g and.** droppin
3d50: 67 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74  g tables are not
3d60: 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
3d70: 49 66 20 61 20 63 61 6c 6c 62 61 63 6b 20 69 6e  If a callback in
3d80: 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 65  vokes [sqlite3_e
3d90: 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  xec()] or [sqlit
3da0: 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72  e3_step()] recur
3db0: 73 69 76 65 6c 79 2c 0a 2a 2a 20 74 68 65 6e 20  sively,.** then 
3dc0: 74 68 65 20 63 68 61 6e 67 65 73 20 69 6e 20 74  the changes in t
3dd0: 68 65 20 69 6e 6e 65 72 2c 20 72 65 63 75 72 73  he inner, recurs
3de0: 69 76 65 20 63 61 6c 6c 20 61 72 65 20 63 6f 75  ive call are cou
3df0: 6e 74 65 64 20 74 6f 67 65 74 68 65 72 0a 2a 2a  nted together.**
3e00: 20 77 69 74 68 20 74 68 65 20 63 68 61 6e 67 65   with the change
3e10: 73 20 69 6e 20 74 68 65 20 6f 75 74 65 72 20 63  s in the outer c
3e20: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  all..**.** SQLit
3e30: 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  e implements the
3e40: 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45   command "DELETE
3e50: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74   FROM table" wit
3e60: 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61  hout a WHERE cla
3e70: 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69  use.** by droppi
3e80: 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e  ng and recreatin
3e90: 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54  g the table.  (T
3ea0: 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 74  his is much fast
3eb0: 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a  er than going.**
3ec0: 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c   through and del
3ed0: 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c  eting individual
3ee0: 20 65 6c 65 6d 65 6e 74 73 20 66 6f 72 6d 20 74   elements form t
3ef0: 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61  he table.)  Beca
3f00: 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20 6f  use of.** this o
3f10: 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65  ptimization, the
3f20: 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f   change count fo
3f30: 72 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  r "DELETE FROM t
3f40: 61 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a 2a  able" will be.**
3f50: 20 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 73 73   zero regardless
3f60: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
3f70: 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20  f elements that 
3f80: 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20  were originally 
3f90: 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e  in the.** table.
3fa0: 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72   To get an accur
3fb0: 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65  ate count of the
3fc0: 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
3fd0: 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20  deleted, use.** 
3fe0: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
3ff0: 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74  le WHERE 1" inst
4000: 65 61 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ead..*/.int sqli
4010: 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  te3_changes(sqli
4020: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
4030: 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75  PI3REF: Total Nu
4040: 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
4050: 69 66 69 65 64 0a 2a 2a 2a 0a 2a 2a 20 54 68 69  ified.***.** Thi
4060: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
4070: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
4080: 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
4090: 68 61 74 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a  hat have been.**
40a0: 20 6d 6f 64 69 66 69 65 64 20 62 79 20 49 4e 53   modified by INS
40b0: 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
40c0: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73  ELETE statements
40d0: 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62   since the datab
40e0: 61 73 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61  ase handle.** wa
40f0: 73 20 6f 70 65 6e 65 64 2e 20 54 68 69 73 20 69  s opened. This i
4100: 6e 63 6c 75 64 65 73 20 55 50 44 41 54 45 2c 20  ncludes UPDATE, 
4110: 49 4e 53 45 52 54 20 61 6e 64 20 44 45 4c 45 54  INSERT and DELET
4120: 45 20 73 74 61 74 65 6d 65 6e 74 73 20 65 78 65  E statements exe
4130: 63 75 74 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  cuted.** as part
4140: 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67   of trigger prog
4150: 72 61 6d 73 2e 20 41 6c 6c 20 63 68 61 6e 67 65  rams. All change
4160: 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73  s are counted as
4170: 20 73 6f 6f 6e 20 61 73 20 74 68 65 0a 2a 2a 20   soon as the.** 
4180: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
4190: 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d  akes them is com
41a0: 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65  pleted (when the
41b0: 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   statement handl
41c0: 65 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  e is.** passed t
41d0: 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
41e0: 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 5f 66  ()] or [sqlite_f
41f0: 69 6e 61 6c 69 73 65 28 29 5d 29 2e 0a 2a 2a 0a  inalise()])..**.
4200: 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
4210: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 28  [sqlite3_change(
4220: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
4230: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
4240: 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e  ments the comman
4250: 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  d "DELETE FROM t
4260: 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20  able" without a 
4270: 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20  WHERE clause.** 
4280: 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20  by dropping and 
4290: 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74  recreating the t
42a0: 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20  able.  (This is 
42b0: 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e  much faster than
42c0: 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67   going.** throug
42d0: 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69  h and deleting i
42e0: 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e  ndividual elemen
42f0: 74 73 20 66 6f 72 6d 20 74 68 65 20 74 61 62 6c  ts form the tabl
4300: 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 0a  e.)  Because of.
4310: 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61  ** this optimiza
4320: 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67 65  tion, the change
4330: 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c 45   count for "DELE
4340: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77  TE FROM table" w
4350: 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72  ill be.** zero r
4360: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
4370: 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65   number of eleme
4380: 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72  nts that were or
4390: 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a  iginally in the.
43a0: 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67 65 74  ** table. To get
43b0: 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75   an accurate cou
43c0: 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
43d0: 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64   of rows deleted
43e0: 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45  , use.** "DELETE
43f0: 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52   FROM table WHER
4400: 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2f  E 1" instead..*/
4410: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74  .int sqlite3_tot
4420: 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
4430: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
4440: 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
4450: 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
4460: 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73  Query.**.** This
4470: 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
4480: 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
4490: 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
44a0: 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
44b0: 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
44c0: 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
44d0: 74 79 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  ty.  This routin
44e0: 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
44f0: 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
4500: 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
4510: 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
4520: 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
4530: 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
4540: 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
4550: 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
4560: 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
4570: 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
4580: 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66  .**.** It is saf
4590: 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
45a0: 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
45b0: 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
45c0: 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
45d0: 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
45e0: 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
45f0: 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
4600: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  on..**.** The SQ
4610: 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
4620: 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
4630: 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
4640: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
4650: 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 72 75  ** If an interru
4660: 70 74 65 64 20 6f 70 65 72 61 74 69 6f 6e 20 77  pted operation w
4670: 61 73 20 61 6e 20 75 70 64 61 74 65 20 74 68 61  as an update tha
4680: 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 0a 2a  t is inside an.*
4690: 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
46a0: 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
46b0: 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
46c0: 69 6f 6e 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  ion will be roll
46d0: 65 64 0a 2a 2a 20 62 61 63 6b 20 61 75 74 6f 6d  ed.** back autom
46e0: 61 74 69 63 61 6c 6c 79 2e 0a 2a 2f 0a 76 6f 69  atically..*/.voi
46f0: 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
4700: 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
4710: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4720: 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
4730: 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
4740: 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20   Complete.**.** 
4750: 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
4760: 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74  return true if t
4770: 68 65 20 67 69 76 65 6e 20 69 6e 70 75 74 20 73  he given input s
4780: 74 72 69 6e 67 20 63 6f 6d 70 72 69 73 65 73 0a  tring comprises.
4790: 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
47a0: 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
47b0: 65 6d 65 6e 74 73 2e 20 46 6f 72 20 74 68 65 20  ements. For the 
47c0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
47d0: 28 29 20 63 61 6c 6c 2c 0a 2a 2a 20 74 68 65 20  () call,.** the 
47e0: 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
47f0: 65 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  e a nul-terminat
4800: 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ed UTF-8 string.
4810: 20 46 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   For.** sqlite3_
4820: 63 6f 6d 70 6c 65 74 65 31 36 28 29 2c 20 61 20  complete16(), a 
4830: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 20 6d  nul-terminated m
4840: 61 63 68 69 6e 65 20 62 79 74 65 20 6f 72 64 65  achine byte orde
4850: 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  r UTF-16 string.
4860: 2a 2a 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ** is required..
4870: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
4880: 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
4890: 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  for command-line
48a0: 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
48b0: 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
48c0: 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
48d0: 74 65 78 74 20 66 6f 72 6d 73 20 6f 6e 65 20 6f  text forms one o
48e0: 72 20 6d 6f 72 65 20 63 6f 6d 70 6c 65 74 65 20  r more complete 
48f0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
4900: 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
4910: 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
4920: 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
4930: 67 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  g the statements
4940: 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
4950: 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 54 68 65  for parsing. The
4960: 20 61 6c 67 6f 72 69 74 68 6d 20 69 73 20 73 69   algorithm is si
4970: 6d 70 6c 65 2e 20 20 49 66 20 74 68 65 20 0a 2a  mple.  If the .*
4980: 2a 20 6c 61 73 74 20 74 6f 6b 65 6e 20 6f 74 68  * last token oth
4990: 65 72 20 74 68 61 6e 20 73 70 61 63 65 73 20 61  er than spaces a
49a0: 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 69 73 20 61  nd comments is a
49b0: 20 73 65 6d 69 63 6f 6c 6f 6e 2c 20 74 68 65 6e   semicolon, then
49c0: 20 72 65 74 75 72 6e 20 0a 2a 2a 20 74 72 75 65   return .** true
49d0: 2e 20 20 41 63 74 75 61 6c 6c 79 2c 20 74 68 65  .  Actually, the
49e0: 20 61 6c 67 6f 72 69 74 68 6d 20 69 73 20 61 20   algorithm is a 
49f0: 6c 69 74 74 6c 65 20 6d 6f 72 65 20 63 6f 6d 70  little more comp
4a00: 6c 69 63 61 74 65 64 20 74 68 61 6e 20 74 68 61  licated than tha
4a10: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  t.** in order to
4a20: 20 64 65 61 6c 20 77 69 74 68 20 74 72 69 67 67   deal with trigg
4a30: 65 72 73 2c 20 62 75 74 20 74 68 65 20 62 61 73  ers, but the bas
4a40: 69 63 20 69 64 65 61 20 69 73 20 74 68 65 20 73  ic idea is the s
4a50: 61 6d 65 3a 20 20 74 68 65 0a 2a 2a 20 73 74 61  ame:  the.** sta
4a60: 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 63 6f  tement is not co
4a70: 6d 70 6c 65 74 65 20 75 6e 6c 65 73 73 20 69 74  mplete unless it
4a80: 20 65 6e 64 73 20 69 6e 20 61 20 73 65 6d 69 63   ends in a semic
4a90: 6f 6c 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  olon..*/.int sql
4aa0: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
4ab0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
4ac0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
4ad0: 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
4ae0: 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
4af0: 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
4b00: 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
4b10: 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
4b20: 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a  USY Errors.**.**
4b30: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 64   This routine id
4b40: 65 6e 74 69 66 69 65 73 20 61 20 63 61 6c 6c 62  entifies a callb
4b50: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
4b60: 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
4b70: 65 64 0a 2a 2a 20 77 68 65 6e 65 76 65 72 20 61  ed.** whenever a
4b80: 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
4b90: 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
4ba0: 62 61 73 65 20 74 61 62 6c 65 20 0a 2a 2a 20 74  base table .** t
4bb0: 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hat another thre
4bc0: 61 64 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ad or process ha
4bd0: 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 49 66 20  s locked..** If 
4be0: 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
4bf0: 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
4c00: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
4c10: 20 28 6f 72 20 73 6f 6d 65 74 69 6d 65 73 20 5b   (or sometimes [
4c20: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
4c30: 43 4b 45 44 5d 29 0a 2a 2a 20 69 73 20 72 65 74  CKED]).** is ret
4c40: 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
4c50: 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
4c60: 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ing the lock..**
4c70: 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c   If the busy cal
4c80: 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 4e 55 4c  lback is not NUL
4c90: 4c 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 63  L, then the.** c
4ca0: 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20  allback will be 
4cb0: 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
4cc0: 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
4cd0: 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65  .** first argume
4ce0: 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65  nt to the handle
4cf0: 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
4d00: 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
4d10: 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
4d20: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
4d30: 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e  to this routine.
4d40: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
4d50: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
4d60: 68 61 6e 64 6c 65 72 20 69 73 20 74 68 65 20 6e  handler is the n
4d70: 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74  umber of times t
4d80: 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  hat the busy han
4d90: 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e  dler has.** been
4da0: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69   invoked for thi
4db0: 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  s locking event.
4dc0: 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20   If the.** busy 
4dd0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
4de0: 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
4df0: 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
4e00: 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
4e10: 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
4e20: 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
4e30: 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
4e40: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
4e50: 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49  s returned..** I
4e60: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
4e70: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
4e80: 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
4e90: 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
4ea0: 20 6f 70 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74   open the.** dat
4eb0: 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
4ec0: 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  g and the cycle 
4ed0: 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
4ee0: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
4ef0: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
4f00: 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
4f10: 20 74 68 61 74 0a 2a 2a 20 69 74 20 77 69 6c 6c   that.** it will
4f20: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
4f30: 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
4f40: 6f 6e 74 65 6e 74 69 6f 6e 2e 0a 2a 2a 20 49 66  ontention..** If
4f50: 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
4f60: 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
4f70: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
4f80: 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
4f90: 6e 0a 2a 2a 20 61 20 64 65 61 64 6c 6f 63 6b 2c  n.** a deadlock,
4fa0: 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
4fb0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 6e  [SQLITE_BUSY] in
4fc0: 73 74 65 61 64 2e 0a 2a 2a 20 43 6f 6e 73 69 64  stead..** Consid
4fd0: 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
4fe0: 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
4ff0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
5000: 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
5010: 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
5020: 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
5030: 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
5040: 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
5050: 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
5060: 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
5070: 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
5080: 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
5090: 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
50a0: 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
50b0: 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
50c0: 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
50d0: 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
50e0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
50f0: 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
5100: 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
5110: 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
5120: 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
5130: 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
5140: 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
5150: 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
5160: 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
5170: 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
5180: 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
5190: 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
51a0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
51b0: 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
51c0: 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
51d0: 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
51e0: 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
51f0: 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
5200: 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
5210: 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
5220: 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
5230: 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
5240: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66  d..**.** The def
5250: 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
5260: 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
5270: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55  * The [SQLITE_BU
5280: 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
5290: 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
52a0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
52b0: 20 77 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   when.** SQLite 
52c0: 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
52d0: 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
52e0: 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
52f0: 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
5300: 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
5310: 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
5320: 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
5330: 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
5340: 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
5350: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
5360: 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
5370: 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
5380: 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
5390: 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
53a0: 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
53b0: 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
53c0: 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
53d0: 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
53e0: 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
53f0: 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
5400: 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
5410: 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
5420: 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
5430: 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
5440: 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
5450: 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
5460: 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
5470: 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
5480: 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
5490: 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
54a0: 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
54b0: 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
54c0: 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
54d0: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
54e0: 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63  ].  This error c
54f0: 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a  ode promotion.**
5500: 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d   forces an autom
5510: 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66  atic rollback of
5520: 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 53 65   the changes. Se
5530: 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
5540: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c  ="http://www.sql
5550: 69 74 65 2e 6f 72 67 2f 63 76 73 74 72 61 63 2f  ite.org/cvstrac/
5560: 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
5570: 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
5580: 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
5590: 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
55a0: 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
55b0: 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
55c0: 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
55d0: 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
55e0: 2e 0a 2a 2a 09 0a 2a 2a 20 53 71 6c 69 74 65 20  ..**..** Sqlite 
55f0: 69 73 20 72 65 2d 65 6e 74 72 61 6e 74 2c 20 73  is re-entrant, s
5600: 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
5610: 65 72 20 6d 61 79 20 73 74 61 72 74 20 61 20 6e  er may start a n
5620: 65 77 20 71 75 65 72 79 2e 20 0a 2a 2a 20 28 49  ew query. .** (I
5630: 74 20 69 73 20 6e 6f 74 20 63 6c 65 61 72 20 77  t is not clear w
5640: 68 79 20 61 6e 79 6f 6e 65 20 77 6f 75 6c 64 20  hy anyone would 
5650: 65 76 65 72 79 20 77 61 6e 74 20 74 6f 20 64 6f  every want to do
5660: 20 74 68 69 73 2c 20 62 75 74 20 69 74 0a 2a 2a   this, but it.**
5670: 20 69 73 20 61 6c 6c 6f 77 65 64 2c 20 69 6e 20   is allowed, in 
5680: 74 68 65 6f 72 79 2e 29 20 20 42 75 74 20 74 68  theory.)  But th
5690: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  e busy handler m
56a0: 61 79 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  ay not close the
56b0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 43  .** database.  C
56c0: 6c 6f 73 69 6e 67 20 74 68 65 20 64 61 74 61 62  losing the datab
56d0: 61 73 65 20 66 72 6f 6d 20 61 20 62 75 73 79 20  ase from a busy 
56e0: 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20 64 65 6c  handler will del
56f0: 65 74 65 20 0a 2a 2a 20 64 61 74 61 20 73 74 72  ete .** data str
5700: 75 63 74 75 72 65 73 20 6f 75 74 20 66 72 6f 6d  uctures out from
5710: 20 75 6e 64 65 72 20 74 68 65 20 65 78 65 63 75   under the execu
5720: 74 69 6e 67 20 71 75 65 72 79 20 61 6e 64 20 77  ting query and w
5730: 69 6c 6c 20 0a 2a 2a 20 70 72 6f 62 61 62 6c 79  ill .** probably
5740: 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
5750: 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
5760: 6f 72 20 6f 74 68 65 72 20 72 75 6e 74 69 6d 65  or other runtime
5770: 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68   error..**.** Th
5780: 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
5790: 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
57a0: 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
57b0: 72 20 65 61 63 68 20 64 61 74 61 62 61 73 65 0a  r each database.
57c0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
57d0: 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
57e0: 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
57f0: 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73 20 6f  s any previous o
5800: 6e 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ne..** Note that
5810: 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
5820: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
5830: 5d 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  ] will also set 
5840: 6f 72 20 63 6c 65 61 72 0a 2a 2a 20 74 68 65 20  or clear.** the 
5850: 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
5860: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
5870: 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
5880: 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
5890: 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  ,int), void*);..
58a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
58b0: 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
58c0: 75 74 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  ut.**.** This ro
58d0: 75 74 69 6e 65 20 73 65 74 73 20 61 20 62 75 73  utine sets a bus
58e0: 79 20 68 61 6e 64 6c 65 72 20 74 68 61 74 20 73  y handler that s
58f0: 6c 65 65 70 73 20 66 6f 72 20 61 20 77 68 69 6c  leeps for a whil
5900: 65 20 77 68 65 6e 20 61 0a 2a 2a 20 74 61 62 6c  e when a.** tabl
5910: 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68  e is locked.  Th
5920: 65 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20 73  e handler will s
5930: 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
5940: 6d 65 73 20 75 6e 74 69 6c 20 0a 2a 2a 20 61 74  mes until .** at
5950: 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
5960: 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
5970: 70 69 6e 67 20 68 61 76 65 20 62 65 65 6e 20 64  ping have been d
5980: 6f 6e 65 2e 20 20 41 66 74 65 72 0a 2a 2a 20 22  one.  After.** "
5990: 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
59a0: 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 20 74 68   of sleeping, th
59b0: 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
59c0: 73 20 30 20 77 68 69 63 68 0a 2a 2a 20 63 61 75  s 0 which.** cau
59d0: 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
59e0: 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 5b  p()] to return [
59f0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
5a00: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
5a10: 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61  OCKED]..**.** Ca
5a20: 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
5a30: 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
5a40: 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
5a50: 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
5a60: 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
5a70: 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
5a80: 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f  *.** There can o
5a90: 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
5aa0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
5ab0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
5ac0: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
5ad0: 74 69 6f 6e 2e 20 20 49 66 20 61 6e 6f 74 68 65  tion.  If anothe
5ae0: 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77  r busy handler w
5af0: 61 73 20 64 65 66 69 6e 65 64 20 20 0a 2a 2a 20  as defined  .** 
5b00: 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
5b10: 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
5b20: 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
5b30: 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
5b40: 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
5b50: 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
5b60: 65 61 72 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eared..*/.int sq
5b70: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
5b80: 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
5b90: 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
5ba0: 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
5bb0: 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
5bc0: 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
5bd0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 6e 65 78 74 20  **.** This next 
5be0: 72 6f 75 74 69 6e 65 20 69 73 20 61 20 63 6f 6e  routine is a con
5bf0: 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72  venience wrapper
5c00: 20 61 72 6f 75 6e 64 20 5b 73 71 6c 69 74 65 33   around [sqlite3
5c10: 5f 65 78 65 63 28 29 5d 2e 0a 2a 2a 20 49 6e 73  _exec()]..** Ins
5c20: 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
5c30: 20 61 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64   a user-supplied
5c40: 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 20 65 61   callback for ea
5c50: 63 68 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a  ch row of the.**
5c60: 20 72 65 73 75 6c 74 2c 20 74 68 69 73 20 72 6f   result, this ro
5c70: 75 74 69 6e 65 20 72 65 6d 65 6d 62 65 72 73 20  utine remembers 
5c80: 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20  each row of the 
5c90: 72 65 73 75 6c 74 20 69 6e 20 6d 65 6d 6f 72 79  result in memory
5ca0: 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  .** obtained fro
5cb0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
5cc0: 63 28 29 5d 2c 20 74 68 65 6e 20 72 65 74 75 72  c()], then retur
5cd0: 6e 73 20 61 6c 6c 20 6f 66 20 74 68 65 20 72 65  ns all of the re
5ce0: 73 75 6c 74 20 61 66 74 65 72 20 74 68 65 0a 2a  sult after the.*
5cf0: 2a 20 71 75 65 72 79 20 68 61 73 20 66 69 6e 69  * query has fini
5d00: 73 68 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 41 73 20  shed. .**.** As 
5d10: 61 6e 20 65 78 61 6d 70 6c 65 2c 20 73 75 70 70  an example, supp
5d20: 6f 73 65 20 74 68 65 20 71 75 65 72 79 20 72 65  ose the query re
5d30: 73 75 6c 74 20 77 68 65 72 65 20 74 68 69 73 20  sult where this 
5d40: 74 61 62 6c 65 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72  table:.**.** <pr
5d50: 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
5d60: 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
5d70: 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
5d80: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
5d90: 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
5da0: 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
5db0: 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
5dc0: 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
5dd0: 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
5de0: 31 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a  1.** </pre>.**.*
5df0: 2a 20 49 66 20 74 68 65 20 33 72 64 20 61 72 67  * If the 3rd arg
5e00: 75 6d 65 6e 74 20 77 65 72 65 20 26 61 7a 52 65  ument were &azRe
5e10: 73 75 6c 74 20 74 68 65 6e 20 61 66 74 65 72 20  sult then after 
5e20: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
5e30: 75 72 6e 73 0a 2a 2a 20 61 7a 52 65 73 75 6c 74  urns.** azResult
5e40: 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 68   will contain th
5e50: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 64 61 74 61  e following data
5e60: 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  :.**.** <pre>.**
5e70: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
5e80: 5b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  [0] = "Name";.**
5e90: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
5ea0: 5b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  [1] = "Age";.** 
5eb0: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b         azResult[
5ec0: 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
5ed0: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
5ee0: 5b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  [3] = "43";.**  
5ef0: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 34        azResult[4
5f00: 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
5f10: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 35 5d       azResult[5]
5f20: 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
5f30: 20 20 20 61 7a 52 65 73 75 6c 74 5b 36 5d 20 3d     azResult[6] =
5f40: 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
5f50: 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 37 5d 20      azResult[7] 
5f60: 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
5f70: 3e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 69 63 65 20 74  >.**.** Notice t
5f80: 68 61 74 20 74 68 65 72 65 20 69 73 20 61 6e 20  hat there is an 
5f90: 65 78 74 72 61 20 72 6f 77 20 6f 66 20 64 61 74  extra row of dat
5fa0: 61 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  a containing the
5fb0: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 68 65 61 64 65   column.** heade
5fc0: 72 73 2e 20 20 42 75 74 20 74 68 65 20 2a 6e 72  rs.  But the *nr
5fd0: 6f 77 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  ow return value 
5fe0: 69 73 20 73 74 69 6c 6c 20 33 2e 20 20 2a 6e 63  is still 3.  *nc
5ff0: 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 73 65 74 20  olumn is.** set 
6000: 74 6f 20 32 2e 20 20 49 6e 20 67 65 6e 65 72 61  to 2.  In genera
6010: 6c 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  l, the number of
6020: 20 76 61 6c 75 65 73 20 69 6e 73 65 72 74 65 64   values inserted
6030: 20 69 6e 74 6f 20 61 7a 52 65 73 75 6c 74 0a 2a   into azResult.*
6040: 2a 20 77 69 6c 6c 20 62 65 20 28 28 2a 6e 72 6f  * will be ((*nro
6050: 77 29 20 2b 20 31 29 2a 28 2a 6e 63 6f 6c 75 6d  w) + 1)*(*ncolum
6060: 6e 29 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  n)..**.** After 
6070: 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
6080: 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
6090: 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 73 75  d using the resu
60a0: 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 20 0a 2a  lt, it should .*
60b0: 2a 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  * pass the resul
60c0: 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74  t data pointer t
60d0: 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
60e0: 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
60f0: 74 6f 20 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74  to .** release t
6100: 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
6110: 61 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e 20 20 42  as malloc-ed.  B
6120: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
6130: 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  y the .** [sqlit
6140: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
6150: 70 65 6e 73 2c 20 74 68 65 20 63 61 6c 6c 69 6e  pens, the callin
6160: 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
6170: 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
6180: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
6190: 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
61a0: 4f 6e 6c 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  Only [sqlite3_fr
61b0: 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
61c0: 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 0a  ble to release .
61d0: 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  ** the memory pr
61e0: 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
61f0: 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74  y..**.** The ret
6200: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
6210: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65  s routine is the
6220: 20 73 61 6d 65 20 61 73 20 66 72 6f 6d 20 5b 73   same as from [s
6230: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 0a  qlite3_exec()]..
6240: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
6250: 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
6260: 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20  te3*,           
6270: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
6280: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
6290: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
62a0: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
62b0: 65 78 65 63 75 74 65 64 20 2a 2f 0a 20 20 63 68  executed */.  ch
62c0: 61 72 20 2a 2a 2a 72 65 73 75 6c 74 70 2c 20 20  ar ***resultp,  
62d0: 20 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 20 77       /* Result w
62e0: 72 69 74 74 65 6e 20 74 6f 20 61 20 63 68 61 72  ritten to a char
62f0: 20 2a 5b 5d 20 20 74 68 61 74 20 74 68 69 73 20   *[]  that this 
6300: 70 6f 69 6e 74 73 20 74 6f 20 2a 2f 0a 20 20 69  points to */.  i
6310: 6e 74 20 2a 6e 72 6f 77 2c 20 20 20 20 20 20 20  nt *nrow,       
6320: 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
6330: 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
6340: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
6350: 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20   int *ncolumn,  
6360: 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
6370: 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
6380: 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
6390: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
63a0: 6d 73 67 20 20 20 20 20 20 20 20 20 20 2f 2a 20  msg          /* 
63b0: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
63c0: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
63d0: 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
63e0: 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
63f0: 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
6400: 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
6410: 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
6420: 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
6430: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
6440: 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66  re workalikes of
6450: 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
6460: 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
6470: 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
6480: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
6490: 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ry..**.** The sq
64a0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
64b0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
64c0: 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
64d0: 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
64e0: 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
64f0: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
6500: 20 5b 73 71 6c 69 74 65 5f 6d 61 6c 6c 6f 63 28   [sqlite_malloc(
6510: 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
6520: 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
6530: 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
6540: 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
6550: 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
6560: 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f  te3_free()].  Bo
6570: 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
6580: 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
6590: 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
65a0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
65b0: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
65c0: 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
65d0: 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
65e0: 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
65f0: 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33  **.** In sqlite3
6600: 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
6610: 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
6620: 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
6630: 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
6640: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
6650: 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
6660: 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
6670: 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
6680: 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
6690: 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
66a0: 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
66b0: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
66c0: 72 61 6d 65 74 65 72 2e 20 20 4e 6f 74 65 20 74  rameter.  Note t
66d0: 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
66e0: 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
66f0: 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
6700: 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
6710: 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20  printf().  This 
6720: 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
6730: 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
6740: 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
6750: 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
6760: 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
6770: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
6780: 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
6790: 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
67a0: 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
67b0: 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
67c0: 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
67d0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
67e0: 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
67f0: 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
6800: 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20 57  o the buffer.  W
6810: 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
6820: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
6830: 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
6840: 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
6850: 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
6860: 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
6870: 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
6880: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
6890: 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
68a0: 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
68b0: 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
68c0: 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
68d0: 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  ** As long as th
68e0: 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
68f0: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
6900: 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
6910: 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
6920: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
6930: 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
6940: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
6950: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   The first.** pa
6960: 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
6970: 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
6980: 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
6990: 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
69a0: 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
69b0: 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
69c0: 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
69d0: 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
69e0: 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
69f0: 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
6a00: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
6a10: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
6a20: 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
6a30: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
6a40: 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
6a50: 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
6a60: 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
6a70: 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
6a80: 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
6a90: 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 20 66  e usual printf f
6aa0: 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
6ab0: 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
6ac0: 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
6ad0: 69 73 20 61 72 65 20 22 25 71 22 20 61 6e 64 20  is are "%q" and 
6ae0: 22 25 51 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%Q" options..**
6af0: 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f  .** The %q optio
6b00: 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
6b10: 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
6b20: 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65  itutes a null-te
6b30: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
6b40: 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
6b50: 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
6b60: 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
6b70: 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
6b80: 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
6b90: 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
6ba0: 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
6bb0: 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75  literal.  By dou
6bc0: 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
6bd0: 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
6be0: 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
6bf0: 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
6c00: 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
6c10: 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
6c20: 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
6c30: 72 20 65 78 61 6d 70 6c 65 2c 20 73 6f 20 73 6f  r example, so so
6c40: 6d 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  me string variab
6c50: 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  le contains text
6c60: 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
6c70: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
6c80: 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
6c90: 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
6ca0: 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
6cb0: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
6cc0: 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
6cd0: 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
6ce0: 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
6cf0: 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
6d00: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
6d10: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
6d20: 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
6d30: 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
6d40: 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
6d50: 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
6d60: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
6d70: 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
6d80: 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
6d90: 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
6da0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
6db0: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
6dc0: 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
6dd0: 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
6de0: 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
6df0: 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
6e00: 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
6e10: 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
6e20: 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
6e30: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
6e40: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
6e50: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
6e60: 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
6e70: 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
6e80: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
6e90: 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
6ea0: 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
6eb0: 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
6ec0: 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
6ed0: 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
6ee0: 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
6ef0: 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
6f00: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
6f10: 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
6f20: 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
6f30: 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
6f40: 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
6f50: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
6f60: 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
6f70: 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
6f80: 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
6f90: 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
6fa0: 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c  ule you.** shoul
6fb0: 64 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  d always use %q 
6fc0: 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
6fd0: 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
6fe0: 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
6ff0: 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  .** literal..**.
7000: 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e  ** The %Q option
7010: 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
7020: 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
7030: 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
7040: 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
7050: 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
7060: 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 4f 72 20  tal string.  Or 
7070: 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
7080: 20 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74   in the argument
7090: 0a 2a 2a 20 6c 69 73 74 20 69 73 20 61 20 4e 55  .** list is a NU
70a0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
70b0: 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
70c0: 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
70d0: 6f 75 74 20 73 69 6e 67 6c 65 0a 2a 2a 20 71 75  out single.** qu
70e0: 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f  otes) in place o
70f0: 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e  f the %Q option.
7100: 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
7110: 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
7120: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
7130: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
7140: 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
7150: 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
7160: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
7170: 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
7180: 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
7190: 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
71a0: 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
71b0: 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
71c0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
71d0: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
71e0: 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
71f0: 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
7200: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
7210: 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
7220: 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
7230: 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
7240: 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
7250: 6e 74 65 72 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73  nter..*/.char *s
7260: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
7270: 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
7280: 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
7290: 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
72a0: 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
72b0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
72c0: 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
72d0: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
72e0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
72f0: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
7300: 61 74 69 6f 6e 20 46 75 6e 63 74 69 6f 6e 73 0a  ation Functions.
7310: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
7320: 73 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79  s its own memory
7330: 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 4f 6e 20   allocator.  On 
7340: 73 6f 6d 65 20 69 6e 73 74 61 6c 6c 61 74 69 6f  some installatio
7350: 6e 73 2c 20 74 68 69 73 0a 2a 2a 20 6d 65 6d 6f  ns, this.** memo
7360: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ry allocator is 
7370: 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 74 68 65  identical to the
7380: 20 73 74 61 6e 64 61 72 64 20 6d 61 6c 6c 6f 63   standard malloc
7390: 28 29 2f 72 65 61 6c 6c 6f 63 28 29 2f 66 72 65  ()/realloc()/fre
73a0: 65 28 29 0a 2a 2a 20 61 6e 64 20 63 61 6e 20 62  e().** and can b
73b0: 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
73c0: 67 61 62 6c 65 2e 20 20 4f 6e 20 6f 74 68 65 72  gable.  On other
73d0: 73 2c 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  s, the implement
73e0: 61 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 69  ations are.** di
73f0: 66 66 65 72 65 6e 74 2e 20 20 46 6f 72 20 6d 61  fferent.  For ma
7400: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
7410: 79 2c 20 69 74 20 69 73 20 62 65 73 74 20 6e 6f  y, it is best no
7420: 74 20 74 6f 20 6d 69 78 20 63 61 6c 6c 73 0a 2a  t to mix calls.*
7430: 2a 20 74 6f 20 74 68 65 20 73 74 61 6e 64 61 72  * to the standar
7440: 64 20 6d 61 6c 6c 6f 63 2f 72 65 61 6c 6c 6f 63  d malloc/realloc
7450: 2f 66 72 65 65 20 77 69 74 68 20 74 68 65 20 73  /free with the s
7460: 71 6c 69 74 65 20 76 65 72 73 69 6f 6e 73 2e 0a  qlite versions..
7470: 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
7480: 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
7490: 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
74a0: 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
74b0: 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
74c0: 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
74d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
74e0: 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
74f0: 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
7500: 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  .***.** This rou
7510: 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
7520: 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
7530: 62 61 63 6b 20 77 69 74 68 20 74 68 65 20 53 51  back with the SQ
7540: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 0a  Lite library.  .
7550: 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
7560: 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
7570: 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
7580: 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
7590: 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
75a0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
75b0: 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
75c0: 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
75d0: 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
75e0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
75f0: 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
7600: 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
7610: 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a  )].  At various.
7620: 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
7630: 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
7640: 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
7650: 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
7660: 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
7670: 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
7680: 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
7690: 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
76a0: 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
76b0: 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
76c0: 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54   are allowed.  T
76d0: 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
76e0: 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
76f0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
7700: 4b 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  K to allow the a
7710: 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
7720: 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
7730: 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
7740: 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
7750: 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
7760: 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
7770: 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
7780: 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
7790: 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
77a0: 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
77b0: 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
77c0: 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
77d0: 6e 20 65 72 72 6f 72 2e 20 20 0a 2a 2a 0a 2a 2a  n error.  .**.**
77e0: 20 44 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   Depending on th
77f0: 65 20 61 63 74 69 6f 6e 2c 20 74 68 65 20 5b 53  e action, the [S
7800: 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 61 6e  QLITE_IGNORE] an
7810: 64 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  d [SQLITE_DENY] 
7820: 72 65 74 75 72 6e 0a 2a 2a 20 63 6f 64 65 73 20  return.** codes 
7830: 6d 69 67 68 74 20 6d 65 61 6e 20 73 6f 6d 65 74  might mean somet
7840: 68 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 6f  hing different o
7850: 72 20 74 68 65 79 20 6d 69 67 68 74 20 6d 65 61  r they might mea
7860: 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 68  n the same.** th
7870: 69 6e 67 2e 20 20 49 66 20 74 68 65 20 61 63 74  ing.  If the act
7880: 69 6f 6e 20 69 73 2c 20 66 6f 72 20 65 78 61 6d  ion is, for exam
7890: 70 6c 65 2c 20 74 6f 20 70 65 72 66 6f 72 6d 20  ple, to perform 
78a0: 61 20 64 65 6c 65 74 65 20 6f 70 65 72 74 69 6f  a delete opertio
78b0: 6e 2c 0a 2a 2a 20 74 68 65 6e 20 5b 53 51 4c 49  n,.** then [SQLI
78c0: 54 45 5f 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b  TE_IGNORE] and [
78d0: 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 62 6f 74  SQLITE_DENY] bot
78e0: 68 20 63 61 75 73 65 20 74 68 65 20 73 74 61 74  h cause the stat
78f0: 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 61 74 69 6f  ement compilatio
7900: 6e 0a 2a 2a 20 74 6f 20 66 61 69 6c 20 77 69 74  n.** to fail wit
7910: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 42 75 74  h an error.  But
7920: 20 69 66 20 74 68 65 20 61 63 74 69 6f 6e 20 69   if the action i
7930: 73 20 74 6f 20 72 65 61 64 20 61 20 73 70 65 63  s to read a spec
7940: 69 66 69 63 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 66  ific column.** f
7950: 72 6f 6d 20 61 20 73 70 65 63 69 66 69 63 20 74  rom a specific t
7960: 61 62 6c 65 2c 20 74 68 65 6e 20 5b 53 51 4c 49  able, then [SQLI
7970: 54 45 5f 44 45 4e 59 5d 20 77 69 6c 6c 20 63 61  TE_DENY] will ca
7980: 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 0a 2a  use the entire.*
7990: 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 66  * statement to f
79a0: 61 69 6c 20 62 75 74 20 5b 53 51 4c 49 54 45 5f  ail but [SQLITE_
79b0: 49 47 4e 4f 52 45 5d 20 77 69 6c 6c 20 63 61 75  IGNORE] will cau
79c0: 73 65 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  se a NULL value 
79d0: 74 6f 20 62 65 0a 2a 2a 20 72 65 61 64 20 69 6e  to be.** read in
79e0: 73 74 65 61 64 20 6f 66 20 74 68 65 20 61 63 74  stead of the act
79f0: 75 61 6c 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  ual column value
7a00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
7a10: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
7a20: 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
7a30: 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
7a40: 20 6f 66 0a 2a 2a 20 74 68 65 20 74 68 69 72 64   of.** the third
7a50: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
7a60: 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
7a70: 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
7a80: 66 61 63 65 2e 0a 2a 2a 20 54 68 65 20 73 65 63  face..** The sec
7a90: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
7aa0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
7ab0: 20 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20   an integer .** 
7ac0: 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
7ad0: 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
7ae0: 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70   specifies the p
7af0: 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
7b00: 0a 2a 2a 20 74 6f 20 62 65 20 61 75 74 68 6f 72  .** to be author
7b10: 69 7a 65 64 2e 20 20 54 68 65 20 61 76 61 69 6c  ized.  The avail
7b20: 61 62 6c 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  able action code
7b30: 73 20 61 72 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s are.** [SQLITE
7b40: 5f 43 4f 50 59 20 7c 20 64 6f 63 75 6d 65 6e 74  _COPY | document
7b50: 65 64 20 73 65 70 61 72 61 74 65 6c 79 5d 2e 20  ed separately]. 
7b60: 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75   The third throu
7b70: 67 68 20 73 69 78 74 68 0a 2a 2a 20 70 61 72 61  gh sixth.** para
7b80: 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61  meters to the ca
7b90: 6c 6c 62 61 63 6b 20 61 72 65 20 73 74 72 69 6e  llback are strin
7ba0: 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  gs that contain 
7bb0: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65  additional.** de
7bc0: 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
7bd0: 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
7be0: 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41  horized..**.** A
7bf0: 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
7c00: 75 73 65 64 20 77 68 65 6e 20 70 72 65 70 61 72  used when prepar
7c10: 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
7c20: 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
7c30: 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65 2c 20  sted.** source, 
7c40: 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
7c50: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
7c60: 73 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  s do not try to 
7c70: 61 63 63 65 73 73 20 64 61 74 61 0a 2a 2a 20 74  access data.** t
7c80: 68 61 74 20 74 68 65 79 20 61 72 65 20 6e 6f 74  hat they are not
7c90: 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
7ca0: 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
7cb0: 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a 20 65   not try to.** e
7cc0: 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
7cd0: 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
7ce0: 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
7cf0: 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
7d00: 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
7d10: 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
7d20: 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
7d30: 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
7d40: 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
7d50: 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
7d60: 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
7d70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
7d80: 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
7d90: 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
7da0: 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
7db0: 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
7dc0: 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
7dd0: 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
7de0: 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
7df0: 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
7e00: 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
7e10: 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
7e20: 70 72 65 70 61 72 65 64 20 74 68 61 74 20 64 69  prepared that di
7e30: 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
7e40: 6e 67 0a 2a 2a 20 65 78 63 65 70 74 20 53 45 4c  ng.** except SEL
7e50: 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  ECT statements. 
7e60: 20 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73   .**.** Only a s
7e70: 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
7e80: 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
7e90: 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
7ea0: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
7eb0: 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
7ec0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
7ed0: 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
7ee0: 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
7ef0: 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 41 20  evious call.  A 
7f00: 4e 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20  NULL authorizer 
7f10: 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75  means that no au
7f20: 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
7f30: 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
7f40: 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
7f50: 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e   authorizer is N
7f60: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ULL..**.** Note 
7f70: 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
7f80: 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
7f90: 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
7fa0: 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
7fb0: 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
7fc0: 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
7fd0: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
7fe0: 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
7ff0: 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
8000: 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
8010: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
8020: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
8030: 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
8040: 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
8050: 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
8060: 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
8070: 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
8080: 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
8090: 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
80a0: 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
80b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
80c0: 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
80d0: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
80e0: 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
80f0: 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
8100: 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
8110: 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
8120: 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
8130: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
8140: 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
8150: 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
8160: 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
8170: 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
8180: 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
8190: 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
81a0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
81b0: 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
81c0: 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
81d0: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
81e0: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
81f0: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64  formation..*/.#d
8200: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
8210: 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
8220: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
8230: 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
8240: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8250: 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
8260: 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
8270: 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
8280: 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
8290: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
82a0: 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
82b0: 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
82c0: 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
82d0: 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
82e0: 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
82f0: 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
8300: 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
8310: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
8320: 61 75 74 68 6f 72 69 7a 65 72 20 63 65 72 74 61  authorizer certa
8330: 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
8340: 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
8350: 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
8360: 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
8370: 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
8380: 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
8390: 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
83a0: 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
83b0: 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
83c0: 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
83d0: 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
83e0: 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
83f0: 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
8400: 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
8410: 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
8420: 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
8430: 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
8440: 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
8450: 62 65 20 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  be .** authorize
8460: 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
8470: 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
8480: 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
8490: 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ion callback.** 
84a0: 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
84b0: 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
84c0: 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
84d0: 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
84e0: 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
84f0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
8500: 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 35  arameter.  The 5
8510: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
8520: 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
8530: 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
8540: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
8550: 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
8560: 22 74 65 6d 70 22 2c 20 0a 2a 2a 20 65 74 63 2e  "temp", .** etc.
8570: 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
8580: 20 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65    The 6th parame
8590: 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
85a0: 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
85b0: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
85c0: 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
85d0: 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
85e0: 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
85f0: 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
8600: 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
8610: 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
8620: 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
8630: 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a  directly from .*
8640: 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
8650: 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
8660: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
8670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
8680: 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
8690: 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
86a0: 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
86b0: 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
86c0: 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
86d0: 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
86e0: 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
86f0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
8700: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
8710: 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
8720: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
8730: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
8740: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
8750: 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
8760: 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
8770: 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
8780: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
8790: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
87a0: 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
87b0: 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
87c0: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
87d0: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
87e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
87f0: 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
8800: 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
8810: 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
8820: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
8830: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8840: 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
8850: 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
8860: 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
8870: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
8880: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8890: 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
88a0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
88b0: 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
88c0: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
88d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
88e0: 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
88f0: 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
8900: 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
8910: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
8920: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
8930: 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
8940: 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
8950: 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
8960: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
8970: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
8980: 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
8990: 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
89a0: 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
89b0: 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
89c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
89d0: 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
89e0: 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
89f0: 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
8a00: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
8a10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
8a20: 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
8a30: 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
8a40: 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
8a50: 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
8a60: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
8a70: 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
8a80: 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
8a90: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
8aa0: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
8ab0: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
8ac0: 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
8ad0: 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
8ae0: 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
8af0: 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
8b00: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
8b10: 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
8b20: 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
8b30: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
8b40: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
8b50: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
8b60: 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
8b70: 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
8b80: 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
8b90: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
8ba0: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
8bb0: 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
8bc0: 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
8bd0: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
8be0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
8bf0: 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
8c00: 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
8c10: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
8c20: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
8c30: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
8c40: 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
8c50: 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
8c60: 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
8c70: 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
8c80: 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
8c90: 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
8ca0: 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
8cb0: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
8cc0: 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
8cd0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8ce0: 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
8cf0: 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
8d00: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
8d10: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
8d20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8d30: 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
8d40: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e         22   /* N
8d50: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
8d60: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
8d70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8d80: 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
8d90: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
8da0: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
8db0: 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
8dc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8dd0: 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
8de0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
8df0: 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
8e00: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
8e10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
8e20: 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
8e30: 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
8e40: 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
8e50: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
8e60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
8e70: 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
8e80: 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
8e90: 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
8ea0: 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
8eb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
8ec0: 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
8ed0: 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
8ee0: 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
8ef0: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
8f00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
8f10: 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
8f20: 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
8f30: 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
8f40: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
8f50: 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
8f60: 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
8f70: 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
8f80: 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
8f90: 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
8fa0: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
8fb0: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
8fc0: 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
8fd0: 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
8fe0: 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
8ff0: 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
9000: 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
9010: 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e     /* Function N
9020: 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
9030: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
9040: 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
9050: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
9060: 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
9070: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
9080: 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
9090: 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
90a0: 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
90b0: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
90c0: 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
90d0: 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
90e0: 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
90f0: 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
9100: 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
9110: 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
9120: 65 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 63  ements..** The c
9130: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
9140: 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
9150: 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
9160: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 74 20  s invoked.** at 
9170: 74 68 65 20 66 69 72 73 74 20 5b 73 71 6c 69 74  the first [sqlit
9180: 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 74  e3_step()] for t
9190: 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
91a0: 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
91b0: 74 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  t..** The callba
91c0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
91d0: 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
91e0: 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
91f0: 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
9200: 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
9210: 66 69 6e 69 73 68 65 73 20 61 6e 64 20 69 6e 63  finishes and inc
9220: 6c 75 64 65 73 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ludes.** informa
9230: 74 69 6f 6e 20 6f 6e 20 68 6f 77 20 6c 6f 6e 67  tion on how long
9240: 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
9250: 72 61 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ran..**.** The s
9260: 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
9270: 20 41 50 49 20 69 73 20 63 75 72 72 65 6e 74 6c   API is currentl
9280: 79 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  y considered exp
9290: 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a  erimental and.**
92a0: 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63   is subject to c
92b0: 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  hange..*/.void *
92c0: 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
92d0: 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54  lite3*, void(*xT
92e0: 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
92f0: 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
9300: 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
9310: 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
9320: 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
9330: 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
9340: 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 5f 75 69   char*,sqlite_ui
9350: 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
9360: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9370: 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
9380: 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54  allbacks.**.** T
9390: 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66  his routine conf
93a0: 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63  igures a callbac
93b0: 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65  k function - the
93c0: 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
93d0: 63 6b 20 2d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ck - that.** is 
93e0: 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
93f0: 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
9400: 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
9410: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
9420: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
9430: 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
9440: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
9450: 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  ].  An example u
9460: 73 65 20 66 6f 72 20 74 68 69 73 20 0a 2a 2a 20  se for this .** 
9470: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
9480: 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
9490: 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
94a0: 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 54  e query..**.** T
94b0: 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
94c0: 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
94d0: 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e  once for every N
94e0: 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
94f0: 20 6f 70 63 6f 64 65 73 2c 0a 2a 2a 20 77 68 65   opcodes,.** whe
9500: 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
9510: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
9520: 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  his function. Th
9530: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
9540: 61 63 6b 0a 2a 2a 20 69 74 73 65 6c 66 20 69 73  ack.** itself is
9550: 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
9560: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
9570: 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  t to this functi
9580: 6f 6e 2e 20 54 68 65 20 66 6f 75 72 74 68 0a 2a  on. The fourth.*
9590: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  * argument to th
95a0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
95b0: 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70 61   void pointer pa
95c0: 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f 67  ssed to the prog
95d0: 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  ress callback.**
95e0: 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74   function each t
95f0: 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  ime it is invoke
9600: 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 61  d..**.** If a ca
9610: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ll to [sqlite3_e
9620: 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
9630: 5f 73 74 65 70 28 29 5d 2c 20 6f 72 20 5b 73 71  _step()], or [sq
9640: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
9650: 29 5d 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  )].** results in
9660: 20 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70   fewer than N op
9670: 63 6f 64 65 73 20 62 65 69 6e 67 20 65 78 65 63  codes being exec
9680: 75 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20 70  uted, then the p
9690: 72 6f 67 72 65 73 73 20 0a 2a 2a 20 63 61 6c 6c  rogress .** call
96a0: 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e  back is never in
96b0: 76 6f 6b 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 4f 6e  voked..** .** On
96c0: 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
96d0: 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 66 75  ress callback fu
96e0: 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
96f0: 67 69 73 74 65 72 65 64 20 66 6f 72 20 65 61 63  gistered for eac
9700: 68 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61  h.** open databa
9710: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
9720: 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 73 71  Every call to sq
9730: 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
9740: 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 6f 76 65 72  andler().** over
9750: 77 72 69 74 65 73 20 74 68 65 20 72 65 73 75 6c  writes the resul
9760: 74 73 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  ts of the previo
9770: 75 73 20 63 61 6c 6c 2e 0a 2a 2a 20 54 6f 20 72  us call..** To r
9780: 65 6d 6f 76 65 20 74 68 65 20 70 72 6f 67 72 65  emove the progre
9790: 73 73 20 63 61 6c 6c 62 61 63 6b 20 61 6c 74 6f  ss callback alto
97a0: 67 65 74 68 65 72 2c 20 70 61 73 73 20 4e 55 4c  gether, pass NUL
97b0: 4c 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  L as the third.*
97c0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  * argument to th
97d0: 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
97e0: 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  ** If the progre
97f0: 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
9800: 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68  rns a result oth
9810: 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 20  er than 0, then 
9820: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
9830: 71 75 65 72 79 20 69 73 20 69 6d 6d 65 64 69 61  query is immedia
9840: 74 65 6c 79 20 74 65 72 6d 69 6e 61 74 65 64 20  tely terminated 
9850: 61 6e 64 20 61 6e 79 20 64 61 74 61 62 61 73 65  and any database
9860: 20 63 68 61 6e 67 65 73 20 72 6f 6c 6c 65 64 20   changes rolled 
9870: 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 63 6f 6e  back..** The con
9880: 74 61 69 6e 69 6e 67 20 5b 73 71 6c 69 74 65 33  taining [sqlite3
9890: 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
98a0: 65 33 5f 73 74 65 70 28 29 5d 2c 20 6f 72 0a 2a  e3_step()], or.*
98b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
98c0: 61 62 6c 65 28 29 5d 20 63 61 6c 6c 20 72 65 74  able()] call ret
98d0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4e 54 45  urns SQLITE_INTE
98e0: 52 52 55 50 54 2e 20 20 20 54 68 69 73 20 66 65  RRUPT.   This fe
98f0: 61 74 75 72 65 0a 2a 2a 20 63 61 6e 20 62 65 20  ature.** can be 
9900: 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
9910: 65 2c 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  e, to implement 
9920: 74 68 65 20 22 43 61 6e 63 65 6c 22 20 62 75 74  the "Cancel" but
9930: 74 6f 6e 20 6f 6e 20 61 0a 2a 2a 20 70 72 6f 67  ton on a.** prog
9940: 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 20  ress dialog box 
9950: 69 6e 20 61 20 47 55 49 2e 0a 2a 2f 0a 76 6f 69  in a GUI..*/.voi
9960: 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
9970: 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
9980: 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
9990: 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
99a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
99b0: 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
99c0: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
99d0: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 74  ion.**.** Open t
99e0: 68 65 20 73 71 6c 69 74 65 20 64 61 74 61 62 61  he sqlite databa
99f0: 73 65 20 66 69 6c 65 20 22 66 69 6c 65 6e 61 6d  se file "filenam
9a00: 65 22 2e 20 20 54 68 65 20 22 66 69 6c 65 6e 61  e".  The "filena
9a10: 6d 65 22 20 69 73 20 55 54 46 2d 38 0a 2a 2a 20  me" is UTF-8.** 
9a20: 65 6e 63 6f 64 65 64 20 66 6f 72 20 73 71 6c 69  encoded for sqli
9a30: 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 55  te3_open() and U
9a40: 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 69 6e  TF-16 encoded in
9a50: 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
9a60: 20 6f 72 64 65 72 0a 2a 2a 20 66 6f 72 20 73 71   order.** for sq
9a70: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
9a80: 20 41 6e 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68   An [sqlite3*] h
9a90: 61 6e 64 6c 65 20 69 73 20 72 65 74 75 72 6e 65  andle is returne
9aa0: 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
9ab0: 0a 2a 2a 20 69 66 20 61 6e 20 65 72 72 6f 72 20  .** if an error 
9ac0: 6f 63 63 75 72 73 2e 20 49 66 20 74 68 65 20 64  occurs. If the d
9ad0: 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
9ae0: 64 20 28 6f 72 20 63 72 65 61 74 65 64 29 20 73  d (or created) s
9af0: 75 63 63 65 73 73 66 75 6c 6c 79 2c 0a 2a 2a 20  uccessfully,.** 
9b00: 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  then SQLITE_OK i
9b10: 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68 65  s returned. Othe
9b20: 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 63  rwise an error c
9b30: 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ode is returned.
9b40: 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
9b50: 65 72 72 6d 73 67 28 29 20 6f 72 20 73 71 6c 69  errmsg() or sqli
9b60: 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 20  te3_errmsg16()  
9b70: 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
9b80: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
9b90: 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
9ba0: 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
9bb0: 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a  n of the error..
9bc0: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  **.** If the dat
9bd0: 61 62 61 73 65 20 66 69 6c 65 20 64 6f 65 73 20  abase file does 
9be0: 6e 6f 74 20 65 78 69 73 74 2c 20 74 68 65 6e 20  not exist, then 
9bf0: 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 77  a new database w
9c00: 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 0a 2a  ill be created.*
9c10: 2a 20 61 73 20 6e 65 65 64 65 64 2e 20 20 54 68  * as needed.  Th
9c20: 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
9c30: 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
9c40: 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
9c50: 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  8 if.** sqlite3_
9c60: 6f 70 65 6e 28 29 20 69 73 20 63 61 6c 6c 65 64  open() is called
9c70: 20 61 6e 64 20 55 54 46 2d 31 36 20 69 66 20 73   and UTF-16 if s
9c80: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 20 69 73  qlite3_open16 is
9c90: 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
9ca0: 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
9cb0: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
9cc0: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
9cd0: 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63 69 61  esources associa
9ce0: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
9cf0: 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c  [sqlite3*] handl
9d00: 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
9d10: 61 73 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ased by passing 
9d20: 69 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  it to.** sqlite3
9d30: 5f 63 6c 6f 73 65 28 29 20 77 68 65 6e 20 69 74  _close() when it
9d40: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
9d50: 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  quired..**.** No
9d60: 74 65 20 74 6f 20 77 69 6e 64 6f 77 73 20 75 73  te to windows us
9d70: 65 72 73 3a 20 20 54 68 65 20 65 6e 63 6f 64 69  ers:  The encodi
9d80: 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
9d90: 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
9da0: 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
9db0: 6f 70 65 6e 28 29 20 6d 75 73 74 20 62 65 20 55  open() must be U
9dc0: 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
9dd0: 65 72 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  er codepage is c
9de0: 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 64 65 66 69  urrently.** defi
9df0: 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
9e00: 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
9e10: 6e 61 74 69 6f 6e 61 6c 20 63 68 61 72 61 63 74  national charact
9e20: 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
9e30: 65 72 74 65 64 0a 2a 2a 20 74 6f 20 55 54 46 2d  erted.** to UTF-
9e40: 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
9e50: 6e 67 20 74 68 65 6d 20 69 6e 74 6f 20 73 71 6c  ng them into sql
9e60: 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2f 0a  ite3_open()..*/.
9e70: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
9e80: 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
9e90: 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
9ea0: 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
9eb0: 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
9ec0: 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
9ed0: 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
9ee0: 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
9ef0: 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
9f00: 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
9f10: 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
9f20: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
9f30: 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
9f40: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
9f50: 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
9f60: 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
9f70: 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  handle */.);../*
9f80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
9f90: 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
9fa0: 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ssages.**.** The
9fb0: 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
9fc0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
9fd0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
9fe0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c  .** [SQLITE_OK |
9ff0: 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72   result code] or
a000: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
a010: 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72  EAD | extended r
a020: 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 66  esult code].** f
a030: 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
a040: 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
a050: 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73  3_* API call ass
a060: 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
a070: 5b 73 71 6c 69 74 65 33 5d 20 68 61 6e 64 6c 65  [sqlite3] handle
a080: 20 27 64 62 27 2e 20 20 49 66 20 61 20 70 72 69   'db'.  If a pri
a090: 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
a0a0: 65 64 20 62 75 74 20 74 68 65 0a 2a 2a 20 6d 6f  ed but the.** mo
a0b0: 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
a0c0: 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
a0d0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
a0e0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63  rom sqlite3_errc
a0f0: 6f 64 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65  ode().** is unde
a100: 66 69 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68  fined. .**.** Th
a110: 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
a120: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
a130: 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
a140: 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 61 75 67   English-langaug
a150: 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
a160: 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
a170: 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
a180: 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 73 70  F8 or UTF16 resp
a190: 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d  ectively..** Mem
a1a0: 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
a1b0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
a1c0: 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
a1d0: 69 6e 74 65 72 6e 61 6c 6c 79 2e 20 20 54 68 65  internally.  The
a1e0: 20 0a 2a 2a 20 73 74 72 69 6e 67 20 6d 61 79 20   .** string may 
a1f0: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
a200: 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
a210: 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
a220: 73 20 74 6f 20 53 51 4c 69 74 65 0a 2a 2a 20 69  s to SQLite.** i
a230: 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
a240: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 73 20  ns..**.** Calls 
a250: 74 6f 20 6d 61 6e 79 20 73 71 6c 69 74 65 33 5f  to many sqlite3_
a260: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 73 65 74 20  * functions set 
a270: 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61  the error code a
a280: 6e 64 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  nd string return
a290: 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
a2a0: 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73  3_errcode()], [s
a2b0: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
a2c0: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  , and [sqlite3_e
a2d0: 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 28 6f  rrmsg16()].** (o
a2e0: 76 65 72 77 72 69 74 69 6e 67 20 74 68 65 20 70  verwriting the p
a2f0: 72 65 76 69 6f 75 73 20 76 61 6c 75 65 73 29 2e  revious values).
a300: 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 73   Note that calls
a310: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
a320: 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  code()],.** [sql
a330: 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20  ite3_errmsg()], 
a340: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
a350: 6d 73 67 31 36 28 29 5d 20 74 68 65 6d 73 65 6c  msg16()] themsel
a360: 76 65 73 20 64 6f 20 6e 6f 74 20 61 66 66 65 63  ves do not affec
a370: 74 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 73  t the.** results
a380: 20 6f 66 20 66 75 74 75 72 65 20 69 6e 76 6f 63   of future invoc
a390: 61 74 69 6f 6e 73 2e 20 20 43 61 6c 6c 73 20 74  ations.  Calls t
a3a0: 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74  o API routines t
a3b0: 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72  hat do not retur
a3c0: 6e 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f  n.** an error co
a3d0: 64 65 20 28 65 78 61 6d 70 6c 65 73 3a 20 5b 73  de (examples: [s
a3e0: 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
a3f0: 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
a400: 5f 6d 70 72 69 6e 74 66 28 29 5d 29 20 64 6f 0a  _mprintf()]) do.
a410: 2a 2a 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  ** not change th
a420: 65 20 65 72 72 6f 72 20 63 6f 64 65 20 72 65 74  e error code ret
a430: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f  urned by this ro
a440: 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 41 73 73  utine..**.** Ass
a450: 75 6d 69 6e 67 20 6e 6f 20 6f 74 68 65 72 20 69  uming no other i
a460: 6e 74 65 72 76 65 6e 69 6e 67 20 73 71 6c 69 74  ntervening sqlit
a470: 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 73 20 61  e3_* API calls a
a480: 72 65 20 6d 61 64 65 2c 20 74 68 65 20 65 72 72  re made, the err
a490: 6f 72 0a 2a 2a 20 63 6f 64 65 20 72 65 74 75 72  or.** code retur
a4a0: 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
a4b0: 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74  tion is associat
a4c0: 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ed with the same
a4d0: 20 65 72 72 6f 72 20 61 73 0a 2a 2a 20 74 68 65   error as.** the
a4e0: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
a4f0: 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72  d by [sqlite3_er
a500: 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c  rmsg()] and [sql
a510: 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
a520: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
a530: 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
a540: 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
a550: 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
a560: 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
a570: 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
a580: 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
a590: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
a5a0: 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d  3REF: SQL Statem
a5b0: 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
a5c0: 20 49 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   Instance of thi
a5d0: 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
a5e0: 6e 74 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74  nt single SQL st
a5f0: 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 0a  atements.  This.
a600: 2a 2a 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ** is variously 
a610: 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
a620: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
a630: 6f 72 20 61 20 0a 2a 2a 20 22 63 6f 6d 70 69 6c  or a .** "compil
a640: 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
a650: 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61  " or simply as a
a660: 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a   "statement"..**
a670: 20 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66   .** The life of
a680: 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
a690: 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
a6a0: 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
a6b0: 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
a6c0: 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
a6d0: 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
a6e0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
a6f0: 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
a700: 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
a710: 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
a720: 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
a730: 65 74 65 72 73 20 75 73 69 6e 67 0a 2a 2a 20 20  eters using.**  
a740: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
a750: 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
a760: 5f 62 69 6e 64 5f 2a 20 69 6e 74 65 72 66 61 63  _bind_* interfac
a770: 65 73 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  es]..** <li> Run
a780: 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
a790: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
a7a0: 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
a7b0: 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
a7c0: 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
a7d0: 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
a7e0: 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
a7f0: 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
a800: 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
a810: 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
a820: 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
a830: 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
a840: 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
a850: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
a860: 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
a870: 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
a880: 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
a890: 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
a8a0: 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
a8b0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
a8c0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
a8d0: 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
a8e0: 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
a8f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
a900: 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
a910: 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
a920: 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
a930: 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
a940: 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
a950: 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
a960: 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
a970: 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
a980: 65 20 72 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a  e routines. .**.
a990: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
a9a0: 75 6d 65 6e 74 20 22 64 62 22 20 69 73 20 61 6e  ument "db" is an
a9b0: 20 5b 73 71 6c 69 74 65 33 20 7c 20 53 51 4c 69   [sqlite3 | SQLi
a9c0: 74 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  te database hand
a9d0: 6c 65 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e 65 64  le] .** obtained
a9e0: 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 20 63 61   from a prior ca
a9f0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
aa00: 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  pen()] or [sqlit
aa10: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
aa20: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
aa30: 6d 65 6e 74 20 22 7a 53 71 6c 22 20 69 73 20 74  ment "zSql" is t
aa40: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
aa50: 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
aa60: 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
aa70: 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
aa80: 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
aa90: 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
aaa0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
aab0: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
aac0: 20 75 73 65 73 20 55 54 46 2d 38 20 61 6e 64 20   uses UTF-8 and 
aad0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
aae0: 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
aaf0: 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
ab00: 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 20 49 66  * use UTF-16. If
ab10: 20 74 68 65 20 6e 65 78 74 20 61 72 67 75 6d 65   the next argume
ab20: 6e 74 2c 20 22 6e 42 79 74 65 73 22 2c 20 69 73  nt, "nBytes", is
ab30: 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a 65   less.** than ze
ab40: 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
ab50: 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20   read up to the 
ab60: 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
ab70: 6e 61 74 6f 72 2e 20 20 49 66 0a 2a 2a 20 22 6e  nator.  If.** "n
ab80: 42 79 74 65 73 22 20 69 73 20 6e 6f 74 20 6c 65  Bytes" is not le
ab90: 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68  ss than zero, th
aba0: 65 6e 20 69 74 20 69 73 20 74 68 65 20 6c 65 6e  en it is the len
abb0: 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
abc0: 67 20 7a 53 71 6c 0a 2a 2a 20 69 6e 20 62 79 74  g zSql.** in byt
abd0: 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
abe0: 72 73 29 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61  rs)..**.** *pzTa
abf0: 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
ac00: 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
ac10: 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65   byte past the e
ac20: 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 0a  nd of the first.
ac30: 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
ac40: 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 69 73 20   in zSql.  This 
ac50: 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6d  routine only com
ac60: 70 69 6c 65 73 20 74 68 65 20 66 69 72 73 74 20  piles the first 
ac70: 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 69 6e 20  statement.** in 
ac80: 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
ac90: 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
aca0: 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e  g to what remain
acb0: 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
acc0: 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c  .** *ppStmt is l
acd0: 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
ace0: 61 20 63 6f 6d 70 69 6c 65 64 20 0a 2a 2a 20 5b  a compiled .** [
acf0: 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 53  sqlite3_stmt | S
ad00: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 73 74 72  QL statement str
ad10: 75 63 74 75 72 65 5d 20 74 68 61 74 20 63 61 6e  ucture] that can
ad20: 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
ad30: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
ad40: 74 65 70 28 29 5d 2e 20 20 4f 72 20 69 66 20 74  tep()].  Or if t
ad50: 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
ad60: 2c 20 2a 70 70 53 74 6d 74 20 6d 61 79 20 62 65  , *ppStmt may be
ad70: 0a 2a 2a 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e  .** set to NULL.
ad80: 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 20 74    If the input t
ad90: 65 78 74 20 63 6f 6e 74 61 69 6e 65 64 20 6e 6f  ext contained no
ada0: 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
adb0: 75 74 20 69 73 20 61 6e 64 0a 2a 2a 20 65 6d 70  ut is and.** emp
adc0: 74 79 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ty string or a c
add0: 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
ade0: 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
adf0: 55 4c 4c 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e  ULL.  The callin
ae00: 67 0a 2a 2a 20 70 72 6f 63 65 64 75 72 65 20 69  g.** procedure i
ae10: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
ae20: 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
ae30: 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
ae40: 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e 67 20 5b  ement.** using [
ae50: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
ae60: 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
ae70: 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
ae80: 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63  t..**.** On succ
ae90: 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
aea0: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
aeb0: 74 68 65 72 77 69 73 65 20 61 6e 20 0a 2a 2a 20  therwise an .** 
aec0: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
aed0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
aee0: 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
aef0: 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
af00: 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
af10: 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
af20: 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
af30: 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
af40: 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
af50: 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
af60: 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
af70: 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
af80: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
af90: 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
afa0: 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
afb0: 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e  scouraged..** In
afc0: 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
afd0: 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
afe0: 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
aff0: 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
b000: 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
b010: 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
b020: 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
b030: 74 68 65 20 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c  the .** original
b040: 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
b050: 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
b060: 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
b070: 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
b080: 76 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79  ve a differently
b090: 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a   in two ways:.**
b0a0: 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
b0b0: 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
b0c0: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
b0d0: 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
b0e0: 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
b0f0: 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
b100: 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
b110: 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
b120: 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
b130: 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
b140: 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
b150: 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
b160: 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
b170: 20 20 49 66 20 74 68 65 20 73 63 68 65 6d 61 20    If the schema 
b180: 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 20 61  has changed in a
b190: 20 77 61 79 0a 2a 2a 20 74 68 61 74 20 6d 61 6b   way.** that mak
b1a0: 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  es the statement
b1b0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64   no longer valid
b1c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
b1d0: 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a  )] will still.**
b1e0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
b1f0: 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e  SCHEMA].  But un
b200: 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20  like the legacy 
b210: 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54  behavior, [SQLIT
b220: 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20  E_SCHEMA] is.** 
b230: 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f  now a fatal erro
b240: 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  r.  Calling [sql
b250: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
b260: 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f  )] again will no
b270: 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72  t make the.** er
b280: 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f  ror go away.  No
b290: 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33  te: use [sqlite3
b2a0: 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69  _errmsg()] to fi
b2b0: 6e 64 20 74 68 65 20 74 65 78 74 20 6f 66 20 74  nd the text of t
b2c0: 68 65 20 70 61 72 73 69 6e 67 0a 2a 2a 20 65 72  he parsing.** er
b2d0: 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73  ror that results
b2e0: 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53   in an [SQLITE_S
b2f0: 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a  CHEMA] return..*
b300: 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
b310: 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72  i>.** When an er
b320: 72 6f 72 20 6f 63 63 75 72 73 2c 20 0a 2a 2a 20  ror occurs, .** 
b330: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
b340: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
b350: 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
b360: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
b370: 4f 52 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OR | result code
b380: 73 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  s] or.** [SQLITE
b390: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
b3a0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
b3b0: 64 65 73 5d 20 73 75 63 68 20 61 73 20 64 69 72  des] such as dir
b3c0: 65 63 74 6c 79 2e 0a 2a 2a 20 54 68 65 20 6c 65  ectly..** The le
b3d0: 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
b3e0: 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
b3f0: 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
b400: 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
b410: 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  ric.** [SQLITE_E
b420: 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
b430: 65 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20  e and you would 
b440: 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
b450: 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a  econd call to.**
b460: 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
b470: 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
b480: 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
b490: 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
b4a0: 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68  problem..** With
b4b0: 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
b4c0: 65 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  e interfaces, th
b4d0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
b4e0: 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
b4f0: 72 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64  r is.** returned
b500: 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
b510: 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
b520: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
b530: 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
b540: 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
b550: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
b560: 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
b570: 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
b580: 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
b590: 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
b5a0: 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
b5b0: 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  s,             /
b5c0: 2a 20 4c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  * Length of zSql
b5d0: 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
b5e0: 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
b5f0: 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
b600: 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
b610: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
b620: 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
b630: 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
b640: 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
b650: 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
b660: 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
b670: 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
b680: 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
b690: 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
b6a0: 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
b6b0: 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
b6c0: 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
b6d0: 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
b6e0: 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 73 2c  */.  int nBytes,
b6f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
b700: 4c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  Length of zSql i
b710: 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
b720: 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
b730: 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
b740: 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
b750: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
b760: 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
b770: 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
b780: 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
b790: 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
b7a0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
b7b0: 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
b7c0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
b7d0: 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
b7e0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
b7f0: 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
b800: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
b810: 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
b820: 0a 20 20 69 6e 74 20 6e 42 79 74 65 73 2c 20 20  .  int nBytes,  
b830: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 65             /* Le
b840: 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
b850: 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
b860: 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
b870: 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
b880: 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
b890: 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
b8a0: 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
b8b0: 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
b8c0: 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
b8d0: 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
b8e0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
b8f0: 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
b900: 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
b910: 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
b920: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
b930: 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
b940: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
b950: 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
b960: 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 73 2c 20  /.  int nBytes, 
b970: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c              /* L
b980: 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
b990: 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
b9a0: 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
b9b0: 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
b9c0: 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
b9d0: 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
b9e0: 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
b9f0: 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
ba00: 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
ba10: 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
ba20: 2a 20 43 41 50 49 33 52 45 46 3a 20 20 44 79 6e  * CAPI3REF:  Dyn
ba30: 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
ba40: 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  alue Object.**.*
ba50: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  * SQLite uses dy
ba60: 6e 61 6d 69 63 20 74 79 70 69 6e 67 20 66 6f 72  namic typing for
ba70: 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
ba80: 74 6f 72 65 73 2e 20 20 56 61 6c 75 65 73 20 63  tores.  Values c
ba90: 61 6e 20 0a 2a 2a 20 62 65 20 69 6e 74 65 67 65  an .** be intege
baa0: 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
bab0: 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
bac0: 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
bad0: 4c 4c 2e 20 20 57 68 65 6e 0a 2a 2a 20 70 61 73  LL.  When.** pas
bae0: 73 69 6e 67 20 61 72 6f 75 6e 64 20 76 61 6c 75  sing around valu
baf0: 65 73 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 65  es internally, e
bb00: 61 63 68 20 76 61 6c 75 65 20 69 73 20 72 65 70  ach value is rep
bb10: 72 65 73 65 6e 74 65 64 20 61 73 0a 2a 2a 20 61  resented as.** a
bb20: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
bb30: 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
bb40: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64  object..*/.typed
bb50: 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
bb60: 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
bb70: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53  .** CAPI3REF:  S
bb80: 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
bb90: 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
bba0: 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
bbb0: 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
bbc0: 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
bbd0: 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
bbe0: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
bbf0: 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69  t object.  A poi
bc00: 6e 74 65 72 20 74 6f 20 73 75 63 68 20 61 6e 20  nter to such an 
bc10: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 0a 2a 2a  object is the.**
bc20: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
bc30: 20 74 6f 20 75 73 65 72 2d 64 65 66 69 6e 65 64   to user-defined
bc40: 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 0a   SQL functions..
bc50: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
bc60: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
bc70: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
bc80: 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
bc90: 45 46 3a 20 20 42 69 6e 64 69 6e 67 20 56 61 6c  EF:  Binding Val
bca0: 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
bcb0: 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 0a 2a 2a  Statements.**.**
bcc0: 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69   In the SQL stri
bcd0: 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ngs input to [sq
bce0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
bcf0: 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
bd00: 61 6e 74 73 2c 0a 2a 2a 20 6f 6e 65 20 6f 72 20  ants,.** one or 
bd10: 6d 6f 72 65 20 6c 69 74 65 72 61 6c 73 20 63 61  more literals ca
bd20: 6e 20 62 65 20 72 65 70 6c 61 63 65 20 62 79 20  n be replace by 
bd30: 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f  a parameter in o
bd40: 6e 65 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 66  ne of these.** f
bd50: 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  orms:.**.** <ul>
bd60: 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
bd70: 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
bd80: 3e 20 20 3a 41 41 41 0a 2a 2a 20 3c 6c 69 3e 20  >  :AAA.** <li> 
bd90: 20 40 41 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @AAA.** <li>  $
bda0: 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
bdb0: 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65  ** In the parame
bdc0: 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20  ter forms shown 
bdd0: 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20  above NNN is an 
bde0: 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
bdf0: 0a 2a 2a 20 41 41 41 20 69 73 20 61 6e 20 61 6c  .** AAA is an al
be00: 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
be10: 69 66 69 65 72 20 61 6e 64 20 56 56 56 20 69 73  ifier and VVV is
be20: 20 61 20 76 61 72 69 61 62 6c 65 20 6e 61 6d 65   a variable name
be30: 20 61 63 63 6f 72 64 69 6e 67 0a 2a 2a 20 74 6f   according.** to
be40: 20 74 68 65 20 73 79 6e 74 61 78 20 72 75 6c 65   the syntax rule
be50: 73 20 6f 66 20 74 68 65 20 54 43 4c 20 70 72 6f  s of the TCL pro
be60: 67 72 61 6d 6d 69 6e 67 20 6c 61 6e 67 75 61 67  gramming languag
be70: 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73  e..** The values
be80: 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
be90: 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
bea0: 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
beb0: 72 20 6e 61 6d 65 73 22 29 0a 2a 2a 20 63 61 6e  r names").** can
bec0: 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
bed0: 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
bee0: 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
bef0: 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
bf00: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
bf10: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
bf20: 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
bf30: 6e 65 73 20 61 6c 77 61 79 73 20 69 73 20 61 20  nes always is a 
bf40: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
bf50: 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
bf60: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
bf70: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
bf80: 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a  repare_v2()] or.
bf90: 2a 2a 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  ** its variants.
bfa0: 20 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20    The second.** 
bfb0: 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
bfc0: 69 6e 64 65 78 20 6f 66 20 74 68 65 20 70 61 72  index of the par
bfd0: 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
bfe0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
bff0: 61 6d 65 74 65 72 20 68 61 73 0a 2a 2a 20 61 6e  ameter has.** an
c000: 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 57 68 65   index of 1. Whe
c010: 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
c020: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
c030: 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
c040: 65 2c 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 6e 64  e, second.** and
c050: 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
c060: 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
c070: 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
c080: 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
c090: 72 72 65 6e 63 65 2e 20 20 54 68 65 20 69 6e 64  rrence.  The ind
c0a0: 65 78 20 66 6f 72 0a 2a 2a 20 6e 61 6d 65 64 20  ex for.** named 
c0b0: 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
c0c0: 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
c0d0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
c0e0: 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
c0f0: 5f 6e 61 6d 65 28 29 5d 20 41 50 49 20 69 66 20  _name()] API if 
c100: 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e  desired.  The in
c110: 64 65 78 20 66 6f 72 20 22 3f 4e 4e 4e 22 0a 2a  dex for "?NNN".*
c120: 2a 20 70 61 72 61 6d 65 74 65 73 20 69 73 20 74  * parametes is t
c130: 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
c140: 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75  .** The NNN valu
c150: 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
c160: 6e 20 31 20 61 6e 64 20 74 68 65 20 63 6f 6d 70  n 1 and the comp
c170: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61  ile-time.** para
c180: 6d 65 74 65 72 20 53 51 4c 49 54 45 5f 4d 41 58  meter SQLITE_MAX
c190: 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
c1a0: 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
c1b0: 20 39 39 39 29 2e 0a 2a 2a 20 53 65 65 20 3c 61   999)..** See <a
c1c0: 20 68 72 65 66 3d 22 6c 69 6d 69 74 73 2e 68 74   href="limits.ht
c1d0: 6d 6c 22 3e 6c 69 6d 69 74 73 2e 68 74 6d 6c 3c  ml">limits.html<
c1e0: 2f 61 3e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  /a> for addition
c1f0: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
c200: 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
c210: 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
c220: 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
c230: 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
c240: 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 0a 2a  **.** In those.*
c250: 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
c260: 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
c270: 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
c280: 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  e is the number 
c290: 6f 66 20 62 79 74 65 73 0a 2a 2a 20 69 6e 20 74  of bytes.** in t
c2a0: 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
c2b0: 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
c2c0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d  value is the num
c2d0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
c2e0: 74 68 65 0a 2a 2a 20 73 74 72 69 6e 67 2c 20 6e  the.** string, n
c2f0: 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
c300: 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 54 68   characters.  Th
c310: 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62  e number.** of b
c320: 79 74 65 73 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ytes does not in
c330: 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 2d 74  clude the zero-t
c340: 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65  erminator at the
c350: 20 65 6e 64 20 6f 66 20 73 74 72 69 6e 67 73 2e   end of strings.
c360: 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
c370: 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  h parameter is n
c380: 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e  egative, the len
c390: 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
c3a0: 67 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f  g is.** number o
c3b0: 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
c3c0: 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
c3d0: 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  minator..**.** T
c3e0: 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
c3f0: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
c400: 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
c410: 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
c420: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
c430: 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
c440: 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
c450: 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
c460: 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 74 65  he BLOB or.** te
c470: 78 74 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  xt after SQLite 
c480: 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
c490: 68 20 69 74 2e 20 20 49 66 20 74 68 65 20 66 69  h it.  If the fi
c4a0: 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 20  fth argument is 
c4b0: 74 68 65 0a 2a 2a 20 73 70 65 63 69 61 6c 20 76  the.** special v
c4c0: 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
c4d0: 54 49 43 5d 2c 20 74 68 65 6e 20 74 68 65 20 6c  TIC], then the l
c4e0: 69 62 72 61 72 79 20 61 73 73 75 6d 65 73 20 74  ibrary assumes t
c4f0: 68 61 74 20 74 68 65 20 69 6e 66 6f 72 6d 61 74  hat the informat
c500: 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 20 73 74 61  ion.** is in sta
c510: 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
c520: 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
c530: 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
c540: 65 64 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 66  ed.  If the.** f
c550: 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
c560: 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
c570: 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
c580: 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
c590: 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 70 72 69  s its.** own pri
c5a0: 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
c5b0: 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
c5c0: 79 2c 20 62 65 66 6f 72 65 20 74 68 65 20 73 71  y, before the sq
c5d0: 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
c5e0: 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
c5f0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
c600: 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
c610: 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
c620: 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
c630: 67 74 68 20 6e 20 74 68 61 74 0a 2a 2a 20 69 73  gth n that.** is
c640: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
c650: 6f 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20  os.  A zeroblob 
c660: 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
c670: 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
c680: 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
c690: 72 20 74 6f 20 68 6f 6c 64 20 69 74 20 73 69 7a  r to hold it siz
c6a0: 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
c6b0: 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
c6c0: 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
c6d0: 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
c6e0: 76 65 20 61 73 20 70 6c 61 63 65 2d 68 6f 6c 64  ve as place-hold
c6f0: 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
c700: 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
c710: 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
c720: 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
c730: 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
c740: 6e 63 72 65 6d 65 6e 74 20 42 4c 4f 42 20 49 2f  ncrement BLOB I/
c750: 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  O] routines..**.
c760: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
c770: 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
c780: 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
c790: 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  after.** [sqlite
c7a0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
c7b0: 28 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74  (and its variant
c7c0: 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  s) or [sqlite3_r
c7d0: 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62  eset()] and.** b
c7e0: 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
c7f0: 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69  tep()]..** Bindi
c800: 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
c810: 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
c820: 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
c830: 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64  tine..** Unbound
c840: 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
c850: 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
c860: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ULL..**.** These
c870: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
c880: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
c890: 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72  success or an er
c8a0: 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61  ror code if.** a
c8b0: 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
c8c0: 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e  ng.  [SQLITE_RAN
c8d0: 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
c8e0: 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
c8f0: 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
c900: 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c   of range.  [SQL
c910: 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
c920: 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
c930: 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49   fails..** [SQLI
c940: 54 45 5f 4d 49 53 55 53 45 5d 20 69 73 20 72 65  TE_MISUSE] is re
c950: 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20  turned if these 
c960: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
c970: 6c 65 64 20 6f 6e 20 61 20 76 69 72 74 75 61 6c  led on a virtual
c980: 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 74 68 61 74  .** machine that
c990: 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74   is the wrong st
c9a0: 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73  ate or which has
c9b0: 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69   already been fi
c9c0: 6e 61 6c 69 7a 65 64 2e 0a 2a 2f 0a 69 6e 74 20  nalized..*/.int 
c9d0: 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
c9e0: 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
c9f0: 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
ca00: 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
ca10: 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
ca20: 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
ca30: 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
ca40: 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
ca50: 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
ca60: 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
ca70: 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
ca80: 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
ca90: 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
caa0: 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
cab0: 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
cac0: 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
cad0: 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
cae0: 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
caf0: 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
cb00: 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
cb10: 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
cb20: 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
cb30: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
cb40: 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
cb50: 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
cb60: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
cb70: 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
cb80: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
cb90: 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
cba0: 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
cbb0: 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
cbc0: 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
cbd0: 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
cbe0: 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
cbf0: 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
cc00: 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
cc10: 72 20 4f 66 20 48 6f 73 74 20 50 61 72 61 6d 65  r Of Host Parame
cc20: 74 65 72 73 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  ters.**.** Retur
cc30: 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20 68 6f  n the largest ho
cc40: 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64  st parameter ind
cc50: 65 78 20 69 6e 20 74 68 65 20 70 72 65 63 6f 6d  ex in the precom
cc60: 70 69 6c 65 64 20 73 74 61 74 65 6d 65 6e 74 20  piled statement 
cc70: 67 69 76 65 6e 0a 2a 2a 20 61 73 20 74 68 65 20  given.** as the 
cc80: 61 72 67 75 6d 65 6e 74 2e 20 20 57 68 65 6e 20  argument.  When 
cc90: 74 68 65 20 68 6f 73 74 20 70 61 72 61 6d 65 74  the host paramet
cca0: 65 72 73 20 61 72 65 20 6f 66 20 74 68 65 20 66  ers are of the f
ccb0: 6f 72 6d 73 20 6c 69 6b 65 20 22 3a 41 41 41 22  orms like ":AAA"
ccc0: 0a 2a 2a 20 6f 72 20 22 3f 22 2c 20 74 68 65 6e  .** or "?", then
ccd0: 20 74 68 65 79 20 61 72 65 20 61 73 73 69 67 6e   they are assign
cce0: 65 64 20 73 65 71 75 65 6e 74 69 61 6c 20 69 6e  ed sequential in
ccf0: 63 72 65 61 73 69 6e 67 20 6e 75 6d 62 65 72 73  creasing numbers
cd00: 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 77 69   beginning.** wi
cd10: 74 68 20 6f 6e 65 2c 20 73 6f 20 74 68 65 20 76  th one, so the v
cd20: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
cd30: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
cd40: 61 72 61 6d 65 74 65 72 73 2e 20 20 48 6f 77 65  arameters.  Howe
cd50: 76 65 72 0a 2a 2a 20 69 66 20 74 68 65 20 73 61  ver.** if the sa
cd60: 6d 65 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  me host paramete
cd70: 72 20 6e 61 6d 65 20 69 73 20 75 73 65 64 20 6d  r name is used m
cd80: 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 2c 20 65  ultiple times, e
cd90: 61 63 68 20 6f 63 63 75 72 72 61 6e 63 65 0a 2a  ach occurrance.*
cda0: 2a 20 69 73 20 67 69 76 65 6e 20 74 68 65 20 73  * is given the s
cdb0: 61 6d 65 20 6e 75 6d 62 65 72 2c 20 73 6f 20 74  ame number, so t
cdc0: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
cdd0: 64 20 69 6e 20 74 68 61 74 20 63 61 73 65 20 69  d in that case i
cde0: 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  s the number.** 
cdf0: 6f 66 20 75 6e 69 71 75 65 20 68 6f 73 74 20 70  of unique host p
ce00: 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 2e 20  arameter names. 
ce10: 20 49 66 20 68 6f 73 74 20 70 61 72 61 6d 65 74   If host paramet
ce20: 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
ce30: 22 3f 4e 4e 4e 22 0a 2a 2a 20 61 72 65 20 75 73  "?NNN".** are us
ce40: 65 64 20 28 77 68 65 72 65 20 4e 4e 4e 20 69 73  ed (where NNN is
ce50: 20 61 6e 20 69 6e 74 65 67 65 72 29 20 74 68 65   an integer) the
ce60: 6e 20 74 68 65 72 65 20 6d 69 67 68 74 20 62 65  n there might be
ce70: 20 67 61 70 73 20 69 6e 20 74 68 65 0a 2a 2a 20   gaps in the.** 
ce80: 6e 75 6d 62 65 72 69 6e 67 20 61 6e 64 20 74 68  numbering and th
ce90: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
cea0: 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
ceb0: 63 65 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  ce is the index 
cec0: 6f 66 20 74 68 65 0a 2a 2a 20 68 6f 73 74 20 70  of the.** host p
ced0: 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 74 68  arameter with th
cee0: 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20  e largest index 
cef0: 76 61 6c 75 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  value..*/.int sq
cf00: 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
cf10: 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
cf20: 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
cf30: 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
cf40: 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
cf50: 65 74 65 72 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  eter.**.** This 
cf60: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
cf70: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
cf80: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74   name of the n-t
cf90: 68 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 61  h parameter in a
cfa0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
cfb0: 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74  mt | prepared st
cfc0: 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 48 6f 73  atement]..** Hos
cfd0: 74 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  t parameters of 
cfe0: 74 68 65 20 66 6f 72 6d 20 22 3a 41 41 41 22 20  the form ":AAA" 
cff0: 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 56  or "@AAA" or "$V
d000: 56 56 22 20 68 61 76 65 20 61 20 6e 61 6d 65 0a  VV" have a name.
d010: 2a 2a 20 77 68 69 63 68 20 69 73 20 74 68 65 20  ** which is the 
d020: 73 74 72 69 6e 67 20 22 3a 41 41 41 22 20 6f 72  string ":AAA" or
d030: 20 22 40 41 41 41 22 20 6f 72 20 22 24 56 56 56   "@AAA" or "$VVV
d040: 22 2e 20 20 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ".  .** In other
d050: 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
d060: 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
d070: 72 20 22 40 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "@".** is incl
d080: 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
d090: 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72  the name..** Par
d0a0: 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
d0b0: 6f 72 6d 20 22 3f 22 20 6f 72 20 22 3f 4e 4e 4e  orm "?" or "?NNN
d0c0: 22 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a  " have no name..
d0d0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
d0e0: 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20  bound parameter 
d0f0: 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
d100: 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
d110: 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69  If the value n i
d120: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
d130: 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61  r if the n-th pa
d140: 72 61 6d 65 74 65 72 20 69 73 20 6e 61 6d 65 6c  rameter is namel
d150: 65 73 73 2c 0a 2a 2a 20 74 68 65 6e 20 4e 55 4c  ess,.** then NUL
d160: 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
d170: 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
d180: 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 69 6e  ing is always in
d190: 20 74 68 65 0a 2a 2a 20 55 54 46 2d 38 20 65 6e   the.** UTF-8 en
d1a0: 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
d1b0: 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
d1c0: 65 72 20 77 61 73 20 6f 72 69 67 69 6e 61 6c 6c  er was originall
d1d0: 79 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 61  y specified.** a
d1e0: 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
d1f0: 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
d200: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
d210: 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
d220: 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
d230: 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
d240: 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
d250: 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
d260: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d270: 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
d280: 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
d290: 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69  n Name.**.** Thi
d2a0: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
d2b0: 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  s the index of a
d2c0: 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
d2d0: 77 69 74 68 20 74 68 65 20 67 69 76 65 6e 20 6e  with the given n
d2e0: 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ame..** The name
d2f0: 20 6d 75 73 74 20 6d 61 74 63 68 20 65 78 61 63   must match exac
d300: 74 6c 79 2e 20 20 49 66 20 6e 6f 20 70 61 72 61  tly.  If no para
d310: 6d 65 74 65 72 20 77 69 74 68 20 74 68 65 20 67  meter with the g
d320: 69 76 65 6e 20 6e 61 6d 65 20 69 73 20 0a 2a 2a  iven name is .**
d330: 20 66 6f 75 6e 64 2c 20 72 65 74 75 72 6e 20 30   found, return 0
d340: 2e 20 20 50 61 72 61 6d 65 74 65 72 20 6e 61 6d  .  Parameter nam
d350: 65 73 20 6d 75 73 74 20 62 65 20 55 54 46 38 2e  es must be UTF8.
d360: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
d370: 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
d380: 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
d390: 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
d3a0: 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
d3b0: 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
d3c0: 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
d3d0: 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
d3e0: 65 6e 74 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61  ent.**.** Contra
d3f0: 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
d400: 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
d410: 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
d420: 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74  oes not.** reset
d430: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
d440: 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
d450: 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b 73 71  gs] on a .** [sq
d460: 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65  lite3_stmt | pre
d470: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
d480: 2e 20 20 55 73 65 20 74 68 69 73 20 72 6f 75 74  .  Use this rout
d490: 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 65 74 20  ine to.** reset 
d4a0: 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
d4b0: 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
d4c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
d4d0: 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
d4e0: 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
d4f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
d500: 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
d510: 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
d520: 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e  .** Return the n
d530: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
d540: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
d550: 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
d560: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
d570: 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20  stmt | compiled 
d580: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  SQL statement]. 
d590: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
d5a0: 75 72 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53 74  urns 0.** if pSt
d5b0: 6d 74 20 69 73 20 61 6e 20 53 51 4c 20 73 74 61  mt is an SQL sta
d5c0: 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
d5d0: 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
d5e0: 20 28 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c   (for .** exampl
d5f0: 65 20 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2f  e an UPDATE)..*/
d600: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
d610: 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
d620: 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
d630: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d640: 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
d650: 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
d660: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
d670: 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
d680: 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
d690: 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
d6a0: 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
d6b0: 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c  ult set of a SEL
d6c0: 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  ECT statement.  
d6d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
d6e0: 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
d6f0: 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
d700: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54   pointer to a UT
d710: 46 38 20 73 74 72 69 6e 67 20 61 6e 64 20 73 71  F8 string and sq
d720: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
d730: 65 31 36 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  e16().** returns
d740: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
d750: 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54  UTF16 string.  T
d760: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
d770: 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 73 71  er is the.** [sq
d780: 6c 69 74 65 5f 73 74 6d 74 20 7c 20 70 72 65 70  lite_stmt | prep
d790: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
d7a0: 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
d7b0: 74 68 65 20 53 45 4c 45 43 54 20 73 74 61 74 65  the SELECT state
d7c0: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 65 63  ment..** The sec
d7d0: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
d7e0: 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62   the column numb
d7f0: 65 72 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f  er.  The left-mo
d800: 73 74 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20  st column is.** 
d810: 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
d820: 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
d830: 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
d840: 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
d850: 72 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  r the .** [sqlit
d860: 65 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65  e_stmt | prepare
d870: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
d880: 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
d890: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
d8a0: 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  ].** or until th
d8b0: 65 20 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c 69  e next call sqli
d8c0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
d8d0: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
d8e0: 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20  umn_name16().** 
d8f0: 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
d900: 6d 6e 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  mn..*/.const cha
d910: 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
d920: 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
d930: 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
d940: 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
d950: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
d960: 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
d970: 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
d980: 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
d990: 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
d9a0: 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54  y Result.**.** T
d9b0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
d9c0: 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
d9d0: 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20   determine what 
d9e0: 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a  column of what.*
d9f0: 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68  * table in which
da00: 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75   database a resu
da10: 6c 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73  lt of a SELECT s
da20: 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66  tatement comes f
da30: 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  rom..** The name
da40: 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
da50: 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
da60: 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
da70: 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
da80: 20 61 20 55 54 46 38 20 6f 72 20 55 54 46 31 36   a UTF8 or UTF16
da90: 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 72 65   string.  The re
daa0: 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
dab0: 20 76 61 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a 20   valid until.** 
dac0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
dad0: 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61  t | prepared sta
dae0: 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
daf0: 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  oyed using.** [s
db00: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
db10: 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
db20: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
db30: 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
db40: 20 61 67 61 69 6e 20 61 62 6f 75 74 20 74 68 65   again about the
db50: 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
db60: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
db70: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f  gument to the fo
db80: 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73  llowing calls is
db90: 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   a .** [sqlite3_
dba0: 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20  stmt | compiled 
dbb0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  SQL statement]..
dbc0: 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
dbd0: 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
dbe0: 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
dbf0: 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
dc00: 6e 65 64 20 62 79 20 0a 2a 2a 20 74 68 65 20 73  ned by .** the s
dc10: 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
dc20: 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
dc30: 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
dc40: 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
dc50: 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
dc60: 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
dc70: 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
dc80: 73 73 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 71  ssion.** or subq
dc90: 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
dca0: 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
dcb0: 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
dcc0: 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72  e functions.** r
dcd0: 65 74 75 72 6e 20 4e 55 4c 4c 2e 20 4f 74 68 65  eturn NULL. Othe
dce0: 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
dcf0: 72 6e 20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65 20  rn the .** name 
dd00: 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
dd10: 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 20  database, table 
dd20: 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  and column that 
dd30: 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
dd40: 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
dd50: 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
dd60: 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68   As with all oth
dd70: 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
dd80: 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20  those postfixed 
dd90: 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
dda0: 20 55 54 46 2d 31 36 0a 2a 2a 20 65 6e 63 6f 64   UTF-16.** encod
ddb0: 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20  ed strings, the 
ddc0: 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
ddd0: 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
dde0: 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61  .** These APIs a
ddf0: 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
de00: 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
de10: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
de20: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
de30: 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
de40: 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f 63  METADATA preproc
de50: 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
de60: 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
de70: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
de80: 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
de90: 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
dea0: 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
deb0: 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
dec0: 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
ded0: 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
dee0: 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
def0: 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
df00: 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
df10: 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
df20: 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
df30: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
df40: 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
df50: 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
df60: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
df70: 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
df80: 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
df90: 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
dfa0: 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
dfb0: 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
dfc0: 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
dfd0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
dfe0: 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
dff0: 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
e000: 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 68   Result.**.** Th
e010: 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
e020: 72 20 69 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  r is a [sqlite3_
e030: 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20  stmt | compiled 
e040: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  SQL statement]. 
e050: 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
e060: 65 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45 43  ement is a SELEC
e070: 54 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  T statement and 
e080: 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
e090: 66 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e  f the .** return
e0a0: 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 20 6f  ed result set  o
e0b0: 66 20 74 68 61 74 20 53 45 4c 45 43 54 20 69 73  f that SELECT is
e0c0: 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
e0d0: 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
e0e0: 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
e0f0: 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
e100: 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
e110: 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
e120: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66   is returned. If
e130: 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
e140: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
e150: 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
e160: 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
e170: 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
e180: 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
e190: 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  ed..** The retur
e1a0: 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
e1b0: 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
e1c0: 65 64 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  ed. For example,
e1d0: 20 69 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62   in.** the datab
e1e0: 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
e1f0: 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
e200: 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
e210: 2a 0a 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f 6c  *.** And the fol
e220: 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
e230: 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
e240: 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
e250: 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
e260: 2a 20 54 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * Then this rout
e270: 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
e280: 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
e290: 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
e2a0: 63 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63  cond.** result c
e2b0: 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
e2c0: 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
e2d0: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
e2e0: 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
e2f0: 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51  (i==0)..**.** SQ
e300: 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
e310: 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
e320: 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61  g.  So just beca
e330: 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
e340: 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
e350: 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
e360: 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
e370: 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
e380: 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
e390: 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
e3a0: 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
e3b0: 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
e3c0: 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
e3d0: 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
e3e0: 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
e3f0: 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65  ot static.  Type
e400: 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
e410: 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
e420: 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
e430: 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
e440: 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
e450: 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
e460: 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
e470: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
e480: 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
e490: 74 6d 74 20 2a 2c 20 69 6e 74 20 69 29 3b 0a 63  tmt *, int i);.c
e4a0: 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
e4b0: 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
e4c0: 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
e4d0: 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a  t*,int);../* .**
e4e0: 20 43 41 50 49 33 52 45 46 3a 20 20 45 76 61 6c   CAPI3REF:  Eval
e4f0: 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
e500: 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  ement.**.** Afte
e510: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  r an [sqlite3_st
e520: 6d 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65  mt | SQL stateme
e530: 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
e540: 70 61 72 65 64 20 77 69 74 68 20 61 20 63 61 6c  pared with a cal
e550: 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72 20 5b  l.** to either [
e560: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
e570: 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
e580: 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
e590: 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a  ] or to one of.*
e5a0: 2a 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  * the legacy int
e5b0: 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
e5c0: 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
e5d0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
e5e0: 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  6()],.** then th
e5f0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  is function must
e600: 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
e610: 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
e620: 65 76 61 6c 75 61 74 65 20 74 68 65 20 0a 2a 2a  evaluate the .**
e630: 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
e640: 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
e650: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
e660: 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 73 74   this sqlite3_st
e670: 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
e680: 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
e690: 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
e6a0: 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
e6b0: 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
e6c0: 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
e6d0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
e6e0: 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
e6f0: 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
e700: 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
e710: 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
e720: 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
e730: 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
e740: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
e750: 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
e760: 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
e770: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
e780: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
e790: 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
e7a0: 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
e7b0: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
e7c0: 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
e7d0: 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
e7e0: 49 6e 20 74 68 65 20 6c 61 67 61 63 79 20 69 6e  In the lagacy in
e7f0: 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
e800: 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
e810: 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
e820: 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c  _BUSY], .** [SQL
e830: 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
e840: 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
e850: 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
e860: 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
e870: 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
e880: 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
e890: 74 68 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54  the other [SQLIT
e8a0: 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
e8b0: 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  de].** or [SQLIT
e8c0: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
e8d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
e8e0: 6f 64 65 5d 20 6d 69 67 68 74 20 62 65 20 72 65  ode] might be re
e8f0: 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77 65 6c  turned as.** wel
e900: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  l..**.** [SQLITE
e910: 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
e920: 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
e930: 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
e940: 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
e950: 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
e960: 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
e970: 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68   its job.  If th
e980: 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
e990: 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63   COMMIT.** or oc
e9a0: 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
e9b0: 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
e9c0: 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
e9d0: 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
e9e0: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
e9f0: 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
ea00: 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54 20  is not a COMMIT 
ea10: 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
ea20: 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20  n a.** explicit 
ea30: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
ea40: 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
ea50: 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
ea60: 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
ea70: 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
ea80: 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d   [SQLITE_DONE] m
ea90: 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
eaa0: 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
eab0: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
eac0: 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
ead0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
eae0: 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
eaf0: 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
eb00: 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
eb10: 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
eb20: 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
eb30: 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
eb40: 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
eb50: 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
eb60: 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
eb70: 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49  l state..**.** I
eb80: 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
eb90: 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
eba0: 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
ebb0: 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 53  ata, then .** [S
ebc0: 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20 72 65  QLITE_ROW] is re
ebd0: 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
ebe0: 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
ebf0: 74 61 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 66  ta is ready.** f
ec00: 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
ec10: 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 54 68 65   the caller. The
ec20: 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
ec30: 63 63 65 73 73 65 64 20 75 73 69 6e 67 0a 2a 2a  ccessed using.**
ec40: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
ec50: 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d  lumn_int | colum
ec60: 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
ec70: 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
ec80: 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
ec90: 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
eca0: 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
ecb0: 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20  of data..** .** 
ecc0: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
ecd0: 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
ece0: 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
ecf0: 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
ed00: 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
ed10: 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
ed20: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
ed30: 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
ed40: 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
ed50: 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
ed60: 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
ed70: 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
ed80: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
ed90: 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c  ]..** With the l
eda0: 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
edb0: 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
edc0: 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61   error code (exa
edd0: 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple:.** [SQLITE
ede0: 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
edf0: 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
ee00: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
ee10: 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
ee20: 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
ee30: 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
ee40: 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
ee50: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f   the.** [sqlite_
ee60: 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20  stmt | prepared 
ee70: 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20  statement].  In 
ee80: 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
ee90: 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
eea0: 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
eeb0: 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
eec0: 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
eed0: 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
eee0: 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
eef0: 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
ef00: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
ef10: 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
ef20: 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
ef30: 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
ef40: 65 64 20 6f 6e 20 61 20 5b 73 71 6c 69 74 65 5f  ed on a [sqlite_
ef50: 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20  stmt | prepared 
ef60: 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
ef70: 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
ef80: 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
ef90: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
efa0: 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
efb0: 74 20 68 61 64 20 0a 2a 2a 20 70 72 65 76 69 6f  t had .** previo
efc0: 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
efd0: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
efe0: 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
eff0: 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
f000: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
f010: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
f020: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
f030: 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
f040: 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
f050: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
f060: 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
f070: 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
f080: 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
f090: 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 6c  </b>.** In the l
f0a0: 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
f0b0: 20 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33   .** the sqlite3
f0c0: 5f 73 74 65 70 28 29 20 41 50 49 20 61 6c 77 61  _step() API alwa
f0d0: 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
f0e0: 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
f0f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
f100: 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
f110: 79 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  y error other th
f120: 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
f130: 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  .** and [SQLITE_
f140: 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
f150: 73 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  st call [sqlite3
f160: 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
f170: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
f180: 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
f190: 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
f1a0: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 5b 53 51   specific.** [SQ
f1b0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73  LITE_ERROR | res
f1c0: 75 6c 74 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ult codes] that 
f1d0: 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
f1e0: 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
f1f0: 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
f200: 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
f210: 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
f220: 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
f230: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
f240: 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
f250: 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
f260: 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
f270: 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
f280: 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
f290: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
f2a0: 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
f2b0: 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
f2c0: 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
f2d0: 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
f2e0: 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
f2f0: 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
f300: 5d 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a 20  ], then the .** 
f310: 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 53  more specific [S
f320: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65  QLITE_ERROR | re
f330: 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20  sult codes] are 
f340: 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
f350: 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
f360: 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
f370: 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
f380: 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
f390: 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
f3a0: 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
f3b0: 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
f3c0: 2a 20 43 41 50 49 33 52 45 46 3a 0a 2a 2a 0a 2a  * CAPI3REF:.**.*
f3d0: 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d  * Return the num
f3e0: 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e  ber of values in
f3f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
f400: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
f410: 65 74 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  et..**.** After 
f420: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
f430: 65 33 5f 73 74 65 70 28 29 5d 20 74 68 61 74 20  e3_step()] that 
f440: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
f450: 52 4f 57 5d 2c 20 74 68 69 73 20 72 6f 75 74 69  ROW], this routi
f460: 6e 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  ne.** will retur
f470: 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  n the same value
f480: 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33   as the [sqlite3
f490: 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
f4a0: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 41 66   function..** Af
f4b0: 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
f4c0: 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
f4d0: 64 20 61 6e 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  d an [SQLITE_DON
f4e0: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  E], [SQLITE_BUSY
f4f0: 5d 2c 20 6f 72 0a 2a 2a 20 61 20 5b 53 51 4c 49  ], or.** a [SQLI
f500: 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72  TE_ERROR | error
f510: 20 63 6f 64 65 5d 2c 20 6f 72 20 62 65 66 6f 72   code], or befor
f520: 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
f530: 29 5d 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a 20  )] has been .** 
f540: 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b 73  called on the [s
f550: 71 6c 69 74 65 5f 73 74 6d 74 20 7c 20 70 72 65  qlite_stmt | pre
f560: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
f570: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 74   for the first t
f580: 69 6d 65 2c 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ime,.** this rou
f590: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
f5a0: 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  o..*/.int sqlite
f5b0: 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
f5c0: 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
f5d0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
f5e0: 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
f5f0: 44 61 74 61 74 79 70 65 73 0a 2a 2a 0a 2a 2a 20  Datatypes.**.** 
f600: 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
f610: 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
f620: 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
f630: 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
f640: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
f650: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
f660: 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
f670: 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
f680: 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
f690: 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
f6a0: 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
f6b0: 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
f6c0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  >.**.** These co
f6d0: 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
f6e0: 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
f6f0: 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
f700: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
f710: 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
f720: 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
f730: 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
f740: 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
f750: 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
f760: 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
f770: 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
f780: 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
f790: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
f7a0: 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
f7b0: 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
f7c0: 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  se SQLITE3_TEXT 
f7d0: 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
f7e0: 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
f7f0: 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
f800: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f810: 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
f820: 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
f830: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
f840: 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
f850: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
f860: 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
f870: 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
f880: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
f890: 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
f8a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
f8b0: 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
f8c0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
f8d0: 73 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  s Values From A 
f8e0: 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Query.**.** Thes
f8f0: 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
f900: 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
f910: 6f 75 74 20 74 68 65 20 69 6e 66 6f 72 6d 61 74  out the informat
f920: 69 6f 6e 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67  ion.** in a sing
f930: 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
f940: 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20   current result 
f950: 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
f960: 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73   In every.** cas
f970: 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
f980: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
f990: 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71  r to the .** [sq
f9a0: 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c  lite3_stmt | SQL
f9b0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
f9c0: 20 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61   is being.** eva
f9d0: 6c 75 61 74 65 20 28 74 68 65 20 5b 73 71 6c 69  luate (the [sqli
f9e0: 74 65 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20 77  te_stmt*] that w
f9f0: 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
fa00: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72   .** [sqlite3_pr
fa10: 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
fa20: 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
fa30: 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20 73  ts) and.** the s
fa40: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
fa50: 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
fa60: 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
fa70: 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ich information 
fa80: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
fa90: 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66  turned.  The lef
faa0: 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 68 61  t-most column ha
fab0: 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e  s an index of 0.
fac0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
fad0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  L statement is n
fae0: 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
faf0: 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
fb00: 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
fb10: 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  the column index
fb20: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
fb30: 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
fb40: 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
fb50: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
fb60: 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
fb70: 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  ne returns .** [
fb80: 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
fb90: 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
fba0: 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
fbb0: 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
fbc0: 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
fbd0: 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64  n.  The returned
fbe0: 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
fbf0: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
fc00: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
fc10: 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
fc20: 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
fc30: 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
fc40: 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
fc50: 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
fc60: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
fc70: 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
fc80: 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
fc90: 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
fca0: 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
fcb0: 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
fcc0: 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
fcd0: 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
fce0: 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
fcf0: 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
fd00: 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
fd10: 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
fd20: 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
fd30: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
fd40: 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
fd50: 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
fd60: 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
fd70: 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
fd80: 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
fd90: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
fda0: 6c 75 6d 6e 5f 6e 6d 0a 2a 2a 0a 2a 2a 20 49 66  lumn_nm.**.** If
fdb0: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
fdc0: 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
fdd0: 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
fde0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
fdf0: 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74 69 6e  tes() .** routin
fe00: 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
fe10: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
fe20: 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
fe30: 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ring..** If the 
fe40: 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
fe50: 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
fe60: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
fe70: 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
fe80: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
fe90: 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
fea0: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
feb0: 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
fec0: 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
fed0: 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
fee0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
fef0: 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
ff00: 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
ff10: 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
ff20: 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
ff30: 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
ff40: 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
ff50: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
ff60: 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
ff70: 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ing..** The valu
ff80: 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  e returned does 
ff90: 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
ffa0: 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
ffb0: 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
ffc0: 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f   the string.  Fo
ffd0: 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
ffe0: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
fff0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
10000 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
10010 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
10020 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
10030 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
10040 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
10050 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20  tes16() routine 
10060 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71  is similar to sq
10070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
10080 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76  es().** but leav
10090 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  es the result in
100a0 20 55 54 46 2d 31 36 20 69 6e 73 74 65 61 64 20   UTF-16 instead 
100b0 6f 66 20 55 54 46 2d 38 2e 20 20 0a 2a 2a 20 54  of UTF-8.  .** T
100c0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
100d0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64  or is not includ
100e0 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74  ed in this count
100f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
10100 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
10110 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
10120 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
10130 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  riate.  For.** e
10140 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
10150 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
10160 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
10170 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
10180 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
10190 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
101a0 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
101b0 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 64 6f  internally to do
101c0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 0a   the conversion.
101d0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
101e0 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  .  The following
101f0 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
10200 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 74  he conversions t
10210 68 61 74 0a 2a 2a 20 61 72 65 20 61 70 70 6c 69  hat.** are appli
10220 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
10230 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
10240 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
10250 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
10260 6c 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  l <th> Requested
10270 20 3c 74 68 3e 20 0a 2a 2a 20 3c 74 72 3e 3c 74   <th> .** <tr><t
10280 68 3e 20 20 54 79 70 65 20 20 20 20 3c 74 68 3e  h>  Type    <th>
10290 20 20 20 20 54 79 70 65 20 20 20 3c 74 68 3e 20      Type   <th> 
102a0 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
102b0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
102c0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
102d0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
102e0 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
102f0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
10300 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
10310 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
10320 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
10330 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
10340 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
10350 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
10360 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
10370 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
10380 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
10390 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
103a0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
103b0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
103c0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
103d0 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
103e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
103f0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
10400 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
10410 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
10420 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
10430 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
10440 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
10450 3e 20 53 61 6d 65 20 61 73 20 66 6f 72 20 49 4e  > Same as for IN
10460 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
10470 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
10480 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
10490 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
104a0 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
104b0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
104c0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
104d0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
104e0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
104f0 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
10500 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
10510 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
10520 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
10530 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
10540 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
10550 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
10560 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
10570 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
10580 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
10590 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
105a0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
105b0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
105c0 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
105d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
105e0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
105f0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
10600 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
10610 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
10620 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
10630 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
10640 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
10650 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
10660 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
10670 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
10680 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
10690 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
106a0 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
106b0 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
106c0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
106d0 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
106e0 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
106f0 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
10700 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
10710 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
10720 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
10730 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
10740 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
10750 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
10760 20 6f 6e 20 65 71 75 61 76 61 6c 65 6e 74 20 69   on equavalent i
10770 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
10780 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
10790 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
107a0 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
107b0 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
107c0 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
107d0 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
107e0 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
107f0 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
10800 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
10810 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
10820 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
10830 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
10840 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
10850 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
10860 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
10870 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
10880 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
10890 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
108a0 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
108b0 65 64 2e 20 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ed. .** Type con
108c0 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
108d0 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
108e0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
108f0 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
10900 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
10910 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20  <ul>.** <li><p> 
10920 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
10930 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
10940 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
10950 6e 5f 74 65 78 74 28 29 20 0a 2a 2a 20 20 20 20  n_text() .**    
10960 20 20 20 20 20 20 6f 72 20 73 71 6c 69 74 65 33        or sqlite3
10970 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
10980 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
10990 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
109a0 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ight.**         
109b0 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
109c0 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
109d0 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  </p></li>.**.** 
109e0 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69  <li><p>  The ini
109f0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
10a00 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
10a10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
10a20 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
10a30 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
10a40 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
10a50 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
10a60 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
10a70 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
10a80 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
10a90 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  /p></li>.**.** <
10aa0 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74  li><p>  The init
10ab0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
10ac0 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
10ad0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
10ae0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
10af0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
10b00 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
10b10 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
10b20 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
10b30 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rted.**         
10b40 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f   to UTF-8.</p></
10b50 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
10b60 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  ** Conversions b
10b70 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
10b80 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
10b90 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
10ba0 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
10bb0 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
10bc0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
10bd0 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
10be0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
10bf0 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
10c00 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
10c10 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77  nter points to w
10c20 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
10c30 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
10c40 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
10c50 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
10c60 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
10c70 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
10c80 20 73 6f 6d 65 74 69 6d 65 20 69 74 20 69 73 0a   sometime it is.
10c90 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  ** not possible 
10ca0 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
10cb0 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
10cc0 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
10cd0 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  d.  .**.** The s
10ce0 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
10cf0 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
10d00 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
10d10 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
10d20 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
10d30 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
10d40 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a  :.**.**  <ul>.**
10d50 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
10d60 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
10d70 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
10d80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
10d90 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
10da0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
10db0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
10dc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
10dd0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
10de0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
10df0 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
10e00 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
10e10 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
10e20 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a  li>.**  </ul>.**
10e30 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
10e40 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
10e50 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
10e60 6d 6e 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  mn_text(), sqlit
10e70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
10e80 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ,.** or sqlite3_
10e90 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
10ea0 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
10eb0 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 74  he result into t
10ec0 68 65 20 64 65 73 69 72 65 64 0a 2a 2a 20 66 6f  he desired.** fo
10ed0 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
10ee0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
10ef0 5f 62 79 74 65 73 28 29 20 6f 72 20 73 71 6c 69  _bytes() or sqli
10f00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
10f10 31 36 28 29 20 74 6f 0a 2a 2a 20 66 69 6e 64 20  16() to.** find 
10f20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
10f30 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
10f40 6d 69 78 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  mix call to sqli
10f50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
10f60 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
10f70 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
10f80 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
10f90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
10fa0 31 36 28 29 2e 20 20 41 6e 64 20 64 6f 20 6e 6f  16().  And do no
10fb0 74 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c 73 20 74  t.** mix calls t
10fc0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
10fd0 5f 74 65 78 74 31 36 28 29 20 77 69 74 68 20 63  _text16() with c
10fe0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
10ff0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
11000 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
11010 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
11020 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
11030 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
11040 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
11050 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
11060 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
11070 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
11080 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
11090 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
110a0 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
110b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
110c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
110d0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
110e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
110f0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
11100 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
11110 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
11120 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
11130 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
11140 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75  t iCol);.const u
11150 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
11160 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
11170 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
11180 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
11190 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
111a0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
111b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
111c0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
111d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
111e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
111f0 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
11200 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
11210 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
11220 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
11230 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
11240 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
11250 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
11260 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
11270 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66  ** The sqlite3_f
11280 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
11290 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
112a0 64 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b 73 71  delete a .** [sq
112b0 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d  lite3_stmt | com
112c0 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
112d0 65 6e 74 5d 2e 20 49 66 20 74 68 65 20 73 74 61  ent]. If the sta
112e0 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 65 78  tement was.** ex
112f0 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75  ecuted successfu
11300 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20 65 78 65 63  lly, or not exec
11310 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65  uted at all, the
11320 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  n SQLITE_OK is r
11330 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 65  eturned..** If e
11340 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
11350 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64  statement failed
11360 20 74 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b 53 51   then an .** [SQ
11370 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72  LITE_ERROR | err
11380 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c  or code] or [SQL
11390 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
113a0 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20   extended error 
113b0 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75  code].** is retu
113c0 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 69  rned. .**.** Thi
113d0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
113e0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
113f0 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20  oint during the 
11400 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
11410 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
11420 74 20 7c 20 76 69 72 74 75 61 6c 20 6d 61 63 68  t | virtual mach
11430 69 6e 65 5d 2e 20 20 49 66 20 74 68 65 20 76 69  ine].  If the vi
11440 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61  rtual machine ha
11450 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65  s not .** comple
11460 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68  ted execution wh
11470 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
11480 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20  is called, that 
11490 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75  is like.** encou
114a0 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72  ntering an error
114b0 20 6f 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74   or an interrupt
114c0 2e 20 20 28 53 65 65 20 5b 73 71 6c 69 74 65 33  .  (See [sqlite3
114d0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 2e 29 20  _interrupt()].) 
114e0 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75  .** Incomplete u
114f0 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f  pdates may be ro
11500 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72  lled back and tr
11510 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65  ansactions cance
11520 6c 6c 65 64 2c 20 20 0a 2a 2a 20 64 65 70 65 6e  lled,  .** depen
11530 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63  ding on the circ
11540 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74  umstances, and t
11550 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  he .** [SQLITE_E
11560 52 52 4f 52 20 7c 20 72 65 73 75 6c 74 20 63 6f  RROR | result co
11570 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c  de] returned wil
11580 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f  l be [SQLITE_ABO
11590 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  RT]..*/.int sqli
115a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
115b0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
115c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
115d0 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
115e0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
115f0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
11600 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
11610 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
11620 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 0a 2a  ed to reset a .*
11630 2a 20 5b 73 71 6c 69 74 65 5f 73 74 6d 74 20 7c  * [sqlite_stmt |
11640 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74   compiled SQL st
11650 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e  atement] object.
11660 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74 27 73  .** back to it's
11670 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
11680 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
11690 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  xecuted..** Any 
116a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
116b0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
116c0 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
116d0 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
116e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
116f0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
11700 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
11710 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
11720 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
11730 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
11740 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
11750 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2f 0a 69  e bindings..*/.i
11760 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
11770 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
11780 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
11790 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
117a0 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
117b0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
117c0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f  he following two
117d0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75   functions are u
117e0 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
117f0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
11800 65 67 61 74 65 73 0a 2a 2a 20 6f 72 20 74 6f 20  egates.** or to 
11810 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
11820 61 76 69 6f 72 20 6f 66 20 65 78 69 73 74 69 6e  avior of existin
11830 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
11840 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
11850 54 68 65 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63  The.** differenc
11860 65 20 6f 6e 6c 79 20 62 65 74 77 65 65 6e 20 74  e only between t
11870 68 65 20 74 77 6f 20 69 73 20 74 68 61 74 20 74  he two is that t
11880 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
11890 74 65 72 2c 20 74 68 65 0a 2a 2a 20 6e 61 6d 65  ter, the.** name
118a0 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29   of the (scalar)
118b0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
118c0 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64  regate, is encod
118d0 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 0a  ed in UTF-8 for.
118e0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
118f0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64  e_function() and
11900 20 55 54 46 2d 31 36 20 66 6f 72 20 73 71 6c 69   UTF-16 for sqli
11910 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
11920 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  ion16()..**.** T
11930 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11940 74 20 69 73 20 74 68 65 20 5b 73 71 6c 69 74 65  t is the [sqlite
11950 33 20 7c 20 64 61 74 61 62 61 73 65 20 68 61 6e  3 | database han
11960 64 6c 65 5d 20 74 68 61 74 20 68 6f 6c 64 73 20  dle] that holds 
11970 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
11980 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
11990 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 20   is to be added 
119a0 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 20 49 66  or redefined. If
119b0 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 70 72 6f   a single.** pro
119c0 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74  gram uses more t
119d0 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
119e0 20 68 61 6e 64 6c 65 20 69 6e 74 65 72 6e 61 6c   handle internal
119f0 6c 79 2c 20 74 68 65 6e 20 53 51 4c 0a 2a 2a 20  ly, then SQL.** 
11a00 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
11a10 72 65 67 61 74 65 73 20 6d 75 73 74 20 62 65 20  regates must be 
11a20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c  added individual
11a30 6c 79 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ly to each datab
11a40 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 20 77 69  ase.** handle wi
11a50 74 68 20 77 68 69 63 68 20 74 68 65 79 20 77 69  th which they wi
11a60 6c 6c 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ll be used..**.*
11a70 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
11a80 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
11a90 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
11aa0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
11ab0 61 74 65 64 0a 2a 2a 20 6f 72 20 72 65 64 65 66  ated.** or redef
11ac0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e  ined..** The len
11ad0 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
11ae0 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
11af0 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69  5 bytes, exclusi
11b00 76 65 20 6f 66 20 74 68 65 20 0a 2a 2a 20 7a 65  ve of the .** ze
11b10 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
11b20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
11b30 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  me length limit 
11b40 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74  is in bytes, not
11b50 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20  .** characters. 
11b60 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
11b70 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
11b80 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
11b90 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
11ba0 75 6c 74 20 69 6e 20 61 6e 20 53 51 4c 49 54 45  ult in an SQLITE
11bb0 5f 45 52 52 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a  _ERROR error..**
11bc0 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70 61  .** The third pa
11bd0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
11be0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
11bf0 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
11c00 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
11c10 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
11c20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
11c30 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
11c40 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
11c50 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
11c60 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
11c70 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
11c80 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ments..**.** The
11c90 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
11ca0 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
11cb0 63 69 66 69 65 73 20 77 68 61 74 20 0a 2a 2a 20  cifies what .** 
11cc0 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
11cd0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
11ce0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
11cf0 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
11d00 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
11d10 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  Any SQL function
11d20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
11d30 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74  should be able t
11d40 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77  o work.** work w
11d50 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
11d60 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
11d70 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
11d80 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
11d90 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
11da0 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
11db0 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
11dc0 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f  her.  It is allo
11dd0 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  wed to.** invoke
11de0 20 73 71 6c 69 74 65 5f 63 72 65 61 74 65 5f 66   sqlite_create_f
11df0 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
11e00 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
11e10 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
11e20 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
11e30 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
11e40 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
11e50 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
11e60 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e  TextRep..** When
11e70 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
11e80 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
11e90 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
11ea0 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
11eb0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
11ec0 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
11ed0 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
11ee0 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
11ef0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
11f00 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
11f10 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
11f20 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
11f30 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
11f40 74 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  t.** text encodi
11f50 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
11f60 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
11f70 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ment should be.*
11f80 2a 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a  * [SQLITE_ANY]..
11f90 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20  **.** The fifth 
11fa0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
11fb0 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
11fc0 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
11fd0 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
11fe0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
11ff0 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
12000 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 0a  s pointer using.
12010 2a 2a 20 5b 73 71 6c 69 74 65 5f 75 73 65 72 5f  ** [sqlite_user_
12020 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  data()]..**.** T
12030 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68  he seventh, eigh
12040 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72  th and ninth par
12050 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
12060 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
12070 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
12080 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
12090 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
120a0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
120b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  .** function or 
120c0 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61  aggregate. A sca
120d0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
120e0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
120f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a  lementation of.*
12100 2a 20 74 68 65 20 78 46 75 6e 63 20 63 61 6c 6c  * the xFunc call
12110 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20  back only, NULL 
12120 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20  pointers should 
12130 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
12140 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
12150 69 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 2e  inal parameters.
12160 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51   An aggregate SQ
12170 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
12180 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
12190 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53 74 65  ation.** of xSte
121a0 70 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  p and xFinal and
121b0 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20   NULL should be 
121c0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
121d0 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 0a 2a  . To delete an.*
121e0 2a 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  * existing SQL f
121f0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
12200 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
12210 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
12220 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  nction.** callba
12230 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ck..**.** It is 
12240 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
12250 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
12260 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
12270 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
12280 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
12290 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
122a0 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
122b0 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
122c0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
122d0 64 69 66 66 65 72 69 6e 67 20 70 65 72 66 65 72  differing perfer
122e0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
122f0 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  gs.  SQLite will
12300 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
12310 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20  ementation most 
12320 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
12330 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
12340 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
12350 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2f  tion is used..*/
12360 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
12370 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
12380 73 71 6c 69 74 65 33 20 2a 2c 0a 20 20 63 6f 6e  sqlite3 *,.  con
12390 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
123a0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
123b0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
123c0 65 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  ep,.  void*,.  v
123d0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
123e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
123f0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
12400 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
12410 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
12420 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
12430 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
12440 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
12450 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
12460 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
12470 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
12480 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f    sqlite3*,.  co
12490 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
124a0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
124b0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
124c0 52 65 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  Rep,.  void*,.  
124d0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
124e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
124f0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
12500 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
12510 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
12520 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
12530 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
12540 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
12550 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
12560 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
12570 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
12580 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
12590 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
125a0 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
125b0 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
125c0 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
125d0 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
125e0 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
125f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12600 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
12610 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12620 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
12630 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12640 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
12650 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12660 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
12670 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
12680 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
12690 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
126a0 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
126b0 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
126c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e  eate_function on
126d0 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
126e0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
126f0 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
12700 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
12710 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
12720 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
12730 73 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e 73  solete Functions
12740 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
12750 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e  ctions are all n
12760 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e  ow obsolete.  In
12770 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
12780 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
12790 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
127a0 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77  th older code, w
127b0 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75  e continue to su
127c0 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20 66  pport.** these f
127d0 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76  unctions.  Howev
127e0 65 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d  er, new developm
127f0 65 6e 74 20 70 72 6f 6a 65 63 74 73 20 73 68 6f  ent projects sho
12800 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
12810 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
12820 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
12830 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
12840 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
12850 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
12860 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
12870 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
12880 6f 75 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e  ou want they do.
12890 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
128a0 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
128b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
128c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  );.int sqlite3_e
128d0 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
128e0 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  tmt*);.int sqlit
128f0 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
12900 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
12910 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
12920 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
12930 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
12940 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid);.../*.** CA
12950 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
12960 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
12970 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
12980 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
12990 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
129a0 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
129b0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
129c0 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
129d0 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
129e0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
129f0 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
12a00 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
12a10 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
12a20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
12a30 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
12a40 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
12a50 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
12a60 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
12a70 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
12a80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
12a90 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
12aa0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
12ab0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
12ac0 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
12ad0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
12ae0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
12af0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
12b00 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
12b10 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
12b20 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
12b30 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
12b40 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
12b50 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
12b60 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
12b70 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
12b80 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
12b90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
12ba0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
12bb0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
12bc0 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
12bd0 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
12be0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
12bf0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
12c00 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
12c10 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
12c20 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
12c30 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  ding .** [sqlite
12c40 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20  3_column_blob | 
12c50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
12c60 20 72 6f 75 74 69 6e 65 73 5d 20 65 78 63 65 70   routines] excep
12c70 74 20 74 68 61 74 20 0a 2a 2a 20 74 68 65 73 65  t that .** these
12c80 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
12c90 20 73 69 6e 67 6c 65 20 5b 73 71 6c 69 74 65 33   single [sqlite3
12ca0 5f 76 61 6c 75 65 2a 5d 20 70 6f 69 6e 74 65 72  _value*] pointer
12cb0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
12cc0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  n [sqlite3_stmt*
12cd0 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
12ce0 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
12cf0 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  number..**.** Th
12d00 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
12d10 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
12d20 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
12d30 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  F16 string.** in
12d40 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
12d50 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
12d60 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65  st machine.  The
12d70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
12d80 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
12d90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
12da0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
12db0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
12dc0 55 54 46 31 36 20 73 74 72 69 6e 67 73 20 61 73  UTF16 strings as
12dd0 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
12de0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
12df0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
12e00 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
12e10 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
12e20 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
12e30 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
12e40 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
12e50 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
12e60 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
12e70 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
12e80 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
12e90 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
12ea0 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
12eb0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
12ec0 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
12ed0 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
12ee0 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
12ef0 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
12f00 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 77 6f 72 64  in order.** word
12f10 73 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  s if the value i
12f20 73 20 6f 72 69 67 69 6e 61 6c 20 61 20 73 74 72  s original a str
12f30 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
12f40 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
12f50 20 74 68 65 6e 20 69 74 20 69 73 20 64 6f 6e 65   then it is done
12f60 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
12f70 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
12f80 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c  s.  The .** [SQL
12f90 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
12fa0 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
12fb0 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
12fc0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  rned..**.** Plea
12fd0 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
12fe0 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
12ff0 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
13000 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
13010 20 69 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f   is returned fro
13020 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
13030 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
13040 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
13050 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
13060 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
13070 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
13080 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
13090 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
130a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
130b0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
130c0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
130d0 5d 2c 20 5b 73 71 6c 69 74 65 5f 76 61 6c 75 65  ], [sqlite_value
130e0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
130f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
13100 65 78 74 31 36 28 29 5d 2e 20 20 0a 2a 2f 0a 63  ext16()].  .*/.c
13110 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
13120 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
13130 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
13140 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
13150 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
13160 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
13170 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
13180 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
13190 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
131a0 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
131b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
131c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
131d0 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
131e0 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 5f 69 6e  lue*);.sqlite_in
131f0 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
13200 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
13210 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75  value*);.const u
13220 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
13230 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
13240 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
13250 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
13260 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
13270 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
13280 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
13290 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
132a0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
132b0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
132c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
132d0 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
132e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
132f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
13300 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
13310 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
13320 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
13330 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
13340 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
13350 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
13360 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
13370 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65  ontext.**.** The
13380 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
13390 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
133a0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
133b0 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  his routine to a
133c0 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72  llocate.** a str
133d0 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69  ucture for stori
133e0 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 20  ng their state. 
133f0 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
13400 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
13410 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 20  is called for a 
13420 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
13430 67 61 74 65 2c 20 61 20 6e 65 77 20 73 74 72 75  gate, a new stru
13440 63 74 75 72 65 20 6f 66 20 73 69 7a 65 20 6e 42  cture of size nB
13450 79 74 65 73 0a 2a 2a 20 69 73 20 61 6c 6c 6f 63  ytes.** is alloc
13460 61 74 65 64 2c 20 7a 65 72 6f 65 64 2c 20 61 6e  ated, zeroed, an
13470 64 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 6e 20  d returned.  On 
13480 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
13490 20 28 66 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d   (for the.** sam
134a0 65 20 61 67 67 72 65 67 61 74 65 20 69 6e 73 74  e aggregate inst
134b0 61 6e 63 65 29 20 74 68 65 20 73 61 6d 65 20 62  ance) the same b
134c0 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65  uffer is returne
134d0 64 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  d.  The implemen
134e0 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
134f0 20 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 75   aggregate can u
13500 73 65 20 74 68 65 20 72 65 74 75 72 6e 65 64 20  se the returned 
13510 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75  buffer to accumu
13520 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  late data..**.**
13530 20 54 68 65 20 62 75 66 66 65 72 20 61 6c 6c 6f   The buffer allo
13540 63 61 74 65 64 20 69 73 20 66 72 65 65 64 20 61  cated is freed a
13550 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
13560 53 51 4c 69 74 65 20 77 68 61 6e 20 74 68 65 20  SQLite whan the 
13570 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65  aggregate.** que
13580 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a  ry concludes..**
13590 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
135a0 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62  rameter should b
135b0 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  e a copy of the 
135c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
135d0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
135e0 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
135f0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
13600 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
13610 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  he callback rout
13620 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
13630 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
13640 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
13650 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
13660 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
13670 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
13680 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
13690 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
136a0 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
136b0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
136c0 54 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  The pUserData pa
136d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
136e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
136f0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
13700 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
13710 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
13720 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64  routines.** used
13730 20 74 6f 20 72 65 67 69 73 74 65 72 20 75 73 65   to register use
13740 72 20 66 75 6e 63 74 69 6f 6e 73 20 69 73 20 61  r functions is a
13750 76 61 69 6c 61 62 6c 65 20 74 6f 0a 2a 2a 20 74  vailable to.** t
13760 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
13770 6e 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  n of the functio
13780 6e 20 75 73 69 6e 67 20 74 68 69 73 20 63 61 6c  n using this cal
13790 6c 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  l..*/.void *sqli
137a0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
137b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
137c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
137d0 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
137e0 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
137f0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
13800 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
13810 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
13820 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
13830 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
13840 6d 65 74 61 2d 64 61 74 61 20 77 69 74 68 20 61  meta-data with a
13850 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
13860 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
13870 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
13880 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
13890 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
138a0 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
138b0 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
138c0 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
138d0 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
138e0 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
138f0 65 64 20 6d 65 74 61 2d 64 61 74 61 20 6d 61 79  ed meta-data may
13900 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
13910 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
13920 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
13930 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
13940 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
13950 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
13960 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
13970 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
13980 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
13990 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
139a0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 2d 64 61  ed as.** meta-da
139b0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
139c0 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
139d0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
139e0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
139f0 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
13a00 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
13a10 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
13a20 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
13a30 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
13a40 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
13a50 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
13a60 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
13a70 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
13a80 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
13a90 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
13aa0 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
13ab0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
13ac0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
13ad0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
13ae0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
13af0 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 2d 64  er to the meta-d
13b00 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
13b10 64 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  d with the Nth a
13b20 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 20 74 6f  rgument value to
13b30 20 74 68 65 20 63 75 72 72 65 6e 74 20 53 51 4c   the current SQL
13b40 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
13b50 6c 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  l, where N is th
13b60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
13b70 65 72 2e 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64  er. If no meta-d
13b80 61 74 61 20 68 61 73 20 62 65 65 6e 20 73 65 74  ata has been set
13b90 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 76 61 6c   for.** that val
13ba0 75 65 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ue, then a NULL 
13bb0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
13bc0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
13bd0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
13be0 74 61 28 29 20 69 73 20 75 73 65 64 20 74 6f 20  ta() is used to 
13bf0 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 2d 64  associate meta-d
13c00 61 74 61 20 77 69 74 68 20 61 6e 20 53 51 4c 0a  ata with an SQL.
13c10 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  ** function argu
13c20 6d 65 6e 74 2e 20 54 68 65 20 74 68 69 72 64 20  ment. The third 
13c30 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
13c40 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
13c50 74 61 2d 64 61 74 61 0a 2a 2a 20 74 6f 20 62 65  ta-data.** to be
13c60 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
13c70 20 74 68 65 20 4e 74 68 20 75 73 65 72 20 66 75   the Nth user fu
13c80 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 20  nction argument 
13c90 76 61 6c 75 65 2e 20 54 68 65 20 66 6f 75 72 74  value. The fourt
13ca0 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73  h.** parameter s
13cb0 70 65 63 69 66 69 65 73 20 61 20 64 65 73 74 72  pecifies a destr
13cc0 75 63 74 6f 72 20 74 68 61 74 20 77 69 6c 6c 20  uctor that will 
13cd0 62 65 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  be called on the
13ce0 20 6d 65 74 61 2d 0a 2a 2a 20 64 61 74 61 20 70   meta-.** data p
13cf0 6f 69 6e 74 65 72 20 74 6f 20 72 65 6c 65 61 73  ointer to releas
13d00 65 20 69 74 20 77 68 65 6e 20 69 74 20 69 73 20  e it when it is 
13d10 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
13d20 65 64 2e 20 49 66 20 74 68 65 20 0a 2a 2a 20 64  ed. If the .** d
13d30 65 73 74 72 75 63 74 6f 72 20 69 73 20 4e 55 4c  estructor is NUL
13d40 4c 2c 20 69 74 20 69 73 20 6e 6f 74 20 69 6e 76  L, it is not inv
13d50 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70  oked..**.** In p
13d60 72 61 63 74 69 63 65 2c 20 6d 65 74 61 2d 64 61  ractice, meta-da
13d70 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
13d80 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
13d90 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78   calls for.** ex
13da0 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61  pressions that a
13db0 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63  re constant at c
13dc0 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69  ompile time. Thi
13dd0 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72  s includes liter
13de0 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
13df0 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a   SQL variables..
13e00 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
13e10 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _get_auxdata(sql
13e20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
13e30 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
13e40 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
13e50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
13e60 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  int, void*, void
13e70 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
13e80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13e90 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
13ea0 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
13eb0 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
13ec0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
13ed0 70 65 63 69 61 6c 20 76 61 6c 75 65 20 66 6f 72  pecial value for
13ee0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
13ef0 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
13f00 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
13f10 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
13f20 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
13f30 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
13f40 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73  ()].  If the des
13f50 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
13f60 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
13f70 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
13f80 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
13f90 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
13fa0 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
13fb0 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
13fc0 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
13fd0 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
13fe0 20 20 54 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45    The .** SQLITE
13ff0 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
14000 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
14010 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
14020 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
14030 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
14040 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
14050 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
14060 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
14070 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
14080 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
14090 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
140a0 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
140b0 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
140c0 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
140d0 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
140e0 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
140f0 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
14100 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
14110 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
14120 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
14130 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
14140 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
14150 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
14160 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
14170 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
14180 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
14190 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
141a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
141b0 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
141c0 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
141d0 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
141e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
141f0 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
14200 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
14210 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
14220 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
14230 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
14240 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
14250 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
14260 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
14270 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
14280 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
14290 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
142a0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
142b0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
142c0 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
142d0 20 6c 69 6b 65 20 74 68 65 20 0a 2a 2a 20 5b 73   like the .** [s
142e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
142f0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
14300 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  *] family of fun
14310 63 74 69 6f 6e 73 20 75 73 65 64 0a 2a 2a 20 74  ctions used.** t
14320 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
14330 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
14340 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
14350 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
14360 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  r to the.** [sql
14370 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
14380 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
14390 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
143a0 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
143b0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
143c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
143d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
143e0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
143f0 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
14400 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
14410 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
14420 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
14430 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
14440 6e 2e 20 20 54 68 65 0a 2a 2a 20 70 61 72 61 6d  n.  The.** param
14450 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
14460 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
14470 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
14480 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 69 73  _error16().** is
14490 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
144a0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
144b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
144c0 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
144d0 20 63 61 75 73 65 20 74 68 65 20 66 75 6e 63 74   cause the funct
144e0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
144f0 6f 6e 0a 2a 2a 20 74 6f 20 74 68 72 6f 77 20 61  on.** to throw a
14500 6e 64 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  nd error indicat
14510 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
14520 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20  g or BLOB is to 
14530 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65 70 72 65  long.** to repre
14540 73 65 6e 74 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  sent..*/.void sq
14550 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
14560 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
14570 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
14580 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
14590 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
145a0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
145b0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
145c0 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
145d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
145e0 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
145f0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
14600 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
14610 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
14620 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
14630 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
14640 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
14650 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
14660 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
14670 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
14680 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
14690 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
146a0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
146b0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
146c0 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
146d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
146e0 69 74 65 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  ite_int64);.void
146f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
14700 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
14710 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
14720 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
14730 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
14740 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
14750 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
14760 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
14770 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
14780 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
14790 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
147a0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
147b0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
147c0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
147d0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
147e0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
147f0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
14800 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
14810 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
14820 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
14830 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
14840 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
14850 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
14860 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
14870 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
14880 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
14890 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
148a0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
148b0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
148c0 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
148d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
148e0 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
148f0 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a  g Sequences.**.*
14900 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
14910 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  s are used to ad
14920 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  d new collation 
14930 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65  sequences to the
14940 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68  .** [sqlite3*] h
14950 61 6e 64 6c 65 20 73 70 65 63 69 66 69 65 64 20  andle specified 
14960 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
14970 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68  ument. .**.** Th
14980 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65  e name of the ne
14990 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
149a0 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65  ence is specifie
149b0 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72  d as a UTF-8 str
149c0 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
149d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
149e0 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
149f0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
14a00 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
14a10 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66   UTF-16 string f
14a20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
14a30 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
14a40 20 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a    In all cases.*
14a50 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61  * the name is pa
14a60 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
14a70 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
14a80 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
14a90 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d  third argument m
14aa0 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  ust be one of th
14ab0 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c  e constants [SQL
14ac0 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53  ITE_UTF8],.** [S
14ad0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f  QLITE_UTF16LE] o
14ae0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  r [SQLITE_UTF16B
14af0 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
14b00 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70  hat the user-sup
14b10 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65  plied.** routine
14b20 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70   expects to be p
14b30 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74  assed pointers t
14b40 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65  o strings encode
14b50 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a  d using UTF-8,.*
14b60 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d  * UTF-16 little-
14b70 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d 31 36  endian or UTF-16
14b80 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65 73 70   big-endian resp
14b90 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
14ba0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
14bb0 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72   user supplied r
14bc0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70  outine must be p
14bd0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66  assed as the fif
14be0 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  th.** argument. 
14bf0 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
14c00 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20  his is the same 
14c10 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  as deleting the 
14c20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
14c30 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53  uence (so that S
14c40 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c  QLite cannot cal
14c50 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 20 45  l it anymore). E
14c60 61 63 68 20 74 69 6d 65 20 74 68 65 20 75 73 65  ach time the use
14c70 72 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 66 75  r.** supplied fu
14c80 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
14c90 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 20  d, it is passed 
14ca0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
14cb0 69 64 2a 20 70 61 73 73 65 64 20 61 73 0a 2a 2a  id* passed as.**
14cc0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
14cd0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
14ce0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
14cf0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
14d00 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
14d10 6e 31 36 28 29 20 61 73 20 69 74 73 20 66 69 72  n16() as its fir
14d20 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
14d30 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
14d40 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  g arguments to t
14d50 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64  he user-supplied
14d60 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f   routine are two
14d70 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63   strings,.** eac
14d80 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  h represented by
14d90 20 61 20 5b 6c 65 6e 67 74 68 2c 20 64 61 74 61   a [length, data
14da0 5d 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64  ] pair and encod
14db0 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69  ed in the encodi
14dc0 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70  ng.** that was p
14dd0 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
14de0 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e  rd argument when
14df0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   the collation s
14e00 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72  equence was.** r
14e10 65 67 69 73 74 65 72 65 64 2e 20 54 68 65 20 75  egistered. The u
14e20 73 65 72 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  ser routine shou
14e30 6c 64 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69  ld return negati
14e40 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69  ve, zero or posi
14e50 74 69 76 65 20 69 66 0a 2a 2a 20 74 68 65 20 66  tive if.** the f
14e60 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c  irst string is l
14e70 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20  ess than, equal 
14e80 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
14e90 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  han the second.*
14ea0 2a 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28  * string. i.e. (
14eb0 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47  STRING1 - STRING
14ec0 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  2)..**.** The sq
14ed0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
14ee0 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
14ef0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
14f00 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
14f10 29 0a 2a 2a 20 65 78 63 61 70 74 20 74 68 61 74  ).** excapt that
14f20 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74   it takes an ext
14f30 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ra argument whic
14f40 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  h is a destructo
14f50 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c  r for.** the col
14f60 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73  lation.  The des
14f70 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
14f80 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  d when the colla
14f90 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72  tion is.** destr
14fa0 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73  oyed and is pass
14fb0 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ed a copy of the
14fc0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
14fd0 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a  r void* pointer.
14fe0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
14ff0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
15000 6f 6e 5f 76 32 28 29 2e 20 20 43 6f 6c 6c 61 74  on_v2().  Collat
15010 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79  ions are destroy
15020 65 64 20 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20  ed when.** they 
15030 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
15040 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f  y later calls to
15050 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63   the collation c
15060 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  reation function
15070 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65  s.** or when the
15080 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61   [sqlite3*] data
15090 62 61 73 65 20 68 61 6e 64 6c 65 20 69 73 20 63  base handle is c
150a0 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
150b0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
150c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
150d0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
150e0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
150f0 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   is experimental
15100 20 61 6e 64 0a 2a 2a 20 73 75 62 6a 65 63 74 20   and.** subject 
15110 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
15120 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20 20 54  ure releases.  T
15130 68 65 20 6f 74 68 65 72 20 63 6f 6c 6c 61 74 69  he other collati
15140 6f 6e 20 63 72 65 61 74 69 6f 6e 0a 2a 2a 20 66  on creation.** f
15150 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 73 74 61  unctions are sta
15160 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ble..*/.int sqli
15170 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
15180 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
15190 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
151a0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
151b0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
151c0 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
151d0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
151e0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
151f0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
15200 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
15210 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
15220 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
15230 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
15240 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
15250 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
15260 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
15270 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
15280 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
15290 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
152a0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
152b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
152c0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
152d0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
152e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
152f0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
15300 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
15310 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
15320 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
15330 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
15340 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
15350 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
15360 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
15370 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76  acks.**.** To av
15380 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65  oid having to re
15390 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61  gister all colla
153a0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62  tion sequences b
153b0 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65  efore a database
153c0 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c  .** can be used,
153d0 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61   a single callba
153e0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  ck function may 
153f0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  be registered wi
15400 74 68 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  th the.** databa
15410 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 62 65 20  se handle to be 
15420 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20  called whenever 
15430 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  an undefined col
15440 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
15450 69 73 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e 0a  is.** required..
15460 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e  **.** If the fun
15470 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65  ction is registe
15480 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71  red using the sq
15490 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
154a0 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a  needed() API,.**
154b0 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73   then it is pass
154c0 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  ed the names of 
154d0 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
154e0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73  ion sequences as
154f0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f   strings.** enco
15500 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 49 66  ded in UTF-8. If
15510 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
15520 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
15530 20 75 73 65 64 2c 20 74 68 65 20 6e 61 6d 65 73   used, the names
15540 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 61  .** are passed a
15550 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
15560 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
15570 6f 72 64 65 72 2e 20 41 20 63 61 6c 6c 20 74 6f  order. A call to
15580 20 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e 63 74   either.** funct
15590 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79  ion replaces any
155a0 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61   existing callba
155b0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ck..**.** When t
155c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
155d0 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
155e0 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
155f0 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
15600 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
15610 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
15620 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
15630 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
15640 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
15650 65 64 31 36 28 29 2e 20 54 68 65 20 73 65 63 6f  ed16(). The seco
15660 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
15670 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68  he database.** h
15680 61 6e 64 6c 65 2e 20 54 68 65 20 74 68 69 72 64  andle. The third
15690 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
156a0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
156b0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
156c0 42 45 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  BE], or.** [SQLI
156d0 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64  TE_UTF16LE], ind
156e0 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74  icating the most
156f0 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20   desirable form 
15700 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
15710 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e  .** sequence fun
15720 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20  ction required. 
15730 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
15740 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
15750 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
15760 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
15770 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  quence..**.** Th
15780 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
15790 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
157a0 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
157b0 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
157c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
157d0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
157e0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
157f0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
15800 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
15810 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
15820 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  _v2()]..*/.int s
15830 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
15840 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
15850 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
15860 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
15870 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
15880 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
15890 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
158a0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
158b0 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
158c0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
158d0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
158e0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
158f0 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
15900 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
15910 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
15920 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
15930 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
15940 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
15950 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
15960 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
15970 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
15980 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
15990 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
159a0 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
159b0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
159c0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
159d0 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a  nt sqlite3_key(.
159e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
159f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
15a00 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
15a10 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
15a20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
15a30 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
15a40 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a  * The key */.);.
15a50 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68  ./*.** Change th
15a60 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e  e key on an open
15a70 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74   database.  If t
15a80 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62  he current datab
15a90 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e  ase is not.** en
15aa0 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f  crypted, this ro
15ab0 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79  utine will encry
15ac0 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d  pt it.  If pNew=
15ad0 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74  =0 or nNew==0, t
15ae0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69  he.** database i
15af0 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a  s decrypted..**.
15b00 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
15b10 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
15b20 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
15b30 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
15b40 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
15b50 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
15b60 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73  lite3_rekey(.  s
15b70 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
15b80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
15b90 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
15ba0 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
15bb0 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
15bc0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
15bd0 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
15be0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15bf0 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  :  Suspend Execu
15c00 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
15c10 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73   Time.**.** This
15c20 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
15c30 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
15c40 65 61 64 20 74 6f 20 73 75 73 70 65 63 74 20 65  ead to suspect e
15c50 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 61 20 6e 75  xecution.** a nu
15c60 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
15c70 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
15c80 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
15c90 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
15ca0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
15cb0 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
15cc0 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
15cd0 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63  ith .** millisec
15ce0 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74  ond time resolut
15cf0 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69  ion, then the ti
15d00 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64  me will be round
15d10 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74 68 65  ed up to .** the
15d20 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
15d30 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
15d40 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
15d50 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 0a 2a  leep actually .*
15d60 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d  * requested from
15d70 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
15d80 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65  ystem is returne
15d90 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
15da0 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
15db0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
15dc0 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
15dd0 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
15de0 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a  rary Files.**.**
15df0 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20   If this global 
15e00 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
15e10 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
15e20 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
15e30 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
15e40 66 6f 6c 64 65 72 20 28 61 2e 6b 61 2e 20 64 69  folder (a.ka. di
15e50 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
15e60 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
15e70 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
15e80 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
15e90 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
15ea0 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68  irectory.  If th
15eb0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
15ec0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  s NULL pointer, 
15ed0 74 68 65 6e 20 53 51 4c 69 74 65 20 64 6f 65 73  then SQLite does
15ee0 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e   a search for an
15ef0 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 65 6d   appropriate tem
15f00 70 6f 72 61 72 79 0a 2a 2a 20 66 69 6c 65 20 64  porary.** file d
15f10 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
15f20 4f 6e 63 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70  Once [sqlite3_op
15f30 65 6e 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  en()] has been c
15f40 61 6c 6c 65 64 2c 20 63 68 61 6e 67 69 6e 67 20  alled, changing 
15f50 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 77 69  this variable wi
15f60 6c 6c 0a 2a 2a 20 69 6e 76 61 6c 69 64 61 74 65  ll.** invalidate
15f70 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 65 6d   the current tem
15f80 70 6f 72 61 72 79 20 64 61 74 61 62 61 73 65 2c  porary database,
15f90 20 69 66 20 61 6e 79 2e 20 20 47 65 6e 65 72 61   if any.  Genera
15fa0 6c 6c 79 20 73 70 65 61 6b 69 6e 67 2c 0a 2a 2a  lly speaking,.**
15fb0 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   it is not safe 
15fc0 74 6f 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 72  to invoke this r
15fd0 6f 75 74 69 6e 65 20 61 66 74 65 72 20 5b 73 71  outine after [sq
15fe0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 68 61  lite3_open()] ha
15ff0 73 0a 2a 2a 20 62 65 65 6e 20 63 61 6c 6c 65 64  s.** been called
16000 2e 0a 2a 2f 0a 65 78 74 65 72 6e 20 63 68 61 72  ..*/.extern char
16010 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   *sqlite3_temp_d
16020 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
16030 20 43 41 50 49 33 52 45 46 3a 20 20 54 65 73 74   CAPI3REF:  Test
16040 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 44   To See If The D
16050 61 74 61 62 73 65 20 49 73 20 49 6e 20 41 75 74  atabse Is In Aut
16060 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a  o-Commit Mode.**
16070 0a 2a 2a 20 54 65 73 74 20 74 6f 20 73 65 65 20  .** Test to see 
16080 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
16090 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
160a0 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 61 75 74  ection is in aut
160b0 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 6d 6f 64 65 2e  ocommit.** mode.
160c0 20 20 52 65 74 75 72 6e 20 54 52 55 45 20 69 66    Return TRUE if
160d0 20 69 74 20 69 73 20 61 6e 64 20 46 41 4c 53 45   it is and FALSE
160e0 20 69 66 20 6e 6f 74 2e 20 20 41 75 74 6f 63 6f   if not.  Autoco
160f0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 0a  mmit mode is on.
16100 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  ** by default.  
16110 41 75 74 6f 63 6f 6d 6d 69 74 20 69 73 20 64 69  Autocommit is di
16120 73 61 62 6c 65 64 20 62 79 20 61 20 42 45 47 49  sabled by a BEGI
16130 4e 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  N statement and 
16140 72 65 65 6e 61 62 6c 65 64 0a 2a 2a 20 62 79 20  reenabled.** by 
16150 74 68 65 20 6e 65 78 74 20 43 4f 4d 4d 49 54 20  the next COMMIT 
16160 6f 72 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2f 0a  or ROLLBACK..*/.
16170 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
16180 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
16190 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
161a0 49 33 52 45 46 3a 20 20 46 69 6e 64 20 54 68 65  I3REF:  Find The
161b0 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65   Database Handle
161c0 20 41 73 73 6f 63 69 61 74 65 64 20 57 69 74 68   Associated With
161d0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
161e0 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 52 65 74 75  ement.**.** Retu
161f0 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a  rn the [sqlite3*
16200 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  ] database handl
16210 65 20 74 6f 20 77 68 69 63 68 20 61 0a 2a 2a 20  e to which a.** 
16220 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
16230 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
16240 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20  nt] belongs..** 
16250 54 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65  This is the same
16260 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
16270 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 74 68 65   that was.** the
16280 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16290 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
162a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
162b0 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a   its variants.**
162c0 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74   that was used t
162d0 6f 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  o create the sta
162e0 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
162f0 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71  rst place..*/.sq
16300 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
16310 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
16320 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _stmt*);.../*.**
16330 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69   CAPI3REF: Commi
16340 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e  t And Rollback N
16350 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
16360 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  backs.**.** Thes
16370 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65  e routines.** re
16380 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
16390 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 62 65 20  functions to be 
163a0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
163b0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a   a transaction.*
163c0 2a 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 20 6f  * is committed o
163d0 72 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 20 20  r rolled back.  
163e0 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  The pArg argumen
163f0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
16400 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ugh.** to the ca
16410 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74 68 65 20  llback.  If the 
16420 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f  callback on a co
16430 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69  mmit hook functi
16440 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e  on .** returns n
16450 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
16460 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76  e commit is conv
16470 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
16480 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  lback..**.** If 
16490 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  another function
164a0 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20   was previously 
164b0 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 20  registered, its 
164c0 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65  pArg value is re
164d0 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72  turned..** Other
164e0 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74  wise NULL is ret
164f0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  urned..**.** Reg
16500 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20  istering a NULL 
16510 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
16520 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  s the callback..
16530 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75  **.** For the pu
16540 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
16550 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
16560 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
16570 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65  e been .** rolle
16580 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70  d back if an exp
16590 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22  licit "ROLLBACK"
165a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78   statement is ex
165b0 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e  ecuted, or.** an
165c0 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72   error or constr
165d0 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69  aint causes an i
165e0 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b  mplicit rollback
165f0 20 74 6f 20 6f 63 63 75 72 2e 20 54 68 65 20 0a   to occur. The .
16600 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ** callback is n
16610 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
16620 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61  transaction is a
16630 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
16640 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 62 65 63 61  led.** back beca
16650 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  use the database
16660 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
16670 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
16680 73 65 20 61 72 65 20 65 78 70 65 72 69 6d 65 6e  se are experimen
16690 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
166a0 6e 64 20 61 72 65 20 73 75 62 6a 65 63 74 20 74  nd are subject t
166b0 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69  o change..*/.voi
166c0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  d *sqlite3_commi
166d0 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  t_hook(sqlite3*,
166e0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
166f0 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71  void*);.void *sq
16700 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
16710 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ook(sqlite3*, vo
16720 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76  id(*)(void *), v
16730 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
16740 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61  PI3REF: Data Cha
16750 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  nge Notification
16760 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
16770 20 52 65 67 69 73 74 65 72 20 61 20 63 61 6c 6c   Register a call
16780 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
16790 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  th the database 
167a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74  connection ident
167b0 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
167c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
167d0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
167e0 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20  enever a row is 
167f0 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
16800 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
16810 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65   Any callback se
16820 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
16830 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e  call to this fun
16840 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 73 61  ction for the sa
16850 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  me .** database 
16860 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
16870 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20  erridden..**.** 
16880 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
16890 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
168a0 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   to the function
168b0 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20   to invoke when 
168c0 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64  a .** row is upd
168d0 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
168e0 72 20 64 65 6c 65 74 65 64 2e 20 54 68 65 20 66  r deleted. The f
168f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
16900 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
16910 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 68  .** a copy of th
16920 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
16930 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61   to sqlite3_upda
16940 74 65 5f 68 6f 6f 6b 28 29 2e 20 54 68 65 20 73  te_hook(). The s
16950 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a  econd callback .
16960 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  ** argument is o
16970 6e 65 20 6f 66 20 53 51 4c 49 54 45 5f 49 4e 53  ne of SQLITE_INS
16980 45 52 54 2c 20 53 51 4c 49 54 45 5f 44 45 4c 45  ERT, SQLITE_DELE
16990 54 45 20 6f 72 20 53 51 4c 49 54 45 5f 55 50 44  TE or SQLITE_UPD
169a0 41 54 45 2c 20 64 65 70 65 6e 64 69 6e 67 0a 2a  ATE, depending.*
169b0 2a 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  * on the operati
169c0 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
169d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62  he callback to b
169e0 65 20 69 6e 76 6f 6b 65 64 2e 20 54 68 65 20 74  e invoked. The t
169f0 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75  hird and .** fou
16a00 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  rth arguments to
16a10 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f   the callback co
16a20 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74  ntain pointers t
16a30 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  o the database a
16a40 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d  nd .** table nam
16a50 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
16a60 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 20 54   affected row. T
16a70 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63  he final callbac
16a80 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 0a  k parameter is .
16a90 2a 2a 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  ** the rowid of 
16aa0 74 68 65 20 72 6f 77 2e 20 49 6e 20 74 68 65 20  the row. In the 
16ab0 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74  case of an updat
16ac0 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 72  e, this is the r
16ad0 6f 77 69 64 20 61 66 74 65 72 20 0a 2a 2a 20 74  owid after .** t
16ae0 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20  he update takes 
16af0 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  place..**.** The
16b00 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20   update hook is 
16b10 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
16b20 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
16b30 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d   tables are.** m
16b40 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71  odified (i.e. sq
16b50 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
16b60 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29  sqlite_sequence)
16b70 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
16b80 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20  er function was 
16b90 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
16ba0 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 20  tered, its pArg 
16bb0 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
16bc0 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20  d..** Otherwise 
16bd0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
16be0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
16bf0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a  e3_update_hook(.
16c00 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
16c10 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e  oid(*)(void *,in
16c20 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c  t ,char const *,
16c30 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c  char const *,sql
16c40 69 74 65 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f  ite_int64),.  vo
16c50 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  id*.);../*.** CA
16c60 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20  PI3REF:  Enable 
16c70 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65  Or Disable Share
16c80 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a  d Pager Cache.**
16c90 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
16ca0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
16cb0 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67  bles the sharing
16cc0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
16cd0 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63   cache.** and sc
16ce0 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74  hema data struct
16cf0 75 72 65 73 20 62 65 74 77 65 65 6e 20 63 6f 6e  ures between con
16d00 6e 65 63 74 69 6f 6e 73 20 74 6f 20 74 68 65 20  nections to the 
16d10 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 0a 2a  same database..*
16d20 2a 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61  * Sharing is ena
16d30 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
16d40 6d 65 6e 74 20 69 73 20 74 72 75 65 20 61 6e 64  ment is true and
16d50 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65   disabled if the
16d60 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20   argument.** is 
16d70 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63  false..**.** Cac
16d80 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e  he sharing is en
16d90 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c  abled and disabl
16da0 65 64 20 6f 6e 20 61 20 74 68 72 65 61 64 2d 62  ed on a thread-b
16db0 79 2d 74 68 72 65 61 64 20 62 61 73 69 73 2e 0a  y-thread basis..
16dc0 2a 2a 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  ** Each call to 
16dd0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61  this routine ena
16de0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
16df0 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6f   cache sharing o
16e00 6e 6c 79 20 66 6f 72 0a 2a 2a 20 63 6f 6e 6e 65  nly for.** conne
16e10 63 74 69 6f 6e 73 20 63 72 65 61 74 65 64 20 69  ctions created i
16e20 6e 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  n the same threa
16e30 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 73 20  d in which this 
16e40 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
16e50 64 2e 0a 2a 2a 20 54 68 65 72 65 20 69 73 20 6e  d..** There is n
16e60 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20  o mechanism for 
16e70 73 68 61 72 69 6e 67 20 63 61 63 68 65 20 62 65  sharing cache be
16e80 74 77 65 65 6e 20 64 61 74 61 62 61 73 65 20 63  tween database c
16e90 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 72 75  onnections.** ru
16ea0 6e 6e 69 6e 67 20 69 6e 20 64 69 66 66 65 72 65  nning in differe
16eb0 6e 74 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a  nt threads..**.*
16ec0 2a 20 53 68 61 72 69 6e 67 20 6d 75 73 74 20 62  * Sharing must b
16ed0 65 20 64 69 73 61 62 6c 65 64 20 70 72 69 6f 72  e disabled prior
16ee0 20 74 6f 20 73 68 75 74 74 69 6e 67 20 64 6f 77   to shutting dow
16ef0 6e 20 61 20 74 68 72 65 61 64 20 6f 72 20 65 6c  n a thread or el
16f00 73 65 0a 2a 2a 20 74 68 65 20 74 68 72 65 61 64  se.** the thread
16f10 20 77 69 6c 6c 20 6c 65 61 6b 20 6d 65 6d 6f 72   will leak memor
16f20 79 2e 20 20 43 61 6c 6c 20 74 68 69 73 20 72 6f  y.  Call this ro
16f30 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
16f40 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 30 20 74  gument of.** 0 t
16f50 6f 20 74 75 72 6e 20 6f 66 66 20 73 68 61 72 69  o turn off shari
16f60 6e 67 2e 20 20 4f 72 20 75 73 65 20 74 68 65 20  ng.  Or use the 
16f70 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
16f80 6c 65 61 6e 75 70 28 29 20 41 50 49 2e 0a 2a 2a  leanup() API..**
16f90 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
16fa0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 63 61 6c   must not be cal
16fb0 6c 65 64 20 77 68 65 6e 20 61 6e 79 20 64 61 74  led when any dat
16fc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16fd0 73 0a 2a 2a 20 61 72 65 20 61 63 74 69 76 65 20  s.** are active 
16fe0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  in the current t
16ff0 68 72 65 61 64 2e 20 20 45 6e 61 62 6c 69 6e 67  hread.  Enabling
17000 20 6f 72 20 64 69 73 61 62 6c 69 6e 67 20 73 68   or disabling sh
17010 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 77 68  ared.** cache wh
17020 69 6c 65 20 74 68 65 72 65 20 61 72 65 20 61 63  ile there are ac
17030 74 69 76 65 20 64 61 74 61 62 61 73 65 20 63 6f  tive database co
17040 6e 6e 65 63 74 69 6f 6e 73 20 77 69 6c 6c 20 72  nnections will r
17050 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 6d 65 6d 6f  esult.** in memo
17060 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ry corruption..*
17070 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 68  *.** When the sh
17080 61 72 65 64 20 63 61 63 68 65 20 69 73 20 65 6e  ared cache is en
17090 61 62 6c 65 64 2c 20 74 68 65 0a 2a 2a 20 66 6f  abled, the.** fo
170a0 6c 6c 6f 77 69 6e 67 20 72 6f 75 74 69 6e 65 73  llowing routines
170b0 20 6d 75 73 74 20 61 6c 77 61 79 73 20 62 65 20   must always be 
170c0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
170d0 73 61 6d 65 20 74 68 72 65 61 64 3a 0a 2a 2a 20  same thread:.** 
170e0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
170f0 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
17100 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
17110 65 33 5f 73 74 65 70 28 29 5d 2c 0a 2a 2a 20 5b  e3_step()],.** [
17120 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
17130 2c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  , [sqlite3_final
17140 69 7a 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ize()], and [sql
17150 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
17160 2a 20 54 68 69 73 20 69 73 20 64 75 65 20 74 6f  * This is due to
17170 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
17180 68 65 20 73 68 61 72 65 64 20 63 61 63 68 65 20  he shared cache 
17190 6d 61 6b 65 73 20 75 73 65 20 6f 66 0a 2a 2a 20  makes use of.** 
171a0 74 68 72 65 61 64 2d 73 70 65 63 69 66 69 63 20  thread-specific 
171b0 73 74 6f 72 61 67 65 20 73 6f 20 74 68 61 74 20  storage so that 
171c0 69 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c  it will be avail
171d0 61 62 6c 65 20 66 6f 72 20 73 68 61 72 69 6e 67  able for sharing
171e0 0a 2a 2a 20 77 69 74 68 20 6f 74 68 65 72 20 63  .** with other c
171f0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  onnections..**.*
17200 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * Virtual tables
17210 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20   cannot be used 
17220 77 69 74 68 20 61 20 73 68 61 72 65 64 20 63 61  with a shared ca
17230 63 68 65 2e 20 20 57 68 65 6e 20 73 68 61 72 65  che.  When share
17240 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
17250 61 62 6c 65 64 2c 20 74 68 65 20 73 71 6c 69 74  abled, the sqlit
17260 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
17270 28 29 20 41 50 49 20 75 73 65 64 20 74 6f 20 72  () API used to r
17280 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75  egister.** virtu
17290 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61  al tables will a
172a0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20  lways return an 
172b0 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  error..**.** Thi
172c0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
172d0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  s [SQLITE_OK] if
172e0 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61   shared cache wa
172f0 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20  s.** enabled or 
17300 64 69 73 61 62 6c 65 64 20 73 75 63 63 65 73 73  disabled success
17310 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 53 51 4c 49  fully.  An [SQLI
17320 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72  TE_ERROR | error
17330 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74   code].** is ret
17340 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e  urned otherwise.
17350 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 61  .**.** Shared ca
17360 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  che is disabled 
17370 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 62  by default for b
17380 61 63 6b 77 61 72 64 20 63 6f 6d 70 61 74 69 62  ackward compatib
17390 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ility..*/.int sq
173a0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
173b0 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a  red_cache(int);.
173c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
173d0 20 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65    Attempt To Fre
173e0 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a  e Heap Memory.**
173f0 0a 2a 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 66  .** Attempt to f
17400 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68  ree N bytes of h
17410 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65  eap memory by de
17420 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65  allocating non-e
17430 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 6d 65 6d 6f  ssential.** memo
17440 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68  ry allocations h
17450 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62  eld by the datab
17460 61 73 65 20 6c 69 62 72 61 72 79 20 28 65 78 61  ase library (exa
17470 6d 70 6c 65 3a 20 6d 65 6d 6f 72 79 20 0a 2a 2a  mple: memory .**
17480 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
17490 61 74 61 62 61 73 65 20 70 61 67 65 73 20 74 6f  atabase pages to
174a0 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
174b0 61 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ance)..**.** Thi
174c0 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f  s function is no
174d0 74 20 61 20 70 61 72 74 20 6f 66 20 73 74 61 6e  t a part of stan
174e0 64 61 72 64 20 62 75 69 6c 64 73 2e 20 20 49 74  dard builds.  It
174f0 20 69 73 20 6f 6e 6c 79 20 63 72 65 61 74 65 64   is only created
17500 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
17510 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
17520 68 65 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  he SQLITE_ENABLE
17530 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
17540 4e 54 20 6d 61 63 72 6f 2e 0a 2a 2f 0a 69 6e 74  NT macro..*/.int
17550 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
17560 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f  _memory(int);../
17570 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
17580 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f  Impose A Limit O
17590 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a  n Heap Size.**.*
175a0 2a 20 50 6c 61 63 65 20 61 20 22 73 6f 66 74 22  * Place a "soft"
175b0 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d   limit on the am
175c0 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d  ount of heap mem
175d0 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20  ory that may be 
175e0 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
175f0 53 51 4c 69 74 65 20 77 69 74 68 69 6e 20 74 68  SQLite within th
17600 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
17610 2e 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c  . If an internal
17620 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72   allocation is r
17630 65 71 75 65 73 74 65 64 20 0a 2a 2a 20 74 68 61  equested .** tha
17640 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74  t would exceed t
17650 68 65 20 73 70 65 63 69 66 69 65 64 20 6c 69 6d  he specified lim
17660 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  it, [sqlite3_rel
17670 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69  ease_memory()] i
17680 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 6f 6e 65  s invoked.** one
17690 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
176a0 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73  o free up some s
176b0 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 65 20  pace before the 
176c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6d 61  allocation is ma
176d0 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  de..**.** The li
176e0 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73  mit is called "s
176f0 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 69 66  oft", because if
17700 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
17710 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 63 61 6e 6e  e_memory()] cann
17720 6f 74 20 66 72 65 65 0a 2a 2a 20 73 75 66 66 69  ot free.** suffi
17730 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20  cient memory to 
17740 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69  prevent the limi
17750 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63  t from being exc
17760 65 65 64 65 64 2c 20 74 68 65 20 6d 65 6d 6f 72  eeded, the memor
17770 79 20 69 73 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  y is.** allocate
17780 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65  d anyway and the
17790 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69   current operati
177a0 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a  on proceeds..**.
177b0 2a 2a 20 50 72 69 6f 72 20 74 6f 20 73 68 75 74  ** Prior to shut
177c0 74 69 6e 67 20 64 6f 77 6e 20 61 20 74 68 72 65  ting down a thre
177d0 61 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  ad sqlite3_soft_
177e0 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 6d 75 73  heap_limit() mus
177f0 74 20 62 65 20 73 65 74 20 74 6f 20 0a 2a 2a 20  t be set to .** 
17800 7a 65 72 6f 20 28 74 68 65 20 64 65 66 61 75 6c  zero (the defaul
17810 74 29 20 6f 72 20 65 6c 73 65 20 74 68 65 20 74  t) or else the t
17820 68 72 65 61 64 20 77 69 6c 6c 20 6c 65 61 6b 20  hread will leak 
17830 6d 65 6d 6f 72 79 2e 20 41 6c 74 65 72 6e 61 74  memory. Alternat
17840 69 76 65 6c 79 2c 20 75 73 65 0a 2a 2a 20 74 68  ively, use.** th
17850 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  e [sqlite3_threa
17860 64 5f 63 6c 65 61 6e 75 70 28 29 5d 20 41 50 49  d_cleanup()] API
17870 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69  ..**.** A negati
17880 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65  ve or zero value
17890 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61   for N means tha
178a0 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f  t there is no so
178b0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e  ft heap limit an
178c0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  d.** [sqlite3_re
178d0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
178e0 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c  will only be cal
178f0 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20  led when memory 
17900 69 73 20 65 78 68 61 75 73 65 64 2e 0a 2a 2a 20  is exhaused..** 
17910 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
17920 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  e for the soft h
17930 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72  eap limit is zer
17940 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  o..**.** SQLite 
17950 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66  makes a best eff
17960 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65  ort to honor the
17970 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
17980 2e 20 20 42 75 74 20 69 66 20 69 74 0a 2a 2a 20  .  But if it.** 
17990 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 72 65 64  is unable to red
179a0 75 63 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  uce memory usage
179b0 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66 74 20   below the soft 
179c0 6c 69 6d 69 74 2c 20 65 78 65 63 75 74 69 6f 6e  limit, execution
179d0 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75   will.** continu
179e0 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20  e without error 
179f0 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e  or notification.
17a00 20 20 54 68 69 73 20 69 73 20 77 68 79 20 74 68    This is why th
17a10 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a 2a 20 63  e limit is .** c
17a20 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c  alled a "soft" l
17a30 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64 76  imit.  It is adv
17a40 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  isory only..**.*
17a50 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
17a60 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
17a70 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
17a80 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
17a90 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
17aa0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
17ab0 4d 41 4e 41 47 45 4d 45 4e 54 20 6f 70 74 69 6f  MANAGEMENT optio
17ac0 6e 20 73 65 74 2e 0a 2a 2a 20 6d 65 6d 6f 72 79  n set..** memory
17ad0 2d 6d 61 6e 61 67 65 6d 65 6e 74 20 68 61 73 20  -management has 
17ae0 62 65 65 6e 20 65 6e 61 62 6c 65 64 2e 0a 2a 2f  been enabled..*/
17af0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f  .void sqlite3_so
17b00 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e  ft_heap_limit(in
17b10 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
17b20 52 45 46 3a 20 20 43 6c 65 61 6e 20 55 70 20 54  REF:  Clean Up T
17b30 68 72 65 61 64 20 4c 6f 63 61 6c 20 53 74 6f 72  hread Local Stor
17b40 61 67 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  age.**.** This r
17b50 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20 73 75 72  outine makes sur
17b60 65 20 74 68 61 74 20 61 6c 6c 20 74 68 72 65 61  e that all threa
17b70 64 2d 6c 6f 63 61 6c 20 73 74 6f 72 61 67 65 20  d-local storage 
17b80 68 61 73 20 62 65 65 6e 0a 2a 2a 20 64 65 61 6c  has been.** deal
17b90 6c 6f 63 61 74 65 64 20 66 6f 72 20 74 68 65 20  located for the 
17ba0 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 2e 0a  current thread..
17bb0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
17bc0 6e 65 20 69 73 20 6e 6f 74 20 74 65 63 68 6e 69  ne is not techni
17bd0 63 61 6c 6c 79 20 6e 65 63 65 73 73 61 72 79 2e  cally necessary.
17be0 20 20 41 6c 6c 20 74 68 72 65 61 64 2d 6c 6f 63    All thread-loc
17bf0 61 6c 20 73 74 6f 72 61 67 65 0a 2a 2a 20 77 69  al storage.** wi
17c00 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
17c10 6c 6c 79 20 64 65 61 6c 6c 6f 63 61 74 65 64 20  lly deallocated 
17c20 6f 6e 63 65 20 6d 65 6d 6f 72 79 2d 6d 61 6e 61  once memory-mana
17c30 67 65 6d 65 6e 74 20 61 6e 64 0a 2a 2a 20 73 68  gement and.** sh
17c40 61 72 65 64 2d 63 61 63 68 65 20 61 72 65 20 64  ared-cache are d
17c50 69 73 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20  isabled and the 
17c60 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
17c70 68 61 73 20 62 65 65 6e 20 73 65 74 0a 2a 2a 20  has been set.** 
17c80 74 6f 20 7a 65 72 6f 2e 20 20 54 68 69 73 20 72  to zero.  This r
17c90 6f 75 74 69 6e 65 20 69 73 20 70 72 6f 76 69 64  outine is provid
17ca0 65 64 20 61 73 20 61 20 63 6f 6e 76 65 6e 69 65  ed as a convenie
17cb0 6e 63 65 20 66 6f 72 20 75 73 65 72 73 20 77 68  nce for users wh
17cc0 6f 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 6d 61 6b  o.** want to mak
17cd0 65 20 61 62 73 6f 6c 75 74 65 6c 79 20 73 75 72  e absolutely sur
17ce0 65 20 74 68 65 79 20 68 61 76 65 20 6e 6f 74 20  e they have not 
17cf0 66 6f 72 67 6f 74 74 65 6e 20 73 6f 6d 65 74 68  forgotten someth
17d00 69 6e 67 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ing.** prior to 
17d10 6b 69 6c 6c 69 6e 67 20 6f 66 66 20 61 20 74 68  killing off a th
17d20 72 65 61 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  read..*/.void sq
17d30 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
17d40 61 6e 75 70 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  anup(void);../*.
17d50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 78  ** CAPI3REF:  Ex
17d60 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41  tract Metadata A
17d70 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66  bout A Column Of
17d80 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 54   A Table.**.** T
17d90 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
17da0 65 74 75 72 6e 73 20 6d 65 74 61 2d 64 61 74 61  eturns meta-data
17db0 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 69   about a specifi
17dc0 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70  c column of a sp
17dd0 65 63 69 66 69 63 20 64 61 74 61 62 61 73 65 0a  ecific database.
17de0 2a 2a 20 74 61 62 6c 65 20 61 63 63 65 73 73 69  ** table accessi
17df0 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 63 6f  ble using the co
17e00 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20  nnection handle 
17e10 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
17e20 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a  rst function .**
17e30 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
17e40 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69   The column is i
17e50 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
17e60 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61   second, third a
17e70 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
17e80 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74 68 69 73  ters to .** this
17e90 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73   function. The s
17ea0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17eb0 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61  is either the na
17ec0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
17ed0 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69  se.** (i.e. "mai
17ee0 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e  n", "temp" or an
17ef0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
17f00 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  se) containing t
17f10 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  he specified.** 
17f20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49  table or NULL. I
17f30 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
17f40 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20  en all attached 
17f50 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65  databases are se
17f60 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68  arched.** for th
17f70 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68  e table using th
17f80 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
17f90 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
17fa0 20 65 6e 67 69 6e 65 20 75 73 65 73 20 74 6f 20   engine uses to 
17fb0 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75  .** resolve unqu
17fc0 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65  alified table re
17fd0 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20  ferences..**.** 
17fe0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
17ff0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
18000 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
18010 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61   are the table a
18020 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e 61  nd column .** na
18030 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65  me of the desire
18040 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63  d column, respec
18050 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20  tively. Neither 
18060 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74  of these paramet
18070 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  ers .** may be N
18080 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 20  ULL..**.** Meta 
18090 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
180a0 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69  eturned by writi
180b0 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  ng to the memory
180c0 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65   locations passe
180d0 64 20 61 73 0a 2a 2a 20 74 68 65 20 35 74 68 20  d as.** the 5th 
180e0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70  and subsequent p
180f0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
18100 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20  s function. Any 
18110 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20 61 72 67  of these .** arg
18120 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 20 4e 55  uments may be NU
18130 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  LL, in which cas
18140 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
18150 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d  ing element of m
18160 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  eta .** informat
18170 69 6f 6e 20 69 73 20 6f 6d 6d 69 74 74 65 64 2e  ion is ommitted.
18180 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
18190 50 61 72 61 6d 65 74 65 72 20 20 20 20 20 4f 75  Parameter     Ou
181a0 74 70 75 74 20 54 79 70 65 20 20 20 20 20 20 44  tput Type      D
181b0 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d 2d  escription.** --
181c0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
181d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
181e0 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20 20  -.**.**   5th   
181f0 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72        const char
18200 2a 20 20 20 20 20 20 44 61 74 61 20 74 79 70 65  *      Data type
18210 0a 2a 2a 20 20 20 36 74 68 20 20 20 20 20 20 20  .**   6th       
18220 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20    const char*   
18230 20 20 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64     Name of the d
18240 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e  efault collation
18250 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20 20   sequence .**   
18260 37 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20  7th         int 
18270 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75               Tru
18280 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e if the column 
18290 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63  has a NOT NULL c
182a0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20 38  onstraint.**   8
182b0 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20  th         int  
182c0 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65              True
182d0 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   if the column i
182e0 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50 52  s part of the PR
182f0 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20 39  IMARY KEY.**   9
18300 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20  th         int  
18310 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65              True
18320 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   if the column i
18330 73 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 0a  s AUTOINCREMENT.
18340 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a  ** </pre>.**.**.
18350 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f  ** The memory po
18360 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
18370 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65  character pointe
18380 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20  rs returned for 
18390 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61 74  the .** declarat
183a0 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c  ion type and col
183b0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
183c0 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e  is valid only un
183d0 74 69 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a 2a  til the next .**
183e0 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71 6c   call to any sql
183f0 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e  ite API function
18400 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73  ..**.** If the s
18410 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 69  pecified table i
18420 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65  s actually a vie
18430 77 2c 20 74 68 65 6e 20 61 6e 20 65 72 72 6f 72  w, then an error
18440 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
18450 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69  .** If the speci
18460 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22  fied column is "
18470 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72  rowid", "oid" or
18480 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61   "_rowid_" and a
18490 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50 52  n .** INTEGER PR
184a0 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e  IMARY KEY column
184b0 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63   has been explic
184c0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74  itly declared, t
184d0 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20 0a  hen the output .
184e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  ** parameters ar
184f0 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78  e set for the ex
18500 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
18510 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65  d column. If the
18520 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c  re is no.** expl
18530 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
18540 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e  IPK column, then
18550 20 74 68 65 20 6f 75 74 70 75 74 20 70 61 72 61   the output para
18560 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61  meters are set a
18570 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  s .** follows:.*
18580 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
18590 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e    data type: "IN
185a0 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f  TEGER".**     co
185b0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
185c0 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20  : "BINARY".**   
185d0 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a    not null: 0.**
185e0 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79       primary key
185f0 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20  : 1.**     auto 
18600 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20  increment: 0.** 
18610 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  </pre>.**.** Thi
18620 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c  s function may l
18630 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  oad one or more 
18640 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74  schemas from dat
18650 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20  abase files. If 
18660 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75  an.** error occu
18670 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70  rs during this p
18680 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68  rocess, or if th
18690 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c  e requested tabl
186a0 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63  e or column.** c
186b0 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20  annot be found, 
186c0 61 6e 20 53 51 4c 49 54 45 20 65 72 72 6f 72 20  an SQLITE error 
186d0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
186e0 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
186f0 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69 6e  ssage.** left in
18700 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68 61   the database ha
18710 6e 64 6c 65 20 28 74 6f 20 62 65 20 72 65 74 72  ndle (to be retr
18720 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69  ieved using sqli
18730 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a  te3_errmsg())..*
18740 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73  *.** This API is
18750 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
18760 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
18770 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
18780 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45   the.** SQLITE_E
18790 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
187a0 41 44 41 54 41 20 70 72 65 70 72 6f 63 65 73 73  ADATA preprocess
187b0 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  or symbol define
187c0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
187d0 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d  3_table_column_m
187e0 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74  etadata(.  sqlit
187f0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
18800 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63         /* Connec
18810 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  tion handle */. 
18820 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
18830 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20  Name,        /* 
18840 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72  Database name or
18850 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74   NULL */.  const
18860 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d   char *zTableNam
18870 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20  e,     /* Table 
18880 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  name */.  const 
18890 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d  char *zColumnNam
188a0 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20  e,    /* Column 
188b0 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  name */.  char c
188c0 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70  onst **pzDataTyp
188d0 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  e,    /* OUTPUT:
188e0 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74   Declared data t
188f0 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f  ype */.  char co
18900 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c  nst **pzCollSeq,
18910 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
18920 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  Collation sequen
18930 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74  ce name */.  int
18940 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20   *pNotNull,     
18950 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
18960 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20  UT: True if NOT 
18970 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20  NULL constraint 
18980 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20  exists */.  int 
18990 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20  *pPrimaryKey,   
189a0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
189b0 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  T: True if colum
189c0 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a  n part of PK */.
189d0 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20    int *pAutoinc 
189e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
189f0 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
18a00 20 63 6f 6c 75 6d 73 20 69 73 20 61 75 74 6f 2d   colums is auto-
18a10 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a  increment */.);.
18a20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18a30 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69   Load An Extensi
18a40 6f 6e 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d 70 74  on.**.** Attempt
18a50 20 74 6f 20 6c 6f 61 64 20 61 6e 20 53 51 4c 69   to load an SQLi
18a60 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62  te extension lib
18a70 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69  rary contained i
18a80 6e 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 7a 46  n the file.** zF
18a90 69 6c 65 2e 20 20 54 68 65 20 65 6e 74 72 79 20  ile.  The entry 
18aa0 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20  point is zProc. 
18ab0 20 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30 20   zProc may be 0 
18ac0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
18ad0 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65  e.** name of the
18ae0 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 64 65 66   entry point def
18af0 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65  aults to "sqlite
18b00 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74  3_extension_init
18b10 22 2e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  "..**.** Return 
18b20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
18b30 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49  uccess and [SQLI
18b40 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d  TE_ERROR] if som
18b50 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ething goes wron
18b60 67 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 65  g..**.** If an e
18b70 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20  rror occurs and 
18b80 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20  pzErrMsg is not 
18b90 30 2c 20 74 68 65 6e 20 66 69 6c 6c 20 2a 70 7a  0, then fill *pz
18ba0 45 72 72 4d 73 67 20 77 69 74 68 20 0a 2a 2a 20  ErrMsg with .** 
18bb0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
18bc0 78 74 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e 67  xt.  The calling
18bd0 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
18be0 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72   free this memor
18bf0 79 0a 2a 2a 20 62 79 20 63 61 6c 6c 69 6e 67 20  y.** by calling 
18c00 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
18c10 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 6e 73 69 6f  ..**.** Extensio
18c20 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62  n loading must b
18c30 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  e enabled using 
18c40 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
18c50 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
18c60 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  ].** prior to ca
18c70 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 20 6f  lling this API o
18c80 72 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20  r an error will 
18c90 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a  be returned..*/.
18ca0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  int sqlite3_load
18cb0 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71  _extension(.  sq
18cc0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
18cd0 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20      /* Load the 
18ce0 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74  extension into t
18cf0 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
18d00 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  nection */.  con
18d10 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
18d20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
18d30 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79  e shared library
18d40 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65   containing exte
18d50 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  nsion */.  const
18d60 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20   char *zProc,   
18d70 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e   /* Entry point.
18d80 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a    Derived from z
18d90 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63  File if 0 */.  c
18da0 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20  har **pzErrMsg  
18db0 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f       /* Put erro
18dc0 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69  r message here i
18dd0 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f  f not 0 */.);../
18de0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
18df0 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
18e00 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  e Extension Load
18e10 69 6e 67 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20  ing.**.** So as 
18e20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75  not to open secu
18e30 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c  rity holes in ol
18e40 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  der applications
18e50 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70   that are.** unp
18e60 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20  repared to deal 
18e70 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c  with extension l
18e80 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61  oading, and as a
18e90 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c   means of disabl
18ea0 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  ing.** extension
18eb0 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65   loading while e
18ec0 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65  valuating user-e
18ed0 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20  ntered SQL, the 
18ee0 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50 49  following.** API
18ef0 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
18f00 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  turn the [sqlite
18f10 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
18f20 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e  ()] mechanism on
18f30 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20 49 74   and.** off.  It
18f40 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75   is off by defau
18f50 6c 74 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  lt.  See ticket 
18f60 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  #1863..**.** Cal
18f70 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
18f80 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 74 6f 20  ith onoff==1 to 
18f90 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c  turn extension l
18fa0 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61 6e 64  oading on.** and
18fb0 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e   call it with on
18fc0 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 20 69  off==0 to turn i
18fd0 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e  t back off again
18fe0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
18ff0 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
19000 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a  ension(sqlite3 *
19010 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  db, int onoff);.
19020 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19030 20 4d 61 6b 65 20 41 72 72 61 6e 67 65 6d 65 6e   Make Arrangemen
19040 74 73 20 54 6f 20 41 75 74 6f 6d 61 74 69 63 61  ts To Automatica
19050 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  lly Load An Exte
19060 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 52 65 67 69  nsion.**.** Regi
19070 73 74 65 72 20 61 6e 20 65 78 74 65 6e 73 69 6f  ster an extensio
19080 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68  n entry point th
19090 61 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  at is automatica
190a0 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77  lly invoked.** w
190b0 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 64 61  henever a new da
190c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
190d0 6e 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e  n is opened usin
190e0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  g.** [sqlite3_op
190f0 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  en()] or [sqlite
19100 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a  3_open16()]..**.
19110 2a 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e 20  ** This API can 
19120 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72  be invoked at pr
19130 6f 67 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e  ogram startup in
19140 20 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73 74   order to regist
19150 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
19160 65 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e  e statically lin
19170 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74  ked extensions t
19180 68 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69  hat will be avai
19190 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20  lable.** to all 
191a0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
191b0 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nections..**.** 
191c0 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73  Duplicate extens
191d0 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65  ions are detecte
191e0 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  d so calling thi
191f0 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c 74 69 70  s routine multip
19200 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
19210 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73   the same extens
19220 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  ion is harmless.
19230 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
19240 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69  ine stores a poi
19250 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 74 65  nter to the exte
19260 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61  nsion in an arra
19270 79 0a 2a 2a 20 74 68 61 74 20 69 73 20 6f 62 74  y.** that is obt
19280 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f  ained from mallo
19290 63 28 29 2e 20 20 49 66 20 79 6f 75 20 72 75 6e  c().  If you run
192a0 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 0a 2a   a memory leak.*
192b0 2a 20 63 68 65 63 6b 65 72 20 6f 6e 20 79 6f 75  * checker on you
192c0 72 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74  r program and it
192d0 20 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20   reports a leak 
192e0 62 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a  because of this.
192f0 2a 2a 20 61 72 72 61 79 2c 20 74 68 65 6e 20 69  ** array, then i
19300 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 61  nvoke [sqlite3_a
19310 75 74 6f 6d 61 74 69 63 5f 65 78 74 65 6e 73 69  utomatic_extensi
19320 6f 6e 5f 72 65 73 65 74 28 29 5d 20 70 72 69 6f  on_reset()] prio
19330 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64 6f 77 6e  r.** to shutdown
19340 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65 6d   to free the mem
19350 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 75 74 6f 6d  ory..**.** Autom
19360 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20  atic extensions 
19370 61 70 70 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c  apply across all
19380 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20   threads..**.** 
19390 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  This interface i
193a0 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  s experimental a
193b0 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f  nd is subject to
193c0 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65   change or.** re
193d0 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20  moval in future 
193e0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
193f0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
19400 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
19410 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72 79 50 6f  n(void *xEntryPo
19420 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  int);.../*.** CA
19430 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75  PI3REF: Reset Au
19440 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f  tomatic Extensio
19450 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20  n Loading.**.** 
19460 44 69 73 61 62 6c 65 20 61 6c 6c 20 70 72 65 76  Disable all prev
19470 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
19480 64 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65  d automatic exte
19490 6e 73 69 6f 6e 73 2e 20 20 54 68 69 73 0a 2a 2a  nsions.  This.**
194a0 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
194b0 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 61 6c  the effect of al
194c0 6c 20 70 72 69 6f 72 20 5b 73 71 6c 69 74 65 33  l prior [sqlite3
194d0 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78 74 65 6e  _automatic_exten
194e0 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  sion()].** calls
194f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 63 61 6c  ..**.** This cal
19500 6c 20 64 69 73 61 62 6c 65 64 20 61 75 74 6f 6d  l disabled autom
19510 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20  atic extensions 
19520 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a  in all threads..
19530 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
19540 66 61 63 65 20 69 73 20 65 78 70 65 72 69 6d 65  face is experime
19550 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a  ntal and is subj
19560 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72  ect to change or
19570 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66  .** removal in f
19580 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
19590 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69  f SQLite..*/.voi
195a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f  d sqlite3_reset_
195b0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76  auto_extension(v
195c0 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a  oid);.../*.*****
195d0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d  * EXPERIMENTAL -
195e0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
195f0 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63  ge without notic
19600 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e **************
19610 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72  .**.** The inter
19620 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74  face to the virt
19630 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
19640 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ism is currently
19650 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74   considered.** t
19660 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61  o be experimenta
19670 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  l.  The interfac
19680 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  e might change i
19690 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77  n incompatible w
196a0 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  ays..** If this 
196b0 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72  is a problem for
196c0 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65   you, do not use
196d0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61   the interface a
196e0 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a  t this time..**.
196f0 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74  ** When the virt
19700 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
19710 69 73 6d 20 73 74 61 62 6c 69 7a 65 73 2c 20 77  ism stablizes, w
19720 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74  e will declare t
19730 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  he.** interface 
19740 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69  fixed, support i
19750 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20  t indefinitely, 
19760 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20  and remove this 
19770 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a  comment..*/../*.
19780 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20 75 73  ** Structures us
19790 65 64 20 62 79 20 74 68 65 20 76 69 72 74 75 61  ed by the virtua
197a0 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63  l table interfac
197b0 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  e.*/.typedef str
197c0 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
197d0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74   sqlite3_vtab;.t
197e0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
197f0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
19800 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
19810 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72  nfo;.typedef str
19820 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
19830 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f  _cursor sqlite3_
19840 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70  vtab_cursor;.typ
19850 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
19860 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74  te3_module sqlit
19870 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a  e3_module;../*.*
19880 2a 20 41 20 6d 6f 64 75 6c 65 20 69 73 20 61 20  * A module is a 
19890 63 6c 61 73 73 20 6f 66 20 76 69 72 74 75 61 6c  class of virtual
198a0 20 74 61 62 6c 65 73 2e 20 20 45 61 63 68 20 6d   tables.  Each m
198b0 6f 64 75 6c 65 20 69 73 20 64 65 66 69 6e 65 64  odule is defined
198c0 0a 2a 2a 20 62 79 20 61 6e 20 69 6e 73 74 61 6e  .** by an instan
198d0 63 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ce of the follow
198e0 69 6e 67 20 73 74 72 75 63 74 75 72 65 2e 20 20  ing structure.  
198f0 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63  This structure c
19900 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f 73 74 6c  onsists.** mostl
19910 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72  y of methods for
19920 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a   the module..*/.
19930 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
19940 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56  odule {.  int iV
19950 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
19960 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65 33  xCreate)(sqlite3
19970 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20  *, void *pAux,. 
19980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
19990 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68  t argc, const ch
199a0 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a  ar *const*argv,.
199b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
199c0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
199d0 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20  VTab, char**);. 
199e0 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29   int (*xConnect)
199f0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20  (sqlite3*, void 
19a00 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20  *pAux,.         
19a10 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
19a20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73  const char *cons
19a30 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20  t*argv,.        
19a40 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76         sqlite3_v
19a50 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68  tab **ppVTab, ch
19a60 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ar**);.  int (*x
19a70 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74  BestIndex)(sqlit
19a80 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
19a90 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
19aa0 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  fo*);.  int (*xD
19ab0 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  isconnect)(sqlit
19ac0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
19ad0 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f  .  int (*xDestro
19ae0 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  y)(sqlite3_vtab 
19af0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
19b00 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
19b10 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
19b20 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
19b30 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20   **ppCursor);.  
19b40 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
19b50 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
19b60 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  r*);.  int (*xFi
19b70 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74  lter)(sqlite3_vt
19b80 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20  ab_cursor*, int 
19b90 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68  idxNum, const ch
19ba0 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20  ar *idxStr,.    
19bb0 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
19bc0 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61  argc, sqlite3_va
19bd0 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69  lue **argv);.  i
19be0 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69  nt (*xNext)(sqli
19bf0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
19c00 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29  );.  int (*xEof)
19c10 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
19c20 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
19c30 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33  xColumn)(sqlite3
19c40 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
19c50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
19c60 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
19c70 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76  Rowid)(sqlite3_v
19c80 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c  tab_cursor*, sql
19c90 69 74 65 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69  ite_int64 *pRowi
19ca0 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64  d);.  int (*xUpd
19cb0 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ate)(sqlite3_vta
19cc0 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  b *, int, sqlite
19cd0 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69  3_value **, sqli
19ce0 74 65 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69  te_int64 *);.  i
19cf0 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c  nt (*xBegin)(sql
19d00 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
19d10 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
19d20 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
19d30 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
19d40 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33  xCommit)(sqlite3
19d50 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
19d60 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b   int (*xRollback
19d70 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
19d80 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
19d90 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73  xFindFunction)(s
19da0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
19db0 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f  ab, int nArg, co
19dc0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
19dd0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
19de0 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a          void (**
19df0 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  pxFunc)(sqlite3_
19e00 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
19e10 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
19e20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19e30 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41        void **ppA
19e40 72 67 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54  rg);.};../*.** T
19e50 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  he sqlite3_index
19e60 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20  _info structure 
19e70 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63  and its substruc
19e80 74 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f  tures is used to
19e90 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61  .** pass informa
19ea0 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65  tion into and re
19eb0 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20  ceive the reply 
19ec0 66 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e  from the xBestIn
19ed0 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  dex.** method of
19ee0 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75   an sqlite3_modu
19ef0 6c 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20  le.  The fields 
19f00 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a  under **Inputs**
19f10 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75   are the.** inpu
19f20 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78  ts to xBestIndex
19f30 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e   and are read-on
19f40 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20  ly.  xBestIndex 
19f50 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72  inserts its.** r
19f60 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20  esults into the 
19f70 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c  **Outputs** fiel
19f80 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43  ds..**.** The aC
19f90 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
19fa0 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20  y records WHERE 
19fb0 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
19fc0 74 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ts of the.** for
19fd0 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20  m:.**.**        
19fe0 20 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a   column OP expr.
19ff0 2a 2a 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69  **.** Where OP i
1a000 73 20 3d 2c 20 3c 2c 20 3c 3d 2c 20 3e 2c 20 6f  s =, <, <=, >, o
1a010 72 20 3e 3d 2e 20 20 54 68 65 20 70 61 72 74 69  r >=.  The parti
1a020 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69  cular operator i
1a030 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
1a040 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e  Constraint[].op.
1a050 20 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74    The index of t
1a060 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f  he column is sto
1a070 72 65 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73  red in .** aCons
1a080 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e  traint[].iColumn
1a090 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  .  aConstraint[]
1a0a0 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20  .usable is TRUE 
1a0b0 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f  if the.** expr o
1a0c0 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  n the right-hand
1a0d0 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61   side can be eva
1a0e0 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73  luated (and thus
1a0f0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a   the constraint.
1a100 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e  ** is usable) an
1a110 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61  d false if it ca
1a120 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nnot..**.** The 
1a130 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61  optimizer automa
1a140 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20  tically inverts 
1a150 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72  terms of the for
1a160 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d  m "expr OP colum
1a170 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20  n".** and makes 
1a180 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61  other simplifica
1a190 74 69 6e 6f 73 20 74 6f 20 74 68 65 20 57 48 45  tinos to the WHE
1a1a0 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20  RE clause in an 
1a1b0 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65  attempt to.** ge
1a1c0 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20  t as many WHERE 
1a1d0 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74  clause terms int
1a1e0 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e  o the form shown
1a1f0 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62   above as possib
1a200 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73  le..** The aCons
1a210 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f  traint[] array o
1a220 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52  nly reports WHER
1a230 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69  E clause terms i
1a240 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a  n the correct.**
1a250 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72   form that refer
1a260 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c   to the particul
1a270 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ar virtual table
1a280 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a   being queried..
1a290 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f  **.** Informatio
1a2a0 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45  n about the ORDE
1a2b0 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73  R BY clause is s
1a2c0 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42  tored in aOrderB
1a2d0 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72  y[]..** Each ter
1a2e0 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65  m of aOrderBy re
1a2f0 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  cords a column o
1a300 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  f the ORDER BY c
1a310 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  lause..**.** The
1a320 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68   xBestIndex meth
1a330 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f  od must fill aCo
1a340 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20  nstraintUsage[] 
1a350 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  with information
1a360 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70  .** about what p
1a370 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73  arameters to pas
1a380 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49  s to xFilter.  I
1a390 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68  f argvIndex>0 th
1a3a0 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d  en.** the right-
1a3b0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65  hand side of the
1a3c0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61   corresponding a
1a3d0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20  Constraint[] is 
1a3e0 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64  evaluated.** and
1a3f0 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67   becomes the arg
1a400 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20  vIndex-th entry 
1a410 69 6e 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f  in argv.  If aCo
1a420 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e  nstraintUsage[].
1a430 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c  omit.** is true,
1a440 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72   then the constr
1a450 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20  aint is assumed 
1a460 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64  to be fully hand
1a470 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69  led by the.** vi
1a480 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20  rtual table and 
1a490 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61  is not checked a
1a4a0 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a  gain by SQLite..
1a4b0 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d  **.** The idxNum
1a4c0 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75   and idxPtr valu
1a4d0 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20  es are recorded 
1a4e0 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20  and passed into 
1a4f0 78 46 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69  xFilter..** sqli
1a500 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 75 73  te3_free() is us
1a510 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74  ed to free idxPt
1a520 72 20 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49  r if needToFreeI
1a530 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a  dxPtr is true..*
1a540 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79  *.** The orderBy
1a550 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74  Consumed means t
1a560 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20  hat output from 
1a570 78 46 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63  xFilter will occ
1a580 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72  ur in.** the cor
1a590 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61  rect order to sa
1a5a0 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20  tisfy the ORDER 
1a5b0 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61  BY clause so tha
1a5c0 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a  t no separate.**
1a5d0 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73   sorting step is
1a5e0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
1a5f0 20 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f   The estimatedCo
1a600 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65  st value is an e
1a610 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63  stimate of the c
1a620 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65  ost of doing the
1a630 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c  .** particular l
1a640 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73  ookup.  A full s
1a650 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77  can of a table w
1a660 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68  ith N entries sh
1a670 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63  ould have.** a c
1a680 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e  ost of N.  A bin
1a690 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20  ary search of a 
1a6a0 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69  table of N entri
1a6b0 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61  es should have a
1a6c0 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72  .** cost of appr
1a6d0 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29  oximately log(N)
1a6e0 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
1a6f0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b  te3_index_info {
1a700 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a  .  /* Inputs */.
1a710 20 20 63 6f 6e 73 74 20 69 6e 74 20 6e 43 6f 6e    const int nCon
1a720 73 74 72 61 69 6e 74 3b 20 20 20 20 20 2f 2a 20  straint;     /* 
1a730 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65  Number of entrie
1a740 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  s in aConstraint
1a750 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 74 72 75   */.  const stru
1a760 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
1a770 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20  _constraint {.  
1a780 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
1a790 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1a7a0 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68  Column on left-h
1a7b0 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73  and side of cons
1a7c0 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75  traint */.     u
1a7d0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b  nsigned char op;
1a7e0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73           /* Cons
1a7f0 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20  traint operator 
1a800 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
1a810 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20   char usable;   
1a820 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69    /* True if thi
1a830 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  s constraint is 
1a840 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69  usable */.     i
1a850 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20  nt iTermOffset; 
1a860 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
1a870 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42   internally - xB
1a880 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20  estIndex should 
1a890 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 63  ignore */.  } *c
1a8a0 6f 6e 73 74 20 61 43 6f 6e 73 74 72 61 69 6e 74  onst aConstraint
1a8b0 3b 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20  ;      /* Table 
1a8c0 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  of WHERE clause 
1a8d0 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20  constraints */. 
1a8e0 20 63 6f 6e 73 74 20 69 6e 74 20 6e 4f 72 64 65   const int nOrde
1a8f0 72 42 79 3b 20 20 20 20 20 20 20 20 2f 2a 20 4e  rBy;        /* N
1a900 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
1a910 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  n the ORDER BY c
1a920 6c 61 75 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  lause */.  const
1a930 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1a940 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a  index_orderby {.
1a950 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e       int iColumn
1a960 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
1a970 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20  * Column number 
1a980 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
1a990 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20   char desc;     
1a9a0 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45    /* True for DE
1a9b0 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41  SC.  False for A
1a9c0 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73  SC. */.  } *cons
1a9d0 74 20 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20  t aOrderBy;     
1a9e0 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52      /* The ORDER
1a9f0 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 0a 20   BY clause */.. 
1aa00 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20   /* Outputs */. 
1aa10 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1aa20 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74  index_constraint
1aa30 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74  _usage {.    int
1aa40 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20   argvIndex;     
1aa50 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20        /* if >0, 
1aa60 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61  constraint is pa
1aa70 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46  rt of argv to xF
1aa80 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73  ilter */.    uns
1aa90 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b  igned char omit;
1aaa0 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20        /* Do not 
1aab0 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20  code a test for 
1aac0 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
1aad0 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74 20 61 43  */.  } *const aC
1aae0 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a  onstraintUsage;.
1aaf0 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20    int idxNum;   
1ab00 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1ab10 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69  Number used to i
1ab20 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65  dentify the inde
1ab30 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78  x */.  char *idx
1ab40 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20  Str;            
1ab50 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73    /* String, pos
1ab60 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  sibly obtained f
1ab70 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
1ab80 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64  oc */.  int need
1ab90 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20  ToFreeIdxStr;   
1aba0 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74     /* Free idxSt
1abb0 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  r using sqlite3_
1abc0 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a  free() if true *
1abd0 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43  /.  int orderByC
1abe0 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f  onsumed;       /
1abf0 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74  * True if output
1ac00 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65   is already orde
1ac10 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20  red */.  double 
1ac20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20  estimatedCost;  
1ac30 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64      /* Estimated
1ac40 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74   cost of using t
1ac50 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a  his index */.};.
1ac60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1ac70 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
1ac80 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  EQ    2.#define 
1ac90 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
1aca0 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a  STRAINT_GT    4.
1acb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1acc0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
1acd0 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20  LE    8.#define 
1ace0 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
1acf0 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36  STRAINT_LT    16
1ad00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ad10 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
1ad20 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e  _GE    32.#defin
1ad30 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
1ad40 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20  ONSTRAINT_MATCH 
1ad50 36 34 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72  64../*.** This r
1ad60 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 74  outine is used t
1ad70 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77  o register a new
1ad80 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 77 69 74   module name wit
1ad90 68 20 61 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 63  h an SQLite.** c
1ada0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 4d 6f 64 75  onnection.  Modu
1adb0 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65  le names must be
1adc0 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f   registered befo
1add0 72 65 20 63 72 65 61 74 69 6e 67 20 6e 65 77 0a  re creating new.
1ade0 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ** virtual table
1adf0 73 20 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c  s on the module,
1ae00 20 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67   or before using
1ae10 20 70 72 65 65 78 69 73 74 69 6e 67 20 76 69 72   preexisting vir
1ae20 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 73 20 6f  tual.** tables o
1ae30 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f  f the module..*/
1ae40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
1ae50 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71  ate_module(.  sq
1ae60 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1ae70 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
1ae80 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
1ae90 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
1aea0 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
1aeb0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
1aec0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
1aed0 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
1aee0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
1aef0 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d  odule *,    /* M
1af00 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
1af10 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
1af20 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *               
1af30 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
1af40 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
1af50 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a  /xConnect */.);.
1af60 0a 2f 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64  ./*.** Every mod
1af70 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
1af80 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61  on uses a subcla
1af90 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ss of the follow
1afa0 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ing structure.**
1afb0 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70   to describe a p
1afc0 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e  articular instan
1afd0 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  ce of the module
1afe0 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73  .  Each subclass
1aff0 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 79 6c   will.** be tayl
1b000 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63  ored to the spec
1b010 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68  ific needs of th
1b020 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  e module impleme
1b030 6e 74 61 74 69 6f 6e 2e 20 20 20 54 68 65 0a 2a  ntation.   The.*
1b040 2a 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69  * purpose of thi
1b050 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20  s superclass is 
1b060 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69  to define certai
1b070 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72  n fields that ar
1b080 65 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20 61  e common.** to a
1b090 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ll module implem
1b0a0 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  entations..**.**
1b0b0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   Virtual tables 
1b0c0 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20  methods can set 
1b0d0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1b0e0 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a   by assigning a.
1b0f0 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  ** string obtain
1b100 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1b110 6d 70 72 69 6e 74 66 28 29 20 74 6f 20 7a 45 72  mprintf() to zEr
1b120 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f  rMsg.  The metho
1b130 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65  d should.** take
1b140 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70   care that any p
1b150 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66  rior string is f
1b160 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  reed by a call t
1b170 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1b180 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73  .** prior to ass
1b190 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72  igning a new str
1b1a0 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ing to zErrMsg. 
1b1b0 20 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72   After the error
1b1c0 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64   message.** is d
1b1d0 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74  elivered up to t
1b1e0 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63  he client applic
1b1f0 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e  ation, the strin
1b200 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  g will be automa
1b210 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64  tically.** freed
1b220 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65   by sqlite3_free
1b230 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d  () and the zErrM
1b240 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65  sg field will be
1b250 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a   zeroed.  Note.*
1b260 2a 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 6d  * that sqlite3_m
1b270 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
1b280 69 74 65 33 5f 66 72 65 65 28 29 20 61 72 65 20  ite3_free() are 
1b290 75 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 72 72  used on the zErr
1b2a0 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e  Msg field.** sin
1b2b0 63 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ce virtual table
1b2c0 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69  s are commonly i
1b2d0 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f  mplemented in lo
1b2e0 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
1b2f0 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f  s which.** do no
1b300 74 20 68 61 76 65 20 61 63 63 65 73 73 20 74 6f  t have access to
1b310 20 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 66 28   sqlite3MPrintf(
1b320 29 20 6f 72 20 73 71 6c 69 74 65 33 46 72 65 65  ) or sqlite3Free
1b330 28 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ()..*/.struct sq
1b340 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63  lite3_vtab {.  c
1b350 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
1b360 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f  ule *pModule;  /
1b370 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72  * The module for
1b380 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61   this virtual ta
1b390 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65  ble */.  int nRe
1b3a0 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  f;              
1b3b0 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
1b3c0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20   internally */. 
1b3d0 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20   char *zErrMsg; 
1b3e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b3f0 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67   /* Error messag
1b400 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  e from sqlite3_m
1b410 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a  printf() */.  /*
1b420 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
1b430 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
1b440 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
1b450 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
1b460 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 20 45 76  lds */.};../* Ev
1b470 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  ery module imple
1b480 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61  mentation uses a
1b490 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
1b4a0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63   following struc
1b4b0 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72  ture.** to descr
1b4c0 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74  ibe cursors that
1b4d0 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 20   point into the 
1b4e0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e  virtual table an
1b4f0 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f  d are used.** to
1b500 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68   loop through th
1b510 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
1b520 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72    Cursors are cr
1b530 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a  eated using the.
1b540 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  ** xOpen method 
1b550 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20  of the module.  
1b560 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c  Each module impl
1b570 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
1b580 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f  define.** the co
1b590 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f  ntent of a curso
1b5a0 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73  r structure to s
1b5b0 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64  uit its own need
1b5c0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75  s..**.** This su
1b5d0 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20  perclass exists 
1b5e0 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69  in order to defi
1b5f0 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65  ne fields of the
1b600 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20   cursor that.** 
1b610 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c  are common to al
1b620 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  l implementation
1b630 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  s..*/.struct sql
1b640 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
1b650 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61   {.  sqlite3_vta
1b660 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f  b *pVtab;      /
1b670 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
1b680 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a  of this cursor *
1b690 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74  /.  /* Virtual t
1b6a0 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
1b6b0 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61  ions will typica
1b6c0 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  lly add addition
1b6d0 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a  al fields */.};.
1b6e0 0a 2f 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65 61  ./*.** The xCrea
1b6f0 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20  te and xConnect 
1b700 6d 65 74 68 6f 64 73 20 6f 66 20 61 20 6d 6f 64  methods of a mod
1b710 75 6c 65 20 75 73 65 20 74 68 65 20 66 6f 6c 6c  ule use the foll
1b720 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74 6f 20  owing API.** to 
1b730 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d  declare the form
1b740 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e  at (the names an
1b750 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74  d datatypes of t
1b760 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a  he columns) of.*
1b770 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  * the virtual ta
1b780 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d  bles they implem
1b790 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ent..*/.int sqli
1b7a0 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
1b7b0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
1b7c0 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54 61   char *zCreateTa
1b7d0 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 56 69 72  ble);../*.** Vir
1b7e0 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20  tual tables can 
1b7f0 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74  provide alternat
1b800 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ive implementati
1b810 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ons of functions
1b820 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 78 46  .** using the xF
1b830 69 6e 64 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68  indFunction meth
1b840 6f 64 2e 20 20 42 75 74 20 67 6c 6f 62 61 6c 20  od.  But global 
1b850 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73  versions of thos
1b860 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d  e functions.** m
1b870 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64  ust exist in ord
1b880 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61  er to be overloa
1b890 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ded..**.** This 
1b8a0 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61  API makes sure a
1b8b0 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20   global version 
1b8c0 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  of a function wi
1b8d0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
1b8e0 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62  ** name and numb
1b8f0 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73  er of parameters
1b900 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20   exists.  If no 
1b910 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78  such function ex
1b920 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ists.** before t
1b930 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65  his API is calle
1b940 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f  d, a new functio
1b950 6e 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54  n is created.  T
1b960 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
1b970 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20  n.** of the new 
1b980 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20  function always 
1b990 63 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74  causes an except
1b9a0 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e  ion to be thrown
1b9b0 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77  .  So.** the new
1b9c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74   function is not
1b9d0 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69   good for anythi
1b9e0 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49  ng by itself.  I
1b9f0 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f  ts only.** purpo
1ba00 73 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c  se is to be a pl
1ba10 61 63 65 2d 68 6f 6c 64 65 72 20 66 75 6e 63 74  ace-holder funct
1ba20 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20  ion that can be 
1ba30 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79  overloaded.** by
1ba40 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e   virtual tables.
1ba50 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
1ba60 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 64  should be consid
1ba70 65 72 65 64 20 70 61 72 74 20 6f 66 20 74 68 65  ered part of the
1ba80 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
1ba90 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69  nterface,.** whi
1baa0 63 68 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74  ch is experiment
1bab0 61 6c 20 61 6e 64 20 73 75 62 6a 65 63 74 20 74  al and subject t
1bac0 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  o change..*/.int
1bad0 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61   sqlite3_overloa
1bae0 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74  d_function(sqlit
1baf0 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
1bb00 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20  *zFuncName, int 
1bb10 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  nArg);../*.** Th
1bb20 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
1bb30 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
1bb40 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e   mechanism defin
1bb50 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75  ed above (back u
1bb60 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e  p.** to a commen
1bb70 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d  t remarkably sim
1bb80 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65  ilar to this one
1bb90 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  ) is currently c
1bba0 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20  onsidered.** to 
1bbb0 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  be experimental.
1bbc0 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
1bbd0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
1bbe0 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79  incompatible way
1bbf0 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73  s..** If this is
1bc00 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79   a problem for y
1bc10 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74  ou, do not use t
1bc20 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20  he interface at 
1bc30 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  this time..**.**
1bc40 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61   When the virtua
1bc50 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
1bc60 6d 20 73 74 61 62 6c 69 7a 65 73 2c 20 77 65 20  m stablizes, we 
1bc70 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65  will declare the
1bc80 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69  .** interface fi
1bc90 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20  xed, support it 
1bca0 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e  indefinitely, an
1bcb0 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f  d remove this co
1bcc0 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a  mment..**.******
1bcd0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20   EXPERIMENTAL - 
1bce0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
1bcf0 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65  e without notice
1bd00 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a   **************.
1bd10 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
1bd20 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20  EF: A Handle To 
1bd30 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a  An Open BLOB.**.
1bd40 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
1bd50 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
1bd60 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
1bd70 20 69 73 20 75 73 65 64 20 74 6f 20 0a 2a 2a 20   is used to .** 
1bd80 72 65 70 72 65 73 65 6e 74 20 61 6e 20 62 6c 6f  represent an blo
1bd90 62 2d 68 61 6e 64 6c 65 2e 20 20 41 20 62 6c 6f  b-handle.  A blo
1bda0 62 2d 68 61 6e 64 6c 65 20 69 73 20 63 72 65 61  b-handle is crea
1bdb0 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ted by.** [sqlit
1bdc0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
1bdd0 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 79  and destroyed by
1bde0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
1bdf0 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lose()]..** The 
1be00 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
1be10 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ad()] and [sqlit
1be20 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d  e3_blob_write()]
1be30 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63   interfaces.** c
1be40 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
1be50 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c  ad or write smal
1be60 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66  l subsections of
1be70 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54 68   the blob..** Th
1be80 65 20 5b 73 71 6c 74 69 65 33 5f 62 6c 6f 62 5f  e [sqltie3_blob_
1be90 73 69 7a 65 28 29 5d 20 69 6e 74 65 72 66 61 63  size()] interfac
1bea0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69  e returns the si
1beb0 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 62 6c 6f  ze of the.** blo
1bec0 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74  b in bytes..*/.t
1bed0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
1bee0 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74  lite3_blob sqlit
1bef0 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_blob;../*.** 
1bf00 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41  CAPI3REF: Open A
1bf10 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d   BLOB For Increm
1bf20 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20  ental I/O.**.** 
1bf30 4f 70 65 6e 20 61 20 68 61 6e 64 6c 65 20 74 6f  Open a handle to
1bf40 20 74 68 65 20 62 6c 6f 62 20 6c 6f 63 61 74 65   the blob locate
1bf50 64 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 2c 20  d in row iRow,, 
1bf60 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20  column zColumn, 
1bf70 0a 2a 2a 20 74 61 62 6c 65 20 7a 54 61 62 6c 65  .** table zTable
1bf80 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62   in database zDb
1bf90 2e 20 69 2e 65 2e 20 74 68 65 20 73 61 6d 65 20  . i.e. the same 
1bfa0 62 6c 6f 62 20 74 68 61 74 20 77 6f 75 6c 64 0a  blob that would.
1bfb0 2a 2a 20 62 65 20 73 65 6c 65 63 74 65 64 20 62  ** be selected b
1bfc0 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  y:.**.** <pre>.*
1bfd0 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f  *     SELECT zCo
1bfe0 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54  lumn FROM zDb.zT
1bff0 61 62 6c 65 20 57 48 45 52 45 20 72 6f 77 69 64  able WHERE rowid
1c000 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72   = iRow;.** </pr
1c010 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e>.**.** If the 
1c020 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
1c030 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  is non-zero, the
1c040 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64 20   blob is opened 
1c050 66 6f 72 20 0a 2a 2a 20 72 65 61 64 20 61 6e 64  for .** read and
1c060 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 49   write access. I
1c070 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68  f it is zero, th
1c080 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64  e blob is opened
1c090 20 66 6f 72 20 72 65 61 64 20 0a 2a 2a 20 61 63   for read .** ac
1c0a0 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73  cess..**.** On s
1c0b0 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
1c0c0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OK] is returned 
1c0d0 61 6e 64 20 74 68 65 20 6e 65 77 20 0a 2a 2a 20  and the new .** 
1c0e0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20  [sqlite3_blob | 
1c0f0 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 20 69 73 20  blob handle] is 
1c100 77 72 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c  written to *ppBl
1c110 6f 62 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65  ob..** Otherwise
1c120 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
1c130 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 0a  s returned and .
1c140 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 77 72 69  ** any value wri
1c150 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 20  tten to *ppBlob 
1c160 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
1c170 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72  ed by the caller
1c180 2e 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  ..** This functi
1c190 6f 6e 20 73 65 74 73 20 74 68 65 20 64 61 74 61  on sets the data
1c1a0 62 61 73 65 2d 68 61 6e 64 6c 65 20 65 72 72 6f  base-handle erro
1c1b0 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
1c1c0 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65  ge.** accessible
1c1d0 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72   via [sqlite3_er
1c1e0 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71  rcode()] and [sq
1c1f0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1c200 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1c210 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c  blob_open(.  sql
1c220 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63  ite3*,.  const c
1c230 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73  har *zDb,.  cons
1c240 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a  t char *zTable,.
1c250 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43    const char *zC
1c260 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 5f  olumn,.  sqlite_
1c270 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e  int64 iRow,.  in
1c280 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74  t flags,.  sqlit
1c290 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62  e3_blob **ppBlob
1c2a0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1c2b0 52 45 46 3a 20 20 43 6c 6f 73 65 20 41 20 42 4c  REF:  Close A BL
1c2c0 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  OB Handle.**.** 
1c2d0 43 6c 6f 73 65 20 61 6e 20 6f 70 65 6e 20 5b 73  Close an open [s
1c2e0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c  qlite3_blob | bl
1c2f0 6f 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2f 0a 69  ob handle]..*/.i
1c300 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
1c310 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c  close(sqlite3_bl
1c320 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ob *);../*.** CA
1c330 50 49 33 52 45 46 3a 20 20 52 65 74 75 72 6e 20  PI3REF:  Return 
1c340 54 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f  The Size Of An O
1c350 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 52  pen BLOB.**.** R
1c360 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 69  eturn the size i
1c370 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 62  n bytes of the b
1c380 6c 6f 62 20 61 63 63 65 73 73 69 62 6c 65 20 76  lob accessible v
1c390 69 61 20 74 68 65 20 6f 70 65 6e 20 0a 2a 2a 20  ia the open .** 
1c3a0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20  [sqlite3_blob | 
1c3b0 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61 73  blob-handle] pas
1c3c0 73 65 64 20 61 73 20 61 6e 20 61 72 67 75 6d 65  sed as an argume
1c3d0 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  nt..*/.int sqlit
1c3e0 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71  e3_blob_bytes(sq
1c3f0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a  lite3_blob *);..
1c400 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c410 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20   Read Data From 
1c420 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
1c430 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ally.**.** This 
1c440 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
1c450 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 66 72   to read data fr
1c460 6f 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b  om an open .** [
1c470 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62  sqlite3_blob | b
1c480 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 69 6e 74 6f  lob-handle] into
1c490 20 61 20 63 61 6c 6c 65 72 20 73 75 70 70 6c 69   a caller suppli
1c4a0 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 6e 20  ed buffer..** n 
1c4b0 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
1c4c0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75  e copied into bu
1c4d0 66 66 65 72 0a 2a 2a 20 7a 20 66 72 6f 6d 20 74  ffer.** z from t
1c4e0 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20 73 74  he open blob, st
1c4f0 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74  arting at offset
1c500 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20   iOffset..**.** 
1c510 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49  On success, SQLI
1c520 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65  TE_OK is returne
1c530 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e  d. Otherwise, an
1c540 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
1c550 4f 52 20 7c 20 53 51 4c 69 74 65 20 65 72 72 6f  OR | SQLite erro
1c560 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  r code] or an.**
1c570 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
1c580 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65  EAD | extended e
1c590 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
1c5a0 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  turned..*/.int s
1c5b0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
1c5c0 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
1c5d0 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c   void *z, int n,
1c5e0 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a   int iOffset);..
1c5f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c600 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f   Write Data Into
1c610 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e   A BLOB Incremen
1c620 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tally.**.** This
1c630 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
1c640 64 20 74 6f 20 77 72 69 74 65 20 64 61 74 61 20  d to write data 
1c650 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a  into an open .**
1c660 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
1c670 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 66 72   blob-handle] fr
1c680 6f 6d 20 61 20 75 73 65 72 20 73 75 70 70 6c 69  om a user suppli
1c690 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 6e 20  ed buffer..** n 
1c6a0 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
1c6b0 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68  e copied from th
1c6c0 65 20 62 75 66 66 65 72 0a 2a 2a 20 70 6f 69 6e  e buffer.** poin
1c6d0 74 65 64 20 74 6f 20 62 79 20 7a 20 69 6e 74 6f  ted to by z into
1c6e0 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20   the open blob, 
1c6f0 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73  starting at offs
1c700 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a  et iOffset..**.*
1c710 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
1c720 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61  3_blob | blob-ha
1c730 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20  ndle] passed as 
1c740 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1c750 6e 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 70  nt.** was not op
1c760 65 6e 65 64 20 66 6f 72 20 77 72 69 74 69 6e 67  ened for writing
1c770 20 28 74 68 65 20 66 6c 61 67 73 20 70 61 72 61   (the flags para
1c780 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
1c790 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a  3_blob_open()].*
1c7a0 2a 2a 20 77 61 73 20 7a 65 72 6f 29 2c 20 74 68  ** was zero), th
1c7b0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
1c7c0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44  rns [SQLITE_READ
1c7d0 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ONLY]..**.** Thi
1c7e0 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f  s function may o
1c7f0 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 63  nly modify the c
1c800 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 62  ontents of the b
1c810 6c 6f 62 2c 20 69 74 20 69 73 0a 2a 2a 20 6e 6f  lob, it is.** no
1c820 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  t possible to in
1c830 63 72 65 61 73 65 20 74 68 65 20 73 69 7a 65 20  crease the size 
1c840 6f 66 20 61 20 62 6c 6f 62 20 75 73 69 6e 67 20  of a blob using 
1c850 74 68 69 73 20 41 50 49 2e 20 49 66 0a 2a 2a 20  this API. If.** 
1c860 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69  offset iOffset i
1c870 73 20 6c 65 73 73 20 74 68 61 6e 20 6e 20 62 79  s less than n by
1c880 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64  tes from the end
1c890 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 0a 2a   of the blob, .*
1c8a0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
1c8b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
1c8c0 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74   no data is writ
1c8d0 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75  ten..**.** On su
1c8e0 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b  ccess, SQLITE_OK
1c8f0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74   is returned. Ot
1c900 68 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20  herwise, an .** 
1c910 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
1c920 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64  SQLite error cod
1c930 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  e] or an.** [SQL
1c940 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
1c950 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20   extended error 
1c960 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
1c970 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
1c980 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c  3_blob_write(sql
1c990 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e  ite3_blob *, con
1c9a0 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20  st void *z, int 
1c9b0 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b  n, int iOffset);
1c9c0 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f 20 74 68 65  ../*.** Undo the
1c9d0 20 68 61 63 6b 20 74 68 61 74 20 63 6f 6e 76 65   hack that conve
1c9e0 72 74 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rts floating poi
1c9f0 6e 74 20 74 79 70 65 73 20 74 6f 20 69 6e 74 65  nt types to inte
1ca00 67 65 72 20 66 6f 72 0a 2a 2a 20 62 75 69 6c 64  ger for.** build
1ca10 73 20 6f 6e 20 70 72 6f 63 65 73 73 6f 72 73 20  s on processors 
1ca20 77 69 74 68 6f 75 74 20 66 6c 6f 61 74 69 6e 67  without floating
1ca30 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2e 0a   point support..
1ca40 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
1ca50 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50  _OMIT_FLOATING_P
1ca60 4f 49 4e 54 0a 23 20 75 6e 64 65 66 20 64 6f 75  OINT.# undef dou
1ca70 62 6c 65 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64  ble.#endif..#ifd
1ca80 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 7d  ef __cplusplus.}
1ca90 20 20 2f 2a 20 45 6e 64 20 6f 66 20 74 68 65 20    /* End of the 
1caa0 27 65 78 74 65 72 6e 20 22 43 22 27 20 62 6c 6f  'extern "C"' blo
1cab0 63 6b 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e  ck */.#endif.#en
1cac0 64 69 66 0a                                      dif.