opcode.html

嵌入式数据库sqlite 3.5.9的文档

Register P3 must not be one of the function inputs.</p>

<p>P1 is a 32-bit bitmask indicating whether or not each argument to the
function was determined to be constant at compile time. If the first
argument was constant then bit 0 of P1 is set. This is used to determine
whether meta data associated with a user function argument using the
sqlite3_set_auxdata() API may be safely retained until the next
invocation of this opcode.</p>

<p>See also: AggStep and AggFinal</td></tr>
<tr><td valign="top" align="center">
<a name="Ge"></a><p>Ge</p>
<td><p>This works just like the Lt opcode except that the jump is taken if
the content of register P3 is greater than or equal to the content of
register P1.  See the Lt opcode for additional information.</td></tr>
<tr><td valign="top" align="center">
<a name="Gosub"></a><p>Gosub</p>
<td><p>Push the current address plus 1 onto the return address stack
and then jump to address P2.</p>

<p>The return address stack is of limited depth.  If too many
OP_Gosub operations occur without intervening OP_Returns, then
the return address stack will fill up and processing will abort
with a fatal error.</td></tr>
<tr><td valign="top" align="center">
<a name="Goto"></a><p>Goto</p>
<td><p>An unconditional jump to address P2.
The next instruction executed will be
the one at index P2 from the beginning of
the program.</td></tr>
<tr><td valign="top" align="center">
<a name="Gt"></a><p>Gt</p>
<td><p>This works just like the Lt opcode except that the jump is taken if
the content of register P3 is greater than the content of
register P1.  See the Lt opcode for additional information.</td></tr>
<tr><td valign="top" align="center">
<a name="Halt"></a><p>Halt</p>
<td><p>Exit immediately.  All open cursors, Fifos, etc are closed
automatically.</p>

<p>P1 is the result code returned by sqlite3_exec(), sqlite3_reset(),
or sqlite3_finalize().  For a normal halt, this should be SQLITE_OK (0).
For errors, it can be some other value.  If P1!=0 then P2 will determine
whether or not to rollback the current transaction.  Do not rollback
if P2==OE_Fail. Do the rollback if P2==OE_Rollback.  If P2==OE_Abort,
then back out all changes that have occurred during this execution of the
VDBE, but do not rollback the transaction.</p>

<p>If P4 is not null then it is an error message string.</p>

<p>There is an implied "Halt 0 0 0" instruction inserted at the very end of
every program.  So a jump past the last instruction of the program
is the same as executing Halt.</td></tr>
<tr><td valign="top" align="center">
<a name="IdxDeleteM"></a><p>IdxDeleteM</p>
<td><p>The content of P3 registers starting at register P2 form
an unpacked index key. This opcode removes that entry from the
index opened by cursor P1.</td></tr>
<tr><td valign="top" align="center">
<a name="IdxGE"></a><p>IdxGE</p>
<td><p>The P4 register values beginning with P3 form an unpacked index
key that omits the ROWID.  Compare this key value against the index
that P1 is currently pointing to, ignoring the ROWID on the P1 index.</p>

<p>If the P1 index entry is greater than or equal to the key value
then jump to P2.  Otherwise fall through to the next instruction.</p>

<p>If P5 is non-zero then the key value is increased by an epsilon
prior to the comparison.  This make the opcode work like IdxGT except
that if the key from register P3 is a prefix of the key in the cursor,
the result is false whereas it would be true with IdxGT.</td></tr>
<tr><td valign="top" align="center">
<a name="IdxInsert"></a><p>IdxInsert</p>
<td><p>Register P2 holds a SQL index key made using the
MakeIdxRec instructions.  This opcode writes that key
into the index P1.  Data for the entry is nil.</p>

<p>P3 is a flag that provides a hint to the b-tree layer that this
insert is likely to be an append.</p>

<p>This instruction only works for indices.  The equivalent instruction
for tables is OP_Insert.</td></tr>
<tr><td valign="top" align="center">
<a name="IdxLT"></a><p>IdxLT</p>
<td><p>The P4 register values beginning with P3 form an unpacked index
key that omits the ROWID.  Compare this key value against the index
that P1 is currently pointing to, ignoring the ROWID on the P1 index.</p>

