opcode.html

嵌入式数据库sqlite 3.5.9的文档

<a name="MakeRecord"></a><p>MakeRecord</p>
<td><p>Convert P2 registers beginning with P1 into a single entry
suitable for use as a data record in a database table or as a key
in an index.  The details of the format are irrelavant as long as
the OP_Column opcode can decode the record later.
Refer to source code comments for the details of the record
format.</p>

<p>P4 may be a string that is P2 characters long.  The nth character of the
string indicates the column affinity that should be used for the nth
field of the index key.</p>

<p>The mapping from character to affinity is given by the SQLITE_AFF_
macros defined in sqliteInt.h.</p>

<p>If P4 is NULL then all index fields have the affinity NONE.</td></tr>
<tr><td valign="top" align="center">
<a name="MemMax"></a><p>MemMax</p>
<td><p>Set the value of register P1 to the maximum of its current value
and the value in register P2.</p>

<p>This instruction throws an error if the memory cell is not initially
an integer.</td></tr>
<tr><td valign="top" align="center">
<a name="Move"></a><p>Move</p>
<td><p>Move the value in register P1 over into register P2.  Register P1
is left holding a NULL.  It is an error for P1 and P2 to be the
same register.</td></tr>
<tr><td valign="top" align="center">
<a name="MoveGe"></a><p>MoveGe</p>
<td><p>If cursor P1 refers to an SQL table (B-Tree that uses integer keys),
use the integer 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 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>A special feature of this opcode (and different from the
related OP_MoveGt, OP_MoveLt, and OP_MoveLe) is that if P2 is
zero and P1 is an SQL table (a b-tree with integer keys) then
the seek is deferred until it is actually needed.  It might be
the case that the cursor is never accessed.  By deferring the
seek, we avoid unnecessary seeks.</p>

<p>See also: Found, NotFound, Distinct, MoveLt, MoveGt, MoveLe</td></tr>
<tr><td valign="top" align="center">
<a name="MoveGt"></a><p>MoveGt</p>
<td><p>If cursor P1 refers to an SQL table (B-Tree that uses integer keys),
use the integer 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, MoveLt, MoveGe, MoveLe</td></tr>
<tr><td valign="top" align="center">
<a name="MoveLe"></a><p>MoveLe</p>
<td><p>If cursor P1 refers to an SQL table (B-Tree that uses integer keys),
use the integer 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, MoveGt, MoveGe, MoveLt</td></tr>
<tr><td valign="top" align="center">
<a name="MoveLt"></a><p>MoveLt</p>
<td><p>If cursor P1 refers to an SQL table (B-Tree that uses integer keys),
use the integer 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, MoveGt, MoveGe, MoveLe</td></tr>
<tr><td valign="top" align="center">
<a name="Multiply"></a><p>Multiply</p>
<td><p>Multiply the value in regiser P1 by the value in regiser 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="MustBeInt"></a><p>MustBeInt</p>
<td><p>Force the value in register P1 to be an integer.  If the value
in P1 is not an integer and cannot be converted into an integer
without data loss, then jump immediately to P2, or if P2==0
raise an SQLITE_MISMATCH exception.</td></tr>
<tr><td valign="top" align="center">
<a name="Ne"></a><p>Ne</p>
<td><p>This works just like the Lt opcode except that the jump is taken if
the operands in registers P1 and P3 are not equal.  See the Lt opcode for
additional information.</td></tr>
<tr><td valign="top" align="center">
<a name="NewRowid"></a><p>NewRowid</p>
<td><p>Get a new integer record number (a.k.a "rowid") used as the key to a table.
The record number is not previously used as a key in the database
table that cursor P1 points to.  The new record number is written
written to register P2.</p>

<p>If P3&gt;0 then P3 is a register that holds the largest previously
generated record number.  No new record numbers are allowed to be less
than this value.  When this value reaches its maximum, a SQLITE_FULL
error is generated.  The P3 register is updated with the generated
record number.  This P3 mechanism is used to help implement the
AUTOINCREMENT feature.</td></tr>
<tr><td valign="top" align="center">
<a name="Next"></a><p>Next</p>
<td><p>Advance cursor P1 so that it points to the next key/data pair in its
table or index.  If there are no more key/value pairs then fall through
to the following instruction.  But if the cursor advance was successful,
jump immediately to P2.</p>

<p>The P1 cursor must be for a real table, not a pseudo-table.</p>

<p>See also: Prev</td></tr>
<tr><td valign="top" align="center">
<a name="Noop"></a><p>Noop</p>
<td><p>Do nothing.  This instruction is often useful as a jump
destination.</td></tr>
<tr><td valign="top" align="center">
<a name="Not"></a><p>Not</p>
<td><p>Interpret the value in register P1 as a boolean value.  Replace it
with its complement.  If the value in register P1 is NULL its value
is unchanged.</td></tr>
<tr><td valign="top" align="center">
<a name="NotExists"></a><p>NotExists</p>
<td><p>Use the content of register P3 as a integer key.  If a record
with that key does not exist in table of P1, then jump to P2.
If the record does exist, then fall thru.  The cursor is left
pointing to the record if it exists.</p>

<p>The difference between this operation and NotFound is that this
operation assumes the key is an integer and that P1 is a table whereas
NotFound assumes key is a blob constructed from MakeRecord and
P1 is an index.</p>

