CRowset Class

Article
08/03/2021

Encapsulates an OLE DB rowset object and several related interfaces and provides manipulation methods for rowset data.

Syntax

template <class TAccessor = CAccessorBase>
class CRowset

Parameters

TAccessor
An accessor class. The default is CAccessorBase.

Requirements

Header: atldbcli.h

Members

Methods

Name	Description
AddRefRows	Increments the reference count associated with the current row.
Close	Releases rows and the current `IRowset` interface.
Compare	Compares two bookmarks using IRowsetLocate::Compare.
CRowset	Creates a new `CRowset` object and (optionally) associates it with an `IRowset` interface supplied as a parameter.
Delete	Deletes rows from the rowset using IRowsetChange:DeleteRows.
FindNextRow	Finds the next matching row after the specified bookmark.
GetApproximatePosition	Returns the approximate position of a row corresponding to a bookmark.
GetData	Retrieves data from the rowset's copy of the row.
GetDataHere	Retrieves data from the specified buffer.
GetOriginalData	Retrieves the data most recently fetched from or transmitted to the data source, ignoring pending changes.
GetRowStatus	Returns the status of all rows.
Insert	Creates and inserts a new row using IRowsetChange:InsertRow.
IsSameRow	Compares the specified row with the current row.
MoveFirst	Repositions the next-fetch location to the initial position.
MoveLast	Moves to the last record.
MoveNext	Fetches data from the next sequential row or a specified number of positions beyond the next row.
MovePrev	Moves to the previous record.
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	Calls IRowset::ReleaseRows to release the current row handle.
SetData	Sets data values in one or more columns of a row using IRowsetChange:SetData.
Undo	Undoes any changes made to a row since the last fetch or Update.
Update	Transmits any pending changes made to the current row since the last fetch or update.
UpdateAll	Transmits any pending changes made to all rows since the last fetch or update.

Remarks

In OLE DB, a rowset is the object through which a program sets and retrieves data.

This class is not meant to be instantiated but rather passed as a template parameter to CTable or CCommand (CRowset is the default).

CRowset::AddRefRows

Calls IRowset::AddRefRows to increment (by one) the reference count associated with the current row handle.

Syntax

HRESULT AddRefRows() throw();

Return Value

A standard HRESULT.

Remarks

This method increments the reference count for the current row handle. Call ReleaseRows to decrement the count. Rows returned by the move methods have a reference count of one.

CRowset::Close

Releases rows and the current IRowset interface.

Syntax

void Close() throw();

Remarks

This method releases all rows currently in the rowset.

CRowset::Compare

Compares two bookmarks using IRowsetLocate::Compare.

Syntax

HRESULT Compare(const CBookmarkBase& bookmark1,
   const CBookmarkBase& bookmark2,
   DBCOMPARE* pComparison) const throw();

Parameters

Bookmark1
[in] The first bookmark to compare.

Bookmark2
[in] The second bookmark to compare.

pComparison
[out] A pointer to the result of the comparison.

Return Value

A standard HRESULT.

Remarks

This method requires the optional interface IRowsetLocate, which might not be supported on all providers; if this is the case, the method returns E_NOINTERFACE. You must also set DBPROP_IRowsetLocate to VARIANT_TRUE before calling Open on the table or command containing the rowset.

For information about using bookmarks in consumers, see Using Bookmarks.

CRowset::CRowset

Creates a new CRowset object and (optionally) associates it with an IRowset interface supplied as a parameter.

Syntax

CRowset();

CRowset(IRowset* pRowset);

Parameters

pRowset
[in] A pointer to an IRowset interface to be associated with this class.

CRowset::Delete

Calls IRowsetChange::DeleteRows to delete the current row from the rowset.

Syntax

HRESULT Delete() const throw();

Return Value

A standard HRESULT.

CRowset::FindNextRow

Finds the next matching row after the specified bookmark.

Syntax

HRESULT FindNextRow(DBCOMPAREOP op,
   BYTE* pData,
   DBTYPE wType,
   DBLENGTH nLength,
   BYTE bPrecision,
   BYTE bScale,
   BOOL bSkipCurrent = TRUE,
   CBookmarkBase* pBookmark = NULL) throw();

Parameters

op
[in] The operation to use in comparing row values. For values, see IRowsetFind::FindNextRow.

pData
[in] A pointer to the value to be matched.

