Documentation Source Text

Check-in [2eccbd9b76]
Login

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

Overview
Comment:Fixes to tcl documentation: Add docs for "version" and "profile" methods, add a hyperlink to the existing "incrblob" documentation.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:2eccbd9b76c4ff1419701baf976a0abc8b90a9e6
User & Date: dan 2009-08-09 22:27:14
Context
2009-08-10
13:25
Last minute documentation tweaks before the release of 3.6.17. check-in: 87b76c67f1 user: drh tags: trunk
2009-08-09
22:27
Fixes to tcl documentation: Add docs for "version" and "profile" methods, add a hyperlink to the existing "incrblob" documentation. check-in: 2eccbd9b76 user: dan tags: trunk
2009-08-06
17:47
Change docs to talk about the fact that virtual tables and shared cache can be used together beginning with version 3.6.17. check-in: 68debd1491 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/btreemodule.in.

969
970
971
972
973
974
975
976


977
978





979
980
981
982
983
984
985
...
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
	transaction (L50017), and at most a single b-tree database connection
        may have such an open transaction at one time, it is not possible for
        a request for a write-lock to fail because another connection is holding
        a write-lock on the same b-tree database image page. It may, however,
        fail because another connection is holding a read-lock.

      <p>
        All locks are held until the current transaction is concluded.



        [fancyformat_import_requirement L50018]






      <p class=todo> Malloc failure?

      <p class=todo> Read uncommitted flag. Maybe this should be handled
        outside of the b-tree module. Is there anything to stop connections
        with this flag set simply not obtaining read locks? There are assert()
        statements in the b-tree module that need to take this flag into account,
................................................................................
      [btree_api_defn sqlite3BtreeSchemaLocked]

        [fancyformat_import_requirement L50014]
        [fancyformat_import_requirement L50015]

    [h2 "What do these do?"]

    <p class=todo>
      The following is used only from within VdbeExec() to check whether or not
      a cursor was opened on a table or index b-tree. Corruption tests can move into
      the b-tree layer.

      [btree_api_defn sqlite3BtreeFlags]

      <p class=todo>
        Where do the following go?

      [btree_api_defn sqlite3BtreeIntegrityCheck sqlite3BtreePager sqlite3BtreeCopyFile]

      [btree_api_defn sqlite3BtreeSchema sqlite3BtreeSchemaLocked sqlite3BtreeLockTable sqlite3BtreeTripAllCursors]







|
>
>


>
>
>
>
>







 







<
<
<
<
<
<







969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
...
996
997
998
999
1000
1001
1002






1003
1004
1005
1006
1007
1008
1009
	transaction (L50017), and at most a single b-tree database connection
        may have such an open transaction at one time, it is not possible for
        a request for a write-lock to fail because another connection is holding
        a write-lock on the same b-tree database image page. It may, however,
        fail because another connection is holding a read-lock.

      <p>
        All locks are held until the current transaction is concluded. Or, if
        a read-write transaction is downgraded to a read-only transaction, all
        currently held write-locks are changed to read-locks.

        [fancyformat_import_requirement L50018]
        [fancyformat_import_requirement L50021]

      <p class=todo> The requirement above should refer to some other
	requirement that defines when a read-write transaction is downgraded to
        a read-only transaction.

      <p class=todo> Malloc failure?

      <p class=todo> Read uncommitted flag. Maybe this should be handled
        outside of the b-tree module. Is there anything to stop connections
        with this flag set simply not obtaining read locks? There are assert()
        statements in the b-tree module that need to take this flag into account,
................................................................................
      [btree_api_defn sqlite3BtreeSchemaLocked]

        [fancyformat_import_requirement L50014]
        [fancyformat_import_requirement L50015]

    [h2 "What do these do?"]








      <p class=todo>
        Where do the following go?

      [btree_api_defn sqlite3BtreeIntegrityCheck sqlite3BtreePager sqlite3BtreeCopyFile]

      [btree_api_defn sqlite3BtreeSchema sqlite3BtreeSchemaLocked sqlite3BtreeLockTable sqlite3BtreeTripAllCursors]

Changes to pages/tclsqlite.in.

74
75
76
77
78
79
80

81
82
83
84
85
86
87
88
89
90
91
92

93
94
95
96
97
98
99
...
742
743
744
745
746
747
748






























749
 complete
 copy
 enable_load_extension
 errorcode
 eval
 exists
 function

 last_insert_rowid
 nullvalue
 onecolumn
 profile
 progress
 restore
 rollback_hook
 status
 timeout
 total_changes
 trace
 transaction

 update_hook
 version
}] {
 hd_puts "<li><a href=\"#$m\">$m</a></li>"
}
</tcl>
</ul>
................................................................................
use <b>temp</b>.  To overwrite an auxilary 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 a existing well-formed SQLite
database file from which the content is extracted.</p>
}






























</tcl>







>












>







 







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

74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
...
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
 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
}] {
 hd_puts "<li><a href=\"#$m\">$m</a></li>"
}
</tcl>
</ul>
................................................................................
use <b>temp</b>.  To overwrite an auxilary 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 a 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>

<blockquote>
<i>dbcmd</i>&nbsp;&nbsp;<b>profile</b>&nbsp;&nbsp;?<i>script</i>
</blockquote>

<p>Unless <i>script</i> is an empty string, this method arranges for the
<i>script</i> to be evaluated after the execution of each SQL statement.
Two arguments are appended to <i>script</i> before it is invoked: the
text of the SQL statement executed and the time elapsed while executing
the statement, in nanoseconds.
</p>
<p>A database handle may only have a single profile script registered at
any time. If there is already a script registered when the profile method
is invoked, the previous profile script is replaced by the new one. If the 
<i>script</i> argument is an empty string, any previously registered 
profile callback is cancelled but no new profile script is registered.
</p>
}

</tcl>

Changes to req/llr50000.txt.

121
122
123
124
125
126
127





128
129
130
131
132
133
134
135
136
137
HLR L50020
If, when attempting to obtain a write-lock as described in L50017, there exists
another b-tree database connection connected to the same page-cache that is
holding a read or write-lock on the same database image page, the write-lock 
shall not be granted and the call to sqlite3BtreeLockTable shall return 
SQLITE_LOCKED_SHAREDCACHE.









HLR L51001
The balance-siblings algorithm shall redistribute the b-tree cells currently 
stored on a overfull or underfull page and up to two sibling pages, adding
or removing siblings as required, such that no sibling page is overfull and
the minimum possible number of sibling pages is used to store the 
redistributed b-tree cells.








>
>
>
>
>










121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
HLR L50020
If, when attempting to obtain a write-lock as described in L50017, there exists
another b-tree database connection connected to the same page-cache that is
holding a read or write-lock on the same database image page, the write-lock 
shall not be granted and the call to sqlite3BtreeLockTable shall return 
SQLITE_LOCKED_SHAREDCACHE.

HLR L50021
When a read-write transaction is downgraded to a read-only transaction, all
advisory b-tree write-locks held by the b-tree database connection shall be
changed to read-locks.




HLR L51001
The balance-siblings algorithm shall redistribute the b-tree cells currently 
stored on a overfull or underfull page and up to two sibling pages, adding
or removing siblings as required, such that no sibling page is overfull and
the minimum possible number of sibling pages is used to store the 
redistributed b-tree cells.