Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Fix formatting problems in vtab.html associated with <yyterm> marks. |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
2262f22f31fdb870e09af147ecedba0d |
User & Date: | drh 2016-09-12 21:06:01.247 |
Context
2016-09-13
| ||
01:12 | Use <codeblock> in more places, instead of <blockquote><pre>. Improved CSS for codeblock and for syntax diagrams. (check-in: 14e4769852 user: drh tags: trunk) | |
2016-09-12
| ||
21:06 | Fix formatting problems in vtab.html associated with <yyterm> marks. (check-in: 2262f22f31 user: drh tags: trunk) | |
21:01 | Fix a typo in vtab.in. (check-in: 4df3244e10 user: dan tags: trunk) | |
Changes
Changes to pages/vtab.in.
︙ | ︙ | |||
65 66 67 68 69 70 71 | <p>The CREATE VIRTUAL TABLE statement creates a new table called <yyterm>table-name</yyterm> derived from the class class <yyterm>module-name</yyterm>. The <yyterm>module-name</yyterm> is the name that is registered for the virtual table by the [sqlite3_create_module()] interface. | | | | | | 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 | <p>The CREATE VIRTUAL TABLE statement creates a new table called <yyterm>table-name</yyterm> derived from the class class <yyterm>module-name</yyterm>. The <yyterm>module-name</yyterm> is the name that is registered for the virtual table by the [sqlite3_create_module()] interface. <codeblock> CREATE VIRTUAL TABLE tablename USING modulename; </codeblock> <p>One can also provide comma-separated arguments to the module following the module name: <codeblock> CREATE VIRTUAL TABLE tablename USING modulename(arg1, arg2, ...); </codeblock> <p>The format of the arguments to the module is very general. Each <yyterm>module-argument</yyterm> may contain keywords, string literals, identifiers, numbers, and punctuation. Each <yyterm>module-argument</yyterm> is passed as written (as text) into the [xCreate | constructor method] of the virtual table implementation |
︙ | ︙ | |||
101 102 103 104 105 106 107 | <h3>Temporary virtual tables</h3> <p>There is no "CREATE TEMP VIRTUAL TABLE" statement. To create a temporary virtual table, add the "temp" schema before the virtual table name. | | | | 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 | <h3>Temporary virtual tables</h3> <p>There is no "CREATE TEMP VIRTUAL TABLE" statement. To create a temporary virtual table, add the "temp" schema before the virtual table name. <codeblock> CREATE VIRTUAL TABLE <b>temp.</b>tablename USING module(arg1, ...); </codeblock> <tcl>hd_fragment epovtab {eponymous virtual tables} \ {eponymous virtual table}</tcl> <h3>Eponymous virtual tables</h3> <p>Some virtual tables exist automatically in the "main" schema of every database connection in which their |
︙ | ︙ | |||
125 126 127 128 129 130 131 | <p>An example of an eponymous virtual table is the [dbstat virtual table]. To use the dbstat virtual table as an eponymous virtual table, simply query against the "dbstat" module name, as if it were an ordinary table. (Note that SQLite must be compiled with the [SQLITE_ENABLE_DBSTAT_VTAB] option to include the dbstat virtual table in the build.) | | | | 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 | <p>An example of an eponymous virtual table is the [dbstat virtual table]. To use the dbstat virtual table as an eponymous virtual table, simply query against the "dbstat" module name, as if it were an ordinary table. (Note that SQLite must be compiled with the [SQLITE_ENABLE_DBSTAT_VTAB] option to include the dbstat virtual table in the build.) <codeblock> SELECT * FROM dbstat; </codeblock> <p>A virtual table is eponymous if its [xCreate] method is the exact same function as the [xConnect] method, or if the [xCreate] method is NULL. The [xCreate] method is called when a virtual table is first created using the [CREATE VIRTUAL TABLE] statement. The [xConnect] method whenever a database connection attaches to or reparses a schema. When these two methods are the same, that indicates that the virtual table has no persistent |
︙ | ︙ | |||
156 157 158 159 160 161 162 | command is attempted against that virtual table module, a jump to a NULL pointer will occur, resulting in a crash. <h2>Implementation</h2> <p>Several new C-level objects are used by the virtual table implementation: | | | | | | 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 | command is attempted against that virtual table module, a jump to a NULL pointer will occur, resulting in a crash. <h2>Implementation</h2> <p>Several new C-level objects are used by the virtual table implementation: <codeblock> typedef struct sqlite3_vtab sqlite3_vtab; typedef struct sqlite3_index_info sqlite3_index_info; typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor; typedef struct sqlite3_module sqlite3_module; </codeblock> <p>The [sqlite3_module] structure defines a module object used to implement a virtual table. Think of a module as a class from which one can construct multiple virtual tables having similar properties. For example, one might have a module that provides read-only access to comma-separated-value (CSV) files on disk. That one module can then be used to create several virtual tables where each virtual table refers to a different CSV file. <p>The module structure contains methods that are invoked by SQLite to perform various actions on the virtual table such as creating new instances of a virtual table or destroying old ones, reading and writing data, searching for and deleting, updating, or inserting rows. The module structure is explained in more detail below. <p>Each virtual table instance is represented by an [sqlite3_vtab] structure. The sqlite3_vtab structure looks like this: <codeblock> struct sqlite3_vtab { const sqlite3_module *pModule; int nRef; char *zErrMsg; }; </codeblock> <p>Virtual table implementations will normally subclass this structure to add additional private and implementation-specific fields. The nRef field is used internally by the SQLite core and should not be altered by the virtual table implementation. The virtual table implementation may pass error message text to the core by putting an error message string in zErrMsg. |
︙ | ︙ | |||
209 210 211 212 213 214 215 | it destroys the virtual table. The virtual table implementation only needs to worry about freeing the zErrMsg content when it overwrites the content with a new, different error message. <p>The [sqlite3_vtab_cursor] structure represents a pointer to a specific row of a virtual table. This is what an sqlite3_vtab_cursor looks like: | | | | | | | 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 | it destroys the virtual table. The virtual table implementation only needs to worry about freeing the zErrMsg content when it overwrites the content with a new, different error message. <p>The [sqlite3_vtab_cursor] structure represents a pointer to a specific row of a virtual table. This is what an sqlite3_vtab_cursor looks like: <codeblock> struct sqlite3_vtab_cursor { sqlite3_vtab *pVtab; }; </codeblock> <p>Once again, practical implementations will likely subclass this structure to add additional private fields. <p>The [sqlite3_index_info] structure is used to pass information into and out of the xBestIndex method of the module that implements a virtual table. <p>Before a [CREATE VIRTUAL TABLE] statement can be run, the module specified in that statement must be registered with the database connection. This is accomplished using either of the [sqlite3_create_module()] or [sqlite3_create_module_v2()] interfaces: <codeblock> int sqlite3_create_module( sqlite3 *db, /* SQLite connection to register module with */ const char *zName, /* Name of the module */ const sqlite3_module *, /* Methods for the module */ void * /* Client data for xCreate/xConnect */ ); int sqlite3_create_module_v2( sqlite3 *db, /* SQLite connection to register module with */ const char *zName, /* Name of the module */ const sqlite3_module *, /* Methods for the module */ void *, /* Client data for xCreate/xConnect */ void(*xDestroy)(void*) /* Client data destructor function */ ); </codeblock> <p>The [sqlite3_create_module()] and [sqlite3_create_module_v2()] routines associates a module name with an [sqlite3_module] structure and a separate client data that is specific to each module. The only difference between the two create_module methods is that the _v2 method includes an extra parameter that specifies a destructor for client data pointer. The module structure is what defines the behavior of a virtual table. The module structure looks like this: <codeblock> struct sqlite3_module { int iVersion; int (*xCreate)(sqlite3*, void *pAux, int argc, char **argv, sqlite3_vtab **ppVTab, char **pzErr); int (*xConnect)(sqlite3*, void *pAux, |
︙ | ︙ | |||
288 289 290 291 292 293 294 | int (*Rename)(sqlite3_vtab *pVtab, const char *zNew); /* The methods above are in version 1 of the sqlite_module object. Those ** below are for version 2 and greater. */ int (*xSavepoint)(sqlite3_vtab *pVTab, int); int (*xRelease)(sqlite3_vtab *pVTab, int); int (*xRollbackTo)(sqlite3_vtab *pVTab, int); }; | | | 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 | int (*Rename)(sqlite3_vtab *pVtab, const char *zNew); /* The methods above are in version 1 of the sqlite_module object. Those ** below are for version 2 and greater. */ int (*xSavepoint)(sqlite3_vtab *pVTab, int); int (*xRelease)(sqlite3_vtab *pVTab, int); int (*xRollbackTo)(sqlite3_vtab *pVTab, int); }; </codeblock> <p>The module structure defines all of the methods for each virtual table object. The module structure also contains the iVersion field which defines the particular edition of the module table structure. Currently, iVersion is always 1, but in future releases of SQLite the module structure definition might be extended with additional methods and in that case the iVersion value will be increased. |
︙ | ︙ | |||
341 342 343 344 345 346 347 | [sqlite3_load_extension | loadable extension]. <h1>Virtual Table Methods</h1> <tcl>hd_fragment xcreate {sqlite3_module.xCreate} {xCreate}</tcl> <h2>The xCreate Method</h2> | | | | 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 | [sqlite3_load_extension | loadable extension]. <h1>Virtual Table Methods</h1> <tcl>hd_fragment xcreate {sqlite3_module.xCreate} {xCreate}</tcl> <h2>The xCreate Method</h2> <codeblock> int (*xCreate)(sqlite3 *db, void *pAux, int argc, char **argv, sqlite3_vtab **ppVTab, char **pzErr); </codeblock> <p>The xCreate method is called to create a new instance of a virtual table in response to a [CREATE VIRTUAL TABLE] statement. If the xCreate method is the same pointer as the [xConnect] method, then the virtual table is an [eponymous virtual table]. If the xCreate method is omitted (if it is a NULL pointer) then the virtual table is an [eponymous-only virtual table]. |
︙ | ︙ | |||
383 384 385 386 387 388 389 | (an [sqlite3_vtab] object) and return a pointer to it in *ppVTab. <p>As part of the task of creating a new [sqlite3_vtab] structure, this method <u>must</u> invoke [sqlite3_declare_vtab()] to tell the SQLite core about the columns and datatypes in the virtual table. The [sqlite3_declare_vtab()] API has the following prototype: | | | | 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 | (an [sqlite3_vtab] object) and return a pointer to it in *ppVTab. <p>As part of the task of creating a new [sqlite3_vtab] structure, this method <u>must</u> invoke [sqlite3_declare_vtab()] to tell the SQLite core about the columns and datatypes in the virtual table. The [sqlite3_declare_vtab()] API has the following prototype: <codeblock> int sqlite3_declare_vtab(sqlite3 *db, const char *zCreateTable) </codeblock> <p>The first argument to [sqlite3_declare_vtab()] must be the same [database connection] pointer as the first parameter to this method. The second argument to [sqlite3_declare_vtab()] must a zero-terminated UTF-8 string that contains a well-formed [CREATE TABLE] statement that defines the columns in the virtual table and their data types. The name of the table in this CREATE TABLE statement is ignored, |
︙ | ︙ | |||
449 450 451 452 453 454 455 | expression in the result set of a [SELECT], and <li> Hidden columns are not included in the implicit column-list used by an [INSERT] statement that lacks an explicit column-list. </ul> <p>For example, if the following SQL is passed to [sqlite3_declare_vtab()]: | | | | 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 | expression in the result set of a [SELECT], and <li> Hidden columns are not included in the implicit column-list used by an [INSERT] statement that lacks an explicit column-list. </ul> <p>For example, if the following SQL is passed to [sqlite3_declare_vtab()]: <codeblock> CREATE TABLE x(a HIDDEN VARCHAR(12), b INTEGER, c INTEGER Hidden); </codeblock> <p>Then the virtual table would be created with two hidden columns, and with datatypes of "VARCHAR(12)" and "INTEGER". <p>An example use of hidden columns can be seen in the [FTS3] virtual table implementation, where every FTS virtual table contains an [FTS hidden column] that is used to pass information from the |
︙ | ︙ | |||
475 476 477 478 479 480 481 | the HIDDEN columns of the virtual table. <p>For example, the "generate_series" extension (located in the [http://www.sqlite.org/src/artifact?ci=trunk&filename=ext/misc/series.c|ext/misc/series.c] file in the [http://www.sqlite.org/src/tree?ci=trunk|source tree]) implements an [eponymous virtual table] with the following schema: | | | | | | | | 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 | the HIDDEN columns of the virtual table. <p>For example, the "generate_series" extension (located in the [http://www.sqlite.org/src/artifact?ci=trunk&filename=ext/misc/series.c|ext/misc/series.c] file in the [http://www.sqlite.org/src/tree?ci=trunk|source tree]) implements an [eponymous virtual table] with the following schema: <codeblock> CREATE TABLE generate_series( value, start HIDDEN, stop HIDDEN, step HIDDEN ); </codeblock> <p>The [sqlite3_module.xBestIndex] method in the implementation of this table checks for equality constraints against the HIDDEN columns, and uses those as input parameters to determine the range of integer "value" outputs to generate. Reasonable defaults are used for any unconstrained columns. For example, to list all integers between 5 and 50: <codeblock> SELECT value FROM generate_series(5,50); </codeblock> <p>The previous query is equivalent to the following: <codeblock> SELECT value FROM generate_series WHERE start=5 AND stop=50; </codeblock> <p>Arguments on the virtual table name are matched to [hidden columns] in order. The number of arguments can be less than the number of hidden columns, in which case the latter hidden columns are unconstrained. However, an error results if there are more arguments than there are hidden columns in the virtual table. |
︙ | ︙ | |||
535 536 537 538 539 540 541 | WITHOUT ROWID virtual tables must be read-only. <tcl>############################################################# xConnect hd_fragment xconnect {sqlite3_module.xConnect} {xConnect}</tcl> <h2>The xConnect Method</h2> | | | | 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 | WITHOUT ROWID virtual tables must be read-only. <tcl>############################################################# xConnect hd_fragment xconnect {sqlite3_module.xConnect} {xConnect}</tcl> <h2>The xConnect Method</h2> <codeblock> int (*xConnect)(sqlite3*, void *pAux, int argc, char **argv, sqlite3_vtab **ppVTab, char **pzErr); </codeblock> <p>The xConnect method is very similar to [xCreate]. It has the same parameters and constructs a new [sqlite3_vtab] structure just like xCreate. And it must also call [sqlite3_declare_vtab()] like xCreate. <p>The difference is that xConnect is called to establish a new |
︙ | ︙ | |||
595 596 597 598 599 600 601 | hd_fragment xbestindex {sqlite3_module.xBestIndex} {xBestIndex}</tcl> <h2>The xBestIndex Method</h2> <p>SQLite uses the xBestIndex method of a virtual table module to determine the best way to access the virtual table. The xBestIndex method has a prototype like this: | | | | | 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 | hd_fragment xbestindex {sqlite3_module.xBestIndex} {xBestIndex}</tcl> <h2>The xBestIndex Method</h2> <p>SQLite uses the xBestIndex method of a virtual table module to determine the best way to access the virtual table. The xBestIndex method has a prototype like this: <codeblock> int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*); </codeblock> <p>The SQLite core communicates with the xBestIndex method by filling in certain fields of the [sqlite3_index_info] structure and passing a pointer to that structure into xBestIndex as the second parameter. The xBestIndex method fills out other fields of this structure which forms the reply. The [sqlite3_index_info] structure looks like this: <codeblock> struct sqlite3_index_info { /* Inputs */ const int nConstraint; /* Number of entries in aConstraint */ const struct sqlite3_index_constraint { int iColumn; /* Column constrained. -1 for ROWID */ unsigned char op; /* Constraint operator */ unsigned char usable; /* True if this constraint is usable */ |
︙ | ︙ | |||
638 639 640 641 642 643 644 | <b>/* Fields below are only available in SQLite 3.8.2 and later */</b> sqlite3_int64 estimatedRows; /* Estimated number of rows returned */ <b>/* Fields below are only available in SQLite 3.9.0 and later */</b> int idxFlags; /* Mask of SQLITE_INDEX_SCAN_* flags */ <b>/* Fields below are only available in SQLite 3.10.0 and later */</b> sqlite3_uint64 colUsed; /* Input: Mask of columns used by statement */ }; | | | | | 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 | <b>/* Fields below are only available in SQLite 3.8.2 and later */</b> sqlite3_int64 estimatedRows; /* Estimated number of rows returned */ <b>/* Fields below are only available in SQLite 3.9.0 and later */</b> int idxFlags; /* Mask of SQLITE_INDEX_SCAN_* flags */ <b>/* Fields below are only available in SQLite 3.10.0 and later */</b> sqlite3_uint64 colUsed; /* Input: Mask of columns used by statement */ }; </codeblock> <p>Note the warnings on the "estimatedRows", "idxFlags", and colUsed fields. These fields were added with SQLite versions 3.8.2, 3.9.0, and 3.10.0, respectively. Any extension that reads or writes these fields must first check that the version of the SQLite library in use is greater than or equal to appropriate version - perhaps comparing the value returned from [sqlite3_libversion_number()] against constants 3008002, 3009000, and/or 3010000. The result of attempting to access these fields in an sqlite3_index_info structure created by an older version of SQLite are undefined. <p>In addition, there are some defined constants: <codeblock> #define SQLITE_INDEX_CONSTRAINT_EQ 2 #define SQLITE_INDEX_CONSTRAINT_GT 4 #define SQLITE_INDEX_CONSTRAINT_LE 8 #define SQLITE_INDEX_CONSTRAINT_LT 16 #define SQLITE_INDEX_CONSTRAINT_GE 32 #define SQLITE_INDEX_CONSTRAINT_MATCH 64 #define SQLITE_INDEX_CONSTRAINT_LIKE 65 /* 3.10.0 and later only */ #define SQLITE_INDEX_CONSTRAINT_GLOB 66 /* 3.10.0 and later only */ #define SQLITE_INDEX_CONSTRAINT_REGEXP 67 /* 3.10.0 and later only */ #define SQLITE_INDEX_SCAN_UNIQUE 1 /* Scan visits at most 1 row */ </codeblock> <p>The SQLite core calls the xBestIndex method when it is compiling a query that involves a virtual table. In other words, SQLite calls this method when it is running [sqlite3_prepare()] or the equivalent. By calling this method, the SQLite core is saying to the virtual table that it needs to access some subset of the rows in the virtual table and it wants to know the |
︙ | ︙ | |||
721 722 723 724 725 726 727 | column OP EXPR </blockquote> <p>Where "column" is a column in the virtual table, OP is an operator like "=" or "<", and EXPR is an arbitrary expression. So, for example, if the WHERE clause contained a term like this: | | | | | | | | 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 | column OP EXPR </blockquote> <p>Where "column" is a column in the virtual table, OP is an operator like "=" or "<", and EXPR is an arbitrary expression. So, for example, if the WHERE clause contained a term like this: <codeblock> a = 5 </codeblock> <p>Then one of the constraints would be on the "a" column with operator "=" and an expression of "5". Constraints need not have a literal representation of the WHERE clause. The query optimizer might make transformations to the WHERE clause in order to extract as many constraints as it can. So, for example, if the WHERE clause contained something like this: <codeblock> x BETWEEN 10 AND 100 AND 999>y </codeblock> <p>The query optimizer might translate this into three separate constraints: <codeblock> x >= 10 x <= 100 y < 999 </codeblock> <p>For each constraint, the aConstraint[].iColumn field indicates which column appears on the left-hand side of the constraint. The first column of the virtual table is column 0. The rowid of the virtual table is column -1. The aConstraint[].op field indicates which operator is used. The SQLITE_INDEX_CONSTRAINT_* constants map integer constants |
︙ | ︙ | |||
850 851 852 853 854 855 856 | each row of the virtual table that it receives. If such a check is redundant, the xBestFilter method can suppress that double-check by setting aConstraintUsage[].omit. <tcl>hd_fragment xdisconnect {sqlite3_module.xDisconnect} {xDisconnect}</tcl> <h2>The xDisconnect Method</h2> | | | | | | | | 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 | each row of the virtual table that it receives. If such a check is redundant, the xBestFilter method can suppress that double-check by setting aConstraintUsage[].omit. <tcl>hd_fragment xdisconnect {sqlite3_module.xDisconnect} {xDisconnect}</tcl> <h2>The xDisconnect Method</h2> <codeblock> int (*xDisconnect)(sqlite3_vtab *pVTab); </codeblock> <p>This method releases a connection to a virtual table. Only the [sqlite3_vtab] object is destroyed. The virtual table is not destroyed and any backing store associated with the virtual table persists. This method undoes the work of [xConnect]. <p>This method is a destructor for a connection to the virtual table. Contrast this method with [xDestroy]. The xDestroy is a destructor for the entire virtual table. <p>The xDisconnect method is required for every virtual table implementation, though it is acceptable for the xDisconnect and [xDestroy] methods to be the same function if that makes sense for the particular virtual table. <tcl>########################################################## xDestroy hd_fragment {sqlite3_module.xDestroy} {xDestroy}</tcl> <h2>The xDestroy Method</h2> <codeblock> int (*xDestroy)(sqlite3_vtab *pVTab); </codeblock> <p>This method releases a connection to a virtual table, just like the [xDisconnect] method, and it also destroys the underlying table implementation. This method undoes the work of [xCreate]. <p>The [xDisconnect] method is called whenever a database connection that uses a virtual table is closed. The xDestroy method is only called when a [DROP TABLE] statement is executed against the virtual table. <p>The xDestroy method is required for every virtual table implementation, though it is acceptable for the [xDisconnect] and xDestroy methods to be the same function if that makes sense for the particular virtual table. <tcl>########################################################## xOpen hd_fragment xopen {sqlite3_module.xOpen}</tcl> <h2>The xOpen Method</h2> <codeblock> int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor); </codeblock> <p>The xOpen method creates a new cursor used for accessing (read and/or writing) a virtual table. A successful invocation of this method will allocate the memory for the [sqlite3_vtab_cursor] (or a subclass), initialize the new object, and make *ppCursor point to the new object. The successful call then returns [SQLITE_OK]. |
︙ | ︙ | |||
924 925 926 927 928 929 930 | <p>The xOpen method is required for every virtual table implementation. <tcl>############################################################### xClose hd_fragment xclose {sqlite3_module.xClose}</tcl> <h2>The xClose Method</h2> | | | | | | | | 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 | <p>The xOpen method is required for every virtual table implementation. <tcl>############################################################### xClose hd_fragment xclose {sqlite3_module.xClose}</tcl> <h2>The xClose Method</h2> <codeblock> int (*xClose)(sqlite3_vtab_cursor*); </codeblock> <p>The xClose method closes a cursor previously opened by [sqlite3_module.xOpen | xOpen]. The SQLite core will always call xClose once for each cursor opened using xOpen. <p>This method must release all resources allocated by the corresponding xOpen call. The routine will not be called again even if it returns an error. The SQLite core will not use the [sqlite3_vtab_cursor] again after it has been closed. <p>The xClose method is required for every virtual table implementation. <tcl>############################################################## xEof hd_fragment xeof {sqlite3_module.xEof} {xEof}</tcl> <h2>The xEof Method</h2> <codeblock> int (*xEof)(sqlite3_vtab_cursor*); </codeblock> <p>The xEof method must return false (zero) if the specified cursor currently points to a valid row of data, or true (non-zero) otherwise. This method is called by the SQL engine immediately after each [xFilter] and [xNext] invocation. <p>The xEof method is required for every virtual table implementation. <tcl>############################################################## xFilter hd_fragment xfilter {sqlite3_module.xFilter} {xFilter}</tcl> <h2>The xFilter Method</h2> <codeblock> int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr, int argc, sqlite3_value **argv); </codeblock> <p>This method begins a search of a virtual table. The first argument is a cursor opened by [sqlite3_module.xOpen | xOpen]. The next two arguments define a particular search index previously chosen by [xBestIndex]. The specific meanings of idxNum and idxStr are unimportant as long as xFilter and xBestIndex agree on what that meaning is. |
︙ | ︙ | |||
994 995 996 997 998 999 1000 | <p>The xFilter method is required for every virtual table implementation. <tcl>############################################################### xNext hd_fragment xnext {sqlite3_module.xNext} {xNext}</tcl> <h2>The xNext Method</h2> | | | | | | 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 | <p>The xFilter method is required for every virtual table implementation. <tcl>############################################################### xNext hd_fragment xnext {sqlite3_module.xNext} {xNext}</tcl> <h2>The xNext Method</h2> <codeblock> int (*xNext)(sqlite3_vtab_cursor*); </codeblock> <p>The xNext method advances a [sqlite3_vtab_cursor | virtual table cursor] to the next row of a result set initiated by [xFilter]. If the cursor is already pointing at the last row when this routine is called, then the cursor no longer points to valid data and a subsequent call to the [xEof] method must return true (non-zero). If the cursor is successfully advanced to another row of content, then subsequent calls to [xEof] must return false (zero). <p>This method must return [SQLITE_OK] if successful, or an sqlite [error code] if an error occurs. <p>The xNext method is required for every virtual table implementation. <tcl>############################################################## xColumn hd_fragment xcolumn {sqlite3_module.xColumn} {xColumn}</tcl> <h2>The xColumn Method</h2> <codeblock> int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int N); </codeblock> <p>The SQLite core invokes this method in order to find the value for the N-th column of the current row. N is zero-based so the first column is numbered 0. The xColumn method may return its result back to SQLite using one of the following interface: |
︙ | ︙ | |||
1053 1054 1055 1056 1057 1058 1059 | <p>The xColumn method is required for every virtual table implementation. <tcl>############################################################# xRowid hd_fragment xrowid {sqlite3_module.xRowid} {xRowid}</tcl> <h2>The xRowid Method</h2> | | | | | | 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 | <p>The xColumn method is required for every virtual table implementation. <tcl>############################################################# xRowid hd_fragment xrowid {sqlite3_module.xRowid} {xRowid}</tcl> <h2>The xRowid Method</h2> <codeblock> int (*xRowid)(sqlite3_vtab_cursor *pCur, sqlite_int64 *pRowid); </codeblock> <p>A successful invocation of this method will cause *pRowid to be filled with the [rowid] of row that the [sqlite3_vtab_cursor | virtual table cursor] pCur is currently pointing at. This method returns [SQLITE_OK] on success. It returns an appropriate [error code] on failure.</p> <p>The xRowid method is required for every virtual table implementation. <tcl>############################################################# xUpdate hd_fragment xupdate {sqlite3_module.xUpdate} {xUpdate}</tcl> <h2>The xUpdate Method</h2> <codeblock> int (*xUpdate)( sqlite3_vtab *pVTab, int argc, sqlite3_value **argv, sqlite_int64 *pRowid ); </codeblock> <p>All changes to a virtual table are made using the xUpdate method. This one method can be used to insert, delete, or update. <p>The argc parameter specifies the number of entries in the argv array. The value of argc will be 1 for a pure delete operation or N+2 for an insert or replace or update where N is the number of columns in the table. |
︙ | ︙ | |||
1167 1168 1169 1170 1171 1172 1173 | is a NULL pointer, then the virtual table is read-only. <tcl>########################################################## xFindFunction hd_fragment xfindfunction {sqlite3_module.xFindFunction} {xFindFunction}</tcl> <h2>The xFindFunction Method</h2> | | | | 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 | is a NULL pointer, then the virtual table is read-only. <tcl>########################################################## xFindFunction hd_fragment xfindfunction {sqlite3_module.xFindFunction} {xFindFunction}</tcl> <h2>The xFindFunction Method</h2> <codeblock> int (*xFindFunction)( sqlite3_vtab *pVtab, int nArg, const char *zName, void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), void **ppArg ); </codeblock> <p>This method is called during [sqlite3_prepare()] to give the virtual table implementation an opportunity to overload functions. This method may be set to NULL in which case no overloading occurs. <p>When a function uses a column from a virtual table as its first argument, this method is called to see if the virtual table would |
︙ | ︙ | |||
1203 1204 1205 1206 1207 1208 1209 | <p>The function pointer returned by this routine must be valid for the lifetime of the [sqlite3_vtab] object given in the first parameter. <tcl>############################################################ xBegin hd_fragment xBegin {sqlite3_module.xBegin} {xBegin}</tcl> <h2>The xBegin Method</h2> | | | | | | | | | | | | | | 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 | <p>The function pointer returned by this routine must be valid for the lifetime of the [sqlite3_vtab] object given in the first parameter. <tcl>############################################################ xBegin hd_fragment xBegin {sqlite3_module.xBegin} {xBegin}</tcl> <h2>The xBegin Method</h2> <codeblock> int (*xBegin)(sqlite3_vtab *pVTab); </codeblock> <p>This method begins a transaction on a virtual table. This is method is optional. The xBegin pointer of [sqlite3_module] may be NULL. <p>This method is always followed by one call to either the [xCommit] or [xRollback] method. Virtual table transactions do not nest, so the xBegin method will not be invoked more than once on a single virtual table without an intervening call to either [xCommit] or [xRollback]. Multiple calls to other methods can and likely will occur in between the xBegin and the corresponding [xCommit] or [xRollback]. <tcl>############################################################ xSync hd_fragment xsync {sqlite3_module.xSync}</tcl> <h2>The xSync Method</h2> <codeblock> int (*xSync)(sqlite3_vtab *pVTab); </codeblock> <p>This method signals the start of a two-phase commit on a virtual table. This is method is optional. The xSync pointer of [sqlite3_module] may be NULL. <p>This method is only invoked after call to the [xBegin] method and prior to an [xCommit] or [xRollback]. In order to implement two-phase commit, the xSync method on all virtual tables is invoked prior to invoking the [xCommit] method on any virtual table. If any of the xSync methods fail, the entire transaction is rolled back. <tcl>########################################################### xCommit hd_fragment xcommit {sqlite3_module.xCommit} {xCommit}</tcl> <h2>The xCommit Method</h2> <codeblock> int (*xCommit)(sqlite3_vtab *pVTab); </codeblock> <p>This method causes a virtual table transaction to commit. This is method is optional. The xCommit pointer of [sqlite3_module] may be NULL. <p>A call to this method always follows a prior call to [xBegin] and [sqlite3_module.xSync|xSync]. <tcl>############################################################## xRollback hd_fragment xrollback {sqlite3_module.xRollback} {xRollback}</tcl> <h2>The xRollback Method</h2> <codeblock> int (*xRollback)(sqlite3_vtab *pVTab); </codeblock> <p>This method causes a virtual table transaction to rollback. This is method is optional. The xRollback pointer of [sqlite3_module] may be NULL. <p>A call to this method always follows a prior call to [xBegin]. <tcl>############################################################# xRename hd_fragment xrename {sqlite3_module.xRename} {xRename}</tcl> <h2>The xRename Method</h2> <codeblock> int (*xRename)(sqlite3_vtab *pVtab, const char *zNew); </codeblock> <p>This method provides notification that the virtual table implementation that the virtual table will be given a new name. If this method returns [SQLITE_OK] then SQLite renames the table. If this method returns an [error code] then the renaming is prevented. <p>The xRename method is required for every virtual table implementation. <tcl>############################################################# xSavepoint hd_fragment xsavepoint {sqlite3_module.xSavepoint} {xSavepoint}\ xRelease xRollbackTo</tcl> <h2>The xSavepoint, xRelease, and xRollbackTo Methods</h2> <codeblock> int (*xSavepoint)(sqlite3_vtab *pVtab, int); int (*xRelease)(sqlite3_vtab *pVtab, int); int (*xRollbackTo)(sqlite3_vtab *pVtab, int); </codeblock> <p> These methods provide the virtual table implementation an opportunity to implement nested transactions. They are always optional and will only be called in SQLite [version 3.7.7] and later. </p> |
︙ | ︙ |
Changes to search/hdom.tcl.
︙ | ︙ | |||
92 93 94 95 96 97 98 | # All inline tags. variable aInline foreach x { tt i b big small u em strong dfn code samp kbd var cite abbr acronym a img object br script map q sub sup span bdo | | | 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 | # All inline tags. variable aInline foreach x { tt i b big small u em strong dfn code samp kbd var cite abbr acronym a img object br script map q sub sup span bdo input select textarea label button tcl yyterm } { set aInline($x) 1 } variable aContentChecker set aContentChecker(p) HtmlInlineContent set aContentChecker(th) HtmlTableCellContent set aContentChecker(td) HtmlTableCellContent set aContentChecker(tr) HtmlTableRowContent |
︙ | ︙ |