Documentation Source Text

Check-in [381e82d92b]
Login

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

Overview
Comment:Updates to the TCL interface documentation, plus other minor typo fixes.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 381e82d92b055a1eceb44cb13830fde4dc9d508172439a0869462d4f668c65a0
User & Date: drh 2018-03-10 20:39:05
Context
2018-03-14
21:01
Updates to the assert.html document. check-in: 6b0d70f277 user: drh tags: trunk
2018-03-10
20:39
Updates to the TCL interface documentation, plus other minor typo fixes. check-in: 381e82d92b user: drh tags: trunk
18:40
Improvements to ZIP processing in the CLI document. Fix a hyperlink in the sqlar.html document. check-in: 23f1f44cc2 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/changes.in.

36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
<li> If the [xColumn] method in a [virtual table] implementation returns
     an error message using [sqlite3_result_error()] then give that error
     message preference over internally-generated messages.
<li> Added the -A command-line option to the [CLI] to make it easier to manage
     [SQLite Archive files].
<li> Bug fixes:
<ol type='a'>
  <li> Fix the parser to acceept valid [row value] syntax.
       Ticket [https://www.sqlite.org/src/info/7310e2fb3d046a5|7310e2fb3d046a5]
  <li> Fix the query planner so that it takes into account dependencies in
       the arguments to table-valued functions in subexpressions in 
       the WHERE clause.
       Ticket [https://www.sqlite.org/src/info/80177f0c226ff54|80177f0c226ff54]
  <li> Fix incorrect result with complex OR-connected WHERE and STAT4.
       Ticket [https://www.sqlite.org/src/info/ec32177c99ccac2|ec32177c99ccac2]







|







36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
<li> If the [xColumn] method in a [virtual table] implementation returns
     an error message using [sqlite3_result_error()] then give that error
     message preference over internally-generated messages.
<li> Added the -A command-line option to the [CLI] to make it easier to manage
     [SQLite Archive files].
<li> Bug fixes:
<ol type='a'>
  <li> Fix the parser to accept valid [row value] syntax.
       Ticket [https://www.sqlite.org/src/info/7310e2fb3d046a5|7310e2fb3d046a5]
  <li> Fix the query planner so that it takes into account dependencies in
       the arguments to table-valued functions in subexpressions in 
       the WHERE clause.
       Ticket [https://www.sqlite.org/src/info/80177f0c226ff54|80177f0c226ff54]
  <li> Fix incorrect result with complex OR-connected WHERE and STAT4.
       Ticket [https://www.sqlite.org/src/info/ec32177c99ccac2|ec32177c99ccac2]

Changes to pages/qmplan.in.

110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

<p>The documentation system automatically maintains a
[chronology] of past releases, as well as a
[complete list of SQLite releases] with change summaries.

<h2>Schedule</h2>

SQLite has a long-range vision.
Planning is done with the assumption that SQLite
will be used and supported through at least the year 2050.
All code is written with the idea that it will one day be read and
maintained by people not yet born.  The code is carefully commented
with an eye toward helping those future developers more easily 
understand the logic and the rationale behind the code.








|







110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

<p>The documentation system automatically maintains a
[chronology] of past releases, as well as a
[complete list of SQLite releases] with change summaries.

<h2>Schedule</h2>

<p>SQLite has a long-range vision.
Planning is done with the assumption that SQLite
will be used and supported through at least the year 2050.
All code is written with the idea that it will one day be read and
maintained by people not yet born.  The code is carefully commented
with an eye toward helping those future developers more easily 
understand the logic and the rationale behind the code.

Changes to pages/tclsqlite.in.

111
112
113
114
115
116
117

118
119
120
121
122
123

124
125
126

127
128
129
130

131
132
133
134

135
136
137
138
139
140
141
...
828
829
830
831
832
833
834
























































835
836
837
838
839
840
841
...
873
874
875
876
877
878
879
880
881
















































882
883
884
885
886
887
888
889
890
...
909
910
911
912
913
914
915
916
917
918

919
 changes
 close
 collate
 collation_needed
 commit_hook
 complete
 copy

 enable_load_extension
 errorcode
 eval
 exists
 function
 incrblob

 last_insert_rowid
 nullvalue
 onecolumn

 profile
 progress
 restore
 rollback_hook

 status
 timeout
 total_changes
 trace

 transaction
 unlock_notify
 update_hook
 version
 wal_hook
}]
</tcl>
................................................................................

<p>The "trace" method registers a callback that is invoked as each SQL
statement is compiled.  The text of the SQL is appended as a single string
to the command before it is invoked.  This can be used (for example) to
keep a log of all SQL operations that an application performs.
</p>
}

























































##############################################################################
METHOD backup {

<p>The "backup" method makes a backup copy of a live database.  The
command syntax is like this:</p>

................................................................................
use <b>temp</b>.  To overwrite an auxiliary database added to the connection
using the [ATTACH] command, use the name of that database as it was assigned
in the [ATTACH] command.</p>

<p>The <i>source-filename</i> is the name of an existing well-formed SQLite
database file from which the content is extracted.</p>
}

##############################################################################
















































METHOD version {
  Return the current library version. For example, "3.6.17".
}

##############################################################################
METHOD profile {
<p>This method is used to profile the execution of SQL statements run by
   the application. The syntax is as follows:
</p>
................................................................................

##############################################################################
METHOD unlock_notify {
<p>The unlock_notify method is used access the [sqlite3_unlock_notify()]
   interface to the SQLite core library for testing purposes.  The use of
   this method by applications is discouraged.
</p>

}


</tcl>







>






>



>




>




>







 







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







 









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

|







 







|
|

>

111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
...
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
...
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
....
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
 changes
 close
 collate
 collation_needed
 commit_hook
 complete
 copy
 deserialize
 enable_load_extension
 errorcode
 eval
 exists
 function
 incrblob
 interrupt
 last_insert_rowid
 nullvalue
 onecolumn
 preupdate
 profile
 progress
 restore
 rollback_hook
 serialize
 status
 timeout
 total_changes
 trace
 trace_v2
 transaction
 unlock_notify
 update_hook
 version
 wal_hook
}]
</tcl>
................................................................................

<p>The "trace" method registers a callback that is invoked as each SQL
statement is compiled.  The text of the SQL is appended as a single string
to the command before it is invoked.  This can be used (for example) to
keep a log of all SQL operations that an application performs.
</p>
}

##############################################################################
METHOD trace_v2 {

<p>The "trace_v2" method registers a callback that is invoked as each SQL
statement is compiled. The syntax is as follows:


<blockquote>
<i>dbcmd</i>&nbsp;&nbsp;<b>trace_v2</b>&nbsp;&nbsp;?<i>callback</i>?&nbsp;&nbsp;?<i>mask</i>?
</blockquote>

<p>This command causes the "callback" script to be invoked whenever
certain conditions occurs.  The conditions are determined by the <i>mask</i>
argument, which should be a TCL-list of zero or more of the following
keywords:

<ul>
<li> <b>statement</b>
<li> <b>profile</b>
<li> <b>row</b>
<li> <b>close</b>
</ul>

<p>Traces for <b>statement</b> invoke the callback with two arguments
whenever a new SQL statement is run.
The first argument is an integer which is the value of the pointer
to the underlying [sqlite3_stmt] object.  This integer can be used
to correlate SQL statement text with the result of a <b>profile</b>
or <b>row</b> callback. The second argument is the
unexpanded text of the SQL statement being run.  By "unexpanded", we
mean that variable substitutions in the text are not expanded into the
variable values.  This is different from the behavior of the "trace"
method which does expand variable substitions.

<p>Traces for <b>profile</b> invoke the callback with two arguments
as each SQL statement finishes.  The first argument is an integer which
is the value of the underlying [sqlite3_stmt] object.  The second
argument is the approximate run-time for the statement in nanoseconds.
The run-time is the best estimate available depending on the capabilities
of the platform on which the application is running.

<p>Traces for <b>row</b> invoke the callback with a single argument
whenever a new result row is available from an SQL statement.
The argument is an integer which is the value of the underlying
[sqlite3_stmt] object pointer.

<p>Traces for <b>close</b> invoke the callback with a single argument
as the database connection is closing.  The argument is an integer which
is the value of a pointer to the underlying [sqlite3] object that is
closing.

<p>There can only be a single trace callback registered on a database
connection.  Each use of "trace" or "trace_v2" cancels all prior
trace callback.
}

##############################################################################
METHOD backup {

<p>The "backup" method makes a backup copy of a live database.  The
command syntax is like this:</p>

................................................................................
use <b>temp</b>.  To overwrite an auxiliary database added to the connection
using the [ATTACH] command, use the name of that database as it was assigned
in the [ATTACH] command.</p>

<p>The <i>source-filename</i> is the name of an existing well-formed SQLite
database file from which the content is extracted.</p>
}

##############################################################################
METHOD serialize {

<p>The "serialize" method creates a BLOB which is a complete copy of an
underlying database.  The syntax is like this:

<blockquote>
<i>dbcmd</i>&nbsp;&nbsp;<b>serialize</b>&nbsp;&nbsp;?<i>database</i>?
</blockquote>

<p>The optional argument is the name of the schema or database to be serialized.
The default value is "main".

<p>This routine returns a TCL byte-array that is the complete content of
the identified database.  This byte-array can be written into a file and
then used as an ordinary SQLite database, or it can be sent over a TCP/IP
connection to some other application, or passed to the "deserialize" method
of another database connection.

<p>This method only functions if SQLite is compiled with -DSQLITE_ENABLE_DESERIALIZE
}

##############################################################################
METHOD deserialize {
<p>The "deserialize" method takes a TCL byte-array that contains an SQLite
database file and adds it to the database connection.  The syntax is:

<blockquote>
<i>dbcmd</i>&nbsp;&nbsp;<b>deserialize</b>&nbsp;&nbsp;?<i>database</i>?&nbsp;&nbsp;<i>value</i>
</blockquote>

<p>The option <i>database</i> argument identifies which attached database
should receive the deserialization.  The default is "main".

<p>This command causes SQLite to disconnect from the previous database and
reattach to an in-memory database with the content in <i>value</i>.  If <i>value</i>
is not a byte-array containing a well-defined SQLite database, then subsequent
commands will likely return [SQLITE_CORRUPT] errors.

<p>This method only functions if SQLite is compiled with -DSQLITE_ENABLE_DESERIALIZE
}

##############################################################################
METHOD interrupt {
<p>The "interrupt" method invokes the [sqlite3_interrupt()] interface, causing
any pending queries to halt.
}

##############################################################################
METHOD version {
  Return the current library version. For example, "3.23.0".
}

##############################################################################
METHOD profile {
<p>This method is used to profile the execution of SQL statements run by
   the application. The syntax is as follows:
</p>
................................................................................

##############################################################################
METHOD unlock_notify {
<p>The unlock_notify method is used access the [sqlite3_unlock_notify()]
   interface to the SQLite core library for testing purposes.  The use of
   this method by applications is discouraged.
</p>
}



</tcl>