IRowsetImpl Class

Provides an implementation of the IRowset interface.

Syntax

template <
   class T,
   class RowsetInterface,
   class RowClass = CSimpleRow,
   class MapClass = CAtlMap <
      RowClass::KeyType,
      RowClass*>>
class ATL_NO_VTABLE IRowsetImpl : public RowsetInterface

Parameters

T
Your class, derived from IRowsetImpl.

RowsetInterface
A class derived from IRowsetImpl.

RowClass
Storage unit for the HROW.

MapClass
Storage unit for all row handles held by the provider.

Requirements

Header: atldb.h

Members

Methods

Name	Description
AddRefRows	Adds a reference count to an existing row handle.
CreateRow	Called by GetNextRows to allocate a new HROW. Not called directly by user.
GetData	Retrieves data from the rowset's copy of the row.
GetDBStatus	Returns the status for the specified field.
GetNextRows	Fetches rows sequentially, remembering the previous position.
IRowsetImpl	The constructor. Not called directly by user.
RefRows	Called by AddRefRows and ReleaseRows. Not called directly by user.
ReleaseRows	Releases rows.
RestartPosition	Repositions the next fetch position to its initial position; that is, its position when the rowset was first created.
SetDBStatus	Sets the status flags for the specified field.

Data Members

Name	Description
m_bCanFetchBack	Indicates whether a provider supports backward fetching.
m_bCanScrollBack	Indicates whether a provider can have its cursor scroll backwards.
m_bReset	Indicates whether a provider has reset its cursor position. This has special meaning when scrolling backwards or fetching backwards in GetNextRows.
m_iRowset	An index to the rowset, representing the cursor.
m_rgRowHandles	A list of row handles.

Remarks

IRowset is the base rowset interface.

IRowsetImpl::AddRefRows

Adds a reference count to an existing row handle.

Syntax

STDMETHOD(AddRefRows )(DBCOUNTITEM cRows,
   const HROW rghRows[],
   DBREFCOUNT rgRefCounts[],
   DBROWSTATUS rgRowStatus[]);

Parameters

See IRowset::AddRefRows in the OLE DB Programmer's Reference.

IRowsetImpl::CreateRow

A helper method called by GetNextRows to allocate a new HROW.

Syntax

HRESULT CreateRow(DBROWOFFSET lRowsOffset,
   DBCOUNTITEM& cRowsObtained,
   HROW* rgRows);

Parameters

lRowsOffset
Cursor position of the row being created.

cRowsObtained
A reference passed back to the user indicating the number of rows created.

rgRows
An array of HROWs returned to the caller with the newly created row handles.

Remarks

If the row exists, this method calls AddRefRows and returns. Otherwise, it allocates a new instance of the RowClass template variable and adds it to m_rgRowHandles.

IRowsetImpl::GetData

Retrieves data from the rowset's copy of the row.

Syntax

STDMETHOD(GetData )(HROW hRow,
   HACCESSOR hAccessor,
   void* pDstData);

Parameters

See IRowset::GetData in the OLE DB Programmer's Reference.

Some parameters correspond to OLE DB Programmer's Reference parameters of different names, which are described in IRowset::GetData:

OLE DB Template parameters	OLE DB Programmer's Reference parameters
pDstData	pData

Remarks

Also handles data conversion using the OLE DB data conversion DLL.

IRowsetImpl::GetDBStatus

Returns the DBSTATUS status flags for the specified field.

Syntax

virtual DBSTATUS GetDBStatus(RowClass* currentRow,
   ATLCOLUMNINFO* columnNames);

Parameters

currentRow
[in] The current row.

columnNames
[in] The column for which status is being requested.

Return Value

The DBSTATUS flags for the column.

IRowsetImpl::GetNextRows

Fetches rows sequentially, remembering the previous position.

Syntax

STDMETHOD(GetNextRows )(HCHAPTER hReserved,
   DBROWOFFSET lRowsOffset,
   DBROWCOUNT cRows,
   DBCOUNTITEM* pcRowsObtained,
   HROW** prghRows);

