CRecordset 類別

表示選取自資料來源的資料錄集。

語法

class CRecordset : public CObject

成員

公用建構函式

名稱	描述
CRecordset::CRecordset	建構 CRecordset 物件。 您的衍生類別必須提供呼叫這個類別的建構函式。

公用方法

名稱	描述
CRecordset::AddNew	準備新增記錄。 呼叫 Update 以完成新增。
CRecordset::CanAppend	如果可以透過 AddNew 成員函式將新記錄加入至記錄集，則傳回非零。
CRecordset::CanBookmark	如果記錄集支援書籤，則傳回非零。
CRecordset::Cancel	從第二個線程取消異步操作或進程。
CRecordset::CancelUpdate	因或 Edit 作業而取消任何擱置的更新AddNew。
CRecordset::CanRestart	如果 Requery 可以呼叫 以再次執行記錄集的查詢，則傳回非零。
CRecordset::CanScroll	如果您可以捲動記錄，則傳回非零。
CRecordset::CanTransact	如果數據源支援交易，則傳回非零。
CRecordset::CanUpdate	如果記錄集可以更新，則傳回非零值（您可以新增、更新或刪除記錄）。
CRecordset::CheckRowsetError	呼叫 以處理記錄擷取期間所產生的錯誤。
CRecordset::Close	關閉與記錄集相關聯的 ODBC HSTMT 。
CRecordset::Delete	從記錄集刪除當前記錄。 您必須在刪除之後明確地捲動至另一筆記錄。
CRecordset::DoBulkFieldExchange	呼叫 以將大量數據列從數據源交換至記錄集。 實作大量記錄欄位交換（大量 RFX）。
CRecordset::DoFieldExchange	呼叫 以在記錄集的欄位數據成員與數據源上的對應記錄之間交換數據（雙向）。 實作記錄欄位交換 （RFX）。
CRecordset::Edit	準備變更目前的記錄。 呼叫 Update 以完成編輯。
CRecordset::FlushResultSet	使用預先定義的查詢時，如果有另一個要擷取的結果集，則傳回非零。
CRecordset::GetBookmark	將記錄的書籤值指派給參數物件。
CRecordset::GetDefaultConnect	呼叫 以取得預設 連接字串。
CRecordset::GetDefaultSQL	呼叫 以取得要執行的預設 SQL 字串。
CRecordset::GetFieldValue	傳回記錄集中欄位的值。
CRecordset::GetODBCFieldCount	傳回記錄集中的欄位數目。
CRecordset::GetODBCFieldInfo	傳回記錄集中欄位的特定類型資訊。
CRecordset::GetRecordCount	傳回記錄集中的記錄數目。
CRecordset::GetRowsetSize	傳回您想要在單一擷取期間擷取的記錄數目。
CRecordset::GetRowsFetched	傳回擷取期間擷取的實際數據列數目。
CRecordset::GetRowStatus	傳回擷取之後的數據列狀態。
CRecordset::GetSQL	取得用來選取記錄集記錄的 SQL 字串。
CRecordset::GetStatus	取得記錄集的狀態：目前記錄的索引，以及是否已取得記錄的最終計數。
CRecordset::GetTableName	取得記錄集所依據之數據表的名稱。
CRecordset::IsBOF	如果記錄集位於第一筆記錄之前，則傳回非零。 沒有目前的記錄。
CRecordset::IsDeleted	如果記錄集位於已刪除的記錄上，則傳回非零。
CRecordset::IsEOF	如果記錄集位於最後一筆記錄之後，則傳回非零。 沒有目前的記錄。
CRecordset::IsFieldDirty	如果當前記錄中的指定欄位已變更，則傳回非零。
CRecordset::IsFieldNull	如果目前記錄中指定的欄位為 null，則傳回非零值（沒有值）。
CRecordset::IsFieldNullable	如果目前記錄中的指定欄位可以設定為 null，則傳回非零值（沒有值）。
CRecordset::IsOpen	如果 Open 先前已呼叫，則傳回非零。
CRecordset::Move	將記錄集放置在任一方向上從目前記錄指定的記錄數目。
CRecordset::MoveFirst	將當前記錄放在記錄集中的第一筆記錄上。 測試 IsBOF 第一個。
CRecordset::MoveLast	將當前記錄放在最後一筆記錄或最後一個數據列集上。 測試 IsEOF 第一個。
CRecordset::MoveNext	將當前記錄放在下一筆記錄或下一個數據列集上。 測試 IsEOF 第一個。
CRecordset::MovePrev	將當前記錄放在上一筆記錄或上一個數據列集上。 測試 IsBOF 第一個。
CRecordset::OnSetOptions	呼叫 以設定指定 ODBC 語句的選項（用於選取範圍）。
CRecordset::OnSetUpdateOptions	呼叫 以設定指定 ODBC 語句的選項（用於更新）。
CRecordset::Open	藉由擷取數據表或執行記錄集所代表的查詢，開啟記錄集。
CRecordset::RefreshRowset	重新整理指定數據列的數據和狀態。
CRecordset::Requery	再次執行記錄集的查詢，以重新整理選取的記錄。
CRecordset::SetAbsolutePosition	將記錄集放在對應至指定記錄編號的記錄上。
CRecordset::SetBookmark	將記錄集放在書籤所指定的記錄上。
CRecordset::SetFieldDirty	將當前記錄中的指定欄位標示為已變更。
CRecordset::SetFieldNull	將目前記錄中指定欄位的值設定為 null（沒有值）。
CRecordset::SetLockingMode	將鎖定模式設定為「開放式」鎖定（預設值）或「悲觀」鎖定。 決定如何鎖定更新的記錄。
CRecordset::SetParamNull	將指定的參數設定為 null（沒有值）。
CRecordset::SetRowsetCursorPosition	將游標放在數據列集內的指定數據列上。
CRecordset::SetRowsetSize	指定您想要在擷取期間擷取的記錄數目。
CRecordset::Update	藉 AddNew 由將新的或編輯的數據儲存在數據源上，以完成 或 Edit 作業。

公用數據成員

名稱	描述
CRecordset::m_hstmt	包含記錄集的 ODBC 語句句柄。 輸入 HSTMT。
CRecordset::m_nFields	包含記錄集中的欄位資料成員數目。 輸入 UINT。
CRecordset::m_nParams	包含記錄集中的參數數據成員數目。 輸入 UINT。
CRecordset::m_pDatabase	包含物件指標， CDatabase 記錄集透過該對象連接到數據源。
CRecordset::m_strFilter	包含 CString ，指定 結構化查詢語言 (SQL) （SQL） WHERE 子句。 用來做為篩選條件，只選取符合特定準則的記錄。
CRecordset::m_strSort	包含 CString 指定 SQL ORDER BY 子句的 。 用來控制記錄的排序方式。

備註

稱為「記錄集」 CRecordset ，物件通常會以兩種形式使用：動態集和快照集。 動態集會與其他用戶進行的數據更新保持同步。 快照集是數據的靜態檢視。 每個表單都代表一組在開啟記錄集時固定的記錄。 當您捲動至動態集中的記錄時，它會反映其他使用者或應用程式中其他記錄集對記錄所做的變更。

注意

如果您要使用數據存取物件 （DAO） 類別，而不是 Open Database Connectivity （ODBC） 類別，請改用 類別 CDaoRecordset 。 如需詳細資訊，請參閱 概觀：資料庫程序設計。

若要使用任一類型的記錄集，您通常會從 CRecordset衍生應用程式特定的記錄集類別。 記錄集會從數據源選取記錄，然後您可以：

• 捲動記錄。

• 更新記錄並指定鎖定模式。

• 篩選記錄集以限制它從數據源上可用的記錄選取的記錄。

• 排序記錄集。

• 將記錄集參數化，以在運行時間之前不知道的資訊來自定義其選取範圍。

若要使用類別，請開啟資料庫並建構 recordset 物件，並將建構函式傳遞至物件的 CDatabase 指標。 然後呼叫記錄集的成員 Open 函式，您可以在其中指定對像是動態集或快照集。 呼叫 Open 會從數據源選取數據。 開啟記錄集物件之後，請使用其成員函式和數據成員來捲動記錄並對其操作。 可用的作業取決於對像是動態集還是快照集，無論是可更新還是只讀的作業（這取決於開放式資料庫連線能力 （ODBC） 數據源的功能，以及您是否已實作大量數據列擷取。 若要重新整理自呼叫之後 Open 可能已變更或新增的 Requery 記錄，請呼叫對象的成員函式。 呼叫對象的 Close 成員函式，並在完成此函式時終結物件。

在衍生 CRecordset 類別中，記錄欄位交換 （RFX） 或大量記錄欄位交換 （Bulk RFX） 是用來支援讀取和更新記錄欄位。

如需記錄集和記錄欄位交換的詳細資訊，請參閱概觀：資料庫程式設計、記錄集 （ODBC）、記錄集：大量擷取記錄和記錄欄位交換 （RFX） 一文。 如需動態集和快照集的焦點，請參閱動態集和快照集文章。

繼承階層

CObject

CRecordset

需求

標頭： afxdb.h

CRecordset::AddNew

準備將新記錄新增至數據表。

virtual void AddNew();

備註

您必須呼叫 Requery 成員函式，才能看到新增的記錄。 記錄的欄位一開始為 Null。 （在資料庫術語中，Null 表示「沒有值」，而且與C++中的 NULL 不同。若要完成作業，您必須呼叫 Update 成員函式。 Update 儲存您對資料源的變更。

注意

如果您已實作大量資料列擷取，則無法呼叫 AddNew。 這會導致判斷提示失敗。 雖然 類別 CRecordset 不提供更新大量數據列的機制，但您可以使用 ODBC API 函 SQLSetPos式來撰寫自己的函式。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

AddNew 使用記錄集的欄位數據成員來準備新的空白記錄。 呼叫 AddNew之後，請在記錄集的欄位資料成員中設定您想要的值。 （您不需要呼叫 針對此目的編輯 成員函式; Edit 僅適用於現有的記錄。當您呼叫 Update時，欄位數據成員中的變更值會儲存在數據源上。

警告

如果您在呼叫 Update之前捲動至新記錄，則會遺失新記錄，而且不會提供任何警告。

如果數據源支援交易，您可以進行 AddNew 交易的呼叫部分。 如需交易的詳細資訊，請參閱 類別 CDatabase。 通話 之前先呼叫 CDatabase::BeginTrans AddNew。

注意

對於動態集，新記錄會新增至記錄集作為最後一筆記錄。 新增的記錄不會新增至快照集;您必須呼叫 Requery 以重新整理記錄集。

呼叫成員函式尚未呼叫的記錄集Open是非法AddNew的。 CDBException如果您呼叫AddNew無法附加至的記錄集，則會擲回 。 您可以呼叫 CanAppend來判斷記錄集是否可更新。

如需詳細資訊，請參閱下列文章： 記錄集：記錄集如何更新記錄 （ODBC）、 記錄集：新增、更新和刪除記錄 （ODBC）和 交易 （ODBC） 。

範例

請參閱 交易：在記錄集 （ODBC） 中執行交易。

CRecordset::CanAppend

判斷先前開啟的記錄集是否允許您新增記錄。

BOOL CanAppend() const;

傳回值

如果記錄集允許新增記錄，則為非零;否則為 0。 CanAppend 如果您以唯讀模式開啟記錄集，則會傳回 0。

CRecordset::CanBookmark

判斷記錄集是否允許您使用書籤標記記錄。

BOOL CanBookmark() const;

傳回值

如果記錄集支援書籤，則為非零;否則為 0。

備註

此函式與CRecordset::useBookmarks成員函式參數Open中的 dwOptions 選項無關。 CanBookmark 指出指定的 ODBC 驅動程式和資料指標類型是否支援書籤。 CRecordset::useBookmarks 會指出書籤是否可供使用，前提是它們受到支援。

注意

僅轉寄記錄集不支援書籤。

如需書籤和記錄集導覽的詳細資訊，請參閱 Recordset：Bookmarks 和 Absolute Positions （ODBC） 和 Recordset： Scrolling （ODBC）文章。

CRecordset::Cancel

要求數據源取消進行中的異步操作，或從第二個線程取消進程。

void Cancel();

備註

