UnixODBC.pm Installation


Contents

  - Installing UnixODBC.pm
  - Testing UnixODBC.pm
  - Configuring the bridge server
  - Installing the Web data manager
  - Example scripts 


- Installing UnixODBC.pm

  UnixODBC.pm links against the unixODBC run time libraries,
  from http://www.easysoft.com, so they need to be installed 
  first.  This version of UnixODBC.pm works with version 2.2.0
  and later of the libraries.
  
  Then, to build and install the Perl modules, use the following
  commands:

  $ cd UnixODBC-<version>
  $ perl Makefile.PL
  $ make
  $ su
  # make install

  To run the test script test.pl, you need to have installed
  the data in the dbms subdirectory.  Refer to "Testing
  UnixODBC.pm," below.  You'll also need to configure the
  ODBC driver for your DBMS and a data source using either
  odbcinst or ODBCConfig.

  UnixODBC.pm and the client and server scripts were written with 
  Perl installed in /usr/local.  If you try to run a script and 
  receive an error message like:

  sh: ./client: no such file or directory

  It means the script can't find the Perl interpreter.  Either
  change the path on the first line of the script to the location
  of the perl binary (the output of "which perl"), or create a 
  symlink /usr/local/bin/perl to the actual perl program.


- Testing UnixODBC.pm

  UnixODBC.pm is known to work with MySQL and PostgreSQL on Linux
  and Solaris systems.

  The test.pl script excercises the unixODBC API.  For most of the
  tests to complete successfully, you need to have installed the
  test data in the dbms/ subdirectory, and to have configured a DSN
  for the test data.  Refer to the file dbms/README for notes about
  MySQL and PostGreSQL and PostgreSQL DBMS's.


- Configuring the bridge server.

  To use the bridge server, you'll need to have installed on each
  host the same versions of Net::Daemon, Storable, PlRPC, Log::Agent 
  (if you want to write CGI scripts), and the modules that they 
  require. This version of UnixODBC.pm works with the following 
  packages:

  - Net-Daemon-0.35
  - Storable-1.0.14
  - PlRPC-0.2015
  - Log-Agent-0.301

  You'll also need to install Sys::Syslog if it isn't included
  with Perl, and, for some of the client scripts in the eg and
  bridge subdirectories, DBIx-HTMLTable to print query results
  as HTML tables.

  The bridge server runs as user nobody and uses port 9999.  To
  change the configuration, edit /etc/odbcbridge.conf after
  installation.  The complete specification of RPC server settings
  is in the RPC::PlServer(3) man page.  Example server and client
  scripts are in the bridge/ directory.  For further exampls of
  writing Perl RPC clients and servers, refer to the man pages for
  RPC::PlServer and RPC::PlClient, and the ProxyServer.pm module in
  the Perl DBI bundle.

  Install UnixODBC.pm.  Create the directories /usr/local/etc,
  /usr/local/var, and /usr/local/sbin if they don't exist 
  already, Then,

  $ su
  # mkdir /usr/local/var/odbcbridge
  # chown nobody /usr/local/var/odbcbridge
  # cp bridge/odbcbridge.conf /usr/local/etc
  # cp bridge/server /usr/local/sbin
  # chmod +x /usr/local/sbin/server

  If everything is installed correctly, you should be able
  to start the server by typing:

  # /usr/local/sbin/server &

  If you want to start the server when the system starts, install
  the odbcserver script in the same directory as the other local
  startup scripts - /usr/local/etc/init.d is a good location.  
  Change the permissions on the script so that it is executable.
  Edit LD_LIBRARY_PATH so it contains the directories of all 
  the libraries ODBC needs to find.  Refer to the system
  administration documents for information about how to start 
  daemons during system initialization.


- Installing the Web data manager

  The Web data manager was written for Apache with mod_perl.
  It requires that the server have server-side includes 
  configured.  

  First, edit the %peers hashes in datamanager/datasources.cgi
  and datamanager/tables.cgi so they contain the hostname
  and login::password of each bridge server on the network.
  Substitute the actual host names or IP addresses for
  hostname1, hostname2, and so forth, and the logins for
  each host. Enter one key-value pair for each host on
  the network which has a UnixODBC.pm server.  The %peers 
  hashes in datasources.cgi and tables.cgi must be identical.

  These instructions have /usr/local/apache/htdocs as the Apache
  document directory and /usr/local/apache/cgi-bin as the CGI
  script directory.  Make the necessary adjustments if your Apache 
  directory configuration is different than the one used here.

  Then install the files using these commands.

  $ su
  # mkdir /usr/local/apache/htdocs/datamanager
  # cp datamanager/*.html /usr/local/apache/htdocs/datamanager
  # cp datamanager/*.shtml /usr/local/apache/htdocs/datamanager
  # cp datamanager/*.png /usr/local/apache/htdocs/datamanager
  # cp datamanager/*.cgi /usr/local/apache/cgi-bin
  # cd /usr/local/apache/cgi-bin
  # chmod +x tables.cgi
  # chmod +x datasources.cgi

  If the Apache server does not have server-side includes, enabled,
  add the following lines to httpd.conf:

  <Directory "/usr/local/apache/htdocs/datamanager">
      Options FollowSymLinks Includes
  </Directory>
  AddType text/html .shtml
  AddHandler server-parsed .shtml

  Then restart the server:

  # /usr/local/apache/bin/apachectl restart
  

- Example scripts

  The eg/ directory contains example ODBC clients.  For the scripts
  that require logging in to a data source, edit $DSN, $UserName,
  and $PassWord at the beginning of the script.

  alltypes - Print a list of the SQL data types for a DSN.
  apifuncs - Return a list of which ODBC API functions a
             DSN driver implements.
  colattributes - Print a list of column attributes for a title.
  connectinfo - List connection attributes.
  datasources - Print a list of DSN's.
  driverinfo - List drivers and their descriptions.

  The bridge/ directory contains example clients for remote DSN's.

  sampleclient - A sample script for testing ODBC function calls
  using the peer-to-peer bridge.

  remotedsn - List the DSN's of a remote system.  Edit the 
  'peeraddr' parameter of RPC::PlClient -> new with the name or 
  IP address of the remote host.

  remotetables - List the tables of a remote DSN.  Edit the 
  'peeraddr' parameter of RPC::PlClient -> new with the name or 
  IP address of the remote host, and $DSN, $UserName, and 
  $PassWord to log into the remote system.



