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:
The FILEDSN connection string has the form:
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:
Table 9-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 Btrieve is:
A FILEDSN connection string is similar except for the initial keyword:
A DSN-less connection string must provide all necessary connection information:
DRIVER=DataDirect 5.3 Btrieve;
DB=J:\Btrvdata;UID=JOHN;PWD=XYZZY
Table 9-1. Btrieve 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.
|
|
ArraySize (AS)
|
An integer value that enables the driver to retrieve an array of records from the Btrieve database and in most cases results in better performance for the application. The value of ArraySize is the number of bytes in the array.
The initial default ArraySize is 4,096 bytes and the maximum is 65,535 bytes.
|
|
Database (DB)
|
The full path name of the directory that contains the Btrieve files and the data dictionary files (.DDF). Data dictionary files describe the structure of Btrieve data. If no directory is specified, the current working directory is used.
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 value, 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 DTA.
|
|
DataSourceName (DSN)
|
A string that identifies a Btrieve data source configuration. Examples include Accounting or Btrieve Files.
|
|
DeferQuery
Evaluation (DQ)
|
DeferQueryEvaluation={0 | 1}. Determines when a query is evaluated-after all records are read or each time a record is fetched.
When set to 0, the driver generates a result set when the first record is fetched. The driver reads all records, evaluates each one against the Where clause, and compiles a result set containing the records that satisfy the search criteria. This process slows performance when the first record is fetched, but activity performed on the result set after this point is much faster because the result set has already been created. You do not see any additions, deletions, or changes in the database that occur while working with this result set.
When set to 1 (the initial default), the driver evaluates the query each time another record is fetched and stops reading through the records when it finds one that matches the search criteria. This setting avoids the slowdown while fetching the first record, but each fetch takes longer because of the evaluation taking place. The data you retrieve reflects the latest changes to the database; however, a result set is still generated if the query is a Union of multiple Select statements, if it contains the Distinct keyword, or if it contains an Order By or Group By clause.
|
|
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 tables, the tables are not actually closed. The driver keeps them open so that if another query uses one of these tables, 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 file locking conflict even though no one appears to have the file open.
The initial default is 0, which means no file open caching.
|
|
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.
|
|
LogonID (UID)
|
The default logon ID used to connect to your Btrieve 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.
The equivalent Setup dialog box option is Default Logon ID.
|
|
Password (PWD)
|
The password that you must enter if your Scalable SQL data dictionary files have security restrictions set.
|
|
UndefinedTable (UT)
|
UndefinedTable={PROMPT | ERROR}. Determines whether the driver prompts the user when it encounters a table for which it has no structure information.
When set to PROMPT, the driver prompts the user.
When set to ERROR (the initial default), the driver returns an error.
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).
|