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. Some languages, like Microsoft Visual Basic, do all the work for you. Other languages, like Microsoft® Visual C++®, require you to do all the work. Microsoft® Visual J++™ with ADO/WFC takes the middle road and does much of the work for you. For more information, see ADO Event Instantiation by Language.
Although implementing the event handler yourself is more work, you can also do things that languages such as Visual Basic won't allow. For example, in Microsoft Visual C++ one RecordsetEvent handler can process notifications from operations on multiple Recordset objects.
Will and Complete event handlers can be used in pairs or separately.
Paired Event Handlers
Imagine paired WillChangeField and FieldChangeComplete events for a Recordset object. In your application, you start to change the value of a field. The WillChangeField event handler is called. You return an indication that it's acceptable to change the field. The operation completes and a FieldChangeComplete event notifies your application that the operation has ended. The event handler status operand reports the success of the operation.
Imagine that 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 operand. As a result, the operation does not complete.
The FieldChangeComplete event notifies you that the operation has ended. The event handler status operand 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 the operation is canceled.
Imagine paired WillChangeField, FieldChangeComplete, WillChangeRecord and RecordChangeComplete events for a Recordset object. You start to change the value of a field; the WillChangeField event handler is called, and you return an indication that it's 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 completes, the FieldChangeComplete and RecordChangeComplete event handlers are called.
Once again, imagine 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's acceptable to change the field.
Next, the WillChangeRecord event handler is called. Perhaps you determine the field change is alright 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 it was canceled by the WillChangeRecord event handler. The FieldChangeComplete event handler is called with the status operand set to adStatusErrorsOccurred; the error parameter is set appropriately.
Next, the RecordChangeComplete event handler is also called with the status operand set to adStatusErrorsOccurred. The matching Complete event is called for the Will event.
Once again, imagine the same set of paired event handlers as before. 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 handler 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 first Complete event handler is called, return adStatusUnwantedEvent and 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 turned on, and 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 very 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.
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, though less useful, to associate one ADO object and its operations to multiple sets of events. For example, you could create multiple WillChangeField events to each perform 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.
The reason why this isn't a very useful technique is that you could simply perform or call all your edits from a single event handler. However, we mention the idea for the sake of completeness.