Update and correct the documentation on the OP_OpenRead, OP_OpenWrite,

and OP_ReopenIdx opcodes.  No code changes other than the addition of
an assert().

FossilOrigin-Name: 8a0b730d0ea640d5cf75febe39b2162411a12eb5275765a85882158b5a085681

manifest

@@ -1,5 +1,5 @@
-C Version\s3.24.0
+C Update\sand\scorrect\sthe\sdocumentation\son\sthe\sOP_OpenRead,\sOP_OpenWrite,\nand\sOP_ReopenIdx\sopcodes.\s\sNo\scode\schanges\sother\sthan\sthe\saddition\sof\nan\sassert().
-D 2018-06-04T19:24:41.225
+D 2018-06-05T13:43:02.599
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F Makefile.in bfc40f350586923e0419d2ea4b559c37ec10ee4b6e210e08c14401f8e340f0da
@@ -565,7 +565,7 @@ F src/upsert.c 47edd408cc73f8d3c00a140550d1ad180b407c146285947969dd09874802bf88
 F src/utf.c 810fbfebe12359f10bc2a011520a6e10879ab2a163bcb26c74768eab82ea62a5
 F src/util.c d9eb0a6c4aae1b00a7369eadd7ca0bbe946cb4c953b6751aa20d357c2f482157
 F src/vacuum.c 37730af7540033135909ecaee3667dddec043293428d8718546d0d64ba4a5025
-F src/vdbe.c 71e5a72d89eabf7f88ef0ad4a429d3c3ee5d10de76af3818c47b275a6b3a9097
+F src/vdbe.c fcec6e9ad743f92f0a557f0b61728d001581ee96e18c3e5c7d09702afde79b38
 F src/vdbe.h e3f43bcc27ff30b0f25a6104d0cb5657e1c4b5e1b5cd2dd2216d5bcc2156a746
 F src/vdbeInt.h 42d3e65ea0c664f6d9bc9a53de645c0baf8566ff0188409ff3b8d2abc327bc17
 F src/vdbeapi.c 765a0bbe01311626417de6cb743f7f25f9f98435c98a9df4bb0714d11014633d
@@ -1730,10 +1730,7 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P 1ecb3aa13de5c8dc611b814ff34010de0bd90aae73d88aa37a59c4627be4cc2d
+P c7ee0833225bfd8c5ec2f9bf62b97c4e04d03bd9566366d5221ac8fb199a87ca
-R 2db4b8b40a57a71d528932145db72c5a
+R 0277d841a9ebaf3476d82cef8e2d4609
-T +bgcolor * #d0c0ff
-T +sym-release *
-T +sym-version-3.24.0 *
 U drh
-Z 1c60c6ad1e28023fcabbb88fe23d7708
+Z a41043871845bbfbe4b1d10a98baf884

manifest.uuid

@@ -1 +1 @@
-c7ee0833225bfd8c5ec2f9bf62b97c4e04d03bd9566366d5221ac8fb199a87ca
+8a0b730d0ea640d5cf75febe39b2162411a12eb5275765a85882158b5a085681

src/vdbe.c

