Visual Basic Concepts

Understanding RemoteData Control Operations

Once your application begins, if sufficient properties have been set at design time, Visual Basic uses the RemoteData control to establish a connection to the ODBC data source. This creates an rdoConnection object by using the control's DataSourceName, UserName, Password, Options, CursorDriver, LoginTimeout, Prompt, and Connect properties. Notice that all of these properties are unique to the RemoteData Control, but are all exposed by the Data control using other properties as shown below:

If insufficient information is provided in the RemoteData control properties, the ODBC driver manager shows a dialog box to gather missing parameters, unless you have set the Prompt property to disable this dialog. If the user or your code does not provide sufficient parameters, a trappable error results.

If the connection is established, the RemoteData control sets or resets the Environment, Connection, DataSourceName, Transactions, and Connect properties based on the values used to establish the connection.

Once the connection is established, the RemoteData control immediately executes a query against the data source using the SQL, CursorDriver, Options, LockType, ErrorThreshold, and ResultsetType properties. This creates an rdoResultset object and sets the Resultset, ResultsetType, and Updatable properties. By default, a read-only, static rdoResultset is created. The StillExecuting property is set to True while the rdoResultset is created. If you choose to cancel the query, and the rdAsyncEnable option is set, you can use the Cancel method against the rdoResultset to terminate query processing.

Once the first row of the rdoResultset is available, the StillExecuting property is set to False and the RemoteData control passes column data to each bound control requesting data. The rdoResultset object's EOF property returns False and the RowCount property is set to a nonzero value if any rows resulted from the query. If no data is returned by the rdoResultset, the RemoteData control’s behavior is determined by the EOFAction property. For example, if EOFAction is set to rdAddNew, the RemoteData control's Validation event fires on the current row, followed by an automatic AddNew, followed by a Reposition event on the new row.

Note   Make sure that each bound control’s DataField property corresponds to the Name property of the rdoColumn object returned by the rdoResultset or an empty string (""). If it doesn't, a trappable error occurs.

When you are using an Image or PictureBox control bound to an image-containing field in a RemoteData Control (RDC), and the RDC uses batch cursors (CursorDriver = rdUseClientBatch), be aware that the Image or PictureBox control doesn't display the image. To correctly display the image, either set the RDC's Options property to 128 (rdFetchLongColumns), or use a different cursor.

Positioning the Current Row Pointer

Users can manipulate the RemoteData control with the mouse. They can move the current row pointer from row to row, or to the beginning or end of the rdoResultset by clicking the control. The RemoteData control doesn’t permit the user to move off either end of the rdoResultset using the mouse. You can’t set focus to the RemoteData control.

Keep the following guidelines in mind when writing code that will reposition to the current row pointer:

• Before each reposition, the bound controls that have changed data are queried for new data for the current row. The Validate event is invoked, and if not canceled by the action argument, the data source is updated if the data changed.
  
  
• After the RemoteData control positions to a new row in the data source, column data is passed to the bound controls and the Reposition event is invoked.
  
  
• Once either end of the rdoResultset is reached, the RemoteData control’s behavior is determined by the EOFAction and BOFAction properties.
  
  
• You can use the MoreResults method against the rdoResultset to complete processing of the current result set and determine if additional result sets are available. If MoreResults returns True, the process of handling the rdoResultset is restarted — just as if a new query had been executed. The previous result set is no longer available.