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 7-1 and Table 7-2 give the names for each attribute, as well as a description. 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 Microsoft SQL Server is: 

DSN=ACCOUNTING;DATABASE=ACCT

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

FILEDSN=SQLServer.dsn;DATABASE=ACCT

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

DRIVER=DataDirect SQL Server Wire Protocol; 
DATABASE=ACCT;SERVER=SQL2;UID=JOHN;PWD=XYZZY

The connection string attribute names are case-sensitive.

Windows

Table 7-1. Windows SQL Server Wire Protocol Connection String Attributes 
Attribute
Description
AnsiNPW
AnsiNPW={yes | no}. Determines whether ANSI-defined behaviors are exposed.
When set to yes (the initial default), the driver uses ANSI-defined behaviors for handling NULL comparisons, character data padding, warnings, and NULL concatenation. If the driver appears to be truncating trailing blank spaces, this attribute should be set to no.
When set to no, ANSI-defined behaviors are not exposed.
APP
The name Microsoft SQL Server uses to identify your application.
The equivalent Setup dialog box option is Application Name.
AttachDBFileName
The name of the primary file of an attachable database. Include the full path and escape any slash ( \ ) characters if using a C character string variable:
AttachDBFileName=C:\\MyFolder\\MyDB.mdf
This database is attached and becomes the default database for the connection. To use AttachDBFileName, you must also specify the database name in either the SQLDriverConnnect DATABASE parameter or the SQL_COPT_CURRENT_CATALOG connection attribute. If the database was previously attached, Microsoft SQL Server will not reattach it; it will use the attached database as the default for the connection.
AutoTranslate
AutoTranslate={yes | no}. Determines how ANSI character strings are translated.
When set to yes (the initial default), ANSI character strings sent between the client and server are translated by converting through Unicode to minimize problems in matching extended characters between the code pages on the client and the server.
These conversions are performed on the client by the SQL Server Wire Protocol driver. This requires that the same ANSI code page (ACP) used on the server be available on the client.
These settings have no effect on the conversions that occur for the following transfers:
  • Unicode SQL_C_WCHAR client data sent to char, varchar, or text on the server.
  • Char, varchar, or text server data sent to a Unicode SQL_C_WCHAR variable on the client.
  • ANSI SQL_C_CHAR client data sent to Unicode nchar, nvarchar, or ntext on the server.
  • Unicode char, varchar, or text server data sent to an ANSI SQL_C_CHAR variable on the client.
When set to no, character translation is not performed.
The SQL Server Wire Protocol driver does not translate client ANSI character SQL_C_CHAR data sent to char, varchar, or text variables, parameters, or columns on the server. No translation is performed on char, varchar, or text data sent from the server to SQL_C_CHAR variables on the client.
If the client and Microsoft SQL Server are using different ACPs, then extended characters can be misinterpreted.
DATABASE
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 database must be an existing database unless AttachDBFileName is also specified. If AttachDBFileName is specified, the primary file it points to is attached and given the database name specified by DATABASE.
The equivalent Setup dialog box option is Database Name.
LANGUAGE
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.
Network
The name of a network library dynamic-link library. The name need not include the path and must not include the .DLL file name extension, for example, Network=dbnmpntw.
PWD
The password for the Microsoft SQL Server login account specified in the UID parameter. PWD need not be specified if the login has a NULL password or when using Windows NT authentication (Trusted_Connection = yes).
QueryLogFile
The full path and file name of a file to be used for logging data about long-running queries. QueryLog_On must be set to yes.
QueryLog_On
QueryLog_On={yes | no}. Determines whether data about long-running queries data is logged.
When set to yes, logging data about long-running queries data is enabled on the connection.
When set to no, long-running query data is not logged.
QueryLogTime
A digit character string specifying the threshold (in milliseconds) for logging data about long-running queries. Any query that does not receive a response in the time specified is written to the long-running query log file.
QuotedID
QuotedID={yes | no}. Determines whether the driver allows the use of quoted identifiers.
When set to yes, 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 set to no (the initial default), applications that use quoted identifiers encounter errors when they generate SQL statements with quoted identifiers.
The equivalent Setup dialog box option is Enable Quoted Identifiers.
Regional
Regional={yes | no}. Determines how currency, date, and time data are converted.
When set to yes, the SQL Server Wire Protocol driver uses client settings when converting currency, date, and time data to character data. The conversion is one way only; the driver does not recognize non-ODBC standard formats for date strings or currency values.
When set to no, the driver uses ODBC standard strings to represent currency, date, and time data that is converted to string data.
SAVEFILE
The name of an ODBC data source file into which the attributes of the current connection are saved if the connection is successful.
SERVER
Specify 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.
You can also specify 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) in the server box when you are using the same computer as Microsoft SQL Server. The user can then connect to a local copy of Microsoft SQL Server, even when running a non-networked version of Microsoft SQL Server. Microsoft SQL Server 2000 and higher support multiple instances of Microsoft SQL Server running on the same computer.
 
