Documentation Source Text

<title>The Carray() Table-Valued Function</title>
<tcl>hd_keywords carray {carray() table-valued function}</tcl>
<fancy_format>

<h1>Overview</h1>

<p>Carray($PTR,$N) is a [table-valued function] with a single column (named
"value") and zero or more rows.
The "value" of each row in the carray() is taken from a C-language array
that is $N elements long and begins at address $PTR.
that is $N elements long.  $PTR is a pointer to the beginning of the array.
In this way, the carray() function provides a convenient mechanism to
bind C-language arrays to SQL queries.

<h1>Availability</h1>

<p>The carray() function is not compiled into SQLite by default.
It is available as a [loadable extension] in the
[https://www.sqlite.org/src/artifact?ci=trunk&filename=ext/misc/carray.c|ext/misc/carray.c]
source file.

<p>The carray() function is dangerous.  The first parameter is
a 64-bit integer which gets cast into a pointer to an array.  In an
application that runs user-generated or untrusted SQL, the carray()
function could be used to crash the application or to leak sensitive 
information.  For that
reason, the carray() function will never be a standard part of SQLite.
Carray() will only be available in applications that 
deliberately request it.  Presumably, applications that deliberately
link carray() will also have protections in place to prevent carray()
from being misused.

<h1>Details</h1>

<p>The carray() function takes two or three arguments.
The first argument is a 64-bit integer that will be cast into a pointer
to the C-language array that is to be returned by the function.  The
second argument is the number of elements in the array.  The optional
The first argument is a pointer to an array.  Since pointer values cannot
be specified directly in SQL, the first argument must be a [parameter] that
is bound to a pointer value using the [sqlite3_bind_pointer()] interface.
The second argument is the number of elements in the array.  The optional
third argument is a string that determines the datatype of the elements
in the C-language array.  Allowed values for the third argument are:

<ol>
<li> 'int32'
<li> 'int64'
<li> 'double'
<li> 'char*'
</ol>

<p>The default datatype is 'int32'.

<p>The carray() function can be used in the FROM clause of a query.
For example, to query two entries from the OBJ table using rowids
taken from a C-language array at address 0x7b3830:
taken from a C-language array at address $PTR.

<codeblock>
SELECT obj.* FROM obj, carray(0x7b3830, 10) AS x
SELECT obj.* FROM obj, carray($PTR, 10) AS x
 WHERE obj.rowid=x.value;
</codeblock>

<p>This query gives the same result:

<codeblock>
SELECT * FROM obj WHERE rowid IN carray(0x7b3830, 10);
SELECT * FROM obj WHERE rowid IN carray($PTR, 10);
</codeblock>

proc chng {date desc {options {}}} {
  global nChng aChng xrefChng
  set aChng($nChng) [list $date $desc $options]
  set xrefChng($date) $nChng
  incr nChng
}

chng {2017-08-31 (3.20.0)} {
chng {2017-07-20 (3.20.0)} {
<li> Update the text of error messages returned by [sqlite3_errmsg()] for some
     error codes.
<li> Add new interfaces [sqlite3_bind_pointer()], [sqlite3_result_pointer()], and
     [sqlite3_value_pointer()].  Update the [carray(PTR,N)] and 
     [https://www.sqlite.org/src/file/ext/misc/remember.c | remember(V,PTR)]
     extensions to require the use of [sqlite3_bind_pointer()] to set their
     pointer values.

<li> Add the -withoutnulls option to the [TCL interface eval method].
<li> Enhance the [sqlite3_analyzer.exe] utility program so that it shows
     the number of bytes of metadata on btree pages.
<li> The [SQLITE_DBCONFIG_ENABLE_QPSG] run-time option and the
     [SQLITE_ENABLE_QPSG] compile-time option enable the
     [query planner stability guarantee].  See also ticket
     [https://www.sqlite.org/src/info/892fc34f173e99d8|892fc34f173e99d8]
<li> Miscellaneous optimizations result in a 2% reduction in CPU cycles.
<p><b>Bug Fixes:</b>
<li> Ensure that the query planner knows that any column of a 
     [flattening optimization|flattened] LEFT JOIN can be NULL even 
     if that column is labeled with "NOT NULL". Fix for ticket 
     [https://sqlite.org/src/info/892fc34f173e99d8|892fc34f173e99d8].
}