DataSource class

Background

ODBC (Open Database Connectivity) provides a standard mechanism for using databases independent of programming languages, database systems, and operating systems.

The ODBC specification offers a procedural API for using SQL queries to access data. Both Windows and Mac OS X offer a built-in ODBC implementation, and OBDC drivers exist for a large variety of database systems and data sources including spreadsheets, text and XML files.

System requirements

The system administrator of the computer hosting Switch must correctly install and configure the appropriate ODBC drivers and the system's ODBC driver manager.

Overview

The DataSource class encapsulates a connection to a particular ODBC data source. A script can be connected to different data sources at the same time. Within the limited capabilities of the Database module, it is not meaningful to have multiple connections to the same data source.

The Statement class allows executing a SQL statement on a data source, and allows retrieving the results.

Constructing

DataSource( ) : DataSource

Constructs a new unconnected data source.

Connecting

connect(data-source-name : String, user : String, password : String, query-codec : String, data-codec : String) : Boolean

Attempts to connect to the specified data source with the specified user and password. If the user and password are empty or null, no user authentication is performed.

Returns true if the connection succeeds, false otherwise (in which case an error message is logged).

The optional codec arguments specify the text encoding used by the connection to communicate with the database and retrieve data. If an argument is missing or null, UTF-16 is used as the default. For more information see separate section on text encoding issues.

disconnect( )

Disconnects the data source if it was connected; otherwise does nothing. Disconnecting a data source invalidates all associated Statement instances.

A disconnected data source can be reconnected by calling connect().

Switch automatically disconnects a data source when exiting the entry point in which it was constructed .Still, it is good programming style to explicitly disconnect all data sources.

isConnected( ) : Boolean

Returns true if the data source is currently connected, false otherwise.

useConnection(data-source-name : String) : Boolean

Attempts to connect to the database with the parameters specified in "data-source-name" Switch data source (in ODBC data sources section of Preferences). Data source name, user, password and codecs information will be taken from Switch's data source settings.

Returns true if the connection succeeds, false otherwise (in which case an error message is logged).