8 Configuring the ODBC Client

---

This chapter describes the tasks you may need to perform to configure and manage the SequeLink Client for ODBC (the ODBC Client).

Using the ODBC Administrator

The first step in setting up an ODBC connection is creating an ODBC data source. You use the ODBC Administrator to create and manage ODBC data sources.

To start the ODBC Administrator, click Start / Programs. From the Programs menu, select DataDirect SequeLink 5.5 Client for ODBC, and then select the ODBC Administrator application. The ODBC Data Source Administrator window appears listing resident data sources.

NOTE: An ODBC Administrator does not exist for UNIX; you must edit the odbc.ini file using a text editor. See "Configuring ODBC Client Data Sources on UNIX" for instructions on creating ODBC client data sources for UNIX.

Configuring ODBC Client Data Sources on Windows

To configure client data sources for the ODBC Client on Windows platforms, you use the ODBC Administrator.

Configuring ODBC User and System Client Data Sources

Start the ODBC Administrator. To start the ODBC Administrator, select Start / Programs. From the Programs menu, select DataDirect SequeLink 5.5 Client for ODBC, and then select the ODBC Administrator application.

Click the User DSN tab or the System DSN tab to list user or system data sources, respectively.





To configure a new data source, click the Add button. A list of installed drivers appears. Select DataDirect 32-BIT SequeLink 5.5; then, click Finish.

NOTE: To change an existing data source, select the data source you want to configure and click the Configure button.

The DataDirect SequeLink for ODBC Setup window appears.





Provide the following information; then, click OK.

Data Source Name: Type a unique name that identifies this ODBC data source configuration. Examples are Accounting or SequeLink to Oracle Data.

Description: Optionally, type a description of the data source, for example, My Accounting Database or Accounting Data in Oracle.

SequeLink Server Host: Type the TCP/IP host name of the SequeLink service to which the ODBC Client will connect.

SequeLink Server Port: Type the TCP/IP port the SequeLink service is listening on for connection requests. The port you specify must be the same port that was specified for the SequeLink service when the SequeLink Server was installed; the default is 19996.

Server Data Source: Type the name of a server data source configured for the SequeLink service to use for the connection, or click the ... button to select an existing server data source. This field is optional. If a server data source is not specified, the default server data source for that SequeLink service is used.

Translate: Click Translate only if you want to configure an ODBC translator.

NOTE: We strongly recommend that you do not configure an ODBC translator and rely on the native SequeLink transliteration between server and client code pages.

The Select Translator dialog box appears, listing translators specified in the ODBC Translators section of the system information file. Select a translator. When satisfied with your choice, click OK to close this dialog box and perform the translation.

NOTE FOR LDAP USERS: To configure the ODBC Client to retrieve connection information from an LDAP directory, select the Use LDAP check box. The fields change on the lower half of the screen to accommodate the information required to query an LDAP server for connection information. Provide the following information:

LDAP Server Host: Type the TCP/IP host name of the LDAP server.

LDAP Server Port: Type the TCP/IP port the LDAP server is listening on for connection requests. If unspecified, the ODBC Client will use the default LDAP port 389.

Distinguished Name (DN): Type an identifier that uniquely identifies the LDAP entry where the connection information is stored.

See Appendix 16 "Using LDAP with ODBC and ADO Clients" for more information about retrieving connection information from LDAP directories.

Configuring ODBC File Client Data Sources

File data sources are data source files stored on a file server. The files are available to any user who can access the server.

To configure ODBC file client data sources:

Start the ODBC Administrator by clicking Start / Programs. From the Programs menu, select DataDirect SequeLink 5.5 Client for ODBC, and then select the ODBC Administrator application.
Click the File DSN tab. The File DSN tab lists any file data sources in the specified directory.





To configure a new data source, click the Add button. A list of installed drivers appears. Select DataDirect 32-BIT SequeLink 5.5; then, perform one of the following actions:
To configure the file data source to connect directly to a SequeLink Server without retrieving connection information from an LDAP directory, click OK. Then, skip to Step 5.
To configure the file data source to retrieve connection information from an LDAP directory, continue with the next step.
Click Advanced. The Advanced File DSN Creation Settings window appears.





Type UserLDAP=1 in the Type driver-specific keywords and values scrollable box; then, click OK. You are returned to the list of drivers. Click Next and continue with Step 5.

The Create New Data Source dialog box appears.





Type the name of the file data source you want to create or click Browse to select an existing file data source; then, click Next.

The Create New Data Source dialog box displays the settings you've configured for this data source.





