HOWTO: Maintain Binary Compatibility in Components Exposing ADO

ID: Q195049

The information in this article applies to:

Microsoft Data Access Components version 2.0
Microsoft Visual Basic Enterprise Edition for Windows, versions 5.0, 6.0

SUMMARY

Recompiling a Visual Basic Project that uses Binary Compatibility can generate a warning to the following effect:

   "...module has arguments and/or return type that is incompatible with a
    similar declaration in the version compatible component.
    ...
    Original Definition: Function <function_name> as ADODB.Recordset15
    Current Definition: Function <function_name> as ADODB.Recordset
   ..."

The dialog box offers a choice to either accept and break the compatibility or edit and preserve the return types or arguments.

The cause of the dialog box is because the component, now being compiled with ActiveX Data Objects (ADO) version 2.0, is exposing objects such as a Recordset and is attempting to maintain Binary Compatibility with the component compiled with ADO version 1.5.

STATUS

This behavior is by design.

MORE INFORMATION

Visual Basic code makes use of Version Independent ProgIDs such as "ADODB.Recordset". This Version Independent ProgID is then used to obtain a Class ID for that particular class when you compile the project. Under ADO 1.5 the Version Independent ProgIDs map to the ADO 1.5 Interface ClsIDs. When you attempt to recompile on ADO version 2.0, the Version Independent ProgIDs now map to the ADO 2.0 Interface ClsIDs. The ADO 2.0 Interfaces are not Binary Compatible with the ADO 1.5 interfaces.

To make the component Binary Compatible with Clients expecting an ADO 1.5 interface select the dialog box option that allows the code to be edited and make the ADO interface(s) exposed version-specific. For example, change the function declaration from a version independent declaration:

   Function <function_name> as ADODB.Recordset

to a version specific declaration:

   Function <function_name> as ADODB.[_Recordset15]

There is a previous version specific ProgID exposed for each of the main ADO objects, Recordset, Command, and Connection. Each are referenced in code as in the preceding example, prefaced with an underscore, postfixed with a version identifier and enclosed in square brackets.

After modifying the declarations, the project compiles without the Binary Compatibility warning.

Following is a more complete example of taking the ADO 1.5 code to ADO 2.0 and maintaining binary compatibility with ADO 1.5. The following example is an ADO 1.5 method that returns an ADO 1.5 RecordSet object:

   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.
       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.
       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

Here is the same function modified so that when compiled with ADO 2.0 it maintains binary compatibility with ADO 1.5:

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

       ' Set the CursorLocation to adUseClient to return an ADORecordset.
       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.
       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

The component or application that you compile against ADO 2.0 requires the ADO 2.0 components to run successfully even if your component or application only exposes ADO 1.5 interfaces. This is common practice when compiling with dependencies. If you recompile a component with a newer version of a dependency, the newer dependency becomes a baseline for the resulting component and you need to redistribute the newer dependency file with the component. This is no different than recompiling a Visual Basic application under a newer version of Visual Basic. The resulting application will not run if you do not distribute the new Visual Basic run- time .dll with the application.

The benefit of this implementation in Visual Basic is that the code can take advantage of the new features and benefits of ADO 2.0 and still remain binary compatible with clients expecting ADO 1.5 interfaces.

REFERENCES

For more information on binary compatibility, ProgID's and ClsID's, and COM please refer to the following books:

Inside COM (Programming Series), Dale Rogerson, Microsoft Press, February 1997.

Inside Distributed COM, Guy Eddon, Henry Eddon, Microsoft Press, April 1998.

Understanding ActiveX and OLE, David Chappell, Microsoft Press, September 1996.

Additional query words:

Keywords          : kbADO150 kbADO200 kbCompiler kbVBp500 kbVBp600 kbCmt 
Version           : WINDOWS:2.0,5.0,6.0
Platform          : WINDOWS
Issue type        : kbhowto

Last Reviewed: November 11, 1998