MFC ODBC 類別不再使用異步處理;若要執行異步操作，您必須直接呼叫 ODBC API 函式 SQLSetConnectOption。 如需詳細資訊，請參閱 ODBC SDK 程式設計人員指南中的。

CRecordset::CancelUpdate

在呼叫 之前Update，取消或 AddNew 作業所造成的Edit任何擱置更新。

void CancelUpdate();

備註

注意

此成員函式不適用於使用大量資料列擷取的記錄集，因為這類記錄集無法呼叫 Edit、 AddNew或 Update。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

如果已啟用自動髒欄位檢查， CancelUpdate 則會將成員變數還原至之前 Edit 或 AddNew 呼叫過的值;否則，任何值變更都會保留。 預設會在開啟記錄集時啟用自動欄位檢查。 若要停用它，您必須在 Open 成員函式的 參數中dwOptions指定 CRecordset::noDirtyFieldCheck 。

如需更新資料的詳細資訊，請參閱 記錄集：新增、更新和刪除記錄 （ODBC） 。

CRecordset::CanRestart

藉由呼叫 Requery 成員函式，判斷記錄集是否允許重新啟動其查詢（重新整理其記錄）。

BOOL CanRestart() const;

傳回值

如果允許重新查詢，則為非零;否則為 0。

CRecordset::CanScroll

判斷記錄集是否允許捲動。

BOOL CanScroll() const;

傳回值

如果記錄集允許卷動，則為非零;否則為 0。

備註

如需捲動的詳細資訊，請參閱 Recordset：Scrolling （ODBC）。

CRecordset::CanTransact

判斷記錄集是否允許交易。

BOOL CanTransact() const;

傳回值

如果記錄集允許交易，則為非零;否則為 0。

備註

如需詳細資訊，請參閱 交易 （ODBC）。

CRecordset::CanUpdate

判斷是否可以更新記錄集。

BOOL CanUpdate() const;

傳回值

如果記錄集可以更新，則為非零;否則為 0。

備註

如果基礎數據源是唯讀的，或是當您開啟記錄集時於 dwOptions 參數中指定CRecordset::readOnly，則記錄集可能是只讀的。

CRecordset::CheckRowsetError

呼叫 以處理記錄擷取期間所產生的錯誤。

virtual void CheckRowsetError(RETCODE nRetCode);

參數

nRetCode
ODBC API 函式傳回碼。 如需詳細資料，請參閱＜備註＞。

備註

此虛擬成員函式會處理擷取記錄時所發生的錯誤，並在大量數據列擷取期間很有用。 您可能想要考慮覆寫 CheckRowsetError 以實作自己的錯誤處理。

CheckRowsetError 在資料指標瀏覽作業中自動呼叫 ，例如 Open、 Requery或任何 Move 作業。 它會傳遞 ODBC API 函 SQLExtendedFetch式 的傳回值。 下表列出 參數的 nRetCode 可能值。

nRetCode	描述
SQL_SUCCESS	函式順利完成;沒有其他資訊可用。
SQL_SUCCESS_WITH_INFO	函式已順利完成，可能發生非嚴重錯誤。 呼叫 即可取得 SQLError其他資訊。
SQL_NO_DATA_FOUND	已擷取結果集中的所有數據列。
SQL_ERROR	函數失敗。 呼叫 即可取得 SQLError其他資訊。
SQL_INVALID_HANDLE	函式失敗，因為環境句柄、連接句柄或語句句柄無效。 這表示此處有程式設計錯誤。 沒有其他資訊可從取得 SQLError。
SQL_STILL_EXECUTING	以非同步方式啟動的函數仍會繼續執行。 根據預設，MFC 永遠不會將此值傳遞至 CheckRowsetError;MFC 會繼續呼叫 SQLExtendedFetch ，直到它不再傳 SQL_STILL_EXECUTING回 為止。

如需 的詳細資訊 SQLError，請參閱 Windows SDK。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

CRecordset::Close

關閉記錄集。

virtual void Close();

備註

已解除分配為記錄集配置架構的 ODBC HSTMT 和所有記憶體。 呼叫 之後 Close，如果您已使用 new配置，您通常會刪除C++ recordset 物件。

您可以在呼叫 之後再次呼叫 Open Close。 這可讓您重複使用 recordset 物件。 替代方法是呼叫 Requery。

範例

// Construct a snapshot object
CCustomer rsCustSet(NULL);

if (!rsCustSet.Open())
return;

// Use the snapshot ...

// Close the snapshot
rsCustSet.Close();

// Destructor is called when the function exits

CRecordset::CRecordset

建構 CRecordset 物件。

CRecordset(CDatabase* pDatabase = NULL);

參數

pDatabase
包含物件的指標 CDatabase 或值 NULL。 如果不是 NULL ， CDatabase 而且尚未呼叫對象的 Open 成員函式來將它連接到數據源，則記錄集會在自己的 Open 呼叫期間嘗試開啟該函式。 如果您傳遞 NULL， CDatabase 則會使用您使用 ClassWizard 衍生記錄集類別時所指定的數據源資訊，為您建構並連接 物件。

備註

您可以直接使用 CRecordset ，或從 CRecordset衍生應用程式特定的類別。 您可以使用 ClassWizard 來衍生您的記錄集類別。

注意

衍生類別 必須 提供自己的建構函式。 在衍生類別的建構函式中，呼叫 建構函式 ，並將適當的參數傳遞至該建構 CRecordset::CRecordset函式。

傳遞 NULL 至您的記錄集建構函式，以 CDatabase 自動為您建構並連接物件。 這是一個實用的速記，不需要您在建構記錄集之前建構及連接 CDatabase 物件。

範例

如需詳細資訊，請參閱 Recordset：宣告數據表的類別 （ODBC）。

CRecordset::Delete

刪除目前的記錄。

virtual void Delete();

備註

成功刪除之後，記錄集的欄位數據成員會設定為 Null 值，而且您必須明確呼叫其中 Move 一個函式，才能離開已刪除的記錄。 一旦您離開已刪除的記錄，就無法返回該記錄。 如果數據源支援交易，您可以進行 Delete 交易的呼叫部分。 如需詳細資訊，請參閱 交易 （ODBC）。

注意

如果您已實作大量資料列擷取，則無法呼叫 Delete。 這會導致判斷提示失敗。 雖然 類別 CRecordset 不提供更新大量數據列的機制，但您可以使用 ODBC API 函 SQLSetPos式來撰寫自己的函式。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

警告

記錄集必須可更新，而且當您呼叫 Delete記錄集時，記錄集中必須有有效的當前記錄，否則會發生錯誤。 例如，如果您刪除記錄，但不在再次呼叫 Delete 之前捲動至新記錄， Delete 則會 擲回CDBException。

與和Edit不同AddNew，對的呼叫Delete不會接著呼叫 Update。 Delete如果呼叫失敗，欄位數據成員會保持不變。

範例

此範例會顯示在函式框架上建立的記錄集。 此範例假設 存在 m_dbCust，這個成員變數的類型 CDatabase 已經連接到數據源。

// Create a derived CRecordset object
CCustomer rsCustSet(&m_dbCust);
rsCustSet.Open();

if (rsCustSet.IsEOF() || !rsCustSet.CanUpdate() ||
   !rsCustSet.CanTransact())
{
   return;
}

m_dbCust.BeginTrans();

// Perhaps scroll to a new record...
// Delete the current record
rsCustSet.Delete();

// Finished commands for this transaction
if (IDYES == AfxMessageBox(_T("Commit transaction?"), MB_YESNO))
m_dbCust.CommitTrans();
else // User changed mind
m_dbCust.Rollback();

CRecordset::DoBulkFieldExchange

呼叫 以將大量數據列從數據源交換至記錄集。 實作大量記錄欄位交換（大量 RFX）。

virtual void DoBulkFieldExchange(CFieldExchange* pFX);

參數

pFX
CFieldExchange 物件的指標。 架構已設定此物件，以指定欄位交換作業的內容。

備註

實作大量數據列擷取時，架構會呼叫這個成員函式，以自動將數據從數據源傳輸到您的 recordset 物件。 DoBulkFieldExchange 也會將參數數據成員系結至記錄集選取範圍之 SQL 語句字串中的參數佔位元。

如果未實作大量資料列擷取，架構會呼叫 DoFieldExchange。 若要實作大量數據列擷取，您必須在成員函式中指定 CRecordset::useMultiRowFetch dwOptions 參數的選項。Open

注意

DoBulkFieldExchange 只有在您使用衍生自 CRecordset的類別時，才能使用 。 如果您已直接從 CRecordset建立 recordset 物件，則必須呼叫 GetFieldValue 成員函式來擷取數據。

大量記錄欄位交換（大量 RFX）類似於記錄欄位交換（RFX）。 數據會自動從數據源傳輸到 recordset 物件。 不過，您無法呼叫 AddNew、 Edit、 Delete或 Update ，將變更傳回數據源。 類別 CRecordset 目前不提供更新大量數據列的機制;不過，您可以使用 ODBC API 函 SQLSetPos式來撰寫自己的函式。

ClassWizard 不支援大量記錄欄位交換;因此，您必須手動覆寫 DoBulkFieldExchange 大量 RFX 函式的呼叫。 如需這些函式的詳細資訊，請參閱 記錄欄位 Exchange 函式。

如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。 如需相關信息，請參閱記錄字段交換（RFX）。

CRecordset::DoFieldExchange

呼叫 以在記錄集的欄位數據成員與數據源上的對應記錄之間交換數據（雙向）。 實作記錄欄位交換 （RFX）。

virtual void DoFieldExchange(CFieldExchange* pFX);

參數

pFX
CFieldExchange 物件的指標。 架構已設定此物件，以指定欄位交換作業的內容。

備註

未實作大量數據列擷取時，架構會呼叫這個成員函式，以在記錄集物件的欄位數據成員與數據源上目前記錄的對應數據行之間自動交換數據。 DoFieldExchange 也會將參數數據成員系結至記錄集選取範圍之 SQL 語句字串中的參數佔位元。

如果實作大量資料列擷取，架構會呼叫 DoBulkFieldExchange。 若要實作大量數據列擷取，您必須在成員函式中Open指定 CRecordset::useMultiRowFetch 參數的選項dwOptions。

注意

DoFieldExchange 只有在您使用衍生自 CRecordset的類別時，才能使用 。 如果您已直接從 CRecordset建立 recordset 物件，則必須呼叫 GetFieldValue 成員函式來擷取數據。

欄位數據的交換，稱為記錄欄位交換（RFX），雙向運作：從 recordset 物件的欄位數據成員到數據源上記錄的欄位，以及從數據源上的記錄到 recordset 物件。

您通常必須針對衍生記錄集類別實 DoFieldExchange 作的唯一動作，就是使用 ClassWizard 建立類別，並指定字段數據成員的名稱和數據類型。 您也可以將程式代碼新增至 ClassWizard 所寫入的內容，以指定參數數據成員，或處理您動態系結的任何數據行。 如需詳細資訊，請參閱資料錄集：動態地繫結資料行 (ODBC)。

當您使用 ClassWizard 宣告衍生的記錄集類別時，精靈會為您撰寫 的覆寫 DoFieldExchange ，其類似下列範例：

void CCustomer::DoFieldExchange(CFieldExchange* pFX)
{
   pFX->SetFieldType(CFieldExchange::outputColumn);
   // Macros such as RFX_Text() and RFX_Int() are dependent on the
   // type of the member variable, not the type of the field in the database.
   // ODBC will try to automatically convert the column value to the requested type
   RFX_Long(pFX, _T("[CustomerID]"), m_CustomerID);
   RFX_Text(pFX, _T("[ContactFirstName]"), m_ContactFirstName);
   RFX_Text(pFX, _T("[PostalCode]"), m_PostalCode);
   RFX_Text(pFX, _T("[L_Name]"), m_L_Name);
   RFX_Long(pFX, _T("[BillingID]"), m_BillingID);

   pFX->SetFieldType(CFieldExchange::inputParam);
   RFX_Text(pFX, _T("Param"), m_strParam);
}

如需 RFX 函式的詳細資訊，請參閱 記錄欄位 Exchange 函式。

如需 的進一步範例和詳細數據 DoFieldExchange，請參閱 記錄字段交換：RFX 的運作方式。 如需 RFX 的一般資訊，請參閱 記錄欄位交換。

