How Event Handlers Work Together
All the event handlers in the ConnectionEvent and RecordsetEvent families must be implemented, regardless of whether you actually use events. The amount of implementation work you have to do depends on your programming language. For more information, see ADO Event Instantiation by Language.
Will and Complete event handlers can be used in pairs or separately.
Paired Event Handlers
- The following scenario depicts what happens when a Will event succeeds.
A Recordset object has paired WillChangeField and FieldChangeComplete events. In your application, you start to change the value of a field. The WillChangeField event handler is called. You return an indication that it is acceptable to change the field. The operation completes and a FieldChangeComplete event notifies your application that the operation has ended. The event handler status parameter reports the success of the operation.
- The following scenario depicts what happens when a Will event cancels an operation.
In the same application, you change another field. The WillChangeField event handler is called. You decide for some reason that it is not acceptable to change the field, so you return adStatusCancel in the status parameter. As a result, the operation does not complete.
The FieldChangeComplete event notifies you that the operation has ended. The event handler status parameter is set to adStatusErrorsOccurred; the error parameter refers to an Error object; and the Error object Number property is set to either an ADO or provider value indicating that the operation is canceled.
- More than one Will and Complete event handler can be called for the same operation. The following scenario depicts what happens when multiple Will events succeed.
A Recordset object has paired WillChangeField, FieldChangeComplete, WillChangeRecord, and RecordChangeComplete events. You start to change the value of a field; the WillChangeField event handler is called, and you return an indication that it is acceptable to change the field.
Next, the WillChangeRecord event handler is called, and once again you indicate that the operation should complete.
Note In general, all the Will event handlers pertaining to a particular instance of an ADO object will be called. However, they will be called in no particular order.
When the operation is complete, the FieldChangeComplete and RecordChangeComplete event handlers are called.
- More than one Will and Complete event handler can be called for the same operation, but one may cancel the pending operation. The following scenario depicts what happens when the last of multiple Will events cancels an operation.
Once again, a Recordset has paired WillChangeField, FieldChangeComplete, WillChangeRecord, and RecordChangeComplete events. You start to change the value of a field; the WillChangeField event handler is called, and you return an indication that it is acceptable to change the field.
Next, the WillChangeRecord event handler is called. Perhaps you determine the field change is acceptable in itself, but it will create an error in the record as a whole. You return adStatusCancel to indicate it is not acceptable to change the field. The WillChangeField event handler has already allowed the operation.
The operation does not complete because the WillChangeRecord event handler canceled it. The FieldChangeComplete event handler is called with the status parameter set to adStatusErrorsOccurred; the error parameter is set appropriately.
Next, the RecordChangeComplete event handler is also called with the status parameter set to adStatusErrorsOccurred. The matching Complete event is called for the Will event.
- More than one Will and Complete event handler can be called for the same operation, but one may cancel the pending operation. The following scenario depicts what happens when an event handler other than the last of multiple Will events, cancels an operation.
Once again, a Recordset has paired WillChangeField, FieldChangeComplete, WillChangeRecord, and RecordChangeComplete events. You start to change the value of a field; the WillChangeField event handler is called, and you return adStatusCancel to indicate it is not acceptable to change the field. The operation does not complete; the FieldChangeComplete event notifies you that the operation has ended with the status and error parameters set appropriately.
However, the WillChangeRecord (and thus the RecordChangeComplete) event handler is not called because the first Will event canceled the operation. In general, if a Will event cancels an operation, no remaining Will event handlers will be called.
Unpaired Event Handlers
You can turn off event notifications for any event by returning adStatusUnwantedEvent in the status parameter. For example, when your Complete event handler is called the first time, return adStatusUnwantedEvent. You will subsequently receive only Will events.
Single Will event handlers can be useful when you want to examine the parameters that will be used in an operation. You can modify those operation parameters or cancel the operation.
Alternatively, leave Complete event notification enabled. When your first Will event handler is called, return adStatusUnwantedEvent. You will subsequently receive only Complete events.
Single Complete event handlers can be useful for managing asynchronous operations. Each asynchronous operation has an appropriate Complete event.
For example, it can take a long time to populate a large Recordset object. If your application is appropriately written, you can start a Recordset.Open(...,adAsyncExecute) operation and continue with other processing. You will eventually be notified when the Recordset is populated by an ExecuteComplete event.
Single Event Handlers and Multiple Objects
The flexibility of a programming language like Microsoft Visual C++ enables you to have one event handler process events from multiple objects. For example, you could have one Disconnect event handler process events from several Connection objects. If one of the connections ended, the Disconnect event handler would be called. You could tell which connection caused the event because the event handler object parameter would be set to the corresponding Connection object.
Note This technique cannot be used in Visual Basic because that language can correlate only one object to an event.
Multiple Event Handlers and Single Operations
It is possible to associate one ADO object and its operations to multiple sets of events. For example, you could create multiple WillChangeField events so that each performs a particular field validation edit. If a field were about to change, one Will event could validate some aspect of the field value, then another Will event could validate a different aspect.
Preferably, you could simply perform or call all your edits from a single event handler.