Share via


CDaoRecordset Class

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

See Also

Reference

CObject Class

Hierarchy Chart

CDaoTableDef Class

CDaoWorkspace Class

CDaoDatabase Class

CDaoQueryDef Class