IRowPosition::SetRowPosition

  • Article

Sets the current row position to a new hRow.

Syntax

HRESULT SetRowPosition (
   HCHAPTER          hChapter,
   HROW              hRow,
   DBPOSITIONFLAGS   dwPositionFlags);

Parameters

  • hChapter
    [in] The chapter associated with the current row, or with DB_NULL_HCHAPTER if the rowset is not chaptered.

  • hRow
    [in] The new current row.

  • dwPositionFlags
    [in] A flag indicating additional information about the new row position. One of values described in the following table.

    Value

    Meaning

    DBPOSITION_OK

    hRow specifies the current row position.

    DBPOSITION_NOROW

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

    DBPOSITION_BOF

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

    DBPOSITION_EOF

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

Return Code

  • S_OK
    The method succeeded.

  • E_FAIL
    A provider-specific error occurred.

  • DB_E_BADCHAPTER
    hChapter was invalid.

  • DB_E_BADROWHANDLE
    hRow was invalid.

  • DB_E_CANCELED
    The operation was canceled by a client during notification. The current row is set to DB_NULL_ROW with a position flag indicating DBPOSITION_NOROW.

  • E_INVALIDARG
    hRow was set to DB_NULL_ROW, and dwPositionFlags indicated DBPOSITION_OK.

    dwPositionFlags indicated DBPOSITION_OK, but hRow was an invalid value.

    dwPositionFlags indicated DBPOSITION_NOROW, DBPOSITION_BOF, or DBPOSITION_EOF, and hRow was not set to DB_NULL_ROW.

  • E_UNEXPECTED
    IRowPosition::SetRowPosition was called without first calling IRowPosition::ClearRowPosition.

    There is no current rowset.

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

Comments

IRowPosition::ClearRowPosition must be called prior to the first and any subsequent IRowPosition::SetRowPosition calls.

IRowPosition::SetRowPosition fires the following notification phases with either DBREASON_ROWPOSITION_CHANGED or DBREASON_ROWPOSITION_CHAPTERCHANGED:

  • DBEVENTPHASE_SYNCHAFTER

  • DBEVENTPHASE_DIDEVENT or DBEVENTPHASE_FAILEDTODO

The row position object maintains a reference count on the both the hRow and the hChapter by respectively calling IRowset::AddRefRows for the hRow and IChapteredRowset::AddRefChapter for the hChapter when IRowPosition::SetRowPosition is called.