Rdsvb.exe demonstrates how to use RDS with Visual Basic

MORE INFORMATION

The following file is available for download from the Microsoft Download Center:
Release Date: October 29, 1999

For more information about how to download Microsoft support files, click the following article number to view the article in the Microsoft Knowledge Base: Microsoft scanned this file for viruses. Microsoft used the most current virus-detection software that was available on the date that the file was posted. The file is stored on security-enhanced servers that help prevent any unauthorized changes to the file.
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:
  
  
• Using the RDS.DataControl within Visual Basic.
• Using the RDS.DataSpace to generate a recordset from the default RDS business object, RDSServer.DataFactory.
• 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 Pages (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. The Remote 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)
  					

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.

1. Compile and build the DLL.
2. Using Regsvr32.exe, register the DLL in the location you want it to reside on the Web server.
3. 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(!)

1. Compile and build the Local Client.
2. 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.

1. 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.
2. Compile and build the Remote project.
3. 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. Now repeat this process, only distribute the Remote Client to another computer on the network.