Connection Strings

• Connection String Rules
• Opening and Closing Connections During Scanning
• ADO Connection String Parameters
• Using a URL for a Connection String

Connection String Rules for the Scantron OLE DB Provider

Typically, the consumer will explicitly specify the data file and application definition file paths. When the directory portion is absent, the current directory is assumed.

Whenever a file is explicitly specified and it does not exist or has some error associated with it, the connection attempt will fail with an appropriate error.

If the data file is explicitly specified and the application definition file is unspecified, then the OLE DB provider uses the first 3 characters of the *.dat file as the application number and looks for z<App-Number>.SDS.StxAppDef in the same folder as the *.dat file. If it is present, the OLE DB provider uses that file to initialize the connection. The connection attempt succeeds if the file is not found. Subsequently, when a query is made for a table or column that is not there, the provider reports an error – table or column not found. This allows users to use *.dat files without meta data. A typical use case is a diagnostics utility.

If the data file is unspecified and the application definition file is explicitly specified, the initialization attempt is allowed to succeed. the OLE DB provider uses the the application number (the last 3 characters of the *.SDS.StxAppDef file) as the data file name and looks for <App-Number>.dat in the same folder as the *.SDS.StxAppDef file. If a data file is not found, a use case is schema retrieval. On a subsequent data query, an empty result set may be created.

If neither file is specified, the provider still allows the connection to succeed. Subsequently data queries will likely return no rows or error out. One use case is the retrieval of meta data information for the NCS Header portion of the data file.

These are currently not used by the OLE DB Provider:

You or your solution will explicitly specify the data file and application definition file paths.

WARNING: ADO scans the connection string only for well known and provider specific attributes. Any other information is ignored. In particular, ADO does not report an error if you specify "sample.dat" instead of "Data File=sample.dat;". ADO will pass on an empty string for the property to the OLE DB provider. ADO will report an error if the connection string as a whole is empty. It cannot locate the OLE DB provider.

See also:

ADO Example--Open an ADO recordset object using a URL

Opening and Closing Connections During Scanning

We recommend that you open and close the connection between your scanning solution and the OLE DB provider during the processing of each event used during scanning. In order for the connection to be closed immediately so scanning can continue, connection pooling must be disabled. This practice will help you avoid potential problems associated with accessing files that, as a result of ongoing scanning operations, may have changed during the connection.

Opening a connection at the start of an event and closing it at the end of the event will cause minimal performance degradation. If performance is a concern, the connection may be left open while accessing application definition files, edit profiles, and schema rowsets.

When a solution opens a connection to the OLE DB provider, the connection string specifies the names of the files to which the connection is made. When files are changed after the connection is made (clips added to the clip file; records added to the data file), the OLE DB provider does not track the changes, creating the potential for errors.

Some files change while others do not:

• Data (*.dat) files and clip (*.tif) files change during the connection because scanning adds new clips and records to the files.
• Application definition (*.sds.StxAppDef) files and edit (*.$epStxEdtPrf) profiles remain unchanged for the duration of the connection. Connections to schema rowsets, including ARCHIVE_INDICES Rowset, CLIPS Rowset, COLUMNS Rowset, Primary_Keys Rowset, Provider_Types Rowset, and TABLES Rowset, also remain unchanged.

ADO Connection String Parameters for the Scantron OLE DB Provider

To connect to the Scantron OLE DB Provider (Scantron.Oledb), set the Provider argument of the ConnectionString property to:

Scantron.Oledb

This value can also be set or read using the Provider property.

Typical Connection String

An example connection string for the Scantron OLE DB Provider is:

"Provider=Scantron.Oledb; Data File=sample.dat; App File = z701.sds.StxAppDef; mode = Read; License=XXXXXXXXXXXXXX:"

where XXXXXXXXXXXXXX is the 14 digit license key string that came with your copy of ScanTools Plus Link SDK.

The string consists of these keywords:

Relative and network paths are supported as file paths. Network paths may use mapped drive letters or UNC.

Examples of supported paths

..\..\data\sample.dat

\\rhino\share\data files\sample.dat

NOTE: Be sure to specify read-write mode in the connection string if you plan to perform an update, delete, or insert. If not specified, the default mode is Read|ShareDenyNone. See Data Link Properties dialog - Advanced Tab.

Provider-Specific Connection Parameters

The Scantron OLEDB Provider supports several provider-specific connection parameters in addition to those defined by ADO. As with the ADO connection properties, these provider-specific properties can be set via the Properties collection of a Connection or can be set as part of the ConnectionString.

Using a URL for a Connection String

Using a URL as a connection string for the Scantron OLE DB Provider can simplify your programming effort because it employs static binding. The provider registers the URL scheme OPL6.

Syntax of the URL in BNF notation

<URL> ::= <Prefix><Data Spec>[<Sep>[<Meta Data Spec>[<Sep>]]]

<Prefix> ::= URL=<Scheme>

<Data Spec> ::= Data File=<data file path> | <DAT file path> | "<DAT file path>"

<Meta Data Spec> ::= App File=<SDS.StxAppDef file path> | <SDS.StxAppDef file path> | "<SDS.StxAppDef file path>"

<DAT file path> ::= [<Dir Spec>\]<file name>.dat

<SDS file path> ::= [<Dir Spec>\]z<App Number>.sds.StxAppDef

<App Number> ::= <N><N><N>

<N> ::= 0|1|2|3|4|5|6|7|8|9

<Dir Spec> ::= <standard dos directory>

<Sep> ::= ;

<Scheme> ::= opl6:

Examples of valid URLs

Opl6:c:\oledb\data\sample.dat

opl6:DataFile="701000001001102700001 Y 5310 #0001 N ALL RIGHT M1003211947012345678998765412345123451234512345123451234512345123451234512345123451234512345123451234512345123451234512345123451234512345123451234512345123451234512345123451234512345123451234512345123451234512345123451234512345 ";App File=c:\oledb\data\z701.sdsStxAppDef;

opl6:DataFile="701000001001102700001 Y 5310 #0001 N ALL RIGHT M1003211947012345678998765412345123451234512345123451234512345123451234512345123451234512345123451234512345123451234512345123451234512345123451234512345123451234512345123451234512345123451234512345123451234512345123451234512345 "

opl6:Data File=c:\oledb\data\sample.dat; App File=c:\oledb\data\z701.sds.StxAppDef;

opl6:Data File=c:\oledb\data\sample.dat

opl6:Data File=sample.dat