Documentation Source Text

Check-in [5856a03e9a]
Login

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

Overview
Comment:Miscellaneous documentation and hyperlink tweaks.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:5856a03e9a64aabbd8f7e44439e29aac0600dcf8
User & Date: drh 2009-05-14 23:56:49
Context
2009-05-18
17:37
Changes in preparation for the 3.6.14.1 release. check-in: 4abdcb6c1c user: drh tags: trunk
2009-05-14
23:56
Miscellaneous documentation and hyperlink tweaks. check-in: 5856a03e9a user: drh tags: trunk
20:45
Better doc_pagelink_crossref.html support. Now catches more hrefs outputted directly via hd_puts. check-in: d0a850961d user: shaneh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/lang.in.

1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
....
1285
1286
1287
1288
1289
1290
1291
1292
1293


1294
1295
1296
1297
1298
1299
1300
....
1669
1670
1671
1672
1673
1674
1675


1676
1677
1678
1679
1680
1681
1682
....
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
....
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
....
2125
2126
2127
2128
2129
2130
2131
2132


2133
2134
2135
2136
2137
2138
2139
2140
X'53514C697465'
</pre></blockquote>

<p>
A literal value can also be the token "NULL".
</p>

<tcl>hd_fragment varparam parameter</tcl>
<h3>Parameters</h3>
<p>
A "variable" or "parameter" token
specifies a placeholder in the expression for a literal
value that is filled in at runtime using the
[sqlite3_bind_blob() | sqlite3_bind()] APIs.
Parameters can take several forms:
</p

<blockquote>
<table>
<tr>
<td align="right" valign="top"><b>?</b><i>NNN</i></td><td width="20"></td>
................................................................................
<td>An "at" sign works exactly like a colon.</td>
</tr>
<tr>
<td align="right" valign="top"><b>$</b><i>AAAA</i></td><td width="20"></td>
<td>A dollar-sign followed by an identifier name also holds a spot for a named
parameter with the name AAAA.  The identifier name in this case can include
one or more occurances of "::" and a suffix enclosed in "(...)" containing
any text at all.  This syntax is the form of a variable name in the Tcl
programming language.</td>


</tr>
</table>
</blockquote>

<p>Parameters that are not assigned values using
[sqlite3_bind_blob() | sqlite3_bind()] are treated
as NULL.</p>
................................................................................
}

funcdef {zeroblob(N)} {} {
  Return a BLOB consisting of N bytes of 0x00.  SQLite
  manages these zeroblobs very efficiently.  Zeroblobs can be used to
  reserve space for a BLOB that is later written using 
  [sqlite3_blob_open() | incremental BLOB I/O].


}
</tcl>
</table>

<tcl>
##############################################################################
Section {Date And Time Functions} datefunc {datefunc}
................................................................................
<p>
The date() function returns the date in this format: YYYY-MM-DD. 
The time() function returns the time as HH:MM:SS. 
The datetime() function returns "YYYY-MM-DD HH:MM:SS". 
The julianday() function returns the 
<a href="http://en.wikipedia.org/wiki/Julian_day">Julian day</a> - 
number of days since noon in Greenwich on November 24, 4714 B.C. 
(<a href="http://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">
Proleptic Gregorian calendar</a>). 
The strftime() routine returns the date formatted according to 
the format string specified as the first argument.
The format string supports the most common substitutions found in the 
<a href="http://opengroup.org/onlinepubs/007908799/xsh/strftime.html">
strftime() function</a> from 
the standard C library plus two new substitutions, %f and %J.
The following is a complete list of valid strftime() substitutions:
................................................................................
Notice that all other date and time functions can be expressed
in terms of strftime():
</p>

<blockquote>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td><b>Function</b><td width="30"><td><b>Equivalent strftime()</b>
<tr><td>   date(...)      <td><td>  strftime("%Y-%m-%d", ...)
<tr><td>   time(...)      <td><td>  strftime("%H:%M:%S", ...)
<tr><td>   datetime(...)  <td><td>  strftime("%Y-%m-%d %H:%M:%S", ...)
<tr><td>   julianday(...) <td><td>  strftime("%J", ...)
</table>
</blockquote>

<p>
The only reasons for providing functions other than strftime() is
for convenience and for efficiency.
</p>
................................................................................
The command continues executing normally.  No error is returned.
If a NOT NULL constraint violation occurs, the NULL value is replaced
by the default value for that column.  If the column has no default
value, then the ABORT algorithm is used.  If a CHECK constraint violation
occurs then the IGNORE algorithm is used.</p>

