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