1.Dd $Mdocdate$ 2.Dt SQLITE3_PREUPDATE_HOOK 3 3.Os 4.Sh NAME 5.Nm sqlite3_preupdate_hook , 6.Nm sqlite3_preupdate_old , 7.Nm sqlite3_preupdate_count , 8.Nm sqlite3_preupdate_depth , 9.Nm sqlite3_preupdate_new 10.Nd The pre-update hook. 11.Sh SYNOPSIS 12.Ft void *SQLITE_STDCALL 13.Fo sqlite3_preupdate_hook 14.Fa "sqlite3 *db" 15.Fa "void(*xPreUpdate)( void *pCtx, sqlite3 *db, int op, char const *zDb, char const *zName, sqlite3_int64 iKey1, sqlite3_int64 iKey2 )" 16.Fa "void* " 17.Fc 18.Ft int SQLITE_STDCALL 19.Fo sqlite3_preupdate_old 20.Fa "sqlite3 *" 21.Fa "int" 22.Fa "sqlite3_value **" 23.Fc 24.Ft int SQLITE_STDCALL 25.Fo sqlite3_preupdate_count 26.Fa "sqlite3 *" 27.Fc 28.Ft int SQLITE_STDCALL 29.Fo sqlite3_preupdate_depth 30.Fa "sqlite3 *" 31.Fc 32.Ft int SQLITE_STDCALL 33.Fo sqlite3_preupdate_new 34.Fa "sqlite3 *" 35.Fa "int" 36.Fa "sqlite3_value **" 37.Fc 38.Sh DESCRIPTION 39These interfaces are only available if SQLite is compiled using the 40SQLITE_ENABLE_PREUPDATE_HOOK compile-time 41option. 42.Pp 43The sqlite3_preupdate_hook() interface registers 44a callback function that is invoked prior to each INSERT, UPDATE, 45and DELETE operation on a rowid table. 46At most one preupdate hook may be registered at a time on a single 47database connection; each call to sqlite3_preupdate_hook() 48overrides the previous setting. 49The preupdate hook is disabled by invoking sqlite3_preupdate_hook() 50with a NULL pointer as the second parameter. 51The third parameter to sqlite3_preupdate_hook() 52is passed through as the first parameter to callbacks. 53.Pp 54The preupdate hook only fires for changes to rowid tables; 55the preupdate hook is not invoked for changes to virtual tables 56or WITHOUT ROWID tables. 57.Pp 58The second parameter to the preupdate callback is a pointer to the 59database connection that registered the preupdate 60hook. 61The third parameter to the preupdate callback is one of the constants 62SQLITE_INSERT, SQLITE_DELETE, or SQLITE_UPDATE 63to indentify the kind of update operation that is about to occur. 64The fourth parameter to the preupdate callback is the name of the database 65within the database connection that is being modified. 66This will be "main" for the main database or "temp" for TEMP tables 67or the name given after the AS keyword in the ATTACH statement 68for attached databases. 69The fifth parameter to the preupdate callback is the name of the table 70that is being modified. 71The sixth parameter to the preupdate callback is the initial rowid 72of the row being changes for SQLITE_UPDATE and SQLITE_DELETE changes 73and is undefined for SQLITE_INSERT changes. 74The seventh parameter to the preupdate callback is the final rowid 75of the row being changed for SQLITE_UPDATE and SQLITE_INSERT changes 76and is undefined for SQLITE_DELETE changes. 77.Pp 78The sqlite3_preupdate_old(), sqlite3_preupdate_new(), 79sqlite3_preupdate_count(), and sqlite3_preupdate_depth() 80interfaces provide additional information about a preupdate event. 81These routines may only be called from within a preupdate callback. 82Invoking any of these routines from outside of a preupdate callback 83or with a database connection pointer that is different 84from the one supplied to the preupdate callback results in undefined 85and probably undesirable behavior. 86.Pp 87The sqlite3_preupdate_count(D) interface 88returns the number of columns in the row that is being inserted, updated, 89or deleted. 90.Pp 91The sqlite3_preupdate_old(D,N,P) interface 92writes into P a pointer to a protected sqlite3_value 93that contains the value of the Nth column of the table row before it 94is updated. 95The N parameter must be between 0 and one less than the number of columns 96or the behavior will be undefined. 97This must only be used within SQLITE_UPDATE and SQLITE_DELETE preupdate 98callbacks; if it is used by an SQLITE_INSERT callback then the behavior 99is undefined. 100The sqlite3_value that P points to will be destroyed when 101the preupdate callback returns. 102.Pp 103The sqlite3_preupdate_new(D,N,P) interface 104writes into P a pointer to a protected sqlite3_value 105that contains the value of the Nth column of the table row after it 106is updated. 107The N parameter must be between 0 and one less than the number of columns 108or the behavior will be undefined. 109This must only be used within SQLITE_INSERT and SQLITE_UPDATE preupdate 110callbacks; if it is used by an SQLITE_DELETE callback then the behavior 111is undefined. 112The sqlite3_value that P points to will be destroyed when 113the preupdate callback returns. 114.Pp 115The sqlite3_preupdate_depth(D) interface 116returns 0 if the preupdate callback was invoked as a result of a direct 117insert, update, or delete operation; or 1 for inserts, updates, or 118deletes invoked by top-level triggers; or 2 for changes resulting from 119triggers called by top-level triggers; and so forth. 120.Pp 121.Sh SEE ALSO 122.Xr sqlite3 3 , 123.Xr sqlite3_value 3 , 124.Xr sqlite3_preupdate_hook 3 , 125.Xr sqlite3_update_hook 3 , 126.Xr sqlite3_value 3 , 127.Xr SQLITE_CREATE_INDEX 3 128