How To Write and Validate a Custom Business Object with RDS

Retired KB Content Disclaimer

View products that this article applies to.

This article was previously published under Q183315

SUMMARY

This article describes how to build, debug, and validate a custom business object for use with the Remote Data Service (RDS). The sample code is written in Visual Basic, however, the techniques demonstrated are valid regardless of the actual language you use to implement the business object (if the language can generate an ActiveX DLL).

Back to the top

MORE INFORMATION

The RDSServer.DataFactory business object provided by RDS has four methods. However, two are typically found in any given business object: the Query method, which returns a recordset, and the SubmitChanges method, which processes and attempts to post any changes made to that recordset. Your business object will likely need the equivalent of these two methods. In addition, two others will be handy for validating both the functionality and installation of your custom business object.

Back to the top

Method 1 - SumInt()

SumInt() tests if the Business Object can be created.

This is a simple method that returns the sum of two integers you provide as arguments. You would use this method to confirm that the business object can be created correctly from either the local or the remote client. If it fails, then either the business object is not correctly registered through Regsvr32.exe, or additional "safe for..." registry entries may be required on the server or the client.

   Public Function SumInt(FirstInt As Integer, _
    SecondInt As Integer) As Integer
      SumInt = FirstInt + SecondInt
   End Function

Possible causes for failure could include the following:

The business object is not registered safe for launching or the ProgID that is registered is misspelled. A registry key whose name matches the ProgID of the business object, "VBCustBusObj.cbo", must be added to the following location:
```
      \HKEY_LOCAL_MACHINE
         \SYSTEM
            \CurrentControlSet
               \Services
                  \W3SVC
                     \Parameters
                        \ADCLaunch 
					
```

Back to the top

Method 2 - ReturnRSValue()

ReturnRSValue() tests if the Recordset can be opened.

This method verifies that the connection and query information you are providing to the business object is correct. It will open but not return an ADO Recordset. It does return an array of variants for the first record in the recordset obtained by the GetRows method. If this is successful, then you know the Recordset you are requesting can be created on the server, which helps isolate any difficulty from an inability to receive it on the client.

Following is some sample code for the ReturnRSValue method:

   Public Function ReturnRSValue(strConnect As String, _
    strQuery As String) As Variant

   Dim adoCon1 As New ADODB.Connection
   Dim adoRs1  As New ADODB.Recordset
   Dim x As Variant    ' Variant array to send to the Client

  ' Open a connection to the Database.
   adoCon1.Open strConnect

  ' Open an ADO Recordset.
  adoRs1.Open strQuery, adoCon1, adOpenStatic, adLockBatchOptimistic


 ' Fill the Variant array using GetRows.
  x = adoRs1.GetRows(adGetRowsRest, adBookmarkFirst)

 ' Return the Variant array to the Client.
   ReturnRSValue = x

   End Function<BR/>

Possible causes of failure could include the following:

If you use ODBC to expose data to RDS, the data source name (DSN) must be a System DSN or a File DSN, not a User DSN.
The connection or query information is not correct and will not work whether you are using RDS to expose an ADO recordset or not.

Back to the top

Method 3 - ReturnRS()

ReturnRS() tests if a Recordset can be returned.

This method returns the recordset that ReturnRSValue() opened. This is actually an archetype method for a business object, and equivalent to the RDSServer.DataFactory's Query() method. However, because you are implementing this method yourself, you can take advantage of the full ADO Object model, such as using the Command object to open a parameterized stored procedure. The DataFactory would not be able to do this as it just creates a standalone Recordset object. However, you should open the exact same kind of recordset in ReturnRSValue() as ReturnRS().

Following is some sample code for this method:

   Public Function ReturnRS(strConnect As String, _
    strQuery As String) As ADODB.Recordset
       Dim adoCon1 As New ADODB.Connection
       Dim adoRs1 As New ADODB.Recordset

       ' Set the CursorLocation to adUseClient to return an
       ' ADORecordset to an RDS DataControl.
       adoCon1.CursorLocation = adUseClient

       ' Open ADO Connection with passed in connect string.
       adoCon1.Open strConnect

       ' Open ADO Recordset with passed in SQL string.
       adoRs1.Open strQuery, adoCon1, adOpenKeyset, adLockBatchOptimistic

       ' Return ADO Recordset object to Client.
       ' (Returns the actual recordset not just a pointer to it).
       Set ReturnRS = adoRs1

       ' Can not close the ADO Recordset object here,
       ' but it can be disassociated.
       Set adoRs1.ActiveConnection = Nothing

       ' Close ADO Connection object.
       adoCon1.Close

   End Function

Back to the top

Method 4 - EnhancedSubmit()

EnhancedSubmit() sends changes back to the DataStore.

This method accepts a recordset and uses it to re-open a connection to the underlying DataStore and submit, in batch, any of the changes you may have made to that recordset. For any records that were not posted to the DataStore, it provides details indicating why the failure may have occurred. It also returns a second recordset that contains just the records that failed to be posted to the DataStore.

