Mercurial > embed
comparison libsqlite/sqlite3.h @ 78:c55ff9f22dca
sqlite: upgrade to 3.29.0
author | David Demelier <markand@malikania.fr> |
---|---|
date | Mon, 22 Jul 2019 21:09:00 +0200 |
parents | 0bd0077049ff |
children | 46cf089188ab |
comparison
equal
deleted
inserted
replaced
77:024c6b4e4992 | 78:c55ff9f22dca |
---|---|
121 ** | 121 ** |
122 ** See also: [sqlite3_libversion()], | 122 ** See also: [sqlite3_libversion()], |
123 ** [sqlite3_libversion_number()], [sqlite3_sourceid()], | 123 ** [sqlite3_libversion_number()], [sqlite3_sourceid()], |
124 ** [sqlite_version()] and [sqlite_source_id()]. | 124 ** [sqlite_version()] and [sqlite_source_id()]. |
125 */ | 125 */ |
126 #define SQLITE_VERSION "3.24.0" | 126 #define SQLITE_VERSION "3.29.0" |
127 #define SQLITE_VERSION_NUMBER 3024000 | 127 #define SQLITE_VERSION_NUMBER 3029000 |
128 #define SQLITE_SOURCE_ID "2018-06-04 19:24:41 c7ee0833225bfd8c5ec2f9bf62b97c4e04d03bd9566366d5221ac8fb199a87ca" | 128 #define SQLITE_SOURCE_ID "2019-07-10 17:32:03 fc82b73eaac8b36950e527f12c4b5dc1e147e6f4ad2217ae43ad82882a88bfa6" |
129 | 129 |
130 /* | 130 /* |
131 ** CAPI3REF: Run-Time Library Version Numbers | 131 ** CAPI3REF: Run-Time Library Version Numbers |
132 ** KEYWORDS: sqlite3_version sqlite3_sourceid | 132 ** KEYWORDS: sqlite3_version sqlite3_sourceid |
133 ** | 133 ** |
187 ** [sqlite_compileoption_get()] and the [compile_options pragma]. | 187 ** [sqlite_compileoption_get()] and the [compile_options pragma]. |
188 */ | 188 */ |
189 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS | 189 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS |
190 SQLITE_API int sqlite3_compileoption_used(const char *zOptName); | 190 SQLITE_API int sqlite3_compileoption_used(const char *zOptName); |
191 SQLITE_API const char *sqlite3_compileoption_get(int N); | 191 SQLITE_API const char *sqlite3_compileoption_get(int N); |
192 #else | |
193 # define sqlite3_compileoption_used(X) 0 | |
194 # define sqlite3_compileoption_get(X) ((void*)0) | |
192 #endif | 195 #endif |
193 | 196 |
194 /* | 197 /* |
195 ** CAPI3REF: Test To See If The Library Is Threadsafe | 198 ** CAPI3REF: Test To See If The Library Is Threadsafe |
196 ** | 199 ** |
470 ** the most recent error can be obtained using | 473 ** the most recent error can be obtained using |
471 ** [sqlite3_extended_errcode()]. | 474 ** [sqlite3_extended_errcode()]. |
472 */ | 475 */ |
473 #define SQLITE_ERROR_MISSING_COLLSEQ (SQLITE_ERROR | (1<<8)) | 476 #define SQLITE_ERROR_MISSING_COLLSEQ (SQLITE_ERROR | (1<<8)) |
474 #define SQLITE_ERROR_RETRY (SQLITE_ERROR | (2<<8)) | 477 #define SQLITE_ERROR_RETRY (SQLITE_ERROR | (2<<8)) |
478 #define SQLITE_ERROR_SNAPSHOT (SQLITE_ERROR | (3<<8)) | |
475 #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) | 479 #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) |
476 #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) | 480 #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) |
477 #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) | 481 #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) |
478 #define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) | 482 #define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) |
479 #define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) | 483 #define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) |
509 #define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8)) | 513 #define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8)) |
510 #define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8)) | 514 #define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8)) |
511 #define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8)) | 515 #define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8)) |
512 #define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3<<8)) | 516 #define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3<<8)) |
513 #define SQLITE_CANTOPEN_CONVPATH (SQLITE_CANTOPEN | (4<<8)) | 517 #define SQLITE_CANTOPEN_CONVPATH (SQLITE_CANTOPEN | (4<<8)) |
518 #define SQLITE_CANTOPEN_DIRTYWAL (SQLITE_CANTOPEN | (5<<8)) /* Not Used */ | |
514 #define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8)) | 519 #define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8)) |
515 #define SQLITE_CORRUPT_SEQUENCE (SQLITE_CORRUPT | (2<<8)) | 520 #define SQLITE_CORRUPT_SEQUENCE (SQLITE_CORRUPT | (2<<8)) |
516 #define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8)) | 521 #define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8)) |
517 #define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8)) | 522 #define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8)) |
518 #define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3<<8)) | 523 #define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3<<8)) |
819 ** current transaction. This hint is not guaranteed to be accurate but it | 824 ** current transaction. This hint is not guaranteed to be accurate but it |
820 ** is often close. The underlying VFS might choose to preallocate database | 825 ** is often close. The underlying VFS might choose to preallocate database |
821 ** file space based on this hint in order to help writes to the database | 826 ** file space based on this hint in order to help writes to the database |
822 ** file run faster. | 827 ** file run faster. |
823 ** | 828 ** |
829 ** <li>[[SQLITE_FCNTL_SIZE_LIMIT]] | |
830 ** The [SQLITE_FCNTL_SIZE_LIMIT] opcode is used by in-memory VFS that | |
831 ** implements [sqlite3_deserialize()] to set an upper bound on the size | |
832 ** of the in-memory database. The argument is a pointer to a [sqlite3_int64]. | |
833 ** If the integer pointed to is negative, then it is filled in with the | |
834 ** current limit. Otherwise the limit is set to the larger of the value | |
835 ** of the integer pointed to and the current database size. The integer | |
836 ** pointed to is set to the new limit. | |
837 ** | |
824 ** <li>[[SQLITE_FCNTL_CHUNK_SIZE]] | 838 ** <li>[[SQLITE_FCNTL_CHUNK_SIZE]] |
825 ** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS | 839 ** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS |
826 ** extends and truncates the database file in chunks of a size specified | 840 ** extends and truncates the database file in chunks of a size specified |
827 ** by the user. The fourth argument to [sqlite3_file_control()] should | 841 ** by the user. The fourth argument to [sqlite3_file_control()] should |
828 ** point to an integer (type int) containing the new chunk-size to use | 842 ** point to an integer (type int) containing the new chunk-size to use |
884 ** interrogated. The zDbName parameter is ignored. | 898 ** interrogated. The zDbName parameter is ignored. |
885 ** | 899 ** |
886 ** <li>[[SQLITE_FCNTL_PERSIST_WAL]] | 900 ** <li>[[SQLITE_FCNTL_PERSIST_WAL]] |
887 ** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the | 901 ** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the |
888 ** persistent [WAL | Write Ahead Log] setting. By default, the auxiliary | 902 ** persistent [WAL | Write Ahead Log] setting. By default, the auxiliary |
889 ** write ahead log and shared memory files used for transaction control | 903 ** write ahead log ([WAL file]) and shared memory |
904 ** files used for transaction control | |
890 ** are automatically deleted when the latest connection to the database | 905 ** are automatically deleted when the latest connection to the database |
891 ** closes. Setting persistent WAL mode causes those files to persist after | 906 ** closes. Setting persistent WAL mode causes those files to persist after |
892 ** close. Persisting the files is useful when other processes that do not | 907 ** close. Persisting the files is useful when other processes that do not |
893 ** have write permission on the directory containing the database file want | 908 ** have write permission on the directory containing the database file want |
894 ** to read the database file, as the WAL and shared memory files must exist | 909 ** to read the database file, as the WAL and shared memory files must exist |
1070 ** <li>[[SQLITE_FCNTL_LOCK_TIMEOUT]] | 1085 ** <li>[[SQLITE_FCNTL_LOCK_TIMEOUT]] |
1071 ** The [SQLITE_FCNTL_LOCK_TIMEOUT] opcode causes attempts to obtain | 1086 ** The [SQLITE_FCNTL_LOCK_TIMEOUT] opcode causes attempts to obtain |
1072 ** a file lock using the xLock or xShmLock methods of the VFS to wait | 1087 ** a file lock using the xLock or xShmLock methods of the VFS to wait |
1073 ** for up to M milliseconds before failing, where M is the single | 1088 ** for up to M milliseconds before failing, where M is the single |
1074 ** unsigned integer parameter. | 1089 ** unsigned integer parameter. |
1090 ** | |
1091 ** <li>[[SQLITE_FCNTL_DATA_VERSION]] | |
1092 ** The [SQLITE_FCNTL_DATA_VERSION] opcode is used to detect changes to | |
1093 ** a database file. The argument is a pointer to a 32-bit unsigned integer. | |
1094 ** The "data version" for the pager is written into the pointer. The | |
1095 ** "data version" changes whenever any change occurs to the corresponding | |
1096 ** database file, either through SQL statements on the same database | |
1097 ** connection or through transactions committed by separate database | |
1098 ** connections possibly in other processes. The [sqlite3_total_changes()] | |
1099 ** interface can be used to find if any database on the connection has changed, | |
1100 ** but that interface responds to changes on TEMP as well as MAIN and does | |
1101 ** not provide a mechanism to detect changes to MAIN only. Also, the | |
1102 ** [sqlite3_total_changes()] interface responds to internal changes only and | |
1103 ** omits changes made by other database connections. The | |
1104 ** [PRAGMA data_version] command provide a mechanism to detect changes to | |
1105 ** a single attached database that occur due to other database connections, | |
1106 ** but omits changes implemented by the database connection on which it is | |
1107 ** called. This file control is the only mechanism to detect changes that | |
1108 ** happen either internally or externally and that are associated with | |
1109 ** a particular attached database. | |
1075 ** </ul> | 1110 ** </ul> |
1076 */ | 1111 */ |
1077 #define SQLITE_FCNTL_LOCKSTATE 1 | 1112 #define SQLITE_FCNTL_LOCKSTATE 1 |
1078 #define SQLITE_FCNTL_GET_LOCKPROXYFILE 2 | 1113 #define SQLITE_FCNTL_GET_LOCKPROXYFILE 2 |
1079 #define SQLITE_FCNTL_SET_LOCKPROXYFILE 3 | 1114 #define SQLITE_FCNTL_SET_LOCKPROXYFILE 3 |
1105 #define SQLITE_FCNTL_PDB 30 | 1140 #define SQLITE_FCNTL_PDB 30 |
1106 #define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 31 | 1141 #define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 31 |
1107 #define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE 32 | 1142 #define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE 32 |
1108 #define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE 33 | 1143 #define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE 33 |
1109 #define SQLITE_FCNTL_LOCK_TIMEOUT 34 | 1144 #define SQLITE_FCNTL_LOCK_TIMEOUT 34 |
1145 #define SQLITE_FCNTL_DATA_VERSION 35 | |
1146 #define SQLITE_FCNTL_SIZE_LIMIT 36 | |
1110 | 1147 |
1111 /* deprecated names */ | 1148 /* deprecated names */ |
1112 #define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE | 1149 #define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE |
1113 #define SQLITE_SET_LOCKPROXYFILE SQLITE_FCNTL_SET_LOCKPROXYFILE | 1150 #define SQLITE_SET_LOCKPROXYFILE SQLITE_FCNTL_SET_LOCKPROXYFILE |
1114 #define SQLITE_LAST_ERRNO SQLITE_FCNTL_LAST_ERRNO | 1151 #define SQLITE_LAST_ERRNO SQLITE_FCNTL_LAST_ERRNO |
1257 ** | 1294 ** |
1258 ** [[sqlite3_vfs.xAccess]] | 1295 ** [[sqlite3_vfs.xAccess]] |
1259 ** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] | 1296 ** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] |
1260 ** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to | 1297 ** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to |
1261 ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ] | 1298 ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ] |
1262 ** to test whether a file is at least readable. The file can be a | 1299 ** to test whether a file is at least readable. The SQLITE_ACCESS_READ |
1263 ** directory. | 1300 ** flag is never actually used and is not implemented in the built-in |
1301 ** VFSes of SQLite. The file is named by the second argument and can be a | |
1302 ** directory. The xAccess method returns [SQLITE_OK] on success or some | |
1303 ** non-zero error code if there is an I/O error or if the name of | |
1304 ** the file given in the second argument is illegal. If SQLITE_OK | |
1305 ** is returned, then non-zero or zero is written into *pResOut to indicate | |
1306 ** whether or not the file is accessible. | |
1264 ** | 1307 ** |
1265 ** ^SQLite will always allocate at least mxPathname+1 bytes for the | 1308 ** ^SQLite will always allocate at least mxPathname+1 bytes for the |
1266 ** output buffer xFullPathname. The exact size of the output buffer | 1309 ** output buffer xFullPathname. The exact size of the output buffer |
1267 ** is also passed as a parameter to both methods. If the output buffer | 1310 ** is also passed as a parameter to both methods. If the output buffer |
1268 ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is | 1311 ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is |
1946 ** from the database as records are returned in sorted order. The default | 1989 ** from the database as records are returned in sorted order. The default |
1947 ** value for this option is to never use this optimization. Specifying a | 1990 ** value for this option is to never use this optimization. Specifying a |
1948 ** negative value for this option restores the default behaviour. | 1991 ** negative value for this option restores the default behaviour. |
1949 ** This option is only available if SQLite is compiled with the | 1992 ** This option is only available if SQLite is compiled with the |
1950 ** [SQLITE_ENABLE_SORTER_REFERENCES] compile-time option. | 1993 ** [SQLITE_ENABLE_SORTER_REFERENCES] compile-time option. |
1994 ** | |
1995 ** [[SQLITE_CONFIG_MEMDB_MAXSIZE]] | |
1996 ** <dt>SQLITE_CONFIG_MEMDB_MAXSIZE | |
1997 ** <dd>The SQLITE_CONFIG_MEMDB_MAXSIZE option accepts a single parameter | |
1998 ** [sqlite3_int64] parameter which is the default maximum size for an in-memory | |
1999 ** database created using [sqlite3_deserialize()]. This default maximum | |
2000 ** size can be adjusted up or down for individual databases using the | |
2001 ** [SQLITE_FCNTL_SIZE_LIMIT] [sqlite3_file_control|file-control]. If this | |
2002 ** configuration setting is never used, then the default maximum is determined | |
2003 ** by the [SQLITE_MEMDB_DEFAULT_MAXSIZE] compile-time option. If that | |
2004 ** compile-time option is not set, then the default maximum is 1073741824. | |
1951 ** </dl> | 2005 ** </dl> |
1952 */ | 2006 */ |
1953 #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ | 2007 #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ |
1954 #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ | 2008 #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ |
1955 #define SQLITE_CONFIG_SERIALIZED 3 /* nil */ | 2009 #define SQLITE_CONFIG_SERIALIZED 3 /* nil */ |
1976 #define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */ | 2030 #define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */ |
1977 #define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */ | 2031 #define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */ |
1978 #define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */ | 2032 #define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */ |
1979 #define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */ | 2033 #define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */ |
1980 #define SQLITE_CONFIG_SORTERREF_SIZE 28 /* int nByte */ | 2034 #define SQLITE_CONFIG_SORTERREF_SIZE 28 /* int nByte */ |
2035 #define SQLITE_CONFIG_MEMDB_MAXSIZE 29 /* sqlite3_int64 */ | |
1981 | 2036 |
1982 /* | 2037 /* |
1983 ** CAPI3REF: Database Connection Configuration Options | 2038 ** CAPI3REF: Database Connection Configuration Options |
1984 ** | 2039 ** |
1985 ** These constants are the available integer configuration options that | 2040 ** These constants are the available integer configuration options that |
1991 ** the call worked. ^The [sqlite3_db_config()] interface will return a | 2046 ** the call worked. ^The [sqlite3_db_config()] interface will return a |
1992 ** non-zero [error code] if a discontinued or unsupported configuration option | 2047 ** non-zero [error code] if a discontinued or unsupported configuration option |
1993 ** is invoked. | 2048 ** is invoked. |
1994 ** | 2049 ** |
1995 ** <dl> | 2050 ** <dl> |
2051 ** [[SQLITE_DBCONFIG_LOOKASIDE]] | |
1996 ** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt> | 2052 ** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt> |
1997 ** <dd> ^This option takes three additional arguments that determine the | 2053 ** <dd> ^This option takes three additional arguments that determine the |
1998 ** [lookaside memory allocator] configuration for the [database connection]. | 2054 ** [lookaside memory allocator] configuration for the [database connection]. |
1999 ** ^The first argument (the third parameter to [sqlite3_db_config()] is a | 2055 ** ^The first argument (the third parameter to [sqlite3_db_config()] is a |
2000 ** pointer to a memory buffer to use for lookaside memory. | 2056 ** pointer to a memory buffer to use for lookaside memory. |
2013 ** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero. | 2069 ** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero. |
2014 ** Any attempt to change the lookaside memory configuration when lookaside | 2070 ** Any attempt to change the lookaside memory configuration when lookaside |
2015 ** memory is in use leaves the configuration unchanged and returns | 2071 ** memory is in use leaves the configuration unchanged and returns |
2016 ** [SQLITE_BUSY].)^</dd> | 2072 ** [SQLITE_BUSY].)^</dd> |
2017 ** | 2073 ** |
2074 ** [[SQLITE_DBCONFIG_ENABLE_FKEY]] | |
2018 ** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt> | 2075 ** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt> |
2019 ** <dd> ^This option is used to enable or disable the enforcement of | 2076 ** <dd> ^This option is used to enable or disable the enforcement of |
2020 ** [foreign key constraints]. There should be two additional arguments. | 2077 ** [foreign key constraints]. There should be two additional arguments. |
2021 ** The first argument is an integer which is 0 to disable FK enforcement, | 2078 ** The first argument is an integer which is 0 to disable FK enforcement, |
2022 ** positive to enable FK enforcement or negative to leave FK enforcement | 2079 ** positive to enable FK enforcement or negative to leave FK enforcement |
2023 ** unchanged. The second parameter is a pointer to an integer into which | 2080 ** unchanged. The second parameter is a pointer to an integer into which |
2024 ** is written 0 or 1 to indicate whether FK enforcement is off or on | 2081 ** is written 0 or 1 to indicate whether FK enforcement is off or on |
2025 ** following this call. The second parameter may be a NULL pointer, in | 2082 ** following this call. The second parameter may be a NULL pointer, in |
2026 ** which case the FK enforcement setting is not reported back. </dd> | 2083 ** which case the FK enforcement setting is not reported back. </dd> |
2027 ** | 2084 ** |
2085 ** [[SQLITE_DBCONFIG_ENABLE_TRIGGER]] | |
2028 ** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt> | 2086 ** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt> |
2029 ** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers]. | 2087 ** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers]. |
2030 ** There should be two additional arguments. | 2088 ** There should be two additional arguments. |
2031 ** The first argument is an integer which is 0 to disable triggers, | 2089 ** The first argument is an integer which is 0 to disable triggers, |
2032 ** positive to enable triggers or negative to leave the setting unchanged. | 2090 ** positive to enable triggers or negative to leave the setting unchanged. |
2033 ** The second parameter is a pointer to an integer into which | 2091 ** The second parameter is a pointer to an integer into which |
2034 ** is written 0 or 1 to indicate whether triggers are disabled or enabled | 2092 ** is written 0 or 1 to indicate whether triggers are disabled or enabled |
2035 ** following this call. The second parameter may be a NULL pointer, in | 2093 ** following this call. The second parameter may be a NULL pointer, in |
2036 ** which case the trigger setting is not reported back. </dd> | 2094 ** which case the trigger setting is not reported back. </dd> |
2037 ** | 2095 ** |
2096 ** [[SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER]] | |
2038 ** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt> | 2097 ** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt> |
2039 ** <dd> ^This option is used to enable or disable the two-argument | 2098 ** <dd> ^This option is used to enable or disable the |
2040 ** version of the [fts3_tokenizer()] function which is part of the | 2099 ** [fts3_tokenizer()] function which is part of the |
2041 ** [FTS3] full-text search engine extension. | 2100 ** [FTS3] full-text search engine extension. |
2042 ** There should be two additional arguments. | 2101 ** There should be two additional arguments. |
2043 ** The first argument is an integer which is 0 to disable fts3_tokenizer() or | 2102 ** The first argument is an integer which is 0 to disable fts3_tokenizer() or |
2044 ** positive to enable fts3_tokenizer() or negative to leave the setting | 2103 ** positive to enable fts3_tokenizer() or negative to leave the setting |
2045 ** unchanged. | 2104 ** unchanged. |
2046 ** The second parameter is a pointer to an integer into which | 2105 ** The second parameter is a pointer to an integer into which |
2047 ** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled | 2106 ** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled |
2048 ** following this call. The second parameter may be a NULL pointer, in | 2107 ** following this call. The second parameter may be a NULL pointer, in |
2049 ** which case the new setting is not reported back. </dd> | 2108 ** which case the new setting is not reported back. </dd> |
2050 ** | 2109 ** |
2110 ** [[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION]] | |
2051 ** <dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt> | 2111 ** <dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt> |
2052 ** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()] | 2112 ** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()] |
2053 ** interface independently of the [load_extension()] SQL function. | 2113 ** interface independently of the [load_extension()] SQL function. |
2054 ** The [sqlite3_enable_load_extension()] API enables or disables both the | 2114 ** The [sqlite3_enable_load_extension()] API enables or disables both the |
2055 ** C-API [sqlite3_load_extension()] and the SQL function [load_extension()]. | 2115 ** C-API [sqlite3_load_extension()] and the SQL function [load_extension()]. |
2063 ** is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface | 2123 ** is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface |
2064 ** is disabled or enabled following this call. The second parameter may | 2124 ** is disabled or enabled following this call. The second parameter may |
2065 ** be a NULL pointer, in which case the new setting is not reported back. | 2125 ** be a NULL pointer, in which case the new setting is not reported back. |
2066 ** </dd> | 2126 ** </dd> |
2067 ** | 2127 ** |
2068 ** <dt>SQLITE_DBCONFIG_MAINDBNAME</dt> | 2128 ** [[SQLITE_DBCONFIG_MAINDBNAME]] <dt>SQLITE_DBCONFIG_MAINDBNAME</dt> |
2069 ** <dd> ^This option is used to change the name of the "main" database | 2129 ** <dd> ^This option is used to change the name of the "main" database |
2070 ** schema. ^The sole argument is a pointer to a constant UTF8 string | 2130 ** schema. ^The sole argument is a pointer to a constant UTF8 string |
2071 ** which will become the new schema name in place of "main". ^SQLite | 2131 ** which will become the new schema name in place of "main". ^SQLite |
2072 ** does not make a copy of the new main schema name string, so the application | 2132 ** does not make a copy of the new main schema name string, so the application |
2073 ** must ensure that the argument passed into this DBCONFIG option is unchanged | 2133 ** must ensure that the argument passed into this DBCONFIG option is unchanged |
2074 ** until after the database connection closes. | 2134 ** until after the database connection closes. |
2075 ** </dd> | 2135 ** </dd> |
2076 ** | 2136 ** |
2137 ** [[SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE]] | |
2077 ** <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt> | 2138 ** <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt> |
2078 ** <dd> Usually, when a database in wal mode is closed or detached from a | 2139 ** <dd> Usually, when a database in wal mode is closed or detached from a |
2079 ** database handle, SQLite checks if this will mean that there are now no | 2140 ** database handle, SQLite checks if this will mean that there are now no |
2080 ** connections at all to the database. If so, it performs a checkpoint | 2141 ** connections at all to the database. If so, it performs a checkpoint |
2081 ** operation before closing the connection. This option may be used to | 2142 ** operation before closing the connection. This option may be used to |
2085 ** The second parameter is a pointer to an integer | 2146 ** The second parameter is a pointer to an integer |
2086 ** into which is written 0 or 1 to indicate whether checkpoints-on-close | 2147 ** into which is written 0 or 1 to indicate whether checkpoints-on-close |
2087 ** have been disabled - 0 if they are not disabled, 1 if they are. | 2148 ** have been disabled - 0 if they are not disabled, 1 if they are. |
2088 ** </dd> | 2149 ** </dd> |
2089 ** | 2150 ** |
2090 ** <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt> | 2151 ** [[SQLITE_DBCONFIG_ENABLE_QPSG]] <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt> |
2091 ** <dd>^(The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates | 2152 ** <dd>^(The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates |
2092 ** the [query planner stability guarantee] (QPSG). When the QPSG is active, | 2153 ** the [query planner stability guarantee] (QPSG). When the QPSG is active, |
2093 ** a single SQL query statement will always use the same algorithm regardless | 2154 ** a single SQL query statement will always use the same algorithm regardless |
2094 ** of values of [bound parameters].)^ The QPSG disables some query optimizations | 2155 ** of values of [bound parameters].)^ The QPSG disables some query optimizations |
2095 ** that look at the values of bound parameters, which can make some queries | 2156 ** that look at the values of bound parameters, which can make some queries |
2101 ** unchanged. The second parameter is a pointer to an integer into which | 2162 ** unchanged. The second parameter is a pointer to an integer into which |
2102 ** is written 0 or 1 to indicate whether the QPSG is disabled or enabled | 2163 ** is written 0 or 1 to indicate whether the QPSG is disabled or enabled |
2103 ** following this call. | 2164 ** following this call. |
2104 ** </dd> | 2165 ** </dd> |
2105 ** | 2166 ** |
2106 ** <dt>SQLITE_DBCONFIG_TRIGGER_EQP</dt> | 2167 ** [[SQLITE_DBCONFIG_TRIGGER_EQP]] <dt>SQLITE_DBCONFIG_TRIGGER_EQP</dt> |
2107 ** <dd> By default, the output of EXPLAIN QUERY PLAN commands does not | 2168 ** <dd> By default, the output of EXPLAIN QUERY PLAN commands does not |
2108 ** include output for any operations performed by trigger programs. This | 2169 ** include output for any operations performed by trigger programs. This |
2109 ** option is used to set or clear (the default) a flag that governs this | 2170 ** option is used to set or clear (the default) a flag that governs this |
2110 ** behavior. The first parameter passed to this operation is an integer - | 2171 ** behavior. The first parameter passed to this operation is an integer - |
2111 ** positive to enable output for trigger programs, or zero to disable it, | 2172 ** positive to enable output for trigger programs, or zero to disable it, |
2113 ** The second parameter is a pointer to an integer into which is written | 2174 ** The second parameter is a pointer to an integer into which is written |
2114 ** 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if | 2175 ** 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if |
2115 ** it is not disabled, 1 if it is. | 2176 ** it is not disabled, 1 if it is. |
2116 ** </dd> | 2177 ** </dd> |
2117 ** | 2178 ** |
2118 ** <dt>SQLITE_DBCONFIG_RESET_DATABASE</dt> | 2179 ** [[SQLITE_DBCONFIG_RESET_DATABASE]] <dt>SQLITE_DBCONFIG_RESET_DATABASE</dt> |
2119 ** <dd> Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run | 2180 ** <dd> Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run |
2120 ** [VACUUM] in order to reset a database back to an empty database | 2181 ** [VACUUM] in order to reset a database back to an empty database |
2121 ** with no schema and no content. The following process works even for | 2182 ** with no schema and no content. The following process works even for |
2122 ** a badly corrupted database file: | 2183 ** a badly corrupted database file: |
2123 ** <ol> | 2184 ** <ol> |
2185 ** <li> If the database connection is newly opened, make sure it has read the | |
2186 ** database schema by preparing then discarding some query against the | |
2187 ** database, or calling sqlite3_table_column_metadata(), ignoring any | |
2188 ** errors. This step is only necessary if the application desires to keep | |
2189 ** the database in WAL mode after the reset if it was in WAL mode before | |
2190 ** the reset. | |
2124 ** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0); | 2191 ** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0); |
2125 ** <li> [sqlite3_exec](db, "[VACUUM]", 0, 0, 0); | 2192 ** <li> [sqlite3_exec](db, "[VACUUM]", 0, 0, 0); |
2126 ** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0); | 2193 ** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0); |
2127 ** </ol> | 2194 ** </ol> |
2128 ** Because resetting a database is destructive and irreversible, the | 2195 ** Because resetting a database is destructive and irreversible, the |
2129 ** process requires the use of this obscure API and multiple steps to help | 2196 ** process requires the use of this obscure API and multiple steps to help |
2130 ** ensure that it does not happen by accident. | 2197 ** ensure that it does not happen by accident. |
2198 ** | |
2199 ** [[SQLITE_DBCONFIG_DEFENSIVE]] <dt>SQLITE_DBCONFIG_DEFENSIVE</dt> | |
2200 ** <dd>The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the | |
2201 ** "defensive" flag for a database connection. When the defensive | |
2202 ** flag is enabled, language features that allow ordinary SQL to | |
2203 ** deliberately corrupt the database file are disabled. The disabled | |
2204 ** features include but are not limited to the following: | |
2205 ** <ul> | |
2206 ** <li> The [PRAGMA writable_schema=ON] statement. | |
2207 ** <li> The [PRAGMA journal_mode=OFF] statement. | |
2208 ** <li> Writes to the [sqlite_dbpage] virtual table. | |
2209 ** <li> Direct writes to [shadow tables]. | |
2210 ** </ul> | |
2211 ** </dd> | |
2212 ** | |
2213 ** [[SQLITE_DBCONFIG_WRITABLE_SCHEMA]] <dt>SQLITE_DBCONFIG_WRITABLE_SCHEMA</dt> | |
2214 ** <dd>The SQLITE_DBCONFIG_WRITABLE_SCHEMA option activates or deactivates the | |
2215 ** "writable_schema" flag. This has the same effect and is logically equivalent | |
2216 ** to setting [PRAGMA writable_schema=ON] or [PRAGMA writable_schema=OFF]. | |
2217 ** The first argument to this setting is an integer which is 0 to disable | |
2218 ** the writable_schema, positive to enable writable_schema, or negative to | |
2219 ** leave the setting unchanged. The second parameter is a pointer to an | |
2220 ** integer into which is written 0 or 1 to indicate whether the writable_schema | |
2221 ** is enabled or disabled following this call. | |
2222 ** </dd> | |
2223 ** | |
2224 ** [[SQLITE_DBCONFIG_LEGACY_ALTER_TABLE]] | |
2225 ** <dt>SQLITE_DBCONFIG_LEGACY_ALTER_TABLE</dt> | |
2226 ** <dd>The SQLITE_DBCONFIG_LEGACY_ALTER_TABLE option activates or deactivates | |
2227 ** the legacy behavior of the [ALTER TABLE RENAME] command such it | |
2228 ** behaves as it did prior to [version 3.24.0] (2018-06-04). See the | |
2229 ** "Compatibility Notice" on the [ALTER TABLE RENAME documentation] for | |
2230 ** additional information. This feature can also be turned on and off | |
2231 ** using the [PRAGMA legacy_alter_table] statement. | |
2232 ** </dd> | |
2233 ** | |
2234 ** [[SQLITE_DBCONFIG_DQS_DML]] | |
2235 ** <dt>SQLITE_DBCONFIG_DQS_DML</td> | |
2236 ** <dd>The SQLITE_DBCONFIG_DQS_DML option activates or deactivates | |
2237 ** the legacy [double-quoted string literal] misfeature for DML statement | |
2238 ** only, that is DELETE, INSERT, SELECT, and UPDATE statements. The | |
2239 ** default value of this setting is determined by the [-DSQLITE_DQS] | |
2240 ** compile-time option. | |
2241 ** </dd> | |
2242 ** | |
2243 ** [[SQLITE_DBCONFIG_DQS_DDL]] | |
2244 ** <dt>SQLITE_DBCONFIG_DQS_DDL</td> | |
2245 ** <dd>The SQLITE_DBCONFIG_DQS option activates or deactivates | |
2246 ** the legacy [double-quoted string literal] misfeature for DDL statements, | |
2247 ** such as CREATE TABLE and CREATE INDEX. The | |
2248 ** default value of this setting is determined by the [-DSQLITE_DQS] | |
2249 ** compile-time option. | |
2131 ** </dd> | 2250 ** </dd> |
2132 ** </dl> | 2251 ** </dl> |
2133 */ | 2252 */ |
2134 #define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */ | 2253 #define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */ |
2135 #define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ | 2254 #define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ |
2139 #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */ | 2258 #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */ |
2140 #define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */ | 2259 #define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */ |
2141 #define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */ | 2260 #define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */ |
2142 #define SQLITE_DBCONFIG_TRIGGER_EQP 1008 /* int int* */ | 2261 #define SQLITE_DBCONFIG_TRIGGER_EQP 1008 /* int int* */ |
2143 #define SQLITE_DBCONFIG_RESET_DATABASE 1009 /* int int* */ | 2262 #define SQLITE_DBCONFIG_RESET_DATABASE 1009 /* int int* */ |
2144 #define SQLITE_DBCONFIG_MAX 1009 /* Largest DBCONFIG */ | 2263 #define SQLITE_DBCONFIG_DEFENSIVE 1010 /* int int* */ |
2264 #define SQLITE_DBCONFIG_WRITABLE_SCHEMA 1011 /* int int* */ | |
2265 #define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE 1012 /* int int* */ | |
2266 #define SQLITE_DBCONFIG_DQS_DML 1013 /* int int* */ | |
2267 #define SQLITE_DBCONFIG_DQS_DDL 1014 /* int int* */ | |
2268 #define SQLITE_DBCONFIG_MAX 1014 /* Largest DBCONFIG */ | |
2145 | 2269 |
2146 /* | 2270 /* |
2147 ** CAPI3REF: Enable Or Disable Extended Result Codes | 2271 ** CAPI3REF: Enable Or Disable Extended Result Codes |
2148 ** METHOD: sqlite3 | 2272 ** METHOD: sqlite3 |
2149 ** | 2273 ** |
2267 ** returns the value as set when the calling statement began executing. | 2391 ** returns the value as set when the calling statement began executing. |
2268 ** ^If it is used by the second or subsequent such statement within a trigger | 2392 ** ^If it is used by the second or subsequent such statement within a trigger |
2269 ** program, the value returned reflects the number of rows modified by the | 2393 ** program, the value returned reflects the number of rows modified by the |
2270 ** previous INSERT, UPDATE or DELETE statement within the same trigger. | 2394 ** previous INSERT, UPDATE or DELETE statement within the same trigger. |
2271 ** | 2395 ** |
2272 ** See also the [sqlite3_total_changes()] interface, the | |
2273 ** [count_changes pragma], and the [changes() SQL function]. | |
2274 ** | |
2275 ** If a separate thread makes changes on the same database connection | 2396 ** If a separate thread makes changes on the same database connection |
2276 ** while [sqlite3_changes()] is running then the value returned | 2397 ** while [sqlite3_changes()] is running then the value returned |
2277 ** is unpredictable and not meaningful. | 2398 ** is unpredictable and not meaningful. |
2399 ** | |
2400 ** See also: | |
2401 ** <ul> | |
2402 ** <li> the [sqlite3_total_changes()] interface | |
2403 ** <li> the [count_changes pragma] | |
2404 ** <li> the [changes() SQL function] | |
2405 ** <li> the [data_version pragma] | |
2406 ** </ul> | |
2278 */ | 2407 */ |
2279 SQLITE_API int sqlite3_changes(sqlite3*); | 2408 SQLITE_API int sqlite3_changes(sqlite3*); |
2280 | 2409 |
2281 /* | 2410 /* |
2282 ** CAPI3REF: Total Number Of Rows Modified | 2411 ** CAPI3REF: Total Number Of Rows Modified |
2290 ** | 2419 ** |
2291 ** ^Changes made as part of [foreign key actions] are included in the | 2420 ** ^Changes made as part of [foreign key actions] are included in the |
2292 ** count, but those made as part of REPLACE constraint resolution are | 2421 ** count, but those made as part of REPLACE constraint resolution are |
2293 ** not. ^Changes to a view that are intercepted by INSTEAD OF triggers | 2422 ** not. ^Changes to a view that are intercepted by INSTEAD OF triggers |
2294 ** are not counted. | 2423 ** are not counted. |
2424 ** | |
2425 ** The [sqlite3_total_changes(D)] interface only reports the number | |
2426 ** of rows that changed due to SQL statement run against database | |
2427 ** connection D. Any changes by other database connections are ignored. | |
2428 ** To detect changes against a database file from other database | |
2429 ** connections use the [PRAGMA data_version] command or the | |
2430 ** [SQLITE_FCNTL_DATA_VERSION] [file control]. | |
2295 ** | 2431 ** |
2296 ** See also the [sqlite3_changes()] interface, the | |
2297 ** [count_changes pragma], and the [total_changes() SQL function]. | |
2298 ** | |
2299 ** If a separate thread makes changes on the same database connection | 2432 ** If a separate thread makes changes on the same database connection |
2300 ** while [sqlite3_total_changes()] is running then the value | 2433 ** while [sqlite3_total_changes()] is running then the value |
2301 ** returned is unpredictable and not meaningful. | 2434 ** returned is unpredictable and not meaningful. |
2435 ** | |
2436 ** See also: | |
2437 ** <ul> | |
2438 ** <li> the [sqlite3_changes()] interface | |
2439 ** <li> the [count_changes pragma] | |
2440 ** <li> the [changes() SQL function] | |
2441 ** <li> the [data_version pragma] | |
2442 ** <li> the [SQLITE_FCNTL_DATA_VERSION] [file control] | |
2443 ** </ul> | |
2302 */ | 2444 */ |
2303 SQLITE_API int sqlite3_total_changes(sqlite3*); | 2445 SQLITE_API int sqlite3_total_changes(sqlite3*); |
2304 | 2446 |
2305 /* | 2447 /* |
2306 ** CAPI3REF: Interrupt A Long-Running Query | 2448 ** CAPI3REF: Interrupt A Long-Running Query |
2922 ** the original statement text and an estimate of wall-clock time | 3064 ** the original statement text and an estimate of wall-clock time |
2923 ** of how long that statement took to run. ^The profile callback | 3065 ** of how long that statement took to run. ^The profile callback |
2924 ** time is in units of nanoseconds, however the current implementation | 3066 ** time is in units of nanoseconds, however the current implementation |
2925 ** is only capable of millisecond resolution so the six least significant | 3067 ** is only capable of millisecond resolution so the six least significant |
2926 ** digits in the time are meaningless. Future versions of SQLite | 3068 ** digits in the time are meaningless. Future versions of SQLite |
2927 ** might provide greater resolution on the profiler callback. The | 3069 ** might provide greater resolution on the profiler callback. Invoking |
2928 ** sqlite3_profile() function is considered experimental and is | 3070 ** either [sqlite3_trace()] or [sqlite3_trace_v2()] will cancel the |
2929 ** subject to change in future versions of SQLite. | 3071 ** profile callback. |
2930 */ | 3072 */ |
2931 SQLITE_API SQLITE_DEPRECATED void *sqlite3_trace(sqlite3*, | 3073 SQLITE_API SQLITE_DEPRECATED void *sqlite3_trace(sqlite3*, |
2932 void(*xTrace)(void*,const char*), void*); | 3074 void(*xTrace)(void*,const char*), void*); |
2933 SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*, | 3075 SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*, |
2934 void(*xProfile)(void*,const char*,sqlite3_uint64), void*); | 3076 void(*xProfile)(void*,const char*,sqlite3_uint64), void*); |
3338 ** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and | 3480 ** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and |
3339 ** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and | 3481 ** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and |
3340 ** is not a database file pathname pointer that SQLite passed into the xOpen | 3482 ** is not a database file pathname pointer that SQLite passed into the xOpen |
3341 ** VFS method, then the behavior of this routine is undefined and probably | 3483 ** VFS method, then the behavior of this routine is undefined and probably |
3342 ** undesirable. | 3484 ** undesirable. |
3485 ** | |
3486 ** See the [URI filename] documentation for additional information. | |
3343 */ | 3487 */ |
3344 SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam); | 3488 SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam); |
3345 SQLITE_API int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault); | 3489 SQLITE_API int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault); |
3346 SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int64); | 3490 SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int64); |
3347 | 3491 |
3352 ** | 3496 ** |
3353 ** ^If the most recent sqlite3_* API call associated with | 3497 ** ^If the most recent sqlite3_* API call associated with |
3354 ** [database connection] D failed, then the sqlite3_errcode(D) interface | 3498 ** [database connection] D failed, then the sqlite3_errcode(D) interface |
3355 ** returns the numeric [result code] or [extended result code] for that | 3499 ** returns the numeric [result code] or [extended result code] for that |
3356 ** API call. | 3500 ** API call. |
3357 ** If the most recent API call was successful, | |
3358 ** then the return value from sqlite3_errcode() is undefined. | |
3359 ** ^The sqlite3_extended_errcode() | 3501 ** ^The sqlite3_extended_errcode() |
3360 ** interface is the same except that it always returns the | 3502 ** interface is the same except that it always returns the |
3361 ** [extended result code] even when extended result codes are | 3503 ** [extended result code] even when extended result codes are |
3362 ** disabled. | 3504 ** disabled. |
3505 ** | |
3506 ** The values returned by sqlite3_errcode() and/or | |
3507 ** sqlite3_extended_errcode() might change with each API call. | |
3508 ** Except, there are some interfaces that are guaranteed to never | |
3509 ** change the value of the error code. The error-code preserving | |
3510 ** interfaces are: | |
3511 ** | |
3512 ** <ul> | |
3513 ** <li> sqlite3_errcode() | |
3514 ** <li> sqlite3_extended_errcode() | |
3515 ** <li> sqlite3_errmsg() | |
3516 ** <li> sqlite3_errmsg16() | |
3517 ** </ul> | |
3363 ** | 3518 ** |
3364 ** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language | 3519 ** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language |
3365 ** text that describes the error, as either UTF-8 or UTF-16 respectively. | 3520 ** text that describes the error, as either UTF-8 or UTF-16 respectively. |
3366 ** ^(Memory to hold the error message string is managed internally. | 3521 ** ^(Memory to hold the error message string is managed internally. |
3367 ** The application does not need to worry about freeing the result. | 3522 ** The application does not need to worry about freeing the result. |
3548 ** be used just once or at most a few times and then destroyed using | 3703 ** be used just once or at most a few times and then destroyed using |
3549 ** [sqlite3_finalize()] relatively soon. The current implementation acts | 3704 ** [sqlite3_finalize()] relatively soon. The current implementation acts |
3550 ** on this hint by avoiding the use of [lookaside memory] so as not to | 3705 ** on this hint by avoiding the use of [lookaside memory] so as not to |
3551 ** deplete the limited store of lookaside memory. Future versions of | 3706 ** deplete the limited store of lookaside memory. Future versions of |
3552 ** SQLite may act on this hint differently. | 3707 ** SQLite may act on this hint differently. |
3708 ** | |
3709 ** [[SQLITE_PREPARE_NORMALIZE]] <dt>SQLITE_PREPARE_NORMALIZE</dt> | |
3710 ** <dd>The SQLITE_PREPARE_NORMALIZE flag is a no-op. This flag used | |
3711 ** to be required for any prepared statement that wanted to use the | |
3712 ** [sqlite3_normalized_sql()] interface. However, the | |
3713 ** [sqlite3_normalized_sql()] interface is now available to all | |
3714 ** prepared statements, regardless of whether or not they use this | |
3715 ** flag. | |
3716 ** | |
3717 ** [[SQLITE_PREPARE_NO_VTAB]] <dt>SQLITE_PREPARE_NO_VTAB</dt> | |
3718 ** <dd>The SQLITE_PREPARE_NO_VTAB flag causes the SQL compiler | |
3719 ** to return an error (error code SQLITE_ERROR) if the statement uses | |
3720 ** any virtual tables. | |
3553 ** </dl> | 3721 ** </dl> |
3554 */ | 3722 */ |
3555 #define SQLITE_PREPARE_PERSISTENT 0x01 | 3723 #define SQLITE_PREPARE_PERSISTENT 0x01 |
3724 #define SQLITE_PREPARE_NORMALIZE 0x02 | |
3725 #define SQLITE_PREPARE_NO_VTAB 0x04 | |
3556 | 3726 |
3557 /* | 3727 /* |
3558 ** CAPI3REF: Compiling An SQL Statement | 3728 ** CAPI3REF: Compiling An SQL Statement |
3559 ** KEYWORDS: {SQL statement compiler} | 3729 ** KEYWORDS: {SQL statement compiler} |
3560 ** METHOD: sqlite3 | 3730 ** METHOD: sqlite3 |
3708 ** created by [sqlite3_prepare_v2()], [sqlite3_prepare_v3()], | 3878 ** created by [sqlite3_prepare_v2()], [sqlite3_prepare_v3()], |
3709 ** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()]. | 3879 ** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()]. |
3710 ** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8 | 3880 ** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8 |
3711 ** string containing the SQL text of prepared statement P with | 3881 ** string containing the SQL text of prepared statement P with |
3712 ** [bound parameters] expanded. | 3882 ** [bound parameters] expanded. |
3883 ** ^The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-8 | |
3884 ** string containing the normalized SQL text of prepared statement P. The | |
3885 ** semantics used to normalize a SQL statement are unspecified and subject | |
3886 ** to change. At a minimum, literal values will be replaced with suitable | |
3887 ** placeholders. | |
3713 ** | 3888 ** |
3714 ** ^(For example, if a prepared statement is created using the SQL | 3889 ** ^(For example, if a prepared statement is created using the SQL |
3715 ** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345 | 3890 ** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345 |
3716 ** and parameter :xyz is unbound, then sqlite3_sql() will return | 3891 ** and parameter :xyz is unbound, then sqlite3_sql() will return |
3717 ** the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql() | 3892 ** the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql() |
3723 ** | 3898 ** |
3724 ** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of | 3899 ** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of |
3725 ** bound parameter expansions. ^The [SQLITE_OMIT_TRACE] compile-time | 3900 ** bound parameter expansions. ^The [SQLITE_OMIT_TRACE] compile-time |
3726 ** option causes sqlite3_expanded_sql() to always return NULL. | 3901 ** option causes sqlite3_expanded_sql() to always return NULL. |
3727 ** | 3902 ** |
3728 ** ^The string returned by sqlite3_sql(P) is managed by SQLite and is | 3903 ** ^The strings returned by sqlite3_sql(P) and sqlite3_normalized_sql(P) |
3729 ** automatically freed when the prepared statement is finalized. | 3904 ** are managed by SQLite and are automatically freed when the prepared |
3905 ** statement is finalized. | |
3730 ** ^The string returned by sqlite3_expanded_sql(P), on the other hand, | 3906 ** ^The string returned by sqlite3_expanded_sql(P), on the other hand, |
3731 ** is obtained from [sqlite3_malloc()] and must be free by the application | 3907 ** is obtained from [sqlite3_malloc()] and must be free by the application |
3732 ** by passing it to [sqlite3_free()]. | 3908 ** by passing it to [sqlite3_free()]. |
3733 */ | 3909 */ |
3734 SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt); | 3910 SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt); |
3735 SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt); | 3911 SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt); |
3912 SQLITE_API const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt); | |
3736 | 3913 |
3737 /* | 3914 /* |
3738 ** CAPI3REF: Determine If An SQL Statement Writes The Database | 3915 ** CAPI3REF: Determine If An SQL Statement Writes The Database |
3739 ** METHOD: sqlite3_stmt | 3916 ** METHOD: sqlite3_stmt |
3740 ** | 3917 ** |
3767 ** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and | 3944 ** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and |
3768 ** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so | 3945 ** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so |
3769 ** sqlite3_stmt_readonly() returns false for those commands. | 3946 ** sqlite3_stmt_readonly() returns false for those commands. |
3770 */ | 3947 */ |
3771 SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt); | 3948 SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt); |
3949 | |
3950 /* | |
3951 ** CAPI3REF: Query The EXPLAIN Setting For A Prepared Statement | |
3952 ** METHOD: sqlite3_stmt | |
3953 ** | |
3954 ** ^The sqlite3_stmt_isexplain(S) interface returns 1 if the | |
3955 ** prepared statement S is an EXPLAIN statement, or 2 if the | |
3956 ** statement S is an EXPLAIN QUERY PLAN. | |
3957 ** ^The sqlite3_stmt_isexplain(S) interface returns 0 if S is | |
3958 ** an ordinary statement or a NULL pointer. | |
3959 */ | |
3960 SQLITE_API int sqlite3_stmt_isexplain(sqlite3_stmt *pStmt); | |
3772 | 3961 |
3773 /* | 3962 /* |
3774 ** CAPI3REF: Determine If A Prepared Statement Has Been Reset | 3963 ** CAPI3REF: Determine If A Prepared Statement Has Been Reset |
3775 ** METHOD: sqlite3_stmt | 3964 ** METHOD: sqlite3_stmt |
3776 ** | 3965 ** |
3907 ** with embedded NULs is undefined. | 4096 ** with embedded NULs is undefined. |
3908 ** | 4097 ** |
3909 ** ^The fifth argument to the BLOB and string binding interfaces | 4098 ** ^The fifth argument to the BLOB and string binding interfaces |
3910 ** is a destructor used to dispose of the BLOB or | 4099 ** is a destructor used to dispose of the BLOB or |
3911 ** string after SQLite has finished with it. ^The destructor is called | 4100 ** string after SQLite has finished with it. ^The destructor is called |
3912 ** to dispose of the BLOB or string even if the call to bind API fails. | 4101 ** to dispose of the BLOB or string even if the call to the bind API fails, |
4102 ** except the destructor is not called if the third parameter is a NULL | |
4103 ** pointer or the fourth parameter is negative. | |
3913 ** ^If the fifth argument is | 4104 ** ^If the fifth argument is |
3914 ** the special value [SQLITE_STATIC], then SQLite assumes that the | 4105 ** the special value [SQLITE_STATIC], then SQLite assumes that the |
3915 ** information is in static, unmanaged space and does not need to be freed. | 4106 ** information is in static, unmanaged space and does not need to be freed. |
3916 ** ^If the fifth argument has the value [SQLITE_TRANSIENT], then | 4107 ** ^If the fifth argument has the value [SQLITE_TRANSIENT], then |
3917 ** SQLite makes its own private copy of the data immediately, before | 4108 ** SQLite makes its own private copy of the data immediately, before |
4512 ** [sqlite3_finalize()] is called. ^The memory space used to hold strings | 4703 ** [sqlite3_finalize()] is called. ^The memory space used to hold strings |
4513 ** and BLOBs is freed automatically. Do not pass the pointers returned | 4704 ** and BLOBs is freed automatically. Do not pass the pointers returned |
4514 ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into | 4705 ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into |
4515 ** [sqlite3_free()]. | 4706 ** [sqlite3_free()]. |
4516 ** | 4707 ** |
4517 ** ^(If a memory allocation error occurs during the evaluation of any | 4708 ** As long as the input parameters are correct, these routines will only |
4518 ** of these routines, a default value is returned. The default value | 4709 ** fail if an out-of-memory error occurs during a format conversion. |
4519 ** is either the integer 0, the floating point number 0.0, or a NULL | 4710 ** Only the following subset of interfaces are subject to out-of-memory |
4520 ** pointer. Subsequent calls to [sqlite3_errcode()] will return | 4711 ** errors: |
4521 ** [SQLITE_NOMEM].)^ | 4712 ** |
4713 ** <ul> | |
4714 ** <li> sqlite3_column_blob() | |
4715 ** <li> sqlite3_column_text() | |
4716 ** <li> sqlite3_column_text16() | |
4717 ** <li> sqlite3_column_bytes() | |
4718 ** <li> sqlite3_column_bytes16() | |
4719 ** </ul> | |
4720 ** | |
4721 ** If an out-of-memory error occurs, then the return value from these | |
4722 ** routines is the same as if the column had contained an SQL NULL value. | |
4723 ** Valid SQL NULL returns can be distinguished from out-of-memory errors | |
4724 ** by invoking the [sqlite3_errcode()] immediately after the suspect | |
4725 ** return value is obtained and before any | |
4726 ** other SQLite interface is called on the same [database connection]. | |
4522 */ | 4727 */ |
4523 SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); | 4728 SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); |
4524 SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol); | 4729 SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol); |
4525 SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol); | 4730 SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol); |
4526 SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); | 4731 SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); |
4593 ** KEYWORDS: {application-defined SQL functions} | 4798 ** KEYWORDS: {application-defined SQL functions} |
4594 ** METHOD: sqlite3 | 4799 ** METHOD: sqlite3 |
4595 ** | 4800 ** |
4596 ** ^These functions (collectively known as "function creation routines") | 4801 ** ^These functions (collectively known as "function creation routines") |
4597 ** are used to add SQL functions or aggregates or to redefine the behavior | 4802 ** are used to add SQL functions or aggregates or to redefine the behavior |
4598 ** of existing SQL functions or aggregates. The only differences between | 4803 ** of existing SQL functions or aggregates. The only differences between |
4599 ** these routines are the text encoding expected for | 4804 ** the three "sqlite3_create_function*" routines are the text encoding |
4600 ** the second parameter (the name of the function being created) | 4805 ** expected for the second parameter (the name of the function being |
4601 ** and the presence or absence of a destructor callback for | 4806 ** created) and the presence or absence of a destructor callback for |
4602 ** the application data pointer. | 4807 ** the application data pointer. Function sqlite3_create_window_function() |
4808 ** is similar, but allows the user to supply the extra callback functions | |
4809 ** needed by [aggregate window functions]. | |
4603 ** | 4810 ** |
4604 ** ^The first parameter is the [database connection] to which the SQL | 4811 ** ^The first parameter is the [database connection] to which the SQL |
4605 ** function is to be added. ^If an application uses more than one database | 4812 ** function is to be added. ^If an application uses more than one database |
4606 ** connection then application-defined SQL functions must be added | 4813 ** connection then application-defined SQL functions must be added |
4607 ** to each database connection separately. | 4814 ** to each database connection separately. |
4643 ** of the [SQLITE_DETERMINISTIC] flag is recommended where possible. | 4850 ** of the [SQLITE_DETERMINISTIC] flag is recommended where possible. |
4644 ** | 4851 ** |
4645 ** ^(The fifth parameter is an arbitrary pointer. The implementation of the | 4852 ** ^(The fifth parameter is an arbitrary pointer. The implementation of the |
4646 ** function can gain access to this pointer using [sqlite3_user_data()].)^ | 4853 ** function can gain access to this pointer using [sqlite3_user_data()].)^ |
4647 ** | 4854 ** |
4648 ** ^The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are | 4855 ** ^The sixth, seventh and eighth parameters passed to the three |
4856 ** "sqlite3_create_function*" functions, xFunc, xStep and xFinal, are | |
4649 ** pointers to C-language functions that implement the SQL function or | 4857 ** pointers to C-language functions that implement the SQL function or |
4650 ** aggregate. ^A scalar SQL function requires an implementation of the xFunc | 4858 ** aggregate. ^A scalar SQL function requires an implementation of the xFunc |
4651 ** callback only; NULL pointers must be passed as the xStep and xFinal | 4859 ** callback only; NULL pointers must be passed as the xStep and xFinal |
4652 ** parameters. ^An aggregate SQL function requires an implementation of xStep | 4860 ** parameters. ^An aggregate SQL function requires an implementation of xStep |
4653 ** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing | 4861 ** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing |
4654 ** SQL function or aggregate, pass NULL pointers for all three function | 4862 ** SQL function or aggregate, pass NULL pointers for all three function |
4655 ** callbacks. | 4863 ** callbacks. |
4656 ** | 4864 ** |
4657 ** ^(If the ninth parameter to sqlite3_create_function_v2() is not NULL, | 4865 ** ^The sixth, seventh, eighth and ninth parameters (xStep, xFinal, xValue |
4658 ** then it is destructor for the application data pointer. | 4866 ** and xInverse) passed to sqlite3_create_window_function are pointers to |
4659 ** The destructor is invoked when the function is deleted, either by being | 4867 ** C-language callbacks that implement the new function. xStep and xFinal |
4660 ** overloaded or when the database connection closes.)^ | 4868 ** must both be non-NULL. xValue and xInverse may either both be NULL, in |
4661 ** ^The destructor is also invoked if the call to | 4869 ** which case a regular aggregate function is created, or must both be |
4662 ** sqlite3_create_function_v2() fails. | 4870 ** non-NULL, in which case the new function may be used as either an aggregate |
4663 ** ^When the destructor callback of the tenth parameter is invoked, it | 4871 ** or aggregate window function. More details regarding the implementation |
4664 ** is passed a single argument which is a copy of the application data | 4872 ** of aggregate window functions are |
4665 ** pointer which was the fifth parameter to sqlite3_create_function_v2(). | 4873 ** [user-defined window functions|available here]. |
4874 ** | |
4875 ** ^(If the final parameter to sqlite3_create_function_v2() or | |
4876 ** sqlite3_create_window_function() is not NULL, then it is destructor for | |
4877 ** the application data pointer. The destructor is invoked when the function | |
4878 ** is deleted, either by being overloaded or when the database connection | |
4879 ** closes.)^ ^The destructor is also invoked if the call to | |
4880 ** sqlite3_create_function_v2() fails. ^When the destructor callback is | |
4881 ** invoked, it is passed a single argument which is a copy of the application | |
4882 ** data pointer which was the fifth parameter to sqlite3_create_function_v2(). | |
4666 ** | 4883 ** |
4667 ** ^It is permitted to register multiple implementations of the same | 4884 ** ^It is permitted to register multiple implementations of the same |
4668 ** functions with the same name but with either differing numbers of | 4885 ** functions with the same name but with either differing numbers of |
4669 ** arguments or differing preferred text encodings. ^SQLite will use | 4886 ** arguments or differing preferred text encodings. ^SQLite will use |
4670 ** the implementation that most closely matches the way in which the | 4887 ** the implementation that most closely matches the way in which the |
4713 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), | 4930 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), |
4714 void (*xStep)(sqlite3_context*,int,sqlite3_value**), | 4931 void (*xStep)(sqlite3_context*,int,sqlite3_value**), |
4715 void (*xFinal)(sqlite3_context*), | 4932 void (*xFinal)(sqlite3_context*), |
4716 void(*xDestroy)(void*) | 4933 void(*xDestroy)(void*) |
4717 ); | 4934 ); |
4935 SQLITE_API int sqlite3_create_window_function( | |
4936 sqlite3 *db, | |
4937 const char *zFunctionName, | |
4938 int nArg, | |
4939 int eTextRep, | |
4940 void *pApp, | |
4941 void (*xStep)(sqlite3_context*,int,sqlite3_value**), | |
4942 void (*xFinal)(sqlite3_context*), | |
4943 void (*xValue)(sqlite3_context*), | |
4944 void (*xInverse)(sqlite3_context*,int,sqlite3_value**), | |
4945 void(*xDestroy)(void*) | |
4946 ); | |
4718 | 4947 |
4719 /* | 4948 /* |
4720 ** CAPI3REF: Text Encodings | 4949 ** CAPI3REF: Text Encodings |
4721 ** | 4950 ** |
4722 ** These constant define integer codes that represent the various | 4951 ** These constant define integer codes that represent the various |
4786 ** <tr><td><b>sqlite3_value_numeric_type </b> | 5015 ** <tr><td><b>sqlite3_value_numeric_type </b> |
4787 ** <td>→ <td>Best numeric datatype of the value | 5016 ** <td>→ <td>Best numeric datatype of the value |
4788 ** <tr><td><b>sqlite3_value_nochange </b> | 5017 ** <tr><td><b>sqlite3_value_nochange </b> |
4789 ** <td>→ <td>True if the column is unchanged in an UPDATE | 5018 ** <td>→ <td>True if the column is unchanged in an UPDATE |
4790 ** against a virtual table. | 5019 ** against a virtual table. |
5020 ** <tr><td><b>sqlite3_value_frombind </b> | |
5021 ** <td>→ <td>True if value originated from a [bound parameter] | |
4791 ** </table></blockquote> | 5022 ** </table></blockquote> |
4792 ** | 5023 ** |
4793 ** <b>Details:</b> | 5024 ** <b>Details:</b> |
4794 ** | 5025 ** |
4795 ** These routines extract type, size, and content information from | 5026 ** These routines extract type, size, and content information from |
4847 ** sqlite3_value_nochange(X) is true will in all other respects appear | 5078 ** sqlite3_value_nochange(X) is true will in all other respects appear |
4848 ** to be a NULL value. If sqlite3_value_nochange(X) is invoked anywhere other | 5079 ** to be a NULL value. If sqlite3_value_nochange(X) is invoked anywhere other |
4849 ** than within an [xUpdate] method call for an UPDATE statement, then | 5080 ** than within an [xUpdate] method call for an UPDATE statement, then |
4850 ** the return value is arbitrary and meaningless. | 5081 ** the return value is arbitrary and meaningless. |
4851 ** | 5082 ** |
5083 ** ^The sqlite3_value_frombind(X) interface returns non-zero if the | |
5084 ** value X originated from one of the [sqlite3_bind_int|sqlite3_bind()] | |
5085 ** interfaces. ^If X comes from an SQL literal value, or a table column, | |
5086 ** and expression, then sqlite3_value_frombind(X) returns zero. | |
5087 ** | |
4852 ** Please pay particular attention to the fact that the pointer returned | 5088 ** Please pay particular attention to the fact that the pointer returned |
4853 ** from [sqlite3_value_blob()], [sqlite3_value_text()], or | 5089 ** from [sqlite3_value_blob()], [sqlite3_value_text()], or |
4854 ** [sqlite3_value_text16()] can be invalidated by a subsequent call to | 5090 ** [sqlite3_value_text16()] can be invalidated by a subsequent call to |
4855 ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()], | 5091 ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()], |
4856 ** or [sqlite3_value_text16()]. | 5092 ** or [sqlite3_value_text16()]. |
4857 ** | 5093 ** |
4858 ** These routines must be called from the same thread as | 5094 ** These routines must be called from the same thread as |
4859 ** the SQL function that supplied the [sqlite3_value*] parameters. | 5095 ** the SQL function that supplied the [sqlite3_value*] parameters. |
5096 ** | |
5097 ** As long as the input parameter is correct, these routines can only | |
5098 ** fail if an out-of-memory error occurs during a format conversion. | |
5099 ** Only the following subset of interfaces are subject to out-of-memory | |
5100 ** errors: | |
5101 ** | |
5102 ** <ul> | |
5103 ** <li> sqlite3_value_blob() | |
5104 ** <li> sqlite3_value_text() | |
5105 ** <li> sqlite3_value_text16() | |
5106 ** <li> sqlite3_value_text16le() | |
5107 ** <li> sqlite3_value_text16be() | |
5108 ** <li> sqlite3_value_bytes() | |
5109 ** <li> sqlite3_value_bytes16() | |
5110 ** </ul> | |
5111 ** | |
5112 ** If an out-of-memory error occurs, then the return value from these | |
5113 ** routines is the same as if the column had contained an SQL NULL value. | |
5114 ** Valid SQL NULL returns can be distinguished from out-of-memory errors | |
5115 ** by invoking the [sqlite3_errcode()] immediately after the suspect | |
5116 ** return value is obtained and before any | |
5117 ** other SQLite interface is called on the same [database connection]. | |
4860 */ | 5118 */ |
4861 SQLITE_API const void *sqlite3_value_blob(sqlite3_value*); | 5119 SQLITE_API const void *sqlite3_value_blob(sqlite3_value*); |
4862 SQLITE_API double sqlite3_value_double(sqlite3_value*); | 5120 SQLITE_API double sqlite3_value_double(sqlite3_value*); |
4863 SQLITE_API int sqlite3_value_int(sqlite3_value*); | 5121 SQLITE_API int sqlite3_value_int(sqlite3_value*); |
4864 SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*); | 5122 SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*); |
4870 SQLITE_API int sqlite3_value_bytes(sqlite3_value*); | 5128 SQLITE_API int sqlite3_value_bytes(sqlite3_value*); |
4871 SQLITE_API int sqlite3_value_bytes16(sqlite3_value*); | 5129 SQLITE_API int sqlite3_value_bytes16(sqlite3_value*); |
4872 SQLITE_API int sqlite3_value_type(sqlite3_value*); | 5130 SQLITE_API int sqlite3_value_type(sqlite3_value*); |
4873 SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*); | 5131 SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*); |
4874 SQLITE_API int sqlite3_value_nochange(sqlite3_value*); | 5132 SQLITE_API int sqlite3_value_nochange(sqlite3_value*); |
5133 SQLITE_API int sqlite3_value_frombind(sqlite3_value*); | |
4875 | 5134 |
4876 /* | 5135 /* |
4877 ** CAPI3REF: Finding The Subtype Of SQL Values | 5136 ** CAPI3REF: Finding The Subtype Of SQL Values |
4878 ** METHOD: sqlite3_value | 5137 ** METHOD: sqlite3_value |
4879 ** | 5138 ** |
5605 ** | 5864 ** |
5606 ** ^The sqlite3_db_filename(D,N) interface returns a pointer to a filename | 5865 ** ^The sqlite3_db_filename(D,N) interface returns a pointer to a filename |
5607 ** associated with database N of connection D. ^The main database file | 5866 ** associated with database N of connection D. ^The main database file |
5608 ** has the name "main". If there is no attached database N on the database | 5867 ** has the name "main". If there is no attached database N on the database |
5609 ** connection D, or if database N is a temporary or in-memory database, then | 5868 ** connection D, or if database N is a temporary or in-memory database, then |
5610 ** a NULL pointer is returned. | 5869 ** this function will return either a NULL pointer or an empty string. |
5611 ** | 5870 ** |
5612 ** ^The filename returned by this function is the output of the | 5871 ** ^The filename returned by this function is the output of the |
5613 ** xFullPathname method of the [VFS]. ^In other words, the filename | 5872 ** xFullPathname method of the [VFS]. ^In other words, the filename |
5614 ** will be an absolute pathname, even if the filename used | 5873 ** will be an absolute pathname, even if the filename used |
5615 ** to open the database originally was a URI or relative pathname. | 5874 ** to open the database originally was a URI or relative pathname. |
6160 /* The methods above are in version 1 of the sqlite_module object. Those | 6419 /* The methods above are in version 1 of the sqlite_module object. Those |
6161 ** below are for version 2 and greater. */ | 6420 ** below are for version 2 and greater. */ |
6162 int (*xSavepoint)(sqlite3_vtab *pVTab, int); | 6421 int (*xSavepoint)(sqlite3_vtab *pVTab, int); |
6163 int (*xRelease)(sqlite3_vtab *pVTab, int); | 6422 int (*xRelease)(sqlite3_vtab *pVTab, int); |
6164 int (*xRollbackTo)(sqlite3_vtab *pVTab, int); | 6423 int (*xRollbackTo)(sqlite3_vtab *pVTab, int); |
6424 /* The methods above are in versions 1 and 2 of the sqlite_module object. | |
6425 ** Those below are for version 3 and greater. */ | |
6426 int (*xShadowName)(const char*); | |
6165 }; | 6427 }; |
6166 | 6428 |
6167 /* | 6429 /* |
6168 ** CAPI3REF: Virtual Table Indexing Information | 6430 ** CAPI3REF: Virtual Table Indexing Information |
6169 ** KEYWORDS: sqlite3_index_info | 6431 ** KEYWORDS: sqlite3_index_info |
6321 #define SQLITE_INDEX_CONSTRAINT_NE 68 | 6583 #define SQLITE_INDEX_CONSTRAINT_NE 68 |
6322 #define SQLITE_INDEX_CONSTRAINT_ISNOT 69 | 6584 #define SQLITE_INDEX_CONSTRAINT_ISNOT 69 |
6323 #define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70 | 6585 #define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70 |
6324 #define SQLITE_INDEX_CONSTRAINT_ISNULL 71 | 6586 #define SQLITE_INDEX_CONSTRAINT_ISNULL 71 |
6325 #define SQLITE_INDEX_CONSTRAINT_IS 72 | 6587 #define SQLITE_INDEX_CONSTRAINT_IS 72 |
6588 #define SQLITE_INDEX_CONSTRAINT_FUNCTION 150 | |
6326 | 6589 |
6327 /* | 6590 /* |
6328 ** CAPI3REF: Register A Virtual Table Implementation | 6591 ** CAPI3REF: Register A Virtual Table Implementation |
6329 ** METHOD: sqlite3 | 6592 ** METHOD: sqlite3 |
6330 ** | 6593 ** |
6997 SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*); | 7260 SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*); |
6998 | 7261 |
6999 /* | 7262 /* |
7000 ** CAPI3REF: Low-Level Control Of Database Files | 7263 ** CAPI3REF: Low-Level Control Of Database Files |
7001 ** METHOD: sqlite3 | 7264 ** METHOD: sqlite3 |
7265 ** KEYWORDS: {file control} | |
7002 ** | 7266 ** |
7003 ** ^The [sqlite3_file_control()] interface makes a direct call to the | 7267 ** ^The [sqlite3_file_control()] interface makes a direct call to the |
7004 ** xFileControl method for the [sqlite3_io_methods] object associated | 7268 ** xFileControl method for the [sqlite3_io_methods] object associated |
7005 ** with a particular database identified by the second argument. ^The | 7269 ** with a particular database identified by the second argument. ^The |
7006 ** name of the database is "main" for the main database or "temp" for the | 7270 ** name of the database is "main" for the main database or "temp" for the |
7011 ** ^The third and fourth parameters to this routine | 7275 ** ^The third and fourth parameters to this routine |
7012 ** are passed directly through to the second and third parameters of | 7276 ** are passed directly through to the second and third parameters of |
7013 ** the xFileControl method. ^The return value of the xFileControl | 7277 ** the xFileControl method. ^The return value of the xFileControl |
7014 ** method becomes the return value of this routine. | 7278 ** method becomes the return value of this routine. |
7015 ** | 7279 ** |
7280 ** A few opcodes for [sqlite3_file_control()] are handled directly | |
7281 ** by the SQLite core and never invoke the | |
7282 ** sqlite3_io_methods.xFileControl method. | |
7016 ** ^The [SQLITE_FCNTL_FILE_POINTER] value for the op parameter causes | 7283 ** ^The [SQLITE_FCNTL_FILE_POINTER] value for the op parameter causes |
7017 ** a pointer to the underlying [sqlite3_file] object to be written into | 7284 ** a pointer to the underlying [sqlite3_file] object to be written into |
7018 ** the space pointed to by the 4th parameter. ^The [SQLITE_FCNTL_FILE_POINTER] | 7285 ** the space pointed to by the 4th parameter. The |
7019 ** case is a short-circuit path which does not actually invoke the | 7286 ** [SQLITE_FCNTL_JOURNAL_POINTER] works similarly except that it returns |
7020 ** underlying sqlite3_io_methods.xFileControl method. | 7287 ** the [sqlite3_file] object associated with the journal file instead of |
7288 ** the main database. The [SQLITE_FCNTL_VFS_POINTER] opcode returns | |
7289 ** a pointer to the underlying [sqlite3_vfs] object for the file. | |
7290 ** The [SQLITE_FCNTL_DATA_VERSION] returns the data version counter | |
7291 ** from the pager. | |
7021 ** | 7292 ** |
7022 ** ^If the second parameter (zDbName) does not match the name of any | 7293 ** ^If the second parameter (zDbName) does not match the name of any |
7023 ** open database file, then SQLITE_ERROR is returned. ^This error | 7294 ** open database file, then SQLITE_ERROR is returned. ^This error |
7024 ** code is not remembered and will not be recalled by [sqlite3_errcode()] | 7295 ** code is not remembered and will not be recalled by [sqlite3_errcode()] |
7025 ** or [sqlite3_errmsg()]. The underlying xFileControl method might | 7296 ** or [sqlite3_errmsg()]. The underlying xFileControl method might |
7073 #define SQLITE_TESTCTRL_ALWAYS 13 | 7344 #define SQLITE_TESTCTRL_ALWAYS 13 |
7074 #define SQLITE_TESTCTRL_RESERVE 14 | 7345 #define SQLITE_TESTCTRL_RESERVE 14 |
7075 #define SQLITE_TESTCTRL_OPTIMIZATIONS 15 | 7346 #define SQLITE_TESTCTRL_OPTIMIZATIONS 15 |
7076 #define SQLITE_TESTCTRL_ISKEYWORD 16 /* NOT USED */ | 7347 #define SQLITE_TESTCTRL_ISKEYWORD 16 /* NOT USED */ |
7077 #define SQLITE_TESTCTRL_SCRATCHMALLOC 17 /* NOT USED */ | 7348 #define SQLITE_TESTCTRL_SCRATCHMALLOC 17 /* NOT USED */ |
7349 #define SQLITE_TESTCTRL_INTERNAL_FUNCTIONS 17 | |
7078 #define SQLITE_TESTCTRL_LOCALTIME_FAULT 18 | 7350 #define SQLITE_TESTCTRL_LOCALTIME_FAULT 18 |
7079 #define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */ | 7351 #define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */ |
7080 #define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD 19 | 7352 #define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD 19 |
7081 #define SQLITE_TESTCTRL_NEVER_CORRUPT 20 | 7353 #define SQLITE_TESTCTRL_NEVER_CORRUPT 20 |
7082 #define SQLITE_TESTCTRL_VDBE_COVERAGE 21 | 7354 #define SQLITE_TESTCTRL_VDBE_COVERAGE 21 |
7083 #define SQLITE_TESTCTRL_BYTEORDER 22 | 7355 #define SQLITE_TESTCTRL_BYTEORDER 22 |
7084 #define SQLITE_TESTCTRL_ISINIT 23 | 7356 #define SQLITE_TESTCTRL_ISINIT 23 |
7085 #define SQLITE_TESTCTRL_SORTER_MMAP 24 | 7357 #define SQLITE_TESTCTRL_SORTER_MMAP 24 |
7086 #define SQLITE_TESTCTRL_IMPOSTER 25 | 7358 #define SQLITE_TESTCTRL_IMPOSTER 25 |
7087 #define SQLITE_TESTCTRL_PARSER_COVERAGE 26 | 7359 #define SQLITE_TESTCTRL_PARSER_COVERAGE 26 |
7088 #define SQLITE_TESTCTRL_LAST 26 /* Largest TESTCTRL */ | 7360 #define SQLITE_TESTCTRL_RESULT_INTREAL 27 |
7361 #define SQLITE_TESTCTRL_LAST 27 /* Largest TESTCTRL */ | |
7089 | 7362 |
7090 /* | 7363 /* |
7091 ** CAPI3REF: SQL Keyword Checking | 7364 ** CAPI3REF: SQL Keyword Checking |
7092 ** | 7365 ** |
7093 ** These routines provide access to the set of SQL language keywords | 7366 ** These routines provide access to the set of SQL language keywords |
8485 ** These macros define the various options to the | 8758 ** These macros define the various options to the |
8486 ** [sqlite3_vtab_config()] interface that [virtual table] implementations | 8759 ** [sqlite3_vtab_config()] interface that [virtual table] implementations |
8487 ** can use to customize and optimize their behavior. | 8760 ** can use to customize and optimize their behavior. |
8488 ** | 8761 ** |
8489 ** <dl> | 8762 ** <dl> |
8763 ** [[SQLITE_VTAB_CONSTRAINT_SUPPORT]] | |
8490 ** <dt>SQLITE_VTAB_CONSTRAINT_SUPPORT | 8764 ** <dt>SQLITE_VTAB_CONSTRAINT_SUPPORT |
8491 ** <dd>Calls of the form | 8765 ** <dd>Calls of the form |
8492 ** [sqlite3_vtab_config](db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) are supported, | 8766 ** [sqlite3_vtab_config](db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) are supported, |
8493 ** where X is an integer. If X is zero, then the [virtual table] whose | 8767 ** where X is an integer. If X is zero, then the [virtual table] whose |
8494 ** [xCreate] or [xConnect] method invoked [sqlite3_vtab_config()] does not | 8768 ** [xCreate] or [xConnect] method invoked [sqlite3_vtab_config()] does not |
8834 SQLITE_API int sqlite3_system_errno(sqlite3*); | 9108 SQLITE_API int sqlite3_system_errno(sqlite3*); |
8835 | 9109 |
8836 /* | 9110 /* |
8837 ** CAPI3REF: Database Snapshot | 9111 ** CAPI3REF: Database Snapshot |
8838 ** KEYWORDS: {snapshot} {sqlite3_snapshot} | 9112 ** KEYWORDS: {snapshot} {sqlite3_snapshot} |
8839 ** EXPERIMENTAL | |
8840 ** | 9113 ** |
8841 ** An instance of the snapshot object records the state of a [WAL mode] | 9114 ** An instance of the snapshot object records the state of a [WAL mode] |
8842 ** database for some specific point in history. | 9115 ** database for some specific point in history. |
8843 ** | 9116 ** |
8844 ** In [WAL mode], multiple [database connections] that are open on the | 9117 ** In [WAL mode], multiple [database connections] that are open on the |
8851 ** | 9124 ** |
8852 ** The sqlite3_snapshot object records state information about an historical | 9125 ** The sqlite3_snapshot object records state information about an historical |
8853 ** version of the database file so that it is possible to later open a new read | 9126 ** version of the database file so that it is possible to later open a new read |
8854 ** transaction that sees that historical version of the database rather than | 9127 ** transaction that sees that historical version of the database rather than |
8855 ** the most recent version. | 9128 ** the most recent version. |
8856 ** | |
8857 ** The constructor for this object is [sqlite3_snapshot_get()]. The | |
8858 ** [sqlite3_snapshot_open()] method causes a fresh read transaction to refer | |
8859 ** to an historical snapshot (if possible). The destructor for | |
8860 ** sqlite3_snapshot objects is [sqlite3_snapshot_free()]. | |
8861 */ | 9129 */ |
8862 typedef struct sqlite3_snapshot { | 9130 typedef struct sqlite3_snapshot { |
8863 unsigned char hidden[48]; | 9131 unsigned char hidden[48]; |
8864 } sqlite3_snapshot; | 9132 } sqlite3_snapshot; |
8865 | 9133 |
8866 /* | 9134 /* |
8867 ** CAPI3REF: Record A Database Snapshot | 9135 ** CAPI3REF: Record A Database Snapshot |
8868 ** EXPERIMENTAL | 9136 ** CONSTRUCTOR: sqlite3_snapshot |
8869 ** | 9137 ** |
8870 ** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a | 9138 ** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a |
8871 ** new [sqlite3_snapshot] object that records the current state of | 9139 ** new [sqlite3_snapshot] object that records the current state of |
8872 ** schema S in database connection D. ^On success, the | 9140 ** schema S in database connection D. ^On success, the |
8873 ** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly | 9141 ** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly |
8879 ** the following statements are false when sqlite3_snapshot_get() is | 9147 ** the following statements are false when sqlite3_snapshot_get() is |
8880 ** called, SQLITE_ERROR is returned. The final value of *P is undefined | 9148 ** called, SQLITE_ERROR is returned. The final value of *P is undefined |
8881 ** in this case. | 9149 ** in this case. |
8882 ** | 9150 ** |
8883 ** <ul> | 9151 ** <ul> |
8884 ** <li> The database handle must be in [autocommit mode]. | 9152 ** <li> The database handle must not be in [autocommit mode]. |
8885 ** | 9153 ** |
8886 ** <li> Schema S of [database connection] D must be a [WAL mode] database. | 9154 ** <li> Schema S of [database connection] D must be a [WAL mode] database. |
8887 ** | 9155 ** |
8888 ** <li> There must not be a write transaction open on schema S of database | 9156 ** <li> There must not be a write transaction open on schema S of database |
8889 ** connection D. | 9157 ** connection D. |
8902 ** The [sqlite3_snapshot] object returned from a successful call to | 9170 ** The [sqlite3_snapshot] object returned from a successful call to |
8903 ** [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()] | 9171 ** [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()] |
8904 ** to avoid a memory leak. | 9172 ** to avoid a memory leak. |
8905 ** | 9173 ** |
8906 ** The [sqlite3_snapshot_get()] interface is only available when the | 9174 ** The [sqlite3_snapshot_get()] interface is only available when the |
8907 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used. | 9175 ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used. |
8908 */ | 9176 */ |
8909 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_get( | 9177 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_get( |
8910 sqlite3 *db, | 9178 sqlite3 *db, |
8911 const char *zSchema, | 9179 const char *zSchema, |
8912 sqlite3_snapshot **ppSnapshot | 9180 sqlite3_snapshot **ppSnapshot |
8913 ); | 9181 ); |
8914 | 9182 |
8915 /* | 9183 /* |
8916 ** CAPI3REF: Start a read transaction on an historical snapshot | 9184 ** CAPI3REF: Start a read transaction on an historical snapshot |
8917 ** EXPERIMENTAL | 9185 ** METHOD: sqlite3_snapshot |
8918 ** | 9186 ** |
8919 ** ^The [sqlite3_snapshot_open(D,S,P)] interface starts a | 9187 ** ^The [sqlite3_snapshot_open(D,S,P)] interface either starts a new read |
8920 ** read transaction for schema S of | 9188 ** transaction or upgrades an existing one for schema S of |
8921 ** [database connection] D such that the read transaction | 9189 ** [database connection] D such that the read transaction refers to |
8922 ** refers to historical [snapshot] P, rather than the most | 9190 ** historical [snapshot] P, rather than the most recent change to the |
8923 ** recent change to the database. | 9191 ** database. ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK |
8924 ** ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK on success | 9192 ** on success or an appropriate [error code] if it fails. |
8925 ** or an appropriate [error code] if it fails. | 9193 ** |
8926 ** | 9194 ** ^In order to succeed, the database connection must not be in |
8927 ** ^In order to succeed, a call to [sqlite3_snapshot_open(D,S,P)] must be | 9195 ** [autocommit mode] when [sqlite3_snapshot_open(D,S,P)] is called. If there |
8928 ** the first operation following the [BEGIN] that takes the schema S | 9196 ** is already a read transaction open on schema S, then the database handle |
8929 ** out of [autocommit mode]. | 9197 ** must have no active statements (SELECT statements that have been passed |
8930 ** ^In other words, schema S must not currently be in | 9198 ** to sqlite3_step() but not sqlite3_reset() or sqlite3_finalize()). |
8931 ** a transaction for [sqlite3_snapshot_open(D,S,P)] to work, but the | 9199 ** SQLITE_ERROR is returned if either of these conditions is violated, or |
8932 ** database connection D must be out of [autocommit mode]. | 9200 ** if schema S does not exist, or if the snapshot object is invalid. |
8933 ** ^A [snapshot] will fail to open if it has been overwritten by a | 9201 ** |
8934 ** [checkpoint]. | 9202 ** ^A call to sqlite3_snapshot_open() will fail to open if the specified |
9203 ** snapshot has been overwritten by a [checkpoint]. In this case | |
9204 ** SQLITE_ERROR_SNAPSHOT is returned. | |
9205 ** | |
9206 ** If there is already a read transaction open when this function is | |
9207 ** invoked, then the same read transaction remains open (on the same | |
9208 ** database snapshot) if SQLITE_ERROR, SQLITE_BUSY or SQLITE_ERROR_SNAPSHOT | |
9209 ** is returned. If another error code - for example SQLITE_PROTOCOL or an | |
9210 ** SQLITE_IOERR error code - is returned, then the final state of the | |
9211 ** read transaction is undefined. If SQLITE_OK is returned, then the | |
9212 ** read transaction is now open on database snapshot P. | |
9213 ** | |
8935 ** ^(A call to [sqlite3_snapshot_open(D,S,P)] will fail if the | 9214 ** ^(A call to [sqlite3_snapshot_open(D,S,P)] will fail if the |
8936 ** database connection D does not know that the database file for | 9215 ** database connection D does not know that the database file for |
8937 ** schema S is in [WAL mode]. A database connection might not know | 9216 ** schema S is in [WAL mode]. A database connection might not know |
8938 ** that the database file is in [WAL mode] if there has been no prior | 9217 ** that the database file is in [WAL mode] if there has been no prior |
8939 ** I/O on that database connection, or if the database entered [WAL mode] | 9218 ** I/O on that database connection, or if the database entered [WAL mode] |
8940 ** after the most recent I/O on the database connection.)^ | 9219 ** after the most recent I/O on the database connection.)^ |
8941 ** (Hint: Run "[PRAGMA application_id]" against a newly opened | 9220 ** (Hint: Run "[PRAGMA application_id]" against a newly opened |
8942 ** database connection in order to make it ready to use snapshots.) | 9221 ** database connection in order to make it ready to use snapshots.) |
8943 ** | 9222 ** |
8944 ** The [sqlite3_snapshot_open()] interface is only available when the | 9223 ** The [sqlite3_snapshot_open()] interface is only available when the |
8945 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used. | 9224 ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used. |
8946 */ | 9225 */ |
8947 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_open( | 9226 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_open( |
8948 sqlite3 *db, | 9227 sqlite3 *db, |
8949 const char *zSchema, | 9228 const char *zSchema, |
8950 sqlite3_snapshot *pSnapshot | 9229 sqlite3_snapshot *pSnapshot |
8951 ); | 9230 ); |
8952 | 9231 |
8953 /* | 9232 /* |
8954 ** CAPI3REF: Destroy a snapshot | 9233 ** CAPI3REF: Destroy a snapshot |
8955 ** EXPERIMENTAL | 9234 ** DESTRUCTOR: sqlite3_snapshot |
8956 ** | 9235 ** |
8957 ** ^The [sqlite3_snapshot_free(P)] interface destroys [sqlite3_snapshot] P. | 9236 ** ^The [sqlite3_snapshot_free(P)] interface destroys [sqlite3_snapshot] P. |
8958 ** The application must eventually free every [sqlite3_snapshot] object | 9237 ** The application must eventually free every [sqlite3_snapshot] object |
8959 ** using this routine to avoid a memory leak. | 9238 ** using this routine to avoid a memory leak. |
8960 ** | 9239 ** |
8961 ** The [sqlite3_snapshot_free()] interface is only available when the | 9240 ** The [sqlite3_snapshot_free()] interface is only available when the |
8962 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used. | 9241 ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used. |
8963 */ | 9242 */ |
8964 SQLITE_API SQLITE_EXPERIMENTAL void sqlite3_snapshot_free(sqlite3_snapshot*); | 9243 SQLITE_API SQLITE_EXPERIMENTAL void sqlite3_snapshot_free(sqlite3_snapshot*); |
8965 | 9244 |
8966 /* | 9245 /* |
8967 ** CAPI3REF: Compare the ages of two snapshot handles. | 9246 ** CAPI3REF: Compare the ages of two snapshot handles. |
8968 ** EXPERIMENTAL | 9247 ** METHOD: sqlite3_snapshot |
8969 ** | 9248 ** |
8970 ** The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages | 9249 ** The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages |
8971 ** of two valid snapshot handles. | 9250 ** of two valid snapshot handles. |
8972 ** | 9251 ** |
8973 ** If the two snapshot handles are not associated with the same database | 9252 ** If the two snapshot handles are not associated with the same database |
8982 ** is undefined. | 9261 ** is undefined. |
8983 ** | 9262 ** |
8984 ** Otherwise, this API returns a negative value if P1 refers to an older | 9263 ** Otherwise, this API returns a negative value if P1 refers to an older |
8985 ** snapshot than P2, zero if the two handles refer to the same database | 9264 ** snapshot than P2, zero if the two handles refer to the same database |
8986 ** snapshot, and a positive value if P1 is a newer snapshot than P2. | 9265 ** snapshot, and a positive value if P1 is a newer snapshot than P2. |
9266 ** | |
9267 ** This interface is only available if SQLite is compiled with the | |
9268 ** [SQLITE_ENABLE_SNAPSHOT] option. | |
8987 */ | 9269 */ |
8988 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_cmp( | 9270 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_cmp( |
8989 sqlite3_snapshot *p1, | 9271 sqlite3_snapshot *p1, |
8990 sqlite3_snapshot *p2 | 9272 sqlite3_snapshot *p2 |
8991 ); | 9273 ); |
8992 | 9274 |
8993 /* | 9275 /* |
8994 ** CAPI3REF: Recover snapshots from a wal file | 9276 ** CAPI3REF: Recover snapshots from a wal file |
8995 ** EXPERIMENTAL | 9277 ** METHOD: sqlite3_snapshot |
8996 ** | 9278 ** |
8997 ** If all connections disconnect from a database file but do not perform | 9279 ** If a [WAL file] remains on disk after all database connections close |
8998 ** a checkpoint, the existing wal file is opened along with the database | 9280 ** (either through the use of the [SQLITE_FCNTL_PERSIST_WAL] [file control] |
8999 ** file the next time the database is opened. At this point it is only | 9281 ** or because the last process to have the database opened exited without |
9000 ** possible to successfully call sqlite3_snapshot_open() to open the most | 9282 ** calling [sqlite3_close()]) and a new connection is subsequently opened |
9001 ** recent snapshot of the database (the one at the head of the wal file), | 9283 ** on that database and [WAL file], the [sqlite3_snapshot_open()] interface |
9002 ** even though the wal file may contain other valid snapshots for which | 9284 ** will only be able to open the last transaction added to the WAL file |
9003 ** clients have sqlite3_snapshot handles. | 9285 ** even though the WAL file contains other valid transactions. |
9004 ** | 9286 ** |
9005 ** This function attempts to scan the wal file associated with database zDb | 9287 ** This function attempts to scan the WAL file associated with database zDb |
9006 ** of database handle db and make all valid snapshots available to | 9288 ** of database handle db and make all valid snapshots available to |
9007 ** sqlite3_snapshot_open(). It is an error if there is already a read | 9289 ** sqlite3_snapshot_open(). It is an error if there is already a read |
9008 ** transaction open on the database, or if the database is not a wal mode | 9290 ** transaction open on the database, or if the database is not a WAL mode |
9009 ** database. | 9291 ** database. |
9010 ** | 9292 ** |
9011 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise. | 9293 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise. |
9294 ** | |
9295 ** This interface is only available if SQLite is compiled with the | |
9296 ** [SQLITE_ENABLE_SNAPSHOT] option. | |
9012 */ | 9297 */ |
9013 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb); | 9298 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb); |
9014 | 9299 |
9015 /* | 9300 /* |
9016 ** CAPI3REF: Serialize a database | 9301 ** CAPI3REF: Serialize a database |
9117 ** | 9402 ** |
9118 ** The SQLITE_DESERIALIZE_FREEONCLOSE means that the database serialization | 9403 ** The SQLITE_DESERIALIZE_FREEONCLOSE means that the database serialization |
9119 ** in the P argument is held in memory obtained from [sqlite3_malloc64()] | 9404 ** in the P argument is held in memory obtained from [sqlite3_malloc64()] |
9120 ** and that SQLite should take ownership of this memory and automatically | 9405 ** and that SQLite should take ownership of this memory and automatically |
9121 ** free it when it has finished using it. Without this flag, the caller | 9406 ** free it when it has finished using it. Without this flag, the caller |
9122 ** is resposible for freeing any dynamically allocated memory. | 9407 ** is responsible for freeing any dynamically allocated memory. |
9123 ** | 9408 ** |
9124 ** The SQLITE_DESERIALIZE_RESIZEABLE flag means that SQLite is allowed to | 9409 ** The SQLITE_DESERIALIZE_RESIZEABLE flag means that SQLite is allowed to |
9125 ** grow the size of the database using calls to [sqlite3_realloc64()]. This | 9410 ** grow the size of the database using calls to [sqlite3_realloc64()]. This |
9126 ** flag should only be used if SQLITE_DESERIALIZE_FREEONCLOSE is also used. | 9411 ** flag should only be used if SQLITE_DESERIALIZE_FREEONCLOSE is also used. |
9127 ** Without this flag, the deserialized database cannot increase in size beyond | 9412 ** Without this flag, the deserialized database cannot increase in size beyond |
9243 int iLevel; /* Level of current node or entry */ | 9528 int iLevel; /* Level of current node or entry */ |
9244 int mxLevel; /* The largest iLevel value in the tree */ | 9529 int mxLevel; /* The largest iLevel value in the tree */ |
9245 sqlite3_int64 iRowid; /* Rowid for current entry */ | 9530 sqlite3_int64 iRowid; /* Rowid for current entry */ |
9246 sqlite3_rtree_dbl rParentScore; /* Score of parent node */ | 9531 sqlite3_rtree_dbl rParentScore; /* Score of parent node */ |
9247 int eParentWithin; /* Visibility of parent node */ | 9532 int eParentWithin; /* Visibility of parent node */ |
9248 int eWithin; /* OUT: Visiblity */ | 9533 int eWithin; /* OUT: Visibility */ |
9249 sqlite3_rtree_dbl rScore; /* OUT: Write the score here */ | 9534 sqlite3_rtree_dbl rScore; /* OUT: Write the score here */ |
9250 /* The following fields are only available in 3.8.11 and later */ | 9535 /* The following fields are only available in 3.8.11 and later */ |
9251 sqlite3_value **apSqlParam; /* Original SQL values of parameters */ | 9536 sqlite3_value **apSqlParam; /* Original SQL values of parameters */ |
9252 }; | 9537 }; |
9253 | 9538 |
9739 ** an application iterates through a changeset using an iterator created by | 10024 ** an application iterates through a changeset using an iterator created by |
9740 ** this function, all changes that relate to a single table are visited | 10025 ** this function, all changes that relate to a single table are visited |
9741 ** consecutively. There is no chance that the iterator will visit a change | 10026 ** consecutively. There is no chance that the iterator will visit a change |
9742 ** the applies to table X, then one for table Y, and then later on visit | 10027 ** the applies to table X, then one for table Y, and then later on visit |
9743 ** another change for table X. | 10028 ** another change for table X. |
10029 ** | |
10030 ** The behavior of sqlite3changeset_start_v2() and its streaming equivalent | |
10031 ** may be modified by passing a combination of | |
10032 ** [SQLITE_CHANGESETSTART_INVERT | supported flags] as the 4th parameter. | |
10033 ** | |
10034 ** Note that the sqlite3changeset_start_v2() API is still <b>experimental</b> | |
10035 ** and therefore subject to change. | |
9744 */ | 10036 */ |
9745 SQLITE_API int sqlite3changeset_start( | 10037 SQLITE_API int sqlite3changeset_start( |
9746 sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */ | 10038 sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */ |
9747 int nChangeset, /* Size of changeset blob in bytes */ | 10039 int nChangeset, /* Size of changeset blob in bytes */ |
9748 void *pChangeset /* Pointer to blob containing changeset */ | 10040 void *pChangeset /* Pointer to blob containing changeset */ |
9749 ); | 10041 ); |
10042 SQLITE_API int sqlite3changeset_start_v2( | |
10043 sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */ | |
10044 int nChangeset, /* Size of changeset blob in bytes */ | |
10045 void *pChangeset, /* Pointer to blob containing changeset */ | |
10046 int flags /* SESSION_CHANGESETSTART_* flags */ | |
10047 ); | |
10048 | |
10049 /* | |
10050 ** CAPI3REF: Flags for sqlite3changeset_start_v2 | |
10051 ** | |
10052 ** The following flags may passed via the 4th parameter to | |
10053 ** [sqlite3changeset_start_v2] and [sqlite3changeset_start_v2_strm]: | |
10054 ** | |
10055 ** <dt>SQLITE_CHANGESETAPPLY_INVERT <dd> | |
10056 ** Invert the changeset while iterating through it. This is equivalent to | |
10057 ** inverting a changeset using sqlite3changeset_invert() before applying it. | |
10058 ** It is an error to specify this flag with a patchset. | |
10059 */ | |
10060 #define SQLITE_CHANGESETSTART_INVERT 0x0002 | |
9750 | 10061 |
9751 | 10062 |
9752 /* | 10063 /* |
9753 ** CAPI3REF: Advance A Changeset Iterator | 10064 ** CAPI3REF: Advance A Changeset Iterator |
9754 ** METHOD: sqlite3_changeset_iter | 10065 ** METHOD: sqlite3_changeset_iter |
9788 ** nul-terminated utf-8 encoded string containing the name of the table | 10099 ** nul-terminated utf-8 encoded string containing the name of the table |
9789 ** affected by the current change. The buffer remains valid until either | 10100 ** affected by the current change. The buffer remains valid until either |
9790 ** sqlite3changeset_next() is called on the iterator or until the | 10101 ** sqlite3changeset_next() is called on the iterator or until the |
9791 ** conflict-handler function returns. If pnCol is not NULL, then *pnCol is | 10102 ** conflict-handler function returns. If pnCol is not NULL, then *pnCol is |
9792 ** set to the number of columns in the table affected by the change. If | 10103 ** set to the number of columns in the table affected by the change. If |
9793 ** pbIncorrect is not NULL, then *pbIndirect is set to true (1) if the change | 10104 ** pbIndirect is not NULL, then *pbIndirect is set to true (1) if the change |
9794 ** is an indirect change, or false (0) otherwise. See the documentation for | 10105 ** is an indirect change, or false (0) otherwise. See the documentation for |
9795 ** [sqlite3session_indirect()] for a description of direct and indirect | 10106 ** [sqlite3session_indirect()] for a description of direct and indirect |
9796 ** changes. Finally, if pOp is not NULL, then *pOp is set to one of | 10107 ** changes. Finally, if pOp is not NULL, then *pOp is set to one of |
9797 ** [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], depending on the | 10108 ** [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], depending on the |
9798 ** type of change that the iterator currently points to. | 10109 ** type of change that the iterator currently points to. |
10399 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */ | 10710 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */ |
10400 sqlite3_changeset_iter *p /* Handle describing change and conflict */ | 10711 sqlite3_changeset_iter *p /* Handle describing change and conflict */ |
10401 ), | 10712 ), |
10402 void *pCtx, /* First argument passed to xConflict */ | 10713 void *pCtx, /* First argument passed to xConflict */ |
10403 void **ppRebase, int *pnRebase, /* OUT: Rebase data */ | 10714 void **ppRebase, int *pnRebase, /* OUT: Rebase data */ |
10404 int flags /* Combination of SESSION_APPLY_* flags */ | 10715 int flags /* SESSION_CHANGESETAPPLY_* flags */ |
10405 ); | 10716 ); |
10406 | 10717 |
10407 /* | 10718 /* |
10408 ** CAPI3REF: Flags for sqlite3changeset_apply_v2 | 10719 ** CAPI3REF: Flags for sqlite3changeset_apply_v2 |
10409 ** | 10720 ** |
10417 ** SAVEPOINT is committed if the changeset or patchset is successfully | 10728 ** SAVEPOINT is committed if the changeset or patchset is successfully |
10418 ** applied, or rolled back if an error occurs. Specifying this flag | 10729 ** applied, or rolled back if an error occurs. Specifying this flag |
10419 ** causes the sessions module to omit this savepoint. In this case, if the | 10730 ** causes the sessions module to omit this savepoint. In this case, if the |
10420 ** caller has an open transaction or savepoint when apply_v2() is called, | 10731 ** caller has an open transaction or savepoint when apply_v2() is called, |
10421 ** it may revert the partially applied changeset by rolling it back. | 10732 ** it may revert the partially applied changeset by rolling it back. |
10733 ** | |
10734 ** <dt>SQLITE_CHANGESETAPPLY_INVERT <dd> | |
10735 ** Invert the changeset before applying it. This is equivalent to inverting | |
10736 ** a changeset using sqlite3changeset_invert() before applying it. It is | |
10737 ** an error to specify this flag with a patchset. | |
10422 */ | 10738 */ |
10423 #define SQLITE_CHANGESETAPPLY_NOSAVEPOINT 0x0001 | 10739 #define SQLITE_CHANGESETAPPLY_NOSAVEPOINT 0x0001 |
10740 #define SQLITE_CHANGESETAPPLY_INVERT 0x0002 | |
10424 | 10741 |
10425 /* | 10742 /* |
10426 ** CAPI3REF: Constants Passed To The Conflict Handler | 10743 ** CAPI3REF: Constants Passed To The Conflict Handler |
10427 ** | 10744 ** |
10428 ** Values that may be passed as the second argument to a conflict-handler. | 10745 ** Values that may be passed as the second argument to a conflict-handler. |
10649 ** | 10966 ** |
10650 ** Argument pIn must point to a buffer containing a changeset nIn bytes | 10967 ** Argument pIn must point to a buffer containing a changeset nIn bytes |
10651 ** in size. This function allocates and populates a buffer with a copy | 10968 ** in size. This function allocates and populates a buffer with a copy |
10652 ** of the changeset rebased rebased according to the configuration of the | 10969 ** of the changeset rebased rebased according to the configuration of the |
10653 ** rebaser object passed as the first argument. If successful, (*ppOut) | 10970 ** rebaser object passed as the first argument. If successful, (*ppOut) |
10654 ** is set to point to the new buffer containing the rebased changset and | 10971 ** is set to point to the new buffer containing the rebased changeset and |
10655 ** (*pnOut) to its size in bytes and SQLITE_OK returned. It is the | 10972 ** (*pnOut) to its size in bytes and SQLITE_OK returned. It is the |
10656 ** responsibility of the caller to eventually free the new buffer using | 10973 ** responsibility of the caller to eventually free the new buffer using |
10657 ** sqlite3_free(). Otherwise, if an error occurs, (*ppOut) and (*pnOut) | 10974 ** sqlite3_free(). Otherwise, if an error occurs, (*ppOut) and (*pnOut) |
10658 ** are set to zero and an SQLite error code returned. | 10975 ** are set to zero and an SQLite error code returned. |
10659 */ | 10976 */ |
10812 SQLITE_API int sqlite3changeset_start_strm( | 11129 SQLITE_API int sqlite3changeset_start_strm( |
10813 sqlite3_changeset_iter **pp, | 11130 sqlite3_changeset_iter **pp, |
10814 int (*xInput)(void *pIn, void *pData, int *pnData), | 11131 int (*xInput)(void *pIn, void *pData, int *pnData), |
10815 void *pIn | 11132 void *pIn |
10816 ); | 11133 ); |
11134 SQLITE_API int sqlite3changeset_start_v2_strm( | |
11135 sqlite3_changeset_iter **pp, | |
11136 int (*xInput)(void *pIn, void *pData, int *pnData), | |
11137 void *pIn, | |
11138 int flags | |
11139 ); | |
10817 SQLITE_API int sqlite3session_changeset_strm( | 11140 SQLITE_API int sqlite3session_changeset_strm( |
10818 sqlite3_session *pSession, | 11141 sqlite3_session *pSession, |
10819 int (*xOutput)(void *pOut, const void *pData, int nData), | 11142 int (*xOutput)(void *pOut, const void *pData, int nData), |
10820 void *pOut | 11143 void *pOut |
10821 ); | 11144 ); |
10838 void *pIn, | 11161 void *pIn, |
10839 int (*xOutput)(void *pOut, const void *pData, int nData), | 11162 int (*xOutput)(void *pOut, const void *pData, int nData), |
10840 void *pOut | 11163 void *pOut |
10841 ); | 11164 ); |
10842 | 11165 |
11166 /* | |
11167 ** CAPI3REF: Configure global parameters | |
11168 ** | |
11169 ** The sqlite3session_config() interface is used to make global configuration | |
11170 ** changes to the sessions module in order to tune it to the specific needs | |
11171 ** of the application. | |
11172 ** | |
11173 ** The sqlite3session_config() interface is not threadsafe. If it is invoked | |
11174 ** while any other thread is inside any other sessions method then the | |
11175 ** results are undefined. Furthermore, if it is invoked after any sessions | |
11176 ** related objects have been created, the results are also undefined. | |
11177 ** | |
11178 ** The first argument to the sqlite3session_config() function must be one | |
11179 ** of the SQLITE_SESSION_CONFIG_XXX constants defined below. The | |
11180 ** interpretation of the (void*) value passed as the second parameter and | |
11181 ** the effect of calling this function depends on the value of the first | |
11182 ** parameter. | |
11183 ** | |
11184 ** <dl> | |
11185 ** <dt>SQLITE_SESSION_CONFIG_STRMSIZE<dd> | |
11186 ** By default, the sessions module streaming interfaces attempt to input | |
11187 ** and output data in approximately 1 KiB chunks. This operand may be used | |
11188 ** to set and query the value of this configuration setting. The pointer | |
11189 ** passed as the second argument must point to a value of type (int). | |
11190 ** If this value is greater than 0, it is used as the new streaming data | |
11191 ** chunk size for both input and output. Before returning, the (int) value | |
11192 ** pointed to by pArg is set to the final value of the streaming interface | |
11193 ** chunk size. | |
11194 ** </dl> | |
11195 ** | |
11196 ** This function returns SQLITE_OK if successful, or an SQLite error code | |
11197 ** otherwise. | |
11198 */ | |
11199 SQLITE_API int sqlite3session_config(int op, void *pArg); | |
11200 | |
11201 /* | |
11202 ** CAPI3REF: Values for sqlite3session_config(). | |
11203 */ | |
11204 #define SQLITE_SESSION_CONFIG_STRMSIZE 1 | |
10843 | 11205 |
10844 /* | 11206 /* |
10845 ** Make sure we can call this stuff from C++. | 11207 ** Make sure we can call this stuff from C++. |
10846 */ | 11208 */ |
10847 #ifdef __cplusplus | 11209 #ifdef __cplusplus |
10971 ** should be greater than or equal to zero and smaller than the value | 11333 ** should be greater than or equal to zero and smaller than the value |
10972 ** output by xInstCount(). | 11334 ** output by xInstCount(). |
10973 ** | 11335 ** |
10974 ** Usually, output parameter *piPhrase is set to the phrase number, *piCol | 11336 ** Usually, output parameter *piPhrase is set to the phrase number, *piCol |
10975 ** to the column in which it occurs and *piOff the token offset of the | 11337 ** to the column in which it occurs and *piOff the token offset of the |
10976 ** first token of the phrase. The exception is if the table was created | 11338 ** first token of the phrase. Returns SQLITE_OK if successful, or an error |
10977 ** with the offsets=0 option specified. In this case *piOff is always | 11339 ** code (i.e. SQLITE_NOMEM) if an error occurs. |
10978 ** set to -1. | |
10979 ** | |
10980 ** Returns SQLITE_OK if successful, or an error code (i.e. SQLITE_NOMEM) | |
10981 ** if an error occurs. | |
10982 ** | 11340 ** |
10983 ** This API can be quite slow if used with an FTS5 table created with the | 11341 ** This API can be quite slow if used with an FTS5 table created with the |
10984 ** "detail=none" or "detail=column" option. | 11342 ** "detail=none" or "detail=column" option. |
10985 ** | 11343 ** |
10986 ** xRowid: | 11344 ** xRowid: |
11017 ** xSetAuxdata(pFts5, pAux, xDelete) | 11375 ** xSetAuxdata(pFts5, pAux, xDelete) |
11018 ** | 11376 ** |
11019 ** Save the pointer passed as the second argument as the extension functions | 11377 ** Save the pointer passed as the second argument as the extension functions |
11020 ** "auxiliary data". The pointer may then be retrieved by the current or any | 11378 ** "auxiliary data". The pointer may then be retrieved by the current or any |
11021 ** future invocation of the same fts5 extension function made as part of | 11379 ** future invocation of the same fts5 extension function made as part of |
11022 ** of the same MATCH query using the xGetAuxdata() API. | 11380 ** the same MATCH query using the xGetAuxdata() API. |
11023 ** | 11381 ** |
11024 ** Each extension function is allocated a single auxiliary data slot for | 11382 ** Each extension function is allocated a single auxiliary data slot for |
11025 ** each FTS query (MATCH expression). If the extension function is invoked | 11383 ** each FTS query (MATCH expression). If the extension function is invoked |
11026 ** more than once for a single FTS query, then all invocations share a | 11384 ** more than once for a single FTS query, then all invocations share a |
11027 ** single auxiliary data context. | 11385 ** single auxiliary data context. |
11032 ** point. | 11390 ** point. |
11033 ** | 11391 ** |
11034 ** The xDelete callback, if one is specified, is also invoked on the | 11392 ** The xDelete callback, if one is specified, is also invoked on the |
11035 ** auxiliary data pointer after the FTS5 query has finished. | 11393 ** auxiliary data pointer after the FTS5 query has finished. |
11036 ** | 11394 ** |
11037 ** If an error (e.g. an OOM condition) occurs within this function, an | 11395 ** If an error (e.g. an OOM condition) occurs within this function, |
11038 ** the auxiliary data is set to NULL and an error code returned. If the | 11396 ** the auxiliary data is set to NULL and an error code returned. If the |
11039 ** xDelete parameter was not NULL, it is invoked on the auxiliary data | 11397 ** xDelete parameter was not NULL, it is invoked on the auxiliary data |
11040 ** pointer before returning. | 11398 ** pointer before returning. |
11041 ** | 11399 ** |
11042 ** | 11400 ** |
11265 ** 1st place" entries are added to the index for tokens "i", "won", | 11623 ** 1st place" entries are added to the index for tokens "i", "won", |
11266 ** "first" and "place". If the user then queries for '1st + place', | 11624 ** "first" and "place". If the user then queries for '1st + place', |
11267 ** the tokenizer substitutes "first" for "1st" and the query works | 11625 ** the tokenizer substitutes "first" for "1st" and the query works |
11268 ** as expected. | 11626 ** as expected. |
11269 ** | 11627 ** |
11270 ** <li> By adding multiple synonyms for a single term to the FTS index. | 11628 ** <li> By querying the index for all synonyms of each query term |
11271 ** In this case, when tokenizing query text, the tokenizer may | 11629 ** separately. In this case, when tokenizing query text, the |
11272 ** provide multiple synonyms for a single term within the document. | 11630 ** tokenizer may provide multiple synonyms for a single term |
11273 ** FTS5 then queries the index for each synonym individually. For | 11631 ** within the document. FTS5 then queries the index for each |
11274 ** example, faced with the query: | 11632 ** synonym individually. For example, faced with the query: |
11275 ** | 11633 ** |
11276 ** <codeblock> | 11634 ** <codeblock> |
11277 ** ... MATCH 'first place'</codeblock> | 11635 ** ... MATCH 'first place'</codeblock> |
11278 ** | 11636 ** |
11279 ** the tokenizer offers both "1st" and "first" as synonyms for the | 11637 ** the tokenizer offers both "1st" and "first" as synonyms for the |
11293 ** document such as "I won first place" is tokenized, entries are | 11651 ** document such as "I won first place" is tokenized, entries are |
11294 ** added to the FTS index for "i", "won", "first", "1st" and | 11652 ** added to the FTS index for "i", "won", "first", "1st" and |
11295 ** "place". | 11653 ** "place". |
11296 ** | 11654 ** |
11297 ** This way, even if the tokenizer does not provide synonyms | 11655 ** This way, even if the tokenizer does not provide synonyms |
11298 ** when tokenizing query text (it should not - to do would be | 11656 ** when tokenizing query text (it should not - to do so would be |
11299 ** inefficient), it doesn't matter if the user queries for | 11657 ** inefficient), it doesn't matter if the user queries for |
11300 ** 'first + place' or '1st + place', as there are entires in the | 11658 ** 'first + place' or '1st + place', as there are entries in the |
11301 ** FTS index corresponding to both forms of the first token. | 11659 ** FTS index corresponding to both forms of the first token. |
11302 ** </ol> | 11660 ** </ol> |
11303 ** | 11661 ** |
11304 ** Whether it is parsing document or query text, any call to xToken that | 11662 ** Whether it is parsing document or query text, any call to xToken that |
11305 ** specifies a <i>tflags</i> argument with the FTS5_TOKEN_COLOCATED bit | 11663 ** specifies a <i>tflags</i> argument with the FTS5_TOKEN_COLOCATED bit |
11323 ** | 11681 ** |
11324 ** In many cases, method (1) above is the best approach. It does not add | 11682 ** In many cases, method (1) above is the best approach. It does not add |
11325 ** extra data to the FTS index or require FTS5 to query for multiple terms, | 11683 ** extra data to the FTS index or require FTS5 to query for multiple terms, |
11326 ** so it is efficient in terms of disk space and query speed. However, it | 11684 ** so it is efficient in terms of disk space and query speed. However, it |
11327 ** does not support prefix queries very well. If, as suggested above, the | 11685 ** does not support prefix queries very well. If, as suggested above, the |
11328 ** token "first" is subsituted for "1st" by the tokenizer, then the query: | 11686 ** token "first" is substituted for "1st" by the tokenizer, then the query: |
11329 ** | 11687 ** |
11330 ** <codeblock> | 11688 ** <codeblock> |
11331 ** ... MATCH '1s*'</codeblock> | 11689 ** ... MATCH '1s*'</codeblock> |
11332 ** | 11690 ** |
11333 ** will not match documents that contain the token "1st" (as the tokenizer | 11691 ** will not match documents that contain the token "1st" (as the tokenizer |