<p>When this conflict resolution strategy deletes rows in order to
satisfy a constraint, it does not invoke delete triggers on those


rows.  This behavior might change in a future release.</p>
</dl>

<p>The algorithm specified in the OR clause of a INSERT or UPDATE
overrides any algorithm specified in a CREATE TABLE.
If no algorithm is specified anywhere, the ABORT algorithm is used.</p>

<tcl>







|





|







 







|
|
>
>







 







>
>







 







|
|







 







|
|
|
|







 







|
>
>
|







1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
....
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
....
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
....
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
....
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
....
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
X'53514C697465'
</pre></blockquote>

<p>
A literal value can also be the token "NULL".
</p>

<tcl>hd_fragment varparam parameter parameters</tcl>
<h3>Parameters</h3>
<p>
A "variable" or "parameter" token
specifies a placeholder in the expression for a literal
value that is filled in at runtime using the
[sqlite3_bind_blob() | sqlite3_bind()] family of C/C++ interfaces.
Parameters can take several forms:
</p

<blockquote>
<table>
<tr>
<td align="right" valign="top"><b>?</b><i>NNN</i></td><td width="20"></td>
................................................................................
<td>An "at" sign works exactly like a colon.</td>
</tr>
<tr>
<td align="right" valign="top"><b>$</b><i>AAAA</i></td><td width="20"></td>
<td>A dollar-sign followed by an identifier name also holds a spot for a named
parameter with the name AAAA.  The identifier name in this case can include
one or more occurances of "::" and a suffix enclosed in "(...)" containing
any text at all.  This syntax is the form of a variable name in the
<a href="http://www.tcl.tk/">Tcl programming language</a>.  The presence
of this syntax results from the fact that SQLite is really a 
[Tcl extension] that has escaped into the wild.</td>
</tr>
</table>
</blockquote>

<p>Parameters that are not assigned values using
[sqlite3_bind_blob() | sqlite3_bind()] are treated
as NULL.</p>
................................................................................
}

funcdef {zeroblob(N)} {} {
  Return a BLOB consisting of N bytes of 0x00.  SQLite
  manages these zeroblobs very efficiently.  Zeroblobs can be used to
  reserve space for a BLOB that is later written using 
  [sqlite3_blob_open() | incremental BLOB I/O].
  This SQL function is implemented using the [sqlite3_result_zeroblob()]
  routine from the C/C++ interface.
}
</tcl>
</table>

<tcl>
##############################################################################
Section {Date And Time Functions} datefunc {datefunc}
................................................................................
<p>
The date() function returns the date in this format: YYYY-MM-DD. 
The time() function returns the time as HH:MM:SS. 
The datetime() function returns "YYYY-MM-DD HH:MM:SS". 
The julianday() function returns the 
<a href="http://en.wikipedia.org/wiki/Julian_day">Julian day</a> - 
number of days since noon in Greenwich on November 24, 4714 B.C. 
(<a href="http://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">Proleptic
Gregorian calendar</a>). 
The strftime() routine returns the date formatted according to 
the format string specified as the first argument.
The format string supports the most common substitutions found in the 
<a href="http://opengroup.org/onlinepubs/007908799/xsh/strftime.html">
strftime() function</a> from 
the standard C library plus two new substitutions, %f and %J.
The following is a complete list of valid strftime() substitutions:
................................................................................
Notice that all other date and time functions can be expressed
in terms of strftime():
</p>

<blockquote>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td><b>Function</b><td width="30"><td><b>Equivalent strftime()</b>
<tr><td>   date(...)      <td><td>  strftime('%Y-%m-%d', ...)
<tr><td>   time(...)      <td><td>  strftime('%H:%M:%S', ...)
<tr><td>   datetime(...)  <td><td>  strftime('%Y-%m-%d %H:%M:%S', ...)
<tr><td>   julianday(...) <td><td>  strftime('%J', ...)
</table>
</blockquote>

<p>
The only reasons for providing functions other than strftime() is
for convenience and for efficiency.
</p>
................................................................................
The command continues executing normally.  No error is returned.
If a NOT NULL constraint violation occurs, the NULL value is replaced
by the default value for that column.  If the column has no default
value, then the ABORT algorithm is used.  If a CHECK constraint violation
occurs then the IGNORE algorithm is used.</p>

<p>When this conflict resolution strategy deletes rows in order to
satisfy a constraint, it does not invoke [CREATE TRIGGER | delete triggers]
on those rows.  Nor is the [sqlite3_update_hook | update hook] invoked.
The exceptional behaviors defined in this paragraph might change 
in a future release.</p>
</dl>

