1.Dd March 11, 2017 2.Dt SQLITE3_PROGRESS_HANDLER 3 3.Os 4.Sh NAME 5.Nm sqlite3_progress_handler 6.Nd Query Progress Callbacks 7.Sh SYNOPSIS 8.Ft void 9.Fo sqlite3_progress_handler 10.Fa "sqlite3*" 11.Fa "int" 12.Fa "int(*)(void*)" 13.Fa "void*" 14.Fc 15.Sh DESCRIPTION 16The sqlite3_progress_handler(D,N,X,P) interface causes the callback 17function X to be invoked periodically during long running calls to 18sqlite3_exec(), sqlite3_step() and sqlite3_get_table() 19for database connection D. 20An example use for this interface is to keep a GUI updated during a 21large query. 22.Pp 23The parameter P is passed through as the only parameter to the callback 24function X. 25The parameter N is the approximate number of virtual machine instructions 26that are evaluated between successive invocations of the callback X. 27If N is less than one then the progress handler is disabled. 28.Pp 29Only a single progress handler may be defined at one time per database connection; 30setting a new progress handler cancels the old one. 31Setting parameter X to NULL disables the progress handler. 32The progress handler is also disabled by setting N to a value less 33than 1. 34.Pp 35If the progress callback returns non-zero, the operation is interrupted. 36This feature can be used to implement a "Cancel" button on a GUI progress 37dialog box. 38.Pp 39The progress handler callback must not do anything that will modify 40the database connection that invoked the progress handler. 41Note that sqlite3_prepare_v2() and sqlite3_step() 42both modify their database connections for the meaning of "modify" 43in this paragraph. 44.Pp 45.Sh SEE ALSO 46.Xr sqlite3 3 , 47.Xr sqlite3_exec 3 , 48.Xr sqlite3_get_table 3 , 49.Xr sqlite3_prepare 3 , 50.Xr sqlite3_step 3 51