7.3 Installing Oracle::OCI

7.3 Installing Oracle::OCI

In order to install Oracle::OCI itself, you will need to obtain some additional precursor modules from CPAN. We'll describe those and then explain how to install and run Oracle::OCI.

7.3.1 Installing Oracle::OCI on Win32

There is quite a bit of compilation needed for Oracle::OCI, and at the time of writing there are no PPM files available to help us (basically because of a necessary bootstrapping process we'll describe later). However, we're confident that the Win32 Perl DBI community will oblige, sooner rather than later. If you're prepared to get your compilers dirty on Win32, the steps will be logically the same as for Unix, so simply follow the Unix installation steps we've provided, and adapt the instructions for your particular compiler type.

At the present time, Oracle::OCI is still something of an experimental Perl development. For now, if you're running Win32, your options are to try installing Oracle::OCI with Cygwin, as we discussed in Chapter 2, or to create your own versions with commercial Win32 compilers.

The best place to keep track of new developments is the main DBI page at http://dbi.perl.org, where you should look for the FAQ work of Ilya Sterin. Ilya regularly creates both XML and Oracle PPD files independently of ActiveState.com; he's often on the leading edge of the technical frontier. You can also look for Ilya's DBI FAQ at http://xmlproj.com/dbi/faq.html or his Perl Oracle PPM packages for Win32 at http://xmlproj.com/PPM.

7.3.2 Precursor Modules

You will need to install these modules in the following order:

Data::Flow

Following original inspirational work by Ilya Zakharevich, Terrence Brannon took over the Data::Flow module, which is a Perl extension for simple recipe-controlled builds of data. You can obtain it from:

http://www.cpan.org/authors/id/T/TB/TBONE

C::Scan

C::Scan also follows in the footsteps of original work by Ilya Zakharevich. C::Scan is designed to scan C language files for easily recognized constructs. You'll require its latest incarnation, especially modified for use with Perl 5.6, at Hugo van der Sanden's CPAN site. (Note that future versions may once again be taken over by their original creator, whose CPAN site listing follows). For Oracle::OCI 0.06, we required at least C::Scan Version 0.74:

http://www.cpan.org/authors/id/HVDS

http://www.cpan.org/authors/id/ILYAZ

7.3.3 Setting the Oracle::OCI Environment

To make sure that the latest downloaded version of Oracle::OCI works, you'll probably also need the latest Perl DBI and DBD::Oracle modules installed. All three modules are tightly interwoven, as we saw earlier in Figure 7-1. We'll explain how to do those installations shortly.

Oracle::OCI is unlike any other typical Perl module installation we've seen in this book. The main difference is the tarball, which is actually a toolkit for building Oracle::OCI, rather than being Oracle::OCI itself. Why is the software built in this way? The project's aim is to match your own database's OCI setup as closely as possible. The toolkit therefore examines your own exact OCI situation and configures accordingly. Doing so ensures that every single OCI function that's available on your own system will be available later within a brand-new Oracle::OCI module tailored exactly for your system. Let's go to work.

7.3.4 Installing Oracle::OCI on Unix

The first step in understanding how to install Oracle::OCI is to get our heads around its central concept. It's not a Perl module in its own right — one you can simply unpack and install, as if you're taking a nice shiny laptop out of a box and plugging in the wires. Instead, Oracle::OCI is a toolkit for building a nice shiny Perl module. What this toolkit does is examine your local version of OCI and then do a one-to-one mapping of all of its functions in order to build a blueprint of the Oracle::OCI system you will eventually require. This blueprint is then used to pull all the bits and pieces together, constructing the module that will be installed. The world's most highly personalized Perl module is essentially built before your very eyes, and you then simply install this module. It's magic!

The following installation notes were prepared using the latest version of Oracle::OCI available to us. However, this project is an extremely fast-moving one. Always check out the latest README file coming with your own latest Oracle::OCI download. This file will contain the most up-to-date installation instructions, and these are expected to get much easier over time. Tim Bunce is likely to be developing this Perl module rapidly over the next few years.

Follow these steps to install Oracle::OCI on Unix systems:

First of all, you might want to alter the boot and h2xs scripts so they have the correct version of Perl on their first shebang line. For instance, Oracle::OCI-0.06 had the following Perl command at the top of the boot file:^[3]

^[3] For more on h2xs, which is beyond the scope of this book, we highly recommend Chapter 18, Extending Perl: A First Course, in Sriram Srinivasan's finely honed masterpiece, Advanced Perl Programming (O'Reilly & Associates, 1997), http://www.oreilly.com/catalog/advperl/.
```
#!/opt/perl5/bin/perl -w
```
We changed ours to:
```
#!/usr/bin/perl -w
```
The following form may be more of a universal solution:
```
#!perl -w
```
(However, make sure to first check step 3, which follows, before doing these hacks.)
If you experience connection errors on the build, you might want to update the first few lines of the 01base.t and 05dbi.t test programs. You'll find that these are dynamically linked to the main unpack directory, and you'll need to get the right ORACLE_SID and ORACLE_USERID variables set for your environment before installing Oracle::OCI:
```
$ export ORACLE_SID=orcl.world
$ export ORACLE_USERID=scott/tiger
```
Once everything's looking good, just run the boot program:
```
$ ./boot
```
Alternatively, if you don't want to hack the #! lines as in step 1, simply run this program as follows:
```
$ perl boot
```
This will build and test everything, and will prepare your proper OCI configuration system (to be installed later).
You may experience some difficulties during the build. We can't predict everything that might go wrong. Because the errors can be varied, we think the best way of tackling any problems is to use the resources detailed in the next section. We also think that getting your hands dirty in the OCI code mines, while clutching an elven ring, should steer you clear of the really ugly cave trolls. Here are some of those we encountered:
- On SuSE Linux 7.3, we got some ORACLE not available errors, with Oracle9i. Setting TWO_TASK to orcl.world cleared these.
- We kept getting ./boot test compilation errors, related to various OCI pointer types, possibly errors only introduced since the introduction of Oracle9i. We added the following lines to getptrdef.h, and this cured the problem:
```
#define ora_getptr_OCIAnyDataSetPtr ora_getptr_generic
#define ora_getptr_OCIAnyDataPtr ora_getptr_generic
#define ora_getptr_OCICPoolPtr ora_getptr_generic
#define ora_getptr_OCIXADTablePtr ora_getptr_generic
#define ora_getptr_OCIXADFieldPtr ora_getptr_generic
```
  Once the boot command does fire correctly, you're looking for output like this:
