IRowPosition::SetRowPosition

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.