Clone Method (ADO)
ADO 2.5 API Reference

Clone Method

Creates a duplicate Recordset object from an existing Recordset object. Optionally, specifies that the clone be read-only.

Syntax

Set rstDuplicate = rstOriginal.Clone (LockType)

Return Value

Returns a Recordset object reference.

Parameters

rstDuplicate
An object variable that identifies the duplicate Recordset object to be created.
rstOriginal
An object variable that identifies the Recordset object to be duplicated.
LockType
Optional. A LockTypeEnum value that specifies either the lock type of the original Recordset, or a read-only Recordset. Valid values are adLockUnspecified or adLockReadOnly.

Remarks

Use the Clone method to create multiple, duplicate Recordset objects, particularly if you want to maintain more than one current record in a given set of records. Using the Clone method is more efficient than creating and opening a new Recordset object with the same definition as the original.

The Filter property of the original Recordset, if any, will not be applied to the clone. Set the Filter property of the new Recordset in order to filter the results. The simplest way to copy any existing Filter value is to assign it directly, like this: rsNew.Filter = rsOriginal.Filter

The current record of a newly created clone is set to the first record.

Changes you make to one Recordset object are visible in all of its clones regardless of cursor type. However, after you execute Requery on the original Recordset, the clones will no longer be synchronized to the original.

Closing the original Recordset does not close its copies, nor does closing a copy close the original or any of the other copies.

You can only clone a Recordset object that supports bookmarks. Bookmark values are interchangeable; that is, a bookmark reference from one Recordset object refers to the same record in any of its clones.

Some Recordset events that are triggered will also fire in all Recordset clones. However, because the current record can differ between cloned Recordsets, the events may not be valid for the clone.

For example, if you change a value of a field, a WillChangeField event will occur in the changed Recordset and in all clones. The Fields parameter of the WillChangeField event of a cloned Recordset (where the change was not made) will simply refer to the fields of the current record of the clone, which may be a different record than the current record of the original Recordset where the change occurred.

The following table provided a full listing of all Recordset events and indicates whether they are valid and triggered for any recordset clones generated using the Clone method.

Event Triggered in clones?
EndOfRecordset No
FetchComplete No
FetchProgress No
FieldChangeComplete Yes
MoveComplete No
RecordChangeComplete Yes
RecordsetChangeComplete No
WillChangeField Yes
WillChangeRecord Yes
WillChangeRecordset No
WillMove No

See Also

Visual Basic Example | VBScript Example | Visual C++ Example | Visual J++ Example

Applies To: Recordset Object

© 1998-2003 Microsoft Corporation. All rights reserved.