| timbo@cvs.perl.org 2005-12-21, 1:24 pm |
| Author: timbo
Date: Wed Dec 21 09:33:01 2005
New Revision: 2320
Added:
dbd-oracle/branches/pythian/README
Modified:
dbd-oracle/branches/pythian/MANIFEST
Log:
Restore main README file from trunk as the one on this branch was deleted.
Update MENIFEST with new names for README files.
Modified: dbd-oracle/branches/pythian/MANIFEST
====================
====================
====================
==================
--- dbd-oracle/branches/pythian/MANIFEST (original)
+++ dbd-oracle/branches/pythian/MANIFEST Wed Dec 21 09:33:01 2005
@@ -18,21 +18,21 @@ Oracle.pm
Oracle.xs
Oraperl.pm
README
-README.aix
-README.clients
-README.explain
-README.help
-README.hpux
-README.java
-README.linux
-README.login
-README.longs
-README.macosx
-README.sec
-README.utf8
-README.vms
-README.win32
-README.wingcc Notes about building with mingw32 and cygwin32
+README.aix.txt
+README.clients.txt
+README.explain.txt
+README.help.txt
+README.hpux.txt
+README.java.txt
+README.linux.txt
+README.login.txt
+README.longs.txt
+README.macosx.txt
+README.sec.txt
+README.utf8.txt
+README.vms.txt
+README.win32.txt
+README.wingcc.txt Notes about building with mingw32 and cygwin32
Todo
dbdimp.c
dbdimp.h
Added: dbd-oracle/branches/pythian/README
====================
====================
====================
==================
--- (empty file)
+++ dbd-oracle/branches/pythian/README Wed Dec 21 09:33:01 2005
@@ -0,0 +1,276 @@
+
+DBD::Oracle -- an Oracle interface for Perl 5.
+
+ Copyright (c) 1994-2005 Tim Bunce, Ireland.
+
+ See the COPYRIGHT section in the Oracle.pm file for terms.
+
+ 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_loa
d_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...T/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.
+
|