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

IRowPosition::GetRowPosition

Returns the hRow of the current row position.

HRESULT GetRowPosition (
   HCHAPTER *          phChapter,
   HROW *              phRow
   DBPOSITIONFLAGS *   pdwPositionFlags);

Parameters

phChapter

[out]
A pointer to memory in which to return the chapter associated with the current row. If the rowset is not chaptered, phChapter is set to DB_NULL_HCHAPTER. If phChapter is a null pointer on input, no chapter value is returned.

phRow

[out]
A pointer to memory in which to return the hRow of the current row position; or DB_NULL_HROW if there is no current row position.

pdwPositionFlags

[out]
A pointer to memory in which to return additional information about the row position. If pdwPositionFlags is a null pointer on input, no additional information is returned for the row position. pdwPositionFlags can indicate one of the conditions described in the following table.

Value	Meaning
DBPOSITION_OK	hRow specifies the current row position.
DBPOSITION_NOROW	hRow is DB_NULL_HROW, and the current row position is undefined.
DBPOSITION_BOF	hRow is DB_NULL_HROW, and the row position is before the beginning of the rowset.
DBPOSITION_EOF	hRow is DB_NULL_HROW, and the row position is off the end of the rowset.

Additional values for this flag may be defined in the future. If an unknown value is returned in pdwPositionFlags, the consumer should assume that there is no row if phRow is set to DB_NULL_HROW and that phRow points to a valid row if it is any other value.

Return Code

S_OK

The method succeeded.

E_FAIL

A provider-specific error occurred.

E_INVALIDARG

phRow was a null pointer.

E_UNEXPECTED

IRowPosition::Initialize has not been called; the row position object is in an uninitialized state.

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

There is no current rowset.

Comments

Before returning, the row position object calls IRowset::AddRefRows to increment the hRow's reference count and if the chapter is non-null, calls IChapteredRowset::AddRefChapter to increment the phChapter's reference count.

Calling IRowPosition::GetRowPosition prior to the first IRowPosition::SetRowPosition returns a value of DB_NULL_HROW for phRow, and a pdwPositionFlags value of DBPOSITION_NOROW.