CDaoRecordset Class

Article
01/08/2013

Represents a set of records selected from a data source.

class CDaoRecordset : public CObject

Members

Public Constructors

Name	Description
CDaoRecordset::CDaoRecordset	Constructs a CDaoRecordset object.

Public Methods

Name	Description
CDaoRecordset::AddNew	Prepares for adding a new record. Call Update to complete the addition.
CDaoRecordset::CanAppend	Returns nonzero if new records can be added to the recordset via the AddNew member function.
CDaoRecordset::CanBookmark	Returns nonzero if the recordset supports bookmarks.
CDaoRecordset::CancelUpdate	Cancels any pending updates due to an Edit or AddNew operation.
CDaoRecordset::CanRestart	Returns nonzero if Requery can be called to run the recordset's query again.
CDaoRecordset::CanScroll	Returns nonzero if you can scroll through the records.
CDaoRecordset::CanTransact	Returns nonzero if the data source supports transactions.
CDaoRecordset::CanUpdate	Returns nonzero if the recordset can be updated (you can add, update, or delete records).
CDaoRecordset::Close	Closes the recordset.
CDaoRecordset::Delete	Deletes the current record from the recordset. You must explicitly scroll to another record after the deletion.
CDaoRecordset::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 DAO record field exchange (DFX).
CDaoRecordset::Edit	Prepares for changes to the current record. Call Update to complete the edit.
CDaoRecordset::FillCache	Fills all or a part of a local cache for a recordset object that contains data from an ODBC data source.
CDaoRecordset::Find	Locates the first, next, previous, or last location of a particular string in a dynaset-type recordset that satisfies the specified criteria and makes that record the current record.
CDaoRecordset::FindFirst	Locates the first record in a dynaset-type or snapshot-type recordset that satisfies the specified criteria and makes that record the current record.
CDaoRecordset::FindLast	Locates the last record in a dynaset-type or snapshot-type recordset that satisfies the specified criteria and makes that record the current record.
CDaoRecordset::FindNext	Locates the next record in a dynaset-type or snapshot-type recordset that satisfies the specified criteria and makes that record the current record.
CDaoRecordset::FindPrev	Locates the previous record in a dynaset-type or snapshot-type recordset that satisfies the specified criteria and makes that record the current record.
CDaoRecordset::GetAbsolutePosition	Returns the record number of a recordset object's current record.
CDaoRecordset::GetBookmark	Returns a value that represents the bookmark on a record.
CDaoRecordset::GetCacheSize	Returns a value that specifies the number of records in a dynaset-type recordset containing data to be locally cached from an ODBC data source.
CDaoRecordset::GetCacheStart	Returns a value that specifies the bookmark of the first record in the recordset to be cached.
CDaoRecordset::GetCurrentIndex	Returns a CString containing the name of the index most recently used on an indexed, table-type CDaoRecordset.
CDaoRecordset::GetDateCreated	Returns the date and time the base table underlying a CDaoRecordset object was created
CDaoRecordset::GetDateLastUpdated	Returns the date and time of the most recent change made to the design of a base table underlying a CDaoRecordset object.
CDaoRecordset::GetDefaultDBName	Returns the name of the default data source.
CDaoRecordset::GetDefaultSQL	Called to get the default SQL string to execute.
CDaoRecordset::GetEditMode	Returns a value that indicates the state of editing for the current record.
CDaoRecordset::GetFieldCount	Returns a value that represents the number of fields in a recordset.
CDaoRecordset::GetFieldInfo	Returns specific kinds of information about the fields in the recordset.
CDaoRecordset::GetFieldValue	Returns the value of a field in a recordset.
CDaoRecordset::GetIndexCount	Retrieves the number of indexes in a table underlying a recordset.
CDaoRecordset::GetIndexInfo	Returns various kinds of information about an index.
CDaoRecordset::GetLastModifiedBookmark	Used to determine the most recently added or updated record.
CDaoRecordset::GetLockingMode	Returns a value that indicates the type of locking that is in effect during editing.
CDaoRecordset::GetName	Returns a CString containing the name of the recordset.
CDaoRecordset::GetParamValue	Retrieves the current value of the specified parameter stored in the underlying DAOParameter object.
CDaoRecordset::GetPercentPosition	Returns the position of the current record as a percentage of the total number of records.
CDaoRecordset::GetRecordCount	Returns the number of records accessed in a recordset object.
CDaoRecordset::GetSQL	Gets the SQL string used to select records for the recordset.
CDaoRecordset::GetType	Called to determine the type of a recordset: table-type, dynaset-type, or snapshot-type.
CDaoRecordset::GetValidationRule	Returns a CString containing the value that validates data as it is entered into a field.
CDaoRecordset::GetValidationText	Retrieves the text that is displayed when a validation rule is not satisfied.
CDaoRecordset::IsBOF	Returns nonzero if the recordset has been positioned before the first record. There is no current record.
CDaoRecordset::IsDeleted	Returns nonzero if the recordset is positioned on a deleted record.
CDaoRecordset::IsEOF	Returns nonzero if the recordset has been positioned after the last record. There is no current record.
CDaoRecordset::IsFieldDirty	Returns nonzero if the specified field in the current record has been changed.
CDaoRecordset::IsFieldNull	Returns nonzero if the specified field in the current record is Null (having no value).
CDaoRecordset::IsFieldNullable	Returns nonzero if the specified field in the current record can be set to Null (having no value).
CDaoRecordset::IsOpen	Returns nonzero if Open has been called previously.
CDaoRecordset::Move	Positions the recordset to a specified number of records from the current record in either direction.
CDaoRecordset::MoveFirst	Positions the current record on the first record in the recordset.
CDaoRecordset::MoveLast	Positions the current record on the last record in the recordset.
CDaoRecordset::MoveNext	Positions the current record on the next record in the recordset .
CDaoRecordset::MovePrev	Positions the current record on the previous record in the recordset.
CDaoRecordset::Open	Creates a new recordset from a table, dynaset, or snapshot.
CDaoRecordset::Requery	Runs the recordset's query again to refresh the selected records.
CDaoRecordset::Seek	Locates the record in an indexed table-type recordset object that satisfies the specified criteria for the current index and makes that record the current record.
CDaoRecordset::SetAbsolutePosition	Sets the record number of a recordset object's current record.
CDaoRecordset::SetBookmark	Positions the recordset on a record containing the specified bookmark.
CDaoRecordset::SetCacheSize	Sets a value that specifies the number of records in a dynaset-type recordset containing data to be locally cached from an ODBC data source.
CDaoRecordset::SetCacheStart	Sets a value that specifies the bookmark of the first record in the recordset to be cached.
CDaoRecordset::SetCurrentIndex	Called to set an index on a table-type recordset.
CDaoRecordset::SetFieldDirty	Marks the specified field in the current record as changed.
CDaoRecordset::SetFieldNull	Sets the value of the specified field in the current record to Null (having no value).
CDaoRecordset::SetFieldValue	Sets the value of a field in a recordset.
CDaoRecordset::SetFieldValueNull	Sets the value of a field in a recordset to Null. (having no value).
CDaoRecordset::SetLockingMode	Sets a value that indicates the type of locking to put into effect during editing.
CDaoRecordset::SetParamValue	Sets the current value of the specified parameter stored in the underlying DAOParameter object
CDaoRecordset::SetParamValueNull	Sets the current value of the specified parameter to Null (having no value).
CDaoRecordset::SetPercentPosition	Sets the position of the current record to a location corresponding to a percentage of the total number of records in a recordset.
CDaoRecordset::Update	Completes an AddNew or Edit operation by saving the new or edited data on the data source.

