void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
R-46053-13931:[The sqlite3_progress_handler(D,N,X,P) interface causes the callback function X to be invoked periodically during long running calls to sqlite3_exec(), sqlite3_step() and sqlite3_get_table() for database connection D. ] An example use for this interface is to keep a GUI updated during a large query.
R-41004-58299:[The parameter P is passed through as the only parameter to the callback function X. ] R-47237-20641:[The parameter N is the approximate number of virtual machine instructions that are evaluated between successive invocations of the callback X. ] R-22338-33270:[If N is less than one then the progress handler is disabled. ]
R-35765-61623:[Only a single progress handler may be defined at one time per database connection; setting a new progress handler cancels the old one. ] R-55398-57340:[Setting parameter X to NULL disables the progress handler. ] R-39556-50570:[The progress handler is also disabled by setting N to a value less than 1. ]
R-18444-13968:[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 sqlite3_prepare_v2() and sqlite3_step() both modify their database connections for the meaning of "modify" in this paragraph.
See also lists of Objects, Constants, and Functions.
*** DRAFT ***