CRecordset::Edit

允許變更目前的記錄。

virtual void Edit();

備註

呼叫 Edit之後，您可以直接重設字段數據成員的值來變更欄位數據成員。 當您呼叫成員函式以 Update 將變更儲存在數據源上時，作業就會完成。

注意

如果您已實作大量資料列擷取，則無法呼叫 Edit。 這會導致判斷提示失敗。 雖然 類別 CRecordset 不提供更新大量數據列的機制，但您可以使用 ODBC API 函 SQLSetPos式來撰寫自己的函式。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

Edit 會儲存記錄集數據成員的值。 如果您呼叫 Edit、進行變更，然後再呼叫 Edit 一次，記錄的值就會還原到第一次 Edit 呼叫之前的值。

在某些情況下，您可能會想要藉由將數據行設為 Null 來更新資料行（不包含任何數據）。 若要這樣做，請使用TRUE的參數呼叫 SetFieldNull 以標示字段 Null;這也會導致數據行更新。 如果您想要將欄位寫入數據源，即使其值尚未變更，請使用TRUE的參數呼叫 SetFieldDirty 。 即使欄位具有 Null 值，也是如此。

如果數據源支援交易，您可以進行 Edit 交易的呼叫部分。 在 CDatabase::BeginTrans 呼叫 之前呼叫 Edit ，並在開啟記錄集之後呼叫 。 此外，呼叫CDatabase::CommitTrans不是用來完成作業的Edit替代呼叫Update。 如需交易的詳細資訊，請參閱 類別 CDatabase。

根據目前的鎖定模式，更新的記錄可能會被鎖定 Edit ，直到您呼叫 Update 或捲動至另一筆記錄，或只能在呼叫期間 Edit 鎖定。 您可以使用 變更鎖定模式 SetLockingMode。

如果您在呼叫 Update之前捲動至新記錄，則會還原目前記錄的先前值。 CDBException如果您呼叫Edit無法更新的記錄集，或沒有目前的記錄，則會擲回 。

如需詳細資訊，請參閱交易 （ODBC） 和記錄集：鎖定記錄 （ODBC） 一文。

範例

// To edit a record, first set up the edit buffer
rsCustSet.Edit();

// Then edit field data members for the record
rsCustSet.m_BillingID = 2795;
rsCustSet.m_ContactFirstName = _T("Jones Mfg");

// Finally, complete the operation
if (!rsCustSet.Update())
{
   // Handle the failure to update
   AfxMessageBox(_T("Couldn't update record!"));
}

CRecordset::FlushResultSet

如果有多個結果集，擷取預先定義查詢的下一個結果集（預存程式）。

BOOL FlushResultSet();

傳回值

如果要擷取更多結果集，則為非零;否則為 0。

備註

只有在您完成目前結果集上的游標時，才應該呼叫 FlushResultSet 。 當您藉由呼叫 FlushResultSet擷取下一個結果集時，游標在該結果集上無效;您應該在呼叫 FlushResultSet之後呼叫MoveNext成員函式。

如果預先定義的查詢使用輸出參數或輸入/輸出參數，您必須呼叫 FlushResultSet ，直到傳回 FALSE（值 0），才能取得這些參數值。

FlushResultSet 會呼叫 ODBC API 函式 SQLMoreResults。 如果 SQLMoreResults 傳回 SQL_ERROR 或 SQL_INVALID_HANDLE，則會 FlushResultSet 擲回例外狀況。 如需 的詳細資訊 SQLMoreResults，請參閱 Windows SDK。

如果您想要呼叫 FlushResultSet，您的預存程式必須具有系結欄位。

範例

下列程式代碼假設 COutParamRecordset 是以 CRecordset具有輸入參數和輸出參數且具有多個結果集之預先定義查詢為基礎的衍生物件。 請注意覆寫的結構 DoFieldExchange 。

// DoFieldExchange override
//
// Only necessary to handle parameter bindings.
// Don't use CRecordset-derived class with bound
// fields unless all result sets have same schema
// OR there is conditional binding code.
void CCourses::DoFieldExchange(CFieldExchange* pFX)
{
   pFX->SetFieldType(CFieldExchange::outputParam);
   RFX_Long(pFX, _T("Param1"), m_nCountParam);
   // The "Param1" name here is a dummy name 
   // that is never used

   pFX->SetFieldType(CFieldExchange::inputParam);
   RFX_Text(pFX, _T("Param2"), m_strNameParam);
   // The "Param2" name here is a dummy name 
   // that is never used
}

 

// Assume db is an already open CDatabase object
CCourses rs(&m_dbCust);
rs.m_strNameParam = _T("History");

// Get the first result set
// NOTE: SQL Server requires forwardOnly cursor 
//       type for multiple rowset returning stored 
//       procedures
rs.Open(CRecordset::forwardOnly,
   _T("{? = CALL GetCourses( ? )}"),
   CRecordset::readOnly);

// Loop through all the data in the first result set
while (!rs.IsEOF())
{
   CString strFieldValue;
   for (short nIndex = 0; nIndex < rs.GetODBCFieldCount(); nIndex++)
   {
      rs.GetFieldValue(nIndex, strFieldValue);

      // TO DO: Use field value string.
   }
   rs.MoveNext();
}

// Retrieve other result sets...
while (rs.FlushResultSet())
{
   // must call MoveNext because cursor is invalid
   rs.MoveNext();

   while (!rs.IsEOF())
   {
      CString strFieldValue;
      for (short nIndex = 0; nIndex < rs.GetODBCFieldCount(); nIndex++)
      {
         rs.GetFieldValue(nIndex, strFieldValue);

         // TO DO: Use field value string.
      }
      rs.MoveNext();
   }
}


// All result sets have been flushed. Cannot
// use the cursor, but the output parameter,
// m_nCountParam, has now been written.
// Note that m_nCountParam is not valid until
// CRecordset::FlushResultSet has returned FALSE,
// indicating no more result sets will be returned.

// TO DO: Use m_nCountParam

// Cleanup
rs.Close();

CRecordset::GetBookmark

取得目前記錄的書籤值。

void GetBookmark(CDBVariant& varBookmark);

參數

varBookmark
對象的參考 CDBVariant ，表示目前記錄上的書籤。

備註

若要判斷記錄集是否支援書籤，請呼叫 CanBookmark。 若要在支援書籤的情況下提供書籤，您必須在成員函式的 Open 參數中dwOptions設定 CRecordset::useBookmarks 選項。

注意

如果書籤不受支援或無法使用，呼叫 GetBookmark 將會導致擲回例外狀況。 僅轉寄記錄集不支援書籤。

GetBookmark 將目前記錄的書籤值指派給 CDBVariant 物件。 若要在移至不同的記錄之後隨時傳回此紀錄，請使用對應的 CDBVariant 物件呼叫 SetBookmark 。

注意

在特定記錄集作業之後，書籤可能不再有效。 例如，如果您呼叫 GetBookmark 後面接著 Requery，可能無法使用 SetBookmark返回記錄。 通話 CDatabase::GetBookmarkPersistence 以檢查您是否可以安全地呼叫 SetBookmark。

如需書籤和記錄集導覽的詳細資訊，請參閱 Recordset：Bookmarks 和 Absolute Positions （ODBC） 和 Recordset： Scrolling （ODBC）文章。

CRecordset::GetDefaultConnect

呼叫 以取得預設 連接字串。

virtual CString GetDefaultConnect();

傳回值

CString，其中包含預設 連接字串。

備註

架構會呼叫此成員函式，以取得記錄集所依據之數據源的預設 連接字串。 ClassWizard 藉由識別您用來 ClassWizard 取得數據表和數據行相關信息的相同數據源，為您實作此函式。 在開發應用程式時，您可能會發現依賴此預設聯機會很方便。 但預設連線可能不適用於您的應用程式使用者。 如果是這種情況，您應該重新實作此函式，捨棄 ClassWizard的版本。 如需 連接字串 的詳細資訊，請參閱數據源 （ODBC）。

CRecordset::GetDefaultSQL

呼叫 以取得要執行的預設 SQL 字串。

virtual CString GetDefaultSQL();

傳回值

CString，包含預設 SQL 語句。

備註

架構會呼叫這個成員函式，以取得記錄集所依據的預設 SQL 語句。 這可能是數據表名稱或 SQL SELECT 語句。

您可以使用 宣告您的記錄集類別 ClassWizard，併 ClassWizard 為您執行這項工作，間接定義預設 SQL 語句。

如果您需要 SQL 語句字串供您自己的使用，請呼叫 GetSQL，這會傳回 SQL 語句，以在開啟記錄集時選取記錄集的記錄。 您可以在 類別的 覆寫 GetDefaultSQL中編輯預設 SQL 字串。 例如，您可以使用 語句來指定對預先定義查詢 CALL 的呼叫。 不過，請注意，如果您編輯 GetDefaultSQL，您也需要修改 m_nFields 以符合數據源中的數據行數目。

如需詳細資訊，請參閱 Recordset：宣告數據表的類別 （ODBC）。

警告

如果架構無法識別數據表名稱、提供多個數據表名稱，或 CALL 無法解譯語句，則數據表名稱會是空的。 當您使用 CALL 語句時，請勿在大括弧與 CALL 關鍵詞之間插入空格符，也不會在大括弧或語句中的 SELECT 關鍵詞之前SELECT插入空格符。

CRecordset::GetFieldValue

擷取目前記錄中的欄位數據。

void GetFieldValue(
    LPCTSTR lpszName,
    CDBVariant& varValue,
    short nFieldType = DEFAULT_FIELD_TYPE);

void GetFieldValue(
    LPCTSTR lpszName,
    CStringA& strValue
);

void GetFieldValue(
    LPCTSTR lpszName,
    CStringW& strValue
);

void GetFieldValue(
    short nIndex,
    CDBVariant& varValue,
    short nFieldType = DEFAULT_FIELD_TYPE);

void GetFieldValue(
    short nIndex,
    CStringA& strValue);

void GetFieldValue(
    short nIndex,
    CStringW& strValue);

參數

lpszName
功能變數名稱。

varValue 將儲存域值的 對象參考 CDBVariant 。

nFieldType
欄位的 ODBC C 資料類型。 使用預設值 DEFAULT_FIELD_TYPE，會根據下表，強制 GetFieldValue 從 SQL 數據類型判斷 C 數據類型。 否則，您可以直接指定數據類型，或選擇相容的數據類型;例如，您可以將任何資料類型儲存到 SQL_C_CHAR。

C 資料類型	SQL 資料類型
SQL_C_BIT	SQL_BIT
SQL_C_UTINYINT	SQL_TINYINT
SQL_C_SSHORT	SQL_SMALLINT
SQL_C_SLONG	SQL_INTEGER
SQL_C_FLOAT	SQL_REAL
SQL_C_DOUBLE	SQL_FLOATSQL_DOUBLE
SQL_C_TIMESTAMP	SQL_DATESQL_TIMESQL_TIMESTAMP
SQL_C_CHAR	SQL_NUMERICSQL_DECIMALSQL_BIGINTSQL_CHARSQL_VARCHARSQL_LONGVARCHAR
SQL_C_BINARY	SQL_BINARYSQL_VARBINARYSQL_LONGVARBINARY

如需 ODBC 資料類型的詳細資訊，請參閱 Windows SDK 附錄 D 中的和主題。

nIndex
欄位以零起始的索引。

strValue
對象的參考 CString ，無論欄位的數據類型為何，都會儲存轉換成文字的欄位值。

備註

您可以依名稱或索引查閱欄位。 您可以將域值儲存在物件或 CString 物件中CDBVariant。

如果您已實作大量數據列擷取，則目前的記錄一律會放在數據列集中的第一筆記錄上。 GetFieldValue若要在指定資料列集內的記錄上使用，您必須先呼叫SetRowsetCursorPosition成員函式，將游標移至該數據列集中所需的數據列。 然後呼叫 GetFieldValue 該數據列。 若要實作大量數據列擷取，您必須在成員函式中Open指定 CRecordset::useMultiRowFetch 參數的選項dwOptions。

您可以使用 GetFieldValue 在運行時間動態擷取欄位，而不是在設計時間以靜態方式系結字段。 例如，如果您已直接從 CRecordset宣告 recordset 物件，則必須使用 GetFieldValue 來擷取欄位數據;記錄欄位交換 （RFX）， 或大量記錄欄位交換 （Bulk RFX），則不會實作。

