Documentation Source Text

# The following macros should be defined before this script is
# invoked:
#
# DOC              The toplevel directory of the documentation source tree.
#
# SRC              The toplevel directory of the source code source tree.
#
# TCLSQLITE3C      Name of the amalgamation source file

#
# TH3              The toplevel directory for TH3.  May be an empty string.
#
# SLT              The toplevel directory for SQLLogicTest.  May be an
#                  empty string
#
# TCLFLAGS         Extra C-compiler options needed to link against TCL
................................................................................

all:	base evidence format_evidence matrix doc

private:	base evidence private_evidence matrix doc

fast:	base doc

sqlite3.h: $(TCLSH) $(SRC)/src/sqlite.h.in $(SRC)/manifest.uuid $(SRC)/VERSION
	./$(TCLSH) $(SRC)/tool/mksqlite3h.tcl $(SRC) | \
	sed 's/^SQLITE_API //' >sqlite3.h

# Generate the directory into which generated documentation files will
# be written.
#
docdir:
	mkdir -p doc doc/c3ref doc/matrix doc/matrix/c3ref doc/matrix/syntax

................................................................................
#-------------------------------------------------------------------------

# Source files for the [tclsqlite3.search] executable. 
#
SSRC = $(DOC)/search/searchc.c \
	    $(DOC)/search/parsehtml.c \
	    $(DOC)/search/fts5ext.c \
	    $(TCLSQLITE3C)

# Flags to build [tclsqlite3.search] with.
#
SFLAGS = $(TCLINC) -DSQLITE_THREADSAFE=0 -DSQLITE_ENABLE_FTS5 -DSQLITE_TCLMD5 -DTCLSH -Dmain=xmain

$(TCLSH): $(SSRC)
	$(CC) -O2 -o $@ -I. $(SFLAGS) $(SSRC) $(TCLFLAGS)

# The following macros should be defined before this script is
# invoked:
#
# DOC              The toplevel directory of the documentation source tree.
#
# SRC              The toplevel directory of the source code source tree.
#
# BLD              The directory in which the current source code has been
#                  built using "make sqlite3.c"
#
# TH3              The toplevel directory for TH3.  May be an empty string.
#
# SLT              The toplevel directory for SQLLogicTest.  May be an
#                  empty string
#
# TCLFLAGS         Extra C-compiler options needed to link against TCL
................................................................................

all:	base evidence format_evidence matrix doc

private:	base evidence private_evidence matrix doc

fast:	base doc

sqlite3.h: $(BLD)/sqlite3.h
	cp $(BLD)/sqlite3.h orig-sqlite3.h
	sed 's/^SQLITE_API //' orig-sqlite3.h >sqlite3.h

# Generate the directory into which generated documentation files will
# be written.
#
docdir:
	mkdir -p doc doc/c3ref doc/matrix doc/matrix/c3ref doc/matrix/syntax

................................................................................
#-------------------------------------------------------------------------

# Source files for the [tclsqlite3.search] executable. 
#
SSRC = $(DOC)/search/searchc.c \
	    $(DOC)/search/parsehtml.c \
	    $(DOC)/search/fts5ext.c \
	    $(BLD)/tclsqlite3.c

# Flags to build [tclsqlite3.search] with.
#
SFLAGS = $(TCLINC) -DSQLITE_THREADSAFE=0 -DSQLITE_ENABLE_FTS5 -DSQLITE_TCLMD5 -DTCLSH -Dmain=xmain

$(TCLSH): $(SSRC)
	$(CC) -O2 -o $@ -I. $(SFLAGS) $(SSRC) $(TCLFLAGS)

      set uri [convert_keyword_to_uri $kw]
      incr funccnts($s)
      dbtoc eval {INSERT INTO toc(name,type,status,title,uri)
                   VALUES($kw,'function',$s,$title,$uri)}
    }
  }
}



