IRowPosition::GetRowPosition

  • Article

Returns the hRow of the current row position.

Syntax

HRESULT GetRowPosition (
   HCHAPTER *          phChapter,
   HROW *              phRow,
   DBPOSITIONFLAGS *   pdwPositionFlags);

Parameters

  • phChapter
    [out] A pointer to memory in which to return the chapter associated with the current row. If the rowset is not chaptered, phChapter is set to DB_NULL_HCHAPTER. If phChapter is a null pointer on input, no chapter value is returned.

  • phRow
    [out] A pointer to memory in which to return the hRow of the current row position; or DB_NULL_HROW if there is no current row position.

  • pdwPositionFlags
    [out] A pointer to memory in which to return additional information about the row position. If pdwPositionFlags is a null pointer on input, no additional information is returned for the row position. pdwPositionFlags can indicate one of the conditions described in the following table.

    Value

    Meaning

    DBPOSITION_OK

    hRow specifies the current row position.

    DBPOSITION_NOROW

    hRow is DB_NULL_HROW, and the current row position is undefined.

    DBPOSITION_BOF

    hRow is DB_NULL_HROW, and the row position is before the beginning of the rowset.

    DBPOSITION_EOF

    hRow is DB_NULL_HROW, and the row position is off the end of the rowset.

    Additional values for this flag may be defined in the future. If an unknown value is returned in pdwPositionFlags, the consumer should assume that there is no row if phRow is set to DB_NULL_HROW and that phRow points to a valid row if it is any other value.

Return Code

  • S_OK
    The method succeeded.

  • E_FAIL
    A provider-specific error occurred.

  • E_INVALIDARG
    phRow was a null pointer.

  • E_UNEXPECTED
    IRowPosition::Initialize has not been called; the row position object is in an uninitialized state.

    ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state.

    There is no current rowset.

Comments

Before returning, the row position object calls IRowset::AddRefRows to increment the hRow's reference count and if the chapter is non-null, calls IChapteredRowset::AddRefChapter to increment the phChapter's reference count.

Calling IRowPosition::GetRowPosition prior to the first IRowPosition::SetRowPosition returns a value of DB_NULL_HROW for phRow, and a pdwPositionFlags value of DBPOSITION_NOROW.