Documentation Source Text

Check-in [cfa4627882]
Login

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

Overview
Comment:Fix typos in documentation. This is the fix for ticket [9ed3b9626c9462e11a557621152f3e2d4eead482]
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:cfa4627882e06b105bff7bcefe6a9be7b6d4a22e
User & Date: drh 2009-03-18 14:19:10
References
2009-03-18
14:21 Fixed ticket [9ed3b9626c]: Fixing some typos in the documentation plus 2 other changes artifact: eb689a6fce user: drh
Context
2009-03-18
15:14
Add a new FAQ entry that attempts to explain the difference between single quotes and double quotes. check-in: b405f2eeeb user: drh tags: trunk
14:19
Fix typos in documentation. This is the fix for ticket [9ed3b9626c9462e11a557621152f3e2d4eead482] check-in: cfa4627882 user: drh tags: trunk
2009-03-17
11:07
Fix typo in the rtree.html webpage. CVSTrac ticket #3730. check-in: 61871a4c17 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Show Whitespace Changes Patch

Changes to pages/arch.in.

161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
and 65536 bytes.
The page cache is responsible for reading, writing, and
caching these chunks.
The page cache also provides the rollback and atomic commit abstraction
and takes care of locking of the database file.  The
B-tree driver requests particular pages from the page cache and notifies
the page cache when it wants to modify pages or commit or rollback
changes and the page cache handles all the messy details of making sure
the requests are handled quickly, safely, and efficiently.</p>

<p>The code to implement the page cache is contained in the single C
source file <b>pager.c</b>.  The interface to the page cache subsystem
is defined by the header file <b>pager.h</b>.
</p>








|







161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
and 65536 bytes.
The page cache is responsible for reading, writing, and
caching these chunks.
The page cache also provides the rollback and atomic commit abstraction
and takes care of locking of the database file.  The
B-tree driver requests particular pages from the page cache and notifies
the page cache when it wants to modify pages or commit or rollback
changes. The page cache handles all the messy details of making sure
the requests are handled quickly, safely, and efficiently.</p>

<p>The code to implement the page cache is contained in the single C
source file <b>pager.c</b>.  The interface to the page cache subsystem
is defined by the header file <b>pager.h</b>.
</p>

Changes to pages/atomiccommit.in.

460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
....
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
then the user space cache must be cleared and reread.  But it is
commonly the case that no changes have been made and the user
space cache can be reused for a significant performance savings.</p>

<br clear="both">
<h2>4.0 Rollback</h2>

<p>An atomic commit is suppose to happen instantaneously.  But the processing
described above clearly takes a finite amount of time.
Suppose the power to the computer were cut
part way through the commit operation described above.  In order
to maintain the illusion that the changes were instantaneous, we
have to "rollback" any partial changes and restore the database to
the state it was in prior to the beginning of the transaction.</p>

................................................................................
synchronous operation and so we think that TRUNCATE will usually be safe
in the face of power failures.  If you are uncertain about whether or
not TRUNCATE will be synchronous and atomic on your filesystem and it is
important to you that your database survive a power loss or operating
system crash that occurs during the truncation operation, then you might
consider using a different journaling mode.</p>

<p>On embedded systems with synchronous filesystems, TRUNCATE is results
in slower behavior than PERSIST.  The commit operation is the same speed.
But subsequent transactions are slower following a TRUNCATE because it is
faster to overwrite existing content than to append to the end of a file.
New journal file entries will always be appended following a TRUNCATE but
will usually overwrite with PERSIST.</p>

<h2>8.0 Testing Atomic Commit Behavior</h2>







|







 







|







460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
....
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
then the user space cache must be cleared and reread.  But it is
commonly the case that no changes have been made and the user
space cache can be reused for a significant performance savings.</p>

<br clear="both">
<h2>4.0 Rollback</h2>

<p>An atomic commit is supposed to happen instantaneously.  But the processing
described above clearly takes a finite amount of time.
Suppose the power to the computer were cut
part way through the commit operation described above.  In order
to maintain the illusion that the changes were instantaneous, we
have to "rollback" any partial changes and restore the database to
the state it was in prior to the beginning of the transaction.</p>

................................................................................
synchronous operation and so we think that TRUNCATE will usually be safe
in the face of power failures.  If you are uncertain about whether or
not TRUNCATE will be synchronous and atomic on your filesystem and it is
important to you that your database survive a power loss or operating
system crash that occurs during the truncation operation, then you might
consider using a different journaling mode.</p>

