ODBCMan

Version 0.71 (22-Jun-2007)

ODBCMan is public domain
This program may be freely distributed for no more than the cost of the media
on which it is distributed. It remains at all times  Copyright 1997 to 2004
R. F. Windley & The Really Small Software Company.

Disclaimer:
-----------
This software is supplied as is. No responsibility will be taken by the
author for any loss of data through the use or misuse of this application.

Introduction
------------
ODBCMan allows the installation and configuration of ODBC drivers and
Datasources. What are SQL and ODBC? If these terms mean nothing to you then
ODBCMan probably won't be of much use, but see below for an explanation
anyway.

What is ODBC?
-------------
ODBC stands for Open DataBase Connectivity. Open Database Connectivity is a
widely accepted application programming interface (API) for database access.
It is based on the Call-Level Interface (CLI) specifications from X/Open and
ISO/IEC for database APIs and uses Structured Query Language (SQL) as its
database access language.

What is SQL?
------------
SQL is an acronym for Structured Query Language. It is a database query
language that was adopted as an industry standard in 1986.

What is a datasource?
---------------------
A Datasource is definition of the location and login details, as well as
other options, which enable an ODBC compliant application to gain access to a
remote or local database.

Getting started
---------------

Installation
------------
ODBCMan can be installed and used in two different ways:

Stand alone
Simply drag the !ODBCMan icon to where you want it to be on your hard disc.

From within Configure
ODBCMan will integrate into the RISC OS 4 and above Configure system. To
install take the following steps:

For RISC OS 4.0x:
+ Manually copy !ODBCMan into !Boot.RO400Hook.Res.Configure

For RISC OS 4.2x and above:
+ Open the Configure window by double clicking !Boot or choosing Choices...
from the Task manager menu
+ Drag !ODBCMan to the Configure window and it will install. A new ODBC
option will appear.

Loading ODBCMan
---------------
ODBCMan can be loaded in two different ways:

Stand alone
For stand alone operation ODBCMan is loaded by double clicking on the ODBCMan
icon in the filer display. Once loaded an the ODBCMan icon will appear on the
iconbar in the standard way.

Configure
If ODBCMan has been installed in Configure then double click !Boot or choose
Choices... from the Task menu.

This will display the Configure window with an ODBC option. Click this to
launch ODBCMan.

Showing the available datasource types
--------------------------------------
If ODBCMan has been run from Configure then this window will already be
displayed. If not, clicking Select on the iconbar icon will display a window
which shows the different types of Datasources that can be configured and a
section that enables database drivers to be installed and removed.

Datasource types
----------------
There are two types of Datasource that can be configured.

System
System Datasources are available to all users of the local computer. They can
be configure by all users.

User
User Datasources are only available to the user that is currently logged in
and can only be configured by the current user.

This only really makes a difference to users of RISC OS Select which provides
the ability to have different user profiles on a single computer. System and
User Datasources are both configured in exactly the same way. The only
difference is that System Datasources are shown as blue icons and User
Datasources are grey.

Creating a new Datasource
-------------------------
Double clicking on the System or User icons from the Datasources window will
display the currently defined datasources.

To create a new Datasource choose New... from the main menu or press Control
N. This will display the Datasource window:

Name
The name of the Datasource.

Description
A brief description of the database the datasource connects to.

Driver
The driver that will be used to access the underlying database. Before
setting up a Datasource you must have some idea of the type of database that
you will be connecting to. Some different databases and the drivers they use
are shown below:

Database        Description                                       Driver
--------        -----------                                       ------
PostgreSQL      Commercial quality database found on Linux        psqlODBC
                and Windows
mySQL           Popular database used for Web sites               myODBC
SQL Server      Microsoft's enterprise database                   FreeTDS
SQLite          Small embeddable database that runs locally       sqlite

Unless there is a good reason it is always best to use the latest available
version of the relevant driver.

Server
The server on which the database resides. If the list does not contain the
required server name then a new name can be typed in.

Database
The name of the database on the specified server to connect to.

Username
The name of the user to connect to the database as. This should have been
allocated by your system or database administrator. If left blank a username
can be specified when connecting to the Datasource.

