1.Dd January 24, 2024 2.Dt SQLITE3_VTAB_IN_FIRST 3 3.Os 4.Sh NAME 5.Nm sqlite3_vtab_in_first , 6.Nm sqlite3_vtab_in_next 7.Nd find all elements on the right-hand side of an IN constraint 8.Sh SYNOPSIS 9.In sqlite3.h 10.Ft int 11.Fo sqlite3_vtab_in_first 12.Fa "sqlite3_value *pVal" 13.Fa "sqlite3_value **ppOut" 14.Fc 15.Ft int 16.Fo sqlite3_vtab_in_next 17.Fa "sqlite3_value *pVal" 18.Fa "sqlite3_value **ppOut" 19.Fc 20.Sh DESCRIPTION 21These interfaces are only useful from within the xFilter() method 22of a virtual table implementation. 23The result of invoking these interfaces from any other context is undefined 24and probably harmful. 25.Pp 26The X parameter in a call to sqlite3_vtab_in_first(X,P) or sqlite3_vtab_in_next(X,P) 27should be one of the parameters to the xFilter method which invokes 28these routines, and specifically a parameter that was previously selected 29for all-at-once IN constraint processing use the 30.Fn sqlite3_vtab_in 31interface in the xBestIndex method. 32If the X parameter is not an xFilter argument that was selected for 33all-at-once IN constraint processing, then these routines return SQLITE_ERROR. 34.Pp 35Use these routines to access all values on the right-hand side of the 36IN constraint using code like the following: 37.Bd -ragged 38.Bd -literal 39 for(rc=sqlite3_vtab_in_first(pList, &pVal); rc==SQLITE_OK 40&& pVal; rc=sqlite3_vtab_in_next(pList, &pVal) ){ // 41do something with pVal } if( rc!=SQLITE_OK ){ // an error 42has occurred } 43.Ed 44.Pp 45.Ed 46.Pp 47On success, the sqlite3_vtab_in_first(X,P) and sqlite3_vtab_in_next(X,P) 48routines return SQLITE_OK and set *P to point to the first or next 49value on the RHS of the IN constraint. 50If there are no more values on the right hand side of the IN constraint, 51then *P is set to NULL and these routines return SQLITE_DONE. 52The return value might be some other value, such as SQLITE_NOMEM, in 53the event of a malfunction. 54.Pp 55The *ppOut values returned by these routines are only valid until the 56next call to either of these routines or until the end of the xFilter 57method from which these routines were called. 58If the virtual table implementation needs to retain the *ppOut values 59for longer, it must make copies. 60The *ppOut values are protected. 61.Sh IMPLEMENTATION NOTES 62These declarations were extracted from the 63interface documentation at line 10035. 64.Bd -literal 65SQLITE_API int sqlite3_vtab_in_first(sqlite3_value *pVal, sqlite3_value **ppOut); 66SQLITE_API int sqlite3_vtab_in_next(sqlite3_value *pVal, sqlite3_value **ppOut); 67.Ed 68.Sh SEE ALSO 69.Xr sqlite3_value 3 , 70.Xr sqlite3_vtab_in 3 , 71.Xr SQLITE_OK 3 72