<p>On embedded systems with synchronous filesystems, TRUNCATE results
in slower behavior than PERSIST.  The commit operation is the same speed.
But subsequent transactions are slower following a TRUNCATE because it is
faster to overwrite existing content than to append to the end of a file.
New journal file entries will always be appended following a TRUNCATE but
will usually overwrite with PERSIST.</p>

<h2>8.0 Testing Atomic Commit Behavior</h2>

Changes to pages/cintro.in.

365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
  The [sqlite3_create_module()] interface is used register new
  virtual table implementations.
</p>

<p>
  The [sqlite3_create_function()] interface creates new SQL functions - 
  either scalar or aggregate.  The new function implementation typically
  make use of the following additional interfaces:
</p>

<p><ul>
  <li> [sqlite3_aggregate_context()] </li>
  <li> [sqlite3_result_int | sqlite3_result()] </li>
  <li> [sqlite3_user_data()] </li>
  <li> [sqlite3_value_int | sqlite3_value()] </li>







|







365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
  The [sqlite3_create_module()] interface is used register new
  virtual table implementations.
</p>

<p>
  The [sqlite3_create_function()] interface creates new SQL functions - 
  either scalar or aggregate.  The new function implementation typically
  makes use of the following additional interfaces:
</p>

<p><ul>
  <li> [sqlite3_aggregate_context()] </li>
  <li> [sqlite3_result_int | sqlite3_result()] </li>
  <li> [sqlite3_user_data()] </li>
  <li> [sqlite3_value_int | sqlite3_value()] </li>

Changes to pages/datatype3.in.

355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
<UL>
<LI><b>BINARY</b> - Compares string data using memcmp(), regardless
                    of text encoding.</LI>
<LI><b>NOCASE</b> - The same as binary, except the 26 upper case
     characters of ASCII are
     folded to their lower case equivalents before
     the comparison is performed.  Note that only ASCII characters
     are case folded.  SQLite does not attempt to due full
     UTF case folding due to the size of the tables required.</li>

<LI><b>RTRIM</b> - The same as binary, except that trailing space
     characters are ignored.</li>
</ul>









|







355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
<UL>
<LI><b>BINARY</b> - Compares string data using memcmp(), regardless
                    of text encoding.</LI>
<LI><b>NOCASE</b> - The same as binary, except the 26 upper case
     characters of ASCII are
     folded to their lower case equivalents before
     the comparison is performed.  Note that only ASCII characters
     are case folded.  SQLite does not attempt to do full
     UTF case folding due to the size of the tables required.</li>

<LI><b>RTRIM</b> - The same as binary, except that trailing space
     characters are ignored.</li>
</ul>


Changes to pages/faq.in.

88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
  </p>
}

faq {
  Why doesn't SQLite allow me to use '0' and '0.0' as the primary
  key on two different rows of the same table?
} {
  <p>Your primary key must have a numeric type.  Change the [datatype] of
  your primary key to TEXT and it should work.</p>

  <p>Every row must have a unique primary key.  For a column with a
  numeric type, SQLite thinks that <b>'0'</b> and <b>'0.0'</b> are the
  same value because they compare equal to one another numerically.
  (See the previous question.)  Hence the values are not unique.</p>
}
        







|
|







88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
  </p>
}

faq {
  Why doesn't SQLite allow me to use '0' and '0.0' as the primary
  key on two different rows of the same table?
} {
  <p>This problem occurs when your primary key is a numeric type.  Change the
  [datatype] of your primary key to TEXT and it should work.</p>

  <p>Every row must have a unique primary key.  For a column with a
  numeric type, SQLite thinks that <b>'0'</b> and <b>'0.0'</b> are the
  same value because they compare equal to one another numerically.
  (See the previous question.)  Hence the values are not unique.</p>
}
        

Changes to pages/features.in.

46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
<h3>Suggested Uses For SQLite:</h3>

<p><ul>
<li><p><b>Application File Format.</b>
Rather than using fopen() to write XML or some proprietary format into
disk files used by your application, use an SQLite database instead.
You'll avoid having to write and troubleshoot a parser, your data
will be more easily accessible and cross-platform, your updates
will be transactional.</p></li>

<li><p><b>Database For Gadgets.</b>
SQLite is popular choice for the database engine in cellphones,
PDAs, MP3 players, set-top boxes, and other electronic gadgets.
SQLite has a small code footprint, makes efficient use of memory,
disk space, and disk bandwidth, is highly reliable, and requires







|







46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
<h3>Suggested Uses For SQLite:</h3>

<p><ul>
<li><p><b>Application File Format.</b>
Rather than using fopen() to write XML or some proprietary format into
disk files used by your application, use an SQLite database instead.
You'll avoid having to write and troubleshoot a parser, your data
will be more easily accessible and cross-platform, and your updates
will be transactional.</p></li>

