$Id: README.DBI,v 1.8 2003/06/14 01:59:56 jeff Exp $

It may be useful to query the calling database from an external Perl procedure.
Since DBI is the standard Perl module for database access, it makes sense to
use it, along with the DBD::Oracle driver, to connect back to the database.
Support for external procedures is included in DBD::Oracle as of version 1.13,
but a bug prevents it from working in that version and 1.14.  A patch is
supplied to fix that bug.  If you are running DBD::Oracle version 1.12 or
earlier, you can apply another patch which adds external procedure support.

Here's how to apply the patches:

1) Change to the DBD-Oracle distribution directory
2) Run: chmod 644 dbdimp.c
3) Patch DBD::Oracle as follows:

   If you have DBD::Oracle 1.12 or earlier:

    1) Copy DBD-Oracle.patch from the extproc_perl distribution to the current
       directory.
    2) Run: patch -p1 < DBD-Oracle.patch

   If you have DBD::Oracle 1.13 or 1.14:

    1) Copy DBD-Oracle-1.13.patch from the extproc_perl distribution to the
       current directory.
    2) Run: patch < DBD-Oracle-1.14.patch

4) Rebuild and install DBD::Oracle
5) Rebuild extproc_perl and include DBI and DBD::Oracle in the list of modules
   to link with.

To connect back to the calling database, call the ExtProc->dbi_connect method
from the ExtProc module, which will return a DBI handle.  It wraps DBI->connect
and helps manage the internal magic that glues extproc_perl and DBD::Oracle
together.

The example below is from the ExtProc module documentation:

 use DBI;
 use ExtProc;

 # connect back to the calling database
 my $dbh = ExtProc->dbi_connect;

If you are connecting to another database, one which did NOT call the external
procedure, just use DBI as you normally would.

IMPORTANT: External procedures are NOT stateful, which means that there is
no concept of a "connection" back to the calling database.  Therefore, you
need to call DBI->connect EACH TIME you want to make a query.  Don't worry,
it's very fast, since Oracle has already set up the infrastructure to make
these queries.  You can call the disconnect method to be proper, but it's
probably not mandatory.

See the extproc_perl POD documentation for important restrictions on using
DBI callbacks.
