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

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

DSN=INFORMIX TABLES;DB=PAYROLL 

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

FILEDSN=Informix.dsn;DB=DBPAYROLL 

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

DRIVER=DataDirect Informix Wire Protocol; 
HOST=INF2;PORT=4321;SRVR=ACCT;DB=PAYROLL;UID=JOHN;PWD=XYZZY 
 



  
 

Table 5-1.  Informix 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. See "Using Connection Failover" for a discussion of connection failover.

 

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

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

 

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

AlternateServers=(Database=Infdb1: 
HostName=Informixhost1:PortNumber=5177: 
ServerName=accounting1, Database=Infdb2: 
HostName=Informixhost2:PortNumber=5178: 
ServerName=accounting2) 

 

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.



  
    
 

CancelDetect
Interval (CDI)


    
 

CancelDetectInterval={0 | 5 | 10 | 30 | 60}. A value in seconds that determines how often the driver checks whether a query has been canceled using SQLCancel.

 

If the driver determines that SQLCancel has been issued, the query is canceled. This attribute determines whether long-running queries in threaded applications are canceled if the application issues a SQLCancel. If set to 0 (the initial default), queries are not canceled even if SQLCancel is issued.

 

For example, if CancelDetectInterval is set to 5, then for every pending request, the driver checks every five seconds to see whether the application has canceled execution of the query using SQLCancel.

 

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. See "Using Connection Retry" 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 Informix data source configuration. Examples include Accounting or INFORMIX-Serv1.



  
    
 

HostName (HOST)


    
 

The name of the machine on which the Informix database resides or enter an IP address.

 

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.



  
    
 

IANAAppCodePage (IACP)

 




    
 

For a list of valid values for this attribute, refer to "Values for the Attribute IANAAppCodePage" in the DataDirect Connect64 for ODBC and Connect64 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 Connect64 for ODBC and Connect64 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). 



  
    
 

LoadBalancing (LB)


    
 

LoadBalancing={0 | 1}. Determines whether the driver uses client load balancing in its attempts to connect to primary and alternate database servers. See "Using Client Load Balancing" 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 name as specified on the Informix server.

 

The equivalent Setup dialog box option is User Name.



  
    
 

Password (PWD)


    
 

The password that the application uses to connect to your Informix database.



  
    
 

PortNumber (PORT)


    
 

The port number of the server listener. There is no default value.



  
    
 

ServerName
(SRVR)


    
 

The name of the Informix server as it appears in the sqlhosts file.



  
    
 

TrimBlankFrom
IndexName (TBFIN)


    
 

TrimBlankFromIndexName={0 | 1}. Determines whether the leading space is trimmed from a system-generated index name. This option is provided to address problems with applications that cannot process a leading space in index names. 

 

When set to 0, the driver does not trim the space.

 

When set to 1 (the initial default), the driver trims the leading space. 



  
    
 

UseDelimitedIdentifier (UDI)


    
 

UseDelimitedIdentifier={0 | 1}. Determines how the Informix server interprets double quotation (") characters in SQL statements. 

 

When set to 0 (the initial default), the Informix server interprets strings enclosed in double quotation marks as string literals, not as identifiers.

 

When set to 1, the driver sets the DELIMIDENT Informix environment variable, causing the Informix server to interpret strings enclosed in double quotation marks as identifiers, not as string literals.