注意

如果您宣告記錄集物件而不衍生自 CRecordset，則不會載入 ODBC 資料指標連結庫。 數據指標連結庫要求記錄集至少有一個系結數據行;不過，當您直接使用 CRecordset 時，不會系結任何數據行。 成員函式 CDatabase::OpenEx ，並 CDatabase::Open 控制是否要載入數據指標連結庫。

GetFieldValue 會呼叫 ODBC API 函式 SQLGetData。 如果您的驅動程式針對域值的實際長度輸出值SQL_NO_TOTAL， GetFieldValue 則會擲回例外狀況。 如需 的詳細資訊 SQLGetData，請參閱 Windows SDK。

範例

下列範例程式代碼說明直接從 CRecordset宣告之 recordset 物件的呼叫GetFieldValue。

// Create and open a database object;
// do not load the cursor library
CDatabase db;
db.OpenEx(NULL, CDatabase::forceOdbcDialog);

// Create and open a recordset object
// directly from CRecordset. Note that a
// table must exist in a connected database.
// Use forwardOnly type recordset for best
// performance, since only MoveNext is required
CRecordset rs(&db);
rs.Open(CRecordset::forwardOnly, _T("SELECT * FROM Customer"));

// Create a CDBVariant object to
// store field data
CDBVariant varValue;

// Loop through the recordset,
// using GetFieldValue and
// GetODBCFieldCount to retrieve
// data in all columns
short nFields = rs.GetODBCFieldCount();
while (!rs.IsEOF())
{
   for (short index = 0; index < nFields; index++)
   {
      rs.GetFieldValue(index, varValue);
      // do something with varValue
   }
   rs.MoveNext();
}

rs.Close();
db.Close();

注意

不同於 DAO 類別 CDaoRecordset， CRecordset 沒有 SetFieldValue 成員函式。 如果您直接從 CRecordset建立物件，它實際上是唯讀的。

如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

CRecordset::GetODBCFieldCount

擷取記錄集物件中的欄位總數。

short GetODBCFieldCount() const;

傳回值

記錄集中的欄位數目。

備註

如需建立記錄集的詳細資訊，請參閱 Recordset：Create and Closing Recordsets （ODBC）。

CRecordset::GetODBCFieldInfo

取得記錄集中欄位的相關信息。

void GetODBCFieldInfo(
    LPCTSTR lpszName,
    CODBCFieldInfo& fieldinfo);

void GetODBCFieldInfo(
    short nIndex,
    CODBCFieldInfo& fieldinfo);

參數

lpszName
功能變數名稱。

fieldinfo
結構的 CODBCFieldInfo 參考。

nIndex
欄位以零起始的索引。

備註

函式的一個版本可讓您依名稱查閱欄位。 另一個版本可讓您依索引查閱欄位。

如需傳回之資訊的描述，請參閱 CODBCFieldInfo 結構。

如需建立記錄集的詳細資訊，請參閱 Recordset：Create and Closing Recordsets （ODBC）。

CRecordset::GetRecordCount

決定記錄集的大小。

long GetRecordCount() const;

傳回值

記錄集中的記錄數目;如果記錄集不包含任何記錄，則為 0;如果無法判斷記錄計數，則為 -1。

備註

警告

記錄計數會維持為「高水位」，這是使用者透過記錄移動時的最高編號記錄。 只有在用戶超過最後一筆記錄之後，才會知道記錄總數。 基於效能考慮，呼叫 MoveLast時不會更新計數。 若要自行計算記錄，請重複呼叫 MoveNext ，直到 IsEOF 傳回非零為止。 透過 CRecordset:AddNew 新增記錄並 Update 增加計數;透過刪除記錄 CRecordset::Delete 會減少計數。

CRecordset::GetRowsetSize

取得您想要在指定擷取期間擷取之數據列數目的目前設定。

DWORD GetRowsetSize() const;

傳回值

在指定擷取期間所要擷取的數據列數目。

備註

如果您使用大量數據列擷取，則開啟記錄集時的預設數據列集大小為 25;否則為 1。

若要實作大量數據列擷取，您必須在成員函式的 Open 參數中dwOptions指定 CRecordset::useMultiRowFetch 選項。 若要變更資料列集大小的設定，請呼叫 SetRowsetSize。

如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

CRecordset::GetRowsFetched

決定擷取之後擷取的記錄數目。

DWORD GetRowsFetched() const;

傳回值

在指定的擷取之後，從數據源擷取的數據列數目。

備註

當您實作大量數據列擷取時，這會很有用。 數據列集大小通常表示從擷取擷取的數據列數目。 不過，記錄集中的數據列總數也會影響數據列集中擷取的數據列數目。 例如，如果您的記錄集有10筆記錄，且數據列集大小設定為4筆，則呼叫 MoveNext 來循環記錄集會導致最後一個數據列集只有兩筆記錄。

若要實作大量數據列擷取，您必須在成員函式的 Open dwOptions 參數中指定 CRecordset::useMultiRowFetch 選項。 若要指定數據列集大小，請呼叫 SetRowsetSize。

如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

範例

CMultiCustomer rs(&m_dbCust);

// Set the rowset size
rs.SetRowsetSize(5);

// Open the recordset
rs.Open(CRecordset::dynaset, NULL, CRecordset::useMultiRowFetch);

// loop through the recordset by rowsets
while (!rs.IsEOF())
{
   for (int rowCount = 0; rowCount < (int)rs.GetRowsFetched(); rowCount++)
   {
      // do something
   }

   rs.MoveNext();
}

rs.Close();

CRecordset::GetRowStatus

取得目前數據列集中數據列的狀態。

WORD GetRowStatus(WORD wRow) const;

參數

wRow
數據列在目前數據列集中的單一位置。 這個值的範圍可以從 1 到數據列集的大小。

傳回值

數據列的狀態值。 如需詳細資料，請參閱＜備註＞。

備註

GetRowStatus 傳回值，這個值表示上次從數據源擷取數據列之後的狀態任何變更，或未擷取對應至 wRow 的數據列。 下表列出可能的傳回值。

狀態值	描述
SQL_ROW_SUCCESS	數據列未變更。
SQL_ROW_UPDATED	數據列已更新。
SQL_ROW_DELETED	數據列已刪除。
SQL_ROW_ADDED	已新增數據列。
SQL_ROW_ERROR	因為發生錯誤，所以無法復原數據列。
SQL_ROW_NOROW	沒有資料欄對應至 wRow。

如需詳細資訊，請參閱 Windows SDK 中的 ODBC API 函 SQLExtendedFetch 式。

CRecordset::GetStatus

判斷記錄集中目前記錄的索引，以及是否已看到最後一筆記錄。

void GetStatus(CRecordsetStatus& rStatus) const;

參數

rStatus
對 CRecordsetStatus 物件的參考。 如需詳細資訊，請參閱備註。

備註

CRecordset 嘗試追蹤索引，但在某些情況下，這可能無法進行。 如需說明，請參閱 GetRecordCount 。

結構 CRecordsetStatus 的格式如下：

struct CRecordsetStatus
{
    long m_lCurrentRecord;
    BOOL m_bRecordCountFinal;
};

的 CRecordsetStatus 兩個成員具有下列意義：

• m_lCurrentRecord 如果已知，則包含記錄集中目前記錄之以零起始的索引。 如果無法判斷索引，這個成員會包含 AFX_CURRENT_RECORD_UNDEFINED （-2）。 如果 IsBOF 為 TRUE （空白記錄集或嘗試在第一筆記錄之前捲動），則會 m_lCurrentRecord 設定為 AFX_CURRENT_RECORD_BOF （-1）。 如果在第一筆記錄上，則會將它設定為0、第二筆記錄1等等。

• m_bRecordCountFinal 如果已判斷記錄集中的記錄總數，則為非零。 一般而言，必須從記錄集的開頭開始，呼叫 MoveNext 直到 IsEOF 傳回非零為止， 才能完成此作業。 如果這個成員為零，則傳回的 GetRecordCount記錄計數，如果不是 -1，則只是記錄的「高水印」計數。

CRecordset::GetSQL

呼叫這個成員函式，以取得 SQL 語句，該語句用於在開啟記錄集時選取記錄集的記錄。

const CString& GetSQL() const;

傳回值

const包含 SQL 語句的 參考CString。

備註

這通常是 SQL SELECT 語句。 所 GetSQL 傳回的字串是唯讀的。

所 GetSQL 傳回的字串通常不同於您可能傳遞至 參數中 lpszSQL 記錄集的任何字串至 Open 成員函式。 這是因為記錄集會根據您傳遞至 Open的專案、使用 指定的ClassWizard專案、在 和 m_strSort 數據成員中指定的m_strFilter專案，以及您可能已指定的任何參數，來建構完整的SQL語句。 如需記錄集如何建構此 SQL 語句的詳細資訊，請參閱 記錄集：記錄集如何選取記錄 （ODBC） 。

注意

只有在呼叫 之後，才呼叫 Open這個成員函式。

CRecordset::GetTableName

取得記錄集查詢所依據之 SQL 資料表的名稱。

const CString& GetTableName() const;

傳回值

const如果記錄集是以數據表為基礎，則為包含數據表名稱的參考CString，否則為空字串。

備註

GetTableName 只有在記錄集是以數據表為基礎，而不是多個數據表的聯結或預先定義的查詢（預存程式）時才有效。 名稱是唯讀的。

注意

只有在呼叫 之後，才呼叫 Open這個成員函式。

CRecordset::IsBOF

如果記錄集位於第一筆記錄之前，則傳回非零。 沒有目前的記錄。

BOOL IsBOF() const;

傳回值

如果記錄集未包含任何記錄，或在第一筆記錄之前向後捲動，則為非零;否則為 0。

備註

從記錄卷動到記錄之前，請先呼叫這個成員函式，以瞭解您是否在記錄集的第一筆記錄之前離開。 您也可以搭配IsEOF使用 IsBOF 來判斷記錄集是否包含任何記錄或空白。 在您呼叫 Open之後，如果記錄集不包含任何記錄， IsBOF 則傳回非零。 當您開啟至少有一筆記錄的記錄集時，第一筆記錄是當前記錄，並 IsBOF 傳回 0。

如果第一筆記錄是當前記錄，而您呼叫 MovePrev， IsBOF 將會傳回非零。 如果 IsBOF 傳回非零，而且您呼叫 MovePrev，就會發生錯誤。 如果 IsBOF 傳回非零，則目前的記錄未定義，而且任何需要當前記錄的動作都會導致錯誤。

範例

此範例會使用 IsBOF 和 IsEOF 來偵測記錄集的限制，因為程式代碼會雙向卷動記錄集。

// Open a recordset; first record is current
// Open a recordset; first record is current
CCustomer rsCustSet(&m_dbCust);
rsCustSet.Open();

if(rsCustSet.IsBOF())
   return;
   // The recordset is empty

// Scroll to the end of the recordset, past
// the last record, so no record is current
while (!rsCustSet.IsEOF())
   rsCustSet.MoveNext();

// Move to the last record
rsCustSet.MoveLast();

// Scroll to beginning of the recordset, before
// the first record, so no record is current
while(!rsCustSet.IsBOF())
   rsCustSet.MovePrev();

// First record is current again
rsCustSet.MoveFirst();

CRecordset::IsDeleted

判斷目前的記錄是否已刪除。

BOOL IsDeleted() const;

傳回值

如果記錄集位於已刪除的記錄上，則為非零;否則為 0。

備註

如果您捲動至記錄並 IsDeleted 傳回 TRUE （非零），則必須先捲動至另一筆記錄，才能執行任何其他記錄集作業。

的結果 IsDeleted 取決於許多因素，例如您的記錄集類型、您的記錄集是否可更新、您是否在開啟記錄集時指定 CRecordset::skipDeletedRecords 選項、驅動程式是否封裝已刪除的記錄，以及是否有多個使用者。

如需和 驅動程式封裝的詳細資訊 CRecordset::skipDeletedRecords ，請參閱 Open 成員函式。

注意

如果您已實作大量資料列擷取，則不應該呼叫 IsDeleted。 請改為呼叫 GetRowStatus 成員函式。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

CRecordset::IsEOF

