Debian Codegraph @

www/opcode.html

raw
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>$&nbsp;<b>sqlite3&nbsp;ex1.db</b>
385 sqlite&gt;&nbsp;<b>explain&nbsp;delete&nbsp;from&nbsp;tbl1&nbsp;where&nbsp;two&lt;20;</b>
386 addr&nbsp;&nbsp;opcode&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;p1&nbsp;&nbsp;&nbsp;&nbsp;p2&nbsp;&nbsp;&nbsp;&nbsp;p3&nbsp;&nbsp;&nbsp;&nbsp;p4&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;p5&nbsp;&nbsp;comment&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
387 ----&nbsp;&nbsp;-------------&nbsp;&nbsp;----&nbsp;&nbsp;----&nbsp;&nbsp;----&nbsp;&nbsp;-------------&nbsp;&nbsp;--&nbsp;&nbsp;-------------
388 0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Init&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;12&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;00&nbsp;&nbsp;Start&nbsp;at&nbsp;12&nbsp;&nbsp;
389 1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Null&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;00&nbsp;&nbsp;r[1]=NULL&nbsp;&nbsp;&nbsp;&nbsp;
390 2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;OpenWrite&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;3&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;00&nbsp;&nbsp;root=2&nbsp;iDb=0;&nbsp;tbl1
391 3&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Rewind&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;10&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;00&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
392 4&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Column&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;00&nbsp;&nbsp;r[2]=tbl1.two
393 5&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Ge&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;3&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;9&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(BINARY)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;51&nbsp;&nbsp;if&nbsp;r[2]&gt;=r[3]&nbsp;goto&nbsp;9
394 6&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Rowid&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;4&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;00&nbsp;&nbsp;r[4]=rowid&nbsp;&nbsp;&nbsp;
395 7&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Once&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;8&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;00&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
396 8&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Delete&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;tbl1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;02&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
397 9&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Next&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;4&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;01&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
398 10&nbsp;&nbsp;&nbsp;&nbsp;Noop&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;00&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
399 11&nbsp;&nbsp;&nbsp;&nbsp;Halt&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;00&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
400 12&nbsp;&nbsp;&nbsp;&nbsp;Transaction&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;01&nbsp;&nbsp;usesStmtJournal=0
401 13&nbsp;&nbsp;&nbsp;&nbsp;TableLock&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;tbl1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;00&nbsp;&nbsp;iDb=0&nbsp;root=2&nbsp;write=1
402 14&nbsp;&nbsp;&nbsp;&nbsp;Integer&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;20&nbsp;&nbsp;&nbsp;&nbsp;3&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;00&nbsp;&nbsp;r[3]=20&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
403 15&nbsp;&nbsp;&nbsp;&nbsp;Goto&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;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' &rarr; BLOB
596 <li> P2=='B' &rarr; TEXT
597 <li> P2=='C' &rarr; NUMERIC
598 <li> P2=='D' &rarr; INTEGER
599 <li> P2=='E' &rarr; 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&#91;P3&#93; if the checkpoint returns
608 SQLITE_BUSY or not, respectively. Write the number of pages in the
609 WAL after the checkpoint into mem&#91;P3+1&#93; and the number of pages
610 in the WAL that have been checkpointed after the checkpoint
611 completes into mem&#91;P3+2&#93;. However on an error, mem&#91;P3+1&#93; and
612 mem&#91;P3+2&#93; 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&gt;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&#91;P3&#93;. 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&#91;P3&#93; and
965 add that hash to the bloom filter contained in r&#91;P1&#93;.</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&gt;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&#91;P2&#93; := r&#91;P1&#93; IS TRUE
1389 <li> If P3==1 and P4==1 then r&#91;P2&#93; := r&#91;P1&#93; IS FALSE
1390 <li> If P3==0 and P4==1 then r&#91;P2&#93; := r&#91;P1&#93; IS NOT TRUE
1391 <li> If P3==1 and P4==0 then r&#91;P2&#93; := r&#91;P1&#93; 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&gt;=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&lt;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&gt;=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&gt;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)&lt;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&gt;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&gt;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&gt;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&#91;P3&#93; 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&#91;P1&#93; holds the limit counter. r&#91;P3&#93;
1693 holds the offset counter. The opcode computes the combined value
1694 of the LIMIT and OFFSET and stores that value in r&#91;P2&#93;. The r&#91;P2&#93;
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&#91;P3&#93; is zero or negative, that means there is no OFFSET
1699 and r&#91;P2&#93; is set to be the value of the LIMIT, r&#91;P1&#93;.</p>
1700
1701 <p>if r&#91;P1&#93; is zero or negative, that means there is no LIMIT
1702 and r&#91;P2&#93; is set to -1.</p>
1703
1704 <p>Otherwise, r&#91;P2&#93; is set to the sum of r&#91;P1&#93; and r&#91;P3&#93;.</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&#91;P3&#93; 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&gt;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&gt;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&gt;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&#91;P3&#93; 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-&gt;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&#91;P3&#93;==P5 ) reg&#91;P2&#93; := CAST(reg&#91;P2&#93; 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&gt;=2, then only check column number P3-2 in the table (which will
2561 be a VIRTUAL column) against the value in reg&#91;P1&#93;. 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&gt;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