This is actually an archetype method for a business object, and is a superset of the functionality found in the SubmitChanges() method of the RDS.DataControl and RDSServer.DataFactory.

Note that the method checks for the occurrence of error 3617, an undocumented RDS error. This may, depending upon the development environment you use, come back as either 0x80040E21 or -2147217887.

Following is some sample code for this method:

Public Function EnhancedSubmit(strConnect As String, _
                                  rs As ADODB.Recordset, _
                                  nPosted As Integer, _
                                  vStatus() As Variant)
       Dim i As Integer
       Dim s As String
       dim nConflict as integer
       Dim r As New ADODB.Recordset

       On Error GoTo ErrCond

       s = ""
       nPosted = 0
       nConflict = 0

       ' Re-establish connection, submit changes &
       ' count # affected records
       r.Open rs, strConnect
       r.UpdateBatch adAffectAll  ' Send in modifications
       r.Filter = adFilterAffectedRecords '
       nPosted = rs.RecordCount

       ' Determine if there are any conflicts and what type...
       ReDim vStatus(r.RecordCount)
       i = 0
       r.MoveFirst
       While r.EOF = False
           vStatus(i) = r.Fields(0).value & ":  "
           CheckStatus r.status, vStatus(i)
           ' Only report back errors, not accepted or unmodified recs(!)
           If (r.status <> adRecOK) And (r.status <> adRecUnmodified) Then
               If Len(s) > 0 Then s = s & vbCrLf
               s = s & vStatus(i)
               nConflict = nConflict + 1
           End If
           r.MoveNext
           i = i + 1
       Wend

       r.Close
       Set r = Nothing

       ' Set message to return to client
       If Len(s) = 0 Then
           s = s & "Success!  " & Str(nPosted) & " Records Posted."
       Else
           s = s & vbCrLf & _
               "Attempted to Post " & Str(nPosted) & " Records, " & _
               Str(nConflict) & " Conflicts Encountered(!)"
       End If

       EnhancedSubmit = s

       Exit Function

   ErrCond:

     Select Case Err.Number
            Case -2147217887 ' Raised when ALL records conflict
                s = "Conflicts Occurred in UpdateBatch!"
                Resume Next
            Case Else
                Test4_EnhancedSubmit = "FAILURE " & Str(Err.Number) & _
                                       "--" & Err.Description
        End Select
    End Function

The CheckStatus subroutine mentioned in the preceding code above is provided in the RDS series of samples listed in the references section and builds a string based on the flags that are set in the Recordset.Status property. You can use this to see why a given record failed. A variation on this conflict resolution code is provided in the RDS* series of samples, as well as the RDSENSUB sample also listed below.

Back to the top

General Diagnosis and Debugging Tips

Using a Local Client

When you write your client, you will not be able to step into the business object if RDS is used over HTTP to invoke it. You should consider the advantages of writing a local client which just instantiates the business object independent of RDS. This is easily done for Visual Basic for Applications, C++, or Java; however, if you are using VBScript, you should consider writing a Visual Basic Local Client to get the same effect.

This lets you validate the functionality of your business object, and debug any issues that might be there. Especially for Visual Basic-based business objects, as the compilation doesn't always catch syntax errors that the more rigorous C++ or Java Compilers would prevent.

Whatever methods the remote client using RDS invokes, you should also invoke with your local client to ensure the validation of the code within the business object.

However, there will be some differences in behavior with a local client. For example, the recordset MarshalOptions property will have no effect in a local client. Consider this code:

   rs.MarshalOptions = adMarshalModifiedOnly

This tells RDS to submit records only to the business object (custom or default) that are changed or added (and of course indicate any deletions that may have occurred). With your local client, as you are bypassing RDS, there is no marshalling; therefore, this property has no affect. The entire recordset is passed to the business object, not just the modified records.

Back to the top

REFERENCES

The techniques in this article are demonstrated by the RDS* Series of Samples. They demonstrate the three techniques for returning data in different languages/development environments, but also include a comprehensive business object, as well as a local and remote client for testing and validating that object. The current list of samples available follows:

183609 (http://support.microsoft.com/kb/183609/EN-US/ ) FILE: Rdsvb.exe Demonstrates How to Use RDS with Visual Basic

To see another example of conflict resolution, please see the following article in the Microsoft Knowledge Base:

177720 (http://support.microsoft.com/kb/177720/EN-US/ ) FILE: Rdsensub.exe with RDS Conflict Resolution Sample

Back to the top

APPLIES TO

Microsoft Remote Data Services 1.5
Remote Data Service for ADO 2.0
Microsoft Remote Data Services 2.1
Microsoft Remote Data Services 2.0

Back to the top

kbdatabase kbhowto KB183315

Back to the top

Retired KB Content Disclaimer

This article was written about products for which Microsoft no longer offers support. Therefore, this article is offered "as is" and will no longer be updated.

Back to the top