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 使用者模板参考