<p>See also: Found, MoveTo, NotFound, IsUnique</td></tr>
<tr><td valign="top" align="center">
<a name="NotFound"></a><p>NotFound</p>
<td><p>Register P3 holds a blob constructed by MakeRecord.  P1 is
an index.  If no entry exists in P1 that matches the blob then jump
to P2.  If an entry does existing, fall through.  The cursor is left
pointing to the entry that matches.</p>

<p>See also: Found, MoveTo, NotExists, IsUnique</td></tr>
<tr><td valign="top" align="center">
<a name="NotNull"></a><p>NotNull</p>
<td><p>Jump to P2 if the value in register P1 is not NULL.</td></tr>
<tr><td valign="top" align="center">
<a name="Null"></a><p>Null</p>
<td><p>Write a NULL into register P2.</td></tr>
<tr><td valign="top" align="center">
<a name="NullRow"></a><p>NullRow</p>
<td><p>Move the cursor P1 to a null row.  Any OP_Column operations
that occur while the cursor is on the null row will always
write a NULL.</td></tr>
<tr><td valign="top" align="center">
<a name="OpenEphemeral"></a><p>OpenEphemeral</p>
<td><p>Open a new cursor P1 to a transient table.
The cursor is always opened read/write even if
the main database is read-only.  The transient or virtual
table is deleted automatically when the cursor is closed.</p>

<p>P2 is the number of columns in the virtual table.
The cursor points to a BTree table if P4==0 and to a BTree index
if P4 is not 0.  If P4 is not NULL, it points to a KeyInfo structure
that defines the format of keys in the index.</p>

<p>This opcode was once called OpenTemp.  But that created
confusion because the term "temp table", might refer either
to a TEMP table at the SQL level, or to a table opened by
this opcode.  Then this opcode was call OpenVirtual.  But
that created confusion with the whole virtual-table idea.</td></tr>
<tr><td valign="top" align="center">
<a name="OpenPseudo"></a><p>OpenPseudo</p>
<td><p>Open a new cursor that points to a fake table that contains a single
row of data.  Any attempt to write a second row of data causes the
first row to be deleted.  All data is deleted when the cursor is
closed.</p>

<p>A pseudo-table created by this opcode is useful for holding the
NEW or OLD tables in a trigger.  Also used to hold the a single
row output from the sorter so that the row can be decomposed into
individual columns using the OP_Column opcode.</p>

<p>When OP_Insert is executed to insert a row in to the pseudo table,
the pseudo-table cursor may or may not make it's own copy of the
original row data. If P2 is 0, then the pseudo-table will copy the
original row data. Otherwise, a pointer to the original memory cell
is stored. In this case, the vdbe program must ensure that the
memory cell containing the row data is not overwritten until the
pseudo table is closed (or a new row is inserted into it).</td></tr>
<tr><td valign="top" align="center">
<a name="OpenRead"></a><p>OpenRead</p>
<td><p>Open a read-only cursor for the database table whose root page is
P2 in a database file.  The database file is determined by P3.
P3==0 means the main database, P3==1 means the database used for
temporary tables, and P3&gt;1 means used the corresponding attached
database.  Give the new cursor an identifier of P1.  The P1
values need not be contiguous but all P1 values should be small integers.
It is an error for P1 to be negative.</p>

<p>If P5!=0 then use the content of register P2 as the root page, not
the value of P2 itself.</p>

<p>There will be a read lock on the database whenever there is an
open cursor.  If the database was unlocked prior to this instruction
then a read lock is acquired as part of this instruction.  A read
lock allows other processes to read the database but prohibits
any other process from modifying the database.  The read lock is
released when all cursors are closed.  If this instruction attempts
to get a read lock but fails, the script terminates with an
SQLITE_BUSY error code.</p>

<p>The P4 value is a pointer to a KeyInfo structure that defines the
content and collating sequence of indices.  P4 is NULL for cursors
that are not pointing to indices.</p>

<p>See also OpenWrite.</td></tr>
<tr><td valign="top" align="center">
<a name="OpenWrite"></a><p>OpenWrite</p>
<td><p>Open a read/write cursor named P1 on the table or index whose root
page is P2.  Or if P5!=0 use the content of register P2 to find the
root page.</p>

<p>The P4 value is a pointer to a KeyInfo structure that defines the
content and collating sequence of indices.  P4 is NULL for cursors
that are not pointing to indices.</p>

<p>This instruction works just like OpenRead except that it opens the cursor
in read/write mode.  For a given table, there can be one or more read-only
cursors or a single read/write cursor but not both.</p>

<p>See also OpenRead.</td></tr>
<tr><td valign="top" align="center">
<a name="Or"></a><p>Or</p>
<td><p>Take the logical OR of the values in register P1 and P2 and
store the answer in register P3.</p>

<p>If either P1 or P2 is nonzero (true) then the result is 1 (true)
even if the other input is NULL.  A NULL and false or two NULLs
give a NULL output.</td></tr>
<tr><td valign="top" align="center">
<a name="ParseSchema"></a><p>ParseSchema</p>
<td><p>Read and parse all entries from the SQLITE_MASTER table of database P1
that match the WHERE clause P4.  P2 is the "force" flag.   Always do
the parsing if P2 is true.  If P2 is false, then this routine is a
no-op if the schema is not currently loaded.  In other words, if P2
is false, the SQLITE_MASTER table is only parsed if the rest of the
schema is already loaded into the symbol table.</p>

<p>This opcode invokes the parser to create a new virtual machine,