| 1 |
<!DOCTYPE html> |
| 2 |
<html><head> |
| 3 |
<meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| 4 |
<meta http-equiv="content-type" content="text/html; charset=UTF-8"> |
| 5 |
<link href="sqlite.css" rel="stylesheet"> |
| 6 |
<title>The SQLite Bytecode Engine</title> |
| 7 |
<!-- path= --> |
| 8 |
</head> |
| 9 |
<body> |
| 10 |
<div class=nosearch> |
| 11 |
<a href="index.html"> |
| 12 |
<img class="logo" src="images/sqlite370_banner.svg" alt="SQLite" border="0"> |
| 13 |
</a> |
| 14 |
<div><!-- IE hack to prevent disappearing logo --></div> |
| 15 |
<div class="tagline desktoponly"> |
| 16 |
Small. Fast. Reliable.<br>Choose any three. |
| 17 |
</div> |
| 18 |
<div class="menu mainmenu"> |
| 19 |
<ul> |
| 20 |
<li><a href="index.html">Home</a> |
| 21 |
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a> |
| 22 |
<li class='wideonly'><a href='about.html'>About</a> |
| 23 |
<li class='desktoponly'><a href="docs.html">Documentation</a> |
| 24 |
<li class='desktoponly'><a href="download.html">Download</a> |
| 25 |
<li class='wideonly'><a href='copyright.html'>License</a> |
| 26 |
<li class='desktoponly'><a href="support.html">Support</a> |
| 27 |
<li class='desktoponly'><a href="prosupport.html">Purchase</a> |
| 28 |
<li class='search' id='search_menubutton'> |
| 29 |
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a> |
| 30 |
</ul> |
| 31 |
</div> |
| 32 |
<div class="menu submenu" id="submenu"> |
| 33 |
<ul> |
| 34 |
<li><a href='about.html'>About</a> |
| 35 |
<li><a href='docs.html'>Documentation</a> |
| 36 |
<li><a href='download.html'>Download</a> |
| 37 |
<li><a href='support.html'>Support</a> |
| 38 |
<li><a href='prosupport.html'>Purchase</a> |
| 39 |
</ul> |
| 40 |
</div> |
| 41 |
<div class="searchmenu" id="searchmenu"> |
| 42 |
<form method="GET" action="search"> |
| 43 |
<select name="s" id="searchtype"> |
| 44 |
<option value="d">Search Documentation</option> |
| 45 |
<option value="c">Search Changelog</option> |
| 46 |
</select> |
| 47 |
<input type="text" name="q" id="searchbox" value=""> |
| 48 |
<input type="submit" value="Go"> |
| 49 |
</form> |
| 50 |
</div> |
| 51 |
</div> |
| 52 |
<script> |
| 53 |
function toggle_div(nm) { |
| 54 |
var w = document.getElementById(nm); |
| 55 |
if( w.style.display=="block" ){ |
| 56 |
w.style.display = "none"; |
| 57 |
}else{ |
| 58 |
w.style.display = "block"; |
| 59 |
} |
| 60 |
} |
| 61 |
function toggle_search() { |
| 62 |
var w = document.getElementById("searchmenu"); |
| 63 |
if( w.style.display=="block" ){ |
| 64 |
w.style.display = "none"; |
| 65 |
} else { |
| 66 |
w.style.display = "block"; |
| 67 |
setTimeout(function(){ |
| 68 |
document.getElementById("searchbox").focus() |
| 69 |
}, 30); |
| 70 |
} |
| 71 |
} |
| 72 |
function div_off(nm){document.getElementById(nm).style.display="none";} |
| 73 |
window.onbeforeunload = function(e){div_off("submenu");} |
| 74 |
/* Disable the Search feature if we are not operating from CGI, since */ |
| 75 |
/* Search is accomplished using CGI and will not work without it. */ |
| 76 |
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){ |
| 77 |
document.getElementById("search_menubutton").style.display = "none"; |
| 78 |
} |
| 79 |
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */ |
| 80 |
function hideorshow(btn,obj){ |
| 81 |
var x = document.getElementById(obj); |
| 82 |
var b = document.getElementById(btn); |
| 83 |
if( x.style.display!='none' ){ |
| 84 |
x.style.display = 'none'; |
| 85 |
b.innerHTML='show'; |
| 86 |
}else{ |
| 87 |
x.style.display = ''; |
| 88 |
b.innerHTML='hide'; |
| 89 |
} |
| 90 |
return false; |
| 91 |
} |
| 92 |
var antiRobot = 0; |
| 93 |
function antiRobotGo(){ |
| 94 |
if( antiRobot!=3 ) return; |
| 95 |
antiRobot = 7; |
| 96 |
var j = document.getElementById("mtimelink"); |
| 97 |
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href"); |
| 98 |
} |
| 99 |
function antiRobotDefense(){ |
| 100 |
document.body.onmousedown=function(){ |
| 101 |
antiRobot |= 2; |
| 102 |
antiRobotGo(); |
| 103 |
document.body.onmousedown=null; |
| 104 |
} |
| 105 |
document.body.onmousemove=function(){ |
| 106 |
antiRobot |= 2; |
| 107 |
antiRobotGo(); |
| 108 |
document.body.onmousemove=null; |
| 109 |
} |
| 110 |
setTimeout(function(){ |
| 111 |
antiRobot |= 1; |
| 112 |
antiRobotGo(); |
| 113 |
}, 100) |
| 114 |
antiRobotGo(); |
| 115 |
} |
| 116 |
antiRobotDefense(); |
| 117 |
</script> |
| 118 |
<div class=fancy> |
| 119 |
<div class=nosearch> |
| 120 |
<div class="fancy_title"> |
| 121 |
The SQLite Bytecode Engine |
| 122 |
</div> |
| 123 |
<details class="fancy_toc"> |
| 124 |
<summary>Table Of Contents</summary> |
| 125 |
<div id="toc_sub"><div class="fancy-toc1"><a href="#executive_summary">1. Executive Summary</a></div> |
| 126 |
<div class="fancy-toc1"><a href="#introduction">2. Introduction</a></div> |
| 127 |
<div class="fancy-toc2"><a href="#vdbe_source_code">2.1. VDBE Source Code</a></div> |
| 128 |
<div class="fancy-toc2"><a href="#instruction_format">2.2. Instruction Format</a></div> |
| 129 |
<div class="fancy-toc2"><a href="#registers">2.3. Registers</a></div> |
| 130 |
<div class="fancy-toc2"><a href="#b_tree_cursors">2.4. B-Tree Cursors</a></div> |
| 131 |
<div class="fancy-toc2"><a href="#subroutines_coroutines_and_subprograms">2.5. Subroutines, Coroutines, and Subprograms</a></div> |
| 132 |
<div class="fancy-toc2"><a href="#self_altering_code">2.6. Self-Altering Code</a></div> |
| 133 |
<div class="fancy-toc1"><a href="#viewing_the_bytecode">3. Viewing The Bytecode</a></div> |
| 134 |
<div class="fancy-toc1"><a href="#the_opcodes">4. The Opcodes</a></div> |
| 135 |
</div> |
| 136 |
</details> |
| 137 |
</div> |
| 138 |
|
| 139 |
|
| 140 |
|
| 141 |
|
| 142 |
|
| 143 |
<h1 id="executive_summary"><span>1. </span>Executive Summary</h1> |
| 144 |
|
| 145 |
<p>SQLite works by translating SQL statements into bytecode and |
| 146 |
then running that bytecode in a virtual machine. This document |
| 147 |
describes how the bytecode engine works. |
| 148 |
|
| 149 |
</p><p>This document describes SQLite internals. The information provided |
| 150 |
here is not needed for routine application development using SQLite. |
| 151 |
This document is intended for people who want to delve more deeply into |
| 152 |
the internal operation of SQLite. |
| 153 |
|
| 154 |
</p><p>The bytecode engine is <u>not</u> an API of SQLite. Details |
| 155 |
about the bytecode engine change from one release of SQLite to the next. |
| 156 |
Applications that use SQLite should not depend on any of the details |
| 157 |
found in this document. |
| 158 |
|
| 159 |
</p><p>See the document "<a href="whybytecode.html">Why SQLite Uses Bytecode</a>" for some reasons why |
| 160 |
SQLite prefers to use bytecode to implement SQL. |
| 161 |
|
| 162 |
|
| 163 |
|
| 164 |
</p><h1 id="introduction"><span>2. </span>Introduction</h1> |
| 165 |
|
| 166 |
<p>SQLite works by translating each SQL statement into bytecode and |
| 167 |
then running that bytecode. |
| 168 |
A <a href="c3ref/stmt.html">prepared statement</a> in SQLite is mostly just the bytecode needed to |
| 169 |
implement the corresponding SQL. The <a href="c3ref/prepare.html">sqlite3_prepare_v2()</a> interface |
| 170 |
is a compiler that translates SQL into bytecode. |
| 171 |
The <a href="c3ref/step.html">sqlite3_step()</a> interface is the virtual machine that runs the |
| 172 |
bytecode contained within the <a href="c3ref/stmt.html">prepared statement</a>. |
| 173 |
|
| 174 |
</p><p>The bytecode virtual machine is the heart of SQLite. |
| 175 |
Programmers who want to understand how SQLite operates internally |
| 176 |
must be familiar with the bytecode engine. |
| 177 |
|
| 178 |
</p><p>Historically, the bytecode engine in SQLite is called the |
| 179 |
"Virtual DataBase Engine" or "VDBE". This website uses the terms |
| 180 |
"bytecode engine", "VDBE", "virtual machine", and "bytecode virtual |
| 181 |
machine" interchangeably, as they all mean the same thing. |
| 182 |
|
| 183 |
</p><p> |
| 184 |
This article also uses the terms "bytecode program" and |
| 185 |
"prepared statement" interchangeably, as they are mostly the same thing. |
| 186 |
|
| 187 |
</p><h2 id="vdbe_source_code"><span>2.1. </span>VDBE Source Code</h2> |
| 188 |
|
| 189 |
<p>The source code to the bytecode engine is in the |
| 190 |
<a href="https://sqlite.org/src/file/src/vdbe.c">vdbe.c</a> source |
| 191 |
file. The <a href="opcode.html#codes">opcode definitions</a> in this document are derived |
| 192 |
from comments in that source file. The |
| 193 |
source code comments are the canonical source of information |
| 194 |
about the bytecode engine. When in doubt, refer to the source code.</p> |
| 195 |
|
| 196 |
<p>In addition to the primary vdbe.c source code file, there are |
| 197 |
other helper code files in the source tree, all of whose names |
| 198 |
begin with "vdbe" - short for "Virtual DataBase Engine". |
| 199 |
|
| 200 |
</p><p>Remember that the names and meanings of opcodes often change from |
| 201 |
one release of SQLite to the next. So if you are studying the <a href="lang_explain.html">EXPLAIN</a> |
| 202 |
output from SQLite, you should reference the version of this document |
| 203 |
(or the vdbe.c source code) |
| 204 |
that corresponds to the version of SQLite that ran the <a href="lang_explain.html">EXPLAIN</a>. |
| 205 |
Otherwise, the description of the opcodes may not be accurate. |
| 206 |
This document is derived from SQLite |
| 207 |
version 3.53.2 check-in |
| 208 |
<a href='https://sqlite.org/src/timeline?c=d6e03d8c777cf'>d6e03d8c777cf</a> dated 2026-06-03. |
| 209 |
|
| 210 |
|
| 211 |
|
| 212 |
|
| 213 |
</p><h2 id="instruction_format"><span>2.2. </span>Instruction Format</h2> |
| 214 |
|
| 215 |
|
| 216 |
<p>A bytecoded program in SQLite consists of one or more instructions. |
| 217 |
Each instruction has an opcode and |
| 218 |
five operands named P1, P2 P3, P4, and P5. The P1, P2, and P3 |
| 219 |
operands are 32-bit signed integers. These operands often refer to |
| 220 |
registers. For instructions that operate on b-tree cursors, |
| 221 |
the P1 operand is usually the cursor number. |
| 222 |
For jump instructions, P2 is usually the jump destination. |
| 223 |
P4 may be a 32-bit signed integer, a 64-bit signed integer, a |
| 224 |
64-bit floating point value, a string literal, a Blob literal, |
| 225 |
a pointer to a collating sequence comparison function, or a |
| 226 |
pointer to the implementation of an application-defined SQL |
| 227 |
function, or various other things. P5 is a 16-bit unsigned integer |
| 228 |
normally used to hold flags. Bits of the P5 flag can sometimes affect |
| 229 |
the opcode in subtle ways. For example, if the |
| 230 |
SQLITE_NULLEQ (0x0080) bit of the P5 operand |
| 231 |
is set on the <a href="opcode.html#Eq">Eq</a> opcode, then the NULL values compare |
| 232 |
equal to one another. Otherwise NULL values compare different |
| 233 |
from one another. |
| 234 |
|
| 235 |
|
| 236 |
<p>Some opcodes use all five operands. Some opcodes use |
| 237 |
one or two. Some opcodes use none of the operands.</p><p> |
| 238 |
|
| 239 |
|
| 240 |
<p>The bytecode engine begins execution on instruction number 0. |
| 241 |
Execution continues until a <a href="opcode.html#Halt">Halt</a> instruction is seen, or until |
| 242 |
the program counter becomes greater than the address of |
| 243 |
last instruction, or until there is an error. |
| 244 |
When the bytecode engine halts, all memory |
| 245 |
that it allocated is released and all database cursors it may |
| 246 |
have had open are closed. If the execution stopped due to an |
| 247 |
error, any pending transactions are terminated and changes made |
| 248 |
to the database are rolled back.</p> |
| 249 |
|
| 250 |
|
| 251 |
|
| 252 |
<p>The <a href="opcode.html#ResultRow">ResultRow</a> opcode causes the |
| 253 |
bytecode engine to pause and the corresponding <a href="c3ref/step.html">sqlite3_step()</a> |
| 254 |
call to return <a href="rescode.html#row">SQLITE_ROW</a>. Before invoking |
| 255 |
<a href="opcode.html#ResultRow">ResultRow</a>, the bytecoded program will |
| 256 |
have loaded the results for a single row of a query into a series |
| 257 |
of registers. C-language APIs such as <a href="c3ref/column_blob.html">sqlite3_column_int()</a> |
| 258 |
or <a href="c3ref/column_blob.html">sqlite3_column_text()</a> extract the query results from those |
| 259 |
registers. The bytecode engine resumes with the next instruction |
| 260 |
after the <a href="opcode.html#ResultRow">ResultRow</a> on the next call |
| 261 |
to <a href="c3ref/step.html">sqlite3_step()</a>. |
| 262 |
|
| 263 |
|
| 264 |
</p><h2 id="registers"><span>2.3. </span>Registers</h2> |
| 265 |
|
| 266 |
|
| 267 |
<p>Every bytecode program has a fixed (but potentially large) number of |
| 268 |
registers. A single register can hold a variety of objects: |
| 269 |
<ul> |
| 270 |
<li> A NULL value |
| 271 |
<li> A signed 64-bit integer |
| 272 |
<li> An IEEE double-precision (64-bit) floating point number |
| 273 |
<li> An arbitrary length string |
| 274 |
<li> An arbitrary length BLOB |
| 275 |
<li> A RowSet object (See the <a href="opcode.html#RowSetAdd">RowSetAdd</a>, <a href="opcode.html#RowSetRead">RowSetRead</a>, and |
| 276 |
<a href="opcode.html#RowSetTest">RowSetTest</a> opcodes) |
| 277 |
<li> A Frame object (Used by <a href="opcode.html#subprog">subprograms</a> - see <a href="opcode.html#Program">Program</a>) |
| 278 |
</ul> |
| 279 |
|
| 280 |
|
| 281 |
<p>A register can also be "Undefined" meaning that it holds no value |
| 282 |
at all. Undefined is different from NULL. Depending on compile-time |
| 283 |
options, an attempt to read an undefined register will usually cause |
| 284 |
a run-time error. If the code generator (<a href="c3ref/prepare.html">sqlite3_prepare_v2()</a>) |
| 285 |
ever generates a <a href="c3ref/stmt.html">prepared statement</a> that reads an Undefined register, |
| 286 |
that is a bug in the code generator. |
| 287 |
|
| 288 |
</p><p> |
| 289 |
Registers are numbered beginning with 0. |
| 290 |
Most opcodes refer to at least one register. |
| 291 |
|
| 292 |
</p><p>The number of registers in a single prepared statement is fixed |
| 293 |
at compile-time. The content of all registers is cleared when |
| 294 |
a prepared statement is <a href="c3ref/reset.html">reset</a> or |
| 295 |
<a href="c3ref/finalize.html">finalized</a>. |
| 296 |
|
| 297 |
</p><p>The internal Mem object stores the value for a single register. |
| 298 |
The abstract <a href="c3ref/value.html">sqlite3_value</a> object that is exposed in the API is really |
| 299 |
just a Mem object or register. |
| 300 |
|
| 301 |
</p><h2 id="b_tree_cursors"><span>2.4. </span>B-Tree Cursors</h2> |
| 302 |
|
| 303 |
|
| 304 |
<p>A prepared statement can have |
| 305 |
zero or more open cursors. Each cursor is identified by a |
| 306 |
small integer, which is usually the P1 parameter to the opcode |
| 307 |
that uses the cursor. |
| 308 |
There can be multiple cursors open on the same index or table. |
| 309 |
All cursors operate independently, even cursors pointing to the same |
| 310 |
indices or tables. |
| 311 |
The only way for the virtual machine to interact with a database |
| 312 |
file is through a cursor. |
| 313 |
Instructions in the virtual machine can create a new cursor |
| 314 |
(ex: <a href="opcode.html#OpenRead">OpenRead</a> or <a href="opcode.html#OpenWrite">OpenWrite</a>), |
| 315 |
read data from a cursor (<a href="opcode.html#Column">Column</a>), |
| 316 |
advance the cursor to the next entry in the table |
| 317 |
(ex: <a href="opcode.html#Next">Next</a> or <a href="opcode.html#Prev">Prev</a>), and so forth. |
| 318 |
All cursors are automatically |
| 319 |
closed when the prepared statement is <a href="c3ref/reset.html">reset</a> or |
| 320 |
<a href="c3ref/finalize.html">finalized</a>. |
| 321 |
|
| 322 |
|
| 323 |
<a name="subprog"></a> |
| 324 |
|
| 325 |
<h2 id="subroutines_coroutines_and_subprograms"><span>2.5. </span>Subroutines, Coroutines, and Subprograms</h2> |
| 326 |
|
| 327 |
<p>The bytecode engine has no stack on which to store the return address |
| 328 |
of a subroutine. Return addresses must be stored in registers. |
| 329 |
Hence, bytecode subroutines are not reentrant. |
| 330 |
|
| 331 |
|
| 332 |
<p>The <a href="opcode.html#Gosub">Gosub</a> opcode stores the current program counter into |
| 333 |
register P1 then jumps to address P2. The <a href="opcode.html#Return">Return</a> opcode jumps |
| 334 |
to address P1+1. Hence, every subroutine is associated with two integers: |
| 335 |
the address of the entry point in the subroutine and the register number |
| 336 |
that is used to hold the return address. |
| 337 |
|
| 338 |
<p>The <a href="opcode.html#Yield">Yield</a> opcode swaps the value of the program counter with |
| 339 |
the integer value in register P1. This opcode is used to implement |
| 340 |
coroutines. Coroutines are often used to implement subqueries from |
| 341 |
which content is pulled on an as-needed basis. |
| 342 |
|
| 343 |
|
| 344 |
</p><p><a href="lang_createtrigger.html">Triggers</a> need to be reentrant. |
| 345 |
|
| 346 |
|
| 347 |
Since bytecode |
| 348 |
subroutines are not reentrant a different mechanism must be used to |
| 349 |
implement triggers. Each trigger is implemented using a separate bytecode |
| 350 |
program with its own opcodes, program counter, and register set. The |
| 351 |
<a href="opcode.html#Program">Program</a> opcode invokes the trigger subprogram. The <a href="opcode.html#Program">Program</a> instruction |
| 352 |
allocates and initializes a fresh register set for each invocation of the |
| 353 |
subprogram, so subprograms can be reentrant and recursive. The |
| 354 |
<a href="opcode.html#Param">Param</a> opcode is used by subprograms to access content in registers |
| 355 |
of the calling bytecode program. |
| 356 |
|
| 357 |
|
| 358 |
</p><h2 id="self_altering_code"><span>2.6. </span>Self-Altering Code</h2> |
| 359 |
|
| 360 |
|
| 361 |
<p>Some opcodes are self-altering. |
| 362 |
For example, the <a href="opcode.html#Init">Init</a> opcode (which is always the first opcode |
| 363 |
in every bytecode program) increments its P1 operand. Subsequent |
| 364 |
<a href="opcode.html#Once">Once</a> opcodes compare their P1 operands to the P1 value for |
| 365 |
the <a href="opcode.html#Init">Init</a> opcode in order to determine if the one-time initialization |
| 366 |
code that follows should be skipped. |
| 367 |
Another example is the <a href="opcode.html#String8">String8</a> opcode which converts its P4 |
| 368 |
operand from UTF-8 into the correct database string encoding, then |
| 369 |
converts itself into a <a href="opcode.html#String">String</a> opcode. |
| 370 |
|
| 371 |
|
| 372 |
|
| 373 |
<h1 id="viewing_the_bytecode"><span>3. </span>Viewing The Bytecode</h1> |
| 374 |
|
| 375 |
<p>Every SQL statement that SQLite interprets results in a program |
| 376 |
for the virtual machine. But if the SQL statement begins with |
| 377 |
the keyword <a href="lang_explain.html">EXPLAIN</a> the virtual machine will not execute the |
| 378 |
program. Instead, the instructions of the program will be returned, |
| 379 |
one instruction per row, |
| 380 |
like a query result. This feature is useful for debugging and |
| 381 |
for learning how the virtual machine operates. For example: |
| 382 |
</p> |
| 383 |
|
| 384 |
<blockquote><pre>$ <b>sqlite3 ex1.db</b> |
| 385 |
sqlite> <b>explain delete from tbl1 where two<20;</b> |
| 386 |
addr opcode p1 p2 p3 p4 p5 comment |
| 387 |
---- ------------- ---- ---- ---- ------------- -- ------------- |
| 388 |
0 Init 0 12 0 00 Start at 12 |
| 389 |
1 Null 0 1 0 00 r[1]=NULL |
| 390 |
2 OpenWrite 0 2 0 3 00 root=2 iDb=0; tbl1 |
| 391 |
3 Rewind 0 10 0 00 |
| 392 |
4 Column 0 1 2 00 r[2]=tbl1.two |
| 393 |
5 Ge 3 9 2 (BINARY) 51 if r[2]>=r[3] goto 9 |
| 394 |
6 Rowid 0 4 0 00 r[4]=rowid |
| 395 |
7 Once 0 8 0 00 |
| 396 |
8 Delete 0 1 0 tbl1 02 |
| 397 |
9 Next 0 4 0 01 |
| 398 |
10 Noop 0 0 0 00 |
| 399 |
11 Halt 0 0 0 00 |
| 400 |
12 Transaction 0 1 1 0 01 usesStmtJournal=0 |
| 401 |
13 TableLock 0 2 1 tbl1 00 iDb=0 root=2 write=1 |
| 402 |
14 Integer 20 3 0 00 r[3]=20 |
| 403 |
15 Goto 0 1 0 00</pre></blockquote> |
| 404 |
|
| 405 |
<p>Any application can run an <a href="lang_explain.html">EXPLAIN</a> query to get output similar to |
| 406 |
the above. |
| 407 |
However, indentation to show the loop structure is not generated |
| 408 |
by the SQLite core. The <a href="cli.html">command-line shell</a> contains extra logic |
| 409 |
for indenting loops. |
| 410 |
Also, the "comment" column in the <a href="lang_explain.html">EXPLAIN</a> output |
| 411 |
is only provided if SQLite is compiled with the |
| 412 |
<a href="compile.html#enable_explain_comments">-DSQLITE_ENABLE_EXPLAIN_COMMENTS</a> options. |
| 413 |
|
| 414 |
</p><p>When SQLite is compiled with the <a href="compile.html#debug">SQLITE_DEBUG</a> compile-time option, |
| 415 |
extra <a href="pragma.html#syntax">PRAGMA</a> commands are available that are useful for debugging and |
| 416 |
for exploring the operation of the VDBE. For example the <a href="pragma.html#pragma_vdbe_trace">vdbe_trace</a> |
| 417 |
pragma can be enabled to cause a disassembly of each VDBE opcode to be |
| 418 |
printed on standard output as the opcode is executed. These debugging |
| 419 |
pragmas include: |
| 420 |
</p><ul> |
| 421 |
<li> <a href="pragma.html#pragma_parser_trace">PRAGMA parser_trace</a> |
| 422 |
</li><li> <a href="pragma.html#pragma_vdbe_addoptrace">PRAGMA vdbe_addoptrace</a> |
| 423 |
</li><li> <a href="pragma.html#pragma_vdbe_debug">PRAGMA vdbe_debug</a> |
| 424 |
</li><li> <a href="pragma.html#pragma_vdbe_listing">PRAGMA vdbe_listing</a> |
| 425 |
</li><li> <a href="pragma.html#pragma_vdbe_trace">PRAGMA vdbe_trace</a> |
| 426 |
</li></ul> |
| 427 |
|
| 428 |
|
| 429 |
<h1 id="the_opcodes"><span>4. </span>The Opcodes</h1> |
| 430 |
|
| 431 |
<p>There are currently 192 |
| 432 |
opcodes defined by the virtual machine. |
| 433 |
All currently defined opcodes are described in the table below. |
| 434 |
This table was generated automatically by scanning the source code |
| 435 |
from the file |
| 436 |
<a href="https://sqlite.org/src/artifact/6c57525d7db0232d52687d30da1093db0c152f14206c2ef1adf0c19a09d863e3">vdbe.c</a>. |
| 437 |
|
| 438 |
|
| 439 |
</p><p>Remember: The VDBE opcodes are <u>not</u> part of the interface |
| 440 |
definition for SQLite. The number of opcodes and their names and meanings |
| 441 |
change from one release of SQLite to the next. |
| 442 |
The opcodes shown in the table below are valid for SQLite |
| 443 |
version 3.53.2 check-in |
| 444 |
<a href='https://sqlite.org/src/timeline?c=d6e03d8c777cf'>d6e03d8c777cf</a> dated 2026-06-03. |
| 445 |
|
| 446 |
<a name="codes"></a> |
| 447 |
|
| 448 |
</div> |
| 449 |
<style>.optab td {vertical-align:top; padding: 1ex 1ex;}</style> |
| 450 |
<div class="optab"> |
| 451 |
<blockquote><table cellspacing=0 border=1 cellpaddin> |
| 452 |
<tr><th>Opcode Name</th><th>Description</th></tr> |
| 453 |
<tr><td valign="top" align="center"> |
| 454 |
<a name="Abortable"></a>Abortable |
| 455 |
<td>Verify that an Abort can happen. Assert if an Abort at this point |
| 456 |
might cause database corruption. This opcode only appears in debugging |
| 457 |
builds.</p> |
| 458 |
|
| 459 |
<p>An Abort is safe if either there have been no writes, or if there is |
| 460 |
an active statement journal.</td></tr> |
| 461 |
<tr><td valign="top" align="center"> |
| 462 |
<a name="Add"></a>Add |
| 463 |
<td>Add the value in register P1 to the value in register P2 |
| 464 |
and store the result in register P3. |
| 465 |
If either input is NULL, the result is NULL.</td></tr> |
| 466 |
<tr><td valign="top" align="center"> |
| 467 |
<a name="AddImm"></a>AddImm |
| 468 |
<td>Add the constant P2 to the value in register P1. |
| 469 |
The result is always an integer.</p> |
| 470 |
|
| 471 |
<p>To force any register to be an integer, just add 0.</td></tr> |
| 472 |
<tr><td valign="top" align="center"> |
| 473 |
<a name="Affinity"></a>Affinity |
| 474 |
<td>Apply affinities to a range of P2 registers starting with P1.</p> |
| 475 |
|
| 476 |
<p>P4 is a string that is P2 characters long. The N-th character of the |
| 477 |
string indicates the column affinity that should be used for the N-th |
| 478 |
memory cell in the range.</td></tr> |
| 479 |
<tr><td valign="top" align="center"> |
| 480 |
<a name="AggFinal"></a>AggFinal |
| 481 |
<td>P1 is the memory location that is the accumulator for an aggregate |
| 482 |
or window function. Execute the finalizer function |
| 483 |
for an aggregate and store the result in P1.</p> |
| 484 |
|
| 485 |
<p>P2 is the number of arguments that the step function takes and |
| 486 |
P4 is a pointer to the FuncDef for this function. The P2 |
| 487 |
argument is not used by this opcode. It is only there to disambiguate |
| 488 |
functions that can take varying numbers of arguments. The |
| 489 |
P4 argument is only needed for the case where |
| 490 |
the step function was not previously called.</td></tr> |
| 491 |
<tr><td valign="top" align="center"> |
| 492 |
<a name="AggInverse"></a>AggInverse |
| 493 |
<td>Execute the xInverse function for an aggregate. |
| 494 |
The function has P5 arguments. P4 is a pointer to the |
| 495 |
FuncDef structure that specifies the function. Register P3 is the |
| 496 |
accumulator.</p> |
| 497 |
|
| 498 |
<p>The P5 arguments are taken from register P2 and its |
| 499 |
successors.</td></tr> |
| 500 |
<tr><td valign="top" align="center"> |
| 501 |
<a name="AggStep"></a>AggStep |
| 502 |
<td>Execute the xStep function for an aggregate. |
| 503 |
The function has P5 arguments. P4 is a pointer to the |
| 504 |
FuncDef structure that specifies the function. Register P3 is the |
| 505 |
accumulator.</p> |
| 506 |
|
| 507 |
<p>The P5 arguments are taken from register P2 and its |
| 508 |
successors.</td></tr> |
| 509 |
<tr><td valign="top" align="center"> |
| 510 |
<a name="AggStep1"></a>AggStep1 |
| 511 |
<td>Execute the xStep (if P1==0) or xInverse (if P1!=0) function for an |
| 512 |
aggregate. The function has P5 arguments. P4 is a pointer to the |
| 513 |
FuncDef structure that specifies the function. Register P3 is the |
| 514 |
accumulator.</p> |
| 515 |
|
| 516 |
<p>The P5 arguments are taken from register P2 and its |
| 517 |
successors.</p> |
| 518 |
|
| 519 |
<p>This opcode is initially coded as OP_AggStep0. On first evaluation, |
| 520 |
the FuncDef stored in P4 is converted into an sqlite3_context and |
| 521 |
the opcode is changed. In this way, the initialization of the |
| 522 |
sqlite3_context only happens once, instead of on each call to the |
| 523 |
step function.</td></tr> |
| 524 |
<tr><td valign="top" align="center"> |
| 525 |
<a name="AggValue"></a>AggValue |
| 526 |
<td>Invoke the xValue() function and store the result in register P3.</p> |
| 527 |
|
| 528 |
<p>P2 is the number of arguments that the step function takes and |
| 529 |
P4 is a pointer to the FuncDef for this function. The P2 |
| 530 |
argument is not used by this opcode. It is only there to disambiguate |
| 531 |
functions that can take varying numbers of arguments. The |
| 532 |
P4 argument is only needed for the case where |
| 533 |
the step function was not previously called.</td></tr> |
| 534 |
<tr><td valign="top" align="center"> |
| 535 |
<a name="And"></a>And |
| 536 |
<td>Take the logical AND of the values in registers P1 and P2 and |
| 537 |
write the result into register P3.</p> |
| 538 |
|
| 539 |
<p>If either P1 or P2 is 0 (false) then the result is 0 even if |
| 540 |
the other input is NULL. A NULL and true or two NULLs give |
| 541 |
a NULL output.</td></tr> |
| 542 |
<tr><td valign="top" align="center"> |
| 543 |
<a name="AutoCommit"></a>AutoCommit |
| 544 |
<td>Set the database auto-commit flag to P1 (1 or 0). If P2 is true, roll |
| 545 |
back any currently active btree transactions. If there are any active |
| 546 |
VMs (apart from this one), then a ROLLBACK fails. A COMMIT fails if |
| 547 |
there are active writing VMs or active VMs that use shared cache.</p> |
| 548 |
|
| 549 |
<p>This instruction causes the VM to halt.</td></tr> |
| 550 |
<tr><td valign="top" align="center"> |
| 551 |
<a name="BeginSubrtn"></a>BeginSubrtn |
| 552 |
<td>Mark the beginning of a subroutine that can be entered in-line |
| 553 |
or that can be called using <a href="opcode.html#Gosub">Gosub</a>. The subroutine should |
| 554 |
be terminated by an <a href="opcode.html#Return">Return</a> instruction that has a P1 operand that |
| 555 |
is the same as the P2 operand to this opcode and that has P3 set to 1. |
| 556 |
If the subroutine is entered in-line, then the <a href="opcode.html#Return">Return</a> will simply |
| 557 |
fall through. But if the subroutine is entered using <a href="opcode.html#Gosub">Gosub</a>, then |
| 558 |
the <a href="opcode.html#Return">Return</a> will jump back to the first instruction after the <a href="opcode.html#Gosub">Gosub</a>.</p> |
| 559 |
|
| 560 |
<p>This routine works by loading a NULL into the P2 register. When the |
| 561 |
return address register contains a NULL, the <a href="opcode.html#Return">Return</a> instruction is |
| 562 |
a no-op that simply falls through to the next instruction (assuming that |
| 563 |
the <a href="opcode.html#Return">Return</a> opcode has a P3 value of 1). Thus if the subroutine is |
| 564 |
entered in-line, then the <a href="opcode.html#Return">Return</a> will cause in-line execution to |
| 565 |
continue. But if the subroutine is entered via <a href="opcode.html#Gosub">Gosub</a>, then the |
| 566 |
<a href="opcode.html#Return">Return</a> will cause a return to the address following the <a href="opcode.html#Gosub">Gosub</a>.</p> |
| 567 |
|
| 568 |
<p>This opcode is identical to <a href="opcode.html#Null">Null</a>. It has a different name |
| 569 |
only to make the byte code easier to read and verify.</td></tr> |
| 570 |
<tr><td valign="top" align="center"> |
| 571 |
<a name="BitAnd"></a>BitAnd |
| 572 |
<td>Take the bit-wise AND of the values in register P1 and P2 and |
| 573 |
store the result in register P3. |
| 574 |
If either input is NULL, the result is NULL.</td></tr> |
| 575 |
<tr><td valign="top" align="center"> |
| 576 |
<a name="BitNot"></a>BitNot |
| 577 |
<td>Interpret the content of register P1 as an integer. Store the |
| 578 |
ones-complement of the P1 value into register P2. If P1 holds |
| 579 |
a NULL then store a NULL in P2.</td></tr> |
| 580 |
<tr><td valign="top" align="center"> |
| 581 |
<a name="BitOr"></a>BitOr |
| 582 |
<td>Take the bit-wise OR of the values in register P1 and P2 and |
| 583 |
store the result in register P3. |
| 584 |
If either input is NULL, the result is NULL.</td></tr> |
| 585 |
<tr><td valign="top" align="center"> |
| 586 |
<a name="Blob"></a>Blob |
| 587 |
<td>P4 points to a blob of data P1 bytes long. Store this |
| 588 |
blob in register P2. If P4 is a NULL pointer, then construct |
| 589 |
a zero-filled blob that is P1 bytes long in P2.</td></tr> |
| 590 |
<tr><td valign="top" align="center"> |
| 591 |
<a name="Cast"></a>Cast |
| 592 |
<td>Force the value in register P1 to be the type defined by P2.</p> |
| 593 |
|
| 594 |
<p><ul> |
| 595 |
<li> P2=='A' → BLOB |
| 596 |
<li> P2=='B' → TEXT |
| 597 |
<li> P2=='C' → NUMERIC |
| 598 |
<li> P2=='D' → INTEGER |
| 599 |
<li> P2=='E' → REAL |
| 600 |
</ul></p> |
| 601 |
|
| 602 |
<p>A NULL value is not changed by this routine. It remains NULL.</td></tr> |
| 603 |
<tr><td valign="top" align="center"> |
| 604 |
<a name="Checkpoint"></a>Checkpoint |
| 605 |
<td>Checkpoint database P1. This is a no-op if P1 is not currently in |
| 606 |
WAL mode. Parameter P2 is one of SQLITE_CHECKPOINT_PASSIVE, FULL, |
| 607 |
RESTART, or TRUNCATE. Write 1 or 0 into mem[P3] if the checkpoint returns |
| 608 |
SQLITE_BUSY or not, respectively. Write the number of pages in the |
| 609 |
WAL after the checkpoint into mem[P3+1] and the number of pages |
| 610 |
in the WAL that have been checkpointed after the checkpoint |
| 611 |
completes into mem[P3+2]. However on an error, mem[P3+1] and |
| 612 |
mem[P3+2] are initialized to -1.</td></tr> |
| 613 |
<tr><td valign="top" align="center"> |
| 614 |
<a name="Clear"></a>Clear |
| 615 |
<td>Delete all contents of the database table or index whose root page |
| 616 |
in the database file is given by P1. But, unlike <a href="opcode.html#Destroy">Destroy</a>, do not |
| 617 |
remove the table or index from the database file.</p> |
| 618 |
|
| 619 |
<p>The table being cleared is in the main database file if P2==0. If |
| 620 |
P2==1 then the table to be cleared is in the auxiliary database file |
| 621 |
that is used to store tables create using CREATE TEMPORARY TABLE.</p> |
| 622 |
|
| 623 |
<p>If the P3 value is non-zero, then the row change count is incremented |
| 624 |
by the number of rows in the table being cleared. If P3 is greater |
| 625 |
than zero, then the value stored in register P3 is also incremented |
| 626 |
by the number of rows in the table being cleared.</p> |
| 627 |
|
| 628 |
<p>See also: <a href="opcode.html#Destroy">Destroy</a></td></tr> |
| 629 |
<tr><td valign="top" align="center"> |
| 630 |
<a name="Close"></a>Close |
| 631 |
<td>Close a cursor previously opened as P1. If P1 is not |
| 632 |
currently open, this instruction is a no-op.</td></tr> |
| 633 |
<tr><td valign="top" align="center"> |
| 634 |
<a name="ClrSubtype"></a>ClrSubtype |
| 635 |
<td>Clear the subtype from register P1.</td></tr> |
| 636 |
<tr><td valign="top" align="center"> |
| 637 |
<a name="CollSeq"></a>CollSeq |
| 638 |
<td>P4 is a pointer to a CollSeq object. If the next call to a user function |
| 639 |
or aggregate calls sqlite3GetFuncCollSeq(), this collation sequence will |
| 640 |
be returned. This is used by the built-in min(), max() and nullif() |
| 641 |
functions.</p> |
| 642 |
|
| 643 |
<p>If P1 is not zero, then it is a register that a subsequent min() or |
| 644 |
max() aggregate will set to 1 if the current row is not the minimum or |
| 645 |
maximum. The P1 register is initialized to 0 by this instruction.</p> |
| 646 |
|
| 647 |
<p>The interface used by the implementation of the aforementioned functions |
| 648 |
to retrieve the collation sequence set by this opcode is not available |
| 649 |
publicly. Only built-in functions have access to this feature.</td></tr> |
| 650 |
<tr><td valign="top" align="center"> |
| 651 |
<a name="Column"></a>Column |
| 652 |
<td>Interpret the data that cursor P1 points to as a structure built using |
| 653 |
the <a href="opcode.html#MakeRecord">MakeRecord</a> instruction. (See the <a href="opcode.html#MakeRecord">MakeRecord</a> opcode for additional |
| 654 |
information about the format of the data.) Extract the P2-th column |
| 655 |
from this record. If there are less than (P2+1) |
| 656 |
values in the record, extract a NULL.</p> |
| 657 |
|
| 658 |
<p>The value extracted is stored in register P3.</p> |
| 659 |
|
| 660 |
<p>If the record contains fewer than P2 fields, then extract a NULL. Or, |
| 661 |
if the P4 argument is a P4_MEM use the value of the P4 argument as |
| 662 |
the result.</p> |
| 663 |
|
| 664 |
<p>If the OPFLAG_LENGTHARG bit is set in P5 then the result is guaranteed |
| 665 |
to only be used by the length() function or the equivalent. The content |
| 666 |
of large blobs is not loaded, thus saving CPU cycles. If the |
| 667 |
OPFLAG_TYPEOFARG bit is set then the result will only be used by the |
| 668 |
typeof() function or the IS NULL or IS NOT NULL operators or the |
| 669 |
equivalent. In this case, all content loading can be omitted.</td></tr> |
| 670 |
<tr><td valign="top" align="center"> |
| 671 |
<a name="ColumnsUsed"></a>ColumnsUsed |
| 672 |
<td>This opcode (which only exists if SQLite was compiled with |
| 673 |
SQLITE_ENABLE_COLUMN_USED_MASK) identifies which columns of the |
| 674 |
table or index for cursor P1 are used. P4 is a 64-bit integer |
| 675 |
(P4_INT64) in which the first 63 bits are one for each of the |
| 676 |
first 63 columns of the table or index that are actually used |
| 677 |
by the cursor. The high-order bit is set if any column after |
| 678 |
the 64th is used.</td></tr> |
| 679 |
<tr><td valign="top" align="center"> |
| 680 |
<a name="Compare"></a>Compare |
| 681 |
<td>Compare two vectors of registers in reg(P1)..reg(P1+P3-1) (call this |
| 682 |
vector "A") and in reg(P2)..reg(P2+P3-1) ("B"). Save the result of |
| 683 |
the comparison for use by the next <a href="opcode.html#Jump">Jump</a> instruct.</p> |
| 684 |
|
| 685 |
<p>If P5 has the OPFLAG_PERMUTE bit set, then the order of comparison is |
| 686 |
determined by the most recent <a href="opcode.html#Permutation">Permutation</a> operator. If the |
| 687 |
OPFLAG_PERMUTE bit is clear, then register are compared in sequential |
| 688 |
order.</p> |
| 689 |
|
| 690 |
<p>P4 is a KeyInfo structure that defines collating sequences and sort |
| 691 |
orders for the comparison. The permutation applies to registers |
| 692 |
only. The KeyInfo elements are used sequentially.</p> |
| 693 |
|
| 694 |
<p>The comparison is a sort comparison, so NULLs compare equal, |
| 695 |
NULLs are less than numbers, numbers are less than strings, |
| 696 |
and strings are less than blobs.</p> |
| 697 |
|
| 698 |
<p>This opcode must be immediately followed by an <a href="opcode.html#Jump">Jump</a> opcode.</td></tr> |
| 699 |
<tr><td valign="top" align="center"> |
| 700 |
<a name="Concat"></a>Concat |
| 701 |
<td>Add the text in register P1 onto the end of the text in |
| 702 |
register P2 and store the result in register P3. |
| 703 |
If either the P1 or P2 text are NULL then store NULL in P3.</p> |
| 704 |
|
| 705 |
<p>P3 = P2 || P1</p> |
| 706 |
|
| 707 |
<p>It is illegal for P1 and P3 to be the same register. Sometimes, |
| 708 |
if P3 is the same register as P2, the implementation is able |
| 709 |
to avoid a memcpy().</td></tr> |
| 710 |
<tr><td valign="top" align="center"> |
| 711 |
<a name="Copy"></a>Copy |
| 712 |
<td>Make a copy of registers P1..P1+P3 into registers P2..P2+P3.</p> |
| 713 |
|
| 714 |
<p>If the 0x0002 bit of P5 is set then also clear the MEM_Subtype flag in the |
| 715 |
destination. The 0x0001 bit of P5 indicates that this <a href="opcode.html#Copy">Copy</a> opcode cannot |
| 716 |
be merged. The 0x0001 bit is used by the query planner and does not |
| 717 |
come into play during query execution.</p> |
| 718 |
|
| 719 |
<p>This instruction makes a deep copy of the value. A duplicate |
| 720 |
is made of any string or blob constant. See also <a href="opcode.html#SCopy">SCopy</a>.</td></tr> |
| 721 |
<tr><td valign="top" align="center"> |
| 722 |
<a name="Count"></a>Count |
| 723 |
<td>Store the number of entries (an integer value) in the table or index |
| 724 |
opened by cursor P1 in register P2.</p> |
| 725 |
|
| 726 |
<p>If P3==0, then an exact count is obtained, which involves visiting |
| 727 |
every btree page of the table. But if P3 is non-zero, an estimate |
| 728 |
is returned based on the current cursor position.</td></tr> |
| 729 |
<tr><td valign="top" align="center"> |
| 730 |
<a name="CreateBtree"></a>CreateBtree |
| 731 |
<td>Allocate a new b-tree in the main database file if P1==0 or in the |
| 732 |
TEMP database file if P1==1 or in an attached database if |
| 733 |
P1>1. The P3 argument must be 1 (BTREE_INTKEY) for a rowid table |
| 734 |
it must be 2 (BTREE_BLOBKEY) for an index or WITHOUT ROWID table. |
| 735 |
The root page number of the new b-tree is stored in register P2.</td></tr> |
| 736 |
<tr><td valign="top" align="center"> |
| 737 |
<a name="CursorHint"></a>CursorHint |
| 738 |
<td>Provide a hint to cursor P1 that it only needs to return rows that |
| 739 |
satisfy the Expr in P4. TK_REGISTER terms in the P4 expression refer |
| 740 |
to values currently held in registers. TK_COLUMN terms in the P4 |
| 741 |
expression refer to columns in the b-tree to which cursor P1 is pointing.</td></tr> |
| 742 |
<tr><td valign="top" align="center"> |
| 743 |
<a name="CursorLock"></a>CursorLock |
| 744 |
<td>Lock the btree to which cursor P1 is pointing so that the btree cannot be |
| 745 |
written by an other cursor.</td></tr> |
| 746 |
<tr><td valign="top" align="center"> |
| 747 |
<a name="CursorUnlock"></a>CursorUnlock |
| 748 |
<td>Unlock the btree to which cursor P1 is pointing so that it can be |
| 749 |
written by other cursors.</td></tr> |
| 750 |
<tr><td valign="top" align="center"> |
| 751 |
<a name="DecrJumpZero"></a>DecrJumpZero |
| 752 |
<td>Register P1 must hold an integer. Decrement the value in P1 |
| 753 |
and jump to P2 if the new value is exactly zero.</td></tr> |
| 754 |
<tr><td valign="top" align="center"> |
| 755 |
<a name="DeferredSeek"></a>DeferredSeek |
| 756 |
<td>P1 is an open index cursor and P3 is a cursor on the corresponding |
| 757 |
table. This opcode does a deferred seek of the P3 table cursor |
| 758 |
to the row that corresponds to the current row of P1.</p> |
| 759 |
|
| 760 |
<p>This is a deferred seek. Nothing actually happens until |
| 761 |
the cursor is used to read a record. That way, if no reads |
| 762 |
occur, no unnecessary I/O happens.</p> |
| 763 |
|
| 764 |
<p>P4 may be an array of integers (type P4_INTARRAY) containing |
| 765 |
one entry for each column in the P3 table. If array entry a(i) |
| 766 |
is non-zero, then reading column a(i)-1 from cursor P3 is |
| 767 |
equivalent to performing the deferred seek and then reading column i |
| 768 |
from P1. This information is stored in P3 and used to redirect |
| 769 |
reads against P3 over to P1, thus possibly avoiding the need to |
| 770 |
seek and read cursor P3.</td></tr> |
| 771 |
<tr><td valign="top" align="center"> |
| 772 |
<a name="Delete"></a>Delete |
| 773 |
<td>Delete the record at which the P1 cursor is currently pointing.</p> |
| 774 |
|
| 775 |
<p>If the OPFLAG_SAVEPOSITION bit of the P5 parameter is set, then |
| 776 |
the cursor will be left pointing at either the next or the previous |
| 777 |
record in the table. If it is left pointing at the next record, then |
| 778 |
the next <a href="opcode.html#Next">Next</a> instruction will be a no-op. As a result, in this case |
| 779 |
it is ok to delete a record from within a <a href="opcode.html#Next">Next</a> loop. If |
| 780 |
OPFLAG_SAVEPOSITION bit of P5 is clear, then the cursor will be |
| 781 |
left in an undefined state.</p> |
| 782 |
|
| 783 |
<p>If the OPFLAG_AUXDELETE bit is set on P5, that indicates that this |
| 784 |
delete is one of several associated with deleting a table row and |
| 785 |
all its associated index entries. Exactly one of those deletes is |
| 786 |
the "primary" delete. The others are all on OPFLAG_FORDELETE |
| 787 |
cursors or else are marked with the AUXDELETE flag.</p> |
| 788 |
|
| 789 |
<p>If the OPFLAG_NCHANGE (0x01) flag of P2 (NB: P2 not P5) is set, then |
| 790 |
the row change count is incremented (otherwise not).</p> |
| 791 |
|
| 792 |
<p>If the OPFLAG_ISNOOP (0x40) flag of P2 (not P5!) is set, then the |
| 793 |
pre-update-hook for deletes is run, but the btree is otherwise unchanged. |
| 794 |
This happens when the <a href="opcode.html#Delete">Delete</a> is to be shortly followed by an <a href="opcode.html#Insert">Insert</a> |
| 795 |
with the same key, causing the btree entry to be overwritten.</p> |
| 796 |
|
| 797 |
<p>P1 must not be pseudo-table. It has to be a real table with |
| 798 |
multiple rows.</p> |
| 799 |
|
| 800 |
<p>If P4 is not NULL then it points to a Table object. In this case either |
| 801 |
the update or pre-update hook, or both, may be invoked. The P1 cursor must |
| 802 |
have been positioned using <a href="opcode.html#NotFound">NotFound</a> prior to invoking this opcode in |
| 803 |
this case. Specifically, if one is configured, the pre-update hook is |
| 804 |
invoked if P4 is not NULL. The update-hook is invoked if one is configured, |
| 805 |
P4 is not NULL, and the OPFLAG_NCHANGE flag is set in P2.</p> |
| 806 |
|
| 807 |
<p>If the OPFLAG_ISUPDATE flag is set in P2, then P3 contains the address |
| 808 |
of the memory cell that contains the value that the rowid of the row will |
| 809 |
be set to by the update.</td></tr> |
| 810 |
<tr><td valign="top" align="center"> |
| 811 |
<a name="Destroy"></a>Destroy |
| 812 |
<td>Delete an entire database table or index whose root page in the database |
| 813 |
file is given by P1.</p> |
| 814 |
|
| 815 |
<p>The table being destroyed is in the main database file if P3==0. If |
| 816 |
P3==1 then the table to be destroyed is in the auxiliary database file |
| 817 |
that is used to store tables create using CREATE TEMPORARY TABLE.</p> |
| 818 |
|
| 819 |
<p>If AUTOVACUUM is enabled then it is possible that another root page |
| 820 |
might be moved into the newly deleted root page in order to keep all |
| 821 |
root pages contiguous at the beginning of the database. The former |
| 822 |
value of the root page that moved - its value before the move occurred - |
| 823 |
is stored in register P2. If no page movement was required (because the |
| 824 |
table being dropped was already the last one in the database) then a |
| 825 |
zero is stored in register P2. If AUTOVACUUM is disabled then a zero |
| 826 |
is stored in register P2.</p> |
| 827 |
|
| 828 |
<p>This opcode throws an error if there are any active reader VMs when |
| 829 |
it is invoked. This is done to avoid the difficulty associated with |
| 830 |
updating existing cursors when a root page is moved in an AUTOVACUUM |
| 831 |
database. This error is thrown even if the database is not an AUTOVACUUM |
| 832 |
db in order to avoid introducing an incompatibility between autovacuum |
| 833 |
and non-autovacuum modes.</p> |
| 834 |
|
| 835 |
<p>See also: <a href="opcode.html#Clear">Clear</a></td></tr> |
| 836 |
<tr><td valign="top" align="center"> |
| 837 |
<a name="Divide"></a>Divide |
| 838 |
<td>Divide the value in register P1 by the value in register P2 |
| 839 |
and store the result in register P3 (P3=P2/P1). If the value in |
| 840 |
register P1 is zero, then the result is NULL. If either input is |
| 841 |
NULL, the result is NULL.</td></tr> |
| 842 |
<tr><td valign="top" align="center"> |
| 843 |
<a name="DropIndex"></a>DropIndex |
| 844 |
<td>Remove the internal (in-memory) data structures that describe |
| 845 |
the index named P4 in database P1. This is called after an index |
| 846 |
is dropped from disk (using the <a href="opcode.html#Destroy">Destroy</a> opcode) |
| 847 |
in order to keep the internal representation of the |
| 848 |
schema consistent with what is on disk.</td></tr> |
| 849 |
<tr><td valign="top" align="center"> |
| 850 |
<a name="DropTable"></a>DropTable |
| 851 |
<td>Remove the internal (in-memory) data structures that describe |
| 852 |
the table named P4 in database P1. This is called after a table |
| 853 |
is dropped from disk (using the <a href="opcode.html#Destroy">Destroy</a> opcode) in order to keep |
| 854 |
the internal representation of the |
| 855 |
schema consistent with what is on disk.</td></tr> |
| 856 |
<tr><td valign="top" align="center"> |
| 857 |
<a name="DropTrigger"></a>DropTrigger |
| 858 |
<td>Remove the internal (in-memory) data structures that describe |
| 859 |
the trigger named P4 in database P1. This is called after a trigger |
| 860 |
is dropped from disk (using the <a href="opcode.html#Destroy">Destroy</a> opcode) in order to keep |
| 861 |
the internal representation of the |
| 862 |
schema consistent with what is on disk.</td></tr> |
| 863 |
<tr><td valign="top" align="center"> |
| 864 |
<a name="ElseEq"></a>ElseEq |
| 865 |
<td>This opcode must follow an <a href="opcode.html#Lt">Lt</a> or <a href="opcode.html#Gt">Gt</a> comparison operator. There |
| 866 |
can be zero or more OP_ReleaseReg opcodes intervening, but no other |
| 867 |
opcodes are allowed to occur between this instruction and the previous |
| 868 |
<a href="opcode.html#Lt">Lt</a> or <a href="opcode.html#Gt">Gt</a>.</p> |
| 869 |
|
| 870 |
<p>If the result of an <a href="opcode.html#Eq">Eq</a> comparison on the same two operands as |
| 871 |
the prior <a href="opcode.html#Lt">Lt</a> or <a href="opcode.html#Gt">Gt</a> would have been true, then jump to P2. If |
| 872 |
the result of an <a href="opcode.html#Eq">Eq</a> comparison on the two previous operands |
| 873 |
would have been false or NULL, then fall through.</td></tr> |
| 874 |
<tr><td valign="top" align="center"> |
| 875 |
<a name="EndCoroutine"></a>EndCoroutine |
| 876 |
<td>The instruction at the address in register P1 is a <a href="opcode.html#Yield">Yield</a>. |
| 877 |
<a href="opcode.html#Jump">Jump</a> to the P2 parameter of that <a href="opcode.html#Yield">Yield</a>. |
| 878 |
After the jump, the value register P1 is left with a value |
| 879 |
such that subsequent OP_Yields go back to the this same |
| 880 |
<a href="opcode.html#EndCoroutine">EndCoroutine</a> instruction.</p> |
| 881 |
|
| 882 |
<p>See also: <a href="opcode.html#InitCoroutine">InitCoroutine</a></td></tr> |
| 883 |
<tr><td valign="top" align="center"> |
| 884 |
<a name="Eq"></a>Eq |
| 885 |
<td>Compare the values in register P1 and P3. If reg(P3)==reg(P1) then |
| 886 |
jump to address P2.</p> |
| 887 |
|
| 888 |
<p>The SQLITE_AFF_MASK portion of P5 must be an affinity character - |
| 889 |
SQLITE_AFF_TEXT, SQLITE_AFF_INTEGER, and so forth. An attempt is made |
| 890 |
to coerce both inputs according to this affinity before the |
| 891 |
comparison is made. If the SQLITE_AFF_MASK is 0x00, then numeric |
| 892 |
affinity is used. Note that the affinity conversions are stored |
| 893 |
back into the input registers P1 and P3. So this opcode can cause |
| 894 |
persistent changes to registers P1 and P3.</p> |
| 895 |
|
| 896 |
<p>Once any conversions have taken place, and neither value is NULL, |
| 897 |
the values are compared. If both values are blobs then memcmp() is |
| 898 |
used to determine the results of the comparison. If both values |
| 899 |
are text, then the appropriate collating function specified in |
| 900 |
P4 is used to do the comparison. If P4 is not specified then |
| 901 |
memcmp() is used to compare text string. If both values are |
| 902 |
numeric, then a numeric comparison is used. If the two values |
| 903 |
are of different types, then numbers are considered less than |
| 904 |
strings and strings are considered less than blobs.</p> |
| 905 |
|
| 906 |
<p>If SQLITE_NULLEQ is set in P5 then the result of comparison is always either |
| 907 |
true or false and is never NULL. If both operands are NULL then the result |
| 908 |
of comparison is true. If either operand is NULL then the result is false. |
| 909 |
If neither operand is NULL the result is the same as it would be if |
| 910 |
the SQLITE_NULLEQ flag were omitted from P5.</p> |
| 911 |
|
| 912 |
<p>This opcode saves the result of comparison for use by the new |
| 913 |
<a href="opcode.html#Jump">Jump</a> opcode.</td></tr> |
| 914 |
<tr><td valign="top" align="center"> |
| 915 |
<a name="Expire"></a>Expire |
| 916 |
<td>Cause precompiled statements to expire. When an expired statement |
| 917 |
is executed using sqlite3_step() it will either automatically |
| 918 |
reprepare itself (if it was originally created using sqlite3_prepare_v2()) |
| 919 |
or it will fail with SQLITE_SCHEMA.</p> |
| 920 |
|
| 921 |
<p>If P1 is 0, then all SQL statements become expired. If P1 is non-zero, |
| 922 |
then only the currently executing statement is expired.</p> |
| 923 |
|
| 924 |
<p>If P2 is 0, then SQL statements are expired immediately. If P2 is 1, |
| 925 |
then running SQL statements are allowed to continue to run to completion. |
| 926 |
The P2==1 case occurs when a CREATE INDEX or similar schema change happens |
| 927 |
that might help the statement run faster but which does not affect the |
| 928 |
correctness of operation.</td></tr> |
| 929 |
<tr><td valign="top" align="center"> |
| 930 |
<a name="Explain"></a>Explain |
| 931 |
<td>This is the same as <a href="opcode.html#Noop">Noop</a> during normal query execution. The |
| 932 |
purpose of this opcode is to hold information about the query |
| 933 |
plan for the purpose of EXPLAIN QUERY PLAN output.</p> |
| 934 |
|
| 935 |
<p>The P4 value is human-readable text that describes the query plan |
| 936 |
element. Something like "SCAN t1" or "SEARCH t2 USING INDEX t2x1".</p> |
| 937 |
|
| 938 |
<p>The P1 value is the ID of the current element and P2 is the parent |
| 939 |
element for the case of nested query plan elements. If P2 is zero |
| 940 |
then this element is a top-level element.</p> |
| 941 |
|
| 942 |
<p>For loop elements, P3 is the estimated code of each invocation of this |
| 943 |
element.</p> |
| 944 |
|
| 945 |
<p>As with all opcodes, the meanings of the parameters for <a href="opcode.html#Explain">Explain</a> |
| 946 |
are subject to change from one release to the next. Applications |
| 947 |
should not attempt to interpret or use any of the information |
| 948 |
contained in the <a href="opcode.html#Explain">Explain</a> opcode. The information provided by this |
| 949 |
opcode is intended for testing and debugging use only.</td></tr> |
| 950 |
<tr><td valign="top" align="center"> |
| 951 |
<a name="Filter"></a>Filter |
| 952 |
<td>Compute a hash on the key contained in the P4 registers starting |
| 953 |
with r[P3]. Check to see if that hash is found in the |
| 954 |
bloom filter hosted by register P1. If it is not present then |
| 955 |
maybe jump to P2. Otherwise fall through.</p> |
| 956 |
|
| 957 |
<p>False negatives are harmless. It is always safe to fall through, |
| 958 |
even if the value is in the bloom filter. A false negative causes |
| 959 |
more CPU cycles to be used, but it should still yield the correct |
| 960 |
answer. However, an incorrect answer may well arise from a |
| 961 |
false positive - if the jump is taken when it should fall through.</td></tr> |
| 962 |
<tr><td valign="top" align="center"> |
| 963 |
<a name="FilterAdd"></a>FilterAdd |
| 964 |
<td>Compute a hash on the P4 registers starting with r[P3] and |
| 965 |
add that hash to the bloom filter contained in r[P1].</td></tr> |
| 966 |
<tr><td valign="top" align="center"> |
| 967 |
<a name="FinishSeek"></a>FinishSeek |
| 968 |
<td>If cursor P1 was previously moved via <a href="opcode.html#DeferredSeek">DeferredSeek</a>, complete that |
| 969 |
seek operation now, without further delay. If the cursor seek has |
| 970 |
already occurred, this instruction is a no-op.</td></tr> |
| 971 |
<tr><td valign="top" align="center"> |
| 972 |
<a name="FkCheck"></a>FkCheck |
| 973 |
<td>Halt with an SQLITE_CONSTRAINT error if there are any unresolved |
| 974 |
foreign key constraint violations. If there are no foreign key |
| 975 |
constraint violations, this is a no-op.</p> |
| 976 |
|
| 977 |
<p>FK constraint violations are also checked when the prepared statement |
| 978 |
exits. This opcode is used to raise foreign key constraint errors prior |
| 979 |
to returning results such as a row change count or the result of a |
| 980 |
RETURNING clause.</td></tr> |
| 981 |
<tr><td valign="top" align="center"> |
| 982 |
<a name="FkCounter"></a>FkCounter |
| 983 |
<td>Increment a "constraint counter" by P2 (P2 may be negative or positive). |
| 984 |
If P1 is non-zero, the database constraint counter is incremented |
| 985 |
(deferred foreign key constraints). Otherwise, if P1 is zero, the |
| 986 |
statement counter is incremented (immediate foreign key constraints).</td></tr> |
| 987 |
<tr><td valign="top" align="center"> |
| 988 |
<a name="FkIfZero"></a>FkIfZero |
| 989 |
<td>This opcode tests if a foreign key constraint-counter is currently zero. |
| 990 |
If so, jump to instruction P2. Otherwise, fall through to the next |
| 991 |
instruction.</p> |
| 992 |
|
| 993 |
<p>If P1 is non-zero, then the jump is taken if the database constraint-counter |
| 994 |
is zero (the one that counts deferred constraint violations). If P1 is |
| 995 |
zero, the jump is taken if the statement constraint-counter is zero |
| 996 |
(immediate foreign key constraint violations).</td></tr> |
| 997 |
<tr><td valign="top" align="center"> |
| 998 |
<a name="Found"></a>Found |
| 999 |
<td>If P4==0 then register P3 holds a blob constructed by <a href="opcode.html#MakeRecord">MakeRecord</a>. If |
| 1000 |
P4>0 then register P3 is the first of P4 registers that form an unpacked |
| 1001 |
record.</p> |
| 1002 |
|
| 1003 |
<p>Cursor P1 is on an index btree. If the record identified by P3 and P4 |
| 1004 |
is a prefix of any entry in P1 then a jump is made to P2 and |
| 1005 |
P1 is left pointing at the matching entry.</p> |
| 1006 |
|
| 1007 |
<p>This operation leaves the cursor in a state where it can be |
| 1008 |
advanced in the forward direction. The <a href="opcode.html#Next">Next</a> instruction will work, |
| 1009 |
but not the <a href="opcode.html#Prev">Prev</a> instruction.</p> |
| 1010 |
|
| 1011 |
<p>See also: <a href="opcode.html#NotFound">NotFound</a>, <a href="opcode.html#NoConflict">NoConflict</a>, <a href="opcode.html#NotExists">NotExists</a>. SeekGe</td></tr> |
| 1012 |
<tr><td valign="top" align="center"> |
| 1013 |
<a name="Function"></a>Function |
| 1014 |
<td>Invoke a user function (P4 is a pointer to an sqlite3_context object that |
| 1015 |
contains a pointer to the function to be run) with arguments taken |
| 1016 |
from register P2 and successors. The number of arguments is in |
| 1017 |
the sqlite3_context object that P4 points to. |
| 1018 |
The result of the function is stored |
| 1019 |
in register P3. Register P3 must not be one of the function inputs.</p> |
| 1020 |
|
| 1021 |
<p>P1 is a 32-bit bitmask indicating whether or not each argument to the |
| 1022 |
function was determined to be constant at compile time. If the first |
| 1023 |
argument was constant then bit 0 of P1 is set. This is used to determine |
| 1024 |
whether meta data associated with a user function argument using the |
| 1025 |
sqlite3_set_auxdata() API may be safely retained until the next |
| 1026 |
invocation of this opcode.</p> |
| 1027 |
|
| 1028 |
<p>See also: <a href="opcode.html#AggStep">AggStep</a>, <a href="opcode.html#AggFinal">AggFinal</a>, <a href="opcode.html#PureFunc">PureFunc</a></td></tr> |
| 1029 |
<tr><td valign="top" align="center"> |
| 1030 |
<a name="Ge"></a>Ge |
| 1031 |
<td>This works just like the Lt opcode except that the jump is taken if |
| 1032 |
the content of register P3 is greater than or equal to the content of |
| 1033 |
register P1. See the Lt opcode for additional information.</td></tr> |
| 1034 |
<tr><td valign="top" align="center"> |
| 1035 |
<a name="GetSubtype"></a>GetSubtype |
| 1036 |
<td>Extract the subtype value from register P1 and write that subtype |
| 1037 |
into register P2. If P1 has no subtype, then P1 gets a NULL.</td></tr> |
| 1038 |
<tr><td valign="top" align="center"> |
| 1039 |
<a name="Gosub"></a>Gosub |
| 1040 |
<td>Write the current address onto register P1 |
| 1041 |
and then jump to address P2.</td></tr> |
| 1042 |
<tr><td valign="top" align="center"> |
| 1043 |
<a name="Goto"></a>Goto |
| 1044 |
<td>An unconditional jump to address P2. |
| 1045 |
The next instruction executed will be |
| 1046 |
the one at index P2 from the beginning of |
| 1047 |
the program.</p> |
| 1048 |
|
| 1049 |
<p>The P1 parameter is not actually used by this opcode. However, it |
| 1050 |
is sometimes set to 1 instead of 0 as a hint to the command-line shell |
| 1051 |
that this <a href="opcode.html#Goto">Goto</a> is the bottom of a loop and that the lines from P2 down |
| 1052 |
to the current line should be indented for EXPLAIN output.</td></tr> |
| 1053 |
<tr><td valign="top" align="center"> |
| 1054 |
<a name="Gt"></a>Gt |
| 1055 |
<td>This works just like the Lt opcode except that the jump is taken if |
| 1056 |
the content of register P3 is greater than the content of |
| 1057 |
register P1. See the Lt opcode for additional information.</td></tr> |
| 1058 |
<tr><td valign="top" align="center"> |
| 1059 |
<a name="Halt"></a>Halt |
| 1060 |
<td>Exit immediately. All open cursors, etc are closed |
| 1061 |
automatically.</p> |
| 1062 |
|
| 1063 |
<p>P1 is the result code returned by sqlite3_exec(), sqlite3_reset(), |
| 1064 |
or sqlite3_finalize(). For a normal halt, this should be SQLITE_OK (0). |
| 1065 |
For errors, it can be some other value. If P1!=0 then P2 will determine |
| 1066 |
whether or not to rollback the current transaction. Do not rollback |
| 1067 |
if P2==OE_Fail. Do the rollback if P2==OE_Rollback. If P2==OE_Abort, |
| 1068 |
then back out all changes that have occurred during this execution of the |
| 1069 |
VDBE, but do not rollback the transaction.</p> |
| 1070 |
|
| 1071 |
<p>If P3 is not zero and P4 is NULL, then P3 is a register that holds the |
| 1072 |
text of an error message.</p> |
| 1073 |
|
| 1074 |
<p>If P3 is zero and P4 is not null then the error message string is held |
| 1075 |
in P4.</p> |
| 1076 |
|
| 1077 |
<p>P5 is a value between 1 and 4, inclusive, then the P4 error message |
| 1078 |
string is modified as follows:</p> |
| 1079 |
|
| 1080 |
<p>1: NOT NULL constraint failed: P4 |
| 1081 |
2: UNIQUE constraint failed: P4 |
| 1082 |
3: CHECK constraint failed: P4 |
| 1083 |
4: FOREIGN KEY constraint failed: P4</p> |
| 1084 |
|
| 1085 |
<p>If P3 is zero and P5 is not zero and P4 is NULL, then everything after |
| 1086 |
the ":" is omitted.</p> |
| 1087 |
|
| 1088 |
<p>There is an implied "<a href="opcode.html#Halt">Halt</a> 0 0 0" instruction inserted at the very end of |
| 1089 |
every program. So a jump past the last instruction of the program |
| 1090 |
is the same as executing <a href="opcode.html#Halt">Halt</a>.</td></tr> |
| 1091 |
<tr><td valign="top" align="center"> |
| 1092 |
<a name="HaltIfNull"></a>HaltIfNull |
| 1093 |
<td>Check the value in register P3. If it is NULL then <a href="opcode.html#Halt">Halt</a> using |
| 1094 |
parameter P1, P2, and P4 as if this were a <a href="opcode.html#Halt">Halt</a> instruction. If the |
| 1095 |
value in register P3 is not NULL, then this routine is a no-op. |
| 1096 |
The P5 parameter should be 1.</td></tr> |
| 1097 |
<tr><td valign="top" align="center"> |
| 1098 |
<a name="IdxDelete"></a>IdxDelete |
| 1099 |
<td>The content of P3 registers starting at register P2 form |
| 1100 |
an unpacked index key. This opcode removes that entry from the |
| 1101 |
index opened by cursor P1.</p> |
| 1102 |
|
| 1103 |
<p>P4 is a pointer to an Index structure.</p> |
| 1104 |
|
| 1105 |
<p>Raise an SQLITE_CORRUPT_INDEX error if no matching index entry is found |
| 1106 |
and not in writable_schema mode.</td></tr> |
| 1107 |
<tr><td valign="top" align="center"> |
| 1108 |
<a name="IdxGE"></a>IdxGE |
| 1109 |
<td>The P4 register values beginning with P3 form an unpacked index |
| 1110 |
key that omits the PRIMARY KEY. <a href="opcode.html#Compare">Compare</a> this key value against the index |
| 1111 |
that P1 is currently pointing to, ignoring the PRIMARY KEY or ROWID |
| 1112 |
fields at the end.</p> |
| 1113 |
|
| 1114 |
<p>If the P1 index entry is greater than or equal to the key value |
| 1115 |
then jump to P2. Otherwise fall through to the next instruction.</td></tr> |
| 1116 |
<tr><td valign="top" align="center"> |
| 1117 |
<a name="IdxGT"></a>IdxGT |
| 1118 |
<td>The P4 register values beginning with P3 form an unpacked index |
| 1119 |
key that omits the PRIMARY KEY. <a href="opcode.html#Compare">Compare</a> this key value against the index |
| 1120 |
that P1 is currently pointing to, ignoring the PRIMARY KEY or ROWID |
| 1121 |
fields at the end.</p> |
| 1122 |
|
| 1123 |
<p>If the P1 index entry is greater than the key value |
| 1124 |
then jump to P2. Otherwise fall through to the next instruction.</td></tr> |
| 1125 |
<tr><td valign="top" align="center"> |
| 1126 |
<a name="IdxInsert"></a>IdxInsert |
| 1127 |
<td>Register P2 holds an SQL index key made using the |
| 1128 |
<a href="opcode.html#MakeRecord">MakeRecord</a> instructions. This opcode writes that key |
| 1129 |
into the index P1. Data for the entry is nil.</p> |
| 1130 |
|
| 1131 |
<p>If P4 is not zero, then it is the number of values in the unpacked |
| 1132 |
key of reg(P2). In that case, P3 is the index of the first register |
| 1133 |
for the unpacked key. The availability of the unpacked key can sometimes |
| 1134 |
be an optimization.</p> |
| 1135 |
|
| 1136 |
<p>If P5 has the OPFLAG_APPEND bit set, that is a hint to the b-tree layer |
| 1137 |
that this insert is likely to be an append.</p> |
| 1138 |
|
| 1139 |
<p>If P5 has the OPFLAG_NCHANGE bit set, then the change counter is |
| 1140 |
incremented by this instruction. If the OPFLAG_NCHANGE bit is clear, |
| 1141 |
then the change counter is unchanged.</p> |
| 1142 |
|
| 1143 |
<p>If the OPFLAG_USESEEKRESULT flag of P5 is set, the implementation might |
| 1144 |
run faster by avoiding an unnecessary seek on cursor P1. However, |
| 1145 |
the OPFLAG_USESEEKRESULT flag must only be set if there have been no prior |
| 1146 |
seeks on the cursor or if the most recent seek used a key equivalent |
| 1147 |
to P2.</p> |
| 1148 |
|
| 1149 |
<p>This instruction only works for indices. The equivalent instruction |
| 1150 |
for tables is <a href="opcode.html#Insert">Insert</a>.</td></tr> |
| 1151 |
<tr><td valign="top" align="center"> |
| 1152 |
<a name="IdxLE"></a>IdxLE |
| 1153 |
<td>The P4 register values beginning with P3 form an unpacked index |
| 1154 |
key that omits the PRIMARY KEY or ROWID. <a href="opcode.html#Compare">Compare</a> this key value against |
| 1155 |
the index that P1 is currently pointing to, ignoring the PRIMARY KEY or |
| 1156 |
ROWID on the P1 index.</p> |
| 1157 |
|
| 1158 |
<p>If the P1 index entry is less than or equal to the key value then jump |
| 1159 |
to P2. Otherwise fall through to the next instruction.</td></tr> |
| 1160 |
<tr><td valign="top" align="center"> |
| 1161 |
<a name="IdxLT"></a>IdxLT |
| 1162 |
<td>The P4 register values beginning with P3 form an unpacked index |
| 1163 |
key that omits the PRIMARY KEY or ROWID. <a href="opcode.html#Compare">Compare</a> this key value against |
| 1164 |
the index that P1 is currently pointing to, ignoring the PRIMARY KEY or |
| 1165 |
ROWID on the P1 index.</p> |
| 1166 |
|
| 1167 |
<p>If the P1 index entry is less than the key value then jump to P2. |
| 1168 |
Otherwise fall through to the next instruction.</td></tr> |
| 1169 |
<tr><td valign="top" align="center"> |
| 1170 |
<a name="IdxRowid"></a>IdxRowid |
| 1171 |
<td>Write into register P2 an integer which is the last entry in the record at |
| 1172 |
the end of the index key pointed to by cursor P1. This integer should be |
| 1173 |
the rowid of the table entry to which this index entry points.</p> |
| 1174 |
|
| 1175 |
<p>See also: <a href="opcode.html#Rowid">Rowid</a>, <a href="opcode.html#MakeRecord">MakeRecord</a>.</td></tr> |
| 1176 |
<tr><td valign="top" align="center"> |
| 1177 |
<a name="If"></a>If |
| 1178 |
<td>Jump to P2 if the value in register P1 is true. The value |
| 1179 |
is considered true if it is numeric and non-zero. If the value |
| 1180 |
in P1 is NULL then take the jump if and only if P3 is non-zero.</td></tr> |
| 1181 |
<tr><td valign="top" align="center"> |
| 1182 |
<a name="IfEmpty"></a>IfEmpty |
| 1183 |
<td>Check to see if the b-tree table that cursor P1 references is empty |
| 1184 |
and jump to P2 if it is.</td></tr> |
| 1185 |
<tr><td valign="top" align="center"> |
| 1186 |
<a name="IFindKey"></a>IFindKey |
| 1187 |
<td>This instruction always follows an <a href="opcode.html#Found">Found</a> with the same P1, P2 and P3 |
| 1188 |
values as this instruction and a non-zero P4 value. The P4 value to |
| 1189 |
this opcode is of type P4_INDEX and contains a pointer to the Index |
| 1190 |
object of for the index being searched.</p> |
| 1191 |
|
| 1192 |
<p>This opcode uses sqlite3VdbeFindIndexKey() to search around the current |
| 1193 |
cursor location for an index key that exactly matches all fields that |
| 1194 |
are not indexed expressions or references to VIRTUAL generated columns, |
| 1195 |
and either exactly match or are real numbers that are within 2 ULPs of |
| 1196 |
each other if the don't match.</p> |
| 1197 |
|
| 1198 |
<p>To put it another way, this opcode looks for nearby index entries that |
| 1199 |
are very close to the search key, but which might have small differences |
| 1200 |
in floating-point values that come via an expression.</p> |
| 1201 |
|
| 1202 |
<p>If no nearby alternative entry is found in cursor P1, then jump to P2. |
| 1203 |
But if a close match is found, fall through.</p> |
| 1204 |
|
| 1205 |
<p>This opcode is used by PRAGMA integrity_check to help distinguish |
| 1206 |
between truely corrupt indexes and expression indexes that are holding |
| 1207 |
floating-point values that are off by one or two ULPs.</td></tr> |
| 1208 |
<tr><td valign="top" align="center"> |
| 1209 |
<a name="IfNoHope"></a>IfNoHope |
| 1210 |
<td>Register P3 is the first of P4 registers that form an unpacked |
| 1211 |
record. Cursor P1 is an index btree. P2 is a jump destination. |
| 1212 |
In other words, the operands to this opcode are the same as the |
| 1213 |
operands to <a href="opcode.html#NotFound">NotFound</a> and <a href="opcode.html#IdxGT">IdxGT</a>.</p> |
| 1214 |
|
| 1215 |
<p>This opcode is an optimization attempt only. If this opcode always |
| 1216 |
falls through, the correct answer is still obtained, but extra work |
| 1217 |
is performed.</p> |
| 1218 |
|
| 1219 |
<p>A value of N in the seekHit flag of cursor P1 means that there exists |
| 1220 |
a key P3:N that will match some record in the index. We want to know |
| 1221 |
if it is possible for a record P3:P4 to match some record in the |
| 1222 |
index. If it is not possible, we can skip some work. So if seekHit |
| 1223 |
is less than P4, attempt to find out if a match is possible by running |
| 1224 |
<a href="opcode.html#NotFound">NotFound</a>.</p> |
| 1225 |
|
| 1226 |
<p>This opcode is used in IN clause processing for a multi-column key. |
| 1227 |
If an IN clause is attached to an element of the key other than the |
| 1228 |
left-most element, and if there are no matches on the most recent |
| 1229 |
seek over the whole key, then it might be that one of the key element |
| 1230 |
to the left is prohibiting a match, and hence there is "no hope" of |
| 1231 |
any match regardless of how many IN clause elements are checked. |
| 1232 |
In such a case, we abandon the IN clause search early, using this |
| 1233 |
opcode. The opcode name comes from the fact that the |
| 1234 |
jump is taken if there is "no hope" of achieving a match.</p> |
| 1235 |
|
| 1236 |
<p>See also: <a href="opcode.html#NotFound">NotFound</a>, <a href="opcode.html#SeekHit">SeekHit</a></td></tr> |
| 1237 |
<tr><td valign="top" align="center"> |
| 1238 |
<a name="IfNot"></a>IfNot |
| 1239 |
<td>Jump to P2 if the value in register P1 is False. The value |
| 1240 |
is considered false if it has a numeric value of zero. If the value |
| 1241 |
in P1 is NULL then take the jump if and only if P3 is non-zero.</td></tr> |
| 1242 |
<tr><td valign="top" align="center"> |
| 1243 |
<a name="IfNotOpen"></a>IfNotOpen |
| 1244 |
<td>If cursor P1 is not open or if P1 is set to a NULL row using the |
| 1245 |
<a href="opcode.html#NullRow">NullRow</a> opcode, then jump to instruction P2. Otherwise, fall through.</td></tr> |
| 1246 |
<tr><td valign="top" align="center"> |
| 1247 |
<a name="IfNotZero"></a>IfNotZero |
| 1248 |
<td>Register P1 must contain an integer. If the content of register P1 is |
| 1249 |
initially greater than zero, then decrement the value in register P1. |
| 1250 |
If it is non-zero (negative or positive) and then also jump to P2. |
| 1251 |
If register P1 is initially zero, leave it unchanged and fall through.</td></tr> |
| 1252 |
<tr><td valign="top" align="center"> |
| 1253 |
<a name="IfNullRow"></a>IfNullRow |
| 1254 |
<td>Check the cursor P1 to see if it is currently pointing at a NULL row. |
| 1255 |
If it is, then set register P3 to NULL and jump immediately to P2. |
| 1256 |
If P1 is not on a NULL row, then fall through without making any |
| 1257 |
changes.</p> |
| 1258 |
|
| 1259 |
<p>If P1 is not an open cursor, then this opcode is a no-op.</td></tr> |
| 1260 |
<tr><td valign="top" align="center"> |
| 1261 |
<a name="IfPos"></a>IfPos |
| 1262 |
<td>Register P1 must contain an integer. |
| 1263 |
If the value of register P1 is 1 or greater, subtract P3 from the |
| 1264 |
value in P1 and jump to P2.</p> |
| 1265 |
|
| 1266 |
<p>If the initial value of register P1 is less than 1, then the |
| 1267 |
value is unchanged and control passes through to the next instruction.</td></tr> |
| 1268 |
<tr><td valign="top" align="center"> |
| 1269 |
<a name="IfSizeBetween"></a>IfSizeBetween |
| 1270 |
<td>Let N be the approximate number of rows in the table or index |
| 1271 |
with cursor P1 and let X be 10*log2(N) if N is positive or -1 |
| 1272 |
if N is zero.</p> |
| 1273 |
|
| 1274 |
<p>Jump to P2 if X is in between P3 and P4, inclusive.</td></tr> |
| 1275 |
<tr><td valign="top" align="center"> |
| 1276 |
<a name="IncrVacuum"></a>IncrVacuum |
| 1277 |
<td>Perform a single step of the incremental vacuum procedure on |
| 1278 |
the P1 database. If the vacuum has finished, jump to instruction |
| 1279 |
P2. Otherwise, fall through to the next instruction.</td></tr> |
| 1280 |
<tr><td valign="top" align="center"> |
| 1281 |
<a name="Init"></a>Init |
| 1282 |
<td>Programs contain a single instance of this opcode as the very first |
| 1283 |
opcode.</p> |
| 1284 |
|
| 1285 |
<p>If tracing is enabled (by the sqlite3_trace()) interface, then |
| 1286 |
the UTF-8 string contained in P4 is emitted on the trace callback. |
| 1287 |
Or if P4 is blank, use the string returned by sqlite3_sql().</p> |
| 1288 |
|
| 1289 |
<p>If P2 is not zero, jump to instruction P2.</p> |
| 1290 |
|
| 1291 |
<p>Increment the value of P1 so that <a href="opcode.html#Once">Once</a> opcodes will jump the |
| 1292 |
first time they are evaluated for this run.</p> |
| 1293 |
|
| 1294 |
<p>If P3 is not zero, then it is an address to jump to if an SQLITE_CORRUPT |
| 1295 |
error is encountered.</td></tr> |
| 1296 |
<tr><td valign="top" align="center"> |
| 1297 |
<a name="InitCoroutine"></a>InitCoroutine |
| 1298 |
<td>Set up register P1 so that it will <a href="opcode.html#Yield">Yield</a> to the coroutine |
| 1299 |
located at address P3.</p> |
| 1300 |
|
| 1301 |
<p>If P2!=0 then the coroutine implementation immediately follows |
| 1302 |
this opcode. So jump over the coroutine implementation to |
| 1303 |
address P2.</p> |
| 1304 |
|
| 1305 |
<p>See also: <a href="opcode.html#EndCoroutine">EndCoroutine</a></td></tr> |
| 1306 |
<tr><td valign="top" align="center"> |
| 1307 |
<a name="Insert"></a>Insert |
| 1308 |
<td>Write an entry into the table of cursor P1. A new entry is |
| 1309 |
created if it doesn't already exist or the data for an existing |
| 1310 |
entry is overwritten. The data is the value MEM_Blob stored in register |
| 1311 |
number P2. The key is stored in register P3. The key must |
| 1312 |
be a MEM_Int.</p> |
| 1313 |
|
| 1314 |
<p>If the OPFLAG_NCHANGE flag of P5 is set, then the row change count is |
| 1315 |
incremented (otherwise not). If the OPFLAG_LASTROWID flag of P5 is set, |
| 1316 |
then rowid is stored for subsequent return by the |
| 1317 |
sqlite3_last_insert_rowid() function (otherwise it is unmodified).</p> |
| 1318 |
|
| 1319 |
<p>If the OPFLAG_USESEEKRESULT flag of P5 is set, the implementation might |
| 1320 |
run faster by avoiding an unnecessary seek on cursor P1. However, |
| 1321 |
the OPFLAG_USESEEKRESULT flag must only be set if there have been no prior |
| 1322 |
seeks on the cursor or if the most recent seek used a key equal to P3.</p> |
| 1323 |
|
| 1324 |
<p>If the OPFLAG_ISUPDATE flag is set, then this opcode is part of an |
| 1325 |
UPDATE operation. Otherwise (if the flag is clear) then this opcode |
| 1326 |
is part of an INSERT operation. The difference is only important to |
| 1327 |
the update hook.</p> |
| 1328 |
|
| 1329 |
<p>Parameter P4 may point to a Table structure, or may be NULL. If it is |
| 1330 |
not NULL, then the update-hook (sqlite3.xUpdateCallback) is invoked |
| 1331 |
following a successful insert.</p> |
| 1332 |
|
| 1333 |
<p>(WARNING/TODO: If P1 is a pseudo-cursor and P2 is dynamically |
| 1334 |
allocated, then ownership of P2 is transferred to the pseudo-cursor |
| 1335 |
and register P2 becomes ephemeral. If the cursor is changed, the |
| 1336 |
value of register P2 will then change. Make sure this does not |
| 1337 |
cause any problems.)</p> |
| 1338 |
|
| 1339 |
<p>This instruction only works on tables. The equivalent instruction |
| 1340 |
for indices is <a href="opcode.html#IdxInsert">IdxInsert</a>.</td></tr> |
| 1341 |
<tr><td valign="top" align="center"> |
| 1342 |
<a name="Int64"></a>Int64 |
| 1343 |
<td>P4 is a pointer to a 64-bit integer value. |
| 1344 |
Write that value into register P2.</td></tr> |
| 1345 |
<tr><td valign="top" align="center"> |
| 1346 |
<a name="IntCopy"></a>IntCopy |
| 1347 |
<td>Transfer the integer value held in register P1 into register P2.</p> |
| 1348 |
|
| 1349 |
<p>This is an optimized version of <a href="opcode.html#SCopy">SCopy</a> that works only for integer |
| 1350 |
values.</td></tr> |
| 1351 |
<tr><td valign="top" align="center"> |
| 1352 |
<a name="Integer"></a>Integer |
| 1353 |
<td>The 32-bit integer value P1 is written into register P2.</td></tr> |
| 1354 |
<tr><td valign="top" align="center"> |
| 1355 |
<a name="IntegrityCk"></a>IntegrityCk |
| 1356 |
<td>Do an analysis of the currently open database. Store in |
| 1357 |
register (P1+1) the text of an error message describing any problems. |
| 1358 |
If no problems are found, store a NULL in register (P1+1).</p> |
| 1359 |
|
| 1360 |
<p>The register (P1) contains one less than the maximum number of allowed |
| 1361 |
errors. At most reg(P1) errors will be reported. |
| 1362 |
In other words, the analysis stops as soon as reg(P1) errors are |
| 1363 |
seen. Reg(P1) is updated with the number of errors remaining.</p> |
| 1364 |
|
| 1365 |
<p>The root page numbers of all tables in the database are integers |
| 1366 |
stored in P4_INTARRAY argument.</p> |
| 1367 |
|
| 1368 |
<p>If P5 is not zero, the check is done on the auxiliary database |
| 1369 |
file, not the main database file.</p> |
| 1370 |
|
| 1371 |
<p>This opcode is used to implement the integrity_check pragma.</td></tr> |
| 1372 |
<tr><td valign="top" align="center"> |
| 1373 |
<a name="IsNull"></a>IsNull |
| 1374 |
<td>Jump to P2 if the value in register P1 is NULL.</td></tr> |
| 1375 |
<tr><td valign="top" align="center"> |
| 1376 |
<a name="IsTrue"></a>IsTrue |
| 1377 |
<td>This opcode implements the IS TRUE, IS FALSE, IS NOT TRUE, and |
| 1378 |
IS NOT FALSE operators.</p> |
| 1379 |
|
| 1380 |
<p>Interpret the value in register P1 as a boolean value. Store that |
| 1381 |
boolean (a 0 or 1) in register P2. Or if the value in register P1 is |
| 1382 |
NULL, then the P3 is stored in register P2. Invert the answer if P4 |
| 1383 |
is 1.</p> |
| 1384 |
|
| 1385 |
<p>The logic is summarized like this:</p> |
| 1386 |
|
| 1387 |
<p><ul> |
| 1388 |
<li> If P3==0 and P4==0 then r[P2] := r[P1] IS TRUE |
| 1389 |
<li> If P3==1 and P4==1 then r[P2] := r[P1] IS FALSE |
| 1390 |
<li> If P3==0 and P4==1 then r[P2] := r[P1] IS NOT TRUE |
| 1391 |
<li> If P3==1 and P4==0 then r[P2] := r[P1] IS NOT FALSE |
| 1392 |
</ul></td></tr> |
| 1393 |
<tr><td valign="top" align="center"> |
| 1394 |
<a name="IsType"></a>IsType |
| 1395 |
<td>Jump to P2 if the type of a column in a btree is one of the types specified |
| 1396 |
by the P5 bitmask.</p> |
| 1397 |
|
| 1398 |
<p>P1 is normally a cursor on a btree for which the row decode cache is |
| 1399 |
valid through at least column P3. In other words, there should have been |
| 1400 |
a prior <a href="opcode.html#Column">Column</a> for column P3 or greater. If the cursor is not valid, |
| 1401 |
then this opcode might give spurious results. |
| 1402 |
The the btree row has fewer than P3 columns, then use P4 as the |
| 1403 |
datatype.</p> |
| 1404 |
|
| 1405 |
<p>If P1 is -1, then P3 is a register number and the datatype is taken |
| 1406 |
from the value in that register.</p> |
| 1407 |
|
| 1408 |
<p>P5 is a bitmask of data types. SQLITE_INTEGER is the least significant |
| 1409 |
(0x01) bit. SQLITE_FLOAT is the 0x02 bit. SQLITE_TEXT is 0x04. |
| 1410 |
SQLITE_BLOB is 0x08. SQLITE_NULL is 0x10.</p> |
| 1411 |
|
| 1412 |
<p>WARNING: This opcode does not reliably distinguish between NULL and REAL |
| 1413 |
when P1>=0. If the database contains a NaN value, this opcode will think |
| 1414 |
that the datatype is REAL when it should be NULL. When P1<0 and the value |
| 1415 |
is already stored in register P3, then this opcode does reliably |
| 1416 |
distinguish between NULL and REAL. The problem only arises then P1>=0.</p> |
| 1417 |
|
| 1418 |
<p>Take the jump to address P2 if and only if the datatype of the |
| 1419 |
value determined by P1 and P3 corresponds to one of the bits in the |
| 1420 |
P5 bitmask.</p></td></tr> |
| 1421 |
<tr><td valign="top" align="center"> |
| 1422 |
<a name="JournalMode"></a>JournalMode |
| 1423 |
<td>Change the journal mode of database P1 to P3. P3 must be one of the |
| 1424 |
PAGER_JOURNALMODE_XXX values. If changing between the various rollback |
| 1425 |
modes (delete, truncate, persist, off and memory), this is a simple |
| 1426 |
operation. No IO is required.</p> |
| 1427 |
|
| 1428 |
<p>If changing into or out of WAL mode the procedure is more complicated.</p> |
| 1429 |
|
| 1430 |
<p>Write a string containing the final journal-mode to register P2.</td></tr> |
| 1431 |
<tr><td valign="top" align="center"> |
| 1432 |
<a name="Jump"></a>Jump |
| 1433 |
<td>Jump to the instruction at address P1, P2, or P3 depending on whether |
| 1434 |
in the most recent <a href="opcode.html#Compare">Compare</a> instruction the P1 vector was less than, |
| 1435 |
equal to, or greater than the P2 vector, respectively.</p> |
| 1436 |
|
| 1437 |
<p>This opcode must immediately follow an <a href="opcode.html#Compare">Compare</a> opcode.</td></tr> |
| 1438 |
<tr><td valign="top" align="center"> |
| 1439 |
<a name="Last"></a>Last |
| 1440 |
<td>The next use of the <a href="opcode.html#Rowid">Rowid</a> or <a href="opcode.html#Column">Column</a> or <a href="opcode.html#Prev">Prev</a> instruction for P1 |
| 1441 |
will refer to the last entry in the database table or index. |
| 1442 |
If the table or index is empty and P2>0, then jump immediately to P2. |
| 1443 |
If P2 is 0 or if the table or index is not empty, fall through |
| 1444 |
to the following instruction.</p> |
| 1445 |
|
| 1446 |
<p>This opcode leaves the cursor configured to move in reverse order, |
| 1447 |
from the end toward the beginning. In other words, the cursor is |
| 1448 |
configured to use <a href="opcode.html#Prev">Prev</a>, not <a href="opcode.html#Next">Next</a>.</td></tr> |
| 1449 |
<tr><td valign="top" align="center"> |
| 1450 |
<a name="Le"></a>Le |
| 1451 |
<td>This works just like the Lt opcode except that the jump is taken if |
| 1452 |
the content of register P3 is less than or equal to the content of |
| 1453 |
register P1. See the Lt opcode for additional information.</td></tr> |
| 1454 |
<tr><td valign="top" align="center"> |
| 1455 |
<a name="LoadAnalysis"></a>LoadAnalysis |
| 1456 |
<td>Read the sqlite_stat1 table for database P1 and load the content |
| 1457 |
of that table into the internal index hash table. This will cause |
| 1458 |
the analysis to be used when preparing all subsequent queries.</td></tr> |
| 1459 |
<tr><td valign="top" align="center"> |
| 1460 |
<a name="Lt"></a>Lt |
| 1461 |
<td>Compare the values in register P1 and P3. If reg(P3)<reg(P1) then |
| 1462 |
jump to address P2.</p> |
| 1463 |
|
| 1464 |
<p>If the SQLITE_JUMPIFNULL bit of P5 is set and either reg(P1) or |
| 1465 |
reg(P3) is NULL then the take the jump. If the SQLITE_JUMPIFNULL |
| 1466 |
bit is clear then fall through if either operand is NULL.</p> |
| 1467 |
|
| 1468 |
<p>The SQLITE_AFF_MASK portion of P5 must be an affinity character - |
| 1469 |
SQLITE_AFF_TEXT, SQLITE_AFF_INTEGER, and so forth. An attempt is made |
| 1470 |
to coerce both inputs according to this affinity before the |
| 1471 |
comparison is made. If the SQLITE_AFF_MASK is 0x00, then numeric |
| 1472 |
affinity is used. Note that the affinity conversions are stored |
| 1473 |
back into the input registers P1 and P3. So this opcode can cause |
| 1474 |
persistent changes to registers P1 and P3.</p> |
| 1475 |
|
| 1476 |
<p>Once any conversions have taken place, and neither value is NULL, |
| 1477 |
the values are compared. If both values are blobs then memcmp() is |
| 1478 |
used to determine the results of the comparison. If both values |
| 1479 |
are text, then the appropriate collating function specified in |
| 1480 |
P4 is used to do the comparison. If P4 is not specified then |
| 1481 |
memcmp() is used to compare text string. If both values are |
| 1482 |
numeric, then a numeric comparison is used. If the two values |
| 1483 |
are of different types, then numbers are considered less than |
| 1484 |
strings and strings are considered less than blobs.</p> |
| 1485 |
|
| 1486 |
<p>This opcode saves the result of comparison for use by the new |
| 1487 |
<a href="opcode.html#Jump">Jump</a> opcode.</td></tr> |
| 1488 |
<tr><td valign="top" align="center"> |
| 1489 |
<a name="MakeRecord"></a>MakeRecord |
| 1490 |
<td>Convert P2 registers beginning with P1 into the <a href="fileformat2.html#record_format">record format</a> |
| 1491 |
use as a data record in a database table or as a key |
| 1492 |
in an index. The <a href="opcode.html#Column">Column</a> opcode can decode the record later.</p> |
| 1493 |
|
| 1494 |
<p>P4 may be a string that is P2 characters long. The N-th character of the |
| 1495 |
string indicates the column affinity that should be used for the N-th |
| 1496 |
field of the index key.</p> |
| 1497 |
|
| 1498 |
<p>The mapping from character to affinity is given by the SQLITE_AFF_ |
| 1499 |
macros defined in sqliteInt.h.</p> |
| 1500 |
|
| 1501 |
<p>If P4 is NULL then all index fields have the affinity BLOB.</p> |
| 1502 |
|
| 1503 |
<p>The meaning of P5 depends on whether or not the SQLITE_ENABLE_NULL_TRIM |
| 1504 |
compile-time option is enabled:</p> |
| 1505 |
|
| 1506 |
<p>* If SQLITE_ENABLE_NULL_TRIM is enabled, then the P5 is the index |
| 1507 |
of the right-most table that can be null-trimmed.</p> |
| 1508 |
|
| 1509 |
<p>* If SQLITE_ENABLE_NULL_TRIM is omitted, then P5 has the value |
| 1510 |
OPFLAG_NOCHNG_MAGIC if the <a href="opcode.html#MakeRecord">MakeRecord</a> opcode is allowed to |
| 1511 |
accept no-change records with serial_type 10. This value is |
| 1512 |
only used inside an assert() and does not affect the end result.</td></tr> |
| 1513 |
<tr><td valign="top" align="center"> |
| 1514 |
<a name="MaxPgcnt"></a>MaxPgcnt |
| 1515 |
<td>Try to set the maximum page count for database P1 to the value in P3. |
| 1516 |
Do not let the maximum page count fall below the current page count and |
| 1517 |
do not change the maximum page count value if P3==0.</p> |
| 1518 |
|
| 1519 |
<p>Store the maximum page count after the change in register P2.</td></tr> |
| 1520 |
<tr><td valign="top" align="center"> |
| 1521 |
<a name="MemMax"></a>MemMax |
| 1522 |
<td>P1 is a register in the root frame of this VM (the root frame is |
| 1523 |
different from the current frame if this instruction is being executed |
| 1524 |
within a sub-program). Set the value of register P1 to the maximum of |
| 1525 |
its current value and the value in register P2.</p> |
| 1526 |
|
| 1527 |
<p>This instruction throws an error if the memory cell is not initially |
| 1528 |
an integer.</td></tr> |
| 1529 |
<tr><td valign="top" align="center"> |
| 1530 |
<a name="Move"></a>Move |
| 1531 |
<td>Move the P3 values in register P1..P1+P3-1 over into |
| 1532 |
registers P2..P2+P3-1. Registers P1..P1+P3-1 are |
| 1533 |
left holding a NULL. It is an error for register ranges |
| 1534 |
P1..P1+P3-1 and P2..P2+P3-1 to overlap. It is an error |
| 1535 |
for P3 to be less than 1.</td></tr> |
| 1536 |
<tr><td valign="top" align="center"> |
| 1537 |
<a name="Multiply"></a>Multiply |
| 1538 |
<td>Multiply the value in register P1 by the value in register P2 |
| 1539 |
and store the result in register P3. |
| 1540 |
If either input is NULL, the result is NULL.</td></tr> |
| 1541 |
<tr><td valign="top" align="center"> |
| 1542 |
<a name="MustBeInt"></a>MustBeInt |
| 1543 |
<td>Force the value in register P1 to be an integer. If the value |
| 1544 |
in P1 is not an integer and cannot be converted into an integer |
| 1545 |
without data loss, then jump immediately to P2, or if P2==0 |
| 1546 |
raise an SQLITE_MISMATCH exception.</td></tr> |
| 1547 |
<tr><td valign="top" align="center"> |
| 1548 |
<a name="Ne"></a>Ne |
| 1549 |
<td>This works just like the Eq opcode except that the jump is taken if |
| 1550 |
the operands in registers P1 and P3 are not equal. See the Eq opcode for |
| 1551 |
additional information.</td></tr> |
| 1552 |
<tr><td valign="top" align="center"> |
| 1553 |
<a name="NewRowid"></a>NewRowid |
| 1554 |
<td>Get a new integer record number (a.k.a "rowid") used as the key to a table. |
| 1555 |
The record number is not previously used as a key in the database |
| 1556 |
table that cursor P1 points to. The new record number is written |
| 1557 |
written to register P2.</p> |
| 1558 |
|
| 1559 |
<p>If P3>0 then P3 is a register in the root frame of this VDBE that holds |
| 1560 |
the largest previously generated record number. No new record numbers are |
| 1561 |
allowed to be less than this value. When this value reaches its maximum, |
| 1562 |
an SQLITE_FULL error is generated. The P3 register is updated with the ' |
| 1563 |
generated record number. This P3 mechanism is used to help implement the |
| 1564 |
AUTOINCREMENT feature.</td></tr> |
| 1565 |
<tr><td valign="top" align="center"> |
| 1566 |
<a name="Next"></a>Next |
| 1567 |
<td>Advance cursor P1 so that it points to the next key/data pair in its |
| 1568 |
table or index. If there are no more key/value pairs then fall through |
| 1569 |
to the following instruction. But if the cursor advance was successful, |
| 1570 |
jump immediately to P2.</p> |
| 1571 |
|
| 1572 |
<p>The <a href="opcode.html#Next">Next</a> opcode is only valid following an <a href="opcode.html#SeekGT">SeekGT</a>, <a href="opcode.html#SeekGE">SeekGE</a>, or |
| 1573 |
<a href="opcode.html#Rewind">Rewind</a> opcode used to position the cursor. <a href="opcode.html#Next">Next</a> is not allowed |
| 1574 |
to follow <a href="opcode.html#SeekLT">SeekLT</a>, <a href="opcode.html#SeekLE">SeekLE</a>, or <a href="opcode.html#Last">Last</a>.</p> |
| 1575 |
|
| 1576 |
<p>The P1 cursor must be for a real table, not a pseudo-table. P1 must have |
| 1577 |
been opened prior to this opcode or the program will segfault.</p> |
| 1578 |
|
| 1579 |
<p>The P3 value is a hint to the btree implementation. If P3==1, that |
| 1580 |
means P1 is an SQL index and that this instruction could have been |
| 1581 |
omitted if that index had been unique. P3 is usually 0. P3 is |
| 1582 |
always either 0 or 1.</p> |
| 1583 |
|
| 1584 |
<p>If P5 is positive and the jump is taken, then event counter |
| 1585 |
number P5-1 in the prepared statement is incremented.</p> |
| 1586 |
|
| 1587 |
<p>See also: <a href="opcode.html#Prev">Prev</a></td></tr> |
| 1588 |
<tr><td valign="top" align="center"> |
| 1589 |
<a name="NoConflict"></a>NoConflict |
| 1590 |
<td>If P4==0 then register P3 holds a blob constructed by <a href="opcode.html#MakeRecord">MakeRecord</a>. If |
| 1591 |
P4>0 then register P3 is the first of P4 registers that form an unpacked |
| 1592 |
record.</p> |
| 1593 |
|
| 1594 |
<p>Cursor P1 is on an index btree. If the record identified by P3 and P4 |
| 1595 |
contains any NULL value, jump immediately to P2. If all terms of the |
| 1596 |
record are not-NULL then a check is done to determine if any row in the |
| 1597 |
P1 index btree has a matching key prefix. If there are no matches, jump |
| 1598 |
immediately to P2. If there is a match, fall through and leave the P1 |
| 1599 |
cursor pointing to the matching row.</p> |
| 1600 |
|
| 1601 |
<p>This opcode is similar to <a href="opcode.html#NotFound">NotFound</a> with the exceptions that the |
| 1602 |
branch is always taken if any part of the search key input is NULL.</p> |
| 1603 |
|
| 1604 |
<p>This operation leaves the cursor in a state where it cannot be |
| 1605 |
advanced in either direction. In other words, the <a href="opcode.html#Next">Next</a> and <a href="opcode.html#Prev">Prev</a> |
| 1606 |
opcodes do not work after this operation.</p> |
| 1607 |
|
| 1608 |
<p>See also: <a href="opcode.html#NotFound">NotFound</a>, <a href="opcode.html#Found">Found</a>, <a href="opcode.html#NotExists">NotExists</a></td></tr> |
| 1609 |
<tr><td valign="top" align="center"> |
| 1610 |
<a name="Noop"></a>Noop |
| 1611 |
<td>Do nothing. Continue downward to the next opcode.</td></tr> |
| 1612 |
<tr><td valign="top" align="center"> |
| 1613 |
<a name="Not"></a>Not |
| 1614 |
<td>Interpret the value in register P1 as a boolean value. Store the |
| 1615 |
boolean complement in register P2. If the value in register P1 is |
| 1616 |
NULL, then a NULL is stored in P2.</td></tr> |
| 1617 |
<tr><td valign="top" align="center"> |
| 1618 |
<a name="NotExists"></a>NotExists |
| 1619 |
<td>P1 is the index of a cursor open on an SQL table btree (with integer |
| 1620 |
keys). P3 is an integer rowid. If P1 does not contain a record with |
| 1621 |
rowid P3 then jump immediately to P2. Or, if P2 is 0, raise an |
| 1622 |
SQLITE_CORRUPT error. If P1 does contain a record with rowid P3 then |
| 1623 |
leave the cursor pointing at that record and fall through to the next |
| 1624 |
instruction.</p> |
| 1625 |
|
| 1626 |
<p>The <a href="opcode.html#SeekRowid">SeekRowid</a> opcode performs the same operation but also allows the |
| 1627 |
P3 register to contain a non-integer value, in which case the jump is |
| 1628 |
always taken. This opcode requires that P3 always contain an integer.</p> |
| 1629 |
|
| 1630 |
<p>The <a href="opcode.html#NotFound">NotFound</a> opcode performs the same operation on index btrees |
| 1631 |
(with arbitrary multi-value keys).</p> |
| 1632 |
|
| 1633 |
<p>This opcode leaves the cursor in a state where it cannot be advanced |
| 1634 |
in either direction. In other words, the <a href="opcode.html#Next">Next</a> and <a href="opcode.html#Prev">Prev</a> opcodes will |
| 1635 |
not work following this opcode.</p> |
| 1636 |
|
| 1637 |
<p>See also: <a href="opcode.html#Found">Found</a>, <a href="opcode.html#NotFound">NotFound</a>, <a href="opcode.html#NoConflict">NoConflict</a>, <a href="opcode.html#SeekRowid">SeekRowid</a></td></tr> |
| 1638 |
<tr><td valign="top" align="center"> |
| 1639 |
<a name="NotFound"></a>NotFound |
| 1640 |
<td>If P4==0 then register P3 holds a blob constructed by <a href="opcode.html#MakeRecord">MakeRecord</a>. If |
| 1641 |
P4>0 then register P3 is the first of P4 registers that form an unpacked |
| 1642 |
record.</p> |
| 1643 |
|
| 1644 |
<p>Cursor P1 is on an index btree. If the record identified by P3 and P4 |
| 1645 |
is not the prefix of any entry in P1 then a jump is made to P2. If P1 |
| 1646 |
does contain an entry whose prefix matches the P3/P4 record then control |
| 1647 |
falls through to the next instruction and P1 is left pointing at the |
| 1648 |
matching entry.</p> |
| 1649 |
|
| 1650 |
<p>This operation leaves the cursor in a state where it cannot be |
| 1651 |
advanced in either direction. In other words, the <a href="opcode.html#Next">Next</a> and <a href="opcode.html#Prev">Prev</a> |
| 1652 |
opcodes do not work after this operation.</p> |
| 1653 |
|
| 1654 |
<p>See also: <a href="opcode.html#Found">Found</a>, <a href="opcode.html#NotExists">NotExists</a>, <a href="opcode.html#NoConflict">NoConflict</a>, <a href="opcode.html#IfNoHope">IfNoHope</a></td></tr> |
| 1655 |
<tr><td valign="top" align="center"> |
| 1656 |
<a name="NotNull"></a>NotNull |
| 1657 |
<td>Jump to P2 if the value in register P1 is not NULL.</td></tr> |
| 1658 |
<tr><td valign="top" align="center"> |
| 1659 |
<a name="Null"></a>Null |
| 1660 |
<td>Write a NULL into registers P2. If P3 greater than P2, then also write |
| 1661 |
NULL into register P3 and every register in between P2 and P3. If P3 |
| 1662 |
is less than P2 (typically P3 is zero) then only register P2 is |
| 1663 |
set to NULL.</p> |
| 1664 |
|
| 1665 |
<p>If the P1 value is non-zero, then also set the MEM_Cleared flag so that |
| 1666 |
NULL values will not compare equal even if SQLITE_NULLEQ is set on |
| 1667 |
<a href="opcode.html#Ne">Ne</a> or <a href="opcode.html#Eq">Eq</a>.</td></tr> |
| 1668 |
<tr><td valign="top" align="center"> |
| 1669 |
<a name="NullRow"></a>NullRow |
| 1670 |
<td>Move the cursor P1 to a null row. Any <a href="opcode.html#Column">Column</a> operations |
| 1671 |
that occur while the cursor is on the null row will always |
| 1672 |
write a NULL.</p> |
| 1673 |
|
| 1674 |
<p>If cursor P1 is not previously opened, open it now to a special |
| 1675 |
pseudo-cursor that always returns NULL for every column.</td></tr> |
| 1676 |
<tr><td valign="top" align="center"> |
| 1677 |
<a name="Offset"></a>Offset |
| 1678 |
<td>Store in register r[P3] the byte offset into the database file that is the |
| 1679 |
start of the payload for the record at which that cursor P1 is currently |
| 1680 |
pointing.</p> |
| 1681 |
|
| 1682 |
<p>P2 is the column number for the argument to the sqlite_offset() function. |
| 1683 |
This opcode does not use P2 itself, but the P2 value is used by the |
| 1684 |
code generator. The P1, P2, and P3 operands to this opcode are the |
| 1685 |
same as for <a href="opcode.html#Column">Column</a>.</p> |
| 1686 |
|
| 1687 |
<p>This opcode is only available if SQLite is compiled with the |
| 1688 |
-DSQLITE_ENABLE_OFFSET_SQL_FUNC option.</td></tr> |
| 1689 |
<tr><td valign="top" align="center"> |
| 1690 |
<a name="OffsetLimit"></a>OffsetLimit |
| 1691 |
<td>This opcode performs a commonly used computation associated with |
| 1692 |
LIMIT and OFFSET processing. r[P1] holds the limit counter. r[P3] |
| 1693 |
holds the offset counter. The opcode computes the combined value |
| 1694 |
of the LIMIT and OFFSET and stores that value in r[P2]. The r[P2] |
| 1695 |
value computed is the total number of rows that will need to be |
| 1696 |
visited in order to complete the query.</p> |
| 1697 |
|
| 1698 |
<p>If r[P3] is zero or negative, that means there is no OFFSET |
| 1699 |
and r[P2] is set to be the value of the LIMIT, r[P1].</p> |
| 1700 |
|
| 1701 |
<p>if r[P1] is zero or negative, that means there is no LIMIT |
| 1702 |
and r[P2] is set to -1.</p> |
| 1703 |
|
| 1704 |
<p>Otherwise, r[P2] is set to the sum of r[P1] and r[P3].</td></tr> |
| 1705 |
<tr><td valign="top" align="center"> |
| 1706 |
<a name="Once"></a>Once |
| 1707 |
<td>Fall through to the next instruction the first time this opcode is |
| 1708 |
encountered on each invocation of the byte-code program. <a href="opcode.html#Jump">Jump</a> to P2 |
| 1709 |
on the second and all subsequent encounters during the same invocation.</p> |
| 1710 |
|
| 1711 |
<p>Top-level programs determine first invocation by comparing the P1 |
| 1712 |
operand against the P1 operand on the <a href="opcode.html#Init">Init</a> opcode at the beginning |
| 1713 |
of the program. If the P1 values differ, then fall through and make |
| 1714 |
the P1 of this opcode equal to the P1 of <a href="opcode.html#Init">Init</a>. If P1 values are |
| 1715 |
the same then take the jump.</p> |
| 1716 |
|
| 1717 |
<p>For subprograms, there is a bitmask in the VdbeFrame that determines |
| 1718 |
whether or not the jump should be taken. The bitmask is necessary |
| 1719 |
because the self-altering code trick does not work for recursive |
| 1720 |
triggers.</p> |
| 1721 |
|
| 1722 |
<p>The P3 operand is not used directly by this opcode. However P3 is |
| 1723 |
used by the code generator as follows: If this opcode is the start |
| 1724 |
of a subroutine and that subroutine uses a Bloom filter, then P3 will |
| 1725 |
be the register that holds that Bloom filter. See tag-202407032019 |
| 1726 |
in the source code for implementation details.</td></tr> |
| 1727 |
<tr><td valign="top" align="center"> |
| 1728 |
<a name="OpenAutoindex"></a>OpenAutoindex |
| 1729 |
<td>This opcode works the same as <a href="opcode.html#OpenEphemeral">OpenEphemeral</a>. It has a |
| 1730 |
different name to distinguish its use. Tables created using |
| 1731 |
by this opcode will be used for automatically created transient |
| 1732 |
indices in joins.</td></tr> |
| 1733 |
<tr><td valign="top" align="center"> |
| 1734 |
<a name="OpenDup"></a>OpenDup |
| 1735 |
<td>Open a new cursor P1 that points to the same ephemeral table as |
| 1736 |
cursor P2. The P2 cursor must have been opened by a prior <a href="opcode.html#OpenEphemeral">OpenEphemeral</a> |
| 1737 |
opcode. Only ephemeral cursors may be duplicated.</p> |
| 1738 |
|
| 1739 |
<p>Duplicate ephemeral cursors are used for self-joins of materialized views.</td></tr> |
| 1740 |
<tr><td valign="top" align="center"> |
| 1741 |
<a name="OpenEphemeral"></a>OpenEphemeral |
| 1742 |
<td>Open a new cursor P1 to a transient table. |
| 1743 |
The cursor is always opened read/write even if |
| 1744 |
the main database is read-only. The ephemeral |
| 1745 |
table is deleted automatically when the cursor is closed.</p> |
| 1746 |
|
| 1747 |
<p>If the cursor P1 is already opened on an ephemeral table, the table |
| 1748 |
is cleared (all content is erased).</p> |
| 1749 |
|
| 1750 |
<p>P2 is the number of columns in the ephemeral table. |
| 1751 |
The cursor points to a BTree table if P4==0 and to a BTree index |
| 1752 |
if P4 is not 0. If P4 is not NULL, it points to a KeyInfo structure |
| 1753 |
that defines the format of keys in the index.</p> |
| 1754 |
|
| 1755 |
<p>The P5 parameter can be a mask of the BTREE_* flags defined |
| 1756 |
in btree.h. These flags control aspects of the operation of |
| 1757 |
the btree. The BTREE_OMIT_JOURNAL and BTREE_SINGLE flags are |
| 1758 |
added automatically.</p> |
| 1759 |
|
| 1760 |
<p>If P3 is positive, then reg[P3] is modified slightly so that it |
| 1761 |
can be used as zero-length data for <a href="opcode.html#Insert">Insert</a>. This is an optimization |
| 1762 |
that avoids an extra <a href="opcode.html#Blob">Blob</a> opcode to initialize that register.</td></tr> |
| 1763 |
<tr><td valign="top" align="center"> |
| 1764 |
<a name="OpenPseudo"></a>OpenPseudo |
| 1765 |
<td>Open a new cursor that points to a fake table that contains a single |
| 1766 |
row of data. The content of that one row is the content of memory |
| 1767 |
register P2. In other words, cursor P1 becomes an alias for the |
| 1768 |
MEM_Blob content contained in register P2.</p> |
| 1769 |
|
| 1770 |
<p>A pseudo-table created by this opcode is used to hold a single |
| 1771 |
row output from the sorter so that the row can be decomposed into |
| 1772 |
individual columns using the <a href="opcode.html#Column">Column</a> opcode. The <a href="opcode.html#Column">Column</a> opcode |
| 1773 |
is the only cursor opcode that works with a pseudo-table.</p> |
| 1774 |
|
| 1775 |
<p>P3 is the number of fields in the records that will be stored by |
| 1776 |
the pseudo-table. If P2 is 0 or negative then the pseudo-cursor |
| 1777 |
will return NULL for every column.</td></tr> |
| 1778 |
<tr><td valign="top" align="center"> |
| 1779 |
<a name="OpenRead"></a>OpenRead |
| 1780 |
<td>Open a read-only cursor for the database table whose root page is |
| 1781 |
P2 in a database file. The database file is determined by P3. |
| 1782 |
P3==0 means the main database, P3==1 means the database used for |
| 1783 |
temporary tables, and P3>1 means used the corresponding attached |
| 1784 |
database. Give the new cursor an identifier of P1. The P1 |
| 1785 |
values need not be contiguous but all P1 values should be small integers. |
| 1786 |
It is an error for P1 to be negative.</p> |
| 1787 |
|
| 1788 |
<p>Allowed P5 bits: |
| 1789 |
<ul> |
| 1790 |
<li> <b>0x02 OPFLAG_SEEKEQ</b>: This cursor will only be used for |
| 1791 |
equality lookups (implemented as a pair of opcodes <a href="opcode.html#SeekGE">SeekGE</a>/<a href="opcode.html#IdxGT">IdxGT</a> |
| 1792 |
of <a href="opcode.html#SeekLE">SeekLE</a>/<a href="opcode.html#IdxLT">IdxLT</a>) |
| 1793 |
</ul></p> |
| 1794 |
|
| 1795 |
<p>The P4 value may be either an integer (P4_INT32) or a pointer to |
| 1796 |
a KeyInfo structure (P4_KEYINFO). If it is a pointer to a KeyInfo |
| 1797 |
object, then table being opened must be an <a href="fileformat2.html#btypes">index b-tree</a> where the |
| 1798 |
KeyInfo object defines the content and collating |
| 1799 |
sequence of that index b-tree. Otherwise, if P4 is an integer |
| 1800 |
value, then the table being opened must be a <a href="fileformat2.html#btypes">table b-tree</a> with a |
| 1801 |
number of columns no less than the value of P4.</p> |
| 1802 |
|
| 1803 |
<p>See also: <a href="opcode.html#OpenWrite">OpenWrite</a>, <a href="opcode.html#ReopenIdx">ReopenIdx</a></td></tr> |
| 1804 |
<tr><td valign="top" align="center"> |
| 1805 |
<a name="OpenWrite"></a>OpenWrite |
| 1806 |
<td>Open a read/write cursor named P1 on the table or index whose root |
| 1807 |
page is P2 (or whose root page is held in register P2 if the |
| 1808 |
OPFLAG_P2ISREG bit is set in P5 - see below).</p> |
| 1809 |
|
| 1810 |
<p>The P4 value may be either an integer (P4_INT32) or a pointer to |
| 1811 |
a KeyInfo structure (P4_KEYINFO). If it is a pointer to a KeyInfo |
| 1812 |
object, then table being opened must be an <a href="fileformat2.html#btypes">index b-tree</a> where the |
| 1813 |
KeyInfo object defines the content and collating |
| 1814 |
sequence of that index b-tree. Otherwise, if P4 is an integer |
| 1815 |
value, then the table being opened must be a <a href="fileformat2.html#btypes">table b-tree</a> with a |
| 1816 |
number of columns no less than the value of P4.</p> |
| 1817 |
|
| 1818 |
<p>Allowed P5 bits: |
| 1819 |
<ul> |
| 1820 |
<li> <b>0x02 OPFLAG_SEEKEQ</b>: This cursor will only be used for |
| 1821 |
equality lookups (implemented as a pair of opcodes <a href="opcode.html#SeekGE">SeekGE</a>/<a href="opcode.html#IdxGT">IdxGT</a> |
| 1822 |
of <a href="opcode.html#SeekLE">SeekLE</a>/<a href="opcode.html#IdxLT">IdxLT</a>) |
| 1823 |
<li> <b>0x08 OPFLAG_FORDELETE</b>: This cursor is used only to seek |
| 1824 |
and subsequently delete entries in an index btree. This is a |
| 1825 |
hint to the storage engine that the storage engine is allowed to |
| 1826 |
ignore. The hint is not used by the official SQLite b*tree storage |
| 1827 |
engine, but is used by COMDB2. |
| 1828 |
<li> <b>0x10 OPFLAG_P2ISREG</b>: Use the content of register P2 |
| 1829 |
as the root page, not the value of P2 itself. |
| 1830 |
</ul></p> |
| 1831 |
|
| 1832 |
<p>This instruction works like <a href="opcode.html#OpenRead">OpenRead</a> except that it opens the cursor |
| 1833 |
in read/write mode.</p> |
| 1834 |
|
| 1835 |
<p>See also: <a href="opcode.html#OpenRead">OpenRead</a>, <a href="opcode.html#ReopenIdx">ReopenIdx</a></td></tr> |
| 1836 |
<tr><td valign="top" align="center"> |
| 1837 |
<a name="Or"></a>Or |
| 1838 |
<td>Take the logical OR of the values in register P1 and P2 and |
| 1839 |
store the answer in register P3.</p> |
| 1840 |
|
| 1841 |
<p>If either P1 or P2 is nonzero (true) then the result is 1 (true) |
| 1842 |
even if the other input is NULL. A NULL and false or two NULLs |
| 1843 |
give a NULL output.</td></tr> |
| 1844 |
<tr><td valign="top" align="center"> |
| 1845 |
<a name="Pagecount"></a>Pagecount |
| 1846 |
<td>Write the current number of pages in database P1 to memory cell P2.</td></tr> |
| 1847 |
<tr><td valign="top" align="center"> |
| 1848 |
<a name="Param"></a>Param |
| 1849 |
<td>This opcode is only ever present in sub-programs called via the |
| 1850 |
<a href="opcode.html#Program">Program</a> instruction. <a href="opcode.html#Copy">Copy</a> a value currently stored in a memory |
| 1851 |
cell of the calling (parent) frame to cell P2 in the current frames |
| 1852 |
address space. This is used by trigger programs to access the new.* |
| 1853 |
and old.* values.</p> |
| 1854 |
|
| 1855 |
<p>The address of the cell in the parent frame is determined by adding |
| 1856 |
the value of the P1 argument to the value of the P1 argument to the |
| 1857 |
calling <a href="opcode.html#Program">Program</a> instruction.</td></tr> |
| 1858 |
<tr><td valign="top" align="center"> |
| 1859 |
<a name="ParseSchema"></a>ParseSchema |
| 1860 |
<td>Read and parse all entries from the schema table of database P1 |
| 1861 |
that match the WHERE clause P4. If P4 is a NULL pointer, then the |
| 1862 |
entire schema for P1 is reparsed.</p> |
| 1863 |
|
| 1864 |
<p>This opcode invokes the parser to create a new virtual machine, |
| 1865 |
then runs the new virtual machine. It is thus a re-entrant opcode.</td></tr> |
| 1866 |
<tr><td valign="top" align="center"> |
| 1867 |
<a name="Permutation"></a>Permutation |
| 1868 |
<td>Set the permutation used by the <a href="opcode.html#Compare">Compare</a> operator in the next |
| 1869 |
instruction. The permutation is stored in the P4 operand.</p> |
| 1870 |
|
| 1871 |
<p>The permutation is only valid for the next opcode which must be |
| 1872 |
an <a href="opcode.html#Compare">Compare</a> that has the OPFLAG_PERMUTE bit set in P5.</p> |
| 1873 |
|
| 1874 |
<p>The first integer in the P4 integer array is the length of the array |
| 1875 |
and does not become part of the permutation.</td></tr> |
| 1876 |
<tr><td valign="top" align="center"> |
| 1877 |
<a name="Prev"></a>Prev |
| 1878 |
<td>Back up cursor P1 so that it points to the previous key/data pair in its |
| 1879 |
table or index. If there is no previous key/value pairs then fall through |
| 1880 |
to the following instruction. But if the cursor backup was successful, |
| 1881 |
jump immediately to P2.</p> |
| 1882 |
|
| 1883 |
<p>The <a href="opcode.html#Prev">Prev</a> opcode is only valid following an <a href="opcode.html#SeekLT">SeekLT</a>, <a href="opcode.html#SeekLE">SeekLE</a>, or |
| 1884 |
<a href="opcode.html#Last">Last</a> opcode used to position the cursor. <a href="opcode.html#Prev">Prev</a> is not allowed |
| 1885 |
to follow <a href="opcode.html#SeekGT">SeekGT</a>, <a href="opcode.html#SeekGE">SeekGE</a>, or <a href="opcode.html#Rewind">Rewind</a>.</p> |
| 1886 |
|
| 1887 |
<p>The P1 cursor must be for a real table, not a pseudo-table. If P1 is |
| 1888 |
not open then the behavior is undefined.</p> |
| 1889 |
|
| 1890 |
<p>The P3 value is a hint to the btree implementation. If P3==1, that |
| 1891 |
means P1 is an SQL index and that this instruction could have been |
| 1892 |
omitted if that index had been unique. P3 is usually 0. P3 is |
| 1893 |
always either 0 or 1.</p> |
| 1894 |
|
| 1895 |
<p>If P5 is positive and the jump is taken, then event counter |
| 1896 |
number P5-1 in the prepared statement is incremented.</td></tr> |
| 1897 |
<tr><td valign="top" align="center"> |
| 1898 |
<a name="Program"></a>Program |
| 1899 |
<td>Execute the trigger program passed as P4 (type P4_SUBPROGRAM).</p> |
| 1900 |
|
| 1901 |
<p>P1 contains the address of the memory cell that contains the first memory |
| 1902 |
cell in an array of values used as arguments to the sub-program. P2 |
| 1903 |
contains the address to jump to if the sub-program throws an IGNORE |
| 1904 |
exception using the RAISE() function. P2 might be zero, if there is |
| 1905 |
no possibility that an IGNORE exception will be raised. |
| 1906 |
Register P3 contains the address |
| 1907 |
of a memory cell in this (the parent) VM that is used to allocate the |
| 1908 |
memory required by the sub-vdbe at runtime.</p> |
| 1909 |
|
| 1910 |
<p>P4 is a pointer to the VM containing the trigger program.</p> |
| 1911 |
|
| 1912 |
<p>If P5 is non-zero, then recursive program invocation is enabled.</td></tr> |
| 1913 |
<tr><td valign="top" align="center"> |
| 1914 |
<a name="PureFunc"></a>PureFunc |
| 1915 |
<td>Invoke a user function (P4 is a pointer to an sqlite3_context object that |
| 1916 |
contains a pointer to the function to be run) with arguments taken |
| 1917 |
from register P2 and successors. The number of arguments is in |
| 1918 |
the sqlite3_context object that P4 points to. |
| 1919 |
The result of the function is stored |
| 1920 |
in register P3. Register P3 must not be one of the function inputs.</p> |
| 1921 |
|
| 1922 |
<p>P1 is a 32-bit bitmask indicating whether or not each argument to the |
| 1923 |
function was determined to be constant at compile time. If the first |
| 1924 |
argument was constant then bit 0 of P1 is set. This is used to determine |
| 1925 |
whether meta data associated with a user function argument using the |
| 1926 |
sqlite3_set_auxdata() API may be safely retained until the next |
| 1927 |
invocation of this opcode.</p> |
| 1928 |
|
| 1929 |
<p>This opcode works exactly like <a href="opcode.html#Function">Function</a>. The only difference is in |
| 1930 |
its name. This opcode is used in places where the function must be |
| 1931 |
purely non-deterministic. Some built-in date/time functions can be |
| 1932 |
either deterministic of non-deterministic, depending on their arguments. |
| 1933 |
When those function are used in a non-deterministic way, they will check |
| 1934 |
to see if they were called using <a href="opcode.html#PureFunc">PureFunc</a> instead of <a href="opcode.html#Function">Function</a>, and |
| 1935 |
if they were, they throw an error.</p> |
| 1936 |
|
| 1937 |
<p>See also: <a href="opcode.html#AggStep">AggStep</a>, <a href="opcode.html#AggFinal">AggFinal</a>, <a href="opcode.html#Function">Function</a></td></tr> |
| 1938 |
<tr><td valign="top" align="center"> |
| 1939 |
<a name="ReadCookie"></a>ReadCookie |
| 1940 |
<td>Read cookie number P3 from database P1 and write it into register P2. |
| 1941 |
P3==1 is the schema version. P3==2 is the database format. |
| 1942 |
P3==3 is the recommended pager cache size, and so forth. P1==0 is |
| 1943 |
the main database file and P1==1 is the database file used to store |
| 1944 |
temporary tables.</p> |
| 1945 |
|
| 1946 |
<p>There must be a read-lock on the database (either a transaction |
| 1947 |
must be started or there must be an open cursor) before |
| 1948 |
executing this instruction.</td></tr> |
| 1949 |
<tr><td valign="top" align="center"> |
| 1950 |
<a name="Real"></a>Real |
| 1951 |
<td>P4 is a pointer to a 64-bit floating point value. |
| 1952 |
Write that value into register P2.</td></tr> |
| 1953 |
<tr><td valign="top" align="center"> |
| 1954 |
<a name="RealAffinity"></a>RealAffinity |
| 1955 |
<td>If register P1 holds an integer convert it to a real value.</p> |
| 1956 |
|
| 1957 |
<p>This opcode is used when extracting information from a column that |
| 1958 |
has REAL affinity. Such column values may still be stored as |
| 1959 |
integers, for space efficiency, but after extraction we want them |
| 1960 |
to have only a real value.</td></tr> |
| 1961 |
<tr><td valign="top" align="center"> |
| 1962 |
<a name="ReleaseReg"></a>ReleaseReg |
| 1963 |
<td>Release registers from service. Any content that was in the |
| 1964 |
the registers is unreliable after this opcode completes.</p> |
| 1965 |
|
| 1966 |
<p>The registers released will be the P2 registers starting at P1, |
| 1967 |
except if bit ii of P3 set, then do not release register P1+ii. |
| 1968 |
In other words, P3 is a mask of registers to preserve.</p> |
| 1969 |
|
| 1970 |
<p>Releasing a register clears the Mem.pScopyFrom pointer. That means |
| 1971 |
that if the content of the released register was set using <a href="opcode.html#SCopy">SCopy</a>, |
| 1972 |
a change to the value of the source register for the <a href="opcode.html#SCopy">SCopy</a> will no longer |
| 1973 |
generate an assertion fault in sqlite3VdbeMemAboutToChange().</p> |
| 1974 |
|
| 1975 |
<p>If P5 is set, then all released registers have their type set |
| 1976 |
to MEM_Undefined so that any subsequent attempt to read the released |
| 1977 |
register (before it is reinitialized) will generate an assertion fault.</p> |
| 1978 |
|
| 1979 |
<p>P5 ought to be set on every call to this opcode. |
| 1980 |
However, there are places in the code generator will release registers |
| 1981 |
before their are used, under the (valid) assumption that the registers |
| 1982 |
will not be reallocated for some other purpose before they are used and |
| 1983 |
hence are safe to release.</p> |
| 1984 |
|
| 1985 |
<p>This opcode is only available in testing and debugging builds. It is |
| 1986 |
not generated for release builds. The purpose of this opcode is to help |
| 1987 |
validate the generated bytecode. This opcode does not actually contribute |
| 1988 |
to computing an answer.</td></tr> |
| 1989 |
<tr><td valign="top" align="center"> |
| 1990 |
<a name="Remainder"></a>Remainder |
| 1991 |
<td>Compute the remainder after integer register P2 is divided by |
| 1992 |
register P1 and store the result in register P3. |
| 1993 |
If the value in register P1 is zero the result is NULL. |
| 1994 |
If either operand is NULL, the result is NULL.</td></tr> |
| 1995 |
<tr><td valign="top" align="center"> |
| 1996 |
<a name="ReopenIdx"></a>ReopenIdx |
| 1997 |
<td>The <a href="opcode.html#ReopenIdx">ReopenIdx</a> opcode works like <a href="opcode.html#OpenRead">OpenRead</a> except that it first |
| 1998 |
checks to see if the cursor on P1 is already open on the same |
| 1999 |
b-tree and if it is this opcode becomes a no-op. In other words, |
| 2000 |
if the cursor is already open, do not reopen it.</p> |
| 2001 |
|
| 2002 |
<p>The <a href="opcode.html#ReopenIdx">ReopenIdx</a> opcode may only be used with P5==0 or P5==OPFLAG_SEEKEQ |
| 2003 |
and with P4 being a P4_KEYINFO object. Furthermore, the P3 value must |
| 2004 |
be the same as every other <a href="opcode.html#ReopenIdx">ReopenIdx</a> or <a href="opcode.html#OpenRead">OpenRead</a> for the same cursor |
| 2005 |
number.</p> |
| 2006 |
|
| 2007 |
<p>Allowed P5 bits: |
| 2008 |
<ul> |
| 2009 |
<li> <b>0x02 OPFLAG_SEEKEQ</b>: This cursor will only be used for |
| 2010 |
equality lookups (implemented as a pair of opcodes <a href="opcode.html#SeekGE">SeekGE</a>/<a href="opcode.html#IdxGT">IdxGT</a> |
| 2011 |
of <a href="opcode.html#SeekLE">SeekLE</a>/<a href="opcode.html#IdxLT">IdxLT</a>) |
| 2012 |
</ul></p> |
| 2013 |
|
| 2014 |
<p>See also: <a href="opcode.html#OpenRead">OpenRead</a>, <a href="opcode.html#OpenWrite">OpenWrite</a></td></tr> |
| 2015 |
<tr><td valign="top" align="center"> |
| 2016 |
<a name="ResetCount"></a>ResetCount |
| 2017 |
<td>The value of the change counter is copied to the database handle |
| 2018 |
change counter (returned by subsequent calls to sqlite3_changes()). |
| 2019 |
Then the VMs internal change counter resets to 0. |
| 2020 |
This is used by trigger programs.</td></tr> |
| 2021 |
<tr><td valign="top" align="center"> |
| 2022 |
<a name="ResetSorter"></a>ResetSorter |
| 2023 |
<td>Delete all contents from the ephemeral table or sorter |
| 2024 |
that is open on cursor P1.</p> |
| 2025 |
|
| 2026 |
<p>This opcode only works for cursors used for sorting and |
| 2027 |
opened with <a href="opcode.html#OpenEphemeral">OpenEphemeral</a> or <a href="opcode.html#SorterOpen">SorterOpen</a>.</td></tr> |
| 2028 |
<tr><td valign="top" align="center"> |
| 2029 |
<a name="ResultRow"></a>ResultRow |
| 2030 |
<td>The registers P1 through P1+P2-1 contain a single row of |
| 2031 |
results. This opcode causes the sqlite3_step() call to terminate |
| 2032 |
with an SQLITE_ROW return code and it sets up the sqlite3_stmt |
| 2033 |
structure to provide access to the r(P1)..r(P1+P2-1) values as |
| 2034 |
the result row.</td></tr> |
| 2035 |
<tr><td valign="top" align="center"> |
| 2036 |
<a name="Return"></a>Return |
| 2037 |
<td>Jump to the address stored in register P1. If P1 is a return address |
| 2038 |
register, then this accomplishes a return from a subroutine.</p> |
| 2039 |
|
| 2040 |
<p>If P3 is 1, then the jump is only taken if register P1 holds an integer |
| 2041 |
values, otherwise execution falls through to the next opcode, and the |
| 2042 |
<a href="opcode.html#Return">Return</a> becomes a no-op. If P3 is 0, then register P1 must hold an |
| 2043 |
integer or else an assert() is raised. P3 should be set to 1 when |
| 2044 |
this opcode is used in combination with <a href="opcode.html#BeginSubrtn">BeginSubrtn</a>, and set to 0 |
| 2045 |
otherwise.</p> |
| 2046 |
|
| 2047 |
<p>The value in register P1 is unchanged by this opcode.</p> |
| 2048 |
|
| 2049 |
<p>P2 is not used by the byte-code engine. However, if P2 is positive |
| 2050 |
and also less than the current address, then the "EXPLAIN" output |
| 2051 |
formatter in the CLI will indent all opcodes from the P2 opcode up |
| 2052 |
to be not including the current <a href="opcode.html#Return">Return</a>. P2 should be the first opcode |
| 2053 |
in the subroutine from which this opcode is returning. Thus the P2 |
| 2054 |
value is a byte-code indentation hint. See tag-20220407a in |
| 2055 |
wherecode.c and shell.c.</td></tr> |
| 2056 |
<tr><td valign="top" align="center"> |
| 2057 |
<a name="Rewind"></a>Rewind |
| 2058 |
<td>The next use of the <a href="opcode.html#Rowid">Rowid</a> or <a href="opcode.html#Column">Column</a> or <a href="opcode.html#Next">Next</a> instruction for P1 |
| 2059 |
will refer to the first entry in the database table or index. |
| 2060 |
If the table or index is empty, jump immediately to P2. |
| 2061 |
If the table or index is not empty, fall through to the following |
| 2062 |
instruction.</p> |
| 2063 |
|
| 2064 |
<p>If P2 is zero, that is an assertion that the P1 table is never |
| 2065 |
empty and hence the jump will never be taken.</p> |
| 2066 |
|
| 2067 |
<p>This opcode leaves the cursor configured to move in forward order, |
| 2068 |
from the beginning toward the end. In other words, the cursor is |
| 2069 |
configured to use <a href="opcode.html#Next">Next</a>, not <a href="opcode.html#Prev">Prev</a>.</td></tr> |
| 2070 |
<tr><td valign="top" align="center"> |
| 2071 |
<a name="RowCell"></a>RowCell |
| 2072 |
<td>P1 and P2 are both open cursors. Both must be opened on the same type |
| 2073 |
of table - intkey or index. This opcode is used as part of copying |
| 2074 |
the current row from P2 into P1. If the cursors are opened on intkey |
| 2075 |
tables, register P3 contains the rowid to use with the new record in |
| 2076 |
P1. If they are opened on index tables, P3 is not used.</p> |
| 2077 |
|
| 2078 |
<p>This opcode must be followed by either an <a href="opcode.html#Insert">Insert</a> or InsertIdx opcode |
| 2079 |
with the OPFLAG_PREFORMAT flag set to complete the insert operation.</td></tr> |
| 2080 |
<tr><td valign="top" align="center"> |
| 2081 |
<a name="RowData"></a>RowData |
| 2082 |
<td>Write into register P2 the complete row content for the row at |
| 2083 |
which cursor P1 is currently pointing. |
| 2084 |
There is no interpretation of the data. |
| 2085 |
It is just copied onto the P2 register exactly as |
| 2086 |
it is found in the database file.</p> |
| 2087 |
|
| 2088 |
<p>If cursor P1 is an index, then the content is the key of the row. |
| 2089 |
If cursor P2 is a table, then the content extracted is the data.</p> |
| 2090 |
|
| 2091 |
<p>If the P1 cursor must be pointing to a valid row (not a NULL row) |
| 2092 |
of a real table, not a pseudo-table.</p> |
| 2093 |
|
| 2094 |
<p>If P3!=0 then this opcode is allowed to make an ephemeral pointer |
| 2095 |
into the database page. That means that the content of the output |
| 2096 |
register will be invalidated as soon as the cursor moves - including |
| 2097 |
moves caused by other cursors that "save" the current cursors |
| 2098 |
position in order that they can write to the same table. If P3==0 |
| 2099 |
then a copy of the data is made into memory. P3!=0 is faster, but |
| 2100 |
P3==0 is safer.</p> |
| 2101 |
|
| 2102 |
<p>If P3!=0 then the content of the P2 register is unsuitable for use |
| 2103 |
in OP_Result and any OP_Result will invalidate the P2 register content. |
| 2104 |
The P2 register content is invalidated by opcodes like <a href="opcode.html#Function">Function</a> or |
| 2105 |
by any use of another cursor pointing to the same table.</td></tr> |
| 2106 |
<tr><td valign="top" align="center"> |
| 2107 |
<a name="Rowid"></a>Rowid |
| 2108 |
<td>Store in register P2 an integer which is the key of the table entry that |
| 2109 |
P1 is currently point to.</p> |
| 2110 |
|
| 2111 |
<p>P1 can be either an ordinary table or a virtual table. There used to |
| 2112 |
be a separate OP_VRowid opcode for use with virtual tables, but this |
| 2113 |
one opcode now works for both table types.</td></tr> |
| 2114 |
<tr><td valign="top" align="center"> |
| 2115 |
<a name="RowSetAdd"></a>RowSetAdd |
| 2116 |
<td>Insert the integer value held by register P2 into a RowSet object |
| 2117 |
held in register P1.</p> |
| 2118 |
|
| 2119 |
<p>An assertion fails if P2 is not an integer.</td></tr> |
| 2120 |
<tr><td valign="top" align="center"> |
| 2121 |
<a name="RowSetRead"></a>RowSetRead |
| 2122 |
<td>Extract the smallest value from the RowSet object in P1 |
| 2123 |
and put that value into register P3. |
| 2124 |
Or, if RowSet object P1 is initially empty, leave P3 |
| 2125 |
unchanged and jump to instruction P2.</td></tr> |
| 2126 |
<tr><td valign="top" align="center"> |
| 2127 |
<a name="RowSetTest"></a>RowSetTest |
| 2128 |
<td>Register P3 is assumed to hold a 64-bit integer value. If register P1 |
| 2129 |
contains a RowSet object and that RowSet object contains |
| 2130 |
the value held in P3, jump to register P2. Otherwise, insert the |
| 2131 |
integer in P3 into the RowSet and continue on to the |
| 2132 |
next opcode.</p> |
| 2133 |
|
| 2134 |
<p>The RowSet object is optimized for the case where sets of integers |
| 2135 |
are inserted in distinct phases, which each set contains no duplicates. |
| 2136 |
Each set is identified by a unique P4 value. The first set |
| 2137 |
must have P4==0, the final set must have P4==-1, and for all other sets |
| 2138 |
must have P4>0.</p> |
| 2139 |
|
| 2140 |
<p>This allows optimizations: (a) when P4==0 there is no need to test |
| 2141 |
the RowSet object for P3, as it is guaranteed not to contain it, |
| 2142 |
(b) when P4==-1 there is no need to insert the value, as it will |
| 2143 |
never be tested for, and (c) when a value that is part of set X is |
| 2144 |
inserted, there is no need to search to see if the same value was |
| 2145 |
previously inserted as part of set X (only if it was previously |
| 2146 |
inserted as part of some other set).</td></tr> |
| 2147 |
<tr><td valign="top" align="center"> |
| 2148 |
<a name="Savepoint"></a>Savepoint |
| 2149 |
<td>Open, release or rollback the savepoint named by parameter P4, depending |
| 2150 |
on the value of P1. To open a new savepoint set P1==0 (SAVEPOINT_BEGIN). |
| 2151 |
To release (commit) an existing savepoint set P1==1 (SAVEPOINT_RELEASE). |
| 2152 |
To rollback an existing savepoint set P1==2 (SAVEPOINT_ROLLBACK).</td></tr> |
| 2153 |
<tr><td valign="top" align="center"> |
| 2154 |
<a name="SCopy"></a>SCopy |
| 2155 |
<td>Make a shallow copy of register P1 into register P2.</p> |
| 2156 |
|
| 2157 |
<p>This instruction makes a shallow copy of the value. If the value |
| 2158 |
is a string or blob, then the copy is only a pointer to the |
| 2159 |
original and hence if the original changes so will the copy. |
| 2160 |
Worse, if the original is deallocated, the copy becomes invalid. |
| 2161 |
Thus the program must guarantee that the original will not change |
| 2162 |
during the lifetime of the copy. Use <a href="opcode.html#Copy">Copy</a> to make a complete |
| 2163 |
copy.</td></tr> |
| 2164 |
<tr><td valign="top" align="center"> |
| 2165 |
<a name="SeekEnd"></a>SeekEnd |
| 2166 |
<td>Position cursor P1 at the end of the btree for the purpose of |
| 2167 |
appending a new entry onto the btree.</p> |
| 2168 |
|
| 2169 |
<p>It is assumed that the cursor is used only for appending and so |
| 2170 |
if the cursor is valid, then the cursor must already be pointing |
| 2171 |
at the end of the btree and so no changes are made to |
| 2172 |
the cursor.</td></tr> |
| 2173 |
<tr><td valign="top" align="center"> |
| 2174 |
<a name="SeekGE"></a>SeekGE |
| 2175 |
<td>If cursor P1 refers to an SQL table (B-Tree that uses integer keys), |
| 2176 |
use the value in register P3 as the key. If cursor P1 refers |
| 2177 |
to an SQL index, then P3 is the first in an array of P4 registers |
| 2178 |
that are used as an unpacked index key.</p> |
| 2179 |
|
| 2180 |
<p>Reposition cursor P1 so that it points to the smallest entry that |
| 2181 |
is greater than or equal to the key value. If there are no records |
| 2182 |
greater than or equal to the key and P2 is not zero, then jump to P2.</p> |
| 2183 |
|
| 2184 |
<p>If the cursor P1 was opened using the OPFLAG_SEEKEQ flag, then this |
| 2185 |
opcode will either land on a record that exactly matches the key, or |
| 2186 |
else it will cause a jump to P2. When the cursor is OPFLAG_SEEKEQ, |
| 2187 |
this opcode must be followed by an <a href="opcode.html#IdxLE">IdxLE</a> opcode with the same arguments. |
| 2188 |
The <a href="opcode.html#IdxGT">IdxGT</a> opcode will be skipped if this opcode succeeds, but the |
| 2189 |
<a href="opcode.html#IdxGT">IdxGT</a> opcode will be used on subsequent loop iterations. The |
| 2190 |
OPFLAG_SEEKEQ flags is a hint to the btree layer to say that this |
| 2191 |
is an equality search.</p> |
| 2192 |
|
| 2193 |
<p>This opcode leaves the cursor configured to move in forward order, |
| 2194 |
from the beginning toward the end. In other words, the cursor is |
| 2195 |
configured to use <a href="opcode.html#Next">Next</a>, not <a href="opcode.html#Prev">Prev</a>.</p> |
| 2196 |
|
| 2197 |
<p>See also: <a href="opcode.html#Found">Found</a>, <a href="opcode.html#NotFound">NotFound</a>, SeekLt, SeekGt, SeekLe</td></tr> |
| 2198 |
<tr><td valign="top" align="center"> |
| 2199 |
<a name="SeekGT"></a>SeekGT |
| 2200 |
<td>If cursor P1 refers to an SQL table (B-Tree that uses integer keys), |
| 2201 |
use the value in register P3 as a key. If cursor P1 refers |
| 2202 |
to an SQL index, then P3 is the first in an array of P4 registers |
| 2203 |
that are used as an unpacked index key.</p> |
| 2204 |
|
| 2205 |
<p>Reposition cursor P1 so that it points to the smallest entry that |
| 2206 |
is greater than the key value. If there are no records greater than |
| 2207 |
the key and P2 is not zero, then jump to P2.</p> |
| 2208 |
|
| 2209 |
<p>This opcode leaves the cursor configured to move in forward order, |
| 2210 |
from the beginning toward the end. In other words, the cursor is |
| 2211 |
configured to use <a href="opcode.html#Next">Next</a>, not <a href="opcode.html#Prev">Prev</a>.</p> |
| 2212 |
|
| 2213 |
<p>See also: <a href="opcode.html#Found">Found</a>, <a href="opcode.html#NotFound">NotFound</a>, SeekLt, SeekGe, SeekLe</td></tr> |
| 2214 |
<tr><td valign="top" align="center"> |
| 2215 |
<a name="SeekHit"></a>SeekHit |
| 2216 |
<td>Increase or decrease the seekHit value for cursor P1, if necessary, |
| 2217 |
so that it is no less than P2 and no greater than P3.</p> |
| 2218 |
|
| 2219 |
<p>The seekHit integer represents the maximum of terms in an index for which |
| 2220 |
there is known to be at least one match. If the seekHit value is smaller |
| 2221 |
than the total number of equality terms in an index lookup, then the |
| 2222 |
<a href="opcode.html#IfNoHope">IfNoHope</a> opcode might run to see if the IN loop can be abandoned |
| 2223 |
early, thus saving work. This is part of the IN-early-out optimization.</p> |
| 2224 |
|
| 2225 |
<p>P1 must be a valid b-tree cursor.</td></tr> |
| 2226 |
<tr><td valign="top" align="center"> |
| 2227 |
<a name="SeekLE"></a>SeekLE |
| 2228 |
<td>If cursor P1 refers to an SQL table (B-Tree that uses integer keys), |
| 2229 |
use the value in register P3 as a key. If cursor P1 refers |
| 2230 |
to an SQL index, then P3 is the first in an array of P4 registers |
| 2231 |
that are used as an unpacked index key.</p> |
| 2232 |
|
| 2233 |
<p>Reposition cursor P1 so that it points to the largest entry that |
| 2234 |
is less than or equal to the key value. If there are no records |
| 2235 |
less than or equal to the key and P2 is not zero, then jump to P2.</p> |
| 2236 |
|
| 2237 |
<p>This opcode leaves the cursor configured to move in reverse order, |
| 2238 |
from the end toward the beginning. In other words, the cursor is |
| 2239 |
configured to use <a href="opcode.html#Prev">Prev</a>, not <a href="opcode.html#Next">Next</a>.</p> |
| 2240 |
|
| 2241 |
<p>If the cursor P1 was opened using the OPFLAG_SEEKEQ flag, then this |
| 2242 |
opcode will either land on a record that exactly matches the key, or |
| 2243 |
else it will cause a jump to P2. When the cursor is OPFLAG_SEEKEQ, |
| 2244 |
this opcode must be followed by an <a href="opcode.html#IdxLE">IdxLE</a> opcode with the same arguments. |
| 2245 |
The <a href="opcode.html#IdxGE">IdxGE</a> opcode will be skipped if this opcode succeeds, but the |
| 2246 |
<a href="opcode.html#IdxGE">IdxGE</a> opcode will be used on subsequent loop iterations. The |
| 2247 |
OPFLAG_SEEKEQ flags is a hint to the btree layer to say that this |
| 2248 |
is an equality search.</p> |
| 2249 |
|
| 2250 |
<p>See also: <a href="opcode.html#Found">Found</a>, <a href="opcode.html#NotFound">NotFound</a>, SeekGt, SeekGe, SeekLt</td></tr> |
| 2251 |
<tr><td valign="top" align="center"> |
| 2252 |
<a name="SeekLT"></a>SeekLT |
| 2253 |
<td>If cursor P1 refers to an SQL table (B-Tree that uses integer keys), |
| 2254 |
use the value in register P3 as a key. If cursor P1 refers |
| 2255 |
to an SQL index, then P3 is the first in an array of P4 registers |
| 2256 |
that are used as an unpacked index key.</p> |
| 2257 |
|
| 2258 |
<p>Reposition cursor P1 so that it points to the largest entry that |
| 2259 |
is less than the key value. If there are no records less than |
| 2260 |
the key and P2 is not zero, then jump to P2.</p> |
| 2261 |
|
| 2262 |
<p>This opcode leaves the cursor configured to move in reverse order, |
| 2263 |
from the end toward the beginning. In other words, the cursor is |
| 2264 |
configured to use <a href="opcode.html#Prev">Prev</a>, not <a href="opcode.html#Next">Next</a>.</p> |
| 2265 |
|
| 2266 |
<p>See also: <a href="opcode.html#Found">Found</a>, <a href="opcode.html#NotFound">NotFound</a>, SeekGt, SeekGe, SeekLe</td></tr> |
| 2267 |
<tr><td valign="top" align="center"> |
| 2268 |
<a name="SeekRowid"></a>SeekRowid |
| 2269 |
<td>P1 is the index of a cursor open on an SQL table btree (with integer |
| 2270 |
keys). If register P3 does not contain an integer or if P1 does not |
| 2271 |
contain a record with rowid P3 then jump immediately to P2. |
| 2272 |
Or, if P2 is 0, raise an SQLITE_CORRUPT error. If P1 does contain |
| 2273 |
a record with rowid P3 then |
| 2274 |
leave the cursor pointing at that record and fall through to the next |
| 2275 |
instruction.</p> |
| 2276 |
|
| 2277 |
<p>The <a href="opcode.html#NotExists">NotExists</a> opcode performs the same operation, but with <a href="opcode.html#NotExists">NotExists</a> |
| 2278 |
the P3 register must be guaranteed to contain an integer value. With this |
| 2279 |
opcode, register P3 might not contain an integer.</p> |
| 2280 |
|
| 2281 |
<p>The <a href="opcode.html#NotFound">NotFound</a> opcode performs the same operation on index btrees |
| 2282 |
(with arbitrary multi-value keys).</p> |
| 2283 |
|
| 2284 |
<p>This opcode leaves the cursor in a state where it cannot be advanced |
| 2285 |
in either direction. In other words, the <a href="opcode.html#Next">Next</a> and <a href="opcode.html#Prev">Prev</a> opcodes will |
| 2286 |
not work following this opcode.</p> |
| 2287 |
|
| 2288 |
<p>See also: <a href="opcode.html#Found">Found</a>, <a href="opcode.html#NotFound">NotFound</a>, <a href="opcode.html#NoConflict">NoConflict</a>, <a href="opcode.html#SeekRowid">SeekRowid</a></td></tr> |
| 2289 |
<tr><td valign="top" align="center"> |
| 2290 |
<a name="SeekScan"></a>SeekScan |
| 2291 |
<td>This opcode is a prefix opcode to <a href="opcode.html#SeekGE">SeekGE</a>. In other words, this |
| 2292 |
opcode must be immediately followed by <a href="opcode.html#SeekGE">SeekGE</a>. This constraint is |
| 2293 |
checked by assert() statements.</p> |
| 2294 |
|
| 2295 |
<p>This opcode uses the P1 through P4 operands of the subsequent |
| 2296 |
<a href="opcode.html#SeekGE">SeekGE</a>. In the text that follows, the operands of the subsequent |
| 2297 |
<a href="opcode.html#SeekGE">SeekGE</a> opcode are denoted as SeekOP.P1 through SeekOP.P4. Only |
| 2298 |
the P1, P2 and P5 operands of this opcode are also used, and are called |
| 2299 |
This.P1, This.P2 and This.P5.</p> |
| 2300 |
|
| 2301 |
<p>This opcode helps to optimize IN operators on a multi-column index |
| 2302 |
where the IN operator is on the later terms of the index by avoiding |
| 2303 |
unnecessary seeks on the btree, substituting steps to the next row |
| 2304 |
of the b-tree instead. A correct answer is obtained if this opcode |
| 2305 |
is omitted or is a no-op.</p> |
| 2306 |
|
| 2307 |
<p>The <a href="opcode.html#SeekGE">SeekGE</a>.P3 and <a href="opcode.html#SeekGE">SeekGE</a>.P4 operands identify an unpacked key which |
| 2308 |
is the desired entry that we want the cursor <a href="opcode.html#SeekGE">SeekGE</a>.P1 to be pointing |
| 2309 |
to. Call this <a href="opcode.html#SeekGE">SeekGE</a>.P3/P4 row the "target".</p> |
| 2310 |
|
| 2311 |
<p>If the <a href="opcode.html#SeekGE">SeekGE</a>.P1 cursor is not currently pointing to a valid row, |
| 2312 |
then this opcode is a no-op and control passes through into the <a href="opcode.html#SeekGE">SeekGE</a>.</p> |
| 2313 |
|
| 2314 |
<p>If the <a href="opcode.html#SeekGE">SeekGE</a>.P1 cursor is pointing to a valid row, then that row |
| 2315 |
might be the target row, or it might be near and slightly before the |
| 2316 |
target row, or it might be after the target row. If the cursor is |
| 2317 |
currently before the target row, then this opcode attempts to position |
| 2318 |
the cursor on or after the target row by invoking sqlite3BtreeStep() |
| 2319 |
on the cursor between 1 and This.P1 times.</p> |
| 2320 |
|
| 2321 |
<p>The This.P5 parameter is a flag that indicates what to do if the |
| 2322 |
cursor ends up pointing at a valid row that is past the target |
| 2323 |
row. If This.P5 is false (0) then a jump is made to <a href="opcode.html#SeekGE">SeekGE</a>.P2. If |
| 2324 |
This.P5 is true (non-zero) then a jump is made to This.P2. The P5==0 |
| 2325 |
case occurs when there are no inequality constraints to the right of |
| 2326 |
the IN constraint. The jump to <a href="opcode.html#SeekGE">SeekGE</a>.P2 ends the loop. The P5!=0 case |
| 2327 |
occurs when there are inequality constraints to the right of the IN |
| 2328 |
operator. In that case, the This.P2 will point either directly to or |
| 2329 |
to setup code prior to the <a href="opcode.html#IdxGT">IdxGT</a> or <a href="opcode.html#IdxGE">IdxGE</a> opcode that checks for |
| 2330 |
loop terminate.</p> |
| 2331 |
|
| 2332 |
<p>Possible outcomes from this opcode:<ol></p> |
| 2333 |
|
| 2334 |
<p><li> If the cursor is initially not pointed to any valid row, then |
| 2335 |
fall through into the subsequent <a href="opcode.html#SeekGE">SeekGE</a> opcode.</p> |
| 2336 |
|
| 2337 |
<p><li> If the cursor is left pointing to a row that is before the target |
| 2338 |
row, even after making as many as This.P1 calls to |
| 2339 |
sqlite3BtreeNext(), then also fall through into <a href="opcode.html#SeekGE">SeekGE</a>.</p> |
| 2340 |
|
| 2341 |
<p><li> If the cursor is left pointing at the target row, either because it |
| 2342 |
was at the target row to begin with or because one or more |
| 2343 |
sqlite3BtreeNext() calls moved the cursor to the target row, |
| 2344 |
then jump to This.P2..,</p> |
| 2345 |
|
| 2346 |
<p><li> If the cursor started out before the target row and a call to |
| 2347 |
to sqlite3BtreeNext() moved the cursor off the end of the index |
| 2348 |
(indicating that the target row definitely does not exist in the |
| 2349 |
btree) then jump to <a href="opcode.html#SeekGE">SeekGE</a>.P2, ending the loop.</p> |
| 2350 |
|
| 2351 |
<p><li> If the cursor ends up on a valid row that is past the target row |
| 2352 |
(indicating that the target row does not exist in the btree) then |
| 2353 |
jump to SeekOP.P2 if This.P5==0 or to This.P2 if This.P5>0. |
| 2354 |
</ol></td></tr> |
| 2355 |
<tr><td valign="top" align="center"> |
| 2356 |
<a name="Sequence"></a>Sequence |
| 2357 |
<td>Find the next available sequence number for cursor P1. |
| 2358 |
Write the sequence number into register P2. |
| 2359 |
The sequence number on the cursor is incremented after this |
| 2360 |
instruction.</td></tr> |
| 2361 |
<tr><td valign="top" align="center"> |
| 2362 |
<a name="SequenceTest"></a>SequenceTest |
| 2363 |
<td>P1 is a sorter cursor. If the sequence counter is currently zero, jump |
| 2364 |
to P2. Regardless of whether or not the jump is taken, increment the |
| 2365 |
the sequence value.</td></tr> |
| 2366 |
<tr><td valign="top" align="center"> |
| 2367 |
<a name="SetCookie"></a>SetCookie |
| 2368 |
<td>Write the integer value P3 into cookie number P2 of database P1. |
| 2369 |
P2==1 is the schema version. P2==2 is the database format. |
| 2370 |
P2==3 is the recommended pager cache |
| 2371 |
size, and so forth. P1==0 is the main database file and P1==1 is the |
| 2372 |
database file used to store temporary tables.</p> |
| 2373 |
|
| 2374 |
<p>A transaction must be started before executing this opcode.</p> |
| 2375 |
|
| 2376 |
<p>If P2 is the SCHEMA_VERSION cookie (cookie number 1) then the internal |
| 2377 |
schema version is set to P3-P5. The "PRAGMA schema_version=N" statement |
| 2378 |
has P5 set to 1, so that the internal schema version will be different |
| 2379 |
from the database schema version, resulting in a schema reset.</td></tr> |
| 2380 |
<tr><td valign="top" align="center"> |
| 2381 |
<a name="SetSubtype"></a>SetSubtype |
| 2382 |
<td>Set the subtype value of register P2 to the integer from register P1. |
| 2383 |
If P1 is NULL, clear the subtype from p2.</td></tr> |
| 2384 |
<tr><td valign="top" align="center"> |
| 2385 |
<a name="ShiftLeft"></a>ShiftLeft |
| 2386 |
<td>Shift the integer value in register P2 to the left by the |
| 2387 |
number of bits specified by the integer in register P1. |
| 2388 |
Store the result in register P3. |
| 2389 |
If either input is NULL, the result is NULL.</td></tr> |
| 2390 |
<tr><td valign="top" align="center"> |
| 2391 |
<a name="ShiftRight"></a>ShiftRight |
| 2392 |
<td>Shift the integer value in register P2 to the right by the |
| 2393 |
number of bits specified by the integer in register P1. |
| 2394 |
Store the result in register P3. |
| 2395 |
If either input is NULL, the result is NULL.</td></tr> |
| 2396 |
<tr><td valign="top" align="center"> |
| 2397 |
<a name="SoftNull"></a>SoftNull |
| 2398 |
<td>Set register P1 to have the value NULL as seen by the <a href="opcode.html#MakeRecord">MakeRecord</a> |
| 2399 |
instruction, but do not free any string or blob memory associated with |
| 2400 |
the register, so that if the value was a string or blob that was |
| 2401 |
previously copied using <a href="opcode.html#SCopy">SCopy</a>, the copies will continue to be valid.</td></tr> |
| 2402 |
<tr><td valign="top" align="center"> |
| 2403 |
<a name="Sort"></a>Sort |
| 2404 |
<td>This opcode does exactly the same thing as <a href="opcode.html#Rewind">Rewind</a> except that |
| 2405 |
it increments an undocumented global variable used for testing.</p> |
| 2406 |
|
| 2407 |
<p>Sorting is accomplished by writing records into a sorting index, |
| 2408 |
then rewinding that index and playing it back from beginning to |
| 2409 |
end. We use the <a href="opcode.html#Sort">Sort</a> opcode instead of <a href="opcode.html#Rewind">Rewind</a> to do the |
| 2410 |
rewinding so that the global variable will be incremented and |
| 2411 |
regression tests can determine whether or not the optimizer is |
| 2412 |
correctly optimizing out sorts.</td></tr> |
| 2413 |
<tr><td valign="top" align="center"> |
| 2414 |
<a name="SorterCompare"></a>SorterCompare |
| 2415 |
<td>P1 is a sorter cursor. This instruction compares a prefix of the |
| 2416 |
record blob in register P3 against a prefix of the entry that |
| 2417 |
the sorter cursor currently points to. Only the first P4 fields |
| 2418 |
of r[P3] and the sorter record are compared.</p> |
| 2419 |
|
| 2420 |
<p>If either P3 or the sorter contains a NULL in one of their significant |
| 2421 |
fields (not counting the P4 fields at the end which are ignored) then |
| 2422 |
the comparison is assumed to be equal.</p> |
| 2423 |
|
| 2424 |
<p>Fall through to next instruction if the two records compare equal to |
| 2425 |
each other. <a href="opcode.html#Jump">Jump</a> to P2 if they are different.</td></tr> |
| 2426 |
<tr><td valign="top" align="center"> |
| 2427 |
<a name="SorterData"></a>SorterData |
| 2428 |
<td>Write into register P2 the current sorter data for sorter cursor P1. |
| 2429 |
Then clear the column header cache on cursor P3.</p> |
| 2430 |
|
| 2431 |
<p>This opcode is normally used to move a record out of the sorter and into |
| 2432 |
a register that is the source for a pseudo-table cursor created using |
| 2433 |
<a href="opcode.html#OpenPseudo">OpenPseudo</a>. That pseudo-table cursor is the one that is identified by |
| 2434 |
parameter P3. Clearing the P3 column cache as part of this opcode saves |
| 2435 |
us from having to issue a separate <a href="opcode.html#NullRow">NullRow</a> instruction to clear that cache.</td></tr> |
| 2436 |
<tr><td valign="top" align="center"> |
| 2437 |
<a name="SorterInsert"></a>SorterInsert |
| 2438 |
<td>Register P2 holds an SQL index key made using the |
| 2439 |
<a href="opcode.html#MakeRecord">MakeRecord</a> instructions. This opcode writes that key |
| 2440 |
into the sorter P1. Data for the entry is nil.</td></tr> |
| 2441 |
<tr><td valign="top" align="center"> |
| 2442 |
<a name="SorterNext"></a>SorterNext |
| 2443 |
<td>This opcode works just like <a href="opcode.html#Next">Next</a> except that P1 must be a |
| 2444 |
sorter object for which the <a href="opcode.html#SorterSort">SorterSort</a> opcode has been |
| 2445 |
invoked. This opcode advances the cursor to the next sorted |
| 2446 |
record, or jumps to P2 if there are no more sorted records.</td></tr> |
| 2447 |
<tr><td valign="top" align="center"> |
| 2448 |
<a name="SorterOpen"></a>SorterOpen |
| 2449 |
<td>This opcode works like <a href="opcode.html#OpenEphemeral">OpenEphemeral</a> except that it opens |
| 2450 |
a transient index that is specifically designed to sort large |
| 2451 |
tables using an external merge-sort algorithm.</p> |
| 2452 |
|
| 2453 |
<p>If argument P3 is non-zero, then it indicates that the sorter may |
| 2454 |
assume that a stable sort considering the first P3 fields of each |
| 2455 |
key is sufficient to produce the required results.</td></tr> |
| 2456 |
<tr><td valign="top" align="center"> |
| 2457 |
<a name="SorterSort"></a>SorterSort |
| 2458 |
<td>After all records have been inserted into the Sorter object |
| 2459 |
identified by P1, invoke this opcode to actually do the sorting. |
| 2460 |
<a href="opcode.html#Jump">Jump</a> to P2 if there are no records to be sorted.</p> |
| 2461 |
|
| 2462 |
<p>This opcode is an alias for <a href="opcode.html#Sort">Sort</a> and <a href="opcode.html#Rewind">Rewind</a> that is used |
| 2463 |
for Sorter objects.</td></tr> |
| 2464 |
<tr><td valign="top" align="center"> |
| 2465 |
<a name="SqlExec"></a>SqlExec |
| 2466 |
<td>Run the SQL statement or statements specified in the P4 string.</p> |
| 2467 |
|
| 2468 |
<p>The P1 parameter is a bitmask of options:</p> |
| 2469 |
|
| 2470 |
<p>0x0001 Disable Auth and <a href="opcode.html#Trace">Trace</a> callbacks while the statements |
| 2471 |
in P4 are running.</p> |
| 2472 |
|
| 2473 |
<p>0x0002 Set db->nAnalysisLimit to P2 while the statements in |
| 2474 |
P4 are running.</p></td></tr> |
| 2475 |
<tr><td valign="top" align="center"> |
| 2476 |
<a name="String"></a>String |
| 2477 |
<td>The string value P4 of length P1 (bytes) is stored in register P2.</p> |
| 2478 |
|
| 2479 |
<p>If P3 is not zero and the content of register P3 is equal to P5, then |
| 2480 |
the datatype of the register P2 is converted to BLOB. The content is |
| 2481 |
the same sequence of bytes, it is merely interpreted as a BLOB instead |
| 2482 |
of a string, as if it had been CAST. In other words:</p> |
| 2483 |
|
| 2484 |
<p>if( P3!=0 and reg[P3]==P5 ) reg[P2] := CAST(reg[P2] as BLOB)</td></tr> |
| 2485 |
<tr><td valign="top" align="center"> |
| 2486 |
<a name="String8"></a>String8 |
| 2487 |
<td>P4 points to a nul terminated UTF-8 string. This opcode is transformed |
| 2488 |
into a <a href="opcode.html#String">String</a> opcode before it is executed for the first time. During |
| 2489 |
this transformation, the length of string P4 is computed and stored |
| 2490 |
as the P1 parameter.</td></tr> |
| 2491 |
<tr><td valign="top" align="center"> |
| 2492 |
<a name="Subtract"></a>Subtract |
| 2493 |
<td>Subtract the value in register P1 from the value in register P2 |
| 2494 |
and store the result in register P3. |
| 2495 |
If either input is NULL, the result is NULL.</td></tr> |
| 2496 |
<tr><td valign="top" align="center"> |
| 2497 |
<a name="TableLock"></a>TableLock |
| 2498 |
<td>Obtain a lock on a particular table. This instruction is only used when |
| 2499 |
the shared-cache feature is enabled.</p> |
| 2500 |
|
| 2501 |
<p>P1 is the index of the database in sqlite3.aDb[] of the database |
| 2502 |
on which the lock is acquired. A readlock is obtained if P3==0 or |
| 2503 |
a write lock if P3==1.</p> |
| 2504 |
|
| 2505 |
<p>P2 contains the root-page of the table to lock.</p> |
| 2506 |
|
| 2507 |
<p>P4 contains a pointer to the name of the table being locked. This is only |
| 2508 |
used to generate an error message if the lock cannot be obtained.</td></tr> |
| 2509 |
<tr><td valign="top" align="center"> |
| 2510 |
<a name="Trace"></a>Trace |
| 2511 |
<td>Write P4 on the statement trace output if statement tracing is |
| 2512 |
enabled.</p> |
| 2513 |
|
| 2514 |
<p>Operand P1 must be 0x7fffffff and P2 must positive.</td></tr> |
| 2515 |
<tr><td valign="top" align="center"> |
| 2516 |
<a name="Transaction"></a>Transaction |
| 2517 |
<td>Begin a transaction on database P1 if a transaction is not already |
| 2518 |
active. |
| 2519 |
If P2 is non-zero, then a write-transaction is started, or if a |
| 2520 |
read-transaction is already active, it is upgraded to a write-transaction. |
| 2521 |
If P2 is zero, then a read-transaction is started. If P2 is 2 or more |
| 2522 |
then an exclusive transaction is started.</p> |
| 2523 |
|
| 2524 |
<p>P1 is the index of the database file on which the transaction is |
| 2525 |
started. Index 0 is the main database file and index 1 is the |
| 2526 |
file used for temporary tables. Indices of 2 or more are used for |
| 2527 |
attached databases.</p> |
| 2528 |
|
| 2529 |
<p>If a write-transaction is started and the Vdbe.usesStmtJournal flag is |
| 2530 |
true (this flag is set if the Vdbe may modify more than one row and may |
| 2531 |
throw an ABORT exception), a statement transaction may also be opened. |
| 2532 |
More specifically, a statement transaction is opened iff the database |
| 2533 |
connection is currently not in autocommit mode, or if there are other |
| 2534 |
active statements. A statement transaction allows the changes made by this |
| 2535 |
VDBE to be rolled back after an error without having to roll back the |
| 2536 |
entire transaction. If no error is encountered, the statement transaction |
| 2537 |
will automatically commit when the VDBE halts.</p> |
| 2538 |
|
| 2539 |
<p>If P5!=0 then this opcode also checks the schema cookie against P3 |
| 2540 |
and the schema generation counter against P4. |
| 2541 |
The cookie changes its value whenever the database schema changes. |
| 2542 |
This operation is used to detect when that the cookie has changed |
| 2543 |
and that the current process needs to reread the schema. If the schema |
| 2544 |
cookie in P3 differs from the schema cookie in the database header or |
| 2545 |
if the schema generation counter in P4 differs from the current |
| 2546 |
generation counter, then an SQLITE_SCHEMA error is raised and execution |
| 2547 |
halts. The sqlite3_step() wrapper function might then reprepare the |
| 2548 |
statement and rerun it from the beginning.</td></tr> |
| 2549 |
<tr><td valign="top" align="center"> |
| 2550 |
<a name="TypeCheck"></a>TypeCheck |
| 2551 |
<td>Apply affinities to the range of P2 registers beginning with P1. |
| 2552 |
Take the affinities from the Table object in P4. If any value |
| 2553 |
cannot be coerced into the correct type, then raise an error.</p> |
| 2554 |
|
| 2555 |
<p>If P3==0, then omit checking of VIRTUAL columns.</p> |
| 2556 |
|
| 2557 |
<p>If P3==1, then omit checking of all generated column, both VIRTUAL |
| 2558 |
and STORED.</p> |
| 2559 |
|
| 2560 |
<p>If P3>=2, then only check column number P3-2 in the table (which will |
| 2561 |
be a VIRTUAL column) against the value in reg[P1]. In this case, |
| 2562 |
P2 will be 1.</p> |
| 2563 |
|
| 2564 |
<p>This opcode is similar to <a href="opcode.html#Affinity">Affinity</a> except that this opcode |
| 2565 |
forces the register type to the Table column type. This is used |
| 2566 |
to implement "strict affinity".</p> |
| 2567 |
|
| 2568 |
<p>GENERATED ALWAYS AS ... STATIC columns are only checked if P3 |
| 2569 |
is zero. When P3 is non-zero, no type checking occurs for |
| 2570 |
static generated columns. Virtual columns are computed at query time |
| 2571 |
and so they are never checked.</p> |
| 2572 |
|
| 2573 |
<p>Preconditions:</p> |
| 2574 |
|
| 2575 |
<p><ul> |
| 2576 |
<li> P2 should be the number of non-virtual columns in the |
| 2577 |
table of P4 unless P3>1, in which case P2 will be 1. |
| 2578 |
<li> Table P4 is a STRICT table. |
| 2579 |
</ul></p> |
| 2580 |
|
| 2581 |
<p>If any precondition is false, an assertion fault occurs.</td></tr> |
| 2582 |
<tr><td valign="top" align="center"> |
| 2583 |
<a name="Vacuum"></a>Vacuum |
| 2584 |
<td>Vacuum the entire database P1. P1 is 0 for "main", and 2 or more |
| 2585 |
for an attached database. The "temp" database may not be vacuumed.</p> |
| 2586 |
|
| 2587 |
<p>If P2 is not zero, then it is a register holding a string which is |
| 2588 |
the file into which the result of vacuum should be written. When |
| 2589 |
P2 is zero, the vacuum overwrites the original database.</td></tr> |
| 2590 |
<tr><td valign="top" align="center"> |
| 2591 |
<a name="Variable"></a>Variable |
| 2592 |
<td>Transfer the values of bound parameter P1 into register P2</td></tr> |
| 2593 |
<tr><td valign="top" align="center"> |
| 2594 |
<a name="VBegin"></a>VBegin |
| 2595 |
<td>P4 may be a pointer to an sqlite3_vtab structure. If so, call the |
| 2596 |
xBegin method for that table.</p> |
| 2597 |
|
| 2598 |
<p>Also, whether or not P4 is set, check that this is not being called from |
| 2599 |
within a callback to a virtual table xSync() method. If it is, the error |
| 2600 |
code will be set to SQLITE_LOCKED.</td></tr> |
| 2601 |
<tr><td valign="top" align="center"> |
| 2602 |
<a name="VCheck"></a>VCheck |
| 2603 |
<td>P4 is a pointer to a Table object that is a virtual table in schema P1 |
| 2604 |
that supports the xIntegrity() method. This opcode runs the xIntegrity() |
| 2605 |
method for that virtual table, using P3 as the integer argument. If |
| 2606 |
an error is reported back, the table name is prepended to the error |
| 2607 |
message and that message is stored in P2. If no errors are seen, |
| 2608 |
register P2 is set to NULL.</td></tr> |
| 2609 |
<tr><td valign="top" align="center"> |
| 2610 |
<a name="VColumn"></a>VColumn |
| 2611 |
<td>Store in register P3 the value of the P2-th column of |
| 2612 |
the current row of the virtual-table of cursor P1.</p> |
| 2613 |
|
| 2614 |
<p>If the <a href="opcode.html#VColumn">VColumn</a> opcode is being used to fetch the value of |
| 2615 |
an unchanging column during an UPDATE operation, then the P5 |
| 2616 |
value is OPFLAG_NOCHNG. This will cause the sqlite3_vtab_nochange() |
| 2617 |
function to return true inside the xColumn method of the virtual |
| 2618 |
table implementation. The P5 column might also contain other |
| 2619 |
bits (OPFLAG_LENGTHARG or OPFLAG_TYPEOFARG) but those bits are |
| 2620 |
unused by <a href="opcode.html#VColumn">VColumn</a>.</td></tr> |
| 2621 |
<tr><td valign="top" align="center"> |
| 2622 |
<a name="VCreate"></a>VCreate |
| 2623 |
<td>P2 is a register that holds the name of a virtual table in database |
| 2624 |
P1. Call the xCreate method for that table.</td></tr> |
| 2625 |
<tr><td valign="top" align="center"> |
| 2626 |
<a name="VDestroy"></a>VDestroy |
| 2627 |
<td>P4 is the name of a virtual table in database P1. Call the xDestroy method |
| 2628 |
of that table.</td></tr> |
| 2629 |
<tr><td valign="top" align="center"> |
| 2630 |
<a name="VFilter"></a>VFilter |
| 2631 |
<td>P1 is a cursor opened using <a href="opcode.html#VOpen">VOpen</a>. P2 is an address to jump to if |
| 2632 |
the filtered result set is empty.</p> |
| 2633 |
|
| 2634 |
<p>P4 is either NULL or a string that was generated by the xBestIndex |
| 2635 |
method of the module. The interpretation of the P4 string is left |
| 2636 |
to the module implementation.</p> |
| 2637 |
|
| 2638 |
<p>This opcode invokes the xFilter method on the virtual table specified |
| 2639 |
by P1. The integer query plan parameter to xFilter is stored in register |
| 2640 |
P3. Register P3+1 stores the argc parameter to be passed to the |
| 2641 |
xFilter method. Registers P3+2..P3+1+argc are the argc |
| 2642 |
additional parameters which are passed to |
| 2643 |
xFilter as argv. Register P3+2 becomes argv[0] when passed to xFilter.</p> |
| 2644 |
|
| 2645 |
<p>A jump is made to P2 if the result set after filtering would be empty.</td></tr> |
| 2646 |
<tr><td valign="top" align="center"> |
| 2647 |
<a name="VInitIn"></a>VInitIn |
| 2648 |
<td>Set register P2 to be a pointer to a ValueList object for cursor P1 |
| 2649 |
with cache register P3 and output register P3+1. This ValueList object |
| 2650 |
can be used as the first argument to sqlite3_vtab_in_first() and |
| 2651 |
sqlite3_vtab_in_next() to extract all of the values stored in the P1 |
| 2652 |
cursor. Register P3 is used to hold the values returned by |
| 2653 |
sqlite3_vtab_in_first() and sqlite3_vtab_in_next().</td></tr> |
| 2654 |
<tr><td valign="top" align="center"> |
| 2655 |
<a name="VNext"></a>VNext |
| 2656 |
<td>Advance virtual table P1 to the next row in its result set and |
| 2657 |
jump to instruction P2. Or, if the virtual table has reached |
| 2658 |
the end of its result set, then fall through to the next instruction.</td></tr> |
| 2659 |
<tr><td valign="top" align="center"> |
| 2660 |
<a name="VOpen"></a>VOpen |
| 2661 |
<td>P4 is a pointer to a virtual table object, an sqlite3_vtab structure. |
| 2662 |
P1 is a cursor number. This opcode opens a cursor to the virtual |
| 2663 |
table and stores that cursor in P1.</td></tr> |
| 2664 |
<tr><td valign="top" align="center"> |
| 2665 |
<a name="VRename"></a>VRename |
| 2666 |
<td>P4 is a pointer to a virtual table object, an sqlite3_vtab structure. |
| 2667 |
This opcode invokes the corresponding xRename method. The value |
| 2668 |
in register P1 is passed as the zName argument to the xRename method.</td></tr> |
| 2669 |
<tr><td valign="top" align="center"> |
| 2670 |
<a name="VUpdate"></a>VUpdate |
| 2671 |
<td>P4 is a pointer to a virtual table object, an sqlite3_vtab structure. |
| 2672 |
This opcode invokes the corresponding xUpdate method. P2 values |
| 2673 |
are contiguous memory cells starting at P3 to pass to the xUpdate |
| 2674 |
invocation. The value in register (P3+P2-1) corresponds to the |
| 2675 |
p2th element of the argv array passed to xUpdate.</p> |
| 2676 |
|
| 2677 |
<p>The xUpdate method will do a DELETE or an INSERT or both. |
| 2678 |
The argv[0] element (which corresponds to memory cell P3) |
| 2679 |
is the rowid of a row to delete. If argv[0] is NULL then no |
| 2680 |
deletion occurs. The argv[1] element is the rowid of the new |
| 2681 |
row. This can be NULL to have the virtual table select the new |
| 2682 |
rowid for itself. The subsequent elements in the array are |
| 2683 |
the values of columns in the new row.</p> |
| 2684 |
|
| 2685 |
<p>If P2==1 then no insert is performed. argv[0] is the rowid of |
| 2686 |
a row to delete.</p> |
| 2687 |
|
| 2688 |
<p>P1 is a boolean flag. If it is set to true and the xUpdate call |
| 2689 |
is successful, then the value returned by sqlite3_last_insert_rowid() |
| 2690 |
is set to the value of the rowid for the row just inserted.</p> |
| 2691 |
|
| 2692 |
<p>P5 is the error actions (OE_Replace, OE_Fail, OE_Ignore, etc) to |
| 2693 |
apply in the case of a constraint failure on an insert or update.</td></tr> |
| 2694 |
<tr><td valign="top" align="center"> |
| 2695 |
<a name="Yield"></a>Yield |
| 2696 |
<td>Swap the program counter with the value in register P1. This |
| 2697 |
has the effect of yielding to a coroutine.</p> |
| 2698 |
|
| 2699 |
<p>If the coroutine that is launched by this instruction ends with |
| 2700 |
<a href="opcode.html#Yield">Yield</a> or <a href="opcode.html#Return">Return</a> then continue to the next instruction. But if |
| 2701 |
the coroutine launched by this instruction ends with |
| 2702 |
<a href="opcode.html#EndCoroutine">EndCoroutine</a>, then jump to P2 rather than continuing with the |
| 2703 |
next instruction.</p> |
| 2704 |
|
| 2705 |
<p>See also: <a href="opcode.html#InitCoroutine">InitCoroutine</a></td></tr> |
| 2706 |
<tr><td valign="top" align="center"> |
| 2707 |
<a name="ZeroOrNull"></a>ZeroOrNull |
| 2708 |
<td>If both registers P1 and P3 are NOT NULL, then store a zero in |
| 2709 |
register P2. If either registers P1 or P3 are NULL then put |
| 2710 |
a NULL in register P2.</td></tr> |
| 2711 |
|
| 2712 |
</table></blockquote> |
| 2713 |
</div> |
| 2714 |
|
| 2715 |
</p><p align="center"><small><i>This page was last updated on 2025-04-16 13:13:29Z </small></i></p> |
| 2716 |
|