Use the Database Connections to define a connection to any database. Database Connections are used for accessing tables external to your file-based datasets. These connections are used in the Dataset Properties Table Join window.

The Database Connections tool is a utility window called 'Java Data Source Administrator', short JDSA. Open the window by selecting the menu option Tools → Database Connections.

To make a connections from a Java application to a database, you require a driver. Many databases provide a Java class to access their database using the SQL language. These are the JDBC drivers.

A Driver is a Java Class allowing the application to make a connection to a JDBC Data Source (using the SQL-language). Depending on the Driver, a URL will provide the information the driver needs to establish the connection and allow the application to execute SQL-commands on a Data Source.

The Database Connections tool allows you to define JDBC drivers. Orbit GIS provides a driver to your ODBC databases as defined in your Windows system.

In Orbit GIS, we will give a name to each individual connection by using this JDSA (Java Data Source Administrator) tool for Database Connections.

Start Database Connections and go to the JDBC Drivers tab. This is what you'll see :

You notice the list of (pre)defined drivers. You can add a new driver, or remove, configure or test a selected driver.

Note: default, two driver specs are included: the ODBC bridge and the InstantDB driver. The ODBC bridge is standard Java but of course only useful on Windows platforms. The InstantDB driver specs are included as example, but you do require to purchase a license and install it if you wish to use the InstantDB driver � if not, use these specs as example and remove it when it bothers you.

Select a Driver and hit the Configuration button. This will open the following dialog :

• Name
  A reference Name for the Driver, to be used in the JDBC Data Sources and Connector dialogs.
• Description
  An optional description of this driver.
• Class
  The exact name of the Java Class implementing a JDBC driver. This class must be accessible by Java, and thus included in the classpath : it is required for the JDSA, but also for the applications using the JDSA.

Type in the proper values, and hit Test. The result should be :

If not, check your driver Class name, or check your classpath. In most cases, the given Java Class is not accessible for your JRE (Java Runtime Engine) because it has not been included in the classpath specification. If you're not familiar to this issue, consult your IT-manager or java.sun.com for details about JDBC and classpath behaviour.

From the JDSA main window, you can also perform the same test.

To add a new driver, consider the same remarks as above. Hit the 'Add' button, the same 'Drivers Configuration' window appears. Enter the values in the fields, and hit Test.

The JDBC Data Source is a connection definition, using a JDBC Driver, and providing all information to an application to connect to the given database.

The URL formed (automatically) by the given parameters allow the applications to connect and execute commands. The information you will have to provide is only the name of the JDBC Data Source which you enter here.

Go to the JDBC Data Sources tab. This is what you might see :

You notice the list of JDBC Data Sources. You can add a new one, or remove, configure or test a selected Data Source.

Select a Data Source and hit the Configuration button. This will open the following dialog:

ODBC Example :

MySQL Example :

To make a connection work, be sure to supply at least the following parameters :

• Name
  The user name of the JDBC Data Source. This is what you will use in Orbit GIS, and it must be unique.
• Driver
  The JDBC Driver to be used.
• User
  The name of the user to access the database with.
• Password
  The password for that user.
• URL
  The connection string that will allow the application to connect to the database. The format of this URL is driver dependant, and you probably need to consult the driver documentation to get the right syntax.

Optionally, you can enter the following parameter :

• Description
  An optional description of the Data Source.

Depending on the selected driver, you can enter information in for following parameters.

• DBMS
  The type of database server system (RDBMS).
• Database
  The name of the database.
• Host
  The computer where the database server resides.
• Port
  The port to which tuhe JDBC driver connects to the database server host.

The URL can be compiled automatically from the input fields. To do so, press the downwards pointing arrow button to the right of the URL-field. Use the upwards pointing arrow button to extract a URL into parameter values.

After entering all information, hit Test. The result should be :

If not, check your parameter values and be sure you've assembled the URL properly. IF you do not succeed in performing a satisfactory test, consult your IT-manager about proper values for the parameters.

From the JDSA main window, you can perform the same test.

ODBC Data Sources have fewer parameters than available in this setup. When choosing 'ODBC' as driver, the DBMS, Host and Port fields will be dimmed, and need not be used. Enter the ODBC name in the Database field as it is defined in your Windows system.

You can use the ODBC Data Sources for many desktop sources, such as an MSAccess file, a DBF file etc.

Note that when using external tables in Orbit GIS, i.e. joining a database table to a dataset, the JDSA name as specified in this tool is used in the ORD file to store the join definition. When moving the dataset to other desktops or users, beware to have the same JDSA connection defined on that computer in order to make the join work.