IViewSort::SetSortOrder

Specifies a sort order to be applied to a view.

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

Parameters

cColumns

[in]
Count of the number of columns to be used in specifying the order, or zero in order 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 in cColumns is zero.

rgOrders

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

The DBSORT structure is

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 only support ordering 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, SetSortOrder overrides the previous sort order.

The setting of sort columns is atomic. If any columns cannot be set, then 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.