<li><p><b>Database For Gadgets.</b>
SQLite is popular choice for the database engine in cellphones,
PDAs, MP3 players, set-top boxes, and other electronic gadgets.
SQLite has a small code footprint, makes efficient use of memory,
disk space, and disk bandwidth, is highly reliable, and requires

Changes to pages/lockingv3.in.

50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
...
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
pager module</a>.
The pager module is responsible for making SQLite "ACID" (Atomic,
Consistent, Isolated, and Durable).  The pager module makes sure changes
happen all at once, that either all changes occur or none of them do,
that two or more processes do not try to access the database
in incompatible ways at the same time, and that once changes have been
written they persist until explicitly deleted.  The pager also provides
an memory cache of some of the contents of the disk file.</p>

<p>The pager is unconcerned
with the details of B-Trees, text encodings, indices, and so forth.
From the point of view of the pager the database consists of
a single file of uniform-sized blocks.  Each block is called a
"page" and is usually 1024 bytes in size.   The pages are numbered
beginning with 1.  So the first 1024 bytes of the database are called
................................................................................
preceding rules will be repeated in bullets:
</p>

<ul>
<li>A journal is hot if...
    <ul>
    <li>It exists, and</li>
    <li>It's master journal exists or the master journal name is an
        empty string, and</li>
    <li>There is no RESERVED lock on the corresponding database file.</li>
    </ul>
</li>
</ul>
}








|







 







|







50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
...
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
pager module</a>.
The pager module is responsible for making SQLite "ACID" (Atomic,
Consistent, Isolated, and Durable).  The pager module makes sure changes
happen all at once, that either all changes occur or none of them do,
that two or more processes do not try to access the database
in incompatible ways at the same time, and that once changes have been
written they persist until explicitly deleted.  The pager also provides
a memory cache of some of the contents of the disk file.</p>

<p>The pager is unconcerned
with the details of B-Trees, text encodings, indices, and so forth.
From the point of view of the pager the database consists of
a single file of uniform-sized blocks.  Each block is called a
"page" and is usually 1024 bytes in size.   The pages are numbered
beginning with 1.  So the first 1024 bytes of the database are called
................................................................................
preceding rules will be repeated in bullets:
</p>

<ul>
<li>A journal is hot if...
    <ul>
    <li>It exists, and</li>
    <li>Its master journal exists or the master journal name is an
        empty string, and</li>
    <li>There is no RESERVED lock on the corresponding database file.</li>
    </ul>
</li>
</ul>
}

Changes to pages/optoverview.in.

