The following examples illustrate ODBC connection specifications for Microsoft SQL
Server, Microsoft Access and Oracle. These depend on the ODBC driver that you are
using: you should refer to the ODBC driver documentation for details of required
connection parameter values. The data source in each case has been set up using the
ODBC Administrator.
Connecting to Microsoft SQL Server
my_spec << extdb_user.connect_template(
:dbtype, :odbc,
:connect_name, "zebra",
:server, :odbc,
:dbusername, "alan",
:dbpassword, "",
:data_source, "mic_sql",
:program_name, "swodbc",
:command, rope.new_with("swodbc.exe"),
:configuration, property_list.new_with( :max_cursors, 10 ),
:options, property_list.new_with( :sql_cursor_type,
:sql_cursor_static ))
This specification defines a connection called zebra for user alan.
Connecting to Microsoft Access
my_spec << extdb_user.connect_template(
:dbtype, :odbc,
:connect_name, "pelican",
:server, :odbc,
:dbusername, "",
:dbpassword, "",
:data_source, "mic_acc",
:program_name, "swodbc",
:command, rope.new_with("swodbc.exe"))
This specification defines a connection called pelican.
Connecting to Oracle via ODBC
my_spec << extdb_user.connect_template(
:dbtype, :odbc,
:connect_name, "puffin"
:server, :odbc,
:dbusername, "scott",
:dbpassword, "tiger",
:data_source, "int_ora",
:program_name, "swodbc",
:command, rope.new_with("swodbc.exe"))
This specification defines a connection called puffin for user scott.
Establishing the connection
When you have defined the connect specification, you can establish the connection
by creating a new extdb_user object of the appropriate subclass, using the
extdb_user method new().
extdb_user.new( connect_spec )
where connect_spec is the connect specification returned by the method
connect_template(). For example:
my_connection << extdb_user.new(my_spec)
You will see a message such as:
Configured External Database puffin an odbc_user
The connection is stored for the current session as an oracle_user, a subclass of
extdb_user determined by the dbtype parameter. Connections via ODBC are stored as
odbc_user (actually determined by the server parameter). The name of the object is
determined by the connect_name given in the specification.
Adding the external database connection to the database view
To add the external database connection to the database view, use the method
add_external_database() on database_view:
database_view.add_external_database( extdb )
where extdb is a connection to an external database (the new instance of
extdb_user). For example:
v << gis_program_manager.cached_dataset(:gis)
v.add_external_database(my_connection)
Any external tables named in the connect specification will be opened at this
stage.
If you open any tables that have no primary key, you will see a warning to this
effect. This is discussed further in Open Systems: Managing data in external
tables.
Once you have added the external tables to the view, you will be able to examine
the new extdb_collections using the standard mechanisms for ds_collections. You
will be able to open editors on the extdb_collections by making them visible using
the ACE Object Configuration dialog box.
Delayed connections
The following method is used for delayed connections (where the connect parameter
has value later). It does nothing if the connection is already established.
swdp_manager.connect_external_database( name )
where name is the connection name of the external database.
Aliases
You can define an alias to represent an external table within a Smallworld session.
Aliases are specified either at connection time in the connect specification, or
when tables are opened later on (see the following section). For example, if you
had a table named road you might shorten this to R. In the connect specification,
instead of specifying the tables parameter as:
rope.new_with(:road)
you would enter:
rope.new_with("road:R")
Thereafter, you could refer to the road table as R.
You might use table aliases to distinguish tables with different owners: if one
table was opened by two different users, the two versions in the Smallworld
application could be distinguished by aliases.
Opening additional external tables
Once a connection has been established, you can manually open an external database
table and add it to the database view (v):
my_connection.open_collection(:shop, v)
This will enable access to the external database table shop which may subsequently
be handled using the standard mechanisms available for datastore collections.
Closing the connection
To close the connection, you should remove the connection from each database view
to which it was added. For a database view, v, use:
my_connection.discard(v)
