OBJECT:  Recordset

Recordset

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 Property
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).

Syntax: recordsetobject. AbsolutePage

AbsolutePosition Property
Sets or returns a long value that is the ordinal position of the cursor.

Syntax: recordsetobject. AbsolutePosition

ActiveCommand Property
Returns a variant that is the Command object associated with the Recordset object.

Syntax: recordsetobject. ActiveCommand

ActiveConnection Property
Sets or returns a variant defining the Connection object to which the Recordset belongs, or returns a string value if there is no connection.

Syntax: recordsetobject. ActiveConnection

BOF Property
Returns a Boolean value indicating if the current record position is before the first record.

Syntax: recordsetobject. BOF

Bookmark Property
Sets or returns a variant value that uniquely defines the position of a record in a recordset.

Syntax: recordsetobject. Bookmark

CacheSize Property
Sets or returns a long value that is the number of records that are cached or are allowed to be cached.

Syntax: recordsetobject. CacheSize

CursorLocation Property
Sets or returns a long value that is a CursorLocationEnum value which defines the location of the cursor engine (server-side or client-side).

Syntax: recordsetobject. CursorLocation

CursorType Property
Sets or returns a CursorTypeEnum value that defines the type of cursor being used.

Syntax: recordsetobject. CursorType

DataMember Property
Sets or returns a string value that names the data member referenced by the DataSource property.

Syntax: recordsetobject. DataMember

DataSource Property
Specifies the object containing the data member that will be represented as a Recordset object.

Syntax: recordsetobject. DataSource

EditMode Property
Returns an EditModeEnum value that defines the editing status of the current
record.

Syntax: recordsetobject. EditMode

EOF Property
Returns a Boolean value indicating if the current record position is after the last record.

Syntax: recordsetobject. EOF

Filter Property
Sets or returns a variant value that is either a string, array of bookmarks, or a FilterGroupEnum value used to filter data. You also use this property to turn an existing Filter off.

Syntax: recordsetobject. Filter

Index Property
Sets or returns a string value that is the name of the index in effect.

Syntax: recordsetobject. Index

LockType Property
Sets or returns a LockTypeEnum value that defines the type of locks that are in effect while editing records.

Syntax: recordsetobject. LockType

MarshalOptions Property
Sets or returns a MarshalOptionEnum value that specifies which records are to be transferred (marshaled) back to the server.

Syntax: recordsetobject. MarshalOptions

MaxRecords Property
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.

Syntax: recordsetobject. MaxRecords

PageCount Property
Returns a long value that is the number of pages contained in a Recordset object.

Syntax: recordsetobject. PageCount

PageSize Property
Sets or returns a long value that specifies how many records are on one page.

Syntax: recordsetobject. PageSize

RecordCount Property
Returns a long value that is the count of how many records are in a Recordset
object.

Syntax: recordsetobject. RecordCount

Sort Property
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.

Syntax: recordsetobject. Sort

Source Property
Sets or returns a string value that defines the data source for a Recordset object.

Syntax: recordsetobject. Source

State Property
Returns a long value describing if the Recordset object is open, closed, or in the process of connecting, executing, or retrieving.

Syntax: recordsetobject. State

Status Property
Returns a sum of one or more RecordStatusEnum values describing the status of the current record.

Syntax: recordsetobject. Status

StayInSync Property
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.

Syntax: recordsetobject. StayInSync

COLLECTIONS

Fields Collection
A collection containing all of the Field objects associated with a Recordset object.

Properties Collection
A collection of Property objects. Each Property object contains a provider-specific property.

METHODS

AddNew Method
Used to create a new record.

Syntax: recordsetobject. AddNew (FieldList, Values)

Cancel Method
Cancels the execution of a pending Open call.

Syntax: recordsetobject. Cancel

CancelBatch Method
Used to cancel a pending batch update. You must be in batch update mode.

Syntax: recordsetobject. CancelBatch (AffectRecords)

CancelUpdate Method
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.

Syntax: recordsetobject. CancelUpdate

Clone Method
Creates a duplicate copy of a Recordset object by copying an existing Recordset object.

Syntax: recordsetobject. Clone (LockType)

Close Method
Closes a Recordset object.

Syntax: recordsetobject. Close

CompareBookmarks Method
Returns a CompareEnum value that compares the relative row position of two bookmarks in the same Recordset object.

Syntax: recordsetobject. CompareBookmarks (Bookmark1, Bookmark2)