wType
[in] Indicates the data type of the value part of the buffer. For information about type indicators, see Data Types in the OLE DB Programmer's Reference in the Windows SDK.

nLength
[in] The length, in bytes, of the consumer data structure allocated for the data value. For details, see the description of cbMaxLen in DBBINDING Structures in the OLE DB Programmer's Reference.

bPrecision
[in] The maximum precision used when getting data. Used only if wType is DBTYPE_NUMERIC. For more information, see Conversions involving DBTYPE_NUMERIC or DBTYPE_DECIMAL in the OLE DB Programmer's Reference.

bScale
[in] The scale used when getting data. Used only if wType is DBTYPE_NUMERIC or DBTYPE_DECIMAL. For more information, see Conversions involving DBTYPE_NUMERIC or DBTYPE_DECIMAL in the OLE DB Programmer's Reference.

bSkipCurrent
[in] The number of rows from the bookmark at which to start a search.

pBookmark
[in] The bookmark for position at which to start a search.

Return Value

A standard HRESULT.

Remarks

This method requires the optional interface IRowsetFind, which might not be supported on all providers; if this is the case, the method returns E_NOINTERFACE. You must also set DBPROP_IRowsetFind to VARIANT_TRUE before calling Open on the table or command containing the rowset.

For information about using bookmarks in consumers, see Using Bookmarks.

CRowset::GetApproximatePosition

Returns the approximate position of a row corresponding to a bookmark.

Syntax

HRESULT GetApproximatePosition(const CBookmarkBase* pBookmark,
   DBCOUNTITEM* pPosition,
   DBCOUNTITEM* pcRows) throw();

Parameters

pBookmark
[in] A pointer to a bookmark that identifies the row whose position is to be found. NULL if only the row count is required.

pPosition
[out] A pointer to the location where GetApproximatePosition returns the position of the row. NULL if the position is not required.

pcRows
[out] A pointer to the location where GetApproximatePosition returns the total number of rows. NULL if the row count is not required.

Return Value

A standard HRESULT.

Remarks

This method requires the optional interface IRowsetScroll, which might not be supported on all providers; if this is the case, the method returns E_NOINTERFACE. You must also set DBPROP_IRowsetScroll to VARIANT_TRUE before calling Open on the table or command containing the rowset.

For information about using bookmarks in consumers, see Using Bookmarks.

CRowset::GetData

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

Syntax

HRESULT GetData() throw();

HRESULT GetData(int nAccessor) throw();

Parameters

nAccessor
[in] The (zero-offset) index number of the accessor to use for accessing the data.

Return Value

A standard HRESULT.

Remarks

If you specify an accessor that is not an autoaccessor in BEGIN_ACCESSOR, use this method to explicitly get the data by passing the accessor number.

CRowset::GetDataHere

Retrieves data from the current row and places it into the specified buffer.

Syntax

HRESULT GetDataHere(int nAccessor,
   void* pBuffer) throw();

Parameters

nAccessor
[in] The index number of the accessor to use for accessing the data.

pBuffer
[out] A buffer into which to place the data for the current record.

Return Value

A standard HRESULT.

Remarks

For an example of how to use this function, see the MultiRead sample.

CRowset::GetOriginalData

Calls IRowsetUpdate::GetOriginalData to retrieve the data most recently fetched from or transmitted to the data source.

Syntax

HRESULT GetOriginalData() throw();

Return Value

A standard HRESULT.

Remarks

This method retrieves the data most recently fetched from or transmitted to the data source; it does not retrieve values based on pending changes.

This method requires the optional interface IRowsetUpdate, which might not be supported on all providers; if this is the case, the method returns E_NOINTERFACE. You must also set DBPROP_IRowsetUpdate to VARIANT_TRUE before calling Open on the table or command containing the rowset.

CRowset::GetRowStatus

Returns the status of all rows.

Syntax

HRESULT GetRowStatus(DBPENDINGSTATUS* pStatus) const throw();

Parameters

pStatus
[out] A pointer to a location where GetRowStatus returns the status value. See DBPENDINGSTATUS in the OLE DB Programmer's Reference.

Return Value

A standard HRESULT.

Remarks

CRowset::Insert

Creates and initializes a new row using data from the accessor.

Syntax

HRESULT Insert(int nAccessor = 0,
   bool bGetHRow = false) throw();

Parameters

nAccessor
[in] The number of the accessor to use for inserting the data.

bGetHRow
[in] Indicates whether the handle for the inserted row is retrieved.

