Configuring Data Sources

After you install the driver, you need to configure a data source or use a connection string to connect to the database. If you want to use a data source, but need to change some of its values, you can either modify it or override its values through a connection string. See "Quick Start Connect" for an explanation of different types of data sources.

If you choose to use a connection string, you must use specific connection string attributes. See "Connecting to a Data Source Using a Connection String" and Table 9-1 for a complete description of driver connection string attributes and their values.

See "Quick Start Connect" for an explanation of different types of data sources as well as instructions on starting and using the Windows ODBC Administrator.

On Windows, data sources are stored in the Windows Registry. You can configure and modify data sources through the ODBC Administrator using a driver Setup dialog box.

Default connection values are specified through the options on the tabs of the Setup dialog box. Connection string attributes that override these options have the same names as the options unless noted otherwise. The connection string attribute name does not have spaces between the words. For example, the option name Application Using Threads is equivalent to the connection string attribute name ApplicationUsingThreads.

By default, edit boxes and drop-down lists on the Setup dialog box are empty unless a specific default is otherwise noted.

To configure a Btrieve data source:

  1. Start the ODBC Administrator; then, select a tab:
    • User DSN: If you are configuring an existing user data source, select the data source name on the User DSN tab and click Configure to display the driver Setup dialog box.

      • If you are configuring a new user data source, click Add on the User DSN tab to display a list of installed drivers. Select the driver and click Finish to display the driver Setup dialog box.

    • System DSN: To configure a new system data source, click Add on the System DSN tab to display a list of installed drivers. Select the driver and click Finish to display the driver Setup dialog box.
    • File DSN: If you are configuring an existing file data source, select the data source name on the File DSN tab and click Configure to display the driver Setup dialog box.

      • If you are configuring a new file data source, click Add on the File DSN tab to display a list of installed drivers. Select the driver and click Next. Specify a name for the data source and click Next. Verify the data source information; then, click Finish to display the driver Setup dialog box.

      The General tab of the Setup dialog box appears by default.


      The General tab of the ODBC Btrieve Driver Setup dialog box

      NOTE: The General tab displays only fields that are required for creating a data source. The fields on all other tabs are optional, unless noted otherwise.

  2. On the General tab, provide the following information; then, click Apply.

    3. Data Source Name: Type a string that identifies this Btrieve data source configuration. Examples include Accounting or Btrieve Files.

    Description: Type an optional long description of a data source name. For example, My Accounting Database or Btrieve files in C:\ACCOUNTS.

    Database Directory: Type 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 connection string attribute is Database.

  3. Optionally, click the Advanced tab to specify data source settings.


    4. The Advanced tab of the ODBC Btrieve Driver Setup dialog box

    On this tab, provide any of the following optional information; then, click Apply.

    Default Logon ID: Type the default logon ID used to connect to your Btrieve database. A logon ID is required only if security is enabled on your database. Your ODBC application may override this value or you may override this value in a connection string.

    The equivalent connection string attribute is LogonID.

    File Open Cache: Type the numeric value to specify the maximum number of used file handles to cache. For example, the value 4 specifies that when 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 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 default is 0, which means no file open caching.

    Array Size: Type the number of bytes in the array. This connection option 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 default value is 4,096 bytes, and the maximum is 65,535 bytes.

    Data File Extension: Type a string of three or fewer characters that specifies the file extension to use for data files. The default value is DTA. This value is used for all Create Table statements. Sending a Create Table statement that uses an extension other than the one specified as the Data File Extension value causes an error.

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

    Action for Undefined Tables: Select one of the following options to indicate whether the driver prompts the user when it encounters a table for which it has no structure information:

    • Prompt for Definition to prompt the user
    • Return Error Condition (the default) to return an error

    The equivalent connection string attribute is UndefinedTable.

    International Sort: Select this check box to use international sort order as defined by your operating system when you issue a Select statement with an Order By clause. This order is always alphabetic, regardless of case; the letters are sorted as "A, b, C." Refer to your operating system documentation concerning the sorting of accented characters.

    If this check box is cleared (the default), ASCII sort order is used. This order sorts items alphabetically with uppercase letters preceding lowercase letters. For example, "A, b, C" is sorted as "A, C, b."

    The equivalent connection string attribute is IntlSort.

    Use Long Qualifiers: Select this check box to specify that the driver uses long path names. In this case, path names can be a maximum of 255 characters. If the check box is cleared (the default), path names can be a maximum of 128 characters.

    Application Using Threads: Select this check box to ensure that the driver works with multi-threaded applications. You can clear this check box when using the driver with single-threaded applications. Turning off this setting avoids additional processing required for ODBC thread-safety standards. By default, the check box is selected.

    Define: Click Define to define table structure. See "Defining Table Structure" for step-by-step instructions.



    Translate: Click Translate to display the Select Translator dialog box, which lists the translators specified in the ODBC Translators section of the Registry. DataDirect provides a translator named OEM to ANSI that translates your data from the IBM PC character set to the ANSI character set.

    Select a translator; then, click OK to close this dialog box and perform the translation.

  4. At any point during the configuration process, you can click Test Connect to attempt to connect to the data source using the connection properties specified in the driver Setup dialog box.
    • If the driver can connect, it releases the connection and displays a Connection established! message. Click OK.
    • If the driver cannot connect because of an incorrect environment or connection value, it displays an appropriate error message.

      • Verify that all required client software is properly installed. If it is not, you will see the message:

      Specified driver could not be loaded due to system error [xxx].

      Click OK.

  5. Click OK or Cancel. If you click OK, the values you have specified become the defaults when you connect to the data source. You can change these defaults by using this procedure to reconfigure your data source. You can override these defaults by connecting to the data source using a connection string with alternate values.