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" and Table 8-1 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 8-1 lists driver connection string attributes that must be used in the system information file. Note that only the long name of the attribute can be used in the 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 Sybase 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 Security tab to specify security data source settings.
- Optionally, click the Connection tab to specify data source settings.
- Optionally, click the Performance tab to specify performance data source settings.
- Optionally, click the Failover tab to specify Failover data source settings.
- 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 logon dialog box appears (see "Connecting to a Data Source Using a Logon Dialog Box" for details). Note that the information you enter in the logon dialog box during a test connect is not saved.
- If the driver can connect, it releases the connection and displays a
Connection Establishedmessage. Click OK. - If the driver cannot connect because of an incorrect environment or connection value, it displays an appropriate error message. Click OK.
- 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 the 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 Sybase data source configuration. Examples include Accounting or Sys11-Serv1.
Description: Type an optional long description of a data source name. For example, My Accounting Database or System 11 on Server number 1.
Network Address: Type the network address. Specify an IP address as follows: IP address, port_number. For example, you might enter 199.226.224.34, 5000. If your network supports named servers, you can specify an address as: servername, port_number. For example, you might enter Sybaseserver, 5000.
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.
NOTE: If you specified a value in either the Interfaces File or Server Name field on this tab, this field is disabled. When specifying connection information, you specify either a network address or an Interfaces file and server name.
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 is the database defined by the system administrator for each user.
The equivalent connection string attribute is Database.
Interfaces File: Type the path name of the Interfaces file. If you do not specify a value in the Interfaces File field, but do specify a value in the Server Name field, then the driver looks for the path name of the Interfaces file in the Registry under HKEY_LOCAL_MACHINE\SOFTWARE\DataDirect\InterfacesFile. If this Registry value is empty, then the driver attempts to open the SQL.INI file found in the same directory as the driver and use it as the Interfaces file.
NOTE: If you specified a value in the Network Address field on this tab, this field is disabled. When specifying connection information, you specify either a network address or an Interfaces file and server name.
Server Name: Type the name of the section in the Interfaces file that contains the network connection information for the Sybase server you want to access. The section name typically is the host name of the server that contains the Sybase server you want to access.
NOTE: If you specified a value in the Network Address field on this tab, this field is disabled. When specifying connection information, you specify either a network address or an Interfaces file and server name.
The equivalent connection string attribute is InterfacesFileServerName.
On this tab, provide any of the following optional information; then, click Apply.
Cursor Positioning for raiserror: Select a value that specifies when the error is returned and where the cursor is positioned when raiserror is encountered.
When set to 0 (the default), raiserror is handled separately from surrounding statements. The error is returned when raiserror is processed via SQLExecute, SQLExecDirect, or SQLMoreResults. The result set is empty.
When set to 1 (Microsoft compatible), raiserror is handled with the next statement. The error is returned when the next statement is processed; the cursor is positioned on the first row of the subsequent result set. This could result in multiple raiserrors being returned on a single execute.
The equivalent connection string attribute is RaiseErrorPositionBehavior.
Default Buffer Size for Long/LOB Columns (in Kb): Type an integer factor value that calculates the maximum length of data fetched from Long/LOB columns. The value must be in multiples of 1024 (for example, 1024, 2048). The default is 1024 KB. You need to increase the default value if the total size of any Long data exceeds 1 MB. This value is multiplied by 1024 to determine the total maximum length of fetched data. For example, if you enter a value of 2048, the maximum length of data would be 1024 x 2048, or 2097152 (2 MB).
This option also applies to binding long parameters in chunks. The driver truncates any data passed in a Long/LOB SQL_DATA_AT_EXEC parameter to the size specified.
This connection option can affect performance. See "Performance Considerations" for details.
The equivalent connection string attribute is DefaultLongDataBuffLen.
Distributed Transaction Model: Select a model to use for distributed transaction support-either XA Protocol or Native OLE.
Initialization String: Enter a semicolon-separated list of Sybase language commands that will be issued immediately after connection.
Report Codepage Conversion Errors: Select the method by which the driver handles code page conversion errors.
When set to 0 - Ignore Errors (the default), if the driver encounters code page conversion errors (a character cannot be converted from one character set to another), it makes a substitution for each character that cannot be converted and does not return a warning or error.
Error and Warning apply both to all ODBC API calls that could cause a conversion error and to all code page conversions to and from the database and to and from the application. The error or warning returned is Code page conversion error encountered. In the case of parameter data conversion errors, the driver adds the following sentence: Error in parameter x, where x is the parameter number. The standard rules for returning specific row and column errors for bulk operations still apply.
When set to 1 - Return Error, if the driver encounters code page conversion errors, it returns an error instead of substituting 0x1A for unconverted characters.
When set to 2 - Return Warning, if the driver encounters code page conversion errors, it substitutes 0x1A for each character that cannot be converted and returns a warning.
XA Open String Parameters: Type -Ltrace_filename, where trace_filename specifies the name of two trace files that will be created. The first trace file will trace all XA call activities and will be named exactly as you specified. The second trace file will contain tracing of any enlistment and unenlistment procedures and will be named as you specified with a "driver" extension. For example, if you specify XAtrace as the file name, the driver will create two trace files-XAtrace and XAtrace.driver.
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).
This option specifies what the client assumes about incoming data. This is not the same as setting the Charset option for the Sybase server. See Charset for details.
Application Using Threads: Select this check box to ensure that the driver works with multi-threaded applications. You can clear this check box when using the driver with single-threaded applications. Turning off this setting avoids additional processing required for ODBC thread-safety standards. By default, the check box is selected.
This connection option can affect performance. See "Performance Considerations" for details.
Enable Quoted Identifiers: Select this check box to enable quoted identifiers. When selected, 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 not selected, applications that use quoted identifiers encounter errors when they generate SQL statements with quoted identifiers. By default, the check box is not selected.
Enable Describe Parameter: Select this check box to enable the SQLDescribeParam function, which allows an application to describe parameters in SQL statements and in stored procedure calls. To use this option, the Prepare Method option on the Performance tab must be set to 0 or 1, and the SQL statement must not include long parameters. This option must be selected when using Microsoft Remote Data Objects (RDO) to access data.
The equivalent connection string attribute is EnableDescribeParam.
Tightly Coupled Distributed Transactions: Select this check box to use tightly coupled distributed transactions when connected to a Sybase 12 or higher server and to ensure that multiple connections within the same distributed transaction obey each other's locks.
When this check box is not selected, the overall performance of the driver is better, but multiple connections within the same distributed transaction may hang each other because the connections do not obey each other's locks.
This option is valid only when the driver is enlisted in a distributed transaction and when it is connected to a Sybase 12 or higher database. Otherwise, this option is ignored.
Truncate Time Type Fractions: Select this check box to cause the driver to set fractional seconds to zero when converting from SQL_TYPE_TIME to SQL_C_TYPE_TIMESTAMP, SQL_C_CHAR, or SQL_C_WCHAR. By default, the check box is not selected.
NOTE: This only applies to the Sybase 12.5.1 and higher Time data type.
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.
See "Using Security" for a general description of authentication and encryption and their requirements.
User Name: Type the default user ID used to connect to your database. Your ODBC application may override this value or you may override it in the logon dialog box or connection string.
The equivalent connection string attribute is LogonID.
Authentication Method: Select the method the driver uses to authenticate the user to the server when a connection is established.
When set to 0 - No Encryption (the default), the driver sends the user ID and password in clear text to the server for authentication.
When set to 1 - Encrypt Password, the driver sends the user ID in clear text and an encrypted password to the server for authentication. Note that the Sybase server must have password encryption enabled (Sybase 12.0 and higher). The specific encryption used is the algorithm required by the Sybase server and is completely implemented within the driver. This encryption capability in the driver is used only for the password at connect time and only when sending it across the network to the server.
When set to 4 - Kerberos, the driver uses Kerberos authentication. This method supports both Windows Active Directory Kerberos and MIT Kerberos environments.
If the specified authentication method is not supported by the database server, the connection fails and the driver generates an error.
Service Principal Name: Type the service principal name of the Sybase server that the driver uses with Kerberos authentication. This value has the following form:
servicePrincipalName
where servicePrincipalName is the service principal name of the Sybase server.
If no value is specified for Service Principal Name, then the value of Network Address is used as the service principal name. If Kerberos authentication is not used, the value of Service Principal Name is ignored.
GSS Client Library: Type the name of the GSS client library that the driver uses to communicate with the Key Distribution Center (KDC). The default value is native, indicating that the driver uses the GSS client that ships with the operating system. The driver uses the standard path for loading the specified client library.
Encryption Method: Select the method the driver uses to encrypt data sent between the driver and the database server.
When set to 0 - No Encryption (the default), data is not encrypted.
When set to 1 - SSL, data is encrypted using SSL.
If the specified encryption method is not supported by the database server, the connection fails and the driver returns an error.
This connection option can affect performance. See "Performance Considerations" for details.
Validate Server Certificate: Select this check box (the default) to validate the security certificate of the server as part of the SSL authentication handshake.
When this check box is not selected, the driver does not validate the security certificate of the server.
Truststore: If you are using SSL, type the path that specifies the location of the truststore file. The truststore file contains a list of the valid Certificate Authorities (CAs) that are trusted by the client machine for SSL server authentication.
Truststore Password: If you are using SSL, type the password required to access the truststore.
Host Name In Certificate: Type the host name established by the SSL administrator for the driver to validate the host name contained in the certificate. If no value is specified for Host Name In Certificate, the driver does not check the host name in the server certificate. The value of Host Name In Certificate is ignored if Validate Server Certificate is not selected or if Encryption Method does not specify SSL.
If a value is specified for Host Name In Certificate, the driver examines the subjectAltName values included in the certificate. If a dnsName value is present in the subjectAltName values, then the driver compares the value specified for Host Name In Certificate with the dnsName value. The connection succeeds if the values match. The connection fails if the Host Name In Certificate value does not match the dnsName value.
If no subjectAltName values exist or a dnsName value is not in the list of subjectAltName values, then the driver compares the value specified for Host Name In Certificate with the commonName part of the Subject name in the certificate. The commonName typically contains the host name of the machine for which the certificate was created. The connection succeeds if the values match. The connection fails if the Host Name In Certificate value does not match the commonName. If multiple commonName parts exist in the Subject name of the certificate, the connection succeeds if the Host Name In Certificate value matches any of the Common Name parts.
If the value specified for HostNameInCertificate is the special value #SERVERNAME#, then the driver compares the Network Address option value specified as part of a data source or connection string to the dnsName value or the commonName.
On this tab, provide any of the following optional information; then, click Apply.
Database List: Type the database names that are to appear in the drop-down list of the logon dialog box (see "Connecting to a Data Source Using a Logon Dialog Box" for a description). Separate the names with commas.
Workstation ID: Type the workstation ID used by the client.
Application Name: Type the name used by Sybase to identify your application.
Charset: Type the name of a character set. This character set must be installed on the Sybase server. The default is the setting on the Sybase server. For this driver to return Unicode SQL types, this option must be set to UTF-8 and you must be connected to a Sybase 12.5 or higher server. Refer to the Sybase server documentation for a list of valid character set names.
For example, if your client needs to receive data in iso-8859-1 from a non-Unicode Sybase server, you would specify a value of iso_1 for Charset.
This setting affects the Sybase server only. Charset is not a substitute for the IANAAppCodePage option. See IANAAppCodePage for details.
Language: Type the national language. This language must be installed on the Sybase server. The default is English.
On this tab, provide any of the following optional information; then, click Apply.
Select Method: Select a value of 0 or 1 that determines whether database cursors are used for Select statements.
When set to 0, the default, database cursors are used. In some cases performance degradation can occur when performing large numbers of sequential Select statements because of the amount of overhead associated with creating database cursors.
When set to 1, Select statements are run directly without using database cursors, and the data source is limited to one active statement.
This connection option can affect performance. See "Performance Considerations" for details.
Prepare Method: Select a value of 0, 1, 2, or 3 that determines whether stored procedures are created on the server for calls to SQLPrepare.
When set to 0, stored procedures are created for every call to SQLPrepare. This setting can result in decreased performance when processing statements that do not contain parameters.
When set to 1 (the initial default), the driver creates stored procedures only if the statement contains parameters. Otherwise, the statement is cached and run directly at the time of SQLExecute.
When set to 2, stored procedures are never created. The driver caches the statement, executes it directly at the time of SQLExecute, and reports any syntax or similar errors at the time of SQLExecute.
When set to 3, stored procedures are never created. This is identical to value 2 except that any syntax or similar errors are returned at the time of SQLPrepare instead of SQLExecute. Use this setting only if you must have syntax errors reported at the time of SQLPrepare.
This connection option can affect performance. See "Performance Considerations" for details.
The equivalent connection string attribute is OptimizePrepare.
Fetch Array Size: Type the number of rows the driver retrieves when fetching from the server. This is not the number of rows given to the user. The default is 50 rows.
This connection option can affect performance. See "Performance Considerations" for details.
The equivalent connection string attribute is ArraySize.
Packet Size: Type a value of -1, 0, or x that determines the number of bytes per packet transferred from the database server to the client machine. The correct setting of this option can improve performance. The optimal value depends on the typical size of data inserted, updated, or retrieved by the application and the environment in which it is running. Typically, larger packet sizes work better for large amounts of data. For example, if an application regularly retrieves character values that are 10,000 characters in length, using a value of 32 (16 KB) typically results in improved performance.
When set to -1, the driver computes the maximum allowable packet on the first connection to the data source and saves the value.
When set to 0, the default, the driver uses the default packet size as specified in the Sybase server configuration.
When set to x, an integer from 1 to 127, the driver uses a packet size represented by x times 512 bytes. For example, 6 means to set the packet size to 6 * 512 bytes (3072 bytes).
To take advantage of this option, you must configure the Sybase server for a maximum packet size greater than or equal to the value you specified for Packet Size times 127. Using the previous example:
sp_configure "maximum network packet size", 3072
reconfigure
Restart Sybase Server
NOTE: The ODBC specification identifies a connect option, SQL_PACKET_SIZE, that offers this same functionality. To avoid conflicts with applications that may set both, the Packet Size option and the ODBC connect option have been defined as mutually exclusive. If Packet Size is specified, you receive the message Driver Not Capable if you attempt to call SQL_PACKET_SIZE. If you do not set Packet Size, then application calls to SQL_PACKET_SIZE are accepted by the driver.
This connection option can affect performance. See "Performance Considerations" for details.
Connection Cache Size: Type a value that determines the number of connections that the connection cache can hold. The default setting is 1. To set the connection cache, you must set the Select Method option to 1- Direct. Increasing the connection cache may increase performance of some applications but requires additional database resources.
The equivalent connection string attribute is CursorCacheSize.
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 Sybase Wire Protocol driver, you must specify the network address of each alternate database server or the section in the Interfaces file that contains the network connection information for the Sybase database server you want to access (InterfacesFileServerName). The string has the format:
({NetworkAddress=addressvalue | InterfacesFileServerName=sectionvalue}[, . . .])
NetworkAddress and InterfacesFileServerName can be used in the same string. The following example Alternate Servers values define four alternate database servers for connection failover:
(InterfacesFileServerName=Accounting, NetworkAddress=\\MySybaseASE\Query, NetworkAddress="255.125.1.11, 4200", NetworkAddress="SybaseASE2, 4200")
Notice in the last two alternates that the network address is enclosed in quotation marks. This is because they contain commas and might be mistaken for the next alternate server in the list.
IMPORTANT: The alternate database servers specified for the Sybase Wire Protocol driver must be using the same network protocol as specified for the primary database server. On UNIX and Linux, only TCP/IP is supported; on Windows, the driver supports both Named Pipes and TCP/IP.
NOTE: The Alternate Servers option and the HA Failover Server Connection Information option are mutually exclusive. If you enter a value for the Alternate Servers, HA Failover Server Connection Information is not available.
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.
HA Failover Server Connection Information/Network Address: Type the network address of the High Availability (HA) Failover server to be used in the event of a connection loss. The driver detects the dropped connection and automatically reconnects to the HA Failover server specified by this attribute. This option is valid only for Sybase 12 and higher servers that have the High Availability Failover feature enabled.
Specify an IP address as follows: IP address, port_number. For example, you might enter 199.226.224.34, 5000. If your network supports named servers, you can specify an address as: servername, port_number. For example, you might enter Sybaseserver, 5000.
NOTE: The HA Failover Server Connection Information option and the Alternate Servers option are mutually exclusive. If you enter a value for the HA Failover Server Connection Information option, the Alternate Servers option is not available.
The equivalent connection string attribute is FailoverNetworkAddress.
NOTE: If you are configuring alternate servers for use with the connection failover feature, be aware that the Test Connect button tests only the primary server, not the alternate servers.