ANNOUNCE: UnixODBC 0.31
From: Robert Kiesling (rkies_at_cpan.org)
Date: 04/11/04
- Next message: Matthew Persico: "Request for Comments - Finance::Calc::Performance"
- Previous message: jessica_at_Vote.Nader.2004: "Message To America's Students: The War, The Draft, Your Future"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Date: Sat, 10 Apr 2004 23:45:02 GMT
Description
-----------
UnixODBC provides a toolkit for writing Perl ODBC clients. It
implements a functional interface for a subset of the API implemented
by unixODBC, http://www.unixodbc.org/, and an extended,
object-oriented API that ODBC connectivity for network hosts.
The package also includes library modules that manage DSN templates
and configure driver properties, and write RSS output from ODBC
queries.
The client programs in the package provide text-mode, Perl/Tk and
mod_cgi Web User Interfaces, as well as bridge services. The clients
can perform data management tasks on local and network hosts.
The README file, below, describes the libraries, client programs, and
system requirements.
Download
--------
You can download UnixODBC.pm from the following sites:
http://sourceforge.net/projects/unixodbc-pm/.
ftp://ftp.cpan.org/pub/CPAN/authors/id/R/RK/RKIES/.
UnixODBC.pm 0.31 README
-----------------------
UnixODBC.pm Installation
- Contents
- Overview
- Ins
talling UnixODBC.pm
- Testing UnixODBC.pm
- Installing and Configuring the Bridge Server
- Installing the GUI Data Manager, Tkdm
- Installing the Web data manager
- Text-mode Programs
- Troubleshooting
- Copyright
- Overview
UnixODBC.pm provides Perl programs with a subset of the X/Open
ODBC Application Programming Interface implemented by unixODBC
from http://www.easysoft.com/. UnixODBC.pm also provides an API
that implements ODBC function calls for TCP/IP network host
systems. Refer to the section, "Installing and Configuring the
Bridge Server," below.
The UnixODBC.pm Text-mode programs and Web and GUI data managers
can perform ODBC queries on local and networked systems. Refer
to the sections, Text-mode Programs," "Installing the GUI Data
Manager, Tkdm," and, "Installing the Web Data Manager," below,
and the file, "INSTALL," in the tkdm/ subdirectory.
- Installing UnixODBC.pm
The unixODBC libraries, from http://www.unixodbc.org/, and an
ODBC driver for your DBMS server, should be installed and
working before installing UnixODBC.pm. UnixODBC.pm has been
tested with unixODBC versions 2.2.0 - 2.2.6. UnixODBC.pm also
requires the unixODBC C-language include files from unixODBC.
They should have been installed in /usr/local/include when you
install unixODBC. If the header files aren't there, you can
find them in the include/ subdirectory of the unixODBC package.
The dbms/README describes DBMS and driver installation for
MySQL and PostgreSQL. It also describes how to handle
PostgreSQL exception signals that can cause Perl programs to
terminate.
UnixODBC.pm itself requires the following Perl libraries:
- Net-Daemon-0.35 - 0.37
- PlRPC-0.2015 - 0.2017
- Tk800.021 - 0.23
IMPORTANT - Each host must have identical versions of Perl,
Net::Daemon, PlRPC, and the modules they require.
Tkdm also requires Perl/Tk.
Versions of Perl prior to 5.6.0 might not provide Sys::Syslog.pm
and Storable.pm. In that case these modules must be installed also.
To build and install the modules, use the following commands:
$ cd UnixODBC-<version>
$ perl Makefile.PL
$ su
# make install
When initially installing UnixODBC.pm, the installation warns
that UnixODBC.pm is not installed. If the installation warns
that other library modules are not installed, you should install
them before proceeding.
To run the test script dbms/test.pl, you need to have
installed the data in the dbms subdirectory. Refer to,
"Testing UnixODBC.pm," below. The ODBC driver needs to be
configured for your DBMS and a data source using either
odbcinst or ODBCConfig.
Standard Disclaimer - UnixODBC.pm and the client and server
scripts were written with Perl installed in /usr/bin. If Perl
scripts print 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/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.
Running, "make test," makes sure that the library modules load
correctly.
The dbms/test.pl script excercises the unixODBC API more
thoroughly. For the script to complete, the DBMS must have
installed the test data in the dbms/ subdirectory, and you must
have configured a DSN for the test data. Refer to the file
dbms/README for notes about MySQL and PostgreSQL DBMS's.
Running test.pl is likely to result in at least a few errors.
The script is designed to test the subset of ODBC API functions
that UnixODBC.pm implements as exhaustively as possible, and as
many different ODBC DBMS drivers as possible (currently the MyODBC
and Easysoft PostgreSQL drivers).
- Installing and Configuring the Bridge Server
IMPORTANT (Again) - The versions of Perl, Net::Daemon, Storable,
and PlRPC on each host MUST be the identical. Net::Daemon,
in particular, checks for version information when authenticating,
and PlRPC generates protocol errors when communicating with
different
versions. Storable also relies having the same version of itself and
Perl on local and remote systems.
UnixODBC and the supporting libraries are not thread-safe (yet).
You may encounter thread exceptions on some systems with Perl
5.8.0 configured with ithreads.
Net::Daemon errors are commonly recorded in the syslog.
Although you can configure the log messages, check the syslog
first. Refer to, "Troubleshooting," below.
The bridge server runs as user nobody and uses port 9999. To
change the configuration, edit /usr/local/etc/odbcbridge.conf
after installation. The RPC::PlServer(3) man page describes the
settings Example server and client scripts are in the bridge/
subdirectory. For further examples 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 as describe above. This step also installs
/usr/local/etc/odbclogins which is necessary for the Web data
manager. You can add host and login information as described below.
If the installation proceeded correctly, the core libraries and
bridge server daemon should be installed in the proper directories,
and you should be able to start and stop the daemon by typing:
# /usr/local/etc/init.d/unixodbc start
# /usr/local/etc/init.d/unixodbc stop
Manual Installation - Create the directories /usr/local/etc,
/usr/local/var, and /usr/local/sbin if they don't exist. Then,
$ su
# mkdir /usr/local/var/odbcbridge
# chown nobody /usr/local/var/odbcbridge
# cp bridge/odbcbridge.conf /usr/local/etc
# cp bridge/odbclogins /usr/local/etc
# chmod 0600 /usr/local/etc/odbclogins
# chown nobody /usr/local/etc/odbclogins
# mkdir /usr/local/etc/init.d
# cp bridge/unixodbc /usr/local/etc/init.d
# cp bridge/odbcbridge /usr/local/sbin
# chmod +x /usr/local/sbin/odbcbridge
If everything is installed correctly, you should be able
to start and stop the server by typing:
# /usr/local/etc/init.d/unixodbc start
# /usr/local/etc/init.d/unixodbc stop
To start the server when the system starts, install the unixodbc
script in the same directory as the other local startup scripts,
refer to the system administration documents for information
about how to start daemons during system initialization.
- Installing the GUI Data Manager, Tkdm
The GUI data manager tkdm is installed when UnixODBC.pm is
installed. Refer to the man page ("man tkdm") and the
tkdm/README file for configuration instructions.
- Installing the Web data manager
The Web data manager works with the Web servers: Apache 1.3 and
2.0, and the Web browsers: Mozilla 1.0, Netscape 4.75, and Internet
Explorer 3.03.
The document describes a configuration that uses
/usr/local/apache/htdocs as the Apache DocumentRoot directory and
/usr/local/apache/cgi-bin as the CGI script directory. Make the
necessary adjustments for the system's Apache configuration.
APACHE CONFIGURATION - Httpd.conf must be configured to load
mod_perl,
mod_env, and mod_ssi, and use server-side includes. On some systems,
LD_LIBRARY_PATH in the server's environment must be able to locate
all
of the libraries that the DBMS server, ODBC, and Perl require.
The data manager is configured to be installed in the,
"datamanager,"
subdirectory of, "htdocs," or the directory named in the httpd.conf
DocumentRoot directive. If installing in a different subdirectory,
modify the directives shown below for httpd.conf accordingly, and
change the value of $folder in the CGI script, datamanager.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
To add the path for all of the libraries to the server's
environment, add a line like this to httpd.conf:
SetEnv LD_LIBRARY_PATH
/usr/lib:/usr/local/lib:/usr/local/mysql/lib/mysql
The specific names of the directories depend on the system's
Apache and DBMS server configuration.
Then restart the Apache:
# /usr/local/apache/bin/apachectl restart
Then install the files.
$ 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/*.gif /usr/local/apache/icons
# cp datamanger/odbclogins /usr/local/etc
# cp datamanager/*.cgi /usr/local/apache/cgi-bin
# cd /usr/local/apache/cgi-bin
# chmod +x tables.cgi datamanager.cgi odbclogin.cgi
Edit the path to the perl interpreter on the
first line of tables,cgi, datamanager.cgi,
odbclogin.cgi to the path of the actual perl
interpreter. The path should be either
/usr/local/bin/perl, /usr/bin/perl, or the output
of the shell command, "which perl."
# cd /usr/local/etc
# chmod 0600 odbclogins
# chown nobody odbclogins # Use the UID/GID of httpd.conf's,
# chgrp nobody odbclogins # "User," and, "Group," directives.
Edit each line of the file /usr/local/etc/odbclogins for
the login of each system that has a bridge server installed.
The format of each line is:
host::user::password
The user names and passwords need not be the same as those
used to log in to the DSN's. They simply need to allow the
clients (either the CGI scripts or the command-line scripts)
to log in to the bridge server on the remote system. They
need to be actual users with passwords, with their own
entries in /etc/passwd.
IMPORTANT - /usr/local/etc/odbclogins contains login data
for remote systems. It is important to change the permissions
and ownership so that it can be read by the httpd server
processes ONLY (i.e., the CGI scripts). Apache servers often run
as user nobody, group nobody. The ownership of
/usr/local/etc/odbclogins should be the values of the User and
Group http.conf directives.
Also, do a, "chmod 0600 /usr/local/etc/odbclogins," to remove,
"group," and, "other," permissions from the file. If this isn't
secure enough, you can also create a separate UID (www, for
example) and make sure to change the User directive value in
httpd.conf.
Standard Disclaimer (Again) - The CGI scripts are written to
find Perl as /usr/bin/perl. If that isn't the location of the
Perl interpreter, then either edit the first line of the scripts
to reflect the actual location of the perl binary (the output of,
"which perl") or make /usr/bin/perl symlink to the interpreter.
The ODBC logo is modified from the XPM in the unixODBC-2.2.2
Data Manager source tree.
CGI script errors are recorded in the Apache error_log, even if
they don't appear in the browser window. If the scripts seem
to work right, but the data manager can't connect to data sources,
look for the bridge error messages in the syslog, and consult the
section, "Troubleshooting," below.
- Text-mode Programs
The eg/ subdirectory contains example ODBC clients for
locally hosted ODBC servers. The scripts that log into a
data source require the DSN, DBMS login name and DBMS
password as command line arguments. The client scripts in
the bridge/ subdirectory, for networked ODBC servers,
additionally require the name or IP address of the host
system.
Documentation for the client scripts are in the man pages.
The command line option, "--help," prints a brief help
message.
# alltypes --help
Clients for local host ODBC queries.
- alltypes List the SQL data types for a DSN.
- apifuncs ODBC API functions that a driver implements.
- colattributes Column attributes for a title.
- connectinfo Connection attributes.
- datasources DSN's on the local system.
- driverinfo Drivers on the local system.
- rssoutput Output result set as RSS RDF file.
- gutenberg.cgi CGI query with Project Gutenberg data in dbms/.
Clients for remote DSN queries are in the bridge/ subdirectory.
sampleclient and sampleclient2 - Testing ODBC function
calls using the peer to peer bridge.
- remotedsn List the DSN's of a remote system.
- remotetables List the tables of a remote DSN.
- Troubleshooting
- Perl error messages similar to,
<programname>: not found
indicate that the script cannot locate the Perl interpreter.
The programs have this automatically configured during
installation. The CGI scripts assume that the Perl binary
is /usr/bin/perl. If it isn't, you can make a symlink
from the actual Perl interpreter, or edit the first line in
the scripts to the path of the Perl binary.
- If a program seems to take forever to start, it generally
indicates that the bridge server can't make a connection
to another machine on a network, and usually indicates that
a network system is not accessible.
- "Failed to make first connection...," to a DSN generally
means that either the remote bridge server is not running,
the client was not able to log in, or the perl and library
versions are different on each system. Check the installation
and configuration of the bridge server (above and, "man
odbcbridge"), and make sure that you can connect to the remote
DSN with a text-mode client like remotedsn ("man remotedsn")
or remotetables ("man remotetables").
If the data manager can connect to local data sources but not
remote data sources, the problem is likely in the RPC network
layer. Ensure that the versions of Perl, Net::Daemon,
Storable, and RPC::PlServer are identical on local and remote
systems. Try connecting with one of the text mode clients
(remotedsn, remotetables) to help diagnose the problem.
The servers at all levels (DBMS server, HTTP server, bridge
server) perform caching on the local and remote machines. It
might be necessary to restart both systems, especially if you
change the configuration of one or more systems, or upgrade
the software. Remember to re-start the bridge server if you
change the system configuration.
- If you receive, "Unexpected EOF while waiting for server
reply," errors while logging into a DSN, try restarting the
bridge server from a terminal session.
- "Out of memory during large request," and "Maximum
message size exceeded," errors occur when the size of a
result set is greater than 64 kb. This is because the
bridge server uses integers as packet indexes. Try to
narrow the SQL query to produce a smaller result set.
- Error and/or status messages do not show up in the
system logs. The clients, especially the Web data manager,
can record activity by the UnixODBC bridge server, the ODBC
Driver Manager, and the HTTP server in up to three (that's
right, three) different system logs.
1. UnixODBC bridge servers and clients use the syslog,
"daemon," facility to record activity. If daemon logging is
not enabled (i.e., there is no, "daemon.log," file), typically
add a line like this to /etc/syslogd.conf, for example (on
Linux systems):
daemon.* /var/log/daemon.log
Refer to the man pages for syslogd, syslogd.conf, and/or
syslog.conf depending on the Unix version. If the 'debug' option
in /usr/local/etc/odbcbridge.conf is non-zero the ODBC server
generates additional status and error messages. Remember to
restart the syslog daemon after making configuration changes.
2. The functions dm_log_open(<logfilename>) and dm_log_close()
in UnixODBC.pm and UnixODBC::BridgeServer.pm begin and end the
logging of ODBC driver manager function calls.
3. The HTTP server records HTTP and CGI script errors in the
server's error_log.
- Authorship and Copyright
UnixODBC.pm is written by Robert Kiesling, rkies@cpan.org.
Copyright <A9> 2002-2004 by Robert Kiesling and licensed under
the same terms as Perl. Refer to the file, "Artistic," for the
details.
$Id: README,v 1.19 2004/03/14 00:27:44 kiesling Exp $
- Next message: Matthew Persico: "Request for Comments - Finance::Calc::Performance"
- Previous message: jessica_at_Vote.Nader.2004: "Message To America's Students: The War, The Draft, Your Future"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Relevant Pages
|