如果記錄集位於最後一筆記錄之後，則傳回非零。 沒有目前的記錄。

BOOL IsEOF() const;

傳回值

如果記錄集未包含任何記錄，或已捲動超過最後一筆記錄，則為非零;否則為 0。

備註

當您從記錄卷動至記錄時呼叫此成員函式，以瞭解您是否已超過記錄集的最後一筆記錄。 您也可以使用 IsEOF 來判斷記錄集是否包含任何記錄或空白。 在您呼叫 Open之後，如果記錄集不包含任何記錄， IsEOF 則傳回非零。 當您開啟至少有一筆記錄的記錄集時，第一筆記錄是當前記錄，並 IsEOF 傳回 0。

如果您呼叫 MoveNext時，最後一筆記錄是當前記錄， IsEOF 將會傳回非零。 如果 IsEOF 傳回非零，而且您呼叫 MoveNext，就會發生錯誤。 如果 IsEOF 傳回非零，則目前的記錄未定義，而且任何需要當前記錄的動作都會導致錯誤。

範例

請參閱 IsBOF 的範例。

CRecordset::IsFieldDirty

判斷指定的欄位數據成員自呼叫之後EditAddNew是否已變更。

BOOL IsFieldDirty(void* pv);

參數

pv
您要檢查其狀態的欄位資料成員指標，或 NULL 判斷是否有任何欄位已變更。

傳回值

如果指定的欄位數據成員自呼叫 AddNew 或 Edit之後已變更，則為非零，否則為 0。

備註

當對 成員CRecordset函式的呼叫Update更新目前記錄時，所有髒字段數據成員中的數據都會傳送至數據源上的記錄（在呼叫 Edit 或 AddNew之後）。

注意

此成員函式不適用於使用大量數據列擷取的記錄集。 如果您已實作大量數據列擷取，則 IsFieldDirty 一律會傳回 FALSE，並會導致判斷提示失敗。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

呼叫 IsFieldDirty 會重設先前對 SetFieldDirty 的呼叫效果，因為重新評估欄位的骯髒狀態。 在此情況下 AddNew ，如果目前的域值與虛擬 Null 值不同，則會設定欄位狀態。 在此情況下 Edit ，如果域值與快取的值不同，則會設定欄位狀態。

IsFieldDirty 是透過實作 DoFieldExchange。

如需有關髒旗標的詳細資訊，請參閱 記錄集：記錄集如何選取記錄 （ODBC） 。

CRecordset::IsFieldNull

如果目前記錄中指定的欄位為 Null，則傳回非零值（沒有值）。

BOOL IsFieldNull(void* pv);

參數

pv
您要檢查其狀態的欄位資料成員指標，或 NULL 判斷任何欄位是否為 Null。

傳回值

如果指定的欄位數據成員標示為 Null，則為非零;否則為 0。

備註

呼叫這個成員函式，以判斷記錄集的指定字段數據成員是否已標示為 Null。 （在資料庫術語中，Null 表示「沒有值」，而且與C++中 NULL 不同。如果字段數據成員標示為 Null，則會解譯為沒有值之目前記錄的數據行。

注意

此成員函式不適用於使用大量數據列擷取的記錄集。 如果您已實作大量數據列擷取，則 IsFieldNull 一律會傳回 FALSE ，並會導致判斷提示失敗。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

IsFieldNull 是透過實作 DoFieldExchange。

CRecordset::IsFieldNullable

如果目前記錄中指定的欄位可以設定為 Null，則傳回非零值。

BOOL IsFieldNullable(void* pv);

參數

pv
您要檢查其狀態的欄位數據成員指標，或 NULL 判斷是否有任何欄位可以設定為 Null 值。

備註

呼叫這個成員函式，以判斷指定的欄位數據成員是否為 「可為 Null」（可以設定為 Null 值;C++ NULL 與 Null 不同，這在資料庫術語中表示「沒有值」。

注意

如果您已實作大量資料列擷取，則無法呼叫 IsFieldNullable。 請改為呼叫 GetODBCFieldInfo 成員函式，以判斷字段是否可以設定為 Null 值。 不論是否已實作大量資料列擷取，您都可以呼叫 GetODBCFieldInfo。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

不能為 Null 的欄位必須有值。 如果您在新增或更新記錄時嘗試將這類字段設定為 Null，數據源會拒絕新增或更新，並 Update 擲回例外狀況。 當您呼叫 Update時，而不是呼叫 SetFieldNull時，就會發生例外狀況。

針對 NULL 函式的第一個自變數使用 ，只會將函式套用至 outputColumn 字段，而不是 param 字段。 例如，呼叫

SetFieldNull(NULL);

只會 outputColumn 將欄位設定為 NULL; param 欄位將不會受到影響。

若要處理 param 欄位，您必須提供您要處理之個人 param 的實際位址，例如：

SetFieldNull(&m_strParam);

這表示您無法將所有欄位設定 param 為 NULL，因為您可以使用 outputColumn 欄位。

IsFieldNullable 是透過 DoFieldExchange 實作。

CRecordset::IsOpen

判斷記錄集是否已開啟。

BOOL IsOpen() const;

傳回值

如果先前已呼叫 recordset 物件的 Open 或 Requery 成員函式且記錄集尚未關閉，則為非零;否則為 0。

CRecordset::m_hstmt

包含與記錄集相關聯之 ODBC 語句資料結構的句柄，類型 HSTMT為 。

備註

ODBC 數據源的每個查詢都會與 HSTMT相關聯。

警告

通話之前Open請勿使用 m_hstmt 。

通常您不需要直接存取 HSTMT ，但您可能需要直接執行 SQL 語句。 類別 ExecuteSQL 的成員 CDatabase 函式提供使用 m_hstmt的範例。

CRecordset::m_nFields

包含記錄集類別中的欄位資料成員數目;也就是說，記錄集從數據源選取的數據行數目。

備註

記錄集類別的建構函式必須以正確的數位初始化 m_nFields 。 如果您尚未實作大量數據列擷取， ClassWizard 請在使用它來宣告記錄集類別時，為您撰寫此初始化。 您也可以手動撰寫。

架構會使用此數位來管理字段數據成員與數據源上目前記錄的對應數據行之間的互動。

警告

這個數字必須對應至 使用 參數 CFieldExchange::outputColumn呼叫SetFieldType之後DoFieldExchangeDoBulkFieldExchange所註冊的「輸出數據行」數目。

您可以動態系結數據行，如「記錄集：動態系結數據行」一文所述。如果您這樣做，您必須增加 中的 m_nFields 計數，以反映動態 DoFieldExchange 綁定數據行之 RFX DoBulkFieldExchange 或成員函式中的 RFX 或大量 RFX 函數調用數目。

如需詳細資訊，請參閱 Recordset：動態系結數據行（ODBC）和記錄集：大量擷取記錄的文章。

範例

請參閱 記錄欄位交換：使用 RFX。

CRecordset::m_nParams

包含記錄集類別中的參數數據成員數目;也就是說，使用記錄集查詢傳遞的參數數目。

備註

如果您的記錄集類別有任何參數數據成員，類別的建構函式必須以正確的數位初始化 m_nParams 。 預設值 m_nParams 為 0。 如果您新增參數數據成員（您必須手動執行），您也必須在類別建構函式中手動新增初始化，以反映參數數目（這至少必須和或m_strFilterm_strSort字串中的 '' 佔位元數目一樣大）。

架構會在參數化記錄集的查詢時使用此數位。

警告

這個數字必須對應至 中DoFieldExchange或DoBulkFieldExchange呼叫 SetFieldType 之後所註冊的 「params」 數目，且參數值為 CFieldExchange::inputParam、 CFieldExchange::paramCFieldExchange::outputParam或 CFieldExchange::inoutParam。

範例

請參閱 Recordset：參數化 Recordset （ODBC） 和 Record Field Exchange：Using RFX 文章。

CRecordset::m_pDatabase

包含物件指標， CDatabase 記錄集透過該對象連接到數據源。

備註

此變數會以兩種方式設定。 一般而言，當您建構 recordset 物件時，會將指標傳遞至已經連接的 CDatabase 物件。 如果您改為傳遞 NULL ， CRecordset 請為您建立 CDatabase 物件並加以連接。 在這兩種情況下， CRecordset 會將指標儲存在此變數中。

通常您不需要直接使用儲存在 中的 m_pDatabase指標。 不過，如果您將自己的延伸模組寫入 ， CRecordset您可能需要使用指標。 例如，如果您擲回自己的 CDBException，您可能需要指標。 或者，如果您需要使用相同 CDatabase 對象執行某些動作，例如執行交易、設定逾時，或呼叫 ExecuteSQL 類別 CDatabase 的成員函式來直接執行 SQL 語句，您可能需要它。

CRecordset::m_strFilter

建構 recordset 物件之後，但在呼叫其 Open 成員函式之前，請使用這個資料成員來儲存 CString 包含 SQL WHERE 子句的 。

備註

記錄集會使用此字串來限制在 或 Requery 呼叫期間選取的Open記錄（或篩選）。 這適用於選取記錄的子集，例如「所有以加州為基礎的銷售人員」（“state = CA”）。 子句的 WHERE ODBC SQL 語法為

WHERE search-condition

請勿在 WHERE 字串中包含 關鍵詞。 架構會提供它。

您也可以在篩選字串中放置 '' 佔位元、針對每個佔位元元宣告類別中的參數數據成員，以及在運行時間將參數傳遞至記錄集，以參數化。 這可讓您在執行時間建構篩選。 如需詳細資訊，請參閱 Recordset：參數化 Recordset （ODBC）。

如需 SQL WHERE 子句的詳細資訊，請參閱 SQL。 如您選取與篩選紀錄的詳細資訊，請參閱 記錄集：篩選記錄 （ODBC） 。

範例

CCustomer rsCustSet(&m_dbCust);

// Set the filter
rsCustSet.m_strFilter = _T("L_Name = 'Flanders'");

// Run the filtered query
rsCustSet.Open(CRecordset::snapshot, _T("Customer"));

CRecordset::m_strSort

建構 recordset 物件之後，但在呼叫其 Open 成員函式之前，請使用這個資料成員來儲存 CString 包含 SQL ORDER BY 子句的 。

備註

記錄集會使用此字串來排序它在 或 Requery 呼叫期間Open選取的記錄。 您可以使用此功能來排序一個或多個資料行上的記錄集。 子句的 ORDER BY ODBC SQL 語法為

ORDER BY sort-specification [, sort-specification]...

其中排序規格是整數或數據行名稱。 您也可以將 「ASC」 或 「DESC」 附加至排序字串中的數據行清單，以指定遞增或遞減順序（順序預設為遞增）。 選取的記錄會先依列出的第一個數據行排序，再依第二個數據行排序，依此類排序。 例如，您可以依姓氏排序「客戶」記錄集，然後依名字排序。 您可以列出的數據行數目取決於數據來源。 如需詳細資訊，請參閱 Windows SDK。

請勿在 ORDER BY 字串中包含 關鍵詞。 架構會提供它。

如需 SQL 子句的詳細資訊，請參閱 SQL。 如需排序記錄的詳細資訊，請參閱 記錄集：排序記錄 （ODBC） 。

範例

CCustomer rsCustSet(&m_dbCust);

// Set the sort string
rsCustSet.m_strSort = _T("L_Name, ContactFirstName");

// Run the sorted query
rsCustSet.Open(CRecordset::snapshot, _T("Customer"));

CRecordset::Move

將記錄集中目前的記錄指標往前或向後移動。

virtual void Move(
    long nRows,
    WORD wFetchType = SQL_FETCH_RELATIVE);

參數

nRows
向前或向後移動的數據列數目。 正值向前移動，朝記錄集結尾。 負值向後移動，朝開頭移動。

wFetchType
決定要擷取的數據列集 Move 。 如需詳細資料，請參閱＜備註＞。

備註

如果您針對 傳遞值為 0nRows，Move則會重新整理目前的記錄;Move將會結束任何目前AddNew或Edit模式，並在呼叫 或 Edit 之前AddNew還原當前記錄的值。

注意

