From 167b16e47346c0b6e07fc161b43143c6b2daeae6 Mon Sep 17 00:00:00 2001 From: drh Date: Fri, 23 Jun 2000 17:02:08 +0000 Subject: [PATCH] :-) (CVS 106) FossilOrigin-Name: d825931dea3ef91600ec0b1f95c6c6b094b5bd96 --- Makefile.in | 4 + manifest | 19 +- manifest.uuid | 2 +- www/fileformat.tcl | 6 +- www/opcode.tcl | 14 +- www/sqlite.tcl | 10 +- www/vdbe.tcl | 718 +++++++++++++++++++++++++++++++++++++++++++++ 7 files changed, 752 insertions(+), 21 deletions(-) create mode 100644 www/vdbe.tcl diff --git a/Makefile.in b/Makefile.in index f5b1b614b5..75efe82eaf 100644 --- a/Makefile.in +++ b/Makefile.in @@ -188,6 +188,9 @@ fileformat.html: $(TOP)/www/fileformat.tcl lang.html: $(TOP)/www/lang.tcl tclsh $(TOP)/www/lang.tcl >lang.html +vdbe.html: $(TOP)/www/vdbe.tcl + tclsh $(TOP)/www/vdbe.tcl >vdbe.html + arch.html: $(TOP)/www/arch.tcl tclsh $(TOP)/www/arch.tcl >arch.html @@ -210,6 +213,7 @@ PUBLISH = \ opcode.html \ arch.html \ arch.png \ + vdbe.html \ c_interface.html website: $(PUBLISH) diff --git a/manifest b/manifest index a1c0d5b0f0..a92d1889ed 100644 --- a/manifest +++ b/manifest @@ -1,7 +1,7 @@ -C :-)\s(CVS\s105) -D 2000-06-21T14:00:40 +C :-)\s(CVS\s106) +D 2000-06-23T17:02:08 F COPYRIGHT 74a8a6531a42e124df07ab5599aad63870fa0bd4 -F Makefile.in 4dc16840f68e3b599915e1ec8463d365474dd286 +F Makefile.in 02ecb0cd0de7ddf7b4623d480061870798787556 F README 51f6a4e7408b34afa5bc1c0485f61b6a4efb6958 F configure c366a0402bce79ef11fe1bf703ad6ce4ff6afbb0 x F configure.in 1085ff994a334b131325de906ed318e926673588 @@ -59,12 +59,13 @@ F www/arch.png c4d908b79065a72e7dcf19317f36d1324c550e87 F www/arch.tcl 4f6a9afecc099a27bba17b4f8cc9561abc15dc40 F www/c_interface.tcl 8eb800f67e6896b1894d666b81c0b418cea09fc7 F www/changes.tcl 0efac47d38f201e31428dc9f77846049a26e847b -F www/fileformat.tcl b11435fcd2cf2238a1c5e6d16fe5e83bcd14d434 +F www/fileformat.tcl f3a70650e942262f8285d53097d48f0b3aa59862 F www/index.tcl 4116afce6a8c63d68882d2b00aa10b079e0129cd F www/lang.tcl 1645e9107d75709be4c6099b643db235bbe0a151 -F www/opcode.tcl 3cdc4bb2515fcfcbe853e3f0c91cd9199e82dadd -F www/sqlite.tcl 9fdcfd48fe9e5669116d02f29b2608903f295740 -P e1bf96a467b739373191bf75e6a097fc0f24bffc -R e797418066fd46003da2b962ee99d71d +F www/opcode.tcl 401bdc639509c2f17d3bb97cbbdfdc22a61faa07 +F www/sqlite.tcl b685dc3ce345a6db0441e6d5716ed29abb96dd29 +F www/vdbe.tcl 7fe9c3f4358d0c6e27ba8eaa37538a0c1b9b7a05 +P 516f022206a6000fb2a535c1dbf3e5cd9e077465 +R 82d5d61965b8834aaa7edc2175faf278 U drh -Z 9b7592dac834377e51fab9f36928bf0c +Z f758ebc92b85fe450c65b87f3da373b0 diff --git a/manifest.uuid b/manifest.uuid index 6bab81ef82..1ac3942c3d 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -516f022206a6000fb2a535c1dbf3e5cd9e077465 \ No newline at end of file +d825931dea3ef91600ec0b1f95c6c6b094b5bd96 \ No newline at end of file diff --git a/www/fileformat.tcl b/www/fileformat.tcl index 5cb450648b..203aab3586 100644 --- a/www/fileformat.tcl +++ b/www/fileformat.tcl @@ -1,7 +1,7 @@ # # Run this Tcl script to generate the fileformat.html file. # -set rcsid {$Id: fileformat.tcl,v 1.1 2000/06/08 19:38:36 drh Exp $} +set rcsid {$Id: fileformat.tcl,v 1.2 2000/06/23 17:02:09 drh Exp $} puts { @@ -27,8 +27,8 @@ proc Code {body} { regsub -all {&} [string trim $body] {\&} body regsub -all {>} $body {\>} body regsub -all {<} $body {\<} body - regsub -all {\(\(\(} $body {} body - regsub -all {\)\)\)} $body {} body + regsub -all {\(\(\(} $body {} body + regsub -all {\)\)\)} $body {} body puts $body puts {} } diff --git a/www/opcode.tcl b/www/opcode.tcl index 1cc59e56f5..c4822b3675 100644 --- a/www/opcode.tcl +++ b/www/opcode.tcl @@ -1,7 +1,7 @@ # # Run this Tcl script to generate the sqlite.html file. # -set rcsid {$Id: opcode.tcl,v 1.2 2000/06/09 14:14:34 drh Exp $} +set rcsid {$Id: opcode.tcl,v 1.3 2000/06/23 17:02:09 drh Exp $} puts { @@ -54,6 +54,14 @@ the statement. The program is generated for a "virtual machine" implemented by the SQLite library. This document describes the operation of that virtual machine.

