Share via

IViewSort::SetSortOrder

  • Article

Specifies a sort order to be applied to a view.

Syntax

HRESULT SetSortOrder (
   DBORDINAL         cColumns,
   const DBORDINAL   rgColumns[],
   const DBSORT      rgOrders[]);

Parameters

  • cColumns
    [in] Count of the number of columns to be used in specifying the order, or zero to clear any sort order previously set on the view.

  • rgColumns
    [in] The ordinals of the columns used to describe the sort. The order of the columns in the list defines the precedence of the columns in the sort. This argument is ignored if cColumns is zero.

  • rgOrders
    [in] The sort order for the corresponding column in the rgColumns list. This argument is ignored if cColumns is zero.

    The DBSORT structure is as follows:

    typedef DWORD DBSORT;

enum DBSORTENUM {
   DBSORT_ASCENDING = 0,
   DBSORT_DESCENDING
};

Return Code

  • S_OK
    The method succeeded.

  • E_FAIL
    A provider-specific error occurred.

  • E_INVALIDARG
    rgColumns was NULL, and cColumns was not equal to zero.

    rgOrders was NULL, and cColumns was not equal to zero.

  • DB_E_CANTORDER
    The described order could not be opened. The provider may have limitations on the columns used in an order or a limitation on the complexity of the order.

    The same column ordinal appeared multiple times in rgColumns.

Comments

A provider may impose constraints on the columns that can be used for sorting. For example, a provider may support ordering only on columns for which there exists an index. If the provider does not support sorting for the specified columns, it returns DB_E_CANTORDER. If there is already a sort order applied to a view, IViewSort::SetSortOrder overrides the previous sort order.

The setting of sort columns is atomic. If any columns cannot be set, IViewSort::SetSortOrder returns DB_E_CANTORDER and the sort order for the view remains unchanged.

Changing the sort order of a view does not change the sort order of any rowsets or chapters previously opened using that view.