Password
The password for the specified user. If this is left blank it can be entered
when connecting to the datasource. This is the recommended setting to
maintain some level of security.

Once the details have been entered clicking Apply will create the datasource
whilst clicking Cancel will abort the operation.

Editing a Datasource
--------------------
Double clicking on a datasource will display a window that allows the
datasource details to be edited.

Name
The name of the Datasource.

Description
A brief description of the database the datasource connects to.

Driver
The driver that will be used to access the underlying database. Before
setting up a Datasource you must have some idea of the type of database that
you will be connecting to. Some different databases and the drivers they use
are shown below:

Database        Description                                       Driver
--------        -----------                                       ------
PostgreSQL      Commercial quality database found on Linux        psqlODBC
                and Windows
mySQL           Popular database used for Web sites               myODBC
SQL Server      Microsoft's enterprise database                   FreeTDS
SQLite          Small embeddable database that runs locally       sqlite

Unless there is a good reason it is always best to use the latest available
version of the relevant driver.

Server
The server on which the database resides. If the list does not contain the
required server name then a new name can be typed in.

Database
The name of the database on the specified server to connect to.

Username
The name of the user to connect to the database as. This should have been
allocated by your system or database administrator. If left blank a username
can be specified when connecting to the Datasource.

Password
The password for the specified user. If this is left blank it can be entered
when connecting to the datasource. This is the recommended setting to
maintain some level of security.

Once the details have been entered clicking Apply will save the Datasource
whilst clicking Cancel will abort the operation.

Miscellaneous
-------------
Clicking the Miscellaneous button will display a window which allows other
settings for the Datasource to be configured. The list of available settings
will depend on the database driver selected.

Creating tag settings
---------------------
Click on the Add... button to add a new tag setting. This displays a window
that allows the tag type to be selected and a value assigned to it. The list
of available tag types for a driver is installed when the driver is
installed. The tag type is selected from the Name menu and suitable value
entered in the Value field.

Clicking the Apply button will store the new tag, clicking Cancel will close
the window without storing the new details.

Editing a tag value
-------------------
To edit the value of a tag select the tags to be amended and click on the
Edit... button. Different tag types have slightly different windows to allow
the value to be edited.

Clicking Apply once the value has been amended will save it, clicking Cancel
will close the window without saving the change.

Deleting a tag value
--------------------
To delete a tag value, select the tags to be deleted and click the Delete
button.

Managing Drivers
----------------
Double clicking on the Drivers icon from the Datasources window will display
the drivers that are installed on your system.

There are no configuration settings for drivers, they can either be installed
or uninstalled.

Installing a driver
-------------------
To install a driver simply drag the supplied driver directory to the Drivers
window. It will be added to the list of available drivers and can then be
used in the configuration of a System datasource.

Uninstalling a driver
---------------------
To uninstall a driver select the driver to be uninstalled and choose Delete
from the Driver sub menu.

The main menu
-------------
The main menu is displayed by clicking Menu over a window.

The following options are available:

Display
Moving the pointer over this option shows the Display menu. This allows the
size and level of detail for items to be set.

Large icons
Displays the items using large icons.

Small icons
Displays the items using small icons.

Full info
Displays the items using small icons and item information.

Datasource/Driver
This provides a single item. Choosing this item will delete the datasource or
driver. A check will be made first to ensure that the datasource has no
dependencies.

Select all
Choosing this will cause all items to be selected. This can also be achieved
by pressing Control A.

Clear selection
Choosing this will cause all selected items to be unselected. This can also
be achieved by pressing Control Z.

New
Choosing this item allows a new datasource to be created. See the sections on
creating new datasources for more details.

Help
This will display the help supplied with the application.

The iconbar menu
----------------
Note that this menu will not be available if ODBCMan has been run from
Configure.

Clicking Menu over the ODBCMan icon on the iconbar will display this menu.
The following items are available:

Info
Moving the mouse pointer over this item displays the About this program
window which displays version information about ODBCMan.

Help
This will display the help supplied with the application.

Quit
Choosing this item will cause ODBCMan to exit.