Small. Fast. Reliable.
Choose any three.

SQLite C Interface

Query Progress Callbacks

void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);

This routine configures a callback function - the progress callback - that is invoked periodically during long running calls to sqlite3_exec(), sqlite3_step() and sqlite3_get_table(). An example use for this interface is to keep a GUI updated during a large query.

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 must not do anything that will modify the database connection that invoked the progress handler. Note that sqlite3_prepare_v2() and sqlite3_step() both modify their database connections for the meaning of "modify" in this paragraph.

Invariants:

H12911 The callback function registered by sqlite3_progress_handler() is invoked periodically during long running calls to sqlite3_step().
H12912 The progress callback is invoked once for every N virtual machine opcodes, where N is the second argument to the sqlite3_progress_handler() call that registered the callback. If N is less than 1, sqlite3_progress_handler() acts as if a NULL progress handler had been specified.
H12913 The progress callback itself is identified by the third argument to sqlite3_progress_handler().
H12914 The fourth argument to sqlite3_progress_handler() is a void pointer passed to the progress callback function each time it is invoked.
H12915 If a call to sqlite3_step() results in fewer than N opcodes being executed, then the progress callback is never invoked.
H12916 Every call to sqlite3_progress_handler() overwrites any previously registered progress handler.
H12917 If the progress handler callback is NULL then no progress handler is invoked.
H12918 If the progress callback returns a result other than 0, then the behavior is a if sqlite3_interrupt() had been called.

See also lists of Objects, Constants, and Functions.


This page last modified 2008/12/09 18:44:04 UTC