New Features and Upgrading Guide
   CHAPTER 5. Upgrading to Adaptive Server Anywhere     

Using the compatibility library

The compatibility library is a dynamic library (a DLL on PCs, shared library on UNIX) that enables Embedded SQL applications to work with both Version 5 and Version 6 database servers. This section describes how the compatibility library works.

  The Version 5 Embedded SQL interface library

All client machines running SQL Anywhere Version 5 applications, whether connecting over a network or to a personal server, have a SQL Anywhere Version 5 interface library.

• For Windows 95 and Windows NT, this library is a DLL named dbl50t.dll.

• For Windows 3.x, this library is a DLL named dbl50w.dll.

• For OS/2, this library is a DLL named dbl502.dll.

In this documentation, these files are written as dbl50?.dll.

  How Version 5 client applications locate the interface library

Version 5 client applications locate the interface library in one of the following ways:

• ODBC applications     ODBC applications connect to a SQL Anywhere database using the SQL Anywhere ODBC driver. The SQL Anywhere Version 5 ODBC driver calls functions in the Version 5 Embedded SQL interface library.

• Embedded SQL applications     Embedded SQL applications for Windows operating systems and OS/2 call into the interface library. In these calls, the interface library is referenced by name—dbl50t.dll for Windows 95 and NT.

  The SQL Anywhere Version 5 ODBC driver is an Embedded SQL application.

  Using the compatibility library

The compatibility library is optionally installed as part of the Version 6 client software. It provides support for two interface libraries at the same time. You should check your installation to confirm that it is installed.

The setup program should ensure that your application calls the compatibility library instead of the Version 5 interface library.

The setup program carries out the following steps to ensure that applications call the interface library.

• The compatibility library has the same name as the SQL Anywhere Version 5 interface library. For example, on Windows NT, the compatibility library is named dbl50t.dll.

• The compatibility library is installed into the same directory as other Version 6 software.

• The Version 6 installation directory is placed ahead of the Version 5 directory in the system path. This ensures that applications locate the compatibility library ahead of the Version 5 interface library.

• A Version 5 interface library is installed into the same directory as the compatibility library, but with the name dbl50to.dll. When the compatibility library is accessing Version 5 servers, it calls this interface library.

• The Version 6 interface library is installed into the same directory as the compatibility library. It has the name dblib6.dll on Windows NT. When the compatibility library is accessing Version 6 servers, it calls this interface library.

If you have problems using the compatibility library, you should check the order of the directories in your path, and ensure that the Version 6 location is ahead of the Version 5 location in the path.

  How the compatibility library works

Using the supplied connection string, the compatibility library attempts to connect to an Adaptive Server Anywhere database using the Adaptive Server Anywhere Version 6 interface library. If this attempt fails, it attempts to connect to a SQL Anywhere database using the SQL Anywhere Version 5 library.

The following figure illustrates how the compatibility library enables communications to both a SQL Anywhere Version 5 and an Adaptive Server Anywhere Version 6 database server. The number in the lower right hand corner of the boxes indicates the version of the software component.

The following figure illustrates the algorithm used by the compatibility library to connect to a server:

  File locations and the compatibility library

The compatibility library and the Version 5 interface library have the same file name (dbl50?.dll). For your application to use the compatibility library, it must locate it ahead of the Version 5 interface library when it searches for DLLs.

To ensure that your application locates the compatibility library ahead of the Version 5 interface library you must understand how your application searches for DLLs.

Searching for DLLs 

The Version 6 installation program places the Version 6 executable directory ahead of the Version 5 directory in the system path, so any application that is searching in the system path for dbl50?.dll will find the compatibility library ahead of the Version 5 interface library. If your application searches in a different manner, you must ensure that the compatibility library is located.

Testing to see which library is located 

You can test to see which library is located in the following ways:

• Attempt to connect to a Version 6 database server. You cannot connect using the Version 5 interface library.

• Specify a database file parameter (DBF) and no start line in your connection string. If the Version 5 interface library is located, the SQL Anywhere Version 5 standalone database engine is started. If the compatibility library is located, the Version 6 personal database server is started.

  Start parameters and the compatibility library

Applications using a connection string that includes a StartLine connection parameter face some additional issues in upgrading.

The StartLine parameter provides explicit instructions for starting the database engine or the SQL Anywhere Client executable. Sample StartLine parameters are as follows:

• Standalone application     A sample StartLine parameter for a Version 5 standalone application is as follows:

  dbeng50.exe -c 8M

• Network client application     A sample StartLine parameter for a Version 5 network client application is as follows:

  dbclient.exe -x tcpip 

In Version 6, the dbeng50.exe executable is replaced by the personal database server dbeng6.exe. The dbclient.exe executable is no longer required in Version 6, but a compatibility client (dbcli6.exe) is provided.

     For a description of the compatibility client, see Capturing dbclient command-line information.

  To upgrade StartLine parameters:

1. The procedure depends on where your connection parameters are stored.

   • If your connection parameters are stored outside the application itself, then you need to alter the connection parameters to use the appropriate dbeng6.exe or dbcli6.exe executable names instead of dbeng50.exe and dbclient.exe.

     All the information on the dbclient command line can be rephrased in terms of other connection parameters. You can avoid using the dbcli6.exe compatibility client by rewriting your connection parameters using these parameter. For information, see Connection and Communication Parameters.

   • If your connection parameters are hard-wired into your application, you must either relink your application with a new connection string, or rename the dbcli6.exe compatibility client as dbclient.exe, and replace the Version 5 client executable with the renamed Version 6 one.

     There are many possible configurations of client command lines and connection parameters. Be sure you test any solution thoroughly before deploying.