Documentation Source Text

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Changes to pages/carray.in.

     3      3   <fancy_format>
     4      4   
     5      5   <h1>Overview</h1>
     6      6   
     7      7   <p>Carray($PTR,$N) is a [table-valued function] with a single column (named
     8      8   "value") and zero or more rows.
     9      9   The "value" of each row in the carray() is taken from a C-language array
    10         -that is $N elements long and begins at address $PTR.
           10  +that is $N elements long.  $PTR is a pointer to the beginning of the array.
    11     11   In this way, the carray() function provides a convenient mechanism to
    12     12   bind C-language arrays to SQL queries.
    13     13   
    14     14   <h1>Availability</h1>
    15     15   
    16     16   <p>The carray() function is not compiled into SQLite by default.
    17     17   It is available as a [loadable extension] in the
    18     18   [https://www.sqlite.org/src/artifact?ci=trunk&filename=ext/misc/carray.c|ext/misc/carray.c]
    19     19   source file.
    20     20   
    21         -<p>The carray() function is dangerous.  The first parameter is
    22         -a 64-bit integer which gets cast into a pointer to an array.  In an
    23         -application that runs user-generated or untrusted SQL, the carray()
    24         -function could be used to crash the application or to leak sensitive 
    25         -information.  For that
    26         -reason, the carray() function will never be a standard part of SQLite.
    27         -Carray() will only be available in applications that 
    28         -deliberately request it.  Presumably, applications that deliberately
    29         -link carray() will also have protections in place to prevent carray()
    30         -from being misused.
    31         -
    32     21   <h1>Details</h1>
    33     22   
    34     23   <p>The carray() function takes two or three arguments.
    35         -The first argument is a 64-bit integer that will be cast into a pointer
    36         -to the C-language array that is to be returned by the function.  The
    37         -second argument is the number of elements in the array.  The optional
           24  +The first argument is a pointer to an array.  Since pointer values cannot
           25  +be specified directly in SQL, the first argument must be a [parameter] that
           26  +is bound to a pointer value using the [sqlite3_bind_pointer()] interface.
           27  +The second argument is the number of elements in the array.  The optional
    38     28   third argument is a string that determines the datatype of the elements
    39     29   in the C-language array.  Allowed values for the third argument are:
    40     30   
    41     31   <ol>
    42     32   <li> 'int32'
    43     33   <li> 'int64'
    44     34   <li> 'double'
................................................................................
    45     35   <li> 'char*'
    46     36   </ol>
    47     37   
    48     38   <p>The default datatype is 'int32'.
    49     39   
    50     40   <p>The carray() function can be used in the FROM clause of a query.
    51     41   For example, to query two entries from the OBJ table using rowids
    52         -taken from a C-language array at address 0x7b3830:
           42  +taken from a C-language array at address $PTR.
    53     43   
    54     44   <codeblock>
    55         -SELECT obj.* FROM obj, carray(0x7b3830, 10) AS x
           45  +SELECT obj.* FROM obj, carray($PTR, 10) AS x
    56     46    WHERE obj.rowid=x.value;
    57     47   </codeblock>
    58     48   
    59     49   <p>This query gives the same result:
    60     50   
    61     51   <codeblock>
    62         -SELECT * FROM obj WHERE rowid IN carray(0x7b3830, 10);
           52  +SELECT * FROM obj WHERE rowid IN carray($PTR, 10);
    63     53   </codeblock>

Changes to pages/changes.in.

    17     17   proc chng {date desc {options {}}} {
    18     18     global nChng aChng xrefChng
    19     19     set aChng($nChng) [list $date $desc $options]
    20     20     set xrefChng($date) $nChng
    21     21     incr nChng
    22     22   }
    23     23   
    24         -chng {2017-08-31 (3.20.0)} {
           24  +chng {2017-07-20 (3.20.0)} {
    25     25   <li> Update the text of error messages returned by [sqlite3_errmsg()] for some
    26     26        error codes.
    27     27   <li> Add new interfaces [sqlite3_bind_pointer()], [sqlite3_result_pointer()], and
    28     28        [sqlite3_value_pointer()].  Update the [carray(PTR,N)] and 
    29     29        [https://www.sqlite.org/src/file/ext/misc/remember.c | remember(V,PTR)]
    30     30        extensions to require the use of [sqlite3_bind_pointer()] to set their
    31     31        pointer values.
................................................................................
    77     77   <li> Add the -withoutnulls option to the [TCL interface eval method].
    78     78   <li> Enhance the [sqlite3_analyzer.exe] utility program so that it shows
    79     79        the number of bytes of metadata on btree pages.
    80     80   <li> The [SQLITE_DBCONFIG_ENABLE_QPSG] run-time option and the
    81     81        [SQLITE_ENABLE_QPSG] compile-time option enable the
    82     82        [query planner stability guarantee].  See also ticket
    83     83        [https://www.sqlite.org/src/info/892fc34f173e99d8|892fc34f173e99d8]
           84  +<li> Miscellaneous optimizations result in a 2% reduction in CPU cycles.
    84     85   <p><b>Bug Fixes:</b>
    85     86   <li> Ensure that the query planner knows that any column of a 
    86     87        [flattening optimization|flattened] LEFT JOIN can be NULL even 
    87     88        if that column is labeled with "NOT NULL". Fix for ticket 
    88     89        [https://sqlite.org/src/info/892fc34f173e99d8|892fc34f173e99d8].
    89     90   }
    90     91