opcode.html

sqlite3源码,适合作为嵌入式（embedded）

corresponds to database 0 ("main"), a P1 of -2 is database 1 ("temp").</p>

<p>There must be a read-lock on the database (either a transaction
must be started or there must be an open cursor) before
executing this instruction.</td></tr><tr><td valign="top" align="center"><a name="Real"></a><p>Real</p><td><p>P4 is a pointer to a 64-bit floating point value.
Write that value into register P2.</td></tr><tr><td valign="top" align="center"><a name="RealAffinity"></a><p>RealAffinity</p><td><p>If register P1 holds an integer convert it to a real value.</p>

<p>This opcode is used when extracting information from a column that
has REAL affinity.  Such column values may still be stored as
integers, for space efficiency, but after extraction we want them
to have only a real value.</td></tr><tr><td valign="top" align="center"><a name="Remainder"></a><p>Remainder</p><td><p>Compute the remainder after integer division of the value in
register P1 by the value in register P2 and store the result in P3.
If the value in register P2 is zero the result is NULL.
If either operand is NULL, the result is NULL.</td></tr><tr><td valign="top" align="center"><a name="ResetCount"></a><p>ResetCount</p><td><p>This opcode resets the VMs internal change counter to 0. If P1 is true,
then the value of the change counter is copied to the database handle
change counter (returned by subsequent calls to sqlite3_changes())
before it is reset. This is used by trigger programs.</td></tr><tr><td valign="top" align="center"><a name="ResultRow"></a><p>ResultRow</p><td><p>The registers P1 through P1+P2-1 contain a single row of
results. This opcode causes the sqlite3_step() call to terminate
with an SQLITE_ROW return code and it sets up the sqlite3_stmt
structure to provide access to the top P1 values as the result
row.</td></tr><tr><td valign="top" align="center"><a name="Return"></a><p>Return</p><td><p>Jump to the next instruction after the address in register P1.</td></tr><tr><td valign="top" align="center"><a name="Rewind"></a><p>Rewind</p><td><p>The next use of the Rowid or Column or Next instruction for P1
will refer to the first entry in the database table or index.
If the table or index is empty and P2&gt;0, then jump immediately to P2.
If P2 is 0 or if the table or index is not empty, fall through
to the following instruction.</td></tr><tr><td valign="top" align="center"><a name="RowData"></a><p>RowData</p><td><p>Write into register P2 the complete row data for cursor P1.
There is no interpretation of the data.
It is just copied onto the P2 register exactly as
it is found in the database file.</p>

<p>If the P1 cursor must be pointing to a valid row (not a NULL row)
of a real table, not a pseudo-table.</td></tr><tr><td valign="top" align="center"><a name="Rowid"></a><p>Rowid</p><td><p>Store in register P2 an integer which is the key of the table entry that
P1 is currently point to.</td></tr><tr><td valign="top" align="center"><a name="RowKey"></a><p>RowKey</p><td><p>Write into register P2 the complete row key for cursor P1.
There is no interpretation of the data.
The key is copied onto the P3 register exactly as
it is found in the database file.</p>

<p>If the P1 cursor must be pointing to a valid row (not a NULL row)
of a real table, not a pseudo-table.</td></tr><tr><td valign="top" align="center"><a name="RowSetAdd"></a><p>RowSetAdd</p><td><p>Insert the integer value held by register P2 into a boolean index
held in register P1.</p>

<p>An assertion fails if P2 is not an integer.</td></tr><tr><td valign="top" align="center"><a name="RowSetRead"></a><p>RowSetRead</p><td><p>Extract the smallest value from boolean index P1 and put that value into
register P3.  Or, if boolean index P1 is initially empty, leave P3
unchanged and jump to instruction P2.</td></tr><tr><td valign="top" align="center"><a name="Savepoint"></a><p>Savepoint</p><td><p>Open, release or rollback the savepoint named by parameter P4, depending
on the value of P1. To open a new savepoint, P1==0. To release (commit) an
existing savepoint, P1==1, or to rollback an existing savepoint P1==2.</td></tr><tr><td valign="top" align="center"><a name="SCopy"></a><p>SCopy</p><td><p>Make a shallow copy of register P1 into register P2.</p>

