Deploying client applications

User's Guide
PART 4. Database Administration and Advanced Use
CHAPTER 27. Deploying Databases and Applications

Deploying client applications

In order to deploy a client application that runs against a network database server, you must provide each end user with the following items:

Client application The application software itself is independent of the database software, and so is not described here.
Database interface files The client application requires the files for the database interface it uses (ODBC, JDBC, Embedded SQL, or Open Client).
Connection information Each client application needs database connection information.

The interface files and connection information required varies with the interface your application is using. Each interface is described separately in the following sections.

Deploying ODBC clients

Each ODBC client machine must have the following:

A working ODBC installation ODBC files and instructions for their redistribution are available for redistribution from Microsoft Corporation. They are not described in detail here.

Microsoft provides their ODBC Driver Manager for 32-bit Windows and for Windows 3.x. Third party vendors such as Intersolv provide ODBC Driver managers for UNIX.

ODBC applications can run without the driver manager, but except on platforms for which an ODBC driver manager is not available, this is generally not recommended.
The Adaptive Server Anywhere ODBC driver This is the file dbodbc6.dll together with some additional files.
Connection information The client application must have access to the information needed to connect to the server. This information is typically included in an ODBC data source.

ODBC driver required files

The following table shows the files needed for a working Adaptive Server Anywhere ODBC driver. These files should be copied into a single directory. The Adaptive Server Anywhere installation places them all in the operating-system subdirectory of your Adaptive Server Anywhere installation directory.

Description

32-bit Windows

Windows 3.x

UNIX

ODBC driver

dbodbc6.dll

dbodbc6wdll

libdbodbc6.so

ODBC translator

dbodtr6.dll

dbodtr6w.dll

Language-specific string library

dblgen6.dll

dblgen6w.dll

dblgen6.res

Network ports

dbport6.dll

N/A

libdbport6.so

Connection Dialog

dbcon6.dll

dbcon6w.dll

Description	32-bit Windows	Windows 3.x	UNIX
ODBC driver	dbodbc6.dll	dbodbc6wdll	libdbodbc6.so
ODBC translator	dbodtr6.dll	dbodtr6w.dll
Language-specific string library	dblgen6.dll	dblgen6w.dll	dblgen6.res
Network ports	dbport6.dll	N/A	libdbport6.so
Connection Dialog	dbcon6.dll	dbcon6w.dll

Notes

Your end user must have a working ODBC installation, including the driver manager. Instructions for deploying ODBC are included in the Microsoft ODBC SDK.
The network port library handles network communications. It is required only if the client is working with the network database server. No network port is available for Windows 3.x; instead, the network ports are part of the ODBC driver DLL.
The Connection dialog is needed if your end users are to create their own data sources, if they need to enter user IDs and passwords when connecting to the database, or if they need to display the Connection dialog for any other purpose.
The ODBC translator is required only if your application relies on OEM to ANSI character set conversion.
On HP-UX, all files listed with extension .so instead have extension .sl. On AIX, the files have extension .so or .a.

Configuring the ODBC driver

In addition to copying the ODBC driver files onto disk, your Setup program must also make a set of registry entries to install the ODBC driver properly.

Windows NT and Windows 95

The Adaptive Server Anywhere Setup program makes changes to the Windows NT and Windows 95 system Registry to identify and configure the ODBC driver. If you are building a setup program for your end users, you should make the same settings.

You can use the Windows regedit utility to inspect registry entries.

The Adaptive Server Anywhere ODBC driver is identified to the system by a set of registry values in the following registry key:

HKEY_LOCAL_MACHINE\
   SOFTWARE\
      ODBC\
         ODBCINST.INI\
            Adaptive Server Anywhere 6.0

The values are as follows:

Value name

Value type

Value data

Driver

String

path\dbodbc6.dll

Setup

String

path\dbodbc6.dll

Value name	Value type	Value data
Driver	String	path\dbodbc6.dll
Setup	String	path\dbodbc6.dll

There is also a registry value in the following key:

HKEY_LOCAL_MACHINE\
   SOFTWARE\
      ODBC\
         ODBCINST.INI\
            ODBC Drivers

The value is as follows:

Value name

Value type

Value data

Adaptive Server Anywhere 6.0

String

Installed

Value name	Value type	Value data
Adaptive Server Anywhere 6.0	String	Installed

Windows 3.x

For Windows 3.x, the ODBC driver information is held in the odbcinst.ini file, instead of the registry. The individual entries are analogous to the registry entries above.

