ADO » Objects » Recordset
Version: 2.5
The ADO Recordset object is used to contain the set of data extracted from a database.
The Recordset object is composed of records (which are also referred to as rows) and of fields
(which are also referred to as columns).
The Recordset object should be considered to be the heart of ADO. Via this object, we can
select desired data and change the data with additions, deletions, and updates. Equally
important is the ability to move around inside the database. In fact, the Recordset object is
blessed with an extremely comprehensive selection of properties, collections, methods, and
events that allow extensive manipulation of the retrieved data and interpretation of the
operational environment. However, the functionality of the provider may impose limitations. For
example, some properties may not be available to the Recordset object depending on which
provider is being accessed. You can use the Supports method to predetermine if a Recordset
object will support a specific type of functionality.
Only the Connection and Recordset objects have events. Note that only the Visual Basic,
Visual C++, and Visual J++ languages can handle these events. You cannot handle an event
using the VBScript or JScript scripting languages.
Properties
- AbsolutePage
-
Syntax: recordsetobject. AbsolutePage
Sets or returns a long value that is the current page number in the Recordset object, or the PositionEnum value (either BOF, EOF, or empty).
- AbsolutePosition
-
Syntax: recordsetobject. AbsolutePosition
Sets or returns a long value that is the ordinal position of the cursor.
- ActiveCommand
-
Syntax: recordsetobject. ActiveCommand
Returns a variant that is the Command object associated with the Recordset object.
- ActiveConnection
-
Syntax: recordsetobject. ActiveConnection
Sets or returns a variant defining the Connection object to which the Recordset belongs, or returns a string value if there is no connection.
- BOF Property
-
Syntax: recordsetobject.BOF
Returns a Boolean value indicating if the current record position is before the first record.
- Bookmark
-
Syntax: recordsetobject.Bookmark
Sets or returns a variant value that uniquely defines the position of a record in a recordset.
- CacheSize
Syntax: recordsetobject. CacheSize
Sets or returns a long value that is the number of records that are cached or are allowed to be cached.
- CursorLocation
Syntax: recordsetobject.CursorLocation
Sets or returns a long value that is a CursorLocationEnum value which defines the location of the cursor engine (server-side or client-side).
- CursorType
Syntax: recordsetobject. CursorType
Sets or returns a CursorTypeEnum value that defines the type of cursor being used.
- DataMember
Syntax: recordsetobject. DataMember
Sets or returns a string value that names the data member referenced by the DataSource property.
- DataSource
Syntax: recordsetobject. DataSource
Specifies the object containing the data member that will be represented as a Recordset object.
- EditMode
Syntax: recordsetobject. EditMode
Returns an EditModeEnum value that defines the editing status of the current record.
- EOF
Syntax: recordsetobject. EOF
Returns a Boolean value indicating if the current record position is after the last record.
- Filter
Syntax: recordsetobject. Filter
Sets or returns a variant value that is either a string, array of bookmarks, or aFilterGroupEnum value used to filter data. You also use this property to turn an existing Filter off.
- Index
Syntax: recordsetobject. Index
Sets or returns a string value that is the name of the index in effect.
- LockType
Syntax: recordsetobject. LockType
Sets or returns a LockTypeEnum value that defines the type of locks that are in effect while editing records.
- MarshalOptions
Syntax: recordsetobject. MarshalOptions
Sets or returns a MarshalOptionEnum value that specifies which records are to be transferred (marshaled) back to the server.
- MaxRecords
Syntax: recordsetobject. MaxRecords
Sets or returns a long value that specifies the maximum number of records that can be returned to a Recordset object as the result of a query.
- PageCount
Syntax: recordsetobject. PageCount
Returns a long value that is the number of pages contained in a Recordset object.
- PageSize
Syntax: recordsetobject. PageSize
Sets or returns a long value that specifies how many records are on one page.
- RecordCount
Syntax: recordsetobject. RecordCount
Returns a long value that is the count of how many records are in a Recordset object.
- Sort
Syntax: recordsetobject. Sort
Sets or returns a string value that is a comma-delineated list of the names of which fields in the Recordset to sort. After each name, you can optionally add a blank space and the keywords ASC or DESC to designate the sort direction.
- Source
Syntax: recordsetobject. Source
Sets or returns a string value that defines the data source for a Recordset object.
- State
Syntax: recordsetobject. State
Returns a long value describing if the Recordset object is open, closed, or in the process of connecting, executing, or retrieving.
- Status
Syntax: recordsetobject. Status
Returns a sum of one or more RecordStatusEnum values describing the status of the current record.
- StayInSync
Syntax: recordsetobject. StayInSync
For a hierarchical Recordset object, sets or returns a Boolean value defining whether the reference to the underlying child record, called the chapter, needs updating.
Methods
- AddNew
Syntax: recordsetobject. AddNew (FieldList, Values)
Used to create a new record.
- Cancel
Syntax: recordsetobject. Cancel
Cancels the execution of a pending Open call.
- CancelBatch
Syntax: recordsetobject. CancelBatch (AffectRecords)
Used to cancel a pending batch update. You must be in batch update mode.
- CancelUpdate
Syntax: recordsetobject. CancelUpdate
Used to cancel any changes made to the current row or to cancel the addition of a new row to a Recordset. This must be done before performing an Update.
- Clone
Syntax: recordsetobject. Clone (LockType)
Creates a duplicate copy of a Recordset object by copying an existing Recordset object.
- Close
Syntax: recordsetobject. Close
Closes a Recordset object.
- CompareBookmarks
Syntax: recordsetobject. CompareBookmarks (Bookmark1, Bookmark2)
Returns a CompareEnum value that compares the relative row position of two bookmarks in the same Recordset object.
- Delete
Syntax: recordsetobject. Delete (AffectRecords)
Deletes the current record, a group of records, or all records.
- Find
Syntax: recordsetobject. Find (Criteria, SkipRows, SearchDirection, Start)
Searches for a row in a Recordset that matches the given criteria.
- GetRows
Syntax: recordsetobject. GetRows (Rows, Start, Field)
Used to copy either all or a specified number of records into a two-dimensional array.
- GetString
Syntax: recordsetobject. GetString (StringFormat, NumRows, ColumnDelimiter,RowDelimiter, NullExpr)
Returns the specified Recordset as a string.
- Move
Syntax: recordsetobject. Move (NumRecords, Start)
Moves the position of the current record pointer.
- MoveFirst
Syntax: recordsetobject. MoveFirst
Moves the position of the current record pointer to the first record.
- MoveLast
Syntax: recordsetobject. MoveLast
Moves the position of the current record pointer to the last record.
- MoveNext
Syntax: recordsetobject. MoveNext
Moves the position of the current record pointer forward to the next record.
- MovePrevious
Syntax: recordsetobject. MovePrevious
Moves the position of the current record pointer back to the previous record.
- NextRecordset
Syntax: recordsetobject. NextRecordset (RecordsAffected)
Clears the current Recordset object and returns the next Recordset object. .
- Open
Syntax: recordsetobject. Open (Source, ActiveConnection, CursorType, LockType, Options)
When used on a Recordset object, this opens a cursor that is used to navigate through records.
- Requery
Syntax: recordsetobject. Requery Options
Used to update (refresh) the data in a Recordset object. This is essentially equivalent to a Close followed by an Open.
- Resync
Syntax: recordsetobject. Resync AffectRecords, ResyncValues
Refreshes the data in the current Recordset object by re-synchronizing records with the underlying (original) database.
- Save
Syntax: recordsetobject. Save Destination, PersistFormat
Saves the Recordset to a file or Stream object.
- Seek
Syntax: recordsetobject. Seek KeyValues, SeekOption
Uses the index of a Recordset to locate a specified row.
- Supports
Syntax: recordsetobject. Supports (CursorOptions)
Returns a Boolean value that indicates whether or not a Recordset object will support a specific type of functionality.
- Update
Syntax: recordsetobject. Update (Fields, Values)
Used to save any changes made to the current row of a Recordset object.
- UpdateBatch
Syntax: recordsetobject. UpdateBatch (AffectRecords)
Writes all pending batch updates to the underlying database.
Events
- EndOfRecordset
Syntax: EndOfRecordset (fMoreData, adStatus, pRecordset)
Called if there is an attempt to move past the last row.
- FetchComplete
Syntax: FetchComplete (pError, asStatus, pRecordset)
Called after all records in an asynchronous operation have been retrieved.
- FetchProgress
Syntax: FetchProgress (Progress, MaxProgress, adStatus, pRecordset)
Called periodically during an asynchronous operation. Returns a long value stating how many rows have been retrieved.
- FieldChangeComplete
Syntax: recordsetobject. UpdateBatch (AffectRecords)
Writes all pending batch updates to the underlying database.
- MoveComplete
Syntax: MoveComplete (adReason, pError, adStatus, pRecordset)
Called after the current position in the database has changed.
- RecordChangeComplete
Syntax: RecordChangeComplete (adReason, cRecords, pError, adStatus, pRecordset)
Called after one or more rows have been changed.
- RecordsetChangeComplete
Syntax: RecordsetChangeComplete (adReason, pError, adStatus, pRecordset)
Called when there have been any changes made to the Recordset.
- WillChangeField
Syntax: WillChangeField (cFields, Fields, adStatus, pRecordset)
Called before the values of one or more Field objects are to be changed.
- WillChangeRecord
Syntax: WillChangeRecord (adReason, cRecords, adStatus, pRecordset)
Called before one or more rows are to be changed.
- WillChangeRecordset
Syntax: WillChangeRecordset (adReason, adStatus, pRecordset)
Called before any pending changes are made to the Recordset.
- WillMove
Syntax: WillMove (adReason, adStatus, pRecordset)
Called before a pending operation can change the current position.
collection
- Fields
A collection containing all of the Field objects associated with a Recordset object.
- Properties
A collection of Property objects. Each Property object contains a provider-specific property.