Return Value

A standard HRESULT.

Remarks

This method requires the optional interface IRowsetChange, which might not be supported on all providers; if this is the case, the method returns E_NOINTERFACE. You must also set DBPROP_IRowsetChange to VARIANT_TRUE before calling Open on the table or command containing the rowset.

Insert might fail if one or more columns is not writable. Modify your cursor map to correct this.

Example

The following example shows how to access a data source through a rowset and then insert a string using a table in that rowset.

First, create a table class by inserting a New ATL Object into your project. For example, right-click the project in the Workspace pane and select New ATL Object. From the Data Access category, select Consumer. Create a consumer object of type Table. (Selecting Table creates a rowset directly from the table; selecting Command creates a rowset through a SQL command.) Select a data source, specifying a table through which to access that data source. If you call your consumer object CCustomerTable, you would then implement your insertion code as follows:

// Access the rowset using the wizard-generated class, CCustomerTable
CCustomerTable rs;           // Your CTable-derived class

// Insert a customer
// Note that for fixed-length fields such as billing ID it isn't necessary
// to set the length
rs.m_BillingID = 5002;
rs.m_dwBillingIDStatus = DBSTATUS_S_OK;

_tcscpy_s(rs.m_ContactFirstName, sizeof(rs.m_ContactFirstName) / sizeof(TCHAR), 
   _T("Malcolm"));
rs.m_dwContactFirstNameLength = 7;
rs.m_dwContactFirstNameStatus = DBSTATUS_S_OK;

_tcscpy_s(rs.m_L_Name, sizeof(rs.m_L_Name) / sizeof(TCHAR), _T("Reynolds"));
rs.m_dwL_NameLength = 8;
rs.m_dwContactFirstNameStatus = DBSTATUS_S_OK;

rs.m_CustomerID = 2005;
rs.m_dwCustomerIDStatus = DBSTATUS_S_OK;

_tcscpy_s(rs.m_PostalCode, sizeof(rs.m_PostalCode) / sizeof(TCHAR), 
   _T("34213-4444"));
rs.m_dwPostalCodeLength = 10;
rs.m_dwPostalCodeStatus = DBSTATUS_S_OK;

HRESULT hr = rs.Insert();
if (FAILED(hr))
{
   ATLTRACE(_T("Insert failed: 0x%X\n"), hr);
}

CRowset::IsSameRow

Compares the specified row with the current row.

Syntax

HRESULT IsSameRow(HROW hRow) const throw();

Parameters

hRow
[in] A handle to the row to compare to the current row.

Return Value

A standard HRESULT. S_OK indicates the rows are the same. For other values, see IRowsetIndentity::IsSameRow in the OLE DB Programmer's Reference in the Windows SDK.

CRowset::MoveFirst

Moves the cursor to the initial position and retrieves the initial row.

Syntax

HRESULT MoveFirst() throw();

Return Value

A standard HRESULT.

Remarks

Calls IRowset::RestartPosition to reposition the next-fetch location to the initial position (the position that was the next-fetch location when the rowset was created) and retrieves the initial row.

CRowset::MoveLast

Moves the cursor to the last row.

Syntax

HRESULT MoveLast() throw();

Return Value

A standard HRESULT.

Remarks

Calls IRowset::RestartPosition to reposition the next-fetch location to the last position and retrieves the last row.

This method requires that you set DBPROP_CANSCROLLBACKWARDS to VARIANT_TRUE before calling Open on the table or command containing the rowset. (For better performance, you might also set DBPROP_QUICKRESTART to VARIANT_TRUE.)

CRowset::MoveNext

Moves the cursor to the next record.

Syntax

HRESULT MoveNext() throw();

HRESULT MoveNext(LONG lSkip,
   bool bForward= true) throw();

Parameters

lSkip
[in] The number of rows to skip before fetching.

bForward
[in] Pass true to move forward to the next record, false to move backward.

Return Value

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

Remarks

Fetches the next sequential row from the CRowset object, remembering the previous position. Optionally, you can choose to skip ahead lSkip rows or move backward.

This method requires that you set the following properties before calling Open on the table or command containing the rowset:

DBPROP_CANSCROLLBACKWARDS must be VARIANT_TRUE if lSkip < 0
DBPROP_CANFETCHBACKWARDS must be VARIANT_TRUE if bForward = false

Otherwise (if lSkip >= 0 and bForward = true), you do not need to set any additional properties.

