CdbRecordset Object

A CdbRecordset object represents the records in a base table or the records that result from running a query.

Remarks

You use CdbRecordset objects to manipulate data in a database at the record level. When you use DAO objects, you manipulate data almost entirely using CdbRecordset objects. All CdbRecordset objects are constructed using records (rows) and fields (columns). There are five types of CdbRecordset objects:

Table-type CdbRecordset — representation in code of a base table that you can use to add, change, or delete records from a single database table (Microsoft Jet workspaces only).
Dynaset-type CdbRecordset — the result of a query that can have updatable records. A dynaset-type CdbRecordset object is a dynamic set of records that you can use to add, change, or delete records from an underlying database table or tables. A dynaset-type CdbRecordset object can contain fields from one or more tables in a database. This type corresponds to an ODBC keyset cursor.
Snapshot-type CdbRecordset — a static copy of a set of records that you can use to find data or generate reports. A snapshot-type CdbRecordset object can contain fields from one or more tables in a database, but can't be updated. This type corresponds to an ODBC static cursor.
Forward-only–type CdbRecordset — identical to a snapshot except that no cursor is provided. You can only scroll forward through records. This improves performance in situations where you only need to make a single pass through a result set. This type corresponds to an ODBC forward-only cursor.
Dynamic-type CdbRecordset — a query result set from one or more base tables in which you can add, change, or delete records from a row-returning query. Further, records other users add, delete, or edit in the base tables also appear in your CdbRecordset. This type corresponds to an ODBC dynamic cursor (ODBCDirect workspaces only).

You can choose the type of CdbRecordset object you want to create using the type argument of the OpenRecordset method.

In a Microsoft Jet workspace, if you don't specify a type, DAO attempts to create the type of CdbRecordset with the most functionality available, starting with table. If this type isn’t available, DAO attempts a dynaset, then a snapshot, and finally a forward-only–type CdbRecordset object.

In an ODBCDirect workspace, if you don't specify a type, DAO attempts to create the type of CdbRecordset with the fastest query response, starting with forward-only. If this type isn't available, DAO attempts a snapshot, then a dynaset, and finally a dynamic-type CdbRecordset object.

When creating a CdbRecordset object using a non-linked CdbTableDef object in a Microsoft Jet workspace, table-type CdbRecordset objects are created. Only dynaset-type or snapshot-type CdbRecordset objects can be created with linked tables or tables in Microsoft Jet-connected ODBC databases.

A new CdbRecordset object is automatically added to the Recordsets collection when you open the object, and is automatically removed when you close it.

Note If you use variables to represent a CdbRecordset object and the CdbDatabase object that contains the CdbRecordset, make sure the variables have the same scope, or lifetime. For example, if you declare a public variable that represents a CdbRecordset object, make sure the variable that represents the CdbDatabase containing the CdbRecordset is also public.

You can create as many CdbRecordset object variables as needed. Different CdbRecordset objects can access the same tables, queries, and fields without conflicting.

Dynaset-, snapshot-, and forward-only–type CdbRecordset objects are stored in local memory. If there isn't enough space in local memory to store the data, the Microsoft Jet database engine saves the additional data to TEMP disk space. If this space is exhausted, a trappable error occurs.

The default collection of a CdbRecordset object is the Fields collection, and the default property of a CdbField object is the Value property. Use these defaults to simplify your code.

When you create a CdbRecordset object, the current record is positioned to the first record if there are any records. If there are no records, the RecordCount property setting is 0, and the BOF and EOF property settings are TRUE.

You can use the MoveNext, MovePrevious, MoveFirst, and MoveLast methods to reposition the current record. Forward-only–type CdbRecordset objects support only the MoveNext method. When using the Move methods to visit each record (or "walk" through the CdbRecordset), you can use the BOF and EOF properties to check for the beginning or end of the CdbRecordset object.

With dynaset- and snapshot-type CdbRecordset objects in a Microsoft Jet workspace, you can also use the Find methods, such as FindFirst, to locate a specific record based on criteria. If the record isn't found, the NoMatch property is set to TRUE. For table-type CdbRecordset objects, you can scan records using the Seek method.

The Type property indicates the type of CdbRecordset object created, and the Updatable property indicates whether you can change the object's records.

Information about the structure of a base table, such as the names and data types of each CdbField object and any CdbIndex objects, is stored in a TableDef object.

To refer to a CdbRecordset object in a collection by its ordinal number or by its Name property setting, use either of the following syntax forms:

Recordsets[0]

Recordsets["name"]

Note You can open a CdbRecordset object from the same data source or database more than once, creating duplicate names in the Recordsets collection. You should assign CdbRecordset objects to object variables and refer to them by variable name.

CdbRecordset Constructor Syntax

Use any one of the following three constructors. The qualifier 'CONSTRUCTOR' in the syntax models is provided to help readability. It has no syntactic value.

CONSTRUCTORCdbRecordset(VOID);

This constructor creates an instance of the class. There are no parameters.

CONSTRUCTORCdbRecordset(const CdbRecordset &);

Type	Description
const CdbRecordset &	Reference to an object.

This constructor creates a copy of the object referenced in the parameter.

CONSTRUCTORCdbRecordset(DAORecordset *prs,

BOOL bAddRef = FALSE);

Type	Argument	Description
DAORecordset *	prs	A DAO Automation interface pointer corresponding to this DAO class.
BOOL	bAddRef =FALSE	Optional. A Boolean. If TRUE, the DAO Automation interface AddRef function is called.

DAO functionality is presented through pointers to DAO Automation interfaces. This constructor makes a DAO interface available in the form of a DAO class object that provides additional functionality.

This constructor is not required for typical use. It is provided to enable you to easily create a DAO class object if you have access to the corresponding DAO interface.

When the destructor for the DAO object is invoked, the underlying Automation interface's Release member is called. If Release decrements the interface's reference count to zero, the pointer to the Automation interface can be deleted. If you don't want this to happen (for example, because you want to discard the DAO object, but continue using the Automation interface), specify TRUE for the second parameter. The underlying Automation interface's AddRef member is called, which counterbalances the eventual call to Release.