/ Hex Artifact Content
Login

Artifact 73b5c1354e250a12ceaaccc376611351c867146a:


0000: 23 0a 23 20 52 75 6e 20 74 68 69 73 20 54 63 6c  #.# Run this Tcl
0010: 20 73 63 72 69 70 74 20 74 6f 20 67 65 6e 65 72   script to gener
0020: 61 74 65 20 74 68 65 20 73 71 6c 69 74 65 2e 68  ate the sqlite.h
0030: 74 6d 6c 20 66 69 6c 65 2e 0a 23 0a 73 65 74 20  tml file..#.set 
0040: 72 63 73 69 64 20 7b 24 49 64 3a 20 63 5f 69 6e  rcsid {$Id: c_in
0050: 74 65 72 66 61 63 65 2e 74 63 6c 2c 76 20 31 2e  terface.tcl,v 1.
0060: 38 20 32 30 30 30 2f 30 39 2f 32 39 20 31 33 3a  8 2000/09/29 13:
0070: 33 30 3a 35 35 20 64 72 68 20 45 78 70 20 24 7d  30:55 drh Exp $}
0080: 0a 0a 70 75 74 73 20 7b 3c 68 74 6d 6c 3e 0a 3c  ..puts {<html>.<
0090: 68 65 61 64 3e 0a 20 20 3c 74 69 74 6c 65 3e 54  head>.  <title>T
00a0: 68 65 20 43 20 6c 61 6e 67 75 61 67 65 20 69 6e  he C language in
00b0: 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 53  terface to the S
00c0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 3c 2f 74  QLite library</t
00d0: 69 74 6c 65 3e 0a 3c 2f 68 65 61 64 3e 0a 3c 62  itle>.</head>.<b
00e0: 6f 64 79 20 62 67 63 6f 6c 6f 72 3d 77 68 69 74  ody bgcolor=whit
00f0: 65 3e 0a 3c 68 31 20 61 6c 69 67 6e 3d 63 65 6e  e>.<h1 align=cen
0100: 74 65 72 3e 0a 54 68 65 20 43 20 6c 61 6e 67 75  ter>.The C langu
0110: 61 67 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  age interface to
0120: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
0130: 61 72 79 0a 3c 2f 68 31 3e 7d 0a 70 75 74 73 20  ary.</h1>}.puts 
0140: 22 3c 70 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "<p align=center
0150: 3e 0a 28 54 68 69 73 20 70 61 67 65 20 77 61 73  >.(This page was
0160: 20 6c 61 73 74 20 6d 6f 64 69 66 69 65 64 20 6f   last modified o
0170: 6e 20 5b 6c 72 61 6e 67 65 20 24 72 63 73 69 64  n [lrange $rcsid
0180: 20 33 20 34 5d 20 47 4d 54 29 0a 3c 2f 70 3e 22   3 4] GMT).</p>"
0190: 0a 0a 70 75 74 73 20 7b 0a 3c 70 3e 54 68 65 20  ..puts {.<p>The 
01a0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69  SQLite library i
01b0: 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 62 65  s designed to be
01c0: 20 76 65 72 79 20 65 61 73 79 20 74 6f 20 75 73   very easy to us
01d0: 65 20 66 72 6f 6d 0a 61 20 43 20 6f 72 20 43 2b  e from.a C or C+
01e0: 2b 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 69 73  + program.  This
01f0: 20 64 6f 63 75 6d 65 6e 74 20 67 69 76 65 73 20   document gives 
0200: 61 6e 20 6f 76 65 72 76 69 65 77 20 6f 66 20 74  an overview of t
0210: 68 65 20 43 2f 43 2b 2b 0a 70 72 6f 67 72 61 6d  he C/C++.program
0220: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 2e 3c  ming interface.<
0230: 2f 70 3e 0a 0a 3c 68 32 3e 54 68 65 20 41 50 49  /p>..<h2>The API
0240: 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65 20 69 6e  </h2>..<p>The in
0250: 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 53  terface to the S
0260: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 63 6f  QLite library co
0270: 6e 73 69 73 74 73 20 6f 66 20 65 69 67 68 74 20  nsists of eight 
0280: 66 75 6e 63 74 69 6f 6e 73 0a 28 6f 6e 6c 79 20  functions.(only 
0290: 74 68 65 20 66 69 72 73 74 20 74 68 72 65 65 20  the first three 
02a0: 6f 66 20 77 68 69 63 68 20 61 72 65 20 72 65 71  of which are req
02b0: 75 69 72 65 64 29 2c 0a 6f 6e 65 20 6f 70 61 71  uired),.one opaq
02c0: 75 65 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ue data structur
02d0: 65 2c 20 61 6e 64 20 73 6f 6d 65 20 63 6f 6e 73  e, and some cons
02e0: 74 61 6e 74 73 20 75 73 65 64 20 61 73 20 72 65  tants used as re
02f0: 74 75 72 6e 0a 76 61 6c 75 65 73 20 66 72 6f 6d  turn.values from
0300: 20 73 71 6c 69 74 65 5f 65 78 65 63 28 29 3a 3c   sqlite_exec():<
0310: 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  /p>..<blockquote
0320: 3e 3c 70 72 65 3e 0a 74 79 70 65 64 65 66 20 73  ><pre>.typedef s
0330: 74 72 75 63 74 20 73 71 6c 69 74 65 20 73 71 6c  truct sqlite sql
0340: 69 74 65 3b 0a 0a 73 71 6c 69 74 65 20 2a 73 71  ite;..sqlite *sq
0350: 6c 69 74 65 5f 6f 70 65 6e 28 63 6f 6e 73 74 20  lite_open(const 
0360: 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
0370: 69 6e 74 20 6d 6f 64 65 2c 20 63 68 61 72 20 2a  int mode, char *
0380: 2a 65 72 72 6d 73 67 29 3b 0a 0a 76 6f 69 64 20  *errmsg);..void 
0390: 73 71 6c 69 74 65 5f 63 6c 6f 73 65 28 73 71 6c  sqlite_close(sql
03a0: 69 74 65 2a 29 3b 0a 0a 69 6e 74 20 73 71 6c 69  ite*);..int sqli
03b0: 74 65 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74  te_exec(.  sqlit
03c0: 65 2a 2c 0a 20 20 63 68 61 72 20 2a 73 71 6c 2c  e*,.  char *sql,
03d0: 0a 20 20 69 6e 74 20 28 2a 29 28 76 6f 69 64 2a  .  int (*)(void*
03e0: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72  ,int,char**,char
03f0: 2a 2a 29 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  **),.  void*,.  
0400: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 0a 29 3b  char **errmsg.);
0410: 0a 0a 69 6e 74 20 73 71 6c 69 74 65 5f 67 65 74  ..int sqlite_get
0420: 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
0430: 2a 2c 0a 20 20 63 68 61 72 20 2a 73 71 6c 2c 0a  *,.  char *sql,.
0440: 20 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 6c 74    char ***result
0450: 2c 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 0a 20  ,.  int *nrow,. 
0460: 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 0a 20   int *ncolumn,. 
0470: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 0a 29   char **errmsg.)
0480: 3b 0a 0a 76 6f 69 64 20 73 71 6c 69 74 65 5f 66  ;..void sqlite_f
0490: 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 2a 2a  ree_table(char**
04a0: 29 3b 0a 0a 69 6e 74 20 73 71 6c 69 74 65 5f 63  );..int sqlite_c
04b0: 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
04c0: 61 72 20 2a 73 71 6c 29 3b 0a 0a 76 6f 69 64 20  ar *sql);..void 
04d0: 73 71 6c 69 74 65 5f 62 75 73 79 5f 68 61 6e 64  sqlite_busy_hand
04e0: 6c 65 72 28 73 71 6c 69 74 65 2a 2c 20 69 6e 74  ler(sqlite*, int
04f0: 20 28 2a 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74   (*)(void*,const
0500: 20 63 68 61 72 2a 2c 69 6e 74 29 2c 20 76 6f 69   char*,int), voi
0510: 64 2a 29 3b 0a 0a 76 6f 69 64 20 73 71 6c 69 74  d*);..void sqlit
0520: 65 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  e_busy_timeout(s
0530: 71 6c 69 74 65 2a 2c 20 69 6e 74 20 6d 73 29 3b  qlite*, int ms);
0540: 0a 0a 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c  ..const char sql
0550: 69 74 65 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 0a  ite_version[];..
0560: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
0570: 4b 20 20 20 20 20 20 20 20 30 20 20 20 20 2f 2a  K        0    /*
0580: 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75   Successful resu
0590: 6c 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  lt */.#define SQ
05a0: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 31  LITE_INTERNAL  1
05b0: 20 20 20 20 2f 2a 20 41 6e 20 69 6e 74 65 72 6e      /* An intern
05c0: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
05d0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
05e0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
05f0: 20 20 20 20 20 32 20 20 20 20 2f 2a 20 53 51 4c       2    /* SQL
0600: 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e   error or missin
0610: 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  g database */.#d
0620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52  efine SQLITE_PER
0630: 4d 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 41  M      3    /* A
0640: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
0650: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
0660: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
0670: 20 20 20 20 34 20 20 20 20 2f 2a 20 43 61 6c 6c      4    /* Call
0680: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
0690: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
06a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
06b0: 45 5f 42 55 53 59 20 20 20 20 20 20 35 20 20 20  E_BUSY      5   
06c0: 20 2f 2a 20 4f 6e 65 20 6f 72 20 6d 6f 72 65 20   /* One or more 
06d0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 61  database files a
06e0: 72 65 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  re locked */.#de
06f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
0700: 4d 20 20 20 20 20 36 20 20 20 20 2f 2a 20 41 20  M     6    /* A 
0710: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
0720: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0730: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 37 20 20 20  E_READONLY  7   
0740: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
0750: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
0760: 64 61 74 61 62 61 73 65 20 2a 2f 0a 3c 2f 70 72  database */.</pr
0770: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
0780: 0a 3c 70 3e 41 6c 6c 20 6f 66 20 74 68 65 20 61  .<p>All of the a
0790: 62 6f 76 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  bove definitions
07a0: 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e   are included in
07b0: 20 74 68 65 20 22 73 71 6c 69 74 65 2e 68 22 0a   the "sqlite.h".
07c0: 68 65 61 64 65 72 20 66 69 6c 65 20 74 68 61 74  header file that
07d0: 20 63 6f 6d 65 73 20 69 6e 20 74 68 65 20 73 6f   comes in the so
07e0: 75 72 63 65 20 74 72 65 65 2e 3c 2f 70 3e 0a 0a  urce tree.</p>..
07f0: 3c 68 32 3e 4f 70 65 6e 69 6e 67 20 61 20 64 61  <h2>Opening a da
0800: 74 61 62 61 73 65 3c 2f 68 32 3e 0a 0a 3c 70 3e  tabase</h2>..<p>
0810: 55 73 65 20 74 68 65 20 3c 62 3e 73 71 6c 69 74  Use the <b>sqlit
0820: 65 5f 6f 70 65 6e 28 29 3c 2f 62 3e 20 66 75 6e  e_open()</b> fun
0830: 63 74 69 6f 6e 20 74 6f 20 6f 70 65 6e 20 61 6e  ction to open an
0840: 20 65 78 69 73 74 69 6e 67 20 53 51 4c 69 74 65   existing SQLite
0850: 0a 64 61 74 61 62 61 73 65 20 6f 72 20 74 6f 20  .database or to 
0860: 63 72 65 61 74 65 20 61 20 6e 65 77 20 53 51 4c  create a new SQL
0870: 69 74 65 20 64 61 74 61 62 61 73 65 2e 20 20 54  ite database.  T
0880: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
0890: 74 0a 69 73 20 74 68 65 20 64 61 74 61 62 61 73  t.is the databas
08a0: 65 20 6e 61 6d 65 2e 20 20 54 68 65 20 73 65 63  e name.  The sec
08b0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
08c0: 61 20 63 6f 6e 73 74 61 6e 74 20 30 36 36 36 20  a constant 0666 
08d0: 74 6f 0a 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to.open the data
08e0: 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
08f0: 20 61 6e 64 20 77 72 69 74 69 6e 67 20 61 6e 64   and writing and
0900: 20 30 34 34 34 20 74 6f 20 6f 70 65 6e 20 74 68   0444 to open th
0910: 65 0a 64 61 74 61 62 61 73 65 20 72 65 61 64 20  e.database read 
0920: 6f 6e 6c 79 2e 20 20 54 68 65 20 74 68 69 72 64  only.  The third
0930: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
0940: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
0950: 6e 67 0a 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  ng.pointer.  If 
0960: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
0970: 6e 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  nt is not NULL a
0980: 6e 64 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  nd an error occu
0990: 72 73 0a 77 68 69 6c 65 20 74 72 79 69 6e 67 20  rs.while trying 
09a0: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
09b0: 62 61 73 65 2c 20 74 68 65 6e 20 61 6e 20 65 72  base, then an er
09c0: 72 6f 72 20 6d 65 73 73 61 67 65 20 77 69 6c 6c  ror message will
09d0: 20 62 65 0a 77 72 69 74 74 65 6e 20 74 6f 20 6d   be.written to m
09e0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
09f0: 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  rom malloc() and
0a00: 20 2a 65 72 72 6d 73 67 20 77 69 6c 6c 20 62 65   *errmsg will be
0a10: 20 6d 61 64 65 0a 74 6f 20 70 6f 69 6e 74 20 74   made.to point t
0a20: 6f 20 74 68 69 73 20 65 72 72 6f 72 20 6d 65 73  o this error mes
0a30: 73 61 67 65 2e 20 20 54 68 65 20 63 61 6c 6c 69  sage.  The calli
0a40: 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ng function is r
0a50: 65 73 70 6f 6e 73 69 62 6c 65 0a 66 6f 72 20 66  esponsible.for f
0a60: 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72  reeing the memor
0a70: 79 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  y when it has fi
0a80: 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 3c  nished with it.<
0a90: 2f 70 3e 0a 0a 3c 70 3e 41 6e 20 53 51 4c 69 74  /p>..<p>An SQLit
0aa0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6a 75  e database is ju
0ab0: 73 74 20 61 20 64 69 72 65 63 74 6f 72 79 20 63  st a directory c
0ac0: 6f 6e 74 61 69 6e 69 6e 67 20 61 20 63 6f 6c 6c  ontaining a coll
0ad0: 65 63 74 69 6f 6e 20 6f 66 0a 47 44 42 4d 20 66  ection of.GDBM f
0ae0: 69 6c 65 73 2e 20 20 54 68 65 72 65 20 69 73 20  iles.  There is 
0af0: 6f 6e 65 20 47 44 42 4d 20 66 69 6c 65 20 66 6f  one GDBM file fo
0b00: 72 20 65 61 63 68 20 74 61 62 6c 65 20 61 6e 64  r each table and
0b10: 20 69 6e 64 65 78 20 69 6e 20 74 68 65 0a 64 61   index in the.da
0b20: 74 61 62 61 73 65 2e 20 20 41 6c 6c 20 47 44 42  tabase.  All GDB
0b30: 4d 20 66 69 6c 65 73 20 65 6e 64 20 77 69 74 68  M files end with
0b40: 20 74 68 65 20 22 2e 74 62 6c 22 20 73 75 66 66   the ".tbl" suff
0b50: 69 78 2e 20 20 45 76 65 72 79 20 53 51 4c 69 74  ix.  Every SQLit
0b60: 65 0a 64 61 74 61 62 61 73 65 20 61 6c 73 6f 20  e.database also 
0b70: 63 6f 6e 74 61 69 6e 73 20 61 20 73 70 65 63 69  contains a speci
0b80: 61 6c 20 64 61 74 61 62 61 73 65 20 74 61 62 6c  al database tabl
0b90: 65 20 6e 61 6d 65 64 20 3c 62 3e 73 71 6c 69 74  e named <b>sqlit
0ba0: 65 5f 6d 61 73 74 65 72 3c 2f 62 3e 0a 73 74 6f  e_master</b>.sto
0bb0: 72 65 64 20 69 6e 20 69 74 73 20 6f 77 6e 20 47  red in its own G
0bc0: 44 42 4d 20 66 69 6c 65 2e 20 20 54 68 69 73 20  DBM file.  This 
0bd0: 73 70 65 63 69 61 6c 20 74 61 62 6c 65 20 72 65  special table re
0be0: 63 6f 72 64 73 20 74 68 65 20 64 61 74 61 62 61  cords the databa
0bf0: 73 65 0a 73 63 68 65 6d 61 2e 3c 2f 70 3e 0a 0a  se.schema.</p>..
0c00: 3c 70 3e 54 6f 20 63 72 65 61 74 65 20 61 20 6e  <p>To create a n
0c10: 65 77 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  ew SQLite databa
0c20: 73 65 2c 20 61 6c 6c 20 79 6f 75 20 68 61 76 65  se, all you have
0c30: 20 74 6f 20 64 6f 20 69 73 20 63 61 6c 6c 0a 3c   to do is call.<
0c40: 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e 28 29 3c  b>sqlite_open()<
0c50: 2f 62 3e 20 77 69 74 68 20 74 68 65 20 66 69 72  /b> with the fir
0c60: 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  st parameter set
0c70: 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a   to the name of.
0c80: 61 6e 20 65 6d 70 74 79 20 64 69 72 65 63 74 6f  an empty directo
0c90: 72 79 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ry and the secon
0ca0: 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
0cb0: 74 6f 20 30 36 36 36 2e 3c 2f 70 3e 0a 0a 3c 70  to 0666.</p>..<p
0cc0: 3e 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  >The return valu
0cd0: 65 20 6f 66 20 74 68 65 20 3c 62 3e 73 71 6c 69  e of the <b>sqli
0ce0: 74 65 5f 6f 70 65 6e 28 29 3c 2f 62 3e 20 66 75  te_open()</b> fu
0cf0: 6e 63 74 69 6f 6e 20 69 73 20 61 0a 70 6f 69 6e  nction is a.poin
0d00: 74 65 72 20 74 6f 20 61 6e 20 6f 70 61 71 75 65  ter to an opaque
0d10: 20 3c 62 3e 73 71 6c 69 74 65 3c 2f 62 3e 20 73   <b>sqlite</b> s
0d20: 74 72 75 63 74 75 72 65 2e 20 20 54 68 69 73 20  tructure.  This 
0d30: 70 6f 69 6e 74 65 72 20 77 69 6c 6c 0a 62 65 20  pointer will.be 
0d40: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
0d50: 6e 74 20 74 6f 20 61 6c 6c 20 73 75 62 73 65 71  nt to all subseq
0d60: 75 65 6e 74 20 53 51 4c 69 74 65 20 66 75 6e 63  uent SQLite func
0d70: 74 69 6f 6e 20 63 61 6c 6c 73 20 74 68 61 74 0a  tion calls that.
0d80: 64 65 61 6c 20 77 69 74 68 20 74 68 65 20 73 61  deal with the sa
0d90: 6d 65 20 64 61 74 61 62 61 73 65 2e 20 20 4e 55  me database.  NU
0da0: 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  LL is returned i
0db0: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
0dc0: 0a 66 6f 72 20 61 6e 79 20 72 65 61 73 6f 6e 2e  .for any reason.
0dd0: 3c 2f 70 3e 0a 0a 3c 68 32 3e 43 6c 6f 73 69 6e  </p>..<h2>Closin
0de0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 3c 2f  g the database</
0df0: 68 32 3e 0a 0a 3c 70 3e 54 6f 20 63 6c 6f 73 65  h2>..<p>To close
0e00: 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
0e10: 61 73 65 2c 20 63 61 6c 6c 20 74 68 65 20 3c 62  ase, call the <b
0e20: 3e 73 71 6c 69 74 65 5f 63 6c 6f 73 65 28 29 3c  >sqlite_close()<
0e30: 2f 62 3e 0a 66 75 6e 63 74 69 6f 6e 20 70 61 73  /b>.function pas
0e40: 73 69 6e 67 20 69 74 20 74 68 65 20 73 71 6c 69  sing it the sqli
0e50: 74 65 20 73 74 72 75 63 74 75 72 65 20 70 6f 69  te structure poi
0e60: 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 6f 62  nter that was ob
0e70: 74 61 69 6e 65 64 0a 66 72 6f 6d 20 61 20 70 72  tained.from a pr
0e80: 69 6f 72 20 63 61 6c 6c 20 74 6f 20 3c 62 3e 73  ior call to <b>s
0e90: 71 6c 69 74 65 5f 6f 70 65 6e 3c 2f 62 3e 2e 0a  qlite_open</b>..
0ea0: 0a 3c 68 32 3e 45 78 65 63 75 74 69 6e 67 20 53  .<h2>Executing S
0eb0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 3c 2f 68  QL statements</h
0ec0: 32 3e 0a 0a 3c 70 3e 54 68 65 20 3c 62 3e 73 71  2>..<p>The <b>sq
0ed0: 6c 69 74 65 5f 65 78 65 63 28 29 3c 2f 62 3e 20  lite_exec()</b> 
0ee0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
0ef0: 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
0f00: 73 74 61 74 65 6d 65 6e 74 73 0a 61 6e 64 20 71  statements.and q
0f10: 75 65 72 69 65 73 2e 20 20 54 68 69 73 20 66 75  ueries.  This fu
0f20: 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
0f30: 35 20 70 61 72 61 6d 65 74 65 72 73 20 61 73 20  5 parameters as 
0f40: 66 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c 6f  follows:</p>..<o
0f50: 6c 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 70 6f 69 6e  l>.<li><p>A poin
0f60: 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
0f70: 65 20 73 74 72 75 63 74 75 72 65 20 6f 62 74 61  e structure obta
0f80: 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
0f90: 72 20 63 61 6c 6c 0a 20 20 20 20 20 20 20 74 6f  r call.       to
0fa0: 20 3c 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e 28   <b>sqlite_open(
0fb0: 29 3c 2f 62 3e 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a  )</b>.</p></li>.
0fc0: 3c 6c 69 3e 3c 70 3e 41 20 6e 75 6c 6c 2d 74 65  <li><p>A null-te
0fd0: 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20  rminated string 
0fe0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74  containing the t
0ff0: 65 78 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ext of one or mo
1000: 72 65 0a 20 20 20 20 20 20 20 53 51 4c 20 73 74  re.       SQL st
1010: 61 74 65 6d 65 6e 74 73 20 61 6e 64 2f 6f 72 20  atements and/or 
1020: 71 75 65 72 69 65 73 20 74 6f 20 62 65 20 70 72  queries to be pr
1030: 6f 63 65 73 73 65 64 2e 3c 2f 70 3e 3c 2f 6c 69  ocessed.</p></li
1040: 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 70 6f 69 6e 74  >.<li><p>A point
1050: 65 72 20 74 6f 20 61 20 63 61 6c 6c 62 61 63 6b  er to a callback
1060: 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63 68 20   function which 
1070: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20  is invoked once 
1080: 66 6f 72 20 65 61 63 68 0a 20 20 20 20 20 20 20  for each.       
1090: 72 6f 77 20 69 6e 20 74 68 65 20 72 65 73 75 6c  row in the resul
10a0: 74 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 54  t of a query.  T
10b0: 68 69 73 20 61 72 67 75 6d 65 6e 74 20 6d 61 79  his argument may
10c0: 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69   be NULL, in whi
10d0: 63 68 0a 20 20 20 20 20 20 20 63 61 73 65 20 6e  ch.       case n
10e0: 6f 20 63 61 6c 6c 62 61 63 6b 73 20 77 69 6c 6c  o callbacks will
10f0: 20 65 76 65 72 20 62 65 20 69 6e 76 6f 6b 65 64   ever be invoked
1100: 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c  .</p></li>.<li><
1110: 70 3e 41 20 70 6f 69 6e 74 65 72 20 74 68 61 74  p>A pointer that
1120: 20 69 73 20 66 6f 72 77 61 72 64 65 64 20 74 6f   is forwarded to
1130: 20 62 65 63 6f 6d 65 20 74 68 65 20 66 69 72 73   become the firs
1140: 74 20 61 72 67 75 6d 65 6e 74 0a 20 20 20 20 20  t argument.     
1150: 20 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63    to the callbac
1160: 6b 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 70 3e 3c  k function.</p><
1170: 2f 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 70 6f  /li>.<li><p>A po
1180: 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 72 72 6f  inter to an erro
1190: 72 20 73 74 72 69 6e 67 2e 20 20 45 72 72 6f 72  r string.  Error
11a0: 20 6d 65 73 73 61 67 65 73 20 61 72 65 20 77 72   messages are wr
11b0: 69 74 74 65 6e 20 74 6f 20 73 70 61 63 65 0a 20  itten to space. 
11c0: 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66        obtained f
11d0: 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  rom malloc() and
11e0: 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
11f0: 67 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  g is made to poi
1200: 6e 74 20 74 6f 0a 20 20 20 20 20 20 20 74 68 65  nt to.       the
1210: 20 6d 61 6c 6c 6f 63 65 64 20 73 70 61 63 65 2e   malloced space.
1220: 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75    The calling fu
1230: 6e 63 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  nction is respon
1240: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
1250: 67 0a 20 20 20 20 20 20 20 74 68 69 73 20 73 70  g.       this sp
1260: 61 63 65 20 77 68 65 6e 20 69 74 20 68 61 73 20  ace when it has 
1270: 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
1280: 2e 0a 20 20 20 20 20 20 20 54 68 69 73 20 61 72  ..       This ar
1290: 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55  gument may be NU
12a0: 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  LL, in which cas
12b0: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73  e error messages
12c0: 20 61 72 65 20 6e 6f 74 0a 20 20 20 20 20 20 20   are not.       
12d0: 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 74 6f  reported back to
12e0: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
12f0: 63 74 69 6f 6e 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a  ction.</p></li>.
1300: 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 0a 54 68 65 20 63  </ol>..<p>.The c
1310: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1320: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 63 65   is used to rece
1330: 69 76 65 20 74 68 65 20 72 65 73 75 6c 74 73 20  ive the results 
1340: 6f 66 20 61 20 71 75 65 72 79 2e 20 20 41 0a 70  of a query.  A.p
1350: 72 6f 74 6f 74 79 70 65 20 66 6f 72 20 74 68 65  rototype for the
1360: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1370: 6f 6e 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  on is as follows
1380: 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  :</p>..<blockquo
1390: 74 65 3e 3c 70 72 65 3e 0a 69 6e 74 20 43 61 6c  te><pre>.int Cal
13a0: 6c 62 61 63 6b 28 76 6f 69 64 20 2a 70 41 72 67  lback(void *pArg
13b0: 2c 20 69 6e 74 20 61 72 67 63 2c 20 63 68 61 72  , int argc, char
13c0: 20 2a 2a 61 72 67 76 2c 20 63 68 61 72 20 2a 2a   **argv, char **
13d0: 63 6f 6c 75 6d 6e 4e 61 6d 65 73 29 7b 0a 20 20  columnNames){.  
13e0: 72 65 74 75 72 6e 20 30 3b 0a 7d 0a 3c 2f 70 72  return 0;.}.</pr
13f0: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1400: 0a 3c 70 3e 54 68 65 20 66 69 72 73 74 20 61 72  .<p>The first ar
1410: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
1420: 6c 6c 62 61 63 6b 20 69 73 20 6a 75 73 74 20 61  llback is just a
1430: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75   copy of the fou
1440: 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 74 6f 20  rth argument.to 
1450: 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 28 29  <b>sqlite_exec()
1460: 3c 2f 62 3e 20 20 54 68 69 73 20 70 61 72 61 6d  </b>  This param
1470: 65 74 65 72 20 63 61 6e 20 62 65 20 75 73 65 64  eter can be used
1480: 20 74 6f 20 70 61 73 73 20 61 72 62 69 74 72 61   to pass arbitra
1490: 72 79 0a 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 74  ry.information t
14a0: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61  hrough to the ca
14b0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
14c0: 66 72 6f 6d 20 63 6c 69 65 6e 74 20 63 6f 64 65  from client code
14d0: 2e 0a 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  ..The second arg
14e0: 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
14f0: 62 65 72 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74  ber columns in t
1500: 68 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 2e  he query result.
1510: 0a 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  .The third argum
1520: 65 6e 74 20 69 73 20 61 6e 20 61 72 72 61 79 20  ent is an array 
1530: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
1540: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
1550: 68 20 73 74 72 69 6e 67 0a 69 73 20 61 20 73 69  h string.is a si
1560: 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
1570: 68 65 20 72 65 73 75 6c 74 20 66 6f 72 20 74 68  he result for th
1580: 61 74 20 72 65 63 6f 72 64 2e 20 20 4e 6f 74 65  at record.  Note
1590: 20 74 68 61 74 20 74 68 65 0a 63 61 6c 6c 62 61   that the.callba
15a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6f  ck function repo
15b0: 72 74 73 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  rts a NULL value
15c0: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
15d0: 20 61 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   as a NULL point
15e0: 65 72 2c 0a 77 68 69 63 68 20 69 73 20 76 65 72  er,.which is ver
15f0: 79 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  y different from
1600: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1610: 2e 20 20 49 66 20 74 68 65 20 69 2d 74 68 20 70  .  If the i-th p
1620: 61 72 61 6d 65 74 65 72 0a 69 73 20 61 6e 20 65  arameter.is an e
1630: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 77 65 20  mpty string, we 
1640: 77 69 6c 6c 20 67 65 74 3a 3c 2f 70 3e 0a 3c 62  will get:</p>.<b
1650: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1660: 61 72 67 76 5b 69 5d 5b 30 5d 20 3d 3d 20 30 0a  argv[i][0] == 0.
1670: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1680: 74 65 3e 0a 3c 70 3e 42 75 74 20 69 66 20 74 68  te>.<p>But if th
1690: 65 20 69 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e i-th parameter
16a0: 20 69 73 20 4e 55 4c 4c 20 77 65 20 77 69 6c 6c   is NULL we will
16b0: 20 67 65 74 3a 3c 2f 70 3e 0a 3c 62 6c 6f 63 6b   get:</p>.<block
16c0: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 61 72 67 76  quote><pre>.argv
16d0: 5b 69 5d 20 3d 3d 20 30 0a 3c 2f 70 72 65 3e 3c  [i] == 0.</pre><
16e0: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 70 3e  /blockquote>.<p>
16f0: 54 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  The names of the
1700: 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20 63 6f 6e   columns are con
1710: 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 6f  tained in the fo
1720: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2e 3c 2f  urth argument.</
1730: 70 3e 0a 0a 3c 70 3e 54 68 65 20 63 61 6c 6c 62  p>..<p>The callb
1740: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
1750: 75 6c 64 20 6e 6f 72 6d 61 6c 6c 79 20 72 65 74  uld normally ret
1760: 75 72 6e 20 30 2e 20 20 49 66 20 74 68 65 20 63  urn 0.  If the c
1770: 61 6c 6c 62 61 63 6b 0a 66 75 6e 63 74 69 6f 6e  allback.function
1780: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1790: 6f 2c 20 74 68 65 20 71 75 65 72 79 20 69 73 20  o, the query is 
17a0: 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 62 6f 72  immediately abor
17b0: 74 65 64 20 61 6e 64 20 0a 3c 62 3e 73 71 6c 69  ted and .<b>sqli
17c0: 74 65 5f 65 78 65 63 28 29 3c 2f 62 3e 20 77 69  te_exec()</b> wi
17d0: 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
17e0: 5f 41 42 4f 52 54 2e 3c 2f 70 3e 0a 0a 3c 70 3e  _ABORT.</p>..<p>
17f0: 54 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78  The <b>sqlite_ex
1800: 65 63 28 29 3c 2f 62 3e 20 66 75 6e 63 74 69 6f  ec()</b> functio
1810: 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  n returns an int
1820: 65 67 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  eger to indicate
1830: 0a 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c  .success or fail
1840: 75 72 65 20 6f 66 20 74 68 65 20 6f 70 65 72 61  ure of the opera
1850: 74 69 6f 6e 2e 20 20 54 68 65 20 66 6f 6c 6c 6f  tion.  The follo
1860: 77 69 6e 67 20 61 72 65 20 70 6f 73 73 69 62 6c  wing are possibl
1870: 65 0a 72 65 74 75 72 6e 20 76 61 6c 75 65 73 3a  e.return values:
1880: 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  </p>..<blockquot
1890: 65 3e 0a 3c 64 6c 3e 0a 3c 64 74 3e 53 51 4c 49  e>.<dl>.<dt>SQLI
18a0: 54 45 5f 4f 4b 3c 2f 64 74 3e 0a 3c 64 64 3e 3c  TE_OK</dt>.<dd><
18b0: 70 3e 54 68 69 73 20 76 61 6c 75 65 20 69 73 20  p>This value is 
18c0: 72 65 74 75 72 6e 65 64 20 69 66 20 65 76 65 72  returned if ever
18d0: 79 74 68 69 6e 67 20 77 6f 72 6b 65 64 20 61 6e  ything worked an
18e0: 64 20 74 68 65 72 65 20 77 65 72 65 20 6e 6f 20  d there were no 
18f0: 65 72 72 6f 72 73 2e 0a 3c 2f 70 3e 3c 2f 64 64  errors..</p></dd
1900: 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 49 4e 54  >.<dt>SQLITE_INT
1910: 45 52 4e 41 4c 3c 2f 64 74 3e 0a 3c 64 64 3e 3c  ERNAL</dt>.<dd><
1920: 70 3e 54 68 69 73 20 76 61 6c 75 65 20 69 6e 64  p>This value ind
1930: 69 63 61 74 65 73 20 74 68 61 74 20 61 6e 20 69  icates that an i
1940: 6e 74 65 72 6e 61 6c 20 63 6f 6e 73 69 73 74 65  nternal consiste
1950: 6e 63 79 20 63 68 65 63 6b 20 77 69 74 68 69 6e  ncy check within
1960: 0a 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72  .the SQLite libr
1970: 61 72 79 20 66 61 69 6c 65 64 2e 20 20 54 68 69  ary failed.  Thi
1980: 73 20 63 61 6e 20 6f 6e 6c 79 20 68 61 70 70 65  s can only happe
1990: 6e 20 69 66 20 74 68 65 72 65 20 69 73 20 61 20  n if there is a 
19a0: 62 75 67 20 69 6e 0a 74 68 65 20 53 51 4c 69 74  bug in.the SQLit
19b0: 65 20 6c 69 62 72 61 72 79 2e 20 20 49 66 20 79  e library.  If y
19c0: 6f 75 20 65 76 65 72 20 67 65 74 20 61 6e 20 53  ou ever get an S
19d0: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 72  QLITE_INTERNAL r
19e0: 65 70 6c 79 20 66 72 6f 6d 0a 61 6e 20 3c 62 3e  eply from.an <b>
19f0: 73 71 6c 69 74 65 5f 65 78 65 63 28 29 3c 2f 62  sqlite_exec()</b
1a00: 3e 20 63 61 6c 6c 2c 20 70 6c 65 61 73 65 20 72  > call, please r
1a10: 65 70 6f 72 74 20 74 68 65 20 70 72 6f 62 6c 65  eport the proble
1a20: 6d 20 6f 6e 20 74 68 65 20 53 51 4c 69 74 65 0a  m on the SQLite.
1a30: 6d 61 69 6c 69 6e 67 20 6c 69 73 74 2e 0a 3c 2f  mailing list..</
1a40: 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49  p></dd>.<dt>SQLI
1a50: 54 45 5f 45 52 52 4f 52 3c 2f 64 74 3e 0a 3c 64  TE_ERROR</dt>.<d
1a60: 64 3e 3c 70 3e 54 68 69 73 20 72 65 74 75 72 6e  d><p>This return
1a70: 20 76 61 6c 75 65 20 69 6e 64 69 63 61 74 65 73   value indicates
1a80: 20 74 68 61 74 20 74 68 65 72 65 20 77 61 73 20   that there was 
1a90: 61 6e 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20  an error in the 
1aa0: 53 51 4c 0a 74 68 61 74 20 77 61 73 20 70 61 73  SQL.that was pas
1ab0: 73 65 64 20 69 6e 74 6f 20 74 68 65 20 3c 62 3e  sed into the <b>
1ac0: 73 71 6c 69 74 65 5f 65 78 65 63 28 29 3c 2f 62  sqlite_exec()</b
1ad0: 3e 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74  >..</p></dd>.<dt
1ae0: 3e 53 51 4c 49 54 45 5f 50 45 52 4d 3c 2f 64 74  >SQLITE_PERM</dt
1af0: 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 72 65  >.<dd><p>This re
1b00: 74 75 72 6e 20 76 61 6c 75 65 20 73 61 79 73 20  turn value says 
1b10: 74 68 61 74 20 74 68 65 20 61 63 63 65 73 73 20  that the access 
1b20: 70 65 72 6d 69 73 73 69 6f 6e 73 20 6f 6e 20 6f  permissions on o
1b30: 6e 65 20 6f 66 20 74 68 65 0a 47 44 42 4d 20 66  ne of the.GDBM f
1b40: 69 6c 65 73 20 69 73 20 73 75 63 68 20 74 68 61  iles is such tha
1b50: 74 20 74 68 65 20 66 69 6c 65 20 63 61 6e 6e 6f  t the file canno
1b60: 74 20 62 65 20 6f 70 65 6e 65 64 2e 0a 3c 2f 70  t be opened..</p
1b70: 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54  ></dd>.<dt>SQLIT
1b80: 45 5f 41 42 4f 52 54 3c 2f 64 74 3e 0a 3c 64 64  E_ABORT</dt>.<dd
1b90: 3e 3c 70 3e 54 68 69 73 20 76 61 6c 75 65 20 69  ><p>This value i
1ba0: 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
1bb0: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1bc0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ion returns non-
1bd0: 7a 65 72 6f 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a  zero..</p></dd>.
1be0: 3c 64 74 3e 53 51 4c 49 54 45 5f 42 55 53 59 3c  <dt>SQLITE_BUSY<
1bf0: 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73  /dt>.<dd><p>This
1c00: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 69 6e 64   return code ind
1c10: 69 63 61 74 65 73 20 74 68 61 74 20 6f 6e 65 20  icates that one 
1c20: 6f 66 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  of the underlyin
1c30: 67 20 47 44 42 4d 20 66 69 6c 65 73 0a 69 73 20  g GDBM files.is 
1c40: 6c 6f 63 6b 65 64 20 62 65 63 61 75 73 65 20 69  locked because i
1c50: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 62  t is currently b
1c60: 65 69 6e 67 20 61 63 63 65 73 73 65 64 20 62 79  eing accessed by
1c70: 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
1c80: 6f 72 0a 70 72 6f 63 65 73 73 2e 20 20 47 44 42  or.process.  GDB
1c90: 4d 20 61 6c 6c 6f 77 73 20 6d 75 74 69 70 6c 65  M allows mutiple
1ca0: 20 72 65 61 64 65 72 73 20 6f 66 20 74 68 65 20   readers of the 
1cb0: 73 61 6d 65 20 66 69 6c 65 2c 20 62 75 74 20 6f  same file, but o
1cc0: 6e 6c 79 20 6f 6e 65 0a 77 72 69 74 65 72 2e 20  nly one.writer. 
1cd0: 20 53 6f 20 6d 75 6c 74 69 70 6c 65 20 70 72 6f   So multiple pro
1ce0: 63 65 73 73 65 73 20 63 61 6e 20 71 75 65 72 79  cesses can query
1cf0: 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
1d00: 61 73 65 20 61 74 20 6f 6e 63 65 2e 0a 42 75 74  ase at once..But
1d10: 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70   only a single p
1d20: 72 6f 63 65 73 73 20 63 61 6e 20 77 72 69 74 65  rocess can write
1d30: 20 74 6f 20 61 6e 20 53 51 4c 69 74 65 20 64 61   to an SQLite da
1d40: 74 61 62 61 73 65 20 61 74 20 6f 6e 65 20 74 69  tabase at one ti
1d50: 6d 65 2e 0a 49 66 20 61 6e 20 61 74 74 65 6d 70  me..If an attemp
1d60: 74 20 69 73 20 6d 61 64 65 20 74 6f 20 77 72 69  t is made to wri
1d70: 74 65 20 74 6f 20 61 6e 20 53 51 4c 69 74 65 20  te to an SQLite 
1d80: 64 61 74 61 62 61 73 65 20 74 68 61 74 20 61 6e  database that an
1d90: 6f 74 68 65 72 0a 70 72 6f 63 65 73 73 20 69 73  other.process is
1da0: 20 63 75 72 72 65 6e 74 6c 79 20 72 65 61 64 69   currently readi
1db0: 6e 67 2c 20 74 68 65 20 77 72 69 74 65 20 69 73  ng, the write is
1dc0: 20 6e 6f 74 20 70 65 72 66 6f 72 6d 65 64 20 61   not performed a
1dd0: 6e 64 20 0a 3c 62 3e 73 71 6c 69 74 65 5f 65 78  nd .<b>sqlite_ex
1de0: 65 63 28 29 3c 2f 62 3e 20 72 65 74 75 72 6e 73  ec()</b> returns
1df0: 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 53   SQLITE_BUSY.  S
1e00: 69 6d 69 6c 61 72 6c 79 2c 20 61 6e 20 61 74 74  imilarly, an att
1e10: 65 6d 70 74 20 74 6f 20 72 65 61 64 0a 61 6e 20  empt to read.an 
1e20: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
1e30: 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
1e40: 79 20 62 65 69 6e 67 20 77 72 69 74 74 65 6e 20  y being written 
1e50: 62 79 20 61 6e 6f 74 68 65 72 20 70 72 6f 63 65  by another proce
1e60: 73 73 0a 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  ss.will return S
1e70: 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 49 6e 20  QLITE_BUSY.  In 
1e80: 62 6f 74 68 20 63 61 73 65 73 2c 20 74 68 65 20  both cases, the 
1e90: 77 72 69 74 65 20 6f 72 20 71 75 65 72 79 20 61  write or query a
1ea0: 74 74 65 6d 70 74 0a 63 61 6e 20 62 65 20 72 65  ttempt.can be re
1eb0: 74 72 69 65 64 20 61 66 74 65 72 20 74 68 65 20  tried after the 
1ec0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 20 66 69  other process fi
1ed0: 6e 69 73 68 65 73 2e 3c 2f 70 3e 0a 3c 70 3e 4e  nishes.</p>.<p>N
1ee0: 6f 74 65 20 74 68 61 74 20 6c 6f 63 6b 69 6e 67  ote that locking
1ef0: 20 69 73 20 64 6f 6e 65 20 61 74 20 74 68 65 20   is done at the 
1f00: 66 69 6c 65 20 6c 65 76 65 6c 2e 20 20 4f 6e 65  file level.  One
1f10: 20 70 72 6f 63 65 73 73 20 63 61 6e 0a 77 72 69   process can.wri
1f20: 74 65 20 74 6f 20 74 61 62 6c 65 20 41 42 43 20  te to table ABC 
1f30: 28 66 6f 72 20 65 78 61 6d 70 6c 65 29 20 77 68  (for example) wh
1f40: 69 6c 65 20 61 6e 6f 74 68 65 72 20 70 72 6f 63  ile another proc
1f50: 65 73 73 20 73 69 6d 75 6c 74 61 6e 65 6f 75 73  ess simultaneous
1f60: 6c 79 0a 72 65 61 64 73 20 66 72 6f 6d 20 61 20  ly.reads from a 
1f70: 64 69 66 66 65 72 65 6e 74 20 74 61 62 6c 65 20  different table 
1f80: 58 59 5a 2e 20 20 42 75 74 20 79 6f 75 20 63 61  XYZ.  But you ca
1f90: 6e 6e 6f 74 20 68 61 76 65 20 74 77 6f 20 70 72  nnot have two pr
1fa0: 6f 63 65 73 73 65 73 20 72 65 61 64 69 6e 67 0a  ocesses reading.
1fb0: 61 6e 64 20 77 72 69 74 69 6e 67 20 74 61 62 6c  and writing tabl
1fc0: 65 20 41 42 43 20 61 74 20 74 68 65 20 73 61 6d  e ABC at the sam
1fd0: 65 20 74 69 6d 65 2e 0a 3c 2f 70 3e 3c 2f 64 64  e time..</p></dd
1fe0: 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 4e 4f 4d  >.<dt>SQLITE_NOM
1ff0: 45 4d 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54  EM</dt>.<dd><p>T
2000: 68 69 73 20 76 61 6c 75 65 20 69 73 20 72 65 74  his value is ret
2010: 75 72 6e 65 64 20 69 66 20 61 20 63 61 6c 6c 20  urned if a call 
2020: 74 6f 20 3c 62 3e 6d 61 6c 6c 6f 63 28 29 3c 2f  to <b>malloc()</
2030: 62 3e 20 66 61 69 6c 73 2e 0a 3c 2f 70 3e 3c 2f  b> fails..</p></
2040: 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 52  dd>.<dt>SQLITE_R
2050: 45 41 44 4f 4e 4c 59 3c 2f 64 74 3e 0a 3c 64 64  EADONLY</dt>.<dd
2060: 3e 3c 70 3e 54 68 69 73 20 72 65 74 75 72 6e 20  ><p>This return 
2070: 63 6f 64 65 20 69 6e 64 69 63 61 74 65 73 20 74  code indicates t
2080: 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 77  hat an attempt w
2090: 61 73 20 6d 61 64 65 20 74 6f 20 77 72 69 74 65  as made to write
20a0: 20 74 6f 0a 61 20 64 61 74 61 62 61 73 65 20 66   to.a database f
20b0: 69 6c 65 20 74 68 61 74 20 77 61 73 20 6f 72 69  ile that was ori
20c0: 67 69 6e 61 6c 6c 79 20 6f 70 65 6e 65 64 20 66  ginally opened f
20d0: 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e  or reading only.
20e0: 20 20 54 68 69 73 20 63 61 6e 0a 68 61 70 70 65    This can.happe
20f0: 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63  n if the callbac
2100: 6b 20 66 72 6f 6d 20 61 20 71 75 65 72 79 20 61  k from a query a
2110: 74 74 65 6d 70 74 73 20 74 6f 20 75 70 64 61 74  ttempts to updat
2120: 65 20 74 68 65 20 74 61 62 6c 65 0a 62 65 69 6e  e the table.bein
2130: 67 20 71 75 65 72 69 65 64 2e 0a 3c 2f 70 3e 3c  g queried..</p><
2140: 2f 64 64 3e 0a 3c 2f 64 6c 3e 0a 3c 2f 62 6c 6f  /dd>.</dl>.</blo
2150: 63 6b 71 75 6f 74 65 3e 0a 0a 3c 68 32 3e 51 75  ckquote>..<h2>Qu
2160: 65 72 79 69 6e 67 20 77 69 74 68 6f 75 74 20 75  erying without u
2170: 73 69 6e 67 20 61 20 63 61 6c 6c 62 61 63 6b 20  sing a callback 
2180: 66 75 6e 63 74 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c  function</h2>..<
2190: 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f  p>The <b>sqlite_
21a0: 67 65 74 5f 74 61 62 6c 65 28 29 3c 2f 62 3e 20  get_table()</b> 
21b0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 77 72  function is a wr
21c0: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 3c 62 3e  apper around.<b>
21d0: 73 71 6c 69 74 65 5f 65 78 65 63 28 29 3c 2f 62  sqlite_exec()</b
21e0: 3e 20 74 68 61 74 20 63 6f 6c 6c 65 63 74 73 20  > that collects 
21f0: 61 6c 6c 20 74 68 65 20 69 6e 66 6f 72 6d 61 74  all the informat
2200: 69 6f 6e 20 66 72 6f 6d 20 73 75 63 63 65 73 73  ion from success
2210: 69 76 65 0a 63 61 6c 6c 62 61 63 6b 73 20 61 6e  ive.callbacks an
2220: 64 20 77 72 69 74 65 20 69 74 20 69 6e 74 6f 20  d write it into 
2230: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
2240: 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 2e 20 20  from malloc().  
2250: 54 68 69 73 0a 69 73 20 61 20 63 6f 6e 76 65 6e  This.is a conven
2260: 69 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 74  ience function t
2270: 68 61 74 20 61 6c 6c 6f 77 73 20 74 68 65 20 61  hat allows the a
2280: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 67 65  pplication to ge
2290: 74 20 74 68 65 0a 65 6e 74 69 72 65 20 72 65 73  t the.entire res
22a0: 75 6c 74 20 6f 66 20 61 20 64 61 74 61 62 61 73  ult of a databas
22b0: 65 20 71 75 65 72 79 20 77 69 74 68 20 61 20 73  e query with a s
22c0: 69 6e 67 6c 65 20 66 75 6e 63 74 69 6f 6e 20 63  ingle function c
22d0: 61 6c 6c 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65  all.</p>..<p>The
22e0: 20 6d 61 69 6e 20 72 65 73 75 6c 74 20 66 72 6f   main result fro
22f0: 6d 20 3c 62 3e 73 71 6c 69 74 65 5f 67 65 74 5f  m <b>sqlite_get_
2300: 74 61 62 6c 65 28 29 3c 2f 62 3e 20 69 73 20 61  table()</b> is a
2310: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
2320: 65 72 73 0a 74 6f 20 73 74 72 69 6e 67 73 2e 20  ers.to strings. 
2330: 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 65 6c   There is one el
2340: 65 6d 65 6e 74 20 69 6e 20 74 68 69 73 20 61 72  ement in this ar
2350: 72 61 79 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  ray for each col
2360: 75 6d 6e 20 6f 66 0a 65 61 63 68 20 72 6f 77 20  umn of.each row 
2370: 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  in the result.  
2380: 4e 55 4c 4c 20 72 65 73 75 6c 74 73 20 61 72 65  NULL results are
2390: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
23a0: 61 20 4e 55 4c 4c 0a 70 6f 69 6e 74 65 72 2e 20  a NULL.pointer. 
23b0: 49 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 74  In addition to t
23c0: 68 65 20 72 65 67 75 6c 61 72 20 64 61 74 61 2c  he regular data,
23d0: 20 74 68 65 72 65 20 69 73 20 61 6e 20 61 64 64   there is an add
23e0: 65 64 20 72 6f 77 20 61 74 20 74 68 65 20 0a 62  ed row at the .b
23f0: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 74 68 65 20  eginning of the 
2400: 61 72 72 61 79 20 74 68 61 74 20 63 6f 6e 74 61  array that conta
2410: 69 6e 73 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ins the names of
2420: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 6f 66 20   each column of 
2430: 74 68 65 0a 72 65 73 75 6c 74 2e 3c 2f 70 3e 0a  the.result.</p>.
2440: 0a 3c 70 3e 41 73 20 61 6e 20 65 78 61 6d 70 6c  .<p>As an exampl
2450: 65 2c 20 63 6f 6e 73 69 64 65 72 20 74 68 65 20  e, consider the 
2460: 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 3a  following query:
2470: 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  </p>..<blockquot
2480: 65 3e 0a 53 45 4c 45 43 54 20 65 6d 70 6c 6f 79  e>.SELECT employ
2490: 65 65 5f 6e 61 6d 65 2c 20 6c 6f 67 69 6e 2c 20  ee_name, login, 
24a0: 68 6f 73 74 20 46 52 4f 4d 20 75 73 65 72 73 20  host FROM users 
24b0: 57 48 45 52 45 20 6c 6f 67 69 63 20 4c 49 4b 45  WHERE logic LIKE
24c0: 20 27 64 25 27 3b 0a 3c 2f 62 6c 6f 63 6b 71 75   'd%';.</blockqu
24d0: 6f 74 65 3e 0a 0a 3c 70 3e 54 68 69 73 20 71 75  ote>..<p>This qu
24e0: 65 72 79 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ery will return 
24f0: 74 68 65 20 6e 61 6d 65 2c 20 6c 6f 67 69 6e 20  the name, login 
2500: 61 6e 64 20 68 6f 73 74 20 63 6f 6d 70 75 74 65  and host compute
2510: 72 20 6e 61 6d 65 0a 66 6f 72 20 65 76 65 72 79  r name.for every
2520: 20 65 6d 70 6c 6f 79 65 65 20 77 68 6f 73 65 20   employee whose 
2530: 6c 6f 67 69 6e 20 62 65 67 69 6e 73 20 77 69 74  login begins wit
2540: 68 20 74 68 65 20 6c 65 74 74 65 72 20 22 64 22  h the letter "d"
2550: 2e 20 20 49 66 20 74 68 69 73 0a 71 75 65 72 79  .  If this.query
2560: 20 69 73 20 73 75 62 6d 69 74 74 65 64 20 74 6f   is submitted to
2570: 20 3c 62 3e 73 71 6c 69 74 65 5f 67 65 74 5f 74   <b>sqlite_get_t
2580: 61 62 6c 65 28 29 3c 2f 62 3e 20 74 68 65 20 72  able()</b> the r
2590: 65 73 75 6c 74 20 6d 69 67 68 74 0a 6c 6f 6f 6b  esult might.look
25a0: 20 6c 69 6b 65 20 74 68 69 73 3a 3c 2f 70 3e 0a   like this:</p>.
25b0: 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 6e 72  .<blockquote>.nr
25c0: 6f 77 20 3d 20 32 3c 62 72 3e 0a 6e 63 6f 6c 75  ow = 2<br>.ncolu
25d0: 6d 6e 20 3d 20 33 3c 62 72 3e 0a 72 65 73 75 6c  mn = 3<br>.resul
25e0: 74 5b 30 5d 20 3d 20 22 65 6d 70 6c 6f 79 65 65  t[0] = "employee
25f0: 5f 6e 61 6d 65 22 3c 62 72 3e 0a 72 65 73 75 6c  _name"<br>.resul
2600: 74 5b 31 5d 20 3d 20 22 6c 6f 67 69 6e 22 3c 62  t[1] = "login"<b
2610: 72 3e 0a 72 65 73 75 6c 74 5b 32 5d 20 3d 20 22  r>.result[2] = "
2620: 68 6f 73 74 22 3c 62 72 3e 0a 72 65 73 75 6c 74  host"<br>.result
2630: 5b 33 5d 20 3d 20 22 64 75 6d 6d 79 22 3c 62 72  [3] = "dummy"<br
2640: 3e 0a 72 65 73 75 6c 74 5b 34 5d 20 3d 20 22 4e  >.result[4] = "N
2650: 6f 20 73 75 63 68 20 75 73 65 72 22 3c 62 72 3e  o such user"<br>
2660: 0a 72 65 73 75 6c 74 5b 35 5d 20 3d 20 30 3c 62  .result[5] = 0<b
2670: 72 3e 0a 72 65 73 75 6c 74 5b 36 5d 20 3d 20 22  r>.result[6] = "
2680: 44 2e 20 52 69 63 68 61 72 64 20 48 69 70 70 22  D. Richard Hipp"
2690: 3c 62 72 3e 0a 72 65 73 75 6c 74 5b 37 5d 20 3d  <br>.result[7] =
26a0: 20 22 64 72 68 22 3c 62 72 3e 0a 72 65 73 75 6c   "drh"<br>.resul
26b0: 74 5b 38 5d 20 3d 20 22 7a 61 64 6f 6b 22 0a 3c  t[8] = "zadok".<
26c0: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70  /blockquote>..<p
26d0: 3e 4e 6f 74 69 63 65 20 74 68 61 74 20 74 68 65  >Notice that the
26e0: 20 22 68 6f 73 74 22 20 76 61 6c 75 65 20 66 6f   "host" value fo
26f0: 72 20 74 68 65 20 22 64 75 6d 6d 79 22 20 72 65  r the "dummy" re
2700: 63 6f 72 64 20 69 73 20 4e 55 4c 4c 20 73 6f 0a  cord is NULL so.
2710: 74 68 65 20 72 65 73 75 6c 74 5b 5d 20 61 72 72  the result[] arr
2720: 61 79 20 63 6f 6e 74 61 69 6e 73 20 61 20 4e 55  ay contains a NU
2730: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 74 20 74 68  LL pointer at th
2740: 61 74 20 73 6c 6f 74 2e 3c 2f 70 3e 0a 0a 3c 70  at slot.</p>..<p
2750: 3e 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  >Memory to hold 
2760: 74 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  the information 
2770: 72 65 74 75 72 6e 65 64 20 62 79 20 3c 62 3e 73  returned by <b>s
2780: 71 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 28  qlite_get_table(
2790: 29 3c 2f 62 3e 0a 69 73 20 6f 62 74 61 69 6e 65  )</b>.is obtaine
27a0: 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 2e  d from malloc().
27b0: 20 20 42 75 74 20 74 68 65 20 63 61 6c 6c 69 6e    But the callin
27c0: 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  g function shoul
27d0: 64 20 6e 6f 74 20 74 72 79 0a 74 6f 20 66 72 65  d not try.to fre
27e0: 65 20 74 68 69 73 20 69 6e 66 6f 72 6d 61 74 69  e this informati
27f0: 6f 6e 20 64 69 72 65 63 74 6c 79 2e 20 20 49 6e  on directly.  In
2800: 73 74 65 61 64 2c 20 70 61 73 73 20 74 68 65 20  stead, pass the 
2810: 63 6f 6d 70 6c 65 74 65 20 74 61 62 6c 65 0a 74  complete table.t
2820: 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 66 72 65 65  o <b>sqlite_free
2830: 5f 74 61 62 6c 65 28 29 3c 2f 62 3e 20 77 68 65  _table()</b> whe
2840: 6e 20 74 68 65 20 74 61 62 6c 65 20 69 73 20 6e  n the table is n
2850: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
2860: 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 3c 62 3e  </p>..<p>The <b>
2870: 73 71 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65  sqlite_get_table
2880: 28 29 3c 2f 62 3e 20 72 6f 75 74 69 6e 65 20 72  ()</b> routine r
2890: 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65 20  eturns the same 
28a0: 69 6e 74 65 67 65 72 0a 72 65 73 75 6c 74 20 63  integer.result c
28b0: 6f 64 65 20 61 73 20 3c 62 3e 73 71 6c 69 74 65  ode as <b>sqlite
28c0: 5f 65 78 65 63 28 29 3c 2f 62 3e 2e 3c 2f 70 3e  _exec()</b>.</p>
28d0: 0a 0a 3c 68 32 3e 54 65 73 74 69 6e 67 20 66 6f  ..<h2>Testing fo
28e0: 72 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  r a complete SQL
28f0: 20 73 74 61 74 65 6d 65 6e 74 3c 2f 68 32 3e 0a   statement</h2>.
2900: 0a 3c 70 3e 54 68 65 20 6c 61 73 74 20 69 6e 74  .<p>The last int
2910: 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 20 74  erface routine t
2920: 6f 20 53 51 4c 69 74 65 20 69 73 20 61 20 63 6f  o SQLite is a co
2930: 6e 76 65 6e 69 65 6e 63 65 20 66 75 6e 63 74 69  nvenience functi
2940: 6f 6e 20 75 73 65 64 0a 74 6f 20 74 65 73 74 20  on used.to test 
2950: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  whether or not a
2960: 20 73 74 72 69 6e 67 20 66 6f 72 6d 73 20 61 20   string forms a 
2970: 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
2980: 74 65 6d 65 6e 74 2e 0a 49 66 20 74 68 65 20 3c  tement..If the <
2990: 62 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 74  b>sqlite_complet
29a0: 65 28 29 3c 2f 62 3e 20 66 75 6e 63 74 69 6f 6e  e()</b> function
29b0: 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 77 68   returns true wh
29c0: 65 6e 20 69 74 73 20 69 6e 70 75 74 0a 69 73 20  en its input.is 
29d0: 61 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 74  a string, then t
29e0: 68 65 20 61 72 67 75 6d 65 6e 74 20 66 6f 72 6d  he argument form
29f0: 73 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  s a complete SQL
2a00: 20 73 74 61 74 65 6d 65 6e 74 2e 0a 54 68 65 72   statement..Ther
2a10: 65 20 61 72 65 20 6e 6f 20 67 75 61 72 61 6e 74  e are no guarant
2a20: 65 65 73 20 74 68 61 74 20 74 68 65 20 73 79 6e  ees that the syn
2a30: 74 61 78 20 6f 66 20 74 68 61 74 20 73 74 61 74  tax of that stat
2a40: 65 6d 65 6e 74 20 69 73 20 63 6f 72 72 65 63 74  ement is correct
2a50: 2c 0a 62 75 74 20 77 65 20 61 74 20 6c 65 61 73  ,.but we at leas
2a60: 74 20 6b 6e 6f 77 20 74 68 65 20 73 74 61 74 65  t know the state
2a70: 6d 65 6e 74 20 69 73 20 63 6f 6d 70 6c 65 74 65  ment is complete
2a80: 2e 20 20 49 66 20 3c 62 3e 73 71 6c 69 74 65 5f  .  If <b>sqlite_
2a90: 63 6f 6d 70 6c 65 74 65 28 29 3c 2f 62 3e 0a 72  complete()</b>.r
2aa0: 65 74 75 72 6e 73 20 66 61 6c 73 65 2c 20 74 68  eturns false, th
2ab0: 65 6e 20 6d 6f 72 65 20 74 65 78 74 20 69 73 20  en more text is 
2ac0: 72 65 71 75 69 72 65 64 20 74 6f 20 63 6f 6d 70  required to comp
2ad0: 6c 65 74 65 20 74 68 65 20 53 51 4c 20 73 74 61  lete the SQL sta
2ae0: 74 65 6d 65 6e 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e  tement.</p>..<p>
2af0: 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 20  For the purpose 
2b00: 6f 66 20 74 68 65 20 3c 62 3e 73 71 6c 69 74 65  of the <b>sqlite
2b10: 5f 63 6f 6d 70 6c 65 74 65 28 29 3c 2f 62 3e 20  _complete()</b> 
2b20: 66 75 6e 63 74 69 6f 6e 2c 20 61 6e 20 53 51 4c  function, an SQL
2b30: 0a 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f  .statement is co
2b40: 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
2b50: 73 20 69 6e 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  s in a semicolon
2b60: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 3c 62  .</p>..<p>The <b
2b70: 3e 73 71 6c 69 74 65 3c 2f 62 3e 20 63 6f 6d 6d  >sqlite</b> comm
2b80: 61 6e 64 2d 6c 69 6e 65 20 75 74 69 6c 69 74 79  and-line utility
2b90: 20 75 73 65 73 20 74 68 65 20 3c 62 3e 73 71 6c   uses the <b>sql
2ba0: 69 74 65 5f 63 6f 6d 70 6c 65 74 65 28 29 3c 2f  ite_complete()</
2bb0: 62 3e 0a 66 75 6e 63 74 69 6f 6e 20 74 6f 20 6b  b>.function to k
2bc0: 6e 6f 77 20 77 68 65 6e 20 69 74 20 6e 65 65 64  now when it need
2bd0: 73 20 74 6f 20 63 61 6c 6c 20 3c 62 3e 73 71 6c  s to call <b>sql
2be0: 69 74 65 5f 65 78 65 63 28 29 3c 2f 62 3e 2e 20  ite_exec()</b>. 
2bf0: 20 41 66 74 65 72 20 65 61 63 68 0a 6c 69 6e 65   After each.line
2c00: 20 6f 66 20 69 6e 70 75 74 20 69 73 20 72 65 63   of input is rec
2c10: 65 69 76 65 64 2c 20 3c 62 3e 73 71 6c 69 74 65  eived, <b>sqlite
2c20: 3c 2f 62 3e 20 63 61 6c 6c 73 20 3c 62 3e 73 71  </b> calls <b>sq
2c30: 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 65 28 29 3c  lite_complete()<
2c40: 2f 62 3e 0a 6f 6e 20 61 6c 6c 20 69 6e 70 75 74  /b>.on all input
2c50: 20 69 6e 20 69 74 73 20 62 75 66 66 65 72 2e 20   in its buffer. 
2c60: 20 49 66 20 3c 62 3e 73 71 6c 69 74 65 5f 63 6f   If <b>sqlite_co
2c70: 6d 70 6c 65 74 65 28 29 3c 2f 62 3e 20 72 65 74  mplete()</b> ret
2c80: 75 72 6e 73 20 74 72 75 65 2c 20 0a 74 68 65 6e  urns true, .then
2c90: 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 28   <b>sqlite_exec(
2ca0: 29 3c 2f 62 3e 20 69 73 20 63 61 6c 6c 65 64 20  )</b> is called 
2cb0: 61 6e 64 20 74 68 65 20 69 6e 70 75 74 20 62 75  and the input bu
2cc0: 66 66 65 72 20 69 73 20 72 65 73 65 74 2e 20 20  ffer is reset.  
2cd0: 49 66 0a 3c 62 3e 73 71 6c 69 74 65 5f 63 6f 6d  If.<b>sqlite_com
2ce0: 70 6c 65 74 65 28 29 3c 2f 62 3e 20 72 65 74 75  plete()</b> retu
2cf0: 72 6e 73 20 66 61 6c 73 65 2c 20 74 68 65 6e 20  rns false, then 
2d00: 74 68 65 20 70 72 6f 6d 70 74 20 69 73 20 63 68  the prompt is ch
2d10: 61 6e 67 65 64 20 74 6f 0a 74 68 65 20 63 6f 6e  anged to.the con
2d20: 74 69 6e 75 61 74 69 6f 6e 20 70 72 6f 6d 70 74  tinuation prompt
2d30: 20 61 6e 64 20 61 6e 6f 74 68 65 72 20 6c 69 6e   and another lin
2d40: 65 20 6f 66 20 74 65 78 74 20 69 73 20 72 65 61  e of text is rea
2d50: 64 20 61 6e 64 20 61 64 64 65 64 20 74 6f 0a 74  d and added to.t
2d60: 68 65 20 69 6e 70 75 74 20 62 75 66 66 65 72 2e  he input buffer.
2d70: 3c 2f 70 3e 0a 0a 3c 68 32 3e 4c 69 62 72 61 72  </p>..<h2>Librar
2d80: 79 20 76 65 72 73 69 6f 6e 20 73 74 72 69 6e 67  y version string
2d90: 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65 20 53 51  </h2>..<p>The SQ
2da0: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 65 78 70  Lite library exp
2db0: 6f 72 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  orts the string 
2dc0: 63 6f 6e 73 74 61 6e 74 20 6e 61 6d 65 64 0a 3c  constant named.<
2dd0: 62 3e 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e  b>sqlite_version
2de0: 3c 2f 62 3e 20 77 68 69 63 68 20 63 6f 6e 74 61  </b> which conta
2df0: 69 6e 73 20 74 68 65 20 76 65 72 73 69 6f 6e 20  ins the version 
2e00: 6e 75 6d 62 65 72 20 6f 66 20 74 68 65 0a 6c 69  number of the.li
2e10: 62 72 61 72 79 2e 20 20 54 68 65 20 68 65 61 64  brary.  The head
2e20: 65 72 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  er file contains
2e30: 20 61 20 6d 61 63 72 6f 20 53 51 4c 49 54 45 5f   a macro SQLITE_
2e40: 56 45 52 53 49 4f 4e 0a 77 69 74 68 20 74 68 65  VERSION.with the
2e50: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
2e60: 6e 2e 20 20 49 66 20 64 65 73 69 72 65 64 2c 20  n.  If desired, 
2e70: 61 20 70 72 6f 67 72 61 6d 20 63 61 6e 20 63 6f  a program can co
2e80: 6d 70 61 72 65 0a 74 68 65 20 53 51 4c 49 54 45  mpare.the SQLITE
2e90: 5f 56 45 52 53 49 4f 4e 20 6d 61 63 72 6f 20 61  _VERSION macro a
2ea0: 67 61 69 6e 73 74 20 74 68 65 20 3c 62 3e 73 71  gainst the <b>sq
2eb0: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 3c 2f 62 3e  lite_version</b>
2ec0: 0a 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74  .string constant
2ed0: 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
2ee0: 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  the version numb
2ef0: 65 72 20 6f 66 20 74 68 65 0a 68 65 61 64 65 72  er of the.header
2f00: 20 66 69 6c 65 20 61 6e 64 20 74 68 65 20 6c 69   file and the li
2f10: 62 72 61 72 79 20 6d 61 74 63 68 2e 3c 2f 70 3e  brary match.</p>
2f20: 20 0a 0a 3c 68 32 3e 43 68 61 6e 67 69 6e 67 20   ..<h2>Changing 
2f30: 74 68 65 20 6c 69 62 72 61 72 69 65 73 20 72 65  the libraries re
2f40: 70 6f 6e 73 65 20 74 6f 20 6c 6f 63 6b 65 64 20  ponse to locked 
2f50: 66 69 6c 65 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 54  files</h2>..<p>T
2f60: 68 65 20 47 44 42 4d 20 6c 69 62 72 61 72 79 20  he GDBM library 
2f70: 73 75 70 70 6f 72 74 73 20 64 61 74 61 62 61 73  supports databas
2f80: 65 20 6c 6f 63 6b 73 20 61 74 20 74 68 65 20 66  e locks at the f
2f90: 69 6c 65 20 6c 65 76 65 6c 2e 0a 49 66 20 61 20  ile level..If a 
2fa0: 47 44 42 4d 20 64 61 74 61 62 61 73 65 20 66 69  GDBM database fi
2fb0: 6c 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  le is opened for
2fc0: 20 72 65 61 64 69 6e 67 2c 20 74 68 65 6e 20 74   reading, then t
2fd0: 68 61 74 20 73 61 6d 65 0a 66 69 6c 65 20 63 61  hat same.file ca
2fe0: 6e 6e 6f 74 20 62 65 20 72 65 6f 70 65 6e 65 64  nnot be reopened
2ff0: 20 66 6f 72 20 77 72 69 74 69 6e 67 20 75 6e 74   for writing unt
3000: 69 6c 20 61 6c 6c 20 72 65 61 64 65 72 73 20 68  il all readers h
3010: 61 76 65 20 63 6c 6f 73 65 64 0a 74 68 65 20 66  ave closed.the f
3020: 69 6c 65 2e 20 20 49 66 20 61 20 47 44 42 4d 20  ile.  If a GDBM 
3030: 66 69 6c 65 20 69 73 20 6f 70 65 6e 20 66 6f 72  file is open for
3040: 20 77 72 69 74 69 6e 67 2c 20 74 68 65 6e 20 74   writing, then t
3050: 68 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 0a 62  he file cannot.b
3060: 65 20 72 65 6f 70 65 6e 65 64 20 66 6f 72 20 72  e reopened for r
3070: 65 61 64 69 6e 67 20 6f 72 20 77 72 69 74 69 6e  eading or writin
3080: 67 20 75 6e 74 69 6c 20 69 74 20 69 73 20 63 6c  g until it is cl
3090: 6f 73 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 49 66  osed.</p>..<p>If
30a0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
30b0: 61 72 79 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ary attempts to 
30c0: 6f 70 65 6e 20 61 20 47 44 42 4d 20 66 69 6c 65  open a GDBM file
30d0: 20 61 6e 64 20 66 69 6e 64 73 20 74 68 61 74 0a   and finds that.
30e0: 74 68 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  the file is lock
30f0: 65 64 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20  ed, the default 
3100: 61 63 74 69 6f 6e 20 69 73 20 74 6f 20 61 62 6f  action is to abo
3110: 72 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 6f  rt the current.o
3120: 70 65 72 61 74 69 6f 6e 20 61 6e 64 20 72 65 74  peration and ret
3130: 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  urn SQLITE_BUSY.
3140: 20 20 42 75 74 20 74 68 69 73 20 69 73 20 6e 6f    But this is no
3150: 74 20 61 6c 77 61 79 73 20 74 68 65 20 6d 6f 73  t always the mos
3160: 74 0a 63 6f 6e 76 65 6e 69 65 6e 74 20 62 65 68  t.convenient beh
3170: 61 76 69 6f 72 2c 20 73 6f 20 61 20 6d 65 63 68  avior, so a mech
3180: 61 6e 69 73 6d 20 65 78 69 73 74 73 20 74 6f 20  anism exists to 
3190: 63 68 61 6e 67 65 20 69 74 2e 3c 2f 70 3e 0a 0a  change it.</p>..
31a0: 3c 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69 74 65  <p>The <b>sqlite
31b0: 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 3c  _busy_handler()<
31c0: 2f 62 3e 20 70 72 6f 63 65 64 75 72 65 20 63 61  /b> procedure ca
31d0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 67  n be used to reg
31e0: 69 73 74 65 72 0a 61 20 62 75 73 79 20 63 61 6c  ister.a busy cal
31f0: 6c 62 61 63 6b 20 77 69 74 68 20 61 6e 20 6f 70  lback with an op
3200: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
3210: 73 65 2e 20 20 54 68 65 20 62 75 73 79 20 63 61  se.  The busy ca
3220: 6c 6c 62 61 63 6b 20 77 69 6c 6c 0a 62 65 20 69  llback will.be i
3230: 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
3240: 53 51 4c 69 74 65 20 74 72 69 65 73 20 74 6f 20  SQLite tries to 
3250: 6f 70 65 6e 20 61 20 47 44 42 4d 20 66 69 6c 65  open a GDBM file
3260: 20 74 68 61 74 20 69 73 20 6c 6f 63 6b 65 64 2e   that is locked.
3270: 0a 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69  .The callback wi
3280: 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 64 6f 20  ll typically do 
3290: 73 6f 6d 65 20 6f 74 68 65 72 20 75 73 65 66 75  some other usefu
32a0: 6c 20 77 6f 72 6b 2c 20 6f 72 20 70 65 72 68 61  l work, or perha
32b0: 70 73 20 73 6c 65 65 70 2c 0a 69 6e 20 6f 72 64  ps sleep,.in ord
32c0: 65 72 20 74 6f 20 67 69 76 65 20 74 68 65 20 6c  er to give the l
32d0: 6f 63 6b 20 61 20 63 68 61 6e 63 65 20 74 6f 20  ock a chance to 
32e0: 63 6c 65 61 72 2e 20 20 49 66 20 74 68 65 20 63  clear.  If the c
32f0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
3300: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 53  non-zero, then S
3310: 51 4c 69 74 65 20 74 72 69 65 73 20 61 67 61 69  QLite tries agai
3320: 6e 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 47 44  n to open the GD
3330: 42 4d 20 66 69 6c 65 20 61 6e 64 20 74 68 65 20  BM file and the 
3340: 63 79 63 6c 65 0a 72 65 70 65 61 74 73 2e 20 20  cycle.repeats.  
3350: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3360: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
3370: 65 6e 20 53 51 4c 69 74 65 20 61 62 6f 72 74 73  en SQLite aborts
3380: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 6f 70 65   the current.ope
3390: 72 61 74 69 6f 6e 20 61 6e 64 20 72 65 74 75 72  ration and retur
33a0: 6e 73 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 3c  ns SQLITE_BUSY.<
33b0: 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 61 72 67 75  /p>..<p>The argu
33c0: 6d 65 6e 74 73 20 74 6f 20 3c 62 3e 73 71 6c 69  ments to <b>sqli
33d0: 74 65 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  te_busy_handler(
33e0: 29 3c 2f 62 3e 20 61 72 65 20 74 68 65 20 6f 70  )</b> are the op
33f0: 61 71 75 65 0a 73 74 72 75 63 74 75 72 65 20 72  aque.structure r
3400: 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 3c 62 3e  eturned from <b>
3410: 73 71 6c 69 74 65 5f 6f 70 65 6e 28 29 3c 2f 62  sqlite_open()</b
3420: 3e 2c 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  >, a pointer to 
3430: 74 68 65 20 62 75 73 79 0a 63 61 6c 6c 62 61 63  the busy.callbac
3440: 6b 20 66 75 6e 63 74 69 6f 6e 2c 20 61 6e 64 20  k function, and 
3450: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
3460: 72 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 70  r that will be p
3470: 61 73 73 65 64 20 61 73 0a 74 68 65 20 66 69 72  assed as.the fir
3480: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
3490: 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
34a0: 2e 20 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  .  When SQLite i
34b0: 6e 76 6f 6b 65 73 20 74 68 65 0a 62 75 73 79 20  nvokes the.busy 
34c0: 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 73 65 6e  callback, it sen
34d0: 64 73 20 69 74 20 74 68 72 65 65 20 61 72 67 75  ds it three argu
34e0: 6d 65 6e 74 73 3a 20 20 74 68 65 20 67 65 6e 65  ments:  the gene
34f0: 72 69 63 20 70 6f 69 6e 74 65 72 0a 74 68 61 74  ric pointer.that
3500: 20 77 61 73 20 70 61 73 73 65 64 20 69 6e 20 61   was passed in a
3510: 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
3520: 6d 65 6e 74 20 74 6f 20 3c 62 3e 73 71 6c 69 74  ment to <b>sqlit
3530: 65 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 3c 2f  e_busy_handler</
3540: 62 3e 2c 0a 74 68 65 20 6e 61 6d 65 20 6f 66 20  b>,.the name of 
3550: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 61 62  the database tab
3560: 6c 65 20 6f 72 20 69 6e 64 65 78 20 74 68 61 74  le or index that
3570: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 73 20   the library is 
3580: 74 72 79 69 6e 67 0a 74 6f 20 6f 70 65 6e 2c 20  trying.to open, 
3590: 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
35a0: 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
35b0: 20 6c 69 62 72 61 72 79 20 68 61 73 20 61 74 74   library has att
35c0: 65 6d 70 74 65 64 20 74 6f 0a 6f 70 65 6e 20 74  empted to.open t
35d0: 68 65 20 64 61 74 61 62 61 73 65 20 74 61 62 6c  he database tabl
35e0: 65 20 6f 72 20 69 6e 64 65 78 2e 3c 2f 70 3e 0a  e or index.</p>.
35f0: 0a 3c 70 3e 46 6f 72 20 74 68 65 20 63 6f 6d 6d  .<p>For the comm
3600: 6f 6e 20 63 61 73 65 20 77 68 65 72 65 20 77 65  on case where we
3610: 20 77 61 6e 74 20 74 68 65 20 62 75 73 79 20 63   want the busy c
3620: 61 6c 6c 62 61 63 6b 20 74 6f 20 73 6c 65 65 70  allback to sleep
3630: 2c 0a 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ,.the SQLite lib
3640: 72 61 72 79 20 70 72 6f 76 69 64 65 73 20 61 20  rary provides a 
3650: 63 6f 6e 76 65 6e 69 65 6e 63 65 20 72 6f 75 74  convenience rout
3660: 69 6e 65 20 3c 62 3e 73 71 6c 69 74 65 5f 62 75  ine <b>sqlite_bu
3670: 73 79 5f 74 69 6d 65 6f 75 74 28 29 3c 2f 62 3e  sy_timeout()</b>
3680: 2e 0a 54 68 65 20 66 69 72 73 74 20 61 72 67 75  ..The first argu
3690: 6d 65 6e 74 20 74 6f 20 3c 62 3e 73 71 6c 69 74  ment to <b>sqlit
36a0: 65 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  e_busy_timeout()
36b0: 3c 2f 62 3e 20 69 73 20 61 20 70 6f 69 6e 74 65  </b> is a pointe
36c0: 72 20 74 6f 0a 61 6e 20 6f 70 65 6e 20 53 51 4c  r to.an open SQL
36d0: 69 74 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  ite database and
36e0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
36f0: 6d 65 6e 74 20 69 73 20 61 20 6e 75 6d 62 65 72  ment is a number
3700: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
3710: 2e 0a 41 66 74 65 72 20 3c 62 3e 73 71 6c 69 74  ..After <b>sqlit
3720: 65 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  e_busy_timeout()
3730: 3c 2f 62 3e 20 68 61 73 20 62 65 65 6e 20 65 78  </b> has been ex
3740: 65 63 75 74 65 64 2c 20 74 68 65 20 53 51 4c 69  ecuted, the SQLi
3750: 74 65 20 6c 69 62 72 61 72 79 0a 77 69 6c 6c 20  te library.will 
3760: 77 61 69 74 20 66 6f 72 20 74 68 65 20 6c 6f 63  wait for the loc
3770: 6b 20 74 6f 20 63 6c 65 61 72 20 66 6f 72 20 61  k to clear for a
3780: 74 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62  t least the numb
3790: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
37a0: 64 73 20 0a 73 70 65 63 69 66 69 65 64 20 62 65  ds .specified be
37b0: 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 20  fore it returns 
37c0: 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 53 70  SQLITE_BUSY.  Sp
37d0: 65 63 69 66 79 69 6e 67 20 7a 65 72 6f 20 6d 69  ecifying zero mi
37e0: 6c 6c 69 73 65 63 6f 6e 64 73 20 66 6f 72 0a 74  lliseconds for.t
37f0: 68 65 20 74 69 6d 65 6f 75 74 20 72 65 73 74 6f  he timeout resto
3800: 72 65 73 20 74 68 65 20 64 65 66 61 75 6c 74 20  res the default 
3810: 62 65 68 61 76 69 6f 72 2e 3c 2f 70 3e 0a 0a 3c  behavior.</p>..<
3820: 68 32 3e 55 73 61 67 65 20 45 78 61 6d 70 6c 65  h2>Usage Example
3830: 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 46 6f 72 20 65  s</h2>..<p>For e
3840: 78 61 6d 70 6c 65 73 20 6f 66 20 68 6f 77 20 74  xamples of how t
3850: 68 65 20 53 51 4c 69 74 65 20 43 2f 43 2b 2b 20  he SQLite C/C++ 
3860: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
3870: 20 75 73 65 64 2c 0a 72 65 66 65 72 20 74 6f 20   used,.refer to 
3880: 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20  the source code 
3890: 66 6f 72 20 74 68 65 20 3c 62 3e 73 71 6c 69 74  for the <b>sqlit
38a0: 65 3c 2f 62 3e 20 70 72 6f 67 72 61 6d 20 69 6e  e</b> program in
38b0: 20 74 68 65 0a 66 69 6c 65 20 3c 62 3e 73 72 63   the.file <b>src
38c0: 2f 73 68 65 6c 6c 2e 63 3c 2f 62 3e 20 6f 66 20  /shell.c</b> of 
38d0: 74 68 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  the source tree.
38e0: 0a 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f  .Additional info
38f0: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 73 71  rmation about sq
3900: 6c 69 74 65 20 69 73 20 61 76 61 69 6c 61 62 6c  lite is availabl
3910: 65 20 61 74 0a 3c 61 20 68 72 65 66 3d 22 73 71  e at.<a href="sq
3920: 6c 69 74 65 2e 68 74 6d 6c 22 3e 73 71 6c 69 74  lite.html">sqlit
3930: 65 2e 68 74 6d 6c 3c 2f 61 3e 2e 0a 53 65 65 20  e.html</a>..See 
3940: 61 6c 73 6f 20 74 68 65 20 73 6f 75 72 63 65 73  also the sources
3950: 20 74 6f 20 74 68 65 20 54 63 6c 20 69 6e 74 65   to the Tcl inte
3960: 72 66 61 63 65 20 66 6f 72 20 53 51 4c 69 74 65  rface for SQLite
3970: 20 69 6e 0a 74 68 65 20 73 6f 75 72 63 65 20 66   in.the source f
3980: 69 6c 65 20 3c 62 3e 73 72 63 2f 74 63 6c 73 71  ile <b>src/tclsq
3990: 6c 69 74 65 2e 63 3c 2f 62 3e 2e 3c 2f 70 3e 0a  lite.c</b>.</p>.
39a0: 7d 0a 0a 70 75 74 73 20 7b 0a 3c 70 3e 3c 68 72  }..puts {.<p><hr
39b0: 20 2f 3e 3c 2f 70 3e 0a 3c 70 3e 3c 61 20 68 72   /></p>.<p><a hr
39c0: 65 66 3d 22 69 6e 64 65 78 2e 68 74 6d 6c 22 3e  ef="index.html">
39d0: 3c 69 6d 67 20 73 72 63 3d 22 2f 67 6f 62 61 63  <img src="/gobac
39e0: 6b 2e 6a 70 67 22 20 62 6f 72 64 65 72 3d 30 20  k.jpg" border=0 
39f0: 2f 3e 0a 42 61 63 6b 20 74 6f 20 74 68 65 20 53  />.Back to the S
3a00: 51 4c 69 74 65 20 48 6f 6d 65 20 50 61 67 65 3c  QLite Home Page<
3a10: 2f 61 3e 0a 3c 2f 70 3e 0a 0a 3c 2f 62 6f 64 79  /a>.</p>..</body
3a20: 3e 3c 2f 68 74 6d 6c 3e 7d 0a                    ></html>}.