CRowset 類別

發行項
08/03/2024

封裝 OLE DB 資料列集物件和數個相關介面，並提供數據列集數據的操作方法。

語法

template <class TAccessor = CAccessorBase>
class CRowset

參數

TAccessor
存取子類別。預設值為 CAccessorBase。

需求

標頭檔：atldbcli.h

成員

方法

名稱	描述
AddRefRows	遞增與目前數據列相關聯的參考計數。
關閉	釋放數據列和目前的 `IRowset` 介面。
比較	使用 IRowsetLocate：：Compare 比較兩個書籤。
CRowset	建立新的 `CRowset` 物件，並（選擇性地）將它與 `IRowset` 提供做為參數的介面產生關聯。
刪除	使用 IRowsetChange：DeleteRows 從數據列集中刪除數據列。
FindNextRow	尋找指定書籤之後的下一個相符數據列。
GetApproximatePosition	傳回對應至書籤之數據列的近似位置。
GetData	從數據列集的數據列復本擷取數據。
GetDataHere	從指定的緩衝區擷取數據。
GetOriginalData	擷取最近從數據源擷取或傳輸的數據，忽略擱置的變更。
GetRowStatus	傳回所有數據列的狀態。
插入	使用 IRowsetChange：InsertRow 建立並插入新的數據列。
IsSameRow	比較指定的數據列與目前的數據列。
MoveFirst	將下一個擷取位置重新置放至初始位置。
MoveLast	移至最後一筆記錄。
MoveNext	從下一個循序數據列擷取數據，或超過下一個數據列的指定位置數目。
MovePrev	移至上一筆記錄。
MoveToBookmark	從該書籤的指定位移擷取以書籤標記的數據列或數據列。
MoveToRatio	從數據列集中的小數位置開始擷取數據列。
ReleaseRows	呼叫 IRowset：：ReleaseRows 以釋放目前的數據列句柄。
SetData	使用 IRowsetChange：SetData，在數據列的一或多個數據行中設定數據值。
復原	復原自上次擷取或更新之後對數據列所做的任何變更。
更新	傳輸自上次擷取或更新之後對目前數據列所做的任何暫止變更。
UpdateAll	傳輸自上次擷取或更新之後對所有數據列所做的任何暫止變更。

備註

在 OLE DB 中，數據列集是程式設定和擷取數據的物件。

這個類別不是要具現化，而是要當做樣板參數傳遞至 CTable 或 CCommand （CRowset 是預設值）。

CRowset::AddRefRows

呼叫 IRowset：：AddRefRows 以遞增與目前數據列句柄相關聯的參考計數。。

語法

HRESULT AddRefRows() throw();

傳回值

標準 HRESULT。

備註

這個方法會遞增目前數據列句柄的參考計數。呼叫 ReleaseRows 以遞減計數。移動方法傳回的數據列具有一個參考計數。

CRowset::Close

釋放數據列和目前的 IRowset 介面。

語法

void Close() throw();

備註

這個方法會釋出目前在資料列集中的所有資料列。

CRowset::Compare

使用 IRowsetLocate：：Compare 比較兩個書籤。

語法

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

參數

Bookmark1
[in]要比較的第一個書籤。

Bookmark2
[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：:D eleteRows ，從數據列集中刪除目前的數據列。

語法

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]為數據值配置的取用者數據結構的長度，以位元組為單位。如需詳細資訊，請參閱 cbMaxLen OLE DB 程式設計人員參考中 DBBINDING 結構的描述。

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中指定不是 autoaccessor 的存取子，請使用此方法傳遞存取子編號來明確取得數據。

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。

備註

CRowset::Insert

使用存取子中的數據，建立並初始化新的數據列。

語法

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

參數

nAccessor
[in]要用於插入數據的存取子數目。

bGetHRow
[in]指出是否擷取插入數據列的句柄。

傳回值

標準 HRESULT。

備註

此方法需要選擇性介面，並非所有提供者都不支持這個介面 IRowsetChange;如果發生這種情況，方法會傳回E_NOINTERFACE。您也必須在包含數據列集的數據表或命令上呼叫Open之前，先將設定DBPROP_IRowsetChange為 VARIANT_TRUE。

如果一或多個數據行無法寫入，插入可能會失敗。請修改您的資料指標對應以修正這個問題。

範例

下列範例示範如何透過數據列集存取數據源，然後使用該數據列集中的數據表插入字串。

