opcode.html

嵌入式数据库sqlite 3.5.9的文档

then runs the new virtual machine.  It is thus a reentrant opcode.</td></tr>
<tr><td valign="top" align="center">
<a name="Prev"></a><p>Prev</p>
<td><p>Back up cursor P1 so that it points to the previous key/data pair in its
table or index.  If there is no previous key/value pairs then fall through
to the following instruction.  But if the cursor backup was successful,
jump immediately to P2.</p>

<p>The P1 cursor must be for a real table, not a pseudo-table.</td></tr>
<tr><td valign="top" align="center">
<a name="ReadCookie"></a><p>ReadCookie</p>
<td><p>Read cookie number P3 from database P1 and write it into register P2.
P3==0 is the schema version.  P3==1 is the database format.
P3==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>If P1 is negative, then this is a request to read the size of a
databases free-list. P3 must be set to 1 in this case. The actual
database accessed is ((P1+1)*-1). For example, a P1 parameter of -1
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 throught 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 immediately to the next instruction after the last unreturned
OP_Gosub.  If an OP_Return has occurred for all OP_Gosubs, then
processing aborts with a fatal error.</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.  If p2==0 then push the integer.</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="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="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 numeric, convert it to a string using the
equivalent of printf().  Blob values are unchanged and
are afterwards simply interpreted as text.</p>

<p>A NULL value is not changed by this routine.  It remains NULL.</td></tr>
<tr><td valign="top" align="center">
<a name="Trace"></a><p>Trace</p>
<td><p>If tracing is enabled (by the sqlite3_trace()) interface, then
the UTF-8 string contained in P4 is emitted on the trace callback.</td></tr>
<tr><td valign="top" align="center">
<a name="Transaction"></a><p>Transaction</p>
<td><p>Begin a transaction.  The transaction ends when a Commit or Rollback
opcode is encountered.  Depending on the ON CONFLICT setting, the
transaction might also be rolled back if an error is encountered.</p>

<p>P1 is the index of the database file on which the transaction is
started.  Index 0 is t