hd_open_aux c3ref/funclist.html
hd_header {List Of SQLite Functions}
hd_keywords *capi3ref_funclist {C-API function list}
hd_enable_main 0
hd_putsnl {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1
</tcl>

      set uri [convert_keyword_to_uri $kw]
      incr funccnts($s)
      dbtoc eval {INSERT INTO toc(name,type,status,title,uri)
                   VALUES($kw,'function',$s,$title,$uri)}
    }
  }
}
#puts "content=[list $content]"
#puts "supported=[list [array get supported]]"
#puts "funccnts=[list [array get funccnts]]
hd_open_aux c3ref/funclist.html
hd_header {List Of SQLite Functions}
hd_keywords *capi3ref_funclist {C-API function list}
hd_enable_main 0
hd_putsnl {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1
</tcl>

<li> Allow [ATTACH] and [DETACH] commands to work inside of a transaction.
<li> Allow [WITHOUT ROWID virtual tables] to be writable if the PRIMARY KEY
     contains exactly one column.
<li> Query planner enhancements:
<ol type="a">
<li> Enhanced the [LIKE optimization] so that it works with an ESCAPE clause.
</ol>
<li> Miscellaneous [microoptimizations] reduce CPU usage by about 0.4%.
<li> Bug fixes:
<ol type="a">
<li> Fix a faulty assert() statement discovered by OSSFuzz.
     Ticket [https://sqlite.org/src/info/cb91bf4290c211d|cb91bf4290c211d]
</ol>
}










chng {2017-08-01 (3.20.0)} {
<li> Update the text of error messages returned by [sqlite3_errmsg()] for some
     error codes.
<li> Add new [pointer passing interfaces].
<li> Backwards-incompatible changes to some extensions in order to take 
     advantage of the improved security offered by the new 

<li> Allow [ATTACH] and [DETACH] commands to work inside of a transaction.
<li> Allow [WITHOUT ROWID virtual tables] to be writable if the PRIMARY KEY
     contains exactly one column.
<li> Query planner enhancements:
<ol type="a">
<li> Enhanced the [LIKE optimization] so that it works with an ESCAPE clause.
</ol>
<li> Miscellaneous [microoptimizations] reduce CPU usage by about 1.6%.
<li> Bug fixes:
<ol type="a">
<li> Fix a faulty assert() statement discovered by OSSFuzz.
     Ticket [https://sqlite.org/src/info/cb91bf4290c211d|cb91bf4290c211d]
</ol>
}

chng {2017-08-24 (3.20.1)} {
<li> Fix a potential memory leak in the new [sqlite3_result_pointer()] interface.
     Ticket [https://sqlite.org/src/info/7486aa54b968e9b5|7486aa54b968e9b5].
<p><b>Hashes:</b>
<li>SQLITE_SOURCE_ID: "2017-08-24 16:21:36 8d3a7ea6c5690d6b7c3767558f4f01b511c55463e3f9e64506801fe9b74dce34"
<li>SHA3-256 for sqlite3.c: 93b1a6d69b48dc39697d1d3a1e4c30b55da0bdd2cad0c054462f91081832954a
} {patchagainst 1}


chng {2017-08-01 (3.20.0)} {
<li> Update the text of error messages returned by [sqlite3_errmsg()] for some
     error codes.
<li> Add new [pointer passing interfaces].
<li> Backwards-incompatible changes to some extensions in order to take 
     advantage of the improved security offered by the new 

#
# A small amount of manual editing and de-duplication followed.
#
# Manually edit the list for each subsequent release.
#      
foreach line [split {
xxxxxxxxxx|pending|Version 3.21.0

9501e22dfe|2017-08-01|Version 3.20.0
036ebf729e|2017-06-17|Version 3.18.2
77bb46233d|2017-06-16|Version 3.18.1
0ee482a1e0|2017-06-08|Version 3.19.3
edb4e819b0|2017-05-25|Version 3.19.2
f6d7b988f4|2017-05-24|Version 3.19.1
28a94eb282|2017-05-22|Version 3.19.0

#
# A small amount of manual editing and de-duplication followed.
#
# Manually edit the list for each subsequent release.
#      
foreach line [split {
xxxxxxxxxx|pending|Version 3.21.0
8d3a7ea6c5|2017-08-24|Version 3.20.1
9501e22dfe|2017-08-01|Version 3.20.0
036ebf729e|2017-06-17|Version 3.18.2
77bb46233d|2017-06-16|Version 3.18.1
0ee482a1e0|2017-06-08|Version 3.19.3
edb4e819b0|2017-05-25|Version 3.19.2
f6d7b988f4|2017-05-24|Version 3.19.1
28a94eb282|2017-05-22|Version 3.19.0

large amounts of comma-separated value content.
The CSV virtual table is also useful as a template source file for
implementing other virtual tables.
</p>


<p>
The CVS virtual table is not built into the SQLite amalgamation.
It is available as a
[https://www.sqlite.org/src/artifact?ci=trunk&filename=ext/misc/csv.c|separate source file]
that can be compiled into a [loadable extension].
Typical usage of the CSV virtual table from the
[command-line shell] would be something like this:

<codeblock>
................................................................................

<li><p><b>data=</b><i>TEXT</i>
<p>The <b>data=</b> argument specifies that <i>TEXT</i> is the literal
content of the CSV file.

<li><p><b>schema=</b><i>SCHEMA</i>
<p> The <b>schema=</b> argument specifies a [CREATE TABLE] statement that
the CVS virtual table passes to the [sqlite3_declare_vtab()] interface in
order to define the number and names of the columns in the virtual table.
If both the <b>schema=</b> and the <b>columns=</b> arguments are omitted,
then the CVS virtual table reads the first row of the input content in order
to determine the number of columns and names the columns <b>cNNN</b> where
<b>NNN</b> values are consecutive integers.  It is not allowed to have
both <b>schema=</b> and <b>columns=</b> arguments.

<li><p><b>columns=</b><i>N</i>
<p>The <b>columns=</b><i>N</i> argument causes the virtual table to have
exactly <i>N</i> columns.  If the input data contains more columns than this,
then the excess columns are ignored.  If the input data contains fewer columns,
then extra columns are filled with NULL.
</u>

large amounts of comma-separated value content.
The CSV virtual table is also useful as a template source file for
implementing other virtual tables.
</p>


<p>
The CSV virtual table is not built into the SQLite amalgamation.
It is available as a
[https://www.sqlite.org/src/artifact?ci=trunk&filename=ext/misc/csv.c|separate source file]
that can be compiled into a [loadable extension].
Typical usage of the CSV virtual table from the
[command-line shell] would be something like this:

<codeblock>
................................................................................

<li><p><b>data=</b><i>TEXT</i>
<p>The <b>data=</b> argument specifies that <i>TEXT</i> is the literal
content of the CSV file.

<li><p><b>schema=</b><i>SCHEMA</i>
<p> The <b>schema=</b> argument specifies a [CREATE TABLE] statement that
the CSV virtual table passes to the [sqlite3_declare_vtab()] interface in
order to define the number and names of the columns in the virtual table.
If both the <b>schema=</b> and the <b>columns=</b> arguments are omitted,
then the CSV virtual table reads the first row of the input content in order
to determine the number of columns and names the columns <b>cNNN</b> where
<b>NNN</b> values are consecutive integers.  It is not allowed to have
both <b>schema=</b> and <b>columns=</b> arguments.

<li><p><b>columns=</b><i>N</i>
<p>The <b>columns=</b><i>N</i> argument causes the virtual table to have
exactly <i>N</i> columns.  If the input data contains more columns than this,
then the excess columns are ignored.  If the input data contains fewer columns,
then extra columns are filled with NULL.
</u>

Note that a recent version of <a href="http://www.tcl-lang.org/">Tcl</a>
is required in order to build from the repository sources. 
The [amalgamation] source code files
(the "sqlite3.c" and "sqlite3.h" files) build products and are
not contained in raw source code tree.</p>

<blockquote>
<a href="http://www.sqlite.org/cgi/src">http://www.sqlite.org/cgi/src</a> (Dallas)<br>
<a href="http://www2.sqlite.org/cgi/src">http://www2.sqlite.org/cgi/src</a> (Newark)<br>
<a href="http://www3.sqlite.org/cgi/src">http://www3.sqlite.org/cgi/src</a> (Fremont)<br>
</blockquote>

<p>The documentation is maintained in separate
[http://www.fossil-scm.org/ | Fossil] repositories located
at:</p>

<blockquote>
<a href="http://www.sqlite.org/cgi/docsrc">http://www.sqlite.org/cgi/docsrc</a> (Dallas)<br>
<a href="http://www2.sqlite.org/cgi/docsrc">http://www2.sqlite.org/cgi/docsrc</a> (Newark)<br>
<a href="http://www3.sqlite.org/cgi/docsrc">http://www3.sqlite.org/cgi/docsrc</a> (Fremont)<br>
</blockquote>
<tcl>
proc set_download_hyperlinks {} {
  set script "<script type='text/JavaScript'>\n"
  append script "/* <!\[CDATA\[ */\n"
  append script "function adce4d016d6cd()\173\n"
  append script "function d391(a,b){document.getElementById(a).href=b;}\n"

Note that a recent version of <a href="http://www.tcl-lang.org/">Tcl</a>
is required in order to build from the repository sources. 
The [amalgamation] source code files
(the "sqlite3.c" and "sqlite3.h" files) build products and are
not contained in raw source code tree.</p>

<blockquote>
<a href="https://www.sqlite.org/cgi/src">https://www.sqlite.org/cgi/src</a> (Dallas)<br>
<a href="https://www2.sqlite.org/cgi/src">https://www2.sqlite.org/cgi/src</a> (Newark)<br>
<a href="https://www3.sqlite.org/cgi/src">https://www3.sqlite.org/cgi/src</a> (San Francisco)<br>
</blockquote>

<p>The documentation is maintained in separate
[http://www.fossil-scm.org/ | Fossil] repositories located
at:</p>

<blockquote>
<a href="https://www.sqlite.org/cgi/docsrc">https://www.sqlite.org/cgi/docsrc</a> (Dallas)<br>
<a href="https://www2.sqlite.org/cgi/docsrc">https://www2.sqlite.org/cgi/docsrc</a> (Newark)<br>
<a href="https://www3.sqlite.org/cgi/docsrc">https://www3.sqlite.org/cgi/docsrc</a> (San Francisco)<br>
</blockquote>
<tcl>
proc set_download_hyperlinks {} {
  set script "<script type='text/JavaScript'>\n"
  append script "/* <!\[CDATA\[ */\n"
  append script "function adce4d016d6cd()\173\n"
  append script "function d391(a,b){document.getElementById(a).href=b;}\n"

  ** handle (accessible using sqlite3_errcode()/errmsg()).
  */</i>
  fts5_api *fts5_api_from_db(sqlite3 *db){
    fts5_api *pRet = 0;
    sqlite3_stmt *pStmt = 0;

    if( SQLITE_OK==sqlite3_prepare(db, "SELECT fts5(?1)", -1, &pStmt, 0) ){
      sqlite3_bind_pointer(pStmt, (void*)&pRet, "fts5_api_ptr");
      sqlite3_step(pStmt);
    }
    sqlite3_finalize(pStmt);
    return pRet;
  }
</codeblock>

  ** handle (accessible using sqlite3_errcode()/errmsg()).
  */</i>
  fts5_api *fts5_api_from_db(sqlite3 *db){
    fts5_api *pRet = 0;
    sqlite3_stmt *pStmt = 0;

    if( SQLITE_OK==sqlite3_prepare(db, "SELECT fts5(?1)", -1, &pStmt, 0) ){
      sqlite3_bind_pointer(pStmt, (void*)&pRet, "fts5_api_ptr", NULL);
      sqlite3_step(pStmt);
    }
    sqlite3_finalize(pStmt);
    return pRet;
  }
</codeblock>

either downloading a tarball or ZIP archive for a specific version, or
by cloning the entire project history.

<p>SQLite sources are maintained on three geographically dispersed
servers:

<blockquote>
[http://www.sqlite.org/cgi/src] (Dallas)<br>
[http://www2.sqlite.org/cgi/src] (Newark)<br>
[http://www3.sqlite.org/cgi/src] (Fremont)<br>
</blockquote>

<p>The documentation is maintained in separate source repositories on
those same servers:

<blockquote>
[http://www.sqlite.org/cgi/docsrc] (Dallas)<br>
[http://www2.sqlite.org/cgi/docsrc] (Newark)<br>
[http://www3.sqlite.org/cgi/docsrc] (Fremont)<br>
</blockquote>

<p>To download a specific historical version, first locate the specific
version desired by visiting the timeline page on one of these servers
(for example: [http://www.sqlite.org/cgi/src/timeline]).  If
you know the approximate date of the version you want to download, you
can add a query parameter like "c=YYYY-MM-DD" to the "timeline" URL to

either downloading a tarball or ZIP archive for a specific version, or
by cloning the entire project history.

<p>SQLite sources are maintained on three geographically dispersed
servers:

<blockquote>
[https://www.sqlite.org/cgi/src] (Dallas)<br>
[https://www2.sqlite.org/cgi/src] (Newark)<br>
[https://www3.sqlite.org/cgi/src] (San Francisco)<br>
</blockquote>

<p>The documentation is maintained in separate source repositories on
those same servers:

<blockquote>
[https://www.sqlite.org/cgi/docsrc] (Dallas)<br>
[https://www2.sqlite.org/cgi/docsrc] (Newark)<br>
[https://www3.sqlite.org/cgi/docsrc] (San Francisco)<br>
</blockquote>

<p>To download a specific historical version, first locate the specific
version desired by visiting the timeline page on one of these servers
(for example: [http://www.sqlite.org/cgi/src/timeline]).  If
you know the approximate date of the version you want to download, you
can add a query parameter like "c=YYYY-MM-DD" to the "timeline" URL to

  hd_puts "<h3>$date - $title</h3>"
  regsub -all "\n( *\n)+" $text "</p>\n\n<p>" txt
  regsub -all {[Tt]icket #(\d+)} $txt \
      {<a href="http://www.sqlite.org/cvstrac/tktview?tn=\1">\0</a>} txt
  hd_resolve "<blockquote>$txt</blockquote>"
  hd_puts "<hr width=\"50%\">"
}







newsitem {2017-08-01} {Release 3.20.0} {
SQLite [version 3.20.0] is a regularly secheduled maintenance release
of SQLite.
<p>
This release contains many minor enhancements, including:
<ul>

  hd_puts "<h3>$date - $title</h3>"
  regsub -all "\n( *\n)+" $text "</p>\n\n<p>" txt
  regsub -all {[Tt]icket #(\d+)} $txt \
      {<a href="http://www.sqlite.org/cvstrac/tktview?tn=\1">\0</a>} txt
  hd_resolve "<blockquote>$txt</blockquote>"
  hd_puts "<hr width=\"50%\">"
}

newsitem {2017-08-24} {Release 3.20.1} {
The [version 3.20.1] patch release changes two lines of code in
the [sqlite3_result_pointer()] interface in order to fix a rare
memory leak.  There are no other changes relative to [version 3.20.0].
}

newsitem {2017-08-01} {Release 3.20.0} {
SQLite [version 3.20.0] is a regularly secheduled maintenance release
of SQLite.
<p>
This release contains many minor enhancements, including:
<ul>