首先，將 New ATL 物件插入您的專案中，以建立資料表類別。例如，以滑鼠右鍵按兩下 [工作區] 窗格中的項目，然後選取 [ 新增 ATL 物件]。從 [ 數據存取] 類別中，選取 [ 取用者]。建立 Table 類型的取用者物件。（選取 數據表 會直接從數據表建立數據列集;選取 [命令 ] 會透過 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。

備註

呼叫 IRowset：：RestartPosition ，將下一個擷取位置重新置放到初始位置（建立數據列集時下一個提取位置的位置），並擷取初始數據列。

CRowset::MoveLast

將游標移至最後一個數據列。

語法

HRESULT MoveLast() throw();

傳回值

標準 HRESULT。

備註

呼叫 IRowset：：RestartPosition ，將下一個擷取位置重新定位到最後一個位置，並擷取最後一個數據列。

此方法會要求您先將設定 DBPROP_CANSCROLLBACKWARDS 為 VARIANT_TRUE，再呼叫 Open 包含數據列集的數據表或命令。（為了提升效能，您也可以將設定 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 包含資料列集的數據表或命令：

DBPROP_CANSCROLLBACKWARDS 如果 lSkip< 0，則必須VARIANT_TRUE
DBPROP_CANFETCHBACKWARDS 如果 bForward = false，則必須VARIANT_TRUE

否則（如果 lSkip>= 0 和 bForward = true），則不需要設定任何其他屬性。

CRowset::MovePrev

將游標移至上一筆記錄。

語法

HRESULT MovePrev() throw();

傳回值

標準 HRESULT。

備註

此方法會要求您先將或 DBPROP_CANSCROLLBACKWARDS 設定DBPROP_CANFETCHBACKWARDS為 VARIANT_TRUE，再呼叫Open包含數據列集的數據表或命令。

CRowset::MoveToBookmark

從該書籤擷取以書籤標記的數據列或位於指定位移（lSkip）的數據列。

語法

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

參數

bookmark
[in] 標記您要從中擷取資料之位置的書籤。

lSkip
[in] 從書籤到目標資料列的資料列計數。如果 lSkip 為零，則擷取的第一個數據列是書籤數據列。如果 lSkip 為 1，則擷取的第一個數據列是書籤數據列之後的數據列。如果 lSkip 為 -1，則擷取的第一個數據列是書籤數據列之前的數據列。

傳回值

標準 HRESULT。

備註

此方法需要選擇性介面，並非所有提供者都不支持這個介面 IRowsetLocate;如果發生這種情況，方法會傳回E_NOINTERFACE。您也必須將設定 DBPROP_IRowsetLocate 為 VARIANT_TRUE，並設定 DBPROP_CANFETCHBACKWARDS 為 VARIANT_TRUE，再呼叫 Open 包含數據列集的數據表或命令。

如需在取用者中使用書籤的相關信息，請參閱使用書籤。

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。

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 以傳輸這些變更。

如果一或多個數據行無法寫入，設定作業可能會失敗。請修改您的資料指標對應以修正這個問題。

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。

備註

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 以傳輸這些變更。

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 一次來更新所有數據列。

傳回值

標準 HRESULT。

另請參閱

DBViewer 範例
 MultiRead 範例
 MultiRead 屬性範例
 OLE DB 消費者範本
 OLE DB 消費者範本參考

共用方式為

CRowset 類別

語法

參數

需求

成員

方法

備註

CRowset::AddRefRows

語法

傳回值

備註

CRowset::Close

語法

備註

CRowset::Compare

語法

參數

傳回值

備註

CRowset::CRowset

語法

參數

CRowset::Delete

語法

傳回值

CRowset::FindNextRow

語法

參數

傳回值

備註

CRowset::GetApproximatePosition

語法

參數

傳回值

備註

CRowset::GetData

語法

參數

傳回值

備註

CRowset::GetDataHere

語法

參數

傳回值

備註

CRowset::GetOriginalData

語法

傳回值

備註

CRowset::GetRowStatus

語法

參數

傳回值

備註

CRowset::Insert

語法

參數

傳回值

備註

範例

CRowset::IsSameRow

語法

參數

傳回值

CRowset::MoveFirst

語法

傳回值

備註

CRowset::MoveLast

語法

傳回值

備註

CRowset::MoveNext

語法

參數

傳回值

備註

CRowset::MovePrev

語法