+

This document is intended as a reference, not a tutorial. +A separate Virtual Machine Tutorial is currently +in preparation. If you are looking for a narrative description +of how the virtual machine works, you should read the tutorial +and not this document. Once you have a basic idea of what the +virtual machine does, you can refer back to this document for +the details on a particular opcode.

+

The source code to the virtual machine is in the vdbe.c source file. All of the opcode definitions further down in this document are contained in comments in the source file. In fact, the opcode table @@ -156,8 +164,8 @@ proc Code {body} { regsub -all {&} [string trim $body] {\&} body regsub -all {>} $body {\>} body regsub -all {<} $body {\<} body - regsub -all {\(\(\(} $body {} body - regsub -all {\)\)\)} $body {} body + regsub -all {\(\(\(} $body {} body + regsub -all {\)\)\)} $body {} body puts $body puts {} } diff --git a/www/sqlite.tcl b/www/sqlite.tcl index b3ee470805..a31133b926 100644 --- a/www/sqlite.tcl +++ b/www/sqlite.tcl @@ -1,7 +1,7 @@ # # Run this Tcl script to generate the sqlite.html file. # -set rcsid {$Id: sqlite.tcl,v 1.9 2000/06/21 13:59:14 drh Exp $} +set rcsid {$Id: sqlite.tcl,v 1.10 2000/06/23 17:02:09 drh Exp $} puts { @@ -42,8 +42,8 @@ proc Code {body} { regsub -all {&} [string trim $body] {\&} body regsub -all {>} $body {\>} body regsub -all {<} $body {\<} body - regsub -all {\(\(\(} $body {} body - regsub -all {\)\)\)} $body {} body + regsub -all {\(\(\(} $body {} body + regsub -all {\)\)\)} $body {} body puts $body puts {} } @@ -63,8 +63,8 @@ sqlite> puts {

(In the example above, and in all subsequent examples, the commands -you type are shown with a green tint in an italic font and the responses -from the computer are shown in black with a constant-width font.)

+you type are underlined shown with a green tint and the responses +from the computer are shown in black without underlining.)

You can terminate the sqlite program by typing your systems End-Of-File character (usually a Control-D) or the interrupt diff --git a/www/vdbe.tcl b/www/vdbe.tcl new file mode 100644 index 0000000000..7a5735d033 --- /dev/null +++ b/www/vdbe.tcl @@ -0,0 +1,718 @@ +# +# Run this Tcl script to generate the vdbe.html file. +# +set rcsid {$Id: vdbe.tcl,v 1.1 2000/06/23 17:02:18 drh Exp $} + +puts { + + The Virtual Database Engine of SQLite + + +

