/ Hex Artifact Content
Login

Artifact 8eb800f67e6896b1894d666b81c0b418cea09fc7:


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: 35 20 32 30 30 30 2f 30 36 2f 32 31 20 31 33 3a  5 2000/06/21 13:
0070: 35 39 3a 31 34 20 64 72 68 20 45 78 70 20 24 7d  59:14 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 34 20 66 75 6e 63  nsists of 4 func
0280: 74 69 6f 6e 73 2c 0a 6f 6e 65 20 6f 70 61 71 75  tions,.one opaqu
0290: 65 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  e data structure
02a0: 2c 20 61 6e 64 20 73 6f 6d 65 20 63 6f 6e 73 74  , and some const
02b0: 61 6e 74 73 20 75 73 65 64 20 61 73 20 72 65 74  ants used as ret
02c0: 75 72 6e 0a 76 61 6c 75 65 73 20 66 72 6f 6d 20  urn.values from 
02d0: 73 71 6c 69 74 65 5f 65 78 65 63 28 29 3a 3c 2f  sqlite_exec():</
02e0: 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  p>..<blockquote>
02f0: 3c 70 72 65 3e 0a 74 79 70 65 64 65 66 20 73 74  <pre>.typedef st
0300: 72 75 63 74 20 73 71 6c 69 74 65 20 73 71 6c 69  ruct sqlite sqli
0310: 74 65 3b 0a 0a 73 71 6c 69 74 65 20 2a 73 71 6c  te;..sqlite *sql
0320: 69 74 65 5f 6f 70 65 6e 28 63 6f 6e 73 74 20 63  ite_open(const c
0330: 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 69  har *filename, i
0340: 6e 74 20 6d 6f 64 65 2c 20 63 68 61 72 20 2a 2a  nt mode, char **
0350: 65 72 72 6d 73 67 29 3b 0a 0a 76 6f 69 64 20 73  errmsg);..void s
0360: 71 6c 69 74 65 5f 63 6c 6f 73 65 28 73 71 6c 69  qlite_close(sqli
0370: 74 65 2a 29 3b 0a 0a 69 6e 74 20 73 71 6c 69 74  te*);..int sqlit
0380: 65 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65  e_exec(.  sqlite
0390: 2a 2c 0a 20 20 63 68 61 72 20 2a 73 71 6c 2c 0a  *,.  char *sql,.
03a0: 20 20 69 6e 74 20 28 2a 29 28 76 6f 69 64 2a 2c    int (*)(void*,
03b0: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
03c0: 2a 29 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 63  *),.  void*,.  c
03d0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 0a 29 3b 0a  har **errmsg.);.
03e0: 0a 69 6e 74 20 73 71 6c 69 74 65 5f 63 6f 6d 70  .int sqlite_comp
03f0: 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
0400: 2a 73 71 6c 29 3b 0a 0a 23 64 65 66 69 6e 65 20  *sql);..#define 
0410: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
0420: 20 30 20 20 20 20 2f 2a 20 53 75 63 63 65 73 73   0    /* Success
0430: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 23 64  ful result */.#d
0440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
0450: 45 52 4e 41 4c 20 20 31 20 20 20 20 2f 2a 20 41  ERNAL  1    /* A
0460: 6e 20 69 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63  n internal logic
0470: 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65   error in SQLite
0480: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
0490: 54 45 5f 45 52 52 4f 52 20 20 20 20 20 32 20 20  TE_ERROR     2  
04a0: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
04b0: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
04c0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
04d0: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 33  LITE_PERM      3
04e0: 20 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65      /* Access pe
04f0: 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20  rmission denied 
0500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0510: 45 5f 41 42 4f 52 54 20 20 20 20 20 34 20 20 20  E_ABORT     4   
0520: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
0530: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
0540: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
0550: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
0560: 20 20 20 20 35 20 20 20 20 2f 2a 20 4f 6e 65 20      5    /* One 
0570: 6f 72 20 6d 6f 72 65 20 64 61 74 61 62 61 73 65  or more database
0580: 20 66 69 6c 65 73 20 61 72 65 20 6c 6f 63 6b 65   files are locke
0590: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
05a0: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 36 20  ITE_NOMEM     6 
05b0: 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29     /* A malloc()
05c0: 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69   failed */.#defi
05d0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
05e0: 4c 59 20 20 37 20 20 20 20 2f 2a 20 41 74 74 65  LY  7    /* Atte
05f0: 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72  mpt to write a r
0600: 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65  eadonly database
0610: 20 2a 2f 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63   */.</pre></bloc
0620: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 41 6c 6c 20  kquote>..<p>All 
0630: 6f 66 20 74 68 65 20 61 62 6f 76 65 20 64 65 66  of the above def
0640: 69 6e 69 74 69 6f 6e 73 20 61 72 65 20 69 6e 63  initions are inc
0650: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 22 73 71  luded in the "sq
0660: 6c 69 74 65 2e 68 22 0a 68 65 61 64 65 72 20 66  lite.h".header f
0670: 69 6c 65 20 74 68 61 74 20 63 6f 6d 65 73 20 69  ile that comes i
0680: 6e 20 74 68 65 20 73 6f 75 72 63 65 20 74 72 65  n the source tre
0690: 65 2e 3c 2f 70 3e 0a 0a 3c 68 32 3e 4f 70 65 6e  e.</p>..<h2>Open
06a0: 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 3c 2f  ing a database</
06b0: 68 32 3e 0a 0a 3c 70 3e 55 73 65 20 74 68 65 20  h2>..<p>Use the 
06c0: 3c 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e 28 29  <b>sqlite_open()
06d0: 3c 2f 62 3e 20 66 75 6e 63 74 69 6f 6e 20 74 6f  </b> function to
06e0: 20 6f 70 65 6e 20 61 6e 20 65 78 69 73 74 69 6e   open an existin
06f0: 67 20 53 51 4c 69 74 65 0a 64 61 74 61 62 61 73  g SQLite.databas
0700: 65 20 6f 72 20 74 6f 20 63 72 65 61 74 65 20 61  e or to create a
0710: 20 6e 65 77 20 53 51 4c 69 74 65 20 64 61 74 61   new SQLite data
0720: 62 61 73 65 2e 20 20 54 68 65 20 66 69 72 73 74  base.  The first
0730: 20 61 72 67 75 6d 65 6e 74 0a 69 73 20 74 68 65   argument.is the
0740: 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2e 20   database name. 
0750: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
0760: 6d 65 6e 74 20 69 73 20 61 20 63 6f 6e 73 74 61  ment is a consta
0770: 6e 74 20 30 36 36 36 20 74 6f 0a 6f 70 65 6e 20  nt 0666 to.open 
0780: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
0790: 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
07a0: 74 69 6e 67 20 61 6e 64 20 30 34 34 34 20 74 6f  ting and 0444 to
07b0: 20 6f 70 65 6e 20 74 68 65 0a 64 61 74 61 62 61   open the.databa
07c0: 73 65 20 72 65 61 64 20 6f 6e 6c 79 2e 20 20 54  se read only.  T
07d0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
07e0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
07f0: 6f 20 61 20 73 74 72 69 6e 67 0a 70 6f 69 6e 74  o a string.point
0800: 65 72 2e 20 20 49 66 20 74 68 65 20 74 68 69 72  er.  If the thir
0810: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 6f  d argument is no
0820: 74 20 4e 55 4c 4c 20 61 6e 64 20 61 6e 20 65 72  t NULL and an er
0830: 72 6f 72 20 6f 63 63 75 72 73 0a 77 68 69 6c 65  ror occurs.while
0840: 20 74 72 79 69 6e 67 20 74 6f 20 6f 70 65 6e 20   trying to open 
0850: 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 68  the database, th
0860: 65 6e 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  en an error mess
0870: 61 67 65 20 77 69 6c 6c 20 62 65 0a 77 72 69 74  age will be.writ
0880: 74 65 6e 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  ten to memory ob
0890: 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c 6c  tained from mall
08a0: 6f 63 28 29 20 61 6e 64 20 2a 65 72 72 6d 73 67  oc() and *errmsg
08b0: 20 77 69 6c 6c 20 62 65 20 6d 61 64 65 0a 74 6f   will be made.to
08c0: 20 70 6f 69 6e 74 20 74 6f 20 74 68 69 73 20 65   point to this e
08d0: 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 54  rror message.  T
08e0: 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
08f0: 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ion is responsib
0900: 6c 65 0a 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le.for freeing t
0910: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 69  he memory when i
0920: 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
0930: 69 74 68 20 69 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e  ith it.</p>..<p>
0940: 41 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  An SQLite databa
0950: 73 65 20 69 73 20 6a 75 73 74 20 61 20 64 69 72  se is just a dir
0960: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
0970: 67 20 61 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  g a collection o
0980: 66 0a 47 44 42 4d 20 66 69 6c 65 73 2e 20 20 54  f.GDBM files.  T
0990: 68 65 72 65 20 69 73 20 6f 6e 65 20 47 44 42 4d  here is one GDBM
09a0: 20 66 69 6c 65 20 66 6f 72 20 65 61 63 68 20 74   file for each t
09b0: 61 62 6c 65 20 61 6e 64 20 69 6e 64 65 78 20 69  able and index i
09c0: 6e 20 74 68 65 0a 64 61 74 61 62 61 73 65 2e 20  n the.database. 
09d0: 20 41 6c 6c 20 47 44 42 4d 20 66 69 6c 65 73 20   All GDBM files 
09e0: 65 6e 64 20 77 69 74 68 20 74 68 65 20 22 2e 74  end with the ".t
09f0: 62 6c 22 20 73 75 66 66 69 78 2e 20 20 45 76 65  bl" suffix.  Eve
0a00: 72 79 20 53 51 4c 69 74 65 0a 64 61 74 61 62 61  ry SQLite.databa
0a10: 73 65 20 61 6c 73 6f 20 63 6f 6e 74 61 69 6e 73  se also contains
0a20: 20 61 20 73 70 65 63 69 61 6c 20 64 61 74 61 62   a special datab
0a30: 61 73 65 20 74 61 62 6c 65 20 6e 61 6d 65 64 20  ase table named 
0a40: 3c 62 3e 73 71 6c 69 74 65 5f 6d 61 73 74 65 72  <b>sqlite_master
0a50: 3c 2f 62 3e 0a 73 74 6f 72 65 64 20 69 6e 20 69  </b>.stored in i
0a60: 74 73 20 6f 77 6e 20 47 44 42 4d 20 66 69 6c 65  ts own GDBM file
0a70: 2e 20 20 54 68 69 73 20 73 70 65 63 69 61 6c 20  .  This special 
0a80: 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
0a90: 65 20 64 61 74 61 62 61 73 65 0a 73 63 68 65 6d  e database.schem
0aa0: 61 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 6f 20 63 72  a.</p>..<p>To cr
0ab0: 65 61 74 65 20 61 20 6e 65 77 20 53 51 4c 69 74  eate a new SQLit
0ac0: 65 20 64 61 74 61 62 61 73 65 2c 20 61 6c 6c 20  e database, all 
0ad0: 79 6f 75 20 68 61 76 65 20 74 6f 20 64 6f 20 69  you have to do i
0ae0: 73 20 63 61 6c 6c 0a 3c 62 3e 73 71 6c 69 74 65  s call.<b>sqlite
0af0: 5f 6f 70 65 6e 28 29 3c 2f 62 3e 20 77 69 74 68  _open()</b> with
0b00: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
0b10: 65 74 65 72 20 73 65 74 20 74 6f 20 74 68 65 20  eter set to the 
0b20: 6e 61 6d 65 20 6f 66 0a 61 6e 20 65 6d 70 74 79  name of.an empty
0b30: 20 64 69 72 65 63 74 6f 72 79 20 61 6e 64 20 74   directory and t
0b40: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
0b50: 74 65 72 20 73 65 74 20 74 6f 20 30 36 36 36 2e  ter set to 0666.
0b60: 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 72 65 74  </p>..<p>The ret
0b70: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
0b80: 20 3c 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e 28   <b>sqlite_open(
0b90: 29 3c 2f 62 3e 20 66 75 6e 63 74 69 6f 6e 20 69  )</b> function i
0ba0: 73 20 61 0a 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a.pointer to a
0bb0: 6e 20 6f 70 61 71 75 65 20 3c 62 3e 73 71 6c 69  n opaque <b>sqli
0bc0: 74 65 3c 2f 62 3e 20 73 74 72 75 63 74 75 72 65  te</b> structure
0bd0: 2e 20 20 54 68 69 73 20 70 6f 69 6e 74 65 72 20  .  This pointer 
0be0: 77 69 6c 6c 0a 62 65 20 74 68 65 20 66 69 72 73  will.be the firs
0bf0: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 61 6c  t argument to al
0c00: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  l subsequent SQL
0c10: 69 74 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ite function cal
0c20: 6c 73 20 74 68 61 74 0a 64 65 61 6c 20 77 69 74  ls that.deal wit
0c30: 68 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  h the same datab
0c40: 61 73 65 2e 20 20 4e 55 4c 4c 20 69 73 20 72 65  ase.  NULL is re
0c50: 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 6f 70  turned if the op
0c60: 65 6e 20 66 61 69 6c 73 0a 66 6f 72 20 61 6e 79  en fails.for any
0c70: 20 72 65 61 73 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 68   reason.</p>..<h
0c80: 32 3e 43 6c 6f 73 69 6e 67 20 74 68 65 20 64 61  2>Closing the da
0c90: 74 61 62 61 73 65 3c 2f 68 32 3e 0a 0a 3c 70 3e  tabase</h2>..<p>
0ca0: 54 6f 20 63 6c 6f 73 65 20 61 6e 20 53 51 4c 69  To close an SQLi
0cb0: 74 65 20 64 61 74 61 62 61 73 65 2c 20 63 61 6c  te database, cal
0cc0: 6c 20 74 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f  l the <b>sqlite_
0cd0: 63 6c 6f 73 65 28 29 3c 2f 62 3e 0a 66 75 6e 63  close()</b>.func
0ce0: 74 69 6f 6e 20 70 61 73 73 69 6e 67 20 69 74 20  tion passing it 
0cf0: 74 68 65 20 73 71 6c 69 74 65 20 73 74 72 75 63  the sqlite struc
0d00: 74 75 72 65 20 70 6f 69 6e 74 65 72 20 74 68 61  ture pointer tha
0d10: 74 20 77 61 73 20 6f 62 74 61 69 6e 65 64 0a 66  t was obtained.f
0d20: 72 6f 6d 20 61 20 70 72 69 6f 72 20 63 61 6c 6c  rom a prior call
0d30: 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 6f 70   to <b>sqlite_op
0d40: 65 6e 3c 2f 62 3e 2e 0a 0a 3c 68 32 3e 45 78 65  en</b>...<h2>Exe
0d50: 63 75 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  cuting SQL state
0d60: 6d 65 6e 74 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 54  ments</h2>..<p>T
0d70: 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65  he <b>sqlite_exe
0d80: 63 28 29 3c 2f 62 3e 20 66 75 6e 63 74 69 6f 6e  c()</b> function
0d90: 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 6f 63   is used to proc
0da0: 65 73 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ess SQL statemen
0db0: 74 73 0a 61 6e 64 20 71 75 65 72 69 65 73 2e 20  ts.and queries. 
0dc0: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
0dd0: 65 71 75 69 72 65 73 20 35 20 70 61 72 61 6d 65  equires 5 parame
0de0: 74 65 72 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ters as follows:
0df0: 3c 2f 70 3e 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 3c  </p>..<ol>.<li><
0e00: 70 3e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  p>A pointer to t
0e10: 68 65 20 73 71 6c 69 74 65 20 73 74 72 75 63 74  he sqlite struct
0e20: 75 72 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ure obtained fro
0e30: 6d 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 0a 20  m a prior call. 
0e40: 20 20 20 20 20 20 74 6f 20 3c 62 3e 73 71 6c 69        to <b>sqli
0e50: 74 65 5f 6f 70 65 6e 28 29 3c 2f 62 3e 2e 3c 2f  te_open()</b>.</
0e60: 70 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e 41  p></li>.<li><p>A
0e70: 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64   null-terminated
0e80: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
0e90: 6e 67 20 74 68 65 20 74 65 78 74 20 6f 66 20 6f  ng the text of o
0ea0: 6e 65 20 6f 72 20 6d 6f 72 65 0a 20 20 20 20 20  ne or more.     
0eb0: 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73    SQL statements
0ec0: 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20   and/or queries 
0ed0: 74 6f 20 62 65 20 70 72 6f 63 65 73 73 65 64 2e  to be processed.
0ee0: 3c 2f 70 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c 70  </p></li>.<li><p
0ef0: 3e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  >A pointer to a 
0f00: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
0f10: 6e 20 77 68 69 63 68 20 69 73 20 69 6e 76 6f 6b  n which is invok
0f20: 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
0f30: 0a 20 20 20 20 20 20 20 72 6f 77 20 69 6e 20 74  .       row in t
0f40: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 61 20 71  he result of a q
0f50: 75 65 72 79 2e 20 20 54 68 69 73 20 61 72 67 75  uery.  This argu
0f60: 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55 4c 4c  ment may be NULL
0f70: 2c 20 69 6e 20 77 68 69 63 68 0a 20 20 20 20 20  , in which.     
0f80: 20 20 63 61 73 65 20 6e 6f 20 63 61 6c 6c 62 61    case no callba
0f90: 63 6b 73 20 77 69 6c 6c 20 65 76 65 72 20 62 65  cks will ever be
0fa0: 20 69 6e 76 6f 6b 65 64 2e 3c 2f 70 3e 3c 2f 6c   invoked.</p></l
0fb0: 69 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 70 6f 69 6e  i>.<li><p>A poin
0fc0: 74 65 72 20 74 68 61 74 20 69 73 20 66 6f 72 77  ter that is forw
0fd0: 61 72 64 65 64 20 74 6f 20 62 65 63 6f 6d 65 20  arded to become 
0fe0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
0ff0: 6e 74 0a 20 20 20 20 20 20 20 74 6f 20 74 68 65  nt.       to the
1000: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1010: 6f 6e 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 3c 6c 69  on.</p></li>.<li
1020: 3e 3c 70 3e 41 20 70 6f 69 6e 74 65 72 20 74 6f  ><p>A pointer to
1030: 20 61 6e 20 65 72 72 6f 72 20 73 74 72 69 6e 67   an error string
1040: 2e 20 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65  .  Error message
1050: 73 20 61 72 65 20 77 72 69 74 74 65 6e 20 74 6f  s are written to
1060: 20 73 70 61 63 65 0a 20 20 20 20 20 20 20 6f 62   space.       ob
1070: 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c 6c  tained from mall
1080: 6f 63 28 29 20 61 6e 64 20 74 68 65 20 65 72 72  oc() and the err
1090: 6f 72 20 73 74 72 69 6e 67 20 69 73 20 6d 61 64  or string is mad
10a0: 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 0a 20 20  e to point to.  
10b0: 20 20 20 20 20 74 68 65 20 6d 61 6c 6c 6f 63 65       the malloce
10c0: 64 20 73 70 61 63 65 2e 20 20 54 68 65 20 63 61  d space.  The ca
10d0: 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  lling function i
10e0: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
10f0: 72 20 66 72 65 65 69 6e 67 0a 20 20 20 20 20 20  r freeing.      
1100: 20 74 68 69 73 20 73 70 61 63 65 20 77 68 65 6e   this space when
1110: 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
1120: 20 77 69 74 68 20 69 74 2e 0a 20 20 20 20 20 20   with it..      
1130: 20 54 68 69 73 20 61 72 67 75 6d 65 6e 74 20 6d   This argument m
1140: 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 77  ay be NULL, in w
1150: 68 69 63 68 20 63 61 73 65 20 65 72 72 6f 72 20  hich case error 
1160: 6d 65 73 73 61 67 65 73 20 61 72 65 20 6e 6f 74  messages are not
1170: 0a 20 20 20 20 20 20 20 72 65 70 6f 72 74 65 64  .       reported
1180: 20 62 61 63 6b 20 74 6f 20 74 68 65 20 63 61 6c   back to the cal
1190: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  ling function.</
11a0: 70 3e 3c 2f 6c 69 3e 0a 3c 2f 6f 6c 3e 0a 0a 3c  p></li>.</ol>..<
11b0: 70 3e 0a 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  p>.The callback 
11c0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
11d0: 20 74 6f 20 72 65 63 65 69 76 65 20 74 68 65 20   to receive the 
11e0: 72 65 73 75 6c 74 73 20 6f 66 20 61 20 71 75 65  results of a que
11f0: 72 79 2e 20 20 41 0a 70 72 6f 74 6f 74 79 70 65  ry.  A.prototype
1200: 20 66 6f 72 20 74 68 65 20 63 61 6c 6c 62 61 63   for the callbac
1210: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 73  k function is as
1220: 20 66 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c   follows:</p>..<
1230: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1240: 0a 69 6e 74 20 43 61 6c 6c 62 61 63 6b 28 76 6f  .int Callback(vo
1250: 69 64 20 2a 70 41 72 67 2c 20 69 6e 74 20 61 72  id *pArg, int ar
1260: 67 63 2c 20 63 68 61 72 20 2a 2a 61 72 67 76 2c  gc, char **argv,
1270: 20 63 68 61 72 20 2a 2a 63 6f 6c 75 6d 6e 4e 61   char **columnNa
1280: 6d 65 73 29 7b 0a 20 20 72 65 74 75 72 6e 20 30  mes){.  return 0
1290: 3b 0a 7d 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  ;.}.</pre></bloc
12a0: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 20  kquote>..<p>The 
12b0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
12c0: 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
12d0: 73 20 6a 75 73 74 20 61 20 63 6f 70 79 20 6f 66  s just a copy of
12e0: 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
12f0: 6d 65 6e 74 0a 74 6f 20 3c 62 3e 73 71 6c 69 74  ment.to <b>sqlit
1300: 65 5f 65 78 65 63 28 29 3c 2f 62 3e 20 20 54 68  e_exec()</b>  Th
1310: 69 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e  is parameter can
1320: 20 62 65 20 75 73 65 64 20 74 6f 20 70 61 73 73   be used to pass
1330: 20 61 72 62 69 74 72 61 72 79 0a 69 6e 66 6f 72   arbitrary.infor
1340: 6d 61 74 69 6f 6e 20 74 68 72 6f 75 67 68 20 74  mation through t
1350: 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  o the callback f
1360: 75 6e 63 74 69 6f 6e 20 66 72 6f 6d 20 63 6c 69  unction from cli
1370: 65 6e 74 20 63 6f 64 65 2e 0a 54 68 65 20 73 65  ent code..The se
1380: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
1390: 20 74 68 65 20 6e 75 6d 62 65 72 20 63 6f 6c 75   the number colu
13a0: 6d 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  mns in the query
13b0: 20 72 65 73 75 6c 74 2e 0a 54 68 65 20 74 68 69   result..The thi
13c0: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  rd argument is a
13d0: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
13e0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
13f0: 68 65 72 65 20 65 61 63 68 20 73 74 72 69 6e 67  here each string
1400: 0a 69 73 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  .is a single col
1410: 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
1420: 74 20 66 6f 72 20 74 68 61 74 20 72 65 63 6f 72  t for that recor
1430: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
1440: 65 0a 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e.callback funct
1450: 69 6f 6e 20 72 65 70 6f 72 74 73 20 61 20 4e 55  ion reports a NU
1460: 4c 4c 20 76 61 6c 75 65 20 69 6e 20 74 68 65 20  LL value in the 
1470: 64 61 74 61 62 61 73 65 20 61 73 20 61 20 4e 55  database as a NU
1480: 4c 4c 20 70 6f 69 6e 74 65 72 2c 0a 77 68 69 63  LL pointer,.whic
1490: 68 20 69 73 20 76 65 72 79 20 64 69 66 66 65 72  h is very differ
14a0: 65 6e 74 20 66 72 6f 6d 20 61 6e 20 65 6d 70 74  ent from an empt
14b0: 79 20 73 74 72 69 6e 67 2e 20 20 49 66 20 74 68  y string.  If th
14c0: 65 20 69 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e i-th parameter
14d0: 0a 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72  .is an empty str
14e0: 69 6e 67 2c 20 77 65 20 77 69 6c 6c 20 67 65 74  ing, we will get
14f0: 3a 3c 2f 70 3e 0a 3c 62 6c 6f 63 6b 71 75 6f 74  :</p>.<blockquot
1500: 65 3e 3c 70 72 65 3e 0a 61 72 67 76 5b 69 5d 5b  e><pre>.argv[i][
1510: 30 5d 20 3d 3d 20 30 0a 3c 2f 70 72 65 3e 3c 2f  0] == 0.</pre></
1520: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 70 3e 42  blockquote>.<p>B
1530: 75 74 20 69 66 20 74 68 65 20 69 2d 74 68 20 70  ut if the i-th p
1540: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
1550: 20 77 65 20 77 69 6c 6c 20 67 65 74 3a 3c 2f 70   we will get:</p
1560: 3e 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  >.<blockquote><p
1570: 72 65 3e 0a 61 72 67 76 5b 69 5d 20 3d 3d 20 30  re>.argv[i] == 0
1580: 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75  .</pre></blockqu
1590: 6f 74 65 3e 0a 3c 70 3e 54 68 65 20 6e 61 6d 65  ote>.<p>The name
15a0: 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
15b0: 20 61 72 65 20 63 6f 6e 74 61 69 6e 65 64 20 69   are contained i
15c0: 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
15d0: 75 6d 65 6e 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54  ument.</p>..<p>T
15e0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
15f0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 72 6d  tion should norm
1600: 61 6c 6c 79 20 72 65 74 75 72 6e 20 30 2e 20 20  ally return 0.  
1610: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  If the callback.
1620: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1630: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 71   non-zero, the q
1640: 75 65 72 79 20 69 73 20 69 6d 6d 65 64 69 61 74  uery is immediat
1650: 65 6c 79 20 61 62 6f 72 74 65 64 20 61 6e 64 20  ely aborted and 
1660: 0a 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 28  .<b>sqlite_exec(
1670: 29 3c 2f 62 3e 20 77 69 6c 6c 20 72 65 74 75 72  )</b> will retur
1680: 6e 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 2e 3c  n SQLITE_ABORT.<
1690: 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 3c 62 3e 73  /p>..<p>The <b>s
16a0: 71 6c 69 74 65 5f 65 78 65 63 28 29 3c 2f 62 3e  qlite_exec()</b>
16b0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
16c0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  s an integer to 
16d0: 69 6e 64 69 63 61 74 65 0a 73 75 63 63 65 73 73  indicate.success
16e0: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
16f0: 68 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 54  he operation.  T
1700: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  he following are
1710: 20 70 6f 73 73 69 62 6c 65 0a 72 65 74 75 72 6e   possible.return
1720: 20 76 61 6c 75 65 73 3a 3c 2f 70 3e 0a 0a 3c 62   values:</p>..<b
1730: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 64 6c 3e 0a  lockquote>.<dl>.
1740: 3c 64 74 3e 53 51 4c 49 54 45 5f 4f 4b 3c 2f 64  <dt>SQLITE_OK</d
1750: 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 76  t>.<dd><p>This v
1760: 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
1770: 20 69 66 20 65 76 65 72 79 74 68 69 6e 67 20 77   if everything w
1780: 6f 72 6b 65 64 20 61 6e 64 20 74 68 65 72 65 20  orked and there 
1790: 77 65 72 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a  were no errors..
17a0: 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51  </p></dd>.<dt>SQ
17b0: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 3c 2f 64  LITE_INTERNAL</d
17c0: 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 76  t>.<dd><p>This v
17d0: 61 6c 75 65 20 69 6e 64 69 63 61 74 65 73 20 74  alue indicates t
17e0: 68 61 74 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20  hat an internal 
17f0: 63 6f 6e 73 69 73 74 65 6e 63 79 20 63 68 65 63  consistency chec
1800: 6b 20 77 69 74 68 69 6e 0a 74 68 65 20 53 51 4c  k within.the SQL
1810: 69 74 65 20 6c 69 62 72 61 72 79 20 66 61 69 6c  ite library fail
1820: 65 64 2e 20 20 54 68 69 73 20 63 61 6e 20 6f 6e  ed.  This can on
1830: 6c 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65  ly happen if the
1840: 72 65 20 69 73 20 61 20 62 75 67 20 69 6e 0a 74  re is a bug in.t
1850: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
1860: 79 2e 20 20 49 66 20 79 6f 75 20 65 76 65 72 20  y.  If you ever 
1870: 67 65 74 20 61 6e 20 53 51 4c 49 54 45 5f 49 4e  get an SQLITE_IN
1880: 54 45 52 4e 41 4c 20 72 65 70 6c 79 20 66 72 6f  TERNAL reply fro
1890: 6d 0a 61 6e 20 3c 62 3e 73 71 6c 69 74 65 5f 65  m.an <b>sqlite_e
18a0: 78 65 63 28 29 3c 2f 62 3e 20 63 61 6c 6c 2c 20  xec()</b> call, 
18b0: 70 6c 65 61 73 65 20 72 65 70 6f 72 74 20 74 68  please report th
18c0: 65 20 70 72 6f 62 6c 65 6d 20 6f 6e 20 74 68 65  e problem on the
18d0: 20 53 51 4c 69 74 65 0a 6d 61 69 6c 69 6e 67 20   SQLite.mailing 
18e0: 6c 69 73 74 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a  list..</p></dd>.
18f0: 3c 64 74 3e 53 51 4c 49 54 45 5f 45 52 52 4f 52  <dt>SQLITE_ERROR
1900: 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69  </dt>.<dd><p>Thi
1910: 73 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  s return value i
1920: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
1930: 65 72 65 20 77 61 73 20 61 6e 20 65 72 72 6f 72  ere was an error
1940: 20 69 6e 20 74 68 65 20 53 51 4c 0a 74 68 61 74   in the SQL.that
1950: 20 77 61 73 20 70 61 73 73 65 64 20 69 6e 74 6f   was passed into
1960: 20 74 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f 65   the <b>sqlite_e
1970: 78 65 63 28 29 3c 2f 62 3e 2e 0a 3c 2f 70 3e 3c  xec()</b>..</p><
1980: 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f  /dd>.<dt>SQLITE_
1990: 50 45 52 4d 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70  PERM</dt>.<dd><p
19a0: 3e 54 68 69 73 20 72 65 74 75 72 6e 20 76 61 6c  >This return val
19b0: 75 65 20 73 61 79 73 20 74 68 61 74 20 74 68 65  ue says that the
19c0: 20 61 63 63 65 73 73 20 70 65 72 6d 69 73 73 69   access permissi
19d0: 6f 6e 73 20 6f 6e 20 6f 6e 65 20 6f 66 20 74 68  ons on one of th
19e0: 65 0a 47 44 42 4d 20 66 69 6c 65 73 20 69 73 20  e.GDBM files is 
19f0: 73 75 63 68 20 74 68 61 74 20 74 68 65 20 66 69  such that the fi
1a00: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 6f 70 65  le cannot be ope
1a10: 6e 65 64 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c  ned..</p></dd>.<
1a20: 64 74 3e 53 51 4c 49 54 45 5f 41 42 4f 52 54 3c  dt>SQLITE_ABORT<
1a30: 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73  /dt>.<dd><p>This
1a40: 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
1a50: 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61  ed if the callba
1a60: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  ck function retu
1a70: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 3c 2f  rns non-zero..</
1a80: 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49  p></dd>.<dt>SQLI
1a90: 54 45 5f 42 55 53 59 3c 2f 64 74 3e 0a 3c 64 64  TE_BUSY</dt>.<dd
1aa0: 3e 3c 70 3e 54 68 69 73 20 72 65 74 75 72 6e 20  ><p>This return 
1ab0: 63 6f 64 65 20 69 6e 64 69 63 61 74 65 73 20 74  code indicates t
1ac0: 68 61 74 20 6f 6e 65 20 6f 66 20 74 68 65 20 75  hat one of the u
1ad0: 6e 64 65 72 6c 79 69 6e 67 20 47 44 42 4d 20 66  nderlying GDBM f
1ae0: 69 6c 65 73 0a 69 73 20 6c 6f 63 6b 65 64 20 62  iles.is locked b
1af0: 65 63 61 75 73 65 20 69 74 20 69 73 20 63 75 72  ecause it is cur
1b00: 72 65 6e 74 6c 79 20 62 65 69 6e 67 20 61 63 63  rently being acc
1b10: 65 73 73 65 64 20 62 79 20 61 6e 6f 74 68 65 72  essed by another
1b20: 20 74 68 72 65 61 64 20 6f 72 0a 70 72 6f 63 65   thread or.proce
1b30: 73 73 2e 20 20 47 44 42 4d 20 61 6c 6c 6f 77 73  ss.  GDBM allows
1b40: 20 6d 75 74 69 70 6c 65 20 72 65 61 64 65 72 73   mutiple readers
1b50: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 69 6c   of the same fil
1b60: 65 2c 20 62 75 74 20 6f 6e 6c 79 20 6f 6e 65 0a  e, but only one.
1b70: 77 72 69 74 65 72 2e 20 20 53 6f 20 6d 75 6c 74  writer.  So mult
1b80: 69 70 6c 65 20 70 72 6f 63 65 73 73 65 73 20 63  iple processes c
1b90: 61 6e 20 71 75 65 72 79 20 61 6e 20 53 51 4c 69  an query an SQLi
1ba0: 74 65 20 64 61 74 61 62 61 73 65 20 61 74 20 6f  te database at o
1bb0: 6e 63 65 2e 0a 42 75 74 20 6f 6e 6c 79 20 61 20  nce..But only a 
1bc0: 73 69 6e 67 6c 65 20 70 72 6f 63 65 73 73 20 63  single process c
1bd0: 61 6e 20 77 72 69 74 65 20 74 6f 20 61 6e 20 53  an write to an S
1be0: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 61  QLite database a
1bf0: 74 20 6f 6e 65 20 74 69 6d 65 2e 0a 49 66 20 61  t one time..If a
1c00: 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
1c10: 65 20 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e  e to write to an
1c20: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
1c30: 20 74 68 61 74 20 61 6e 6f 74 68 65 72 0a 70 72   that another.pr
1c40: 6f 63 65 73 73 20 69 73 20 63 75 72 72 65 6e 74  ocess is current
1c50: 6c 79 20 72 65 61 64 69 6e 67 2c 20 74 68 65 20  ly reading, the 
1c60: 77 72 69 74 65 20 69 73 20 6e 6f 74 20 70 65 72  write is not per
1c70: 66 6f 72 6d 65 64 20 61 6e 64 20 0a 3c 62 3e 73  formed and .<b>s
1c80: 71 6c 69 74 65 5f 65 78 65 63 28 29 3c 2f 62 3e  qlite_exec()</b>
1c90: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
1ca0: 42 55 53 59 2e 20 20 53 69 6d 69 6c 61 72 6c 79  BUSY.  Similarly
1cb0: 2c 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 20  , an attempt to 
1cc0: 72 65 61 64 0a 61 6e 20 53 51 4c 69 74 65 20 64  read.an SQLite d
1cd0: 61 74 61 62 61 73 65 20 74 68 61 74 20 69 73 20  atabase that is 
1ce0: 63 75 72 72 65 6e 74 6c 79 20 62 65 69 6e 67 20  currently being 
1cf0: 77 72 69 74 74 65 6e 20 62 79 20 61 6e 6f 74 68  written by anoth
1d00: 65 72 20 70 72 6f 63 65 73 73 0a 77 69 6c 6c 20  er process.will 
1d10: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55  return SQLITE_BU
1d20: 53 59 2e 20 20 49 6e 20 62 6f 74 68 20 63 61 73  SY.  In both cas
1d30: 65 73 2c 20 74 68 65 20 77 72 69 74 65 20 6f 72  es, the write or
1d40: 20 71 75 65 72 79 20 61 74 74 65 6d 70 74 0a 63   query attempt.c
1d50: 61 6e 20 62 65 20 72 65 74 72 69 65 64 20 61 66  an be retried af
1d60: 74 65 72 20 74 68 65 20 6f 74 68 65 72 20 70 72  ter the other pr
1d70: 6f 63 65 73 73 20 66 69 6e 69 73 68 65 73 2e 3c  ocess finishes.<
1d80: 2f 70 3e 0a 3c 70 3e 4e 6f 74 65 20 74 68 61 74  /p>.<p>Note that
1d90: 20 6c 6f 63 6b 69 6e 67 20 69 73 20 64 6f 6e 65   locking is done
1da0: 20 61 74 20 74 68 65 20 66 69 6c 65 20 6c 65 76   at the file lev
1db0: 65 6c 2e 20 20 4f 6e 65 20 70 72 6f 63 65 73 73  el.  One process
1dc0: 20 63 61 6e 0a 77 72 69 74 65 20 74 6f 20 74 61   can.write to ta
1dd0: 62 6c 65 20 41 42 43 20 28 66 6f 72 20 65 78 61  ble ABC (for exa
1de0: 6d 70 6c 65 29 20 77 68 69 6c 65 20 61 6e 6f 74  mple) while anot
1df0: 68 65 72 20 70 72 6f 63 65 73 73 20 73 69 6d 75  her process simu
1e00: 6c 74 61 6e 65 6f 75 73 6c 79 0a 72 65 61 64 73  ltaneously.reads
1e10: 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
1e20: 74 20 74 61 62 6c 65 20 58 59 5a 2e 20 20 42 75  t table XYZ.  Bu
1e30: 74 20 79 6f 75 20 63 61 6e 6e 6f 74 20 68 61 76  t you cannot hav
1e40: 65 20 74 77 6f 20 70 72 6f 63 65 73 73 65 73 20  e two processes 
1e50: 72 65 61 64 69 6e 67 0a 61 6e 64 20 77 72 69 74  reading.and writ
1e60: 69 6e 67 20 74 61 62 6c 65 20 41 42 43 20 61 74  ing table ABC at
1e70: 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a   the same time..
1e80: 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51  </p></dd>.<dt>SQ
1e90: 4c 49 54 45 5f 4e 4f 4d 45 4d 3c 2f 64 74 3e 0a  LITE_NOMEM</dt>.
1ea0: 3c 64 64 3e 3c 70 3e 54 68 69 73 20 76 61 6c 75  <dd><p>This valu
1eb0: 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  e is returned if
1ec0: 20 61 20 63 61 6c 6c 20 74 6f 20 3c 62 3e 6d 61   a call to <b>ma
1ed0: 6c 6c 6f 63 28 29 3c 2f 62 3e 20 66 61 69 6c 73  lloc()</b> fails
1ee0: 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e  ..</p></dd>.<dt>
1ef0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 3c  SQLITE_READONLY<
1f00: 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73  /dt>.<dd><p>This
1f10: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 69 6e 64   return code ind
1f20: 69 63 61 74 65 73 20 74 68 61 74 20 61 6e 20 61  icates that an a
1f30: 74 74 65 6d 70 74 20 77 61 73 20 6d 61 64 65 20  ttempt was made 
1f40: 74 6f 20 77 72 69 74 65 20 74 6f 0a 61 20 64 61  to write to.a da
1f50: 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74  tabase file that
1f60: 20 77 61 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20   was originally 
1f70: 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1f80: 6e 67 20 6f 6e 6c 79 2e 20 20 54 68 69 73 20 63  ng only.  This c
1f90: 61 6e 0a 68 61 70 70 65 6e 20 69 66 20 74 68 65  an.happen if the
1fa0: 20 63 61 6c 6c 62 61 63 6b 20 66 72 6f 6d 20 61   callback from a
1fb0: 20 71 75 65 72 79 20 61 74 74 65 6d 70 74 73 20   query attempts 
1fc0: 74 6f 20 75 70 64 61 74 65 20 74 68 65 20 74 61  to update the ta
1fd0: 62 6c 65 0a 62 65 69 6e 67 20 71 75 65 72 69 65  ble.being querie
1fe0: 64 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 2f 64  d..</p></dd>.</d
1ff0: 6c 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  l>.</blockquote>
2000: 0a 0a 3c 68 32 3e 54 65 73 74 69 6e 67 20 66 6f  ..<h2>Testing fo
2010: 72 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  r a complete SQL
2020: 20 73 74 61 74 65 6d 65 6e 74 3c 2f 68 32 3e 0a   statement</h2>.
2030: 0a 3c 70 3e 54 68 65 20 6c 61 73 74 20 69 6e 74  .<p>The last int
2040: 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 20 74  erface routine t
2050: 6f 20 53 51 4c 69 74 65 20 69 73 20 61 20 63 6f  o SQLite is a co
2060: 6e 76 65 6e 69 65 6e 63 65 20 66 75 6e 63 74 69  nvenience functi
2070: 6f 6e 20 75 73 65 64 0a 74 6f 20 74 65 73 74 20  on used.to test 
2080: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  whether or not a
2090: 20 73 74 72 69 6e 67 20 66 6f 72 6d 73 20 61 20   string forms a 
20a0: 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
20b0: 74 65 6d 65 6e 74 2e 0a 49 66 20 74 68 65 20 3c  tement..If the <
20c0: 62 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 74  b>sqlite_complet
20d0: 65 28 29 3c 2f 62 3e 20 66 75 6e 63 74 69 6f 6e  e()</b> function
20e0: 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 77 68   returns true wh
20f0: 65 6e 20 69 74 73 20 69 6e 70 75 74 0a 69 73 20  en its input.is 
2100: 61 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 74  a string, then t
2110: 68 65 20 61 72 67 75 6d 65 6e 74 20 66 6f 72 6d  he argument form
2120: 73 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  s a complete SQL
2130: 20 73 74 61 74 65 6d 65 6e 74 2e 0a 54 68 65 72   statement..Ther
2140: 65 20 61 72 65 20 6e 6f 20 67 75 61 72 61 6e 74  e are no guarant
2150: 65 65 73 20 74 68 61 74 20 74 68 65 20 73 79 6e  ees that the syn
2160: 74 61 78 20 6f 66 20 74 68 61 74 20 73 74 61 74  tax of that stat
2170: 65 6d 65 6e 74 20 69 73 20 63 6f 72 72 65 63 74  ement is correct
2180: 2c 0a 62 75 74 20 77 65 20 61 74 20 6c 65 61 73  ,.but we at leas
2190: 74 20 6b 6e 6f 77 20 74 68 65 20 73 74 61 74 65  t know the state
21a0: 6d 65 6e 74 20 69 73 20 63 6f 6d 70 6c 65 74 65  ment is complete
21b0: 2e 20 20 49 66 20 3c 62 3e 73 71 6c 69 74 65 5f  .  If <b>sqlite_
21c0: 63 6f 6d 70 6c 65 74 65 28 29 3c 2f 62 3e 0a 72  complete()</b>.r
21d0: 65 74 75 72 6e 73 20 66 61 6c 73 65 2c 20 74 68  eturns false, th
21e0: 65 6e 20 6d 6f 72 65 20 74 65 78 74 20 69 73 20  en more text is 
21f0: 72 65 71 75 69 72 65 64 20 74 6f 20 63 6f 6d 70  required to comp
2200: 6c 65 74 65 20 74 68 65 20 53 51 4c 20 73 74 61  lete the SQL sta
2210: 74 65 6d 65 6e 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e  tement.</p>..<p>
2220: 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 20  For the purpose 
2230: 6f 66 20 74 68 65 20 3c 62 3e 73 71 6c 69 74 65  of the <b>sqlite
2240: 5f 63 6f 6d 70 6c 65 74 65 28 29 3c 2f 62 3e 20  _complete()</b> 
2250: 66 75 6e 63 74 69 6f 6e 2c 20 61 6e 20 53 51 4c  function, an SQL
2260: 0a 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f  .statement is co
2270: 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
2280: 73 20 69 6e 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  s in a semicolon
2290: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 3c 62  .</p>..<p>The <b
22a0: 3e 73 71 6c 69 74 65 3c 2f 62 3e 20 63 6f 6d 6d  >sqlite</b> comm
22b0: 61 6e 64 2d 6c 69 6e 65 20 75 74 69 6c 69 74 79  and-line utility
22c0: 20 75 73 65 73 20 74 68 65 20 3c 62 3e 73 71 6c   uses the <b>sql
22d0: 69 74 65 5f 63 6f 6d 70 6c 65 74 65 28 29 3c 2f  ite_complete()</
22e0: 62 3e 0a 66 75 6e 63 74 69 6f 6e 20 74 6f 20 6b  b>.function to k
22f0: 6e 6f 77 20 77 68 65 6e 20 69 74 20 6e 65 65 64  now when it need
2300: 73 20 74 6f 20 63 61 6c 6c 20 3c 62 3e 73 71 6c  s to call <b>sql
2310: 69 74 65 5f 65 78 65 63 28 29 3c 2f 62 3e 2e 20  ite_exec()</b>. 
2320: 20 41 66 74 65 72 20 65 61 63 68 0a 6c 69 6e 65   After each.line
2330: 20 6f 66 20 69 6e 70 75 74 20 69 73 20 72 65 63   of input is rec
2340: 65 69 76 65 64 2c 20 3c 62 3e 73 71 6c 69 74 65  eived, <b>sqlite
2350: 3c 2f 62 3e 20 63 61 6c 6c 73 20 3c 62 3e 73 71  </b> calls <b>sq
2360: 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 65 28 29 3c  lite_complete()<
2370: 2f 62 3e 0a 6f 6e 20 61 6c 6c 20 69 6e 70 75 74  /b>.on all input
2380: 20 69 6e 20 69 74 73 20 62 75 66 66 65 72 2e 20   in its buffer. 
2390: 20 49 66 20 3c 62 3e 73 71 6c 69 74 65 5f 63 6f   If <b>sqlite_co
23a0: 6d 70 6c 65 74 65 28 29 3c 2f 62 3e 20 72 65 74  mplete()</b> ret
23b0: 75 72 6e 73 20 74 72 75 65 2c 20 0a 74 68 65 6e  urns true, .then
23c0: 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 28   <b>sqlite_exec(
23d0: 29 3c 2f 62 3e 20 69 73 20 63 61 6c 6c 65 64 20  )</b> is called 
23e0: 61 6e 64 20 74 68 65 20 69 6e 70 75 74 20 62 75  and the input bu
23f0: 66 66 65 72 20 69 73 20 72 65 73 65 74 2e 20 20  ffer is reset.  
2400: 49 66 0a 3c 62 3e 73 71 6c 69 74 65 5f 63 6f 6d  If.<b>sqlite_com
2410: 70 6c 65 74 65 28 29 3c 2f 62 3e 20 72 65 74 75  plete()</b> retu
2420: 72 6e 73 20 66 61 6c 73 65 2c 20 74 68 65 6e 20  rns false, then 
2430: 74 68 65 20 70 72 6f 6d 70 74 20 69 73 20 63 68  the prompt is ch
2440: 61 6e 67 65 64 20 74 6f 0a 74 68 65 20 63 6f 6e  anged to.the con
2450: 74 69 6e 75 61 74 69 6f 6e 20 70 72 6f 6d 70 74  tinuation prompt
2460: 20 61 6e 64 20 61 6e 6f 74 68 65 72 20 6c 69 6e   and another lin
2470: 65 20 6f 66 20 74 65 78 74 20 69 73 20 72 65 61  e of text is rea
2480: 64 20 61 6e 64 20 61 64 64 65 64 20 74 6f 0a 74  d and added to.t
2490: 68 65 20 69 6e 70 75 74 20 62 75 66 66 65 72 2e  he input buffer.
24a0: 3c 2f 70 3e 0a 0a 3c 68 32 3e 55 73 61 67 65 20  </p>..<h2>Usage 
24b0: 45 78 61 6d 70 6c 65 73 3c 2f 68 32 3e 0a 0a 3c  Examples</h2>..<
24c0: 70 3e 46 6f 72 20 65 78 61 6d 70 6c 65 73 20 6f  p>For examples o
24d0: 66 20 68 6f 77 20 74 68 65 20 53 51 4c 69 74 65  f how the SQLite
24e0: 20 43 2f 43 2b 2b 20 69 6e 74 65 72 66 61 63 65   C/C++ interface
24f0: 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 72 65   can be used,.re
2500: 66 65 72 20 74 6f 20 74 68 65 20 73 6f 75 72 63  fer to the sourc
2510: 65 20 63 6f 64 65 20 66 6f 72 20 74 68 65 20 3c  e code for the <
2520: 62 3e 73 71 6c 69 74 65 3c 2f 62 3e 20 70 72 6f  b>sqlite</b> pro
2530: 67 72 61 6d 20 69 6e 20 74 68 65 0a 66 69 6c 65  gram in the.file
2540: 20 3c 62 3e 73 72 63 2f 73 68 65 6c 6c 2e 63 3c   <b>src/shell.c<
2550: 2f 62 3e 20 6f 66 20 74 68 65 20 73 6f 75 72 63  /b> of the sourc
2560: 65 20 74 72 65 65 2e 0a 41 64 64 69 74 69 6f 6e  e tree..Addition
2570: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  al information a
2580: 62 6f 75 74 20 73 71 6c 69 74 65 20 69 73 20 61  bout sqlite is a
2590: 76 61 69 6c 61 62 6c 65 20 61 74 0a 3c 61 20 68  vailable at.<a h
25a0: 72 65 66 3d 22 73 71 6c 69 74 65 2e 68 74 6d 6c  ref="sqlite.html
25b0: 22 3e 73 71 6c 69 74 65 2e 68 74 6d 6c 3c 2f 61  ">sqlite.html</a
25c0: 3e 2e 0a 53 65 65 20 61 6c 73 6f 20 74 68 65 20  >..See also the 
25d0: 73 6f 75 72 63 65 73 20 74 6f 20 74 68 65 20 54  sources to the T
25e0: 63 6c 20 69 6e 74 65 72 66 61 63 65 20 66 6f 72  cl interface for
25f0: 20 53 51 4c 69 74 65 20 69 6e 0a 74 68 65 20 73   SQLite in.the s
2600: 6f 75 72 63 65 20 66 69 6c 65 20 3c 62 3e 73 72  ource file <b>sr
2610: 63 2f 74 63 6c 73 71 6c 69 74 65 2e 63 3c 2f 62  c/tclsqlite.c</b
2620: 3e 2e 3c 2f 70 3e 0a 7d 0a 0a 70 75 74 73 20 7b  >.</p>.}..puts {
2630: 0a 3c 70 3e 3c 68 72 20 2f 3e 3c 2f 70 3e 0a 3c  .<p><hr /></p>.<
2640: 70 3e 3c 61 20 68 72 65 66 3d 22 69 6e 64 65 78  p><a href="index
2650: 2e 68 74 6d 6c 22 3e 3c 69 6d 67 20 73 72 63 3d  .html"><img src=
2660: 22 2f 67 6f 62 61 63 6b 2e 6a 70 67 22 20 62 6f  "/goback.jpg" bo
2670: 72 64 65 72 3d 30 20 2f 3e 0a 42 61 63 6b 20 74  rder=0 />.Back t
2680: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 48 6f 6d  o the SQLite Hom
2690: 65 20 50 61 67 65 3c 2f 61 3e 0a 3c 2f 70 3e 0a  e Page</a>.</p>.
26a0: 0a 3c 2f 62 6f 64 79 3e 3c 2f 68 74 6d 6c 3e 7d  .</body></html>}
26b0: 0a                                               .