CRecordset

CRecordset::appendOnly 不允許 Edit 或 Delete 在記錄集。 只允許 AddNew。 此選項是互斥的 CRecordset::readOnly。

類成員

數據成員

m_hstmt 包含記錄集的ODBC語句處理，並 鍵入 HSTMT。

備註：

在 打開 調用之前，不要使用 m_hstmt。通常不直接需要訪問 HSTMT，但是，您可能需要它SQL語句的直接執行的。 選件類 CDatabase 的ExecuteSQL 成員函式提供示例 m_hstmt。

m_nFields 在記錄集包含欄位數據成員的數目，並 鍵入 UINT。

備註：

記錄集選件類的構造函式必須初始化正確數目的 m_nFields。 如果尚未實現批量取行，類嚮導編寫此初始化，如果您在使用它來聲明記錄集選件類。 您還可以編寫它手動。

框架使用此數字管理欄位數據成員和當前記錄之間的相應列的互動在數據源中。

此數字必須對應於“在 DoFieldExchange 或 DoBulkFieldExchange ”註冊的輸出列的數目在調用後對SetFieldType 與參數 CFieldExchange::outputColumn。

可以動態綁定列，遵循該文章“記錄集聲明:動態綁定數據列”。如果這樣做，則必須添加在 m_nFields 的計數反映RFX的數目或"批量RFX在您的動態綁定的列的 DoFieldExchange 或 DoBulkFieldExchange 成員函式調用。

　　

m_nParams 在記錄集包含參數數據成員的數目，並鍵入 UINT。

備註：