Delete Method
Deletes the current record, a group of records, or all records.

Syntax: recordsetobject. Delete (AffectRecords)

Find Method
Searches for a row in a Recordset that matches the given criteria.

Syntax: recordsetobject. Find (Criteria, SkipRows, SearchDirection, Start)

GetRows Method
Used to copy either all or a specified number of records into a two-dimensional array.

Syntax: recordsetobject. GetRows (Rows, Start, Field)

GetString Method
Returns the specified Recordset as a string.

Syntax: recordsetobject. GetString (StringFormat, NumRows, ColumnDelimiter, RowDelimiter, NullExpr)

Move Method
Moves the position of the current record pointer.

Syntax: recordsetobject. Move (NumRecords, Start)

MoveFirst Method
Moves the position of the current record pointer to the first record.

Syntax: recordsetobject. MoveFirst

MoveLast Method
Moves the position of the current record pointer to the last record.

Syntax: recordsetobject. MoveLast

MoveNext Method
Moves the position of the current record pointer forward to the next record.

Syntax: recordsetobject. MoveNext

MovePrevious Method
Moves the position of the current record pointer back to the previous record.

Syntax: recordsetobject. MovePrevious

NextRecordset Method
Clears the current Recordset object and returns the next Recordset object.

Syntax: recordsetobject. NextRecordset (RecordsAffected)

Open Method
When used on a Recordset object, this opens a cursor that is used to navigate through records.

Syntax: recordsetobject. Open (Source, ActiveConnection, CursorType, LockType, Options

Requery Method
Used to update (refresh) the data in a Recordset object. This is essentially equivalent to a Close followed by an Open.

Syntax: recordsetobject. Requery Options

Resync Method
Refreshes the data in the current Recordset object by re-synchronizing records with the underlying (original) database.

Syntax: recordsetobject. Resync AffectRecords, ResyncValues

Save Method
Saves the Recordset to a file or Stream object.

Syntax: recordsetobject. Save Destination, PersistFormat

Seek Method
Uses the index of a Recordset to locate a specified row.

Syntax: recordsetobject. Seek KeyValues, SeekOption

Supports Method
Returns a Boolean value that indicates whether or not a Recordset object will support a specific type of functionality.

Syntax: recordsetobject. Supports (CursorOptions)

Update Method
Used to save any changes made to the current row of a Recordset object.

Syntax: recordsetobject. Update (Fields, Values)

UpdateBatch Method
Writes all pending batch updates to the underlying database.

Syntax: recordsetobject. UpdateBatch (AffectRecords)

EVENTS

EndOfRecordset Event
Called if there is an attempt to move past the last row.

Syntax: EndOfRecordset (fMoreData, adStatus, pRecordset)

FetchComplete Event
Called after all records in an asynchronous operation have been retrieved.

Syntax: FetchComplete (pError, asStatus, pRecordset)

FetchProgress Event
Called periodically during an asynchronous operation. Returns a long value stating how many rows have been retrieved.

Syntax: FetchProgress (Progress, MaxProgress, adStatus, pRecordset)

FieldChangeComplete Event
Called after the values of one or more Field objects have been changed.

Syntax: FieldChangeComplete (cFields, Fields, pError, adStatus, pRecordset)

MoveComplete Event
Called after the current position in the database has changed.

Syntax: MoveComplete (adReason, pError, adStatus, pRecordset)

RecordChangeComplete Event
Called after one or more rows have been changed.

Syntax: RecordChangeComplete (adReason, cRecords, pError, adStatus, pRecordset)

RecordsetChangeComplete Event
Called when there have been any changes made to the Recordset.

Syntax: RecordsetChangeComplete (adReason, pError, adStatus, pRecordset)

WillChangeField Event
Called before the values of one or more Field objects are to be changed.

Syntax: WillChangeField (cFields, Fields, adStatus, pRecordset)

WillChangeRecord Event
Called before one or more rows are to be changed.

Syntax: WillChangeRecord (adReason, cRecords, adStatus, pRecordset)

WillChangeRecordset Event
Called before any pending changes are made to the Recordset.

Syntax: WillChangeRecordset (adReason, adStatus, pRecordset)

WillMove Event
Called before a pending operation can change the current position.

Syntax: WillMove (adReason, adStatus, pRecordset)

Copyright 1999-2001 by Infinite Software Solutions, Inc. All rights reserved.
Trademark Information