/ Hex Artifact Content
Login

Artifact 8164526b1658a6dad472953ea91239849f913d45:


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 2e 68 2e  ) $Id: sqlite.h.
05e0: 69 6e 2c 76 20 31 2e 32 31 38 20 32 30 30 37 2f  in,v 1.218 2007/
05f0: 30 37 2f 31 39 20 31 32 3a 34 31 3a 34 30 20 64  07/19 12:41:40 d
0600: 72 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e  rh Exp $.*/.#ifn
0610: 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a  def _SQLITE3_H_.
0620: 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33  #define _SQLITE3
0630: 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74  _H_.#include <st
0640: 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e  darg.h>     /* N
0650: 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65  eeded for the de
0660: 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c  finition of va_l
0670: 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61  ist */../*.** Ma
0680: 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63  ke sure we can c
0690: 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66  all this stuff f
06a0: 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64  rom C++..*/.#ifd
06b0: 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65  ef __cplusplus.e
06c0: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64  xtern "C" {.#end
06d0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73  if../*.** Make s
06e0: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
06f0: 73 20 77 68 65 72 65 20 6e 6f 74 20 64 65 66 69  s where not defi
0700: 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76  ned by some prev
0710: 69 6f 75 73 20 68 65 61 64 65 72 0a 2a 2a 20 66  ious header.** f
0720: 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ile..*/.#ifdef S
0730: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20  QLITE_VERSION.# 
0740: 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  undef SQLITE_VER
0750: 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64  SION.#endif.#ifd
0760: 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ef SQLITE_VERSIO
0770: 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66  N_NUMBER.# undef
0780: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
0790: 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f  NUMBER.#endif../
07a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
07b0: 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72  ompile-Time Libr
07c0: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62  ary Version Numb
07d0: 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 65  ers.**.** The ve
07e0: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  rsion of the SQL
07f0: 69 74 65 20 6c 69 62 72 61 72 79 20 69 73 20 63  ite library is c
0800: 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20  ontained in the 
0810: 73 71 6c 69 74 65 33 2e 68 0a 2a 2a 20 68 65 61  sqlite3.h.** hea
0820: 64 65 72 20 66 69 6c 65 20 69 6e 20 61 20 23 64  der file in a #d
0830: 65 66 69 6e 65 20 6e 61 6d 65 64 20 53 51 4c 49  efine named SQLI
0840: 54 45 5f 56 45 52 53 49 4f 4e 2e 20 20 54 68 65  TE_VERSION.  The
0850: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
0860: 2a 2a 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65  ** macro resolve
0870: 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f  s to a string co
0880: 6e 73 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  nstant..**.** Th
0890: 65 20 66 6f 72 6d 61 74 20 6f 66 20 74 68 65 20  e format of the 
08a0: 76 65 72 73 69 6f 6e 20 73 74 72 69 6e 67 20 69  version string i
08b0: 73 20 22 58 2e 59 2e 5a 22 2c 20 77 68 65 72 65  s "X.Y.Z", where
08c0: 0a 2a 2a 20 58 20 69 73 20 74 68 65 20 6d 61 6a  .** X is the maj
08d0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
08e0: 72 2c 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f  r, Y is the mino
08f0: 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  r version number
0900: 20 61 6e 64 20 5a 0a 2a 2a 20 69 73 20 74 68 65   and Z.** is the
0910: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e   release number.
0920: 20 20 54 68 65 20 58 2e 59 2e 5a 20 6d 69 67 68    The X.Y.Z migh
0930: 74 20 62 65 20 66 6f 6c 6c 6f 77 65 64 20 62 79  t be followed by
0940: 20 22 61 6c 70 68 61 22 20 6f 72 20 22 62 65 74   "alpha" or "bet
0950: 61 22 2e 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  a"..** For examp
0960: 6c 65 20 22 33 2e 31 2e 31 62 65 74 61 22 2e 0a  le "3.1.1beta"..
0970: 2a 2a 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75  **.** The X valu
0980: 65 20 69 73 20 61 6c 77 61 79 73 20 33 20 69 6e  e is always 3 in
0990: 20 53 51 4c 69 74 65 2e 20 20 54 68 65 20 58 20   SQLite.  The X 
09a0: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67  value only chang
09b0: 65 73 20 77 68 65 6e 0a 2a 2a 20 62 61 63 6b 77  es when.** backw
09c0: 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
09d0: 74 79 20 69 73 20 62 72 6f 6b 65 6e 20 61 6e 64  ty is broken and
09e0: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65   we intend to ne
09f0: 76 65 72 20 62 72 65 61 6b 0a 2a 2a 20 62 61 63  ver break.** bac
0a00: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
0a10: 6c 69 74 79 2e 20 20 54 68 65 20 59 20 76 61 6c  lity.  The Y val
0a20: 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20  ue only changes 
0a30: 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72  when.** there ar
0a40: 65 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20  e major feature 
0a50: 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61  enhancements tha
0a60: 74 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63  t are forwards c
0a70: 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74  ompatible.** but
0a80: 20 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63   not backwards c
0a90: 6f 6d 70 61 74 69 62 6c 65 2e 20 20 54 68 65 20  ompatible.  The 
0aa0: 5a 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  Z value is incre
0ab0: 6d 65 6e 74 65 64 20 77 69 74 68 0a 2a 2a 20 65  mented with.** e
0ac0: 61 63 68 20 72 65 6c 65 61 73 65 20 62 75 74 20  ach release but 
0ad0: 72 65 73 65 74 73 20 62 61 63 6b 20 74 6f 20 30  resets back to 0
0ae0: 20 77 68 65 6e 20 59 20 69 73 20 69 6e 63 72 65   when Y is incre
0af0: 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  mented..**.** Th
0b00: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0b10: 5f 4e 55 4d 42 45 52 20 69 73 20 61 6e 20 69 6e  _NUMBER is an in
0b20: 74 65 67 65 72 20 77 69 74 68 20 74 68 65 20 76  teger with the v
0b30: 61 6c 75 65 20 0a 2a 2a 20 28 58 2a 31 30 30 30  alue .** (X*1000
0b40: 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a  000 + Y*1000 + Z
0b50: 29 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ). For example, 
0b60: 66 6f 72 20 76 65 72 73 69 6f 6e 20 22 33 2e 31  for version "3.1
0b70: 2e 31 62 65 74 61 22 2c 20 0a 2a 2a 20 53 51 4c  .1beta", .** SQL
0b80: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0b90: 45 52 20 69 73 20 73 65 74 20 74 6f 20 33 30 30  ER is set to 300
0ba0: 31 30 30 31 2e 20 54 6f 20 64 65 74 65 63 74 20  1001. To detect 
0bb0: 69 66 20 74 68 65 79 20 61 72 65 20 75 73 69 6e  if they are usin
0bc0: 67 20 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e  g .** version 3.
0bd0: 31 2e 31 20 6f 72 20 67 72 65 61 74 65 72 20 61  1.1 or greater a
0be0: 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2c 20  t compile time, 
0bf0: 70 72 6f 67 72 61 6d 73 20 6d 61 79 20 75 73 65  programs may use
0c00: 20 74 68 65 20 74 65 73 74 20 0a 2a 2a 20 28 53   the test .** (S
0c10: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0c20: 4d 42 45 52 3e 3d 33 30 30 31 30 30 31 29 2e 0a  MBER>=3001001)..
0c30: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
0c40: 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  [sqlite3_libvers
0c50: 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
0c60: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
0c70: 75 6d 62 65 72 28 29 5d 2e 0a 2a 2f 0a 23 64 65  umber()]..*/.#de
0c80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
0c90: 49 4f 4e 20 20 20 20 20 20 20 20 20 22 2d 2d 56  ION         "--V
0ca0: 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53  ERS--".#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 2d 2d 56 45 52 53 49 4f 4e 2d 4e  MBER --VERSION-N
0cd0: 55 4d 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43  UMBER--../*.** C
0ce0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
0cf0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0d00: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0d10: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
0d20: 65 74 75 72 6e 20 76 61 6c 75 65 73 20 65 71 75  eturn values equ
0d30: 69 76 61 6c 65 6e 74 20 74 6f 20 74 68 65 20 68  ivalent to the h
0d40: 65 61 64 65 72 20 63 6f 6e 73 74 61 6e 74 73 0a  eader constants.
0d50: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
0d60: 4f 4e 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ON] and [SQLITE_
0d70: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e  VERSION_NUMBER].
0d80: 20 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 74    The values ret
0d90: 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73  urned.** by this
0da0: 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
0db0: 20 6f 6e 6c 79 20 62 65 20 64 69 66 66 65 72 65   only be differe
0dc0: 6e 74 20 66 72 6f 6d 20 74 68 65 20 68 65 61 64  nt from the head
0dd0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 69 66 20  er values.** if 
0de0: 79 6f 75 20 63 6f 6d 70 69 6c 65 20 79 6f 75 72  you compile your
0df0: 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 61   program using a
0e00: 6e 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64  n sqlite3.h head
0e10: 65 72 20 66 72 6f 6d 20 61 0a 2a 2a 20 64 69 66  er from a.** dif
0e20: 66 65 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f  ferent version o
0e30: 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 74 68  f SQLite that th
0e40: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
0e50: 20 6c 69 62 72 61 72 79 20 79 6f 75 0a 2a 2a 20   library you.** 
0e60: 6c 69 6e 6b 20 61 67 61 69 6e 73 74 2e 0a 2a 2a  link against..**
0e70: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
0e80: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
0e90: 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69   constant contai
0ea0: 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 74  ns the text of t
0eb0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  he.** [SQLITE_VE
0ec0: 52 53 49 4f 4e 5d 20 73 74 72 69 6e 67 2e 20 20  RSION] string.  
0ed0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
0ee0: 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f  ersion() functio
0ef0: 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  n returns.** a p
0f00: 6f 69 6e 65 72 20 74 6f 20 74 68 65 20 73 71 6c  oiner to the sql
0f10: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
0f20: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
0f30: 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a   The function.**
0f40: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
0f50: 20 44 4c 4c 20 75 73 65 72 73 20 77 68 6f 20 63   DLL users who c
0f60: 61 6e 20 6f 6e 6c 79 20 61 63 63 65 73 73 20 66  an only access f
0f70: 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 6e 6f 74  unctions and not
0f80: 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  .** constants wi
0f90: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2f  thin the DLL..*/
0fa0: 0a 65 78 74 65 72 6e 20 63 6f 6e 73 74 20 63 68  .extern const ch
0fb0: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
0fc0: 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72  on[];.const char
0fd0: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
0fe0: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  sion(void);.int 
0ff0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1000: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
1010: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1020: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
1030: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 0a  ction Handle.**.
1040: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
1050: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
1060: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 70  represented by p
1070: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
1080: 74 61 6e 63 65 20 6f 66 20 74 68 65 0a 2a 2a 20  tance of the.** 
1090: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
10a0: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
10b0: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
10c0: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
10d0: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
10e0: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
10f0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1100: 65 6e 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73  en] interface is
1110: 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72   its constructor
1120: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
1130: 5f 63 6c 6f 73 65 5d 20 69 73 20 69 74 73 20 64  _close] is its d
1140: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
1150: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
1160: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 28   interfaces.** (
1170: 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74 65 33  such as [sqlite3
1180: 5f 70 72 65 70 61 72 65 5f 76 32 5d 2c 20 5b 73  _prepare_v2], [s
1190: 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
11a0: 6e 63 74 69 6f 6e 5d 2c 20 61 6e 64 0a 2a 2a 20  nction], and.** 
11b0: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
11c0: 6d 65 6f 75 74 5d 20 74 6f 20 6e 61 6d 65 20 62  meout] to name b
11d0: 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61  ut three) that a
11e0: 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 74 68  re methods on th
11f0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a 2f  is.** object..*/
1200: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1210: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
1220: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
1230: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
1240: 72 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 53 6f  r Types.**.** So
1250: 6d 65 20 63 6f 6d 70 69 6c 65 72 73 20 64 6f 20  me compilers do 
1260: 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65 20  not support the 
1270: 22 6c 6f 6e 67 20 6c 6f 6e 67 22 20 64 61 74 61  "long long" data
1280: 74 79 70 65 2e 20 20 53 6f 20 77 65 20 68 61 76  type.  So we hav
1290: 65 0a 2a 2a 20 74 6f 20 64 6f 20 63 6f 6d 70 69  e.** to do compi
12a0: 6c 65 72 2d 73 70 65 63 69 66 69 63 20 74 79 70  ler-specific typ
12b0: 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74  edefs for 64-bit
12c0: 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69   signed and unsi
12d0: 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a  gned integers..*
12e0: 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65  *.** Many SQLite
12f0: 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
1300: 69 6f 6e 73 20 72 65 71 75 69 72 65 20 61 20 36  ions require a 6
1310: 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 61 72  4-bit integer ar
1320: 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 6f 73  guments..** Thos
1330: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
1340: 20 64 65 63 6c 61 72 65 64 20 75 73 69 6e 67 20   declared using 
1350: 74 68 69 73 20 74 79 70 65 64 65 66 2e 0a 2a 2f  this typedef..*/
1360: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49  .#ifdef SQLITE_I
1370: 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65  NT64_TYPE.  type
1380: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
1390: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74  _TYPE sqlite_int
13a0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
13b0: 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e  signed SQLITE_IN
13c0: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
13d0: 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65  uint64;.#elif de
13e0: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20  fined(_MSC_VER) 
13f0: 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52  || defined(__BOR
1400: 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64  LANDC__).  typed
1410: 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ef __int64 sqlit
1420: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
1430: 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e  ef unsigned __in
1440: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  t64 sqlite_uint6
1450: 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64  4;.#else.  typed
1460: 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ef long long int
1470: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
1480: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
1490: 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20  d long long int 
14a0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
14b0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  endif../*.** If 
14c0: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
14d0: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
14e0: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
14f0: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
1500: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
1510: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
1520: 70 6f 69 6e 74 0a 2a 2f 0a 23 69 66 64 65 66 20  point.*/.#ifdef 
1530: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41  SQLITE_OMIT_FLOA
1540: 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66  TING_POINT.# def
1550: 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  ine double sqlit
1560: 65 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a  e_int64.#endif..
1570: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1580: 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61  Closing A Databa
1590: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
15a0: 0a 2a 2a 20 43 61 6c 6c 20 74 68 69 73 20 66 75  .** Call this fu
15b0: 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 6f  nction with a po
15c0: 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 75 63  inter to a struc
15d0: 74 75 72 65 20 74 68 61 74 20 77 61 73 20 70 72  ture that was pr
15e0: 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 74 75  eviously.** retu
15f0: 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
1600: 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 74  e3_open()] and t
1610: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
1620: 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1630: 79 0a 2a 2a 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  y.** closed..**.
1640: 2a 2a 20 41 6c 6c 20 53 51 4c 20 73 74 61 74 65  ** All SQL state
1650: 6d 65 6e 74 73 20 70 72 65 70 61 72 65 64 20 75  ments prepared u
1660: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
1670: 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a  epare_v2()] or.*
1680: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1690: 72 65 31 36 5f 76 32 28 29 5d 20 6d 75 73 74 20  re16_v2()] must 
16a0: 62 65 20 64 65 73 74 72 6f 79 65 64 20 75 73 69  be destroyed usi
16b0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
16c0: 6c 69 7a 65 28 29 5d 0a 2a 2a 20 62 65 66 6f 72  lize()].** befor
16d0: 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
16e0: 73 20 63 61 6c 6c 65 64 2e 20 4f 74 68 65 72 77  s called. Otherw
16f0: 69 73 65 2c 20 53 51 4c 49 54 45 5f 42 55 53 59  ise, SQLITE_BUSY
1700: 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
1710: 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1720: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 72 65 6d 61   connection rema
1730: 69 6e 73 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74  ins open..*/.int
1740: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73   sqlite3_close(s
1750: 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a  qlite3 *);../*.*
1760: 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61  * The type for a
1770: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1780: 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c  on..** This is l
1790: 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63  egacy and deprec
17a0: 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63  ated.  It is inc
17b0: 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  luded for histor
17c0: 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ical.** compatib
17d0: 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74  ility and is not
17e0: 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a   documented..*/.
17f0: 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71  typedef int (*sq
1800: 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28  lite3_callback)(
1810: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
1820: 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a  , char**);../*.*
1830: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d  * CAPI3REF: One-
1840: 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75  Step Query Execu
1850: 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a  tion Interface.*
1860: 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
1870: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 64  ace is used to d
1880: 6f 20 61 20 6f 6e 65 2d 74 69 6d 65 20 65 76 61  o a one-time eva
1890: 6c 75 61 74 61 74 69 6f 6e 20 6f 66 20 7a 65 72  luatation of zer
18a0: 6f 0a 2a 2a 20 6f 72 20 6d 6f 72 65 20 53 51 4c  o.** or more SQL
18b0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 55 54   statements.  UT
18c0: 46 2d 38 20 74 65 78 74 20 6f 66 20 74 68 65 20  F-8 text of the 
18d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
18e0: 6f 0a 2a 2a 20 62 65 20 65 76 61 6c 75 74 65 64  o.** be evaluted
18f0: 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
1900: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1910: 6d 65 74 65 72 2e 20 20 54 68 65 20 73 74 61 74  meter.  The stat
1920: 65 6d 65 6e 74 73 0a 2a 2a 20 61 72 65 20 70 72  ements.** are pr
1930: 65 70 61 72 65 64 20 6f 6e 65 20 62 79 20 6f 6e  epared one by on
1940: 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
1950: 5f 70 72 65 70 61 72 65 28 29 5d 2c 20 65 76 61  _prepare()], eva
1960: 6c 75 61 74 65 64 0a 2a 2a 20 75 73 69 6e 67 20  luated.** using 
1970: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1980: 2c 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65 64  , then destroyed
1990: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
19a0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a  finalize()]..**.
19b0: 2a 2a 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  ** If one or mor
19c0: 65 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61  e of the SQL sta
19d0: 74 65 6d 65 6e 74 73 20 61 72 65 20 71 75 65 72  tements are quer
19e0: 69 65 73 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ies, then.** the
19f0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1a00: 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
1a10: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
1a20: 72 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  r is.** invoked 
1a30: 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f  once for each ro
1a40: 77 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 72  w of the query r
1a50: 65 73 75 6c 74 2e 20 20 54 68 69 73 20 63 61 6c  esult.  This cal
1a60: 6c 62 61 63 6b 0a 2a 2a 20 73 68 6f 75 6c 64 20  lback.** should 
1a70: 6e 6f 72 6d 61 6c 6c 79 20 72 65 74 75 72 6e 20  normally return 
1a80: 30 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62  0.  If the callb
1a90: 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ack returns a no
1aa0: 6e 2d 7a 65 72 6f 0a 2a 2a 20 76 61 6c 75 65 20  n-zero.** value 
1ab0: 74 68 65 6e 20 74 68 65 20 71 75 65 72 79 20 69  then the query i
1ac0: 73 20 61 62 6f 72 74 65 64 2c 20 61 6c 6c 20 73  s aborted, all s
1ad0: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
1ae0: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 72 65 20  atements.** are 
1af0: 73 6b 69 70 70 65 64 20 61 6e 64 20 74 68 65 20  skipped and the 
1b00: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 66  sqlite3_exec() f
1b10: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1b20: 74 68 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  the SQLITE_ABORT
1b30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 34 74 68 20  ..**.** The 4th 
1b40: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 69  parameter to thi
1b50: 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  s interface is a
1b60: 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
1b70: 74 65 72 20 74 68 61 74 20 69 73 0a 2a 2a 20 70  ter that is.** p
1b80: 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f  assed through to
1b90: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   the callback fu
1ba0: 6e 63 74 69 6f 6e 20 61 73 20 69 74 73 20 66 69  nction as its fi
1bb0: 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
1bc0: 2a 0a 2a 2a 20 54 68 65 20 32 6e 64 20 70 61 72  *.** The 2nd par
1bd0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1be0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1bf0: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
1c00: 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74  .** columns in t
1c10: 68 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 2e  he query result.
1c20: 20 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65    The 3rd parame
1c30: 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
1c40: 61 63 6b 0a 2a 2a 20 69 73 20 61 6e 20 61 72 72  ack.** is an arr
1c50: 61 79 20 6f 66 20 73 74 72 69 6e 67 73 20 68 6f  ay of strings ho
1c60: 6c 64 69 6e 67 20 74 68 65 20 76 61 6c 75 65 73  lding the values
1c70: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
1c80: 0a 2a 2a 20 61 73 20 65 78 74 72 61 63 74 65 64  .** as extracted
1c90: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1ca0: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
1cb0: 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
1cc0: 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
1cd0: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
1ce0: 20 6f 66 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f   of strings.** o
1cf0: 62 74 61 69 6e 65 64 20 75 73 69 6e 67 20 5b 73  btained using [s
1d00: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1d10: 6d 65 28 29 5d 20 61 6e 64 20 68 6f 6c 64 69 6e  me()] and holdin
1d20: 67 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 6f  g.** the names o
1d30: 66 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 0a 2a  f each column..*
1d40: 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
1d50: 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
1d60: 65 20 4e 55 4c 4c 2c 20 65 76 65 6e 20 66 6f 72  e NULL, even for
1d70: 20 71 75 65 72 69 65 73 2e 20 20 41 20 4e 55 4c   queries.  A NUL
1d80: 4c 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  L.** callback is
1d90: 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 2e 20 20   not an error.  
1da0: 49 74 20 6a 75 73 74 20 6d 65 61 6e 73 20 74 68  It just means th
1db0: 61 74 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a  at no callback.*
1dc0: 2a 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  * will be invoke
1dd0: 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 65  d..**.** If an e
1de0: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
1df0: 65 20 70 61 72 73 69 6e 67 20 6f 72 20 65 76 61  e parsing or eva
1e00: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
1e10: 28 62 75 74 0a 2a 2a 20 6e 6f 74 20 77 68 69 6c  (but.** not whil
1e20: 65 20 65 78 65 63 75 74 69 6e 67 20 74 68 65 20  e executing the 
1e30: 63 61 6c 6c 62 61 63 6b 29 20 74 68 65 6e 20 61  callback) then a
1e40: 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
1e50: 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 69  ror.** message i
1e60: 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  s written into m
1e70: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
1e80: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
1e90: 6c 6f 63 28 29 5d 20 61 6e 64 0a 2a 2a 20 2a 65  loc()] and.** *e
1ea0: 72 72 6d 73 67 20 69 73 20 6d 61 64 65 20 74 6f  rrmsg is made to
1eb0: 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 20 6d   point to that m
1ec0: 65 73 73 61 67 65 2e 20 20 54 68 65 20 63 61 6c  essage.  The cal
1ed0: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ling function.**
1ee0: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1ef0: 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20  for freeing the 
1f00: 6d 65 6d 6f 72 79 20 74 68 61 74 20 68 6f 6c 64  memory that hold
1f10: 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
1f20: 65 73 73 61 67 65 2e 20 20 20 55 73 65 20 5b 73  essage.   Use [s
1f30: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 66  qlite3_free()] f
1f40: 6f 72 20 74 68 69 73 2e 20 20 49 66 20 65 72 72  or this.  If err
1f50: 6d 73 67 3d 3d 4e 55 4c 4c 2c 0a 2a 2a 20 74 68  msg==NULL,.** th
1f60: 65 6e 20 6e 6f 20 65 72 72 6f 72 20 6d 65 73 73  en no error mess
1f70: 61 67 65 20 69 73 20 65 76 65 72 20 77 72 69 74  age is ever writ
1f80: 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72  ten..**.** The r
1f90: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 20 69  eturn value is i
1fa0: 73 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 74  s SQLITE_OK if t
1fb0: 68 65 72 65 20 61 72 65 20 6e 6f 20 65 72 72 6f  here are no erro
1fc0: 72 73 20 61 6e 64 0a 2a 2a 20 73 6f 6d 65 20 6f  rs and.** some o
1fd0: 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 20  ther [SQLITE_OK 
1fe0: 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 20 69  | return code] i
1ff0: 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
2000: 72 6f 72 2e 20 20 0a 2a 2a 20 54 68 65 20 70 61  ror.  .** The pa
2010: 72 74 69 63 75 6c 61 72 20 72 65 74 75 72 6e 20  rticular return 
2020: 76 61 6c 75 65 20 64 65 70 65 6e 64 73 20 6f 6e  value depends on
2030: 20 74 68 65 20 74 79 70 65 20 6f 66 20 65 72 72   the type of err
2040: 6f 72 2e 20 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73  or. .**.*/.int s
2050: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
2060: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
2070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2080: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
2090: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
20a0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
20b0: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
20c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
20d0: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
20e0: 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63  ted */.  int (*c
20f0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
2100: 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a  nt,char**,char**
2110: 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  ),  /* Callback 
2120: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
2130: 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20  id *,           
2140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2150: 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20           /* 1st 
2160: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
2170: 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a  back */.  char *
2180: 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20  *errmsg         
2190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21a0: 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
21b0: 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
21c0: 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
21d0: 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64  3REF: Result Cod
21e0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
21f0: 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a 0a 2a 2a 20  SQLITE_OK.**.** 
2200: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63  Many SQLite func
2210: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20  tions return an 
2220: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63  integer result c
2230: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74  ode from the set
2240: 20 73 68 6f 77 6e 0a 2a 2a 20 61 62 6f 76 65 20   shown.** above 
2250: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
2260: 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f 72  cates success or
2270: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
2280: 54 68 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  The result codes
2290: 20 61 62 6f 76 65 20 61 72 65 20 74 68 65 20 6f   above are the o
22a0: 6e 6c 79 20 6f 6e 65 73 20 72 65 74 75 72 6e 65  nly ones returne
22b0: 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
22c0: 74 73 0a 2a 2a 20 64 65 66 61 75 6c 74 20 63 6f  ts.** default co
22d0: 6e 66 69 67 75 72 61 74 69 6f 6e 2e 20 20 48 6f  nfiguration.  Ho
22e0: 77 65 76 65 72 2c 20 74 68 65 20 5b 73 71 6c 69  wever, the [sqli
22f0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
2300: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 0a 2a 2a 20  ult_codes()].** 
2310: 41 50 49 20 63 61 6e 20 62 65 20 75 73 65 64 20  API can be used 
2320: 74 6f 20 73 65 74 20 61 20 64 61 74 61 62 61 73  to set a databas
2330: 65 20 63 6f 6e 6e 65 63 74 6f 69 6e 20 74 6f 20  e connectoin to 
2340: 72 65 74 75 72 6e 20 6d 6f 72 65 20 64 65 74 61  return more deta
2350: 69 6c 65 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63  iled.** result c
2360: 6f 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  odes..**.** See 
2370: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
2380: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
2390: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
23a0: 5d 0a 2a 2a 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ].**.*/.#define 
23b0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
23c0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
23d0: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
23e0: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
23f0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
2400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
2410: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
2420: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
2430: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
2440: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2450: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
2460: 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20     /* NOT USED. 
2470: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
2480: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
2490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24a0: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
24b0: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
24c0: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
24d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24e0: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
24f0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
2500: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
2510: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
2520: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
2530: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
2540: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
2550: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
2560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
2570: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
2580: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
2590: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
25a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
25b0: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
25c0: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
25d0: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
25e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
25f0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
2600: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
2610: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
2620: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
2630: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2640: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
2650: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
2660: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
2670: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
2680: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
2690: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
26a0: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
26b0: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
26c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
26d0: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
26e0: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
26f0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
2700: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
2710: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
2720: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
2730: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
2740: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
2750: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
2760: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
2770: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
2780: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
2790: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
27a0: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
27b0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
27c0: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
27d0: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
27e0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
27f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
2800: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
2810: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74  /* NOT USED. Dat
2820: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
2830: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
2840: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
2850: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
2860: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
2870: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
2880: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
2890: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
28a0: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
28b0: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
28c0: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
28d0: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
28e0: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
28f0: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
2900: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
2910: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
2920: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
2930: 6f 6e 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  ontraint violati
2940: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
2950: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
2960: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
2970: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
2980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
2990: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
29a0: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
29b0: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
29c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
29d0: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
29e0: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
29f0: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
2a00: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
2a10: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
2a20: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
2a30: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
2a40: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
2a50: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
2a60: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
2a70: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
2a80: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
2a90: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
2aa0: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
2ab0: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
2ac0: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
2ad0: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
2ae0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
2af0: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
2b00: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
2b10: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
2b20: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
2b30: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
2b40: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
2b50: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
2b60: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
2b70: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
2b80: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
2b90: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
2ba0: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
2bb0: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
2bc0: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
2bd0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
2be0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
2bf0: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
2c00: 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64  s.**.** In its d
2c10: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
2c20: 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49  tion, SQLite API
2c30: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2c40: 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67   one of 26 integ
2c50: 65 72 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 64  er.** result cod
2c60: 65 73 20 64 65 73 63 72 69 62 65 64 20 61 74 20  es described at 
2c70: 72 65 73 75 6c 74 2d 63 6f 64 65 73 2e 20 20 48  result-codes.  H
2c80: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
2c90: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
2ca0: 74 0a 2a 2a 20 6d 61 6e 79 20 6f 66 20 74 68 65  t.** many of the
2cb0: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
2cc0: 61 72 65 20 74 6f 6f 20 63 6f 75 72 73 65 2d 67  are too course-g
2cd0: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
2ce0: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
2cf0: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
2d00: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
2d10: 6d 73 20 61 73 20 75 73 65 72 73 20 6d 69 67 68  ms as users migh
2d20: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
2d30: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
2d40: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
2d50: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2d60: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
2d70: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
2d80: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
2d90: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
2da0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
2db0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
2dc0: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
2dd0: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
2de0: 72 73 2e 20 20 54 68 65 20 65 78 74 65 6e 64 65  rs.  The extende
2df0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
2e00: 72 65 20 65 6e 61 62 6c 65 64 20 28 6f 72 20 64  re enabled (or d
2e10: 69 73 61 62 6c 65 64 29 20 66 6f 72 20 0a 2a 2a  isabled) for .**
2e20: 20 65 61 63 68 20 64 61 74 61 62 61 73 65 0a 2a   each database.*
2e30: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69  * connection usi
2e40: 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
2e50: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
2e60: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a  codes()] API..**
2e70: 20 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65   .** Some of the
2e80: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
2e90: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2ea0: 20 61 72 65 20 6c 69 73 74 65 64 20 61 62 6f 76   are listed abov
2eb0: 65 2e 0a 2a 2a 20 57 65 20 65 78 70 65 63 74 20  e..** We expect 
2ec0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
2ed0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
2ee0: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
2ef0: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
2f00: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
2f10: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
2f20: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
2f30: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
2f40: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
2f50: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
2f60: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
2f70: 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 73 79 6d  ..** .** The sym
2f80: 62 6f 6c 69 63 20 6e 61 6d 65 20 66 6f 72 20 61  bolic name for a
2f90: 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
2fa0: 74 20 63 6f 64 65 20 61 6c 77 61 79 73 20 63 6f  t code always co
2fb0: 6e 74 61 69 6e 73 20 61 20 72 65 6c 61 74 65 64  ntains a related
2fc0: 0a 2a 2a 20 70 72 69 6d 61 72 79 20 72 65 73 75  .** primary resu
2fd0: 6c 74 20 63 6f 64 65 20 61 73 20 61 20 70 72 65  lt code as a pre
2fe0: 66 69 78 2e 20 20 50 72 69 6d 61 72 79 20 72 65  fix.  Primary re
2ff0: 73 75 6c 74 20 63 6f 64 65 73 20 63 6f 6e 74 61  sult codes conta
3000: 69 6e 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 22  in a single.** "
3010: 5f 22 20 63 68 61 72 61 63 74 65 72 2e 20 20 45  _" character.  E
3020: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
3030: 6f 64 65 73 20 63 6f 6e 74 61 69 6e 20 74 77 6f  odes contain two
3040: 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61   or more "_" cha
3050: 72 61 63 74 65 72 73 2e 0a 2a 2a 20 54 68 65 20  racters..** The 
3060: 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66  numeric value of
3070: 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73   an extended res
3080: 75 6c 74 20 63 6f 64 65 20 63 61 6e 20 62 65 20  ult code can be 
3090: 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 69 74 73  converted to its
30a0: 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
30b0: 67 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74  g primary result
30c0: 20 63 6f 64 65 20 62 79 20 6d 61 73 6b 69 6e 67   code by masking
30d0: 20 6f 66 66 20 74 68 65 20 6c 6f 77 65 72 20 38   off the lower 8
30e0: 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   bytes..**.** Th
30f0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
3100: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
3110: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
3120: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
3130: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
3140: 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ro..*/.#define S
3150: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
3160: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3170: 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29  E_IOERR | (1<<8)
3180: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3190: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
31a0: 44 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45  D    (SQLITE_IOE
31b0: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RR | (2<<8)).#de
31c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
31d0: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20  R_WRITE         
31e0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
31f0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
3200: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
3210: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
3220: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
3230: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3240: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
3250: 43 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f  C     (SQLITE_IO
3260: 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64  ERR | (5<<8)).#d
3270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3280: 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20  RR_TRUNCATE     
3290: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
32a0: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
32b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
32c0: 54 41 54 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAT         (SQL
32d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
32e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
32f0: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
3300: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
3310: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
3320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3330: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
3340: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
3350: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
3360: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
3370: 45 4c 45 54 45 20 20 20 20 20 20 20 20 28 53 51  ELETE        (SQ
3380: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30  LITE_IOERR | (10
3390: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
33a0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
33b0: 45 44 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  ED       (SQLITE
33c0: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
33d0: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
33e0: 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
33f0: 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
3400: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
3410: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e   This routine en
3420: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
3430: 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
3440: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
3450: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
3460: 64 65 73 5d 20 66 65 61 74 75 72 65 2e 0a 2a 2a  des] feature..**
3470: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 53 51 4c   By default, SQL
3480: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
3490: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 6f   return one of o
34a0: 6e 6c 79 20 32 36 20 69 6e 74 65 67 65 72 0a 2a  nly 26 integer.*
34b0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72  * [SQLITE_OK | r
34c0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 57  esult codes].  W
34d0: 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
34e0: 75 6c 74 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65  ult codes.** are
34f0: 20 65 6e 61 62 6c 65 64 20 62 79 20 74 68 69 73   enabled by this
3500: 20 72 6f 75 74 69 6e 65 2c 20 74 68 65 20 72 65   routine, the re
3510: 70 65 74 6f 69 72 65 20 6f 66 20 72 65 73 75 6c  petoire of resul
3520: 74 20 63 6f 64 65 73 20 63 61 6e 20 62 65 0a 2a  t codes can be.*
3530: 2a 20 6d 75 63 68 20 6c 61 72 67 65 72 20 61 6e  * much larger an
3540: 64 20 63 61 6e 20 28 68 6f 70 65 66 75 6c 6c 79  d can (hopefully
3550: 29 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  ) provide more d
3560: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
3570: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ion.** about the
3580: 20 63 61 75 73 65 20 6f 66 20 61 6e 20 65 72 72   cause of an err
3590: 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  or..**.** The se
35a0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
35b0: 20 61 20 62 6f 6f 6c 65 61 6e 20 76 61 6c 75 65   a boolean value
35c0: 20 74 68 61 74 20 74 75 72 6e 73 20 65 78 74 65   that turns exte
35d0: 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  nded result.** c
35e0: 6f 64 65 73 20 6f 6e 20 61 6e 64 20 6f 66 66 2e  odes on and off.
35f0: 20 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c    Extended resul
3600: 74 20 63 6f 64 65 73 20 61 72 65 20 6f 66 66 20  t codes are off 
3610: 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 0a 2a  by default for.*
3620: 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
3630: 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
3640: 6c 64 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  lder versions of
3650: 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
3660: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
3670: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
3680: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
3690: 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
36a0: 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
36b0: 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 45 61 63   Rowid.**.** Eac
36c0: 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51  h entry in an SQ
36d0: 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61  Lite table has a
36e0: 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
36f0: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 6b 65  igned integer ke
3700: 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 74 68 65 20  y.** called the 
3710: 22 72 6f 77 69 64 22 2e 20 54 68 65 20 72 6f 77  "rowid". The row
3720: 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
3730: 69 6c 61 62 6c 65 20 61 73 20 61 6e 20 75 6e 64  ilable as an und
3740: 65 63 6c 61 72 65 64 0a 2a 2a 20 63 6f 6c 75 6d  eclared.** colum
3750: 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
3760: 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 2e 20  ID, or _ROWID_. 
3770: 20 49 66 20 74 68 65 20 74 61 62 6c 65 20 68 61   If the table ha
3780: 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 0a 2a 2a  s a column of.**
3790: 20 74 79 70 65 20 49 4e 54 45 47 45 52 20 50 52   type INTEGER PR
37a0: 49 4d 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74  IMARY KEY then t
37b0: 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 61 6e  hat column is an
37c0: 6f 74 68 65 72 20 61 6e 20 61 6c 69 61 73 20 66  other an alias f
37d0: 6f 72 20 74 68 65 0a 2a 2a 20 72 6f 77 69 64 2e  or the.** rowid.
37e0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
37f0: 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
3800: 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d 6f 73  rowid of the mos
3810: 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 20  t recent INSERT 
3820: 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 64 61 74 61  into.** the data
3830: 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 64 61  base from the da
3840: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3850: 6e 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 66  n given in the f
3860: 69 72 73 74 20 0a 2a 2a 20 61 72 67 75 6d 65 6e  irst .** argumen
3870: 74 2e 20 20 49 66 20 6e 6f 20 69 6e 73 65 72 74  t.  If no insert
3880: 73 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  s have ever occu
3890: 72 72 65 64 20 6f 6e 20 74 68 69 73 20 64 61 74  rred on this dat
38a0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
38b0: 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74  ion, zero is ret
38c0: 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  urned..**.** If 
38d0: 61 6e 20 49 4e 53 45 52 54 20 6f 63 63 75 72 73  an INSERT occurs
38e0: 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
38f0: 72 2c 20 74 68 65 6e 20 74 68 65 20 72 6f 77 69  r, then the rowi
3900: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6e 73 65  d of the.** inse
3910: 72 74 65 64 20 72 6f 77 20 69 73 20 72 65 74 75  rted row is retu
3920: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  rned by this rou
3930: 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20  tine as long as 
3940: 74 68 65 20 74 72 69 67 67 65 72 0a 2a 2a 20 69  the trigger.** i
3950: 73 20 72 75 6e 6e 69 6e 67 2e 20 20 42 75 74 20  s running.  But 
3960: 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
3970: 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65   terminates, the
3980: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
3990: 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
39a0: 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 74 68  ne reverts to th
39b0: 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73  e last value ins
39c0: 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65  erted before the
39d0: 0a 2a 2a 20 74 72 69 67 67 65 72 20 66 69 72 65  .** trigger fire
39e0: 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 5f 69 6e 74  d..*/.sqlite_int
39f0: 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
3a00: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
3a10: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
3a20: 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
3a30: 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
3a40: 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
3a50: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
3a60: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
3a70: 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f  r of database ro
3a80: 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61  ws that were cha
3a90: 6e 67 65 64 0a 2a 2a 20 28 6f 72 20 69 6e 73 65  nged.** (or inse
3aa0: 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 29  rted or deleted)
3ab0: 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
3ac0: 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ent SQL statemen
3ad0: 74 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 63 68 61 6e  t.  Only.** chan
3ae0: 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
3af0: 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
3b00: 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55  by the INSERT, U
3b10: 50 44 41 54 45 2c 20 6f 72 0a 2a 2a 20 44 45 4c  PDATE, or.** DEL
3b20: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
3b30: 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69  e counted.  Auxi
3b40: 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
3b50: 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67  used by.** trigg
3b60: 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ers are not coun
3b70: 74 65 64 2e 20 20 55 73 65 20 74 68 65 20 5b 73  ted.  Use the [s
3b80: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
3b90: 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
3ba0: 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20  .** to find the 
3bb0: 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
3bc0: 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e  changes includin
3bd0: 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  g changes caused
3be0: 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a   by triggers..**
3bf0: 0a 2a 2a 20 57 69 74 68 69 6e 20 74 68 65 20 62  .** Within the b
3c00: 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72  ody of a trigger
3c10: 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  , the sqlite3_ch
3c20: 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
3c30: 65 20 63 61 6e 20 62 65 0a 2a 2a 20 63 61 6c 6c  e can be.** call
3c40: 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
3c50: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e  umber of.** chan
3c60: 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
3c70: 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
3c80: 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
3c90: 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
3ca0: 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
3cb0: 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65   the body of the
3cc0: 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   trigger..**.** 
3cd0: 41 6c 6c 20 63 68 61 6e 67 65 73 20 61 72 65 20  All changes are 
3ce0: 63 6f 75 6e 74 65 64 2c 20 65 76 65 6e 20 69 66  counted, even if
3cf0: 20 74 68 65 79 20 77 65 72 65 20 6c 61 74 65 72   they were later
3d00: 20 75 6e 64 6f 6e 65 20 62 79 20 61 0a 2a 2a 20   undone by a.** 
3d10: 52 4f 4c 4c 42 41 43 4b 20 6f 72 20 41 42 4f 52  ROLLBACK or ABOR
3d20: 54 2e 20 20 45 78 63 65 70 74 2c 20 63 68 61 6e  T.  Except, chan
3d30: 67 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  ges associated w
3d40: 69 74 68 20 63 72 65 61 74 69 6e 67 20 61 6e 64  ith creating and
3d50: 0a 2a 2a 20 64 72 6f 70 70 69 6e 67 20 74 61 62  .** dropping tab
3d60: 6c 65 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  les are not coun
3d70: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  ted..**.** If a 
3d80: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 6b 65 73  callback invokes
3d90: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3da0: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
3db0: 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
3dc0: 79 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  y,.** then the c
3dd0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 69 6e  hanges in the in
3de0: 6e 65 72 2c 20 72 65 63 75 72 73 69 76 65 20 63  ner, recursive c
3df0: 61 6c 6c 20 61 72 65 20 63 6f 75 6e 74 65 64 20  all are counted 
3e00: 74 6f 67 65 74 68 65 72 0a 2a 2a 20 77 69 74 68  together.** with
3e10: 20 74 68 65 20 63 68 61 6e 67 65 73 20 69 6e 20   the changes in 
3e20: 74 68 65 20 6f 75 74 65 72 20 63 61 6c 6c 2e 0a  the outer call..
3e30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
3e40: 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d  lements the comm
3e50: 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  and "DELETE FROM
3e60: 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20   table" without 
3e70: 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a  a WHERE clause.*
3e80: 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e  * by dropping an
3e90: 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65  d recreating the
3ea0: 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69   table.  (This i
3eb0: 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68  s much faster th
3ec0: 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f  an going.** thro
3ed0: 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67  ugh and deleting
3ee0: 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d   individual elem
3ef0: 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61  ents from the ta
3f00: 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f  ble.)  Because o
3f10: 66 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d 69  f.** this optimi
3f20: 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e  zation, the chan
3f30: 67 65 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45  ge count for "DE
3f40: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
3f50: 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f   will be.** zero
3f60: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
3f70: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65  he number of ele
3f80: 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20  ments that were 
3f90: 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68  originally in th
3fa0: 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67  e.** table. To g
3fb0: 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63  et an accurate c
3fc0: 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62  ount of the numb
3fd0: 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74  er of rows delet
3fe0: 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45  ed, use.** "DELE
3ff0: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48  TE FROM table WH
4000: 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a  ERE 1" instead..
4010: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
4020: 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
4030: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
4040: 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
4050: 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
4060: 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  .***.** This fun
4070: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
4080: 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
4090: 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 68  base rows that h
40a0: 61 76 65 20 62 65 65 6e 0a 2a 2a 20 6d 6f 64 69  ave been.** modi
40b0: 66 69 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20  fied by INSERT, 
40c0: 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
40d0: 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
40e0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68  e the database h
40f0: 61 6e 64 6c 65 0a 2a 2a 20 77 61 73 20 6f 70 65  andle.** was ope
4100: 6e 65 64 2e 20 54 68 69 73 20 69 6e 63 6c 75 64  ned. This includ
4110: 65 73 20 55 50 44 41 54 45 2c 20 49 4e 53 45 52  es UPDATE, INSER
4120: 54 20 61 6e 64 20 44 45 4c 45 54 45 20 73 74 61  T and DELETE sta
4130: 74 65 6d 65 6e 74 73 20 65 78 65 63 75 74 65 64  tements executed
4140: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 74  .** as part of t
4150: 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e  rigger programs.
4160: 20 41 6c 6c 20 63 68 61 6e 67 65 73 20 61 72 65   All changes are
4170: 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e   counted as soon
4180: 20 61 73 20 74 68 65 0a 2a 2a 20 73 74 61 74 65   as the.** state
4190: 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
41a0: 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65  them is complete
41b0: 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74  d (when the stat
41c0: 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 0a  ement handle is.
41d0: 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  ** passed to [sq
41e0: 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
41f0: 72 20 5b 73 71 6c 69 74 65 5f 66 69 6e 61 6c 69  r [sqlite_finali
4200: 73 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  se()])..**.** Se
4210: 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
4220: 74 65 33 5f 63 68 61 6e 67 65 28 29 5d 20 69 6e  te3_change()] in
4230: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 53  terface..**.** S
4240: 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
4250: 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45   the command "DE
4260: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
4270: 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45   without a WHERE
4280: 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72   clause.** by dr
4290: 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65  opping and recre
42a0: 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e  ating the table.
42b0: 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 20    (This is much 
42c0: 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e  faster than goin
42d0: 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64  g.** through and
42e0: 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69   deleting indivi
42f0: 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 6f  dual elements fo
4300: 72 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20  rm the table.)  
4310: 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68  Because of.** th
4320: 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c  is optimization,
4330: 20 74 68 65 20 63 68 61 6e 67 65 20 63 6f 75 6e   the change coun
4340: 74 20 66 6f 72 20 22 44 45 4c 45 54 45 20 46 52  t for "DELETE FR
4350: 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 62  OM table" will b
4360: 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72 64  e.** zero regard
4370: 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62  less of the numb
4380: 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74  er of elements t
4390: 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61  hat were origina
43a0: 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61  lly in the.** ta
43b0: 62 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e 20 61  ble. To get an a
43c0: 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66  ccurate count of
43d0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
43e0: 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65  ows deleted, use
43f0: 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  .** "DELETE FROM
4400: 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20   table WHERE 1" 
4410: 69 6e 73 74 65 61 64 2e 0a 2a 2f 0a 69 6e 74 20  instead..*/.int 
4420: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
4430: 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
4440: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4450: 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
4460: 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
4470: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
4480: 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
4490: 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
44a0: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
44b0: 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
44c0: 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
44d0: 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 20  t opportunity.  
44e0: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
44f0: 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
4500: 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
4510: 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
4520: 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
4530: 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
4540: 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
4550: 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
4560: 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
4570: 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
4580: 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
4590: 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20  * It is safe to 
45a0: 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
45b0: 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
45c0: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
45d0: 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
45e0: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
45f0: 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
4600: 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ase operation..*
4610: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 20 6f 70 65  *.** The SQL ope
4620: 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
4630: 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
4640: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
4650: 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66  NTERRUPT]..** If
4660: 20 61 6e 20 69 6e 74 65 72 72 75 70 74 65 64 20   an interrupted 
4670: 6f 70 65 72 61 74 69 6f 6e 20 77 61 73 20 61 6e  operation was an
4680: 20 75 70 64 61 74 65 20 74 68 61 74 20 69 73 20   update that is 
4690: 69 6e 73 69 64 65 20 61 6e 0a 2a 2a 20 65 78 70  inside an.** exp
46a0: 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
46b0: 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
46c0: 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77  re transaction w
46d0: 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 0a 2a 2a  ill be rolled.**
46e0: 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
46f0: 6c 6c 79 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  lly..*/.void sql
4700: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
4710: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
4720: 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
4730: 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
4740: 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
4750: 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lete.**.** These
4760: 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
4770: 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 67 69  n true if the gi
4780: 76 65 6e 20 69 6e 70 75 74 20 73 74 72 69 6e 67  ven input string
4790: 20 63 6f 6d 70 72 69 73 65 73 0a 2a 2a 20 6f 6e   comprises.** on
47a0: 65 20 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 6c 65  e or more comple
47b0: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
47c0: 73 2e 20 46 6f 72 20 74 68 65 20 73 71 6c 69 74  s. For the sqlit
47d0: 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 63 61  e3_complete() ca
47e0: 6c 6c 2c 0a 2a 2a 20 74 68 65 20 70 61 72 61 6d  ll,.** the param
47f0: 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 6e  eter must be a n
4800: 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ul-terminated UT
4810: 46 2d 38 20 73 74 72 69 6e 67 2e 20 46 6f 72 0a  F-8 string. For.
4820: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ** sqlite3_compl
4830: 65 74 65 31 36 28 29 2c 20 61 20 6e 75 6c 2d 74  ete16(), a nul-t
4840: 65 72 6d 69 6e 61 74 65 64 20 6d 61 63 68 69 6e  erminated machin
4850: 65 20 62 79 74 65 20 6f 72 64 65 72 20 55 54 46  e byte order UTF
4860: 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 73  -16 string.** is
4870: 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
4880: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
4890: 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
48a0: 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
48b0: 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
48c0: 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
48d0: 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
48e0: 66 6f 72 6d 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  forms one or mor
48f0: 65 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  e complete SQL s
4900: 74 61 74 65 6d 65 6e 74 73 20 6f 72 0a 2a 2a 20  tatements or.** 
4910: 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
4920: 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
4930: 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
4940: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 74 6f   statements into
4950: 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
4960: 61 72 73 69 6e 67 2e 20 54 68 65 20 61 6c 67 6f  arsing. The algo
4970: 72 69 74 68 6d 20 69 73 20 73 69 6d 70 6c 65 2e  rithm is simple.
4980: 20 20 49 66 20 74 68 65 20 0a 2a 2a 20 6c 61 73    If the .** las
4990: 74 20 74 6f 6b 65 6e 20 6f 74 68 65 72 20 74 68  t token other th
49a0: 61 6e 20 73 70 61 63 65 73 20 61 6e 64 20 63 6f  an spaces and co
49b0: 6d 6d 65 6e 74 73 20 69 73 20 61 20 73 65 6d 69  mments is a semi
49c0: 63 6f 6c 6f 6e 2c 20 74 68 65 6e 20 72 65 74 75  colon, then retu
49d0: 72 6e 20 0a 2a 2a 20 74 72 75 65 2e 20 20 41 63  rn .** true.  Ac
49e0: 74 75 61 6c 6c 79 2c 20 74 68 65 20 61 6c 67 6f  tually, the algo
49f0: 72 69 74 68 6d 20 69 73 20 61 20 6c 69 74 74 6c  rithm is a littl
4a00: 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74  e more complicat
4a10: 65 64 20 74 68 61 6e 20 74 68 61 74 0a 2a 2a 20  ed than that.** 
4a20: 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 61 6c  in order to deal
4a30: 20 77 69 74 68 20 74 72 69 67 67 65 72 73 2c 20   with triggers, 
4a40: 62 75 74 20 74 68 65 20 62 61 73 69 63 20 69 64  but the basic id
4a50: 65 61 20 69 73 20 74 68 65 20 73 61 6d 65 3a 20  ea is the same: 
4a60: 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
4a70: 74 20 69 73 20 6e 6f 74 20 63 6f 6d 70 6c 65 74  t is not complet
4a80: 65 20 75 6e 6c 65 73 73 20 69 74 20 65 6e 64 73  e unless it ends
4a90: 20 69 6e 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2e   in a semicolon.
4aa0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4ab0: 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
4ac0: 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
4ad0: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
4ae0: 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
4af0: 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
4b00: 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
4b10: 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
4b20: 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
4b30: 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  rrors.**.** This
4b40: 20 72 6f 75 74 69 6e 65 20 69 64 65 6e 74 69 66   routine identif
4b50: 69 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ies a callback f
4b60: 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67  unction that mig
4b70: 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ht be invoked.**
4b80: 20 77 68 65 6e 65 76 65 72 20 61 6e 20 61 74 74   whenever an att
4b90: 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
4ba0: 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  open a database 
4bb0: 74 61 62 6c 65 20 0a 2a 2a 20 74 68 61 74 20 61  table .** that a
4bc0: 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 6f 72  nother thread or
4bd0: 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
4be0: 6b 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62  ked..** If the b
4bf0: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
4c00: 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
4c10: 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 28 6f 72 20  TE_BUSY].** (or 
4c20: 73 6f 6d 65 74 69 6d 65 73 20 5b 53 51 4c 49 54  sometimes [SQLIT
4c30: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
4c40: 29 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ).** is returned
4c50: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
4c60: 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
4c70: 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 49 66 20 74  he lock..** If t
4c80: 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
4c90: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
4ca0: 65 6e 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 62 61  en the.** callba
4cb0: 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  ck will be invok
4cc0: 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
4cd0: 6d 65 6e 74 73 2e 20 20 54 68 65 0a 2a 2a 20 66  ments.  The.** f
4ce0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
4cf0: 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20   the handler is 
4d00: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
4d10: 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
4d20: 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
4d30: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
4d40: 69 73 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 65  is routine.  The
4d50: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
4d60: 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c   to.** the handl
4d70: 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  er is the number
4d80: 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
4d90: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
4da0: 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
4db0: 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
4dc0: 6b 69 6e 67 20 65 76 65 6e 74 2e 20 49 66 20 74  king event. If t
4dd0: 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
4de0: 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
4df0: 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
4e00: 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
4e10: 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
4e20: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
4e30: 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
4e40: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
4e50: 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
4e60: 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  urned..** If the
4e70: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
4e80: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
4e90: 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
4ea0: 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
4eb0: 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
4ec0: 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
4ed0: 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
4ee0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
4ef0: 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
4f00: 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
4f10: 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
4f20: 0a 2a 2a 20 69 74 20 77 69 6c 6c 20 62 65 20 69  .** it will be i
4f30: 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 72  nvoked when ther
4f40: 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
4f50: 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 53 51 4c 69  tion..** If SQLi
4f60: 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
4f70: 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
4f80: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6f 75  busy handler cou
4f90: 6c 64 20 72 65 73 75 6c 74 20 69 6e 0a 2a 2a 20  ld result in.** 
4fa0: 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
4fb0: 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
4fc0: 54 45 5f 42 55 53 59 5d 20 69 6e 73 74 65 61 64  TE_BUSY] instead
4fd0: 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
4fe0: 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
4ff0: 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
5000: 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
5010: 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
5020: 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
5030: 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
5040: 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
5050: 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
5060: 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
5070: 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
5080: 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
5090: 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
50a0: 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
50b0: 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
50c0: 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
50d0: 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
50e0: 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
50f0: 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
5100: 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
5110: 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
5120: 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
5130: 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
5140: 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
5150: 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
5160: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
5170: 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
5180: 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
5190: 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
51a0: 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
51b0: 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
51c0: 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
51d0: 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
51e0: 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
51f0: 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
5200: 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
5210: 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
5220: 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
5230: 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
5240: 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
5250: 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
5260: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
5270: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
5280: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
5290: 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
52a0: 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
52b0: 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 77 68 65 6e  RR_BLOCKED] when
52c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 69 6e  .** SQLite is in
52d0: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
52e0: 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
52f0: 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
5300: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
5310: 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
5320: 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
5330: 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
5340: 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
5350: 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
5360: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
5370: 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
5380: 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
5390: 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
53a0: 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
53b0: 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
53c0: 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
53d0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
53e0: 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
53f0: 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
5400: 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69 74   readers.  If it
5410: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72   is unable to pr
5420: 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20  omote the lock, 
5430: 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  then the in-memo
5440: 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c  ry.** cache will
5450: 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69   be left in an i
5460: 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74  nconsistent stat
5470: 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72  e and so the err
5480: 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72  or.** code is pr
5490: 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20  omoted from the 
54a0: 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67  relatively benig
54b0: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
54c0: 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  to.** the more s
54d0: 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f  evere [SQLITE_IO
54e0: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54  ERR_BLOCKED].  T
54f0: 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70  his error code p
5500: 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63  romotion.** forc
5510: 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  es an automatic 
5520: 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  rollback of the 
5530: 63 68 61 6e 67 65 73 2e 20 53 65 65 20 74 68 65  changes. See the
5540: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74  .** <a href="htt
5550: 70 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f  p://www.sqlite.o
5560: 72 67 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f  rg/cvstrac/wiki?
5570: 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  p=CorruptionFoll
5580: 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e  owingBusyError">
5590: 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f  .** CorruptionFo
55a0: 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
55b0: 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66  </a> wiki page f
55c0: 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20  or a discussion 
55d0: 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69  of why.** this i
55e0: 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 09  s important..**.
55f0: 0a 2a 2a 20 53 71 6c 69 74 65 20 69 73 20 72 65  .** Sqlite is re
5600: 2d 65 6e 74 72 61 6e 74 2c 20 73 6f 20 74 68 65  -entrant, so the
5610: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 61   busy handler ma
5620: 79 20 73 74 61 72 74 20 61 20 6e 65 77 20 71 75  y start a new qu
5630: 65 72 79 2e 20 0a 2a 2a 20 28 49 74 20 69 73 20  ery. .** (It is 
5640: 6e 6f 74 20 63 6c 65 61 72 20 77 68 79 20 61 6e  not clear why an
5650: 79 6f 6e 65 20 77 6f 75 6c 64 20 65 76 65 72 79  yone would every
5660: 20 77 61 6e 74 20 74 6f 20 64 6f 20 74 68 69 73   want to do this
5670: 2c 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 61  , but it.** is a
5680: 6c 6c 6f 77 65 64 2c 20 69 6e 20 74 68 65 6f 72  llowed, in theor
5690: 79 2e 29 20 20 42 75 74 20 74 68 65 20 62 75 73  y.)  But the bus
56a0: 79 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 6e 6f  y handler may no
56b0: 74 20 63 6c 6f 73 65 20 74 68 65 0a 2a 2a 20 64  t close the.** d
56c0: 61 74 61 62 61 73 65 2e 20 20 43 6c 6f 73 69 6e  atabase.  Closin
56d0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
56e0: 72 6f 6d 20 61 20 62 75 73 79 20 68 61 6e 64 6c  rom a busy handl
56f0: 65 72 20 77 69 6c 6c 20 64 65 6c 65 74 65 20 0a  er will delete .
5700: 2a 2a 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ** data structur
5710: 65 73 20 6f 75 74 20 66 72 6f 6d 20 75 6e 64 65  es out from unde
5720: 72 20 74 68 65 20 65 78 65 63 75 74 69 6e 67 20  r the executing 
5730: 71 75 65 72 79 20 61 6e 64 20 77 69 6c 6c 20 0a  query and will .
5740: 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 73 75  ** probably resu
5750: 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
5760: 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
5770: 68 65 72 20 72 75 6e 74 69 6d 65 20 65 72 72 6f  her runtime erro
5780: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63  r..**.** There c
5790: 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
57a0: 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
57b0: 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
57c0: 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  h database.** co
57d0: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 74 74 69  nnection.  Setti
57e0: 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
57f0: 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
5800: 20 70 72 65 76 69 6f 75 73 20 6f 6e 65 2e 0a 2a   previous one..*
5810: 2a 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c  * Note that call
5820: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
5830: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 77 69 6c  y_timeout()] wil
5840: 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c  l also set or cl
5850: 65 61 72 0a 2a 2a 20 74 68 65 20 62 75 73 79 20  ear.** the busy 
5860: 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20  handler..*/.int 
5870: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
5880: 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
5890: 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
58a0: 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
58b0: 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
58c0: 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
58d0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
58e0: 20 73 65 74 73 20 61 20 62 75 73 79 20 68 61 6e   sets a busy han
58f0: 64 6c 65 72 20 74 68 61 74 20 73 6c 65 65 70 73  dler that sleeps
5900: 20 66 6f 72 20 61 20 77 68 69 6c 65 20 77 68 65   for a while whe
5910: 6e 20 61 0a 2a 2a 20 74 61 62 6c 65 20 69 73 20  n a.** table is 
5920: 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e  locked.  The han
5930: 64 6c 65 72 20 77 69 6c 6c 20 73 6c 65 65 70 20  dler will sleep 
5940: 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
5950: 6e 74 69 6c 20 0a 2a 2a 20 61 74 20 6c 65 61 73  ntil .** at leas
5960: 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
5970: 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 20  nds of sleeping 
5980: 68 61 76 65 20 62 65 65 6e 20 64 6f 6e 65 2e 20  have been done. 
5990: 20 41 66 74 65 72 0a 2a 2a 20 22 6d 73 22 20 6d   After.** "ms" m
59a0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
59b0: 6c 65 65 70 69 6e 67 2c 20 74 68 65 20 68 61 6e  leeping, the han
59c0: 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
59d0: 68 69 63 68 0a 2a 2a 20 63 61 75 73 65 73 20 5b  hich.** causes [
59e0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
59f0: 74 6f 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  to return [SQLIT
5a00: 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
5a10: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
5a20: 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  ]..**.** Calling
5a30: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
5a40: 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
5a50: 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
5a60: 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
5a70: 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
5a80: 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
5a90: 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
5aa0: 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
5ab0: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
5ac0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
5ad0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
5ae0: 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
5af0: 79 20 68 61 6e 64 6c 65 72 20 77 61 73 20 64 65  y handler was de
5b00: 66 69 6e 65 64 20 20 0a 2a 2a 20 28 75 73 69 6e  fined  .** (usin
5b10: 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
5b20: 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
5b30: 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
5b40: 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
5b50: 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
5b60: 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
5b70: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
5b80: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
5b90: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
5ba0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5bb0: 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
5bc0: 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
5bd0: 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
5be0: 20 54 68 69 73 20 6e 65 78 74 20 72 6f 75 74 69   This next routi
5bf0: 6e 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ne is a convenie
5c00: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
5c10: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  nd [sqlite3_exec
5c20: 28 29 5d 2e 0a 2a 2a 20 49 6e 73 74 65 61 64 20  ()]..** Instead 
5c30: 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 61 20 75 73  of invoking a us
5c40: 65 72 2d 73 75 70 70 6c 69 65 64 20 63 61 6c 6c  er-supplied call
5c50: 62 61 63 6b 20 66 6f 72 20 65 61 63 68 20 72 6f  back for each ro
5c60: 77 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 73 75  w of the.** resu
5c70: 6c 74 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  lt, this routine
5c80: 20 72 65 6d 65 6d 62 65 72 73 20 65 61 63 68 20   remembers each 
5c90: 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
5ca0: 74 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f  t in memory.** o
5cb0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
5cc0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
5cd0: 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61 6c   then returns al
5ce0: 6c 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  l of the result 
5cf0: 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 71 75 65  after the.** que
5d00: 72 79 20 68 61 73 20 66 69 6e 69 73 68 65 64 2e  ry has finished.
5d10: 20 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78   .**.** As an ex
5d20: 61 6d 70 6c 65 2c 20 73 75 70 70 6f 73 65 20 74  ample, suppose t
5d30: 68 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  he query result 
5d40: 77 68 65 72 65 20 74 68 69 73 20 74 61 62 6c 65  where this table
5d50: 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  :.**.** <pre>.**
5d60: 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
5d70: 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
5d80: 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
5d90: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
5da0: 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
5db0: 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
5dc0: 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
5dd0: 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
5de0: 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
5df0: 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20  </pre>.**.** If 
5e00: 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  the 3rd argument
5e10: 20 77 65 72 65 20 26 61 7a 52 65 73 75 6c 74 20   were &azResult 
5e20: 74 68 65 6e 20 61 66 74 65 72 20 74 68 65 20 66  then after the f
5e30: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a  unction returns.
5e40: 2a 2a 20 61 7a 52 65 73 75 6c 74 20 77 69 6c 6c  ** azResult will
5e50: 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 66 6f 6c   contain the fol
5e60: 6c 6f 77 69 6e 67 20 64 61 74 61 3a 0a 2a 2a 0a  lowing data:.**.
5e70: 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  ** <pre>.**     
5e80: 20 20 20 61 7a 52 65 73 75 6c 74 5b 30 5d 20 3d     azResult[0] =
5e90: 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
5ea0: 20 20 20 61 7a 52 65 73 75 6c 74 5b 31 5d 20 3d     azResult[1] =
5eb0: 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
5ec0: 20 20 61 7a 52 65 73 75 6c 74 5b 32 5d 20 3d 20    azResult[2] = 
5ed0: 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
5ee0: 20 20 20 61 7a 52 65 73 75 6c 74 5b 33 5d 20 3d     azResult[3] =
5ef0: 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
5f00: 20 61 7a 52 65 73 75 6c 74 5b 34 5d 20 3d 20 22   azResult[4] = "
5f10: 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
5f20: 61 7a 52 65 73 75 6c 74 5b 35 5d 20 3d 20 22 32  azResult[5] = "2
5f30: 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
5f40: 52 65 73 75 6c 74 5b 36 5d 20 3d 20 22 43 69 6e  Result[6] = "Cin
5f50: 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
5f60: 7a 52 65 73 75 6c 74 5b 37 5d 20 3d 20 22 32 31  zResult[7] = "21
5f70: 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a  ";.** </pre>.**.
5f80: 2a 2a 20 4e 6f 74 69 63 65 20 74 68 61 74 20 74  ** Notice that t
5f90: 68 65 72 65 20 69 73 20 61 6e 20 65 78 74 72 61  here is an extra
5fa0: 20 72 6f 77 20 6f 66 20 64 61 74 61 20 63 6f 6e   row of data con
5fb0: 74 61 69 6e 69 6e 67 20 74 68 65 20 63 6f 6c 75  taining the colu
5fc0: 6d 6e 0a 2a 2a 20 68 65 61 64 65 72 73 2e 20 20  mn.** headers.  
5fd0: 42 75 74 20 74 68 65 20 2a 6e 72 6f 77 20 72 65  But the *nrow re
5fe0: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 20 73 74  turn value is st
5ff0: 69 6c 6c 20 33 2e 20 20 2a 6e 63 6f 6c 75 6d 6e  ill 3.  *ncolumn
6000: 20 69 73 0a 2a 2a 20 73 65 74 20 74 6f 20 32 2e   is.** set to 2.
6010: 20 20 49 6e 20 67 65 6e 65 72 61 6c 2c 20 74 68    In general, th
6020: 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75  e number of valu
6030: 65 73 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  es inserted into
6040: 20 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 77 69 6c   azResult.** wil
6050: 6c 20 62 65 20 28 28 2a 6e 72 6f 77 29 20 2b 20  l be ((*nrow) + 
6060: 31 29 2a 28 2a 6e 63 6f 6c 75 6d 6e 29 2e 0a 2a  1)*(*ncolumn)..*
6070: 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63  *.** After the c
6080: 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
6090: 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
60a0: 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69  ng the result, i
60b0: 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 61 73  t should .** pas
60c0: 73 20 74 68 65 20 72 65 73 75 6c 74 20 64 61 74  s the result dat
60d0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  a pointer to sql
60e0: 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
60f0: 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 0a 2a  ) in order to .*
6100: 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
6110: 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
6120: 6c 6c 6f 63 2d 65 64 2e 20 20 42 65 63 61 75 73  lloc-ed.  Becaus
6130: 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
6140: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
6150: 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 2c  lloc()] happens,
6160: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
6170: 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
6180: 72 79 20 74 6f 20 63 61 6c 6c 20 0a 2a 2a 20 5b  ry to call .** [
6190: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
61a0: 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 20  directly.  Only 
61b0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
61c0: 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
61d0: 6f 20 72 65 6c 65 61 73 65 20 0a 2a 2a 20 74 68  o release .** th
61e0: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
61f0: 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
6200: 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76  .** The return v
6210: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75  alue of this rou
6220: 74 69 6e 65 20 69 73 20 74 68 65 20 73 61 6d 65  tine is the same
6230: 20 61 73 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65   as from [sqlite
6240: 33 5f 65 78 65 63 28 29 5d 2e 0a 2a 2f 0a 69 6e  3_exec()]..*/.in
6250: 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
6260: 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ble(.  sqlite3*,
6270: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
6280: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
6290: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
62a0: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 2f 2a  r *sql,       /*
62b0: 20 53 51 4c 20 74 6f 20 62 65 20 65 78 65 63 75   SQL to be execu
62c0: 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
62d0: 2a 72 65 73 75 6c 74 70 2c 20 20 20 20 20 20 20  *resultp,       
62e0: 2f 2a 20 52 65 73 75 6c 74 20 77 72 69 74 74 65  /* Result writte
62f0: 6e 20 74 6f 20 61 20 63 68 61 72 20 2a 5b 5d 20  n to a char *[] 
6300: 20 74 68 61 74 20 74 68 69 73 20 70 6f 69 6e 74   that this point
6310: 73 20 74 6f 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e  s to */.  int *n
6320: 72 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 20  row,            
6330: 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
6340: 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
6350: 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
6360: 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  *ncolumn,       
6370: 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
6380: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
6390: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
63a0: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20   char **errmsg  
63b0: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
63c0: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
63d0: 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
63e0: 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
63f0: 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
6400: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6410: 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
6420: 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
6430: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
6440: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
6450: 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  rkalikes of the 
6460: 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
6470: 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
6480: 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
6490: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
64a0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
64b0: 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
64c0: 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
64d0: 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
64e0: 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
64f0: 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
6500: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
6510: 69 74 65 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  ite_malloc()]..*
6520: 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
6530: 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
6540: 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
6550: 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
6560: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
6570: 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f  ree()].  Both ro
6580: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
6590: 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
65a0: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
65b0: 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
65c0: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
65d0: 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
65e0: 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
65f0: 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
6600: 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   In sqlite3_snpr
6610: 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
6620: 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
6630: 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
6640: 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
6650: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
6660: 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
6670: 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
6680: 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
6690: 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
66a0: 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
66b0: 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
66c0: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
66d0: 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  er.  Note that t
66e0: 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
66f0: 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
6700: 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
6710: 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
6720: 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e  f().  This is an
6730: 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
6740: 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
6750: 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
6760: 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
6770: 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
6780: 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20  tibility.  Note 
6790: 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
67a0: 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
67b0: 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
67c0: 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
67d0: 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
67e0: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
67f0: 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
6800: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
6810: 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d   buffer.  We adm
6820: 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
6830: 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
6840: 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
6850: 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
6860: 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
6870: 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
6880: 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
6890: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
68a0: 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
68b0: 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
68c0: 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
68d0: 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73  bility..**.** As
68e0: 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
68f0: 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
6900: 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
6910: 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
6920: 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
6930: 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
6940: 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
6950: 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20  erminated.  The 
6960: 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
6970: 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
6980: 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
6990: 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
69a0: 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
69b0: 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
69c0: 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
69d0: 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
69e0: 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
69f0: 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
6a00: 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
6a10: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ers..**.** These
6a20: 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
6a30: 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
6a40: 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
6a50: 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
6a60: 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
6a70: 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
6a80: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
6a90: 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
6aa0: 61 6c 20 70 72 69 6e 74 66 20 66 6f 72 6d 61 74  al printf format
6ab0: 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
6ac0: 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
6ad0: 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
6ae0: 65 20 22 25 71 22 20 61 6e 64 20 22 25 51 22 20  e "%q" and "%Q" 
6af0: 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  options..**.** T
6b00: 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
6b10: 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
6b20: 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
6b30: 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61  s a null-termina
6b40: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
6b50: 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
6b60: 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
6b70: 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
6b80: 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
6b90: 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
6ba0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
6bb0: 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
6bc0: 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  al.  By doubling
6bd0: 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
6be0: 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
6bf0: 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
6c00: 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
6c10: 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
6c20: 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
6c30: 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
6c40: 6d 70 6c 65 2c 20 73 6f 20 73 6f 6d 65 20 73 74  mple, so some st
6c50: 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 63 6f  ring variable co
6c60: 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
6c70: 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
6c80: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
6c90: 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
6ca0: 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
6cb0: 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
6cc0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
6cd0: 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
6ce0: 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
6cf0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
6d00: 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
6d10: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
6d20: 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
6d30: 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
6d40: 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
6d50: 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
6d60: 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
6d70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
6d80: 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
6d90: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
6da0: 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
6db0: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
6dc0: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
6dd0: 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
6de0: 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
6df0: 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
6e00: 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
6e10: 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
6e20: 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
6e30: 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
6e40: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
6e50: 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
6e60: 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
6e70: 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
6e80: 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
6e90: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
6ea0: 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
6eb0: 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
6ec0: 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
6ed0: 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
6ee0: 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
6ef0: 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
6f00: 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
6f10: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
6f20: 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
6f30: 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
6f40: 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
6f50: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
6f60: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
6f70: 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
6f80: 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
6f90: 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
6fa0: 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
6fb0: 6f 75 0a 2a 2a 20 73 68 6f 75 6c 64 20 61 6c 77  ou.** should alw
6fc0: 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
6fd0: 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
6fe0: 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
6ff0: 6f 20 61 20 73 74 72 69 6e 67 20 0a 2a 2a 20 6c  o a string .** l
7000: 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  iteral..**.** Th
7010: 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
7020: 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
7030: 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
7040: 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
7050: 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
7060: 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
7070: 74 72 69 6e 67 2e 20 20 4f 72 20 69 66 20 74 68  tring.  Or if th
7080: 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
7090: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6c  he argument.** l
70a0: 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
70b0: 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
70c0: 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
70d0: 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 20 73  NULL" (without s
70e0: 69 6e 67 6c 65 0a 2a 2a 20 71 75 6f 74 65 73 29  ingle.** quotes)
70f0: 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
7100: 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c   %Q option.  So,
7110: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
7120: 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
7130: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
7140: 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
7150: 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
7160: 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
7170: 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
7180: 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
7190: 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
71a0: 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
71b0: 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
71c0: 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
71d0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
71e0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
71f0: 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
7200: 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
7210: 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
7220: 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
7230: 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
7240: 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
7250: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
7260: 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
7270: 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
7280: 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
7290: 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
72a0: 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
72b0: 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
72c0: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
72d0: 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
72e0: 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f   char*, ...);../
72f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
7300: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
7310: 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
7320: 20 53 51 4c 69 74 65 20 75 73 65 73 20 69 74 73   SQLite uses its
7330: 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   own memory allo
7340: 63 61 74 6f 72 2e 20 20 4f 6e 20 73 6f 6d 65 20  cator.  On some 
7350: 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 73 2c 20 74  installations, t
7360: 68 69 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  his.** memory al
7370: 6c 6f 63 61 74 6f 72 20 69 73 20 69 64 65 6e 74  locator is ident
7380: 69 63 61 6c 20 74 6f 20 74 68 65 20 73 74 61 6e  ical to the stan
7390: 64 61 72 64 20 6d 61 6c 6c 6f 63 28 29 2f 72 65  dard malloc()/re
73a0: 61 6c 6c 6f 63 28 29 2f 66 72 65 65 28 29 0a 2a  alloc()/free().*
73b0: 2a 20 61 6e 64 20 63 61 6e 20 62 65 20 75 73 65  * and can be use
73c0: 64 20 69 6e 74 65 72 63 68 61 6e 67 61 62 6c 65  d interchangable
73d0: 2e 20 20 4f 6e 20 6f 74 68 65 72 73 2c 20 74 68  .  On others, th
73e0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
73f0: 73 20 61 72 65 0a 2a 2a 20 64 69 66 66 65 72 65  s are.** differe
7400: 6e 74 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  nt.  For maximum
7410: 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 20 69 74   portability, it
7420: 20 69 73 20 62 65 73 74 20 6e 6f 74 20 74 6f 20   is best not to 
7430: 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
7440: 74 68 65 20 73 74 61 6e 64 61 72 64 20 6d 61 6c  the standard mal
7450: 6c 6f 63 2f 72 65 61 6c 6c 6f 63 2f 66 72 65 65  loc/realloc/free
7460: 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74 65   with the sqlite
7470: 20 76 65 72 73 69 6f 6e 73 2e 0a 2a 2f 0a 76 6f   versions..*/.vo
7480: 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
7490: 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  oc(int);.void *s
74a0: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
74b0: 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
74c0: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
74d0: 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
74e0: 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
74f0: 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
7500: 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 2a 0a  n Callbacks.***.
7510: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
7520: 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68  registers a auth
7530: 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
7540: 77 69 74 68 20 74 68 65 20 53 51 4c 69 74 65 20  with the SQLite 
7550: 6c 69 62 72 61 72 79 2e 20 20 0a 2a 2a 20 54 68  library.  .** Th
7560: 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
7570: 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
7580: 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
7590: 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
75a0: 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
75b0: 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
75c0: 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
75d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
75e0: 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
75f0: 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
7600: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
7610: 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
7620: 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
7630: 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
7640: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
7650: 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
7660: 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
7670: 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
7680: 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
7690: 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
76a0: 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
76b0: 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
76c0: 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
76d0: 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75  allowed.  The au
76e0: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
76f0: 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
7700: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 74 6f 20  rn SQLITE_OK to 
7710: 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
7720: 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
7730: 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
7740: 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
7750: 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
7760: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
7770: 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
7780: 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
7790: 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
77a0: 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
77b0: 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
77c0: 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
77d0: 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
77e0: 6f 72 2e 20 20 0a 2a 2a 0a 2a 2a 20 44 65 70 65  or.  .**.** Depe
77f0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 61 63 74  nding on the act
7800: 69 6f 6e 2c 20 74 68 65 20 5b 53 51 4c 49 54 45  ion, the [SQLITE
7810: 5f 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b 53 51  _IGNORE] and [SQ
7820: 4c 49 54 45 5f 44 45 4e 59 5d 20 72 65 74 75 72  LITE_DENY] retur
7830: 6e 0a 2a 2a 20 63 6f 64 65 73 20 6d 69 67 68 74  n.** codes might
7840: 20 6d 65 61 6e 20 73 6f 6d 65 74 68 69 6e 67 20   mean something 
7850: 64 69 66 66 65 72 65 6e 74 20 6f 72 20 74 68 65  different or the
7860: 79 20 6d 69 67 68 74 20 6d 65 61 6e 20 74 68 65  y might mean the
7870: 20 73 61 6d 65 0a 2a 2a 20 74 68 69 6e 67 2e 20   same.** thing. 
7880: 20 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 69   If the action i
7890: 73 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  s, for example, 
78a0: 74 6f 20 70 65 72 66 6f 72 6d 20 61 20 64 65 6c  to perform a del
78b0: 65 74 65 20 6f 70 65 72 74 69 6f 6e 2c 0a 2a 2a  ete opertion,.**
78c0: 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 49 47   then [SQLITE_IG
78d0: 4e 4f 52 45 5d 20 61 6e 64 20 5b 53 51 4c 49 54  NORE] and [SQLIT
78e0: 45 5f 44 45 4e 59 5d 20 62 6f 74 68 20 63 61 75  E_DENY] both cau
78f0: 73 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  se the statement
7900: 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 0a 2a 2a 20   compilation.** 
7910: 74 6f 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  to fail with an 
7920: 65 72 72 6f 72 2e 20 20 42 75 74 20 69 66 20 74  error.  But if t
7930: 68 65 20 61 63 74 69 6f 6e 20 69 73 20 74 6f 20  he action is to 
7940: 72 65 61 64 20 61 20 73 70 65 63 69 66 69 63 20  read a specific 
7950: 63 6f 6c 75 6d 6e 0a 2a 2a 20 66 72 6f 6d 20 61  column.** from a
7960: 20 73 70 65 63 69 66 69 63 20 74 61 62 6c 65 2c   specific table,
7970: 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 44 45   then [SQLITE_DE
7980: 4e 59 5d 20 77 69 6c 6c 20 63 61 75 73 65 20 74  NY] will cause t
7990: 68 65 20 65 6e 74 69 72 65 0a 2a 2a 20 73 74 61  he entire.** sta
79a0: 74 65 6d 65 6e 74 20 74 6f 20 66 61 69 6c 20 62  tement to fail b
79b0: 75 74 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ut [SQLITE_IGNOR
79c0: 45 5d 20 77 69 6c 6c 20 63 61 75 73 65 20 61 20  E] will cause a 
79d0: 4e 55 4c 4c 20 76 61 6c 75 65 20 74 6f 20 62 65  NULL value to be
79e0: 0a 2a 2a 20 72 65 61 64 20 69 6e 73 74 65 61 64  .** read instead
79f0: 20 6f 66 20 74 68 65 20 61 63 74 75 61 6c 20 63   of the actual c
7a00: 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a  olumn value..**.
7a10: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
7a20: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
7a30: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
7a40: 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  k is a copy of.*
7a50: 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  * the third para
7a60: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
7a70: 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
7a80: 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
7a90: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
7aa0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
7ab0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
7ac0: 6e 74 65 67 65 72 20 0a 2a 2a 20 5b 53 51 4c 49  nteger .** [SQLI
7ad0: 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
7ae0: 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
7af0: 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63  ifies the partic
7b00: 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 74  ular action.** t
7b10: 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
7b20: 20 20 54 68 65 20 61 76 61 69 6c 61 62 6c 65 20    The available 
7b30: 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 61 72 65  action codes are
7b40: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  .** [SQLITE_COPY
7b50: 20 7c 20 64 6f 63 75 6d 65 6e 74 65 64 20 73 65   | documented se
7b60: 70 61 72 61 74 65 6c 79 5d 2e 20 20 54 68 65 20  parately].  The 
7b70: 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
7b80: 78 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  xth.** parameter
7b90: 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
7ba0: 6b 20 61 72 65 20 73 74 72 69 6e 67 73 20 74 68  k are strings th
7bb0: 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
7bc0: 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
7bd0: 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
7be0: 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
7bf0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ed..**.** An aut
7c00: 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
7c10: 77 68 65 6e 20 70 72 65 70 61 72 69 6e 67 20 53  when preparing S
7c20: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
7c30: 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 0a  om an untrusted.
7c40: 2a 2a 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ** source, to en
7c50: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
7c60: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 64 6f 20  L statements do 
7c70: 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
7c80: 73 20 64 61 74 61 0a 2a 2a 20 74 68 61 74 20 74  s data.** that t
7c90: 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
7ca0: 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
7cb0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  hat they do not 
7cc0: 74 72 79 20 74 6f 0a 2a 2a 20 65 78 65 63 75 74  try to.** execut
7cd0: 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
7ce0: 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
7cf0: 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
7d00: 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
7d10: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
7d20: 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
7d30: 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
7d40: 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
7d50: 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
7d60: 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
7d70: 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
7d80: 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
7d90: 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
7da0: 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
7db0: 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
7dc0: 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
7dd0: 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
7de0: 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
7df0: 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
7e00: 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
7e10: 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
7e20: 4c 20 69 73 20 62 65 69 6e 67 20 70 72 65 70 61  L is being prepa
7e30: 72 65 64 20 74 68 61 74 20 64 69 73 61 6c 6c 6f  red that disallo
7e40: 77 73 20 65 76 65 72 79 74 68 69 6e 67 0a 2a 2a  ws everything.**
7e50: 20 65 78 63 65 70 74 20 53 45 4c 45 43 54 20 73   except SELECT s
7e60: 74 61 74 65 6d 65 6e 74 73 2e 20 20 0a 2a 2a 0a  tatements.  .**.
7e70: 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  ** Only a single
7e80: 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
7e90: 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
7ea0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
7eb0: 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
7ec0: 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
7ed0: 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
7ee0: 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
7ef0: 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
7f00: 73 20 63 61 6c 6c 2e 20 20 41 20 4e 55 4c 4c 20  s call.  A NULL 
7f10: 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73  authorizer means
7f20: 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69   that no authori
7f30: 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
7f40: 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
7f50: 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 74 68  The default auth
7f60: 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e 0a  orizer is NULL..
7f70: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
7f80: 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
7f90: 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
7fa0: 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 20 0a  ed only during .
7fb0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
7fc0: 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
7fd0: 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
7fe0: 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
7ff0: 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
8000: 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
8010: 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
8020: 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2f 0a 69  e3_step()]..*/.i
8030: 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
8040: 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
8050: 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
8060: 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
8070: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
8080: 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
8090: 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
80a0: 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
80b0: 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
80c0: 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
80d0: 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
80e0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
80f0: 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
8100: 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
8110: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
8120: 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
8130: 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
8140: 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
8150: 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
8160: 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
8170: 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
8180: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
8190: 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
81a0: 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
81b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
81c0: 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
81d0: 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
81e0: 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
81f0: 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
8200: 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  tion..*/.#define
8210: 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
8220: 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
8230: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
8240: 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
8250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
8260: 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
8270: 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
8280: 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
8290: 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
82a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
82b0: 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
82c0: 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
82d0: 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
82e0: 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
82f0: 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
8300: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
8310: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20  tion.** that is 
8320: 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f  invoked to autho
8330: 72 69 7a 65 72 20 63 65 72 74 61 69 6e 20 53 51  rizer certain SQ
8340: 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
8350: 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
8360: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
8370: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
8380: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
8390: 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
83a0: 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
83b0: 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
83c0: 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
83d0: 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
83e0: 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
83f0: 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
8400: 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
8410: 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
8420: 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
8430: 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
8440: 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
8450: 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 0a 2a  tion is to be .*
8460: 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
8470: 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
8480: 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
8490: 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63   authorization c
84a0: 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
84b0: 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
84c0: 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
84d0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
84e0: 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
84f0: 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
8500: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
8510: 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61  ter.  The 5th pa
8520: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
8530: 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
8540: 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
8550: 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
8560: 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
8570: 22 2c 20 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  ", .** etc.) if 
8580: 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65  applicable.  The
8590: 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
85a0: 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
85b0: 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
85c0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
85d0: 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
85e0: 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
85f0: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
8600: 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
8610: 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
8620: 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
8630: 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
8640: 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74 6f 70  tly from .** top
8650: 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
8660: 0a 2a 2f 0a 2f 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 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
8690: 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
86a0: 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
86b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
86c0: 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
86d0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
86e0: 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
86f0: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
8700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8710: 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
8720: 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
8730: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
8740: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
8750: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8760: 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
8770: 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
8780: 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
8790: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
87a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
87b0: 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
87c0: 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
87d0: 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
87e0: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
87f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
8800: 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
8810: 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
8820: 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
8830: 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
8840: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
8850: 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
8860: 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
8870: 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
8880: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
8890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
88a0: 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
88b0: 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
88c0: 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
88d0: 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
88e0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
88f0: 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
8900: 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
8910: 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
8920: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
8930: 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
8940: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8950: 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
8960: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
8970: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
8980: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
8990: 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
89a0: 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
89b0: 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
89c0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
89d0: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
89e0: 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
89f0: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
8a00: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
8a10: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
8a20: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
8a30: 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
8a40: 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
8a50: 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
8a60: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
8a70: 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
8a80: 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
8a90: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
8aa0: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
8ab0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
8ac0: 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
8ad0: 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
8ae0: 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
8af0: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
8b00: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
8b10: 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
8b20: 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
8b30: 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
8b40: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
8b50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8b60: 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
8b70: 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
8b80: 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
8b90: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
8ba0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8bb0: 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
8bc0: 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
8bd0: 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
8be0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
8bf0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8c00: 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
8c10: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
8c20: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
8c30: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
8c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8c50: 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
8c60: 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
8c70: 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
8c80: 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
8c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
8ca0: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
8cb0: 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
8cc0: 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
8cd0: 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
8ce0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
8cf0: 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
8d00: 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
8d10: 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
8d20: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
8d30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
8d40: 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
8d50: 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    22   /* NULL  
8d60: 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
8d70: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
8d80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
8d90: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
8da0: 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
8db0: 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
8dc0: 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
8dd0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
8de0: 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
8df0: 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
8e00: 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
8e10: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
8e20: 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
8e30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
8e40: 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
8e50: 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
8e60: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
8e70: 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
8e80: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
8e90: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
8ea0: 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
8eb0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
8ec0: 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
8ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
8ee0: 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
8ef0: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
8f00: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
8f10: 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
8f20: 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
8f30: 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
8f40: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
8f50: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
8f60: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
8f70: 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
8f80: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
8f90: 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
8fa0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
8fb0: 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
8fc0: 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
8fd0: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
8fe0: 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
8ff0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
9000: 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
9010: 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
9020: 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
9030: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
9040: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
9050: 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
9060: 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
9070: 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
9080: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
9090: 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
90a0: 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
90b0: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
90c0: 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
90d0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
90e0: 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
90f0: 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
9100: 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
9110: 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
9120: 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
9130: 73 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  s..** The callba
9140: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
9150: 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
9160: 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
9170: 6f 6b 65 64 0a 2a 2a 20 61 74 20 74 68 65 20 66  oked.** at the f
9180: 69 72 73 74 20 5b 73 71 6c 69 74 65 33 5f 73 74  irst [sqlite3_st
9190: 65 70 28 29 5d 20 66 6f 72 20 74 68 65 20 65 76  ep()] for the ev
91a0: 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 20 53  aluation of an S
91b0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
91c0: 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
91d0: 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
91e0: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
91f0: 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
9200: 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
9210: 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
9220: 68 65 73 20 61 6e 64 20 69 6e 63 6c 75 64 65 73  hes and includes
9230: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
9240: 6f 6e 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  on how long that
9250: 20 73 74 61 74 65 6d 65 6e 74 20 72 61 6e 2e 0a   statement ran..
9260: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
9270: 33 5f 70 72 6f 66 69 6c 65 28 29 20 41 50 49 20  3_profile() API 
9280: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
9290: 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
92a0: 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73  ntal and.** is s
92b0: 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
92c0: 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
92d0: 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
92e0: 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
92f0: 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
9300: 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69  r*), void*);.voi
9310: 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
9320: 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
9330: 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
9340: 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
9350: 2a 2c 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 29  *,sqlite_uint64)
9360: 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
9370: 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
9380: 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
9390: 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  cks.**.** This r
93a0: 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65  outine configure
93b0: 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
93c0: 63 74 69 6f 6e 20 2d 20 74 68 65 20 70 72 6f 67  ction - the prog
93d0: 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20  ress callback - 
93e0: 74 68 61 74 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  that.** is invok
93f0: 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
9400: 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
9410: 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ing calls to [sq
9420: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 0a 2a  lite3_exec()],.*
9430: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
9440: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
9450: 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41  get_table()].  A
9460: 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
9470: 72 20 74 68 69 73 20 0a 2a 2a 20 69 6e 74 65 72  r this .** inter
9480: 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
9490: 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
94a0: 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
94b0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ry..**.** The pr
94c0: 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
94d0: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20  is invoked once 
94e0: 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69 72 74  for every N virt
94f0: 75 61 6c 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f  ual machine opco
9500: 64 65 73 2c 0a 2a 2a 20 77 68 65 72 65 20 4e 20  des,.** where N 
9510: 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
9520: 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66  gument to this f
9530: 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 70 72 6f  unction. The pro
9540: 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a  gress callback.*
9550: 2a 20 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e  * itself is iden
9560: 74 69 66 69 65 64 20 62 79 20 74 68 65 20 74 68  tified by the th
9570: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
9580: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54  this function. T
9590: 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 61 72 67  he fourth.** arg
95a0: 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75  ument to this fu
95b0: 6e 63 74 69 6f 6e 20 69 73 20 61 20 76 6f 69 64  nction is a void
95c0: 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
95d0: 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  to the progress 
95e0: 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
95f0: 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20 69  tion each time i
9600: 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  t is invoked..**
9610: 0a 2a 2a 20 49 66 20 61 20 63 61 6c 6c 20 74 6f  .** If a call to
9620: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
9630: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
9640: 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
9650: 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a  _get_table()].**
9660: 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65   results in fewe
9670: 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73  r than N opcodes
9680: 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c   being executed,
9690: 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65   then the progre
96a0: 73 73 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ss .** callback 
96b0: 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64  is never invoked
96c0: 2e 0a 2a 2a 20 0a 2a 2a 20 4f 6e 6c 79 20 61 20  ..** .** Only a 
96d0: 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
96e0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
96f0: 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
9700: 72 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  red for each.** 
9710: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  open database co
9720: 6e 6e 65 63 74 69 6f 6e 2e 20 20 45 76 65 72 79  nnection.  Every
9730: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
9740: 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
9750: 72 28 29 0a 2a 2a 20 6f 76 65 72 77 72 69 74 65  r().** overwrite
9760: 73 20 74 68 65 20 72 65 73 75 6c 74 73 20 6f 66  s the results of
9770: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
9780: 6c 6c 2e 0a 2a 2a 20 54 6f 20 72 65 6d 6f 76 65  ll..** To remove
9790: 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
97a0: 6c 6c 62 61 63 6b 20 61 6c 74 6f 67 65 74 68 65  llback altogethe
97b0: 72 2c 20 70 61 73 73 20 4e 55 4c 4c 20 61 73 20  r, pass NULL as 
97c0: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
97d0: 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75  ument to this fu
97e0: 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  nction..**.** If
97f0: 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
9800: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
9810: 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68   result other th
9820: 61 6e 20 30 2c 20 74 68 65 6e 20 74 68 65 20 63  an 0, then the c
9830: 75 72 72 65 6e 74 20 0a 2a 2a 20 71 75 65 72 79  urrent .** query
9840: 20 69 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20   is immediately 
9850: 74 65 72 6d 69 6e 61 74 65 64 20 61 6e 64 20 61  terminated and a
9860: 6e 79 20 64 61 74 61 62 61 73 65 20 63 68 61 6e  ny database chan
9870: 67 65 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  ges rolled back.
9880: 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 61 69 6e 69  .** The containi
9890: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
98a0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
98b0: 65 70 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  ep()], or.** [sq
98c0: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
98d0: 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 20  )] call returns 
98e0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
98f0: 2e 20 20 20 54 68 69 73 20 66 65 61 74 75 72 65  .   This feature
9900: 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c  .** can be used,
9910: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
9920: 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 22   implement the "
9930: 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
9940: 6e 20 61 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20  n a.** progress 
9950: 64 69 61 6c 6f 67 20 62 6f 78 20 69 6e 20 61 20  dialog box in a 
9960: 47 55 49 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  GUI..*/.void sql
9970: 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
9980: 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
9990: 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
99a0: 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
99b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
99c0: 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
99d0: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
99e0: 2a 0a 2a 2a 20 4f 70 65 6e 20 74 68 65 20 73 71  *.** Open the sq
99f0: 6c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  lite database fi
9a00: 6c 65 20 22 66 69 6c 65 6e 61 6d 65 22 2e 20 20  le "filename".  
9a10: 54 68 65 20 22 66 69 6c 65 6e 61 6d 65 22 20 69  The "filename" i
9a20: 73 20 55 54 46 2d 38 0a 2a 2a 20 65 6e 63 6f 64  s UTF-8.** encod
9a30: 65 64 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ed for sqlite3_o
9a40: 70 65 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36  pen() and UTF-16
9a50: 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20   encoded in the 
9a60: 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
9a70: 72 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  r.** for sqlite3
9a80: 5f 6f 70 65 6e 31 36 28 29 2e 20 20 41 6e 20 5b  _open16().  An [
9a90: 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65  sqlite3*] handle
9aa0: 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20   is returned in 
9ab0: 2a 70 70 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69  *ppDb, even.** i
9ac0: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
9ad0: 73 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61  s. If the databa
9ae0: 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 6f 72  se is opened (or
9af0: 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
9b00: 73 66 75 6c 6c 79 2c 0a 2a 2a 20 74 68 65 6e 20  sfully,.** then 
9b10: 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74  SQLITE_OK is ret
9b20: 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65  urned. Otherwise
9b30: 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
9b40: 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 0a  s returned. The.
9b50: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  ** sqlite3_errms
9b60: 67 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 65  g() or sqlite3_e
9b70: 72 72 6d 73 67 31 36 28 29 20 20 72 6f 75 74 69  rrmsg16()  routi
9b80: 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
9b90: 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
9ba0: 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
9bb0: 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
9bc0: 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a  the error..**.**
9bd0: 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
9be0: 20 66 69 6c 65 20 64 6f 65 73 20 6e 6f 74 20 65   file does not e
9bf0: 78 69 73 74 2c 20 74 68 65 6e 20 61 20 6e 65 77  xist, then a new
9c00: 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
9c10: 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 61 73 20  e created.** as 
9c20: 6e 65 65 64 65 64 2e 20 20 54 68 65 20 64 65 66  needed.  The def
9c30: 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
9c40: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  r the database w
9c50: 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a  ill be UTF-8 if.
9c60: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
9c70: 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 20  ) is called and 
9c80: 55 54 46 2d 31 36 20 69 66 20 73 71 6c 69 74 65  UTF-16 if sqlite
9c90: 33 5f 6f 70 65 6e 31 36 20 69 73 20 75 73 65 64  3_open16 is used
9ca0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
9cb0: 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
9cc0: 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
9cd0: 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
9ce0: 63 65 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  ces associated.*
9cf0: 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  * with the [sqli
9d00: 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 68 6f  te3*] handle sho
9d10: 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
9d20: 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  by passing it to
9d30: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  .** sqlite3_clos
9d40: 65 28 29 20 77 68 65 6e 20 69 74 20 69 73 20 6e  e() when it is n
9d50: 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
9d60: 64 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 6f  d..**.** Note to
9d70: 20 77 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 20   windows users: 
9d80: 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
9d90: 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
9da0: 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
9db0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
9dc0: 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
9dd0: 20 6e 6f 74 20 77 68 61 74 65 76 65 72 20 63 6f   not whatever co
9de0: 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
9df0: 74 6c 79 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20  tly.** defined. 
9e00: 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
9e10: 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
9e20: 6e 61 6c 20 63 68 61 72 61 63 74 65 72 73 20 6d  nal characters m
9e30: 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
9e40: 0a 2a 2a 20 74 6f 20 55 54 46 2d 38 20 70 72 69  .** to UTF-8 pri
9e50: 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
9e60: 65 6d 20 69 6e 74 6f 20 73 71 6c 69 74 65 33 5f  em into sqlite3_
9e70: 6f 70 65 6e 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73  open()..*/.int s
9e80: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
9e90: 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
9ea0: 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
9eb0: 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
9ec0: 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
9ed0: 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
9ee0: 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
9ef0: 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
9f00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
9f10: 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
9f20: 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
9f30: 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
9f40: 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
9f50: 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
9f60: 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
9f70: 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
9f80: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
9f90: 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
9fa0: 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
9fb0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  s.**.** The sqli
9fc0: 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e  te3_errcode() in
9fd0: 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
9fe0: 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b  the numeric.** [
9ff0: 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75  SQLITE_OK | resu
a000: 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c  lt code] or [SQL
a010: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
a020: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
a030: 20 63 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 74 68   code].** for th
a040: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
a050: 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
a060: 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74  PI call associat
a070: 65 64 0a 2a 2a 20 77 69 74 68 20 5b 73 71 6c 69  ed.** with [sqli
a080: 74 65 33 5d 20 68 61 6e 64 6c 65 20 27 64 62 27  te3] handle 'db'
a090: 2e 20 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  .  If a prior AP
a0a0: 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 20 62 75  I call failed bu
a0b0: 74 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  t the.** most re
a0c0: 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75  cent API call su
a0d0: 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74  cceeded, the ret
a0e0: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
a0f0: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
a100: 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
a110: 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  . .**.** The sql
a120: 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
a130: 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
a140: 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
a150: 69 73 68 2d 6c 61 6e 67 61 75 67 65 0a 2a 2a 20  ish-langauge.** 
a160: 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
a170: 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
a180: 73 20 65 69 74 68 65 72 20 55 54 46 38 20 6f 72  s either UTF8 or
a190: 20 55 54 46 31 36 20 72 65 73 70 65 63 74 69 76   UTF16 respectiv
a1a0: 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74  ely..** Memory t
a1b0: 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
a1c0: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
a1d0: 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
a1e0: 6e 61 6c 6c 79 2e 20 20 54 68 65 20 0a 2a 2a 20  nally.  The .** 
a1f0: 73 74 72 69 6e 67 20 6d 61 79 20 62 65 20 6f 76  string may be ov
a200: 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
a210: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 75 62 73  llocated by subs
a220: 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
a230: 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 66  SQLite.** interf
a240: 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ace functions..*
a250: 2a 0a 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 6d 61  *.** Calls to ma
a260: 6e 79 20 73 71 6c 69 74 65 33 5f 2a 20 66 75 6e  ny sqlite3_* fun
a270: 63 74 69 6f 6e 73 20 73 65 74 20 74 68 65 20 65  ctions set the e
a280: 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 73 74  rror code and st
a290: 72 69 6e 67 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ring returned.**
a2a0: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   by [sqlite3_err
a2b0: 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  code()], [sqlite
a2c0: 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64  3_errmsg()], and
a2d0: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
a2e0: 31 36 28 29 5d 0a 2a 2a 20 28 6f 76 65 72 77 72  16()].** (overwr
a2f0: 69 74 69 6e 67 20 74 68 65 20 70 72 65 76 69 6f  iting the previo
a300: 75 73 20 76 61 6c 75 65 73 29 2e 20 4e 6f 74 65  us values). Note
a310: 20 74 68 61 74 20 63 61 6c 6c 73 20 74 6f 20 5b   that calls to [
a320: 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
a330: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
a340: 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b  errmsg()], and [
a350: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
a360: 28 29 5d 20 74 68 65 6d 73 65 6c 76 65 73 20 64  ()] themselves d
a370: 6f 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65  o not affect the
a380: 0a 2a 2a 20 72 65 73 75 6c 74 73 20 6f 66 20 66  .** results of f
a390: 75 74 75 72 65 20 69 6e 76 6f 63 61 74 69 6f 6e  uture invocation
a3a0: 73 2e 20 20 43 61 6c 6c 73 20 74 6f 20 41 50 49  s.  Calls to API
a3b0: 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 64   routines that d
a3c0: 6f 20 6e 6f 74 20 72 65 74 75 72 6e 0a 2a 2a 20  o not return.** 
a3d0: 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65  an error code (e
a3e0: 78 61 6d 70 6c 65 73 3a 20 5b 73 71 6c 69 74 65  xamples: [sqlite
a3f0: 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 20  3_data_count()] 
a400: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  or [sqlite3_mpri
a410: 6e 74 66 28 29 5d 29 20 64 6f 0a 2a 2a 20 6e 6f  ntf()]) do.** no
a420: 74 20 63 68 61 6e 67 65 20 74 68 65 20 65 72 72  t change the err
a430: 6f 72 20 63 6f 64 65 20 72 65 74 75 72 6e 65 64  or code returned
a440: 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
a450: 2e 0a 2a 2a 0a 2a 2a 20 41 73 73 75 6d 69 6e 67  ..**.** Assuming
a460: 20 6e 6f 20 6f 74 68 65 72 20 69 6e 74 65 72 76   no other interv
a470: 65 6e 69 6e 67 20 73 71 6c 69 74 65 33 5f 2a 20  ening sqlite3_* 
a480: 41 50 49 20 63 61 6c 6c 73 20 61 72 65 20 6d 61  API calls are ma
a490: 64 65 2c 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  de, the error.**
a4a0: 20 63 6f 64 65 20 72 65 74 75 72 6e 65 64 20 62   code returned b
a4b0: 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  y this function 
a4c0: 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
a4d0: 74 68 20 74 68 65 20 73 61 6d 65 20 65 72 72 6f  th the same erro
a4e0: 72 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  r as.** the stri
a4f0: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
a500: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
a510: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
a520: 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a  errmsg16()]..*/.
a530: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
a540: 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
a550: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
a560: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
a570: 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
a580: 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
a590: 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
a5a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a5b0: 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
a5c0: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 49 6e 73 74  bject.**.** Inst
a5d0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
a5e0: 65 63 74 20 72 65 70 72 65 73 65 6e 74 20 73 69  ect represent si
a5f0: 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
a600: 6e 74 73 2e 20 20 54 68 69 73 0a 2a 2a 20 69 73  nts.  This.** is
a610: 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
a620: 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
a630: 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 20  statement" or a 
a640: 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
a650: 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
a660: 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
a670: 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a 20  tement"..** .** 
a680: 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
a690: 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
a6a0: 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
a6b0: 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
a6c0: 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
a6d0: 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
a6e0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
a6f0: 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
a700: 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
a710: 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
a720: 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
a730: 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
a740: 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b   using.**      [
a750: 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
a760: 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
a770: 5f 2a 20 69 6e 74 65 72 66 61 63 65 73 5d 2e 0a  _* interfaces]..
a780: 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
a790: 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
a7a0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
a7b0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
a7c0: 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
a7d0: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
a7e0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
a7f0: 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
a800: 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
a810: 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
a820: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
a830: 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
a840: 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
a850: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
a860: 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
a870: 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
a880: 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
a890: 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
a8a0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
a8b0: 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
a8c0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
a8d0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
a8e0: 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
a8f0: 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
a900: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
a910: 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
a920: 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ment.**.** To ex
a930: 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
a940: 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
a950: 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
a960: 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
a970: 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
a980: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
a990: 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a 20 54 68  tines. .**.** Th
a9a0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
a9b0: 20 22 64 62 22 20 69 73 20 61 6e 20 5b 73 71 6c   "db" is an [sql
a9c0: 69 74 65 33 20 7c 20 53 51 4c 69 74 65 20 64 61  ite3 | SQLite da
a9d0: 74 61 62 61 73 65 20 68 61 6e 64 6c 65 5d 20 0a  tabase handle] .
a9e0: 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
a9f0: 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
aa00: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
aa10: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
aa20: 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  en16()]..** The 
aa30: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
aa40: 22 7a 53 71 6c 22 20 69 73 20 74 68 65 20 73 74  "zSql" is the st
aa50: 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
aa60: 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
aa70: 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
aa80: 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
aa90: 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
aaa0: 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
aab0: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
aac0: 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 73   interfaces uses
aad0: 20 55 54 46 2d 38 20 61 6e 64 20 73 71 6c 69 74   UTF-8 and sqlit
aae0: 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
aaf0: 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
ab00: 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
ab10: 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49   UTF-16..**.** I
ab20: 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
ab30: 6d 65 6e 74 20 69 73 20 6c 65 73 73 0a 2a 2a 20  ment is less.** 
ab40: 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20  than zero, then 
ab50: 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
ab60: 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
ab70: 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 49  o terminator.  I
ab80: 66 0a 2a 2a 20 6e 42 79 74 65 20 69 73 20 6e 6f  f.** nByte is no
ab90: 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
aba0: 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d   it is the maxim
abb0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a  um number of .**
abc0: 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
abd0: 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79   zSql.  When nBy
abe0: 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
abf0: 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20  ve, the.** zSql 
ac00: 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65  string ends at e
ac10: 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20  ither the first 
ac20: 27 5c 30 30 30 27 20 63 68 61 72 61 63 74 65 72  '\000' character
ac30: 20 6f 72 20 0a 2a 2a 20 75 6e 74 69 6c 20 74 68   or .** until th
ac40: 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
ac50: 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
ac60: 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 2a 70   first..**.** *p
ac70: 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
ac80: 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
ac90: 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68  rst byte past th
aca0: 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
acb0: 73 74 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  st.** SQL statem
acc0: 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
acd0: 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
ace0: 63 6f 6d 70 69 6c 65 73 20 74 68 65 20 66 69 72  compiles the fir
acf0: 73 74 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  st statement.** 
ad00: 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
ad10: 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
ad20: 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d  ting to what rem
ad30: 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
ad40: 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69  .**.** *ppStmt i
ad50: 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
ad60: 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 0a 2a  to a compiled .*
ad70: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
ad80: 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  | SQL statement 
ad90: 73 74 72 75 63 74 75 72 65 5d 20 74 68 61 74 20  structure] that 
ada0: 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
adb0: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
adc0: 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72 20 69  3_step()].  Or i
add0: 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
ade0: 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 6d 61 79  ror, *ppStmt may
adf0: 20 62 65 0a 2a 2a 20 73 65 74 20 74 6f 20 4e 55   be.** set to NU
ae00: 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75  LL.  If the inpu
ae10: 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 65 64  t text contained
ae20: 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
ae30: 69 6e 70 75 74 20 69 73 20 61 6e 64 0a 2a 2a 20  input is and.** 
ae40: 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
ae50: 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
ae60: 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
ae70: 6f 20 4e 55 4c 4c 2e 20 20 54 68 65 20 63 61 6c  o NULL.  The cal
ae80: 6c 69 6e 67 0a 2a 2a 20 70 72 6f 63 65 64 75 72  ling.** procedur
ae90: 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
aea0: 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
aeb0: 65 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73  e compiled SQL s
aec0: 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e  tatement.** usin
aed0: 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
aee0: 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
aef0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
af00: 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73  h it..**.** On s
af10: 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
af20: 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
af30: 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 0a    Otherwise an .
af40: 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
af50: 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69   | error code] i
af60: 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
af70: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
af80: 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
af90: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
afa0: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
afb0: 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
afc0: 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
afd0: 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
afe0: 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
aff0: 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
b000: 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
b010: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
b020: 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
b030: 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
b040: 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
b050: 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
b060: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
b070: 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
b080: 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
b090: 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
b0a0: 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
b0b0: 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72 69 67 69  of the .** origi
b0c0: 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
b0d0: 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
b0e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
b0f0: 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
b100: 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e  ehave a differen
b110: 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a  tly in two ways:
b120: 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
b130: 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  li>.** If the da
b140: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
b150: 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
b160: 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
b170: 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
b180: 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
b190: 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
b1a0: 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
b1b0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
b1c0: 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
b1d0: 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
b1e0: 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
b1f0: 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65  in.  If the sche
b200: 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69  ma has changed i
b210: 6e 20 61 20 77 61 79 0a 2a 2a 20 74 68 61 74 20  n a way.** that 
b220: 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d  makes the statem
b230: 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61  ent no longer va
b240: 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  lid, [sqlite3_st
b250: 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c  ep()] will still
b260: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
b270: 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74  TE_SCHEMA].  But
b280: 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61   unlike the lega
b290: 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51  cy behavior, [SQ
b2a0: 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a  LITE_SCHEMA] is.
b2b0: 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  ** now a fatal e
b2c0: 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b  rror.  Calling [
b2d0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
b2e0: 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c  v2()] again will
b2f0: 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a   not make the.**
b300: 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20   error go away. 
b310: 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69   Note: use [sqli
b320: 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f  te3_errmsg()] to
b330: 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 20 6f   find the text o
b340: 66 20 74 68 65 20 70 61 72 73 69 6e 67 0a 2a 2a  f the parsing.**
b350: 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75   error that resu
b360: 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  lts in an [SQLIT
b370: 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e  E_SCHEMA] return
b380: 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
b390: 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e   <li>.** When an
b3a0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 0a   error occurs, .
b3b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
b3c0: 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
b3d0: 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
b3e0: 6c 65 64 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  led .** [SQLITE_
b3f0: 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74 20 63  ERROR | result c
b400: 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  odes] or.** [SQL
b410: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
b420: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
b430: 20 63 6f 64 65 73 5d 20 73 75 63 68 20 61 73 20   codes] such as 
b440: 64 69 72 65 63 74 6c 79 2e 0a 2a 2a 20 54 68 65  directly..** The
b450: 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
b460: 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c 69 74   was that [sqlit
b470: 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
b480: 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
b490: 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54  eneric.** [SQLIT
b4a0: 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
b4b0: 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77 6f 75  code and you wou
b4c0: 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
b4d0: 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
b4e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
b4f0: 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  et()] in order t
b500: 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
b510: 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
b520: 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20 57  he problem..** W
b530: 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
b540: 70 61 72 65 20 69 6e 74 65 72 66 61 63 65 73 2c  pare interfaces,
b550: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
b560: 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
b570: 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74 75 72  rror is.** retur
b580: 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
b590: 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
b5a0: 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
b5b0: 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
b5c0: 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
b5d0: 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
b5e0: 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
b5f0: 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
b600: 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
b610: 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
b620: 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
b630: 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
b640: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
b650: 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
b660: 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
b670: 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
b680: 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
b690: 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
b6a0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
b6b0: 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
b6c0: 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
b6d0: 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
b6e0: 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
b6f0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
b700: 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
b710: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
b720: 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
b730: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
b740: 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
b750: 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
b760: 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
b770: 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
b780: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
b790: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
b7a0: 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
b7b0: 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
b7c0: 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
b7d0: 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
b7e0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
b7f0: 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
b800: 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
b810: 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
b820: 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
b830: 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
b840: 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
b850: 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
b860: 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
b870: 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
b880: 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
b890: 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
b8a0: 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
b8b0: 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
b8c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
b8d0: 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
b8e0: 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
b8f0: 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
b900: 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
b910: 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
b920: 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
b930: 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
b940: 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
b950: 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
b960: 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
b970: 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
b980: 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
b990: 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
b9a0: 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
b9b0: 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
b9c0: 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
b9d0: 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
b9e0: 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
b9f0: 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
ba00: 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
ba10: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
ba20: 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
ba30: 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
ba40: 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
ba50: 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
ba60: 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
ba70: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
ba80: 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
ba90: 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
baa0: 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
bab0: 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
bac0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
bad0: 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
bae0: 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
baf0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
bb00: 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 20   dynamic typing 
bb10: 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
bb20: 74 20 73 74 6f 72 65 73 2e 20 20 56 61 6c 75 65  t stores.  Value
bb30: 73 20 63 61 6e 20 0a 2a 2a 20 62 65 20 69 6e 74  s can .** be int
bb40: 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
bb50: 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
bb60: 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
bb70: 20 4e 55 4c 4c 2e 20 20 57 68 65 6e 0a 2a 2a 20   NULL.  When.** 
bb80: 70 61 73 73 69 6e 67 20 61 72 6f 75 6e 64 20 76  passing around v
bb90: 61 6c 75 65 73 20 69 6e 74 65 72 6e 61 6c 6c 79  alues internally
bba0: 2c 20 65 61 63 68 20 76 61 6c 75 65 20 69 73 20  , each value is 
bbb0: 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 0a 2a  represented as.*
bbc0: 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * an instance of
bbd0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
bbe0: 75 65 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  ue object..*/.ty
bbf0: 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
bc00: 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
bc10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
bc20: 20 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43    SQL Function C
bc30: 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
bc40: 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
bc50: 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
bc60: 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
bc70: 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
bc80: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
bc90: 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20  text object.  A 
bca0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 75 63 68 20  pointer to such 
bcb0: 61 6e 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  an object is the
bcc0: 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d 65  .** first parame
bcd0: 74 65 72 20 74 6f 20 75 73 65 72 2d 64 65 66 69  ter to user-defi
bce0: 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
bcf0: 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
bd00: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
bd10: 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
bd20: 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
bd30: 49 33 52 45 46 3a 20 20 42 69 6e 64 69 6e 67 20  I3REF:  Binding 
bd40: 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
bd50: 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
bd60: 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73  .** In the SQL s
bd70: 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20  trings input to 
bd80: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
bd90: 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
bda0: 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6f 6e 65 20  ariants,.** one 
bdb0: 6f 72 20 6d 6f 72 65 20 6c 69 74 65 72 61 6c 73  or more literals
bdc0: 20 63 61 6e 20 62 65 20 72 65 70 6c 61 63 65 20   can be replace 
bdd0: 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69  by a parameter i
bde0: 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 0a 2a  n one of these.*
bdf0: 2a 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c  * forms:.**.** <
be00: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
be10: 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
be20: 3c 6c 69 3e 20 20 3a 41 41 41 0a 2a 2a 20 3c 6c  <li>  :AAA.** <l
be30: 69 3e 20 20 40 41 41 41 0a 2a 2a 20 3c 6c 69 3e  i>  @AAA.** <li>
be40: 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
be50: 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72  **.** In the par
be60: 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f  ameter forms sho
be70: 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20  wn above NNN is 
be80: 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
be90: 61 6c 2c 0a 2a 2a 20 41 41 41 20 69 73 20 61 6e  al,.** AAA is an
bea0: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
beb0: 65 6e 74 69 66 69 65 72 20 61 6e 64 20 56 56 56  entifier and VVV
bec0: 20 69 73 20 61 20 76 61 72 69 61 62 6c 65 20 6e   is a variable n
bed0: 61 6d 65 20 61 63 63 6f 72 64 69 6e 67 0a 2a 2a  ame according.**
bee0: 20 74 6f 20 74 68 65 20 73 79 6e 74 61 78 20 72   to the syntax r
bef0: 75 6c 65 73 20 6f 66 20 74 68 65 20 54 43 4c 20  ules of the TCL 
bf00: 70 72 6f 67 72 61 6d 6d 69 6e 67 20 6c 61 6e 67  programming lang
bf10: 75 61 67 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c  uage..** The val
bf20: 75 65 73 20 6f 66 20 74 68 65 73 65 20 70 61 72  ues of these par
bf30: 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
bf40: 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
bf50: 65 74 65 72 20 6e 61 6d 65 73 22 29 0a 2a 2a 20  eter names").** 
bf60: 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
bf70: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
bf80: 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
bf90: 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
bfa0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
bfb0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
bfc0: 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
bfd0: 75 74 69 6e 65 73 20 61 6c 77 61 79 73 20 69 73  utines always is
bfe0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
bff0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
c000: 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
c010: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
c020: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
c030: 6f 72 0a 2a 2a 20 69 74 73 20 76 61 72 69 61 6e  or.** its varian
c040: 74 73 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 0a  ts.  The second.
c050: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  ** argument is t
c060: 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
c070: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
c080: 73 65 74 2e 20 20 54 68 65 20 66 69 72 73 74 20  set.  The first 
c090: 70 61 72 61 6d 65 74 65 72 20 68 61 73 0a 2a 2a  parameter has.**
c0a0: 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
c0b0: 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
c0c0: 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  med parameter is
c0d0: 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
c0e0: 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 0a 2a 2a 20  once, second.** 
c0f0: 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
c100: 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
c110: 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
c120: 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
c130: 63 63 75 72 72 65 6e 63 65 2e 20 20 54 68 65 20  ccurrence.  The 
c140: 69 6e 64 65 78 20 66 6f 72 0a 2a 2a 20 6e 61 6d  index for.** nam
c150: 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
c160: 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
c170: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
c180: 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
c190: 74 65 72 5f 6e 61 6d 65 28 29 5d 20 41 50 49 20  ter_name()] API 
c1a0: 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 65  if desired.  The
c1b0: 20 69 6e 64 65 78 20 66 6f 72 20 22 3f 4e 4e 4e   index for "?NNN
c1c0: 22 0a 2a 2a 20 70 61 72 61 6d 65 74 65 73 20 69  ".** parametes i
c1d0: 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
c1e0: 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76  NN..** The NNN v
c1f0: 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
c200: 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 63  ween 1 and the c
c210: 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70  ompile-time.** p
c220: 61 72 61 6d 65 74 65 72 20 53 51 4c 49 54 45 5f  arameter SQLITE_
c230: 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MAX_VARIABLE_NUM
c240: 42 45 52 20 28 64 65 66 61 75 6c 74 20 76 61 6c  BER (default val
c250: 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 20 53 65 65  ue: 999)..** See
c260: 20 3c 61 20 68 72 65 66 3d 22 6c 69 6d 69 74 73   <a href="limits
c270: 2e 68 74 6d 6c 22 3e 6c 69 6d 69 74 73 2e 68 74  .html">limits.ht
c280: 6d 6c 3c 2f 61 3e 20 66 6f 72 20 61 64 64 69 74  ml</a> for addit
c290: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
c2a0: 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  n..**.** The thi
c2b0: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
c2c0: 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
c2d0: 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
c2e0: 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73  r..**.** In thos
c2f0: 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  e.** routines th
c300: 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
c310: 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
c320: 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62  alue is the numb
c330: 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 69  er of bytes.** i
c340: 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
c350: 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
c360: 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20  he value is the 
c370: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
c380: 69 6e 20 74 68 65 0a 2a 2a 20 73 74 72 69 6e 67  in the.** string
c390: 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
c3a0: 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 20   of characters. 
c3b0: 20 54 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   The number.** o
c3c0: 66 20 62 79 74 65 73 20 64 6f 65 73 20 6e 6f 74  f bytes does not
c3d0: 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
c3e0: 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20  o-terminator at 
c3f0: 74 68 65 20 65 6e 64 20 6f 66 20 73 74 72 69 6e  the end of strin
c400: 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  gs..** If the fo
c410: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
c420: 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  s negative, the 
c430: 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
c440: 72 69 6e 67 20 69 73 0a 2a 2a 20 6e 75 6d 62 65  ring is.** numbe
c450: 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
c460: 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
c470: 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
c480: 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 67 75  * The fifth argu
c490: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
c4a0: 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
c4b0: 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
c4c0: 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
c4d0: 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
c4e0: 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
c4f0: 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
c500: 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
c510: 20 74 65 78 74 20 61 66 74 65 72 20 53 51 4c 69   text after SQLi
c520: 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
c530: 77 69 74 68 20 69 74 2e 20 20 49 66 20 74 68 65  with it.  If the
c540: 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
c550: 69 73 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 61  is the.** specia
c560: 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
c570: 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 74 68  STATIC], then th
c580: 65 20 6c 69 62 72 61 72 79 20 61 73 73 75 6d 65  e library assume
c590: 73 20 74 68 61 74 20 74 68 65 20 69 6e 66 6f 72  s that the infor
c5a0: 6d 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 20  mation.** is in 
c5b0: 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
c5c0: 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
c5d0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
c5e0: 66 72 65 65 64 2e 20 20 49 66 20 74 68 65 0a 2a  freed.  If the.*
c5f0: 2a 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  * fifth argument
c600: 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
c610: 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
c620: 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ], then SQLite m
c630: 61 6b 65 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20  akes its.** own 
c640: 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
c650: 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
c660: 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65  tely, before the
c670: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
c680: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
c690: 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
c6a0: 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
c6b0: 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
c6c0: 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
c6d0: 6c 65 6e 67 74 68 20 6e 20 74 68 61 74 0a 2a 2a  length n that.**
c6e0: 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
c6f0: 7a 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f 62 6c  zeros.  A zerobl
c700: 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
c710: 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
c720: 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
c730: 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 20  eger to hold it 
c740: 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
c750: 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
c760: 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
c770: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
c780: 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 2d 68  serve as place-h
c790: 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
c7a0: 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
c7b0: 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
c7c0: 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  en using .** [sq
c7d0: 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
c7e0: 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c 4f 42  | increment BLOB
c7f0: 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
c800: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
c810: 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
c820: 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
c830: 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c  ed after.** [sql
c840: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
c850: 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 69  )] (and its vari
c860: 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65  ants) or [sqlite
c870: 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a  3_reset()] and.*
c880: 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  * before [sqlite
c890: 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69  3_step()]..** Bi
c8a0: 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
c8b0: 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
c8c0: 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
c8d0: 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f  routine..** Unbo
c8e0: 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
c8f0: 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
c900: 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
c910: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
c920: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
c930: 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
c940: 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a   error code if.*
c950: 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  * anything goes 
c960: 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f  wrong.  [SQLITE_
c970: 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
c980: 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
c990: 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
c9a0: 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b  out of range.  [
c9b0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
c9c0: 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
c9d0: 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53  loc fails..** [S
c9e0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 69 73  QLITE_MISUSE] is
c9f0: 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
ca00: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
ca10: 63 61 6c 6c 65 64 20 6f 6e 20 61 20 76 69 72 74  called on a virt
ca20: 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 74  ual.** machine t
ca30: 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67  hat is the wrong
ca40: 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 20   state or which 
ca50: 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e  has already been
ca60: 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2f 0a 69   finalized..*/.i
ca70: 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
ca80: 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
ca90: 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
caa0: 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
cab0: 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
cac0: 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
cad0: 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
cae0: 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
caf0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
cb00: 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
cb10: 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
cb20: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
cb30: 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
cb40: 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
cb50: 69 74 65 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  ite_int64);.int 
cb60: 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
cb70: 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
cb80: 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
cb90: 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
cba0: 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
cbb0: 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
cbc0: 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
cbd0: 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
cbe0: 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
cbf0: 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
cc00: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
cc10: 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
cc20: 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
cc30: 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
cc40: 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
cc50: 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
cc60: 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
cc70: 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
cc80: 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
cc90: 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
cca0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
ccb0: 6d 62 65 72 20 4f 66 20 48 6f 73 74 20 50 61 72  mber Of Host Par
ccc0: 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 52 65  ameters.**.** Re
ccd0: 74 75 72 6e 20 74 68 65 20 6c 61 72 67 65 73 74  turn the largest
cce0: 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
ccf0: 69 6e 64 65 78 20 69 6e 20 74 68 65 20 70 72 65  index in the pre
cd00: 63 6f 6d 70 69 6c 65 64 20 73 74 61 74 65 6d 65  compiled stateme
cd10: 6e 74 20 67 69 76 65 6e 0a 2a 2a 20 61 73 20 74  nt given.** as t
cd20: 68 65 20 61 72 67 75 6d 65 6e 74 2e 20 20 57 68  he argument.  Wh
cd30: 65 6e 20 74 68 65 20 68 6f 73 74 20 70 61 72 61  en the host para
cd40: 6d 65 74 65 72 73 20 61 72 65 20 6f 66 20 74 68  meters are of th
cd50: 65 20 66 6f 72 6d 73 20 6c 69 6b 65 20 22 3a 41  e forms like ":A
cd60: 41 41 22 0a 2a 2a 20 6f 72 20 22 3f 22 2c 20 74  AA".** or "?", t
cd70: 68 65 6e 20 74 68 65 79 20 61 72 65 20 61 73 73  hen they are ass
cd80: 69 67 6e 65 64 20 73 65 71 75 65 6e 74 69 61 6c  igned sequential
cd90: 20 69 6e 63 72 65 61 73 69 6e 67 20 6e 75 6d 62   increasing numb
cda0: 65 72 73 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ers beginning.**
cdb0: 20 77 69 74 68 20 6f 6e 65 2c 20 73 6f 20 74 68   with one, so th
cdc0: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
cdd0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
cde0: 66 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 48  f parameters.  H
cdf0: 6f 77 65 76 65 72 0a 2a 2a 20 69 66 20 74 68 65  owever.** if the
ce00: 20 73 61 6d 65 20 68 6f 73 74 20 70 61 72 61 6d   same host param
ce10: 65 74 65 72 20 6e 61 6d 65 20 69 73 20 75 73 65  eter name is use
ce20: 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
ce30: 2c 20 65 61 63 68 20 6f 63 63 75 72 72 61 6e 63  , each occurranc
ce40: 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e 20 74 68  e.** is given th
ce50: 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 2c 20 73  e same number, s
ce60: 6f 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  o the value retu
ce70: 72 6e 65 64 20 69 6e 20 74 68 61 74 20 63 61 73  rned in that cas
ce80: 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 0a  e is the number.
ce90: 2a 2a 20 6f 66 20 75 6e 69 71 75 65 20 68 6f 73  ** of unique hos
cea0: 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
ceb0: 73 2e 20 20 49 66 20 68 6f 73 74 20 70 61 72 61  s.  If host para
cec0: 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
ced0: 72 6d 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 61 72 65  rm "?NNN".** are
cee0: 20 75 73 65 64 20 28 77 68 65 72 65 20 4e 4e 4e   used (where NNN
cef0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29 20   is an integer) 
cf00: 74 68 65 6e 20 74 68 65 72 65 20 6d 69 67 68 74  then there might
cf10: 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 0a   be gaps in the.
cf20: 2a 2a 20 6e 75 6d 62 65 72 69 6e 67 20 61 6e 64  ** numbering and
cf30: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
cf40: 6e 65 64 20 62 79 20 74 68 69 73 20 69 6e 74 65  ned by this inte
cf50: 72 66 61 63 65 20 69 73 20 74 68 65 20 69 6e 64  rface is the ind
cf60: 65 78 20 6f 66 20 74 68 65 0a 2a 2a 20 68 6f 73  ex of the.** hos
cf70: 74 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68  t parameter with
cf80: 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64   the largest ind
cf90: 65 78 20 76 61 6c 75 65 2e 0a 2a 2f 0a 69 6e 74  ex value..*/.int
cfa0: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
cfb0: 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
cfc0: 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
cfd0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
cfe0: 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
cff0: 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 54 68  rameter.**.** Th
d000: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
d010: 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
d020: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
d030: 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  n-th parameter i
d040: 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  n a .** [sqlite3
d050: 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64  _stmt | prepared
d060: 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
d070: 48 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  Host parameters 
d080: 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3a 41 41  of the form ":AA
d090: 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
d0a0: 22 24 56 56 56 22 20 68 61 76 65 20 61 20 6e 61  "$VVV" have a na
d0b0: 6d 65 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 74  me.** which is t
d0c0: 68 65 20 73 74 72 69 6e 67 20 22 3a 41 41 41 22  he string ":AAA"
d0d0: 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
d0e0: 56 56 56 22 2e 20 20 0a 2a 2a 20 49 6e 20 6f 74  VVV".  .** In ot
d0f0: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
d100: 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
d110: 22 20 6f 72 20 22 40 22 0a 2a 2a 20 69 73 20 69  " or "@".** is i
d120: 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
d130: 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20  of the name..** 
d140: 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
d150: 65 20 66 6f 72 6d 20 22 3f 22 20 6f 72 20 22 3f  e form "?" or "?
d160: 4e 4e 4e 22 20 68 61 76 65 20 6e 6f 20 6e 61 6d  NNN" have no nam
d170: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
d180: 73 74 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  st bound paramet
d190: 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
d1a0: 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
d1b0: 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65 20  ** If the value 
d1c0: 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  n is out of rang
d1d0: 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68  e or if the n-th
d1e0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 61   parameter is na
d1f0: 6d 65 6c 65 73 73 2c 0a 2a 2a 20 74 68 65 6e 20  meless,.** then 
d200: 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
d210: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  .  The returned 
d220: 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
d230: 20 69 6e 20 74 68 65 0a 2a 2a 20 55 54 46 2d 38   in the.** UTF-8
d240: 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
d250: 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
d260: 6d 65 74 65 72 20 77 61 73 20 6f 72 69 67 69 6e  meter was origin
d270: 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 0a 2a  ally specified.*
d280: 2a 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  * as UTF-16 in [
d290: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
d2a0: 36 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  6()] or [sqlite3
d2b0: 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
d2c0: 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
d2d0: 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
d2e0: 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
d2f0: 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
d300: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
d310: 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
d320: 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
d330: 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20  iven Name.**.** 
d340: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
d350: 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
d360: 66 20 61 20 68 6f 73 74 20 70 61 72 61 6d 65 74  f a host paramet
d370: 65 72 20 77 69 74 68 20 74 68 65 20 67 69 76 65  er with the give
d380: 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 6e  n name..** The n
d390: 61 6d 65 20 6d 75 73 74 20 6d 61 74 63 68 20 65  ame must match e
d3a0: 78 61 63 74 6c 79 2e 20 20 49 66 20 6e 6f 20 70  xactly.  If no p
d3b0: 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 74 68  arameter with th
d3c0: 65 20 67 69 76 65 6e 20 6e 61 6d 65 20 69 73 20  e given name is 
d3d0: 0a 2a 2a 20 66 6f 75 6e 64 2c 20 72 65 74 75 72  .** found, retur
d3e0: 6e 20 30 2e 20 20 50 61 72 61 6d 65 74 65 72 20  n 0.  Parameter 
d3f0: 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 55 54  names must be UT
d400: 46 38 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  F8..*/.int sqlit
d410: 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
d420: 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
d430: 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
d440: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
d450: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
d460: 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
d470: 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
d480: 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 43 6f 6e  tement.**.** Con
d490: 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
d4a0: 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
d4b0: 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
d4c0: 5d 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72 65  ] does not.** re
d4d0: 73 65 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  set the [sqlite3
d4e0: 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
d4f0: 64 69 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20  dings] on a .** 
d500: 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
d510: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
d520: 6e 74 5d 2e 20 20 55 73 65 20 74 68 69 73 20 72  nt].  Use this r
d530: 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73  outine to.** res
d540: 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
d550: 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
d560: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
d570: 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
d580: 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
d590: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
d5a0: 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
d5b0: 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
d5c0: 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68  .**.** Return th
d5d0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
d5e0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
d5f0: 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
d600: 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  y the .** [sqlit
d610: 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c  e3_stmt | compil
d620: 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
d630: 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ]. This routine 
d640: 72 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69 66 20  returns 0.** if 
d650: 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 20  pStmt is an SQL 
d660: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
d670: 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
d680: 61 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65 78 61  ata (for .** exa
d690: 6d 70 6c 65 20 61 6e 20 55 50 44 41 54 45 29 2e  mple an UPDATE).
d6a0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
d6b0: 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
d6c0: 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
d6d0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
d6e0: 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
d6f0: 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
d700: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
d710: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
d720: 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
d730: 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
d740: 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
d750: 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
d760: 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
d770: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  .  The sqlite3_c
d780: 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
d790: 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
d7a0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
d7b0: 20 55 54 46 38 20 73 74 72 69 6e 67 20 61 6e 64   UTF8 string and
d7c0: 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
d7d0: 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 72 65 74 75  name16().** retu
d7e0: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
d7f0: 20 61 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e   a UTF16 string.
d800: 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
d810: 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
d820: 5b 73 71 6c 69 74 65 5f 73 74 6d 74 20 7c 20 70  [sqlite_stmt | p
d830: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
d840: 74 5d 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  t] that implemen
d850: 74 73 20 74 68 65 20 53 45 4c 45 43 54 20 73 74  ts the SELECT st
d860: 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  atement..** The 
d870: 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
d880: 20 69 73 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e   is the column n
d890: 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74  umber.  The left
d8a0: 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 0a  -most column is.
d8b0: 2a 2a 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  ** number 0..**.
d8c0: 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  ** The returned 
d8d0: 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
d8e0: 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
d8f0: 74 68 65 72 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ther the .** [sq
d900: 6c 69 74 65 5f 73 74 6d 74 20 7c 20 70 72 65 70  lite_stmt | prep
d910: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
d920: 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
d930: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
d940: 65 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c  e()].** or until
d950: 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 73   the next call s
d960: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
d970: 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
d980: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a  column_name16().
d990: 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  ** on the same c
d9a0: 6f 6c 75 6d 6e 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  olumn..*/.const 
d9b0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
d9c0: 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
d9d0: 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
d9e0: 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
d9f0: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
da00: 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
da10: 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
da20: 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
da30: 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
da40: 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
da50: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
da60: 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
da70: 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68   to determine wh
da80: 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61  at column of wha
da90: 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68  t.** table in wh
daa0: 69 63 68 20 64 61 74 61 62 61 73 65 20 61 20 72  ich database a r
dab0: 65 73 75 6c 74 20 6f 66 20 61 20 53 45 4c 45 43  esult of a SELEC
dac0: 54 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65  T statement come
dad0: 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e  s from..** The n
dae0: 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
daf0: 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
db00: 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
db10: 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
db20: 68 65 72 20 61 20 55 54 46 38 20 6f 72 20 55 54  her a UTF8 or UT
db30: 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65  F16 string.  The
db40: 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
db50: 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
db60: 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
db70: 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
db80: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
db90: 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
dba0: 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
dbb0: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
dbc0: 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
dbd0: 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65  ..** The returne
dbe0: 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
dbf0: 64 20 75 6e 74 69 6c 0a 2a 2a 20 74 68 65 20 5b  d until.** the [
dc00: 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70  sqlite3_stmt | p
dc10: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
dc20: 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  t] is destroyed 
dc30: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
dc40: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
dc50: 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
dc60: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
dc70: 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
dc80: 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
dc90: 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
dca0: 20 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72   The names retur
dcb0: 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
dcc0: 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
dcd0: 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
dce0: 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
dcf0: 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
dd00: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
dd10: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c  ument to the fol
dd20: 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20  lowing calls is 
dd30: 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  a .** [sqlite3_s
dd40: 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53  tmt | compiled S
dd50: 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  QL statement]..*
dd60: 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
dd70: 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
dd80: 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
dd90: 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
dda0: 65 64 20 62 79 20 0a 2a 2a 20 74 68 65 20 73 74  ed by .** the st
ddb0: 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
ddc0: 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
ddd0: 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
dde0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e  ..**.** If the N
ddf0: 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
de00: 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
de10: 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
de20: 73 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75  sion.** or subqu
de30: 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
de40: 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
de50: 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
de60: 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
de70: 74 75 72 6e 20 4e 55 4c 4c 2e 20 4f 74 68 65 72  turn NULL. Other
de80: 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
de90: 6e 20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f  n the .** name o
dea0: 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
deb0: 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 20 61  atabase, table a
dec0: 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  nd column that q
ded0: 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 63  uery result.** c
dee0: 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
def0: 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
df00: 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
df10: 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
df20: 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20 77  hose postfixed w
df30: 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 20  ith "16" return 
df40: 55 54 46 2d 31 36 0a 2a 2a 20 65 6e 63 6f 64 65  UTF-16.** encode
df50: 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f  d strings, the o
df60: 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
df70: 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
df80: 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72  ** These APIs ar
df90: 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
dfa0: 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
dfb0: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
dfc0: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45  h the .** SQLITE
dfd0: 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
dfe0: 45 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65  ETADATA preproce
dff0: 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
e000: 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
e010: 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
e020: 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
e030: 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
e040: 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
e050: 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
e060: 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
e070: 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
e080: 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
e090: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
e0a0: 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
e0b0: 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
e0c0: 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
e0d0: 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
e0e0: 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
e0f0: 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
e100: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
e110: 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
e120: 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
e130: 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
e140: 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
e150: 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
e160: 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
e170: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
e180: 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
e190: 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
e1a0: 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Result.**.** The
e1b0: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
e1c0: 20 69 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   is a [sqlite3_s
e1d0: 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53  tmt | compiled S
e1e0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a  QL statement]. .
e1f0: 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
e200: 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45 43 54  ment is a SELECT
e210: 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
e220: 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
e230: 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65   the .** returne
e240: 64 20 72 65 73 75 6c 74 20 73 65 74 20 20 6f 66  d result set  of
e250: 20 74 68 61 74 20 53 45 4c 45 43 54 20 69 73 20   that SELECT is 
e260: 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
e270: 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
e280: 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
e290: 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
e2a0: 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
e2b0: 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
e2c0: 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20  is returned. If 
e2d0: 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
e2e0: 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
e2f0: 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
e300: 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
e310: 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
e320: 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
e330: 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  d..** The return
e340: 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
e350: 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
e360: 64 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d. For example, 
e370: 69 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  in.** the databa
e380: 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
e390: 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
e3a0: 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
e3b0: 0a 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c  .** And the foll
e3c0: 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
e3d0: 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
e3e0: 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
e3f0: 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
e400: 20 54 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   Then this routi
e410: 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
e420: 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
e430: 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
e440: 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f  ond.** result co
e450: 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
e460: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
e470: 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
e480: 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28  sult column.** (
e490: 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  i==0)..**.** SQL
e4a0: 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
e4b0: 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
e4c0: 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75  .  So just becau
e4d0: 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
e4e0: 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
e4f0: 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
e500: 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
e510: 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
e520: 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
e530: 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
e540: 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
e550: 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
e560: 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
e570: 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
e580: 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
e590: 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a  t static.  Type.
e5a0: 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
e5b0: 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
e5c0: 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
e5d0: 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
e5e0: 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
e5f0: 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
e600: 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
e610: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
e620: 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
e630: 6d 74 20 2a 2c 20 69 6e 74 20 69 29 3b 0a 63 6f  mt *, int i);.co
e640: 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
e650: 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
e660: 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
e670: 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20  *,int);../* .** 
e680: 43 41 50 49 33 52 45 46 3a 20 20 45 76 61 6c 75  CAPI3REF:  Evalu
e690: 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
e6a0: 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
e6b0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d   an [sqlite3_stm
e6c0: 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  t | SQL statemen
e6d0: 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
e6e0: 61 72 65 64 20 77 69 74 68 20 61 20 63 61 6c 6c  ared with a call
e6f0: 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72 20 5b 73  .** to either [s
e700: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
e710: 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
e720: 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
e730: 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a 2a   or to one of.**
e740: 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
e750: 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
e760: 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
e770: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
e780: 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  ()],.** then thi
e790: 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  s function must 
e7a0: 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
e7b0: 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
e7c0: 76 61 6c 75 61 74 65 20 74 68 65 20 0a 2a 2a 20  valuate the .** 
e7d0: 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
e7e0: 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
e7f0: 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
e800: 74 68 69 73 20 73 71 6c 69 74 65 33 5f 73 74 65  this sqlite3_ste
e810: 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
e820: 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
e830: 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
e840: 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
e850: 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
e860: 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
e870: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
e880: 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
e890: 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
e8a0: 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
e8b0: 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
e8c0: 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
e8d0: 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
e8e0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
e8f0: 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
e900: 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
e910: 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
e920: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
e930: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
e940: 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
e950: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
e960: 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
e970: 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  pported..**.** I
e980: 6e 20 74 68 65 20 6c 61 67 61 63 79 20 69 6e 74  n the lagacy int
e990: 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
e9a0: 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
e9b0: 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
e9c0: 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49  BUSY], .** [SQLI
e9d0: 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
e9e0: 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
e9f0: 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
ea00: 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57  TE_MISUSE]..** W
ea10: 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
ea20: 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
ea30: 68 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54 45  he other [SQLITE
ea40: 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  _OK | result cod
ea50: 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  e].** or [SQLITE
ea60: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
ea70: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
ea80: 64 65 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  de] might be ret
ea90: 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77 65 6c 6c  urned as.** well
eaa0: 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
eab0: 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
eac0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
ead0: 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
eae0: 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
eaf0: 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
eb00: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
eb10: 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65  its job.  If the
eb20: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
eb30: 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63 63  COMMIT.** or occ
eb40: 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
eb50: 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
eb60: 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
eb70: 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
eb80: 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
eb90: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
eba0: 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54 20 61  s not a COMMIT a
ebb0: 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
ebc0: 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74   a.** explicit t
ebd0: 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
ebe0: 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
ebf0: 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
ec00: 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
ec10: 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
ec20: 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
ec30: 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
ec40: 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
ec50: 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
ec60: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
ec70: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
ec80: 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
ec90: 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
eca0: 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
ecb0: 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
ecc0: 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
ecd0: 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
ece0: 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
ecf0: 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
ed00: 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
ed10: 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66   state..**.** If
ed20: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
ed30: 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
ed40: 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
ed50: 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 53 51  ta, then .** [SQ
ed60: 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20 72 65 74  LITE_ROW] is ret
ed70: 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
ed80: 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
ed90: 61 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 66 6f  a is ready.** fo
eda0: 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
edb0: 74 68 65 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  the caller. The 
edc0: 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
edd0: 63 65 73 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  cessed using.** 
ede0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
edf0: 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d 6e  umn_int | column
ee00: 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
ee10: 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
ee20: 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
ee30: 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
ee40: 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
ee50: 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b  f data..** .** [
ee60: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
ee70: 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
ee80: 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
ee90: 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
eea0: 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
eeb0: 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
eec0: 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
eed0: 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
eee0: 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
eef0: 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
ef00: 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
ef10: 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
ef20: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
ef30: 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65  ..** With the le
ef40: 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
ef50: 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
ef60: 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61 6d  error code (exam
ef70: 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple:.** [SQLITE_
ef80: 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
ef90: 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
efa0: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
efb0: 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
efc0: 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
efd0: 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
efe0: 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
eff0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 73  the.** [sqlite_s
f000: 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73  tmt | prepared s
f010: 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74  tatement].  In t
f020: 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
f030: 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
f040: 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
f050: 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
f060: 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
f070: 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
f080: 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
f090: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
f0a0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
f0b0: 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
f0c0: 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
f0d0: 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
f0e0: 64 20 6f 6e 20 61 20 5b 73 71 6c 69 74 65 5f 73  d on a [sqlite_s
f0f0: 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73  tmt | prepared s
f100: 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
f110: 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
f120: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
f130: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
f140: 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
f150: 20 68 61 64 20 0a 2a 2a 20 70 72 65 76 69 6f 75   had .** previou
f160: 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
f170: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
f180: 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
f190: 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
f1a0: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
f1b0: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
f1c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
f1d0: 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
f1e0: 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
f1f0: 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
f200: 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
f210: 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
f220: 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
f230: 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65  /b>.** In the le
f240: 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
f250: 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
f260: 73 74 65 70 28 29 20 41 50 49 20 61 6c 77 61 79  step() API alway
f270: 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
f280: 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a  ric error code,.
f290: 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
f2a0: 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
f2b0: 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
f2c0: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
f2d0: 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  ** and [SQLITE_M
f2e0: 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
f2f0: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
f300: 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
f310: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
f320: 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
f330: 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 20  find one of the 
f340: 73 70 65 63 69 66 69 63 0a 2a 2a 20 5b 53 51 4c  specific.** [SQL
f350: 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75  ITE_ERROR | resu
f360: 6c 74 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  lt codes] that b
f370: 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
f380: 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
f390: 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
f3a0: 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
f3b0: 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
f3c0: 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
f3d0: 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
f3e0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
f3f0: 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
f400: 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
f410: 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
f420: 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
f430: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
f440: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
f450: 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
f460: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
f470: 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
f480: 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
f490: 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
f4a0: 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a 20 6d  , then the .** m
f4b0: 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 53 51  ore specific [SQ
f4c0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73  LITE_ERROR | res
f4d0: 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ult codes] are r
f4e0: 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
f4f0: 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
f500: 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
f510: 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
f520: 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
f530: 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nded..*/.int sql
f540: 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
f550: 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
f560: 20 43 41 50 49 33 52 45 46 3a 0a 2a 2a 0a 2a 2a   CAPI3REF:.**.**
f570: 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62   Return the numb
f580: 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20  er of values in 
f590: 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
f5a0: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
f5b0: 74 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  t..**.** After a
f5c0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
f5d0: 33 5f 73 74 65 70 28 29 5d 20 74 68 61 74 20 72  3_step()] that r
f5e0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
f5f0: 4f 57 5d 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  OW], this routin
f600: 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  e.** will return
f610: 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
f620: 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  as the [sqlite3_
f630: 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 20  column_count()] 
f640: 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 41 66 74  function..** Aft
f650: 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
f660: 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
f670: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   an [SQLITE_DONE
f680: 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
f690: 2c 20 6f 72 0a 2a 2a 20 61 20 5b 53 51 4c 49 54  , or.** a [SQLIT
f6a0: 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20  E_ERROR | error 
f6b0: 63 6f 64 65 5d 2c 20 6f 72 20 62 65 66 6f 72 65  code], or before
f6c0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
f6d0: 5d 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a 20 63  ] has been .** c
f6e0: 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b 73 71  alled on the [sq
f6f0: 6c 69 74 65 5f 73 74 6d 74 20 7c 20 70 72 65 70  lite_stmt | prep
f700: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
f710: 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 74 69  for the first ti
f720: 6d 65 2c 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  me,.** this rout
f730: 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
f740: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
f750: 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
f760: 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
f770: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
f780: 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
f790: 61 74 61 74 79 70 65 73 0a 2a 2a 0a 2a 2a 20 45  atatypes.**.** E
f7a0: 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
f7b0: 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
f7c0: 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
f7d0: 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
f7e0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
f7f0: 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
f800: 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
f810: 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
f820: 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
f830: 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
f840: 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
f850: 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
f860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
f870: 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
f880: 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
f890: 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
f8a0: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
f8b0: 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
f8c0: 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
f8d0: 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
f8e0: 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
f8f0: 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
f900: 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
f910: 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
f920: 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
f930: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
f940: 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
f950: 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
f960: 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 6e  e SQLITE3_TEXT n
f970: 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
f980: 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
f990: 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
f9a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
f9b0: 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
f9c0: 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
f9d0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
f9e0: 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
f9f0: 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
fa00: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
fa10: 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
fa20: 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
fa30: 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
fa40: 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
fa50: 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
fa60: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 73  API3REF: Results
fa70: 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
fa80: 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  uery.**.** These
fa90: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
faa0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
fab0: 75 74 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 69  ut the informati
fac0: 6f 6e 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c  on.** in a singl
fad0: 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
fae0: 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 72  current result r
faf0: 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
fb00: 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73 65  In every.** case
fb10: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
fb20: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
fb30: 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   to the .** [sql
fb40: 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20  ite3_stmt | SQL 
fb50: 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
fb60: 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61 6c  is being.** eval
fb70: 75 61 74 65 20 28 74 68 65 20 5b 73 71 6c 69 74  uate (the [sqlit
fb80: 65 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20 77 61  e_stmt*] that wa
fb90: 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
fba0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
fbb0: 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
fbc0: 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
fbd0: 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20 73 65  s) and.** the se
fbe0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
fbf0: 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
fc00: 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
fc10: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a  ch information .
fc20: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
fc30: 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74  urned.  The left
fc40: 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 68 61 73  -most column has
fc50: 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a   an index of 0..
fc60: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
fc70: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
fc80: 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
fc90: 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
fca0: 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 74  , or if the.** t
fcb0: 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  he column index 
fcc0: 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
fcd0: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
fce0: 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
fcf0: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
fd00: 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
fd10: 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53  e returns .** [S
fd20: 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
fd30: 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
fd40: 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
fd50: 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
fd60: 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
fd70: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  .  The returned 
fd80: 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
fd90: 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
fda0: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
fdb0: 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
fdc0: 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
fdd0: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
fde0: 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
fdf0: 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
fe00: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
fe10: 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
fe20: 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
fe30: 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
fe40: 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
fe50: 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
fe60: 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
fe70: 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
fe80: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
fe90: 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
fea0: 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
feb0: 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
fec0: 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
fed0: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
fee0: 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
fef0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
ff00: 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
ff10: 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
ff20: 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
ff30: 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
ff40: 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
ff50: 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
ff60: 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
ff70: 62 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74  bytes() .** rout
ff80: 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
ff90: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
ffa0: 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
ffb0: 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68  string..** If th
ffc0: 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
ffd0: 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
ffe0: 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
fff0: 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
10000 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
10010 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
10020 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
10030 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
10040 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
10050 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
10060 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
10070 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
10080 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
10090 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
100a0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
100b0 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
100c0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
100d0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
100e0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
100f0 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61  tring..** The va
10100 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65  lue returned doe
10110 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  s not include th
10120 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
10130 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  r at the end.** 
10140 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
10150 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
10160 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
10170 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
10180 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
10190 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
101a0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
101b0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  cters..**.** The
101c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
101d0 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e  bytes16() routin
101e0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
101f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
10200 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65  ytes().** but le
10210 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  aves the result 
10220 69 6e 20 55 54 46 2d 31 36 20 69 6e 73 74 65 61  in UTF-16 instea
10230 64 20 6f 66 20 55 54 46 2d 38 2e 20 20 0a 2a 2a  d of UTF-8.  .**
10240 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   The zero termin
10250 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c  ator is not incl
10260 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75  uded in this cou
10270 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  nt..**.** These 
10280 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
10290 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
102a0 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
102b0 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a  opriate.  For.**
102c0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
102d0 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
102e0 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
102f0 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
10300 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
10310 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
10320 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
10330 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
10340 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  do the conversio
10350 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  n.** automatical
10360 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ly.  The followi
10370 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
10380 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
10390 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 70 70   that.** are app
103a0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
103b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
103c0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
103d0 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
103e0 6e 61 6c 20 3c 74 68 3e 20 52 65 71 75 65 73 74  nal <th> Request
103f0 65 64 20 3c 74 68 3e 20 0a 2a 2a 20 3c 74 72 3e  ed <th> .** <tr>
10400 3c 74 68 3e 20 20 54 79 70 65 20 20 20 20 3c 74  <th>  Type    <t
10410 68 3e 20 20 20 20 54 79 70 65 20 20 20 3c 74 68  h>    Type   <th
10420 3e 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a  > Conversion.**.
10430 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
10440 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
10450 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
10460 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
10470 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
10480 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
10490 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
104a0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
104b0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
104c0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
104d0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
104e0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
104f0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
10500 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
10510 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
10520 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
10530 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
10540 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
10550 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
10560 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
10570 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
10580 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
10590 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
105a0 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
105b0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
105c0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
105d0 74 64 3e 20 53 61 6d 65 20 61 73 20 66 6f 72 20  td> Same as for 
105e0 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
105f0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
10600 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
10610 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
10620 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74  rom float to int
10630 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
10640 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
10650 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
10660 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
10670 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
10680 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
10690 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
106a0 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41  td> Same as FLOA
106b0 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  T->TEXT.** <tr><
106c0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
106d0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
106e0 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   Use atoi().** <
106f0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
10700 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
10710 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a  <td> Use atof().
10720 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
10730 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
10740 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
10750 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
10760 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
10770 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
10780 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
10790 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   use atoi().** <
107a0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
107b0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
107c0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
107d0 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
107e0 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
107f0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
10800 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
10810 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
10820 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
10830 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
10840 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
10850 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
10860 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
10870 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
10880 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
10890 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
108a0 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
108b0 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
108c0 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
108d0 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
108e0 2a 2a 20 6f 6e 20 65 71 75 61 76 61 6c 65 6e 74  ** on equavalent
108f0 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
10900 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
10910 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
10920 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
10930 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
10940 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
10950 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
10960 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
10970 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
10980 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
10990 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
109a0 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
109b0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
109c0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
109d0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
109e0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
109f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
10a00 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
10a10 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
10a20 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
10a30 61 74 65 64 2e 20 0a 2a 2a 20 54 79 70 65 20 63  ated. .** Type c
10a40 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
10a50 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
10a60 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
10a70 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
10a80 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
10a90 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70  * <ul>.** <li><p
10aa0 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  >  The initial c
10ab0 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
10ac0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
10ad0 75 6d 6e 5f 74 65 78 74 28 29 20 0a 2a 2a 20 20  umn_text() .**  
10ae0 20 20 20 20 20 20 20 20 6f 72 20 73 71 6c 69 74          or sqlit
10af0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
10b00 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
10b10 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
10b20 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 20   might.**       
10b30 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
10b40 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
10b50 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  g.</p></li>.**.*
10b60 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69  * <li><p>  The i
10b70 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
10b80 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
10b90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
10ba0 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
10bb0 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
10bc0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
10bd0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
10be0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
10bf0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
10c00 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36         to UTF-16
10c10 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  .</p></li>.**.**
10c20 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e   <li><p>  The in
10c30 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
10c40 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
10c50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
10c60 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
10c70 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
10c80 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
10c90 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
10ca0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
10cb0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  verted.**       
10cc0 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 70 3e     to UTF-8.</p>
10cd0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
10ce0 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73  *.** Conversions
10cf0 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
10d00 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
10d10 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
10d20 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
10d30 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
10d40 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
10d50 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
10d60 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
10d70 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
10d80 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
10d90 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f  ointer points to
10da0 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
10db0 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
10dc0 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
10dd0 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
10de0 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
10df0 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
10e00 75 74 20 73 6f 6d 65 74 69 6d 65 20 69 74 20 69  ut sometime it i
10e10 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c  s.** not possibl
10e20 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
10e30 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
10e40 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
10e50 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ted.  .**.** The
10e60 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
10e70 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
10e80 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
10e90 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
10ea0 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
10eb0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
10ec0 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a  ys:.**.**  <ul>.
10ed0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
10ee0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
10ef0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
10f00 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
10f10 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
10f20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
10f30 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
10f40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
10f50 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
10f60 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
10f70 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
10f80 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
10f90 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
10fa0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a  </li>.**  </ul>.
10fb0 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
10fc0 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
10fd0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
10fe0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 73 71 6c  lumn_text(), sql
10ff0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
11000 28 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  (),.** or sqlite
11010 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
11020 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
11030 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f   the result into
11040 20 74 68 65 20 64 65 73 69 72 65 64 0a 2a 2a 20   the desired.** 
11050 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
11060 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
11070 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 20 73 71  mn_bytes() or sq
11080 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
11090 65 73 31 36 28 29 20 74 6f 0a 2a 2a 20 66 69 6e  es16() to.** fin
110a0 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
110b0 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
110c0 74 20 6d 69 78 20 63 61 6c 6c 20 74 6f 20 73 71  t mix call to sq
110d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
110e0 74 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  t() or.** sqlite
110f0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
11100 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
11110 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
11120 65 73 31 36 28 29 2e 20 20 41 6e 64 20 64 6f 20  es16().  And do 
11130 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c 73  not.** mix calls
11140 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
11150 6d 6e 5f 74 65 78 74 31 36 28 29 20 77 69 74 68  mn_text16() with
11160 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
11170 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
11180 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
11190 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
111a0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
111b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
111c0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
111d0 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
111e0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
111f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
11200 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
11210 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
11220 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
11230 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
11240 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
11250 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
11260 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
11270 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
11280 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
11290 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
112a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
112b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
112c0 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
112d0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
112e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
112f0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
11300 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
11310 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
11320 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
11330 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
11340 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
11350 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
11360 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
11370 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
11380 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
11390 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
113a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
113b0 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
113c0 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
113d0 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
113e0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
113f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
11400 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
11410 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
11420 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b  o delete a .** [
11430 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63  sqlite3_stmt | c
11440 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
11450 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68 65 20 73  ement]. If the s
11460 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
11470 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73  executed success
11480 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20 65 78  fully, or not ex
11490 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74  ecuted at all, t
114a0 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  hen SQLITE_OK is
114b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66   returned..** If
114c0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
114d0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c  e statement fail
114e0 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b  ed then an .** [
114f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65  SQLITE_ERROR | e
11500 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 53  rror code] or [S
11510 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
11520 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f   | extended erro
11530 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65  r code].** is re
11540 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54  turned. .**.** T
11550 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
11560 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
11570 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68   point during th
11580 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  e execution of t
11590 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
115a0 74 6d 74 20 7c 20 76 69 72 74 75 61 6c 20 6d 61  tmt | virtual ma
115b0 63 68 69 6e 65 5d 2e 20 20 49 66 20 74 68 65 20  chine].  If the 
115c0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
115d0 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70  has not .** comp
115e0 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20  leted execution 
115f0 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  when this routin
11600 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61  e is called, tha
11610 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63  t is like.** enc
11620 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72  ountering an err
11630 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65 72 72 75  or or an interru
11640 70 74 2e 20 20 28 53 65 65 20 5b 73 71 6c 69 74  pt.  (See [sqlit
11650 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 2e  e3_interrupt()].
11660 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65  ) .** Incomplete
11670 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20   updates may be 
11680 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20  rolled back and 
11690 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e  transactions can
116a0 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a 20 64 65 70  celled,  .** dep
116b0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69  ending on the ci
116c0 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64  rcumstances, and
116d0 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
116e0 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74 20  _ERROR | result 
116f0 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77  code] returned w
11700 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  ill be [SQLITE_A
11710 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  BORT]..*/.int sq
11720 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
11730 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
11740 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
11750 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
11760 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
11770 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
11780 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
11790 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
117a0 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
117b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 73 74 6d 74  .** [sqlite_stmt
117c0 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20   | compiled SQL 
117d0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
117e0 74 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74  t..** back to it
117f0 27 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  's initial state
11800 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
11810 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e  -executed..** An
11820 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
11830 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
11840 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
11850 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
11860 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
11870 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
11880 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
11890 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
118a0 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
118b0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
118c0 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
118d0 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2f  the bindings..*/
118e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
118f0 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
11900 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
11910 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
11920 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
11930 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
11940 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
11950 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  wo functions are
11960 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
11970 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
11980 67 72 65 67 61 74 65 73 0a 2a 2a 20 6f 72 20 74  gregates.** or t
11990 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
119a0 65 68 61 76 69 6f 72 20 6f 66 20 65 78 69 73 74  ehavior of exist
119b0 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
119c0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
119d0 20 20 54 68 65 0a 2a 2a 20 64 69 66 66 65 72 65    The.** differe
119e0 6e 63 65 20 6f 6e 6c 79 20 62 65 74 77 65 65 6e  nce only between
119f0 20 74 68 65 20 74 77 6f 20 69 73 20 74 68 61 74   the two is that
11a00 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
11a10 6d 65 74 65 72 2c 20 74 68 65 0a 2a 2a 20 6e 61  meter, the.** na
11a20 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61  me of the (scala
11a30 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  r) function or a
11a40 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63  ggregate, is enc
11a50 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f  oded in UTF-8 fo
11a60 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  r.** sqlite3_cre
11a70 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61  ate_function() a
11a80 6e 64 20 55 54 46 2d 31 36 20 66 6f 72 20 73 71  nd UTF-16 for sq
11a90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
11aa0 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ction16()..**.**
11ab0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
11ac0 65 6e 74 20 69 73 20 74 68 65 20 5b 73 71 6c 69  ent is the [sqli
11ad0 74 65 33 20 7c 20 64 61 74 61 62 61 73 65 20 68  te3 | database h
11ae0 61 6e 64 6c 65 5d 20 74 68 61 74 20 68 6f 6c 64  andle] that hold
11af0 73 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  s the.** SQL fun
11b00 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
11b10 74 65 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  te is to be adde
11b20 64 20 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 20  d or redefined. 
11b30 49 66 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 70  If a single.** p
11b40 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65  rogram uses more
11b50 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
11b60 73 65 20 68 61 6e 64 6c 65 20 69 6e 74 65 72 6e  se handle intern
11b70 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 0a 2a  ally, then SQL.*
11b80 2a 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  * functions or a
11b90 67 67 72 65 67 61 74 65 73 20 6d 75 73 74 20 62  ggregates must b
11ba0 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75  e added individu
11bb0 61 6c 6c 79 20 74 6f 20 65 61 63 68 20 64 61 74  ally to each dat
11bc0 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 20  abase.** handle 
11bd0 77 69 74 68 20 77 68 69 63 68 20 74 68 65 79 20  with which they 
11be0 77 69 6c 6c 20 62 65 20 75 73 65 64 2e 0a 2a 2a  will be used..**
11bf0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
11c00 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
11c10 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
11c20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
11c30 72 65 61 74 65 64 0a 2a 2a 20 6f 72 20 72 65 64  reated.** or red
11c40 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6c  efined..** The l
11c50 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
11c60 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
11c70 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75  255 bytes, exclu
11c80 73 69 76 65 20 6f 66 20 74 68 65 20 0a 2a 2a 20  sive of the .** 
11c90 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
11ca0 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
11cb0 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69  name length limi
11cc0 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e  t is in bytes, n
11cd0 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  ot.** characters
11ce0 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  .  Any attempt t
11cf0 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
11d00 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
11d10 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
11d20 65 73 75 6c 74 20 69 6e 20 61 6e 20 53 51 4c 49  esult in an SQLI
11d30 54 45 5f 45 52 52 4f 52 20 65 72 72 6f 72 2e 0a  TE_ERROR error..
11d40 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
11d50 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
11d60 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
11d70 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
11d80 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
11d90 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
11da0 2e 20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65  . If this parame
11db0 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ter is negative,
11dc0 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
11dd0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
11de0 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
11df0 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
11e00 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  guments..**.** T
11e10 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
11e20 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
11e30 70 65 63 69 66 69 65 73 20 77 68 61 74 20 0a 2a  pecifies what .*
11e40 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
11e50 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
11e60 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
11e70 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
11e80 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
11e90 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69    Any SQL functi
11ea0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
11eb0 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65  n should be able
11ec0 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b   to work.** work
11ed0 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46   with UTF-8, UTF
11ee0 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36  -16le, or UTF-16
11ef0 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d  be.  But some im
11f00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61  plementations ma
11f10 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66  y be.** more eff
11f20 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20  icient with one 
11f30 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e  encoding than an
11f40 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c  other.  It is al
11f50 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f  lowed to.** invo
11f60 6b 65 20 73 71 6c 69 74 65 5f 63 72 65 61 74 65  ke sqlite_create
11f70 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73  _function() or s
11f80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
11f90 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69  nction16() multi
11fa0 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
11fb0 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  h the same funct
11fc0 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66  ion but with dif
11fd0 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66  ferent values of
11fe0 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68   eTextRep..** Wh
11ff0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
12000 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
12010 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
12020 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
12030 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
12040 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
12050 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
12060 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
12070 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
12080 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e  * If there is on
12090 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c  ly a single impl
120a0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68  ementation which
120b0 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77   does not care w
120c0 68 61 74 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  hat.** text enco
120d0 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ding is used, th
120e0 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  en the fourth ar
120f0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
12100 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d  .** [SQLITE_ANY]
12110 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74  ..**.** The fift
12120 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
12130 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
12140 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
12150 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74  entation.** of t
12160 68 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  he function can 
12170 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
12180 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
12190 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 75 73 65  g.** [sqlite_use
121a0 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a  r_data()]..**.**
121b0 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69   The seventh, ei
121c0 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70  ghth and ninth p
121d0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
121e0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
121f0 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
12200 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
12210 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
12220 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
12230 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6f  QL.** function o
12240 72 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 73  r aggregate. A s
12250 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
12260 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
12270 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
12280 0a 2a 2a 20 74 68 65 20 78 46 75 6e 63 20 63 61  .** the xFunc ca
12290 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c  llback only, NUL
122a0 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c  L pointers shoul
122b0 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  d be passed as t
122c0 68 65 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  he xStep.** and 
122d0 78 46 69 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  xFinal parameter
122e0 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 20  s. An aggregate 
122f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
12300 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
12310 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53  ntation.** of xS
12320 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  tep and xFinal a
12330 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62  nd NULL should b
12340 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
12350 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e  nc. To delete an
12360 0a 2a 2a 20 65 78 69 73 74 69 6e 67 20 53 51 4c  .** existing SQL
12370 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
12380 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
12390 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  L for all three 
123a0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
123b0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  back..**.** It i
123c0 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
123d0 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
123e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
123f0 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
12400 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
12410 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
12420 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
12430 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
12440 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
12450 72 20 64 69 66 66 65 72 69 6e 67 20 70 65 72 66  r differing perf
12460 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
12470 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69  ings.  SQLite wi
12480 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
12490 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73  plementation mos
124a0 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
124b0 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
124c0 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
124d0 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  nction is used..
124e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
124f0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
12500 20 20 73 71 6c 69 74 65 33 20 2a 2c 0a 20 20 63    sqlite3 *,.  c
12510 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
12520 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
12530 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
12540 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20  tRep,.  void*,. 
12550 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
12560 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
12570 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
12580 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
12590 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
125a0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
125b0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
125c0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
125d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
125e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
125f0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
12600 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
12610 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
12620 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
12630 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
12640 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a  xtRep,.  void*,.
12650 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
12660 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
12670 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
12680 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
12690 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
126a0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
126b0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
126c0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
126d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
126e0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
126f0 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
12700 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ngs.**.** These 
12710 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
12720 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
12730 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
12740 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
12750 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
12760 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
12770 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12780 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
12790 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
127a0 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
127b0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
127c0 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
127d0 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
127e0 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
127f0 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
12800 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
12810 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12820 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
12830 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  5    /* sqlite3_
12840 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20  create_function 
12850 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
12860 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
12870 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
12880 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
12890 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
128a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
128b0 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f  Obsolete Functio
128c0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ns.**.** These f
128d0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c  unctions are all
128e0 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20   now obsolete.  
128f0 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
12900 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
12910 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
12920 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
12930 20 77 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   we continue to 
12940 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65  support.** these
12950 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77   functions.  How
12960 65 76 65 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f  ever, new develo
12970 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73 20 73  pment projects s
12980 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
12990 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
129a0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
129b0 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
129c0 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
129d0 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
129e0 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
129f0 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
12a00 20 79 6f 75 20 77 61 6e 74 20 74 68 65 79 20 64   you want they d
12a10 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  o..*/.int sqlite
12a20 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
12a30 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
12a40 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  t*);.int sqlite3
12a50 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
12a60 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c  _stmt*);.int sql
12a70 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
12a80 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
12a90 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
12aa0 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  mt*);.int sqlite
12ab0 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
12ac0 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  (void);.../*.** 
12ad0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
12ae0 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
12af0 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
12b00 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  s.**.** The C-la
12b10 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
12b20 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
12b30 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
12b40 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
12b50 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
12b60 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
12b70 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
12b80 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
12b90 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
12ba0 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a  r aggregate..**.
12bb0 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
12bc0 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
12bd0 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
12be0 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
12bf0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
12c00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
12c10 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
12c20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
12c30 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
12c40 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
12c50 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
12c60 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
12c70 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
12c80 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72  ..** The 4th par
12c90 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
12ca0 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
12cb0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
12cc0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
12cd0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
12ce0 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
12cf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
12d00 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
12d10 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
12d20 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
12d30 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
12d40 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
12d50 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
12d60 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
12d70 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
12d80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
12d90 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
12da0 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
12db0 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69  onding .** [sqli
12dc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 20  te3_column_blob 
12dd0 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
12de0 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20 65 78 63  _* routines] exc
12df0 65 70 74 20 74 68 61 74 20 0a 2a 2a 20 74 68 65  ept that .** the
12e00 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
12e10 20 61 20 73 69 6e 67 6c 65 20 5b 73 71 6c 69 74   a single [sqlit
12e20 65 33 5f 76 61 6c 75 65 2a 5d 20 70 6f 69 6e 74  e3_value*] point
12e30 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  er instead.** of
12e40 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d   an [sqlite3_stm
12e50 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
12e60 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
12e70 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
12e80 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
12e90 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
12ea0 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
12eb0 55 54 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF16 string.** 
12ec0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
12ed0 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te-order of the 
12ee0 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54  host machine.  T
12ef0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
12f00 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
12f10 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
12f20 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
12f30 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
12f40 74 20 55 54 46 31 36 20 73 74 72 69 6e 67 73 20  t UTF16 strings 
12f50 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
12f60 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
12f70 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
12f80 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12f90 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
12fa0 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
12fb0 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
12fc0 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
12fd0 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
12fe0 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
12ff0 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
13000 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
13010 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
13020 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
13030 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
13040 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
13050 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
13060 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
13070 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
13080 20 28 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 77 6f   (in order.** wo
13090 72 64 73 20 69 66 20 74 68 65 20 76 61 6c 75 65  rds if the value
130a0 20 69 73 20 6f 72 69 67 69 6e 61 6c 20 61 20 73   is original a s
130b0 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
130c0 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
130d0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 6f  ** then it is do
130e0 6e 65 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ne.  Otherwise n
130f0 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
13100 75 72 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b 53  urs.  The .** [S
13110 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
13120 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
13130 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
13140 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c  turned..**.** Pl
13150 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
13160 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
13170 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
13180 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  he pointer that.
13190 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 66  ** is returned f
131a0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
131b0 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  ue_blob()], [sql
131c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
131d0 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
131e0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
131f0 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69  )] can be invali
13200 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65  dated by a subse
13210 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  quent call to.**
13220 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
13230 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74  bytes()], [sqlit
13240 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
13250 28 29 5d 2c 20 5b 73 71 6c 69 74 65 5f 76 61 6c  ()], [sqlite_val
13260 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
13270 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
13280 5f 74 65 78 74 31 36 28 29 5d 2e 20 20 0a 2a 2f  _text16()].  .*/
13290 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
132a0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
132b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
132c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
132d0 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
132e0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
132f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
13300 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
13310 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  e*);.double sqli
13320 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
13330 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
13340 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
13350 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
13360 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 5f  value*);.sqlite_
13370 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
13380 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
13390 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
133a0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
133b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
133c0 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
133d0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
133e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
133f0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
13400 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
13410 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
13420 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
13430 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
13440 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
13450 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
13460 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
13470 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
13480 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
13490 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
134a0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
134b0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
134c0 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
134d0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
134e0 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
134f0 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54   Context.**.** T
13500 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
13510 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  n of aggregate S
13520 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
13530 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
13540 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73   allocate.** a s
13550 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f  tructure for sto
13560 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
13570 2e 20 20 54 68 65 20 66 69 72 73 74 20 74 69 6d  .  The first tim
13580 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  e this routine.*
13590 2a 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20  * is called for 
135a0 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
135b0 72 65 67 61 74 65 2c 20 61 20 6e 65 77 20 73 74  regate, a new st
135c0 72 75 63 74 75 72 65 20 6f 66 20 73 69 7a 65 20  ructure of size 
135d0 6e 42 79 74 65 73 0a 2a 2a 20 69 73 20 61 6c 6c  nBytes.** is all
135e0 6f 63 61 74 65 64 2c 20 7a 65 72 6f 65 64 2c 20  ocated, zeroed, 
135f0 61 6e 64 20 72 65 74 75 72 6e 65 64 2e 20 20 4f  and returned.  O
13600 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
13610 6c 73 20 28 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ls (for the.** s
13620 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 69 6e  ame aggregate in
13630 73 74 61 6e 63 65 29 20 74 68 65 20 73 61 6d 65  stance) the same
13640 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
13650 6e 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ned.  The implem
13660 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74  entation.** of t
13670 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61 6e  he aggregate can
13680 20 75 73 65 20 74 68 65 20 72 65 74 75 72 6e 65   use the returne
13690 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 63 75  d buffer to accu
136a0 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a  mulate data..**.
136b0 2a 2a 20 54 68 65 20 62 75 66 66 65 72 20 61 6c  ** The buffer al
136c0 6c 6f 63 61 74 65 64 20 69 73 20 66 72 65 65 64  located is freed
136d0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
136e0 79 20 53 51 4c 69 74 65 20 77 68 61 6e 20 74 68  y SQLite whan th
136f0 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71  e aggregate.** q
13700 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
13710 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
13720 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
13730 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
13740 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  e .** [sqlite3_c
13750 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
13760 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
13770 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
13780 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
13790 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f   the callback ro
137a0 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
137b0 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
137c0 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
137d0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
137e0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
137f0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
13800 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73  ext*, int nBytes
13810 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13820 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f  EF: User Data Fo
13830 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
13840 2a 20 54 68 65 20 70 55 73 65 72 44 61 74 61 20  * The pUserData 
13850 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
13860 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
13870 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
13880 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
13890 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
138a0 5d 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73  ] routines.** us
138b0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 75  ed to register u
138c0 73 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 69 73  ser functions is
138d0 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 0a 2a 2a   available to.**
138e0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
138f0 69 6f 6e 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ion of the funct
13900 69 6f 6e 20 75 73 69 6e 67 20 74 68 69 73 20 63  ion using this c
13910 61 6c 6c 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  all..*/.void *sq
13920 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
13930 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
13940 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13950 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
13960 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
13970 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
13980 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
13990 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
139a0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
139b0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
139c0 65 20 6d 65 74 61 2d 64 61 74 61 20 77 69 74 68  e meta-data with
139d0 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
139e0 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
139f0 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
13a00 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
13a10 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
13a20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
13a30 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
13a40 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
13a50 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
13a60 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
13a70 61 74 65 64 20 6d 65 74 61 2d 64 61 74 61 20 6d  ated meta-data m
13a80 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
13a90 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20   This may.** be 
13aa0 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
13ab0 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75  e, to add a regu
13ac0 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
13ad0 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a  atching scalar.*
13ae0 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  * function. The 
13af0 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e  compiled version
13b00 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20   of the regular 
13b10 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74  expression is st
13b20 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 2d  ored as.** meta-
13b30 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
13b40 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
13b50 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
13b60 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
13b70 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
13b80 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
13b90 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
13ba0 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
13bb0 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
13bc0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
13bd0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
13be0 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
13bf0 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
13c00 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
13c10 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
13c20 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
13c30 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  ocation..**.** T
13c40 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
13c50 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
13c60 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
13c70 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
13c80 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  -data.** associa
13c90 74 65 64 20 77 69 74 68 20 74 68 65 20 4e 74 68  ted with the Nth
13ca0 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 20   argument value 
13cb0 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 53  to the current S
13cc0 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  QL function.** c
13cd0 61 6c 6c 2c 20 77 68 65 72 65 20 4e 20 69 73 20  all, where N is 
13ce0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
13cf0 65 74 65 72 2e 20 49 66 20 6e 6f 20 6d 65 74 61  eter. If no meta
13d00 2d 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 73  -data has been s
13d10 65 74 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 76  et for.** that v
13d20 61 6c 75 65 2c 20 74 68 65 6e 20 61 20 4e 55 4c  alue, then a NUL
13d30 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
13d40 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
13d50 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
13d60 64 61 74 61 28 29 20 69 73 20 75 73 65 64 20 74  data() is used t
13d70 6f 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  o associate meta
13d80 2d 64 61 74 61 20 77 69 74 68 20 61 6e 20 53 51  -data with an SQ
13d90 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 72  L.** function ar
13da0 67 75 6d 65 6e 74 2e 20 54 68 65 20 74 68 69 72  gument. The thir
13db0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
13dc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
13dd0 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 74 6f 20  meta-data.** to 
13de0 62 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  be associated wi
13df0 74 68 20 74 68 65 20 4e 74 68 20 75 73 65 72 20  th the Nth user 
13e00 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
13e10 74 20 76 61 6c 75 65 2e 20 54 68 65 20 66 6f 75  t value. The fou
13e20 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rth.** parameter
13e30 20 73 70 65 63 69 66 69 65 73 20 61 20 64 65 73   specifies a des
13e40 74 72 75 63 74 6f 72 20 74 68 61 74 20 77 69 6c  tructor that wil
13e50 6c 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 20 74  l be called on t
13e60 68 65 20 6d 65 74 61 2d 0a 2a 2a 20 64 61 74 61  he meta-.** data
13e70 20 70 6f 69 6e 74 65 72 20 74 6f 20 72 65 6c 65   pointer to rele
13e80 61 73 65 20 69 74 20 77 68 65 6e 20 69 74 20 69  ase it when it i
13e90 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
13ea0 69 72 65 64 2e 20 49 66 20 74 68 65 20 0a 2a 2a  ired. If the .**
13eb0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 4e   destructor is N
13ec0 55 4c 4c 2c 20 69 74 20 69 73 20 6e 6f 74 20 69  ULL, it is not i
13ed0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  nvoked..**.** In
13ee0 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 2d   practice, meta-
13ef0 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
13f00 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
13f10 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
13f20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
13f30 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
13f40 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
13f50 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
13f60 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
13f70 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73  nd SQL variables
13f80 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
13f90 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
13fa0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
13fb0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
13fc0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
13fd0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
13fe0 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 76 6f  , int, void*, vo
13ff0 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
14000 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14010 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
14020 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
14030 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
14040 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
14050 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 66   special value f
14060 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
14070 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
14080 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
14090 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
140a0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
140b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
140c0 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64  ob()].  If the d
140d0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
140e0 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
140f0 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
14100 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
14110 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
14120 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
14130 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
14140 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
14150 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
14160 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51 4c 49  d.  The .** SQLI
14170 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
14180 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
14190 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
141a0 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
141b0 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
141c0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
141d0 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
141e0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
141f0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
14200 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
14210 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
14220 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
14230 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
14240 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
14250 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
14260 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
14270 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
14280 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
14290 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
142a0 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
142b0 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
142c0 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
142d0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
142e0 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
142f0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
14300 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
14310 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
14320 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
14330 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
14340 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
14350 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
14360 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
14370 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
14380 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
14390 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
143a0 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
143b0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
143c0 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
143d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
143e0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
143f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
14400 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
14410 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
14420 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
14430 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
14440 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
14450 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a 2a 20  ch like the .** 
14460 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
14470 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
14480 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 20 66  d_*] family of f
14490 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a 2a 2a  unctions used.**
144a0 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
144b0 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
144c0 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
144d0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
144e0 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73  fer to the.** [s
144f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
14500 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
14510 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  * documentation]
14520 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
14530 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
14540 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
14550 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
14560 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
14570 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
14580 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
14590 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
145a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
145b0 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
145c0 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 70 61 72  ion.  The.** par
145d0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
145e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
145f0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
14600 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
14610 69 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  is the text of a
14620 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
14630 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
14640 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
14650 28 29 20 63 61 75 73 65 20 74 68 65 20 66 75 6e  () cause the fun
14660 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
14670 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 72 6f 77  tion.** to throw
14680 20 61 6e 64 20 65 72 72 6f 72 20 69 6e 64 69 63   and error indic
14690 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
146a0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
146b0 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65 70  o long.** to rep
146c0 72 65 73 65 6e 74 2e 0a 2a 2f 0a 76 6f 69 64 20  resent..*/.void 
146d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
146e0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
146f0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
14700 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
14710 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
14720 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
14730 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ble(sqlite3_cont
14740 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76  ext*, double);.v
14750 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
14760 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
14770 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
14780 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f   char*, int);.vo
14790 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
147a0 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
147b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
147c0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  t void*, int);.v
147d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
147e0 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
147f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
14800 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
14810 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74  result_int(sqlit
14820 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
14830 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
14840 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c  result_int64(sql
14850 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
14860 71 6c 69 74 65 5f 69 6e 74 36 34 29 3b 0a 76 6f  qlite_int64);.vo
14870 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
14880 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
14890 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
148a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
148b0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
148c0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
148d0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
148e0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
148f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
14900 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
14910 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
14920 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
14930 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
14940 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
14950 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
14960 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
14970 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
14980 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
14990 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
149a0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
149b0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
149c0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
149d0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
149e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
149f0 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
14a00 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
14a10 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
14a20 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
14a30 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
14a40 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
14a50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
14a60 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
14a70 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a  ing Sequences.**
14a80 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
14a90 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  ons are used to 
14aa0 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  add new collatio
14ab0 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74  n sequences to t
14ac0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d  he.** [sqlite3*]
14ad0 20 68 61 6e 64 6c 65 20 73 70 65 63 69 66 69 65   handle specifie
14ae0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
14af0 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20  rgument. .**.** 
14b00 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
14b10 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
14b20 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66  quence is specif
14b30 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73  ied as a UTF-8 s
14b40 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
14b50 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
14b60 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
14b70 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
14b80 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
14b90 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
14ba0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
14bb0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
14bc0 29 2e 20 20 49 6e 20 61 6c 6c 20 63 61 73 65 73  ).  In all cases
14bd0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20  .** the name is 
14be0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
14bf0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
14c00 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
14c10 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
14c20 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20   must be one of 
14c30 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53  the constants [S
14c40 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
14c50 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
14c60 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
14c70 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6BE], indicating
14c80 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73   that the user-s
14c90 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69  upplied.** routi
14ca0 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65  ne expects to be
14cb0 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73   passed pointers
14cc0 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f   to strings enco
14cd0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c  ded using UTF-8,
14ce0 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
14cf0 65 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d  e-endian or UTF-
14d00 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65  16 big-endian re
14d10 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
14d20 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
14d30 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64  he user supplied
14d40 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
14d50 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
14d60 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ifth.** argument
14d70 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c  . If it is NULL,
14d80 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d   this is the sam
14d90 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68  e as deleting th
14da0 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
14db0 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74  equence (so that
14dc0 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63   SQLite cannot c
14dd0 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e  all it anymore).
14de0 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 75   Each time the u
14df0 73 65 72 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ser.** supplied 
14e00 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
14e10 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65  ked, it is passe
14e20 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
14e30 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 0a  void* passed as.
14e40 2a 2a 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  ** the fourth ar
14e50 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
14e60 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
14e70 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  on() or.** sqlit
14e80 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
14e90 69 6f 6e 31 36 28 29 20 61 73 20 69 74 73 20 66  ion16() as its f
14ea0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
14eb0 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  **.** The remain
14ec0 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ing arguments to
14ed0 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69   the user-suppli
14ee0 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74  ed routine are t
14ef0 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65  wo strings,.** e
14f00 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20  ach represented 
14f10 62 79 20 61 20 5b 6c 65 6e 67 74 68 2c 20 64 61  by a [length, da
14f20 74 61 5d 20 70 61 69 72 20 61 6e 64 20 65 6e 63  ta] pair and enc
14f30 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f  oded in the enco
14f40 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73  ding.** that was
14f50 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
14f60 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68  hird argument wh
14f70 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
14f80 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a   sequence was.**
14f90 20 72 65 67 69 73 74 65 72 65 64 2e 20 54 68 65   registered. The
14fa0 20 75 73 65 72 20 72 6f 75 74 69 6e 65 20 73 68   user routine sh
14fb0 6f 75 6c 64 20 72 65 74 75 72 6e 20 6e 65 67 61  ould return nega
14fc0 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f  tive, zero or po
14fd0 73 69 74 69 76 65 20 69 66 0a 2a 2a 20 74 68 65  sitive if.** the
14fe0 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
14ff0 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61   less than, equa
15000 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
15010 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
15020 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e  .** string. i.e.
15030 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49   (STRING1 - STRI
15040 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NG2)..**.** The 
15050 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
15060 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f  ollation_v2() wo
15070 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
15080 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
15090 6e 28 29 0a 2a 2a 20 65 78 63 61 70 74 20 74 68  n().** excapt th
150a0 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65  at it takes an e
150b0 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68  xtra argument wh
150c0 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63  ich is a destruc
150d0 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63  tor for.** the c
150e0 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  ollation.  The d
150f0 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
15100 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c  led when the col
15110 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73  lation is.** des
15120 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61  troyed and is pa
15130 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74  ssed a copy of t
15140 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
15150 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  ter void* pointe
15160 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  r.** of the 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 5f 76 32 28 29 2e 20 20 43 6f 6c 6c  tion_v2().  Coll
15190 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72  ations are destr
151a0 6f 79 65 64 20 77 68 65 6e 0a 2a 2a 20 74 68 65  oyed when.** the
151b0 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
151c0 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20   by later calls 
151d0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  to the collation
151e0 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
151f0 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74  ons.** or when t
15200 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61  he [sqlite3*] da
15210 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69 73  tabase handle is
15220 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73   closed using [s
15230 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
15240 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
15250 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
15260 69 6f 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  ion_v2() interfa
15270 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74  ce is experiment
15280 61 6c 20 61 6e 64 0a 2a 2a 20 73 75 62 6a 65 63  al and.** subjec
15290 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
152a0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20  uture releases. 
152b0 20 54 68 65 20 6f 74 68 65 72 20 63 6f 6c 6c 61   The other colla
152c0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 0a 2a 2a  tion creation.**
152d0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 73   functions are s
152e0 74 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  table..*/.int sq
152f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
15300 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
15310 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
15320 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
15330 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
15340 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
15350 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
15360 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
15370 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
15380 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
15390 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
153a0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
153b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
153c0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
153d0 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
153e0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
153f0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
15400 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
15410 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
15420 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
15430 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
15440 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
15450 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
15460 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
15470 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
15480 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
15490 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
154a0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
154b0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
154c0 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
154d0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
154e0 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
154f0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 6f 20  lbacks.**.** To 
15500 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20  avoid having to 
15510 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c  register all col
15520 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
15530 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61   before a databa
15540 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  se.** can be use
15550 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c  d, a single call
15560 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61  back function ma
15570 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
15580 77 69 74 68 20 74 68 65 0a 2a 2a 20 64 61 74 61  with the.** data
15590 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 62  base handle to b
155a0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65  e called wheneve
155b0 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
155c0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
155d0 65 20 69 73 0a 2a 2a 20 72 65 71 75 69 72 65 64  e is.** required
155e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
155f0 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
15600 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
15610 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
15620 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
15630 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
15640 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
15650 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
15660 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
15670 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
15680 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
15690 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
156a0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
156b0 69 73 20 75 73 65 64 2c 20 74 68 65 20 6e 61 6d  is used, the nam
156c0 65 73 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64  es.** are passed
156d0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
156e0 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
156f0 65 20 6f 72 64 65 72 2e 20 41 20 63 61 6c 6c 20  e order. A call 
15700 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e  to either.** fun
15710 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61  ction replaces a
15720 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c  ny existing call
15730 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  back..**.** When
15740 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
15750 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
15760 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
15770 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
15780 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
15790 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
157a0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
157b0 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
157c0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
157d0 65 64 65 64 31 36 28 29 2e 20 54 68 65 20 73 65  eded16(). The se
157e0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
157f0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
15800 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 74 68 69   handle. The thi
15810 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
15820 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
15830 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
15840 31 36 42 45 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51  16BE], or.** [SQ
15850 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
15860 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
15870 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
15880 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
15890 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
158a0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
158b0 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
158c0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
158d0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
158e0 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
158f0 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20  sequence..**.** 
15900 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
15910 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
15920 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
15930 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
15940 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
15950 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
15960 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
15970 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
15980 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
15990 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
159a0 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  on_v2()]..*/.int
159b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
159c0 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
159d0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
159e0 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
159f0 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
15a00 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
15a10 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  ar*).);.int sqli
15a20 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
15a30 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65  eded16(.  sqlite
15a40 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  3*, .  void*,.  
15a50 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
15a60 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
15a70 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
15a80 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  .);../*.** Speci
15a90 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
15aa0 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
15ab0 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
15ac0 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
15ad0 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
15ae0 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
15af0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
15b00 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
15b10 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
15b20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
15b30 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
15b40 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
15b50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
15b60 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
15b70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
15b80 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
15b90 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
15ba0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
15bb0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
15bc0 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
15bd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20  ;../*.** Change 
15be0 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70  the key on an op
15bf0 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66  en database.  If
15c00 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
15c10 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20  abase is not.** 
15c20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20  encrypted, this 
15c30 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63  routine will enc
15c40 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65  rypt it.  If pNe
15c50 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c  w==0 or nNew==0,
15c60 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
15c70 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a   is decrypted..*
15c80 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
15c90 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
15ca0 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
15cb0 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
15cc0 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
15cd0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
15ce0 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
15cf0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
15d00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
15d10 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
15d20 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
15d30 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
15d40 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
15d50 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
15d60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
15d70 45 46 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65  EF:  Suspend Exe
15d80 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
15d90 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68  rt Time.**.** Th
15da0 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
15db0 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
15dc0 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
15dd0 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 61 20   execution.** a 
15de0 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
15df0 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
15e00 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
15e10 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
15e20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
15e30 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
15e40 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
15e50 20 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73   with .** millis
15e60 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
15e70 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
15e80 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
15e90 6e 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74  nded up to .** t
15ea0 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e  he nearest secon
15eb0 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  d. The number of
15ec0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
15ed0 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20   sleep actually 
15ee0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
15ef0 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
15f00 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
15f10 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
15f20 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
15f30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15f40 20 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f    Name Of The Fo
15f50 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
15f60 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a  porary Files.**.
15f70 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61  ** If this globa
15f80 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
15f90 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
15fa0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
15fb0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
15fc0 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 61 2e 20  a folder (a.ka. 
15fd0 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
15fe0 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
15ff0 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
16000 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  by SQLite will b
16010 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
16020 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20   directory.  If 
16030 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
16040 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
16050 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 64 6f  , then SQLite do
16060 65 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20  es a search for 
16070 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 74  an appropriate t
16080 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66 69 6c 65  emporary.** file
16090 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
160a0 2a 20 4f 6e 63 65 20 5b 73 71 6c 69 74 65 33 5f  * Once [sqlite3_
160b0 6f 70 65 6e 28 29 5d 20 68 61 73 20 62 65 65 6e  open()] has been
160c0 20 63 61 6c 6c 65 64 2c 20 63 68 61 6e 67 69 6e   called, changin
160d0 67 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  g this variable 
160e0 77 69 6c 6c 0a 2a 2a 20 69 6e 76 61 6c 69 64 61  will.** invalida
160f0 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  te the current t
16100 65 6d 70 6f 72 61 72 79 20 64 61 74 61 62 61 73  emporary databas
16110 65 2c 20 69 66 20 61 6e 79 2e 20 20 47 65 6e 65  e, if any.  Gene
16120 72 61 6c 6c 79 20 73 70 65 61 6b 69 6e 67 2c 0a  rally speaking,.
16130 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66  ** it is not saf
16140 65 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 69 73  e to invoke this
16150 20 72 6f 75 74 69 6e 65 20 61 66 74 65 72 20 5b   routine after [
16160 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
16170 68 61 73 0a 2a 2a 20 62 65 65 6e 20 63 61 6c 6c  has.** been call
16180 65 64 2e 0a 2a 2f 0a 65 78 74 65 72 6e 20 63 68  ed..*/.extern ch
16190 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70  ar *sqlite3_temp
161a0 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a  _directory;../*.
161b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 54 65  ** CAPI3REF:  Te
161c0 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 65  st To See If The
161d0 20 44 61 74 61 62 73 65 20 49 73 20 49 6e 20 41   Databse Is In A
161e0 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a  uto-Commit Mode.
161f0 2a 2a 0a 2a 2a 20 54 65 73 74 20 74 6f 20 73 65  **.** Test to se
16200 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
16210 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
16220 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 61  nnection is in a
16230 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 6d 6f 64  utocommit.** mod
16240 65 2e 20 20 52 65 74 75 72 6e 20 54 52 55 45 20  e.  Return TRUE 
16250 69 66 20 69 74 20 69 73 20 61 6e 64 20 46 41 4c  if it is and FAL
16260 53 45 20 69 66 20 6e 6f 74 2e 20 20 41 75 74 6f  SE if not.  Auto
16270 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f  commit mode is o
16280 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2e  n.** by default.
16290 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 69 73 20    Autocommit is 
162a0 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 42 45  disabled by a BE
162b0 47 49 4e 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  GIN statement an
162c0 64 20 72 65 65 6e 61 62 6c 65 64 0a 2a 2a 20 62  d reenabled.** b
162d0 79 20 74 68 65 20 6e 65 78 74 20 43 4f 4d 4d 49  y the next COMMI
162e0 54 20 6f 72 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a  T or ROLLBACK..*
162f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
16300 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
16310 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
16320 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20 54  API3REF:  Find T
16330 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
16340 6c 65 20 41 73 73 6f 63 69 61 74 65 64 20 57 69  le Associated Wi
16350 74 68 20 41 20 50 72 65 70 61 72 65 64 20 53 74  th A Prepared St
16360 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 52 65  atement.**.** Re
16370 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  turn the [sqlite
16380 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e  3*] database han
16390 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a 2a  dle to which a.*
163a0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
163b0 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
163c0 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a  ment] belongs..*
163d0 2a 20 54 68 69 73 20 69 73 20 74 68 65 20 73 61  * This is the sa
163e0 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  me database hand
163f0 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 74  le that was.** t
16400 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16410 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
16420 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
16430 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a  or its variants.
16440 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73 65 64  ** that was used
16450 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 20 73   to create the s
16460 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
16470 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a  first place..*/.
16480 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
16490 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
164a0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a  e3_stmt*);.../*.
164b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
164c0 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b  mit And Rollback
164d0 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
164e0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68  llbacks.**.** Th
164f0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
16500 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
16510 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 62  k functions to b
16520 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
16530 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
16540 0a 2a 2a 20 69 73 20 63 6f 6d 6d 69 74 74 65 64  .** is committed
16550 20 6f 72 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e   or rolled back.
16560 20 20 54 68 65 20 70 41 72 67 20 61 72 67 75 6d    The pArg argum
16570 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68  ent is passed th
16580 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65 20  rough.** to the 
16590 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74 68  callback.  If th
165a0 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
165b0 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
165c0 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e 73  tion .** returns
165d0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
165e0 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f  the commit is co
165f0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
16600 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49  ollback..**.** I
16610 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69  f another functi
16620 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c  on was previousl
16630 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74  y registered, it
16640 73 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20  s pArg value is 
16650 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68  returned..** Oth
16660 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72  erwise NULL is r
16670 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  eturned..**.** R
16680 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c  egistering a NUL
16690 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  L function disab
166a0 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  les the callback
166b0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20  ..**.** For the 
166c0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
166d0 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74   API, a transact
166e0 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68  ion is said to h
166f0 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c  ave been .** rol
16700 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65  led back if an e
16710 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43  xplicit "ROLLBAC
16720 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  K" statement is 
16730 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20  executed, or.** 
16740 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73  an error or cons
16750 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e  traint causes an
16760 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61   implicit rollba
16770 63 6b 20 74 6f 20 6f 63 63 75 72 2e 20 54 68 65  ck to occur. The
16780 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73   .** callback is
16790 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
167a0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
167b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
167c0 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 62 65  olled.** back be
167d0 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61  cause the databa
167e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
167f0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
16800 68 65 73 65 20 61 72 65 20 65 78 70 65 72 69 6d  hese are experim
16810 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
16820 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65 63 74   and are subject
16830 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76   to change..*/.v
16840 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
16850 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
16860 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
16870 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
16880 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
16890 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
168a0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
168b0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
168c0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
168d0 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
168e0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
168f0 2a 2a 20 52 65 67 69 73 74 65 72 20 61 20 63 61  ** Register a ca
16900 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
16910 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73  with the databas
16920 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65  e connection ide
16930 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ntified by the .
16940 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  ** first argumen
16950 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  t to be invoked 
16960 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69  whenever a row i
16970 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
16980 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
16990 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
169a0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
169b0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
169c0 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  unction for the 
169d0 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61 73  same .** databas
169e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
169f0 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a  overridden..**.*
16a00 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
16a10 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
16a20 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69  er to the functi
16a30 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65  on to invoke whe
16a40 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75  n a .** row is u
16a50 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
16a60 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 54 68 65   or deleted. The
16a70 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16a80 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
16a90 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20  is.** a copy of 
16aa0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
16ab0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70  nt to sqlite3_up
16ac0 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 20 54 68 65  date_hook(). The
16ad0 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b   second callback
16ae0 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73   .** argument is
16af0 20 6f 6e 65 20 6f 66 20 53 51 4c 49 54 45 5f 49   one of SQLITE_I
16b00 4e 53 45 52 54 2c 20 53 51 4c 49 54 45 5f 44 45  NSERT, SQLITE_DE
16b10 4c 45 54 45 20 6f 72 20 53 51 4c 49 54 45 5f 55  LETE or SQLITE_U
16b20 50 44 41 54 45 2c 20 64 65 70 65 6e 64 69 6e 67  PDATE, depending
16b30 0a 2a 2a 20 6f 6e 20 74 68 65 20 6f 70 65 72 61  .** on the opera
16b40 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64  tion that caused
16b50 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f   the callback to
16b60 20 62 65 20 69 6e 76 6f 6b 65 64 2e 20 54 68 65   be invoked. The
16b70 20 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66   third and .** f
16b80 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
16b90 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
16ba0 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
16bb0 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
16bc0 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e   and .** table n
16bd0 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
16be0 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
16bf0 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62   The final callb
16c00 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
16c10 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64 20 6f   .** the rowid o
16c20 66 20 74 68 65 20 72 6f 77 2e 20 49 6e 20 74 68  f the row. In th
16c30 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64  e case of an upd
16c40 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65  ate, this is the
16c50 20 72 6f 77 69 64 20 61 66 74 65 72 20 0a 2a 2a   rowid after .**
16c60 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65   the update take
16c70 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  s place..**.** T
16c80 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
16c90 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68  s not invoked wh
16ca0 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74  en internal syst
16cb0 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a  em tables are.**
16cc0 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20   modified (i.e. 
16cd0 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e  sqlite_master an
16ce0 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63  d sqlite_sequenc
16cf0 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  e)..**.** If ano
16d00 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61  ther function wa
16d10 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  s previously reg
16d20 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72  istered, its pAr
16d30 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  g value is retur
16d40 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  ned..** Otherwis
16d50 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  e NULL is return
16d60 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ed..*/.void *sql
16d70 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
16d80 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
16d90 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c   void(*)(void *,
16da0 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20  int ,char const 
16db0 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73  *,char const *,s
16dc0 71 6c 69 74 65 5f 69 6e 74 36 34 29 2c 0a 20 20  qlite_int64),.  
16dd0 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
16de0 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c  CAPI3REF:  Enabl
16df0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61  e Or Disable Sha
16e00 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a  red Pager Cache.
16e10 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
16e20 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
16e30 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69  sables the shari
16e40 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ng of the databa
16e50 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20  se cache.** and 
16e60 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75  schema data stru
16e70 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 63  ctures between c
16e80 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20 74 68  onnections to th
16e90 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e  e same database.
16ea0 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73 20 65  .** Sharing is e
16eb0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  nabled if the ar
16ec0 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 20 61  gument is true a
16ed0 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74  nd disabled if t
16ee0 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69  he argument.** i
16ef0 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43  s false..**.** C
16f00 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20  ache sharing is 
16f10 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61  enabled and disa
16f20 62 6c 65 64 20 6f 6e 20 61 20 74 68 72 65 61 64  bled on a thread
16f30 2d 62 79 2d 74 68 72 65 61 64 20 62 61 73 69 73  -by-thread basis
16f40 2e 0a 2a 2a 20 45 61 63 68 20 63 61 6c 6c 20 74  ..** Each call t
16f50 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 65  o this routine e
16f60 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
16f70 65 73 20 63 61 63 68 65 20 73 68 61 72 69 6e 67  es cache sharing
16f80 20 6f 6e 6c 79 20 66 6f 72 0a 2a 2a 20 63 6f 6e   only for.** con
16f90 6e 65 63 74 69 6f 6e 73 20 63 72 65 61 74 65 64  nections created
16fa0 20 69 6e 20 74 68 65 20 73 61 6d 65 20 74 68 72   in the same thr
16fb0 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 69  ead in which thi
16fc0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  s routine is cal
16fd0 6c 65 64 2e 0a 2a 2a 20 54 68 65 72 65 20 69 73  led..** There is
16fe0 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f   no mechanism fo
16ff0 72 20 73 68 61 72 69 6e 67 20 63 61 63 68 65 20  r sharing cache 
17000 62 65 74 77 65 65 6e 20 64 61 74 61 62 61 73 65  between database
17010 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
17020 72 75 6e 6e 69 6e 67 20 69 6e 20 64 69 66 66 65  running in diffe
17030 72 65 6e 74 20 74 68 72 65 61 64 73 2e 0a 2a 2a  rent threads..**
17040 0a 2a 2a 20 53 68 61 72 69 6e 67 20 6d 75 73 74  .** Sharing must
17050 20 62 65 20 64 69 73 61 62 6c 65 64 20 70 72 69   be disabled pri
17060 6f 72 20 74 6f 20 73 68 75 74 74 69 6e 67 20 64  or to shutting d
17070 6f 77 6e 20 61 20 74 68 72 65 61 64 20 6f 72 20  own a thread or 
17080 65 6c 73 65 0a 2a 2a 20 74 68 65 20 74 68 72 65  else.** the thre
17090 61 64 20 77 69 6c 6c 20 6c 65 61 6b 20 6d 65 6d  ad will leak mem
170a0 6f 72 79 2e 20 20 43 61 6c 6c 20 74 68 69 73 20  ory.  Call this 
170b0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
170c0 61 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 30  argument of.** 0
170d0 20 74 6f 20 74 75 72 6e 20 6f 66 66 20 73 68 61   to turn off sha
170e0 72 69 6e 67 2e 20 20 4f 72 20 75 73 65 20 74 68  ring.  Or use th
170f0 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  e sqlite3_thread
17100 5f 63 6c 65 61 6e 75 70 28 29 20 41 50 49 2e 0a  _cleanup() API..
17110 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
17120 6e 65 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 63  ne must not be c
17130 61 6c 6c 65 64 20 77 68 65 6e 20 61 6e 79 20 64  alled when any d
17140 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17150 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 63 74 69 76  ons.** are activ
17160 65 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  e in the current
17170 20 74 68 72 65 61 64 2e 20 20 45 6e 61 62 6c 69   thread.  Enabli
17180 6e 67 20 6f 72 20 64 69 73 61 62 6c 69 6e 67 20  ng or disabling 
17190 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
171a0 77 68 69 6c 65 20 74 68 65 72 65 20 61 72 65 20  while there are 
171b0 61 63 74 69 76 65 20 64 61 74 61 62 61 73 65 20  active database 
171c0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 77 69 6c 6c  connections will
171d0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 6d 65   result.** in me
171e0 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2e  mory corruption.
171f0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
17200 73 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  shared cache is 
17210 65 6e 61 62 6c 65 64 2c 20 74 68 65 0a 2a 2a 20  enabled, the.** 
17220 66 6f 6c 6c 6f 77 69 6e 67 20 72 6f 75 74 69 6e  following routin
17230 65 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20 62  es must always b
17240 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
17250 65 20 73 61 6d 65 20 74 68 72 65 61 64 3a 0a 2a  e same thread:.*
17260 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  * [sqlite3_open(
17270 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  )], [sqlite3_pre
17280 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
17290 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 0a 2a 2a  ite3_step()],.**
172a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
172b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  )], [sqlite3_fin
172c0 61 6c 69 7a 65 28 29 5d 2c 20 61 6e 64 20 5b 73  alize()], and [s
172d0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
172e0 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 75 65 20  .** This is due 
172f0 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
17300 20 74 68 65 20 73 68 61 72 65 64 20 63 61 63 68   the shared cach
17310 65 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 0a 2a  e makes use of.*
17320 2a 20 74 68 72 65 61 64 2d 73 70 65 63 69 66 69  * thread-specifi
17330 63 20 73 74 6f 72 61 67 65 20 73 6f 20 74 68 61  c storage so tha
17340 74 20 69 74 20 77 69 6c 6c 20 62 65 20 61 76 61  t it will be ava
17350 69 6c 61 62 6c 65 20 66 6f 72 20 73 68 61 72 69  ilable for shari
17360 6e 67 0a 2a 2a 20 77 69 74 68 20 6f 74 68 65 72  ng.** with other
17370 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a   connections..**
17380 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c  .** Virtual tabl
17390 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65  es cannot be use
173a0 64 20 77 69 74 68 20 61 20 73 68 61 72 65 64 20  d with a shared 
173b0 63 61 63 68 65 2e 20 20 57 68 65 6e 20 73 68 61  cache.  When sha
173c0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
173d0 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 73 71 6c  enabled, the sql
173e0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
173f0 6c 65 28 29 20 41 50 49 20 75 73 65 64 20 74 6f  le() API used to
17400 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72   register.** vir
17410 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c  tual tables will
17420 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61   always return a
17430 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  n error..**.** T
17440 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
17450 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
17460 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20  if shared cache 
17470 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f  was.** enabled o
17480 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 63 65  r disabled succe
17490 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 53 51  ssfully.  An [SQ
174a0 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72  LITE_ERROR | err
174b0 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72  or code].** is r
174c0 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73  eturned otherwis
174d0 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20  e..**.** Shared 
174e0 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65  cache is disable
174f0 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72  d by default for
17500 20 62 61 63 6b 77 61 72 64 20 63 6f 6d 70 61 74   backward compat
17510 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
17520 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
17530 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29  hared_cache(int)
17540 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17550 46 3a 20 20 41 74 74 65 6d 70 74 20 54 6f 20 46  F:  Attempt To F
17560 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a  ree Heap Memory.
17570 2a 2a 0a 2a 2a 20 41 74 74 65 6d 70 74 20 74 6f  **.** Attempt to
17580 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66   free N bytes of
17590 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20   heap memory by 
175a0 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e  deallocating non
175b0 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 6d 65  -essential.** me
175c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
175d0 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74   held by the dat
175e0 61 62 61 73 65 20 6c 69 62 72 61 72 79 20 28 65  abase library (e
175f0 78 61 6d 70 6c 65 3a 20 6d 65 6d 6f 72 79 20 0a  xample: memory .
17600 2a 2a 20 75 73 65 64 20 74 6f 20 63 61 63 68 65  ** used to cache
17610 20 64 61 74 61 62 61 73 65 20 70 61 67 65 73 20   database pages 
17620 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  to improve perfo
17630 72 6d 61 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 54  rmance)..**.** T
17640 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
17650 6e 6f 74 20 61 20 70 61 72 74 20 6f 66 20 73 74  not a part of st
17660 61 6e 64 61 72 64 20 62 75 69 6c 64 73 2e 20 20  andard builds.  
17670 49 74 20 69 73 20 6f 6e 6c 79 20 63 72 65 61 74  It is only creat
17680 65 64 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  ed.** if SQLite 
17690 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
176a0 20 74 68 65 20 53 51 4c 49 54 45 5f 45 4e 41 42   the SQLITE_ENAB
176b0 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
176c0 4d 45 4e 54 20 6d 61 63 72 6f 2e 0a 2a 2f 0a 69  MENT macro..*/.i
176d0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  nt sqlite3_relea
176e0 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a  se_memory(int);.
176f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17700 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74    Impose A Limit
17710 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a   On Heap Size.**
17720 0a 2a 2a 20 50 6c 61 63 65 20 61 20 22 73 6f 66  .** Place a "sof
17730 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20  t" limit on the 
17740 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
17750 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
17760 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  e allocated by.*
17770 2a 20 53 51 4c 69 74 65 20 77 69 74 68 69 6e 20  * SQLite within 
17780 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
17790 61 64 2e 20 49 66 20 61 6e 20 69 6e 74 65 72 6e  ad. If an intern
177a0 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  al allocation is
177b0 20 72 65 71 75 65 73 74 65 64 20 0a 2a 2a 20 74   requested .** t
177c0 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64  hat would exceed
177d0 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6c   the specified l
177e0 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72  imit, [sqlite3_r
177f0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
17800 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 6f   is invoked.** o
17810 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
17820 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65   to free up some
17830 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 74 68   space before th
17840 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  e allocation is 
17850 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  made..**.** The 
17860 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20  limit is called 
17870 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20  "soft", because 
17880 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  if [sqlite3_rele
17890 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 63 61  ase_memory()] ca
178a0 6e 6e 6f 74 20 66 72 65 65 0a 2a 2a 20 73 75 66  nnot free.** suf
178b0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74  ficient memory t
178c0 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69  o prevent the li
178d0 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65  mit from being e
178e0 78 63 65 65 64 65 64 2c 20 74 68 65 20 6d 65 6d  xceeded, the mem
178f0 6f 72 79 20 69 73 0a 2a 2a 20 61 6c 6c 6f 63 61  ory is.** alloca
17900 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74  ted anyway and t
17910 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  he current opera
17920 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a  tion proceeds..*
17930 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 73 68  *.** Prior to sh
17940 75 74 74 69 6e 67 20 64 6f 77 6e 20 61 20 74 68  utting down a th
17950 72 65 61 64 20 73 71 6c 69 74 65 33 5f 73 6f 66  read sqlite3_sof
17960 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 6d  t_heap_limit() m
17970 75 73 74 20 62 65 20 73 65 74 20 74 6f 20 0a 2a  ust be set to .*
17980 2a 20 7a 65 72 6f 20 28 74 68 65 20 64 65 66 61  * zero (the defa
17990 75 6c 74 29 20 6f 72 20 65 6c 73 65 20 74 68 65  ult) or else the
179a0 20 74 68 72 65 61 64 20 77 69 6c 6c 20 6c 65 61   thread will lea
179b0 6b 20 6d 65 6d 6f 72 79 2e 20 41 6c 74 65 72 6e  k memory. Altern
179c0 61 74 69 76 65 6c 79 2c 20 75 73 65 0a 2a 2a 20  atively, use.** 
179d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  the [sqlite3_thr
179e0 65 61 64 5f 63 6c 65 61 6e 75 70 28 29 5d 20 41  ead_cleanup()] A
179f0 50 49 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61  PI..**.** A nega
17a00 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c  tive or zero val
17a10 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74  ue for N means t
17a20 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hat there is no 
17a30 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
17a40 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
17a50 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
17a60 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63  ] will only be c
17a70 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72  alled when memor
17a80 79 20 69 73 20 65 78 68 61 75 73 65 64 2e 0a 2a  y is exhaused..*
17a90 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  * The default va
17aa0 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74  lue for the soft
17ab0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a   heap limit is z
17ac0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ero..**.** SQLit
17ad0 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65  e makes a best e
17ae0 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74  ffort to honor t
17af0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
17b00 69 74 2e 20 20 42 75 74 20 69 66 20 69 74 0a 2a  it.  But if it.*
17b10 2a 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 72  * is unable to r
17b20 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75 73 61  educe memory usa
17b30 67 65 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66  ge below the sof
17b40 74 20 6c 69 6d 69 74 2c 20 65 78 65 63 75 74 69  t limit, executi
17b50 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69  on will.** conti
17b60 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f  nue without erro
17b70 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f  r or notificatio
17b80 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79 20  n.  This is why 
17b90 74 68 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a 2a  the limit is .**
17ba0 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22   called a "soft"
17bb0 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61   limit.  It is a
17bc0 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a  dvisory only..**
17bd0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
17be0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
17bf0 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
17c00 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
17c10 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
17c20 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
17c30 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 20 6f 70 74  Y_MANAGEMENT opt
17c40 69 6f 6e 20 73 65 74 2e 0a 2a 2a 20 6d 65 6d 6f  ion set..** memo
17c50 72 79 2d 6d 61 6e 61 67 65 6d 65 6e 74 20 68 61  ry-management ha
17c60 73 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 2e 0a  s been enabled..
17c70 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
17c80 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
17c90 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
17ca0 49 33 52 45 46 3a 20 20 43 6c 65 61 6e 20 55 70  I3REF:  Clean Up
17cb0 20 54 68 72 65 61 64 20 4c 6f 63 61 6c 20 53 74   Thread Local St
17cc0 6f 72 61 67 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73  orage.**.** This
17cd0 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20 73   routine makes s
17ce0 75 72 65 20 74 68 61 74 20 61 6c 6c 20 74 68 72  ure that all thr
17cf0 65 61 64 2d 6c 6f 63 61 6c 20 73 74 6f 72 61 67  ead-local storag
17d00 65 20 68 61 73 20 62 65 65 6e 0a 2a 2a 20 64 65  e has been.** de
17d10 61 6c 6c 6f 63 61 74 65 64 20 66 6f 72 20 74 68  allocated for th
17d20 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
17d30 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
17d40 74 69 6e 65 20 69 73 20 6e 6f 74 20 74 65 63 68  tine is not tech
17d50 6e 69 63 61 6c 6c 79 20 6e 65 63 65 73 73 61 72  nically necessar
17d60 79 2e 20 20 41 6c 6c 20 74 68 72 65 61 64 2d 6c  y.  All thread-l
17d70 6f 63 61 6c 20 73 74 6f 72 61 67 65 0a 2a 2a 20  ocal storage.** 
17d80 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
17d90 63 61 6c 6c 79 20 64 65 61 6c 6c 6f 63 61 74 65  cally deallocate
17da0 64 20 6f 6e 63 65 20 6d 65 6d 6f 72 79 2d 6d 61  d once memory-ma
17db0 6e 61 67 65 6d 65 6e 74 20 61 6e 64 0a 2a 2a 20  nagement and.** 
17dc0 73 68 61 72 65 64 2d 63 61 63 68 65 20 61 72 65  shared-cache are
17dd0 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 74 68   disabled and th
17de0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
17df0 74 20 68 61 73 20 62 65 65 6e 20 73 65 74 0a 2a  t has been set.*
17e00 2a 20 74 6f 20 7a 65 72 6f 2e 20 20 54 68 69 73  * to zero.  This
17e10 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72 6f 76   routine is prov
17e20 69 64 65 64 20 61 73 20 61 20 63 6f 6e 76 65 6e  ided as a conven
17e30 69 65 6e 63 65 20 66 6f 72 20 75 73 65 72 73 20  ience for users 
17e40 77 68 6f 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 6d  who.** want to m
17e50 61 6b 65 20 61 62 73 6f 6c 75 74 65 6c 79 20 73  ake absolutely s
17e60 75 72 65 20 74 68 65 79 20 68 61 76 65 20 6e 6f  ure they have no
17e70 74 20 66 6f 72 67 6f 74 74 65 6e 20 73 6f 6d 65  t forgotten some
17e80 74 68 69 6e 67 0a 2a 2a 20 70 72 69 6f 72 20 74  thing.** prior t
17e90 6f 20 6b 69 6c 6c 69 6e 67 20 6f 66 66 20 61 20  o killing off a 
17ea0 74 68 72 65 61 64 2e 0a 2a 2f 0a 76 6f 69 64 20  thread..*/.void 
17eb0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
17ec0 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 0a 2f  leanup(void);../
17ed0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
17ee0 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61  Extract Metadata
17ef0 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20   About A Column 
17f00 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a  Of A Table.**.**
17f10 20 54 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   This routine.**
17f20 20 72 65 74 75 72 6e 73 20 6d 65 74 61 2d 64 61   returns meta-da
17f30 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69  ta about a speci
17f40 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  fic column of a 
17f50 73 70 65 63 69 66 69 63 20 64 61 74 61 62 61 73  specific databas
17f60 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63 65 73  e.** table acces
17f70 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  sible using the 
17f80 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c  connection handl
17f90 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
17fa0 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 0a  first function .
17fb0 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  ** argument..**.
17fc0 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73  ** The column is
17fd0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
17fe0 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64  he second, third
17ff0 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
18000 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74 68  meters to .** th
18010 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  is function. The
18020 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18030 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  r is either the 
18040 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
18050 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d  base.** (i.e. "m
18060 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20  ain", "temp" or 
18070 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61  an attached data
18080 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67  base) containing
18090 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a   the specified.*
180a0 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e  * table or NULL.
180b0 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20   If it is NULL, 
180c0 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65  then all attache
180d0 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20  d databases are 
180e0 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20  searched.** for 
180f0 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20  the table using 
18100 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
18110 68 6d 20 61 73 20 74 68 65 20 64 61 74 61 62 61  hm as the databa
18120 73 65 20 65 6e 67 69 6e 65 20 75 73 65 73 20 74  se engine uses t
18130 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e  o .** resolve un
18140 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20  qualified table 
18150 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a  references..**.*
18160 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20  * The third and 
18170 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
18180 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
18190 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65  on are the table
181a0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20   and column .** 
181b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69  name of the desi
181c0 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70  red column, resp
181d0 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65  ectively. Neithe
181e0 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d  r of these param
181f0 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62 65  eters .** may be
18200 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74   NULL..**.** Met
18210 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  a information is
18220 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69   returned by wri
18230 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f  ting to the memo
18240 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73  ry locations pas
18250 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 35 74  sed as.** the 5t
18260 68 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  h and subsequent
18270 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
18280 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e  his function. An
18290 79 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20 61  y of these .** a
182a0 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 20  rguments may be 
182b0 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63  NULL, in which c
182c0 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ase the correspo
182d0 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66  nding element of
182e0 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d   meta .** inform
182f0 61 74 69 6f 6e 20 69 73 20 6f 6d 6d 69 74 74 65  ation is ommitte
18300 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  d..**.** <pre>.*
18310 2a 20 50 61 72 61 6d 65 74 65 72 20 20 20 20 20  * Parameter     
18320 4f 75 74 70 75 74 20 54 79 70 65 20 20 20 20 20  Output Type     
18330 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20   Description.** 
18340 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
18350 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
18360 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68 20  ---.**.**   5th 
18370 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68          const ch
18380 61 72 2a 20 20 20 20 20 20 44 61 74 61 20 74 79  ar*      Data ty
18390 70 65 0a 2a 2a 20 20 20 36 74 68 20 20 20 20 20  pe.**   6th     
183a0 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20      const char* 
183b0 20 20 20 20 20 4e 61 6d 65 20 6f 66 20 74 68 65       Name of the
183c0 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69   default collati
183d0 6f 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a 20  on sequence .** 
183e0 20 20 37 74 68 20 20 20 20 20 20 20 20 20 69 6e    7th         in
183f0 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54  t              T
18400 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d  rue if the colum
18410 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c  n has a NOT NULL
18420 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 20   constraint.**  
18430 20 38 74 68 20 20 20 20 20 20 20 20 20 69 6e 74   8th         int
18440 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72                Tr
18450 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ue if the column
18460 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   is part of the 
18470 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 20  PRIMARY KEY.**  
18480 20 39 74 68 20 20 20 20 20 20 20 20 20 69 6e 74   9th         int
18490 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72                Tr
184a0 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ue if the column
184b0 20 69 73 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e   is AUTOINCREMEN
184c0 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a  T.** </pre>.**.*
184d0 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20  *.** The memory 
184e0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
184f0 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e  e character poin
18500 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f  ters returned fo
18510 72 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61 72  r the .** declar
18520 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63  ation type and c
18530 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
18540 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20  e is valid only 
18550 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 0a  until the next .
18560 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 73  ** call to any s
18570 71 6c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69  qlite API functi
18580 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  on..**.** If the
18590 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65   specified table
185a0 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76   is actually a v
185b0 69 65 77 2c 20 74 68 65 6e 20 61 6e 20 65 72 72  iew, then an err
185c0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  or is returned..
185d0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65  **.** If the spe
185e0 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73  cified column is
185f0 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20   "rowid", "oid" 
18600 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64  or "_rowid_" and
18610 20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52 20   an .** INTEGER 
18620 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75  PRIMARY KEY colu
18630 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c  mn has been expl
18640 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c  icitly declared,
18650 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
18660 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20   .** parameters 
18670 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20  are set for the 
18680 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
18690 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74  red column. If t
186a0 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78  here is no.** ex
186b0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
186c0 64 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68  d IPK column, th
186d0 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20 70 61  en the output pa
186e0 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
186f0 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a   as .** follows:
18700 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
18710 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22      data type: "
18720 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20  INTEGER".**     
18730 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
18740 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20  ce: "BINARY".** 
18750 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a      not null: 0.
18760 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b  **     primary k
18770 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74  ey: 1.**     aut
18780 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a  o increment: 0.*
18790 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54  * </pre>.**.** T
187a0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
187b0 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72   load one or mor
187c0 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64  e schemas from d
187d0 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49  atabase files. I
187e0 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63  f an.** error oc
187f0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73  curs during this
18800 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
18810 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61  the requested ta
18820 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  ble or column.**
18830 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64   cannot be found
18840 2c 20 61 6e 20 53 51 4c 49 54 45 20 65 72 72 6f  , an SQLITE erro
18850 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
18860 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20  ed and an error 
18870 6d 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74 20  message.** left 
18880 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
18890 68 61 6e 64 6c 65 20 28 74 6f 20 62 65 20 72 65  handle (to be re
188a0 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71  trieved using sq
188b0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e  lite3_errmsg()).
188c0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
188d0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
188e0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
188f0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
18900 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
18910 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
18920 45 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65  ETADATA preproce
18930 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
18940 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
18950 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e  te3_table_column
18960 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c  _metadata(.  sql
18970 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
18980 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e           /* Conn
18990 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f  ection handle */
189a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
189b0 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f  DbName,        /
189c0 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20  * Database name 
189d0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e  or NULL */.  con
189e0 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e  st char *zTableN
189f0 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c  ame,     /* Tabl
18a00 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73  e name */.  cons
18a10 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e  t char *zColumnN
18a20 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d  ame,    /* Colum
18a30 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72  n name */.  char
18a40 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54   const **pzDataT
18a50 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55  ype,    /* OUTPU
18a60 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61  T: Declared data
18a70 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20   type */.  char 
18a80 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65  const **pzCollSe
18a90 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  q,     /* OUTPUT
18aa0 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  : Collation sequ
18ab0 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69  ence name */.  i
18ac0 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20  nt *pNotNull,   
18ad0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
18ae0 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f  TPUT: True if NO
18af0 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
18b00 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e  t exists */.  in
18b10 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20  t *pPrimaryKey, 
18b20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
18b30 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
18b40 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a  umn part of PK *
18b50 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e  /.  int *pAutoin
18b60 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  c               
18b70 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
18b80 69 66 20 63 6f 6c 75 6d 73 20 69 73 20 61 75 74  if colums is aut
18b90 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29  o-increment */.)
18ba0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18bb0 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e  F: Load An Exten
18bc0 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d  sion.**.** Attem
18bd0 70 74 20 74 6f 20 6c 6f 61 64 20 61 6e 20 53 51  pt to load an SQ
18be0 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
18bf0 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64  ibrary contained
18c00 20 69 6e 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   in the file.** 
18c10 7a 46 69 6c 65 2e 20 20 54 68 65 20 65 6e 74 72  zFile.  The entr
18c20 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63  y point is zProc
18c30 2e 20 20 7a 50 72 6f 63 20 6d 61 79 20 62 65 20  .  zProc may be 
18c40 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
18c50 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  the.** name of t
18c60 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 64  he entry point d
18c70 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69  efaults to "sqli
18c80 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e  te3_extension_in
18c90 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  it"..**.** Retur
18ca0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
18cb0 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
18cc0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
18cd0 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
18ce0 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ong..**.** If an
18cf0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e   error occurs an
18d00 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f  d pzErrMsg is no
18d10 74 20 30 2c 20 74 68 65 6e 20 66 69 6c 6c 20 2a  t 0, then fill *
18d20 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 0a 2a  pzErrMsg with .*
18d30 2a 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  * error message 
18d40 74 65 78 74 2e 20 20 54 68 65 20 63 61 6c 6c 69  text.  The calli
18d50 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ng function shou
18d60 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d  ld free this mem
18d70 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c 69 6e  ory.** by callin
18d80 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  g [sqlite3_free(
18d90 29 5d 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 6e 73  )]..**.** Extens
18da0 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74  ion loading must
18db0 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   be enabled usin
18dc0 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
18dd0 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
18de0 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ()].** prior to 
18df0 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49  calling this API
18e00 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 77 69 6c   or an error wil
18e10 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a  l be returned..*
18e20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f  /.int sqlite3_lo
18e30 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20  ad_extension(.  
18e40 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
18e50 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68        /* Load th
18e60 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f  e extension into
18e70 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63   this database c
18e80 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63  onnection */.  c
18e90 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
18ea0 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20  ,    /* Name of 
18eb0 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61  the shared libra
18ec0 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78  ry containing ex
18ed0 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  tension */.  con
18ee0 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20  st char *zProc, 
18ef0 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e     /* Entry poin
18f00 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d  t.  Derived from
18f10 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20   zFile if 0 */. 
18f20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67   char **pzErrMsg
18f30 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72         /* Put er
18f40 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65  ror message here
18f50 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a   if not 0 */.);.
18f60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18f70 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61    Enable Or Disa
18f80 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  ble Extension Lo
18f90 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 53 6f 20 61  ading.**.** So a
18fa0 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65  s not to open se
18fb0 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20  curity holes in 
18fc0 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f  older applicatio
18fd0 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75  ns that are.** u
18fe0 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61  nprepared to dea
18ff0 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e  l with extension
19000 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73   loading, and as
19010 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61   a means of disa
19020 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69  bling.** extensi
19030 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65  on loading while
19040 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72   evaluating user
19050 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68  -entered SQL, th
19060 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41  e following.** A
19070 50 49 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  PI is provided t
19080 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69  o turn the [sqli
19090 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
190a0 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20  on()] mechanism 
190b0 6f 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20  on and.** off.  
190c0 49 74 20 69 73 20 6f 66 66 20 62 79 20 64 65 66  It is off by def
190d0 61 75 6c 74 2e 20 20 53 65 65 20 74 69 63 6b 65  ault.  See ticke
190e0 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 43  t #1863..**.** C
190f0 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
19100 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 74   with onoff==1 t
19110 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e  o turn extension
19120 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61   loading on.** a
19130 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
19140 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
19150 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61   it back off aga
19160 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  in..*/.int sqlit
19170 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
19180 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33  xtension(sqlite3
19190 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29   *db, int onoff)
191a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
191b0 46 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67 65 6d  F: Make Arrangem
191c0 65 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61 74 69  ents To Automati
191d0 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78  cally Load An Ex
191e0 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 52 65  tension.**.** Re
191f0 67 69 73 74 65 72 20 61 6e 20 65 78 74 65 6e 73  gister an extens
19200 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  ion entry point 
19210 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61 74 69  that is automati
19220 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a 2a 2a  cally invoked.**
19230 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20   whenever a new 
19240 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19250 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20 75 73  ion is opened us
19260 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
19270 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69  open()] or [sqli
19280 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
19290 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63 61  *.** This API ca
192a0 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20  n be invoked at 
192b0 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70 20  program startup 
192c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67 69  in order to regi
192d0 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  ster.** one or m
192e0 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20 6c  ore statically l
192f0 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e 73  inked extensions
19300 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61 76   that will be av
19310 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c  ailable.** to al
19320 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  l new database c
19330 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  onnections..**.*
19340 2a 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 65  * Duplicate exte
19350 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63  nsions are detec
19360 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74  ted so calling t
19370 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c 74  his routine mult
19380 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69  iple.** times wi
19390 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65  th the same exte
193a0 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73  nsion is harmles
193b0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  s..**.** This ro
193c0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70  utine stores a p
193d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78  ointer to the ex
193e0 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72  tension in an ar
193f0 72 61 79 0a 2a 2a 20 74 68 61 74 20 69 73 20 6f  ray.** that is o
19400 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c  btained from mal
19410 6c 6f 63 28 29 2e 20 20 49 66 20 79 6f 75 20 72  loc().  If you r
19420 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  un a memory leak
19430 0a 2a 2a 20 63 68 65 63 6b 65 72 20 6f 6e 20 79  .** checker on y
19440 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e 64 20  our program and 
19450 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c 65 61  it reports a lea
19460 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74 68 69  k because of thi
19470 73 0a 2a 2a 20 61 72 72 61 79 2c 20 74 68 65 6e  s.** array, then
19480 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
19490 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78 74 65 6e  _automatic_exten
194a0 73 69 6f 6e 5f 72 65 73 65 74 28 29 5d 20 70 72  sion_reset()] pr
194b0 69 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64 6f  ior.** to shutdo
194c0 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d  wn to free the m
194d0 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 75 74  emory..**.** Aut
194e0 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
194f0 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20 61  s apply across a
19500 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a  ll threads..**.*
19510 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
19520 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   is experimental
19530 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20   and is subject 
19540 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  to change or.** 
19550 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72  removal in futur
19560 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
19570 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
19580 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
19590 69 6f 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72 79  ion(void *xEntry
195a0 50 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  Point);.../*.** 
195b0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
195c0 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73  Automatic Extens
195d0 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a  ion Loading.**.*
195e0 2a 20 44 69 73 61 62 6c 65 20 61 6c 6c 20 70 72  * Disable all pr
195f0 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
19600 72 65 64 20 61 75 74 6f 6d 61 74 69 63 20 65 78  red automatic ex
19610 74 65 6e 73 69 6f 6e 73 2e 20 20 54 68 69 73 0a  tensions.  This.
19620 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
19630 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
19640 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c 69 74  all prior [sqlit
19650 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78 74  e3_automatic_ext
19660 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63 61 6c  ension()].** cal
19670 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 63  ls..**.** This c
19680 61 6c 6c 20 64 69 73 61 62 6c 65 64 20 61 75 74  all disabled aut
19690 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
196a0 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73  s in all threads
196b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
196c0 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69  erface is experi
196d0 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75  mental and is su
196e0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
196f0 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e  or.** removal in
19700 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
19710 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76   of SQLite..*/.v
19720 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65  oid sqlite3_rese
19730 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
19740 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 2a  (void);.../*.***
19750 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  *** EXPERIMENTAL
19760 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68   - subject to ch
19770 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74  ange without not
19780 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ice ************
19790 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  **.**.** The int
197a0 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
197b0 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
197c0 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74  anism is current
197d0 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  ly considered.**
197e0 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e   to be experimen
197f0 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66  tal.  The interf
19800 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65  ace might change
19810 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65   in incompatible
19820 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69   ways..** If thi
19830 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66  s is a problem f
19840 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75  or you, do not u
19850 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  se the interface
19860 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a   at this time..*
19870 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69  *.** When the vi
19880 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
19890 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65 73 2c  anism stablizes,
198a0 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
198b0 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
198c0 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
198d0 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
198e0 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
198f0 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f  s comment..*/../
19900 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20  *.** Structures 
19910 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74  used by the virt
19920 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66  ual table interf
19930 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ace.*/.typedef s
19940 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
19950 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b  ab sqlite3_vtab;
19960 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
19970 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
19980 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  fo sqlite3_index
19990 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73  _info;.typedef s
199a0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
199b0 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65  ab_cursor sqlite
199c0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74  3_vtab_cursor;.t
199d0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
199e0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c  lite3_module sql
199f0 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a  ite3_module;../*
19a00 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69 73 20  .** A module is 
19a10 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72 74 75  a class of virtu
19a20 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61 63 68  al tables.  Each
19a30 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66 69 6e   module is defin
19a40 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e 73 74  ed.** by an inst
19a50 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c  ance of the foll
19a60 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 2e  owing structure.
19a70 20 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65    This structure
19a80 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f 73   consists.** mos
19a90 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66  tly of methods f
19aa0 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a  or the module..*
19ab0 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
19ac0 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20  _module {.  int 
19ad0 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
19ae0 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74  (*xCreate)(sqlit
19af0 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
19b00 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
19b10 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
19b20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
19b30 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
19b40 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
19b50 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
19b60 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63  .  int (*xConnec
19b70 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  t)(sqlite3*, voi
19b80 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
19b90 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
19ba0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
19bb0 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
19bc0 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
19bd0 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
19be0 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
19bf0 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c  *xBestIndex)(sql
19c00 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
19c10 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  , sqlite3_index_
19c20 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  info*);.  int (*
19c30 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c  xDisconnect)(sql
19c40 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
19c50 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74  );.  int (*xDest
19c60 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61  roy)(sqlite3_vta
19c70 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
19c80 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
19c90 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73  3_vtab *pVTab, s
19ca0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
19cb0 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a  or **ppCursor);.
19cc0 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
19cd0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
19ce0 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
19cf0 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f  Filter)(sqlite3_
19d00 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e  vtab_cursor*, in
19d10 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20  t idxNum, const 
19d20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20  char *idxStr,.  
19d30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
19d40 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f  t argc, sqlite3_
19d50 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20  value **argv);. 
19d60 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71   int (*xNext)(sq
19d70 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
19d80 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f  r*);.  int (*xEo
19d90 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  f)(sqlite3_vtab_
19da0 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
19db0 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74  (*xColumn)(sqlit
19dc0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
19dd0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
19de0 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
19df0 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33  *xRowid)(sqlite3
19e00 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
19e10 71 6c 69 74 65 5f 69 6e 74 36 34 20 2a 70 52 6f  qlite_int64 *pRo
19e20 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  wid);.  int (*xU
19e30 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76  pdate)(sqlite3_v
19e40 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  tab *, int, sqli
19e50 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71  te3_value **, sq
19e60 6c 69 74 65 5f 69 6e 74 36 34 20 2a 29 3b 0a 20  lite_int64 *);. 
19e70 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73   int (*xBegin)(s
19e80 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
19e90 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ab);.  int (*xSy
19ea0 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  nc)(sqlite3_vtab
19eb0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
19ec0 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74  (*xCommit)(sqlit
19ed0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
19ee0 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61  .  int (*xRollba
19ef0 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ck)(sqlite3_vtab
19f00 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
19f10 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29  (*xFindFunction)
19f20 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
19f30 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20  Vtab, int nArg, 
19f40 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
19f50 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  e,.             
19f60 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 28            void (
19f70 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65  **pxFunc)(sqlite
19f80 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
19f90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
19fa0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
19fb0 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70          void **p
19fc0 70 41 72 67 29 3b 0a 0a 20 20 69 6e 74 20 28 2a  pArg);..  int (*
19fd0 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  xRename)(sqlite3
19fe0 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f  _vtab *pVtab, co
19ff0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b  nst char *zNew);
1a000 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 73  .};../*.** The s
1a010 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
1a020 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20  o structure and 
1a030 69 74 73 20 73 75 62 73 74 72 75 63 74 75 72 65  its substructure
1a040 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20  s is used to.** 
1a050 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  pass information
1a060 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76   into and receiv
1a070 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d  e the reply from
1a080 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 0a   the xBestIndex.
1a090 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ** method of an 
1a0a0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 20  sqlite3_module. 
1a0b0 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65   The fields unde
1a0c0 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65  r **Inputs** are
1a0d0 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74   the.** inputs t
1a0e0 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64  o xBestIndex and
1a0f0 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20   are read-only. 
1a100 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65   xBestIndex inse
1a110 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c  rts its.** resul
1a120 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75  ts into the **Ou
1a130 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a  tputs** fields..
1a140 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74  **.** The aConst
1a150 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65  raint[] array re
1a160 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 75  cords WHERE clau
1a170 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f  se constraints o
1a180 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 3a 0a 2a  f the.** form:.*
1a190 2a 0a 2a 2a 20 20 20 20 20 20 20 20 20 63 6f 6c  *.**         col
1a1a0 75 6d 6e 20 4f 50 20 65 78 70 72 0a 2a 2a 0a 2a  umn OP expr.**.*
1a1b0 2a 20 57 68 65 72 65 20 4f 50 20 69 73 20 3d 2c  * Where OP is =,
1a1c0 20 3c 2c 20 3c 3d 2c 20 3e 2c 20 6f 72 20 3e 3d   <, <=, >, or >=
1a1d0 2e 20 20 54 68 65 20 70 61 72 74 69 63 75 6c 61  .  The particula
1a1e0 72 20 6f 70 65 72 61 74 6f 72 20 69 73 20 73 74  r operator is st
1a1f0 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 43 6f 6e 73  ored.** in aCons
1a200 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68  traint[].op.  Th
1a210 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
1a220 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20  olumn is stored 
1a230 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69  in .** aConstrai
1a240 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61  nt[].iColumn.  a
1a250 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61  Constraint[].usa
1a260 62 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74  ble is TRUE if t
1a270 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68  he.** expr on th
1a280 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64  e right-hand sid
1a290 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74  e can be evaluat
1a2a0 65 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65  ed (and thus the
1a2b0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69   constraint.** i
1a2c0 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61  s usable) and fa
1a2d0 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74  lse if it cannot
1a2e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69  ..**.** The opti
1a2f0 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61  mizer automatica
1a300 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d  lly inverts term
1a310 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65  s of the form "e
1a320 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a  xpr OP column".*
1a330 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65  * and makes othe
1a340 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6e 6f  r simplificatino
1a350 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63  s to the WHERE c
1a360 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65  lause in an atte
1a370 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73  mpt to.** get as
1a380 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75   many WHERE clau
1a390 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68  se terms into th
1a3a0 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f  e form shown abo
1a3b0 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a  ve as possible..
1a3c0 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69  ** The aConstrai
1a3d0 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20  nt[] array only 
1a3e0 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c  reports WHERE cl
1a3f0 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68  ause terms in th
1a400 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72  e correct.** for
1a410 6d 20 74 68 61 74 20 72 65 66 65 72 20 74 6f 20  m that refer to 
1a420 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76  the particular v
1a430 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69  irtual table bei
1a440 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a  ng queried..**.*
1a450 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  * Information ab
1a460 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59  out the ORDER BY
1a470 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65   clause is store
1a480 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e  d in aOrderBy[].
1a490 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 6f 66  .** Each term of
1a4a0 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64   aOrderBy record
1a4b0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  s a column of th
1a4c0 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
1a4d0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 42 65  e..**.** The xBe
1a4e0 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6d  stIndex method m
1a4f0 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72  ust fill aConstr
1a500 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68  aintUsage[] with
1a510 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
1a520 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d  about what param
1a530 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f  eters to pass to
1a540 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61 72   xFilter.  If ar
1a550 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a  gvIndex>0 then.*
1a560 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  * the right-hand
1a570 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72   side of the cor
1a580 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73  responding aCons
1a590 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c  traint[] is eval
1a5a0 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63  uated.** and bec
1a5b0 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e 64  omes the argvInd
1a5c0 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61  ex-th entry in a
1a5d0 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74 72  rgv.  If aConstr
1a5e0 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74  aintUsage[].omit
1a5f0 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65  .** is true, the
1a600 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  n the constraint
1a610 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62   is assumed to b
1a620 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20  e fully handled 
1a630 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61  by the.** virtua
1a640 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e  l table and is n
1a650 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e  ot checked again
1a660 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   by SQLite..**.*
1a670 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64  * The idxNum and
1a680 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61   idxPtr values a
1a690 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20  re recorded and 
1a6a0 70 61 73 73 65 64 20 69 6e 74 6f 20 78 46 69 6c  passed into xFil
1a6b0 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ter..** sqlite3_
1a6c0 66 72 65 65 28 29 20 69 73 20 75 73 65 64 20 74  free() is used t
1a6d0 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66  o free idxPtr if
1a6e0 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74   needToFreeIdxPt
1a6f0 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a  r is true..**.**
1a700 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73   The orderByCons
1a710 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20  umed means that 
1a720 6f 75 74 70 75 74 20 66 72 6f 6d 20 78 46 69 6c  output from xFil
1a730 74 65 72 20 77 69 6c 6c 20 6f 63 63 75 72 20 69  ter will occur i
1a740 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74  n.** the correct
1a750 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73 66   order to satisf
1a760 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  y the ORDER BY c
1a770 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f  lause so that no
1a780 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72   separate.** sor
1a790 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 65 71  ting step is req
1a7a0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
1a7b0 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76   estimatedCost v
1a7c0 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d  alue is an estim
1a7d0 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20  ate of the cost 
1a7e0 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20  of doing the.** 
1a7f0 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75  particular looku
1a800 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20  p.  A full scan 
1a810 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 68 20  of a table with 
1a820 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
1a830 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20   have.** a cost 
1a840 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20  of N.  A binary 
1a850 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c  search of a tabl
1a860 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73  e of N entries s
1a870 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20  hould have a.** 
1a880 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d  cost of approxim
1a890 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f  ately log(N)..*/
1a8a0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
1a8b0 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f  index_info {.  /
1a8c0 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 63 6f  * Inputs */.  co
1a8d0 6e 73 74 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61  nst int nConstra
1a8e0 69 6e 74 3b 20 20 20 20 20 2f 2a 20 4e 75 6d 62  int;     /* Numb
1a8f0 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e  er of entries in
1a900 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a   aConstraint */.
1a910 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
1a920 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e  qlite3_index_con
1a930 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69  straint {.     i
1a940 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20  nt iColumn;     
1a950 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75           /* Colu
1a960 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20  mn on left-hand 
1a970 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69  side of constrai
1a980 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  nt */.     unsig
1a990 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20  ned char op;    
1a9a0 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69       /* Constrai
1a9b0 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20  nt operator */. 
1a9c0 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
1a9d0 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a  r usable;     /*
1a9e0 20 54 72 75 65 20 69 66 20 74 68 69 73 20 63 6f   True if this co
1a9f0 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 61 62  nstraint is usab
1aa00 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69  le */.     int i
1aa10 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20  TermOffset;     
1aa20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74       /* Used int
1aa30 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49  ernally - xBestI
1aa40 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f  ndex should igno
1aa50 72 65 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74  re */.  } *const
1aa60 20 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20   aConstraint;   
1aa70 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57     /* Table of W
1aa80 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73  HERE clause cons
1aa90 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 63 6f 6e  traints */.  con
1aaa0 73 74 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b  st int nOrderBy;
1aab0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1aac0 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68  r of terms in th
1aad0 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
1aae0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 74 72  e */.  const str
1aaf0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
1ab00 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20  x_orderby {.    
1ab10 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
1ab20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
1ab30 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  lumn number */. 
1ab40 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
1ab50 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a  r desc;       /*
1ab60 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20   True for DESC. 
1ab70 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20   False for ASC. 
1ab80 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74 20 61 4f  */.  } *const aO
1ab90 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20  rderBy;         
1aba0 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20  /* The ORDER BY 
1abb0 63 6c 61 75 73 65 20 2a 2f 0a 0a 20 20 2f 2a 20  clause */..  /* 
1abc0 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72  Outputs */.  str
1abd0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
1abe0 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61  x_constraint_usa
1abf0 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67  ge {.    int arg
1ac00 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20  vIndex;         
1ac10 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73    /* if >0, cons
1ac20 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f  traint is part o
1ac30 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65  f argv to xFilte
1ac40 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65  r */.    unsigne
1ac50 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20  d char omit;    
1ac60 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65    /* Do not code
1ac70 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73   a test for this
1ac80 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20   constraint */. 
1ac90 20 7d 20 2a 63 6f 6e 73 74 20 61 43 6f 6e 73 74   } *const aConst
1aca0 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e  raintUsage;.  in
1acb0 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20  t idxNum;       
1acc0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
1acd0 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74  er used to ident
1ace0 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f  ify the index */
1acf0 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b  .  char *idxStr;
1ad00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1ad10 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c   String, possibl
1ad20 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1ad30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a  sqlite3_malloc *
1ad40 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72  /.  int needToFr
1ad50 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f  eeIdxStr;      /
1ad60 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73  * Free idxStr us
1ad70 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1ad80 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20  () if true */.  
1ad90 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  int orderByConsu
1ada0 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  med;       /* Tr
1adb0 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20  ue if output is 
1adc0 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20  already ordered 
1add0 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69  */.  double esti
1ade0 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20  matedCost;      
1adf0 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73  /* Estimated cos
1ae00 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20  t of using this 
1ae10 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66  index */.};.#def
1ae20 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
1ae30 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20  _CONSTRAINT_EQ  
1ae40 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
1ae50 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
1ae60 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66  INT_GT    4.#def
1ae70 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
1ae80 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20  _CONSTRAINT_LE  
1ae90 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
1aea0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
1aeb0 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65  INT_LT    16.#de
1aec0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
1aed0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20  X_CONSTRAINT_GE 
1aee0 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51     32.#define SQ
1aef0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
1af00 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a  RAINT_MATCH 64..
1af10 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  /*.** This routi
1af20 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  ne is used to re
1af30 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d 6f 64  gister a new mod
1af40 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 61 6e  ule name with an
1af50 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 6e 6e 65   SQLite.** conne
1af60 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c 65 20 6e  ction.  Module n
1af70 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65 67  ames must be reg
1af80 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 20 63  istered before c
1af90 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a 2a 20 76  reating new.** v
1afa0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6f 6e  irtual tables on
1afb0 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20   the module, or 
1afc0 62 65 66 6f 72 65 20 75 73 69 6e 67 20 70 72 65  before using pre
1afd0 65 78 69 73 74 69 6e 67 20 76 69 72 74 75 61 6c  existing virtual
1afe0 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66 20 74 68  .** tables of th
1aff0 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69 6e 74  e module..*/.int
1b000 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1b010 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65  module(.  sqlite
1b020 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1b030 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63       /* SQLite c
1b040 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67  onnection to reg
1b050 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74  ister module wit
1b060 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  h */.  const cha
1b070 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20  r *zName,       
1b080 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
1b090 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e   module */.  con
1b0a0 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
1b0b0 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f  e *,    /* Metho
1b0c0 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
1b0d0 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 20 20  e */.  void *   
1b0e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b0f0 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61    /* Client data
1b100 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f   for xCreate/xCo
1b110 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  nnect */.);../*.
1b120 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1b130 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
1b140 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
1b150 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6d 65 74 68  te_module() meth
1b160 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65 78 63  od above,.** exc
1b170 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 6c 6f  ept that it allo
1b180 77 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ws a destructor 
1b190 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 73  function to be s
1b1a0 70 65 63 69 66 69 65 64 2e 20 49 74 20 69 73 0a  pecified. It is.
1b1b0 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65 78 70  ** even more exp
1b1c0 65 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e 20 74  erimental than t
1b1d0 68 65 20 72 65 73 74 20 6f 66 20 74 68 65 20 76  he rest of the v
1b1e0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 41 50  irtual tables AP
1b1f0 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  I..*/.int sqlite
1b200 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
1b210 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
1b220 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
1b230 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65   /* SQLite conne
1b240 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65  ction to registe
1b250 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f  r module with */
1b260 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1b270 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a  Name,         /*
1b280 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64   Name of the mod
1b290 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73  ule */.  const s
1b2a0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c  qlite3_module *,
1b2b0 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66      /* Methods f
1b2c0 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  or the module */
1b2d0 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
1b2e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1b2f0 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72   Client data for
1b300 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63   xCreate/xConnec
1b310 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65  t */.  void(*xDe
1b320 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20  stroy)(void*)   
1b330 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74    /* Module dest
1b340 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
1b350 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 45 76 65  */.);../*.** Eve
1b360 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ry module implem
1b370 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20  entation uses a 
1b380 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20  subclass of the 
1b390 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74  following struct
1b3a0 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69  ure.** to descri
1b3b0 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  be a particular 
1b3c0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
1b3d0 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 73 75  module.  Each su
1b3e0 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62  bclass will.** b
1b3f0 65 20 74 61 79 6c 6f 72 65 64 20 74 6f 20 74 68  e taylored to th
1b400 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
1b410 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   of the module i
1b420 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
1b430 20 54 68 65 0a 2a 2a 20 70 75 72 70 6f 73 65 20   The.** purpose 
1b440 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61  of this supercla
1b450 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20  ss is to define 
1b460 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74  certain fields t
1b470 68 61 74 20 61 72 65 20 63 6f 6d 6d 6f 6e 0a 2a  hat are common.*
1b480 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20  * to all module 
1b490 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e  implementations.
1b4a0 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74  .**.** Virtual t
1b4b0 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61  ables methods ca
1b4c0 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d  n set an error m
1b4d0 65 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e  essage by assign
1b4e0 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20  ing a.** string 
1b4f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
1b500 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
1b510 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65  to zErrMsg.  The
1b520 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a   method should.*
1b530 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74  * take care that
1b540 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e   any prior strin
1b550 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20  g is freed by a 
1b560 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1b570 66 72 65 65 28 29 0a 2a 2a 20 70 72 69 6f 72 20  free().** prior 
1b580 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e  to assigning a n
1b590 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72  ew string to zEr
1b5a0 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74 68 65  rMsg.  After the
1b5b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
1b5c0 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20 75  * is delivered u
1b5d0 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 20  p to the client 
1b5e0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
1b5f0 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
1b600 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
1b610 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74 65   freed by sqlite
1b620 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68 65  3_free() and the
1b630 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20 77   zErrMsg field w
1b640 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 20 20  ill be zeroed.  
1b650 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20 73 71 6c  Note.** that sql
1b660 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
1b670 6e 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  nd sqlite3_free(
1b680 29 20 61 72 65 20 75 73 65 64 20 6f 6e 20 74 68  ) are used on th
1b690 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 0a  e zErrMsg field.
1b6a0 2a 2a 20 73 69 6e 63 65 20 76 69 72 74 75 61 6c  ** since virtual
1b6b0 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 6d 6d   tables are comm
1b6c0 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e 74 65 64  only implemented
1b6d0 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20 65 78 74   in loadable ext
1b6e0 65 6e 73 69 6f 6e 73 20 77 68 69 63 68 0a 2a 2a  ensions which.**
1b6f0 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 61 63 63   do not have acc
1b700 65 73 73 20 74 6f 20 73 71 6c 69 74 65 33 4d 50  ess to sqlite3MP
1b710 72 69 6e 74 66 28 29 20 6f 72 20 73 71 6c 69 74  rintf() or sqlit
1b720 65 33 46 72 65 65 28 29 2e 0a 2a 2f 0a 73 74 72  e3Free()..*/.str
1b730 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
1b740 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74   {.  const sqlit
1b750 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75  e3_module *pModu
1b760 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75  le;  /* The modu
1b770 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74  le for this virt
1b780 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69  ual table */.  i
1b790 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20  nt nRef;        
1b7a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
1b7b0 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  * Used internall
1b7c0 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72  y */.  char *zEr
1b7d0 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 20  rMsg;           
1b7e0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1b7f0 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c  message from sql
1b800 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a  ite3_mprintf() *
1b810 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74  /.  /* Virtual t
1b820 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
1b830 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61  ions will typica
1b840 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  lly add addition
1b850 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a  al fields */.};.
1b860 0a 2f 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c 65  ./* Every module
1b870 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1b880 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20  uses a subclass 
1b890 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
1b8a0 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f   structure.** to
1b8b0 20 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72   describe cursor
1b8c0 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74  s that point int
1b8d0 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  o the virtual ta
1b8e0 62 6c 65 20 61 6e 64 20 61 72 65 20 75 73 65 64  ble and are used
1b8f0 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f  .** to loop thro
1b900 75 67 68 20 74 68 65 20 76 69 72 74 75 61 6c 20  ugh the virtual 
1b910 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20  table.  Cursors 
1b920 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
1b930 67 20 74 68 65 0a 2a 2a 20 78 4f 70 65 6e 20 6d  g the.** xOpen m
1b940 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64  ethod of the mod
1b950 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c  ule.  Each modul
1b960 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1b970 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20   will define.** 
1b980 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61  the content of a
1b990 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72   cursor structur
1b9a0 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77  e to suit its ow
1b9b0 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  n needs..**.** T
1b9c0 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65  his superclass e
1b9d0 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74  xists in order t
1b9e0 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20  o define fields 
1b9f0 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68  of the cursor th
1ba00 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e  at.** are common
1ba10 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e   to all implemen
1ba20 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75  tations..*/.stru
1ba30 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  ct sqlite3_vtab_
1ba40 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74  cursor {.  sqlit
1ba50 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20  e3_vtab *pVtab; 
1ba60 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20       /* Virtual 
1ba70 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75  table of this cu
1ba80 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72  rsor */.  /* Vir
1ba90 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
1baa0 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20  mentations will 
1bab0 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64  typically add ad
1bac0 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
1bad0 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  */.};../*.** The
1bae0 20 78 43 72 65 61 74 65 20 61 6e 64 20 78 43 6f   xCreate and xCo
1baf0 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73 20 6f 66  nnect methods of
1bb00 20 61 20 6d 6f 64 75 6c 65 20 75 73 65 20 74 68   a module use th
1bb10 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a  e following API.
1bb20 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68  ** to declare th
1bb30 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61  e format (the na
1bb40 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 65  mes and datatype
1bb50 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1bb60 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74  ) of.** the virt
1bb70 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20  ual tables they 
1bb80 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e  implement..*/.in
1bb90 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72  t sqlite3_declar
1bba0 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c  e_vtab(sqlite3*,
1bbb0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 72   const char *zCr
1bbc0 65 61 74 65 54 61 62 6c 65 29 3b 0a 0a 2f 2a 0a  eateTable);../*.
1bbd0 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  ** Virtual table
1bbe0 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c  s can provide al
1bbf0 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d  ternative implem
1bc00 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e  entations of fun
1bc10 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20  ctions.** using 
1bc20 74 68 65 20 78 46 69 6e 64 46 75 6e 63 74 69 6f  the xFindFunctio
1bc30 6e 20 6d 65 74 68 6f 64 2e 20 20 42 75 74 20 67  n method.  But g
1bc40 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f  lobal versions o
1bc50 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e  f those function
1bc60 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20  s.** must exist 
1bc70 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f  in order to be o
1bc80 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a  verloaded..**.**
1bc90 20 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20   This API makes 
1bca0 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65  sure a global ve
1bcb0 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74  rsion of a funct
1bcc0 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74 69  ion with a parti
1bcd0 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e  cular.** name an
1bce0 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61  d number of para
1bcf0 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e 20 20  meters exists.  
1bd00 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74  If no such funct
1bd10 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65  ion exists.** be
1bd20 66 6f 72 65 20 74 68 69 73 20 41 50 49 20 69 73  fore this API is
1bd30 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66   called, a new f
1bd40 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74  unction is creat
1bd50 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  ed.  The impleme
1bd60 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68  ntation.** of th
1bd70 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61  e new function a
1bd80 6c 77 61 79 73 20 63 61 75 73 65 73 20 61 6e 20  lways causes an 
1bd90 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20  exception to be 
1bda0 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74  thrown.  So.** t
1bdb0 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20  he new function 
1bdc0 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20  is not good for 
1bdd0 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73 65  anything by itse
1bde0 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a  lf.  Its only.**
1bdf0 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62   purpose is to b
1be00 65 20 61 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72  e a place-holder
1be10 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63   function that c
1be20 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  an be overloaded
1be30 0a 2a 2a 20 62 79 20 76 69 72 74 75 61 6c 20 74  .** by virtual t
1be40 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ables..**.** Thi
1be50 73 20 41 50 49 20 73 68 6f 75 6c 64 20 62 65 20  s API should be 
1be60 63 6f 6e 73 69 64 65 72 65 64 20 70 61 72 74 20  considered part 
1be70 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  of the virtual t
1be80 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 2c 0a  able interface,.
1be90 2a 2a 20 77 68 69 63 68 20 69 73 20 65 78 70 65  ** which is expe
1bea0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 73 75 62  rimental and sub
1beb0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a  ject to change..
1bec0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
1bed0 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e  verload_function
1bee0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
1bef0 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65   char *zFuncName
1bf00 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a  , int nArg);../*
1bf10 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63  .** The interfac
1bf20 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  e to the virtual
1bf30 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
1bf40 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28   defined above (
1bf50 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20  back up.** to a 
1bf60 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62  comment remarkab
1bf70 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68  ly similar to th
1bf80 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65  is one) is curre
1bf90 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
1bfa0 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
1bfb0 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
1bfc0 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
1bfd0 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
1bfe0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
1bff0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
1c000 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
1c010 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
1c020 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
1c030 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
1c040 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
1c050 63 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65  chanism stablize
1c060 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
1c070 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
1c080 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
1c090 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
1c0a0 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
1c0b0 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a  his comment..**.
1c0c0 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  ****** EXPERIMEN
1c0d0 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f  TAL - subject to
1c0e0 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20   change without 
1c0f0 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  notice *********
1c100 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  *****.*/../*.** 
1c110 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64  CAPI3REF: A Hand
1c120 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c  le To An Open BL
1c130 4f 42 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  OB.**.** An inst
1c140 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c  ance of the foll
1c150 6f 77 69 6e 67 20 6f 70 61 71 75 65 20 73 74 72  owing opaque str
1c160 75 63 74 75 72 65 20 69 73 20 75 73 65 64 20 74  ucture is used t
1c170 6f 20 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 20  o .** represent 
1c180 61 6e 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 2e 20  an blob-handle. 
1c190 20 41 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 20 69   A blob-handle i
1c1a0 73 20 63 72 65 61 74 65 64 20 62 79 0a 2a 2a 20  s created by.** 
1c1b0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
1c1c0 65 6e 28 29 5d 20 61 6e 64 20 64 65 73 74 72 6f  en()] and destro
1c1d0 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
1c1e0 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  blob_close()]..*
1c1f0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * The [sqlite3_b
1c200 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20  lob_read()] and 
1c210 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
1c220 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ite()] interface
1c230 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  s.** can be used
1c240 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
1c250 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69  e small subsecti
1c260 6f 6e 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 2e  ons of the blob.
1c270 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 74 69 65 33  .** The [sqltie3
1c280 5f 62 6c 6f 62 5f 73 69 7a 65 28 29 5d 20 69 6e  _blob_size()] in
1c290 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1c2a0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  the size of the.
1c2b0 2a 2a 20 62 6c 6f 62 20 69 6e 20 62 79 74 65 73  ** blob in bytes
1c2c0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1c2d0 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  uct sqlite3_blob
1c2e0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a   sqlite3_blob;..
1c2f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c300 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20  Open A BLOB For 
1c310 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a  Incremental I/O.
1c320 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 61 20 68 61 6e  **.** Open a han
1c330 64 6c 65 20 74 6f 20 74 68 65 20 62 6c 6f 62 20  dle to the blob 
1c340 6c 6f 63 61 74 65 64 20 69 6e 20 72 6f 77 20 69  located in row i
1c350 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f  Row,, column zCo
1c360 6c 75 6d 6e 2c 20 0a 2a 2a 20 74 61 62 6c 65 20  lumn, .** table 
1c370 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61  zTable in databa
1c380 73 65 20 7a 44 62 2e 20 69 2e 65 2e 20 74 68 65  se zDb. i.e. the
1c390 20 73 61 6d 65 20 62 6c 6f 62 20 74 68 61 74 20   same blob that 
1c3a0 77 6f 75 6c 64 0a 2a 2a 20 62 65 20 73 65 6c 65  would.** be sele
1c3b0 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c  cted by:.**.** <
1c3c0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45  pre>.**     SELE
1c3d0 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20  CT zColumn FROM 
1c3e0 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45  zDb.zTable WHERE
1c3f0 20 72 6f 77 69 64 20 3d 20 69 52 6f 77 3b 0a 2a   rowid = iRow;.*
1c400 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 49  * </pre>.**.** I
1c410 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  f the flags para
1c420 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72  meter is non-zer
1c430 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20 6f  o, the blob is o
1c440 70 65 6e 65 64 20 66 6f 72 20 0a 2a 2a 20 72 65  pened for .** re
1c450 61 64 20 61 6e 64 20 77 72 69 74 65 20 61 63 63  ad and write acc
1c460 65 73 73 2e 20 49 66 20 69 74 20 69 73 20 7a 65  ess. If it is ze
1c470 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20  ro, the blob is 
1c480 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20  opened for read 
1c490 0a 2a 2a 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  .** access..**.*
1c4a0 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53  * On success, [S
1c4b0 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
1c4c0 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65  urned and the ne
1c4d0 77 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  w .** [sqlite3_b
1c4e0 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c  lob | blob handl
1c4f0 65 5d 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  e] is written to
1c500 20 2a 70 70 42 6c 6f 62 2e 0a 2a 2a 20 4f 74 68   *ppBlob..** Oth
1c510 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
1c520 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
1c530 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 20 76 61 6c   and .** any val
1c540 75 65 20 77 72 69 74 74 65 6e 20 74 6f 20 2a 70  ue written to *p
1c550 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e 6f 74  pBlob should not
1c560 20 62 65 20 75 73 65 64 20 62 79 20 74 68 65 20   be used by the 
1c570 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69 73 20  caller..** This 
1c580 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68  function sets th
1c590 65 20 64 61 74 61 62 61 73 65 2d 68 61 6e 64 6c  e database-handl
1c5a0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  e error code and
1c5b0 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63 65   message.** acce
1c5c0 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69  ssible via [sqli
1c5d0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 61  te3_errcode()] a
1c5e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
1c5f0 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  sg()]..*/.int sq
1c600 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
1c610 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63  .  sqlite3*,.  c
1c620 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a  onst char *zDb,.
1c630 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54    const char *zT
1c640 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68  able,.  const ch
1c650 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73  ar *zColumn,.  s
1c660 71 6c 69 74 65 5f 69 6e 74 36 34 20 69 52 6f 77  qlite_int64 iRow
1c670 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20  ,.  int flags,. 
1c680 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a   sqlite3_blob **
1c690 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ppBlob.);../*.**
1c6a0 20 43 41 50 49 33 52 45 46 3a 20 20 43 6c 6f 73   CAPI3REF:  Clos
1c6b0 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 0a  e A BLOB Handle.
1c6c0 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 20 61 6e 20 6f  **.** Close an o
1c6d0 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  pen [sqlite3_blo
1c6e0 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c 65 5d  b | blob handle]
1c6f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1c700 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69  _blob_close(sqli
1c710 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a  te3_blob *);../*
1c720 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 52  .** CAPI3REF:  R
1c730 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f  eturn The Size O
1c740 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a  f An Open BLOB.*
1c750 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
1c760 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66  size in bytes of
1c770 20 74 68 65 20 62 6c 6f 62 20 61 63 63 65 73 73   the blob access
1c780 69 62 6c 65 20 76 69 61 20 74 68 65 20 6f 70 65  ible via the ope
1c790 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  n .** [sqlite3_b
1c7a0 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c  lob | blob-handl
1c7b0 65 5d 20 70 61 73 73 65 64 20 61 73 20 61 6e 20  e] passed as an 
1c7c0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74  argument..*/.int
1c7d0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79   sqlite3_blob_by
1c7e0 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  tes(sqlite3_blob
1c7f0 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   *);../*.** CAPI
1c800 33 52 45 46 3a 20 20 52 65 61 64 20 44 61 74 61  3REF:  Read Data
1c810 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63   From A BLOB Inc
1c820 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a  rementally.**.**
1c830 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
1c840 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 64  s used to read d
1c850 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e  ata from an open
1c860 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c   .** [sqlite3_bl
1c870 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65  ob | blob-handle
1c880 5d 20 69 6e 74 6f 20 61 20 63 61 6c 6c 65 72 20  ] into a caller 
1c890 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e  supplied buffer.
1c8a0 0a 2a 2a 20 6e 20 62 79 74 65 73 20 6f 66 20 64  .** n bytes of d
1c8b0 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 69  ata are copied i
1c8c0 6e 74 6f 20 62 75 66 66 65 72 0a 2a 2a 20 7a 20  nto buffer.** z 
1c8d0 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 62 6c  from the open bl
1c8e0 6f 62 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20  ob, starting at 
1c8f0 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a  offset iOffset..
1c900 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
1c910 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  , SQLITE_OK is r
1c920 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69  eturned. Otherwi
1c930 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49  se, an .** [SQLI
1c940 54 45 5f 45 52 52 4f 52 20 7c 20 53 51 4c 69 74  TE_ERROR | SQLit
1c950 65 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72  e error code] or
1c960 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   an.** [SQLITE_I
1c970 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
1c980 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
1c990 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f   is returned..*/
1c9a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
1c9b0 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62  b_read(sqlite3_b
1c9c0 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 7a 2c 20  lob *, void *z, 
1c9d0 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73  int n, int iOffs
1c9e0 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
1c9f0 33 52 45 46 3a 20 20 57 72 69 74 65 20 44 61 74  3REF:  Write Dat
1ca00 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e  a Into A BLOB In
1ca10 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a  crementally.**.*
1ca20 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
1ca30 69 73 20 75 73 65 64 20 74 6f 20 77 72 69 74 65  is used to write
1ca40 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70   data into an op
1ca50 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
1ca60 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64  blob | blob-hand
1ca70 6c 65 5d 20 66 72 6f 6d 20 61 20 75 73 65 72 20  le] from a user 
1ca80 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e  supplied buffer.
1ca90 0a 2a 2a 20 6e 20 62 79 74 65 73 20 6f 66 20 64  .** n bytes of d
1caa0 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 66  ata are copied f
1cab0 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 0a 2a  rom the buffer.*
1cac0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
1cad0 7a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20  z into the open 
1cae0 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e 67 20 61  blob, starting a
1caf0 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74  t offset iOffset
1cb00 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
1cb10 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62  sqlite3_blob | b
1cb20 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61 73 73  lob-handle] pass
1cb30 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
1cb40 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  argument.** was 
1cb50 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 20 77  not opened for w
1cb60 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67  riting (the flag
1cb70 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  s parameter to [
1cb80 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
1cb90 6e 28 29 5d 0a 2a 2a 2a 20 77 61 73 20 7a 65 72  n()].*** was zer
1cba0 6f 29 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  o), this functio
1cbb0 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  n returns [SQLIT
1cbc0 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a  E_READONLY]..**.
1cbd0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
1cbe0 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79   may only modify
1cbf0 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66   the contents of
1cc00 20 74 68 65 20 62 6c 6f 62 2c 20 69 74 20 69 73   the blob, it is
1cc10 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  .** not possible
1cc20 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65   to increase the
1cc30 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20   size of a blob 
1cc40 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 20  using this API. 
1cc50 49 66 0a 2a 2a 20 6f 66 66 73 65 74 20 69 4f 66  If.** offset iOf
1cc60 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61  fset is less tha
1cc70 6e 20 6e 20 62 79 74 65 73 20 66 72 6f 6d 20 74  n n bytes from t
1cc80 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 62 6c  he end of the bl
1cc90 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ob, .** [SQLITE_
1cca0 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
1ccb0 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
1ccc0 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a  s written..**.**
1ccd0 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c   On success, SQL
1cce0 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
1ccf0 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 61  ed. Otherwise, a
1cd00 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
1cd10 52 4f 52 20 7c 20 53 51 4c 69 74 65 20 65 72 72  ROR | SQLite err
1cd20 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  or code] or an.*
1cd30 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  * [SQLITE_IOERR_
1cd40 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
1cd50 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
1cd60 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  eturned..*/.int 
1cd70 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
1cd80 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  te(sqlite3_blob 
1cd90 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  *, const void *z
1cda0 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66  , int n, int iOf
1cdb0 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 55 6e  fset);../*.** Un
1cdc0 64 6f 20 74 68 65 20 68 61 63 6b 20 74 68 61 74  do the hack that
1cdd0 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f 61 74 69   converts floati
1cde0 6e 67 20 70 6f 69 6e 74 20 74 79 70 65 73 20 74  ng point types t
1cdf0 6f 20 69 6e 74 65 67 65 72 20 66 6f 72 0a 2a 2a  o integer for.**
1ce00 20 62 75 69 6c 64 73 20 6f 6e 20 70 72 6f 63 65   builds on proce
1ce10 73 73 6f 72 73 20 77 69 74 68 6f 75 74 20 66 6c  ssors without fl
1ce20 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70  oating point sup
1ce30 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  port..*/.#ifdef 
1ce40 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41  SQLITE_OMIT_FLOA
1ce50 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 75 6e 64  TING_POINT.# und
1ce60 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e 64 69 66  ef double.#endif
1ce70 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73  ..#ifdef __cplus
1ce80 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e 64 20 6f  plus.}  /* End o
1ce90 66 20 74 68 65 20 27 65 78 74 65 72 6e 20 22 43  f the 'extern "C
1cea0 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64  "' block */.#end
1ceb0 69 66 0a 23 65 6e 64 69 66 0a                    if.#endif.