<p>The algorithm specified in the OR clause of a INSERT or UPDATE
overrides any algorithm specified in a CREATE TABLE.
If no algorithm is specified anywhere, the ABORT algorithm is used.</p>

<tcl>

Changes to pages/limits.in.

24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
...
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
<p>
Unfortunately, the no-limits policy has been shown to create
problems.  Because the upper bounds were not well
defined, they were not tested, and bugs (including possible
security exploits) were often found when pushing SQLite to
extremes.  For this reason, newer versions of SQLite have
well-defined limits and those limits are tested as part of
the test suite.
</p>

<p>
This article defines what the limits of SQLite are and how they
can be customized for specific applications.  The default settings
for limits are normally quite large and adequate for almost every
application.  Some applications may want to increase a limit here
................................................................................
and 1073741824.  
</p>

<p>
If an SQL statement is limited to be a million bytes in length, then
obviously you will not be able to insert multi-million byte strings
by embedding them as literals inside of INSERT statements.  But
you should not do that anyway.  Use host parameters 
for your data.  Prepare short SQL statements like this:
</p>

<blockquote>
INSERT INTO tab1 VALUES(?,?,?);
</blockquote>








|







 







|







24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
...
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
<p>
Unfortunately, the no-limits policy has been shown to create
problems.  Because the upper bounds were not well
defined, they were not tested, and bugs (including possible
security exploits) were often found when pushing SQLite to
extremes.  For this reason, newer versions of SQLite have
well-defined limits and those limits are tested as part of
the [test suite].
</p>

<p>
This article defines what the limits of SQLite are and how they
can be customized for specific applications.  The default settings
for limits are normally quite large and adequate for almost every
application.  Some applications may want to increase a limit here
................................................................................
and 1073741824.  
</p>

<p>
If an SQL statement is limited to be a million bytes in length, then
obviously you will not be able to insert multi-million byte strings
by embedding them as literals inside of INSERT statements.  But
you should not do that anyway.  Use host [parameters] 
for your data.  Prepare short SQL statements like this:
</p>

<blockquote>
INSERT INTO tab1 VALUES(?,?,?);
</blockquote>

Changes to pages/tclsqlite.in.

1
2

3
4
5
6
7
8
9
10
11






12
13
14
15
16
17
18
19
20
<title>The Tcl interface to the SQLite library</title>
<tcl>

proc METHOD {name text} {
  hd_puts "<a name=\"$name\"></a>\n<h3>The \"$name\" method</h3>\n"
  hd_resolve $text
}
</tcl>

<h2>The Tcl interface to the SQLite library</h2>

<p>The SQLite library is designed to be very easy to use from






a Tcl or Tcl/Tk script.  This document gives an overview of the Tcl
programming interface.</p>

<h3>The API</h3>

<p>The interface to the SQLite library consists of single
tcl command named <b>sqlite3</b>
Because there is only this
one command, the interface is not placed in a separate


>









>
>
>
>
>
>
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<title>The Tcl interface to the SQLite library</title>
<tcl>
hd_keywords {Tcl extension}
proc METHOD {name text} {
  hd_puts "<a name=\"$name\"></a>\n<h3>The \"$name\" method</h3>\n"
  hd_resolve $text
}
</tcl>

<h2>The Tcl interface to the SQLite library</h2>

<p>The SQLite library is designed to be very easy to use from
a <a href="http://www.tcl.tk">Tcl or Tcl/Tk</a> script.  SQLite
began as a <a href="http://www.tcl.tk/doc/tea/">Tcl extension</a>
and the primary [test suite] for SQLite is written in TCL.  SQLite
can be used with any programming language, but its connections to
TCL run deep.</p>

<p>This document gives an overview of the Tcl
programming interface for SQLite.</p>

<h3>The API</h3>

<p>The interface to the SQLite library consists of single
tcl command named <b>sqlite3</b>
Because there is only this
one command, the interface is not placed in a separate

Changes to pages/testing.in.

1

2
3
4
5
6
7
8
<title>How SQLite Is Tested</title>


<tcl>
# This document contains many size statistics about SQLite, statistics
# that change frequently.  We want the document to be up-to-date.  To
# facilitate that, all the size values are defined by variables here
# which are then used as needed through the document.
#

>







1
2
3
4
5
6
7
8
9
<title>How SQLite Is Tested</title>
<tcl>hd_keywords testing tested {test suite}</tcl>

<tcl>
# This document contains many size statistics about SQLite, statistics
# that change frequently.  We want the document to be up-to-date.  To
# facilitate that, all the size values are defined by variables here
# which are then used as needed through the document.
#