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

Capturing dbclient command-line information

Version 5 client applications that connect to a database server do so via the SQL Anywhere Client, an executable named dbclient.exe. The client executable command line contains information needed to locate a server, including the following:

• Default server name     The server name on the client command line is the default server name. When a client executable is running, the application does not need to supply a server name in order to connect to the default server.

• Network communications parameters     A listing of network protocols to use together with a set of communications parameters specifies where the client executable is to look as it attempts to locate a server.

• Client/Server communication tuning     A set of parameters allows the packet size, buffer size, and so on to be tuned for optimum performance.

In Version 6, this information is held in an ODBC data source along with other connection information. As there is no longer a client executable, there is no longer a client command line. In Version 6, Embedded SQL applications can use ODBC data sources as a source of connection parameters.

Client command line scope 

Only one Version 5 client executable can be run at a time, and it may be used by more than one application and handle connections to more than one server. The command-line information is therefore global to the machine.

  How to capture client command-line information

During upgrade to Version 6, you must ensure that Version 5 dbclient command-line information is captured in such a way that the Version 6 ODBC or Embedded SQL applications can use it. You can do this in one of the following ways:

• Place the information in an ODBC data source     If the information can be placed in a data source, you can use it with Version 6 ODBC or Embedded SQL applications.

• Use the SQLCONNECT environment variable     The SQLCONNECT environment variable contains a connection string. It is searched early in the process of establishing which connection parameters to use. You may be able to use SQLCONNECT settings to override connection parameters.

• Use the dbcli6 executable     If the information cannot be placed in a data source, you can use an executable named dbcli6.exe, which makes the command-line information available to the Version 6 interface libraries.

The way to capture client command-line information depends on where the information is located.

Where command-line information is located 

Your existing command line information may be held in one of the following places.

• ODBC data source     The ODBC data source contains a START parameter that can hold a client executable command-line.

• As a connection string     Your application may obtain client information (for example from an initialization file), and supply it in a connection string as the START parameter.

• A batch file     You may have a batch file that includes a client executable command line as part of your startup process.

• Under an icon     You may have a client executable command line under an icon on your desktop.

How to capture the information 

• From an ODBC data source     The ODBC data source upgrade captures the information in an ODBC data source START parameter.

• From a batch file or under an icon     You can replace the reference to dbclient.exe in the batch file with dbcli6.exe. The dbcli6.exe executable is provided for compatibility reasons only, and makes the command-line parameters available to Version 6 interface libraries.

• From a connection string     If the application retrieves information from an initialization file or other editable source, you can replace references to dbclient.exe with dbcli6.exe.

• Hard-wired connection strings     Only if you have a hard-wired connection string in your application (that is, one that cannot be edited), you must alter the source of the application and recompile.

  How the compatibility client executable works

The Version 6 compatibility client executable does not serve the same purpose as the Version 5 client executable. Instead, it simply places the command-line parameters into a specially-named data source and terminates.

The compatibility data source is named dbcli6 Connection Parameters.

When dbcli6.exe is needed 

The Version 6 compatibility client is only needed when the existing Version 5 application runs the client from outside an ODBC data source.

If the ODBC data source contains a START parameter that holds the dbclient command line, this information is captured in Version 6 form when the ODBC data source is upgraded, and you do not need to use the Version 6 compatibility client.

If you store the client command line in a batch file, under an icon on your desktop, or in an initialization file used by an Embedded SQL application, you need to replace dbclient with dbcli6.exe in this command line.

Typical use for the compatibility client 

The most common method of using the client in Version 5 applications is as follows:

1. The dbclient command line includes a server name. This server name is the default server for connections made through that client.

2. The client application runs without specifying a server. The Version 5 interface library locates the client, and connects to its default server.

How the compatibility data source works 

When you replace dbclient with dbcli6 in the client command line, the following set of steps takes place:

1. When the dbcli6 command line is executed, the compatibility client creates a data source named dbcli6 Connection Parameters, and then stops.

   The special data source, named dbcli6 Connection Parameters, is called a compatibility data source. The name is reserved for use by the compatibility client, and you should not use it for any other purpose.

2. The client application starts. Its connection string is handed to the compatibility library.

3. The compatibility library attempts to connect to a Version 6 server.

   • The connection string does not contain a server name (no ENG connection parameter). The next step in the process is to search for a data source.

   • As the connection string is from a Version 5 application, it has no DSN or FileDSN parameter (these parameters were not available for dbclient in Version 5). The next step is to look for a compatibility data source.

   • The dbcli6 Connection Parameters data source is located, and the server name and other parameters from the data source used to enable a connection to the server.

4. When the application disconnects from the server, the Version 6 interface library deletes the dbcli6 Connection Parameters data source from the list of available data sources.

   This behavior allows other applications to use the compatibility data source to establish connections while the first application is running, and prevents it from being used once that application has closed down (although established connections are not affected). The lifetime of the compatibility data source is thus similar to that of the Version 5 client.

The compatibility data source is only used if no other data source is specified in the connection string or in the SQLCONNECT environment variable.