當您移動記錄集時，無法略過已刪除的記錄。 如需相關資訊，請參閱 CRecordset::IsDeleted 。 當您以選項集開啟 CRecordset skipDeletedRecords 時， Move 判斷 nRows 提示 參數是否為 0。 此行為可防止使用相同數據的其他用戶端應用程式刪除的數據列重新整理。 如需 的描述skipDeletedRecords，dwOption請參閱 中的 Open 參數。

Move 依數據列集重新定位記錄集。 根據 和wFetchType的值nRows，Move擷取適當的數據列集，然後將該數據列集中的第一筆記錄變成目前記錄。 如果您尚未實作大量數據列擷取，則數據列集大小一律為 1。 擷取數據列集時， Move 直接呼叫 CheckRowsetError 成員函式來處理擷取所產生的任何錯誤。

視您傳遞的值而定， Move 相當於其他 CRecordset 成員函式。 特別是的值 wFetchType 可能表示成員函式更直覺，而且通常是移動目前記錄的慣用方法。

下表列出的可能值wFetchType、根據 和nRows擷取wFetchType的數據列集Move，以及對應至wFetchType的任何對等成員函式。

wFetchType	擷取的數據列集	對等成員函式
SQL_FETCH_RELATIVE （預設值）	目前數據列集中第一個數據列的起始 nRows 數據列集。
SQL_FETCH_NEXT	下一個數據列集; nRows 會忽略 。	MoveNext
SQL_FETCH_PRIOR	上一個數據列集; nRows 會忽略 。	MovePrev
SQL_FETCH_FIRST	記錄集中的第一個數據列集; nRows 會忽略 。	MoveFirst
SQL_FETCH_LAST	記錄集中的最後一個完整數據列集; nRows 會忽略 。	MoveLast
SQL_FETCH_ABSOLUTE	如果 nRows> 為 0，則數據列集會從記錄集的開頭開始 nRows 數據列集。 如果 nRows< 為 0，則從記錄集結尾開始數據 nRows 列集的數據列集。 如果 nRows = 0，則會傳回檔案開頭 （BOF） 條件。	SetAbsolutePosition
SQL_FETCH_BOOKMARK	從書籤值對應至 nRows的數據列開始的數據列集。	SetBookmark

注意

若為正向記錄集， Move 則只有在的值 SQL_FETCH_NEXT 為 wFetchType時才有效。

警告

如果記錄集沒有記錄，則呼叫 Move 會擲回例外狀況。 若要判斷記錄集是否有任何記錄，請呼叫 IsBOF 和 IsEOF。

注意

如果您已捲動至記錄集的開頭或結尾（IsBOF 或 IsEOF 傳回非零），則呼叫函 Move 式可能會擲回 CDBException。 例如，如果 IsEOF 傳回非零且 IsBOF 未傳回 ，則會 MoveNext 擲回例外狀況，但 MovePrev 不會擲回。

注意

如果您在正在更新或新增當前記錄時呼叫 Move ，則更新會遺失而不發出警告。

如需記錄集導覽的詳細資訊，請參閱 Recordset：Scrolling （ODBC） 和 Recordset： Bookmarks and Absolute Positions （ODBC） 文章。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。 如需相關信息，請參閱 Windows SDK 中的 ODBC API 函式 SQLExtendedFetch 。

範例

// rs is a CRecordset or a CRecordset-derived object

// Change the rowset size to 5
rs.SetRowsetSize(5);

// Open the recordset
rs.Open(CRecordset::dynaset, NULL, CRecordset::useMultiRowFetch);

// Move to the first record in the recordset
rs.MoveFirst();

// Move to the sixth record
rs.Move(5);
// Other equivalent ways to move to the sixth record:
rs.Move(6, SQL_FETCH_ABSOLUTE);
rs.SetAbsolutePosition(6);
// In this case, the sixth record is the first record in the next rowset,
// so the following are also equivalent:
rs.MoveFirst();
rs.Move(1, SQL_FETCH_NEXT);

rs.MoveFirst();
rs.MoveNext();

CRecordset::MoveFirst

讓第一個數據列集中的第一筆記錄成為當前記錄。

void MoveFirst();

備註

不論是否已實作大量數據列擷取，這一律會是記錄集中的第一筆記錄。

開啟記錄集之後，您不需要立即呼叫 MoveFirst 。 當時，第一筆記錄（如果有的話）會自動是當前記錄。

注意

此成員函式對正向記錄集無效。

注意

當您移動記錄集時，無法略過已刪除的記錄。 如需詳細資訊， IsDeleted 請參閱成員函式。

警告

如果記錄集沒有記錄，則呼叫任何 Move 函式會擲回例外狀況。 若要判斷記錄集是否有任何記錄，請呼叫 IsBOF 和 IsEOF。

注意

如果您在目前記錄更新或新增時呼叫任何 Move 函式，更新就會遺失，而不會發出警告。

如需記錄集導覽的詳細資訊，請參閱 Recordset：Scrolling （ODBC） 和 Recordset： Bookmarks and Absolute Positions （ODBC） 文章。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

範例

請參閱 IsBOF 的範例。

CRecordset::MoveLast

使最後一個完整數據列集中的第一筆記錄成為當前記錄。

void MoveLast();

備註

如果您尚未實作大量數據列擷取，則記錄集的大小為1，因此 MoveLast 會移至記錄集中的最後一筆記錄。

注意

此成員函式對正向記錄集無效。

注意

當您移動記錄集時，無法略過已刪除的記錄。 如需詳細資訊， IsDeleted 請參閱成員函式。

警告

如果記錄集沒有記錄，則呼叫任何 Move 函式會擲回例外狀況。 若要判斷記錄集是否有任何記錄，請呼叫 IsBOF 和 IsEOF。

注意

如果您在目前記錄更新或新增時呼叫任何 Move 函式，更新就會遺失，而不會發出警告。

如需記錄集導覽的詳細資訊，請參閱 Recordset：Scrolling （ODBC） 和 Recordset： Bookmarks and Absolute Positions （ODBC） 文章。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

範例

請參閱 IsBOF 的範例。

CRecordset::MoveNext

讓下一個數據列集中的第一筆記錄成為當前記錄。

void MoveNext();

備註

如果您尚未實作大量數據列擷取，則記錄集的大小為1，因此 MoveNext 請移至下一筆記錄。

注意

當您移動記錄集時，無法略過已刪除的記錄。 如需詳細資訊， IsDeleted 請參閱成員函式。

警告

如果記錄集沒有記錄，則呼叫任何 Move 函式會擲回例外狀況。 若要判斷記錄集是否有任何記錄，請呼叫 IsBOF 和 IsEOF。

注意

此外，建議您先呼叫 IsEOF ，再呼叫 MoveNext。 例如，如果您已捲動超過記錄集結尾， IsEOF 將會傳回非零;後續呼叫 MoveNext 會擲回例外狀況。

注意

如果您在目前記錄更新或新增時呼叫任何 Move 函式，更新就會遺失，而不會發出警告。

如需記錄集導覽的詳細資訊，請參閱 Recordset：Scrolling （ODBC） 和 Recordset： Bookmarks and Absolute Positions （ODBC） 文章。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

範例

請參閱 IsBOF 的範例。

CRecordset::MovePrev

讓上一個數據列集中的第一筆記錄成為當前記錄。

void MovePrev();

備註

如果您尚未實作大量數據列擷取，則記錄集的大小為1，因此 MovePrev 請移至上一筆記錄。

注意

此成員函式對正向記錄集無效。

注意

當您移動記錄集時，無法略過已刪除的記錄。 如需詳細資訊， IsDeleted 請參閱成員函式。

警告

如果記錄集沒有記錄，則呼叫任何 Move 函式會擲回例外狀況。 若要判斷記錄集是否有任何記錄，請呼叫 IsBOF 和 IsEOF。

注意

此外，建議您先呼叫 IsBOF ，再呼叫 MovePrev。 例如，如果您已在記錄集開頭之前捲動， IsBOF 將會傳回非零;後續呼叫 MovePrev 會擲回例外狀況。

注意

如果您在目前記錄更新或新增時呼叫任何 Move 函式，更新就會遺失，而不會發出警告。

如需記錄集導覽的詳細資訊，請參閱 Recordset：Scrolling （ODBC） 和 Recordset： Bookmarks and Absolute Positions （ODBC） 文章。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

範例

請參閱 IsBOF 的範例。

CRecordset::OnSetOptions

呼叫 以設定指定 ODBC 語句的選項（用於選取範圍）。

virtual void OnSetOptions(HSTMT hstmt);

參數

hstmt
HSTMT要設定其選項之 ODBC 語句的 。

備註

呼叫 OnSetOptions 以設定指定之 ODBC 語句的選項（用於選取範圍）。 架構會呼叫這個成員函式來設定記錄集的初始選項。 OnSetOptions 會決定數據源對可捲動數據指標的支援，以及針對數據指標並行，並據以設定記錄集的選項。 （而 OnSetOptions 用於選取作業， OnSetUpdateOptions 則用於更新作業。

覆寫 OnSetOptions 以設定驅動程式或數據源特定的選項。 例如，如果您的數據源支援開啟獨佔存取權，您可以覆寫 OnSetOptions 以利用該功能。

如需數據指標的詳細資訊，請參閱 ODBC。

CRecordset::OnSetUpdateOptions

呼叫 以設定指定 ODBC 語句的選項（用於更新）。

virtual void OnSetUpdateOptions(HSTMT hstmt);

參數

hstmt
HSTMT要設定其選項之 ODBC 語句的 。

備註

呼叫 OnSetUpdateOptions 以設定指定 ODBC 語句的選項（用於更新）。 架構會在建立 HSTMT 之後呼叫這個成員函式，以更新記錄集中的記錄。 （雖然 OnSetOptions 用於選取作業， OnSetUpdateOptions 但用於更新作業。） OnSetUpdateOptions 會決定數據源對可捲動數據指標的支援，以及針對數據指標並行，並據以設定記錄集的選項。

覆寫 OnSetUpdateOptions 以設定 ODBC 語句的選項，再使用該語句來存取資料庫。

如需數據指標的詳細資訊，請參閱 ODBC。

CRecordset::Open

藉由擷取數據表或執行記錄集所代表的查詢，開啟記錄集。

virtual BOOL Open(
    UINT nOpenType = AFX_DB_USE_DEFAULT_TYPE,
    LPCTSTR lpszSQL = NULL,
    DWORD dwOptions = none);

參數

nOpenType
接受預設值 ， AFX_DB_USE_DEFAULT_TYPE或使用 下列其中一個來自 enum OpenType的值：

• CRecordset::dynaset 具有雙向卷動的記錄集。 開啟記錄集會決定記錄的成員資格和順序，但其他使用者對數據值所做的變更會在擷取作業之後顯示。 動態集也稱為索引鍵集驅動記錄集。

• CRecordset::snapshot 具有雙向卷動的靜態記錄集。 開啟記錄集會決定記錄的成員資格和順序。 擷取記錄會決定數據值。 在記錄集關閉后重新開啟之前，其他使用者所做的變更不會顯示。

• CRecordset::dynamic 具有雙向卷動的記錄集。 其他使用者對成員資格、排序和數據值所做的變更，會在擷取作業之後顯示。 許多 ODBC 驅動程式不支援這種類型的記錄集。

• CRecordset::forwardOnly 只讀記錄集，僅向前捲動。

  針對 CRecordset預設值為 CRecordset::snapshot。 默認值機制可讓 Visual C++ 精靈與 ODBC CRecordset 和 DAO CDaoRecordset互動，其具有不同的預設值。

如需這些記錄集類型的詳細資訊，請參閱 Recordset （ODBC）。 如需相關信息，請參閱 Windows SDK 中的。

警告

如果不支援要求的型別，架構會擲回例外狀況。

lpszSQL
包含下列其中一項的字串指標：

• NULL指標。

• 資料表的名稱。

• SQL SELECT 語句（選擇性地使用 SQL WHERE 或 ORDER BY 子句）。

• CALL指定預先定義查詢名稱的語句（預存程式）。 請小心不要在大括弧與 CALL 關鍵詞之間插入空格符。

如需此字串的詳細資訊，請參閱<備註>一節下 ClassWizard 角色的數據表和討論。

注意

結果集中數據行的順序必須符合或DoBulkFieldExchange函式覆寫中 DoFieldExchange RFX 或大量 RFX 函數呼叫的順序。

dwOptions
位掩碼，可以指定下列值的組合。 其中一些是互斥的。 預設值是 none。