<p>This instruction makes a shallow copy of the value.  If the value
is a string or blob, then the copy is only a pointer to the
original and hence if the original changes so will the copy.
Worse, if the original is deallocated, the copy becomes invalid.
Thus the program must guarantee that the original will not change
during the lifetime of the copy.  Use OP_Copy to make a complete
copy.</td></tr><tr><td valign="top" align="center"><a name="Seek"></a><p>Seek</p><td><p>P1 is an open table cursor and P2 is a rowid integer.  Arrange
for P1 to move so that it points to the rowid given by P2.</p>

<p>This is actually a deferred seek.  Nothing actually happens until
the cursor is used to read a record.  That way, if no reads
occur, no unnecessary I/O happens.</td></tr><tr><td valign="top" align="center"><a name="SeekGe"></a><p>SeekGe</p><td><p>If cursor P1 refers to an SQL table (B-Tree that uses integer keys),
use the value in register P3 as the key.  If cursor P1 refers
to an SQL index, then P3 is the first in an array of P4 registers
that are used as an unpacked index key.</p>

<p>Reposition cursor P1 so that  it points to the smallest entry that
is greater than or equal to the key value. If there are no records
greater than or equal to the key and P2 is not zero, then jump to P2.</p>

<p>See also: Found, NotFound, Distinct, SeekLt, SeekGt, SeekLe</td></tr><tr><td valign="top" align="center"><a name="SeekGt"></a><p>SeekGt</p><td><p>If cursor P1 refers to an SQL table (B-Tree that uses integer keys),
use the value in register P3 as a key. If cursor P1 refers
to an SQL index, then P3 is the first in an array of P4 registers
that are used as an unpacked index key.</p>

<p>Reposition cursor P1 so that  it points to the smallest entry that
is greater than the key value. If there are no records greater than
the key and P2 is not zero, then jump to P2.</p>

<p>See also: Found, NotFound, Distinct, SeekLt, SeekGe, SeekLe</td></tr><tr><td valign="top" align="center"><a name="SeekLe"></a><p>SeekLe</p><td><p>If cursor P1 refers to an SQL table (B-Tree that uses integer keys),
use the value in register P3 as a key. If cursor P1 refers
to an SQL index, then P3 is the first in an array of P4 registers
that are used as an unpacked index key.</p>

<p>Reposition cursor P1 so that it points to the largest entry that
is less than or equal to the key value. If there are no records
less than or equal to the key and P2 is not zero, then jump to P2.</p>

<p>See also: Found, NotFound, Distinct, SeekGt, SeekGe, SeekLt</td></tr><tr><td valign="top" align="center"><a name="SeekLt"></a><p>SeekLt</p><td><p>If cursor P1 refers to an SQL table (B-Tree that uses integer keys),
use the value in register P3 as a key. If cursor P1 refers
to an SQL index, then P3 is the first in an array of P4 registers
that are used as an unpacked index key.</p>

<p>Reposition cursor P1 so that  it points to the largest entry that
is less than the key value. If there are no records less than
the key and P2 is not zero, then jump to P2.</p>

<p>See also: Found, NotFound, Distinct, SeekGt, SeekGe, SeekLe</td></tr><tr><td valign="top" align="center"><a name="Sequence"></a><p>Sequence</p><td><p>Find the next available sequence number for cursor P1.
Write the sequence number into register P2.
The sequence number on the cursor is incremented after this
instruction.</td></tr><tr><td valign="top" align="center"><a name="SetCookie"></a><p>SetCookie</p><td><p>Write the content of register P3 (interpreted as an integer)
into cookie number P2 of database P1.
P2==0 is the schema version.  P2==1 is the database format.
P2==2 is the recommended pager cache size, and so forth.  P1==0 is
the main database file and P1==1 is the database file used to store
temporary tables.</p>

<p>A transaction must be started before executing this opcode.</td></tr><tr><td valign="top" align="center"><a name="SetNumColumns"></a><p>SetNumColumns</p><td><p>This opcode sets the number of columns for the cursor opened by the
following instruction to P2.</p>

<p>An OP_SetNumColumns is only useful if it occurs immediately before
one of the following opcodes:</p>

<p>OpenRead
OpenWrite
OpenPseudo</p>

