Visual Basic Concepts

Using rdoConnection Object Events

The rdoConnection object triggers a series of event procedures that can be used to make the job of managing connections and the queries associated with the connections easier. These events are triggered under the following conditions:

The QueryComplete, QueryTimeout, and WillExecute events fire for all queries executed on the associated rdoConnection. This includes those queries executed via the OpenResultset or Execute methods, as well as those executed from an associated rdoQuery object. The Query argument is an object reference indicating which query triggered the event. Using this argument, you can write a single event handler for all queries on the connection, but still customize the handler for specific queries. When executing queries against the rdoConnection object itself, RDO creates an rdoQuery object internally, and a reference to this internal rdoQuery is passed as the Query argument.

Using the BeforeConnect Event Handler

The BeforeConnect event gives you the opportunity to alter the connect string being passed to the ODBC SQLDriverConnect function. Your code can add a workstation ID or other parameter that might not have been supplied earlier. By filtering the connect arguments, you can prevent users from browsing unauthorized data sources or user names.

Using the Connect Event Handler

The Connect event permits your code to know when the connection operation has been completed for a specific connection object — that is, this event fires whether or not the connection operation succeeds. Each rdoConnection object can be declared to expose this event and all other connection-specific events.

The Connect event is especially helpful in situations where connections can take awhile to connect — as in wide area networks. Using this event is recommended over polling the rdoConnection object's StillConnecting property when using the rdAsyncEnable option of the OpenConnection or EstablishConnection methods. If the connect operation fails to establish a connection, the ErrorOccurred argument is set to True. At this point your code needs to examine the rdoErrors collection to determine the cause of the failure.

Using the QueryComplete Event Handler

When using asynchronous queries, you should always set up an event handler for the QueryComplete event that is fired when the query is complete. This event handler is established on a connection basis so all queries on the connection fire the same QueryComplete event.

While most ODBC drivers do not support more than one operation at a time, some do, so your QueryComplete event handler needs to be cognizant of which query has completed. The QueryComplete event is passed an object reference to the rdoQuery, which can be examined to indicate the query's name or other properties. If the query fails to establish a connection, the ErrorOccurred argument is set to True. At this point your code needs to examine the rdoErrors collection to determine the cause of the failure.

Using the QueryTimeout Event Handler

Not all queries complete immediately or even within a few minutes. However, unless you indicate the expected length of the query in seconds by setting the QueryTimeout property, the QueryTimeout event will fire after a set number of seconds; the default is 30 seconds. If your code passes False to the Cancel argument of the QueryTimeout event, RDO restarts the query timeout clock using the number of seconds in the QueryTimeout property. This feature can be especially useful when working with wide area networks that do not always execute queries in the same length of time.

Note   The QueryTimeout property is passed to the ODBC drivers when a query is started, so changing the property has no effect until you start another query.

Using the WillExecute Event Handler

This event is fired before the execution of a query, regardless of whether it is an action or row-returning query. You can trap this event to disallow the execution of certain queries, or to make last-minute adjustments to the SQL string.

The Cancel argument lets you disallow the query. For example, you can prescreen the query to make sure it has enough in the WHERE clause to avoid a table scan. In addition, you might wish to prohibit users from searching for customers with the last name of "Smith" without also providing a first name or street address. The Cancel argument defaults to False, but if you set it to True, the query will not be executed and RDO generates a trappable error indicating that the query was canceled.

An important aspect of this event is the ability to substitute or augment the operation with your own code. That is, you could execute your own set of operations including stored procedures to carry out the functions being performed. For example, if your remote database only permits updates through use of protected stored procedures, you can trap the WillExecute event to fire specific parameterized stored procedures to perform the update and use the Cancel argument to defeat the automatic operation being initiated.