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

   Copyright (c) 1994,1995,1996  Tim Bunce

   You may distribute under the terms of either the GNU General Public
   License or the Artistic License, as specified in the Perl README file.


** WARNING: THIS IS MOSTLY ALPHA SOFTWARE. Your mileage may vary.      **
** THE ORAPERL EMULATION IS NO LONGER ALPHA. IT IS NOW FULLY RELEASED. **

   The only currently supported interface is via Oraperl.pm, the
   oraperl emulation layer. This is fairly complete and stable.
   Execute "perldoc Oraperl" for info.


*BEFORE* BUILDING, TESTING AND INSTALLING this you will need to:

    Build, test and install Perl 5 (at least 5.002beta2).
    It is very important to test it and install it!

    Build, test and install the DBI module (at least DBI 0.69).
    It is very important to test it and install it!

    Remember to *read* the DBI README file!


BUILDING

	perl Makefile.PL
	make
	make test
	make test TEST_VERBOSE=1   (if any of the t/* tests fail)

	make install (if the tests look okay)

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 never 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 HAVE PROBLEMS:

Please don't post problems to comp.lang.perl.misc 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 a
mailing list via http://www.fugue.com/dbi (if you are unable to use the
web you can subscribe by sending a message to dbi-request@fugue.com, it
may take a few days to be processed).

Please post details of any problems (or changes you needed to make) to
dbi-users@fugue.com and CC them to me at Tim.Bunce@ig.co.uk.

Please include:

1. A complete log of a all steps of the build, e.g.:

	perl Makefile.PL           (do a make realclean first)
	make
	make test
	make test TEST_VERBOSE=1   (if any tests fail)

2. Full details of which version of Oracle and Perl you're using.

3. The output of perl -V

4. If you get a core dump, try to include a stack trace from it.
   I may not be able to help you much without it.
   If the stack trace mentions XS_DynaLoader_dl_load_file then rerun
   make test after setting the environment variable PERL_DL_DEBUG to 2.


Regards,
Tim.

===============================================================================
Some Users of DBD::Oracle on Specific Platforms:
(this is VERY out of date now, there are MANY users on many platforms)

Solaris 1:
	Myself.
	John D Groenveld <groenvel@cse.psu.edu>
	Christian Murphy <r1938c@ismuc.sps.mot.com>

Solaris 2:
	Myself.
	David Moellenhoff <David_Moellenhoff@msi-gateway1.metropolis.com>
	James Taylor <james.taylor@srs.gov>
	Jay Krish <krishnam@hollynet.usc.edu>
	John D Groenveld <groenvel@cse.psu.edu>
	Joe Hildebrand <hildebra@arls2007.den.mmc.com>
	John Liptak <jliptak@coefmd3.mnet.uswest.com>
	Philip Kizer <pckizer@tamu.edu>
	Alan Johnson <alan.johnson@gel.com>
	Jim Fox <fox@austin.asc.slb.com>

HP-UX 9:
	Terry Greenlaw <z50816@mip.lasc.lockheed.com>
	Les Troyer <t2078@dcs2.nfuel.com>
	Norbert Kiesel <nk@ipgate.col.sw-ley.de>
	Greg Anderson <greg@ftp.netgate.net>
	Johann Griessler <griess@atc.co.at>
	Dave Venus <DVENUS@delphi.com>

Unisys U6000/300:
	Alan Burlison <aburlison@cix.compulink.co.uk>

SCO 3:
	Joel Rosi-Schwartz <joel@techne.co.uk>
	Greg Gerber <ggerber@grctechs.va.grci.com>

Sequent DYNIX/ptx 2:
	Alligator Descartes <descarte@mcqueen.com>
	Jonathan Lemon <jlemon@americantv.com>

NT:
    Jim Fox <fox@austin.asc.slb.com>

Motorola M88100 (SVR3.2):
	Christian Murphy <r1938c@ismuc.sps.mot.com>

DEC UNIX 3.2:
	David J. DeWolfe <SXDJD@orca.alaska.edu>


DEC Alpha, OSF/1 v2:
	Royal Hansen <rivory@minerva.cis.yale.edu>
	Jonathan Olson <jbolson@peruvian.cs.utah.edu>
	Greg Gerber <ggerber@grctechs.va.grci.com>
    Davide Migliavacca <davide.migliavacca@relay.inferentia.it>

SGI Iris Indigo R4000 Irix 5.3:
	Andrew G Wood <agw@mail.nerc-bas.ac.uk>

AIX 3.2
    Davide Migliavacca <davide.migliavacca@relay.inferentia.it>
	Joerg Senekowitsch <joerg@pharmacy.isu.edu>

AIX 4.1
	Ken P. Nikolai <nikolai@facstaff.wisc.edu>


===============================================================================
Platform or Oracle Version specific notes:

-------------------------------------------------------------------------------
HP-UX: Terry Greenlaw <z50816@mip.lasc.lockheed.com>

I traced a problem with "ld: Invalid loader fixup needed" to the file
libocic.a. On HP-UX it contains position-dependant code and cannot be
used to generate dynamic load libraries. The only shared library that
Oracle ships under HP-UX is liboracle.sl which replaces libxa.a,
libsql.a, libora.a, libcvg.a, and libnlsrtl.a. The OCI stuff still
appears to only link statically under HU-UX.

You'll need to build DBD::Oracle statically linked into the perl binary.
See the static linking notes below.

-------------------------------------------------------------------------------
For platforms which require static linking.

If you get an error like:

/usr/lib/dld.sl: Bad magic number for shared library:
/usr/local/lib/perl5/hpux/auto/DBD/Oracle/Oracle.a

You'll need to build DBD::Oracle statically linked and then link it
into a perl binary:

	perl Makefile.PL LINKTYPE=static
	make
	make perl             (makes a perl binary in current directory)
	make test FULLPERL=./perl  (run tests using the new perl binary)
    make install

You will probably need to have already built and installed a static
version of the DBI in order that it be automatically included when
you do the 'make perl' above.

-------------------------------------------------------------------------------
Oracle 7.1.3: Syntax error in oratypes.h

Try uncommenting the '#define signed' line in Oracle.h

-------------------------------------------------------------------------------
Oracle 7.1.3/4: Connection takes a long time and may coredump

Oracle bug number: 227321 related to changing the environment before
connecting to oracle.

To work around this bug, do not set any environment variables in your
oraperl script before you call ora_login, and when you do call
ora_login, the first argument must be the empty string.  This means
that you have to be sure that your environment variables ORACLE_SID
and ORACLE_HOME are set properly before you execute any oraperl
script.  It is probably also possible to pass the SID to ora_login as
part of the username (for example, ora_login("", "SCOTT/TIGER@PROD",
"")), although I have not tested this.
This workaround is based on information from Kevin Stock.

-------------------------------------------------------------------------------
Oracle 7.1.4/5: ORA-01002: fetch out of sequence
Edited from Message-ID: <3qaui9$ae@usenet.rpi.edu> and
<3qb5dp$2nc@usenet.rpi.edu> in comp.databases.oracle
From: finkej@ts.its.rpi.edu (Jon Finke)

I am in the process of converting a locally developed that sits on top
of the OCI routines from version 6 to version 7.   Unfortunately, I have
run into a snag that I have been unable to get around.   Every test run
results in getting an "ORA-01002: fetch out of sequence" error.

The manual claims that this is the result of calling "ofetch" before
oparse/oexec, or running out of things to fetch.   Yet, I am calling
oopen, oparse, oexec, (odesc, odefin) all without error.  As a control
case, I also built the cdemo2 program, and it appears to be calling
the same routines, yet it is successful.  

Note: In the "broken" program, I am currently calling odsc in a loop
      for each column in the query, and then calling odefin, while in the 
      "working" program, I call odescr/odefin, odesc/odefin for each column.
      In both cases, the calls to odefin seem reasonable.

Both programs are attempting the query "select user,uid from dual".

This is a known problem in version 7.1.4, and it will be fixed in 7.1.6.
The bug report is #239128.
-- 
Jon Finke                           finkej@rpi.edu
Senior Network Systems Engineer     http://www.rpi.edu/~finkej
Information Technology Services     518 276 8185 (voice) | 518 276 2809 (fax)
Rensselaer Polytechnic Institute    110 8th Street, Troy NY, 12180

-------------------------------------------------------------------------------
ORA-00604: error occurred at recursive SQL level  (DBD: login failed)

This can happen if TWO_TASK is defined but you connect using ORACLE_SID.

-------------------------------------------------------------------------------
Environment:  SunOS 4.1.3, Oracle 7.1.6  Steve Livingston <mouche@hometown.com>

If you get link errors like: ld: Undefined symbols _environ _dlopen _dlclose ...
and the link command line includes '-L/usr/5lib -lc' then comment out the
'CLIBS= $(OTHERLIBS) -L/usr/5lib -lc' line in the Makefile.

-------------------------------------------------------------------------------
Environment:  Solaris, GCC, Sanford Dickert <ncc1701a@isl.stanford.edu>

Error: gcc: unrecognized option `-Y'
Fix: Edit the Makefile to remove the space from '-Y P'.

-------------------------------------------------------------------------------
Environment:  SVR4, stephen.zander@mckesson.com

Error: can't load ./blib/arch/auto/DBD/Oracle/Oracle.so for module DBD::Oracle:
DynamicLinker:/usr/local/bin/perl:relocation error:symbol not found:setitimer
Fix: Try adding the '-lc' to $ORACLE_HOME/rdbms/lib/sysliblist (just
make sure it's not on a new line).

-------------------------------------------------------------------------------
Environment:  Solaris, GCC

Error: Undefined symbols __cg92_used at link time.
Fix: If you're compiling Oracle applications with gcc on Solaris you need to
link with a file called $ORACLE_HOME/lib/__fstd.o. If you compile with the
SparcWorks compiler you need to add the command line option on -xcg92
to resolve these symbol problems cleanly.

Alligator Descartes <descarte@hermetica.com>

-------------------------------------------------------------------------------
Environment:  SunOS 4.1.3, Oracle 7.1.3  John Carlson <carlson@tis.llnl.gov>

Problem:  oraperl and DBD::Oracle fail to link.  Some messing around with
the library order makes the link succeed.  Now I get a "Bad free()" when
ora_logoff is called.

Solution:
In my case, this was caused by a faulty oracle install.  The install grabbed
the wrong version of mergelib (The X11R6 one) instead of the one in
$ORACLE_HOME/bin.  Try a more limited path and reinstall Oracle again.

-------------------------------------------------------------------------------
Environment:  DEC Alpha, OSF, Jonathan Olson <jbolson@peruvian.cs.utah.edu>

Problem: ERROR EVENT: DBI::dr=HASH(0x14011fee8)->DBI::default_handler:
        0 ORA-00000: normal, successful completion (DBD: login failed)

Solution: Add '#define A_OSF' to Oracle.h above '#include <oratypes.h>' and
complain to Oracle about bugs in their header files on 64 bit systems.

Problem: Unable to connect

Solution: Try using something like this: "scott/tiger@t:HOST_IP:INSTANCE"
and not just "scott/tiger".

===============================================================================

End.
