Documentation Source Text

Check-in [77dee5dcd0]
Login

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

Overview
Comment:Improve the text (rephrasing, not changing the meaning) of some requirements related to functions and pragmas. Improve or correct requirements marks.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 77dee5dcd0ccd9072ba61fcc63947bd3e2046931
User & Date: drh 2013-10-11 20:16:42
Context
2013-10-11
23:33
Improved documentation for DETACH - explain how behavior changes in shared cache mode. Update the makefile to scan the th3/core/*.c files for requirements marks. check-in: 949c314919 user: drh tags: trunk
20:16
Improve the text (rephrasing, not changing the meaning) of some requirements related to functions and pragmas. Improve or correct requirements marks. check-in: 77dee5dcd0 user: drh tags: trunk
14:18
Edits to the change log. check-in: c508b3c51a user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/lang.in.

402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
...
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
....
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
....
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
....
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
file) then the behavior of the ROLLBACK command is undefined.
</p>

<h3>Response To Errors Within A Transaction</h3>

<p> ^(If certain kinds of errors occur within a transaction, the
transaction may or may not be rolled back automatically.  The
errors that cause the behavior include:</p>

<ul>
<li> [SQLITE_FULL]: database or disk full
<li> [SQLITE_IOERR]: disk I/O error
<li> [SQLITE_BUSY]: database in use by another process
<li> [SQLITE_NOMEM]: out or memory
<li> [SQLITE_INTERRUPT]: processing [sqlite3_interrupt|interrupted]
................................................................................

<tcl>hd_fragment {descidx} {descending indices} {descending index}</tcl>
<p>^Each column name can be followed by one of the "ASC" or "DESC" keywords
to indicate sort order.  ^The sort order may or may not be ignored depending
on the database file format, and in particular the [schema format number].
^The "legacy" schema format (1) ignores index
sort order.  ^The descending index schema format (4) takes index sort order
into account.  ^(Only copies of SQLite newer than [version 3.3.0] 
(released on 2006-01-10) are able to understand the newer descending
index file format.)^  For compatibility, version of SQLite between 3.3.0
and 3.7.9 use the legacy schema format by default.  The newer schema format is
used by default in version 3.7.10 and later.
^The [legacy_file_format pragma] can be used to change set the specific
behavior for any version of SQLite.</p>

<p>^The COLLATE clause optionally following each column name defines a
collating sequence used for text entries in that column.
................................................................................
  or inserted or deleted by the most recently completed INSERT, DELETE,
  or UPDATE statement, exclusive of statements in lower-level triggers.
  ^The changes() SQL function is a wrapper around the [sqlite3_changes()]
  C/C++ function and hence follows the same rules for counting changes.
}

funcdef {char(X1,X2,...,XN)} {} {
  ^The char(X1,X2,...,XN) function returns a string composed of characters having the
   unicode code point values of integers X1 through XN, respectively.
}

funcdef {coalesce(X,Y,...)} {} {
  ^The coalesce() function returns a copy of its first non-NULL argument, or
  NULL if all arguments are NULL.  ^Coalesce() must be at least 
  2 arguments.
}
................................................................................
  [LIKE] operator depending on whether or not an ESCAPE clause was 
  specified.
}


funcdef {likelihood(X,Y)} {} {
  ^The likelihood(X,Y) function returns argument X unchanged.
  ^The value Y in likelihood(X,Y) must be a floating point constant
  between 0.0 and 1.0, inclusive.
  ^The likelihood(X) function is a no-op that the code generator
  optimizes away so that it consumes no CPU cycles during run-time
  (that is, during calls to [sqlite3_step()]).
  ^The purpose of the likelihood(X,Y) function is to provide a hint
  to the query planner that the argument X is a boolean that is
  true with a probability of approximately Y.
  ^The [unlikely(X)] fucntion is short-hand for likelihood(X,0.0625).
}

funcdef {load_extension(X) load_extension(X,Y)} {} {
  ^The load_extension(X,Y) function loads [SQLite extensions] out of the shared
  library file named X using the entry point Y.  ^The result of load_extension()
  is always a NULL.  ^If Y is omitted then the default entry point name is used.
  ^The load_extension() function raises an exception if the extension fails to
................................................................................
funcdef {unlikely(X)} {} {
  ^The unlikely(X) function returns the argument X unchanged.
  ^The unlikely(X) function is a no-op that the code generator
  optimizes away so that it consumes no CPU cycles at
  run-time (that is, during calls to [sqlite3_step()]).
  ^The purpose of the unlikely(X) function is to provide a hint
  to the query planner that the argument X is a boolean value
  that is usually not true. ^The unlikely(X) function is equivalent
  to [likelihood](X, 0.0625).
}

funcdef {unicode(X)} {} {
  ^The unicode(X) function returns the numeric unicode code point corresponding to
  the first character of the string X.  ^If the argument to unicode(X) is not a string
  then the result is undefined.
}

funcdef {upper(X)} {} {
  ^The upper(X) function returns a copy of input string X in which all 
  lower-case ASCII characters are converted to their upper-case equivalent.
}







|







 







|
<
|







 







|
|







 







|
|






|







 







|
|




|







402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
...
598
599
600
601
602
603
604
605

606
607
608
609
610
611
612
613
....
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
....
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
....
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
file) then the behavior of the ROLLBACK command is undefined.
</p>

<h3>Response To Errors Within A Transaction</h3>

<p> ^(If certain kinds of errors occur within a transaction, the
transaction may or may not be rolled back automatically.  The
errors that can cause an automatic rollback include:</p>

<ul>
<li> [SQLITE_FULL]: database or disk full
<li> [SQLITE_IOERR]: disk I/O error
<li> [SQLITE_BUSY]: database in use by another process
<li> [SQLITE_NOMEM]: out or memory
<li> [SQLITE_INTERRUPT]: processing [sqlite3_interrupt|interrupted]
................................................................................

<tcl>hd_fragment {descidx} {descending indices} {descending index}</tcl>
<p>^Each column name can be followed by one of the "ASC" or "DESC" keywords
to indicate sort order.  ^The sort order may or may not be ignored depending
on the database file format, and in particular the [schema format number].
^The "legacy" schema format (1) ignores index
sort order.  ^The descending index schema format (4) takes index sort order
into account.  Only versions of SQLite 3.3.0 and later are able to understand

the descending index format. For compatibility, version of SQLite between 3.3.0
and 3.7.9 use the legacy schema format by default.  The newer schema format is
used by default in version 3.7.10 and later.
^The [legacy_file_format pragma] can be used to change set the specific
behavior for any version of SQLite.</p>

<p>^The COLLATE clause optionally following each column name defines a
collating sequence used for text entries in that column.
................................................................................
  or inserted or deleted by the most recently completed INSERT, DELETE,
  or UPDATE statement, exclusive of statements in lower-level triggers.
  ^The changes() SQL function is a wrapper around the [sqlite3_changes()]
  C/C++ function and hence follows the same rules for counting changes.
}

funcdef {char(X1,X2,...,XN)} {} {
  ^(The char(X1,X2,...,XN) function returns a string composed of characters having the
   unicode code point values of integers X1 through XN, respectively.)^
}

funcdef {coalesce(X,Y,...)} {} {
  ^The coalesce() function returns a copy of its first non-NULL argument, or
  NULL if all arguments are NULL.  ^Coalesce() must be at least 
  2 arguments.
}
................................................................................
  [LIKE] operator depending on whether or not an ESCAPE clause was 
  specified.
}


funcdef {likelihood(X,Y)} {} {
  ^The likelihood(X,Y) function returns argument X unchanged.
  ^(The value Y in likelihood(X,Y) must be a floating point constant
  between 0.0 and 1.0, inclusive.)^
  ^The likelihood(X) function is a no-op that the code generator
  optimizes away so that it consumes no CPU cycles during run-time
  (that is, during calls to [sqlite3_step()]).
  ^The purpose of the likelihood(X,Y) function is to provide a hint
  to the query planner that the argument X is a boolean that is
  true with a probability of approximately Y.
  ^(The [unlikely(X)] fucntion is short-hand for likelihood(X,0.0625).)^
}

funcdef {load_extension(X) load_extension(X,Y)} {} {
  ^The load_extension(X,Y) function loads [SQLite extensions] out of the shared
  library file named X using the entry point Y.  ^The result of load_extension()
  is always a NULL.  ^If Y is omitted then the default entry point name is used.
  ^The load_extension() function raises an exception if the extension fails to
................................................................................
funcdef {unlikely(X)} {} {
  ^The unlikely(X) function returns the argument X unchanged.
  ^The unlikely(X) function is a no-op that the code generator
  optimizes away so that it consumes no CPU cycles at
  run-time (that is, during calls to [sqlite3_step()]).
  ^The purpose of the unlikely(X) function is to provide a hint
  to the query planner that the argument X is a boolean value
  that is usually not true. ^(The unlikely(X) function is equivalent
  to [likelihood](X, 0.0625).)^
}

funcdef {unicode(X)} {} {
  ^The unicode(X) function returns the numeric unicode code point corresponding to
  the first character of the string X.  If the argument to unicode(X) is not a string
  then the result is undefined.
}

funcdef {upper(X)} {} {
  ^The upper(X) function returns a copy of input string X in which all 
  lower-case ASCII characters are converted to their upper-case equivalent.
}

Changes to pages/pragma.in.

138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
....
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
....
1113
1114
1115
1116
1117
1118
1119


1120
1121

1122
1123
1124
1125
1126
1127
1128
....
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188

1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
}

Pragma {automatic_index} {
    <p>^(<b>PRAGMA automatic_index;
     <br>PRAGMA automatic_index = </b><i>boolean</i><b>;</b></p>

    <p>Query, set, or clear the [automatic indexing] capability.)^
    <p>^[Automatic indexing] is enabled by default as of version 3.7.17,
    but this might change in future releases of SQLite.
}

Pragma {auto_vacuum} {
    <p><b>PRAGMA auto_vacuum;<br>
          PRAGMA auto_vacuum = </b>
           <i>0 | NONE | 1 | FULL | 2 | INCREMENTAL</i><b>;</b></p>
................................................................................
    table "<i>table-name</i>".)^
}

Pragma foreign_key_check {
    <p>^(<b>PRAGMA foreign_key_check;
        <br>PRAGMA foreign_key_check(</b><i>table-name</i><b>);</b>)^</b></p>

    <p>The foreign_key_check pragma checks the database, or the table
    called "<i>table-name</i>", for 
    [foreign key constraints] that are violated and returns one row of
    output for each violation.  There are four columns in each result row.
    The first column is the name of the table that contains the REFERENCES
    clause.  The second column is the [rowid] of the row that
    contains the invalid REFERENCES clause.  The third column is the name
    of the table that is referred to. The fourth column is the index of
    the specific foreign key constraint that failed.  The fourth column
    in the output of the foreign_key_check pragma is the same integer as
    the first column in the output of the [foreign_key_list pragma].
    When a "<i>table-name</i>" is specified, the only foreign key constraints
    checked are those created by REFERENCES clauses in the
    CREATE TABLE statement for <i>table-name</i>.</p>
}

Pragma freelist_count {
    <p>^(<b>PRAGMA freelist_count;</b></p>
    <p>Return the number of unused pages in the database file.)^</p>
}

................................................................................
    table. ^The third column of output is the name of the column being indexed.
    </p>
}

Pragma index_list {
    <p>^(<b>PRAGMA index_list(</b><i>table-name</i><b>);</b></p>
    <p>This pragma returns one row for each index associated with the


    given table.)^   ^Columns of the result set include the
    index name and a flag to indicate whether or not the index is UNIQUE.

    </p>
}

Pragma page_count {
    <p>^(<b>PRAGMA page_count;</b></p>
    <p>Return the total number of pages in the database file.</p>)^
}
................................................................................
    from the returned option names.  See also the
    [sqlite3_compileoption_get()] C/C++ interface and the
    [sqlite_compileoption_get()] SQL functions.</p>
}

Pragma integrity_check {
    <p><b>PRAGMA integrity_check;
    <br>PRAGMA integrity_check(</b><i>integer</i><b>)</b></p>
    <p>^This pragma does an integrity check of the entire database.  ^It
    looks for out-of-order records, missing pages, malformed records, and
    corrupt indices.
    ^If any problems are found, then strings are returned (as multiple
    rows with a single column per row) which describe
    the problems.  ^At most <i>integer</i> errors will be reported
    before the analysis quits.  ^The default value for <i>integer</i>
    is 100.  ^If no errors are found, a single row with the value "ok" is
    returned.</p>

}

Pragma quick_check {
    <p><b>PRAGMA quick_check;
    <br>PRAGMA quick_check(</b><i>integer</i><b>)</b></p>
    <p>^The pragma is like [integrity_check] except that it does not verify
    that index content matches table content.  By skipping the verification
    of index content, quick_check is able to run much faster than
    integrity_check.  Otherwise the two pragmas are the same.
    </p>
}

DebugPragma parser_trace {
    <p><b>PRAGMA parser_trace = </b><i>boolean</i><b>; </b></p>

    <p>If SQLite has been compiled with the [SQLITE_DEBUG] compile-time







|







 







|


|
|
|
|
|
|


|

|







 







>
>
|
|
>







 







|
|
|
|
|
|
|
|
|
|
>




|



|







138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
....
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
....
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
....
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
}

Pragma {automatic_index} {
    <p>^(<b>PRAGMA automatic_index;
     <br>PRAGMA automatic_index = </b><i>boolean</i><b>;</b></p>

    <p>Query, set, or clear the [automatic indexing] capability.)^
    <p>[Automatic indexing] is enabled by default as of version 3.7.17,
    but this might change in future releases of SQLite.
}

Pragma {auto_vacuum} {
    <p><b>PRAGMA auto_vacuum;<br>
          PRAGMA auto_vacuum = </b>
           <i>0 | NONE | 1 | FULL | 2 | INCREMENTAL</i><b>;</b></p>
................................................................................
    table "<i>table-name</i>".)^
}

Pragma foreign_key_check {
    <p>^(<b>PRAGMA foreign_key_check;
        <br>PRAGMA foreign_key_check(</b><i>table-name</i><b>);</b>)^</b></p>

    <p>^(The foreign_key_check pragma checks the database, or the table
    called "<i>table-name</i>", for 
    [foreign key constraints] that are violated and returns one row of
    output for each violation.)^  ^There are four columns in each result row.
    ^The first column is the name of the table that contains the REFERENCES
    clause.  ^The second column is the [rowid] of the row that
    contains the invalid REFERENCES clause.  ^The third column is the name
    of the table that is referred to. ^The fourth column is the index of
    the specific foreign key constraint that failed.  ^The fourth column
    in the output of the foreign_key_check pragma is the same integer as
    the first column in the output of the [foreign_key_list pragma].
    ^(When a "<i>table-name</i>" is specified, the only foreign key constraints
    checked are those created by REFERENCES clauses in the
    CREATE TABLE statement for <i>table-name</i>.)^</p>
}

Pragma freelist_count {
    <p>^(<b>PRAGMA freelist_count;</b></p>
    <p>Return the number of unused pages in the database file.)^</p>
}

................................................................................
    table. ^The third column of output is the name of the column being indexed.
    </p>
}

Pragma index_list {
    <p>^(<b>PRAGMA index_list(</b><i>table-name</i><b>);</b></p>
    <p>This pragma returns one row for each index associated with the
    given table.)^   ^The original table with its rowid key is considered
    an index with a NULL name for the purposes of this pragma.
    ^Columns of the result set include the
    index name, a flag to indicate whether or not the index is UNIQUE, and
    an estimate of the number of bytes in each row of the index.
    </p>
}

Pragma page_count {
    <p>^(<b>PRAGMA page_count;</b></p>
    <p>Return the total number of pages in the database file.</p>)^
}
................................................................................
    from the returned option names.  See also the
    [sqlite3_compileoption_get()] C/C++ interface and the
    [sqlite_compileoption_get()] SQL functions.</p>
}

Pragma integrity_check {
    <p><b>PRAGMA integrity_check;
    <br>PRAGMA integrity_check(</b><i>N</i><b>)</b></p>
    <p>^This pragma does an integrity check of the entire database.  ^The
    integrity_check pragma
    looks for out-of-order records, missing pages, malformed records, and
    corrupt indices.
    ^If the integrity_check pragma finds problems, strings are returned
    (as multiple rows with a single column per row) which describe
    the problems.  ^Pragma integrity_check will return at most <i>N</i>
    errors will be reported before the analysis quits, with N defaulting
    to 100.  ^If pragma integrity_check finds no errors are found, a
    single row with the value 'ok' is returned.</p>
}

Pragma quick_check {
    <p><b>PRAGMA quick_check;
    <br>PRAGMA quick_check(</b><i>N</i><b>)</b></p>
    <p>^The pragma is like [integrity_check] except that it does not verify
    that index content matches table content.  By skipping the verification
    of index content, quick_check is able to run much faster than
    integrity_check.  ^Otherwise the two pragmas are the same.
    </p>
}

DebugPragma parser_trace {
    <p><b>PRAGMA parser_trace = </b><i>boolean</i><b>; </b></p>

    <p>If SQLite has been compiled with the [SQLITE_DEBUG] compile-time