CRowset 类
封装 OLE DB 行集对象和多个相关接口，并为行集数据提供操作方法。
语法
template <class TAccessor = CAccessorBase>
class CRowset
参数
TAccessor
一个访问器类。 默认值为 CAccessorBase。
要求
标头: atldbcli.h
成员
方法
| 名称 | 描述 |
|---|---|
| AddRefRows | 递增与当前行关联的引用计数。 |
| Close | 释放行和当前的 IRowset 接口。 |
| 比较 | 使用 IRowsetLocate::Compare 比较两个书签。 |
| CRowset | 创建新的 CRowset 对象并（可选）将其与作为参数提供的 IRowset 接口关联。 |
| 删除 | 使用 IRowsetChange:DeleteRows 从行集中删除行。 |
| FindNextRow | 查找指定书签后面的下一个匹配行。 |
| GetApproximatePosition | 返回对应于书签的行的大致位置。 |
| GetData | 从行集的行副本中检索数据。 |
| GetDataHere | 从指定缓冲区检索数据。 |
| GetOriginalData | 检索最近从数据源提取或传输到数据源的数据，忽略挂起的更改。 |
| GetRowStatus | 返回所有行的状态。 |
| 插入 | 使用 IRowsetChange:InsertRow 创建并插入新行。 |
| IsSameRow | 将指定行与当前行进行比较。 |
| MoveFirst | 将下一个提取位置重新定位到初始位置。 |
| MoveFirst | 移动到最后一条记录。 |
| MoveNext | 从下一个顺序行或下一行之后的指定数目的位置提取数据。 |
| MovePrev | 移动到上一条记录。 |
| MoveToBookmark | 提取用书签标记的行或距离该书签指定偏移量的行。 |
| MoveToRatio | 从行集中的分数位置开始提取行。 |
| ReleaseRows | 调用 IRowset::ReleaseRows 以释放当前行句柄。 |
| SetData | 使用 IRowsetChange:SetData 设置行中一列或多列的数据值。 |
| 撤消 | 撤消自上次提取或更新以来对行进行的任何更改。 |
| 更新 | 传输自上次提取或更新以来对当前行进行的任何挂起的更改。 |
| UpdateAll | 传输自上次提取或更新以来对所有行进行的任何挂起的更改。 |
备注
在 OLE DB 中，行集是程序设置和检索数据的对象。
此类不是要实例化，而是作为模板参数传递给 CTable 或 CCommand（CRowset 为默认值）。
CRowset::AddRefRows
调用 IRowset::AddRefRows 以递增（以 1 为增量）与当前行句柄关联的引用计数。
语法
HRESULT AddRefRows() throw();
返回值
标准 HRESULT。
注解
此方法递增当前行句柄的引用计数。 调用 ReleaseRows 以递减计数。 移动方法返回的行的引用计数为 1。
CRowset::Close
释放行和当前的 IRowset 接口。
语法
void Close() throw();
备注
此方法释放行集合中当前包含的所有行。
CRowset::Compare
使用 IRowsetLocate::Compare 比较两个书签。
语法
HRESULT Compare(const CBookmarkBase& bookmark1,
const CBookmarkBase& bookmark2,
DBCOMPARE* pComparison) const throw();
参数
书签 1
[in] 要比较的第一个书签。
书签 2
[in] 要比较的第二个书签。
pComparison
[out] 指向比较结果的指针。
返回值
标准 HRESULT。
备注
此方法需要可选接口 IRowsetLocate，该接口可能并非在所有提供程序上都受支持；如果是这样，该方法将返回 E_NOINTERFACE。 在包含行集的表或命令上调用 Open 之前，还必须将 DBPROP_IRowsetLocate 设置为 VARIANT_TRUE。
有关在使用者中使用书签的信息，请参阅使用书签。
CRowset::CRowset
创建新的 CRowset 对象并（可选）将其与作为参数提供的 IRowset 接口关联。
语法
CRowset();
CRowset(IRowset* pRowset);
参数
pRowset
[in] 指向将与此类关联的 IRowset 接口的指针。
CRowset::Delete
调用 IRowsetChange::DeleteRows 以从行集中删除当前行。
语法
HRESULT Delete() const throw();
返回值
标准 HRESULT。
CRowset::FindNextRow
查找指定书签后面的下一个匹配行。
语法
HRESULT FindNextRow(DBCOMPAREOP op,
BYTE* pData,
DBTYPE wType,
DBLENGTH nLength,
BYTE bPrecision,
BYTE bScale,
BOOL bSkipCurrent = TRUE,
CBookmarkBase* pBookmark = NULL) throw();
参数
op
[in] 用于比较行值的操作。 有关值，请参阅 IRowsetFind::FindNextRow。
pData
[in] 指向要匹配的值的指针。
wType
[in] 指示缓冲区的值部分的数据类型。 有关类型指示器的信息，请参阅 Windows SDK 中“OLE DB 程序员参考”中的数据类型。
nLength
[in] 为数据值分配的使用者数据结构的长度（以字节为单位）。 有关详细信息，请参阅“OLE DB 程序员参考”中 DBBINDING 结构中的 cbMaxLen 的说明。
bPrecision
[in] 获取数据时使用的最大精度。 仅当 wType 为 DBTYPE_NUMERIC 时使用。 有关详细信息，请参阅“OLE DB 程序员参考”中的涉及 DBTYPE_NUMERIC 或 DBTYPE_DECIMAL 的转换。
bScale
[in] 获取数据时使用的比例。 仅当 wType 为 DBTYPE_NUMERIC 或 DBTYPE_DECIMAL 时使用。 有关详细信息，请参阅“OLE DB 程序员参考”中的涉及 DBTYPE_NUMERIC 或 DBTYPE_DECIMAL 的转换。
bSkipCurrent
[in] 要在其中启动搜索的书签中的行数。
pBookmark
[in] 用于开始搜索的位置的书签。
返回值
标准 HRESULT。
注解
此方法需要可选接口 IRowsetFind，该接口可能并非在所有提供程序上都受支持；如果是这样，该方法将返回 E_NOINTERFACE。 在包含行集的表或命令上调用 Open 之前，还必须将 DBPROP_IRowsetFind 设置为 VARIANT_TRUE。
有关在使用者中使用书签的信息，请参阅使用书签。
CRowset::GetApproximatePosition
返回对应于书签的行的大致位置。
语法
HRESULT GetApproximatePosition(const CBookmarkBase* pBookmark,
DBCOUNTITEM* pPosition,
DBCOUNTITEM* pcRows) throw();
参数
pBookmark
[in] 指向用于标识要找到其位置的行的书签的指针。 如果只需要行计数，则为 NULL。
pPosition
[out] 指向 GetApproximatePosition 返回行位置的位置的指针。 如果不需要位置，则为 NULL。
pcRows
[out] 指向 GetApproximatePosition 返回总行数的位置的指针。 如果不需要行计数，则为 NULL。
返回值
标准 HRESULT。
备注
此方法需要可选接口 IRowsetScroll，该接口可能并非在所有提供程序上都受支持；如果是这样，该方法将返回 E_NOINTERFACE。 在包含行集的表或命令上调用 Open 之前，还必须将 DBPROP_IRowsetScroll 设置为 VARIANT_TRUE。
有关在使用者中使用书签的信息，请参阅使用书签。
CRowset::GetData
从行集的行副本中检索数据。
语法
HRESULT GetData() throw();
HRESULT GetData(int nAccessor) throw();
参数
nAccessor
[in] 用于访问数据的访问器的（零偏移量）索引号。
返回值
标准 HRESULT。
备注
如果在 BEGIN_ACCESSOR 中指定不是自动访问器的访问器，请使用此方法通过传递访问器编号显式获取数据。
CRowset::GetDataHere
从当前行中检索数据，并将其置于指定的缓冲区中。
语法
HRESULT GetDataHere(int nAccessor,
void* pBuffer) throw();
参数
nAccessor
[in] 用于访问数据的访问器的索引号。
pBuffer
[out] 要将当前记录的数据放入其中的缓冲区。
返回值
标准 HRESULT。
备注
有关如何使用此函数的示例，请参阅 MultiRead 示例文档。
CRowset::GetOriginalData
调用 IRowsetUpdate::GetOriginalData 以检索最近从数据源提取或传输到数据源的数据。
语法
HRESULT GetOriginalData() throw();
返回值
标准 HRESULT。
备注
此方法将检索最近从数据源提取或传输到数据源的数据；它不会根据挂起的更改检索值。
此方法需要可选接口 IRowsetUpdate，该接口可能并非在所有提供程序上都受支持；如果是这样，该方法将返回 E_NOINTERFACE。 在包含行集的表或命令上调用 Open 之前，还必须将 DBPROP_IRowsetUpdate 设置为 VARIANT_TRUE。
CRowset::GetRowStatus
返回所有行的状态。
语法
HRESULT GetRowStatus(DBPENDINGSTATUS* pStatus) const throw();
参数
pStatus
[out] 指向返回 GetRowStatus 状态值的位置的指针。 请参阅“OLE DB 程序员参考”中的 DBPENDINGSTATUS。
返回值
标准 HRESULT。
注解
此方法需要可选接口 IRowsetUpdate，该接口可能并非在所有提供程序上都受支持；如果是这样，该方法将返回 E_NOINTERFACE。 在包含行集的表或命令上调用 Open 之前，还必须将 DBPROP_IRowsetUpdate 设置为 VARIANT_TRUE。
CRowset::Insert
使用访问器中的数据创建并初始化新行。
语法
HRESULT Insert(int nAccessor = 0,
bool bGetHRow = false) throw();
参数
nAccessor
[in] 用于插入数据的访问器的编号。
bGetHRow
[in] 指示是否检索所插入行的句柄。
返回值
标准 HRESULT。
备注
此方法需要可选接口 IRowsetChange，该接口可能并非在所有提供程序上都受支持；如果是这样，该方法将返回 E_NOINTERFACE。 在包含行集的表或命令上调用 Open 之前，还必须将 DBPROP_IRowsetChange 设置为 VARIANT_TRUE。
如果一列或多列不可写，则插入可能失败。 修改光标映射以更正此问题。
示例
以下示例演示了如何通过行集访问数据源，然后使用该行集中的表插入字符串。
首先，通过将新的 ATL 对象插入项目来创建表类。 例如，右键单击“工作区”窗格中的项目，然后选择“新建 ATL 对象”。 从“数据访问”类别中，选择“使用者”。 创建类型为“表”的使用者对象。 （选择“表”会直接从表中创建行集；选择“命令”会通过 SQL 命令创建行集。）选择数据源并指定要用于访问该数据源的表。 如果调用使用者对象 CCustomerTable，则将实现插入代码，如下所示：
// 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
将指定行与当前行进行比较。
语法
HRESULT IsSameRow(HROW hRow) const throw();
参数
hRow
[in] 要与当前行进行比较的行的句柄。
返回值
标准 HRESULT。 S_OK 指示行是相同的。 有关其他值，请参阅 Windows SDK 中“OLE DB 程序员参考”中的 IRowsetIndentity::IsSameRow。
CRowset::MoveFirst
将游标移动到初始位置并检索初始行。
语法
HRESULT MoveFirst() throw();
返回值
标准 HRESULT。
备注
调用 以将下一个提取位置重新定位到初始位置（创建行集时下一个提取位置的位置）并检索初始行。
CRowset::MoveLast
将游标移到最后一行。
语法
HRESULT MoveLast() throw();
返回值
标准 HRESULT。
注解
调用 IRowset::RestartPosition 以将下一个提取位置重新定位到最后一个位置并检索最后一行。
此方法要求在包含行集的表或命令上调用 Open 之前将 DBPROP_CANSCROLLBACKWARDS 设置为 VARIANT_TRUE。 （为了获得更好的性能，还可以将 DBPROP_QUICKRESTART 设置为 VARIANT_TRUE。）
CRowset::MoveNext
将游标移到下一条记录。
语法
HRESULT MoveNext() throw();
HRESULT MoveNext(LONG lSkip,
bool bForward= true) throw();
参数
lSkip
[in] 提取之前要跳过的行数。
bForward
[in] 传递 true 向前移动到下一条记录，传递 false 向后移动到下一条记录。
返回值
标准 HRESULT。 到达行集末尾时，返回 DB_S_ENDOFROWSET。
备注
从 CRowset 对象中提取下一个顺序行，记住上一个位置。 或者，可以选择跳过 lSkip 行或向后移动。
此方法要求在包含行集的表或命令上调用 Open 之前设置以下属性：
如果 lSkip< 0，则
DBPROP_CANSCROLLBACKWARDS必须为 VARIANT_TRUE如果 bForward = false，则
DBPROP_CANFETCHBACKWARDS必须为 VARIANT_TRUE
否则（如果 lSkip>= 0 且 bForward = true），无需设置任何其他属性。
CRowset::MovePrev
将游标移动到上一条记录。
语法
HRESULT MovePrev() throw();
返回值
标准 HRESULT。
注解
此方法要求在包含行集的表或命令上调用 Open 之前将 DBPROP_CANFETCHBACKWARDS 或 DBPROP_CANSCROLLBACKWARDS 设置为 VARIANT_TRUE。
CRowset::MoveToBookmark
提取用书签标记的行或距离该书签指定偏移量 (lSkip) 的行。
语法
HRESULT MoveToBookmark(const CBookmarkBase& bookmark,
LONG lSkip = 0) throw();
参数
bookmark
[in] 标记要从其提取数据的位置的书签。
lSkip
[in] 从书签到目标行的行数。 如果 lSkip 为 0，则提取的第一行是添加了书签的行。 如果 lSkip 为 1，则提取的第一行是位于添加了书签的行后面的行。 如果 lSkip 为 -1，则提取的第一行是位于添加了书签的行前面的行。
返回值
标准 HRESULT。
注解
此方法需要可选接口 IRowsetLocate，该接口可能并非在所有提供程序上都受支持；如果是这样，该方法将返回 E_NOINTERFACE。 在包含行集的表或命令上调用 Open 之前，还必须将 DBPROP_IRowsetLocate 设置为 VARIANT_TRUE，并将 DBPROP_CANFETCHBACKWARDS 设置为 VARIANT_TRUE。
有关在使用者中使用书签的信息，请参阅使用书签。
CRowset::MoveToRatio
从行集中的分数位置开始提取行。
语法
HRESULT MoveToRatio(DBCOUNTITEM nNumerator,
DBCOUNTITEM nDenominator,bool bForward = true) throw();
参数
nNumerator
[in] 用于确定从中提取数据的分数位置的分子。
nDenominator
[in] 用于确定从中提取数据的分数位置的分母。
bForward
[in] 指示是向前移动还是向后移动。 默认值为向前。
返回值
标准 HRESULT。
备注
MoveToRatio 大致根据以下公式提取行：
(nNumerator * RowsetSize ) / nDenominator
其中 RowsetSize 是行集的大小（以行为单位）。 此公式的准确性取决于具体的提供程序。 有关详细信息，请参阅 IRowsetScroll::GetRowsAtRatio。
此方法需要可选接口 IRowsetScroll，该接口可能并非在所有提供程序上都受支持；如果是这样，该方法将返回 E_NOINTERFACE。 在包含行集的表或命令上调用 Open 之前，还必须将 DBPROP_IRowsetScroll 设置为 VARIANT_TRUE。
CRowset::ReleaseRows
调用 IRowset::ReleaseRows 以释放当前行句柄。
语法
HRESULT ReleaseRows() throw();
返回值
标准 HRESULT。
CRowset::SetData
设置一行中的一列或多列中的数据值。
语法
HRESULT SetData() const throw();
HRESULT SetData(int nAccessor) const throw();
参数
nAccessor
[in] 用于访问数据的访问器的编号。
返回值
标准 HRESULT。
备注
对于接受无自变量的 SetData 表单，所有访问器都用于更新。 通常调用 SetData 以在行中的列中数据值，然后调用 Update 以传输这些更改。
此方法需要可选接口 IRowsetChange，该接口可能并非在所有提供程序上都受支持；如果是这样，该方法将返回 E_NOINTERFACE。 在包含行集的表或命令上调用 Open 之前，还必须将 DBPROP_IRowsetChange 设置为 VARIANT_TRUE。
如果一列或多列不可写，则设置操作可能失败。 修改光标映射以更正此问题。
CRowset::Undo
撤消自上次提取或更新以来对行进行的任何更改。
语法
HRESULT Undo(DBCOUNTITEM* pcRows = NULL,
HROW* phRow = NULL,
DBROWSTATUS* pStatus = NULL) throw();
参数
pcRows
[out] 指向 Undo 尝试撤消（如果需要）的行数的位置的指针。
phRow
[out] 指向 Undo 尝试撤消（如果需要）的所有行的句柄数组的位置的指针。
pStatus
[out] 指向 Undo 返回行状态值的位置的指针。 如果 pStatus 为 null，则不返回状态。
返回值
标准 HRESULT。
注解
此方法需要可选接口 IRowsetUpdate，该接口可能并非在所有提供程序上都受支持；如果是这样，该方法将返回 E_NOINTERFACE。 在包含行集的表或命令上调用 Open 之前，还必须将 DBPROP_IRowsetUpdate 设置为 VARIANT_TRUE。
CRowset::Update
传输自上次提取或调用 Update 以来对当前行进行的任何挂起的更改。
语法
HRESULT Update(DBCOUNTITEM* pcRows = NULL,
HROW* phRow = NULL,
DBROWSTATUS* pStatus = NULL) throw();
参数
pcRows
[out] 指向 Update 尝试更新（如果需要）的行数的位置的指针。
phRow
[out] 指向 Update 尝试更新（如果需要）的行的句柄的位置的指针。 如果 phRow 为 null，则不返回句柄。
pStatus
[out] 指向 Update 返回行状态值的位置的指针。 如果 pStatus 为 null，则不返回状态。
返回值
标准 HRESULT。
备注
传输自上次提取或更新（使用 Update 或 UpdateAll）当前行以来对其进行的任何挂起的更改。 通常调用 SetData 以在行中的列中数据值，然后调用 Update 以传输这些更改。
此方法需要可选接口 IRowsetUpdate，该接口可能并非在所有提供程序上都受支持；如果是这样，该方法将返回 E_NOINTERFACE。 在包含行集的表或命令上调用 Open 之前，还必须将 DBPROP_IRowsetUpdate 设置为 VARIANT_TRUE。
CRowset::UpdateAll
传输自上次提取或调用 Update 以来对所有行进行的任何挂起的更改。
语法
HRESULT UpdateAll(DBCOUNTITEM* pcRows = NULL,
HROW** pphRow = NULL,
DBROWSTATUS** ppStatus = NULL) throw();
参数
pcRows
[out] 指向 UpdateAll 尝试更新（如果需要）的行数的位置的指针。
pphRow
[out] 指向 UpdateAll 尝试更新（如果需要）的行的句柄的所处的内存的指针。 如果 pphRow 为 null，则不返回句柄。
ppStatus
[out] 指向 Update 返回行状态值的位置的指针。 如果 ppStatus 为 null，则不返回状态。
注解
传输自上次提取或更新（使用 Update 或 UpdateAll）所有行以来对其进行的任何挂起的更改。 UpdateAll 将更新已修改的每一行，不管它们是否仍有句柄（请参阅 pphRow）。
例如，如果你曾经使用 Insert 在行集中插入五行，则可以调用 Update 五次或调用 UpdateAll 一次以将其全部更新。
此方法需要可选接口 IRowsetUpdate，该接口可能并非在所有提供程序上都受支持；如果是这样，该方法将返回 E_NOINTERFACE。 在包含行集的表或命令上调用 Open 之前，还必须将 DBPROP_IRowsetUpdate 设置为 VARIANT_TRUE。
返回值
标准 HRESULT。
另请参阅
DBViewer 示例
MultiRead 示例
MultiRead 特性示例
OLE DB 使用者模板
OLE DB 使用者模板参考
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