Share via

IMDFind::FindTuple

  • Article

Returns a pointer to a tuple ordinal based on array of members, a starting ordinal, and an axis identifier.

Syntax

HRESULT FindTuple(
   ULONG         ulAxisIdentifier,
   DBORDINAL     ulStartingOrdinal,
   DBCOUNTITEM   cMembers,
   LPCOLESTR    *rgpwszMember,
   ULONG        *pulTupleOrdinal);

Parameters

  • ulAxisIdentifier
    [in] The numeric identifier of an axis.

  • ulStartingOrdinal
    [in] The ordinal of the starting tuple on the axis. FindTuple begins with this ordinal and continues in the direction of increasing axis ordinals.

  • cMembers
    [in] The cardinality of the rgpwszMember array.

  • rgpwszMember
    [in] An array of members. For more information, see Comments.

  • pulTupleOrdinal
    [out] A pointer to a tuple ordinal. The tuple ordinal is used to calculate the cell ordinal.

Return Code

  • S_OK
    The method succeeded.

  • E_FAIL
    A provider-specific error occurred.

  • E_INVALIDARG
    pulTupleOrdinal was a null pointer.

    cMembers was less than 1.

  • MD_E_INVALIDAXIS
    ulAxisIdentifier did not identify a valid axis.

  • MD_E_BADTUPLE
    The ulStartingOrdinal was greater than the number of tuples on the specified axis.

    The array of members did not match any tuple on the axis occurring after ulStartingOrdinal (inclusive).

    The array of members contained multiple members from the same dimension.

    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

ulAxisIdentifier is the axis number. Axes are numbered starting from 0 (the column axis).

ulStartingOrdinal is the ordinal number of the tuple from which to begin the search. This tuple is included in the search. In many cases, the axis specification is such that the same tuple can occur more than once on an axis. Because FindTuple finds one tuple per call, ulStartingOrdinal can be used iteratively to find multiple occurrences of the same tuple. Successive calls to this method increment the *pulTupleOrdinal returned by the previous call and then use this as the value of ulStartingOrdinal for the next call.

rgpwszMember is an array of member names. Each name is null-terminated. Member names must be qualified to the degree needed to avoid any ambiguity. Using the MEMBER_UNIQUE_NAME column of the MEMBERS rowset guarantees this. The members are in the order of dimension nesting: Members of the outermost dimension come first, followed by members of inner dimensions.

pulTupleOrdinal is the ordinal number of the tuple on the axis, as returned in *plTupleOrdinal. Each tuple along an axis is numbered, starting from zero and increasing in the rightward direction. This ordinal number can be used to calculate cell ordinals, using the formula described in IMDDataset::GetCellData.

This method performs an exact match in that it compares for equality. Combined with the fact that members should be qualified enough to create an unambiguous reference, this means there is no possibility, by definition, of finding more than one cell.

A tuple ordinal for each tuple on an axis is available in the axis rowset.

You can indicate that you want the default member for a given dimension on an axis by setting the corresponding array element to a null pointer. If rgpwszMember is a null pointer, the default member is used for all dimensions on the axis. If a dimension does not have a default member, this case results in MD_E_BADTUPLE.

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