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 12-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 Oracle is:

DSN=Accounting;SRVR=QESRVR;UID=JOHN;PWD=XYZZY 

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

FILEDSN=Oracle.dsn;SRVR=QESRVR;UID=JOHN;PWD=XYZZY 

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

DRIVER=DataDirect Oracle;SRVR=QESRVR;CV=10GR1; 
UID=JOHN;PWD=XYZZY 

If the server name contains a semicolon, enclose it in quotation marks:

DSN=Accounting;SRVR="QE;SRVR";UID=JOHN;PWD=XYZZY 
 



  
 

Table 12-1.  Oracle 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.

 

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 Oracle driver, you must specify the server name. The string has the format:

(ServerName=servervalue[, . . .]) 

 

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

AlternateServers=(ServerName=AcctBackup1, 
ServerName=AcctBackup2) 

 

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



  
    
 

ApplicationUsing
Threads (AUT)


    
 

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

 

When set to 1 (the initial default), the driver is thread-safe. 

 

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.



  
    
 

ArraySize (AS)


    
 

The number of bytes the driver uses for fetching multiple rows. Values can be an integer from 1 to 4,294,967,296 (4 GB). Larger values increase throughput by reducing the number of times the driver fetches data across the network. Smaller values increase response time, as there is less of a delay waiting for the server to transmit data.

 

The initial default is 60000.

 

The value 1 is a special value that does not define the number of bytes but, instead, causes the driver to allocate space for exactly one row of data.

 

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



  
    
 

CatalogIncludesSynonyms (CIS)


    
 

CatalogIncludesSynonyms={0 | 1}. Determines whether synonyms are included in calls to SQLProcedures, SQLStatistics, and SQLProcedureColumns.

 

When set to 1, synonyms are included in these calls.

 

When set to 0, synonyms are not included (a non-standard behavior) and performance is improved.

 

The initial default is 1.

 

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

 

The equivalent Setup dialog box option is Catalog Functions Include Synonyms.



  
    
 

CatalogOptions (CO)


    
 

CatalogOptions={0 | 1}. Determines whether the result column REMARKS (for the catalog functions SQLTables and SQLColumns) and the result column COLUMN_DEF (for the catalog function SQLColumns) return actual values.

 

When set to 1, REMARKS and COLUMN_DEF return actual values.

 

When set to 0 (the initial default), REMARKS and COLUMN_DEF return SQL_NULL_DATA.

 

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



  
    
 

ClientVersion (CV)


    
 

ClientVersion={8i | 9iR1 | 9iR2 | 10gR1}. Specifies an Oracle client software version. The driver assumes that it is using the version of Oracle client software specified by this attribute to connect to an Oracle server. 

 

When set to 10gR1, the driver binds all non-integer numerics as Binary Float and Binary Double. When set to any Oracle version previous to 10g R1, the driver binds non-integer numerics as if connected to an Oracle 9i R2 or earlier version of the server (regardless of the actual version of the server to which it is connected). When connecting to an Oracle 10g server with a pre-10g client, this option must be set to the same version as the actual Oracle client software in use; otherwise, numeric parameter bindings may fail. Versions of the Oracle client software prior to 10g R1 do not fully support the new features of the Oracle 10g database server.

 

The initial default is 9iR1.



  
    
 

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.



  
    
 

DataSourceName (DSN)


    
 

A string that identifies an Oracle data source configuration. Examples include Accounting or Oracle-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.

 

NOTE: This attribute is ignored if OptimizeLong Performance (OLP) is enabled.

 

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



  
    
 

DescribeAtPrepare (DAP)


    
 

DescribeAtPrepare={0 | 1}. Determines whether the driver describes the SQL statement at prepare time.

 

When set to 0 (the initial default), the driver does not describe the SQL statement at prepare time.

 

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



  
    
 

EnableDescribeParam (EDP)


    
 

EnableDescribeParam={0 | 1}. Determines whether the ODBC API function SQLDescribeParam is enabled, which results in all parameters being described with a data type of SQL_VARCHAR. 

 

This attribute must be set to 1 when using Microsoft Remote Data Objects (RDO) to access data. 

 

The initial default is 0.

 

The equivalent Setup dialog box option is Enable SQLDescribeParam.



  
    
 

EnableNcharSupport (ENS)


    
 

EnableNcharSupport={0 | 1}. Determines whether the N-types NCHAR, NVARCHAR2, and NCLOB are supported.

 

When set to 1, these types are described as SQL_WCHAR, SQL_WVARCHAR, and SQL_WLONGVARCHAR, and are returned as supported by SQLGetTypeInfo. In addition, the "normal" char types (CHAR, VARCHAR2, LONG, CLOB) are described as SQL_CHAR, SQL_VARCHAR, and SQL_LONGVARCHAR regardless of the character set on the Oracle server. See "Unicode Support" for details.

 

NOTE: Valid only on Oracle 9i and higher.

 

The initial default is 0.



  
    
 

EnableScrollableCursors (ESC)


    
 

EnableScrollableCursors={0 | 1}. Determines whether scrollable cursors are enabled for the data source.

 

When set to 1 (the initial default), both Keyset and Static cursors are enabled.



  
    
 

EnableStaticCursorsFor
LongData (ESCLD)


    
 

EnableStaticCursorsForLongData={0 | 1}. Determines whether the driver supports Long columns when using a static cursor. Using this attribute causes a performance penalty at the time of execution when reading Long data. 

 

The initial default is 0.

 

NOTE: You must set this attribute to 1 if you want to persist a result set that contains Long data into an XML data file.

 

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



  
    
 

