The rdoEngine Object

The rdoEngine object represents the remote data source and is created automatically
when you first make reference to an RDO object or the RemoteData control. As the top-
level object, it contains all the other objects in the hierarchy of Remote Data Objects. The
rdoEngine object is predefined, therefore you can’t create additional rdoEngine objects,
and it isn’t a member of any collection. You can use the rdoEngine to set data source
parameters and create additional rdoEnvironment objects.

Even though the rdoEngine is shared among the various applications that use it, the
rdoEngine default properties are not shared between applications. Each instance of your
application is provided with its own set of default values that have no effect on other
applications that also use RDO or the RemoteData control.

Note Adding the RemoteData control to your Toolbox does not automatically set a
reference to the Microsoft Remote Data Object library. To use the rdoEngine and Remote
Data Objects from code, you must set a reference to the Microsoft Remote Data Object
2.0 object library in the References dialog box (available from the Projects menu);
otherwise, you will get a compilation error when the first RDO object is referenced. Also,
If you have Visual Basic version 4.0 or Microsoft Office installed on your computer, the
RDO 1.0 library might appear in the list of object libraries exposed by the Project
References dialog. While using this library is possible with Visual Basic version 5.0 or
later, it is not recommended.

Features of Remote Data Objects

With RDO and the RemoteData control, your applications can access ODBC data sources
without using a local query processor. This can mean significantly higher performance
and more flexibility when accessing remote database engines.

By using RDO, you can:

 Create simple cursorless result sets, or more complex cursors.

 Run queries and process any number of result sets.

 Execute stored procedures that return result sets with or without output
parameters and return values.

 Execute action queries that perform data manipulation or data definition

operations.
  Limit the number of rows returned or processed.

 Monitor all of the messages and errors generated by the remote data source
without compromising the executing query.

 Enable synchronous, asynchronous, or event-driven asynchronous processing so

your application isn't blocked while lengthy queries are executed or the current
row pointer is repositioned.

About the User Connection Designer

The User Connection Designer uses Microsoft Visual Basic’s new class designer
architecture to provide design-time support for programmatic data access. It allows you
to create connection and query objects (based on Remote Data Objects) at design time.
These connections and queries are persisted as project-level objects. You can preset
properties, define new properties and methods, and write code behind the objects to trap
events.

This provides a simplified method for responding to events raised from connections and
queries as well as for calling stored procedures and client-defined queries at run time.

RDO and Client/Server Design Goals

RDO and the RemoteData control can help you meet a specific set of client/server
requirements. By using these remote data access features, you can:

 Gain high-performance data access against remote ODBC data sources. The
ability to quickly retrieve the results from complex queries is a goal of every data
access application. RDO provides a level of performance rivaled only by the
ODBC and VBSQL API programming models. By leveraging the remote data
engine, RDO greatly improves response time and user productivity.

 Manage return codes and both input and output parameters from stored
procedures. Output parameters are the only way to extract information from an
Oracle stored procedure, and are used heavily for singleton queries and many
administrative functions. In many cases, you cannot determine if a stored
procedure completed successfully without accessing the procedure’s return value.
RDO supports access to each of these parameters through the rdoParameter
object.

 Manage multiple result sets. By using a single query that returns several sets of
results, you can use the query processor and system resources more efficiently.
 You can improve performance by running a single query to gather data to fill
multiple data-driven list boxes and menus. In addition, by combining a row-count
query with a SELECT query, you can accurately set up scroll bars and progress
status bars.

 Submit multiple action queries in a single batch. In many cases, your

application can submit a set of INSERT, DELETE or UPDATE operations as a
single SQL statement. This increases performance, as it reduces network and
remote processing overhead and lets you manage transactions more easily.

 Limit the number of returned or processed rows. In situations where users

might select more rows than it is practical to handle, RDO implements a query
governor to limit the number of rows returned from any data source. This way,
you can predict query response time and more easily manage the workstation or
server resources required to maintain cursor keysets. Using the same mechanism,
you can limit the number of rows affected by a data-modification query.

 Utilize server-side cursors. Some servers, such as Microsoft SQL Server,

