DataControl Recordset Property
ADO and RDS Objects
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