CRowset::MovePrev

Moves the cursor to the previous record.

Syntax

HRESULT MovePrev() throw();

Return Value

A standard HRESULT.

Remarks

This method requires that you set either DBPROP_CANFETCHBACKWARDS or DBPROP_CANSCROLLBACKWARDS to VARIANT_TRUE before calling Open on the table or command containing the rowset.

CRowset::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,
   LONG 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

A standard HRESULT.

Remarks

This method requires the optional interface IRowsetLocate, which might not be supported on all providers; if this is the case, the method returns E_NOINTERFACE. You must also set DBPROP_IRowsetLocate to VARIANT_TRUE and set DBPROP_CANFETCHBACKWARDS to VARIANT_TRUE before calling Open on the table or command containing the rowset.

For information about using bookmarks in consumers, see Using Bookmarks.

CRowset::MoveToRatio

Fetches rows starting from a fractional position in the rowset.

Syntax

HRESULT MoveToRatio(DBCOUNTITEM nNumerator,
   DBCOUNTITEM nDenominator,bool bForward = true) throw();

Parameters

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

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

bForward
[in] Indicates whether to move forward or backward. The default is forward.

Return Value

A standard HRESULT.

Remarks

MoveToRatio fetches rows according roughly 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.

CRowset::ReleaseRows

Calls IRowset::ReleaseRows to release the current row handle.

Syntax

HRESULT ReleaseRows() throw();

Return Value

A standard HRESULT.

CRowset::SetData

Sets data values in one or more columns of a row.

Syntax

HRESULT SetData() const throw();

HRESULT SetData(int nAccessor) const throw();

Parameters

nAccessor
[in] The number of the accessor to use for accessing the data.

Return Value

A standard HRESULT.

Remarks

For the SetData form that accepts no arguments, all accessors are used for updating. You typically call SetData to set data values in columns in a row, then call Update to transmit those changes.

The setting operation might fail if one or more columns is not writable. Modify your cursor map to correct this.

CRowset::Undo

Undoes any changes made to a row since the last fetch or Update.

Syntax

HRESULT Undo(DBCOUNTITEM* pcRows = NULL,
   HROW* phRow = NULL,
   DBROWSTATUS* pStatus = NULL) throw();

Parameters

pcRows
[out] A pointer to the location where Undo returns the number of rows it attempted to undo if required.

phRow
[out] A pointer to the location where Undo returns an array of handles to all rows it attempted to undo if required.

pStatus
[out] A pointer to the location where Undo returns the row status value. No status is returned if pStatus is null.

Return Value

A standard HRESULT.

Remarks

CRowset::Update

Transmits any pending changes made to the current row since the last fetch or Update call on it.

Syntax

HRESULT Update(DBCOUNTITEM* pcRows = NULL,
   HROW* phRow = NULL,
   DBROWSTATUS* pStatus = NULL) throw();

Parameters

pcRows
[out] A pointer to the location where Update returns the number of rows it attempted to update, if required.

phRow
[out] A pointer to the location where Update returns the handle of the row it attempted to update. No handle is returned if phRow is null.

pStatus
[out] A pointer to the location where Update returns the row status value. No status is returned if pStatus is null.

Return Value

A standard HRESULT.

Remarks

Transmits any pending changes made to the current row since that row was last fetched or updated (using Update or UpdateAll). You typically call SetData to set data values in columns in a row, and then call Update to transmit those changes.

CRowset::UpdateAll

Transmits any pending changes made to all rows since the last fetch or Update call on it.

Syntax

HRESULT UpdateAll(DBCOUNTITEM* pcRows = NULL,
   HROW** pphRow = NULL,
   DBROWSTATUS** ppStatus = NULL) throw();

Parameters

pcRows
[out] A pointer to the location where UpdateAll returns the number of rows it attempted to update, if required.

pphRow
[out] A pointer to memory in which UpdateAll returns the handle of the row it attempted to update. No handle is returned if pphRow is null.

ppStatus
[out] A pointer to the location where Update returns the row status value. No status is returned if ppStatus is null.

Remarks

Transmits any pending changes made to all rows since those rows were last fetched or updated using Update or UpdateAll. UpdateAll will update every row that has been modified, regardless of whether you still have the handle for them (see pphRow) or not.

For example, if you used Insert to insert five rows in a rowset, you could either call Update five times or call UpdateAll once to update them all.

Return Value

A standard HRESULT.