Documentation Source Text

  }
  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
set fd [open $::SRC/VERSION r]
................................................................................
  global Opcode
  set out {}
  while {[regexp {^(.*?)(OP_[A-Z][a-z])\y(.*)$} $txt \
             all pre op tail] ||
        [regexp {^(.*?)\y((OP_)?[A-Z][A-Za-z][A-Za-z0-9]+)\y(.*)$} $txt \
             all pre op opx tail]} {
    hd_resolve $pre
    if {($pre=="" || [regexp {> *$} $pre]) && ![regexp {^OP_} $op]} {

      hd_puts $op
    } else {
      regsub {^OP_} $op {} key
      if {[info exists Opcode($key:text)]} {
        hd_puts "<a href=\"opcode.html#$key\">$key</a>"
      } else {
        hd_puts $op
................................................................................
after the OP_ResultRow on the next call
to [sqlite3_step()].
}
</tcl>

<h2>Registers</h2>



<p>Every bytecode program has a fixed (but potentially large) number of
registers.  A single register can hold a variety of objects:
<ul>
<li> A NULL value
<li> A signed 64-bit integer
<li> An IEEE double-precision (64-bit) floating point number
<li> An arbitrary length strings
<li> An arbitrary length BLOB
<li> A RowSet object (used internally)

<li> A Frame object (used internally)
</ul>



<p>A register can also be "Undefined" meaning that it holds no value
at all.  Undefined is different from NULL.  Depending on compile-time
options, an attempt to read an undefined register will usually cause
a run-time error.  If the code generator ([sqlite3_prepare_v2()])
ever generates a [prepared statement] that reads an Undefined register,
that is a bug in the code generator.
................................................................................
(ex: OP_Next or OP_Prev), and so forth.
All cursors are automatically
closed when the prepared statement is [sqlite3_reset()|reset] or
[sqlite3_finalize()|finalized].
}
</tcl>


<h2>Subroutines, Coroutines, and Subprograms</h2>

<p>The bytecode engine has no stack on which to store the return address
of a subroutine.  Return addresses must be stored in registers.
Hence, bytecode subroutines are not reentrant.

<tcl>
................................................................................
OP_Program opcode invokes the trigger subprogram.  The OP_Program instruction
allocates and initializes a fresh register set for each invocation of the
subprogram, so subprograms can be reentrant and recursive.  The
OP_Param opcode is used by subprograms to access content in registers
of the calling bytecode program.
}
</tcl>


















<h1>Viewing The Bytecode</h1>

<p>Every SQL statement that SQLite interprets results in a program
for the virtual machine.  But if the SQL statement begins with
the keyword [EXPLAIN] the virtual machine will not execute the
program.  Instead, the instructions of the program will be returned,

  }
  set line [string trim [string range $line 3 end]]
  if {$line==""} {
    append Opcode($current_op:text) $pend
    set pend {}
    set pstart {<p>}
  } else {
    if {![regexp {</?(ul|li|ol)} $line]} {
      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
set fd [open $::SRC/VERSION r]
................................................................................
  global Opcode
  set out {}
  while {[regexp {^(.*?)(OP_[A-Z][a-z])\y(.*)$} $txt \
             all pre op tail] ||
        [regexp {^(.*?)\y((OP_)?[A-Z][A-Za-z][A-Za-z0-9]+)\y(.*)$} $txt \
             all pre op opx tail]} {
    hd_resolve $pre
    if {($pre=="" || [regexp {> *$} $pre]) && ![regexp {^OP_} $op]
         || [regexp {^object} [string trim $tail]]} {
      hd_puts $op
    } else {
      regsub {^OP_} $op {} key
      if {[info exists Opcode($key:text)]} {
        hd_puts "<a href=\"opcode.html#$key\">$key</a>"
      } else {
        hd_puts $op
................................................................................
after the OP_ResultRow on the next call
to [sqlite3_step()].
}
</tcl>

<h2>Registers</h2>

<tcl>
LinkOpcodeNames {
<p>Every bytecode program has a fixed (but potentially large) number of
registers.  A single register can hold a variety of objects:
<ul>
<li> A NULL value
<li> A signed 64-bit integer
<li> An IEEE double-precision (64-bit) floating point number
<li> An arbitrary length strings
<li> An arbitrary length BLOB
<li> A RowSet object (See the OP_RowSetAdd, OP_RowSetRead, and
                      OP_RowSetTest opcodes)
<li> A Frame object (Used by [subprograms] - see OP_Program)
</ul>
}
</tcl>

<p>A register can also be "Undefined" meaning that it holds no value
at all.  Undefined is different from NULL.  Depending on compile-time
options, an attempt to read an undefined register will usually cause
a run-time error.  If the code generator ([sqlite3_prepare_v2()])
ever generates a [prepared statement] that reads an Undefined register,
that is a bug in the code generator.
................................................................................
(ex: OP_Next or OP_Prev), and so forth.
All cursors are automatically
closed when the prepared statement is [sqlite3_reset()|reset] or
[sqlite3_finalize()|finalized].
}
</tcl>

<tcl>hd_fragment subprog subprograms</tcl>
<h2>Subroutines, Coroutines, and Subprograms</h2>

<p>The bytecode engine has no stack on which to store the return address
of a subroutine.  Return addresses must be stored in registers.
Hence, bytecode subroutines are not reentrant.

<tcl>
................................................................................
OP_Program opcode invokes the trigger subprogram.  The OP_Program instruction
allocates and initializes a fresh register set for each invocation of the
subprogram, so subprograms can be reentrant and recursive.  The
OP_Param opcode is used by subprograms to access content in registers
of the calling bytecode program.
}
</tcl>

<h2>Self-Altering Code</h2>

<tcl>
LinkOpcodeNames {
<p>Some opcodes are self-altering.
For example, the OP_Init opcode (which is always the first opcode
run a bytecode program) increments its P1 operand.  Subsequent
OP_Once opcodes compare their P1 operands to the P1 value for
the OP_Init opcode in order to determine if the one-time initialization
code that follows should be skipped.
Another example is the OP_String8 opcode which converts its P4
operand from UTF-8 into the correct database string encoding, then
converts itself into a OP_String opcode.
}
</tcl>


<h1>Viewing The Bytecode</h1>

<p>Every SQL statement that SQLite interprets results in a program
for the virtual machine.  But if the SQL statement begins with
the keyword [EXPLAIN] the virtual machine will not execute the
program.  Instead, the instructions of the program will be returned,