Rdsvb.exe Demonstrates How to Use RDS with Visual Basic

ID: Q183609

The information in this article applies to:

Remote Data Service for ADO versions 1.5, 2.0, 2.1 SP2

SUMMARY

Rdsvb.exe is a sample that demonstrates using Remote Data Service (RDS) within Visual Basic.

NOTE: This sample was originally written for RDS version 1.5, but works properly with RDS version 2.0 and later.

MORE INFORMATION

The following file is available for download from the Microsoft Software Library. Click the file name below to download the file:

Rdsvb.exe

Release Date: April-09-1998

For more information about how to download files from the Microsoft Software Library, please see the following article in the Microsoft Knowledge Base:

Q119591 How to Obtain Microsoft Support Files from Online Services

The Remote Data Service is a mechanism for remoting a recordset from a server running Internet Information Server (IIS) or Personal Web Server (PWS) to a client computer over HTTP, HTTPS, or DCOM. Key concepts that the Rdsvb.exe sample demonstrates include the following:

- Building, debugging and testing a custom business object.

- Conflict resolution when submitting changes to the server.

- The "Three Techniques" for returning a recordset to a client using RDS, which include:


       a. Using the RDS.DataControl within Visual Basic.


       b. Using the RDS.DataSpace to generate a recordset from the
          default RDS business object, RDSServer.DataFactory.


       c. Using the RDS.DataSpace to generate a recordset from a custom
          business object.

- Generating a dynamic recordset using the CreateRecordset() method.

Visual Basic for Applications (VBA) within Visual Basic remains probably the simplest technical way to implement a RDS application, but it also has an advantage for non VBA-developers in that it lets you focus just on the RDS technology and not any additional issues that may arise from using COM in C++ or Java. The only drawback is a limitation of the RDS.DataControl, which only allows binding of graphical controls within the Active Server Page (ASP) environment. However, you can still manipulate this RDS object programmatically.

About the RDSVB Sample

The Rdsvb.exe sample implements three separate projects to demonstrate the use of RDS with Visual Basic. After extracting the project (using the -d switch to preserve the sub-directory structure required by the sample), you will see the following three directories:

BusObj - An ActiveX DLL that has several methods both for validating the business object as well as for common activities used with RDS such as, conflict resolution and submitting a dynamically created Recordset.

Local - Contains a minimalist interface for testing the business object outside of RDS.

Remote - RDS Client implemented in Visual Basic that utilizes the Remote Data Service, and in particular, exercises the custom business object included with the sample.

In addition, the RDSVB sample provides a Microsoft Access database, Rdsdemo.mdb, which assumes you will create an ODBC System data source name (DSN) named RDSDemo. Some of the code in RDSVB is written specifically for this .mdb file. The code that lets you test conflict resolution assumes that it is working with a table having two columns, the first numeric, the second string. The code demonstrating the three techniques makes no assumptions about the data returned.

The BusObj Project

The BusObj project builds an ActiveX DLL (Vbcbo.dll) that has five public functions exposed. These functions demonstrate RDS functionality, as well as helper routines for validating your business object. Because you can not actually debug (step into) a business object when invoked by the Remote Data Service, these routines help provide information to diagnose any difficulties you might encounter during development.

The ProgID for the BusObj project is VBCustBusObj.CBO, and it references the following two typelibs:


   - Microsoft ActiveX Data Objects Library (Msado15.dll)
   - Microsoft Remote Data Services Server Library (Msadcf.dll)

The Local Project

When implemented, the business object is registered and stored on a computer supporting Internet Information Server versions 3.0 and later. The client is typically on a remote computer, and while you may be able to debug the client on that remote computer, you will not be able to step into the business object and walk through its code. Therefore, you need a local client that you can run and use to debug the business object without using RDS to invoke it.

Visual Basic SPECIFIC: For Visual Basic, you should have both the local client and business object projects in the same project group. This is provided in the RDSVB sample through the Localtst.vbg file.

The Local Project is just for testing the business object, and has enough of an interface to accomplish this. Specifically, the user must provide the following:

A Connection String used to specify the datastore to be opened.

A Query used to return data from the underlying datastore.

A ProgID of the Business Object to be invoked.

Once provided, there are four buttons the user can use to validate the functionality of the business object:

Create Custom Business Object and Open Recordset

This button invokes the business object and calls the first three test methods. A recordset is cached locally upon successful completion of the underlying functionality.

Automatically Add Record

This button adds a record to the recordset returned previously by the business object. You use this button with multiple instances of either the local or remote client to test conflict resolution.

This method looks at the last record in the Authors table, and adds a new one with a key 1 greater than the last existing record. If that record, say, has a key of 10, then a new record with a key of 11 is created. However, it is not posted to the datastore, so if multiple instances are running, each creates a new record with a key of 11. The first instance to submit its changes will (likely) post successfully. The next instance to attempt to submit its changes to the datastore fails, demonstrating the conflict resolution code of the custom business object.

Submit Changes to Custom Business Object

This method posts changes made to the recordset, such as records added with the previous button, to the business object. If any conflicts occurred, the business object returns details on which records failed.

