Share via


CRecordset Class

Represents a set of records selected from a data source.

class CRecordset : public CObject

Members

Public Constructors

Name

Description

CRecordset::CRecordset

Constructs a CRecordset object. Your derived class must provide a constructor that calls this one.

Public Methods

Name

Description

CRecordset::AddNew

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

CRecordset::CanAppend

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

CRecordset::CanBookmark

Returns nonzero if the recordset supports bookmarks.

CRecordset::Cancel

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

CRecordset::CancelUpdate

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

CRecordset::CanRestart

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

CRecordset::CanScroll

Returns nonzero if you can scroll through the records.

CRecordset::CanTransact

Returns nonzero if the data source supports transactions.

CRecordset::CanUpdate

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

CRecordset::CheckRowsetError

Called to handle errors generated during record fetching.

CRecordset::Close

Closes the recordset and the ODBC HSTMT associated with it.

CRecordset::Delete

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

CRecordset::DoBulkFieldExchange

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

CRecordset::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).

CRecordset::Edit

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

CRecordset::FlushResultSet

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

CRecordset::GetBookmark

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

CRecordset::GetDefaultConnect

Called to get the default connection string.

CRecordset::GetDefaultSQL

Called to get the default SQL string to execute.

CRecordset::GetFieldValue

Returns the value of a field in a recordset.

CRecordset::GetODBCFieldCount

Returns the number of fields in the recordset.

CRecordset::GetODBCFieldInfo

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

CRecordset::GetRecordCount

Returns the number of records in the recordset.

CRecordset::GetRowsetSize

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

CRecordset::GetRowsFetched

Returns the actual number of rows retrieved during a fetch.

CRecordset::GetRowStatus

Returns the status of the row after a fetch.

CRecordset::GetSQL

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

CRecordset::GetStatus

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

CRecordset::GetTableName

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

CRecordset::IsBOF

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

CRecordset::IsDeleted

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

CRecordset::IsEOF

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

CRecordset::IsFieldDirty

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

CRecordset::IsFieldNull

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

CRecordset::IsFieldNullable

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

CRecordset::IsOpen

Returns nonzero if Open has been called previously.

CRecordset::Move

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

CRecordset::MoveFirst

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

CRecordset::MoveLast

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

CRecordset::MoveNext

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

CRecordset::MovePrev

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

CRecordset::OnSetOptions

Called to set options (used on selection) for the specified ODBC statement.

CRecordset::OnSetUpdateOptions

Called to set options (used on update) for the specified ODBC statement.

CRecordset::Open

Opens the recordset by retrieving the table or performing the query that the recordset represents.

CRecordset::RefreshRowset

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

CRecordset::Requery

Runs the recordset's query again to refresh the selected records.

CRecordset::SetAbsolutePosition

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

CRecordset::SetBookmark

Positions the recordset on the record specified by the bookmark.

CRecordset::SetFieldDirty

Marks the specified field in the current record as changed.

CRecordset::SetFieldNull

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

CRecordset::SetLockingMode

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

CRecordset::SetParamNull

Sets the specified parameter to null (having no value).

CRecordset::SetRowsetCursorPosition

Positions the cursor on the specified row within the rowset.

CRecordset::SetRowsetSize

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

CRecordset::Update

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

Public Data Members

Name

Description

CRecordset::m_hstmt

Contains the ODBC statement handle for the recordset. Type HSTMT.

CRecordset::m_nFields

Contains the number of field data members in the recordset. Type UINT.

CRecordset::m_nParams

Contains the number of parameter data members in the recordset. Type UINT.

CRecordset::m_pDatabase

Contains a pointer to the CDatabase object through which the recordset is connected to a data source.

CRecordset::m_strFilter

Contains a CString that specifies a Structured Query Language (SQL) WHERE clause. Used as a filter to select only those records that meet certain criteria.

CRecordset::m_strSort

Contains a CString that specifies a SQL ORDER BY clause. Used to control how the records are sorted.

Remarks

Known as "recordsets," CRecordset objects are typically used in two forms: dynasets and snapshots. A dynaset stays synchronized with data updates made by other users. A snapshot is a static view of the data. Each form represents a set of records fixed at the time the recordset is opened, but when you scroll to a record in a dynaset, it reflects changes subsequently made to the record, either by other users or by other recordsets in your application.

Note

If you are working with the Data Access Objects (DAO) classes rather than the Open Database Connectivity (ODBC) classes, use class CDaoRecordset instead. For more information, see the article Overview: Database Programming.

To work with either kind of recordset, you typically derive an application-specific recordset class from CRecordset. Recordsets select records from a data source, and you can then:

  • Scroll through the records.

  • Update the records and specify a locking mode.

  • Filter the recordset to constrain which records it selects from those available on the data source.

  • Sort the recordset.

  • Parameterize the recordset to customize its selection with information not known until run time.

To use your class, open a database and construct a recordset object, passing the constructor a pointer to your CDatabase object. Then call the recordset's Open member function, where you can specify whether the object is a dynaset or a snapshot. Calling Open selects data from the data source. After the recordset object is opened, use its member functions and data members to scroll through the records and operate on them. The operations available depend on whether the object is a dynaset or a snapshot, whether it is updatable or read-only (this depends on the capability of the Open Database Connectivity (ODBC) data source), and whether you have implemented bulk row fetching. To refresh records that may have been changed or added since the Open call, call the object's Requery member function. Call the object's Close member function and destroy the object when you finish with it.

In a derived CRecordset class, record field exchange (RFX) or bulk record field exchange (Bulk RFX) is used to support reading and updating of record fields.

For more information about recordsets and record field exchange, see the articles Overview: Database Programming, Recordset (ODBC), Recordset: Fetching Records in Bulk (ODBC), and Record Field Exchange (RFX). For a focus on dynasets and snapshots, see the articles Dynaset and Snapshot.

Inheritance Hierarchy

CObject

CRecordset

Requirements

Header: afxdb.h

See Also

Reference

CObject Class

Hierarchy Chart

CDatabase Class

CRecordView Class