ADO Record Object Functions and Methods

[Previous] [Next]

Now let's examine the functions and methods exposed by the Record object and shown in the following table.

Record Object Functions and Methods
Function or Method Name	Description
Cancel	Cancels an asynchronous action on the Record object
Close	Closes an open Record object
CopyRecord	Copies the Record object to another location
DeleteRecord	Deletes the Record object
GetChildren	Retrieves the child data associated with the Record object
MoveRecord	Moves the Record object to another location
Open	Opens an existing Record object or creates a new Record object

Cancel Method

Use the Cancel method to cancel a pending asynchronous call on the Record object. This method can cancel calls to the Open, CopyRecord, DeleteRecord, and MoveRecord methods on the Record object, which can all be called asynchronously if the OLE DB provider supports asynchronous operations. The Cancel method takes no parameters.

Close Method

The Close method closes an open Record object. Like the Close method on a Recordset object, a Record object's Close method does not remove the object from memory. The Close method takes no parameters.

CopyRecord Method

The CopyRecord method copies a Record and its contents to another location. This method accepts six parameters:

 Record.CopyRecord Source, Destination, UserName, Password, _                   Options, Async 

The Source parameter is optional and accepts a string to denote the Record you want to copy. If you omit this parameter, the data referenced by the current Record object will be copied. The Destination parameter is marked as optional in the ADO Help files, but it's actually required. This parameter accepts a string value to specify the location where you want to create a new copy of the Record object.

The UserName and Password parameters are optional and can be used to authorize the user to copy the Record to the specified destination. You can use the optional Options parameter to specify which of the attributes available in CopyRecordOptionsEnum (and listed in the following table) you want. The Options parameter can accept the sum of multiple values from CopyRecordOptionsEnum.

CopyRecordOptionsEnum Values
Constant	Value	Description
adCopyUnspecified	-1	This is the default.
adCopyOverWrite	1	Overwrites whatever data is currently stored in the location specified by the Destination parameter. The CopyRecord method will fail if you attempt to copy over existing data without specifying this option.
adCopyNonRecursive	2	Copies the Record object but none of the child data associated with it. For example, CopyRecord copies the directory but not the files and subdirectories contained in it.
adCopyAllowEmulation	4	Requests that the provider attempt to simulate the copy (using download, upload, and delete operations) if the attempt to copy the Record object fails, because the destination URL is on a different server or serviced by a different provider than the source. Note that specifying this option can cause increased latency and/or data loss because of different provider capabilities when moving resources between providers.

The optional Async parameter accepts a Boolean value that indicates whether you want to call the CopyRecord method asynchronously. By default, this parameter is set to False. (Be aware that not all OLE DB providers that support the Record object allow asynchronous operations on the Record object.)

DeleteRecord Method

Use the DeleteRecord method to delete the Record and its contents. The DeleteRecord method accepts two optional parameters, as shown here:

 Record.DeleteRecord Source, Async 

The Source parameter accepts a string to denote the Record you want to delete. If you omit this parameter, the data currently referenced by the Record object will be deleted. The Async parameter accepts a Boolean value and indicates whether you want to call the DeleteRecord method asynchronously. By default, this parameter is set to False. (Note that not all OLE DB providers that support the Record object allow asynchronous operations on the Record object.)

GetChildren Method

The GetChildren method returns a Recordset object, as shown:

 Set Recordset = Record.GetChildren 

The returned Recordset object contains the child data associated with the current Record. You can call this method on Record objects that have a RecordType property value of adCollectionRecord. Depending on the functionality that your OLE DB provider supports, you might be able to call this method on a Record object whose RecordType is adStructDoc.

MoveRecord Method

The MoveRecord method copies a Record object and its contents to another location, and then deletes it from its current location. This method accepts the following six parameters:

 Record.MoveRecord Source, Destination, UserName, Password, _                   Options, Async 

All the parameters behave the same as the parameters for the CopyRecord method, with the exception of the Options parameter. Rather than taking a value from CopyRecordOptionsEnum, the Options parameter for the MoveRecord method accepts values from MoveRecordOptionsEnum, shown in the next table. The Options parameter can accept the sum of multiple values from MoveRecordOptionsEnum.

MoveRecordOptionsEnum Values
Constant	Value	Description
adMoveUnspecified	-1	This is the default.
adMoveOverWrite	1	Overwrites whatever data is currently stored in the location specified by the Destination parameter. The MoveRecord method will fail if you attempt to move data onto existing data without specifying this option.
adMoveDontUpdateLinks	2	Modifies the default behavior of the MoveRecord method by not updating the hypertext links of the source Record object. The default behavior depends on the capabilities of the provider. The move operation updates links if the provider offers this capability. If the provider cannot fix links or if this value isn't specified, the move succeeds even when links have not been fixed.
adMoveAllowEmulation	4	Requests that the provider attempt to simulate the move (using download, upload, and delete operations) if the attempt to move the Record object fails because the destination URL is on a different server or serviced by a different provider than the source. Note that specifying this option can cause increased latency and/or data loss because of different provider capabilities when moving resources between providers.

Open Method

Use the Open method to open an existing Record or create a new one. The Open method has seven parameters, all of which are optional:

 Record.Open Source, ActiveConnection, Mode, CreateOptions, _             Options, UserName, Password 

The Source parameter accepts a string or a Recordset and indicates the location of the data in your data store. You can use this parameter to override the current setting of the Record object's Source property. If you omit this parameter, ADO will use the current setting for the Source property.

The ActiveConnection parameter accepts a connection string or a Connection object to indicate the location of your data store. Omitting this parameter will cause ADO to use the current value of the Record object's ActiveConnection property to connect to your data store. Using this parameter overrides the current setting for the ActiveConnection property on the Record object.

The Mode parameter accepts values from ConnectModeEnum and corresponds to the Record object's Mode property to specify the access mode used to communicate with your data store. The CreateOptions parameter accepts values available in RecordCreateOptionsEnum, listed in the following table.

RecordCreateOptionsEnum Values
Constant	Value	Description
adFailIfNotExists	-1	Default; results in a run-time error if the value in the Source parameter points to a nonexistent node
adCreateNonCollection	0	Creates a new Record object with a RecordType value of adSimpleRecord
adCreateCollection	8192	Creates a new Record object with a RecordType value of adCollectionRecord
adOpenIfExists	33554432	Specifies that if the Record object at the location used in the Source parameter exists in your data store, the Open method will open that Record object rather than create a new one
adCreateOverwrite	67108864	Specifies that if the Record object at the location used in the Source parameter exists in your data store, the Open method will overwrite that data with a new Record
adCreateStructDoc	-2147483648	Creates a new Record object with a RecordType value of adStructDoc instead of opening an existing Record

You can use the Options parameter to supply a combination of values from RecordOpenOptionsEnum for further options upon opening your Record, as this next table shows.

RecordOpenOptionsEnum Values
Constant	Value	Description
adOpenRecordUnspecified	-1	This is the default.
adOpenAsync	4096	Indicates that you want to open the Record object in asynchronous mode.
adDelayFetchStream	16384	Specifies that the default stream associated with the Record object need not be fetched initially.
adDelayFetchFields	32768	Specifies not to fetch the fields associated with the Record object initially, but to fetch each field at the first attempt to access that field.
adOpenSource	8388608	Indicates that if the value in the Source parameter points to a node containing an executable script (such as an .asp script file), a Record containing the source is opened rather than the executed contents of the script. Only valid with noncollection Record objects.

You can specify the UserName and Password parameters to authorize the user to open or create the Record.