237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
...
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
  of case for latin1 characters.  Thus, by default, the following
  expression is true:
}
CODE {
  'a' LIKE 'A'
}
PARAGRAPH {
  By turned on the case_sensitive_like pragma as follows:
}
CODE {
  PRAGMA case_sensitive_like=ON;
}
PARAGRAPH {
  Then the LIKE operator pays attention to case and the example above would
  evaluate to false.  Note that case insensitivity only applies to
  latin1 characters - basically the upper and lower case letters of English
  in the lower 127 byte codes of ASCII.  International character sets
  are case sensitive in SQLite unless a user-supplied collating
  sequence is used.  But if you employ a user-supplied collating sequence,
  the LIKE optimization describe here will never be taken.
}
PARAGRAPH {
  The LIKE operator is case insensitive by default because this is what
  the SQL standard requires.  You can change the default behavior at
  compile time by using the -DSQLITE_CASE_SENSITIVE_LIKE command-line option
  to the compiler.
}
................................................................................
PARAGRAPH {
  When faced with a choice of two or more indices, SQLite tries to estimate
  the total amount of work needed to perform the query using each option.
  It then selects the option that gives the least estimated work.
}
PARAGRAPH {
  To help the optimizer get a more accurate estimate of the work involved
  in using various indices, the user may optional run the ANALYZE command.
  The ANALYZE command scans all indices of database where there might
  be a choice between two or more indices and gathers statistics on the
  selectiveness of those indices.  The results of this scan are stored
  in the sqlite_stat1 table.
  The contents of the sqlite_stat1 table are not updated as the database
  changes so after making significant changes it might be prudent to
  rerun ANALYZE.







|











|







 







|







237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
...
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
  of case for latin1 characters.  Thus, by default, the following
  expression is true:
}
CODE {
  'a' LIKE 'A'
}
PARAGRAPH {
  By turning on the case_sensitive_like pragma as follows:
}
CODE {
  PRAGMA case_sensitive_like=ON;
}
PARAGRAPH {
  Then the LIKE operator pays attention to case and the example above would
  evaluate to false.  Note that case insensitivity only applies to
  latin1 characters - basically the upper and lower case letters of English
  in the lower 127 byte codes of ASCII.  International character sets
  are case sensitive in SQLite unless a user-supplied collating
  sequence is used.  But if you employ a user-supplied collating sequence,
  the LIKE optimization described here will never be taken.
}
PARAGRAPH {
  The LIKE operator is case insensitive by default because this is what
  the SQL standard requires.  You can change the default behavior at
  compile time by using the -DSQLITE_CASE_SENSITIVE_LIKE command-line option
  to the compiler.
}
................................................................................
PARAGRAPH {
  When faced with a choice of two or more indices, SQLite tries to estimate
  the total amount of work needed to perform the query using each option.
  It then selects the option that gives the least estimated work.
}
PARAGRAPH {
  To help the optimizer get a more accurate estimate of the work involved
  in using various indices, the user may optionally run the ANALYZE command.
  The ANALYZE command scans all indices of database where there might
  be a choice between two or more indices and gathers statistics on the
  selectiveness of those indices.  The results of this scan are stored
  in the sqlite_stat1 table.
  The contents of the sqlite_stat1 table are not updated as the database
  changes so after making significant changes it might be prudent to
  rerun ANALYZE.

Changes to pages/testing.in.

175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
SQLite is frequently used on embedded devices, it is important that
SQLite be able to gracefully handle OOM errors.</p>

<p>OOM testing is accomplished by simulating OOM errors.
SQLite allows an application to substitute an alternative malloc()
implementation using the [sqlite3_config]([SQLITE_CONFIG_MALLOC],...)
interface.  The TCL and TH3 test harnesses are both capable of
inserting a modified version of malloc() that can be rigged fail 
after a certain number of allocations.  These instrumented mallocs
can be set to fail only once and then start working again, or to
continue failing after the first failure.  OOM tests are done in a
loop.  On the first iteration of the loop, the instrumented malloc
is rigged to fail on the first allocation.  Then some SQLite operation
is carried out and checks are done to make sure SQLite handled the
OOM error correctly.  Then the time-to-failure counter







|







175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
SQLite is frequently used on embedded devices, it is important that
SQLite be able to gracefully handle OOM errors.</p>

<p>OOM testing is accomplished by simulating OOM errors.
SQLite allows an application to substitute an alternative malloc()
implementation using the [sqlite3_config]([SQLITE_CONFIG_MALLOC],...)
interface.  The TCL and TH3 test harnesses are both capable of
inserting a modified version of malloc() that can be rigged to fail 
after a certain number of allocations.  These instrumented mallocs
can be set to fail only once and then start working again, or to
continue failing after the first failure.  OOM tests are done in a
loop.  On the first iteration of the loop, the instrumented malloc
is rigged to fail on the first allocation.  Then some SQLite operation
is carried out and checks are done to make sure SQLite handled the
OOM error correctly.  Then the time-to-failure counter

Changes to req/hlr40000.txt.

812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
accept a "update-stmt" that conforms to the following syntax:
<center>[syntax/update-stmt.gif]</center>

HLR H46700
In the absence of semantic or other errors, the SQLite parser shall
accept a "update-stmt-limited" that conforms to the following syntax:
<center>[syntax/update-stmt-limited.gif]</center>

HLR H46800
In the absence of semantic or other errors, the SQLite parser shall
accept a "qualified-table-name" that conforms to the following syntax:
<center>[syntax/qualified-table-name.gif]</center>

HLR H46900
In the absence of semantic or other errors, the SQLite parser shall
accept a "vacuum-stmt" that conforms to the following syntax:
<center>[syntax/vacuum-stmt.gif]</center>







<









812
813
814
815
816
817
818

819
820
821
822
823
824
825
826
827
accept a "update-stmt" that conforms to the following syntax:
<center>[syntax/update-stmt.gif]</center>

HLR H46700
In the absence of semantic or other errors, the SQLite parser shall
accept a "update-stmt-limited" that conforms to the following syntax:
<center>[syntax/update-stmt-limited.gif]</center>

HLR H46800
In the absence of semantic or other errors, the SQLite parser shall
accept a "qualified-table-name" that conforms to the following syntax:
<center>[syntax/qualified-table-name.gif]</center>

HLR H46900
In the absence of semantic or other errors, the SQLite parser shall
accept a "vacuum-stmt" that conforms to the following syntax:
<center>[syntax/vacuum-stmt.gif]</center>