=head1 NAME
extproc_perl - Oracle Perl Procedure Library
=head1 SYNOPSIS
=head2 FUNCTION SYNTAX
=over 4
select perl('sub1','1','2') from dual;
=back
=head2 PROCEDURE SYNTAX
=over 4
exec perl_p('sub2','arg1');
=back
=head1 DESCRIPTION
extproc_perl enables Oracle stored procedures and functions to be written
in Perl. It uses Oracle 8's external procedure interface to create Perl
interpreters on the fly to execute Perl subroutines. Code is stored in
a central "bootstrap" file that is interpreted after each interpreter is
initialized. In the current implementation of Oracle external procedures,
the Perl interpreter is persistent for the life of a client session. This
has the effect of keeping both interpreted code and data in memory for the
life of that particular session.
=head1 MODULES
The Oracle external procedure process and DynaLoader do not work well
together. In fact, DynaLoader doesn't work at all in this environment.
Therefore, in order to use dynamically loaded modules like Socket, hooks for
each module need to be compiled into the extproc_perl shared library. This
means that for each module you want to use, you must declare it at build time.
The Makefile.PL file provides gives you the option of declaring these modules.
Note that this restriction does not apply to Perl-only modules, but it's safe
to declare them as well during this process -- they will be ignored.
ExtProc is a module that is statically linked into the extproc_perl object.
It provides several functions that interact with the Oracle database itself.
See the ExtProc(3) manpage for details.
=head1 SPECIAL SUBROUTINES
The following subroutines are reserved for extproc_perl, and can be called
like any other Perl subroutine from Oracle.
=over 4
=item _flush()
Destroys Perl interpreter and all Perl data. A new interpreter will be started
for the next query.
=item _version()
Reports the version and configuration options of the currently loaded extproc_perl.
=item _modules()
Returns a space separated list of modules that were requested to be statically
linked into extproc_perl.
=item _codetable(table_name)
Sets or returns the database table queried for code.
=item _error()
Returns the most recent error string.
=item _errno()
Returns the most recent system error message ($! in Perl).
=item _preload()
Force extproc_perl to load code from the database immediately.
=item _eval(code)
Execute raw code in an eval block and return its return value.
=item _enable_debug()
Enable debugging and return path to log file.
=item _disable_debug()
Disable debugging.
=back
=head1 DBI CALLBACKS
If you are using DBD::Oracle with the supplied patch, you can query the calling
database using DBI. This is a surprisingly fast operation, as there is no
need to establish a new session to the database. There are two basic steps
for using a DBI callback:
=over 4
1. Initialize the callback infrastructure and obtain a DBI handle using
ExtProc->dbi_connect:
=over 4
my $dbh = ExtProc->dbi_connect();
=back
2. Query/Update the database using standard DBI methods.
=back
NOTE: External procedure callbacks are stateless, therefore you MUST call
DBI->connect once per transaction (for extproc_perl, this means once per
function or procedure call from Oracle).
The following rules apply when using DBI callbacks:
=over 4
=item
Queries work from both functions and procedures.
=item
DML statements (insert, update, delete, etc.) only work from procedures.
This is an Oracle restriction.
=item
DDL statements (create table, drop table, etc.) will not work at all.
Again, an Oracle restriction.
=back
=head1 SECURITY
If you enabled taint mode during the configuration of extproc_perl, all
arguments to functions and procedures will be tainted before they are passed
to Perl subroutines. This is HIGHLY recommended for environments in which you
do not trust the content of the arguments, such as web form data. See the
perlsec(1) man page for more information on Perl's taint mode.
=head1 AUTHOR
Jeff Horwitz <jeff@smashing.org>
=head1 SEE ALSO
perl(1), perlembed(1), perlsec(1), ExtProc(3)
=cut