+The Virtual Database Engine of SQLite +

} +puts "

+(This page was last modified on [lrange $rcsid 3 4] GMT) +

" +puts { +
This document is +currently under development. It is incomplete and contains +errors. Use it accordingly.
+} + +puts { +

If you want to know how the SQLite library works internally, +you need to begin with a solid understanding of the Virtual Database +Engine or VDBE. The VDBE occurs right in the middle of the +processing stream (see the architecture diagram) +and so it seems to touch most as parts of the library. Even +parts of the code that do not directly interact with the VDBE +are usually in a supporting role. The VDBE really is the heart of +SQLite.

+ +

This article is a brief tutorial introduction to how the VDBE +works and in particular how the various VDBE instructions +(documented here) work together +to do useful things with the database. The style is tutorial, +beginning with simple tasks and working toward solving more +complex problems. Along the way we will touch briefly on most +aspects of the SQLite library. After completeing this tutorial, +you should have a pretty good understanding of how SQLite works +and will be ready to begin studying the actual source code.

+ +

Preliminaries

+ +

The VDBE implements a virtual computer that runs a program in +its virtual machine language. The goal of each program is to +interagate or change the database. Toward this end, the machine +language that the VDBE implements is specifically designed to +work with databases.

+ +

Each instruction of the VDBE language contains an opcode and +three operands labeled P1, P2, and P3. Operand P1 is an arbitrary +integer. P2 is a non-negative integer. P3 is a null-terminated +string, or possibly just a null pointer. Only a few VDBE +instructions use all three operands. Many instructions use only +one or two operands. A significant number of instructions use +no operands at all, taking there data and storing their results +on the execution stack. The details of what each instruction +does and which operands it uses are described in the separate +opcode description document.

+ +

A VDBE program begins +execution on instruction 0 and continues with successive instructions +until it either (1) encounters a fatal error, (2) executes a +Halt instruction, or (3) advances the program counter past the +last instruction of the program. When the VDBE completes execution, +all open database cursors are closed, all memory is freed, and +everything is popped from the stack. +So there are never any worries about memory leaks or +undeallocated resources.

+ +

If you have done any assembly language programming or have +worked with any kind of abstract machine before, all of these +details should be familiar to you. So let's jump right in and +start looking as some code.

+ + +

Inserting Records Into The Database

+ +

We begin with a problem that can be solved using a VDBE program +that is only a few instructions long. Suppose we have an SQL +table that was created like this:

+ +
+CREATE TABLE ex1(col1 text);
+
+ +

In words, we have a database table named "ex1" that has a single +column of data named "col1". Now suppose we want to insert a single +record into this table. Like this:

+ +
+INSERT INTO ex1 VALUES('Hello, World!');
+
+ +

We can see the VDBE program that SQLite uses to implement this +INSERT using the sqlite command-line utility. First start +up sqlite on a new, empty database, then create the table. +Finally, enter the INSERT statement shown above, but precede the +INSERT with the special keyword "EXPLAIN". The EXPLAIN keyword +will cause sqlite to print the VDBE program rather than +execute it. We have:

+} + +proc Code {body} { + puts {
}
+  regsub -all {&} [string trim $body] {\&} body
+  regsub -all {>} $body {\>} body
+  regsub -all {<} $body {\<} body
+  regsub -all {\(\(\(} $body {} body
+  regsub -all {\)\)\)} $body {} body
+  puts $body
+  puts {
} +} + +Code { +$ (((sqlite test_database_1))) +sqlite> (((CREATE TABLE ex1(col1 test);))) +sqlite> (((.explain))) +sqlite> (((EXPLAIN INSERT INTO ex1 VALUES('Hello, World!');))) +addr opcode p1 p2 p3 +---- ------------ ----- ----- ---------------------------------------- +0 Open 0 1 ex1 +1 New 0 0 +2 String 0 0 Hello, World! +3 MakeRecord 1 0 +4 Put 0 0 +} + +puts {

As you can see above, our simple insert statement is +implemented in just 5 instructions. There are no jumps, so the +program executes once through from top to bottom. Let's now +look at each instruction in detail.

+ +

The first instruction opens a cursor that points into the +"ex1" table. The P1 operand is a handle for the cursor: zero +in this case. Cursor handles can be any non-negative integer. +But the VDBE allocates cursors in an array with the size of the +array being one more than the largest cursor. So to conserve +memory, it is best to use handles beginning with zero and +working upward consecutively.

+ +

The P2 operand to the open instruction is 1 which means +that the cursor is opened for writing. 0 would have been used +for P2 if we wanted to open the cursor for reading only. +It is acceptable to open more than one cursor to the same +database file at the same time. But all simultaneously +opened cursors must be opened with the same P2 value. It is +not allowed to have one cursor open for reading a file and +another cursor open for writing that same file.

+ +

The second instruction, New, generates an integer key that +has not been previously used in the file "ex1". The New instruction +uses its P1 operand as the handle of a cursor for the file +for which the new key will be generated. The new key is +pushed onto the stack. The P2 and P3 operands are not used +by the New instruction.

+ +

The third instruction, String, simply pushes its P3 +operand onto the stack. After the string instruction executes, +the stack will contain two elements, as follows:

+} + +proc stack args { + puts "
" + foreach elem $args { + puts "" + } + puts "
$elem
" +} + +stack {The string "Hello, World!"} {A random integer key} + +puts {

The 4th instructionn, MakeRecord, pops the top P1 +elements off the stack (1 element in this case) and converts them +all into the binary format used for storing records in a +database file. (See the file format +description for details.) The record format consists of +a header with one integer for each column giving the offset +into the record for the beginning of data for that column. +Following the header is the data for each column, Each column +is stored as a null-terminated ASCII text string. The new +record generated by the MakeRecord instruction is pushed back +onto the stack, so that after the 4th instruction executes, +the stack looks like this:

+} + +stack {A one-column record containing "Hello, World!"} \ + {A random integer key} + +puts {

The last instruction pops top elements from the stack +and uses them as data and key to make a new entry in database +database file pointed to by cursor P1. This instruction is where +the insert actually occurs.

+ +

After the last instruction executes, the program counter +advances to one past the last instruction, which causes the +VDBE to halt. When the VDBE halts, it automatically closes +all open cursors, frees any elements left on the stack, +and releases any other resources we may have allocated. +In this case, the only cleanup necessary is to close the +open cursor to the "ex1" file.

+ + +

Tracing VDBE Program Execution

+ +

If the SQLite library is compiled without the NDEBUG +preprocessor macro being defined, then +there is a special SQL comment that will cause the +the VDBE to traces the execution of programs. +Though this features was originally intended for testing +and debugging, it might also be useful in learning about +how the VDBE operates. +Use the "--vdbe-trace-on--" comment to +turn tracing on and "--vdbe-trace-off--" to turn tracing +back off. Like this:

+} + +Code { +sqlite> (((--vdbe-trace-on--))) + ...> (((INSERT INTO ex1 VALUES('Hello, World!');))) + 0 Open 0 1 ex1 + 1 New 0 0 +Stack: i:179007474 + 2 String 0 0 Hello, World! +Stack: s:[Hello, Worl] i:179007474 + 3 MakeRecord 1 0 +Stack: z:[] i:179007474 + 4 Put 0 0 +} + +puts { +

With tracing mode on, the VDBE prints each instruction prior +to executing it. After the instruction is executed, the top few +entries in the stack are displayed. The stack display is omitted +if the stack is empty.

+ +

On the stack display, most entries are show with a prefix +that tells the datatype of that stack entry. Integers begin +with "i:". Floating point values begin with "r:". +(The "r" stands for "real-number".) Strings begin with either +"s:" or "z:". The difference between s: and +z: strings is that z: strings are stored in memory obtained +from malloc(). This doesn't make any difference to you, +the observer, but it is vitally important to the VDBE since the +z: strings need to be passed to free() when they are +popped to avoid a memory leak. Note that only the first 10 +characters of string values are displayed and that binary +values (such as the result of the MakeRecord instruction) are +treated as strings. The only other datatype that can be stored +on the VDBE stack is a NULL, which is display without prefix +as simply "NULL". + + +

Simple Queries

+ +

At this point, you should understand the basics of how the VDBE +writes to a database. Now let's look at how it does queries. +We will use the follow simple SELECT statement as our example:

+ +
+SELECT col1 FROM ex1;
+
+ +

The VDBE program generated for this SQL statement is as follows:

+} + +Code { +sqlite> (((EXPLAIN SELECT * FROM ex1;))) +addr opcode p1 p2 p3 +---- ------------ ----- ----- ---------------------------------------- +0 ColumnCount 1 0 +1 ColumnName 0 0 col1 +2 Open 0 0 ex1 +3 Next 0 7 +4 Field 0 0 +5 Callback 1 0 +6 Goto 0 3 +7 Close 0 0 +} + +puts { +

Before we begin looking at this problem, let's briefly review +how queries work in SQLite so that we will know what we are trying +to accomplish. For each row in the result of a query, +SQLite will invoke a callback function with the following +prototype:

+ +
+int Callback(void *pUserData, int nColumn, char *azData[], char *azColumnName[]);
+
+ +

The SQLite library supplies the VDBE with a pointer to the callback function +itself, and the pUserData pointer. The job of the VDBE is to +come up with values for nColumn, azData[], +and azColumnName[]. +nColumn is the number of columns in the results, of course. +azColumnName[] is an array of strings where each string is the name +of one of the result column. azData[] is an array of strings holding +the actual data.

+ +

The first two instructions in the VDBE program for our query are +considered with setting up values for azColumn. +The ColumnCount instruction tells the VDBE how much space to allocate +for the azColumnName[] array. The ColumnName instructions +tell the VDBE what value to fill in for each element of the +azColumnName[] array. Every query will begin with once +ColumnCount instruction and once ColumnName instruction for each +column in the result.

+ +

The third instruction opens a cursor into the database file +that is to be queried. This works the same as the Open instruction +in the INSERT example above except that the +cursor is opened for reading this time instead of for writing.

+ +

The instructions at address 3 and 6 form a loop that will execute +once for each record in the database file. This is a key concept that +you should pay close attention to. The Next instruction at +address 3 tell the VDBE to advance the cursor (identified by P1) +to the next record. The first time Next instruction is executed, +the cursor is set to the first record of the file. If there are +no more records in the database file when Next is executed, then +the VDBE makes an immediate jump over the body of the loop to +instruction 7 (specified by operand P2). The body of the loop +is formed by instructions at addresses 4 and 5. After the loop +body is an unconditional jump at instruction 6 which takes us +back to the Next instruction at the beginning of the loop. +

+ +

The body of the loop consists of instructions at addresses 4 and +5. The Field instruction at address 4 takes the P2-th column from +the P1-th cursor and pushes it onto the stack. +(The "Field" instruction probably should be renamed as the "Column" +instruction.) In this example, the Field instruction is pushing the +value for the "col1" data column onto the stack.

+ +

The Callback instruction at address 5 invokes the callback function. +The P1 operand to callback becomes the value for nColumn. +The Callback instruction also pops P1 values from the stack and +uses them to form the azData[] for the callback.

+ +

The Close instruction at the end of the program closes the +cursor that points into the database file. It is not really necessary +to call close here since all cursors will be automatically closed +by the VDBE when the program halts. But we needed an instruction +for the Next to jump to so we might as well go ahead and have that +instruction do something useful.

+ + +

A Slightly More Complex Query

+ +

The key points of the previous example where the use of the Callback +instruction to invoke the callback function, and the use of the Next +instruction to implement a loop over all records of the database file. +This example attempts to drive home those ideas by demonstrating a +slightly more complex query that involves multiple columns of +output, some of which are computed values, and a WHERE clause that +limits which records actually make it to the callback function. +Consider this query:

+ +
+SELECT col1 AS 'Name', '**' || col1 || '**' AS 'With Stars'
+FROM ex1
+WHERE col1 LIKE '%ll%'
+
+ +

This query is perhaps a bit contrived, but it does serve to +illustrate our points. The result will have two column with +names "Name" and "With Stars". The first column is just the +sole column in our simple example table. The second column +of the result is the same as the first column except that +asterisks have been prepended and appended. Finally, the +WHERE clause says that we will only chose rows for the +results that contain two "l" characters in a row. Here is +what the VDBE program looks like for this query:

+} + +Code { +sqlite> (((EXPLAIN SELECT col1 AS 'Name', '**' || col1 || '**' AS 'With Stars'))) + ...> (((FROM ex1))) + ...> (((WHERE col1 LIKE '%ll%';))) +addr opcode p1 p2 p3 +---- ------------ ----- ----- ---------------------------------------- +0 ColumnCount 2 0 +1 ColumnName 0 0 Name +2 ColumnName 1 0 With Stars +3 Open 0 0 ex1 +4 Next 0 16 +5 Field 0 0 +6 String 0 0 %ll% +7 Like 1 4 +8 Field 0 0 +9 String 0 0 ** +10 Field 0 0 +11 Concat 2 0 +12 String 0 0 ** +13 Concat 2 0 +14 Callback 2 0 +15 Goto 0 4 +16 Close 0 0 +} + +puts { +

Except for the WHERE clause, the structure of the program for +this example is very much like the prior example, just with an +extra column. The ColumnCount is 2 now, instead of 1 as before, +and there are two ColumnName instructions. +A cursor is opened using the Open instruction, just like in the +prior example. The Next instruction at address 4 and the +Goto at address 15 form a loop over all records of the database +file. The Close instruction at the end is there to give the +Next instruction something to jump to when it is done. All of +this is just like in the first query demonstration.

+ +

The Callback instruction in this example has to generate +data for two result columns instead of one, but is otherwise +the same as in the first query. When the Callback instruction +is invoked, the left-most column of the result should be +the lowest in the stack and the right-most result column should +be the top of the stack. We can see the stack being set up +this way at addresses 8 through 13. The Field instruction at +8 pushes the value of the "col1" column of table "ex1" onto the +stack, and that is all that has to be done for the left column +of the result. Instructions at 9 through 13 evaluate the +expression used for the second result column and leave it +on the stack as well.

+ +

The only thing that is really new about the current example +is the WHERE clause which is implemented by instructions at +addresses 5, 6, and 7. Instructions at address 5 and 6 push +onto the stack the value of the "col1" column and the literal +string "%ll%". The Like instruction at address 7 pops these +two values from the stack and causes an +immediate jump back to the Next instruction if the "col1" value +is not like the literal string "%ll%". Taking this +jump effectively skips the callback, which is the whole point +of the WHERE clause. If the result +of the comparison is true, the jump is not taken and control +falls through to the Callback instruction below.

+ +

Notice how the Like instruction works. It uses the top of +the stack as its pattern and the next on stack as the data +to compare. Because P1 is 1, a jump is made to P2 if the +comparison fails. So with P1 equal to one, a more precise +name for this instruction might be "Jump If NOS Is Not Like TOS". +The sense of the test in inverted if P1 is 0. So when P1 +is zero, the instruction is more like "Jump If NOS Is Like TOS". +

+ + +

A Template For SELECT Programs

+ +

The first two query examples illustrate a kind of template that +every SELECT program will follow. Basically, we have:

+ +

+

    +
  1. Initialize the azColumnName[] array for the callback.
    2. +
  2. Open a cursor into the table to be queried.
    3. +
  3. For each record in the table, do: +
      +
    1. If the WHERE clause evaluates to FALSE, then skip the steps that + follow and continue to the next record.
      2. +
    2. Compute all columns for the current row of the result.
      3. +
    3. Invoke the callback function for the current row of the result.
      4. +
    +
  4. Close the cursor.
    5. +
+

+ +

This template will be expanded considerably as we consider +additional complications such as joins, compound selects, using +indices to speed the search, sorting, and aggregate functions +with and without GROUP BY and HAVING clauses. +But the same basic ideas will continue to apply.

+ +

UPDATE And DELETE Statements

+ +

The UPDATE and DELETE statements are coded using a template +that is very similar to the SELECT statement template. The main +difference, of course, is that the end action is to modify the +database rather than invoke a callback function. Let's begin +by looking at a DELETE statement:

+ +
+DELETE FROM ex1 WHERE col1 NOT LIKE '%H%'
+
+ +

This DELETE statement will remove every record from the "ex1" +table that does not contain an "H" characters in the "col1" +column. The code generated to do this is as follows:

+} + +Code { +sqlite> (((EXPLAIN DELETE FROM ex1 WHERE col1 NOT LIKE '%H%';))) +addr opcode p1 p2 p3 +---- ------------ ----- ----- ---------------------------------------- +0 ListOpen 0 0 +1 Open 0 0 ex1 +2 Next 0 9 +3 Field 0 0 +4 String 0 0 %H% +5 Like 0 2 +6 Key 0 0 +7 ListWrite 0 0 +8 Goto 0 2 +9 Close 0 0 +10 ListRewind 0 0 +11 Open 0 1 ex1 +12 ListRead 0 15 +13 Delete 0 0 +14 Goto 0 12 +15 ListClose 0 0 +} + +puts { +

Here is what the program must do. First it has to locate all of +the records in the "ex1" database that are to be deleted. This is +done using a loop very much like the loop used in the SELECT examples +above. Once all records have been located, then we can go back through +an delete them one by one. Note that we cannot delete each record +as soon as we find it. We have to locate all records first, then +go back and delete them. This is because with the GDBM database +backend (as with most other backends based on hashing) when you +delete a record it might change the scan order. And if the scan +order changes in the middle of the scan, some records might be +tested more than once, and some records might not be tested at all.

+ +

So the implemention of DELETE is really in two loops. The +first loop (instructions 3 through 8 in the example) locates the records that +are to be deleted and the second loop (instructions 12 through 14) +do the actual deleting.

+ +

The very first instruction in the program, the ListOpen instruction, +creates a new List object in which we can store the keys of the records +that are to be deleted. The P1 operand serves as a handle to the +list. As with cursors, you can open as many lists as you like +(though in practice we never need more than one at a time.) Each list +has a handle specified by P1 which is a non-negative integer. The +VDBE allocates an array of handles, so it is best to use only small +handles. As currently implemented, SQLite never uses more than one +list at a time and so it always uses the handle of 0 for every list.

+ +

Each list is really a file descriptor for a temporary file that +is created for holding the list. What's going to happen is this: the +first loop of the program is going to locate records that need to +be deleted and write their keys onto the list. Then the second +loop is going to playback the list and delete the records one by one.

+ +

The second instruction opens a cursor to the database file "ex1". +Notice that the cursor is opened for reading, not writing. At this +stage of the program we are going to be scanning the file not changing +it. We will reopen the same file for writing it later, at instruction 11. +

+ +

Following the Open, there is a loop composed of the Next instruction +at address 2 and continuing down to the Goto at 8. This loop works +the same way as the query loops worked in the prior examples. But +instead of invoking a callback at the end of each loop iteration, this +program calls ListWrite at instruction 7. The ListWrite instruction +pops an integer from the stack and appends it to the List identified +by P1. The integer is a key to a record that should be deleted and +was placed on the stack by the preceding Key instruction. +The WHERE clause is implemented by instructions 3, 4, and 5. +The implementation of the WHERE clause is exactly the same as in the +previous SELECT statement, except that the P1 operand to the Like +instruction is 0 instead of one because the DELETE statement uses +the NOT LIKE operator instead of the LIKE operator. If the WHERE +clause evaluates to false (if col2 is like "%ll%") then the ListWrite +instruction gets skipped and the key to that record is never written +to the list. Hence, the record is not deleted.

+ +

At the end of the first loop, the cursor is closed at instruction 9, +and the list is rewound back to the beginning at instruction 10. +Next, instruction 11 reopens the same database file, but for +writing this time. The loop that does the actual deleting of records +is on instructions 12, 13, and 14.

+ +

The ListRead instruction as 12 reads a single integer key from +the list and pushes that key onto the stack. If there are no +more keys, nothing gets pushed onto the stack but instead a jump +is made to instruction 15. Notice the similarity of operation +between the ListRead and Next instructions. Both operations work +something like this:

+ +
+Push the next "thing" onto the stack and fall through. +Or if there is no next "thing" to push, jump immediately to P2. +
+ +

The only difference between Next and ListRead is the definition +of "next thing". The "things" for the Next instruction are records +in a database file. "Things" for ListRead are integer keys in a list. +Later on, +we will see other looping instructions (NextIdx and SortNext) that +operating using the same principle.

+ +

The Delete instruction at address 13 pops an integer key from +the stack (the key was put there by the preceding ListRead +instruction) and deletes the record of cursor P1 that has that key. +If there is not record in the database with the given key, then +Delete is a no-op.

+ +

There is a Goto instruction at 14 to complete the second loop. +Then at instruction 15 is as ListClose operation. The ListClose +closes the list and deletes the temporary that held the ist. +Calling ListClose is optional. The VDBE will automatically close +the list when it halts. But we need an instruction for the +ListRead to jump to when it reaches the end of the list and +ListClose seemed like a natural candidate.

+ +

UPDATE statements work very much like DELETE statements except +that instead of deleting the record they replace it with a new one. +Consider this example: +

+ +
+UPDATE ex1 SET col1='H' || col1 WHERE col1 NOT LIKE '%H%'
+
+ +

Instead of deleting records that lack an "H" in column "col1", +this statement changes the column by prepending an "H". +The VDBE program to implement this statement follows:

+} + +Code { +addr opcode p1 p2 p3 +---- ------------ ----- ----- ---------------------------------------- +0 ListOpen 0 0 +1 Open 0 0 ex1 +2 Next 0 9 +3 Field 0 0 +4 String 0 0 %H% +5 Like 0 2 +6 Key 0 0 +7 ListWrite 0 0 +8 Goto 0 2 +9 Close 0 0 +10 ListRewind 0 0 +11 Open 0 1 ex1 +12 ListRead 0 21 +13 Dup 0 0 +14 Fetch 0 0 +15 String 0 0 H +16 Field 0 0 +17 Concat 2 0 +18 MakeRecord 1 0 +19 Put 0 0 +20 Goto 0 12 +21 ListClose 0 0 +} + +puts { +

This program is exactly the same as the DELETE program +except that the single Delete instruction in the second loop +has been replace by a sequence of instructions (at addresses +13 through 19) that update the record rather than delete it. +Most of this instruction sequence you already be familiar to +you, but there are a couple of minor twists so we will go +over it briefly.

+ +

As we enter the interior of the second loop (at instruction 13) +the stack contains a single integer which is the key of the +record we want to modify. We are going to need to use this +key twice: once to fetch the old value of column "col1" and +a second time to write back the new value. So the first instruction +is a Dup to make a duplicate of the top of the stack. The +VDBE Dup instruction is actually a little more general than that. +It will duplicate any element of the stack, not just the top +element. You specify which element to duplication using the +P1 operand. When P1 is 0, the top of the stack is duplicated. +When P1 is 1, the next element down on the stack duplication. +And so forth.

+ +

After duplicating the key, the next instruction is Fetch +pops the stack once and uses the value popped as a key to +load a record from the database file. In this way, we obtain +the old column values for the record that is about to be +updated.

+ +

Instructions 15 through 18 construct a new database record +that will be used to replace the existing record. This is +the same kind of code that we say above +in the description of INSERT and will not be described further. +After instruction 18 executes, the stack looks like this:

+} + +stack {New data record} {Integer key} + +puts { +

The Put instruction (also described above +during the discussion about INSERT) writes an entry into the +database file whose data is the top of the stack and whose key +is the next on the stack, and then pops the stack twice. The +Put instruction will overwrite the data of an existing record +with the same key, which is what we want here. It was not +an issue with INSERT because with INSERT the key was generated +by the Key instruction which is guaranteed to generate a key +that has not been used before. (By the way, since keys must +all be unique and each key is a 32-bit integer, a single +SQLite database table can have no more than 232 +rows. Actually, the Key instruction starts to become +very inefficient as you approach this upper bound, so it +is best to keep the number of entries below 231 +or so. Surely a couple billion records will be enough for +most applications!)

+ +

The rest of the UPDATE program is the same as for DELETE, +and for all the same reasons.

+} + +puts { +

+

+Back to the SQLite Home Page +

+ +}