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 10-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 dBASE is:

DSN=DBASE FILES;LCK=NONE;IS=0 

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

FILEDSN=DBASE.dsn;LCK=NONE;IS=0 

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

DRIVER=DataDirect 5.3 dBASEFile (*.dbf); 
DB=C:\DBASE;CT=dBASE5 
 



  
 

Table 10-1.  dBASE Connection String Attributes 


  
    
 

Attribute


    
 

Description



  
    
 

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.



  
    
 

CreateType (CT)


    
 

CreateType={dBASE4 | dBASE5 | Clipper | FoxPro25 | FoxPro30}. Specifies the type of table or index to be created on a Create Table or Create Index statement. 

 

The initial default is dBASE5.



  
    
 

Database (DB)


    
 

The directory in which the dBASE files are stored.

 

The equivalent Setup dialog box option is Database Directory.



  
    
 

DataFileExtension (DFE)


    
 

A string of three or fewer characters that specifies the file extension to use for data files. This value is used for all Create Table statements. If you execute a Create Table statement that uses an extension other than the one specified as the DataFileExtension, an error occurs.

 

In other SQL statements, such as Select or Insert, you can specify an extension other than the DataFileExtension value. If you do not specify an extension value in these cases, the DataFileExtension value is used.

 

The initial default is DBF.



  
    
 

DataSourceName
(DSN)


    
 

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



  
    
 

ExtensionCase (EC)

 




    
 

ExtensionCase={LOWER | UPPER}. Specifies whether uppercase or lowercase file extensions are accepted. 

 

When set to LOWER, lowercase extensions are accepted. 

 

When set to UPPER (the initial default), uppercase extensions are accepted.



  
    
 

FileOpenCache (FOC)


    
 

An integer value that determines the maximum number of used file handles 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, which means no file open caching.



  
    
 

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.



  
    
 

LockCompatibility (LCOMP)


    
 

LockCompatibility={Clipper | dBASE | Fox | Q+E | Q+EVirtual}. Specifies the locking scheme to be used in your dBASE tables. The advantage of using a Q+E locking scheme over dBASE locking is that, on Inserts and Updates, Q+E locks only individual index tags, while dBASE locks the entire index.

 

When set to Clipper, Clipper-compatible locking is specified.

 

When set to dBASE (the initial default), Borland-compatible locking is specified. 

 

When set to Fox, FoxPro-compatible locking is specified.

 

When set to Q+E, locks are placed on the actual bytes occupied by the record. Only applications that use the dBASE driver can read and write to the database. Other applications are locked out of the table completely (they cannot even read other records). This locking is compatible with earlier versions of Q+E products.

 

When set to Q+EVirtual, locks are placed on bytes beyond the physical end-of-file. Q+EVirtual is the same as Q+E except that other applications can open the table and read the data.

 

If you are accessing a table with an application that uses the dBASE driver, your locking scheme does not have to match the Create Type. If you are accessing a table with two applications, however, and only one uses the dBASE driver, set your locking scheme to match the other application. For example, you do not have to set LCOMP=Fox to work with a FoxPro table. But if you are using a FoxPro application simultaneously with an application using the dBASE driver on the same set of tables, set LCOMP=Fox to ensure that your data does not get corrupted. See "Locking" for details.



  
    
 

Locking (LCK)


    
 

Locking={NONE | RECORD | FILE}. Determines the level of locking for the database tables. 

 

When set to NONE, the best performance is offered, but is intended only for single-user environments.

 

When set to RECORD (the initial default), only the records affected by the statement are locked.

 

When set to FILE, all of the records in the table are locked.



  
    
 

UltraSafeCommit (USF)


    
 

UltraSafeCommit={0 | 1}. Specifies when the driver flushes the file cache. 

 

When set to 0 (the initial default), the driver updates the directory entry when the file is closed. In this case, a machine "crash" before closing the file causes newly inserted records to be lost.

 

When set to 1, the driver updates directory entries after each Commit. This decreases performance. 



  
    
 

UseLongNames (ULN)


    
 

UseLongNames={0 | 1}. Determines whether the driver uses long file names as table names. 

 

When set to 0 (the initial default), the driver does not use long file names. 

 

When set to 1, the driver uses long file names. The maximum table name length is specific to the environment in which you are running (for example, in Windows 98, the maximum table name length is 128).



  
    
 

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