DBD::Oracle -- an Oracle interface for Perl 5.
Copyright (c) 1994-2004 Tim Bunce, Ireland.
See the COPYRIGHT section in the Oracle.pm file.
PLEASE READ THE ENTIRE README FILE CAREFULLY !
AND THEN READ ANY README.* FILES RELEVANT TO YOUR PLATFORM:
README.aix - AIX
README.hpux - HP-UX
README.java - Java/thread problem on Solaris
README.macosx - Mac OS/X
README.win32 - MS Windows
README.wingcc - MS Windows using GCC
README.* - see if there's a file for your platform
You may find these useful
README.help - Help and hints on build problems
README.sec - Oracle security issues to be aware of
README.login - Help on how to connect to Oracle
README.longs - Help on handling LONGs
README.utf8 - Help on using UFT8
README.clients - What Oracle client files you need installed
*** QUICK START GUIDE:
The DBI requires one or more 'driver' modules to talk to databases.
Fetch, build and install the DBI module as per its README file.
You may then delete its source directory tree since it's no longer needed.
Use the 'perldoc DBI' command to read the DBI documentation.
Fetch this DBD::Oracle driver module and unpack it.
Follow the guidelines in this README file carefully.
*** *BEFORE* BUILDING, TESTING AND INSTALLING DBD::Oracle:
Build, test and install Perl 5 (at least 5.6.1)
It is very important to TEST it and INSTALL it!
Build, test and install the DBI module (at least DBI 1.21).
It is very important to TEST it and INSTALL it!
Remember to *read* the DBI README file and this one CAREFULLY!
Install enough Oracle software to enable DBD::Oracle to build.
That usually includes Pro*C and SQL*Net. That's not very specific
because it varies so much between Oracle releases.
Except under MS Windows, ORACLE_HOME must point to the Oracle Home
used to create DBD::Oracle. Even under MS Windows, it doesn't hurt.
Make sure Oracle is working and you can use Oracle commands
like sqlplus to talk to the database *from the machine* you
want to build DBD::Oracle on. (This often involves setting
environment variables like PATH, LD_LIBRARY_PATH, TWO_TASK etc.)
*** BUILDING:
perl Makefile.PL # use a perl that's in your PATH
make
If you get an error like "make: not found" you need to find the
directory that has the make command installed in it (e.g. /usr/ccs/bin
on Solaris) and add that to your PATH environment variable.
Don't worry about most warnings when make runs, specifically ones like
"end-of-loop code not reached", "ANSI C forbids braced-groups within
expressions", "cast increases required alignment of target type" and
"passing arg 2 of `oerhms' with different width due to prototype".
If you have problems see the 'IF YOU HAVE PROBLEMS' section below.
If it builds without error you should then run the tests. For the
main tests to work they must be able to connect to an Oracle database.
You will need to set either the TWO_TASK or ORACLE_SID environment
variables to the correct values for your database. Consult Oracle
documentation for more details. Test your settings by connecting to
the database using an Oracle tool such as sqlplus. Only once you can do
that should you try testing DBD::Oracle.
The supplied tests will connect to the database using the value of the
ORACLE_USERID environment variable to supply the username/password so
you should set that to a valid value (e.g. 'scott/tiger') before
starting the test. Using 'system/manager' might work but is not
recommended! Please read README.login.
make test
make install (if the tests look okay, the last few are rather verbose)
*** IF YOU HAVE PROBLEMS:
Make sure you are using a recent perl (5.6.1 or later) and make
sure it's on your PATH so you can say 'perl Makefile.PL' and not
'/path/to/perl Makefile.PL'.
If you get compiler errors refering to Perl's own header files
(.../CORE/*.h) then there is something wrong with your installation.
It is important to use a Perl that was built on the system you are
trying to use and it's also important to use the same compiler that
was used to build the Perl you are using.
If you have build/link or core dump problems try:
perl Makefile.PL -p
or
perl Makefile.PL -nob
If it helps then please let me know (and please include a copy
of the log from the failed default build, the log from the build that
worked, plus the output of the "perl -V" command).
Do not hand edit the generated Makefile unless you are completely sure
you understand the implications! Always try to make changes via the
Makefile.PL command line and/or editing the Makefile.PL.
You should not need to make any changes. If you do please let me
know so that I can try to make it automatic in a later release.
If you just can't login or login takes a long time then read
README.login
If you can't get it to build on a minimally configured client system
then read README.client, it might help but basically I can't help much.
Others on the dbi-users mailing list probably can.
If you have linking problems (errors related to libraries or functions)
then you could try forcing a 'static' build using:
make realclean
perl Makefile.PL LINKTYPE=static
make
make perl (you'll need to use and install _this_ new perl binary)
make test
make -f Makefile.aperl inst_perl MAP_TARGET=perl (install new perl)
make install (install DBD::Oracle)
>>> Also carefully read the README.help file which is full of useful
>>> tips and workarounds for various problems of various systems.
*** HOW TO REPORT PROBLEMS
Please don't post problems to comp.lang.perl.* or perl5-porters.
This software is supported via the dbi-users mailing list. For more
information and to keep informed about progress you can join the
mailing list by sending a message to dbi-users-help@perl.org
Please post details of any problems (or changes you needed to make) to
dbi-users@perl.org and CC them to me at Tim.Bunce@pobox.com. But note...
** IT IS IMPORTANT TO INCLUDE *ALL* THE FOLLOWING INFORMATION:
1. A complete log of all steps of the build, e.g.:
(do a make realclean first)
perl Makefile.PL -v (note the -v for verbose)
make
make test
Make sure to include the 'stderr' output. The best way to do this is
to use the "script" command (man script). If that's not available
then "command > command.log 2>&1" (assuming you're not using csh).
The "2>&1" is required (after the stdout redirect) to redirect stderr
to the same place.
If a test fails then also include the output of:
perl -Mblib t/<name-of-failed-test>.t
2. Full details of which version of Oracle you're using (if it
wasn't automatically found and printed by "perl Makefile.PL")
3. The output of perl -V (that's a capital V, not lowercase)
4. If you get errors like "undefined symbol", "symbol not found",
"undefined reference", "Text relocation remains" or any similar
error then include the output of "perl Makefile.PL -s XXX"
where XXX is the name of one of the symbols.
Please don't send the entire output of this command,
just any obviously 'interesting' parts (if there are any).
See also the LINKTYPE=static notes above.
5. If you get a core dump, rebuild DBD::Oracle with debugging
enabled by executing: perl Makefile.PL -g (note the -g option)
then rerun the code to get a new core dump file, finally use a
debugger (gdb, sdb, dbx, adb etc) to get a stack trace from it.
NOTE: I may not be able to help you much without a stack trace!
It is worth fetching and building the GNU GDB debugger (>=4.15) if
you don't have a good debugger on your system. If desparate try:
make perl; ./perl script; echo '$c' | adb ./perl core
Also see the Devel::CoreStack module on CPAN.
6. If the stack trace mentions XS_DynaLoader_dl_load_file then rerun
make test after setting the environment variable PERL_DL_DEBUG to 2.
7. If your installation succeeds, but your script does not behave
as you expect, the problem is most likely on your end. Before
sending to dbi-users, try writing a small, easy to use test case
to reproduce your problem. Also, use the DBI->trace method to
trace your database calls.
It is important to check that you are using the latest version before
posting. If you're not then I'm *very* likely to simply say "upgrade to
the latest". You would do yourself a favour by upgrading beforehand.
Please remember that I'm _very_ busy. Try to help yourself first,
then try to help me help you by following these guidelines carefully.
And remember, please don't mail me directly - use the dbi-users
mailing list.
Regards,
Tim.
===============================================================================
Examples and other info:
README.help -- READ IT FIRST IF YOU HAVE ANY PROBLEMS
README.win32 -- building DBD::Oracle under MS Windows
README.wingcc -- building DBD::Oracle under MS Windows with gcc
README.macosx -- building DBD::Oracle under MacOS X
README.clients -- building/using DBD::Oracle on minimally configured systems
README.login -- help for login problems
README.longs -- examples dealing with LONG types (blobs)
README.utf8 -- Perl 5.6.1, Oracle, and UTF-8
DBI 'home page': http://dbi.perl.org
Old archive site for Perl DB information:
ftp://ftp.demon.co.uk/pub/perl/db/
Mailing list archive: /DBI/perldb-interest/
Perl 4 Oraperl (v2.4) /perl4/oraperl/
ftp://ftp.bf.rmit.edu.au/pub/Oracle/sources/...
Jeff Stander's stuff stands out for Oraperl:
Directories of interest might be
/pub/Oracle/sources
/pub/Oracle/sources/jstander
/pub/Oracle/sources/jstander/distrib
/pub/Oracle/sources/jstander/tsmlib
/pub/Oracle/sources/jstander/wdbex
/pub/Oracle/sources/web/scripts
/pub/Oracle/sources/dba
/pub/Oracle/sources/dba/imp2sql7
/pub/Oracle/sources/Lonnroth
/pub/Oracle/sources/harrison
Send stuff for the archive in
[.{cpio|tar|zip}][.{gz|Z|zip}].uu
format if by mail to me (orafaq@bf.rmit.edu.au)
And drop the .uu if using ftp, putting file(s) in
ftp://ftp.bf.rmit.edu.au/incoming/Oracle
http://www.bf.rmit.edu.au/~orafaq/perlish.html
ftp://ftp.bf.rmit.edu.au/pub/perl/db
ftp://ftp.bf.rmit.edu.au/pub/Oracle
ftp://ftp.bf.rmit.edu.au/pub/Oracle/sources
ftp://ftp.bf.rmit.edu.au/pub/Oracle/OS/MS/NT/ntoraperl.zip
DBI and DBD::Oracle are very portable. If Perl and Oracle run on a platform
then the chances are that DBD::Oracle will as well.
===============================================================================
See the large README.help file for lots of hints and advice about building and
runtime issues.
End.