Documentation Source Text

Check-in [066b35fad5]
Login

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

Overview
Comment:Fix documentation errors and typos.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 066b35fad587a425c4babea21456ffef9e0f8ad5
User & Date: drh 2014-08-08 21:27:58
Context
2014-08-11
18:36
Updates to expression documentation. check-in: 5608ec77f8 user: drh tags: trunk
2014-08-08
21:27
Fix documentation errors and typos. check-in: 066b35fad5 user: drh tags: trunk
17:05
First complete draft of the "rescode.html" document. check-in: e5ea14f1ff user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/lang.in.

1767
1768
1769
1770
1771
1772
1773
1774
1775
1776

1777
1778
1779
1780
1781
1782
1783

1784

1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
....
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
^It is not possible for an IS or IS NOT expression to evaluate to NULL.
^Operators [Operator IS] and [Operator {IS NOT}] have the same 
precedence as [Operator =]."

<tcl>hd_fragment litvalue {literal value}</tcl>
<h3>Literal Values (Constants)</h3>
<p>
^A literal value represents a constant.
^Literal values may be integers, floating point numbers, strings,
BLOBs, or NULLs.

The syntax for integer and floating point literals (collectively
"numeric literals") is shown by the following diagram:</p>

<tcl>BubbleDiagram numeric-literal</tcl>

<p>
^(If a numeric literal has a decimal point or an exponentiation

clause, then it is a floating point literal.  Otherwise is it is an 

integer literal.)^  ^The "E" character that begins the exponentiation
clause of a floating point literal can be either upper or lower case.
^(The "." character is always used 
as the decimal point even if the locale setting specifies "," for
this role - the use of "," for the decimal point would result in
syntactic ambiguity.)^

