| title | description | ms.date | f1_keywords | helpviewer_keywords | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
CRowset Class |
Learn more about: CRowset Class |
11/04/2016 |
|
|
Encapsulates an OLE DB rowset object and several related interfaces and provides manipulation methods for rowset data.
template <class TAccessor = CAccessorBase>
class CRowsetTAccessor
An accessor class. The default is CAccessorBase.
Header: atldbcli.h
| 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. |
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).
Calls IRowset::AddRefRows to increment (by one) the reference count associated with the current row handle.
HRESULT AddRefRows() throw();A standard HRESULT.
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.
Releases rows and the current IRowset interface.
void Close() throw();This method releases all rows currently in the rowset.
Compares two bookmarks using IRowsetLocate::Compare.
HRESULT Compare(const CBookmarkBase& bookmark1,
const CBookmarkBase& bookmark2,
DBCOMPARE* pComparison) const throw();Bookmark1
[in] The first bookmark to compare.
Bookmark2
[in] The second bookmark to compare.
pComparison
[out] A pointer to the result of the comparison.
A standard HRESULT.
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.
Creates a new CRowset object and (optionally) associates it with an IRowset interface supplied as a parameter.
CRowset();
CRowset(IRowset* pRowset);pRowset
[in] A pointer to an IRowset interface to be associated with this class.
Calls IRowsetChange::DeleteRows to delete the current row from the rowset.
HRESULT Delete() const throw();A standard HRESULT.
Finds the next matching row after the specified bookmark.
HRESULT FindNextRow(DBCOMPAREOP op,
BYTE* pData,
DBTYPE wType,
DBLENGTH nLength,
BYTE bPrecision,
BYTE bScale,
BOOL bSkipCurrent = TRUE,
CBookmarkBase* pBookmark = NULL) throw();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.
A standard HRESULT.
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.
Returns the approximate position of a row corresponding to a bookmark.
HRESULT GetApproximatePosition(const CBookmarkBase* pBookmark,
DBCOUNTITEM* pPosition,
DBCOUNTITEM* pcRows) throw();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.
A standard HRESULT.
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.
Retrieves data from the rowset's copy of the row.
HRESULT GetData() throw();
HRESULT GetData(int nAccessor) throw();nAccessor
[in] The (zero-offset) index number of the accessor to use for accessing the data.
A standard HRESULT.
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.
Retrieves data from the current row and places it into the specified buffer.
HRESULT GetDataHere(int nAccessor,
void* pBuffer) throw();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.
A standard HRESULT.
For an example of how to use this function, see the MultiRead sample.
Calls IRowsetUpdate::GetOriginalData to retrieve the data most recently fetched from or transmitted to the data source.
HRESULT GetOriginalData() throw();A standard HRESULT.
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.
Returns the status of all rows.
HRESULT GetRowStatus(DBPENDINGSTATUS* pStatus) const throw();pStatus
[out] A pointer to a location where GetRowStatus returns the status value. See DBPENDINGSTATUS in the OLE DB Programmer's Reference.
A standard HRESULT.
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.
Creates and initializes a new row using data from the accessor.
HRESULT Insert(int nAccessor = 0,
bool bGetHRow = false) throw();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.
A standard HRESULT.
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.
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:
[!code-cppNVC_OLEDB_Consumer#10]
Compares the specified row with the current row.
HRESULT IsSameRow(HROW hRow) const throw();hRow
[in] A handle to the row to compare to the current row.
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.
Moves the cursor to the initial position and retrieves the initial row.
HRESULT MoveFirst() throw();A standard HRESULT.
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.
Moves the cursor to the last row.
HRESULT MoveLast() throw();A standard HRESULT.
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.)
Moves the cursor to the next record.
HRESULT MoveNext() throw();
HRESULT MoveNext(LONG lSkip,
bool bForward= true) throw();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.
A standard HRESULT. When the end of the rowset has been reached, returns DB_S_ENDOFROWSET.
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_CANSCROLLBACKWARDSmust be VARIANT_TRUE if lSkip < 0 -
DBPROP_CANFETCHBACKWARDSmust be VARIANT_TRUE if bForward = false
Otherwise (if lSkip >= 0 and bForward = true), you do not need to set any additional properties.
Moves the cursor to the previous record.
HRESULT MovePrev() throw();A standard HRESULT.
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.
Fetches the row marked by a bookmark or the row at a specified offset (lSkip) from that bookmark.
HRESULT MoveToBookmark(const CBookmarkBase& bookmark,
LONG lSkip = 0) throw();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.
A standard HRESULT.
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.
Fetches rows starting from a fractional position in the rowset.
HRESULT MoveToRatio(DBCOUNTITEM nNumerator,
DBCOUNTITEM nDenominator,bool bForward = true) throw();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.
A standard HRESULT.
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.
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.
Calls IRowset::ReleaseRows to release the current row handle.
HRESULT ReleaseRows() throw();A standard HRESULT.
Sets data values in one or more columns of a row.
HRESULT SetData() const throw();
HRESULT SetData(int nAccessor) const throw();nAccessor
[in] The number of the accessor to use for accessing the data.
A standard HRESULT.
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.
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.
The setting operation might fail if one or more columns is not writable. Modify your cursor map to correct this.
Undoes any changes made to a row since the last fetch or Update.
HRESULT Undo(DBCOUNTITEM* pcRows = NULL,
HROW* phRow = NULL,
DBROWSTATUS* pStatus = NULL) throw();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.
A standard HRESULT.
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.
Transmits any pending changes made to the current row since the last fetch or Update call on it.
HRESULT Update(DBCOUNTITEM* pcRows = NULL,
HROW* phRow = NULL,
DBROWSTATUS* pStatus = NULL) throw();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.
A standard HRESULT.
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.
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.
Transmits any pending changes made to all rows since the last fetch or Update call on it.
HRESULT UpdateAll(DBCOUNTITEM* pcRows = NULL,
HROW** pphRow = NULL,
DBROWSTATUS** ppStatus = NULL) throw();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.
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.
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.
A standard HRESULT.
DBViewer Sample
MultiRead Sample
MultiRead Attributes Sample
OLE DB Consumer Templates
OLE DB Consumer Templates Reference