Click Finish to create the file data source. A series of connection dialogs appear as described in "ODBC Connection Dialogs". The file data source will be saved after you enter the correct information in the connection dialog boxes.

ODBC Connection Dialogs

A SequeLink data access connection involves the following stages:

A network connection is established.
An authentication mechanism is used to establish the identity of the SequeLink Client to the SequeLink Server.
Based on information provided by the SequeLink Client application (for example, a database user name and password), a database connection is established.

Stage 1: Establishing a Network Connection

The first stage of the connection process involves establishing a network connection. The dialog box that appears depends on whether the connection has been configured to connect directly to a SequeLink service or to retrieve connection information for the SequeLink service from a centralized LDAP directory.

Connecting Directly to a SequeLink® Service

If the connection has been configured to connect directly to a SequeLink service, the Connect to the SequeLink Server dialog box appears.

Provide the following information; then, click OK.

SequeLink Server Host: Type the TCP/IP host name of the SequeLink service.

SequeLink Server Port: Type the TCP/IP port on which the SequeLink service is listening. A default installation of SequeLink Server uses the port 19996.

Server Data Source: Type the name of a server data source to use for the connection, or select one from the drop-down list. This step is optional. If a server data source is not specified, the default server data source for that service will be used for the connection.

Retrieving Connection Information from an LDAP Directory

If the connection has been configured to connect to an LDAP server to retrieve connection information from an LDAP directory, the Connect to the SequeLink Server dialog box appears.

Provide the following information; then, click OK.

LDAP Server Host: Type the TCP/IP host name of the LDAP server.

LDAP Server Port: Type the TCP/IP port on which the LDAP server is listening.

Distinguished Name: Type the Distinguished Name (DN) of the LDAP entry.

Stage 2: SequeLink® Server Authentication

The second stage of the connection process involves authentication of the SequeLink Client to the SequeLink Server. The dialog boxes that appear depend on how authentication is configured for the SequeLink service.

When ServiceAuthMethods=anonymous or ServiceAuthMethods=integrated_nt, no dialog boxes appear.
When ServiceAuthMethods=OSLogon(HUID,HPWD) or ServiceAuthMethods=OSLogon(UID,PWD), the Logon to SequeLink Service dialog box appears.





Provide the following information; then, click OK.

Host User Name: Type the host user name.

NOTE: When connecting to a Windows server, you must prefix the host user name with a server name, if authenticating to a local server, or a domain name (for example, SALES\DJONES). If the server name or domain name is omitted, the SequeLink Server will attempt to authenticate the user ID and password with the database account defined for the machine on which the SequeLink Server is running. If this validation fails, the SequeLink Server will attempt to authenticate the user ID and password with the database account defined for the domain of the machine on which the SequeLink Server is running.

Host Password: Type the host password.

When ServiceAuthMethods=OSLogon(HUID,HPWD,NPWD) or ServiceAuthMethods=OSLogon(UID,PWD,NPWD) and the password is expired, the Logon to SequeLink service dialog box appears.





NOTE: If the password is not expired, the previously described dialog box appears, prompting only for the host user name and host password.

Provide the following information; then, click OK.

Host User Name: Type the host user name.

NOTE: When connecting to a Windows server, you must prefix the host user name with a server name, if authenticating to a local server, or a domain name (for example, SALES\DJONES). If the server name or domain name is omitted, the SequeLink Server will attempt to authenticate the user ID and password with the database account defined for the machine on which the SequeLink Server is running. If this validation fails, the SequeLink Server will attempt to authenticate the user ID and password with the database account defined for the domain of the machine on which the SequeLink Server is running.

Host Password: Type the host password.

New Password: Type the new password to be used by the SequeLink password change mechanism.

Confirm Password: Type again the new password to confirm it.

For more information about configuring authentication, see Chapter 13 "Configuring SequeLink® Security".

Stage 3: Data Store Logon

The last stage of the connection process involves logging on the data store. The dialog boxes that appear depend on the data store logon method configured for the SequeLink service:

When DataSourceLogonMethod=OSIntegrated, no dialog boxes appear.
When DataSourceLogonMethod=DBMSLogon(UID,PWD) or DataSourceLogonMethod=DBMSLogon(DBUID,DBPWD), a data store-specific user name and password are required and the Logon to SequeLink Service dialog box appears.





Provide the following information; then, click OK.

Database User Name: Type the database logon ID.

Database Password: Type the database password.

Database: Type the name of the database to which you want to connect. This field is disabled when the data store does not recognize the concept of databases.

