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.