1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
3
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
4
<title>SQLite Virtual Machine Opcodes</title>
5
<style type="text/css">
8
font-family: Verdana, sans-serif;
13
a:visited { color: #734559 }
15
.logo { position:absolute; margin:3px; }
31
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
32
.toolbar a:visited { color: white; }
33
.toolbar a:hover { color: #044a64; background: white; }
35
.content { margin: 5%; }
36
.content dt { font-weight:bold; }
37
.content dd { margin-bottom: 25px; margin-left:20%; }
38
.content ul { padding:0px; padding-left: 15px; margin:0px; }
41
.se { background: url(images/se.gif) 100% 100% no-repeat #044a64}
42
.sw { background: url(images/sw.gif) 0% 100% no-repeat }
43
.ne { background: url(images/ne.gif) 100% 0% no-repeat }
44
.nw { background: url(images/nw.gif) 0% 0% no-repeat }
46
/* Things for "fancyformat" documents start here. */
47
.fancy img+p {font-style:italic}
48
.fancy .codeblock i { color: darkblue; }
49
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
50
.fancy h2 { margin-left: 10px }
51
.fancy h3 { margin-left: 20px }
52
.fancy h4 { margin-left: 30px }
53
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
54
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
55
.fancy #toc a { color: darkblue ; text-decoration: none }
56
.fancy .todo { color: #AA3333 ; font-style : italic }
57
.fancy .todo:before { content: 'TODO:' }
58
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
59
.fancy img { display:block; }
60
.fancy :link:hover, .fancy :visited:hover { background: wheat }
61
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
62
.fancy li p { margin: 1em 0 }
63
/* End of "fancyformat" specific rules. */
69
<div><!-- container div to satisfy validator -->
72
<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite Logo"
74
<div><!-- IE hack to prevent disappearing logo--></div>
75
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
77
<table width=100% style="clear:both"><tr><td>
78
<div class="se"><div class="sw"><div class="ne"><div class="nw">
79
<table width=100% style="padding:0;margin:0;cell-spacing:0"><tr>
82
<a href="about.html">About</a>
83
<a href="sitemap.html">Sitemap</a>
84
<a href="docs.html">Documentation</a>
85
<a href="download.html">Download</a>
86
<a href="copyright.html">License</a>
87
<a href="news.html">News</a>
88
<a href="support.html">Support</a>
91
gMsg = "Search SQLite Docs..."
92
function entersearch() {
93
var q = document.getElementById("q");
94
if( q.value == gMsg ) { q.value = "" }
95
q.style.color = "black"
96
q.style.fontStyle = "normal"
98
function leavesearch() {
99
var q = document.getElementById("q");
100
if( q.value == "" ) {
102
q.style.color = "#044a64"
103
q.style.fontStyle = "italic"
108
<div style="padding:0 1em 0px 0;white-space:nowrap">
109
<form name=f method="GET" action="http://www.sqlite.org/search">
110
<input id=q name=q type=text
111
onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
112
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
116
</div></div></div></div>
118
<div class=startsearch></div>
123
<h2>SQLite Virtual Machine Opcodes</h2>
127
<h3>Introduction</h3>
129
<p>In order to execute an SQL statement, the SQLite library first parses
130
the SQL, analyzes the statement, then generates a short program to execute
131
the statement. The program is generated for a "virtual machine" implemented
132
by the SQLite library. This document describes the operation of that
135
<p>This document is intended as a reference, not a tutorial.
136
A separate <a href="vdbe.html">Virtual Machine Tutorial</a> is
137
available. If you are looking for a narrative description
138
of how the virtual machine works, you should read the tutorial
139
and not this document. Once you have a basic idea of what the
140
virtual machine does, you can refer back to this document for
141
the details on a particular opcode.
142
Unfortunately, the virtual machine tutorial was written for
143
SQLite version 1.0. There are substantial changes in the virtual
144
machine for version 2.0 and again for version 3.0.0 and again
145
for version 3.5.5 and the document has not been updated. But the
146
basic concepts behind the virtual machine still apply.
149
<p>The source code to the virtual machine is in the <b>vdbe.c</b> source
150
file. All of the opcode definitions further down in this document are
151
contained in comments in the source file. In fact, the opcode table
153
was generated by scanning the <b>vdbe.c</b> source file
154
and extracting the necessary information from comments. So the
155
source code comments are really the canonical source of information
156
about the virtual machine. When in doubt, refer to the source code.</p>
158
<p>Each instruction in the virtual machine consists of an opcode and
159
up to five operands named P1, P2 P3, P4, and P5. P1, P2, and P3
160
are 32-bit signed integers. These operands often refer to registers.
162
jump destination in any operation that might cause a jump.
163
P4 may be a 32-bit signed integer, a 64-bit signed integer, a
164
64-bit floating point value, a string literal, a Blob literal,
165
a pointer to a collating sequence comparison function, or a
166
pointer to the implementation of an application-defined SQL
167
function, or various other things. P5 is an unsigned character
168
normally used as a flag.
169
Some operators use all five operands. Some use
170
one or two. Some operators use none of the operands.<p>
172
<p>The virtual machine begins execution on instruction number 0.
173
Execution continues until a Halt instruction is seen, or
174
the program counter becomes one greater than the address of
175
last instruction, or there is an execution error.
176
When the virtual machine halts, all memory
177
that it allocated is released and all database cursors it may
178
have had open are closed. If the execution stopped due to an
179
error, any pending transactions are terminated and changes made
180
to the database are rolled back.</p>
182
<p>The virtual machine can have zero or more cursors. Each cursor
183
is a pointer into a single table or index within the database.
184
There can be multiple cursors pointing at the same index or table.
185
All cursors operate independently, even cursors pointing to the same
187
The only way for the virtual machine to interact with a database
188
file is through a cursor.
189
Instructions in the virtual
190
machine can create a new cursor (OpenRead or OpenWrite),
191
read data from a cursor
192
(Column), advance the cursor to the next entry in the table
193
(Next) or index (NextIdx), and many other operations.
194
All cursors are automatically
195
closed when the virtual machine terminates.</p>
197
<p>The virtual machine contains an arbitrary number of registers
198
locations with addresses beginning at one and growing upward.
199
Each memory location can hold an arbitrary string. The registers
200
hold all intermediate results of a calculation.</p>
202
<h3>Viewing Programs Generated By SQLite</h3>
204
<p>Every SQL statement that SQLite interprets results in a program
205
for the virtual machine. But if you precede the SQL statement with
206
the keyword <a href="lang_explain.html">EXPLAIN</a> the virtual machine will not execute the
207
program. Instead, the instructions of the program will be returned
208
like a query result. This feature is useful for debugging and
209
for learning how the virtual machine operates.</p>
211
<p>You can use the <b>sqlite3.exe</b> command-line interface (CLI)
213
instructions generated by an SQL statement. The following is
216
<blockquote><tt>$ <b>sqlite3 ex1.db</b><br>
217
sqlite> <b>.explain</b><br>
218
sqlite> <b>explain delete from tbl1 where two<20;</b><br>
219
addr opcode p1 p2 p3 p4 p5 comment<br>
220
---- ------------- ---- ---- ---- --------- -- -------<br>
221
0 Trace 0 0 0 explain.. 00 <br>
222
1 Goto 0 20 0 00 <br>
223
2 OpenRead 0 2 0 00 tbl <br>
224
3 SetNumColumns 0 2 0 00 <br>
225
4 Rewind 0 11 0 00 <br>
226
5 Column 0 1 2 00 tbl.two<br>
227
6 Integer 20 3 0 00 <br>
228
7 Ge 3 10 2 cs(BINARY) 6a <br>
229
8 Rowid 0 1 0 00 <br>
230
9 FifoWrite 1 0 0 00 <br>
231
10 Next 0 5 0 00 <br>
232
11 Close 0 0 0 00 <br>
233
12 OpenWrite 0 2 0 00 tbl <br>
234
13 SetNumColumns 0 2 0 00 <br>
235
14 FifoRead 1 18 0 00 <br>
236
15 NotExists 0 17 1 00 <br>
237
16 Delete 0 1 0 tbl 00 <br>
238
17 Goto 0 14 0 00 <br>
239
18 Close 0 0 0 00 <br>
240
19 Halt 0 0 0 00 <br>
241
20 Transaction 0 1 0 00 <br>
242
21 VerifyCookie 0 1 0 00 <br>
243
22 TableLock -1 2 0 tbl 00 <br>
244
23 Goto 0 2 0 00</tt></blockquote>
246
<p>All you have to do is add the <a href="lang_explain.html">EXPLAIN</a> keyword to the front of the
247
SQL statement. But if you use the ".explain" command in the CLI,
248
it will set up the output mode to make the program more easily
251
<p>Depending on compile-time options, you
252
can put the SQLite virtual machine in a mode where it will trace its
253
execution by writing messages to standard output. The non-standard
254
SQL "PRAGMA" comments can be used to turn tracing on and off. To
255
turn tracing on, enter:
259
PRAGMA vdbe_trace=on;
263
You can turn tracing back off by entering a similar statement but
264
changing the value "on" to "off".</p>
268
<p>There are currently 146
269
opcodes defined by the virtual machine.
270
All currently defined opcodes are described in the table below.
271
This table was generated automatically by scanning the source code
272
from the file <b>vdbe.c</b>.</p>
274
<p><table cellspacing="1" border="1" cellpadding="10">
275
<tr><th>Opcode Name</th><th>Description</th></tr>
277
<tr><td valign="top" align="center"><a name="Add"></a><p>Add</p><td><p>Add the value in register P1 to the value in register P2
278
and store the result in register P3.
279
If either input is NULL, the result is NULL.</td></tr><tr><td valign="top" align="center"><a name="AddImm"></a><p>AddImm</p><td><p>Add the constant P2 to the value in register P1.
280
The result is always an integer.</p>
282
<p>To force any register to be an integer, just add 0.</td></tr><tr><td valign="top" align="center"><a name="Affinity"></a><p>Affinity</p><td><p>Apply affinities to a range of P2 registers starting with P1.</p>
284
<p>P4 is a string that is P2 characters long. The nth character of the
285
string indicates the column affinity that should be used for the nth
286
memory cell in the range.</td></tr><tr><td valign="top" align="center"><a name="AggFinal"></a><p>AggFinal</p><td><p>Execute the finalizer function for an aggregate. P1 is
287
the memory location that is the accumulator for the aggregate.</p>
289
<p>P2 is the number of arguments that the step function takes and
290
P4 is a pointer to the FuncDef for this function. The P2
291
argument is not used by this opcode. It is only there to disambiguate
292
functions that can take varying numbers of arguments. The
293
P4 argument is only needed for the degenerate case where
294
the step function was not previously called.</td></tr><tr><td valign="top" align="center"><a name="AggStep"></a><p>AggStep</p><td><p>Execute the step function for an aggregate. The
295
function has P5 arguments. P4 is a pointer to the FuncDef
296
structure that specifies the function. Use register
297
P3 as the accumulator.</p>
299
<p>The P5 arguments are taken from register P2 and its
300
successors.</td></tr><tr><td valign="top" align="center"><a name="And"></a><p>And</p><td><p>Take the logical AND of the values in registers P1 and P2 and
301
write the result into register P3.</p>
303
<p>If either P1 or P2 is 0 (false) then the result is 0 even if
304
the other input is NULL. A NULL and true or two NULLs give
305
a NULL output.</td></tr><tr><td valign="top" align="center"><a name="AutoCommit"></a><p>AutoCommit</p><td><p>Set the database auto-commit flag to P1 (1 or 0). If P2 is true, roll
306
back any currently active btree transactions. If there are any active
307
VMs (apart from this one), then a ROLLBACK fails. A COMMIT fails if
308
there are active writing VMs or active VMs that use shared cache.</p>
310
<p>This instruction causes the VM to halt.</td></tr><tr><td valign="top" align="center"><a name="BitAnd"></a><p>BitAnd</p><td><p>Take the bit-wise AND of the values in register P1 and P2 and
311
store the result in register P3.
312
If either input is NULL, the result is NULL.</td></tr><tr><td valign="top" align="center"><a name="BitNot"></a><p>BitNot</p><td><p>Interpret the content of register P1 as an integer. Store the
313
ones-complement of the P1 value into register P2. If P1 holds
314
a NULL then store a NULL in P2.</td></tr><tr><td valign="top" align="center"><a name="BitOr"></a><p>BitOr</p><td><p>Take the bit-wise OR of the values in register P1 and P2 and
315
store the result in register P3.
316
If either input is NULL, the result is NULL.</td></tr><tr><td valign="top" align="center"><a name="Blob"></a><p>Blob</p><td><p>P4 points to a blob of data P1 bytes long. Store this
317
blob in register P2.</td></tr><tr><td valign="top" align="center"><a name="Checkpoint"></a><p>Checkpoint</p><td><p>Checkpoint database P1. This is a no-op if P1 is not currently in
318
WAL mode. Parameter P2 is one of SQLITE_CHECKPOINT_PASSIVE, FULL
319
or RESTART. Write 1 or 0 into mem[P3] if the checkpoint returns
320
SQLITE_BUSY or not, respectively. Write the number of pages in the
321
WAL after the checkpoint into mem[P3+1] and the number of pages
322
in the WAL that have been checkpointed after the checkpoint
323
completes into mem[P3+2]. However on an error, mem[P3+1] and
324
mem[P3+2] are initialized to -1.</td></tr><tr><td valign="top" align="center"><a name="Clear"></a><p>Clear</p><td><p>Delete all contents of the database table or index whose root page
325
in the database file is given by P1. But, unlike Destroy, do not
326
remove the table or index from the database file.</p>
328
<p>The table being clear is in the main database file if P2==0. If
329
P2==1 then the table to be clear is in the auxiliary database file
330
that is used to store tables create using CREATE TEMPORARY TABLE.</p>
332
<p>If the P3 value is non-zero, then the table referred to must be an
333
intkey table (an SQL table, not an index). In this case the row change
334
count is incremented by the number of rows in the table being cleared.
335
If P3 is greater than zero, then the value stored in register P3 is
336
also incremented by the number of rows in the table being cleared.</p>
338
<p>See also: Destroy</td></tr><tr><td valign="top" align="center"><a name="Close"></a><p>Close</p><td><p>Close a cursor previously opened as P1. If P1 is not
339
currently open, this instruction is a no-op.</td></tr><tr><td valign="top" align="center"><a name="CollSeq"></a><p>CollSeq</p><td><p>P4 is a pointer to a CollSeq struct. If the next call to a user function
340
or aggregate calls sqlite3GetFuncCollSeq(), this collation sequence will
341
be returned. This is used by the built-in min(), max() and nullif()
344
<p>If P1 is not zero, then it is a register that a subsequent min() or
345
max() aggregate will set to 1 if the current row is not the minimum or
346
maximum. The P1 register is initialized to 0 by this instruction.</p>
348
<p>The interface used by the implementation of the aforementioned functions
349
to retrieve the collation sequence set by this opcode is not available
350
publicly, only to user functions defined in func.c.</td></tr><tr><td valign="top" align="center"><a name="Column"></a><p>Column</p><td><p>Interpret the data that cursor P1 points to as a structure built using
351
the MakeRecord instruction. (See the MakeRecord opcode for additional
352
information about the format of the data.) Extract the P2-th column
353
from this record. If there are less that (P2+1)
354
values in the record, extract a NULL.</p>
356
<p>The value extracted is stored in register P3.</p>
358
<p>If the column contains fewer than P2 fields, then extract a NULL. Or,
359
if the P4 argument is a P4_MEM use the value of the P4 argument as
362
<p>If the OPFLAG_CLEARCACHE bit is set on P5 and P1 is a pseudo-table cursor,
363
then the cache of the cursor is reset prior to extracting the column.
364
The first OP_Column against a pseudo-table after the value of the content
365
register has changed should have this bit set.</p>
367
<p>If the OPFLAG_LENGTHARG and OPFLAG_TYPEOFARG bits are set on P5 when
368
the result is guaranteed to only be used as the argument of a length()
369
or typeof() function, respectively. The loading of large blobs can be
370
skipped for length() and all content loading can be skipped for typeof().</td></tr><tr><td valign="top" align="center"><a name="Compare"></a><p>Compare</p><td><p>Compare two vectors of registers in reg(P1)..reg(P1+P3-1) (call this
371
vector "A") and in reg(P2)..reg(P2+P3-1) ("B"). Save the result of
372
the comparison for use by the next OP_Jump instruct.</p>
374
<p>P4 is a KeyInfo structure that defines collating sequences and sort
375
orders for the comparison. The permutation applies to registers
376
only. The KeyInfo elements are used sequentially.</p>
378
<p>The comparison is a sort comparison, so NULLs compare equal,
379
NULLs are less than numbers, numbers are less than strings,
380
and strings are less than blobs.</td></tr><tr><td valign="top" align="center"><a name="Concat"></a><p>Concat</p><td><p>Add the text in register P1 onto the end of the text in
381
register P2 and store the result in register P3.
382
If either the P1 or P2 text are NULL then store NULL in P3.</p>
386
<p>It is illegal for P1 and P3 to be the same register. Sometimes,
387
if P3 is the same register as P2, the implementation is able
388
to avoid a memcpy().</td></tr><tr><td valign="top" align="center"><a name="Copy"></a><p>Copy</p><td><p>Make a copy of register P1 into register P2.</p>
390
<p>This instruction makes a deep copy of the value. A duplicate
391
is made of any string or blob constant. See also OP_SCopy.</td></tr><tr><td valign="top" align="center"><a name="Count"></a><p>Count</p><td><p>Store the number of entries (an integer value) in the table or index
392
opened by cursor P1 in register P2</td></tr><tr><td valign="top" align="center"><a name="CreateIndex"></a><p>CreateIndex</p><td><p>Allocate a new index in the main database file if P1==0 or in the
393
auxiliary database file if P1==1 or in an attached database if
394
P1>1. Write the root page number of the new table into
397
<p>See documentation on OP_CreateTable for additional information.</td></tr><tr><td valign="top" align="center"><a name="CreateTable"></a><p>CreateTable</p><td><p>Allocate a new table in the main database file if P1==0 or in the
398
auxiliary database file if P1==1 or in an attached database if
399
P1>1. Write the root page number of the new table into
402
<p>The difference between a table and an index is this: A table must
403
have a 4-byte integer key and can have arbitrary data. An index
404
has an arbitrary key but no data.</p>
406
<p>See also: CreateIndex</td></tr><tr><td valign="top" align="center"><a name="Delete"></a><p>Delete</p><td><p>Delete the record at which the P1 cursor is currently pointing.</p>
408
<p>The cursor will be left pointing at either the next or the previous
409
record in the table. If it is left pointing at the next record, then
410
the next Next instruction will be a no-op. Hence it is OK to delete
411
a record from within an Next loop.</p>
413
<p>If the OPFLAG_NCHANGE flag of P2 is set, then the row change count is
414
incremented (otherwise not).</p>
416
<p>P1 must not be pseudo-table. It has to be a real table with
419
<p>If P4 is not NULL, then it is the name of the table that P1 is
420
pointing to. The update hook will be invoked, if it exists.
421
If P4 is not NULL then the P1 cursor must have been positioned
422
using OP_NotFound prior to invoking this opcode.</td></tr><tr><td valign="top" align="center"><a name="Destroy"></a><p>Destroy</p><td><p>Delete an entire database table or index whose root page in the database
423
file is given by P1.</p>
425
<p>The table being destroyed is in the main database file if P3==0. If
426
P3==1 then the table to be clear is in the auxiliary database file
427
that is used to store tables create using CREATE TEMPORARY TABLE.</p>
429
<p>If AUTOVACUUM is enabled then it is possible that another root page
430
might be moved into the newly deleted root page in order to keep all
431
root pages contiguous at the beginning of the database. The former
432
value of the root page that moved - its value before the move occurred -
433
is stored in register P2. If no page
434
movement was required (because the table being dropped was already
435
the last one in the database) then a zero is stored in register P2.
436
If AUTOVACUUM is disabled then a zero is stored in register P2.</p>
438
<p>See also: Clear</td></tr><tr><td valign="top" align="center"><a name="Divide"></a><p>Divide</p><td><p>Divide the value in register P1 by the value in register P2
439
and store the result in register P3 (P3=P2/P1). If the value in
440
register P1 is zero, then the result is NULL. If either input is
441
NULL, the result is NULL.</td></tr><tr><td valign="top" align="center"><a name="DropIndex"></a><p>DropIndex</p><td><p>Remove the internal (in-memory) data structures that describe
442
the index named P4 in database P1. This is called after an index
443
is dropped in order to keep the internal representation of the
444
schema consistent with what is on disk.</td></tr><tr><td valign="top" align="center"><a name="DropTable"></a><p>DropTable</p><td><p>Remove the internal (in-memory) data structures that describe
445
the table named P4 in database P1. This is called after a table
446
is dropped in order to keep the internal representation of the
447
schema consistent with what is on disk.</td></tr><tr><td valign="top" align="center"><a name="DropTrigger"></a><p>DropTrigger</p><td><p>Remove the internal (in-memory) data structures that describe
448
the trigger named P4 in database P1. This is called after a trigger
449
is dropped in order to keep the internal representation of the
450
schema consistent with what is on disk.</td></tr><tr><td valign="top" align="center"><a name="Eq"></a><p>Eq</p><td><p>This works just like the Lt opcode except that the jump is taken if
451
the operands in registers P1 and P3 are equal.
452
See the Lt opcode for additional information.</p>
454
<p>If SQLITE_NULLEQ is set in P5 then the result of comparison is always either
455
true or false and is never NULL. If both operands are NULL then the result
456
of comparison is true. If either operand is NULL then the result is false.
457
If neither operand is NULL the result is the same as it would be if
458
the SQLITE_NULLEQ flag were omitted from P5.</td></tr><tr><td valign="top" align="center"><a name="Expire"></a><p>Expire</p><td><p>Cause precompiled statements to become expired. An expired statement
459
fails with an error code of SQLITE_SCHEMA if it is ever executed
460
(via sqlite3_step()).</p>
462
<p>If P1 is 0, then all SQL statements become expired. If P1 is non-zero,
463
then only the currently executing statement is affected.</td></tr><tr><td valign="top" align="center"><a name="FkCounter"></a><p>FkCounter</p><td><p>Increment a "constraint counter" by P2 (P2 may be negative or positive).
464
If P1 is non-zero, the database constraint counter is incremented
465
(deferred foreign key constraints). Otherwise, if P1 is zero, the
466
statement counter is incremented (immediate foreign key constraints).</td></tr><tr><td valign="top" align="center"><a name="FkIfZero"></a><p>FkIfZero</p><td><p>This opcode tests if a foreign key constraint-counter is currently zero.
467
If so, jump to instruction P2. Otherwise, fall through to the next
470
<p>If P1 is non-zero, then the jump is taken if the database constraint-counter
471
is zero (the one that counts deferred constraint violations). If P1 is
472
zero, the jump is taken if the statement constraint-counter is zero
473
(immediate foreign key constraint violations).</td></tr><tr><td valign="top" align="center"><a name="Found"></a><p>Found</p><td><p>If P4==0 then register P3 holds a blob constructed by MakeRecord. If
474
P4>0 then register P3 is the first of P4 registers that form an unpacked
477
<p>Cursor P1 is on an index btree. If the record identified by P3 and P4
478
is a prefix of any entry in P1 then a jump is made to P2 and
479
P1 is left pointing at the matching entry.</td></tr><tr><td valign="top" align="center"><a name="Function"></a><p>Function</p><td><p>Invoke a user function (P4 is a pointer to a Function structure that
480
defines the function) with P5 arguments taken from register P2 and
481
successors. The result of the function is stored in register P3.
482
Register P3 must not be one of the function inputs.</p>
484
<p>P1 is a 32-bit bitmask indicating whether or not each argument to the
485
function was determined to be constant at compile time. If the first
486
argument was constant then bit 0 of P1 is set. This is used to determine
487
whether meta data associated with a user function argument using the
488
sqlite3_set_auxdata() API may be safely retained until the next
489
invocation of this opcode.</p>
491
<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
492
the content of register P3 is greater than or equal to the content of
493
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>Write the current address onto register P1
494
and then jump to address P2.</td></tr><tr><td valign="top" align="center"><a name="Goto"></a><p>Goto</p><td><p>An unconditional jump to address P2.
495
The next instruction executed will be
496
the one at index P2 from the beginning of
497
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
498
the content of register P3 is greater than the content of
499
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, etc are closed
502
<p>P1 is the result code returned by sqlite3_exec(), sqlite3_reset(),
503
or sqlite3_finalize(). For a normal halt, this should be SQLITE_OK (0).
504
For errors, it can be some other value. If P1!=0 then P2 will determine
505
whether or not to rollback the current transaction. Do not rollback
506
if P2==OE_Fail. Do the rollback if P2==OE_Rollback. If P2==OE_Abort,
507
then back out all changes that have occurred during this execution of the
508
VDBE, but do not rollback the transaction.</p>
510
<p>If P4 is not null then it is an error message string.</p>
512
<p>There is an implied "Halt 0 0 0" instruction inserted at the very end of
513
every program. So a jump past the last instruction of the program
514
is the same as executing Halt.</td></tr><tr><td valign="top" align="center"><a name="HaltIfNull"></a><p>HaltIfNull</p><td><p>Check the value in register P3. If it is NULL then Halt using
515
parameter P1, P2, and P4 as if this were a Halt instruction. If the
516
value in register P3 is not NULL, then this routine is a no-op.</td></tr><tr><td valign="top" align="center"><a name="IdxDelete"></a><p>IdxDelete</p><td><p>The content of P3 registers starting at register P2 form
517
an unpacked index key. This opcode removes that entry from the
518
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
519
key that omits the ROWID. Compare this key value against the index
520
that P1 is currently pointing to, ignoring the ROWID on the P1 index.</p>
522
<p>If the P1 index entry is greater than or equal to the key value
523
then jump to P2. Otherwise fall through to the next instruction.</p>
525
<p>If P5 is non-zero then the key value is increased by an epsilon
526
prior to the comparison. This make the opcode work like IdxGT except
527
that if the key from register P3 is a prefix of the key in the cursor,
528
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 an SQL index key made using the
529
MakeRecord instructions. This opcode writes that key
530
into the index P1. Data for the entry is nil.</p>
532
<p>P3 is a flag that provides a hint to the b-tree layer that this
533
insert is likely to be an append.</p>
535
<p>This instruction only works for indices. The equivalent instruction
536
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
537
key that omits the ROWID. Compare this key value against the index
538
that P1 is currently pointing to, ignoring the ROWID on the P1 index.</p>
540
<p>If the P1 index entry is less than the key value then jump to P2.
541
Otherwise fall through to the next instruction.</p>
543
<p>If P5 is non-zero then the key value is increased by an epsilon prior
544
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
545
the end of the index key pointed to by cursor P1. This integer should be
546
the rowid of the table entry to which this index entry points.</p>
548
<p>See also: Rowid, MakeRecord.</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
549
is considered true if it is numeric and non-zero. If the value
550
in P1 is NULL then take the jump if P3 is non-zero.</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>
552
<p>It is illegal to use this instruction on a register that does
553
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
554
is considered false if it has a numeric value of zero. If the value
555
in P1 is NULL then take the jump if P3 is zero.</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>
557
<p>It is illegal to use this instruction on a register that does
558
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>The register P1 must contain an integer. Add literal P3 to the
559
value in register P1. If the result is exactly 0, jump to P2.</p>
561
<p>It is illegal to use this instruction on a register that does
562
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
563
the P1 database. If the vacuum has finished, jump to instruction
564
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
565
created if it doesn't already exist or the data for an existing
566
entry is overwritten. The data is the value MEM_Blob stored in register
567
number P2. The key is stored in register P3. The key must
570
<p>If the OPFLAG_NCHANGE flag of P5 is set, then the row change count is
571
incremented (otherwise not). If the OPFLAG_LASTROWID flag of P5 is set,
572
then rowid is stored for subsequent return by the
573
sqlite3_last_insert_rowid() function (otherwise it is unmodified).</p>
575
<p>If the OPFLAG_USESEEKRESULT flag of P5 is set and if the result of
576
the last seek operation (OP_NotExists) was a success, then this
577
operation will not attempt to find the appropriate row before doing
578
the insert but will instead overwrite the row that the cursor is
579
currently pointing to. Presumably, the prior OP_NotExists opcode
580
has already positioned the cursor correctly. This is an optimization
581
that boosts performance by avoiding redundant seeks.</p>
583
<p>If the OPFLAG_ISUPDATE flag is set, then this opcode is part of an
584
UPDATE operation. Otherwise (if the flag is clear) then this opcode
585
is part of an INSERT operation. The difference is only important to
588
<p>Parameter P4 may point to a string containing the table-name, or
589
may be NULL. If it is not NULL, then the update-hook
590
(sqlite3.xUpdateCallback) is invoked following a successful insert.</p>
592
<p>(WARNING/TODO: If P1 is a pseudo-cursor and P2 is dynamically
593
allocated, then ownership of P2 is transferred to the pseudo-cursor
594
and register P2 becomes ephemeral. If the cursor is changed, the
595
value of register P2 will then change. Make sure this does not
596
cause any problems.)</p>
598
<p>This instruction only works on tables. The equivalent instruction
599
for indices is OP_IdxInsert.</td></tr><tr><td valign="top" align="center"><a name="InsertInt"></a><p>InsertInt</p><td><p>This works exactly like OP_Insert except that the key is the
600
integer value P3, not the value of the integer stored in register P3.</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.
601
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
602
register P1 the text of an error message describing any problems.
603
If no problems are found, store a NULL in register P1.</p>
605
<p>The register P3 contains the maximum number of allowed errors.
606
At most reg(P3) errors will be reported.
607
In other words, the analysis stops as soon as reg(P1) errors are
608
seen. Reg(P1) is updated with the number of errors remaining.</p>
610
<p>The root page numbers of all tables in the database are integer
611
stored in reg(P1), reg(P1+1), reg(P1+2), .... There are P2 tables
614
<p>If P5 is not zero, the check is done on the auxiliary database
615
file, not the main database file.</p>
617
<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.</td></tr><tr><td valign="top" align="center"><a name="IsUnique"></a><p>IsUnique</p><td><p>Cursor P1 is open on an index b-tree - that is to say, a btree which
618
no data and where the key are records generated by OP_MakeRecord with
619
the list field being the integer ROWID of the entry that the index
622
<p>The P3 register contains an integer record number. Call this record
623
number R. Register P4 is the first in a set of N contiguous registers
624
that make up an unpacked index key that can be used with cursor P1.
625
The value of N can be inferred from the cursor. N includes the rowid
626
value appended to the end of the index record. This rowid value may
627
or may not be the same as R.</p>
629
<p>If any of the N registers beginning with register P4 contains a NULL
630
value, jump immediately to P2.</p>
632
<p>Otherwise, this instruction checks if cursor P1 contains an entry
633
where the first (N-1) fields match but the rowid value at the end
634
of the index entry is not R. If there is no such entry, control jumps
635
to instruction P2. Otherwise, the rowid of the conflicting index
636
entry is copied to register P3 and control falls through to the next
639
<p>See also: NotFound, NotExists, Found</td></tr><tr><td valign="top" align="center"><a name="JournalMode"></a><p>JournalMode</p><td><p>Change the journal mode of database P1 to P3. P3 must be one of the
640
PAGER_JOURNALMODE_XXX values. If changing between the various rollback
641
modes (delete, truncate, persist, off and memory), this is a simple
642
operation. No IO is required.</p>
644
<p>If changing into or out of WAL mode the procedure is more complicated.</p>
646
<p>Write a string containing the final journal-mode to register P2.</td></tr><tr><td valign="top" align="center"><a name="Jump"></a><p>Jump</p><td><p>Jump to the instruction at address P1, P2, or P3 depending on whether
647
in the most recent OP_Compare instruction the P1 vector was less than
648
equal to, or greater than the P2 vector, respectively.</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
649
will refer to the last entry in the database table or index.
650
If the table or index is empty and P2>0, then jump immediately to P2.
651
If P2 is 0 or if the table or index is not empty, fall through
652
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
653
the content of register P3 is less than or equal to the content of
654
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
655
of that table into the internal index hash table. This will cause
656
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)<reg(P1) then
657
jump to address P2.</p>
659
<p>If the SQLITE_JUMPIFNULL bit of P5 is set and either reg(P1) or
660
reg(P3) is NULL then take the jump. If the SQLITE_JUMPIFNULL
661
bit is clear then fall through if either operand is NULL.</p>
663
<p>The SQLITE_AFF_MASK portion of P5 must be an affinity character -
664
SQLITE_AFF_TEXT, SQLITE_AFF_INTEGER, and so forth. An attempt is made
665
to coerce both inputs according to this affinity before the
666
comparison is made. If the SQLITE_AFF_MASK is 0x00, then numeric
667
affinity is used. Note that the affinity conversions are stored
668
back into the input registers P1 and P3. So this opcode can cause
669
persistent changes to registers P1 and P3.</p>
671
<p>Once any conversions have taken place, and neither value is NULL,
672
the values are compared. If both values are blobs then memcmp() is
673
used to determine the results of the comparison. If both values
674
are text, then the appropriate collating function specified in
675
P4 is used to do the comparison. If P4 is not specified then
676
memcmp() is used to compare text string. If both values are
677
numeric, then a numeric comparison is used. If the two values
678
are of different types, then numbers are considered less than
679
strings and strings are considered less than blobs.</p>
681
<p>If the SQLITE_STOREP2 bit of P5 is set, then do not jump. Instead,
682
store a boolean result (either 0, or 1, or NULL) in register P2.</td></tr><tr><td valign="top" align="center"><a name="MakeRecord"></a><p>MakeRecord</p><td><p>Convert P2 registers beginning with P1 into the <a href="fileformat2.html#record_format">record format</a>
683
use as a data record in a database table or as a key
684
in an index. The OP_Column opcode can decode the record later.</p>
686
<p>P4 may be a string that is P2 characters long. The nth character of the
687
string indicates the column affinity that should be used for the nth
688
field of the index key.</p>
690
<p>The mapping from character to affinity is given by the SQLITE_AFF_
691
macros defined in sqliteInt.h.</p>
693
<p>If P4 is NULL then all index fields have the affinity NONE.</td></tr><tr><td valign="top" align="center"><a name="MaxPgcnt"></a><p>MaxPgcnt</p><td><p>Try to set the maximum page count for database P1 to the value in P3.
694
Do not let the maximum page count fall below the current page count and
695
do not change the maximum page count value if P3==0.</p>
697
<p>Store the maximum page count after the change in register P2.</td></tr><tr><td valign="top" align="center"><a name="MemMax"></a><p>MemMax</p><td><p>P1 is a register in the root frame of this VM (the root frame is
698
different from the current frame if this instruction is being executed
699
within a sub-program). Set the value of register P1 to the maximum of
700
its current value and the value in register P2.</p>
702
<p>This instruction throws an error if the memory cell is not initially
703
an integer.</td></tr><tr><td valign="top" align="center"><a name="Move"></a><p>Move</p><td><p>Move the values in register P1..P1+P3-1 over into
704
registers P2..P2+P3-1. Registers P1..P1+P1-1 are
705
left holding a NULL. It is an error for register ranges
706
P1..P1+P3-1 and P2..P2+P3-1 to overlap.</td></tr><tr><td valign="top" align="center"><a name="Multiply"></a><p>Multiply</p><td><p>Multiply the value in register P1 by the value in register P2
707
and store the result in register P3.
708
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
709
in P1 is not an integer and cannot be converted into an integer
710
without data loss, then jump immediately to P2, or if P2==0
711
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
712
the operands in registers P1 and P3 are not equal. See the Lt opcode for
713
additional information.</p>
715
<p>If SQLITE_NULLEQ is set in P5 then the result of comparison is always either
716
true or false and is never NULL. If both operands are NULL then the result
717
of comparison is false. If either operand is NULL then the result is true.
718
If neither operand is NULL the result is the same as it would be if
719
the SQLITE_NULLEQ flag were omitted from P5.</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.
720
The record number is not previously used as a key in the database
721
table that cursor P1 points to. The new record number is written
722
written to register P2.</p>
724
<p>If P3>0 then P3 is a register in the root frame of this VDBE that holds
725
the largest previously generated record number. No new record numbers are
726
allowed to be less than this value. When this value reaches its maximum,
727
an SQLITE_FULL error is generated. The P3 register is updated with the '
728
generated record number. This P3 mechanism is used to help implement the
729
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
730
table or index. If there are no more key/value pairs then fall through
731
to the following instruction. But if the cursor advance was successful,
732
jump immediately to P2.</p>
734
<p>The P1 cursor must be for a real table, not a pseudo-table.</p>
736
<p>P4 is always of type P4_ADVANCE. The function pointer points to
737
sqlite3BtreeNext().</p>
739
<p>If P5 is positive and the jump is taken, then event counter
740
number P5-1 in the prepared statement is incremented.</p>
742
<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
743
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. Store the
744
boolean complement in register P2. If the value in register P1 is
745
NULL, then a NULL is stored in P2.</td></tr><tr><td valign="top" align="center"><a name="NotExists"></a><p>NotExists</p><td><p>Use the content of register P3 as an integer key. If a record
746
with that key does not exist in table of P1, then jump to P2.
747
If the record does exist, then fall through. The cursor is left
748
pointing to the record if it exists.</p>
750
<p>The difference between this operation and NotFound is that this
751
operation assumes the key is an integer and that P1 is a table whereas
752
NotFound assumes key is a blob constructed from MakeRecord and
755
<p>See also: Found, NotFound, IsUnique</td></tr><tr><td valign="top" align="center"><a name="NotFound"></a><p>NotFound</p><td><p>If P4==0 then register P3 holds a blob constructed by MakeRecord. If
756
P4>0 then register P3 is the first of P4 registers that form an unpacked
759
<p>Cursor P1 is on an index btree. If the record identified by P3 and P4
760
is not the prefix of any entry in P1 then a jump is made to P2. If P1
761
does contain an entry whose prefix matches the P3/P4 record then control
762
falls through to the next instruction and P1 is left pointing at the
765
<p>See also: Found, 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 registers P2. If P3 greater than P2, then also write
766
NULL into register P3 and ever register in between P2 and P3. If P3
767
is less than P2 (typically P3 is zero) then only register P2 is
768
set to NULL</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
769
that occur while the cursor is on the null row will always
770
write a NULL.</td></tr><tr><td valign="top" align="center"><a name="Once"></a><p>Once</p><td><p>Check if OP_Once flag P1 is set. If so, jump to instruction P2. Otherwise,
771
set the flag and fall through to the next instruction.</p>
773
<p>See also: JumpOnce</td></tr><tr><td valign="top" align="center"><a name="OpenAutoindex"></a><p>OpenAutoindex</p><td><p>This opcode works the same as OP_OpenEphemeral. It has a
774
different name to distinguish its use. Tables created using
775
by this opcode will be used for automatically created transient
776
indices in joins.</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.
777
The cursor is always opened read/write even if
778
the main database is read-only. The ephemeral
779
table is deleted automatically when the cursor is closed.</p>
781
<p>P2 is the number of columns in the ephemeral table.
782
The cursor points to a BTree table if P4==0 and to a BTree index
783
if P4 is not 0. If P4 is not NULL, it points to a KeyInfo structure
784
that defines the format of keys in the index.</p>
786
<p>This opcode was once called OpenTemp. But that created
787
confusion because the term "temp table", might refer either
788
to a TEMP table at the SQL level, or to a table opened by
789
this opcode. Then this opcode was call OpenVirtual. But
790
that created confusion with the whole virtual-table idea.</p>
792
<p>The P5 parameter can be a mask of the BTREE_* flags defined
793
in btree.h. These flags control aspects of the operation of
794
the btree. The BTREE_OMIT_JOURNAL and BTREE_SINGLE flags are
795
added automatically.</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
796
row of data. The content of that one row in the content of memory
797
register P2. In other words, cursor P1 becomes an alias for the
798
MEM_Blob content contained in register P2.</p>
800
<p>A pseudo-table created by this opcode is used to hold a single
801
row output from the sorter so that the row can be decomposed into
802
individual columns using the OP_Column opcode. The OP_Column opcode
803
is the only cursor opcode that works with a pseudo-table.</p>
805
<p>P3 is the number of fields in the records that will be stored by
806
the pseudo-table.</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
807
P2 in a database file. The database file is determined by P3.
808
P3==0 means the main database, P3==1 means the database used for
809
temporary tables, and P3>1 means used the corresponding attached
810
database. Give the new cursor an identifier of P1. The P1
811
values need not be contiguous but all P1 values should be small integers.
812
It is an error for P1 to be negative.</p>
814
<p>If P5!=0 then use the content of register P2 as the root page, not
815
the value of P2 itself.</p>
817
<p>There will be a read lock on the database whenever there is an
818
open cursor. If the database was unlocked prior to this instruction
819
then a read lock is acquired as part of this instruction. A read
820
lock allows other processes to read the database but prohibits
821
any other process from modifying the database. The read lock is
822
released when all cursors are closed. If this instruction attempts
823
to get a read lock but fails, the script terminates with an
824
SQLITE_BUSY error code.</p>
826
<p>The P4 value may be either an integer (P4_INT32) or a pointer to
827
a KeyInfo structure (P4_KEYINFO). If it is a pointer to a KeyInfo
828
structure, then said structure defines the content and collating
829
sequence of the index being opened. Otherwise, if P4 is an integer
830
value, it is set to the number of columns in the table.</p>
832
<p>See also OpenWrite.</td></tr><tr><td valign="top" align="center"><a name="OpenSorter"></a><p>OpenSorter</p><td><p>This opcode works like OP_OpenEphemeral except that it opens
833
a transient index that is specifically designed to sort large
834
tables using an external merge-sort algorithm.</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
835
page is P2. Or if P5!=0 use the content of register P2 to find the
838
<p>The P4 value may be either an integer (P4_INT32) or a pointer to
839
a KeyInfo structure (P4_KEYINFO). If it is a pointer to a KeyInfo
840
structure, then said structure defines the content and collating
841
sequence of the index being opened. Otherwise, if P4 is an integer
842
value, it is set to the number of columns in the table, or to the
843
largest index of any column of the table that is actually used.</p>
845
<p>This instruction works just like OpenRead except that it opens the cursor
846
in read/write mode. For a given table, there can be one or more read-only
847
cursors or a single read/write cursor but not both.</p>
849
<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
850
store the answer in register P3.</p>
852
<p>If either P1 or P2 is nonzero (true) then the result is 1 (true)
853
even if the other input is NULL. A NULL and false or two NULLs
854
give a NULL output.</td></tr><tr><td valign="top" align="center"><a name="Pagecount"></a><p>Pagecount</p><td><p>Write the current number of pages in database P1 to memory cell P2.</td></tr><tr><td valign="top" align="center"><a name="Param"></a><p>Param</p><td><p>This opcode is only ever present in sub-programs called via the
855
OP_Program instruction. Copy a value currently stored in a memory
856
cell of the calling (parent) frame to cell P2 in the current frames
857
address space. This is used by trigger programs to access the new.*
858
and old.* values.</p>
860
<p>The address of the cell in the parent frame is determined by adding
861
the value of the P1 argument to the value of the P1 argument to the
862
calling OP_Program instruction.</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
863
that match the WHERE clause P4.</p>
865
<p>This opcode invokes the parser to create a new virtual machine,
866
then runs the new virtual machine. It is thus a re-entrant opcode.</td></tr><tr><td valign="top" align="center"><a name="Permutation"></a><p>Permutation</p><td><p>Set the permutation used by the OP_Compare operator to be the array
867
of integers in P4.</p>
869
<p>The permutation is only valid until the next OP_Permutation, OP_Compare,
870
OP_Halt, or OP_ResultRow. Typically the OP_Permutation should occur
871
immediately prior to the OP_Compare.</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
872
table or index. If there is no previous key/value pairs then fall through
873
to the following instruction. But if the cursor backup was successful,
874
jump immediately to P2.</p>
876
<p>The P1 cursor must be for a real table, not a pseudo-table.</p>
878
<p>P4 is always of type P4_ADVANCE. The function pointer points to
879
sqlite3BtreePrevious().</p>
881
<p>If P5 is positive and the jump is taken, then event counter
882
number P5-1 in the prepared statement is incremented.</td></tr><tr><td valign="top" align="center"><a name="Program"></a><p>Program</p><td><p>Execute the trigger program passed as P4 (type P4_SUBPROGRAM).</p>
884
<p>P1 contains the address of the memory cell that contains the first memory
885
cell in an array of values used as arguments to the sub-program. P2
886
contains the address to jump to if the sub-program throws an IGNORE
887
exception using the RAISE() function. Register P3 contains the address
888
of a memory cell in this (the parent) VM that is used to allocate the
889
memory required by the sub-vdbe at runtime.</p>
891
<p>P4 is a pointer to the VM containing the trigger program.</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.
892
P3==1 is the schema version. P3==2 is the database format.
893
P3==3 is the recommended pager cache size, and so forth. P1==0 is
894
the main database file and P1==1 is the database file used to store
895
temporary tables.</p>
897
<p>There must be a read-lock on the database (either a transaction
898
must be started or there must be an open cursor) before
899
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.
900
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>
902
<p>This opcode is used when extracting information from a column that
903
has REAL affinity. Such column values may still be stored as
904
integers, for space efficiency, but after extraction we want them
905
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
906
register P1 by the value in register P2 and store the result in P3.
907
If the value in register P2 is zero the result is NULL.
908
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>The value of the change counter is copied to the database handle
909
change counter (returned by subsequent calls to sqlite3_changes()).
910
Then the VMs internal change counter resets to 0.
911
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
912
results. This opcode causes the sqlite3_step() call to terminate
913
with an SQLITE_ROW return code and it sets up the sqlite3_stmt
914
structure to provide access to the top P1 values as the result
915
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
916
will refer to the first entry in the database table or index.
917
If the table or index is empty and P2>0, then jump immediately to P2.
918
If P2 is 0 or if the table or index is not empty, fall through
919
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.
920
There is no interpretation of the data.
921
It is just copied onto the P2 register exactly as
922
it is found in the database file.</p>
924
<p>If the P1 cursor must be pointing to a valid row (not a NULL row)
925
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
926
P1 is currently point to.</p>
928
<p>P1 can be either an ordinary table or a virtual table. There used to
929
be a separate OP_VRowid opcode for use with virtual tables, but this
930
one opcode now works for both table types.</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.
931
There is no interpretation of the data.
932
The key is copied onto the P3 register exactly as
933
it is found in the database file.</p>
935
<p>If the P1 cursor must be pointing to a valid row (not a NULL row)
936
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
937
held in register P1.</p>
939
<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
940
register P3. Or, if boolean index P1 is initially empty, leave P3
941
unchanged and jump to instruction P2.</td></tr><tr><td valign="top" align="center"><a name="RowSetTest"></a><p>RowSetTest</p><td><p>Register P3 is assumed to hold a 64-bit integer value. If register P1
942
contains a RowSet object and that RowSet object contains
943
the value held in P3, jump to register P2. Otherwise, insert the
944
integer in P3 into the RowSet and continue on to the
947
<p>The RowSet object is optimized for the case where successive sets
948
of integers, where each set contains no duplicates. Each set
949
of values is identified by a unique P4 value. The first set
950
must have P4==0, the final set P4=-1. P4 must be either -1 or
951
non-negative. For non-negative values of P4 only the lower 4
952
bits are significant.</p>
954
<p>This allows optimizations: (a) when P4==0 there is no need to test
955
the rowset object for P3, as it is guaranteed not to contain it,
956
(b) when P4==-1 there is no need to insert the value, as it will
957
never be tested for, and (c) when a value that is part of set X is
958
inserted, there is no need to search to see if the same value was
959
previously inserted as part of set X (only if it was previously
960
inserted as part of some other set).</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
961
on the value of P1. To open a new savepoint, P1==0. To release (commit) an
962
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>
964
<p>This instruction makes a shallow copy of the value. If the value
965
is a string or blob, then the copy is only a pointer to the
966
original and hence if the original changes so will the copy.
967
Worse, if the original is deallocated, the copy becomes invalid.
968
Thus the program must guarantee that the original will not change
969
during the lifetime of the copy. Use OP_Copy to make a complete
970
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
971
for P1 to move so that it points to the rowid given by P2.</p>
973
<p>This is actually a deferred seek. Nothing actually happens until
974
the cursor is used to read a record. That way, if no reads
975
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),
976
use the value in register P3 as the key. If cursor P1 refers
977
to an SQL index, then P3 is the first in an array of P4 registers
978
that are used as an unpacked index key.</p>
980
<p>Reposition cursor P1 so that it points to the smallest entry that
981
is greater than or equal to the key value. If there are no records
982
greater than or equal to the key and P2 is not zero, then jump to P2.</p>
984
<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),
985
use the value in register P3 as a key. If cursor P1 refers
986
to an SQL index, then P3 is the first in an array of P4 registers
987
that are used as an unpacked index key.</p>
989
<p>Reposition cursor P1 so that it points to the smallest entry that
990
is greater than the key value. If there are no records greater than
991
the key and P2 is not zero, then jump to P2.</p>
993
<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),
994
use the value in register P3 as a key. If cursor P1 refers
995
to an SQL index, then P3 is the first in an array of P4 registers
996
that are used as an unpacked index key.</p>
998
<p>Reposition cursor P1 so that it points to the largest entry that
999
is less than or equal to the key value. If there are no records
1000
less than or equal to the key and P2 is not zero, then jump to P2.</p>
1002
<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),
1003
use the value in register P3 as a key. If cursor P1 refers
1004
to an SQL index, then P3 is the first in an array of P4 registers
1005
that are used as an unpacked index key.</p>
1007
<p>Reposition cursor P1 so that it points to the largest entry that
1008
is less than the key value. If there are no records less than
1009
the key and P2 is not zero, then jump to P2.</p>
1011
<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.
1012
Write the sequence number into register P2.
1013
The sequence number on the cursor is incremented after this
1014
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)
1015
into cookie number P2 of database P1. P2==1 is the schema version.
1016
P2==2 is the database format. P2==3 is the recommended pager cache
1017
size, and so forth. P1==0 is the main database file and P1==1 is the
1018
database file used to store temporary tables.</p>
1020
<p>A transaction must be started before executing this opcode.</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
1021
number of bits specified by the integer in register P1.
1022
Store the result in register P3.
1023
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
1024
number of bits specified by the integer in register P1.
1025
Store the result in register P3.
1026
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
1027
it increments an undocumented global variable used for testing.</p>
1029
<p>Sorting is accomplished by writing records into a sorting index,
1030
then rewinding that index and playing it back from beginning to
1031
end. We use the OP_Sort opcode instead of OP_Rewind to do the
1032
rewinding so that the global variable will be incremented and
1033
regression tests can determine whether or not the optimizer is
1034
correctly optimizing out sorts.</td></tr><tr><td valign="top" align="center"><a name="SorterCompare"></a><p>SorterCompare</p><td><p>P1 is a sorter cursor. This instruction compares the record blob in
1035
register P3 with the entry that the sorter cursor currently points to.
1036
If, excluding the rowid fields at the end, the two records are a match,
1037
fall through to the next instruction. Otherwise, jump to instruction P2.</td></tr><tr><td valign="top" align="center"><a name="SorterData"></a><p>SorterData</p><td><p>Write into register P2 the current sorter data for sorter cursor P1.</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
1038
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
1039
and store the result in register P3.
1040
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
1041
the shared-cache feature is enabled.</p>
1043
<p>P1 is the index of the database in sqlite3.aDb[] of the database
1044
on which the lock is acquired. A readlock is obtained if P3==0 or
1045
a write lock if P3==1.</p>
1047
<p>P2 contains the root-page of the table to lock.</p>
1049
<p>P4 contains a pointer to the name of the table being locked. This is only
1050
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.
1051
If the value is numeric, convert it to a string first.
1052
Strings are simply reinterpreted as blobs with no change
1053
to the underlying data.</p>
1055
<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 to be an integer. If
1056
The value is currently a real number, drop its fractional part.
1057
If the value is text or blob, try to convert it to an integer using the
1058
equivalent of atoi() and store 0 if no such conversion is possible.</p>
1060
<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
1061
integer or a floating-point number.)
1062
If the value is text or blob, try to convert it to an using the
1063
equivalent of atoi() or atof() and store 0 if no such conversion
1066
<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.
1067
If The value is currently an integer, convert it.
1068
If the value is text or blob, try to convert it to an integer using the
1069
equivalent of atoi() and store 0.0 if no such conversion is possible.</p>
1071
<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.
1072
If the value is numeric, convert it to a string using the
1073
equivalent of printf(). Blob values are unchanged and
1074
are afterwards simply interpreted as text.</p>
1076
<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
1077
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
1078
opcode is encountered. Depending on the ON CONFLICT setting, the
1079
transaction might also be rolled back if an error is encountered.</p>
1081
<p>P1 is the index of the database file on which the transaction is
1082
started. Index 0 is the main database file and index 1 is the
1083
file used for temporary tables. Indices of 2 or more are used for
1084
attached databases.</p>
1086
<p>If P2 is non-zero, then a write-transaction is started. A RESERVED lock is
1087
obtained on the database file when a write-transaction is started. No
1088
other process can start another write transaction while this transaction is
1089
underway. Starting a write transaction also creates a rollback journal. A
1090
write transaction must be started before any changes can be made to the
1091
database. If P2 is 2 or greater then an EXCLUSIVE lock is also obtained
1094
<p>If a write-transaction is started and the Vdbe.usesStmtJournal flag is
1095
true (this flag is set if the Vdbe may modify more than one row and may
1096
throw an ABORT exception), a statement transaction may also be opened.
1097
More specifically, a statement transaction is opened iff the database
1098
connection is currently not in autocommit mode, or if there are other
1099
active statements. A statement transaction allows the changes made by this
1100
VDBE to be rolled back after an error without having to roll back the
1101
entire transaction. If no error is encountered, the statement transaction
1102
will automatically commit when the VDBE halts.</p>
1104
<p>If P2 is zero, then a read-lock is obtained on the database file.</td></tr><tr><td valign="top" align="center"><a name="Vacuum"></a><p>Vacuum</p><td><p>Vacuum the entire database. This opcode will cause other virtual
1105
machines to be created and run. It may not be called from within
1106
a transaction.</td></tr><tr><td valign="top" align="center"><a name="Variable"></a><p>Variable</p><td><p>Transfer the values of bound parameter P1 into register P2</p>
1108
<p>If the parameter is named, then its name appears in P4 and P3==1.
1109
The P4 value is used by sqlite3_bind_parameter_name().</td></tr><tr><td valign="top" align="center"><a name="VBegin"></a><p>VBegin</p><td><p>P4 may be a pointer to an sqlite3_vtab structure. If so, call the
1110
xBegin method for that table.</p>
1112
<p>Also, whether or not P4 is set, check that this is not being called from
1113
within a callback to a virtual table xSync() method. If it is, the error
1114
code will be set to SQLITE_LOCKED.</td></tr><tr><td valign="top" align="center"><a name="VColumn"></a><p>VColumn</p><td><p>Store the value of the P2-th column of
1115
the row of the virtual-table that the
1116
P1 cursor is pointing to into register P3.</td></tr><tr><td valign="top" align="center"><a name="VCreate"></a><p>VCreate</p><td><p>P4 is the name of a virtual table in database P1. Call the xCreate method
1117
for that table.</td></tr><tr><td valign="top" align="center"><a name="VDestroy"></a><p>VDestroy</p><td><p>P4 is the name of a virtual table in database P1. Call the xDestroy method
1118
of that table.</td></tr><tr><td valign="top" align="center"><a name="VerifyCookie"></a><p>VerifyCookie</p><td><p>Check the value of global database parameter number 0 (the
1119
schema version) and make sure it is equal to P2 and that the
1120
generation counter on the local schema parse equals P3.</p>
1122
<p>P1 is the database number which is 0 for the main database file
1123
and 1 for the file holding temporary tables and some higher number
1124
for auxiliary databases.</p>
1126
<p>The cookie changes its value whenever the database schema changes.
1127
This operation is used to detect when that the cookie has changed
1128
and that the current process needs to reread the schema.</p>
1130
<p>Either a transaction needs to have been started or an OP_Open needs
1131
to be executed (to establish a read lock) before this opcode is
1132
invoked.</td></tr><tr><td valign="top" align="center"><a name="VFilter"></a><p>VFilter</p><td><p>P1 is a cursor opened using VOpen. P2 is an address to jump to if
1133
the filtered result set is empty.</p>
1135
<p>P4 is either NULL or a string that was generated by the xBestIndex
1136
method of the module. The interpretation of the P4 string is left
1137
to the module implementation.</p>
1139
<p>This opcode invokes the xFilter method on the virtual table specified
1140
by P1. The integer query plan parameter to xFilter is stored in register
1141
P3. Register P3+1 stores the argc parameter to be passed to the
1142
xFilter method. Registers P3+2..P3+1+argc are the argc
1143
additional parameters which are passed to
1144
xFilter as argv. Register P3+2 becomes argv[0] when passed to xFilter.</p>
1146
<p>A jump is made to P2 if the result set after filtering would be empty.</td></tr><tr><td valign="top" align="center"><a name="VNext"></a><p>VNext</p><td><p>Advance virtual table P1 to the next row in its result set and
1147
jump to instruction P2. Or, if the virtual table has reached
1148
the end of its result set, then fall through to the next instruction.</td></tr><tr><td valign="top" align="center"><a name="VOpen"></a><p>VOpen</p><td><p>P4 is a pointer to a virtual table object, an sqlite3_vtab structure.
1149
P1 is a cursor number. This opcode opens a cursor to the virtual
1150
table and stores that cursor in P1.</td></tr><tr><td valign="top" align="center"><a name="VRename"></a><p>VRename</p><td><p>P4 is a pointer to a virtual table object, an sqlite3_vtab structure.
1151
This opcode invokes the corresponding xRename method. The value
1152
in register P1 is passed as the zName argument to the xRename method.</td></tr><tr><td valign="top" align="center"><a name="VUpdate"></a><p>VUpdate</p><td><p>P4 is a pointer to a virtual table object, an sqlite3_vtab structure.
1153
This opcode invokes the corresponding xUpdate method. P2 values
1154
are contiguous memory cells starting at P3 to pass to the xUpdate
1155
invocation. The value in register (P3+P2-1) corresponds to the
1156
p2th element of the argv array passed to xUpdate.</p>
1158
<p>The xUpdate method will do a DELETE or an INSERT or both.
1159
The argv[0] element (which corresponds to memory cell P3)
1160
is the rowid of a row to delete. If argv[0] is NULL then no
1161
deletion occurs. The argv[1] element is the rowid of the new
1162
row. This can be NULL to have the virtual table select the new
1163
rowid for itself. The subsequent elements in the array are
1164
the values of columns in the new row.</p>
1166
<p>If P2==1 then no insert is performed. argv[0] is the rowid of
1167
a row to delete.</p>
1169
<p>P1 is a boolean flag. If it is set to true and the xUpdate call
1170
is successful, then the value returned by sqlite3_last_insert_rowid()
1171
is set to the value of the rowid for the row just inserted.</td></tr><tr><td valign="top" align="center"><a name="Yield"></a><p>Yield</p><td><p>Swap the program counter with the value in register P1.</td></tr>
added
removed
opcode.html
