Documentation Source Text

Check-in [8d811e938b]
Login

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

Overview
Comment:Update documentation for the sqlite3_value_nochange() interface.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256:8d811e938b297189c2af27ccbd9aff38eb890af7610d37be735eb8a5f6867ce1
User & Date: drh 2018-01-12 23:52:35
Context
2018-01-13
00:03
Clarification and typo fixes in the sqlite3_value_nochange() description within the xUpdate documentation. check-in: 92b3735966 user: drh tags: trunk
2018-01-12
23:52
Update documentation for the sqlite3_value_nochange() interface. check-in: 8d811e938b user: drh tags: trunk
17:40
Update the speed-and-size spreadsheet to the latest performance numbers. check-in: 3ce75e588e user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/changes.in.

24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
chng {2018-02-00 (3.22.0)} {
<li> The output of [sqlite3_trace_v2()] now shows each individual SQL statements
     run within a trigger.
<li> Add the ability to read from [WAL mode] databases even if the application 
     lacks write permission on the database and its containing directory, as long as
     the -shm and -wal files exist in that directory.
<li> Added the [rtreecheck()] scalar SQL function to the [R-Tree extension].
<li> Added the [sqlite3_vtab_nochange()] interface to help virtual table implementations
     optimize UPDATE operations.
<li> Added support for the [FTS5 initial token|"&#94;" initial token syntax] in FTS5.
<li> New extensions:
<ol type='a'>
  <li> The [Zipfile virtual table] can read and write a 
       [https://en.wikipedia.org/wiki/Zip_(file_format)|ZIP Archive].
  <li> Added the fsdir(PATH) [table-valued function] to the
       [https://sqlite.org/src/file/ext/misc/fileio.c|fileio.c] extension,







|
|







24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
chng {2018-02-00 (3.22.0)} {
<li> The output of [sqlite3_trace_v2()] now shows each individual SQL statements
     run within a trigger.
<li> Add the ability to read from [WAL mode] databases even if the application 
     lacks write permission on the database and its containing directory, as long as
     the -shm and -wal files exist in that directory.
<li> Added the [rtreecheck()] scalar SQL function to the [R-Tree extension].
<li> Added the [sqlite3_vtab_nochange()] and [sqlite3_value_nochange()] interfaces
     to help virtual table implementations optimize UPDATE operations.
<li> Added support for the [FTS5 initial token|"&#94;" initial token syntax] in FTS5.
<li> New extensions:
<ol type='a'>
  <li> The [Zipfile virtual table] can read and write a 
       [https://en.wikipedia.org/wiki/Zip_(file_format)|ZIP Archive].
  <li> Added the fsdir(PATH) [table-valued function] to the
       [https://sqlite.org/src/file/ext/misc/fileio.c|fileio.c] extension,

Changes to pages/vtab.in.

1172
1173
1174
1175
1176
1177
1178


















1179
1180
1181
1182
1183
1184
1185
using functions such as [sqlite3_mprintf()] or [sqlite3_malloc()].

<p>If the xUpdate method violates some constraint of the virtual table
(including, but not limited to, attempting to store a value of the wrong 
datatype, attempting to store a value that is too
large or too small, or attempting to change a read-only value) then the
xUpdate must fail with an appropriate [error code].



















<p>There might be one or more [sqlite3_vtab_cursor] objects open and in use 
on the virtual table instance and perhaps even on the row of the virtual
table when the xUpdate method is invoked.  The implementation of
xUpdate must be prepared for attempts to delete or modify rows of the table
out from other existing cursors.  If the virtual table cannot accommodate
such changes, the xUpdate method must return an [error code].







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







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
using functions such as [sqlite3_mprintf()] or [sqlite3_malloc()].

<p>If the xUpdate method violates some constraint of the virtual table
(including, but not limited to, attempting to store a value of the wrong 
datatype, attempting to store a value that is too
large or too small, or attempting to change a read-only value) then the
xUpdate must fail with an appropriate [error code].

<p>If the xUpdate method is performaing an UPDATE, then
[sqlite3_value_nochange(X)] can be used to discover which columns
of the virtual table were actually modified by the UPDATE
statement.  The [sqlite3_value_nochange(X)] interface returns
true for columns that do not change.
On every UPDATE, SQLite will first invoke
[xColumn] separately for each unchanging column in the table to 
obtain the value for that column.  The [xColumn] method can
check to see if the column is unchanged by invoking
[sqlite3_vtab_nochange()].  If [xColumn] sees that the column
is not being modified, it can return without setting a result
using one of the [sqlite3_result_int|sqlite3_result_xxxxx()]
interfaces.  In that case [sqlite3_value_nochange()] will be
true within the xUpdate method.  However, if [xColumn]
invokes one or more [sqlite3_result_int|sqlite3_result_xxxxx()]
interfaces, then the [sqlite3_value_nochange()] for that
column will be false within xUpdate.

<p>There might be one or more [sqlite3_vtab_cursor] objects open and in use 
on the virtual table instance and perhaps even on the row of the virtual
table when the xUpdate method is invoked.  The implementation of
xUpdate must be prepared for attempts to delete or modify rows of the table
out from other existing cursors.  If the virtual table cannot accommodate
such changes, the xUpdate method must return an [error code].