```
chmod 755 blib/arch/auto/Oracle/OCI/OCI.so
...
t/01base............ok                                                       
t/05dbi.............ok                                                       
All tests successful.
Files=2, Tests=119, 11 wallclock secs (0.81 cusr+0.07 csys = 0.88 CPU)
...
```
Now we get to the fun part. After the first compilation stage, we should now possess a pre-installation Oracle::OCI module, ready to load up and install as in the usual Perl manner. It should be quietly awaiting instruction within the ../Oracle/OCI directory. Go here, and inscribe the following spells onto the command line to repeat the wizardry:
```
$ cd Oracle/OCI
$ perl Makefile.PL
$ make 
$ make test
...
All tests successful.
...
```
The final step should produce plenty of output:
```
$ make install
```

7.3.5 For Further Help with Oracle::OCI

Here are some suggestions for things to check and do if you have trouble with Oracle::OCI:

There's some great help on the Oracle::OCI mailing lists. To join the mighty throng, send an email to:
[email protected]
There is also a mail archive, which is especially useful for dealing with installation problems when slight tweaks are required for different flavors of Unix. Check out:
http://archive.develooper.com/[email protected]
Oracle Corporation occasionally moves their installation directories around just to keep us on our toes. For example:
- You might want to look out for situations where Oracle::OCI is expecting to see $ORACLE_HOME/network/public, but the files it's looking for are actually in $ORACLE_HOME/rdbms/public
- C header files expected in $ORACLE_HOME/rdbms/demo may also be hiding in $ORACLE_HOME/plsql/public
You may get lines such as the following:
```
Error: invalid argument declaration 
'void * argv[ ]' in OCI.xs, line 666
```
Find the offending line in the OCI.xs file, and then add the relevant function to the following piece of code in the boot file, which deliberately excludes such problematic items:
```
oci_skip => [ sort keys %{ { ... } } ]
```

For errors such as:

Error: 'OCIFooBar *' not in typemap in 
OCI.xs, line 777

You might want to add an extra line to the extra.typemap file:

OCIFooBar *    T_PTROBJ

You might also want to check the README.build file, which may hold the exact answer to your problem. However, as Oracle::OCI matures, expect it to become as pain-free as DBD::Oracle and Perl DBI are now.