IRowPosition::SetRowPosition

Sets the current row position to a new hRow.

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

Parameters

hChapter

[in]
The chapter associated with the current row, or 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 the following:

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
SetRowPosition was called without first calling ClearRowPosition.

There is no current rowset.

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

Comments

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

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

The RowPostion object maintains a reference count on the both the hRow and the hChapter by respectively calling AddRefRows for the hRow and AddRefChapter for the hChapter when SetRowPosition is called.