/ Hex Artifact Content
Login

Artifact ae6c0ed88f601119c15de964b7b4b2f8c9b05831:


0000: 73 65 74 20 72 63 73 69 64 20 7b 24 49 64 3a 20  set rcsid {$Id: 
0010: 63 61 70 69 33 72 65 66 2e 74 63 6c 2c 76 20 31  capi3ref.tcl,v 1
0020: 2e 35 20 32 30 30 34 2f 30 36 2f 31 39 20 30 38  .5 2004/06/19 08
0030: 3a 31 38 3a 32 37 20 64 61 6e 69 65 6c 6b 31 39  :18:27 danielk19
0040: 37 37 20 45 78 70 20 24 7d 0a 73 6f 75 72 63 65  77 Exp $}.source
0050: 20 63 6f 6d 6d 6f 6e 2e 74 63 6c 0a 68 65 61 64   common.tcl.head
0060: 65 72 20 7b 43 2f 43 2b 2b 20 49 6e 74 65 72 66  er {C/C++ Interf
0070: 61 63 65 20 46 6f 72 20 53 51 4c 69 74 65 20 56  ace For SQLite V
0080: 65 72 73 69 6f 6e 20 33 7d 0a 70 75 74 73 20 7b  ersion 3}.puts {
0090: 0a 3c 68 32 3e 43 2f 43 2b 2b 20 49 6e 74 65 72  .<h2>C/C++ Inter
00a0: 66 61 63 65 20 46 6f 72 20 53 51 4c 69 74 65 20  face For SQLite 
00b0: 56 65 72 73 69 6f 6e 20 33 3c 2f 68 32 3e 0a 7d  Version 3</h2>.}
00c0: 0a 0a 70 72 6f 63 20 61 70 69 20 7b 6e 61 6d 65  ..proc api {name
00d0: 20 70 72 6f 74 6f 74 79 70 65 20 64 65 73 63 20   prototype desc 
00e0: 7b 6e 6f 74 75 73 65 64 20 78 7d 7d 20 7b 0a 20  {notused x}} {. 
00f0: 20 67 6c 6f 62 61 6c 20 61 70 69 6c 69 73 74 0a   global apilist.
0100: 20 20 69 66 20 7b 24 6e 61 6d 65 3d 3d 22 22 7d    if {$name==""}
0110: 20 7b 0a 20 20 20 20 72 65 67 73 75 62 20 2d 61   {.    regsub -a
0120: 6c 6c 20 7b 73 71 6c 69 74 65 33 5f 5b 61 2d 7a  ll {sqlite3_[a-z
0130: 30 2d 39 5f 5d 2b 5c 28 7d 20 24 70 72 6f 74 6f  0-9_]+\(} $proto
0140: 74 79 70 65 20 5c 0a 20 20 20 20 20 20 7b 5b 6c  type \.      {[l
0150: 61 70 70 65 6e 64 20 6e 61 6d 65 20 5b 73 74 72  append name [str
0160: 69 6e 67 20 74 72 69 6d 72 69 67 68 74 20 26 20  ing trimright & 
0170: 28 5d 5d 7d 20 78 31 0a 20 20 20 20 73 75 62 73  (]]} x1.    subs
0180: 74 20 24 78 31 0a 20 20 7d 0a 20 20 6c 61 70 70  t $x1.  }.  lapp
0190: 65 6e 64 20 61 70 69 6c 69 73 74 20 5b 6c 69 73  end apilist [lis
01a0: 74 20 24 6e 61 6d 65 20 24 70 72 6f 74 6f 74 79  t $name $prototy
01b0: 70 65 20 24 64 65 73 63 5d 0a 7d 0a 0a 61 70 69  pe $desc].}..api
01c0: 20 7b 72 65 73 75 6c 74 2d 63 6f 64 65 73 7d 20   {result-codes} 
01d0: 7b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  {.#define SQLITE
01e0: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
01f0: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
0200: 72 65 73 75 6c 74 20 2a 2f 0a 23 64 65 66 69 6e  result */.#defin
0210: 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20  e SQLITE_ERROR  
0220: 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c        1   /* SQL
0230: 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e   error or missin
0240: 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  g database */.#d
0250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
0260: 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a  ERNAL     2   /*
0270: 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6c 6f 67   An internal log
0280: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
0290: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
02a0: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
02b0: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
02c0: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
02d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
02e0: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
02f0: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
0300: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
0310: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
0320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
0330: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
0340: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
0350: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
0360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0370: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
0380: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
0390: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
03a0: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
03b0: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
03c0: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
03d0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
03e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
03f0: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
0400: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
0410: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
0420: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
0430: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
0440: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
0450: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
0460: 74 65 64 20 62 79 20 73 71 6c 69 74 65 5f 69 6e  ted by sqlite_in
0470: 74 65 72 72 75 70 74 28 29 20 2a 2f 0a 23 64 65  terrupt() */.#de
0480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
0490: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
04a0: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
04b0: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
04c0: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
04d0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
04e0: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
04f0: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
0500: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
0510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0520: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
0530: 20 20 20 2f 2a 20 28 49 6e 74 65 72 6e 61 6c 20     /* (Internal 
0540: 4f 6e 6c 79 29 20 54 61 62 6c 65 20 6f 72 20 72  Only) Table or r
0550: 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20  ecord not found 
0560: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0570: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33  E_FULL        13
0580: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20     /* Insertion 
0590: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64  failed because d
05a0: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20  atabase is full 
05b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
05c0: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34  E_CANTOPEN    14
05d0: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20     /* Unable to 
05e0: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
05f0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
0600: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f  e SQLITE_PROTOCO
0610: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74  L    15   /* Dat
0620: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
0630: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
0640: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
0650: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
0660: 28 49 6e 74 65 72 6e 61 6c 20 4f 6e 6c 79 29 20  (Internal Only) 
0670: 44 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 69  Database table i
0680: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
0690: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
06a0: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
06b0: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
06c0: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
06d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
06e0: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
06f0: 54 6f 6f 20 6d 75 63 68 20 64 61 74 61 20 66 6f  Too much data fo
0700: 72 20 6f 6e 65 20 72 6f 77 20 6f 66 20 61 20 74  r one row of a t
0710: 61 62 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  able */.#define 
0720: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
0730: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
0740: 20 64 75 65 20 74 6f 20 63 6f 6e 74 72 61 69 6e   due to contrain
0750: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23  t violation */.#
0760: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
0770: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f  SMATCH    20   /
0780: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d  * Data type mism
0790: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20  atch */.#define 
07a0: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20  SQLITE_MISUSE   
07b0: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61     21   /* Libra
07c0: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63  ry used incorrec
07d0: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tly */.#define S
07e0: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20  QLITE_NOLFS     
07f0: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f    22   /* Uses O
0800: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73  S features not s
0810: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74  upported on host
0820: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
0830: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32  TE_AUTH        2
0840: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61  3   /* Authoriza
0850: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  tion denied */.#
0860: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f  define SQLITE_RO
0870: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f  W         100  /
0880: 2a 20 73 71 6c 69 74 65 5f 73 74 65 70 28 29 20  * sqlite_step() 
0890: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  has another row 
08a0: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ready */.#define
08b0: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20   SQLITE_DONE    
08c0: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69      101  /* sqli
08d0: 74 65 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  te_step() has fi
08e0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
08f0: 20 2a 2f 0a 7d 20 7b 0a 4d 61 6e 79 20 53 51 4c   */.} {.Many SQL
0900: 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ite functions re
0910: 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20  turn an integer 
0920: 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d  result code from
0930: 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 61   the set shown.a
0940: 62 6f 76 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  bove in order to
0950: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
0960: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 7d  ss or failure..}
0970: 0a 0a 61 70 69 20 7b 7d 20 7b 0a 20 20 76 6f 69  ..api {} {.  voi
0980: 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
0990: 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
09a0: 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
09b0: 6e 74 20 6e 42 79 74 65 73 29 3b 0a 7d 20 7b 0a  nt nBytes);.} {.
09c0: 20 20 41 67 67 72 65 67 61 74 65 20 66 75 6e 63    Aggregate func
09d0: 74 69 6f 6e 73 20 75 73 65 20 74 68 65 20 66 6f  tions use the fo
09e0: 6c 6c 6f 77 69 6e 67 20 72 6f 75 74 69 6e 65 20  llowing routine 
09f0: 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 20 20 61 20  to allocate.  a 
0a00: 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 74  structure for st
0a10: 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
0a20: 65 2e 20 20 54 68 65 20 66 69 72 73 74 20 74 69  e.  The first ti
0a30: 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  me this routine.
0a40: 20 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20    is called for 
0a50: 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
0a60: 72 65 67 61 74 65 2c 20 61 20 6e 65 77 20 73 74  regate, a new st
0a70: 72 75 63 74 75 72 65 20 6f 66 20 73 69 7a 65 20  ructure of size 
0a80: 6e 42 79 74 65 73 0a 20 20 69 73 20 61 6c 6c 6f  nBytes.  is allo
0a90: 63 61 74 65 64 2c 20 7a 65 72 6f 65 64 2c 20 61  cated, zeroed, a
0aa0: 6e 64 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 6e  nd returned.  On
0ab0: 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
0ac0: 73 20 28 66 6f 72 20 74 68 65 0a 20 20 73 61 6d  s (for the.  sam
0ad0: 65 20 61 67 67 72 65 67 61 74 65 20 69 6e 73 74  e aggregate inst
0ae0: 61 6e 63 65 29 20 74 68 65 20 73 61 6d 65 20 62  ance) the same b
0af0: 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65  uffer is returne
0b00: 64 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  d.  The implemen
0b10: 74 61 74 69 6f 6e 0a 20 20 6f 66 20 74 68 65 20  tation.  of the 
0b20: 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 75 73  aggregate can us
0b30: 65 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 62  e the returned b
0b40: 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c  uffer to accumul
0b50: 61 74 65 20 64 61 74 61 2e 0a 0a 20 20 54 68 65  ate data...  The
0b60: 20 62 75 66 66 65 72 20 61 6c 6c 6f 63 61 74 65   buffer allocate
0b70: 64 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  d is freed autom
0b80: 61 74 69 63 61 6c 6c 79 20 62 79 20 53 51 4c 69  atically by SQLi
0b90: 74 65 2e 0a 7d 0a 0a 61 70 69 20 7b 7d 20 7b 0a  te..}..api {} {.
0ba0: 20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67    int sqlite3_ag
0bb0: 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
0bc0: 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
0bd0: 0a 7d 20 7b 0a 20 20 54 68 65 20 6e 65 78 74 20  .} {.  The next 
0be0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
0bf0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61  the number of ca
0c00: 6c 6c 73 20 74 6f 20 78 53 74 65 70 20 66 6f 72  lls to xStep for
0c10: 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 20 20   a particular.  
0c20: 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
0c30: 6f 6e 20 69 6e 73 74 61 6e 63 65 2e 20 20 54 68  on instance.  Th
0c40: 65 20 63 75 72 72 65 6e 74 20 63 61 6c 6c 20 74  e current call t
0c50: 6f 20 78 53 74 65 70 20 63 6f 75 6e 74 73 20 73  o xStep counts s
0c60: 6f 20 74 68 69 73 0a 20 20 72 6f 75 74 69 6e 65  o this.  routine
0c70: 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
0c80: 61 74 20 6c 65 61 73 74 20 31 2e 0a 7d 0a 0a 61  at least 1..}..a
0c90: 70 69 20 7b 7d 20 7b 0a 20 20 69 6e 74 20 73 71  pi {} {.  int sq
0ca0: 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
0cb0: 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
0cc0: 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
0cd0: 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
0ce0: 76 6f 69 64 2a 29 29 3b 0a 20 20 69 6e 74 20 73  void*));.  int s
0cf0: 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
0d00: 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
0d10: 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
0d20: 20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69    int sqlite3_bi
0d30: 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
0d40: 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
0d50: 0a 20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  .  int sqlite3_b
0d60: 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
0d70: 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 6c 6f  3_stmt*, int, lo
0d80: 6e 67 20 6c 6f 6e 67 20 69 6e 74 29 3b 0a 20 20  ng long int);.  
0d90: 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
0da0: 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
0db0: 6d 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  mt*, int);.  int
0dc0: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
0dd0: 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
0de0: 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
0df0: 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  r*, int n, void(
0e00: 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 20 20 69 6e  *)(void*));.  in
0e10: 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
0e20: 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
0e30: 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
0e40: 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
0e50: 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 20  id(*)(void*));. 
0e60: 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f   #define SQLITE_
0e70: 53 54 41 54 49 43 20 20 20 20 20 20 28 28 76 6f  STATIC      ((vo
0e80: 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 29 30 29  id(*)(void *))0)
0e90: 0a 20 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54  .  #define SQLIT
0ea0: 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
0eb0: 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 29  void(*)(void *))
0ec0: 2d 31 29 0a 7d 20 7b 0a 20 49 6e 20 74 68 65 20  -1).} {. In the 
0ed0: 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75  SQL strings inpu
0ee0: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 65  t to sqlite3_pre
0ef0: 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
0f00: 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 2c 0a  e3_prepare16(),.
0f10: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6c 69 74   one or more lit
0f20: 65 72 61 6c 73 20 63 61 6e 20 62 65 20 72 65 70  erals can be rep
0f30: 6c 61 63 65 20 62 79 20 61 20 77 69 6c 64 63 61  lace by a wildca
0f40: 72 64 20 22 3f 22 20 6f 72 20 22 3a 4e 3a 22 20  rd "?" or ":N:" 
0f50: 77 68 65 72 65 0a 20 4e 20 69 73 20 61 6e 20 69  where. N is an i
0f60: 6e 74 65 67 65 72 2e 20 20 54 68 65 20 76 61 6c  nteger.  The val
0f70: 75 65 20 6f 66 20 74 68 65 73 65 20 77 69 6c 64  ue of these wild
0f80: 63 61 72 64 20 6c 69 74 65 72 61 6c 73 20 63 61  card literals ca
0f90: 6e 20 62 65 20 73 65 74 0a 20 75 73 69 6e 67 20  n be set. using 
0fa0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
0fb0: 0a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  . The first para
0fc0: 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
0fd0: 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
0fe0: 33 5f 73 74 6d 74 0a 20 73 74 72 75 63 74 75 72  3_stmt. structur
0ff0: 65 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  e returned from 
1000: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1010: 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  ).  The second p
1020: 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
1030: 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 77 69   index of the wi
1040: 6c 64 63 61 72 64 2e 20 20 54 68 65 20 66 69 72  ldcard.  The fir
1050: 73 74 20 22 3f 22 20 68 61 73 20 61 6e 20 69 6e  st "?" has an in
1060: 64 65 78 20 6f 66 20 31 2e 20 20 22 3a 4e 3a 22  dex of 1.  ":N:"
1070: 20 77 69 6c 64 63 61 72 64 73 0a 20 75 73 65 20   wildcards. use 
1080: 74 68 65 20 69 6e 64 65 78 20 4e 2e 0a 0a 20 54  the index N... T
1090: 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
10a0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
10b0: 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  nd_blob(), sqlit
10c0: 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
10d0: 61 6e 64 0a 20 73 71 6c 69 74 65 33 5f 62 69 6e  and. sqlite3_bin
10e0: 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
10f0: 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
1100: 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
1110: 65 20 42 4c 4f 42 20 6f 72 0a 20 74 65 78 74 20  e BLOB or. text 
1120: 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
1130: 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
1140: 74 2e 20 20 49 66 20 74 68 65 20 66 69 66 74 68  t.  If the fifth
1150: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1160: 0a 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  . special value 
1170: 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
1180: 68 65 6e 20 74 68 65 20 6c 69 62 72 61 72 79 20  hen the library 
1190: 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
11a0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 20 69 73   information. is
11b0: 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
11c0: 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
11d0: 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
11e0: 20 62 65 20 66 72 65 65 64 2e 20 20 49 66 20 74   be freed.  If t
11f0: 68 65 0a 20 66 69 66 74 68 20 61 72 67 75 6d 65  he. fifth argume
1200: 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
1210: 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
1220: 54 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  T, then SQLite m
1230: 61 6b 65 73 20 69 74 73 0a 20 6f 77 6e 20 70 72  akes its. own pr
1240: 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
1250: 65 20 64 61 74 61 2e 0a 0a 20 54 68 65 20 73 71  e data... The sq
1260: 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1270: 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
1280: 61 6c 6c 65 64 20 61 66 74 65 72 0a 20 73 71 6c  alled after. sql
1290: 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 6f  ite3_prepare() o
12a0: 72 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  r sqlite3_reset(
12b0: 29 20 61 6e 64 20 62 65 66 6f 72 65 20 73 71 6c  ) and before sql
12c0: 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 20 42 69  ite3_step().. Bi
12d0: 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 72  ndings are not r
12e0: 65 73 65 74 20 62 79 20 74 68 65 20 73 71 6c 69  eset by the sqli
12f0: 74 65 33 5f 72 65 73 65 74 28 29 20 72 6f 75 74  te3_reset() rout
1300: 69 6e 65 2e 0a 20 55 6e 62 6f 75 6e 64 20 77 69  ine.. Unbound wi
1310: 6c 64 63 61 72 64 73 20 61 72 65 20 69 6e 74 65  ldcards are inte
1320: 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
1330: 0a 7d 0a 0a 61 70 69 20 7b 7d 20 7b 0a 20 20 69  .}..api {} {.  i
1340: 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
1350: 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 2a 2c  handler(sqlite*,
1360: 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
1370: 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 7d 20 7b 0a  t), void*);.} {.
1380: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 64   This routine id
1390: 65 6e 74 69 66 69 65 73 20 61 20 63 61 6c 6c 62  entifies a callb
13a0: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
13b0: 74 20 69 73 20 69 6e 76 6f 6b 65 64 0a 20 77 68  t is invoked. wh
13c0: 65 6e 65 76 65 72 20 61 6e 20 61 74 74 65 6d 70  enever an attemp
13d0: 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
13e0: 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
13f0: 6c 65 20 74 68 61 74 20 69 73 0a 20 63 75 72 72  le that is. curr
1400: 65 6e 74 6c 79 20 6c 6f 63 6b 65 64 20 62 79 20  ently locked by 
1410: 61 6e 6f 74 68 65 72 20 70 72 6f 63 65 73 73 20  another process 
1420: 6f 72 20 74 68 72 65 61 64 2e 20 20 49 66 20 74  or thread.  If t
1430: 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1440: 0a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  . is NULL, then 
1450: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72  sqlite3_exec() r
1460: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 42 55  eturns SQLITE_BU
1470: 53 59 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 69  SY immediately i
1480: 66 0a 20 69 74 20 66 69 6e 64 73 20 61 20 6c 6f  f. it finds a lo
1490: 63 6b 65 64 20 74 61 62 6c 65 2e 20 20 49 66 20  cked table.  If 
14a0: 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
14b0: 6b 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  k is not NULL, t
14c0: 68 65 6e 0a 20 73 71 6c 69 74 65 33 5f 65 78 65  hen. sqlite3_exe
14d0: 63 28 29 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  c() invokes the 
14e0: 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 74 77  callback with tw
14f0: 6f 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  o arguments.  Th
1500: 65 0a 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  e. second argume
1510: 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
1520: 20 6f 66 20 70 72 69 6f 72 20 63 61 6c 6c 73 20   of prior calls 
1530: 74 6f 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  to the busy call
1540: 62 61 63 6b 0a 20 66 6f 72 20 74 68 65 20 73 61  back. for the sa
1550: 6d 65 20 6c 6f 63 6b 2e 20 20 49 66 20 74 68 65  me lock.  If the
1560: 0a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  . busy callback 
1570: 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
1580: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
1590: 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75 72  mmediately retur
15a0: 6e 73 0a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  ns. SQLITE_BUSY.
15b0: 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63    If the callbac
15c0: 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
15d0: 72 6f 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ro, then sqlite3
15e0: 5f 65 78 65 63 28 29 0a 20 74 72 69 65 73 20 74  _exec(). tries t
15f0: 6f 20 6f 70 65 6e 20 74 68 65 20 74 61 62 6c 65  o open the table
1600: 20 61 67 61 69 6e 20 61 6e 64 20 74 68 65 20 63   again and the c
1610: 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 0a 20  ycle repeats... 
1620: 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
1630: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1640: 4c 2e 0a 0a 20 53 71 6c 69 74 65 20 69 73 20 72  L... Sqlite is r
1650: 65 2d 65 6e 74 72 61 6e 74 2c 20 73 6f 20 74 68  e-entrant, so th
1660: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  e busy handler m
1670: 61 79 20 73 74 61 72 74 20 61 20 6e 65 77 20 71  ay start a new q
1680: 75 65 72 79 2e 20 0a 20 28 49 74 20 69 73 20 6e  uery. . (It is n
1690: 6f 74 20 63 6c 65 61 72 20 77 68 79 20 61 6e 79  ot clear why any
16a0: 6f 6e 65 20 77 6f 75 6c 64 20 65 76 65 72 79 20  one would every 
16b0: 77 61 6e 74 20 74 6f 20 64 6f 20 74 68 69 73 2c  want to do this,
16c0: 20 62 75 74 20 69 74 0a 20 69 73 20 61 6c 6c 6f   but it. is allo
16d0: 77 65 64 2c 20 69 6e 20 74 68 65 6f 72 79 2e 29  wed, in theory.)
16e0: 20 20 42 75 74 20 74 68 65 20 62 75 73 79 20 68    But the busy h
16f0: 61 6e 64 6c 65 72 20 6d 61 79 20 6e 6f 74 20 63  andler may not c
1700: 6c 6f 73 65 20 74 68 65 0a 20 64 61 74 61 62 61  lose the. databa
1710: 73 65 2e 20 20 43 6c 6f 73 69 6e 67 20 74 68 65  se.  Closing the
1720: 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 61   database from a
1730: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77 69   busy handler wi
1740: 6c 6c 20 64 65 6c 65 74 65 20 0a 20 64 61 74 61  ll delete . data
1750: 20 73 74 72 75 63 74 75 72 65 73 20 6f 75 74 20   structures out 
1760: 66 72 6f 6d 20 75 6e 64 65 72 20 74 68 65 20 65  from under the e
1770: 78 65 63 75 74 69 6e 67 20 71 75 65 72 79 20 61  xecuting query a
1780: 6e 64 20 77 69 6c 6c 20 0a 20 70 72 6f 62 61 62  nd will . probab
1790: 6c 79 20 72 65 73 75 6c 74 20 69 6e 20 61 20 63  ly result in a c
17a0: 6f 72 65 64 75 6d 70 2e 0a 7d 0a 0a 61 70 69 20  oredump..}..api 
17b0: 7b 7d 20 7b 0a 20 20 69 6e 74 20 73 71 6c 69 74  {} {.  int sqlit
17c0: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
17d0: 73 71 6c 69 74 65 2a 2c 20 69 6e 74 20 6d 73 29  sqlite*, int ms)
17e0: 3b 0a 7d 20 7b 0a 20 54 68 69 73 20 72 6f 75 74  ;.} {. This rout
17f0: 69 6e 65 20 73 65 74 73 20 61 20 62 75 73 79 20  ine sets a busy 
1800: 68 61 6e 64 6c 65 72 20 74 68 61 74 20 73 6c 65  handler that sle
1810: 65 70 73 20 66 6f 72 20 61 20 77 68 69 6c 65 20  eps for a while 
1820: 77 68 65 6e 20 61 0a 20 74 61 62 6c 65 20 69 73  when a. table is
1830: 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61   locked.  The ha
1840: 6e 64 6c 65 72 20 77 69 6c 6c 20 73 6c 65 65 70  ndler will sleep
1850: 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
1860: 75 6e 74 69 6c 20 0a 20 61 74 20 6c 65 61 73 74  until . at least
1870: 20 22 6d 73 22 20 6d 69 6c 6c 65 73 65 63 6f 6e   "ms" millesecon
1880: 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 20 68  ds of sleeping h
1890: 61 76 65 20 62 65 65 6e 20 64 6f 6e 65 2e 20 20  ave been done.  
18a0: 41 66 74 65 72 0a 20 22 6d 73 22 20 6d 69 6c 6c  After. "ms" mill
18b0: 65 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  eseconds of slee
18c0: 70 69 6e 67 2c 20 74 68 65 20 68 61 6e 64 6c 65  ping, the handle
18d0: 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
18e0: 68 0a 20 63 61 75 73 65 73 20 73 71 6c 69 74 65  h. causes sqlite
18f0: 33 5f 65 78 65 63 28 29 20 74 6f 20 72 65 74 75  3_exec() to retu
1900: 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a  rn SQLITE_BUSY..
1910: 0a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72  . Calling this r
1920: 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
1930: 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
1940: 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
1950: 72 6f 0a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  ro. turns off al
1960: 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
1970: 0a 7d 0a 0a 61 70 69 20 7b 7d 20 7b 0a 20 20 69  .}..api {} {.  i
1980: 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
1990: 65 73 28 73 71 6c 69 74 65 2a 29 3b 0a 7d 20 7b  es(sqlite*);.} {
19a0: 0a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  . This function 
19b0: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
19c0: 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72  er of database r
19d0: 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68  ows that were ch
19e0: 61 6e 67 65 64 0a 20 28 6f 72 20 69 6e 73 65 72  anged. (or inser
19f0: 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 29 20  ted or deleted) 
1a00: 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
1a10: 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 0a 20  ntly completed. 
1a20: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
1a30: 6f 72 20 44 45 4c 45 54 45 0a 20 73 74 61 74 65  or DELETE. state
1a40: 6d 65 6e 74 2e 20 20 4f 6e 6c 79 20 63 68 61 6e  ment.  Only chan
1a50: 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
1a60: 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
1a70: 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 0a 20  by the INSERT,. 
1a80: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
1a90: 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20  E statement are 
1aa0: 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69  counted.  Auxili
1ab0: 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
1ac0: 65 64 20 62 79 0a 20 74 72 69 67 67 65 72 73 20  ed by. triggers 
1ad0: 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1ae0: 20 20 55 73 65 20 74 68 65 20 73 71 6c 69 74 65    Use the sqlite
1af0: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1b00: 29 20 66 75 6e 63 74 69 6f 6e 0a 20 74 6f 20 66  ) function. to f
1b10: 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  ind the total nu
1b20: 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
1b30: 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
1b40: 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
1b50: 67 65 72 73 2e 0a 0a 20 57 69 74 68 69 6e 20 74  gers... Within t
1b60: 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
1b70: 67 67 65 72 2c 20 74 68 65 20 73 71 6c 69 74 65  gger, the sqlite
1b80: 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
1b90: 74 69 6f 6e 20 64 6f 65 73 20 77 6f 72 6b 0a 20  tion does work. 
1ba0: 74 6f 20 72 65 70 6f 72 74 20 74 68 65 20 6e 75  to report the nu
1bb0: 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 74 68 61  mber of rows tha
1bc0: 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 20 66  t were changed f
1bd0: 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
1be0: 6e 74 6c 79 0a 20 63 6f 6d 70 6c 65 74 65 64 20  ntly. completed 
1bf0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
1c00: 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1c10: 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 74  ent within the t
1c20: 72 69 67 67 65 72 20 62 6f 64 79 2e 0a 0a 20 53  rigger body... S
1c30: 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
1c40: 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45   the command "DE
1c50: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
1c60: 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45   without a WHERE
1c70: 20 63 6c 61 75 73 65 0a 20 62 79 20 64 72 6f 70   clause. by drop
1c80: 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74  ping and recreat
1c90: 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20  ing the table.  
1ca0: 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61  (This is much fa
1cb0: 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a  ster than going.
1cc0: 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c   through and del
1cd0: 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c  eting individual
1ce0: 20 65 6c 65 6d 65 6e 74 73 20 66 6f 72 6d 20 74   elements form t
1cf0: 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61  he table.)  Beca
1d00: 75 73 65 20 6f 66 0a 20 74 68 69 73 20 6f 70 74  use of. this opt
1d10: 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63  imization, the c
1d20: 68 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72 20  hange count for 
1d30: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
1d40: 6c 65 22 20 77 69 6c 6c 20 62 65 0a 20 7a 65 72  le" will be. zer
1d50: 6f 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  o regardless of 
1d60: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c  the number of el
1d70: 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65  ements that were
1d80: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74   originally in t
1d90: 68 65 0a 20 74 61 62 6c 65 2e 20 54 6f 20 67 65  he. table. To ge
1da0: 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f  t an accurate co
1db0: 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
1dc0: 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65  r of rows delete
1dd0: 64 2c 20 75 73 65 0a 20 22 44 45 4c 45 54 45 20  d, use. "DELETE 
1de0: 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45  FROM table WHERE
1df0: 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 7d 0a 0a   1" instead..}..
1e00: 61 70 69 20 7b 7d 20 7b 0a 20 20 69 6e 74 20 73  api {} {.  int s
1e10: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1e20: 6e 67 65 73 28 73 71 6c 69 74 65 2a 29 3b 0a 7d  nges(sqlite*);.}
1e30: 20 7b 0a 20 20 54 68 69 73 20 66 75 6e 63 74 69   {.  This functi
1e40: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  on returns the t
1e50: 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 64  otal number of d
1e60: 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
1e70: 74 20 68 61 76 65 0a 20 20 62 65 20 6d 6f 64 69  t have.  be modi
1e80: 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 2c 20  fied, inserted, 
1e90: 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65  or deleted since
1ea0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1eb0: 6e 6e 65 63 74 69 6f 6e 20 77 61 73 0a 20 20 63  nnection was.  c
1ec0: 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c  reated using sql
1ed0: 69 74 65 33 5f 6f 70 65 6e 28 29 2e 20 20 41 6c  ite3_open().  Al
1ee0: 6c 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  l changes are co
1ef0: 75 6e 74 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67  unted, including
1f00: 0a 20 20 63 68 61 6e 67 65 73 20 62 79 20 74 72  .  changes by tr
1f10: 69 67 67 65 72 73 20 61 6e 64 20 63 68 61 6e 67  iggers and chang
1f20: 65 73 20 74 6f 20 54 45 4d 50 20 61 6e 64 20 61  es to TEMP and a
1f30: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
1f40: 65 73 2e 0a 20 20 45 78 63 65 70 74 2c 20 63 68  es..  Except, ch
1f50: 61 6e 67 65 73 20 74 6f 20 74 68 65 20 53 51 4c  anges to the SQL
1f60: 49 54 45 5f 4d 41 53 54 45 52 20 74 61 62 6c 65  ITE_MASTER table
1f70: 20 28 63 61 75 73 65 64 20 62 79 20 73 74 61 74   (caused by stat
1f80: 65 6d 65 6e 74 73 20 0a 20 20 73 75 63 68 20 61  ements .  such a
1f90: 73 20 43 52 45 41 54 45 20 54 41 42 4c 45 29 20  s CREATE TABLE) 
1fa0: 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1fb0: 20 20 4e 6f 72 20 61 72 65 20 63 68 61 6e 67 65    Nor are change
1fc0: 73 20 63 6f 75 6e 74 65 64 20 77 68 65 6e 0a 20  s counted when. 
1fd0: 20 61 6e 20 65 6e 74 69 72 65 20 74 61 62 6c 65   an entire table
1fe0: 20 69 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e   is deleted usin
1ff0: 67 20 44 52 4f 50 20 54 41 42 4c 45 2e 0a 0a 20  g DROP TABLE... 
2000: 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 73 71   See also the sq
2010: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
2020: 41 50 49 2e 0a 0a 20 20 53 51 4c 69 74 65 20 69  API...  SQLite i
2030: 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f  mplements the co
2040: 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52  mmand "DELETE FR
2050: 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75  OM table" withou
2060: 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65  t a WHERE clause
2070: 0a 20 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61  .  by dropping a
2080: 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68  nd recreating th
2090: 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20  e table.  (This 
20a0: 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74  is much faster t
20b0: 68 61 6e 20 67 6f 69 6e 67 0a 20 20 74 68 72 6f  han going.  thro
20c0: 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67  ugh and deleting
20d0: 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d   individual elem
20e0: 65 6e 74 73 20 66 6f 72 6d 20 74 68 65 20 74 61  ents form the ta
20f0: 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f  ble.)  Because o
2100: 66 0a 20 20 74 68 69 73 20 6f 70 74 69 6d 69 7a  f.  this optimiz
2110: 61 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67  ation, the chang
2120: 65 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c  e count for "DEL
2130: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
2140: 77 69 6c 6c 20 62 65 0a 20 20 7a 65 72 6f 20 72  will be.  zero r
2150: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
2160: 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65   number of eleme
2170: 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72  nts that were or
2180: 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a  iginally in the.
2190: 20 20 74 61 62 6c 65 2e 20 54 6f 20 67 65 74 20    table. To get 
21a0: 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e  an accurate coun
21b0: 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  t of the number 
21c0: 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c  of rows deleted,
21d0: 20 75 73 65 0a 20 20 22 44 45 4c 45 54 45 20 46   use.  "DELETE F
21e0: 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20  ROM table WHERE 
21f0: 31 22 20 69 6e 73 74 65 61 64 2e 0a 7d 0a 0a 61  1" instead..}..a
2200: 70 69 20 7b 7d 20 7b 0a 20 20 69 6e 74 20 73 71  pi {} {.  int sq
2210: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69  lite3_close(sqli
2220: 74 65 20 2a 29 3b 0a 7d 20 7b 0a 20 20 43 61 6c  te *);.} {.  Cal
2230: 6c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  l this function 
2240: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
2250: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
2260: 61 74 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c  at was previousl
2270: 79 0a 20 20 72 65 74 75 72 6e 65 64 20 66 72 6f  y.  returned fro
2280: 6d 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  m sqlite3_open()
2290: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
22a0: 31 36 28 29 0a 20 20 61 6e 64 20 74 68 65 20 63  16().  and the c
22b0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 64 61 74  orresponding dat
22c0: 61 62 61 73 65 20 77 69 6c 6c 20 62 79 20 63 6c  abase will by cl
22d0: 6f 73 65 64 2e 0a 0a 20 20 53 51 4c 49 54 45 5f  osed...  SQLITE_
22e0: 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  OK is returned i
22f0: 66 20 74 68 65 20 63 6c 6f 73 65 20 69 73 20 73  f the close is s
2300: 75 63 63 65 73 73 66 75 6c 2e 20 20 49 66 20 74  uccessful.  If t
2310: 68 65 72 65 20 61 72 65 0a 20 20 70 72 65 70 61  here are.  prepa
2320: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 74  red statements t
2330: 68 61 74 20 68 61 76 65 20 6e 6f 74 20 62 65 65  hat have not bee
2340: 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
2350: 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 0a 20 20  n SQLITE_BUSY.  
2360: 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 51  is returned.  SQ
2370: 4c 49 54 45 5f 45 52 52 4f 52 20 6d 69 67 68 74  LITE_ERROR might
2380: 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
2390: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
23a0: 6e 6f 74 0a 20 20 61 20 76 61 6c 69 64 20 63 6f  not.  a valid co
23b0: 6e 6e 65 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  nnection pointer
23c0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
23d0: 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 69  ite3_open() or i
23e0: 66 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  f the connection
23f0: 0a 20 20 70 6f 69 6e 74 65 72 20 68 61 73 20 62  .  pointer has b
2400: 65 65 6e 20 63 6c 6f 73 65 64 20 70 72 65 76 69  een closed previ
2410: 6f 75 73 6c 79 2e 0a 7d 0a 0a 61 70 69 20 7b 7d  ously..}..api {}
2420: 20 7b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73   {.const void *s
2430: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2440: 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2450: 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2460: 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2470: 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
2480: 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2490: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
24a0: 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
24b0: 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
24c0: 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
24d0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
24e0: 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
24f0: 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2500: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2510: 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2520: 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 6c 6f 6e  , int iCol);.lon
2530: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2540: 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
2550: 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2560: 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
2570: 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2580: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2590: 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
25a0: 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
25b0: 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
25c0: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
25d0: 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
25e0: 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
25f0: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2600: 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2610: 69 6e 74 20 69 43 6f 6c 29 3b 0a 23 64 65 66 69  int iCol);.#defi
2620: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
2630: 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
2640: 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
2650: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
2660: 58 54 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65  XT     3.#define
2670: 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
2680: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
2690: 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 7d 20 7b  E_NULL     5.} {
26a0: 0a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  . These routines
26b0: 20 72 65 74 75 72 6e 73 20 69 6e 66 6f 72 6d 61   returns informa
26c0: 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 69  tion about the i
26d0: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 20 69 6e 20 61  nformation. in a
26e0: 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
26f0: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65  f the current re
2700: 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
2710: 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 0a 20  ery.  In every. 
2720: 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 70  case the first p
2730: 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
2740: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  inter to the SQL
2750: 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
2760: 69 73 20 62 65 69 6e 67 0a 20 65 78 65 63 75 74  is being. execut
2770: 65 64 20 28 74 68 65 20 73 71 6c 69 74 65 5f 73  ed (the sqlite_s
2780: 74 6d 74 2a 20 74 68 61 74 20 77 61 73 20 72 65  tmt* that was re
2790: 74 75 72 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  turned from sqli
27a0: 74 65 33 5f 70 72 65 70 61 72 65 28 29 29 20 61  te3_prepare()) a
27b0: 6e 64 0a 20 74 68 65 20 73 65 63 6f 6e 64 20 61  nd. the second a
27c0: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
27d0: 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
27e0: 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
27f0: 6f 72 6d 61 74 69 6f 6e 20 0a 20 73 68 6f 75 6c  ormation . shoul
2800: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20  d be returned.  
2810: 69 43 6f 6c 20 69 73 20 7a 65 72 6f 2d 69 6e 64  iCol is zero-ind
2820: 65 78 65 64 2e 20 20 54 68 65 20 6c 65 66 74 2d  exed.  The left-
2830: 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 61 73 20 61  most column as a
2840: 6e 0a 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a 0a  n. index of 0...
2850: 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
2860: 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 63 75 72  ement is not cur
2870: 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
2880: 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
2890: 69 66 20 74 68 65 0a 20 74 68 65 20 63 6f 6c 75  if the. the colu
28a0: 6c 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  lmn index is out
28b0: 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
28c0: 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
28d0: 65 64 2e 0a 0a 20 54 68 65 73 65 20 72 6f 75 74  ed... These rout
28e0: 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
28f0: 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2900: 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
2910: 61 74 65 2e 20 20 46 6f 72 0a 20 65 78 61 6d 70  ate.  For. examp
2920: 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
2930: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
2940: 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
2950: 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 20 69  a text result. i
2960: 73 20 72 65 71 75 65 73 74 65 64 2c 20 73 70 72  s requested, spr
2970: 69 6e 74 66 28 29 20 69 73 20 75 73 65 64 20 69  intf() is used i
2980: 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 64 6f 20  nternally to do 
2990: 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 0a 20  the conversion. 
29a0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
29b0: 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
29c0: 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
29d0: 63 6f 6e 76 65 72 73 69 6f 6e 73 20 74 68 61 74  conversions that
29e0: 0a 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 0a  . are applied:..
29f0: 20 3c 74 61 62 6c 65 20 62 72 6f 64 65 72 3d 31   <table broder=1
2a00: 3e 0a 3c 74 72 3e 3c 74 68 3e 49 6e 74 65 72 6e  >.<tr><th>Intern
2a10: 61 6c 20 54 79 70 65 3c 2f 74 68 3e 3c 74 68 3e  al Type</th><th>
2a20: 52 65 71 75 65 73 74 65 64 20 54 79 70 65 3c 2f  Requested Type</
2a30: 74 68 3e 3c 74 68 3e 43 6f 6e 76 65 72 73 69 6f  th><th>Conversio
2a40: 6e 3c 2f 74 68 3e 3c 2f 74 72 3e 0a 3c 74 72 3e  n</th></tr>.<tr>
2a50: 3c 74 64 3e 20 4e 55 4c 4c 20 20 20 20 3c 2f 74  <td> NULL    </t
2a60: 64 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 3c 2f  d><td> INTEGER</
2a70: 74 64 3e 3c 74 64 3e 52 65 73 75 6c 74 20 69 73  td><td>Result is
2a80: 20 30 3c 2f 74 64 3e 3c 2f 74 72 3e 0a 3c 74 72   0</td></tr>.<tr
2a90: 3e 3c 74 64 3e 20 4e 55 4c 4c 20 3c 2f 74 64 3e  ><td> NULL </td>
2aa0: 3c 74 64 3e 20 20 20 20 46 4c 4f 41 54 20 3c 2f  <td>    FLOAT </
2ab0: 74 64 3e 3c 74 64 3e 20 52 65 73 75 6c 74 20 69  td><td> Result i
2ac0: 73 20 30 2e 30 3c 2f 74 64 3e 3c 2f 74 72 3e 0a  s 0.0</td></tr>.
2ad0: 3c 74 72 3e 3c 74 64 3e 20 4e 55 4c 4c 20 3c 2f  <tr><td> NULL </
2ae0: 74 64 3e 3c 74 64 3e 20 20 20 20 54 45 58 54 20  td><td>    TEXT 
2af0: 3c 2f 74 64 3e 3c 74 64 3e 20 20 52 65 73 75 6c  </td><td>  Resul
2b00: 74 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  t is an empty st
2b10: 72 69 6e 67 3c 2f 74 64 3e 3c 2f 74 72 3e 0a 3c  ring</td></tr>.<
2b20: 74 72 3e 3c 74 64 3e 20 4e 55 4c 4c 20 3c 2f 74  tr><td> NULL </t
2b30: 64 3e 3c 74 64 3e 20 20 20 20 42 4c 4f 42 20 3c  d><td>    BLOB <
2b40: 2f 74 64 3e 3c 74 64 3e 20 20 52 65 73 75 6c 74  /td><td>  Result
2b50: 20 69 73 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   is a zero-lengt
2b60: 68 20 42 4c 4f 42 3c 2f 74 64 3e 3c 2f 74 72 3e  h BLOB</td></tr>
2b70: 0a 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45  .<tr><td> INTEGE
2b80: 52 20 3c 2f 74 64 3e 3c 74 64 3e 20 46 4c 4f 41  R </td><td> FLOA
2b90: 54 20 3c 2f 74 64 3e 3c 74 64 3e 20 43 6f 6e 76  T </td><td> Conv
2ba0: 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
2bb0: 20 74 6f 20 66 6c 6f 61 74 3c 2f 74 64 3e 3c 2f   to float</td></
2bc0: 74 72 3e 0a 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  tr>.<tr><td> INT
2bd0: 45 47 45 52 20 3c 2f 74 64 3e 3c 74 64 3e 20 54  EGER </td><td> T
2be0: 45 58 54 20 3c 2f 74 64 3e 3c 74 64 3e 20 20 41  EXT </td><td>  A
2bf0: 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2c00: 66 20 74 68 65 20 69 6e 74 65 67 65 72 3c 2f 74  f the integer</t
2c10: 64 3e 3c 2f 74 72 3e 0a 3c 74 72 3e 3c 74 64 3e  d></tr>.<tr><td>
2c20: 20 49 4e 54 45 47 45 52 20 3c 2f 74 64 3e 3c 74   INTEGER </td><t
2c30: 64 3e 20 42 4c 4f 42 20 3c 2f 74 64 3e 3c 74 64  d> BLOB </td><td
2c40: 3e 20 20 53 61 6d 65 20 61 73 20 66 6f 72 20 49  >  Same as for I
2c50: 4e 54 45 47 45 52 2d 3e 54 45 58 54 3c 2f 74 64  NTEGER->TEXT</td
2c60: 3e 3c 2f 74 72 3e 0a 3c 74 72 3e 3c 74 64 3e 20  ></tr>.<tr><td> 
2c70: 46 4c 4f 41 54 20 3c 2f 74 64 3e 3c 74 64 3e 20  FLOAT </td><td> 
2c80: 20 20 49 4e 54 45 47 45 52 3c 2f 74 64 3e 3c 74    INTEGER</td><t
2c90: 64 3e 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66  d>Convert from f
2ca0: 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 3c  loat to integer<
2cb0: 2f 74 64 3e 3c 2f 74 72 3e 0a 3c 74 72 3e 3c 74  /td></tr>.<tr><t
2cc0: 64 3e 20 46 4c 4f 41 54 20 3c 2f 74 64 3e 3c 74  d> FLOAT </td><t
2cd0: 64 3e 20 20 20 54 45 58 54 20 3c 2f 74 64 3e 3c  d>   TEXT </td><
2ce0: 74 64 3e 20 20 41 53 43 49 49 20 72 65 6e 64 65  td>  ASCII rende
2cf0: 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
2d00: 74 3c 2f 74 64 3e 3c 2f 74 72 3e 0a 3c 74 72 3e  t</td></tr>.<tr>
2d10: 3c 74 64 3e 20 46 4c 4f 41 54 20 3c 2f 74 64 3e  <td> FLOAT </td>
2d20: 3c 74 64 3e 20 20 20 42 4c 4f 42 20 3c 2f 74 64  <td>   BLOB </td
2d30: 3e 3c 74 64 3e 20 20 53 61 6d 65 20 61 73 20 46  ><td>  Same as F
2d40: 4c 4f 41 54 2d 3e 54 45 58 54 3c 2f 74 64 3e 3c  LOAT->TEXT</td><
2d50: 2f 74 72 3e 0a 3c 74 72 3e 3c 74 64 3e 20 54 45  /tr>.<tr><td> TE
2d60: 58 54 20 3c 2f 74 64 3e 3c 74 64 3e 20 20 20 20  XT </td><td>    
2d70: 49 4e 54 45 47 45 52 3c 2f 74 64 3e 3c 74 64 3e  INTEGER</td><td>
2d80: 55 73 65 20 61 74 6f 69 28 29 3c 2f 74 64 3e 3c  Use atoi()</td><
2d90: 2f 74 72 3e 0a 3c 74 72 3e 3c 74 64 3e 20 54 45  /tr>.<tr><td> TE
2da0: 58 54 20 3c 2f 74 64 3e 3c 74 64 3e 20 20 20 20  XT </td><td>    
2db0: 46 4c 4f 41 54 20 3c 2f 74 64 3e 3c 74 64 3e 20  FLOAT </td><td> 
2dc0: 55 73 65 20 61 74 6f 66 28 29 3c 2f 74 64 3e 3c  Use atof()</td><
2dd0: 2f 74 72 3e 0a 3c 74 72 3e 3c 74 64 3e 20 54 45  /tr>.<tr><td> TE
2de0: 58 54 20 3c 2f 74 64 3e 3c 74 64 3e 20 20 20 20  XT </td><td>    
2df0: 42 4c 4f 42 20 3c 2f 74 64 3e 3c 74 64 3e 20 20  BLOB </td><td>  
2e00: 4e 6f 20 63 68 61 6e 67 65 3c 2f 74 64 3e 3c 2f  No change</td></
2e10: 74 72 3e 0a 3c 74 72 3e 3c 74 64 3e 20 42 4c 4f  tr>.<tr><td> BLO
2e20: 42 20 3c 2f 74 64 3e 3c 74 64 3e 20 20 20 20 49  B </td><td>    I
2e30: 4e 54 45 47 45 52 3c 2f 74 64 3e 3c 74 64 3e 43  NTEGER</td><td>C
2e40: 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
2e50: 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 3c 2f  hen use atoi()</
2e60: 74 64 3e 3c 2f 74 72 3e 0a 3c 74 72 3e 3c 74 64  td></tr>.<tr><td
2e70: 3e 20 42 4c 4f 42 20 3c 2f 74 64 3e 3c 74 64 3e  > BLOB </td><td>
2e80: 20 20 20 20 46 4c 4f 41 54 20 3c 2f 74 64 3e 3c      FLOAT </td><
2e90: 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
2ea0: 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
2eb0: 66 28 29 3c 2f 74 64 3e 3c 2f 74 72 3e 0a 3c 74  f()</td></tr>.<t
2ec0: 72 3e 3c 74 64 3e 20 42 4c 4f 42 20 3c 2f 74 64  r><td> BLOB </td
2ed0: 3e 3c 74 64 3e 20 20 20 20 54 45 58 54 20 3c 2f  ><td>    TEXT </
2ee0: 74 64 3e 3c 74 64 3e 20 20 41 64 64 20 61 20 5c  td><td>  Add a \
2ef0: 30 30 30 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  000 terminator i
2f00: 66 20 6e 65 65 64 65 64 3c 2f 74 64 3e 3c 2f 74  f needed</td></t
2f10: 72 3e 0a 3c 2f 74 61 62 6c 65 3e 0a 7d 0a 0a 61  r>.</table>.}..a
2f20: 70 69 20 7b 7d 20 7b 0a 69 6e 74 20 73 71 6c 69  pi {} {.int sqli
2f30: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2f40: 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2f50: 53 74 6d 74 29 3b 0a 7d 20 7b 0a 20 52 65 74 75  Stmt);.} {. Retu
2f60: 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
2f70: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2f80: 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
2f90: 6e 65 64 20 62 79 20 74 68 65 20 70 72 65 70 61  ned by the prepa
2fa0: 72 65 64 0a 20 53 51 4c 20 73 74 61 74 65 6d 65  red. SQL stateme
2fb0: 6e 74 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  nt. This routine
2fc0: 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
2fd0: 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 20 73 74  tmt is an SQL st
2fe0: 61 74 65 6d 65 6e 74 0a 20 74 68 61 74 20 64 6f  atement. that do
2ff0: 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
3000: 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
3010: 61 6e 20 55 50 44 41 54 45 29 2e 0a 0a 20 53 65  an UPDATE)... Se
3020: 65 20 61 6c 73 6f 20 73 71 6c 69 74 65 33 5f 64  e also sqlite3_d
3030: 61 74 61 5f 63 6f 75 6e 74 28 29 2e 0a 7d 0a 0a  ata_count()..}..
3040: 61 70 69 20 7b 7d 20 7b 0a 63 6f 6e 73 74 20 63  api {} {.const c
3050: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
3060: 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
3070: 69 74 65 33 5f 73 74 6d 74 20 2a 2c 20 69 6e 74  ite3_stmt *, int
3080: 20 69 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   i);.const void 
3090: 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30a0: 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
30b0: 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 7d  e3_stmt*,int);.}
30c0: 20 7b 0a 20 54 68 65 20 66 69 72 73 74 20 70 61   {. The first pa
30d0: 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 72 65  rameter is a pre
30e0: 70 61 72 65 64 20 53 51 4c 20 73 74 61 74 65 6d  pared SQL statem
30f0: 65 6e 74 2e 20 49 66 20 74 68 69 73 20 73 74 61  ent. If this sta
3100: 74 65 6d 65 6e 74 0a 20 69 73 20 61 20 53 45 4c  tement. is a SEL
3110: 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  ECT statement, t
3120: 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
3130: 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 72 65   the returned re
3140: 73 75 6c 74 20 73 65 74 20 0a 20 6f 66 20 74 68  sult set . of th
3150: 65 20 53 45 4c 45 43 54 20 69 73 20 61 20 74 61  e SELECT is a ta
3160: 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 65 6e 20  ble column then 
3170: 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
3180: 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 20  e of the table. 
3190: 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
31a0: 65 64 2e 20 49 66 20 74 68 65 20 4e 74 68 20 63  ed. If the Nth c
31b0: 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
31c0: 75 6c 74 20 73 65 74 20 69 73 20 6e 6f 74 20 61  ult set is not a
31d0: 74 20 74 61 62 6c 65 0a 20 63 6f 6c 75 6d 6e 2c  t table. column,
31e0: 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
31f0: 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
3200: 2e 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  . The returned s
3210: 74 72 69 6e 67 20 69 73 20 0a 20 55 54 46 2d 38  tring is . UTF-8
3220: 20 65 6e 63 6f 64 65 64 20 66 6f 72 20 73 71 6c   encoded for sql
3230: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
3240: 74 79 70 65 28 29 20 61 6e 64 20 55 54 46 2d 31  type() and UTF-1
3250: 36 20 65 6e 63 6f 64 65 64 0a 20 66 6f 72 20 73  6 encoded. for s
3260: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
3270: 63 6c 74 79 70 65 31 36 28 29 2e 0a 20 46 6f 72  cltype16().. For
3280: 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 74 68 65   example, in the
3290: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
32a0: 3a 0a 0a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  :.. <blockquote>
32b0: 3c 70 72 65 3e 0a 20 43 52 45 41 54 45 20 54 41  <pre>. CREATE TA
32c0: 42 4c 45 20 74 31 28 63 31 20 49 4e 54 45 47 45  BLE t1(c1 INTEGE
32d0: 52 29 3b 0a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  R);. </pre></blo
32e0: 63 6b 71 75 6f 74 65 3e 0a 0a 20 41 6e 64 20 74  ckquote>.. And t
32f0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
3300: 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64 3a  tement compiled:
3310: 0a 0a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  .. <blockquote><
3320: 70 72 65 3e 0a 20 53 45 4c 45 43 54 20 63 31 20  pre>. SELECT c1 
3330: 2b 20 31 2c 20 30 20 46 52 4f 4d 20 74 31 3b 0a  + 1, 0 FROM t1;.
3340: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
3350: 6f 74 65 3e 0a 0a 20 54 68 65 6e 20 74 68 69 73  ote>.. Then this
3360: 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
3370: 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
3380: 20 22 49 4e 54 45 47 45 52 22 20 66 6f 72 20 74   "INTEGER" for t
3390: 68 65 20 73 65 63 6f 6e 64 0a 20 72 65 73 75 6c  he second. resul
33a0: 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  t column (i==1),
33b0: 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
33c0: 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
33d0: 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  t result column.
33e0: 20 28 69 3d 3d 30 29 2e 0a 7d 0a 0a 61 70 69 20   (i==0)..}..api 
33f0: 7b 7d 20 7b 0a 63 6f 6e 73 74 20 63 68 61 72 20  {} {.const char 
3400: 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
3410: 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
3420: 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
3430: 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
3440: 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
3450: 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 7d  e3_stmt*,int);.}
3460: 20 7b 0a 20 54 68 65 20 66 69 72 73 74 20 70 61   {. The first pa
3470: 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 72 65  rameter is a pre
3480: 70 61 72 65 64 20 53 51 4c 20 73 74 61 74 65 6d  pared SQL statem
3490: 65 6e 74 2e 20 54 68 69 73 20 66 75 6e 63 74 69  ent. This functi
34a0: 6f 6e 20 72 65 74 75 72 6e 73 0a 20 74 68 65 20  on returns. the 
34b0: 63 6f 6c 75 6d 6e 20 68 65 61 64 69 6e 67 20 66  column heading f
34c0: 6f 72 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  or the Nth colum
34d0: 6e 20 6f 66 20 74 68 61 74 20 73 74 61 74 65 6d  n of that statem
34e0: 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
34f0: 74 68 65 0a 20 73 65 63 6f 6e 64 20 66 75 6e 63  the. second func
3500: 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 2e 20  tion parameter. 
3510: 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75   The string retu
3520: 72 6e 65 64 20 69 73 20 55 54 46 2d 38 20 66 6f  rned is UTF-8 fo
3530: 72 0a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r. sqlite3_colum
3540: 6e 5f 6e 61 6d 65 28 29 20 61 6e 64 20 55 54 46  n_name() and UTF
3550: 2d 31 36 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  -16 for sqlite3_
3560: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 2e  column_name16().
3570: 0a 7d 0a 0a 61 70 69 20 7b 7d 20 7b 0a 76 6f 69  .}..api {} {.voi
3580: 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  d *sqlite3_commi
3590: 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 2a 2c 20  t_hook(sqlite*, 
35a0: 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28  int(*xCallback)(
35b0: 76 6f 69 64 2a 29 2c 20 76 6f 69 64 20 2a 70 41  void*), void *pA
35c0: 72 67 29 3b 0a 7d 20 7b 0a 20 3c 69 3e 45 78 70  rg);.} {. <i>Exp
35d0: 65 72 69 6d 65 6e 74 61 6c 3c 2f 69 3e 0a 0a 20  erimental</i>.. 
35e0: 52 65 67 69 73 74 65 72 20 61 20 63 61 6c 6c 62  Register a callb
35f0: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ack function to 
3600: 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
3610: 76 65 72 20 61 20 6e 65 77 20 74 72 61 6e 73 61  ver a new transa
3620: 63 74 69 6f 6e 0a 20 69 73 20 63 6f 6d 6d 69 74  ction. is commit
3630: 74 65 64 2e 20 20 54 68 65 20 70 41 72 67 20 61  ted.  The pArg a
3640: 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65  rgument is passe
3650: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3660: 20 63 61 6c 6c 62 61 63 6b 2e 0a 20 63 61 6c 6c   callback.. call
3670: 62 61 63 6b 2e 20 20 49 66 20 74 68 65 20 63 61  back.  If the ca
3680: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3690: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
36a0: 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69  , then the commi
36b0: 74 0a 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  t. is converted 
36c0: 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e  into a rollback.
36d0: 0a 0a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75  .. If another fu
36e0: 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69  nction was previ
36f0: 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64  ously registered
3700: 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c 75 65  , its pArg value
3710: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 20 4f   is returned.. O
3720: 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73  therwise NULL is
3730: 20 72 65 74 75 72 6e 65 64 2e 0a 0a 20 52 65 67   returned... Reg
3740: 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20  istering a NULL 
3750: 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
3760: 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20  s the callback. 
3770: 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 63   Only a single c
3780: 6f 6d 6d 69 74 0a 20 68 6f 6f 6b 20 63 61 6c 6c  ommit. hook call
3790: 62 61 63 6b 20 63 61 6e 20 62 65 20 72 65 67 69  back can be regi
37a0: 73 74 65 72 65 64 20 61 74 20 61 20 74 69 6d 65  stered at a time
37b0: 2e 0a 7d 0a 0a 61 70 69 20 7b 7d 20 7b 0a 69 6e  ..}..api {} {.in
37c0: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
37d0: 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
37e0: 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
37f0: 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
3800: 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 7d 20  t void *sql);.} 
3810: 7b 0a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  {. These functio
3820: 6e 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 69  ns return true i
3830: 66 20 74 68 65 20 67 69 76 65 6e 20 69 6e 70 75  f the given inpu
3840: 74 20 73 74 72 69 6e 67 20 63 6f 6d 70 72 69 73  t string compris
3850: 65 73 0a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  es. one or more 
3860: 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
3870: 74 65 6d 65 6e 74 73 2e 0a 20 54 68 65 20 70 61  tements.. The pa
3880: 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
3890: 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
38a0: 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 66 6f   UTF-8 string fo
38b0: 72 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  r sqlite3_comple
38c0: 74 65 28 29 0a 20 61 6e 64 20 61 20 6e 75 6c 2d  te(). and a nul-
38d0: 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31  terminated UTF-1
38e0: 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c  6 string for sql
38f0: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
3900: 29 2e 0a 0a 20 54 68 65 20 61 6c 67 6f 72 69 74  )... The algorit
3910: 68 6d 20 69 73 20 73 69 6d 70 6c 65 2e 20 20 49  hm is simple.  I
3920: 66 20 74 68 65 20 6c 61 73 74 20 74 6f 6b 65 6e  f the last token
3930: 20 6f 74 68 65 72 20 74 68 61 6e 20 73 70 61 63   other than spac
3940: 65 73 0a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  es. and comments
3950: 20 69 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2c   is a semicolon,
3960: 20 74 68 65 6e 20 72 65 74 75 72 6e 20 74 72 75   then return tru
3970: 65 2e 20 20 6f 74 68 65 72 77 69 73 65 20 72 65  e.  otherwise re
3980: 74 75 72 6e 0a 20 66 61 6c 73 65 2e 0a 7d 20 7b  turn. false..} {
3990: 7d 0a 0a 61 70 69 20 7b 7d 20 7b 0a 69 6e 74 20  }..api {} {.int 
39a0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
39b0: 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
39c0: 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
39d0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
39e0: 6e 74 20 70 72 65 66 31 36 2c 20 0a 20 20 76 6f  nt pref16, .  vo
39f0: 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
3a00: 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
3a10: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
3a20: 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
3a30: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
3a40: 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a  te_collation16(.
3a50: 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
3a60: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
3a70: 2c 20 0a 20 20 69 6e 74 20 70 72 65 66 31 36 2c  , .  int pref16,
3a80: 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
3a90: 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
3aa0: 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
3ab0: 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
3ac0: 2a 29 0a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  *).);.#define SQ
3ad0: 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 31 0a  LITE_UTF8     1.
3ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
3af0: 54 46 31 36 42 45 20 20 32 0a 23 64 65 66 69 6e  TF16BE  2.#defin
3b00: 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
3b10: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
3b20: 54 45 5f 55 54 46 31 36 20 20 20 20 34 0a 7d 20  TE_UTF16    4.} 
3b30: 7b 0a 20 54 68 65 73 65 20 74 77 6f 20 66 75 6e  {. These two fun
3b40: 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20  ctions are used 
3b50: 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61  to add new colla
3b60: 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74  tion sequences t
3b70: 6f 20 74 68 65 0a 20 73 71 6c 69 74 65 33 20 68  o the. sqlite3 h
3b80: 61 6e 64 6c 65 20 73 70 65 63 69 66 69 65 64 20  andle specified 
3b90: 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
3ba0: 75 6d 65 6e 74 2e 20 0a 0a 20 54 68 65 20 6e 61  ument. .. The na
3bb0: 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f  me of the new co
3bc0: 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
3bd0: 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73   is specified as
3be0: 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
3bf0: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
3c00: 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
3c10: 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
3c20: 69 6e 67 20 66 6f 72 0a 20 73 71 6c 69 74 65 33  ing for. sqlite3
3c30: 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
3c40: 6e 31 36 28 29 2e 20 49 6e 20 62 6f 74 68 20 63  n16(). In both c
3c50: 61 73 65 73 20 74 68 65 20 6e 61 6d 65 20 69 73  ases the name is
3c60: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 20   passed as the. 
3c70: 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
3c80: 61 72 67 75 6d 65 6e 74 2e 0a 0a 20 54 68 65 20  argument... The 
3c90: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d  third argument m
3ca0: 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  ust be one of th
3cb0: 65 20 63 6f 6e 73 74 61 6e 74 73 20 53 51 4c 49  e constants SQLI
3cc0: 54 45 5f 55 54 46 38 2c 0a 20 53 51 4c 49 54 45  TE_UTF8,. SQLITE
3cd0: 5f 55 54 46 31 36 4c 45 20 6f 72 20 53 51 4c 49  _UTF16LE or SQLI
3ce0: 54 45 5f 55 54 46 31 36 42 45 2c 20 69 6e 64 69  TE_UTF16BE, indi
3cf0: 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20  cating that the 
3d00: 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 20 72  user-supplied. r
3d10: 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 74  outine expects t
3d20: 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e  o be passed poin
3d30: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3d40: 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
3d50: 46 2d 38 2c 0a 20 55 54 46 2d 31 36 20 6c 69 74  F-8,. UTF-16 lit
3d60: 74 6c 65 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54  tle-endian or UT
3d70: 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 20  F-16 big-endian 
3d80: 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 54  respectively.  T
3d90: 68 65 0a 20 53 51 4c 49 54 45 5f 55 54 46 31 36  he. SQLITE_UTF16
3da0: 20 63 6f 6e 73 74 61 6e 74 20 69 6e 64 69 63 61   constant indica
3db0: 74 65 73 20 74 68 61 74 20 74 65 78 74 20 73 74  tes that text st
3dc0: 72 69 6e 67 73 20 61 72 65 20 65 78 70 65 63 74  rings are expect
3dd0: 65 64 20 69 6e 0a 20 55 54 46 2d 31 36 20 69 6e  ed in. UTF-16 in
3de0: 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
3df0: 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f   order of the ho
3e00: 73 74 20 6d 61 63 68 69 6e 65 2e 0a 0a 20 41 20  st machine... A 
3e10: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75  pointer to the u
3e20: 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75  ser supplied rou
3e30: 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73  tine must be pas
3e40: 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68  sed as the fifth
3e50: 0a 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69  . argument. If i
3e60: 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20  t is NULL, this 
3e70: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64  is the same as d
3e80: 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c  eleting the coll
3e90: 61 74 69 6f 6e 0a 20 73 65 71 75 65 6e 63 65 20  ation. sequence 
3ea0: 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20  (so that SQLite 
3eb0: 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61  cannot call it a
3ec0: 6e 79 6d 6f 72 65 29 2e 20 45 61 63 68 20 74 69  nymore). Each ti
3ed0: 6d 65 20 74 68 65 20 75 73 65 72 0a 20 73 75 70  me the user. sup
3ee0: 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  plied function i
3ef0: 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73  s invoked, it is
3f00: 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f   passed a copy o
3f10: 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73  f the void* pass
3f20: 65 64 20 61 73 0a 20 74 68 65 20 66 6f 75 72 74  ed as. the fourt
3f30: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
3f40: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
3f50: 6c 61 74 69 6f 6e 28 29 20 6f 72 0a 20 73 71 6c  lation() or. sql
3f60: 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
3f70: 61 74 69 6f 6e 31 36 28 29 20 61 73 20 69 74 73  ation16() as its
3f80: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
3f90: 2e 0a 0a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  ... The remainin
3fa0: 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  g arguments to t
3fb0: 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64  he user-supplied
3fc0: 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f   routine are two
3fd0: 20 73 74 72 69 6e 67 73 2c 0a 20 65 61 63 68 20   strings,. each 
3fe0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
3ff0: 20 5b 6c 65 6e 67 74 68 2c 20 64 61 74 61 5d 20   [length, data] 
4000: 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64  pair and encoded
4010: 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
4020: 0a 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65  . that was passe
4030: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61  d as the third a
4040: 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65  rgument when the
4050: 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
4060: 6e 63 65 20 77 61 73 0a 20 72 65 67 69 73 74 65  nce was. registe
4070: 72 65 64 2e 20 54 68 65 20 75 73 65 72 20 72 6f  red. The user ro
4080: 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74  utine should ret
4090: 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65  urn negative, ze
40a0: 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69  ro or positive i
40b0: 66 0a 20 74 68 65 20 66 69 72 73 74 20 73 74 72  f. the first str
40c0: 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
40d0: 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
40e0: 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
40f0: 73 65 63 6f 6e 64 0a 20 73 74 72 69 6e 67 2e 20  second. string. 
4100: 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20  i.e. (STRING1 - 
4110: 53 54 52 49 4e 47 32 29 2e 0a 7d 0a 0a 61 70 69  STRING2)..}..api
4120: 20 7b 7d 20 7b 0a 69 6e 74 20 73 71 6c 69 74 65   {} {.int sqlite
4130: 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
4140: 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
4150: 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
4160: 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
4170: 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
4180: 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
4190: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
41a0: 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
41b0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
41c0: 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29  void*,.  void(*)
41d0: 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
41e0: 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
41f0: 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 7d 20 7b  st void*).);.} {
4200: 0a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e  . To avoid havin
4210: 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
4220: 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
4230: 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
4240: 61 74 61 62 61 73 65 0a 20 63 61 6e 20 62 65 20  atabase. can be 
4250: 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63  used, a single c
4260: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4270: 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
4280: 65 64 20 77 69 74 68 20 74 68 65 0a 20 64 61 74  ed with the. dat
4290: 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20  abase handle to 
42a0: 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76  be called whenev
42b0: 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
42c0: 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
42d0: 63 65 20 69 73 0a 20 72 65 71 75 69 72 65 64 2e  ce is. required.
42e0: 0a 0a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69  .. If the functi
42f0: 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64  on is registered
4300: 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
4310: 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
4320: 64 65 64 28 29 20 41 50 49 2c 0a 20 74 68 65 6e  ded() API,. then
4330: 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
4340: 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
4350: 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
4360: 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
4370: 6e 67 73 0a 20 65 6e 63 6f 64 65 64 20 69 6e 20  ngs. encoded in 
4380: 55 54 46 2d 38 2e 20 49 66 20 73 71 6c 69 74 65  UTF-8. If sqlite
4390: 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
43a0: 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 20  ed16() is used, 
43b0: 74 68 65 20 6e 61 6d 65 73 0a 20 61 72 65 20 70  the names. are p
43c0: 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
43d0: 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
43e0: 65 20 62 79 74 65 20 6f 72 64 65 72 2e 20 41 20  e byte order. A 
43f0: 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 0a 20  call to either. 
4400: 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
4410: 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63  s any existing c
4420: 61 6c 6c 62 61 63 6b 2e 0a 0a 20 57 68 65 6e 20  allback... When 
4430: 74 68 65 20 75 73 65 72 2d 66 75 6e 63 74 69 6f  the user-functio
4440: 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  n is invoked, th
4450: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
4460: 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70   passed is a cop
4470: 79 0a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  y. of the second
4480: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
4490: 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
44a0: 65 65 64 65 64 28 29 20 6f 72 0a 20 73 71 6c 69  eeded() or. sqli
44b0: 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
44c0: 65 64 65 64 31 36 28 29 2e 20 54 68 65 20 73 65  eded16(). The se
44d0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
44e0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 20 68   the database. h
44f0: 61 6e 64 6c 65 2e 20 54 68 65 20 74 68 69 72 64  andle. The third
4500: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
4510: 20 6f 66 20 53 51 4c 49 54 45 5f 55 54 46 38 2c   of SQLITE_UTF8,
4520: 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
4530: 6f 72 0a 20 53 51 4c 49 54 45 5f 55 54 46 31 36  or. SQLITE_UTF16
4540: 4c 45 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  LE, indicating t
4550: 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c  he most desirabl
4560: 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f  e form of the co
4570: 6c 6c 61 74 69 6f 6e 0a 20 73 65 71 75 65 6e 63  llation. sequenc
4580: 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  e function requi
4590: 72 65 64 2e 20 54 68 65 20 66 6f 75 72 74 68 20  red. The fourth 
45a0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
45b0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 20 72 65   name of the. re
45c0: 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
45d0: 20 73 65 71 75 65 6e 63 65 2e 0a 0a 20 54 68 65   sequence... The
45e0: 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
45f0: 6e 63 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  nce is returned 
4600: 74 6f 20 53 51 4c 69 74 65 20 62 79 20 61 20 63  to SQLite by a c
4610: 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 0a  ollation-needed.
4620: 20 63 61 6c 6c 62 61 63 6b 20 75 73 69 6e 67 20   callback using 
4630: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
4640: 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f  te_collation() o
4650: 72 0a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r. sqlite3_creat
4660: 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 20  e_collation16() 
4670: 41 50 49 73 2c 20 64 65 73 63 72 69 62 65 64 20  APIs, described 
4680: 61 62 6f 76 65 2e 0a 7d 0a 0a 61 70 69 20 7b 7d  above..}..api {}
4690: 20 7b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63   {.int sqlite3_c
46a0: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
46b0: 20 20 73 71 6c 69 74 65 33 20 2a 2c 0a 20 20 63    sqlite3 *,.  c
46c0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
46d0: 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
46e0: 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
46f0: 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20  tRep,.  void*,. 
4700: 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
4710: 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
4720: 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
4730: 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
4740: 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
4750: 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
4760: 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
4770: 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
4780: 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
4790: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
47a0: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
47b0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
47c0: 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
47d0: 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
47e0: 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
47f0: 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a  xtRep,.  void*,.
4800: 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
4810: 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
4820: 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
4830: 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
4840: 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
4850: 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
4860: 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
4870: 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
4880: 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
4890: 0a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .);.#define SQLI
48a0: 54 45 5f 55 54 46 38 20 20 20 20 20 31 0a 23 64  TE_UTF8     1.#d
48b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
48c0: 31 36 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  16    2.#define 
48d0: 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
48e0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
48f0: 5f 55 54 46 31 36 4c 45 20 20 34 0a 23 64 65 66  _UTF16LE  4.#def
4900: 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
4910: 20 20 20 20 35 0a 7d 20 7b 0a 20 54 68 65 73 65      5.} {. These
4920: 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 61   two functions a
4930: 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 75  re used to add u
4940: 73 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ser functions or
4950: 20 61 67 67 72 65 67 61 74 65 73 0a 20 69 6d 70   aggregates. imp
4960: 6c 65 6d 65 6e 74 65 64 20 69 6e 20 43 20 74 6f  lemented in C to
4970: 20 74 68 65 20 53 51 4c 20 6c 61 6e 67 61 75 67   the SQL langaug
4980: 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 62 79  e interpreted by
4990: 20 53 51 4c 69 74 65 2e 20 54 68 65 0a 20 64 69   SQLite. The. di
49a0: 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20 62 65  fference only be
49b0: 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20 69 73  tween the two is
49c0: 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
49d0: 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 0a   parameter, the.
49e0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63   name of the (sc
49f0: 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f  alar) function o
4a00: 72 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20  r aggregate, is 
4a10: 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
4a20: 20 66 6f 72 0a 20 73 71 6c 69 74 65 33 5f 63 72   for. sqlite3_cr
4a30: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
4a40: 61 6e 64 20 55 54 46 2d 31 36 20 66 6f 72 20 73  and UTF-16 for s
4a50: 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
4a60: 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 0a 20 54 68  nction16()... Th
4a70: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
4a80: 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
4a90: 20 68 61 6e 64 6c 65 20 74 68 61 74 20 74 68 65   handle that the
4aa0: 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 6f 72   new function or
4ab0: 0a 20 61 67 67 72 65 67 61 74 65 20 69 73 20 74  . aggregate is t
4ac0: 6f 20 62 65 20 61 64 64 65 64 20 74 6f 2e 20 49  o be added to. I
4ad0: 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  f a single progr
4ae0: 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  am uses more tha
4af0: 6e 20 6f 6e 65 0a 20 64 61 74 61 62 61 73 65 20  n one. database 
4b00: 68 61 6e 64 6c 65 20 69 6e 74 65 72 6e 61 6c 6c  handle internall
4b10: 79 2c 20 74 68 65 6e 20 75 73 65 72 20 66 75 6e  y, then user fun
4b20: 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
4b30: 61 74 65 73 20 6d 75 73 74 20 0a 20 62 65 20 61  ates must . be a
4b40: 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  dded individuall
4b50: 79 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  y to each databa
4b60: 73 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 77  se handle with w
4b70: 68 69 63 68 20 74 68 65 79 20 77 69 6c 6c 20 62  hich they will b
4b80: 65 0a 20 75 73 65 64 2e 0a 0a 20 54 68 65 20 74  e. used... The t
4b90: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
4ba0: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
4bb0: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
4bc0: 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 20  he function or. 
4bd0: 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
4be0: 20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   If this paramet
4bf0: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
4c00: 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  then the functio
4c10: 6e 20 6f 72 0a 20 61 67 67 72 65 67 61 74 65 20  n or. aggregate 
4c20: 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
4c30: 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
4c40: 2e 0a 0a 20 54 68 65 20 73 69 78 74 68 2c 20 73  ... The sixth, s
4c50: 65 76 65 6e 74 68 20 61 6e 64 20 20 65 69 67 68  eventh and  eigh
4c60: 74 68 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  th, xFunc, xStep
4c70: 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
4c80: 0a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 75 73  . pointers to us
4c90: 65 72 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 43  er implemented C
4ca0: 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
4cb0: 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 75 73  implement the us
4cc0: 65 72 0a 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  er. function or 
4cd0: 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61  aggregate. A sca
4ce0: 6c 61 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  lar function req
4cf0: 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
4d00: 6e 74 61 74 69 6f 6e 20 6f 66 0a 20 74 68 65 20  ntation of. the 
4d10: 78 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f  xFunc callback o
4d20: 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly, NULL pointe
4d30: 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  rs should be pas
4d40: 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
4d50: 0a 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 61 72  . and xFinal par
4d60: 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72  ameters. An aggr
4d70: 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 72  egate function r
4d80: 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
4d90: 6d 65 6e 74 61 74 69 6f 6e 0a 20 6f 66 20 78 53  mentation. of xS
4da0: 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
4db0: 62 75 74 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20  but NULL should 
4dc0: 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
4dd0: 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61  unc. To delete a
4de0: 6e 0a 20 65 78 69 73 74 69 6e 67 20 75 73 65 72  n. existing user
4df0: 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
4e00: 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
4e10: 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  L for all three 
4e20: 66 75 6e 63 74 69 6f 6e 0a 20 63 61 6c 6c 62 61  function. callba
4e30: 63 6b 2e 20 53 70 65 63 69 66 79 69 6e 67 20 61  ck. Specifying a
4e40: 6e 20 69 6e 63 6f 6e 73 74 65 6e 74 20 73 65 74  n inconstent set
4e50: 20 6f 66 20 63 61 6c 6c 62 61 63 6b 20 76 61 6c   of callback val
4e60: 75 65 73 2c 20 73 75 63 68 20 61 73 20 61 6e 0a  ues, such as an.
4e70: 20 78 46 75 6e 63 20 61 6e 64 20 61 6e 20 78 46   xFunc and an xF
4e80: 69 6e 61 6c 2c 20 6f 72 20 61 6e 20 78 53 74 65  inal, or an xSte
4e90: 70 20 62 75 74 20 6e 6f 20 78 46 69 6e 61 6c 2c  p but no xFinal,
4ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73   SQLITE_ERROR is
4eb0: 0a 20 72 65 74 75 72 6e 65 64 2e 0a 7d 0a 0a 61  . returned..}..a
4ec0: 70 69 20 7b 7d 20 7b 0a 69 6e 74 20 73 71 6c 69  pi {} {.int sqli
4ed0: 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
4ee0: 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
4ef0: 6d 74 29 3b 0a 7d 20 7b 0a 20 52 65 74 75 72 6e  mt);.} {. Return
4f00: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76   the number of v
4f10: 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72  alues in the cur
4f20: 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
4f30: 72 65 73 75 6c 74 20 73 65 74 2e 0a 0a 20 41 66  result set... Af
4f40: 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ter a call to sq
4f50: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 74 68 61  lite3_step() tha
4f60: 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  t returns SQLITE
4f70: 5f 52 4f 57 2c 20 74 68 69 73 20 72 6f 75 74 69  _ROW, this routi
4f80: 6e 65 0a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ne. will return 
4f90: 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 61  the same value a
4fa0: 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  s the sqlite3_co
4fb0: 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 66 75 6e  lumn_count() fun
4fc0: 63 74 69 6f 6e 2e 0a 20 41 66 74 65 72 20 73 71  ction.. After sq
4fd0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4fe0: 20 72 65 74 75 72 6e 65 64 20 61 6e 20 53 51 4c   returned an SQL
4ff0: 49 54 45 5f 44 4f 4e 45 2c 20 53 51 4c 49 54 45  ITE_DONE, SQLITE
5000: 5f 42 55 53 59 20 6f 72 0a 20 65 72 72 6f 72 20  _BUSY or. error 
5010: 63 6f 64 65 2c 20 6f 72 20 62 65 66 6f 72 65 20  code, or before 
5020: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
5030: 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  as been called o
5040: 6e 20 61 20 0a 20 70 72 65 70 61 72 65 64 20 53  n a . prepared S
5050: 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68  QL statement, th
5060: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
5070: 6e 73 20 7a 65 72 6f 2e 0a 7d 0a 0a 61 70 69 20  ns zero..}..api 
5080: 7b 7d 20 7b 0a 69 6e 74 20 73 71 6c 69 74 65 33  {} {.int sqlite3
5090: 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
50a0: 20 2a 64 62 29 3b 0a 7d 20 7b 0a 20 52 65 74 75   *db);.} {. Retu
50b0: 72 6e 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  rn the error cod
50c0: 65 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72  e for the most r
50d0: 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20  ecent sqlite3_* 
50e0: 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61  API call associa
50f0: 74 65 64 0a 20 77 69 74 68 20 73 71 6c 69 74 65  ted. with sqlite
5100: 33 20 68 61 6e 64 6c 65 20 27 64 62 27 2e 20 53  3 handle 'db'. S
5110: 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
5120: 72 6e 65 64 20 69 66 20 74 68 65 20 6d 6f 73 74  rned if the most
5130: 20 72 65 63 65 6e 74 20 0a 20 41 50 49 20 63 61   recent . API ca
5140: 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 75  ll was successfu
5150: 6c 2e 0a 0a 20 43 61 6c 6c 73 20 74 6f 20 6d 61  l... Calls to ma
5160: 6e 79 20 73 71 6c 69 74 65 33 5f 2a 20 66 75 6e  ny sqlite3_* fun
5170: 63 74 69 6f 6e 73 20 73 65 74 20 74 68 65 20 65  ctions set the e
5180: 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 73 74  rror code and st
5190: 72 69 6e 67 20 72 65 74 75 72 6e 65 64 0a 20 62  ring returned. b
51a0: 79 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  y sqlite3_errcod
51b0: 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 65 72 72  e(), sqlite3_err
51c0: 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
51d0: 33 5f 65 72 72 6d 73 67 31 36 28 29 0a 20 28 6f  3_errmsg16(). (o
51e0: 76 65 72 77 72 69 74 69 6e 67 20 74 68 65 20 70  verwriting the p
51f0: 72 65 76 69 6f 75 73 20 76 61 6c 75 65 73 29 2e  revious values).
5200: 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 73   Note that calls
5210: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 72 72 63   to sqlite3_errc
5220: 6f 64 65 28 29 2c 0a 20 73 71 6c 69 74 65 33 5f  ode(),. sqlite3_
5230: 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
5240: 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
5250: 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f  themselves do no
5260: 74 20 61 66 66 65 63 74 20 74 68 65 0a 20 72 65  t affect the. re
5270: 73 75 6c 74 73 20 6f 66 20 66 75 74 75 72 65 20  sults of future 
5280: 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a 0a 20 41  invocations... A
5290: 73 73 75 6d 69 6e 67 20 6e 6f 20 6f 74 68 65 72  ssuming no other
52a0: 20 69 6e 74 65 72 76 65 6e 69 6e 67 20 73 71 6c   intervening sql
52b0: 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 73  ite3_* API calls
52c0: 20 61 72 65 20 6d 61 64 65 2c 20 74 68 65 20 65   are made, the e
52d0: 72 72 6f 72 0a 20 63 6f 64 65 20 72 65 74 75 72  rror. code retur
52e0: 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
52f0: 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74  tion is associat
5300: 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ed with the same
5310: 20 65 72 72 6f 72 20 61 73 0a 20 74 68 65 20 73   error as. the s
5320: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
5330: 62 79 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  by sqlite3_errms
5340: 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
5350: 65 72 72 6d 73 67 31 36 28 29 2e 0a 7d 20 7b 7d  errmsg16()..} {}
5360: 0a 0a 61 70 69 20 7b 7d 20 7b 0a 63 6f 6e 73 74  ..api {} {.const
5370: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
5380: 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
5390: 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
53a0: 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
53b0: 6c 69 74 65 33 2a 29 3b 0a 7d 20 7b 0a 20 52 65  lite3*);.} {. Re
53c0: 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  turn a pointer t
53d0: 6f 20 61 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  o a UTF-8 encode
53e0: 64 20 73 74 72 69 6e 67 20 28 73 71 6c 69 74 65  d string (sqlite
53f0: 33 5f 65 72 72 6d 73 67 29 0a 20 6f 72 20 61 20  3_errmsg). or a 
5400: 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
5410: 74 72 69 6e 67 20 28 73 71 6c 69 74 65 33 5f 65  tring (sqlite3_e
5420: 72 72 6d 73 67 31 36 29 20 64 65 73 63 72 69 62  rrmsg16) describ
5430: 69 6e 67 20 69 6e 20 45 6e 67 6c 69 73 68 20 74  ing in English t
5440: 68 65 0a 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  he. error condit
5450: 69 6f 6e 20 66 6f 72 20 74 68 65 20 6d 6f 73 74  ion for the most
5460: 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f   recent sqlite3_
5470: 2a 20 41 50 49 20 63 61 6c 6c 2e 20 54 68 65 20  * API call. The 
5480: 72 65 74 75 72 6e 65 64 0a 20 73 74 72 69 6e 67  returned. string
5490: 20 69 73 20 61 6c 77 61 79 73 20 74 65 72 6d 69   is always termi
54a0: 6e 61 74 65 64 20 62 79 20 61 6e 20 30 78 30 30  nated by an 0x00
54b0: 20 62 79 74 65 2e 0a 0a 20 54 68 65 20 73 74 72   byte... The str
54c0: 69 6e 67 20 22 6e 6f 74 20 61 6e 20 65 72 72 6f  ing "not an erro
54d0: 72 22 20 69 73 20 72 65 74 75 72 6e 65 64 20 77  r" is returned w
54e0: 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
54f0: 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73  ent API call was
5500: 0a 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 7d 0a  . successful..}.
5510: 0a 61 70 69 20 7b 7d 20 7b 0a 69 6e 74 20 73 71  .api {} {.int sq
5520: 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71  lite3_exec(.  sq
5530: 6c 69 74 65 2a 2c 20 20 20 20 20 20 20 20 20 20  lite*,          
5540: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
5550: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
5560: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
5570: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
5580: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
5590: 65 78 65 63 75 74 65 64 20 2a 2f 0a 20 20 73 71  executed */.  sq
55a0: 6c 69 74 65 5f 63 61 6c 6c 62 61 63 6b 2c 20 20  lite_callback,  
55b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
55c0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
55d0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
55e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
55f0: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
5600: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
5610: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 68  function */.  ch
5620: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
5630: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
5640: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
5650: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 7d 20 7b 0a   here */.);.} {.
5660: 20 41 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 65   A function to e
5670: 78 65 63 75 74 65 73 20 6f 6e 65 20 6f 72 20 6d  xecutes one or m
5680: 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  ore statements o
5690: 66 20 53 51 4c 2e 0a 0a 20 49 66 20 6f 6e 65 20  f SQL... If one 
56a0: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 53  or more of the S
56b0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
56c0: 65 20 71 75 65 72 69 65 73 2c 20 74 68 65 6e 0a  e queries, then.
56d0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   the callback fu
56e0: 6e 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64  nction specified
56f0: 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61   by the 3rd para
5700: 6d 65 74 65 72 20 69 73 0a 20 69 6e 76 6f 6b 65  meter is. invoke
5710: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
5720: 72 6f 77 20 6f 66 20 74 68 65 20 71 75 65 72 79  row of the query
5730: 20 72 65 73 75 6c 74 2e 20 20 54 68 69 73 20 63   result.  This c
5740: 61 6c 6c 62 61 63 6b 0a 20 73 68 6f 75 6c 64 20  allback. should 
5750: 6e 6f 72 6d 61 6c 6c 79 20 72 65 74 75 72 6e 20  normally return 
5760: 30 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62  0.  If the callb
5770: 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ack returns a no
5780: 6e 2d 7a 65 72 6f 0a 20 76 61 6c 75 65 20 74 68  n-zero. value th
5790: 65 6e 20 74 68 65 20 71 75 65 72 79 20 69 73 20  en the query is 
57a0: 61 62 6f 72 74 65 64 2c 20 61 6c 6c 20 73 75 62  aborted, all sub
57b0: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
57c0: 65 6d 65 6e 74 73 0a 20 61 72 65 20 73 6b 69 70  ements. are skip
57d0: 70 65 64 20 61 6e 64 20 74 68 65 20 73 71 6c 69  ped and the sqli
57e0: 74 65 33 5f 65 78 65 63 28 29 20 66 75 6e 63 74  te3_exec() funct
57f0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
5800: 53 51 4c 49 54 45 5f 41 42 4f 52 54 2e 0a 0a 20  SQLITE_ABORT... 
5810: 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  The 4th paramete
5820: 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
5830: 79 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  y pointer that i
5840: 73 20 70 61 73 73 65 64 0a 20 74 6f 20 74 68 65  s passed. to the
5850: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
5860: 6f 6e 20 61 73 20 69 74 73 20 66 69 72 73 74 20  on as its first 
5870: 70 61 72 61 6d 65 74 65 72 2e 0a 0a 20 54 68 65  parameter... The
5880: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
5890: 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  o the callback f
58a0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 20 6e  unction is the n
58b0: 75 6d 62 65 72 20 6f 66 0a 20 63 6f 6c 75 6d 6e  umber of. column
58c0: 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 72  s in the query r
58d0: 65 73 75 6c 74 2e 20 20 54 68 65 20 33 72 64 20  esult.  The 3rd 
58e0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
58f0: 20 63 61 6c 6c 62 61 63 6b 0a 20 69 73 20 61 6e   callback. is an
5900: 20 61 72 72 61 79 20 6f 66 20 73 74 72 69 6e 67   array of string
5910: 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 20 76 61  s holding the va
5920: 6c 75 65 73 20 66 6f 72 20 65 61 63 68 20 63 6f  lues for each co
5930: 6c 75 6d 6e 2e 0a 20 54 68 65 20 34 74 68 20 70  lumn.. The 4th p
5940: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
5950: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
5960: 72 72 61 79 20 6f 66 20 73 74 72 69 6e 67 73 20  rray of strings 
5970: 68 6f 6c 64 69 6e 67 0a 20 74 68 65 20 6e 61 6d  holding. the nam
5980: 65 73 20 6f 66 20 65 61 63 68 20 63 6f 6c 75 6d  es of each colum
5990: 6e 2e 0a 0a 20 54 68 65 20 63 61 6c 6c 62 61 63  n... The callbac
59a0: 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
59b0: 65 20 4e 55 4c 4c 2c 20 65 76 65 6e 20 66 6f 72  e NULL, even for
59c0: 20 71 75 65 72 69 65 73 2e 20 20 41 20 4e 55 4c   queries.  A NUL
59d0: 4c 0a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  L. callback is n
59e0: 6f 74 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 74  ot an error.  It
59f0: 20 6a 75 73 74 20 6d 65 61 6e 73 20 74 68 61 74   just means that
5a00: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 20 77 69   no callback. wi
5a10: 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 0a  ll be invoked...
5a20: 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   If an error occ
5a30: 75 72 73 20 77 68 69 6c 65 20 70 61 72 73 69 6e  urs while parsin
5a40: 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20  g or evaluating 
5a50: 74 68 65 20 53 51 4c 20 28 62 75 74 0a 20 6e 6f  the SQL (but. no
5a60: 74 20 77 68 69 6c 65 20 65 78 65 63 75 74 69 6e  t while executin
5a70: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 29 20  g the callback) 
5a80: 74 68 65 6e 20 61 6e 20 61 70 70 72 6f 70 72 69  then an appropri
5a90: 61 74 65 20 65 72 72 6f 72 0a 20 6d 65 73 73 61  ate error. messa
5aa0: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
5ab0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
5ac0: 65 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29  ed from malloc()
5ad0: 20 61 6e 64 0a 20 2a 65 72 72 6d 73 67 20 69 73   and. *errmsg is
5ae0: 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
5af0: 6f 20 74 68 61 74 20 6d 65 73 73 61 67 65 2e 20  o that message. 
5b00: 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   The calling fun
5b10: 63 74 69 6f 6e 0a 20 69 73 20 72 65 73 70 6f 6e  ction. is respon
5b20: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
5b30: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  g the memory tha
5b40: 74 20 68 6f 6c 64 73 20 74 68 65 20 65 72 72 6f  t holds the erro
5b50: 72 0a 20 6d 65 73 73 61 67 65 2e 20 20 20 55 73  r. message.   Us
5b60: 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
5b70: 20 66 6f 72 20 74 68 69 73 2e 20 20 49 66 20 65   for this.  If e
5b80: 72 72 6d 73 67 3d 3d 4e 55 4c 4c 2c 0a 20 74 68  rrmsg==NULL,. th
5b90: 65 6e 20 6e 6f 20 65 72 72 6f 72 20 6d 65 73 73  en no error mess
5ba0: 61 67 65 20 69 73 20 65 76 65 72 20 77 72 69 74  age is ever writ
5bb0: 74 65 6e 2e 0a 0a 20 54 68 65 20 72 65 74 75 72  ten... The retur
5bc0: 6e 20 76 61 6c 75 65 20 69 73 20 69 73 20 53 51  n value is is SQ
5bd0: 4c 49 54 45 5f 4f 4b 20 69 66 20 74 68 65 72 65  LITE_OK if there
5be0: 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 20 61   are no errors a
5bf0: 6e 64 0a 20 73 6f 6d 65 20 6f 74 68 65 72 20 72  nd. some other r
5c00: 65 74 75 72 6e 20 63 6f 64 65 20 69 66 20 74 68  eturn code if th
5c10: 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  ere is an error.
5c20: 20 20 54 68 65 20 70 61 72 74 69 63 75 6c 61 72    The particular
5c30: 0a 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 64  . return value d
5c40: 65 70 65 6e 64 73 20 6f 6e 20 74 68 65 20 74 79  epends on the ty
5c50: 70 65 20 6f 66 20 65 72 72 6f 72 2e 20 0a 0a 20  pe of error. .. 
5c60: 49 66 20 74 68 65 20 71 75 65 72 79 20 63 6f 75  If the query cou
5c70: 6c 64 20 6e 6f 74 20 62 65 20 65 78 65 63 75 74  ld not be execut
5c80: 65 64 20 62 65 63 61 75 73 65 20 61 20 64 61 74  ed because a dat
5c90: 61 62 61 73 65 20 66 69 6c 65 20 69 73 0a 20 6c  abase file is. l
5ca0: 6f 63 6b 65 64 20 6f 72 20 62 75 73 79 2c 20 74  ocked or busy, t
5cb0: 68 65 6e 20 74 68 69 73 20 66 75 6e 63 74 69 6f  hen this functio
5cc0: 6e 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  n returns SQLITE
5cd0: 5f 42 55 53 59 2e 20 20 28 54 68 69 73 0a 20 62  _BUSY.  (This. b
5ce0: 65 68 61 76 69 6f 72 20 63 61 6e 20 62 65 20 6d  ehavior can be m
5cf0: 6f 64 69 66 69 65 64 20 73 6f 6d 65 77 68 61 74  odified somewhat
5d00: 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
5d10: 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
5d20: 29 0a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 62  ). and sqlite3_b
5d30: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 20 66 75  usy_timeout() fu
5d40: 6e 63 74 69 6f 6e 73 2e 29 0a 7d 20 7b 7d 0a 0a  nctions.).} {}..
5d50: 61 70 69 20 7b 7d 20 7b 0a 69 6e 74 20 73 71 6c  api {} {.int sql
5d60: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
5d70: 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
5d80: 74 29 3b 0a 7d 20 7b 0a 20 54 68 65 20 73 71 6c  t);.} {. The sql
5d90: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
5da0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
5db0: 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 70  ed to delete a p
5dc0: 72 65 70 61 72 65 64 0a 20 53 51 4c 20 73 74 61  repared. SQL sta
5dd0: 74 65 6d 65 6e 74 20 6f 62 74 61 69 6e 65 64 20  tement obtained 
5de0: 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
5df0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72  ll to sqlite3_pr
5e00: 65 70 61 72 65 28 29 0a 20 6f 72 20 73 71 6c 69  epare(). or sqli
5e10: 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 2e  te3_prepare16().
5e20: 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
5e30: 74 20 77 61 73 20 65 78 65 63 75 74 65 64 20 73  t was executed s
5e40: 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 6f 72 0a  uccessfully, or.
5e50: 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 74   not executed at
5e60: 20 61 6c 6c 2c 20 74 68 65 6e 20 53 51 4c 49 54   all, then SQLIT
5e70: 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64  E_OK is returned
5e80: 2e 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f  . If execution o
5e90: 66 20 74 68 65 0a 20 73 74 61 74 65 6d 65 6e 74  f the. statement
5ea0: 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 20   failed then an 
5eb0: 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
5ec0: 74 75 72 6e 65 64 2e 20 0a 0a 20 41 6c 6c 20 70  turned. .. All p
5ed0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
5ee0: 74 73 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  ts must finalize
5ef0: 64 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  d before sqlite3
5f00: 5f 63 6c 6f 73 65 28 29 20 69 73 0a 20 63 61 6c  _close() is. cal
5f10: 6c 65 64 20 6f 72 20 65 6c 73 65 20 74 68 65 20  led or else the 
5f20: 63 6c 6f 73 65 20 77 69 6c 6c 20 66 61 69 6c 20  close will fail 
5f30: 77 69 74 68 20 61 20 72 65 74 75 72 6e 20 63 6f  with a return co
5f40: 64 65 20 6f 66 20 53 51 4c 49 54 45 5f 42 55 53  de of SQLITE_BUS
5f50: 59 2e 0a 0a 20 54 68 69 73 20 72 6f 75 74 69 6e  Y... This routin
5f60: 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
5f70: 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
5f80: 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
5f90: 6e 20 6f 66 20 74 68 65 0a 20 76 69 72 74 75 61  n of the. virtua
5fa0: 6c 20 6d 61 63 68 69 6e 65 2e 20 20 49 66 20 74  l machine.  If t
5fb0: 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69  he virtual machi
5fc0: 6e 65 20 68 61 73 20 6e 6f 74 20 63 6f 6d 70 6c  ne has not compl
5fd0: 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 0a 20  eted execution. 
5fe0: 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  when this routin
5ff0: 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61  e is called, tha
6000: 74 20 69 73 20 6c 69 6b 65 20 65 6e 63 6f 75 6e  t is like encoun
6010: 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20  tering an error 
6020: 6f 72 0a 20 61 6e 20 69 6e 74 65 72 72 75 70 74  or. an interrupt
6030: 2e 20 20 28 53 65 65 20 73 71 6c 69 74 65 33 5f  .  (See sqlite3_
6040: 69 6e 74 65 72 72 75 70 74 28 29 2e 29 20 20 49  interrupt().)  I
6050: 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65  ncomplete update
6060: 73 20 6d 61 79 20 62 65 0a 20 72 6f 6c 6c 65 64  s may be. rolled
6070: 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61   back and transa
6080: 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 6c 65 64  ctions cancelled
6090: 2c 20 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ,  depending on 
60a0: 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  the circumstance
60b0: 73 2c 0a 20 61 6e 64 20 74 68 65 20 72 65 73 75  s,. and the resu
60c0: 6c 74 20 63 6f 64 65 20 72 65 74 75 72 6e 65 64  lt code returned
60d0: 20 77 69 6c 6c 20 62 65 20 53 51 4c 49 54 45 5f   will be SQLITE_
60e0: 41 42 4f 52 54 2e 0a 7d 0a 0a 61 70 69 20 7b 7d  ABORT..}..api {}
60f0: 20 7b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f   {.void sqlite3_
6100: 66 72 65 65 28 63 68 61 72 20 2a 7a 29 3b 0a 7d  free(char *z);.}
6110: 20 7b 0a 20 55 73 65 20 74 68 69 73 20 72 6f 75   {. Use this rou
6120: 74 69 6e 65 20 74 6f 20 66 72 65 65 20 6d 65 6d  tine to free mem
6130: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
6140: 6d 20 0a 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  m . sqlite3_mpri
6150: 6e 74 66 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ntf() or sqlite3
6160: 5f 76 6d 70 72 69 6e 74 66 28 29 2e 0a 7d 0a 0a  _vmprintf()..}..
6170: 61 70 69 20 7b 7d 20 7b 0a 69 6e 74 20 73 71 6c  api {} {.int sql
6180: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
6190: 20 20 73 71 6c 69 74 65 2a 2c 20 20 20 20 20 20    sqlite*,      
61a0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
61b0: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
61c0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71    const char *sq
61d0: 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
61e0: 74 6f 20 62 65 20 65 78 65 63 75 74 65 64 20 2a  to be executed *
61f0: 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 72 65 73 75  /.  char ***resu
6200: 6c 74 70 2c 20 20 20 20 20 20 20 2f 2a 20 52 65  ltp,       /* Re
6210: 73 75 6c 74 20 77 72 69 74 74 65 6e 20 74 6f 20  sult written to 
6220: 61 20 63 68 61 72 20 2a 5b 5d 20 20 74 68 61 74  a char *[]  that
6230: 20 74 68 69 73 20 70 6f 69 6e 74 73 20 74 6f 20   this points to 
6240: 2a 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20  */.  int *nrow, 
6250: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
6260: 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
6270: 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
6280: 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c  e */.  int *ncol
6290: 75 6d 6e 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  umn,          /*
62a0: 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
62b0: 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
62c0: 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
62d0: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20   **errmsg       
62e0: 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
62f0: 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
6300: 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
6310: 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
6320: 2a 2a 72 65 73 75 6c 74 29 3b 0a 7d 20 7b 0a 20  **result);.} {. 
6330: 54 68 69 73 20 6e 65 78 74 20 72 6f 75 74 69 6e  This next routin
6340: 65 20 69 73 20 72 65 61 6c 6c 79 20 6a 75 73 74  e is really just
6350: 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
6360: 64 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  d sqlite3_exec()
6370: 2e 0a 20 49 6e 73 74 65 61 64 20 6f 66 20 69 6e  .. Instead of in
6380: 76 6f 6b 69 6e 67 20 61 20 75 73 65 72 2d 73 75  voking a user-su
6390: 70 70 6c 69 65 64 20 63 61 6c 6c 62 61 63 6b 20  pplied callback 
63a0: 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20  for each row of 
63b0: 74 68 65 0a 20 72 65 73 75 6c 74 2c 20 74 68 69  the. result, thi
63c0: 73 20 72 6f 75 74 69 6e 65 20 72 65 6d 65 6d 62  s routine rememb
63d0: 65 72 73 20 65 61 63 68 20 72 6f 77 20 6f 66 20  ers each row of 
63e0: 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 6d 65  the result in me
63f0: 6d 6f 72 79 0a 20 6f 62 74 61 69 6e 65 64 20 66  mory. obtained f
6400: 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 2c 20 74 68  rom malloc(), th
6410: 65 6e 20 72 65 74 75 72 6e 73 20 61 6c 6c 20 6f  en returns all o
6420: 66 20 74 68 65 20 72 65 73 75 6c 74 20 61 66 74  f the result aft
6430: 65 72 20 74 68 65 0a 20 71 75 65 72 79 20 68 61  er the. query ha
6440: 73 20 66 69 6e 69 73 68 65 64 2e 20 0a 0a 20 41  s finished. .. A
6450: 73 20 61 6e 20 65 78 61 6d 70 6c 65 2c 20 73 75  s an example, su
6460: 70 70 6f 73 65 20 74 68 65 20 71 75 65 72 79 20  ppose the query 
6470: 72 65 73 75 6c 74 20 77 68 65 72 65 20 74 68 69  result where thi
6480: 73 20 74 61 62 6c 65 3a 0a 0a 20 3c 70 72 65 3e  s table:.. <pre>
6490: 0a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  .        Name   
64a0: 20 20 20 20 20 7c 20 41 67 65 0a 20 20 20 20 20       | Age.     
64b0: 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
64c0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 20 20 20 20 20  ----------.     
64d0: 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
64e0: 20 34 33 0a 20 20 20 20 20 20 20 20 42 6f 62 20   43.        Bob 
64f0: 20 20 20 20 20 20 20 20 7c 20 32 38 0a 20 20 20          | 28.   
6500: 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
6510: 20 7c 20 32 31 0a 20 3c 2f 70 72 65 3e 0a 0a 20   | 21. </pre>.. 
6520: 49 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  If the 3rd argum
6530: 65 6e 74 20 77 65 72 65 20 26 61 7a 52 65 73 75  ent were &azResu
6540: 6c 74 20 74 68 65 6e 20 61 66 74 65 72 20 74 68  lt then after th
6550: 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
6560: 6e 73 0a 20 61 7a 52 65 73 75 6c 74 20 77 69 6c  ns. azResult wil
6570: 6c 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 66 6f  l contain the fo
6580: 6c 6c 6f 77 69 6e 67 20 64 61 74 61 3a 0a 0a 20  llowing data:.. 
6590: 3c 70 72 65 3e 0a 20 20 20 20 20 20 20 20 61 7a  <pre>.        az
65a0: 52 65 73 75 6c 74 5b 30 5d 20 3d 20 22 4e 61 6d  Result[0] = "Nam
65b0: 65 22 3b 0a 20 20 20 20 20 20 20 20 61 7a 52 65  e";.        azRe
65c0: 73 75 6c 74 5b 31 5d 20 3d 20 22 41 67 65 22 3b  sult[1] = "Age";
65d0: 0a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  .        azResul
65e0: 74 5b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  t[2] = "Alice";.
65f0: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
6600: 5b 33 5d 20 3d 20 22 34 33 22 3b 0a 20 20 20 20  [3] = "43";.    
6610: 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 34 5d 20      azResult[4] 
6620: 3d 20 22 42 6f 62 22 3b 0a 20 20 20 20 20 20 20  = "Bob";.       
6630: 20 61 7a 52 65 73 75 6c 74 5b 35 5d 20 3d 20 22   azResult[5] = "
6640: 32 38 22 3b 0a 20 20 20 20 20 20 20 20 61 7a 52  28";.        azR
6650: 65 73 75 6c 74 5b 36 5d 20 3d 20 22 43 69 6e 64  esult[6] = "Cind
6660: 79 22 3b 0a 20 20 20 20 20 20 20 20 61 7a 52 65  y";.        azRe
6670: 73 75 6c 74 5b 37 5d 20 3d 20 22 32 31 22 3b 0a  sult[7] = "21";.
6680: 20 3c 2f 70 72 65 3e 0a 0a 20 4e 6f 74 69 63 65   </pre>.. Notice
6690: 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 61   that there is a
66a0: 6e 20 65 78 74 72 61 20 72 6f 77 20 6f 66 20 64  n extra row of d
66b0: 61 74 61 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ata containing t
66c0: 68 65 20 63 6f 6c 75 6d 6e 0a 20 68 65 61 64 65  he column. heade
66d0: 72 73 2e 20 20 42 75 74 20 74 68 65 20 2a 6e 72  rs.  But the *nr
66e0: 6f 77 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  ow return value 
66f0: 69 73 20 73 74 69 6c 6c 20 33 2e 20 20 2a 6e 63  is still 3.  *nc
6700: 6f 6c 75 6d 6e 20 69 73 0a 20 73 65 74 20 74 6f  olumn is. set to
6710: 20 32 2e 20 20 49 6e 20 67 65 6e 65 72 61 6c 2c   2.  In general,
6720: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76   the number of v
6730: 61 6c 75 65 73 20 69 6e 73 65 72 74 65 64 20 69  alues inserted i
6740: 6e 74 6f 20 61 7a 52 65 73 75 6c 74 0a 20 77 69  nto azResult. wi
6750: 6c 6c 20 62 65 20 28 28 2a 6e 72 6f 77 29 20 2b  ll be ((*nrow) +
6760: 20 31 29 2a 28 2a 6e 63 6f 6c 75 6d 6e 29 2e 0a   1)*(*ncolumn)..
6770: 0a 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c  . After the call
6780: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73  ing function has
6790: 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
67a0: 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73  the result, it s
67b0: 68 6f 75 6c 64 20 0a 20 70 61 73 73 20 74 68 65  hould . pass the
67c0: 20 72 65 73 75 6c 74 20 64 61 74 61 20 70 6f 69   result data poi
67d0: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
67e0: 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
67f0: 6f 72 64 65 72 20 74 6f 20 0a 20 72 65 6c 65 61  order to . relea
6800: 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
6810: 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 2d 65 64  at was malloc-ed
6820: 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
6830: 65 20 77 61 79 20 74 68 65 20 0a 20 6d 61 6c 6c  e way the . mall
6840: 6f 63 28 29 20 68 61 70 70 65 6e 73 2c 20 74 68  oc() happens, th
6850: 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
6860: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
6870: 74 6f 20 63 61 6c 6c 20 0a 20 6d 61 6c 6c 6f 63  to call . malloc
6880: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  () directly.  On
6890: 6c 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  ly sqlite3_free_
68a0: 74 61 62 6c 65 28 29 20 69 73 20 61 62 6c 65 20  table() is able 
68b0: 74 6f 20 72 65 6c 65 61 73 65 20 0a 20 74 68 65  to release . the
68c0: 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
68d0: 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 0a 20 54   and safely... T
68e0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
68f0: 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
6900: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 66  is the same as f
6910: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 78 65 63  rom sqlite3_exec
6920: 28 29 2e 0a 7d 0a 0a 61 70 69 20 7b 73 71 6c 69  ()..}..api {sqli
6930: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 7d 20 7b  te3_interrupt} {
6940: 0a 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  . void sqlite3_i
6950: 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 2a  nterrupt(sqlite*
6960: 29 3b 0a 7d 20 7b 0a 20 54 68 69 73 20 66 75 6e  );.} {. This fun
6970: 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
6980: 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
6990: 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
69a0: 62 6f 72 74 20 61 6e 64 0a 20 72 65 74 75 72 6e  bort and. return
69b0: 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
69c0: 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 20 54   opportunity.  T
69d0: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
69e0: 79 70 69 63 61 6c 6c 79 0a 20 63 61 6c 6c 65 64  ypically. called
69f0: 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
6a00: 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
6a10: 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
6a20: 43 61 6e 63 65 6c 22 0a 20 6f 72 20 43 74 72 6c  Cancel". or Ctrl
6a30: 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
6a40: 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
6a50: 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
6a60: 6f 20 68 61 6c 74 0a 20 69 6d 6d 65 64 69 61 74  o halt. immediat
6a70: 65 6c 79 2e 0a 7d 20 7b 7d 0a 0a 61 70 69 20 7b  ely..} {}..api {
6a80: 7d 20 7b 0a 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  } {.long long in
6a90: 74 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  t sqlite3_last_i
6aa0: 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
6ab0: 74 65 2a 29 3b 0a 7d 20 7b 0a 20 45 61 63 68 20  te*);.} {. Each 
6ac0: 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69  entry in an SQLi
6ad0: 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75  te table has a u
6ae0: 6e 69 71 75 65 20 69 6e 74 65 67 65 72 20 6b 65  nique integer ke
6af0: 79 2e 20 20 28 54 68 65 20 6b 65 79 20 69 73 0a  y.  (The key is.
6b00: 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
6b10: 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52  e INTEGER PRIMAR
6b20: 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 69 66 20  Y KEY column if 
6b30: 74 68 65 72 65 20 69 73 20 73 75 63 68 20 61 20  there is such a 
6b40: 63 6f 6c 75 6d 6e 2c 0a 20 6f 74 68 65 72 77 69  column,. otherwi
6b50: 73 65 20 74 68 65 20 6b 65 79 20 69 73 20 67 65  se the key is ge
6b60: 6e 65 72 61 74 65 64 20 61 74 20 72 61 6e 64 6f  nerated at rando
6b70: 6d 2e 20 20 54 68 65 20 75 6e 69 71 75 65 20 6b  m.  The unique k
6b80: 65 79 20 69 73 20 61 6c 77 61 79 73 0a 20 61 76  ey is always. av
6b90: 61 69 6c 61 62 6c 65 20 61 73 20 74 68 65 20 52  ailable as the R
6ba0: 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
6bb0: 4f 57 49 44 5f 20 63 6f 6c 75 6d 6e 2e 29 20 20  OWID_ column.)  
6bc0: 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 72 6f  The following ro
6bd0: 75 74 69 6e 65 0a 20 72 65 74 75 72 6e 73 20 74  utine. returns t
6be0: 68 65 20 69 6e 74 65 67 65 72 20 6b 65 79 20 6f  he integer key o
6bf0: 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
6c00: 74 20 69 6e 73 65 72 74 20 69 6e 20 74 68 65 20  t insert in the 
6c10: 64 61 74 61 62 61 73 65 2e 0a 0a 20 54 68 69 73  database... This
6c20: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 69 6d   function is sim
6c30: 69 6c 61 72 20 74 6f 20 74 68 65 20 6d 79 73 71  ilar to the mysq
6c40: 6c 5f 69 6e 73 65 72 74 5f 69 64 28 29 20 66 75  l_insert_id() fu
6c50: 6e 63 74 69 6f 6e 20 66 72 6f 6d 20 4d 79 53 51  nction from MySQ
6c60: 4c 2e 0a 7d 20 7b 7d 0a 0a 61 70 69 20 7b 7d 20  L..} {}..api {} 
6c70: 7b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  {.char *sqlite3_
6c80: 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
6c90: 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
6ca0: 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
6cb0: 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
6cc0: 5f 6c 69 73 74 29 3b 0a 7d 20 7b 0a 20 54 68 65  _list);.} {. The
6cd0: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
6ce0: 76 61 72 69 61 6e 74 73 20 6f 66 20 74 68 65 20  variants of the 
6cf0: 22 73 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  "sprintf()" from
6d00: 20 74 68 65 0a 20 73 74 61 6e 64 61 72 64 20 43   the. standard C
6d10: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
6d20: 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
6d30: 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
6d40: 6d 65 6d 6f 72 79 0a 20 6f 62 74 61 69 6e 65 64  memory. obtained
6d50: 20 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 20 73   from malloc() s
6d60: 6f 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20  o that there is 
6d70: 6e 65 76 65 72 20 61 20 70 6f 73 73 69 62 6c 69  never a possibli
6d80: 74 79 20 6f 66 20 62 75 66 66 65 72 0a 20 6f 76  ty of buffer. ov
6d90: 65 72 66 6c 6f 77 2e 20 20 54 68 65 73 65 20 72  erflow.  These r
6da0: 6f 75 74 69 6e 65 73 20 61 6c 73 6f 20 69 6d 70  outines also imp
6db0: 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
6dc0: 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
6dd0: 67 0a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  g. options that 
6de0: 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
6df0: 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
6e00: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 0a 20 54 68  statements... Th
6e10: 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
6e20: 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
6e30: 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 20 66  ines should be f
6e40: 72 65 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 0a  reed by calling.
6e50: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 2e   sqlite3_free().
6e60: 0a 0a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  .. All of the us
6e70: 75 61 6c 20 70 72 69 6e 74 66 20 66 6f 72 6d 61  ual printf forma
6e80: 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
6e90: 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
6ea0: 6e 2c 20 74 68 65 72 65 0a 20 69 73 20 61 20 22  n, there. is a "
6eb0: 25 71 22 20 6f 70 74 69 6f 6e 2e 20 20 25 71 20  %q" option.  %q 
6ec0: 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
6ed0: 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
6ee0: 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d  utes a null-term
6ef0: 69 6e 61 74 65 64 0a 20 73 74 72 69 6e 67 20 66  inated. string f
6f00: 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
6f10: 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
6f20: 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
6f30: 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
6f40: 2e 0a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  .. %q is designe
6f50: 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
6f60: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
6f70: 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  l.  By doubling 
6f80: 65 61 63 68 20 27 5c 27 27 0a 20 63 68 61 72 61  each '\''. chara
6f90: 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
6fa0: 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
6fb0: 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
6fc0: 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
6fd0: 0a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 0a 20  . the string... 
6fe0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 73 6f 20  For example, so 
6ff0: 73 6f 6d 65 20 73 74 72 69 6e 67 20 76 61 72 69  some string vari
7000: 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74 65  able contains te
7010: 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 0a  xt as follows:..
7020: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
7030: 65 3e 0a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  e>.  char *zText
7040: 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
7050: 20 64 61 79 21 22 3b 0a 20 3c 2f 70 72 65 3e 3c   day!";. </pre><
7060: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 20 4f  /blockquote>.. O
7070: 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
7080: 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
7090: 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
70a0: 6f 77 73 3a 0a 0a 20 3c 62 6c 6f 63 6b 71 75 6f  ows:.. <blockquo
70b0: 74 65 3e 3c 70 72 65 3e 0a 20 20 73 71 6c 69 74  te><pre>.  sqlit
70c0: 65 33 5f 65 78 65 63 5f 70 72 69 6e 74 66 28 64  e3_exec_printf(d
70d0: 62 2c 20 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  b, "INSERT INTO 
70e0: 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
70f0: 27 29 22 2c 0a 20 20 20 20 20 20 20 63 61 6c 6c  ')",.       call
7100: 62 61 63 6b 31 2c 20 30 2c 20 30 2c 20 7a 54 65  back1, 0, 0, zTe
7110: 78 74 29 3b 0a 20 20 3c 2f 70 72 65 3e 3c 2f 62  xt);.  </pre></b
7120: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 20 42 65 63  lockquote>.. Bec
7130: 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
7140: 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
7150: 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
7160: 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 20  acter in zText. 
7170: 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
7180: 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
7190: 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
71a0: 0a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  . <blockquote><p
71b0: 72 65 3e 0a 20 20 49 4e 53 45 52 54 20 49 4e 54  re>.  INSERT INT
71c0: 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
71d0: 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
71e0: 61 79 21 27 29 0a 20 3c 2f 70 72 65 3e 3c 2f 62  ay!'). </pre></b
71f0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 20 54 68 69  lockquote>.. Thi
7200: 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
7210: 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
7220: 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
7230: 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 20   generated SQL. 
7240: 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
7250: 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 0a 20 20  d like this:..  
7260: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
7270: 3e 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  >.  INSERT INTO 
7280: 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
7290: 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
72a0: 27 29 3b 0a 20 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ');.  </pre></bl
72b0: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 20 54 68 69 73  ockquote>.. This
72c0: 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
72d0: 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
72e0: 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
72f0: 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 0a 20  neral rule you. 
7300: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 20 75 73  should always us
7310: 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
7320: 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
7330: 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
7340: 72 69 6e 67 20 0a 20 6c 69 74 65 72 61 6c 2e 0a  ring . literal..
7350: 7d 20 7b 7d 0a 0a 61 70 69 20 7b 7d 20 7b 0a 69  } {}..api {} {.i
7360: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
7370: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
7380: 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
7390: 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
73a0: 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
73b0: 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
73c0: 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
73d0: 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
73e0: 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
73f0: 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
7400: 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
7410: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
7420: 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
7430: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
7440: 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
7450: 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
7460: 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 7d 20 7b 0a  andle */.);.} {.
7470: 20 4f 70 65 6e 20 74 68 65 20 73 71 6c 69 74 65   Open the sqlite
7480: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
7490: 66 69 6c 65 6e 61 6d 65 22 2e 20 20 54 68 65 20  filename".  The 
74a0: 22 66 69 6c 65 6e 61 6d 65 22 20 69 73 20 55 54  "filename" is UT
74b0: 46 2d 38 0a 20 65 6e 63 6f 64 65 64 20 66 6f 72  F-8. encoded for
74c0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
74d0: 61 6e 64 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  and UTF-16 encod
74e0: 65 64 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ed in the native
74f0: 20 62 79 74 65 20 6f 72 64 65 72 0a 20 66 6f 72   byte order. for
7500: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
7510: 29 2e 20 20 41 6e 20 73 71 6c 69 74 65 33 2a 20  ).  An sqlite3* 
7520: 68 61 6e 64 6c 65 20 69 73 20 72 65 74 75 72 6e  handle is return
7530: 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
7540: 6e 0a 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  n. if an error o
7550: 63 63 75 72 73 2e 20 49 66 20 74 68 65 20 64 61  ccurs. If the da
7560: 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
7570: 20 28 6f 72 20 63 72 65 61 74 65 64 29 20 73 75   (or created) su
7580: 63 63 65 73 73 66 75 6c 6c 79 2c 0a 20 74 68 65  ccessfully,. the
7590: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  n SQLITE_OK is r
75a0: 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69  eturned. Otherwi
75b0: 73 65 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65  se an error code
75c0: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68   is returned. Th
75d0: 65 0a 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  e. sqlite3_errms
75e0: 67 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 65  g() or sqlite3_e
75f0: 72 72 6d 73 67 31 36 28 29 20 20 72 6f 75 74 69  rrmsg16()  routi
7600: 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
7610: 74 6f 20 6f 62 74 61 69 6e 0a 20 61 6e 20 45 6e  to obtain. an En
7620: 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
7630: 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
7640: 65 20 65 72 72 6f 72 2e 0a 0a 20 49 66 20 74 68  e error... If th
7650: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
7660: 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2c 20  does not exist, 
7670: 74 68 65 6e 20 61 20 6e 65 77 20 64 61 74 61 62  then a new datab
7680: 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
7690: 74 65 64 0a 20 61 73 20 6e 65 65 64 65 64 2e 0a  ted. as needed..
76a0: 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 66 6f   The encoding fo
76b0: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  r the database w
76c0: 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 20  ill be UTF-8 if 
76d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 69  sqlite3_open() i
76e0: 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 20 55 54  s called and. UT
76f0: 46 2d 31 36 20 69 66 20 73 71 6c 69 74 65 33 5f  F-16 if sqlite3_
7700: 6f 70 65 6e 31 36 20 69 73 20 75 73 65 64 2e 0a  open16 is used..
7710: 0a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  . Whether or not
7720: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
7730: 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
7740: 65 64 2c 20 72 65 73 6f 75 72 63 65 73 20 61 73  ed, resources as
7750: 73 6f 63 69 61 74 65 64 0a 20 77 69 74 68 20 74  sociated. with t
7760: 68 65 20 73 71 6c 69 74 65 33 2a 20 68 61 6e 64  he sqlite3* hand
7770: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
7780: 65 61 73 65 64 20 62 79 20 70 61 73 73 69 6e 67  eased by passing
7790: 20 69 74 20 74 6f 0a 20 73 71 6c 69 74 65 33 5f   it to. sqlite3_
77a0: 63 6c 6f 73 65 28 29 20 77 68 65 6e 20 69 74 20  close() when it 
77b0: 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
77c0: 75 69 72 65 64 2e 0a 7d 0a 0a 61 70 69 20 7b 7d  uired..}..api {}
77d0: 20 7b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70   {.int sqlite3_p
77e0: 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
77f0: 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
7800: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
7810: 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
7820: 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
7830: 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
7840: 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
7850: 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
7860: 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  s,             /
7870: 2a 20 4c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  * Length of zSql
7880: 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
7890: 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
78a0: 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
78b0: 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
78c0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
78d0: 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
78e0: 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
78f0: 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
7900: 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
7910: 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
7920: 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
7930: 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
7940: 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
7950: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
7960: 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
7970: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
7980: 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
7990: 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 73 2c  */.  int nBytes,
79a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
79b0: 4c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  Length of zSql i
79c0: 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
79d0: 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
79e0: 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
79f0: 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
7a00: 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
7a10: 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
7a20: 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
7a30: 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
7a40: 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 7d 20 7b 0a   zSql */.);.} {.
7a50: 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
7a60: 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
7a70: 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
7a80: 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
7a90: 63 6f 64 65 0a 20 70 72 6f 67 72 61 6d 20 75 73  code. program us
7aa0: 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  ing one of the f
7ab0: 6f 6c 6c 6f 77 69 6e 67 20 72 6f 75 74 69 6e 65  ollowing routine
7ac0: 73 2e 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  s. The only diff
7ad0: 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 0a 20  erence between. 
7ae0: 74 68 65 6d 20 69 73 20 74 68 61 74 20 74 68 65  them is that the
7af0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
7b00: 2c 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65  , specifying the
7b10: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
7b20: 6f 0a 20 63 6f 6d 70 69 6c 65 2c 20 69 73 20 61  o. compile, is a
7b30: 73 73 75 6d 65 64 20 74 6f 20 62 65 20 65 6e 63  ssumed to be enc
7b40: 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f  oded in UTF-8 fo
7b50: 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  r the sqlite3_pr
7b60: 65 70 61 72 65 28 29 0a 20 66 75 6e 63 74 69 6f  epare(). functio
7b70: 6e 20 61 6e 64 20 55 54 46 2d 31 36 20 66 6f 72  n and UTF-16 for
7b80: 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
7b90: 31 36 28 29 2e 0a 0a 20 54 68 65 20 66 69 72 73  16()... The firs
7ba0: 74 20 70 61 72 61 6d 65 74 65 72 20 22 64 62 22  t parameter "db"
7bb0: 20 69 73 20 61 6e 20 53 51 4c 69 74 65 20 64 61   is an SQLite da
7bc0: 74 61 62 61 73 65 20 68 61 6e 64 6c 65 2e 20 54  tabase handle. T
7bd0: 68 65 20 73 65 63 6f 6e 64 0a 20 70 61 72 61 6d  he second. param
7be0: 65 74 65 72 20 22 7a 53 71 6c 22 20 69 73 20 74  eter "zSql" is t
7bf0: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
7c00: 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
7c10: 6f 64 65 64 20 61 73 20 65 69 74 68 65 72 0a 20  oded as either. 
7c20: 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
7c30: 28 73 65 65 20 61 62 6f 76 65 29 2e 20 49 66 20  (see above). If 
7c40: 74 68 65 20 6e 65 78 74 20 70 61 72 61 6d 65 74  the next paramet
7c50: 65 72 2c 20 22 6e 42 79 74 65 73 22 2c 20 69 73  er, "nBytes", is
7c60: 20 6c 65 73 73 0a 20 74 68 61 6e 20 7a 65 72 6f   less. than zero
7c70: 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
7c80: 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 66 69  ead up to the fi
7c90: 72 73 74 20 6e 75 6c 20 74 65 72 6d 69 6e 61 74  rst nul terminat
7ca0: 6f 72 2e 20 20 49 66 0a 20 22 6e 42 79 74 65 73  or.  If. "nBytes
7cb0: 22 20 69 73 20 6e 6f 74 20 6c 65 73 73 20 74 68  " is not less th
7cc0: 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 69 74  an zero, then it
7cd0: 20 69 73 20 74 68 65 20 6c 65 6e 67 74 68 20 6f   is the length o
7ce0: 66 20 74 68 65 20 73 74 72 69 6e 67 20 7a 53 71  f the string zSq
7cf0: 6c 0a 20 69 6e 20 62 79 74 65 73 20 28 6e 6f 74  l. in bytes (not
7d00: 20 63 68 61 72 61 63 74 65 72 73 29 2e 0a 0a 20   characters)... 
7d10: 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
7d20: 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
7d30: 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20  first byte past 
7d40: 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
7d50: 69 72 73 74 0a 20 53 51 4c 20 73 74 61 74 65 6d  irst. SQL statem
7d60: 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
7d70: 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
7d80: 63 6f 6d 70 69 6c 65 73 20 74 68 65 20 66 69 72  compiles the fir
7d90: 73 74 20 73 74 61 74 65 6d 65 6e 74 0a 20 69 6e  st statement. in
7da0: 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
7db0: 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
7dc0: 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69  ng to what remai
7dd0: 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 0a  ns uncompiled...
7de0: 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74   *ppStmt is left
7df0: 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
7e00: 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
7e10: 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 20 62  ement that can b
7e20: 65 0a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  e. executed usin
7e30: 67 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  g sqlite3_step()
7e40: 2e 20 20 4f 72 20 69 66 20 74 68 65 72 65 20 69  .  Or if there i
7e50: 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
7e60: 74 6d 74 20 6d 61 79 20 62 65 0a 20 73 65 74 20  tmt may be. set 
7e70: 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65  to NULL.  If the
7e80: 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
7e90: 61 69 6e 65 64 20 6e 6f 20 53 51 4c 20 28 69 66  ained no SQL (if
7ea0: 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
7eb0: 64 0a 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  d. empty string 
7ec0: 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
7ed0: 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
7ee0: 74 20 74 6f 20 4e 55 4c 4c 2e 0a 0a 20 4f 6e 20  t to NULL... On 
7ef0: 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f  success, SQLITE_
7f00: 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  OK is returned. 
7f10: 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   Otherwise an er
7f20: 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
7f30: 72 6e 65 64 2e 0a 7d 0a 0a 61 70 69 20 7b 7d 20  rned..}..api {} 
7f40: 7b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  {.void sqlite3_p
7f50: 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
7f60: 73 71 6c 69 74 65 2a 2c 20 69 6e 74 2c 20 69 6e  sqlite*, int, in
7f70: 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
7f80: 64 2a 29 3b 0a 7d 20 7b 0a 20 3c 69 3e 45 78 70  d*);.} {. <i>Exp
7f90: 65 72 69 6d 65 6e 74 61 6c 3c 2f 69 3e 0a 0a 20  erimental</i>.. 
7fa0: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e  This routine con
7fb0: 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61  figures a callba
7fc0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68  ck function - th
7fd0: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
7fe0: 61 63 6b 20 2d 20 74 68 61 74 0a 20 69 73 20 69  ack - that. is i
7ff0: 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
8000: 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
8010: 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
8020: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
8030: 0a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  . sqlite3_step()
8040: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 67 65 74   and sqlite3_get
8050: 5f 74 61 62 6c 65 28 29 2e 0a 20 41 6e 20 65 78  _table().. An ex
8060: 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
8070: 69 73 20 41 50 49 20 69 73 20 74 6f 20 6b 65 65  is API is to kee
8080: 70 0a 20 61 20 47 55 49 20 75 70 64 61 74 65 64  p. a GUI updated
8090: 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
80a0: 71 75 65 72 79 2e 0a 0a 20 54 68 65 20 70 72 6f  query... The pro
80b0: 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69  gress callback i
80c0: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66  s invoked once f
80d0: 6f 72 20 65 76 65 72 79 20 4e 20 76 69 72 74 75  or every N virtu
80e0: 61 6c 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64  al machine opcod
80f0: 65 73 2c 0a 20 77 68 65 72 65 20 4e 20 69 73 20  es,. where N is 
8100: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
8110: 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ent to this func
8120: 74 69 6f 6e 2e 20 54 68 65 20 70 72 6f 67 72 65  tion. The progre
8130: 73 73 20 63 61 6c 6c 62 61 63 6b 0a 20 69 74 73  ss callback. its
8140: 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69 65  elf is identifie
8150: 64 20 62 79 20 74 68 65 20 74 68 69 72 64 20 61  d by the third a
8160: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
8170: 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 66 6f  function. The fo
8180: 75 72 74 68 0a 20 61 72 67 75 6d 65 6e 74 20 74  urth. argument t
8190: 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
81a0: 69 73 20 61 20 76 6f 69 64 20 70 6f 69 6e 74 65  is a void pointe
81b0: 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
81c0: 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
81d0: 6b 0a 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68  k. function each
81e0: 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f   time it is invo
81f0: 6b 65 64 2e 0a 0a 20 49 66 20 61 20 63 61 6c 6c  ked... If a call
8200: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
8210: 28 29 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  (), sqlite3_step
8220: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 67 65  () or sqlite3_ge
8230: 74 5f 74 61 62 6c 65 28 29 20 72 65 73 75 6c 74  t_table() result
8240: 73 20 0a 20 69 6e 20 6c 65 73 73 20 74 68 61 6e  s . in less than
8250: 20 4e 20 6f 70 63 6f 64 65 73 20 62 65 69 6e 67   N opcodes being
8260: 20 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e 20   executed, then 
8270: 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
8280: 6c 62 61 63 6b 20 69 73 20 6e 6f 74 0a 20 69 6e  lback is not. in
8290: 76 6f 6b 65 64 2e 0a 20 0a 20 54 6f 20 72 65 6d  voked.. . To rem
82a0: 6f 76 65 20 74 68 65 20 70 72 6f 67 72 65 73 73  ove the progress
82b0: 20 63 61 6c 6c 62 61 63 6b 20 61 6c 74 6f 67 65   callback altoge
82c0: 74 68 65 72 2c 20 70 61 73 73 20 4e 55 4c 4c 20  ther, pass NULL 
82d0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 20 61 72  as the third. ar
82e0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66  gument to this f
82f0: 75 6e 63 74 69 6f 6e 2e 0a 0a 20 49 66 20 74 68  unction... If th
8300: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
8310: 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65  ack returns a re
8320: 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20  sult other than 
8330: 30 2c 20 74 68 65 6e 20 74 68 65 20 63 75 72 72  0, then the curr
8340: 65 6e 74 20 0a 20 71 75 65 72 79 20 69 73 20 69  ent . query is i
8350: 6d 6d 65 64 69 61 74 65 6c 79 20 74 65 72 6d 69  mmediately termi
8360: 6e 61 74 65 64 20 61 6e 64 20 61 6e 79 20 64 61  nated and any da
8370: 74 61 62 61 73 65 20 63 68 61 6e 67 65 73 20 72  tabase changes r
8380: 6f 6c 6c 65 64 20 62 61 63 6b 2e 20 49 66 20 74  olled back. If t
8390: 68 65 0a 20 71 75 65 72 79 20 77 61 73 20 70 61  he. query was pa
83a0: 72 74 20 6f 66 20 61 20 6c 61 72 67 65 72 20 74  rt of a larger t
83b0: 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
83c0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
83d0: 20 69 73 20 6e 6f 74 20 72 6f 6c 6c 65 64 0a 20   is not rolled. 
83e0: 62 61 63 6b 20 61 6e 64 20 72 65 6d 61 69 6e 73  back and remains
83f0: 20 61 63 74 69 76 65 2e 20 54 68 65 20 73 71 6c   active. The sql
8400: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
8410: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
8420: 41 42 4f 52 54 2e 20 0a 0a 7d 0a 0a 61 70 69 20  ABORT. ..}..api 
8430: 7b 7d 20 7b 0a 69 6e 74 20 73 71 6c 69 74 65 33  {} {.int sqlite3
8440: 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
8450: 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 7d 20 7b  tmt *pStmt);.} {
8460: 0a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  . The sqlite3_re
8470: 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
8480: 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
8490: 74 20 61 20 70 72 65 70 61 72 65 64 20 53 51 4c  t a prepared SQL
84a0: 0a 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 74 61  . statement obta
84b0: 69 6e 65 64 20 62 79 20 61 20 70 72 65 76 69 6f  ined by a previo
84c0: 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
84d0: 65 33 5f 70 72 65 70 61 72 65 28 29 20 6f 72 0a  e3_prepare() or.
84e0: 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
84f0: 31 36 28 29 20 62 61 63 6b 20 74 6f 20 69 74 27  16() back to it'
8500: 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
8510: 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
8520: 65 78 65 63 75 74 65 64 2e 0a 20 41 6e 79 20 53  executed.. Any S
8530: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
8540: 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
8550: 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
8560: 74 68 65 6d 20 75 73 69 6e 67 0a 20 74 68 65 20  them using. the 
8570: 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
8580: 20 41 50 49 20 72 65 74 61 69 6e 20 74 68 65 69   API retain thei
8590: 72 20 76 61 6c 75 65 73 2e 0a 7d 0a 0a 61 70 69  r values..}..api
85a0: 20 7b 7d 20 7b 0a 76 6f 69 64 20 73 71 6c 69 74   {} {.void sqlit
85b0: 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
85c0: 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
85d0: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
85e0: 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
85f0: 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
8600: 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
8610: 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
8620: 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
8630: 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
8640: 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
8650: 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
8660: 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
8670: 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
8680: 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
8690: 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
86a0: 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
86b0: 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
86c0: 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
86d0: 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
86e0: 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
86f0: 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
8700: 6e 74 65 78 74 2a 2c 20 6c 6f 6e 67 20 6c 6f 6e  ntext*, long lon
8710: 67 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  g int);.void sql
8720: 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
8730: 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
8740: 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
8750: 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
8760: 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
8770: 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
8780: 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
8790: 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
87a0: 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
87b0: 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
87c0: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
87d0: 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
87e0: 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
87f0: 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
8800: 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
8810: 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
8820: 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
8830: 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
8840: 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
8850: 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
8860: 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
8870: 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
8880: 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
8890: 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
88a0: 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
88b0: 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
88c0: 33 5f 76 61 6c 75 65 2a 29 3b 0a 7d 20 7b 0a 20  3_value*);.} {. 
88d0: 55 73 65 72 2d 64 65 66 69 6e 65 64 20 66 75 6e  User-defined fun
88e0: 63 74 69 6f 6e 73 20 69 6e 76 6f 6b 65 20 74 68  ctions invoke th
88f0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 72 6f 75 74  e following rout
8900: 69 6e 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  ines in order to
8910: 0a 20 73 65 74 20 74 68 65 69 72 20 72 65 74 75  . set their retu
8920: 72 6e 20 76 61 6c 75 65 2e 20 20 54 68 65 20 73  rn value.  The s
8930: 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
8940: 6c 75 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  lue() routine is
8950: 20 75 73 65 64 0a 20 74 6f 20 72 65 74 75 72 6e   used. to return
8960: 20 61 6e 20 65 78 61 63 74 20 63 6f 70 79 20 6f   an exact copy o
8970: 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 70 61 72  f one of the par
8980: 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 66  ameters to the f
8990: 75 6e 63 74 69 6f 6e 2e 0a 0a 20 54 68 65 20 6f  unction... The o
89a0: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  peration of thes
89b0: 65 20 72 6f 75 74 69 6e 65 73 20 69 73 20 76 65  e routines is ve
89c0: 72 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68  ry similar to th
89d0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 0a 20  e operation of. 
89e0: 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
89f0: 62 28 29 20 61 6e 64 20 69 74 73 20 63 6f 75 73  b() and its cous
8a00: 69 6e 73 2e 20 20 52 65 66 65 72 20 74 6f 20 74  ins.  Refer to t
8a10: 68 65 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  he documentation
8a20: 20 74 68 65 72 65 0a 20 66 6f 72 20 61 64 64 69   there. for addi
8a30: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
8a40: 6f 6e 2e 0a 7d 0a 0a 61 70 69 20 7b 7d 20 7b 0a  on..}..api {} {.
8a50: 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
8a60: 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
8a70: 6c 69 74 65 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  lite*,.  int (*x
8a80: 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
8a90: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
8aa0: 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
8ab0: 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
8ac0: 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
8ad0: 61 74 61 0a 29 3b 0a 23 64 65 66 69 6e 65 20 53  ata.);.#define S
8ae0: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
8af0: 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
8b00: 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
8b10: 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
8b20: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
8b30: 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
8b40: 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
8b50: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
8b60: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
8b70: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
8b80: 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
8b90: 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
8ba0: 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
8bb0: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
8bc0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8bd0: 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
8be0: 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
8bf0: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
8c00: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
8c10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8c20: 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
8c30: 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
8c40: 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
8c50: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
8c60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8c70: 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
8c80: 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
8c90: 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
8ca0: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
8cb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8cc0: 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
8cd0: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
8ce0: 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
8cf0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
8d00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
8d10: 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
8d20: 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
8d30: 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
8d40: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
8d50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
8d60: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
8d70: 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
8d80: 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
8d90: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
8da0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
8db0: 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
8dc0: 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
8dd0: 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
8de0: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
8df0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
8e00: 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
8e10: 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
8e20: 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
8e30: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
8e40: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
8e50: 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
8e60: 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
8e70: 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
8e80: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
8e90: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
8ea0: 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
8eb0: 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
8ec0: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
8ed0: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
8ee0: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
8ef0: 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
8f00: 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
8f10: 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
8f20: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
8f30: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
8f40: 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
8f50: 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
8f60: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
8f70: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
8f80: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
8f90: 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
8fa0: 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
8fb0: 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
8fc0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
8fd0: 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
8fe0: 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
8ff0: 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
9000: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
9010: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
9020: 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
9030: 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
9040: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
9050: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
9060: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
9070: 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
9080: 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
9090: 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
90a0: 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
90b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
90c0: 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
90d0: 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
90e0: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
90f0: 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
9100: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9110: 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
9120: 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
9130: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
9140: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
9150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
9160: 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
9170: 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55        22   /* NU
9180: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
9190: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
91a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
91b0: 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
91c0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
91d0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
91e0: 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
91f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
9200: 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
9210: 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
9220: 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
9230: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
9240: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
9250: 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
9260: 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
9270: 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
9280: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 23             */..#
9290: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
92a0: 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
92b0: 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
92c0: 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
92d0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
92e0: 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
92f0: 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
9300: 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
9310: 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
9320: 72 20 2a 2f 0a 7d 20 7b 0a 20 54 68 69 73 20 72  r */.} {. This r
9330: 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
9340: 20 61 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68   a callback with
9350: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
9360: 61 72 79 2e 20 20 54 68 65 0a 20 63 61 6c 6c 62  ary.  The. callb
9370: 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  ack is invoked (
9380: 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2c  at compile-time,
9390: 20 6e 6f 74 20 61 74 20 72 75 6e 2d 74 69 6d 65   not at run-time
93a0: 29 20 66 6f 72 20 65 61 63 68 0a 20 61 74 74 65  ) for each. atte
93b0: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 20 61 20  mpt to access a 
93c0: 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 74 61 62 6c  column of a tabl
93d0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
93e0: 65 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  e.  The callback
93f0: 0a 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  . returns SQLITE
9400: 5f 4f 4b 20 69 66 20 61 63 63 65 73 73 20 69 73  _OK if access is
9410: 20 61 6c 6c 6f 77 65 64 2c 20 53 51 4c 49 54 45   allowed, SQLITE
9420: 5f 44 45 4e 59 20 69 66 20 74 68 65 20 65 6e 74  _DENY if the ent
9430: 69 72 65 0a 20 53 51 4c 20 73 74 61 74 65 6d 65  ire. SQL stateme
9440: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6f  nt should be abo
9450: 72 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  rted with an err
9460: 6f 72 20 61 6e 64 20 53 51 4c 49 54 45 5f 49 47  or and SQLITE_IG
9470: 4e 4f 52 45 0a 20 69 66 20 74 68 65 20 63 6f 6c  NORE. if the col
9480: 75 6d 6e 20 73 68 6f 75 6c 64 20 62 65 20 74 72  umn should be tr
9490: 65 61 74 65 64 20 61 73 20 61 20 4e 55 4c 4c 20  eated as a NULL 
94a0: 76 61 6c 75 65 2e 0a 0a 20 54 68 65 20 73 65 63  value... The sec
94b0: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
94c0: 20 74 68 65 20 61 63 63 65 73 73 20 61 75 74 68   the access auth
94d0: 6f 72 69 7a 61 74 69 6f 6e 20 66 75 6e 63 74 69  orization functi
94e0: 6f 6e 20 61 62 6f 76 65 20 77 69 6c 6c 0a 20 62  on above will. b
94f0: 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 76 61 6c  e one of the val
9500: 75 65 73 20 62 65 6c 6f 77 2e 20 20 54 68 65 73  ues below.  Thes
9510: 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
9520: 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
9530: 65 72 61 74 69 6f 6e 0a 20 69 73 20 74 6f 20 62  eration. is to b
9540: 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  e authorized.  T
9550: 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
9560: 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
9570: 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 20   authorization. 
9580: 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
9590: 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
95a0: 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
95b0: 20 77 68 69 63 68 20 6f 66 20 74 68 65 20 66 6f   which of the fo
95c0: 6c 6c 6f 77 69 6e 67 0a 20 63 6f 64 65 73 20 69  llowing. codes i
95d0: 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
95e0: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
95f0: 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   The 5th paramet
9600: 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 20  er is the name. 
9610: 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
9620: 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
9630: 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
9640: 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70  able.  The 6th p
9650: 61 72 61 6d 65 74 65 72 0a 20 69 73 20 74 68 65  arameter. is the
9660: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
9670: 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
9680: 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
9690: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
96a0: 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
96b0: 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
96c0: 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
96d0: 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
96e0: 72 6f 6d 20 0a 20 69 6e 70 75 74 20 53 51 4c 20  rom . input SQL 
96f0: 63 6f 64 65 2e 0a 0a 20 54 68 65 20 72 65 74 75  code... The retu
9700: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
9710: 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 66 75  authorization fu
9720: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
9730: 20 6f 6e 65 20 6f 66 20 74 68 65 0a 20 63 6f 6e   one of the. con
9740: 73 74 61 6e 74 73 20 53 51 4c 49 54 45 5f 44 45  stants SQLITE_DE
9750: 4e 59 20 6f 72 20 53 51 4c 49 54 45 5f 49 47 4e  NY or SQLITE_IGN
9760: 4f 52 45 2e 0a 7d 0a 0a 61 70 69 20 7b 7d 20 7b  ORE..}..api {} {
9770: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
9780: 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
9790: 3b 0a 7d 20 7b 0a 20 41 66 74 65 72 20 61 6e 20  ;.} {. After an 
97a0: 53 51 4c 20 71 75 65 72 79 20 68 61 73 20 62 65  SQL query has be
97b0: 65 6e 20 70 72 65 70 61 72 65 64 20 77 69 74 68  en prepared with
97c0: 20 61 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65   a call to eithe
97d0: 72 0a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r. sqlite3_prepa
97e0: 72 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  re() or sqlite3_
97f0: 70 72 65 70 61 72 65 31 36 28 29 2c 20 74 68 65  prepare16(), the
9800: 6e 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  n this function 
9810: 6d 75 73 74 20 62 65 0a 20 63 61 6c 6c 65 64 20  must be. called 
9820: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
9830: 73 20 74 6f 20 65 78 65 63 75 74 65 20 74 68 65  s to execute the
9840: 20 73 74 61 74 65 6d 65 6e 74 2e 0a 0a 20 54 68   statement... Th
9850: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
9860: 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 53 51  ill be either SQ
9870: 4c 49 54 45 5f 42 55 53 59 2c 20 53 51 4c 49 54  LITE_BUSY, SQLIT
9880: 45 5f 44 4f 4e 45 2c 20 0a 20 53 51 4c 49 54 45  E_DONE, . SQLITE
9890: 5f 52 4f 57 2c 20 53 51 4c 49 54 45 5f 45 52 52  _ROW, SQLITE_ERR
98a0: 4f 52 2c 20 6f 72 20 53 51 4c 49 54 45 5f 4d 49  OR, or SQLITE_MI
98b0: 53 55 53 45 2e 0a 0a 20 53 51 4c 49 54 45 5f 42  SUSE... SQLITE_B
98c0: 55 53 59 20 6d 65 61 6e 73 20 74 68 61 74 20 74  USY means that t
98d0: 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
98e0: 6e 65 20 61 74 74 65 6d 70 74 65 64 20 74 6f 20  ne attempted to 
98f0: 6f 70 65 6e 0a 20 61 20 6c 6f 63 6b 65 64 20 64  open. a locked d
9900: 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 72  atabase and ther
9910: 65 20 69 73 20 6e 6f 20 62 75 73 79 20 63 61 6c  e is no busy cal
9920: 6c 62 61 63 6b 20 72 65 67 69 73 74 65 72 65 64  lback registered
9930: 2e 0a 20 43 61 6c 6c 20 73 71 6c 69 74 65 33 5f  .. Call sqlite3_
9940: 73 74 65 70 28 29 20 61 67 61 69 6e 20 74 6f 20  step() again to 
9950: 72 65 74 72 79 20 74 68 65 20 6f 70 65 6e 2e 0a  retry the open..
9960: 0a 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 6d 65  . SQLITE_DONE me
9970: 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
9980: 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
9990: 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 20 73  hed executing. s
99a0: 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
99b0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
99c0: 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
99d0: 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
99e0: 76 69 72 74 75 61 6c 0a 20 6d 61 63 68 69 6e 65  virtual. machine
99f0: 2e 0a 0a 20 49 66 20 74 68 65 20 53 51 4c 20 73  ... If the SQL s
9a00: 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
9a10: 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
9a20: 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 0a  any data, then .
9a30: 20 53 51 4c 49 54 45 5f 52 4f 57 20 69 73 20 72   SQLITE_ROW is r
9a40: 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
9a50: 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
9a60: 61 74 61 20 69 73 20 72 65 61 64 79 0a 20 66 6f  ata is ready. fo
9a70: 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
9a80: 74 68 65 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  the caller. The 
9a90: 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
9aa0: 63 65 73 73 65 64 20 75 73 69 6e 67 0a 20 74 68  cessed using. th
9ab0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
9ac0: 5f 2a 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 64  _*() functions d
9ad0: 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
9ae0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 20  sqlite3_step(). 
9af0: 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
9b00: 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
9b10: 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
9b20: 2e 0a 20 0a 20 53 51 4c 49 54 45 5f 45 52 52 4f  .. . SQLITE_ERRO
9b30: 52 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  R means that a r
9b40: 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
9b50: 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
9b60: 69 6e 74 0a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  int. violation) 
9b70: 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
9b80: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
9b90: 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
9ba0: 65 64 20 61 67 61 69 6e 20 6f 6e 0a 20 74 68 65  ed again on. the
9bb0: 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
9bc0: 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
9bd0: 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 73 71  nd by calling sq
9be0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 2e 0a  lite3_errmsg()..
9bf0: 0a 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  . SQLITE_MISUSE 
9c00: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
9c10: 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
9c20: 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
9c30: 69 61 74 65 6c 79 2e 0a 20 50 65 72 68 61 70 73  iately.. Perhaps
9c40: 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
9c50: 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
9c60: 69 6e 65 20 74 68 61 74 20 68 61 64 20 61 6c 72  ine that had alr
9c70: 65 61 64 79 20 62 65 65 6e 0a 20 66 69 6e 61 6c  eady been. final
9c80: 69 7a 65 64 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  ized or on one t
9c90: 68 61 74 20 68 61 64 20 70 72 65 76 69 6f 75 73  hat had previous
9ca0: 6c 79 20 72 65 74 75 72 6e 65 64 20 53 51 4c 49  ly returned SQLI
9cb0: 54 45 5f 45 52 52 4f 52 20 6f 72 0a 20 53 51 4c  TE_ERROR or. SQL
9cc0: 49 54 45 5f 44 4f 4e 45 2e 20 20 4f 72 20 69 74  ITE_DONE.  Or it
9cd0: 20 63 6f 75 6c 64 20 62 65 20 74 68 65 20 63 61   could be the ca
9ce0: 73 65 20 74 68 65 20 74 68 65 20 73 61 6d 65 20  se the the same 
9cf0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
9d00: 69 6f 6e 0a 20 69 73 20 62 65 69 6e 67 20 75 73  ion. is being us
9d10: 65 64 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73  ed simulataneous
9d20: 6c 79 20 62 79 20 74 77 6f 20 6f 72 20 6d 6f 72  ly by two or mor
9d30: 65 20 74 68 72 65 61 64 73 2e 0a 7d 0a 0a 61 70  e threads..}..ap
9d40: 69 20 7b 7d 20 7b 0a 76 6f 69 64 20 2a 73 71 6c  i {} {.void *sql
9d50: 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
9d60: 65 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  e*, void(*xTrace
9d70: 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
9d80: 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 7d 20  ar*), void*);.} 
9d90: 7b 0a 20 52 65 67 69 73 74 65 72 20 61 20 66 75  {. Register a fu
9da0: 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 63  nction that is c
9db0: 61 6c 6c 65 64 20 61 74 20 65 76 65 72 79 20 69  alled at every i
9dc0: 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 73 71 6c  nvocation of sql
9dd0: 69 74 65 33 5f 65 78 65 63 28 29 0a 20 6f 72 20  ite3_exec(). or 
9de0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
9df0: 29 2e 20 20 54 68 69 73 20 66 75 6e 63 74 69 6f  ).  This functio
9e00: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 28 66  n can be used (f
9e10: 6f 72 20 65 78 61 6d 70 6c 65 29 20 74 6f 20 67  or example) to g
9e20: 65 6e 65 72 61 74 65 0a 20 61 20 6c 6f 67 20 66  enerate. a log f
9e30: 69 6c 65 20 6f 66 20 61 6c 6c 20 53 51 4c 20 65  ile of all SQL e
9e40: 78 65 63 75 74 65 64 20 61 67 61 69 6e 73 74 20  xecuted against 
9e50: 61 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  a database.  Thi
9e60: 73 20 69 73 20 66 72 65 71 75 65 6e 74 6c 79 0a  s is frequently.
9e70: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 64 65 62   useful when deb
9e80: 75 67 67 69 6e 67 20 61 6e 20 61 70 70 6c 69 63  ugging an applic
9e90: 61 74 69 6f 6e 20 74 68 61 74 20 75 73 65 73 20  ation that uses 
9ea0: 53 51 4c 69 74 65 2e 0a 7d 0a 0a 61 70 69 20 7b  SQLite..}..api {
9eb0: 7d 20 7b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  } {.void *sqlite
9ec0: 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
9ed0: 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 7d  te3_context*);.}
9ee0: 20 7b 0a 20 54 68 65 20 70 55 73 65 72 44 61 74   {. The pUserDat
9ef0: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  a parameter to t
9f00: 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
9f10: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64  e_function() and
9f20: 0a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  . sqlite3_create
9f30: 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 72 6f  _function16() ro
9f40: 75 74 69 6e 65 73 20 75 73 65 64 20 74 6f 20 72  utines used to r
9f50: 65 67 69 73 74 65 72 20 75 73 65 72 20 66 75 6e  egister user fun
9f60: 63 74 69 6f 6e 73 0a 20 69 73 20 61 76 61 69 6c  ctions. is avail
9f70: 61 62 6c 65 20 74 6f 20 74 68 65 20 69 6d 70 6c  able to the impl
9f80: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
9f90: 65 20 66 75 6e 63 74 69 6f 6e 20 75 73 69 6e 67  e function using
9fa0: 20 74 68 69 73 0a 20 63 61 6c 6c 2e 0a 7d 0a 0a   this. call..}..
9fb0: 61 70 69 20 7b 7d 20 7b 0a 63 6f 6e 73 74 20 76  api {} {.const v
9fc0: 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
9fd0: 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
9fe0: 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
9ff0: 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
a000: 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
a010: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
a020: 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
a030: 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
a040: 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
a050: 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
a060: 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
a070: 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
a080: 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
a090: 0a 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73  .long long int s
a0a0: 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
a0b0: 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
a0c0: 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
a0d0: 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
a0e0: 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
a0f0: 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
a100: 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
a110: 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
a120: 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
a130: 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
a140: 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
a150: 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
a160: 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
a170: 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
a180: 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
a190: 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
a1a0: 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
a1b0: 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 7d  lite3_value*);.}
a1c0: 20 7b 0a 20 54 68 69 73 20 67 72 6f 75 70 20 6f   {. This group o
a1d0: 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
a1e0: 6e 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ns information a
a1f0: 62 6f 75 74 20 70 61 72 61 6d 65 74 65 72 73 20  bout parameters 
a200: 74 6f 0a 20 61 20 75 73 65 72 2d 64 65 66 69 6e  to. a user-defin
a210: 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 46 75  ed function.  Fu
a220: 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
a230: 61 74 69 6f 6e 73 20 75 73 65 20 74 68 65 73 65  ations use these
a240: 20 72 6f 75 74 69 6e 65 73 0a 20 74 6f 20 61 63   routines. to ac
a250: 63 65 73 73 20 74 68 65 69 72 20 70 61 72 61 6d  cess their param
a260: 65 74 65 72 73 2e 20 20 54 68 65 73 65 20 72 6f  eters.  These ro
a270: 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 73  utines are the s
a280: 61 6d 65 20 61 73 20 74 68 65 0a 20 73 71 6c 69  ame as the. sqli
a290: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75  te3_column_* rou
a2a0: 74 69 6e 65 73 20 65 78 63 65 70 74 20 74 68 61  tines except tha
a2b0: 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  t these routines
a2c0: 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 0a 20   take a single. 
a2d0: 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20 70  sqlite3_value* p
a2e0: 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
a2f0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 73 74 6d  f an sqlite3_stm
a300: 74 2a 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  t* and an intege
a310: 72 0a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  r. column number
a320: 2e 0a 7d 0a 0a 73 65 74 20 6e 20 30 0a 73 65 74  ..}..set n 0.set
a330: 20 69 20 30 0a 66 6f 72 65 61 63 68 20 69 74 65   i 0.foreach ite
a340: 6d 20 24 61 70 69 6c 69 73 74 20 7b 0a 20 20 73  m $apilist {.  s
a350: 65 74 20 6e 61 6d 65 6c 69 73 74 20 5b 6c 69 6e  et namelist [lin
a360: 64 65 78 20 24 69 74 65 6d 20 30 5d 0a 20 20 66  dex $item 0].  f
a370: 6f 72 65 61 63 68 20 6e 61 6d 65 20 24 6e 61 6d  oreach name $nam
a380: 65 6c 69 73 74 20 7b 0a 20 20 20 20 73 65 74 20  elist {.    set 
a390: 6e 5f 74 6f 5f 6e 61 6d 65 28 24 6e 29 20 24 6e  n_to_name($n) $n
a3a0: 61 6d 65 0a 20 20 20 20 73 65 74 20 6e 5f 74 6f  ame.    set n_to
a3b0: 5f 69 64 78 28 24 6e 29 20 24 69 0a 20 20 20 20  _idx($n) $i.    
a3c0: 73 65 74 20 6e 61 6d 65 5f 74 6f 5f 69 64 78 28  set name_to_idx(
a3d0: 24 6e 61 6d 65 29 20 24 69 0a 20 20 20 20 69 6e  $name) $i.    in
a3e0: 63 72 20 6e 0a 20 20 7d 0a 20 20 69 6e 63 72 20  cr n.  }.  incr 
a3f0: 69 0a 7d 0a 73 65 74 20 69 20 30 0a 66 6f 72 65  i.}.set i 0.fore
a400: 61 63 68 20 6e 61 6d 65 20 5b 6c 73 6f 72 74 20  ach name [lsort 
a410: 5b 61 72 72 61 79 20 6e 61 6d 65 73 20 6e 61 6d  [array names nam
a420: 65 5f 74 6f 5f 69 64 78 5d 5d 20 7b 0a 20 20 73  e_to_idx]] {.  s
a430: 65 74 20 73 6e 61 6d 65 28 24 69 29 20 24 6e 61  et sname($i) $na
a440: 6d 65 0a 20 20 69 6e 63 72 20 69 0a 7d 0a 70 75  me.  incr i.}.pu
a450: 74 73 20 7b 3c 74 61 62 6c 65 20 77 69 64 74 68  ts {<table width
a460: 3d 22 31 30 30 25 22 20 63 65 6c 6c 70 61 64 64  ="100%" cellpadd
a470: 69 6e 67 3d 22 35 22 3e 3c 74 72 3e 7d 0a 73 65  ing="5"><tr>}.se
a480: 74 20 6e 72 6f 77 20 5b 65 78 70 72 20 7b 28 24  t nrow [expr {($
a490: 6e 2b 32 29 2f 33 7d 5d 0a 73 65 74 20 69 20 30  n+2)/3}].set i 0
a4a0: 0a 66 6f 72 20 7b 73 65 74 20 6a 20 30 7d 20 7b  .for {set j 0} {
a4b0: 24 6a 3c 33 7d 20 7b 69 6e 63 72 20 6a 7d 20 7b  $j<3} {incr j} {
a4c0: 0a 20 20 69 66 20 7b 24 6a 3e 30 7d 20 7b 70 75  .  if {$j>0} {pu
a4d0: 74 73 20 7b 3c 74 64 20 77 69 64 74 68 3d 22 31  ts {<td width="1
a4e0: 30 22 3e 3c 2f 74 64 3e 7d 7d 0a 20 20 70 75 74  0"></td>}}.  put
a4f0: 73 20 7b 3c 74 64 20 76 61 6c 69 67 6e 3d 22 74  s {<td valign="t
a500: 6f 70 22 3e 7d 0a 20 20 73 65 74 20 6c 69 6d 69  op">}.  set limi
a510: 74 20 5b 65 78 70 72 20 7b 24 69 2b 24 6e 72 6f  t [expr {$i+$nro
a520: 77 7d 5d 0a 20 20 70 75 74 73 20 7b 3c 75 6c 3e  w}].  puts {<ul>
a530: 7d 0a 20 20 77 68 69 6c 65 20 7b 24 69 3c 24 6c  }.  while {$i<$l
a540: 69 6d 69 74 20 26 26 20 24 69 3c 24 6e 7d 20 7b  imit && $i<$n} {
a550: 0a 20 20 20 20 73 65 74 20 6e 61 6d 65 20 24 73  .    set name $s
a560: 6e 61 6d 65 28 24 69 29 0a 20 20 20 20 69 66 20  name($i).    if 
a570: 7b 5b 72 65 67 65 78 70 20 7b 5e 73 71 6c 69 74  {[regexp {^sqlit
a580: 65 7d 20 24 6e 61 6d 65 5d 7d 20 7b 73 65 74 20  e} $name]} {set 
a590: 64 69 73 70 6c 61 79 20 24 6e 61 6d 65 7d 20 7b  display $name} {
a5a0: 73 65 74 20 64 69 73 70 6c 61 79 20 3c 69 3e 24  set display <i>$
a5b0: 6e 61 6d 65 3c 2f 69 3e 7d 0a 20 20 20 20 70 75  name</i>}.    pu
a5c0: 74 73 20 22 3c 6c 69 3e 3c 61 20 68 72 65 66 3d  ts "<li><a href=
a5d0: 5c 22 23 24 6e 61 6d 65 5c 22 3e 24 64 69 73 70  \"#$name\">$disp
a5e0: 6c 61 79 3c 2f 61 3e 3c 2f 6c 69 3e 22 0a 20 20  lay</a></li>".  
a5f0: 20 20 69 6e 63 72 20 69 0a 20 20 7d 0a 20 20 70    incr i.  }.  p
a600: 75 74 73 20 7b 3c 2f 75 6c 3e 3c 2f 74 64 3e 7d  uts {</ul></td>}
a610: 0a 7d 0a 70 75 74 73 20 22 3c 2f 74 61 62 6c 65  .}.puts "</table
a620: 3e 22 0a 70 75 74 73 20 22 3c 21 2d 2d 20 24 6e  >".puts "<!-- $n
a630: 20 65 6e 74 72 69 65 73 2e 20 20 24 6e 72 6f 77   entries.  $nrow
a640: 20 72 6f 77 73 20 69 6e 20 33 20 63 6f 6c 75 6d   rows in 3 colum
a650: 6e 73 20 2d 2d 3e 22 0a 0a 70 72 6f 63 20 72 65  ns -->"..proc re
a660: 73 6f 6c 76 65 5f 6e 61 6d 65 20 7b 69 67 6e 6f  solve_name {igno
a670: 72 65 5f 6c 69 73 74 20 6e 61 6d 65 7d 20 7b 0a  re_list name} {.
a680: 20 20 67 6c 6f 62 61 6c 20 6e 61 6d 65 5f 74 6f    global name_to
a690: 5f 69 64 78 0a 20 20 69 66 20 7b 21 5b 69 6e 66  _idx.  if {![inf
a6a0: 6f 20 65 78 69 73 74 73 20 6e 61 6d 65 5f 74 6f  o exists name_to
a6b0: 5f 69 64 78 28 24 6e 61 6d 65 29 5d 20 7c 7c 20  _idx($name)] || 
a6c0: 5b 6c 73 65 61 72 63 68 20 24 69 67 6e 6f 72 65  [lsearch $ignore
a6d0: 5f 6c 69 73 74 20 24 6e 61 6d 65 5d 3e 3d 30 7d  _list $name]>=0}
a6e0: 20 7b 0a 20 20 20 20 72 65 74 75 72 6e 20 24 6e   {.    return $n
a6f0: 61 6d 65 0a 20 20 7d 20 65 6c 73 65 20 7b 0a 20  ame.  } else {. 
a700: 20 20 20 72 65 74 75 72 6e 20 22 3c 61 20 68 72     return "<a hr
a710: 65 66 3d 5c 22 23 24 6e 61 6d 65 5c 22 3e 24 6e  ef=\"#$name\">$n
a720: 61 6d 65 3c 2f 61 3e 22 0a 20 20 7d 0a 7d 0a 0a  ame</a>".  }.}..
a730: 66 6f 72 65 61 63 68 20 6e 61 6d 65 20 5b 6c 73  foreach name [ls
a740: 6f 72 74 20 5b 61 72 72 61 79 20 6e 61 6d 65 73  ort [array names
a750: 20 6e 61 6d 65 5f 74 6f 5f 69 64 78 5d 5d 20 7b   name_to_idx]] {
a760: 0a 20 20 73 65 74 20 69 20 24 6e 61 6d 65 5f 74  .  set i $name_t
a770: 6f 5f 69 64 78 28 24 6e 61 6d 65 29 0a 20 20 69  o_idx($name).  i
a780: 66 20 7b 5b 69 6e 66 6f 20 65 78 69 73 74 73 20  f {[info exists 
a790: 64 6f 6e 65 28 24 69 29 5d 7d 20 63 6f 6e 74 69  done($i)]} conti
a7a0: 6e 75 65 0a 20 20 73 65 74 20 64 6f 6e 65 28 24  nue.  set done($
a7b0: 69 29 20 31 0a 20 20 66 6f 72 65 61 63 68 20 7b  i) 1.  foreach {
a7c0: 6e 61 6d 65 6c 69 73 74 20 70 72 6f 74 6f 74 79  namelist prototy
a7d0: 70 65 20 64 65 73 63 7d 20 5b 6c 69 6e 64 65 78  pe desc} [lindex
a7e0: 20 24 61 70 69 6c 69 73 74 20 24 69 5d 20 62 72   $apilist $i] br
a7f0: 65 61 6b 0a 20 20 66 6f 72 65 61 63 68 20 6e 61  eak.  foreach na
a800: 6d 65 20 24 6e 61 6d 65 6c 69 73 74 20 7b 0a 20  me $namelist {. 
a810: 20 20 20 70 75 74 73 20 22 3c 61 20 6e 61 6d 65     puts "<a name
a820: 3d 5c 22 24 6e 61 6d 65 5c 22 3e 22 0a 20 20 7d  =\"$name\">".  }
a830: 0a 20 20 70 75 74 73 20 22 3c 70 3e 3c 68 72 3e  .  puts "<p><hr>
a840: 3c 2f 70 3e 22 0a 20 20 70 75 74 73 20 22 3c 62  </p>".  puts "<b
a850: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 22  lockquote><pre>"
a860: 0a 20 20 72 65 67 73 75 62 20 22 5e 28 20 2a 5c  .  regsub "^( *\
a870: 6e 29 2b 22 20 24 70 72 6f 74 6f 74 79 70 65 20  n)+" $prototype 
a880: 7b 7d 20 70 32 0a 20 20 72 65 67 73 75 62 20 22  {} p2.  regsub "
a890: 28 5c 6e 20 2a 29 2b 5c 24 22 20 24 70 32 20 7b  (\n *)+\$" $p2 {
a8a0: 7d 20 70 33 0a 20 20 70 75 74 73 20 24 70 33 0a  } p3.  puts $p3.
a8b0: 20 20 70 75 74 73 20 22 3c 2f 70 72 65 3e 3c 2f    puts "</pre></
a8c0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 22 0a 20 20 72  blockquote>".  r
a8d0: 65 67 73 75 62 20 2d 61 6c 6c 20 7b 5c 5b 7d 20  egsub -all {\[} 
a8e0: 24 64 65 73 63 20 7b 5c 5b 7d 20 64 65 73 63 0a  $desc {\[} desc.
a8f0: 20 20 72 65 67 73 75 62 20 2d 61 6c 6c 20 7b 73    regsub -all {s
a900: 71 6c 69 74 65 33 5f 5b 61 2d 7a 30 2d 39 5f 5d  qlite3_[a-z0-9_]
a910: 2b 7d 20 24 64 65 73 63 20 22 5c 5b 72 65 73 6f  +} $desc "\[reso
a920: 6c 76 65 5f 6e 61 6d 65 20 24 6e 61 6d 65 20 26  lve_name $name &
a930: 5c 5d 22 20 64 32 0a 20 20 72 65 67 73 75 62 20  \]" d2.  regsub 
a940: 2d 61 6c 6c 20 22 5c 6e 28 20 2a 5c 6e 29 2b 22  -all "\n( *\n)+"
a950: 20 5b 73 75 62 73 74 20 24 64 32 5d 20 22 3c 2f   [subst $d2] "</
a960: 70 3e 5c 6e 5c 6e 3c 70 3e 22 20 64 33 0a 20 20  p>\n\n<p>" d3.  
a970: 70 75 74 73 20 22 3c 70 3e 24 64 33 3c 2f 70 3e  puts "<p>$d3</p>
a980: 22 0a 7d 0a 0a 66 6f 6f 74 65 72 20 24 72 63 73  ".}..footer $rcs
a990: 69 64 0a                                         id.