MDAC 2.5 SDK - ADO


 

Event Parameters

See Also

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