Public Data Members

Name	Description
CDaoRecordset::m_bCheckCacheForDirtyFields	Contains a flag indicating whether fields are automatically marked as changed.
CDaoRecordset::m_nFields	Contains the number of field data members in the recordset class and the number of columns selected by the recordset from the data source.
CDaoRecordset::m_nParams	Contains the number of parameter data members in the recordset class — the number of parameters passed with the recordset's query
CDaoRecordset::m_pDAORecordset	A pointer to the DAO interface underlying the recordset object.
CDaoRecordset::m_pDatabase	Source database for this result set. Contains a pointer to a CDaoDatabase object.
CDaoRecordset::m_strFilter	Contains a string used to construct a SQL WHERE statement.
CDaoRecordset::m_strSort	Contains a string used to construct a SQL ORDER BY statement.

Remarks

Known as "recordsets," CDaoRecordset objects are available in the following three forms:

Table-type recordsets represent a base table that you can use to examine, add, change, or delete records from a single database table.
Dynaset-type recordsets are the result of a query that can have updateable records. These recordsets are a set of records that you can use to examine, add, change, or delete records from an underlying database table or tables. Dynaset-type recordsets can contain fields from one or more tables in a database.
Snapshot-type recordsets are a static copy of a set of records that you can use to find data or generate reports. These recordsets can contain fields from one or more tables in a database but cannot be updated.

Each form of recordset represents a set of records fixed at the time the recordset is opened. When you scroll to a record in a table-type recordset or a dynaset-type recordset, it reflects changes made to the record after the recordset is opened, either by other users or by other recordsets in your application. (A snapshot-type recordset cannot be updated.) You can use CDaoRecordset directly or derive an application-specific recordset class from CDaoRecordset. You can then:

Scroll through the records.
Set an index and quickly look for records using Seek (table-type recordsets only).
Find records based on a string comparison: "<", "<=", "=", ">=", or ">" (dynaset-type and snapshot-type recordsets).
Update the records and specify a locking mode (except snapshot-type recordsets).
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.

Class CDaoRecordset supplies an interface similar to that of class CRecordset. The main difference is that class CDaoRecordset accesses data through a Data Access Object (DAO) based on OLE. Class CRecordset accesses the DBMS through Open Database Connectivity (ODBC) and an ODBC driver for that DBMS.

Note

The DAO database classes are distinct from the MFC database classes based on Open Database Connectivity (ODBC). All DAO database class names have the "CDao" prefix. You can still access ODBC data sources with the DAO classes; the DAO classes generally offer superior capabilities because they are specific to the Microsoft Jet database engine.

You can either use CDaoRecordset directly or derive a class from CDaoRecordset. To use a recordset class in either case, open a database and construct a recordset object, passing the constructor a pointer to your CDaoDatabase object. You can also construct a CDaoRecordset object and let MFC create a temporary CDaoDatabase object for you. Then call the recordset's Open member function, specifying whether the object is a table-type recordset, a dynaset-type recordset, or a snapshot-type recordset. Calling Open selects data from the database and retrieves the first record.

Use the object's member functions and data members to scroll through the records and operate on them. The operations available depend on whether the object is a table-type recordset, a dynaset-type recordset, or a snapshot-type recordset, and whether it is updateable or read-only — this depends on the capability of the database or Open Database Connectivity (ODBC) data source. 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.

CDaoRecordset uses DAO record field exchange (DFX) to support reading and updating of record fields through type-safe C++ members of your CDaoRecordset or CDaoRecordset-derived class. You can also implement dynamic binding of columns in a database without using the DFX mechanism using GetFieldValue and SetFieldValue.

For related information, see the topic "Recordset Object" in DAO Help.

Inheritance Hierarchy

CObject

CDaoRecordset

Requirements

Header: afxdao.h