IMDFind::FindCell

OLE DB Programmer's Reference

Finds and returns a cell ordinal based on an array of members and a starting cell ordinal in the dataset.

HRESULT FindCell(    DBORDINAL     ulStartingOrdinal,    DBCOUNTITEM   cMembers,    LPCOLESTR    *rgpwszMember,    DBORDINAL    *pulCellOrdinal);

Parameters

ulStartingOrdinal

[in]
The cell ordinal from which to begin the search. For more information, see Comments.

cMembers

[in]
The cardinality of the rgpwszMember array.

rgpwszMember

[in]
An array of members. Each element of the array contains a member along a given axis. For more information, see Comments.

pulCellOrdinal

[out]
The ordinal value of the cell specified by the members in the rgpwszMember array.

Return Code

S_OK

The method succeeded.

E_FAIL

A provider-specific error occurred.

E_INVALIDARG

pulCellOrdinal was a null pointer.

cMembers was less than 1.

MD_E_BADCOORDINATE

ulStartingOrdinal did not identify a cell in the dataset.

The set of members for a given axis did not identify a valid tuple.

The set of tuples resulting from the member array did not identify a valid cell in the dataset beyond ulStartingOrdinal (inclusive).

One or more elements of the member array specified a member that does not exist.

One or more elements of the member array contained an ambiguous member specification.

Comments

The search is initiated from the cell identified by ulStartingOrdinal, in the direction of increasing axis ordinals. The starting cell is included in the search.

Each member string is null-terminated.

The members must be listed in increasing order of numeric axis identifiers, and members for a given axis must form a tuple on that axis. Constituent members of this tuple are listed in increasing order of dimension nesting—that is, members of the outermost dimension come first, followed by members of inner dimensions.

Note   Members must be specified with enough qualifiers to create an unambiguous reference. Using MEMBER_UNIQUE_NAME from the MEMBERS rowset accomplishes this because it is qualified to the extent required to create an unambiguous reference.

The members collectively specify a cell in the dataset. The provider generates a cell ordinal, identifying this cell, and returns a pointer to the ordinal, which can then be used as the input argument to IMDDataset::GetCellData. For more information on cell ordinals and how they are generated, see IMDDataset::GetCellData.

This method searches for an exact match in that it compares for equality. Since members must be qualified to create an unambiguous reference, there is no possibility (by definition) of finding more than one cell.

Because the same tuple can be repeated on an axis, there can be more than one cell identified by the same set of members. The parameter ulStartingOrdinal can be used to find all such occurrences. You call this method successively, setting ulStartingOrdinal to 0 for the first call. Successive calls increment the value of *pulCellOrdinal returned by the previous call and use the new value for ulStartingOrdinal.

The default member of a dimension (if one exists) is used in the absence of an explicit member specification. To use the default member for a given dimension, you set the corresponding array element to a null pointer. If rgpwszMember is a null pointer, default members are used for all the constituent dimensions.

If an error occurs, the contents of *pulCellOrdinal are undefined.

Note   The FindCell method calls IMDFind::FindTuple for each axis and uses the returned pulTupleOrdinal to calculate the cell coordinate.

1998-2001 Microsoft Corporation. All rights reserved.