Configuring Data Sources
After you install the driver, you need to configure a data source or use a connection string to connect to the database. If you want to use a data source, but need to change some of its values, you can either modify it or override its values through a connection string. See "Quick Start Connect" for an explanation of different types of data sources.
If you choose to use a connection string, you must use specific connection string attributes. See "Connecting to a Data Source Using a Connection String", Table 7-3, and Table 7-2 for a complete description of driver connection string attributes and their values.
UNIX
On UNIX and Linux, you must set up the proper ODBC environment before configuring data sources. See "Environment Configuration" for basic setup information and "Environment Variables" for more detail about this procedure.
Data sources are stored in the system information file (by default, odbc.ini). If you have a Motif GUI environment on UNIX or Linux, you can configure and modify data sources through the DataDirect ODBC Data Source Administrator for UNIX/Linux (the UNIX ODBC Administrator) using a driver Setup dialog box, as described in the following procedure. (See "Configuration Through the UNIX ODBC Administrator" for a detailed explanation of the Administrator.)
If you do not have a GUI environment, you can configure and modify data sources directly by editing the system information file and storing default connection values there. See "Configuration Through the System Information File" for detailed information about the specific steps necessary to configure a data source.
Table 7-1 and Table 7-2 list driver connection string attributes that must be used in the system information file.
Windows
On Windows, data sources are stored in the Windows Registry. You can configure and modify data sources through the ODBC Administrator using a driver Setup dialog box, as described in the following section.
Configuration
Default connection values are specified through the options on the tabs of the Setup dialog box. Connection string attributes that override these options have the same names as the options unless noted otherwise. The connection string attribute name does not have spaces between the words. For example, the option name Application Using Threads is equivalent to the connection string attribute name ApplicationUsingThreads.
NOTE: This book shows dialog box images that are specific to Windows. If you are using the drivers in the UNIX/Linux environments, the dialog box that you see may differ slightly from the Windows version. Windows-only and UNIX-only connection options are specifically noted by icons in the Setup dialog box descriptions.
By default, edit boxes and drop-down lists on the Setup dialog box are empty unless a specific default is otherwise noted.
To configure a Microsoft SQL Server data source:
- Start the ODBC Administrator:
- Select a tab:
- User DSN: If you are configuring an existing user data source, select the data source name and click Configure to display the driver Setup dialog box.
System DSN: If you are configuring an existing system data source, select the data source name and click Configure to display the driver Setup dialog box.- File DSN: If you are configuring an existing file data source, select the data source file and click Configure to display the driver Setup dialog box.
- On the General tab, provide the following information; then, click Apply.
- Optionally, click the Advanced tab to specify additional data source settings.
Optionally, click the Failover tab to specify Failover data source settings. This tab is available only on UNIX and Linux.- At any point during the configuration process, you can click Test Connect to attempt to connect to the data source using the connection options specified in the driver Setup dialog box. A Login dialog box appears; see "Connecting to a Data Source Using a Login Dialog Box" for details. Note that the information you enter in the Login dialog box during a test connect is not saved.
- Click OK or Cancel. If you click OK, the values you have specified become the defaults when you connect to the data source. You can change these defaults by using this procedure to reconfigure your data source. You can override these defaults by connecting to the data source using a connection string with alternate values.
If you are configuring a new user data source, click Add to display a list of installed drivers. Select the driver and click Finish to display the driver Setup dialog box.
If you are configuring a new system data source, click Add to display a list of installed drivers. Select the driver and click Finish to display the driver Setup dialog box.
If you are configuring a new file data source, click Add to display a list of installed drivers. Select the driver and click Advanced to specify attributes; otherwise, click Next to proceed. Specify a name for the data source and click Next. Verify the data source information; then, click Finish to display the driver Setup dialog box.
The General tab of the Setup dialog box appears by default.
NOTE: The General tab displays only fields that are required for creating a data source. The fields on all other tabs are optional, unless noted otherwise.
Data Source Name: Type a string that identifies this Microsoft SQL Server data source configuration. Examples include Accounting or SQL Server-Serv1.
Description: Type an optional long description of a data source name. For example, My Accounting Database or SQL Server on Server number 1.
Server: Type an IP address in the following format: IP_address, port_number. For example, you can enter 199.226.224.34,5000. If your network supports named servers, you can specify an address as: server_name, port_number. For example, you can enter SSserver,5000.
To specify a named instance of Microsoft SQL Server, use the format: server_name\instance_name. If only a server name is specified with no instance name, the driver connects to the server and uses the default named instance on the server.
Type the name of a server on your network. It must be an entry on the Alias tab of the SQL Server Network Client Utility or the network name of a server running Microsoft SQL Server. You can enter (local) when the driver is on the same computer as the Microsoft SQL Server database. You can connect to a local copy of Microsoft SQL Server, even when it is a non-networked version. Microsoft SQL Server 2000 and higher support multiple instances of Microsoft SQL Server running on the same computer.
The numeric IP address can be specified in either IPv4 or IPv6 format, or a combination of the two. See "Using IP Addresses" for details concerning these formats.
The equivalent connection string attribute on UNIX is Address.
Database Name: Type the name of the database to which you want to connect by default. If you do not specify a value, the default database defined by Microsoft SQL Server is used.
The equivalent connection string attribute is DATABASE.
On this tab, provide any of the following optional information; then, click Apply.
Application Name: Type the name Microsoft SQL Server uses to identify your application.
The equivalent connection string attribute is APP.
Default User Name: Type the default user ID used to connect to your Microsoft SQL Server database. This ID is case-sensitive. A Login ID is required only if security is enabled on your database. Your ODBC application may override this value or you may override this value in the Login dialog box or connection string.
The equivalent connection string attribute is UID.
Language: Type the national language to use for Microsoft SQL Server system messages. This overrides the default language specified for the login on the server. If no language is specified, the connection uses the default language specified for the login on the server.
Workstation ID: Type the workstation ID used by the client.
The equivalent connection string attribute is WSID.
Enable Quoted Identifiers: Select this check box to enable quoted identifiers. When selected, Microsoft SQL Server enforces ANSI rules regarding quotation marks. Double quotation marks can only be used for identifiers, such as column and table names. Character strings must be enclosed in single quotation marks, for example:
SELECT "au_id"
FROM "authors"
WHERE "au_lname" = 'O''Brien'
When this check box is not selected (the default), applications that use quoted identifiers encounter errors when they generate SQL statements with quoted identifiers. By default, the check box is not selected.
The equivalent connection string attribute is QuotedID.
IANAAppCodePage: For a list of valid values for this option, refer to "Values for the Attribute IANAAppCodePage" in the DataDirect Connect for ODBC and Connect XE for ODBC Reference. You need to specify a value for this option if your application is not Unicode-enabled and/or if your database character set is not Unicode (refer to "Internationalization, Localization, and Unicode" in the DataDirect Connect for ODBC and Connect XE for ODBC Reference 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:
If no IANAAppCodePage value is found, the driver uses the default value of 4 (ISO 8859-1 Latin-1).
Use NT Authentication: Select the Use NT Authentication check box to specify that the SQL Server Wire Protocol driver request a secure (or trusted) connection to Microsoft SQL Server running on Windows NT, Windows 2000, Windows XP, or Windows Server 2003. Microsoft SQL Server uses integrated login security to establish connections using this data source, regardless of the current login security mode at the server. Any login ID or password supplied is ignored. The Microsoft SQL Server system administrator must have associated your Windows network ID with a Microsoft SQL Server login ID.
When not selected (the default), Microsoft SQL Server uses standard login security to establish connections using this data source. In this case, you must specify a login ID and password for all connection requests.
The equivalent connection string attribute is Trusted_Connection.
Use Snapshot Transactions: For Microsoft SQL Server 2005 only. Select this check box to allow your application to use the snapshot isolation level if your Microsoft SQL Server 2005 database is configured for Snapshot isolation.
When this check box is selected and your application has the transaction isolation level set to serializable, then the application uses the snapshot isolation level.
When this check box is not selected and your application has the transaction isolation level set to serializable, then the application uses the serializable isolation level.
This option is useful for existing applications that set the isolation level to serializable. Use Snapshot Transactions in this case allows you to change to the snapshot isolation level with no or minimum code changes. If you are writing a new application, you may want to code it to set the connection attribute SQL_COPT_SS_TXN_ISOLATION to the value SQL_TXN_SS_SNAPSHOT.
See "Isolation and Lock Levels Supported" for details about using the snapshot isolation level.
This connection option can affect performance. See "Performance Considerations" for details.
The equivalent connection string attribute is SnapshotSerializable.
Translate: Click Translate to display the Select Translator dialog box, which lists the translators specified in the ODBC Translators section of the Registry. DataDirect provides a translator named OEM to ANSI that translates your data from the IBM PC character set to the ANSI character set.
Select a translator; then, click OK to close this dialog box and perform the translation.
On this tab, provide any of the following optional information; then, click Apply.
Load Balancing: Select this check box to allow the driver to use client load balancing in its attempts to connect to primary and alternate database servers. In this case, the driver attempts to connect to the database servers in random order. See "Using Client Load Balancing" for more information.
If this check box is not selected (the default), client load balancing is not used and the driver connects to each database server based on its sequential order (primary server first, then, alternate servers in the order they are specified).
NOTE: This option has no effect unless alternate servers are defined for the Alternate Servers connection option.
The Load Balancing option is an optional setting that you can use in conjunction with connection failover. See "Configuring Connection Failover" for a discussion of connection failover and for information about other connection options that you can set for this feature.
Alternate Servers: Type a list of alternate database servers to which the driver will try to connect if the primary database server is unavailable. Specifying a value for this option enables connection failover for the driver. See "Using Connection Failover" for a discussion of connection failover.
The value you specify must be in the form of a string that defines the physical location of each alternate server. All of the other required connection information for each alternate server is the same as what is defined for the primary server connection.
For the SQL Server Wire Protocol driver, you must specify the network address. The string has the format:
(Address=addressvalue[, . . .])
For example, the following two Alternate Servers values define two alternate database servers for connection failover:
AlternateServers=(Address=\\MySQLServer\Instance1,
Address="255.125.1.11,5002")
Notice in the second alternate that the address is enclosed in quotation marks. This is because it contains a comma and might be mistaken for the next alternate server in the list.
See "Configuring Connection Failover" for information about other connection options that you can set for this feature.
Connection Retry Count: Type a value to specify the number of times the driver tries to connect to the primary server and, if configured, to the alternate servers after the initial unsuccessful attempt. See "Using Connection Retry" for more information about this feature.
Valid values are integers from 0 to 65535. When set to 0 (the default), the driver does not try to connect after the initial unsuccessful attempt.
If a connection is not established during the retry attempts, the driver returns an error that is generated by the last server to which it tried to connect.
This option and the Connection Retry Delay connection option, which specifies the wait interval between attempts, can be used in conjunction with connection failover.
See "Configuring Connection Failover" for a discussion of connection failover and for information about other connection options that you can set for this feature.
Connection Retry Delay: Type a value to specify the number of seconds that the driver waits after the initial unsuccessful connection attempt before retrying a connection to the primary server and, if specified, to the alternate servers.
Valid values are integers from 0 to 65535. The default value is 3 (seconds). When set to 0, there is no delay between retries.
NOTE: This option has no effect unless the Connection Retry Count connection option is set to an integer value greater than 0.
This option and the Connection Retry Count connection option, which specifies the number of times the driver tries to connect after the initial unsuccessful attempt, can be used in conjunction with connection failover.
See "Configuring Connection Failover" for a discussion of connection failover and for information about other connection options that you can set for this feature.