SnapshotSerializable
SnapshotSerializable={0 | 1}. For Microsoft SQL Server 2005 only. Allows your application to use Snapshot Isolation for connections.
To configure Snapshot Isolation for connections, you must have your Microsoft SQL Server 2005 database configured for Snapshot Isolation, your application must have the transaction isolation level set to Serializable, and this attribute must be set to 1.
If set to 0 (the default) and your application has the transaction isolation level set to Serializable, the application uses the Serializable isolation level.
This attribute is useful for applications that have the Serializable isolation level set. Using the SnapshotSerializable attribute in this case allows you to use Snapshot Isolation with no or minimum code changes. If you are developing 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 the snapshot isolation level.
This attribute can affect performance. See "Performance Considerations" for details.
The equivalent Setup dialog box option is Use Snapshot Transactions.
StatsLogFile
The full path and file name of a file used to record SQL Server Wire Protocol driver performance data. StatsLog_On must be set to yes.
StatsLog_On
StatsLog_On={yes | no}. Determines whether SQL Server Wire Protocol driver performance data is available.
When set to yes, SQL Server Wire Protocol driver performance data is captured.
When set to no (the initial default), SQL Server Wire Protocol driver performance data is not available on the connection.
Trusted_Connection
Trusted_Connection={yes | no}. Determines what information the SQL Server Wire Protocol driver uses for login validation.
When set to yes (the initial default), the SQL Server Wire Protocol driver requests 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 set to no, the SQL Server Wire Protocol driver uses a Microsoft SQL Server username and password for login validation. The UID and PWD keywords must be specified.
The equivalent Setup dialog box option is Use NT Authentication.
UID
A valid Microsoft SQL Server login account. UID need not be specified when using Windows NT authentication (Trusted_Connection = yes).
The equivalent Setup dialog box option is Default Login ID.
WSID
The workstation ID used by the client.
The equivalent Setup dialog box option is Workstation ID.

UNIX and Linux

Table 7-2. UNIX/Linux SQL Server Wire Protocol Connection String Attributes 
Attribute
Description
Address
Specify 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.
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.
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.
The equivalent Setup dialog box option is Server.
AlternateServers
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.
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 string attributes that you can set for this feature.
AnsiNPW
AnsiNPW={yes | no}. Determines whether ANSI-defined behaviors are exposed.
When set to yes (the initial default), the driver uses ANSI-defined behaviors for handling NULL comparisons, character data padding, warnings, and NULL concatenation. If the driver appears to be truncating trailing blank spaces, this attribute should be set to no.
When set to no, ANSI-defined behaviors are not exposed.
APP
The name Microsoft SQL Server uses to identify your application.
ConnectionRetryCount
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
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
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.
IANAAppCodePage
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.
Both this driver and the Driver Manager check 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).

LANGUAGE
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.
LoadBalancing
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 options that you can set for this feature.
PWD
The password for the Microsoft SQL Server login account specified in the UID parameter. PWD need not be specified if the login has a NULL password.
QuotedID
QuotedID={yes | no}. Determines whether the driver allows the use of quoted identifiers.
When set to yes, 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 set to no (the initial default), applications that use quoted identifiers encounter errors when they generate SQL statements with quoted identifiers.
SnapshotSerializable
SnapshotSerializable={0 | 1}. For Microsoft SQL Server 2005 only. Allows your application to use Snapshot Isolation for connections.
To configure Snapshot Isolation for connections, you must have your Microsoft SQL Server 2005 database configured for Snapshot Isolation, your application must have the transaction isolation level set to Serializable, and this attribute must be set to 1.
If set to 0 (the default) and your application has the transaction isolation level set to Serializable, the application uses the Serializable isolation level.
This attribute is useful for applications that have the Serializable isolation level set. Using the SnapshotSerializable attribute in this case allows you to use Snapshot Isolation with no or minimum code changes. If you are developing 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 the snapshot isolation level.
This attribute can affect performance. See "Performance Considerations" for details.
The equivalent Setup dialog box option is Use Snapshot Transactions.
UID
A valid Microsoft SQL Server login account.
NOTE: UID is not a valid attribute name for the system information file (odbc.ini); you must use LogonID instead.
WSID
The workstation ID used by the client.