Documentation Source Text

<title>SQLite Autoincrement</title>
<h1>SQLite Autoincrement</h1>

<p>
In SQLite, every row of every table has an integer ROWID.
The ROWID for each row is unique among all rows in the same table.
In SQLite 3.0.0 and later the ROWID is a 64-bit signed integer.

</p>

<p>
You can access the ROWID of an SQLite table using one the special column
names ROWID, _ROWID_, or OID.
Except if you declare an ordinary table column to use one of those special
names, then the use of that name will refer to the declared column not

<p>
If no ROWID is specified on the insert, an appropriate ROWID is created
automatically.  The usual algorithm is to give the newly created row
a ROWID that is one larger than the largest ROWID in the table prior
to the insert.  If the table is initially empty, then a ROWID of 1 is
used.  If the largest ROWID is equal to the largest possible integer
(9223372036854775807 in SQLite version 3.0.0 and later) then the database
engine starts picking candidate ROWIDs at random until it finds one
that is not previously used.
</p>

<p>
The normal ROWID selection algorithm described above
will generate monotonically increasing

selected ROWIDs are guaranteed to have ROWIDs that have never been used
before by the same table in the same database.  And the automatically generated
ROWIDs are guaranteed to be monotonically increasing.  These are important
properties in certain applications.  But if your application does not
need these properties, you should probably stay with the default behavior
since the use of AUTOINCREMENT requires additional work to be done
as each row is inserted and thus causes INSERTs to run a little slower.
</p>

      set lx [string trim [string range $line 3 end]]
      if {[regexp {^CATEGORY: +([a-z]*)} $lx all cx]} {
        set type $cx
      } elseif {[regexp {^KEYWORDS: +(.*)} $lx all kx]} {
        foreach k $kx {
          set keyword($k) 1
        }
      } elseif {[regexp {^INVARIANTS:$} $lx]} {
        append body "\n<h3>Invariants:</h3>\n"
        starttab
        set phase 2
      } elseif {[regexp {^LIMITATIONS:$} $lx]} {
        append body "\n<h3>Limitations:</h3>\n"
        starttab
        set phase 2
      } else {

      <a href="http://www.sqlite.org/cvstrac/timeline">
      http://www.sqlite.org/cvstrac/timeline</a>.</p>
    }
    hd_close_aux
    hd_enable_main 1
  }
}

chng {2008 Jan 31 (3.5.5)} {
<li>Convert the underlying virtual machine to be a register-based machine
rather than a stack-based machine.  The only user-visible change
is in the output of EXPLAIN.</li>
<li>Add the build-in RTRIM collating sequence.</li>
}