如果您的記錄集選件類具有任何參數數據成員，選件類的構造函式必須初始化正確數目的 m_nParams。m_nParams 默認的值更改為0。 如果添加參數必須手動執行)的數據成員(必須手動添加在選件類構造函式的初始化反映了必須至少具有大到數量的“數參數(?”在您的 m_strFilter 或 m_strSort 字元串的占位符）。它將參數化記錄集的查詢時，框架使用此號碼。

此數字必須對應於 DoFieldExchange 或 DoBulkFieldExchange ”簽入“參數的數目中，調用 SetFieldType與 CFieldExchange::inputParam、 CFieldExchange::param、 CFieldExchange::outputParam或CFieldExchange::inoutParam後的參數值。

m_pDatabase 在記錄集包含參數數據成員的數目，並鍵入 UINT。

備註：

此變數設定通過兩種方式。 通常，那么，當您構造記錄集對象時，您將指針傳遞給已連線的 CDatabase 對象。 如果通過 NULL，CRecordset 會為您創建一 CDatabase 對象並將其連線。 在任何情況下，CRecordset 此變數存儲指針。

通常不會直接需要使用在 m_pDatabase存儲的指針。 如果您編寫了 CRecordset的擴展，但是，您可能需要使用指針。 例如，因此，如果引發您的 CDBExceptions.，您可能需要指針。 如果需要執行某個使用同一CDatabase 對象，例如運行期間發生的事務，設定逾時或調用選件類 CDatabase 的 ExecuteSQL 成員函式直接執行SQL語句，或者您可能需要它。

m_strFilter 包含指定結構化查詢語言(SQL) WHERE 子句的 CString。 用於，篩選器選擇滿足特定條件的那些記錄。

備註：

記錄集使用此選擇在 Open 期間的字元串約束(或篩選器)記錄或 Requery 調用。 這對於選擇記錄的子集非常有用，例如“加利福尼亞基於的任何salesperson” (“狀態= CA”）。 WHERE 子句的ODBC SQL語法為

WHERE search-condition

注意在您的字元串不包含 WHERE 關鍵字。 框架提供它。

可以通過將還參數化篩選器字元串“?”其中的占位符，聲明您的選件類的一個參數數據成員每個占位符的和傳遞參數傳遞到記錄集在運行時。 這使您可以構造篩選器在運行時。 有關更多信息，請參見文章 記錄集:參數化記錄集(odbc)。

有關SQL WHERE 子句的更多信息，請參見文章 SQL。 有關選擇和篩選記錄的更多信息，請參見文章 記錄集:篩選記錄(odbc)。

　　

m_strSort 包含指定SQL ORDER BY 子句的 CString。 用於控制日誌排序。

備註：

記錄集使用它選擇在 Open 過程中該字元串排序記錄或 Requery 調用。 可以使用此函式對一個或多個列的記錄集。 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( CDatabase* pDatabase = NULL);

構造 CRecordset 對象。 您的派生類必須提供調用此站點的構造函式。

參數：

• pDatabase
  
• 包含指向 CDatabase 對象或該值 NULL。 如果 NULL 和不 CDatabase 對象的 Open 成員函式未調用將其連線到數據源，記錄集嘗試打開它可以在自己的 Open 調用過程。 如果通過 NULL，CDatabase對象而不是構造並連線使用指定的數據源信息何時派生了與類嚮導的記錄集選件類。
  

備註：

可以直接使用 CRecordset 或從派生 CRecordset特定的選件類。 可以使用類嚮導派生記錄集選件類。

派生類 必須 提供自己的構造函式。 在派生類構造函式中，調用構造函式 CRecordset::CRecordset，將適當的參數傳遞給它。

通過 NULL 傳遞給記錄集構造函式已為您自動構造和連線線的 CDatabase 對象。 這是不要求您在構造記錄集之前構造和連線 CDatabase 對象的有用的簡短。

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

通過檢索表或執行記錄集表示的查詢打開記錄集。

參數：

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互動，具有不同的默認值。
  

有關這些記錄集類型的更多信息，請參見文章 記錄集(odbc)。 有關相關信息，請參見文章“使用塊和滾動的游標”在 Windows SDK。

pszSQL

• 包含下列操作之一的字元串指針:
  NULL 指針。
  
• 表的名稱。
  
• SQL SELECT 語句(可選)與SQL WHERE 或 ORDER BY 子句）。
  
• 指定預定義查詢(存儲過程)的名稱 CALL 語句。 注意不在大括弧和 CALL 關鍵字之間插入空白。
  

dwOptions

• 可以指定值的組合的位掩碼下面列出。 其中一些互相排斥。 默認值為 none。
  
• CRecordset::readOnly 打開記錄集為唯讀。 此選項是互斥的 CRecordset::appendOnly。
  
• CRecordset::optimizeBulkAdd 使用一個準備的SQL語句最佳化一次添加多個記錄。 僅當未使用ODBC API函式 SQLSetPos 更新記錄集，適用。 第一次更新確定哪些欄位標記為已更新。 此選項是互斥的 CRecordset::useMultiRowFetch。
  
• CRecordset::useMultiRowFetch 實現批量取行允許多個行檢索在單個獲取操作。 這是旨在的高級功能提高性能;但是，批量記錄欄位交換不是由類嚮導支持。 此選項是互斥的CRecordset::optimizeBulkAdd。 請注意，如果指定 CRecordset::useMultiRowFetch，然後選項卡 CRecordset::noDirtyFieldCheck 將自動打開(雙緩衝不可用);在向前記錄集，選項卡CRecordset::useExtendedFetch 將自動打開。 有關批量取行的更多信息，請參見文章 記錄集:獲取記錄(odbc)。
  
• CRecordset::skipDeletedRecords 跳過所有刪除的記錄，在記錄集中定位時常時。 這將減慢在某些相對獲取的性能。 此選項無效在向前記錄集。 如果您調用了 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 成員函式不會調用中，指定此選項。
  
• 而不是 SQLFetch的CRecordset::useExtendedFetch 實現 SQLExtendedFetch。 對於實現能在僅向前記錄集的批量行模型。 如果在僅向前記錄集指定選項CRecordset::useMultiRowFetch，則 CRecordset::useExtendedFetch 將自動打開。
  
• CRecordset::userAllocMultiRowBuffers 用戶將數據的存儲緩衝區。 如果要將自己的存儲，請使用 CRecordset::useMultiRowFetch 結合使用此選項;否則，則框架將自動分配必要的存儲區。 有關更多信息，請參見文章 記錄集:獲取記錄(odbc)。 請注意指定CRecordset::userAllocMultiRowBuffers 的，因此，不指定 CRecordset::useMultiRowFetch導致生成失敗的斷言。
  

返回值

非零，如果成功打開了 CRecordset 對象;否則0，則 CDatabase::Open (如果調用)返回0。

備註

必須調用該成員函式運行記錄集定義的查詢。 在調用 Open之前，必須構造記錄集對象。

與數據源的此記錄集的連線取決於您在調用 Open之前構造記錄集。 如果要將傳遞給未連線到數據源的記錄集構造函式的一 CDatabase 對象，此成員函式使用 GetDefaultConnect 嘗試打開資料庫對象。 如果通過NULL 到記錄集構造函式，該構造函式編寫您的一 CDatabase 對象和 Open 嘗試連線的資料庫對象。 有關關閉記錄集和連線的詳細信息。這些更改的情況下，請參見 關閉。

CRecordset::Close

virtual void Close( );關閉記錄集和ODBC HSTMT 與它。

備註

為記錄集分配的框架釋放ODBC HSTMT 和所有記憶體。 通常在調用 Close後，您刪除C++記錄集對象是否分配了 new。

可以在調用 Close之後再次調用 Open。 這使您可以重新使用記錄集對象。 另一種方法是調用 Requery。

屬性

CanAppend Returns nonzero if new records can be added to the recordset via the AddNew member function.

CanBookmark Returns nonzero if the recordset supports bookmarks.

CanRestart Returns nonzero if Requery can be called to run the recordset’s query again.

CanScroll Returns nonzero if you can scroll through the records.

CanTransact Returns nonzero if the data source supports transactions.

CanUpdate Returns nonzero if the recordset can be updated (you can add, update, or delete records).

GetODBCFieldCount Returns the number of fields in the recordset.

GetRecordCount Returns the number of records in the recordset.

GetStatus Gets the status of the recordset: the index of the current record and whether a final count of the records has been obtained.

GetTableName Gets the name of the table on which the recordset is based.

GetSQL Gets the SQL string used to select records for the recordset.

IsOpen Returns nonzero ifOpen has been called previously.

IsBOF Returns nonzero if the recordset has been positioned before the first record. There is no current record.

IsEOF Returns nonzero if the recordset has been positioned after the last record. There is no current record.

IsDeleted Returns nonzero if the recordset is positioned on a deleted record.

更新操作函式

AddNew Prepares for adding a new record. Call Update to complete the addition.

CancelUpdate Cancels any pending updates due to an AddNew or Edit operation.

Delete Deletes the current record from the recordset. You must explicitly scroll to another record after the deletion.

Edit Prepares for changes to the current record. Call Update to complete the edit.

Update Completes an AddNew or Edit operation by saving the new or edited data on the data source.

導航操作

GetBookmark Assigns the bookmark value of a record to the parameter object.

Move Positions the recordset to a specified number of records from the current record in either direction.

MoveFirst Positions the current record on the first record in the recordset. Test for IsBOF first.

MoveLast Positions the current record on the last record or on the last rowset. Test for IsEOF first.

MoveNext Positions the current record on the next record or on the next rowset. Test for IsEOF first.

MovePrev Positions the current record on the previous record or on the previous rowset. Test for IsBOF first.

SetAbsolutePosition Positions the recordset on the record corresponding to the specified record number.

SetBookmark Positions the recordset on the record specified by the bookmark.

其他操作

Cancel Cancels an asynchronous operation or a process from a second thread.

FlushResultSet Returns nonzero if there is another result set to be retrieved, when using a predefined query.

GetFieldValue Returns the value of a field in a recordset.

GetODBCFieldInfo Returns specific kinds of information about the fields in a recordset.

GetRowsetSize Returns the number of records you wish to retrieve during a single fetch.

GetRowsFetched Returns the actual number of rows retrieved during a fetch.

GetRowStatus Returns the status of the row after a fetch.

IsFieldDirty Returns nonzero if the specified field in the current record has been changed.

IsFieldDirty Returns nonzero if the specified field in the current record has been changed.

IsFieldNull Returns nonzero if the specified field in the current record is Null (has no value).

IsFieldNullable Returns nonzero if the specified field in the current record can be set to Null (having no value).

RefreshRowset Refreshes the data and status of the specified row(s).

Requery Runs the recordset’s query again to refresh the selected records.

SetFieldDirty Marks the specified field in the current record as changed.

SetFieldNull Sets the value of the specified field in the current record to Null (having no value).

SetLockingMode Sets the locking mode to “optimistic” locking (the default) or “pessimistic” locking. Determines how records are locked for updates.

SetParamNull Sets the specified parameter to Null (having no value).

SetRowsetCursorPosition Positions the cursor on the specified row within the rowset.

覆蓋

Check Called to examine the return code from an ODBC API function.

CheckRowsetError Called to handle errors generated during record fetching.

DoBulkFieldExchange Called to exchange bulk rows of data from the data source to the recordset. Implements bulk record field exchange (Bulk RFX).

DoFieldExchange Called to exchange data (in both directions) between the field data members of the recordset and the corresponding record on the data source. Implements record field exchange (RFX).

GetDefaultConnect Called to get the default connect string.

GetDefaultSQL Called to get the default SQL string to execute.

OnSetOptions Called to set options for the specified ODBC statement.

SetRowsetSize Specifies the number of records you wish to retrieve during a fetch.

備註

稱為“記錄集”，CRecordset 對象通常用於兩種形式:動態集和快照。 動態集保持與其他用戶所做的更新數據同步。 快照是數據的靜態視圖。 每個窗體表示已修復的一組記錄，每次打開記錄集，但，以便在移動到動態集時的記錄，它反映其他記錄集以後對該記錄，由其他用戶或更改在應用程式中。

如果您使用的是數據訪問使用否決(DAO)選件類而不是開放式資料庫連線(odbc)選件類，使用選件類CDaoRecordset。 有關更多信息，請參見文章 概述:資料庫編程。

若要使用branch使用類型的記錄集，則從 CRecordset通常派生特定的記錄集選件類。 從數據源的記錄集選擇記錄和然後可以:

• 滾動記錄。
  
• 更新記錄並指定一個鎖定模式。
  
• 篩選記錄它從這些選擇可用在數據源的記錄集約束。
  
• 排序記錄集。
  
• 參數化記錄集自定義該控制項的信息選擇未知直到運行時。
  

若要使用您的選件類，請打開資料庫並構造記錄集對象，通過構造函式指針到您的 CDatabase 對象。 然後調用記錄集的 Open 成員函式，可以指定對象是否是動態集還是快照。 調用 Open 選擇數據從數據源。 在打開後記錄集對象，請使用其成員函式和數據成員滾動記錄和對它們。 可用的操作取決於對象是否是動態集或快照，它是否可更新或唯讀(這取決於開放式資料庫連線(odbc)數據源)的功能，因此，您是否實現批量取行。 若要刷新可能已更改或添加的記錄，因為 Open 調用，調用對象的 Requery 成員函式。 當您完成使用協定時，調用對象的 Close 成員函式和銷毀對象。

在派生的 CRecordset 選件類，記錄欄位交換(rfx)或批量記錄欄位交換(bulk RFX)用於支持讀取和更新記錄欄位。

有關記錄集和記錄欄位交換的更多信息，請參見位於 概述:資料庫編程、 記錄集(odbc)、 記錄集:獲取記錄(odbc)和 記錄欄位交換(rfx)。 有關動態集和快照中的一個焦點，請參見位於 動態集 和 快照。

功能

該類代表從數據源中提取的記錄集。程式可以選擇數據源中的某個表作為一個記錄集，也可以通過對表的查詢得到記錄集，還可以合併同一數據源中的多個表作為一個記錄集中。通過該類可以對記錄集中的記錄進行滾動、修改、增加和刪除等操作。