Connecting to a Data Source 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), a File DSN, or a DSN-less connection in the string. The difference is whether you use the DSN=, FILEDSN=, or the DRIVER= keyword in the connection string, as described in the ODBC specification. A DSN or FILEDSN 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.

The DSN connection string has the form:

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

The FILEDSN connection string has the form:

FILEDSN=filename.dsn[;attribute=value[;attribute=value]...] 

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

Table 2-1 gives the long and short names for each attribute, as well as a description. You can specify either long or short names in the connection string. Connection string attribute names are the same as the option names on the driver Setup dialog box tabs unless otherwise noted. The connection string attribute name does not have spaces between the words. For example, the connection string attribute name ApplicationUsingThreads is equivalent to the option name Application Using Threads.

The defaults listed in the table are initial defaults that apply when no value is specified in either the data source definition or in the connection string. If you specified a value for the attribute when configuring the data source, that value is the default. Note that if no default value is listed in the table for attributes that use a string value, an empty string is the default value.

An example of a DSN connection string with overriding attribute values for MySQL is:

DSN=MySQL TABLES;DB=PAYROLL 

A FILEDSN connection string is similar except for the initial keyword:

FILEDSN=MySQL.dsn;DB=DBPAYROLL 

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

DRIVER=DataDirect MySQL Wire Protocol; 
HOST=MySQL2;PORT=3306;DB=PAYROLL;UID=JOHN;PWD=XYZZY 
 



  
 

Table 2-1.  MySQL Wire Protocol Connection String Attributes 


  
    
 

Attribute


    
 

Description



  
    
 

AlternateServers	 (ASRV)


    
 

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 connection string attribute enables connection failover for the driver. Refer to "Using Connection Failover" in "Using The Product" of the DataDirect Connect for ODBC and Connect XE for ODBC User's Guide for a discussion of connection failover.

 

For the MySQL Wire Protocol driver, you must specify the database, host name, and port number. The string has the format:

AlternateServers=(Database=databasename:HostName=host
value:PortNumber=portvalue[, . . .]) 

 

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

AlternateServers=(Database=MySQLdb1: 
HostName=MySQLhost1:PortNumber=3306, 
Database=MySQLdb2:HostName=MySQLhost2: 
PortNumber=3307) 

 

See "Configuring Connection Failover" for information about other connection string attributes that you can set for this feature.



  
    
 

ApplicationUsing
Threads (AUT)


    
 

ApplicationUsingThreads={0 | 1}. Determines whether the driver works with multi-threaded applications. 

 

When set to 1 (the initial default), the driver is thread-safe and is ensured to work with multi-threaded applications. 

 

When using the driver with single-threaded applications, you can set this option to 0 to avoid additional processing required for ODBC thread-safety standards.   

 

This attribute can affect performance. See "Performance Considerations" for details.



  
    
 

ConnectionRetryCount (CRC)


    
 

Specifies 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 Connect for ODBC and Connect 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 initial 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 attribute and the ConnectionRetryDelay connection string attribute, 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 string attributes that you can set for this feature.



  
    
 

ConnectionRetryDelay (CRD)


    
 

Specifies 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 initial default is 3 (seconds). When set to 0, there is no delay between retries.

 

NOTE: This attribute has no effect unless the ConnectionRetryCount connection string attribute is set to an integer value greater than 0.

 

This attribute and the ConnectionRetryCount connection string attribute, 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 string attributes that you can set for this feature.



  
    
 

Database (DB)


    
 

The name of the database to which you want to connect.

 

The equivalent Setup dialog box option is Database Name.



  
    
 

DataSourceName (DSN)


    
 

A string that identifies an MySQL data source configuration. Examples include Accounting or MySQL-Serv1.



  
    
 

DefaultLongDataBuffLen (DLDBL)


    
 

An integer factor value that specifies, in 1024-byte multiples, the maximum length of data fetched from Long/LOB columns. The value must be in multiples of 1024 (for example, 1024, 2048). 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 attribute 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.

 

The initial default is 1024.

 

This attribute can affect performance. See "Performance Considerations" for details.

 

The equivalent Setup dialog box option is Default Buffer Size for Long/LODB Columns (in KB).



  
    
 

EnableDescribeParam (EDP)


    
 

EnableDescribeParam={0 | 1}. Determines whether the ODBC API function SQLDescribeParam is enabled.

 

When set to 1, the SQLDescribeParam function describes all parameters as a data type of SQL_VARCHAR with a length of 255 for statements.

 

When set to 0 (the initial default), calls to the SQLDescribeParam function return the standard ODBC error IM001.

 

The equivalent Setup dialog box option is Enable SQLDescribeParam.



  
    
 

HostName (HOST)

 

 


    
 

The name of the machine on which the MySQL database resides.



  
    
 

IANAAppCodePage (IACP)

 




    
 

For a list of valid values for this attribute, 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 attribute 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.

 

The Driver Manager checks 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).



  
    
 

InteractiveClient (IC)

 

 


    
 

InteractiveClient={0 | 1}. Controls how the wait_timeout session variable of the connection is initialized. This determines how long a connection can be idle before the server disconnects it.

 

When set to 1, the driver initializes the wait_time session variable for the connection with the value of the global interactive_timeout variable.

 

When set to 0 (the initial default), the driver initializes the wait_timeout session variable with the value of the global wait_timeout variable

 

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



  
    
 

LoadBalancing (LB)


    
 

LoadBalancing={0 | 1}. Determines whether the driver uses client load balancing in its attempts to connect to primary and alternate database servers. Refer to "Using Client Load Balancing" in "Using The Product" of the DataDirect Connect for ODBC and Connect XE for ODBC User's Guide for more information.

 

When set to 1, the driver attempts to connect to the database servers in random order. 

 

When set to 0 (the initial 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 attribute has no effect unless alternate servers are defined for the AlternateServers connection string attribute.

 

The LoadBalancing connection string attribute 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 string attributes that you can set for this feature.



  
    
 

LogonID (UID)


    
 

Your user ID as specified on the MySQL server.

 

The equivalent Setup dialog box option is Default User Name.



  
    
 

Password (PWD)


    
 

A password.



  
    
 

PortNumber (PORT)


    
 

The port number of the server listener. The initial default is 3306.



  
    
 

ReportCodePage
ConversionErrors (RCCE)


    
 

ReportCodePageConversionErrors={0 | 1 | 2}. Provides flexibility for the way in which the driver returns error or warning messages associated with code page conversion. 

 

When set to 0 (the initial 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.

 

Settings 1 and 2 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, if the driver encounters code page conversion errors, it returns an error instead of substituting 0x1A for unconverted characters.

 

When set to 2, if the driver encounters code page conversion errors, it substitutes 0x1A for each character that cannot be converted and returns a warning.



  
    
 

TreatBinaryAsChar (TBAC)

 

 


    
 

TreatBinaryAsChar={0 | 1}. Determines the ODBC data type the driver uses to describe and return data that MySQL stores as BINARY or VARBINARY. By default, the driver describes and returns data that MySQL stores as BINARY or VARBINARY as BINARY or VARBINARY values, respectively.

 

When set to 1, the driver describes and returns 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 set to 0 (the initial default), the driver describes and returns data that MySQL describes as BINARY or VARBINARY as BINARY or VARBINARY values, respectively.

 

The equivalent Setup dialog box option is Treat Binary As Character Data.