<p>If the P1 index entry is less than the key value then jump to P2.
Otherwise fall through to the next instruction.</p>

<p>If P5 is non-zero then the key value is increased by an epsilon prior
to the comparison.  This makes the opcode work like IdxLE.</td></tr>
<tr><td valign="top" align="center">
<a name="IdxRowid"></a><p>IdxRowid</p>
<td><p>Write into register P2 an integer which is the last entry in the record at
the end of the index key pointed to by cursor P1.  This integer should be
the rowid of the table entry to which this index entry points.</p>

<p>See also: Rowid, MakeIdxRec.</td></tr>
<tr><td valign="top" align="center">
<a name="If"></a><p>If</p>
<td><p>Jump to P2 if the value in register P1 is true.  The value is
is considered true if it is numeric and non-zero.  If the value
in P1 is NULL then take the jump if P3 is true.</td></tr>
<tr><td valign="top" align="center">
<a name="IfNeg"></a><p>IfNeg</p>
<td><p>If the value of register P1 is less than zero, jump to P2.</p>

<p>It is illegal to use this instruction on a register that does
not contain an integer.  An assertion fault will result if you try.</td></tr>
<tr><td valign="top" align="center">
<a name="IfNot"></a><p>IfNot</p>
<td><p>Jump to P2 if the value in register P1 is False.  The value is
is considered true if it has a numeric value of zero.  If the value
in P1 is NULL then take the jump if P3 is true.</td></tr>
<tr><td valign="top" align="center">
<a name="IfPos"></a><p>IfPos</p>
<td><p>If the value of register P1 is 1 or greater, jump to P2.</p>

<p>It is illegal to use this instruction on a register that does
not contain an integer.  An assertion fault will result if you try.</td></tr>
<tr><td valign="top" align="center">
<a name="IfZero"></a><p>IfZero</p>
<td><p>If the value of register P1 is exactly 0, jump to P2.</p>

<p>It is illegal to use this instruction on a register that does
not contain an integer.  An assertion fault will result if you try.</td></tr>
<tr><td valign="top" align="center">
<a name="IncrVacuum"></a><p>IncrVacuum</p>
<td><p>Perform a single step of the incremental vacuum procedure on
the P1 database. If the vacuum has finished, jump to instruction
P2. Otherwise, fall through to the next instruction.</td></tr>
<tr><td valign="top" align="center">
<a name="Insert"></a><p>Insert</p>
<td><p>Write an entry into the table of cursor P1.  A new entry is
created if it doesn't already exist or the data for an existing
entry is overwritten.  The data is the value stored register
number P2. The key is stored in register P3. The key must
be an integer.</p>

<p>If the OPFLAG_NCHANGE flag of P5 is set, then the row change count is
incremented (otherwise not).  If the OPFLAG_LASTROWID flag of P5 is set,
then rowid is stored for subsequent return by the
sqlite3_last_insert_rowid() function (otherwise it is unmodified).</p>

<p>Parameter P4 may point to a string containing the table-name, or
may be NULL. If it is not NULL, then the update-hook
(sqlite3.xUpdateCallback) is invoked following a successful insert.</p>

<p>(WARNING/TODO: If P1 is a pseudo-cursor and P2 is dynamically
allocated, then ownership of P2 is transferred to the pseudo-cursor
and register P2 becomes ephemeral.  If the cursor is changed, the
value of register P2 will then change.  Make sure this does not
cause any problems.)</p>

<p>This instruction only works on tables.  The equivalent instruction
for indices is OP_IdxInsert.</td></tr>
<tr><td valign="top" align="center">
<a name="Int64"></a><p>Int64</p>
<td><p>P4 is a pointer to a 64-bit integer value.
Write that value into register P2.</td></tr>
<tr><td valign="top" align="center">
<a name="Integer"></a><p>Integer</p>
<td><p>The 32-bit integer value P1 is written into register P2.</td></tr>
<tr><td valign="top" align="center">
<a name="IntegrityCk"></a><p>IntegrityCk</p>
<td><p>Do an analysis of the currently open database.  Store in
register P1 the text of an error message describing any problems.
If no problems are found, store a NULL in register P1.</p>

