IViewFilter::SetFilter

  • Article

Specifies a filter condition for a view.

Syntax

HRESULT SetFilter (
   HACCESSOR     hAccessor,
   DBCOUNTITEM   cRows,
   DBCOMPAREOP   CompareOps[],
   void         *pCriteriaData);

Parameters

  • hAccessor
    [in] The handle of the accessor that describes the data in pCriteriaData. The same column may appear more than once in the criteria.

  • cRows
    [in] The number of rows in the criteria table, where the criteria described by each row is joined in a logical OR with the other rows. Some providers may have limits on the number of rows (OR conditions) that can be expressed in the criteria.

  • CompareOps
    [in] A two-dimensional array containing cRows by cBindings comparison operators in cRows-major format, where cBindings is the number of columns represented in hAccessor. Each comparison operator in the cBindings dimension refers to a column in pCriteriaData, and each set of columns in the pcRows dimension refers to a row in pCriteriaData. Columns within a row are joined together in a logical AND, and each row is joined in a logical OR with another row. The consumer should check DBPROP_FINDCOMPAREOPS to determine which comparison operators the provider supports. For information about the DBCOMPAREOP enumerated type, see IRowsetFind::FindNextRow.

    Note

    The expression column DBCOMPAREOPS_IGNORE value always resolves to TRUE when used with the IViewFilter::SetFilter.

  • pCriteriaData
    [in] A pointer to memory containing the data values, at offsets that correspond to the bindings in the accessor that, in conjunction with the array of comparison operators, define the criteria.

Return Code

  • S_OK
    The method succeeded.

  • E_FAIL
    A provider-specific error occurred.

  • DB_E_BADCOMPAREOP
    In an element of CompareOps, both DBCOMPAREOPS_CASESENSITIVE and DBCOMPAREOPS_CASEINSENSITIVE were specified.

    The provider was asked for an option that it does not support.

  • DB_E_CANTFILTER
    The described filter could not be applied. The provider may have limitations on the columns used in a filter or a limitation on the complexity of the filter.

Comments

A provider may restrict filter columns to use only existing indexes or may restrict a filter to work only with an order chapter as a source.

If there is already a filter condition applied to a view, IViewFilter::SetFilter overrides that previous filter condition.

The behavior of ADO filters containing chapter columns is undefined.

Changing the filter condition of a view does not change the filtering of any rowsets or chapters opened using that view.

For example, given filter criteria of "(column1 < 10) or (column1 > 20)":

  1. Build two bindings, each referring to column 1, and suitable for the column's data type. In this case, assume the data type is DBTYPE_I4.

  2. Assign the bindings to an accessor.

  3. Construct a buffer for the criteria data. The buffer contains two values, each of a data type equivalent to DBTYPE_I4, with the first value set to 10 and the second to 20 ? in this case: LONG rgCriteriaData[] = {10, 20};

  4. Set a pCriteriaData with the address of the criteria data buffer. In this case, the array name is equivalent to the buffer address.

  5. Construct an array of comparison operators consisting of two elements ? in this case:

    DBCOMPAREOPS rgCompareOps[] = {DBCOMPAREOPS_LT, DBCOMPAREOPSS_GT};

  6. Set cRows to 2 so that the comparison operators are treated as two rows ? that is, so that the comparisons are joined in a logical OR operation.

  7. Execute IViewFilter::SetFilter. In this case, the method call is similar to

    pIViewFilter->SetFilter(hAccessor, 2, rgCompareOps, rgCriteriaData);

When the method executes, a filter condition is set where, as specified in the first binding, column 1 is compared via the DBCOMPAREOP_LT operator with the value 10. Then, as specified in the second binding, column 1 is compared via the DBCOMPAREOP_GT operator with the value 20. Then the two comparisons are joined in a logical OR operation.