MDAC 2.5 SDK - OLE DB Programmer's Reference
Appendix I: Row Position Object

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 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.