Third party ODBC drivers

If you are using a third-party ODBC driver on an operating system other than Windows, consult the documentation for that driver on how to configure the ODBC driver.

Deploying connection information

ODBC client connection information is generally deployed as an ODBC data source. You can deploy an ODBC data source in one of the following ways:

Programatically Add a data source description to your end-user's Registry or ODBC initialization files.
Manually Provide your end-users with instructions, so that they can create an appropriate data source on their own machine.

You create a data source manually using the ODBC Administrator, from the User DSN tab or the System DSN tab. The Adaptive Server Anywhere ODBC driver displays the configuration dialog for entering settings. Data source settings include the location of the database file, the name of the database server, as well as any start up parameters and other options.

This section provides you with the information you need to know for either approach.

Types of data source

There are three kinds of data sources: User data sources, System data sources, and File data sources.

User data source definitions are stored in the part of the registry containing settings for the specific user currently logged on to the system. System data sources, however, are available to all users and to Windows NT or Windows 95 services, which run regardless of whether a user is logged onto the system or not. Given a correctly configured System data source named MyApp, any user can use that ODBC connection by providing DSN=MyApp in the ODBC connection string.

File data sources are not held in the registry, but are held in a special directory. A connection string must provide a FileDSN connection parameter to use a File data source.

Data source registry entries

Each user data source is identified to the system by registry entries.

You must enter a set of registry values in a particular registry key. For User data sources the key is as follows:

HKEY_CURRENT_USER\
   SOFTWARE\
      ODBC\
         ODBC.INI\
            userdatasourcename

For System data sources the key is as follows:

HKEY_LOCAL_MACHINE\
   SOFTWARE\
      ODBC\
         ODBC.INI\
            systemdatasourcename

The key contains a set of registry values, each of which corresponds to a connection parameter. For example, the ASA 6.0 Sample key corresponding to the ASA 6.0 Sample data source contains the following settings:

Value name

Value type

Value data

Autostop

String

Yes

DatabaseFile

String

path\asademo.db

Description

String

Adaptive Server Anywhere Sample Database

Driver

String

path\win32\dbodbc6.dll

PWD

String

sql

Start

String

path\win32\dbeng6.exe -c 8m

UID

String

dba

Value name	Value type	Value data
Autostop	String	Yes
DatabaseFile	String	path\asademo.db
Description	String	Adaptive Server Anywhere Sample Database
Driver	String	path\win32\dbodbc6.dll
PWD	String	sql
Start	String	path\win32\dbeng6.exe -c 8m
UID	String	dba

In these entries, path is the Adaptive Server Anywhere installation directory.

In addition, you must add the data source to the list of data sources in registry. For User data sources, you use the following key:

HKEY_CURRENT_USER\
   SOFTWARE\
      ODBC\
         ODBC.INI\
            ODBC Data Sources

For System data sources, use the following key:

HKEY_LOCAL_MACHINE\
   SOFTWARE\
      ODBC\
         ODBC.INI\
            ODBC Data Sources.

The value associates each data source with an ODBC driver. The value name is the data source name, and the value data is the ODBC driver name. For example, the User data source installed by Adaptive Server Anywhere is named ASA 6.0 Sample , and has the following value:

Value name

Value type

Value data

ASA 6.0 Sample

string

Adaptive Server Anywhere 6.0

Value name	Value type	Value data
ASA 6.0 Sample	string	Adaptive Server Anywhere 6.0

Caution: ODBC settings are easily viewed
User data source configurations can contain sensitive database settings such as a user's ID and password. These settings are stored in the registry in plain text, and can be view using the Windows registry editors regedit.exe or regedt32.exe, which are provided by Microsoft with the operating system. You can choose to encrypt passwords, or require users to enter them on connecting.

Required and optional connection parameters

You can identify the data source name in an ODBC configuration string in this manner,

DSN=userdatasourcename

... identifies which user data source or system data source from the Registry is to be used for the ODBC connection.

When a DSN parameter is provided in the connection string, the current User data source definitions in the Registry are searched, followed by the System data source. File data sources are searched only when FileDSN is provided in the ODBC connection string.

The following table illustrates the implications to the user and developer when a DSN exists, when it is provided and the effects of including different parameters in the DSN.

To connect a client application to a database ...

The connection string must identify...

The user must supply...