<p>If the OP_Column opcode is to be executed on a cursor, then
this opcode must be present immediately before the opcode that
opens the cursor.</td></tr><tr><td valign="top" align="center"><a name="ShiftLeft"></a><p>ShiftLeft</p><td><p>Shift the integer value in register P2 to the left by the
number of bits specified by the integer in regiser P1.
Store the result in register P3.
If either input is NULL, the result is NULL.</td></tr><tr><td valign="top" align="center"><a name="ShiftRight"></a><p>ShiftRight</p><td><p>Shift the integer value in register P2 to the right by the
number of bits specified by the integer in register P1.
Store the result in register P3.
If either input is NULL, the result is NULL.</td></tr><tr><td valign="top" align="center"><a name="Sort"></a><p>Sort</p><td><p>This opcode does exactly the same thing as OP_Rewind except that
it increments an undocumented global variable used for testing.</p>

<p>Sorting is accomplished by writing records into a sorting index,
then rewinding that index and playing it back from beginning to
end.  We use the OP_Sort opcode instead of OP_Rewind to do the
rewinding so that the global variable will be incremented and
regression tests can determine whether or not the optimizer is
correctly optimizing out sorts.</td></tr><tr><td valign="top" align="center"><a name="Statement"></a><p>Statement</p><td><p>Begin an individual statement transaction which is part of a larger
transaction.  This is needed so that the statement
can be rolled back after an error without having to roll back the
entire transaction.  The statement transaction will automatically
commit when the VDBE halts.</p>

<p>If the database connection is currently in autocommit mode (that
is to say, if it is in between BEGIN and COMMIT)
and if there are no other active statements on the same database
connection, then this operation is a no-op.  No statement transaction
is needed since any error can use the normal ROLLBACK process to
undo changes.</p>

<p>If a statement transaction is started, then a statement journal file
will be allocated and initialized.</p>

<p>The statement is begun on the database file with index P1.  The main
database file has an index of 0 and the file used for temporary tables
has an index of 1.</td></tr><tr><td valign="top" align="center"><a name="String"></a><p>String</p><td><p>The string value P4 of length P1 (bytes) is stored in register P2.</td></tr><tr><td valign="top" align="center"><a name="String8"></a><p>String8</p><td><p>P4 points to a nul terminated UTF-8 string. This opcode is transformed
into an OP_String before it is executed for the first time.</td></tr><tr><td valign="top" align="center"><a name="Subtract"></a><p>Subtract</p><td><p>Subtract the value in register P1 from the value in register P2
and store the result in register P3.
If either input is NULL, the result is NULL.</td></tr><tr><td valign="top" align="center"><a name="TableLock"></a><p>TableLock</p><td><p>Obtain a lock on a particular table. This instruction is only used when
the shared-cache feature is enabled.</p>

<p>If P1 is  the index of the database in sqlite3.aDb[] of the database
on which the lock is acquired.  A readlock is obtained if P3==0 or
a write lock if P3==1.</p>

<p>P2 contains the root-page of the table to lock.</p>

<p>P4 contains a pointer to the name of the table being locked. This is only
used to generate an error message if the lock cannot be obtained.</td></tr><tr><td valign="top" align="center"><a name="ToBlob"></a><p>ToBlob</p><td><p>Force the value in register P1 to be a BLOB.
If the value is numeric, convert it to a string first.
Strings are simply reinterpreted as blobs with no change
to the underlying data.</p>

<p>A NULL value is not changed by this routine.  It remains NULL.</td></tr><tr><td valign="top" align="center"><a name="ToInt"></a><p>ToInt</p><td><p>Force the value in register P1 be an integer.  If
The value is currently a real number, drop its fractional part.
If the value is text or blob, try to convert it to an integer using the
equivalent of atoi() and store 0 if no such conversion is possible.</p>

<p>A NULL value is not changed by this routine.  It remains NULL.</td></tr><tr><td valign="top" align="center"><a name="ToNumeric"></a><p>ToNumeric</p><td><p>Force the value in register P1 to be numeric (either an
integer or a floating-point number.)
If the value is text or blob, try to convert it to an using the
equivalent of atoi() or atof() and store 0 if no such conversion
is possible.</p>

<p>A NULL value is not changed by this routine.  It remains NULL.</td></tr><tr><td valign="top" align="center"><a name="ToReal"></a><p>ToReal</p><td><p>Force the value in register P1 to be a floating point number.
If The value is currently an integer, convert it.
If the value is text or blob, try to convert it to an integer using the
equivalent of atoi() and store 0.0 if no such conversion is possible.</p>

<p>A NULL value is not changed by this routine.  It remains NULL.</td></tr><tr><td valign="top" align="center"><a name="ToText"></a><p>ToText</p><td><p>Force the value in register P1 to be text.
If the value is num