See Chapter 13 "Configuring SequeLink® Security" for more information about configuring data store logon methods.

Testing ODBC Connections on Windows

On the SequeLink Client, start the ODBC Administrator. To start the ODBC Administrator, select Start / Programs. From the Programs menu, select DataDirect SequeLink for ODBC 5.5, and then select the ODBC Administrator application. The ODBC Data Source Administrator window appears listing resident data sources.





Create an ODBC data source as described in "Configuring ODBC User and System Client Data Sources" specifying the TCP/IP address and TCP/IP port of the SequeLink service.
Click the Test Connect button to test the connection. If successful, a dialog appears telling you the connection was successful. You are now ready to start using your ODBC applications with SequeLink.

Configuring ODBC Client Data Sources on UNIX

For UNIX, an ODBC Administrator does not exist. This section describes how to configure the odbc.ini file and how to set some required environment variables to use the ODBC Client on UNIX.

Configuring System Information Files

To configure an ODBC data source for UNIX, you must edit the system information file, that is, the odbc.ini file (32-bit ODBC Client) or odbc64.ini file (64-bit ODBC Client) using the attributes in Table 8-1. The system information file accepts only long names for attributes.

ODBC Data Source Attributes for UNIX

NOTE: To configure an ODBC data source for UNIX, you must edit the system information file using the attributes in Table 8-1.

Table 8-1. ODBC Attributes for odbc.ini  

Attribute	Description
DistinguishedName	The distinguished name identifying the LDAP entry from which connection information is retrieved. This attribute is required when UseLDAP=1.
Host	The TCP/IP address of the SequeLink Server, specified in dotted format or as a host name. LDAP: If LDAP is enabled, this identifies the TCP/IP address of the LDAP server. This can also be a list of LDAP servers separated by a blank space (for example, "ld1.foo.com ld2.foo.com ld3.foo.com"). If the first LDAP server in the list does not respond, the ODBC Client will try to connect to the next LDAP server in the list.
IANAAppCodePage	See Appendix G "Values for IANAAppCodePage Connection String Attribute" for a list of valid values for this attribute. You need to set this attribute if your application is not Unicode-enabled and/or if your database character set is not Unicode (see Appendix F "Internationalization, Localization, and Unicode" for details). The value you specify must match the database character encoding and the system locale. Both this driver and the Driver Manager check for the value of IANAAppCodePage in the following order: In the connection string In the Data Source section of the system information file (odbc.ini) In the ODBC section of the system information file (odbc.ini) If no IANAAppCodePage value is found, the driver uses the default value of 4 (ISO 8859-1 Latin-1).
LogonID	The host or data store user name, which may be required depending on the server configuration.
Password	The host or data store password, which may be required depending on the server configuration.
Port	The TCP/IP port on which the SequeLink Server is listening. LDAP: If LDAP is enabled, this identifies the TCP/IP port on which the LDAP server is listening. If you do not specify a port, the default port for LDAP (389) will be used.
ServerDataSource	A string that optionally identifies the server data source to be used for the connection. If not specified, the configuration of the default server data source will be used for the connection.
UseLDAP	UseLDAP={0 | 1}. Determines whether the parameters to establish a connection to the SequeLink Server should be retrieved from LDAP. When set to 0 (the initial default), the SequeLink Client will connect directly to the specified SequeLink Server. When set to 1, the ODBC Client will retrieve the TCP/IP host, TCP/IP port, and SequeLink data source (optional) from an LDAP entry identified by a Distinguished Name (DN). Once the connection information is retrieved, the SequeLink Client will connect directly to the specified SequeLink Server. The DistinguishedName (DN) attribute is required.

Example: odbc.ini for Solaris

The following code shows an example of an odbc.ini file for a 32-bit ODBC Client installed on a Solaris machine:

[ODBC Data Sources] 
SALESDB=DataDirect 32-BIT SequeLink 5.5 
 
[SALESDB] 
Driver=SALES/lib/ivslk20.so 
Description=DataDirect 32-BIT SequeLink 5.5 
Host= 
Port= 
UseLDAP=0 
DistinguishedName= 
 
[ODBC] 
Trace=0 
TraceFile=odbctrace.out 
TraceDll=path_of_installdir/lib/odbctrac.so 
InstallDir=path_of_installdir 

where path_of_installdir is the path to the ODBC Client installation directory.

Example: odbc64.ini for Solaris

The following code shows an example of the odbc64.ini file for a 64-bit ODBC Client installed on a Solaris machine:

[ODBC Data Sources] 
SALESDB=DataDirect 64-BIT SequeLink 5.5 
 
