CBulkRowset Class

Fetches and manipulates rows to work on data in bulk by retrieving multiple row handles with a single call.

Syntax

template <class TAccessor>
class CBulkRowset : public CRowset<TAccessor>

Parameters

TAccessor
An accessor class.

Requirements

Header: atldbcli.h

Members

Methods

Name	Description
AddRefRows	Increments the reference count.
CBulkRowset	Constructor.
MoveFirst	Retrieves the first row of data, performing a new bulk fetch if necessary.
MoveLast	Moves to the last row.
MoveNext	Retrieves the next row of data.
MovePrev	Moves to the previous row.
MoveToBookmark	Fetches the row marked by a bookmark or the row at a specified offset from that bookmark.
MoveToRatio	Fetches rows starting from a fractional position in the rowset.
ReleaseRows	Sets the current row (m_nCurrentRow) to zero and releases all rows.
SetRows	Sets the number of row handles to be retrieved by one call.

Example

The following example demonstrates use of the CBulkRowset class.

class CCustomerData
{
public:
   char m_szField1[50];

   BEGIN_COLUMN_MAP(CCustomerData)
     COLUMN_ENTRY(1, m_szField1)
   END_COLUMN_MAP()
};

void DoCBulkRowsetTest()
{
   CoInitialize(NULL);

   CCommand<CAccessor<CCustomerData>, CBulkRowset > cmd;
   CDataSource ds;

   // Open up data link dialogs to create a data source
   ds.Open();

   CSession session;
   session.Open(ds);
   // Could call SetRows() here if you want to fetch 
   // more than 10 HROWs at a time.
   cmd.Open(session, L"Select * from customer");
   cmd.MoveFirst();
   // Note that the CBulkRowset by default fetched 10 HROWs at a time 
   // so that the MoveNext call will not have to make the GetNextRows 
   // call to get the second HROW because it has already been fetched 
   //by the MoveFirst() call above.
   cmd.MoveNext();

   cmd.Close();
   session.Close();
   ds.Close();
}

CBulkRowset::AddRefRows

Calls IRowset::AddRefRows to increment the reference count for all rows currently retrieved from the bulk rowset.

Syntax

HRESULT AddRefRows() throw();

Return Value

A standard HRESULT.

CBulkRowset::CBulkRowset

Creates a new CBulkRowset object and sets the default row count to 10.

Syntax

CBulkRowset();

CBulkRowset::MoveFirst

Retrieves the first row of data.

Syntax

HRESULT MoveFirst() throw();

Return Value

A standard HRESULT.

CBulkRowset::MoveLast

Moves to the last row.

Syntax

HRESULT MoveLast() throw();

Return Value

A standard HRESULT.

CBulkRowset::MoveNext

Retrieves the next row of data.

Syntax

HRESULT MoveNext() throw();

Return Value

A standard HRESULT. When the end of the rowset has been reached, returns DB_S_ENDOFROWSET.

CBulkRowset::MovePrev

Moves to the previous row.

Syntax

HRESULT MovePrev() throw();

Return Value

A standard HRESULT.

CBulkRowset::MoveToBookmark

Fetches the row marked by a bookmark or the row at a specified offset (lSkip) from that bookmark.

Syntax

HRESULT MoveToBookmark(const CBookmarkBase& bookmark,
   DBCOUNTITEM lSkip = 0) throw();

Parameters

bookmark
[in] A bookmark marking the location from which you want to fetch data.

lSkip
[in] The number count of rows from the bookmark to the target row. If lSkip is zero, the first row fetched is the bookmarked row. If lSkip is 1, the first row fetched is the row after the bookmarked row. If lSkip is -1, the first row fetched is the row before the bookmarked row.

Return Value

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

CBulkRowset::MoveToRatio

Fetches rows starting from a fractional position in the rowset.

Syntax

HRESULT MoveToRatio(DBCOUNTITEM nNumerator,
   DBCOUNTITEM nDenominator)throw();

Parameters

nNumerator
[in] The numerator used to determine the fractional position from which to fetch data.

nDenominator
[in] The denominator used to determine the fractional position from which to fetch data.

Return Value

A standard HRESULT.

Remarks

MoveToRatio fetches the rows roughly according to the following formula:

(nNumerator * RowsetSize ) / nDenominator

Where RowsetSize is the size of the rowset, measured in rows. The accuracy of this formula depends on the specific provider. For details, see IRowsetScroll::GetRowsAtRatio in the OLE DB Programmer's Reference.

CBulkRowset::ReleaseRows

Calls IRowset::ReleaseRows to decrement the reference count for all rows currently retrieved from the bulk rowset.

Syntax

HRESULT ReleaseRows() throw();

Return Value

A standard HRESULT.

CBulkRowset::SetRows

Sets the number of row handles retrieved by each call.

Syntax

void SetRows(DBROWCOUNT nRows) throw();

Parameters

nRows
[in] The new size of the rowset (number of rows).

Remarks

If you call this function, it must be before the rowset is opened.

See also

OLE DB Consumer Templates
OLE DB Consumer Templates Reference