• CRecordset::none 未設定任何選項。 此參數值與其他所有值互斥。 根據預設，記錄集可以使用 或 Delete 更新Edit，並允許使用 AddNew來附加新的記錄。 可更新性取決於數據源和 nOpenType 您指定的選項。 大量新增的優化無法使用。 不會實作大量數據列擷取。 刪除的記錄將不會在記錄集瀏覽期間略過。 無法使用書籤。 已實作自動髒欄位檢查。

• CRecordset::appendOnly 不允許 Edit 或 Delete 記錄集上。 僅允許 AddNew 。 此選項與 CRecordset::readOnly互斥。

• CRecordset::readOnly 以唯讀模式開啟記錄集。 此選項與 CRecordset::appendOnly互斥。

• CRecordset::optimizeBulkAdd 使用備妥的 SQL 語句，一次優化新增許多記錄。 只有在您未使用 ODBC API 函 SQLSetPos 式來更新記錄集時，才適用 。 第一次更新會決定哪些欄位標示為已變更。 此選項與 CRecordset::useMultiRowFetch互斥。

• CRecordset::useMultiRowFetch 實作大量數據列擷取，以允許在單一擷取作業中擷取多個數據列。 這是專為改善效能而設計的進階功能;不過，不支援大量記錄欄位交換 ClassWizard。 此選項與 CRecordset::optimizeBulkAdd互斥。 如果您指定 CRecordset::useMultiRowFetch，則選項 CRecordset::noDirtyFieldCheck 會自動開啟（雙緩衝將無法使用）：在僅轉寄的記錄集上，選項 CRecordset::useExtendedFetch 將會自動開啟。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

• CRecordset::skipDeletedRecords 瀏覽記錄集時，略過所有已刪除的記錄。 這會降低特定相對擷取的效能。 此選項在僅限轉寄記錄集上無效。 如果您使用 Move nRows 參數設定為 0 且 CRecordset::skipDeletedRecords 選項集呼叫， Move 將會判斷提示。 CRecordset::skipDeletedRecords 類似於 驅動程式封裝，這表示已刪除的數據列會從記錄集移除。 不過，如果您的驅動程式封裝記錄，則只會略過您刪除的記錄;當記錄集開啟時，它不會略過其他使用者刪除的記錄。 CRecordset::skipDeletedRecords 將會略過其他使用者刪除的數據列。

• CRecordset::useBookmarks 如果支援，可以使用記錄集上的書籤。 書籤會緩慢擷取數據，但改善數據流覽的效能。 在僅轉寄記錄集上無效。 如需詳細資訊，請參閱 記錄集：書籤和絕對位置 （ODBC）。

• CRecordset::noDirtyFieldCheck 關閉自動髒欄位檢查（雙緩衝）。 這將改善效能;不過，您必須藉由呼叫 SetFieldDirty 和 SetFieldNull 成員函式，手動將字段標示為已變更。 類別 CRecordset 中的雙重緩衝類似於 類別 CDaoRecordset中的雙緩衝處理。 不過，在 中 CRecordset，您無法在個別欄位上啟用雙重緩衝;您可以針對所有欄位啟用雙緩衝，或針對所有欄位停用。 如果您指定 選項 CRecordset::useMultiRowFetch，則 CRecordset::noDirtyFieldCheck 會自動開啟 ;不過， SetFieldDirty 而且 SetFieldNull 無法用於實作大量數據列擷取的記錄集。

• CRecordset::executeDirect 請勿使用備妥的 SQL 語句。 為了改善效能，如果永遠不會呼叫成員函式， Requery 請指定此選項。

• CRecordset::useExtendedFetch 實作 SQLExtendedFetch 而非 SQLFetch。 這是針對在正向記錄集上實作大量數據列擷取而設計。 如果您在僅轉寄記錄集上指定 選項 CRecordset::useMultiRowFetch ，則 CRecordset::useExtendedFetch 會自動開啟。

• CRecordset::userAllocMultiRowBuffers 使用者將會為數據配置記憶體緩衝區。 如果您想要設定自己的記憶體，請使用此選項 CRecordset::useMultiRowFetch 。 否則，架構會自動配置必要的記憶體。 如需詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。 指定 CRecordset::userAllocMultiRowBuffers 而不指定 CRecordset::useMultiRowFetch 會導致判斷提示失敗。

傳回值

如果成功開啟物件，則為 CRecordset 非零，否則為 0 如果傳回 0，則 CDatabase::Open 為 。否則為 0。

備註

您必須呼叫這個成員函式，才能執行記錄集所定義的查詢。 呼叫 Open之前，您必須建構 recordset 物件。

此記錄集與數據源的連線取決於您在呼叫 Open之前如何建構記錄集。 如果您將 CDatabase 對象傳遞至尚未連線至數據源的記錄集建構函式，這個成員函式會使用 GetDefaultConnect 來嘗試開啟資料庫物件。 如果您將 NULL 傳遞給記錄集建構函式，建構函式會為您建構 CDatabase 物件，並 Open 嘗試連接資料庫物件。 如需在這些不同情況下關閉記錄集和連線的詳細資料，請參閱 Close。

注意

透過物件存取數據源 CRecordset 一律會共用。 不同於 類別 CDaoRecordset ，您無法使用 CRecordset 對象來開啟具有獨佔存取權的數據源。

當您呼叫 Open時，查詢通常是 SQL SELECT 語句，會根據下表所示的準則來選取記錄。

lpszSQL 參數的值	選取的記錄取決於	範例
NULL	所 GetDefaultSQL傳回的字串。
SQL 資料表名稱	或DoBulkFieldExchange中DoFieldExchange資料表清單的所有數據行。	"Customer"
預先定義的查詢 （預存程式） 名稱	查詢要傳回的數據行。	"{call OverDueAccts}"
SELECT column-list FROM table-list	來自指定數據表的指定數據行。	"SELECT CustId, CustName FROM Customer"

警告

請勿在 SQL 字串中插入額外的空格符。 例如，如果您在大括號和 CALL 關鍵詞之間插入空格符，MFC 會將 SQL 字串誤譯為數據表名稱，並將它併入 SELECT 語句中，這會導致擲回例外狀況。 同樣地，如果您的預先定義查詢使用輸出參數，請勿在大括弧與 '' 符號之間插入空格符。 最後，您不得在語句中的CALL大括弧或 語句中的 SELECT 關鍵詞之前SELECT插入空格符。

一般程式是傳遞 NULL 至 Open，在此情況下，會 Open 呼叫 GetDefaultSQL。 如果您使用衍生 CRecordset 類別， GetDefaultSQL 請提供您在 中指定的 ClassWizard資料表名稱。 您可以改為在 參數中 lpszSQL 指定其他資訊。

無論您傳遞什麼， Open 都會建構查詢的最終 SQL 字串（字串可能會將 SQL WHERE 和 ORDER BY 子句附加至您傳遞的 lpszSQL 字串），然後執行查詢。 您可以在呼叫 之後呼叫 GetSQL Open來檢查建構的字串。 如需記錄集如何建構 SQL 語句及選取記錄的詳細資訊，請參閱記錄集：記錄集如何選取記錄（ODBC）。

記錄集類別的欄位數據成員會系結至所選取資料的數據行。 如果傳回任何記錄，則第一筆記錄會變成當前記錄。

如果您想要設定記錄集的選項，例如篩選或排序，請在建構記錄集物件之後，但在呼叫 Open之前指定這些選項。 如果您要在記錄集開啟之後重新整理記錄集中的記錄，請呼叫 Requery。

如需詳細資訊，包括更多範例，請參閱 Recordset （ODBC）、 Recordset：記錄集如何選取記錄集 （ODBC），以及 記錄集：建立和關閉記錄集 （ODBC） 。

範例

下列程式代碼範例顯示不同形式的 Open 呼叫。

// rsSnap, rsLName, and rsDefault are CRecordset or CRecordset-derived 
// objects

// Open rs using the default SQL statement, implement bookmarks, and turn 
// off automatic dirty field checking
rsSnap.Open(CRecordset::snapshot, NULL, CRecordset::useBookmarks |
   CRecordset::noDirtyFieldCheck);

// Pass a complete SELECT statement and open as a dynaset
rsLName.Open(CRecordset::dynaset, _T("Select L_Name from Customer"));

// Accept all defaults
rsDefault.Open();

CRecordset::RefreshRowset

更新目前數據列集中數據列的數據和狀態。

void RefreshRowset(
    WORD wRow,
    WORD wLockType = SQL_LOCK_NO_CHANGE);

參數

wRow
數據列在目前數據列集中的單一位置。 這個值的範圍可以從零到數據列集的大小。

wLockType
值，指出如何在重新整理數據列之後鎖定數據列。 如需詳細資料，請參閱＜備註＞。

備註

如果您針對 傳遞零 wRow的值，則會重新整理數據列集中的每一個數據列。

若要使用 RefreshRowset，您必須在成員函式中Open指定 CRecordset::useMulitRowFetch 選項，以實作大量數據列擷取。

RefreshRowset 會呼叫 ODBC API 函式 SQLSetPos。 參數 wLockType 會指定執行之後 SQLSetPos 數據列的鎖定狀態。 下表描述的 wLockType可能值。

wLockType	描述
SQL_LOCK_NO_CHANGE （預設值）	驅動程式或數據源可確保數據列處於與呼叫前 RefreshRowset 相同的鎖定或解除鎖定狀態。
SQL_LOCK_EXCLUSIVE	驅動程式或數據源會以獨佔方式鎖定數據列。 並非所有數據源都支援這種類型的鎖定。
SQL_LOCK_UNLOCK	驅動程式或數據源會解除鎖定數據列。 並非所有數據源都支援這種類型的鎖定。

如需 的詳細資訊 SQLSetPos，請參閱 Windows SDK。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

CRecordset::Requery

重建（重新整理）記錄集。

virtual BOOL Requery();

傳回值

如果成功重建記錄集，則為非零;否則為 0。

備註

如果傳回任何記錄，則第一筆記錄會變成當前記錄。

為了讓記錄集反映您或其他使用者對數據源進行的新增和刪除，您必須呼叫 Requery來重建記錄集。 如果記錄集是動態集，它會自動反映您或其他使用者對其現有記錄所做的更新（但不會新增）。 如果記錄集是快照集，您必須呼叫 Requery 以反映其他使用者的編輯和新增和刪除。

針對動態集或快照集， Requery 您可以隨時使用新的篩選或排序或新的參數值來重建記錄集。 在呼叫 Requery之前，將新值指派給 m_strFilter 和 m_strSort 之前，以設定新的篩選或排序屬性。 在呼叫 Requery之前，先將新值指派給參數數據成員，以設定新的參數。 如果篩選和排序字串保持不變，您可以重複使用查詢，以改善效能。

如果嘗試重建記錄集失敗，則會關閉記錄集。 呼叫 Requery之前，您可以藉由呼叫 CanRestart 成員函式來判斷是否可以重新查詢記錄集。 CanRestart 不保證 Requery 會成功。

警告

只有在您呼叫 之後才呼叫 Requery Open。

範例

此範例會重建記錄集以套用不同的排序順序。

CCustomer rsCustSet(&m_dbCust);

// Open the recordset
rsCustSet.Open();

// Use the recordset ...

// Set the sort order and Requery the recordset
rsCustSet.m_strSort = _T("L_Name, ContactFirstName");
if (!rsCustSet.CanRestart())
return;    // Unable to requery

if (!rsCustSet.Requery())
// Requery failed, so take action
AfxMessageBox(_T("Requery failed!"));

CRecordset::SetAbsolutePosition

將記錄集放在對應至指定記錄編號的記錄上。

void SetAbsolutePosition(long nRows);

參數

nRows
記錄集中目前記錄的單一序數位置。

備註

SetAbsolutePosition 會根據這個序數位置移動目前的記錄指標。

注意

此成員函式在僅轉寄記錄集上無效。

針對 ODBC 記錄集，1 的絕對位置設定是指記錄集中的第一筆記錄;設定為 0 是指檔案開頭 （BOF） 位置。

您也可以將負值傳遞至 SetAbsolutePosition。 在此情況下，會從記錄集結尾評估記錄集的位置。 例如， SetAbsolutePosition( -1 ) 將當前記錄指標移至記錄集中的最後一筆記錄。