[AccountingDB] 
Driver=Accounting/lib64/ivslk20.so 
Description=DataDirect 64-BIT SequeLink 5.5 
Host= 
Port= 
UseLDAP=0 
DistinguishedName= 
 
[ODBC] 
Trace=0 
TraceFile=odbctrace.out 
TraceDll=path_of_installdir/lib64/odbctrac.so 
InstallDir=path_of_installdir 

where path_of_installdir is the path to the ODBC Client installation directory.

Setting Environment Variables

You must set several environment variables for the ODBC Client on UNIX by executing a shell script located in the installation directory.

To execute the shell script:

If you are using the Bourne or Korn shell, type:
. .sqlnk.sh (for 32-bit client)
. .sqlnk64.sh (for 64-bit client)
If you are using the C shell, type:
source .sqlnk.csh (for 32-bit client)
source .sqlnk64.csh (for 64-bit client)

Executing this shell script sets the following environment variables:

ODBCINI	Specifies where the centralized odbc.ini or odbc64.ini file is located.
SQLNK_ODBC_HOME	Specifies the full path of the directory containing the ODBC Client shared libraries.

Executing this shell script also sets the appropriate library search environment variable (LD_LIBRARY_PATH on Solaris and Linux, SHLIB_PATH on HP-UX, or LIBPATH on AIX).

Using a Centralized System Information File

Because UNIX is a multi-user environment, you may want to use a single centralized odbc.ini file controlled by a system administrator. To do this, set the ODBCINI environment variable to point to the fully qualified pathname of the centralized file.

For example:

In the Bourne or Korn shell, type:

ODBCINI=/opt/odbc/system_odbc.ini;export ODBCINI

In the C shell, type:

setenv ODBCINI /opt/odbc/system_odbc.ini

The odbc.ini file also require an [ODBC] section that includes the InstallDir keyword. The value of the InstallDir keyword must be the path to the directory that contains the /lib and /messages directories.

For example, if you choose the default installation directory for the 32-bit ODBC Client, the following line must be in the [ODBC] section of the odbc.ini file:

InstallDir=/usr/slodbc55 

Connecting Using a Connection String

If you want to use a connection string for connecting to a database, or if your application requires it, you must specify either a DSN (data source name) or a DSN-less connection in the string. The difference is whether you use the DSN= or the DRIVER= keyword in the connection string, as described in the ODBC specification. A DSN connection string tells the driver where to find the default connection information. Optionally, you may specify attribute=value pairs in the connection string to override the default values stored in the data source.

If your application requires a connection string to connect to a data source, you must specify the data source name that tells the driver which data source to use for the default connection information. Optionally, you may specify attribute=value pairs in the connection string to override the default values stored in the data source.

The DSN connection string has the form::

DSN=data_source_name[;attribute=value[;attribute=value]...] 

For example, a connection string for SequeLink may look like this:

DSN=Accounting;DB=EMP;UID=JOHN;PWD=XYZZY 

or

DSN=Accounting;DB="X:IV;EMP";UID=JOHN;PWD=XYZZY 

NOTE: If the database name (DB) contains a semicolon (;), you must place the name in quotes, as shown in the preceding example.

The DSN-less connection string specifies a driver instead of a data source. All connection information must be entered in the connection string because there is no data source storing the information.

The DSN-less connection string has the form:

DRIVER=[{]driver_name[}][;attribute=value[;attribute=value] 
...] 

NOTE: Empty string is the default value for attributes that use a string value unless otherwise noted.

A DSN-less connection string must provide all necessary connection information:

DRIVER=DataDirect 32-BIT SequeLink 5.5;DB=Emp;UID=JOHN; 
PWD=XYZZY 

For a list of ODBC connection attributes and their valid values, refer to the SequeLink Developer's Reference.

Importing and Exporting ODBC Client Data Sources

The SequeLink Data Source SyncTool allows you to export ODBC client data source definitions to data source files and distribute them to multiple end users. The SequeLink Data Source SyncTool provides two user implementations, one for the SequeLink administrator and another for the end user:

The SequeLink for ODBC Data Source SyncTool Administrator is used by the SequeLink administrator to create data source files. It can import and export data sources. This tool should be made available to the SequeLink administrator only.
The SequeLink for ODBC Data Source SyncTool is used by the end user and can import data sources only. It should be installed on every SequeLink for ODBC Client.

In addition, you can create a customized, installable image of SequeLink for ODBC Client with predefined, site-specific settings, including data source files created with the SequeLink Data Source SyncTool. This customized, installable image is called a Quick Install image. For more information about creating Quick Install images, refer to the SequeLink Installation Guide.

