Documentation Source Text

<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 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

<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

  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

  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

<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 &lt;sqlite3ext.h&gt;</tt>" at the top of your source
code files instead of "<tt>#include &lt;sqlite3.h&gt;</tt>".
</p>

<li><p>
Put the macro "<tt>SQLITE_EXTENSION_INIT1</tt>" on a line by itself 
right after the "<tt>#include &lt;sqlite3ext.h&gt;</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 &lt;sqlite3ext.h&gt; /* Do not use &lt;sqlite3.h&gt;! */
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>

  );
  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,              -- 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(

  );
  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(