[svn:dbd-oracle] r2382 - dbd-oracle/trunk

Author: timbo
Date: Wed Jan 11 03:23:28 2006
New Revision: 2382

Modified:
dbd-oracle/trunk/README
Log:
Assorted updates to the README


Modified: dbd-oracle/trunk/README
 ====================
 ====================
 ====================
================
==
--- dbd-oracle/trunk/README	(original)
+++ dbd-oracle/trunk/README	Wed Jan 11 03:23:28 2006
@@ -1,7 +1,7 @@

DBD::Oracle  --  an Oracle interface for Perl 5.

-   Copyright (c) 1994-2005  Tim Bunce, Ireland.
+   Copyright (c) 1994-2006  Tim Bunce, Ireland.

See the COPYRIGHT section in the Oracle.pm file for terms.

@@ -23,7 +23,6 @@ DBD::Oracle  --  an Oracle interface for
README.sec.txt - Oracle security issues to be aware of
README.login.txt - Help on how to connect to Oracle
README.longs.txt - Help on handling LONGs
-	README.utf8.txt - Help on using UFT8
README.clients.txt - What Oracle client files you need installed


@@ -49,14 +48,17 @@ DBD::Oracle  --  an Oracle interface for
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.
+    For Oracle Instant Client that means install the SDK component.
+    For full Oracle installs that usually includes Pro*C and SQL*Net.
+    (That's not very specific because it varies 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.
+    The ORACLE_HOME environment variable must point to the Oracle Home
+    used to create DBD::Oracle. (Not essential under MS Windows).

-    Make sure Oracle is working and you can use Oracle commands
-    like sqlplus to talk to the database *from the machine* you
+    MOST IMPORTANTLY:
+
+    Make sure Oracle is working and you can use the Oracle sqlplus
+    command 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.)

@@ -71,18 +73,17 @@ on Solaris) and add that to your PATH en

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".
+expressions", "cast increases required alignment of target type" etc.

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
+If it builds without error you should then run 'make test'. 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.
+that should you try building and 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
@@ -103,9 +104,9 @@ sure it's on your PATH so you can say 'p

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.
+It is important to use a Perl that was built on the system you are using.
+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
@@ -124,10 +125,6 @@ know so that I can try to make it automa
If you just can't login or login takes a long time then read
README.login.txt

-If you can't get it to build on a minimally configured client system
-then read README.client.txt, 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:

@@ -139,6 +136,7 @@ then you could try forcing a 'static' bu
make -f Makefile.aperl inst_perl MAP_TARGET=perl  (install new perl)
make install                                      (install DBD::Oracle)

+But that's not recommended these days.
 
@@ -146,13 +144,23 @@ then you could try forcing a 'static' bu

*** 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
+This software is supported via the dbi-users@perl.org mailing list.
+(You don't need to subscribe to the list in order to post.)
+
+Please do NOT post problems to comp.lang.perl.*, perl5-porters@perl.org,
+http://www.cpanforum.com/dist/DBD-Oracle, or google groups etc.
+
+If you're *sure* the problem is a bug then you can post a bug report
+to http://rt.cpan.org/NoAuth/Bugs.html?Dist=DBD-Oracle
+Problem reports that don't include sufficient detail (including the
+information listed below and how to reproduce the problem)
+are unlikely to get resolved.
+
+For more information and to keep informed about progress you can join the
+mailing list. Send a message to dbi-users-help@perl.org for more informatio
n.

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...
+dbi-users@perl.org.


** IT IS IMPORTANT TO INCLUDE *ALL* THE FOLLOWING INFORMATION:
@@ -174,8 +182,8 @@ dbi-users@perl.org and CC them to me at

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")
+2. Full details of which version of Oracle client and server 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)

@@ -201,19 +209,18 @@ dbi-users@perl.org and CC them to me at
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
+   as you expect, the problem may be 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
+posting. If you're not then you're *very* likely to be told "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.
+Try to help yourself first, then try to help others help you by following
+these guidelines carefully.  And remember, please don't mail developers
+directly - use the dbi-users mailing list.

Regards,
Tim.
@@ -236,8 +243,6 @@ Old archive site for Perl DB information
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
@@ -251,12 +256,6 @@ Directories of interest might be
/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