1.Dd January 24, 2024 2.Dt SQLITE3_VTAB_RHS_VALUE 3 3.Os 4.Sh NAME 5.Nm sqlite3_vtab_rhs_value 6.Nd constraint values in xBestIndex() 7.Sh SYNOPSIS 8.In sqlite3.h 9.Ft int 10.Fo sqlite3_vtab_rhs_value 11.Fa "sqlite3_index_info*" 12.Fa "int" 13.Fa "sqlite3_value **ppVal" 14.Fc 15.Sh DESCRIPTION 16This API may only be used from within the xBestIndex method 17of a virtual table implementation. 18The result of calling this interface from outside of an xBestIndex 19method are undefined and probably harmful. 20.Pp 21When the sqlite3_vtab_rhs_value(P,J,V) interface is invoked from within 22the xBestIndex method of a virtual table implementation, 23with P being a copy of the sqlite3_index_info object 24pointer passed into xBestIndex and J being a 0-based index into P->aConstraint[], 25then this routine attempts to set *V to the value of the right-hand 26operand of that constraint if the right-hand operand is known. 27If the right-hand operand is not known, then *V is set to a NULL pointer. 28The sqlite3_vtab_rhs_value(P,J,V) interface returns SQLITE_OK if and 29only if *V is set to a value. 30The sqlite3_vtab_rhs_value(P,J,V) inteface returns SQLITE_NOTFOUND 31if the right-hand side of the J-th constraint is not available. 32The sqlite3_vtab_rhs_value() interface can return an result code other 33than SQLITE_OK or SQLITE_NOTFOUND if something goes wrong. 34.Pp 35The sqlite3_vtab_rhs_value() interface is usually only successful if 36the right-hand operand of a constraint is a literal value in the original 37SQL statement. 38If the right-hand operand is an expression or a reference to some other 39column or a host parameter, then sqlite3_vtab_rhs_value() 40will probably return SQLITE_NOTFOUND. 41.Pp 42Some constraints, such as SQLITE_INDEX_CONSTRAINT_ISNULL 43and SQLITE_INDEX_CONSTRAINT_ISNOTNULL, 44have no right-hand operand. 45For such constraints, sqlite3_vtab_rhs_value() always returns SQLITE_NOTFOUND. 46.Pp 47The sqlite3_value object returned in *V is a protected 48sqlite3_value and remains valid for the duration of the xBestIndex 49method call. 50When xBestIndex returns, the sqlite3_value object returned by sqlite3_vtab_rhs_value() 51is automatically deallocated. 52.Pp 53The "_rhs_" in the name of this routine is an abbreviation for "Right-Hand 54Side". 55.Sh IMPLEMENTATION NOTES 56These declarations were extracted from the 57interface documentation at line 10083. 58.Bd -literal 59SQLITE_API int sqlite3_vtab_rhs_value(sqlite3_index_info*, int, sqlite3_value **ppVal); 60.Ed 61.Sh SEE ALSO 62.Xr sqlite3_bind_blob 3 , 63.Xr sqlite3_index_info 3 , 64.Xr sqlite3_value 3 , 65.Xr SQLITE_INDEX_CONSTRAINT_EQ 3 , 66.Xr SQLITE_OK 3 67