Documentation Source Text

Check-in [a1c70893c6]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Working on global [...]-style hyperlinks. This is an interim check-in in order to transfer from one machine to another.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: a1c70893c60bfd0166be3ccfa32925095b596d0f
User & Date: drh 2007-12-16 00:42:24
Context
2007-12-18
18:09
SQLite does not have an ! operator. CVSTrac ticket #2849. check-in: 253e0c9a09 user: drh tags: trunk
2007-12-16
00:42
Working on global [...]-style hyperlinks. This is an interim check-in in order to transfer from one machine to another. check-in: a1c70893c6 user: drh tags: trunk
2007-12-15
14:44
Updates to the distinctive features page. check-in: ceb449161d user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/capi3ref.in.

     1      1   <title>C/C++ Interface For SQLite Version 3</title>
     2      2   
     3      3   <h2 class=pdf_section>C/C++ Interface For SQLite Version 3</h2>
     4      4   
     5      5   <tcl>
     6         -set in [open sqlite3.h]
            6  +set in [open sqlite3.h] 
     7      7   set title {}       ;# title of a section of interface definition
     8      8   set type {}        ;# one of: constant datatype function
     9      9   set body {}        ;# human-readable description
    10     10   set code {}        ;# C code of the definition
    11     11   set phase 0        ;# Phase used by the parser 
    12     12   set content {}     ;# List of records, one record per definition
    13     13   set dcnt 0         ;# Number of individual declarations
    14     14   set lineno 0       ;# input file line number
           15  +set intab 0        ;# In a covenents or limitations table
           16  +set inrow 0        ;# In a row of a table
           17  +set rowbody {}     ;# Content of a row
           18  +
           19  +# End a table row or the complete table.
           20  +#
           21  +proc endrow {} {
           22  +  global inrow body rowbody
           23  +  if {$inrow} {
           24  +    append body [string trim $rowbody]</td></tr>\n
           25  +    set inrow 0
           26  +    set rowbody {}
           27  +  }
           28  +}
           29  +proc endtab {} {
           30  +  global intab body
           31  +  endrow
           32  +  if {$intab} {
           33  +    append body "</table>\n"
           34  +    set intab 0
           35  +  }
           36  +}
           37  +proc starttab {} {
           38  +  global intab body
           39  +  endtab
           40  +  append body {<table border="0" cellpadding="5" cellspacing="0">}
           41  +  append body \n
           42  +  set intab 1
           43  +}
    15     44   
    16     45   # Read sqlite3.h line by line and extract interface definition
    17     46   # information.
    18     47   #
    19     48   while {![eof $in]} {
    20     49     set line [gets $in]
    21     50     incr lineno
................................................................................
    31     60         set lx [string trim [string range $line 3 end]]
    32     61         if {[regexp {^CATEGORY: +([a-z]*)} $lx all cx]} {
    33     62           set type $cx
    34     63         } elseif {[regexp {^KEYWORDS: +(.*)} $lx all kx]} {
    35     64           foreach k $kx {
    36     65             set keyword($k) 1
    37     66           }
           67  +      } elseif {[regexp {^COVENANTS:$} $lx]} {
           68  +        append body "\n<h3>Covenants:</h3>\n"
           69  +        starttab
           70  +        set phase 2
           71  +      } elseif {[regexp {^LIMITATIONS:$} $lx]} {
           72  +        append body "\n<h3>Limitations:</h3>\n"
           73  +        starttab
           74  +        set phase 2
    38     75         } else {
    39     76           append body $lx\n
    40     77         }
    41     78       } elseif {[string range $line 0 1]=="*/"} {
    42         -      set phase 2
           79  +      set phase 3
    43     80       }
    44     81     } elseif {$phase==2} {
           82  +    if {[string range $line 0 1]=="**"} {
           83  +      set lx [string trim [string range $line 3 end]]
           84  +      if {[regexp {\{([\w.]+)\}\s+(.+)$} $lx all tag lxtail]} {
           85  +        endrow
           86  +        append body "<tr><td valign=\"top\">$tag</td>\
           87  +                     \n<td valign=\"top\">\n"
           88  +        set rowbody $lxtail\n
           89  +        set inrow 1
           90  +      } elseif {[regexp {^COVENANTS:$} $lx]} {
           91  +        endtab
           92  +        append body "\n<h3>Covenants:</h3>\n"
           93  +        starttab
           94  +      } elseif {[regexp {^LIMITATIONS:$} $lx]} {
           95  +        endtab
           96  +        append body "\n<h3>Limitations:</h3>\n"
           97  +        starttab
           98  +        set phase 2
           99  +      } else {
          100  +        append rowbody $lx\n
          101  +      }
          102  +    } elseif {[string range $line 0 1]=="*/"} {
          103  +      endtab
          104  +      set phase 3
          105  +    }
          106  +  } elseif {$phase==3} {
    45    107       if {$line==""} {
    46    108         set kwlist [lsort [array names keyword]]
    47    109         unset -nocomplain keyword
    48    110         set key $type:$kwlist
    49    111         regsub { *\{[\w.]+\}} $title {} title
    50    112         regsub -all { *\{[\w.]+\}} $body {} body
    51    113         set body [string map \
................................................................................
   349    411     set body [subst -novar -noback $body]
   350    412     puts "$body"
   351    413     puts "<hr>"
   352    414     set fkey [lindex $keywords 0]
   353    415     if {![info exists keyword_to_file($fkey)]} {
   354    416       real_puts fkey=$fkey
   355    417       real_puts c=$c
   356         -    exit
          418  +    error "no such key: $fkey"
   357    419     }
   358    420     c3ref_open_file $::keyword_to_file($fkey) $title
   359    421     puts "<blockquote><pre>"
   360    422     puts "$code"
   361    423     puts "</pre></blockquote>"
   362    424     set body [lindex $c 4]
   363    425     regsub -all "\n\n+" $body "</p>\n\n<p>" body

Changes to pages/conflict.in.

     2      2   
     3      3   <h1>Constraint Conflict Resolution in SQLite</h1>
     4      4   
     5      5   <p>
     6      6   In most SQL databases, if you have a UNIQUE constraint on
     7      7   a table and you try to do an UPDATE or INSERT that violates
     8      8   the constraint, the database will abort the operation in
     9         -progress, back out any prior changes associated with
    10         -UPDATE or INSERT command, and return an error.
    11         -This is the default behavior of SQLite.
    12         -Beginning with version 2.3.0, though, SQLite allows you to
            9  +progress, back out any prior changes associated with the same
           10  +UPDATE or INSERT statement, and return an error.
           11  +This is the default behavior of SQLite, though SQLite also allows one to
    13     12   define alternative ways for dealing with constraint violations.
    14     13   This article describes those alternatives and how to use them.
    15     14   </p>
    16     15   
    17     16   <h2>Conflict Resolution Algorithms</h2>
    18     17   
    19     18   <p>
................................................................................
    39     38   <dt><b>FAIL</b></dt>
    40     39   <dd><p>When a constraint violation occurs, the command aborts with a
    41     40   return code SQLITE_CONSTRAINT.  But any changes to the database that
    42     41   the command made prior to encountering the constraint violation
    43     42   are preserved and are not backed out.  For example, if an UPDATE
    44     43   statement encountered a constraint violation on the 100th row that
    45     44   it attempts to update, then the first 99 row changes are preserved
    46         -by change to rows 100 and beyond never occur.</p></dd>
           45  +but change to rows 100 and beyond never occur.</p></dd>
    47     46   
    48     47   <dt><b>IGNORE</b></dt>
    49     48   <dd><p>When a constraint violation occurs, the one row that contains
    50     49   the constraint violation is not inserted or changed.  But the command
    51     50   continues executing normally.  Other rows before and after the row that
    52     51   contained the constraint violation continue to be inserted or updated
    53     52   normally.  No error is returned.</p></dd>
................................................................................
    54     53   
    55     54   <dt><b>REPLACE</b></dt>
    56     55   <dd><p>When a UNIQUE constraint violation occurs, the pre-existing row
    57     56   that caused the constraint violation is removed prior to inserting
    58     57   or updating the current row.  Thus the insert or update always occurs.
    59     58   The command continues executing normally.  No error is returned.</p></dd>
    60     59   </dl>
    61         -
    62         -<h2>Why So Many Choices?</h2>
    63         -
    64         -<p>SQLite provides multiple conflict resolution algorithms for a
    65         -couple of reasons.  First, SQLite tries to be roughly compatible with as
    66         -many other SQL databases as possible, but different SQL database
    67         -engines exhibit different conflict resolution strategies.  For
    68         -example, PostgreSQL always uses ROLLBACK, Oracle always uses ABORT, and
    69         -MySQL usually uses FAIL but can be instructed to use IGNORE or REPLACE.
    70         -By supporting all five alternatives, SQLite provides maximum
    71         -portability.</p>
    72         -
    73         -<p>Another reason for supporting multiple algorithms is that sometimes
    74         -it is useful to use an algorithm other than the default.
    75         -Suppose, for example, you are
    76         -inserting 1000 records into a database, all within a single
    77         -transaction, but one of those records is malformed and causes
    78         -a constraint error.  Under PostgreSQL or Oracle, none of the
    79         -1000 records would get inserted.  In MySQL, some subset of the
    80         -records that appeared before the malformed record would be inserted
    81         -but the rest would not.  Neither behavior is especially helpful.
    82         -What you really want is to use the IGNORE algorithm to insert
    83         -all but the malformed record.</p>

Deleted pages/requirements.in.

     1         -<title>SQLite Requirements</title>
     2         -
     3         -<h2>SQLite Requirements</h2>
     4         -
     5         -<p>This document is a work in progress.</p>
     6         -
     7         -<p>The goal of this document is to provide an precise and exact
     8         -definition of what SQLite does, how it works, and what to expect
     9         -from SQLite for any given input.  When completed, this document
    10         -will become the authoritative reference for using SQLite.</p>
    11         -
    12         -<h3>The C/C++ Interface</h3>
    13         -
    14         -<table cellspacing="20" border="0">
    15         -
    16         -<tcl>
    17         -# Extract requirements from the sqlite3.h header file
    18         -#
    19         -set in [open sqlite3.h]
    20         -set title {}       ;# Title of an interface
    21         -set body {}        ;# human-readable description
    22         -set code {}        ;# C code of the definition
    23         -set phase 0        ;# Phase used by the parser 
    24         -set reqlist {}     ;# List of requirements, on record per requirement entry
    25         -set dcnt 0         ;# Number of individual declarations
    26         -set lineno 0       ;# input file line number
    27         -
    28         -# Split the input string $in at the first {...} marker.  Store the text
    29         -# before the marker in the prefixvar.  Store the content of the marker
    30         -# in tagvar.  And store the text after the marker in tailvar.
    31         -#
    32         -proc split_text {in prefixvar tagvar tailvar} {
    33         -  if {[regexp -indices {\{[\w.]+\}} $in i]} {
    34         -    upvar 1 $prefixvar prefix
    35         -    upvar 1 $tagvar tag
    36         -    upvar 1 $tailvar tail
    37         -    foreach {front back} $i break
    38         -    set x0 [expr {$front-1}]
    39         -    set prefix [string range $in 0 $x0]
    40         -    set x1 [expr {$front+1}]
    41         -    set x2 [expr {$back-1}]
    42         -    set tag [string range $in $x1 $x2]
    43         -    set x3 [expr {$back+1}]
    44         -    set tail [string range $in $x3 end]
    45         -    return 1
    46         -  } else {
    47         -    return 0
    48         -  }
    49         -}
    50         -
    51         -# Convert a tag name into the filename used for the
    52         -# multi-file version.
    53         -#
    54         -# Constants begin with SQLITE_.  The names are converted
    55         -# to lower case and prefixed with "c_".  If we did not
    56         -# do this, then the names "SQLITE_BLOB" and "sqlite3_blob"
    57         -# would collide.
    58         -#
    59         -proc convert_tag_name {oldname} {
    60         -  set oldname [string tolower $oldname]
    61         -  regsub {^sqlite_} $oldname {c_} oldname
    62         -  regsub {^sqlite3_} $oldname {} name
    63         -  return $name.html
    64         -}
    65         -
    66         -# Read sqlite3.h line by line and extract interface definition
    67         -# information.
    68         -#
    69         -while {![eof $in]} {
    70         -  set line [gets $in]
    71         -  incr lineno
    72         -  if {$phase==0} {
    73         -    # Looking for the CAPI3REF: keyword
    74         -    if {[regexp {^\*\* CAPI3REF: +(.*)} $line all tx]} {
    75         -      set title $tx
    76         -      set title_lineno $lineno
    77         -      set phase 1
    78         -    }
    79         -  } elseif {$phase==1} {
    80         -    if {[string range $line 0 1]=="**"} {
    81         -      set lx [string trim [string range $line 3 end]]
    82         -      if {[regexp {^CATEGORY: +([a-z]*)} $lx all cx]} {
    83         -        set type $cx
    84         -      } elseif {[regexp {^KEYWORDS: +(.*)} $lx all kx]} {
    85         -        foreach k $kx {
    86         -          set keyword($k) 1
    87         -        }
    88         -      } else {
    89         -        append body $lx\n
    90         -      }
    91         -    } elseif {[string range $line 0 1]=="*/"} {
    92         -      set phase 2
    93         -    }
    94         -  } elseif {$phase==2} {
    95         -    if {$line==""} {
    96         -      set kwlist [lsort [array names keyword]]
    97         -      set docfile [convert_tag_name [lindex $kwlist 0]]
    98         -      unset -nocomplain keyword
    99         -      set key $type:$kwlist
   100         -      if {[regexp {\{([\w.]+)\}} $title all tag]} {
   101         -        regsub { *\{[\w.]+\}} $title {} title
   102         -        if {$dcnt>1} {set d declarations} {set d {a declaration}}
   103         -        set code [string map {& &amp; < &lt; > &gt;} $code]
   104         -        set req "The \"sqlite3.h\" header file\
   105         -            shall contain $d equivalent to the following:\
   106         -            \n<blockquote><pre>\n$code</pre></blockquote>"
   107         -        regexp {\d+} $tag key
   108         -        lappend reqlist [list $key $tag sqlite3.h $title_lineno $req $docfile]
   109         -      }
   110         -      set x $body
   111         -      while {[split_text $x prefix tag suffix]} {
   112         -        if {![split_text $suffix req endtag tail]} {
   113         -          set req $suffix
   114         -          set x {}
   115         -        } elseif {$endtag=="END"} {
   116         -          set x $tail
   117         -        } else {
   118         -          set x "{$endtag} $tail"
   119         -        }
   120         -        regsub -all {\[([^]|]+\|)?([^]]+)\]} $req {\2} req
   121         -        #regsub -all {\s+} $req { } req
   122         -        set req [string trim $req]
   123         -        set req [string map \
   124         -          {<todo> {<font color="red">(TODO: } </todo> )</font>} $req]
   125         -        regexp {\d+} $tag key
   126         -        lappend reqlist [list $key $tag sqlite3.h $title_lineno $req $docfile]
   127         -      }
   128         -      set title {}
   129         -      set keywords {}
   130         -      set type {}
   131         -      set body {}
   132         -      set code {}
   133         -      set phase 0
   134         -      set dcnt 0
   135         -    } else {
   136         -      if {[regexp {^#define (SQLITE_[A-Z0-9_]+)} $line all kx]} {
   137         -        set type constant
   138         -        set keyword($kx) 1
   139         -        incr dcnt
   140         -      } elseif {[regexp {^typedef .*(sqlite[0-9a-z_]+);} $line all kx]} {
   141         -        set type datatype
   142         -        set keyword($kx) 1
   143         -        incr dcnt
   144         -      } elseif {[regexp {^[a-z].*[ *](sqlite3_[a-z0-9_]+)\(} $line all kx]} {
   145         -        set type function
   146         -        set keyword($kx) 1
   147         -        incr dcnt
   148         -      } elseif {[regexp {^SQLITE_EXTERN .*(sqlite[0-9a-z_]+);} $line all kx]} {
   149         -        set type datatype
   150         -        set keyword($kx) 1
   151         -        incr dcnt
   152         -      }
   153         -      append code $line\n
   154         -    }
   155         -  }
   156         -}
   157         -
   158         -set dbfd [open reqdb.sql w]
   159         -foreach req [lsort -index 0 $reqlist] {
   160         -  foreach {key tag file lineno text docfile} $req break
   161         -  puts "<tr><td valign=\"top\"><a href=\"c3ref/$docfile\">$tag</a></td>"
   162         -  puts "<td valign=\"top\">$text</td></tr>"
   163         -  set qtext [string map {' ''} $text]
   164         -  real_puts $dbfd "INSERT INTO req VALUES('$tag','$file',$lineno,'$qtext');"
   165         -}
   166         -close $dbfd
   167         -</tcl>
   168         -
   169         -</table>

Added pages/specification.in.

            1  +<title>SQLite Requirements</title>
            2  +
            3  +<h2>SQLite Specifications</h2>
            4  +
            5  +<p>This document is a work in progress.</p>
            6  +
            7  +<p>The goal of this document is to provide an precise and exact
            8  +definition of what SQLite does, how it works, and what to expect
            9  +from SQLite for any given input.  When completed, this document
           10  +will become the authoritative reference for using SQLite.</p>
           11  +
           12  +<h3>The C/C++ Interface</h3>
           13  +
           14  +<table cellspacing="20" border="0">
           15  +
           16  +<tcl>
           17  +# Initialization the specification array
           18  +#
           19  +unset -nocomplain spec
           20  +
           21  +# Extract specifications from the sqlite3.h header file
           22  +#
           23  +set in [open sqlite3.h] 
           24  +set title {}       ;# title of a section of interface definition
           25  +set code {}        ;# C code of the definition
           26  +set phase 0        ;# Phase used by the parser 
           27  +set dcnt 0         ;# Number of individual declarations
           28  +set lineno 0       ;# input file line number
           29  +set spectag {}     ;# Current specification tag number
           30  +set specbody {}    ;# Text of current specification
           31  +
           32  +proc endspec {} {
           33  +  global spectag specbody spec
           34  +  if {$spectag!="" && $specbody!=""} {
           35  +    if {[info exists spec($spectag)]} {
           36  +       real_puts "WARNING: duplicate specification: $spectag"
           37  +    }
           38  +    set body [string map \
           39  +          {<todo> {<font color="red">(TODO: } </todo> )</font>} $specbody]
           40  +    set spec($spectag) [string trim $body]
           41  +  }
           42  +  set spectag {}
           43  +  set specbody {}
           44  +}
           45  +proc beginspec {tag body} {
           46  +  global spectag specbody
           47  +  endspec
           48  +  set spectag $tag
           49  +  set specbody $body
           50  +}
           51  +
           52  +# Read sqlite3.h line by line and extract interface definition
           53  +# information.
           54  +#
           55  +while {![eof $in]} {
           56  +  set line [gets $in]
           57  +  incr lineno
           58  +  if {$phase==0} {
           59  +    # Looking for the CAPI3REF: keyword
           60  +    if {[regexp {^\*\* CAPI3REF: +(.*)} $line all tx]} {
           61  +      set title $tx
           62  +      set title_lineno $lineno
           63  +      set phase 1
           64  +    }
           65  +  } elseif {$phase==1} {
           66  +    if {[string range $line 0 1]=="**"} {
           67  +      set lx [string trim [string range $line 3 end]]
           68  +      if {[regexp {^COVENANTS:$} $lx]} {
           69  +        set phase 2
           70  +      } elseif {[regexp {^LIMITATIONS:$} $lx]} {
           71  +        set phase 2
           72  +      }
           73  +    } elseif {[string range $line 0 1]=="*/"} {
           74  +      set phase 3
           75  +    }
           76  +  } elseif {$phase==2} {
           77  +    if {[string range $line 0 1]=="**"} {
           78  +      set lx [string trim [string range $line 3 end]]
           79  +      if {[regexp {\{([\w.]+)\}\s+(.+)$} $lx all tag lxtail]} {
           80  +        endspec
           81  +        beginspec $tag $lxtail\n
           82  +      } elseif {[regexp {^COVENANTS:$} $lx]} {
           83  +        endspec
           84  +      } elseif {[regexp {^LIMITATIONS:$} $lx]} {
           85  +        endspec
           86  +      } else {
           87  +        append specbody $lx\n
           88  +      }
           89  +    } elseif {[string range $line 0 1]=="*/"} {
           90  +      endspec
           91  +      set phase 3
           92  +    }
           93  +  } elseif {$phase==3} {
           94  +    if {$line==""} {
           95  +      if {[regexp {\{([\w.]+)\}} $title all tag]} {
           96  +        set bx "The following C/C++ interfaces are defined:\n"
           97  +        append bx <blockquote><pre>\n"
           98  +        set code [string map {& &amp; < &lt; > &gt;} $code]
           99  +        append bx [string trim $code]\n
          100  +        append bx "</pre></blockquote"
          101  +        beginspec $tag $bx
          102  +        endspec
          103  +      }
          104  +      lappend content [list $key $title $type $kwlist $body $code]
          105  +      set title {}
          106  +      set keywords {}
          107  +      set type {}
          108  +      set body {}
          109  +      set code {}
          110  +      set phase 0
          111  +      set dcnt 0
          112  +    } else {
          113  +      if {[regexp {^#define (SQLITE_[A-Z0-9_]+)} $line all kx]} {
          114  +        set type constant
          115  +        set keyword($kx) 1
          116  +        incr dcnt
          117  +      } elseif {[regexp {^typedef .*(sqlite[0-9a-z_]+);} $line all kx]} {
          118  +        set type datatype
          119  +        set keyword($kx) 1
          120  +        incr dcnt
          121  +      } elseif {[regexp {^[a-z].*[ *](sqlite3_[a-z0-9_]+)\(} $line all kx]} {
          122  +        set type function
          123  +        set keyword($kx) 1
          124  +        incr dcnt
          125  +      } elseif {[regexp {^SQLITE_EXTERN .*(sqlite[0-9a-z_]+);} $line all kx]} {
          126  +        set type datatype
          127  +        set keyword($kx) 1
          128  +        incr dcnt
          129  +      }
          130  +      append code $line\n
          131  +    }
          132  +  }
          133  +}
          134  +
          135  +# Convert a tag name into the filename used for the
          136  +# multi-file version.
          137  +#
          138  +# Constants begin with SQLITE_.  The names are converted
          139  +# to lower case and prefixed with "c_".  If we did not
          140  +# do this, then the names "SQLITE_BLOB" and "sqlite3_blob"
          141  +# would collide.
          142  +#
          143  +proc convert_tag_name {oldname} {
          144  +  set oldname [string tolower $oldname]
          145  +  regsub {^sqlite_} $oldname {c_} oldname
          146  +  regsub {^sqlite3_} $oldname {} name
          147  +  return $name.html
          148  +}
          149  +
          150  +</tcl>
          151  +
          152  +</table>

Changes to sqlite.h.in.

    79     79   ** there are major feature enhancements that are forwards compatible
    80     80   ** but not backwards compatible.  The Z value is release number
    81     81   ** and is incremented with
    82     82   ** each release but resets back to 0 when Y is incremented.
    83     83   **
    84     84   ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
    85     85   **
    86         -** PROMISES:
           86  +** COVENANTS:
    87     87   **
    88     88   ** {F10011} The SQLITE_VERSION #define in the sqlite3.h header file
    89     89   **          evaluates to a string literal that is the SQLite version
    90     90   **          with which the header file is associated.
    91     91   **
    92     92   ** {F10014} The SQLITE_VERSION_NUMBER #define resolves to an integer
    93     93   **          with the value  (X*1000000 + Y*1000 + Z) where X, Y, and
................................................................................
   107    107   ** [SQLITE_VERSION_NUMBER].
   108    108   **
   109    109   ** The sqlite3_libversion() function returns the same information as is
   110    110   ** in the sqlite3_version[] string constant.  The function is provided
   111    111   ** for use in DLLs since DLL users usually do not have direct access to string
   112    112   ** constants within the DLL.
   113    113   **
   114         -** PROMISES:
          114  +** COVENANTS:
   115    115   **
   116    116   ** {F10021} The [sqlite3_libversion_number()] interface returns an integer
   117    117   **          equal to [SQLITE_VERSION_NUMBER]. 
   118    118   **
   119    119   ** {F10022} The [sqlite3_version] string constant contains the text of the
   120    120   **          [SQLITE_VERSION] string. 
   121    121   **
................................................................................
   140    140   ** the mutexes.  But for maximum safety, mutexes should be enabled.
   141    141   ** The default behavior is for mutexes to be enabled.
   142    142   **
   143    143   ** This interface can be used by a program to make sure that the
   144    144   ** version of SQLite that it is linking against was compiled with
   145    145   ** the desired setting of the SQLITE_THREADSAFE macro.
   146    146   **
   147         -** PROMISES:
          147  +** COVENANTS:
   148    148   **
   149    149   ** {F10101} The [sqlite3_threadsafe()] function returns nonzero if
   150    150   **          SQLite was compiled with its mutexes enabled or zero
   151    151   **          if SQLite was compiled with mutexes disabled.
   152    152   */
   153    153   int sqlite3_threadsafe(void);
   154    154   
................................................................................
   173    173   ** Because there is no cross-platform way to specify 64-bit integer types
   174    174   ** SQLite includes typedefs for 64-bit signed and unsigned integers.
   175    175   **
   176    176   ** The sqlite3_int64 and sqlite3_uint64 are the preferred type
   177    177   ** definitions.  The sqlite_int64 and sqlite_uint64 types are
   178    178   ** supported for backwards compatibility only.
   179    179   **
   180         -** PROMISES:
          180  +** COVENANTS:
   181    181   **
   182    182   ** {F10201} The [sqlite_int64] and [sqlite3_int64] types specify a
   183    183   **          64-bit signed integer.
   184    184   **
   185    185   ** {F10202} The [sqlite_uint64] and [sqlite3_uint64] types specify
   186    186   **          a 64-bit unsigned integer.
   187    187   */
................................................................................
   216    216   ** [sqlite3_blob_close | close] all [sqlite3_blob | BLOBs] 
   217    217   ** associated with the [sqlite3] object prior
   218    218   ** to attempting to close the [sqlite3] object.
   219    219   **
   220    220   ** <todo>What happens to pending transactions?  Are they
   221    221   ** rolled back, or abandoned?</todo>
   222    222   **
   223         -** PROMISES:
          223  +** COVENANTS:
   224    224   **
   225    225   ** {F12011} The [sqlite3_close()] interface destroys an [sqlite3] object
   226    226   **          allocated by a prior call to [sqlite3_open()],
   227    227   **          [sqlite3_open16()], or [sqlite3_open_v2()].
   228    228   **
   229    229   ** {F12012} The [sqlite3_close()] function releases all memory used by the
   230    230   **          connection and closes all open files.
................................................................................
   269    269   **
   270    270   ** The sqlite3_exec() interface is implemented in terms of
   271    271   ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
   272    272   ** The sqlite3_exec() routine does nothing that cannot be done
   273    273   ** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
   274    274   ** The sqlite3_exec() is just a convenient wrapper.
   275    275   **
   276         -** PROMISES:
          276  +** COVENANTS:
   277    277   ** 
   278    278   ** {F12101} The [sqlite3_exec()] interface evaluates zero or more UTF-8
   279    279   **          encoded, semicolon-separated, SQL statements in the
   280    280   **          zero-terminated string of its 2nd parameter within the
   281    281   **          context of the [sqlite3] object given in the 1st parameter.
   282    282   **
   283    283   ** {F12104} The return value of [sqlite3_exec()] is SQLITE_OK if all
................................................................................
   338    338   ** {U12142} The database connection must not be closed while
   339    339   **          [sqlite3_exec()] is running.
   340    340   ** 
   341    341   ** {U12143} The calling function is should use [sqlite3_free()] to free
   342    342   **          the memory that *errmsg is left pointing at once the error
   343    343   **          message is no longer needed.
   344    344   **
   345         -** {U12145} The SQL statement textin 2nd parameter to [sqlite3_exec()]
          345  +** {U12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()]
   346    346   **          must remain unchanged while [sqlite3_exec()] is running.
   347    347   */
   348    348   int sqlite3_exec(
   349    349     sqlite3*,                                  /* An open database */
   350    350     const char *sql,                           /* SQL to be evaluted */
   351    351     int (*callback)(void*,int,char**,char**),  /* Callback function */
   352    352     void *,                                    /* 1st argument to callback */
................................................................................
   361    361   ** here in order to indicates success or failure.
   362    362   **
   363    363   ** See also: [SQLITE_IOERR_READ | extended result codes]
   364    364   */
   365    365   #define SQLITE_OK           0   /* Successful result */
   366    366   /* beginning-of-error-codes */
   367    367   #define SQLITE_ERROR        1   /* SQL error or missing database */
   368         -#define SQLITE_INTERNAL     2   /* NOT USED. Internal logic error in SQLite */
          368  +#define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
   369    369   #define SQLITE_PERM         3   /* Access permission denied */
   370    370   #define SQLITE_ABORT        4   /* Callback routine requested an abort */
   371    371   #define SQLITE_BUSY         5   /* The database file is locked */
   372    372   #define SQLITE_LOCKED       6   /* A table in the database is locked */
   373    373   #define SQLITE_NOMEM        7   /* A malloc() failed */
   374    374   #define SQLITE_READONLY     8   /* Attempt to write a readonly database */
   375    375   #define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/
................................................................................
   411    411   ** One may expect the number of extended result codes will be expand
   412    412   ** over time.  Software that uses extended result codes should expect
   413    413   ** to see new result codes in future releases of SQLite.
   414    414   **
   415    415   ** The SQLITE_OK result code will never be extended.  It will always
   416    416   ** be exactly zero.
   417    417   ** 
   418         -** PROMISES:
          418  +** COVENANTS:
   419    419   **
   420    420   ** {F10223} The symbolic name for an extended result code always contains
   421    421   **          a related primary result code as a prefix.
   422    422   **
   423    423   ** {F10224} Primary result code names contain a single "_" character.
   424    424   **
   425    425   ** {F10225} Extended result code names contain two or more "_" characters.
................................................................................
   821    821   ** CAPI3REF: Enable Or Disable Extended Result Codes {F12200}
   822    822   **
   823    823   ** The sqlite3_extended_result_codes() routine enables or disables the
   824    824   ** [SQLITE_IOERR_READ | extended result codes] feature of SQLite.
   825    825   ** The extended result codes are disabled by default for historical
   826    826   ** compatibility.
   827    827   **
   828         -** PROMISES:
          828  +** COVENANTS:
   829    829   **
   830    830   ** {F12201} New [sqlite3 | database connections] have the 
   831    831   **          [SQLITE_IOERR_READ | extended result codes] feature
   832    832   **          disabled by default.
   833    833   **
   834    834   ** {F12202} The [sqlite3_extended_result_codes()] interface will enable
   835    835   **          [SQLITE_IOERR_READ | extended result codes] for the 
................................................................................
   869    869   ** INSERT continues to completion after deleting rows that caused
   870    870   ** the constraint problem so INSERT OR REPLACE will always change
   871    871   ** the return value of this interface. 
   872    872   **
   873    873   ** For the purposes of this routine, an insert is considered to
   874    874   ** be successful even if it is subsequently rolled back.
   875    875   **
   876         -** PROMISES:
          876  +** COVENANTS:
   877    877   **
   878    878   ** {F12221} The [sqlite3_last_insert_rowid()] function returns the
   879    879   **          rowid of the most recent successful insert done
   880    880   **          on the same database connection and within the same
   881    881   **          trigger context, or zero if there have
   882    882   **          been no qualifying inserts on that connection.
   883    883   **
................................................................................
   942    942   ** faster than going through and deleting individual elements from the
   943    943   ** table.)  Because of this optimization, the deletions in
   944    944   ** "DELETE FROM table" are not row changes and will not be counted
   945    945   ** by the sqlite3_changes() or [sqlite3_total_changes()] functions.
   946    946   ** To get an accurate count of the number of rows deleted, use
   947    947   ** "DELETE FROM table WHERE 1" instead.
   948    948   **
   949         -** PROMISES:
          949  +** COVENANTS:
   950    950   **
   951    951   ** {F12241} The [sqlite3_changes()] function returns the number of
   952    952   **          row changes caused by the most recent INSERT, UPDATE,
   953    953   **          or DELETE statement on the same database connection and
   954    954   **          within the same trigger context, or zero if there have
   955    955   **          not been any qualifying row changes.
   956    956   **
................................................................................
   983    983   ** this optimization, the change count for "DELETE FROM table" will be
   984    984   ** zero regardless of the number of elements that were originally in the
   985    985   ** table. To get an accurate count of the number of rows deleted, use
   986    986   ** "DELETE FROM table WHERE 1" instead.
   987    987   **
   988    988   ** See also the [sqlite3_change()] interface.
   989    989   **
   990         -** PROMISES:
          990  +** COVENANTS:
   991    991   ** 
   992    992   ** {F12261} The [sqlite3_total_changes()] returns the total number
   993    993   **          of row changes caused by INSERT, UPDATE, and/or DELETE
   994    994   **          statements on the same [sqlite3 | database connection], in any
   995    995   **          trigger context, since the database connection was
   996    996   **          created.
   997    997   **
................................................................................
  1023   1023   ** An SQL operation that is interrupted will return
  1024   1024   ** [SQLITE_INTERRUPT].  If the interrupted SQL operation is an
  1025   1025   ** INSERT, UPDATE, or DELETE that is inside an explicit transaction, 
  1026   1026   ** then the entire transaction will be rolled back automatically.
  1027   1027   ** A call to sqlite3_interrupt() has no effect on SQL statements
  1028   1028   ** that are started after sqlite3_interrupt() returns.
  1029   1029   **
  1030         -** PROMISES:
         1030  +** COVENANTS:
  1031   1031   **
  1032   1032   ** {F12271} The [sqlite3_interrupt()] interface will force all running
  1033   1033   **          SQL statements associated with the same database connection
  1034   1034   **          to halt after processing at most one additional row of
  1035   1035   **          data.
  1036   1036   **
  1037   1037   ** {F12272} Any SQL statement that is interrupted by [sqlite3_interrupt()]
................................................................................
  1057   1057   ** string literals or quoted identifier names or comments are not
  1058   1058   ** independent tokens (they are part of the token in which they are
  1059   1059   ** embedded) and thus do not count as a statement terminator.
  1060   1060   **
  1061   1061   ** These routines do not parse the SQL and
  1062   1062   ** so will not detect syntactically incorrect SQL.
  1063   1063   **
  1064         -** PROMISES:
         1064  +** COVENANTS:
  1065   1065   **
  1066   1066   ** {F10511} The sqlite3_complete() and sqlite3_complete16() functions
  1067   1067   **          return true (non-zero) if and only if the last
  1068   1068   **          non-whitespace token in their input is a semicolon that
  1069   1069   **          is not in between the BEGIN and END of a CREATE TRIGGER
  1070   1070   **          statement.
  1071   1071   **
................................................................................
  1135   1135   ** this is important.
  1136   1136   **	
  1137   1137   ** There can only be a single busy handler defined for each database
  1138   1138   ** connection.  Setting a new busy handler clears any previous one. 
  1139   1139   ** Note that calling [sqlite3_busy_timeout()] will also set or clear
  1140   1140   ** the busy handler.
  1141   1141   **
  1142         -** PROMISES:
         1142  +** COVENANTS:
  1143   1143   **
  1144   1144   ** {F12311} The [sqlite3_busy_handler()] function replaces the busy handler
  1145   1145   **          callback in the database connection identified by the 1st
  1146   1146   **          parameter with a new busy handler identified by the 2nd and 3rd
  1147   1147   **          parameters.
  1148   1148   **
  1149   1149   ** {F12312} The default busy handler for new database connections is NULL.
................................................................................
  1182   1182   ** turns off all busy handlers.
  1183   1183   **
  1184   1184   ** There can only be a single busy handler for a particular database
  1185   1185   ** connection.  If another busy handler was defined  
  1186   1186   ** (using [sqlite3_busy_handler()]) prior to calling
  1187   1187   ** this routine, that other busy handler is cleared.
  1188   1188   **
  1189         -** PROMISES:
         1189  +** COVENANTS:
  1190   1190   **
  1191   1191   ** {F12341} The [sqlite3_busy_timeout()] function overrides any prior
  1192   1192   **          [sqlite3_busy_timeout()] or [sqlite3_busy_handler()] setting
  1193   1193   **          on the same database connection.
  1194   1194   **
  1195   1195   ** {F12343} If the 2nd parameter to [sqlite3_busy_timeout()] is less than
  1196   1196   **          or equal to zero, then the busy handler is cleared so that
................................................................................
  1263   1263   ** After the calling function has finished using the result, it should 
  1264   1264   ** pass the pointer to the result table to sqlite3_free_table() in order to 
  1265   1265   ** release the memory that was malloc-ed.  Because of the way the 
  1266   1266   ** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
  1267   1267   ** function must not try to call [sqlite3_free()] directly.  Only 
  1268   1268   ** [sqlite3_free_table()] is able to release the memory properly and safely.
  1269   1269   **
  1270         -** PROMISES:
         1270  +** COVENANTS:
  1271   1271   **
  1272   1272   ** {F12371} If a [sqlite3_get_table()] fails a memory allocation, then
  1273   1273   **          it frees the result table under construction, aborts the
  1274   1274   **          query in process, skips any subsequent queries, sets the
  1275   1275   **          *resultp output pointer to NULL and returns [SQLITE_NOMEM].
  1276   1276   **
  1277   1277   ** {F12373} If the ncolumn parameter to [sqlite3_get_table()] is not NULL
................................................................................
  1389   1389   ** The code above will render a correct SQL statement in the zSQL
  1390   1390   ** variable even if the zText variable is a NULL pointer.
  1391   1391   **
  1392   1392   ** The "%z" formatting option works exactly like "%s" with the
  1393   1393   ** addition that after the string has been read and copied into
  1394   1394   ** the result, [sqlite3_free()] is called on the input string. {END}
  1395   1395   **
  1396         -** PROMISES:
         1396  +** COVENANTS:
  1397   1397   **
  1398   1398   **   
  1399   1399   */
  1400   1400   char *sqlite3_mprintf(const char*,...);
  1401   1401   char *sqlite3_vmprintf(const char*, va_list);
  1402   1402   char *sqlite3_snprintf(int,char*,const char*, ...);
  1403   1403   
................................................................................
  2560   2560   int sqlite3_finalize(sqlite3_stmt *pStmt);
  2561   2561   
  2562   2562   /*
  2563   2563   ** CAPI3REF: Reset A Prepared Statement Object {F13330}
  2564   2564   **
  2565   2565   ** The sqlite3_reset() function is called to reset a 
  2566   2566   ** [sqlite3_stmt | compiled SQL statement] object.
  2567         -** back to it's initial state, ready to be re-executed.
         2567  +** back to its initial state, ready to be re-executed.
  2568   2568   ** Any SQL statement variables that had values bound to them using
  2569   2569   ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
  2570   2570   ** Use [sqlite3_clear_bindings()] to reset the bindings.
  2571   2571   */
  2572   2572   int sqlite3_reset(sqlite3_stmt *pStmt);
  2573   2573   
  2574   2574   /*

Changes to wrap.tcl.

    16     16   #     *  An appropriate header is prepended to the file.  
    17     17   #     *  Any <title>...</title> in the input is moved into the prepended
    18     18   #        header.
    19     19   #     *  An appropriate footer is appended.
    20     20   #     *  Scripts within <tcl>...</tcl> are evaluated.  Output that
    21     21   #        is emitted from these scripts by "puts" appears in place of
    22     22   #        the original script.
           23  +#     *  Hyperlinks within [...] are resolved.
           24  +#
           25  +# 
    23     26   #
    24     27   set DOC [lindex $argv 0]
    25     28   set SRC [lindex $argv 1]
    26     29   set DEST [lindex $argv 2]
    27     30   set HOMEDIR [pwd]            ;# Also remember our home directory.
    28     31   
    29     32   # We are going to overload the puts command, so remember the