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 14-2 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 an XML data source:
- 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.
- 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.
- On the General tab, provide the following information; then, click Apply.
- On the General tab of the Configure Location dialog box, provide the following required information; then, click Apply.
- Optionally, click the Advanced tab of the Configure Location dialog box to specify additional information about the location you are defining.
- Data Island Format: This option causes new tables to be created with the Internet Explorer 5 Data Island XML style.
- ADO Format: This option causes new tables to be created with the ADO 2.5 XML style.
- DataDirect Format: This option causes new tables to be created with the DataDirect Format (the default). This format conforms to the W3C recommendation for XML schema, working draft April 07, 2000.
- Click Close to return to the ODBC XML driver Setup dialog box.
- Optionally, click the Advanced tab of the ODBC XML driver Setup dialog box to specify data source settings.
- Show Virtual Schemas Only. This option returns "XML" in the Schema Name column when a SQLTables or SQLColumns operation is performed when connected to a data source. For example:
- Show Manufactured Schemas Only. This option returns the manufactured schema names in the Schema Name column when a SQLTables or SQLColumns operation is performed when connected to a data source. The Location names you define for a data source are manufactured into a schema name by adding a # symbol after the Location names. For example:
- Show Both Virtual and Manufactured Schemas. This option returns both virtual and manufactured schema names when a SQLTables or SQLColumns operation is performed when connected to a data source. For example, the information from both of the preceding tables would be returned.
- Optionally, click the Options tab to specify data source connection values.
- 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 Setup window.
- 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 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.
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.
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 XML data source configuration. Examples include Accounting or XML Files.
Description: Type an optional long description of a data source name. For example, My Accounting Files or My XML Files in the Accounting Directory.
Location Names: The text box displays all existing location names defined for the data source you are configuring. The location names listed in the text box are used for connections according to the order that they are displayed. If you want to change the order or precedence, use the Up and Down buttons.
To define a location, click Add. The Configure Location dialog box appears.
Location Name: Type a name for the location you are defining, for example, Loc1.
Location Type: Select a location type. See "Defining Locations" for the definition of each type.
Location: Either type or select the location. See "Defining Locations" for valid values for each type of location.
On this tab, provide any of the following optional information; then, click Apply.
Table Hint: This field is valid only for Folder and HTML Document location types. Type a string that specifies an Extensible Sylesheet Language (XSL) pattern to identify the table or rowset nodes in an XML file. See "Using Hints for Tabular-Formatted XML Documents" for details.
The equivalent connection string attribute is location_name.Table Hint.
Row Hint: This field is valid only for Folder and HTML Document location types. Type a string that specifies an XSL pattern to identify the nodes that make up the rows in the rowset. See "Using Hints for Tabular-Formatted XML Documents" for details.
The equivalent connection string attribute is location_name.Row Hint.
Validate Schema: Select this check box to enable the validation of the XML document against its schema. By default, this check box is not selected. To process an XML document even if the document is not valid, clear the check box.
The equivalent connection string attribute is location_name.Validate Schema.
Resolve External References: Select this check box to enable the resolution of external references, such as DTDs, Schemas, Entities, and Notations. By default, this check box is not selected. Clearing this box allows the document to be processed, even if the XML parser cannot locate the external references.
The equivalent connection string attribute is location_name.Resolve External.
Flush Every Change: This check box is valid only for Folder location types. Select this check box to write the document to disk after every change. By default, this check box is selected. When this check box is not selected, the driver does not write the document to disk after every insert, update, or delete operation. Clearing this check box can improve performance.
Require User ID/Password: Select this check box to specify whether a User ID and password are required to establish a connection to the location you are defining. By default, this check box is not selected. When this check box is not selected, no user ID and password are required to establish a connection to the location. You must select this check box if the location you are defining is password-protected; otherwise, the connection will fail. Selecting this check box causes a Logon dialog box to appear when connecting with the driver.
The equivalent connection string attribute is location_name.Require Passwd.
User ID: Type the default user ID used to establish a connection to the location you are defining. This field is enabled, but not required, when the Use Required User ID/Password check box is selected. If you do not specify a user ID and you selected the Require User ID/Password check box, the driver will prompt you for a User ID at connection time.
The equivalent connection string attribute is location_name.User ID.
Password: Type the password used to establish a connection to the location you are defining. This field is enabled, but not required, when the Use Required User ID/Password check box is selected. If you do not specify a password and you selected the Require User ID/Password check box, the driver will prompt you for a password at connection time.
Table Creation: This group is valid only for Folder location types. Select one of these options to determine the style of XML that is generated when a new table is created. By default, DataDirect Format is selected.
See "Common Tabular Formats for XML Documents" for a description of each of these formats.
The equivalent connection string attribute is location_name.Create Type.
Delete Linked Schema: This check box is valid only for Folder location types. Select this check box to specify whether externally linked schema files are deleted when a table is deleted. The XML document for the table contains a link to this external schema file. If multiple XML documents are linked to the same schema file, the schema file is not deleted when a table is deleted. By default, this check box is not selected.
The equivalent connection string attribute is location_name.Delete Schema.
Max Rows to Scan: This option is valid only for XML Document location types. Type an integer that represents the maximum number of rows to scan when the XML driver is determining the data type of each column. During the scan, the driver inspects each column value in the row of a table and adjusts the data type determination for each column based on the corresponding value. The more sample column values it encounters, the more accurate the determination is.
By default, the value is 0, which means all rows in the table are scanned. Limiting the number of rows can reduce the amount of time it takes to determine the column information on very large documents. However, because less information is available, the determination of the data types can be incorrect.
The equivalent connection string attribute is location_name.Scan Rows.
On this tab, provide any of the following optional information; then, click Apply.
Logging: Select this check box to enable logging. The log file logs the SQL execution plan. By default, this check box is not selected. If you select the check box, a log file is created in the current directory. The default log file name is \Integrator.txt.
International Sort Order: 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."
Schema Mode: From the drop-down box, select one of the following options:
Report Codepage Conversion Errors: Select the method by which the driver handles code page conversion errors.
When set to 0 - Ignore Errors (the default), if the driver encounters code page conversion errors (a character cannot be converted from one character set to another), it makes a substitution for each character that cannot be converted and does not return a warning or error.
Error and Warning apply both to all ODBC API calls that could cause a conversion error and to all code page conversions to and from the database and to and from the application. The error or warning returned is Code page conversion error encountered. In the case of parameter data conversion errors, the driver adds the following sentence: Error in parameter x, where x is the parameter number. The standard rules for returning specific row and column errors for bulk operations still apply.
When set to 1 - Return Error, if the driver encounters code page conversion errors, it returns an error instead of substituting 0x1A for unconverted characters.
When set to 2 - Return Warning, if the driver encounters code page conversion errors, it substitutes 0x1A for each character that cannot be converted and returns a warning.
Driver Options: Type configuration options specific to the XML driver.