<p>The register P3 contains the maximum number of allowed errors.
At most reg(P3) errors will be reported.
In other words, the analysis stops as soon as reg(P1) errors are
seen.  Reg(P1) is updated with the number of errors remaining.</p>

<p>The root page numbers of all tables in the database are integer
stored in reg(P1), reg(P1+1), reg(P1+2), ....  There are P2 tables
total.</p>

<p>If P5 is not zero, the check is done on the auxiliary database
file, not the main database file.</p>

<p>This opcode is used to implement the integrity_check pragma.</td></tr>
<tr><td valign="top" align="center">
<a name="IsNull"></a><p>IsNull</p>
<td><p>Jump to P2 if the value in register P1 is NULL.  If P3 is greater
than zero, then check all values reg(P1), reg(P1+1),
reg(P1+2), ..., reg(P1+P3-1).</td></tr>
<tr><td valign="top" align="center">
<a name="IsUnique"></a><p>IsUnique</p>
<td><p>The P3 register contains an integer record number.  Call this
record number R.  The P4 register contains an index key created
using MakeIdxRec.  Call it K.</p>

<p>P1 is an index.  So it has no data and its key consists of a
record generated by OP_MakeRecord where the last field is the
rowid of the entry that the index refers to.</p>

<p>This instruction asks if there is an entry in P1 where the
fields matches K but the rowid is different from R.
If there is no such entry, then there is an immediate
jump to P2.  If any entry does exist where the index string
matches K but the record number is not R, then the record
number for that entry is written into P3 and control
falls through to the next instruction.</p>

<p>See also: NotFound, NotExists, Found</td></tr>
<tr><td valign="top" align="center">
<a name="Last"></a><p>Last</p>
<td><p>The next use of the Rowid or Column or Next instruction for P1
will refer to the last 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="Le"></a><p>Le</p>
<td><p>This works just like the Lt opcode except that the jump is taken if
the content of register P3 is less than or equal to the content of
register P1.  See the Lt opcode for additional information.</td></tr>
<tr><td valign="top" align="center">
<a name="LoadAnalysis"></a><p>LoadAnalysis</p>
<td><p>Read the sqlite_stat1 table for database P1 and load the content
of that table into the internal index hash table.  This will cause
the analysis to be used when preparing all subsequent queries.</td></tr>
<tr><td valign="top" align="center">
<a name="Lt"></a><p>Lt</p>
<td><p>Compare the values in register P1 and P3.  If reg(P3)&lt;reg(P1) then
jump to address P2.</p>

<p>If the SQLITE_JUMPIFNULL bit of P5 is set and either reg(P1) or
reg(P3) is NULL then take the jump.  If the SQLITE_JUMPIFNULL
bit is clear then fall thru if either operand is NULL.</p>

<p>If the SQLITE_NULLEQUAL bit of P5 is set then treat NULL operands
as being equal to one another.  Normally NULLs are not equal to
anything including other NULLs.</p>

<p>The SQLITE_AFF_MASK portion of P5 must be an affinity character -
SQLITE_AFF_TEXT, SQLITE_AFF_INTEGER, and so forth. An attempt is made
to coerce both inputs according to this affinity before the
comparison is made. If the SQLITE_AFF_MASK is 0x00, then numeric
affinity is used. Note that the affinity conversions are stored
back into the input registers P1 and P3.  So this opcode can cause
persistent changes to registers P1 and P3.</p>

<p>Once any conversions have taken place, and neither value is NULL,
the values are compared. If both values are blobs then memcmp() is
used to determine the results of the comparison.  If both values
are text, then the appropriate collating function specified in
P4 is  used to do the comparison.  If P4 is not specified then
memcmp() is used to compare text string.  If both values are
numeric, then a numeric comparison is used. If the two values
are of different types, then numbers are considered less than
strings and strings are considered less than blobs.</p>

<p>If the SQLITE_STOREP2 bit of P5 is set, then do not jump.  Instead,
store a boolean result (either 0, or 1, or NULL) in register P2.</td></tr>
<tr><td valign="top" align="center">