@@ -3370,59 +3370,78 @@ case OP_SetCookie: {
 ** values need not be contiguous but all P1 values should be small integers.
 ** It is an error for P1 to be negative.
 **
-** If P5!=0 then use the content of register P2 as the root page, not
+** Allowed P5 bits:
-** the value of P2 itself.
+** <ul>
-**
+** <li>  <b>0x02 OPFLAG_SEEKEQ</b>: This cursor will only be used for
-** There will be a read lock on the database whenever there is an
+**       equality lookups (implemented as a pair of opcodes OP_SeekGE/OP_IdxGT
-** open cursor.  If the database was unlocked prior to this instruction
+**       of OP_SeekLE/OP_IdxGT)
-** then a read lock is acquired as part of this instruction.  A read
+** </ul>
-** lock allows other processes to read the database but prohibits
-** any other process from modifying the database.  The read lock is
-** released when all cursors are closed.  If this instruction attempts
-** to get a read lock but fails, the script terminates with an
-** SQLITE_BUSY error code.
 **
 ** The P4 value may be either an integer (P4_INT32) or a pointer to
 ** a KeyInfo structure (P4_KEYINFO). If it is a pointer to a KeyInfo 
-** structure, then said structure defines the content and collating 
+** object, then table being opened must be an [index b-tree] where the
-** sequence of the index being opened. Otherwise, if P4 is an integer 
+** KeyInfo object defines the content and collating 
-** value, it is set to the number of columns in the table.
+** sequence of that index b-tree. Otherwise, if P4 is an integer 
+** value, then the table being opened must be a [table b-tree] with a
+** number of columns no less than the value of P4.
 **
 ** See also: OpenWrite, ReopenIdx
 */
 /* Opcode: ReopenIdx P1 P2 P3 P4 P5
 ** Synopsis: root=P2 iDb=P3
 **
-** The ReopenIdx opcode works exactly like ReadOpen except that it first
+** The ReopenIdx opcode works like OP_OpenRead except that it first
-** checks to see if the cursor on P1 is already open with a root page
+** checks to see if the cursor on P1 is already open on the same
-** number of P2 and if it is this opcode becomes a no-op.  In other words,
+** b-tree and if it is this opcode becomes a no-op.  In other words,
 ** if the cursor is already open, do not reopen it.
 **
-** The ReopenIdx opcode may only be used with P5==0 and with P4 being
+** The ReopenIdx opcode may only be used with P5==0 or P5==OPFLAG_SEEKEQ
-** a P4_KEYINFO object.  Furthermore, the P3 value must be the same as
+** and with P4 being a P4_KEYINFO object.  Furthermore, the P3 value must
-** every other ReopenIdx or OpenRead for the same cursor number.
+** be the same as every other ReopenIdx or OpenRead for the same cursor
+** number.
 **
-** See the OpenRead opcode documentation for additional information.
+** Allowed P5 bits:
+** <ul>
+** <li>  <b>0x02 OPFLAG_SEEKEQ</b>: This cursor will only be used for
+**       equality lookups (implemented as a pair of opcodes OP_SeekGE/OP_IdxGT
+**       of OP_SeekLE/OP_IdxGT)
+** </ul>
+**
+** See also: OP_OpenRead, OP_OpenWrite
 */
 /* Opcode: OpenWrite P1 P2 P3 P4 P5
 ** Synopsis: root=P2 iDb=P3
 **
 ** Open a read/write cursor named P1 on the table or index whose root
-** page is P2.  Or if P5!=0 use the content of register P2 to find the
+** page is P2 (or whose root page is held in register P2 if the
-** root page.
+** OPFLAG_P2ISREG bit is set in P5 - see below).
 **
 ** The P4 value may be either an integer (P4_INT32) or a pointer to
 ** a KeyInfo structure (P4_KEYINFO). If it is a pointer to a KeyInfo 
-** structure, then said structure defines the content and collating 
+** object, then table being opened must be an [index b-tree] where the
-** sequence of the index being opened. Otherwise, if P4 is an integer 
+** KeyInfo object defines the content and collating 
-** value, it is set to the number of columns in the table, or to the
+** sequence of that index b-tree. Otherwise, if P4 is an integer 
-** largest index of any column of the table that is actually used.
+** value, then the table being opened must be a [table b-tree] with a
+** number of columns no less than the value of P4.
 **
-** This instruction works just like OpenRead except that it opens the cursor
+** Allowed P5 bits:
-** in read/write mode.  For a given table, there can be one or more read-only
+** <ul>
-** cursors or a single read/write cursor but not both.
+** <li>  <b>0x02 OPFLAG_SEEKEQ</b>: This cursor will only be used for
+**       equality lookups (implemented as a pair of opcodes OP_SeekGE/OP_IdxGT
+**       of OP_SeekLE/OP_IdxGT)
+** <li>  <b>0x08 OPFLAG_FORDELETE</b>: This cursor is used only to seek
+**       and subsequently delete entries in an index btree.  This is a
+**       hint to the storage engine that the storage engine is allowed to
+**       ignore.  The hint is not used by the official SQLite b*tree storage
+**       engine, but is used by COMDB2.
+** <li>  <b>0x10 OPFLAG_P2ISREG</b>: Use the content of register P2
+**       as the root page, not the value of P2 itself.
+** </ul>
 **
-** See also OpenRead.
+** This instruction works like OpenRead except that it opens the cursor
+** in read/write mode.
+**
+** See also: OP_OpenRead, OP_ReopenIdx
 */
 case OP_ReopenIdx: {
   int nField;
@@ -3478,6 +3497,7 @@ case OP_OpenWrite:
   if( pOp->p5 & OPFLAG_P2ISREG ){
     assert( p2>0 );
     assert( p2<=(p->nMem+1 - p->nCursor) );
+    assert( pOp->opcode==OP_OpenWrite );
     pIn2 = &aMem[p2];
     assert( memIsValid(pIn2) );
     assert( (pIn2->flags & MEM_Int)!=0 );