<tcl>hd_fragment hexint {hexadecimal integer literals} {hexadecimal integers}</tcl>
<p>Hexadecimal integer literals follow the C-language notation of
"0x" or "0X" followed by hexadecimal digits.
For example, 0x1234 means the same as 4660
and 0x8000000000000000 means the same as -9223372036854775808.
 ^(Hexadecimal integer literals are interpreted as 64-bit
two's-complement integers and are thus limited
to sixteen significant digits of precision.)^
Support for hexadecimal integers was added to SQLite version 3.8.6.
For backwards compatibility, the "0x" hexadecimal integer
notation is only understood by the SQL language parser, not by the
type conversions routines.
^(String variables that
contain text formatted like hexadecimal integers are not
interpreted as hexadecimal integers when coercing the string value
into an integer due to a [CAST expression] or for a [column affinity]
transformation or prior to performing a numeric operation or for
................................................................................
<p> ^A string constant is formed by enclosing the
string in single quotes (').  ^A single quote within the string can
be encoded by putting two single quotes in a row - as in Pascal.
C-style escapes using the backslash character are not supported because
they are not standard SQL.

<p> ^BLOB literals are string literals containing hexadecimal data and
preceded by a single "x" or "X" character.  ^(For example: X'53514C697465').

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

<tcl>hd_fragment varparam parameter parameters {bound parameter} {bound parameters}</tcl>
<h3>Parameters</h3>







|


>







>
|
>
|







|

|





|







 







|







1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
....
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
^It is not possible for an IS or IS NOT expression to evaluate to NULL.
^Operators [Operator IS] and [Operator {IS NOT}] have the same 
precedence as [Operator =]."

<tcl>hd_fragment litvalue {literal value}</tcl>
<h3>Literal Values (Constants)</h3>
<p>
A literal value represents a constant.
^Literal values may be integers, floating point numbers, strings,
BLOBs, or NULLs.
<p>
The syntax for integer and floating point literals (collectively
"numeric literals") is shown by the following diagram:</p>

<tcl>BubbleDiagram numeric-literal</tcl>

<p>
^(If a numeric literal has a decimal point or an exponentiation
clause or if its magnitude is less than -9223372036854775808 or
greater than 9223372036854775807, then it is a floating point literal.
Otherwise is it is an  integer literal.)^
^The "E" character that begins the exponentiation
clause of a floating point literal can be either upper or lower case.
^(The "." character is always used 
as the decimal point even if the locale setting specifies "," for
this role - the use of "," for the decimal point would result in
syntactic ambiguity.)^

<tcl>hd_fragment hexint {hexadecimal integer literals} {hexadecimal integers}</tcl>
<p>^Hexadecimal integer literals follow the C-language notation of
"0x" or "0X" followed by hexadecimal digits.
^For example, 0x1234 means the same as 4660
and 0x8000000000000000 means the same as -9223372036854775808.
 ^(Hexadecimal integer literals are interpreted as 64-bit
two's-complement integers and are thus limited
to sixteen significant digits of precision.)^
Support for hexadecimal integers was added to SQLite version 3.8.6.
^For backwards compatibility, the "0x" hexadecimal integer
notation is only understood by the SQL language parser, not by the
type conversions routines.
^(String variables that
contain text formatted like hexadecimal integers are not
interpreted as hexadecimal integers when coercing the string value
into an integer due to a [CAST expression] or for a [column affinity]
transformation or prior to performing a numeric operation or for
................................................................................
<p> ^A string constant is formed by enclosing the
string in single quotes (').  ^A single quote within the string can
be encoded by putting two single quotes in a row - as in Pascal.
C-style escapes using the backslash character are not supported because
they are not standard SQL.

<p> ^BLOB literals are string literals containing hexadecimal data and
preceded by a single "x" or "X" character.  ^(Example: X'53514C697465')^

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

<tcl>hd_fragment varparam parameter parameters {bound parameter} {bound parameters}</tcl>
<h3>Parameters</h3>

Changes to pages/rescode.in.

86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

105
106
107
108
109
110
111
...
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
...
175
176
177
178
179
180
181

182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
...
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
...
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
}
RESCODE SQLITE_INTERNAL     2  {
  The SQLITE_INTERNAL result code indicates an internal malfunction.
  In a working version of SQLite, an application should never see this
  result code.  If application does encounter this result code, it shows
  that there is a bug in the database engine.
  <p>
  Actually, SQLite does not currently generate this result code under
  any circumstances.  However, [application-defined SQL functions] or
  [virtual tables], or [VFSes], or other extensions might cause this 
  result code to be returned.
}
RESCODE SQLITE_PERM         3  {
  The SQLITE_PERM result code indicates a file-system permissions problem.
  Currently, on the unix VFS generates this result code.
}
RESCODE SQLITE_ABORT        4  {
  The SQLITE_ABORT result code indicates that an operation was aborted
  prior to completion, usually be application request.

  <p>
  ^If the callback function to [sqlite3_exec()] returns non-zero, then
  sqlite3_exec() will return SQLITE_ABORT.
  <p>
  ^If a [ROLLBACK] operation occurs on the same [database connection] as
  a pending read or write, then the pending read or write may fail with
  an SQLITE_ABORT or [SQLITE_ABORT_ROLLBACK] error.
................................................................................
  separate [database connection], probably in a separate process,
  whereas [SQLITE_LOCKED] 
  indicates a conflict within the same [database connection] (or sometimes
  a database connection with a [shared cache]).
}
RESCODE SQLITE_LOCKED       6  {
  The SQLITE_LOCKED result code indicates that a write operation could not
  proceed because of a conflict within the same [database connection] or
  a conflict with a different database connection that uses a [shared cache].
  <p>
  For example, a [DROP TABLE] statement cannot be run while another thread
  is reading from that table on the same [database connection] because 
  dropping the table would delete the table out from under the concurrent
  reader.
  <p>
................................................................................
  The SQLITE_READONLY result code is returned when an attempt is made to 
  alter some data for which the current database connection does not have
  write permission.
}
RESCODE SQLITE_INTERRUPT    9   {
  The SQLITE_INTERRUPT result code indicates that an operation was
  interrupted by the [sqlite3_interrupt()] interface.

}
RESCODE SQLITE_IOERR       10   {
  The SQLITE_IOERR result code says that the operation could not finish
  because the operating system reported an I/O error.  This could mean
  a hardware malfunction.  Or perhaps a removable storage device such as
  a USB thumb drive on which the database file is stored was removed in
  the middle of a write operation.
  <p>
  A full disk drive will normally give an SQLITE_FULL error rather than
  an SQLITE_IOERR error.
  <p>
  There are many different extended result codes for I/O errors that
  identify the specific I/O operation that failed.
}
RESCODE SQLITE_CORRUPT     11   {
  The SQLITE_CORRUPT result code indicates that the database file has
................................................................................
  a brief delay.  If the same connection loses the locking race dozens
  of times over a span of multiple seconds, it will eventually give up and
  return SQLITE_PROTOCOL.  The SQLITE_PROTOCOL error should appear in practice
  very, very rarely, and only when there are many separate processes all
  competing intensely to write to the same database.
}
RESCODE SQLITE_EMPTY       16   {
  The SQLITE_EMPTY result code originally meant that a database file was
  empty and held no content.  This result code is no longer used, but might
  be reused in some future release of SQLite.
}
RESCODE SQLITE_SCHEMA      17   {
  The SQLITE_SCHEMA result code indicates that the database schema
  has changed.  This result code can be returned from [sqlite3_step()] for
  a [prepared statement] that was generated using [sqlite3_prepare()] or
  [sqlite3_prepare16()].  If the database schema was changed by some other
  process in between the time that the statement was prepared and the time
................................................................................
  SQLITE_BUSY is for the much more common case of separate database
  connections that do not share the same cache.  Also, the
  [sqlite3_busy_handler()] and [sqlite3_busy_timeout()] interfaces
  do not help in resolving SQLITE_LOCKED_SHAREDCACHE conflicts.
}
RESCODE SQLITE_BUSY_RECOVERY           {SQLITE_BUSY   |  (1<<8)} {
  The SQLITE_BUSY_RECOVERY error code is an [ext-v-prim|extended error code]
  for [SQLITE_BUSY] that indicates that an operation could not proceed
  because another process is busy recovering a [WAL mode] database file
  following a crash.  The SQLITE_BUSY_RECOVERY error code only occurs
  on [WAL mode] databases.
}
RESCODE SQLITE_BUSY_SNAPSHOT           {SQLITE_BUSY   |  (2<<8)} {
  The SQLITE_BUSY_SNAPSHOT error code is an [ext-v-prim|extended error code]
  for [SQLITE_BUSY] that occurs on [WAL mode] databases when a database







|
|




|
|




>







 







|







 







>



|
<
<
<

|







 







|
<
<







 







|







86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
...
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
...
176
177
178
179
180
181
182
183
184
185
186
187



188
189
190
191
192
193
194
195
196
...
235
236
237
238
239
240
241
242


243
244
245
246
247
248
249
...
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
}
RESCODE SQLITE_INTERNAL     2  {
  The SQLITE_INTERNAL result code indicates an internal malfunction.
  In a working version of SQLite, an application should never see this
  result code.  If application does encounter this result code, it shows
  that there is a bug in the database engine.
  <p>
  SQLite does not currently generate this result code.
  However, [application-defined SQL functions] or
  [virtual tables], or [VFSes], or other extensions might cause this 
  result code to be returned.
}
RESCODE SQLITE_PERM         3  {
  The SQLITE_PERM result code indicates that the requested access mode
  for a newly created database could not be provided.
}
RESCODE SQLITE_ABORT        4  {
  The SQLITE_ABORT result code indicates that an operation was aborted
  prior to completion, usually be application request.
  See also: [SQLITE_INTERRUPT].
  <p>
  ^If the callback function to [sqlite3_exec()] returns non-zero, then
  sqlite3_exec() will return SQLITE_ABORT.
  <p>
  ^If a [ROLLBACK] operation occurs on the same [database connection] as
  a pending read or write, then the pending read or write may fail with
  an SQLITE_ABORT or [SQLITE_ABORT_ROLLBACK] error.
................................................................................
  separate [database connection], probably in a separate process,
  whereas [SQLITE_LOCKED] 
  indicates a conflict within the same [database connection] (or sometimes
  a database connection with a [shared cache]).
}
RESCODE SQLITE_LOCKED       6  {
  The SQLITE_LOCKED result code indicates that a write operation could not
  continue because of a conflict within the same [database connection] or
  a conflict with a different database connection that uses a [shared cache].
  <p>
  For example, a [DROP TABLE] statement cannot be run while another thread
  is reading from that table on the same [database connection] because 
  dropping the table would delete the table out from under the concurrent
  reader.
  <p>
................................................................................
  The SQLITE_READONLY result code is returned when an attempt is made to 
  alter some data for which the current database connection does not have
  write permission.
}
RESCODE SQLITE_INTERRUPT    9   {
  The SQLITE_INTERRUPT result code indicates that an operation was
  interrupted by the [sqlite3_interrupt()] interface.
  See also: [SQLITE_ABORT]
}
RESCODE SQLITE_IOERR       10   {
  The SQLITE_IOERR result code says that the operation could not finish
  because the operating system reported an I/O error.



  <p>
  A full disk drive will normally give an [SQLITE_FULL] error rather than
  an SQLITE_IOERR error.
  <p>
  There are many different extended result codes for I/O errors that
  identify the specific I/O operation that failed.
}
RESCODE SQLITE_CORRUPT     11   {
  The SQLITE_CORRUPT result code indicates that the database file has
................................................................................
  a brief delay.  If the same connection loses the locking race dozens
  of times over a span of multiple seconds, it will eventually give up and
  return SQLITE_PROTOCOL.  The SQLITE_PROTOCOL error should appear in practice
  very, very rarely, and only when there are many separate processes all
  competing intensely to write to the same database.
}
RESCODE SQLITE_EMPTY       16   {
  The SQLITE_EMPTY result code is not currently used.


}
RESCODE SQLITE_SCHEMA      17   {
  The SQLITE_SCHEMA result code indicates that the database schema
  has changed.  This result code can be returned from [sqlite3_step()] for
  a [prepared statement] that was generated using [sqlite3_prepare()] or
  [sqlite3_prepare16()].  If the database schema was changed by some other
  process in between the time that the statement was prepared and the time
................................................................................
  SQLITE_BUSY is for the much more common case of separate database
  connections that do not share the same cache.  Also, the
  [sqlite3_busy_handler()] and [sqlite3_busy_timeout()] interfaces
  do not help in resolving SQLITE_LOCKED_SHAREDCACHE conflicts.
}
RESCODE SQLITE_BUSY_RECOVERY           {SQLITE_BUSY   |  (1<<8)} {
  The SQLITE_BUSY_RECOVERY error code is an [ext-v-prim|extended error code]
  for [SQLITE_BUSY] that indicates that an operation could not continue
  because another process is busy recovering a [WAL mode] database file
  following a crash.  The SQLITE_BUSY_RECOVERY error code only occurs
  on [WAL mode] databases.
}
RESCODE SQLITE_BUSY_SNAPSHOT           {SQLITE_BUSY   |  (2<<8)} {
  The SQLITE_BUSY_SNAPSHOT error code is an [ext-v-prim|extended error code]
  for [SQLITE_BUSY] that occurs on [WAL mode] databases when a database