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 10-1 for a complete description of driver connection string attributes and their values.
UNIX
On UNIX and Linux, you must set up the proper ODBC environment before configuring data sources. See "Environment Configuration" for basic setup information and "Environment Variables" for more detail about this procedure.
Data sources are stored in the system information file (by default, odbc.ini). If you have a Motif GUI environment on UNIX or Linux, you can configure and modify data sources through the DataDirect ODBC Data Source Administrator for UNIX/Linux (the UNIX ODBC Administrator) using a driver Setup dialog box, as described in the following procedure. (See "Configuration Through the UNIX ODBC Administrator" for a detailed explanation of the Administrator.)
If you do not have a GUI environment, you can configure and modify data sources directly by editing the system information file and storing default connection values there. See "Configuration Through the System Information File" for detailed information about the specific steps necessary to configure a data source.
Table 10-1 lists the connection values, in the form of connection string attributes, that must be used in the system information file. Note that only the long name of the attribute can be used in the file.
Windows
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, as described in the following section.
To configure a data source for a FoxPro 3.0 database container (DBC), see "FoxPro 3.0 DBC".
Configuration
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.
NOTE: This book shows dialog box images that are specific to Windows. If you are using the drivers in the UNIX/Linux environments, the dialog box that you see may differ slightly from the Windows version. Windows-only and UNIX-only connection options are specifically noted by icons in the Setup dialog box descriptions.
By default, edit boxes and drop-down lists on the Setup dialog box are empty unless a specific default is otherwise noted.
dBASE
To configure a dBASE data source:
- Start the ODBC Administrator:
- Select a tab:
- User DSN: If you are configuring an existing user data source, select the data source name and click Configure to display the driver Setup dialog box.
System DSN: If you are configuring an existing system data source, select the data source name and click Configure to display the driver Setup dialog box.- File DSN: If you are configuring an existing file data source, select the data source file and click Configure to display the driver Setup dialog box.
- On the General tab, provide the following information; then, click Apply.
- Optionally, click the Advanced tab to specify data source settings.
- Clipper specifies Clipper-compatible locking.
- dBASE specifies Borland-compatible locking.
- Fox specifies FoxPro-compatible locking.
- Q+E specifies that locks be 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.
- Q+EVirtual specifies that locks be 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 use index files that have different names than their corresponding data files and you have not defined this association, click the Define tab. See "Defining Index Attributes on Windows" for step-by-step instructions.
- 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.
- 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.
If you are configuring a new user data source, click Add to display a list of installed drivers. Select the driver and click Finish to display the driver Setup dialog box.
If you are configuring a new system data source, click Add to display a list of installed drivers. Select the driver and click Finish to display the driver Setup dialog box.
If you are configuring a new file data source, click Add to display a list of installed drivers. Select the driver and click Advanced to specify attributes; otherwise, click Next to proceed. 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.
NOTE: The General tab displays the only fields that are required for creating a data source. The fields on all other tabs are optional, unless noted otherwise.
Data Source Name: Type a string that identifies this dBASE data source configuration. Examples include Accounting or dBASE Files.
Description: Type an optional long description of a data source name. For example, My Accounting Database or dBASE files in C:\ACCOUNTS.
Database Directory: Type the path to the directory that contains the database files. If none is specified, the current working directory is used.
The equivalent connection string attribute is Database.
Create Type: Select the type of table or index to be created on a Create Table or Create Index statement. The default is dBASE5.
On this tab, provide any of the following optional information; then, click Apply.
Locking: Select the level of locking for the database file. FILE locks all of the records in the table. RECORD (the default) locks only the records affected by the statement. NONE offers the best performance, but is intended only for single-user environments. See "Locking" for details.
Lock Compatibility: Select the locking scheme the driver uses when locking records, either Clipper, dBASE, Fox, Q+E, or Q+EVirtual. The default is dBASE. 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. These values determine locking support as follows:
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 this value to 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 this value to Fox to ensure that your data does not become corrupted.
File Open Cache: Type an integer 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 locking conflict even though no one appears to have the file open. The default is 0, which means no file open caching.
Cache Size: Type 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 default is 4.
Data File Extension: Type the file extension to use for data files. The default setting is DBF. The setting cannot be greater than three characters, and it cannot be one the driver already uses, such as MDX or CDX. The Data File Extension setting is used for all Create Table statements. Sending a Create Table using an extension other than the value specified for this option causes an error.
In other SQL statements, such as Select or Insert, users can specify an extension other than the one specified for this connection option. The Data File Extension value is used when no extension is specified.
Extension Case: Select whether uppercase or lowercase file extensions are accepted. When set to UPPER (the default), uppercase extensions are accepted. When set to LOWER, lowercase extensions are accepted.
IANAAppCodePage: For a list of valid values for this option, 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 option 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:
If no IANAAppCodePage value is found, the driver uses the default value of 4 (ISO 8859-1 Latin-1).
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 Names: Select this check box to use long file names as table 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).
Use Long Qualifiers: Select this check box to use long path names as table qualifiers. When you select this check box, path names can be up to 255 characters. The default length for path names is 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.
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.
FoxPro 3.0 DBC
To configure a FoxPro 3.0 data container data source:
- Start the ODBC Administrator:
- Select a tab:
- User DSN: If you are configuring an existing user data source, select the data source name and click Configure to display the driver Setup dialog box.
System DSN: If you are configuring an existing system data source, select the data source name and click Configure to display the driver Setup dialog box.- File DSN: If you are configuring an existing file data source, select the data source file and click Configure to display the driver Setup dialog box.
- On the General tab, provide the following information; then, click Apply.
- Optionally, click the Advanced tab to specify data source settings.
- Clipper specifies Clipper-compatible locking.
- dBASE specifies Borland-compatible locking.
- Fox specifies FoxPro-compatible locking.
- Q+E specifies that locks be 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.
- Q+EVirtual specifies that locks be 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.
- 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.
If you are configuring a new user data source, click Add to display a list of installed drivers. Select the driver and click Finish to display the driver Setup dialog box.
If you are configuring a new system data source, click Add to display a list of installed drivers. Select the driver and click Finish to display the driver Setup dialog box.
If you are configuring a new file data source, click Add to display a list of installed drivers. Select the driver and click Advanced to specify attributes; otherwise, click Next to proceed. 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.
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.
Data Source Name: Type a string that identifies this FoxPro data source configuration, for example, Accounting.
Description: Type an optional long description of a data source name, for example, My Accounting Database.
Database Name: Type the path to the directory that contains the database files. If none is specified, the current working directory is used. Click Select to browse the available FoxPro 3.0 database containers.
The equivalent connection string attribute is Database.
Create Type: You cannot change the Create Type for the FoxPro 3.0 DBC driver.
On this tab, provide any of the following optional information; then, click Apply.
Locking: Select the level of locking for the database file. FILE locks all of the records in the table. RECORD (the default) locks only the records affected by the statement. NONE offers the best performance, but is intended only for single-user environments. See "Locking" for details.
Lock Compatibility: Select the locking scheme the driver uses when locking records, either Clipper, dBASE, Fox, Q+E, or Q+EVirtual. The default is dBASE. 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. These values determine locking support as follows:
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 this value to 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 this value to Fox to ensure that your data does not get corrupted.
File Open Cache: Type an integer 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 specifies file locking on open may get a locking conflict even though no one appears to have the file open. The default is 0, which means no file open caching.
Cache Size: Type 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 default is 4.
Data File Extension: Type the file extension to use for data files. The default setting is DBF. The setting cannot be greater than three characters, and it cannot be one the driver already uses, such as MDX or CDX. The Data File Extension setting is used for all Create Table statements. Sending a Create Table using an extension other than the value specified for this option causes an error.
In other SQL statements, such as Select or Insert, users can specify an extension other than the one specified for this attribute. The DataFileExtension value is used when no extension is specified.
Extension Case: Select whether uppercase or lowercase file extensions are accepted. When set to UPPER (the default), uppercase extensions are accepted. When set to LOWER, lowercase extensions are accepted.
IANAAppCodePage: For a list of valid values for this option, 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 option 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:
If no IANAAppCodePage value is found, the driver uses the default value of 4 (ISO 8859-1 Latin-1).
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 from the previous example 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 Names: Select this check box to use long file names as table 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).
Use Long Qualifiers: Select this check box to use long path names as table qualifiers. When you select this check box, path names can be up to 255 characters. The default length for path names is 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.
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.
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.