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 Logon Dialog Box" and Table 2-1 for a complete description of driver connection string attributes and their values.

On UNIX and Linux, data sources for the MySQL Wire Protocol driver are configured and modified by editing the system information file (by default, odbc.ini) and storing default connection values there. Refer to "Configuring the Product on UNIX/Linux"of the DataDirect Connect64 for ODBC and Connect64 XE for ODBC User's Guide for detailed information about the specific steps needed to set up the UNIX and Linux environments and to configure both a data source (through odbc.ini) and a DSN-less connection (through odbcinst.ini).

NOTE: Currently, you cannot create or modify MySQL Wire Protocol driver data sources through the DataDirect ODBC Data Source Administrator for UNIX/Linux.

Table 2-1 lists the connection values, in the form of connection string attributes, which must be used in the system information file. Note that only the long name of the attribute can be used in the file. The following is a specific MySQL Wire Protocol driver example of these attributes as used in the odbc.ini file:

odbc.ini 

 
LicenseNotice=If DataDirect Connect64 for ODBC is licensed 
for the MySQL database the following shall apply: You must 
purchase commercially licensed MySQL database software or a 
MySQL Enterprise subscription in order to use the 
DataDirect Connect64 for ODBC for MySQL Enterprise driver 
with MySQL software.

The following is a specific MySQL Wire Protocol driver example of an odbcinst.ini file entry: 

[ODBC Data Sources] 
MySQL Wire Protocol=DataDirect 5.3 MySQL Wire Protocol 
[MySQL Wire Protocol] 
Driver=ODBCHOME/lib/ddmysql23.so 
Description=DataDirect 5.3 MySQL Wire Protocol 
AlternateServers= 
ApplicationUsingThreads=1 
ConnectionRetryCount=0 
ConnectionRetryDelay=3 
Database=<database_name> 
DefaultLongDataBuffLen=1024 
EnableDescribeParam=0 
HostName=<MySQL_host> 
LicenseNotice=Use of the MySQL Wire Protocol driver 
requires that customers purchase a commercially licensed 
MySQL database or MySQL Enterprise subscription for use 
with the driver. 
LoadBalancing=0 
LogonID= 
Password= 
PortNumber=<MySQL_server_port> 
ReportCodePageConversionErrors=0 
TreatBinaryAsChar=0

odbcinst.ini 

[ODBC Drivers] 
DataDirect 5.3 MySQL Wire Protocol=Installed 
[DataDirect 5.3 MySQL Wire Protocol] 
Driver=ODBCHOME/lib/ddmysql23.so 
APILevel=1 
ConnectFunctions=YYY 
DriverODBCVer=3.52 
FileUsage=0 
HelpRootDirectory=ODBCHOME/help 
Setup=ODBCHOME/lib/ivmysql23.so 
SQLLevel=1

On Windows, data sources are configured and modified through the ODBC Administrator using a driver Setup dialog box. 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: 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 MySQL data source on Windows:

  1. Start the ODBC Administrator; then, select a tab:
    • User DSN: If you are configuring an existing user data source, select the data source name on the User DSN tab and click Configure to display the driver Setup dialog box.

      • If you are configuring a new user data source, click Add on the User DSN tab to display a list of installed drivers. Select the MySQL Wire Protocol driver, and click Finish to display the driver Setup dialog box.

    • System DSN: To configure a new system data source, click Add on the System DSN tab to display a list of installed drivers. Select the MySQL Wire Protocol driver, and click Finish to display the driver Setup dialog box.
    • File DSN: If you are configuring an existing file data source, select the data source name on the File DSN tab, and click Configure to display the driver Setup dialog box.

      • If you are configuring a new file data source, click Add on the File DSN tab to display a list of installed drivers. Select the MySQL Wire Protocol driver, and click Next. 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.


      The General tab of the ODBC MySQL Wire Protocol Driver Setup dialog box

      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.

  2. On the General tab, provide the following information; then, click Apply.

    3. Data Source Name: Type a string that identifies this MySQL data source configuration. Examples include Accounting or MySQL-Serv1.

    Description: Type an optional long description of a data source name. For example, My Accounting Database or MySQL files on Server number 1.

    Host Name: Type the name of the machine on which the MySQL database resides.

    Port Number: Type the port number of the server listener. The default is 3306.

    Database Name: Type the name of the database to which you want to connect by default.

    The equivalent connection string attribute is Database.

  3. Optionally, click the Advanced tab to specify data source settings.


    4. The Advanced tab of the ODBC MySQL Wire Protocol Driver Setup dialog box

    On this tab, provide any of the following optional information; then, click Apply.

    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 SQLDescribeParam: Select this check box to enable the SQLDescribeParam function, which results in all parameters being described as a data type of SQL_VARCHAR with a length of 255 for statements.

    When this check box is not selected (the default), calls to the SQLDescribeParam function return the standard ODBC error IM001.

    The equivalent connection string is EnableDescribeParam.

    Interactive Client: Select this check box to initialize the wait_time session variable for the connection with the value of the global interactive_timeout variable. When this checkbox is cleared (the default), the driver initializes the wait_timeout session variable with the value of the global wait_timeout variable. This option determines how long a connection can be idle before the server disconnects it.

    NOTE: The wait_timeout variable controlled by the Interactive Client option is a session variable that can be modified by the application after the connection has been established. The Interactive Client option controls only the initial value of the wait_timeout session variable.

    Treat Binary Data as Character Data: Select this check box to enable the driver to describe and return data that MySQL stores as BINARY or VARBINARY as CHAR or VARCHAR values, respectively. For example, consider the following example.

    Create the following MySQL table:

    CREATE TABLE binTable (col1 binary(3))

    Then, execute the following Insert statement:

    INSERT INTO binTable values('abc')

    Then, execute the following query:

    SELECT col1 FROM binTable

    Using this example, the driver would return the value of col1 as a CHAR value, "abc", instead of a BINARY value "616263".

    When this check box is not selected (the default), the driver describes and returns data that MySQL describes as BINARY or VARBINARY as BINARY or VARBINARY values, respectively.

    The equivalent connection string attribute is TreatBinaryAsChar.

    Default User Name: Type your user ID as specified on the MySQL server.

    The equivalent connection string attribute is LogonID.

    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.

    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.

    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.

  4. Optionally, click the Failover tab to specify Failover data source settings.


    5. The Failover tab of the ODBC MySQL Wire Protocol Driver Setup dialog box

    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. Refer to "Using Client Load Balancing" in "Using The Product" of the DataDirect Connect64 for ODBC and Connect64 XE for ODBC User's Guide 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. Refer to "Using Connection Failover" in "Using The Product" of the DataDirect Connect64 for ODBC and Connect64 XE for ODBC User's Guide 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 MySQL Wire Protocol driver, you must specify the database name, host name, and port number. The string has the format:

    (Database=databasename:HostName=hostvalue:

    PortNumber=portvalue[, . . .])

    For example, the following Alternate Servers value defines two alternate database servers for connection failover:

    (Database=MySQLdb1:HostName=MySQLhost1:PortNumber=5177, Database=MySQLdb2:HostName=MySQLhost2:PortNumber=5178)

    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. Refer to "Using Connection Retry" in "Using The Product" of the DataDirect Connect64 for ODBC and Connect64 XE for ODBC User's Guide 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.    

  5. At any point during the configuration process, you can click Test Connect to attempt to connect to the data source using the connection properties 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 Established message. Click OK.
    • If the driver cannot connect because of an improper environment or incorrect connection value, it displays an appropriate error message.

      • Click OK.

      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.

  6. 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.