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.

DSN=data_source_name[;attribute=value[;attribute=value]...]

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.

DRIVER=[{]driver_name[}][;attribute=value[;attribute=value]
...]

Table 14-2 gives the names and descriptions of the attributes. It also lists the initial defaults that apply when no value is specified in either the connection string or in the data source definition in the system information. 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 XML is:

DSN=XML FILES;LOC1.Create Type=ADO25;Logging=1

FILEDSN=XML.dsn;LOC1.Create Type=ADO25;Logging=1

DRIVER=DataDirect 5.3 XML; LOC1={DataDirect Closed XML ADO Provider}

Table 14-2. XML Connection String Attributes
Attribute	Description
International Sort	International Sort={0 \| 1}. Determines the order that 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 Order.
location_name	`location_name`={DataDirect Closed XML ADO Provider}, where `location_name` is the name of the location you are defining for the connection, for example: LOC1={DataDirect Closed XML ADO Provider} See "Defining Locations" for an explanation of locations. The equivalent Configure Location dialog box option is Location Name.
location_name. Catalog Type Hint	`location_name`.Catalog Type Hint={Folder \| XML Document \| HTML Document}. Determines the type of location you are defining for the connection, for example: LOC1.Catalog Type Hint=XML Document The initial default is Folder. See "Defining Locations" for a definition of each location type.
location_name.Create Type	location_name.Create Type={IE5DataIsland \| ADO25 \| DataDirect}. Determines the style of tabular-formatted XML that is generated when a new table is created in the location specified by location_name. This attribute is valid only for Folder location types. When set to IEDataIsland, new tables are created with the Internet Explorer 5 Data Island XML style. When set to ADO25, new tables are created with the ADO 2.5 XML style. When set to DataDirect (the initial default), new tables are created with the DataDirect Format. This format complies to the W3C recommendation for XML schema, working draft April 07, 2000. See "Common Tabular Formats for XML Documents" for a description of each of these formats. The equivalent Configure Location dialog box option is Table Creation.
location_name.Delete Schema	location_name.Delete Schema={0 \| 1}. Determines whether externally linked schema files are deleted when a table is deleted from the location specified by location_name. 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. This attribute is valid only for Folder location types. When set to 0 (the initial default), externally linked schema files are not deleted when a table is deleted. When set to 1, externally linked schema files are deleted when a table is deleted. The equivalent Configure Location dialog box option is Delete Linked Schema.
location_name.Initial Catalog	Specifies the full path for a location. The location can be either a local file system or a web server, for example: LOC1.Initial Catalog=c:\xmlsample See "Defining Locations" for an explanation of locations.
location_name.Password	The password used to establish a connection to the location specified by location_name. A password is required only if the location to which you are connecting is password-protected. If so, contact your system administrator to get your password.
location_name.Require Passwd	location_name.Require Passwd={0 \| 1}. Specifies whether a User ID and password are required to establish a connection to the location specified by location_name. When set to 0 (the initial default), a User ID and password are not required. When set to 1, a User ID and password are required. You must set this attribute to 1 when the location to which you want to connect is password-protected; otherwise, the connection will fail. Setting this attribute to 1 causes a Logon dialog box to appear when connecting with the driver. The equivalent Configure Location dialog box option is Require User/ID Password.
location_name.Resolve External	location_name.Resolve External={0 \| 1}. Determines whether external references such as DTDs, Schemas, Entities, and Notations are resolved for the XML documents contained within the location specified by location_name. When set to 0, the documents are allowed to be processed, even if the XML parser cannot locate the external references. When set to 1 (the initial default), the documents are not allowed to be processed if the XML parser cannot locate the external references. The equivalent Configure Location dialog box option is Resolve External References.
location_name.Row Hint	A string that specifies an Extensible Stylesheet Language (XSL) pattern to identify the nodes that make up the rows in the rowset of a tabular-formatted XML document contained within the location specified by location_name. This attribute is valid only for Folder and HTML Document location types. See "Using Hints for Tabular-Formatted XML Documents" for details. The equivalent Configure Location dialog box option is Row Hint.
location_name.Scan Rows	Any positive integer that represents the maximum number of rows to scan during the column scan of a table in the location specified by location_name. This attribute is valid only for XML Document location types. When set to 0 (the initial default), the driver scans all rows in the table. Limiting the number of rows to scan 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 Configure Location dialog box option is Max Rows to Scan.
location_name.Table Hint	A string that specifies an XSL pattern to identify the table or rowset nodes in a tabular-formatted XML document contained within the location specified by location_name. This attribute is valid only for Folder and HTML Document location types. See "Using Hints for Tabular-Formatted XML Documents" for details.
location_name. Top Table Hint	A string that specifies an XSL pattern to identify where in a hierarchical-formatted XML document the table scan begins, for example, LOC1.Top Table Hint=/table/empdata. This attribute is valid only for XML Document location types. This attribute enables you to return only the data from an XML document that is relevant to your task, thus, eliminating unnecessary data from being reported.
location_name.User ID	The User ID (user name) used to establish a connection to the location specified by location_name. A User ID is required only if the location to which you are connecting is password-protected. If so, contact your system administrator to get your User ID.
location_name.Validate Schema	Validate Schema={0 \| 1}. Determines whether the XML documents contained within the location specified by location_name are validated against their schema. When set to 0 (the initial default), the XML documents are not validated against their schema. When set to 1, the XML documents are validated against their schema. This allows a well-formed XML document to be processed, even if the document is not valid.
Log Filename	The name of the file in which logging will occur. The initial default log file name is \Integrator.txt.
Logging	Logging={0 \| 1}. Determines whether internal information is logged. When set to 0 (the initial default), internal information is logged. When set to 1, internal information is not logged.
Max BLOB Compare Size	The number of bytes at the beginning of a BLOB when making comparisons in the XML driver's evaluator. If a BLOB is larger than the specified length, it is truncated before comparison.
Max BLOB Sort Size	The number of bytes at the beginning of a BLOB that are used when performing an Order By, Distinct, or Group By on a BLOB column. This option can affect in-memory indexes that are built over BLOB columns during a join. The initial default is 512. NOTE: Do not set the value higher than the default if the client application uses BLOBs as join condition columns.
Read Only	Read Only={0 \| 1}. Determines whether the data source is read-only. When set to 0, the data source is configured to be read/write (the initial default). When set to 1, the data source is configured to be read-only.
ReportCodepage ConversionErrors (RCCE)	ReportCodePageConversionErrors={0 \| 1 \| 2}. Provides flexibility for the way in which the driver returns error or warning messages associated with code page conversion. When set to 0 (the initial 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. Settings 1 and 2 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, if the driver encounters code page conversion errors, it returns an error instead of substituting 0x1A for unconverted characters. When set to 2, if the driver encounters code page conversion errors, it substitutes 0x1A for each character that cannot be converted and returns a warning.
Show Manufactured Schemas	Show Manufactured Schemas={0 \| 1}. Determines whether the manufactured schema name is returned when a SQLTables or SQLColumns operation is performed. See "Schema Mode" on page 597 for further explanation. When set to 0 (the initial default), virtual schema names are returned. When set to 1, manufactured schema names are returned. To return both manufactured and virtual schema names, set this connection string attribute to 1 and the Show Virtual Schemas connection string attribute to 1.
Show Virtual Schemas	Show Virtual Schemas={0 \| 1}. Determines whether the virtual schema name is returned when a SQLTables or SQLColumns operation is performed. See "Schema Mode" on page 597 for further explanation. When set to 1 (the initial default), virtual schema names are returned. When set to 0, manufactured schemas names are returned. To return both virtual and manufactured schema names, set this connection string attribute to 1 and the Show Manufactured Schemas connection string attribute to 1.
Use Floating Point Rounding	Use Floating Point Rounding={0 \| 1}. Determines whether the XML evaluator performs a small amount of rounding when comparing floating-point numbers. The binary representation of two identical floating-point numbers can be slightly different. When set to 0 (the initial default), the XML evaluator does not perform a small amount of rounding when comparing floating-point numbers. When set to 1, the evaluator compensates for slight differences.