Event Parameters
Every event handler has a status parameter that controls the event handler. Most Complete events have an error parameter to report whether the operation causing the event succeeded, as well as an object parameter to identify the ADO object to which the operation applied. (The ExecuteComplete event actually includes object parameters for the Command, Recordset and Connection objects associated with the event.)
The parameters are also passed to the Will events to be used in the pending operation. This gives you the opportunity to examine the parameters and determine whether the operation should complete.
Some event handlers have a reason parameter, which provides additional information about why the event occurred.
Status Parameter
When the event handler routine is called, the status parameter is set to one of the following informational values.
| Value | Description |
|---|---|
| adStatusOK | The operation that caused the event occurred successfully. |
| adStatusErrorsOccurred | The operation that caused the event occurred unsuccessfully, or a Will event canceled the operation. Check the error parameter for more details. |
| adStatusCantDeny | A Will event cannot request cancellation of the operation about to occur. |
Before the event handler routine returns, leave the status parameter unchanged or set it to one of the following request values.
| Value | Description |
|---|---|
| adStatusUnwantedEvent | Request that this event handler receive no further notifications. |
| adStatusCancel | Request cancellation of the operation that is about to occur. |
Depending on event type, the status parameter can have one of the following values when the event handler is called.
| Event Type | Value |
|---|---|
| Will | adStatusOK, adStatusCantDeny |
| Complete | adStatusOK, adStatusErrorsOccurred |
Depending on event type, the status parameter can have one of the following values when the event handler returns.
| Event Type | Value |
|---|---|
| Will | adStatusOK, adStatusCancel, adStatusUnwantedEvent, adStatusCantDeny |
| Complete | adStatusOK, adStatusUnwantedEvent |
Error Parameter
The error parameter is a reference to an ADO Error object containing details about why the operation failed if the status parameter equals adStatusErrorsOccurred.
Object Parameter
The object parameter is a reference to the ADO object for which the operation applies. (The ExecuteComplete event actually includes object parameters for the Command, Recordset and Connection objects associated with the operation.)
Note The object parameter does not apply to Microsoft Visual Basic. You must create separate event handlers for each object.
Reason Parameter
The reason parameter, adReason, provides additional information about why the event occurred. Events with an adReason parameter may be called several times, even for the same operation, but for a different reason each time.
For example, the WillChangeRecord event handler is called for operations that are about to do or undo the insertion, deletion, or modification of a record. Use the adReason parameter as a filter to process only particular events.
You must return adStatusUnwantedEvent in the adStatus parameter to request that an event handler without an adReason parameter stop receiving event notifications. However, an event handler with an adReason parameter may receive several notifications, each for a different reason. Therefore, you must return adStatusUnwantedEvent for each notification caused by a different reason.
For example, assume you have a WillChangeRecord event handler coded in Visual Basic. If you don't want to receive any further notifications, simply code the following:
adStatus = adStatusUnwantedEvent
However, if you want to process events where the row is about to be deleted, but cancel notifications for all other reasons, then code the following:
if (adReason = adRsnDelete)
' Process an event for this reason.
...
else
' Stop receiving events for any other reason.
adStatus = adStatusUnwantedEvent
...