When the ODBC connection string identifies: a fully-configured DSN that contains the ODBC driver name and location; the name of the database file/server; startup parameters; and the user ID and password.

No additional information

No additional information.

When the OBDC connection string identifies a DSN containing only the name and location of the ODBC driver.

The name of the database file/ server; and, optionally, the user ID and the password.

User ID and password if not provided in the DSN or ODBC connection string.

When the system has no appropriately configured DSN.

The name of the ODBC driver to be used, in the following format:

Driver = {ODBCdrivername}

Also, the name of the database, the database file or the database server; and, optionally, other connection parameters such as user ID and password.

User ID and password if not provided in the ODBC connection string.

To connect a client application to a database ...	The connection string must identify...	The user must supply...
When the ODBC connection string identifies: a fully-configured DSN that contains the ODBC driver name and location; the name of the database file/server; startup parameters; and the user ID and password.	No additional information	No additional information.
When the OBDC connection string identifies a DSN containing only the name and location of the ODBC driver.	The name of the database file/ server; and, optionally, the user ID and the password.	User ID and password if not provided in the DSN or ODBC connection string.
When the system has no appropriately configured DSN.	The name of the ODBC driver to be used, in the following format: Driver = {ODBCdrivername} Also, the name of the database, the database file or the database server; and, optionally, other connection parameters such as user ID and password.	User ID and password if not provided in the ODBC connection string.

For Info For more information on ODBC connections and configurations, see the following:

Connecting to a Database.
The Open Database Connectivity (ODBC) SDK, available from Microsoft.

Deploying Embedded SQL clients

Deploying Embedded SQL clients involves the following:

Installed files Each client machine must have the files required for an Adaptive Server Anywhere Embedded SQL client application.
Connection information The client application must have access to the information needed to connect to the server. This information may be included in an ODBC data source.

Installing files for Embedded SQL clients

The following table shows which files are needed for Embedded SQL clients.

Description

32-bit Windows

Windows 3.x

UNIX

Interface library

dblib6.dll

dblib6w.dll

libdblib6.so

Language-specific string library

dblgen6.dll

dblgen6w.dll

dblgen6.res

Network ports

dbport6.dll

N/A

Connection Dialog

dbcon6.dll

dbcon6w.dll

Description	32-bit Windows	Windows 3.x	UNIX
Interface library	dblib6.dll	dblib6w.dll	libdblib6.so
Language-specific string library	dblgen6.dll	dblgen6w.dll	dblgen6.res
Network ports	dbport6.dll	N/A
Connection Dialog	dbcon6.dll	dbcon6w.dll

Notes

The network ports DLL is not required if the client is working only with the personal database server.
If the client application uses an ODBC data source to hold the connection parameters, your end user must have a working ODBC installation. Instructions for deploying ODBC are included in the Microsoft ODBC SDK.

For more information on deploying ODBC information, see Deploying ODBC clients.
The Connection dialog is needed if your end users will be creating their own data sources, if they will need to enter user IDs and passwords when connecting to the database, or if they need to display the Connection dialog for any other purpose.
On HP-UX, all files listed with extension .so instead have extension .sl. On AIX, the files have extension .so or .a.
No network port library is provided for Windows 3.x. Instead, the network ports are linked into the interface library.

Connection information

You can deploy Embedded SQL connection information in one of the following ways:

Manual Provide your end-users with instructions for creating an appropriate data source on their machine.
File Distribute a file that contains connection information in a format that your application can read.
ODBC data source You can use an ODBC data source to hold connection information. In this case, you need a subset of the ODBC redistributable files, available from Microsoft. For details see Deploying ODBC clients.
Hard coded You can hard code connection information into your application. This is an inflexible method, which may be limiting, for example when databases are upgraded.

Deploying JDBC clients

In addition to a Java Runtime Environment, each JDBC client requires the Sybase jConnect JDBC driver. Instructions on deploying jConnect can be found on the Sybase Web site at the following location:

http://www.sybase.com/products/internet/jconnect

Your Java application needs a URL in order to connect to the database. This URL specifies the driver, the machine to use, and the port on which the database server is listening.

For Info For more information on URLs, see Supplying a URL for the server.

Deploying Open Client applications

In order to deploy Open Client applications, each client machine needs the Sybase Open Client product. You must purchase the Open Client software separately from Sybase. It contains its own installation instructions.

Connection information for Open Client clients is held in the interfaces file. For information on the interfaces file, see the Open Client documentation and Configuring Open Servers with DSEDIT.