Let's look at the properties and collections exposed by the Record object and shown in the following table.
Record Object Properties and Collections | ||
---|---|---|
Property or Collection Name | Data Type | Description |
ActiveConnection | Variant | Specifies the Connection object used to retrieve the data for the Record object |
Fields | Collection of Field objects | A pointer to the collection of Field objects that contain data in the Record object |
Mode | ConnectModeEnum | Specifies the permissions for modification of the Record object |
ParentURL | String | Indicates the parent URL for the Record object |
Properties | Collection of Property objects | Collection of dynamic properties for the Record object |
RecordType | RecordTypeEnum | Indicates the type of the Record object |
Source | Variant | Specifies the source of the data contained in the Record object |
State | ObjectStateEnum | Indicates the state of the Record object |
The ActiveConnection property on the Record object contains the connection information that ADO will use to connect to your data store. You can set the ActiveConnection property to a valid connection string or to an open Connection object. The ActiveConnection property will return a Connection object.
Use the Record object's ActiveConnection property in the same way you'd use the ActiveConnection property on the Recordset and Command objects. (See Chapters 4 and 5, respectively.)
Like the Recordset object, the Record object exposes a Fields collection. As mentioned earlier in this chapter, when you examine a record in a Record object its Fields collection might contain more entries than if you examine the same record in a Recordset object. For more information on the Fields collection, see Chapter 4.
The Mode property indicates the permissions for modification of the Record object. This property contains a long value that represents a bitmask of values in ConnectModeEnum, as the following table describes.
ConnectModeEnum Values | ||
---|---|---|
Constant | Value | Description |
adModeUnknown | 0 | Uses the default permissions to your Record object |
adModeRead | 1 | Default; opens the Record object with read-only permissions |
adModeWrite | 2 | Opens the Record object with write-only permissions |
adModeReadWrite | 3 | Opens the Record object using read/write permissions |
adModeShareDenyRead | 4 | Prevents other users from reading the contents of your Record object while it's open |
adModeShareDenyWrite | 8 | Prevents other users from modifying your Record object while it's open |
adModeShareExclusive | 12 | Prevents other users from connecting to your Record object while it's open |
adModeShareDenyNone | 16 | Allows other users to open the same Record object with read and write permissions but prevents other users from using adModeShareDenyWrite or adModeShareExclusive |
You can set this property only on a closed Record object; the value of the Mode property is read-only when the Record is open. Although the Record's Mode property accepts the same values as the Connection object's Mode property, in functionality it closely resembles the Recordset object's LockType property.
The ParentURL property is read-only and contains a string indicating the location of the Record object's parent Record. The documentation for ParentURL states that this property will be set to Null if the Record represents the root in a hierarchy or if the type of data stored in the Record does not support URLs (such as a record in a Recordset). While testing with the beta versions of ADO, I found that the root Record's ParentURL property returns the URL for that Record, rather than Null or an empty string.
Like most ADO objects, the Record object exposes a Properties collection whose contents depend on your choice of OLE DB providers. In the samples I've written to test the Record object's Properties collection using the OLE DB Provider For Internet Publishing, the Properties collection is always empty. However, as more OLE DB providers support the Record object, this collection is where those providers will expose provider-specific attributes for the Record object.
The RecordType property indicates the type of data stored in the Record object. It's read-only and returns one of the values from RecordTypeEnum listed in the following table.
RecordTypeEnum Values | ||
---|---|---|
Constant | Value | Description |
adSimpleRecord | 0 | Indicates a simple record (does not contain child nodes) |
adCollectionRecord | 1 | Indicates a collection record (contains child nodes) |
adStructDoc | 2 | Indicates a special kind of collection record that represents COM structured documents |
Like the Source property on the Recordset object, this property stores a Variant that directs ADO to the location where the Record's data is stored. While the Record object is closed, this property is read/write. While the Record object is open, this property is read-only.
You can set the Source property to a string or to a Record object. The Source property corresponds to the Source parameter on the Record's Open method. For more information, see the Open method documented later in this chapter in the section "Open Method."
The Record object's State property indicates the current state of the Record. Like the State property on the Recordset object, this property returns a long value that represents a bitmask of values available in ObjectStateEnum. The following table lists these values.
ObjectStateEnum Values Applicable to the Record Object | ||
---|---|---|
Constant | Value | Description |
adStateClosed | 0 | The Record object is closed. |
adStateOpen | 1 | The Record object is open. |
adStateExecuting | 4 | The Record object is being opened asynchronously. |
The OLE DB Provider For Internet Publishing does not support opening Record objects asynchronously. If you use a provider that does support asynchronous operations with the Record object, be sure to perform bitwise operations rather than checking for specific values when testing the State property. For example, if the Record object is being opened asynchronously, the State property will return a value of 5 (adStateOpen + adStateExecuting).
NOTE
ObjectStateEnum also contains the value adStateFetching, but this value currently is not applicable to the State property of the Record object.