EnableTimestampWith
Timezone (ETWT)


    
 

EnableTimestampWithTimezone={0 | 1}. Determines whether the driver exposes timestamps with timezones to the application.

 

When set to 1, the driver issues an ALTER SESSION at connection time to modify NLS_TIMESTAMP_TZ_FORMAT. NLS_TIMESTAMP_TZ_FORMAT is changed to the ODBC definition of a timestamp literal with the addition of the timezone literal: 'YYYY-MM-DD HH24:MI:SSXFF TZR'.

 

The initial default is 0.



  
    
 

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.

 

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

 

 



  
    
 

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.



  
    
 

LocalTimeZoneOffset (LTZO)


    
 

Determines whether the driver acquires local time zone information from the operating system. The initial default value is "" (empty string), which means that, on Windows, the driver checks the operating system. If the information is not available from the operating system, the driver defaults to using the setting on the Oracle server.

 

Valid values are specified as offsets from GMT in the following format: (-)HH:MM. For example, -08:00 equals GMT minus 8 hours. The driver uses the value of the attribute to issue an "ALTER SESSION" for the local time zone at connect time.



  
    
 

LockTimeOut (LTO)


    
 

Determines whether Oracle waits for a lock to be freed before raising an error when processing a Select...For Update statement. When connected to an Oracle 9i or higher server, you can specify the number of seconds to wait by setting this attribute to an integer greater than 0.

 

When set to 0, Oracle does not wait.

 

When set to -1 (the initial default), Oracle waits indefinitely.

 

If you are connected to an Oracle 8i server, any value greater than 0 is equivalent to the value -1.

 

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



  
    
 

LogonID (UID)


    
 

The default user ID that the application uses to connect to your Oracle database. A logon ID is required only if security is enabled on your database. If so, contact your system administrator to get your logon ID.

 

You can also use OS Authentication to connect to your Oracle database. See "OS Authentication" for details.

 

The equivalent Setup dialog box option is Default User Name.



  
    
 

OptimizeLong
Performance (OLP)


    
 

OptimizeLongPerformance={0 | 1}. Determines whether the driver fetches Long data directly into the application's buffers rather than allocating buffers and making a copy. 

 

When set to 0 (the initial default), the driver allocates buffers for Long data.

 

When set to 1, the driver fetches Long data directly into the application's buffers. The time an application takes to fetch Long data decreases; however, it can cause the application to be limited to one active statement per connection.

 

NOTE: If this attribute is set to 1, the DefaultLongDataBuffLen (DLDBL) attribute is ignored.

 

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



  
    
 

Password (PWD)


    
 

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

 

You can also use OS Authentication to connect to your Oracle database. See "OS Authentication" for details.



  
    
 

ProcedureRetResults (PRR)



    
 

ProcedureRetResults={0 | 1}. Determines whether the driver returns result sets from stored procedure functions. 

 

When set to 0 (the initial default), the driver does not return result sets from stored procedures.

 

When set to 1, the driver returns result sets from stored procedures. See "Stored Procedure Results" for details. When set to 1 and you execute a stored procedure that does not return result sets, you will incur a small performance penalty.

 

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

 

The equivalent Setup dialog box option is Procedure Returns Results.



  
    
 

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.



  
    
 

ReportRecycleBin (RRB)


    
 

ReportRecycleBin={0 | 1}. Determines whether the driver reports objects that are in the Oracle Recycle Bin.

 

When set to 0 (the initial default), the driver does not report tables that are in the recycle bin.

 

When set to 1, the driver reports tables that are in the recycle bin.

 

Starting with Oracle 10g R1, when a table is dropped, it is not actually removed from the database, but placed in the recycle bin instead. The driver does not normally report tables in the recycle bin because such tables are not intended for use by applications.

 

By default, the driver does not return tables contained in the recycle bin in the result sets returned from SQLTables and SQLColumns when connected to Oracle 10g R1 or higher. Functionally, this means that the driver filters out any results whose table name begins with BIN$.

 

The equivalent Setup dialog box option is Report Objects in Recycle Bin.



  
    
 

ServerName (SRVR)


    
 

For local servers, use the SQL*Net connection string. If the SQL*Net connection string contains semicolons, enclose it in quotation marks. Refer to your SQL*Net documentation for more information.

 

For remote servers, the Oracle TNS Client connection string is the alias name of the Oracle Listener on your network.



  
    
 

TimestampEscapeMapping (TEM)


    
 

TimestampEscapeMapping={0 | 1}. Determines how the driver maps Date, Time, and Timestamp literals.

 

When set to 0 (the initial default), the driver determines whether to use the TO_DATE or TO_TIMESTAMP function based on the version of the Oracle server to which it is connected.

 

When set to 1, the driver always uses the Oracle 8.x TO_DATE function as if connected to an Oracle 8.x server.

 

When this attribute is set to 0, if the driver is connected to an Oracle 8.x server, it maps the Date, Time, and Timestamp literals to the TO_DATE function. If the driver is connected to an Oracle 9.x or higher server, it maps these escapes to the TO_TIMESTAMP function.



  
    
 

UseCurrentSchema (UCS)


    
 

UseCurrentSchema={0 | 1}. Specifies whether the driver returns only procedures owned by the current user when executing SQLProcedures.

 

When set to 1 (the initial default), the call for SQLProcedures is optimized, but only procedures owned by the user are returned.

 

When set to 0, the driver does not specify only the current user.

 

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

 

The equivalent Setup dialog box option is Use Current Schema for SQLProcedures.