Documentation Source Text

Hex Artifact Content
Login

Artifact bdd8d3d6e3ebbfe90fdbe3a08d34a93e41d5f544:


0000: 48 4c 52 20 48 31 30 30 31 31 20 53 36 30 31 30  HLR H10011 S6010
0010: 30 0a 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  0.The [SQLITE_VE
0020: 52 53 49 4f 4e 5d 20 23 64 65 66 69 6e 65 20 69  RSION] #define i
0030: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20  n the sqlite3.h 
0040: 68 65 61 64 65 72 20 66 69 6c 65 20 73 68 61 6c  header file shal
0050: 6c 0a 65 76 61 6c 75 61 74 65 20 74 6f 20 61 20  l.evaluate to a 
0060: 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74  string literal t
0070: 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74  hat is the SQLit
0080: 65 20 76 65 72 73 69 6f 6e 0a 77 69 74 68 20 77  e version.with w
0090: 68 69 63 68 20 74 68 65 20 68 65 61 64 65 72 20  hich the header 
00a0: 66 69 6c 65 20 69 73 20 61 73 73 6f 63 69 61 74  file is associat
00b0: 65 64 2e 0a 0a 48 4c 52 20 48 31 30 30 31 34 20  ed...HLR H10014 
00c0: 53 36 30 31 30 30 0a 54 68 65 20 5b 53 51 4c 49  S60100.The [SQLI
00d0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
00e0: 52 5d 20 23 64 65 66 69 6e 65 20 73 68 61 6c 6c  R] #define shall
00f0: 20 72 65 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69   resolve to an i
0100: 6e 74 65 67 65 72 0a 77 69 74 68 20 74 68 65 20  nteger.with the 
0110: 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30  value (X*1000000
0120: 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77   + Y*1000 + Z) w
0130: 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a  here X, Y, and Z
0140: 0a 61 72 65 20 74 68 65 20 6d 61 6a 6f 72 20 76  .are the major v
0150: 65 72 73 69 6f 6e 2c 20 6d 69 6e 6f 72 20 76 65  ersion, minor ve
0160: 72 73 69 6f 6e 2c 20 61 6e 64 20 72 65 6c 65 61  rsion, and relea
0170: 73 65 20 6e 75 6d 62 65 72 2e 0a 0a 48 4c 52 20  se number...HLR 
0180: 48 31 30 30 32 31 20 53 36 30 31 30 30 0a 54 68  H10021 S60100.Th
0190: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  e [sqlite3_libve
01a0: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 20  rsion_number()] 
01b0: 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
01c0: 72 65 74 75 72 6e 0a 61 6e 20 69 6e 74 65 67 65  return.an intege
01d0: 72 20 65 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49  r equal to [SQLI
01e0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
01f0: 52 5d 2e 0a 0a 48 4c 52 20 48 31 30 30 32 32 20  R]...HLR H10022 
0200: 53 36 30 31 30 30 0a 54 68 65 20 5b 73 71 6c 69  S60100.The [sqli
0210: 74 65 33 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72  te3_version] str
0220: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 73 68 61  ing constant sha
0230: 6c 6c 20 63 6f 6e 74 61 69 6e 0a 74 68 65 20 74  ll contain.the t
0240: 65 78 74 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ext of the [SQLI
0250: 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73 74 72 69  TE_VERSION] stri
0260: 6e 67 2e 0a 0a 48 4c 52 20 48 31 30 30 32 33 20  ng...HLR H10023 
0270: 53 36 30 31 30 30 0a 54 68 65 20 5b 73 71 6c 69  S60100.The [sqli
0280: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
0290: 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c  ] function shall
02a0: 20 72 65 74 75 72 6e 0a 61 20 70 6f 69 6e 74 65   return.a pointe
02b0: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
02c0: 33 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e  3_version] strin
02d0: 67 20 63 6f 6e 73 74 61 6e 74 2e 0a 0a 48 4c 52  g constant...HLR
02e0: 20 48 31 30 31 30 31 20 53 36 30 31 30 30 0a 54   H10101 S60100.T
02f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  he [sqlite3_thre
0300: 61 64 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69  adsafe()] functi
0310: 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  on shall return 
0320: 7a 65 72 6f 20 69 66 0a 61 6e 64 20 6f 6e 6c 79  zero if.and only
0330: 20 69 66 20 53 51 4c 69 74 65 20 77 61 73 20 63   if SQLite was c
0340: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74  ompiled with mut
0350: 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74  exing code omitt
0360: 65 64 2e 0a 0a 48 4c 52 20 48 31 30 31 30 32 20  ed...HLR H10102 
0370: 53 36 30 31 30 30 0a 54 68 65 20 76 61 6c 75 65  S60100.The value
0380: 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
0390: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
03a0: 28 29 5d 20 73 68 61 6c 6c 20 72 65 6d 61 69 6e  ()] shall remain
03b0: 20 74 68 65 20 73 61 6d 65 0a 61 63 72 6f 73 73   the same.across
03c0: 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
03d0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 0a 48  e3_config()]...H
03e0: 4c 52 20 48 31 30 32 30 31 20 53 31 30 31 31 30  LR H10201 S10110
03f0: 0a 54 68 65 20 5b 73 71 6c 69 74 65 5f 69 6e 74  .The [sqlite_int
0400: 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  64] and [sqlite3
0410: 5f 69 6e 74 36 34 5d 20 74 79 70 65 73 20 73 68  _int64] types sh
0420: 61 6c 6c 20 73 70 65 63 69 66 79 0a 61 20 36 34  all specify.a 64
0430: 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
0440: 67 65 72 2e 0a 0a 48 4c 52 20 48 31 30 32 30 32  ger...HLR H10202
0450: 20 53 31 30 31 31 30 0a 54 68 65 20 5b 73 71 6c   S10110.The [sql
0460: 69 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 20  ite_uint64] and 
0470: 5b 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 5d  [sqlite3_uint64]
0480: 20 74 79 70 65 73 20 73 68 61 6c 6c 20 73 70 65   types shall spe
0490: 63 69 66 79 0a 61 20 36 34 2d 62 69 74 20 75 6e  cify.a 64-bit un
04a0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a  signed integer..
04b0: 0a 0a 48 4c 52 20 48 31 30 33 33 31 20 53 33 30  ..HLR H10331 S30
04c0: 39 30 30 0a 41 20 73 75 63 63 65 73 73 66 75 6c  900.A successful
04d0: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
04e0: 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
04f0: 68 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 0a  hared_cache(B)].
0500: 77 69 6c 6c 20 65 6e 61 62 6c 65 20 6f 72 20 64  will enable or d
0510: 69 73 61 62 6c 65 20 73 68 61 72 65 64 20 63 61  isable shared ca
0520: 63 68 65 20 6d 6f 64 65 20 66 6f 72 20 73 75 62  che mode for sub
0530: 73 65 71 75 65 6e 74 6c 79 0a 63 72 65 61 74 65  sequently.create
0540: 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  d [database conn
0550: 65 63 74 69 6f 6e 5d 20 69 6e 20 74 68 65 20 73  ection] in the s
0560: 61 6d 65 20 70 72 6f 63 65 73 73 2e 0a 0a 48 4c  ame process...HL
0570: 52 20 48 31 30 33 33 36 20 53 33 30 39 30 30 0a  R H10336 S30900.
0580: 57 68 65 6e 20 73 68 61 72 65 64 20 63 61 63 68  When shared cach
0590: 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68  e is enabled, th
05a0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
05b0: 65 5f 6d 6f 64 75 6c 65 28 29 5d 0a 69 6e 74 65  e_module()].inte
05c0: 72 66 61 63 65 20 77 69 6c 6c 20 61 6c 77 61 79  rface will alway
05d0: 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  s return an erro
05e0: 72 2e 0a 0a 48 4c 52 20 48 31 30 33 33 37 20 53  r...HLR H10337 S
05f0: 33 30 39 30 30 0a 54 68 65 20 5b 73 71 6c 69 74  30900.The [sqlit
0600: 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
0610: 5f 63 61 63 68 65 28 42 29 5d 20 69 6e 74 65 72  _cache(B)] inter
0620: 66 61 63 65 20 72 65 74 75 72 6e 73 0a 5b 53 51  face returns.[SQ
0630: 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
0640: 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61  ed cache was ena
0650: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
0660: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 0a 0a   successfully...
0670: 48 4c 52 20 48 31 30 33 33 39 20 53 33 30 39 30  HLR H10339 S3090
0680: 30 0a 53 68 61 72 65 64 20 63 61 63 68 65 20 69  0.Shared cache i
0690: 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
06a0: 66 61 75 6c 74 2e 0a 0a 48 4c 52 20 48 31 30 35  fault...HLR H105
06b0: 31 31 20 53 37 30 32 30 30 0a 41 20 73 75 63 63  11 S70200.A succ
06c0: 65 73 73 66 75 6c 20 65 76 61 6c 75 61 74 69 6f  essful evaluatio
06d0: 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f  n of [sqlite3_co
06e0: 6d 70 6c 65 74 65 28 29 5d 20 6f 72 0a 5b 73 71  mplete()] or.[sq
06f0: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
0700: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 20 73 68  ()] functions sh
0710: 61 6c 6c 0a 72 65 74 75 72 6e 20 61 20 6e 75 6d  all.return a num
0720: 65 72 69 63 20 31 20 69 66 20 61 6e 64 20 6f 6e  eric 1 if and on
0730: 6c 79 20 69 66 20 74 68 65 20 69 6e 70 75 74 20  ly if the input 
0740: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 0a  string contains.
0750: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6e 6f 6e 2d  one or more non-
0760: 77 68 69 74 65 73 70 61 63 65 20 74 6f 6b 65 6e  whitespace token
0770: 73 20 61 6e 64 20 74 68 65 20 6c 61 73 74 20 6e  s and the last n
0780: 6f 6e 2d 77 68 69 74 65 73 70 61 63 65 0a 74 6f  on-whitespace.to
0790: 6b 65 6e 20 69 6e 20 69 73 20 61 20 73 65 6d 69  ken in is a semi
07a0: 63 6f 6c 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f  colon that is no
07b0: 74 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  t in the middle 
07c0: 6f 66 0a 61 20 5b 43 52 45 41 54 45 20 54 52 49  of.a [CREATE TRI
07d0: 47 47 45 52 5d 20 73 74 61 74 65 6d 65 6e 74 2e  GGER] statement.
07e0: 0a 0a 48 4c 52 20 48 31 30 35 31 32 20 53 37 30  ..HLR H10512 S70
07f0: 32 30 30 0a 49 66 20 61 20 6d 65 6d 6f 72 79 20  200.If a memory 
0800: 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
0810: 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 61   occurs during a
0820: 6e 20 69 6e 76 6f 63 61 74 69 6f 6e 0a 6f 66 20  n invocation.of 
0830: 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
0840: 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
0850: 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 74  _complete16()] t
0860: 68 65 6e 20 74 68 65 0a 72 6f 75 74 69 6e 65 20  hen the.routine 
0870: 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51  shall return [SQ
0880: 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 0a 48 4c  LITE_NOMEM]...HL
0890: 52 20 48 31 30 35 33 33 20 53 34 30 34 31 30 0a  R H10533 S40410.
08a0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65  The [sqlite3_sle
08b0: 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65  ep(M)] interface
08c0: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 6c   invokes the xSl
08d0: 65 65 70 0a 6d 65 74 68 6f 64 20 6f 66 20 74 68  eep.method of th
08e0: 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
08f0: 65 33 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f  e3_vfs|VFS] in o
0900: 72 64 65 72 20 74 6f 0a 73 75 73 70 65 6e 64 20  rder to.suspend 
0910: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
0920: 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
0930: 66 6f 72 20 61 74 20 6c 65 61 73 74 0a 4d 20 6d  for at least.M m
0940: 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 0a 48 4c  illiseconds...HL
0950: 52 20 48 31 30 35 33 36 20 53 34 30 34 31 30 0a  R H10536 S40410.
0960: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65  The [sqlite3_sle
0970: 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65  ep(M)] interface
0980: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
0990: 62 65 72 20 6f 66 0a 6d 69 6c 6c 69 73 65 63 6f  ber of.milliseco
09a0: 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
09b0: 75 61 6c 6c 79 20 72 65 71 75 65 73 74 65 64 20  ually requested 
09c0: 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  of the operating
09d0: 0a 73 79 73 74 65 6d 2c 20 77 68 69 63 68 20 6d  .system, which m
09e0: 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74  ight be larger t
09f0: 68 61 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65  han the paramete
0a00: 72 20 4d 2e 0a 0a 48 4c 52 20 48 31 31 32 30 33  r M...HLR H11203
0a10: 20 53 32 30 31 30 30 0a 54 68 65 20 5b 73 71 6c   S20100.The [sql
0a20: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 4e 29  ite3_vfs_find(N)
0a30: 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
0a40: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
0a50: 20 74 68 65 0a 72 65 67 69 73 74 65 72 65 64 20   the.registered 
0a60: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
0a70: 6a 65 63 74 20 77 68 6f 73 65 20 6e 61 6d 65 20  ject whose name 
0a80: 65 78 61 63 74 6c 79 20 6d 61 74 63 68 65 73 0a  exactly matches.
0a90: 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
0aa0: 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
0ab0: 20 4e 2c 20 6f 72 20 69 74 20 72 65 74 75 72 6e   N, or it return
0ac0: 73 20 4e 55 4c 4c 20 69 66 0a 74 68 65 72 65 20  s NULL if.there 
0ad0: 69 73 20 6e 6f 20 6d 61 74 63 68 2e 0a 0a 48 4c  is no match...HL
0ae0: 52 20 48 31 31 32 30 36 20 53 32 30 31 30 30 0a  R H11206 S20100.
0af0: 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  If the N paramet
0b00: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76  er to [sqlite3_v
0b10: 66 73 5f 66 69 6e 64 28 4e 29 5d 20 69 73 20 4e  fs_find(N)] is N
0b20: 55 4c 4c 20 74 68 65 6e 0a 74 68 65 20 66 75 6e  ULL then.the fun
0b30: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
0b40: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 64  pointer to the d
0b50: 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
0b60: 76 66 73 5d 0a 6f 62 6a 65 63 74 20 69 66 20 74  vfs].object if t
0b70: 68 65 72 65 20 69 73 20 6f 6e 65 2c 20 6f 72 20  here is one, or 
0b80: 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73  NULL if there is
0b90: 20 6e 6f 20 64 65 66 61 75 6c 74 0a 5b 73 71 6c   no default.[sql
0ba0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
0bb0: 2e 0a 0a 48 4c 52 20 48 31 31 32 30 39 20 53 32  ...HLR H11209 S2
0bc0: 30 31 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65  0100.The [sqlite
0bd0: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 50  3_vfs_register(P
0be0: 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,F)] interface r
0bf0: 65 67 69 73 74 65 72 73 20 74 68 65 0a 77 65 6c  egisters the.wel
0c00: 6c 2d 66 6f 72 6d 65 64 20 5b 73 71 6c 69 74 65  l-formed [sqlite
0c10: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 50 20  3_vfs] object P 
0c20: 75 73 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 67  using the name g
0c30: 69 76 65 6e 0a 62 79 20 74 68 65 20 7a 4e 61 6d  iven.by the zNam
0c40: 65 20 66 69 65 6c 64 20 6f 66 20 74 68 65 20 6f  e field of the o
0c50: 62 6a 65 63 74 20 50 2e 0a 0a 48 4c 52 20 48 31  bject P...HLR H1
0c60: 31 32 31 32 20 53 32 30 31 30 30 0a 55 73 69 6e  1212 S20100.Usin
0c70: 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  g the [sqlite3_v
0c80: 66 73 5f 72 65 67 69 73 74 65 72 28 50 2c 46 29  fs_register(P,F)
0c90: 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 72  ] interface to r
0ca0: 65 67 69 73 74 65 72 0a 74 68 65 20 73 61 6d 65  egister.the same
0cb0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
0cc0: 62 6a 65 63 74 20 6d 75 6c 74 69 70 6c 65 20 74  bject multiple t
0cd0: 69 6d 65 73 20 69 73 20 61 20 68 61 72 6d 6c 65  imes is a harmle
0ce0: 73 73 20 6e 6f 2d 6f 70 2e 0a 0a 48 4c 52 20 48  ss no-op...HLR H
0cf0: 31 31 32 31 35 20 53 32 30 31 30 30 0a 54 68 65  11215 S20100.The
0d00: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
0d10: 67 69 73 74 65 72 28 50 2c 46 29 5d 20 69 6e 74  gister(P,F)] int
0d20: 65 72 66 61 63 65 20 6d 61 6b 65 73 20 74 68 65  erface makes the
0d30: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 0a 6f   [sqlite3_vfs].o
0d40: 62 6a 65 63 74 20 50 20 74 68 65 20 64 65 66 61  bject P the defa
0d50: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
0d60: 5d 20 6f 62 6a 65 63 74 20 69 66 20 46 20 69 73  ] object if F is
0d70: 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 0a 48 4c 52 20   non-zero...HLR 
0d80: 48 31 31 32 31 38 20 53 32 30 31 30 30 0a 54 68  H11218 S20100.Th
0d90: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  e [sqlite3_vfs_u
0da0: 6e 72 65 67 69 73 74 65 72 28 50 29 5d 20 69 6e  nregister(P)] in
0db0: 74 65 72 66 61 63 65 20 75 6e 72 65 67 69 73 74  terface unregist
0dc0: 65 72 73 20 74 68 65 0a 5b 73 71 6c 69 74 65 33  ers the.[sqlite3
0dd0: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 50 20 73  _vfs] object P s
0de0: 6f 20 74 68 61 74 20 69 74 20 69 73 20 6e 6f 20  o that it is no 
0df0: 6c 6f 6e 67 65 72 20 72 65 74 75 72 6e 65 64 20  longer returned 
0e00: 62 79 0a 73 75 62 73 65 71 75 65 6e 74 20 63 61  by.subsequent ca
0e10: 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
0e20: 76 66 73 5f 66 69 6e 64 28 29 5d 2e 0a 0a 48 4c  vfs_find()]...HL
0e30: 52 20 48 31 31 33 30 32 20 53 37 30 33 30 30 0a  R H11302 S70300.
0e40: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  The [sqlite3_fin
0e50: 61 6c 69 7a 65 28 53 29 5d 20 69 6e 74 65 72 66  alize(S)] interf
0e60: 61 63 65 20 64 65 73 74 72 6f 79 73 20 74 68 65  ace destroys the
0e70: 0a 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65  .[prepared state
0e80: 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c 65  ment] S and rele
0e90: 61 73 65 73 20 61 6c 6c 0a 6d 65 6d 6f 72 79 20  ases all.memory 
0ea0: 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75 72 63  and file resourc
0eb0: 65 73 20 68 65 6c 64 20 62 79 20 74 68 61 74 20  es held by that 
0ec0: 6f 62 6a 65 63 74 2e 0a 0a 48 4c 52 20 48 31 31  object...HLR H11
0ed0: 33 30 34 20 53 37 30 33 30 30 0a 49 66 20 74 68  304 S70300.If th
0ee0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
0ef0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
0f00: 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
0f10: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
0f20: 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
0f30: 61 6e 20 65 72 72 6f 72 2c 0a 74 68 65 6e 20 5b  an error,.then [
0f40: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
0f50: 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68 61  (S)] returns tha
0f60: 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 0a 48  t same error...H
0f70: 4c 52 20 48 31 32 30 31 31 20 53 33 30 31 30 30  LR H12011 S30100
0f80: 0a 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  .A successful ca
0f90: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
0fa0: 6c 6f 73 65 28 43 29 5d 20 73 68 61 6c 6c 20 64  lose(C)] shall d
0fb0: 65 73 74 72 6f 79 20 74 68 65 0a 5b 64 61 74 61  estroy the.[data
0fc0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
0fd0: 20 6f 62 6a 65 63 74 20 43 2e 0a 0a 48 4c 52 20   object C...HLR 
0fe0: 48 31 32 30 31 32 20 53 33 30 31 30 30 0a 41 20  H12012 S30100.A 
0ff0: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
1000: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
1010: 65 28 43 29 5d 20 73 68 61 6c 6c 20 72 65 74 75  e(C)] shall retu
1020: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 0a 48  rn SQLITE_OK...H
1030: 4c 52 20 48 31 32 30 31 33 20 53 33 30 31 30 30  LR H12013 S30100
1040: 0a 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  .A successful ca
1050: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
1060: 6c 6f 73 65 28 43 29 5d 20 73 68 61 6c 6c 20 72  lose(C)] shall r
1070: 65 6c 65 61 73 65 20 61 6c 6c 0a 6d 65 6d 6f 72  elease all.memor
1080: 79 20 61 6e 64 20 73 79 73 74 65 6d 20 72 65 73  y and system res
1090: 6f 75 72 63 65 73 20 61 73 73 6f 63 69 61 74 65  ources associate
10a0: 64 20 77 69 74 68 20 5b 64 61 74 61 62 61 73 65  d with [database
10b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 2e 0a   connection] C..
10c0: 0a 48 4c 52 20 48 31 32 30 31 34 20 53 33 30 31  .HLR H12014 S301
10d0: 30 30 0a 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71  00.A call to [sq
10e0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
10f0: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
1100: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 20 74 68 61  onnection] C tha
1110: 74 0a 68 61 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  t.has one or mor
1120: 65 20 6f 70 65 6e 20 5b 70 72 65 70 61 72 65 64  e open [prepared
1130: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 68 61   statements] sha
1140: 6c 6c 20 66 61 69 6c 20 77 69 74 68 0a 61 6e 20  ll fail with.an 
1150: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72  [SQLITE_BUSY] er
1160: 72 6f 72 20 63 6f 64 65 2e 0a 0a 48 4c 52 20 48  ror code...HLR H
1170: 31 32 30 31 35 20 53 33 30 31 30 30 0a 41 20 63  12015 S30100.A c
1180: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1190: 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 72 65 20  close(C)] where 
11a0: 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  C is a NULL poin
11b0: 74 65 72 20 73 68 61 6c 6c 0a 62 65 20 61 20 68  ter shall.be a h
11c0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 20 72 65  armless no-op re
11d0: 74 75 72 6e 69 6e 67 20 53 51 4c 49 54 45 5f 4f  turning SQLITE_O
11e0: 4b 2e 0a 0a 48 4c 52 20 48 31 32 30 31 39 20 53  K...HLR H12019 S
11f0: 33 30 31 30 30 0a 57 68 65 6e 20 5b 73 71 6c 69  30100.When [sqli
1200: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 69 73  te3_close(C)] is
1210: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 5b 64   invoked on a [d
1220: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1230: 6f 6e 5d 20 43 0a 74 68 61 74 20 68 61 73 20 61  on] C.that has a
1240: 20 70 65 6e 64 69 6e 67 20 74 72 61 6e 73 61 63   pending transac
1250: 74 69 6f 6e 2c 20 74 68 65 20 74 72 61 6e 73 61  tion, the transa
1260: 63 74 69 6f 6e 20 73 68 61 6c 6c 20 62 65 0a 72  ction shall be.r
1270: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 0a 48 4c 52  olled back...HLR
1280: 20 48 31 32 31 30 31 20 53 31 30 30 30 30 0a 41   H12101 S10000.A
1290: 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
12a0: 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
12b0: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c  e3_exec(D,S,C,A,
12c0: 45 29 5d 0a 73 68 61 6c 6c 20 73 65 71 75 65 6e  E)].shall sequen
12d0: 74 69 61 6c 6c 79 20 65 76 61 6c 75 61 74 65 20  tially evaluate 
12e0: 61 6c 6c 20 6f 66 20 74 68 65 20 55 54 46 2d 38  all of the UTF-8
12f0: 20 65 6e 63 6f 64 65 64 2c 0a 73 65 6d 69 63 6f   encoded,.semico
1300: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
1310: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
1320: 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1330: 74 65 64 0a 73 74 72 69 6e 67 20 53 20 77 69 74  ted.string S wit
1340: 68 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20  hin the context 
1350: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
1360: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
1370: 0a 48 4c 52 20 48 31 32 31 30 32 20 53 31 30 30  .HLR H12102 S100
1380: 30 30 0a 49 66 20 74 68 65 20 53 20 70 61 72 61  00.If the S para
1390: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
13a0: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
13b0: 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a  )] is NULL then.
13c0: 74 68 65 20 61 63 74 69 6f 6e 73 20 6f 66 20 74  the actions of t
13d0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  he interface sha
13e0: 6c 6c 20 62 65 20 74 68 65 20 73 61 6d 65 20 61  ll be the same a
13f0: 73 20 69 66 20 74 68 65 0a 53 20 70 61 72 61 6d  s if the.S param
1400: 65 74 65 72 20 77 65 72 65 20 61 6e 20 65 6d 70  eter were an emp
1410: 74 79 20 73 74 72 69 6e 67 2e 0a 0a 48 4c 52 20  ty string...HLR 
1420: 48 31 32 31 30 34 20 53 31 30 30 30 30 0a 54 68  H12104 S10000.Th
1430: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
1440: 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  f [sqlite3_exec(
1450: 29 5d 20 73 68 61 6c 6c 20 62 65 20 5b 53 51 4c  )] shall be [SQL
1460: 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6c 6c 0a 53  ITE_OK] if all.S
1470: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 72 75  QL statements ru
1480: 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61  n successfully a
1490: 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  nd to completion
14a0: 2e 0a 0a 48 4c 52 20 48 31 32 31 30 35 20 53 31  ...HLR H12105 S1
14b0: 30 30 30 30 0a 54 68 65 20 72 65 74 75 72 6e 20  0000.The return 
14c0: 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
14d0: 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20  3_exec()] shall 
14e0: 62 65 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  be an appropriat
14f0: 65 0a 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  e.non-zero [erro
1500: 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 20 53  r code] if any S
1510: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69  QL statement fai
1520: 6c 73 2e 0a 0a 48 4c 52 20 48 31 32 31 30 37 20  ls...HLR H12107 
1530: 53 31 30 30 30 30 0a 49 66 20 6f 6e 65 20 6f 72  S10000.If one or
1540: 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 53 51 4c   more of the SQL
1550: 20 73 74 61 74 65 6d 65 6e 74 73 20 68 61 6e 64   statements hand
1560: 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ed to [sqlite3_e
1570: 78 65 63 28 29 5d 0a 72 65 74 75 72 6e 20 72 65  xec()].return re
1580: 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20 33 72  sults and the 3r
1590: 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
15a0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 74 68  ot NULL, then.th
15b0: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
15c0: 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79  ion specified by
15d0: 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
15e0: 65 72 20 73 68 61 6c 6c 20 62 65 0a 69 6e 76 6f  er shall be.invo
15f0: 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  ked once for eac
1600: 68 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e  h row of result.
1610: 0a 0a 48 4c 52 20 48 31 32 31 31 30 20 53 31 30  ..HLR H12110 S10
1620: 30 30 30 0a 49 66 20 74 68 65 20 63 61 6c 6c 62  000.If the callb
1630: 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ack returns a no
1640: 6e 2d 7a 65 72 6f 20 76 61 6c 75 65 20 74 68 65  n-zero value the
1650: 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  n [sqlite3_exec(
1660: 29 5d 0a 73 68 61 6c 6c 20 61 62 6f 72 74 20 74  )].shall abort t
1670: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1680: 20 69 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79   it is currently
1690: 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a 73 6b 69   evaluating,.ski
16a0: 70 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  p all subsequent
16b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c   SQL statements,
16c0: 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
16d0: 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 0a 48 4c 52  ITE_ABORT]...HLR
16e0: 20 48 31 32 31 31 33 20 53 31 30 30 30 30 0a 54   H12113 S10000.T
16f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  he [sqlite3_exec
1700: 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c  ()] routine shal
1710: 6c 20 70 61 73 73 20 69 74 73 20 34 74 68 20 70  l pass its 4th p
1720: 61 72 61 6d 65 74 65 72 20 74 68 72 6f 75 67 68  arameter through
1730: 0a 61 73 20 74 68 65 20 31 73 74 20 70 61 72 61  .as the 1st para
1740: 6d 65 74 65 72 20 6f 66 20 74 68 65 20 63 61 6c  meter of the cal
1750: 6c 62 61 63 6b 2e 0a 0a 48 4c 52 20 48 31 32 31  lback...HLR H121
1760: 31 36 20 53 31 30 30 30 30 0a 54 68 65 20 5b 73  16 S10000.The [s
1770: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
1780: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74  outine shall set
1790: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
17a0: 65 72 20 6f 66 20 69 74 73 0a 63 61 6c 6c 62 61  er of its.callba
17b0: 63 6b 20 74 6f 20 62 65 20 74 68 65 20 6e 75 6d  ck to be the num
17c0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
17d0: 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
17e0: 77 20 6f 66 0a 72 65 73 75 6c 74 2e 0a 0a 48 4c  w of.result...HL
17f0: 52 20 48 31 32 31 31 39 20 53 31 30 30 30 30 0a  R H12119 S10000.
1800: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
1810: 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61  c()] routine sha
1820: 6c 6c 20 73 65 74 20 74 68 65 20 33 72 64 20 70  ll set the 3rd p
1830: 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a  arameter of its.
1840: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61  callback to be a
1850: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
1860: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68  ers to strings h
1870: 6f 6c 64 69 6e 67 20 74 68 65 0a 76 61 6c 75 65  olding the.value
1880: 73 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  s for each colum
1890: 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
18a0: 20 72 65 73 75 6c 74 20 73 65 74 20 72 6f 77 20   result set row 
18b0: 61 73 0a 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  as.obtained from
18c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
18d0: 5f 74 65 78 74 28 29 5d 2e 0a 0a 48 4c 52 20 48  _text()]...HLR H
18e0: 31 32 31 32 32 20 53 31 30 30 30 30 0a 54 68 65  12122 S10000.The
18f0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1900: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
1910: 73 65 74 20 74 68 65 20 34 74 68 20 70 61 72 61  set the 4th para
1920: 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 63 61 6c  meter of its.cal
1930: 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61  lback to be an a
1940: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
1950: 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64   to strings hold
1960: 69 6e 67 20 74 68 65 0a 6e 61 6d 65 73 20 6f 66  ing the.names of
1970: 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
1980: 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  as obtained from
1990: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
19a0: 5f 6e 61 6d 65 28 29 5d 2e 0a 0a 48 4c 52 20 48  _name()]...HLR H
19b0: 31 32 31 32 35 20 53 31 30 30 30 30 0a 49 66 20  12125 S10000.If 
19c0: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
19d0: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  r to [sqlite3_ex
19e0: 65 63 28 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68  ec()] is NULL th
19f0: 65 6e 0a 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  en.[sqlite3_exec
1a00: 28 29 5d 20 73 68 61 6c 6c 20 73 69 6c 65 6e 74  ()] shall silent
1a10: 6c 79 20 64 69 73 63 61 72 64 20 71 75 65 72 79  ly discard query
1a20: 20 72 65 73 75 6c 74 73 2e 0a 0a 48 4c 52 20 48   results...HLR H
1a30: 31 32 31 33 31 20 53 31 30 30 30 30 0a 49 66 20  12131 S10000.If 
1a40: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
1a50: 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72  while parsing or
1a60: 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20   evaluating any 
1a70: 6f 66 20 74 68 65 20 53 51 4c 0a 73 74 61 74 65  of the SQL.state
1a80: 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 53 20 70  ments in the S p
1a90: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
1aa0: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c  ite3_exec(D,S,C,
1ab0: 41 2c 45 29 5d 20 61 6e 64 20 69 66 0a 74 68 65  A,E)] and if.the
1ac0: 20 45 20 70 61 72 61 6d 65 74 65 72 20 69 73 20   E parameter is 
1ad0: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b  not NULL, then [
1ae0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
1af0: 73 68 61 6c 6c 20 73 74 6f 72 65 0a 69 6e 20 2a  shall store.in *
1b00: 45 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  E an appropriate
1b10: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77   error message w
1b20: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
1b30: 72 79 20 6f 62 74 61 69 6e 65 64 0a 66 72 6f 6d  ry obtained.from
1b40: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1b50: 28 29 5d 2e 0a 0a 48 4c 52 20 48 31 32 31 33 34  ()]...HLR H12134
1b60: 20 53 31 30 30 30 30 0a 54 68 65 20 5b 73 71 6c   S10000.The [sql
1b70: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c  ite3_exec(D,S,C,
1b80: 41 2c 45 29 5d 20 72 6f 75 74 69 6e 65 20 73 68  A,E)] routine sh
1b90: 61 6c 6c 20 73 65 74 20 74 68 65 20 76 61 6c 75  all set the valu
1ba0: 65 20 6f 66 0a 2a 45 20 74 6f 20 4e 55 4c 4c 20  e of.*E to NULL 
1bb0: 69 66 20 45 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  if E is not NULL
1bc0: 20 61 6e 64 20 74 68 65 72 65 20 61 72 65 20 6e   and there are n
1bd0: 6f 20 65 72 72 6f 72 73 2e 0a 0a 48 4c 52 20 48  o errors...HLR H
1be0: 31 32 31 33 37 20 53 31 30 30 30 30 0a 54 68 65  12137 S10000.The
1bf0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44   [sqlite3_exec(D
1c00: 2c 53 2c 43 2c 41 2c 45 29 5d 20 66 75 6e 63 74  ,S,C,A,E)] funct
1c10: 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 74 68  ion shall set th
1c20: 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 0a 61  e [error code].a
1c30: 6e 64 20 6d 65 73 73 61 67 65 20 61 63 63 65 73  nd message acces
1c40: 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74  sible via [sqlit
1c50: 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 5b  e3_errcode()],.[
1c60: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
1c70: 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 5b 73 71  _errcode()],.[sq
1c80: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c  lite3_errmsg()],
1c90: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
1ca0: 72 6d 73 67 31 36 28 29 5d 2e 0a 0a 48 4c 52 20  rmsg16()]...HLR 
1cb0: 48 31 32 31 33 38 20 53 31 30 30 30 30 0a 49 66  H12138 S10000.If
1cc0: 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72   the S parameter
1cd0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
1ce0: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73  c(D,S,C,A,E)] is
1cf0: 20 4e 55 4c 4c 20 6f 72 20 61 6e 0a 65 6d 70 74   NULL or an.empt
1d00: 79 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e 74  y string or cont
1d10: 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68  ains nothing oth
1d20: 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61  er than whitespa
1d30: 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a 61 6e  ce, comments,.an
1d40: 64 2f 6f 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c  d/or semicolons,
1d50: 20 74 68 65 6e 20 72 65 73 75 6c 74 73 20 6f 66   then results of
1d60: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1d70: 65 28 29 5d 2c 0a 5b 73 71 6c 69 74 65 33 5f 65  e()],.[sqlite3_e
1d80: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
1d90: 29 5d 2c 0a 5b 73 71 6c 69 74 65 33 5f 65 72 72  )],.[sqlite3_err
1da0: 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  msg()], and [sql
1db0: 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
1dc0: 0a 73 68 61 6c 6c 20 72 65 73 65 74 20 74 6f 20  .shall reset to 
1dd0: 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 72 72 6f  indicate no erro
1de0: 72 73 2e 0a 0a 48 4c 52 20 48 31 32 32 30 31 20  rs...HLR H12201 
1df0: 53 31 30 37 30 30 0a 45 61 63 68 20 6e 65 77 20  S10700.Each new 
1e00: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1e10: 74 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 61 76 65  tion] shall have
1e20: 20 74 68 65 0a 5b 65 78 74 65 6e 64 65 64 20 72   the.[extended r
1e30: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
1e40: 74 75 72 65 20 64 69 73 61 62 6c 65 64 20 62 79  ture disabled by
1e50: 20 64 65 66 61 75 6c 74 2e 0a 0a 48 4c 52 20 48   default...HLR H
1e60: 31 32 32 30 32 20 53 31 30 37 30 30 0a 54 68 65  12202 S10700.The
1e70: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
1e80: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
1e90: 44 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20  D,F)] interface 
1ea0: 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a 5b 65 78  shall enable.[ex
1eb0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
1ec0: 64 65 73 5d 20 66 6f 72 20 74 68 65 20 20 5b 64  des] for the  [d
1ed0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ee0: 6f 6e 5d 20 44 0a 69 66 20 74 68 65 20 46 20 70  on] D.if the F p
1ef0: 61 72 61 6d 65 74 65 72 20 69 73 20 74 72 75 65  arameter is true
1f00: 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  , or disable the
1f10: 6d 20 69 66 20 46 20 69 73 20 66 61 6c 73 65 2e  m if F is false.
1f20: 0a 0a 48 4c 52 20 48 31 32 32 32 31 20 53 31 30  ..HLR H12221 S10
1f30: 37 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65 33  700.The [sqlite3
1f40: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1f50: 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73  id()] function s
1f60: 68 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  hall return the 
1f70: 72 6f 77 69 64 0a 6f 66 20 74 68 65 20 6d 6f 73  rowid.of the mos
1f80: 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
1f90: 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 70 65 72  ful [INSERT] per
1fa0: 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20 73 61  formed on the sa
1fb0: 6d 65 0a 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me.[database con
1fc0: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 77 69 74  nection] and wit
1fd0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20  hin the same or 
1fe0: 68 69 67 68 65 72 20 6c 65 76 65 6c 0a 74 72 69  higher level.tri
1ff0: 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72  gger context, or
2000: 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 68   zero if there h
2010: 61 76 65 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c  ave been no qual
2020: 69 66 79 69 6e 67 0a 5b 49 4e 53 45 52 54 5d 20  ifying.[INSERT] 
2030: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 0a 48 4c 52  statements...HLR
2040: 20 48 31 32 32 32 33 20 53 31 30 37 30 30 0a 54   H12223 S10700.T
2050: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
2060: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
2070: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
2080: 72 65 74 75 72 6e 20 74 68 65 0a 73 61 6d 65 20  return the.same 
2090: 76 61 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c 65  value when calle
20a0: 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
20b0: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 0a  trigger context.
20c0: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
20d0: 72 65 20 61 6e 64 20 61 66 74 65 72 20 61 20 5b  re and after a [
20e0: 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 0a 48 4c 52 20  ROLLBACK]...HLR 
20f0: 48 31 32 32 34 31 20 53 31 30 36 30 30 0a 54 68  H12241 S10600.Th
2100: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
2110: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73  es()] function s
2120: 68 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  hall return the 
2130: 6e 75 6d 62 65 72 20 6f 66 0a 72 6f 77 20 63 68  number of.row ch
2140: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
2150: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2160: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a  INSERT, UPDATE,.
2170: 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
2180: 65 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ent on the same 
2190: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21a0: 69 6f 6e 20 61 6e 64 0a 77 69 74 68 69 6e 20 74  ion and.within t
21b0: 68 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65  he same or highe
21c0: 72 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  r trigger contex
21d0: 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68  t, or zero if th
21e0: 65 72 65 20 68 61 76 65 0a 6e 6f 74 20 62 65 65  ere have.not bee
21f0: 6e 20 61 6e 79 20 71 75 61 6c 69 66 79 69 6e 67  n any qualifying
2200: 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 0a 48   row changes...H
2210: 4c 52 20 48 31 32 32 34 33 20 53 31 30 36 30 30  LR H12243 S10600
2220: 0a 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74  .Statements of t
2230: 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20  he form "DELETE 
2240: 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20  FROM tablename" 
2250: 77 69 74 68 20 6e 6f 0a 57 48 45 52 45 20 63 6c  with no.WHERE cl
2260: 61 75 73 65 20 73 68 61 6c 6c 20 63 61 75 73 65  ause shall cause
2270: 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2280: 73 20 74 6f 0a 5b 73 71 6c 69 74 65 33 5f 63 68  s to.[sqlite3_ch
2290: 61 6e 67 65 73 28 29 5d 20 74 6f 20 72 65 74 75  anges()] to retu
22a0: 72 6e 20 7a 65 72 6f 2c 20 72 65 67 61 72 64 6c  rn zero, regardl
22b0: 65 73 73 20 6f 66 20 74 68 65 0a 6e 75 6d 62 65  ess of the.numbe
22c0: 72 20 6f 66 20 72 6f 77 73 20 6f 72 69 67 69 6e  r of rows origin
22d0: 61 6c 6c 79 20 69 6e 20 74 68 65 20 74 61 62 6c  ally in the tabl
22e0: 65 2e 0a 0a 48 4c 52 20 48 31 32 32 36 31 20 53  e...HLR H12261 S
22f0: 31 30 36 30 30 0a 54 68 65 20 5b 73 71 6c 69 74  10600.The [sqlit
2300: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
2310: 28 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20  ()] returns the 
2320: 74 6f 74 61 6c 20 6e 75 6d 62 65 72 0a 6f 66 20  total number.of 
2330: 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
2340: 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50  ed by INSERT, UP
2350: 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45 4c  DATE, and/or DEL
2360: 45 54 45 0a 73 74 61 74 65 6d 65 6e 74 73 20 6f  ETE.statements o
2370: 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
2380: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2390: 2c 20 69 6e 20 61 6e 79 0a 74 72 69 67 67 65 72  , in any.trigger
23a0: 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65 20   context, since 
23b0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
23c0: 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72 65 61  nection was crea
23d0: 74 65 64 2e 0a 0a 48 4c 52 20 48 31 32 32 36 33  ted...HLR H12263
23e0: 20 53 31 30 36 30 30 0a 53 74 61 74 65 6d 65 6e   S10600.Statemen
23f0: 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ts of the form "
2400: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
2410: 65 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 57  ename" with no.W
2420: 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61 6c  HERE clause shal
2430: 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  l not change the
2440: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
2450: 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  by [sqlite3_tota
2460: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 2e 0a 0a 48  l_changes()]...H
2470: 4c 52 20 48 31 32 32 37 31 20 53 33 30 35 30 30  LR H12271 S30500
2480: 0a 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  .The [sqlite3_in
2490: 74 65 72 72 75 70 74 28 29 5d 20 69 6e 74 65 72  terrupt()] inter
24a0: 66 61 63 65 20 77 69 6c 6c 20 66 6f 72 63 65 20  face will force 
24b0: 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 53 51 4c 20  all running.SQL 
24c0: 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
24d0: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73  iated with the s
24e0: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
24f0: 6e 65 63 74 69 6f 6e 0a 74 6f 20 68 61 6c 74 20  nection.to halt 
2500: 61 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e 67  after processing
2510: 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64   at most one add
2520: 69 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64  itional row of d
2530: 61 74 61 2e 0a 0a 48 4c 52 20 48 31 32 32 37 32  ata...HLR H12272
2540: 20 53 33 30 35 30 30 0a 41 6e 79 20 53 51 4c 20   S30500.Any SQL 
2550: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 69  statement that i
2560: 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 62 79  s interrupted by
2570: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
2580: 75 70 74 28 29 5d 0a 77 69 6c 6c 20 72 65 74 75  upt()].will retu
2590: 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
25a0: 52 55 50 54 5d 2e 0a 0a 48 4c 52 20 48 31 32 32  RUPT]...HLR H122
25b0: 38 31 20 53 36 30 34 30 30 0a 54 68 65 20 63 61  81 S60400.The ca
25c0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
25d0: 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73  registered by [s
25e0: 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a  qlite3_trace()].
25f0: 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64  shall be invoked
2600: 0a 77 68 65 6e 65 76 65 72 20 61 6e 20 53 51 4c  .whenever an SQL
2610: 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
2620: 20 62 65 67 69 6e 73 20 74 6f 20 65 78 65 63 75   begins to execu
2630: 74 65 20 61 6e 64 0a 77 68 65 6e 65 76 65 72 20  te and.whenever 
2640: 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f  a trigger subpro
2650: 67 72 61 6d 20 66 69 72 73 74 20 62 65 67 69 6e  gram first begin
2660: 73 20 74 6f 20 72 75 6e 2e 0a 0a 48 4c 52 20 48  s to run...HLR H
2670: 31 32 32 38 32 20 53 36 30 34 30 30 0a 45 61 63  12282 S60400.Eac
2680: 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
2690: 65 33 5f 74 72 61 63 65 28 29 5d 20 73 68 61 6c  e3_trace()] shal
26a0: 6c 20 6f 76 65 72 72 69 64 65 20 74 68 65 20 70  l override the p
26b0: 72 65 76 69 6f 75 73 6c 79 0a 72 65 67 69 73 74  reviously.regist
26c0: 65 72 65 64 20 74 72 61 63 65 20 63 61 6c 6c 62  ered trace callb
26d0: 61 63 6b 2e 0a 0a 48 4c 52 20 48 31 32 32 38 33  ack...HLR H12283
26e0: 20 53 36 30 34 30 30 0a 41 20 4e 55 4c 4c 20 74   S60400.A NULL t
26f0: 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 73 68  race callback sh
2700: 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 72 61 63  all disable trac
2710: 69 6e 67 2e 0a 0a 48 4c 52 20 48 31 32 32 38 34  ing...HLR H12284
2720: 20 53 36 30 34 30 30 0a 54 68 65 20 66 69 72 73   S60400.The firs
2730: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2740: 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
2750: 20 73 68 61 6c 6c 20 62 65 20 61 20 63 6f 70 79   shall be a copy
2760: 20 6f 66 0a 74 68 65 20 70 6f 69 6e 74 65 72 20   of.the pointer 
2770: 77 68 69 63 68 20 77 61 73 20 74 68 65 20 33 72  which was the 3r
2780: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  d argument to [s
2790: 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e  qlite3_trace()].
27a0: 0a 0a 48 4c 52 20 48 31 32 32 38 35 20 53 36 30  ..HLR H12285 S60
27b0: 34 30 30 0a 54 68 65 20 73 65 63 6f 6e 64 20 61  400.The second a
27c0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74  rgument to the t
27d0: 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  race callback is
27e0: 20 61 0a 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a.zero-terminat
27f0: 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  ed UTF-8 string 
2800: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6f  containing the o
2810: 72 69 67 69 6e 61 6c 20 74 65 78 74 0a 6f 66 20  riginal text.of 
2820: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2830: 74 20 61 73 20 69 74 20 77 61 73 20 70 61 73 73  t as it was pass
2840: 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33  ed into [sqlite3
2850: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 6f  _prepare_v2()].o
2860: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
2870: 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d  , or an SQL comm
2880: 65 6e 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ent indicating t
2890: 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a 6f 66 20  he beginning.of 
28a0: 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f  a trigger subpro
28b0: 67 72 61 6d 2e 0a 0a 48 4c 52 20 48 31 32 32 38  gram...HLR H1228
28c0: 37 20 53 36 30 34 30 30 0a 54 68 65 20 63 61 6c  7 S60400.The cal
28d0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
28e0: 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 71  egistered by [sq
28f0: 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
2900: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 61 73 20 65   is invoked.as e
2910: 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
2920: 74 20 66 69 6e 69 73 68 65 73 2e 0a 0a 48 4c 52  t finishes...HLR
2930: 20 48 31 32 32 38 38 20 53 36 30 34 30 30 0a 54   H12288 S60400.T
2940: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2950: 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c  er to the profil
2960: 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  e callback is a 
2970: 63 6f 70 79 20 6f 66 0a 74 68 65 20 33 72 64 20  copy of.the 3rd 
2980: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2990: 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
29a0: 2e 0a 0a 48 4c 52 20 48 31 32 32 38 39 20 53 36  ...HLR H12289 S6
29b0: 30 34 30 30 0a 54 68 65 20 73 65 63 6f 6e 64 20  0400.The second 
29c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
29d0: 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
29e0: 6b 20 69 73 20 61 0a 7a 65 72 6f 2d 74 65 72 6d  k is a.zero-term
29f0: 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
2a00: 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ing that contain
2a10: 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 74  s the complete t
2a20: 65 78 74 20 6f 66 0a 74 68 65 20 53 51 4c 20 73  ext of.the SQL s
2a30: 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77  tatement as it w
2a40: 61 73 20 70 72 6f 63 65 73 73 65 64 20 62 79 20  as processed by 
2a50: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a60: 5f 76 32 28 29 5d 0a 6f 72 20 74 68 65 20 65 71  _v2()].or the eq
2a70: 75 69 76 61 6c 65 6e 74 2e 0a 0a 48 4c 52 20 48  uivalent...HLR H
2a80: 31 32 32 39 30 20 53 36 30 34 30 30 0a 54 68 65  12290 S60400.The
2a90: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2aa0: 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
2ab0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 65  callback is an e
2ac0: 73 74 69 6d 61 74 65 0a 6f 66 20 74 68 65 20 6e  stimate.of the n
2ad0: 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63  umber of nanosec
2ae0: 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  onds of wall-clo
2af0: 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72 65 64  ck time required
2b00: 20 74 6f 0a 72 75 6e 20 74 68 65 20 53 51 4c 20   to.run the SQL 
2b10: 73 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73  statement from s
2b20: 74 61 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a  tart to finish..
2b30: 0a 48 4c 52 20 48 31 32 33 31 31 20 53 34 30 34  .HLR H12311 S404
2b40: 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  00.The [sqlite3_
2b50: 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 43  busy_handler(D,C
2b60: 2c 41 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  ,A)] function sh
2b70: 61 6c 6c 20 72 65 70 6c 61 63 65 0a 62 75 73 79  all replace.busy
2b80: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65   callback in the
2b90: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2ba0: 63 74 69 6f 6e 5d 20 44 20 77 69 74 68 20 61 20  ction] D with a 
2bb0: 6e 65 77 0a 61 20 6e 65 77 20 62 75 73 79 20 68  new.a new busy h
2bc0: 61 6e 64 6c 65 72 20 43 20 61 6e 64 20 61 70 70  andler C and app
2bd0: 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
2be0: 69 6e 74 65 72 20 41 2e 0a 0a 48 4c 52 20 48 31  inter A...HLR H1
2bf0: 32 33 31 32 20 53 34 30 34 30 30 0a 4e 65 77 6c  2312 S40400.Newl
2c00: 79 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 62  y created [datab
2c10: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
2c20: 20 73 68 61 6c 6c 20 68 61 76 65 20 61 20 62 75   shall have a bu
2c30: 73 79 0a 68 61 6e 64 6c 65 72 20 6f 66 20 4e 55  sy.handler of NU
2c40: 4c 4c 2e 0a 0a 48 4c 52 20 48 31 32 33 31 34 20  LL...HLR H12314 
2c50: 53 34 30 34 30 30 0a 57 68 65 6e 20 74 77 6f 20  S40400.When two 
2c60: 6f 72 20 6d 6f 72 65 20 5b 64 61 74 61 62 61 73  or more [databas
2c70: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73  e connections] s
2c80: 68 61 72 65 20 61 0a 5b 73 71 6c 69 74 65 33 5f  hare a.[sqlite3_
2c90: 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
2ca0: 63 68 65 20 7c 20 63 6f 6d 6d 6f 6e 20 63 61 63  che | common cac
2cb0: 68 65 5d 2c 0a 74 68 65 20 62 75 73 79 20 68 61  he],.the busy ha
2cc0: 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 64 61  ndler for the da
2cd0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ce0: 6e 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  n currently usin
2cf0: 67 0a 74 68 65 20 63 61 63 68 65 20 73 68 61 6c  g.the cache shal
2d00: 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  l be invoked whe
2d10: 6e 20 74 68 65 20 63 61 63 68 65 20 65 6e 63 6f  n the cache enco
2d20: 75 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 0a  unters a lock...
2d30: 48 4c 52 20 48 31 32 33 31 36 20 53 34 30 34 30  HLR H12316 S4040
2d40: 30 0a 49 66 20 61 20 62 75 73 79 20 68 61 6e 64  0.If a busy hand
2d50: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ler callback ret
2d60: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  urns zero, then 
2d70: 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
2d80: 66 61 63 65 0a 74 68 61 74 20 70 72 6f 76 6f 6b  face.that provok
2d90: 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e 67 20 65  ed the locking e
2da0: 76 65 6e 74 20 73 68 61 6c 6c 20 72 65 74 75 72  vent shall retur
2db0: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  n [SQLITE_BUSY].
2dc0: 0a 0a 48 4c 52 20 48 31 32 33 31 38 20 53 34 30  ..HLR H12318 S40
2dd0: 34 30 30 0a 53 51 4c 69 74 65 20 73 68 61 6c 6c  400.SQLite shall
2de0: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 73   invokes the bus
2df0: 79 20 68 61 6e 64 6c 65 72 20 77 69 74 68 20 74  y handler with t
2e00: 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 77 68 69  wo arguments whi
2e10: 63 68 0a 61 72 65 20 61 20 63 6f 70 79 20 6f 66  ch.are a copy of
2e20: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 73 75 70   the pointer sup
2e30: 70 6c 69 65 64 20 62 79 20 74 68 65 20 33 72 64  plied by the 3rd
2e40: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 5b 73   parameter to.[s
2e50: 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
2e60: 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75  ler()] and a cou
2e70: 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
2e80: 20 6f 66 20 70 72 69 6f 72 0a 69 6e 76 6f 63 61   of prior.invoca
2e90: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 73  tions of the bus
2ea0: 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68  y handler for th
2eb0: 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65  e same locking e
2ec0: 76 65 6e 74 2e 0a 0a 48 4c 52 20 48 31 32 33 34  vent...HLR H1234
2ed0: 31 20 53 34 30 34 31 30 0a 54 68 65 20 5b 73 71  1 S40410.The [sq
2ee0: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
2ef0: 75 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73  ut()] function s
2f00: 68 61 6c 6c 20 6f 76 65 72 72 69 64 65 20 61 6e  hall override an
2f10: 79 20 70 72 69 6f 72 0a 5b 73 71 6c 69 74 65 33  y prior.[sqlite3
2f20: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
2f30: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 75 73   or [sqlite3_bus
2f40: 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73 65 74  y_handler()] set
2f50: 74 69 6e 67 0a 6f 6e 20 74 68 65 20 73 61 6d 65  ting.on the same
2f60: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f70: 63 74 69 6f 6e 5d 2e 0a 0a 48 4c 52 20 48 31 32  ction]...HLR H12
2f80: 33 34 33 20 53 34 30 34 31 30 0a 49 66 20 74 68  343 S40410.If th
2f90: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2fa0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  to [sqlite3_busy
2fb0: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c  _timeout()] is l
2fc0: 65 73 73 20 74 68 61 6e 0a 6f 72 20 65 71 75 61  ess than.or equa
2fd0: 6c 20 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20  l to zero, then 
2fe0: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
2ff0: 20 73 68 61 6c 6c 20 62 65 20 63 6c 65 61 72 65   shall be cleare
3000: 64 20 73 6f 20 74 68 61 74 0a 61 6c 6c 20 73 75  d so that.all su
3010: 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69 6e 67  bsequent locking
3020: 20 65 76 65 6e 74 73 20 69 6d 6d 65 64 69 61 74   events immediat
3030: 65 6c 79 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ely return [SQLI
3040: 54 45 5f 42 55 53 59 5d 2e 0a 0a 48 4c 52 20 48  TE_BUSY]...HLR H
3050: 31 32 33 34 34 20 53 34 30 34 31 30 0a 49 66 20  12344 S40410.If 
3060: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3070: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75  r to [sqlite3_bu
3080: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73  sy_timeout()] is
3090: 20 61 20 70 6f 73 69 74 69 76 65 0a 6e 75 6d 62   a positive.numb
30a0: 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73  er N, then a bus
30b0: 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20  y handler shall 
30c0: 62 65 20 73 65 74 20 74 68 61 74 20 72 65 70 65  be set that repe
30d0: 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 74 68 65  atedly calls.the
30e0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
30f0: 20 69 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33   in the [sqlite3
3100: 5f 76 66 73 20 7c 20 56 46 53 20 69 6e 74 65 72  _vfs | VFS inter
3110: 66 61 63 65 5d 20 75 6e 74 69 6c 0a 65 69 74 68  face] until.eith
3120: 65 72 20 74 68 65 20 6c 6f 63 6b 20 63 6c 65 61  er the lock clea
3130: 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  rs or until the 
3140: 63 75 6d 75 6c 61 74 69 76 65 20 73 6c 65 65 70  cumulative sleep
3150: 20 74 69 6d 65 0a 72 65 70 6f 72 74 65 64 20 62   time.reported b
3160: 61 63 6b 20 62 79 20 78 53 6c 65 65 70 28 29 20  ack by xSleep() 
3170: 65 78 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73  exceeds N millis
3180: 65 63 6f 6e 64 73 2e 0a 0a 48 4c 52 20 48 31 32  econds...HLR H12
3190: 33 37 31 20 53 31 30 30 30 30 0a 49 66 20 61 20  371 S10000.If a 
31a0: 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
31b0: 6c 65 28 29 5d 20 66 61 69 6c 73 20 61 20 6d 65  le()] fails a me
31c0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  mory allocation,
31d0: 20 74 68 65 6e 0a 69 74 20 73 68 61 6c 6c 20 66   then.it shall f
31e0: 72 65 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ree the result t
31f0: 61 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73 74  able under const
3200: 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74 20 74  ruction, abort t
3210: 68 65 0a 71 75 65 72 79 20 69 6e 20 70 72 6f 63  he.query in proc
3220: 65 73 73 2c 20 73 6b 69 70 20 61 6e 79 20 73 75  ess, skip any su
3230: 62 73 65 71 75 65 6e 74 20 71 75 65 72 69 65 73  bsequent queries
3240: 2c 20 73 65 74 20 74 68 65 0a 2a 70 61 7a 52 65  , set the.*pazRe
3250: 73 75 6c 74 20 6f 75 74 70 75 74 20 70 6f 69 6e  sult output poin
3260: 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e 64 20  ter to NULL and 
3270: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
3280: 4f 4d 45 4d 5d 2e 0a 0a 48 4c 52 20 48 31 32 33  OMEM]...HLR H123
3290: 37 33 20 53 31 30 30 30 30 0a 49 66 20 74 68 65  73 S10000.If the
32a0: 20 70 6e 43 6f 6c 75 6d 6e 20 70 61 72 61 6d 65   pnColumn parame
32b0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
32c0: 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  get_table()] is 
32d0: 6e 6f 74 20 4e 55 4c 4c 0a 74 68 65 6e 20 61 20  not NULL.then a 
32e0: 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
32f0: 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
3300: 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 73  3_get_table()] s
3310: 68 61 6c 6c 0a 77 72 69 74 65 20 74 68 65 20 6e  hall.write the n
3320: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3330: 20 69 6e 20 74 68 65 0a 72 65 73 75 6c 74 20 73   in the.result s
3340: 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  et of the query 
3350: 69 6e 74 6f 20 2a 70 6e 43 6f 6c 75 6d 6e 2e 0a  into *pnColumn..
3360: 0a 48 4c 52 20 48 31 32 33 37 34 20 53 31 30 30  .HLR H12374 S100
3370: 30 30 0a 49 66 20 74 68 65 20 70 6e 52 6f 77 20  00.If the pnRow 
3380: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
3390: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
33a0: 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 74  )] is not NULL.t
33b0: 68 65 6e 20 61 20 73 75 63 63 65 73 73 66 75 6c  hen a successful
33c0: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
33d0: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
33e0: 65 28 29 5d 20 73 68 61 6c 6c 0a 77 72 69 74 65  e()] shall.write
33f0: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
3400: 72 6f 77 73 20 69 6e 20 74 68 65 0a 72 65 73 75  rows in the.resu
3410: 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75  lt set of the qu
3420: 65 72 79 20 69 6e 74 6f 20 2a 70 6e 52 6f 77 2e  ery into *pnRow.
3430: 0a 0a 48 4c 52 20 48 31 32 33 37 36 20 53 31 30  ..HLR H12376 S10
3440: 30 30 30 0a 41 20 73 75 63 63 65 73 73 66 75 6c  000.A successful
3450: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
3460: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
3470: 65 28 29 5d 20 74 68 61 74 20 63 6f 6d 70 75 74  e()] that comput
3480: 65 73 0a 4e 20 72 6f 77 73 20 6f 66 20 72 65 73  es.N rows of res
3490: 75 6c 74 20 77 69 74 68 20 43 20 63 6f 6c 75 6d  ult with C colum
34a0: 6e 73 20 70 65 72 20 72 6f 77 20 73 68 61 6c 6c  ns per row shall
34b0: 20 6d 61 6b 65 20 2a 70 61 7a 52 65 73 75 6c 74   make *pazResult
34c0: 0a 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 72 72  .point to an arr
34d0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
34e0: 6f 20 28 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67  o (N+1)*C string
34f0: 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73  s where the firs
3500: 74 0a 43 20 73 74 72 69 6e 67 73 20 61 72 65 20  t.C strings are 
3510: 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 61 73 20  column names as 
3520: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 5b 73  obtained from.[s
3530: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3540: 6d 65 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65  me()] and the re
3550: 73 74 20 61 72 65 20 63 6f 6c 75 6d 6e 20 72 65  st are column re
3560: 73 75 6c 74 20 76 61 6c 75 65 73 0a 6f 62 74 61  sult values.obta
3570: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
3580: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
3590: 5d 2e 0a 0a 48 4c 52 20 48 31 32 33 37 39 20 53  ]...HLR H12379 S
35a0: 31 30 30 30 30 0a 54 68 65 20 76 61 6c 75 65 73  10000.The values
35b0: 20 69 6e 20 74 68 65 20 70 61 7a 52 65 73 75 6c   in the pazResul
35c0: 74 20 61 72 72 61 79 20 72 65 74 75 72 6e 65 64  t array returned
35d0: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   by [sqlite3_get
35e0: 5f 74 61 62 6c 65 28 29 5d 0a 73 68 61 6c 6c 20  _table()].shall 
35f0: 72 65 6d 61 69 6e 20 76 61 6c 69 64 20 75 6e 74  remain valid unt
3600: 69 6c 20 63 6c 65 61 72 65 64 20 62 79 20 5b 73  il cleared by [s
3610: 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
3620: 65 28 29 5d 2e 0a 0a 48 4c 52 20 48 31 32 33 38  e()]...HLR H1238
3630: 32 20 53 31 30 30 30 30 0a 57 68 65 6e 20 61 6e  2 S10000.When an
3640: 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
3650: 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 6f  n SQLITE_NOMEM o
3660: 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 76 61  ccurs during eva
3670: 6c 75 61 74 69 6f 6e 20 0a 6f 66 20 5b 73 71 6c  luation .of [sql
3680: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
3690: 5d 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 73  ] the function s
36a0: 68 61 6c 6c 20 73 65 74 20 2a 70 61 7a 52 65 73  hall set *pazRes
36b0: 75 6c 74 20 74 6f 20 4e 55 4c 4c 2c 0a 77 72 69  ult to NULL,.wri
36c0: 74 65 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  te an error mess
36d0: 61 67 65 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  age into memory 
36e0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
36f0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
3700: 2c 20 6d 61 6b 65 0a 2a 2a 70 7a 45 72 72 6d 73  , make.**pzErrms
3710: 67 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 20  g point to that 
3720: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2c 20 61  error message, a
3730: 6e 64 20 72 65 74 75 72 6e 20 61 0a 61 70 70 72  nd return a.appr
3740: 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
3750: 6f 64 65 5d 2e 0a 0a 48 4c 52 20 48 31 32 35 30  ode]...HLR H1250
3760: 31 20 53 37 30 31 30 30 0a 54 68 65 20 5b 73 71  1 S70100.The [sq
3770: 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
3780: 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74  izer(D,...)] int
3790: 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
37a0: 20 61 0a 61 75 74 68 6f 72 69 7a 65 72 20 63 61   a.authorizer ca
37b0: 6c 6c 62 61 63 6b 20 77 69 74 68 20 64 61 74 61  llback with data
37c0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37d0: 44 2e 0a 0a 48 4c 52 20 48 31 32 35 30 32 20 53  D...HLR H12502 S
37e0: 37 30 31 30 30 0a 54 68 65 20 61 75 74 68 6f 72  70100.The author
37f0: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
3800: 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
3810: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 62  statements are.b
3820: 65 69 6e 67 20 70 61 72 73 65 65 64 20 61 6e 64  eing parseed and
3830: 20 63 6f 6d 70 69 6c 65 64 2e 0a 0a 48 4c 52 20   compiled...HLR 
3840: 48 31 32 35 30 33 20 53 37 30 31 30 30 0a 49 66  H12503 S70100.If
3850: 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
3860: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
3870: 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
3880: 20 74 68 61 6e 0a 5b 53 51 4c 49 54 45 5f 49 47   than.[SQLITE_IG
3890: 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
38a0: 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
38b0: 45 4e 59 5d 2c 20 74 68 65 6e 0a 74 68 65 20 61  ENY], then.the a
38c0: 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 74 65 72  pplication inter
38d0: 66 61 63 65 20 63 61 6c 6c 20 74 68 61 74 20 63  face call that c
38e0: 61 75 73 65 64 0a 74 68 65 20 61 75 74 68 6f 72  aused.the author
38f0: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f  izer callback to
3900: 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20   run shall fail 
3910: 77 69 74 68 20 61 6e 0a 5b 53 51 4c 49 54 45 5f  with an.[SQLITE_
3920: 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64  ERROR] error cod
3930: 65 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72  e and an appropr
3940: 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
3950: 67 65 2e 0a 0a 48 4c 52 20 48 31 32 35 30 34 20  ge...HLR H12504 
3960: 53 37 30 31 30 30 0a 57 68 65 6e 20 74 68 65 20  S70100.When the 
3970: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
3980: 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
3990: 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65  ITE_OK], the ope
39a0: 72 61 74 69 6f 6e 0a 64 65 73 63 72 69 62 65 64  ration.described
39b0: 20 69 73 20 70 72 6f 63 65 73 73 65 64 20 6e 6f   is processed no
39c0: 72 6d 61 6c 6c 79 2e 0a 0a 48 4c 52 20 48 31 32  rmally...HLR H12
39d0: 35 30 35 20 53 37 30 31 30 30 0a 57 68 65 6e 20  505 S70100.When 
39e0: 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
39f0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
3a00: 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
3a10: 68 65 0a 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he.application i
3a20: 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 74 68  nterface call th
3a30: 61 74 20 63 61 75 73 65 64 20 74 68 65 0a 61 75  at caused the.au
3a40: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
3a50: 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66  k to run shall f
3a60: 61 69 6c 0a 77 69 74 68 20 61 6e 20 5b 53 51 4c  ail.with an [SQL
3a70: 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72  ITE_ERROR] error
3a80: 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72   code and an err
3a90: 6f 72 20 6d 65 73 73 61 67 65 0a 65 78 70 6c 61  or message.expla
3aa0: 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65 73  ining that acces
3ab0: 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 0a 48 4c  s is denied...HL
3ac0: 52 20 48 31 32 35 30 36 20 53 37 30 31 30 30 0a  R H12506 S70100.
3ad0: 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
3ae0: 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64 20  r code (the 2nd 
3af0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
3b00: 20 61 75 74 68 6f 72 69 7a 65 72 0a 63 61 6c 6c   authorizer.call
3b10: 62 61 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 45  back) is [SQLITE
3b20: 5f 52 45 41 44 5d 20 61 6e 64 20 74 68 65 20 61  _READ] and the a
3b30: 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
3b40: 63 6b 20 72 65 74 75 72 6e 73 0a 5b 53 51 4c 49  ck returns.[SQLI
3b50: 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e  TE_IGNORE], then
3b60: 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
3b70: 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
3b80: 72 75 63 74 65 64 20 74 6f 0a 69 6e 73 65 72 74  ructed to.insert
3b90: 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
3ba0: 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
3bb0: 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
3bc0: 77 6f 75 6c 64 20 68 61 76 65 0a 62 65 65 6e 20  would have.been 
3bd0: 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
3be0: 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
3bf0: 75 72 6e 65 64 2e 0a 0a 48 4c 52 20 48 31 32 35  urned...HLR H125
3c00: 30 37 20 53 37 30 31 30 30 0a 49 66 20 74 68 65  07 S70100.If the
3c10: 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65   authorizer code
3c20: 20 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65   (the 2nd parame
3c30: 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
3c40: 72 69 7a 65 72 0a 63 61 6c 6c 62 61 63 6b 29 20  rizer.callback) 
3c50: 69 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65  is anything othe
3c60: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
3c70: 45 41 44 5d 2c 20 74 68 65 6e 0a 61 20 72 65 74  EAD], then.a ret
3c80: 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  urn of [SQLITE_I
3c90: 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20 73  GNORE] has the s
3ca0: 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b 53  ame effect as [S
3cb0: 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 0a 0a 48 4c  QLITE_DENY]...HL
3cc0: 52 20 48 31 32 35 31 30 20 53 37 30 31 30 30 0a  R H12510 S70100.
3cd0: 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
3ce0: 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
3cf0: 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
3d00: 73 20 61 20 63 6f 70 79 20 6f 66 0a 74 68 65 20  s a copy of.the 
3d10: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
3d20: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
3d30: 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
3d40: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 0a 48 4c  ] interface...HL
3d50: 52 20 48 31 32 35 31 31 20 53 37 30 31 30 30 0a  R H12511 S70100.
3d60: 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
3d70: 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
3d80: 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
3d90: 65 72 0a 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er.[SQLITE_COPY 
3da0: 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
3db0: 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
3dc0: 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
3dd0: 69 6f 6e 0a 74 6f 20 62 65 20 61 75 74 68 6f 72  ion.to be author
3de0: 69 7a 65 64 2e 0a 0a 48 4c 52 20 48 31 32 35 31  ized...HLR H1251
3df0: 32 20 53 37 30 31 30 30 0a 54 68 65 20 74 68 69  2 S70100.The thi
3e00: 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
3e10: 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
3e20: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a  he callback are.
3e30: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
3e40: 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
3e50: 74 61 69 6e 0a 61 64 64 69 74 69 6f 6e 61 6c 20  tain.additional 
3e60: 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
3e70: 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
3e80: 75 74 68 6f 72 69 7a 65 64 2e 0a 0a 48 4c 52 20  uthorized...HLR 
3e90: 48 31 32 35 32 30 20 53 37 30 31 30 30 0a 45 61  H12520 S70100.Ea
3ea0: 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
3eb0: 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
3ec0: 65 72 28 29 5d 20 6f 76 65 72 72 69 64 65 73 0a  er()] overrides.
3ed0: 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 69  any previously i
3ee0: 6e 73 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 69  nstalled authori
3ef0: 7a 65 72 2e 0a 0a 48 4c 52 20 48 31 32 35 32 31  zer...HLR H12521
3f00: 20 53 37 30 31 30 30 0a 41 20 4e 55 4c 4c 20 61   S70100.A NULL a
3f10: 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20  uthorizer means 
3f20: 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a  that no authoriz
3f30: 61 74 69 6f 6e 0a 63 61 6c 6c 62 61 63 6b 20 69  ation.callback i
3f40: 73 20 69 6e 76 6f 6b 65 64 2e 0a 0a 48 4c 52 20  s invoked...HLR 
3f50: 48 31 32 35 32 32 20 53 37 30 31 30 30 0a 54 68  H12522 S70100.Th
3f60: 65 20 64 65 66 61 75 6c 74 20 61 75 74 68 6f 72  e default author
3f70: 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 0a 48  izer is NULL...H
3f80: 4c 52 20 48 31 32 35 35 31 20 48 31 32 35 30 30  LR H12551 H12500
3f90: 0a 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  .The second para
3fa0: 6d 65 74 65 72 20 74 6f 20 61 6e 0a 5b 73 71 6c  meter to an.[sql
3fb0: 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
3fc0: 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
3fd0: 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61 6c 6c   callback] shall
3fe0: 20 62 65 20 61 6e 20 69 6e 74 65 67 65 72 0a 5b   be an integer.[
3ff0: 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75  SQLITE_COPY | au
4000: 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 74  thorizer code] t
4010: 68 61 74 20 73 70 65 63 69 66 69 65 73 20 77 68  hat specifies wh
4020: 61 74 20 61 63 74 69 6f 6e 0a 69 73 20 62 65 69  at action.is bei
4030: 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 0a  ng authorized...
4040: 48 4c 52 20 48 31 32 35 35 32 20 48 31 32 35 30  HLR H12552 H1250
4050: 30 0a 54 68 65 20 33 72 64 20 61 6e 64 20 34 74  0.The 3rd and 4t
4060: 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
4070: 74 68 65 0a 5b 73 71 6c 69 74 65 33 5f 73 65 74  the.[sqlite3_set
4080: 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
4090: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c  thorization call
40a0: 62 61 63 6b 5d 0a 73 68 61 6c 6c 20 62 65 20 70  back].shall be p
40b0: 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
40c0: 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
40d0: 68 69 63 68 0a 5b 53 51 4c 49 54 45 5f 43 4f 50  hich.[SQLITE_COP
40e0: 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  Y | authorizer c
40f0: 6f 64 65 5d 20 69 73 20 75 73 65 64 20 61 73 20  ode] is used as 
4100: 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
4110: 65 74 65 72 2e 0a 0a 48 4c 52 20 48 31 32 35 35  eter...HLR H1255
4120: 33 20 48 31 32 35 30 30 0a 54 68 65 20 35 74 68  3 H12500.The 5th
4130: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
4140: 65 0a 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e.[sqlite3_set_a
4150: 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
4160: 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d  orizer callback]
4170: 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20 6e 61   shall be the na
4180: 6d 65 0a 6f 66 20 74 68 65 20 64 61 74 61 62 61  me.of the databa
4190: 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61  se (example: "ma
41a0: 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 63  in", "temp", etc
41b0: 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
41c0: 2e 0a 0a 48 4c 52 20 48 31 32 35 35 34 20 48 31  ...HLR H12554 H1
41d0: 32 35 30 30 0a 54 68 65 20 36 74 68 20 70 61 72  2500.The 6th par
41e0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 5b 73  ameter to the.[s
41f0: 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
4200: 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
4210: 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61  er callback] sha
4220: 6c 6c 20 62 65 20 74 68 65 20 6e 61 6d 65 0a 6f  ll be the name.o
4230: 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
4240: 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
4250: 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
4260: 69 62 6c 65 20 66 6f 72 0a 74 68 65 20 61 63 63  ible for.the acc
4270: 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
4280: 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
4290: 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
42a0: 72 65 63 74 6c 79 20 66 72 6f 6d 0a 74 6f 70 2d  rectly from.top-
42b0: 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
42c0: 0a 48 4c 52 20 48 31 32 37 30 31 20 53 34 30 32  .HLR H12701 S402
42d0: 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  00.The [sqlite3_
42e0: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
42f0: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
4300: 0a 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  .[sqlite3_open_v
4310: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
4320: 63 72 65 61 74 65 20 61 20 6e 65 77 0a 5b 64 61  create a new.[da
4330: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4340: 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  n] associated wi
4350: 74 68 0a 74 68 65 20 64 61 74 61 62 61 73 65 20  th.the database 
4360: 66 69 6c 65 20 67 69 76 65 6e 20 69 6e 20 74 68  file given in th
4370: 65 69 72 20 66 69 72 73 74 20 70 61 72 61 6d 65  eir first parame
4380: 74 65 72 2e 0a 0a 48 4c 52 20 48 31 32 37 30 32  ter...HLR H12702
4390: 20 53 34 30 32 30 30 0a 54 68 65 20 66 69 6c 65   S40200.The file
43a0: 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
43b0: 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
43c0: 55 54 46 2d 38 0a 66 6f 72 20 5b 73 71 6c 69 74  UTF-8.for [sqlit
43d0: 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b  e3_open()] and [
43e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
43f0: 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  )] and as UTF-16
4400: 0a 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62  .in the native b
4410: 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73  yte order for [s
4420: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
4430: 2e 0a 0a 48 4c 52 20 48 31 32 37 30 33 20 53 34  ...HLR H12703 S4
4440: 30 32 30 30 0a 41 20 73 75 63 63 65 73 73 66 75  0200.A successfu
4450: 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
4460: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
4470: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
4480: 36 28 29 5d 2c 0a 6f 72 20 5b 73 71 6c 69 74 65  6()],.or [sqlite
4490: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72 69  3_open_v2()] wri
44a0: 74 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  tes a pointer to
44b0: 20 61 20 6e 65 77 0a 5b 64 61 74 61 62 61 73 65   a new.[database
44c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74   connection] int
44d0: 6f 20 2a 70 70 44 62 2e 0a 0a 48 4c 52 20 48 31  o *ppDb...HLR H1
44e0: 32 37 30 34 20 53 34 30 32 30 30 0a 54 68 65 20  2704 S40200.The 
44f0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
4500: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
4510: 36 28 29 5d 2c 20 61 6e 64 0a 5b 73 71 6c 69 74  6()], and.[sqlit
4520: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
4530: 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
4540: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e  [SQLITE_OK] upon
4550: 20 73 75 63 63 65 73 73 2c 0a 6f 72 20 61 6e 20   success,.or an 
4560: 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
4570: 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c  or code] on fail
4580: 75 72 65 2e 0a 0a 48 4c 52 20 48 31 32 37 30 36  ure...HLR H12706
4590: 20 53 34 30 32 30 30 0a 54 68 65 20 64 65 66 61   S40200.The defa
45a0: 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  ult text encodin
45b0: 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61  g for a new data
45c0: 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69  base created usi
45d0: 6e 67 0a 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ng.[sqlite3_open
45e0: 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
45f0: 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20  open_v2()] will 
4600: 62 65 20 55 54 46 2d 38 2e 0a 0a 48 4c 52 20 48  be UTF-8...HLR H
4610: 31 32 37 30 37 20 53 34 30 32 30 30 0a 54 68 65  12707 S40200.The
4620: 20 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e   default text en
4630: 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77  coding for a new
4640: 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65   database create
4650: 64 20 75 73 69 6e 67 0a 5b 73 71 6c 69 74 65 33  d using.[sqlite3
4660: 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c 20  _open16()] will 
4670: 62 65 20 55 54 46 2d 31 36 2e 0a 0a 48 4c 52 20  be UTF-16...HLR 
4680: 48 31 32 37 30 39 20 53 34 30 32 30 30 0a 54 68  H12709 S40200.Th
4690: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
46a0: 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,D)] interface 
46b0: 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
46c0: 0a 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  .[sqlite3_open_v
46d0: 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72  2(F,D,G,0)] wher
46e0: 65 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  e the G paramete
46f0: 72 20 69 73 0a 5b 53 51 4c 49 54 45 5f 4f 50 45  r is.[SQLITE_OPE
4700: 4e 5f 52 45 41 44 57 52 49 54 45 5d 7c 5b 53 51  N_READWRITE]|[SQ
4710: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
4720: 5d 2e 0a 0a 48 4c 52 20 48 31 32 37 31 31 20 53  ]...HLR H12711 S
4730: 34 30 32 30 30 0a 49 66 20 74 68 65 20 47 20 70  40200.If the G p
4740: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
4750: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
4760: 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20  ,G,V)] contains 
4770: 74 68 65 0a 62 69 74 20 76 61 6c 75 65 20 5b 53  the.bit value [S
4780: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
4790: 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65 20 64 61  NLY] then the da
47a0: 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
47b0: 0a 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c  .for reading onl
47c0: 79 2e 0a 0a 48 4c 52 20 48 31 32 37 31 32 20 53  y...HLR H12712 S
47d0: 34 30 32 30 30 0a 49 66 20 74 68 65 20 47 20 70  40200.If the G p
47e0: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
47f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
4800: 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20  ,G,V)] contains 
4810: 74 68 65 0a 62 69 74 20 76 61 6c 75 65 20 5b 53  the.bit value [S
4820: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
4830: 52 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20 64  RITE] then the d
4840: 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
4850: 64 0a 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  d.reading and wr
4860: 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
4870: 65 2c 20 6f 72 20 66 6f 72 20 72 65 61 64 69 6e  e, or for readin
4880: 67 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a 66 69  g only if the.fi
4890: 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
48a0: 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
48b0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a 0a  rating system...
48c0: 48 4c 52 20 48 31 32 37 31 33 20 53 34 30 32 30  HLR H12713 S4020
48d0: 30 0a 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  0.If the G param
48e0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
48f0: 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56  _open_v2(F,D,G,V
4900: 29 5d 20 6f 6d 69 74 73 20 74 68 65 0a 62 69 74  )] omits the.bit
4910: 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f   value [SQLITE_O
4920: 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20  PEN_CREATE] and 
4930: 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
4940: 73 20 6e 6f 74 0a 70 72 65 76 69 6f 75 73 6c 79  s not.previously
4950: 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
4960: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 0a 48   is returned...H
4970: 4c 52 20 48 31 32 37 31 34 20 53 34 30 32 30 30  LR H12714 S40200
4980: 0a 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65  .If the G parame
4990: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
49a0: 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29  open_v2(F,D,G,V)
49b0: 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 62  ] contains the.b
49c0: 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
49d0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e  _OPEN_CREATE] an
49e0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  d the database d
49f0: 6f 65 73 20 6e 6f 74 0a 70 72 65 76 69 6f 75 73  oes not.previous
4a00: 6c 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20 61  ly exist, then a
4a10: 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
4a20: 65 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64 0a  e to create and.
4a30: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 64  initialize the d
4a40: 61 74 61 62 61 73 65 2e 0a 0a 48 4c 52 20 48 31  atabase...HLR H1
4a50: 32 37 31 37 20 53 34 30 32 30 30 0a 49 66 20 74  2717 S40200.If t
4a60: 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
4a70: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
4a80: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
4a90: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 6f 72  e3_open16()],.or
4aa0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
4ab0: 32 28 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79  2()] is ":memory
4ac0: 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76  :", then an priv
4ad0: 61 74 65 2c 0a 65 70 68 65 6d 65 72 61 6c 2c 20  ate,.ephemeral, 
4ae0: 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
4af0: 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  se is created fo
4b00: 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
4b10: 2e 0a 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54  ..<todo>Is SQLIT
4b20: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51  E_OPEN_CREATE|SQ
4b30: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
4b40: 49 54 45 20 72 65 71 75 69 72 65 64 0a 69 6e 20  ITE required.in 
4b50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
4b60: 29 3f 3c 2f 74 6f 64 6f 3e 0a 0a 48 4c 52 20 48  )?</todo>..HLR H
4b70: 31 32 37 31 39 20 53 34 30 32 30 30 0a 49 66 20  12719 S40200.If 
4b80: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
4b90: 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79  NULL or an empty
4ba0: 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
4bb0: 70 72 69 76 61 74 65 2c 0a 65 70 68 65 6d 65 72  private,.ephemer
4bc0: 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  al on-disk datab
4bd0: 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
4be0: 74 65 64 2e 0a 3c 74 6f 64 6f 3e 49 73 20 53 51  ted..<todo>Is SQ
4bf0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
4c00: 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  |SQLITE_OPEN_REA
4c10: 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a  DWRITE required.
4c20: 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  in sqlite3_open_
4c30: 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 0a 48 4c  v2()?</todo>..HL
4c40: 52 20 48 31 32 37 32 31 20 53 34 30 32 30 30 0a  R H12721 S40200.
4c50: 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
4c60: 6e 6e 65 63 74 69 6f 6e 5d 20 63 72 65 61 74 65  nnection] create
4c70: 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d by [sqlite3_op
4c80: 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 0a  en_v2(F,D,G,V)].
4c90: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 5b 73 71  will use the [sq
4ca0: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
4cb0: 74 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  t identified by 
4cc0: 74 68 65 20 56 20 70 61 72 61 6d 65 74 65 72 2c  the V parameter,
4cd0: 0a 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  .or the default 
4ce0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
4cf0: 6a 65 63 74 20 69 66 20 56 20 69 73 20 61 20 4e  ject if V is a N
4d00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 0a 48 4c  ULL pointer...HL
4d10: 52 20 48 31 32 37 32 33 20 53 34 30 32 30 30 0a  R H12723 S40200.
4d20: 54 77 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f  Two [database co
4d30: 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c 20  nnections] will 
4d40: 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63  share a common c
4d50: 61 63 68 65 20 69 66 20 62 6f 74 68 20 77 65 72  ache if both wer
4d60: 65 0a 6f 70 65 6e 65 64 20 77 69 74 68 20 74 68  e.opened with th
4d70: 65 20 73 61 6d 65 20 56 46 53 20 77 68 69 6c 65  e same VFS while
4d80: 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
4d90: 6f 64 65 5d 20 77 61 73 20 65 6e 61 62 6c 65 64  ode] was enabled
4da0: 20 61 6e 64 0a 69 66 20 62 6f 74 68 20 66 69 6c   and.if both fil
4db0: 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20 65  enames compare e
4dc0: 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63 6d  qual using memcm
4dd0: 70 28 29 20 61 66 74 65 72 20 68 61 76 69 6e 67  p() after having
4de0: 20 62 65 65 6e 0a 70 72 6f 63 65 73 73 65 64 20   been.processed 
4df0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
4e00: 76 66 73 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e  vfs | xFullPathn
4e10: 61 6d 65 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74  ame] method of t
4e20: 68 65 20 56 46 53 2e 0a 0a 48 4c 52 20 48 31 32  he VFS...HLR H12
4e30: 37 36 32 20 53 32 30 36 30 30 0a 41 20 73 75 63  762 S20600.A suc
4e40: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
4e50: 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44  [sqlite3_limit(D
4e60: 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69  ,C,V)] where V i
4e70: 73 0a 70 6f 73 69 74 69 76 65 20 63 68 61 6e 67  s.positive chang
4e80: 65 73 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20  es the limit on 
4e90: 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73  the size of cons
4ea0: 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a 5b  truct C in the.[
4eb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4ec0: 69 6f 6e 5d 20 44 20 74 6f 20 74 68 65 20 6c 65  ion] D to the le
4ed0: 73 73 65 72 20 6f 66 20 56 20 61 6e 64 20 74 68  sser of V and th
4ee0: 65 20 68 61 72 64 20 75 70 70 65 72 0a 62 6f 75  e hard upper.bou
4ef0: 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f  nd on the size o
4f00: 66 20 43 20 74 68 61 74 20 69 73 20 73 65 74 20  f C that is set 
4f10: 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e  at compile-time.
4f20: 0a 0a 48 4c 52 20 48 31 32 37 36 36 20 53 32 30  ..HLR H12766 S20
4f30: 36 30 30 0a 41 20 73 75 63 63 65 73 73 66 75 6c  600.A successful
4f40: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
4f50: 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20  3_limit(D,C,V)] 
4f60: 77 68 65 72 65 20 56 20 69 73 20 6e 65 67 61 74  where V is negat
4f70: 69 76 65 0a 6c 65 61 76 65 73 20 74 68 65 20 73  ive.leaves the s
4f80: 74 61 74 65 20 6f 66 20 74 68 65 20 5b 64 61 74  tate of the [dat
4f90: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4fa0: 5d 20 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a 0a  ] D unchanged...
4fb0: 48 4c 52 20 48 31 32 37 36 39 20 53 32 30 36 30  HLR H12769 S2060
4fc0: 30 0a 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  0.A successful c
4fd0: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
4fe0: 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 72 65  limit(D,C,V)] re
4ff0: 74 75 72 6e 73 20 74 68 65 0a 76 61 6c 75 65 20  turns the.value 
5000: 6f 66 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20  of the limit on 
5010: 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73  the size of cons
5020: 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a 5b  truct C in the.[
5030: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
5040: 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 61 73  ion] D as it was
5050: 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61   prior to the ca
5060: 6c 6c 2e 0a 0a 48 4c 52 20 48 31 32 38 30 31 20  ll...HLR H12801 
5070: 53 36 30 32 30 30 0a 54 68 65 20 5b 73 71 6c 69  S60200.The [sqli
5080: 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20  te3_errcode(D)] 
5090: 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
50a0: 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 5b 72  s the numeric.[r
50b0: 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b  esult code] or [
50c0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
50d0: 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
50e0: 73 74 20 72 65 63 65 6e 74 6c 79 0a 66 61 69 6c  st recently.fail
50f0: 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c  ed interface cal
5100: 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
5110: 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
5120: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 0a  connection] D...
5130: 48 4c 52 20 48 31 32 38 30 32 20 53 36 30 32 30  HLR H12802 S6020
5140: 30 0a 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  0.The [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  D)] interface re
5170: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
5180: 63 0a 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  c.[extended resu
5190: 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
51a0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a 66   most recently.f
51b0: 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20  ailed interface 
51c0: 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20  call associated 
51d0: 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
51e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
51f0: 2e 0a 0a 48 4c 52 20 48 31 32 38 30 33 20 53 36  ...HLR H12803 S6
5200: 30 32 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65  0200.The [sqlite
5210: 33 5f 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64  3_errmsg(D)] and
5220: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
5230: 31 36 28 44 29 5d 0a 69 6e 74 65 72 66 61 63 65  16(D)].interface
5240: 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  s return English
5250: 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20 74  -language text t
5260: 68 61 74 20 64 65 73 63 72 69 62 65 73 0a 74 68  hat describes.th
5270: 65 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 6d  e error in the m
5280: 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 66  ostly recently f
5290: 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20  ailed interface 
52a0: 63 61 6c 6c 2c 0a 65 6e 63 6f 64 65 64 20 61 73  call,.encoded as
52b0: 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
52c0: 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
52d0: 76 65 6c 79 2e 0a 0a 48 4c 52 20 48 31 32 38 30  vely...HLR H1280
52e0: 37 20 53 36 30 32 30 30 0a 54 68 65 20 73 74 72  7 S60200.The str
52f0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
5300: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
5310: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
5320: 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 61 72 65  _errmsg16()].are
5330: 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
5340: 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69 6e 74   next SQLite int
5350: 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 0a 48 4c  erface call...HL
5360: 52 20 48 31 32 38 30 38 20 53 36 30 32 30 30 0a  R H12808 S60200.
5370: 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75  Calls to API rou
5380: 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  tines that do no
5390: 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  t return an erro
53a0: 72 20 63 6f 64 65 0a 28 65 78 61 6d 70 6c 65 3a  r code.(example:
53b0: 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
53c0: 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a  ount()]) do not.
53d0: 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72  change the error
53e0: 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 67 65   code or message
53f0: 20 72 65 74 75 72 6e 65 64 20 62 79 0a 5b 73 71   returned by.[sq
5400: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
5410: 2c 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  , [sqlite3_exten
5420: 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a  ded_errcode()],.
5430: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
5440: 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
5450: 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 0a 48 4c  errmsg16()]...HL
5460: 52 20 48 31 32 38 30 39 20 53 36 30 32 30 30 0a  R H12809 S60200.
5470: 49 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20  Interfaces that 
5480: 61 72 65 20 6e 6f 74 20 61 73 73 6f 63 69 61 74  are not associat
5490: 65 64 20 77 69 74 68 20 61 20 73 70 65 63 69 66  ed with a specif
54a0: 69 63 0a 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ic.[database con
54b0: 6e 65 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c  nection] (exampl
54c0: 65 73 3a 0a 5b 73 71 6c 69 74 65 33 5f 6d 70 72  es:.[sqlite3_mpr
54d0: 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69  intf()] or [sqli
54e0: 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
54f0: 64 5f 63 61 63 68 65 28 29 5d 0a 64 6f 20 6e 6f  d_cache()].do no
5500: 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
5510: 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
5520: 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
5530: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 78  ()], [sqlite3_ex
5540: 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
5550: 5d 2c 0a 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ],.[sqlite3_errm
5560: 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  sg()], or [sqlit
5570: 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a  e3_errmsg16()]..
5580: 0a 48 4c 52 20 48 31 32 39 31 31 20 53 36 30 34  .HLR H12911 S604
5590: 30 30 0a 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  00.The callback 
55a0: 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
55b0: 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
55c0: 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
55d0: 29 0a 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72  ).is invoked per
55e0: 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
55f0: 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
5600: 6c 6c 73 20 74 6f 0a 5b 73 71 6c 69 74 65 33 5f  lls to.[sqlite3_
5610: 73 74 65 70 28 29 5d 2e 0a 0a 48 4c 52 20 48 31  step()]...HLR H1
5620: 32 39 31 32 20 53 36 30 34 30 30 0a 54 68 65 20  2912 S60400.The 
5630: 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
5640: 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  k is invoked onc
5650: 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69  e for every N vi
5660: 72 74 75 61 6c 0a 6d 61 63 68 69 6e 65 20 6f 70  rtual.machine op
5670: 63 6f 64 65 73 2c 20 77 68 65 72 65 20 4e 20 69  codes, where N i
5680: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
5690: 75 6d 65 6e 74 20 74 6f 0a 74 68 65 20 5b 73 71  ument to.the [sq
56a0: 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
56b0: 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74  andler()] call t
56c0: 68 61 74 20 72 65 67 69 73 74 65 72 65 64 0a 74  hat registered.t
56d0: 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66  he callback.  If
56e0: 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
56f0: 31 2c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  1, sqlite3_progr
5700: 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 61 63  ess_handler().ac
5710: 74 73 20 61 73 20 69 66 20 61 20 4e 55 4c 4c 20  ts as if a NULL 
5720: 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
5730: 20 68 61 64 20 62 65 65 6e 20 73 70 65 63 69 66   had been specif
5740: 69 65 64 2e 0a 0a 48 4c 52 20 48 31 32 39 31 33  ied...HLR H12913
5750: 20 53 36 30 34 30 30 0a 54 68 65 20 70 72 6f 67   S60400.The prog
5760: 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 74  ress callback it
5770: 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69  self is identifi
5780: 65 64 20 62 79 20 74 68 65 20 74 68 69 72 64 0a  ed by the third.
5790: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
57a0: 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
57b0: 64 6c 65 72 28 29 2e 0a 0a 48 4c 52 20 48 31 32  dler()...HLR H12
57c0: 39 31 34 20 53 36 30 34 30 30 0a 54 68 65 20 66  914 S60400.The f
57d0: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
57e0: 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  o sqlite3_progre
57f0: 73 73 5f 68 61 6e 64 6c 65 72 28 29 20 69 73 20  ss_handler() is 
5800: 61 0a 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70  a.void pointer p
5810: 61 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f  assed to the pro
5820: 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 66  gress callback.f
5830: 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d  unction each tim
5840: 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e  e it is invoked.
5850: 0a 0a 48 4c 52 20 48 31 32 39 31 35 20 53 36 30  ..HLR H12915 S60
5860: 34 30 30 0a 49 66 20 61 20 63 61 6c 6c 20 74 6f  400.If a call to
5870: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
5880: 5d 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77  ] results in few
5890: 65 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64 65  er than N opcode
58a0: 73 0a 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  s.being executed
58b0: 2c 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  , then the progr
58c0: 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ess callback is 
58d0: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 0a  never invoked...
58e0: 48 4c 52 20 48 31 32 39 31 36 20 53 36 30 34 30  HLR H12916 S6040
58f0: 30 0a 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20  0.Every call to 
5900: 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73  [sqlite3_progres
5910: 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 6f 76 65  s_handler()].ove
5920: 72 77 72 69 74 65 73 20 61 6e 79 20 70 72 65 76  rwrites any prev
5930: 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
5940: 64 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  d progress handl
5950: 65 72 2e 0a 0a 48 4c 52 20 48 31 32 39 31 37 20  er...HLR H12917 
5960: 53 36 30 34 30 30 0a 49 66 20 74 68 65 20 70 72  S60400.If the pr
5970: 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
5980: 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 20  allback is NULL 
5990: 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73 73  then no progress
59a0: 0a 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f  .handler is invo
59b0: 6b 65 64 2e 0a 0a 48 4c 52 20 48 31 32 39 31 38  ked...HLR H12918
59c0: 20 53 33 30 35 30 30 20 53 36 30 34 30 30 0a 49   S30500 S60400.I
59d0: 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
59e0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
59f0: 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74  a result other t
5a00: 68 61 6e 20 30 2c 20 74 68 65 6e 0a 74 68 65 20  han 0, then.the 
5a10: 62 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 66  behavior is a if
5a20: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
5a30: 75 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20  upt()] had been 
5a40: 63 61 6c 6c 65 64 2e 0a 0a 48 4c 52 20 48 31 32  called...HLR H12
5a50: 39 33 31 20 53 36 30 32 30 30 0a 54 68 65 20 5b  931 S60200.The [
5a60: 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
5a70: 63 6f 6d 6d 69 74 28 44 29 5d 20 69 6e 74 65 72  commit(D)] inter
5a80: 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e  face returns non
5a90: 2d 7a 65 72 6f 20 6f 72 0a 7a 65 72 6f 20 69 66  -zero or.zero if
5aa0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
5ab0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 73 20  onnection] D is 
5ac0: 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
5ad0: 6f 63 6f 6d 6d 69 74 0a 6d 6f 64 65 2c 20 72 65  ocommit.mode, re
5ae0: 73 70 65 63 74 69 76 65 6c 79 2e 0a 0a 48 4c 52  spectively...HLR
5af0: 20 48 31 32 39 33 32 20 53 36 30 32 30 30 0a 41   H12932 S60200.A
5b00: 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
5b10: 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
5b20: 0a 0a 48 4c 52 20 48 31 32 39 33 33 20 53 36 30  ..HLR H12933 S60
5b30: 32 30 30 0a 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  200.Autocommit m
5b40: 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
5b50: 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c 20  by a successful 
5b60: 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e  [BEGIN] statemen
5b70: 74 2e 0a 0a 48 4c 52 20 48 31 32 39 33 34 20 53  t...HLR H12934 S
5b80: 36 30 32 30 30 0a 41 75 74 6f 63 6f 6d 6d 69 74  60200.Autocommit
5b90: 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
5ba0: 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c   by a successful
5bb0: 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
5bc0: 4c 4c 42 41 43 4b 5d 0a 73 74 61 74 65 6d 65 6e  LLBACK].statemen
5bd0: 74 2e 0a 0a 48 4c 52 20 48 31 32 39 35 31 20 53  t...HLR H12951 S
5be0: 36 30 34 30 30 0a 54 68 65 20 5b 73 71 6c 69 74  60400.The [sqlit
5bf0: 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44  e3_commit_hook(D
5c00: 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
5c10: 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 63   registers the.c
5c20: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
5c30: 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   F to be invoked
5c40: 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
5c50: 20 77 68 65 6e 65 76 65 72 0a 61 20 74 72 61 6e   whenever.a tran
5c60: 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 20  saction commits 
5c70: 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
5c80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
5c90: 0a 48 4c 52 20 48 31 32 39 35 32 20 53 36 30 34  .HLR H12952 S604
5ca0: 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  00.The [sqlite3_
5cb0: 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c  commit_hook(D,F,
5cc0: 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  P)] interface re
5cd0: 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75  turns the P argu
5ce0: 6d 65 6e 74 0a 66 72 6f 6d 20 74 68 65 20 70 72  ment.from the pr
5cf0: 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68  evious call with
5d00: 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
5d10: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
5d20: 44 2c 0a 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68  D,.or NULL on th
5d30: 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72  e first call for
5d40: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
5d50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
5d60: 6e 20 44 2e 0a 0a 48 4c 52 20 48 31 32 39 35 33  n D...HLR H12953
5d70: 20 53 36 30 34 30 30 0a 45 61 63 68 20 63 61 6c   S60400.Each cal
5d80: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
5d90: 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65  mmit_hook()] ove
5da0: 72 77 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c  rwrites the call
5db0: 62 61 63 6b 0a 72 65 67 69 73 74 65 72 65 64 20  back.registered 
5dc0: 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a  by prior calls..
5dd0: 0a 48 4c 52 20 48 31 32 39 35 34 20 53 36 30 34  .HLR H12954 S604
5de0: 30 30 0a 49 66 20 74 68 65 20 46 20 61 72 67 75  00.If the F argu
5df0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
5e00: 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46  _commit_hook(D,F
5e10: 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 74 68 65  ,P)] is NULL.the
5e20: 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  n the commit hoo
5e30: 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61  k callback is ca
5e40: 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61  nceled and no ca
5e50: 6c 6c 62 61 63 6b 0a 69 73 20 69 6e 76 6f 6b 65  llback.is invoke
5e60: 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63  d when a transac
5e70: 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 0a 48  tion commits...H
5e80: 4c 52 20 48 31 32 39 35 35 20 53 36 30 34 30 30  LR H12955 S60400
5e90: 0a 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 63  .If the commit c
5ea0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
5eb0: 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e 20 74 68  non-zero then th
5ec0: 65 20 63 6f 6d 6d 69 74 20 69 73 0a 63 6f 6e 76  e commit is.conv
5ed0: 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
5ee0: 6c 62 61 63 6b 2e 0a 0a 48 4c 52 20 48 31 32 39  lback...HLR H129
5ef0: 36 31 20 53 36 30 34 30 30 0a 54 68 65 20 5b 73  61 S60400.The [s
5f00: 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
5f10: 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
5f20: 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
5f30: 20 74 68 65 0a 63 61 6c 6c 62 61 63 6b 20 66 75   the.callback fu
5f40: 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69  nction F to be i
5f50: 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
5f60: 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
5f70: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f  a transaction ro
5f80: 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 74 68 65 20  lls back on the 
5f90: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
5fa0: 74 69 6f 6e 5d 20 44 2e 0a 0a 48 4c 52 20 48 31  tion] D...HLR H1
5fb0: 32 39 36 32 20 53 36 30 34 30 30 0a 54 68 65 20  2962 S60400.The 
5fc0: 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
5fd0: 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  k_hook(D,F,P)] i
5fe0: 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
5ff0: 20 74 68 65 20 50 0a 61 72 67 75 6d 65 6e 74 20   the P.argument 
6000: 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
6010: 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20  s call with the 
6020: 73 61 6d 65 0a 5b 64 61 74 61 62 61 73 65 20 63  same.[database c
6030: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72  onnection] D, or
6040: 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72   NULL on the fir
6050: 73 74 20 63 61 6c 6c 0a 66 6f 72 20 61 20 70 61  st call.for a pa
6060: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
6070: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a  e connection D..
6080: 0a 48 4c 52 20 48 31 32 39 36 33 20 53 36 30 34  .HLR H12963 S604
6090: 30 30 0a 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  00.Each call to 
60a0: 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
60b0: 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72  k_hook()] overwr
60c0: 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  ites the callbac
60d0: 6b 0a 72 65 67 69 73 74 65 72 65 64 20 62 79 20  k.registered by 
60e0: 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 0a 48 4c  prior calls...HL
60f0: 52 20 48 31 32 39 36 34 20 53 36 30 34 30 30 0a  R H12964 S60400.
6100: 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e  If the F argumen
6110: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f  t to [sqlite3_ro
6120: 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c  llback_hook(D,F,
6130: 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 74 68 65 6e  P)] is NULL.then
6140: 20 74 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f   the rollback ho
6150: 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63  ok callback is c
6160: 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63  anceled and no c
6170: 61 6c 6c 62 61 63 6b 0a 69 73 20 69 6e 76 6f 6b  allback.is invok
6180: 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61  ed when a transa
6190: 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b  ction rolls back
61a0: 2e 0a 0a 48 4c 52 20 48 31 32 39 37 31 20 53 36  ...HLR H12971 S6
61b0: 30 34 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65  0400.The [sqlite
61c0: 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
61d0: 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
61e0: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
61f0: 61 63 6b 0a 66 75 6e 63 74 69 6f 6e 20 46 20 74  ack.function F t
6200: 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  o be invoked wit
6210: 68 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  h first paramete
6220: 72 20 50 20 77 68 65 6e 65 76 65 72 0a 61 20 74  r P whenever.a t
6230: 61 62 6c 65 20 72 6f 77 20 69 73 20 6d 6f 64 69  able row is modi
6240: 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 2c 20  fied, inserted, 
6250: 6f 72 20 64 65 6c 65 74 65 64 20 6f 6e 0a 74 68  or deleted on.th
6260: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
6270: 65 63 74 69 6f 6e 5d 20 44 2e 0a 0a 48 4c 52 20  ection] D...HLR 
6280: 48 31 32 39 37 33 20 53 36 30 34 30 30 0a 54 68  H12973 S60400.Th
6290: 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
62a0: 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  e_hook(D,F,P)] i
62b0: 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
62c0: 20 74 68 65 20 76 61 6c 75 65 0a 6f 66 20 50 20   the value.of P 
62d0: 66 6f 72 20 74 68 65 20 70 72 65 76 69 6f 75 73  for the previous
62e0: 20 63 61 6c 6c 20 6f 6e 20 74 68 65 20 73 61 6d   call on the sam
62f0: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
6300: 65 63 74 69 6f 6e 5d 20 44 2c 0a 6f 72 20 4e 55  ection] D,.or NU
6310: 4c 4c 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  LL for the first
6320: 20 63 61 6c 6c 2e 0a 0a 48 4c 52 20 48 31 32 39   call...HLR H129
6330: 37 35 20 53 36 30 34 30 30 0a 49 66 20 74 68 65  75 S60400.If the
6340: 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c   update hook cal
6350: 6c 62 61 63 6b 20 46 20 69 6e 20 5b 73 71 6c 69  lback F in [sqli
6360: 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
6370: 44 2c 46 2c 50 29 5d 0a 69 73 20 4e 55 4c 4c 20  D,F,P)].is NULL 
6380: 74 68 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 61  then the no upda
6390: 74 65 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65  te callbacks are
63a0: 20 6d 61 64 65 2e 0a 0a 48 4c 52 20 48 31 32 39   made...HLR H129
63b0: 37 37 20 53 36 30 34 30 30 0a 45 61 63 68 20 63  77 S60400.Each c
63c0: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
63d0: 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c  update_hook(D,F,
63e0: 50 29 5d 20 6f 76 65 72 72 69 64 65 73 20 70 72  P)] overrides pr
63f0: 69 6f 72 20 63 61 6c 6c 73 0a 74 6f 20 74 68 65  ior calls.to the
6400: 20 73 61 6d 65 20 69 6e 74 65 72 66 61 63 65 20   same interface 
6410: 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
6420: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
6430: 5d 20 44 2e 0a 0a 48 4c 52 20 48 31 32 39 37 39  ] D...HLR H12979
6440: 20 53 36 30 34 30 30 0a 54 68 65 20 75 70 64 61   S60400.The upda
6450: 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  te hook callback
6460: 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
6470: 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79  when internal sy
6480: 73 74 65 6d 0a 74 61 62 6c 65 73 20 73 75 63 68  stem.tables such
6490: 20 61 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 65   as sqlite_maste
64a0: 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
64b0: 75 65 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 69  uence are modifi
64c0: 65 64 2e 0a 0a 48 4c 52 20 48 31 32 39 38 31 20  ed...HLR H12981 
64d0: 53 36 30 34 30 30 0a 54 68 65 20 73 65 63 6f 6e  S60400.The secon
64e0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
64f0: 68 65 20 75 70 64 61 74 65 20 63 61 6c 6c 62 61  he update callba
6500: 63 6b 0a 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ck.is one of [SQ
6510: 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
6520: 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72  QLITE_DELETE] or
6530: 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d   [SQLITE_UPDATE]
6540: 2c 0a 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  ,.depending on t
6550: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  he operation tha
6560: 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c  t caused the cal
6570: 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f  lback to be invo
6580: 6b 65 64 2e 0a 0a 48 4c 52 20 48 31 32 39 38 33  ked...HLR H12983
6590: 20 53 36 30 34 30 30 0a 54 68 65 20 74 68 69 72   S60400.The thir
65a0: 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67  d and fourth arg
65b0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
65c0: 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
65d0: 6f 69 6e 74 65 72 73 0a 74 6f 20 7a 65 72 6f 2d  ointers.to zero-
65e0: 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
65f0: 20 73 74 72 69 6e 67 73 20 77 68 69 63 68 20 61   strings which a
6600: 72 65 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  re the names of 
6610: 74 68 65 0a 64 61 74 61 62 61 73 65 20 61 6e 64  the.database and
6620: 20 74 61 62 6c 65 20 74 68 61 74 20 69 73 20 62   table that is b
6630: 65 69 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a 48  eing updated...H
6640: 4c 52 20 48 31 32 39 38 36 20 53 36 30 34 30 30  LR H12986 S60400
6650: 0a 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62  .The final callb
6660: 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
6670: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
6680: 65 20 72 6f 77 20 61 66 74 65 72 0a 74 68 65 20  e row after.the 
6690: 63 68 61 6e 67 65 20 6f 63 63 75 72 73 2e 0a 0a  change occurs...
66a0: 48 4c 52 20 48 31 33 30 31 31 20 53 31 30 30 30  HLR H13011 S1000
66b0: 30 0a 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  0.The [sqlite3_p
66c0: 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 2e  repare(db,zSql,.
66d0: 2e 2e 29 5d 20 61 6e 64 0a 5b 73 71 6c 69 74 65  ..)] and.[sqlite
66e0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
66f0: 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  zSql,...)] inter
6700: 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20  faces interpret 
6710: 74 68 65 0a 74 65 78 74 20 69 6e 20 74 68 65 69  the.text in thei
6720: 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72  r zSql parameter
6730: 20 61 73 20 55 54 46 2d 38 2e 0a 0a 48 4c 52 20   as UTF-8...HLR 
6740: 48 31 33 30 31 32 20 53 31 30 30 30 30 0a 54 68  H13012 S10000.Th
6750: 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
6760: 72 65 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  re16(db,zSql,...
6770: 29 5d 20 61 6e 64 0a 5b 73 71 6c 69 74 65 33 5f  )] and.[sqlite3_
6780: 70 72 65 70 61 72 65 31 36 5f 76 32 28 64 62 2c  prepare16_v2(db,
6790: 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  zSql,...)] inter
67a0: 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20  faces interpret 
67b0: 74 68 65 0a 74 65 78 74 20 69 6e 20 74 68 65 69  the.text in thei
67c0: 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72  r zSql parameter
67d0: 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
67e0: 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
67f0: 64 65 72 2e 0a 0a 48 4c 52 20 48 31 33 30 31 33  der...HLR H13013
6800: 20 53 31 30 30 30 30 0a 49 66 20 74 68 65 20 6e   S10000.If the n
6810: 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  Byte argument to
6820: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
6830: 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  e_v2(db,zSql,nBy
6840: 74 65 2c 2e 2e 2e 29 5d 0a 61 6e 64 20 69 74 73  te,...)].and its
6850: 20 76 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73   variants is les
6860: 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
6870: 20 53 51 4c 20 74 65 78 74 20 69 73 0a 72 65 61   SQL text is.rea
6880: 64 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73 20 72  d from zSql is r
6890: 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 66 69  ead up to the fi
68a0: 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
68b0: 74 6f 72 2e 0a 0a 48 4c 52 20 48 31 33 30 31 34  tor...HLR H13014
68c0: 20 53 31 30 30 30 30 0a 49 66 20 74 68 65 20 6e   S10000.If the n
68d0: 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  Byte argument to
68e0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
68f0: 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  e_v2(db,zSql,nBy
6900: 74 65 2c 2e 2e 2e 29 5d 0a 61 6e 64 20 69 74 73  te,...)].and its
6910: 20 76 61 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e   variants is non
6920: 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
6930: 61 74 20 6d 6f 73 74 20 6e 42 79 74 65 73 20 62  at most nBytes b
6940: 79 74 65 73 20 6f 66 0a 53 51 4c 20 74 65 78 74  ytes of.SQL text
6950: 20 69 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53   is read from zS
6960: 71 6c 2e 0a 0a 48 4c 52 20 48 31 33 30 31 35 20  ql...HLR H13015 
6970: 53 31 30 30 30 30 0a 49 6e 20 5b 73 71 6c 69 74  S10000.In [sqlit
6980: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
6990: 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c  ,zSql,N,P,pzTail
69a0: 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
69b0: 6e 74 73 0a 69 66 20 74 68 65 20 7a 53 71 6c 20  nts.if the zSql 
69c0: 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
69d0: 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ins more than on
69e0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  e SQL statement.
69f0: 61 6e 64 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  and pzTail is no
6a00: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a  t NULL, then *pz
6a10: 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
6a20: 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a 66 69 72  point to the.fir
6a30: 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65  st byte past the
6a40: 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
6a50: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
6a60: 69 6e 20 7a 53 71 6c 2e 0a 3c 74 6f 64 6f 3e 57  in zSql..<todo>W
6a70: 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 69 6c  hat does *pzTail
6a80: 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 68 65   point to if the
6a90: 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74 65 6d  re is one statem
6aa0: 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 0a 48 4c 52  ent?</todo>..HLR
6ab0: 20 48 31 33 30 31 36 20 53 31 30 30 30 30 0a 41   H13016 S10000.A
6ac0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
6ad0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
6ae0: 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
6af0: 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 6f  N,ppStmt,...)].o
6b00: 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
6b10: 69 61 6e 74 73 20 77 72 69 74 65 73 20 69 6e 74  iants writes int
6b20: 6f 20 2a 70 70 53 74 6d 74 20 61 20 70 6f 69 6e  o *ppStmt a poin
6b30: 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 5b 70 72  ter to a new.[pr
6b40: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
6b50: 5d 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  ] or a pointer t
6b60: 6f 20 4e 55 4c 4c 20 69 66 20 7a 53 71 6c 20 63  o NULL if zSql c
6b70: 6f 6e 74 61 69 6e 73 0a 6e 6f 74 68 69 6e 67 20  ontains.nothing 
6b80: 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74 65  other than white
6b90: 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e 74  space or comment
6ba0: 73 2e 0a 0a 48 4c 52 20 48 31 33 30 31 39 20 53  s...HLR H13019 S
6bb0: 31 30 30 30 30 0a 54 68 65 20 5b 73 71 6c 69 74  10000.The [sqlit
6bc0: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
6bd0: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69   interface and i
6be0: 74 73 20 76 61 72 69 61 6e 74 73 20 72 65 74 75  ts variants retu
6bf0: 72 6e 0a 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn.[SQLITE_OK] o
6c00: 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
6c10: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
6c20: 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 0a 48 4c 52  on failure...HLR
6c30: 20 48 31 33 30 32 31 20 53 31 30 30 30 30 0a 42   H13021 S10000.B
6c40: 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 70  efore [sqlite3_p
6c50: 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e  repare(db,zSql,n
6c60: 42 79 74 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61  Byte,ppStmt,pzTa
6c70: 69 6c 29 5d 20 6f 72 20 69 74 73 0a 76 61 72 69  il)] or its.vari
6c80: 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61 6e 20  ants returns an 
6c90: 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c 75 65  error (any value
6ca0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
6cb0: 49 54 45 5f 4f 4b 5d 29 2c 0a 74 68 65 79 20 66  ITE_OK]),.they f
6cc0: 69 72 73 74 20 73 65 74 20 2a 70 70 53 74 6d 74  irst set *ppStmt
6cd0: 20 74 6f 20 4e 55 4c 4c 2e 0a 0a 48 4c 52 20 48   to NULL...HLR H
6ce0: 31 33 31 30 31 20 48 31 33 30 30 30 0a 49 66 20  13101 H13000.If 
6cf0: 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
6d00: 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20  atement] passed 
6d10: 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  as the argument 
6d20: 74 6f 0a 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28  to.[sqlite3_sql(
6d30: 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  )] was compiled 
6d40: 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
6d50: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
6d60: 28 29 5d 20 6f 72 0a 5b 73 71 6c 69 74 65 33 5f  ()] or.[sqlite3_
6d70: 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c  prepare16_v2()],
6d80: 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   then [sqlite3_s
6d90: 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a 61 20  ql()] returns.a 
6da0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
6db0: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
6dc0: 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  ing containing a
6dd0: 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
6de0: 0a 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .of the original
6df0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
6e00: 0a 48 4c 52 20 48 31 33 31 30 32 20 48 31 33 30  .HLR H13102 H130
6e10: 30 30 0a 49 66 20 74 68 65 20 5b 70 72 65 70 61  00.If the [prepa
6e20: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70  red statement] p
6e30: 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72 67  assed as the arg
6e40: 75 6d 65 6e 74 20 74 6f 0a 5b 73 71 6c 69 74 65  ument to.[sqlite
6e50: 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d  3_sql()] was com
6e60: 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
6e70: 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
6e80: 61 72 65 28 29 5d 20 6f 72 0a 5b 73 71 6c 69 74  are()] or.[sqlit
6e90: 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
6ea0: 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   then [sqlite3_s
6eb0: 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 20 61 20  ql()] returns a 
6ec0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 0a 48  NULL pointer...H
6ed0: 4c 52 20 48 31 33 31 30 33 20 48 31 33 30 30 30  LR H13103 H13000
6ee0: 0a 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75  .The string retu
6ef0: 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
6f00: 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c 69  _sql(S)] is vali
6f10: 64 20 75 6e 74 69 6c 20 74 68 65 0a 5b 70 72 65  d until the.[pre
6f20: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
6f30: 20 53 20 69 73 20 64 65 6c 65 74 65 64 20 75 73   S is deleted us
6f40: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
6f50: 61 6c 69 7a 65 28 53 29 5d 2e 0a 0a 48 4c 52 20  alize(S)]...HLR 
6f60: 48 31 33 31 32 33 20 53 36 30 36 30 30 0a 54 68  H13123 S60600.Th
6f70: 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  e [sqlite3_db_ha
6f80: 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65 72 66 61  ndle(S)] interfa
6f90: 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
6fa0: 6e 74 65 72 0a 74 6f 20 74 68 65 20 5b 64 61 74  nter.to the [dat
6fb0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
6fc0: 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  ] associated wit
6fd0: 68 20 74 68 65 0a 5b 70 72 65 70 61 72 65 64 20  h the.[prepared 
6fe0: 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 0a 48  statement] S...H
6ff0: 4c 52 20 48 31 33 31 34 33 20 53 36 30 36 30 30  LR H13143 S60600
7000: 0a 49 66 20 44 20 69 73 20 61 20 5b 64 61 74 61  .If D is a [data
7010: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
7020: 20 74 68 61 74 20 68 6f 6c 64 73 20 6f 6e 65 20   that holds one 
7030: 6f 72 20 6d 6f 72 65 0a 75 6e 66 69 6e 61 6c 69  or more.unfinali
7040: 7a 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  zed [prepared st
7050: 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20  atements] and S 
7060: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
7070: 72 2c 0a 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  r,.then [sqlite3
7080: 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29  _next_stmt(D, S)
7090: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
70a0: 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
70b0: 0a 74 6f 20 6f 6e 65 20 6f 66 20 74 68 65 20 70  .to one of the p
70c0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
70d0: 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
70e0: 74 68 20 44 2e 0a 0a 48 4c 52 20 48 31 33 31 34  th D...HLR H1314
70f0: 36 20 53 36 30 36 30 30 0a 49 66 20 44 20 69 73  6 S60600.If D is
7100: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
7110: 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f  nection] that ho
7120: 6c 64 73 20 6e 6f 20 75 6e 66 69 6e 61 6c 69 7a  lds no unfinaliz
7130: 65 64 0a 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed.[prepared sta
7140: 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20 69  tements] and S i
7150: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
7160: 2c 20 74 68 65 6e 0a 5b 73 71 6c 69 74 65 33 5f  , then.[sqlite3_
7170: 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d  next_stmt(D, S)]
7180: 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72   routine shall r
7190: 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  eturn a NULL poi
71a0: 6e 74 65 72 2e 0a 0a 48 4c 52 20 48 31 33 31 34  nter...HLR H1314
71b0: 39 20 53 36 30 36 30 30 0a 49 66 20 53 20 69 73  9 S60600.If S is
71c0: 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
71d0: 74 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65 20 5b  tement] in the [
71e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
71f0: 69 6f 6e 5d 20 44 0a 61 6e 64 20 53 20 69 73 20  ion] D.and S is 
7200: 6e 6f 74 20 74 68 65 20 6c 61 73 74 20 70 72 65  not the last pre
7210: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
7220: 69 6e 20 44 2c 20 74 68 65 6e 0a 5b 73 71 6c 69  in D, then.[sqli
7230: 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
7240: 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61   S)] routine sha
7250: 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  ll return a poin
7260: 74 65 72 0a 74 6f 20 74 68 65 20 6e 65 78 74 20  ter.to the next 
7270: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
7280: 6e 74 20 69 6e 20 44 20 61 66 74 65 72 20 53 2e  nt in D after S.
7290: 0a 0a 48 4c 52 20 48 31 33 31 35 32 20 53 36 30  ..HLR H13152 S60
72a0: 36 30 30 0a 49 66 20 53 20 69 73 20 74 68 65 20  600.If S is the 
72b0: 6c 61 73 74 20 5b 70 72 65 70 61 72 65 64 20 73  last [prepared s
72c0: 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65  tatement] in the
72d0: 0a 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  .[database conne
72e0: 63 74 69 6f 6e 5d 20 44 20 74 68 65 6e 20 74 68  ction] D then th
72f0: 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  e [sqlite3_next_
7300: 73 74 6d 74 28 44 2c 20 53 29 5d 0a 72 6f 75 74  stmt(D, S)].rout
7310: 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ine shall return
7320: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
7330: 0a 0a 48 4c 52 20 48 31 33 32 30 32 20 53 31 30  ..HLR H13202 S10
7340: 30 30 30 0a 49 66 20 74 68 65 20 5b 70 72 65 70  000.If the [prep
7350: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
7360: 53 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65  S is ready to be
7370: 20 72 75 6e 2c 20 74 68 65 6e 0a 5b 73 71 6c 69   run, then.[sqli
7380: 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61 64 76  te3_step(S)] adv
7390: 61 6e 63 65 73 20 74 68 61 74 20 70 72 65 70 61  ances that prepa
73a0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 6e  red statement un
73b0: 74 69 6c 0a 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  til.completion o
73c0: 72 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65  r until it is re
73d0: 61 64 79 20 74 6f 20 72 65 74 75 72 6e 20 61 6e  ady to return an
73e0: 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65  other row of the
73f0: 0a 72 65 73 75 6c 74 20 73 65 74 2c 20 6f 72 20  .result set, or 
7400: 75 6e 74 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65  until an [sqlite
7410: 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e  3_interrupt | in
7420: 74 65 72 72 75 70 74 5d 0a 6f 72 20 61 20 72 75  terrupt].or a ru
7430: 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f 63 63  n-time error occ
7440: 75 72 73 2e 0a 0a 48 4c 52 20 48 31 33 35 30 36  urs...HLR H13506
7450: 20 53 37 30 33 30 30 0a 54 68 65 20 5b 53 51 4c   S70300.The [SQL
7460: 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
7470: 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73 20  ler] recognizes 
7480: 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66 6f  tokens of the fo
7490: 72 6d 73 0a 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  rms."?", "?NNN",
74a0: 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56 22 2c   "$VVV", ":VVV",
74b0: 20 61 6e 64 20 22 40 56 56 56 22 20 61 73 20 53   and "@VVV" as S
74c0: 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2c 0a 77  QL parameters,.w
74d0: 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20  here NNN is any 
74e0: 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20  sequence of one 
74f0: 6f 72 20 6d 6f 72 65 20 64 69 67 69 74 73 0a 61  or more digits.a
7500: 6e 64 20 77 68 65 72 65 20 56 56 56 20 69 73 20  nd where VVV is 
7510: 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20  any sequence of 
7520: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 61 6c 70 68  one or more alph
7530: 61 6e 75 6d 65 72 69 63 0a 63 68 61 72 61 63 74  anumeric.charact
7540: 65 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69  ers or "::" opti
7550: 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20  onally followed 
7560: 62 79 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74  by a string cont
7570: 61 69 6e 69 6e 67 0a 6e 6f 20 73 70 61 63 65 73  aining.no spaces
7580: 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20 77   and contained w
7590: 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73 65  ithin parenthese
75a0: 73 2e 0a 0a 48 4c 52 20 48 31 33 35 30 39 20 53  s...HLR H13509 S
75b0: 37 30 33 30 30 0a 54 68 65 20 69 6e 69 74 69 61  70300.The initia
75c0: 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51  l value of an SQ
75d0: 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  L parameter is N
75e0: 55 4c 4c 2e 0a 0a 48 4c 52 20 48 31 33 35 31 32  ULL...HLR H13512
75f0: 20 53 37 30 33 30 30 0a 54 68 65 20 69 6e 64 65   S70300.The inde
7600: 78 20 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c 20  x of an "?" SQL 
7610: 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
7620: 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
7630: 0a 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f  .largest index o
7640: 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  f SQL parameter 
7650: 74 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f 72 20  to the left, or 
7660: 31 20 69 66 0a 74 68 65 20 22 3f 22 20 69 73 20  1 if.the "?" is 
7670: 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  the leftmost SQL
7680: 20 70 61 72 61 6d 65 74 65 72 2e 0a 0a 48 4c 52   parameter...HLR
7690: 20 48 31 33 35 31 35 20 53 37 30 33 30 30 0a 54   H13515 S70300.T
76a0: 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22  he index of an "
76b0: 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d 65  ?NNN" SQL parame
76c0: 74 65 72 20 69 73 20 74 68 65 20 69 6e 74 65 67  ter is the integ
76d0: 65 72 20 4e 4e 4e 2e 0a 0a 48 4c 52 20 48 31 33  er NNN...HLR H13
76e0: 35 31 38 20 53 37 30 33 30 30 0a 54 68 65 20 69  518 S70300.The i
76f0: 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a 56 56 56  ndex of an ":VVV
7700: 22 2c 20 22 24 56 56 56 22 2c 20 6f 72 20 22 40  ", "$VVV", or "@
7710: 56 56 56 22 20 53 51 4c 20 70 61 72 61 6d 65 74  VVV" SQL paramet
7720: 65 72 20 69 73 0a 74 68 65 20 73 61 6d 65 20 61  er is.the same a
7730: 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 6c  s the index of l
7740: 65 66 74 6d 6f 73 74 20 6f 63 63 75 72 72 65 6e  eftmost occurren
7750: 63 65 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ces of the same.
7760: 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e  parameter, or on
7770: 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 20  e more than the 
7780: 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 76  largest index ov
7790: 65 72 20 61 6c 6c 0a 70 61 72 61 6d 65 74 65 72  er all.parameter
77a0: 73 20 74 6f 20 74 68 65 20 6c 65 66 74 20 69 66  s to the left if
77b0: 20 74 68 69 73 20 69 73 20 74 68 65 20 66 69 72   this is the fir
77c0: 73 74 20 6f 63 63 75 72 72 65 6e 63 65 0a 6f 66  st occurrence.of
77d0: 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c   this parameter,
77e0: 20 6f 72 20 31 20 69 66 20 74 68 69 73 20 69 73   or 1 if this is
77f0: 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61   the leftmost pa
7800: 72 61 6d 65 74 65 72 2e 0a 0a 48 4c 52 20 48 31  rameter...HLR H1
7810: 33 35 32 31 20 53 37 30 33 30 30 0a 54 68 65 20  3521 S70300.The 
7820: 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  [SQL statement c
7830: 6f 6d 70 69 6c 65 72 5d 20 66 61 69 6c 73 20 77  ompiler] fails w
7840: 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52  ith an [SQLITE_R
7850: 41 4e 47 45 5d 0a 65 72 72 6f 72 20 69 66 20 74  ANGE].error if t
7860: 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
7870: 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
7880: 6c 65 73 73 20 74 68 61 6e 20 31 0a 6f 72 20 67  less than 1.or g
7890: 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
78a0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53 51 4c  compile-time SQL
78b0: 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45  ITE_MAX_VARIABLE
78c0: 5f 4e 55 4d 42 45 52 0a 70 61 72 61 6d 65 74 65  _NUMBER.paramete
78d0: 72 2e 0a 0a 48 4c 52 20 48 31 33 35 32 34 20 53  r...HLR H13524 S
78e0: 37 30 33 30 30 0a 43 61 6c 6c 73 20 74 6f 20 5b  70300.Calls to [
78f0: 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
7900: 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  t | sqlite3_bind
7910: 28 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 61 73 73  (S,N,V,...)].ass
7920: 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c 75 65  ociate the value
7930: 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51 4c 20   V with all SQL 
7940: 70 61 72 61 6d 65 74 65 72 73 20 68 61 76 69 6e  parameters havin
7950: 67 20 61 6e 0a 69 6e 64 65 78 20 6f 66 20 4e 20  g an.index of N 
7960: 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
7970: 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 0a   statement] S...
7980: 48 4c 52 20 48 31 33 35 32 37 20 53 37 30 33 30  HLR H13527 S7030
7990: 30 0a 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  0.Calls to [sqli
79a0: 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
79b0: 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e  sqlite3_bind(S,N
79c0: 2c 2e 2e 2e 29 5d 0a 6f 76 65 72 72 69 64 65 20  ,...)].override 
79d0: 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68  prior calls with
79e0: 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73   the same values
79f0: 20 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 0a 48 4c   of S and N...HL
7a00: 52 20 48 31 33 35 33 30 20 53 37 30 33 30 30 0a  R H13530 S70300.
7a10: 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62 6c 69  Bindings establi
7a20: 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  shed by [sqlite3
7a30: 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c  _bind_text | sql
7a40: 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e 29  ite3_bind(S,...)
7a50: 5d 0a 70 65 72 73 69 73 74 20 61 63 72 6f 73 73  ].persist across
7a60: 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
7a70: 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a 0a 48  e3_reset(S)]...H
7a80: 4c 52 20 48 31 33 35 33 33 20 53 37 30 33 30 30  LR H13533 S70300
7a90: 0a 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  .In calls to [sq
7aa0: 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
7ab0: 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 5b 73 71  S,N,V,L,D)],.[sq
7ac0: 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
7ad0: 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a  S,N,V,L,D)], or.
7ae0: 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
7af0: 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  xt16(S,N,V,L,D)]
7b00: 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 74 68   SQLite binds th
7b10: 65 20 66 69 72 73 74 20 4c 0a 62 79 74 65 73 20  e first L.bytes 
7b20: 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
7b30: 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
7b40: 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a 69 73   by V, when L.is
7b50: 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 0a   non-negative...
7b60: 48 4c 52 20 48 31 33 35 33 36 20 53 37 30 33 30  HLR H13536 S7030
7b70: 30 0a 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  0.In calls to [s
7b80: 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
7b90: 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a  (S,N,V,L,D)] or.
7ba0: 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
7bb0: 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  xt16(S,N,V,L,D)]
7bc0: 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 63 68   SQLite binds ch
7bd0: 61 72 61 63 74 65 72 73 0a 66 72 6f 6d 20 56 20  aracters.from V 
7be0: 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
7bf0: 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
7c00: 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74   when L is negat
7c10: 69 76 65 2e 0a 0a 48 4c 52 20 48 31 33 35 33 39  ive...HLR H13539
7c20: 20 53 37 30 33 30 30 0a 49 6e 20 63 61 6c 6c 73   S70300.In calls
7c30: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
7c40: 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
7c50: 29 5d 2c 0a 5b 73 71 6c 69 74 65 33 5f 62 69 6e  )],.[sqlite3_bin
7c60: 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
7c70: 29 5d 2c 20 6f 72 0a 5b 73 71 6c 69 74 65 33 5f  )], or.[sqlite3_
7c80: 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c  bind_text16(S,N,
7c90: 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69  V,L,D)] when D i
7ca0: 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 63 6f  s the special.co
7cb0: 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53  nstant [SQLITE_S
7cc0: 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61  TATIC], SQLite a
7cd0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
7ce0: 76 61 6c 75 65 20 56 0a 69 73 20 68 65 6c 64 20  value V.is held 
7cf0: 69 6e 20 73 74 61 74 69 63 20 75 6e 6d 61 6e 61  in static unmana
7d00: 67 65 64 20 73 70 61 63 65 20 74 68 61 74 20 77  ged space that w
7d10: 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a 64  ill not change.d
7d20: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
7d30: 6d 65 20 6f 66 20 74 68 65 20 62 69 6e 64 69 6e  me of the bindin
7d40: 67 2e 0a 0a 48 4c 52 20 48 31 33 35 34 32 20 53  g...HLR H13542 S
7d50: 37 30 33 30 30 0a 49 6e 20 63 61 6c 6c 73 20 74  70300.In calls t
7d60: 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
7d70: 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
7d80: 2c 0a 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ,.[sqlite3_bind_
7d90: 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
7da0: 2c 20 6f 72 0a 5b 73 71 6c 69 74 65 33 5f 62 69  , or.[sqlite3_bi
7db0: 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
7dc0: 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20  L,D)] when D is 
7dd0: 74 68 65 20 73 70 65 63 69 61 6c 0a 63 6f 6e 73  the special.cons
7de0: 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52 41  tant [SQLITE_TRA
7df0: 4e 53 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75  NSIENT], the rou
7e00: 74 69 6e 65 20 6d 61 6b 65 73 20 61 0a 70 72 69  tine makes a.pri
7e10: 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
7e20: 20 76 61 6c 75 65 20 56 20 62 65 66 6f 72 65 20   value V before 
7e30: 69 74 20 72 65 74 75 72 6e 73 2e 0a 0a 48 4c 52  it returns...HLR
7e40: 20 48 31 33 35 34 35 20 53 37 30 33 30 30 0a 49   H13545 S70300.I
7e50: 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
7e60: 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c  te3_bind_blob(S,
7e70: 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 5b 73 71 6c 69  N,V,L,D)],.[sqli
7e80: 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
7e90: 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 5b 73  N,V,L,D)], or.[s
7ea0: 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
7eb0: 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77  16(S,N,V,L,D)] w
7ec0: 68 65 6e 20 44 20 69 73 20 61 20 70 6f 69 6e 74  hen D is a point
7ed0: 65 72 20 74 6f 0a 61 20 66 75 6e 63 74 69 6f 6e  er to.a function
7ee0: 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  , SQLite invokes
7ef0: 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 74   that function t
7f00: 6f 20 64 65 73 74 72 6f 79 20 74 68 65 0a 76 61  o destroy the.va
7f10: 6c 75 65 20 56 20 61 66 74 65 72 20 69 74 20 68  lue V after it h
7f20: 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
7f30: 67 20 74 68 65 20 76 61 6c 75 65 20 56 2e 0a 0a  g the value V...
7f40: 48 4c 52 20 48 31 33 35 34 38 20 53 37 30 33 30  HLR H13548 S7030
7f50: 30 0a 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  0.In calls to [s
7f60: 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
7f70: 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74  blob(S,N,V,L)] t
7f80: 68 65 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 69  he value bound.i
7f90: 73 20 61 20 42 4c 4f 42 20 6f 66 20 4c 20 62 79  s a BLOB of L by
7fa0: 74 65 73 2c 20 6f 72 20 61 20 7a 65 72 6f 2d 6c  tes, or a zero-l
7fb0: 65 6e 67 74 68 20 42 4c 4f 42 20 69 66 20 4c 20  ength BLOB if L 
7fc0: 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 0a 48 4c  is negative...HL
7fd0: 52 20 48 31 33 35 35 31 20 53 37 30 33 30 30 0a  R H13551 S70300.
7fe0: 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
7ff0: 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
8000: 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20 61 72  S,N,V)] the V ar
8010: 67 75 6d 65 6e 74 20 6d 61 79 0a 62 65 20 65 69  gument may.be ei
8020: 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63 74 65  ther a [protecte
8030: 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
8040: 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a 5b 75   object or an.[u
8050: 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
8060: 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
8070: 2e 0a 0a 48 4c 52 20 48 31 33 36 30 31 20 53 37  ...HLR H13601 S7
8080: 30 33 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65  0300.The [sqlite
8090: 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
80a0: 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72  _count(S)] inter
80b0: 66 61 63 65 20 72 65 74 75 72 6e 73 0a 74 68 65  face returns.the
80c0: 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f   largest index o
80d0: 66 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65  f all SQL parame
80e0: 74 65 72 73 20 69 6e 20 74 68 65 0a 5b 70 72 65  ters in the.[pre
80f0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
8100: 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20 63 6f   S, or 0 if S co
8110: 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61  ntains no SQL pa
8120: 72 61 6d 65 74 65 72 73 2e 0a 0a 48 4c 52 20 48  rameters...HLR H
8130: 31 33 36 32 31 20 53 37 30 33 30 30 0a 54 68 65  13621 S70300.The
8140: 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
8150: 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c  arameter_name(S,
8160: 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
8170: 74 75 72 6e 73 0a 61 20 55 54 46 2d 38 20 72 65  turns.a UTF-8 re
8180: 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e  ndering of the n
8190: 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70  ame of the SQL p
81a0: 61 72 61 6d 65 74 65 72 20 69 6e 0a 74 68 65 20  arameter in.the 
81b0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
81c0: 65 6e 74 5d 20 53 20 68 61 76 69 6e 67 20 69 6e  ent] S having in
81d0: 64 65 78 20 4e 2c 20 6f 72 0a 4e 55 4c 4c 20 69  dex N, or.NULL i
81e0: 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51  f there is no SQ
81f0: 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68  L parameter with
8200: 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74   index N or if t
8210: 68 65 0a 70 61 72 61 6d 65 74 65 72 20 77 69 74  he.parameter wit
8220: 68 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e 20  h index N is an 
8230: 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
8240: 74 65 72 20 22 3f 22 2e 0a 0a 48 4c 52 20 48 31  ter "?"...HLR H1
8250: 33 36 34 31 20 53 37 30 33 30 30 0a 54 68 65 20  3641 S70300.The 
8260: 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
8270: 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53 2c  rameter_index(S,
8280: 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
8290: 74 75 72 6e 73 0a 74 68 65 20 69 6e 64 65 78 20  turns.the index 
82a0: 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  of SQL parameter
82b0: 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
82c0: 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 53 20 77  d statement].S w
82d0: 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74 63 68 65  hose name matche
82e0: 73 20 74 68 65 20 55 54 46 2d 38 20 73 74 72 69  s the UTF-8 stri
82f0: 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66 20 74 68  ng N, or 0 if th
8300: 65 72 65 20 69 73 0a 6e 6f 20 6d 61 74 63 68 2e  ere is.no match.
8310: 0a 0a 48 4c 52 20 48 31 33 36 36 31 20 53 37 30  ..HLR H13661 S70
8320: 33 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65 33  300.The [sqlite3
8330: 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
8340: 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
8350: 73 65 74 73 20 61 6c 6c 20 53 51 4c 0a 70 61 72  sets all SQL.par
8360: 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 73 20  ameter bindings 
8370: 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
8380: 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 62 61   statement] S ba
8390: 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 0a 48 4c 52  ck to NULL...HLR
83a0: 20 48 31 33 37 31 31 20 53 31 30 37 30 30 0a 54   H13711 S10700.T
83b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
83c0: 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74  mn_count(S)] int
83d0: 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
83e0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 63 6f 6c  he number of.col
83f0: 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
8400: 6c 74 20 73 65 74 20 67 65 6e 65 72 61 74 65 64  lt set generated
8410: 20 62 79 20 74 68 65 20 5b 70 72 65 70 61 72 65   by the [prepare
8420: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a  d statement] S,.
8430: 6f 72 20 30 20 69 66 20 53 20 64 6f 65 73 20 6e  or 0 if S does n
8440: 6f 74 20 67 65 6e 65 72 61 74 65 20 61 20 72 65  ot generate a re
8450: 73 75 6c 74 20 73 65 74 2e 0a 0a 48 4c 52 20 48  sult set...HLR H
8460: 31 33 37 32 31 20 53 31 30 37 30 30 0a 41 20 73  13721 S10700.A s
8470: 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
8480: 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
8490: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
84a0: 28 53 2c 4e 29 5d 0a 69 6e 74 65 72 66 61 63 65  (S,N)].interface
84b0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d   returns the nam
84c0: 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  e of the Nth col
84d0: 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 0a  umn (where 0 is.
84e0: 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  the leftmost col
84f0: 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 65 73  umn) for the res
8500: 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 0a 5b  ult set of the.[
8510: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
8520: 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d  nt] S as a zero-
8530: 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
8540: 20 73 74 72 69 6e 67 2e 0a 0a 48 4c 52 20 48 31   string...HLR H1
8550: 33 37 32 33 20 53 31 30 37 30 30 0a 41 20 73 75  3723 S10700.A su
8560: 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
8570: 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
8580: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
8590: 36 28 53 2c 4e 29 5d 0a 69 6e 74 65 72 66 61 63  6(S,N)].interfac
85a0: 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61  e returns the na
85b0: 6d 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f  me of the Nth co
85c0: 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73  lumn (where 0 is
85d0: 0a 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  .the leftmost co
85e0: 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 65  lumn) for the re
85f0: 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 0a  sult set of the.
8600: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
8610: 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f  ent] S as a zero
8620: 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
8630: 31 36 20 73 74 72 69 6e 67 0a 69 6e 20 74 68 65  16 string.in the
8640: 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
8650: 65 72 2e 0a 0a 48 4c 52 20 48 31 33 37 32 34 20  er...HLR H13724 
8660: 53 31 30 37 30 30 0a 54 68 65 20 5b 73 71 6c 69  S10700.The [sqli
8670: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
8680: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
8690: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d  column_name16()]
86a0: 0a 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75  .interfaces retu
86b0: 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  rn a NULL pointe
86c0: 72 20 69 66 20 74 68 65 79 20 61 72 65 20 75 6e  r if they are un
86d0: 61 62 6c 65 20 74 6f 0a 61 6c 6c 6f 63 61 74 65  able to.allocate
86e0: 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
86f0: 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74  their normal ret
8700: 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 0a 48 4c  urn strings...HL
8710: 52 20 48 31 33 37 32 35 20 53 31 30 37 30 30 0a  R H13725 S10700.
8720: 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  If the N paramet
8730: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
8740: 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d  olumn_name(S,N)]
8750: 20 6f 72 0a 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   or.[sqlite3_col
8760: 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  umn_name16(S,N)]
8770: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
8780: 2c 20 74 68 65 6e 20 74 68 65 0a 69 6e 74 65 72  , then the.inter
8790: 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e  faces return a N
87a0: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 0a 48 4c  ULL pointer...HL
87b0: 52 20 48 31 33 37 32 36 20 53 31 30 37 30 30 0a  R H13726 S10700.
87c0: 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
87d0: 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
87e0: 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e  _column_name(S,N
87f0: 29 5d 20 61 6e 64 0a 5b 73 71 6c 69 74 65 33 5f  )] and.[sqlite3_
8800: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
8810: 4e 29 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e  N)] are valid un
8820: 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 63 61 6c  til the next.cal
8830: 6c 20 74 6f 20 65 69 74 68 65 72 20 72 6f 75 74  l to either rout
8840: 69 6e 65 20 77 69 74 68 20 74 68 65 20 73 61 6d  ine with the sam
8850: 65 20 53 20 61 6e 64 20 4e 20 70 61 72 61 6d 65  e S and N parame
8860: 74 65 72 73 0a 6f 72 20 75 6e 74 69 6c 20 5b 73  ters.or until [s
8870: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
8880: 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 0a  S)] is called...
8890: 48 4c 52 20 48 31 33 37 32 37 20 53 31 30 37 30  HLR H13727 S1070
88a0: 30 0a 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20  0.When a result 
88b0: 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c  column of a [SEL
88c0: 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63  ECT] statement c
88d0: 6f 6e 74 61 69 6e 73 0a 61 6e 20 41 53 20 63 6c  ontains.an AS cl
88e0: 61 75 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f  ause, the name o
88f0: 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  f that column is
8900: 20 74 68 65 20 69 64 65 6e 74 69 66 69 65 72 0a   the identifier.
8910: 74 6f 20 74 68 65 20 72 69 67 68 74 20 6f 66 20  to the right of 
8920: 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 2e 0a  the AS keyword..
8930: 0a 48 4c 52 20 48 31 33 37 34 31 20 53 31 30 37  .HLR H13741 S107
8940: 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  00.The [sqlite3_
8950: 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
8960: 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  name(S,N)] inter
8970: 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
8980: 68 65 72 0a 74 68 65 20 55 54 46 2d 38 20 7a 65  her.the UTF-8 ze
8990: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
89a0: 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
89b0: 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  se from which th
89c0: 65 0a 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e.Nth result col
89d0: 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70  umn of the [prep
89e0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
89f0: 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a  S is extracted,.
8a00: 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
8a10: 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
8a20: 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72  s a general expr
8a30: 65 73 73 69 6f 6e 0a 6f 72 20 69 66 20 75 6e 61  ession.or if una
8a40: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
8a50: 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
8a60: 74 68 65 20 6e 61 6d 65 2e 0a 0a 48 4c 52 20 48  the name...HLR H
8a70: 31 33 37 34 32 20 53 31 30 37 30 30 0a 54 68 65  13742 S10700.The
8a80: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
8a90: 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
8aa0: 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
8ab0: 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
8ac0: 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
8ad0: 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72  e byte order zer
8ae0: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
8af0: 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
8b00: 65 0a 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  e.from which the
8b10: 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
8b20: 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61  mn of the [prepa
8b30: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
8b40: 20 69 73 0a 65 78 74 72 61 63 74 65 64 2c 20 6f   is.extracted, o
8b50: 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
8b60: 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
8b70: 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65   a general expre
8b80: 73 73 69 6f 6e 0a 6f 72 20 69 66 20 75 6e 61 62  ssion.or if unab
8b90: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
8ba0: 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74  emory to store t
8bb0: 68 65 20 6e 61 6d 65 2e 0a 0a 48 4c 52 20 48 31  he name...HLR H1
8bc0: 33 37 34 33 20 53 31 30 37 30 30 0a 54 68 65 20  3743 S10700.The 
8bd0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
8be0: 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d  table_name(S,N)]
8bf0: 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
8c00: 6e 73 20 65 69 74 68 65 72 0a 74 68 65 20 55 54  ns either.the UT
8c10: 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
8c20: 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
8c30: 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68  table from which
8c40: 20 74 68 65 0a 4e 74 68 20 72 65 73 75 6c 74 20   the.Nth result 
8c50: 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70  column of the [p
8c60: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
8c70: 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65  t] S is extracte
8c80: 64 2c 0a 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d,.or NULL if th
8c90: 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
8ca0: 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65  S is a general e
8cb0: 78 70 72 65 73 73 69 6f 6e 0a 6f 72 20 69 66 20  xpression.or if 
8cc0: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
8cd0: 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f  te memory to sto
8ce0: 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 0a 48 4c  re the name...HL
8cf0: 52 20 48 31 33 37 34 34 20 53 31 30 37 30 30 0a  R H13744 S10700.
8d00: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
8d10: 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
8d20: 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
8d30: 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
8d40: 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
8d50: 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72  e byte order zer
8d60: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
8d70: 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 66  e of the table.f
8d80: 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74  rom which the Nt
8d90: 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
8da0: 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  of the [prepared
8db0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
8dc0: 0a 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e  .extracted, or N
8dd0: 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
8de0: 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20  olumn of S is a 
8df0: 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
8e00: 6f 6e 0a 6f 72 20 69 66 20 75 6e 61 62 6c 65 20  on.or if unable 
8e10: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
8e20: 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20  ry to store the 
8e30: 6e 61 6d 65 2e 0a 0a 48 4c 52 20 48 31 33 37 34  name...HLR H1374
8e40: 35 20 53 31 30 37 30 30 0a 54 68 65 20 5b 73 71  5 S10700.The [sq
8e50: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
8e60: 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69  gin_name(S,N)] i
8e70: 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
8e80: 20 65 69 74 68 65 72 0a 74 68 65 20 55 54 46 2d   either.the UTF-
8e90: 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
8ea0: 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
8eb0: 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20  ble column from 
8ec0: 77 68 69 63 68 20 74 68 65 0a 4e 74 68 20 72 65  which the.Nth re
8ed0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
8ee0: 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
8ef0: 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74  tement] S is ext
8f00: 72 61 63 74 65 64 2c 0a 6f 72 20 4e 55 4c 4c 20  racted,.or NULL 
8f10: 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
8f20: 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65  n of S is a gene
8f30: 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 6f  ral expression.o
8f40: 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
8f50: 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
8f60: 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
8f70: 2e 0a 0a 48 4c 52 20 48 31 33 37 34 36 20 53 31  ...HLR H13746 S1
8f80: 30 37 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65  0700.The [sqlite
8f90: 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
8fa0: 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74  name16(S,N)] int
8fb0: 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
8fc0: 69 74 68 65 72 0a 74 68 65 20 55 54 46 2d 31 36  ither.the UTF-16
8fd0: 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
8fe0: 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  er zero-terminat
8ff0: 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
9000: 61 62 6c 65 0a 63 6f 6c 75 6d 6e 20 66 72 6f 6d  able.column from
9010: 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72   which the Nth r
9020: 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
9030: 74 68 65 0a 5b 70 72 65 70 61 72 65 64 20 73 74  the.[prepared st
9040: 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78  atement] S is ex
9050: 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
9060: 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
9070: 6d 6e 0a 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn.of S is a gen
9080: 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20  eral expression 
9090: 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
90a0: 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a  allocate memory.
90b0: 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d  to store the nam
90c0: 65 2e 0a 0a 48 4c 52 20 48 31 33 37 34 38 20 53  e...HLR H13748 S
90d0: 31 30 37 30 30 0a 54 68 65 20 72 65 74 75 72 6e  10700.The return
90e0: 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a 5b 73 71   values from.[sq
90f0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
9100: 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
9110: 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
9120: 65 72 66 61 63 65 73 5d 0a 61 72 65 20 76 61 6c  erfaces].are val
9130: 69 64 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74  id for the lifet
9140: 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70  ime of the [prep
9150: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
9160: 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63  or until the enc
9170: 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64  oding is changed
9180: 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61   by another meta
9190: 64 61 74 61 0a 69 6e 74 65 72 66 61 63 65 20 63  data.interface c
91a0: 61 6c 6c 20 66 6f 72 20 74 68 65 20 73 61 6d 65  all for the same
91b0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
91c0: 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  ent and column..
91d0: 0a 48 4c 52 20 48 31 33 37 36 31 20 53 31 30 37  .HLR H13761 S107
91e0: 30 30 0a 41 20 73 75 63 63 65 73 73 66 75 6c 20  00.A successful 
91f0: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
9200: 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
9210: 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61  (S,N)] returns a
9220: 0a 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64  .zero-terminated
9230: 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f   UTF-8 string co
9240: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63  ntaining the dec
9250: 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 0a 6f  lared datatype.o
9260: 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
9270: 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 20  mn that appears 
9280: 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  as the Nth colum
9290: 6e 20 28 6e 75 6d 62 65 72 65 64 0a 66 72 6f 6d  n (numbered.from
92a0: 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c   0) of the resul
92b0: 74 20 73 65 74 20 74 6f 20 74 68 65 20 5b 70 72  t set to the [pr
92c0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
92d0: 5d 20 53 2e 0a 0a 48 4c 52 20 48 31 33 37 36 32  ] S...HLR H13762
92e0: 20 53 31 30 37 30 30 0a 41 20 73 75 63 63 65 73   S10700.A succes
92f0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
9300: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
9310: 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a 72 65  ltype16(S,N)].re
9320: 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72  turns a zero-ter
9330: 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e  minated UTF-16 n
9340: 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
9350: 20 73 74 72 69 6e 67 0a 63 6f 6e 74 61 69 6e 69   string.containi
9360: 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  ng the declared 
9370: 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20  datatype of the 
9380: 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
9390: 74 20 61 70 70 65 61 72 73 0a 61 73 20 74 68 65  t appears.as the
93a0: 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d   Nth column (num
93b0: 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20 6f 66  bered from 0) of
93c0: 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
93d0: 74 6f 20 74 68 65 0a 5b 70 72 65 70 61 72 65 64  to the.[prepared
93e0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 0a   statement] S...
93f0: 48 4c 52 20 48 31 33 37 36 33 20 53 31 30 37 30  HLR H13763 S1070
9400: 30 0a 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74  0.If N is less t
9410: 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 20 67 72  han 0 or N is gr
9420: 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71  eater than or eq
9430: 75 61 6c 20 74 6f 0a 74 68 65 20 6e 75 6d 62 65  ual to.the numbe
9440: 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
9450: 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
9460: 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 6f 72 20 69  atement] S,.or i
9470: 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
9480: 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70 72   of S is an expr
9490: 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
94a0: 72 79 20 72 61 74 68 65 72 0a 74 68 61 6e 20 61  ry rather.than a
94b0: 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 2c 20 6f   table column, o
94c0: 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r if a memory al
94d0: 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
94e0: 0a 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 65  .occurs during e
94f0: 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73 69  ncoding conversi
9500: 6f 6e 73 2c 20 74 68 65 6e 0a 63 61 6c 6c 73 20  ons, then.calls 
9510: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
9520: 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29  mn_decltype(S,N)
9530: 5d 20 6f 72 0a 5b 73 71 6c 69 74 65 33 5f 63 6f  ] or.[sqlite3_co
9540: 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
9550: 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55 4c  S,N)] return NUL
9560: 4c 2e 0a 0a 48 4c 52 20 48 31 33 37 37 31 20 53  L...HLR H13771 S
9570: 31 30 37 30 30 0a 41 66 74 65 72 20 61 20 63 61  10700.After a ca
9580: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
9590: 74 65 70 28 53 29 5d 20 74 68 61 74 20 72 65 74  tep(S)] that ret
95a0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57  urns [SQLITE_ROW
95b0: 5d 2c 0a 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ],.the [sqlite3_
95c0: 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72  data_count(S)] r
95d0: 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75  outine will retu
95e0: 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  rn the same valu
95f0: 65 0a 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65  e.as the [sqlite
9600: 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53  3_column_count(S
9610: 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 0a 48 4c  )] function...HL
9620: 52 20 48 31 33 37 37 32 20 53 31 30 37 30 30 0a  R H13772 S10700.
9630: 41 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  After [sqlite3_s
9640: 74 65 70 28 53 29 5d 20 68 61 73 20 72 65 74 75  tep(S)] has retu
9650: 72 6e 65 64 20 61 6e 79 20 76 61 6c 75 65 20 6f  rned any value o
9660: 74 68 65 72 20 74 68 61 6e 0a 5b 53 51 4c 49 54  ther than.[SQLIT
9670: 45 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f 72 65  E_ROW] or before
9680: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
9690: 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
96a0: 65 64 20 6f 6e 20 74 68 65 0a 5b 70 72 65 70 61  ed on the.[prepa
96b0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 66  red statement] f
96c0: 6f 72 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  or the first tim
96d0: 65 20 73 69 6e 63 65 20 69 74 20 77 61 73 0a 5b  e since it was.[
96e0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
96f0: 7c 20 70 72 65 70 61 72 65 64 5d 20 6f 72 20 5b  | prepared] or [
9700: 73 71 6c 69 74 65 33 5f 72 65 73 65 74 20 7c 20  sqlite3_reset | 
9710: 72 65 73 65 74 5d 2c 0a 74 68 65 20 5b 73 71 6c  reset],.the [sql
9720: 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
9730: 53 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  S)] routine retu
9740: 72 6e 73 20 7a 65 72 6f 2e 0a 0a 48 4c 52 20 48  rns zero...HLR H
9750: 31 33 38 30 33 20 53 31 30 37 30 30 0a 54 68 65  13803 S10700.The
9760: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
9770: 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65  _blob(S,N)] inte
9780: 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
9790: 68 65 0a 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e  he.Nth column in
97a0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
97b0: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
97c0: 65 74 20 66 6f 72 0a 74 68 65 20 5b 70 72 65 70  et for.the [prep
97d0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
97e0: 53 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e  S into a BLOB an
97f0: 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61  d then returns a
9800: 0a 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20  .pointer to the 
9810: 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e  converted value.
9820: 0a 0a 48 4c 52 20 48 31 33 38 30 36 20 53 31 30  ..HLR H13806 S10
9830: 37 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65 33  700.The [sqlite3
9840: 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c  _column_bytes(S,
9850: 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
9860: 74 75 72 6e 73 20 74 68 65 0a 6e 75 6d 62 65 72  turns the.number
9870: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
9880: 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
9890: 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
98a0: 65 0a 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e.zero terminato
98b0: 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
98c0: 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
98d0: 65 64 20 62 79 20 74 68 65 0a 6d 6f 73 74 20 72  ed by the.most r
98e0: 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
98f0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
9900: 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 5b 73 71 6c  ob(S,N)] or.[sql
9910: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
9920: 28 53 2c 4e 29 5d 2e 0a 0a 48 4c 52 20 48 31 33  (S,N)]...HLR H13
9930: 38 30 39 20 53 31 30 37 30 30 0a 54 68 65 20 5b  809 S10700.The [
9940: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
9950: 79 74 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74  ytes16(S,N)] int
9960: 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
9970: 68 65 0a 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he.number of byt
9980: 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
9990: 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74   (exclusive of t
99a0: 68 65 0a 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he.zero terminat
99b0: 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67  or on the string
99c0: 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ) that was retur
99d0: 6e 65 64 20 62 79 20 74 68 65 0a 6d 6f 73 74 20  ned by the.most 
99e0: 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
99f0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
9a00: 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 0a 48 4c  ext16(S,N)]...HL
9a10: 52 20 48 31 33 38 31 32 20 53 31 30 37 30 30 0a  R H13812 S10700.
9a20: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
9a30: 75 6d 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d  umn_double(S,N)]
9a40: 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
9a50: 72 74 73 20 74 68 65 0a 4e 74 68 20 63 6f 6c 75  rts the.Nth colu
9a60: 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
9a70: 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
9a80: 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a  ult set for the.
9a90: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
9aa0: 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c  ent] S into a fl
9ab0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
9ac0: 75 65 20 61 6e 64 0a 72 65 74 75 72 6e 73 20 61  ue and.returns a
9ad0: 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61   copy of that va
9ae0: 6c 75 65 2e 0a 0a 48 4c 52 20 48 31 33 38 31 35  lue...HLR H13815
9af0: 20 53 31 30 37 30 30 0a 54 68 65 20 5b 73 71 6c   S10700.The [sql
9b00: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
9b10: 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
9b20: 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 4e 74 68  converts the.Nth
9b30: 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
9b40: 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
9b50: 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
9b60: 20 74 68 65 0a 5b 70 72 65 70 61 72 65 64 20 73   the.[prepared s
9b70: 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
9b80: 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64   a 64-bit signed
9b90: 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 72 65 74   integer and.ret
9ba0: 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33  urns the lower 3
9bb0: 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69  2 bits of that i
9bc0: 6e 74 65 67 65 72 2e 0a 0a 48 4c 52 20 48 31 33  nteger...HLR H13
9bd0: 38 31 38 20 53 31 30 37 30 30 0a 54 68 65 20 5b  818 S10700.The [
9be0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
9bf0: 6e 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72  nt64(S,N)] inter
9c00: 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
9c10: 65 0a 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20  e.Nth column in 
9c20: 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
9c30: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
9c40: 74 20 66 6f 72 20 74 68 65 0a 5b 70 72 65 70 61  t for the.[prepa
9c50: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
9c60: 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73   into a 64-bit s
9c70: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
9c80: 64 0a 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  d.returns a copy
9c90: 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
9ca0: 2e 0a 0a 48 4c 52 20 48 31 33 38 32 31 20 53 31  ...HLR H13821 S1
9cb0: 30 37 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65  0700.The [sqlite
9cc0: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c  3_column_text(S,
9cd0: 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
9ce0: 6e 76 65 72 74 73 20 74 68 65 0a 4e 74 68 20 63  nverts the.Nth c
9cf0: 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
9d00: 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
9d10: 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 74  result set for.t
9d20: 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
9d30: 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
9d40: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
9d50: 20 55 54 46 2d 38 0a 73 74 72 69 6e 67 20 61 6e   UTF-8.string an
9d60: 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
9d70: 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
9d80: 6e 67 2e 0a 0a 48 4c 52 20 48 31 33 38 32 34 20  ng...HLR H13824 
9d90: 53 31 30 37 30 30 0a 54 68 65 20 5b 73 71 6c 69  S10700.The [sqli
9da0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
9db0: 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
9dc0: 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 4e  e converts the.N
9dd0: 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
9de0: 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
9df0: 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
9e00: 6f 72 20 74 68 65 0a 5b 70 72 65 70 61 72 65 64  or the.[prepared
9e10: 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
9e20: 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
9e30: 61 74 65 64 20 32 2d 62 79 74 65 0a 61 6c 69 67  ated 2-byte.alig
9e40: 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76  ned UTF-16 nativ
9e50: 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 74 72  e byte order str
9e60: 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
9e70: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
9e80: 74 20 73 74 72 69 6e 67 2e 0a 0a 48 4c 52 20 48  t string...HLR H
9e90: 31 33 38 32 37 20 53 31 30 37 30 30 0a 54 68 65  13827 S10700.The
9ea0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
9eb0: 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _type(S,N)] inte
9ec0: 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 6f 6e  rface returns.on
9ed0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  e of [SQLITE_NUL
9ee0: 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  L], [SQLITE_INTE
9ef0: 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c  GER], [SQLITE_FL
9f00: 4f 41 54 5d 2c 0a 5b 53 51 4c 49 54 45 5f 54 45  OAT],.[SQLITE_TE
9f10: 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  XT], or [SQLITE_
9f20: 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72  BLOB] as appropr
9f30: 69 61 74 65 20 66 6f 72 0a 74 68 65 20 4e 74 68  iate for.the Nth
9f40: 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
9f50: 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
9f60: 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
9f70: 0a 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73  .the [prepared s
9f80: 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 0a 48 4c  tatement] S...HL
9f90: 52 20 48 31 33 38 33 30 20 53 31 30 37 30 30 0a  R H13830 S10700.
9fa0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
9fb0: 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20  umn_value(S,N)] 
9fc0: 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
9fd0: 73 20 61 0a 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a.pointer to a
9fe0: 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
9ff0: 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
a000: 6a 65 63 74 20 66 6f 72 20 74 68 65 0a 4e 74 68  ject for the.Nth
a010: 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
a020: 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
a030: 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
a040: 0a 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73  .the [prepared s
a050: 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 0a 48 4c  tatement] S...HL
a060: 52 20 48 31 34 31 30 33 20 53 32 30 30 30 30 0a  R H14103 S20000.
a070: 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
a080: 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
a090: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 73 68  te3_config()] sh
a0a0: 61 6c 6c 20 72 65 74 75 72 6e 0a 5b 53 51 4c 49  all return.[SQLI
a0b0: 54 45 5f 4f 4b 5d 2e 0a 0a 48 4c 52 20 48 31 34  TE_OK]...HLR H14
a0c0: 31 30 36 20 53 32 30 30 30 30 0a 54 68 65 20 5b  106 S20000.The [
a0d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a0e0: 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  ] interface shal
a0f0: 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
a100: 5f 4d 49 53 55 53 45 5d 0a 69 66 20 69 74 20 69  _MISUSE].if it i
a110: 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 62 65 74  s invoked in bet
a120: 77 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  ween calls to [s
a130: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a140: 65 28 29 5d 20 61 6e 64 0a 5b 73 71 6c 69 74 65  e()] and.[sqlite
a150: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 0a  3_shutdown()]...
a160: 48 4c 52 20 48 31 34 31 32 30 20 53 32 30 30 30  HLR H14120 S2000
a170: 30 0a 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  0.A successful c
a180: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
a190: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
a1a0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
a1b0: 45 41 44 5d 29 0a 73 68 61 6c 6c 20 73 65 74 20  EAD]).shall set 
a1c0: 74 68 65 20 64 65 66 61 75 6c 74 20 5b 74 68 72  the default [thr
a1d0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
a1e0: 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 0a 0a  Single-thread...
a1f0: 48 4c 52 20 48 31 34 31 32 33 20 53 32 30 30 30  HLR H14123 S2000
a200: 30 0a 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  0.A successful c
a210: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
a220: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
a230: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
a240: 41 44 5d 29 0a 73 68 61 6c 6c 20 73 65 74 20 74  AD]).shall set t
a250: 68 65 20 64 65 66 61 75 6c 74 20 5b 74 68 72 65  he default [thre
a260: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d  ading mode] to M
a270: 75 6c 74 69 2d 74 68 72 65 61 64 2e 0a 0a 48 4c  ulti-thread...HL
a280: 52 20 48 31 34 31 32 36 20 53 32 30 30 30 30 0a  R H14126 S20000.
a290: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
a2a0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
a2b0: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
a2c0: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
a2d0: 29 0a 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20  ).shall set the 
a2e0: 64 65 66 61 75 6c 74 20 5b 74 68 72 65 61 64 69  default [threadi
a2f0: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
a300: 61 6c 69 7a 65 64 2e 0a 0a 48 4c 52 20 48 31 34  alized...HLR H14
a310: 31 32 39 20 53 32 30 30 30 30 0a 41 20 73 75 63  129 S20000.A suc
a320: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
a330: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
a340: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
a350: 4d 55 54 45 58 5d 2c 58 29 0a 77 68 65 72 65 20  MUTEX],X).where 
a360: 58 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  X is a pointer t
a370: 6f 20 61 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  o an initialized
a380: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
a390: 6d 65 74 68 6f 64 73 5d 0a 6f 62 6a 65 63 74 20  methods].object 
a3a0: 73 68 61 6c 6c 20 63 61 75 73 65 20 61 6c 6c 20  shall cause all 
a3b0: 73 75 62 73 65 71 75 65 6e 74 20 6d 75 74 65 78  subsequent mutex
a3c0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 70 65 72 66   operations perf
a3d0: 6f 72 6d 65 64 0a 62 79 20 53 51 4c 69 74 65 20  ormed.by SQLite 
a3e0: 74 6f 20 75 73 65 20 74 68 65 20 6d 75 74 65 78  to use the mutex
a3f0: 20 6d 65 74 68 6f 64 73 20 74 68 61 74 20 77 65   methods that we
a400: 72 65 20 70 72 65 73 65 6e 74 20 69 6e 20 58 0a  re present in X.
a410: 64 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c 20  during the call 
a420: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
a430: 69 67 28 29 5d 2e 0a 0a 48 4c 52 20 48 31 34 31  ig()]...HLR H141
a440: 33 32 20 53 32 30 30 30 30 0a 41 20 73 75 63 63  32 S20000.A succ
a450: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
a460: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
a470: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
a480: 45 54 4d 55 54 45 58 5d 2c 58 29 0a 77 68 65 72  ETMUTEX],X).wher
a490: 65 20 58 20 69 73 20 61 20 70 6f 69 6e 74 65 72  e X is a pointer
a4a0: 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
a4b0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 6f  mutex_methods] o
a4c0: 62 6a 65 63 74 0a 73 68 61 6c 6c 20 6f 76 65 72  bject.shall over
a4d0: 77 72 69 74 65 20 74 68 65 20 63 6f 6e 74 65 6e  write the conten
a4e0: 74 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 75  t of [sqlite3_mu
a4f0: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  tex_methods] obj
a500: 65 63 74 0a 77 69 74 68 20 74 68 65 20 6d 75 74  ect.with the mut
a510: 65 78 20 6d 65 74 68 6f 64 73 20 63 75 72 72 65  ex methods curre
a520: 6e 74 6c 79 20 69 6e 20 75 73 65 20 62 79 20 53  ntly in use by S
a530: 51 4c 69 74 65 2e 0a 0a 48 4c 52 20 48 31 34 31  QLite...HLR H141
a540: 33 35 20 53 32 30 30 30 30 0a 41 20 73 75 63 63  35 S20000.A succ
a550: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
a560: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
a570: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
a580: 41 4c 4c 4f 43 5d 2c 4d 29 0a 77 68 65 72 65 20  ALLOC],M).where 
a590: 4d 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  M is a pointer t
a5a0: 6f 20 61 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  o an initialized
a5b0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
a5c0: 74 68 6f 64 73 5d 0a 6f 62 6a 65 63 74 20 73 68  thods].object sh
a5d0: 61 6c 6c 20 63 61 75 73 65 20 61 6c 6c 20 73 75  all cause all su
a5e0: 62 73 65 71 75 65 6e 74 20 6d 65 6d 6f 72 79 20  bsequent memory 
a5f0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 70 65 72 61  allocation opera
a600: 74 69 6f 6e 73 0a 70 65 72 66 6f 72 6d 65 64 20  tions.performed 
a610: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  by SQLite to use
a620: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 74 68 61   the methods tha
a630: 74 20 77 65 72 65 20 70 72 65 73 65 6e 74 20 69  t were present i
a640: 6e 0a 4d 20 64 75 72 69 6e 67 20 74 68 65 20 63  n.M during the c
a650: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
a660: 63 6f 6e 66 69 67 28 29 5d 2e 0a 0a 48 4c 52 20  config()]...HLR 
a670: 48 31 34 31 33 38 20 53 32 30 30 30 30 0a 41 20  H14138 S20000.A 
a680: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
a690: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
a6a0: 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
a6b0: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2c 4d 29  IG_GETMALLOC],M)
a6c0: 0a 77 68 65 72 65 20 4d 20 69 73 20 61 20 70 6f  .where M is a po
a6d0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
a6e0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
a6f0: 5d 20 6f 62 6a 65 63 74 20 73 68 61 6c 6c 0a 6f  ] object shall.o
a700: 76 65 72 77 72 69 74 65 20 74 68 65 20 63 6f 6e  verwrite the con
a710: 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65 33  tent of [sqlite3
a720: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  _mem_methods] ob
a730: 6a 65 63 74 20 77 69 74 68 0a 74 68 65 20 6d 65  ject with.the me
a740: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
a750: 6d 65 74 68 6f 64 73 20 63 75 72 72 65 6e 74 6c  methods currentl
a760: 79 20 69 6e 20 75 73 65 20 62 79 0a 53 51 4c 69  y in use by.SQLi
a770: 74 65 2e 0a 0a 48 4c 52 20 48 31 34 31 34 31 20  te...HLR H14141 
a780: 53 32 30 30 30 30 0a 41 20 73 75 63 63 65 73 73  S20000.A success
a790: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
a7a0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
a7b0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
a7c0: 54 41 54 55 53 5d 2c 31 29 0a 73 68 61 6c 6c 20  TATUS],1).shall 
a7d0: 65 6e 61 62 6c 65 20 74 68 65 20 6d 65 6d 6f 72  enable the memor
a7e0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
a7f0: 74 75 73 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6c  tus collection l
a800: 6f 67 69 63 2e 0a 0a 48 4c 52 20 48 31 34 31 34  ogic...HLR H1414
a810: 34 20 53 32 30 30 30 30 0a 41 20 73 75 63 63 65  4 S20000.A succe
a820: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
a830: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
a840: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
a850: 4d 53 54 41 54 55 53 5d 2c 30 29 0a 73 68 61 6c  MSTATUS],0).shal
a860: 6c 20 64 69 73 61 62 6c 65 20 74 68 65 20 6d 65  l disable the me
a870: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
a880: 73 74 61 74 75 73 20 63 6f 6c 6c 65 63 74 69 6f  status collectio
a890: 6e 20 6c 6f 67 69 63 2e 0a 0a 48 4c 52 20 48 31  n logic...HLR H1
a8a0: 34 31 34 37 20 53 32 30 30 30 30 0a 54 68 65 20  4147 S20000.The 
a8b0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
a8c0: 6e 20 73 74 61 74 75 73 20 63 6f 6c 6c 65 63 74  n status collect
a8d0: 69 6f 6e 20 6c 6f 67 69 63 20 73 68 61 6c 6c 20  ion logic shall 
a8e0: 62 65 0a 65 6e 61 62 6c 65 64 20 62 79 20 64 65  be.enabled by de
a8f0: 66 61 75 6c 74 2e 0a 0a 48 4c 52 20 48 31 34 31  fault...HLR H141
a900: 35 30 20 53 32 30 30 30 30 0a 41 20 73 75 63 63  50 S20000.A succ
a910: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
a920: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
a930: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
a940: 43 52 41 54 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 77  CRATCH],S,Z,N).w
a950: 68 65 72 65 20 5a 20 61 6e 64 20 4e 20 61 72 65  here Z and N are
a960: 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 69 6e   non-negative in
a970: 74 65 67 65 72 73 20 61 6e 64 0a 53 20 69 73 20  tegers and.S is 
a980: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a990: 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
a9a0: 75 66 66 65 72 20 6e 6f 74 20 6c 65 73 73 20 74  uffer not less t
a9b0: 68 61 6e 0a 5a 2a 4e 20 62 79 74 65 73 20 69 6e  han.Z*N bytes in
a9c0: 20 73 69 7a 65 20 73 68 61 6c 6c 20 63 61 75 73   size shall caus
a9d0: 65 20 53 20 74 6f 20 62 65 20 75 73 65 64 20 62  e S to be used b
a9e0: 79 20 74 68 65 0a 5b 73 63 72 61 74 63 68 20 6d  y the.[scratch m
a9f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
aa00: 20 66 6f 72 20 61 73 20 6d 61 6e 79 20 61 73 20   for as many as 
aa10: 4e 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73 0a  N simulataneous.
aa20: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 65 61 63 68  allocations each
aa30: 20 6f 66 20 73 69 7a 65 20 5a 2e 0a 0a 48 4c 52   of size Z...HLR
aa40: 20 48 31 34 31 35 33 20 53 32 30 30 30 30 0a 41   H14153 S20000.A
aa50: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
aa60: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
aa70: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
aa80: 46 49 47 5f 53 43 52 41 54 43 48 5d 2c 53 2c 5a  FIG_SCRATCH],S,Z
aa90: 2c 4e 29 0a 77 68 65 72 65 20 53 20 69 73 20 61  ,N).where S is a
aaa0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73 68   NULL pointer sh
aab0: 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65 0a  all disable the.
aac0: 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20  [scratch memory 
aad0: 61 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 0a 48 4c 52  allocator]...HLR
aae0: 20 48 31 34 31 35 36 20 53 32 30 30 30 30 0a 41   H14156 S20000.A
aaf0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
ab00: 20 74 6f 0a 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to.[sqlite3_con
ab10: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
ab20: 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 53  FIG_PAGECACHE],S
ab30: 2c 5a 2c 4e 29 0a 77 68 65 72 65 20 5a 20 61 6e  ,Z,N).where Z an
ab40: 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e 65 67 61  d N are non-nega
ab50: 74 69 76 65 20 69 6e 74 65 67 65 72 73 20 61 6e  tive integers an
ab60: 64 0a 53 20 69 73 20 61 20 70 6f 69 6e 74 65 72  d.S is a pointer
ab70: 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d   to an aligned m
ab80: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74  emory buffer not
ab90: 20 6c 65 73 73 20 74 68 61 6e 0a 5a 2a 4e 20 62   less than.Z*N b
aba0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 73 68 61  ytes in size sha
abb0: 6c 6c 20 63 61 75 73 65 20 53 20 74 6f 20 62 65  ll cause S to be
abc0: 20 75 73 65 64 20 62 79 20 74 68 65 0a 5b 70 61   used by the.[pa
abd0: 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  gecache memory a
abe0: 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 61 73  llocator] for as
abf0: 20 6d 61 6e 79 20 61 73 20 4e 20 73 69 6d 75 6c   many as N simul
ac00: 61 74 61 6e 65 6f 75 73 0a 61 6c 6c 6f 63 61 74  ataneous.allocat
ac10: 69 6f 6e 73 20 65 61 63 68 20 6f 66 20 73 69 7a  ions each of siz
ac20: 65 20 5a 2e 0a 0a 48 4c 52 20 48 31 34 31 35 39  e Z...HLR H14159
ac30: 20 53 32 30 30 30 30 0a 41 20 73 75 63 63 65 73   S20000.A succes
ac40: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 0a 5b 73 71  sful call to.[sq
ac50: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
ac60: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
ac70: 45 43 41 43 48 45 5d 2c 53 2c 5a 2c 4e 29 0a 77  ECACHE],S,Z,N).w
ac80: 68 65 72 65 20 53 20 69 73 20 61 20 4e 55 4c 4c  here S is a NULL
ac90: 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 64   pointer shall d
aca0: 69 73 61 62 6c 65 20 74 68 65 0a 5b 70 61 67 65  isable the.[page
acb0: 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
acc0: 6f 63 61 74 6f 72 5d 2e 0a 0a 48 4c 52 20 48 31  ocator]...HLR H1
acd0: 34 31 36 32 20 53 32 30 30 30 30 0a 41 20 73 75  4162 S20000.A su
ace0: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
acf0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
ad00: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
ad10: 5f 48 45 41 50 5d 2c 48 2c 5a 2c 4e 29 0a 77 68  _HEAP],H,Z,N).wh
ad20: 65 72 65 20 5a 20 61 6e 64 20 4e 20 61 72 65 20  ere Z and N are 
ad30: 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 69 6e 74  non-negative int
ad40: 65 67 65 72 73 20 61 6e 64 0a 48 20 69 73 20 61  egers and.H is a
ad50: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
ad60: 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
ad70: 66 66 65 72 20 6e 6f 74 20 6c 65 73 73 20 74 68  ffer not less th
ad80: 61 6e 0a 5a 20 62 79 74 65 73 20 69 6e 20 73 69  an.Z bytes in si
ad90: 7a 65 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 20  ze shall enable 
ada0: 74 68 65 20 5b 6d 65 6d 73 79 73 35 5d 20 6d 65  the [memsys5] me
adb0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 0a 61  mory allocator.a
adc0: 6e 64 20 63 61 75 73 65 20 69 74 20 74 6f 20 75  nd cause it to u
add0: 73 65 20 62 75 66 66 65 72 20 53 20 61 73 20 69  se buffer S as i
ade0: 74 73 20 6d 65 6d 6f 72 79 20 73 6f 75 72 63 65  ts memory source
adf0: 20 61 6e 64 20 74 6f 20 75 73 65 0a 61 20 6d 69   and to use.a mi
ae00: 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
ae10: 20 73 69 7a 65 20 6f 66 20 4e 2e 0a 0a 48 4c 52   size of N...HLR
ae20: 20 48 31 34 31 36 35 20 53 32 30 30 30 30 0a 41   H14165 S20000.A
ae30: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
ae40: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
ae50: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
ae60: 46 49 47 5f 48 45 41 50 5d 2c 48 2c 5a 2c 4e 29  FIG_HEAP],H,Z,N)
ae70: 0a 77 68 65 72 65 20 48 20 69 73 20 61 20 4e 55  .where H is a NU
ae80: 4c 4c 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c  LL pointer shall
ae90: 20 64 69 73 61 62 6c 65 20 74 68 65 0a 5b 6d 65   disable the.[me
aea0: 6d 73 79 73 35 5d 20 6d 65 6d 6f 72 79 20 61 6c  msys5] memory al
aeb0: 6c 6f 63 61 74 6f 72 2e 0a 0a 48 4c 52 20 48 31  locator...HLR H1
aec0: 34 31 36 38 20 53 32 30 30 30 30 0a 41 20 73 75  4168 S20000.A su
aed0: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
aee0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
aef0: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
af00: 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 5a 2c 4e 29  _LOOKASIDE],Z,N)
af10: 0a 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65  .shall cause the
af20: 20 64 65 66 61 75 6c 74 20 5b 6c 6f 6f 6b 61 73   default [lookas
af30: 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
af40: 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
af50: 69 6f 6e 0a 66 6f 72 20 6e 65 77 20 5b 64 61 74  ion.for new [dat
af60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
af70: 73 5d 20 74 6f 20 62 65 20 4e 20 73 6c 6f 74 73  s] to be N slots
af80: 20 6f 66 20 5a 20 62 79 74 65 73 20 65 61 63 68   of Z bytes each
af90: 2e 0a 0a 48 4c 52 20 48 31 34 32 30 33 20 53 32  ...HLR H14203 S2
afa0: 30 30 30 30 0a 41 20 63 61 6c 6c 20 74 6f 20 5b  0000.A call to [
afb0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
afc0: 67 28 44 2c 56 2c 2e 2e 2e 29 5d 20 73 68 61 6c  g(D,V,...)] shal
afd0: 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
afe0: 5f 4f 4b 5d 0a 69 66 20 61 6e 64 20 6f 6e 6c 79  _OK].if and only
aff0: 20 69 66 20 74 68 65 20 63 61 6c 6c 20 69 73 20   if the call is 
b000: 73 75 63 63 65 73 73 66 75 6c 2e 0a 0a 48 4c 52  successful...HLR
b010: 20 48 31 34 32 30 36 20 53 32 30 30 30 30 0a 49   H14206 S20000.I
b020: 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 6c  f one or more sl
b030: 6f 74 73 20 6f 66 20 74 68 65 20 5b 6c 6f 6f 6b  ots of the [look
b040: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
b050: 6f 63 61 74 6f 72 5d 20 66 6f 72 0a 5b 64 61 74  ocator] for.[dat
b060: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
b070: 5d 20 44 20 61 72 65 20 69 6e 20 75 73 65 2c 20  ] D are in use, 
b080: 74 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 5b  then a call to.[
b090: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
b0a0: 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43  g](D,[SQLITE_DBC
b0b0: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
b0c0: 2c 2e 2e 2e 29 20 73 68 61 6c 6c 0a 66 61 69 6c  ,...) shall.fail
b0d0: 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45   with an [SQLITE
b0e0: 5f 42 55 53 59 5d 20 72 65 74 75 72 6e 20 63 6f  _BUSY] return co
b0f0: 64 65 2e 0a 0a 48 4c 52 20 48 31 34 32 30 39 20  de...HLR H14209 
b100: 53 32 30 30 30 30 0a 41 20 73 75 63 63 65 73 73  S20000.A success
b110: 66 75 6c 20 63 61 6c 6c 20 74 6f 0a 5b 73 71 6c  ful call to.[sql
b120: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 5d 28  ite3_db_config](
b130: 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  D,[SQLITE_DBCONF
b140: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 42 2c  IG_LOOKASIDE],B,
b150: 5a 2c 4e 29 20 77 68 65 72 65 0a 44 20 69 73 20  Z,N) where.D is 
b160: 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  an open [databas
b170: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
b180: 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 70 6f  d Z and N are po
b190: 73 69 74 69 76 65 0a 69 6e 74 65 67 65 72 73 20  sitive.integers 
b1a0: 61 6e 64 20 42 20 69 73 20 61 6e 20 61 6c 69 67  and B is an alig
b1b0: 6e 65 64 20 62 75 66 66 65 72 20 61 74 20 6c 65  ned buffer at le
b1c0: 61 73 74 20 5a 2a 4e 20 62 79 74 65 73 20 69 6e  ast Z*N bytes in
b1d0: 20 73 69 7a 65 0a 73 68 61 6c 6c 20 63 61 75 73   size.shall caus
b1e0: 65 20 74 68 65 20 5b 6c 6f 6f 6b 61 73 69 64 65  e the [lookaside
b1f0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
b200: 72 5d 20 66 6f 72 20 44 20 74 6f 20 75 73 65 20  r] for D to use 
b210: 62 75 66 66 65 72 20 42 0a 77 69 74 68 20 4e 20  buffer B.with N 
b220: 73 6c 6f 74 73 20 6f 66 20 5a 20 62 79 74 65 73  slots of Z bytes
b230: 20 65 61 63 68 2e 0a 0a 48 4c 52 20 48 31 34 32   each...HLR H142
b240: 31 32 20 53 32 30 30 30 30 0a 41 20 73 75 63 63  12 S20000.A succ
b250: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 0a 5b  essful call to.[
b260: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
b270: 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43  g](D,[SQLITE_DBC
b280: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
b290: 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 44 20  ,B,Z,N) where.D 
b2a0: 69 73 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61  is an open [data
b2b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
b2c0: 20 61 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65   and Z and N are
b2d0: 20 70 6f 73 69 74 69 76 65 0a 69 6e 74 65 67 65   positive.intege
b2e0: 72 73 20 61 6e 64 20 42 20 69 73 20 4e 55 4c 4c  rs and B is NULL
b2f0: 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 63   pointer shall c
b300: 61 75 73 65 20 74 68 65 0a 5b 6c 6f 6f 6b 61 73  ause the.[lookas
b310: 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
b320: 61 74 6f 72 5d 20 66 6f 72 20 44 20 74 6f 20 61  ator] for D to a
b330: 20 6f 62 74 61 69 6e 20 5a 2a 4e 20 62 79 74 65   obtain Z*N byte
b340: 20 62 75 66 66 65 72 0a 66 72 6f 6d 20 74 68 65   buffer.from the
b350: 20 70 72 69 6d 61 72 79 20 6d 65 6d 6f 72 79 20   primary memory 
b360: 61 6c 6c 6f 63 61 74 6f 72 20 61 6e 64 20 75 73  allocator and us
b370: 65 20 74 68 61 74 20 62 75 66 66 65 72 0a 77 69  e that buffer.wi
b380: 74 68 20 4e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  th N lookaside s
b390: 6c 6f 74 73 20 6f 66 20 5a 20 62 79 74 65 73 20  lots of Z bytes 
b3a0: 65 61 63 68 2e 0a 0a 48 4c 52 20 48 31 34 32 31  each...HLR H1421
b3b0: 35 20 53 32 30 30 30 30 0a 41 20 73 75 63 63 65  5 S20000.A succe
b3c0: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 0a 5b 73  ssful call to.[s
b3d0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
b3e0: 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ](D,[SQLITE_DBCO
b3f0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
b400: 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 44 20 69  B,Z,N) where.D i
b410: 73 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62  s an open [datab
b420: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
b430: 61 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20  and Z and N are 
b440: 7a 65 72 6f 20 73 68 61 6c 6c 0a 64 69 73 61 62  zero shall.disab
b450: 6c 65 20 74 68 65 20 5b 6c 6f 6f 6b 61 73 69 64  le the [lookasid
b460: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
b470: 6f 72 5d 20 66 6f 72 20 44 2e 0a 0a 48 4c 52 20  or] for D...HLR 
b480: 48 31 35 31 30 33 20 53 32 30 32 30 30 0a 54 68  H15103 S20200.Th
b490: 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
b4a0: 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72 66  _blob(V)] interf
b4b0: 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
b4c0: 0a 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  .[protected sqli
b4d0: 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
b4e0: 74 20 56 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20  t V into a BLOB 
b4f0: 61 6e 64 20 74 68 65 6e 0a 72 65 74 75 72 6e 73  and then.returns
b500: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
b510: 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75  e converted valu
b520: 65 2e 0a 0a 48 4c 52 20 48 31 35 31 30 36 20 53  e...HLR H15106 S
b530: 32 30 32 30 30 0a 54 68 65 20 5b 73 71 6c 69 74  20200.The [sqlit
b540: 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 56  e3_value_bytes(V
b550: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
b560: 75 72 6e 73 20 74 68 65 0a 6e 75 6d 62 65 72 20  urns the.number 
b570: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
b580: 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28  BLOB or string (
b590: 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
b5a0: 0a 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72  .zero terminator
b5b0: 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20   on the string) 
b5c0: 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
b5d0: 64 20 62 79 20 74 68 65 0a 6d 6f 73 74 20 72 65  d by the.most re
b5e0: 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
b5f0: 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
b600: 28 56 29 5d 20 6f 72 0a 5b 73 71 6c 69 74 65 33  (V)] or.[sqlite3
b610: 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 2e  _value_text(V)].
b620: 0a 0a 48 4c 52 20 48 31 35 31 30 39 20 53 32 30  ..HLR H15109 S20
b630: 32 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65 33  200.The [sqlite3
b640: 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 56  _value_bytes16(V
b650: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
b660: 75 72 6e 73 20 74 68 65 0a 6e 75 6d 62 65 72 20  urns the.number 
b670: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
b680: 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
b690: 65 20 6f 66 20 74 68 65 0a 7a 65 72 6f 20 74 65  e of the.zero te
b6a0: 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
b6b0: 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
b6c0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
b6d0: 0a 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c  .most recent cal
b6e0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61  l to [sqlite3_va
b6f0: 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 2c 0a  lue_text16(V)],.
b700: 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
b710: 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f 72 20  ext16be(V)], or 
b720: 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
b730: 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a 0a 48 4c  ext16le(V)]...HL
b740: 52 20 48 31 35 31 31 32 20 53 32 30 32 30 30 0a  R H15112 S20200.
b750: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
b760: 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69 6e  ue_double(V)] in
b770: 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
b780: 20 74 68 65 0a 5b 70 72 6f 74 65 63 74 65 64 20   the.[protected 
b790: 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
b7a0: 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 66  bject V into a f
b7b0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
b7c0: 6c 75 65 20 61 6e 64 0a 72 65 74 75 72 6e 73 20  lue and.returns 
b7d0: 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76  a copy of that v
b7e0: 61 6c 75 65 2e 0a 0a 48 4c 52 20 48 31 35 31 31  alue...HLR H1511
b7f0: 35 20 53 32 30 32 30 30 0a 54 68 65 20 5b 73 71  5 S20200.The [sq
b800: 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
b810: 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
b820: 6e 76 65 72 74 73 20 74 68 65 0a 5b 70 72 6f 74  nverts the.[prot
b830: 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
b840: 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
b850: 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
b860: 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 72  ed integer and.r
b870: 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72  eturns the lower
b880: 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74   32 bits of that
b890: 20 69 6e 74 65 67 65 72 2e 0a 0a 48 4c 52 20 48   integer...HLR H
b8a0: 31 35 31 31 38 20 53 32 30 32 30 30 0a 54 68 65  15118 S20200.The
b8b0: 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
b8c0: 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 65 72 66  int64(V)] interf
b8d0: 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
b8e0: 0a 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  .[protected sqli
b8f0: 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
b900: 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  t V into a 64-bi
b910: 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
b920: 20 61 6e 64 0a 72 65 74 75 72 6e 73 20 61 20 63   and.returns a c
b930: 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65  opy of that inte
b940: 67 65 72 2e 0a 0a 48 4c 52 20 48 31 35 31 32 31  ger...HLR H15121
b950: 20 53 32 30 32 30 30 0a 54 68 65 20 5b 73 71 6c   S20200.The [sql
b960: 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
b970: 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
b980: 6e 76 65 72 74 73 20 74 68 65 0a 5b 70 72 6f 74  nverts the.[prot
b990: 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
b9a0: 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
b9b0: 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
b9c0: 61 74 65 64 20 55 54 46 2d 38 0a 73 74 72 69 6e  ated UTF-8.strin
b9d0: 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
b9e0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
b9f0: 73 74 72 69 6e 67 2e 0a 0a 48 4c 52 20 48 31 35  string...HLR H15
ba00: 31 32 34 20 53 32 30 32 30 30 0a 54 68 65 20 5b  124 S20200.The [
ba10: 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
ba20: 78 74 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61  xt16(V)] interfa
ba30: 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
ba40: 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
ba50: 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
ba60: 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
ba70: 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65  erminated 2-byte
ba80: 0a 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20  .aligned UTF-16 
ba90: 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
baa0: 72 0a 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  r.string and ret
bab0: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
bac0: 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 0a  o that string...
bad0: 48 4c 52 20 48 31 35 31 32 37 20 53 32 30 32 30  HLR H15127 S2020
bae0: 30 0a 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  0.The [sqlite3_v
baf0: 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29  alue_text16be(V)
bb00: 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
bb10: 65 72 74 73 20 74 68 65 0a 5b 70 72 6f 74 65 63  erts the.[protec
bb20: 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
bb30: 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
bb40: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
bb50: 65 64 20 32 2d 62 79 74 65 0a 61 6c 69 67 6e 65  ed 2-byte.aligne
bb60: 64 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64  d UTF-16 big-end
bb70: 69 61 6e 0a 73 74 72 69 6e 67 20 61 6e 64 20 72  ian.string and r
bb80: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
bb90: 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
bba0: 0a 0a 48 4c 52 20 48 31 35 31 33 30 20 53 32 30  ..HLR H15130 S20
bbb0: 32 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65 33  200.The [sqlite3
bbc0: 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
bbd0: 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
bbe0: 6e 76 65 72 74 73 20 74 68 65 0a 5b 70 72 6f 74  nverts the.[prot
bbf0: 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
bc00: 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
bc10: 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
bc20: 61 74 65 64 20 32 2d 62 79 74 65 0a 61 6c 69 67  ated 2-byte.alig
bc30: 6e 65 64 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  ned UTF-16 littl
bc40: 65 2d 65 6e 64 69 61 6e 0a 73 74 72 69 6e 67 20  e-endian.string 
bc50: 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
bc60: 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
bc70: 72 69 6e 67 2e 0a 0a 48 4c 52 20 48 31 35 31 33  ring...HLR H1513
bc80: 33 20 53 32 30 32 30 30 0a 54 68 65 20 5b 73 71  3 S20200.The [sq
bc90: 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
bca0: 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (V)] interface r
bcb0: 65 74 75 72 6e 73 0a 6f 6e 65 20 6f 66 20 5b 53  eturns.one of [S
bcc0: 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51  QLITE_NULL], [SQ
bcd0: 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b  LITE_INTEGER], [
bce0: 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 5b  SQLITE_FLOAT],.[
bcf0: 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72  SQLITE_TEXT], or
bd00: 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61   [SQLITE_BLOB] a
bd10: 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
bd20: 72 0a 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  r.the [sqlite3_v
bd30: 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a  alue] object V..
bd40: 0a 48 4c 52 20 48 31 35 31 33 36 20 53 32 30 32  .HLR H15136 S202
bd50: 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  00.The [sqlite3_
bd60: 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
bd70: 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  pe(V)] interface
bd80: 20 63 6f 6e 76 65 72 74 73 0a 74 68 65 20 5b 70   converts.the [p
bd90: 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
bda0: 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
bdb0: 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e 20   into either an 
bdc0: 69 6e 74 65 67 65 72 20 6f 72 0a 61 20 66 6c 6f  integer or.a flo
bdd0: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
bde0: 65 20 69 66 20 69 74 20 63 61 6e 20 64 6f 20 73  e if it can do s
bdf0: 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  o without loss o
be00: 66 0a 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61  f.information, a
be10: 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f  nd returns one o
be20: 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c  f [SQLITE_NULL],
be30: 0a 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  .[SQLITE_INTEGER
be40: 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ], [SQLITE_FLOAT
be50: 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
be60: 2c 20 6f 72 0a 5b 53 51 4c 49 54 45 5f 42 4c 4f  , or.[SQLITE_BLO
be70: 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74  B] as appropriat
be80: 65 20 66 6f 72 20 74 68 65 0a 5b 70 72 6f 74 65  e for the.[prote
be90: 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
bea0: 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 61 66 74  ue] object V aft
beb0: 65 72 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  er the conversio
bec0: 6e 20 61 74 74 65 6d 70 74 2e 0a 0a 48 4c 52 20  n attempt...HLR 
bed0: 48 31 35 33 30 34 20 53 31 30 30 30 30 0a 57 68  H15304 S10000.Wh
bee0: 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  en a call to [sq
bef0: 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63  lite3_step(S)] c
bf00: 61 75 73 65 73 20 74 68 65 20 5b 70 72 65 70 61  auses the [prepa
bf10: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 53  red statement].S
bf20: 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c   to run to compl
bf30: 65 74 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63 74  etion, the funct
bf40: 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ion returns [SQL
bf50: 49 54 45 5f 44 4f 4e 45 5d 2e 0a 0a 48 4c 52 20  ITE_DONE]...HLR 
bf60: 48 31 35 33 30 36 20 53 31 30 30 30 30 0a 57 68  H15306 S10000.Wh
bf70: 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  en a call to [sq
bf80: 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 73  lite3_step(S)] s
bf90: 74 6f 70 73 20 62 65 63 61 75 73 65 20 69 74 20  tops because it 
bfa0: 69 73 20 72 65 61 64 79 20 74 6f 0a 72 65 74 75  is ready to.retu
bfb0: 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f  rn another row o
bfc0: 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
bfd0: 2c 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51  , it returns [SQ
bfe0: 4c 49 54 45 5f 52 4f 57 5d 2e 0a 0a 48 4c 52 20  LITE_ROW]...HLR 
bff0: 48 31 35 33 30 38 20 53 31 30 30 30 30 0a 49 66  H15308 S10000.If
c000: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
c010: 74 65 33 5f 73 74 65 70 28 53 29 5d 20 65 6e 63  te3_step(S)] enc
c020: 6f 75 6e 74 65 72 73 20 61 6e 0a 5b 73 71 6c 69  ounters an.[sqli
c030: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20  te3_interrupt | 
c040: 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20  interrupt] or a 
c050: 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c 0a  run-time error,.
c060: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  it returns an ap
c070: 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
c080: 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74  code that is not
c090: 20 6f 6e 65 20 6f 66 0a 5b 53 51 4c 49 54 45 5f   one of.[SQLITE_
c0a0: 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  OK], [SQLITE_ROW
c0b0: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  ], or [SQLITE_DO
c0c0: 4e 45 5d 2e 0a 0a 48 4c 52 20 48 31 35 33 31 30  NE]...HLR H15310
c0d0: 20 53 31 30 30 30 30 0a 49 66 20 61 6e 20 5b 73   S10000.If an [s
c0e0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
c0f0: 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72   | interrupt] or
c100: 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
c110: 72 0a 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r.occurs during 
c120: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
c130: 65 33 5f 73 74 65 70 28 53 29 5d 0a 66 6f 72 20  e3_step(S)].for 
c140: 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
c150: 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65 64  ement] S created
c160: 20 75 73 69 6e 67 0a 6c 65 67 61 63 79 20 69 6e   using.legacy in
c170: 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
c180: 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a  3_prepare()] or.
c190: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
c1a0: 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  16()], then the 
c1b0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
c1c0: 20 65 69 74 68 65 72 0a 5b 53 51 4c 49 54 45 5f   either.[SQLITE_
c1d0: 45 52 52 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERROR], [SQLITE_
c1e0: 42 55 53 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BUSY], or [SQLIT
c1f0: 45 5f 4d 49 53 55 53 45 5d 2e 0a 0a 48 4c 52 20  E_MISUSE]...HLR 
c200: 48 31 36 31 30 33 20 53 32 30 32 30 30 0a 54 68  H16103 S20200.Th
c210: 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
c220: 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58  e_function16(D,X
c230: 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
c240: 20 73 68 61 6c 6c 20 62 65 68 61 76 65 0a 61 73   shall behave.as
c250: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
c260: 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e  _function(D,X,..
c270: 2e 29 5d 20 69 6e 20 65 76 65 72 79 20 77 61 79  .)] in every way
c280: 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 0a   except that it.
c290: 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 58  interprets the X
c2a0: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 7a 65 72   argument as zer
c2b0: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
c2c0: 2d 31 36 0a 6e 61 74 69 76 65 20 62 79 74 65 20  -16.native byte 
c2d0: 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66  order instead of
c2e0: 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   as zero-termina
c2f0: 74 65 64 20 55 54 46 2d 38 2e 0a 0a 48 4c 52 20  ted UTF-8...HLR 
c300: 48 31 36 31 30 36 20 53 32 30 32 30 30 0a 41 20  H16106 S20200.A 
c310: 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
c320: 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 5b 73 71  ation of the.[sq
c330: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
c340: 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e  ction(D,X,N,E,..
c350: 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  .)] interface sh
c360: 61 6c 6c 20 72 65 67 69 73 74 65 72 0a 6f 72 20  all register.or 
c370: 72 65 70 6c 61 63 65 73 20 63 61 6c 6c 62 61 63  replaces callbac
c380: 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74  k functions in t
c390: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
c3a0: 6e 65 63 74 69 6f 6e 5d 20 44 0a 75 73 65 64 20  nection] D.used 
c3b0: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  to implement the
c3c0: 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61   SQL function na
c3d0: 6d 65 64 20 58 20 77 69 74 68 20 4e 20 70 61 72  med X with N par
c3e0: 61 6d 65 74 65 72 73 0a 61 6e 64 20 68 61 76 69  ameters.and havi
c3f0: 6e 67 20 61 20 70 72 65 66 65 72 72 65 64 20 74  ng a preferred t
c400: 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  ext encoding of 
c410: 45 2e 0a 0a 48 4c 52 20 48 31 36 31 30 39 20 53  E...HLR H16109 S
c420: 32 30 32 30 30 0a 41 20 73 75 63 63 65 73 73 66  20200.A successf
c430: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
c440: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
c450: 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
c460: 53 2c 4c 29 5d 0a 73 68 61 6c 6c 20 72 65 70 6c  S,L)].shall repl
c470: 61 63 65 20 74 68 65 20 50 2c 20 46 2c 20 53 2c  ace the P, F, S,
c480: 20 61 6e 64 20 4c 20 76 61 6c 75 65 73 20 66 72   and L values fr
c490: 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c  om any prior cal
c4a0: 6c 73 20 77 69 74 68 0a 74 68 65 20 73 61 6d 65  ls with.the same
c4b0: 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20   D, X, N, and E 
c4c0: 76 61 6c 75 65 73 2e 0a 0a 48 4c 52 20 48 31 36  values...HLR H16
c4d0: 31 31 32 20 53 32 30 32 30 30 0a 54 68 65 20 5b  112 S20200.The [
c4e0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
c4f0: 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29  unction(D,X,...)
c500: 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  ] interface shal
c510: 6c 20 66 61 69 6c 0a 69 66 20 74 68 65 20 53 51  l fail.if the SQ
c520: 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20  L function name 
c530: 58 20 69 73 0a 6c 6f 6e 67 65 72 20 74 68 61 6e  X is.longer than
c540: 20 32 35 35 20 62 79 74 65 73 20 65 78 63 6c 75   255 bytes exclu
c550: 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
c560: 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 0a 48 4c   terminator...HL
c570: 52 20 48 31 36 31 31 38 20 53 32 30 32 30 30 0a  R H16118 S20200.
c580: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
c590: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
c5a0: 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 69  ,N,E,P,F,S,L)] i
c5b0: 6e 74 65 72 66 61 63 65 0a 73 68 61 6c 6c 20 66  nterface.shall f
c5c0: 61 69 6c 20 75 6e 6c 65 73 73 20 65 69 74 68 65  ail unless eithe
c5d0: 72 20 46 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20  r F is NULL and 
c5e0: 53 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d  S and L are non-
c5f0: 4e 55 4c 4c 20 6f 72 0a 46 20 69 73 20 6e 6f 6e  NULL or.F is non
c600: 2d 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20  -NULL and S and 
c610: 4c 20 61 72 65 20 4e 55 4c 4c 2e 0a 0a 48 4c 52  L are NULL...HLR
c620: 20 48 31 36 31 32 31 20 53 32 30 32 30 30 0a 54   H16121 S20200.T
c630: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
c640: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e  te_function(D,..
c650: 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  .)] interface sh
c660: 61 6c 6c 20 66 61 69 6c 73 20 77 69 74 68 20 61  all fails with a
c670: 6e 0a 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20  n.error code of 
c680: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 66  [SQLITE_BUSY] if
c690: 20 74 68 65 72 65 20 65 78 69 73 74 20 5b 70 72   there exist [pr
c6a0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
c6b0: 73 5d 0a 61 73 73 6f 63 69 61 74 65 64 20 77 69  s].associated wi
c6c0: 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
c6d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
c6e0: 0a 48 4c 52 20 48 31 36 31 32 37 20 53 32 30 32  .HLR H16127 S202
c6f0: 30 30 0a 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e  00.When N is non
c700: 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 5b  -negative, the [
c710: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
c720: 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e  unction(D,X,N,..
c730: 2e 29 5d 0a 69 6e 74 65 72 66 61 63 65 20 73 68  .)].interface sh
c740: 61 6c 6c 20 72 65 67 69 73 74 65 72 20 63 61 6c  all register cal
c750: 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76  lbacks to be inv
c760: 6f 6b 65 64 20 66 6f 72 20 74 68 65 0a 53 51 4c  oked for the.SQL
c770: 20 66 75 6e 63 74 69 6f 6e 0a 6e 61 6d 65 64 20   function.named 
c780: 58 20 77 68 65 6e 20 74 68 65 20 6e 75 6d 62 65  X when the numbe
c790: 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
c7a0: 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
c7b0: 6f 6e 20 69 73 0a 65 78 61 63 74 6c 79 20 4e 2e  on is.exactly N.
c7c0: 0a 0a 48 4c 52 20 48 31 36 31 33 30 20 53 32 30  ..HLR H16130 S20
c7d0: 32 30 30 0a 57 68 65 6e 20 4e 20 69 73 20 2d 31  200.When N is -1
c7e0: 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  , the [sqlite3_c
c7f0: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
c800: 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 69 6e 74 65 72  ,X,N,...)].inter
c810: 66 61 63 65 20 73 68 61 6c 6c 20 72 65 67 69 73  face shall regis
c820: 74 65 72 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f  ter callbacks to
c830: 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   be invoked for 
c840: 74 68 65 20 53 51 4c 0a 66 75 6e 63 74 69 6f 6e  the SQL.function
c850: 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 61 6e   named X with an
c860: 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
c870: 6d 65 6e 74 73 2e 0a 0a 48 4c 52 20 48 31 36 31  ments...HLR H161
c880: 33 33 20 53 32 30 32 30 30 0a 57 68 65 6e 20 63  33 S20200.When c
c890: 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
c8a0: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
c8b0: 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 73 70 65  (D,X,N,...)].spe
c8c0: 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d  cify multiple im
c8d0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
c8e0: 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
c8f0: 6f 6e 20 58 0a 61 6e 64 20 77 68 65 6e 20 6f 6e  on X.and when on
c900: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
c910: 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68   has N>=0 and th
c920: 65 20 6f 74 68 65 72 20 68 61 73 20 4e 3d 28 2d  e other has N=(-
c930: 31 29 0a 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  1).the implement
c940: 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
c950: 2d 7a 65 72 6f 20 4e 20 73 68 61 6c 6c 20 62 65  -zero N shall be
c960: 20 70 72 65 66 65 72 72 65 64 2e 0a 0a 48 4c 52   preferred...HLR
c970: 20 48 31 36 31 33 36 20 53 32 30 32 30 30 0a 57   H16136 S20200.W
c980: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  hen calls to [sq
c990: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
c9a0: 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e  ction(D,X,N,E,..
c9b0: 2e 29 5d 0a 73 70 65 63 69 66 79 20 6d 75 6c 74  .)].specify mult
c9c0: 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
c9d0: 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
c9e0: 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68   function X with
c9f0: 0a 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72  .the same number
ca00: 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 4e 20   of arguments N 
ca10: 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
ca20: 6e 74 0a 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20  nt.encodings E, 
ca30: 74 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65  then the impleme
ca40: 6e 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20  ntation where E 
ca50: 6d 61 74 63 68 65 73 20 74 68 65 0a 64 61 74 61  matches the.data
ca60: 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 73 68  base encoding sh
ca70: 61 6c 6c 20 70 72 65 66 65 72 72 65 64 2e 0a 0a  all preferred...
ca80: 48 4c 52 20 48 31 36 31 33 39 20 53 32 30 32 30  HLR H16139 S2020
ca90: 30 0a 46 6f 72 20 61 6e 20 61 67 67 72 65 67 61  0.For an aggrega
caa0: 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
cab0: 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 5b 73  created using.[s
cac0: 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
cad0: 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
cae0: 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e  ,0,S,L)] the fin
caf0: 61 6c 69 7a 65 72 0a 66 75 6e 63 74 69 6f 6e 20  alizer.function 
cb00: 4c 20 73 68 61 6c 6c 20 61 6c 77 61 79 73 20 62  L shall always b
cb10: 65 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c  e invoked exactl
cb20: 79 20 6f 6e 63 65 20 69 66 20 74 68 65 0a 73 74  y once if the.st
cb30: 65 70 20 66 75 6e 63 74 69 6f 6e 20 53 20 69 73  ep function S is
cb40: 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
cb50: 6f 72 65 20 74 69 6d 65 73 2e 0a 0a 48 4c 52 20  ore times...HLR 
cb60: 48 31 36 31 34 32 20 53 32 30 32 30 30 0a 57 68  H16142 S20200.Wh
cb70: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
cb80: 73 20 65 69 74 68 65 72 20 74 68 65 20 78 46 75  s either the xFu
cb90: 6e 63 20 6f 72 20 78 53 74 65 70 20 66 75 6e 63  nc or xStep func
cba0: 74 69 6f 6e 20 6f 66 0a 61 6e 20 61 70 70 6c 69  tion of.an appli
cbb0: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
cbc0: 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
cbd0: 67 67 72 65 67 61 74 65 20 63 72 65 61 74 65 64  ggregate created
cbe0: 0a 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .by [sqlite3_cre
cbf0: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
cc00: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  or [sqlite3_crea
cc10: 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
cc20: 2c 0a 74 68 65 6e 20 74 68 65 20 61 72 72 61 79  ,.then the array
cc30: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
cc40: 75 65 5d 20 6f 62 6a 65 63 74 73 20 70 61 73 73  ue] objects pass
cc50: 65 64 20 61 73 20 74 68 65 0a 74 68 69 72 64 20  ed as the.third 
cc60: 70 61 72 61 6d 65 74 65 72 20 73 68 61 6c 6c 20  parameter shall 
cc70: 62 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  be [protected sq
cc80: 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
cc90: 65 63 74 73 2e 0a 0a 48 4c 52 20 48 31 36 32 31  ects...HLR H1621
cca0: 31 20 53 32 30 32 30 30 0a 54 68 65 20 66 69 72  1 S20200.The fir
ccb0: 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  st invocation of
ccc0: 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
ccd0: 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
cce0: 5d 20 66 6f 72 0a 61 20 70 61 72 74 69 63 75 6c  ] for.a particul
ccf0: 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61  ar instance of a
cd00: 6e 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  n aggregate func
cd10: 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74  tion (for a part
cd20: 69 63 75 6c 61 72 0a 63 6f 6e 74 65 78 74 20 43  icular.context C
cd30: 29 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  ) causes SQLite 
cd40: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20 62 79  to allocate N by
cd50: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 7a  tes of memory,.z
cd60: 65 72 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  ero that memory,
cd70: 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f   and return a po
cd80: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 61 6c 6c  inter to the all
cd90: 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79 2e 0a 0a  ocated memory...
cda0: 48 4c 52 20 48 31 36 32 31 33 20 53 32 30 32 30  HLR H16213 S2020
cdb0: 30 0a 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  0.If a memory al
cdc0: 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
cdd0: 63 63 75 72 73 20 64 75 72 69 6e 67 0a 5b 73 71  ccurs during.[sq
cde0: 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
cdf0: 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74 68  context(C,N)] th
ce00: 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
ce10: 72 65 74 75 72 6e 73 20 30 2e 0a 0a 48 4c 52 20  returns 0...HLR 
ce20: 48 31 36 32 31 35 20 53 32 30 32 30 30 0a 53 65  H16215 S20200.Se
ce30: 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
ce40: 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ent invocations 
ce50: 6f 66 0a 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  of.[sqlite3_aggr
ce60: 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
ce70: 4e 29 5d 20 66 6f 72 20 74 68 65 20 73 61 6d 65  N)] for the same
ce80: 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
ce90: 20 43 0a 69 67 6e 6f 72 65 20 74 68 65 20 4e 20   C.ignore the N 
cea0: 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
ceb0: 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  turn a pointer t
cec0: 6f 20 74 68 65 20 73 61 6d 65 0a 62 6c 6f 63 6b  o the same.block
ced0: 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75 72   of memory retur
cee0: 6e 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ned by the first
cef0: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 0a 48 4c   invocation...HL
cf00: 52 20 48 31 36 32 31 37 20 53 32 30 32 30 30 0a  R H16217 S20200.
cf10: 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
cf20: 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
cf30: 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
cf40: 78 74 28 43 2c 4e 29 5d 20 69 73 0a 61 75 74 6f  xt(C,N)] is.auto
cf50: 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20  matically freed 
cf60: 6f 6e 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  on the next call
cf70: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
cf80: 65 74 28 29 5d 0a 6f 72 20 5b 73 71 6c 69 74 65  et()].or [sqlite
cf90: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 66 6f  3_finalize()] fo
cfa0: 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
cfb0: 73 74 61 74 65 6d 65 6e 74 5d 20 63 6f 6e 74 61  statement] conta
cfc0: 69 6e 69 6e 67 0a 74 68 65 20 61 67 67 72 65 67  ining.the aggreg
cfd0: 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73 73  ate function ass
cfe0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 6f 6e  ociated with con
cff0: 74 65 78 74 20 43 2e 0a 0a 48 4c 52 20 48 31 36  text C...HLR H16
d000: 32 34 33 20 53 32 30 32 30 30 0a 54 68 65 20 5b  243 S20200.The [
d010: 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
d020: 61 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20  a(C)] interface 
d030: 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
d040: 66 20 74 68 65 0a 50 20 70 6f 69 6e 74 65 72 20  f the.P pointer 
d050: 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
d060: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
d070: 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  n(D,X,N,E,P,F,S,
d080: 4c 29 5d 0a 6f 72 20 5b 73 71 6c 69 74 65 33 5f  L)].or [sqlite3_
d090: 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
d0a0: 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  6(D,X,N,E,P,F,S,
d0b0: 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 72 65  L)] call that.re
d0c0: 67 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c  gistered the SQL
d0d0: 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69   function associ
d0e0: 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  ated with [sqlit
d0f0: 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 0a  e3_context] C...
d100: 48 4c 52 20 48 31 36 32 35 33 20 53 36 30 36 30  HLR H16253 S6060
d110: 30 0a 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  0.The [sqlite3_c
d120: 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
d130: 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (C)] interface r
d140: 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
d150: 20 74 68 65 0a 44 20 70 6f 69 6e 74 65 72 20 66   the.D pointer f
d160: 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
d170: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
d180: 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
d190: 29 5d 0a 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63  )].or [sqlite3_c
d1a0: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
d1b0: 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
d1c0: 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 72 65 67  )] call that.reg
d1d0: 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20  istered the SQL 
d1e0: 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61  function associa
d1f0: 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  ted with [sqlite
d200: 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 0a 48  3_context] C...H
d210: 4c 52 20 48 31 36 32 37 32 20 53 32 30 32 30 30  LR H16272 S20200
d220: 0a 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65  .The [sqlite3_ge
d230: 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d 20  t_auxdata(C,N)] 
d240: 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
d250: 73 20 61 20 70 6f 69 6e 74 65 72 0a 74 6f 20 6d  s a pointer.to m
d260: 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
d270: 65 64 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  ed with the Nth 
d280: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
d290: 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 77 68   SQL function.wh
d2a0: 6f 73 65 20 63 6f 6e 74 65 78 74 20 69 73 20 43  ose context is C
d2b0: 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
d2c0: 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74  re is no metadat
d2d0: 61 20 61 73 73 6f 63 69 61 74 65 64 0a 77 69 74  a associated.wit
d2e0: 68 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  h that parameter
d2f0: 2e 0a 0a 48 4c 52 20 48 31 36 32 37 34 20 53 32  ...HLR H16274 S2
d300: 30 32 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65  0200.The [sqlite
d310: 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
d320: 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  N,P,D)] interfac
d330: 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74 61  e assigns a meta
d340: 64 61 74 61 0a 70 6f 69 6e 74 65 72 20 50 20 74  data.pointer P t
d350: 6f 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65  o the Nth parame
d360: 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ter of the SQL f
d370: 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e  unction with con
d380: 74 65 78 74 20 43 2e 0a 0a 48 4c 52 20 48 31 36  text C...HLR H16
d390: 32 37 36 20 53 32 30 32 30 30 0a 53 51 4c 69 74  276 S20200.SQLit
d3a0: 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
d3b0: 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77  e destructor D w
d3c0: 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67  ith a single arg
d3d0: 75 6d 65 6e 74 0a 77 68 69 63 68 20 69 73 20 74  ument.which is t
d3e0: 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69 6e  he metadata poin
d3f0: 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20  ter P following 
d400: 61 20 63 61 6c 6c 20 74 6f 0a 5b 73 71 6c 69 74  a call to.[sqlit
d410: 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
d420: 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 51  ,N,P,D)] when SQ
d430: 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68  Lite ceases to h
d440: 6f 6c 64 0a 74 68 65 20 6d 65 74 61 64 61 74 61  old.the metadata
d450: 2e 0a 0a 48 4c 52 20 48 31 36 32 37 37 20 53 32  ...HLR H16277 S2
d460: 30 32 30 30 0a 53 51 4c 69 74 65 20 63 65 61 73  0200.SQLite ceas
d470: 65 73 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64  es to hold metad
d480: 61 74 61 20 66 6f 72 20 61 6e 20 53 51 4c 20 66  ata for an SQL f
d490: 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
d4a0: 72 0a 77 68 65 6e 20 74 68 65 20 76 61 6c 75 65  r.when the value
d4b0: 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65 74   of that paramet
d4c0: 65 72 20 63 68 61 6e 67 65 73 2e 0a 0a 48 4c 52  er changes...HLR
d4d0: 20 48 31 36 32 37 38 20 53 32 30 32 30 30 0a 57   H16278 S20200.W
d4e0: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  hen [sqlite3_set
d4f0: 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44  _auxdata(C,N,P,D
d500: 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  )] is invoked, t
d510: 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 69 73  he destructor.is
d520: 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20   called for any 
d530: 70 72 69 6f 72 20 6d 65 74 61 64 61 74 61 20 61  prior metadata a
d540: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
d550: 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
d560: 0a 63 6f 6e 74 65 78 74 20 43 20 61 6e 64 20 70  .context C and p
d570: 61 72 61 6d 65 74 65 72 20 4e 2e 0a 0a 48 4c 52  arameter N...HLR
d580: 20 48 31 36 32 37 39 20 53 32 30 32 30 30 0a 53   H16279 S20200.S
d590: 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20  QLite will call 
d5a0: 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20  destructors for 
d5b0: 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74 20  any metadata it 
d5c0: 69 73 20 68 6f 6c 64 69 6e 67 0a 69 6e 20 61 20  is holding.in a 
d5d0: 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65 70  particular [prep
d5e0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
d5f0: 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a 5b 73  S when either.[s
d600: 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
d610: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
d620: 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c  alize(S)] is cal
d630: 6c 65 64 2e 0a 0a 48 4c 52 20 48 31 36 33 35 31  led...HLR H16351
d640: 20 53 33 30 32 32 30 0a 54 68 65 20 5b 73 71 6c   S30220.The [sql
d650: 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
d660: 69 6d 69 74 28 4e 29 5d 20 69 6e 74 65 72 66 61  imit(N)] interfa
d670: 63 65 20 70 6c 61 63 65 73 20 61 20 73 6f 66 74  ce places a soft
d680: 20 6c 69 6d 69 74 0a 6f 66 20 4e 20 62 79 74 65   limit.of N byte
d690: 73 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  s on the amount 
d6a0: 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74  of heap memory t
d6b0: 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63  hat may be alloc
d6c0: 61 74 65 64 0a 75 73 69 6e 67 20 5b 73 71 6c 69  ated.using [sqli
d6d0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
d6e0: 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
d6f0: 63 28 29 5d 20 61 74 20 61 6e 79 20 70 6f 69 6e  c()] at any poin
d700: 74 0a 69 6e 20 74 69 6d 65 2e 0a 0a 48 4c 52 20  t.in time...HLR 
d710: 48 31 36 33 35 32 20 53 33 30 32 32 30 0a 49 66  H16352 S30220.If
d720: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
d730: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
d740: 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
d750: 63 28 29 5d 20 77 6f 75 6c 64 0a 63 61 75 73 65  c()] would.cause
d760: 20 74 68 65 20 74 6f 74 61 6c 20 61 6d 6f 75 6e   the total amoun
d770: 74 20 6f 66 20 61 6c 6c 6f 63 61 74 65 64 20 6d  t of allocated m
d780: 65 6d 6f 72 79 20 74 6f 20 65 78 63 65 65 64 20  emory to exceed 
d790: 74 68 65 0a 73 6f 66 74 20 68 65 61 70 20 6c 69  the.soft heap li
d7a0: 6d 69 74 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74  mit, then [sqlit
d7b0: 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
d7c0: 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a  y()] is invoked.
d7d0: 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f  in an attempt to
d7e0: 20 72 65 64 75 63 65 20 74 68 65 20 6d 65 6d 6f   reduce the memo
d7f0: 72 79 20 75 73 61 67 65 20 70 72 69 6f 72 20 74  ry usage prior t
d800: 6f 20 70 72 6f 63 65 65 64 69 6e 67 0a 77 69 74  o proceeding.wit
d810: 68 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  h the memory all
d820: 6f 63 61 74 69 6f 6e 20 61 74 74 65 6d 70 74 2e  ocation attempt.
d830: 0a 0a 48 4c 52 20 48 31 36 33 35 33 20 53 33 30  ..HLR H16353 S30
d840: 32 32 30 0a 43 61 6c 6c 73 20 74 6f 20 5b 73 71  220.Calls to [sq
d850: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
d860: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
d870: 6c 6f 63 28 29 5d 20 74 68 61 74 20 74 72 69 67  loc()] that trig
d880: 67 65 72 0a 61 74 74 65 6d 70 74 73 20 74 6f 20  ger.attempts to 
d890: 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75 73  reduce memory us
d8a0: 61 67 65 20 74 68 72 6f 75 67 68 20 74 68 65 20  age through the 
d8b0: 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a  soft heap limit.
d8c0: 6d 65 63 68 61 6e 69 73 6d 20 63 6f 6e 74 69 6e  mechanism contin
d8d0: 75 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 61  ue even if the a
d8e0: 74 74 65 6d 70 74 20 74 6f 20 72 65 64 75 63 65  ttempt to reduce
d8f0: 20 6d 65 6d 6f 72 79 0a 75 73 61 67 65 20 69 73   memory.usage is
d900: 20 75 6e 73 75 63 63 65 73 73 66 75 6c 2e 0a 0a   unsuccessful...
d910: 48 4c 52 20 48 31 36 33 35 34 20 53 33 30 32 32  HLR H16354 S3022
d920: 30 0a 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20  0.A negative or 
d930: 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e  zero value for N
d940: 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 5b 73   in a call to.[s
d950: 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
d960: 5f 6c 69 6d 69 74 28 4e 29 5d 20 6d 65 61 6e 73  _limit(N)] means
d970: 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e   that there is n
d980: 6f 20 73 6f 66 74 0a 68 65 61 70 20 6c 69 6d 69  o soft.heap limi
d990: 74 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  t and [sqlite3_r
d9a0: 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
d9b0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 0a 63 61   will only be.ca
d9c0: 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79  lled when memory
d9d0: 20 69 73 20 63 6f 6d 70 6c 65 74 65 6c 79 20 65   is completely e
d9e0: 78 68 61 75 73 74 65 64 2e 0a 0a 48 4c 52 20 48  xhausted...HLR H
d9f0: 31 36 33 35 35 20 53 33 30 32 32 30 0a 54 68 65  16355 S30220.The
da00: 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
da10: 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
da20: 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
da30: 0a 48 4c 52 20 48 31 36 33 35 38 20 53 33 30 32  .HLR H16358 S302
da40: 32 30 0a 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  20.Each call to 
da50: 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
da60: 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6f 76 65  ap_limit(N)] ove
da70: 72 72 69 64 65 73 20 74 68 65 0a 76 61 6c 75 65  rrides the.value
da80: 73 20 73 65 74 20 62 79 20 61 6c 6c 20 70 72 69  s set by all pri
da90: 6f 72 20 63 61 6c 6c 73 2e 0a 0a 48 4c 52 20 48  or calls...HLR H
daa0: 31 36 34 30 33 20 53 32 30 32 30 30 0a 54 68 65  16403 S20200.The
dab0: 20 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e 20   default return 
dac0: 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20 53  value from any S
dad0: 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e  QL function is N
dae0: 55 4c 4c 2e 0a 0a 48 4c 52 20 48 31 36 34 30 36  ULL...HLR H16406
daf0: 20 53 32 30 32 30 30 0a 54 68 65 20 5b 73 71 6c   S20200.The [sql
db00: 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
db10: 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
db20: 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
db30: 0a 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66  .return value of
db40: 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
db50: 65 20 61 20 42 4c 4f 42 20 74 68 61 74 20 69 73  e a BLOB that is
db60: 20 4e 20 62 79 74 65 73 0a 69 6e 20 6c 65 6e 67   N bytes.in leng
db70: 74 68 20 61 6e 64 20 77 69 74 68 20 63 6f 6e 74  th and with cont
db80: 65 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ent pointed to b
db90: 79 20 56 2e 0a 0a 48 4c 52 20 48 31 36 34 30 39  y V...HLR H16409
dba0: 20 53 32 30 32 30 30 0a 54 68 65 20 5b 73 71 6c   S20200.The [sql
dbb0: 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
dbc0: 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61  le(C,V)] interfa
dbd0: 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 72  ce changes the.r
dbe0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
dbf0: 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
dc00: 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
dc10: 6e 74 20 76 61 6c 75 65 20 56 2e 0a 0a 48 4c 52  nt value V...HLR
dc20: 20 48 31 36 34 31 32 20 53 32 30 32 30 30 0a 54   H16412 S20200.T
dc30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
dc40: 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d  lt_error(C,V,N)]
dc50: 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
dc60: 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 76 61  es the return.va
dc70: 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
dc80: 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
dc90: 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
dca0: 63 6f 64 65 0a 5b 53 51 4c 49 54 45 5f 45 52 52  code.[SQLITE_ERR
dcb0: 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 38 20  OR] and a UTF-8 
dcc0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f  error message co
dcd0: 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74  pied from V up t
dce0: 6f 20 74 68 65 0a 66 69 72 73 74 20 7a 65 72 6f  o the.first zero
dcf0: 20 62 79 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e   byte or until N
dd00: 20 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20   bytes are read 
dd10: 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  if N is positive
dd20: 2e 0a 0a 48 4c 52 20 48 31 36 34 31 35 20 53 32  ...HLR H16415 S2
dd30: 30 32 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65  0200.The [sqlite
dd40: 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
dd50: 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61  (C,V,N)] interfa
dd60: 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
dd70: 65 74 75 72 6e 0a 76 61 6c 75 65 20 6f 66 20 66  eturn.value of f
dd80: 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
dd90: 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
dda0: 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 5b 53 51  h error code.[SQ
ddb0: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20  LITE_ERROR] and 
ddc0: 61 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  a UTF-16 native 
ddd0: 62 79 74 65 20 6f 72 64 65 72 20 65 72 72 6f 72  byte order error
dde0: 20 6d 65 73 73 61 67 65 0a 63 6f 70 69 65 64 20   message.copied 
ddf0: 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65  from V up to the
de00: 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
de10: 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20  inator or until 
de20: 4e 20 62 79 74 65 73 0a 61 72 65 20 72 65 61 64  N bytes.are read
de30: 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
de40: 65 2e 0a 0a 48 4c 52 20 48 31 36 34 31 38 20 53  e...HLR H16418 S
de50: 32 30 32 30 30 0a 54 68 65 20 5b 73 71 6c 69 74  20200.The [sqlit
de60: 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
de70: 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74 65 72  toobig(C)] inter
de80: 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
de90: 20 72 65 74 75 72 6e 0a 76 61 6c 75 65 20 6f 66   return.value of
dea0: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20   the function C 
deb0: 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69  to be an excepti
dec0: 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f  on with error co
ded0: 64 65 0a 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49  de.[SQLITE_TOOBI
dee0: 47 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70  G] and an approp
def0: 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73  riate error mess
df00: 61 67 65 2e 0a 0a 48 4c 52 20 48 31 36 34 32 31  age...HLR H16421
df10: 20 53 32 30 32 30 30 0a 54 68 65 20 5b 73 71 6c   S20200.The [sql
df20: 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
df30: 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65  r_nomem(C)] inte
df40: 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
df50: 65 20 72 65 74 75 72 6e 0a 76 61 6c 75 65 20 6f  e return.value o
df60: 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43  f the function C
df70: 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
df80: 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
df90: 6f 64 65 0a 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  ode.[SQLITE_NOME
dfa0: 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70  M] and an approp
dfb0: 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73  riate error mess
dfc0: 61 67 65 2e 0a 0a 48 4c 52 20 48 31 36 34 32 34  age...HLR H16424
dfd0: 20 53 32 30 32 30 30 0a 54 68 65 20 5b 73 71 6c   S20200.The [sql
dfe0: 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
dff0: 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74  r_code(C,E)] int
e000: 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
e010: 68 65 20 72 65 74 75 72 6e 0a 76 61 6c 75 65 20  he return.value 
e020: 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
e030: 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
e040: 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
e050: 63 6f 64 65 20 45 2e 0a 54 68 65 20 65 72 72 6f  code E..The erro
e060: 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 69  r message text i
e070: 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 0a 48 4c  s unchanged...HL
e080: 52 20 48 31 36 34 32 37 20 53 32 30 32 30 30 0a  R H16427 S20200.
e090: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
e0a0: 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e  ult_int(C,V)] in
e0b0: 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
e0c0: 74 68 65 0a 72 65 74 75 72 6e 20 76 61 6c 75 65  the.return value
e0d0: 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
e0e0: 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
e0f0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e  integer value V.
e100: 0a 0a 48 4c 52 20 48 31 36 34 33 30 20 53 32 30  ..HLR H16430 S20
e110: 32 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65 33  200.The [sqlite3
e120: 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c  _result_int64(C,
e130: 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
e140: 61 6e 67 65 73 20 74 68 65 0a 72 65 74 75 72 6e  anges the.return
e150: 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
e160: 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 36  on C to be the 6
e170: 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 61  4-bit integer va
e180: 6c 75 65 20 56 2e 0a 0a 48 4c 52 20 48 31 36 34  lue V...HLR H164
e190: 33 33 20 53 32 30 32 30 30 0a 54 68 65 20 5b 73  33 S20200.The [s
e1a0: 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
e1b0: 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  ll(C)] interface
e1c0: 20 63 68 61 6e 67 65 73 20 74 68 65 0a 72 65 74   changes the.ret
e1d0: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
e1e0: 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55  ction C to be NU
e1f0: 4c 4c 2e 0a 0a 48 4c 52 20 48 31 36 34 33 36 20  LL...HLR H16436 
e200: 53 32 30 32 30 30 0a 54 68 65 20 5b 73 71 6c 69  S20200.The [sqli
e210: 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
e220: 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
e230: 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
e240: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
e250: 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
e260: 20 74 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e   the UTF-8 strin
e270: 67 0a 56 20 75 70 20 74 6f 20 74 68 65 20 66 69  g.V up to the fi
e280: 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73  rst zero if N is
e290: 20 6e 65 67 61 74 69 76 65 0a 6f 72 20 74 68 65   negative.or the
e2a0: 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f   first N bytes o
e2b0: 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d  f V if N is non-
e2c0: 6e 65 67 61 74 69 76 65 2e 0a 0a 48 4c 52 20 48  negative...HLR H
e2d0: 31 36 34 33 39 20 53 32 30 32 30 30 0a 54 68 65  16439 S20200.The
e2e0: 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
e2f0: 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29  _text16(C,V,N,D)
e300: 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
e310: 67 65 73 20 74 68 65 0a 72 65 74 75 72 6e 20 76  ges the.return v
e320: 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
e330: 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46   C to be the UTF
e340: 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
e350: 6f 72 64 65 72 0a 73 74 72 69 6e 67 20 56 20 75  order.string V u
e360: 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
e370: 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61  ero if N is nega
e380: 74 69 76 65 0a 6f 72 20 74 68 65 20 66 69 72 73  tive.or the firs
e390: 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69  t N bytes of V i
e3a0: 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
e3b0: 69 76 65 2e 0a 0a 48 4c 52 20 48 31 36 34 34 32  ive...HLR H16442
e3c0: 20 53 32 30 32 30 30 0a 54 68 65 20 5b 73 71 6c   S20200.The [sql
e3d0: 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
e3e0: 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16be(C,V,N,D)] i
e3f0: 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
e400: 20 74 68 65 0a 72 65 74 75 72 6e 20 76 61 6c 75   the.return valu
e410: 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
e420: 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36  to be the UTF-16
e430: 20 62 69 67 2d 65 6e 64 69 61 6e 0a 73 74 72 69   big-endian.stri
e440: 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66  ng V up to the f
e450: 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69  irst zero if N i
e460: 73 20 6e 65 67 61 74 69 76 65 0a 6f 72 20 74 68  s negative.or th
e470: 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20  e first N bytes 
e480: 6f 72 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e  or V if N is non
e490: 2d 6e 65 67 61 74 69 76 65 2e 0a 0a 48 4c 52 20  -negative...HLR 
e4a0: 48 31 36 34 34 35 20 53 32 30 32 30 30 0a 54 68  H16445 S20200.Th
e4b0: 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
e4c0: 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e  t_text16le(C,V,N
e4d0: 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
e4e0: 68 61 6e 67 65 73 20 74 68 65 0a 72 65 74 75 72  hanges the.retur
e4f0: 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
e500: 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
e510: 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e  UTF-16 little-en
e520: 64 69 61 6e 0a 73 74 72 69 6e 67 20 56 20 75 70  dian.string V up
e530: 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
e540: 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74  ro if N is negat
e550: 69 76 65 0a 6f 72 20 74 68 65 20 66 69 72 73 74  ive.or the first
e560: 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
e570: 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
e580: 76 65 2e 0a 0a 48 4c 52 20 48 31 36 34 34 38 20  ve...HLR H16448 
e590: 53 32 30 32 30 30 0a 54 68 65 20 5b 73 71 6c 69  S20200.The [sqli
e5a0: 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
e5b0: 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
e5c0: 20 63 68 61 6e 67 65 73 20 74 68 65 0a 72 65 74   changes the.ret
e5d0: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
e5e0: 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
e5f0: 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
e600: 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 6f 62  qlite3_value].ob
e610: 6a 65 63 74 20 56 2e 0a 0a 48 4c 52 20 48 31 36  ject V...HLR H16
e620: 34 35 31 20 53 32 30 32 30 30 0a 54 68 65 20 5b  451 S20200.The [
e630: 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
e640: 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e  eroblob(C,N)] in
e650: 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
e660: 74 68 65 0a 72 65 74 75 72 6e 20 76 61 6c 75 65  the.return value
e670: 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
e680: 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74 65 20 42  o be an N-byte B
e690: 4c 4f 42 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73  LOB of all zeros
e6a0: 2e 0a 0a 48 4c 52 20 48 31 36 34 35 34 20 53 32  ...HLR H16454 S2
e6b0: 30 32 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65  0200.The [sqlite
e6c0: 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
e6d0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
e6e0: 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 5d  esult_error16()]
e6f0: 0a 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65  .interfaces make
e700: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 69 72   a copy of their
e710: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
e720: 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a 72 65  trings before.re
e730: 74 75 72 6e 69 6e 67 2e 0a 0a 48 4c 52 20 48 31  turning...HLR H1
e740: 36 34 35 37 20 53 32 30 32 30 30 0a 49 66 20 74  6457 S20200.If t
e750: 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
e760: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
e770: 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
e780: 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 5b 73 71  b(C,V,N,D)],.[sq
e790: 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
e7a0: 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71  t(C,V,N,D)], [sq
e7b0: 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
e7c0: 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 5b  t16(C,V,N,D)],.[
e7d0: 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
e7e0: 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29  ext16be(C,V,N,D)
e7f0: 5d 2c 20 6f 72 0a 5b 73 71 6c 69 74 65 33 5f 72  ], or.[sqlite3_r
e800: 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43  esult_text16le(C
e810: 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20  ,V,N,D)] is the 
e820: 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45  constant [SQLITE
e830: 5f 53 54 41 54 49 43 5d 0a 74 68 65 6e 20 6e 6f  _STATIC].then no
e840: 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 65   destructor is e
e850: 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68  ver called on th
e860: 65 20 70 6f 69 6e 74 65 72 20 56 20 61 6e 64 20  e pointer V and 
e870: 53 51 4c 69 74 65 0a 61 73 73 75 6d 65 73 20 74  SQLite.assumes t
e880: 68 61 74 20 56 20 69 73 20 69 6d 6d 75 74 61 62  hat V is immutab
e890: 6c 65 2e 0a 0a 48 4c 52 20 48 31 36 34 36 30 20  le...HLR H16460 
e8a0: 53 32 30 32 30 30 0a 49 66 20 74 68 65 20 44 20  S20200.If the D 
e8b0: 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d  destructor param
e8c0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
e8d0: 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
e8e0: 2c 4e 2c 44 29 5d 2c 0a 5b 73 71 6c 69 74 65 33  ,N,D)],.[sqlite3
e8f0: 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
e900: 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ,N,D)], [sqlite3
e910: 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43  _result_text16(C
e920: 2c 56 2c 4e 2c 44 29 5d 2c 0a 5b 73 71 6c 69 74  ,V,N,D)],.[sqlit
e930: 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
e940: 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72  be(C,V,N,D)], or
e950: 0a 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  .[sqlite3_result
e960: 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c  _text16le(C,V,N,
e970: 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74  D)] is the const
e980: 61 6e 74 0a 5b 53 51 4c 49 54 45 5f 54 52 41 4e  ant.[SQLITE_TRAN
e990: 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 65 20  SIENT] then the 
e9a0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 73  interfaces makes
e9b0: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 63   a copy of the.c
e9c0: 6f 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64 20  ontent of V and 
e9d0: 72 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70 79  retains the copy
e9e0: 2e 0a 0a 48 4c 52 20 48 31 36 34 36 33 20 53 32  ...HLR H16463 S2
e9f0: 30 32 30 30 0a 49 66 20 74 68 65 20 44 20 64 65  0200.If the D de
ea00: 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
ea10: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
ea20: 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
ea30: 2c 44 29 5d 2c 0a 5b 73 71 6c 69 74 65 33 5f 72  ,D)],.[sqlite3_r
ea40: 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
ea50: 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72  ,D)], [sqlite3_r
ea60: 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56  esult_text16(C,V
ea70: 2c 4e 2c 44 29 5d 2c 0a 5b 73 71 6c 69 74 65 33  ,N,D)],.[sqlite3
ea80: 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
ea90: 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 5b  (C,V,N,D)], or.[
eaa0: 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
eab0: 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29  ext16le(C,V,N,D)
eac0: 5d 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65 20  ] is some value 
ead0: 6f 74 68 65 72 20 74 68 61 6e 0a 74 68 65 20 63  other than.the c
eae0: 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45  onstants [SQLITE
eaf0: 5f 53 54 41 54 49 43 5d 20 61 6e 64 20 5b 53 51  _STATIC] and [SQ
eb00: 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20  LITE_TRANSIENT] 
eb10: 74 68 65 6e 0a 53 51 4c 69 74 65 20 77 69 6c 6c  then.SQLite will
eb20: 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
eb30: 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 56 20  ructor D with V 
eb40: 61 73 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75  as its only argu
eb50: 6d 65 6e 74 0a 77 68 65 6e 20 69 74 20 68 61 73  ment.when it has
eb60: 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
eb70: 68 65 20 56 20 76 61 6c 75 65 2e 0a 0a 48 4c 52  he V value...HLR
eb80: 20 48 31 36 36 30 33 20 53 32 30 33 30 30 0a 41   H16603 S20300.A
eb90: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
eba0: 20 74 6f 20 74 68 65 0a 5b 73 71 6c 69 74 65 33   to the.[sqlite3
ebb0: 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
ebc0: 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
ebd0: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 72 65 67  )] interface.reg
ebe0: 69 73 74 65 72 73 20 66 75 6e 63 74 69 6f 6e 20  isters function 
ebf0: 46 20 61 73 20 74 68 65 20 63 6f 6d 70 61 72 69  F as the compari
ec00: 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73 65  son function use
ec10: 64 20 74 6f 0a 69 6d 70 6c 65 6d 65 6e 74 20 63  d to.implement c
ec20: 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 74 68  ollation X on th
ec30: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
ec40: 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 64 61  ection] B for.da
ec50: 74 61 62 61 73 65 73 20 68 61 76 69 6e 67 20 65  tabases having e
ec60: 6e 63 6f 64 69 6e 67 20 45 2e 0a 0a 48 4c 52 20  ncoding E...HLR 
ec70: 48 31 36 36 30 34 20 53 32 30 33 30 30 0a 53 51  H16604 S20300.SQ
ec80: 4c 69 74 65 20 75 6e 64 65 72 73 74 61 6e 64 73  Lite understands
ec90: 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   the X parameter
eca0: 20 74 6f 0a 5b 73 71 6c 69 74 65 33 5f 63 72 65   to.[sqlite3_cre
ecb0: 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
ecc0: 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61  (B,X,E,P,F,D)] a
ecd0: 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
ece0: 74 65 64 0a 55 54 46 2d 38 20 73 74 72 69 6e 67  ted.UTF-8 string
ecf0: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 69   in which case i
ed00: 73 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 53  s ignored for AS
ed10: 43 49 49 20 63 68 61 72 61 63 74 65 72 73 20 61  CII characters a
ed20: 6e 64 0a 69 73 20 73 69 67 6e 69 66 69 63 61 6e  nd.is significan
ed30: 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20  t for non-ASCII 
ed40: 63 68 61 72 61 63 74 65 72 73 2e 0a 0a 48 4c 52  characters...HLR
ed50: 20 48 31 36 36 30 36 20 53 32 30 33 30 30 0a 53   H16606 S20300.S
ed60: 75 63 63 65 73 73 69 76 65 20 63 61 6c 6c 73 20  uccessive calls 
ed70: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
ed80: 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
ed90: 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 77 69  B,X,E,P,F,D)].wi
eda0: 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  th the same valu
edb0: 65 73 20 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64  es for B, X, and
edc0: 20 45 2c 20 6f 76 65 72 72 69 64 65 20 70 72 69   E, override pri
edd0: 6f 72 20 76 61 6c 75 65 73 0a 6f 66 20 50 2c 20  or values.of P, 
ede0: 46 2c 20 61 6e 64 20 44 2e 0a 0a 48 4c 52 20 48  F, and D...HLR H
edf0: 31 36 36 30 39 20 53 32 30 33 30 30 0a 49 66 20  16609 S20300.If 
ee00: 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44  the destructor D
ee10: 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   in [sqlite3_cre
ee20: 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
ee30: 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 69  (B,X,E,P,F,D)].i
ee40: 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
ee50: 69 74 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  it is called wit
ee60: 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
ee70: 6e 20 74 68 65 0a 63 6f 6c 6c 61 74 69 6e 67 20  n the.collating 
ee80: 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
ee90: 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 0a  ped by SQLite...
eea0: 48 4c 52 20 48 31 36 36 31 32 20 53 32 30 33 30  HLR H16612 S2030
eeb0: 30 0a 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  0.A collating fu
eec0: 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65  nction is droppe
eed0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 6f 76 65  d when it is ove
eee0: 72 6c 6f 61 64 65 64 2e 0a 0a 48 4c 52 20 48 31  rloaded...HLR H1
eef0: 36 36 31 35 20 53 32 30 33 30 30 0a 41 20 63 6f  6615 S20300.A co
ef00: 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
ef10: 20 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e   is dropped when
ef20: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
ef30: 6e 6e 65 63 74 69 6f 6e 0a 69 73 20 63 6c 6f 73  nnection.is clos
ef40: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
ef50: 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 0a 48 4c 52  3_close()]...HLR
ef60: 20 48 31 36 36 31 38 20 53 32 30 33 30 30 0a 54   H16618 S20300.T
ef70: 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69 6e 20  he pointer P in 
ef80: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
ef90: 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
efa0: 2c 45 2c 50 2c 46 2c 44 29 5d 0a 69 73 20 70 61  ,E,P,F,D)].is pa
efb0: 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
efc0: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
efd0: 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6d 70 61  ter to the compa
efe0: 72 69 73 6f 6e 0a 66 75 6e 63 74 69 6f 6e 20 46  rison.function F
eff0: 20 66 6f 72 20 61 6c 6c 20 73 75 62 73 65 71 75   for all subsequ
f000: 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ent invocations 
f010: 6f 66 20 46 2e 0a 0a 48 4c 52 20 48 31 36 36 32  of F...HLR H1662
f020: 31 20 53 32 30 33 30 30 0a 41 20 63 61 6c 6c 20  1 S20300.A call 
f030: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
f040: 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58  te_collation(B,X
f050: 2c 45 2c 50 2c 46 29 5d 20 69 73 20 65 78 61 63  ,E,P,F)] is exac
f060: 74 6c 79 0a 74 68 65 20 73 61 6d 65 20 61 73 20  tly.the same as 
f070: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
f080: 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
f090: 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 0a 74  ion_v2()] with.t
f0a0: 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65  he same paramete
f0b0: 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64 65  rs and a NULL de
f0c0: 73 74 72 75 63 74 6f 72 2e 0a 0a 48 4c 52 20 48  structor...HLR H
f0d0: 31 36 36 32 34 20 53 32 30 33 30 30 0a 46 6f 6c  16624 S20300.Fol
f0e0: 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69 74 65  lowing a [sqlite
f0f0: 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
f100: 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
f110: 44 29 5d 2c 0a 53 51 4c 69 74 65 20 75 73 65 73  D)],.SQLite uses
f120: 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20   the comparison 
f130: 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61  function F for a
f140: 6c 6c 20 74 65 78 74 20 63 6f 6d 70 61 72 69 73  ll text comparis
f150: 6f 6e 0a 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  on.operations on
f160: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
f170: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 6f 6e 20  onnection] B on 
f180: 74 65 78 74 20 76 61 6c 75 65 73 20 74 68 61 74  text values that
f190: 0a 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 69  .use the collati
f1a0: 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  ng sequence name
f1b0: 64 20 58 2e 0a 0a 48 4c 52 20 48 31 36 36 32 37  d X...HLR H16627
f1c0: 20 53 32 30 33 30 30 0a 54 68 65 20 5b 73 71 6c   S20300.The [sql
f1d0: 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
f1e0: 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c  ation16(B,X,E,P,
f1f0: 46 29 5d 20 77 6f 72 6b 73 20 74 68 65 20 73 61  F)] works the sa
f200: 6d 65 0a 61 73 20 5b 73 71 6c 69 74 65 33 5f 63  me.as [sqlite3_c
f210: 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
f220: 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65  B,X,E,P,F)] exce
f230: 70 74 20 74 68 61 74 20 74 68 65 0a 63 6f 6c 6c  pt that the.coll
f240: 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20  ation name X is 
f250: 75 6e 64 65 72 73 74 6f 6f 64 20 61 73 20 55 54  understood as UT
f260: 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62  F-16 in native b
f270: 79 74 65 20 6f 72 64 65 72 0a 69 6e 73 74 65 61  yte order.instea
f280: 64 20 6f 66 20 55 54 46 2d 38 2e 0a 0a 48 4c 52  d of UTF-8...HLR
f290: 20 48 31 36 36 33 30 20 53 32 30 33 30 30 0a 57   H16630 S20300.W
f2a0: 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d  hen multiple com
f2b0: 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e  parison function
f2c0: 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20  s are available 
f2d0: 66 6f 72 20 74 68 65 20 73 61 6d 65 0a 63 6f 6c  for the same.col
f2e0: 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c  lating sequence,
f2f0: 20 53 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 20   SQLite chooses 
f300: 74 68 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 65  the one whose te
f310: 78 74 20 65 6e 63 6f 64 69 6e 67 0a 72 65 71 75  xt encoding.requ
f320: 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  ires the least a
f330: 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73  mount of convers
f340: 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64 65 66  ion from the def
f350: 61 75 6c 74 0a 74 65 78 74 20 65 6e 63 6f 64 69  ault.text encodi
f360: 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ng of the databa
f370: 73 65 2e 0a 0a 48 4c 52 20 48 31 36 37 30 32 20  se...HLR H16702 
f380: 53 32 30 33 30 30 0a 41 20 73 75 63 63 65 73 73  S20300.A success
f390: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
f3a0: 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
f3b0: 65 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a 6f 72  eeded(D,P,F)].or
f3c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
f3d0: 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44 2c 50  ion_needed16(D,P
f3e0: 2c 46 29 5d 20 63 61 75 73 65 73 0a 74 68 65 20  ,F)] causes.the 
f3f0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
f400: 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b  tion] D to invok
f410: 65 20 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 74  e callback F wit
f420: 68 20 66 69 72 73 74 0a 70 61 72 61 6d 65 74 65  h first.paramete
f430: 72 20 50 20 77 68 65 6e 65 76 65 72 20 69 74 20  r P whenever it 
f440: 6e 65 65 64 73 20 61 20 63 6f 6d 70 61 72 69 73  needs a comparis
f450: 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20  on function for 
f460: 61 0a 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75  a.collating sequ
f470: 65 6e 63 65 20 74 68 61 74 20 69 74 20 64 6f 65  ence that it doe
f480: 73 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 74  s not know about
f490: 2e 0a 0a 48 4c 52 20 48 31 36 37 30 34 20 53 32  ...HLR H16704 S2
f4a0: 30 33 30 30 0a 45 61 63 68 20 73 75 63 63 65 73  0300.Each succes
f4b0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
f4c0: 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
f4d0: 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 5b 73 71  needed()] or.[sq
f4e0: 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
f4f0: 6e 65 65 64 65 64 31 36 28 29 5d 20 6f 76 65 72  needed16()] over
f500: 72 69 64 65 73 20 74 68 65 20 63 61 6c 6c 62 61  rides the callba
f510: 63 6b 20 72 65 67 69 73 74 65 72 65 64 0a 6f 6e  ck registered.on
f520: 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
f530: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
f540: 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74  by prior calls t
f550: 6f 20 65 69 74 68 65 72 0a 69 6e 74 65 72 66 61  o either.interfa
f560: 63 65 2e 0a 0a 48 4c 52 20 48 31 36 37 30 36 20  ce...HLR H16706 
f570: 53 32 30 33 30 30 0a 54 68 65 20 6e 61 6d 65 20  S20300.The name 
f580: 6f 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  of the requested
f590: 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
f5a0: 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20 74 68  ion passed in th
f5b0: 65 0a 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e.4th parameter 
f5c0: 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
f5d0: 69 73 20 69 6e 20 55 54 46 2d 38 20 69 66 20 74  is in UTF-8 if t
f5e0: 68 65 20 63 61 6c 6c 62 61 63 6b 0a 77 61 73 20  he callback.was 
f5f0: 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
f600: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
f610: 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e  ion_needed()] an
f620: 64 0a 69 73 20 69 6e 20 55 54 46 2d 31 36 20 6e  d.is in UTF-16 n
f630: 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
f640: 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   if the callback
f650: 20 77 61 73 0a 72 65 67 69 73 74 65 72 65 64 20   was.registered 
f660: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
f670: 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
f680: 36 28 29 5d 2e 0a 0a 48 4c 52 20 48 31 37 33 30  6()]...HLR H1730
f690: 33 20 53 32 30 30 30 30 0a 54 68 65 20 5b 73 71  3 S20000.The [sq
f6a0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d  lite3_malloc(N)]
f6b0: 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
f6c0: 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e  ns either a poin
f6d0: 74 65 72 20 74 6f 0a 61 20 6e 65 77 6c 79 20 63  ter to.a newly c
f6e0: 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b  hecked-out block
f6f0: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
f700: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 74  ytes of memory.t
f710: 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c  hat is 8-byte al
f720: 69 67 6e 65 64 2c 20 6f 72 20 69 74 20 72 65 74  igned, or it ret
f730: 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74 20  urns NULL if it 
f740: 69 73 20 75 6e 61 62 6c 65 0a 74 6f 20 66 75 6c  is unable.to ful
f750: 66 69 6c 6c 20 74 68 65 20 72 65 71 75 65 73 74  fill the request
f760: 2e 0a 0a 48 4c 52 20 48 31 37 33 30 34 20 53 32  ...HLR H17304 S2
f770: 30 30 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65  0000.The [sqlite
f780: 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74  3_malloc(N)] int
f790: 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
f7a0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
f7b0: 0a 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  .N is less than 
f7c0: 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
f7d0: 2e 0a 0a 48 4c 52 20 48 31 37 33 30 35 20 53 32  ...HLR H17305 S2
f7e0: 30 30 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65  0000.The [sqlite
f7f0: 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74 65 72  3_free(P)] inter
f800: 66 61 63 65 20 72 65 6c 65 61 73 65 73 20 6d 65  face releases me
f810: 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c 79 0a  mory previously.
f820: 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
f830: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
f840: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
f850: 6c 6c 6f 63 28 29 5d 2c 0a 6d 61 6b 69 6e 67 20  lloc()],.making 
f860: 69 74 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72  it available for
f870: 20 72 65 75 73 65 2e 0a 0a 48 4c 52 20 48 31 37   reuse...HLR H17
f880: 33 30 36 20 53 32 30 30 30 30 0a 41 20 63 61 6c  306 S20000.A cal
f890: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  l to [sqlite3_fr
f8a0: 65 65 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20 68  ee(NULL)] is a h
f8b0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 0a  armless no-op...
f8c0: 48 4c 52 20 48 31 37 33 31 30 20 53 32 30 30 30  HLR H17310 S2000
f8d0: 30 0a 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  0.A call to [sql
f8e0: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e  ite3_realloc(0,N
f8f0: 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  )] is equivalent
f900: 20 74 6f 20 61 20 63 61 6c 6c 0a 74 6f 20 5b 73   to a call.to [s
f910: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
f920: 5d 2e 0a 0a 48 4c 52 20 48 31 37 33 31 32 20 53  ]...HLR H17312 S
f930: 32 30 30 30 30 0a 41 20 63 61 6c 6c 20 74 6f 20  20000.A call to 
f940: 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
f950: 28 50 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61  (P,0)] is equiva
f960: 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 74  lent to a call.t
f970: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
f980: 50 29 5d 2e 0a 0a 48 4c 52 20 48 31 37 33 31 35  P)]...HLR H17315
f990: 20 53 32 30 30 30 30 0a 54 68 65 20 53 51 4c 69   S20000.The SQLi
f9a0: 74 65 20 63 6f 72 65 20 75 73 65 73 20 5b 73 71  te core uses [sq
f9b0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
f9c0: 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
f9d0: 63 28 29 5d 2c 0a 61 6e 64 20 5b 73 71 6c 69 74  c()],.and [sqlit
f9e0: 65 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 20 61  e3_free()] for a
f9f0: 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d 6f 72 79  ll of its memory
fa00: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 0a   allocation and.
fa10: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  deallocation nee
fa20: 64 73 2e 0a 0a 48 4c 52 20 48 31 37 33 31 38 20  ds...HLR H17318 
fa30: 53 32 30 30 30 30 0a 54 68 65 20 5b 73 71 6c 69  S20000.The [sqli
fa40: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29  te3_realloc(P,N)
fa50: 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
fa60: 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69  rns either a poi
fa70: 6e 74 65 72 0a 74 6f 20 61 20 62 6c 6f 63 6b 20  nter.to a block 
fa80: 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d  of checked-out m
fa90: 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73  emory of at leas
faa0: 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
fab0: 65 0a 74 68 61 74 20 69 73 20 38 2d 62 79 74 65  e.that is 8-byte
fac0: 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e   aligned, or a N
fad0: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 0a 48 4c  ULL pointer...HL
fae0: 52 20 48 31 37 33 32 31 20 53 32 30 30 30 30 0a  R H17321 S20000.
faf0: 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  When [sqlite3_re
fb00: 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75  alloc(P,N)] retu
fb10: 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  rns a non-NULL p
fb20: 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74  ointer, it first
fb30: 0a 63 6f 70 69 65 73 20 74 68 65 20 66 69 72 73  .copies the firs
fb40: 74 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f 6e  t K bytes of con
fb50: 74 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74 6f  tent from P into
fb60: 20 74 68 65 20 6e 65 77 6c 79 0a 61 6c 6c 6f 63   the newly.alloc
fb70: 61 74 65 64 20 62 6c 6f 63 6b 2c 20 77 68 65 72  ated block, wher
fb80: 65 20 4b 20 69 73 20 74 68 65 20 6c 65 73 73 65  e K is the lesse
fb90: 72 20 6f 66 20 4e 20 61 6e 64 20 74 68 65 20 73  r of N and the s
fba0: 69 7a 65 20 6f 66 0a 74 68 65 20 62 75 66 66 65  ize of.the buffe
fbb0: 72 20 50 2e 0a 0a 48 4c 52 20 48 31 37 33 32 32  r P...HLR H17322
fbc0: 20 53 32 30 30 30 30 0a 57 68 65 6e 20 5b 73 71   S20000.When [sq
fbd0: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
fbe0: 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  N)] returns a no
fbf0: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
fc00: 69 74 20 66 69 72 73 74 0a 72 65 6c 65 61 73 65  it first.release
fc10: 73 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a  s the buffer P..
fc20: 0a 48 4c 52 20 48 31 37 33 32 33 20 53 32 30 30  .HLR H17323 S200
fc30: 30 30 0a 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  00.When [sqlite3
fc40: 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72  _realloc(P,N)] r
fc50: 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
fc60: 20 62 75 66 66 65 72 20 50 20 69 73 0a 6e 6f 74   buffer P is.not
fc70: 20 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65 6c   modified or rel
fc80: 65 61 73 65 64 2e 0a 0a 48 4c 52 20 48 31 37 33  eased...HLR H173
fc90: 34 31 20 53 33 30 32 32 30 0a 54 68 65 20 5b 73  41 S30220.The [s
fca0: 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
fcb0: 65 6d 6f 72 79 28 4e 29 5d 20 69 6e 74 65 72 66  emory(N)] interf
fcc0: 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 0a  ace attempts to.
fcd0: 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20  free N bytes of 
fce0: 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64  heap memory by d
fcf0: 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d  eallocating non-
fd00: 65 73 73 65 6e 74 69 61 6c 0a 6d 65 6d 6f 72 79  essential.memory
fd10: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c   allocations hel
fd20: 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
fd30: 65 20 6c 69 62 72 61 72 79 2e 0a 0a 48 4c 52 20  e library...HLR 
fd40: 48 31 37 33 34 32 20 53 33 30 32 32 30 0a 54 68  H17342 S30220.Th
fd50: 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  e [sqlite3_relea
fd60: 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 72 65  se_memory(N)] re
fd70: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
fd80: 0a 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c  .of bytes actual
fd90: 6c 79 20 66 72 65 65 64 2c 20 77 68 69 63 68 20  ly freed, which 
fda0: 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72  might be more or
fdb0: 20 6c 65 73 73 0a 74 68 61 6e 20 74 68 65 20 61   less.than the a
fdc0: 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e  mount requested.
fdd0: 0a 0a 48 4c 52 20 48 31 37 33 37 31 20 53 33 30  ..HLR H17371 S30
fde0: 32 31 30 0a 54 68 65 20 5b 73 71 6c 69 74 65 33  210.The [sqlite3
fdf0: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
fe00: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
fe10: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
fe20: 74 65 73 0a 6f 66 20 6d 65 6d 6f 72 79 20 63 75  tes.of memory cu
fe30: 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
fe40: 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
fe50: 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 0a 48  t not freed)...H
fe60: 4c 52 20 48 31 37 33 37 33 20 53 33 30 32 31 30  LR H17373 S30210
fe70: 0a 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  .The [sqlite3_me
fe80: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
fe90: 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
fea0: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 76 61  s the maximum.va
feb0: 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
fec0: 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
fed0: 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
fee0: 74 65 72 20 6d 61 72 6b 0a 77 61 73 20 6c 61 73  ter mark.was las
fef0: 74 20 72 65 73 65 74 2e 0a 0a 48 4c 52 20 48 31  t reset...HLR H1
ff00: 37 33 37 34 20 53 33 30 32 31 30 0a 54 68 65 20  7374 S30210.The 
ff10: 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
ff20: 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
ff30: 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 5b  ry_used()] and.[
ff40: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
ff50: 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
ff60: 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
ff70: 0a 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65  .added by SQLite
ff80: 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
ff90: 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
ffa0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 62 75  e3_malloc()],.bu
ffb0: 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
ffc0: 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
ffd0: 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
ffe0: 6d 20 6c 69 62 72 61 72 79 0a 72 6f 75 74 69 6e  m library.routin
fff0: 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
10000 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
10010 61 6c 6c 2e 0a 0a 48 4c 52 20 48 31 37 33 37 35  all...HLR H17375
10020 20 53 33 30 32 31 30 0a 54 68 65 20 6d 65 6d 6f   S30210.The memo
10030 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  ry high-water ma
10040 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
10050 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
10060 20 6f 66 0a 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of.[sqlite3_mem
10070 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
10080 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
10090 61 72 61 6d 65 74 65 72 20 74 6f 0a 5b 73 71 6c  arameter to.[sql
100a0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
100b0 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
100c0 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  .  The value ret
100d0 75 72 6e 65 64 0a 62 79 20 5b 73 71 6c 69 74 65  urned.by [sqlite
100e0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
100f0 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
10100 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 70 72  gh-water mark.pr
10110 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
10120 2e 0a 0a 48 4c 52 20 48 31 37 33 39 32 20 53 32  ...HLR H17392 S2
10130 30 30 30 30 0a 54 68 65 20 5b 73 71 6c 69 74 65  0000.The [sqlite
10140 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50  3_randomness(N,P
10150 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72 69  )] interface wri
10160 74 65 73 20 4e 20 62 79 74 65 73 20 6f 66 0a 68  tes N bytes of.h
10170 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
10180 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  do-randomness in
10190 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 0a 48 4c  to buffer P...HL
101a0 52 20 48 31 37 34 30 33 20 53 37 30 30 30 30 0a  R H17403 S70000.
101b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  The [sqlite3_mpr
101c0 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c  intf()] and [sql
101d0 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d  ite3_vmprintf()]
101e0 20 69 6e 74 65 72 66 61 63 65 73 0a 72 65 74 75   interfaces.retu
101f0 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65  rn either pointe
10200 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
10210 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
10220 6e 67 73 20 68 65 6c 64 20 69 6e 0a 6d 65 6d 6f  ngs held in.memo
10230 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
10240 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
10250 28 29 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e  ()] or NULL poin
10260 74 65 72 73 20 69 66 0a 61 20 63 61 6c 6c 20 74  ters if.a call t
10270 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
10280 63 28 29 5d 20 66 61 69 6c 73 2e 0a 0a 48 4c 52  c()] fails...HLR
10290 20 48 31 37 34 30 36 20 53 37 30 30 30 30 0a 54   H17406 S70000.T
102a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  he [sqlite3_snpr
102b0 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63  intf()] interfac
102c0 65 20 77 72 69 74 65 73 20 61 20 7a 65 72 6f 2d  e writes a zero-
102d0 74 65 72 6d 69 6e 61 74 65 64 0a 55 54 46 2d 38  terminated.UTF-8
102e0 20 73 74 72 69 6e 67 20 69 6e 74 6f 20 74 68 65   string into the
102f0 20 62 75 66 66 65 72 20 70 6f 69 6e 74 65 64 20   buffer pointed 
10300 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
10310 20 70 61 72 61 6d 65 74 65 72 0a 70 72 6f 76 69   parameter.provi
10320 64 65 64 20 74 68 61 74 20 74 68 65 20 66 69 72  ded that the fir
10330 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
10340 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
10350 6f 2e 0a 0a 48 4c 52 20 48 31 37 34 30 37 20 53  o...HLR H17407 S
10360 37 30 30 30 30 0a 54 68 65 20 5b 73 71 6c 69 74  70000.The [sqlit
10370 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
10380 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
10390 74 20 77 72 69 74 65 20 73 6c 6f 74 73 20 6f 66  t write slots of
103a0 0a 69 74 73 20 6f 75 74 70 75 74 20 62 75 66 66  .its output buff
103b0 65 72 20 28 74 68 65 20 73 65 63 6f 6e 64 20 70  er (the second p
103c0 61 72 61 6d 65 74 65 72 29 20 6f 75 74 73 69 64  arameter) outsid
103d0 65 20 74 68 65 20 72 61 6e 67 65 0a 6f 66 20 30  e the range.of 0
103e0 20 74 68 72 6f 75 67 68 20 4e 2d 31 20 28 77 68   through N-1 (wh
103f0 65 72 65 20 4e 20 69 73 20 74 68 65 20 66 69 72  ere N is the fir
10400 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 72 65  st parameter).re
10410 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
10420 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
10430 72 69 6e 67 0a 72 65 71 75 65 73 74 65 64 20 62  ring.requested b
10440 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73 70 65  y the format spe
10450 63 69 66 69 63 61 74 69 6f 6e 2e 0a 0a 48 4c 52  cification...HLR
10460 20 48 31 37 38 31 33 20 53 33 30 32 33 30 0a 41   H17813 S30230.A
10470 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
10480 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  cation of the [s
10490 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
104a0 28 44 2c 42 2c 54 2c 43 2c 52 2c 46 2c 50 29 5d  (D,B,T,C,R,F,P)]
104b0 0a 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c  .interface shall
104c0 20 6f 70 65 6e 20 61 6e 20 5b 73 71 6c 69 74 65   open an [sqlite
104d0 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 50  3_blob] object P
104e0 20 6f 6e 20 74 68 65 20 42 4c 4f 42 0a 69 6e 20   on the BLOB.in 
104f0 63 6f 6c 75 6d 6e 20 43 20 6f 66 20 74 68 65 20  column C of the 
10500 74 61 62 6c 65 20 54 20 69 6e 20 74 68 65 20 64  table T in the d
10510 61 74 61 62 61 73 65 20 42 20 6f 6e 0a 74 68 65  atabase B on.the
10520 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10530 63 74 69 6f 6e 5d 20 44 2e 0a 0a 48 4c 52 20 48  ction] D...HLR H
10540 31 37 38 31 34 20 53 33 30 32 33 30 0a 41 20 73  17814 S30230.A s
10550 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
10560 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
10570 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 2e 2e 2e  _blob_open(D,...
10580 29 5d 20 73 68 61 6c 6c 20 73 74 61 72 74 0a 61  )] shall start.a
10590 20 6e 65 77 20 74 72 61 6e 73 61 63 74 69 6f 6e   new transaction
105a0 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
105b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
105c0 69 66 20 74 68 61 74 0a 63 6f 6e 6e 65 63 74 69  if that.connecti
105d0 6f 6e 20 69 73 20 6e 6f 74 20 61 6c 72 65 61 64  on is not alread
105e0 79 20 69 6e 20 61 20 74 72 61 6e 73 61 63 74 69  y in a transacti
105f0 6f 6e 2e 0a 0a 48 4c 52 20 48 31 37 38 31 36 20  on...HLR H17816 
10600 53 33 30 32 33 30 0a 54 68 65 20 5b 73 71 6c 69  S30230.The [sqli
10610 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c  te3_blob_open(D,
10620 42 2c 54 2c 43 2c 52 2c 46 2c 50 29 5d 20 69 6e  B,T,C,R,F,P)] in
10630 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 6f 70  terface shall op
10640 65 6e 0a 74 68 65 20 42 4c 4f 42 20 66 6f 72 20  en.the BLOB for 
10650 72 65 61 64 20 61 6e 64 20 77 72 69 74 65 20 61  read and write a
10660 63 63 65 73 73 20 69 66 20 61 6e 64 20 6f 6e 6c  ccess if and onl
10670 79 20 69 66 20 74 68 65 20 46 0a 70 61 72 61 6d  y if the F.param
10680 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f  eter is non-zero
10690 2e 0a 0a 48 4c 52 20 48 31 37 38 31 39 20 53 33  ...HLR H17819 S3
106a0 30 32 33 30 0a 54 68 65 20 5b 73 71 6c 69 74 65  0230.The [sqlite
106b0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 69  3_blob_open()] i
106c0 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72  nterface shall r
106d0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
106e0 5d 20 6f 6e 0a 73 75 63 63 65 73 73 20 61 6e 64  ] on.success and
106f0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
10700 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20  [error code] on 
10710 66 61 69 6c 75 72 65 2e 0a 0a 48 4c 52 20 48 31  failure...HLR H1
10720 37 38 32 31 20 53 33 30 32 33 30 0a 49 66 20 61  7821 S30230.If a
10730 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
10740 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e  uring evaluation
10750 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   of [sqlite3_blo
10760 62 5f 6f 70 65 6e 28 44 2c 2e 2e 2e 29 5d 0a 74  b_open(D,...)].t
10770 68 65 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63  hen subsequent c
10780 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
10790 5f 65 72 72 63 6f 64 65 28 44 29 5d 2c 0a 5b 73  _errcode(D)],.[s
107a0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
107b0 65 72 72 63 6f 64 65 28 29 5d 2c 0a 5b 73 71 6c  errcode()],.[sql
107c0 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 2c  ite3_errmsg(D)],
107d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
107e0 72 6d 73 67 31 36 28 44 29 5d 20 73 68 61 6c 6c  rmsg16(D)] shall
107f0 20 72 65 74 75 72 6e 0a 69 6e 66 6f 72 6d 61 74   return.informat
10800 69 6f 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20  ion appropriate 
10810 66 6f 72 20 74 68 61 74 20 65 72 72 6f 72 2e 0a  for that error..
10820 0a 48 4c 52 20 48 31 37 38 32 34 20 53 33 30 32  .HLR H17824 S302
10830 33 30 0a 49 66 20 61 6e 79 20 63 6f 6c 75 6d 6e  30.If any column
10840 20 69 6e 20 74 68 65 20 72 6f 77 20 74 68 61 74   in the row that
10850 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62   a [sqlite3_blob
10860 5d 20 68 61 73 20 6f 70 65 6e 20 69 73 0a 63 68  ] has open is.ch
10870 61 6e 67 65 64 20 62 79 20 61 20 73 65 70 61 72  anged by a separ
10880 61 74 65 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  ate [UPDATE] or 
10890 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
108a0 6e 74 20 6f 72 20 62 79 0a 61 6e 20 5b 4f 4e 20  nt or by.an [ON 
108b0 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 20 65  CONFLICT] side e
108c0 66 66 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20  ffect, then the 
108d0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 73  [sqlite3_blob] s
108e0 68 61 6c 6c 0a 62 65 20 6d 61 72 6b 65 64 20 61  hall.be marked a
108f0 73 20 69 6e 76 61 6c 69 64 2e 0a 0a 48 4c 52 20  s invalid...HLR 
10900 48 31 37 38 33 33 20 53 33 30 32 33 30 0a 54 68  H17833 S30230.Th
10910 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
10920 63 6c 6f 73 65 28 50 29 5d 20 69 6e 74 65 72 66  close(P)] interf
10930 61 63 65 20 63 6c 6f 73 65 73 20 61 6e 20 5b 73  ace closes an [s
10940 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 0a 6f 62 6a  qlite3_blob].obj
10950 65 63 74 20 50 20 70 72 65 76 69 6f 75 73 6c 79  ect P previously
10960 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 20 5b 73   opened using [s
10970 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
10980 28 29 5d 2e 0a 0a 48 4c 52 20 48 31 37 38 33 36  ()]...HLR H17836
10990 20 53 33 30 32 33 30 0a 43 6c 6f 73 69 6e 67 20   S30230.Closing 
109a0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  an [sqlite3_blob
109b0 5d 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 0a 5b  ] object using.[
109c0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
109d0 73 65 28 29 5d 20 73 68 61 6c 6c 20 63 61 75 73  se()] shall caus
109e0 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72  e the current tr
109f0 61 6e 73 61 63 74 69 6f 6e 20 74 6f 0a 63 6f 6d  ansaction to.com
10a00 6d 69 74 20 69 66 20 74 68 65 72 65 20 61 72 65  mit if there are
10a10 20 6e 6f 20 6f 74 68 65 72 20 6f 70 65 6e 20 5b   no other open [
10a20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62  sqlite3_blob] ob
10a30 6a 65 63 74 73 0a 6f 72 20 5b 70 72 65 70 61 72  jects.or [prepar
10a40 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f  ed statements] o
10a50 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
10a60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10a70 20 61 6e 64 0a 74 68 65 20 64 61 74 61 62 61 73   and.the databas
10a80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
10a90 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  in [autocommit m
10aa0 6f 64 65 5d 2e 0a 0a 48 4c 52 20 48 31 37 38 33  ode]...HLR H1783
10ab0 39 20 53 33 30 32 33 30 0a 54 68 65 20 5b 73 71  9 S30230.The [sq
10ac0 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
10ad0 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  (P)] interfaces 
10ae0 73 68 61 6c 6c 20 63 6c 6f 73 65 20 74 68 65 0a  shall close the.
10af0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f  [sqlite3_blob] o
10b00 62 6a 65 63 74 20 50 20 75 6e 63 6f 6e 64 69 74  bject P uncondit
10b10 69 6f 6e 61 6c 6c 79 2c 20 65 76 65 6e 20 69 66  ionally, even if
10b20 0a 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63  .[sqlite3_blob_c
10b30 6c 6f 73 65 28 50 29 5d 20 72 65 74 75 72 6e 73  lose(P)] returns
10b40 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
10b50 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
10b60 5d 2e 0a 0a 48 4c 52 20 48 31 37 38 34 33 20 53  ]...HLR H17843 S
10b70 33 30 32 33 30 0a 54 68 65 20 5b 73 71 6c 69 74  30230.The [sqlit
10b80 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 50 29  e3_blob_bytes(P)
10b90 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
10ba0 72 6e 73 20 74 68 65 20 73 69 7a 65 0a 69 6e 20  rns the size.in 
10bb0 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f  bytes of the BLO
10bc0 42 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  B that the [sqli
10bd0 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74  te3_blob] object
10be0 20 50 0a 72 65 66 65 72 73 20 74 6f 2e 0a 0a 48   P.refers to...H
10bf0 4c 52 20 48 31 37 38 35 33 20 53 33 30 32 33 30  LR H17853 S30230
10c00 0a 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e  .A successful in
10c10 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
10c20 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50  ite3_blob_read(P
10c30 2c 5a 2c 4e 2c 58 29 5d 0a 73 68 61 6c 6c 20 72  ,Z,N,X)].shall r
10c40 65 61 64 73 20 4e 20 62 79 74 65 73 20 6f 66 20  eads N bytes of 
10c50 64 61 74 61 20 6f 75 74 20 6f 66 20 74 68 65 20  data out of the 
10c60 42 4c 4f 42 20 72 65 66 65 72 65 6e 63 65 64 20  BLOB referenced 
10c70 62 79 0a 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  by.[BLOB handle]
10c80 20 50 20 62 65 67 69 6e 6e 69 6e 67 20 61 74 20   P beginning at 
10c90 6f 66 66 73 65 74 20 58 20 61 6e 64 20 73 74 6f  offset X and sto
10ca0 72 65 20 74 68 6f 73 65 20 62 79 74 65 73 0a 69  re those bytes.i
10cb0 6e 74 6f 20 62 75 66 66 65 72 20 5a 2e 0a 0a 48  nto buffer Z...H
10cc0 4c 52 20 48 31 37 38 35 36 20 53 33 30 32 33 30  LR H17856 S30230
10cd0 0a 49 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .In [sqlite3_blo
10ce0 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d  b_read(P,Z,N,X)]
10cf0 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20   if the size of 
10d00 74 68 65 20 42 4c 4f 42 0a 69 73 20 6c 65 73 73  the BLOB.is less
10d10 20 74 68 61 6e 20 4e 2b 58 20 62 79 74 65 73 2c   than N+X bytes,
10d20 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   then the functi
10d30 6f 6e 20 73 68 61 6c 6c 20 6c 65 61 76 65 20 74  on shall leave t
10d40 68 65 0a 5a 20 62 75 66 66 65 72 20 75 6e 63 68  he.Z buffer unch
10d50 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
10d60 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
10d70 0a 0a 48 4c 52 20 48 31 37 38 35 39 20 53 33 30  ..HLR H17859 S30
10d80 32 33 30 0a 49 6e 20 5b 73 71 6c 69 74 65 33 5f  230.In [sqlite3_
10d90 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c  blob_read(P,Z,N,
10da0 58 29 5d 20 69 66 20 58 20 6f 72 20 4e 20 69 73  X)] if X or N is
10db0 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 0a   less than zero.
10dc0 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  then the functio
10dd0 6e 20 73 68 61 6c 6c 20 6c 65 61 76 65 20 74 68  n shall leave th
10de0 65 20 5a 20 62 75 66 66 65 72 20 75 6e 63 68 61  e Z buffer uncha
10df0 6e 67 65 64 0a 61 6e 64 20 72 65 74 75 72 6e 20  nged.and return 
10e00 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a  [SQLITE_ERROR]..
10e10 0a 48 4c 52 20 48 31 37 38 36 32 20 53 33 30 32  .HLR H17862 S302
10e20 33 30 0a 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  30.The [sqlite3_
10e30 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c  blob_read(P,Z,N,
10e40 58 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  X)] interface sh
10e50 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  all return [SQLI
10e60 54 45 5f 4f 4b 5d 0a 69 66 20 4e 20 62 79 74 65  TE_OK].if N byte
10e70 73 20 61 72 65 20 73 75 63 63 65 73 73 66 75 6c  s are successful
10e80 6c 79 20 72 65 61 64 20 69 6e 74 6f 20 62 75 66  ly read into buf
10e90 66 65 72 20 5a 2e 0a 0a 48 4c 52 20 48 31 37 38  fer Z...HLR H178
10ea0 36 33 20 53 33 30 32 33 30 0a 49 66 20 74 68 65  63 S30230.If the
10eb0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 50   [BLOB handle] P
10ec0 20 69 73 20 65 78 70 69 72 65 64 20 61 6e 64 20   is expired and 
10ed0 58 20 61 6e 64 20 4e 20 61 72 65 20 77 69 74 68  X and N are with
10ee0 69 6e 20 62 6f 75 6e 64 73 0a 74 68 65 6e 20 5b  in bounds.then [
10ef0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
10f00 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 73 68 61 6c  d(P,Z,N,X)] shal
10f10 6c 20 6c 65 61 76 65 20 74 68 65 20 5a 20 62 75  l leave the Z bu
10f20 66 66 65 72 0a 75 6e 63 68 61 6e 67 65 64 20 61  ffer.unchanged a
10f30 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
10f40 45 5f 41 42 4f 52 54 5d 2e 0a 0a 48 4c 52 20 48  E_ABORT]...HLR H
10f50 31 37 38 36 35 20 53 33 30 32 33 30 0a 49 66 20  17865 S30230.If 
10f60 74 68 65 20 72 65 71 75 65 73 74 65 64 20 72 65  the requested re
10f70 61 64 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ad could not be 
10f80 63 6f 6d 70 6c 65 74 65 64 2c 0a 74 68 65 20 5b  completed,.the [
10f90 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
10fa0 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65  d(P,Z,N,X)] inte
10fb0 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75  rface shall retu
10fc0 72 6e 20 61 6e 0a 61 70 70 72 6f 70 72 69 61 74  rn an.appropriat
10fd0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
10fe0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
10ff0 72 20 63 6f 64 65 5d 2e 0a 0a 48 4c 52 20 48 31  r code]...HLR H1
11000 37 38 36 38 20 53 33 30 32 33 30 0a 49 66 20 61  7868 S30230.If a
11010 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
11020 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e  uring evaluation
11030 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   of [sqlite3_blo
11040 62 5f 72 65 61 64 28 50 2c 2e 2e 2e 29 5d 0a 74  b_read(P,...)].t
11050 68 65 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63  hen subsequent c
11060 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
11070 5f 65 72 72 63 6f 64 65 28 44 29 5d 2c 0a 5b 73  _errcode(D)],.[s
11080 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
11090 65 72 72 63 6f 64 65 28 29 5d 2c 0a 5b 73 71 6c  errcode()],.[sql
110a0 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 2c  ite3_errmsg(D)],
110b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
110c0 72 6d 73 67 31 36 28 44 29 5d 20 73 68 61 6c 6c  rmsg16(D)] shall
110d0 20 72 65 74 75 72 6e 0a 69 6e 66 6f 72 6d 61 74   return.informat
110e0 69 6f 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20  ion appropriate 
110f0 66 6f 72 20 74 68 61 74 20 65 72 72 6f 72 2c 20  for that error, 
11100 77 68 65 72 65 20 44 20 69 73 20 74 68 65 0a 5b  where D is the.[
11110 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11120 69 6f 6e 5d 20 74 68 61 74 20 77 61 73 20 75 73  ion] that was us
11130 65 64 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 5b  ed to open the [
11140 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 50 2e 0a  BLOB handle] P..
11150 0a 48 4c 52 20 48 31 37 38 37 33 20 53 33 30 32  .HLR H17873 S302
11160 33 30 0a 41 20 73 75 63 63 65 73 73 66 75 6c 20  30.A successful 
11170 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
11180 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
11190 65 28 50 2c 5a 2c 4e 2c 58 29 5d 0a 73 68 61 6c  e(P,Z,N,X)].shal
111a0 6c 20 77 72 69 74 65 20 4e 20 62 79 74 65 73 20  l write N bytes 
111b0 6f 66 20 64 61 74 61 20 66 72 6f 6d 20 62 75 66  of data from buf
111c0 66 65 72 20 5a 20 69 6e 74 6f 20 74 68 65 20 42  fer Z into the B
111d0 4c 4f 42 0a 72 65 66 65 72 65 6e 63 65 64 20 62  LOB.referenced b
111e0 79 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  y [BLOB handle] 
111f0 50 20 62 65 67 69 6e 6e 69 6e 67 20 61 74 20 6f  P beginning at o
11200 66 66 73 65 74 20 58 20 69 6e 74 6f 0a 74 68 65  ffset X into.the
11210 20 42 4c 4f 42 2e 0a 0a 48 4c 52 20 48 31 37 38   BLOB...HLR H178
11220 37 34 20 53 33 30 32 33 30 0a 49 6e 20 74 68 65  74 S30230.In the
11230 20 61 62 73 65 6e 63 65 20 6f 66 20 6f 74 68 65   absence of othe
11240 72 20 6f 76 65 72 72 69 64 64 69 6e 67 20 63 68  r overridding ch
11250 61 6e 67 65 73 2c 20 74 68 65 20 63 68 61 6e 67  anges, the chang
11260 65 73 0a 77 72 69 74 74 65 6e 20 74 6f 20 61 20  es.written to a 
11270 42 4c 4f 42 20 62 79 20 5b 73 71 6c 69 74 65 33  BLOB by [sqlite3
11280 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 73  _blob_write()] s
11290 68 61 6c 6c 0a 72 65 6d 61 69 6e 20 69 6e 20 65  hall.remain in e
112a0 66 66 65 63 74 20 61 66 74 65 72 20 74 68 65 20  ffect after the 
112b0 61 73 73 6f 63 69 61 74 65 64 20 5b 42 4c 4f 42  associated [BLOB
112c0 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 73   handle] expires
112d0 2e 0a 0a 48 4c 52 20 48 31 37 38 37 35 20 53 33  ...HLR H17875 S3
112e0 30 32 33 30 0a 49 66 20 74 68 65 20 5b 42 4c 4f  0230.If the [BLO
112f0 42 20 68 61 6e 64 6c 65 5d 20 50 20 77 61 73 20  B handle] P was 
11300 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
11310 6e 67 20 6f 6e 6c 79 20 74 68 65 6e 0a 61 6e 20  ng only then.an 
11320 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
11330 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
11340 65 28 50 2c 5a 2c 4e 2c 58 29 5d 20 73 68 61 6c  e(P,Z,N,X)] shal
11350 6c 20 6c 65 61 76 65 0a 74 68 65 20 72 65 66 65  l leave.the refe
11360 72 65 6e 63 65 64 20 42 4c 4f 42 20 75 6e 63 68  renced BLOB unch
11370 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
11380 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   [SQLITE_READONL
11390 59 5d 2e 0a 0a 48 4c 52 20 48 31 37 38 37 36 20  Y]...HLR H17876 
113a0 53 33 30 32 33 30 0a 49 66 20 74 68 65 20 73 69  S30230.If the si
113b0 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 72  ze of the BLOB r
113c0 65 66 65 72 65 6e 63 65 64 20 62 79 20 5b 42 4c  eferenced by [BL
113d0 4f 42 20 68 61 6e 64 6c 65 5d 20 50 20 69 73 0a  OB handle] P is.
113e0 6c 65 73 73 20 74 68 61 6e 20 4e 2b 58 20 62 79  less than N+X by
113f0 74 65 73 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  tes then [sqlite
11400 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 2c 5a  3_blob_write(P,Z
11410 2c 4e 2c 58 29 5d 20 73 68 61 6c 6c 0a 6c 65 61  ,N,X)] shall.lea
11420 76 65 20 74 68 65 20 42 4c 4f 42 20 75 6e 63 68  ve the BLOB unch
11430 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
11440 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
11450 0a 0a 48 4c 52 20 48 31 37 38 37 37 20 53 33 30  ..HLR H17877 S30
11460 32 33 30 0a 49 66 20 74 68 65 20 5b 42 4c 4f 42  230.If the [BLOB
11470 20 68 61 6e 64 6c 65 5d 20 50 20 69 73 20 65 78   handle] P is ex
11480 70 69 72 65 64 20 61 6e 64 20 58 20 61 6e 64 20  pired and X and 
11490 4e 20 61 72 65 20 77 69 74 68 69 6e 20 62 6f 75  N are within bou
114a0 6e 64 73 0a 74 68 65 6e 20 5b 73 71 6c 69 74 65  nds.then [sqlite
114b0 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c  3_blob_read(P,Z,
114c0 4e 2c 58 29 5d 20 73 68 61 6c 6c 20 6c 65 61 76  N,X)] shall leav
114d0 65 20 74 68 65 20 42 4c 4f 42 0a 75 6e 63 68 61  e the BLOB.uncha
114e0 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 20  nged and return 
114f0 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
11500 0a 48 4c 52 20 48 31 37 38 37 39 20 53 33 30 32  .HLR H17879 S302
11510 33 30 0a 49 66 20 58 20 6f 72 20 4e 20 61 72 65  30.If X or N are
11520 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20   less than zero 
11530 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c  then [sqlite3_bl
11540 6f 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58  ob_write(P,Z,N,X
11550 29 5d 0a 73 68 61 6c 6c 20 6c 65 61 76 65 20 74  )].shall leave t
11560 68 65 20 42 4c 4f 42 20 72 65 66 65 72 65 6e 63  he BLOB referenc
11570 65 64 20 62 79 20 5b 42 4c 4f 42 20 68 61 6e 64  ed by [BLOB hand
11580 6c 65 5d 20 50 20 75 6e 63 68 61 6e 67 65 64 0a  le] P unchanged.
11590 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
115a0 54 45 5f 45 52 52 4f 52 5d 2e 0a 0a 48 4c 52 20  TE_ERROR]...HLR 
115b0 48 31 37 38 38 32 20 53 33 30 32 33 30 0a 54 68  H17882 S30230.Th
115c0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
115d0 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29 5d 20  write(P,Z,N,X)] 
115e0 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
115f0 72 65 74 75 72 6e 0a 5b 53 51 4c 49 54 45 5f 4f  return.[SQLITE_O
11600 4b 5d 20 69 66 20 4e 20 62 79 74 65 73 20 77 68  K] if N bytes wh
11610 65 72 65 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ere successfully
11620 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
11630 65 20 42 4c 4f 42 2e 0a 0a 48 4c 52 20 48 31 37  e BLOB...HLR H17
11640 38 38 35 20 53 33 30 32 33 30 0a 49 66 20 74 68  885 S30230.If th
11650 65 20 72 65 71 75 65 73 74 65 64 20 77 72 69 74  e requested writ
11660 65 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63  e could not be c
11670 6f 6d 70 6c 65 74 65 64 2c 0a 74 68 65 20 5b 73  ompleted,.the [s
11680 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
11690 65 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65  e(P,Z,N,X)] inte
116a0 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75  rface shall retu
116b0 72 6e 20 61 6e 0a 61 70 70 72 6f 70 72 69 61 74  rn an.appropriat
116c0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
116d0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
116e0 72 20 63 6f 64 65 5d 2e 0a 0a 48 4c 52 20 48 31  r code]...HLR H1
116f0 37 38 38 38 20 53 33 30 32 33 30 0a 49 66 20 61  7888 S30230.If a
11700 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
11710 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e  uring evaluation
11720 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   of [sqlite3_blo
11730 62 5f 77 72 69 74 65 28 44 2c 2e 2e 2e 29 5d 0a  b_write(D,...)].
11740 74 68 65 6e 20 73 75 62 73 65 71 75 65 6e 74 20  then subsequent 
11750 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
11760 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 2c 0a 5b  3_errcode(D)],.[
11770 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
11780 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 5b 73 71  _errcode()],.[sq
11790 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d  lite3_errmsg(D)]
117a0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  , and [sqlite3_e
117b0 72 72 6d 73 67 31 36 28 44 29 5d 20 73 68 61 6c  rrmsg16(D)] shal
117c0 6c 20 72 65 74 75 72 6e 0a 69 6e 66 6f 72 6d 61  l return.informa
117d0 74 69 6f 6e 20 61 70 70 72 6f 70 72 69 61 74 65  tion appropriate
117e0 20 66 6f 72 20 74 68 61 74 20 65 72 72 6f 72 2e   for that error.
117f0 0a                                               .