Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Add a documentation page describing how to write run-time loadable extensions. |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
6da9f893bca0f8fb4a6cf96b62552029 |
User & Date: | drh 2013-04-17 12:58:02.654 |
Context
2013-04-17
| ||
13:35 | Fix a coordinate error in the RTree documentation. (check-in: 600d427573 user: drh tags: trunk) | |
12:58 | Add a documentation page describing how to write run-time loadable extensions. (check-in: 6da9f893bc user: drh tags: trunk) | |
2013-04-16
| ||
13:57 | Fix typos in new documents. (check-in: 224d684b8b user: drh tags: trunk) | |
Changes
Changes to pages/datatype3.in.
︙ | ︙ | |||
477 478 479 480 481 482 483 | <p>^The compound SELECT operators UNION, INTERSECT and EXCEPT perform implicit comparisons between values. ^No affinity is applied to comparison operands for the implicit comparisons associated with UNION, INTERSECT, or EXCEPT - the values are compared as is.</p> | | | 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 | <p>^The compound SELECT operators UNION, INTERSECT and EXCEPT perform implicit comparisons between values. ^No affinity is applied to comparison operands for the implicit comparisons associated with UNION, INTERSECT, or EXCEPT - the values are compared as is.</p> <tcl>hd_fragment collation {*collating sequence} {*collating sequences}\ {collating function} *collation *BINARY *NOCASE *RTRIM \ {BINARY collating function} \ {NOCASE collating function} \ {RTRIM collating function}</tcl> <h2>6.0 Collating Sequences</h2> <p>^When SQLite compares two strings, it uses a collating sequence or |
︙ | ︙ |
Changes to pages/lang.in.
︙ | ︙ | |||
2132 2133 2134 2135 2136 2137 2138 | to override both the two and three argument versions of the like() function. Otherwise, different code may be called to implement the [LIKE] operator depending on whether or not an ESCAPE clause was specified. } funcdef {load_extension(X) load_extension(X,Y)} {} { | | | 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 | to override both the two and three argument versions of the like() function. Otherwise, different code may be called to implement the [LIKE] operator depending on whether or not an ESCAPE clause was specified. } funcdef {load_extension(X) load_extension(X,Y)} {} { ^The load_extension(X,Y) function loads [SQLite extensions] out of the shared library file named X using the entry point Y. ^The result of load_extension() is always a NULL. ^If Y is omitted then the default entry point of <b>sqlite3_extension_init</b> is used. ^The load_extension() function raises an exception if the extension fails to load or initialize correctly. <p>^The load_extension() function will fail if the extension attempts to modify or delete an SQL function or collating sequence. ^The |
︙ | ︙ |
Added pages/loadext.in.
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 | <title>Run-Time Loadable Extensions</title> <tcl>hd_keywords {loadext} {loadable extensions} {extension loading} \ {SQLite extension} {SQLite extensions}</tcl> <h1 align="center">Run-Time Loadable Extensions</h1> <p>SQLite has the ability to load extensions (including new [application-defined SQL functions], [collating sequences], [virtual tables], and [VFSes]) at run-time. This feature allows the code for extensions to be developed and tested separately from the application and then loaded on an as-needed basis.</p> <p>Extensions can also be statically linked with the application. The code template shown below will work just as well as a statically linked extension as it does as a run-time loadable extension except that you might want to give the entry point function ("sqlite3_extension_init") a different name to avoid name collisions if your application contains two or more extensions.</p> <h2>Loading An Extension</h2> <p>An SQLite extension is a shared library or DLL. To load it, you need to supply SQLite with the name of the file containing the shared library or DLL and an entry point to initialize the extension. At the lowest level, this information is supplied using the [sqlite3_load_extension()] API.</p> <p>There is also an SQL function that can be used to load extensions: [load_extension(X,Y)]. The entry point name, Y, is optional and if omitted defaults to "sqlite3_extension_init".</p> <p>For security reasons, extension loading is turned off by default. In order to use either the C-language or SQL extension loading functions, one must first enable extension loading using the [sqlite3_enable_load_extension()] C-language API.</p> <p>From the [command-line shell], extensions can be loaded using the ".load" dot-command. For example: <blockquote><pre> .load ./YourCode.so </pre></blockquote> <p>As with the load_extension() SQL function, the entry point defaults to "sqlite3_extension_init" unless an alternative name if given as the second argument to ".load".</p> <tcl>hd_fragment build {Compiling Loadable Extensions}</tcl> <h2>Compiling A Loadable Extension</h2> <p>Loadable extensions are C-code. To compile them on unix-like operating systems, the usual command is something like this:</p> <blockquote><pre> gcc -g -fPIC -shared YourCode.c -o YourCode.so </pre></blockquote> <p>To compile on Windows using MSVC, a command similar to the following will usually work:</p> <blockquote><pre> cl YourCode.c -link -dll -out:YourCode.dll -export:sqlite3_extension_init </blockquote></pre> <tcl>hd_fragment write {Programming Loadable Extensions}</tcl> <h2>Programming Loadable Extensions</h2> <p>A template loadable extension contains the following three elements:</p> <ol> <li><p> Use "<tt>#include <sqlite3ext.h></tt>" at the top of your source code files instead of "<tt>#include <sqlite3.h></tt>". </p> <li><p> Put the macro "<tt>SQLITE_EXTENSION_INIT1</tt>" on a line by itself right after the "<tt>#include <sqlite3ext.h></tt>" line. </p> <li><p> Add an extension loading entry point routine that looks like the following: <blockquote><pre> #ifdef _WIN32 __declspec(dllexport) #endif int sqlite3_extension_init( sqlite3 *db, char **pzErrMsg, const sqlite3_api_routines *pApi ){ int rc = SQLITE_OK; SQLITE_EXTENSION_INIT2(pApi); /* insert code to initialize your extension here */ return rc; } </pre></blockquote></p> </ol> <p>Here is a complete template extension that you can copy/paste to get started:</p> <hr> <pre> /* Add your header comment here */ #include <sqlite3ext.h> /* Do not use <sqlite3.h>! */ SQLITE_EXTENSION_INIT1 /* Insert here code to implement your extension */ #ifdef _WIN32 __declspec(dllexport) #endif int sqlite3_extension_init( sqlite3 *db, char **pzErrMsg, const sqlite3_api_routines *pApi ){ int rc = SQLITE_OK; SQLITE_EXTENSION_INIT2(pApi); /* Insert here calls to ** sqlite3_create_function_v2(), ** sqlite3_create_collation_v2(), ** sqlite3_create_module_v2(), and/or ** sqlite3_vfs_register() ** to register the new features that your extension adds. */ return rc; } </pre> <hr> |
Changes to schema.tcl.
︙ | ︙ | |||
32 33 34 35 36 37 38 | ); CREATE INDEX IF NOT EXISTS fragment_pageid ON fragment(pageid); /* ** Keywords used to identify link targets. */ CREATE TABLE IF NOT EXISTS keyword( | | | | | | 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 | ); CREATE INDEX IF NOT EXISTS fragment_pageid ON fragment(pageid); /* ** Keywords used to identify link targets. */ CREATE TABLE IF NOT EXISTS keyword( kwid INTEGER PRIMARY KEY, -- ID for internal use only kw TEXT UNIQUE NOT NULL COLLATE nocase, -- The keyword or keyphrase indexKw BOOLEAN NOT NULL, -- Show in the keyword doc index fragment TEXT -- Fragment keyword refers to ); /* ** Each row in this table records a hyperlink to a keyword. The ** source and destination of the hyperlink are recorded. */ CREATE TABLE IF NOT EXISTS link( |
︙ | ︙ |