As mentioned in the section titled
"Connection
Object Events," the Recordset is one of but two ADO objects that support events
and that you can declare using the WithEvents keyword.
Recordset event names
and functionality follow a similar pattern to those of Connection events: They
are mostly divided into two groups. One group, the Will events, happens just before
some action is about to take place; the other group, the Complete events, happens
just after an action has occurred.
The EndOfRecordset Event
This event fires when the cursor attempts to move past the first or last row
of the Recordset and the BOF or EOF property becomes True.
You can use this event to add new records at the end of the Recordset when
the record pointer attempts to navigate beyond the last record.
The EndOfRecordset event's parameters are as follows:
-
fMoreData - A Boolean that you must set to True if you add
records during the course of this event procedure. This signals ADO to find a
new end of the Recordset.
-
adStatus - If it is adStatusOK, you can set the value of adStatus
to adStatusCancel (the EOF action is cancelled), to adStatusCantDeny (meaning
that you can't cancel this event in the future) or adStatusUnwantedEvent (meaning
that the event won't fire again).
-
pRecordset - Points to the current Recordset that raised this
event (not needed in VB programming).
The Will Events
These Recordset events' names all begin with the word Will (hence, the term
Will events). Each Will event happens just before some action on the Recordset.
A list of the Recordset's Will events follows:
-
WillChangeField
-
WillChangeRecord
-
WillChangeRecordset
-
WillMove
Probably the most important parameter of each Will event is the adStatus parameter:
It tells you what the current status of the Recordset is, but, more interestingly,
you can change its value in the event procedure to either
-
prevent the pending action from occurring (set adStatus to adStatusCancel)
or
-
change the event's behavior for the rest of the current session: set adStatus
to adStatusUnwantedEvent to stop the event from firing again for this Recordset.
A brief description of each Will event and its parameters follows:
-
WillMove - Fires when the current row is about to change.
• adReason - An integer specifying the reason that the
move is going to occur. Possible values for this parameter in the context of a
move are these: adRsnMoveFirst, adRsnMoveLast, adRsnMoveNext, adRsnMovePrevious,
adRsnMove, adRsnRequery.
• adStatus - See earlier discussion.
• pRecordset - Pointer to current Recordset (not used in
VB).
-
WillChangeField - Fires when some action will cause one or
more fields in the record buffer to change. This could be due to a user edit with
the ADO Data Control or due to an assignment of a field's value in your code.
• cFields - Number of fields that will be affected, same
as number of elements of the Fields parameter.
• Fields - Variant array of Field objects representing
the fields in this record to be changed with this event.
• adStatus - See earlier discussion.
• pRecordset - Pointer to current Recordset (not used in
VB).
-
WillChangeRecord - Fires when one or more records in the underlying
data are to be changed through deletion, addition, or writing changes from the
record buffer to the underlying data.
• adReason - An integer specifying the reason that records
are going to be changed. Possible values for this parameter in the context of
a record change are these: adRsnAddNew, adRsnDelete, adRsnFirstChange, adRsnUndoAddNew,
adRsnUndoDelete, adRsnUndoUpdate, adRsnUpdate.
• cRecords - Number of records that will be affected with
this event.
• adStatus - See earlier discussion.
• pRecordset - Pointer to current Recordset (not used in
VB).
-
WillChangeRecordset - Fires before some action that will change
the entire Recordset across the board, including setting the Recordset to Nothing.
• adReason - An integer specifying the reason that the
Recordset is going to be changed. Possible values for this parameter in the context
of a Recordset change are these: adRsnRequery, adRsnResynch, adRsnClose, adRsnOpen.
• adStatus - See earlier discussion.
• pRecordset - Pointer to current Recordset (not used in
VB).
The Complete Events
There is a correspondingly named Complete event for each of the Recordset's
Will events described earlier. Just as a Will event fires before the actual completion
of an action, so a Complete event fires after the action has completed. The names
of the Complete events are as follows:
-
ChangeFieldComplete
-
ChangeRecordComplete
-
ChangeRecordsetComplete
-
MoveComplete
The Complete events all take the same parameters in the same order as their
respective Will events, with one addition: A pError parameter that comes just
before the adStatus parameter in all four event pairs and contains an Error object
that gives information about any error that occurred.
You can, of course, find out whether an error occurred by checking the adStatus
parameter for the value adStatusErrorsOccurred.
See Also