support cursor keysets that are created on the server, instead of on the
workstation. Under the right conditions, this type of cursor management can
significantly improve performance and reduce network load and workstation
resource requirements.

 Execute queries asynchronously. If a query takes an extended period of time to

run, you should have the option of either executing code while the query is being
processed or canceling the query. RDO provides an asynchronous query option
that you can use when executing any query, as well as a way to cancel an
asynchronous query. RDO also provides a unique event-driven asynchronous
programming interface that eliminates the need for polling loops. Asynchronous
processing extends to opening connections and when using the MoveLast method.

 Continue queries after initial timeout period. When a query exhausts the period
set in the QueryTimeout property, RDO permits you to override query
cancellation and continue waiting for another timeout period.

 Support improved polymorphism and "free-standing" object creation. RDO

now supports creation of rdoConnection and rdoQuery objects using the Dim
statement. These free-standing objects can be associated with other objects to
perform actions. For example, you can create an rdoQuery object independent of
any rdoConnection object and associate it with an open connection at a later time.

 Support dissociated result sets. RDO permits you to create a static read-write
cursor and break the connection with the remote server. The data in the
rdoResultset object remains available for access or changes. Once you re-
associate the result set with another rdoConnection object, you can use the
BatchUpdate method to post these offline changes to the database.
  Create and manage optimistic batch updates. While the ODBC cursor library
supports the concept of optimistic updates, it does so on a row by row basis rather
than a batch basis. This type of update operation consumes considerable network
and server bandwidth. RDO leverages the new Client Batch cursor library that
groups sets of rows to be inserted, updated, or deleted. This way, only one round
trip to the server is needed, thus improving update performance and decreasing
network traffic.

 Make the use of stored procedures easier. RDO permits you to express
parameterized queries and stored procedures as methods of a parent
rdoConnection object. You can pass parameters just as you would to any Visual
Basic function without having to manipulate any rdoParameter objects.

 Expose underlying ODBC handles. In cases where you need more flexibility or
control than is available in the object model, you should have a way to directly
access the data source. RDO provides access to the ODBC environment,
connection, and statement handles.

 Reduce memory footprint. In many cases, the system that hosts a client/server
front-end application is limited in RAM capacity. Because of this, it is important
that applications designed for these systems economize their use of RAM and
other workstation system resources. The RDO memory footprint is dramatically
smaller than other programming models, and it does not require the use of local
memory or disk space for its lowest-level cursors.

Creating Remote Data Objects

You can use the RemoteData control to create RDO objects, just as you can use the Data
control to create DAO objects. You can also create result sets using RDO methods and
pass them to the RemoteData control for management and editing by associated bound
controls.

Remote Data Objects are also created by using methods on the parent object, or by
declaring the objects with the Dim statement. If you use the Dim as New statement to
instantiate a new object, the object is not appended to the associated collection. The
following table shows how to create each of the primary Remote Data Objects:

Remote Data Object How created

rdoEngine Created automatically.
rdoEnvironment First instance created automatically.
rdoEngine.rdoCreateEnvironment
rdoConnection rdoEnvironment(x).OpenConnection
(can also be created by the RemoteData control)
Dim MyCn as New rdoConnection
rdoQuery rdoConnections(x).CreateQuery
 Dim MyQry as New rdoQuery
rdoResultset rdoQuery(x).OpenResultset
rdoConnection(x).OpenResultset
(can also be created by the RemoteData control)
rdoParameter Created automatically for parameter queries.
rdoTable Created automatically when referenced.
rdoError Created automatically when ODBC errors or messages are
returned.

You can use the rdoEnvironment object's OpenConnection method to open connections
to the data source.

In an rdoEnvironment, you can open multiple connections (each accessing its own
database), manage transactions, and establish security based on user names and
passwords. For example, you can:

 Create an rdoEnvironment object using the Name, Password, and UserName

properties to establish a named, password-protected environment. The
environment creates a scope in which you can open multiple connections and
manage multiple ODBC transactions.

Use the OpenConnection method to establish one or more connections in that

rdoEnvironment.