Documentation Source Text

Check-in [fb20146338]
Login

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

Overview
Comment:Documentation on the bind_falback method of the TCL interface.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: fb2014633876f76524baccf910ca16763b15c3082e190f08c5fe23f2a06e9413
User & Date: drh 2019-02-28 17:29:37.742
Context
2019-03-02
17:12
Add an initial change log for the 3.28 development cycle. (check-in: f41d1a3db0 user: drh tags: trunk)
2019-02-28
17:29
Documentation on the bind_falback method of the TCL interface. (check-in: fb20146338 user: drh tags: trunk)
2019-02-27
16:51
Add documentation for the Tcl command "db function" -returntype option. (check-in: 2f154421cf user: dan tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/tclsqlite.in.
102
103
104
105
106
107
108

109
110
111
112
113
114
115
</dl>
</blockquote>

<tcl>
set method_list [lsort {
 authorizer
 backup

 busy
 cache
 changes
 close
 collate
 collation_needed
 commit_hook







>







102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
</dl>
</blockquote>

<tcl>
set method_list [lsort {
 authorizer
 backup
 bind_fallback
 busy
 cache
 changes
 close
 collate
 collation_needed
 commit_hook
699
700
701
702
703
704
705






































706
707
708
709
710
711
712
then the operation is silently disabled.  If the return is "SQLITE_DENY"
then the compilation fails with an error.
</p>

<p>If the argument is an empty string then the authorizer is disabled.
If the argument is omitted, then the current authorizer is returned.</p>
}







































##############################################################################
METHOD progress {

<p>This method registers a callback that is invoked periodically during
query processing.  There are two arguments: the number of SQLite virtual
machine opcodes between invocations, and the TCL command to invoke.







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







700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
then the operation is silently disabled.  If the return is "SQLITE_DENY"
then the compilation fails with an error.
</p>

<p>If the argument is an empty string then the authorizer is disabled.
If the argument is omitted, then the current authorizer is returned.</p>
}

##############################################################################
METHOD bind_fallback {

<p>The "bind_fallback" method gives the application control over how to
handle parameter binding when no TCL variable matches the parameter name.

<p>When the <a href="#eval">eval method</a> sees a named SQL
parameter such as "$abc" or ":def" or "@ghi" in an SQL statement, it tries
to look up a TCL variable with the same name, and it binds the value
of that TCL variable to the SQL parameter.  If no such TCL variable exists,
the default behavior is to bind an SQL NULL value to the parameter.  However,
if a bind_fallback proc is specified, then that proc is invoked with the
name of the SQL parameter and the return value from the proc is bound to
the SQL parameter.  Or if the proc returns an error, then the SQL statement
aborts with that error.  If the proc returns with some code other than
TCL_OK or TCL_ERROR, then the SQL parameter is bound to NULL, as it would
be by default.

<p>The "bind_fallback" method has a single optional argument.  If the argument
is an empty string, then the bind_fallback is cancelled and the default behavior
is restored.  If the argument is a non-empty string, then the argument is a
TCL command (usually the name of a proc) to invoke whenever an SQL parameter 
is seen that does not match any TCL variable.  If the "bind_fallback" method 
is given no arguments, then the current bind_fallback command is returned.

<p>As an example, the following setup causes TCL to throw an error if
an SQL statement contains an parameter that does not match any global
TCL variable:

<blockquote><pre><b>
proc bind_error {nm} {
  error "no such variable: $nm"
}
db bind_fallback bind_error
</b></pre></blockquote>
}


##############################################################################
METHOD progress {

<p>This method registers a callback that is invoked periodically during
query processing.  There are two arguments: the number of SQLite virtual
machine opcodes between invocations, and the TCL command to invoke.
726
727
728
729
730
731
732
733
734
735
736

737
738
739
740
741
742
743
744
745
sequence.
</p>

<p>For example, the following code implements a collating sequence called
"NOCASE" that sorts in text order without regard to case:
</p>

<blockquote><b>
proc nocase_compare {a b} {<br>
&nbsp;&nbsp;&nbsp;&nbsp;return &#91;string compare &#91;string tolower $a&#93; &#91;string tolower $b&#93;&#93;<br>
}<br>

db collate NOCASE nocase_compare<br>
</b></blockquote>
}

##############################################################################
METHOD collation_needed {

<p>This method registers a callback routine that is invoked when the SQLite
engine needs a particular collating sequence but does not have that







|
|
|
<
>
|
|







765
766
767
768
769
770
771
772
773
774

775
776
777
778
779
780
781
782
783
784
sequence.
</p>

<p>For example, the following code implements a collating sequence called
"NOCASE" that sorts in text order without regard to case:
</p>

<blockquote><pre><b>
proc nocase_compare {a b} {
  return &#91;string compare &#91;string tolower $a] &#91;string tolower $b]]

}
db collate NOCASE nocase_compare
</b></pre></blockquote>
}

##############################################################################
METHOD collation_needed {

<p>This method registers a callback routine that is invoked when the SQLite
engine needs a particular collating sequence but does not have that