注意

絕對位置不是用來做為代理記錄編號。 書籤仍然是保留並傳回指定位置的建議方式，因為刪除前一筆記錄時記錄的位置會變更。 此外，如果您再次重新建立記錄集，則無法保證指定的記錄會有相同的絕對位置，因為除非使用 ORDER BY 子句使用 SQL 語句建立記錄集內的個別記錄順序，否則不保證記錄集中的個別記錄順序。

如需記錄集導覽和書籤的詳細資訊，請參閱 Recordset：Scrolling （ODBC） 和 Recordset： Bookmarks and Absolute Positions （ODBC） 文章。

CRecordset::SetBookmark

將記錄集放在包含指定書籤的記錄上。

void SetBookmark(const CDBVariant& varBookmark);

參數

varBookmark
對象的參考 CDBVariant ，其中包含特定記錄的書籤值。

備註

若要判斷記錄集是否支援書籤，請呼叫 CanBookmark。 若要在支援書籤的情況下提供書籤，您必須在成員函式的 Open 參數中dwOptions設定 CRecordset::useBookmarks 選項。

注意

如果書籤不受支援或無法使用，呼叫 SetBookmark 將會導致擲回例外狀況。 僅轉寄記錄集不支援書籤。

若要先擷取目前記錄的書籤，請呼叫 GetBookmark，以將書籤值儲存至 CDBVariant 物件。 稍後，您可以使用已儲存的書籤值呼叫 SetBookmark ，以返回該記錄。

注意

在特定記錄集作業之後，您應該先檢查書籤持續性，再呼叫 SetBookmark。 例如，如果您使用 擷取書籤 GetBookmark ，然後呼叫 Requery，則書籤可能不再有效。 通話 CDatabase::GetBookmarkPersistence 以檢查您是否可以安全地呼叫 SetBookmark。

如需書籤和記錄集導覽的詳細資訊，請參閱 Recordset：Bookmarks 和 Absolute Positions （ODBC） 和 Recordset： Scrolling （ODBC）文章。

CRecordset::SetFieldDirty

將記錄集的欄位數據成員標示為已變更或未變更。

void SetFieldDirty(void* pv, BOOL bDirty = TRUE);

參數

pv
包含記錄集或 NULL中欄位資料成員的位址。 如果 NULL為 ，則會標示記錄集中的所有欄位數據成員。 （C++ NULL 與資料庫術語中的 Null 不同，這表示「沒有值」。

bDirty
TRUE 如果欄位資料成員要標示為「已變更」，則為 。 否則 FALSE ，如果欄位數據成員要標示為 「clean」 （未變更）。

備註

將字段標示為未變更可確保字段不會更新，併產生較少的 SQL 流量。

注意

此成員函式不適用於使用大量數據列擷取的記錄集。 如果您已實作大量數據列擷取，則 SetFieldDirty 會導致判斷提示失敗。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

架構會標示已變更的欄位數據成員，以確保這些成員會由記錄欄位交換 （RFX） 機制寫入數據源上的記錄。 變更欄位的值通常會自動設定欄位，因此您很少需要自行呼叫 SetFieldDirty ，但有時候您可能想要確保不論欄位數據成員中的值為何，都會明確更新或插入數據行。

警告

只有在呼叫 或 AddNew之後，才呼叫Edit這個成員函式。

針對 NULL 函式的第一個自變數使用 ，只會將函式套用至 outputColumn 字段，而不是 param 字段。 例如，呼叫

SetFieldNull(NULL);

只會 outputColumn 將欄位設定為 NULL; param 欄位將不會受到影響。

若要處理 param 欄位，您必須提供您要處理之個人 param 的實際位址，例如：

SetFieldNull(&m_strParam);

這表示您無法將所有欄位設定 param 為 NULL，因為您可以使用 outputColumn 欄位。

CRecordset::SetFieldNull

將記錄集的欄位數據成員標示為 Null（特別是沒有值）或非 Null。

void SetFieldNull(void* pv, BOOL bNull = TRUE);

參數

pv
包含記錄集或 NULL中欄位資料成員的位址。 如果 NULL為 ，則會標示記錄集中的所有欄位數據成員。 （C++ NULL 與資料庫術語中的 Null 不同，這表示「沒有值」。

bNull
如果欄位數據成員標示為沒有值（Null），則為非零。 否則，如果欄位數據成員要標示為非 Null，則為 0。

備註

當您將新記錄新增至記錄集時，所有欄位數據成員一開始都會設定為 Null 值，並標示為「已變更」。 當您從數據源擷取記錄時，其數據行已具有值或為 Null。

注意

請勿在使用大量數據列擷取的記錄集上呼叫這個成員函式。 如果您已實作大量數據列擷取，呼叫 SetFieldNull 會導致判斷提示失敗。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

如果您特別想要將當前記錄的欄位指定為沒有值，請呼叫 SetFieldNull bNull ，並將 設定為 將 TRUE 它標示為 Null。 如果字段先前標示為 Null，而您現在想要為其指定值，請設定其新值。 您不需要使用 SetFieldNull移除 Null 旗標。 若要判斷欄位是否允許為 Null，請呼叫 IsFieldNullable。

警告

只有在呼叫 或 AddNew之後，才呼叫Edit這個成員函式。

針對 NULL 函式的第一個自變數使用 ，只會將函式套用至 outputColumn 字段，而不是 param 字段。 例如，呼叫

SetFieldNull(NULL);

只會 outputColumn 將欄位設定為 NULL; param 欄位將不會受到影響。

若要處理 param 欄位，您必須提供您要處理之個人 param 的實際位址，例如：

SetFieldNull(&m_strParam);

這表示您無法將所有欄位設定 param 為 NULL，因為您可以使用 outputColumn 欄位。

注意

將參數設定為 Null 時，在開啟記錄集之前呼叫 SetFieldNull 會導致判斷提示。 在這裡情況下，請呼叫 SetParamNull。

SetFieldNull 是透過實作 DoFieldExchange。

CRecordset::SetLockingMode

將鎖定模式設定為「開放式」鎖定（預設值）或「悲觀」鎖定。 決定如何鎖定更新的記錄。

void SetLockingMode(UINT nMode);

參數

nMode
包含下列其中一個值：enum LockMode

• optimistic 開放式鎖定只會鎖定在呼叫 Update期間更新的記錄。

• pessimistic 在呼叫時，悲觀鎖定會鎖定記錄 Edit ，並保持鎖定，直到 Update 呼叫完成或移至新記錄為止。

備註

如果您需要指定記錄集用於更新的兩個記錄鎖定策略中的哪一個，請呼叫這個成員函式。 根據預設，記錄集的鎖定模式為 optimistic。 您可以將變更為更謹慎 pessimistic 的鎖定策略。 SetLockingMode在您建構並開啟 recordset 物件之後，但在呼叫 之前呼叫 Edit。

CRecordset::SetParamNull

將參數標示為 Null（特別是沒有值）或非 Null。

void SetParamNull(
    int nIndex,
    BOOL bNull = TRUE);

參數

nIndex
參數之以零為起始的索引。

bNull
如果 TRUE 為 （預設值），則參數會標示為 Null。 否則，參數會標示為非 Null。

備註

不同於 SetFieldNull，您可以在開啟記錄集之前呼叫 SetParamNull 。

SetParamNull 通常用於預先定義的查詢（預存程式）。

CRecordset::SetRowsetCursorPosition

將游標移至目前數據列集中的數據列。

void SetRowsetCursorPosition(WORD wRow, WORD wLockType = SQL_LOCK_NO_CHANGE);

參數

wRow
數據列在目前數據列集中的單一位置。 這個值的範圍可以從 1 到數據列集的大小。

wLockType
值，指出如何在重新整理數據列之後鎖定數據列。 如需詳細資料，請參閱＜備註＞。

備註

實作大量數據列擷取時，數據列集會擷取記錄，其中所擷取數據列集中的第一筆記錄是當前記錄。 若要在資料列集中建立另一筆記錄，請呼叫 SetRowsetCursorPosition。 例如，您可以結合SetRowsetCursorPositionGetFieldValue成員函式，以動態方式從記錄集的任何記錄擷取數據。

若要使用 SetRowsetCursorPosition，您必須在成員函式中Open指定 CRecordset::useMultiRowFetch 參數的 dwOptions 選項，實作大量數據列擷取。

SetRowsetCursorPosition 會呼叫 ODBC API 函式 SQLSetPos。 參數 wLockType 會指定執行之後 SQLSetPos 數據列的鎖定狀態。 下表描述的 wLockType可能值。

wLockType	描述
SQL_LOCK_NO_CHANGE （預設值）	驅動程式或數據源可確保數據列處於與呼叫前 SetRowsetCursorPosition 相同的鎖定或解除鎖定狀態。
SQL_LOCK_EXCLUSIVE	驅動程式或數據源會以獨佔方式鎖定數據列。 並非所有數據源都支援這種類型的鎖定。
SQL_LOCK_UNLOCK	驅動程式或數據源會解除鎖定數據列。 並非所有數據源都支援這種類型的鎖定。

如需 的詳細資訊 SQLSetPos，請參閱 Windows SDK。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

CRecordset::SetRowsetSize

指定您想要在擷取期間擷取的記錄數目。

virtual void SetRowsetSize(DWORD dwNewRowsetSize);

參數

dwNewRowsetSize
在指定擷取期間所要擷取的數據列數目。

備註

此虛擬成員函式會指定在使用大量數據列擷取時，您想要在單一擷取期間擷取的數據列數目。 若要實作大量數據列擷取，您必須在成員函式的 Open 參數中dwOptions設定 CRecordset::useMultiRowFetch 選項。

注意

呼叫 SetRowsetSize 而不實作大量數據列擷取會導致判斷提示失敗。

呼叫 之前先呼叫 SetRowsetSize Open 以設定記錄集的數據列集大小。 實作大量數據列擷取時的預設數據列集大小為 25。

注意

呼叫 SetRowsetSize時請小心。 如果您要手動配置數據的記憶體（如 中的 OpendwOptions 參數選項所指定CRecordset::userAllocMultiRowBuffers），您應該檢查您是否需要在呼叫 SetRowsetSize之後重新配置這些記憶體緩衝區，但在執行任何數據指標瀏覽作業之前。

若要取得資料列集大小的目前設定，請呼叫 GetRowsetSize。

如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

CRecordset::Update

藉 AddNew 由將新的或編輯的數據儲存在數據源上，以完成 或 Edit 作業。

virtual BOOL Update();

傳回值

如果成功更新一筆記錄，則為非零;否則，如果沒有變更任何數據行，則為 0。 如果未更新任何記錄，或更新了多個記錄，則會擲回例外狀況。 數據源上的任何其他失敗也會擲回例外狀況。

備註

呼叫 或 Edit 成員函式之後，呼叫AddNew這個成員函式。 需要此呼叫才能完成 AddNew 或 Edit 作業。

注意

如果您已實作大量資料列擷取，則無法呼叫 Update。 這會導致判斷提示失敗。 雖然 類別 CRecordset 不提供更新大量數據列的機制，但您可以使用 ODBC API 函 SQLSetPos式來撰寫自己的函式。 如需大量數據列擷取的詳細資訊，請參閱 記錄集：大量擷取記錄 （ODBC）。

AddNew並Edit準備一個編輯緩衝區，在其中新增或編輯的數據要儲存至數據源。 Update 會儲存數據。 只會更新標示或偵測到變更的欄位。

如果數據源支援交易，您可以進行 Update 交易的呼叫（及其對應 AddNew 或 Edit 呼叫）部分。 如需交易的詳細資訊，請參閱 交易 （ODBC）。

警告

如果您在未先呼叫 或Edit的情況下呼叫 AddNew Update ，Update則會CDBException擲回 。 如果您呼叫 AddNew 或 Edit，則必須 Update 在呼叫 Move 作業之前或關閉記錄集或資料來源連線之前呼叫 。 否則，您的變更會遺失而不通知。

如需處理 Update 失敗的詳細資料，請參閱 記錄集：記錄集如何更新記錄 （ODBC） 。

範例

請參閱 交易：在記錄集 （ODBC） 中執行交易。

另請參閱

CObject 類別
階層圖
CDatabase 類別
CRecordView 類別