Fossil SCM

fossil-scm / extsrc / sqlite3.h
Source Blame History 1830 lines
d452c5c… brickviking 1 ** <a href="http://fossil-scm.org/">Fossil configuration management
3c639f7… drh 2 ** [sqlite_version()] and [sqlite_source_id()].
17f9878… drh 3 #define SQLITE_VERSION "3.53.0"
17f9878… drh 4 #define SQLITE_VERSION_NUMBER 3053000
0201a1e… drh 5 #define SQLITE_SOURCE_ID "2026-04-07 09:15:21 c8121593fa455cd43b3878f8b65ebac47c07dab4b8ce081aa34b14fc9440afbc"
dc45faa… drh 6 #define SQLITE_SCM_BRANCH "trunk"
17f9878… drh 7 #define SQLITE_SCM_TAGS ""
0201a1e… drh 8 #define SQLITE_SCM_DATETIME "2026-04-07T09:15:21.538Z"
746a963… drh 9 ** ^The sqlite3_version[] string constant contains the text of the
746a963… drh 10 ** [SQLITE_VERSION] macro. ^The sqlite3_libversion() function returns a
746a963… drh 11 ** pointer to the sqlite3_version[] string constant. The sqlite3_libversion()
3c639f7… drh 12 ** See also: [sqlite_version()] and [sqlite_source_id()].
746a963… drh 13 ** semicolon-separated SQL statements passed into its 2nd argument,
746a963… drh 14 ** entry represents the name of a corresponding result column as obtained
aa33292… drh 15 ** <li> The application must not dereference the arrays or string pointers
aa33292… drh 16 ** passed as the 3rd and 4th callback parameters after it returns.
104c079… drh 17 #define SQLITE_ERROR_RESERVESIZE (SQLITE_ERROR | (4<<8))
104c079… drh 18 #define SQLITE_ERROR_KEY (SQLITE_ERROR | (5<<8))
104c079… drh 19 #define SQLITE_ERROR_UNABLE (SQLITE_ERROR | (6<<8))
16ee395… drh 20 #define SQLITE_IOERR_IN_PAGE (SQLITE_IOERR | (34<<8))
104c079… drh 21 #define SQLITE_IOERR_BADKEY (SQLITE_IOERR | (35<<8))
104c079… drh 22 #define SQLITE_IOERR_CODEC (SQLITE_IOERR | (36<<8))
ad59a04… drh 23 #define SQLITE_OK_SYMLINK (SQLITE_OK | (2<<8)) /* internal only */
746a963… drh 24 ** [sqlite3_open_v2()] has historically been a no-op and might become an
66899f8… drh 25 **
66899f8… drh 26 ** The SQLITE_IOCAP_SUBPAGE_READ property means that it is ok to read
66899f8… drh 27 ** from the database file in amounts that are not a multiple of the
66899f8… drh 28 ** page size and that do not begin at a page boundary. Without this
66899f8… drh 29 ** property, SQLite is careful to only do full-page reads and write
66899f8… drh 30 ** on aligned pages, with the one exception that it will do a sub-page
66899f8… drh 31 ** read of the first page to access the database header.
66899f8… drh 32 #define SQLITE_IOCAP_SUBPAGE_READ 0x00008000
746a963… drh 33 ** least restrictive to most restrictive.
3b99d2c… drh 34 ** xLock() is always one of SHARED, RESERVED, PENDING, or EXCLUSIVE, never
3b99d2c… drh 35 ** If the lock is already at or below the requested lock state, then the call
cd50820… drh 36 ** PENDING, or EXCLUSIVE lock on the file. It returns, via its output
cd50820… drh 37 ** pointer parameter, true if such a lock exists and false otherwise.
66899f8… drh 38 ** <li> [SQLITE_IOCAP_SUBPAGE_READ]
92871e0… drh 39 ** The SQLITE_FCNTL_SYNC_OMITTED file-control is no longer used.
746a963… drh 40 ** all [VFSes] in the VFS stack. The names of all VFS shims and the
746a963… drh 41 ** of type "[sqlite3_vfs] **". This opcode will set *X
5493cc7… drh 42 ** <li>[[SQLITE_FCNTL_NULL_IO]]
5493cc7… drh 43 ** The [SQLITE_FCNTL_NULL_IO] opcode sets the low-level file descriptor
5493cc7… drh 44 ** or file handle for the [sqlite3_file] object such that it will no longer
5493cc7… drh 45 ** read or write to the database file.
5493cc7… drh 46 **
d23f1ab… drh 47 ** <li>[[SQLITE_FCNTL_BLOCK_ON_CONNECT]]
d23f1ab… drh 48 ** The [SQLITE_FCNTL_BLOCK_ON_CONNECT] opcode is used to configure the
d23f1ab… drh 49 ** VFS to block when taking a SHARED lock to connect to a wal mode database.
d23f1ab… drh 50 ** This is used to implement the functionality associated with
d23f1ab… drh 51 ** SQLITE_SETLK_BLOCK_ON_CONNECT.
d23f1ab… drh 52 **
746a963… drh 53 ** transaction open on the database or not. It is only available on unix. The
f8a29b2… drh 54 ** The [SQLITE_FCNTL_CKSM_FILE] opcode is for use internally by the
92871e0… drh 55 **
92871e0… drh 56 ** <li>[[SQLITE_FCNTL_FILESTAT]]
92871e0… drh 57 ** The [SQLITE_FCNTL_FILESTAT] opcode returns low-level diagnostic information
92871e0… drh 58 ** about the [sqlite3_file] objects used access the database and journal files
92871e0… drh 59 ** for the given schema. The fourth parameter to [sqlite3_file_control()]
92871e0… drh 60 ** should be an initialized [sqlite3_str] pointer. JSON text describing
92871e0… drh 61 ** various aspects of the sqlite3_file object is appended to the sqlite3_str.
92871e0… drh 62 ** The SQLITE_FCNTL_FILESTAT opcode is usually a no-op, unless compile-time
92871e0… drh 63 ** options are used to enable it.
5493cc7… drh 64 #define SQLITE_FCNTL_NULL_IO 43
d23f1ab… drh 65 #define SQLITE_FCNTL_BLOCK_ON_CONNECT 44
92871e0… drh 66 #define SQLITE_FCNTL_FILESTAT 45
92871e0… drh 67
ad59a04… drh 68 /* reserved file-control numbers:
ad59a04… drh 69 ** 101
ad59a04… drh 70 ** 102
ad59a04… drh 71 ** 103
ad59a04… drh 72 */
ad59a04… drh 73
d326547… drh 74 ** ^The xSetSystemCall(), xGetSystemCall(), and xNextSystemCall() interfaces
746a963… drh 75 ** initialized when [sqlite3_open()] is called if it has not been initialized
2516fca… drh 76 **
2516fca… drh 77 ** For most configuration options, the sqlite3_config() interface
2516fca… drh 78 ** may only be invoked prior to library initialization using
2516fca… drh 79 ** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
2516fca… drh 80 ** The exceptional configuration options that may be invoked at any time
2516fca… drh 81 ** are called "anytime configuration options".
2516fca… drh 82 ** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
2516fca… drh 83 ** [sqlite3_shutdown()] with a first argument that is not an anytime
ad59a04… drh 84 ** configuration option, then the sqlite3_config() call will
ad59a04… drh 85 ** return SQLITE_MISUSE.
2516fca… drh 86 ** Note, however, that ^sqlite3_config() can be called as part of the
2516fca… drh 87 ** implementation of an application-defined [sqlite3_os_init()].
2516fca… drh 88 ** Most of the configuration options for sqlite3_config()
2516fca… drh 89 ** will only work if invoked prior to [sqlite3_initialize()] or after
2516fca… drh 90 ** [sqlite3_shutdown()]. The few exceptions to this rule are called
2516fca… drh 91 ** "anytime configuration options".
2516fca… drh 92 ** ^Calling [sqlite3_config()] with a first argument that is not an
2516fca… drh 93 ** anytime configuration option in between calls to [sqlite3_initialize()] and
2516fca… drh 94 ** [sqlite3_shutdown()] is a no-op that returns SQLITE_MISUSE.
2516fca… drh 95 **
2516fca… drh 96 ** The set of anytime configuration options can change (by insertions
2516fca… drh 97 ** and/or deletions) from one release of SQLite to the next.
2516fca… drh 98 ** As of SQLite version 3.42.0, the complete set of anytime configuration
2516fca… drh 99 ** options is:
2516fca… drh 100 ** <ul>
2516fca… drh 101 ** <li> SQLITE_CONFIG_LOG
2516fca… drh 102 ** <li> SQLITE_CONFIG_PCACHE_HDRSZ
2516fca… drh 103 ** </ul>
2516fca… drh 104 **
746a963… drh 105 ** routines with a wrapper that simulates memory allocation failure or
746a963… drh 106 ** <dd> ^The SQLITE_CONFIG_SMALL_MALLOC option takes a single argument of
746a963… drh 107 ** but some applications might prefer to run slower in exchange for
746a963… drh 108 ** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes a single argument of type int,
746a963… drh 109 ** of -1024*N bytes if N is negative. ^If additional
746a963… drh 110 ** in place of the mutex routines built into SQLite.)^ ^SQLite makes a copy of
679265a… drh 111 ** the default size of [lookaside memory] on each [database connection].
679265a… drh 112 ** size of each lookaside buffer slot ("sz") and the second is the number of
679265a… drh 113 ** slots allocated to each database connection ("cnt").)^
679265a… drh 114 ** ^(SQLITE_CONFIG_LOOKASIDE sets the <i>default</i> lookaside size.
679265a… drh 115 ** The [SQLITE_DBCONFIG_LOOKASIDE] option to [sqlite3_db_config()] can
679265a… drh 116 ** be used to change the lookaside configuration on individual connections.)^
679265a… drh 117 ** The [-DSQLITE_DEFAULT_LOOKASIDE] option can be used to change the
679265a… drh 118 ** default lookaside configuration at compile-time.
679265a… drh 119 ** </dd>
746a963… drh 120 ** is a pointer to an [sqlite3_pcache_methods2] object. SQLite copies off
746a963… drh 121 ** a log message after formatting via [sqlite3_snprintf()].
e4d2c1d… drh 122 ** negative value for this option restores the default behavior.
452f8e1… drh 123 **
452f8e1… drh 124 ** [[SQLITE_CONFIG_ROWID_IN_VIEW]]
452f8e1… drh 125 ** <dt>SQLITE_CONFIG_ROWID_IN_VIEW
452f8e1… drh 126 ** <dd>The SQLITE_CONFIG_ROWID_IN_VIEW option enables or disables the ability
452f8e1… drh 127 ** for VIEWs to have a ROWID. The capability can only be enabled if SQLite is
452f8e1… drh 128 ** compiled with -DSQLITE_ALLOW_ROWID_IN_VIEW, in which case the capability
452f8e1… drh 129 ** defaults to on. This configuration option queries the current setting or
452f8e1… drh 130 ** changes the setting to off or on. The argument is a pointer to an integer.
452f8e1… drh 131 ** If that integer initially holds a value of 1, then the ability for VIEWs to
452f8e1… drh 132 ** have ROWIDs is activated. If the integer initially holds zero, then the
452f8e1… drh 133 ** ability is deactivated. Any other initial value for the integer leaves the
452f8e1… drh 134 ** setting unchanged. After changes, if any, the integer is written with
452f8e1… drh 135 ** a 1 or 0, if the ability for VIEWs to have ROWIDs is on or off. If SQLite
452f8e1… drh 136 ** is compiled without -DSQLITE_ALLOW_ROWID_IN_VIEW (which is the usual and
452f8e1… drh 137 ** recommended case) then the integer is always filled with zero, regardless
452f8e1… drh 138 ** if its initial value.
71ed8cb… drh 139 #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
71ed8cb… drh 140 #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
71ed8cb… drh 141 #define SQLITE_CONFIG_SERIALIZED 3 /* nil */
71ed8cb… drh 142 #define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
71ed8cb… drh 143 #define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
71ed8cb… drh 144 #define SQLITE_CONFIG_SCRATCH 6 /* No longer used */
71ed8cb… drh 145 #define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
71ed8cb… drh 146 #define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
71ed8cb… drh 147 #define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
71ed8cb… drh 148 #define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
71ed8cb… drh 149 #define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
71ed8cb… drh 150 /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
71ed8cb… drh 151 #define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
71ed8cb… drh 152 #define SQLITE_CONFIG_PCACHE 14 /* no-op */
71ed8cb… drh 153 #define SQLITE_CONFIG_GETPCACHE 15 /* no-op */
71ed8cb… drh 154 #define SQLITE_CONFIG_LOG 16 /* xFunc, void* */
71ed8cb… drh 155 #define SQLITE_CONFIG_URI 17 /* int */
71ed8cb… drh 156 #define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */
71ed8cb… drh 157 #define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */
71ed8cb… drh 158 #define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */
71ed8cb… drh 159 #define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */
452f8e1… drh 160 #define SQLITE_CONFIG_ROWID_IN_VIEW 30 /* int* */
935cd45… drh 161 ** can be passed as the second parameter to the [sqlite3_db_config()] interface.
935cd45… drh 162 **
746a963… drh 163 ** The [sqlite3_db_config()] interface is a var-args function. It takes a
935cd45… drh 164 ** variable number of parameters, though always at least two. The number of
935cd45… drh 165 ** parameters passed into sqlite3_db_config() depends on which of these
935cd45… drh 166 ** constants is given as the second parameter. This documentation page
935cd45… drh 167 ** refers to parameters beyond the second as "arguments". Thus, when this
935cd45… drh 168 ** page says "the N-th argument" it means "the N-th parameter past the
935cd45… drh 169 ** configuration option" or "the (N+2)-th parameter to sqlite3_db_config()".
88bc7cf… drh 170 ** <dd> The SQLITE_DBCONFIG_LOOKASIDE option is used to adjust the
679265a… drh 171 ** configuration of the [lookaside memory allocator] within a database
88bc7cf… drh 172 ** connection.
88bc7cf… drh 173 ** The arguments to the SQLITE_DBCONFIG_LOOKASIDE option are <i>not</i>
88bc7cf… drh 174 ** in the [DBCONFIG arguments|usual format].
935cd45… drh 175 ** The SQLITE_DBCONFIG_LOOKASIDE option takes three arguments, not two,
935cd45… drh 176 ** so that a call to [sqlite3_db_config()] that uses SQLITE_DBCONFIG_LOOKASIDE
935cd45… drh 177 ** should have a total of five parameters.
679265a… drh 178 ** <ol>
679265a… drh 179 ** <li><p>The first argument ("buf") is a
679265a… drh 180 ** The first argument may be NULL in which case SQLite will allocate the
679265a… drh 181 ** lookaside buffer itself using [sqlite3_malloc()].
679265a… drh 182 ** <li><P>The second argument ("sz") is the
679265a… drh 183 ** size of each lookaside buffer slot. Lookaside is disabled if "sz"
679265a… drh 184 ** is less than 8. The "sz" argument should be a multiple of 8 less than
679265a… drh 185 ** 65536. If "sz" does not meet this constraint, it is reduced in size until
679265a… drh 186 ** it does.
ad59a04… drh 187 ** <li><p>The third argument ("cnt") is the number of slots.
ad59a04… drh 188 ** Lookaside is disabled if "cnt"is less than 1.
ad59a04… drh 189 * The "cnt" value will be reduced, if necessary, so
ad59a04… drh 190 ** that the product of "sz" and "cnt" does not exceed 2,147,418,112. The "cnt"
679265a… drh 191 ** parameter is usually chosen so that the product of "sz" and "cnt" is less
679265a… drh 192 ** than 1,000,000.
679265a… drh 193 ** </ol>
679265a… drh 194 ** <p>If the "buf" argument is not NULL, then it must
679265a… drh 195 ** point to a memory buffer with a size that is greater than
679265a… drh 196 ** or equal to the product of "sz" and "cnt".
679265a… drh 197 ** The buffer must be aligned to an 8-byte boundary.
679265a… drh 198 ** The lookaside memory
679265a… drh 199 ** when the value returned by [SQLITE_DBSTATUS_LOOKASIDE_USED] is zero.
679265a… drh 200 ** [SQLITE_BUSY].
679265a… drh 201 ** If the "buf" argument is NULL and an attempt
679265a… drh 202 ** to allocate memory based on "sz" and "cnt" fails, then
679265a… drh 203 ** lookaside is silently disabled.
679265a… drh 204 ** <p>
679265a… drh 205 ** The [SQLITE_CONFIG_LOOKASIDE] configuration option can be used to set the
679265a… drh 206 ** default lookaside configuration at initialization. The
679265a… drh 207 ** [-DSQLITE_DEFAULT_LOOKASIDE] option can be used to set the default lookaside
679265a… drh 208 ** configuration at compile-time. Typical values for lookaside are 1200 for
679265a… drh 209 ** "sz" and 40 to 100 for "cnt".
679265a… drh 210 ** </dd>
88bc7cf… drh 211 ** [foreign key constraints]. This is the same setting that is
88bc7cf… drh 212 ** enabled or disabled by the [PRAGMA foreign_keys] statement.
88bc7cf… drh 213 ** triggers in the main database schema or in the schemas of [ATTACH]-ed
88bc7cf… drh 214 ** There must be two additional arguments.
dc45faa… drh 215 ** <dd> ^This option is used to enable or disable using the
dc45faa… drh 216 ** [fts3_tokenizer()] function - part of the [FTS3] full-text search engine
dc45faa… drh 217 ** extension - without using bound parameters as the parameters. Doing so
dc45faa… drh 218 ** is disabled by default. There must be two additional arguments. The first
dc45faa… drh 219 ** argument is an integer. If it is passed 0, then using fts3_tokenizer()
dc45faa… drh 220 ** without bound parameters is disabled. If it is passed a positive value,
dc45faa… drh 221 ** then calling fts3_tokenizer without bound parameters is enabled. If it
dc45faa… drh 222 ** is passed a negative value, this setting is not modified - this can be
dc45faa… drh 223 ** used to query for the current setting. The second parameter is a pointer
dc45faa… drh 224 ** to an integer into which is written 0 or 1 to indicate the current value
dc45faa… drh 225 ** of this setting (after it is modified, if applicable). The second
dc45faa… drh 226 ** parameter may be a NULL pointer, in which case the value of the setting
dc45faa… drh 227 ** is not reported back. Refer to [FTS3] documentation for further details.
dc45faa… drh 228 ** </dd>
88bc7cf… drh 229 ** There must be two additional arguments.
746a963… drh 230 ** If the first argument is -1, then no changes are made to the state of either
746a963… drh 231 ** the C-API or the SQL function.
88bc7cf… drh 232 ** schema. This option does not follow the
88bc7cf… drh 233 ** [DBCONFIG arguments|usual SQLITE_DBCONFIG argument format].
935cd45… drh 234 ** This option takes exactly one additional argument so that the
935cd45… drh 235 ** [sqlite3_db_config()] call has a total of three parameters. The
935cd45… drh 236 ** extra argument must be a pointer to a constant UTF8 string which
935cd45… drh 237 ** will become the new schema name in place of "main". ^SQLite does
935cd45… drh 238 ** not make a copy of the new main schema name string, so the application
935cd45… drh 239 ** must ensure that the argument passed into SQLITE_DBCONFIG MAINDBNAME
935cd45… drh 240 ** is unchanged until after the database connection closes.
88bc7cf… drh 241 ** <dd> Usually, when a database in [WAL mode] is closed or detached from a
88bc7cf… drh 242 ** database handle, SQLite checks if if there are other connections to the
88bc7cf… drh 243 ** same database, and if there are no other database connection (if the
88bc7cf… drh 244 ** connection being closed is the last open connection to the database),
88bc7cf… drh 245 ** then SQLite performs a [checkpoint] before closing the connection and
88bc7cf… drh 246 ** deletes the WAL file. The SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE option can
935cd45… drh 247 ** be used to override that behavior. The first argument passed to this
935cd45… drh 248 ** operation (the third parameter to [sqlite3_db_config()]) is an integer
935cd45… drh 249 ** which is positive to disable checkpoints-on-close, or zero (the default)
935cd45… drh 250 ** to enable them, and negative to leave the setting unchanged.
935cd45… drh 251 ** The second argument (the fourth parameter) is a pointer to an integer
746a963… drh 252 ** the legacy behavior of the [ALTER TABLE RENAME] command such that it
a6cc3da… drh 253 ** <dt>SQLITE_DBCONFIG_DQS_DML</dt>
a6cc3da… drh 254 ** <dt>SQLITE_DBCONFIG_DQS_DDL</dt>
a6cc3da… drh 255 ** <dt>SQLITE_DBCONFIG_TRUSTED_SCHEMA</dt>
a6cc3da… drh 256 ** <dt>SQLITE_DBCONFIG_LEGACY_FILE_FORMAT</dt>
746a963… drh 257 ** created database files to have a schema format version number (the 4-byte
a6cc3da… drh 258 ** is now scarcely any need to generate database files that are compatible
f8a29b2… drh 259 ** either generated columns or descending indexes.
2516fca… drh 260 ** </dd>
2516fca… drh 261 **
2516fca… drh 262 ** [[SQLITE_DBCONFIG_STMT_SCANSTATUS]]
a6cc3da… drh 263 ** <dt>SQLITE_DBCONFIG_STMT_SCANSTATUS</dt>
2516fca… drh 264 ** <dd>The SQLITE_DBCONFIG_STMT_SCANSTATUS option is only useful in
4f76459… drh 265 ** [SQLITE_ENABLE_STMT_SCANSTATUS] builds. In this case, it sets or clears
4f76459… drh 266 ** a flag that enables collection of run-time performance statistics
4f76459… drh 267 ** used by [sqlite3_stmt_scanstatus_v2()] and the [nexec and ncycle]
4f76459… drh 268 ** columns of the [bytecode virtual table].
4f76459… drh 269 ** For statistics to be collected, the flag must be set on
4f76459… drh 270 ** the database handle both when the SQL statement is
4f76459… drh 271 ** [sqlite3_prepare|prepared] and when it is [sqlite3_step|stepped].
4f76459… drh 272 ** The flag is set (collection of statistics is enabled) by default.
4f76459… drh 273 ** <p>This option takes two arguments: an integer and a pointer to
746a963… drh 274 ** an integer. The first argument is 1, 0, or -1 to enable, disable, or
a6cc3da… drh 275 ** leave unchanged the statement scanstatus option. If the second argument
a6cc3da… drh 276 ** is not NULL, then the value of the statement scanstatus setting after
a6cc3da… drh 277 ** processing the first argument is written into the integer that the second
a6cc3da… drh 278 ** argument points to.
a6cc3da… drh 279 ** </dd>
2516fca… drh 280 **
2516fca… drh 281 ** [[SQLITE_DBCONFIG_REVERSE_SCANORDER]]
a6cc3da… drh 282 ** <dt>SQLITE_DBCONFIG_REVERSE_SCANORDER</dt>
a6cc3da… drh 283 ** <dd>The SQLITE_DBCONFIG_REVERSE_SCANORDER option changes the default order
2516fca… drh 284 ** in which tables and indexes are scanned so that the scans start at the end
2516fca… drh 285 ** and work toward the beginning rather than starting at the beginning and
a6cc3da… drh 286 ** working toward the end. Setting SQLITE_DBCONFIG_REVERSE_SCANORDER is the
88bc7cf… drh 287 ** same as setting [PRAGMA reverse_unordered_selects]. <p>This option takes
a6cc3da… drh 288 ** two arguments which are an integer and a pointer to an integer. The first
a6cc3da… drh 289 ** argument is 1, 0, or -1 to enable, disable, or leave unchanged the
a6cc3da… drh 290 ** reverse scan order flag, respectively. If the second argument is not NULL,
a6cc3da… drh 291 ** then 0 or 1 is written into the integer that the second argument points to
a6cc3da… drh 292 ** depending on if the reverse scan order flag is set after processing the
a6cc3da… drh 293 ** first argument.
a6cc3da… drh 294 ** </dd>
a6cc3da… drh 295 **
88bc7cf… drh 296 ** [[SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE]]
88bc7cf… drh 297 ** <dt>SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE</dt>
88bc7cf… drh 298 ** <dd>The SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE option enables or disables
88bc7cf… drh 299 ** the ability of the [ATTACH DATABASE] SQL command to create a new database
88bc7cf… drh 300 ** file if the database filed named in the ATTACH command does not already
88bc7cf… drh 301 ** exist. This ability of ATTACH to create a new database is enabled by
88bc7cf… drh 302 ** default. Applications can disable or reenable the ability for ATTACH to
88bc7cf… drh 303 ** create new database files using this DBCONFIG option.<p>
88bc7cf… drh 304 ** This option takes two arguments which are an integer and a pointer
88bc7cf… drh 305 ** to an integer. The first argument is 1, 0, or -1 to enable, disable, or
88bc7cf… drh 306 ** leave unchanged the attach-create flag, respectively. If the second
88bc7cf… drh 307 ** argument is not NULL, then 0 or 1 is written into the integer that the
88bc7cf… drh 308 ** second argument points to depending on if the attach-create flag is set
88bc7cf… drh 309 ** after processing the first argument.
88bc7cf… drh 310 ** </dd>
88bc7cf… drh 311 **
88bc7cf… drh 312 ** [[SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE]]
88bc7cf… drh 313 ** <dt>SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE</dt>
88bc7cf… drh 314 ** <dd>The SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE option enables or disables the
88bc7cf… drh 315 ** ability of the [ATTACH DATABASE] SQL command to open a database for writing.
88bc7cf… drh 316 ** This capability is enabled by default. Applications can disable or
746a963… drh 317 ** reenable this capability using the current DBCONFIG option. If
746a963… drh 318 ** this capability is disabled, the [ATTACH] command will still work,
88bc7cf… drh 319 ** but the database will be opened read-only. If this option is disabled,
88bc7cf… drh 320 ** then the ability to create a new database using [ATTACH] is also disabled,
88bc7cf… drh 321 ** regardless of the value of the [SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE]
88bc7cf… drh 322 ** option.<p>
88bc7cf… drh 323 ** This option takes two arguments which are an integer and a pointer
88bc7cf… drh 324 ** to an integer. The first argument is 1, 0, or -1 to enable, disable, or
88bc7cf… drh 325 ** leave unchanged the ability to ATTACH another database for writing,
88bc7cf… drh 326 ** respectively. If the second argument is not NULL, then 0 or 1 is written
88bc7cf… drh 327 ** into the integer to which the second argument points, depending on whether
88bc7cf… drh 328 ** the ability to ATTACH a read/write database is enabled or disabled
88bc7cf… drh 329 ** after processing the first argument.
88bc7cf… drh 330 ** </dd>
88bc7cf… drh 331 **
88bc7cf… drh 332 ** [[SQLITE_DBCONFIG_ENABLE_COMMENTS]]
88bc7cf… drh 333 ** <dt>SQLITE_DBCONFIG_ENABLE_COMMENTS</dt>
88bc7cf… drh 334 ** <dd>The SQLITE_DBCONFIG_ENABLE_COMMENTS option enables or disables the
88bc7cf… drh 335 ** ability to include comments in SQL text. Comments are enabled by default.
88bc7cf… drh 336 ** An application can disable or reenable comments in SQL text using this
88bc7cf… drh 337 ** DBCONFIG option.<p>
88bc7cf… drh 338 ** This option takes two arguments which are an integer and a pointer
88bc7cf… drh 339 ** to an integer. The first argument is 1, 0, or -1 to enable, disable, or
88bc7cf… drh 340 ** leave unchanged the ability to use comments in SQL text,
88bc7cf… drh 341 ** respectively. If the second argument is not NULL, then 0 or 1 is written
88bc7cf… drh 342 ** into the integer that the second argument points to depending on if
88bc7cf… drh 343 ** comments are allowed in SQL text after processing the first argument.
88bc7cf… drh 344 ** </dd>
88bc7cf… drh 345 **
b8ab8b3… drh 346 ** [[SQLITE_DBCONFIG_FP_DIGITS]]
b8ab8b3… drh 347 ** <dt>SQLITE_DBCONFIG_FP_DIGITS</dt>
b8ab8b3… drh 348 ** <dd>The SQLITE_DBCONFIG_FP_DIGITS setting is a small integer that determines
b8ab8b3… drh 349 ** the number of significant digits that SQLite will attempt to preserve when
b8ab8b3… drh 350 ** converting floating point numbers (IEEE 754 "doubles") into text. The
b8ab8b3… drh 351 ** default value 17, as of SQLite version 3.52.0. The value was 15 in all
b8ab8b3… drh 352 ** prior versions.<p>
b8ab8b3… drh 353 ** This option takes two arguments which are an integer and a pointer
b8ab8b3… drh 354 ** to an integer. The first argument is a small integer, between 3 and 23, or
b8ab8b3… drh 355 ** zero. The FP_DIGITS setting is changed to that small integer, or left
ad59a04… drh 356 ** unaltered if the first argument is zero or out of range. The second argument
b8ab8b3… drh 357 ** is a pointer to an integer. If the pointer is not NULL, then the value of
b8ab8b3… drh 358 ** the FP_DIGITS setting, after possibly being modified by the first
b8ab8b3… drh 359 ** arguments, is written into the integer to which the second argument points.
b8ab8b3… drh 360 ** </dd>
b8ab8b3… drh 361 **
88bc7cf… drh 362 **
88bc7cf… drh 363 ** [[DBCONFIG arguments]] <h3>Arguments To SQLITE_DBCONFIG Options</h3>
88bc7cf… drh 364 **
935cd45… drh 365 ** <p>Most of the SQLITE_DBCONFIG options take two arguments, so that the
935cd45… drh 366 ** overall call to [sqlite3_db_config()] has a total of four parameters.
ad59a04… drh 367 ** The first argument (the third parameter to sqlite3_db_config()) is
ad59a04… drh 368 ** an integer.
ad59a04… drh 369 ** The second argument is a pointer to an integer. If the first argument is 1,
ad59a04… drh 370 ** then the option becomes enabled. If the first integer argument is 0,
ad59a04… drh 371 ** then the option is disabled.
ad59a04… drh 372 ** If the first argument is -1, then the option setting
88bc7cf… drh 373 ** is unchanged. The second argument, the pointer to an integer, may be NULL.
88bc7cf… drh 374 ** If the second argument is not NULL, then a value of 0 or 1 is written into
88bc7cf… drh 375 ** the integer to which the second argument points, depending on whether the
88bc7cf… drh 376 ** setting is disabled or enabled after applying any changes specified by
88bc7cf… drh 377 ** the first argument.
88bc7cf… drh 378 **
88bc7cf… drh 379 ** <p>While most SQLITE_DBCONFIG options use the argument format
b8ab8b3… drh 380 ** described in the previous paragraph, the [SQLITE_DBCONFIG_MAINDBNAME],
b8ab8b3… drh 381 ** [SQLITE_DBCONFIG_LOOKASIDE], and [SQLITE_DBCONFIG_FP_DIGITS] options
b8ab8b3… drh 382 ** are different. See the documentation of those exceptional options for
b8ab8b3… drh 383 ** details.
a6cc3da… drh 384 #define SQLITE_DBCONFIG_STMT_SCANSTATUS 1018 /* int int* */
2516fca… drh 385 #define SQLITE_DBCONFIG_REVERSE_SCANORDER 1019 /* int int* */
88bc7cf… drh 386 #define SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE 1020 /* int int* */
88bc7cf… drh 387 #define SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE 1021 /* int int* */
88bc7cf… drh 388 #define SQLITE_DBCONFIG_ENABLE_COMMENTS 1022 /* int int* */
b8ab8b3… drh 389 #define SQLITE_DBCONFIG_FP_DIGITS 1023 /* int int* */
b8ab8b3… drh 390 #define SQLITE_DBCONFIG_MAX 1023 /* Largest DBCONFIG */
5493cc7… drh 391 ** and that if the number of rows modified by the most recent INSERT, UPDATE,
5493cc7… drh 392 ** For the purposes of this interface, a CREATE TABLE AS SELECT statement
5493cc7… drh 393 ** does not count as an INSERT, UPDATE or DELETE statement and hence the rows
5493cc7… drh 394 ** added to the new table by the CREATE TABLE AS SELECT statement are not
5493cc7… drh 395 ** counted.
f8a29b2… drh 396 ** It returns 1 if an interrupt is currently in effect, or 0 otherwise.
746a963… drh 397 ** ^These routines do not parse the SQL statements and thus
d23f1ab… drh 398 ** CAPI3REF: Set the Setlk Timeout
d23f1ab… drh 399 ** METHOD: sqlite3
d23f1ab… drh 400 **
d23f1ab… drh 401 ** This routine is only useful in SQLITE_ENABLE_SETLK_TIMEOUT builds. If
d23f1ab… drh 402 ** the VFS supports blocking locks, it sets the timeout in ms used by
d23f1ab… drh 403 ** eligible locks taken on wal mode databases by the specified database
d23f1ab… drh 404 ** handle. In non-SQLITE_ENABLE_SETLK_TIMEOUT builds, or if the VFS does
d23f1ab… drh 405 ** not support blocking locks, this function is a no-op.
d23f1ab… drh 406 **
d23f1ab… drh 407 ** Passing 0 to this function disables blocking locks altogether. Passing
d23f1ab… drh 408 ** -1 to this function requests that the VFS blocks for a long time -
d23f1ab… drh 409 ** indefinitely if possible. The results of passing any other negative value
d23f1ab… drh 410 ** are undefined.
d23f1ab… drh 411 **
746a963… drh 412 ** Internally, each SQLite database handle stores two timeout values - the
d23f1ab… drh 413 ** busy-timeout (used for rollback mode databases, or if the VFS does not
d23f1ab… drh 414 ** support blocking locks) and the setlk-timeout (used for blocking locks
d23f1ab… drh 415 ** on wal-mode databases). The sqlite3_busy_timeout() method sets both
d23f1ab… drh 416 ** values, this function sets only the setlk-timeout value. Therefore,
d23f1ab… drh 417 ** to configure separate busy-timeout and setlk-timeout values for a single
d23f1ab… drh 418 ** database handle, call sqlite3_busy_timeout() followed by this function.
d23f1ab… drh 419 **
d23f1ab… drh 420 ** Whenever the number of connections to a wal mode database falls from
d23f1ab… drh 421 ** 1 to 0, the last connection takes an exclusive lock on the database,
d23f1ab… drh 422 ** then checkpoints and deletes the wal file. While it is doing this, any
d23f1ab… drh 423 ** new connection that tries to read from the database fails with an
d23f1ab… drh 424 ** SQLITE_BUSY error. Or, if the SQLITE_SETLK_BLOCK_ON_CONNECT flag is
d23f1ab… drh 425 ** passed to this API, the new connection blocks until the exclusive lock
d23f1ab… drh 426 ** has been released.
d23f1ab… drh 427 */
d23f1ab… drh 428 SQLITE_API int sqlite3_setlk_timeout(sqlite3*, int ms, int flags);
d23f1ab… drh 429
d23f1ab… drh 430 /*
d23f1ab… drh 431 ** CAPI3REF: Flags for sqlite3_setlk_timeout()
d23f1ab… drh 432 */
d23f1ab… drh 433 #define SQLITE_SETLK_BLOCK_ON_CONNECT 0x01
d23f1ab… drh 434
d23f1ab… drh 435 /*
746a963… drh 436 ** Definition: A <b>result table</b> is a memory data structure created by the
746a963… drh 437 ** a no-op if it is called with a NULL pointer. Passing a NULL pointer
746a963… drh 438 ** ^If M is the size of the prior allocation, then min(N,M) bytes of the
746a963… drh 439 ** prior allocation are copied into the beginning of the buffer returned
746a963… drh 440 ** ^The sqlite3_realloc64(X,N) interface works the same as
746a963… drh 441 ** but not overhead added by any underlying system library
452f8e1… drh 442 ** CAPI3REF: Deprecated Tracing And Profiling Functions
452f8e1… drh 443 ** DEPRECATED
f8a29b2… drh 444 ** ^Each call to either sqlite3_trace(D,X,P) or sqlite3_trace_v2(D,M,X,P)
f8a29b2… drh 445 ** overrides (cancels) all prior calls to sqlite3_trace(D,X,P) or
f8a29b2… drh 446 ** sqlite3_trace_v2(D,M,X,P) for the [database connection] D. Each
f8a29b2… drh 447 ** database connection may have at most one trace callback.
746a963… drh 448 ** <dd>The database is opened with [shared cache] enabled, overriding
746a963… drh 449 ** <dd>The database is opened with [shared cache] disabled, overriding
44f067d… drh 450 ** In other words, the database behaves as if
44f067d… drh 451 ** [sqlite3_extended_result_codes(db,1)] were called on the database
f8a29b2… drh 452 ** passed into the xOpen() method of a VFS implementation, or
f8a29b2… drh 453 ** These interfaces are provided for use by [VFS shim] implementations and
b10fbd8… drh 454 ** an array P of N URI Key/Value pairs. The result from
d326547… drh 455 ** <li> sqlite3_db_handle()
70cae0a… drh 456 ** text that describes the error, as either UTF-8 or UTF-16 respectively,
70cae0a… drh 457 ** or NULL if no error message is available.
e4d2c1d… drh 458 ** (See how SQLite handles [invalid UTF] for exceptions to this rule.)
70cae0a… drh 459 ** ^The sqlite3_errstr(E) interface returns the English-language text
07a16b7… drh 460 ** that describes the [result code] E, as UTF-8, or NULL if E is not a
70cae0a… drh 461 ** result code for which a text error message is available.
07a16b7… drh 462 ** sqlite3_error_offset() assumes that the input SQL is UTF-8.
3041904… drh 463
3041904… drh 464 /*
4f76459… drh 465 ** CAPI3REF: Set Error Code And Message
3041904… drh 466 ** METHOD: sqlite3
3041904… drh 467 **
3041904… drh 468 ** Set the error code of the database handle passed as the first argument
3041904… drh 469 ** to errcode, and the error message to a copy of nul-terminated string
3041904… drh 470 ** zErrMsg. If zErrMsg is passed NULL, then the error message is set to
3041904… drh 471 ** the default message associated with the supplied error code. Subsequent
3041904… drh 472 ** calls to [sqlite3_errcode()] and [sqlite3_errmsg()] and similar will
3041904… drh 473 ** return the values set by this routine in place of what was previously
3041904… drh 474 ** set by SQLite itself.
3041904… drh 475 **
3041904… drh 476 ** This function returns SQLITE_OK if the error code and error message are
3041904… drh 477 ** successfully set, SQLITE_NOMEM if an OOM occurs, and SQLITE_MISUSE if
3041904… drh 478 ** the database handle is NULL or invalid.
3041904… drh 479 **
3041904… drh 480 ** The error code and message set by this routine remains in effect until
3041904… drh 481 ** they are changed, either by another call to this routine or until they are
3041904… drh 482 ** changed to by SQLite itself to reflect the result of some subsquent
3041904… drh 483 ** API call.
3041904… drh 484 **
3041904… drh 485 ** This function is intended for use by SQLite extensions or wrappers. The
3041904… drh 486 ** idea is that an extension or wrapper can use this routine to set error
3041904… drh 487 ** messages and error codes and thus behave more like a core SQLite
3041904… drh 488 ** feature from the point of view of an application.
3041904… drh 489 */
3041904… drh 490 SQLITE_API int sqlite3_set_errmsg(sqlite3 *db, int errcode, const char *zErrMsg);
07a16b7… drh 491 ** A concise description of these limits follows, and additional information
07a16b7… drh 492 ** is available at [limits | Limits in SQLite].
07a16b7… drh 493 **
4f76459… drh 494 ** [[SQLITE_LIMIT_PARSER_DEPTH]] ^(<dt>SQLITE_LIMIT_PARSER_DEPTH</dt>
4f76459… drh 495 ** <dd>The maximum depth of the LALR(1) parser stack used to analyze
4f76459… drh 496 ** input SQL statements.</dd>)^
4f76459… drh 497 **
4f76459… drh 498 #define SQLITE_LIMIT_PARSER_DEPTH 12
07a16b7… drh 499 ** These constants define various flags that can be passed into the
077e53a… drh 500 **
077e53a… drh 501 ** [[SQLITE_PREPARE_DONT_LOG]] <dt>SQLITE_PREPARE_DONT_LOG</dt>
077e53a… drh 502 ** <dd>The SQLITE_PREPARE_DONT_LOG flag prevents SQL compiler
077e53a… drh 503 ** errors from being sent to the error log defined by
077e53a… drh 504 ** [SQLITE_CONFIG_LOG]. This can be used, for example, to do test
077e53a… drh 505 ** compiles to see if some SQL syntax is well-formed, without generating
077e53a… drh 506 ** messages on the global error log when it is not. If the test compile
077e53a… drh 507 ** fails, the sqlite3_prepare_v3() call returns the same error indications
077e53a… drh 508 ** with or without this flag; it just omits the call to [sqlite3_log()] that
077e53a… drh 509 ** logs the error.
b9ecacf… drh 510 **
b9ecacf… drh 511 ** [[SQLITE_PREPARE_FROM_DDL]] <dt>SQLITE_PREPARE_FROM_DDL</dt>
73512f4… drh 512 ** <dd>The SQLITE_PREPARE_FROM_DDL flag causes the SQL compiler to enforce
73512f4… drh 513 ** security constraints that would otherwise only be enforced when parsing
73512f4… drh 514 ** the database schema. In other words, the SQLITE_PREPARE_FROM_DDL flag
73512f4… drh 515 ** causes the SQL compiler to treat the SQL statement being prepared as if
73512f4… drh 516 ** it had come from an attacker. When SQLITE_PREPARE_FROM_DDL is used and
73512f4… drh 517 ** [SQLITE_DBCONFIG_TRUSTED_SCHEMA] is off, SQL functions may only be called
73512f4… drh 518 ** if they are tagged with [SQLITE_INNOCUOUS] and virtual tables may only
73512f4… drh 519 ** be used if they are tagged with [SQLITE_VTAB_INNOCUOUS]. Best practice
73512f4… drh 520 ** is to use the SQLITE_PREPARE_FROM_DDL option when preparing any SQL that
73512f4… drh 521 ** is derived from parts of the database schema. In particular, virtual
73512f4… drh 522 ** table implementations that run SQL statements that are derived from
73512f4… drh 523 ** arguments to their CREATE VIRTUAL TABLE statement should always use
73512f4… drh 524 ** [sqlite3_prepare_v3()] and set the SQLITE_PREPARE_FROM_DDL flag to
73512f4… drh 525 ** prevent bypass of the [SQLITE_DBCONFIG_TRUSTED_SCHEMA] security checks.
077e53a… drh 526 #define SQLITE_PREPARE_DONT_LOG 0x10
b9ecacf… drh 527 #define SQLITE_PREPARE_FROM_DDL 0x20
b9ecacf… drh 528 ** [sqlite3_prepare_v3()] has an extra
17f9878… drh 529 ** [SQLITE_PREPARE_FROM_DDL|"prepFlags" option] that is sometimes
b9ecacf… drh 530 ** needed for special purpose or to pass along security restrictions.
c20aa86… drh 531 ** first zero terminator. ^If nByte is positive, then it is the maximum
c20aa86… drh 532 ** number of bytes read from zSql. When nByte is positive, zSql is read
c20aa86… drh 533 ** up to the first zero terminator or until the nByte bytes have been read,
c20aa86… drh 534 ** whichever comes first. ^If nByte is zero, then no prepared
07a16b7… drh 535 ** Note that nByte measures the length of the input in bytes, not
d0730da… drh 536 ** characters, even for the UTF-16 interfaces.
07a16b7… drh 537 ** maximum string length determined by the [SQLITE_LIMIT_LENGTH].
23cb537… drh 538 ** CAPI3REF: Change The EXPLAIN Setting For A Prepared Statement
23cb537… drh 539 ** METHOD: sqlite3_stmt
23cb537… drh 540 **
23cb537… drh 541 ** The sqlite3_stmt_explain(S,E) interface changes the EXPLAIN
23cb537… drh 542 ** setting for [prepared statement] S. If E is zero, then S becomes
23cb537… drh 543 ** a normal prepared statement. If E is 1, then S behaves as if
23cb537… drh 544 ** its SQL text began with "[EXPLAIN]". If E is 2, then S behaves as if
23cb537… drh 545 ** its SQL text began with "[EXPLAIN QUERY PLAN]".
23cb537… drh 546 **
23cb537… drh 547 ** Calling sqlite3_stmt_explain(S,E) might cause S to be reprepared.
23cb537… drh 548 ** SQLite tries to avoid a reprepare, but a reprepare might be necessary
23cb537… drh 549 ** on the first transition into EXPLAIN or EXPLAIN QUERY PLAN mode.
23cb537… drh 550 **
23cb537… drh 551 ** Because of the potential need to reprepare, a call to
23cb537… drh 552 ** sqlite3_stmt_explain(S,E) will fail with SQLITE_ERROR if S cannot be
23cb537… drh 553 ** reprepared because it was created using [sqlite3_prepare()] instead of
23cb537… drh 554 ** the newer [sqlite3_prepare_v2()] or [sqlite3_prepare_v3()] interfaces and
23cb537… drh 555 ** hence has no saved SQL text with which to reprepare.
23cb537… drh 556 **
23cb537… drh 557 ** Changing the explain setting for a prepared statement does not change
23cb537… drh 558 ** the original SQL text for the statement. Hence, if the SQL text originally
23cb537… drh 559 ** began with EXPLAIN or EXPLAIN QUERY PLAN, but sqlite3_stmt_explain(S,0)
23cb537… drh 560 ** is called to convert the statement into an ordinary statement, the EXPLAIN
23cb537… drh 561 ** or EXPLAIN QUERY PLAN keywords will still appear in the sqlite3_sql(S)
23cb537… drh 562 ** output, even though the statement now acts like a normal SQL statement.
23cb537… drh 563 **
23cb537… drh 564 ** This routine returns SQLITE_OK if the explain mode is successfully
23cb537… drh 565 ** changed, or an error code if the explain mode could not be changed.
23cb537… drh 566 ** The explain mode cannot be changed while a statement is active.
23cb537… drh 567 ** Hence, it is good practice to call [sqlite3_reset(S)]
23cb537… drh 568 ** immediately prior to calling sqlite3_stmt_explain(S,E).
23cb537… drh 569 */
23cb537… drh 570 SQLITE_API int sqlite3_stmt_explain(sqlite3_stmt *pStmt, int eMode);
23cb537… drh 571
23cb537… drh 572 /*
07a16b7… drh 573 ** is always the first parameter to [application-defined SQL functions].
b10fbd8… drh 574 ** literals may be replaced by a [parameter] that matches one of the following
13c221a… drh 575 ** either UTF8 if the sixth parameter is SQLITE_UTF8 or SQLITE_UTF8_ZT,
13c221a… drh 576 ** or UTF16 otherwise.
b10fbd8… drh 577 ** found in the first character, which is removed, or in the absence of a BOM
b10fbd8… drh 578 ** terminated. If any NUL characters occur at byte offsets less than
f8a29b2… drh 579 ** ^ (2) The special constant, [SQLITE_STATIC], may be passed to indicate that
13c221a… drh 580 ** ^The sixth argument (the E argument)
13c221a… drh 581 ** to sqlite3_bind_text64(S,K,Z,N,D,E) must be one of
13c221a… drh 582 ** [SQLITE_UTF8], [SQLITE_UTF8_ZT], [SQLITE_UTF16], [SQLITE_UTF16BE],
13c221a… drh 583 ** or [SQLITE_UTF16LE] to specify the encoding of the text in the
13c221a… drh 584 ** third parameter, Z. The special value [SQLITE_UTF8_ZT] means that the
13c221a… drh 585 ** string argument is both UTF-8 encoded and is zero-terminated. In other
13c221a… drh 586 ** words, SQLITE_UTF8_ZT means that the Z array is allocated to hold at
13c221a… drh 587 ** least N+1 bytes and that the Z&#91;N&#93; byte is zero. If
13c221a… drh 588 ** the E argument to sqlite3_bind_text64(S,K,Z,N,D,E) is not one of the
92871e0… drh 589 ** P, even if the call to sqlite3_bind_pointer() fails. Due to a
92871e0… drh 590 ** historical design quirk, results are undefined if D is
92871e0… drh 591 ** SQLITE_TRANSIENT. The T parameter should be a static string,
92871e0… drh 592 ** preferably a string literal. The sqlite3_bind_pointer() routine is
92871e0… drh 593 ** part of the [pointer passing interface] added for SQLite 3.20.0.
b10fbd8… drh 594 ** table column that is the origin of a particular result column in a
2a04c64… drh 595 ** sqlite3_step(). But after [version 3.6.23.1] ([dateof:3.6.23.1]),
07a16b7… drh 596 ** or if the statement has never been evaluated, then sqlite3_finalize() returns
f8a29b2… drh 597 ** ^The return code from [sqlite3_reset(S)] indicates whether or not
f8a29b2… drh 598 ** the previous evaluation of prepared statement S completed successfully.
f8a29b2… drh 599 ** ^If [sqlite3_step(S)] has never before been called on S or if
f8a29b2… drh 600 ** [sqlite3_step(S)] has not been called since the previous call
f8a29b2… drh 601 ** to [sqlite3_reset(S)], then [sqlite3_reset(S)] will return
f8a29b2… drh 602 ** [SQLITE_OK].
f8a29b2… drh 603 ** ^The [sqlite3_reset(S)] interface might also return an [error code]
f8a29b2… drh 604 ** if there were no prior errors but the process of resetting
f8a29b2… drh 605 ** the prepared statement caused a new error. ^For example, if an
f8a29b2… drh 606 ** [INSERT] statement with a [RETURNING] clause is only stepped one time,
f8a29b2… drh 607 ** that one call to [sqlite3_step(S)] might return SQLITE_ROW but
f8a29b2… drh 608 ** the overall statement might still fail and the [sqlite3_reset(S)] call
f8a29b2… drh 609 ** might return SQLITE_BUSY if locking constraints prevent the
f8a29b2… drh 610 ** database change from committing. Therefore, it is important that
f8a29b2… drh 611 ** applications check the return code from [sqlite3_reset(S)] even if
f8a29b2… drh 612 ** no prior call to [sqlite3_step(S)] indicated a problem.
b0db6dd… drh 613
b10fbd8… drh 614 ** used inside of triggers, views, CHECK constraints, or other elements of
b10fbd8… drh 615 ** the database schema. This flag is especially recommended for SQL
b10fbd8… drh 616 ** sqlite3_create_window_function() is not NULL, then it is the destructor for
07a16b7… drh 617 ** These constants define integer codes that represent the various
13c221a… drh 618 **
13c221a… drh 619 ** <dl>
13c221a… drh 620 ** [[SQLITE_UTF8]] <dt>SQLITE_UTF8</dt><dd>Text is encoding as UTF-8</dd>
13c221a… drh 621 **
13c221a… drh 622 ** [[SQLITE_UTF16LE]] <dt>SQLITE_UTF16LE</dt><dd>Text is encoding as UTF-16
13c221a… drh 623 ** with each code point being expressed "little endian" - the least significant
13c221a… drh 624 ** byte first. This is the usual encoding, for example on Windows.</dd>
13c221a… drh 625 **
13c221a… drh 626 ** [[SQLITE_UTF16BE]] <dt>SQLITE_UTF16BE</dt><dd>Text is encoding as UTF-16
13c221a… drh 627 ** with each code point being expressed "big endian" - the most significant
13c221a… drh 628 ** byte first. This encoding is less common, but is still sometimes seen,
13c221a… drh 629 ** specially on older systems.
13c221a… drh 630 **
13c221a… drh 631 ** [[SQLITE_UTF16]] <dt>SQLITE_UTF16</dt><dd>Text is encoding as UTF-16
13c221a… drh 632 ** with each code point being expressed either little endian or as big
13c221a… drh 633 ** endian, according to the native endianness of the host computer.
13c221a… drh 634 **
13c221a… drh 635 ** [[SQLITE_ANY]] <dt>SQLITE_ANY</dt><dd>This encoding value may only be used
13c221a… drh 636 ** to declare the preferred text for [application-defined SQL functions]
13c221a… drh 637 ** created using [sqlite3_create_function()] and similar. If the preferred
13c221a… drh 638 ** encoding (the 4th parameter to sqlite3_create_function() - the eTextRep
13c221a… drh 639 ** parameter) is SQLITE_ANY, that indicates that the function does not have
13c221a… drh 640 ** a preference regarding the text encoding of its parameters and can take
13c221a… drh 641 ** any text encoding that the SQLite core find convenient to supply. This
13c221a… drh 642 ** option is deprecated. Please do not use it in new applications.
13c221a… drh 643 **
13c221a… drh 644 ** [[SQLITE_UTF16_ALIGNED]] <dt>SQLITE_UTF16_ALIGNED</dt><dd>This encoding
13c221a… drh 645 ** value may be used as the 3rd parameter (the eTextRep parameter) to
13c221a… drh 646 ** [sqlite3_create_collation()] and similar. This encoding value means
13c221a… drh 647 ** that the application-defined collating sequence created expects its
13c221a… drh 648 ** input strings to be in UTF16 in native byte order, and that the start
13c221a… drh 649 ** of the strings must be aligned to a 2-byte boundary.
13c221a… drh 650 **
13c221a… drh 651 ** [[SQLITE_UTF8_ZT]] <dt>SQLITE_UTF8_ZT</dt><dd>This option can only be
ad59a04… drh 652 ** used to specify the text encoding to strings input to
ad59a04… drh 653 ** [sqlite3_result_text64()] and [sqlite3_bind_text64()].
ad59a04… drh 654 ** The SQLITE_UTF8_ZT encoding means that the input string (call it "z")
13c221a… drh 655 ** is UTF-8 encoded and that it is zero-terminated. If the length parameter
13c221a… drh 656 ** (call it "n") is non-negative, this encoding option means that the caller
13c221a… drh 657 ** guarantees that z array contains at least n+1 bytes and that the z&#91;n&#93;
13c221a… drh 658 ** byte has a value of zero.
13c221a… drh 659 ** This option gives the same output as SQLITE_UTF8, but can be more efficient
13c221a… drh 660 ** by avoiding the need to make a copy of the input string, in some cases.
13c221a… drh 661 ** However, if z is allocated to hold fewer than n+1 bytes or if the
13c221a… drh 662 ** z&#91;n&#93; byte is not zero, undefined behavior may result.
13c221a… drh 663 ** </dl>
13c221a… drh 664 #define SQLITE_UTF8_ZT 16 /* Zero-terminated UTF8 */
f8a29b2… drh 665 ** into using a database file that has had its schema surreptitiously
2edeeee… drh 666 ** The SQLITE_SUBTYPE flag indicates to SQLite that a function might call
2edeeee… drh 667 ** This flag instructs SQLite to omit some corner-case optimizations that
2edeeee… drh 668 ** might disrupt the operation of the [sqlite3_value_subtype()] function,
2edeeee… drh 669 ** causing it to return zero rather than the correct subtype().
72070b3… drh 670 ** All SQL functions that invoke [sqlite3_value_subtype()] should have this
2edeeee… drh 671 ** property. If the SQLITE_SUBTYPE property is omitted, then the return
2edeeee… drh 672 ** value from [sqlite3_value_subtype()] might sometimes be zero even though
2edeeee… drh 673 ** a non-zero subtype was specified by the function argument expression.
2edeeee… drh 674 **
2edeeee… drh 675 ** [[SQLITE_RESULT_SUBTYPE]] <dt>SQLITE_RESULT_SUBTYPE</dt><dd>
2edeeee… drh 676 ** The SQLITE_RESULT_SUBTYPE flag indicates to SQLite that a function might call
2edeeee… drh 677 ** [sqlite3_result_subtype()] to cause a sub-type to be associated with its
2edeeee… drh 678 ** result.
2edeeee… drh 679 ** Every function that invokes [sqlite3_result_subtype()] should have this
2edeeee… drh 680 ** property. If it does not, then the call to [sqlite3_result_subtype()]
07a16b7… drh 681 ** might become a no-op if the function is used as a term in an
2edeeee… drh 682 ** [expression index]. On the other hand, SQL functions that never invoke
2edeeee… drh 683 ** [sqlite3_result_subtype()] should avoid setting this property, as the
2edeeee… drh 684 ** purpose of this property is to disable certain optimizations that are
2edeeee… drh 685 ** incompatible with subtypes.
ff93103… drh 686 **
ff93103… drh 687 ** [[SQLITE_SELFORDER1]] <dt>SQLITE_SELFORDER1</dt><dd>
ff93103… drh 688 ** The SQLITE_SELFORDER1 flag indicates that the function is an aggregate
ff93103… drh 689 ** that internally orders the values provided to the first argument. The
ff93103… drh 690 ** ordered-set aggregate SQL notation with a single ORDER BY term can be
ff93103… drh 691 ** used to invoke this function. If the ordered-set aggregate notation is
ff93103… drh 692 ** used on a function that lacks this flag, then an error is raised. Note
ff93103… drh 693 ** that the ordered-set aggregate syntax is only available if SQLite is
ff93103… drh 694 ** built using the -DSQLITE_ENABLE_ORDERED_SET_AGGREGATES compile-time option.
2edeeee… drh 695 #define SQLITE_RESULT_SUBTYPE 0x001000000
ff93103… drh 696 #define SQLITE_SELFORDER1 0x002000000
07a16b7… drh 697 ** the prior [xColumn] method call that was invoked to extract
ad59a04… drh 698 ** fail if an out-of-memory error occurs while trying to do a
ad59a04… drh 699 ** UTF8&rarr;UTF16 or UTF16&rarr;UTF8 conversion.
ad59a04… drh 700 ** If the input sqlite3_value was not obtained from [sqlite3_value_dup()],
ad59a04… drh 701 ** then valid SQL NULL returns can also be distinguished from
ad59a04… drh 702 ** out-of-memory errors after extracting the value
ad59a04… drh 703 ** by invoking the [sqlite3_errcode()] immediately after the suspicious
ad59a04… drh 704 ** If the input sqlite3_value was obtained from sqlite3_value_dup() then
ad59a04… drh 705 ** it is disconnected from the database connection and so sqlite3_errcode()
ad59a04… drh 706 ** will not work.
ad59a04… drh 707 ** In that case, the only way to distinguish an out-of-memory
ad59a04… drh 708 ** condition from a true SQL NULL is to invoke sqlite3_value_type() on the
ad59a04… drh 709 ** input to see if it is NULL prior to trying to extract the value.
ad59a04… drh 710 ** [sqlite3_value_text(X)], [sqlite3_value_text16(X)],
ad59a04… drh 711 ** [sqlite3_value_text16be(X)],
2edeeee… drh 712 **
dc15083… drh 713 ** Every [application-defined SQL function] that invokes this interface
2edeeee… drh 714 ** should include the [SQLITE_SUBTYPE] property in the text
2edeeee… drh 715 ** encoding argument when the function is [sqlite3_create_function|registered].
2edeeee… drh 716 ** If the [SQLITE_SUBTYPE] property is omitted, then sqlite3_value_subtype()
2edeeee… drh 717 ** might return zero instead of the upstream subtype in some corner cases.
cdaec3a… drh 718 ** object V and returns a pointer to that copy. ^The [sqlite3_value] returned
cdaec3a… drh 719 ** determined by the N parameter on the first successful call. Changing the
b0db6dd… drh 720 ** associate auxiliary data with argument values. If the same argument
b0db6dd… drh 721 ** value is passed to multiple invocations of the same SQL function during
b0db6dd… drh 722 ** query execution, under some circumstances the associated auxiliary data
b0db6dd… drh 723 ** might be preserved. An example of where this might be useful is in a
b0db6dd… drh 724 ** regular-expression matching function. The compiled version of the regular
ad59a04… drh 725 ** expression can be stored as auxiliary data associated with the pattern
ad59a04… drh 726 ** string. Then as long as the pattern string remains the same,
ad59a04… drh 727 ** ^The sqlite3_get_auxdata(C,N) interface returns a pointer to the auxiliary
ad59a04… drh 728 ** data associated by the sqlite3_set_auxdata(C,N,P,X) function with the
ad59a04… drh 729 ** Nth argument value to the application-defined function. ^N is zero
ad59a04… drh 730 ** for the left-most function argument. ^If there is no auxiliary data
ad59a04… drh 731 ** associated with the function argument, the sqlite3_get_auxdata(C,N)
ad59a04… drh 732 ** interface returns a NULL pointer.
b0db6dd… drh 733 ** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as auxiliary data for the
b0db6dd… drh 734 ** N-th argument of the application-defined function. ^Subsequent
b0db6dd… drh 735 ** sqlite3_set_auxdata(C,N,P,X) call if the auxiliary data is still valid or
b0db6dd… drh 736 ** NULL if the auxiliary data has been discarded.
b0db6dd… drh 737 ** once, when the auxiliary data is discarded.
b0db6dd… drh 738 ** SQLite is free to discard the auxiliary data at any time, including: <ul>
2edeeee… drh 739 ** allocation error occurs.)^
2edeeee… drh 740 ** <li> ^(during the original sqlite3_set_auxdata() call if the function
2edeeee… drh 741 ** is evaluated during query planning instead of during query execution,
2edeeee… drh 742 ** as sometimes happens with [SQLITE_ENABLE_STAT4].)^ </ul>
2edeeee… drh 743 ** Note the last two bullets in particular. The destructor X in
2edeeee… drh 744 ** sqlite3_set_auxdata() has been called. Furthermore, a call to
2edeeee… drh 745 ** sqlite3_get_auxdata() that occurs immediately after a corresponding call
2edeeee… drh 746 ** to sqlite3_set_auxdata() might still return NULL if an out-of-memory
2edeeee… drh 747 ** condition occurred during the sqlite3_set_auxdata() call or if the
2edeeee… drh 748 ** function is being evaluated during query planning rather than during
2edeeee… drh 749 ** query execution.
b0db6dd… drh 750 ** ^(In practice, auxiliary data is preserved between function calls for
b0db6dd… drh 751 **
b0db6dd… drh 752 ** See also: [sqlite3_get_clientdata()] and [sqlite3_set_clientdata()].
b0db6dd… drh 753 /*
b0db6dd… drh 754 ** CAPI3REF: Database Connection Client Data
b0db6dd… drh 755 ** METHOD: sqlite3
b0db6dd… drh 756 **
b0db6dd… drh 757 ** These functions are used to associate one or more named pointers
b0db6dd… drh 758 ** with a [database connection].
b0db6dd… drh 759 ** A call to sqlite3_set_clientdata(D,N,P,X) causes the pointer P
b0db6dd… drh 760 ** to be attached to [database connection] D using name N. Subsequent
b0db6dd… drh 761 ** calls to sqlite3_get_clientdata(D,N) will return a copy of pointer P
b0db6dd… drh 762 ** or a NULL pointer if there were no prior calls to
b0db6dd… drh 763 ** sqlite3_set_clientdata() with the same values of D and N.
b0db6dd… drh 764 ** Names are compared using strcmp() and are thus case sensitive.
dc45faa… drh 765 ** It returns 0 on success and SQLITE_NOMEM on allocation failure.
b0db6dd… drh 766 **
b0db6dd… drh 767 ** If P and X are both non-NULL, then the destructor X is invoked with
b0db6dd… drh 768 ** argument P on the first of the following occurrences:
b0db6dd… drh 769 ** <ul>
b0db6dd… drh 770 ** <li> An out-of-memory error occurs during the call to
b0db6dd… drh 771 ** sqlite3_set_clientdata() which attempts to register pointer P.
b0db6dd… drh 772 ** <li> A subsequent call to sqlite3_set_clientdata(D,N,P,X) is made
b0db6dd… drh 773 ** with the same D and N parameters.
b0db6dd… drh 774 ** <li> The database connection closes. SQLite does not make any guarantees
b0db6dd… drh 775 ** about the order in which destructors are called, only that all
b0db6dd… drh 776 ** destructors will be called exactly once at some point during the
e4d2c1d… drh 777 ** database connection closing process.
b0db6dd… drh 778 ** </ul>
b0db6dd… drh 779 **
b0db6dd… drh 780 ** SQLite does not do anything with client data other than invoke
b0db6dd… drh 781 ** destructors on the client data at the appropriate time. The intended
b0db6dd… drh 782 ** use for client data is to provide a mechanism for wrapper libraries
b0db6dd… drh 783 ** to store additional information about an SQLite database connection.
b0db6dd… drh 784 **
b0db6dd… drh 785 ** There is no limit (other than available memory) on the number of different
b0db6dd… drh 786 ** client data pointers (with different names) that can be attached to a
2b2530d… drh 787 ** single database connection. However, the current implementation stores
2b2530d… drh 788 ** the content on a linked list. Insert and retrieval performance will
2b2530d… drh 789 ** be proportional to the number of entries. The design use case, and
2b2530d… drh 790 ** the use case for which the implementation is optimized, is
2b2530d… drh 791 ** that an application will store only small number of client data names,
2b2530d… drh 792 ** typically just one or two. This interface is not intended to be a
2b2530d… drh 793 ** generalized key/value store for thousands or millions of keys. It
2b2530d… drh 794 ** will work for that, but performance might be disappointing.
b0db6dd… drh 795 **
b0db6dd… drh 796 ** There is no way to enumerate the client data pointers
b0db6dd… drh 797 ** associated with a database connection. The N parameter can be thought
b0db6dd… drh 798 ** of as a secret key such that only code that knows the secret key is able
b0db6dd… drh 799 ** to access the associated data.
b0db6dd… drh 800 **
b0db6dd… drh 801 ** Security Warning: These interfaces should not be exposed in scripting
b0db6dd… drh 802 ** languages or in other circumstances where it might be possible for an
cdaec3a… drh 803 ** attacker to invoke them. Any agent that can invoke these interfaces
b0db6dd… drh 804 ** can probably also take control of the process.
b0db6dd… drh 805 **
b0db6dd… drh 806 ** Database connection client data is only available for SQLite
b0db6dd… drh 807 ** version 3.44.0 ([dateof:3.44.0]) and later.
b0db6dd… drh 808 **
b0db6dd… drh 809 ** See also: [sqlite3_set_auxdata()] and [sqlite3_get_auxdata()].
b0db6dd… drh 810 */
b0db6dd… drh 811 SQLITE_API void *sqlite3_get_clientdata(sqlite3*,const char*);
b0db6dd… drh 812 SQLITE_API int sqlite3_set_clientdata(sqlite3*, const char*, void*, void(*)(void*));
13c221a… drh 813 ** ^The sqlite3_result_text64(C,Z,N,D,E) interface sets the return value of an
13c221a… drh 814 ** specified the E parameter, which must be one
13c221a… drh 815 ** of [SQLITE_UTF8], [SQLITE_UTF8_ZT], [SQLITE_UTF16], [SQLITE_UTF16BE],
13c221a… drh 816 ** or [SQLITE_UTF16LE]. ^The special value [SQLITE_UTF8_ZT] means that
13c221a… drh 817 ** the result text is both UTF-8 and zero-terminated. In other words,
17f9878… drh 818 ** SQLITE_UTF8_ZT means that the Z array holds at least N+1 bytes and that
13c221a… drh 819 ** the Z&#91;N&#93; is zero.
cdaec3a… drh 820 ** appear if the string were NUL terminated. If any NUL characters occur
cdaec3a… drh 821 ** If these routines are called from within a different thread
13c221a… drh 822 SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char *z, sqlite3_uint64 n,
2edeeee… drh 823 **
2edeeee… drh 824 ** Every [application-defined SQL function] that invokes this interface
2edeeee… drh 825 ** should include the [SQLITE_RESULT_SUBTYPE] property in its
2edeeee… drh 826 ** text encoding argument when the SQL function is
2edeeee… drh 827 ** [sqlite3_create_function|registered]. If the [SQLITE_RESULT_SUBTYPE]
2edeeee… drh 828 ** property is omitted from the function that invokes sqlite3_result_subtype(),
2edeeee… drh 829 ** then in some cases the sqlite3_result_subtype() might fail to set
2edeeee… drh 830 ** the result subtype.
2edeeee… drh 831 **
2edeeee… drh 832 ** If SQLite is compiled with -DSQLITE_STRICT_SUBTYPE=1, then any
2edeeee… drh 833 ** SQL function that invokes the sqlite3_result_subtype() interface
2edeeee… drh 834 ** and that does not have the SQLITE_RESULT_SUBTYPE property will raise
2edeeee… drh 835 ** an error. Future versions of SQLite might enable -DSQLITE_STRICT_SUBTYPE=1
2edeeee… drh 836 ** by default.
71ed8cb… drh 837 **
71ed8cb… drh 838 ** If a negative argument is passed to sqlite3_sleep() the results vary by
71ed8cb… drh 839 ** VFS and operating system. Some system treat a negative argument as an
71ed8cb… drh 840 ** instruction to sleep forever. Others understand it to mean do not sleep
71ed8cb… drh 841 ** at all. ^In SQLite version 3.42.0 and later, a negative
71ed8cb… drh 842 ** argument passed into sqlite3_sleep() is changed to zero before it is relayed
71ed8cb… drh 843 ** down into the xSleep method of the VFS.
cdaec3a… drh 844 ** for the N-th database on database connection D, or a NULL pointer if N is
e4d2c1d… drh 845 ** CAPI3REF: Allowed return values from sqlite3_txn_state()
cdaec3a… drh 846 ** will be advanced to SQLITE_TXN_WRITE if any changes occur and there are
cdaec3a… drh 847 ** SQLITE_TXN_NONE at the next [ROLLBACK] or [COMMIT].</dd>
e4d2c1d… drh 848 ** then the autovacuum steps callback is canceled. The return value
2a04c64… drh 849 ** ^The update hook is disabled by invoking sqlite3_update_hook()
2a04c64… drh 850 ** with a NULL pointer as the second parameter.
92f2a04… danield 851 **
92f2a04… danield 852 ** Whether the update hook is invoked before or after the
92f2a04… danield 853 ** corresponding change is currently unspecified and may differ
92f2a04… danield 854 ** depending on the type of change. Do not rely on the order of the
92f2a04… danield 855 ** hook call with regards to the final result of the operation which
92f2a04… danield 856 ** triggers the hook.
cdaec3a… drh 857 ** used by all database connections within a single process.
cdaec3a… drh 858 ** change in future releases of SQLite.
5f65ed5… drh 859 ** with various operating-system specific filename extensions added.
5f65ed5… drh 860 ** If that does not work, it tries names of the form "sqlite3_X_init"
5f65ed5… drh 861 ** where X consists of the lower-case equivalent of all ASCII alphabetic
5f65ed5… drh 862 ** characters or all ASCII alphanumeric characters in the filename from
5f65ed5… drh 863 ** the last "/" to the first following "." and omitting any initial "lib".)^
b10fbd8… drh 864 ** entry point were as follows:
b0db6dd… drh 865 /* The methods above are in versions 1 through 3 of the sqlite_module object.
b0db6dd… drh 866 ** Those below are for version 4 and greater. */
e4d2c1d… drh 867 int (*xIntegrity)(sqlite3_vtab *pVTab, const char *zSchema,
e4d2c1d… drh 868 const char *zTabName, int mFlags, char **pzErr);
cdaec3a… drh 869 ** checked separately in byte code. If the omit flag is changed to true, then
e17b8da… stephan 870 ** mask of SQLITE_INDEX_SCAN_* flags. One such flag is
e17b8da… stephan 871 ** [SQLITE_INDEX_SCAN_HEX], which if set causes the [EXPLAIN QUERY PLAN]
cdaec3a… drh 872 ** output to show the idxNum as hex instead of as decimal. Another flag is
e17b8da… stephan 873 ** SQLITE_INDEX_SCAN_UNIQUE, which if set indicates that the query plan will
e17b8da… stephan 874 ** return at most one row.
e17b8da… stephan 875 #define SQLITE_INDEX_SCAN_UNIQUE 0x00000001 /* Scan visits at most 1 row */
e17b8da… stephan 876 #define SQLITE_INDEX_SCAN_HEX 0x00000002 /* Display idxNum as hex */
e17b8da… stephan 877 /* in EXPLAIN QUERY PLAN */
b10fbd8… drh 878 ** when a new virtual table is being created or reinitialized.
b10fbd8… drh 879 ** on *ppBlob after this function returns.
e4d2c1d… drh 880 ** open blob handle results in undefined behavior. ^Calling this routine
b10fbd8… drh 881 ** incremental blob I/O routines can only read or overwrite existing
cdaec3a… drh 882 ** mutex. The argument to sqlite3_mutex_alloc() must be one of these
6da2550… drh 883 ** will always return SQLITE_BUSY. In most cases the SQLite core only uses
6da2550… drh 884 ** sqlite3_mutex_try() as an optimization, so this is acceptable
6da2550… drh 885 ** behavior. The exceptions are unix builds that set the
6da2550… drh 886 ** SQLITE_ENABLE_SETLK_TIMEOUT build option. In that case a working
6da2550… drh 887 ** sqlite3_mutex_try() is required.)^
b2d5aa8… drh 888 ** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(),
b2d5aa8… drh 889 ** sqlite3_mutex_leave(), or sqlite3_mutex_free() is a NULL pointer,
b2d5aa8… drh 890 ** then any of the four routines behaves as a no-op.
cdaec3a… drh 891 ** ^This interface returns a pointer to the [sqlite3_mutex] object that
b0db6dd… drh 892 #define SQLITE_TESTCTRL_FK_NO_ACTION 7
70cae0a… drh 893 #define SQLITE_TESTCTRL_JSON_SELFCHECK 14
e17b8da… stephan 894 #define SQLITE_TESTCTRL_GETOPT 16
72070b3… drh 895 #define SQLITE_TESTCTRL_USELONGDOUBLE 34 /* NOT USED */
a10f931… drh 896 #define SQLITE_TESTCTRL_ATOF 34
65c6bda… drh 897 #define SQLITE_TESTCTRL_LAST 34 /* Largest TESTCTRL */
cdaec3a… drh 898 ** recognized by SQLite. Applications can use these routines to determine
92f2a04… danield 899 ** The sqlite3_keyword_name(N,Z,L) interface finds the 0-based N-th keyword and
d326547… drh 900 ** [sqlite3_str_finish(X)] interface might also return a NULL pointer if the
4f76459… drh 901 **
4f76459… drh 902 ** ^The [sqlite3_str_free(X)] interface destroys both the sqlite3_str object
4f76459… drh 903 ** X and the string content it contains. Calling sqlite3_str_free(X) is
4f76459… drh 904 ** the equivalent of calling [sqlite3_free](sqlite3_str_finish(X)).
4f76459… drh 905 SQLITE_API void sqlite3_str_free(sqlite3_str*);
4f76459… drh 906 ** These interfaces add or remove content to an sqlite3_str object
4f76459… drh 907 ** previously obtained from [sqlite3_str_new()].
4f76459… drh 908 ** ^The [sqlite3_str_truncate(X,N)] method changes the length of the string
17f9878… drh 909 ** under construction to be N bytes or less. This routine is a no-op if
4f76459… drh 910 ** N is negative or if the string is already N bytes or smaller in size.
4f76459… drh 911 **
4f76459… drh 912 SQLITE_API void sqlite3_str_truncate(sqlite3_str*,int N);
cdaec3a… drh 913 ** [sqlite3_str] object. Applications must not use the pointer returned by
cdaec3a… drh 914 ** were too large (they were larger than the "sz" parameter to
3c639f7… drh 915 ** ^The sqlite3_db_status64(D,O,C,H,R) routine works exactly the same
3c639f7… drh 916 ** way as sqlite3_db_status(D,O,C,H,R) routine except that the C and H
3c639f7… drh 917 ** parameters are pointer to 64-bit integers (type: sqlite3_int64) instead
3c639f7… drh 918 ** of pointers to 32-bit integers, which allows larger status values
3c639f7… drh 919 ** to be returned. If a status value exceeds 2,147,483,647 then
3c639f7… drh 920 ** sqlite3_db_status() will truncate the value whereas sqlite3_db_status64()
3c639f7… drh 921 ** will return the full value.
3c639f7… drh 922 **
3c639f7… drh 923 SQLITE_API int sqlite3_db_status64(sqlite3*,int,sqlite3_int64*,sqlite3_int64*,int);
cdaec3a… drh 924 ** the current value is always zero.</dd>)^
cdaec3a… drh 925 ** <dd>This parameter returns the number of malloc attempts that might have
cdaec3a… drh 926 ** the current value is always zero.</dd>)^
cdaec3a… drh 927 ** <dd>This parameter returns the number of malloc attempts that might have
cdaec3a… drh 928 ** the current value is always zero.</dd>)^
cdaec3a… drh 929 ** </dd>
cdaec3a… drh 930 ** value as DBSTATUS_CACHE_USED. Or, if one or more of the pager caches are
cdaec3a… drh 931 ** SQLITE_DBSTATUS_CACHE_USED_SHARED is always 0.</dd>
cdaec3a… drh 932 ** </dd>
3c639f7… drh 933 ** <p>
3c639f7… drh 934 ** ^(There is overlap between the quantities measured by this parameter
3c639f7… drh 935 ** (SQLITE_DBSTATUS_CACHE_WRITE) and SQLITE_DBSTATUS_TEMPBUF_SPILL.
3c639f7… drh 936 ** Resetting one will reduce the other.)^
cdaec3a… drh 937 ** additional overhead. This parameter can be used to help identify
3c639f7… drh 938 **
3c639f7… drh 939 ** [[SQLITE_DBSTATUS_TEMPBUF_SPILL] ^(<dt>SQLITE_DBSTATUS_TEMPBUF_SPILL</dt>
3c639f7… drh 940 ** <dd>^(This parameter returns the number of bytes written to temporary
3c639f7… drh 941 ** files on disk that could have been kept in memory had sufficient memory
3c639f7… drh 942 ** been available. This value includes writes to intermediate tables that
3c639f7… drh 943 ** are part of complex queries, external sorts that spill to disk, and
3c639f7… drh 944 ** writes to TEMP tables.)^
3c639f7… drh 945 ** ^The highwater mark is always 0.
3c639f7… drh 946 ** <p>
3c639f7… drh 947 ** ^(There is overlap between the quantities measured by this parameter
3c639f7… drh 948 ** (SQLITE_DBSTATUS_TEMPBUF_SPILL) and SQLITE_DBSTATUS_CACHE_WRITE.
3c639f7… drh 949 ** Resetting one will reduce the other.)^
3c639f7… drh 950 #define SQLITE_DBSTATUS_TEMPBUF_SPILL 13
3c639f7… drh 951 #define SQLITE_DBSTATUS_MAX 13 /* Largest defined DBSTATUS */
bcbf150… drh 952 ** improve performance through careful use of indices.</dd>
bcbf150… drh 953 ** improve performance by adding permanent indices that do not
bcbf150… drh 954 ** then the value returned by this statement status code is undefined.</dd>
bcbf150… drh 955 ** [bound parameters] that might affect the query plan.</dd>
bcbf150… drh 956 ** cycle.</dd>
bcbf150… drh 957 ** had to be processed as normal.</dd>
bcbf150… drh 958 ** be allocated by the cache. ^szPage will always be a power of two. ^The
bcbf150… drh 959 ** associated with each page cache entry. ^The szExtra parameter will be
bcbf150… drh 960 ** does not have to do anything special based upon the value of bPurgeable;
bcbf150… drh 961 ** ^Hence, a cache created with bPurgeable set to false will
bcbf150… drh 962 ** suggested maximum cache-size (number of pages stored) for the cache
bcbf150… drh 963 ** parameter to help it determine what action to take:
bcbf150… drh 964 ** <tr><td> 1 <td> Allocate a new page if it is easy and convenient to do so.
bcbf150… drh 965 ** zero, then the page may be discarded or retained at the discretion of the
bcbf150… drh 966 ** of these pages are pinned, they become implicitly unpinned, meaning that
b10fbd8… drh 967 ** database is modified by using the same database connection as is used
b10fbd8… drh 968 ** sqlite3_backup_step() errors occurred, regardless of whether or not
d0730da… drh 969 **
d0730da… drh 970 ** <b>Alternatives To Using The Backup API</b>
d0730da… drh 971 **
d0730da… drh 972 ** Other techniques for safely creating a consistent backup of an SQLite
d0730da… drh 973 ** database include:
d0730da… drh 974 **
d0730da… drh 975 ** <ul>
d0730da… drh 976 ** <li> The [VACUUM INTO] command.
d0730da… drh 977 ** <li> The [sqlite3_rsync] utility program.
d0730da… drh 978 ** </ul>
bcbf150… drh 979 ** when the blocking connection's current transaction is concluded. ^The
bcbf150… drh 980 ** unlock-notify callback is canceled. ^The blocked connection's
e4d2c1d… drh 981 ** unlock-notify callback may also be canceled by closing the blocked
dc45faa… drh 982 ** ^The callback function should normally return [SQLITE_OK]. ^If an error
dc45faa… drh 983 ** ^A single database handle may have at most a single write-ahead log
dc45faa… drh 984 ** callback registered at one time. ^Calling [sqlite3_wal_hook()]
dc45faa… drh 985 ** replaces the default behavior or previously registered write-ahead
dc45faa… drh 986 ** log callback.
dc45faa… drh 987 **
dc45faa… drh 988 ** ^The return value is a copy of the third parameter from the
dc45faa… drh 989 ** previous call, if any, or 0.
dc45faa… drh 990 **
dc45faa… drh 991 ** ^The [sqlite3_wal_autocheckpoint()] interface and the
dc45faa… drh 992 ** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and
dc45faa… drh 993 ** will overwrite any prior [sqlite3_wal_hook()] settings.
dc45faa… drh 994 **
dc45faa… drh 995 ** ^If a write-ahead log callback is set using this function then
dc45faa… drh 996 ** [sqlite3_wal_checkpoint_v2()] or [PRAGMA wal_checkpoint]
dc45faa… drh 997 ** should be invoked periodically to keep the write-ahead log file
dc45faa… drh 998 ** from growing without bound.
dc45faa… drh 999 **
dc45faa… drh 1000 ** ^Passing a NULL pointer for the callback disables automatic
dc45faa… drh 1001 ** checkpointing entirely. To re-enable the default behavior, call
dc45faa… drh 1002 ** sqlite3_wal_autocheckpoint(db,1000) or use [PRAGMA wal_checkpoint].
dc45faa… drh 1003 ** a negative value as the N parameter disables automatic
dc45faa… drh 1004 ** pages.
dc45faa… drh 1005 **
dc45faa… drh 1006 ** ^The use of this interface is only necessary if the default setting
dc45faa… drh 1007 ** is found to be suboptimal for a particular application.
dc45faa… drh 1008 **
dc45faa… drh 1009 ** <dt>SQLITE_CHECKPOINT_NOOP<dd>
dc45faa… drh 1010 ** ^This mode always checkpoints zero frames. The only reason to invoke
dc45faa… drh 1011 ** a NOOP checkpoint is to access the values returned by
dc45faa… drh 1012 ** sqlite3_wal_checkpoint_v2() via output parameters *pnLog and *pnCkpt.
dc45faa… drh 1013 #define SQLITE_CHECKPOINT_NOOP -1 /* Do no work at all */
bcbf150… drh 1014 ** specified as part of the user's SQL statement, regardless of the actual
f8a29b2… drh 1015 ** the [xConnect] or [xCreate] methods of a [virtual table] implementation
bcbf150… drh 1016 ** [xConnect] or [xCreate] methods of a [virtual table] implementation
2eb2077… drh 1017 **
2eb2077… drh 1018 ** [[SQLITE_VTAB_USES_ALL_SCHEMAS]]<dt>SQLITE_VTAB_USES_ALL_SCHEMAS</dt>
2eb2077… drh 1019 ** <dd>Calls of the form
2eb2077… drh 1020 ** [sqlite3_vtab_config](db,SQLITE_VTAB_USES_ALL_SCHEMA) from within the
2eb2077… drh 1021 ** the [xConnect] or [xCreate] methods of a [virtual table] implementation
2eb2077… drh 1022 ** instruct the query planner to begin at least a read transaction on
2eb2077… drh 1023 ** all schemas ("main", "temp", and any ATTACH-ed databases) whenever the
2eb2077… drh 1024 ** virtual table is used.
2eb2077… drh 1025 ** </dd>
2eb2077… drh 1026 #define SQLITE_VTAB_USES_ALL_SCHEMAS 4
2ba99c2… drh 1027 ** order, as long as rows with the same values in all columns identified
2ba99c2… drh 1028 ** by "aOrderBy" are adjacent.)^ ^(Furthermore, when two or more rows
2ba99c2… drh 1029 ** contain the same values for all columns identified by "colUsed", all but
2ba99c2… drh 1030 ** one such row may optionally be omitted from the result.)^
2ba99c2… drh 1031 ** The virtual table is not required to omit rows that are duplicates
2ba99c2… drh 1032 ** over the "colUsed" columns, but if the virtual table can do that without
2ba99c2… drh 1033 ** too much extra effort, it could potentially help the query to run faster.
2ba99c2… drh 1034 ** ^(If the sqlite3_vtab_distinct() interface returns 3, that means the
2ba99c2… drh 1035 ** virtual table must return rows in the order defined by "aOrderBy" as
2ba99c2… drh 1036 ** if the sqlite3_vtab_distinct() interface had returned 0. However if
2ba99c2… drh 1037 ** two or more rows in the result have the same values for all columns
2ba99c2… drh 1038 ** identified by "colUsed", then all but one such row may optionally be
2ba99c2… drh 1039 ** omitted.)^ Like when the return value is 2, the virtual table
2ba99c2… drh 1040 ** is not required to omit rows that are duplicates over the "colUsed"
2ba99c2… drh 1041 ** columns, but if the virtual table can do that without
2ba99c2… drh 1042 ** too much extra effort, it could potentially help the query to run faster.
2ba99c2… drh 1043 ** This mode is used for queries
2ba99c2… drh 1044 ** <p>The following table summarizes the conditions under which the
2ba99c2… drh 1045 ** virtual table is allowed to set the "orderByConsumed" flag based on
2ba99c2… drh 1046 ** the value returned by sqlite3_vtab_distinct(). This table is a
2ba99c2… drh 1047 ** restatement of the previous four paragraphs:
2ba99c2… drh 1048 **
2ba99c2… drh 1049 ** <table border=1 cellspacing=0 cellpadding=10 width="90%">
2ba99c2… drh 1050 ** <tr>
2ba99c2… drh 1051 ** <td valign="top">sqlite3_vtab_distinct() return value
2ba99c2… drh 1052 ** <td valign="top">Rows are returned in aOrderBy order
ad59a04… drh 1053 ** <td valign="top">Rows with the same value in all aOrderBy columns are
ad59a04… drh 1054 ** adjacent
2ba99c2… drh 1055 ** <td valign="top">Duplicates over all colUsed columns may be omitted
2ba99c2… drh 1056 ** <tr><td>0<td>yes<td>yes<td>no
2ba99c2… drh 1057 ** <tr><td>1<td>no<td>yes<td>no
2ba99c2… drh 1058 ** <tr><td>2<td>no<td>yes<td>yes
2ba99c2… drh 1059 ** <tr><td>3<td>yes<td>yes<td>yes
2ba99c2… drh 1060 ** </table>
2ba99c2… drh 1061 **
ad59a04… drh 1062 ** values are the same value for sorting purposes, two NULL values are
ad59a04… drh 1063 ** considered to be the same. In other words, the comparison operator is "IS"
bcbf150… drh 1064 ** "orderByConsumed" flag is unset, the query planner will add extra
f8a29b2… drh 1065 ** aConstraintUsage[].argvIndex to a positive integer. ^(Then, under
bcbf150… drh 1066 ** processing using the [sqlite3_vtab_in()] interface in the
4f76459… drh 1067 ** &nbsp; if( rc!=SQLITE_DONE ){
bcbf150… drh 1068 ** can return a result code other than SQLITE_OK or SQLITE_NOTFOUND if
bcbf150… drh 1069 ** inform a [virtual table] implementation of the [ON CONFLICT] mode
bcbf150… drh 1070 ** for the SQL statement being evaluated.
bcbf150… drh 1071 ** iteration of the X-th loop. If the query planner's estimate was accurate,
bcbf150… drh 1072 ** be the NLOOP value for the current loop.</dd>
bcbf150… drh 1073 ** used for the X-th loop.</dd>
bcbf150… drh 1074 ** description for the X-th loop.</dd>
bcbf150… drh 1075 ** column of an [EXPLAIN QUERY PLAN] query.</dd>
bcbf150… drh 1076 ** id of the parent of the current query element, if applicable, or
bcbf150… drh 1077 ** returned in the second column of an [EXPLAIN QUERY PLAN] query.</dd>
bcbf150… drh 1078 ** set to -1.</dd>
4f76459… drh 1079 ** one flag is defined - [SQLITE_SCANSTAT_COMPLEX]. If SQLITE_SCANSTAT_COMPLEX
4f76459… drh 1080 ** of a query plan that are reported by "[EXPLAIN QUERY PLAN]" output. If
bcbf150… drh 1081 ** for. Query elements are numbered starting from zero. A value of -1 may
bcbf150… drh 1082 ** retrieve statistics for the entire query. ^If idx is out of range
4f76459… drh 1083 ** See also: [sqlite3_stmt_scanstatus_reset()] and the
17f9878… drh 1084 ** [nexec and ncycle] columns of the [bytecode virtual table].
b10fbd8… drh 1085 ** [sqlite3_db_cacheflush(D)] interface is invoked, any dirty
bcbf150… drh 1086 ** the pre-update hook is invoked with SQLITE_DELETE, because
bcbf150… drh 1087 ** the new values are not yet available. In this case, when a
f8a29b2… drh 1088 ** callback made with op==SQLITE_DELETE is actually a write using the
72070b3… drh 1089 ** If a read-transaction is opened by this function, then it is guaranteed
72070b3… drh 1090 ** that the returned snapshot object may not be invalidated by a database
72070b3… drh 1091 ** writer or checkpointer until after the read-transaction is closed. This
72070b3… drh 1092 ** is not guaranteed if a read-transaction is already open when this
72070b3… drh 1093 ** function is called. In that case, any subsequent write or checkpoint
72070b3… drh 1094 ** operation on the database may invalidate the returned snapshot handle,
72070b3… drh 1095 ** even while the read-transaction remains open.
72070b3… drh 1096 **
dc45faa… drh 1097 SQLITE_API int sqlite3_snapshot_get(
dc45faa… drh 1098 SQLITE_API int sqlite3_snapshot_open(
dc45faa… drh 1099 SQLITE_API void sqlite3_snapshot_free(sqlite3_snapshot*);
dc45faa… drh 1100 SQLITE_API int sqlite3_snapshot_cmp(
dc45faa… drh 1101 SQLITE_API int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb);
3ce667a… drh 1102 ** The sqlite3_serialize(D,S,P,F) interface returns a pointer to
3ce667a… drh 1103 ** memory that is a serialization of the S database on
3ce667a… drh 1104 ** [database connection] D. If S is a NULL pointer, the main database is used.
bcbf150… drh 1105 ** to disk if that database were backed up to disk.
bcbf150… drh 1106 ** is currently using for that database, or NULL if no such contiguous
b0db6dd… drh 1107 **
b0db6dd… drh 1108 ** After the call, if the SQLITE_SERIALIZE_NOCOPY bit had been set,
b0db6dd… drh 1109 ** the returned buffer content will remain accessible and unchanged
b0db6dd… drh 1110 ** until either the next write operation on the connection or when
b0db6dd… drh 1111 ** the connection is closed, and applications must not modify the
b0db6dd… drh 1112 ** buffer. If the bit had been clear, the returned buffer will not
b0db6dd… drh 1113 ** be accessed by SQLite after the call.
dc45faa… drh 1114 ** reopen S as an in-memory database based on the serialization
dc45faa… drh 1115 ** contained in P. If S is a NULL pointer, the main database is
dc45faa… drh 1116 ** used. The serialized database P is N bytes in size. M is the size
dc45faa… drh 1117 ** of the buffer P, which might be larger than N. If M is larger than
dc45faa… drh 1118 ** N, and the SQLITE_DESERIALIZE_READONLY bit is not set in F, then
dc45faa… drh 1119 ** SQLite is permitted to add content to the in-memory database as
dc45faa… drh 1120 ** long as the total size does not exceed M bytes.
b0db6dd… drh 1121 ** Applications must not modify the buffer P or invalidate it before
b0db6dd… drh 1122 ** the database connection D is closed.
b0db6dd… drh 1123 **
bcbf150… drh 1124 ** It is not possible to deserialize into the TEMP database. If the
b0db6dd… drh 1125 **
b0db6dd… drh 1126 ** The deserialized database should not be in [WAL mode]. If the database
b0db6dd… drh 1127 ** is in WAL mode, then any attempt to use the database file will result
b0db6dd… drh 1128 ** in an [SQLITE_CANTOPEN] error. The application can set the
b0db6dd… drh 1129 ** [file format version numbers] (bytes 18 and 19) of the input database P
b0db6dd… drh 1130 ** to 0x01 prior to invoking sqlite3_deserialize(D,S,P,N,M,F) to force the
b0db6dd… drh 1131 ** database file into rollback mode and work around this limitation.
bcbf150… drh 1132 sqlite3_int64 szDb, /* Number of bytes in the deserialization */
bcbf150… drh 1133 ** The following are allowed values for the 6th argument (the F argument) to
70539ee… drh 1134
70539ee… drh 1135 /*
70539ee… drh 1136 ** CAPI3REF: Bind array values to the CARRAY table-valued function
70539ee… drh 1137 **
7b0960d… drh 1138 ** The sqlite3_carray_bind_v2(S,I,P,N,F,X,D) interface binds an array value to
7b0960d… drh 1139 ** parameter that is the first argument of the [carray() table-valued function].
ad59a04… drh 1140 ** The S parameter is a pointer to the [prepared statement] that uses the
ad59a04… drh 1141 ** carray() functions. I is the parameter index to be bound. I must be the
ad59a04… drh 1142 ** index of the parameter that is the first argument to the carray()
ad59a04… drh 1143 ** table-valued function. P is a pointer to the array to be bound, and N
ad59a04… drh 1144 ** is the number of elements in the array. The F argument is one of
ad59a04… drh 1145 ** constants [SQLITE_CARRAY_INT32], [SQLITE_CARRAY_INT64],
ad59a04… drh 1146 ** [SQLITE_CARRAY_DOUBLE], [SQLITE_CARRAY_TEXT],
7b0960d… drh 1147 ** or [SQLITE_CARRAY_BLOB] to indicate the datatype of the array P.
7b0960d… drh 1148 **
7b0960d… drh 1149 ** If the X argument is not a NULL pointer or one of the special
7b0960d… drh 1150 ** values [SQLITE_STATIC] or [SQLITE_TRANSIENT], then SQLite will invoke
7b0960d… drh 1151 ** the function X with argument D when it is finished using the data in P.
7b0960d… drh 1152 ** The call to X(D) is a destructor for the array P. The destructor X(D)
17f9878… drh 1153 ** is invoked even if the call to sqlite3_carray_bind_v2() fails. If the X
7b0960d… drh 1154 ** parameter is the special-case value [SQLITE_STATIC], then SQLite assumes
7b0960d… drh 1155 ** that the data static and the destructor is never invoked. If the X
7b0960d… drh 1156 ** parameter is the special-case value [SQLITE_TRANSIENT], then
7b0960d… drh 1157 ** sqlite3_carray_bind_v2() makes its own private copy of the data prior
7b0960d… drh 1158 ** to returning and never invokes the destructor X.
7b0960d… drh 1159 **
17f9878… drh 1160 ** The sqlite3_carray_bind() function works the same as sqlite3_carray_bind_v2()
7b0960d… drh 1161 ** with a D parameter set to P. In other words,
7b0960d… drh 1162 ** sqlite3_carray_bind(S,I,P,N,F,X) is same as
17f9878… drh 1163 ** sqlite3_carray_bind_v2(S,I,P,N,F,X,P).
70539ee… drh 1164 */
7b0960d… drh 1165 SQLITE_API int sqlite3_carray_bind_v2(
7b0960d… drh 1166 sqlite3_stmt *pStmt, /* Statement to be bound */
7b0960d… drh 1167 int i, /* Parameter index */
7b0960d… drh 1168 void *aData, /* Pointer to array data */
7b0960d… drh 1169 int nData, /* Number of data elements */
7b0960d… drh 1170 int mFlags, /* CARRAY flags */
7b0960d… drh 1171 void (*xDel)(void*), /* Destructor for aData */
7b0960d… drh 1172 void *pDel /* Optional argument to xDel() */
7b0960d… drh 1173 );
92871e0… drh 1174 SQLITE_API int sqlite3_carray_bind(
70539ee… drh 1175 sqlite3_stmt *pStmt, /* Statement to be bound */
70539ee… drh 1176 int i, /* Parameter index */
70539ee… drh 1177 void *aData, /* Pointer to array data */
70539ee… drh 1178 int nData, /* Number of data elements */
70539ee… drh 1179 int mFlags, /* CARRAY flags */
70539ee… drh 1180 void (*xDel)(void*) /* Destructor for aData */
70539ee… drh 1181 );
70539ee… drh 1182
70539ee… drh 1183 /*
92871e0… drh 1184 ** CAPI3REF: Datatypes for the CARRAY table-valued function
70539ee… drh 1185 **
70539ee… drh 1186 ** The fifth argument to the [sqlite3_carray_bind()] interface musts be
70539ee… drh 1187 ** one of the following constants, to specify the datatype of the array
70539ee… drh 1188 ** that is being bound into the [carray table-valued function].
70539ee… drh 1189 */
70539ee… drh 1190 #define SQLITE_CARRAY_INT32 0 /* Data is 32-bit signed integers */
70539ee… drh 1191 #define SQLITE_CARRAY_INT64 1 /* Data is 64-bit signed integers */
70539ee… drh 1192 #define SQLITE_CARRAY_DOUBLE 2 /* Data is doubles */
70539ee… drh 1193 #define SQLITE_CARRAY_TEXT 3 /* Data is char* */
70539ee… drh 1194 #define SQLITE_CARRAY_BLOB 4 /* Data is struct iovec */
70539ee… drh 1195
70539ee… drh 1196 /*
70539ee… drh 1197 ** Versions of the above #defines that omit the initial SQLITE_, for
70539ee… drh 1198 ** legacy compatibility.
70539ee… drh 1199 */
70539ee… drh 1200 #define CARRAY_INT32 0 /* Data is 32-bit signed integers */
70539ee… drh 1201 #define CARRAY_INT64 1 /* Data is 64-bit signed integers */
70539ee… drh 1202 #define CARRAY_DOUBLE 2 /* Data is doubles */
70539ee… drh 1203 #define CARRAY_TEXT 3 /* Data is char* */
70539ee… drh 1204 #define CARRAY_BLOB 4 /* Data is struct iovec */
b58b305… drh 1205
b58b305… drh 1206 /*
66899f8… drh 1207 /* #endif for SQLITE3_H will be added by mksqlite3.tcl */
a6cc3da… drh 1208 ** CAPI3REF: Configure a Session Object
a6cc3da… drh 1209 ** created. At present the only valid values for the second parameter are
a6cc3da… drh 1210 ** [SQLITE_SESSION_OBJCONFIG_SIZE] and [SQLITE_SESSION_OBJCONFIG_ROWID].
a6cc3da… drh 1211 */
a6cc3da… drh 1212 SQLITE_API int sqlite3session_object_config(sqlite3_session*, int op, void *pArg);
a6cc3da… drh 1213
a6cc3da… drh 1214 /*
a6cc3da… drh 1215 ** CAPI3REF: Options for sqlite3session_object_config
a6cc3da… drh 1216 ** The following values may passed as the the 2nd parameter to
a6cc3da… drh 1217 **
a6cc3da… drh 1218 ** <dt>SQLITE_SESSION_OBJCONFIG_ROWID <dd>
a6cc3da… drh 1219 ** This option is used to set, clear or query the flag that enables
a6cc3da… drh 1220 ** collection of data for tables with no explicit PRIMARY KEY.
a6cc3da… drh 1221 **
a6cc3da… drh 1222 ** Normally, tables with no explicit PRIMARY KEY are simply ignored
a6cc3da… drh 1223 ** by the sessions module. However, if this flag is set, it behaves
a6cc3da… drh 1224 ** as if such tables have a column "_rowid_ INTEGER PRIMARY KEY" inserted
a6cc3da… drh 1225 ** as their leftmost columns.
a6cc3da… drh 1226 **
a6cc3da… drh 1227 ** It is an error (SQLITE_MISUSE) to attempt to modify this setting after
a6cc3da… drh 1228 ** the first table has been attached to the session object.
a6cc3da… drh 1229 #define SQLITE_SESSION_OBJCONFIG_SIZE 1
a6cc3da… drh 1230 #define SQLITE_SESSION_OBJCONFIG_ROWID 2
22b3844… drh 1231 ** Or, if one field of a row is updated while a session is enabled, and
22b3844… drh 1232 ** then another field of the same row is updated while the session is disabled,
22b3844… drh 1233 ** the resulting changeset will contain an UPDATE change that updates both
22b3844… drh 1234 ** fields.
d14a780… drh 1235 ** Unless the call to this function is a no-op as described above, it is an
d14a780… drh 1236 ** error if database zFrom does not exist or does not contain the required
d14a780… drh 1237 ** compatible table.
f40c00b… drh 1238 ** <dt>SQLITE_CHANGESETSTART_INVERT <dd>
b0db6dd… drh 1239
b0db6dd… drh 1240 /*
b0db6dd… drh 1241 ** CAPI3REF: Add a Schema to a Changegroup
b0db6dd… drh 1242 ** METHOD: sqlite3_changegroup_schema
b0db6dd… drh 1243 **
b0db6dd… drh 1244 ** This method may be used to optionally enforce the rule that the changesets
b0db6dd… drh 1245 ** added to the changegroup handle must match the schema of database zDb
b0db6dd… drh 1246 ** ("main", "temp", or the name of an attached database). If
b0db6dd… drh 1247 ** sqlite3changegroup_add() is called to add a changeset that is not compatible
b0db6dd… drh 1248 ** with the configured schema, SQLITE_SCHEMA is returned and the changegroup
b0db6dd… drh 1249 ** object is left in an undefined state.
b0db6dd… drh 1250 **
b0db6dd… drh 1251 ** A changeset schema is considered compatible with the database schema in
b0db6dd… drh 1252 ** the same way as for sqlite3changeset_apply(). Specifically, for each
b0db6dd… drh 1253 ** table in the changeset, there exists a database table with:
b0db6dd… drh 1254 **
b0db6dd… drh 1255 ** <ul>
b0db6dd… drh 1256 ** <li> The name identified by the changeset, and
b0db6dd… drh 1257 ** <li> at least as many columns as recorded in the changeset, and
b0db6dd… drh 1258 ** <li> the primary key columns in the same position as recorded in
b0db6dd… drh 1259 ** the changeset.
b0db6dd… drh 1260 ** </ul>
b0db6dd… drh 1261 **
b0db6dd… drh 1262 ** The output of the changegroup object always has the same schema as the
b0db6dd… drh 1263 ** database nominated using this function. In cases where changesets passed
b0db6dd… drh 1264 ** to sqlite3changegroup_add() have fewer columns than the corresponding table
b0db6dd… drh 1265 ** in the database schema, these are filled in using the default column
b0db6dd… drh 1266 ** values from the database schema. This makes it possible to combined
b0db6dd… drh 1267 ** changesets that have different numbers of columns for a single table
b0db6dd… drh 1268 ** within a changegroup, provided that they are otherwise compatible.
b0db6dd… drh 1269 */
b0db6dd… drh 1270 SQLITE_API int sqlite3changegroup_schema(sqlite3_changegroup*, sqlite3*, const char *zDb);
b0db6dd… drh 1271 ** case, this function fails with SQLITE_SCHEMA. Except, if the changegroup
b0db6dd… drh 1272 ** object has been configured with a database schema using the
b0db6dd… drh 1273 ** sqlite3changegroup_schema() API, then it is possible to combine changesets
b0db6dd… drh 1274 ** with different numbers of columns for a single table, provided that
b0db6dd… drh 1275 ** they are otherwise compatible.
b0db6dd… drh 1276 ** If the input changeset appears to be corrupt and the corruption is
b0db6dd… drh 1277 ** detected, SQLITE_CORRUPT is returned. Or, if an out-of-memory condition
b0db6dd… drh 1278 ** occurs during processing, this function returns SQLITE_NOMEM.
b0db6dd… drh 1279 **
b0db6dd… drh 1280 ** In all cases, if an error occurs the state of the final contents of the
b0db6dd… drh 1281 ** changegroup is undefined. If no error occurs, SQLITE_OK is returned.
b0db6dd… drh 1282
b0db6dd… drh 1283 /*
c09fea3… drh 1284 ** CAPI3REF: Add A Single Change To A Changegroup
c09fea3… drh 1285 ** METHOD: sqlite3_changegroup
c09fea3… drh 1286 **
c09fea3… drh 1287 ** This function adds the single change currently indicated by the iterator
c09fea3… drh 1288 ** passed as the second argument to the changegroup object. The rules for
c09fea3… drh 1289 ** adding the change are just as described for [sqlite3changegroup_add()].
c09fea3… drh 1290 **
c09fea3… drh 1291 ** If the change is successfully added to the changegroup, SQLITE_OK is
c09fea3… drh 1292 ** returned. Otherwise, an SQLite error code is returned.
c09fea3… drh 1293 **
c09fea3… drh 1294 ** The iterator must point to a valid entry when this function is called.
c09fea3… drh 1295 ** If it does not, SQLITE_ERROR is returned and no change is added to the
c09fea3… drh 1296 ** changegroup. Additionally, the iterator must not have been opened with
c09fea3… drh 1297 ** the SQLITE_CHANGESETAPPLY_INVERT flag. In this case SQLITE_ERROR is also
c09fea3… drh 1298 ** returned.
c09fea3… drh 1299 */
c09fea3… drh 1300 SQLITE_API int sqlite3changegroup_add_change(
c09fea3… drh 1301 sqlite3_changegroup*,
c09fea3… drh 1302 sqlite3_changeset_iter*
c09fea3… drh 1303 );
c09fea3… drh 1304
c09fea3… drh 1305
c09fea3… drh 1306
c09fea3… drh 1307 /*
3041904… drh 1308 ** All changes made by these functions are enclosed in a savepoint transaction.
3041904… drh 1309 ** If any other error (aside from a constraint failure when attempting to
3041904… drh 1310 ** write to the target database) occurs, then the savepoint transaction is
3041904… drh 1311 ** rolled back, restoring the target database to its original state, and an
3041904… drh 1312 ** SQLite error code returned. Additionally, starting with version 3.51.0,
3041904… drh 1313 ** an error code and error message that may be accessed using the
3041904… drh 1314 ** [sqlite3_errcode()] and [sqlite3_errmsg()] APIs are left in the database
3041904… drh 1315 ** handle.
3041904… drh 1316 **
0185597… drh 1317 ** callback". This may be passed NULL, in which case all changes in the
0185597… drh 1318 ** changeset are applied to the database. For sqlite3changeset_apply() and
0185597… drh 1319 ** sqlite3_changeset_apply_v2(), if it is not NULL, then it is invoked once
0185597… drh 1320 ** for each table affected by at least one change in the changeset. In this
0185597… drh 1321 ** case the table name is passed as the second argument, and a copy of
0185597… drh 1322 ** the context pointer passed as the sixth argument to apply() or apply_v2()
0185597… drh 1323 ** as the first. If the "filter callback" returns zero, then no attempt is
0185597… drh 1324 ** made to apply any changes to the table. Otherwise, if the return value is
0185597… drh 1325 ** non-zero, all changes related to the table are attempted.
0185597… drh 1326 **
0185597… drh 1327 ** For sqlite3_changeset_apply_v3(), the xFilter callback is invoked once
0185597… drh 1328 ** per change. The second argument in this case is an sqlite3_changeset_iter
0185597… drh 1329 ** that may be queried using the usual APIs for the details of the current
0185597… drh 1330 ** change. If the "filter callback" returns zero in this case, then no attempt
0185597… drh 1331 ** is made to apply the current change. If it returns non-zero, the change
0185597… drh 1332 ** is applied.
0185597… drh 1333 ** to modify the table contents according to each UPDATE, INSERT or DELETE
0185597… drh 1334 ** change that is not excluded by a filter callback. If a change cannot be
0185597… drh 1335 ** applied cleanly, the conflict handler function passed as the fifth argument
0185597… drh 1336 ** to sqlite3changeset_apply() may be invoked. A description of exactly when
0185597… drh 1337 ** the conflict handler is invoked for each type of change is below.
0185597… drh 1338 ),
0185597… drh 1339 int(*xConflict)(
0185597… drh 1340 void *pCtx, /* Copy of sixth arg to _apply() */
0185597… drh 1341 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
0185597… drh 1342 sqlite3_changeset_iter *p /* Handle describing change and conflict */
0185597… drh 1343 ),
0185597… drh 1344 void *pCtx, /* First argument passed to xConflict */
0185597… drh 1345 void **ppRebase, int *pnRebase, /* OUT: Rebase data */
0185597… drh 1346 int flags /* SESSION_CHANGESETAPPLY_* flags */
0185597… drh 1347 );
0185597… drh 1348 SQLITE_API int sqlite3changeset_apply_v3(
0185597… drh 1349 sqlite3 *db, /* Apply change to "main" db of this handle */
0185597… drh 1350 int nChangeset, /* Size of changeset in bytes */
0185597… drh 1351 void *pChangeset, /* Changeset blob */
0185597… drh 1352 int(*xFilter)(
0185597… drh 1353 void *pCtx, /* Copy of sixth arg to _apply() */
0185597… drh 1354 sqlite3_changeset_iter *p /* Handle describing change */
b0db6dd… drh 1355 ),
b0db6dd… drh 1356 int(*xConflict)(
b0db6dd… drh 1357 void *pCtx, /* Copy of sixth arg to _apply() */
b0db6dd… drh 1358 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
b0db6dd… drh 1359 sqlite3_changeset_iter *p /* Handle describing change and conflict */
b0db6dd… drh 1360 ),
b0db6dd… drh 1361 void *pCtx, /* First argument passed to xConflict */
b0db6dd… drh 1362 void **ppRebase, int *pnRebase, /* OUT: Rebase data */
b0db6dd… drh 1363 int flags /* SESSION_CHANGESETAPPLY_* flags */
b0db6dd… drh 1364 );
2516fca… drh 1365 **
2516fca… drh 1366 ** <dt>SQLITE_CHANGESETAPPLY_IGNORENOOP <dd>
2516fca… drh 1367 ** Do not invoke the conflict handler callback for any changes that
2516fca… drh 1368 ** would not actually modify the database even if they were applied.
2516fca… drh 1369 ** Specifically, this means that the conflict handler is not invoked
2516fca… drh 1370 ** for:
2516fca… drh 1371 ** <ul>
2516fca… drh 1372 ** <li>a delete change if the row being deleted cannot be found,
2516fca… drh 1373 ** <li>an update change if the modified fields are already set to
2516fca… drh 1374 ** their new values in the conflicting row, or
2516fca… drh 1375 ** <li>an insert change if all fields of the conflicting row match
2516fca… drh 1376 ** the row being inserted.
2516fca… drh 1377 ** </ul>
b0db6dd… drh 1378 **
b0db6dd… drh 1379 ** <dt>SQLITE_CHANGESETAPPLY_FKNOACTION <dd>
b0db6dd… drh 1380 ** If this flag it set, then all foreign key constraints in the target
b0db6dd… drh 1381 ** database behave as if they were declared with "ON UPDATE NO ACTION ON
b0db6dd… drh 1382 ** DELETE NO ACTION", even if they are actually CASCADE, RESTRICT, SET NULL
b0db6dd… drh 1383 ** or SET DEFAULT.
2516fca… drh 1384 #define SQLITE_CHANGESETAPPLY_IGNORENOOP 0x0004
b0db6dd… drh 1385 #define SQLITE_CHANGESETAPPLY_FKNOACTION 0x0008
0185597… drh 1386 SQLITE_API int sqlite3changeset_apply_v3_strm(
0185597… drh 1387 sqlite3 *db, /* Apply change to "main" db of this handle */
0185597… drh 1388 int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
0185597… drh 1389 void *pIn, /* First arg for xInput */
0185597… drh 1390 int(*xFilter)(
0185597… drh 1391 void *pCtx, /* Copy of sixth arg to _apply() */
0185597… drh 1392 sqlite3_changeset_iter *p
0185597… drh 1393 ),
0185597… drh 1394 int(*xConflict)(
0185597… drh 1395 void *pCtx, /* Copy of sixth arg to _apply() */
0185597… drh 1396 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
0185597… drh 1397 sqlite3_changeset_iter *p /* Handle describing change and conflict */
0185597… drh 1398 ),
0185597… drh 1399 void *pCtx, /* First argument passed to xConflict */
0185597… drh 1400 void **ppRebase, int *pnRebase,
0185597… drh 1401 int flags
0185597… drh 1402 );
ad59a04… drh 1403
ad59a04… drh 1404 /*
ad59a04… drh 1405 ** CAPI3REF: Configure a changegroup object
ad59a04… drh 1406 **
ad59a04… drh 1407 ** Configure the changegroup object passed as the first argument.
ad59a04… drh 1408 ** At present the only valid value for the second parameter is
ad59a04… drh 1409 ** [SQLITE_CHANGEGROUP_CONFIG_PATCHSET].
ad59a04… drh 1410 */
ad59a04… drh 1411 SQLITE_API int sqlite3changegroup_config(sqlite3_changegroup*, int, void *pArg);
ad59a04… drh 1412
ad59a04… drh 1413 /*
ad59a04… drh 1414 ** CAPI3REF: Options for sqlite3changegroup_config().
ad59a04… drh 1415 **
ad59a04… drh 1416 ** The following values may be passed as the 2nd parameter to
ad59a04… drh 1417 ** sqlite3changegroup_config().
ad59a04… drh 1418 **
ad59a04… drh 1419 ** <dt>SQLITE_CHANGEGROUP_CONFIG_PATCHSET <dd>
ad59a04… drh 1420 ** A changegroup object generates either a changeset or patchset. Usually,
ad59a04… drh 1421 ** this is determined by whether the first call to sqlite3changegroup_add()
ad59a04… drh 1422 ** is passed a changeset or a patchset. Or, if the first changes are added
ad59a04… drh 1423 ** to the changegroup object using the sqlite3changegroup_change_xxx()
ad59a04… drh 1424 ** APIs, then this option may be used to configure whether the changegroup
ad59a04… drh 1425 ** object generates a changeset or patchset.
ad59a04… drh 1426 **
ad59a04… drh 1427 ** When this option is invoked, parameter pArg must point to a value of
ad59a04… drh 1428 ** type int. If the changegroup currently contains zero changes, and the
ad59a04… drh 1429 ** value of the int variable is zero or greater than zero, then the
ad59a04… drh 1430 ** changegroup is configured to generate a changeset or patchset,
ad59a04… drh 1431 ** respectively. It is a no-op, not an error, if the changegroup is not
ad59a04… drh 1432 ** configured because it has already started accumulating changes.
ad59a04… drh 1433 **
ad59a04… drh 1434 ** Before returning, the int variable is set to 0 if the changegroup is
ad59a04… drh 1435 ** configured to generate a changeset, or 1 if it is configured to generate
ad59a04… drh 1436 ** a patchset.
ad59a04… drh 1437 */
ad59a04… drh 1438 #define SQLITE_CHANGEGROUP_CONFIG_PATCHSET 1
ad59a04… drh 1439
ad59a04… drh 1440
ad59a04… drh 1441 /*
ad59a04… drh 1442 ** CAPI3REF: Begin adding a change to a changegroup
ad59a04… drh 1443 **
ad59a04… drh 1444 ** This API is used, in concert with other sqlite3changegroup_change_xxx()
ad59a04… drh 1445 ** APIs, to add changes to a changegroup object one at a time. To add a
ad59a04… drh 1446 ** single change, the caller must:
ad59a04… drh 1447 **
ad59a04… drh 1448 ** 1. Invoke sqlite3changegroup_change_begin() to indicate the type of
ad59a04… drh 1449 ** change (INSERT, UPDATE or DELETE), the affected table and whether
ad59a04… drh 1450 ** or not the change should be marked as indirect.
ad59a04… drh 1451 **
ad59a04… drh 1452 ** 2. Invoke sqlite3changegroup_change_int64() or one of the other four
ad59a04… drh 1453 ** value functions - _null(), _double(), _text() or _blob() - one or
ad59a04… drh 1454 ** more times to specify old.* and new.* values for the change being
ad59a04… drh 1455 ** constructed.
ad59a04… drh 1456 **
ad59a04… drh 1457 ** 3. Invoke sqlite3changegroup_change_finish() to either finish adding
ad59a04… drh 1458 ** the change to the group, or to discard the change altogether.
ad59a04… drh 1459 **
ad59a04… drh 1460 ** The first argument to this function must be a pointer to the existing
ad59a04… drh 1461 ** changegroup object that the change will be added to. The second argument
ad59a04… drh 1462 ** must be SQLITE_INSERT, SQLITE_UPDATE or SQLITE_DELETE. The third is the
ad59a04… drh 1463 ** name of the table that the change affects, and the fourth is a boolean
ad59a04… drh 1464 ** flag specifying whether the change should be marked as "indirect" (if
ad59a04… drh 1465 ** bIndirect is non-zero) or not indirect (if bIndirect is zero).
ad59a04… drh 1466 **
ad59a04… drh 1467 ** Following a successful call to this function, this function may not be
ad59a04… drh 1468 ** called again on the same changegroup object until after
ad59a04… drh 1469 ** sqlite3changegroup_change_finish() has been called. Doing so is an
ad59a04… drh 1470 ** SQLITE_MISUSE error.
ad59a04… drh 1471 **
ad59a04… drh 1472 ** The changegroup object passed as the first argument must be already
ad59a04… drh 1473 ** configured with schema data for the specified table. It may be configured
ad59a04… drh 1474 ** either by calling sqlite3changegroup_schema() with a database that contains
ad59a04… drh 1475 ** the table, or sqlite3changegroup_add() with a changeset that contains the
ad59a04… drh 1476 ** table. If the changegroup object has not been configured with a schema for
ad59a04… drh 1477 ** the specified table when this function is called, SQLITE_ERROR is returned.
ad59a04… drh 1478 **
ad59a04… drh 1479 ** If successful, SQLITE_OK is returned. Otherwise, if an error occurs, an
ad59a04… drh 1480 ** SQLite error code is returned. In this case, if argument pzErr is non-NULL,
ad59a04… drh 1481 ** then (*pzErr) may be set to point to a buffer containing a utf-8 formated,
ad59a04… drh 1482 ** nul-terminated, English language error message. It is the responsibility
ad59a04… drh 1483 ** of the caller to eventually free this buffer using sqlite3_free().
ad59a04… drh 1484 */
ad59a04… drh 1485 SQLITE_API int sqlite3changegroup_change_begin(
ad59a04… drh 1486 sqlite3_changegroup*,
ad59a04… drh 1487 int eOp,
ad59a04… drh 1488 const char *zTab,
ad59a04… drh 1489 int bIndirect,
ad59a04… drh 1490 char **pzErr
ad59a04… drh 1491 );
ad59a04… drh 1492
ad59a04… drh 1493 /*
ad59a04… drh 1494 ** CAPI3REF: Add a 64-bit integer to a changegroup
ad59a04… drh 1495 **
ad59a04… drh 1496 ** This function may only be called between a successful call to
ad59a04… drh 1497 ** sqlite3changegroup_change_begin() and its matching
ad59a04… drh 1498 ** sqlite3changegroup_change_finish() call. If it is called at any
ad59a04… drh 1499 ** other time, it is an SQLITE_MISUSE error. Calling this function
ad59a04… drh 1500 ** specifies a 64-bit integer value to be used in the change currently being
ad59a04… drh 1501 ** added to the changegroup object passed as the first argument.
ad59a04… drh 1502 **
ad59a04… drh 1503 ** The second parameter, bNew, specifies whether the value is to be part of
ad59a04… drh 1504 ** the new.* (if bNew is non-zero) or old.* (if bNew is zero) record of
ad59a04… drh 1505 ** the change under construction. If this does not match the type of change
ad59a04… drh 1506 ** specified by the preceding call to sqlite3changegroup_change_begin() (i.e.
ad59a04… drh 1507 ** an old.* value for an SQLITE_INSERT change, or a new.* value for an
ad59a04… drh 1508 ** SQLITE_DELETE), then SQLITE_ERROR is returned.
ad59a04… drh 1509 **
ad59a04… drh 1510 ** The third parameter specifies the column of the old.* or new.* record that
ad59a04… drh 1511 ** the value will be a part of. If the specified table has an explicit primary
ad59a04… drh 1512 ** key, then this is the index of the table column, numbered from 0 in the order
ad59a04… drh 1513 ** specified within the CREATE TABLE statement. Or, if the table uses an
ad59a04… drh 1514 ** implicit rowid key, then the column 0 is the rowid and the explicit columns
ad59a04… drh 1515 ** are numbered starting from 1. If the iCol parameter is less than 0 or greater
ad59a04… drh 1516 ** than the index of the last column in the table, SQLITE_RANGE is returned.
ad59a04… drh 1517 **
ad59a04… drh 1518 ** The fourth parameter is the integer value to use as part of the old.* or
ad59a04… drh 1519 ** new.* record.
ad59a04… drh 1520 **
ad59a04… drh 1521 ** If this call is successful, SQLITE_OK is returned. Otherwise, if an
ad59a04… drh 1522 ** error occurs, an SQLite error code is returned.
ad59a04… drh 1523 */
ad59a04… drh 1524 SQLITE_API int sqlite3changegroup_change_int64(
ad59a04… drh 1525 sqlite3_changegroup*,
ad59a04… drh 1526 int bNew,
ad59a04… drh 1527 int iCol,
ad59a04… drh 1528 sqlite3_int64 iVal
ad59a04… drh 1529 );
ad59a04… drh 1530
ad59a04… drh 1531 /*
ad59a04… drh 1532 ** CAPI3REF: Add a NULL to a changegroup
ad59a04… drh 1533 **
ad59a04… drh 1534 ** This function is similar to sqlite3changegroup_change_int64(). Except that
ad59a04… drh 1535 ** it configures the change currently under construction with a NULL value
ad59a04… drh 1536 ** instead of a 64-bit integer.
ad59a04… drh 1537 */
ad59a04… drh 1538 SQLITE_API int sqlite3changegroup_change_null(sqlite3_changegroup*, int, int);
ad59a04… drh 1539
ad59a04… drh 1540 /*
ad59a04… drh 1541 ** CAPI3REF: Add an double to a changegroup
ad59a04… drh 1542 **
ad59a04… drh 1543 ** This function is similar to sqlite3changegroup_change_int64(). Except that
ad59a04… drh 1544 ** it configures the change currently being constructed with a real value
ad59a04… drh 1545 ** instead of a 64-bit integer.
ad59a04… drh 1546 */
ad59a04… drh 1547 SQLITE_API int sqlite3changegroup_change_double(sqlite3_changegroup*, int, int, double);
ad59a04… drh 1548
ad59a04… drh 1549 /*
ad59a04… drh 1550 ** CAPI3REF: Add a text value to a changegroup
ad59a04… drh 1551 **
ad59a04… drh 1552 ** This function is similar to sqlite3changegroup_change_int64(). It configures
ad59a04… drh 1553 ** the currently accumulated change with a text value instead of a 64-bit
ad59a04… drh 1554 ** integer. Parameter pVal points to a buffer containing the text encoded using
ad59a04… drh 1555 ** utf-8. Parameter nVal may either be the size of the text value in bytes, or
ad59a04… drh 1556 ** else a negative value, in which case the buffer pVal points to is assumed to
ad59a04… drh 1557 ** be nul-terminated.
ad59a04… drh 1558 */
ad59a04… drh 1559 SQLITE_API int sqlite3changegroup_change_text(
ad59a04… drh 1560 sqlite3_changegroup*, int, int, const char *pVal, int nVal
ad59a04… drh 1561 );
ad59a04… drh 1562
ad59a04… drh 1563 /*
ad59a04… drh 1564 ** CAPI3REF: Add a blob to a changegroup
ad59a04… drh 1565 **
ad59a04… drh 1566 ** This function is similar to sqlite3changegroup_change_int64(). It configures
ad59a04… drh 1567 ** the currently accumulated change with a blob value instead of a 64-bit
ad59a04… drh 1568 ** integer. Parameter pVal points to a buffer containing the blob. Parameter
ad59a04… drh 1569 ** nVal is the size of the blob in bytes.
ad59a04… drh 1570 */
ad59a04… drh 1571 SQLITE_API int sqlite3changegroup_change_blob(
ad59a04… drh 1572 sqlite3_changegroup*, int, int, const void *pVal, int nVal
ad59a04… drh 1573 );
ad59a04… drh 1574
ad59a04… drh 1575 /*
ad59a04… drh 1576 ** CAPI3REF: Finish adding one-at-at-time changes to a changegroup
ad59a04… drh 1577 **
ad59a04… drh 1578 ** This function may only be called following a successful call to
ad59a04… drh 1579 ** sqlite3changegroup_change_begin(). Otherwise, it is an SQLITE_MISUSE error.
ad59a04… drh 1580 **
ad59a04… drh 1581 ** If parameter bDiscard is non-zero, then the current change is simply
ad59a04… drh 1582 ** discarded. In this case this function is always successful and SQLITE_OK
ad59a04… drh 1583 ** returned.
ad59a04… drh 1584 **
ad59a04… drh 1585 ** If parameter bDiscard is zero, then an attempt is made to add the current
ad59a04… drh 1586 ** change to the changegroup. Assuming the changegroup is configured to
ad59a04… drh 1587 ** produce a changeset (not a patchset), this requires that:
ad59a04… drh 1588 **
ad59a04… drh 1589 ** * If the change is an INSERT or DELETE, then a value must be specified
ad59a04… drh 1590 ** for all columns of the new.* or old.* record, respectively.
ad59a04… drh 1591 **
ad59a04… drh 1592 ** * If the change is an UPDATE record, then values must be provided for
ad59a04… drh 1593 ** the PRIMARY KEY columns of the old.* record, but must not be provided
ad59a04… drh 1594 ** for PRIMARY KEY columns of the new.* record.
ad59a04… drh 1595 **
ad59a04… drh 1596 ** * If the change is an UPDATE record, then for each non-PRIMARY KEY
ad59a04… drh 1597 ** column in the old.* record for which a value has been provided, a
ad59a04… drh 1598 ** value must also be provided for the same column in the new.* record.
ad59a04… drh 1599 ** Similarly, for each non-PK column in the old.* record for which
ad59a04… drh 1600 ** a value is not provided, a value must not be provided for the same
ad59a04… drh 1601 ** column in the new.* record.
ad59a04… drh 1602 **
ad59a04… drh 1603 ** * All values specified for PRIMARY KEY columns must be non-NULL.
ad59a04… drh 1604 **
ad59a04… drh 1605 ** Otherwise, it is an error.
ad59a04… drh 1606 **
ad59a04… drh 1607 ** If the changegroup already contains a change for the same row (identified
ad59a04… drh 1608 ** by PRIMARY KEY columns), then the current change is combined with the
ad59a04… drh 1609 ** existing change in the same way as for sqlite3changegroup_add().
ad59a04… drh 1610 **
ad59a04… drh 1611 ** For a patchset, all of the above rules apply except that it doesn't matter
ad59a04… drh 1612 ** whether or not values are provided for the non-PK old.* record columns
ad59a04… drh 1613 ** for an UPDATE or DELETE change. This means that code used to produce
ad59a04… drh 1614 ** a changeset using the sqlite3changegroup_change_xxx() APIs may also
ad59a04… drh 1615 ** be used to produce patchsets.
ad59a04… drh 1616 **
ad59a04… drh 1617 ** If the call is successful, SQLITE_OK is returned. Otherwise, if an error
ad59a04… drh 1618 ** occurs, an SQLite error code is returned. If an error is returned and
ad59a04… drh 1619 ** parameter pzErr is not NULL, then (*pzErr) may be set to point to a buffer
ad59a04… drh 1620 ** containing a nul-terminated, utf-8 encoded, English language error message.
ad59a04… drh 1621 ** It is the responsibility of the caller to eventually free any such error
ad59a04… drh 1622 ** message buffer using sqlite3_free().
ad59a04… drh 1623 */
ad59a04… drh 1624 SQLITE_API int sqlite3changegroup_change_finish(
ad59a04… drh 1625 sqlite3_changegroup*,
ad59a04… drh 1626 int bDiscard,
ad59a04… drh 1627 char **pzErr
ad59a04… drh 1628 );
92f2a04… danield 1629
92f2a04… danield 1630 /*
92f2a04… danield 1631 ** Return a copy of the pUserData pointer passed to the xCreateFunction()
92f2a04… danield 1632 ** API when the extension function was registered.
6da2550… drh 1633 ** If parameter iCol is less than zero, or greater than or equal to the
6da2550… drh 1634 ** number of columns in the table, SQLITE_RANGE is returned.
6da2550… drh 1635 **
6da2550… drh 1636 ** Otherwise, this function attempts to retrieve the text of column iCol of
6da2550… drh 1637 ** the current document. If successful, (*pz) is set to point to a buffer
6da2550… drh 1638 ** If parameter iCol is less than zero, or greater than or equal to the
6da2550… drh 1639 ** number of phrases in the current query, as returned by xPhraseCount,
6da2550… drh 1640 ** 0 is returned. Otherwise, this function returns the number of tokens in
6da2550… drh 1641 ** phrase iPhrase of the query. Phrases are numbered starting from zero.
6da2550… drh 1642 ** output by xInstCount(). If iIdx is less than zero or greater than
6da2550… drh 1643 ** or equal to the value returned by xInstCount(), SQLITE_RANGE is returned.
6da2550… drh 1644 ** Otherwise, output parameter *piPhrase is set to the phrase number, *piCol
6da2550… drh 1645 ** first token of the phrase. SQLITE_OK is returned if successful, or an
6da2550… drh 1646 ** error code (i.e. SQLITE_NOMEM) if an error occurs.
6da2550… drh 1647 **
6da2550… drh 1648 ** If parameter iPhrase is less than zero, or greater than or equal to
6da2550… drh 1649 ** the number of phrases in the query, as returned by xPhraseCount(),
6da2550… drh 1650 ** this function returns SQLITE_RANGE.
cd50820… drh 1651 ** In all cases, matches are visited in (column ASC, offset ASC) order.
cd50820… drh 1652 ** i.e. all those in column 0, sorted by offset, followed by those in
cd50820… drh 1653 ** column 1, etc.
cd50820… drh 1654 **
70cae0a… drh 1655 **
70cae0a… drh 1656 ** xQueryToken(pFts5, iPhrase, iToken, ppToken, pnToken)
70cae0a… drh 1657 ** This is used to access token iToken of phrase iPhrase of the current
70cae0a… drh 1658 ** query. Before returning, output parameter *ppToken is set to point
70cae0a… drh 1659 ** to a buffer containing the requested token, and *pnToken to the
70cae0a… drh 1660 ** size of this buffer in bytes.
70cae0a… drh 1661 **
6da2550… drh 1662 ** If iPhrase or iToken are less than zero, or if iPhrase is greater than
6da2550… drh 1663 ** or equal to the number of phrases in the query as reported by
6da2550… drh 1664 ** xPhraseCount(), or if iToken is equal to or greater than the number of
6da2550… drh 1665 ** tokens in the phrase, SQLITE_RANGE is returned and *ppToken and *pnToken
6da2550… drh 1666 are both zeroed.
6da2550… drh 1667 **
70cae0a… drh 1668 ** The output text is not a copy of the query text that specified the
70cae0a… drh 1669 ** token. It is the output of the tokenizer module. For tokendata=1
70cae0a… drh 1670 ** tables, this includes any embedded 0x00 and trailing data.
70cae0a… drh 1671 **
70cae0a… drh 1672 ** xInstToken(pFts5, iIdx, iToken, ppToken, pnToken)
70cae0a… drh 1673 ** This is used to access token iToken of phrase hit iIdx within the
6da2550… drh 1674 ** current row. If iIdx is less than zero or greater than or equal to the
6da2550… drh 1675 ** value returned by xInstCount(), SQLITE_RANGE is returned. Otherwise,
6da2550… drh 1676 ** output variable (*ppToken) is set to point to a buffer containing the
6da2550… drh 1677 ** matching document token, and (*pnToken) to the size of that buffer in
077e53a… drh 1678 ** bytes.
70cae0a… drh 1679 **
70cae0a… drh 1680 ** The output text is not a copy of the document text that was tokenized.
70cae0a… drh 1681 ** It is the output of the tokenizer module. For tokendata=1 tables, this
70cae0a… drh 1682 ** includes any embedded 0x00 and trailing data.
077e53a… drh 1683 **
077e53a… drh 1684 ** This API may be slow in some cases if the token identified by parameters
077e53a… drh 1685 ** iIdx and iToken matched a prefix token in the query. In most cases, the
077e53a… drh 1686 ** first call to this API for each prefix token in the query is forced
077e53a… drh 1687 ** to scan the portion of the full-text index that matches the prefix
077e53a… drh 1688 ** token to collect the extra data required by this API. If the prefix
077e53a… drh 1689 ** token matches a large number of token instances in the document set,
077e53a… drh 1690 ** this may be a performance problem.
077e53a… drh 1691 **
077e53a… drh 1692 ** If the user knows in advance that a query may use this API for a
077e53a… drh 1693 ** prefix token, FTS5 may be configured to collect all required data as part
077e53a… drh 1694 ** of the initial querying of the full-text index, avoiding the second scan
077e53a… drh 1695 ** entirely. This also causes prefix queries that do not use this API to
077e53a… drh 1696 ** run more slowly and use more memory. FTS5 may be configured in this way
077e53a… drh 1697 ** either on a per-table basis using the [FTS5 insttoken | 'insttoken']
077e53a… drh 1698 ** option, or on a per-query basis using the
077e53a… drh 1699 ** [fts5_insttoken | fts5_insttoken()] user function.
e17b8da… stephan 1700 **
70cae0a… drh 1701 ** This API can be quite slow if used with an FTS5 table created with the
70cae0a… drh 1702 ** "detail=none" or "detail=column" option.
e17b8da… stephan 1703 **
e17b8da… stephan 1704 ** xColumnLocale(pFts5, iIdx, pzLocale, pnLocale)
e17b8da… stephan 1705 ** If parameter iCol is less than zero, or greater than or equal to the
e17b8da… stephan 1706 ** number of columns in the table, SQLITE_RANGE is returned.
e17b8da… stephan 1707 **
e17b8da… stephan 1708 ** Otherwise, this function attempts to retrieve the locale associated
e17b8da… stephan 1709 ** with column iCol of the current row. Usually, there is no associated
e17b8da… stephan 1710 ** locale, and output parameters (*pzLocale) and (*pnLocale) are set
e17b8da… stephan 1711 ** to NULL and 0, respectively. However, if the fts5_locale() function
e17b8da… stephan 1712 ** was used to associate a locale with the value when it was inserted
e17b8da… stephan 1713 ** into the fts5 table, then (*pzLocale) is set to point to a nul-terminated
e17b8da… stephan 1714 ** buffer containing the name of the locale in utf-8 encoding. (*pnLocale)
e17b8da… stephan 1715 ** is set to the size in bytes of the buffer, not including the
e17b8da… stephan 1716 ** nul-terminator.
e17b8da… stephan 1717 **
e17b8da… stephan 1718 ** If successful, SQLITE_OK is returned. Or, if an error occurs, an
e17b8da… stephan 1719 ** SQLite error code is returned. The final value of the output parameters
e17b8da… stephan 1720 ** is undefined in this case.
e17b8da… stephan 1721 **
e17b8da… stephan 1722 ** xTokenize_v2:
e17b8da… stephan 1723 ** Tokenize text using the tokenizer belonging to the FTS5 table. This
e17b8da… stephan 1724 ** API is the same as the xTokenize() API, except that it allows a tokenizer
e17b8da… stephan 1725 ** locale to be specified.
e17b8da… stephan 1726 int iVersion; /* Currently always set to 4 */
70cae0a… drh 1727
70cae0a… drh 1728 /* Below this point are iVersion>=3 only */
70cae0a… drh 1729 int (*xQueryToken)(Fts5Context*,
70cae0a… drh 1730 int iPhrase, int iToken,
70cae0a… drh 1731 const char **ppToken, int *pnToken
70cae0a… drh 1732 );
70cae0a… drh 1733 int (*xInstToken)(Fts5Context*, int iIdx, int iToken, const char**, int*);
e17b8da… stephan 1734
e17b8da… stephan 1735 /* Below this point are iVersion>=4 only */
e17b8da… stephan 1736 int (*xColumnLocale)(Fts5Context*, int iCol, const char **pz, int *pn);
e17b8da… stephan 1737 int (*xTokenize_v2)(Fts5Context*,
e17b8da… stephan 1738 const char *pText, int nText, /* Text to tokenize */
e17b8da… stephan 1739 const char *pLocale, int nLocale, /* Locale to pass to tokenizer */
e17b8da… stephan 1740 void *pCtx, /* Context passed to xToken() */
e17b8da… stephan 1741 int (*xToken)(void*, int, const char*, int, int, int) /* Callback */
e17b8da… stephan 1742 );
e17b8da… stephan 1743 ** pointer provided by the application when the fts5_tokenizer_v2 object
e17b8da… stephan 1744 ** The third argument indicates the reason that FTS5 is requesting
e17b8da… stephan 1745 ** The sixth and seventh arguments passed to xTokenize() - pLocale and
e17b8da… stephan 1746 ** nLocale - are a pointer to a buffer containing the locale to use for
e17b8da… stephan 1747 ** tokenization (e.g. "en_US") and its size in bytes, respectively. The
e17b8da… stephan 1748 ** pLocale buffer is not nul-terminated. pLocale may be passed NULL (in
e17b8da… stephan 1749 ** which case nLocale is always 0) to indicate that the tokenizer should
e17b8da… stephan 1750 ** use its default locale.
e17b8da… stephan 1751 **
e17b8da… stephan 1752 **
e17b8da… stephan 1753 ** If the tokenizer is registered using an fts5_tokenizer_v2 object,
e17b8da… stephan 1754 ** then the xTokenize() method has two additional arguments - pLocale
e17b8da… stephan 1755 ** and nLocale. These specify the locale that the tokenizer should use
e17b8da… stephan 1756 ** for the current request. If pLocale and nLocale are both 0, then the
e17b8da… stephan 1757 ** tokenizer should use its default locale. Otherwise, pLocale points to
e17b8da… stephan 1758 ** an nLocale byte buffer containing the name of the locale to use as utf-8
e17b8da… stephan 1759 ** text. pLocale is not nul-terminated.
e17b8da… stephan 1760 **
e17b8da… stephan 1761 ** FTS5_TOKENIZER
e17b8da… stephan 1762 **
ff93103… drh 1763 ** There is also an fts5_tokenizer object. This is an older, deprecated,
ff93103… drh 1764 ** version of fts5_tokenizer_v2. It is similar except that:
e17b8da… stephan 1765 **
e17b8da… stephan 1766 ** <ul>
e17b8da… stephan 1767 ** <li> There is no "iVersion" field, and
e17b8da… stephan 1768 ** <li> The xTokenize() method does not take a locale argument.
e17b8da… stephan 1769 ** </ul>
e17b8da… stephan 1770 **
ff93103… drh 1771 ** Legacy fts5_tokenizer tokenizers must be registered using the
ff93103… drh 1772 ** legacy xCreateTokenizer() function, instead of xCreateTokenizer_v2().
ff93103… drh 1773 **
ff93103… drh 1774 ** Tokenizer implementations registered using either API may be retrieved
ff93103… drh 1775 ** using both xFindTokenizer() and xFindTokenizer_v2().
b5aa9f8… drh 1776 ** provide synonyms when tokenizing document text (method (3)) or query
b5aa9f8… drh 1777 ** text (method (2)), not both. Doing so will not cause any errors, but is
e17b8da… stephan 1778 typedef struct fts5_tokenizer_v2 fts5_tokenizer_v2;
e17b8da… stephan 1779 struct fts5_tokenizer_v2 {
e17b8da… stephan 1780 int iVersion; /* Currently always 2 */
e17b8da… stephan 1781
e17b8da… stephan 1782 int (*xCreate)(void*, const char **azArg, int nArg, Fts5Tokenizer **ppOut);
e17b8da… stephan 1783 void (*xDelete)(Fts5Tokenizer*);
e17b8da… stephan 1784 int (*xTokenize)(Fts5Tokenizer*,
e17b8da… stephan 1785 void *pCtx,
e17b8da… stephan 1786 int flags, /* Mask of FTS5_TOKENIZE_* flags */
e17b8da… stephan 1787 const char *pText, int nText,
e17b8da… stephan 1788 const char *pLocale, int nLocale,
e17b8da… stephan 1789 int (*xToken)(
e17b8da… stephan 1790 void *pCtx, /* Copy of 2nd argument to xTokenize() */
e17b8da… stephan 1791 int tflags, /* Mask of FTS5_TOKEN_* flags */
e17b8da… stephan 1792 const char *pToken, /* Pointer to buffer containing token */
e17b8da… stephan 1793 int nToken, /* Size of token in bytes */
e17b8da… stephan 1794 int iStart, /* Byte offset of token within input text */
e17b8da… stephan 1795 int iEnd /* Byte offset of end of token within input text */
e17b8da… stephan 1796 )
e17b8da… stephan 1797 );
e17b8da… stephan 1798 };
e17b8da… stephan 1799
e17b8da… stephan 1800 /*
e17b8da… stephan 1801 ** New code should use the fts5_tokenizer_v2 type to define tokenizer
e17b8da… stephan 1802 ** implementations. The following type is included for legacy applications
e17b8da… stephan 1803 ** that still use it.
e17b8da… stephan 1804 */
e17b8da… stephan 1805
e17b8da… stephan 1806 int iVersion; /* Currently always set to 3 */
16ee395… drh 1807 void *pUserData,
16ee395… drh 1808 void **ppUserData,
16ee395… drh 1809 void *pUserData,
16ee395… drh 1810 );
e17b8da… stephan 1811
e17b8da… stephan 1812 /* APIs below this point are only available if iVersion>=3 */
e17b8da… stephan 1813
e17b8da… stephan 1814 /* Create a new tokenizer */
e17b8da… stephan 1815 int (*xCreateTokenizer_v2)(
e17b8da… stephan 1816 fts5_api *pApi,
e17b8da… stephan 1817 const char *zName,
e17b8da… stephan 1818 void *pUserData,
e17b8da… stephan 1819 fts5_tokenizer_v2 *pTokenizer,
e17b8da… stephan 1820 void (*xDestroy)(void*)
e17b8da… stephan 1821 );
e17b8da… stephan 1822
e17b8da… stephan 1823 /* Find an existing tokenizer */
e17b8da… stephan 1824 int (*xFindTokenizer_v2)(
e17b8da… stephan 1825 fts5_api *pApi,
e17b8da… stephan 1826 const char *zName,
e17b8da… stephan 1827 void **ppUserData,
e17b8da… stephan 1828 fts5_tokenizer_v2 **ppTokenizer
e17b8da… stephan 1829 );
66899f8… drh 1830 #endif /* SQLITE3_H */

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button