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 15-4 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 Text is:

DSN=Text1;DB=C:\TEXTDATA;TT=Comma 

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

FILEDSN=Text1.dsn;DB=C:\TEXTDATA;TT=Comma 

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

DRIVER=DataDirect 5.3 TextFile (*.*); 
DB=C:\TEXTDATA;TT=Comma 
 



  
 

Table 15-4.  Text Connection String Attributes 


  
    
 

Attribute


    
 

Description



  
    
 

AllowUpdateAnd
Delete (AUD)


    
 

AllowUpdateAndDelete={0 | 1}. Determines whether a data source allows Update and Delete statements. Because Update and Delete statements cause immediate changes to a text file, only one connection at a time can operate on a file. 

 

When set to 1, text files are opened exclusively by the current connection. Each update and delete on a text file can cause significant changes to the file, and performance may be poor. Consider a more appropriate database form if performance is a significant factor.

 

The initial default is 0. 



  
    
 

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.   



  
    
 

CacheSize (CSZ)


    
 

The number of 64 KB blocks the driver uses to cache database records. The greater the number of blocks, the better the performance. The maximum number of blocks you can set depends on the system memory available. If the cache size is greater than 0, when browsing backwards, you will not be able to see updates made by other users until you run the Select statement again. 

 

The initial default is 4.



  
    
 

CenturyBoundary (CB)


    
 

CenturyBoundary=20. Specifies the cutoff year for century inference when converting two-digit dates to four-digit dates. Two-digit dates that are less than the specified year number will be converted to 20xx. Two-digit dates greater than or equal to the number will be converted to 19xx. The default value is 20. For example, using the default value of 20, a date of 19 will be interpreted as 2019 and a date of 21 will be interpreted as 1921.



  
    
 

Database (DB)


    
 

The directory in which the text files are stored.

 

The equivalent Setup dialog box option is Database Directory.



  
    
 

DataFileExtension (DFE)


    
 

The file extension to use for data files. The Data File Extension setting cannot exceed three characters. The Data File Extension setting is used for all Create Table statements. Sending a Create Table using an extension other than the Data File Extension setting causes an error.

 

In other SQL statements, such as Select or Insert, users can specify an extension other than the Data File Extension setting. The Data File Extension setting is used when no extension is specified.

 

The initial default is TXT.



  
    
 

DataSourceName (DSN)


    
 

A string that identifies a Text data source configuration. Examples include Accounting or Text Files.



  
    
 

DecimalSymbol (DS)


    
 

DecimalSymbol={. | ,}. Specifies the decimal separator used when data is stored. The international decimal symbol (.), which is the initial default, must be used in DML statements and parameter buffers.



  
    
 

Delimiter (DC)


    
 

The character used as a delimiter for character-separated files. It can be any printable character except single quotes, double quotes, or semicolons. Note that it is possible to specify a semicolon if you configure the data source using the ODBC Administrator (Windows only).

 

The initial default is a comma (,).

 

The equivalent Setup dialog box option is Delimiter Character.



  
    
 

ExtraExtensions (EE)

 




    
 

A list of additional file name extensions to be recognized as text files. When an application requests a list of files, only files that have been defined are returned. To have the driver also return names of undefined files, specify a comma-separated list of file extensions. To specify files with no extension, use the keyword None.

 

The equivalent Setup dialog box option is ExtensionList.



  
    
 

FileOpenCache (FOC)


    
 

The maximum number of unused file opens to cache. For example, when FileOpenCache=4, and a user opens and closes four files, the files are not actually closed. The driver keeps them open so that if another query uses one of these files, the driver does not have to perform another open, which is expensive. The advantage of using file open caching is increased performance. The disadvantage is that a user who tries to open the file exclusively may get a locking conflict even though no one appears to have the file open. 

 

The initial default is 0.



  
    
 

FirstLineNames (FLN)


    
 

FirstLineNames={0 | 1}. Determines whether the driver looks for column names in the first line of the file. 

 

When set to 0 (the initial default), the first line is interpreted as the first record in the file.

 

When set to 1, the driver looks for column names in the first line of the file. 

 

The equivalent Setup dialog box option is Column Names in First Line.



  
    
 

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



  
    
 

IntlSort (IS)


    
 

IntlSort={0 | 1}. Determines the order in which records are retrieved when you issue a Select statement with an Order By clause. 

 

When set to 0 (the initial default), the driver uses the ASCII sort order. This order sorts items alphabetically with uppercase letters preceding lowercase letters. For example, "A, b, C" is sorted as "A, C, b."

 

When set to 1, the driver uses the international sort order as defined by your operating system. This order is always alphabetic, regardless of case; the letters from the previous example are sorted as "A, b, C." Refer to your operating system documentation concerning the sorting of accented characters.

 

The equivalent Setup dialog box option is International Sort.



  
    
 

ScanRows (SR)


    
 

The number of rows in a text file that the driver scans to determine the column types in the file. If the value is 0, all rows in the file are scanned. 

 

The initial default is 25.

 

The equivalent Setup dialog box option is Rows to Scan.



  
    
 

TableType (TT)


    
 

TableType={Comma | Tab | Character | Fixed | Stream}. The Text driver supports five table (text file) types: comma-separated, tab-separated, character-separated, fixed length, and stream. Setting this value tells the driver the default type, which is used when creating a new table and opening an undefined table.

 

The equivalent Setup dialog box option is Default Table Type.



  
    
 

UndefinedTable (UT)


    
 

UndefinedTable={PROMPT | GUESS}. Determines whether the driver prompts the user when it encounters a table (text file) for which it has no structure information.

 

When set to PROMPT, the driver is told to display a dialog box that allows the user to describe the file's format. 

 

When set to GUESS (the initial default), the driver is told to guess the file's format.

 

The equivalent Setup dialog box option is Action for Undefined Tables.



  
    
 

UseLongQualifiers (ULQ)

 




    
 

UseLongQualifiers={0 | 1}. Determines whether the driver uses long path names as table qualifiers. 

 

When set to 0 (the initial default), the driver does not use long path names (the maximum path name length is 128 characters). 

 

When set to 1, the driver uses long path names (the maximum path name length is 255 characters).



  
    
 

NOTE: The ScanRows, TableType, Delimiter, and FirstLineNames attributes apply to tables that have not been defined. These attributes also determine the characteristics of new tables created with the Create Table statement.