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

Upgrading Embedded SQL applications

You can upgrade a SQL Anywhere Version 5 standalone application to use the Adaptive Server Anywhere Version 6 database server by upgrading the database server and the interface library. You do not need to upgrade the database or the client application itself.

The upgrade procedure uses 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.

     For a description of the compatibility library, see Using the compatibility library.

Components upgraded 

The following figure illustrates the changes you need to make in your setup in order to upgrade:

     For a description of the compatibility library, see Using the compatibility library.

  Upgrade procedures for Embedded SQL applications

This section provides step-by-step procedures for different kinds of Embedded SQL applications:

• Applications using an embedded database are standalone applications using the personal database server (dbeng50.exe for Version 5, dbeng6.exe for Version 6).

• Client/server applications connect across a network to the network database server. In Version 5, these applications use the dbclient.exe executable.

  To upgrade Embedded SQL applications that use an embedded database:

1. Install the Version 6 software     The Version 6 software contains components that enable Version 5 applications to continue working. You can either install into a separate directory or over the top of your Version 5 software.

   The installation places the Version 6 executable directory ahead of the Version 5 executable directory in your system path.

2. Ensure that your application is using the compatibility DLL     If necessary, copy the compatibility library dbl50?.dll from your Adaptive Server Anywhere executable directory to a place where your application will locate it.

   For example, you could copy the compatibility library to the same directory as the module of your application that loads it. The file dbl50?o.dll is installed into your Adaptive Server Anywhere executable directory. This directory must be in your path as this library is required by the compatibility library.

   At this stage, your Version 5 application should continue to work as before. However, it will be connecting to your database through the compatibility library rather than directly through the Version 5 interface library.

        If you have any problems at this stage, you need to check how your application locates the interface library. For information, see File locations and the compatibility library.

3. Create a new connection description     If your application obtains its connection parameters from configuration files, batch files, or the system registry, you should prepare a new description that uses the Version 6 database server. For example, Sybase Central stores connection descriptions in the system registry.

   • If you store a connection string that uses the DBF parameter to start the default database server, then the Version 6 database server is started automatically by the compatibility library, instead of the Version 5 database server. In this case, no new connection description is needed.

   • If you store a connection string that uses a Start Line parameter specifying dbeng50.exe, you must replace this with one specifying dbeng6.exe. If your application contains a hard-coded connection string, you need to take extra steps at this point.

          For more information on upgrading StartLine parameters, see Start parameters and the compatibility library.

   • If the database server is started in some other way, such as by a batch file or using a Windows NT service, you must reconfigure this so that the Version 6 database server is started instead.

4. Use the new connection description     With this step, you are using all Version 6 software and have completed your upgrade. The database itself does not need to be upgraded to work with existing applications.

  To upgrade Embedded SQL client/server applications:

1. Prepare for the upgrade     This step must be carried out at each client machine. You prepare for the upgrade by installing the Version 6 software.

   The installation places the Version 6 executable directory ahead of the Version 5 executable directory in your system path.

2. Ensure that your application is using the compatibility DLL     This step must be carried out at each client machine. If necessary, copy the compatibility library dbl50?.dll from your Adaptive Server Anywhere executable directory to a place where your application will locate it.

   For example, you could copy the compatibility library to the same directory as the module of your application that loads it. The file dbl50?o.dll is installed into your Adaptive Server Anywhere executable directory. This directory must be in your path as this library is required by the compatibility library.

   At this stage, your Version 5 application should continue to work as before. However, it will be connecting to your database through the compatibility library rather than directly through the Version 5 interface library.

        If you have any problems at this stage, you need to check how your application locates the interface library. For information, see File locations and the compatibility library.

3. Create a new connection description     This step must be carried out at each client machine. If your application obtains its connection parameters from configuration files, batch files, or the system registry, you should prepare a new description that uses the Version 6 database server. This description is for use when the server is upgraded.

   If you store a connection string that uses a StartLine connection parameter specifying dbclient.exe, you must replace this with a new one. The new connection description should either contain all the dbclient information as a set of parameters or should specify dbcli6.exe instead of dbclient.exe. If your application contains a hard-coded connection string, you need to take extra steps at this point.

        For more information on upgrading StartLine parameters, see Start parameters and the compatibility library.

        For more information on creating connection descriptions that capture the dbclient command-line information, see Capturing dbclient command-line information.

4. Upgrade the database server     This step must be carried out at the server machine.

   • As with any software upgrade, back up your database before upgrading.

   • Install Adaptive Server Anywhere on the server machine.

   • Start the Version 6 database server on the database.

5. Use the new connection description     This step must be carried out at each client machine. You need to use the new connection description to connect to the Version 6 server. With this step, you are using all Version 6 software and have completed your upgrade. The database itself does not need to be upgraded to work with existing applications.

  Using the version 5 utilities with Adaptive Server Anywhere 6.0

For the Version 5 database utilities, connection strings are supplied interactively. The Version 5 database utilities such as ISQL are Embedded SQL applications that search for the interface library in the following order:

1. The current directory

2. The Version 5 executable directory

3. The system path

For these applications, even though the compatibility library is ahead of the Version 5 interface library in the system path, the Version 5 compatibility library is located.

  To use Version 5 utilities with Adaptive Server Anywhere 6.0:

1. Make a backup copy of your interface library file.

2. Copy the compatibility library from your Version 6 executable directory to your Version 5 directory. For example, on Windows 95 and Windows NT, copy the file dbl50t.dll from the win32 subdirectory of your Version 6 installation to the win32 subdirectory of your Version 5 installation.

3. You can now run your Version 5 utilities against both Version 5 and Version 6 database servers.