chng {2007 Dec 14 (3.5.4)} {
<li>Fix a critical bug in UPDATE or DELETE that occurs when an
OR REPLACE clause or a trigger causes rows in the same table to
be deleted as side effects.  (See [ticket #2832].)  The most likely
result of this bug is a segmentation fault, though database
corruption is a possibility.</li>

<title>SQLite Virtual Machine Opcodes</title>

<h2>SQLite Virtual Machine Opcodes</h2>

<tcl>
set fd [open $::SRC/src/vdbe.c r]
set file [read $fd]
close $fd
set current_op {}
unset -nocomplain Opcode
unset -nocomplain OpcodeList
foreach line [split $file \n] {
  set line [string trim $line]
  if {[string index $line 1]!="*"} {
    set current_op {}
    continue
  }
  if {[regexp {^/\* Opcode: } $line]} {
    set current_op [lindex $line 2]
    set txt [lrange $line 3 end]
    regsub -all {>} $txt {\&gt;} txt
    regsub -all {<} $txt {\&lt;} txt
    set Opcode($current_op:args) $txt
    lappend OpcodeList $current_op
    set pend {}
    set pstart {}
    continue
  }
  if {$current_op==""} continue
  if {[regexp {^\*/} $line]} {
    set current_op {}
    continue
  }
  set line [string trim [string range $line 3 end]]
  if {$line==""} {
    append Opcode($current_op:text) $pend
    set pend {}
    set pstart {<p>}
  } else {
    regsub -all {>} $line {\&gt;} line
    regsub -all {<} $line {\&lt;} line
    append Opcode($current_op:text) \n$pstart$line
    set pstart {}
    set pend "</p>\n"
  }
}
unset file
</tcl>

<h3>Introduction</h3>

available.  If you are looking for a narrative description
of how the virtual machine works, you should read the tutorial
and not this document.  Once you have a basic idea of what the
virtual machine does, you can refer back to this document for
the details on a particular opcode.
Unfortunately, the virtual machine tutorial was written for
SQLite version 1.0.  There are substantial changes in the virtual
machine for version 2.0 and and again for version 3.0.0 and again
for version 3.5.5 and the document has not been updated.  But the
basic concepts behind the virtual machine still apply.
</p>

<p>The source code to the virtual machine is in the <b>vdbe.c</b> source
file.  All of the opcode definitions further down in this document are
contained in comments in the source file.  In fact, the opcode table
in this document
was generated by scanning the <b>vdbe.c</b> source file 
and extracting the necessary information from comments.  So the 
source code comments are really the canonical source of information
about the virtual machine.  When in doubt, refer to the source code.</p>

<p>Each instruction in the virtual machine consists of an opcode and
up to five operands named P1, P2  P3, P4, and P5.  P1, P2, and P3 
are 32-bit signed integers.  These operands often refer to registers.
P2 is always the
jump destination in any operation that might cause a jump.
P4 may be a 32-bit signed integer, a 64-bit signed integer, a
64-bit floating point value, a string literal, a Blob literal,
a pointer to a collating sequence comparison function, or a
pointer to the implemantation of an application-defined SQL
function, or various other things.  P5 is an unsigned character
normally used as a flag.
Some operators use all five operands.  Some use
one or two.  Some operators use none of the operands.<p>

<p>The virtual machine begins execution on instruction number 0.
Execution continues until a Halt instruction is seen, or 
the program counter becomes one greater than the address of
last instruction, or there is an execution error.
When the virtual machine halts, all memory
that it allocated is released and all database cursors it may
have had open are closed.  If the execution stopped due to an
error, any pending transactions are terminated and changes made
to the database are rolled back.</p>





<p>The virtual machine can have zero or more cursors.  Each cursor
is a pointer into a single table or index within the database.
There can be multiple cursors pointing at the same index or table.
All cursors operate independently, even cursors pointing to the same
indices or tables.
The only way for the virtual machine to interact with a database
file is through a cursor.
Instructions in the virtual
machine can create a new cursor (OpenRead or OpenWrite),
read data from a cursor
(Column), advance the cursor to the next entry in the table
(Next) or index (NextIdx), and many other operations.
All cursors are automatically
closed when the virtual machine terminates.</p>

<p>The virtual machine contains an arbitrary number of registers
locations with addresses beginning at one and growing upward.
Each memory location can hold an arbitrary string.  The registers


hold all intermediate results of a calculation.</p>






























<h3>Viewing Programs Generated By SQLite</h3>

<p>Every SQL statement that SQLite interprets results in a program
for the virtual machine.  But if you precede the SQL statement with
the keyword "EXPLAIN" the virtual machine will not execute the
program.  Instead, the instructions of the program will be returned
like a query result.  This feature is useful for debugging and
for learning how the virtual machine operates.</p>

<p>You can use the <b>sqlite3.exe</b> command-line interface (CLI)
tool to see the
instructions generated by an SQL statement.  The following is
an example:</p>

<tcl>
proc Code {body} {
  hd_puts {<blockquote><tt>}
  regsub -all {&} [string trim $body] {\&amp;} body
  regsub -all {>} $body {\&gt;} body
  regsub -all {<} $body {\&lt;} body
  regsub -all {\(\(\(} $body {<b>} body
  regsub -all {\)\)\)} $body {</b>} body
  regsub -all { } $body {\&nbsp;} body
  regsub -all \n $body <br>\n body
  hd_puts $body
  hd_puts {</tt></blockquote>}
}

Code {
$ (((sqlite3 ex1.db)))
sqlite> (((.explain)))
sqlite> (((explain delete from tbl1 where two<20;)))
addr  opcode         p1    p2    p3    p4         p5  comment
----  -------------  ----  ----  ----  ---------  --  -------
0     Trace          0     0     0     explain..  00         
1     Goto           0     20    0                00         
2     OpenRead       0     2     0                00  tbl    
3     SetNumColumns  0     2     0                00         
4     Rewind         0     11    0                00         

5     Column         0     1     2                00  tbl.two
6     Integer        20    3     0                00         
7     Ge             3     10    2     cs(BINARY) 6a         
8     Rowid          0     1     0                00         
9     FifoWrite      1     0     0                00         
10    Next           0     5     0                00         
11    Close          0     0     0                00         

12    OpenWrite      0     2     0                00  tbl    
13    SetNumColumns  0     2     0                00         
14    FifoRead       1     18    0                00         
15    NotExists      0     17    1                00         
16    Delete         0     1     0     tbl        00         
17    Goto           0     14    0                00         
18    Close          0     0     0                00         
19    Halt           0     0     0                00         
20    Transaction    0     1     0                00         
21    VerifyCookie   0     1     0                00         
22    TableLock      -1    2     0     tbl        00         
23    Goto           0     2     0                00         
}
</tcl>

<p>All you have to do is add the "EXPLAIN" keyword to the front of the
SQL statement.  But if you use the ".explain" command in the CLI,
it will set up the output mode to make the program more easily
viewable.</p>

<p>Depending on compile-time options, you 

can put the SQLite virtual machine in a mode where it will trace its
execution by writing messages to standard output.  The non-standard
SQL "PRAGMA" comments can be used to turn tracing on and off.  To
turn tracing on, enter:
</p>

<blockquote><pre>

<p><table cellspacing="1" border="1" cellpadding="10">
<tr><th>Opcode&nbsp;Name</th><th>Description</th></tr>

<tcl>
  foreach op [lsort -dictionary $OpcodeList] {
    hd_puts {<tr><td valign="top" align="center">}
    hd_puts "<a name=\"$op\"></a><p>$op</p>"
    hd_resolve "<td>[string trim $Opcode($op:text)]</td></tr>"
  }
</tcl>
</table></p>

** there are major feature enhancements that are forwards compatible
** but not backwards compatible.  The Z value is release number
** and is incremented with
** each release but resets back to 0 when Y is incremented.
**
** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
**
** INVARIANTS:
**
** {F10011} The SQLITE_VERSION #define in the sqlite3.h header file
**          evaluates to a string literal that is the SQLite version
**          with which the header file is associated.
**
** {F10014} The SQLITE_VERSION_NUMBER #define resolves to an integer
**          with the value  (X*1000000 + Y*1000 + Z) where X, Y, and

** [SQLITE_VERSION_NUMBER].
**
** The sqlite3_libversion() function returns the same information as is
** in the sqlite3_version[] string constant.  The function is provided
** for use in DLLs since DLL users usually do not have direct access to string
** constants within the DLL.
**
** INVARIANTS:
**
** {F10021} The [sqlite3_libversion_number()] interface returns an integer
**          equal to [SQLITE_VERSION_NUMBER]. 
**
** {F10022} The [sqlite3_version] string constant contains the text of the
**          [SQLITE_VERSION] string. 
**

** the mutexes.  But for maximum safety, mutexes should be enabled.
** The default behavior is for mutexes to be enabled.
**
** This interface can be used by a program to make sure that the
** version of SQLite that it is linking against was compiled with
** the desired setting of the SQLITE_THREADSAFE macro.
**
** INVARIANTS:
**
** {F10101} The [sqlite3_threadsafe()] function returns nonzero if
**          SQLite was compiled with its mutexes enabled or zero
**          if SQLite was compiled with mutexes disabled.
*/
int sqlite3_threadsafe(void);

** Because there is no cross-platform way to specify 64-bit integer types
** SQLite includes typedefs for 64-bit signed and unsigned integers.
**
** The sqlite3_int64 and sqlite3_uint64 are the preferred type
** definitions.  The sqlite_int64 and sqlite_uint64 types are
** supported for backwards compatibility only.
**
** INVARIANTS:
**
** {F10201} The [sqlite_int64] and [sqlite3_int64] types specify a
**          64-bit signed integer.
**
** {F10202} The [sqlite_uint64] and [sqlite3_uint64] types specify
**          a 64-bit unsigned integer.
*/

** [sqlite3_blob_close | close] all [sqlite3_blob | BLOBs] 
** associated with the [sqlite3] object prior
** to attempting to close the [sqlite3] object.
**
** <todo>What happens to pending transactions?  Are they
** rolled back, or abandoned?</todo>
**
** INVARIANTS:
**
** {F12011} The [sqlite3_close()] interface destroys an [sqlite3] object
**          allocated by a prior call to [sqlite3_open()],
**          [sqlite3_open16()], or [sqlite3_open_v2()].
**
** {F12012} The [sqlite3_close()] function releases all memory used by the
**          connection and closes all open files.

**
** The sqlite3_exec() interface is implemented in terms of
** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
** The sqlite3_exec() routine does nothing that cannot be done
** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
** The sqlite3_exec() is just a convenient wrapper.
**
** INVARIANTS:
** 
** {F12101} The [sqlite3_exec()] interface evaluates zero or more UTF-8
**          encoded, semicolon-separated, SQL statements in the
**          zero-terminated string of its 2nd parameter within the
**          context of the [sqlite3] object given in the 1st parameter.
**
** {F12104} The return value of [sqlite3_exec()] is SQLITE_OK if all
**          SQL statements run successfully.
**
** {F12105} The return value of [sqlite3_exec()] is an appropriate 
**          non-zero error code if any SQL statement fails.
**
** {F12107} If one or more of the SQL statements handed to [sqlite3_exec()]
**          return results and the 3rd parameter is not NULL, then
**          the callback function specified by the 3rd parameter is
**          invoked once for each row of result.
**
** {F12110} If the callback returns a non-zero value then [sqlite3_exec()]

** One may expect the number of extended result codes will be expand
** over time.  Software that uses extended result codes should expect
** to see new result codes in future releases of SQLite.
**
** The SQLITE_OK result code will never be extended.  It will always
** be exactly zero.
** 
** INVARIANTS:
**
** {F10223} The symbolic name for an extended result code always contains
**          a related primary result code as a prefix.
**
** {F10224} Primary result code names contain a single "_" character.
**
** {F10225} Extended result code names contain two or more "_" characters.

** CAPI3REF: Enable Or Disable Extended Result Codes {F12200}
**
** The sqlite3_extended_result_codes() routine enables or disables the
** [SQLITE_IOERR_READ | extended result codes] feature of SQLite.
** The extended result codes are disabled by default for historical
** compatibility.
**
** INVARIANTS:
**
** {F12201} New [sqlite3 | database connections] have the 
**          [SQLITE_IOERR_READ | extended result codes] feature
**          disabled by default.
**
** {F12202} The [sqlite3_extended_result_codes()] interface will enable
**          [SQLITE_IOERR_READ | extended result codes] for the 

** INSERT continues to completion after deleting rows that caused
** the constraint problem so INSERT OR REPLACE will always change
** the return value of this interface. 
**
** For the purposes of this routine, an insert is considered to
** be successful even if it is subsequently rolled back.
**
** INVARIANTS:
**
** {F12221} The [sqlite3_last_insert_rowid()] function returns the
**          rowid of the most recent successful insert done
**          on the same database connection and within the same
**          trigger context, or zero if there have
**          been no qualifying inserts on that connection.
**

** faster than going through and deleting individual elements from the
** table.)  Because of this optimization, the deletions in
** "DELETE FROM table" are not row changes and will not be counted
** by the sqlite3_changes() or [sqlite3_total_changes()] functions.
** To get an accurate count of the number of rows deleted, use
** "DELETE FROM table WHERE 1" instead.
**
** INVARIANTS:
**
** {F12241} The [sqlite3_changes()] function returns the number of
**          row changes caused by the most recent INSERT, UPDATE,
**          or DELETE statement on the same database connection and
**          within the same trigger context, or zero if there have
**          not been any qualifying row changes.
**

** this optimization, the change count for "DELETE FROM table" will be
** zero regardless of the number of elements that were originally in the
** table. To get an accurate count of the number of rows deleted, use
** "DELETE FROM table WHERE 1" instead.
**
** See also the [sqlite3_change()] interface.
**
** INVARIANTS:
** 
** {F12261} The [sqlite3_total_changes()] returns the total number
**          of row changes caused by INSERT, UPDATE, and/or DELETE
**          statements on the same [sqlite3 | database connection], in any
**          trigger context, since the database connection was
**          created.
**

** An SQL operation that is interrupted will return
** [SQLITE_INTERRUPT].  If the interrupted SQL operation is an
** INSERT, UPDATE, or DELETE that is inside an explicit transaction, 
** then the entire transaction will be rolled back automatically.
** A call to sqlite3_interrupt() has no effect on SQL statements
** that are started after sqlite3_interrupt() returns.
**
** INVARIANTS:
**
** {F12271} The [sqlite3_interrupt()] interface will force all running
**          SQL statements associated with the same database connection
**          to halt after processing at most one additional row of
**          data.
**
** {F12272} Any SQL statement that is interrupted by [sqlite3_interrupt()]

** string literals or quoted identifier names or comments are not
** independent tokens (they are part of the token in which they are
** embedded) and thus do not count as a statement terminator.
**
** These routines do not parse the SQL and
** so will not detect syntactically incorrect SQL.
**
** INVARIANTS:
**
** {F10511} The sqlite3_complete() and sqlite3_complete16() functions
**          return true (non-zero) if and only if the last
**          non-whitespace token in their input is a semicolon that
**          is not in between the BEGIN and END of a CREATE TRIGGER
**          statement.
**

** this is important.
**	
** There can only be a single busy handler defined for each database
** connection.  Setting a new busy handler clears any previous one. 
** Note that calling [sqlite3_busy_timeout()] will also set or clear
** the busy handler.
**
** INVARIANTS:
**
** {F12311} The [sqlite3_busy_handler()] function replaces the busy handler
**          callback in the database connection identified by the 1st
**          parameter with a new busy handler identified by the 2nd and 3rd
**          parameters.
**
** {F12312} The default busy handler for new database connections is NULL.

** turns off all busy handlers.
**
** There can only be a single busy handler for a particular database
** connection.  If another busy handler was defined  
** (using [sqlite3_busy_handler()]) prior to calling
** this routine, that other busy handler is cleared.
**
** INVARIANTS:
**
** {F12341} The [sqlite3_busy_timeout()] function overrides any prior
**          [sqlite3_busy_timeout()] or [sqlite3_busy_handler()] setting
**          on the same database connection.
**
** {F12343} If the 2nd parameter to [sqlite3_busy_timeout()] is less than
**          or equal to zero, then the busy handler is cleared so that

** After the calling function has finished using the result, it should 
** pass the pointer to the result table to sqlite3_free_table() in order to 
** release the memory that was malloc-ed.  Because of the way the 
** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
** function must not try to call [sqlite3_free()] directly.  Only 
** [sqlite3_free_table()] is able to release the memory properly and safely.
**
** The sqlite3_get_table() interface is implemented as a wrapper around
** [sqlite3_exec()].  The sqlite3_get_table() routine does not have access
** to any internal data structures of SQLite.  It uses only the public
** interface defined here.  As a consequence, errors that occur in the
** wrapper layer outside of the internal [sqlite3_exec()] call are not
** reflected in subsequent calls to [sqlite3_errcode()] or
** [sqlite3_errmsg()].
**
** INVARIANTS:
**
** {F12371} If a [sqlite3_get_table()] fails a memory allocation, then
**          it frees the result table under construction, aborts the
**          query in process, skips any subsequent queries, sets the
**          *resultp output pointer to NULL and returns [SQLITE_NOMEM].
**
** {F12373} If the ncolumn parameter to [sqlite3_get_table()] is not NULL

**          successful (if the function returns SQLITE_OK).
**
** {F12373} The [sqlite3_get_table()] function sets its *ncolumn value
**          to the number of columns in the result set of the query in the
**          sql parameter, or to zero if the query in sql has an empty
**          result set.
**
** LIMITATIONS:
**
** {F12380} Error codes returned [sqlite3_get_table()] might not be
**          seen by subsequent calls to [sqlite3_errcode()], or
**          [sqlite3_errmsg()].
**
*/
int sqlite3_get_table(
  sqlite3*,             /* An open database */
  const char *sql,      /* SQL to be evaluated */
  char ***pResult,      /* Results of the query */
  int *nrow,            /* Number of result rows written here */
  int *ncolumn,         /* Number of result columns written here */

** The code above will render a correct SQL statement in the zSQL
** variable even if the zText variable is a NULL pointer.
**
** The "%z" formatting option works exactly like "%s" with the
** addition that after the string has been read and copied into
** the result, [sqlite3_free()] is called on the input string. {END}
**
** INVARIANTS:
**
** {F17403}  The [sqlite3_mprintf()] and [sqlite3_vmprintf()] interfaces
**           return either pointers to zero-terminated UTF-8 strings held in
**           memory obtained from [sqlite3_malloc()] or NULL pointers if
**           a call to [sqlite3_malloc()] fails.
**
** {F17406}  The [sqlite3_snprintf()] interface writes a zero-terminated
**           UTF-8 string into the buffer pointed to by the second parameter
**           provided that the first parameter is greater than zero.
**
** {F17407}  The [sqlite3_snprintf()] interface does not writes slots of
**           its output buffer (the second parameter) outside the range
**           of 0 through N-1 (where N is the first parameter)
**           regardless of the length of the string
**           requested by the format specification.
**   
*/
char *sqlite3_mprintf(const char*,...);
char *sqlite3_vmprintf(const char*, va_list);
char *sqlite3_snprintf(int,char*,const char*, ...);

/*
** CAPI3REF: Memory Allocation Subsystem {F17300}
**
** The SQLite core  uses these three routines for all of its own
** internal memory allocation needs. "Core" in the previous sentence
** does not include operating-system specific VFS implementation.  The
** windows VFS uses native malloc and free for some operations.
**
** The sqlite3_malloc() routine returns a pointer to a block
** of memory at least N bytes in length, where N is the parameter.
** If sqlite3_malloc() is unable to obtain sufficient free
** memory, it returns a NULL pointer.  If the parameter N to
** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
** a NULL pointer.
**
** Calling sqlite3_free() with a pointer previously returned
** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
** that it might be reused.  The sqlite3_free() routine is
** a no-op if is called with a NULL pointer.  Passing a NULL pointer
** to sqlite3_free() is harmless.  After being freed, memory
** should neither be read nor written.  Even reading previously freed
** memory might result in a segmentation fault or other severe error.
** Memory corruption, a segmentation fault, or other severe error
** might result if sqlite3_free() is called with a non-NULL pointer that
** was not obtained from sqlite3_malloc() or sqlite3_free().
**
** {F17310} The sqlite3_realloc() interface attempts to resize a
** prior memory allocation to be at least N bytes, where N is the
** second parameter.  The memory allocation to be resized is the first
** parameter.  {F17311} If the first parameter to sqlite3_realloc()

** The windows OS interface layer calls
** the system malloc() and free() directly when converting
** filenames between the UTF-8 encoding used by SQLite
** and whatever filename encoding is used by the particular windows
** installation.  Memory allocation errors are detected, but
** they are reported back as [SQLITE_CANTOPEN] or
** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
**
** INVARIANTS:
**
** {F17303}  The [sqlite3_malloc()] interface returns either a pointer to 
**           newly checked-out block of at least N bytes of memory
**           (where N is the first parameter) that is 8-byte aligned, 
**           or it returns NULL if it is unable to fulfill the request.
**
** {F17304}  The [sqlite3_malloc()] interface returns a NULL pointer if
**           its parameter is less than or equal to zero.
**
** {F17305}  The [sqlite3_free()] interface releases memory previously
**           returned from [sqlite3_malloc()] or [sqlite3_realloc()],
**           making it available for reuse.
**
** {F17306}  If the argument to [sqlite3_free()] is a NULL pointer, then
**           the [sqlite3_free()] call is a harmless no-op.
**
** {F17310}  A call to [sqlite3_realloc](0,N) is equivalent to a call
**           to [sqlite3_malloc](N).
**
** {F17312}  A call to [sqlite3_realloc](p,0) is equivalent to a call
**           to [sqlite3_free](p).
**
** {F17315}  The SQLite core uses [sqlite3_malloc], [sqlite3_realloc],
**           and [sqlite3_free] for all of its memory allocation and
**           deallocation.
**
** {F17318}  The [sqlite3_realloc] interface returns either a pointer to a block
**           of checked-out memory of at least N bytes in size (where N
**           is the second parameter) that is 8-byte aligned, or a NULL
**           pointer.
**
** {F17321}  When [sqlite3_realloc] returns a non-NULL pointer, it first
**           copies K bytes of content from the buffer given by the first
**           parameter into the newly allocated buffer, where K is the smaller
**           of N and the size of the buffer given in the first parameter.
**
** {F17322}  When [sqlite3_realloc] returns a non-NULL pointer, it first
**           releases the buffer given in the first parameter.
**
** {F17323}  When [sqlite3_realloc] returns NULL, the buffer pointed to by
**           the first parameter is not released and its content is not
**           altered.
**
** LIMITATIONS:
**
** {U17350}  The pointer arguments to [sqlite3_free] and [sqlite3_realloc]
**           must be either NULL or else a pointer obtained from a prior
**           invocation of [sqlite3_malloc] or [sqlite3_realloc] that has
**           not been released.
**
** {U17351}  The application must not read or write memory any part of 
**           a block of memory after it has been released.
**
*/
void *sqlite3_malloc(int);
void *sqlite3_realloc(void*, int);
void sqlite3_free(void*);

/*
** CAPI3REF: Memory Allocator Statistics {F17370}

** routines have been call and remain unchanged thereafter.
*/
SQLITE_EXTERN char *sqlite3_temp_directory;

/*
** CAPI3REF:  Test To See If The Database Is In Auto-Commit Mode {F12930}
**
** The sqlite3_get_autocommit() interfaces returns non-zero or
** zero if the given database connection is or is not in autocommit mode,
** respectively.   Autocommit mode is on
** by default.  Autocommit mode is disabled by a [BEGIN] statement.
** Autocommit mode is reenabled by a [COMMIT] or [ROLLBACK].
**
** If certain kinds of errors occur on a statement within a multi-statement
** transactions (errors including [SQLITE_FULL], [SQLITE_IOERR], 
** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
** transaction might be rolled back automatically.  The only way to
** find out if SQLite automatically rolled back the transaction after
** an error is to use this function.
**
** INVARIANTS:
**
** {F12931} The [sqlite3_get_autocommit()] interface returns non-zero or
**          zero if the given database connection is or is not in autocommit
**          mode, respectively.
**
** {F12932} Autocommit mode is on by default.
**
** {F12933} Autocommit mode is disabled by a successful [BEGIN] statement.
**
** {F12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK]
**          statement.
** 
**
** LIMITATIONS:
***
** {U12936} If another thread changes the autocommit status of the database
**          connection while this routine is running, then the return value
**          is undefined.
*/
int sqlite3_get_autocommit(sqlite3*);

/*
** CAPI3REF:  Find The Database Handle Of A Prepared Statement {F13120}
**
** {F13121} The sqlite3_db_handle interface

# 
proc hd_resolve_2ndpass {text} {
  regsub -all {\[(.*?)\]} $text \
      "\175; hd_resolve_one \173\\1\175; hd_puts \173" text
  eval "hd_puts \173$text\175"
}
proc hd_resolve_one {x} {
  if {[string is integer $x]} {
    hd_puts \[$x\]
    return
  }
  set x2 [split $x |]
  set kw [string trim [lindex $x2 0]]
  if {[llength $x2]==1} {
    set content $kw
    regsub {\([^)]*\)} $content {} kw
    regsub -all {[^a-zA-Z0-9_.# -]} $kw {} kw
  } else {
    regsub -all {[^a-zA-Z0-9_.# -]} $kw {} kw
    set content [string trim [lindex $x2 1]]
  }
  global hd llink glink
  if {$hd(enable-main)} {
    set fn $hd(fn-main)