DataSource Object - Stonefield Query SDK

A class in an object-oriented language serves as a template: it defines a certain interface and behavior. The object created when you instantiate the class can be thought of as the physical implementation of the class.

Stonefield Query treats databases in a similar manner. A logical database is similar to a class: it defines what tables belong to the database and the structure of those tables. A physical database is the actual database on disk. The logical database doesn't concern itself with location or type of access; those are issues for the physical database. For example, you may have both SQL Server and Access versions of the same logical database; the Northwind sample database that comes with both of these is one such set of physical databases that have the same logical database structure.

A Database object in the Stonefield Query data dictionary contains information about a logical database. A DataSource object define the connection information for a physical instance of the logical database. It's also responsible for communicating with the database engine: connecting to it, retrieving the necessary data for a report, disconnecting from it, and so on.

Because different database engines have different properties that determine how to access a specific database, there are different versions of DataSource objects in Stonefield Query. The available versions are:

VFP: a Visual FoxPro data source.
ODBC: an ODBC data source.
ADO: an ADO/OLE DB data source.
WebService: a data source accessed via a Web service.
SQLXML: a SQL Server data source accessed via HTTP. See the SQL Server Books Online or the MSDN Web site (http://msdn.microsoft.com) for information on SQLXML.
Text: comma-delimited text files. The name of the file must be in the Custom Properties property of each table in the data dictionary and the path must be in the Database property of the DataSource object.

When you add a DataSource object to the DataSources collection, you must pass the type to the AddItem method.

Each type of DataSource object has its own set of properties which define how to connect to the data source. All also share a common set of properties.

Common Properties

All properties are read-write except Type, which is assigned when you create the datasource object.

Name	Data Type	Description
Database	String	The name of the physical database this data source connects to. In the case of file-based database engines such as Visual FoxPro and Access, this must include the path to the database. In the case of text files, this must contain the path for the files.
DataSource	String	The name of the DataSource object.
Description	String	The descriptive name for the data source (the name the user sees in the Open Database dialog).
Type	String	The type of data source: "ODBC," "ADO," "VFP," "WebService," "SQLXML," or "Text".
UserDefined	String	This property can contain anything you want to place in it.

ODBC Properties

The properties of an ODBC DataSource object define how to connect to the data source. There are three ways you can specify how to connect:

Set the DSN property to the name of the DSN you want to connect to. You may also have to set the UserName and Password properties if those are required.
Set the ConnectionString property to the connection string to use. This is sometimes called a "DSN-less" connection, one that doesn't require a DSN on the user's system.
Set the Driver, Server, Database, UserName, and Password properties to the necessary values as another way of using a DSN-less connection.

Name	Data Type	Description
ConnectionFailureMessage	Integer	The text of any error that occurs when connecting to the database.
ConnectionHandle	Integer	The ODBC connection handle for the connection.
ConnectionString	String	The connection string to use to connect to the database.
Driver	String	The name of the ODBC driver to use. This must be the exact name as displayed in the ODBC Administrator dialog.
DSN	String	A user or system data source name (DSN) defined on the user's system that connects to the data source.
OtherConnectInfo	String	Additional information to pass to the ODBC driver. For example, for protected Microsoft Access databases, you have to specify "SystemDb=path for MDW file."
Password	String	The password to access the database.
Server	String	The server the database is located on.
Shared	Boolean	True if the connection is shared with another data source (read only).
Specifier	String	The name for the attribute specifying the database, such as "database," "datasource," "catalog," etc.
UserName	String	The user name to access the database.

ADO Properties

The properties of an ADO DataSource object define how to connect to the data source and provide a reference to the ADO Connection object.

Name	Data Type	Description
CommandTimeout	Numeric	Specifies the command timeout setting for the ADO Connection object. Set this to a higher value to avoid timeout issues with queries on large tables.
Connection	Object	A reference to the ADO Connection object used to connect to the database.
ConnectionString	String	The connection string to connect to the database using an ADO Connection object.
ConnectionTimeout	Numeric	Specifies the connection timeout setting for the ADO Connection object.

Web Service Properties

The properties of a Web Service DataSource object define where the Web service is located and what method to call.

Name	Data Type	Description
Method	String	The method of the Web service to call. If desired, specify "<<select>>" as a placeholder to tell Stonefield Query to insert the SQL statement it creates for a particular table. See the GetDataSources help topic for an example.
SOAPClient	Object	A reference to the SOAP client object. One use for this object is to set properties of the SOAP client using the ConnectorProperty member. For example: DataSource.SOAPClient.ConnectorProperty('Timeout') = 60000 Note this object only exists once the connection has been made to the Web service, so call the datasource object's Connect method manually if you want to access this object before the connection is normally made (such as in a GetDataSources script).
WSDLURL	String	The URL of the WSDL file for the Web service.

SQLXML Properties

Name	Data Type	Description
BaseURL	String	The base URL queries are sent to.
UseTemplate	Boolean	True if queries are sent to a template; False (the default) to include the SQL statement in the URL.

Methods