The window title bar of the SequeLink Data Source SyncTool indicates whether you, or the end user, is performing an export or an import operation. Also, context-sensitive online help is available by clicking ? on the title bar; then, click the area about which you want more information.

Exporting ODBC Client Data Sources

From the SequeLink program manager group, double-click the ODBC Data Source SyncTool Administrator icon. The SequeLink for ODBC Data Source SyncTool Administrator Welcome window appears.
Select the Manage Data Sources Files option; then, click Next.
Select a data source file from the Filename list box, or click Browse to find a data source file not listed. The default extension for a data source file is .DSF.

To create a new data source file, click New.

Select whether you want to export User or System data sources to the data source file you selected; then click Next.
Select the data sources you want to export to the data source file.

NOTE: You cannot export grayed-out data sources, which are data sources that are configured for a previous incompatible version of the ODBC driver.

Using the following symbols, verify that the appropriate actions will be performed on the data sources in the data source file; then, click Next.

	The data source will remain unchanged.
	The data source will be added to the data source file.
	The data source will be deleted from the data source file.
	The data source will be updated in the data source file.

Type a description for the data source file; then, click Next. This description will appear when the end user selects this file for importing.
Select the mode the end user will use to import these data sources; then, click Next.
Interactive mode allows the user to select which data sources will be imported. This mode is not supported by the Quick Install feature; the Quick Install feature supports only data source files created with the Merge or Overwrite options. For instructions on creating Quick Install images, refer to the SequeLink Installation Guide.
Merge mode adds or updates all the data sources in the data source file without deleting other data sources.
Overwrite mode adds or updates the data sources in the data source file and deletes any other data sources configured for the ODBC driver.
Select the option that will determine how the end user will be able to import the data sources you exported to the data source file; then, click Next.
Suggest SequeLink User DSN. When imported, the SequeLink for ODBC Data Source SyncTool will suggest to the end user that these data sources be imported as User data sources, but will allow them to be imported as User or System data sources.
Suggest SequeLink System DSN. When imported, the SequeLink for ODBC Data Source SyncTool will suggest to the end user that these data sources be imported as System data sources, but will allow them to be imported as User or System data sources.
Force SequeLink User DSN. When imported, the SequeLink for ODBC Data Source SyncTool will allow these data sources to be imported as User data sources only.
Force SequeLink System DSN. When imported, the SequeLink for ODBC Data Source SyncTool will allow these data sources to be imported as System data sources only.
Click Finish to quit.

Importing ODBC Client Data Sources

The SequeLink administrator and end user use a different implementation of the SequeLink for ODBC Data Source SyncTool to import ODBC data source definitions.

To import ODBC client data sources:

From the SequeLink program manager group, double-click the appropriate ODBC SyncTool icon. The Welcome window appears.
Select the Import option, and click Next.

NOTE: If using the SequeLink for ODBC Data Source SyncTool Administrator, select the Import Data Sources option; then, click Next.

Select a data source file from the Filename list box, or click Browse to find a data source file not listed. The default extension for data source files is .DSF.
Indicate whether you want to import the data sources in the data source file you just selected as User or System data sources; then, click Next.
Verify that the appropriate actions will be performed on the data sources on your local machine; then, click Next. Depending on the import mode that was set when the data source file was exported, you may see the following symbols:

	The data source will remain unchanged.
	The data source will be added to your local machine.
	The data source will be deleted from your local machine.
	The data source will be updated to your local machine.

NOTE: Grayed-out data sources are data sources that are configured for a previous incompatible version of the ODBC driver; these data sources will remain unchanged unless you update them in Interactive mode with a data source configured for the current version of the ODBC driver.

Click Finish to quit.

Unicode and Code Page Support

The ODBC driver fully supports the SQL-W functions and Unicode arguments, for example, SQLConnectW. This support enables faster processing of wide-characters and allows binding of the SQL_C_WCHAR output type.

On Windows, SQL-W routines map to UTF-16. On UNIX, SQL-W routines map to UTF-8 or UTF-16. How the database data types are mapped depends on the database and a number of configuration options. See Appendix F "Internationalization, Localization, and Unicode" for more information about internationalization and localization and about important differences in developing applications on UNIX.

See Appendix D "SequeLink® Service Attributes" for information about the SequeLink service attributes that affect configuration.

Refer to the SequeLink Developer's Reference for information about data type mappings, and additional information about developing applications on UNIX.