<p>The cache-flush method <a href="capi3ref.html#sqlite3_finalize">finalizes</a>all prepared statements currentlyin the cache.</p>}##############################################################################METHOD complete {<p>The "complete" method takes a string of supposed SQL as its only argument.It returns TRUE if the string is a complete statement of SQL and FALSE ifthere is more to be entered.</p><p>The "complete" method is useful when building interactive applicationsin order to know when the user has finished entering a line of SQL code.This is really just an interface to the <a href="capi3ref.html#sqlite3_complete"><b>sqlite3_complete()</b></a> Cfunction.}##############################################################################METHOD copy {<p>The "copy" method copies data from a file into a table.It returns the number of rows processed successfully from the file.The syntax of the copy method looks like this:</p><blockquote><i>dbcmd</i>&nbsp;&nbsp;<b>copy</b>&nbsp;&nbsp;<i>conflict-algorithm</i>&nbsp;&nbsp;<i>table-name&nbsp;</i>&nbsp;&nbsp;<i>file-name&nbsp;</i>&nbsp;&nbsp;&nbsp;&nbsp;?<i>column-separator&nbsp;</i>?&nbsp;&nbsp;?<i>null-indicator</i>?</blockquote><p>Conflict-alogrithm must be one of the SQLite conflict algorithms forthe INSERT statement: <i>rollback</i>, <i>abort</i>,<i>fail</i>,<i>ignore</i>, or <i>replace</i>. See the SQLite Languagesection for <a href="lang.html#conflict">ON CONFLICT</a> for more information.The conflict-algorithm must be specified in lower case.</p><p>Table-name must already exists as a table.  File-name must exist, andeach row must contain the same number of columns as defined in the table.If a line in the file contains more or less than the number of columns defined,the copy method rollbacks any inserts, and returns an error.</p><p>Column-separator is an optional column separator string.  The default isthe ASCII tab character \t. </p><p>Null-indicator is an optional string that indicates a column value is null.The default is an empty string.  Note that column-separator andnull-indicator are optional positional arguments; if null-indicatoris specified, a column-separator argument must be specifed andprecede the null-indicator argument.</p><p>The copy method implements similar functionality to the <b>.import</b>SQLite shell command. The SQLite 2.x <a href="lang.html#copy"><b>COPY</b></a> statement (using the PostgreSQL COPY file format)can be implemented with this method as:</p><blockquote>dbcmd&nbsp;&nbsp;copy&nbsp;&nbsp;$conflictalgo&nbsp;&nbsp;$tablename&nbsp;&nbsp;&nbsp;$filename&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\t&nbsp;&nbsp;&nbsp;\\N</blockquote>}##############################################################################METHOD timeout {<p>The "timeout" method is used to control how long the SQLite librarywill wait for locks to clear before giving up on a database transaction.The default timeout is 0 millisecond.  (In other words, the default behavioris not to wait at all.)</p><p>The SQLite database allows multiple simultaneousreaders or a single writer but not both.  If any process is writing tothe database no other process is allows to read or write.  If any processis reading the database other processes are allowed to read but not write.The entire database shared a single lock.</p><p>When SQLite tries to open a database and finds that it is locked, itcan optionally delay for a short while and try to open the file again.This process repeats until the query times out and SQLite returns afailure.  The timeout is adjustable.  It is set to 0 by default so thatif the database is locked, the SQL statement fails immediately.  But youcan use the "timeout" method to change the timeout value to a positivenumber.  For example:</p><blockquote><b>db1 timeout 2000</b></blockquote><p>The argument to the timeout method is the maximum number of millisecondsto wait for the lock to clear.  So in the example above, the maximum delaywould be 2 seconds.</p>}##############################################################################METHOD busy {<p>The "busy" method, like "timeout", only comes into play when thedatabase is locked.  But the "busy" method gives the programmer much morecontrol over what action to take.  The "busy" method specifies a callbackTcl procedure that is invoked whenever SQLite tries to open a lockeddatabase.  This callback can do whatever is desired.  Presumably, thecallback will do some other useful work for a short while (such as serviceGUI events) then returnso that the lock can be tried again.  The callback procedure shouldreturn "0" if it wants SQLite to try again to open the database andshould return "1" if it wants SQLite to abandon the current operation.}##############################################################################METHOD exists {<p>The "exists" method is similar to "onecolumn" and "eval" in thatit executes SQL statements.  The difference is that the "exists" methodalways returns a boolean value which is TRUE if a query in the SQLstatement it executes returns one or more rows and FALSE if the SQLreturns an empty set.</p><p>The "exists" method is often used to test for the existance ofrows in a table.  For example:</p><blockquote><b>if {[db exists {SELECT 1 FROM table1 WHERE user=$user}]} {<br>&nbsp;&nbsp;&nbsp;# Processing if $user exists<br>} else {<br>&nbsp;&nbsp;&nbsp;# Processing if $user does not exist<br>}</b></blockquote>}##############################################################################METHOD last_insert_rowid {<p>The "last_insert_rowid" method returns an integer which is the ROWIDof the most recently inserted database row.</p>}##############################################################################METHOD function {<p>The "function" method registers new SQL functions with the SQLite engine.The arguments are the name of the new SQL function and a TCL command thatimplements that function.  Arguments to the function are appended to theTCL command before it is invoked.</p><p>The following example creates a new SQL function named "hex" that convertsits numeric argument in to a hexadecimal encoded string:</p><blockquote><b>db function hex {format 0x%X}</b></blockquote>}##############################################################################METHOD nullvalue {<p>The "nullvalue" method changes the representation for NULL returnedas result of the "eval" method.</p><blockquote><b>db1 nullvalue NULL</b></blockquote><p>The "nullvalue" method is useful to differ between NULL and emptycolumn values as Tcl lacks a NULL representation.  The defaultrepresentation for NULL values is an empty string.</p>}##############################################################################METHOD onecolumn {<p>The "onecolumn" method works like "<a href="#eval">eval</a>" in that it evaluates theSQL query statement given as its argument.  The difference is that"onecolumn" returns a single element which is the first column of thefirst row of the query result.</p><p>This is a convenience method.  It saves the user from having todo a "<tt>[lindex&nbsp;...&nbsp;0]</tt>" on the results of an "eval"in order to extract a single column result.</p>}##############################################################################METHOD changes {<p>The "changes" method returns an integer which is the number of rowsin the database that were inserted, deleted, and/or modified by the mostrecent "eval" method.</p>}##############################################################################METHOD total_changes {<p>The "total_changes" method returns an integer which is the number of rowsin the database that were inserted, deleted, and/or modified since thecurrent database connection was first opened.</p>}##############################################################################METHOD authorizer {<p>The "authorizer" method provides access to the <a href="capi3ref.html#sqlite3_set_authorizer">sqlite3_set_authorizer</a>C/C++ interface.  The argument to authorizer is the name of a procedure thatis called when SQL statements are being compiled in order to authorizecertain operations.  The callback procedure takes 5 arguments which describethe operation being coded.  If the callback returns the text string"SQLITE_OK", then the operation is allowed.  If it returns "SQLITE_IGNORE",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 duringquery processing.  There are two arguments: the number of SQLite virtualmachine opcodes between invocations, and the TCL command to invoke.Setting the progress callback to an empty string disables it.</p><p>The progress callback can be used to display the status of a lengthyquery or to process GUI events during a lengthy query.</p>}##############################################################################METHOD collate {<p>This method registers new text collating sequences.  There aretwo arguments: the name of the collating sequence and the name of aTCL procedure that implements a comparison function for the collatingsequence.</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 [string compare [string tolower $a] [string tolower $b]]<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 SQLiteengine needs a particular collating sequence but does not have thatcollating sequence registered.  The callback can register the collatingsequence.  The callback is invoked with a single parameter which is thename of the needed collating sequence.</p>}##############################################################################METHOD commit_hook {<p>This method registers a callback routine that is invoked just beforeSQLite tries to commit changes to a database.  If the callback throwsan exception or returns a non-zero result, then the transaction rolls backrather than commit.</p>}##############################################################################METHOD errorcode {<p>This method returns the numeric error code that resulted from the mostrecent SQLite operation.</p>}##############################################################################METHOD trace {<p>The "trace" method registers a callback that is invoked as each SQLstatement is compiled.  The text of the SQL is appended as a single stringto the command before it is invoked.  This can be used (for example) tokeep a log of all SQL operations that an application performs.</p>}footer $rcsid