Create and Submit Dynamic Recordset

This demonstrates how to use the CreateRecordset method to build a dynamic recordset, programmatically, and then pass it to the business object. This method actually cheats, because in theory your client application should be separate from RDS. However, in order to create a recordset programmatically, you have to do so with either the RDSServer.DataFactory or RDS.DataControl. To eliminate any dependence upon having IIS available, the sample uses the RDS.DataControl.

The Local Project references the following two typelibs:

Microsoft ActiveX Data Objects Recordset 1.5 Library (Msado15r.dll)

Microsoft Remote Data Services 1.5 Library (Msadco.dll)

The Remote Project

The Remote Project extends the functionality offered in the Local Project in the following ways:

The "Three Techniques" for retrieving data mentioned previously are demonstrated.

Up to two columns from the recordset returned by each of the three techniques is visible, and navigation through the recordset is provided.

The Remote Data Service is used to generate the business object. The Local project let us validate the third technique, by returning a recordset from a custom business object when that business object was invoked standalone. Now, the Remote sample demonstrates using RDS to invoke the business object to verify the same functionality.

Possible Causes for Failure of the Remote Project:

An incorrect URL was provided for the server running IIS/PWS, or else the server is not actually running.

If you were testing with Local, it's possible an older version, or one without binary compatibility, of the business object is still loaded in memory. (In this case make sure you rebuild the DLL with binary compatibility, and that you do not have the Local Project open or executing, and therefore potentially the DLL still loaded in memory.


  - Microsoft ActiveX Data Objects Recordset 1.5 Library (Msado15r.dll)
  - Microsoft Remote Data Services 1.5 Library (Msadco.dll)

Configuring and Running the RDSVB Sample

If you have not already, create a System DSN named RDSDemo for the Rdsdemo.mdb file included with the project.

Step 1: Compile and Build the Custom Business Object

You can register the Custom Business Object by hand, or use the ClsidView sample that allows you to view and manipulate registry settings. For more information on this sample, please see the references section.

Compile and build the DLL.

Using Regsvr32.exe, register the DLL in the location you want it to reside on the Web server.

Add the Registry key so that the business object is safe for launching:


\HKEY_LOCAL_MACHINE
          \SYSTEM
              \CurrentControlSet
                 \Services
                    \W3SVC
                        \Parameters
                            \ADCLaunch
                               \VBCustBusObj.CBO]

You can now verify the business object with the Local client. Visual Basic SPECIFIC: Once the DLL has been rebuilt, the project settings do not indicate that binary compatibility is to be maintained. The first time you build the DLL on your system, the Project Properties on the Component Tab should be set to No Compatibility, but after that you should change it to Binary Compatibility and set the path to the DLL.

Step 2: Verify the Local Client

It is not necessary to have Visual Basic on the server, but it is convenient. However, you can register the business object on your development computer and test it with the Local client independent of a Web server, although RDS Client Components are required(!)

Compile and build the Local Client.

Try each of the buttons in order. If you need to debug the business object, you will want to open the LocalTst.vbg Visual Basic Group file, instead of the Local Visual Basic Project file.

To test conflict resolution, start two instances of the compiled EXE, and try running.

Step 3: Verify the Remote Client

First, we will assume you are running the remote client on the same computer running the Web server where the RDS Server Components are installed.

Open the Remote project. For your convenience, you might want to change the properties for the Server text box to indicate the URL of the server the Custom Business Object is registered on.

Compile and build the Remote project.

Open two instances of the compiled EXE. Try each of the techniques, and observe the results that occur when both EXEs try to post a new record with the same primary key.

REFERENCES

For additional information on using RDS in Visual Basic, click the article number below to view the article in the Microsoft Knowledge Base:
Q183609 FILE: Rdsvb.exe Demonstrates How to Use RDS with Visual Basic

The conflict resolution code used in the custom business object was inspired (and abbreviated) from the RDSENSUB sample. RDSENSUB does offer somewhat more comprehensive conflict resolution than presented in this sample, such as, optionally rolling back any changes if a conflict occurred, checking if changes were made before calling the business object to perform the submit, returning a recordset back with the records that generated specific conflicts, and so on. However, this sample has only been written in VBA and requires translation of the additional functionality to C++/Java/VBScript. For additional information, please see the following article in the Microsoft Knowledge Base:

Q177720 FILE: Rdsensub.exe with RDS Conflict Resolution Sample

For more information on writing and validating a custom business object or the methods exposed by the Vbcbo.dll, please refer to the following article in the Microsoft Knowledge Base:

Q183315 HOWTO: Write and Validate a Custom Business Object with RDS

For more information on the three techniques for returning data via RDS, please see the following article in the Microsoft Knowledge Base:

Q183294 INFO: Techniques for Returning a Recordset via RDS

Additional query words:

Keywords : kbfile kbDatabase kbGenInfo kbRDS kbRDS200 kbVBp kbGrpVBDB kbGrpMDAC kbDSupport kbRDS210SP2
Version : WINDOWS:1.5,2.0,2.1 SP2
Platform : WINDOWS
Issue type : kbhowto