Support the libsqlite3 native library.
The libsq3lite package is a library for using the sqlite3 database
link:-Lpath -lsq3liteor automake:LDADD = libsq3lite.la
The libsq3lite package is a composition of multiple classes defining the Programming-Language-Micro-Kernel (PLMK) :
| object | description |
|---|---|
Sq3 | the namespace with all libsq3lite specific definitions |
Sq3Attribute(…) | the interface to access the package specific attribute |
Sq3ClassAttribute(…) | the interface to access the class specific attribute |
Sq3ClassAttribute(Instance,…) | the interface to access the instance specific attribute |
To access all features without Sq3 prefix use:
#include "LibSq3Lite_lc.h"
orLDADD = path/to/libsq3lite.la
Example from acmds/Makefile.am using libmkkernel.la and libmqmsgque.la:mylib_la_LIBADD = path/to/libsq3lite.la
C-API: SQ3_C_API - The Sq3Lite API.
SQLite is an in-process library that implements a self-contained, serverless, zero-configuration, transactional SQL database engine.
The code for SQLite is in the public domain and is thus free for use for any purpose, commercial or private.
| Sq3Lite SETUP | |||
| libsq3lite | META - Setup und Cleanup the Meta Library libsq3lite … | ||
| libsqlite3 | NATIVE - Initialize The SQLite Library libsqlite3 … | ||
| Sq3Lite ENUM | |||
| enum Sq3VtabE | Virtual Table Configuration Options. | ||
| enum Sq3TypeE | Fundamental Datatypes. | ||
| enum Sq3TxnE | Allowed return values from sqlite3_txn_state() | ||
| enum Sq3TraceEF | SQL Trace Event Codes. | ||
| enum Sq3TextE | Text Encodings. | ||
| enum Sq3TestCtrlE | Testing Interface Operation Codes. | ||
| enum Sq3SyncEF | Synchronization Type Flags. | ||
| enum Sq3StmtStatusE | Status Parameters for prepared statements. | ||
| enum Sq3StatusE | Status Parameters. | ||
| enum Sq3ShmLockE | Flags for the xShmLock VFS method. | ||
| enum Sq3SessionObjConfigE | Options for sqlite3session_object_config. | ||
| enum Sq3SerializeE | Flags for sqlite3_serialize. | ||
| enum Sq3ScanStatE | Prepared Statement Scan Status Opcodes. | ||
| enum Sq3PrepareEF | Prepare Flags. | ||
| enum Sq3OpenEF | Flags For File Open Operations. | ||
| enum Sq3MutexE | Mutex Types. | ||
| enum Sq3LockE | File Locking Levels. | ||
| enum Sq3LimitE | Run-Time Limit Categories. | ||
| enum Sq3IoCapEF | Device Characteristics. | ||
| enum Sq3IndexConstraintEF | Virtual Table Constraint Operator Codes. | ||
| enum Sq3FunctionEF | Function Flags. | ||
| enum Sq3FcntlE | Standard File Control Opcodes. | ||
| enum Sq3ExtendetResultCodesE | Extended Result Codes. | ||
| enum Sq3ErrorE | Result Codes. | ||
| enum Sq3DeSerializeEF | Flags for sqlite3_deserialize() | ||
| enum Sq3DbStatusE | Status Parameters for database connections. | ||
| enum Sq3DbConfigE | Database Connection Configuration Options. | ||
| enum Sq3ConflictResolutionE | Conflict resolution modes. | ||
| enum Sq3ConfigE | Configuration Options. | ||
| enum Sq3CheckpointE | Checkpoint Mode Values. | ||
| enum Sq3ChangesetE | Constants Passed To The Conflict Handler. | ||
| enum Sq3ChangeSetConflictE | Constants Returned By The Conflict Handler. | ||
| enum Sq3AuthReturnE | Authorizer Return Codes. | ||
| enum Sq3AuthActionE | Authorizer Action Codes. | ||
| enum Sq3AccessE | Flags for the xAccess VFS method. | ||
| Sq3Lite CONFIG | |||
| CompileOptionGet | Run-Time Library Compilation Options Diagnostics … | ||
| CompileOptionUsed | Run-Time Library Compilation Options Diagnostics … | ||
| ProgressHandler | Query Progress Callbacks … | ||
| SetAuthorizer | Compile-Time Authorization Callbacks … | ||
| MemoryHighwater | Memory Allocator Statistics … | ||
| MemoryUsed | Memory Allocator Statistics … | ||
| Randomness | Pseudo-Random Number Generator … | ||
| SetupThreadCallback | Initialize a callback which is called at runtime-setup … | ||
| Threadsafe | Test To See If The Library Is Threadsafe … | ||
| Sq3Lite INFO | |||
| Complete | Determine If An SQL Statement Is Complete … | ||
| KeywordCheck | SQL Keyword Checking … | ||
| KeywordCount | SQL Keyword Checking … | ||
| KeywordName | SQL Keyword Checking … | ||
| KeywordNameBUF | SQL Keyword Checking … | ||
| Status | SQLite Runtime Status … | ||
| Status64 | SQLite Runtime Status … | ||
| Sq3Lite INTERNAL | |||
| Alloc | Memory Allocation Subsystem … | ||
| Memory | Sq3Lite PACKAGE - functions related to index 'Internal' and doc 'Memory' … | ||
| String | Sq3Lite PACKAGE - functions related to index 'Internal' and doc 'String' … | ||
| Sq3Lite VERSION | |||
| Libversion | Run-Time Library Version Numbers … | ||
| LibversionNumber | Run-Time Library Version Numbers … | ||
| Sourceid | Run-Time Library Version Numbers … | ||
| Sq3Lite VFS | |||
| CreateFilename | Create and Destroy VFS Filenames … | ||
| FilenameDatabase | Translate filenames … | ||
| FilenameJournal | Translate filenames … | ||
| FilenameWal | Translate filenames … | ||
| FreeFilename | Create and Destroy VFS Filenames … | ||
| UriBoolean | Obtain Values For URI Parameters … | ||
| UriInt64 | Obtain Values For URI Parameters … | ||
| UriKey | Obtain Values For URI Parameters … | ||
| UriParameter | Obtain Values For URI Parameters … | ||
| Sq3Lite ERROR | |||
| ErrorCheckI | check if ret signal an error … | ||
| ErrorToMQ | if a libsq3lite funtion return a MkErrorE use this function to convert the libsq3lite-error into the libmkkernel-error … | ||
C-API: Sq3Lite_C_API - Sq3Lite PACKAGE - toplevel package of the Programming-Language-Micro-Kernel (PLMK) …
The libsq3lite package is loaded with:
link:-Lpath -lsq3liteor automake:LDADD = libsq3lite.la
and is a composition of one or more package-item and exact one package-main.
The libsq3lite package add the following classes into MkObjectC_C_API :
| Object | C-Short | Description |
|---|---|---|
| Sq3LiteC | SQ3_LITE | Sq3LiteC - the class known as sq3lite or Lite defined by Sq3LiteS … |
| Sq3ValueC | SQ3_VAL | Sq3ValueC - the class known as sq3val or Value define by Sq3ValueS … |
| Sq3BlobC | SQ3_BLOB | Sq3BlobC - the class known as sq3blob or Blob define by Sq3BlobS … |
| Sq3FileC | SQ3_FILE | Sq3FileC - the class known as sq3file or File defined by Sq3FileS … |
| Sq3StmtC | SQ3_STMT | Sq3StmtC - the class known as sq3stmt or Statement defined by Sq3StmtS … |
The libsq3lite package add the following types into MkObjectC_C_API :
ABSTRACT: MkTypeSTT (TypeTypeType = type of a TypeType)
|
|- ABSTRACT: MkSuperTypeSTT (TypeType = type of a Type)
|
|- Sq3LiteST, Sq3ValueST, Sq3BlobST, Sq3FileST, Sq3StmtST| Cleanup | cleanup libsq3lite internal memory … | ||
| Setup | setup libsq3lite internal memory … | ||
| Initialize | Initialize The SQLite Library … | ||
| OsEnd | Initialize The SQLite Library … | ||
| OsInit | Initialize The SQLite Library … | ||
| Shutdown | Initialize The SQLite Library … | ||
C-API: Sq3Lite_Setup_C_API - Sq3Lite PACKAGE - setup library and Programming-Language-Micro-Kernel (PLMK) …
C-API: Sq3Lite_Setup_libsq3lite_C_API - META - Setup und Cleanup the Meta Library libsq3lite …
For details about Setup and Cleanup usage refer to MkKernel_Setup_libmkkernel_C_API
(static) void Sq3Cleanup()top cleanup libsq3lite internal memory … → API: Sq3Cleanup
MkCleanup can only be called once and will be ignored if not called in the same thread as Sq3Setup. after a call to Sq3Setup the call to MkCleanup is possible again.
(static) void Sq3Setup()top setup libsq3lite internal memory … → API: Sq3Setup
Sq3Setup can only be called once, additional call's will be ignored until a Sq3Cleanup is called.
C-API: Sq3Lite_Setup_libsqlite3_C_API - NATIVE - Initialize The SQLite Library libsqlite3 …
Initialize The SQLite Library …
The Sq3Initialize() routine initializes the SQLite library. The Sq3Shutdown() routine deallocates any resources that were allocated by Sq3Initialize(). These routines are designed to aid in process initialization and shutdown on embedded systems. Workstation applications using SQLite normally do not need to invoke either of these routines.
A call to Sq3Initialize() is an "effective" call if it is the first time Sq3Initialize() is invoked during the lifetime of the process, or if it is the first time Sq3Initialize() is invoked following a call to Sq3Shutdown(). Only an effective call of Sq3Initialize() does any initialization. All other calls are harmless no-ops.
A call to Sq3Shutdown() is an "effective" call if it is the first call to Sq3Shutdown() since the last Sq3Initialize(). Only an effective call to Sq3Shutdown() does any deinitialization. All other valid calls to Sq3Shutdown() are harmless no-ops.
The Sq3Initialize() interface is threadsafe, but Sq3Shutdown() is not. The Sq3Shutdown() interface must only be called from a single thread. All open database connections must be closed and all other SQLite resources must be deallocated prior to invoking Sq3Shutdown().
Among other things, Sq3Initialize() will invoke Sq3OsInit(). Similarly, Sq3Shutdown() will invoke Sq3OsEnd().
The Sq3Initialize() routine returns SQ3_RESULT_OK on success. If for some reason, Sq3Initialize() is unable to initialize the library (perhaps it is unable to allocate a needed resource such as a mutex) it returns an error code other than SQ3_RESULT_OK.
The Sq3Initialize() routine is called internally by many other SQLite interfaces so that an application usually does not need to invoke Sq3Initialize() directly. For example, sqlite3_open () calls Sq3Initialize() so the SQLite library will be automatically initialized when sqlite3_open () is called if it has not be initialized already. However, if SQLite is compiled with the SQLITE_OMIT_AUTOINIT compile-time option, then the automatic calls to Sq3Initialize() are omitted and the application must call Sq3Initialize() directly prior to using any other SQLite interface. For maximum portability, it is recommended that applications always invoke Sq3Initialize() directly prior to using any other SQLite interface. Future releases of SQLite may require this. In other words, the behavior exhibited when SQLite is compiled with SQLITE_OMIT_AUTOINIT might become the default behavior in some future release of SQLite.
The Sq3OsInit() routine does operating-system specific initialization of the SQLite library. The Sq3OsEnd() routine undoes the effect of Sq3OsInit(). Typical tasks performed by these routines include allocation or deallocation of static resources, initialization of global variables, setting up a default sqlite3_vfs module, or setting up a default configuration using sqlite3_config ().
The application should never invoke either Sq3OsInit() or Sq3OsEnd() directly. The application should only invoke Sq3Initialize() and Sq3Shutdown(). The Sq3OsInit() interface is called automatically by Sq3Initialize() and Sq3OsEnd() is called by Sq3Shutdown(). Appropriate implementations for Sq3OsInit() and Sq3OsEnd() are built into SQLite when it is compiled for Unix, Windows, or OS/2. When built for other platforms (using the SQLITE_OS_OTHER=1 compile-time option) the application must supply a suitable implementation for Sq3OsInit() and Sq3OsEnd(). An application-supplied implementation of Sq3OsInit() or Sq3OsEnd() must return SQ3_RESULT_OK on success and some other error code upon failure.
Reference code from sqlite3:
(static) enum MkErrorE Sq3Initialize()top Initialize The SQLite Library … → API: Sq3Initialize
read more at 'Sq3Lite_Setup_libsqlite3_C_API'
(static) enum MkErrorE Sq3OsEnd()top Initialize The SQLite Library … → API: Sq3OsEnd
read more at 'Sq3Lite_Setup_libsqlite3_C_API'
(static) enum MkErrorE Sq3OsInit()top Initialize The SQLite Library … → API: Sq3OsInit
read more at 'Sq3Lite_Setup_libsqlite3_C_API'
(static) enum MkErrorE Sq3Shutdown()top Initialize The SQLite Library … → API: Sq3Shutdown
read more at 'Sq3Lite_Setup_libsqlite3_C_API'
C-API: Sq3Lite_Enum_C_API - Sq3Lite PACKAGE - definition of the enum type …
read more at: MkKernel_Enum_C_API
top Flags for the xAccess VFS method. → API: Sq3AccessE
Flags for the xAccess VFS method …
These integer constants can be used as the third parameter to the xAccess method of an sqlite3_vfs object. They determine what kind of permissions the xAccess method is looking for. With SQ3_ACCESS_EXISTS, the xAccess method simply checks whether the file exists. With SQ3_ACCESS_READWRITE, the xAccess method checks whether the named directory is both readable and writable (in other words, if files can be added, removed, and renamed within the directory). The SQ3_ACCESS_READWRITE constant is currently used only by the temp_store_directory pragma, though this could change in a future release of SQLite. With SQ3_ACCESS_READ, the xAccess method checks whether the file is readable. The SQ3_ACCESS_READ constant is currently unused, though it might be used in a future release of SQLite.
Reference code from sqlite3:
(static) enum MkErrorE Sq3AccessE_FromInt(MK_I32 const value, enum Sq3AccessE *value_out)top return the Sq3AccessE from integer … → API: Sq3AccessE_FromInt
(static) MK_I32 Sq3AccessE_ToInt(enum Sq3AccessE value)top return the Sq3AccessE as integer … → API: Sq3AccessE_ToInt
(static) MK_STRN Sq3AccessE_ToString(enum Sq3AccessE value)top return the Sq3AccessE as string … → API: Sq3AccessE_ToString
top Authorizer Action Codes. → API: Sq3AuthActionE
Authorizer Action Codes …
The Sq3LiteSetAuthorizer () interface registers a callback function that is invoked to authorize certain SQL statement actions. The second parameter to the callback is an integer code that specifies what action is being authorized. These are the integer action codes that the authorizer callback may be passed.
These action code values signify what kind of operation is to be authorized. The 3rd and 4th parameters to the authorization callback function will be parameters or NULL depending on which of these codes is used as the second parameter. The 5th parameter to the authorizer callback is the name of the database ("main", "temp", etc.) if applicable. The 6th parameter to the authorizer callback is the name of the inner-most trigger or view that is responsible for the access attempt or NULL if this access attempt is directly from top-level SQL code.
Reference code from sqlite3:
(static) enum MkErrorE Sq3AuthActionE_FromInt(MK_I32 const value, enum Sq3AuthActionE *value_out)top return the Sq3AuthActionE from integer … → API: Sq3AuthActionE_FromInt
(static) MK_I32 Sq3AuthActionE_ToInt(enum Sq3AuthActionE value)top return the Sq3AuthActionE as integer … → API: Sq3AuthActionE_ToInt
(static) MK_STRN Sq3AuthActionE_ToString(enum Sq3AuthActionE value)top return the Sq3AuthActionE as string … → API: Sq3AuthActionE_ToString
top Authorizer Return Codes. → API: Sq3AuthReturnE
Authorizer Return Codes …
The authorizer callback function must return either SQ3_RESULT_OK or one of these two constants in order to signal SQLite whether or not the action is permitted. See the authorizer documentation for additional information.
Note that SQ3_AUTHRETURN_IGNORE is also used as a conflict resolution mode returned from the Sq3LiteVtabOnConflict () interface.
Reference code from sqlite3:
(static) enum MkErrorE Sq3AuthReturnE_FromInt(MK_I32 const value, enum Sq3AuthReturnE *value_out)top return the Sq3AuthReturnE from integer … → API: Sq3AuthReturnE_FromInt
(static) MK_I32 Sq3AuthReturnE_ToInt(enum Sq3AuthReturnE value)top return the Sq3AuthReturnE as integer … → API: Sq3AuthReturnE_ToInt
(static) MK_STRN Sq3AuthReturnE_ToString(enum Sq3AuthReturnE value)top return the Sq3AuthReturnE as string … → API: Sq3AuthReturnE_ToString
top Constants Returned By The Conflict Handler. → API: Sq3ChangeSetConflictE
Constants Returned By The Conflict Handler …
A conflict handler callback must return one of the following three values.
If a conflict handler returns this value no special action is taken. The change that caused the conflict is not applied. The session module continues to the next change in the changeset.
This value may only be returned if the second argument to the conflict handler was SQ3_CHANGESET_DATA or SQ3_CHANGESET_CONFLICT. If this is not the case, any changes applied so far are rolled back and the call to sqlite3changeset_apply() returns SQ3_RESULT_MISUSE.
If CHANGESET_REPLACE is returned by an SQ3_CHANGESET_DATA conflict handler, then the conflicting row is either updated or deleted, depending on the type of change.
If CHANGESET_REPLACE is returned by an SQ3_CHANGESET_CONFLICT conflict handler, then the conflicting row is removed from the database and a second attempt to apply the change is made. If this second attempt fails, the original row is restored to the database before continuing.
Reference code from sqlite3:
(static) enum MkErrorE Sq3ChangeSetConflictE_FromInt(MK_I32 const value, enum Sq3ChangeSetConflictE *value_out)top return the Sq3ChangeSetConflictE from integer … → API: Sq3ChangeSetConflictE_FromInt
(static) MK_I32 Sq3ChangeSetConflictE_ToInt(enum Sq3ChangeSetConflictE value)top return the Sq3ChangeSetConflictE as integer … → API: Sq3ChangeSetConflictE_ToInt
(static) MK_STRN Sq3ChangeSetConflictE_ToString(enum Sq3ChangeSetConflictE value)top return the Sq3ChangeSetConflictE as string … → API: Sq3ChangeSetConflictE_ToString
top Constants Passed To The Conflict Handler. → API: Sq3ChangesetE
Constants Passed To The Conflict Handler …
Values that may be passed as the second argument to a conflict-handler.
The conflict handler is invoked with CHANGESET_DATA as the second argument when processing a DELETE or UPDATE change if a row with the required PRIMARY KEY fields is present in the database, but one or more other (non primary-key) fields modified by the update do not contain the expected "before" values.
The conflicting row, in this case, is the database row with the matching primary key.
The conflict handler is invoked with CHANGESET_NOTFOUND as the second argument when processing a DELETE or UPDATE change if a row with the required PRIMARY KEY fields is not present in the database.
There is no conflicting row in this case. The results of invoking the sqlite3changeset_conflict() API are undefined.
CHANGESET_CONFLICT is passed as the second argument to the conflict handler while processing an INSERT change if the operation would result in duplicate primary key values.
The conflicting row in this case is the database row with the matching primary key.
If foreign key handling is enabled, and applying a changeset leaves the database in a state containing foreign key violations, the conflict handler is invoked with CHANGESET_FOREIGN_KEY as the second argument exactly once before the changeset is committed. If the conflict handler returns CHANGESET_OMIT, the changes, including those that caused the foreign key constraint violation, are committed. Or, if it returns CHANGESET_ABORT, the changeset is rolled back.
No current or conflicting row information is provided. The only function it is possible to call on the supplied sqlite3_changeset_iter handle is sqlite3changeset_fk_conflicts().
If any other constraint violation occurs while applying a change (i.e. a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is invoked with CHANGESET_CONSTRAINT as the second argument.
There is no conflicting row in this case. The results of invoking the sqlite3changeset_conflict() API are undefined.
Reference code from sqlite3:
(static) enum MkErrorE Sq3ChangesetE_FromInt(MK_I32 const value, enum Sq3ChangesetE *value_out)top return the Sq3ChangesetE from integer … → API: Sq3ChangesetE_FromInt
(static) MK_I32 Sq3ChangesetE_ToInt(enum Sq3ChangesetE value)top return the Sq3ChangesetE as integer … → API: Sq3ChangesetE_ToInt
(static) MK_STRN Sq3ChangesetE_ToString(enum Sq3ChangesetE value)top return the Sq3ChangesetE as string … → API: Sq3ChangesetE_ToString
top Checkpoint Mode Values. → API: Sq3CheckpointE
Checkpoint Mode Values …
These constants define all valid values for the "checkpoint mode" passed as the third parameter to the Sq3LiteWalCheckpointV2 () interface. See the Sq3LiteWalCheckpointV2 () documentation for details on the meaning of each of these checkpoint modes.
Reference code from sqlite3:
(static) enum MkErrorE Sq3CheckpointE_FromInt(MK_I32 const value, enum Sq3CheckpointE *value_out)top return the Sq3CheckpointE from integer … → API: Sq3CheckpointE_FromInt
(static) MK_I32 Sq3CheckpointE_ToInt(enum Sq3CheckpointE value)top return the Sq3CheckpointE as integer … → API: Sq3CheckpointE_ToInt
(static) MK_STRN Sq3CheckpointE_ToString(enum Sq3CheckpointE value)top return the Sq3CheckpointE as string … → API: Sq3CheckpointE_ToString
top Configuration Options. → API: Sq3ConfigE
Configuration Options …
These constants are the available integer configuration options that can be passed as the first argument to the sqlite3_config () interface.
Most of the configuration options for sqlite3_config() will only work if invoked prior to Sq3Initialize () or after Sq3Shutdown (). The few exceptions to this rule are called "anytime configuration options". Calling sqlite3_config () with a first argument that is not an anytime configuration option in between calls to Sq3Initialize () and Sq3Shutdown () is a no-op that returns SQ3_RESULT_MISUSE.
The set of anytime configuration options can change (by insertions and/or deletions) from one release of SQLite to the next. As of SQLite version 3.42.0, the complete set of anytime configuration options is:
New configuration options may be added in future releases of SQLite. Existing configuration options might be discontinued. Applications should check the return code from sqlite3_config () to make sure that the call worked. The sqlite3_config () interface will return a non-zero error code if a discontinued or unsupported configuration option is invoked.
There are no arguments to this option. This option sets the threading mode to Single-thread. In other words, it disables all mutexing and puts SQLite into a mode where it can only be used by a single thread. If SQLite is compiled with the SQLITE_THREADSAFE=0 compile-time option then it is not possible to change the threading mode from its default value of Single-thread and so sqlite3_config () will return SQ3_RESULT_ERROR if called with the SQ3_CONFIG_SINGLETHREAD configuration option.
There are no arguments to this option. This option sets the threading mode to Multi-thread. In other words, it disables mutexing on database connection and prepared statement objects. The application is responsible for serializing access to database connections and prepared statements. But other mutexes are enabled so that SQLite will be safe to use in a multi-threaded environment as long as no two threads attempt to use the same database connection at the same time. If SQLite is compiled with the SQLITE_THREADSAFE=0 compile-time option then it is not possible to set the Multi-thread threading mode and sqlite3_config () will return SQ3_RESULT_ERROR if called with the SQ3_CONFIG_MULTITHREAD configuration option.
There are no arguments to this option. This option sets the threading mode to Serialized. In other words, this option enables all mutexes including the recursive mutexes on database connection and prepared statement objects. In this mode (which is the default when SQLite is compiled with SQLITE_THREADSAFE=1) the SQLite library will itself serialize access to database connections and prepared statements so that the application is free to use the same database connection or the same prepared statement in different threads at the same time. If SQLite is compiled with the SQLITE_THREADSAFE=0 compile-time option then it is not possible to set the Serialized threading mode and sqlite3_config () will return SQ3_RESULT_ERROR if called with the SQ3_CONFIG_SERIALIZED configuration option.
The SQ3_CONFIG_MALLOC option takes a single argument which is a pointer to an instance of the sqlite3_mem_methods structure. The argument specifies alternative low-level memory allocation routines to be used in place of the memory allocation routines built into SQLite. SQLite makes its own private copy of the content of the sqlite3_mem_methods structure before the sqlite3_config () call returns.
The SQ3_CONFIG_GETMALLOC option takes a single argument which is a pointer to an instance of the sqlite3_mem_methods structure. The sqlite3_mem_methods structure is filled with the currently defined memory allocation routines. This option can be used to overload the default memory allocation routines with a wrapper that simulations memory allocation failure or tracks memory usage, for example.
The SQ3_CONFIG_SMALL_MALLOC option takes single argument of type int, interpreted as a boolean, which if true provides a hint to SQLite that it should avoid large memory allocations if possible. SQLite will run faster if it is free to make large memory allocations, but some application might prefer to run slower in exchange for guarantees about memory fragmentation that are possible if large allocations are avoided. This hint is normally off.
The SQ3_CONFIG_MEMSTATUS option takes single argument of type int, interpreted as a boolean, which enables or disables the collection of memory allocation statistics. When memory allocation statistics are disabled, the following SQLite interfaces become non-operational:
Memory allocation statistics are enabled by default unless SQLite is compiled with SQLITE_DEFAULT_MEMSTATUS=0 in which case memory allocation statistics are disabled by default.
The SQ3_CONFIG_PAGECACHE option specifies a memory pool that SQLite can use for the database page cache with the default page cache implementation. This configuration option is a no-op if an application-defined page cache implementation is loaded using the SQ3_CONFIG_PCACHE2. There are three arguments to SQ3_CONFIG_PAGECACHE: A pointer to 8-byte aligned memory (pMem), the size of each page cache line (sz), and the number of cache lines (N). The sz argument should be the size of the largest database page (a power of two between 512 and 65536) plus some extra bytes for each page header. The number of extra bytes needed by the page header can be determined using SQ3_CONFIG_PCACHE_HDRSZ. It is harmless, apart from the wasted memory, for the sz parameter to be larger than necessary. The pMem argument must be either a NULL pointer or a pointer to an 8-byte aligned block of memory of at least sz*N bytes, otherwise subsequent behavior is undefined. When pMem is not NULL, SQLite will strive to use the memory provided to satisfy page cache needs, falling back to Sq3Malloc () if a page cache line is larger than sz bytes or if all of the pMem buffer is exhausted. If pMem is NULL and N is non-zero, then each database connection does an initial bulk allocation for page cache memory from Sq3Malloc () sufficient for N cache lines if N is positive or of -1024*N bytes if N is negative, . If additional page cache memory is needed beyond what is provided by the initial allocation, then SQLite goes to Sq3Malloc () separately for each additional cache line.
The SQ3_CONFIG_HEAP option specifies a static memory buffer that SQLite will use for all of its dynamic memory allocation needs beyond those provided for by SQ3_CONFIG_PAGECACHE. The SQ3_CONFIG_HEAP option is only available if SQLite is compiled with either SQLITE_ENABLE_MEMSYS3 or SQLITE_ENABLE_MEMSYS5 and returns SQ3_RESULT_ERROR if invoked otherwise. There are three arguments to SQ3_CONFIG_HEAP: An 8-byte aligned pointer to the memory, the number of bytes in the memory buffer, and the minimum allocation size. If the first pointer (the memory pointer) is NULL, then SQLite reverts to using its default memory allocator (the system malloc() implementation), undoing any prior invocation of SQ3_CONFIG_MALLOC. If the memory pointer is not NULL then the alternative memory allocator is engaged to handle all of SQLites memory allocation needs. The first pointer (the memory pointer) must be aligned to an 8-byte boundary or subsequent behavior of SQLite will be undefined. The minimum allocation size is capped at 2**12. Reasonable values for the minimum allocation size are 2**5 through 2**8.
The SQ3_CONFIG_MUTEX option takes a single argument which is a pointer to an instance of the sqlite3_mutex_methods structure. The argument specifies alternative low-level mutex routines to be used in place the mutex routines built into SQLite. SQLite makes a copy of the content of the sqlite3_mutex_methods structure before the call to sqlite3_config () returns. If SQLite is compiled with the SQLITE_THREADSAFE=0 compile-time option then the entire mutexing subsystem is omitted from the build and hence calls to sqlite3_config () with the SQ3_CONFIG_MUTEX configuration option will return SQ3_RESULT_ERROR.
The SQ3_CONFIG_GETMUTEX option takes a single argument which is a pointer to an instance of the sqlite3_mutex_methods structure. The sqlite3_mutex_methods structure is filled with the currently defined mutex routines. This option can be used to overload the default mutex allocation routines with a wrapper used to track mutex usage for performance profiling or testing, for example. If SQLite is compiled with the SQLITE_THREADSAFE=0 compile-time option then the entire mutexing subsystem is omitted from the build and hence calls to sqlite3_config () with the SQ3_CONFIG_GETMUTEX configuration option will return SQ3_RESULT_ERROR.
The SQ3_CONFIG_LOOKASIDE option takes two arguments that determine the default size of lookaside memory on each database connection. The first argument is the size of each lookaside buffer slot and the second is the number of slots allocated to each database connection. SQ3_CONFIG_LOOKASIDE sets the default lookaside size. The SQ3_DBCONFIG_LOOKASIDE option to sqlite3_db_config () can be used to change the lookaside configuration on individual connections.
The SQ3_CONFIG_PCACHE2 option takes a single argument which is a pointer to an sqlite3_pcache_methods2 object. This object specifies the interface to a custom page cache implementation. SQLite makes a copy of the sqlite3_pcache_methods2 object.
The SQ3_CONFIG_GETPCACHE2 option takes a single argument which is a pointer to an sqlite3_pcache_methods2 object. SQLite copies of the current page cache implementation into that object.
The SQ3_CONFIG_LOG option is used to configure the SQLite global error log. (The SQ3_CONFIG_LOG option takes two arguments: a pointer to a function with a call signature of void(*)(void*,int,const char*), and a pointer to void. If the function pointer is not NULL, it is invoked by sqlite3_log () to process each logging event. If the function pointer is NULL, the sqlite3_log () interface becomes a no-op. The void pointer that is the second argument to SQ3_CONFIG_LOG is passed through as the first parameter to the application-defined logger function whenever that function is invoked. The second parameter to the logger function is a copy of the first parameter to the corresponding sqlite3_log () call and is intended to be a result code or an extended result code. The third parameter passed to the logger is log message after formatting via sqlite3_snprintf (). The SQLite logging interface is not reentrant; the logger function supplied by the application must not invoke any SQLite interface. In a multi-threaded application, the application-defined logger function must be threadsafe.
The SQ3_CONFIG_URI option takes a single argument of type int. If non-zero, then URI handling is globally enabled. If the parameter is zero, then URI handling is globally disabled. If URI handling is globally enabled, all filenames passed to sqlite3_open (), Sq3LiteOpenV2 (), sqlite3_open16 () or specified as part of ATTACH commands are interpreted as URIs, regardless of whether or not the SQ3_OPEN_URI flag is set when the database connection is opened. If it is globally disabled, filenames are only interpreted as URIs if the SQ3_OPEN_URI flag is set when the database connection is opened. By default, URI handling is globally disabled. The default value may be changed by compiling with the SQLITE_USE_URI symbol defined.
The SQ3_CONFIG_COVERING_INDEX_SCAN option takes a single integer argument which is interpreted as a boolean in order to enable or disable the use of covering indices for full table scans in the query optimizer. The default setting is determined by the SQLITE_ALLOW_COVERING_INDEX_SCAN compile-time option, or is "on" if that compile-time option is omitted. The ability to disable the use of covering indices for full table scans is because some incorrectly coded legacy applications might malfunction when the optimization is enabled. Providing the ability to disable the optimization allows the older, buggy application code to work without change even with newer versions of SQLite.
These options are obsolete and should not be used by new code. They are retained for backwards compatibility but are now no-ops.
This option is only available if sqlite is compiled with the SQLITE_ENABLE_SQLLOG pre-processor macro defined. The first argument should be a pointer to a function of type void(*)(void*,Sq3LiteC*,const char*, int). The second should be of type (void*). The callback is invoked by the library in three separate circumstances, identified by the value passed as the fourth parameter. If the fourth parameter is 0, then the database connection passed as the second argument has just been opened. The third argument points to a buffer containing the name of the main database file. If the fourth parameter is 1, then the SQL statement that the third parameter points to has just been executed. Or, if the fourth parameter is 2, then the connection being passed as the second parameter is being closed. The third parameter is passed NULL In this case. An example of using this configuration option can be seen in the "test_sqllog.c" source file in the canonical SQLite source tree.
SQ3_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values that are the default mmap size limit (the default setting for PRAGMA mmap_size) and the maximum allowed mmap size limit. The default setting can be overridden by each database connection using either the PRAGMA mmap_size command, or by using the SQ3_FCNTL_MMAP_SIZE file control. The maximum allowed mmap size will be silently truncated if necessary so that it does not exceed the compile-time maximum mmap size set by the SQLITE_MAX_MMAP_SIZE compile-time option. If either argument to this option is negative, then that argument is changed to its compile-time default.
The SQ3_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is compiled for Windows with the SQLITE_WIN32_MALLOC pre-processor macro defined. SQ3_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value that specifies the maximum size of the created heap.
The SQ3_CONFIG_PCACHE_HDRSZ option takes a single parameter which is a pointer to an integer and writes into that integer the number of extra bytes per page required for each page in SQ3_CONFIG_PAGECACHE. The amount of extra space required can change depending on the compiler, target platform, and SQLite version.
The SQ3_CONFIG_PMASZ option takes a single parameter which is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded sorter to that integer. The default minimum PMA Size is set by the SQLITE_SORTER_PMASZ compile-time option. New threads are launched to help with sort operations when multithreaded sorting is enabled (using the PRAGMA threads command) and the amount of content to be sorted exceeds the page size times the minimum of the PRAGMA cache_size setting and this value.
The SQ3_CONFIG_STMTJRNL_SPILL option takes a single parameter which becomes the statement journal spill-to-disk threshold. Statement journals are held in memory until their size (in bytes) exceeds this threshold, at which point they are written to disk. Or if the threshold is -1, statement journals are always held exclusively in memory. Since many statement journals never become large, setting the spill threshold to a value such as 64KiB can greatly reduce the amount of I/O required to support statement rollback. The default value for this setting is controlled by the SQLITE_STMTJRNL_SPILL compile-time option.
The SQ3_CONFIG_SORTERREF_SIZE option accepts a single parameter of type (int) - the new value of the sorter-reference size threshold. Usually, when SQLite uses an external sort to order records according to an ORDER BY clause, all fields required by the caller are present in the sorted records. However, if SQLite determines based on the declared type of a table column that its values are likely to be very large - larger than the configured sorter-reference size threshold - then a reference is stored in each sorted record and the required column values loaded from the database as records are returned in sorted order. The default value for this option is to never use this optimization. Specifying a negative value for this option restores the default behavior. This option is only available if SQLite is compiled with the SQLITE_ENABLE_SORTER_REFERENCES compile-time option.
Reference code from sqlite3:
(static) enum MkErrorE Sq3ConfigE_FromInt(MK_I32 const value, enum Sq3ConfigE *value_out)top return the Sq3ConfigE from integer … → API: Sq3ConfigE_FromInt
(static) MK_I32 Sq3ConfigE_ToInt(enum Sq3ConfigE value)top return the Sq3ConfigE as integer … → API: Sq3ConfigE_ToInt
(static) MK_STRN Sq3ConfigE_ToString(enum Sq3ConfigE value)top return the Sq3ConfigE as string … → API: Sq3ConfigE_ToString
top Conflict resolution modes. → API: Sq3ConflictResolutionE
Conflict resolution modes …
These constants are returned by Sq3LiteVtabOnConflict () to inform a virtual table implementation what the ON CONFLICT mode is for the SQL statement being evaluated.
Note that the SQ3_AUTHRETURN_IGNORE constant is also used as a potential return value from the Sq3LiteSetAuthorizer () callback and that SQ3_RESULT_ABORT is also a result code.
Reference code from sqlite3:
(static) enum MkErrorE Sq3ConflictResolutionE_FromInt(MK_I32 const value, enum Sq3ConflictResolutionE *value_out)top return the Sq3ConflictResolutionE from integer … → API: Sq3ConflictResolutionE_FromInt
(static) MK_I32 Sq3ConflictResolutionE_ToInt(enum Sq3ConflictResolutionE value)top return the Sq3ConflictResolutionE as integer … → API: Sq3ConflictResolutionE_ToInt
(static) MK_STRN Sq3ConflictResolutionE_ToString(enum Sq3ConflictResolutionE value)top return the Sq3ConflictResolutionE as string … → API: Sq3ConflictResolutionE_ToString
top Database Connection Configuration Options. → API: Sq3DbConfigE
Database Connection Configuration Options …
These constants are the available integer configuration options that can be passed as the second argument to the sqlite3_db_config () interface.
New configuration options may be added in future releases of SQLite. Existing configuration options might be discontinued. Applications should check the return code from sqlite3_db_config () to make sure that the call worked. The sqlite3_db_config () interface will return a non-zero error code if a discontinued or unsupported configuration option is invoked.
This option takes three additional arguments that determine the lookaside memory allocator configuration for the database connection. The first argument (the third parameter to sqlite3_db_config () is a pointer to a memory buffer to use for lookaside memory. The first argument after the SQ3_DBCONFIG_LOOKASIDE verb may be NULL in which case SQLite will allocate the lookaside buffer itself using Sq3Malloc (). The second argument is the size of each lookaside buffer slot. The third argument is the number of slots. The size of the buffer in the first argument must be greater than or equal to the product of the second and third arguments. The buffer must be aligned to an 8-byte boundary. If the second argument to SQ3_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally rounded down to the next smaller multiple of 8. The lookaside memory configuration for a database connection can only be changed when that connection is not currently using lookaside memory, or in other words when the "current value" returned by Sq3LiteDbStatus(D,SQ3_DBSTATUS_LOOKASIDE_USED,...) is zero. Any attempt to change the lookaside memory configuration when lookaside memory is in use leaves the configuration unchanged and returns SQ3_RESULT_BUSY.
This option is used to enable or disable the enforcement of foreign key constraints. There should be two additional arguments. The first argument is an integer which is 0 to disable FK enforcement, positive to enable FK enforcement or negative to leave FK enforcement unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether FK enforcement is off or on following this call. The second parameter may be a NULL pointer, in which case the FK enforcement setting is not reported back.
This option is used to enable or disable triggers. There should be two additional arguments. The first argument is an integer which is 0 to disable triggers, positive to enable triggers or negative to leave the setting unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether triggers are disabled or enabled following this call. The second parameter may be a NULL pointer, in which case the trigger setting is not reported back.
Originally this option disabled all triggers. However, since SQLite version 3.35.0, TEMP triggers are still allowed even if this option is off. So, in other words, this option now only disables triggers in the main database schema or in the schemas of ATTACH-ed databases.
This option is used to enable or disable views. There should be two additional arguments. The first argument is an integer which is 0 to disable views, positive to enable views or negative to leave the setting unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether views are disabled or enabled following this call. The second parameter may be a NULL pointer, in which case the view setting is not reported back.
Originally this option disabled all views. However, since SQLite version 3.35.0, TEMP views are still allowed even if this option is off. So, in other words, this option now only disables views in the main database schema or in the schemas of ATTACH-ed databases.
This option is used to enable or disable the fts3_tokenizer () function which is part of the FTS3 full-text search engine extension. There should be two additional arguments. The first argument is an integer which is 0 to disable fts3_tokenizer() or positive to enable fts3_tokenizer() or negative to leave the setting unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled following this call. The second parameter may be a NULL pointer, in which case the new setting is not reported back.
This option is used to enable or disable the Sq3LiteLoadExtension () interface independently of the load_extension () SQL function. The Sq3LiteEnableLoadExtension () API enables or disables both the C-API Sq3LiteLoadExtension () and the SQL function load_extension (). There should be two additional arguments. When the first argument to this interface is 1, then only the C-API is enabled and the SQL function remains disabled. If the first argument to this interface is 0, then both the C-API and the SQL function are disabled. If the first argument is -1, then no changes are made to state of either the C-API or the SQL function. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether Sq3LiteLoadExtension () interface is disabled or enabled following this call. The second parameter may be a NULL pointer, in which case the new setting is not reported back.
This option is used to change the name of the "main" database schema. The sole argument is a pointer to a constant UTF8 string which will become the new schema name in place of "main". SQLite does not make a copy of the new main schema name string, so the application must ensure that the argument passed into this DBCONFIG option is unchanged until after the database connection closes.
Usually, when a database in wal mode is closed or detached from a database handle, SQLite checks if this will mean that there are now no connections at all to the database. If so, it performs a checkpoint operation before closing the connection. This option may be used to override this behavior. The first parameter passed to this operation is an integer - positive to disable checkpoints-on-close, or zero (the default) to enable them, and negative to leave the setting unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether checkpoints-on-close have been disabled - 0 if they are not disabled, 1 if they are.
The SQ3_DBCONFIG_ENABLE_QPSG option activates or deactivates the query planner stability guarantee (QPSG). When the QPSG is active, a single SQL query statement will always use the same algorithm regardless of values of bound parameters. The QPSG disables some query optimizations that look at the values of bound parameters, which can make some queries slower. But the QPSG has the advantage of more predictable behavior. With the QPSG active, SQLite will always use the same query plan in the field as was used during testing in the lab. The first argument to this setting is an integer which is 0 to disable the QPSG, positive to enable QPSG, or negative to leave the setting unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether the QPSG is disabled or enabled following this call.
By default, the output of EXPLAIN QUERY PLAN commands does not include output for any operations performed by trigger programs. This option is used to set or clear (the default) a flag that governs this behavior. The first parameter passed to this operation is an integer - positive to enable output for trigger programs, or zero to disable it, or negative to leave the setting unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if it is not disabled, 1 if it is.
Set the SQ3_DBCONFIG_RESET_DATABASE flag and then run VACUUM in order to reset a database back to an empty database with no schema and no content. The following process works even for a badly corrupted database file:
Because resetting a database is destructive and irreversible, the process requires the use of this obscure API and multiple steps to help ensure that it does not happen by accident. Because this feature must be capable of resetting corrupt databases, and shutting down virtual tables may require access to that corrupt storage, the library must abandon any installed virtual tables without calling their xDestroy() methods.
The SQ3_DBCONFIG_DEFENSIVE option activates or deactivates the "defensive" flag for a database connection. When the defensive flag is enabled, language features that allow ordinary SQL to deliberately corrupt the database file are disabled. The disabled features include but are not limited to the following:
The SQ3_DBCONFIG_WRITABLE_SCHEMA option activates or deactivates the "writable_schema" flag. This has the same effect and is logically equivalent to setting PRAGMA writable_schema=ON or PRAGMA writable_schema=OFF. The first argument to this setting is an integer which is 0 to disable the writable_schema, positive to enable writable_schema, or negative to leave the setting unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether the writable_schema is enabled or disabled following this call.
The SQ3_DBCONFIG_LEGACY_ALTER_TABLE option activates or deactivates the legacy behavior of the ALTER TABLE RENAME command such it behaves as it did prior to version 3.24.0 (2018-06-04). See the "Compatibility Notice" on the ALTER TABLE RENAME documentation for additional information. This feature can also be turned on and off using the PRAGMA legacy_alter_table statement.
The SQ3_DBCONFIG_DQS_DML option activates or deactivates the legacy double-quoted string literal misfeature for DML statements only, that is DELETE, INSERT, SELECT, and UPDATE statements. The default value of this setting is determined by the -DSQLITE_DQS compile-time option.
The SQ3_DBCONFIG_DQS_DDL option activates or deactivates the legacy double-quoted string literal misfeature for DDL statements, such as CREATE TABLE and CREATE INDEX. The default value of this setting is determined by the -DSQLITE_DQS compile-time option.
The SQ3_DBCONFIG_TRUSTED_SCHEMA option tells SQLite to assume that database schemas are untainted by malicious content. When the SQ3_DBCONFIG_TRUSTED_SCHEMA option is disabled, SQLite takes additional defensive steps to protect the application from harm including:
This setting defaults to "on" for legacy compatibility, however all applications are advised to turn it off if possible. This setting can also be controlled using the PRAGMA trusted_schema statement.
The SQ3_DBCONFIG_LEGACY_FILE_FORMAT option activates or deactivates the legacy file format flag. When activated, this flag causes all newly created database file to have a schema format version number (the 4-byte integer found at offset 44 into the database header) of 1. This in turn means that the resulting database file will be readable and writable by any SQLite version back to 3.0.0 (dateof:3.0.0). Without this setting, newly created databases are generally not understandable by SQLite versions prior to 3.3.0 (dateof:3.3.0). As these words are written, there is now scarcely any need to generate database files that are compatible all the way back to version 3.0.0, and so this setting is of little practical use, but is provided so that SQLite can continue to claim the ability to generate new database files that are compatible with version 3.0.0.
Note that when the SQ3_DBCONFIG_LEGACY_FILE_FORMAT setting is on, the VACUUM command will fail with an obscure error when attempting to process a table with generated columns and a descending index. This is not considered a bug since SQLite versions 3.3.0 and earlier do not support either generated columns or descending indexes.
The SQ3_DBCONFIG_STMT_SCANSTATUS option is only useful in SQLITE_ENABLE_STMT_SCANSTATUS builds. In this case, it sets or clears a flag that enables collection of the sqlite3_stmt_scanstatus_v2() statistics. For statistics to be collected, the flag must be set on the database handle both when the SQL statement is prepared and when it is stepped. The flag is set (collection of statistics is enabled) by default. This option takes two arguments: an integer and a pointer to an integer.. The first argument is 1, 0, or -1 to enable, disable, or leave unchanged the statement scanstatus option. If the second argument is not NULL, then the value of the statement scanstatus setting after processing the first argument is written into the integer that the second argument points to.
Reference code from sqlite3:
(static) enum MkErrorE Sq3DbConfigE_FromInt(MK_I32 const value, enum Sq3DbConfigE *value_out)top return the Sq3DbConfigE from integer … → API: Sq3DbConfigE_FromInt
(static) MK_I32 Sq3DbConfigE_ToInt(enum Sq3DbConfigE value)top return the Sq3DbConfigE as integer … → API: Sq3DbConfigE_ToInt
(static) MK_STRN Sq3DbConfigE_ToString(enum Sq3DbConfigE value)top return the Sq3DbConfigE as string … → API: Sq3DbConfigE_ToString
top Status Parameters for database connections. → API: Sq3DbStatusE
Status Parameters for database connections …
These constants are the available integer "verbs" that can be passed as the second argument to the Sq3LiteDbStatus () interface.
New verbs may be added in future releases of SQLite. Existing verbs might be discontinued. Applications should check the return code from Sq3LiteDbStatus () to make sure that the call worked. The Sq3LiteDbStatus () interface will return a non-zero error code if a discontinued or unsupported verb is invoked.
This parameter returns the number of lookaside memory slots currently checked out.
This parameter returns the number of malloc attempts that were satisfied using lookaside memory. Only the high-water value is meaningful; the current value is always zero.
This parameter returns the number malloc attempts that might have been satisfied using lookaside memory but failed due to the amount of memory requested being larger than the lookaside slot size. Only the high-water value is meaningful; the current value is always zero.
This parameter returns the number malloc attempts that might have been satisfied using lookaside memory but failed due to all lookaside memory already being in use. Only the high-water value is meaningful; the current value is always zero.
This parameter returns the approximate number of bytes of heap memory used by all pager caches associated with the database connection. The highwater mark associated with SQ3_DBSTATUS_CACHE_USED is always 0.
This parameter is similar to DBSTATUS_CACHE_USED, except that if a pager cache is shared between two or more connections the bytes of heap memory used by that pager cache is divided evenly between the attached connections. In other words, if none of the pager caches associated with the database connection are shared, this request returns the same value as DBSTATUS_CACHE_USED. Or, if one or more or the pager caches are shared, the value returned by this call will be smaller than that returned by DBSTATUS_CACHE_USED. The highwater mark associated with SQ3_DBSTATUS_CACHE_USED_SHARED is always 0.
This parameter returns the approximate number of bytes of heap memory used to store the schema for all databases associated with the connection - main, temp, and any ATTACH-ed databases. The full amount of memory used by the schemas is reported, even if the schema memory is shared with other database connections due to shared cache mode being enabled. The highwater mark associated with SQ3_DBSTATUS_SCHEMA_USED is always 0.
This parameter returns the approximate number of bytes of heap and lookaside memory used by all prepared statements associated with the database connection. The highwater mark associated with SQ3_DBSTATUS_STMT_USED is always 0.
This parameter returns the number of pager cache hits that have occurred. The highwater mark associated with SQ3_DBSTATUS_CACHE_HIT is always 0.
This parameter returns the number of pager cache misses that have occurred. The highwater mark associated with SQ3_DBSTATUS_CACHE_MISS is always 0.
This parameter returns the number of dirty cache entries that have been written to disk. Specifically, the number of pages written to the wal file in wal mode databases, or the number of pages written to the database file in rollback mode databases. Any pages written as part of transaction rollback or database recovery operations are not included. If an IO or other error occurs while writing a page to disk, the effect on subsequent SQ3_DBSTATUS_CACHE_WRITE requests is undefined. The highwater mark associated with SQ3_DBSTATUS_CACHE_WRITE is always 0.
This parameter returns the number of dirty cache entries that have been written to disk in the middle of a transaction due to the page cache overflowing. Transactions are more efficient if they are written to disk all at once. When pages spill mid-transaction, that introduces additional overhead. This parameter can be used help identify inefficiencies that can be resolved by increasing the cache size.
Reference code from sqlite3:
(static) enum MkErrorE Sq3DbStatusE_FromInt(MK_I32 const value, enum Sq3DbStatusE *value_out)top return the Sq3DbStatusE from integer … → API: Sq3DbStatusE_FromInt
(static) MK_I32 Sq3DbStatusE_ToInt(enum Sq3DbStatusE value)top return the Sq3DbStatusE as integer … → API: Sq3DbStatusE_ToInt
(static) MK_STRN Sq3DbStatusE_ToString(enum Sq3DbStatusE value)top return the Sq3DbStatusE as string … → API: Sq3DbStatusE_ToString
top Flags for sqlite3_deserialize() → API: Sq3DeSerializeEF
Flags for sqlite3_deserialize() …
The following are allowed values for 6th argument (the F argument) to the Sq3LiteDeserialize (D,S,P,N,M,F) interface.
The SQ3_DESERIALIZE_FREEONCLOSE means that the database serialization in the P argument is held in memory obtained from Sq3Malloc64 () and that SQLite should take ownership of this memory and automatically free it when it has finished using it. Without this flag, the caller is responsible for freeing any dynamically allocated memory.
The SQ3_DESERIALIZE_RESIZEABLE flag means that SQLite is allowed to grow the size of the database using calls to Sq3Realloc64 (). This flag should only be used if SQ3_DESERIALIZE_FREEONCLOSE is also used. Without this flag, the deserialized database cannot increase in size beyond the number of bytes specified by the M parameter.
The SQ3_DESERIALIZE_READONLY flag means that the deserialized database should be treated as read-only.
Reference code from sqlite3:
(static) enum MkErrorE Sq3DeSerializeEF_FromInt(MK_I32 const value, enum Sq3DeSerializeEF *value_out)top return the Sq3DeSerializeEF from integer … → API: Sq3DeSerializeEF_FromInt
(static) MK_I32 Sq3DeSerializeEF_ToInt(enum Sq3DeSerializeEF value)top return the Sq3DeSerializeEF as integer … → API: Sq3DeSerializeEF_ToInt
(static) MK_STRN Sq3DeSerializeEF_ToString(enum Sq3DeSerializeEF value)top return the Sq3DeSerializeEF as string … → API: Sq3DeSerializeEF_ToString
top Result Codes. → API: Sq3ErrorE
Result Codes …
Many SQLite functions return an integer result code from the set shown here in order to indicate success or failure.
New error codes may be added in future versions of SQLite.
See also: extended result code definitions
Reference code from sqlite3:
(static) enum MkErrorE Sq3ErrorE_FromInt(MK_I32 const value, enum Sq3ErrorE *value_out)top return the Sq3ErrorE from integer … → API: Sq3ErrorE_FromInt
(static) MK_I32 Sq3ErrorE_ToInt(enum Sq3ErrorE value)top return the Sq3ErrorE as integer … → API: Sq3ErrorE_ToInt
(static) MK_STRN Sq3ErrorE_ToString(enum Sq3ErrorE value)top return the Sq3ErrorE as string … → API: Sq3ErrorE_ToString
top Extended Result Codes. → API: Sq3ExtendetResultCodesE
Extended Result Codes …
In its default configuration, SQLite API routines return one of 30 integer result codes. However, experience has shown that many of these result codes are too coarse-grained. They do not provide as much information about problems as programmers might like. In an effort to address this, newer versions of SQLite (version 3.3.8 dateof:3.3.8 and later) include support for additional result codes that provide more detailed information about errors. These extended result codes are enabled or disabled on a per database connection basis using the Sq3LiteExtendedResultCodes () API. Or, the extended code for the most recent error can be obtained using Sq3LiteExtendetErrCode ().
Reference code from sqlite3:
(static) enum MkErrorE Sq3ExtendetResultCodesE_FromInt(MK_I32 const value, enum Sq3ExtendetResultCodesE *value_out)top return the Sq3ExtendetResultCodesE from integer … → API: Sq3ExtendetResultCodesE_FromInt
(static) MK_I32 Sq3ExtendetResultCodesE_ToInt(enum Sq3ExtendetResultCodesE value)top return the Sq3ExtendetResultCodesE as integer … → API: Sq3ExtendetResultCodesE_ToInt
(static) MK_STRN Sq3ExtendetResultCodesE_ToString(enum Sq3ExtendetResultCodesE value)top return the Sq3ExtendetResultCodesE as string … → API: Sq3ExtendetResultCodesE_ToString
top Standard File Control Opcodes. → API: Sq3FcntlE
Standard File Control Opcodes …
These integer constants are opcodes for the xFileControl method of the sqlite3_io_methods object and for the Sq3LiteFileControl () interface.
The SQ3_FCNTL_LOCKSTATE opcode is used for debugging. This opcode causes the xFileControl method to write the current state of the lock (one of SQ3_LOCK_NONE, SQ3_LOCK_SHARED, SQ3_LOCK_RESERVED, SQ3_LOCK_PENDING, or SQ3_LOCK_EXCLUSIVE) into an integer that the pArg argument points to. This capability is only available if SQLite is compiled with SQLITE_DEBUG.
The SQ3_FCNTL_SIZE_HINT opcode is used by SQLite to give the VFS layer a hint of how large the database file will grow to be during the current transaction. This hint is not guaranteed to be accurate but it is often close. The underlying VFS might choose to preallocate database file space based on this hint in order to help writes to the database file run faster.
The SQ3_FCNTL_SIZE_LIMIT opcode is used by in-memory VFS that implements Sq3LiteDeserialize () to set an upper bound on the size of the in-memory database. The argument is a pointer to a sqlite3_int64. If the integer pointed to is negative, then it is filled in with the current limit. Otherwise the limit is set to the larger of the value of the integer pointed to and the current database size. The integer pointed to is set to the new limit.
The SQ3_FCNTL_CHUNK_SIZE opcode is used to request that the VFS extends and truncates the database file in chunks of a size specified by the user. The fourth argument to Sq3LiteFileControl () should point to an integer (type int) containing the new chunk-size to use for the nominated database. Allocating database file space in large chunks (say 1MB at a time), may reduce file-system fragmentation and improve performance on some systems.
The SQ3_FCNTL_FILE_POINTER opcode is used to obtain a pointer to the Sq3FileC object associated with a particular database connection. See also SQ3_FCNTL_JOURNAL_POINTER.
The SQ3_FCNTL_JOURNAL_POINTER opcode is used to obtain a pointer to the Sq3FileC object associated with the journal file (either the rollback journal or the write-ahead log) for a particular database connection. See also SQ3_FCNTL_FILE_POINTER.
The SQ3_FCNTL_SYNC opcode is generated internally by SQLite and sent to the VFS immediately before the xSync method is invoked on a database file descriptor. Or, if the xSync method is not invoked because the user has configured SQLite with PRAGMA synchronous=OFF it is invoked in place of the xSync method. In most cases, the pointer argument passed with this file-control is NULL. However, if the database file is being synced as part of a multi-database commit, the argument points to a nul-terminated string containing the transactions super-journal file name. VFSes that do not need this signal should silently ignore this opcode. Applications should not call Sq3LiteFileControl () with this opcode as doing so may disrupt the operation of the specialized VFSes that do require it.
The SQ3_FCNTL_COMMIT_PHASETWO opcode is generated internally by SQLite and sent to the VFS after a transaction has been committed immediately but before the database is unlocked. VFSes that do not need this signal should silently ignore this opcode. Applications should not call Sq3LiteFileControl () with this opcode as doing so may disrupt the operation of the specialized VFSes that do require it.
The SQ3_FCNTL_WIN32_AV_RETRY opcode is used to configure automatic retry counts and intervals for certain disk I/O operations for the windows VFS in order to provide robustness in the presence of anti-virus programs. By default, the windows VFS will retry file read, file write, and file delete operations up to 10 times, with a delay of 25 milliseconds before the first retry and with the delay increasing by an additional 25 milliseconds with each subsequent retry. This opcode allows these two values (10 retries and 25 milliseconds of delay) to be adjusted. The values are changed for all database connections within the same process. The argument is a pointer to an array of two integers where the first integer is the new retry count and the second integer is the delay. If either integer is negative, then the setting is not changed but instead the prior value of that setting is written into the array entry, allowing the current retry settings to be interrogated. The zDbName parameter is ignored.
The SQ3_FCNTL_PERSIST_WAL opcode is used to set or query the persistent Write Ahead Log setting. By default, the auxiliary write ahead log (WAL file) and shared memory files used for transaction control are automatically deleted when the latest connection to the database closes. Setting persistent WAL mode causes those files to persist after close. Persisting the files is useful when other processes that do not have write permission on the directory containing the database file want to read the database file, as the WAL and shared memory files must exist in order for the database to be readable. The fourth parameter to Sq3LiteFileControl () for this opcode should be a pointer to an integer. That integer is 0 to disable persistent WAL mode or 1 to enable persistent WAL mode. If the integer is -1, then it is overwritten with the current WAL persistence setting.
The SQ3_FCNTL_POWERSAFE_OVERWRITE opcode is used to set or query the persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting determines the SQ3_IOCAP_POWERSAFE_OVERWRITE bit of the xDeviceCharacteristics methods. The fourth parameter to Sq3LiteFileControl () for this opcode should be a pointer to an integer. That integer is 0 to disable zero-damage mode or 1 to enable zero-damage mode. If the integer is -1, then it is overwritten with the current zero-damage mode setting.
The SQ3_FCNTL_OVERWRITE opcode is invoked by SQLite after opening a write transaction to indicate that, unless it is rolled back for some reason, the entire database file will be overwritten by the current transaction. This is used by VACUUM operations.
The SQ3_FCNTL_VFSNAME opcode can be used to obtain the names of all VFSes in the VFS stack. The names are of all VFS shims and the final bottom-level VFS are written into memory obtained from Sq3Malloc () and the result is stored in the char* variable that the fourth parameter of Sq3LiteFileControl () points to. The caller is responsible for freeing the memory when done. As with all file-control actions, there is no guarantee that this will actually do anything. Callers should initialize the char* variable to a NULL pointer in case this file-control is not implemented. This file-control is intended for diagnostic use only.
The SQ3_FCNTL_VFS_POINTER opcode finds a pointer to the top-level VFSes currently in use. The argument X in Sq3LiteFileControl(db,SQ3_FCNTL_VFS_POINTER,X) must be of type "<a href="https://www.sqlite.org/c3ref/vfs.html">sqlite3_vfs</a> **". This opcodes will set *X to a pointer to the top-level VFS. When there are multiple VFS shims in the stack, this opcode finds the upper-most shim only.
Whenever a PRAGMA statement is parsed, an SQ3_FCNTL_PRAGMA file control is sent to the open Sq3FileC object corresponding to the database file to which the pragma statement refers. The argument to the SQ3_FCNTL_PRAGMA file control is an array of pointers to strings (char**) in which the second element of the array is the name of the pragma and the third element is the argument to the pragma or NULL if the pragma has no argument. The handler for an SQ3_FCNTL_PRAGMA file control can optionally make the first element of the char** argument point to a string obtained from sqlite3_mprintf () or the equivalent and that string will become the result of the pragma or the error message if the pragma fails. If the SQ3_FCNTL_PRAGMA file control returns SQ3_RESULT_NOTFOUND, then normal PRAGMA processing continues. If the SQ3_FCNTL_PRAGMA file control returns SQ3_RESULT_OK, then the parser assumes that the VFS has handled the PRAGMA itself and the parser generates a no-op prepared statement if result string is NULL, or that returns a copy of the result string if the string is non-NULL. If the SQ3_FCNTL_PRAGMA file control returns any result code other than SQ3_RESULT_OK or SQ3_RESULT_NOTFOUND, that means that the VFS encountered an error while handling the PRAGMA and the compilation of the PRAGMA fails with an error. The SQ3_FCNTL_PRAGMA file control occurs at the beginning of pragma statement analysis and so it is able to override built-in PRAGMA statements.
The SQ3_FCNTL_BUSYHANDLER file-control may be invoked by SQLite on the database file handle shortly after it is opened in order to provide a custom VFS with access to the connection's busy-handler callback. The argument is of type (void**)
Applications can invoke the SQ3_FCNTL_TEMPFILENAME file-control to have SQLite generate a temporary filename using the same algorithm that is followed to generate temporary filenames for TEMP tables and other internal uses. The argument should be a char** which will be filled with the filename written into memory obtained from Sq3Malloc (). The caller should invoke Sq3Free () on the result to avoid a memory leak.
The SQ3_FCNTL_MMAP_SIZE file control is used to query or set the maximum number of bytes that will be used for memory-mapped I/O. The argument is a pointer to a value of type sqlite3_int64 that is an advisory maximum number of bytes in the file to memory map. The pointer is overwritten with the old value. The limit is not changed if the value originally pointed to is negative, and so the current limit can be queried by passing in a pointer to a negative number. This file-control is used internally to implement PRAGMA mmap_size.
The SQ3_FCNTL_TRACE file control provides advisory information to the VFS about what the higher layers of the SQLite stack are doing. This file control is used by some VFS activity tracing shims. The argument is a zero-terminated string. Higher layers in the SQLite stack may generate instances of this file control if the SQLITE_USE_FCNTL_TRACE compile-time option is enabled.
The SQ3_FCNTL_HAS_MOVED file control interprets its argument as a pointer to an integer and it writes a boolean into that integer depending on whether or not the file has been renamed, moved, or deleted since it was first opened.
The SQ3_FCNTL_WIN32_GET_HANDLE opcode can be used to obtain the underlying native file handle associated with a file handle. This file control interprets its argument as a pointer to a native file handle and writes the resulting value there.
The SQ3_FCNTL_WIN32_SET_HANDLE opcode is used for debugging. This opcode causes the xFileControl method to swap the file handle with the one pointed to by the pArg argument. This capability is used during testing and only needs to be supported when SQLITE_TEST is defined.
The SQ3_FCNTL_WAL_BLOCK is a signal to the VFS layer that it might be advantageous to block on the next WAL lock if the lock is not immediately available. The WAL subsystem issues this signal during rare circumstances in order to fix a problem with priority inversion. Applications should not use this file-control.
The SQ3_FCNTL_ZIPVFS opcode is implemented by zipvfs only. All other VFS should return SQ3_RESULT_NOTFOUND for this opcode.
The SQ3_FCNTL_RBU opcode is implemented by the special VFS used by the RBU extension only. All other VFS should return SQ3_RESULT_NOTFOUND for this opcode.
If the SQ3_FCNTL_BEGIN_ATOMIC_WRITE opcode returns SQ3_RESULT_OK, then the file descriptor is placed in "batch write mode", which means all subsequent write operations will be deferred and done atomically at the next SQ3_FCNTL_COMMIT_ATOMIC_WRITE. Systems that do not support batch atomic writes will return SQ3_RESULT_NOTFOUND. Following a successful SQ3_FCNTL_BEGIN_ATOMIC_WRITE and prior to the closing SQ3_FCNTL_COMMIT_ATOMIC_WRITE or SQ3_FCNTL_ROLLBACK_ATOMIC_WRITE, SQLite will make no VFS interface calls on the same Sq3FileC file descriptor except for calls to the xWrite method and the xFileControl method with SQ3_FCNTL_SIZE_HINT.
The SQ3_FCNTL_COMMIT_ATOMIC_WRITE opcode causes all write operations since the previous successful call to SQ3_FCNTL_BEGIN_ATOMIC_WRITE to be performed atomically. This file control returns SQ3_RESULT_OK if and only if the writes were all performed successfully and have been committed to persistent storage. Regardless of whether or not it is successful, this file control takes the file descriptor out of batch write mode so that all subsequent write operations are independent. SQLite will never invoke SQ3_FCNTL_COMMIT_ATOMIC_WRITE without a prior successful call to SQ3_FCNTL_BEGIN_ATOMIC_WRITE.
The SQ3_FCNTL_ROLLBACK_ATOMIC_WRITE opcode causes all write operations since the previous successful call to SQ3_FCNTL_BEGIN_ATOMIC_WRITE to be rolled back. This file control takes the file descriptor out of batch write mode so that all subsequent write operations are independent. SQLite will never invoke SQ3_FCNTL_ROLLBACK_ATOMIC_WRITE without a prior successful call to SQ3_FCNTL_BEGIN_ATOMIC_WRITE.
The SQ3_FCNTL_LOCK_TIMEOUT opcode is used to configure a VFS to block for up to M milliseconds before failing when attempting to obtain a file lock using the xLock or xShmLock methods of the VFS. The parameter is a pointer to a 32-bit signed integer that contains the value that M is to be set to. Before returning, the 32-bit signed integer is overwritten with the previous value of M.
The SQ3_FCNTL_DATA_VERSION opcode is used to detect changes to a database file. The argument is a pointer to a 32-bit unsigned integer. The "data version" for the pager is written into the pointer. The "data version" changes whenever any change occurs to the corresponding database file, either through SQL statements on the same database connection or through transactions committed by separate database connections possibly in other processes. The Sq3LiteTotalChanges () interface can be used to find if any database on the connection has changed, but that interface responds to changes on TEMP as well as MAIN and does not provide a mechanism to detect changes to MAIN only. Also, the Sq3LiteTotalChanges () interface responds to internal changes only and omits changes made by other database connections. The PRAGMA data_version command provides a mechanism to detect changes to a single attached database that occur due to other database connections, but omits changes implemented by the database connection on which it is called. This file control is the only mechanism to detect changes that happen either internally or externally and that are associated with a particular attached database.
The SQ3_FCNTL_CKPT_START opcode is invoked from within a checkpoint in wal mode before the client starts to copy pages from the wal file to the database file.
The SQ3_FCNTL_CKPT_DONE opcode is invoked from within a checkpoint in wal mode after the client has finished copying pages from the wal file to the database file, but before the *-shm file is updated to record the fact that the pages have been checkpointed.
The EXPERIMENTAL SQ3_FCNTL_EXTERNAL_READER opcode is used to detect whether or not there is a database client in another process with a wal-mode transaction open on the database or not. It is only available on unix.The (void*) argument passed with this file-control should be a pointer to a value of type (int). The integer value is set to 1 if the database is a wal mode database and there exists at least one client in another process that currently has an SQL transaction open on the database. It is set to 0 if the database is not a wal-mode db, or if there is no such connection in any other process. This opcode cannot be used to detect transactions opened by clients within the current process, only within other processes.
The SQ3_FCNTL_CKSM_FILE opcode is for use internally by the checksum VFS shim only.
Reference code from sqlite3:
(static) enum MkErrorE Sq3FcntlE_FromInt(MK_I32 const value, enum Sq3FcntlE *value_out)top return the Sq3FcntlE from integer … → API: Sq3FcntlE_FromInt
(static) MK_I32 Sq3FcntlE_ToInt(enum Sq3FcntlE value)top return the Sq3FcntlE as integer … → API: Sq3FcntlE_ToInt
(static) MK_STRN Sq3FcntlE_ToString(enum Sq3FcntlE value)top return the Sq3FcntlE as string … → API: Sq3FcntlE_ToString
top Function Flags. → API: Sq3FunctionEF
Function Flags …
These constants may be ORed together with the preferred text encoding as the fourth argument to sqlite3_create_function (), sqlite3_create_function16 (), or Sq3LiteCreateFunctionV2 ().
The SQ3_FUNCTION_DETERMINISTIC flag means that the new function always gives the same output when the input parameters are the same. The abs() function is deterministic, for example, but randomblob() is not. Functions must be deterministic in order to be used in certain contexts such as with the WHERE clause of partial indexes or in generated columns. SQLite might also optimize deterministic functions by factoring them out of inner loops.
The SQ3_FUNCTION_DIRECTONLY flag means that the function may only be invoked from top-level SQL, and cannot be used in VIEWs or TRIGGERs nor in schema structures such as CHECK constraints, DEFAULT clauses, expression indexes, partial indexes, or generated columns.
The SQ3_FUNCTION_DIRECTONLY flag is recommended for any application-defined SQL function that has side-effects or that could potentially leak sensitive information. This will prevent attacks in which an application is tricked into using a database file that has had its schema surreptitiously modified to invoke the application-defined function in ways that are harmful.
Some people say it is good practice to set SQ3_FUNCTION_DIRECTONLY on all application-defined SQL functions, regardless of whether or not they are security sensitive, as doing so prevents those functions from being used inside of the database schema, and thus ensures that the database can be inspected and modified using generic tools (such as the CLI) that do not have access to the application-defined functions.
The SQ3_FUNCTION_INNOCUOUS flag means that the function is unlikely to cause problems even if misused. An innocuous function should have no side effects and should not depend on any values other than its input parameters. The abs() function is an example of an innocuous function. The load_extension() SQL function is not innocuous because of its side effects.
SQ3_FUNCTION_INNOCUOUS is similar to SQ3_FUNCTION_DETERMINISTIC, but is not exactly the same. The random() function is an example of a function that is innocuous but not deterministic.
Some heightened security settings (SQ3_DBCONFIG_TRUSTED_SCHEMA and PRAGMA trusted_schema=OFF) disable the use of SQL functions inside views and triggers and in schema structures such as CHECK constraints, DEFAULT clauses, expression indexes, partial indexes, and generated columns unless the function is tagged with SQ3_FUNCTION_INNOCUOUS. Most built-in functions are innocuous. Developers are advised to avoid using the SQ3_FUNCTION_INNOCUOUS flag for application-defined functions unless the function has been carefully audited and found to be free of potentially security-adverse side-effects and information-leaks.
The SQ3_FUNCTION_SUBTYPE flag indicates to SQLite that a function might call Sq3ValueSubType () to inspect the sub-types of its arguments. This flag instructs SQLite to omit some corner-case optimizations that might disrupt the operation of the Sq3ValueSubType () function, causing it to return zero rather than the correct subtype(). SQL functions that invokes Sq3ValueSubType () should have this property. If the SQ3_FUNCTION_SUBTYPE property is omitted, then the return value from Sq3ValueSubType () might sometimes be zero even though a non-zero subtype was specified by the function argument expression.
Reference code from sqlite3:
(static) enum MkErrorE Sq3FunctionEF_FromInt(MK_I32 const value, enum Sq3FunctionEF *value_out)top return the Sq3FunctionEF from integer … → API: Sq3FunctionEF_FromInt
(static) MK_I32 Sq3FunctionEF_ToInt(enum Sq3FunctionEF value)top return the Sq3FunctionEF as integer … → API: Sq3FunctionEF_ToInt
(static) MK_STRN Sq3FunctionEF_ToString(enum Sq3FunctionEF value)top return the Sq3FunctionEF as string … → API: Sq3FunctionEF_ToString
top Virtual Table Constraint Operator Codes. → API: Sq3IndexConstraintEF
Virtual Table Constraint Operator Codes …
These macros define the allowed values for the sqlite3_index_info.aConstraint[].op field. Each value represents an operator that is part of a constraint term in the WHERE clause of a query that uses a virtual table.
The left-hand operand of the operator is given by the corresponding aConstraint[].iColumn field. An iColumn of -1 indicates the left-hand operand is the rowid. The SQ3_INDEX_CONSTRAINT_LIMIT and SQ3_INDEX_CONSTRAINT_OFFSET operators have no left-hand operand, and so for those operators the corresponding aConstraint[].iColumn is meaningless and should not be used.
All operator values from SQ3_INDEX_CONSTRAINT_FUNCTION through value 255 are reserved to represent functions that are overloaded by the xFindFunction method of the virtual table implementation.
The right-hand operands for each constraint might be accessible using the sqlite3_vtab_rhs_value () interface. Usually the right-hand operand is only available if it appears as a single constant literal in the input SQL. If the right-hand operand is another column or an expression (even a constant expression) or a parameter, then the sqlite3_vtab_rhs_value() probably will not be able to extract it. The SQ3_INDEX_CONSTRAINT_ISNULL and SQ3_INDEX_CONSTRAINT_ISNOTNULL operators have no right-hand operand and hence calls to sqlite3_vtab_rhs_value() for those operators will always return SQ3_RESULT_NOTFOUND.
The collating sequence to be used for comparison can be found using the sqlite3_vtab_collation () interface. For most real-world virtual tables, the collating sequence of constraints does not matter (for example because the constraints are numeric) and so the sqlite3_vtab_collation() interface is not commonly needed.
Reference code from sqlite3:
(static) enum MkErrorE Sq3IndexConstraintEF_FromInt(MK_I32 const value, enum Sq3IndexConstraintEF *value_out)top return the Sq3IndexConstraintEF from integer … → API: Sq3IndexConstraintEF_FromInt
(static) MK_I32 Sq3IndexConstraintEF_ToInt(enum Sq3IndexConstraintEF value)top return the Sq3IndexConstraintEF as integer … → API: Sq3IndexConstraintEF_ToInt
(static) MK_STRN Sq3IndexConstraintEF_ToString(enum Sq3IndexConstraintEF value)top return the Sq3IndexConstraintEF as string … → API: Sq3IndexConstraintEF_ToString
top Device Characteristics. → API: Sq3IoCapEF
Device Characteristics …
The xDeviceCharacteristics method of the sqlite3_io_methods object returns an integer which is a vector of these bit values expressing I/O characteristics of the mass storage device that holds the file that the sqlite3_io_methods refers to.
The SQ3_IOCAP_ATOMIC property means that all writes of any size are atomic. The SQ3_IOCAP_ATOMICnnn values mean that writes of blocks that are nnn bytes in size and are aligned to an address which is an integer multiple of nnn are atomic. The SQ3_IOCAP_SAFE_APPEND value means that when data is appended to a file, the data is appended first then the size of the file is extended, never the other way around. The SQ3_IOCAP_SEQUENTIAL property means that information is written to disk in the same order as calls to xWrite(). The SQ3_IOCAP_POWERSAFE_OVERWRITE property means that after reboot following a crash or power loss, the only bytes in a file that were written at the application level might have changed and that adjacent bytes, even bytes within the same sector are guaranteed to be unchanged. The SQ3_IOCAP_UNDELETABLE_WHEN_OPEN flag indicates that a file cannot be deleted when open. The SQ3_IOCAP_IMMUTABLE flag indicates that the file is on read-only media and cannot be changed even by processes with elevated privileges.
The SQ3_IOCAP_BATCH_ATOMIC property means that the underlying filesystem supports doing multiple write operations atomically when those write operations are bracketed by SQ3_FCNTL_BEGIN_ATOMIC_WRITE and SQ3_FCNTL_COMMIT_ATOMIC_WRITE.
Reference code from sqlite3:
(static) enum MkErrorE Sq3IoCapEF_FromInt(MK_I32 const value, enum Sq3IoCapEF *value_out)top return the Sq3IoCapEF from integer … → API: Sq3IoCapEF_FromInt
(static) MK_I32 Sq3IoCapEF_ToInt(enum Sq3IoCapEF value)top return the Sq3IoCapEF as integer … → API: Sq3IoCapEF_ToInt
(static) MK_STRN Sq3IoCapEF_ToString(enum Sq3IoCapEF value)top return the Sq3IoCapEF as string … → API: Sq3IoCapEF_ToString
top Run-Time Limit Categories. → API: Sq3LimitE
Run-Time Limit Categories …
These constants define various performance limits that can be lowered at run-time using Sq3LiteLimit (). The synopsis of the meanings of the various limits is shown below. Additional information is available at Limits in SQLite.
The maximum size of any string or BLOB or table row, in bytes.
The maximum number of columns in a table definition or in the result set of a SELECT or the maximum number of columns in an index or in an ORDER BY or GROUP BY clause.
The maximum number of instructions in a virtual machine program used to implement an SQL statement. If Sq3StmtPrepareV2 () or the equivalent tries to allocate space for more than this many opcodes in a single prepared statement, an SQ3_RESULT_NOMEM error is returned.
The maximum number of attached databases.
The maximum length of the pattern argument to the LIKE or GLOB operators.
The maximum index number of any parameter in an SQL statement.
Reference code from sqlite3:
(static) enum MkErrorE Sq3LimitE_FromInt(MK_I32 const value, enum Sq3LimitE *value_out)top return the Sq3LimitE from integer … → API: Sq3LimitE_FromInt
(static) MK_I32 Sq3LimitE_ToInt(enum Sq3LimitE value)top return the Sq3LimitE as integer … → API: Sq3LimitE_ToInt
(static) MK_STRN Sq3LimitE_ToString(enum Sq3LimitE value)top return the Sq3LimitE as string … → API: Sq3LimitE_ToString
top File Locking Levels. → API: Sq3LockE
File Locking Levels …
SQLite uses one of these integer values as the second argument to calls it makes to the xLock() and xUnlock() methods of an sqlite3_io_methods object. These values are ordered from lest restrictive to most restrictive.
The argument to xLock() is always SHARED or higher. The argument to xUnlock is either SHARED or NONE.
Reference code from sqlite3:
(static) enum MkErrorE Sq3LockE_FromInt(MK_I32 const value, enum Sq3LockE *value_out)top return the Sq3LockE from integer … → API: Sq3LockE_FromInt
(static) MK_I32 Sq3LockE_ToInt(enum Sq3LockE value)top return the Sq3LockE as integer … → API: Sq3LockE_ToInt
(static) MK_STRN Sq3LockE_ToString(enum Sq3LockE value)top return the Sq3LockE as string … → API: Sq3LockE_ToString
top Mutex Types. → API: Sq3MutexE
Mutex Types …
The sqlite3_mutex_alloc () interface takes a single argument which is one of these integer constants.
The set of static mutexes may change from one SQLite release to the next. Applications that override the built-in mutex logic must be prepared to accommodate additional static mutexes.
Reference code from sqlite3:
(static) enum MkErrorE Sq3MutexE_FromInt(MK_I32 const value, enum Sq3MutexE *value_out)top return the Sq3MutexE from integer … → API: Sq3MutexE_FromInt
(static) MK_I32 Sq3MutexE_ToInt(enum Sq3MutexE value)top return the Sq3MutexE as integer … → API: Sq3MutexE_ToInt
(static) MK_STRN Sq3MutexE_ToString(enum Sq3MutexE value)top return the Sq3MutexE as string … → API: Sq3MutexE_ToString
top Flags For File Open Operations. → API: Sq3OpenEF
Flags For File Open Operations …
These bit values are intended for use in the 3rd parameter to the Sq3LiteOpenV2 () interface and in the 4th parameter to the sqlite3_vfs.xOpen method.
Only those flags marked as "Ok for sqlite3_open_v2()" may be used as the third argument to the Sq3LiteOpenV2 () interface. The other flags have historically been ignored by Sq3LiteOpenV2(), though future versions of SQLite might change so that an error is raised if any of the disallowed bits are passed into Sq3LiteOpenV2(). Applications should not depend on the historical behavior.
Note in particular that passing the SQ3_OPEN_EXCLUSIVE flag into Sq3LiteOpenV2 () does not cause the underlying database file to be opened using O_EXCL. Passing SQ3_OPEN_EXCLUSIVE into Sq3LiteOpenV2 () has historically be a no-op and might become an error in future versions of SQLite.
Reference code from sqlite3:
(static) enum MkErrorE Sq3OpenEF_FromInt(MK_I32 const value, enum Sq3OpenEF *value_out)top return the Sq3OpenEF from integer … → API: Sq3OpenEF_FromInt
(static) MK_I32 Sq3OpenEF_ToInt(enum Sq3OpenEF value)top return the Sq3OpenEF as integer … → API: Sq3OpenEF_ToInt
(static) MK_STRN Sq3OpenEF_ToString(enum Sq3OpenEF value)top return the Sq3OpenEF as string … → API: Sq3OpenEF_ToString
top Prepare Flags. → API: Sq3PrepareEF
Prepare Flags …
These constants define various flags that can be passed into "prepFlags" parameter of the Sq3StmtPrepareV3 () and sqlite3_prepare16_v3 () interfaces.
New flags may be added in future releases of SQLite.
The SQ3_PREPARE_PERSISTENT flag is a hint to the query planner that the prepared statement will be retained for a long time and probably reused many times. Without this flag, Sq3StmtPrepareV3 () and sqlite3_prepare16_v3 () assume that the prepared statement will be used just once or at most a few times and then destroyed using Sq3StmtFinalize () relatively soon. The current implementation acts on this hint by avoiding the use of lookaside memory so as not to deplete the limited store of lookaside memory. Future versions of SQLite may act on this hint differently.
The SQ3_PREPARE_NORMALIZE flag is a no-op. This flag used to be required for any prepared statement that wanted to use the sqlite3_normalized_sql () interface. However, the sqlite3_normalized_sql () interface is now available to all prepared statements, regardless of whether or not they use this flag.
Reference code from sqlite3:
(static) enum MkErrorE Sq3PrepareEF_FromInt(MK_I32 const value, enum Sq3PrepareEF *value_out)top return the Sq3PrepareEF from integer … → API: Sq3PrepareEF_FromInt
(static) MK_I32 Sq3PrepareEF_ToInt(enum Sq3PrepareEF value)top return the Sq3PrepareEF as integer … → API: Sq3PrepareEF_ToInt
(static) MK_STRN Sq3PrepareEF_ToString(enum Sq3PrepareEF value)top return the Sq3PrepareEF as string … → API: Sq3PrepareEF_ToString
top Prepared Statement Scan Status Opcodes. → API: Sq3ScanStatE
Prepared Statement Scan Status Opcodes …
The following constants can be used for the T parameter to the sqlite3_stmt_scanstatus (S,X,T,V) interface. Each constant designates a different metric for sqlite3_stmt_scanstatus() to return.
When the value returned to V is a string, space to hold that string is managed by the prepared statement S and will be automatically freed when S is finalized.
Not all values are available for all query elements. When a value is not available, the output variable is set to -1 if the value is numeric, or to NULL if it is a string (SQ3_SCANSTAT_NAME).
The sqlite3_int64 variable pointed to by the V parameter will be set to the total number of times that the X-th loop has run.
The sqlite3_int64 variable pointed to by the V parameter will be set to the total number of rows examined by all iterations of the X-th loop.
The "double" variable pointed to by the V parameter will be set to the query planner's estimate for the average number of rows output from each iteration of the X-th loop. If the query planner's estimates was accurate, then this value will approximate the quotient NVISIT/NLOOP and the product of this value for all prior loops with the same SELECTID will be the NLOOP value for the current loop.
The "const char *" variable pointed to by the V parameter will be set to a zero-terminated UTF-8 string containing the name of the index or table used for the X-th loop.
The "const char *" variable pointed to by the V parameter will be set to a zero-terminated UTF-8 string containing the EXPLAIN QUERY PLAN description for the X-th loop.
The "int" variable pointed to by the V parameter will be set to the id for the X-th query plan element. The id value is unique within the statement. The select-id is the same value as is output in the first column of an EXPLAIN QUERY PLAN query.
The "int" variable pointed to by the V parameter will be set to the the id of the parent of the current query element, if applicable, or to zero if the query element has no parent. This is the same value as returned in the second column of an EXPLAIN QUERY PLAN query.
Reference code from sqlite3:
(static) enum MkErrorE Sq3ScanStatE_FromInt(MK_I32 const value, enum Sq3ScanStatE *value_out)top return the Sq3ScanStatE from integer … → API: Sq3ScanStatE_FromInt
(static) MK_I32 Sq3ScanStatE_ToInt(enum Sq3ScanStatE value)top return the Sq3ScanStatE as integer … → API: Sq3ScanStatE_ToInt
(static) MK_STRN Sq3ScanStatE_ToString(enum Sq3ScanStatE value)top return the Sq3ScanStatE as string … → API: Sq3ScanStatE_ToString
top Flags for sqlite3_serialize. → API: Sq3SerializeE
Flags for sqlite3_serialize …
Zero or more of the following constants can be OR-ed together for the F argument to Sq3LiteSerialize (D,S,P,F).
SQ3_SERIALIZE_NOCOPY means that Sq3LiteSerialize () will return a pointer to contiguous in-memory database that it is currently using, without making a copy of the database. If SQLite is not currently using a contiguous in-memory database, then this option causes Sq3LiteSerialize () to return a NULL pointer. SQLite will only be using a contiguous in-memory database if it has been initialized by a prior call to Sq3LiteDeserialize ().
Reference code from sqlite3:
(static) enum MkErrorE Sq3SerializeE_FromInt(MK_I32 const value, enum Sq3SerializeE *value_out)top return the Sq3SerializeE from integer … → API: Sq3SerializeE_FromInt
(static) MK_I32 Sq3SerializeE_ToInt(enum Sq3SerializeE value)top return the Sq3SerializeE as integer … → API: Sq3SerializeE_ToInt
(static) MK_STRN Sq3SerializeE_ToString(enum Sq3SerializeE value)top return the Sq3SerializeE as string … → API: Sq3SerializeE_ToString
top Options for sqlite3session_object_config. → API: Sq3SessionObjConfigE
Options for sqlite3session_object_config …
The following values may passed as the the 2nd parameter to sqlite3session_object_config().
This option is used to set, clear or query the flag that enables the sqlite3session_changeset_size () API. Because it imposes some computational overhead, this API is disabled by default. Argument pArg must point to a value of type (int). If the value is initially 0, then the sqlite3session_changeset_size() API is disabled. If it is greater than 0, then the same API is enabled. Or, if the initial value is less than zero, no change is made. In all cases the (int) variable is set to 1 if the sqlite3session_changeset_size() API is enabled following the current call, or 0 otherwise.
It is an error (SQ3_RESULT_MISUSE) to attempt to modify this setting after the first table has been attached to the session object.
This option is used to set, clear or query the flag that enables collection of data for tables with no explicit PRIMARY KEY.
Normally, tables with no explicit PRIMARY KEY are simply ignored by the sessions module. However, if this flag is set, it behaves as if such tables have a column "_rowid_ INTEGER PRIMARY KEY" inserted as their leftmost columns.
It is an error (SQ3_RESULT_MISUSE) to attempt to modify this setting after the first table has been attached to the session object.
Reference code from sqlite3:
(static) enum MkErrorE Sq3SessionObjConfigE_FromInt(MK_I32 const value, enum Sq3SessionObjConfigE *value_out)top return the Sq3SessionObjConfigE from integer … → API: Sq3SessionObjConfigE_FromInt
(static) MK_I32 Sq3SessionObjConfigE_ToInt(enum Sq3SessionObjConfigE value)top return the Sq3SessionObjConfigE as integer … → API: Sq3SessionObjConfigE_ToInt
(static) MK_STRN Sq3SessionObjConfigE_ToString(enum Sq3SessionObjConfigE value)top return the Sq3SessionObjConfigE as string … → API: Sq3SessionObjConfigE_ToString
top Flags for the xShmLock VFS method. → API: Sq3ShmLockE
Flags for the xShmLock VFS method …
These integer constants define the various locking operations allowed by the xShmLock method of sqlite3_io_methods. The following are the only legal combinations of flags to the xShmLock method:
When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as was given on the corresponding lock.
The xShmLock method can transition between unlocked and SHARED or between unlocked and EXCLUSIVE. It cannot transition between SHARED and EXCLUSIVE.
Reference code from sqlite3:
(static) enum MkErrorE Sq3ShmLockE_FromInt(MK_I32 const value, enum Sq3ShmLockE *value_out)top return the Sq3ShmLockE from integer … → API: Sq3ShmLockE_FromInt
(static) MK_I32 Sq3ShmLockE_ToInt(enum Sq3ShmLockE value)top return the Sq3ShmLockE as integer … → API: Sq3ShmLockE_ToInt
(static) MK_STRN Sq3ShmLockE_ToString(enum Sq3ShmLockE value)top return the Sq3ShmLockE as string … → API: Sq3ShmLockE_ToString
top Status Parameters. → API: Sq3StatusE
Status Parameters …
These integer constants designate various run-time status parameters that can be returned by Sq3Status ().
This parameter is the current amount of memory checked out using Sq3Malloc (), either directly or indirectly. The figure includes calls made to Sq3Malloc () by the application and internal memory usage by the SQLite library. Auxiliary page-cache memory controlled by SQ3_CONFIG_PAGECACHE is not included in this parameter. The amount returned is the sum of the allocation sizes as reported by the xSize method in sqlite3_mem_methods.
This parameter records the largest memory allocation request handed to Sq3Malloc () or Sq3Realloc () (or their internal equivalents). Only the value returned in the pHighwater parameter to Sq3Status () is of interest. The value written into the *pCurrent parameter is undefined.
This parameter records the number of separate memory allocations currently checked out.
This parameter returns the number of pages used out of the pagecache memory allocator that was configured using SQ3_CONFIG_PAGECACHE. The value returned is in pages, not in bytes.
This parameter returns the number of bytes of page cache allocation which could not be satisfied by the SQ3_CONFIG_PAGECACHE buffer and where forced to overflow to Sq3Malloc (). The returned value includes allocations that overflowed because they where too large (they were larger than the "sz" parameter to SQ3_CONFIG_PAGECACHE) and allocations that overflowed because no space was left in the page cache.
This parameter records the largest memory allocation request handed to the pagecache memory allocator. Only the value returned in the pHighwater parameter to Sq3Status () is of interest. The value written into the *pCurrent parameter is undefined.
New status parameters may be added from time to time.
Reference code from sqlite3:
(static) enum MkErrorE Sq3StatusE_FromInt(MK_I32 const value, enum Sq3StatusE *value_out)top return the Sq3StatusE from integer … → API: Sq3StatusE_FromInt
(static) MK_I32 Sq3StatusE_ToInt(enum Sq3StatusE value)top return the Sq3StatusE as integer … → API: Sq3StatusE_ToInt
(static) MK_STRN Sq3StatusE_ToString(enum Sq3StatusE value)top return the Sq3StatusE as string … → API: Sq3StatusE_ToString
top Status Parameters for prepared statements. → API: Sq3StmtStatusE
Status Parameters for prepared statements …
These preprocessor macros define integer codes that name counter values associated with the Sq3StmtStatus () interface. The meanings of the various counters are as follows:
This is the number of times that SQLite has stepped forward in a table as part of a full table scan. Large numbers for this counter may indicate opportunities for performance improvement through careful use of indices.
This is the number of sort operations that have occurred. A non-zero value in this counter may indicate an opportunity to improvement performance through careful use of indices.
This is the number of rows inserted into transient indices that were created automatically in order to help joins run faster. A non-zero value in this counter may indicate an opportunity to improvement performance by adding permanent indices that do not need to be reinitialized each time the statement is run.
This is the number of virtual machine operations executed by the prepared statement if that number is less than or equal to 2147483647. The number of virtual machine operations can be used as a proxy for the total work done by the prepared statement. If the number of virtual machine operations exceeds 2147483647 then the value returned by this statement status code is undefined.
This is the number of times that the prepare statement has been automatically regenerated due to schema changes or changes to bound parameters that might affect the query plan.
This is the number of times that the prepared statement has been run. A single "run" for the purposes of this counter is one or more calls to Sq3StmtStep () followed by a call to Sq3StmtReset (). The counter is incremented on the first Sq3StmtStep () call of each cycle.
SQ3_STMTSTATUS_FILTER_HIT is the number of times that a join step was bypassed because a Bloom filter returned not-found. The corresponding SQ3_STMTSTATUS_FILTER_MISS value is the number of times that the Bloom filter returned a find, and thus the join step had to be processed as normal.
Reference code from sqlite3:
(static) enum MkErrorE Sq3StmtStatusE_FromInt(MK_I32 const value, enum Sq3StmtStatusE *value_out)top return the Sq3StmtStatusE from integer … → API: Sq3StmtStatusE_FromInt
(static) MK_I32 Sq3StmtStatusE_ToInt(enum Sq3StmtStatusE value)top return the Sq3StmtStatusE as integer … → API: Sq3StmtStatusE_ToInt
(static) MK_STRN Sq3StmtStatusE_ToString(enum Sq3StmtStatusE value)top return the Sq3StmtStatusE as string … → API: Sq3StmtStatusE_ToString
top Synchronization Type Flags. → API: Sq3SyncEF
Synchronization Type Flags …
When SQLite invokes the xSync() method of an sqlite3_io_methods object it uses a combination of these integer values as the second argument.
When the SQ3_SYNC_DATAONLY flag is used, it means that the sync operation only needs to flush data to mass storage. Inode information need not be flushed. If the lower four bits of the flag equal SQ3_SYNC_NORMAL, that means to use normal fsync() semantics. If the lower four bits equal SQ3_SYNC_FULL, that means to use Mac OS X style fullsync instead of fsync().
Do not confuse the SQ3_SYNC_NORMAL and SQ3_SYNC_FULL flags with the PRAGMA synchronous=NORMAL and PRAGMA synchronous=FULL settings. The synchronous pragma determines when calls to the xSync VFS method occur and applies uniformly across all platforms. The SQ3_SYNC_NORMAL and SQ3_SYNC_FULL flags determine how energetic or rigorous or forceful the sync operations are and only make a difference on Mac OSX for the default SQLite code. (Third-party VFS implementations might also make the distinction between SQ3_SYNC_NORMAL and SQ3_SYNC_FULL, but among the operating systems natively supported by SQLite, only Mac OSX cares about the difference.)
Reference code from sqlite3:
(static) enum MkErrorE Sq3SyncEF_FromInt(MK_I32 const value, enum Sq3SyncEF *value_out)top return the Sq3SyncEF from integer … → API: Sq3SyncEF_FromInt
(static) MK_I32 Sq3SyncEF_ToInt(enum Sq3SyncEF value)top return the Sq3SyncEF as integer … → API: Sq3SyncEF_ToInt
(static) MK_STRN Sq3SyncEF_ToString(enum Sq3SyncEF value)top return the Sq3SyncEF as string … → API: Sq3SyncEF_ToString
top Testing Interface Operation Codes. → API: Sq3TestCtrlE
Testing Interface Operation Codes …
These constants are the valid operation code parameters used as the first argument to sqlite3_test_control ().
These parameters and their meanings are subject to change without notice. These values are for testing purposes only. Applications should not use any of these parameters or the sqlite3_test_control () interface.
Reference code from sqlite3:
(static) enum MkErrorE Sq3TestCtrlE_FromInt(MK_I32 const value, enum Sq3TestCtrlE *value_out)top return the Sq3TestCtrlE from integer … → API: Sq3TestCtrlE_FromInt
(static) MK_I32 Sq3TestCtrlE_ToInt(enum Sq3TestCtrlE value)top return the Sq3TestCtrlE as integer … → API: Sq3TestCtrlE_ToInt
(static) MK_STRN Sq3TestCtrlE_ToString(enum Sq3TestCtrlE value)top return the Sq3TestCtrlE as string … → API: Sq3TestCtrlE_ToString
top Text Encodings. → API: Sq3TextE
Text Encodings …
These constant define integer codes that represent the various text encodings supported by SQLite.
Reference code from sqlite3:
(static) enum MkErrorE Sq3TextE_FromInt(MK_I32 const value, enum Sq3TextE *value_out)top return the Sq3TextE from integer … → API: Sq3TextE_FromInt
(static) MK_I32 Sq3TextE_ToInt(enum Sq3TextE value)top return the Sq3TextE as integer … → API: Sq3TextE_ToInt
(static) MK_STRN Sq3TextE_ToString(enum Sq3TextE value)top return the Sq3TextE as string … → API: Sq3TextE_ToString
top SQL Trace Event Codes. → API: Sq3TraceEF
SQL Trace Event Codes …
These constants identify classes of events that can be monitored using the sqlite3_trace_v2 () tracing logic. The M argument to sqlite3_trace_v2 (D,M,X,P) is an OR-ed combination of one or more of the following constants. The first argument to the trace callback is one of the following constants.
New tracing constants may be added in future releases.
A trace callback has four arguments: xCallback(T,C,P,X). The T argument is one of the integer type codes above. The C argument is a copy of the context pointer passed in as the fourth argument to sqlite3_trace_v2 (). The P and X arguments are pointers whose meanings depend on T.
An SQ3_TRACE_STMT callback is invoked when a prepared statement first begins running and possibly at other times during the execution of the prepared statement, such as at the start of each trigger subprogram. The P argument is a pointer to the prepared statement. The X argument is a pointer to a string which is the unexpanded SQL text of the prepared statement or an SQL comment that indicates the invocation of a trigger. The callback can compute the same text that would have been returned by the legacy sqlite3_trace () interface by using the X argument when X begins with "--" and invoking Sq3StmtExpandedSql (P) otherwise.
An SQ3_TRACE_PROFILE callback provides approximately the same information as is provided by the sqlite3_profile () callback. The P argument is a pointer to the prepared statement and the X argument points to a 64-bit integer which is approximately the number of nanoseconds that the prepared statement took to run. The SQ3_TRACE_PROFILE callback is invoked when the statement finishes.
An SQ3_TRACE_ROW callback is invoked whenever a prepared statement generates a single row of result. The P argument is a pointer to the prepared statement and the X argument is unused.
Reference code from sqlite3:
(static) enum MkErrorE Sq3TraceEF_FromInt(MK_I32 const value, enum Sq3TraceEF *value_out)top return the Sq3TraceEF from integer … → API: Sq3TraceEF_FromInt
(static) MK_I32 Sq3TraceEF_ToInt(enum Sq3TraceEF value)top return the Sq3TraceEF as integer … → API: Sq3TraceEF_ToInt
(static) MK_STRN Sq3TraceEF_ToString(enum Sq3TraceEF value)top return the Sq3TraceEF as string … → API: Sq3TraceEF_ToString
top Allowed return values from sqlite3_txn_state() → API: Sq3TxnE
Allowed return values from sqlite3_txn_state() …
These constants define the current transaction state of a database file. The Sq3LiteTxnState (D,S) interface returns one of these constants in order to describe the transaction state of schema S in database connection D.
The SQ3_TXN_NONE state means that no transaction is currently pending.
The SQ3_TXN_READ state means that the database is currently in a read transaction. Content has been read from the database file but nothing in the database file has changed. The transaction state will advanced to SQ3_TXN_WRITE if any changes occur and there are no other conflicting concurrent write transactions. The transaction state will revert to SQ3_TXN_NONE following a ROLLBACK or COMMIT.
Reference code from sqlite3:
(static) enum MkErrorE Sq3TxnE_FromInt(MK_I32 const value, enum Sq3TxnE *value_out)top return the Sq3TxnE from integer … → API: Sq3TxnE_FromInt
(static) MK_I32 Sq3TxnE_ToInt(enum Sq3TxnE value)top return the Sq3TxnE as integer … → API: Sq3TxnE_ToInt
(static) MK_STRN Sq3TxnE_ToString(enum Sq3TxnE value)top return the Sq3TxnE as string … → API: Sq3TxnE_ToString
top Fundamental Datatypes. → API: Sq3TypeE
Fundamental Datatypes …
Every value in SQLite has one of five fundamental datatypes:
These constants are codes for each of those types.
Note that the SQ3_TYPE_TEXT constant was also used in SQLite version 2 for a completely different meaning. Software that links against both SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not SQ3_TYPE_TEXT.
Reference code from sqlite3:
(static) enum MkErrorE Sq3TypeE_FromInt(MK_I32 const value, enum Sq3TypeE *value_out)top return the Sq3TypeE from integer … → API: Sq3TypeE_FromInt
(static) MK_I32 Sq3TypeE_ToInt(enum Sq3TypeE value)top return the Sq3TypeE as integer … → API: Sq3TypeE_ToInt
(static) MK_STRN Sq3TypeE_ToString(enum Sq3TypeE value)top return the Sq3TypeE as string … → API: Sq3TypeE_ToString
top Virtual Table Configuration Options. → API: Sq3VtabE
Virtual Table Configuration Options …
These macros define the various options to the Sq3LiteVtabConfig () interface that virtual table implementations can use to customize and optimize their behavior.
Calls of the form Sq3LiteVtabConfig(db,SQ3_VTAB_CONSTRAINT_SUPPORT,X) are supported, where X is an integer. If X is zero, then the virtual table whose xCreate or xConnect method invoked Sq3LiteVtabConfig () does not support constraints. In this configuration (which is the default) if a call to the xUpdate method returns SQ3_RESULT_CONSTRAINT, then the entire statement is rolled back as if OR ABORT had been specified as part of the users SQL statement, regardless of the actual ON CONFLICT mode specified.
If X is non-zero, then the virtual table implementation guarantees that if xUpdate returns SQ3_RESULT_CONSTRAINT, it will do so before any modifications to internal or persistent data structures have been made. If the ON CONFLICT mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite is able to roll back a statement or database transaction, and abandon or continue processing the current SQL statement as appropriate. If the ON CONFLICT mode is REPLACE and the xUpdate method returns SQ3_RESULT_CONSTRAINT, SQLite handles this as if the ON CONFLICT mode had been ABORT.
Virtual table implementations that are required to handle OR REPLACE must do so within the xUpdate method. If a call to the Sq3LiteVtabOnConflict () function indicates that the current ON CONFLICT policy is REPLACE, the virtual table implementation should silently replace the appropriate rows within the xUpdate callback and return SQ3_RESULT_OK. Or, if this is not possible, it may return SQ3_RESULT_CONSTRAINT, in which case SQLite falls back to OR ABORT constraint handling.
Calls of the form Sq3LiteVtabConfig(db,SQ3_VTAB_DIRECTONLY) from within the the xConnect or xCreate methods of a virtual table implementation prohibits that virtual table from being used from within triggers and views.
Calls of the form Sq3LiteVtabConfig(db,SQ3_VTAB_INNOCUOUS) from within the the xConnect or xCreate methods of a virtual table implementation identify that virtual table as being safe to use from within triggers and views. Conceptually, the SQ3_VTAB_INNOCUOUS tag means that the virtual table can do no serious harm even if it is controlled by a malicious hacker. Developers should avoid setting the SQ3_VTAB_INNOCUOUS flag unless absolutely necessary.
Reference code from sqlite3:
(static) enum MkErrorE Sq3VtabE_FromInt(MK_I32 const value, enum Sq3VtabE *value_out)top return the Sq3VtabE from integer … → API: Sq3VtabE_FromInt
(static) MK_I32 Sq3VtabE_ToInt(enum Sq3VtabE value)top return the Sq3VtabE as integer … → API: Sq3VtabE_ToInt
(static) MK_STRN Sq3VtabE_ToString(enum Sq3VtabE value)top return the Sq3VtabE as string … → API: Sq3VtabE_ToString
C-API: Sq3Lite_Config_C_API - Sq3Lite PACKAGE - configure the applicatione …
(static) MK_STRN Sq3CompileOptionGet(MK_I32 N)top Run-Time Library Compilation Options Diagnostics … → API: Sq3CompileOptionGet
The Sq3CompileOptionUsed() function returns 0 or 1 indicating whether the specified option was defined at compile time. The SQLITE_ prefix may be omitted from the option name passed to Sq3CompileOptionUsed().
The Sq3CompileOptionGet() function allows iterating over the list of options that were defined at compile time by returning the N-th compile time option string. If N is out of range, Sq3CompileOptionGet() returns a NULL pointer. The SQLITE_ prefix is omitted from any strings returned by Sq3CompileOptionGet().
Support for the diagnostic functions Sq3CompileOptionUsed() and Sq3CompileOptionGet() may be omitted by specifying the SQLITE_OMIT_COMPILEOPTION_DIAGS option at compile time.
See also: SQL functions sqlite_compileoption_used () and sqlite_compileoption_get () and the compile_options pragma.
Reference code from sqlite3:
(static) MK_BOOL Sq3CompileOptionUsed(MK_STRN zOptName)top Run-Time Library Compilation Options Diagnostics … → API: Sq3CompileOptionUsed
read more at 'Sq3CompileOptionGet'
(static,hide) void Sq3LiteProgressHandler(SQ3_LITE sq3lite, MK_I32 N, Sq3Fupu_Sq3LiteProgressHandler_X X, MK_PTR P)top Query Progress Callbacks … → API: Sq3LiteProgressHandler
The Sq3LiteProgressHandler(D,N,X,P) interface causes the callback function X to be invoked periodically during long running calls to Sq3StmtStep () and sqlite3_prepare () and similar for database connection D. An example use for this interface is to keep a GUI updated during a large query.
The parameter P is passed through as the only parameter to the callback function X. The parameter N is the approximate number of virtual machine instructions that are evaluated between successive invocations of the callback X. If N is less than one then the progress handler is disabled.
Only a single progress handler may be defined at one time per database connection; setting a new progress handler cancels the old one. Setting parameter X to NULL disables the progress handler. The progress handler is also disabled by setting N to a value less than 1.
If the progress callback returns non-zero, the operation is interrupted. This feature can be used to implement a "Cancel" button on a GUI progress dialog box.
The progress handler callback must not do anything that will modify the database connection that invoked the progress handler. Note that Sq3StmtPrepareV2 () and Sq3StmtStep () both modify their database connections for the meaning of "modify" in this paragraph.
The progress handler callback would originally only be invoked from the bytecode engine. It still might be invoked during sqlite3_prepare () and similar because those routines might force a reparse of the schema which involves running the bytecode engine. However, beginning with SQLite version 3.41.0, the progress handler callback might also be invoked directly from sqlite3_prepare () while analyzing and generating code for complex queries.
Reference code from sqlite3:
(static,hide) enum Sq3AuthReturnE Sq3LiteSetAuthorizer(SQ3_LITE sq3lite, Sq3Fupu_Sq3LiteSetAuthorizer_xAuth xAuth, MK_PTR pUserData)top Compile-Time Authorization Callbacks … → API: Sq3LiteSetAuthorizer
This routine registers an authorizer callback with a particular database connection, supplied in the first argument. The authorizer callback is invoked as SQL statements are being compiled by sqlite3_prepare () or its variants Sq3StmtPrepareV2 (), Sq3StmtPrepareV3 (), sqlite3_prepare16 (), sqlite3_prepare16_v2 (), and sqlite3_prepare16_v3 (). At various points during the compilation process, as logic is being created to perform various actions, the authorizer callback is invoked to see if those actions are allowed. The authorizer callback should return SQ3_RESULT_OK to allow the action, SQ3_AUTHRETURN_IGNORE to disallow the specific action but allow the SQL statement to continue to be compiled, or SQ3_AUTHRETURN_DENY to cause the entire SQL statement to be rejected with an error. If the authorizer callback returns any value other than SQ3_AUTHRETURN_IGNORE, SQ3_RESULT_OK, or SQ3_AUTHRETURN_DENY then the Sq3StmtPrepareV2 () or equivalent call that triggered the authorizer will fail with an error message.
When the callback returns SQ3_RESULT_OK, that means the operation requested is ok. When the callback returns SQ3_AUTHRETURN_DENY, the Sq3StmtPrepareV2 () or equivalent call that triggered the authorizer will fail with an error message explaining that access is denied.
The first parameter to the authorizer callback is a copy of the third parameter to the Sq3LiteSetAuthorizer() interface. The second parameter to the callback is an integer action code that specifies the particular action to be authorized. The third through sixth parameters to the callback are either NULL pointers or zero-terminated strings that contain additional details about the action to be authorized. Applications must always be prepared to encounter a NULL pointer in any of the third through the sixth parameters of the authorization callback.
If the action code is SQ3_AUTHACTION_READ and the callback returns SQ3_AUTHRETURN_IGNORE then the prepared statement statement is constructed to substitute a NULL value in place of the table column that would have been read if SQ3_RESULT_OK had been returned. The SQ3_AUTHRETURN_IGNORE return can be used to deny an untrusted user access to individual columns of a table. When a table is referenced by a SELECT but no column values are extracted from that table (for example in a query like "SELECT count(*) FROM tab") then the SQ3_AUTHACTION_READ authorizer callback is invoked once for that table with a column name that is an empty string. If the action code is SQ3_AUTHACTION_DELETE and the callback returns SQ3_AUTHRETURN_IGNORE then the DELETE operation proceeds but the truncate optimization is disabled and all rows are deleted individually.
An authorizer is used when preparing SQL statements from an untrusted source, to ensure that the SQL statements do not try to access data they are not allowed to see, or that they do not try to execute malicious statements that damage the database. For example, an application may allow a user to enter arbitrary SQL queries for evaluation by a database. But the application does not want the user to be able to make arbitrary changes to the database. An authorizer could then be put in place while the user-entered SQL is being prepared that disallows everything except SELECT statements.
Applications that need to process SQL from untrusted sources might also consider lowering resource limits using Sq3LiteLimit () and limiting database size using the max_page_count PRAGMA in addition to using an authorizer.
Only a single authorizer can be in place on a database connection at a time. Each call to Sq3LiteSetAuthorizer overrides the previous call. Disable the authorizer by installing a NULL callback. The authorizer is disabled by default.
The authorizer callback must not do anything that will modify the database connection that invoked the authorizer callback. Note that Sq3StmtPrepareV2 () and Sq3StmtStep () both modify their database connections for the meaning of "modify" in this paragraph.
When Sq3StmtPrepareV2 () is used to prepare a statement, the statement might be re-prepared during Sq3StmtStep () due to a schema change. Hence, the application should ensure that the correct authorizer callback remains in place during the Sq3StmtStep ().
Note that the authorizer callback is invoked only during sqlite3_prepare () or its variants. Authorization is not performed during statement evaluation in Sq3StmtStep (), unless as stated in the previous paragraph, Sq3StmtStep() invokes Sq3StmtPrepareV2() to reprepare a statement after a schema change.
Reference code from sqlite3:
(static) MK_I64 Sq3MemoryHighwater(MK_I32 resetFlag)top Memory Allocator Statistics … → API: Sq3MemoryHighwater
SQLite provides these two interfaces for reporting on the status of the Sq3Malloc (), Sq3Free (), and Sq3Realloc () routines, which form the built-in memory allocation subsystem.
The Sq3MemoryUsed () routine returns the number of bytes of memory currently outstanding (malloced but not freed). The Sq3MemoryHighwater () routine returns the maximum value of Sq3MemoryUsed () since the high-water mark was last reset. The values returned by Sq3MemoryUsed () and Sq3MemoryHighwater () include any overhead added by SQLite in its implementation of Sq3Malloc (), but not overhead added by the any underlying system library routines that Sq3Malloc () may call.
The memory high-water mark is reset to the current value of Sq3MemoryUsed () if and only if the parameter to Sq3MemoryHighwater () is true. The value returned by Sq3MemoryHighwater (1) is the high-water mark prior to the reset.
Reference code from sqlite3:
(static) MK_I64 Sq3MemoryUsed()top Memory Allocator Statistics … → API: Sq3MemoryUsed
read more at 'Sq3MemoryHighwater'
(static,hide) void Sq3Randomness(MK_I32 N, MK_PTR P)top Pseudo-Random Number Generator … → API: Sq3Randomness
SQLite contains a high-quality pseudo-random number generator (PRNG) used to select random ROWIDs when inserting new records into a table that already uses the largest possible ROWID. The PRNG is also used for the built-in random() and randomblob() SQL functions. This interface allows applications to access the same PRNG for other purposes.
A call to this routine stores N bytes of randomness into buffer P. The P parameter can be a NULL pointer.
If this routine has not been previously called or if the previous call had N less than one or a NULL pointer for P, then the PRNG is seeded using randomness obtained from the xRandomness method of the default sqlite3_vfs object. If the previous call to this routine had an N of 1 or more and a non-NULL P then the pseudo-randomness is generated internally and without recourse to the sqlite3_vfs xRandomness method.
Reference code from sqlite3:
(static,hide) void Sq3SetupThreadCallback(Sq3SetupThreadF call)top Initialize a callback which is called at runtime-setup … → API: Sq3SetupThreadCallback
A runtime is created with every new thread and the purpose of this function is to provide the possible to add extra code at the end of the runtime-setup.
Internal the MkRuntimeCallbackAdd is used to register the callback.
| [in] | call | the new callback or MK_NULL for cleanup. |
(static) enum MkErrorE Sq3Threadsafe()top Test To See If The Library Is Threadsafe … → API: Sq3Threadsafe
The Sq3Threadsafe() function returns zero if and only if SQLite was compiled with mutexing code omitted due to the SQLITE_THREADSAFE compile-time option being set to 0.
SQLite can be compiled with or without mutexes. When the SQLITE_THREADSAFE C preprocessor macro is 1 or 2, mutexes are enabled and SQLite is threadsafe. When the SQLITE_THREADSAFE macro is 0, the mutexes are omitted. Without the mutexes, it is not safe to use SQLite concurrently from more than one thread.
Enabling mutexes incurs a measurable performance penalty. So if speed is of utmost importance, it makes sense to disable the mutexes. But for maximum safety, mutexes should be enabled. The default behavior is for mutexes to be enabled.
This interface can be used by an application to make sure that the version of SQLite that it is linking against was compiled with the desired setting of the SQLITE_THREADSAFE macro.
This interface only reports on the compile-time mutex setting of the SQLITE_THREADSAFE flag. If SQLite is compiled with SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but can be fully or partially disabled using a call to sqlite3_config () with the verbs SQ3_CONFIG_SINGLETHREAD, SQ3_CONFIG_MULTITHREAD, or SQ3_CONFIG_SERIALIZED. The return value of the Sq3Threadsafe() function shows only the compile-time setting of thread safety, not any run-time changes to that setting made by sqlite3_config(). In other words, the return value from Sq3Threadsafe() is unchanged by calls to sqlite3_config().
See the threading mode documentation for additional information.
Reference code from sqlite3:
C-API: Sq3Lite_Info_C_API - Sq3Lite PACKAGE - get information about the application …
(static) enum MkErrorE Sq3Complete(MK_STRN sql)top Determine If An SQL Statement Is Complete … → API: Sq3Complete
These routines are useful during command-line input to determine if the currently entered text seems to form a complete SQL statement or if additional input is needed before sending the text into SQLite for parsing. These routines return 1 if the input string appears to be a complete SQL statement. A statement is judged to be complete if it ends with a semicolon token and is not a prefix of a well-formed CREATE TRIGGER statement. Semicolons that are embedded within string literals or quoted identifier names or comments are not independent tokens (they are part of the token in which they are embedded) and thus do not count as a statement terminator. Whitespace and comments that follow the final semicolon are ignored.
These routines return 0 if the statement is incomplete. If a memory allocation fails, then SQ3_RESULT_NOMEM is returned.
These routines do not parse the SQL statements thus will not detect syntactically incorrect SQL.
If SQLite has not been initialized using Sq3Initialize () prior to invoking sqlite3_complete16() then Sq3Initialize() is invoked automatically by sqlite3_complete16(). If that initialization fails, then the return value from sqlite3_complete16() will be non-zero regardless of whether or not the input SQL is complete.
The input to Sq3Complete () must be a zero-terminated UTF-8 string.
The input to sqlite3_complete16 () must be a zero-terminated UTF-16 string in native byte order.
Reference code from sqlite3:
(static) enum MkErrorE Sq3KeywordCheck(MK_STRN arg0, MK_I32 arg1)top SQL Keyword Checking … → API: Sq3KeywordCheck
These routines provide access to the set of SQL language keywords recognized by SQLite. Applications can uses these routines to determine whether or not a specific identifier needs to be escaped (for example, by enclosing in double-quotes) so as not to confuse the parser.
The Sq3KeywordCount() interface returns the number of distinct keywords understood by SQLite.
The Sq3KeywordName(N,Z,L) interface finds the N-th keyword and makes *Z point to that keyword expressed as UTF8 and writes the number of bytes in the keyword into *L. The string that *Z points to is not zero-terminated. The Sq3KeywordName(N,Z,L) routine returns SQ3_RESULT_OK if N is within bounds and SQ3_RESULT_ERROR if not. If either Z or L are NULL or invalid pointers then calls to Sq3KeywordName(N,Z,L) result in undefined behavior.
The Sq3KeywordCheck(Z,L) interface checks to see whether or not the L-byte UTF8 identifier that Z points to is a keyword, returning non-zero if it is and zero if not.
The parser used by SQLite is forgiving. It is often possible to use a keyword as an identifier as long as such use does not result in a parsing ambiguity. For example, the statement "CREATE TABLE BEGIN(REPLACE,PRAGMA,END);" is accepted by SQLite, and creates a new table named "BEGIN" with three columns named "REPLACE", "PRAGMA", and "END". Nevertheless, best practice is to avoid using keywords as identifiers. Common techniques used to avoid keyword name collisions include:
Note that the number of keywords understood by SQLite can depend on compile-time options. For example, "VACUUM" is not a keyword if SQLite is compiled with the -DSQLITE_OMIT_VACUUM option. Also, new keywords may be added to future releases of SQLite.
Reference code from sqlite3:
(static) enum MkErrorE Sq3KeywordCount()top SQL Keyword Checking … → API: Sq3KeywordCount
read more at 'Sq3KeywordCheck'
(static) enum MkErrorE Sq3KeywordName(MK_I32 num, MK_STRN *kwd, MK_I32 *kwdsz)top SQL Keyword Checking … → API: Sq3KeywordName
read more at 'Sq3KeywordCheck'
(static,runtime) enum MkErrorE Sq3KeywordNameBUF(MK_I32 num, MK_BUF *kwd_out)top SQL Keyword Checking … → API: Sq3KeywordNameBUF_RT
read more at 'Sq3KeywordCheck'
| [in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
| [in] | num | The keyword-number |
| [out] | kwd_out | The return-value have to be not MK_NULL. |
MK_NULL for a non-error result.(static) enum MkErrorE Sq3Status(enum Sq3StatusE op, MK_I32 *pCurrent, MK_I32 *pHighwater, MK_BOOL resetFlag)top SQLite Runtime Status … → API: Sq3Status
These interfaces are used to retrieve runtime status information about the performance of SQLite, and optionally to reset various highwater marks. The first argument is an integer code for the specific parameter to measure. Recognized integer codes are of the form SQ3_STATUS_.... The current value of the parameter is returned into *pCurrent. The highest recorded value is returned in *pHighwater. If the resetFlag is true, then the highest record value is reset after pHighwater is written. Some parameters do not record the highest value. For those parameters nothing is written into *pHighwater and the resetFlag is ignored. Other parameters record only the highwater mark and not the current value. For these latter parameters nothing is written into *pCurrent.
The Sq3Status() and Sq3Status64() routines return SQ3_RESULT_OK on success and a non-zero error code on failure.
If either the current value or the highwater mark is too large to be represented by a 32-bit integer, then the values returned by Sq3Status() are undefined.
See also: Sq3LiteDbStatus ()
Reference code from sqlite3:
(static) enum MkErrorE Sq3Status64(enum Sq3StatusE op, MK_I64 *pCurrent, MK_I64 *pHighwater, MK_BOOL resetFlag)top SQLite Runtime Status … → API: Sq3Status64
| Free | Memory Allocation Subsystem … | ||
| Malloc | Memory Allocation Subsystem … | ||
| Malloc64 | Memory Allocation Subsystem … | ||
| Msize | Memory Allocation Subsystem … | ||
| Realloc | Memory Allocation Subsystem … | ||
| Realloc64 | Memory Allocation Subsystem … | ||
| HardHeapLimit64 | Impose A Limit On Heap Size … | ||
| ReleaseMemory | Attempt To Free Heap Memory … | ||
| SoftHeapLimit64 | Impose A Limit On Heap Size … | ||
| StrGlob | String Globbing … | ||
| StrIcmp | String Comparison … | ||
| StrLike | String LIKE Matching … | ||
| StrNicmp | String Comparison … | ||
C-API: Sq3Lite_Internal_C_API - Sq3Lite PACKAGE - low level internal functions …
C-API: Sq3Lite_Internal_Alloc_C_API - Memory Allocation Subsystem …
The SQLite core uses these three routines for all of its own internal memory allocation needs. "Core" in the previous sentence does not include operating-system specific VFS implementation. The Windows VFS uses native malloc() and free() for some operations.
The Sq3Malloc() routine returns a pointer to a block of memory at least N bytes in length, where N is the parameter. If Sq3Malloc() is unable to obtain sufficient free memory, it returns a NULL pointer. If the parameter N to Sq3Malloc() is zero or negative then Sq3Malloc() returns a NULL pointer.
The Sq3Malloc64(N) routine works just like Sq3Malloc(N) except that N is an unsigned 64-bit integer instead of a signed 32-bit integer.
Calling Sq3Free() with a pointer previously returned by Sq3Malloc() or Sq3Realloc() releases that memory so that it might be reused. The Sq3Free() routine is a no-op if is called with a NULL pointer. Passing a NULL pointer to Sq3Free() is harmless. After being freed, memory should neither be read nor written. Even reading previously freed memory might result in a segmentation fault or other severe error. Memory corruption, a segmentation fault, or other severe error might result if Sq3Free() is called with a non-NULL pointer that was not obtained from Sq3Malloc() or Sq3Realloc().
The Sq3Realloc(X,N) interface attempts to resize a prior memory allocation X to be at least N bytes. If the X parameter to Sq3Realloc(X,N) is a NULL pointer then its behavior is identical to calling Sq3Malloc(N). If the N parameter to Sq3Realloc(X,N) is zero or negative then the behavior is exactly the same as calling Sq3Free(X). Sq3Realloc(X,N) returns a pointer to a memory allocation of at least N bytes in size or NULL if insufficient memory is available. If M is the size of the prior allocation, then min(N,M) bytes of the prior allocation are copied into the beginning of buffer returned by Sq3Realloc(X,N) and the prior allocation is freed. If Sq3Realloc(X,N) returns NULL and N is positive, then the prior allocation is not freed.
The Sq3Realloc64(X,N) interfaces works the same as Sq3Realloc(X,N) except that N is a 64-bit unsigned integer instead of a 32-bit signed integer.
If X is a memory allocation previously obtained from Sq3Malloc(), Sq3Malloc64(), Sq3Realloc(), or Sq3Realloc64(), then Sq3Msize(X) returns the size of that memory allocation in bytes. The value returned by Sq3Msize(X) might be larger than the number of bytes requested when X was allocated. If X is a NULL pointer then Sq3Msize(X) returns zero. If X points to something that is not the beginning of memory allocation, or if it points to a formerly valid memory allocation that has now been freed, then the behavior of Sq3Msize(X) is undefined and possibly harmful.
The memory returned by Sq3Malloc(), Sq3Realloc(), Sq3Malloc64(), and Sq3Realloc64() is always aligned to at least an 8 byte boundary, or to a 4 byte boundary if the SQLITE_4_BYTE_ALIGNED_MALLOC compile-time option is used.
The pointer arguments to Sq3Free () and Sq3Realloc () must be either NULL or else pointers obtained from a prior invocation of Sq3Malloc () or Sq3Realloc () that have not yet been released.
The application must not read or write any part of a block of memory after it has been released using Sq3Free () or Sq3Realloc ().
Reference code from sqlite3:
(static,hide) void Sq3Free(MK_PTR N)top Memory Allocation Subsystem … → API: Sq3Free
read more at 'Sq3Lite_Internal_Alloc_C_API'
(static,hide) MK_PTR Sq3Malloc(MK_I32 N)top Memory Allocation Subsystem … → API: Sq3Malloc
read more at 'Sq3Lite_Internal_Alloc_C_API'
(static,hide) MK_PTR Sq3Malloc64(MK_I64 N)top Memory Allocation Subsystem … → API: Sq3Malloc64
read more at 'Sq3Lite_Internal_Alloc_C_API'
(static,hide) MK_I64 Sq3Msize(MK_PTR N)top Memory Allocation Subsystem … → API: Sq3Msize
read more at 'Sq3Lite_Internal_Alloc_C_API'
(static,hide) MK_PTR Sq3Realloc(MK_PTR arg0, MK_I32 N)top Memory Allocation Subsystem … → API: Sq3Realloc
read more at 'Sq3Lite_Internal_Alloc_C_API'
(static,hide) MK_PTR Sq3Realloc64(MK_PTR arg0, MK_I64 N)top Memory Allocation Subsystem … → API: Sq3Realloc64
read more at 'Sq3Lite_Internal_Alloc_C_API'
C-API: Sq3Lite_Internal_Memory_C_API - Sq3Lite PACKAGE - functions related to index 'Internal' and doc 'Memory' …
Attempt To Free Heap Memory:
Impose A Limit On Heap Size:
Reference code from sqlite3:
(static) MK_I64 Sq3HardHeapLimit64(MK_I64 N)top Impose A Limit On Heap Size … → API: Sq3HardHeapLimit64
These interfaces impose limits on the amount of heap memory that will be by all database connections within a single process.
The Sq3SoftHeapLimit64() interface sets and/or queries the soft limit on the amount of heap memory that may be allocated by SQLite. SQLite strives to keep heap memory utilization below the soft heap limit by reducing the number of pages held in the page cache as heap memory usages approaches the limit. The soft heap limit is "soft" because even though SQLite strives to stay below the limit, it will exceed the limit rather than generate an SQ3_RESULT_NOMEM error. In other words, the soft heap limit is advisory only.
The Sq3HardHeapLimit64(N) interface sets a hard upper bound of N bytes on the amount of memory that will be allocated. The Sq3HardHeapLimit64(N) interface is similar to Sq3SoftHeapLimit64(N) except that memory allocations will fail when the hard heap limit is reached.
The return value from both Sq3SoftHeapLimit64() and Sq3HardHeapLimit64() is the size of the heap limit prior to the call, or negative in the case of an error. If the argument N is negative then no change is made to the heap limit. Hence, the current size of heap limits can be determined by invoking Sq3SoftHeapLimit64(-1) or Sq3HardHeapLimit64(-1).
Setting the heap limits to zero disables the heap limiter mechanism.
The soft heap limit may not be greater than the hard heap limit. If the hard heap limit is enabled and if sqlite3_soft_heap_limit(N) is invoked with a value of N that is greater than the hard heap limit, the soft heap limit is set to the value of the hard heap limit. The soft heap limit is automatically enabled whenever the hard heap limit is enabled. When Sq3HardHeapLimit64(N) is invoked and the soft heap limit is outside the range of 1..N, then the soft heap limit is set to N. Invoking Sq3SoftHeapLimit64(0) when the hard heap limit is enabled makes the soft heap limit equal to the hard heap limit.
The memory allocation limits can also be adjusted using PRAGMA soft_heap_limit and PRAGMA hard_heap_limit.
The heap limits are not enforced in the current implementation if one or more of following conditions are true:
The circumstances under which SQLite will enforce the heap limits may changes in future releases of SQLite.
Reference code from sqlite3:
(static) enum MkErrorE Sq3ReleaseMemory(MK_I32 N)top Attempt To Free Heap Memory … → API: Sq3ReleaseMemory
The Sq3ReleaseMemory() interface attempts to free N bytes of heap memory by deallocating non-essential memory allocations held by the database library. Memory used to cache database pages to improve performance is an example of non-essential memory. Sq3ReleaseMemory() returns the number of bytes actually freed, which might be more or less than the amount requested. The Sq3ReleaseMemory() routine is a no-op returning zero if SQLite is not compiled with SQLITE_ENABLE_MEMORY_MANAGEMENT.
See also: Sq3LiteDbReleaseMemory ()
Reference code from sqlite3:
(static) MK_I64 Sq3SoftHeapLimit64(MK_I64 N)top Impose A Limit On Heap Size … → API: Sq3SoftHeapLimit64
read more at 'Sq3HardHeapLimit64'
C-API: Sq3Lite_Internal_String_C_API - Sq3Lite PACKAGE - functions related to index 'Internal' and doc 'String' …
String Comparison:
String Globbing:
String LIKE Matching:
Reference code from sqlite3:
(static) MK_I32 Sq3StrGlob(MK_STRN zGlob, MK_STRN zStr)top String Globbing … → API: Sq3StrGlob
The Sq3StrGlob (P,X) interface returns zero if and only if string X matches the GLOB pattern P. The definition of GLOB pattern matching used in Sq3StrGlob (P,X) is the same as for the "X GLOB P" operator in the SQL dialect understood by SQLite. The Sq3StrGlob (P,X) function is case sensitive.
Note that this routine returns zero on a match and non-zero if the strings do not match, the same as Sq3StrIcmp () and Sq3StrNicmp ().
See also: Sq3StrLike ().
Reference code from sqlite3:
(static) MK_I32 Sq3StrIcmp(MK_STRN arg0, MK_STRN arg1)top String Comparison … → API: Sq3StrIcmp
The Sq3StrIcmp () and Sq3StrNicmp () APIs allow applications and extensions to compare the contents of two buffers containing UTF-8 strings in a case-independent fashion, using the same definition of "case independence" that SQLite uses internally when comparing identifiers.
Reference code from sqlite3:
(static) MK_I32 Sq3StrLike(MK_STRN zGlob, MK_STRN zStr, MK_I32 cEsc)top String LIKE Matching … → API: Sq3StrLike
The Sq3StrLike (P,X,E) interface returns zero if and only if string X matches the LIKE pattern P with escape character E. The definition of LIKE pattern matching used in Sq3StrLike (P,X,E) is the same as for the "X LIKE P ESCAPE E" operator in the SQL dialect understood by SQLite. For "X LIKE P" without the ESCAPE clause, set the E parameter of Sq3StrLike (P,X,E) to 0. As with the LIKE operator, the Sq3StrLike (P,X,E) function is case insensitive - equivalent upper and lower case ASCII characters match one another.
The Sq3StrLike (P,X,E) function matches Unicode characters, though only ASCII characters are case folded.
Note that this routine returns zero on a match and non-zero if the strings do not match, the same as Sq3StrIcmp () and Sq3StrNicmp ().
See also: Sq3StrGlob ().
Reference code from sqlite3:
(static) MK_I32 Sq3StrNicmp(MK_STRN arg0, MK_STRN arg1, MK_I32 arg2)top String Comparison … → API: Sq3StrNicmp
C-API: Sq3Lite_Version_C_API - Sq3Lite PACKAGE - get version information …
(static) MK_STRN Sq3Libversion()top Run-Time Library Version Numbers … → API: Sq3Libversion
These interfaces provide the same information as the SQLITE_VERSION, SQLITE_VERSION_NUMBER, and SQLITE_SOURCE_ID C preprocessor macros but are associated with the library instead of the header file. Cautious programmers might include assert() statements in their application to verify that values returned by these interfaces match the macros in the header, and thus ensure that the application is compiled with matching library and header files.
assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER ); assert( strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 ); assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
The sqlite3_version[] string constant contains the text of SQLITE_VERSION macro. The Sq3Libversion() function returns a pointer to the to the sqlite3_version[] string constant. The Sq3Libversion() function is provided for use in DLLs since DLL users usually do not have direct access to string constants within the DLL. The Sq3LibversionNumber() function returns an integer equal to SQLITE_VERSION_NUMBER. The Sq3Sourceid() function returns a pointer to a string constant whose value is the same as the SQLITE_SOURCE_ID C preprocessor macro. Except if SQLite is built using an edited copy of the amalgamation, then the last four characters of the hash might be different from SQLITE_SOURCE_ID.
See also: sqlite_version () and sqlite_source_id ().
Reference code from sqlite3:
(static) enum MkErrorE Sq3LibversionNumber()top Run-Time Library Version Numbers … → API: Sq3LibversionNumber
(static) MK_STRN Sq3Sourceid()top Run-Time Library Version Numbers … → API: Sq3Sourceid
C-API: Sq3Lite_Vfs_C_API - Sq3Lite PACKAGE - work with the virtual-file-system …
(static,hide) SQ3_FILENAME Sq3CreateFilename(MK_STRN zDatabase, MK_STRN zJournal, MK_STRN zWal, MK_I32 azParam_num, MK_STRN *azParam)top Create and Destroy VFS Filenames … → API: Sq3CreateFilename
These interfaces are provided for use by VFS shim implementations and are not useful outside of that context.
The Sq3CreateFilename(D,J,W,N,P) allocates memory to hold a version of database filename D with corresponding journal file J and WAL file W and with N URI parameters key/values pairs in the array P. The result from Sq3CreateFilename(D,J,W,N,P) is a pointer to a database filename that is safe to pass to routines like:
If a memory allocation error occurs, Sq3CreateFilename() might return a NULL pointer. The memory obtained from Sq3CreateFilename(X) must be released by a corresponding call to Sq3FreeFilename(Y).
The P parameter in Sq3CreateFilename(D,J,W,N,P) should be an array of 2*N pointers to strings. Each pair of pointers in this array corresponds to a key and value for a query parameter. The P parameter may be a NULL pointer if N is zero. None of the 2*N pointers in the P array may be NULL pointers and key pointers should not be empty strings. None of the D, J, or W parameters to Sq3CreateFilename(D,J,W,N,P) may be NULL pointers, though they can be empty strings.
The Sq3FreeFilename(Y) routine releases a memory allocation previously obtained from Sq3CreateFilename(). Invoking Sq3FreeFilename(Y) where Y is a NULL pointer is a harmless no-op.
If the Y parameter to Sq3FreeFilename(Y) is anything other than a NULL pointer or a pointer previously acquired from Sq3CreateFilename(), then bad things such as heap corruption or segfaults may occur. The value Y should not be used again after Sq3FreeFilename(Y) has been called. This means that if the sqlite3_vfs.xOpen() method of a VFS has been called using Y, then the corresponding sqlite3_module.xClose() method should also be invoked prior to calling Sq3FreeFilename(Y).
Reference code from sqlite3:
(static) MK_STRN Sq3FilenameDatabase(SQ3_FILENAME F)top Translate filenames … → API: Sq3FilenameDatabase
These routines are available to custom VFS implementations for translating filenames between the main database file, the journal file, and the WAL file.
If F is the name of an sqlite database file, journal file, or WAL file passed by the SQLite core into the VFS, then Sq3FilenameDatabase(F) returns the name of the corresponding database file.
If F is the name of an sqlite database file, journal file, or WAL file passed by the SQLite core into the VFS, or if F is a database filename obtained from Sq3LiteDbFilename (), then Sq3FilenameJournal(F) returns the name of the corresponding rollback journal file.
If F is the name of an sqlite database file, journal file, or WAL file that was passed by the SQLite core into the VFS, or if F is a database filename obtained from Sq3LiteDbFilename (), then Sq3FilenameWal(F) returns the name of the corresponding WAL file.
In all of the above, if F is not the name of a database, journal or WAL filename passed into the VFS from the SQLite core and F is not the return value from Sq3LiteDbFilename (), then the result is undefined and is likely a memory access violation.
Reference code from sqlite3:
(static) MK_STRN Sq3FilenameJournal(SQ3_FILENAME F)top Translate filenames … → API: Sq3FilenameJournal
read more at 'Sq3FilenameDatabase'
(static) MK_STRN Sq3FilenameWal(SQ3_FILENAME F)top Translate filenames … → API: Sq3FilenameWal
read more at 'Sq3FilenameDatabase'
(static) void Sq3FreeFilename(SQ3_FILENAME arg0)top Create and Destroy VFS Filenames … → API: Sq3FreeFilename
read more at 'Sq3CreateFilename'
(static) enum MkErrorE Sq3UriBoolean(SQ3_FILENAME z, MK_STRN zParam, MK_I32 bDefault)top Obtain Values For URI Parameters … → API: Sq3UriBoolean
These are utility routines, useful to custom VFS implementations, that check if a database file was a URI that contained a specific query parameter, and if so obtains the value of that query parameter.
The first parameter to these interfaces (hereafter referred to as F) must be one of:
If the F parameter is not one of the above, then the behavior is undefined and probably undesirable. Older versions of SQLite were more tolerant of invalid F parameters than newer versions.
If F is a suitable filename (as described in the previous paragraph) and if P is the name of the query parameter, then Sq3UriParameter(F,P) returns the value of the P parameter if it exists or a NULL pointer if P does not appear as a query parameter on F. If P is a query parameter of F and it has no explicit value, then Sq3UriParameter(F,P) returns a pointer to an empty string.
The Sq3UriBoolean(F,P,B) routine assumes that P is a boolean parameter and returns true (1) or false (0) according to the value of P. The Sq3UriBoolean(F,P,B) routine returns true (1) if the value of query parameter P is one of "yes", "true", or "on" in any case or if the value begins with a non-zero number. The Sq3UriBoolean(F,P,B) routines returns false (0) if the value of query parameter P is one of "no", "false", or "off" in any case or if the value begins with a numeric zero. If P is not a query parameter on F or if the value of P does not match any of the above, then Sq3UriBoolean(F,P,B) returns (B!=0).
The Sq3UriInt64(F,P,D) routine converts the value of P into a 64-bit signed integer and returns that integer, or D if P does not exist. If the value of P is something other than an integer, then zero is returned.
The Sq3UriKey(F,N) returns a pointer to the name (not the value) of the N-th query parameter for filename F, or a NULL pointer if N is less than zero or greater than the number of query parameters minus 1. The N value is zero-based so N should be 0 to obtain the name of the first query parameter, 1 for the second parameter, and so forth.
If F is a NULL pointer, then Sq3UriParameter(F,P) returns NULL and Sq3UriBoolean(F,P,B) returns B. If F is not a NULL pointer and is not a database file pathname pointer that the SQLite core passed into the xOpen VFS method, then the behavior of this routine is undefined and probably undesirable.
Beginning with SQLite version 3.31.0 (dateof:3.31.0) the input F parameter can also be the name of a rollback journal file or WAL file in addition to the main database file. Prior to version 3.31.0, these routines would only work if F was the name of the main database file. When the F parameter is the name of the rollback journal or WAL file, it has access to all the same query parameters as were found on the main database file.
See the URI filename documentation for additional information.
Reference code from sqlite3:
(static) MK_I64 Sq3UriInt64(SQ3_FILENAME arg0, MK_STRN arg1, MK_I64 arg2)top Obtain Values For URI Parameters … → API: Sq3UriInt64
(static) MK_STRN Sq3UriKey(SQ3_FILENAME z, MK_I32 N)top Obtain Values For URI Parameters … → API: Sq3UriKey
(static) MK_STRN Sq3UriParameter(SQ3_FILENAME z, MK_STRN zParam)top Obtain Values For URI Parameters … → API: Sq3UriParameter
C-API: Sq3Lite_Error_C_API - Sq3Lite PACKAGE - work with an error …
Error handling in libsq3lite.
The error signals the end of an operation with an undesirable result or state.
(static) MK_BOOL Sq3ErrorCheckI(enum Sq3ErrorE ret)top check if ret signal an error … → API: Sq3ErrorCheckI
| [in] | ret | input for libsq3lite error-check |
(static,hide) enum MkErrorE Sq3LiteErrorToMQ(MK_OBJN const obj, MK_STRN const func, MK_STRN const file, MK_I32 const line)top if a libsq3lite funtion return a MkErrorE use this function to convert the libsq3lite-error into the libmkkernel-error … → API: Sq3LiteErrorToMQ
| Sq3LiteC CLASS | |||
| Define | Sq3LiteC - low level definition, access and cast … | ||
| Export | Sq3LiteC - Export class functions … | ||
| Introspection | Sq3LiteC - Introspection class functions … | ||
| Misc | Sq3LiteC - Misc class functions … | ||
| Sq3LiteC TOR | |||
| OpenV2 | Opening A New Database Connection … | ||
| CloseV2 | Closing A Database Connection … | ||
| PrepareV2 | Compiling An SQL Statement … | ||
| Sq3LiteC CONFIG | |||
| BusyHandler | Register A Callback To Handle SQLITE_BUSY Errors … | ||
| BusyTimeout | Set A Busy Timeout … | ||
| CommitHook | Commit And Rollback Notification Callbacks … | ||
| DeclareVtab | Declare The Schema Of A Virtual Table … | ||
| EnableLoadExtension | Enable Or Disable Extension Loading … | ||
| ExtendedResultCodes | Enable Or Disable Extended Result Codes … | ||
| Limit | Run-time Limits … | ||
| LoadExtension | Load An Extension … | ||
| RollbackHook | Commit And Rollback Notification Callbacks … | ||
| UpdateHook | Data Change Notification Callbacks … | ||
| Sq3LiteC EXECUTION | |||
| Sleep | Suspend Execution For A Short Time … | ||
| Exec | One-Step Query Execution Interface … | ||
| ExecV2 | The Sq3LiteExecV2() interface is a convenience wrapper around Sq3StmtPrepareV2(), Sq3StmtStep(), and Sq3StmtFinalize(), that allows an application to run multiple statements of SQL without having to use a lot of C code. | ||
| Sq3LiteC INFO | |||
| GetAutocommit | Test For Auto-Commit Mode … | ||
| LastInsertRowid | Last Insert Rowid … | ||
| TxnState | Determine the transaction state of a database … | ||
| VtabOnConflict | Determine The Virtual Table Conflict Policy … | ||
| Sq3LiteC MODIFY | |||
| Create | Sq3LiteC - functions related to index 'Modify' and doc 'Create' … | ||
| Wal | Sq3LiteC - functions related to index 'Modify' and doc 'Wal' … | ||
| Sq3LiteC QUERY | |||
| Interrupt | Interrupt A Long-Running Query … | ||
| IsInterrupted | Interrupt A Long-Running Query … | ||
| Sq3LiteC ROW | |||
| Changes | Count The Number Of Rows Modified … | ||
| Changes64 | Count The Number Of Rows Modified … | ||
| SetLastInsertRowid | Set the Last Insert Rowid value … | ||
| TotalChanges | Total Number Of Rows Modified … | ||
| TotalChanges64 | Total Number Of Rows Modified … | ||
| Sq3LiteC ERROR | |||
| ErrStr | Error Codes And Messages … | ||
| ErrCode | Error Codes And Messages … | ||
| ErrMsg | Error Codes And Messages … | ||
| ErrorOffset | Error Codes And Messages … | ||
| ExtendetErrCode | Error Codes And Messages … | ||
| SystemErrno | Low-level system error code … | ||
| Sq3LiteC MISC | |||
| AutovacuumPages | Autovacuum Compaction Amount Callback … | ||
| CollationNeeded | Collation Needed Callbacks … | ||
| DbCacheflush | Flush caches to disk mid-transaction … | ||
| DbFilename | Return The Filename For A Database Connection … | ||
| DbName | Return The Schema Name For A Database Connection … | ||
| DbReadonly | Determine if a database is read-only … | ||
| DbReleaseMemory | Free Memory Used By A Database Connection … | ||
| DbStatus | Database Connection Status … | ||
| DbStatusBFL | Database Connection Status … | ||
| Deserialize | Deserialize a database … | ||
| DeserializeHide | Deserialize a database … | ||
| DropModules | Remove Unnecessary Virtual Table Implementations … | ||
| DropModulesHide | Remove Unnecessary Virtual Table Implementations … | ||
| FileControl | Low-Level Control Of Database Files … | ||
| Log | log the lite … | ||
| OverloadFunction | Overload A Function For A Virtual Table … | ||
| Serialize | Serialize a database … | ||
| SerializeHide | Serialize a database … | ||
| TableColumnMetadata | Extract Metadata About A Column Of A Table … | ||
| VtabConfig | Virtual Table Interface Configuration … | ||
C-API: Sq3LiteC_C_API - Sq3LiteC - the class known as sq3lite or Lite defined by Sq3LiteS …
Struct to represent the data of the Sq3LiteC …
Database Connection Handle …
Each open SQLite database is represented by a pointer to an instance of the opaque structure named "sqlite3". It is useful to think of an Sq3LiteC pointer as an object. The sqlite3_open (), sqlite3_open16 (), and Sq3LiteOpenV2 () interfaces are its constructors, and sqlite3_close () and Sq3LiteCloseV2 () are its destructors. There are many other interfaces (such as Sq3StmtPrepareV2 (), sqlite3_create_function (), and Sq3LiteBusyTimeout () to name but three) that are methods on an Sq3LiteC object.
Reference code from sqlite3:
| Lite | cast a unknown-object into an Sq3LiteS pointer or NULL if not possible | ||
| LiteCheck | check Sq3LiteS -> MkObjectS::signature … | ||
| LiteCheckO | check Sq3LiteS -> MkObjectS::signature … | ||
| LiteN | (const) cast a unknown-object into an Sq3LiteS pointer or NULL if not possible | ||
| HandleResolve | Handle-Resolve-Slot - return a Sq3LiteC from netHdl or MK_NULL if invalid… | ||
| HandleGet | Handle-Get-Slot - returns a export-hdl to the Sq3LiteC useable for external storage | ||
| Instances | get head-instance from linked-list of Sq3LiteS type … | ||
| Next | get next instance from linked-list of Sq3LiteS type | ||
| Prev | get previous instance from linked-list of Sq3LiteS type | ||
| GetNull | Null-Slot - return a Sq3LiteC typed | ||
C-API: Sq3LiteC_Class_C_API - Sq3LiteC - define the class …
C-API: Sq3LiteC_Class_Define_C_API - Sq3LiteC - low level definition, access and cast …
(static,hide) SQ3_LITE Sq3Lite(MK_MNG mng)top cast a unknown-object into an Sq3LiteS pointer or NULL if not possible → API: Sq3Lite
(static,hide) MK_BOOL Sq3LiteCheck(MK_MNGN mng)top check Sq3LiteS -> MkObjectS::signature … → API: Sq3LiteCheck
(static,hide) MK_BOOL Sq3LiteCheckO(MK_OBJN obj)top check Sq3LiteS -> MkObjectS::signature … → API: Sq3LiteCheckO
(static,hide) SQ3_LITEN Sq3LiteN(MK_MNGN mng)top (const) cast a unknown-object into an Sq3LiteS pointer or NULL if not possible → API: Sq3LiteN
Sq3LiteC - Export class functions …
(static,runtime) SQ3_LITE Sq3LiteHandleResolve(MK_HDL const netHdl)top Handle-Resolve-Slot - return a Sq3LiteC from netHdl or MK_NULL if invalid… → API: Sq3LiteHandleResolve_RT
The Sq3LiteHandleResolve undo the Sq3LiteHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).
| [in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
| [in] | netHdl | handle former exported with Sq3LiteHandleGet |
MK_NULL if netHdl is invalid (runtime) MK_HDL Sq3LiteHandleGet(SQ3_LITE const lite)top Handle-Get-Slot - returns a export-hdl to the Sq3LiteC useable for external storage → API: Sq3LiteHandleGet_RT
The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the Sq3LiteHandleResolve.
The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.
example: The export-hdl is used in rpc to identify an object across the network.
| [in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
| [in] | lite | Programming-Language-Micro-Kernel (PLMK) instance from sqlite3 |
Sq3LiteC - Introspection class functions …
(static,runtime) SQ3_LITE Sq3LiteInstances()top get head-instance from linked-list of Sq3LiteS type … → API: Sq3LiteInstances_RT
The head-instance is the last instance created.
SQ3_LITE Sq3LiteNext(SQ3_LITE const lite)top get next instance from linked-list of Sq3LiteS type → API: Sq3LiteNext
SQ3_LITE Sq3LitePrev(SQ3_LITE const lite)top get previous instance from linked-list of Sq3LiteS type → API: Sq3LitePrev
Sq3LiteC - Misc class functions …
(static) SQ3_LITE Sq3LiteGetNull()top Null-Slot - return a Sq3LiteC typed NULL instance … → API: Sq3LiteGetNull
C-API: Sq3LiteC_TOR_C_API - Sq3LiteC - various functions to create, initialize and destroy …
(constructor,static) enum MkErrorE Sq3LiteOpenV2(MK_STRN filename, SQ3_LITE *ppDb, enum Sq3OpenEF flags, MK_STRN zVfs)top Opening A New Database Connection … → API: Sq3LiteOpenV2
These routines open an SQLite database file as specified by the filename argument. The filename argument is interpreted as UTF-8 for sqlite3_open() and Sq3LiteOpenV2() and as UTF-16 in the native byte order for sqlite3_open16(). A database connection handle is usually returned in *ppDb, even if an error occurs. The only exception is that if SQLite is unable to allocate memory to hold the Sq3LiteC object, a NULL will be written into *ppDb instead of a pointer to the Sq3LiteC object. If the database is opened (and/or created) successfully, then SQ3_RESULT_OK is returned. Otherwise an error code is returned. The Sq3LiteErrMsg () or sqlite3_errmsg16 () routines can be used to obtain an English language description of the error following a failure of any of the sqlite3_open() routines.
The default encoding will be UTF-8 for databases created using sqlite3_open() or Sq3LiteOpenV2(). The default encoding for databases created using sqlite3_open16() will be UTF-16 in the native byte order.
Whether or not an error occurs when it is opened, resources associated with the database connection handle should be released by passing it to sqlite3_close () when it is no longer required.
The Sq3LiteOpenV2() interface works like sqlite3_open() except that it accepts two additional parameters for additional control over the new database connection. The flags parameter to Sq3LiteOpenV2() must include, at a minimum, one of the following three flag combinations:
The database is opened in read-only mode. If the database does not already exist, an error is returned.
The database is opened for reading and writing if possible, or reading only if the file is write protected by the operating system. In either case the database must already exist, otherwise an error is returned. For historical reasons, if opening in read-write mode fails due to OS-level permissions, an attempt is made to open it in read-only mode. Sq3LiteDbReadonly () can be used to determine whether the database is actually read-write.
In addition to the required flags, the following optional flags are also supported:
The filename can be interpreted as a URI if this flag is set.
The database will be opened as an in-memory database. The database is named by the "filename" argument for the purposes of cache-sharing, if shared cache mode is enabled, but the "filename" is otherwise ignored.
The new database connection will use the "multi-thread" threading mode. This means that separate threads are allowed to use SQLite at the same time, as long as each thread is using a different database connection.
The new database connection will use the "serialized" threading mode. This means the multiple threads can safely attempt to use the same database connection at the same time. (Mutexes will block any actual concurrency, but in this mode there is no harm in trying.)
The database is opened shared cache enabled, overriding the default shared cache setting provided by sqlite3_enable_shared_cache (). The use of shared cache mode is discouraged and hence shared cache capabilities may be omitted from many builds of SQLite. In such cases, this option is a no-op.
The database is opened shared cache disabled, overriding the default shared cache setting provided by sqlite3_enable_shared_cache ().
The database connection comes up in "extended result code mode". In other words, the database behaves has if Sq3LiteExtendedResultCodes (db,1) where called on the database connection as soon as the connection is created. In addition to setting the extended result code mode, this flag also causes Sq3LiteOpenV2 () to return an extended result code.
If the 3rd parameter to Sq3LiteOpenV2() is not one of the required combinations shown above optionally combined with other SQ3_OPEN_* bits then the behavior is undefined. Historic versions of SQLite have silently ignored surplus bits in the flags parameter to Sq3LiteOpenV2(), however that behavior might not be carried through into future versions of SQLite and so applications should not rely upon it. Note in particular that the SQ3_OPEN_EXCLUSIVE flag is a no-op for Sq3LiteOpenV2(). The SQ3_OPEN_EXCLUSIVE does not cause the open to fail if the database already exists. The SQ3_OPEN_EXCLUSIVE flag is intended for use by the VFS interface only, and not by Sq3LiteOpenV2().
The fourth parameter to Sq3LiteOpenV2() is the name of the sqlite3_vfs object that defines the operating system interface that the new database connection should use. If the fourth parameter is a NULL pointer then the default sqlite3_vfs object is used.
If the filename is ":memory:", then a private, temporary in-memory database is created for the connection. This in-memory database will vanish when the database connection is closed. Future versions of SQLite might make use of additional special filenames that begin with the ":" character. It is recommended that when a database filename actually does begin with a ":" character you should prefix the filename with a pathname such as "./" to avoid ambiguity.
If the filename is an empty string, then a private, temporary on-disk database will be created. This private database will be automatically deleted as soon as the database connection is closed.
If URI filename interpretation is enabled, and the filename argument begins with "file:", then the filename is interpreted as a URI. URI filename interpretation is enabled if the SQ3_OPEN_URI flag is set in the third argument to Sq3LiteOpenV2(), or if it has been enabled globally using the SQ3_CONFIG_URI option with the sqlite3_config () method or by the SQLITE_USE_URI compile-time option. URI filename interpretation is turned off by default, but future releases of SQLite might enable URI filename interpretation by default. See "<a href="https://www.sqlite.org/uri.html">URI filenames</a>" for additional information.
URI filenames are parsed according to RFC 3986. If the URI contains an authority, then it must be either an empty string or the string "localhost". If the authority is not an empty string or "localhost", an error is returned to the caller. The fragment component of a URI, if present, is ignored.
SQLite uses the path component of the URI as the name of the disk file which contains the database. If the path begins with a '/' character, then it is interpreted as an absolute path. If the path does not begin with a '/' (meaning that the authority section is omitted from the URI) then the path is interpreted as a relative path. On windows, the first component of an absolute path is a drive specification (e.g. "C:").
The query component of a URI may contain parameters that are interpreted either by SQLite itself, or by a custom VFS implementation. SQLite and its built-in VFSes interpret the following query parameters:
vfs: The "vfs" parameter may be used to specify the name of a VFS object that provides the operating system interface that should be used to access the database file on disk. If this option is set to an empty string the default VFS object is used. Specifying an unknown VFS is an error. If Sq3LiteOpenV2() is used and the vfs option is present, then the VFS specified by the option takes precedence over the value passed as the fourth parameter to Sq3LiteOpenV2().
mode: The mode parameter may be set to either "ro", "rw", "rwc", or "memory". Attempting to set it to any other value is an error. If "ro" is specified, then the database is opened for read-only access, just as if the SQ3_OPEN_READONLY flag had been set in the third argument to Sq3LiteOpenV2(). If the mode option is set to "rw", then the database is opened for read-write (but not create) access, as if SQ3_OPEN_READWRITE (but not SQ3_OPEN_CREATE) had been set. Value "rwc" is equivalent to setting both SQ3_OPEN_READWRITE and SQ3_OPEN_CREATE. If the mode option is set to "memory" then a pure in-memory database that never reads or writes from disk is used. It is an error to specify a value for the mode parameter that is less restrictive than that specified by the flags passed in the third parameter to Sq3LiteOpenV2().
cache: The cache parameter may be set to either "shared" or "private". Setting it to "shared" is equivalent to setting the SQ3_OPEN_SHAREDCACHE bit in the flags argument passed to Sq3LiteOpenV2(). Setting the cache parameter to "private" is equivalent to setting the SQ3_OPEN_PRIVATECACHE bit. If Sq3LiteOpenV2() is used and the "cache" parameter is present in a URI filename, its value overrides any behavior requested by setting SQ3_OPEN_PRIVATECACHE or SQ3_OPEN_SHAREDCACHE flag.
psow: The psow parameter indicates whether or not the powersafe overwrite property does or does not apply to the storage media on which the database file resides.
nolock: The nolock parameter is a boolean query parameter which if set disables file locking in rollback journal modes. This is useful for accessing a database on a filesystem that does not support locking. Caution: Database corruption might result if two or more processes write to the same database and any one of those processes uses nolock=1.
immutable: The immutable parameter is a boolean query parameter that indicates that the database file is stored on read-only media. When immutable is set, SQLite assumes that the database file cannot be changed, even by a process with higher privilege, and so the database is opened read-only and all locking and change detection is disabled. Caution: Setting the immutable property on a database file that does in fact change can result in incorrect query results and/or SQ3_RESULT_CORRUPT errors. See also: SQ3_IOCAP_IMMUTABLE.
Specifying an unknown parameter in the query component of a URI is not an error. Future versions of SQLite might understand additional query parameters. See "<a href="https://www.sqlite.org/uri.html#coreqp">query parameters with special meaning to SQLite</a>" for additional information.
| URI filenames | Results |
|---|---|
| file:data.db | Open the file "data.db" in the current directory. |
| file:/home/fred/data.db file:///home/fred/data.db file://localhost/home/fred/data.db | Open the database file "/home/fred/data.db". |
| file://darkstar/home/fred/data.db | An error. "darkstar" is not a recognized authority. |
| file:///C:/Documents%20and%20Settings/fred/Desktop/data.db | Windows only: Open the file "data.db" on fred's desktop on drive C:. Note that the %20 escaping in this example is not strictly necessary - space characters can be used literally in URI filenames. |
| file:data.db?mode=ro&cache=private | Open file "data.db" in the current directory for read-only access. Regardless of whether or not shared-cache mode is enabled by default, use a private cache. |
| file:/home/fred/data.db?vfs=unix-dotfile | Open file "/home/fred/data.db". Use the special VFS "unix-dotfile" that uses dot-files in place of posix advisory locking. |
| file:data.db?mode=readonly | An error. "readonly" is not a valid option for the "mode" parameter. Use "ro" instead: "file:data.db?mode=ro". |
URI hexadecimal escape sequences (HH) are supported within the path and query components of a URI. A hexadecimal escape sequence consists of a percent sign - "%" - followed by exactly two hexadecimal digits specifying an octet value. Before the path or query components of a URI filename are interpreted, they are encoded using UTF-8 and all hexadecimal escape sequences replaced by a single byte containing the corresponding octet. If this process generates an invalid UTF-8 encoding, the results are undefined.
Note to Windows users: The encoding used for the filename argument of sqlite3_open() and Sq3LiteOpenV2() must be UTF-8, not whatever codepage is currently defined. Filenames containing international characters must be converted to UTF-8 prior to passing them into sqlite3_open() or Sq3LiteOpenV2().
Note to Windows Runtime users: The temporary directory must be set prior to calling sqlite3_open() or Sq3LiteOpenV2(). Otherwise, various features that require the use of temporary files may fail.
See also: sqlite3_temp_directory
Reference code from sqlite3:
(destructor) enum MkErrorE Sq3LiteCloseV2(SQ3_LITE sq3lite)top Closing A Database Connection … → API: Sq3LiteCloseV2
The sqlite3_close() and Sq3LiteCloseV2() routines are destructors for the Sq3LiteC object. Calls to sqlite3_close() and Sq3LiteCloseV2() return SQ3_RESULT_OK if the Sq3LiteC object is successfully destroyed and all associated resources are deallocated.
Ideally, applications should finalize all prepared statements, close all BLOB handles, and finish all sqlite3_backup objects associated with the Sq3LiteC object prior to attempting to close the object. If the database connection is associated with unfinalized prepared statements, BLOB handlers, and/or unfinished sqlite3_backup objects then sqlite3_close() will leave the database connection open and return SQ3_RESULT_BUSY. If Sq3LiteCloseV2() is called with unfinalized prepared statements, unclosed BLOB handlers, and/or unfinished Sq3Backup's, it returns SQ3_RESULT_OK regardless, but instead of deallocating the database connection immediately, it marks the database connection as an unusable "zombie" and makes arrangements to automatically deallocate the database connection after all prepared statements are finalized, all BLOB handles are closed, and all backups have finished. The Sq3LiteCloseV2() interface is intended for use with host languages that are garbage collected, and where the order in which destructors are called is arbitrary.
If an Sq3LiteC object is destroyed while a transaction is open, the transaction is automatically rolled back.
The C parameter to sqlite3_close (C) and Sq3LiteCloseV2 (C) must be either a NULL pointer or an Sq3LiteC object pointer obtained from sqlite3_open (), sqlite3_open16 (), or Sq3LiteOpenV2 (), and not previously closed. Calling sqlite3_close() or Sq3LiteCloseV2() with a NULL pointer argument is a harmless no-op.
Reference code from sqlite3:
(constructor) enum MkErrorE Sq3LitePrepareV2(SQ3_LITE db, MkStringR zSql, SQ3_STMT *ppStmt)top Compiling An SQL Statement … → API: Sq3LitePrepareV2
This is an enhanced version of Sq3StmtPrepareV2Hide. The last argument pzTail is stored into the Sq3StmtC class Sq3StmtS::pzTail attribute and can be accessed with Sq3StmtGetPzTail.
| [in] | db | the Sq3LiteC instance to work on a database |
| [in] | zSql | The statement to be compiled, encoded as UTF-8 |
| [out] | ppStmt | The new Sq3StmtC instance |
If the database schema changes, instead of returning SQ3_RESULT_SCHEMA as it always used to do, Sq3StmtStep () will automatically recompile the SQL statement and try to run it again. As many as SQLITE_MAX_SCHEMA_RETRY retries will occur before Sq3StmtStep() gives up and returns an error.
When an error occurs, Sq3StmtStep () will return one of the detailed error codes or extended error codes. The legacy behavior was that Sq3StmtStep () would only return a generic SQ3_RESULT_ERROR result code and the application would have to make a second call to Sq3StmtReset () in order to find the underlying cause of the problem. With the "v2" prepare interfaces, the underlying reason for the error is returned immediately.
C-API: Sq3LiteC_Config_C_API - Sq3LiteC - configure the class …
(hide) enum MkErrorE Sq3LiteBusyHandler(SQ3_LITE sq3lite, Sq3Fupu_Sq3LiteBusyHandler_arg1 arg1, MK_PTR arg2)top Register A Callback To Handle SQLITE_BUSY Errors … → API: Sq3LiteBusyHandler
The Sq3LiteBusyHandler(D,X,P) routine sets a callback function X that might be invoked with argument P whenever an attempt is made to access a database table associated with database connection D when another thread or process has the table locked. The Sq3LiteBusyHandler() interface is used to implement Sq3LiteBusyTimeout () and PRAGMA busy_timeout.
If the busy callback is NULL, then SQ3_RESULT_BUSY is returned immediately upon encountering the lock. If the busy callback is not NULL, then the callback might be invoked with two arguments.
The first argument to the busy handler is a copy of the void* pointer which is the third argument to Sq3LiteBusyHandler(). The second argument to the busy handler callback is the number of times that the busy handler has been invoked previously for the same locking event. If the busy callback returns 0, then no additional attempts are made to access the database and SQ3_RESULT_BUSY is returned to the application. If the callback returns non-zero, then another attempt is made to access the database and the cycle repeats.
The presence of a busy handler does not guarantee that it will be invoked when there is lock contention. If SQLite determines that invoking the busy handler could result in a deadlock, it will go ahead and return SQ3_RESULT_BUSY to the application instead of invoking the busy handler. Consider a scenario where one process is holding a read lock that it is trying to promote to a reserved lock and a second process is holding a reserved lock that it is trying to promote to an exclusive lock. The first process cannot proceed because it is blocked by the second and the second process cannot proceed because it is blocked by the first. If both processes invoke the busy handlers, neither will make any progress. Therefore, SQLite returns SQ3_RESULT_BUSY for the first process, hoping that this will induce the first process to release its read lock and allow the second process to proceed.
The default busy callback is NULL.
There can only be a single busy handler defined for each database connection. Setting a new busy handler clears any previously set handler. Note that calling Sq3LiteBusyTimeout () or evaluating PRAGMA busy_timeout=N will change the busy handler and thus clear any previously set busy handler.
The busy callback should not take any actions which modify the database connection that invoked the busy handler. In other words, the busy handler is not reentrant. Any such actions result in undefined behavior.
A busy handler must not close the database connection or prepared statement that invoked the busy handler.
Reference code from sqlite3:
enum MkErrorE Sq3LiteBusyTimeout(SQ3_LITE sq3lite, MK_I32 ms)top Set A Busy Timeout … → API: Sq3LiteBusyTimeout
This routine sets a busy handler that sleeps for a specified amount of time when a table is locked. The handler will sleep multiple times until at least "ms" milliseconds of sleeping have accumulated. After at least "ms" milliseconds of sleeping, the handler returns 0 which causes Sq3StmtStep () to return SQ3_RESULT_BUSY.
Calling this routine with an argument less than or equal to zero turns off all busy handlers.
There can only be a single busy handler for a particular database connection at any given moment. If another busy handler was defined (using Sq3LiteBusyHandler ()) prior to calling this routine, that other busy handler is cleared.
See also: PRAGMA busy_timeout
Reference code from sqlite3:
(hide) MK_PTR Sq3LiteCommitHook(SQ3_LITE sq3lite, Sq3Fupu_Sq3LiteCommitHook_arg1 arg1, MK_PTR arg2)top Commit And Rollback Notification Callbacks … → API: Sq3LiteCommitHook
The Sq3LiteCommitHook() interface registers a callback function to be invoked whenever a transaction is committed. Any callback set by a previous call to Sq3LiteCommitHook() for the same database connection is overridden. The Sq3LiteRollbackHook() interface registers a callback function to be invoked whenever a transaction is rolled back. Any callback set by a previous call to Sq3LiteRollbackHook() for the same database connection is overridden. The pArg argument is passed through to the callback. If the callback on a commit hook function returns non-zero, then the commit is converted into a rollback.
The Sq3LiteCommitHook(D,C,P) and Sq3LiteRollbackHook(D,C,P) functions return the P argument from the previous call of the same function on the same database connection D, or NULL for the first call for each function on D.
The commit and rollback hook callbacks are not reentrant. The callback implementation must not do anything that will modify the database connection that invoked the callback. Any actions to modify the database connection must be deferred until after the completion of the Sq3StmtStep () call that triggered the commit or rollback hook in the first place. Note that running any other SQL statements, including SELECT statements, or merely calling Sq3StmtPrepareV2 () and Sq3StmtStep () will modify the database connections for the meaning of "modify" in this paragraph.
Registering a NULL function disables the callback.
When the commit hook callback routine returns zero, the COMMIT operation is allowed to continue normally. If the commit hook returns non-zero, then the COMMIT is converted into a ROLLBACK. The rollback hook is invoked on a rollback that results from a commit hook returning non-zero, just as it would be with any other rollback.
For the purposes of this API, a transaction is said to have been rolled back if an explicit "ROLLBACK" statement is executed, or an error or constraint causes an implicit rollback to occur. The rollback callback is not invoked if a transaction is automatically rolled back because the database connection is closed.
See also the Sq3LiteUpdateHook () interface.
Reference code from sqlite3:
enum MkErrorE Sq3LiteDeclareVtab(SQ3_LITE sq3lite, MK_STRN zSQL)top Declare The Schema Of A Virtual Table … → API: Sq3LiteDeclareVtab
The xCreate and xConnect methods of a virtual table module call this interface to declare the format (the names and datatypes of the columns) of the virtual tables they implement.
Reference code from sqlite3:
enum MkErrorE Sq3LiteEnableLoadExtension(SQ3_LITE db, MK_I32 onoff)top Enable Or Disable Extension Loading … → API: Sq3LiteEnableLoadExtension
So as not to open security holes in older applications that are unprepared to deal with extension loading, and as a means of disabling extension loading while evaluating user-entered SQL, the following API is provided to turn the Sq3LiteLoadExtension () mechanism on and off.
Extension loading is off by default. Call the Sq3LiteEnableLoadExtension() routine with onoff==1 to turn extension loading on and call it with onoff==0 to turn it back off again.
This interface enables or disables both the C-API Sq3LiteLoadExtension () and the SQL function load_extension (). Use sqlite3_db_config(db,SQ3_DBCONFIG_ENABLE_LOAD_EXTENSION,..) to enable or disable only the C-API.
Security warning: It is recommended that extension loading be enabled using the SQ3_DBCONFIG_ENABLE_LOAD_EXTENSION method rather than this interface, so the load_extension () SQL function remains disabled. This will prevent SQL injections from giving attackers access to extension loading capabilities.
Reference code from sqlite3:
enum MkErrorE Sq3LiteExtendedResultCodes(SQ3_LITE sq3lite, MK_I32 onoff)top Enable Or Disable Extended Result Codes … → API: Sq3LiteExtendedResultCodes
The Sq3LiteExtendedResultCodes() routine enables or disables the extended result codes feature of SQLite. The extended result codes are disabled by default for historical compatibility.
Reference code from sqlite3:
enum MkErrorE Sq3LiteLimit(SQ3_LITE sq3lite, enum Sq3LimitE id, MK_I32 newVal)top Run-time Limits … → API: Sq3LiteLimit
This interface allows the size of various constructs to be limited on a connection by connection basis. The first parameter is the database connection whose limit is to be set or queried. The second parameter is one of the limit categories that define a class of constructs to be size limited. The third parameter is the new limit for that construct.
If the new limit is a negative number, the limit is unchanged. For each limit category SQ3_LIMIT_NAME there is a hard upper bound set at compile-time by a C preprocessor macro called SQLITE_MAX_NAME. (The "_LIMIT_" in the name is changed to "_MAX_".) Attempts to increase a limit above its hard upper bound are silently truncated to the hard upper bound.
Regardless of whether or not the limit was changed, the Sq3LiteLimit () interface returns the prior value of the limit. Hence, to find the current value of a limit without changing it, simply invoke this interface with the third parameter set to -1.
Run-time limits are intended for use in applications that manage both their own internal database and also databases that are controlled by untrusted external sources. An example application might be a web browser that has its own databases for storing history and separate databases controlled by JavaScript applications downloaded off the Internet. The internal databases can be given the large, default limits. Databases managed by external sources can be given much smaller limits designed to prevent a denial of service attack. Developers might also want to use the Sq3LiteSetAuthorizer () interface to further control untrusted SQL. The size of the database created by an untrusted script can be contained using the max_page_count PRAGMA.
New run-time limit categories may be added in future releases.
Reference code from sqlite3:
enum MkErrorE Sq3LiteLoadExtension(SQ3_LITE db, MK_STRN zFile, MK_STRN zProc, MK_STR *pzErrMsg)top Load An Extension … → API: Sq3LiteLoadExtension
This interface loads an SQLite extension library from the named file.
The Sq3LiteLoadExtension() interface attempts to load an SQLite extension library contained in the file zFile. If the file cannot be loaded directly, attempts are made to load with various operating-system specific extensions added. So for example, if "samplelib" cannot be loaded, then names like "samplelib.so" or "samplelib.dylib" or "samplelib.dll" might be tried also.
The entry point is zProc. zProc may be 0, in which case SQLite will try to come up with an entry point name on its own. It first tries "sqlite3_extension_init". If that does not work, it constructs a name "sqlite3_X_init" where the X is consists of the lower-case equivalent of all ASCII alphabetic characters in the filename from the last "/" to the first following "." and omitting any initial "lib". The Sq3LiteLoadExtension() interface returns SQ3_RESULT_OK on success and SQ3_RESULT_ERROR if something goes wrong. If an error occurs and pzErrMsg is not 0, then the Sq3LiteLoadExtension () interface shall attempt to fill *pzErrMsg with error message text stored in memory obtained from Sq3Malloc (). The calling function should free this memory by calling Sq3Free ().
Extension loading must be enabled using Sq3LiteEnableLoadExtension () or sqlite3_db_config(db,SQ3_DBCONFIG_ENABLE_LOAD_EXTENSION,1,NULL) prior to calling this API, otherwise an error will be returned.
Security warning: It is recommended that the SQ3_DBCONFIG_ENABLE_LOAD_EXTENSION method be used to enable only this interface. The use of the Sq3LiteEnableLoadExtension () interface should be avoided. This will keep the SQL function load_extension () disabled and prevent SQL injections from giving attackers access to extension loading capabilities.
See also the load_extension() SQL function.
Reference code from sqlite3:
(hide) MK_PTR Sq3LiteRollbackHook(SQ3_LITE sq3lite, Sq3Fupu_Sq3LiteRollbackHook_arg1 arg1, MK_PTR arg2)top Commit And Rollback Notification Callbacks … → API: Sq3LiteRollbackHook
read more at 'Sq3LiteCommitHook'
(hide) MK_PTR Sq3LiteUpdateHook(SQ3_LITE sq3lite, Sq3Fupu_Sq3LiteUpdateHook_arg1 arg1, MK_PTR arg2)top Data Change Notification Callbacks … → API: Sq3LiteUpdateHook
The Sq3LiteUpdateHook() interface registers a callback function with the database connection identified by the first argument to be invoked whenever a row is updated, inserted or deleted in a rowid table. Any callback set by a previous call to this function for the same database connection is overridden.
The second argument is a pointer to the function to invoke when a row is updated, inserted or deleted in a rowid table. The first argument to the callback is a copy of the third argument to Sq3LiteUpdateHook(). The second callback argument is one of SQ3_AUTHACTION_INSERT, SQ3_AUTHACTION_DELETE, or SQ3_AUTHACTION_UPDATE, depending on the operation that caused the callback to be invoked. The third and fourth arguments to the callback contain pointers to the database and table name containing the affected row. The final callback parameter is the rowid of the row. In the case of an update, this is the rowid after the update takes place.
The update hook is not invoked when internal system tables are modified (i.e. sqlite_sequence). The update hook is not invoked when WITHOUT ROWID tables are modified.
In the current implementation, the update hook is not invoked when conflicting rows are deleted because of an ON CONFLICT REPLACE clause. Nor is the update hook invoked when rows are deleted using the truncate optimization. The exceptions defined in this paragraph might change in a future release of SQLite.
The update hook implementation must not do anything that will modify the database connection that invoked the update hook. Any actions to modify the database connection must be deferred until after the completion of the Sq3StmtStep () call that triggered the update hook. Note that Sq3StmtPrepareV2 () and Sq3StmtStep () both modify their database connections for the meaning of "modify" in this paragraph.
The Sq3LiteUpdateHook(D,C,P) function returns the P argument from the previous call on the same database connection D, or NULL for the first call on D.
See also the Sq3LiteCommitHook (), Sq3LiteRollbackHook (), and sqlite3_preupdate_hook () interfaces.
Reference code from sqlite3:
C-API: Sq3LiteC_Execution_C_API - Sq3LiteC - execute a sql statement …
(static) enum MkErrorE Sq3LiteSleep(MK_I32 arg0)top Suspend Execution For A Short Time … → API: Sq3LiteSleep
The Sq3LiteSleep() function causes the current thread to suspend execution for at least a number of milliseconds specified in its parameter.
If the operating system does not support sleep requests with millisecond time resolution, then the time will be rounded up to the nearest second. The number of milliseconds of sleep actually requested from the operating system is returned.
SQLite implements this interface by calling the xSleep() method of the default sqlite3_vfs object. If the xSleep() method of the default VFS is not implemented correctly, or not implemented at all, then the behavior of Sq3LiteSleep() may deviate from the description in the previous paragraphs.
If a negative argument is passed to Sq3LiteSleep() the results vary by VFS and operating system. Some system treat a negative argument as an instruction to sleep forever. Others understand it to mean do not sleep at all. In SQLite version 3.42.0 and later, a negative argument passed into Sq3LiteSleep() is changed to zero before it is relayed down into the xSleep method of the VFS.
Reference code from sqlite3:
enum MkErrorE Sq3LiteExec(SQ3_LITE sq3lite, MK_STRN sql, Sq3Fupu_Sq3LiteExec_callback_call callback_call, MK_CBP callback_data)top One-Step Query Execution Interface … → API: Sq3LiteExec
| [in] | sq3lite | the Sq3LiteC instance to work on a database |
| [in] | sql | The sql data to be processed |
| [in] | callback_call | (C-only) The callback to call from type Sq3LiteExecV2CB |
| [in] | callback_data | The additional data, used as Sq3LiteExecV2CB first argument and as callback for a non-C language. |
Sq3LiteExec : callback signatureThe callback Sq3Fupu_Sq3LiteExec_callback_call has the same signature as the sqlite3_exec callback.
Read more about how to define a service-callback in theLink .
Sq3LiteExec : callback example// RPC example for a callback SINGELTON to provide a callback with ARRAY-of-STRING as argument static Sq3Fupu_Sq3LiteExec_callback_call_ret Sq3LiteExecCB (Sq3Fupu_Sq3LiteExec_callback_call_args) { // constructer define local attributes const struct Sq3CbS * cbP = (struct Sq3CbS *) callV1; MkRtSetup_RT(cbP->mkrt); const MQ_CTX rpc = cbP->rpc; if (cbP->ret == NULL) { // callback_first_check == 2 // "Callback1" to collect **all** result sets into **one** MkBufferStreamC data object // which is then sent to the client at the end with **one** response. MqSendSTART_E(rpc); MqSendBFL_E(rpc, MkBufferListCreateVC(num,(MK_STRN*)vals)); MqSendBFL_E(rpc, MkBufferListCreateVC(num,(MK_STRN*)cols)); MqSendRETURN_SUB(rpc); } else { // callback_first_check == 1 // "Callback2" to send each result set **individually** to the client MkBufferStreamReset(cbP->ret); MkBufferStreamWriteBFL_E(cbP->ret, MkBufferListCreateVC(num,(MK_STRN*)vals)); MkBufferStreamWriteBFL_E(cbP->ret, MkBufferListCreateVC(num,(MK_STRN*)cols)); } return 0; error: MkErrorStack_1X(rpc); return 1; } #define rpc mqctx // naming in MQ_SERVICE_CALL_ARGS // RPC callback called from service static enum MkErrorE SrvSq3LiteExec ( MQ_SERVICE_CALL_ARGS ) { // create one THREAD-LOCAL callback instance as storage for additional attributes MkBufferStreamCreateTLS_T(MkBufferStream256C,bus); // collect service data SQ3_LITE sq3lite = Sq3LiteHandleResolve_e(MqReadHDL_e(rpc)); MK_STRN sql = MqReadSTR_e(rpc); const MK_I32 callback_first_check = MqReadI32_e(rpc); Sq3Fupu_Sq3LiteExec_callback_call callback = NULL; MK_CBP callback_first_ptr = NULL; // initialize the "Sq3LiteExecData", set the "Callback" switch (callback_first_check) { case 0: callback = NULL; callback_first_ptr = NULL; break; case 1: { callback = Sq3LiteExecCB; struct Sq3CbS Sq3CbS_callback_first_ptr = {MK_RT_PTR,rpc,bus}; callback_first_ptr = &Sq3CbS_callback_first_ptr; break; } case 2: { callback = Sq3LiteExecCB; struct Sq3CbS Sq3CbS_callback_first_ptr = {MK_RT_PTR,rpc,NULL}; callback_first_ptr = &Sq3CbS_callback_first_ptr; break; } default: { return MkErrorSetV_1E("invalid control number '%d', expect: 1,2,3", callback_first_check); } } // start the "sql" query with "Exec" Sq3LiteExec_E(sq3lite, sql, callback, callback_first_ptr); // if "Callback2" was used, return the MkBufferStreamC data object MqSendSTART_E(rpc); switch (callback_first_check) { case 1: MqSendBUS_FLAT_E(rpc,bus); break; } error: return MqSendRETURN(rpc); } #undef rpc
The Sq3LiteExec() interface is a convenience wrapper around Sq3StmtPrepareV2 (), Sq3StmtStep (), and Sq3StmtFinalize (), that allows an application to run multiple statements of SQL without having to use a lot of C code.
The Sq3LiteExec() interface runs zero or more UTF-8 encoded, semicolon-separate SQL statements passed into its 2nd argument, in the context of the database connection passed in as its 1st argument. If the callback function of the 3rd argument to Sq3LiteExec() is not NULL, then it is invoked for each result row coming out of the evaluated SQL statements. The 4th argument to Sq3LiteExec() is relayed through to the 1st argument of each callback invocation. If the callback pointer to Sq3LiteExec() is NULL, then no callback is ever invoked and result rows are ignored.
If an error occurs while evaluating the SQL statements passed into Sq3LiteExec(), then execution of the current statement stops and subsequent statements are skipped. If the 5th parameter to Sq3LiteExec() is not NULL then any error message is written into memory obtained from Sq3Malloc () and passed back through the 5th parameter. To avoid memory leaks, the application should invoke Sq3Free () on error message strings returned through the 5th parameter of Sq3LiteExec() after the error message string is no longer needed. If the 5th parameter to Sq3LiteExec() is not NULL and no errors occur, then Sq3LiteExec() sets the pointer in its 5th parameter to NULL before returning.
If an Sq3LiteExec() callback returns non-zero, the Sq3LiteExec() routine returns SQ3_RESULT_ABORT without invoking the callback again and without running any subsequent SQL statements.
The 2nd argument to the Sq3LiteExec() callback function is the number of columns in the result. The 3rd argument to the Sq3LiteExec() callback is an array of pointers to strings obtained as if from Sq3StmtColumnText (), one for each column. If an element of a result row is NULL then the corresponding string pointer for the Sq3LiteExec() callback is a NULL pointer. The 4th argument to the Sq3LiteExec() callback is an array of pointers to strings where each entry represents the name of corresponding result column as obtained from Sq3StmtColumnName ().
If the 2nd parameter to Sq3LiteExec() is a NULL pointer, a pointer to an empty string, or a pointer that contains only whitespace and/or SQL comments, then no SQL statements are evaluated and the database is not changed.
Restrictions:
Reference code from sqlite3:
(runtime) enum MkErrorE Sq3LiteExecV2(SQ3_LITE sq3lite, MK_STRN sql, Sq3LiteExecV2CB callback_call, MK_CBP callback)top The Sq3LiteExecV2() interface is a convenience wrapper around Sq3StmtPrepareV2(), Sq3StmtStep(), and Sq3StmtFinalize(), that allows an application to run multiple statements of SQL without having to use a lot of C code. → API: Sq3LiteExecV2_RT
This is an enhanced version of Sq3LiteExec with support of MkBufferListC data-type for the vals and cols arguments.
| [in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
| [in] | sq3lite | the Sq3LiteC instance to work on a database |
| [in] | sql | The sql data to be processed |
| [in] | callback_call | (C-only) The callback to call from type Sq3LiteExecV2CB |
| [in] | callback | The additional data, used as Sq3LiteExecV2CB first argument and as callback for a non-C language. |
C-API: Sq3LiteC_Info_C_API - Sq3LiteC - get information …
MK_I32 Sq3LiteGetAutocommit(SQ3_LITE sq3lite)top Test For Auto-Commit Mode … → API: Sq3LiteGetAutocommit
The Sq3LiteGetAutocommit() interface returns non-zero or zero if the given database connection is or is not in autocommit mode, respectively. Autocommit mode is on by default. Autocommit mode is disabled by a BEGIN statement. Autocommit mode is re-enabled by a COMMIT or ROLLBACK.
If certain kinds of errors occur on a statement within a multi-statement transaction (errors including SQ3_RESULT_FULL, SQ3_RESULT_IOERR, SQ3_RESULT_NOMEM, SQ3_RESULT_BUSY, and SQ3_RESULT_INTERRUPT) then the transaction might be rolled back automatically. The only way to find out whether SQLite automatically rolled back the transaction after an error is to use this function.
If another thread changes the autocommit status of the database connection while this routine is running, then the return value is undefined.
Reference code from sqlite3:
MK_I64 Sq3LiteLastInsertRowid(SQ3_LITE sq3lite)top Last Insert Rowid … → API: Sq3LiteLastInsertRowid
Each entry in most SQLite tables (except for WITHOUT ROWID tables) has a unique 64-bit signed integer key called the "rowid". The rowid is always available as an undeclared column named ROWID, OID, or ROWID as long as those names are not also used by explicitly declared columns. If the table has a column of type INTEGER PRIMARY KEY then that column is another alias for the rowid.
The Sq3LiteLastInsertRowid(D) interface usually returns the rowid of the most recent successful INSERT into a rowid table or virtual table on database connection D. Inserts into WITHOUT ROWID tables are not recorded. If no successful INSERTs into rowid tables have ever occurred on the database connection D, then Sq3LiteLastInsertRowid(D) returns zero.
As well as being set automatically as rows are inserted into database tables, the value returned by this function may be set explicitly by Sq3LiteSetLastInsertRowid ()
Some virtual table implementations may INSERT rows into rowid tables as part of committing a transaction (e.g. to flush data accumulated in memory to disk). In this case subsequent calls to this function return the rowid associated with these internal INSERT operations, which leads to unintuitive results. Virtual table implementations that do write to rowid tables in this way can avoid this problem by restoring the original rowid value using Sq3LiteSetLastInsertRowid () before returning control to the user.
If an INSERT occurs within a trigger then this routine will return the rowid of the inserted row as long as the trigger is running. Once the trigger program ends, the value returned by this routine reverts to what it was before the trigger was fired.
An INSERT that fails due to a constraint violation is not a successful INSERT and does not change the value returned by this routine. Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK, and INSERT OR ABORT make no changes to the return value of this routine when their insertion fails. When INSERT OR REPLACE encounters a constraint violation, it does not fail. The INSERT continues to completion after deleting rows that caused the constraint problem so INSERT OR REPLACE will always change the return value of this interface.
For the purposes of this routine, an INSERT is considered to be successful even if it is subsequently rolled back.
This function is accessible to SQL statements via the last_insert_rowid() SQL function.
If a separate thread performs a new INSERT on the same database connection while the Sq3LiteLastInsertRowid () function is running and thus changes the last insert rowid, then the value returned by Sq3LiteLastInsertRowid () is unpredictable and might not equal either the old or the new last insert rowid.
Reference code from sqlite3:
enum MkErrorE Sq3LiteTxnState(SQ3_LITE sq3lite, MK_STRN zSchema)top Determine the transaction state of a database … → API: Sq3LiteTxnState
The Sq3LiteTxnState(D,S) interface returns the current transaction state of schema S in database connection D. If S is NULL, then the highest transaction state of any schema on database connection D is returned. Transaction states are (in order of lowest to highest):
If the S argument to Sq3LiteTxnState(D,S) is not the name of a valid schema, then -1 is returned.
Reference code from sqlite3:
enum MkErrorE Sq3LiteVtabOnConflict(SQ3_LITE sq3lite)top Determine The Virtual Table Conflict Policy … → API: Sq3LiteVtabOnConflict
This function may only be called from within a call to the xUpdate method of a virtual table implementation for an INSERT or UPDATE operation. The value returned is one of SQ3_CONFLICT_ROLLBACK, SQ3_AUTHRETURN_IGNORE, SQ3_CONFLICT_FAIL, SQ3_RESULT_ABORT, or SQ3_CONFLICT_REPLACE, according to the ON CONFLICT mode of the SQL statement that triggered the call to the xUpdate method of the virtual table.
Reference code from sqlite3:
| CreateCollationV2 | Define New Collating Sequences … | ||
| CreateFunctionV2 | Create Or Redefine SQL Functions … | ||
| CreateWindowFunction | Create Or Redefine SQL Functions … | ||
| WalAutocheckpoint | Configure an auto-checkpoint … | ||
| WalCheckpointV2 | Checkpoint a database … | ||
| WalHook | Write-Ahead Log Commit Hook … | ||
C-API: Sq3LiteC_Modify_C_API - Sq3LiteC - modify the database …
C-API: Sq3LiteC_Modify_Create_C_API - Sq3LiteC - functions related to index 'Modify' and doc 'Create' …
Create Or Redefine SQL Functions:
Define New Collating Sequences:
Reference code from sqlite3:
(hide) enum MkErrorE Sq3LiteCreateCollationV2(SQ3_LITE sq3lite, MK_STRN zName, enum Sq3TextE eTextRep, MK_PTR pArg, Sq3Fupu_Sq3LiteCreateCollationV2_xCompare xCompare, Sq3Fupu_Sq3LiteCreateCollationV2_xDestroy xDestroy)top Define New Collating Sequences … → API: Sq3LiteCreateCollationV2
These functions add, remove, or modify a collation associated with the database connection specified as the first argument.
The name of the collation is a UTF-8 string for sqlite3_create_collation() and Sq3LiteCreateCollationV2() and a UTF-16 string in native byte order for sqlite3_create_collation16(). Collation names that compare equal according to Sq3StrNicmp () are considered to be the same name.
The third argument (eTextRep) must be one of the constants:
The eTextRep argument determines the encoding of strings passed to the collating function callback, xCompare. The SQ3_TEXT_UTF16 and SQ3_TEXT_UTF16_ALIGNED values for eTextRep force strings to be UTF16 with native byte order. The SQ3_TEXT_UTF16_ALIGNED value for eTextRep forces strings to begin on an even byte address.
The fourth argument, pArg, is an application data pointer that is passed through as the first argument to the collating function callback.
The fifth argument, xCompare, is a pointer to the collating function. Multiple collating functions can be registered using the same name but with different eTextRep parameters and SQLite will use whichever function requires the least amount of data transformation. If the xCompare argument is NULL then the collating function is deleted. When all collating functions having the same name are deleted, that collation is no longer usable.
The collating function callback is invoked with a copy of the pArg application data pointer and with two strings in the encoding specified by the eTextRep argument. The two integer parameters to the collating function callback are the length of the two strings, in bytes. The collating function must return an integer that is negative, zero, or positive if the first string is less than, equal to, or greater than the second, respectively. A collating function must always return the same answer given the same inputs. If two or more collating functions are registered to the same collation name (using different eTextRep values) then all must give an equivalent answer when invoked with equivalent strings. The collating function must obey the following properties for all strings A, B, and C:
If a collating function fails any of the above constraints and that collating function is registered and used, then the behavior of SQLite is undefined.
The Sq3LiteCreateCollationV2() works like sqlite3_create_collation() with the addition that the xDestroy callback is invoked on pArg when the collating function is deleted. Collating functions are deleted when they are overridden by later calls to the collation creation functions or when the database connection is closed using sqlite3_close ().
The xDestroy callback is not called if the Sq3LiteCreateCollationV2() function fails. Applications that invoke Sq3LiteCreateCollationV2() with a non-NULL xDestroy argument should check the return code and dispose of the application data pointer themselves rather than expecting SQLite to deal with it for them. This is different from every other SQLite interface. The inconsistency is unfortunate but cannot be changed without breaking backwards compatibility.
See also: Sq3LiteCollationNeeded () and sqlite3_collation_needed16 ().
Reference code from sqlite3:
(hide) enum MkErrorE Sq3LiteCreateFunctionV2(SQ3_LITE db, MK_STRN zFunctionName, MK_I32 nArg, enum Sq3TextE eTextRep, MK_PTR pApp, Sq3Fupu_Sq3LiteCreateFunctionV2_xFunc xFunc, Sq3Fupu_Sq3LiteCreateFunctionV2_xStep xStep, Sq3Fupu_Sq3LiteCreateFunctionV2_xFinal xFinal, Sq3Fupu_Sq3LiteCreateFunctionV2_xDestroy xDestroy)top Create Or Redefine SQL Functions … → API: Sq3LiteCreateFunctionV2
These functions (collectively known as "function creation routines") are used to add SQL functions or aggregates or to redefine the behavior of existing SQL functions or aggregates. The only differences between the three "sqlite3_create_function*" routines are the text encoding expected for the second parameter (the name of the function being created) and the presence or absence of a destructor callback for the application data pointer. Function Sq3LiteCreateWindowFunction() is similar, but allows the user to supply the extra callback functions needed by aggregate window functions.
The first parameter is the database connection to which the SQL function is to be added. If an application uses more than one database connection then application-defined SQL functions must be added to each database connection separately.
The second parameter is the name of the SQL function to be created or redefined. The length of the name is limited to 255 bytes in a UTF-8 representation, exclusive of the zero-terminator. Note that the name length limit is in UTF-8 bytes, not characters nor UTF-16 bytes. Any attempt to create a function with a longer name will result in SQ3_RESULT_MISUSE being returned.
The third parameter (nArg) is the number of arguments that the SQL function or aggregate takes. If this parameter is -1, then the SQL function or aggregate may take any number of arguments between 0 and the limit set by Sq3LiteLimit(SQ3_LIMIT_FUNCTION_ARG). If the third parameter is less than -1 or greater than 127 then the behavior is undefined.
The fourth parameter, eTextRep, specifies what text encoding this SQL function prefers for its parameters. The application should set this parameter to SQ3_TEXT_UTF16LE if the function implementation invokes sqlite3_value_text16le () on an input, or SQ3_TEXT_UTF16BE if the implementation invokes sqlite3_value_text16be () on an input, or SQ3_TEXT_UTF16 if sqlite3_value_text16 () is used, or SQ3_TEXT_UTF8 otherwise. The same SQL function may be registered multiple times using different preferred text encodings, with different implementations for each encoding. When multiple implementations of the same function are available, SQLite will pick the one that involves the least amount of data conversion.
The fourth parameter may optionally be ORed with SQ3_FUNCTION_DETERMINISTIC to signal that the function will always return the same result given the same inputs within a single SQL statement. Most SQL functions are deterministic. The built-in random () SQL function is an example of a function that is not deterministic. The SQLite query planner is able to perform additional optimizations on deterministic functions, so use of the SQ3_FUNCTION_DETERMINISTIC flag is recommended where possible.
The fourth parameter may also optionally include the SQ3_FUNCTION_DIRECTONLY flag, which if present prevents the function from being invoked from within VIEWs, TRIGGERs, CHECK constraints, generated column expressions, index expressions, or the WHERE clause of partial indexes.
For best security, the SQ3_FUNCTION_DIRECTONLY flag is recommended for all application-defined SQL functions that do not need to be used inside of triggers, view, CHECK constraints, or other elements of the database schema. This flags is especially recommended for SQL functions that have side effects or reveal internal application state. Without this flag, an attacker might be able to modify the schema of a database file to include invocations of the function with parameters chosen by the attacker, which the application will then execute when the database file is opened and read.
The fifth parameter is an arbitrary pointer. The implementation of the function can gain access to this pointer using sqlite3_user_data ().
The sixth, seventh and eighth parameters passed to the three "sqlite3_create_function*" functions, xFunc, xStep and xFinal, are pointers to C-language functions that implement the SQL function or aggregate. A scalar SQL function requires an implementation of the xFunc callback only; NULL pointers must be passed as the xStep and xFinal parameters. An aggregate SQL function requires an implementation of xStep and xFinal and NULL pointer must be passed for xFunc. To delete an existing SQL function or aggregate, pass NULL pointers for all three function callbacks.
The sixth, seventh, eighth and ninth parameters (xStep, xFinal, xValue and xInverse) passed to Sq3LiteCreateWindowFunction are pointers to C-language callbacks that implement the new function. xStep and xFinal must both be non-NULL. xValue and xInverse may either both be NULL, in which case a regular aggregate function is created, or must both be non-NULL, in which case the new function may be used as either an aggregate or aggregate window function. More details regarding the implementation of aggregate window functions are available here.
If the final parameter to Sq3LiteCreateFunctionV2() or Sq3LiteCreateWindowFunction() is not NULL, then it is destructor for the application data pointer. The destructor is invoked when the function is deleted, either by being overloaded or when the database connection closes. The destructor is also invoked if the call to Sq3LiteCreateFunctionV2() fails. When the destructor callback is invoked, it is passed a single argument which is a copy of the application data pointer which was the fifth parameter to Sq3LiteCreateFunctionV2().
It is permitted to register multiple implementations of the same functions with the same name but with either differing numbers of arguments or differing preferred text encodings. SQLite will use the implementation that most closely matches the way in which the SQL function is used. A function implementation with a non-negative nArg parameter is a better match than a function implementation with a negative nArg. A function where the preferred text encoding matches the database encoding is a better match than a function where the encoding is different. A function where the encoding difference is between UTF16le and UTF16be is a closer match than a function where the encoding difference is between UTF8 and UTF16.
Built-in functions may be overloaded by new application-defined functions.
An application-defined function is permitted to call other SQLite interfaces. However, such calls must not close the database connection nor finalize or reset the prepared statement in which the function is running.
Reference code from sqlite3:
(hide) enum MkErrorE Sq3LiteCreateWindowFunction(SQ3_LITE db, MK_STRN zFunctionName, MK_I32 nArg, enum Sq3TextE eTextRep, MK_PTR pApp, Sq3Fupu_Sq3LiteCreateWindowFunction_xStep xStep, Sq3Fupu_Sq3LiteCreateWindowFunction_xFinal xFinal, Sq3Fupu_Sq3LiteCreateWindowFunction_xValue xValue, Sq3Fupu_Sq3LiteCreateWindowFunction_xInverse xInverse, Sq3Fupu_Sq3LiteCreateWindowFunction_xDestroy xDestroy)top Create Or Redefine SQL Functions … → API: Sq3LiteCreateWindowFunction
read more at 'Sq3LiteCreateFunctionV2'
C-API: Sq3LiteC_Modify_Wal_C_API - Sq3LiteC - functions related to index 'Modify' and doc 'Wal' …
Write-Ahead Log Commit Hook:
Configure an auto-checkpoint:
Checkpoint a database:
Reference code from sqlite3:
enum MkErrorE Sq3LiteWalAutocheckpoint(SQ3_LITE db, MK_I32 N)top Configure an auto-checkpoint … → API: Sq3LiteWalAutocheckpoint
The Sq3LiteWalAutocheckpoint (D,N) is a wrapper around Sq3LiteWalHook () that causes any database on database connection D to automatically checkpoint after committing a transaction if there are N or more frames in the write-ahead log file. Passing zero or a negative value as the nFrame parameter disables automatic checkpoints entirely.
The callback registered by this function replaces any existing callback registered using Sq3LiteWalHook (). Likewise, registering a callback using Sq3LiteWalHook () disables the automatic checkpoint mechanism configured by this function.
The wal_autocheckpoint pragma can be used to invoke this interface from SQL.
Checkpoints initiated by this mechanism are PASSIVE.
Every new database connection defaults to having the auto-checkpoint enabled with a threshold of 1000 or SQLITE_DEFAULT_WAL_AUTOCHECKPOINT pages. The use of this interface is only necessary if the default setting is found to be suboptimal for a particular application.
Reference code from sqlite3:
enum MkErrorE Sq3LiteWalCheckpointV2(SQ3_LITE db, MK_STRN zDb, MK_I32 eMode, MK_I32 *pnLog, MK_I32 *pnCkpt)top Checkpoint a database … → API: Sq3LiteWalCheckpointV2
The Sq3LiteWalCheckpointV2(D,X,M,L,C) interface runs a checkpoint operation on database X of database connection D in mode M. Status information is written back into integers pointed to by L and C. The M parameter must be a valid checkpoint mode:
Checkpoint as many frames as possible without waiting for any database readers or writers to finish, then sync the database file if all frames in the log were checkpointed. The busy-handler callback is never invoked in the SQ3_CHECKPOINT_PASSIVE mode. On the other hand, passive mode might leave the checkpoint unfinished if there are concurrent readers or writers.
This mode blocks (it invokes the busy-handler callback) until there is no database writer and all readers are reading from the most recent database snapshot. It then checkpoints all frames in the log file and syncs the database file. This mode blocks new database writers while it is pending, but new database readers are allowed to continue unimpeded.
This mode works the same way as SQ3_CHECKPOINT_FULL with the addition that after checkpointing the log file it blocks (calls the busy-handler callback) until all readers are reading from the database file only. This ensures that the next writer will restart the log file from the beginning. Like SQ3_CHECKPOINT_FULL, this mode blocks new database writer attempts while it is pending, but does not impede readers.
If pnLog is not NULL, then *pnLog is set to the total number of frames in the log file or to -1 if the checkpoint could not run because of an error or because the database is not in WAL mode. If pnCkpt is not NULL,then *pnCkpt is set to the total number of checkpointed frames in the log file (including any that were already checkpointed before the function was called) or to -1 if the checkpoint could not run due to an error or because the database is not in WAL mode. Note that upon successful completion of an SQ3_CHECKPOINT_TRUNCATE, the log file will have been truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero.
All calls obtain an exclusive "checkpoint" lock on the database file. If any other process is running a checkpoint operation at the same time, the lock cannot be obtained and SQ3_RESULT_BUSY is returned. Even if there is a busy-handler configured, it will not be invoked in this case.
The SQ3_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the exclusive "writer" lock on the database file. If the writer lock cannot be obtained immediately, and a busy-handler is configured, it is invoked and the writer lock retried until either the busy-handler returns 0 or the lock is successfully obtained. The busy-handler is also invoked while waiting for database readers as described above. If the busy-handler returns 0 before the writer lock is obtained or while waiting for database readers, the checkpoint operation proceeds from that point in the same way as SQ3_CHECKPOINT_PASSIVE - checkpointing as many frames as possible without blocking any further. SQ3_RESULT_BUSY is returned in this case.
If parameter zDb is NULL or points to a zero length string, then the specified operation is attempted on all WAL databases attached to database connection db. In this case the values written to output parameters *pnLog and *pnCkpt are undefined. If an SQ3_RESULT_BUSY error is encountered when processing one or more of the attached WAL databases, the operation is still attempted on any remaining attached databases and SQ3_RESULT_BUSY is returned at the end. If any other error occurs while processing an attached database, processing is abandoned and the error code is returned to the caller immediately. If no error (SQ3_RESULT_BUSY or otherwise) is encountered while processing the attached databases, SQ3_RESULT_OK is returned.
If database zDb is the name of an attached database that is not in WAL mode, SQ3_RESULT_OK is returned and both *pnLog and *pnCkpt set to -1. If zDb is not NULL (or a zero length string) and is not the name of any attached database, SQ3_RESULT_ERROR is returned to the caller.
Unless it returns SQ3_RESULT_MISUSE, the Sq3LiteWalCheckpointV2() interface sets the error information that is queried by Sq3LiteErrCode () and Sq3LiteErrMsg ().
The PRAGMA wal_checkpoint command can be used to invoke this interface from SQL.
Reference code from sqlite3:
(hide) MK_PTR Sq3LiteWalHook(SQ3_LITE sq3lite, Sq3Fupu_Sq3LiteWalHook_arg1 arg1, MK_PTR arg2)top Write-Ahead Log Commit Hook … → API: Sq3LiteWalHook
The Sq3LiteWalHook () function is used to register a callback that is invoked each time data is committed to a database in wal mode.
The callback is invoked by SQLite after the commit has taken place and the associated write-lock on the database released, so the implementation may read, write or checkpoint the database as required.
The first parameter passed to the callback function when it is invoked is a copy of the third parameter passed to Sq3LiteWalHook() when registering the callback. The second is a copy of the database handle. The third parameter is the name of the database that was written to - either "main" or the name of an ATTACH-ed database. The fourth parameter is the number of pages currently in the write-ahead log file, including those that were just committed.
The callback function should normally return SQ3_RESULT_OK. If an error code is returned, that error will propagate back up through the SQLite code base to cause the statement that provoked the callback to report an error, though the commit will have still occurred. If the callback returns SQ3_RESULT_ROW or SQ3_RESULT_DONE, or if it returns a value that does not correspond to any valid SQLite error code, the results are undefined.
A single database handle may have at most a single write-ahead log callback registered at one time. Calling Sq3LiteWalHook () replaces any previously registered write-ahead log callback. The return value is a copy of the third parameter from the previous call, if any, or 0. Note that the Sq3LiteWalAutocheckpoint () interface and the wal_autocheckpoint pragma both invoke Sq3LiteWalHook () and will overwrite any prior Sq3LiteWalHook () settings.
Reference code from sqlite3:
C-API: Sq3LiteC_Query_C_API - Sq3LiteC - work with a query …
void Sq3LiteInterrupt(SQ3_LITE sq3lite)top Interrupt A Long-Running Query … → API: Sq3LiteInterrupt
This function causes any pending database operation to abort and return at its earliest opportunity. This routine is typically called in response to a user action such as pressing "Cancel" or Ctrl-C where the user wants a long query operation to halt immediately.
It is safe to call this routine from a thread different from the thread that is currently running the database operation. But it is not safe to call this routine with a database connection that is closed or might close before Sq3LiteInterrupt() returns.
If an SQL operation is very nearly finished at the time when Sq3LiteInterrupt() is called, then it might not have an opportunity to be interrupted and might continue to completion.
An SQL operation that is interrupted will return SQ3_RESULT_INTERRUPT. If the interrupted SQL operation is an INSERT, UPDATE, or DELETE that is inside an explicit transaction, then the entire transaction will be rolled back automatically.
The Sq3LiteInterrupt(D) call is in effect until all currently running SQL statements on database connection D complete. Any new SQL statements that are started after the Sq3LiteInterrupt() call and before the running statement count reaches zero are interrupted as if they had been running prior to the Sq3LiteInterrupt() call. New SQL statements that are started after the running statement count reaches zero are not effected by the Sq3LiteInterrupt(). A call to Sq3LiteInterrupt(D) that occurs when there are no running SQL statements is a no-op and has no effect on SQL statements that are started after the Sq3LiteInterrupt() call returns.
The Sq3LiteIsInterrupted (D) interface can be used to determine whether or not an interrupt is currently in effect for database connection D. It returns 1 if an interrupt is currently in effect, or 0 otherwise.
Reference code from sqlite3:
MK_BOOL Sq3LiteIsInterrupted(SQ3_LITE sq3lite)top Interrupt A Long-Running Query … → API: Sq3LiteIsInterrupted
read more at 'Sq3LiteInterrupt'
C-API: Sq3LiteC_Row_C_API - Sq3LiteC - work with a row …
enum MkErrorE Sq3LiteChanges(SQ3_LITE sq3lite)top Count The Number Of Rows Modified … → API: Sq3LiteChanges
These functions return the number of rows modified, inserted or deleted by the most recently completed INSERT, UPDATE or DELETE statement on the database connection specified by the only parameter. The two functions are identical except for the type of the return value and that if the number of rows modified by the most recent INSERT, UPDATE or DELETE is greater than the maximum value supported by type "int", then the return value of Sq3LiteChanges() is undefined. Executing any other type of SQL statement does not modify the value returned by these functions.
Only changes made directly by the INSERT, UPDATE or DELETE statement are considered - auxiliary changes caused by triggers, foreign key actions or REPLACE constraint resolution are not counted.
Changes to a view that are intercepted by INSTEAD OF triggers are not counted. The value returned by Sq3LiteChanges() immediately after an INSERT, UPDATE or DELETE statement run on a view is always zero. Only changes made to real tables are counted.
Things are more complicated if the Sq3LiteChanges() function is executed while a trigger program is running. This may happen if the program uses the changes() SQL function, or if some other callback function invokes Sq3LiteChanges() directly. Essentially:
Before entering a trigger program the value returned by Sq3LiteChanges() function is saved. After the trigger program has finished, the original value is restored.
This means that if the changes() SQL function (or similar) is used by the first INSERT, UPDATE or DELETE statement within a trigger, it returns the value as set when the calling statement began executing. If it is used by the second or subsequent such statement within a trigger program, the value returned reflects the number of rows modified by the previous INSERT, UPDATE or DELETE statement within the same trigger.
If a separate thread makes changes on the same database connection while Sq3LiteChanges () is running then the value returned is unpredictable and not meaningful.
See also:
Reference code from sqlite3:
MK_I64 Sq3LiteChanges64(SQ3_LITE sq3lite)top Count The Number Of Rows Modified … → API: Sq3LiteChanges64
void Sq3LiteSetLastInsertRowid(SQ3_LITE sq3lite, MK_I64 arg1)top Set the Last Insert Rowid value … → API: Sq3LiteSetLastInsertRowid
The Sq3LiteSetLastInsertRowid(D, R) method allows the application to set the value returned by calling Sq3LiteLastInsertRowid(D) to R without inserting a row into the database.
Reference code from sqlite3:
enum MkErrorE Sq3LiteTotalChanges(SQ3_LITE sq3lite)top Total Number Of Rows Modified … → API: Sq3LiteTotalChanges
These functions return the total number of rows inserted, modified or deleted by all INSERT, UPDATE or DELETE statements completed since the database connection was opened, including those executed as part of trigger programs. The two functions are identical except for the type of the return value and that if the number of rows modified by the connection exceeds the maximum value supported by type "int", then the return value of Sq3LiteTotalChanges() is undefined. Executing any other type of SQL statement does not affect the value returned by Sq3LiteTotalChanges().
Changes made as part of foreign key actions are included in the count, but those made as part of REPLACE constraint resolution are not. Changes to a view that are intercepted by INSTEAD OF triggers are not counted.
The Sq3LiteTotalChanges (D) interface only reports the number of rows that changed due to SQL statement run against database connection D. Any changes by other database connections are ignored. To detect changes against a database file from other database connections use the PRAGMA data_version command or the SQ3_FCNTL_DATA_VERSION file control.
If a separate thread makes changes on the same database connection while Sq3LiteTotalChanges () is running then the value returned is unpredictable and not meaningful.
See also:
Reference code from sqlite3:
MK_I64 Sq3LiteTotalChanges64(SQ3_LITE sq3lite)top Total Number Of Rows Modified … → API: Sq3LiteTotalChanges64
read more at 'Sq3LiteTotalChanges'
C-API: Sq3LiteC_Error_C_API - Sq3LiteC - work with an error …
(static) MK_STRN Sq3LiteErrStr(MK_I32 arg0)top Error Codes And Messages … → API: Sq3LiteErrStr
enum Sq3ErrorE Sq3LiteErrCode(SQ3_LITE db)top Error Codes And Messages … → API: Sq3LiteErrCode
If the most recent sqlite3_* API call associated with database connection D failed, then the Sq3LiteErrCode(D) interface returns the numeric result code or extended result code for that API call. The Sq3LiteExtendetErrCode() interface is the same except that it always returns the extended result code even when extended result codes are disabled.
The values returned by Sq3LiteErrCode() and/or Sq3LiteExtendetErrCode() might change with each API call. Except, there are some interfaces that are guaranteed to never change the value of the error code. The error-code preserving interfaces include the following:
The Sq3LiteErrMsg() and sqlite3_errmsg16() return English-language text that describes the error, as either UTF-8 or UTF-16 respectively. (See how SQLite handles invalid UTF for exceptions to this rule.) Memory to hold the error message string is managed internally. The application does not need to worry about freeing the result. However, the error string might be overwritten or deallocated by subsequent calls to other SQLite interface functions.
The Sq3LiteErrStr() interface returns the English-language text that describes the result code, as UTF-8. Memory to hold the error message string is managed internally and must not be freed by the application.
If the most recent error references a specific token in the input SQL, the Sq3LiteErrorOffset() interface returns the byte offset of the start of that token. The byte offset returned by Sq3LiteErrorOffset() assumes that the input SQL is UTF8. If the most recent error does not reference a specific token in the input SQL, then the Sq3LiteErrorOffset() function returns -1.
When the serialized threading mode is in use, it might be the case that a second error occurs on a separate thread in between the time of the first error and the call to these interfaces. When that happens, the second error will be reported since these interfaces always report the most recent result. To avoid this, each thread can obtain exclusive use of the database connection D by invoking sqlite3_mutex_enter(sqlite3_db_mutex(D)) before beginning to use D and invoking sqlite3_mutex_leave(sqlite3_db_mutex(D)) after all calls to the interfaces listed here are completed.
If an interface fails with SQ3_RESULT_MISUSE, that means the interface was invoked incorrectly by the application. In that case, the error code and message may or may not be set.
Reference code from sqlite3:
MK_STRN Sq3LiteErrMsg(SQ3_LITE sq3lite)top Error Codes And Messages … → API: Sq3LiteErrMsg
enum MkErrorE Sq3LiteErrorOffset(SQ3_LITE db)top Error Codes And Messages … → API: Sq3LiteErrorOffset
enum Sq3ExtendetResultCodesE Sq3LiteExtendetErrCode(SQ3_LITE db)top Error Codes And Messages … → API: Sq3LiteExtendetErrCode
enum MkErrorE Sq3LiteSystemErrno(SQ3_LITE sq3lite)top Low-level system error code … → API: Sq3LiteSystemErrno
Attempt to return the underlying operating system error code or error number that caused the most recent I/O error or failure to open a file. The return value is OS-dependent. For example, on unix systems, after Sq3LiteOpenV2 () returns SQ3_RESULT_CANTOPEN, this interface could be called to get back the underlying "errno" that caused the problem, such as ENOSPC, EAUTH, EISDIR, and so forth.
Reference code from sqlite3:
C-API: Sq3LiteC_Misc_C_API - Sq3LiteC - various functions to perform misc operations …
(hide) enum MkErrorE Sq3LiteAutovacuumPages(SQ3_LITE db, Sq3Fupu_Sq3LiteAutovacuumPages_arg1 arg1, MK_PTR arg2, Sq3Fupu_Sq3LiteAutovacuumPages_arg3 arg3)top Autovacuum Compaction Amount Callback … → API: Sq3LiteAutovacuumPages
The Sq3LiteAutovacuumPages(D,C,P,X) interface registers a callback function C that is invoked prior to each autovacuum of the database file. The callback is passed a copy of the generic data pointer (P), the schema-name of the attached database that is being autovacuumed, the size of the database file in pages, the number of free pages, and the number of bytes per page, respectively. The callback should return the number of free pages that should be removed by the autovacuum. If the callback returns zero, then no autovacuum happens. If the value returned is greater than or equal to the number of free pages, then a complete autovacuum happens.
If there are multiple ATTACH-ed database files that are being modified as part of a transaction commit, then the autovacuum pages callback is invoked separately for each file.
The callback is not reentrant. The callback function should not attempt to invoke any other SQLite interface. If it does, bad things may happen, including segmentation faults and corrupt database files. The callback function should be a simple function that does some arithmetic on its input parameters and returns a result.
The X parameter to Sq3LiteAutovacuumPages(D,C,P,X) is an optional destructor for the P parameter. If X is not NULL, then X(P) is invoked whenever the database connection closes or when the callback is overwritten by another invocation of Sq3LiteAutovacuumPages().
There is only one autovacuum pages callback per database connection. Each call to the Sq3LiteAutovacuumPages() interface overrides all previous invocations for that database connection. If the callback argument (C) to Sq3LiteAutovacuumPages(D,C,P,X) is a NULL pointer, then the autovacuum steps callback is canceled. The return value from Sq3LiteAutovacuumPages() is normally SQ3_RESULT_OK, but might be some other error code if something goes wrong. The current implementation will only return SQ3_RESULT_OK or SQ3_RESULT_MISUSE, but other return codes might be added in future releases.
If no autovacuum pages callback is specified (the usual case) or a NULL pointer is provided for the callback, then the default behavior is to vacuum all free pages. So, in other words, the default behavior is the same as if the callback function were something like this:
unsigned int demonstration_autovac_pages_callback(
void *pClientData,
const char *zSchema,
unsigned int nDbPage,
unsigned int nFreePage,
unsigned int nBytePerPage
){
return nFreePage;
}
Reference code from sqlite3:
(hide) enum MkErrorE Sq3LiteCollationNeeded(SQ3_LITE sq3lite, MK_PTR arg1, Sq3Fupu_Sq3LiteCollationNeeded_arg2 arg2)top Collation Needed Callbacks … → API: Sq3LiteCollationNeeded
To avoid having to register all collation sequences before a database can be used, a single callback function may be registered with the database connection to be invoked whenever an undefined collation sequence is required.
If the function is registered using the Sq3LiteCollationNeeded() API, then it is passed the names of undefined collation sequences as strings encoded in UTF-8. If sqlite3_collation_needed16() is used, the names are passed as UTF-16 in machine native byte order. A call to either function replaces the existing collation-needed callback.
When the callback is invoked, the first argument passed is a copy of the second argument to Sq3LiteCollationNeeded() or sqlite3_collation_needed16(). The second argument is the database connection. The third argument is one of SQ3_TEXT_UTF8, SQ3_TEXT_UTF16BE, or SQ3_TEXT_UTF16LE, indicating the most desirable form of the collation sequence function required. The fourth parameter is the name of the required collation sequence.
The callback function should register the desired collation using sqlite3_create_collation (), sqlite3_create_collation16 (), or Sq3LiteCreateCollationV2 ().
Reference code from sqlite3:
enum MkErrorE Sq3LiteDbCacheflush(SQ3_LITE sq3lite)top Flush caches to disk mid-transaction … → API: Sq3LiteDbCacheflush
If a write-transaction is open on database connection D when the Sq3LiteDbCacheflush (D) interface invoked, any dirty pages in the pager-cache that are not currently in use are written out to disk. A dirty page may be in use if a database cursor created by an active SQL statement is reading from it, or if it is page 1 of a database file (page 1 is always "in use"). The Sq3LiteDbCacheflush (D) interface flushes caches for all schemas - "main", "temp", and any attached databases.
If this function needs to obtain extra database locks before dirty pages can be flushed to disk, it does so. If those locks cannot be obtained immediately and there is a busy-handler callback configured, it is invoked in the usual manner. If the required lock still cannot be obtained, then the database is skipped and an attempt made to flush any dirty pages belonging to the next (if any) database. If any databases are skipped because locks cannot be obtained, but no other error occurs, this function returns SQ3_RESULT_BUSY.
If any other error occurs while flushing dirty pages to disk (for example an IO error or out-of-memory condition), then processing is abandoned and an SQLite error code is returned to the caller immediately.
Otherwise, if no error occurs, Sq3LiteDbCacheflush () returns SQ3_RESULT_OK.
This function does not set the database handle error code or message returned by the Sq3LiteErrCode () and Sq3LiteErrMsg () functions.
Reference code from sqlite3:
SQ3_FILENAME Sq3LiteDbFilename(SQ3_LITE db, MK_STRN zDbName)top Return The Filename For A Database Connection … → API: Sq3LiteDbFilename
The Sq3LiteDbFilename(D,N) interface returns a pointer to the filename associated with database N of connection D. If there is no attached database N on the database connection D, or if database N is a temporary or in-memory database, then this function will return either a NULL pointer or an empty string.
The string value returned by this routine is owned and managed by the database connection. The value will be valid until the database N is DETACH-ed or until the database connection closes.
The filename returned by this function is the output of the xFullPathname method of the VFS. In other words, the filename will be an absolute pathname, even if the filename used to open the database originally was a URI or relative pathname.
If the filename pointer returned by this routine is not NULL, then it can be used as the filename input parameter to these routines:
Reference code from sqlite3:
MK_STRN Sq3LiteDbName(SQ3_LITE db, MK_I32 N)top Return The Schema Name For A Database Connection … → API: Sq3LiteDbName
The Sq3LiteDbName(D,N) interface returns a pointer to the schema name for the N-th database on database connection D, or a NULL pointer of N is out of range. An N value of 0 means the main database file. An N of 1 is the "temp" schema. Larger values of N correspond to various ATTACH-ed databases.
Space to hold the string that is returned by Sq3LiteDbName() is managed by SQLite itself. The string might be deallocated by any operation that changes the schema, including ATTACH or DETACH or calls to Sq3LiteSerialize () or Sq3LiteDeserialize (), even operations that occur on a different thread. Applications that need to remember the string long-term should make their own copy. Applications that are accessing the same database connection simultaneously on multiple threads should mutex-protect calls to this API and should make their own private copy of the result prior to releasing the mutex.
Reference code from sqlite3:
enum MkErrorE Sq3LiteDbReadonly(SQ3_LITE db, MK_STRN zDbName)top Determine if a database is read-only … → API: Sq3LiteDbReadonly
The Sq3LiteDbReadonly(D,N) interface returns 1 if the database N of connection D is read-only, 0 if it is read/write, or -1 if N is not the name of a database on connection D.
Reference code from sqlite3:
enum MkErrorE Sq3LiteDbReleaseMemory(SQ3_LITE sq3lite)top Free Memory Used By A Database Connection … → API: Sq3LiteDbReleaseMemory
The Sq3LiteDbReleaseMemory(D) interface attempts to free as much heap memory as possible from database connection D. Unlike the Sq3ReleaseMemory () interface, this interface is in effect even when the SQLITE_ENABLE_MEMORY_MANAGEMENT compile-time option is omitted.
See also: Sq3ReleaseMemory ()
Reference code from sqlite3:
enum MkErrorE Sq3LiteDbStatus(SQ3_LITE sq3lite, enum Sq3DbStatusE op, MK_I32 *pCur, MK_I32 *pHiwtr, MK_BOOL resetFlg)top Database Connection Status … → API: Sq3LiteDbStatus
This interface is used to retrieve runtime status information about a single database connection. The first argument is the database connection object to be interrogated. The second argument is an integer constant, taken from the set of SQ3_DBSTATUS options, that determines the parameter to interrogate. The set of SQ3_DBSTATUS options is likely to grow in future releases of SQLite.
The current value of the requested parameter is written into *pCur and the highest instantaneous value is written into *pHiwtr. If the resetFlg is true, then the highest instantaneous value is reset back down to the current value.
The Sq3LiteDbStatus() routine returns SQ3_RESULT_OK on success and a non-zero error code on failure.
See also: Sq3Status () and Sq3StmtStatus ().
Reference code from sqlite3:
(runtime) enum MkErrorE Sq3LiteDbStatusBFL(SQ3_LITE sq3lite, enum Sq3DbStatusE op, MK_BFL *val_out, MK_BOOL resetFlg)top Database Connection Status … → API: Sq3LiteDbStatusBFL_RT
This interface is used to retrieve runtime status information about a single database connection. The first argument is the database connection object to be interrogated. The second argument is an integer constant, taken from the set of SQ3_DBSTATUS options, that determines the parameter to interrogate. The set of SQ3_DBSTATUS options is likely to grow in future releases of SQLite.
The current value of the requested parameter is written into *pCur and the highest instantaneous value is written into *pHiwtr. If the resetFlg is true, then the highest instantaneous value is reset back down to the current value.
The Sq3LiteDbStatus() routine returns SQ3_RESULT_OK on success and a non-zero error code on failure.
See also: Sq3Status () and Sq3StmtStatus ().
Reference code from sqlite3:
| [in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
| [in] | sq3lite | the Sq3LiteC instance to work on a database |
| [in] | op | a value from the enum Sq3DbStatusE |
| [out] | val_out | The return-value have to be none MK_NULL. |
| [in] | resetFlg | If the resetFlg is true, then the highest instantaneous value is reset back down to the current value. |
MK_NULL for a non-error result.(runtime) enum MkErrorE Sq3LiteDeserialize(SQ3_LITE sq3lite, MK_STRN zSchema, MkBinaryR pData, enum Sq3DeSerializeEF mFlags)top Deserialize a database … → API: Sq3LiteDeserialize_RT
This is an enhanced version of Sq3LiteDeserializeHide, the return value changed to MkBinaryR.
| [in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
| [in] | sq3lite | the Sq3LiteC instance to work on a database |
| [in] | zSchema | Which DB to reopen with the deserialization |
| [in] | pData | The serialized database content |
| [in] | mFlags | Zero or more Sq3SerializeE flags |
(hide) enum MkErrorE Sq3LiteDeserializeHide(SQ3_LITE db, MK_STRN zSchema, MK_BIN pData, MK_I64 szDb, MK_I64 szBuf, enum Sq3DeSerializeEF mFlags)top Deserialize a database … → API: Sq3LiteDeserializeHide
The Sq3LiteDeserialize(D,S,P,N,M,F) interface causes the database connection D to disconnect from database S and then reopen S as an in-memory database based on the serialization contained in P. The serialized database P is N bytes in size. M is the size of the buffer P, which might be larger than N. If M is larger than N, and the SQ3_DESERIALIZE_READONLY bit is not set in F, then SQLite is permitted to add content to the in-memory database as long as the total size does not exceed M bytes.
If the SQ3_DESERIALIZE_FREEONCLOSE bit is set in F, then SQLite will invoke Sq3Free() on the serialization buffer when the database connection closes. If the SQ3_DESERIALIZE_RESIZEABLE bit is set, then SQLite will try to increase the buffer size using Sq3Realloc64() if writes on the database cause it to grow larger than M bytes.
Applications must not modify the buffer P or invalidate it before the database connection D is closed.
The Sq3LiteDeserialize() interface will fail with SQ3_RESULT_BUSY if the database is currently in a read transaction or is involved in a backup operation.
It is not possible to deserialized into the TEMP database. If the S argument to Sq3LiteDeserialize(D,S,P,N,M,F) is "temp" then the function returns SQ3_RESULT_ERROR.
The deserialized database should not be in WAL mode. If the database is in WAL mode, then any attempt to use the database file will result in an SQ3_RESULT_CANTOPEN error. The application can set the file format version numbers (bytes 18 and 19) of the input database P to 0x01 prior to invoking Sq3LiteDeserialize(D,S,P,N,M,F) to force the database file into rollback mode and work around this limitation.
If Sq3LiteDeserialize(D,S,P,N,M,F) fails for any reason and if the SQ3_DESERIALIZE_FREEONCLOSE bit is set in argument F, then Sq3Free () is invoked on argument P prior to returning.
This interface is omitted if SQLite is compiled with the SQLITE_OMIT_DESERIALIZE option.
Reference code from sqlite3:
(runtime) enum MkErrorE Sq3LiteDropModules(SQ3_LITE sq3lite, MK_BFL azKeepBfl)top Remove Unnecessary Virtual Table Implementations … → API: Sq3LiteDropModules_RT
This is an enhanced version of Sq3LiteDropModulesHide.
| [in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
| [in] | sq3lite | the Sq3LiteC instance to work on a database |
| azKeepBfl | The MkBufferListC list of modules to drop |
(hide) enum MkErrorE Sq3LiteDropModulesHide(SQ3_LITE db, MK_STRN *azKeep)top Remove Unnecessary Virtual Table Implementations … → API: Sq3LiteDropModulesHide
The Sq3LiteDropModules(D,L) interface removes all virtual table modules from database connection D except those named on list L. The L parameter must be either NULL or a pointer to an array of pointers to strings where the array is terminated by a single NULL pointer. If the L parameter is NULL, then all virtual table modules are removed.
See also: sqlite3_create_module ()
Reference code from sqlite3:
(hide) enum MkErrorE Sq3LiteFileControl(SQ3_LITE sq3lite, MK_STRN zDbName, enum Sq3TestCtrlE op, MK_PTR arg3)top Low-Level Control Of Database Files … → API: Sq3LiteFileControl
The Sq3LiteFileControl () interface makes a direct call to the xFileControl method for the sqlite3_io_methods object associated with a particular database identified by the second argument. The name of the database is "main" for the main database or "temp" for the TEMP database, or the name that appears after the AS keyword for databases that are added using the ATTACH SQL command. A NULL pointer can be used in place of "main" to refer to the main database file. The third and fourth parameters to this routine are passed directly through to the second and third parameters of the xFileControl method. The return value of the xFileControl method becomes the return value of this routine.
A few opcodes for Sq3LiteFileControl () are handled directly by the SQLite core and never invoke the sqlite3_io_methods.xFileControl method. The SQ3_FCNTL_FILE_POINTER value for the op parameter causes a pointer to the underlying Sq3FileC object to be written into the space pointed to by the 4th parameter. The SQ3_FCNTL_JOURNAL_POINTER works similarly except that it returns the Sq3FileC object associated with the journal file instead of the main database. The SQ3_FCNTL_VFS_POINTER opcode returns a pointer to the underlying sqlite3_vfs object for the file. The SQ3_FCNTL_DATA_VERSION returns the data version counter from the pager.
If the second parameter (zDbName) does not match the name of any open database file, then SQ3_RESULT_ERROR is returned. This error code is not remembered and will not be recalled by Sq3LiteErrCode () or Sq3LiteErrMsg (). The underlying xFileControl method might also return SQ3_RESULT_ERROR. There is no way to distinguish between an incorrect zDbName and an SQ3_RESULT_ERROR return from the underlying xFileControl method.
See also: file control opcodes
Reference code from sqlite3:
(runtime) void Sq3LiteLog(SQ3_LITEN const lite, MK_OBJN fmtobj, MK_DBG const debug, MK_STRN const callfunc, MK_I32 const lvl)top log the lite … → API: Sq3LiteLog_RT
| [in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
| [in] | lite | Programming-Language-Micro-Kernel (PLMK) instance from sqlite3 |
| [in] | fmtobj | managed object used to format the log-message (default=MK_NULL → use default-format) |
| [in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0) |
| [in] | callfunc | a user-defined postfix to identify the calling function or the environment (default=name-of-function) |
| [in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0) |
enum MkErrorE Sq3LiteOverloadFunction(SQ3_LITE sq3lite, MK_STRN zFuncName, MK_I32 nArg)top Overload A Function For A Virtual Table … → API: Sq3LiteOverloadFunction
Virtual tables can provide alternative implementations of functions using the xFindFunction method of the virtual table module. But global versions of those functions must exist in order to be overloaded.
This API makes sure a global version of a function with a particular name and number of parameters exists. If no such function exists before this API is called, a new function is created. The implementation of the new function always causes an exception to be thrown. So the new function is not good for anything by itself. Its only purpose is to be a placeholder function that can be overloaded by a virtual table.
Reference code from sqlite3:
MkBinaryR Sq3LiteSerialize(SQ3_LITE sq3lite, MK_STRN zSchema, enum Sq3SerializeE mFlags)top Serialize a database … → API: Sq3LiteSerialize
This is an enhanced version of Sq3LiteSerializeHide, the return value changed to MkBinaryR.
| [in] | sq3lite | the Sq3LiteC instance to work on a database |
| [in] | zSchema | Which DB to serialize. ex: "main", "temp", ... |
| [in] | mFlags | Zero or more Sq3SerializeE flags |
(hide) MK_BIN Sq3LiteSerializeHide(SQ3_LITE db, MK_STRN zSchema, MK_I64 *piSize, enum Sq3SerializeE mFlags)top Serialize a database … → API: Sq3LiteSerializeHide
The Sq3LiteSerialize(D,S,P,F) interface returns a pointer to memory that is a serialization of the S database on database connection D. If P is not a NULL pointer, then the size of the database in bytes is written into *P.
For an ordinary on-disk database file, the serialization is just a copy of the disk file. For an in-memory database or a "TEMP" database, the serialization is the same sequence of bytes which would be written to disk if that database where backed up to disk.
The usual case is that Sq3LiteSerialize() copies the serialization of the database into memory obtained from Sq3Malloc64 () and returns a pointer to that memory. The caller is responsible for freeing the returned value to avoid a memory leak. However, if the F argument contains the SQ3_SERIALIZE_NOCOPY bit, then no memory allocations are made, and the Sq3LiteSerialize() function will return a pointer to the contiguous memory representation of the database that SQLite is currently using for that database, or NULL if the no such contiguous memory representation of the database exists. A contiguous memory representation of the database will usually only exist if there has been a prior call to Sq3LiteDeserialize (D,S,...) with the same values of D and S. The size of the database is written into *P even if the SQ3_SERIALIZE_NOCOPY bit is set but no contiguous copy of the database exists.
After the call, if the SQ3_SERIALIZE_NOCOPY bit had been set, the returned buffer content will remain accessible and unchanged until either the next write operation on the connection or when the connection is closed, and applications must not modify the buffer. If the bit had been clear, the returned buffer will not be accessed by SQLite after the call.
A call to Sq3LiteSerialize(D,S,P,F) might return NULL even if the SQ3_SERIALIZE_NOCOPY bit is omitted from argument F if a memory allocation error occurs.
This interface is omitted if SQLite is compiled with the SQLITE_OMIT_DESERIALIZE option.
Reference code from sqlite3:
enum MkErrorE Sq3LiteTableColumnMetadata(SQ3_LITE db, MK_STRN zDbName, MK_STRN zTableName, MK_STRN zColumnName, MK_STRN *pzDataType, MK_STRN *pzCollSeq, MK_I32 *pNotNull, MK_I32 *pPrimaryKey, MK_I32 *pAutoinc)top Extract Metadata About A Column Of A Table … → API: Sq3LiteTableColumnMetadata
The Sq3LiteTableColumnMetadata(X,D,T,C,....) routine returns information about column C of table T in database D on database connection X. The Sq3LiteTableColumnMetadata() interface returns SQ3_RESULT_OK and fills in the non-NULL pointers in the final five arguments with appropriate values if the specified column exists. The Sq3LiteTableColumnMetadata() interface returns SQ3_RESULT_ERROR if the specified column does not exist. If the column-name parameter to Sq3LiteTableColumnMetadata() is a NULL pointer, then this routine simply checks for the existence of the table and returns SQ3_RESULT_OK if the table exists and SQ3_RESULT_ERROR if it does not. If the table name parameter T in a call to Sq3LiteTableColumnMetadata(X,D,T,C,...) is NULL then the result is undefined behavior.
The column is identified by the second, third and fourth parameters to this function. The second parameter is either the name of the database (i.e. "main", "temp", or an attached database) containing the specified table or NULL. If it is NULL, then all attached databases are searched for the table using the same algorithm used by the database engine to resolve unqualified table references.
The third and fourth parameters to this function are the table and column name of the desired column, respectively.
Metadata is returned by writing to the memory locations passed as the 5th and subsequent parameters to this function. Any of these arguments may be NULL, in which case the corresponding element of metadata is omitted.
Parameter Output
TypeDescription
5th const char* Data type 6th const char* Name of default collation sequence 7th int True if column has a NOT NULL constraint 8th int True if column is part of the PRIMARY KEY 9th int True if column is AUTOINCREMENT
The memory pointed to by the character pointers returned for the declaration type and collation sequence is valid until the next call to any SQLite API function.
If the specified table is actually a view, an error code is returned.
If the specified column is "rowid", "oid" or "_rowid_" and the table is not a WITHOUT ROWID table and an INTEGER PRIMARY KEY column has been explicitly declared, then the output parameters are set for the explicitly declared column. If there is no INTEGER PRIMARY KEY column, then the outputs for the rowid are set as follows:
data type: "INTEGER" collation sequence: "BINARY" not null: 0 primary key: 1 auto increment: 0
This function causes all database schemas to be read from disk and parsed, if that has not already been done, and returns an error if any errors are encountered while loading the schema.
Reference code from sqlite3:
(hide,macro) enum MkErrorE Sq3LiteVtabConfig(SQ3_LITE sq3lite, enum Sq3VtabE op, ...)top Virtual Table Interface Configuration … → API: Sq3LiteVtabConfig
This function may be called by either the xConnect or xCreate method of a virtual table implementation to configure various facets of the virtual table interface.
If this interface is invoked outside the context of an xConnect or xCreate virtual table method then the behavior is undefined.
In the call Sq3LiteVtabConfig(D,C,...) the D parameter is the database connection in which the virtual table is being created and which is passed in as the first argument to the xConnect or xCreate method that is invoking Sq3LiteVtabConfig(). The C parameter is one of the virtual table configuration options. The presence and meaning of parameters after C depend on which virtual table configuration option is used.
Reference code from sqlite3:
| Sq3ValueC CLASS | |||
| Define | Sq3ValueC - low level definition, access and cast … | ||
| Export | Sq3ValueC - Export class functions … | ||
| Introspection | Sq3ValueC - Introspection class functions … | ||
| Misc | Sq3ValueC - Misc class functions … | ||
| Sq3ValueC TOR | |||
| Free | Copy And Free SQL Values … | ||
| Dup | Copy And Free SQL Values … | ||
| Sq3ValueC INFO | |||
| Bytes | Obtaining SQL Values … | ||
| Encoding | Report the internal text encoding state of an sqlite3_value object … | ||
| FromBind | Obtaining SQL Values … | ||
| Log | log the val … | ||
| NoChange | Obtaining SQL Values … | ||
| NumericType | Obtaining SQL Values … | ||
| SubType | Finding The Subtype Of SQL Values … | ||
| Type | Obtaining SQL Values … | ||
| Sq3ValueC TYPES | |||
| BinaryR | Obtaining SQL Values … | ||
| Blob | Obtaining SQL Values … | ||
| BlobHide | Obtaining SQL Values … | ||
| BUF | Obtaining a MkBufferC value… | ||
| Double | Obtaining SQL Values … | ||
| Int | Obtaining SQL Values … | ||
| Int64 | Obtaining SQL Values … | ||
| Pointer | Obtaining SQL Values … | ||
| StringR | Obtaining SQL Values … | ||
| Text | Obtaining SQL Values … | ||
| Sq3ValueC VTAB | |||
| VtabInFirst | Find all elements on the right-hand side of an IN constraint … | ||
| VtabInNext | Find all elements on the right-hand side of an IN constraint … | ||
C-API: Sq3ValueC_C_API - Sq3ValueC - the class known as sq3val or Value define by Sq3ValueS …
Struct to represent the data of the Sq3ValueC …
Dynamically Typed Value Object …
SQLite uses the Sq3ValueC object to represent all values that can be stored in a database table. SQLite uses dynamic typing for the values it stores. Values stored in Sq3ValueC objects can be integers, floating point values, strings, BLOBs, or NULL.
An Sq3ValueC object may be either "protected" or "unprotected". Some interfaces require a protected Sq3ValueC. Other interfaces will accept either a protected or an unprotected Sq3ValueC. Every interface that accepts Sq3ValueC arguments specifies whether or not it requires a protected Sq3ValueC. The Sq3ValueDup () interface can be used to construct a new protected Sq3ValueC from an unprotected Sq3ValueC.
The terms "protected" and "unprotected" refer to whether or not a mutex is held. An internal mutex is held for a protected Sq3ValueC object but no mutex is held for an unprotected Sq3ValueC object. If SQLite is compiled to be single-threaded (with SQLITE_THREADSAFE=0 and with Sq3Threadsafe () returning 0) or if SQLite is run in one of reduced mutex modes SQ3_CONFIG_SINGLETHREAD or SQ3_CONFIG_MULTITHREAD then there is no distinction between protected and unprotected Sq3ValueC objects and they can be used interchangeably. However, for maximum code portability it is recommended that applications still make the distinction between protected and unprotected Sq3ValueC objects even when not strictly required.
The Sq3ValueC objects that are passed as parameters into the implementation of application-defined SQL functions are protected. The Sq3ValueC objects returned by sqlite3_vtab_rhs_value () are protected. The Sq3ValueC object returned by Sq3StmtColumnValue () is unprotected. Unprotected Sq3ValueC objects may only be used as arguments to sqlite3_result_value (), Sq3StmtBindValue (), and Sq3ValueDup (). The sqlite3_value_type() family of interfaces require protected Sq3ValueC objects.
Reference code from sqlite3:
| Val | cast a unknown-object into an Sq3ValueS pointer or NULL if not possible | ||
| ValCheck | check Sq3ValueS -> MkObjectS::signature … | ||
| ValCheckO | check Sq3ValueS -> MkObjectS::signature … | ||
| ValN | (const) cast a unknown-object into an Sq3ValueS pointer or NULL if not possible | ||
| HandleResolve | Handle-Resolve-Slot - return a Sq3ValueC from netHdl or MK_NULL if invalid… | ||
| HandleGet | Handle-Get-Slot - returns a export-hdl to the Sq3ValueC useable for external storage | ||
| Instances | get head-instance from linked-list of Sq3ValueS type … | ||
| Next | get next instance from linked-list of Sq3ValueS type | ||
| Prev | get previous instance from linked-list of Sq3ValueS type | ||
| GetNull | Null-Slot - return a Sq3ValueC typed | ||
C-API: Sq3ValueC_Class_C_API - Sq3ValueC - define the class …
C-API: Sq3ValueC_Class_Define_C_API - Sq3ValueC - low level definition, access and cast …
(static,hide) SQ3_VAL Sq3Val(MK_MNG mng)top cast a unknown-object into an Sq3ValueS pointer or NULL if not possible → API: Sq3Val
(static,hide) MK_BOOL Sq3ValCheck(MK_MNGN mng)top check Sq3ValueS -> MkObjectS::signature … → API: Sq3ValCheck
(static,hide) MK_BOOL Sq3ValCheckO(MK_OBJN obj)top check Sq3ValueS -> MkObjectS::signature … → API: Sq3ValCheckO
(static,hide) SQ3_VALN Sq3ValN(MK_MNGN mng)top (const) cast a unknown-object into an Sq3ValueS pointer or NULL if not possible → API: Sq3ValN
Sq3ValueC - Export class functions …
(static,runtime) SQ3_VAL Sq3ValueHandleResolve(MK_HDL const netHdl)top Handle-Resolve-Slot - return a Sq3ValueC from netHdl or MK_NULL if invalid… → API: Sq3ValueHandleResolve_RT
The Sq3ValueHandleResolve undo the Sq3ValueHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).
| [in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
| [in] | netHdl | handle former exported with Sq3ValueHandleGet |
MK_NULL if netHdl is invalid (runtime) MK_HDL Sq3ValueHandleGet(SQ3_VAL const val)top Handle-Get-Slot - returns a export-hdl to the Sq3ValueC useable for external storage → API: Sq3ValueHandleGet_RT
The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the Sq3ValueHandleResolve.
The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.
example: The export-hdl is used in rpc to identify an object across the network.
| [in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
| [in] | val | Programming-Language-Micro-Kernel (PLMK) instance from sqlite3_value |
Sq3ValueC - Introspection class functions …
(static,runtime) SQ3_VAL Sq3ValueInstances()top get head-instance from linked-list of Sq3ValueS type … → API: Sq3ValueInstances_RT
The head-instance is the last instance created.
SQ3_VAL Sq3ValueNext(SQ3_VAL const val)top get next instance from linked-list of Sq3ValueS type → API: Sq3ValueNext
SQ3_VAL Sq3ValuePrev(SQ3_VAL const val)top get previous instance from linked-list of Sq3ValueS type → API: Sq3ValuePrev
Sq3ValueC - Misc class functions …
(static) SQ3_VAL Sq3ValueGetNull()top Null-Slot - return a Sq3ValueC typed NULL instance … → API: Sq3ValueGetNull
C-API: Sq3ValueC_TOR_C_API - Sq3ValueC - various functions to create, initialize and destroy …
(destructor) void Sq3ValueFree(SQ3_VAL sq3val)top Copy And Free SQL Values … → API: Sq3ValueFree
(constructor) SQ3_VAL Sq3ValueDup(SQ3_VALN sq3val)top Copy And Free SQL Values … → API: Sq3ValueDup
The Sq3ValueDup(V) interface makes a copy of the Sq3ValueC object D and returns a pointer to that copy. The Sq3ValueC returned is a protected Sq3ValueC object even if the input is not. The Sq3ValueDup(V) interface returns NULL if V is NULL or if a memory allocation fails. If V is a pointer value, then the result of Sq3ValueDup(V) is a NULL value.
The Sq3ValueFree(V) interface frees an Sq3ValueC object previously obtained from Sq3ValueDup (). If V is a NULL pointer then Sq3ValueFree(V) is a harmless no-op.
Reference code from sqlite3:
C-API: Sq3ValueC_Info_C_API - Sq3ValueC - get type-information …
enum Sq3TextE Sq3ValueBytes(SQ3_VALN sq3val)top Obtaining SQL Values … → API: Sq3ValueBytes
enum Sq3TextE Sq3ValueEncoding(SQ3_VALN sq3val)top Report the internal text encoding state of an sqlite3_value object … → API: Sq3ValueEncoding
The Sq3ValueEncoding(X) interface returns one of SQ3_TEXT_UTF8, SQ3_TEXT_UTF16BE, or SQ3_TEXT_UTF16LE according to the current text encoding of the value X, assuming that X has type TEXT. If Sq3ValueType(X) returns something other than SQ3_TYPE_TEXT, then the return value from Sq3ValueEncoding(X) is meaningless. Calls to Sq3ValueText (X), sqlite3_value_text16 (X), sqlite3_value_text16be (X), sqlite3_value_text16le (X), Sq3ValueBytes (X), or sqlite3_value_bytes16 (X) might change the encoding of the value X and thus change the return from subsequent calls to Sq3ValueEncoding(X).
This routine is intended for used by applications that test and validate the SQLite implementation. This routine is inquiring about the opaque internal state of an Sq3ValueC object. Ordinary applications should not need to know what the internal state of an Sq3ValueC object is and hence should not need to use this interface.
Reference code from sqlite3:
MK_BOOL Sq3ValueFromBind(SQ3_VALN sq3val)top Obtaining SQL Values … → API: Sq3ValueFromBind
(runtime) void Sq3ValueLog(SQ3_VALN const val, MK_OBJN fmtobj, MK_DBG const debug, MK_STRN const callfunc, MK_I32 const lvl)top log the val … → API: Sq3ValueLog_RT
| [in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
| [in] | val | Programming-Language-Micro-Kernel (PLMK) instance from sqlite3_value |
| [in] | fmtobj | managed object used to format the log-message (default=MK_NULL → use default-format) |
| [in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0) |
| [in] | callfunc | a user-defined postfix to identify the calling function or the environment (default=name-of-function) |
| [in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0) |
MK_BOOL Sq3ValueNoChange(SQ3_VALN sq3val)top Obtaining SQL Values … → API: Sq3ValueNoChange
enum Sq3TypeE Sq3ValueNumericType(SQ3_VALN sq3val)top Obtaining SQL Values … → API: Sq3ValueNumericType
MK_I32 Sq3ValueSubType(SQ3_VALN sq3val)top Finding The Subtype Of SQL Values … → API: Sq3ValueSubType
The Sq3ValueSubType(V) function returns the subtype for an application-defined SQL function argument V. The subtype information can be used to pass a limited amount of context from one SQL function to another. Use the sqlite3_result_subtype () routine to set the subtype for the return value of an SQL function.
Every application-defined SQL function that invoke this interface should include the SQ3_FUNCTION_SUBTYPE property in the text encoding argument when the function is registered. If the SQ3_FUNCTION_SUBTYPE property is omitted, then Sq3ValueSubType() might return zero instead of the upstream subtype in some corner cases.
Reference code from sqlite3:
enum Sq3TypeE Sq3ValueType(SQ3_VALN sq3val)top Obtaining SQL Values … → API: Sq3ValueType
C-API: Sq3ValueC_Types_C_API - Sq3ValueC - get type from value …
MkBinaryR Sq3ValueBinaryR(SQ3_VALN sq3val)top Obtaining SQL Values … → API: Sq3ValueBinaryR
read more at 'Sq3ValueBlobHide'
(runtime) MK_BUF Sq3ValueBlob(SQ3_VALN sq3val)top Obtaining SQL Values … → API: Sq3ValueBlob_RT
read more at 'Sq3ValueBlobHide'
MK_NULL for a non-error result.(hide) MK_BINN Sq3ValueBlobHide(SQ3_VALN sq3val)top Obtaining SQL Values … → API: Sq3ValueBlobHide
Summary:
sqlite3_value_blob → BLOB value sqlite3_value_double → REAL value sqlite3_value_int → 32-bit INTEGER value sqlite3_value_int64 → 64-bit INTEGER value sqlite3_value_pointer → Pointer value sqlite3_value_text → UTF-8 TEXT value sqlite3_value_text16 → UTF-16 TEXT value in the native byteorder sqlite3_value_text16be → UTF-16be TEXT value sqlite3_value_text16le → UTF-16le TEXT value sqlite3_value_bytes → Size of a BLOB or a UTF-8 TEXT in bytes sqlite3_value_bytes16 → Size of UTF-16 TEXT in bytes sqlite3_value_type → Default datatype of the value sqlite3_value_numeric_type → Best numeric datatype of the value sqlite3_value_nochange → True if the column is unchanged in an UPDATE against a virtual table. sqlite3_value_frombind → True if value originated from a bound parameter
Details:
These routines extract type, size, and content information from protected Sq3ValueC objects. Protected Sq3ValueC objects are used to pass parameter information into the functions that implement application-defined SQL functions and virtual tables.
These routines work only with protected Sq3ValueC objects. Any attempt to use these routines on an unprotected Sq3ValueC is not threadsafe.
These routines work just like the corresponding column access functions except that these routines take a single protected Sq3ValueC object pointer instead of a Sq3StmtC* pointer and an integer column number.
The sqlite3_value_text16() interface extracts a UTF-16 string in the native byte-order of the host machine. The sqlite3_value_text16be() and sqlite3_value_text16le() interfaces extract UTF-16 strings as big-endian and little-endian respectively.
If Sq3ValueC object V was initialized using Sq3StmtBindPointer (S,I,P,X,D) or sqlite3_result_pointer (C,P,X,D) and if X and Y are strings that compare equal according to strcmp(X,Y), then Sq3ValuePointer(V,Y) will return the pointer P. Otherwise, Sq3ValuePointer(V,Y) returns a NULL. The Sq3StmtBindPointer() routine is part of the pointer passing interface added for SQLite 3.20.0.
The Sq3ValueType(V) interface returns the datatype code for the initial datatype of the Sq3ValueC object V. The returned value is one of SQ3_TYPE_INTEGER, SQ3_TYPE_FLOAT, SQ3_TYPE_TEXT, SQ3_TYPE_BLOB, or SQ3_TYPE_NULL. Other interfaces might change the datatype for an Sq3ValueC object. For example, if the datatype is initially SQ3_TYPE_INTEGER and Sq3ValueText(V) is called to extract a text value for that integer, then subsequent calls to Sq3ValueType(V) might return SQ3_TYPE_TEXT. Whether or not a persistent internal datatype conversion occurs is undefined and may change from one release of SQLite to the next.
The Sq3ValueNumericType() interface attempts to apply numeric affinity to the value. This means that an attempt is made to convert the value to an integer or floating point. If such a conversion is possible without loss of information (in other words, if the value is a string that looks like a number) then the conversion is performed. Otherwise no conversion occurs. The datatype after conversion is returned.
Within the xUpdate method of a virtual table, the Sq3ValueNoChange(X) interface returns true if and only if the column corresponding to X is unchanged by the UPDATE operation that the xUpdate method call was invoked to implement and if and the prior xColumn method call that was invoked to extracted the value for that column returned without setting a result (probably because it queried sqlite3_vtab_nochange () and found that the column was unchanging). Within an xUpdate method, any value for which Sq3ValueNoChange(X) is true will in all other respects appear to be a NULL value. If Sq3ValueNoChange(X) is invoked anywhere other than within an xUpdate method call for an UPDATE statement, then the return value is arbitrary and meaningless.
The Sq3ValueFromBind(X) interface returns non-zero if the value X originated from one of the sqlite3_bind() interfaces. If X comes from an SQL literal value, or a table column, or an expression, then Sq3ValueFromBind(X) returns zero.
Please pay particular attention to the fact that the pointer returned from Sq3ValueBlob (), Sq3ValueText (), or sqlite3_value_text16 () can be invalidated by a subsequent call to Sq3ValueBytes (), sqlite3_value_bytes16 (), Sq3ValueText (), or sqlite3_value_text16 ().
These routines must be called from the same thread as the SQL function that supplied the Sq3ValueC* parameters.
As long as the input parameter is correct, these routines can only fail if an out-of-memory error occurs during a format conversion. Only the following subset of interfaces are subject to out-of-memory errors:
If an out-of-memory error occurs, then the return value from these routines is the same as if the column had contained an SQL NULL value. Valid SQL NULL returns can be distinguished from out-of-memory errors by invoking the Sq3LiteErrCode () immediately after the suspect return value is obtained and before any other SQLite interface is called on the same database connection.
Reference code from sqlite3:
(runtime) MK_BUF Sq3ValueBUF(SQ3_VALN const val)top Obtaining a MkBufferC value… → API: Sq3ValueBUF_RT
read more at Sq3ValueBlobHide
| [in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
| [in] | val | Programming-Language-Micro-Kernel (PLMK) instance from sqlite3_value |
MK_DBL Sq3ValueDouble(SQ3_VALN sq3val)top Obtaining SQL Values … → API: Sq3ValueDouble
MK_I32 Sq3ValueInt(SQ3_VALN sq3val)top Obtaining SQL Values … → API: Sq3ValueInt
MK_I64 Sq3ValueInt64(SQ3_VALN sq3val)top Obtaining SQL Values … → API: Sq3ValueInt64
(hide) MK_PTR Sq3ValuePointer(SQ3_VALN sq3val, MK_STRN arg1)top Obtaining SQL Values … → API: Sq3ValuePointer
MkStringR Sq3ValueStringR(SQ3_VALN sq3val)top Obtaining SQL Values … → API: Sq3ValueStringR
read more at 'Sq3ValueBlobHide'
MK_NULL for a non-error result. MK_STRN Sq3ValueText(SQ3_VALN sq3val)top Obtaining SQL Values … → API: Sq3ValueText
C-API: Sq3ValueC_Vtab_C_API - Sq3ValueC - work with the virtual-file-system …
enum MkErrorE Sq3ValueVtabInFirst(SQ3_VAL pVal, SQ3_VAL *ppOut)top Find all elements on the right-hand side of an IN constraint … → API: Sq3ValueVtabInFirst
These interfaces are only useful from within the xFilter() method of a virtual table implementation. The result of invoking these interfaces from any other context is undefined and probably harmful.
The X parameter in a call to Sq3ValueVtabInFirst(X,P) or Sq3ValueVtabInNext(X,P) should be one of the parameters to the xFilter method which invokes these routines, and specifically a parameter that was previously selected for all-at-once IN constraint processing use the sqlite3_vtab_in () interface in the xBestIndex method. If the X parameter is not an xFilter argument that was selected for all-at-once IN constraint processing, then these routines return SQ3_RESULT_ERROR.
Use these routines to access all values on the right-hand side of the IN constraint using code like the following:
for(rc=sqlite3_vtab_in_first(pList, &pVal);
rc==SQ3_RESULT_OK && pVal;
rc=sqlite3_vtab_in_next(pList, &pVal)
){
// do something with pVal
}
if( rc!=SQ3_RESULT_OK ){
// an error has occurred
}
On success, the Sq3ValueVtabInFirst(X,P) and Sq3ValueVtabInNext(X,P) routines return SQ3_RESULT_OK and set *P to point to the first or next value on the RHS of the IN constraint. If there are no more values on the right hand side of the IN constraint, then *P is set to NULL and these routines return SQ3_RESULT_DONE. The return value might be some other value, such as SQ3_RESULT_NOMEM, in the event of a malfunction.
The *ppOut values returned by these routines are only valid until the next call to either of these routines or until the end of the xFilter method from which these routines were called. If the virtual table implementation needs to retain the *ppOut values for longer, it must make copies. The *ppOut values are protected.
Reference code from sqlite3:
enum MkErrorE Sq3ValueVtabInNext(SQ3_VAL pVal, SQ3_VAL *ppOut)top Find all elements on the right-hand side of an IN constraint … → API: Sq3ValueVtabInNext
read more at 'Sq3ValueVtabInFirst'
| Sq3StmtC CLASS | |||
| Define | Sq3StmtC - low level definition, access and cast … | ||
| Export | Sq3StmtC - Export class functions … | ||
| Introspection | Sq3StmtC - Introspection class functions … | ||
| Misc | Sq3StmtC - Misc class functions … | ||
| Sq3StmtC TOR | |||
| PrepareV2 | Compiling An SQL Statement … | ||
| PrepareV2Hide | Compiling An SQL Statement … | ||
| PrepareV3 | Compiling An SQL Statement … | ||
| PrepareV3Hide | Compiling An SQL Statement … | ||
| Finalize | Destroy A Prepared Statement Object … | ||
| Sq3StmtC BIND | |||
| BindBlob | Bind a MkBinaryR Value To a Prepared Statement … | ||
| BindBlob64 | Bind a MkBinaryR Value To a Prepared Statement … | ||
| BindBlob64Hide | Binding Values To Prepared Statements … | ||
| BindBlobHide | Binding Values To Prepared Statements … | ||
| BindDouble | Binding Values To Prepared Statements … | ||
| BindInt | Binding Values To Prepared Statements … | ||
| BindInt64 | Binding Values To Prepared Statements … | ||
| BindNull | Binding Values To Prepared Statements … | ||
| BindParameterCount | Number Of SQL Parameters … | ||
| BindParameterIndex | Index Of A Parameter With A Given Name … | ||
| BindParameterName | Name Of A Host Parameter … | ||
| BindPointer | Binding Values To Prepared Statements … | ||
| BindText | Bind a MkStringR Value To a Prepared Statement … | ||
| BindText64 | Bind a MkStringR Value To a Prepared Statement … | ||
| BindText64Hide | Binding Values To Prepared Statements … | ||
| BindTextHide | Binding Values To Prepared Statements … | ||
| BindValue | Binding Values To Prepared Statements … | ||
| BindZeroblob | Binding Values To Prepared Statements … | ||
| BindZeroblob64 | Binding Values To Prepared Statements … | ||
| Sq3StmtC COLUMN | |||
| ColumnBlob | Result a MkBinaryR Value From A Query. | ||
| ColumnBlobHide | Result Values From A Query … | ||
| ColumnBytes | Result Values From A Query … | ||
| ColumnCount | Number Of Columns In A Result Set … | ||
| ColumnDecltype | Declared Datatype Of A Query Result … | ||
| ColumnDouble | Result Values From A Query … | ||
| ColumnInt | Result Values From A Query … | ||
| ColumnInt64 | Result Values From A Query … | ||
| ColumnName | Column Names In A Result Set … | ||
| ColumnText | Result a MkStringR Value From A Query. | ||
| ColumnTextHide | Result Values From A Query … | ||
| ColumnType | Result Values From A Query … | ||
| ColumnValue | Result Values From A Query … | ||
| Sq3StmtC INFO | |||
| Busy | Determine If A Prepared Statement Has Been Reset … | ||
| DataCount | Number of columns in a result set … | ||
| DbHandle | Find The Database Handle Of A Prepared Statement … | ||
| IsExplain | Query The EXPLAIN Setting For A Prepared Statement … | ||
| Log | log the val … | ||
| Readonly | Determine If An SQL Statement Writes The Database … | ||
| Status | Prepared Statement Status … | ||
| Sq3StmtC SQL | |||
| ExpandedSql | Retrieving Statement SQL … | ||
| GetPzTail | return the non compiled sql-statement from Sq3StmtPrepareV2 and Sq3StmtPrepareV3 … | ||
| Sql | Retrieving Statement SQL … | ||
| Sq3StmtC MISC | |||
| NextStmt | Find the next prepared statement … | ||
| ClearBindings | Reset All Bindings On A Prepared Statement … | ||
| Explain | Change The EXPLAIN Setting For A Prepared Statement … | ||
| Reset | Reset A Prepared Statement Object … | ||
| Step | Evaluate An SQL Statement … | ||
C-API: Sq3StmtC_C_API - Sq3StmtC - the class known as sq3stmt or Statement defined by Sq3StmtS …
Struct to represent the data of the Sq3StmtC …
Prepared Statement Object …
An instance of this object represents a single SQL statement that has been compiled into binary form and is ready to be evaluated.
Think of each SQL statement as a separate computer program. The original SQL text is source code. A prepared statement object is the compiled object code. All SQL must be converted into a prepared statement before it can be run.
The life-cycle of a prepared statement object usually goes like this:
Reference code from sqlite3:
| Stmt | cast a unknown-object into an Sq3StmtS pointer or NULL if not possible | ||
| StmtCheck | check Sq3StmtS -> MkObjectS::signature … | ||
| StmtCheckO | check Sq3StmtS -> MkObjectS::signature … | ||
| StmtN | (const) cast a unknown-object into an Sq3StmtS pointer or NULL if not possible | ||
| HandleResolve | Handle-Resolve-Slot - return a Sq3StmtC from netHdl or MK_NULL if invalid… | ||
| HandleGet | Handle-Get-Slot - returns a export-hdl to the Sq3StmtC useable for external storage | ||
| Instances | get head-instance from linked-list of Sq3StmtS type … | ||
| Next | get next instance from linked-list of Sq3StmtS type | ||
| Prev | get previous instance from linked-list of Sq3StmtS type | ||
| GetNull | Null-Slot - return a Sq3StmtC typed | ||
C-API: Sq3StmtC_Class_C_API - Sq3StmtC - define the class …
C-API: Sq3StmtC_Class_Define_C_API - Sq3StmtC - low level definition, access and cast …
(static,hide) SQ3_STMT Sq3Stmt(MK_MNG mng)top cast a unknown-object into an Sq3StmtS pointer or NULL if not possible → API: Sq3Stmt
(static,hide) MK_BOOL Sq3StmtCheck(MK_MNGN mng)top check Sq3StmtS -> MkObjectS::signature … → API: Sq3StmtCheck
(static,hide) MK_BOOL Sq3StmtCheckO(MK_OBJN obj)top check Sq3StmtS -> MkObjectS::signature … → API: Sq3StmtCheckO
(static,hide) SQ3_STMTN Sq3StmtN(MK_MNGN mng)top (const) cast a unknown-object into an Sq3StmtS pointer or NULL if not possible → API: Sq3StmtN
Sq3StmtC - Export class functions …
(static,runtime) SQ3_STMT Sq3StmtHandleResolve(MK_HDL const netHdl)top Handle-Resolve-Slot - return a Sq3StmtC from netHdl or MK_NULL if invalid… → API: Sq3StmtHandleResolve_RT
The Sq3StmtHandleResolve undo the Sq3StmtHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).
| [in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
| [in] | netHdl | handle former exported with Sq3StmtHandleGet |
MK_NULL if netHdl is invalid (runtime) MK_HDL Sq3StmtHandleGet(SQ3_STMT const stmt)top Handle-Get-Slot - returns a export-hdl to the Sq3StmtC useable for external storage → API: Sq3StmtHandleGet_RT
The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the Sq3StmtHandleResolve.
The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.
example: The export-hdl is used in rpc to identify an object across the network.
| [in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
| [in] | stmt | Programming-Language-Micro-Kernel (PLMK) instance from sqlite3_stmt |
Sq3StmtC - Introspection class functions …
(static,runtime) SQ3_STMT Sq3StmtInstances()top get head-instance from linked-list of Sq3StmtS type … → API: Sq3StmtInstances_RT
The head-instance is the last instance created.
SQ3_STMT Sq3StmtNext(SQ3_STMT const stmt)top get next instance from linked-list of Sq3StmtS type → API: Sq3StmtNext
SQ3_STMT Sq3StmtPrev(SQ3_STMT const stmt)top get previous instance from linked-list of Sq3StmtS type → API: Sq3StmtPrev
Sq3StmtC - Misc class functions …
(static) SQ3_STMT Sq3StmtGetNull()top Null-Slot - return a Sq3StmtC typed NULL instance … → API: Sq3StmtGetNull
C-API: Sq3StmtC_TOR_C_API - Sq3StmtC - various functions to create, initialize and destroy …
(constructor,static) enum MkErrorE Sq3StmtPrepareV2(SQ3_LITE db, MkStringR zSql, SQ3_STMT *ppStmt)top Compiling An SQL Statement … → API: Sq3StmtPrepareV2
This is an enhanced version of Sq3StmtPrepareV2Hide using the Programming-Language-Micro-Kernel (PLMK) definition of a zSql called MkStringR. The last argument pzTail is stored into the Sq3StmtC class Sq3StmtS::pzTail attribute and can be accessed with Sq3StmtGetPzTail.
| [in] | db | the Sq3LiteC instance to work on a database |
| [in] | zSql | The statement to be compiled, encoded as UTF-8 |
| [out] | ppStmt | The new Sq3StmtC instance |
If the database schema changes, instead of returning SQ3_RESULT_SCHEMA as it always used to do, Sq3StmtStep () will automatically recompile the SQL statement and try to run it again. As many as SQLITE_MAX_SCHEMA_RETRY retries will occur before Sq3StmtStep() gives up and returns an error.
When an error occurs, Sq3StmtStep () will return one of the detailed error codes or extended error codes. The legacy behavior was that Sq3StmtStep () would only return a generic SQ3_RESULT_ERROR result code and the application would have to make a second call to Sq3StmtReset () in order to find the underlying cause of the problem. With the "v2" prepare interfaces, the underlying reason for the error is returned immediately.
(constructor,static,hide) enum MkErrorE Sq3StmtPrepareV2Hide(SQ3_LITE db, MK_STRN zSql, MK_I32 nByte, SQ3_STMT *ppStmt, MK_STRN *pzTail)top Compiling An SQL Statement … → API: Sq3StmtPrepareV2Hide
To execute an SQL statement, it must first be compiled into a byte-code program using one of these routines. Or, in other words, these routines are constructors for the prepared statement object.
The preferred routine to use is Sq3StmtPrepareV2 (). The sqlite3_prepare () interface is legacy and should be avoided. Sq3StmtPrepareV3 () has an extra "prepFlags" option that is used for special purposes.
The use of the UTF-8 interfaces is preferred, as SQLite currently does all parsing using UTF-8. The UTF-16 interfaces are provided as a convenience. The UTF-16 interfaces work by converting the input text into UTF-8, then invoking the corresponding UTF-8 interface.
The first argument, "db", is a database connection obtained from a prior successful call to sqlite3_open (), Sq3LiteOpenV2 () or sqlite3_open16 (). The database connection must not have been closed.
The second argument, "zSql", is the statement to be compiled, encoded as either UTF-8 or UTF-16. The sqlite3_prepare(), Sq3StmtPrepareV2(), and Sq3StmtPrepareV3() interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(), and sqlite3_prepare16_v3() use UTF-16.
If the nByte argument is negative, then zSql is read up to the first zero terminator. If nByte is positive, then it is the number of bytes read from zSql. If nByte is zero, then no prepared statement is generated. If the caller knows that the supplied string is nul-terminated, then there is a small performance advantage to passing an nByte parameter that is the number of bytes in the input string including the nul-terminator.
If pzTail is not NULL then *pzTail is made to point to the first byte past the end of the first SQL statement in zSql. These routines only compile the first statement in zSql, so *pzTail is left pointing to what remains uncompiled.
ppStmt is left pointing to a compiled prepared statement that can be executed using Sq3StmtStep (). If there is an error, *ppStmt is set to NULL. If the input text contains no SQL (if the input is an empty string or a comment) then *ppStmt is set to NULL. The calling procedure is responsible for deleting the compiled SQL statement using Sq3StmtFinalize () after it has finished with it. ppStmt may not be NULL.
On success, the sqlite3_prepare() family of routines return SQ3_RESULT_OK; otherwise an error code is returned.
The Sq3StmtPrepareV2(), Sq3StmtPrepareV3(), sqlite3_prepare16_v2(), and sqlite3_prepare16_v3() interfaces are recommended for all new programs. The older interfaces (sqlite3_prepare() and sqlite3_prepare16()) are retained for backwards compatibility, but their use is discouraged. In the "vX" interfaces, the prepared statement that is returned (the Sq3StmtC object) contains a copy of the original SQL text. This causes the Sq3StmtStep () interface to behave differently in three ways:
If the database schema changes, instead of returning SQ3_RESULT_SCHEMA as it always used to do, Sq3StmtStep () will automatically recompile the SQL statement and try to run it again. As many as SQLITE_MAX_SCHEMA_RETRY retries will occur before Sq3StmtStep() gives up and returns an error.
When an error occurs, Sq3StmtStep () will return one of the detailed error codes or extended error codes. The legacy behavior was that Sq3StmtStep () would only return a generic SQ3_RESULT_ERROR result code and the application would have to make a second call to Sq3StmtReset () in order to find the underlying cause of the problem. With the "v2" prepare interfaces, the underlying reason for the error is returned immediately.
Sq3StmtPrepareV3() differs from Sq3StmtPrepareV2() only in having the extra prepFlags parameter, which is a bit array consisting of zero or more of the SQ3_PREPARE_* flags. The Sq3StmtPrepareV2() interface works exactly the same as Sq3StmtPrepareV3() with a zero prepFlags parameter.
Reference code from sqlite3:
(constructor,static) enum MkErrorE Sq3StmtPrepareV3(SQ3_LITE db, MkStringR zSql, enum Sq3PrepareEF prepFlags, SQ3_STMT *ppStmt)top Compiling An SQL Statement … → API: Sq3StmtPrepareV3
This is an enhanced version of Sq3StmtPrepareV2Hide using the Programming-Language-Micro-Kernel (PLMK) definition of a zSql called MkStringR. The last argument pzTail is stored into the Sq3StmtC class Sq3StmtS::pzTail attribute and can be accessed with Sq3StmtGetPzTail.
| [in] | db | the Sq3LiteC instance to work on a database |
| [in] | zSql | The statement to be compiled, encoded as UTF-8 |
| [in] | prepFlags | Is a bit array consisting of zero or more of the SQ3_PREPARE_* flags. |
| [out] | ppStmt | The new Sq3StmtC instance |
(constructor,static,hide) enum MkErrorE Sq3StmtPrepareV3Hide(SQ3_LITE db, MK_STRN zSql, MK_I32 nByte, enum Sq3PrepareEF prepFlags, SQ3_STMT *ppStmt, MK_STRN *pzTail)top Compiling An SQL Statement … → API: Sq3StmtPrepareV3Hide
read more at 'Sq3StmtPrepareV2'
(destructor) enum MkErrorE Sq3StmtFinalize(SQ3_STMT pStmt)top Destroy A Prepared Statement Object … → API: Sq3StmtFinalize
The Sq3StmtFinalize() function is called to delete a prepared statement. If the most recent evaluation of the statement encountered no errors or if the statement is never been evaluated, then Sq3StmtFinalize() returns SQ3_RESULT_OK. If the most recent evaluation of statement S failed, then Sq3StmtFinalize(S) returns the appropriate error code or extended error code.
The Sq3StmtFinalize(S) routine can be called at any point during the life cycle of prepared statement S: before statement S is ever evaluated, after one or more calls to Sq3StmtReset (), or after any call to Sq3StmtStep () regardless of whether or not the statement has completed execution.
Invoking Sq3StmtFinalize() on a NULL pointer is a harmless no-op.
The application must finalize every prepared statement in order to avoid resource leaks. It is a grievous error for the application to try to use a prepared statement after it has been finalized. Any use of a prepared statement after it has been finalized can result in undefined and undesirable behavior such as segfaults and heap corruption.
Reference code from sqlite3:
C-API: Sq3StmtC_Bind_C_API - Sq3StmtC - bind a type …
(runtime) enum MkErrorE Sq3StmtBindBlob(SQ3_STMT sq3stmt, MK_I32 pos, MkBinaryR blob)top Bind a MkBinaryR Value To a Prepared Statement … → API: Sq3StmtBindBlob_RT
This is an enhanced version of Sq3StmtBindBlob64Hide using the Programming-Language-Micro-Kernel (PLMK) definition of a blob called MkBinaryR and the default value for the cb as SQLITE_TRANSIENT.
| [in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
| [in] | sq3stmt | the Sq3StmtC instance to work on a statement |
| [in] | pos | The index of the SQL parameter to be set, the leftmost SQL parameter has an index of 1. |
| [in] | blob | The MkBinaryR value to be bind. |
(runtime,hide) enum MkErrorE Sq3StmtBindBlob64(SQ3_STMT sq3stmt, MK_I32 pos, MkBinaryR blob)top Bind a MkBinaryR Value To a Prepared Statement … → API: Sq3StmtBindBlob64_RT
This is an enhanced version of Sq3StmtBindBlob64Hide using the Programming-Language-Micro-Kernel (PLMK) definition of a blob called MkBinaryR and the default value for the cb as SQLITE_TRANSIENT.
| [in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
| [in] | sq3stmt | the Sq3StmtC instance to work on a statement |
| [in] | pos | The index of the SQL parameter to be set, the leftmost SQL parameter has an index of 1. |
| [in] | blob | The MkBinaryR value to be bind. |
(hide) enum MkErrorE Sq3StmtBindBlob64Hide(SQ3_STMT sq3stmt, MK_I32 pos, MK_PTRN blob, MK_I64 len, Sq3Fupu_Sq3StmtBindBlob64Hide_cb cb)top Binding Values To Prepared Statements … → API: Sq3StmtBindBlob64Hide
read more at 'Sq3StmtBindBlob'
(hide) enum MkErrorE Sq3StmtBindBlobHide(SQ3_STMT sq3stmt, MK_I32 pos, MK_PTRN blob, MK_I32 len, Sq3Fupu_Sq3StmtBindBlobHide_cb cb)top Binding Values To Prepared Statements … → API: Sq3StmtBindBlobHide
In the SQL statement text input to Sq3StmtPrepareV2 () and its variants, literals may be replaced by a parameter that matches one of following templates:
In the templates above, NNN represents an integer literal, and VVV represents an alphanumeric identifier. The values of these parameters (also called "host parameter names" or "SQL parameters") can be set using the Sq3StmtBindValue*() routines defined here.
The first argument to the Sq3StmtBindValue*() routines is always a pointer to the Sq3StmtC object returned from Sq3StmtPrepareV2 () or its variants.
The second argument is the index of the SQL parameter to be set. The leftmost SQL parameter has an index of 1. When the same named SQL parameter is used more than once, second and subsequent occurrences have the same index as the first occurrence. The index for named parameters can be looked up using the Sq3StmtBindParameterIndex () API if desired. The index for "?NNN" parameters is the value of NNN. The NNN value must be between 1 and the Sq3LiteLimit () parameter SQ3_LIMIT_VARIABLE_NUMBER (default value: 32766).
The third argument is the value to bind to the parameter. If the third parameter to Sq3StmtBindText() or sqlite3_bind_text16() or Sq3StmtBindBlob() is a NULL pointer then the fourth parameter is ignored and the end result is the same as Sq3StmtBindNull(). If the third parameter to Sq3StmtBindText() is not NULL, then it should be a pointer to well-formed UTF8 text. If the third parameter to sqlite3_bind_text16() is not NULL, then it should be a pointer to well-formed UTF16 text. If the third parameter to Sq3StmtBindText64() is not NULL, then it should be a pointer to a well-formed unicode string that is either UTF8 if the sixth parameter is SQ3_TEXT_UTF8, or UTF16 otherwise.
The byte-order of UTF16 input text is determined by the byte-order mark (BOM, U+FEFF) found in first character, which is removed, or in the absence of a BOM the byte order is the native byte order of the host machine for