The ADO Object Model - Asynchronous Processing
(Page 8 of 9 )
Asynchronous processing was a new feature in ADO 2.0 and allows commands to be executed at the same time as other commands. This is particularly useful when creating very large recordsets or running a query that may take a long time, because you can continue with another task and allow ADO to tell you via an event when the command has finished. You can also cancel a long-running command if you wish. Events can also be used to perform preprocessing and postprocessing around certain ADO operations, such as opening a Recordset or establishing a Connection.
Note that ASP scripting languages do not support events on the server. Client-side script does support events. |
Events
For ADO, only the Recordset and Connection objects support events. There are generally two types of events:
- Will… events—those called before an operation starts
- …Complete events—those called after it has completed
A few other events are called after an event has completed, but they are not part of the Will… and …Complete event pairs.
A Will… event is called just before the action starts. It gives you the chance to examine the details of the action, and to cancel the action if you decide not to run it. The …Complete event is called just after the action completes, even if the operation was cancelled. If it was cancelled, the Errors collection is filled with details of why it was cancelled.
The Will… events generally have an argument, adStatus, indicating the status of the event. You can set this argument to adStatusCancel before the method ends, to cancel the action that caused the event. For example, suppose a connection generated a WillConnect event; setting adStatus to adStatusCancel will cancel the connection. The ConnectComplete event will then be called, with a status indicating that the connection failed.
The nature of events means that there can be several Will… events that could result from a single action. Although all of these will be called, there is no guaranteed order in which this will happen.
Event Pairings The way the Will… and …Complete events are generated can often be confusing, especially in terms of what happens when you wish to cancel the operation that raised the event. The action triggers the Will… event, which has its own event procedure. This code runs, and then the action itself is run. After the action is finished, the …Complete event is triggered, which runs its event procedure. Once that has completed, execution will continue at the line after the action. The following diagram shows this using Connection events when opening a connection:
In the WillConnect event procedure, you can decide whether you want this action (that is, the objConn.Open) to occur or not. The event procedure has a parameter called adStatus, which you can use. If you set this to adStatusCancel before the event procedure finishes, the action is cancelled. The ConnectComplete event will still run, but its parameters will indicate that an error has occurred. For example, the following diagram shows how this can be trapped:
The important thing to note is that the ConnectComplete event is still generated, but the connection does not actually take place. Some actions may generate more than one event, so what happens then? Well, the Will… event is always generated before its associated …Complete event, but when two Will… events exist, the order in which they are generated is not guaranteed. If you cancel the action from within an event procedure, and this happens to run as the first event procedure, then the second set of event procedures (both the Will… and the …Complete) are never generated. For example, imagine a recordset where you have events to detect when fields and records change, as shown here:
Here the action has been canceled in the WillChangeRecord event procedure. The RecordChangeComplete event procedure runs, but indicates that an error occurred, and the actual action, that of setting the field value is not executed. The WillChangeRecord and RecordChangeComplete event procedures are not run.
These diagrams use Visual Basic, but language choice is not crucial; it’s the order of events that’s important.
Events in Visual Basic To use events within Visual Basic, you declare a variable by using the WithEvents keyword. This must be a module/form/class/control level or global variable, because WithEvents is invalid within procedures:
Private WithEvents m_rsAuthors As ADODB.Recordset
Note that the New keyword is omitted when using this syntax, because you can’t instantiate objects at the same time as declaring the variable with events. You must do this separately:
Set m_rsAuthors = New ADODB.Recordset
Once you have declared the variable, the object will appear in the objects list in the code combo and in a list of events in the event drop-down list (for a selected object). Selecting an event will create the event procedure.
 | This chapter is from ADO Programmer's Referencep,by David Sussman. (Apress Books, 2004, ISBN: 1590593421). Check it out at your favorite bookstore today. Buy this book now! |
Next: Connection Events >>
More ASP.NET Articles
More By Apress Publishing
/ 14 