Parameters

See IRowset::GetNextRows in the OLE DB Programmer's Reference.

IRowsetImpl::IRowsetImpl

The constructor.

Syntax

IRowsetImpl();

Remarks

You usually do not need to call this method directly.

IRowsetImpl::RefRows

Called by AddRefRows and ReleaseRows to either increment or release a reference count to an existing row handle.

Syntax

HRESULT RefRows(DBCOUNTITEM cRows,
   const HROWrghRows[],
   DBREFCOUNT rgRefCounts[],
   DBROWSTATUS rgRowStatus[],
   BOOL bAdd);

Parameters

See IRowset::AddRefRows in the OLE DB Programmer's Reference.

Return Value

A standard HRESULT value.

IRowsetImpl::ReleaseRows

Releases rows.

Syntax

STDMETHOD(ReleaseRows )(DBCOUNTITEM cRows,
   const HROW rghRows[],
   DBROWOPTIONS rgRowOptions[],
   DBREFCOUNT rgRefCounts[],
   DBROWSTATUS rgRowStatus[]);

Parameters

See IRowset::ReleaseRows in the OLE DB Programmer's Reference.

IRowsetImpl::RestartPosition

Repositions the next fetch position to its initial position; that is, its position when the rowset was first created.

Syntax

STDMETHOD(RestartPosition )(HCHAPTER /* hReserved */);

Parameters

See IRowset::RestartPosition in the OLE DB Programmer's Reference.

Remarks

The rowset position is undefined until GetNextRow is called. You can move backwards in a rowet by calling RestartPosition and then fetching or scrolling backwards.

IRowsetImpl::SetDBStatus

Sets the DBSTATUS status flags for the specified field.

Syntax

virtual HRESULT SetDBStatus(DBSTATUS* statusFlags,
   RowClass* currentRow,
   ATLCOLUMNINFO* columnInfo);

Parameters

statusFlags
The DBSTATUS flags to set for the column.

currentRow
The current row.

columnInfo
The column for which status is being set.

Return Value

A standard HRESULT value.

Remarks

The provider overrides this function to provide special processing for DBSTATUS_S_ISNULL and DBSTATUS_S_DEFAULT.

IRowsetImpl::m_bCanFetchBack

Indicates whether a provider supports backward fetching.

Syntax

unsigned m_bCanFetchBack:1;

Remarks

Linked to the DBPROP_CANFETCHBACKWARDS property in the DBPROPSET_ROWSET group. The provider must support DBPROP_CANFETCHBACKWARDS for m_bCanFetchBackwards to be true.

IRowsetImpl::m_bCanScrollBack

Indicates whether a provider can have its cursor scroll backwards.

Syntax

unsigned  m_bCanScrollBack:1;

Remarks

Linked to the DBPROP_CANSCROLLBACKWARDS property in the DBPROPSET_ROWSET group. The provider must support DBPROP_CANSCROLLBACKWARDS for m_bCanFetchBackwards to be true.

IRowsetImpl::m_bReset

A bit flag used to determine if the cursor position is defined on the rowset.

Syntax

unsigned m_bReset:1;

Remarks

If the consumer calls GetNextRows with a negative lOffset or cRows and m_bReset is true, GetNextRows moves to the end of the rowset. If m_bReset is false, the consumer receives an error code, in conformance with the OLE DB specification. The m_bReset flag gets set to true when the rowset is first created and when the consumer calls IRowsetImpl::RestartPosition. It gets set to false when you call GetNextRows.

IRowsetImpl::m_iRowset

An index to the rowset, representing the cursor.

Syntax

DBROWOFFSET m_iRowset;

IRowsetImpl::m_rgRowHandles

A map of row handles currently contained by the provider in response to GetNextRows.

Syntax

MapClass m_rgRowHandles;

Remarks

Row handles are removed by calling ReleaseRows. See the IRowsetImpl overview for the definition of MapClass.

See also

OLE DB Provider Templates
OLE DB Provider Template Architecture
CSimpleRow Class