/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact 42ec2b1e9186f08461d90b8268d06d3ae5cd9487:


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 33 20 32 30 30 37 2f  in,v 1.213 2007/
05f0: 30 36 2f 32 30 20 30 39 3a 30 39 3a 34 38 20 64  06/20 09:09:48 d
0600: 61 6e 69 65 6c 6b 31 39 37 37 20 45 78 70 20 24  anielk1977 Exp $
0610: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
0620: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
0630: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0640: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0650: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0660: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0670: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0680: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0690: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
06a0: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
06b0: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
06c0: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
06d0: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  " {.#endif../*.*
06e0: 2a 20 4d 61 6b 65 20 73 75 72 65 20 74 68 65 73  * Make sure thes
06f0: 65 20 73 79 6d 62 6f 6c 73 20 77 68 65 72 65 20  e symbols where 
0700: 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 73  not defined by s
0710: 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 61  ome previous hea
0720: 64 65 72 0a 2a 2a 20 66 69 6c 65 2e 0a 2a 2f 0a  der.** file..*/.
0730: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45  #ifdef SQLITE_VE
0740: 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51  RSION.# undef SQ
0750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e  LITE_VERSION.#en
0760: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54  dif.#ifdef SQLIT
0770: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0780: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0790: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
07a0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
07b0: 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
07c0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
07d0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a  ion Numbers.**.*
07e0: 2a 20 54 68 65 20 76 65 72 73 69 6f 6e 20 6f 66  * The version of
07f0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
0800: 61 72 79 20 69 73 20 63 6f 6e 74 61 69 6e 65 64  ary is contained
0810: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 2e   in the sqlite3.
0820: 68 0a 2a 2a 20 68 65 61 64 65 72 20 66 69 6c 65  h.** header file
0830: 20 69 6e 20 61 20 23 64 65 66 69 6e 65 20 6e 61   in a #define na
0840: 6d 65 64 20 53 51 4c 49 54 45 5f 56 45 52 53 49  med SQLITE_VERSI
0850: 4f 4e 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ON.  The SQLITE_
0860: 56 45 52 53 49 4f 4e 0a 2a 2a 20 6d 61 63 72 6f  VERSION.** macro
0870: 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 20 73   resolves to a s
0880: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 0a  tring constant..
0890: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 72 6d 61 74  **.** The format
08a0: 20 6f 66 20 74 68 65 20 76 65 72 73 69 6f 6e 20   of the version 
08b0: 73 74 72 69 6e 67 20 69 73 20 22 58 2e 59 2e 5a  string is "X.Y.Z
08c0: 22 2c 20 77 68 65 72 65 0a 2a 2a 20 58 20 69 73  ", where.** X is
08d0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
08e0: 6f 6e 20 6e 75 6d 62 65 72 2c 20 59 20 69 73 20  on number, Y is 
08f0: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
0900: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 0a 2a  n number and Z.*
0910: 2a 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65  * is the release
0920: 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 58 2e   number.  The X.
0930: 59 2e 5a 20 6d 69 67 68 74 20 62 65 20 66 6f 6c  Y.Z might be fol
0940: 6c 6f 77 65 64 20 62 79 20 22 61 6c 70 68 61 22  lowed by "alpha"
0950: 20 6f 72 20 22 62 65 74 61 22 2e 0a 2a 2a 20 46   or "beta"..** F
0960: 6f 72 20 65 78 61 6d 70 6c 65 20 22 33 2e 31 2e  or example "3.1.
0970: 31 62 65 74 61 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  1beta"..**.** Th
0980: 65 20 58 20 76 61 6c 75 65 20 69 73 20 61 6c 77  e X value is alw
0990: 61 79 73 20 33 20 69 6e 20 53 51 4c 69 74 65 2e  ays 3 in SQLite.
09a0: 20 20 54 68 65 20 58 20 76 61 6c 75 65 20 6f 6e    The X value on
09b0: 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e 0a  ly changes when.
09c0: 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
09d0: 70 61 74 69 62 69 6c 69 74 79 20 69 73 20 62 72  patibility is br
09e0: 6f 6b 65 6e 20 61 6e 64 20 77 65 20 69 6e 74 65  oken and we inte
09f0: 6e 64 20 74 6f 20 6e 65 76 65 72 20 62 72 65 61  nd to never brea
0a00: 6b 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  k.** backwards c
0a10: 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 54  ompatibility.  T
0a20: 68 65 20 59 20 76 61 6c 75 65 20 6f 6e 6c 79 20  he Y value only 
0a30: 63 68 61 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20  changes when.** 
0a40: 74 68 65 72 65 20 61 72 65 20 6d 61 6a 6f 72 20  there are major 
0a50: 66 65 61 74 75 72 65 20 65 6e 68 61 6e 63 65 6d  feature enhancem
0a60: 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 66 6f  ents that are fo
0a70: 72 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c  rwards compatibl
0a80: 65 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 62 61 63  e.** but not bac
0a90: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c  kwards compatibl
0aa0: 65 2e 20 20 54 68 65 20 5a 20 76 61 6c 75 65 20  e.  The Z value 
0ab0: 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 77  is incremented w
0ac0: 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c 65  ith.** each rele
0ad0: 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20 62  ase but resets b
0ae0: 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 20 59 20  ack to 0 when Y 
0af0: 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e 0a  is incremented..
0b00: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
0b10: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0b20: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 69  is an integer wi
0b30: 74 68 20 74 68 65 20 76 61 6c 75 65 20 0a 2a 2a  th the value .**
0b40: 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a   (X*1000000 + Y*
0b50: 31 30 30 30 20 2b 20 5a 29 2e 20 46 6f 72 20 65  1000 + Z). For e
0b60: 78 61 6d 70 6c 65 2c 20 66 6f 72 20 76 65 72 73  xample, for vers
0b70: 69 6f 6e 20 22 33 2e 31 2e 31 62 65 74 61 22 2c  ion "3.1.1beta",
0b80: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 56 45 52 53   .** SQLITE_VERS
0b90: 49 4f 4e 5f 4e 55 4d 42 45 52 20 69 73 20 73 65  ION_NUMBER is se
0ba0: 74 20 74 6f 20 33 30 30 31 30 30 31 2e 20 54 6f  t to 3001001. To
0bb0: 20 64 65 74 65 63 74 20 69 66 20 74 68 65 79 20   detect if they 
0bc0: 61 72 65 20 75 73 69 6e 67 20 0a 2a 2a 20 76 65  are using .** ve
0bd0: 72 73 69 6f 6e 20 33 2e 31 2e 31 20 6f 72 20 67  rsion 3.1.1 or g
0be0: 72 65 61 74 65 72 20 61 74 20 63 6f 6d 70 69 6c  reater at compil
0bf0: 65 20 74 69 6d 65 2c 20 70 72 6f 67 72 61 6d 73  e time, programs
0c00: 20 6d 61 79 20 75 73 65 20 74 68 65 20 74 65 73   may use the tes
0c10: 74 20 0a 2a 2a 20 28 53 51 4c 49 54 45 5f 56 45  t .** (SQLITE_VE
0c20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 3e 3d 33 30  RSION_NUMBER>=30
0c30: 30 31 30 30 31 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  01001)..**.** Se
0c40: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
0c50: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61  _libversion()] a
0c60: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  nd [sqlite3_libv
0c70: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d  ersion_number()]
0c80: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
0c90: 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20  ITE_VERSION     
0ca0: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
0cb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0cc0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
0cd0: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
0ce0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
0cf0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
0d00: 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72  y Version Number
0d10: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
0d20: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 76 61  utines return va
0d30: 6c 75 65 73 20 65 71 75 69 76 61 6c 65 6e 74 20  lues equivalent 
0d40: 74 6f 20 74 68 65 20 68 65 61 64 65 72 20 63 6f  to the header co
0d50: 6e 73 74 61 6e 74 73 0a 2a 2a 20 5b 53 51 4c 49  nstants.** [SQLI
0d60: 54 45 5f 56 45 52 53 49 4f 4e 5d 20 61 6e 64 20  TE_VERSION] and 
0d70: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
0d80: 4e 55 4d 42 45 52 5d 2e 20 20 54 68 65 20 76 61  NUMBER].  The va
0d90: 6c 75 65 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  lues returned.**
0da0: 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
0db0: 73 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65  s should only be
0dc0: 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
0dd0: 74 68 65 20 68 65 61 64 65 72 20 76 61 6c 75 65  the header value
0de0: 73 0a 2a 2a 20 69 66 20 79 6f 75 20 63 6f 6d 70  s.** if you comp
0df0: 69 6c 65 20 79 6f 75 72 20 70 72 6f 67 72 61 6d  ile your program
0e00: 20 75 73 69 6e 67 20 61 6e 20 73 71 6c 69 74 65   using an sqlite
0e10: 33 2e 68 20 68 65 61 64 65 72 20 66 72 6f 6d 20  3.h header from 
0e20: 61 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 76  a.** different v
0e30: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
0e40: 20 74 68 61 74 20 74 68 65 20 76 65 72 73 69 6f   that the versio
0e50: 6e 20 6f 66 20 74 68 65 20 6c 69 62 72 61 72 79  n of the library
0e60: 20 79 6f 75 0a 2a 2a 20 6c 69 6e 6b 20 61 67 61   you.** link aga
0e70: 69 6e 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  inst..**.** The 
0e80: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
0e90: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
0ea0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
0eb0: 65 78 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 53  ext of the.** [S
0ec0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73  QLITE_VERSION] s
0ed0: 74 72 69 6e 67 2e 20 20 54 68 65 20 73 71 6c 69  tring.  The sqli
0ee0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
0ef0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
0f00: 73 0a 2a 2a 20 61 20 70 6f 69 6e 65 72 20 74 6f  s.** a poiner to
0f10: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72   the sqlite3_ver
0f20: 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f  sion[] string co
0f30: 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 66 75 6e  nstant.  The fun
0f40: 63 74 69 6f 6e 0a 2a 2a 20 69 73 20 70 72 6f 76  ction.** is prov
0f50: 69 64 65 64 20 66 6f 72 20 44 4c 4c 20 75 73 65  ided for DLL use
0f60: 72 73 20 77 68 6f 20 63 61 6e 20 6f 6e 6c 79 20  rs who can only 
0f70: 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
0f80: 20 61 6e 64 20 6e 6f 74 0a 2a 2a 20 63 6f 6e 73   and not.** cons
0f90: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
0fa0: 20 44 4c 4c 2e 0a 2a 2f 0a 65 78 74 65 72 6e 20   DLL..*/.extern 
0fb0: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
0fc0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f  e3_version[];.co
0fd0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
0fe0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69  3_libversion(voi
0ff0: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
1000: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
1010: 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  r(void);../*.** 
1020: 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
1030: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61  se Connection Ha
1040: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  ndle.**.** Each 
1050: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61  open SQLite data
1060: 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e  base is represen
1070: 74 65 64 20 62 79 20 70 6f 69 6e 74 65 72 20 74  ted by pointer t
1080: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
1090: 20 74 68 65 0a 2a 2a 20 6f 70 61 71 75 65 20 73   the.** opaque s
10a0: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
10b0: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
10c0: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
10d0: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
10e0: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
10f0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
1100: 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 69 6e 74 65  lite3_open] inte
1110: 72 66 61 63 65 20 69 73 20 69 74 73 20 63 6f 6e  rface is its con
1120: 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 6e 64 20  structor.** and 
1130: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5d 20  [sqlite3_close] 
1140: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  is its destructo
1150: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  r.  There are ma
1160: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61  ny other interfa
1170: 63 65 73 0a 2a 2a 20 28 73 75 63 68 20 61 73 20  ces.** (such as 
1180: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1190: 5f 76 32 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  _v2], [sqlite3_c
11a0: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5d 2c  reate_function],
11b0: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
11c0: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 20 74  _busy_timeout] t
11d0: 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65  o name but three
11e0: 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f  ) that are metho
11f0: 64 73 20 6f 6e 20 74 68 69 73 0a 2a 2a 20 6f 62  ds on this.** ob
1200: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ject..*/.typedef
1210: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20   struct sqlite3 
1220: 73 71 6c 69 74 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a  sqlite3;.../*.**
1230: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
1240: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a  t Integer Types.
1250: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 63 6f 6d 70 69  **.** Some compi
1260: 6c 65 72 73 20 64 6f 20 6e 6f 74 20 73 75 70 70  lers do not supp
1270: 6f 72 74 20 74 68 65 20 22 6c 6f 6e 67 20 6c 6f  ort the "long lo
1280: 6e 67 22 20 64 61 74 61 74 79 70 65 2e 20 20 53  ng" datatype.  S
1290: 6f 20 77 65 20 68 61 76 65 0a 2a 2a 20 74 6f 20  o we have.** to 
12a0: 64 6f 20 63 6f 6d 70 69 6c 65 72 2d 73 70 65 63  do compiler-spec
12b0: 69 66 69 63 20 74 79 70 65 64 65 66 73 20 66 6f  ific typedefs fo
12c0: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
12d0: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
12e0: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4d 61 6e  egers..**.** Man
12f0: 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
1300: 63 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 71  ce functions req
1310: 75 69 72 65 20 61 20 36 34 2d 62 69 74 20 69 6e  uire a 64-bit in
1320: 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 73 2e  teger arguments.
1330: 0a 2a 2a 20 54 68 6f 73 65 20 69 6e 74 65 72 66  .** Those interf
1340: 61 63 65 73 20 61 72 65 20 64 65 63 6c 61 72 65  aces are declare
1350: 64 20 75 73 69 6e 67 20 74 68 69 73 20 74 79 70  d using this typ
1360: 65 64 65 66 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  edef..*/.#ifdef 
1370: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
1380: 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49  E.  typedef SQLI
1390: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
13a0: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
13b0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53  pedef unsigned S
13c0: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
13d0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
13e0: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d  #elif defined(_M
13f0: 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e  SC_VER) || defin
1400: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
1410: 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74  .  typedef __int
1420: 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  64 sqlite_int64;
1430: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
1440: 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  ned __int64 sqli
1450: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65  te_uint64;.#else
1460: 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20  .  typedef long 
1470: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
1480: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
1490: 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c   unsigned long l
14a0: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75  ong int sqlite_u
14b0: 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 0a 2f  int64;.#endif../
14c0: 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e  *.** If compilin
14d0: 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f  g for a processo
14e0: 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f  r that lacks flo
14f0: 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70  ating point supp
1500: 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75  ort,.** substitu
1510: 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66  te integer for f
1520: 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 0a 2a 2f  loating-point.*/
1530: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f  .#ifdef SQLITE_O
1540: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49  MIT_FLOATING_POI
1550: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62  NT.# define doub
1560: 6c 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 0a  le sqlite_int64.
1570: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
1580: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
1590: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
15a0: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  ction.**.** Call
15b0: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 77   this function w
15c0: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ith a pointer to
15d0: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
15e0: 74 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79  t was previously
15f0: 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f  .** returned fro
1600: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
1610: 29 5d 20 61 6e 64 20 74 68 65 20 63 6f 72 72 65  )] and the corre
1620: 73 70 6f 6e 64 69 6e 67 20 64 61 74 61 62 61 73  sponding databas
1630: 65 20 77 69 6c 6c 20 62 79 0a 2a 2a 20 63 6c 6f  e will by.** clo
1640: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20 53  sed..**.** All S
1650: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 72  QL statements pr
1660: 65 70 61 72 65 64 20 75 73 69 6e 67 20 5b 73 71  epared using [sq
1670: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1680: 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1690: 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
16a0: 29 5d 20 6d 75 73 74 20 62 65 20 64 65 73 74 72  )] must be destr
16b0: 6f 79 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  oyed using [sqli
16c0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
16d0: 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 72  ** before this r
16e0: 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
16f0: 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 53 51 4c  . Otherwise, SQL
1700: 49 54 45 5f 42 55 53 59 20 69 73 20 72 65 74 75  ITE_BUSY is retu
1710: 72 6e 65 64 20 61 6e 64 20 74 68 65 0a 2a 2a 20  rned and the.** 
1720: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1730: 69 6f 6e 20 72 65 6d 61 69 6e 73 20 6f 70 65 6e  ion remains open
1740: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1750: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a  _close(sqlite3 *
1760: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
1770: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
1780: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
1790: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
17a0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
17b0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
17c0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
17d0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
17e0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
17f0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
1800: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
1810: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
1820: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
1830: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1840: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
1850: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
1860: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 69  erface.**.** Thi
1870: 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  s interface is u
1880: 73 65 64 20 74 6f 20 64 6f 20 61 20 6f 6e 65 2d  sed to do a one-
1890: 74 69 6d 65 20 65 76 61 6c 75 61 74 61 74 69 6f  time evaluatatio
18a0: 6e 20 6f 66 20 7a 65 72 6f 0a 2a 2a 20 6f 72 20  n of zero.** or 
18b0: 6d 6f 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  more SQL stateme
18c0: 6e 74 73 2e 20 20 55 54 46 2d 38 20 74 65 78 74  nts.  UTF-8 text
18d0: 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   of the SQL stat
18e0: 65 6d 65 6e 74 73 20 74 6f 0a 2a 2a 20 62 65 20  ements to.** be 
18f0: 65 76 61 6c 75 74 65 64 20 69 73 20 70 61 73 73  evaluted is pass
1900: 65 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63  ed in as the sec
1910: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
1920: 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  The statements.*
1930: 2a 20 61 72 65 20 70 72 65 70 61 72 65 64 20 6f  * are prepared o
1940: 6e 65 20 62 79 20 6f 6e 65 20 75 73 69 6e 67 20  ne by one using 
1950: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1960: 28 29 5d 2c 20 65 76 61 6c 75 61 74 65 64 0a 2a  ()], evaluated.*
1970: 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
1980: 5f 73 74 65 70 28 29 5d 2c 20 74 68 65 6e 20 64  _step()], then d
1990: 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 20 5b  estroyed using [
19a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
19b0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 6e  ()]..**.** If on
19c0: 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
19d0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
19e0: 61 72 65 20 71 75 65 72 69 65 73 2c 20 74 68 65  are queries, the
19f0: 6e 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 62 61 63  n.** the callbac
1a00: 6b 20 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69  k function speci
1a10: 66 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20  fied by the 3rd 
1a20: 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1a30: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
1a40: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65   each row of the
1a50: 20 71 75 65 72 79 20 72 65 73 75 6c 74 2e 20 20   query result.  
1a60: 54 68 69 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  This callback.**
1a70: 20 73 68 6f 75 6c 64 20 6e 6f 72 6d 61 6c 6c 79   should normally
1a80: 20 72 65 74 75 72 6e 20 30 2e 20 20 49 66 20 74   return 0.  If t
1a90: 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1aa0: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  rns a non-zero.*
1ab0: 2a 20 76 61 6c 75 65 20 74 68 65 6e 20 74 68 65  * value then the
1ac0: 20 71 75 65 72 79 20 69 73 20 61 62 6f 72 74 65   query is aborte
1ad0: 64 2c 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  d, all subsequen
1ae0: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
1af0: 0a 2a 2a 20 61 72 65 20 73 6b 69 70 70 65 64 20  .** are skipped 
1b00: 61 6e 64 20 74 68 65 20 73 71 6c 69 74 65 33 5f  and the sqlite3_
1b10: 65 78 65 63 28 29 20 66 75 6e 63 74 69 6f 6e 20  exec() function 
1b20: 72 65 74 75 72 6e 73 20 74 68 65 20 53 51 4c 49  returns the SQLI
1b30: 54 45 5f 41 42 4f 52 54 2e 0a 2a 2a 0a 2a 2a 20  TE_ABORT..**.** 
1b40: 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  The 4th paramete
1b50: 72 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66  r to this interf
1b60: 61 63 65 20 69 73 20 61 6e 20 61 72 62 69 74 72  ace is an arbitr
1b70: 61 72 79 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ary pointer that
1b80: 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
1b90: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c  rough to the cal
1ba0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 61  lback function a
1bb0: 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61  s its first para
1bc0: 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  meter..**.** The
1bd0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
1be0: 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  o the callback f
1bf0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 20 6e  unction is the n
1c00: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 6f 6c 75  umber of.** colu
1c10: 6d 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  mns in the query
1c20: 20 72 65 73 75 6c 74 2e 20 20 54 68 65 20 33 72   result.  The 3r
1c30: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
1c40: 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  he callback.** i
1c50: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 73 74  s an array of st
1c60: 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68  rings holding th
1c70: 65 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63  e values for eac
1c80: 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 73 20 65  h column.** as e
1c90: 78 74 72 61 63 74 65 64 20 75 73 69 6e 67 20 5b  xtracted using [
1ca0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1cb0: 65 78 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 34  ext()]..** The 4
1cc0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1cd0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1ce0: 61 6e 20 61 72 72 61 79 20 6f 66 20 73 74 72 69  an array of stri
1cf0: 6e 67 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20  ngs.** obtained 
1d00: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
1d10: 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e  olumn_name()] an
1d20: 64 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 74 68 65  d holding.** the
1d30: 20 6e 61 6d 65 73 20 6f 66 20 65 61 63 68 20 63   names of each c
1d40: 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  olumn..**.** The
1d50: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1d60: 6f 6e 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20  on may be NULL, 
1d70: 65 76 65 6e 20 66 6f 72 20 71 75 65 72 69 65 73  even for queries
1d80: 2e 20 20 41 20 4e 55 4c 4c 0a 2a 2a 20 63 61 6c  .  A NULL.** cal
1d90: 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 61 6e 20  lback is not an 
1da0: 65 72 72 6f 72 2e 20 20 49 74 20 6a 75 73 74 20  error.  It just 
1db0: 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 63 61  means that no ca
1dc0: 6c 6c 62 61 63 6b 0a 2a 2a 20 77 69 6c 6c 20 62  llback.** will b
1dd0: 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  e invoked..**.**
1de0: 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   If an error occ
1df0: 75 72 73 20 77 68 69 6c 65 20 70 61 72 73 69 6e  urs while parsin
1e00: 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20  g or evaluating 
1e10: 74 68 65 20 53 51 4c 20 28 62 75 74 0a 2a 2a 20  the SQL (but.** 
1e20: 6e 6f 74 20 77 68 69 6c 65 20 65 78 65 63 75 74  not while execut
1e30: 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ing the callback
1e40: 29 20 74 68 65 6e 20 61 6e 20 61 70 70 72 6f 70  ) then an approp
1e50: 72 69 61 74 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  riate error.** m
1e60: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
1e70: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
1e80: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
1e90: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
1ea0: 6e 64 0a 2a 2a 20 2a 65 72 72 6d 73 67 20 69 73  nd.** *errmsg is
1eb0: 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
1ec0: 6f 20 74 68 61 74 20 6d 65 73 73 61 67 65 2e 20  o that message. 
1ed0: 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   The calling fun
1ee0: 63 74 69 6f 6e 0a 2a 2a 20 69 73 20 72 65 73 70  ction.** is resp
1ef0: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
1f00: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ing the memory t
1f10: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 65 72  hat holds the er
1f20: 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 2e 20  ror.** message. 
1f30: 20 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 66    Use [sqlite3_f
1f40: 72 65 65 28 29 5d 20 66 6f 72 20 74 68 69 73 2e  ree()] for this.
1f50: 20 20 49 66 20 65 72 72 6d 73 67 3d 3d 4e 55 4c    If errmsg==NUL
1f60: 4c 2c 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 65 72  L,.** then no er
1f70: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 65  ror message is e
1f80: 76 65 72 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a  ver written..**.
1f90: 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  ** The return va
1fa0: 6c 75 65 20 69 73 20 69 73 20 53 51 4c 49 54 45  lue is is SQLITE
1fb0: 5f 4f 4b 20 69 66 20 74 68 65 72 65 20 61 72 65  _OK if there are
1fc0: 20 6e 6f 20 65 72 72 6f 72 73 20 61 6e 64 0a 2a   no errors and.*
1fd0: 2a 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 53 51  * some other [SQ
1fe0: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 74 75 72 6e  LITE_OK | return
1ff0: 20 63 6f 64 65 5d 20 69 66 20 74 68 65 72 65 20   code] if there 
2000: 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 20 0a 2a  is an error.  .*
2010: 2a 20 54 68 65 20 70 61 72 74 69 63 75 6c 61 72  * The particular
2020: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 64 65   return value de
2030: 70 65 6e 64 73 20 6f 6e 20 74 68 65 20 74 79 70  pends on the typ
2040: 65 20 6f 66 20 65 72 72 6f 72 2e 20 0a 2a 2a 0a  e of error. .**.
2050: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
2060: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  xec(.  sqlite3*,
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 20 20 20 20 20 20                  
2090: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
20a0: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
20b0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
20c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20d0: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
20e0: 62 65 20 65 76 61 6c 75 74 65 64 20 2a 2f 0a 20  be evaluted */. 
20f0: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
2100: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
2110: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
2120: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2130: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
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 20 20 20 20 20 20 20                  
2160: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
2170: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
2180: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
2190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
21b0: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
21c0: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
21d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
21e0: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
21f0: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
2200: 4b 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c  K.**.** Many SQL
2210: 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ite functions re
2220: 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20  turn an integer 
2230: 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d  result code from
2240: 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a   the set shown.*
2250: 2a 20 61 62 6f 76 65 20 69 6e 20 6f 72 64 65 72  * above in order
2260: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
2270: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
2280: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 73 75  ..**.** The resu
2290: 6c 74 20 63 6f 64 65 73 20 61 62 6f 76 65 20 61  lt codes above a
22a0: 72 65 20 74 68 65 20 6f 6e 6c 79 20 6f 6e 65 73  re the only ones
22b0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
22c0: 69 74 65 20 69 6e 20 69 74 73 0a 2a 2a 20 64 65  ite in its.** de
22d0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
22e0: 69 6f 6e 2e 20 20 48 6f 77 65 76 65 72 2c 20 74  ion.  However, t
22f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  he [sqlite3_exte
2300: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
2310: 73 28 29 5d 0a 2a 2a 20 41 50 49 20 63 61 6e 20  s()].** API can 
2320: 62 65 20 75 73 65 64 20 74 6f 20 73 65 74 20 61  be used to set a
2330: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2340: 74 6f 69 6e 20 74 6f 20 72 65 74 75 72 6e 20 6d  toin to return m
2350: 6f 72 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  ore detailed.** 
2360: 72 65 73 75 6c 74 20 63 6f 64 65 73 2e 0a 2a 2a  result codes..**
2370: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53  .** See also: [S
2380: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
2390: 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
23a0: 6c 74 20 63 6f 64 65 73 5d 0a 2a 2a 0a 2a 2f 0a  lt codes].**.*/.
23b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
23c0: 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20  K           0   
23d0: 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65  /* Successful re
23e0: 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e  sult */./* begin
23f0: 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f  ning-of-error-co
2400: 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  des */.#define S
2410: 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20  QLITE_ERROR     
2420: 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72     1   /* SQL er
2430: 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64  ror or missing d
2440: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
2450: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e  ne SQLITE_INTERN
2460: 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 4e 4f  AL     2   /* NO
2470: 54 20 55 53 45 44 2e 20 49 6e 74 65 72 6e 61 6c  T USED. Internal
2480: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
2490: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
24a0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
24b0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
24c0: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
24d0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
24e0: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
24f0: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
2500: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
2510: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
2520: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2530: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
2540: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
2550: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
2560: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
2570: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
2580: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
2590: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
25a0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
25b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
25c0: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
25d0: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
25e0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
25f0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
2600: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
2610: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
2620: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
2630: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2640: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
2650: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
2660: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
2670: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
2680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2690: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
26a0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
26b0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
26c0: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
26d0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
26e0: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
26f0: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
2700: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
2710: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
2720: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
2730: 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53    12   /* NOT US
2740: 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63  ED. Table or rec
2750: 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f  ord not found */
2760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2770: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
2780: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
2790: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
27a0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
27b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27c0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
27d0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
27e0: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
27f0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
2800: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
2810: 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55     15   /* NOT U
2820: 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f  SED. Database lo
2830: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f  ck protocol erro
2840: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
2850: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20  ITE_EMPTY       
2860: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  16   /* Database
2870: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65   is empty */.#de
2880: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45  fine SQLITE_SCHE
2890: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20  MA      17   /* 
28a0: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  The database sch
28b0: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23  ema changed */.#
28c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f  define SQLITE_TO
28d0: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f  OBIG      18   /
28e0: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  * String or BLOB
28f0: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69   exceeds size li
2900: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mit */.#define S
2910: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
2920: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20    19   /* Abort 
2930: 64 75 65 20 74 6f 20 63 6f 6e 74 72 61 69 6e 74  due to contraint
2940: 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64   violation */.#d
2950: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
2960: 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a  MATCH    20   /*
2970: 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61   Data type misma
2980: 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tch */.#define S
2990: 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20  QLITE_MISUSE    
29a0: 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72    21   /* Librar
29b0: 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74  y used incorrect
29c0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
29d0: 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20  LITE_NOLFS      
29e0: 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53   22   /* Uses OS
29f0: 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75   features not su
2a00: 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20  pported on host 
2a10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2a20: 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33  E_AUTH        23
2a30: 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74     /* Authorizat
2a40: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
2a50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52  efine SQLITE_FOR
2a60: 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a  MAT      24   /*
2a70: 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62   Auxiliary datab
2a80: 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72  ase format error
2a90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2aa0: 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32  TE_RANGE       2
2ab0: 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d  5   /* 2nd param
2ac0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2ad0: 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67  bind out of rang
2ae0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
2af0: 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20  ITE_NOTADB      
2b00: 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65  26   /* File ope
2b10: 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ned that is not 
2b20: 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
2b30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2b40: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
2b50: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
2b60: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
2b70: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
2b80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
2b90: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
2ba0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2bb0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
2bc0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
2bd0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
2be0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
2bf0: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
2c00: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ult Codes.**.** 
2c10: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
2c20: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
2c30: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
2c40: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
2c50: 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 72 65  26 integer.** re
2c60: 73 75 6c 74 20 63 6f 64 65 73 20 64 65 73 63 72  sult codes descr
2c70: 69 62 65 64 20 61 74 20 72 65 73 75 6c 74 2d 63  ibed at result-c
2c80: 6f 64 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  odes.  However, 
2c90: 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73  experience has s
2ca0: 68 6f 77 6e 20 74 68 61 74 0a 2a 2a 20 6d 61 6e  hown that.** man
2cb0: 79 20 6f 66 20 74 68 65 73 65 20 72 65 73 75 6c  y of these resul
2cc0: 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20  t codes are too 
2cd0: 63 6f 75 72 73 65 2d 67 72 61 69 6e 65 64 2e 20  course-grained. 
2ce0: 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f   They do not pro
2cf0: 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20  vide as.** much 
2d00: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2d10: 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 75 73  t problems as us
2d20: 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20  ers might like. 
2d30: 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f   In an effort to
2d40: 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73  .** address this
2d50: 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  , newer versions
2d60: 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73   of SQLite (vers
2d70: 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61  ion 3.3.8 and la
2d80: 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20  ter) include.** 
2d90: 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69  support for addi
2da0: 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f  tional result co
2db0: 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65  des that provide
2dc0: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69   more detailed i
2dd0: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
2de0: 6f 75 74 20 65 72 72 6f 72 73 2e 20 20 54 68 65  out errors.  The
2df0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
2e00: 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c   codes are enabl
2e10: 65 64 20 28 6f 72 20 64 69 73 61 62 6c 65 64 29  ed (or disabled)
2e20: 20 66 6f 72 20 0a 2a 2a 20 65 61 63 68 20 64 61   for .** each da
2e30: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
2e40: 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 20 5b  tion using the [
2e50: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
2e60: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d  _result_codes()]
2e70: 20 41 50 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d   API..** .** Som
2e80: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
2e90: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
2ea0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
2eb0: 74 65 64 20 61 62 6f 76 65 2e 0a 2a 2a 20 57 65  ted above..** We
2ec0: 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62   expect the numb
2ed0: 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72  er of extended r
2ee0: 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c  esult codes will
2ef0: 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76   be expand.** ov
2f00: 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61  er time.  Softwa
2f10: 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74  re that uses ext
2f20: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
2f30: 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74  es should expect
2f40: 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72  .** to see new r
2f50: 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66  esult codes in f
2f60: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
2f70: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 0a 2a 2a  f SQLite..** .**
2f80: 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61   The symbolic na
2f90: 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64  me for an extend
2fa0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61  ed result code a
2fb0: 6c 77 61 79 73 20 63 6f 6e 74 61 69 6e 73 20 61  lways contains a
2fc0: 20 72 65 6c 61 74 65 64 0a 2a 2a 20 70 72 69 6d   related.** prim
2fd0: 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ary result code 
2fe0: 61 73 20 61 20 70 72 65 66 69 78 2e 20 20 50 72  as a prefix.  Pr
2ff0: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64  imary result cod
3000: 65 73 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e  es contain a sin
3010: 67 6c 65 0a 2a 2a 20 22 5f 22 20 63 68 61 72 61  gle.** "_" chara
3020: 63 74 65 72 2e 20 20 45 78 74 65 6e 64 65 64 20  cter.  Extended 
3030: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 63 6f 6e  result codes con
3040: 74 61 69 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65  tain two or more
3050: 20 22 5f 22 20 63 68 61 72 61 63 74 65 72 73 2e   "_" characters.
3060: 0a 2a 2a 20 54 68 65 20 6e 75 6d 65 72 69 63 20  .** The numeric 
3070: 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 74 65  value of an exte
3080: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
3090: 20 63 61 6e 20 62 65 20 63 6f 6e 76 65 72 74 65   can be converte
30a0: 64 20 74 6f 20 69 74 73 0a 2a 2a 20 63 6f 72 72  d to its.** corr
30b0: 65 73 70 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72  esponding primar
30c0: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 62 79  y result code by
30d0: 20 6d 61 73 6b 69 6e 67 20 6f 66 66 20 74 68 65   masking off the
30e0: 20 6c 6f 77 65 72 20 38 20 62 79 74 65 73 2e 0a   lower 8 bytes..
30f0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
3100: 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20  _OK result code 
3110: 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78  will never be ex
3120: 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c  tended.  It will
3130: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78   always.** be ex
3140: 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23  actly zero..*/.#
3150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3160: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20  ERR_READ        
3170: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
3180: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
3190: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
31a0: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 28 53 51  HORT_READ    (SQ
31b0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
31c0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
31d0: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
31e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
31f0: 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a  IOERR | (3<<8)).
3200: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3210: 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20  OERR_FSYNC      
3220: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
3230: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
3240: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
3250: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 28 53  DIR_FSYNC     (S
3260: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
3270: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
3280: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
3290: 41 54 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  ATE      (SQLITE
32a0: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
32b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
32c0: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
32d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
32e0: 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66  R | (7<<8)).#def
32f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3300: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 28  _UNLOCK        (
3310: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
3320: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
3330: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f  QLITE_IOERR_RDLO
3340: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  CK        (SQLIT
3350: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
3360: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3370: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
3380: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
3390: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
33a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
33b0: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
33c0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
33d0: 20 28 31 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a   (11<<8))../*.**
33e0: 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
33f0: 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
3400: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
3410: 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  es.**.** This ro
3420: 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
3430: 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
3440: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
3450: 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72  EAD | extended r
3460: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
3470: 74 75 72 65 2e 0a 2a 2a 20 42 79 20 64 65 66 61  ture..** By defa
3480: 75 6c 74 2c 20 53 51 4c 69 74 65 20 41 50 49 20  ult, SQLite API 
3490: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
34a0: 6f 6e 65 20 6f 66 20 6f 6e 6c 79 20 32 36 20 69  one of only 26 i
34b0: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
34c0: 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
34d0: 64 65 73 5d 2e 20 20 57 68 65 6e 20 65 78 74 65  des].  When exte
34e0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
34f0: 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
3500: 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
3510: 2c 20 74 68 65 20 72 65 70 65 74 6f 69 72 65 20  , the repetoire 
3520: 6f 66 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  of result codes 
3530: 63 61 6e 20 62 65 0a 2a 2a 20 6d 75 63 68 20 6c  can be.** much l
3540: 61 72 67 65 72 20 61 6e 64 20 63 61 6e 20 28 68  arger and can (h
3550: 6f 70 65 66 75 6c 6c 79 29 20 70 72 6f 76 69 64  opefully) provid
3560: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20  e more detailed 
3570: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
3580: 62 6f 75 74 20 74 68 65 20 63 61 75 73 65 20 6f  bout the cause o
3590: 66 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a  f an error..**.*
35a0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
35b0: 75 6d 65 6e 74 20 69 73 20 61 20 62 6f 6f 6c 65  ument is a boole
35c0: 61 6e 20 76 61 6c 75 65 20 74 68 61 74 20 74 75  an value that tu
35d0: 72 6e 73 20 65 78 74 65 6e 64 65 64 20 72 65 73  rns extended res
35e0: 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 6f 6e 20  ult.** codes on 
35f0: 61 6e 64 20 6f 66 66 2e 20 20 45 78 74 65 6e 64  and off.  Extend
3600: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3610: 61 72 65 20 6f 66 66 20 62 79 20 64 65 66 61 75  are off by defau
3620: 6c 74 20 66 6f 72 0a 2a 2a 20 62 61 63 6b 77 61  lt for.** backwa
3630: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
3640: 79 20 77 69 74 68 20 6f 6c 64 65 72 20 76 65 72  y with older ver
3650: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
3660: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
3670: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
3680: 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
3690: 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
36a0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
36b0: 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a  t Insert Rowid.*
36c0: 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20  *.** Each entry 
36d0: 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  in an SQLite tab
36e0: 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
36f0: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
3700: 74 65 67 65 72 20 6b 65 79 0a 2a 2a 20 63 61 6c  teger key.** cal
3710: 6c 65 64 20 74 68 65 20 22 72 6f 77 69 64 22 2e  led the "rowid".
3720: 20 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c   The rowid is al
3730: 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 20 61  ways available a
3740: 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 0a  s an undeclared.
3750: 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ** column named 
3760: 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
3770: 52 4f 57 49 44 5f 2e 20 20 49 66 20 74 68 65 20  ROWID_.  If the 
3780: 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
3790: 6d 6e 20 6f 66 0a 2a 2a 20 74 79 70 65 20 49 4e  mn of.** type IN
37a0: 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
37b0: 59 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  Y then that colu
37c0: 6d 6e 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6e  mn is another an
37d0: 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 0a 2a   alias for the.*
37e0: 2a 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54  * rowid..**.** T
37f0: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
3800: 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66  rns the rowid of
3810: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
3820: 20 49 4e 53 45 52 54 20 69 6e 74 6f 0a 2a 2a 20   INSERT into.** 
3830: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f  the database fro
3840: 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  m the database c
3850: 6f 6e 6e 65 63 74 69 6f 6e 20 67 69 76 65 6e 20  onnection given 
3860: 69 6e 20 74 68 65 20 66 69 72 73 74 20 0a 2a 2a  in the first .**
3870: 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e   argument.  If n
3880: 6f 20 69 6e 73 65 72 74 73 20 68 61 76 65 20 65  o inserts have e
3890: 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
38a0: 74 68 69 73 20 64 61 74 61 62 61 73 65 0a 2a 2a  this database.**
38b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72   connection, zer
38c0: 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
38d0: 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45 52  *.** If an INSER
38e0: 54 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  T occurs within 
38f0: 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20  a trigger, then 
3900: 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65  the rowid of the
3910: 0a 2a 2a 20 69 6e 73 65 72 74 65 64 20 72 6f 77  .** inserted row
3920: 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
3930: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20  this routine as 
3940: 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
3950: 67 65 72 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e  ger.** is runnin
3960: 67 2e 20 20 42 75 74 20 6f 6e 63 65 20 74 68 65  g.  But once the
3970: 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61   trigger termina
3980: 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  tes, the value r
3990: 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68  eturned.** by th
39a0: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
39b0: 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76  ts to the last v
39c0: 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65  alue inserted be
39d0: 66 6f 72 65 20 74 68 65 0a 2a 2a 20 74 72 69 67  fore the.** trig
39e0: 67 65 72 20 66 69 72 65 64 2e 0a 2a 2f 0a 73 71  ger fired..*/.sq
39f0: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74  lite_int64 sqlit
3a00: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
3a10: 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
3a20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
3a30: 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
3a40: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
3a50: 65 64 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  ed.**.** This fu
3a60: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
3a70: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
3a80: 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
3a90: 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
3aa0: 28 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20  (or inserted or 
3ab0: 64 65 6c 65 74 65 64 29 20 62 79 20 74 68 65 20  deleted) by the 
3ac0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 53 51 4c 20  most recent SQL 
3ad0: 73 74 61 74 65 6d 65 6e 74 2e 20 20 4f 6e 6c 79  statement.  Only
3ae0: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68 61 74  .** changes that
3af0: 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70   are directly sp
3b00: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 49  ecified by the I
3b10: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
3b20: 72 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74  r.** DELETE stat
3b30: 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
3b40: 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
3b50: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
3b60: 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20  ** triggers are 
3b70: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 55 73  not counted.  Us
3b80: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  e the [sqlite3_t
3b90: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
3ba0: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66  function.** to f
3bb0: 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  ind the total nu
3bc0: 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
3bd0: 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
3be0: 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
3bf0: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 57 69 74 68  gers..**.** With
3c00: 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
3c10: 20 74 72 69 67 67 65 72 2c 20 74 68 65 20 73 71   trigger, the sq
3c20: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
3c30: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
3c40: 0a 2a 2a 20 63 61 6c 6c 65 64 20 74 6f 20 66 69  .** called to fi
3c50: 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
3c60: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
3c70: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
3c80: 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
3c90: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
3ca0: 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
3cb0: 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
3cc0: 79 20 6f 66 20 74 68 65 20 74 72 69 67 67 65 72  y of the trigger
3cd0: 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20 63 68 61 6e  ..**.** All chan
3ce0: 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2c  ges are counted,
3cf0: 20 65 76 65 6e 20 69 66 20 74 68 65 79 20 77 65   even if they we
3d00: 72 65 20 6c 61 74 65 72 20 75 6e 64 6f 6e 65 20  re later undone 
3d10: 62 79 20 61 0a 2a 2a 20 52 4f 4c 4c 42 41 43 4b  by a.** ROLLBACK
3d20: 20 6f 72 20 41 42 4f 52 54 2e 20 20 45 78 63 65   or ABORT.  Exce
3d30: 70 74 2c 20 63 68 61 6e 67 65 73 20 61 73 73 6f  pt, changes asso
3d40: 63 69 61 74 65 64 20 77 69 74 68 20 63 72 65 61  ciated with crea
3d50: 74 69 6e 67 20 61 6e 64 0a 2a 2a 20 64 72 6f 70  ting and.** drop
3d60: 70 69 6e 67 20 74 61 62 6c 65 73 20 61 72 65 20  ping tables are 
3d70: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  not counted..**.
3d80: 2a 2a 20 49 66 20 61 20 63 61 6c 6c 62 61 63 6b  ** If a callback
3d90: 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65   invokes [sqlite
3da0: 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
3db0: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
3dc0: 63 75 72 73 69 76 65 6c 79 2c 0a 2a 2a 20 74 68  cursively,.** th
3dd0: 65 6e 20 74 68 65 20 63 68 61 6e 67 65 73 20 69  en the changes i
3de0: 6e 20 74 68 65 20 69 6e 6e 65 72 2c 20 72 65 63  n the inner, rec
3df0: 75 72 73 69 76 65 20 63 61 6c 6c 20 61 72 65 20  ursive call are 
3e00: 63 6f 75 6e 74 65 64 20 74 6f 67 65 74 68 65 72  counted together
3e10: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 63 68 61  .** with the cha
3e20: 6e 67 65 73 20 69 6e 20 74 68 65 20 6f 75 74 65  nges in the oute
3e30: 72 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 53 51  r call..**.** SQ
3e40: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
3e50: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
3e60: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
3e70: 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20  without a WHERE 
3e80: 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f  clause.** by dro
3e90: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
3ea0: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
3eb0: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66   (This is much f
3ec0: 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67  aster than going
3ed0: 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20  .** through and 
3ee0: 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64  deleting individ
3ef0: 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 6f 72  ual elements for
3f00: 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42  m the table.)  B
3f10: 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69  ecause of.** thi
3f20: 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20  s optimization, 
3f30: 74 68 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74  the change count
3f40: 20 66 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f   for "DELETE FRO
3f50: 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65  M table" will be
3f60: 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c  .** zero regardl
3f70: 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ess of the numbe
3f80: 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68  r of elements th
3f90: 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c  at were original
3fa0: 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62  ly in the.** tab
3fb0: 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63  le. To get an ac
3fc0: 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20  curate count of 
3fd0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
3fe0: 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a  ws deleted, use.
3ff0: 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  ** "DELETE FROM 
4000: 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69  table WHERE 1" i
4010: 6e 73 74 65 61 64 2e 0a 2a 2f 0a 69 6e 74 20 73  nstead..*/.int s
4020: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
4030: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
4040: 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
4050: 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
4060: 4d 6f 64 69 66 69 65 64 0a 2a 2a 2a 0a 2a 2a 20  Modified.***.** 
4070: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
4080: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
4090: 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
40a0: 73 20 74 68 61 74 20 68 61 76 65 20 62 65 65 6e  s that have been
40b0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 62 79 20  .** modified by 
40c0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
40d0: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
40e0: 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 64 61  nts since the da
40f0: 74 61 62 61 73 65 20 68 61 6e 64 6c 65 0a 2a 2a  tabase handle.**
4100: 20 77 61 73 20 6f 70 65 6e 65 64 2e 20 54 68 69   was opened. Thi
4110: 73 20 69 6e 63 6c 75 64 65 73 20 55 50 44 41 54  s includes UPDAT
4120: 45 2c 20 49 4e 53 45 52 54 20 61 6e 64 20 44 45  E, INSERT and DE
4130: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20  LETE statements 
4140: 65 78 65 63 75 74 65 64 0a 2a 2a 20 61 73 20 70  executed.** as p
4150: 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70  art of trigger p
4160: 72 6f 67 72 61 6d 73 2e 20 41 6c 6c 20 63 68 61  rograms. All cha
4170: 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  nges are counted
4180: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 0a   as soon as the.
4190: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
41a0: 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
41b0: 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
41c0: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
41d0: 6e 64 6c 65 20 69 73 0a 2a 2a 20 70 61 73 73 65  ndle is.** passe
41e0: 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
41f0: 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
4200: 65 5f 66 69 6e 61 6c 69 73 65 28 29 5d 29 2e 0a  e_finalise()])..
4210: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
4220: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
4230: 67 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ge()] interface.
4240: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d  .**.** SQLite im
4250: 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d  plements the com
4260: 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f  mand "DELETE FRO
4270: 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74  M table" without
4280: 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a   a WHERE clause.
4290: 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61  ** by dropping a
42a0: 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68  nd recreating th
42b0: 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20  e table.  (This 
42c0: 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74  is much faster t
42d0: 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72  han going.** thr
42e0: 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e  ough and deletin
42f0: 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65  g individual ele
4300: 6d 65 6e 74 73 20 66 6f 72 6d 20 74 68 65 20 74  ments form the t
4310: 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20  able.)  Because 
4320: 6f 66 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d  of.** this optim
4330: 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63 68 61  ization, the cha
4340: 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72 20 22 44  nge count for "D
4350: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
4360: 22 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72  " will be.** zer
4370: 6f 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  o regardless of 
4380: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c  the number of el
4390: 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65  ements that were
43a0: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74   originally in t
43b0: 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20  he.** table. To 
43c0: 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20  get an accurate 
43d0: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
43e0: 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65  ber of rows dele
43f0: 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c  ted, use.** "DEL
4400: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57  ETE FROM table W
4410: 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e  HERE 1" instead.
4420: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4430: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
4440: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
4450: 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
4460: 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
4470: 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54  ng Query.**.** T
4480: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
4490: 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
44a0: 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
44b0: 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
44c0: 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
44d0: 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
44e0: 75 6e 69 74 79 2e 20 20 54 68 69 73 20 72 6f 75  unity.  This rou
44f0: 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
4500: 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
4510: 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
4520: 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
4530: 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
4540: 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
4550: 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
4560: 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
4570: 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
4580: 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
4590: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ly..**.** It is 
45a0: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
45b0: 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
45c0: 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
45d0: 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
45e0: 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
45f0: 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
4600: 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
4610: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
4620: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
4630: 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
4640: 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
4650: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
4660: 5d 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  ]..** If an inte
4670: 72 72 75 70 74 65 64 20 6f 70 65 72 61 74 69 6f  rrupted operatio
4680: 6e 20 77 61 73 20 61 6e 20 75 70 64 61 74 65 20  n was an update 
4690: 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
46a0: 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
46b0: 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
46c0: 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
46d0: 61 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 72  action will be r
46e0: 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 61 75  olled.** back au
46f0: 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2f 0a  tomatically..*/.
4700: 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
4710: 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
4720: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
4730: 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
4740: 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
4750: 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
4760: 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
4770: 6e 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 69  ns return true i
4780: 66 20 74 68 65 20 67 69 76 65 6e 20 69 6e 70 75  f the given inpu
4790: 74 20 73 74 72 69 6e 67 20 63 6f 6d 70 72 69 73  t string compris
47a0: 65 73 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  es.** one or mor
47b0: 65 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  e complete SQL s
47c0: 74 61 74 65 6d 65 6e 74 73 2e 20 46 6f 72 20 74  tatements. For t
47d0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  he sqlite3_compl
47e0: 65 74 65 28 29 20 63 61 6c 6c 2c 0a 2a 2a 20 74  ete() call,.** t
47f0: 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  he parameter mus
4800: 74 20 62 65 20 61 20 6e 75 6c 2d 74 65 72 6d 69  t be a nul-termi
4810: 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
4820: 6e 67 2e 20 46 6f 72 0a 2a 2a 20 73 71 6c 69 74  ng. For.** sqlit
4830: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2c  e3_complete16(),
4840: 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
4850: 64 20 6d 61 63 68 69 6e 65 20 62 79 74 65 20 6f  d machine byte o
4860: 72 64 65 72 20 55 54 46 2d 31 36 20 73 74 72 69  rder UTF-16 stri
4870: 6e 67 0a 2a 2a 20 69 73 20 72 65 71 75 69 72 65  ng.** is require
4880: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
4890: 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
48a0: 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c  ul for command-l
48b0: 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
48c0: 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
48d0: 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
48e0: 65 64 20 74 65 78 74 20 66 6f 72 6d 73 20 6f 6e  ed text forms on
48f0: 65 20 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 6c 65  e or more comple
4900: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
4910: 73 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  s or.** if addit
4920: 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
4930: 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
4940: 64 69 6e 67 20 74 68 65 20 73 74 61 74 65 6d 65  ding the stateme
4950: 6e 74 73 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  nts into.** SQLi
4960: 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
4970: 54 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 69 73  The algorithm is
4980: 20 73 69 6d 70 6c 65 2e 20 20 49 66 20 74 68 65   simple.  If the
4990: 20 0a 2a 2a 20 6c 61 73 74 20 74 6f 6b 65 6e 20   .** last token 
49a0: 6f 74 68 65 72 20 74 68 61 6e 20 73 70 61 63 65  other than space
49b0: 73 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 69  s and comments i
49c0: 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2c 20 74  s a semicolon, t
49d0: 68 65 6e 20 72 65 74 75 72 6e 20 0a 2a 2a 20 74  hen return .** t
49e0: 72 75 65 2e 20 20 41 63 74 75 61 6c 6c 79 2c 20  rue.  Actually, 
49f0: 74 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 69 73  the algorithm is
4a00: 20 61 20 6c 69 74 74 6c 65 20 6d 6f 72 65 20 63   a little more c
4a10: 6f 6d 70 6c 69 63 61 74 65 64 20 74 68 61 6e 20  omplicated than 
4a20: 74 68 61 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  that.** in order
4a30: 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 74 72   to deal with tr
4a40: 69 67 67 65 72 73 2c 20 62 75 74 20 74 68 65 20  iggers, but the 
4a50: 62 61 73 69 63 20 69 64 65 61 20 69 73 20 74 68  basic idea is th
4a60: 65 20 73 61 6d 65 3a 20 20 74 68 65 0a 2a 2a 20  e same:  the.** 
4a70: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
4a80: 20 63 6f 6d 70 6c 65 74 65 20 75 6e 6c 65 73 73   complete unless
4a90: 20 69 74 20 65 6e 64 73 20 69 6e 20 61 20 73 65   it ends in a se
4aa0: 6d 69 63 6f 6c 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  micolon..*/.int 
4ab0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
4ac0: 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
4ad0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
4ae0: 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
4af0: 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
4b00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
4b10: 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
4b20: 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
4b30: 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
4b40: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
4b50: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 63 61   identifies a ca
4b60: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
4b70: 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
4b80: 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76 65  voked.** wheneve
4b90: 72 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  r an attempt is 
4ba0: 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
4bb0: 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 0a 2a  atabase table .*
4bc0: 2a 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  * that another t
4bd0: 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73 73  hread or process
4be0: 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20   has locked..** 
4bf0: 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
4c00: 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
4c10: 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
4c20: 0a 2a 2a 20 28 6f 72 20 73 6f 6d 65 74 69 6d 65  .** (or sometime
4c30: 73 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  s [SQLITE_IOERR_
4c40: 42 4c 4f 43 4b 45 44 5d 29 0a 2a 2a 20 69 73 20  BLOCKED]).** is 
4c50: 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
4c60: 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
4c70: 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
4c80: 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20  .** If the busy 
4c90: 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
4ca0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 0a 2a  NULL, then the.*
4cb0: 2a 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20  * callback will 
4cc0: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
4cd0: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  two arguments.  
4ce0: 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72 67  The.** first arg
4cf0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e  ument to the han
4d00: 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
4d10: 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
4d20: 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
4d30: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
4d40: 6e 74 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  nt to this routi
4d50: 6e 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ne.  The second 
4d60: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
4d70: 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 74 68  he handler is th
4d80: 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
4d90: 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
4da0: 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
4db0: 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
4dc0: 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65  this locking eve
4dd0: 6e 74 2e 20 49 66 20 74 68 65 0a 2a 2a 20 62 75  nt. If the.** bu
4de0: 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
4df0: 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
4e00: 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
4e10: 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
4e20: 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
4e30: 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
4e40: 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4e60: 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
4e70: 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63  * If the callbac
4e80: 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
4e90: 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
4ea0: 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
4eb0: 20 74 6f 20 6f 70 65 6e 20 74 68 65 0a 2a 2a 20   to open the.** 
4ec0: 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
4ed0: 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63  ding and the cyc
4ee0: 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
4ef0: 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
4f00: 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
4f10: 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
4f20: 74 65 65 20 74 68 61 74 0a 2a 2a 20 69 74 20 77  tee that.** it w
4f30: 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ill be invoked w
4f40: 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
4f50: 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 0a 2a 2a  k contention..**
4f60: 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72   If SQLite deter
4f70: 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
4f80: 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e  ing the busy han
4f90: 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
4fa0: 74 20 69 6e 0a 2a 2a 20 61 20 64 65 61 64 6c 6f  t in.** a deadlo
4fb0: 63 6b 2c 20 69 74 20 77 69 6c 6c 20 72 65 74 75  ck, it will retu
4fc0: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
4fd0: 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 20 43 6f 6e   instead..** Con
4fe0: 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
4ff0: 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
5000: 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
5010: 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
5020: 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
5030: 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
5040: 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
5050: 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
5060: 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
5070: 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
5080: 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
5090: 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
50a0: 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
50b0: 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
50c0: 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
50d0: 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
50e0: 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
50f0: 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
5100: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
5110: 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
5120: 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
5130: 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
5140: 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
5150: 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
5160: 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
5170: 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
5180: 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
5190: 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
51a0: 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
51b0: 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
51c0: 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
51d0: 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
51e0: 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
51f0: 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
5200: 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
5210: 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
5220: 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
5230: 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
5240: 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
5250: 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ceed..**.** The 
5260: 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
5270: 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
5280: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
5290: 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
52a0: 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
52b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
52c0: 45 44 5d 20 77 68 65 6e 0a 2a 2a 20 53 51 4c 69  ED] when.** SQLi
52d0: 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
52e0: 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
52f0: 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
5300: 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
5310: 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
5320: 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
5330: 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
5340: 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
5350: 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
5360: 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
5370: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
5380: 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
5390: 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
53a0: 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
53b0: 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
53c0: 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
53d0: 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
53e0: 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
53f0: 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
5400: 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
5410: 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62  .  If it is unab
5420: 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
5430: 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
5440: 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
5450: 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
5460: 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
5470: 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
5480: 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
5490: 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
54a0: 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
54b0: 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
54c0: 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
54d0: 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
54e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
54f0: 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f  KED].  This erro
5500: 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e  r code promotion
5510: 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75  .** forces an au
5520: 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b  tomatic rollback
5530: 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e   of the changes.
5540: 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
5550: 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e  ref="http://www.
5560: 73 71 6c 69 74 65 2e 6f 72 67 2f 63 76 73 74 72  sqlite.org/cvstr
5570: 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
5580: 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
5590: 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
55a0: 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
55b0: 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
55c0: 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
55d0: 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
55e0: 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
55f0: 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 53 71 6c 69  ant..**..** Sqli
5600: 74 65 20 69 73 20 72 65 2d 65 6e 74 72 61 6e 74  te is re-entrant
5610: 2c 20 73 6f 20 74 68 65 20 62 75 73 79 20 68 61  , so the busy ha
5620: 6e 64 6c 65 72 20 6d 61 79 20 73 74 61 72 74 20  ndler may start 
5630: 61 20 6e 65 77 20 71 75 65 72 79 2e 20 0a 2a 2a  a new query. .**
5640: 20 28 49 74 20 69 73 20 6e 6f 74 20 63 6c 65 61   (It is not clea
5650: 72 20 77 68 79 20 61 6e 79 6f 6e 65 20 77 6f 75  r why anyone wou
5660: 6c 64 20 65 76 65 72 79 20 77 61 6e 74 20 74 6f  ld every want to
5670: 20 64 6f 20 74 68 69 73 2c 20 62 75 74 20 69 74   do this, but it
5680: 0a 2a 2a 20 69 73 20 61 6c 6c 6f 77 65 64 2c 20  .** is allowed, 
5690: 69 6e 20 74 68 65 6f 72 79 2e 29 20 20 42 75 74  in theory.)  But
56a0: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
56b0: 72 20 6d 61 79 20 6e 6f 74 20 63 6c 6f 73 65 20  r may not close 
56c0: 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
56d0: 20 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 64 61    Closing the da
56e0: 74 61 62 61 73 65 20 66 72 6f 6d 20 61 20 62 75  tabase from a bu
56f0: 73 79 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20  sy handler will 
5700: 64 65 6c 65 74 65 20 0a 2a 2a 20 64 61 74 61 20  delete .** data 
5710: 73 74 72 75 63 74 75 72 65 73 20 6f 75 74 20 66  structures out f
5720: 72 6f 6d 20 75 6e 64 65 72 20 74 68 65 20 65 78  rom under the ex
5730: 65 63 75 74 69 6e 67 20 71 75 65 72 79 20 61 6e  ecuting query an
5740: 64 20 77 69 6c 6c 20 0a 2a 2a 20 70 72 6f 62 61  d will .** proba
5750: 62 6c 79 20 72 65 73 75 6c 74 20 69 6e 20 61 20  bly result in a 
5760: 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
5770: 6c 74 20 6f 72 20 6f 74 68 65 72 20 72 75 6e 74  lt or other runt
5780: 69 6d 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a  ime error..**.**
5790: 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20   There can only 
57a0: 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
57b0: 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
57c0: 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62 61   for each databa
57d0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
57e0: 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
57f0: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
5800: 65 61 72 73 20 61 6e 79 20 70 72 65 76 69 6f 75  ears any previou
5810: 73 20 6f 6e 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74  s one..** Note t
5820: 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
5830: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
5840: 74 28 29 5d 20 77 69 6c 6c 20 61 6c 73 6f 20 73  t()] will also s
5850: 65 74 20 6f 72 20 63 6c 65 61 72 0a 2a 2a 20 74  et or clear.** t
5860: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
5870: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
5880: 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
5890: 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
58a0: 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
58b0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
58c0: 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
58d0: 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 54 68 69 73  meout.**.** This
58e0: 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
58f0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 74 68 61  busy handler tha
5900: 74 20 73 6c 65 65 70 73 20 66 6f 72 20 61 20 77  t sleeps for a w
5910: 68 69 6c 65 20 77 68 65 6e 20 61 0a 2a 2a 20 74  hile when a.** t
5920: 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
5930: 20 54 68 65 20 68 61 6e 64 6c 65 72 20 77 69 6c   The handler wil
5940: 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
5950: 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 0a 2a 2a   times until .**
5960: 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
5970: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
5980: 6c 65 65 70 69 6e 67 20 68 61 76 65 20 62 65 65  leeping have bee
5990: 6e 20 64 6f 6e 65 2e 20 20 41 66 74 65 72 0a 2a  n done.  After.*
59a0: 2a 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  * "ms" milliseco
59b0: 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
59c0: 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
59d0: 75 72 6e 73 20 30 20 77 68 69 63 68 0a 2a 2a 20  urns 0 which.** 
59e0: 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
59f0: 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
5a00: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
5a10: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
5a20: 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
5a30: 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   Calling this ro
5a40: 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
5a50: 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
5a60: 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
5a70: 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
5a80: 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
5a90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61  ..**.** There ca
5aa0: 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
5ab0: 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
5ac0: 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
5ad0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
5ae0: 6e 65 63 74 69 6f 6e 2e 20 20 49 66 20 61 6e 6f  nection.  If ano
5af0: 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
5b00: 72 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 0a  r was defined  .
5b10: 2a 2a 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  ** (using [sqlit
5b20: 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
5b30: 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
5b40: 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
5b50: 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
5b60: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
5b70: 20 63 6c 65 61 72 65 64 2e 0a 2a 2f 0a 69 6e 74   cleared..*/.int
5b80: 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
5b90: 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
5ba0: 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
5bb0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
5bc0: 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
5bd0: 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
5be0: 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6e 65  es.**.** This ne
5bf0: 78 74 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  xt routine is a 
5c00: 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70  convenience wrap
5c10: 70 65 72 20 61 72 6f 75 6e 64 20 5b 73 71 6c 69  per around [sqli
5c20: 74 65 33 5f 65 78 65 63 28 29 5d 2e 0a 2a 2a 20  te3_exec()]..** 
5c30: 49 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  Instead of invok
5c40: 69 6e 67 20 61 20 75 73 65 72 2d 73 75 70 70 6c  ing a user-suppl
5c50: 69 65 64 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72  ied callback for
5c60: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65   each row of the
5c70: 0a 2a 2a 20 72 65 73 75 6c 74 2c 20 74 68 69 73  .** result, this
5c80: 20 72 6f 75 74 69 6e 65 20 72 65 6d 65 6d 62 65   routine remembe
5c90: 72 73 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74  rs each row of t
5ca0: 68 65 20 72 65 73 75 6c 74 20 69 6e 20 6d 65 6d  he result in mem
5cb0: 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20  ory.** obtained 
5cc0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
5cd0: 6c 6c 6f 63 28 29 5d 2c 20 74 68 65 6e 20 72 65  lloc()], then re
5ce0: 74 75 72 6e 73 20 61 6c 6c 20 6f 66 20 74 68 65  turns all of the
5cf0: 20 72 65 73 75 6c 74 20 61 66 74 65 72 20 74 68   result after th
5d00: 65 0a 2a 2a 20 71 75 65 72 79 20 68 61 73 20 66  e.** query has f
5d10: 69 6e 69 73 68 65 64 2e 20 0a 2a 2a 0a 2a 2a 20  inished. .**.** 
5d20: 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 2c 20 73  As an example, s
5d30: 75 70 70 6f 73 65 20 74 68 65 20 71 75 65 72 79  uppose the query
5d40: 20 72 65 73 75 6c 74 20 77 68 65 72 65 20 74 68   result where th
5d50: 69 73 20 74 61 62 6c 65 3a 0a 2a 2a 0a 2a 2a 20  is table:.**.** 
5d60: 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
5d70: 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
5d80: 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
5d90: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
5da0: 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
5db0: 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
5dc0: 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
5dd0: 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
5de0: 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
5df0: 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a  | 21.** </pre>.*
5e00: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
5e10: 61 72 67 75 6d 65 6e 74 20 77 65 72 65 20 26 61  argument were &a
5e20: 7a 52 65 73 75 6c 74 20 74 68 65 6e 20 61 66 74  zResult then aft
5e30: 65 72 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  er the function 
5e40: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 7a 52 65 73  returns.** azRes
5e50: 75 6c 74 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e  ult will contain
5e60: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 64   the following d
5e70: 61 74 61 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e  ata:.**.** <pre>
5e80: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
5e90: 75 6c 74 5b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  ult[0] = "Name";
5ea0: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
5eb0: 75 6c 74 5b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  ult[1] = "Age";.
5ec0: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
5ed0: 6c 74 5b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  lt[2] = "Alice";
5ee0: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
5ef0: 75 6c 74 5b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  ult[3] = "43";.*
5f00: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
5f10: 74 5b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  t[4] = "Bob";.**
5f20: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
5f30: 5b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  [5] = "28";.**  
5f40: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 36        azResult[6
5f50: 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
5f60: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b         azResult[
5f70: 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
5f80: 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 69 63  pre>.**.** Notic
5f90: 65 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20  e that there is 
5fa0: 61 6e 20 65 78 74 72 61 20 72 6f 77 20 6f 66 20  an extra row of 
5fb0: 64 61 74 61 20 63 6f 6e 74 61 69 6e 69 6e 67 20  data containing 
5fc0: 74 68 65 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 68 65  the column.** he
5fd0: 61 64 65 72 73 2e 20 20 42 75 74 20 74 68 65 20  aders.  But the 
5fe0: 2a 6e 72 6f 77 20 72 65 74 75 72 6e 20 76 61 6c  *nrow return val
5ff0: 75 65 20 69 73 20 73 74 69 6c 6c 20 33 2e 20 20  ue is still 3.  
6000: 2a 6e 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 73  *ncolumn is.** s
6010: 65 74 20 74 6f 20 32 2e 20 20 49 6e 20 67 65 6e  et to 2.  In gen
6020: 65 72 61 6c 2c 20 74 68 65 20 6e 75 6d 62 65 72  eral, the number
6030: 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 73 65 72   of values inser
6040: 74 65 64 20 69 6e 74 6f 20 61 7a 52 65 73 75 6c  ted into azResul
6050: 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 28 28 2a  t.** will be ((*
6060: 6e 72 6f 77 29 20 2b 20 31 29 2a 28 2a 6e 63 6f  nrow) + 1)*(*nco
6070: 6c 75 6d 6e 29 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  lumn)..**.** Aft
6080: 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  er the calling f
6090: 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  unction has fini
60a0: 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 72  shed using the r
60b0: 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64  esult, it should
60c0: 20 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 72 65   .** pass the re
60d0: 73 75 6c 74 20 64 61 74 61 20 70 6f 69 6e 74 65  sult data pointe
60e0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
60f0: 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
6100: 65 72 20 74 6f 20 0a 2a 2a 20 72 65 6c 65 61 73  er to .** releas
6110: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
6120: 74 20 77 61 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e  t was malloc-ed.
6130: 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
6140: 20 77 61 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71   way the .** [sq
6150: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
6160: 68 61 70 70 65 6e 73 2c 20 74 68 65 20 63 61 6c  happens, the cal
6170: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ling function mu
6180: 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
6190: 6c 6c 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ll .** [sqlite3_
61a0: 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
61b0: 2e 20 20 4f 6e 6c 79 20 5b 73 71 6c 69 74 65 33  .  Only [sqlite3
61c0: 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
61d0: 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
61e0: 65 20 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  e .** the memory
61f0: 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
6200: 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
6210: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
6220: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
6230: 74 68 65 20 73 61 6d 65 20 61 73 20 66 72 6f 6d  the same as from
6240: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
6250: 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
6260: 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
6270: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
6280: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
6290: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
62a0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
62b0: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
62c0: 62 65 20 65 78 65 63 75 74 65 64 20 2a 2f 0a 20  be executed */. 
62d0: 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 6c 74 70   char ***resultp
62e0: 2c 20 20 20 20 20 20 20 2f 2a 20 52 65 73 75 6c  ,       /* Resul
62f0: 74 20 77 72 69 74 74 65 6e 20 74 6f 20 61 20 63  t written to a c
6300: 68 61 72 20 2a 5b 5d 20 20 74 68 61 74 20 74 68  har *[]  that th
6310: 69 73 20 70 6f 69 6e 74 73 20 74 6f 20 2a 2f 0a  is points to */.
6320: 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20 20 20 20    int *nrow,    
6330: 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
6340: 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
6350: 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
6360: 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e  /.  int *ncolumn
6370: 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  ,          /* Nu
6380: 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
6390: 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
63a0: 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
63b0: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
63c0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
63d0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
63e0: 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
63f0: 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
6400: 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
6410: 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
6420: 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
6430: 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
6440: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
6450: 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73  s are workalikes
6460: 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
6470: 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
6480: 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
6490: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
64a0: 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  brary..**.** The
64b0: 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
64c0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
64d0: 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
64e0: 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
64f0: 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
6500: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
6510: 72 6f 6d 20 5b 73 71 6c 69 74 65 5f 6d 61 6c 6c  rom [sqlite_mall
6520: 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
6530: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
6540: 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
6550: 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
6560: 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
6570: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
6580: 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72   Both routines r
6590: 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
65a0: 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
65b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
65c0: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
65d0: 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
65e0: 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
65f0: 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
6600: 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69  g..**.** In sqli
6610: 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
6620: 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
6630: 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
6640: 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
6650: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
6660: 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
6670: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
6680: 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
6690: 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
66a0: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
66b0: 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
66c0: 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
66d0: 20 70 61 72 61 6d 65 74 65 72 2e 20 20 4e 6f 74   parameter.  Not
66e0: 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
66f0: 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
6700: 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
6710: 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
6720: 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68   snprintf().  Th
6730: 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
6740: 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
6750: 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
6760: 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
6770: 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
6780: 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
6790: 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61  .  Note also tha
67a0: 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
67b0: 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
67c0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
67d0: 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
67e0: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
67f0: 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
6800: 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
6810: 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
6820: 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
6830: 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
6840: 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
6850: 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
6860: 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
6870: 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
6880: 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
6890: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
68a0: 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
68b0: 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
68c0: 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
68d0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
68e0: 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73  **.** As long as
68f0: 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
6900: 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
6910: 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
6920: 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
6930: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
6940: 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
6950: 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
6960: 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  d.  The first.**
6970: 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
6980: 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
6990: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
69a0: 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
69b0: 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
69c0: 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
69d0: 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
69e0: 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
69f0: 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
6a00: 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
6a10: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
6a20: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
6a30: 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
6a40: 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
6a50: 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
6a60: 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
6a70: 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
6a80: 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
6a90: 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
6aa0: 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
6ab0: 66 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  f formatting opt
6ac0: 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
6ad0: 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
6ae0: 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 20 61  ** is are "%q" a
6af0: 6e 64 20 22 25 51 22 20 6f 70 74 69 6f 6e 73 2e  nd "%Q" options.
6b00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70  .**.** The %q op
6b10: 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
6b20: 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
6b30: 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c  bstitutes a null
6b40: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
6b50: 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
6b60: 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
6b70: 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
6b80: 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
6b90: 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
6ba0: 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
6bb0: 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
6bc0: 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20  ng literal.  By 
6bd0: 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
6be0: 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
6bf0: 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
6c00: 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
6c10: 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
6c20: 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
6c30: 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
6c40: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 73 6f   For example, so
6c50: 20 73 6f 6d 65 20 73 74 72 69 6e 67 20 76 61 72   some string var
6c60: 69 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74  iable contains t
6c70: 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
6c80: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
6c90: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
6ca0: 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
6cb0: 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
6cc0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
6cd0: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
6ce0: 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
6cf0: 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
6d00: 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
6d10: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
6d20: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
6d30: 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
6d40: 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
6d50: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
6d60: 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
6d70: 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
6d80: 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
6d90: 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
6da0: 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
6db0: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
6dc0: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
6dd0: 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
6de0: 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
6df0: 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
6e00: 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
6e10: 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
6e20: 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
6e30: 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
6e40: 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
6e50: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
6e60: 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
6e70: 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
6e80: 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
6e90: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
6ea0: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
6eb0: 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
6ec0: 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
6ed0: 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
6ee0: 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
6ef0: 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
6f00: 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
6f10: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
6f20: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
6f30: 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
6f40: 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
6f50: 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
6f60: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
6f70: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
6f80: 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
6f90: 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
6fa0: 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
6fb0: 6c 20 72 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 68  l rule you.** sh
6fc0: 6f 75 6c 64 20 61 6c 77 61 79 73 20 75 73 65 20  ould always use 
6fd0: 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
6fe0: 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
6ff0: 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
7000: 6e 67 20 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a  ng .** literal..
7010: 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74  **.** The %Q opt
7020: 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
7030: 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
7040: 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
7050: 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
7060: 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
7070: 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
7080: 4f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  Or if the parame
7090: 74 65 72 20 69 6e 20 74 68 65 20 61 72 67 75 6d  ter in the argum
70a0: 65 6e 74 0a 2a 2a 20 6c 69 73 74 20 69 73 20 61  ent.** list is a
70b0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
70c0: 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
70d0: 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
70e0: 69 74 68 6f 75 74 20 73 69 6e 67 6c 65 0a 2a 2a  ithout single.**
70f0: 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63   quotes) in plac
7100: 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69  e of the %Q opti
7110: 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  on.  So, for exa
7120: 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
7130: 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
7140: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
7150: 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
7160: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
7170: 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
7180: 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
7190: 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
71a0: 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
71b0: 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
71c0: 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
71d0: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
71e0: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
71f0: 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
7200: 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
7210: 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
7220: 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
7230: 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
7240: 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
7250: 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
7260: 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 63 68 61 72  pointer..*/.char
7270: 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
7280: 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
7290: 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
72a0: 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
72b0: 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
72c0: 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
72d0: 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
72e0: 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
72f0: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
7300: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
7310: 6c 6f 63 61 74 69 6f 6e 20 46 75 6e 63 74 69 6f  location Functio
7320: 6e 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ns.**.** SQLite 
7330: 75 73 65 73 20 69 74 73 20 6f 77 6e 20 6d 65 6d  uses its own mem
7340: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
7350: 4f 6e 20 73 6f 6d 65 20 69 6e 73 74 61 6c 6c 61  On some installa
7360: 74 69 6f 6e 73 2c 20 74 68 69 73 0a 2a 2a 20 6d  tions, this.** m
7370: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
7380: 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
7390: 74 68 65 20 73 74 61 6e 64 61 72 64 20 6d 61 6c  the standard mal
73a0: 6c 6f 63 28 29 2f 72 65 61 6c 6c 6f 63 28 29 2f  loc()/realloc()/
73b0: 66 72 65 65 28 29 0a 2a 2a 20 61 6e 64 20 63 61  free().** and ca
73c0: 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
73d0: 68 61 6e 67 61 62 6c 65 2e 20 20 4f 6e 20 6f 74  hangable.  On ot
73e0: 68 65 72 73 2c 20 74 68 65 20 69 6d 70 6c 65 6d  hers, the implem
73f0: 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 0a 2a 2a  entations are.**
7400: 20 64 69 66 66 65 72 65 6e 74 2e 20 20 46 6f 72   different.  For
7410: 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69   maximum portabi
7420: 6c 69 74 79 2c 20 69 74 20 69 73 20 62 65 73 74  lity, it is best
7430: 20 6e 6f 74 20 74 6f 20 6d 69 78 20 63 61 6c 6c   not to mix call
7440: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 73 74 61 6e  s.** to the stan
7450: 64 61 72 64 20 6d 61 6c 6c 6f 63 2f 72 65 61 6c  dard malloc/real
7460: 6c 6f 63 2f 66 72 65 65 20 77 69 74 68 20 74 68  loc/free with th
7470: 65 20 73 71 6c 69 74 65 20 76 65 72 73 69 6f 6e  e sqlite version
7480: 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
7490: 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
74a0: 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
74b0: 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
74c0: 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
74d0: 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
74e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
74f0: 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
7500: 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
7510: 63 6b 73 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20  cks.***.** This 
7520: 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
7530: 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63  s a authorizer c
7540: 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 74 68 65  allback with the
7550: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
7560: 20 20 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72    .** The author
7570: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
7580: 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
7590: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
75a0: 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
75b0: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
75c0: 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
75d0: 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
75e0: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
75f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
7600: 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
7610: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
7620: 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f  v2()].  At vario
7630: 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
7640: 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
7650: 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
7660: 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
7670: 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
7680: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
7690: 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
76a0: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
76b0: 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
76c0: 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
76d0: 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
76e0: 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72    The authorizer
76f0: 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
7700: 0a 2a 2a 20 72 65 74 75 72 6e 20 53 51 4c 49 54  .** return SQLIT
7710: 45 5f 4f 4b 20 74 6f 20 61 6c 6c 6f 77 20 74 68  E_OK to allow th
7720: 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
7730: 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
7740: 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
7750: 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
7760: 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
7770: 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
7780: 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
7790: 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
77a0: 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
77b0: 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
77c0: 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
77d0: 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
77e0: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 0a 2a 2a  h an error.  .**
77f0: 0a 2a 2a 20 44 65 70 65 6e 64 69 6e 67 20 6f 6e  .** Depending on
7800: 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 74 68 65   the action, the
7810: 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
7820: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 44 45 4e   and [SQLITE_DEN
7830: 59 5d 20 72 65 74 75 72 6e 0a 2a 2a 20 63 6f 64  Y] return.** cod
7840: 65 73 20 6d 69 67 68 74 20 6d 65 61 6e 20 73 6f  es might mean so
7850: 6d 65 74 68 69 6e 67 20 64 69 66 66 65 72 65 6e  mething differen
7860: 74 20 6f 72 20 74 68 65 79 20 6d 69 67 68 74 20  t or they might 
7870: 6d 65 61 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  mean the same.**
7880: 20 74 68 69 6e 67 2e 20 20 49 66 20 74 68 65 20   thing.  If the 
7890: 61 63 74 69 6f 6e 20 69 73 2c 20 66 6f 72 20 65  action is, for e
78a0: 78 61 6d 70 6c 65 2c 20 74 6f 20 70 65 72 66 6f  xample, to perfo
78b0: 72 6d 20 61 20 64 65 6c 65 74 65 20 6f 70 65 72  rm a delete oper
78c0: 74 69 6f 6e 2c 0a 2a 2a 20 74 68 65 6e 20 5b 53  tion,.** then [S
78d0: 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 61 6e  QLITE_IGNORE] an
78e0: 64 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  d [SQLITE_DENY] 
78f0: 62 6f 74 68 20 63 61 75 73 65 20 74 68 65 20 73  both cause the s
7900: 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 61  tatement compila
7910: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 61 69 6c 20  tion.** to fail 
7920: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
7930: 42 75 74 20 69 66 20 74 68 65 20 61 63 74 69 6f  But if the actio
7940: 6e 20 69 73 20 74 6f 20 72 65 61 64 20 61 20 73  n is to read a s
7950: 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 0a 2a  pecific column.*
7960: 2a 20 66 72 6f 6d 20 61 20 73 70 65 63 69 66 69  * from a specifi
7970: 63 20 74 61 62 6c 65 2c 20 74 68 65 6e 20 5b 53  c table, then [S
7980: 51 4c 49 54 45 5f 44 45 4e 59 5d 20 77 69 6c 6c  QLITE_DENY] will
7990: 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
79a0: 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  e.** statement t
79b0: 6f 20 66 61 69 6c 20 62 75 74 20 5b 53 51 4c 49  o fail but [SQLI
79c0: 54 45 5f 49 47 4e 4f 52 45 5d 20 77 69 6c 6c 20  TE_IGNORE] will 
79d0: 63 61 75 73 65 20 61 20 4e 55 4c 4c 20 76 61 6c  cause a NULL val
79e0: 75 65 20 74 6f 20 62 65 0a 2a 2a 20 72 65 61 64  ue to be.** read
79f0: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
7a00: 61 63 74 75 61 6c 20 63 6f 6c 75 6d 6e 20 76 61  actual column va
7a10: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  lue..**.** The f
7a20: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
7a30: 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
7a40: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
7a50: 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 74 68  opy of.** the th
7a60: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
7a70: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
7a80: 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
7a90: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65 20  terface..** The 
7aa0: 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
7ab0: 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
7ac0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 0a   is an integer .
7ad0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  ** [SQLITE_COPY 
7ae0: 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
7af0: 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
7b00: 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
7b10: 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65 20 61 75 74  ion.** to be aut
7b20: 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 61 76  horized.  The av
7b30: 61 69 6c 61 62 6c 65 20 61 63 74 69 6f 6e 20 63  ailable action c
7b40: 6f 64 65 73 20 61 72 65 0a 2a 2a 20 5b 53 51 4c  odes are.** [SQL
7b50: 49 54 45 5f 43 4f 50 59 20 7c 20 64 6f 63 75 6d  ITE_COPY | docum
7b60: 65 6e 74 65 64 20 73 65 70 61 72 61 74 65 6c 79  ented separately
7b70: 5d 2e 20 20 54 68 65 20 74 68 69 72 64 20 74 68  ].  The third th
7b80: 72 6f 75 67 68 20 73 69 78 74 68 0a 2a 2a 20 70  rough sixth.** p
7b90: 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
7ba0: 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 73 74   callback are st
7bb0: 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
7bc0: 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
7bd0: 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
7be0: 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
7bf0: 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
7c00: 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
7c10: 69 73 20 75 73 65 64 20 77 68 65 6e 20 70 72 65  is used when pre
7c20: 70 61 72 69 6e 67 20 53 51 4c 20 73 74 61 74 65  paring SQL state
7c30: 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
7c40: 74 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63  trusted.** sourc
7c50: 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
7c60: 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
7c70: 65 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72 79 20  ents do not try 
7c80: 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 0a 2a  to access data.*
7c90: 2a 20 74 68 61 74 20 74 68 65 79 20 61 72 65 20  * that they are 
7ca0: 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
7cb0: 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
7cc0: 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a   do not try to.*
7cd0: 2a 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  * execute malici
7ce0: 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
7cf0: 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
7d00: 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
7d10: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
7d20: 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
7d30: 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
7d40: 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
7d50: 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
7d60: 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
7d70: 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
7d80: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
7d90: 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
7da0: 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
7db0: 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
7dc0: 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
7dd0: 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
7de0: 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
7df0: 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
7e00: 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
7e10: 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
7e20: 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
7e30: 6e 67 20 70 72 65 70 61 72 65 64 20 74 68 61 74  ng prepared that
7e40: 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
7e50: 74 68 69 6e 67 0a 2a 2a 20 65 78 63 65 70 74 20  thing.** except 
7e60: 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
7e70: 73 2e 20 20 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20  s.  .**.** Only 
7e80: 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
7e90: 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
7ea0: 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
7eb0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
7ec0: 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
7ed0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
7ee0: 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
7ef0: 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
7f00: 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20   previous call. 
7f10: 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72 69 7a   A NULL authoriz
7f20: 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f  er means that no
7f30: 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
7f40: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  * callback is in
7f50: 76 6f 6b 65 64 2e 20 20 54 68 65 20 64 65 66 61  voked.  The defa
7f60: 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20 69  ult authorizer i
7f70: 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  s NULL..**.** No
7f80: 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
7f90: 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
7fa0: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
7fb0: 64 75 72 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69  during .** [sqli
7fc0: 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
7fd0: 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
7fe0: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
7ff0: 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
8000: 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
8010: 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
8020: 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
8030: 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
8040: 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
8050: 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
8060: 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
8070: 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
8080: 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
8090: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
80a0: 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
80b0: 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
80c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
80d0: 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
80e0: 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
80f0: 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
8100: 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
8110: 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
8120: 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
8130: 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
8140: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
8150: 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
8160: 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
8170: 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
8180: 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
8190: 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
81a0: 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
81b0: 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
81c0: 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
81d0: 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
81e0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
81f0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
8200: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
8210: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8220: 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
8230: 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
8240: 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
8250: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
8260: 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
8270: 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
8280: 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
8290: 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
82a0: 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
82b0: 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
82c0: 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
82d0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
82e0: 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
82f0: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
8300: 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
8310: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
8320: 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
8330: 74 6f 20 61 75 74 68 6f 72 69 7a 65 72 20 63 65  to authorizer ce
8340: 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
8350: 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
8360: 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
8370: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
8380: 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
8390: 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
83a0: 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
83b0: 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
83c0: 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
83d0: 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
83e0: 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
83f0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
8400: 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
8410: 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
8420: 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
8430: 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
8440: 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
8450: 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
8460: 74 6f 20 62 65 20 0a 2a 2a 20 61 75 74 68 6f 72  to be .** author
8470: 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
8480: 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
8490: 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
84a0: 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 0a  zation callback.
84b0: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ** function will
84c0: 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
84d0: 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
84e0: 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
84f0: 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
8500: 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
8510: 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
8520: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
8530: 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
8540: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
8550: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
8560: 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
8570: 22 2c 20 22 74 65 6d 70 22 2c 20 0a 2a 2a 20 65  ", "temp", .** e
8580: 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
8590: 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72  le.  The 6th par
85a0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
85b0: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
85c0: 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
85d0: 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
85e0: 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
85f0: 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
8600: 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
8610: 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
8620: 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
8630: 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
8640: 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
8650: 20 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53   .** top-level S
8660: 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
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: 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
86a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
86b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
86c0: 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
86d0: 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
86e0: 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
86f0: 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
8700: 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
8710: 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
8720: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
8730: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
8740: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
8750: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
8760: 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
8770: 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
8780: 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
8790: 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
87a0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
87b0: 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
87c0: 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
87d0: 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
87e0: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
87f0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
8800: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
8810: 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
8820: 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
8830: 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
8840: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
8850: 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
8860: 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
8870: 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
8880: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
8890: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
88a0: 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
88b0: 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
88c0: 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
88d0: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
88e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
88f0: 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
8900: 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
8910: 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
8920: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
8930: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8940: 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
8950: 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
8960: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
8970: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
8980: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8990: 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
89a0: 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
89b0: 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
89c0: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
89d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
89e0: 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
89f0: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
8a00: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
8a10: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
8a20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
8a30: 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
8a40: 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
8a50: 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
8a60: 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
8a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
8a80: 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
8a90: 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
8aa0: 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
8ab0: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
8ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
8ad0: 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
8ae0: 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
8af0: 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
8b00: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
8b10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
8b20: 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
8b30: 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
8b40: 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
8b50: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
8b60: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
8b70: 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
8b80: 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
8b90: 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
8ba0: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
8bb0: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
8bc0: 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
8bd0: 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
8be0: 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
8bf0: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
8c00: 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
8c10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
8c20: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
8c30: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
8c40: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
8c50: 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
8c60: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
8c70: 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
8c80: 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
8c90: 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
8ca0: 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
8cb0: 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
8cc0: 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
8cd0: 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
8ce0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
8cf0: 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
8d00: 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
8d10: 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
8d20: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
8d30: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
8d40: 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
8d50: 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
8d60: 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
8d70: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
8d80: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
8d90: 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
8da0: 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
8db0: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
8dc0: 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
8dd0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8de0: 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
8df0: 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
8e00: 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
8e10: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
8e20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8e30: 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
8e40: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
8e50: 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
8e60: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
8e70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8e80: 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
8e90: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
8ea0: 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
8eb0: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
8ec0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8ed0: 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
8ee0: 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
8ef0: 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
8f00: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
8f10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
8f20: 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
8f30: 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
8f40: 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
8f50: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
8f60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
8f70: 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
8f80: 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
8f90: 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
8fa0: 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
8fb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
8fc0: 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
8fd0: 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
8fe0: 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
8ff0: 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
9000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
9010: 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
9020: 20 33 31 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f   31   /* Functio
9030: 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  n Name   NULL   
9040: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
9050: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
9060: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
9070: 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
9080: 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  r used */../*.**
9090: 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
90a0: 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
90b0: 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
90c0: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
90d0: 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
90e0: 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
90f0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
9100: 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
9110: 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
9120: 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
9130: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  tatements..** Th
9140: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
9150: 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
9160: 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
9170: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
9180: 61 74 20 74 68 65 20 66 69 72 73 74 20 5b 73 71  at the first [sq
9190: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
91a0: 72 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  r the evaluation
91b0: 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
91c0: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  ment..** The cal
91d0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
91e0: 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
91f0: 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
9200: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
9210: 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
9220: 6e 74 20 66 69 6e 69 73 68 65 73 20 61 6e 64 20  nt finishes and 
9230: 69 6e 63 6c 75 64 65 73 0a 2a 2a 20 69 6e 66 6f  includes.** info
9240: 72 6d 61 74 69 6f 6e 20 6f 6e 20 68 6f 77 20 6c  rmation on how l
9250: 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
9260: 6e 74 20 72 61 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nt ran..**.** Th
9270: 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  e sqlite3_profil
9280: 65 28 29 20 41 50 49 20 69 73 20 63 75 72 72 65  e() API is curre
9290: 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 20  ntly considered 
92a0: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
92b0: 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63 74 20 74  .** is subject t
92c0: 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69  o change..*/.voi
92d0: 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
92e0: 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
92f0: 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
9300: 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
9310: 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  d*);.void *sqlit
9320: 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
9330: 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
9340: 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
9350: 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
9360: 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
9370: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
9380: 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
9390: 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  s Callbacks.**.*
93a0: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
93b0: 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c  onfigures a call
93c0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20  back function - 
93d0: 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
93e0: 6c 62 61 63 6b 20 2d 20 74 68 61 74 0a 2a 2a 20  lback - that.** 
93f0: 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  is invoked perio
9400: 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
9410: 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
9420: 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  s to [sqlite3_ex
9430: 65 63 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ec()],.** [sqlit
9440: 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
9450: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
9460: 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c  e()].  An exampl
9470: 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 20 0a  e use for this .
9480: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
9490: 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
94a0: 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
94b0: 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
94c0: 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63  * The progress c
94d0: 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
94e0: 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72  ed once for ever
94f0: 79 20 4e 20 76 69 72 74 75 61 6c 20 6d 61 63 68  y N virtual mach
9500: 69 6e 65 20 6f 70 63 6f 64 65 73 2c 0a 2a 2a 20  ine opcodes,.** 
9510: 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
9520: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
9530: 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
9540: 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   The progress ca
9550: 6c 6c 62 61 63 6b 0a 2a 2a 20 69 74 73 65 6c 66  llback.** itself
9560: 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62   is identified b
9570: 79 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  y the third argu
9580: 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e  ment to this fun
9590: 63 74 69 6f 6e 2e 20 54 68 65 20 66 6f 75 72 74  ction. The fourt
95a0: 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  h.** argument to
95b0: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   this function i
95c0: 73 20 61 20 76 6f 69 64 20 70 6f 69 6e 74 65 72  s a void pointer
95d0: 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 70   passed to the p
95e0: 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
95f0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 65 61 63  .** function eac
9600: 68 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e 76  h time it is inv
9610: 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  oked..**.** If a
9620: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
9630: 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
9640: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 6f 72 20  te3_step()], or 
9650: 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
9660: 6c 65 28 29 5d 0a 2a 2a 20 72 65 73 75 6c 74 73  le()].** results
9670: 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e 20 4e   in fewer than N
9680: 20 6f 70 63 6f 64 65 73 20 62 65 69 6e 67 20 65   opcodes being e
9690: 78 65 63 75 74 65 64 2c 20 74 68 65 6e 20 74 68  xecuted, then th
96a0: 65 20 70 72 6f 67 72 65 73 73 20 0a 2a 2a 20 63  e progress .** c
96b0: 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72  allback is never
96c0: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 0a 2a 2a   invoked..** .**
96d0: 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70   Only a single p
96e0: 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
96f0: 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
9700: 20 72 65 67 69 73 74 65 72 65 64 20 66 6f 72 20   registered for 
9710: 65 61 63 68 0a 2a 2a 20 6f 70 65 6e 20 64 61 74  each.** open dat
9720: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9730: 2e 20 20 45 76 65 72 79 20 63 61 6c 6c 20 74 6f  .  Every call to
9740: 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
9750: 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 6f  s_handler().** o
9760: 76 65 72 77 72 69 74 65 73 20 74 68 65 20 72 65  verwrites the re
9770: 73 75 6c 74 73 20 6f 66 20 74 68 65 20 70 72 65  sults of the pre
9780: 76 69 6f 75 73 20 63 61 6c 6c 2e 0a 2a 2a 20 54  vious call..** T
9790: 6f 20 72 65 6d 6f 76 65 20 74 68 65 20 70 72 6f  o remove the pro
97a0: 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 61  gress callback a
97b0: 6c 74 6f 67 65 74 68 65 72 2c 20 70 61 73 73 20  ltogether, pass 
97c0: 4e 55 4c 4c 20 61 73 20 74 68 65 20 74 68 69 72  NULL as the thir
97d0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
97e0: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
97f0: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f  **.** If the pro
9800: 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
9810: 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
9820: 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68  other than 0, th
9830: 65 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  en the current .
9840: 2a 2a 20 71 75 65 72 79 20 69 73 20 69 6d 6d 65  ** query is imme
9850: 64 69 61 74 65 6c 79 20 74 65 72 6d 69 6e 61 74  diately terminat
9860: 65 64 20 61 6e 64 20 61 6e 79 20 64 61 74 61 62  ed and any datab
9870: 61 73 65 20 63 68 61 6e 67 65 73 20 72 6f 6c 6c  ase changes roll
9880: 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  ed back..** The 
9890: 63 6f 6e 74 61 69 6e 69 6e 67 20 5b 73 71 6c 69  containing [sqli
98a0: 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
98b0: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 6f  lite3_step()], o
98c0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  r.** [sqlite3_ge
98d0: 74 5f 74 61 62 6c 65 28 29 5d 20 63 61 6c 6c 20  t_table()] call 
98e0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
98f0: 4e 54 45 52 52 55 50 54 2e 20 20 20 54 68 69 73  NTERRUPT.   This
9900: 20 66 65 61 74 75 72 65 0a 2a 2a 20 63 61 6e 20   feature.** can 
9910: 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
9920: 6d 70 6c 65 2c 20 74 6f 20 69 6d 70 6c 65 6d 65  mple, to impleme
9930: 6e 74 20 74 68 65 20 22 43 61 6e 63 65 6c 22 20  nt the "Cancel" 
9940: 62 75 74 74 6f 6e 20 6f 6e 20 61 0a 2a 2a 20 70  button on a.** p
9950: 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
9960: 6f 78 20 69 6e 20 61 20 47 55 49 2e 0a 2a 2f 0a  ox in a GUI..*/.
9970: 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
9980: 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
9990: 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
99a0: 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
99b0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
99c0: 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
99d0: 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
99e0: 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 4f 70 65  ection.**.** Ope
99f0: 6e 20 74 68 65 20 73 71 6c 69 74 65 20 64 61 74  n the sqlite dat
9a00: 61 62 61 73 65 20 66 69 6c 65 20 22 66 69 6c 65  abase file "file
9a10: 6e 61 6d 65 22 2e 20 20 54 68 65 20 22 66 69 6c  name".  The "fil
9a20: 65 6e 61 6d 65 22 20 69 73 20 55 54 46 2d 38 0a  ename" is UTF-8.
9a30: 2a 2a 20 65 6e 63 6f 64 65 64 20 66 6f 72 20 73  ** encoded for s
9a40: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
9a50: 64 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  d UTF-16 encoded
9a60: 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
9a70: 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 66 6f 72  yte order.** for
9a80: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
9a90: 29 2e 20 20 41 6e 20 5b 73 71 6c 69 74 65 33 2a  ).  An [sqlite3*
9aa0: 5d 20 68 61 6e 64 6c 65 20 69 73 20 72 65 74 75  ] handle is retu
9ab0: 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
9ac0: 76 65 6e 0a 2a 2a 20 69 66 20 61 6e 20 65 72 72  ven.** if an err
9ad0: 6f 72 20 6f 63 63 75 72 73 2e 20 49 66 20 74 68  or occurs. If th
9ae0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
9af0: 65 6e 65 64 20 28 6f 72 20 63 72 65 61 74 65 64  ened (or created
9b00: 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 0a  ) successfully,.
9b10: 2a 2a 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f  ** then SQLITE_O
9b20: 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f  K is returned. O
9b30: 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
9b40: 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
9b50: 65 64 2e 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  ed. The.** sqlit
9b60: 65 33 5f 65 72 72 6d 73 67 28 29 20 6f 72 20 73  e3_errmsg() or s
9b70: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
9b80: 29 20 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )  routines can 
9b90: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
9ba0: 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
9bb0: 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
9bc0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
9bd0: 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
9be0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 6f  database file do
9bf0: 65 73 20 6e 6f 74 20 65 78 69 73 74 2c 20 74 68  es not exist, th
9c00: 65 6e 20 61 20 6e 65 77 20 64 61 74 61 62 61 73  en a new databas
9c10: 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
9c20: 64 0a 2a 2a 20 61 73 20 6e 65 65 64 65 64 2e 20  d.** as needed. 
9c30: 20 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63   The default enc
9c40: 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
9c50: 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
9c60: 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74  TF-8 if.** sqlit
9c70: 65 33 5f 6f 70 65 6e 28 29 20 69 73 20 63 61 6c  e3_open() is cal
9c80: 6c 65 64 20 61 6e 64 20 55 54 46 2d 31 36 20 69  led and UTF-16 i
9c90: 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  f sqlite3_open16
9ca0: 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
9cb0: 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
9cc0: 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
9cd0: 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
9ce0: 2c 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f  , resources asso
9cf0: 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
9d00: 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61  he [sqlite3*] ha
9d10: 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
9d20: 65 6c 65 61 73 65 64 20 62 79 20 70 61 73 73 69  eleased by passi
9d30: 6e 67 20 69 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ng it to.** sqli
9d40: 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 68 65 6e  te3_close() when
9d50: 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
9d60: 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
9d70: 20 4e 6f 74 65 20 74 6f 20 77 69 6e 64 6f 77 73   Note to windows
9d80: 20 75 73 65 72 73 3a 20 20 54 68 65 20 65 6e 63   users:  The enc
9d90: 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
9da0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
9db0: 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
9dc0: 65 33 5f 6f 70 65 6e 28 29 20 6d 75 73 74 20 62  e3_open() must b
9dd0: 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
9de0: 74 65 76 65 72 20 63 6f 64 65 70 61 67 65 20 69  tever codepage i
9df0: 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 64  s currently.** d
9e00: 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
9e10: 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
9e20: 74 65 72 6e 61 74 69 6f 6e 61 6c 20 63 68 61 72  ternational char
9e30: 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
9e40: 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 74 6f 20 55  onverted.** to U
9e50: 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
9e60: 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 20  ssing them into 
9e70: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a  sqlite3_open()..
9e80: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
9e90: 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
9ea0: 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
9eb0: 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
9ec0: 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
9ed0: 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
9ee0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
9ef0: 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
9f00: 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
9f10: 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
9f20: 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
9f30: 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
9f40: 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
9f50: 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
9f60: 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
9f70: 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
9f80: 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
9f90: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9fa0: 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
9fb0: 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20   Messages.**.** 
9fc0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
9fd0: 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
9fe0: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
9ff0: 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ric.** [SQLITE_O
a000: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  K | result code]
a010: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
a020: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
a030: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a  d result code].*
a040: 2a 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72  * for the most r
a050: 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c  ecent failed sql
a060: 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20  ite3_* API call 
a070: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
a080: 74 68 20 5b 73 71 6c 69 74 65 33 5d 20 68 61 6e  th [sqlite3] han
a090: 64 6c 65 20 27 64 62 27 2e 20 20 49 66 20 61 20  dle 'db'.  If a 
a0a0: 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
a0b0: 61 69 6c 65 64 20 62 75 74 20 74 68 65 0a 2a 2a  ailed but the.**
a0c0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
a0d0: 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
a0e0: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
a0f0: 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65  e from sqlite3_e
a100: 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 73 20 75  rrcode().** is u
a110: 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a  ndefined. .**.**
a120: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   The sqlite3_err
a130: 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
a140: 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
a150: 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
a160: 61 75 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  auge.** text tha
a170: 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
a180: 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
a190: 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 72   UTF8 or UTF16 r
a1a0: 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
a1b0: 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
a1c0: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
a1d0: 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
a1e0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 20 20  ed internally.  
a1f0: 54 68 65 20 0a 2a 2a 20 73 74 72 69 6e 67 20 6d  The .** string m
a200: 61 79 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ay be overwritte
a210: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
a220: 20 62 79 20 73 75 62 73 65 71 75 65 6e 74 20 63   by subsequent c
a230: 61 6c 6c 73 20 74 6f 20 53 51 4c 69 74 65 0a 2a  alls to SQLite.*
a240: 2a 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  * interface func
a250: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  tions..**.** Cal
a260: 6c 73 20 74 6f 20 6d 61 6e 79 20 73 71 6c 69 74  ls to many sqlit
a270: 65 33 5f 2a 20 66 75 6e 63 74 69 6f 6e 73 20 73  e3_* functions s
a280: 65 74 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  et the error cod
a290: 65 20 61 6e 64 20 73 74 72 69 6e 67 20 72 65 74  e and string ret
a2a0: 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
a2b0: 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c  ite3_errcode()],
a2c0: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
a2d0: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
a2e0: 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a  3_errmsg16()].**
a2f0: 20 28 6f 76 65 72 77 72 69 74 69 6e 67 20 74 68   (overwriting th
a300: 65 20 70 72 65 76 69 6f 75 73 20 76 61 6c 75 65  e previous value
a310: 73 29 2e 20 4e 6f 74 65 20 74 68 61 74 20 63 61  s). Note that ca
a320: 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
a330: 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 5b  errcode()],.** [
a340: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
a350: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
a360: 65 72 72 6d 73 67 31 36 28 29 5d 20 74 68 65 6d  errmsg16()] them
a370: 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 66  selves do not af
a380: 66 65 63 74 20 74 68 65 0a 2a 2a 20 72 65 73 75  fect the.** resu
a390: 6c 74 73 20 6f 66 20 66 75 74 75 72 65 20 69 6e  lts of future in
a3a0: 76 6f 63 61 74 69 6f 6e 73 2e 20 20 43 61 6c 6c  vocations.  Call
a3b0: 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65  s to API routine
a3c0: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65  s that do not re
a3d0: 74 75 72 6e 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  turn.** an error
a3e0: 20 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 73 3a   code (examples:
a3f0: 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
a400: 6f 75 6e 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  ount()] or [sqli
a410: 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 29 20  te3_mprintf()]) 
a420: 64 6f 0a 2a 2a 20 6e 6f 74 20 63 68 61 6e 67 65  do.** not change
a430: 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
a440: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
a450: 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20   routine..**.** 
a460: 41 73 73 75 6d 69 6e 67 20 6e 6f 20 6f 74 68 65  Assuming no othe
a470: 72 20 69 6e 74 65 72 76 65 6e 69 6e 67 20 73 71  r intervening sq
a480: 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
a490: 73 20 61 72 65 20 6d 61 64 65 2c 20 74 68 65 20  s are made, the 
a4a0: 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 72 65  error.** code re
a4b0: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
a4c0: 75 6e 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63  unction is assoc
a4d0: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73  iated with the s
a4e0: 61 6d 65 20 65 72 72 6f 72 20 61 73 0a 2a 2a 20  ame error as.** 
a4f0: 74 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  the strings retu
a500: 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
a510: 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b  _errmsg()] and [
a520: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
a530: 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
a540: 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
a550: 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20  te3 *db);.const 
a560: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
a570: 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
a580: 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
a590: 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
a5a0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
a5b0: 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61  API3REF: SQL Sta
a5c0: 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
a5d0: 0a 2a 2a 20 49 6e 73 74 61 6e 63 65 20 6f 66 20  .** Instance of 
a5e0: 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
a5f0: 65 73 65 6e 74 20 73 69 6e 67 6c 65 20 53 51 4c  esent single SQL
a600: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68   statements.  Th
a610: 69 73 0a 2a 2a 20 69 73 20 76 61 72 69 6f 75 73  is.** is various
a620: 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70  ly known as a "p
a630: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
a640: 74 22 20 6f 72 20 61 20 0a 2a 2a 20 22 63 6f 6d  t" or a .** "com
a650: 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
a660: 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
a670: 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
a680: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c 69 66 65  .** .** The life
a690: 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20   of a statement 
a6a0: 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65  object goes some
a6b0: 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a  thing like this:
a6c0: 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
a6d0: 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f  li> Create the o
a6e0: 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
a6f0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
a700: 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a  )] or a related.
a710: 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e  **      function
a720: 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
a730: 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
a740: 72 61 6d 65 74 65 72 73 20 75 73 69 6e 67 0a 2a  rameters using.*
a750: 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f  *      [sqlite3_
a760: 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
a770: 74 65 33 5f 62 69 6e 64 5f 2a 20 69 6e 74 65 72  te3_bind_* inter
a780: 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20  faces]..** <li> 
a790: 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
a7a0: 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
a7b0: 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
a7c0: 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
a7d0: 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61  i> Reset the sta
a7e0: 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
a7f0: 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
a800: 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
a810: 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
a820: 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
a830: 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
a840: 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
a850: 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
a860: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
a870: 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  ]..** </ol>.**.*
a880: 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d  * Refer to docum
a890: 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  entation on indi
a8a0: 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61  vidual methods a
a8b0: 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f  bove for additio
a8c0: 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
a8d0: 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
a8e0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
a8f0: 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
a900: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a910: 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
a920: 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  QL Statement.**.
a930: 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
a940: 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
a950: 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
a960: 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
a970: 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
a980: 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
a990: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 0a  hese routines. .
a9a0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
a9b0: 61 72 67 75 6d 65 6e 74 20 22 64 62 22 20 69 73  argument "db" is
a9c0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 20 7c 20 53   an [sqlite3 | S
a9d0: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 68  QLite database h
a9e0: 61 6e 64 6c 65 5d 20 0a 2a 2a 20 6f 62 74 61 69  andle] .** obtai
a9f0: 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
aa00: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
aa10: 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71  3_open()] or [sq
aa20: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
aa30: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
aa40: 72 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22 20 69  rgument "zSql" i
aa50: 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
aa60: 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
aa70: 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
aa80: 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
aa90: 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
aaa0: 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
aab0: 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
aac0: 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
aad0: 63 65 73 20 75 73 65 73 20 55 54 46 2d 38 20 61  ces uses UTF-8 a
aae0: 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
aaf0: 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
ab00: 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
ab10: 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
ab20: 20 49 66 20 74 68 65 20 6e 65 78 74 20 61 72 67   If the next arg
ab30: 75 6d 65 6e 74 2c 20 22 6e 42 79 74 65 73 22 2c  ument, "nBytes",
ab40: 20 69 73 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e   is less.** than
ab50: 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
ab60: 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
ab70: 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
ab80: 72 6d 69 6e 61 74 6f 72 2e 20 20 49 66 0a 2a 2a  rminator.  If.**
ab90: 20 22 6e 42 79 74 65 73 22 20 69 73 20 6e 6f 74   "nBytes" is not
aba0: 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
abb0: 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
abc0: 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
abd0: 72 69 6e 67 20 7a 53 71 6c 0a 2a 2a 20 69 6e 20  ring zSql.** in 
abe0: 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
abf0: 63 74 65 72 73 29 2e 0a 2a 2a 0a 2a 2a 20 2a 70  cters)..**.** *p
ac00: 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
ac10: 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
ac20: 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68  rst byte past th
ac30: 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
ac40: 73 74 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  st.** SQL statem
ac50: 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
ac60: 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
ac70: 63 6f 6d 70 69 6c 65 73 20 74 68 65 20 66 69 72  compiles the fir
ac80: 73 74 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  st statement.** 
ac90: 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
aca0: 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
acb0: 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d  ting to what rem
acc0: 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
acd0: 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69  .**.** *ppStmt i
ace0: 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
acf0: 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 0a 2a  to a compiled .*
ad00: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
ad10: 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  | SQL statement 
ad20: 73 74 72 75 63 74 75 72 65 5d 20 74 68 61 74 20  structure] that 
ad30: 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
ad40: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
ad50: 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72 20 69  3_step()].  Or i
ad60: 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
ad70: 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 6d 61 79  ror, *ppStmt may
ad80: 20 62 65 0a 2a 2a 20 73 65 74 20 74 6f 20 4e 55   be.** set to NU
ad90: 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75  LL.  If the inpu
ada0: 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 65 64  t text contained
adb0: 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
adc0: 69 6e 70 75 74 20 69 73 20 61 6e 64 0a 2a 2a 20  input is and.** 
add0: 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
ade0: 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
adf0: 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
ae00: 6f 20 4e 55 4c 4c 2e 20 20 54 68 65 20 63 61 6c  o NULL.  The cal
ae10: 6c 69 6e 67 0a 2a 2a 20 70 72 6f 63 65 64 75 72  ling.** procedur
ae20: 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
ae30: 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
ae40: 65 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73  e compiled SQL s
ae50: 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e  tatement.** usin
ae60: 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
ae70: 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
ae80: 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
ae90: 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73  h it..**.** On s
aea0: 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
aeb0: 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
aec0: 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 0a    Otherwise an .
aed0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
aee0: 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69   | error code] i
aef0: 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
af00: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
af10: 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
af20: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
af30: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
af40: 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
af50: 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
af60: 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
af70: 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
af80: 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
af90: 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
afa0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
afb0: 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
afc0: 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
afd0: 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
afe0: 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
aff0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
b000: 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
b010: 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
b020: 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
b030: 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
b040: 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72 69 67 69  of the .** origi
b050: 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
b060: 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
b070: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
b080: 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
b090: 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e  ehave a differen
b0a0: 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a  tly in two ways:
b0b0: 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
b0c0: 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  li>.** If the da
b0d0: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
b0e0: 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
b0f0: 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
b100: 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
b110: 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
b120: 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
b130: 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
b140: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
b150: 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
b160: 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
b170: 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
b180: 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65  in.  If the sche
b190: 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69  ma has changed i
b1a0: 6e 20 61 20 77 61 79 0a 2a 2a 20 74 68 61 74 20  n a way.** that 
b1b0: 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d  makes the statem
b1c0: 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61  ent no longer va
b1d0: 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  lid, [sqlite3_st
b1e0: 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c  ep()] will still
b1f0: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
b200: 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74  TE_SCHEMA].  But
b210: 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61   unlike the lega
b220: 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51  cy behavior, [SQ
b230: 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a  LITE_SCHEMA] is.
b240: 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  ** now a fatal e
b250: 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b  rror.  Calling [
b260: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
b270: 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c  v2()] again will
b280: 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a   not make the.**
b290: 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20   error go away. 
b2a0: 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69   Note: use [sqli
b2b0: 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f  te3_errmsg()] to
b2c0: 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 20 6f   find the text o
b2d0: 66 20 74 68 65 20 70 61 72 73 69 6e 67 0a 2a 2a  f the parsing.**
b2e0: 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75   error that resu
b2f0: 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  lts in an [SQLIT
b300: 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e  E_SCHEMA] return
b310: 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
b320: 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e   <li>.** When an
b330: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 0a   error occurs, .
b340: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
b350: 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
b360: 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
b370: 6c 65 64 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  led .** [SQLITE_
b380: 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74 20 63  ERROR | result c
b390: 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  odes] or.** [SQL
b3a0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
b3b0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
b3c0: 20 63 6f 64 65 73 5d 20 73 75 63 68 20 61 73 20   codes] such as 
b3d0: 64 69 72 65 63 74 6c 79 2e 0a 2a 2a 20 54 68 65  directly..** The
b3e0: 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
b3f0: 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c 69 74   was that [sqlit
b400: 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
b410: 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
b420: 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54  eneric.** [SQLIT
b430: 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
b440: 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77 6f 75  code and you wou
b450: 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
b460: 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
b470: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
b480: 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  et()] in order t
b490: 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
b4a0: 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
b4b0: 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20 57  he problem..** W
b4c0: 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
b4d0: 70 61 72 65 20 69 6e 74 65 72 66 61 63 65 73 2c  pare interfaces,
b4e0: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
b4f0: 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
b500: 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74 75 72  rror is.** retur
b510: 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
b520: 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
b530: 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
b540: 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
b550: 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
b560: 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
b570: 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
b580: 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
b590: 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
b5a0: 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
b5b0: 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
b5c0: 79 74 65 73 2c 20 20 20 20 20 20 20 20 20 20 20  ytes,           
b5d0: 20 20 2f 2a 20 4c 65 6e 67 74 68 20 6f 66 20 7a    /* Length of z
b5e0: 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
b5f0: 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
b600: 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
b610: 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
b620: 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
b630: 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
b640: 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
b650: 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
b660: 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
b670: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
b680: 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
b690: 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
b6a0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
b6b0: 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
b6c0: 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
b6d0: 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
b6e0: 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
b6f0: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
b700: 65 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  es,             
b710: 2f 2a 20 4c 65 6e 67 74 68 20 6f 66 20 7a 53 71  /* Length of zSq
b720: 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
b730: 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
b740: 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
b750: 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
b760: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
b770: 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
b780: 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
b790: 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
b7a0: 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
b7b0: 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
b7c0: 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
b7d0: 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
b7e0: 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
b7f0: 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
b800: 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
b810: 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
b820: 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
b830: 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 73   */.  int nBytes
b840: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ,             /*
b850: 20 4c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   Length of zSql 
b860: 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
b870: 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
b880: 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
b890: 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
b8a0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
b8b0: 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
b8c0: 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
b8d0: 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
b8e0: 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
b8f0: 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
b900: 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
b910: 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
b920: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
b930: 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
b940: 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
b950: 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
b960: 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
b970: 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
b980: 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  s,             /
b990: 2a 20 4c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  * Length of zSql
b9a0: 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
b9b0: 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
b9c0: 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
b9d0: 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
b9e0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
b9f0: 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
ba00: 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
ba10: 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
ba20: 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
ba30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
ba40: 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
ba50: 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
ba60: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
ba70: 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 20   dynamic typing 
ba80: 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
ba90: 74 20 73 74 6f 72 65 73 2e 20 20 56 61 6c 75 65  t stores.  Value
baa0: 73 20 63 61 6e 20 0a 2a 2a 20 62 65 20 69 6e 74  s can .** be int
bab0: 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
bac0: 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
bad0: 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
bae0: 20 4e 55 4c 4c 2e 20 20 57 68 65 6e 0a 2a 2a 20   NULL.  When.** 
baf0: 70 61 73 73 69 6e 67 20 61 72 6f 75 6e 64 20 76  passing around v
bb00: 61 6c 75 65 73 20 69 6e 74 65 72 6e 61 6c 6c 79  alues internally
bb10: 2c 20 65 61 63 68 20 76 61 6c 75 65 20 69 73 20  , each value is 
bb20: 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 0a 2a  represented as.*
bb30: 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * an instance of
bb40: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
bb50: 75 65 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  ue object..*/.ty
bb60: 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
bb70: 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
bb80: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
bb90: 20 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43    SQL Function C
bba0: 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
bbb0: 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
bbc0: 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
bbd0: 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
bbe0: 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
bbf0: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
bc00: 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20  text object.  A 
bc10: 70 6f 69 6e 74 65 72 20 74 6f 20 73 75 63 68 20  pointer to such 
bc20: 61 6e 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  an object is the
bc30: 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d 65  .** first parame
bc40: 74 65 72 20 74 6f 20 75 73 65 72 2d 64 65 66 69  ter to user-defi
bc50: 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
bc60: 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
bc70: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
bc80: 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
bc90: 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
bca0: 49 33 52 45 46 3a 20 20 42 69 6e 64 69 6e 67 20  I3REF:  Binding 
bcb0: 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
bcc0: 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
bcd0: 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73  .** In the SQL s
bce0: 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20  trings input to 
bcf0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
bd00: 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
bd10: 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6f 6e 65 20  ariants,.** one 
bd20: 6f 72 20 6d 6f 72 65 20 6c 69 74 65 72 61 6c 73  or more literals
bd30: 20 63 61 6e 20 62 65 20 72 65 70 6c 61 63 65 20   can be replace 
bd40: 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69  by a parameter i
bd50: 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 0a 2a  n one of these.*
bd60: 2a 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c  * forms:.**.** <
bd70: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
bd80: 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
bd90: 3c 6c 69 3e 20 20 3a 41 41 41 0a 2a 2a 20 3c 6c  <li>  :AAA.** <l
bda0: 69 3e 20 20 40 41 41 41 0a 2a 2a 20 3c 6c 69 3e  i>  @AAA.** <li>
bdb0: 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
bdc0: 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72  **.** In the par
bdd0: 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f  ameter forms sho
bde0: 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20  wn above NNN is 
bdf0: 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
be00: 61 6c 2c 0a 2a 2a 20 41 41 41 20 69 73 20 61 6e  al,.** AAA is an
be10: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
be20: 65 6e 74 69 66 69 65 72 20 61 6e 64 20 56 56 56  entifier and VVV
be30: 20 69 73 20 61 20 76 61 72 69 61 62 6c 65 20 6e   is a variable n
be40: 61 6d 65 20 61 63 63 6f 72 64 69 6e 67 0a 2a 2a  ame according.**
be50: 20 74 6f 20 74 68 65 20 73 79 6e 74 61 78 20 72   to the syntax r
be60: 75 6c 65 73 20 6f 66 20 74 68 65 20 54 43 4c 20  ules of the TCL 
be70: 70 72 6f 67 72 61 6d 6d 69 6e 67 20 6c 61 6e 67  programming lang
be80: 75 61 67 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c  uage..** The val
be90: 75 65 73 20 6f 66 20 74 68 65 73 65 20 70 61 72  ues of these par
bea0: 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
beb0: 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
bec0: 65 74 65 72 20 6e 61 6d 65 73 22 29 0a 2a 2a 20  eter names").** 
bed0: 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
bee0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
bef0: 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
bf00: 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
bf10: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
bf20: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
bf30: 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
bf40: 75 74 69 6e 65 73 20 61 6c 77 61 79 73 20 69 73  utines always is
bf50: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
bf60: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
bf70: 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
bf80: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
bf90: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
bfa0: 6f 72 0a 2a 2a 20 69 74 73 20 76 61 72 69 61 6e  or.** its varian
bfb0: 74 73 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 0a  ts.  The second.
bfc0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  ** argument is t
bfd0: 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
bfe0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
bff0: 73 65 74 2e 20 20 54 68 65 20 66 69 72 73 74 20  set.  The first 
c000: 70 61 72 61 6d 65 74 65 72 20 68 61 73 0a 2a 2a  parameter has.**
c010: 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
c020: 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
c030: 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  med parameter is
c040: 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
c050: 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 0a 2a 2a 20  once, second.** 
c060: 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
c070: 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
c080: 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
c090: 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
c0a0: 63 63 75 72 72 65 6e 63 65 2e 20 20 54 68 65 20  ccurrence.  The 
c0b0: 69 6e 64 65 78 20 66 6f 72 0a 2a 2a 20 6e 61 6d  index for.** nam
c0c0: 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
c0d0: 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
c0e0: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
c0f0: 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
c100: 74 65 72 5f 6e 61 6d 65 28 29 5d 20 41 50 49 20  ter_name()] API 
c110: 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 65  if desired.  The
c120: 20 69 6e 64 65 78 20 66 6f 72 20 22 3f 4e 4e 4e   index for "?NNN
c130: 22 0a 2a 2a 20 70 61 72 61 6d 65 74 65 73 20 69  ".** parametes i
c140: 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
c150: 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76  NN..** The NNN v
c160: 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
c170: 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 63  ween 1 and the c
c180: 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70  ompile-time.** p
c190: 61 72 61 6d 65 74 65 72 20 53 51 4c 49 54 45 5f  arameter SQLITE_
c1a0: 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MAX_VARIABLE_NUM
c1b0: 42 45 52 20 28 64 65 66 61 75 6c 74 20 76 61 6c  BER (default val
c1c0: 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 20 53 65 65  ue: 999)..** See
c1d0: 20 3c 61 20 68 72 65 66 3d 22 6c 69 6d 69 74 73   <a href="limits
c1e0: 2e 68 74 6d 6c 22 3e 6c 69 6d 69 74 73 2e 68 74  .html">limits.ht
c1f0: 6d 6c 3c 2f 61 3e 20 66 6f 72 20 61 64 64 69 74  ml</a> for addit
c200: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
c210: 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  n..**.** The thi
c220: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
c230: 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
c240: 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
c250: 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73  r..**.** In thos
c260: 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  e.** routines th
c270: 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
c280: 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
c290: 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62  alue is the numb
c2a0: 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 69  er of bytes.** i
c2b0: 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
c2c0: 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
c2d0: 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20  he value is the 
c2e0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
c2f0: 69 6e 20 74 68 65 0a 2a 2a 20 73 74 72 69 6e 67  in the.** string
c300: 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
c310: 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 20   of characters. 
c320: 20 54 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   The number.** o
c330: 66 20 62 79 74 65 73 20 64 6f 65 73 20 6e 6f 74  f bytes does not
c340: 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
c350: 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20  o-terminator at 
c360: 74 68 65 20 65 6e 64 20 6f 66 20 73 74 72 69 6e  the end of strin
c370: 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  gs..** If the fo
c380: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
c390: 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  s negative, the 
c3a0: 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
c3b0: 72 69 6e 67 20 69 73 0a 2a 2a 20 6e 75 6d 62 65  ring is.** numbe
c3c0: 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
c3d0: 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
c3e0: 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
c3f0: 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 67 75  * The fifth argu
c400: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
c410: 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
c420: 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
c430: 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
c440: 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
c450: 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
c460: 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
c470: 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
c480: 20 74 65 78 74 20 61 66 74 65 72 20 53 51 4c 69   text after SQLi
c490: 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
c4a0: 77 69 74 68 20 69 74 2e 20 20 49 66 20 74 68 65  with it.  If the
c4b0: 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
c4c0: 69 73 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 61  is the.** specia
c4d0: 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
c4e0: 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 74 68  STATIC], then th
c4f0: 65 20 6c 69 62 72 61 72 79 20 61 73 73 75 6d 65  e library assume
c500: 73 20 74 68 61 74 20 74 68 65 20 69 6e 66 6f 72  s that the infor
c510: 6d 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 20  mation.** is in 
c520: 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
c530: 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
c540: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
c550: 66 72 65 65 64 2e 20 20 49 66 20 74 68 65 0a 2a  freed.  If the.*
c560: 2a 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  * fifth argument
c570: 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
c580: 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
c590: 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ], then SQLite m
c5a0: 61 6b 65 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20  akes its.** own 
c5b0: 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
c5c0: 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
c5d0: 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65  tely, before the
c5e0: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
c5f0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
c600: 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
c610: 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
c620: 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
c630: 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
c640: 6c 65 6e 67 74 68 20 6e 20 74 68 61 74 0a 2a 2a  length n that.**
c650: 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
c660: 7a 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f 62 6c  zeros.  A zerobl
c670: 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
c680: 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
c690: 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
c6a0: 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 20  eger to hold it 
c6b0: 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
c6c0: 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
c6d0: 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
c6e0: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
c6f0: 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 2d 68  serve as place-h
c700: 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
c710: 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
c720: 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
c730: 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  en using .** [sq
c740: 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
c750: 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c 4f 42  | increment BLOB
c760: 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
c770: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
c780: 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
c790: 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
c7a0: 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c  ed after.** [sql
c7b0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
c7c0: 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 69  )] (and its vari
c7d0: 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65  ants) or [sqlite
c7e0: 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a  3_reset()] and.*
c7f0: 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  * before [sqlite
c800: 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69  3_step()]..** Bi
c810: 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
c820: 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
c830: 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
c840: 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f  routine..** Unbo
c850: 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
c860: 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
c870: 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
c880: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
c890: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
c8a0: 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
c8b0: 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a   error code if.*
c8c0: 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  * anything goes 
c8d0: 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f  wrong.  [SQLITE_
c8e0: 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
c8f0: 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
c900: 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
c910: 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b  out of range.  [
c920: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
c930: 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
c940: 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53  loc fails..** [S
c950: 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 69 73  QLITE_MISUSE] is
c960: 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
c970: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
c980: 63 61 6c 6c 65 64 20 6f 6e 20 61 20 76 69 72 74  called on a virt
c990: 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 74  ual.** machine t
c9a0: 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67  hat is the wrong
c9b0: 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 20   state or which 
c9c0: 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e  has already been
c9d0: 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2f 0a 69   finalized..*/.i
c9e0: 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
c9f0: 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
ca00: 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
ca10: 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
ca20: 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
ca30: 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
ca40: 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
ca50: 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
ca60: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
ca70: 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
ca80: 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
ca90: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
caa0: 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
cab0: 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
cac0: 69 74 65 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  ite_int64);.int 
cad0: 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
cae0: 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
caf0: 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
cb00: 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
cb10: 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
cb20: 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
cb30: 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
cb40: 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
cb50: 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
cb60: 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
cb70: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
cb80: 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
cb90: 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
cba0: 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
cbb0: 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
cbc0: 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
cbd0: 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
cbe0: 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
cbf0: 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
cc00: 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
cc10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
cc20: 6d 62 65 72 20 4f 66 20 48 6f 73 74 20 50 61 72  mber Of Host Par
cc30: 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 52 65  ameters.**.** Re
cc40: 74 75 72 6e 20 74 68 65 20 6c 61 72 67 65 73 74  turn the largest
cc50: 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
cc60: 69 6e 64 65 78 20 69 6e 20 74 68 65 20 70 72 65  index in the pre
cc70: 63 6f 6d 70 69 6c 65 64 20 73 74 61 74 65 6d 65  compiled stateme
cc80: 6e 74 20 67 69 76 65 6e 0a 2a 2a 20 61 73 20 74  nt given.** as t
cc90: 68 65 20 61 72 67 75 6d 65 6e 74 2e 20 20 57 68  he argument.  Wh
cca0: 65 6e 20 74 68 65 20 68 6f 73 74 20 70 61 72 61  en the host para
ccb0: 6d 65 74 65 72 73 20 61 72 65 20 6f 66 20 74 68  meters are of th
ccc0: 65 20 66 6f 72 6d 73 20 6c 69 6b 65 20 22 3a 41  e forms like ":A
ccd0: 41 41 22 0a 2a 2a 20 6f 72 20 22 3f 22 2c 20 74  AA".** or "?", t
cce0: 68 65 6e 20 74 68 65 79 20 61 72 65 20 61 73 73  hen they are ass
ccf0: 69 67 6e 65 64 20 73 65 71 75 65 6e 74 69 61 6c  igned sequential
cd00: 20 69 6e 63 72 65 61 73 69 6e 67 20 6e 75 6d 62   increasing numb
cd10: 65 72 73 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ers beginning.**
cd20: 20 77 69 74 68 20 6f 6e 65 2c 20 73 6f 20 74 68   with one, so th
cd30: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
cd40: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
cd50: 66 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 48  f parameters.  H
cd60: 6f 77 65 76 65 72 0a 2a 2a 20 69 66 20 74 68 65  owever.** if the
cd70: 20 73 61 6d 65 20 68 6f 73 74 20 70 61 72 61 6d   same host param
cd80: 65 74 65 72 20 6e 61 6d 65 20 69 73 20 75 73 65  eter name is use
cd90: 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
cda0: 2c 20 65 61 63 68 20 6f 63 63 75 72 72 61 6e 63  , each occurranc
cdb0: 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e 20 74 68  e.** is given th
cdc0: 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 2c 20 73  e same number, s
cdd0: 6f 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  o the value retu
cde0: 72 6e 65 64 20 69 6e 20 74 68 61 74 20 63 61 73  rned in that cas
cdf0: 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 0a  e is the number.
ce00: 2a 2a 20 6f 66 20 75 6e 69 71 75 65 20 68 6f 73  ** of unique hos
ce10: 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
ce20: 73 2e 20 20 49 66 20 68 6f 73 74 20 70 61 72 61  s.  If host para
ce30: 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
ce40: 72 6d 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 61 72 65  rm "?NNN".** are
ce50: 20 75 73 65 64 20 28 77 68 65 72 65 20 4e 4e 4e   used (where NNN
ce60: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29 20   is an integer) 
ce70: 74 68 65 6e 20 74 68 65 72 65 20 6d 69 67 68 74  then there might
ce80: 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 0a   be gaps in the.
ce90: 2a 2a 20 6e 75 6d 62 65 72 69 6e 67 20 61 6e 64  ** numbering and
cea0: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
ceb0: 6e 65 64 20 62 79 20 74 68 69 73 20 69 6e 74 65  ned by this inte
cec0: 72 66 61 63 65 20 69 73 20 74 68 65 20 69 6e 64  rface is the ind
ced0: 65 78 20 6f 66 20 74 68 65 0a 2a 2a 20 68 6f 73  ex of the.** hos
cee0: 74 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68  t parameter with
cef0: 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64   the largest ind
cf00: 65 78 20 76 61 6c 75 65 2e 0a 2a 2f 0a 69 6e 74  ex value..*/.int
cf10: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
cf20: 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
cf30: 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
cf40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
cf50: 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
cf60: 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 54 68  rameter.**.** Th
cf70: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
cf80: 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
cf90: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
cfa0: 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  n-th parameter i
cfb0: 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  n a .** [sqlite3
cfc0: 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64  _stmt | prepared
cfd0: 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
cfe0: 48 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  Host parameters 
cff0: 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3a 41 41  of the form ":AA
d000: 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
d010: 22 24 56 56 56 22 20 68 61 76 65 20 61 20 6e 61  "$VVV" have a na
d020: 6d 65 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 74  me.** which is t
d030: 68 65 20 73 74 72 69 6e 67 20 22 3a 41 41 41 22  he string ":AAA"
d040: 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
d050: 56 56 56 22 2e 20 20 0a 2a 2a 20 49 6e 20 6f 74  VVV".  .** In ot
d060: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
d070: 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
d080: 22 20 6f 72 20 22 40 22 0a 2a 2a 20 69 73 20 69  " or "@".** is i
d090: 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
d0a0: 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20  of the name..** 
d0b0: 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
d0c0: 65 20 66 6f 72 6d 20 22 3f 22 20 6f 72 20 22 3f  e form "?" or "?
d0d0: 4e 4e 4e 22 20 68 61 76 65 20 6e 6f 20 6e 61 6d  NNN" have no nam
d0e0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
d0f0: 73 74 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  st bound paramet
d100: 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
d110: 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
d120: 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65 20  ** If the value 
d130: 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  n is out of rang
d140: 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68  e or if the n-th
d150: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 61   parameter is na
d160: 6d 65 6c 65 73 73 2c 0a 2a 2a 20 74 68 65 6e 20  meless,.** then 
d170: 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
d180: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  .  The returned 
d190: 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
d1a0: 20 69 6e 20 74 68 65 0a 2a 2a 20 55 54 46 2d 38   in the.** UTF-8
d1b0: 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
d1c0: 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
d1d0: 6d 65 74 65 72 20 77 61 73 20 6f 72 69 67 69 6e  meter was origin
d1e0: 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 0a 2a  ally specified.*
d1f0: 2a 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  * as UTF-16 in [
d200: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
d210: 36 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  6()] or [sqlite3
d220: 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
d230: 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
d240: 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
d250: 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
d260: 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
d270: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
d280: 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
d290: 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
d2a0: 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20  iven Name.**.** 
d2b0: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
d2c0: 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
d2d0: 66 20 61 20 68 6f 73 74 20 70 61 72 61 6d 65 74  f a host paramet
d2e0: 65 72 20 77 69 74 68 20 74 68 65 20 67 69 76 65  er with the give
d2f0: 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 6e  n name..** The n
d300: 61 6d 65 20 6d 75 73 74 20 6d 61 74 63 68 20 65  ame must match e
d310: 78 61 63 74 6c 79 2e 20 20 49 66 20 6e 6f 20 70  xactly.  If no p
d320: 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 74 68  arameter with th
d330: 65 20 67 69 76 65 6e 20 6e 61 6d 65 20 69 73 20  e given name is 
d340: 0a 2a 2a 20 66 6f 75 6e 64 2c 20 72 65 74 75 72  .** found, retur
d350: 6e 20 30 2e 20 20 50 61 72 61 6d 65 74 65 72 20  n 0.  Parameter 
d360: 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 55 54  names must be UT
d370: 46 38 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  F8..*/.int sqlit
d380: 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
d390: 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
d3a0: 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
d3b0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
d3c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
d3d0: 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
d3e0: 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
d3f0: 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 43 6f 6e  tement.**.** Con
d400: 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
d410: 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
d420: 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
d430: 5d 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72 65  ] does not.** re
d440: 73 65 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  set the [sqlite3
d450: 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
d460: 64 69 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20  dings] on a .** 
d470: 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
d480: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
d490: 6e 74 5d 2e 20 20 55 73 65 20 74 68 69 73 20 72  nt].  Use this r
d4a0: 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73  outine to.** res
d4b0: 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
d4c0: 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
d4d0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
d4e0: 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
d4f0: 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
d500: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
d510: 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
d520: 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
d530: 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68  .**.** Return th
d540: 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
d550: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
d560: 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
d570: 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  y the .** [sqlit
d580: 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c  e3_stmt | compil
d590: 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
d5a0: 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ]. This routine 
d5b0: 72 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69 66 20  returns 0.** if 
d5c0: 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 20  pStmt is an SQL 
d5d0: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
d5e0: 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
d5f0: 61 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65 78 61  ata (for .** exa
d600: 6d 70 6c 65 20 61 6e 20 55 50 44 41 54 45 29 2e  mple an UPDATE).
d610: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
d620: 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
d630: 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
d640: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
d650: 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
d660: 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
d670: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
d680: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
d690: 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
d6a0: 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
d6b0: 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
d6c0: 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
d6d0: 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
d6e0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  .  The sqlite3_c
d6f0: 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
d700: 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
d710: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
d720: 20 55 54 46 38 20 73 74 72 69 6e 67 20 61 6e 64   UTF8 string and
d730: 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
d740: 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 72 65 74 75  name16().** retu
d750: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
d760: 20 61 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e   a UTF16 string.
d770: 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
d780: 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
d790: 5b 73 71 6c 69 74 65 5f 73 74 6d 74 20 7c 20 70  [sqlite_stmt | p
d7a0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
d7b0: 74 5d 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  t] that implemen
d7c0: 74 73 20 74 68 65 20 53 45 4c 45 43 54 20 73 74  ts the SELECT st
d7d0: 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  atement..** The 
d7e0: 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
d7f0: 20 69 73 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e   is the column n
d800: 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74  umber.  The left
d810: 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 0a  -most column is.
d820: 2a 2a 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  ** number 0..**.
d830: 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  ** The returned 
d840: 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
d850: 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
d860: 74 68 65 72 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ther the .** [sq
d870: 6c 69 74 65 5f 73 74 6d 74 20 7c 20 70 72 65 70  lite_stmt | prep
d880: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
d890: 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
d8a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
d8b0: 65 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c  e()].** or until
d8c0: 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 73   the next call s
d8d0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
d8e0: 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
d8f0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a  column_name16().
d900: 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  ** on the same c
d910: 6f 6c 75 6d 6e 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  olumn..*/.const 
d920: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
d930: 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
d940: 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
d950: 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
d960: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
d970: 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
d980: 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
d990: 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
d9a0: 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
d9b0: 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
d9c0: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
d9d0: 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
d9e0: 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68   to determine wh
d9f0: 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61  at column of wha
da00: 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68  t.** table in wh
da10: 69 63 68 20 64 61 74 61 62 61 73 65 20 61 20 72  ich database a r
da20: 65 73 75 6c 74 20 6f 66 20 61 20 53 45 4c 45 43  esult of a SELEC
da30: 54 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65  T statement come
da40: 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e  s from..** The n
da50: 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
da60: 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
da70: 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
da80: 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
da90: 68 65 72 20 61 20 55 54 46 38 20 6f 72 20 55 54  her a UTF8 or UT
daa0: 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65  F16 string.  The
dab0: 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
dac0: 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 0a   is valid until.
dad0: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
dae0: 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20  stmt | prepared 
daf0: 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
db00: 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a  stroyed using.**
db10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
db20: 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
db30: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
db40: 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
db50: 0a 2a 2a 20 61 67 61 69 6e 20 61 62 6f 75 74 20  .** again about 
db60: 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
db70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
db80: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
db90: 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73   following calls
dba0: 20 69 73 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74   is a .** [sqlit
dbb0: 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c  e3_stmt | compil
dbc0: 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
dbd0: 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  ]..** These func
dbe0: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
dbf0: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
dc00: 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
dc10: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 74 68  turned by .** th
dc20: 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
dc30: 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
dc40: 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
dc50: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ment..**.** If t
dc60: 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
dc70: 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
dc80: 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
dc90: 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72 20 73  pression.** or s
dca0: 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
dcb0: 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
dcc0: 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
dcd0: 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  hese functions.*
dce0: 2a 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 20 4f  * return NULL. O
dcf0: 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
dd00: 65 74 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e 61  eturn the .** na
dd10: 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
dd20: 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
dd30: 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68  le and column th
dd40: 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a  at query result.
dd50: 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  ** column was ex
dd60: 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
dd70: 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20  .** As with all 
dd80: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
dd90: 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78  s, those postfix
dda0: 65 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  ed with "16" ret
ddb0: 75 72 6e 20 55 54 46 2d 31 36 0a 2a 2a 20 65 6e  urn UTF-16.** en
ddc0: 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74  coded strings, t
ddd0: 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
dde0: 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
ddf0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49  .**.** These API
de00: 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
de10: 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
de20: 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
de30: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
de40: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
de50: 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70  MN_METADATA prep
de60: 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20  rocessor symbol 
de70: 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
de80: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
de90: 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
dea0: 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
deb0: 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
dec0: 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
ded0: 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
dee0: 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
def0: 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
df00: 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
df10: 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
df20: 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
df30: 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
df40: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
df50: 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
df60: 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
df70: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
df80: 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
df90: 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
dfa0: 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
dfb0: 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
dfc0: 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
dfd0: 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
dfe0: 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
dff0: 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
e000: 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
e010: 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
e020: 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
e030: 65 74 65 72 20 69 73 20 61 20 5b 73 71 6c 69 74  eter is a [sqlit
e040: 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c  e3_stmt | compil
e050: 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
e060: 5d 2e 20 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  ]. .** If this s
e070: 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 53 45  tatement is a SE
e080: 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 61  LECT statement a
e090: 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
e0a0: 6e 20 6f 66 20 74 68 65 20 0a 2a 2a 20 72 65 74  n of the .** ret
e0b0: 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
e0c0: 20 20 6f 66 20 74 68 61 74 20 53 45 4c 45 43 54    of that SELECT
e0d0: 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
e0e0: 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
e0f0: 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
e100: 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
e110: 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
e120: 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
e130: 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
e140: 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   If the Nth colu
e150: 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
e160: 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
e170: 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
e180: 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
e190: 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
e1a0: 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65  urned..** The re
e1b0: 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
e1c0: 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
e1d0: 63 6f 64 65 64 2e 20 46 6f 72 20 65 78 61 6d 70  coded. For examp
e1e0: 6c 65 2c 20 69 6e 0a 2a 2a 20 74 68 65 20 64 61  le, in.** the da
e1f0: 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
e200: 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
e210: 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
e220: 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20 74 68 65 20  ;.**.** And the 
e230: 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
e240: 65 6e 74 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a  ent compiled:.**
e250: 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
e260: 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
e270: 2a 0a 2a 2a 20 54 68 65 6e 20 74 68 69 73 20 72  *.** Then this r
e280: 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
e290: 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
e2a0: 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
e2b0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c   second.** resul
e2c0: 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  t column (i==1),
e2d0: 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
e2e0: 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
e2f0: 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  t result column.
e300: 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a  ** (i==0)..**.**
e310: 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
e320: 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
e330: 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62  ping.  So just b
e340: 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
e350: 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
e360: 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
e370: 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
e380: 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
e390: 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
e3a0: 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
e3b0: 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
e3c0: 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
e3d0: 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
e3e0: 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
e3f0: 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
e400: 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54  c not static.  T
e410: 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
e420: 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
e430: 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
e440: 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
e450: 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
e460: 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
e470: 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  s..*/.const char
e480: 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
e490: 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
e4a0: 33 5f 73 74 6d 74 20 2a 2c 20 69 6e 74 20 69 29  3_stmt *, int i)
e4b0: 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
e4c0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
e4d0: 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
e4e0: 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20  stmt*,int);../* 
e4f0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45  .** CAPI3REF:  E
e500: 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53  valuate An SQL S
e510: 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41  tatement.**.** A
e520: 66 74 65 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  fter an [sqlite3
e530: 5f 73 74 6d 74 20 7c 20 53 51 4c 20 73 74 61 74  _stmt | SQL stat
e540: 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
e550: 70 72 65 70 61 72 65 64 20 77 69 74 68 20 61 20  prepared with a 
e560: 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65  call.** to eithe
e570: 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
e580: 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
e590: 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
e5a0: 32 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f  2()] or to one o
e5b0: 66 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20  f.** the legacy 
e5c0: 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
e5d0: 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
e5e0: 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
e5f0: 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  re16()],.** then
e600: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d   this function m
e610: 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
e620: 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
e630: 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
e640: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  .** statement..*
e650: 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
e660: 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
e670: 20 6f 66 20 74 68 69 73 20 73 71 6c 69 74 65 33   of this sqlite3
e680: 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
e690: 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
e6a0: 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
e6b0: 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
e6c0: 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
e6d0: 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
e6e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
e6f0: 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
e700: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
e710: 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
e720: 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
e730: 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
e740: 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
e750: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
e760: 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
e770: 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
e780: 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
e790: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
e7a0: 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
e7b0: 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
e7c0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
e7d0: 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
e7e0: 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
e7f0: 2a 2a 20 49 6e 20 74 68 65 20 6c 61 67 61 63 79  ** In the lagacy
e800: 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
e810: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c  return value wil
e820: 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c  l be either [SQL
e830: 49 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b  ITE_BUSY], .** [
e840: 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
e850: 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
e860: 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
e870: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
e880: 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 22  ** With the "v2"
e890: 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20   interface, any 
e8a0: 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 53 51  of the other [SQ
e8b0: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
e8c0: 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51   code].** or [SQ
e8d0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
e8e0: 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  | extended resul
e8f0: 74 20 63 6f 64 65 5d 20 6d 69 67 68 74 20 62 65  t code] might be
e900: 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
e910: 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  well..**.** [SQL
e920: 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20  ITE_BUSY] means 
e930: 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
e940: 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61  e engine was una
e950: 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74  ble to acquire t
e960: 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c  he.** database l
e970: 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f  ocks it needs to
e980: 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66   do its job.  If
e990: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
e9a0: 73 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72  s a COMMIT.** or
e9b0: 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
e9c0: 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
e9d0: 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
e9e0: 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
e9f0: 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
ea00: 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
ea10: 6e 74 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d  nt is not a COMM
ea20: 49 54 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  IT and occurs wi
ea30: 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63  thin a.** explic
ea40: 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
ea50: 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
ea60: 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
ea70: 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
ea80: 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
ea90: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
eaa0: 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
eab0: 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
eac0: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
ead0: 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
eae0: 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
eaf0: 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
eb00: 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
eb10: 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
eb20: 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
eb30: 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
eb40: 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
eb50: 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
eb60: 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
eb70: 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
eb80: 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
eb90: 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
eba0: 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
ebb0: 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
ebc0: 79 20 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a  y data, then .**
ebd0: 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73   [SQLITE_ROW] is
ebe0: 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
ebf0: 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
ec00: 20 64 61 74 61 20 69 73 20 72 65 61 64 79 0a 2a   data is ready.*
ec10: 2a 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  * for processing
ec20: 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   by the caller. 
ec30: 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
ec40: 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
ec50: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
ec60: 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f  _column_int | co
ec70: 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
ec80: 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
ec90: 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
eca0: 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
ecb0: 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
ecc0: 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a  ow of data..** .
ecd0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
ece0: 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
ecf0: 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
ed00: 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
ed10: 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
ed20: 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
ed30: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
ed40: 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
ed50: 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
ed60: 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
ed70: 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
ed80: 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
ed90: 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
eda0: 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  g()]..** With th
edb0: 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
edc0: 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
edd0: 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
ede0: 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c  example:.** [SQL
edf0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
ee00: 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
ee10: 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
ee20: 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
ee30: 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
ee40: 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
ee50: 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
ee60: 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   on the.** [sqli
ee70: 74 65 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72  te_stmt | prepar
ee80: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
ee90: 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
eea0: 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
eeb0: 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
eec0: 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
eed0: 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
eee0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
eef0: 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
ef00: 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
ef10: 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
ef20: 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
ef30: 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
ef40: 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
ef50: 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 73 71 6c 69  alled on a [sqli
ef60: 74 65 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72  te_stmt | prepar
ef70: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
ef80: 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
ef90: 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
efa0: 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
efb0: 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
efc0: 74 68 61 74 20 68 61 64 20 0a 2a 2a 20 70 72 65  that had .** pre
efd0: 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
efe0: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
eff0: 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
f000: 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
f010: 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
f020: 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
f030: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
f040: 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
f050: 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
f060: 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
f070: 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
f080: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  me..**.** <b>Goo
f090: 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
f0a0: 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68  rt:</b>.** In th
f0b0: 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
f0c0: 63 65 2c 20 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ce, .** the sqli
f0d0: 74 65 33 5f 73 74 65 70 28 29 20 41 50 49 20 61  te3_step() API a
f0e0: 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
f0f0: 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
f100: 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  de,.** [SQLITE_E
f110: 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
f120: 20 61 6e 79 20 65 72 72 6f 72 20 6f 74 68 65 72   any error other
f130: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
f140: 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49  SY].** and [SQLI
f150: 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
f160: 20 6d 75 73 74 20 63 61 6c 6c 20 5b 73 71 6c 69   must call [sqli
f170: 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
f180: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
f190: 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
f1a0: 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
f1b0: 74 68 65 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  the specific.** 
f1c0: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
f1d0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 74 68  result codes] th
f1e0: 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
f1f0: 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
f200: 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
f210: 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
f220: 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
f230: 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
f240: 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
f250: 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
f260: 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
f270: 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
f280: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
f290: 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
f2a0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
f2b0: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
f2c0: 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
f2d0: 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
f2e0: 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
f2f0: 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
f300: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
f310: 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 0a  6()], then the .
f320: 2a 2a 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  ** more specific
f330: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c   [SQLITE_ERROR |
f340: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61   result codes] a
f350: 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
f360: 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
f370: 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
f380: 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
f390: 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
f3a0: 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74  ommended..*/.int
f3b0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
f3c0: 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
f3d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 0a 2a  *.** CAPI3REF:.*
f3e0: 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
f3f0: 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73  number of values
f400: 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
f410: 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
f420: 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  t set..**.** Aft
f430: 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  er a call to [sq
f440: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 68  lite3_step()] th
f450: 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  at returns [SQLI
f460: 54 45 5f 52 4f 57 5d 2c 20 74 68 69 73 20 72 6f  TE_ROW], this ro
f470: 75 74 69 6e 65 0a 2a 2a 20 77 69 6c 6c 20 72 65  utine.** will re
f480: 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61  turn the same va
f490: 6c 75 65 20 61 73 20 74 68 65 20 5b 73 71 6c 69  lue as the [sqli
f4a0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
f4b0: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ()] function..**
f4c0: 20 41 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   After [sqlite3_
f4d0: 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
f4e0: 72 6e 65 64 20 61 6e 20 5b 53 51 4c 49 54 45 5f  rned an [SQLITE_
f4f0: 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  DONE], [SQLITE_B
f500: 55 53 59 5d 2c 20 6f 72 0a 2a 2a 20 61 20 5b 53  USY], or.** a [S
f510: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72  QLITE_ERROR | er
f520: 72 6f 72 20 63 6f 64 65 5d 2c 20 6f 72 20 62 65  ror code], or be
f530: 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  fore [sqlite3_st
f540: 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 0a  ep()] has been .
f550: 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  ** called on the
f560: 20 5b 73 71 6c 69 74 65 5f 73 74 6d 74 20 7c 20   [sqlite_stmt | 
f570: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
f580: 6e 74 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  nt] for the firs
f590: 74 20 74 69 6d 65 2c 0a 2a 2a 20 74 68 69 73 20  t time,.** this 
f5a0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
f5b0: 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  zero..*/.int sql
f5c0: 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
f5d0: 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
f5e0: 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
f5f0: 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
f600: 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 0a  al Datatypes.**.
f610: 2a 2a 20 45 76 65 72 79 20 76 61 6c 75 65 20 69  ** Every value i
f620: 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
f630: 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
f640: 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
f650: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
f660: 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
f670: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
f680: 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
f690: 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
f6a0: 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
f6b0: 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
f6c0: 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
f6d0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  /ul>.**.** These
f6e0: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
f6f0: 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
f700: 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
f710: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
f720: 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
f730: 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
f740: 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
f750: 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
f760: 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
f770: 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
f780: 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
f790: 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
f7a0: 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
f7b0: 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
f7c0: 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
f7d0: 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
f7e0: 58 54 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  XT not.** SQLITE
f7f0: 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
f800: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
f810: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
f820: 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
f830: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
f840: 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
f850: 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
f860: 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
f870: 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
f880: 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
f890: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
f8a0: 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
f8b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
f8c0: 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
f8d0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
f8e0: 75 6c 74 73 20 56 61 6c 75 65 73 20 46 72 6f 6d  ults Values From
f8f0: 20 41 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54   A Query.**.** T
f900: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
f910: 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
f920: 20 61 62 6f 75 74 20 74 68 65 20 69 6e 66 6f 72   about the infor
f930: 6d 61 74 69 6f 6e 0a 2a 2a 20 69 6e 20 61 20 73  mation.** in a s
f940: 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
f950: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73 75  the current resu
f960: 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
f970: 79 2e 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20  y.  In every.** 
f980: 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
f990: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
f9a0: 6e 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  nter to the .** 
f9b0: 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
f9c0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  SQL statement] t
f9d0: 68 61 74 20 69 73 20 62 65 69 6e 67 0a 2a 2a 20  hat is being.** 
f9e0: 65 76 61 6c 75 61 74 65 20 28 74 68 65 20 5b 73  evaluate (the [s
f9f0: 71 6c 69 74 65 5f 73 74 6d 74 2a 5d 20 74 68 61  qlite_stmt*] tha
fa00: 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
fa10: 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
fa20: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
fa30: 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
fa40: 69 61 6e 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68  iants) and.** th
fa50: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
fa60: 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
fa70: 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
fa80: 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
fa90: 6f 6e 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  on .** should be
faa0: 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
fab0: 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
fac0: 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
fad0: 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65   0..**.** If the
fae0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
faf0: 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
fb00: 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
fb10: 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
fb20: 2a 2a 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e  ** the column in
fb30: 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
fb40: 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
fb50: 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
fb60: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
fb70: 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
fb80: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a  utine returns .*
fb90: 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
fba0: 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
fbb0: 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
fbc0: 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
fbd0: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
fbe0: 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72  lumn.  The retur
fbf0: 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
fc00: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
fc10: 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
fc20: 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
fc30: 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
fc40: 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
fc50: 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
fc60: 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
fc70: 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
fc80: 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
fc90: 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
fca0: 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
fcb0: 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
fcc0: 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
fcd0: 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
fce0: 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
fcf0: 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
fd00: 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
fd10: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
fd20: 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
fd30: 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
fd40: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
fd50: 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
fd60: 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
fd70: 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
fd80: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
fd90: 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
fda0: 0a 2a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  .*** The sqlite3
fdb0: 5f 63 6f 6c 75 6d 6e 5f 6e 6d 0a 2a 2a 0a 2a 2a  _column_nm.**.**
fdc0: 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
fdd0: 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
fde0: 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
fdf0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
fe00: 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75  _bytes() .** rou
fe10: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
fe20: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
fe30: 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
fe40: 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74   string..** If t
fe50: 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
fe60: 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
fe70: 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
fe80: 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
fe90: 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
fea0: 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
feb0: 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
fec0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
fed0: 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
fee0: 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
fef0: 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
ff00: 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
ff10: 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
ff20: 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
ff30: 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
ff40: 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
ff50: 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
ff60: 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
ff70: 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
ff80: 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76  string..** The v
ff90: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f  alue returned do
ffa0: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  es not include t
ffb0: 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
ffc0: 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  or at the end.**
ffd0: 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
ffe0: 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68   For clarity: th
fff0: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
10000 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
10010 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
10020 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
10030 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
10040 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  acters..**.** Th
10050 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
10060 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69  _bytes16() routi
10070 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
10080 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
10090 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c  bytes().** but l
100a0 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74  eaves the result
100b0 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 73 74 65   in UTF-16 inste
100c0 61 64 20 6f 66 20 55 54 46 2d 38 2e 20 20 0a 2a  ad of UTF-8.  .*
100d0 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * The zero termi
100e0 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63  nator is not inc
100f0 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f  luded in this co
10100 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  unt..**.** These
10110 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
10120 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
10130 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
10140 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a  ropriate.  For.*
10150 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
10160 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
10170 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
10180 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
10190 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
101a0 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
101b0 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
101c0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
101d0 20 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 69   do the conversi
101e0 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  on.** automatica
101f0 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77  lly.  The follow
10200 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
10210 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
10220 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 70  s that.** are ap
10230 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
10240 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
10250 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
10260 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
10270 72 6e 61 6c 20 3c 74 68 3e 20 52 65 71 75 65 73  rnal <th> Reques
10280 74 65 64 20 3c 74 68 3e 20 0a 2a 2a 20 3c 74 72  ted <th> .** <tr
10290 3e 3c 74 68 3e 20 20 54 79 70 65 20 20 20 20 3c  ><th>  Type    <
102a0 74 68 3e 20 20 20 20 54 79 70 65 20 20 20 3c 74  th>    Type   <t
102b0 68 3e 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  h> Conversion.**
102c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
102d0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
102e0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
102f0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
10300 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
10310 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
10320 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
10330 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
10340 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
10350 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
10360 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
10370 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
10380 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
10390 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
103a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
103b0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
103c0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
103d0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
103e0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
103f0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
10400 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
10410 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
10420 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
10430 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
10440 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
10450 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
10460 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 66 6f 72  <td> Same as for
10470 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
10480 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
10490 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
104a0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
104b0 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
104c0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
104d0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
104e0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
104f0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
10500 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
10510 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
10520 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
10530 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
10540 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
10550 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
10560 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
10570 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
10580 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
10590 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
105a0 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
105b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
105c0 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
105d0 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
105e0 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
105f0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
10600 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
10610 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
10620 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
10630 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
10640 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
10650 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
10660 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
10670 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
10680 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
10690 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
106a0 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
106b0 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
106c0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
106d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
106e0 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
106f0 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
10700 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
10710 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
10720 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
10730 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
10740 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
10750 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
10760 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
10770 0a 2a 2a 20 6f 6e 20 65 71 75 61 76 61 6c 65 6e  .** on equavalen
10780 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
10790 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
107a0 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
107b0 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
107c0 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
107d0 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
107e0 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
107f0 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
10800 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
10810 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
10820 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
10830 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
10840 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
10850 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
10860 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
10870 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
10880 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
10890 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
108a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
108b0 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
108c0 64 61 74 65 64 2e 20 0a 2a 2a 20 54 79 70 65 20  dated. .** Type 
108d0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
108e0 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
108f0 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
10900 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
10910 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
10920 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c  ** <ul>.** <li><
10930 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20  p>  The initial 
10940 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
10950 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
10960 6c 75 6d 6e 5f 74 65 78 74 28 29 20 0a 2a 2a 20  lumn_text() .** 
10970 20 20 20 20 20 20 20 20 20 6f 72 20 73 71 6c 69           or sqli
10980 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
10990 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
109a0 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
109b0 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
109c0 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
109d0 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
109e0 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a  ng.</p></li>.**.
109f0 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20  ** <li><p>  The 
10a00 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
10a10 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
10a20 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
10a30 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
10a40 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
10a50 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
10a60 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
10a70 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
10a80 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
10a90 20 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31          to UTF-1
10aa0 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  6.</p></li>.**.*
10ab0 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69  * <li><p>  The i
10ac0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
10ad0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
10ae0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
10af0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
10b00 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
10b10 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
10b20 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
10b30 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
10b40 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
10b50 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 70      to UTF-8.</p
10b60 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ></li>.** </ul>.
10b70 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e  **.** Conversion
10b80 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
10b90 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
10ba0 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
10bb0 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
10bc0 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
10bd0 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
10be0 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
10bf0 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
10c00 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
10c10 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
10c20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74  pointer points t
10c30 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  o will have been
10c40 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
10c50 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
10c60 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
10c70 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
10c80 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
10c90 62 75 74 20 73 6f 6d 65 74 69 6d 65 20 69 74 20  but sometime it 
10ca0 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  is.** not possib
10cb0 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
10cc0 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
10cd0 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
10ce0 61 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  ated.  .**.** Th
10cf0 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
10d00 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
10d10 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
10d20 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
10d30 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
10d40 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
10d50 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e  ays:.**.**  <ul>
10d60 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
10d70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
10d80 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
10d90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
10da0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
10db0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
10dc0 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
10dd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
10de0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
10df0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
10e00 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
10e10 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
10e20 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
10e30 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e  )</li>.**  </ul>
10e40 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
10e50 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
10e60 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
10e70 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 73 71  olumn_text(), sq
10e80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
10e90 62 28 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  b(),.** or sqlit
10ea0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
10eb0 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
10ec0 65 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  e the result int
10ed0 6f 20 74 68 65 20 64 65 73 69 72 65 64 0a 2a 2a  o the desired.**
10ee0 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
10ef0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
10f00 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 20 73  umn_bytes() or s
10f10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
10f20 74 65 73 31 36 28 29 20 74 6f 0a 2a 2a 20 66 69  tes16() to.** fi
10f30 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
10f40 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
10f50 6f 74 20 6d 69 78 20 63 61 6c 6c 20 74 6f 20 73  ot mix call to s
10f60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
10f70 78 74 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  xt() or.** sqlit
10f80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
10f90 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
10fa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
10fb0 74 65 73 31 36 28 29 2e 20 20 41 6e 64 20 64 6f  tes16().  And do
10fc0 20 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c   not.** mix call
10fd0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
10fe0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 77 69 74  umn_text16() wit
10ff0 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
11000 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
11010 29 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )..*/.const void
11020 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
11030 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
11040 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
11050 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
11060 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
11070 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
11080 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
11090 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
110a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
110b0 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
110c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
110d0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
110e0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
110f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
11100 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
11110 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
11120 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
11130 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
11140 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
11150 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
11160 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
11170 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
11180 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
11190 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
111a0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
111b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
111c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
111d0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
111e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
111f0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
11200 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
11210 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
11220 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
11230 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
11240 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
11250 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
11260 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
11270 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
11280 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
11290 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
112a0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
112b0 74 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a 20  to delete a .** 
112c0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
112d0 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
112e0 74 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68 65 20  tement]. If the 
112f0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a  statement was.**
11300 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73   executed succes
11310 73 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20 65  sfully, or not e
11320 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20  xecuted at all, 
11330 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  then SQLITE_OK i
11340 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49  s returned..** I
11350 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  f execution of t
11360 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69  he statement fai
11370 6c 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a 2a 20  led then an .** 
11380 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
11390 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b  error code] or [
113a0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
113b0 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72 72  D | extended err
113c0 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72  or code].** is r
113d0 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20  eturned. .**.** 
113e0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
113f0 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
11400 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74  y point during t
11410 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
11420 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
11430 73 74 6d 74 20 7c 20 76 69 72 74 75 61 6c 20 6d  stmt | virtual m
11440 61 63 68 69 6e 65 5d 2e 20 20 49 66 20 74 68 65  achine].  If the
11450 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
11460 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d   has not .** com
11470 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
11480 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   when this routi
11490 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  ne is called, th
114a0 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e  at is like.** en
114b0 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72  countering an er
114c0 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65 72 72  ror or an interr
114d0 75 70 74 2e 20 20 28 53 65 65 20 5b 73 71 6c 69  upt.  (See [sqli
114e0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
114f0 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74  .) .** Incomplet
11500 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65  e updates may be
11510 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64   rolled back and
11520 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61   transactions ca
11530 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a 20 64 65  ncelled,  .** de
11540 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
11550 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e  ircumstances, an
11560 64 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  d the .** [SQLIT
11570 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74  E_ERROR | result
11580 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20   code] returned 
11590 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f  will be [SQLITE_
115a0 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ABORT]..*/.int s
115b0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
115c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
115d0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
115e0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
115f0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
11600 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
11610 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
11620 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
11630 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
11640 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 73 74 6d   .** [sqlite_stm
11650 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c  t | compiled SQL
11660 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
11670 63 74 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69  ct..** back to i
11680 74 27 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  t's initial stat
11690 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
116a0 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41  e-executed..** A
116b0 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
116c0 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
116d0 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
116e0 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
116f0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
11700 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
11710 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
11720 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
11730 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
11740 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
11750 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
11760 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
11770 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
11780 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
11790 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
117a0 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
117b0 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
117c0 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  L Functions.**.*
117d0 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
117e0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  two functions ar
117f0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
11800 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
11810 67 67 72 65 67 61 74 65 73 0a 2a 2a 20 6f 72 20  ggregates.** or 
11820 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
11830 62 65 68 61 76 69 6f 72 20 6f 66 20 65 78 69 73  behavior of exis
11840 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
11850 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
11860 2e 20 20 54 68 65 0a 2a 2a 20 64 69 66 66 65 72  .  The.** differ
11870 65 6e 63 65 20 6f 6e 6c 79 20 62 65 74 77 65 65  ence only betwee
11880 6e 20 74 68 65 20 74 77 6f 20 69 73 20 74 68 61  n the two is tha
11890 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  t the second par
118a0 61 6d 65 74 65 72 2c 20 74 68 65 0a 2a 2a 20 6e  ameter, the.** n
118b0 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c  ame of the (scal
118c0 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  ar) function or 
118d0 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e  aggregate, is en
118e0 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66  coded in UTF-8 f
118f0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  or.** sqlite3_cr
11900 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
11910 61 6e 64 20 55 54 46 2d 31 36 20 66 6f 72 20 73  and UTF-16 for s
11920 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
11930 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a  nction16()..**.*
11940 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
11950 6d 65 6e 74 20 69 73 20 74 68 65 20 5b 73 71 6c  ment is the [sql
11960 69 74 65 33 20 7c 20 64 61 74 61 62 61 73 65 20  ite3 | database 
11970 68 61 6e 64 6c 65 5d 20 74 68 61 74 20 68 6f 6c  handle] that hol
11980 64 73 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ds the.** SQL fu
11990 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
119a0 61 74 65 20 69 73 20 74 6f 20 62 65 20 61 64 64  ate is to be add
119b0 65 64 20 6f 72 20 72 65 64 65 66 69 6e 65 64 2e  ed or redefined.
119c0 20 49 66 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   If a single.** 
119d0 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72  program uses mor
119e0 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
119f0 61 73 65 20 68 61 6e 64 6c 65 20 69 6e 74 65 72  ase handle inter
11a00 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 0a  nally, then SQL.
11a10 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  ** functions or 
11a20 61 67 67 72 65 67 61 74 65 73 20 6d 75 73 74 20  aggregates must 
11a30 62 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64  be added individ
11a40 75 61 6c 6c 79 20 74 6f 20 65 61 63 68 20 64 61  ually to each da
11a50 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65  tabase.** handle
11a60 20 77 69 74 68 20 77 68 69 63 68 20 74 68 65 79   with which they
11a70 20 77 69 6c 6c 20 62 65 20 75 73 65 64 2e 0a 2a   will be used..*
11a80 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
11a90 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
11aa0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
11ab0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
11ac0 63 72 65 61 74 65 64 0a 2a 2a 20 6f 72 20 72 65  created.** or re
11ad0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  defined..** The 
11ae0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
11af0 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
11b00 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c   255 bytes, excl
11b10 75 73 69 76 65 20 6f 66 20 74 68 65 20 0a 2a 2a  usive of the .**
11b20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
11b30 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
11b40 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d   name length lim
11b50 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20  it is in bytes, 
11b60 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  not.** character
11b70 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20  s.  Any attempt 
11b80 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
11b90 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
11ba0 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
11bb0 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 53 51 4c  result in an SQL
11bc0 49 54 45 5f 45 52 52 4f 52 20 65 72 72 6f 72 2e  ITE_ERROR error.
11bd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  .**.** The third
11be0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
11bf0 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
11c00 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53  ments that the S
11c10 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
11c20 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65  * aggregate take
11c30 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 61 6d  s. If this param
11c40 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
11c50 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
11c60 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
11c70 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
11c80 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
11c90 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
11ca0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
11cb0 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
11cc0 73 70 65 63 69 66 69 65 73 20 77 68 61 74 20 0a  specifies what .
11cd0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
11ce0 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
11cf0 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
11d00 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
11d10 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
11d20 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74  .  Any SQL funct
11d30 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
11d40 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c  on should be abl
11d50 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72  e to work.** wor
11d60 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  k with UTF-8, UT
11d70 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
11d80 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
11d90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
11da0 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
11db0 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
11dc0 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
11dd0 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20 61  nother.  It is a
11de0 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  llowed to.** inv
11df0 6f 6b 65 20 73 71 6c 69 74 65 5f 63 72 65 61 74  oke sqlite_creat
11e00 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20  e_function() or 
11e10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
11e20 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74  unction16() mult
11e30 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69  iple.** times wi
11e40 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  th the same func
11e50 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69  tion but with di
11e60 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f  fferent values o
11e70 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57  f eTextRep..** W
11e80 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
11e90 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
11ea0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
11eb0 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
11ec0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
11ed0 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
11ee0 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
11ef0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
11f00 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
11f10 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f  ** If there is o
11f20 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70  nly a single imp
11f30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63  lementation whic
11f40 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  h does not care 
11f50 77 68 61 74 0a 2a 2a 20 74 65 78 74 20 65 6e 63  what.** text enc
11f60 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  oding is used, t
11f70 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61  hen the fourth a
11f80 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
11f90 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 41 4e 59  e.** [SQLITE_ANY
11fa0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66  ]..**.** The fif
11fb0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
11fc0 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
11fd0 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
11fe0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
11ff0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  the function can
12000 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
12010 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
12020 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 75 73  ng.** [sqlite_us
12030 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a  er_data()]..**.*
12040 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65  * The seventh, e
12050 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20  ighth and ninth 
12060 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
12070 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
12080 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
12090 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
120a0 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
120b0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
120c0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
120d0 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 41 20  or aggregate. A 
120e0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
120f0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
12100 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
12110 66 0a 2a 2a 20 74 68 65 20 78 46 75 6e 63 20 63  f.** the xFunc c
12120 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55  allback only, NU
12130 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75  LL pointers shou
12140 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20  ld be passed as 
12150 74 68 65 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64  the xStep.** and
12160 20 78 46 69 6e 61 6c 20 70 61 72 61 6d 65 74 65   xFinal paramete
12170 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65  rs. An aggregate
12180 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
12190 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
121a0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 78  entation.** of x
121b0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 20  Step and xFinal 
121c0 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20  and NULL should 
121d0 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
121e0 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61  unc. To delete a
121f0 6e 0a 2a 2a 20 65 78 69 73 74 69 6e 67 20 53 51  n.** existing SQ
12200 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
12210 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
12220 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  LL for all three
12230 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
12240 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  lback..**.** It 
12250 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
12260 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
12270 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12280 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
12290 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
122a0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
122b0 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
122c0 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
122d0 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
122e0 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 65 72  or differing per
122f0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
12300 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77  dings.  SQLite w
12310 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
12320 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f  mplementation mo
12330 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
12340 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
12350 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
12360 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
12370 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12380 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
12390 0a 20 20 73 71 6c 69 74 65 33 20 2a 2c 0a 20 20  .  sqlite3 *,.  
123a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
123b0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
123c0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
123d0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a  xtRep,.  void*,.
123e0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
123f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
12400 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
12410 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
12420 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
12430 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
12440 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
12450 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
12460 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
12470 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
12480 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
12490 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  6(.  sqlite3*,. 
124a0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
124b0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
124c0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
124d0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a 2c  extRep,.  void*,
124e0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
124f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
12500 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
12510 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
12520 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
12530 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
12540 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
12550 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
12560 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
12570 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
12580 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
12590 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
125a0 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
125b0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
125c0 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
125d0 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
125e0 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
125f0 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
12600 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
12610 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
12620 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
12630 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
12640 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
12650 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
12660 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
12670 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
12680 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
12690 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
126a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
126b0 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
126c0 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
126d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
126e0 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
126f0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
12700 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
12710 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
12720 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
12730 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12740 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63 74 69   Obsolete Functi
12750 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
12760 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  functions are al
12770 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20  l now obsolete. 
12780 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
12790 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
127a0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
127b0 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
127c0 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f  , we continue to
127d0 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73   support.** thes
127e0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f  e functions.  Ho
127f0 77 65 76 65 72 2c 20 6e 65 77 20 64 65 76 65 6c  wever, new devel
12800 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73 20  opment projects 
12810 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
12820 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
12830 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
12840 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
12850 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
12860 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
12870 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
12880 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
12890 6c 20 79 6f 75 20 77 61 6e 74 20 74 68 65 79 20  l you want they 
128a0 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  do..*/.int sqlit
128b0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
128c0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
128d0 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  xt*);.int sqlite
128e0 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
128f0 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71  3_stmt*);.int sq
12900 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
12910 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
12920 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
12930 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  tmt*);.int sqlit
12940 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
12950 72 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  r(void);.../*.**
12960 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
12970 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
12980 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
12990 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  es.**.** The C-l
129a0 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
129b0 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
129c0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
129d0 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
129e0 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
129f0 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
12a00 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
12a10 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
12a20 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
12a30 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
12a40 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
12a50 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
12a60 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
12a70 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
12a80 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
12a90 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
12aa0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
12ab0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
12ac0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
12ad0 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
12ae0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
12af0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
12b00 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
12b10 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61  s..** The 4th pa
12b20 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
12b30 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
12b40 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
12b50 72 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  rs to.** [sqlite
12b60 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
12b70 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
12b80 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
12b90 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
12ba0 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
12bb0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
12bc0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
12bd0 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
12be0 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
12bf0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
12c00 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
12c10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
12c20 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
12c30 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
12c40 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  ponding .** [sql
12c50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
12c60 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
12c70 6e 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20 65 78  n_* routines] ex
12c80 63 65 70 74 20 74 68 61 74 20 0a 2a 2a 20 74 68  cept that .** th
12c90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
12ca0 65 20 61 20 73 69 6e 67 6c 65 20 5b 73 71 6c 69  e a single [sqli
12cb0 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 6f 69 6e  te3_value*] poin
12cc0 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ter instead.** o
12cd0 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  f an [sqlite3_st
12ce0 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
12cf0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
12d00 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
12d10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
12d20 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
12d30 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
12d40 20 55 54 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a   UTF16 string.**
12d50 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
12d60 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
12d70 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
12d80 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
12d90 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
12da0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
12db0 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
12dc0 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
12dd0 63 74 20 55 54 46 31 36 20 73 74 72 69 6e 67 73  ct UTF16 strings
12de0 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
12df0 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
12e00 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
12e10 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
12e20 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
12e30 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
12e40 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
12e50 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
12e60 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
12e70 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
12e80 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
12e90 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
12ea0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
12eb0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
12ec0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
12ed0 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
12ee0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
12ef0 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
12f00 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
12f10 6e 20 28 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 77  n (in order.** w
12f20 6f 72 64 73 20 69 66 20 74 68 65 20 76 61 6c 75  ords if the valu
12f30 65 20 69 73 20 6f 72 69 67 69 6e 61 6c 20 61 20  e is original a 
12f40 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
12f50 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
12f60 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64  .** then it is d
12f70 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69 73 65 20  one.  Otherwise 
12f80 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
12f90 63 75 72 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b  curs.  The .** [
12fa0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
12fb0 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
12fc0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
12fd0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  eturned..**.** P
12fe0 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
12ff0 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
13000 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
13010 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
13020 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
13030 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
13040 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
13050 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
13060 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
13070 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
13080 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
13090 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
130a0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
130b0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
130c0 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
130d0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
130e0 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 5f 76 61  6()], [sqlite_va
130f0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
13100 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
13110 65 5f 74 65 78 74 31 36 28 29 5d 2e 20 20 0a 2a  e_text16()].  .*
13120 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
13130 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
13140 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
13150 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
13160 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
13170 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
13180 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
13190 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
131a0 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  ue*);.double sql
131b0 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
131c0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
131d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
131e0 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
131f0 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65  _value*);.sqlite
13200 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76  _int64 sqlite3_v
13210 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
13220 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
13230 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
13240 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
13250 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
13260 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
13270 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
13280 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
13290 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
132a0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
132b0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
132c0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
132d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
132e0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
132f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
13300 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
13310 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
13320 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
13330 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
13340 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
13350 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
13360 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
13370 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
13380 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  n Context.**.** 
13390 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
133a0 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 20  on of aggregate 
133b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  SQL functions us
133c0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
133d0 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20  o allocate.** a 
133e0 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 74  structure for st
133f0 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
13400 65 2e 20 20 54 68 65 20 66 69 72 73 74 20 74 69  e.  The first ti
13410 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  me this routine.
13420 2a 2a 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72  ** is called for
13430 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67   a particular ag
13440 67 72 65 67 61 74 65 2c 20 61 20 6e 65 77 20 73  gregate, a new s
13450 74 72 75 63 74 75 72 65 20 6f 66 20 73 69 7a 65  tructure of size
13460 20 6e 42 79 74 65 73 0a 2a 2a 20 69 73 20 61 6c   nBytes.** is al
13470 6c 6f 63 61 74 65 64 2c 20 7a 65 72 6f 65 64 2c  located, zeroed,
13480 20 61 6e 64 20 72 65 74 75 72 6e 65 64 2e 20 20   and returned.  
13490 4f 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  On subsequent ca
134a0 6c 6c 73 20 28 66 6f 72 20 74 68 65 0a 2a 2a 20  lls (for the.** 
134b0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 69  same aggregate i
134c0 6e 73 74 61 6e 63 65 29 20 74 68 65 20 73 61 6d  nstance) the sam
134d0 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
134e0 72 6e 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65  rned.  The imple
134f0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
13500 74 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61  the aggregate ca
13510 6e 20 75 73 65 20 74 68 65 20 72 65 74 75 72 6e  n use the return
13520 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 63  ed buffer to acc
13530 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a  umulate data..**
13540 0a 2a 2a 20 54 68 65 20 62 75 66 66 65 72 20 61  .** The buffer a
13550 6c 6c 6f 63 61 74 65 64 20 69 73 20 66 72 65 65  llocated is free
13560 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
13570 62 79 20 53 51 4c 69 74 65 20 77 68 61 6e 20 74  by SQLite whan t
13580 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
13590 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
135a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
135b0 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
135c0 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  d be a copy of t
135d0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
135e0 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
135f0 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
13600 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
13610 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  t.** parameter t
13620 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  o the callback r
13630 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
13640 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
13650 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
13660 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
13670 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
13680 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
13690 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
136a0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
136b0 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
136c0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
136d0 2a 2a 20 54 68 65 20 70 55 73 65 72 44 61 74 61  ** The pUserData
136e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
136f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
13700 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
13710 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
13720 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
13730 29 5d 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75  )] routines.** u
13740 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  sed to register 
13750 75 73 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 69  user functions i
13760 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 0a 2a  s available to.*
13770 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
13780 74 69 6f 6e 20 6f 66 20 74 68 65 20 66 75 6e 63  tion of the func
13790 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 69 73 20  tion using this 
137a0 63 61 6c 6c 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  call..*/.void *s
137b0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
137c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
137d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
137e0 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
137f0 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
13800 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
13810 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
13820 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
13830 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
13840 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
13850 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77 69 74  te meta-data wit
13860 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
13870 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
13880 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
13890 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
138a0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
138b0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
138c0 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
138d0 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
138e0 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
138f0 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
13900 69 61 74 65 64 20 6d 65 74 61 2d 64 61 74 61 20  iated meta-data 
13910 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
13920 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
13930 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
13940 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
13950 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
13960 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
13970 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
13980 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
13990 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
139a0 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
139b0 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
139c0 2d 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  -data associated
139d0 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
139e0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
139f0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
13a00 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
13a10 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
13a20 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
13a30 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
13a40 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
13a50 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
13a60 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
13a70 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
13a80 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
13a90 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
13aa0 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
13ab0 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
13ac0 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
13ad0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
13ae0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
13af0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
13b00 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
13b10 61 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  a-data.** associ
13b20 61 74 65 64 20 77 69 74 68 20 74 68 65 20 4e 74  ated with the Nt
13b30 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
13b40 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
13b50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  SQL function.** 
13b60 63 61 6c 6c 2c 20 77 68 65 72 65 20 4e 20 69 73  call, where N is
13b70 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
13b80 6d 65 74 65 72 2e 20 49 66 20 6e 6f 20 6d 65 74  meter. If no met
13b90 61 2d 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  a-data has been 
13ba0 73 65 74 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  set for.** that 
13bb0 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 20 4e 55  value, then a NU
13bc0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
13bd0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
13be0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
13bf0 78 64 61 74 61 28 29 20 69 73 20 75 73 65 64 20  xdata() is used 
13c00 74 6f 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  to associate met
13c10 61 2d 64 61 74 61 20 77 69 74 68 20 61 6e 20 53  a-data with an S
13c20 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  QL.** function a
13c30 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 74 68 69  rgument. The thi
13c40 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
13c50 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
13c60 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 74 6f   meta-data.** to
13c70 20 62 65 20 61 73 73 6f 63 69 61 74 65 64 20 77   be associated w
13c80 69 74 68 20 74 68 65 20 4e 74 68 20 75 73 65 72  ith the Nth user
13c90 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
13ca0 6e 74 20 76 61 6c 75 65 2e 20 54 68 65 20 66 6f  nt value. The fo
13cb0 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65  urth.** paramete
13cc0 72 20 73 70 65 63 69 66 69 65 73 20 61 20 64 65  r specifies a de
13cd0 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 77 69  structor that wi
13ce0 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 20  ll be called on 
13cf0 74 68 65 20 6d 65 74 61 2d 0a 2a 2a 20 64 61 74  the meta-.** dat
13d00 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 72 65 6c  a pointer to rel
13d10 65 61 73 65 20 69 74 20 77 68 65 6e 20 69 74 20  ease it when it 
13d20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
13d30 75 69 72 65 64 2e 20 49 66 20 74 68 65 20 0a 2a  uired. If the .*
13d40 2a 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  * destructor is 
13d50 4e 55 4c 4c 2c 20 69 74 20 69 73 20 6e 6f 74 20  NULL, it is not 
13d60 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  invoked..**.** I
13d70 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
13d80 2d 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  -data is preserv
13d90 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
13da0 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
13db0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61   expressions tha
13dc0 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61  t are constant a
13dd0 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  t compile time. 
13de0 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69  This includes li
13df0 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
13e00 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65  and SQL variable
13e10 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
13e20 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
13e30 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
13e40 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
13e50 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
13e60 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
13e70 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 76  *, int, void*, v
13e80 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
13e90 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
13ea0 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
13eb0 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
13ec0 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
13ed0 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  r.**.** These ar
13ee0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
13ef0 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
13f00 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
13f10 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
13f20 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
13f30 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
13f40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
13f50 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20  lob()].  If the 
13f60 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
13f70 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
13f80 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
13f90 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
13fa0 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
13fb0 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
13fc0 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
13fd0 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
13fe0 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
13ff0 65 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51 4c  ed.  The .** SQL
14000 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
14010 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
14020 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
14030 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
14040 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
14050 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
14060 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
14070 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
14080 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
14090 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
140a0 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
140b0 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
140c0 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
140d0 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
140e0 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
140f0 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
14100 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
14110 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
14120 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
14130 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
14140 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
14150 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
14160 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
14170 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
14180 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
14190 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
141a0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
141b0 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
141c0 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
141d0 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
141e0 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  L Function.**.**
141f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
14200 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
14210 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
14220 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
14230 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
14240 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
14250 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
14260 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
14270 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
14280 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
14290 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
142a0 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
142b0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
142c0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
142d0 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
142e0 75 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a 2a  uch like the .**
142f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
14300 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
14310 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 20  nd_*] family of 
14320 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a 2a  functions used.*
14330 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  * to bind values
14340 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
14350 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
14360 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
14370 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  efer to the.** [
14380 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
14390 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
143a0 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  _* documentation
143b0 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  ] for.** additio
143c0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
143d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
143e0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
143f0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
14400 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
14410 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
14420 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
14430 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
14440 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
14450 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 70 61  tion.  The.** pa
14460 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
14470 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
14480 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
14490 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
144a0 20 69 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   is the text of 
144b0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
144c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
144d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69  te3_result_toobi
144e0 67 28 29 20 63 61 75 73 65 20 74 68 65 20 66 75  g() cause the fu
144f0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
14500 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 72 6f  ation.** to thro
14510 77 20 61 6e 64 20 65 72 72 6f 72 20 69 6e 64 69  w and error indi
14520 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
14530 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
14540 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65  to long.** to re
14550 70 72 65 73 65 6e 74 2e 0a 2a 2f 0a 76 6f 69 64  present..*/.void
14560 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
14570 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
14580 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
14590 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
145a0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
145b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
145c0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
145d0 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
145e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
145f0 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
14600 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
14610 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
14620 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
14630 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
14640 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
14650 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
14660 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
14670 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
14680 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
14690 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
146a0 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
146b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
146c0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
146d0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
146e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
146f0 73 71 6c 69 74 65 5f 69 6e 74 36 34 29 3b 0a 76  sqlite_int64);.v
14700 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
14710 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
14720 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
14730 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
14740 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
14750 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
14760 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
14770 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
14780 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
14790 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
147a0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
147b0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
147c0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
147d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
147e0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
147f0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
14800 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
14810 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
14820 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
14830 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
14840 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
14850 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
14860 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
14870 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
14880 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
14890 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
148a0 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  alue*);.void sql
148b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
148c0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
148d0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
148e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
148f0 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
14900 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a  ting Sequences.*
14910 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
14920 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f  ions are used to
14930 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69   add new collati
14940 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20  on sequences to 
14950 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a  the.** [sqlite3*
14960 5d 20 68 61 6e 64 6c 65 20 73 70 65 63 69 66 69  ] handle specifi
14970 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
14980 61 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a  argument. .**.**
14990 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
149a0 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   new collation s
149b0 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69  equence is speci
149c0 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20  fied as a UTF-8 
149d0 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
149e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
149f0 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
14a00 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
14a10 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
14a20 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
14a30 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  g for sqlite3_cr
14a40 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
14a50 28 29 2e 20 20 49 6e 20 61 6c 6c 20 63 61 73 65  ().  In all case
14a60 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73  s.** the name is
14a70 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
14a80 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
14a90 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
14aa0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
14ab0 74 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  t must be one of
14ac0 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b   the constants [
14ad0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
14ae0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
14af0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  ] or [SQLITE_UTF
14b00 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16BE], indicatin
14b10 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d  g that the user-
14b20 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74  supplied.** rout
14b30 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62  ine expects to b
14b40 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72  e passed pointer
14b50 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63  s to strings enc
14b60 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
14b70 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
14b80 6c 65 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 46  le-endian or UTF
14b90 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 72  -16 big-endian r
14ba0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
14bb0 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
14bc0 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65  the user supplie
14bd0 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  d routine must b
14be0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
14bf0 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e  fifth.** argumen
14c00 74 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  t. If it is NULL
14c10 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61  , this is the sa
14c20 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74  me as deleting t
14c30 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
14c40 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61  sequence (so tha
14c50 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20  t SQLite cannot 
14c60 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29  call it anymore)
14c70 2e 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20  . Each time the 
14c80 75 73 65 72 0a 2a 2a 20 73 75 70 70 6c 69 65 64  user.** supplied
14c90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
14ca0 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73  oked, it is pass
14cb0 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ed a copy of the
14cc0 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73   void* passed as
14cd0 0a 2a 2a 20 74 68 65 20 66 6f 75 72 74 68 20 61  .** the fourth a
14ce0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
14cf0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
14d00 69 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ion() or.** sqli
14d10 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
14d20 74 69 6f 6e 31 36 28 29 20 61 73 20 69 74 73 20  tion16() as its 
14d30 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
14d40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  .**.** The remai
14d50 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74  ning arguments t
14d60 6f 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c  o the user-suppl
14d70 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20  ied routine are 
14d80 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20  two strings,.** 
14d90 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64  each represented
14da0 20 62 79 20 61 20 5b 6c 65 6e 67 74 68 2c 20 64   by a [length, d
14db0 61 74 61 5d 20 70 61 69 72 20 61 6e 64 20 65 6e  ata] pair and en
14dc0 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63  coded in the enc
14dd0 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61  oding.** that wa
14de0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
14df0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77  third argument w
14e00 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  hen the collatio
14e10 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a  n sequence was.*
14e20 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 54 68  * registered. Th
14e30 65 20 75 73 65 72 20 72 6f 75 74 69 6e 65 20 73  e user routine s
14e40 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 6e 65 67  hould return neg
14e50 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70  ative, zero or p
14e60 6f 73 69 74 69 76 65 20 69 66 0a 2a 2a 20 74 68  ositive if.** th
14e70 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
14e80 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
14e90 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
14ea0 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
14eb0 64 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e 65  d.** string. i.e
14ec0 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52  . (STRING1 - STR
14ed0 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ING2)..**.** The
14ee0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
14ef0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
14f00 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
14f10 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
14f20 6f 6e 28 29 0a 2a 2a 20 65 78 63 61 70 74 20 74  on().** excapt t
14f30 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20  hat it takes an 
14f40 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77  extra argument w
14f50 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75  hich is a destru
14f60 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ctor for.** the 
14f70 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20  collation.  The 
14f80 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
14f90 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f  lled when the co
14fa0 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  llation is.** de
14fb0 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70  stroyed and is p
14fc0 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20  assed a copy of 
14fd0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
14fe0 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74  eter void* point
14ff0 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  er.** of the sql
15000 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
15010 61 74 69 6f 6e 5f 76 32 28 29 2e 20 20 43 6f 6c  ation_v2().  Col
15020 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74  lations are dest
15030 72 6f 79 65 64 20 77 68 65 6e 0a 2a 2a 20 74 68  royed when.** th
15040 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65  ey are overridde
15050 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73  n by later calls
15060 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   to the collatio
15070 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74  n creation funct
15080 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20  ions.** or when 
15090 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64  the [sqlite3*] d
150a0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69  atabase handle i
150b0 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
150c0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
150d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
150e0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
150f0 74 69 6f 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  tion_v2() interf
15100 61 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e  ace is experimen
15110 74 61 6c 20 61 6e 64 0a 2a 2a 20 73 75 62 6a 65  tal and.** subje
15120 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
15130 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
15140 20 20 54 68 65 20 6f 74 68 65 72 20 63 6f 6c 6c    The other coll
15150 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 0a 2a  ation creation.*
15160 2a 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  * functions are 
15170 73 74 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73  stable..*/.int s
15180 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
15190 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
151a0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
151b0 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
151c0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
151d0 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
151e0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
151f0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
15200 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
15210 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
15220 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
15230 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
15240 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
15250 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
15260 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
15270 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
15280 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
15290 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
152a0 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  void*),.  void(*
152b0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
152c0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
152d0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
152e0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
152f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
15300 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
15310 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
15320 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
15330 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
15340 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
15350 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
15360 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
15370 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61  lation Needed Ca
15380 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 6f  llbacks.**.** To
15390 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
153a0 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
153b0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
153c0 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
153d0 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
153e0 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
153f0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
15400 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
15410 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 64 61 74   with the.** dat
15420 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20  abase handle to 
15430 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76  be called whenev
15440 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
15450 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
15460 63 65 20 69 73 0a 2a 2a 20 72 65 71 75 69 72 65  ce is.** require
15470 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
15480 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
15490 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
154a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
154b0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
154c0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
154d0 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
154e0 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
154f0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
15500 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
15510 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
15520 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   If sqlite3_coll
15530 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
15540 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 6e 61   is used, the na
15550 6d 65 73 0a 2a 2a 20 61 72 65 20 70 61 73 73 65  mes.** are passe
15560 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
15570 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
15580 74 65 20 6f 72 64 65 72 2e 20 41 20 63 61 6c 6c  te order. A call
15590 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75   to either.** fu
155a0 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
155b0 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c  any existing cal
155c0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  lback..**.** Whe
155d0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  n the callback i
155e0 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66  s invoked, the f
155f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61  irst argument pa
15600 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a  ssed is a copy.*
15610 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * of the second 
15620 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
15630 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
15640 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  eded() or.** sql
15650 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
15660 65 65 64 65 64 31 36 28 29 2e 20 54 68 65 20 73  eeded16(). The s
15670 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
15680 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
15690 2a 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 74 68  * handle. The th
156a0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
156b0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  one of [SQLITE_U
156c0 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
156d0 46 31 36 42 45 5d 2c 20 6f 72 0a 2a 2a 20 5b 53  F16BE], or.** [S
156e0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
156f0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d  indicating the m
15700 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f  ost desirable fo
15710 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  rm of the collat
15720 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
15730 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
15740 64 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  d. The fourth pa
15750 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
15760 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
15770 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
15780 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a   sequence..**.**
15790 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
157a0 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
157b0 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
157c0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
157d0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
157e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
157f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
15800 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
15810 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
15820 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
15830 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e  ion_v2()]..*/.in
15840 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
15850 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
15860 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
15870 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
15880 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
15890 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
158a0 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
158b0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
158c0 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
158d0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
158e0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
158f0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
15900 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
15910 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  ).);../*.** Spec
15920 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
15930 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
15940 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
15950 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
15960 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
15970 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
15980 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
15990 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
159a0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
159b0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
159c0 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
159d0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
159e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  /.int sqlite3_ke
159f0 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
15a00 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
15a10 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
15a20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
15a30 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
15a40 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
15a50 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
15a60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65  );../*.** Change
15a70 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f   the key on an o
15a80 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49  pen database.  I
15a90 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  f the current da
15aa0 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a  tabase is not.**
15ab0 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73   encrypted, this
15ac0 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e   routine will en
15ad0 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e  crypt it.  If pN
15ae0 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30  ew==0 or nNew==0
15af0 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  , the.** databas
15b00 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a  e is decrypted..
15b10 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
15b20 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
15b30 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
15b40 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
15b50 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
15b60 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
15b70 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a   sqlite3_rekey(.
15b80 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
15b90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
15ba0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
15bb0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
15bc0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
15bd0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
15be0 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
15bf0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
15c00 52 45 46 3a 20 20 53 75 73 70 65 6e 64 20 45 78  REF:  Suspend Ex
15c10 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68  ecution For A Sh
15c20 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54  ort Time.**.** T
15c30 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
15c40 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
15c50 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
15c60 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 61  d execution.** a
15c70 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
15c80 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65  seconds specifie
15c90 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74  d in its paramet
15ca0 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  er..**.** If the
15cb0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
15cc0 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f  m does not suppo
15cd0 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74  rt sleep request
15ce0 73 20 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69  s with .** milli
15cf0 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f  second time reso
15d00 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  lution, then the
15d10 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f   time will be ro
15d20 75 6e 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20  unded up to .** 
15d30 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
15d40 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
15d50 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
15d60 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
15d70 20 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66   .** requested f
15d80 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e  rom the operatin
15d90 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75  g system is retu
15da0 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rned..*/.int sql
15db0 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
15dc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15dd0 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  :  Name Of The F
15de0 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
15df0 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a  mporary Files.**
15e00 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62  .** If this glob
15e10 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
15e20 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
15e30 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
15e40 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
15e50 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 61 2e   a folder (a.ka.
15e60 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
15e70 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20  n all temporary 
15e80 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  files.** created
15e90 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   by SQLite will 
15ea0 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61  be placed in tha
15eb0 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66  t directory.  If
15ec0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
15ed0 2a 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * is NULL pointe
15ee0 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 64  r, then SQLite d
15ef0 6f 65 73 20 61 20 73 65 61 72 63 68 20 66 6f 72  oes a search for
15f00 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
15f10 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66 69 6c  temporary.** fil
15f20 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  e directory..**.
15f30 2a 2a 20 4f 6e 63 65 20 5b 73 71 6c 69 74 65 33  ** Once [sqlite3
15f40 5f 6f 70 65 6e 28 29 5d 20 68 61 73 20 62 65 65  _open()] has bee
15f50 6e 20 63 61 6c 6c 65 64 2c 20 63 68 61 6e 67 69  n called, changi
15f60 6e 67 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  ng this variable
15f70 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 61 6c 69 64   will.** invalid
15f80 61 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ate the current 
15f90 74 65 6d 70 6f 72 61 72 79 20 64 61 74 61 62 61  temporary databa
15fa0 73 65 2c 20 69 66 20 61 6e 79 2e 20 20 47 65 6e  se, if any.  Gen
15fb0 65 72 61 6c 6c 79 20 73 70 65 61 6b 69 6e 67 2c  erally speaking,
15fc0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 73 61  .** it is not sa
15fd0 66 65 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 69  fe to invoke thi
15fe0 73 20 72 6f 75 74 69 6e 65 20 61 66 74 65 72 20  s routine after 
15ff0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
16000 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 63 61 6c   has.** been cal
16010 6c 65 64 2e 0a 2a 2f 0a 65 78 74 65 72 6e 20 63  led..*/.extern c
16020 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
16030 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
16040 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 54  .** CAPI3REF:  T
16050 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
16060 65 20 44 61 74 61 62 73 65 20 49 73 20 49 6e 20  e Databse Is In 
16070 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
16080 0a 2a 2a 0a 2a 2a 20 54 65 73 74 20 74 6f 20 73  .**.** Test to s
16090 65 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ee whether or no
160a0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  t the database c
160b0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20  onnection is in 
160c0 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 6d 6f  autocommit.** mo
160d0 64 65 2e 20 20 52 65 74 75 72 6e 20 54 52 55 45  de.  Return TRUE
160e0 20 69 66 20 69 74 20 69 73 20 61 6e 64 20 46 41   if it is and FA
160f0 4c 53 45 20 69 66 20 6e 6f 74 2e 20 20 41 75 74  LSE if not.  Aut
16100 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
16110 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  on.** by default
16120 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 69 73  .  Autocommit is
16130 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 42   disabled by a B
16140 45 47 49 4e 20 73 74 61 74 65 6d 65 6e 74 20 61  EGIN statement a
16150 6e 64 20 72 65 65 6e 61 62 6c 65 64 0a 2a 2a 20  nd reenabled.** 
16160 62 79 20 74 68 65 20 6e 65 78 74 20 43 4f 4d 4d  by the next COMM
16170 49 54 20 6f 72 20 52 4f 4c 4c 42 41 43 4b 2e 0a  IT or ROLLBACK..
16180 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
16190 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
161a0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
161b0 43 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20  CAPI3REF:  Find 
161c0 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
161d0 64 6c 65 20 41 73 73 6f 63 69 61 74 65 64 20 57  dle Associated W
161e0 69 74 68 20 41 20 50 72 65 70 61 72 65 64 20 53  ith A Prepared S
161f0 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 52  tatement.**.** R
16200 65 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74  eturn the [sqlit
16210 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61  e3*] database ha
16220 6e 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a  ndle to which a.
16230 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
16240 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74   | prepared stat
16250 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a  ement] belongs..
16260 2a 2a 20 54 68 69 73 20 69 73 20 74 68 65 20 73  ** This is the s
16270 61 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  ame database han
16280 64 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  dle that was.** 
16290 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
162a0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
162b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
162c0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
162d0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73 65  .** that was use
162e0 64 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 20  d to create the 
162f0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
16300 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f   first place..*/
16310 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
16320 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  3_db_handle(sqli
16330 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a  te3_stmt*);.../*
16340 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
16350 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63  mmit And Rollbac
16360 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  k Notification C
16370 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54  allbacks.**.** T
16380 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
16390 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
163a0 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20  ck functions to 
163b0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
163c0 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
163d0 6e 0a 2a 2a 20 69 73 20 63 6f 6d 6d 69 74 74 65  n.** is committe
163e0 64 20 6f 72 20 72 6f 6c 6c 65 64 20 62 61 63 6b  d or rolled back
163f0 2e 20 20 54 68 65 20 70 41 72 67 20 61 72 67 75  .  The pArg argu
16400 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74  ment is passed t
16410 68 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65  hrough.** to the
16420 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74   callback.  If t
16430 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
16440 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
16450 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e  ction .** return
16460 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
16470 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
16480 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
16490 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
164a0 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
164b0 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
164c0 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
164d0 74 73 20 70 41 72 67 20 76 61 6c 75 65 20 69 73  ts pArg value is
164e0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74   returned..** Ot
164f0 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20  herwise NULL is 
16500 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
16510 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55  Registering a NU
16520 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  LL function disa
16530 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  bles the callbac
16540 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65  k..**.** For the
16550 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
16560 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63  s API, a transac
16570 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20  tion is said to 
16580 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f  have been .** ro
16590 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20  lled back if an 
165a0 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41  explicit "ROLLBA
165b0 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73  CK" statement is
165c0 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a   executed, or.**
165d0 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e   an error or con
165e0 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61  straint causes a
165f0 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62  n implicit rollb
16600 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 20 54 68  ack to occur. Th
16610 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  e .** callback i
16620 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
16630 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
16640 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
16650 72 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 62  rolled.** back b
16660 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
16670 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
16680 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
16690 54 68 65 73 65 20 61 72 65 20 65 78 70 65 72 69  These are experi
166a0 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65  mental interface
166b0 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65 63  s and are subjec
166c0 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  t to change..*/.
166d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
166e0 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
166f0 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
16700 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
16710 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
16720 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
16730 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
16740 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
16750 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
16760 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
16770 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
16780 0a 2a 2a 20 52 65 67 69 73 74 65 72 20 61 20 63  .** Register a c
16790 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
167a0 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
167b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64  se connection id
167c0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
167d0 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65  .** first argume
167e0 6e 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  nt to be invoked
167f0 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
16800 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
16810 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
16820 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b  .** Any callback
16830 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
16840 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
16850 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65  function for the
16860 20 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61   same .** databa
16870 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
16880 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
16890 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
168a0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
168b0 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74  ter to the funct
168c0 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68  ion to invoke wh
168d0 65 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20  en a .** row is 
168e0 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
168f0 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 54 68  d or deleted. Th
16900 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16910 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
16920 20 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66   is.** a copy of
16930 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
16940 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75  ent to sqlite3_u
16950 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 20 54 68  pdate_hook(). Th
16960 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63  e second callbac
16970 6b 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  k .** argument i
16980 73 20 6f 6e 65 20 6f 66 20 53 51 4c 49 54 45 5f  s one of SQLITE_
16990 49 4e 53 45 52 54 2c 20 53 51 4c 49 54 45 5f 44  INSERT, SQLITE_D
169a0 45 4c 45 54 45 20 6f 72 20 53 51 4c 49 54 45 5f  ELETE or SQLITE_
169b0 55 50 44 41 54 45 2c 20 64 65 70 65 6e 64 69 6e  UPDATE, dependin
169c0 67 0a 2a 2a 20 6f 6e 20 74 68 65 20 6f 70 65 72  g.** on the oper
169d0 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65  ation that cause
169e0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74  d the callback t
169f0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 20 54 68  o be invoked. Th
16a00 65 20 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20  e third and .** 
16a10 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
16a20 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
16a30 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
16a40 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
16a50 65 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20  e and .** table 
16a60 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
16a70 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
16a80 2e 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c  . The final call
16a90 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
16aa0 73 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64 20  s .** the rowid 
16ab0 6f 66 20 74 68 65 20 72 6f 77 2e 20 49 6e 20 74  of the row. In t
16ac0 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70  he case of an up
16ad0 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68  date, this is th
16ae0 65 20 72 6f 77 69 64 20 61 66 74 65 72 20 0a 2a  e rowid after .*
16af0 2a 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b  * the update tak
16b00 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  es place..**.** 
16b10 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
16b20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
16b30 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73  hen internal sys
16b40 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a  tem tables are.*
16b50 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e  * modified (i.e.
16b60 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
16b70 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
16b80 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ce)..**.** If an
16b90 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
16ba0 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
16bb0 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41  gistered, its pA
16bc0 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  rg value is retu
16bd0 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  rned..** Otherwi
16be0 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  se NULL is retur
16bf0 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ned..*/.void *sq
16c00 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
16c10 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  k(.  sqlite3*, .
16c20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a    void(*)(void *
16c30 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74  ,int ,char const
16c40 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c   *,char const *,
16c50 73 71 6c 69 74 65 5f 69 6e 74 36 34 29 2c 0a 20  sqlite_int64),. 
16c60 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   void*.);../*.**
16c70 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62   CAPI3REF:  Enab
16c80 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68  le Or Disable Sh
16c90 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65  ared Pager Cache
16ca0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
16cb0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
16cc0 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72  isables the shar
16cd0 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
16ce0 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64  ase cache.** and
16cf0 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72   schema data str
16d00 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20  uctures between 
16d10 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20 74  connections to t
16d20 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
16d30 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73 20  ..** Sharing is 
16d40 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  enabled if the a
16d50 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 20  rgument is true 
16d60 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20  and disabled if 
16d70 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  the argument.** 
16d80 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20  is false..**.** 
16d90 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73  Cache sharing is
16da0 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73   enabled and dis
16db0 61 62 6c 65 64 20 6f 6e 20 61 20 74 68 72 65 61  abled on a threa
16dc0 64 2d 62 79 2d 74 68 72 65 61 64 20 62 61 73 69  d-by-thread basi
16dd0 73 2e 0a 2a 2a 20 45 61 63 68 20 63 61 6c 6c 20  s..** Each call 
16de0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
16df0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
16e00 6c 65 73 20 63 61 63 68 65 20 73 68 61 72 69 6e  les cache sharin
16e10 67 20 6f 6e 6c 79 20 66 6f 72 0a 2a 2a 20 63 6f  g only for.** co
16e20 6e 6e 65 63 74 69 6f 6e 73 20 63 72 65 61 74 65  nnections create
16e30 64 20 69 6e 20 74 68 65 20 73 61 6d 65 20 74 68  d in the same th
16e40 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68  read in which th
16e50 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  is routine is ca
16e60 6c 6c 65 64 2e 0a 2a 2a 20 54 68 65 72 65 20 69  lled..** There i
16e70 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66  s no mechanism f
16e80 6f 72 20 73 68 61 72 69 6e 67 20 63 61 63 68 65  or sharing cache
16e90 20 62 65 74 77 65 65 6e 20 64 61 74 61 62 61 73   between databas
16ea0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
16eb0 20 72 75 6e 6e 69 6e 67 20 69 6e 20 64 69 66 66   running in diff
16ec0 65 72 65 6e 74 20 74 68 72 65 61 64 73 2e 0a 2a  erent threads..*
16ed0 2a 0a 2a 2a 20 53 68 61 72 69 6e 67 20 6d 75 73  *.** Sharing mus
16ee0 74 20 62 65 20 64 69 73 61 62 6c 65 64 20 70 72  t be disabled pr
16ef0 69 6f 72 20 74 6f 20 73 68 75 74 74 69 6e 67 20  ior to shutting 
16f00 64 6f 77 6e 20 61 20 74 68 72 65 61 64 20 6f 72  down a thread or
16f10 20 65 6c 73 65 0a 2a 2a 20 74 68 65 20 74 68 72   else.** the thr
16f20 65 61 64 20 77 69 6c 6c 20 6c 65 61 6b 20 6d 65  ead will leak me
16f30 6d 6f 72 79 2e 20 20 43 61 6c 6c 20 74 68 69 73  mory.  Call this
16f40 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
16f50 20 61 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20   argument of.** 
16f60 30 20 74 6f 20 74 75 72 6e 20 6f 66 66 20 73 68  0 to turn off sh
16f70 61 72 69 6e 67 2e 20 20 4f 72 20 75 73 65 20 74  aring.  Or use t
16f80 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
16f90 64 5f 63 6c 65 61 6e 75 70 28 29 20 41 50 49 2e  d_cleanup() API.
16fa0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
16fb0 69 6e 65 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  ine must not be 
16fc0 63 61 6c 6c 65 64 20 77 68 65 6e 20 61 6e 79 20  called when any 
16fd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16fe0 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 63 74 69  ions.** are acti
16ff0 76 65 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  ve in the curren
17000 74 20 74 68 72 65 61 64 2e 20 20 45 6e 61 62 6c  t thread.  Enabl
17010 69 6e 67 20 6f 72 20 64 69 73 61 62 6c 69 6e 67  ing or disabling
17020 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
17030 20 77 68 69 6c 65 20 74 68 65 72 65 20 61 72 65   while there are
17040 20 61 63 74 69 76 65 20 64 61 74 61 62 61 73 65   active database
17050 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 77 69 6c   connections wil
17060 6c 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 6d  l result.** in m
17070 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
17080 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
17090 20 73 68 61 72 65 64 20 63 61 63 68 65 20 69 73   shared cache is
170a0 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 0a 2a 2a   enabled, the.**
170b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 72 6f 75 74 69   following routi
170c0 6e 65 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20  nes must always 
170d0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
170e0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 3a 0a  he same thread:.
170f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
17100 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
17110 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
17120 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 0a 2a  lite3_step()],.*
17130 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
17140 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 69  ()], [sqlite3_fi
17150 6e 61 6c 69 7a 65 28 29 5d 2c 20 61 6e 64 20 5b  nalize()], and [
17160 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
17170 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 75 65  ..** This is due
17180 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
17190 74 20 74 68 65 20 73 68 61 72 65 64 20 63 61 63  t the shared cac
171a0 68 65 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 0a  he makes use of.
171b0 2a 2a 20 74 68 72 65 61 64 2d 73 70 65 63 69 66  ** thread-specif
171c0 69 63 20 73 74 6f 72 61 67 65 20 73 6f 20 74 68  ic storage so th
171d0 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 61 76  at it will be av
171e0 61 69 6c 61 62 6c 65 20 66 6f 72 20 73 68 61 72  ailable for shar
171f0 69 6e 67 0a 2a 2a 20 77 69 74 68 20 6f 74 68 65  ing.** with othe
17200 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a  r connections..*
17210 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62  *.** Virtual tab
17220 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73  les cannot be us
17230 65 64 20 77 69 74 68 20 61 20 73 68 61 72 65 64  ed with a shared
17240 20 63 61 63 68 65 2e 20 20 57 68 65 6e 20 73 68   cache.  When sh
17250 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
17260 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 73 71   enabled, the sq
17270 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
17280 75 6c 65 28 29 20 41 50 49 20 75 73 65 64 20 74  ule() API used t
17290 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69  o register.** vi
172a0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c  rtual tables wil
172b0 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
172c0 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  an error..**.** 
172d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
172e0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
172f0 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
17300 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20   was.** enabled 
17310 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 63  or disabled succ
17320 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 53  essfully.  An [S
17330 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72  QLITE_ERROR | er
17340 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20  ror code].** is 
17350 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
17360 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64  se..**.** Shared
17370 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
17380 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
17390 72 20 62 61 63 6b 77 61 72 64 20 63 6f 6d 70 61  r backward compa
173a0 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74  tibility..*/.int
173b0 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
173c0 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74  shared_cache(int
173d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
173e0 45 46 3a 20 20 41 74 74 65 6d 70 74 20 54 6f 20  EF:  Attempt To 
173f0 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79  Free Heap Memory
17400 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d 70 74 20 74  .**.** Attempt t
17410 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f  o free N bytes o
17420 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79  f heap memory by
17430 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f   deallocating no
17440 6e 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 6d  n-essential.** m
17450 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
17460 73 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61  s held by the da
17470 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 20 28  tabase library (
17480 65 78 61 6d 70 6c 65 3a 20 6d 65 6d 6f 72 79 20  example: memory 
17490 0a 2a 2a 20 75 73 65 64 20 74 6f 20 63 61 63 68  .** used to cach
174a0 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 73  e database pages
174b0 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
174c0 6f 72 6d 61 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20  ormance)..**.** 
174d0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
174e0 20 6e 6f 74 20 61 20 70 61 72 74 20 6f 66 20 73   not a part of s
174f0 74 61 6e 64 61 72 64 20 62 75 69 6c 64 73 2e 20  tandard builds. 
17500 20 49 74 20 69 73 20 6f 6e 6c 79 20 63 72 65 61   It is only crea
17510 74 65 64 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  ted.** if SQLite
17520 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
17530 68 20 74 68 65 20 53 51 4c 49 54 45 5f 45 4e 41  h the SQLITE_ENA
17540 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
17550 45 4d 45 4e 54 20 6d 61 63 72 6f 2e 0a 2a 2f 0a  EMENT macro..*/.
17560 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  int sqlite3_rele
17570 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b  ase_memory(int);
17580 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17590 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69  :  Impose A Limi
175a0 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a  t On Heap Size.*
175b0 2a 0a 2a 2a 20 50 6c 61 63 65 20 61 20 22 73 6f  *.** Place a "so
175c0 66 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65  ft" limit on the
175d0 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20   amount of heap 
175e0 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20  memory that may 
175f0 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a  be allocated by.
17600 2a 2a 20 53 51 4c 69 74 65 20 77 69 74 68 69 6e  ** SQLite within
17610 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
17620 65 61 64 2e 20 49 66 20 61 6e 20 69 6e 74 65 72  ead. If an inter
17630 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  nal allocation i
17640 73 20 72 65 71 75 65 73 74 65 64 20 0a 2a 2a 20  s requested .** 
17650 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65  that would excee
17660 64 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  d the specified 
17670 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f  limit, [sqlite3_
17680 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
17690 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ] is invoked.** 
176a0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
176b0 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d  s to free up som
176c0 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 74  e space before t
176d0 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  he allocation is
176e0 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   made..**.** The
176f0 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64   limit is called
17700 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65   "soft", because
17710 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c   if [sqlite3_rel
17720 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 63  ease_memory()] c
17730 61 6e 6e 6f 74 20 66 72 65 65 0a 2a 2a 20 73 75  annot free.** su
17740 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
17750 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c  to prevent the l
17760 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20  imit from being 
17770 65 78 63 65 65 64 65 64 2c 20 74 68 65 20 6d 65  exceeded, the me
17780 6d 6f 72 79 20 69 73 0a 2a 2a 20 61 6c 6c 6f 63  mory is.** alloc
17790 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20  ated anyway and 
177a0 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72  the current oper
177b0 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a  ation proceeds..
177c0 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 73  **.** Prior to s
177d0 68 75 74 74 69 6e 67 20 64 6f 77 6e 20 61 20 74  hutting down a t
177e0 68 72 65 61 64 20 73 71 6c 69 74 65 33 5f 73 6f  hread sqlite3_so
177f0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20  ft_heap_limit() 
17800 6d 75 73 74 20 62 65 20 73 65 74 20 74 6f 20 0a  must be set to .
17810 2a 2a 20 7a 65 72 6f 20 28 74 68 65 20 64 65 66  ** zero (the def
17820 61 75 6c 74 29 20 6f 72 20 65 6c 73 65 20 74 68  ault) or else th
17830 65 20 74 68 72 65 61 64 20 77 69 6c 6c 20 6c 65  e thread will le
17840 61 6b 20 6d 65 6d 6f 72 79 2e 20 41 6c 74 65 72  ak memory. Alter
17850 6e 61 74 69 76 65 6c 79 2c 20 75 73 65 0a 2a 2a  natively, use.**
17860 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 68   the [sqlite3_th
17870 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 29 5d 20  read_cleanup()] 
17880 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67  API..**.** A neg
17890 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61  ative or zero va
178a0 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20  lue for N means 
178b0 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f  that there is no
178c0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
178d0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
178e0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
178f0 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20  )] will only be 
17900 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f  called when memo
17910 72 79 20 69 73 20 65 78 68 61 75 73 65 64 2e 0a  ry is exhaused..
17920 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  ** The default v
17930 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66  alue for the sof
17940 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
17950 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  zero..**.** SQLi
17960 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20  te makes a best 
17970 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20  effort to honor 
17980 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
17990 6d 69 74 2e 20 20 42 75 74 20 69 66 20 69 74 0a  mit.  But if it.
179a0 2a 2a 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  ** is unable to 
179b0 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75 73  reduce memory us
179c0 61 67 65 20 62 65 6c 6f 77 20 74 68 65 20 73 6f  age below the so
179d0 66 74 20 6c 69 6d 69 74 2c 20 65 78 65 63 75 74  ft limit, execut
179e0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  ion will.** cont
179f0 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72  inue without err
17a00 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69  or or notificati
17a10 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79  on.  This is why
17a20 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a   the limit is .*
17a30 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74  * called a "soft
17a40 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20  " limit.  It is 
17a50 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a  advisory only..*
17a60 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
17a70 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
17a80 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
17a90 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
17aa0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
17ab0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
17ac0 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 20 6f 70  RY_MANAGEMENT op
17ad0 74 69 6f 6e 20 73 65 74 2e 0a 2a 2a 20 6d 65 6d  tion set..** mem
17ae0 6f 72 79 2d 6d 61 6e 61 67 65 6d 65 6e 74 20 68  ory-management h
17af0 61 73 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 2e  as been enabled.
17b00 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
17b10 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
17b20 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
17b30 50 49 33 52 45 46 3a 20 20 43 6c 65 61 6e 20 55  PI3REF:  Clean U
17b40 70 20 54 68 72 65 61 64 20 4c 6f 63 61 6c 20 53  p Thread Local S
17b50 74 6f 72 61 67 65 0a 2a 2a 0a 2a 2a 20 54 68 69  torage.**.** Thi
17b60 73 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20  s routine makes 
17b70 73 75 72 65 20 74 68 61 74 20 61 6c 6c 20 74 68  sure that all th
17b80 72 65 61 64 2d 6c 6f 63 61 6c 20 73 74 6f 72 61  read-local stora
17b90 67 65 20 68 61 73 20 62 65 65 6e 0a 2a 2a 20 64  ge has been.** d
17ba0 65 61 6c 6c 6f 63 61 74 65 64 20 66 6f 72 20 74  eallocated for t
17bb0 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
17bc0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  d..**.** This ro
17bd0 75 74 69 6e 65 20 69 73 20 6e 6f 74 20 74 65 63  utine is not tec
17be0 68 6e 69 63 61 6c 6c 79 20 6e 65 63 65 73 73 61  hnically necessa
17bf0 72 79 2e 20 20 41 6c 6c 20 74 68 72 65 61 64 2d  ry.  All thread-
17c00 6c 6f 63 61 6c 20 73 74 6f 72 61 67 65 0a 2a 2a  local storage.**
17c10 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
17c20 69 63 61 6c 6c 79 20 64 65 61 6c 6c 6f 63 61 74  ically deallocat
17c30 65 64 20 6f 6e 63 65 20 6d 65 6d 6f 72 79 2d 6d  ed once memory-m
17c40 61 6e 61 67 65 6d 65 6e 74 20 61 6e 64 0a 2a 2a  anagement and.**
17c50 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 61 72   shared-cache ar
17c60 65 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 74  e disabled and t
17c70 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
17c80 69 74 20 68 61 73 20 62 65 65 6e 20 73 65 74 0a  it has been set.
17c90 2a 2a 20 74 6f 20 7a 65 72 6f 2e 20 20 54 68 69  ** to zero.  Thi
17ca0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72 6f  s routine is pro
17cb0 76 69 64 65 64 20 61 73 20 61 20 63 6f 6e 76 65  vided as a conve
17cc0 6e 69 65 6e 63 65 20 66 6f 72 20 75 73 65 72 73  nience for users
17cd0 20 77 68 6f 0a 2a 2a 20 77 61 6e 74 20 74 6f 20   who.** want to 
17ce0 6d 61 6b 65 20 61 62 73 6f 6c 75 74 65 6c 79 20  make absolutely 
17cf0 73 75 72 65 20 74 68 65 79 20 68 61 76 65 20 6e  sure they have n
17d00 6f 74 20 66 6f 72 67 6f 74 74 65 6e 20 73 6f 6d  ot forgotten som
17d10 65 74 68 69 6e 67 0a 2a 2a 20 70 72 69 6f 72 20  ething.** prior 
17d20 74 6f 20 6b 69 6c 6c 69 6e 67 20 6f 66 66 20 61  to killing off a
17d30 20 74 68 72 65 61 64 2e 0a 2a 2f 0a 76 6f 69 64   thread..*/.void
17d40 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
17d50 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 0a  cleanup(void);..
17d60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17d70 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74   Extract Metadat
17d80 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e  a About A Column
17d90 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a   Of A Table.**.*
17da0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  * This routine.*
17db0 2a 20 72 65 74 75 72 6e 73 20 6d 65 74 61 2d 64  * returns meta-d
17dc0 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63  ata about a spec
17dd0 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61  ific column of a
17de0 20 73 70 65 63 69 66 69 63 20 64 61 74 61 62 61   specific databa
17df0 73 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63 65  se.** table acce
17e00 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65  ssible using the
17e10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64   connection hand
17e20 6c 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  le passed as the
17e30 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20   first function 
17e40 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  .** argument..**
17e50 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69  .** The column i
17e60 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
17e70 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72  the second, thir
17e80 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
17e90 61 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74  ameters to .** t
17ea0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  his function. Th
17eb0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17ec0 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65  er is either the
17ed0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
17ee0 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22  abase.** (i.e. "
17ef0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72  main", "temp" or
17f00 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74   an attached dat
17f10 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e  abase) containin
17f20 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a  g the specified.
17f30 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c  ** table or NULL
17f40 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c  . If it is NULL,
17f50 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68   then all attach
17f60 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65  ed databases are
17f70 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72   searched.** for
17f80 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67   the table using
17f90 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
17fa0 74 68 6d 20 61 73 20 74 68 65 20 64 61 74 61 62  thm as the datab
17fb0 61 73 65 20 65 6e 67 69 6e 65 20 75 73 65 73 20  ase engine uses 
17fc0 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75  to .** resolve u
17fd0 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65  nqualified table
17fe0 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a   references..**.
17ff0 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  ** The third and
18000 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
18010 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
18020 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c  ion are the tabl
18030 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a  e and column .**
18040 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73   name of the des
18050 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73  ired column, res
18060 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68  pectively. Neith
18070 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  er of these para
18080 6d 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62  meters .** may b
18090 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65  e NULL..**.** Me
180a0 74 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ta information i
180b0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72  s returned by wr
180c0 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d  iting to the mem
180d0 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61  ory locations pa
180e0 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 35  ssed as.** the 5
180f0 74 68 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  th and subsequen
18100 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
18110 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41  this function. A
18120 6e 79 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20  ny of these .** 
18130 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65  arguments may be
18140 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20   NULL, in which 
18150 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70  case the corresp
18160 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f  onding element o
18170 66 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72  f meta .** infor
18180 6d 61 74 69 6f 6e 20 69 73 20 6f 6d 6d 69 74 74  mation is ommitt
18190 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  ed..**.** <pre>.
181a0 2a 2a 20 50 61 72 61 6d 65 74 65 72 20 20 20 20  ** Parameter    
181b0 20 4f 75 74 70 75 74 20 54 79 70 65 20 20 20 20   Output Type    
181c0 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a    Description.**
181d0 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
181e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
181f0 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68  ----.**.**   5th
18200 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63           const c
18210 68 61 72 2a 20 20 20 20 20 20 44 61 74 61 20 74  har*      Data t
18220 79 70 65 0a 2a 2a 20 20 20 36 74 68 20 20 20 20  ype.**   6th    
18230 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a       const char*
18240 20 20 20 20 20 20 4e 61 6d 65 20 6f 66 20 74 68        Name of th
18250 65 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74  e default collat
18260 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a  ion sequence .**
18270 20 20 20 37 74 68 20 20 20 20 20 20 20 20 20 69     7th         i
18280 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nt              
18290 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75  True if the colu
182a0 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c  mn has a NOT NUL
182b0 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  L constraint.** 
182c0 20 20 38 74 68 20 20 20 20 20 20 20 20 20 69 6e    8th         in
182d0 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54  t              T
182e0 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d  rue if the colum
182f0 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  n is part of the
18300 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20   PRIMARY KEY.** 
18310 20 20 39 74 68 20 20 20 20 20 20 20 20 20 69 6e    9th         in
18320 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54  t              T
18330 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d  rue if the colum
18340 6e 20 69 73 20 41 55 54 4f 49 4e 43 52 45 4d 45  n is AUTOINCREME
18350 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a  NT.** </pre>.**.
18360 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79  **.** The memory
18370 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
18380 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69  he character poi
18390 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66  nters returned f
183a0 6f 72 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61  or the .** decla
183b0 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20  ration type and 
183c0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
183d0 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79  ce is valid only
183e0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
183f0 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20  .** call to any 
18400 73 71 6c 69 74 65 20 41 50 49 20 66 75 6e 63 74  sqlite API funct
18410 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ion..**.** If th
18420 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c  e specified tabl
18430 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20  e is actually a 
18440 76 69 65 77 2c 20 74 68 65 6e 20 61 6e 20 65 72  view, then an er
18450 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
18460 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70  .**.** If the sp
18470 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69  ecified column i
18480 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22  s "rowid", "oid"
18490 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e   or "_rowid_" an
184a0 64 20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52  d an .** INTEGER
184b0 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c   PRIMARY KEY col
184c0 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70  umn has been exp
184d0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
184e0 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75  , then the outpu
184f0 74 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  t .** parameters
18500 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 65   are set for the
18510 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
18520 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20  ared column. If 
18530 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65  there is no.** e
18540 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
18550 65 64 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74  ed IPK column, t
18560 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20 70  hen the output p
18570 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
18580 74 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73  t as .** follows
18590 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  :.**.** <pre>.**
185a0 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20       data type: 
185b0 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20  "INTEGER".**    
185c0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
185d0 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a  nce: "BINARY".**
185e0 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30       not null: 0
185f0 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20  .**     primary 
18600 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75  key: 1.**     au
18610 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a  to increment: 0.
18620 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20  ** </pre>.**.** 
18630 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
18640 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f  y load one or mo
18650 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20  re schemas from 
18660 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20  database files. 
18670 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f  If an.** error o
18680 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69  ccurs during thi
18690 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  s process, or if
186a0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74   the requested t
186b0 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a  able or column.*
186c0 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e  * cannot be foun
186d0 64 2c 20 61 6e 20 53 51 4c 49 54 45 20 65 72 72  d, an SQLITE err
186e0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
186f0 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72  ned and an error
18700 20 6d 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74   message.** left
18710 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
18720 20 68 61 6e 64 6c 65 20 28 74 6f 20 62 65 20 72   handle (to be r
18730 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73  etrieved using s
18740 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29  qlite3_errmsg())
18750 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  ..**.** This API
18760 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
18770 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
18780 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
18790 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
187a0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
187b0 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f 63  METADATA preproc
187c0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
187d0 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
187e0 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d  ite3_table_colum
187f0 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71  n_metadata(.  sq
18800 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
18810 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e            /* Con
18820 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a  nection handle *
18830 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
18840 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20  zDbName,        
18850 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65  /* Database name
18860 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f   or NULL */.  co
18870 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
18880 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62  Name,     /* Tab
18890 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e  le name */.  con
188a0 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
188b0 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75  Name,    /* Colu
188c0 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61  mn name */.  cha
188d0 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61  r const **pzData
188e0 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50  Type,    /* OUTP
188f0 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74  UT: Declared dat
18900 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72  a type */.  char
18910 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53   const **pzCollS
18920 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55  eq,     /* OUTPU
18930 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  T: Collation seq
18940 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  uence name */.  
18950 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20  int *pNotNull,  
18960 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
18970 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e  UTPUT: True if N
18980 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
18990 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69  nt exists */.  i
189a0 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c  nt *pPrimaryKey,
189b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
189c0 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
189d0 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20  lumn part of PK 
189e0 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69  */.  int *pAutoi
189f0 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nc              
18a00 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
18a10 20 69 66 20 63 6f 6c 75 6d 73 20 69 73 20 61 75   if colums is au
18a20 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a  to-increment */.
18a30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18a40 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  EF: Load An Exte
18a50 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 41 74 74 65  nsion.**.** Atte
18a60 6d 70 74 20 74 6f 20 6c 6f 61 64 20 61 6e 20 53  mpt to load an S
18a70 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20  QLite extension 
18a80 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65  library containe
18a90 64 20 69 6e 20 74 68 65 20 66 69 6c 65 0a 2a 2a  d in the file.**
18aa0 20 7a 46 69 6c 65 2e 20 20 54 68 65 20 65 6e 74   zFile.  The ent
18ab0 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f  ry point is zPro
18ac0 63 2e 20 20 7a 50 72 6f 63 20 6d 61 79 20 62 65  c.  zProc may be
18ad0 20 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65   0 in which case
18ae0 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20   the.** name of 
18af0 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  the entry point 
18b00 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c  defaults to "sql
18b10 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69  ite3_extension_i
18b20 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 52 65 74 75  nit"..**.** Retu
18b30 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
18b40 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53  n success and [S
18b50 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
18b60 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77  something goes w
18b70 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  rong..**.** If a
18b80 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61  n error occurs a
18b90 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e  nd pzErrMsg is n
18ba0 6f 74 20 30 2c 20 74 68 65 6e 20 66 69 6c 6c 20  ot 0, then fill 
18bb0 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 0a  *pzErrMsg with .
18bc0 2a 2a 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ** error message
18bd0 20 74 65 78 74 2e 20 20 54 68 65 20 63 61 6c 6c   text.  The call
18be0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ing function sho
18bf0 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65  uld free this me
18c00 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c 69  mory.** by calli
18c10 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
18c20 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 6e  ()]..**.** Exten
18c30 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73  sion loading mus
18c40 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69  t be enabled usi
18c50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
18c60 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
18c70 6e 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  n()].** prior to
18c80 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50   calling this AP
18c90 49 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 77 69  I or an error wi
18ca0 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a  ll be returned..
18cb0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
18cc0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20  oad_extension(. 
18cd0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
18ce0 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74         /* Load t
18cf0 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74  he extension int
18d00 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20  o this database 
18d10 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20  connection */.  
18d20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
18d30 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66  e,    /* Name of
18d40 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72   the shared libr
18d50 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65  ary containing e
18d60 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f  xtension */.  co
18d70 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c  nst char *zProc,
18d80 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69      /* Entry poi
18d90 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f  nt.  Derived fro
18da0 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a  m zFile if 0 */.
18db0 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73    char **pzErrMs
18dc0 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65  g       /* Put e
18dd0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72  rror message her
18de0 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b  e if not 0 */.);
18df0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18e00 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  :  Enable Or Dis
18e10 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c  able Extension L
18e20 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 53 6f 20  oading.**.** So 
18e30 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73  as not to open s
18e40 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e  ecurity holes in
18e50 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69   older applicati
18e60 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  ons that are.** 
18e70 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65  unprepared to de
18e80 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f  al with extensio
18e90 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61  n loading, and a
18ea0 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73  s a means of dis
18eb0 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73  abling.** extens
18ec0 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c  ion loading whil
18ed0 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65  e evaluating use
18ee0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74  r-entered SQL, t
18ef0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  he following.** 
18f00 41 50 49 20 69 73 20 70 72 6f 76 69 64 65 64 20  API is provided 
18f10 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c  to turn the [sql
18f20 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
18f30 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d  ion()] mechanism
18f40 20 6f 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20   on and.** off. 
18f50 20 49 74 20 69 73 20 6f 66 66 20 62 79 20 64 65   It is off by de
18f60 66 61 75 6c 74 2e 20 20 53 65 65 20 74 69 63 6b  fault.  See tick
18f70 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20  et #1863..**.** 
18f80 43 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  Call this routin
18f90 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20  e with onoff==1 
18fa0 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f  to turn extensio
18fb0 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20  n loading on.** 
18fc0 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68  and call it with
18fd0 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72   onoff==0 to tur
18fe0 6e 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67  n it back off ag
18ff0 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ain..*/.int sqli
19000 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
19010 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65  extension(sqlite
19020 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66  3 *db, int onoff
19030 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19040 45 46 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67 65  EF: Make Arrange
19050 6d 65 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61 74  ments To Automat
19060 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45  ically Load An E
19070 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 52  xtension.**.** R
19080 65 67 69 73 74 65 72 20 61 6e 20 65 78 74 65 6e  egister an exten
19090 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74  sion entry point
190a0 20 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61 74   that is automat
190b0 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a 2a  ically invoked.*
190c0 2a 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77  * whenever a new
190d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
190e0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20 75  tion is opened u
190f0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
19100 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c  _open()] or [sql
19110 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
19120 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63  **.** This API c
19130 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74  an be invoked at
19140 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70   program startup
19150 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67   in order to reg
19160 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  ister.** one or 
19170 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20  more statically 
19180 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e  linked extension
19190 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61  s that will be a
191a0 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61  vailable.** to a
191b0 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  ll new database 
191c0 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  connections..**.
191d0 2a 2a 20 44 75 70 6c 69 63 61 74 65 20 65 78 74  ** Duplicate ext
191e0 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65  ensions are dete
191f0 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20  cted so calling 
19200 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c  this routine mul
19210 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
19220 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74  ith the same ext
19230 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65  ension is harmle
19240 73 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ss..**.** This r
19250 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20  outine stores a 
19260 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65  pointer to the e
19270 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61  xtension in an a
19280 72 72 61 79 0a 2a 2a 20 74 68 61 74 20 69 73 20  rray.** that is 
19290 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61  obtained from ma
192a0 6c 6c 6f 63 28 29 2e 20 20 49 66 20 79 6f 75 20  lloc().  If you 
192b0 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  run a memory lea
192c0 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20 6f 6e 20  k.** checker on 
192d0 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e 64  your program and
192e0 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c 65   it reports a le
192f0 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74 68  ak because of th
19300 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20 74 68 65  is.** array, the
19310 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  n invoke [sqlite
19320 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78 74 65  3_automatic_exte
19330 6e 73 69 6f 6e 5f 72 65 73 65 74 28 29 5d 20 70  nsion_reset()] p
19340 72 69 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64  rior.** to shutd
19350 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20  own to free the 
19360 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 75  memory..**.** Au
19370 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
19380 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20  ns apply across 
19390 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a  all threads..**.
193a0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
193b0 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61  e is experimenta
193c0 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74  l and is subject
193d0 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a   to change or.**
193e0 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75   removal in futu
193f0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
19400 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
19410 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
19420 73 69 6f 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72  sion(void *xEntr
19430 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  yPoint);.../*.**
19440 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
19450 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e   Automatic Exten
19460 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a  sion Loading.**.
19470 2a 2a 20 44 69 73 61 62 6c 65 20 61 6c 6c 20 70  ** Disable all p
19480 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
19490 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63 20 65  ered automatic e
194a0 78 74 65 6e 73 69 6f 6e 73 2e 20 20 54 68 69 73  xtensions.  This
194b0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
194c0 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
194d0 20 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c 69   all prior [sqli
194e0 74 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78  te3_automatic_ex
194f0 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63 61  tension()].** ca
19500 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  lls..**.** This 
19510 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20 61 75  call disabled au
19520 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
19530 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64  ns in all thread
19540 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  s..**.** This in
19550 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72  terface is exper
19560 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73  imental and is s
19570 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
19580 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69   or.** removal i
19590 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
195a0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
195b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
195c0 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
195d0 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  n(void);.../*.**
195e0 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  **** EXPERIMENTA
195f0 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63  L - subject to c
19600 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f  hange without no
19610 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  tice ***********
19620 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ***.**.** The in
19630 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76  terface to the v
19640 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
19650 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e  hanism is curren
19660 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
19670 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
19680 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
19690 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
196a0 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
196b0 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
196c0 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
196d0 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
196e0 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
196f0 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
19700 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
19710 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
19720 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65 73  hanism stablizes
19730 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
19740 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** interfa
19750 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72  ce fixed, suppor
19760 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c  t it indefinitel
19770 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68  y, and remove th
19780 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a  is comment..*/..
19790 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73  /*.** Structures
197a0 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72   used by the vir
197b0 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72  tual table inter
197c0 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20  face.*/.typedef 
197d0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
197e0 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62  tab sqlite3_vtab
197f0 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
19800 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
19810 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  nfo sqlite3_inde
19820 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20  x_info;.typedef 
19830 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
19840 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74  tab_cursor sqlit
19850 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a  e3_vtab_cursor;.
19860 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
19870 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71  qlite3_module sq
19880 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f  lite3_module;../
19890 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69 73  *.** A module is
198a0 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72 74   a class of virt
198b0 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61 63  ual tables.  Eac
198c0 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66 69  h module is defi
198d0 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e 73  ned.** by an ins
198e0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f 6c  tance of the fol
198f0 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65  lowing structure
19900 2e 20 20 54 68 69 73 20 73 74 72 75 63 74 75 72  .  This structur
19910 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f  e consists.** mo
19920 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20  stly of methods 
19930 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
19940 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
19950 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74  3_module {.  int
19960 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
19970 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69   (*xCreate)(sqli
19980 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
19990 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
199a0 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
199b0 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
199c0 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
199d0 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
199e0 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
199f0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65  ;.  int (*xConne
19a00 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ct)(sqlite3*, vo
19a10 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
19a20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
19a30 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
19a40 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
19a50 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
19a60 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
19a70 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
19a80 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71  (*xBestIndex)(sq
19a90 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
19aa0 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  b, sqlite3_index
19ab0 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28  _info*);.  int (
19ac0 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71  *xDisconnect)(sq
19ad0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
19ae0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73  b);.  int (*xDes
19af0 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74  troy)(sqlite3_vt
19b00 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
19b10 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
19b20 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
19b30 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
19b40 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b  sor **ppCursor);
19b50 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
19b60 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
19b70 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
19b80 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33  xFilter)(sqlite3
19b90 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69  _vtab_cursor*, i
19ba0 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74  nt idxNum, const
19bb0 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20   char *idxStr,. 
19bc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
19bd0 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33  nt argc, sqlite3
19be0 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a  _value **argv);.
19bf0 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73    int (*xNext)(s
19c00 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
19c10 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45  or*);.  int (*xE
19c20 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  of)(sqlite3_vtab
19c30 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
19c40 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69   (*xColumn)(sqli
19c50 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
19c60 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  , sqlite3_contex
19c70 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  t*, int);.  int 
19c80 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65  (*xRowid)(sqlite
19c90 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
19ca0 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 2a 70 52  sqlite_int64 *pR
19cb0 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78  owid);.  int (*x
19cc0 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f  Update)(sqlite3_
19cd0 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c  vtab *, int, sql
19ce0 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73  ite3_value **, s
19cf0 71 6c 69 74 65 5f 69 6e 74 36 34 20 2a 29 3b 0a  qlite_int64 *);.
19d00 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28    int (*xBegin)(
19d10 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
19d20 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Tab);.  int (*xS
19d30 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ync)(sqlite3_vta
19d40 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
19d50 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69   (*xCommit)(sqli
19d60 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
19d70 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62  ;.  int (*xRollb
19d80 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ack)(sqlite3_vta
19d90 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
19da0 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e   (*xFindFunction
19db0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
19dc0 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c  pVtab, int nArg,
19dd0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
19de0 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  me,.            
19df0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
19e00 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74  (**pxFunc)(sqlit
19e10 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
19e20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
19e30 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
19e40 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a           void **
19e50 70 70 41 72 67 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a  ppArg);.};../*.*
19e60 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
19e70 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75  dex_info structu
19e80 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74  re and its subst
19e90 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64  ructures is used
19ea0 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f   to.** pass info
19eb0 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64  rmation into and
19ec0 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70   receive the rep
19ed0 6c 79 20 66 72 6f 6d 20 74 68 65 20 78 42 65 73  ly from the xBes
19ee0 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64  tIndex.** method
19ef0 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d   of an sqlite3_m
19f00 6f 64 75 6c 65 2e 20 20 54 68 65 20 66 69 65 6c  odule.  The fiel
19f10 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74  ds under **Input
19f20 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69  s** are the.** i
19f30 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e  nputs to xBestIn
19f40 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 61 64  dex and are read
19f50 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64  -only.  xBestInd
19f60 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a  ex inserts its.*
19f70 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74  * results into t
19f80 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66  he **Outputs** f
19f90 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ields..**.** The
19fa0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
19fb0 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48 45  rray records WHE
19fc0 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
19fd0 61 69 6e 74 73 20 6f 66 20 74 68 65 0a 2a 2a 20  aints of the.** 
19fe0 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20  form:.**.**     
19ff0 20 20 20 20 63 6f 6c 75 6d 6e 20 4f 50 20 65 78      column OP ex
1a000 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65 72 65 20 4f  pr.**.** Where O
1a010 50 20 69 73 20 3d 2c 20 3c 2c 20 3c 3d 2c 20 3e  P is =, <, <=, >
1a020 2c 20 6f 72 20 3e 3d 2e 20 20 54 68 65 20 70 61  , or >=.  The pa
1a030 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f  rticular operato
1a040 72 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  r is stored.** i
1a050 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  n aConstraint[].
1a060 6f 70 2e 20 20 54 68 65 20 69 6e 64 65 78 20 6f  op.  The index o
1a070 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
1a080 73 74 6f 72 65 64 20 69 6e 20 0a 2a 2a 20 61 43  stored in .** aC
1a090 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c  onstraint[].iCol
1a0a0 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e  umn.  aConstrain
1a0b0 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52  t[].usable is TR
1a0c0 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70  UE if the.** exp
1a0d0 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68  r on the right-h
1a0e0 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62 65 20  and side can be 
1a0f0 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74  evaluated (and t
1a100 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hus the constrai
1a110 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29  nt.** is usable)
1a120 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74   and false if it
1a130 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54   cannot..**.** T
1a140 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74  he optimizer aut
1a150 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72  omatically inver
1a160 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20  ts terms of the 
1a170 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f  form "expr OP co
1a180 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b  lumn".** and mak
1a190 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66  es other simplif
1a1a0 69 63 61 74 69 6e 6f 73 20 74 6f 20 74 68 65 20  icatinos to the 
1a1b0 57 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20  WHERE clause in 
1a1c0 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a  an attempt to.**
1a1d0 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45   get as many WHE
1a1e0 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20  RE clause terms 
1a1f0 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68  into the form sh
1a200 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73  own above as pos
1a210 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43  sible..** The aC
1a220 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
1a230 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57  y only reports W
1a240 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
1a250 73 20 69 6e 20 74 68 65 20 63 6f 72 72 65 63 74  s in the correct
1a260 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20 72 65  .** form that re
1a270 66 65 72 20 74 6f 20 74 68 65 20 70 61 72 74 69  fer to the parti
1a280 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61  cular virtual ta
1a290 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69 65  ble being querie
1a2a0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61  d..**.** Informa
1a2b0 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f  tion about the O
1a2c0 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69  RDER BY clause i
1a2d0 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64  s stored in aOrd
1a2e0 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20  erBy[]..** Each 
1a2f0 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79  term of aOrderBy
1a300 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d   records a colum
1a310 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42  n of the ORDER B
1a320 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  Y clause..**.** 
1a330 54 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d  The xBestIndex m
1a340 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20  ethod must fill 
1a350 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
1a360 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74  [] with informat
1a370 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61  ion.** about wha
1a380 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
1a390 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e  pass to xFilter.
1a3a0 20 20 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30    If argvIndex>0
1a3b0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67   then.** the rig
1a3c0 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ht-hand side of 
1a3d0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
1a3e0 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  g aConstraint[] 
1a3f0 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20  is evaluated.** 
1a400 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20  and becomes the 
1a410 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74  argvIndex-th ent
1a420 72 79 20 69 6e 20 61 72 67 76 2e 20 20 49 66 20  ry in argv.  If 
1a430 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
1a440 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72  [].omit.** is tr
1a450 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  ue, then the con
1a460 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d  straint is assum
1a470 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68  ed to be fully h
1a480 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a  andled by the.**
1a490 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61   virtual table a
1a4a0 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65  nd is not checke
1a4b0 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74  d again by SQLit
1a4c0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78  e..**.** The idx
1a4d0 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76  Num and idxPtr v
1a4e0 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 64  alues are record
1a4f0 65 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e  ed and passed in
1a500 74 6f 20 78 46 69 6c 74 65 72 2e 0a 2a 2a 20 73  to xFilter..** s
1a510 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1a520 20 75 73 65 64 20 74 6f 20 66 72 65 65 20 69 64   used to free id
1a530 78 50 74 72 20 69 66 20 6e 65 65 64 54 6f 46 72  xPtr if needToFr
1a540 65 65 49 64 78 50 74 72 20 69 73 20 74 72 75 65  eeIdxPtr is true
1a550 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65  ..**.** The orde
1a560 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e  rByConsumed mean
1a570 73 20 74 68 61 74 20 6f 75 74 70 75 74 20 66 72  s that output fr
1a580 6f 6d 20 78 46 69 6c 74 65 72 20 77 69 6c 6c 20  om xFilter will 
1a590 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20  occur in.** the 
1a5a0 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f  correct order to
1a5b0 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 44   satisfy the ORD
1a5c0 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20  ER BY clause so 
1a5d0 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65  that no separate
1a5e0 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70  .** sorting step
1a5f0 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
1a600 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61 74 65  .** The estimate
1a610 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61  dCost value is a
1a620 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68  n estimate of th
1a630 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20  e cost of doing 
1a640 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61  the.** particula
1a650 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c  r lookup.  A ful
1a660 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c  l scan of a tabl
1a670 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73  e with N entries
1a680 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20   should have.** 
1a690 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20  a cost of N.  A 
1a6a0 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66  binary search of
1a6b0 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e   a table of N en
1a6c0 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76  tries should hav
1a6d0 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61  e a.** cost of a
1a6e0 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67  pproximately log
1a6f0 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  (N)..*/.struct s
1a700 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
1a710 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20  o {.  /* Inputs 
1a720 2a 2f 0a 20 20 63 6f 6e 73 74 20 69 6e 74 20 6e  */.  const int n
1a730 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
1a740 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74  /* Number of ent
1a750 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61  ries in aConstra
1a760 69 6e 74 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73  int */.  const s
1a770 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
1a780 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b  dex_constraint {
1a790 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
1a7a0 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
1a7b0 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66  /* Column on lef
1a7c0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63  t-hand side of c
1a7d0 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20  onstraint */.   
1a7e0 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
1a7f0 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43  op;         /* C
1a800 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74  onstraint operat
1a810 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  or */.     unsig
1a820 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b  ned char usable;
1a830 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
1a840 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
1a850 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20  is usable */.   
1a860 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65    int iTermOffse
1a870 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55  t;          /* U
1a880 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d  sed internally -
1a890 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75   xBestIndex shou
1a8a0 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d  ld ignore */.  }
1a8b0 20 2a 63 6f 6e 73 74 20 61 43 6f 6e 73 74 72 61   *const aConstra
1a8c0 69 6e 74 3b 20 20 20 20 20 20 2f 2a 20 54 61 62  int;      /* Tab
1a8d0 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75  le of WHERE clau
1a8e0 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a  se constraints *
1a8f0 2f 0a 20 20 63 6f 6e 73 74 20 69 6e 74 20 6e 4f  /.  const int nO
1a900 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 2f  rderBy;        /
1a910 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  * Number of term
1a920 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42  s in the ORDER B
1a930 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 63 6f  Y clause */.  co
1a940 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
1a950 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79  e3_index_orderby
1a960 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c   {.     int iCol
1a970 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  umn;            
1a980 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62    /* Column numb
1a990 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  er */.     unsig
1a9a0 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20  ned char desc;  
1a9b0 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72       /* True for
1a9c0 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f   DESC.  False fo
1a9d0 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 63  r ASC. */.  } *c
1a9e0 6f 6e 73 74 20 61 4f 72 64 65 72 42 79 3b 20 20  onst aOrderBy;  
1a9f0 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52         /* The OR
1aa00 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
1aa10 0a 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a  ..  /* Outputs *
1aa20 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
1aa30 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61  e3_index_constra
1aa40 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20  int_usage {.    
1aa50 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20  int argvIndex;  
1aa60 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e           /* if >
1aa70 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  0, constraint is
1aa80 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f   part of argv to
1aa90 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20   xFilter */.    
1aaa0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d  unsigned char om
1aab0 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e  it;      /* Do n
1aac0 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66  ot code a test f
1aad0 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69  or this constrai
1aae0 6e 74 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74  nt */.  } *const
1aaf0 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67   aConstraintUsag
1ab00 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b  e;.  int idxNum;
1ab10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ab20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74  /* Number used t
1ab30 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69  o identify the i
1ab40 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ndex */.  char *
1ab50 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20  idxStr;         
1ab60 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20       /* String, 
1ab70 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65  possibly obtaine
1ab80 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1ab90 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e  alloc */.  int n
1aba0 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b  eedToFreeIdxStr;
1abb0 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64        /* Free id
1abc0 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74  xStr using sqlit
1abd0 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75  e3_free() if tru
1abe0 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72  e */.  int order
1abf0 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20  ByConsumed;     
1ac00 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74    /* True if out
1ac10 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f  put is already o
1ac20 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62  rdered */.  doub
1ac30 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  le estimatedCost
1ac40 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61  ;      /* Estima
1ac50 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e  ted cost of usin
1ac60 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a  g this index */.
1ac70 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  };.#define SQLIT
1ac80 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
1ac90 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69  NT_EQ    2.#defi
1aca0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
1acb0 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20  CONSTRAINT_GT   
1acc0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
1acd0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
1ace0 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69  NT_LE    8.#defi
1acf0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
1ad00 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20  CONSTRAINT_LT   
1ad10 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
1ad20 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
1ad30 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65  INT_GE    32.#de
1ad40 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
1ad50 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54  X_CONSTRAINT_MAT
1ad60 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 54 68 69  CH 64../*.** Thi
1ad70 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65  s routine is use
1ad80 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20  d to register a 
1ad90 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20  new module name 
1ada0 77 69 74 68 20 61 6e 20 53 51 4c 69 74 65 0a 2a  with an SQLite.*
1adb0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 4d  * connection.  M
1adc0 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74  odule names must
1add0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 62   be registered b
1ade0 65 66 6f 72 65 20 63 72 65 61 74 69 6e 67 20 6e  efore creating n
1adf0 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  ew.** virtual ta
1ae00 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d 6f 64 75  bles on the modu
1ae10 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20 75 73  le, or before us
1ae20 69 6e 67 20 70 72 65 65 78 69 73 74 69 6e 67 20  ing preexisting 
1ae30 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65  virtual.** table
1ae40 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e  s of the module.
1ae50 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1ae60 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20  create_module(. 
1ae70 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1ae80 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
1ae90 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
1aea0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
1aeb0 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
1aec0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
1aed0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
1aee0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
1aef0 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
1af00 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f  3_module *,    /
1af10 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
1af20 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
1af30 69 64 20 2a 20 20 20 20 20 20 20 20 20 20 20 20  id *            
1af40 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
1af50 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
1af60 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
1af70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 45 76 65 72 79 20  );../*.** Every 
1af80 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
1af90 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62  ation uses a sub
1afa0 63 6c 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c  class of the fol
1afb0 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65  lowing structure
1afc0 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20  .** to describe 
1afd0 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73  a particular ins
1afe0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 6d 6f 64  tance of the mod
1aff0 75 6c 65 2e 20 20 45 61 63 68 20 73 75 62 63 6c  ule.  Each subcl
1b000 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74  ass will.** be t
1b010 61 79 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73  aylored to the s
1b020 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
1b030 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c   the module impl
1b040 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 20 54 68  ementation.   Th
1b050 65 0a 2a 2a 20 70 75 72 70 6f 73 65 20 6f 66 20  e.** purpose of 
1b060 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20  this superclass 
1b070 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72  is to define cer
1b080 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74  tain fields that
1b090 20 61 72 65 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74   are common.** t
1b0a0 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70  o all module imp
1b0b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a  lementations..**
1b0c0 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c  .** Virtual tabl
1b0d0 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73  es methods can s
1b0e0 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  et an error mess
1b0f0 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67  age by assigning
1b100 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74   a.** string obt
1b110 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
1b120 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 74 6f 20  e3_mprintf() to 
1b130 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65  zErrMsg.  The me
1b140 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74  thod should.** t
1b150 61 6b 65 20 63 61 72 65 20 74 68 61 74 20 61 6e  ake care that an
1b160 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69  y prior string i
1b170 73 20 66 72 65 65 64 20 62 79 20 61 20 63 61 6c  s freed by a cal
1b180 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  l to sqlite3_fre
1b190 65 28 29 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  e().** prior to 
1b1a0 61 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20  assigning a new 
1b1b0 73 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73  string to zErrMs
1b1c0 67 2e 20 20 41 66 74 65 72 20 74 68 65 20 65 72  g.  After the er
1b1d0 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69  ror message.** i
1b1e0 73 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74  s delivered up t
1b1f0 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70  o the client app
1b200 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74  lication, the st
1b210 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74  ring will be aut
1b220 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72  omatically.** fr
1b230 65 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66  eed by sqlite3_f
1b240 72 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45  ree() and the zE
1b250 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c  rrMsg field will
1b260 20 62 65 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74   be zeroed.  Not
1b270 65 0a 2a 2a 20 74 68 61 74 20 73 71 6c 69 74 65  e.** that sqlite
1b280 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1b290 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61  sqlite3_free() a
1b2a0 72 65 20 75 73 65 64 20 6f 6e 20 74 68 65 20 7a  re used on the z
1b2b0 45 72 72 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20  ErrMsg field.** 
1b2c0 73 69 6e 63 65 20 76 69 72 74 75 61 6c 20 74 61  since virtual ta
1b2d0 62 6c 65 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c  bles are commonl
1b2e0 79 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e  y implemented in
1b2f0 20 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73   loadable extens
1b300 69 6f 6e 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f  ions which.** do
1b310 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
1b320 20 74 6f 20 73 71 6c 69 74 65 33 4d 50 72 69 6e   to sqlite3MPrin
1b330 74 66 28 29 20 6f 72 20 73 71 6c 69 74 65 33 46  tf() or sqlite3F
1b340 72 65 65 28 29 2e 0a 2a 2f 0a 73 74 72 75 63 74  ree()..*/.struct
1b350 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a   sqlite3_vtab {.
1b360 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
1b370 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b  module *pModule;
1b380 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20    /* The module 
1b390 66 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c  for this virtual
1b3a0 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20   table */.  int 
1b3b0 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20  nRef;           
1b3c0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55              /* U
1b3d0 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a  sed internally *
1b3e0 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  /.  char *zErrMs
1b3f0 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g;              
1b400 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73      /* Error mes
1b410 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  sage from sqlite
1b420 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20  3_mprintf() */. 
1b430 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
1b440 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1b450 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79  s will typically
1b460 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20   add additional 
1b470 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  fields */.};../*
1b480 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d   Every module im
1b490 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65  plementation use
1b4a0 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  s a subclass of 
1b4b0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
1b4c0 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65  ructure.** to de
1b4d0 73 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74  scribe cursors t
1b4e0 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74  hat point into t
1b4f0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
1b500 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a   and are used.**
1b510 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68   to loop through
1b520 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
1b530 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65  le.  Cursors are
1b540 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74   created using t
1b550 68 65 0a 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68  he.** xOpen meth
1b560 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  od of the module
1b570 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69  .  Each module i
1b580 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
1b590 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  ll define.** the
1b5a0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75   content of a cu
1b5b0 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74  rsor structure t
1b5c0 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e  o suit its own n
1b5d0 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eeds..**.** This
1b5e0 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73   superclass exis
1b5f0 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64  ts in order to d
1b600 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20  efine fields of 
1b610 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a  the cursor that.
1b620 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f  ** are common to
1b630 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74   all implementat
1b640 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  ions..*/.struct 
1b650 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
1b660 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f  sor {.  sqlite3_
1b670 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20  vtab *pVtab;    
1b680 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
1b690 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f  le of this curso
1b6a0 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61  r */.  /* Virtua
1b6b0 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
1b6c0 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70  tations will typ
1b6d0 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74  ically add addit
1b6e0 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a  ional fields */.
1b6f0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 78 43  };../*.** The xC
1b700 72 65 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65  reate and xConne
1b710 63 74 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 20  ct methods of a 
1b720 6d 6f 64 75 6c 65 20 75 73 65 20 74 68 65 20 66  module use the f
1b730 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20  ollowing API.** 
1b740 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66  to declare the f
1b750 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73  ormat (the names
1b760 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f   and datatypes o
1b770 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f  f the columns) o
1b780 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c  f.** the virtual
1b790 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70   tables they imp
1b7a0 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73  lement..*/.int s
1b7b0 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76  qlite3_declare_v
1b7c0 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f  tab(sqlite3*, co
1b7d0 6e 73 74 20 63 68 61 72 20 2a 7a 43 72 65 61 74  nst char *zCreat
1b7e0 65 54 61 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  eTable);../*.** 
1b7f0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63  Virtual tables c
1b800 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72  an provide alter
1b810 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74  native implement
1b820 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69  ations of functi
1b830 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  ons.** using the
1b840 20 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 20 6d   xFindFunction m
1b850 65 74 68 6f 64 2e 20 20 42 75 74 20 67 6c 6f 62  ethod.  But glob
1b860 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74  al versions of t
1b870 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  hose functions.*
1b880 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20  * must exist in 
1b890 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72  order to be over
1b8a0 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  loaded..**.** Th
1b8b0 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72  is API makes sur
1b8c0 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69  e a global versi
1b8d0 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e  on of a function
1b8e0 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
1b8f0 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e  ar.** name and n
1b900 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74  umber of paramet
1b910 65 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 20  ers exists.  If 
1b920 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e  no such function
1b930 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72   exists.** befor
1b940 65 20 74 68 69 73 20 41 50 49 20 69 73 20 63 61  e this API is ca
1b950 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63  lled, a new func
1b960 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e  tion is created.
1b970 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
1b980 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e  tion.** of the n
1b990 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61  ew function alwa
1b9a0 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63  ys causes an exc
1b9b0 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72  eption to be thr
1b9c0 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20  own.  So.** the 
1b9d0 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  new function is 
1b9e0 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79  not good for any
1b9f0 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e  thing by itself.
1ba00 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75    Its only.** pu
1ba10 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61  rpose is to be a
1ba20 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 20 66 75   place-holder fu
1ba30 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20  nction that can 
1ba40 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a  be overloaded.**
1ba50 20 62 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c   by virtual tabl
1ba60 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  es..**.** This A
1ba70 50 49 20 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e  PI should be con
1ba80 73 69 64 65 72 65 64 20 70 61 72 74 20 6f 66 20  sidered part of 
1ba90 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
1baa0 65 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  e interface,.** 
1bab0 77 68 69 63 68 20 69 73 20 65 78 70 65 72 69 6d  which is experim
1bac0 65 6e 74 61 6c 20 61 6e 64 20 73 75 62 6a 65 63  ental and subjec
1bad0 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  t to change..*/.
1bae0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72  int sqlite3_over
1baf0 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71  load_function(sq
1bb00 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
1bb10 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69  ar *zFuncName, i
1bb20 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a  nt nArg);../*.**
1bb30 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
1bb40 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
1bb50 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65  ble mechanism de
1bb60 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63  fined above (bac
1bb70 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d  k up.** to a com
1bb80 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20  ment remarkably 
1bb90 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20  similar to this 
1bba0 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c  one) is currentl
1bbb0 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  y considered.** 
1bbc0 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74  to be experiment
1bbd0 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  al.  The interfa
1bbe0 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ce might change 
1bbf0 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  in incompatible 
1bc00 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ways..** If this
1bc10 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f   is a problem fo
1bc20 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73  r you, do not us
1bc30 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  e the interface 
1bc40 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a  at this time..**
1bc50 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72  .** When the vir
1bc60 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
1bc70 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65 73 2c 20  nism stablizes, 
1bc80 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20  we will declare 
1bc90 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  the.** interface
1bca0 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20   fixed, support 
1bcb0 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c  it indefinitely,
1bcc0 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73   and remove this
1bcd0 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a   comment..**.***
1bce0 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  *** EXPERIMENTAL
1bcf0 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68   - subject to ch
1bd00 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74  ange without not
1bd10 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ice ************
1bd20 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  **.*/../*.** CAP
1bd30 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20  I3REF: A Handle 
1bd40 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a  To An Open BLOB.
1bd50 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
1bd60 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
1bd70 6e 67 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  ng opaque struct
1bd80 75 72 65 20 69 73 20 75 73 65 64 20 74 6f 20 0a  ure is used to .
1bd90 2a 2a 20 72 65 70 72 65 73 65 6e 74 20 61 6e 20  ** represent an 
1bda0 62 6c 6f 62 2d 68 61 6e 64 6c 65 2e 20 20 41 20  blob-handle.  A 
1bdb0 62 6c 6f 62 2d 68 61 6e 64 6c 65 20 69 73 20 63  blob-handle is c
1bdc0 72 65 61 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71  reated by.** [sq
1bdd0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
1bde0 29 5d 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64  )] and destroyed
1bdf0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
1be00 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54  b_close()]..** T
1be10 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
1be20 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71  _read()] and [sq
1be30 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
1be40 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ()] interfaces.*
1be50 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
1be60 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73   read or write s
1be70 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73  mall subsections
1be80 20 6f 66 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a   of the blob..**
1be90 20 54 68 65 20 5b 73 71 6c 74 69 65 33 5f 62 6c   The [sqltie3_bl
1bea0 6f 62 5f 73 69 7a 65 28 29 5d 20 69 6e 74 65 72  ob_size()] inter
1beb0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
1bec0 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
1bed0 62 6c 6f 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a  blob in bytes..*
1bee0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1bef0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71   sqlite3_blob sq
1bf00 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a  lite3_blob;../*.
1bf10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
1bf20 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63  n A BLOB For Inc
1bf30 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a  remental I/O.**.
1bf40 2a 2a 20 4f 70 65 6e 20 61 20 68 61 6e 64 6c 65  ** Open a handle
1bf50 20 74 6f 20 74 68 65 20 62 6c 6f 62 20 6c 6f 63   to the blob loc
1bf60 61 74 65 64 20 69 6e 20 72 6f 77 20 69 52 6f 77  ated in row iRow
1bf70 2c 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d  ,, column zColum
1bf80 6e 2c 20 0a 2a 2a 20 74 61 62 6c 65 20 7a 54 61  n, .** table zTa
1bf90 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20  ble in database 
1bfa0 7a 44 62 2e 20 69 2e 65 2e 20 74 68 65 20 73 61  zDb. i.e. the sa
1bfb0 6d 65 20 62 6c 6f 62 20 74 68 61 74 20 77 6f 75  me blob that wou
1bfc0 6c 64 0a 2a 2a 20 62 65 20 73 65 6c 65 63 74 65  ld.** be selecte
1bfd0 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  d by:.**.** <pre
1bfe0 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20  >.**     SELECT 
1bff0 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62  zColumn FROM zDb
1c000 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 72 6f  .zTable WHERE ro
1c010 77 69 64 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c  wid = iRow;.** <
1c020 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  /pre>.**.** If t
1c030 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
1c040 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  er is non-zero, 
1c050 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e  the blob is open
1c060 65 64 20 66 6f 72 20 0a 2a 2a 20 72 65 61 64 20  ed for .** read 
1c070 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73  and write access
1c080 2e 20 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c  . If it is zero,
1c090 20 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65   the blob is ope
1c0a0 6e 65 64 20 66 6f 72 20 72 65 61 64 20 0a 2a 2a  ned for read .**
1c0b0 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4f   access..**.** O
1c0c0 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49  n success, [SQLI
1c0d0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
1c0e0 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 0a  ed and the new .
1c0f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
1c100 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 20   | blob handle] 
1c110 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 2a 70  is written to *p
1c120 70 42 6c 6f 62 2e 0a 2a 2a 20 4f 74 68 65 72 77  pBlob..** Otherw
1c130 69 73 65 20 61 6e 20 65 72 72 6f 72 20 63 6f 64  ise an error cod
1c140 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  e is returned an
1c150 64 20 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  d .** any value 
1c160 77 72 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c  written to *ppBl
1c170 6f 62 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  ob should not be
1c180 20 75 73 65 64 20 62 79 20 74 68 65 20 63 61 6c   used by the cal
1c190 6c 65 72 2e 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ler..** This fun
1c1a0 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 64  ction sets the d
1c1b0 61 74 61 62 61 73 65 2d 68 61 6e 64 6c 65 20 65  atabase-handle e
1c1c0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
1c1d0 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69  ssage.** accessi
1c1e0 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ble via [sqlite3
1c1f0 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20  _errcode()] and 
1c200 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1c210 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1c220 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20  e3_blob_open(.  
1c230 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73  sqlite3*,.  cons
1c240 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63  t char *zDb,.  c
1c250 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c  onst char *zTabl
1c260 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  e,.  const char 
1c270 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69  *zColumn,.  sqli
1c280 74 65 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20  te_int64 iRow,. 
1c290 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71   int flags,.  sq
1c2a0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42  lite3_blob **ppB
1c2b0 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lob.);../*.** CA
1c2c0 50 49 33 52 45 46 3a 20 20 43 6c 6f 73 65 20 41  PI3REF:  Close A
1c2d0 20 42 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a   BLOB Handle.**.
1c2e0 2a 2a 20 43 6c 6f 73 65 20 61 6e 20 6f 70 65 6e  ** Close an open
1c2f0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
1c300 20 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a   blob handle]..*
1c310 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
1c320 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  ob_close(sqlite3
1c330 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _blob *);../*.**
1c340 20 43 41 50 49 33 52 45 46 3a 20 20 52 65 74 75   CAPI3REF:  Retu
1c350 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41  rn The Size Of A
1c360 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a  n Open BLOB.**.*
1c370 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
1c380 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68  e in bytes of th
1c390 65 20 62 6c 6f 62 20 61 63 63 65 73 73 69 62 6c  e blob accessibl
1c3a0 65 20 76 69 61 20 74 68 65 20 6f 70 65 6e 20 0a  e via the open .
1c3b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
1c3c0 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20   | blob-handle] 
1c3d0 70 61 73 73 65 64 20 61 73 20 61 6e 20 61 72 67  passed as an arg
1c3e0 75 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ument..*/.int sq
1c3f0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
1c400 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29  (sqlite3_blob *)
1c410 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c420 46 3a 20 20 52 65 61 64 20 44 61 74 61 20 46 72  F:  Read Data Fr
1c430 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d  om A BLOB Increm
1c440 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68  entally.**.** Th
1c450 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
1c460 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61  sed to read data
1c470 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a   from an open .*
1c480 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  * [sqlite3_blob 
1c490 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 69  | blob-handle] i
1c4a0 6e 74 6f 20 61 20 63 61 6c 6c 65 72 20 73 75 70  nto a caller sup
1c4b0 70 6c 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a  plied buffer..**
1c4c0 20 6e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61   n bytes of data
1c4d0 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
1c4e0 20 62 75 66 66 65 72 0a 2a 2a 20 7a 20 66 72 6f   buffer.** z fro
1c4f0 6d 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c  m the open blob,
1c500 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66   starting at off
1c510 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a  set iOffset..**.
1c520 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53  ** On success, S
1c530 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
1c540 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c  rned. Otherwise,
1c550 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   an .** [SQLITE_
1c560 45 52 52 4f 52 20 7c 20 53 51 4c 69 74 65 20 65  ERROR | SQLite e
1c570 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e  rror code] or an
1c580 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
1c590 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
1c5a0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
1c5b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e   returned..*/.in
1c5c0 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72  t sqlite3_blob_r
1c5d0 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ead(sqlite3_blob
1c5e0 20 2a 2c 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74   *, void *z, int
1c5f0 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29   n, int iOffset)
1c600 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c610 46 3a 20 20 57 72 69 74 65 20 44 61 74 61 20 49  F:  Write Data I
1c620 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65  nto A BLOB Incre
1c630 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54  mentally.**.** T
1c640 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
1c650 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61  used to write da
1c660 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20  ta into an open 
1c670 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
1c680 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d  b | blob-handle]
1c690 20 66 72 6f 6d 20 61 20 75 73 65 72 20 73 75 70   from a user sup
1c6a0 70 6c 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a  plied buffer..**
1c6b0 20 6e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61   n bytes of data
1c6c0 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d   are copied from
1c6d0 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 70   the buffer.** p
1c6e0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 7a 20 69  ointed to by z i
1c6f0 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f  nto the open blo
1c700 62 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f  b, starting at o
1c710 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a  ffset iOffset..*
1c720 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
1c730 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62  ite3_blob | blob
1c740 2d 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20  -handle] passed 
1c750 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
1c760 75 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 6e 6f 74  ument.** was not
1c770 20 6f 70 65 6e 65 64 20 66 6f 72 20 77 72 69 74   opened for writ
1c780 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20 70  ing (the flags p
1c790 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1c7a0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
1c7b0 5d 0a 2a 2a 2a 20 77 61 73 20 7a 65 72 6f 29 2c  ].*** was zero),
1c7c0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
1c7d0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
1c7e0 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20  EADONLY]..**.** 
1c7f0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
1c800 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68  y only modify th
1c810 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68  e contents of th
1c820 65 20 62 6c 6f 62 2c 20 69 74 20 69 73 0a 2a 2a  e blob, it is.**
1c830 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
1c840 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 69   increase the si
1c850 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 75 73 69  ze of a blob usi
1c860 6e 67 20 74 68 69 73 20 41 50 49 2e 20 49 66 0a  ng this API. If.
1c870 2a 2a 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  ** offset iOffse
1c880 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6e  t is less than n
1c890 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20   bytes from the 
1c8a0 65 6e 64 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c  end of the blob,
1c8b0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
1c8c0 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
1c8d0 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77  and no data is w
1c8e0 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  ritten..**.** On
1c8f0 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45   success, SQLITE
1c900 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
1c910 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 0a   Otherwise, an .
1c920 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
1c930 20 7c 20 53 51 4c 69 74 65 20 65 72 72 6f 72 20   | SQLite error 
1c940 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
1c950 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
1c960 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72 72  D | extended err
1c970 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
1c980 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rned..*/.int sql
1c990 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
1c9a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20  sqlite3_blob *, 
1c9b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69  const void *z, i
1c9c0 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65  nt n, int iOffse
1c9d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f 20  t);../*.** Undo 
1c9e0 74 68 65 20 68 61 63 6b 20 74 68 61 74 20 63 6f  the hack that co
1c9f0 6e 76 65 72 74 73 20 66 6c 6f 61 74 69 6e 67 20  nverts floating 
1ca00 70 6f 69 6e 74 20 74 79 70 65 73 20 74 6f 20 69  point types to i
1ca10 6e 74 65 67 65 72 20 66 6f 72 0a 2a 2a 20 62 75  nteger for.** bu
1ca20 69 6c 64 73 20 6f 6e 20 70 72 6f 63 65 73 73 6f  ilds on processo
1ca30 72 73 20 77 69 74 68 6f 75 74 20 66 6c 6f 61 74  rs without float
1ca40 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
1ca50 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  t..*/.#ifdef SQL
1ca60 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e  ITE_OMIT_FLOATIN
1ca70 47 5f 50 4f 49 4e 54 0a 23 20 75 6e 64 65 66 20  G_POINT.# undef 
1ca80 64 6f 75 62 6c 65 0a 23 65 6e 64 69 66 0a 0a 23  double.#endif..#
1ca90 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75  ifdef __cplusplu
1caa0 73 0a 7d 20 20 2f 2a 20 45 6e 64 20 6f 66 20 74  s.}  /* End of t
1cab0 68 65 20 27 65 78 74 65 72 6e 20 22 43 22 27 20  he 'extern "C"' 
1cac0 62 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 66 0a  block */.#endif.
1cad0 23 65 6e 64 69 66 0a                             #endif.