Event Parameters

Every event handler has a status parameter that controls the event handler. For Complete events, this parameter is also used to indicate the success or failure of the operation that generated the event. Most Complete events also have an error parameter to provide information about any error that might have occurred, as well as one or more object parameters that refer to the ADO objects used to perform the operation. For example, the ExecuteComplete event includes object parameters for the Command, Recordset, and Connection objects associated with the event. In the following Microsoft Visual Basic example, you can see the pCommand, pRecordset and pConnection objects which represent the Command, Recordset, and Connection objects used by the Execute method.

Private Sub connEvent_ExecuteComplete(ByVal RecordsAffected As Long, _
     ByVal pError As ADODB.Error, _
     adStatus As ADODB.EventStatusEnum, _
     ByVal pCommand As ADODB.Command, _
     ByVal pRecordset As ADODB.Recordset, _
     ByVal pConnection As ADODB.Connection)

Except for the Error object, the same parameters are passed to the Will events. This gives you the opportunity to examine each of the objects to be used in the pending operation and determine whether the operation should be allowed to complete.

Some event handlers have a Reason parameter, which provides additional information about why the event occurred. For example, the WillMove and MoveComplete events can occur due to any one of the navigation methods (MoveNext, MovePrevious, and so on) being called or as the result of a requery.

Status Parameter

When the event-handler routine is called, the Status parameter is set to one of the following values.

If you determine in your Will event that the operation should continue, leave the Status parameter unchanged. As long as the incoming status parameter was not set to adStatusCantDeny, however, you can cancel the pending operation by changing Status to adStatusCancel. When you do so, the Complete event associated with the operation has its Status parameter set to adStatusErrorsOccurred. The Error object passed to the Complete event will contain the value adErrOperationCancelled.

If you no longer want to process an event, you can set Status to adStatusUnwantedEvent and your application will no longer receive notification of that event. Remember, however, that some events can be raised for more than one reason. In that case, you must specify adStatusUnwantedEvent for each possible reason. For example, in order to stop receiving notification of pending RecordChange events, you must set the Status parameter to adStatusUnwantedEvent for adRsnAddNew, adRsnDelete, adRsnUpdate, adRsnUndoUpdate, adRsnUndoAddNew, adRsnUndoDelete, and adRsnFirstChange as they occur.

Error Parameter

The Error parameter is a reference to an ADO Error object. When the Status parameter is set to adStatusErrorsOccurred, the Error object contains details about why the operation failed. If the Will event associated with a Complete event has canceled the operation by setting the Status parameter to adStatusCancel, the error object is always set to adErrOperationCancelled.

Object Parameter

Each event receives one or more objects representing the objects that are involved in the operation. For example, the ExecuteComplete event receives a Command object, a Recordset object, and a Connection 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, each time for a different reason. 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. If you want to process an event only when it occurs for a particular reason, you can use the adReason parameter to filter out the occurrences you are not interested in. For example, if you wanted to process record-change events only when they occur because a record was added, you can do something like this:

' BeginEventExampleVB01
Private Sub rsTest_WillChangeRecord(ByVal adReason As ADODB.EventReasonEnum, ByVal cRecords As Long, adStatus As ADODB.EventStatusEnum, ByVal pRecordset As ADODB.Recordset)
   If adReason = adRsnAddNew Then
       ' Process event
       '...
   Else
       ' Cancel event notification for all
       ' other possible adReason values.
       adStatus = adStatusUnwantedEvent
   End If
End Sub
' EndEventExampleVB01

In this case, notification can potentially occur for each of the other reasons. However, it will occur only once for each reason. After the notification has occurred once for each reason, you will receive notification only for the addition of a new record.

In contrast, you need to set adStatus to adStatusUnwantedEvent only one time to request that an event handler without an adReason parameter stop receiving event notifications.

See Also

ADO Event Handler Summary | ADO Event Instantiation by Language | How Event Handlers Work Together | Types of Events