[svn:dbd-oracle] r14858 - dbd-oracle/trunk
[email protected] Fri, 13 May 2011 05:46:23 -0700 (PDT)
| Newsgroups | perl.dbd.oracle.changes |
|---|---|
| Message-ID | <[email protected]> |
Author: byterock
Date: Fri May 13 05:46:22 2011
New Revision: 14858
Modified:
dbd-oracle/trunk/Changes
dbd-oracle/trunk/Oracle.pm
dbd-oracle/trunk/Oraperl.pm
dbd-oracle/trunk/oci8.c
Log:
Fixed up the POD based on DBD::Pg by John Scoles
Revoved oparse_lng as it is obsolete by John Scoles
Modified: dbd-oracle/trunk/Changes
==============================================================================
--- dbd-oracle/trunk/Changes (original)
+++ dbd-oracle/trunk/Changes Fri May 13 05:46:22 2011
@@ -1,5 +1,7 @@
=head1 Changes in DBD-Oracle 1.29_1 (svn rev NNNNN)
+ Fixed up the POD based on DBD::Pg by John Scoles (most likely killed martins below
+ Revoved oparse_lng as it is obsolete by John Scoles
Added installation notes for MAC Snow Leopard by Martin J. Evans
pod review rephrasing, fixing typos and spelling mistakes up to "Placeholder Binding Attributes" by Martin J. Evans
Add /etc to the search paths for tnsnames.ora (rt67942) by Martin J. Evans, Jay Senseman
Modified: dbd-oracle/trunk/Oracle.pm
==============================================================================
--- dbd-oracle/trunk/Oracle.pm (original)
+++ dbd-oracle/trunk/Oracle.pm Fri May 13 05:46:22 2011
@@ -52,7 +52,7 @@
sub CLONE {
$drh = undef ;
}
-
+
sub driver{
return $drh if $drh;
my($class, $attr) = @_;
@@ -499,7 +499,7 @@
if (ref $catalog eq 'HASH') {
($schema, $table) = @$catalog{'TABLE_SCHEM','TABLE_NAME'};
$catalog = undef;
- }
+ }
my $SQL = <<'SQL';
SELECT *
FROM
@@ -890,7 +890,7 @@
my $version = join ".", @{ ora_server_version($dbh) }[0..1];
my $len = 32767;
if ($version < 10.2){
- $len = 400;
+ $len = 400;
}
# line can be greater that 255 (e.g. 7 byte date is expanded on output)
$sth->bind_param_inout(':l', \$line, $len, { ora_type => 1 });
@@ -1109,19 +1109,27 @@
=head1 DESCRIPTION
DBD::Oracle is a Perl module which works with the DBI module to provide
-access to Oracle databases.
+access to Oracle databases.
+
+=head1 Module Documentation
+
+This documentation describes driver specific behaviour and restrictions. It is
+not supposed to be used as the only reference for the user. In any case
+consult the B<DBI> documentation first!
-=head1 Which version of DBD::Oracle is for me?
+=for html <a href="http://search.cpan.org/~timb/DBI/DBI.pm">Latest DBI documentation.</a>
-From version 1.25 onwards DBD::Oracle will only support Oracle clients
-9.2 or greater. Support for ProC connections was dropped in 1.29.
+=head1 Which version DBD::Oracle is for me?
-If you are still stuck with an older version of Oracle or its client
-you might want to look at the table below.
+From version 1.25 onwards DBD::Oracle will only support Oracle clients 9.2 or greater as well
+support for ProC connections was dropped in 1.29. This is especially so with the many new functions
+being introduced in 10g and 11g.
+
+If you are still stuck with an older version of Oracle or its client you might want to look at the table below.
+---------------------+-----------------------------------------------------+
- | | Oracle Version |
+ | | Oracle Version |
+---------------------+----+-------------+---------+------+--------+--------+
| DBD::Oracle Version | <8 | 8.0.3~8.0.6 | 8iR1~R2 | 8iR3 | 9i | 9.2~11 |
+---------------------+----+-------------+---------+------+--------+--------+
@@ -1140,37 +1148,116 @@
| 1.25+ | N | N | N | N | N | Y |
+---------------------+----+-------------+---------+------+--------+--------+
-As there are dozens of different versions of Oracle's clients this
-list does not include all of them, just the major released versions of
-Oracle.
-
-Note that one can still connect to any Oracle version with the older
-DBD::Oracle versions the only problem you will have is that some of
-the newer OCI and Oracle features available in later DBD::Oracle
-releases will not be available to you.
+As there are dozens and dozens of different versions of Oracle's clients I did not bother to list any of them, just the
+major release versions of Oracle that are out there.
+
+Note that one can still connect to any Oracle version with the older DBD::Oracle versions the only problem you will
+have is that some of the newer OCI and Oracle features available in later DBD::Oracle releases will not be available to you.
So to make a short story a little longer;
- 1) If you are using Oracle 7 or early 8 DB and you can manage to get a 9 client and you can use any DBD::Oracle version.
+ 1) If you are using Oracle 7 or early 8 DB and you can manage to get a 9 client and you can use
+ any DBD::Oracle version.
2) If you have to use an Oracle 7 client then DBD::Oracle 1.17 should work
- 3) Same thing for 8 up to R2, use 1.17, if you are lucky and have the right patch-set you might go with 1.18.
- 4) For 8iR3 you can use any of the DBD::Oracle versions up to 1.21. Again this depends on your patch-set, If you run into trouble go with 1.19
+ 3) Same thing for 8 up to R2, use 1.17, if you are lucky and have the right patch-set you might
+ go with 1.18.
+ 4) For 8iR3 you can use any of the DBD::Oracle versions up to 1.21. Again this depends on your
+ patch-set, If you run into trouble go with 1.19
5) After 9.2 you can use any version you want.
- 6) For you Luddites out there ORAPERL still works and is still included but not updated or supported anymore and was removed in 1.29.
- 7) It seems that the 10g client can only connect to 9 and 11 DBs while the 9 can go back to 7 and even get to 10. I am not sure what the 11g client can connect to.
+ 6) For you Luddites out there ORAPERL still works and is still included but not updated or
+ supported anymore and will be removed as some time in the near future.
+ 7) It seems that the 10g client can only connect to 9 and 11 DBs while the 9 can go back to 7
+ and even get to 10. I am not sure what the 11g client can connect to.
+
+
+
+
+
+
+=head1 Constants
+
+=over 4
+
+=item :ora_session_modes
+
+ORA_SYSDBA ORA_SYSOPER
+
+=item :ora_types
+
+ ORA_VARCHAR2 ORA_STRING ORA_NUMBER ORA_LONG ORA_ROWID ORA_DATE ORA_RAW
+ ORA_LONGRAW ORA_CHAR ORA_CHARZ ORA_MLSLABEL ORA_XMLTYPE ORA_CLOB ORA_BLOB
+ ORA_RSET ORA_VARCHAR2_TABLE ORA_NUMBER_TABLE SQLT_INT SQLT_FLT ORA_OCI
+ SQLT_CHR SQLT_BIN
+
+=item SQLCS_IMPLICIT
+
+=item SQLCS_NCHAR
+
+SQLCS_IMPLICIT and SQLCS_NCHAR are I<character set form> values.
+See notes about Unicode elsewhere in this document.
+
+=item SQLT_INT
+
+=item SQLT_FLT
+
+These types are used only internally, and may be specified as internal
+bind type for ORA_NUMBER_TABLE. See notes about ORA_NUMBER_TABLE elsewhere
+in this document
+
+=item ORA_OCI
+
+Oracle doesn't provide a formal API for determining the exact version
+number of the OCI client library used, so DBD::Oracle has to go digging
+(and sometimes has to more or less guess). The ORA_OCI constant
+holds the result of that process.
+
+In string context ORA_OCI returns the full "A.B.C.D" version string.
+
+In numeric context ORA_OCI returns the major.minor version number
+(8.1, 9.2, 10.0 etc). But note that version numbers are not actually
+floating point and so if Oracle ever makes a release that has a two
+digit minor version, such as C<9.10> it will have a lower numeric
+value than the preceding C<9.9> release. So use with care.
+
+The contents and format of ORA_OCI are subject to change (it may,
+for example, become a I<version object> in later releases).
+I recommend that you avoid checking for exact values.
+
+=item :ora_fetch_orient
+
+ OCI_FETCH_CURRENT OCI_FETCH_NEXT OCI_FETCH_FIRST OCI_FETCH_LAST
+ OCI_FETCH_PRIOR OCI_FETCH_ABSOLUTE OCI_FETCH_RELATIVE
+
+These constants are used to set the orientation of a fetch on a scrollable cursor.
+
+=item :ora_exe_modes
+
+ OCI_STMT_SCROLLABLE_READONLY
+
+=item :ora_fail_over
+
+ OCI_FO_END OCI_FO_ABORT OCI_FO_REAUTH OCI_FO_BEGIN OCI_FO_ERROR
+ OCI_FO_NONE OCI_FO_SESSION OCI_FO_SELECT OCI_FO_TXNAL
+
+=back
+
+=head1 The DBI Class
+=head2 DBI Class Methods
-=head1 CONNECTING TO ORACLE
+=head3 B<connect>
-This is a topic which often causes problems mainly due to Oracle's
-many and sometimes complex ways of specifying and connecting to
-databases. James Taylor and Lane Sharman have contributed much of the
-text in this section. Unfortunately it is only really relevant to
-connecting into older Oracle (<9) versions. Most of this is well out
-of date. See the next section L</CONNECTING TO ORACLE II> for more up
-to date connection hints.
+This method creates a database handle by connecting to a database, and is the DBI
+equivalent of the "new" method.
-=head2 Connecting without environment variables or tnsnames.ora file
+This is a topic which often causes problems. Mainly due to Oracle's many
+and sometimes complex ways of specifying and connecting to databases.
+James Taylor and Lane Sharman have contributed much of the text in
+this section. Unfortunately it is only really relative for connecting into older Oracle (<9) versions.
+Most of this stuff is well out of date but it will be left in for now.
+See the next section L</CONNECTING TO ORACLE II> for some more up to date connection hints.
+
+=head4 Connecting without environment variables or tnsnames.ora file
If you use the C<host=$host;sid=$sid> style syntax, for example:
@@ -1180,13 +1267,13 @@
for you and Oracle will not need to consult the tnsnames.ora file.
If a C<port> number is not specified then the descriptor will try both
-1526 and 1521 in that order (i.e., new then old). You can check which
-port(s) are in use by typing C<"$ORACLE_HOME/bin/lsnrctl stat"> on the server.
+1526 and 1521 in that order (e.g., new then old). You can check which
+port(s) are in use by typing "$ORACLE_HOME/bin/lsnrctl stat" on the server.
-=head2 Oracle Environment Variables
+=head4 Oracle Environment Variables
Oracle typically no longer needs two environment variables to specify default
-connections: ORACLE_SID and TWO_TASK.
+connections: ORACLE_SID and TWO_TASK.
ORACLE_SID is really unnecessary to set since TWO_TASK provides the
same functionality in addition to allowing remote connections.
@@ -1196,10 +1283,10 @@
% sqlplus username/password
-Note that if you have B<both> local and remote databases, and you
-have ORACLE_SID B<and> TWO_TASK set, and you don't specify a fully
+Note that if you have *both* local and remote databases, and you
+have ORACLE_SID *and* TWO_TASK set, and you don't specify a fully
qualified connect string on the command line, TWO_TASK takes precedence
-over ORACLE_SID (i.e. you are connected to the remote system).
+over ORACLE_SID (i.e. you get connected to remote system).
TWO_TASK=P:sid
@@ -1214,8 +1301,8 @@
will use the info stored in the SQL*Net v2 F<tnsnames.ora>
configuration file for local or remote connections.
-Support for 'T:' syntax of Oracle SQL*Net V1 is only supported on older 7 clients and
-I have my doubts it will even work if the DB or client has been patched and I know it
+Support for 'T:' syntax of Oracle SQL*Net V1 is only supported on older 7 clients and
+I have my doubts it will even work if the DB or client has been patched and I know it
will not work on any later clients.
The ORACLE_HOME environment variable should be set correctly.
@@ -1225,22 +1312,20 @@
to load in the Oracle client libraries (via LD_LIBRARY_PATH, ldconfig,
or similar on Unix).
-ORACLE_HOME can be left unset if you are not using any of Oracle's
-executables, but it is I<not> recommended and error messages may not
-display. It should be set to the ORACLE_HOME directory of the version
-of Oracle that DBD::Oracle was compiled with.
+ORACLE_HOME can be left unset if you aren't using any of Oracle's
+executables, but it is I<not> recommended and error messages may not display.
+It should be set to the ORACLE_HOME directory of the version of Oracle
+that DBD::Oracle was compiled with.
Discouraging the use of ORACLE_SID makes it easier on the users to see
-what is going on. (It is unfortunate that TWO_TASK could not be
-renamed, since it makes no sense to the end user, and does not have
-the ORACLE prefix).
-
-Also remember that depending on the operating system you are using the
-various "ORACLE" environment variables may be case sensitive, so if
-you are not connecting as you should double check the case of both the
-variable and its value.
+what is going on. (It's unfortunate that TWO_TASK couldn't be renamed,
+since it makes no sense to the end user, and doesn't have the ORACLE prefix).
+
+Also remember that depending on the operating system you are using
+the differing "ORACLE" environment variables may be case sensitive, so if you are not connecting
+as you should double check the case of both the variable and its value.
-=head2 Connection Examples Using DBD::Oracle
+=head4 Connection Examples Using DBD::Oracle
First, how to connect to a local database I<without> using a Listener:
@@ -1251,7 +1336,7 @@
$dbh = DBI->connect('dbi:Oracle:','scott', 'tiger');
in which case Oracle client code will use the ORACLE_SID environment
-variable (if the TWO_TASK environment variable is not defined).
+variable (if TWO_TASK env var isn't defined).
Below are various ways of connecting to an oracle database using
SQL*Net 1.x and SQL*Net 2.x. "Machine" is the computer the database is
@@ -1291,8 +1376,8 @@
$dbh = DBI->connect('','username/password@DB','');
On the other hand, that may cause you to trip up on another Oracle bug
-that causes alternating connection attempts to fail (in reality only a
-small proportion of people experience these problems.)
+that causes alternating connection attempts to fail! (In reality only
+a small proportion of people experience these problems.)
To connect to a local database with a user which has been set-up to
@@ -1301,63 +1386,53 @@
$dbh = DBI->connect('dbi:Oracle:','/','');
Note the lack of a connection name (use the ORACLE_SID environment
-variable). If an explicit SID is used you will probably get an
-ORA-01004 error.
+variable). If an explicit SID is used you'll probably get an ORA-01004 error.
-That only works for local databases. Authentication to remote Oracle
-databases using your Unix login name without a password is possible
-but it is not secure and not recommended so not documented here. If
-you cannot find the information elsewhere then you probably should not
-be trying to do it.
+That only works for local databases. (Authentication to remote Oracle
+databases using your Unix login name without a password and is possible
+but it's not secure and not recommended so not documented here. If you
+can't find the information elsewhere then you probably shouldn't be
+trying to do it.)
-=head1 CONNECTING TO ORACLE II
+=head4 Connecting to oracle II
-If you are reading this it is assumed that you have successfully
-installed DBD::Oracle and you are having some problems connecting to
-Oracle.
+If you are reading this it is assumed that DBD::Oracle has been successfully installed on you PERL instance and
+you are having some problems connecting to Oracle.
-First off you will have to tell DBD::Oracle where the binaries reside
-for the Oracle client it was compiled against. This is the case when
-you encounter a
+First off you will have to tell DBD::Oracle where the binaries reside for the Oracle client it was compiled against.
+This is the case when you encounter a
- DBI connect('','system',...) failed: ERROR OCIEnvNlsCreate.
-
-error in Linux or in Windows when you get
+ DBI connect('','system',...) failed: ERROR OCIEnvNlsCreate.
+
+error in Linux or in Windows when you get
OCI.DLL not found
-
-The solution to this problem in the case of Linux is to ensure your
-'ORACLE_HOME' (or LD_LIBRARY_PATH for InstantClient) environment
-variable points to the correct directory.
+
+The solution to this problem in the case of Linux is to ensure your 'ORACLE_HOME' environment variable points to the correct directory.
export ORACLE_HOME=/app/oracle/product/xx.x.x
-For Windows the solution is to add this value to you PATH
+For Windows solution is to add this value to you PATH
PATH=c:\app\oracle\product\xx.x.x;%PATH%
-
+
If you get past this stage and get a
- ORA-12154: TNS:could not resolve the connect identifier specified
-
-error then the most likely cause is DBD::ORACLE cannot find your .ORA
-(F<TNSNAMES.ORA>, F<LISTENER.ORA>, F<SQLNET.ORA>) files. This can be
-solved by setting the TNS_ADMIN environment variable to the directory
-where these files can be found.
+ ORA-12154: TNS:could not resolve the connect identifier specified
+
+error then the most likely cause is DBD::ORACLE cannot find your .ORA (TNSNAMES.ORA, LISTENER.ORA, SQLNET.ORA) files. This can be solved by setting the
+TNS_ADMIN environment variable to the directory where these files can be found.
-If you get to this stage and you have either one of the following
-errors;
+If you get to this stage and you then either one of the following errors;
ORA-12560: TNS:protocol adapter error
- ORA-12162: TNS:net service name is incorrectly specified
+ ORA-12162: TNS:net service name is incorrectly specified
-it usually means that DBD::Oracle can find the listener but the it
-cannot connect to the DB because the listener cannot find the DB you
-asked for.
+usually means that DBD::Oracle can find the listener but the it cannot connect to the DB because the listener cannot find the DB you asked for.
-=head2 Connection Examples Using DBD::Oracle
+=head4 Connection Examples Using DBD::Oracle
It is best to not use ORACLE_SID or TWO_TASK as both of these are rather out of date. You are better off keeping it simple like the following examples
@@ -1372,126 +1447,126 @@
For those who really want to use ORACLE_SID and TWO_TASK here are examples of it in use;
-Given this TNS entry:
+Given this TNS entry;
- DB.TEST =
- (DESCRIPTION =
+ DB.TEST =
+ (DESCRIPTION =
(ADDRESS =
(PROTOCOL = TCP)
(HOST = xxx.xxx.xxx.xx)
- (PORT = 1523))
- (CONNECT_DATA = (SID = DB) )
+ (PORT = 1523))
+ (CONNECT_DATA = (SID = DB) )
)
-and this code:
+and this code
BEGIN {
$ENV{ORACLE_SID} = 'DB';
}
-
+
$dbh = DBI->connect('dbi:Oracle:','username/password','');
-
+
you will be able to connect to DB. Note this may not work for Windows.
-TWO_TASK works the same way except it should override the value in
-ORACLE_SID so this:
+TWO_TASK works the same way except it should override the value in ORACLE_SID so this
BEGIN {
$ENV{ORACLE_SID} = 'DB';
$ENV{TWO_TASK} = 'DB.TEST';
-
+
}
-
+
$dbh = DBI->connect('dbi:Oracle:','username/password','');
-
+
will work as well. Note this may not work for Windows.
-=head2 Oracle DRCP
+=head5 Timezones
+
+If TWO_TASK isn't set, Oracle uses the TZ variable from the local environment.
+
+If TWO_TASK IS set, Oracle uses the TZ variable of the listener process
+running on the server.
+
+You could have multiple listeners, each with their own TZ, and assign
+users to the appropriate listener by setting TNS_ADMIN to a directory
+that contains a tnsnames.ora file that points to the port that their
+listener is on.
-DBD::Oracle now supports DRCP (Database Resident Connection Pool) so
-if you have an 11.2 database and DRCP is enabled you can now direct
-all of your connections to it by simply adding ':POOLED' to the SID or
-setting a connection attribute of ora_drcp, or set the SERVER=POOLED
-when using a TNSENTRY style connection or even by setting an
-environment variable ORA_DRCP. All of which are demonstrated below;
+[Brad Howerter, who supplied this info said: "I've done this to simulate
+running a Perl script at the end of the previous month even though it
+was the 6th of the new month. I had the dba start up a listener with
+TZ=X+144. (144 hours = 6 days)"]
+
+=head4 Oracle DRCP
+
+DBD::Oracle now supports DRCP (Database Resident Connection Pool) so if you have an 11.2 database and the DRCP is turned on
+you can now direct all of your connections to it simply adding ':POOLED' to the SID or setting a connection attribute of ora_drcp, or
+set the SERVER=POOLED when using a TNSENTRY style connection or even by setting an environment variable ORA_DRCP.
+All of which are demonstrated below;
$dbh = DBI->connect('dbi:Oracle:DB:POOLED','username','password')
$dbh = DBI->connect('dbi:Oracle:','username@DB:POOLED','password')
-
+
$dbh = DBI->connect('dbi:Oracle:DB','username','password',{ora_drcp=>1})
-
+
$dbh = DBI->connect('dbi:Oracle:DB','username','password',{ora_drcp=>1,
ora_drcp_class=>'my_app',
ora_drcp_min =>10})
-
+
$dbh = DBI->connect('dbi:Oracle:host=foobar;sid=ORCL;port=1521;SERVER=POOLED', 'scott/tiger', '')
$dbh = DBI->connect('dbi:Oracle:', q{scott/tiger@(DESCRIPTION=
(ADDRESS=(PROTOCOL=TCP)(HOST= foobar)(PORT=1521))
(CONNECT_DATA=(SID=ORCL)(SERVER=POOLED)))}, "")
- if ORA_DRCP environment var is set then just this
-
+ if ORA_DRCP environment var is set the just this
+
$dbh = DBI->connect('dbi:Oracle:DB','username','password')
+
+You can find a white paper on setting up DRCP and its advantages here http://www.oracle.com/technology/tech/oci/pdf/oracledrcp11g.pdf
+At this point in time this is just the first crack at DRCP and DBD::Oracle so the mechanics or its implementation are subject to change.
+
+=head4 TAF (Transparent Application Failover)
+
+Transparent Application Failover (TAF) is a longstanding default feature in OCI that allows for clients to automatically reconnect to
+an instance in the event of a failure of the instance. The reconnect happens automatically from within the OCI (Oracle Call Interface) library.
+DBD::Oracle now supports a callback function that will fire when a TAF event takes place. The main use of the callback is to give the
+opportunity for the program to inform the user that a failover is taking place.
-You can find a white paper on setting up DRCP and its advantages at L<http://www.oracle.com/technology/tech/oci/pdf/oracledrcp11g.pdf>.
-
-Please note that DRCP support in DBD::Oracle is relatively new so the
-mechanics or its implementation are subject to change.
-
-=head2 TAF (Transparent Application Failover)
-
-Transparent Application Failover (TAF) is the feature in OCI that
-allows for clients to automatically reconnect to an instance in the
-event of a failure of the instance. The reconnect happens
-automatically from within the OCI (Oracle Call Interface) library.
-DBD::Oracle now supports a callback function that will fire when a TAF
-event takes place. The main use of the callback is to give your
-program the opportunity to inform the user that a failover is taking
-place.
-
-You will have to set up TAF on your instance before you can use this
-callback. You can test your instance to see if you can use TAF
-callback with
+You will have to set up TAF on your instance before you can use this callback. You can test your instance to see if you can use TAF callback with
$dbh->ora_can_taf();
+
+If you try to set up a callback without it being enable DBD::Oracle will croak.
-If you try to set up a callback without it being enabled DBD::Oracle will croak.
-
-It is outside the scope of this documents to go through all of the
-possiable TAF situations you might want to set up but here is a simple
-example:
+It is outside the scope of this documents to go through all of the possible TAF situations you might want to set up. Below is the simplest of examples;
-The TNS entry for the instance has had the following added to the
-CONNECT_DATA section
+The TNS entry for the instance has had the following added to the CONNECT_DATA portion
(FAILOVER_MODE=
- (TYPE=select)
+ (TYPE=select)
(METHOD=basic)
(RETRIES=10)
(DELAY=10))
-You will also have to create your own perl function that will be
-called from the client. You can name it anything you want and it will
-always be passed two parameters, the failover event value and the
-failover type. You can also set a sleep value in case of failover
-error and the OCI client will sleep for the specified seconds before it
-attempts another event.
+You will also have to create your on perl function that will be called from the client. You can name it anything you want and it will always have
+two parameters, the failover event value and the failover type. You can also set a sleep value in case of failover error and the oci client will sleep
+for the entered seconds before it attempts another event.
use DBD::Oracle(qw(:ora_fail_over));
- #import the ora fail over constants
-
+ #import the ora_fail_over constants
+
#set up TAF on the connection
my $dbh = DBI->connect('dbi:Oracle:XE','hr','hr',{ora_taf=>1,taf_sleep=>5,ora_taf_function=>'handle_taft'});
-
- #create the perl TAF event function
-
+
+ #create the perl TAF event function
+
sub handle_taf {
my ($fo_event,$fo_type) = @_;
if ($fo_event == OCI_FO_BEGIN){
-
- print " Instance Unavailable Please stand by!! \n";
+
+ print(" Instance Unavailable Please stand by!! \n");
printf(" Your TAF type is %s \n",
(($fo_type==OCI_FO_NONE) ? "NONE"
:($fo_type==OCI_FO_SESSION) ? "SESSION"
@@ -1499,7 +1574,7 @@
: "UNKNOWN!"));
}
elsif ($fo_event == OCI_FO_ABORT){
- print " Failover aborted. Failover will not take place.\n";
+ printf(" Failover aborted. Failover will not take place.\n");
}
elsif ($fo_event == OCI_FO_END){
printf(" Failover ended ...Resuming your %s\n",(($fo_type==OCI_FO_NONE) ? "NONE"
@@ -1508,24 +1583,24 @@
: "UNKNOWN!"));
}
elsif ($fo_event == OCI_FO_REAUTH){
- print " Failed over user. Resuming services\n";
+ printf(" Failed over user. Resuming services\n");
}
elsif ($fo_event == OCI_FO_ERROR){
- print " Failover error Sleeping...\n";
+ printf(" Failover error Sleeping...\n");
}
else {
printf(" Bad Failover Event: %d.\n", $fo_event);
-
+
}
return 0;
}
The TAF types are as follows
- OCI_FO_SESSION indicates the user has requested only session failover.
- OCI_FO_SELECT indicates the user has requested select failover.
- OCI_FO_NONE indicates the user has not requested a failover type.
- OCI_FO_TXNAL indicates the user has requested a transaction failover.
+ OCI_FO_SESSION which indicates the user has requested only session failover.
+ OCI_FO_SELECT which indicates the user has requested select failover.
+ OCI_FO_NONE which indicates the user has not requested a failover type.
+ OCI_FO_TXNAL which indicates the user has requested a transaction failover.
The TAF events are as follows
@@ -1536,9 +1611,9 @@
OCI_FO_REAUTH indicates that you have multiple authentication handles and failover has occurred after the original authentication. It indicates that a user handle has been re-authenticated. To find out which, the application checks the OCI_ATTR_SESSION attribute of the service context handle (which is the first parameter).
-=head2 Optimizing Oracle's listener
+=head4 Optimizing Oracle's listener
-[By Lane Sharman <[email protected]>] I spent a lot of time optimizing
+[By Lane Sharman <[email protected]>] I spent a LOT of time optimizing
listener.ora and I am including it here for anyone to benefit from. My
connections over tnslistener on the same humble Netra 1 take an average
of 10-20 milli seconds according to tnsping. If anyone knows how to
@@ -1569,7 +1644,7 @@
)
)
-1) When the application is co-located on the host and there is no need for
+1) When the application is co-located on the host AND there is no need for
outside SQLNet connectivity, stop the listener. You do not need it. Get
your application/cgi/whatever working using pipes and shared memory. I am
convinced that this is one of the connection bugs (sockets over the same
@@ -1602,7 +1677,7 @@
my $dbh = DBI->connect("dbi:Oracle:$dbname", $dbuser, $dbpass)
|| die "Unable to connect to $dbname: $DBI::errstr\n";
-=head2 Oracle utilities
+=head4 Oracle utilities
If you are still having problems connecting then the Oracle adapters
utility may offer some help. Run these two commands:
@@ -1618,180 +1693,97 @@
Oracle technical support (and not the dbi-users mailing list). Thanks.
Thanks to Mark Dedlow for this information.
-=head1 Constants
-
-=over 4
-
-=item :ora_session_modes
-
-ORA_SYSDBA ORA_SYSOPER
-
-=item :ora_types
-
- ORA_VARCHAR2 ORA_STRING ORA_NUMBER ORA_LONG ORA_ROWID ORA_DATE ORA_RAW
- ORA_LONGRAW ORA_CHAR ORA_CHARZ ORA_MLSLABEL ORA_XMLTYPE ORA_CLOB ORA_BLOB
- ORA_RSET ORA_VARCHAR2_TABLE ORA_NUMBER_TABLE SQLT_INT SQLT_FLT ORA_OCI
- SQLT_CHR SQLT_BIN
-
-=over 4
-
-=item SQLCS_IMPLICIT
-
-=item SQLCS_NCHAR
-
-SQLCS_IMPLICIT and SQLCS_NCHAR are I<character set form> values.
-See notes about Unicode elsewhere in this document.
-
-=item SQLT_INT
-
-=item SQLT_FLT
-
-These types are used only internally, and may be specified as internal
-bind type for ORA_NUMBER_TABLE. See notes about ORA_NUMBER_TABLE elsewhere
-in this document
-
-=item ORA_OCI
-
-Oracle doesn't provide a formal API for determining the exact version
-number of the OCI client library used, so DBD::Oracle has to go digging
-(and sometimes has to more or less guess). The ORA_OCI constant
-holds the result of that process.
-
-In string context ORA_OCI returns the full "A.B.C.D" version string.
-
-In numeric context ORA_OCI returns the major.minor version number
-(8.1, 9.2, 10.0 etc). But note that version numbers are not actually
-floating point and so if Oracle ever makes a release that has a two
-digit minor version, such as C<9.10> it will have a lower numeric
-value than the preceding C<9.9> release. So use with care.
-
-The contents and format of ORA_OCI are subject to change (it may,
-for example, become a I<version object> in later releases).
-I recommend that you avoid checking for exact values.
-
-=back
-
-=item :ora_fetch_orient
-
- OCI_FETCH_CURRENT OCI_FETCH_NEXT OCI_FETCH_FIRST OCI_FETCH_LAST
- OCI_FETCH_PRIOR OCI_FETCH_ABSOLUTE OCI_FETCH_RELATIVE
+=head3 B<Private Connect Attributes>
-These constants are used to set the orientation of a fetch on a scrollable cursor.
-
-=item :ora_exe_modes
-
- OCI_STMT_SCROLLABLE_READONLY
-
-=item :ora_fail_over
-
- OCI_FO_END OCI_FO_ABORT OCI_FO_REAUTH OCI_FO_BEGIN OCI_FO_ERROR
- OCI_FO_NONE OCI_FO_SESSION OCI_FO_SELECT OCI_FO_TXNAL
-
-=back
-
-=head1 Attributes
-
-=head2 Connect Attributes
-
-=over 4
-
-=item ora_ncs_buff_mtpl
+=head4 ora_ncs_buff_mtpl
You can now customize the size of the buffer when selecting LOBs with
-the built in AUTO Lob. The default value is 4 which is probably
-excessive for most situations but is needed for backward
-compatibility. If you not converting between a NCS on the DB and the
-Client then you might want to set this to 1 to reduce memory usage.
-
-This value can also be specified with the C<ORA_DBD_NCS_BUFFER>
-environment variable in which case it sets the value at the connect
-stage.
+the built in AUTO Lob. The default value is 4 which should is actually excessive
+for most situations but is needed for backward compatibility.
+If you not converting between a NCS on the DB and the Client then you might
+want to set this to 1 to free up memory.
+
+For convenience I have added support for a 'ORA_DBD_NCS_BUFFER'
+environment variable that you can use at the OS level to set this
+value. If used it will take the value at the connect stage.
See more details in the LOB section of the POD
-=item ora_drcp
+=head4 ora_drcp
If you have an 11.2 or greater database your can utilize the DRCP by setting
-this attribute to 1 at connect time.
+this attribute to 1 at connect time.
-This value can also be set with the C<ORA_DRCP> environment variable.
+For convenience I have added support for a 'ORA_DRCP'
+environment variable that you can use at the OS level to set this
+value.
-=item ora_drcp_class
+=head4 ora_drcp_class
-If you are using DRCP, you can set a CONNECTION_CLASS for your pools
-as well. As sessions from a DRCP cannot be shared by users, you can
-use this setting to identify the same user across different
-applications. OCI will ensure that sessions belonging to a 'class' are
-not shared outside the class'.
+If you are using DRCP, you can set a CONNECTION_CLASS for your pools as well.
+As sessions from a DRCP cannot be shared by users, you can use this
+setting to identify the same user across different applications. OCI will ensure that
+session belonging to a 'class' are not shared outside the class'.
-The values for ora_drcp_class cannot contain a '*' and must be less
-than 1024 characters.
+The values for ora_drcp_class cannot contain an '*' and must be less than 1024 characters.
-This value can be also be specified with the C<ORA_DRCP_CLASS>
-environment variable.
+This value can be set at the environment level with 'ORA_DRCP_CLASS'.
-=item ora_drcp_min
+=head4 ora_drcp_min
-This optional value specifies the minimum number of sessions that are
-initially opened. New sessions are only opened after this value has
-been reached.
+Is an optional value that specifies the minimum number of sessions that are initially opened.
+New sessions are only opened after this value has been reached.
-The default value is 4 and any value above 0 is valid.
+The default value is '4' and any value above '0' is valid.
-Generally, it should be set to the number of concurrent statements the
-application is planning or expecting to run.
+Generally, it should be set to the number of concurrent statements the application is planning
+or expecting to run.
-This value can also be specified with the C<ORA_DRCP_MIN> environment
-variable.
+This value can be set at the environment level with 'ORA_DRCP_MIN'.
-=item ora_drcp_max
+=head4 ora_drcp_max
-This optional value specifies the maximum number of sessions that can
-be open at one time. Once reached no more sessions can be opened
-until one becomes free. The default value is 40 and any value above 1
-is valid. You should not set this value lower than ora_drcp_min as
+Is an optional value that specifies the maximum number of sessions that can be open at one time.
+Once reached no more session can be opened until one becomes free. The default value
+is '40' and any value above '1' is valid. You should not set this value lower than ora_drcp_min as
that will just waste resources.
-This value can also be specified with the C<ORA_DRCP_MAX> environment
-variable.
+This value can be set at the environment level with 'ORA_DRCP_MAX'.
-=item ora_drcp_incr
+=head4 ora_drcp_incr
-This optional value specifies the next increment for sessions to be
-started if the current number of sessions are less than
-ora_drcp_max. The default value is 2 and any value above 0 is
-valid as long as the value of ora_drcp_min + ora_drcp_incr is not
-greater than ora_drcp_max.
+Is an optional value that specifies the next increment for sessions to be started if the current number of
+sessions are less than ora_drcp_max. The default value is '2' and any value above '0' is valid as long
+as the value of ora_drcp_min + ora_drcp_incr is not greater than ora_drcp_max.
-This value can also be specified with the C<ORA_DRCP_INCR> environment
-variable.
+This value can be set at the environment level with 'ORA_DRCP_INCR'.
-=item ora_taf
-If your Oracle instance has been configured to use TAF events you can
-enable the TAF callback by setting this value to anything other than 0.
+=head4 ora_taf
-=item ora_taf_function
+If your Oracle instance has been configured to use TAF events you can enable the TAF callback by setting this
+value to anything other than 0;
-The name of the Perl subroutine that will be called from OCI when a
-TAF event occurs. You must supply a perl function to use the callback
-and it will always receive two parameters, the failover event value
-and the failover type. Below is an example of a TAF function
+=head4 ora_taf_function
- sub taf_event{
- my ($event, $type) = @_;
+The name of the Perl that will be called from OCI when a TAF event. You must supply a perl function to use the callback it will
+always have two parameters, the failover event value and the failover type. Below is an example of a TAF function
+ sub taf_event{
+ my ($event,$type)=@_;
+
print "My TAF event=$event\n";
print "My TAF type=$type\n";
return;
}
-=item taf_sleep
+=head4 taf_sleep
+
+A sleep value in seconds that you can sent to the OCI client and when there is a TAF event of the type OCI_FO_ERROR the client
+will sleep that long before it attempts another failover event.
-The amount of time in seconds the OCI client will sleep between attempting
-successive failover events when the event is OCI_FO_ERROR.
-=item ora_session_mode
+=head4 ora_session_mode
The ora_session_mode attribute can be used to connect with SYSDBA
authorization and SYSOPER authorization.
@@ -1811,21 +1803,21 @@
$dbh = DBI->connect($dsn, "", "", { ora_session_mode => ORA_SYSDBA });
-It has been reported that this only works if C<$dsn> does not contain
-a SID so that Oracle then uses the value of ORACLE_SID (not
-TWO_TASK) environment variable to connect to a local instance. Also
-the username and password should be empty, and the user executing the
-script needs to be part of the dba group or osdba group.
+It has been reported that this only works if $dsn does not contain a SID
+so that Oracle then uses the value of the ORACLE_SID (not TWO_TASK)
+environment variable to connect to a local instance. Also the username
+and password should be empty, and the user executing the script needs
+to be part of the dba group or osdba group.
-=item ora_oratab_orahome
+=head4 ora_oratab_orahome
Passing a true value for the ora_oratab_orahome attribute will make
-DBD::Oracle change C<$ENV{ORACLE_HOME}> to make the Oracle home directory
-that specified in the C</etc/oratab> file I<if> the database to connect to
+DBD::Oracle change $ENV{ORACLE_HOME} to make the Oracle home directory
+specified in the C</etc/oratab> file I<if> the database to connect to
is specified as a SID that exists in the oratab file, and DBD::Oracle was
built to use the Oracle 7 OCI API (not Oracle 8+).
-=item ora_module_name
+=head4 ora_module_name
After connecting to the database the value of this attribute is passed
to the SET_MODULE() function in the C<DBMS_APPLICATION_INFO> PL/SQL
@@ -1833,16 +1825,16 @@
monitoring and performance tuning purposes. For example:
my $dbh = DBI->connect($dsn, $user, $passwd, { ora_module_name => $0 });
+
+ $dbh->{ora_module_name} = $y;
- $dbh->{ora_module_name} = $y;
-
-=item ora_driver_name
+=head4 ora_driver_name
For 11g and later you can now set the name of the driver layer using OCI.
-Perl, Perl5, ApachePerl so on. Names starting with "ORA" are reserved. You
+PERL, PERL5, ApachePerl so on. Names starting with "ORA" are reserved. You
can enter up to 8 characters. If none is enter then this will default to
-DBDOxxxx where xxxx is the current version number. This value can be
-retrieved on the server side using V$SESSION_CONNECT_INFO or
+DBDOxxxx where xxxx is the current version number. This value can be
+retrieved on the server side using V$SESSION_CONNECT_INFO or
GV$SESSION_CONNECT_INFO
@@ -1850,53 +1842,51 @@
$dbh->{ora_driver_name} = $q;
-=item ora_client_info
+=head4 ora_client_info
-Allows you to add any value (up to 64 bytes) to your session and it can be
-retrieved on the server side from the C<V$SESSION>a view.
+When passed in on the connection attributes it can specify any info you want
+onto the session up to 64 bytes. This value can be
+retrieved on the server side using V$SESSION view.
my $dbh = DBI->connect($dsn, $user, $passwd, { ora_client_info => 'Remote2' });
$dbh->{ora_client_info} = "Remote2";
-=item ora_client_identifier
-
-Allows you to specify the user identifier in the session handle.
+=head4 ora_client_identifier
-Most useful for web applications as it can pass in the session user
-name which might be different to the connection user name. Can be up
-to 64 bytes long but do not to include the password for security
-reasons and the first character of the identifier should not be
-':'. This value can be retrieved on the server side using C<V$SESSION>
-view.
+When passed in on the connection attributes it specifies the user identifier
+in the session handle. Most useful for web app as it can pass in the session
+user name which might be different than the connection user name. Can be up
+to 64 bytes long do not to include the password for security reasons and the
+first character of the identifier should not be ':'. This value can be
+retrieved on the server side using V$SESSION view.
my $dbh = DBI->connect($dsn, $user, $passwd, { ora_client_identifier => $some_web_user });
$dbh->{ora_client_identifier} = $local_user;
-=item ora_action
+=head4 ora_action
-Allows you to specify any string up to 32 bytes which may be retrieved
-on the server side using C<V$SESSION> view.
+You can set this value to anything you want up to 32 bytes. This value can be
+retrieved on the server side using V$SESSION view.
my $dbh = DBI->connect($dsn, $user, $passwd, { ora_action => "Login"});
-
+
$dbh->{ora_action} = "New Long Query 22";
-=item ora_dbh_share
+=head4 ora_dbh_share
-Requires at least Perl 5.8.0 compiled with ithreads. Allows you to share
-database connections between threads. The first connect will make the
-connection, all following calls to connect with the same ora_dbh_share
-attribute will use the same database connection. The value must be a
-reference to a already shared scalar which is initialized to an empty
-string.
+Needs at least Perl 5.8.0 compiled with ithreads. Allows to share database
+connections between threads. The first connect will make the connection,
+all following calls to connect with the same ora_dbh_share attribute
+will use the same database connection. The value must be a reference
+to a already shared scalar which is initialized to an empty string.
our $orashr : shared = '' ;
$dbh = DBI->connect ($dsn, $user, $passwd, {ora_dbh_share => \$orashr}) ;
-=item ora_envhp
+=head4 ora_envhp
The first time a connection is made a new OCI 'environment' is
created by DBD::Oracle and stored in the driver handle.
@@ -1907,10 +1897,10 @@
environment from a previous connect. If the value is C<0> then
a new OCI environment is allocated and used for this connection.
-The OCI environment holds information about the client side context,
-such as the local NLS environment. By altering C<%ENV> and setting
-ora_envhp to 0 you can create connections with different NLS
-settings. This is most useful for testing.
+The OCI environment is what holds information about the client side
+context, such as the local NLS environment. So by altering %ENV and
+setting ora_envhp to 0 you can create connections with different
+NLS settings. This is most useful for testing.
=item ora_charset, ora_ncharset
@@ -1923,48 +1913,46 @@
$dbh = DBI->connect ($dsn, $user, $passwd,
{ora_charset => 'AL32UTF8'});
-=item ora_verbose
+=head4 ora_verbose
-Use this value to enable DBD::Oracle only tracing. Simply either set
-the ora_verbose attribute on the connect() method to the trace level
-you desire like this
+Use this value to enable DBD::Oracle only tracing. Simply
+either set the ora_verbose attribute on the connect() method to the trace level you desire like this
my $dbh = DBI->connect($dsn, "", "", {ora_verbose=>6});
or set it directly on the DB handle like this;
- $dbh->{ora_verbose} = 6;
+ $dbh->{ora_verbose} =6;
-In both cases the DBD::Oracle trace level to 6, which is the highest
-level tracing most of the calls to OCI.
+In both cases the DBD::Oracle trace level to 6, which is this level that will trace most of the calls to OCI.
-=item ora_oci_success_warn
-Use this value to print otherwise silent OCI warnings that may happen
-when an execute or fetch returns "Success With Info" or when you want
-to tune RowCaching and LOB Reads
+=head4 ora_oci_success_warn
+
+Use this value to print silent OCI warnings that may happen when an execute or fetch returns "Success With Info" or when
+you want to tune RowCaching and LOB Reads
- $dbh->{ora_oci_success_warn} = 1;
+ $dbh->{ora_oci_success_warn} =1;
-=item ora_objects
+=head4 ora_objects
Use this value to enable extended embedded oracle objects mode. In extended:
-=over 8
+=over 4
=item 1
-Embedded objects are returned as <DBD::Oracle::Object> instance (including type-name etc.) instead of simple ARRAY.
+Embedded objects are returned as <DBD::Oracle::Object> instance (including type-name etc.) instead of simple ARRAY.
=item 2
-Determine object type for each instance. All object attributes are returned (not only super-type's attributes).
+Determine object type for each instance. All object attributes are returned (not only super-type's attributes).
-=back
+=back
$dbh->{ora_objects} = 1;
-=item ora_ph_type
+=head4 ora_ph_type
The default placeholder datatype for the database session.
The C<TYPE> or L</ora_type> attributes to L<DBI/bind_param> and
@@ -1988,39 +1976,36 @@
=item ORA_STRING
-Do not strip trailing spaces and end the string at the first \0.
+Don't strip trailing spaces and end the string at the first \0.
=item ORA_CHAR
-Do not strip trailing spaces and allow embedded \0.
+Don't strip trailing spaces and allow embedded \0.
Force 'blank-padded comparison semantics'.
For example:
use DBD::Oracle qw(:ora_types);
-
+
$SQL="select username from all_users where username = ?";
#username is a char(8)
$sth=$dbh->prepare($SQL)";
$sth->bind_param(1,'bloggs',{ ora_type => ORA_CHAR});
-Will pad bloggs out to 8 characters and return the username.
+Will pad bloggs out to 8 characters and return the username.
=back
-=item ora_parse_error_offset
+=head4 ora_parse_error_offset
If the previous error was from a failed C<prepare> due to a syntax error,
this attribute gives the offset into the C<Statement> attribute where the
error was found.
-=back
-
-=over 4
-=item ora_array_chunk_size
+=head4 ora_array_chunk_size
-Due to OCI limitations, DBD::Oracle needs to buffer up rows of
+Because of OCI limitations, DBD::Oracle needs to buffer up rows of
bind values in its C<execute_for_fetch> implementation. This attribute
sets the number of rows to buffer at a time (default value is 1000).
@@ -2032,2683 +2017,3508 @@
Note that this attribute also applies to C<execute_array>, since that
method is implemented using C<execute_for_fetch>.
-=item ora_connect_with_default_signals
+=head4 ora_connect_with_default_signals
-Sometimes the Oracle client seems to change some of the signal
-handlers of the process during the connect phase. For instance, some
-users have observed Perl's default C<$SIG{INT}> handler being ignored
-after connecting to an Oracle database. If this causes problems in
-your application, set this attribute to an array reference of signals
-you would like to be localized during the connect process. Once the
-connect is complete, the signal handlers should be returned to their
-previous state.
+Sometimes the Oracle client seems to change some of the signal handlers
+of the process during the connect phase. For instance, some users have
+observed Perl's default C<$SIG{INT}> handler being ignored after
+connecting to an Oracle database. If this causes problems in your
+application, set this attribute to an array reference of signals you
+would like to be localized during the connect process. Once the connect
+is complete, the signal handlers should be returned to their previous state.
For example:
$dbh = DBI->connect ($dsn, $user, $passwd,
{ora_connect_with_default_signals => [ 'INT' ] });
-NOTE disabling the signal handlers the OCI library sets up may affect
-functionality in the OCI library.
-
=back
-=head2 Prepare Attributes
-These attributes may be used in the C<\%attr> parameter of the
-L<DBI/prepare> database handle method.
+=head3 B<connect_cached>
-=over 4
+Implemented by DBI, no driver-specific impact. Please note that connect_cached as not been tested with DRCP.
-=item ora_placeholders
+=head3 B<data_sources>
-Set to false to disable processing of placeholders. Used mainly for loading a
-PL/SQL package that has been I<wrapped> with Oracle's C<wrap> utility.
+ @data_sources = DBI->data_sources('Oracle');
+ @data_sources = $dbh->data_sources();
-=item ora_parse_lang -->deprecated will be removed in 1.29
+Returns a list of available databases. You will have to set either the 'ORACLE_HOME' or
+'TNS_ADMIN' environment value to retrieve this list. It will read these values from
+TNSNAMES.ORA file entries.
-Tells the connected database how to interpret the SQL statement.
-If 1 (default), the native SQL version for the database is used.
-Other recognized values are 0 (old V6, treated as V7 in OCI8),
-2 (old V7), 7 (V7), and 8 (V8).
-All other values have the same effect as 1.
-=item ora_auto_lob
-If true (the default), fetching retrieves the contents of the CLOB or
-BLOB column in most circumstances. If false, fetching retrieves the
-Oracle "LOB Locator" of the CLOB or BLOB value.
-See L</LOBs and LONGs> for more details.
+=head2 Methods Common To All Handles
-See also the LOB tests in 05dbi.t of Oracle::OCI for examples
-of how to use LOB Locators.
+For all of the methods below, B<$h> can be either a database handle (B<$dbh>)
+or a statement handle (B<$sth>). Note that I<$dbh> and I<$sth> can be replaced with
+any variable name you choose: these are just the names most often used. Another
+common variable used in this documentation is $I<rv>, which stands for "return value".
-=item ora_pers_lob
+=head3 B<err>
-If true the L</Simple Fetch for CLOBs and BLOBs> method for the L</Data Interface for Persistent LOBs> will be
-used for LOBs rather than the default method L</Data Interface for LOB Locators>.
+ $rv = $h->err;
-=item ora_clbk_lob
+Returns the error code from the last method called.
-If true the L</Piecewise Fetch with Callback> method for the L</Data
-Interface for Persistent LOBs> will be used for LOBs.
+=head3 B<errstr>
-=item ora_piece_lob
+ $str = $h->errstr;
-If true the L</Piecewise Fetch with Polling> method for the L</Data
-Interface for Persistent LOBs> will be used for LOBs.
+Returns the last error that was reported by Oracle. Starting with "ORA-00000" code followed by the error message.
-=item ora_piece_size
+=head3 B<state>
-This is the max piece size for the L</Piecewise Fetch with Callback>
-and L</Piecewise Fetch with Polling> methods, in chars for CLOBS, and
-bytes for BLOBS.
+ $str = $h->state;
+
+Oracle hasn't supported SQLSTATE since the early versions OCI. It will return empty when the command succeeds and
+'S1000' (General Error) for all other errors.
-=item ora_check_sql
+While this method can be called as either C<< $sth->state >> or C<< $dbh->state >>, it
+is usually clearer to always use C<< $dbh->state >>.
-If 1 (default), force SELECT statements to be described in prepare().
-If 0, allow SELECT statements to defer describe until execute().
+=head3 B<trace>
-See L</Prepare postponed until execute> for more information.
+Implemented by DBI, no driver-specific impact.
-=item ora_exe_mode
+=head3 B<trace_msg>
-This will set the execute mode of the current statement. Presently
-only one mode is supported;
+Implemented by DBI, no driver-specific impact.
- OCI_STMT_SCROLLABLE_READONLY - make result set scrollable
+=head3 B<parse_trace_flag> and B<parse_trace_flags>
-See L</Scrollable Cursors> for more details.
+Implemented by DBI, no driver-specific impact.
-=item ora_prefetch_rows
+=head3 B<func>
-Sets the number of rows to be prefetched. If it is not set, then the
-default value is 1. See L</Row Prefetching> for more details.
+DBD::Oracle uses the C<func> method to support a variety of functions.
-=item ora_prefetch_memory
+=head3 B<Private database handle functions>
-Sets the memory level for rows to be prefetched. The application then
-fetches as many rows as will fit into that much memory. See L</Row
-Prefetching> for more details.
+Some of these functions are called through the method func()
+which is described in the DBI documentation. Any function that begins with ora_
+can be called directly.
-=item ora_row_cache_off
+=head3 B<plsql_errstr>
-By default DBD::Oracle will use a row cache when fetching to cut down
-the number of round trips to the server. If you do not want to use an
-array fetch set this value to any value other than 0;
+This function returns a string which describes the errors
+from the most recent PL/SQL function, procedure, package,
+or package body compile in a format similar to the output
+of the SQL*Plus command 'show errors'.
-See L</Prefetching Rows> for more details.
+The function returns undef if the error string could not
+be retrieved due to a database error.
+Look in $dbh->errstr for the cause of the failure.
-=back
+If there are no compile errors, an empty string is returned.
-=head2 Placeholder Binding Attributes
+Example:
-These attributes may be used in the C<\%attr> parameter of the
-L<DBI/bind_param> or L<DBI/bind_param_inout> statement handle methods.
+ # Show the errors if CREATE PROCEDURE fails
+ $dbh->{RaiseError} = 0;
+ if ( $dbh->do( q{
+ CREATE OR REPLACE PROCEDURE perl_dbd_oracle_test as
+ BEGIN
+ PROCEDURE filltab( stuff OUT TAB ); asdf
+ END; } ) ) {} # Statement succeeded
+ }
+ elsif ( 6550 != $dbh->err ) { die $dbh->errstr; } # Utter failure
+ else {
+ my $msg = $dbh->func( 'plsql_errstr' );
+ die $dbh->errstr if ! defined $msg;
+ die $msg if $msg;
+ }
-=over 4
+=head3 B<dbms_output_enable / dbms_output_put / dbms_output_get>
-=item ora_type
+These functions use the PL/SQL DBMS_OUTPUT package to store and
+retrieve text using the DBMS_OUTPUT buffer. Text stored in this buffer
+by dbms_output_put or any PL/SQL block can be retrieved by
+dbms_output_get or any PL/SQL block connected to the same database
+session.
-Specify the placeholder's datatype using an Oracle datatype.
-A fatal error is raised if C<ora_type> and the DBI C<TYPE> attribute
-are used for the same placeholder.
-Some of these types are not supported by the current version of
-DBD::Oracle and will cause a fatal error if used.
-Constants for the Oracle datatypes may be imported using
+Stored text is not available until after dbms_output_put or the PL/SQL
+block that saved it completes its execution. This means you B<CAN NOT>
+use these functions to monitor long running PL/SQL procedures.
- use DBD::Oracle qw(:ora_types);
+Example 1:
-Potentially useful values when DBD::Oracle was built using OCI 7 and later:
+ # Enable DBMS_OUTPUT and set the buffer size
+ $dbh->{RaiseError} = 1;
+ $dbh->func( 1000000, 'dbms_output_enable' );
- ORA_VARCHAR2, ORA_STRING, ORA_LONG, ORA_RAW, ORA_LONGRAW,
- ORA_CHAR, ORA_MLSLABEL, ORA_RSET
+ # Put text in the buffer . . .
+ $dbh->func( @text, 'dbms_output_put' );
-Additional values when DBD::Oracle was built using OCI 8 and later:
+ # . . . and retrieve it later
+ @text = $dbh->func( 'dbms_output_get' );
- ORA_CLOB, ORA_BLOB, ORA_XMLTYPE, ORA_VARCHAR2_TABLE, ORA_NUMBER_TABLE
+Example 2:
-Additional values when DBD::Oracle was built using OCI 9.2 and later:
+ $dbh->{RaiseError} = 1;
+ $sth = $dbh->prepare(q{
+ DECLARE tmp VARCHAR2(50);
+ BEGIN
+ SELECT SYSDATE INTO tmp FROM DUAL;
+ dbms_output.put_line('The date is '||tmp);
+ END;
+ });
+ $sth->execute;
- SQLT_CHR, SQLT_BIN
+ # retrieve the string
+ $date_string = $dbh->func( 'dbms_output_get' );
-See L</Binding Cursors> for the correct way to use ORA_RSET.
+=head3 B<dbms_output_enable ( [ buffer_size ] )>
-See L</LOBs and LONGs> for how to use ORA_CLOB and ORA_BLOB.
+This function calls DBMS_OUTPUT.ENABLE to enable calls to package
+DBMS_OUTPUT procedures GET, GET_LINE, PUT, and PUT_LINE. Calls to
+these procedures are ignored unless DBMS_OUTPUT.ENABLE is called
+first.
-See L</SYS.DBMS_SQL datatypes> for ORA_VARCHAR2_TABLE, ORA_NUMBER_TABLE.
+The buffer_size is the maximum amount of text that can be saved in the
+buffer and must be between 2000 and 1,000,000. If buffer_size is not
+given, the default is 20,000 bytes.
-See L</Data Interface for Persistent LOBs> for the correct way to use SQLT_CHR and SQLT_BIN.
+=head3 B<dbms_output_put ( [ @lines ] )>
-See L</Other Data Types> for more information.
+This function calls DBMS_OUTPUT.PUT_LINE to add lines to the buffer.
-See also L<DBI/Placeholders and Bind Values>.
+If all lines were saved successfully the function returns 1. Depending
+on the context, an empty list or undef is returned for failure.
-=item ora_csform
+If any line causes buffer_size to be exceeded, a buffer overflow error
+is raised and the function call fails. Some of the text might be in
+the buffer.
-Specify the OCI_ATTR_CHARSET_FORM for the bind value. Valid values
-are SQLCS_IMPLICIT (1) and SQLCS_NCHAR (2). Both those constants can
-be imported from the DBD::Oracle module. Rarely needed.
+=head3 B<dbms_output_get>
-=item ora_csid
+This function calls DBMS_OUTPUT.GET_LINE to retrieve lines of text from
+the buffer.
-Specify the I<integer> OCI_ATTR_CHARSET_ID for the bind value.
-Character set names can't be used currently.
+In an array context, all complete lines are removed from the buffer and
+returned as a list. If there are no complete lines, an empty list is
+returned.
-=item ora_maxdata_size
+In a scalar context, the first complete line is removed from the buffer
+and returned. If there are no complete lines, undef is returned.
-Specify the integer OCI_ATTR_MAXDATA_SIZE for the bind value.
-May be needed if a character set conversion from client to server
-causes the data to use more space and so fail with a truncation error.
+Any text in the buffer after a call to DBMS_OUTPUT.GET_LINE or
+DBMS_OUTPUT.GET is discarded by the next call to DBMS_OUTPUT.PUT_LINE,
+DBMS_OUTPUT.PUT, or DBMS_OUTPUT.NEW_LINE.
-=item ora_maxarray_numentries
+=head3 B<reauthenticate ( $username, $password )>
-Specify the maximum number of array entries to allocate. Used with
-ORA_VARCHAR2_TABLE, ORA_NUMBER_TABLE. Define the maximum number of
-array entries Oracle can pass back to you in OUT variable of type
-TABLE OF ... .
+Starts a new session against the current database using the credentials
+supplied.
-=item ora_internal_type
-Specify internal data representation. Currently is supported only for
-ORA_NUMBER_TABLE.
+=head3 B<private_attribute_info>
-=back
+ $hashref = $dbh->private_attribute_info();
+ $hashref = $sth->private_attribute_info();
-=head1 Optimizing Results
+Returns a hash of all private attributes used by DBD::Oracle, for either
+a database or a statement handle. Currently, all the hash values are undef.
-=head2 Prepare postponed till execute
+=head2 Attributes Common To All Handles
-The DBD::Oracle module can avoid an explicit 'describe' operation
-prior to the execution of the statement unless the application requests
-information about the results (such as $sth->{NAME}). This reduces
-communication with the server and increases performance (reducing the
-number of PARSE_CALLS inside the server).
+=head3 B<InactiveDestroy> (boolean)
-However, it also means that SQL errors are not detected until
-C<execute()> (or $sth->{NAME} etc) is called instead of when
-C<prepare()> is called. Note that if the describe is triggered by the
-use of $sth->{NAME} or a similar attribute and the describe fails then
-I<an exception is thrown> even if C<RaiseError> is false!
+Implemented by DBI, no driver-specific impact.
-Set L</ora_check_sql> to 0 in prepare() to enable this behaviour.
+=head3 B<RaiseError> (boolean, inherited)
-=head1 Prefetching and Row Caching
+Forces errors to always raise an exception. Although it defaults to off, it is recommended that this
+be turned on, as the alternative is to check the return value of every method (prepare, execute, fetch, etc.)
+manually, which is easy to forget to do.
-DBD::Oracle now supports both Server pre-fetch and Client side row caching. By default both
-are turned on to give optimum performance. Most of the time one can just let DBD::Oracle
-figure out the best optimization.
+=head3 B<PrintError> (boolean, inherited)
-=head2 Row Caching
+Forces database errors to also generate warnings, which can then be filtered with methods such as
+locally redefining I<$SIG{__WARN__}> or using modules such as C<CGI::Carp>. This attribute is on
+by default.
-Row caching occurs on the client side and the object of it is to cut down the number of round
-trips made to the server when fetching rows. At each fetch a set number of rows will be retrieved
-from the server and stored locally. Further calls the server are made only when the end of the
-local buffer(cache) is reached.
+=head3 B<ShowErrorStatement> (boolean, inherited)
-Rows up to the specified top level row
-count C<RowCacheSize> are fetched if it occupies no more than the specified memory usage limit.
-The default value is 0, which means that memory size is not included in computing the number of rows to prefetch. If
-the C<RowCacheSize> value is set to a negative number then the positive value of RowCacheSize is used
-to compute the number of rows to prefetch.
+Appends information about the current statement to error messages. If placeholder information
+is available, adds that as well. Defaults to true.
-By default C<RowCacheSize> is automatically set. If you want to totally turn off prefetching set this to 1.
+=head3 B<Warn> (boolean, inherited)
-For any SQL statement that contains a LOB, Long or Object Type Row Caching will be turned off. However server side
-caching still works. If you are only selecting a LOB Locator then Row Caching will still work.
+Enables warnings. This is on by default, and should only be turned off in a local block
+for a short a time only when absolutely needed.
-=head2 Row Prefetching
+=head3 B<Executed> (boolean, read-only)
-Row prefetching occurs on the server side and uses the DBI database handle attribute C<RowCacheSize> and or the
-Prepare Attribute 'ora_prefetch_memory'. Tweaking these values may yield improved performance.
+Indicates if a handle has been executed. For database handles, this value is true after the L</do> method has been called, or
+when one of the child statement handles has issued an L</execute>. Issuing a L</commit> or L</rollback> always resets the
+attribute to false for database handles. For statement handles, any call to L</execute> or its variants will flip the value to
+true for the lifetime of the statement handle.
- $dbh->{RowCacheSize} = 100;
- $sth=$dbh->prepare($SQL,{ora_exe_mode=>OCI_STMT_SCROLLABLE_READONLY,ora_prefetch_memory=>10000});
+=head3 B<TraceLevel> (integer, inherited)
-In the above example 10 rows will be prefetched up to a maximum of 10000 bytes of data. The Oracle® Call Interface Programmer's Guide,
-suggests a good row cache value for a scrollable cursor is about 20% of expected size of the record set.
+Sets the trace level, similar to the L</trace> method. See the sections on
+L</trace> and L</parse_trace_flag> for more details.
-The prefetch settings tell the DBD::Oracle to grab x rows (or x-bytes) when it needs to get new rows. This happens on the first
-fetch that sets the current_positon to any value other than 0. In the above example if we do a OCI_FETCH_FIRST the first 10 rows are
-loaded into the buffer and DBD::Oracle will not have to go back to the server for more rows. When record 11 is fetched DBD::Oracle
-fetches and returns this row and the next 9 rows are loaded into the buffer. In this case if you fetch backwards from 10 to 1
-no server round trips are made.
+=head3 B<Active> (boolean, read-only)
-With large record sets it is best not to attempt to go to the last record as this may take some time, A large buffer size might even slow down
-the fetch. If you must get the number of rows in a large record set you might try using an few large OCI_FETCH_ABSOLUTEs and then an OCI_FETCH_LAST,
-this might save some time. So if you had a record set of 10000 rows and you set the buffer to 5000 and did a OCI_FETCH_LAST one would fetch the first 5000 rows into the buffer then the next 5000 rows.
-If one requires only the first few rows there is no need to set a large prefetch value.
+Indicates if a handle is active or not. For database handles, this indicates if the database has
+been disconnected or not. For statement handles, it indicates if all the data has been fetched yet
+or not. Use of this attribute is not encouraged.
-If the ora_prefetch_memory less than 1 or not present then memory size is not included in computing the
-number of rows to prefetch otherwise the number of rows will be limited to memory size. Likewise if the RowCacheSize is less than 1 it
-is not included in the computing of the prefetch rows.
+=head3 B<Kids> (integer, read-only)
-=head1 Spaces & Padding
+Returns the number of child processes created for each handle type. For a driver handle, indicates the number
+of database handles created. For a database handle, indicates the number of statement handles created. For
+statement handles, it always returns zero, because statement handles do not create kids.
-=head2 Trailing Spaces
+=head3 B<ActiveKids> (integer, read-only)
-Please note that only the Oracle OCI 8 strips trailing spaces from VARCHAR placeholder
-values and uses Nonpadded Comparison Semantics with the result.
-This causes trouble if the spaces are needed for
-comparison with a CHAR value or to prevent the value from
-becoming '' which Oracle treats as NULL.
-Look for Blank-padded Comparison Semantics and Nonpadded
-Comparison Semantics in Oracle's SQL Reference or Server
-SQL Reference for more details.
+Same as C<Kids>, but only returns those that are active.
-To preserve trailing spaces in placeholder values for Oracle clients that use OCI 8,
-either change the default placeholder type with L</ora_ph_type> or the placeholder
-type for a particular call to L<DBI/bind> or L<DBI/bind_param_inout>
-with L</ora_type> or C<TYPE>.
-Using L<ORA_CHAR> with L<ora_type> or C<SQL_CHAR> with C<TYPE>
-allows the placeholder to be used with Padded Comparison Semantics
-if the value it is being compared to is a CHAR, NCHAR, or literal.
+=head3 B<CachedKids> (hash ref)
-Please remember that using spaces as a value or at the end of
-a value makes visually distinguishing values with different
-numbers of spaces difficult and should be avoided.
+Returns a hashref of handles. If called on a database handle, returns all statement handles created by use of the
+C<prepare_cached> method. If called on a driver handle, returns all database handles created by the L</connect_cached>
+method.
-Oracle Clients that use OCI 9.2 do not strip trailing spaces.
+=head3 B<ChildHandles> (array ref)
-=head2 Padded Char Fields
+Implemented by DBI, no driver-specific impact.
-Oracle Clients after OCI 9.2 will automatically pad CHAR placeholder values to the size of the CHAR.
-As the default placeholder type value in DBD::Oracle is ORA_VARCHAR2 to access this behaviour you will
-have to change the default placeholder type with L</ora_ph_type> or placeholder
-type for a particular call with L<DBI/bind> or L<DBI/bind_param_inout>
-with L</ORA_CHAR>.
+=head3 B<PrintWarn> (boolean, inherited)
-=head1 Metadata
+Implemented by DBI, no driver-specific impact.
-=head2 C<get_info()>
+=head3 B<HandleError> (boolean, inherited)
-DBD::Oracle supports C<get_info()>, but (currently) only a few info types.
+Implemented by DBI, no driver-specific impact.
-=head2 C<table_info()>
+=head3 B<HandleSetErr> (code ref, inherited)
-DBD::Oracle supports attributes for C<table_info()>.
+Implemented by DBI, no driver-specific impact.
-In Oracle, the concept of I<user> and I<schema> is (currently) the
-same. Because database objects are owned by an user, the owner names
-in the data dictionary views correspond to schema names.
-Oracle does not support catalogs so TABLE_CAT is ignored as
-selection criterion.
+=head3 B<ErrCount> (unsigned integer)
-Search patterns are supported for TABLE_SCHEM and TABLE_NAME.
+Implemented by DBI, no driver-specific impact.
-TABLE_TYPE may contain a comma-separated list of table types.
-The following table types are supported:
+=head3 B<FetchHashKeyName> (string, inherited)
- TABLE
- VIEW
- SYNONYM
- SEQUENCE
+Implemented by DBI, no driver-specific impact.
-The result set is ordered by TABLE_TYPE, TABLE_SCHEM, TABLE_NAME.
+=head3 B<ChopBlanks> (boolean, inherited)
-The special enumerations of catalogs, schemas and table types are
-supported. However, TABLE_CAT is always NULL.
+Implemented by DBI, no driver-specific impact.
-An identifier is passed I<as is>, i.e. as the user provides or
-Oracle returns it.
-C<table_info()> performs a case-sensitive search. So, a selection
-criterion should respect upper and lower case.
-Normally, an identifier is case-insensitive. Oracle stores and
-returns it in upper case. Sometimes, database objects are created
-with quoted identifiers (for reserved words, mixed case, special
-characters, ...). Such an identifier is case-sensitive (if not all
-upper case). Oracle stores and returns it as given.
-C<table_info()> has no special quote handling, neither adds nor
-removes quotes.
+=head3 B<Taint> (boolean, inherited)
-=head2 C<primary_key_info()>
+Implemented by DBI, no driver-specific impact.
-Oracle does not support catalogs so TABLE_CAT is ignored as
-selection criterion.
-The TABLE_CAT field of a fetched row is always NULL (undef).
-See L</table_info()> for more detailed information.
+=head3 B<TaintIn> (boolean, inherited)
-If the primary key constraint was created without an identifier,
-PK_NAME contains a system generated name with the form SYS_Cn.
+Implemented by DBI, no driver-specific impact.
-The result set is ordered by TABLE_SCHEM, TABLE_NAME, KEY_SEQ.
+=head3 B<TaintOut> (boolean, inherited)
-An identifier is passed I<as is>, i.e. as the user provides or
-Oracle returns it.
-See L</table_info()> for more detailed information.
+Implemented by DBI, no driver-specific impact.
-=head2 C<foreign_key_info()>
+=head3 B<Profile> (inherited)
-This method (currently) supports the extended behaviour of SQL/CLI, i.e. the
-result set contains foreign keys that refer to primary B<and> alternate keys.
-The field UNIQUE_OR_PRIMARY distinguishes these keys.
+Implemented by DBI, no driver-specific impact.
-Oracle does not support catalogs, so C<$pk_catalog> and C<$fk_catalog> are
-ignored as selection criteria (in the new style interface).
-The UK_TABLE_CAT and FK_TABLE_CAT fields of a fetched row are always
-NULL (undef).
-See L</table_info()> for more detailed information.
+=head3 B<Type> (scalar)
-If the primary or foreign key constraints were created without an identifier,
-UK_NAME or FK_NAME contains a system generated name with the form SYS_Cn.
+Returns C<dr> for a driver handle, C<db> for a database handle, and C<st> for a statement handle.
+Should be rarely needed.
-The UPDATE_RULE field is always 3 ('NO ACTION'), because Oracle (currently)
-does not support other actions.
+=head3 B<LongReadLen>
-The DELETE_RULE field may contain wrong values. This is a known Bug (#1271663)
-in Oracle's data dictionary views. Currently (as of 8.1.7), 'RESTRICT' and
-'SET DEFAULT' are not supported, 'CASCADE' is mapped correctly and all other
-actions (incl. 'SET NULL') appear as 'NO ACTION'.
+Implemented by DBI, no driver-specific impact.
-The DEFERABILITY field is always NULL, because this columns is
-not present in the ALL_CONSTRAINTS view of older Oracle releases.
+=head3 B<LongTruncOk>
-The result set is ordered by UK_TABLE_SCHEM, UK_TABLE_NAME, FK_TABLE_SCHEM,
-FK_TABLE_NAME, ORDINAL_POSITION.
+Implemented by DBI, no driver-specific impact.
-An identifier is passed I<as is>, i.e. as the user provides or
-Oracle returns it.
-See L</table_info()> for more detailed information.
-=head2 C<column_info()>
+=head3 B<CompatMode>
-Oracle does not support catalogs so TABLE_CAT is ignored as
-selection criterion.
-The TABLE_CAT field of a fetched row is always NULL (undef).
-See L</table_info()> for more detailed information.
+Type: boolean, inherited
-The CHAR_OCTET_LENGTH field is (currently) always NULL (undef).
+The CompatMode attribute is used by emulation layers (such as Oraperl) to enable compatible behaviour in the underlying driver (e.g., DBD::Oracle) for this handle. Not normally set by application code.
-Don't rely on the values of the BUFFER_LENGTH field!
-Especially the length of FLOATs may be wrong.
+It also has the effect of disabling the 'quick FETCH' of attribute values from the handles attribute cache. So all attribute values are handled by the drivers own FETCH method. This makes them slightly slower but is useful for special-purpose drivers like DBD::Multiplex.
-Datatype codes for non-standard types are subject to change.
-Attention! The DATA_DEFAULT (COLUMN_DEF) column is of type LONG.
+=head1 DBI Database Handle Object
-The result set is ordered by TABLE_SCHEM, TABLE_NAME, ORDINAL_POSITION.
+=head2 Database Handle Methods
-An identifier is passed I<as is>, i.e. as the user provides or
-Oracle returns it.
-See L</table_info()> for more detailed information.
+=head3 B<selectall_arrayref>
-It is possible with Oracle to make the names of the various DB objects (table,column,index etc)
-case sensitive.
+ $ary_ref = $dbh->selectall_arrayref($sql);
+ $ary_ref = $dbh->selectall_arrayref($sql, \%attr);
+ $ary_ref = $dbh->selectall_arrayref($sql, \%attr, @bind_values);
- alter table bloggind add ("Bla_BLA" NUMBER)
+Returns a reference to an array containing the rows returned by preparing and executing the SQL string.
+See the DBI documentation for full details.
-So in the example the exact case "Bla_BLA" must be used to get it info on the column. While this
+=head3 B<selectall_hashref>
- alter table bloggind add (Bla_BLA NUMBER)
+ $hash_ref = $dbh->selectall_hashref($sql, $key_field);
-any case can be used to get info on the column.
+Returns a reference to a hash containing the rows returned by preparing and executing the SQL string.
+See the DBI documentation for full details.
-=head1 Unicode
+=head3 B<selectcol_arrayref>
-DBD::Oracle now supports Unicode UTF-8. There are, however, a number
-of issues you should be aware of, so please read all this section
-carefully.
+ $ary_ref = $dbh->selectcol_arrayref($sql, \%attr, @bind_values);
-In this section we'll discuss "Perl and Unicode", then "Oracle and
-Unicode", and finally "DBD::Oracle and Unicode".
+Returns a reference to an array containing the first column
+from each rows returned by preparing and executing the SQL string. It is possible to specify exactly
+which columns to return. See the DBI documentation for full details.
-Information about Unicode in general can be found at:
-L<http://www.unicode.org/>. It is well worth reading because there are
-many misconceptions about Unicode and you may be holding some of them.
+=head3 B<prepare>
-=head2 Perl and Unicode
+ $sth = $dbh->prepare($statement, \%attr);
-Perl began implementing Unicode with version 5.6, but the implementation
-did not mature until version 5.8 and later. If you plan to use Unicode
-you are I<strongly> urged to use Perl 5.8.2 or later and to I<carefully> read
-the Perl documentation on Unicode:
+Prepares a statement for later execution by the database engine and returns a reference to a statement handle object.
- perldoc perluniintro # in Perl 5.8 or later
- perldoc perlunicode
+=head4 B<Prepare Attributes>
-And then read it again.
+These attributes may be used in the C<\%attr> parameter of the
+L<DBI/prepare> database handle method in addition to the standard DBI prepare Attributes.
-Perl's internal Unicode format is UTF-8
-which corresponds to the Oracle character set called AL32UTF8.
+=over 4
-=head2 Oracle and Unicode
+=item ora_placeholders
-Oracle supports many characters sets, including several different forms
-of Unicode. These include:
+Set to false to disable processing of placeholders. Used mainly for loading a
+PL/SQL package that has been I<wrapped> with Oracle's C<wrap> utility.
- AL16UTF16 => valid for NCHAR columns (CSID=2000)
- UTF8 => valid for NCHAR columns (CSID=871), deprecated
- AL32UTF8 => valid for NCHAR and CHAR columns (CSID=873)
+=item ora_auto_lob
-When you create an Oracle database, you must specify the DATABASE
-character set (used for DDL, DML and CHAR datatypes) and the NATIONAL
-character set (used for NCHAR and NCLOB types).
-The character sets used in your database can be found using:
+If true (the default), fetching retrieves the contents of the CLOB or
+BLOB column in most circumstances. If false, fetching retrieves the
+Oracle "LOB Locator" of the CLOB or BLOB value.
- $hash_ref = $dbh->ora_nls_parameters()
- $database_charset = $hash_ref->{NLS_CHARACTERSET};
- $national_charset = $hash_ref->{NLS_NCHAR_CHARACTERSET};
+See L</LOBs and LONGs> for more details.
+See also the LOB tests in 05dbi.t of Oracle::OCI for examples
+of how to use LOB Locators.
-The Oracle 9.2 and later default for the national character set is AL16UTF16.
-The default for the database character set is often US7ASCII.
-Although many experienced DBAs will consider an 8bit character set like
-WE8ISO8859P1 or WE8MSWIN1252. To use any character set with Oracle
-other than US7ASCII, requires that the NLS_LANG environment variable be set.
-See the L<"Oracle UTF8 is not UTF-8"> section below.
+=item ora_pers_lob
+If true the L</Simple Fetch for CLOBs and BLOBs> method for the L</Data Interface for Persistent LOBs> will be
+used for LOBs rather than the default method L</Data Interface for LOB Locators>.
-You are strongly urged to read the Oracle Internationalization documentation
-specifically with respect the choices and trade offs for creating
-a databases for use with international character sets.
+=item ora_clbk_lob
-Oracle uses the NLS_LANG environment variable to indicate what
-character set is being used on the client. When fetching data Oracle
-will convert from whatever the database character set is to the client
-character set specified by NLS_LANG. Similarly, when sending data to
-the database Oracle will convert from the character set specified by
-NLS_LANG to the database character set.
+If true the L</Piecewise Fetch with Callback> method for the L</Data Interface for Persistent LOBs> will be
+used for LOBs.
-The NLS_NCHAR environment variable can be used to define a different
-character set for 'national' (NCHAR) character types.
+=item ora_piece_lob
-Both UTF8 and AL32UTF8 can be used in NLS_LANG and NLS_NCHAR.
-For example:
+If true the L</Piecewise Fetch with Polling> method for the L</Data Interface for Persistent LOBs> will be
+used for LOBs.
- NLS_LANG=AMERICAN_AMERICA.UTF8
- NLS_LANG=AMERICAN_AMERICA.AL32UTF8
- NLS_NCHAR=UTF8
- NLS_NCHAR=AL32UTF8
+=item ora_piece_size
-=head2 Oracle UTF8 is not UTF-8
+This is the max piece size for the L</Piecewise Fetch with Callback> and L</Piecewise Fetch with Polling> methods, in chars for CLOBS,
+and bytes for BLOBS.
-AL32UTF8 should be used in preference to UTF8 if it works for you,
-which it should for Oracle 9.2 or later. If you're using an old
-version of Oracle that doesn't support AL32UTF8 then you should
-avoid using any Unicode characters that require surrogates, in other
-words characters beyond the Unicode BMP (Basic Multilingual Plane).
+=item ora_check_sql
-That's because the character set that Oracle calls "UTF8" doesn't
-conform to the UTF-8 standard in its handling of surrogate characters.
-Technically the encoding that Oracle calls "UTF8" is known as "CESU-8".
-Here are a couple of extracts from L<http://www.unicode.org/reports/tr26/>:
+If 1 (default), force SELECT statements to be described in prepare().
+If 0, allow SELECT statements to defer describe until execute().
- CESU-8 is useful in 8-bit processing environments where binary
- collation with UTF-16 is required. It is designed and recommended
- for use only within products requiring this UTF-16 binary collation
- equivalence. It is not intended nor recommended for open interchange.
+See L</Prepare postponed till execute> for more information.
- As a very small percentage of characters in a typical data stream
- are expected to be supplementary characters, there is a strong
- possibility that CESU-8 data may be misinterpreted as UTF-8.
- Therefore, all use of CESU-8 outside closed implementations is
- strongly discouraged, such as the emittance of CESU-8 in output
- files, markup language or other open transmission forms.
+=item ora_exe_mode
-Oracle uses this internally because it collates (sorts) in the same order
-as UTF16, which is the basis of Oracle's internal collation definitions.
+This will set the execute mode of the current statement. Presently only one mode is supported;
-Rather than change UTF8 for clients Oracle chose to define a new character
-set called "AL32UTF8" which does conform to the UTF-8 standard.
-(The AL32UTF8 character set can't be used on the server because it
-would break collation.)
+ OCI_STMT_SCROLLABLE_READONLY - make result set scrollable
-Because of that, for the rest of this document we'll use "AL32UTF8".
-If you're using an Oracle version below 9.2 you'll need to use "UTF8"
-until you upgrade.
+See L</Scrollable Cursors> for more details.
-=head2 DBD::Oracle and Unicode
+=item ora_prefetch_rows
-DBD::Oracle Unicode support has been implemented for Oracle versions 9
-or greater, and Perl version 5.6 or greater (though we I<strongly>
-suggest that you use Perl 5.8.2 or later).
+Sets the number of rows to be prefetched. If it is not set, then the default value is 1.
+See L</Row Prefetching> for more details.
-You can check which Oracle version your DBD::Oracle was built with by
-importing the C<ORA_OCI> constant from DBD::Oracle.
+=item ora_prefetch_memory
-B<Fetching Data>
+Sets the memory level for rows to be prefetched. The application then fetches as many rows as will fit into that much memory.
+See L</Row Prefetching> for more details.
-Any data returned from Oracle to DBD::Oracle in the AL32UTF8
-character set will be marked as UTF-8 to ensure correct handling by Perl.
+=item ora_row_cache_off
-For Oracle to return data in the AL32UTF8 character set the
-NLS_LANG or NLS_NCHAR environment variable I<must> be set as described
-in the previous section.
+By default DBD::Oracle will use a row cache when fetching to cut down the number of round
+trips to the server. If you do not want to use an array fetch set this value to any value other than 0;
+See L</Prefetching Rows> for more details.
-When fetching NCHAR, NVARCHAR, or NCLOB data from Oracle, DBD::Oracle
-will set the Perl UTF-8 flag on the returned data if either NLS_NCHAR
-is AL32UTF8, or NLS_NCHAR is not set and NLS_LANG is AL32UTF8.
+=item ora_verbose
-When fetching other character data from Oracle, DBD::Oracle
-will set the Perl UTF-8 flag on the returned data if NLS_LANG is AL32UTF8.
+Use this value to enable DBD::Oracle only tracing. Simply set the attribute to the trace level you desire.
-B<Sending Data using Placeholders>
+=item ora_oci_success_warn
-Data bound to a placeholder is assumed to be in the default client
-character set (specified by NLS_LANG) except for a few special
-cases. These are listed here with the highest precedence first:
+Use this value to print silent OCI warnings that may happen when a fetch returns "Success With Info".
-If the C<ora_csid> attribute is given to bind_param() then that
-is passed to Oracle and takes precedence.
+=back
-If the value is a Perl Unicode string (UTF-8) then DBD::Oracle
-ensures that Oracle uses the Unicode character set, regardless of
-the NLS_LANG and NLS_NCHAR settings.
+=head4 B<Placeholders>
-If the placeholder is for inserting an NCLOB then the client NLS_NCHAR
-character set is used. (That's useful but inconsistent with the other behaviour
-so may change. Best to be explicit by using the C<ora_csform>
-attribute.)
+There are two types of placeholders that can be used in DBD::Oracle. The first is
+the "question mark" type, in which each placeholder is represented by a single
+question mark character. This is the method recommended by the DBI specs and is the most
+portable. Each question mark is internally replaced by a "dollar sign number" in the order
+in which they appear in the query (important when using L</bind_param>).
+
+The other placeholder type is "named parameters" in the format ":foo" which is the one Oralce prefers.
+
+ $dbh->{RaiseError} = 1; # save having to check each method call
+ $sth = $dbh->prepare("SELECT name, age FROM people WHERE name LIKE :name");
+ $sth->bind_param(':name', "John%");
+ $sth->execute;
+ DBI::dump_results($sth);
+
+The different types of placeholders cannot be mixed within a statement, but you may
+use different ones for each statement handle you have. This is confusing at best, so
+stick to one style within your program.
-If the C<ora_csform> attribute is given to bind_param() then that
-determines if the value should be assumed to be in the default
-(NLS_LANG) or NCHAR (NLS_NCHAR) client character set.
+=head3 B<prepare_cached>
- use DBD::Oracle qw( SQLCS_IMPLICIT SQLCS_NCHAR );
- ...
- $sth->bind_param(1, $value, { ora_csform => SQLCS_NCHAR });
+ $sth = $dbh->prepare_cached($statement, \%attr);
-or
+Implemented by DBI, no driver-specific impact. This method is most useful
+if the same query is used over and over as it will cut down round trips to the server.
- $dbh->{ora_ph_csform} = SQLCS_NCHAR; # default for all future placeholders
+=head3 B<do>
-Binding with bind_param_array and execute_array is also UTF-8 compatible in the same way. If you attempt to
-insert UTF-8 data into a non UTF-8 Oracle instance or with an non UTF-8 NCHAR or NVARCHAR the insert
-will still happen but a error code of 0 will be returned with the following warning;
+ $rv = $dbh->do($statement);
+ $rv = $dbh->do($statement, \%attr);
+ $rv = $dbh->do($statement, \%attr, @bind_values);
- DBD Oracle Warning: You have mixed utf8 and non-utf8 in an array bind in parameter#1. This may result in corrupt data.
- The Query charset id=1, name=US7ASCII
+Prepare and execute a single statement. Returns the number of rows affected if the
+query was successful, returns undef if an error occurred, and returns -1 if the
+number of rows is unknown or not available. Note that this method will return B<0E0> instead
+of 0 for 'no rows were affected', in order to always return a true value if no error occurred.
-The warning will report the parameter number and the NCHAR setting that the query is running.
-B<Sending Data using SQL>
+=head3 B<last_insert_id>
-Oracle assumes the SQL statement is in the default client character
-set (as specified by NLS_LANG). So Unicode strings containing
-non-ASCII characters should not be used unless the default client
-character set is AL32UTF8.
+Oracle does not implement auto_increment of serial type columns it uses predefined
+sequences where the id numbers are either selected before insert, at insert time with a trigger,
+ or as part of the query.
-=head2 DBD::Oracle and Other Character Sets and Encodings
+Below is an example of you to use the latter with the SQL returning clause to get the ID number back
+on insert with the bind_param_inout method.
+.
-The only multi-byte Oracle character set supported by DBD::Oracle is
-"AL32UTF8" (and "UTF8"). Single-byte character sets should work well.
+ $dbh->do('CREATE SEQUENCE lii_seq START 1');
+ $dbh->do(q{CREATE TABLE lii (
+ foobar INTEGER NOT NULL UNIQUE,
+ baz VARCHAR)});
+ $SQL = "INSERT INTO lii (foobar,baz) VALUES (lii_seq.nextval,'XX') returning foobar into :p_new_id";";
+ $sth = $dbh->prepare($SQL);
+ my $p_new_id='-1';
+ $sth->bind_param_inout(":p_new_id",\$p_new_id,38);
+ $sth->execute();
+ $db->commit();
-=head1 SYS.DBMS_SQL datatypes
+=head3 B<commit>
-DBD::Oracle has built-in support for B<SYS.DBMS_SQL.VARCHAR2_TABLE>
-and B<SYS.DBMS_SQL.NUMBER_TABLE> datatypes. The simple example is here:
+ $rv = $dbh->commit;
- my $statement='
- DECLARE
- tbl SYS.DBMS_SQL.VARCHAR2_TABLE;
- BEGIN
- tbl := :mytable;
- :cc := tbl.count();
- tbl(1) := \'def\';
- tbl(2) := \'ijk\';
- :mytable := tbl;
- END;
- ';
+Issues a COMMIT to the server, indicating that the current transaction is finished and that
+all changes made will be visible to other processes. If AutoCommit is enabled, then
+a warning is given and no COMMIT is issued. Returns true on success, false on error.
+See also the the section on L</Transactions>.
- my $sth=$dbh->prepare( $statement );
+=head3 B<rollback>
- my @arr=( "abc","efg","hij" );
+ $rv = $dbh->rollback;
- $sth->bind_param_inout(":mytable", \\@arr, 10, {
- ora_type => ORA_VARCHAR2_TABLE,
- ora_maxarray_numentries => 100
- } ) ;
- $sth->bind_param_inout(":cc", \$cc, 100 );
- $sth->execute();
- print "Result: cc=",$cc,"\n",
- "\tarr=",Data::Dumper::Dumper(\@arr),"\n";
+Issues a ROLLBACK to the server, which discards any changes made in the current transaction. If AutoCommit
+is enabled, then a warning is given and no ROLLBACK is issued. Returns true on success, and
+false on error. See also the the section on L</Transactions>.
-N.B.
+=head3 B<begin_work>
- Take careful note that we use '\\@arr' here because the 'bind_param_inout'
- will only take a reference to a scalar.
+This method turns on transactions until the next call to L</commit> or L</rollback>, if L</AutoCommit> is
+currently enabled. If it is not enabled, calling begin_work will issue an error. Note that the
+transaction will not actually begin until the first statement after begin_work is called.
-=over
+=head3 B<disconnect>
-=item ORA_VARCHAR2_TABLE
+ $rv = $dbh->disconnect;
-SYS.DBMS_SQL.VARCHAR2_TABLE object is always bound to array reference.
-( in bind_param() and bind_param_inout() ). When you bind array, you need
-to specify full buffer size for OUT data. So, there are two parameters:
-I<max_len> (specified as 3rd argument of bind_param_inout() ),
-and I<ora_maxarray_numentries>. They define maximum array entry length and
-maximum rows, that can be passed to Oracle and back to you. In this
-example we send array with 1 element with length=3, but allocate space for 100
-Oracle array entries with maximum length 10 of each. So, you can get no more
-than 100 array entries with length <= 10.
+Disconnects from the Oracle database. Any uncommitted changes will be rolled back upon disconnection. It's
+good policy to always explicitly call commit or rollback at some point before disconnecting, rather than
+relying on the default rollback behavior.
-If you set I<max_len> to zero, maximum array entry length is calculated
-as maximum length of entry of array bound. If 0 < I<max_len> < length( $some_element ),
-truncation occur.
+If the script exits before disconnect is called (or, more precisely, if the database handle is no longer
+referenced by anything), then the database handle's DESTROY method will call the rollback() and disconnect()
+methods automatically. It is best to explicitly disconnect rather than rely on this behavior.
-If you set I<ora_maxarray_numentries> to zero, current (at bind time) bound
-array length is used as maximum. If 0 < I<ora_maxarray_numentries> < scalar(@array),
-not all array entries are bound.
-=item ORA_NUMBER_TABLE
+=head3 B<ping>
-SYS.DBMS_SQL.NUMBER_TABLE object handling is much alike ORA_VARCHAR2_TABLE.
-The main difference is internal data representation. Currently 2 types of
-bind is allowed : as C-integer, or as C-double type. To select one of them,
-you may specify additional bind parameter I<ora_internal_type> as either
-B<SQLT_INT> or B<SQLT_FLT> for C-integer and C-double types.
-Integer size is architecture-specific and is usually 32 or 64 bit.
-Double is standard IEEE 754 type.
+ $rv = $dbh->ping;
-I<ora_internal_type> defaults to double (SQLT_FLT).
+This C<ping> method is used to check the validity of a database handle. The value returned is
+either 0, indicating that the connection is no longer valid, or 1, indicating the connection is valid.
+This function does 1 round trip to the Oracle Server.
+
+=head3 B<get_info()>
-I<max_len> is ignored for OCI_NUMBER_TABLE.
+ $value = $dbh->get_info($info_type);
-Currently, you cannot bind full native Oracle NUMBER(38). If you really need,
-send request to dbi-dev list.
+DBD::Oracle supports C<get_info()>, but (currently) only a few info types.
-The usage example is here:
+=head3 B<table_info()>
- $statement='
- DECLARE
- tbl SYS.DBMS_SQL.NUMBER_TABLE;
- BEGIN
- tbl := :mytable;
- :cc := tbl(2);
- tbl(4) := -1;
- tbl(5) := -2;
- :mytable := tbl;
- END;
- ';
+DBD::Oracle supports attributes for C<table_info()>.
- $sth=$dbh->prepare( $statement );
+In Oracle, the concept of I<user> and I<schema> is (currently) the
+same. Because database objects are owned by an user, the owner names
+in the data dictionary views correspond to schema names.
+Oracle does not support catalogues so TABLE_CAT is ignored as
+selection criterion.
- if( ! defined($sth) ){
- die "Prepare error: ",$dbh->errstr,"\n";
- }
+Search patterns are supported for TABLE_SCHEM and TABLE_NAME.
- @arr=( 1,"2E0","3.5" );
+TABLE_TYPE may contain a comma-separated list of table types.
+The following table types are supported:
- # note, that ora_internal_type defaults to SQLT_FLT for ORA_NUMBER_TABLE .
- if( not $sth->bind_param_inout(":mytable", \\@arr, 10, {
- ora_type => ORA_NUMBER_TABLE,
- ora_maxarray_numentries => (scalar(@arr)+2),
- ora_internal_type => SQLT_FLT
- } ) ){
- die "bind :mytable error: ",$dbh->errstr,"\n";
- }
- $cc=undef;
- if( not $sth->bind_param_inout(":cc", \$cc, 100 ) ){
- die "bind :cc error: ",$dbh->errstr,"\n";
- }
+ TABLE
+ VIEW
+ SYNONYM
+ SEQUENCE
- if( not $sth->execute() ){
- die "Execute failed: ",$dbh->errstr,"\n";
- }
- print "Result: cc=",$cc,"\n",
- "\tarr=",Data::Dumper::Dumper(\@arr),"\n";
+The result set is ordered by TABLE_TYPE, TABLE_SCHEM, TABLE_NAME.
-The result is like:
+The special enumerations of catalogues, schemas and table types are
+supported. However, TABLE_CAT is always NULL.
- Result: cc=2
- arr=$VAR1 = [
- '1',
- '2',
- '3.5',
- '-1',
- '-2'
- ];
+An identifier is passed I<as is>, i.e. as the user provides or
+Oracle returns it.
+C<table_info()> performs a case-sensitive search. So, a selection
+criterion should respect upper and lower case.
+Normally, an identifier is case-insensitive. Oracle stores and
+returns it in upper case. Sometimes, database objects are created
+with quoted identifiers (for reserved words, mixed case, special
+characters, ...). Such an identifier is case-sensitive (if not all
+upper case). Oracle stores and returns it as given.
+C<table_info()> has no special quote handling, neither adds nor
+removes quotes.
-If you change bind type to B<SQLT_INT>, like:
+=head3 B<primary_key_info()>
- ora_internal_type => SQLT_INT
+Oracle does not support catalogues so TABLE_CAT is ignored as
+selection criterion.
+The TABLE_CAT field of a fetched row is always NULL (undef).
+See L</table_info()> for more detailed information.
-you get:
+If the primary key constraint was created without an identifier,
+PK_NAME contains a system generated name with the form SYS_Cn.
- Result: cc=2
- arr=$VAR1 = [
- 1,
- 2,
- 3,
- -1,
- -2
- ];
+The result set is ordered by TABLE_SCHEM, TABLE_NAME, KEY_SEQ.
-=back
+An identifier is passed I<as is>, i.e. as the user provides or
+Oracle returns it.
+See L</table_info()> for more detailed information.
-=head1 Other Data Types
+=head3 B<foreign_key_info()>
-DBD::Oracle does not I<explicitly> support most Oracle datatypes.
-It simply asks Oracle to return them as strings and Oracle does so.
-Mostly. Similarly when binding placeholder values DBD::Oracle binds
-them as strings and Oracle converts them to the appropriate type,
-such as DATE, when used.
+This method (currently) supports the extended behaviour of SQL/CLI, i.e. the
+result set contains foreign keys that refer to primary B<and> alternate keys.
+The field UNIQUE_OR_PRIMARY distinguishes these keys.
-Some of these automatic conversions to and from strings use NLS
-settings to control the formatting for output and the parsing for
-input. The most common example is the DATE type. The default NLS
-format for DATE might be DD-MON-YYYY and so when a DATE type is
-fetched that's how Oracle will format the date. NLS settings also
-control the default parsing of strings into DATE values. An error
-will be generated if the contents of the string don't match the
-NLS format. If you're dealing in dates which don't match the default
-NLS format then you can either change the default NLS format or, more
-commonly, use TO_CHAR(field, "format") and TO_DATE(?, "format")
-to explicitly specify formats for converting to and from strings.
+Oracle does not support catalogues, so C<$pk_catalog> and C<$fk_catalog> are
+ignored as selection criteria (in the new style interface).
+The UK_TABLE_CAT and FK_TABLE_CAT fields of a fetched row are always
+NULL (undef).
+See L</table_info()> for more detailed information.
-A slightly more subtle problem can occur with NUMBER types. The
-default NLS settings might format numbers with a fullstop ("C<.>")
-to separate thousands and a comma ("C<,>") as the decimal point.
-Perl will generate warnings and use incorrect values when numbers,
-returned and formatted as strings in this way by Oracle, are used
-in a numeric context. You could explicitly convert each numeric
-value using the TO_CHAR(...) function but that gets tedious very
-quickly. The best fix is to change the NLS settings. That can be
-done for an individual connection by doing:
+If the primary or foreign key constraints were created without an identifier,
+UK_NAME or FK_NAME contains a system generated name with the form SYS_Cn.
- $dbh->do("ALTER SESSION SET NLS_NUMERIC_CHARACTERS = '.,'");
+The UPDATE_RULE field is always 3 ('NO ACTION'), because Oracle (currently)
+does not support other actions.
-There are some types, like BOOLEAN, that Oracle does not automatically
-convert to or from strings (pity). These need to be converted
-explicitly using SQL or PL/SQL functions.
+The DELETE_RULE field may contain wrong values. This is a known Bug (#1271663)
+in Oracle's data dictionary views. Currently (as of 8.1.7), 'RESTRICT' and
+'SET DEFAULT' are not supported, 'CASCADE' is mapped correctly and all other
+actions (incl. 'SET NULL') appear as 'NO ACTION'.
-Examples:
+The DEFERABILITY field is always NULL, because this columns is
+not present in the ALL_CONSTRAINTS view of older Oracle releases.
- # DATE values
- my $sth0 = $dbh->prepare( <<SQL_END );
- SELECT username, TO_CHAR( created, ? )
- FROM all_users
- WHERE created >= TO_DATE( ?, ? )
- SQL_END
- $sth0->execute( 'YYYY-MM-DD HH24:MI:SS', "2003", 'YYYY' );
+The result set is ordered by UK_TABLE_SCHEM, UK_TABLE_NAME, FK_TABLE_SCHEM,
+FK_TABLE_NAME, ORDINAL_POSITION.
- # BOOLEAN values
- my $sth2 = $dbh->prepare( <<PLSQL_END );
- DECLARE
- b0 BOOLEAN;
- b1 BOOLEAN;
- o0 VARCHAR2(32);
- o1 VARCHAR2(32);
+An identifier is passed I<as is>, i.e. as the user provides or
+Oracle returns it.
+See L</table_info()> for more detailed information.
- FUNCTION to_bool( i VARCHAR2 ) RETURN BOOLEAN IS
- BEGIN
- IF i IS NULL THEN RETURN NULL;
- ELSIF i = 'F' OR i = '0' THEN RETURN FALSE;
- ELSE RETURN TRUE;
- END IF;
- END;
- FUNCTION from_bool( i BOOLEAN ) RETURN NUMBER IS
- BEGIN
- IF i IS NULL THEN RETURN NULL;
- ELSIF i THEN RETURN 1;
- ELSE RETURN 0;
- END IF;
- END;
- BEGIN
- -- Converting values to BOOLEAN
- b0 := to_bool( :i0 );
- b1 := to_bool( :i1 );
+=head3 B<column_info()>
- -- Converting values from BOOLEAN
- :o0 := from_bool( b0 );
- :o1 := from_bool( b1 );
- END;
- PLSQL_END
- my ( $i0, $i1, $o0, $o1 ) = ( "", "Something else" );
- $sth2->bind_param( ":i0", $i0 );
- $sth2->bind_param( ":i1", $i1 );
- $sth2->bind_param_inout( ":o0", \$o0, 32 );
- $sth2->bind_param_inout( ":o1", \$o1, 32 );
- $sth2->execute();
- foreach ( $i0, $b0, $o0, $i1, $b1, $o1 ) {
- $_ = "(undef)" if ! defined $_;
- }
- print "$i0 to $o0, $i1 to $o1\n";
- # Result is : "'' to '(undef)', 'Something else' to '1'"
+Oracle does not support catalogues so TABLE_CAT is ignored as
+selection criterion.
+The TABLE_CAT field of a fetched row is always NULL (undef).
+See L</table_info()> for more detailed information.
+The CHAR_OCTET_LENGTH field is (currently) always NULL (undef).
-=head1 PL/SQL Examples
+Don't rely on the values of the BUFFER_LENGTH field!
+Especially the length of FLOATs may be wrong.
-Most of these PL/SQL examples come from: Eric Bartley <[email protected]>.
+Datatype codes for non-standard types are subject to change.
- /*
- * PL/SQL to create package with stored procedures invoked by
- * Perl examples. Execute using sqlplus.
- *
- * Use of "... OR REPLACE" prevents failure in the event that the
- * package already exists.
- */
+Attention! The DATA_DEFAULT (COLUMN_DEF) column is of type LONG.
- CREATE OR REPLACE PACKAGE plsql_example
- IS
- PROCEDURE proc_np;
+The result set is ordered by TABLE_SCHEM, TABLE_NAME, ORDINAL_POSITION.
- PROCEDURE proc_in (
- err_code IN NUMBER
- );
+An identifier is passed I<as is>, i.e. as the user provides or
+Oracle returns it.
+See L</table_info()> for more detailed information.
- PROCEDURE proc_in_inout (
- test_num IN NUMBER,
- is_odd IN OUT NUMBER
- );
+It is possible with Oracle to make the names of the various DB objects (table,column,index etc)
+case sensitive.
- FUNCTION func_np
- RETURN VARCHAR2;
+ alter table bloggind add ("Bla_BLA" NUMBER)
- END plsql_example;
- /
+So in the example the exact case "Bla_BLA" must be used to get it info on the column. While this
- CREATE OR REPLACE PACKAGE BODY plsql_example
- IS
- PROCEDURE proc_np
- IS
- whoami VARCHAR2(20) := NULL;
- BEGIN
- SELECT USER INTO whoami FROM DUAL;
- END;
+ alter table bloggind add (Bla_BLA NUMBER)
- PROCEDURE proc_in (
- err_code IN NUMBER
- )
- IS
- BEGIN
- RAISE_APPLICATION_ERROR(err_code, 'This is a test.');
- END;
+any case can be used to get info on the column.
- PROCEDURE proc_in_inout (
- test_num IN NUMBER,
- is_odd IN OUT NUMBER
- )
- IS
- BEGIN
- is_odd := MOD(test_num, 2);
- END;
+=head3 B<selectrow_array>
- FUNCTION func_np
- RETURN VARCHAR2
- IS
- ret_val VARCHAR2(20);
- BEGIN
- SELECT USER INTO ret_val FROM DUAL;
- RETURN ret_val;
- END;
+ @row_ary = $dbh->selectrow_array($sql);
+ @row_ary = $dbh->selectrow_array($sql, \%attr);
+ @row_ary = $dbh->selectrow_array($sql, \%attr, @bind_values);
- END plsql_example;
- /
- /* End PL/SQL for example package creation. */
+Returns an array of row information after preparing and executing the provided SQL string. The rows are returned
+by calling L</fetchrow_array>. The string can also be a statement handle generated by a previous prepare. Note that
+only the first row of data is returned. If called in a scalar context, only the first column of the first row is
+returned. Because this is not portable, it is not recommended that you use this method in that way.
- use DBI;
+=head3 B<selectrow_arrayref>
- my($db, $csr, $ret_val);
+ $ary_ref = $dbh->selectrow_arrayref($statement);
+ $ary_ref = $dbh->selectrow_arrayref($statement, \%attr);
+ $ary_ref = $dbh->selectrow_arrayref($statement, \%attr, @bind_values);
- $db = DBI->connect('dbi:Oracle:database','user','password')
- or die "Unable to connect: $DBI::errstr";
+Exactly the same as L</selectrow_array>, except that it returns a reference to an array, by internal use of
+the L</fetchrow_arrayref> method.
- # So we don't have to check every DBI call we set RaiseError.
- # See the DBI docs now if you're not familiar with RaiseError.
- $db->{RaiseError} = 1;
+=head3 B<selectrow_hashref>
- # Example 1 Eric Bartley <[email protected]>
- #
- # Calling a PLSQL procedure that takes no parameters. This shows you the
- # basic's of what you need to execute a PLSQL procedure. Just wrap your
- # procedure call in a BEGIN END; block just like you'd do in SQL*Plus.
- #
- # p.s. If you've used SQL*Plus's exec command all it does is wrap the
- # command in a BEGIN END; block for you.
+ $hash_ref = $dbh->selectrow_hashref($sql);
+ $hash_ref = $dbh->selectrow_hashref($sql, \%attr);
+ $hash_ref = $dbh->selectrow_hashref($sql, \%attr, @bind_values);
- $csr = $db->prepare(q{
- BEGIN
- PLSQL_EXAMPLE.PROC_NP;
- END;
- });
- $csr->execute;
+Exactly the same as L</selectrow_array>, except that it returns a reference to an hash, by internal use of
+the L</fetchrow_hashref> method.
+=head3 B<clone>
- # Example 2 Eric Bartley <[email protected]>
- #
- # Now we call a procedure that has 1 IN parameter. Here we use bind_param
- # to bind out parameter to the prepared statement just like you might
- # do for an INSERT, UPDATE, DELETE, or SELECT statement.
- #
- # I could have used positional placeholders (e.g. :1, :2, etc.) or
- # ODBC style placeholders (e.g. ?), but I prefer Oracle's named
- # placeholders (but few DBI drivers support them so they're not portable).
+ $other_dbh = $dbh->clone();
- my $err_code = -20001;
+Creates a copy of the database handle by connecting with the same parameters as the original
+handle, then trying to merge the attributes. See the DBI documentation for complete usage.
- $csr = $db->prepare(q{
- BEGIN
- PLSQL_EXAMPLE.PROC_IN(:err_code);
- END;
- });
+=head2 Private Database Handle Methods
- $csr->bind_param(":err_code", $err_code);
+=head3 B<ora_can_unicode ( [ $refresh ] )>
- # PROC_IN will RAISE_APPLICATION_ERROR which will cause the execute to 'fail'.
- # Because we set RaiseError, the DBI will croak (die) so we catch that with eval.
- eval {
- $csr->execute;
- };
- print 'After proc_in: $@=',"'$@', errstr=$DBI::errstr, ret_val=$ret_val\n";
+Returns a number indicating whether either of the database character sets
+is a Unicode encoding. Calls ora_nls_parameters() and passes the optional
+$refresh parameter to it.
+0 = Neither character set is a Unicode encoding.
- # Example 3 Eric Bartley <[email protected]>
- #
- # Building on the last example, I've added 1 IN OUT parameter. We still
- # use a placeholders in the call to prepare, the difference is that
- # we now call bind_param_inout to bind the value to the place holder.
- #
- # Note that the third parameter to bind_param_inout is the maximum size
- # of the variable. You normally make this slightly larger than necessary.
- # But note that the Perl variable will have that much memory assigned to
- # it even if the actual value returned is shorter.
+1 = National character set is a Unicode encoding.
- my $test_num = 5;
- my $is_odd;
+2 = Database character set is a Unicode encoding.
- $csr = $db->prepare(q{
- BEGIN
- PLSQL_EXAMPLE.PROC_IN_INOUT(:test_num, :is_odd);
- END;
- });
+3 = Both character sets are Unicode encodings.
- # The value of $test_num is _copied_ here
- $csr->bind_param(":test_num", $test_num);
+=head3 B<ora_can_taf>
- $csr->bind_param_inout(":is_odd", \$is_odd, 1);
+Returns true if the current connection supports TAF events. False if otherise.
- # The execute will automagically update the value of $is_odd
- $csr->execute;
+=head3 B<ora_nls_parameters ( [ $refresh ] )>
- print "$test_num is ", ($is_odd) ? "odd - ok" : "even - error!", "\n";
+Returns a hash reference containing the current NLS parameters, as given
+by the v$nls_parameters view. The values fetched are cached between calls.
+To cause the latest values to be fetched, pass a true value to the function.
- # Example 4 Eric Bartley <[email protected]>
- #
- # What about the return value of a PLSQL function? Well treat it the same
- # as you would a call to a function from SQL*Plus. We add a placeholder
- # for the return value and bind it with a call to bind_param_inout so
- # we can access it's value after execute.
+=head2 Database Handle Attributes
- my $whoami = "";
+=head3 B<AutoCommit> (boolean)
- $csr = $db->prepare(q{
- BEGIN
- :whoami := PLSQL_EXAMPLE.FUNC_NP;
- END;
- });
+Supported by DBD::Oracle as proposed by DBI.The default of AutoCommit is on, but this may change
+in the future, so it is highly recommended that you explicitly set it when
+calling L</connect>. For details see the notes about L</Transactions>
+elsewhere in this document.
- $csr->bind_param_inout(":whoami", \$whoami, 20);
- $csr->execute;
- print "Your database user name is $whoami\n";
+=head3 B<ReadOnly> (boolean)
- $db->disconnect;
+ $dbh->{ReadOnly} = 1;
-You can find more examples in the t/plsql.t file in the DBD::Oracle
-source directory.
+Specifies if the current database connection should be in read-only mode or not.
-Oracle 9.2 appears to have a bug where a variable bound
-with bind_param_inout() that isn't assigned to by the executed
-PL/SQL block may contain garbage.
-See L<http://www.mail-archive.com/[email protected]/msg18835.html>
+Please not that this method is not foolproof: there are still ways to update the
+database. Consider this a safety net to catch applications that should not be
+issuing commands such as INSERT, UPDATE, or DELETE.
-=head2 Avoid Using "SQL Call"
+This method method requires DBI version 1.55 or better.
-Avoid using the "SQL Call" statement with DBD:Oracle as you might find that
-DBD::Oracle will not raise an exception in some case. Specifically if you use
-"SQL Call" to run a procedure all "No data found" exceptions will be quietly
-ignored and returned as null. According to Oracle support this is part of the same
-mechanism where;
+=head3 B<Name> (string, read-only)
- select (select * from dual where 0=1) from dual
+Returns the name of the current database. This is the same as the DSN, without the
+"dbi:Oracle:" part.
-returns a null value rather than an exception.
+=head3 B<Username> (string, read-only)
-=head1 Private database handle functions
+Returns the name of the user connected to the database.
-Some of these functions are called through the method func()
-which is described in the DBI documentation. Any function that begins with ora_
-can be called directly.
+=head3 B<Driver> (handle, read-only)
-=head2 plsql_errstr
+Holds the handle of the parent driver. The only recommended use for this is to find the name
+of the driver using:
-This function returns a string which describes the errors
-from the most recent PL/SQL function, procedure, package,
-or package body compile in a format similar to the output
-of the SQL*Plus command 'show errors'.
+ $dbh->{Driver}->{Name}
-The function returns undef if the error string could not
-be retrieved due to a database error.
-Look in $dbh->errstr for the cause of the failure.
+=head3 B<RowCacheSize>
-If there are no compile errors, an empty string is returned.
-
-Example:
+DBD::Oracle supports both Server pre-fetch and Client side row caching. By default both
+are turned on to give optimum performance. Most of the time one can just let DBD::Oracle
+figure out the best optimization.
- # Show the errors if CREATE PROCEDURE fails
- $dbh->{RaiseError} = 0;
- if ( $dbh->do( q{
- CREATE OR REPLACE PROCEDURE perl_dbd_oracle_test as
- BEGIN
- PROCEDURE filltab( stuff OUT TAB ); asdf
- END; } ) ) {} # Statement succeeded
- }
- elsif ( 6550 != $dbh->err ) { die $dbh->errstr; } # Utter failure
- else {
- my $msg = $dbh->func( 'plsql_errstr' );
- die $dbh->errstr if ! defined $msg;
- die $msg if $msg;
- }
+=head4 B<Row Caching>
-=head2 dbms_output_enable / dbms_output_put / dbms_output_get
+Row caching occurs on the client side and the object of it is to cut down the number of round
+trips made to the server when fetching rows. At each fetch a set number of rows will be retrieved
+from the server and stored locally. Further calls the server are made only when the end of the
+local buffer(cache) is reached.
-These functions use the PL/SQL DBMS_OUTPUT package to store and
-retrieve text using the DBMS_OUTPUT buffer. Text stored in this buffer
-by dbms_output_put or any PL/SQL block can be retrieved by
-dbms_output_get or any PL/SQL block connected to the same database
-session.
+Rows up to the specified top level row
+count C<RowCacheSize> are fetched if it occupies no more than the specified memory usage limit.
+The default value is 0, which means that memory size is not included in computing the number of rows to prefetch. If
+the C<RowCacheSize> value is set to a negative number then the positive value of RowCacheSize is used
+to compute the number of rows to prefetch.
-Stored text is not available until after dbms_output_put or the PL/SQL
-block that saved it completes its execution. This means you B<CAN NOT>
-use these functions to monitor long running PL/SQL procedures.
+By default C<RowCacheSize> is automatically set. If you want to totally turn off prefetching set this to 1.
-Example 1:
+For any SQL statement that contains a LOB, Long or Object Type Row Caching will be turned off. However server side
+caching still works. If you are only selecting a LOB Locator then Row Caching will still work.
- # Enable DBMS_OUTPUT and set the buffer size
- $dbh->{RaiseError} = 1;
- $dbh->func( 1000000, 'dbms_output_enable' );
+=head4 Row Prefetching
- # Put text in the buffer . . .
- $dbh->func( @text, 'dbms_output_put' );
+Row prefetching occurs on the server side and uses the DBI database handle attribute C<RowCacheSize> and or the
+Prepare Attribute 'ora_prefetch_memory'. Tweaking these values may yield improved performance.
- # . . . and retrieve it later
- @text = $dbh->func( 'dbms_output_get' );
+ $dbh->{RowCacheSize} = 100;
+ $sth=$dbh->prepare($SQL,{ora_exe_mode=>OCI_STMT_SCROLLABLE_READONLY,ora_prefetch_memory=>10000});
+
+In the above example 10 rows will be prefetched up to a maximum of 10000 bytes of data. The Oracle® Call Interface Programmer's Guide,
+suggests a good row cache value for a scrollable cursor is about 20% of expected size of the record set.
-Example 2:
+The prefetch settings tell the DBD::Oracle to grab x rows (or x-bytes) when it needs to get new rows. This happens on the first
+fetch that sets the current_positon to any value other than 0. In the above example if we do a OCI_FETCH_FIRST the first 10 rows are
+loaded into the buffer and DBD::Oracle will not have to go back to the server for more rows. When record 11 is fetched DBD::Oracle
+fetches and returns this row and the next 9 rows are loaded into the buffer. In this case if you fetch backwards from 10 to 1
+no server round trips are made.
- $dbh->{RaiseError} = 1;
- $sth = $dbh->prepare(q{
- DECLARE tmp VARCHAR2(50);
- BEGIN
- SELECT SYSDATE INTO tmp FROM DUAL;
- dbms_output.put_line('The date is '||tmp);
- END;
- });
- $sth->execute;
+With large record sets it is best not to attempt to go to the last record as this may take some time, A large buffer size might even slow down
+the fetch. If you must get the number of rows in a large record set you might try using an few large OCI_FETCH_ABSOLUTEs and then an OCI_FETCH_LAST,
+this might save some time. So if you had a record set of 10000 rows and you set the buffer to 5000 and did a OCI_FETCH_LAST one would fetch the first 5000 rows into the buffer then the next 5000 rows.
+If one requires only the first few rows there is no need to set a large prefetch value.
- # retrieve the string
- $date_string = $dbh->func( 'dbms_output_get' );
+If the ora_prefetch_memory less than 1 or not present then memory size is not included in computing the
+number of rows to prefetch otherwise the number of rows will be limited to memory size. Likewise if the RowCacheSize is less than 1 it
+is not included in the computing of the prefetch rows.
-=head2 dbms_output_enable ( [ buffer_size ] )
-This function calls DBMS_OUTPUT.ENABLE to enable calls to package
-DBMS_OUTPUT procedures GET, GET_LINE, PUT, and PUT_LINE. Calls to
-these procedures are ignored unless DBMS_OUTPUT.ENABLE is called
-first.
+=head1 DBI Statement Handle Object
-The buffer_size is the maximum amount of text that can be saved in the
-buffer and must be between 2000 and 1,000,000. If buffer_size is not
-given, the default is 20,000 bytes.
+=head2 Statement Handle Methods
-=head2 dbms_output_put ( [ @lines ] )
+=head3 B<bind_param>
-This function calls DBMS_OUTPUT.PUT_LINE to add lines to the buffer.
+ $rv = $sth->bind_param($param_num, $bind_value);
+ $rv = $sth->bind_param($param_num, $bind_value, $bind_type);
+ $rv = $sth->bind_param($param_num, $bind_value, \%attr);
-If all lines were saved successfully the function returns 1. Depending
-on the context, an empty list or undef is returned for failure.
+Allows the user to bind a value and/or a data type to a placeholder.
-If any line causes buffer_size to be exceeded, a buffer overflow error
-is raised and the function call fails. Some of the text might be in
-the buffer.
+The value of C<$param_num> is a number if using the '?' or if using ":foo" style placeholders, the complete name
+(e.g. ":foo") must be given.
+The C<$bind_value> argument is fairly self-explanatory. A value of C<undef> will
+bind a C<NULL> to the placeholder. Using C<undef> is useful when you want
+to change just the type and will be overwriting the value later.
+(Any value is actually usable, but C<undef> is easy and efficient).
-=head2 dbms_output_get
+The C<\%attr> hash is used to indicate the data type of the placeholder.
+The default value is "varchar". If you need something else, you must
+use one of the values provided by DBI or by DBD::Pg. To use a SQL value,
+modify your "use DBI" statement at the top of your script as follows:
-This function calls DBMS_OUTPUT.GET_LINE to retrieve lines of text from
-the buffer.
+ use DBI qw(:sql_types);
-In an array context, all complete lines are removed from the buffer and
-returned as a list. If there are no complete lines, an empty list is
-returned.
+This will import some constants into your script. You can plug those
+directly into the L</bind_param> call. Some common ones that you will
+encounter are:
-In a scalar context, the first complete line is removed from the buffer
-and returned. If there are no complete lines, undef is returned.
+ SQL_INTEGER
-Any text in the buffer after a call to DBMS_OUTPUT.GET_LINE or
-DBMS_OUTPUT.GET is discarded by the next call to DBMS_OUTPUT.PUT_LINE,
-DBMS_OUTPUT.PUT, or DBMS_OUTPUT.NEW_LINE.
+To use Oracle SQL data types, import the list of values like this:
-=head2 reauthenticate ( $username, $password )
+ use DBD::Pg qw(:ora_types);
-Starts a new session against the current database using the credentials
-supplied.
+You can then set the data types by setting the value of the C<ora_type>
+key in the hash passed to L</bind_param>.
+The current list of Oracle data types exported is:
-=head2 ora_nls_parameters ( [ $refresh ] )
+ ORA_VARCHAR2 ORA_STRING ORA_NUMBER ORA_LONG ORA_ROWID ORA_DATE ORA_RAW
+ ORA_LONGRAW ORA_CHAR ORA_CHARZ ORA_MLSLABEL ORA_XMLTYPE ORA_CLOB ORA_BLOB
+ ORA_RSET ORA_VARCHAR2_TABLE ORA_NUMBER_TABLE SQLT_INT SQLT_FLT ORA_OCI
+ SQLT_CHR SQLT_BIN
+
+Data types are "sticky," in that once a data type is set to a certain placeholder,
+it will remain for that placeholder, unless it is explicitly set to something
+else afterwards. If the statement has already been prepared, and you switch the
+data type to something else, DBD::Oracle will re-prepare the statement for you before
+doing the next execute.
-Returns a hash reference containing the current NLS parameters, as given
-by the v$nls_parameters view. The values fetched are cached between calls.
-To cause the latest values to be fetched, pass a true value to the function.
+Examples:
-=head2 ora_can_unicode ( [ $refresh ] )
+ use DBI qw(:sql_types);
+ use DBD::Pg qw(:ora_types);
-Returns a number indicating whether either of the database character sets
-is a Unicode encoding. Calls ora_nls_parameters() and passes the optional
-$refresh parameter to it.
+ $SQL = "SELECT id FROM ptable WHERE size > ? AND title = ?";
+ $sth = $dbh->prepare($SQL);
-0 = Neither character set is a Unicode encoding.
+ ## Both arguments below are bound to placeholders as "varchar"
+ $sth->execute(123, "Merk");
-1 = National character set is a Unicode encoding.
+ ## Reset the datatype for the first placeholder to an integer
+ $sth->bind_param(1, undef, SQL_INTEGER);
-2 = Database character set is a Unicode encoding.
+ ## The "undef" bound above is not used, since we supply params to execute
+ $sth->execute(123, "Merk");
-3 = Both character sets are Unicode encodings.
+ ## Set the first placeholder's value and data type
+ $sth->bind_param(1, 234, { pg_type => ORA_NUMBER });
-=head2 ora_can_taf
+ ## Set the second placeholder's value and data type.
+ ## We don't send a third argument, so the default "varchar" is used
+ $sth->bind_param('$2', "Zool");
-Returns true if the current connection supports TAF events. False if otherise.
+ ## We realize that the wrong data type was set above, so we change it:
+ $sth->bind_param('$1', 234, { pg_type => SQL_INTEGER });
-=head1 Private statement handle functions
+ ## We also got the wrong value, so we change that as well.
+ ## Because the data type is sticky, we don't need to change it
+ $sth->bind_param(1, 567);
-=over
+ ## This executes the statement with 567 (integer) and "Zool" (varchar)
+ $sth->execute();
-=head2 ora_stmt_type
-Returns the OCI Statement Type number for the SQL of a statement handle.
+These attributes may be used in the C<\%attr> parameter of the
+L<DBI/bind_param> or L<DBI/bind_param_inout> statement handle methods.
-=head2 ora_stmt_type_name
+=over 4
-Returns the OCI Statement Type name for the SQL of a statement handle.
+=item ora_type
-=head1 Scrollable Cursors
+Specify the placeholder's datatype using an Oracle datatype.
+A fatal error is raised if C<ora_type> and the DBI C<TYPE> attribute
+are used for the same placeholder.
+Some of these types are not supported by the current version of
+DBD::Oracle and will cause a fatal error if used.
+Constants for the Oracle datatypes may be imported using
-Oracle supports the concept of a 'Scrollable Cursor' which is defined as a 'Result Set' where
-the rows can be fetched either sequentially or non-sequentially. One can fetch rows forward,
-backwards, from any given position or the n-th row from the current position in the result set.
+ use DBD::Oracle qw(:ora_types);
-Rows are numbered sequentially starting at one and client-side caching of the partial or entire result set
-can improve performance by limiting round trips to the server.
+Potentially useful values when DBD::Oracle was built using OCI 7 and later:
-Oracle does not support DML type operations with scrollable cursors so you are limited
-to simple 'Select' operations only. As well you can not use this functionality with remote
-mapped queries or if the LONG datatype is part of the select list.
+ ORA_VARCHAR2, ORA_STRING, ORA_LONG, ORA_RAW, ORA_LONGRAW,
+ ORA_CHAR, ORA_MLSLABEL, ORA_RSET
-However, LOBSs, CLOBSs, and BLOBs do work as do all the regular bind, and fetch methods.
+Additional values when DBD::Oracle was built using OCI 8 and later:
-Only use scrollable cursors if you really have a good reason to. They do use up considerable
-more server and client resources and have poorer response times than non-scrolling cursors.
+ ORA_CLOB, ORA_BLOB, ORA_XMLTYPE, ORA_VARCHAR2_TABLE, ORA_NUMBER_TABLE
+Additional values when DBD::Oracle was built using OCI 9.2 and later:
-=head2 Enabling Scrollable Cursors
+ SQLT_CHR, SQLT_BIN
-To enable this functionality you must first import the 'Fetch Orientation' and the 'Execution Mode' constants by using;
+See L</Binding Cursors> for the correct way to use ORA_RSET.
- use DBD::Oracle qw(:ora_fetch_orient :ora_exe_modes);
+See L</LOBs and LONGs> for how to use ORA_CLOB and ORA_BLOB.
-Next you will have to tell DBD::Oracle that you will be using scrolling by setting the ora_exe_mode attribute on the
-statement handle to 'OCI_STMT_SCROLLABLE_READONLY' with the prepare method;
+See L</SYS.DBMS_SQL datatypes> for ORA_VARCHAR2_TABLE, ORA_NUMBER_TABLE.
- $sth=$dbh->prepare($SQL,{ora_exe_mode=>OCI_STMT_SCROLLABLE_READONLY});
+See L</Data Interface for Persistent LOBs> for the correct way to use SQLT_CHR and SQLT_BIN.
-When the statement is executed you will then be able to use 'ora_fetch_scroll' method to get a row
-or you can still use any of the other fetch methods but with a poorer response time than if you used a
-non-scrolling cursor. As well scrollable cursors are compatible with any applicable bind methods.
+See L</Other Data Types> for more information.
+See also L<DBI/Placeholders and Bind Values>.
-=head2 Scrollable Cursor Methods
+=item ora_csform
-The following driver-specific methods are used with scrollable cursors.
+Specify the OCI_ATTR_CHARSET_FORM for the bind value. Valid values
+are SQLCS_IMPLICIT (1) and SQLCS_NCHAR (2). Both those constants can
+be imported from the DBD::Oracle module. Rarely needed.
-=over
+=item ora_csid
-=item ora_scroll_position
+Specify the I<integer> OCI_ATTR_CHARSET_ID for the bind value.
+Character set names can't be used currently.
- $position = $sth->ora_scroll_position();
+=item ora_maxdata_size
-This method returns the current position (row number) attribute of the result set. Prior to the first fetch this value is 0. This is the only time
-this value will be 0 after the first fetch the value will be set, so you can use this value to test if any rows have been fetched.
-The minimum value will always be 1 after the first fetch. The maximum value will always be the total number of rows in the record set.
+Specify the integer OCI_ATTR_MAXDATA_SIZE for the bind value.
+May be needed if a character set conversion from client to server
+causes the data to use more space and so fail with a truncation error.
-=item ora_fetch_scroll
+=item ora_maxarray_numentries
- @ary = $sth->ora_fetch_scroll($fetch_orient,$fetch_offset);
+Specify the maximum number of array entries to allocate. Used with
+ORA_VARCHAR2_TABLE, ORA_NUMBER_TABLE. Define the maximum number of
+array entries Oracle can pass back to you in OUT variable of type
+TABLE OF ... .
-Works the same as fetchrow_array method however, one passes in a 'Fetch Orientation' constant and a fetch_offset
-value which will then determine the row that will be fetched. It returns the row as a list containing the field values.
-Null fields are returned as undef values in the list.
+=item ora_internal_type
-The valid orientation constant and fetch offset values combination are detailed below
+Specify internal data representation. Currently is supported only for
+ORA_NUMBER_TABLE.
- OCI_FETCH_CURRENT, fetches the current row, the fetch offset value is ignored.
- OCI_FETCH_NEXT, fetches the next row from the current position, the fetch offset value
- is ignored.
- OCI_FETCH_FIRST, fetches the first row, the fetch offset value is ignored.
- OCI_FETCH_LAST, fetches the last row, the fetch offset value is ignored.
- OCI_FETCH_PRIOR, fetches the previous row from the current position, the fetch offset
- value is ignored.
- OCI_FETCH_ABSOLUTE, fetches the row that is specified by the fetch offset value.
- OCI_FETCH_RELATIVE, fetches the row relative from the current position as specified by the
- fetch offset value.
+=back
- OCI_FETCH_ABSOLUTE, and a fetch offset value of 1 is equivalent to a OCI_FETCH_FIRST.
- OCI_FETCH_ABSOLUTE, and a fetch offset value of 0 is equivalent to a OCI_FETCH_CURRENT.
+=head4 Optimizing Results
- OCI_FETCH_RELATIVE, and a fetch offset value of 0 is equivalent to a OCI_FETCH_CURRENT.
- OCI_FETCH_RELATIVE, and a fetch offset value of 1 is equivalent to a OCI_FETCH_NEXT.
- OCI_FETCH_RELATIVE, and a fetch offset value of -1 is equivalent to a OCI_FETCH_PRIOR.
+=head5 Prepare postponed till execute
-The effect that a ora_fetch_scroll method call has on the current_positon attribute is detailed below.
+The DBD::Oracle module can avoid an explicit 'describe' operation
+prior to the execution of the statement unless the application requests
+information about the results (such as $sth->{NAME}). This reduces
+communication with the server and increases performance (reducing the
+number of PARSE_CALLS inside the server).
- OCI_FETCH_CURRENT, has no effect on the current_positon attribute.
- OCI_FETCH_NEXT, increments current_positon attribute by 1
- OCI_FETCH_NEXT, when at the last row in the record set does not change current_positon
- attribute, it is equivalent to a OCI_FETCH_CURRENT
- OCI_FETCH_FIRST, sets the current_positon attribute to 1.
- OCI_FETCH_LAST, sets the current_positon attribute to the total number of rows in the
- record set.
- OCI_FETCH_PRIOR, decrements current_positon attribute by 1.
- OCI_FETCH_PRIOR, when at the first row in the record set does not change current_positon
- attribute, it is equivalent to a OCI_FETCH_CURRENT.
+However, it also means that SQL errors are not detected until
+C<execute()> (or $sth->{NAME} etc) is called instead of when
+C<prepare()> is called. Note that if the describe is triggered by the
+use of $sth->{NAME} or a similar attribute and the describe fails then
+I<an exception is thrown> even if C<RaiseError> is false!
- OCI_FETCH_ABSOLUTE, sets the current_positon attribute to the fetch offset value.
- OCI_FETCH_ABSOLUTE, and a fetch offset value that is less than 1 does not change
- current_positon attribute, it is equivalent to a OCI_FETCH_CURRENT.
- OCI_FETCH_ABSOLUTE, and a fetch offset value that is greater than the number of records in
- the record set, does not change current_positon attribute, it is
- equivalent to a OCI_FETCH_CURRENT.
- OCI_FETCH_RELATIVE, sets the current_positon attribute to (current_positon attribute +
- fetch offset value).
- OCI_FETCH_RELATIVE, and a fetch offset value that makes the current position less than 1,
- does not change fetch offset value so it is equivalent to a OCI_FETCH_CURRENT.
- OCI_FETCH_RELATIVE, and a fetch offset value that makes it greater than the number of records
- in the record set, does not change fetch offset value so it is equivalent
- to a OCI_FETCH_CURRENT.
+Set L</ora_check_sql> to 0 in prepare() to enable this behaviour.
-The effects of the differing orientation constants on the first fetch (current_postion attribute at 0) are as follows.
+=head4 Spaces & Padding
- OCI_FETCH_CURRENT, dose not fetch a row or change the current_positon attribute.
- OCI_FETCH_FIRST, fetches row 1 and sets the current_positon attribute to 1.
- OCI_FETCH_LAST, fetches the last row in the record set and sets the current_positon
- attribute to the total number of rows in the record set.
- OCI_FETCH_NEXT, equivalent to a OCI_FETCH_FIRST.
- OCI_FETCH_PRIOR, equivalent to a OCI_FETCH_CURRENT.
+=head5 Trailing Spaces
- OCI_FETCH_ABSOLUTE, and a fetch offset value that is less than 1 is equivalent to a
- OCI_FETCH_CURRENT.
- OCI_FETCH_ABSOLUTE, and a fetch offset value that is greater than the number of
- records in the record set is equivalent to a OCI_FETCH_CURRENT.
- OCI_FETCH_RELATIVE, and a fetch offset value that is less than 1 is equivalent
- to a OCI_FETCH_CURRENT.
- OCI_FETCH_RELATIVE, and a fetch offset value that makes it greater than the number
- of records in the record set, is equivalent to a OCI_FETCH_CURRENT.
+Please note that only the Oracle OCI 8 strips trailing spaces from VARCHAR placeholder
+values and uses Nonpadded Comparison Semantics with the result.
+This causes trouble if the spaces are needed for
+comparison with a CHAR value or to prevent the value from
+becoming '' which Oracle treats as NULL.
+Look for Blank-padded Comparison Semantics and Nonpadded
+Comparison Semantics in Oracle's SQL Reference or Server
+SQL Reference for more details.
-=back
+To preserve trailing spaces in placeholder values for Oracle clients that use OCI 8,
+either change the default placeholder type with L</ora_ph_type> or the placeholder
+type for a particular call to L<DBI/bind> or L<DBI/bind_param_inout>
+with L</ora_type> or C<TYPE>.
+Using L<ORA_CHAR> with L<ora_type> or C<SQL_CHAR> with C<TYPE>
+allows the placeholder to be used with Padded Comparison Semantics
+if the value it is being compared to is a CHAR, NCHAR, or literal.
-=head2 Scrollable Cursor Usage
+Please remember that using spaces as a value or at the end of
+a value makes visually distinguishing values with different
+numbers of spaces difficult and should be avoided.
-Given a simple code like this:
+Oracle Clients that use OCI 9.2 do not strip trailing spaces.
- use DBI;
- use DBD::Oracle qw(:ora_types :ora_fetch_orient :ora_exe_modes);
- my $dbh = DBI->connect($dsn, $dbuser, '');
- my $SQL = "select id,
- first_name,
- last_name
- from employee";
- my $sth=$dbh->prepare($SQL,{ora_exe_mode=>OCI_STMT_SCROLLABLE_READONLY});
- $sth->execute();
- my $value;
+=head5 Padded Char Fields
-and one assumes that the number of rows returned from the query is 20, the code snippets below will illustrate the use of ora_fetch_scroll
-method;
+Oracle Clients after OCI 9.2 will automatically pad CHAR placeholder values to the size of the CHAR.
+As the default placeholder type value in DBD::Oracle is ORA_VARCHAR2 to access this behaviour you will
+have to change the default placeholder type with L</ora_ph_type> or placeholder
+type for a particular call with L<DBI/bind> or L<DBI/bind_param_inout>
+with L</ORA_CHAR>.
-=over
+=head4 Unicode
-=item Fetching the Last Row
+DBD::Oracle now supports Unicode UTF-8. There are, however, a number
+of issues you should be aware of, so please read all this section
+carefully.
- $value = $sth->ora_fetch_scroll(OCI_FETCH_LAST,0);
- print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
- print "current scroll position=".$sth->ora_scroll_position()."\n";
-
-The current_positon attribute to will be 20 after this snippet. This is also a way to get the number of rows in the record set, however,
-if the record set is large this could take some time.
-
-=item Fetching the Current Row
-
- $value = $sth->ora_fetch_scroll(OCI_FETCH_CURRENT,0);
- print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
- print "current scroll position=".$sth->ora_scroll_position()."\n";
-
-The current_positon attribute will still be 20 after this snippet.
-
-=item Fetching the First Row
+In this section we'll discuss "Perl and Unicode", then "Oracle and
+Unicode", and finally "DBD::Oracle and Unicode".
- $value = $sth->ora_fetch_scroll(OCI_FETCH_FIRST,0);
- print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
- print "current scroll position=".$sth->ora_scroll_position()."\n";
+Information about Unicode in general can be found at:
+L<http://www.unicode.org/>. It is well worth reading because there are
+many misconceptions about Unicode and you may be holding some of them.
-The current_positon attribute will be 1 after this snippet.
+=head5 Perl and Unicode
-=item Fetching the Next Row
+Perl began implementing Unicode with version 5.6, but the implementation
+did not mature until version 5.8 and later. If you plan to use Unicode
+you are I<strongly> urged to use Perl 5.8.2 or later and to I<carefully> read
+the Perl documentation on Unicode:
- for(my $i=0;$i<=3;$i++){
- $value = $sth->ora_fetch_scroll(OCI_FETCH_NEXT,0);
- print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
- }
- print "current scroll position=".$sth->ora_scroll_position()."\n";
+ perldoc perluniintro # in Perl 5.8 or later
+ perldoc perlunicode
-The current_positon attribute will be 5 after this snippet.
+And then read it again.
-=item Fetching the Prior Row
+Perl's internal Unicode format is UTF-8
+which corresponds to the Oracle character set called AL32UTF8.
- for(my $i=0;$i<=3;$i++){
- $value = $sth->ora_fetch_scroll(OCI_FETCH_PRIOR,0);
- print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
- }
- print "current scroll position=".$sth->ora_scroll_position()."\n";
+=head5 Oracle and Unicode
-The current_positon attribute will be 1 after this snippet.
+Oracle supports many characters sets, including several different forms
+of Unicode. These include:
-=item Fetching the 10th Row
+ AL16UTF16 => valid for NCHAR columns (CSID=2000)
+ UTF8 => valid for NCHAR columns (CSID=871), deprecated
+ AL32UTF8 => valid for NCHAR and CHAR columns (CSID=873)
- $value = $sth->ora_fetch_scroll(OCI_FETCH_ABSOLUTE,10);
- print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
- print "current scroll position=".$sth->ora_scroll_position()."\n";
+When you create an Oracle database, you must specify the DATABASE
+character set (used for DDL, DML and CHAR datatypes) and the NATIONAL
+character set (used for NCHAR and NCLOB types).
+The character sets used in your database can be found using:
-The current_positon attribute will be 10 after this snippet.
+ $hash_ref = $dbh->ora_nls_parameters()
+ $database_charset = $hash_ref->{NLS_CHARACTERSET};
+ $national_charset = $hash_ref->{NLS_NCHAR_CHARACTERSET};
-=item Fetching the 10th to 14th Row
+The Oracle 9.2 and later default for the national character set is AL16UTF16.
+The default for the database character set is often US7ASCII.
+Although many experienced DBAs will consider an 8bit character set like
+WE8ISO8859P1 or WE8MSWIN1252. To use any character set with Oracle
+other than US7ASCII, requires that the NLS_LANG environment variable be set.
+See the L<"Oracle UTF8 is not UTF-8"> section below.
- for(my $i=10;$i<15;$i++){
- $value = $sth->ora_fetch_scroll(OCI_FETCH_ABSOLUTE,$i);
- print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
- }
- print "current scroll position=".$sth->ora_scroll_position()."\n";
-The current_positon attribute will be 14 after this snippet.
+You are strongly urged to read the Oracle Internationalization documentation
+specifically with respect the choices and trade offs for creating
+a databases for use with international character sets.
-=item Fetching the 14th to 10th Row
+Oracle uses the NLS_LANG environment variable to indicate what
+character set is being used on the client. When fetching data Oracle
+will convert from whatever the database character set is to the client
+character set specified by NLS_LANG. Similarly, when sending data to
+the database Oracle will convert from the character set specified by
+NLS_LANG to the database character set.
- for(my $i=14;$i>9;$i--){
- $value = $sth->ora_fetch_scroll(OCI_FETCH_ABSOLUTE,$i);
- print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
- }
- print "current scroll position=".$sth->ora_scroll_position()."\n";
+The NLS_NCHAR environment variable can be used to define a different
+character set for 'national' (NCHAR) character types.
-The current_positon attribute will be 10 after this snippet.
+Both UTF8 and AL32UTF8 can be used in NLS_LANG and NLS_NCHAR.
+For example:
-=item Fetching the 5th Row From the Present Position.
+ NLS_LANG=AMERICAN_AMERICA.UTF8
+ NLS_LANG=AMERICAN_AMERICA.AL32UTF8
+ NLS_NCHAR=UTF8
+ NLS_NCHAR=AL32UTF8
- $value = $sth->ora_fetch_scroll(OCI_FETCH_RELATIVE,5);
- print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
- print "current scroll position=".$sth->ora_scroll_position()."\n";
+=head5 Oracle UTF8 is not UTF-8
-The current_positon attribute will be 15 after this snippet.
+AL32UTF8 should be used in preference to UTF8 if it works for you,
+which it should for Oracle 9.2 or later. If you're using an old
+version of Oracle that doesn't support AL32UTF8 then you should
+avoid using any Unicode characters that require surrogates, in other
+words characters beyond the Unicode BMP (Basic Multilingual Plane).
-=item Fetching the 9th Row Prior From the Present Position
+That's because the character set that Oracle calls "UTF8" doesn't
+conform to the UTF-8 standard in its handling of surrogate characters.
+Technically the encoding that Oracle calls "UTF8" is known as "CESU-8".
+Here are a couple of extracts from L<http://www.unicode.org/reports/tr26/>:
- $value = $sth->ora_fetch_scroll(OCI_FETCH_RELATIVE,-9);
- print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
- print "current scroll position=".$sth->ora_scroll_position()."\n";
+ CESU-8 is useful in 8-bit processing environments where binary
+ collation with UTF-16 is required. It is designed and recommended
+ for use only within products requiring this UTF-16 binary collation
+ equivalence. It is not intended nor recommended for open interchange.
-The current_positon attribute will be 6 after this snippet.
+ As a very small percentage of characters in a typical data stream
+ are expected to be supplementary characters, there is a strong
+ possibility that CESU-8 data may be misinterpreted as UTF-8.
+ Therefore, all use of CESU-8 outside closed implementations is
+ strongly discouraged, such as the emittance of CESU-8 in output
+ files, markup language or other open transmission forms.
-=item Use Finish
+Oracle uses this internally because it collates (sorts) in the same order
+as UTF16, which is the basis of Oracle's internal collation definitions.
- $sth->finish();
+Rather than change UTF8 for clients Oracle chose to define a new character
+set called "AL32UTF8" which does conform to the UTF-8 standard.
+(The AL32UTF8 character set can't be used on the server because it
+would break collation.)
-When using scrollable cursors it is required that you use the $sth->finish() method when you are done with the cursor as this type of
-cursor has to be explicitly cancelled on the server. If you do not do this you may cause resource problems on your database.
+Because of that, for the rest of this document we'll use "AL32UTF8".
+If you're using an Oracle version below 9.2 you'll need to use "UTF8"
+until you upgrade.
-=back
+=head5 DBD::Oracle and Unicode
-=head1 LOBs and LONGs
+DBD::Oracle Unicode support has been implemented for Oracle versions 9
+or greater, and Perl version 5.6 or greater (though we I<strongly>
+suggest that you use Perl 5.8.2 or later).
-The key to working with LOBs (CLOB, BLOBs) is to remember the value of an Oracle LOB column is not the content of the LOB. It's a
-'LOB Locator' which, after being selected or inserted needs extra processing to read or write the content of the LOB. There are also legacy LONG types (LONG, LONG RAW, VARCHAR2)
-which are presently deprecated by Oracle but are still in use. These LONG types do not utilize a 'LOB Locator' and also are more limited in
-functionality than CLOB or BLOB fields.
+You can check which Oracle version your DBD::Oracle was built with by
+importing the C<ORA_OCI> constant from DBD::Oracle.
-DBD::Oracle now offers three interfaces to LOB and LONG data,
+B<Fetching Data>
-=over
+Any data returned from Oracle to DBD::Oracle in the AL32UTF8
+character set will be marked as UTF-8 to ensure correct handling by Perl.
-=item L</Data Interface for Persistent LOBs>
+For Oracle to return data in the AL32UTF8 character set the
+NLS_LANG or NLS_NCHAR environment variable I<must> be set as described
+in the previous section.
-With this interface DBD::Oracle handles your data directly utilizing regular OCI calls, Oracle itself takes care of the LOB Locator operations in the case of
-BLOBs and CLOBs treating them exactly as if they were the same as the legacy LONG or LONG RAW types.
+When fetching NCHAR, NVARCHAR, or NCLOB data from Oracle, DBD::Oracle
+will set the Perl UTF-8 flag on the returned data if either NLS_NCHAR
+is AL32UTF8, or NLS_NCHAR is not set and NLS_LANG is AL32UTF8.
-=item L</Data Interface for LOB Locators>
+When fetching other character data from Oracle, DBD::Oracle
+will set the Perl UTF-8 flag on the returned data if NLS_LANG is AL32UTF8.
-With this interface DBD::Oracle handles your data utilizing LOB Locator OCI calls so it only works with CLOB and BLOB datatypes. With this interface DBD::Oracle takes care of the LOB Locator operations for you.
+B<Sending Data using Placeholders>
-=item L</LOB Locator Method Interface>
+Data bound to a placeholder is assumed to be in the default client
+character set (specified by NLS_LANG) except for a few special
+cases. These are listed here with the highest precedence first:
-This allows the user direct access to the LOB Locator methods, so you have to take case of the LOB Locator operations yourself.
+If the C<ora_csid> attribute is given to bind_param() then that
+is passed to Oracle and takes precedence.
-=back
+If the value is a Perl Unicode string (UTF-8) then DBD::Oracle
+ensures that Oracle uses the Unicode character set, regardless of
+the NLS_LANG and NLS_NCHAR settings.
-Generally speaking the interface that you will chose will be dependent on what end you are trying to achieve. All have their benefits and
-drawbacks.
+If the placeholder is for inserting an NCLOB then the client NLS_NCHAR
+character set is used. (That's useful but inconsistent with the other behaviour
+so may change. Best to be explicit by using the C<ora_csform>
+attribute.)
-One point to remember when working with LOBs (CLOBs, BLOBs) is if your LOB column can be in one of three states;
+If the C<ora_csform> attribute is given to bind_param() then that
+determines if the value should be assumed to be in the default
+(NLS_LANG) or NCHAR (NLS_NCHAR) client character set.
-=over
-=item NULL
+ use DBD::Oracle qw( SQLCS_IMPLICIT SQLCS_NCHAR );
+ ...
+ $sth->bind_param(1, $value, { ora_csform => SQLCS_NCHAR });
-The table cell is created, but the cell holds no locator or value.
-If your LOB field is in this state then there is no LOB Locator that DBD::Oracle can work so if your encounter a
+or
- DBD::Oracle::db::ora_lob_read: locator is not of type OCILobLocatorPtr
+ $dbh->{ora_ph_csform} = SQLCS_NCHAR; # default for all future placeholders
-error when working with a LOB.
+Binding with bind_param_array and execute_array is also UTF-8 compatible in the same way. If you attempt to
+insert UTF-8 data into a non UTF-8 Oracle instance or with an non UTF-8 NCHAR or NVARCHAR the insert
+will still happen but a error code of 0 will be returned with the following warning;
+
+ DBD Oracle Warning: You have mixed utf8 and non-utf8 in an array bind in parameter#1. This may result in corrupt data.
+ The Query charset id=1, name=US7ASCII
-You can correct this by using an SQL UPDATE statement to reset the LOB column to a non-NULL (or empty LOB) value with either EMPTY_BLOB or EMPTY_CLOB as in this example;
+The warning will report the parameter number and the NCHAR setting that the query is running.
+
+B<Sending Data using SQL>
- UPDATE lob_example
- SET bindata=EMPTY_BLOB()
- WHERE bindata IS NULL.
+Oracle assumes the SQL statement is in the default client character
+set (as specified by NLS_LANG). So Unicode strings containing
+non-ASCII characters should not be used unless the default client
+character set is AL32UTF8.
-=item Empty
+=head5 DBD::Oracle and Other Character Sets and Encodings
-A LOB instance with a locator exists in the cell, but it has no value. The length of the LOB is zero. In this case DBD::Oracle will return 'undef' for the field.
+The only multi-byte Oracle character set supported by DBD::Oracle is
+"AL32UTF8" (and "UTF8"). Single-byte character sets should work well.
-=item Populated
+=head4 Other Data Types
-A LOB instance with a locator and a value exists in the cell. You actually get the LOB value.
+DBD::Oracle does not I<explicitly> support most Oracle datatypes.
+It simply asks Oracle to return them as strings and Oracle does so.
+Mostly. Similarly when binding placeholder values DBD::Oracle binds
+them as strings and Oracle converts them to the appropriate type,
+such as DATE, when used.
-=back
+Some of these automatic conversions to and from strings use NLS
+settings to control the formatting for output and the parsing for
+input. The most common example is the DATE type. The default NLS
+format for DATE might be DD-MON-YYYY and so when a DATE type is
+fetched that's how Oracle will format the date. NLS settings also
+control the default parsing of strings into DATE values. An error
+will be generated if the contents of the string don't match the
+NLS format. If you're dealing in dates which don't match the default
+NLS format then you can either change the default NLS format or, more
+commonly, use TO_CHAR(field, "format") and TO_DATE(?, "format")
+to explicitly specify formats for converting to and from strings.
-=head2 Data Interface for Persistent LOBs
+A slightly more subtle problem can occur with NUMBER types. The
+default NLS settings might format numbers with a fullstop ("C<.>")
+to separate thousands and a comma ("C<,>") as the decimal point.
+Perl will generate warnings and use incorrect values when numbers,
+returned and formatted as strings in this way by Oracle, are used
+in a numeric context. You could explicitly convert each numeric
+value using the TO_CHAR(...) function but that gets tedious very
+quickly. The best fix is to change the NLS settings. That can be
+done for an individual connection by doing:
-This is the original interface for LONG and LONG RAW datatypes and from Oracle 9iR1 and later the OCI API was extended to work directly with the other LOB datatypes.
-In other words you can treat all LOB type data (BLOB, CLOB) as if it was a LONG, LONG RAW, or VARCHAR2. So you can perform INSERT, UPDATE, fetch, bind, and define operations on LOBs using the same techniques
-you would use on other datatypes that store character or binary data. In some cases there are fewer round trips to the server as no 'LOB Locators' are
-used, normally one can get an entire LOB is a single round trip.
+ $dbh->do("ALTER SESSION SET NLS_NUMERIC_CHARACTERS = '.,'");
-=head3 Simple Fetch for LONGs and LONG RAWs
+There are some types, like BOOLEAN, that Oracle does not automatically
+convert to or from strings (pity). These need to be converted
+explicitly using SQL or PL/SQL functions.
-As the name implies this is the simplest way to use this interface. DBD::Oracle just attempts to get your LONG datatypes as a single large piece.
-There are no special settings, simply set the database handle's 'LongReadLen' attribute to a value that will be the larger than the expected size of the LONG or LONG RAW.
-If the size of the LONG or LONG RAW exceeds the 'LongReadLen' DBD::Oracle will return a 'ORA-24345: A Truncation' error. To stop this set the database handle's 'LongTruncOk' attribute to '1'.
-The maximum value of 'LongReadLen' seems to be dependent on the physical memory limits of the box that Oracle is running on. You have most likely reached this limit if you run into
-an 'ORA-01062: unable to allocate memory for define buffer' error. One solution is to set the size of 'LongReadLen' to a lower value.
-For example give this table;
+Examples:
- CREATE TABLE test_long (
- id NUMBER,
- long1 long)
+ # DATE values
+ my $sth0 = $dbh->prepare( <<SQL_END );
+ SELECT username, TO_CHAR( created, ? )
+ FROM all_users
+ WHERE created >= TO_DATE( ?, ? )
+ SQL_END
+ $sth0->execute( 'YYYY-MM-DD HH24:MI:SS', "2003", 'YYYY' );
-this code;
+ # BOOLEAN values
+ my $sth2 = $dbh->prepare( <<PLSQL_END );
+ DECLARE
+ b0 BOOLEAN;
+ b1 BOOLEAN;
+ o0 VARCHAR2(32);
+ o1 VARCHAR2(32);
- $dbh->{LongReadLen} = 2*1024*1024; #2 meg
- $SQL='select p_id,long1 from test_long';
- $sth=$dbh->prepare($SQL);
- $sth->execute();
- while (my ( $p_id,$long )=$sth->fetchrow()){
- print "p_id=".$p_id."\n";
- print "long=".$long."\n";
+ FUNCTION to_bool( i VARCHAR2 ) RETURN BOOLEAN IS
+ BEGIN
+ IF i IS NULL THEN RETURN NULL;
+ ELSIF i = 'F' OR i = '0' THEN RETURN FALSE;
+ ELSE RETURN TRUE;
+ END IF;
+ END;
+ FUNCTION from_bool( i BOOLEAN ) RETURN NUMBER IS
+ BEGIN
+ IF i IS NULL THEN RETURN NULL;
+ ELSIF i THEN RETURN 1;
+ ELSE RETURN 0;
+ END IF;
+ END;
+ BEGIN
+ -- Converting values to BOOLEAN
+ b0 := to_bool( :i0 );
+ b1 := to_bool( :i1 );
+
+ -- Converting values from BOOLEAN
+ :o0 := from_bool( b0 );
+ :o1 := from_bool( b1 );
+ END;
+ PLSQL_END
+ my ( $i0, $i1, $o0, $o1 ) = ( "", "Something else" );
+ $sth2->bind_param( ":i0", $i0 );
+ $sth2->bind_param( ":i1", $i1 );
+ $sth2->bind_param_inout( ":o0", \$o0, 32 );
+ $sth2->bind_param_inout( ":o1", \$o1, 32 );
+ $sth2->execute();
+ foreach ( $i0, $b0, $o0, $i1, $b1, $o1 ) {
+ $_ = "(undef)" if ! defined $_;
}
+ print "$i0 to $o0, $i1 to $o1\n";
+ # Result is : "'' to '(undef)', 'Something else' to '1'"
+
+
+=head5 Object & Collection Data Types
+
+Oracle databases allow for the creation of object oriented like user-defined types.
+There are two types of objects, Embedded--an object stored in a column of a regular table
+and REF--an object that uses the REF retrieval mechanism.
-Will select out all of the long1 fields in the table as long as they are all under 2MB in length. A value in long1 longer than this will throw an error. Adding this line;
+DBD::Oracle supports only the 'selection' of embedded objects of the following types OBJECT, VARRAY
+and TABLE in any combination. Support is seamless and recursive, meaning you
+need only supply a simple SQL statement to get all the values in an embedded object.
+You can either get the values as an array of scalars or they can be returned into a DBD::Oracle::Object.
- $dbh->{LongTruncOk}=1;
-before the execute will return all the long1 fields but they will be truncated at 2MBs.
+Array example, given this type and table;
-=head3 Using ora_ncs_buff_mtpl
+ CREATE OR REPLACE TYPE "PHONE_NUMBERS" as varray(10) of varchar(30);
+
+ CREATE TABLE "CONTACT"
+ ( "COMPANYNAME" VARCHAR2(40),
+ "ADDRESS" VARCHAR2(100),
+ "PHONE_NUMBERS" "PHONE_NUMBERS"
+ )
-When getting CLOBs and NCLOBs in or out of Oracle, the Server will translate from the Server's NCharSet to the
-Client's. If they happen to be the same or at least compatible then all of these actions are a 1 char to 1 char bases.
-Thus if you set your LongReadLen buffer to 10_000_000 you will get up to 10_000_000 char.
+The code to access all the data in the table could be something like this;
-However if the Server has to translate from one NCharSet to another it will use bytes for conversion. The buffer
-value is set to 4 * LONG_READ_LEN which was very wasteful as you might only be asking for 10_000_000 bytes
-but you were actually using 40_000_000 bytes of buffer under the hood. You would still get 10_000_000 bytes
-(maybe less characters though) but you are using allot more memory that you need.
+ my $sth = $dbh->prepare('SELECT * FROM CONTACT');
+ $sth->execute;
+ while ( my ($company, $address, $phone) = $sth->fetchrow()) {
+ print "Company: ".$company."\n";
+ print "Address: ".$address."\n";
+ print "Phone #: ";
+
+ foreach my $items (@$phone){
+ print $items.", ";
+ }
+ print "\n";
+ }
-You can now customize the size of the buffer by setting the 'ora_ncs_buff_mtpl' either on the connection or statement handle. You can
-also set this as 'ORA_DBD_NCS_BUFFER' OS environment variable so you will have to go back and change all your code if you are getting into trouble.
+Note that values in PHONE_NUMBERS are returned as an array reference '@$phone'.
-The default value is still set to 4 for backward compatibility. You can lower this value and thus increase the amount of data you can retrieve. If the
-ora_ncs_buff_mtpl is too small DBD::Oracle will throw and error telling you to increase this buffer by one.
+As stated before DBD::Oracle will automatically drill into the embedded object and extract
+all of the data as reference arrays of scalars. The example below has OBJECT type embedded in a TABLE type embedded in an
+SQL TABLE;
-If the error is not captured then you may get at some random point later on, usually at a finish() or disconnect() or even a fetch() this error;
+ CREATE OR REPLACE TYPE GRADELIST AS TABLE OF NUMBER;
- ORA-03127: no new operations allowed until the active operation ends
+ CREATE OR REPLACE TYPE STUDENT AS OBJECT(
+ NAME VARCHAR2(60),
+ SOME_GRADES GRADELIST);
-This is one of the more obscure ORA errors (have some fun and report it to Meta-Link they will scratch their heads for hours)
+ CREATE OR REPLACE TYPE STUDENTS_T AS TABLE OF STUDENT;
-If you get this, simply increment the ora_ncs_buff_mtpl by one until it goes away.
+ CREATE TABLE GROUPS(
+ GRP_ID NUMBER(4),
+ GRP_NAME VARCHAR2(10),
+ STUDENTS STUDENTS_T)
+ NESTED TABLE STUDENTS STORE AS GROUP_STUDENTS_TAB
+ (NESTED TABLE SOME_GRADES STORE AS GROUP_STUDENT_GRADES_TAB);
-This should greatly increase your ability to select very large CLOBs or NCLOBs, by freeing up a large block of memory.
+The following code will access all of the embedded data;
-You can tune this value by setting ora_oci_success_warn which will display the following
+ $SQL='select grp_id,grp_name,students as my_students_test from groups';
+ $sth=$dbh->prepare($SQL);
+ $sth->execute();
+ while (my ($grp_id,$grp_name,$students)=$sth->fetchrow()){
+ print "Group ID#".$grp_id." Group Name =".$grp_name."\n";
+ foreach my $student (@$students){
+ print "Name:".$student->[0]."\n";
+ print "Marks:";
+ foreach my $grades (@$student->[1]){
+ foreach my $marks (@$grades){
+ print $marks.",";
+ }
+ }
+ print "\n";
+ }
+ print "\n";
+ }
- OCILobRead field 2 of 3 SUCCESS: csform 1 (SQLCS_IMPLICIT), LOBlen 10240(characters), LongReadLen
- 20(characters), BufLen 80(characters), Got 28(characters)
+Object example, given this object and table;
-In the case above the query Got 28 characters (well really only 20 characters of 28 bytes) so we could use ora_ncs_buff_mtpl=>2 (20*2=40) thus saving 40bytes of memory.
+ CREATE OR REPLACE TYPE Person AS OBJECT (
+ name VARCHAR2(20),
+ age INTEGER)
+ ) NOT FINAL;
+ CREATE TYPE Employee UNDER Person (
+ salary NUMERIC(8,2)
+ );
-=head3 Simple Fetch for CLOBs and BLOBs
+ CREATE TABLE people (id INTEGER, obj Person);
+
+ INSERT INTO people VALUES (1, Person('Black', 25));
+ INSERT INTO people VALUES (2, Employee('Smith', 44, 5000));
-To use this interface for CLOBs and LOBs datatypes set the 'ora_pers_lob' attribute of the statement handle to '1' with the prepare method, as well
-set the database handle's 'LongReadLen' attribute to a value that will be the larger than the expected size of the LOB. If the size of the LOB exceeds
-the 'LongReadLen' DBD::Oracle will return a 'ORA-24345: A Truncation' error. To stop this set the database handle's 'LongTruncOk' attribute to '1'.
-The maximum value of 'LongReadLen' seems to be dependent on the physical memory limits of the box that Oracle is running on in the same way that LONGs and LONG RAWs are.
+The following code will access the data;
-For CLOBs and NCLOBs the limit is 64k chars if there is no truncation, this is an internal OCI limit complain to them if you want it changed. However if you CLOB is longer than this
-and also larger than the 'LongReadLen' than the 'LongReadLen' in chars is returned.
+ $dbh{'ora_objects'} =>1;
+
+ $sth = $dbh->prepare("select * from people order by id");
+ $sth->execute();
+
+ # object are fetched as instance of DBD::Oracle::Object
+ my ($id1, $obj1) = $sth->fetchrow();
+ my ($id2, $obj2) = $sth->fetchrow();
+
+ # get full type-name of object
+ print $obj1->type_name."44\n"; # 'TEST.PERSON' is printed
+ print $obj2->type_name."4\n"; # 'TEST.EMPLOYEE' is printed
+
+ # get attribute NAME from object
+ print $obj1->attr('NAME')."3\n"; # 'Black' is printed
+ print $obj2->attr('NAME')."3\n"; # 'Smith' is printed
+
+ # get all atributes as hash reference
+ my $h1 = $obj1->attr; # returns {'NAME' => 'Black', 'AGE' => 25}
+ my $h2 = $obj2->attr; # returns {'NAME' => 'Smith', 'AGE' => 44,
+ # 'SALARY' => 5000 }
+
+ # get all attributes (names and values) as array
+ my @a1 = $obj1->attributes; # returns ('NAME', 'Black', 'AGE', 25)
+ my @a2 = $obj2->attributes; # returns ('NAME', 'Smith', 'AGE', 44,
+ # 'SALARY', 5000 )
+
+So far DBD::Oracle has been tested on a table with 20 embedded Objects, Varrays and Tables
+nested to 10 levels.
-It seems with BLOBs you are not limited by the 64k.
+Any NULL values found in the embedded object will be returned as 'undef'.
-For example give this table;
+=head5 Support for Insert of XMLType (ORA_XMLTYPE)
- CREATE TABLE test_lob (id NUMBER,
- clob1 CLOB,
- clob2 CLOB,
- blob1 BLOB,
- blob2 BLOB)
+Inserting large XML data sets into tables with XMLType fields is now supported by DBD::Oracle. The only special
+requirement is the use of bind_param() with an attribute hash parameter that specifies ora_type as ORA_XMLTYPE. For
+example with a table like this;
-this code;
+ create table books (book_id number, book_xml XMLType);
- $dbh->{LongReadLen} = 2*1024*1024; #2 meg
- $SQL='select p_id,lob_1,lob_2,blob_2 from test_lobs';
- $sth=$dbh->prepare($SQL,{ora_pers_lob=>1});
- $sth->execute();
- while (my ( $p_id,$log,$log2,$log3,$log4 )=$sth->fetchrow()){
- print "p_id=".$p_id."\n";
- print "clob1=".$clob1."\n";
- print "clob2=".$clob2."\n";
- print "blob1=".$blob2."\n";
- print "blob2=".$blob2."\n";
- }
+one can insert data using this code
-Will select out all of the LOBs in the table as long as they are all under 2MB in length. Longer lobs will throw an error. Adding this line;
+ $SQL='insert into books values (1,:p_xml)';
+ $xml= '<Books>
+ <Book id=1>
+ <Title>Programming the Perl DBI</Title>
+ <Subtitle>The Cheetah Book</Subtitle>
+ <Authors>
+ <Author>T. Bunce</Author>
+ <Author>Alligator Descartes</Author>
+ </Authors>
+
+ </Book>
+ <Book id=10000>...
+ </Books>';
+ my $sth =$dbh-> prepare($SQL);
+ $sth-> bind_param("p_xml", $xml, { ora_type => ORA_XMLTYPE });
+ $sth-> execute();
+
+In the above case we will assume that $xml has 10000 Book nodes and is over 32k in size and is well formed XML.
+This will also work for XML that is smaller than 32k as well. Attempting to insert malformed XML will cause an error.
- $dbh->{LongTruncOk}=1;
+=head4 Binding Cursors
-before the execute will return all the lobs but they will be truncated at 2MBs.
+Cursors can be returned from PL/SQL blocks, either from stored
+functions (or procedures with OUT parameters) or
+from direct C<OPEN> statements, as shown below:
-=head3 Piecewise Fetch with Callback
+ use DBI;
+ use DBD::Oracle qw(:ora_types);
+ my $dbh = DBI->connect(...);
+ my $sth1 = $dbh->prepare(q{
+ BEGIN OPEN :cursor FOR
+ SELECT table_name, tablespace_name
+ FROM user_tables WHERE tablespace_name = :space;
+ END;
+ });
+ $sth1->bind_param(":space", "USERS");
+ my $sth2;
+ $sth1->bind_param_inout(":cursor", \$sth2, 0, { ora_type => ORA_RSET } );
+ $sth1->execute;
+ # $sth2 is now a valid DBI statement handle for the cursor
+ while ( my @row = $sth2->fetchrow_array ) { ... }
-With a piecewise callback fetch DBD::Oracle sets up a function that will 'callback' to the DB during the fetch and gets your LOB (LONG, LONG RAW, CLOB, BLOB) piece by piece.
-To use this interface set the 'ora_clbk_lob' attribute of the statement handle to '1' with the prepare method. Next set the 'ora_piece_size' to the size of the piece that
-you want to return on the callback. Finally set the database handle's 'LongReadLen' attribute to a value that will be the larger than the expected
-size of the LOB. Like the L</Simple Fetch for LONGs and LONG RAWs> and L</Simple Fetch for CLOBs and BLOBs> the if the size of the LOB exceeds the is 'LongReadLen' you can use the 'LongTruncOk' attribute to truncate the LOB
-or set the 'LongReadLen' to a higher value. With this interface the value of 'ora_piece_size' seems to be constrained by the same memory limit as found on
-the Simple Fetch interface. If you encounter an 'ORA-01062' error try setting the value of 'ora_piece_size' to a smaller value. The value for 'LongReadLen' is
-dependent on the version and settings of the Oracle DB you are using. In theory it ranges from 8GBs
-in 9iR1 up to 128 terabytes with 11g but you will also be limited by the physical memory of your Perl instance.
+The only special requirement is the use of C<bind_param_inout()> with an
+attribute hash parameter that specifies C<ora_type> as C<ORA_RSET>.
+If you don't do that you'll get an error from the C<execute()> like:
+"ORA-06550: line X, column Y: PLS-00306: wrong number or types of
+arguments in call to ...".
-Using the table from the last example this code;
+Here's an alternative form using a function that returns a cursor.
+This example uses the pre-defined weak (or generic) REF CURSOR type
+SYS_REFCURSOR. This is an Oracle 9 feature.
- $dbh->{LongReadLen} = 20*1024*1024; #20 meg
- $SQL='select p_id,lob_1,lob_2,blob_2 from test_lobs';
- $sth=$dbh->prepare($SQL,{ora_clbk_lob=>1,ora_piece_size=>5*1024*1024});
- $sth->execute();
- while (my ( $p_id,$log,$log2,$log3,$log4 )=$sth->fetchrow()){
- print "p_id=".$p_id."\n";
- print "clob1=".$clob1."\n";
- print "clob2=".$clob2."\n";
- print "blob1=".$blob2."\n";
- print "blob2=".$blob2."\n";
- }
+ # Create the function that returns a cursor
+ $dbh->do(q{
+ CREATE OR REPLACE FUNCTION sp_ListEmp RETURN SYS_REFCURSOR
+ AS l_cursor SYS_REFCURSOR;
+ BEGIN
+ OPEN l_cursor FOR select ename, empno from emp
+ ORDER BY ename;
+ RETURN l_cursor;
+ END;
+ });
-Will select out all of the LOBs in the table as long as they are all under 20MB in length. If the LOB is longer than 5MB (ora_piece_size) DBD::Oracle will fetch it in at least 2 pieces to a
-maximum of 4 pieces (4*5MB=20MB). Like the Simple Fetch examples Lobs longer than 20MB will throw an error.
+ # Use the function that returns a cursor
+ my $sth1 = $dbh->prepare(q{BEGIN :cursor := sp_ListEmp; END;});
+ my $sth2;
+ $sth1->bind_param_inout(":cursor", \$sth2, 0, { ora_type => ORA_RSET } );
+ $sth1->execute;
+ # $sth2 is now a valid DBI statement handle for the cursor
+ while ( my @row = $sth2->fetchrow_array ) { ... }
-Using the table from the first example (LONG) this code;
+A cursor obtained from PL/SQL as above may be passed back to PL/SQL
+by binding for input, as shown in this example, which explicitly
+closes a cursor:
- $dbh->{LongReadLen} = 20*1024*1024; #2 meg
- $SQL='select p_id,long1 from test_long';
- $sth=$dbh->prepare($SQL,{ora_clbk_lob=>1,ora_piece_size=>5*1024*1024});
- $sth->execute();
- while (my ( $p_id,$long )=$sth->fetchrow()){
- print "p_id=".$p_id."\n";
- print "long=".$long."\n";
- }
+ my $sth3 = $dbh->prepare("BEGIN CLOSE :cursor; END;");
+ $sth3->bind_param(":cursor", $sth2, { ora_type => ORA_RSET } );
+ $sth3->execute;
-Will select all of the long1 fields from table as long as they are is under 20MB in length. If the long1 filed is longer than 5MB (ora_piece_size) DBD::Oracle will fetch it in at least 2 pieces to a
-maximum of 4 pieces (4*5MB=20MB). Like the other examples long1 fields longer than 20MB will throw an error.
+It is not normally necessary to close a cursor
+explicitly in this way. Oracle will close the cursor automatically
+at the first client-server interaction after the cursor statement handle is
+destroyed. An explicit close may be desirable if the reference to
+the cursor handle from the PL/SQL statement handle delays the destruction
+of the cursor handle for too long. This reference remains until the
+PL/SQL handle is re-bound, re-executed or destroyed.
-=head3 Piecewise Fetch with Polling
+See the C<curref.pl> script in the Oracle.ex directory in the DBD::Oracle
+source distribution for a complete working example.
-With a polling piecewise fetch DBD::Oracle iterates (Polls) over the LOB during the fetch getting your LOB (LONG, LONG RAW, CLOB, BLOB) piece by piece. To use this interface set the 'ora_piece_lob'
-attribute of the statement handle to '1' with the prepare method. Next set the 'ora_piece_size' to the size of the piece that
-you want to return on the callback. Finally set the database handle's 'LongReadLen' attribute to a value that will be the larger than the expected
-size of the LOB. Like the L</Piecewise Fetch with Callback> and Simple Fetches if the size of the LOB exceeds the is 'LongReadLen' you can use the 'LongTruncOk' attribute to truncate the LOB
-or set the 'LongReadLen' to a higher value. With this interface the value of 'ora_piece_size' seems to be constrained by the same memory limit as found on
-the L</Piecewise Fetch with Callback>.
+=head4 Fetching Nested Cursors
-Using the table from the example above this code;
+Oracle supports the use of select list expressions of type REF CURSOR.
+These may be explicit cursor expressions - C<CURSOR(SELECT ...)>, or
+calls to PL/SQL functions which return REF CURSOR values. The values
+of these expressions are known as nested cursors.
- $dbh->{LongReadLen} = 20*1024*1024; #20 meg
- $SQL='select p_id,lob_1,lob_2,blob_2 from test_lobs';
- $sth=$dbh->prepare($SQL,{ora_piece_lob=>1,ora_piece_size=>5*1024*1024});
- $sth->execute();
- while (my ( $p_id,$log,$log2,$log3,$log4 )=$sth->fetchrow()){
- print "p_id=".$p_id."\n";
- print "clob1=".$clob1."\n";
- print "clob2=".$clob2."\n";
- print "blob1=".$blob2."\n";
- print "blob2=".$blob2."\n";
- }
-
-Will select out all of the LOBs in the table as long as they are all under 20MB in length. If the LOB is longer than 5MB (ora_piece_size) DBD::Oracle will fetch it in at least 2 pieces to a
-maximum of 4 pieces (4*5MB=20MB). Like the other fetch methods LOBs longer than 20MB will throw an error.
-
-Finally with this code;
-
- $dbh->{LongReadLen} = 20*1024*1024; #2 meg
- $SQL='select p_id,long1 from test_long';
- $sth=$dbh->prepare($SQL,{ora_piece_lob=>1,ora_piece_size=>5*1024*1024});
- $sth->execute();
- while (my ( $p_id,$long )=$sth->fetchrow()){
- print "p_id=".$p_id."\n";
- print "long=".$long."\n";
- }
-
-Will select all of the long1 fields from table as long as they are is under 20MB in length. If the long1 field is longer than 5MB (ora_piece_size) DBD::Oracle will fetch it in at least 2 pieces to a
-maximum of 4 pieces (4*5MB=20MB). Like the other examples long1 fields longer than 20MB will throw an error.
+The value returned to a Perl program when a nested cursor is fetched
+is a statement handle. This statement handle is ready to be fetched from.
+It should not (indeed, must not) be executed.
-=head3 Binding for Updates and Inserts for CLOBs and BLOBs
+Oracle imposes a restriction on the order of fetching when nested
+cursors are used. Suppose C<$sth1> is a handle for a select statement
+involving nested cursors, and C<$sth2> is a nested cursor handle fetched
+from C<$sth1>. C<$sth2> can only be fetched from while C<$sth1> is
+still active, and the row containing C<$sth2> is still current in C<$sth1>.
+Any attempt to fetch another row from C<$sth1> renders all nested cursor
+handles previously fetched from C<$sth1> defunct.
-To bind for updates and inserts all that is required to use this interface is to set the statement handle's prepare method
-'ora_type' attribute to 'SQLT_CHR' in the case of CLOBs and NCLOBs or 'SQLT_BIN' in the case of BLOBs as in this example for an insert;
+Fetching from such a defunct handle results in an error with the message
+C<ERROR nested cursor is defunct (parent row is no longer current)>.
- my $in_clob = "<document>\n";
- $in_clob .= " <value>$_</value>\n" for 1 .. 10_000;
- $in_clob .= "</document>\n";
- my $in_blob ="0101" for 1 .. 10_000;
+This means that the C<fetchall...> or C<selectall...> methods are not useful
+for queries returning nested cursors. By the time such a method returns,
+all the nested cursor handles it has fetched will be defunct.
- $SQL='insert into test_lob3@tpgtest (id,clob1,clob2, blob1,blob2) values(?,?,?,?,?)';
- $sth=$dbh->prepare($SQL );
- $sth->bind_param(1,3);
- $sth->bind_param(2,$in_clob,{ora_type=>SQLT_CHR});
- $sth->bind_param(3,$in_clob,{ora_type=>SQLT_CHR});
- $sth->bind_param(4,$in_blob,{ora_type=>SQLT_BIN});
- $sth->bind_param(5,$in_blob,{ora_type=>SQLT_BIN});
- $sth->execute();
+It is necessary to use an explicit fetch loop, and to do all the
+fetching of nested cursors within the loop, as the following example
+shows:
-So far the only limit reached with this form of insert is the LOBs must be under 2GB in size.
+ use DBI;
+ my $dbh = DBI->connect(...);
+ my $sth = $dbh->prepare(q{
+ SELECT dname, CURSOR(
+ SELECT ename FROM emp
+ WHERE emp.deptno = dept.deptno
+ ORDER BY ename
+ ) FROM dept ORDER BY dname
+ });
+ $sth->execute;
+ while ( my ($dname, $nested) = $sth->fetchrow_array ) {
+ print "$dname\n";
+ while ( my ($ename) = $nested->fetchrow_array ) {
+ print " $ename\n";
+ }
+ }
-=head3 Support for Remote LOBs;
-Starting with Oracle 10gR2 the interface for Persistent LOBs was expanded to support remote LOBs (access over a dblink). Given a database called 'lob_test' that has a 'LINK' defined like this;
+The cursor returned by the function C<sp_ListEmp> defined in the
+previous section can be fetched as a nested cursor as follows:
- CREATE DATABASE LINK link_test CONNECT TO test_lobs IDENTIFIED BY tester USING 'lob_test';
+ my $sth = $dbh->prepare(q{SELECT sp_ListEmp FROM dual});
+ $sth->execute;
+ my ($nested) = $sth->fetchrow_array;
+ while ( my @row = $nested->fetchrow_array ) { ... }
-to a remote database called 'test_lobs', the following code will work;
+=head4 Pre-fetching Nested Cursors
- $dbh = DBI->connect('dbi:Oracle:','test@lob_test','test');
- $dbh->{LongReadLen} = 2*1024*1024; #2 meg
- $SQL='select p_id,lob_1,lob_2,blob_2 from test_lobs@link_test';
- $sth=$dbh->prepare($SQL,{ora_pers_lob=>1});
- $sth->execute();
- while (my ( $p_id,$log,$log2,$log3,$log4 )=$sth->fetchrow()){
- print "p_id=".$p_id."\n";
- print "clob1=".$clob1."\n";
- print "clob2=".$clob2."\n";
- print "blob1=".$blob2."\n";
- print "blob2=".$blob2."\n";
- }
+By default, DBD::Oracle pre-fetches rows in order to reduce the number of
+round trips to the server. For queries which do not involve nested cursors,
+the number of pre-fetched rows is controlled by the DBI database handle
+attribute C<RowCacheSize> (q.v.).
-Below are the limitations of Remote LOBs;
+In Oracle, server side open cursors are a controlled resource, limited in
+number, on a per session basis, to the value of the initialization
+parameter C<OPEN_CURSORS>. Nested cursors count towards this limit.
+Each nested cursor in the current row counts 1, as does
+each nested cursor in a pre-fetched row. Defunct nested cursors do not count.
-=over
+An Oracle specific database handle attribute, C<ora_max_nested_cursors>,
+further controls pre-fetching for queries involving nested cursors. For
+each statement handle, the total number of nested cursors in pre-fetched
+rows is limited to the value of this parameter. The default value
+is 0, which disables pre-fetching for queries involving nested cursors.
-=item Queries involving more than one database are not supported;
-so the following returns an error:
+=head3 B<bind_param_inout>
- SELECT t1.lobcol,
- a2.lobcol
- FROM t1,
- t2.lobcol@dbs2 a2 W
- WHERE LENGTH(t1.lobcol) = LENGTH(a2.lobcol);
+ $rv = $sth->bind_param_inout($param_num, \$scalar, 0);
+
+
+DBD::Oracle fully supports bind_param_inout below are some uses for this method.
-as does:
- SELECT t1.lobcol
- FROM t1@dbs1
- UNION ALL
- SELECT t2.lobcol
- FROM t2@dbs2;
+=head4 B<Returning A Value from an INSERT>
-=item DDL commands are not supported;
+Oracle supports an extended SQL insert syntax which will return one
+or more of the values inserted. This can be particularly useful for
+single-pass insertion of values with re-used sequence values
+(avoiding a separate "select seq.nextval from dual" step).
-so the following returns an error:
+ $sth = $dbh->prepare(qq{
+ INSERT INTO foo (id, bar)
+ VALUES (foo_id_seq.nextval, :bar)
+ RETURNING id INTO :id
+ });
+ $sth->bind_param(":bar", 42);
+ $sth->bind_param_inout(":id", \my $new_id, 99);
+ $sth->execute;
+ print "The id of the new record is $new_id\n";
- CREATE VIEW v AS SELECT lob_col FROM tab@dbs;
+If you have many columns to bind you can use code like this:
-=item Only binds and defines for data going into remote persistent LOBs are supported.
+ @params = (... column values for record to be inserted ...);
+ $sth->bind_param($_, $params[$_-1]) for (1..@params);
+ $sth->bind_param_inout(@params+1, \my $new_id, 99);
+ $sth->execute;
-so that parameter passing in PL/SQL where CHAR data is bound or defined for remote LOBs is not allowed .
+If you have many rows to insert you can take advantage of Oracle's built in execute array feature
+with code like this:
-These statements all produce errors:
+ my @in_values=('1',2,'3','4',5,'6',7,'8',9,'10');
+ my @out_values;
+ my @status;
+ my $sth = $dbh->prepare(qq{
+ INSERT INTO foo (id, bar)
+ VALUES (foo_id_seq.nextval, ?)
+ RETURNING id INTO ?
+ });
+ $sth->bind_param_array(1,\@in_values);
+ $sth->bind_param_inout_array(2,\@out_values,0,{ora_type => ORA_VARCHAR2});
+ $sth->execute_array({ArrayTupleStatus=>\@status}) or die "error inserting";
+ foreach my $id (@out_values){
+ print 'returned id='.$id.'\n';
+ }
+
+Which will return all the ids into @out_values.
- SELECT foo() FROM table1@dbs2;
+=over
- SELECT foo()@dbs INTO char_val FROM DUAL;
+B<Note:>
- SELECT XMLType().getclobval FROM table1@dbs2;
+=item 1 This will only work for numbered (?) placeholders,
-=item If the remote object is a view such as
+=item 2 The third parameter of bind_param_inout_array, (0 in the example), "maxlen" is required by DBI but not used by DBD::Oracle
- CREATE VIEW v AS SELECT foo() FROM ...
+=item 3 The "ora_type" attribute is not needed but only ORA_VARCHAR2 will work.
-the following would not work:
+=back
- SELECT * FROM v@dbs2;
+=head4 Returning A Recordset
-=item Limited PL/SQL parameter passing
+DBD::Oracle does not currently support binding a PL/SQL table (aka array)
+as an IN OUT parameter to any Perl data structure. You cannot therefore call
+a PL/SQL function or procedure from DBI that uses a non-atomic datatype as
+either a parameter, or a return value. However, if you are using Oracle 9.0.1
+or later, you can make use of table (or pipelined) functions.
-PL/SQL parameter passing is not allowed where the actual argument is a LOB type
-and the remote argument is one of VARCHAR2, NVARCHAR2, CHAR, NCHAR, or RAW.
+For example, assume you have the existing PL/SQL Package :
-=item RETURNING INTO does not support implicit conversions between CHAR and CLOB.
+ CREATE OR REPLACE PACKAGE Array_Example AS
+ --
+ TYPE tRec IS RECORD (
+ Col1 NUMBER,
+ Col2 VARCHAR2 (10),
+ Col3 DATE) ;
+ --
+ TYPE taRec IS TABLE OF tRec INDEX BY BINARY_INTEGER ;
+ --
+ FUNCTION Array_Func RETURN taRec ;
+ --
+ END Array_Example ;
-so the following returns an error:
+ CREATE OR REPLACE PACKAGE BODY Array_Example AS
+ --
+ FUNCTION Array_Func RETURN taRec AS
+ --
+ l_Ret taRec ;
+ --
+ BEGIN
+ FOR i IN 1 .. 5 LOOP
+ l_Ret (i).Col1 := i ;
+ l_Ret (i).Col2 := 'Row : ' || i ;
+ l_Ret (i).Col3 := TRUNC (SYSDATE) + i ;
+ END LOOP ;
+ RETURN l_Ret ;
+ END ;
+ --
+ END Array_Example ;
+ /
- SELECT t1.lobcol as test, a2.lobcol FROM t1, t2.lobcol@dbs2 a2 RETURNING test
+Currently, there is no way to directly call the function
+Array_Example.Array_Func from DBI. However, by making the following relatively
+painless additions, its not only possible, but extremely efficient.
-=back
+First, you need to create database object types that correspond to the record
+and table types in the package. From the above example, these would be :
-=head2 Locator Data Interface
+ CREATE OR REPLACE TYPE tArray_Example__taRec
+ AS OBJECT (
+ Col1 NUMBER,
+ Col2 VARCHAR2 (10),
+ Col3 DATE
+ ) ;
-=head3 Simple Usage
+ CREATE OR REPLACE TYPE taArray_Example__taRec
+ AS TABLE OF tArray_Example__taRec ;
-When fetching LOBs with this interface a 'LOB Locator' is created then used to get the lob with the LongReadLen and LongTruncOk attributes.
-The value for 'LongReadLen' is dependent on the version and settings of the Oracle DB you are using. In theory it ranges from 8GBs
-in 9iR1 up to 128 terabytes with 11g but you will also be limited by the physical memory of your Perl instance.
+Now, assuming the existing function needs to remain unchanged (it is probably
+being called from other PL/SQL code), we need to add a new function to the
+package. Here's the new package specification and body :
-When inserting or updating LOBs some I<major> magic has to be performed
-behind the scenes to make it transparent. Basically the driver has to
-insert a 'LOB Locator' and then refetch the newly inserted LOB
-Locator before being able to write the data into it. However, it works
-well most of the time, and I've made it as fast as possible, just one
-extra server-round-trip per insert or update after the first. For the
-time being, only single-row LOB updates are supported.
+ CREATE OR REPLACE PACKAGE Array_Example AS
+ --
+ TYPE tRec IS RECORD (
+ Col1 NUMBER,
+ Col2 VARCHAR2 (10),
+ Col3 DATE) ;
+ --
+ TYPE taRec IS TABLE OF tRec INDEX BY BINARY_INTEGER ;
+ --
+ FUNCTION Array_Func RETURN taRec ;
+ FUNCTION Array_Func_DBI RETURN taArray_Example__taRec PIPELINED ;
+ --
+ END Array_Example ;
-To insert or update a large LOB using a placeholder, DBD::Oracle has to
-know in advance that it is a LOB type. So you need to say:
+ CREATE OR REPLACE PACKAGE BODY Array_Example AS
+ --
+ FUNCTION Array_Func RETURN taRec AS
+ l_Ret taRec ;
+ BEGIN
+ FOR i IN 1 .. 5 LOOP
+ l_Ret (i).Col1 := i ;
+ l_Ret (i).Col2 := 'Row : ' || i ;
+ l_Ret (i).Col3 := TRUNC (SYSDATE) + i ;
+ END LOOP ;
+ RETURN l_Ret ;
+ END ;
- $sth->bind_param($field_num, $lob_value, { ora_type => ORA_CLOB });
+ FUNCTION Array_Func_DBI RETURN taArray_Example__taRec PIPELINED AS
+ l_Set taRec ;
+ BEGIN
+ l_Set := Array_Func ;
+ FOR i IN l_Set.FIRST .. l_Set.LAST LOOP
+ PIPE ROW (
+ tArray_Example__taRec (
+ l_Set (i).Col1,
+ l_Set (i).Col2,
+ l_Set (i).Col3
+ )
+ ) ;
+ END LOOP ;
+ RETURN ;
+ END ;
+ --
+ END Array_Example ;
-The ORA_CLOB and ORA_BLOB constants can be imported using
+As you can see, the new function is very simple. Now, it is a simple matter
+of calling the function as a straight-forward SELECT from your DBI code. From
+the above example, the code would look something like this :
- use DBD::Oracle qw(:ora_types);
+ my $sth = $dbh->prepare('SELECT * FROM TABLE(Array_Example.Array_Func_DBI)');
+ $sth->execute;
+ while ( my ($col1, $col2, $col3) = $sth->fetchrow_array {
+ ...
+ }
-or use the corresponding integer values (112 and 113).
-One further wrinkle: for inserts and updates of LOBs, DBD::Oracle has
-to be able to tell which parameters relate to which table fields.
-In all cases where it can possibly work it out for itself, it does,
-however, if there are multiple LOB fields of the same type in the table
-then you need to tell it which field each LOB param relates to:
- $sth->bind_param($idx, $value, { ora_type=>ORA_CLOB, ora_field=>'foo' });
-There are some limitations inherent in the way DBD::Oracle makes typical
-LOB operations simple by hiding the LOB Locator processing:
- - Can't read/write LOBs in chunks (except via DBMS_LOB.WRITEAPPEND in PL/SQL)
- - To INSERT a LOB, you need UPDATE privilege.
+=head4 B<SYS.DBMS_SQL datatypes>
-The alternative is to disable the automatic LOB Locator processing.
-If L</ora_auto_lob> is 0 in prepare(), you can fetch the LOB Locators and
-do all the work yourself using the ora_lob_*() methods.
-See the L</Data Interface for LOB Locators> section below.
+DBD::Oracle has built-in support for B<SYS.DBMS_SQL.VARCHAR2_TABLE>
+and B<SYS.DBMS_SQL.NUMBER_TABLE> datatypes. The simple example is here:
-=head3 LOB support in PL/SQL
+ my $statement='
+ DECLARE
+ tbl SYS.DBMS_SQL.VARCHAR2_TABLE;
+ BEGIN
+ tbl := :mytable;
+ :cc := tbl.count();
+ tbl(1) := \'def\';
+ tbl(2) := \'ijk\';
+ :mytable := tbl;
+ END;
+ ';
-LOB Locators can be passed to PL/SQL calls by binding them to placeholders
-with the proper C<ora_type>. If L</ora_auto_lob> is true, output LOB
-parameters will be automatically returned as strings.
+ my $sth=$dbh->prepare( $statement );
-If the Oracle driver has support for temporary LOBs (Oracle 9i and higher),
-strings can be bound to input LOB placeholders and will be automatically
-converted to LOBs.
+ my @arr=( "abc","efg","hij" );
-Example:
- # Build a large XML document, bind it as a CLOB,
- # extract elements through PL/SQL and return as a CLOB
+ $sth->bind_param_inout(":mytable", \\@arr, 10, {
+ ora_type => ORA_VARCHAR2_TABLE,
+ ora_maxarray_numentries => 100
+ } ) ;
+ $sth->bind_param_inout(":cc", \$cc, 100 );
+ $sth->execute();
+ print "Result: cc=",$cc,"\n",
+ "\tarr=",Data::Dumper::Dumper(\@arr),"\n";
- # $dbh is a connected database handle
- # output will be large
+=over
- local $dbh->{LongReadLen} = 1_000_000;
+B<Note:>
+
+ Take careful note that we use '\\@arr' here because the 'bind_param_inout'
+ will only take a reference to a scalar.
- my $in_clob = "<document>\n";
- $in_clob .= " <value>$_</value>\n" for 1 .. 10_000;
- $in_clob .= "</document>\n";
+=back
- my $out_clob;
- my $sth = $dbh->prepare(<<PLSQL_END);
- -- extract 'value' nodes
- DECLARE
- x XMLTYPE := XMLTYPE(:in);
- BEGIN
- :out := x.extract('/document/value').getClobVal();
- END;
+=head4 B<ORA_VARCHAR2_TABLE>
- PLSQL_END
+SYS.DBMS_SQL.VARCHAR2_TABLE object is always bound to array reference.
+( in bind_param() and bind_param_inout() ). When you bind array, you need
+to specify full buffer size for OUT data. So, there are two parameters:
+I<max_len> (specified as 3rd argument of bind_param_inout() ),
+and I<ora_maxarray_numentries>. They define maximum array entry length and
+maximum rows, that can be passed to Oracle and back to you. In this
+example we send array with 1 element with length=3, but allocate space for 100
+Oracle array entries with maximum length 10 of each. So, you can get no more
+than 100 array entries with length <= 10.
- # :in param will be converted to a temp lob
- # :out parameter will be returned as a string.
+If you set I<max_len> to zero, maximum array entry length is calculated
+as maximum length of entry of array bound. If 0 < I<max_len> < length( $some_element ),
+truncation occur.
- $sth->bind_param( ':in', $in_clob, { ora_type => ORA_CLOB } );
- $sth->bind_param_inout( ':out', \$out_clob, 0, { ora_type => ORA_CLOB } );
- $sth->execute;
+If you set I<ora_maxarray_numentries> to zero, current (at bind time) bound
+array length is used as maximum. If 0 < I<ora_maxarray_numentries> < scalar(@array),
+not all array entries are bound.
-If you ever get an
+=head4 B<ORA_NUMBER_TABLE>
- ORA-01691 unable to extend lob segment sss.ggg by nnn in tablespace ttt
+SYS.DBMS_SQL.NUMBER_TABLE object handling is much alike ORA_VARCHAR2_TABLE.
+The main difference is internal data representation. Currently 2 types of
+bind is allowed : as C-integer, or as C-double type. To select one of them,
+you may specify additional bind parameter I<ora_internal_type> as either
+B<SQLT_INT> or B<SQLT_FLT> for C-integer and C-double types.
+Integer size is architecture-specific and is usually 32 or 64 bit.
+Double is standard IEEE 754 type.
-error, while attempting to insert a LOB, this means the Oracle user has insufficient space for LOB you are trying to insert.
-One solution it to use "alter database datafile 'sss.ggg' resize Mnnn" to increase the available memory for LOBs.
+I<ora_internal_type> defaults to double (SQLT_FLT).
-=head2 Persistent and Locator Interface Caveats
+I<max_len> is ignored for OCI_NUMBER_TABLE.
-Now that one has the option of using the Persistent or the Locator interface for LOBs the questions arises
-which one to use. For starters, if you want to access LOBs over a dblink you will have to use the Persistent
-interface so that choice is simple. The question of which one to use after that is a little more tricky.
-It basically boils down to a choice between LOB size and speed.
+Currently, you cannot bind full native Oracle NUMBER(38). If you really need,
+send request to dbi-dev list.
-The Callback and Polling piecewise fetches are very very slow
-when compared to the Simple and the Locator fetches but they can handle very large blocks of data. Given a situation where a
-large LOB is to be read the Locator fetch may time out while either of the piecewise fetches may not.
+The usage example is here:
-With the Simple fetch you are limited by physical memory of your server but it runs a little faster than the Locator, as there are fewer round trips
-to the server. So if you have small LOBs and need to save a little bandwidth this is the one to use. It you are going after large LOBs then the Locator interface is the one to use.
+ $statement='
+ DECLARE
+ tbl SYS.DBMS_SQL.NUMBER_TABLE;
+ BEGIN
+ tbl := :mytable;
+ :cc := tbl(2);
+ tbl(4) := -1;
+ tbl(5) := -2;
+ :mytable := tbl;
+ END;
+ ';
+
+ $sth=$dbh->prepare( $statement );
+
+ if( ! defined($sth) ){
+ die "Prepare error: ",$dbh->errstr,"\n";
+ }
+
+ @arr=( 1,"2E0","3.5" );
+
+ # note, that ora_internal_type defaults to SQLT_FLT for ORA_NUMBER_TABLE .
+ if( not $sth->bind_param_inout(":mytable", \\@arr, 10, {
+ ora_type => ORA_NUMBER_TABLE,
+ ora_maxarray_numentries => (scalar(@arr)+2),
+ ora_internal_type => SQLT_FLT
+ } ) ){
+ die "bind :mytable error: ",$dbh->errstr,"\n";
+ }
+ $cc=undef;
+ if( not $sth->bind_param_inout(":cc", \$cc, 100 ) ){
+ die "bind :cc error: ",$dbh->errstr,"\n";
+ }
+
+ if( not $sth->execute() ){
+ die "Execute failed: ",$dbh->errstr,"\n";
+ }
+ print "Result: cc=",$cc,"\n",
+ "\tarr=",Data::Dumper::Dumper(\@arr),"\n";
-If you need to update more than a single row of with LOB data then the Persistent interface can do it while the Locator can't.
+The result is like:
-If you encounter a situation where you have to access the legacy LOBs (LONG, LONG RAW) and the values are to large for you system then you can use
-the Callback or Polling piecewise fetches to get all of the data.
+ Result: cc=2
+ arr=$VAR1 = [
+ '1',
+ '2',
+ '3.5',
+ '-1',
+ '-2'
+ ];
-Not all of the Persistent interface has been implemented yet, the following are not supported;
+If you change bind type to B<SQLT_INT>, like:
- 1) Piecewise, polling and callback binds for INSERT and UPDATE operations.
- 2) Piecewise array binds for SELECT, INSERT and UPDATE operations.
+ ora_internal_type => SQLT_INT
-Most of the time you should just use the L</Locator Data Interface> as this is in one that has the best combination of speed and size.
+you get:
-All this being said if you are doing some critical programming I would use the L</Data Interface for LOB Locators> as this gives you very
-fine grain control of your LOBs, of course the code for this will be somewhat more involved.
+ Result: cc=2
+ arr=$VAR1 = [
+ 1,
+ 2,
+ 3,
+ -1,
+ -2
+ ];
-=head2 Data Interface for LOB Locators
+=head3 B<bind_param_inout_array>
-The following driver-specific methods let you manipulate "LOB Locators" directly.
-To select a LOB locator directly set the if the C<ora_auto_lob>
-attribute to false, or alternatively they can be returned via PL/SQL procedure calls.
+DBD::Oracle supports this undocumented feature of DBI. See L</Returning A Value from an INSERT> for an example.
-(If using a DBI version earlier than 1.36 they must be called via the
-func() method. Note that methods called via func() don't honour
-RaiseError etc, and so it's important to check $dbh->err after each call.
-It's recommended that you upgrade to DBI 1.38 or later.)
-Note that LOB locators are only valid while the statement handle that
-created them is valid. When all references to the original statement
-handle are lost, the handle is destroyed and the locators are freed.
+=head3 B<bind_param_array>
-=over 4
+ $rv = $sth->bind_param_array($param_num, $array_ref_or_value)
+ $rv = $sth->bind_param_array($param_num, $array_ref_or_value, $bind_type)
+ $rv = $sth->bind_param_array($param_num, $array_ref_or_value, \%attr)
-=item ora_lob_read
+Binds an array of values to a placeholder, so that each is used in turn by a call
+to the L</execute_array> method.
- $data = $dbh->ora_lob_read($lob_locator, $offset, $length);
-Read a portion of the LOB. $offset starts at 1.
-Uses the Oracle OCILobRead function.
-=item ora_lob_write
+=head3 B<execute>
- $rc = $dbh->ora_lob_write($lob_locator, $offset, $data);
+ $rv = $sth->execute(@bind_values);
-Write/overwrite a portion of the LOB. $offset starts at 1.
-Uses the Oracle OCILobWrite function.
+Perform whatever processing is necessary to execute the prepared statement.
-=item ora_lob_append
+=head3 B<execute_array>
- $rc = $dbh->ora_lob_append($lob_locator, $data);
+ $tuples = $sth->execute_array() or die $sth->errstr;
+ $tuples = $sth->execute_array(\%attr) or die $sth->errstr;
+ $tuples = $sth->execute_array(\%attr, @bind_values) or die $sth->errstr;
-Append $data to the LOB. Uses the Oracle OCILobWriteAppend function.
+ ($tuples, $rows) = $sth->execute_array(\%attr) or die $sth->errstr;
+ ($tuples, $rows) = $sth->execute_array(\%attr, @bind_values) or die $sth->errstr;
-=item ora_lob_trim
+Execute a prepared statement once for each item in a passed-in hashref, or items that
+were previously bound via the L</bind_param_array> method. See the DBI documentation
+for more details.
- $rc = $dbh->ora_lob_trim($lob_locator, $length);
+DBD::Oracle takes full advantage of OCI's array interface so inserts and updates using this interface will run very
+quickly.
-Trims the length of the LOB to $length.
-Uses the Oracle OCILobTrim function.
+=head3 B<execute_for_fetch>
-=item ora_lob_length
+ $tuples = $sth->execute_for_fetch($fetch_tuple_sub);
+ $tuples = $sth->execute_for_fetch($fetch_tuple_sub, \@tuple_status);
- $length = $dbh->ora_lob_length($lob_locator);
+ ($tuples, $rows) = $sth->execute_for_fetch($fetch_tuple_sub);
+ ($tuples, $rows) = $sth->execute_for_fetch($fetch_tuple_sub, \@tuple_status);
-Returns the length of the LOB.
-Uses the Oracle OCILobGetLength function.
+Used internally by the L</execute_array> method, and rarely used directly. See the
+DBI documentation for more details.
+=head3 B<fetchrow_arrayref>
-=item ora_lob_is_init
+ $ary_ref = $sth->fetchrow_arrayref;
- $is_init = $dbh->ora_lob_is_init($lob_locator);
+Fetches the next row of data from the statement handle, and returns a reference to an array
+holding the column values. Any columns that are NULL are returned as undef within the array.
-Returns true(1) if the Lob Locator is initialized false(0) if it is not, or 'undef'
-if there is an error.
-Uses the Oracle OCILobLocatorIsInit function.
+If there are no more rows or if an error occurs, the this method return undef. You should
+check C<< $sth->err >> afterwards (or use the L</RaiseError> attribute) to discover if the undef returned
+was due to an error.
-=item ora_lob_chunk_size
+Note that the same array reference is returned for each fetch, so don't store the reference and
+then use it after a later fetch. Also, the elements of the array are also reused for each row,
+so take care if you want to take a reference to an element. See also L</bind_columns>.
- $chunk_size = $dbh->ora_lob_chunk_size($lob_locator);
+=head3 B<fetchrow_array>
-Returns the chunk size of the LOB.
-Uses the Oracle OCILobGetChunkSize function.
+ @ary = $sth->fetchrow_array;
-For optimal performance, Oracle recommends reading from and
-writing to a LOB in batches using a multiple of the LOB chunk size.
-In Oracle 10g and before, when all defaults are in place, this
-chunk size defaults to 8k (8192).
+Similar to the L</fetchrow_arrayref> method, but returns a list of column information rather than
+a reference to a list. Do not use this in a scalar context.
-=back
+=head3 B<fetchrow_hashref>
-=head3 LOB Locator Method Examples
+ $hash_ref = $sth->fetchrow_hashref;
+ $hash_ref = $sth->fetchrow_hashref($name);
-I<Note:> Make sure you first read the note in the section above about
-multi-byte character set issues with these methods.
+Fetches the next row of data and returns a hashref containing the name of the columns as the keys
+and the data itself as the values. Any NULL value is returned as as undef value.
-The following examples demonstrate the usage of LOB Locators
-to read, write, and append data, and to query the size of
-large data.
+If there are no more rows or if an error occurs, the this method return undef. You should
+check C<< $sth->err >> afterwards (or use the L</RaiseError> attribute) to discover if the undef returned
+was due to an error.
-The following examples assume a table containing two large
-object columns, one binary and one character, with a primary
-key column, defined as follows:
+The optional C<$name> argument should be either C<NAME>, C<NAME_lc> or C<NAME_uc>, and indicates
+what sort of transformation to make to the keys in the hash. By default Oracle uses upper case.
- CREATE TABLE lob_example (
- lob_id INTEGER PRIMARY KEY,
- bindata BLOB,
- chardata CLOB
- )
+=head3 B<fetchall_arrayref>
-It also assumes a sequence for use in generating unique
-lob_id field values, defined as follows:
+ $tbl_ary_ref = $sth->fetchall_arrayref();
+ $tbl_ary_ref = $sth->fetchall_arrayref( $slice );
+ $tbl_ary_ref = $sth->fetchall_arrayref( $slice, $max_rows );
- CREATE SEQUENCE lob_example_seq
+Returns a reference to an array of arrays that contains all the remaining rows to be fetched from the
+statement handle. If there are no more rows, an empty arrayref will be returned. If an error occurs,
+the data read in so far will be returned. Because of this, you should always check C<< $sth->err >> after
+calling this method, unless L</RaiseError> has been enabled.
+If C<$slice> is an array reference, fetchall_arrayref uses the L</fetchrow_arrayref> method to fetch each
+row as an array ref. If the C<$slice> array is not empty then it is used as a slice to select individual
+columns by perl array index number (starting at 0, unlike column and parameter numbers which start at 1).
-=head3 Example: Inserting a new row with large data
+With no parameters, or if $slice is undefined, fetchall_arrayref acts as if passed an empty array ref.
-Unless enough memory is available to store and bind the
-entire LOB data for insert all at once, the LOB columns must
-be written interactively, piece by piece. In the case of a new row,
-this is performed by first inserting a row, with empty values in
-the LOB columns, then modifying the row by writing the large data
-interactively to the LOB columns using their LOB locators as handles.
+If C<$slice> is a hash reference, fetchall_arrayref uses L</fetchrow_hashref> to fetch each row as a hash reference.
-The insert statement must create token values in the LOB
-columns. Here, we use the empty string for both the binary
-and character large object columns 'bindata' and 'chardata'.
+See the DBI documentation for a complete discussion.
-After the INSERT statement, a SELECT statement is used to
-acquire LOB locators to the 'bindata' and 'chardata' fields
-of the newly inserted row. Because these LOB locators are
-subsequently written, they must be acquired from a select
-statement containing the clause 'FOR UPDATE' (LOB locators
-are only valid within the transaction that fetched them, so
-can't be used effectively if AutoCommit is enabled).
+=head3 B<fetchall_hashref>
- my $lob_id = $dbh->selectrow_array( <<" SQL" );
- SELECT lob_example_seq.nextval FROM DUAL
- SQL
+ $hash_ref = $sth->fetchall_hashref( $key_field );
- my $sth = $dbh->prepare( <<" SQL" );
- INSERT INTO lob_example
- ( lob_id, bindata, chardata )
- VALUES ( ?, EMPTY_BLOB(),EMPTY_CLOB() )
- SQL
- $sth->execute( $lob_id );
+Returns a hashref containing all rows to be fetched from the statement handle. See the DBI documentation for
+a full discussion.
- $sth = $dbh->prepare( <<" SQL", { ora_auto_lob => 0 } );
- SELECT bindata, chardata
- FROM lob_example
- WHERE lob_id = ?
- FOR UPDATE
- SQL
- $sth->execute( $lob_id );
- my ( $bin_locator, $char_locator ) = $sth->fetchrow_array();
- $sth->finish();
+=head3 B<finish>
- open BIN_FH, "/binary/data/source" or die;
- open CHAR_FH, "/character/data/source" or die;
- my $chunk_size = $dbh->ora_lob_chunk_size( $bin_locator );
+ $rv = $sth->finish;
- # BEGIN WRITING BIN_DATA COLUMN
- my $offset = 1; # Offsets start at 1, not 0
- my $length = 0;
- my $buffer = '';
- while( $length = read( BIN_FH, $buffer, $chunk_size ) ) {
- $dbh->ora_lob_write( $bin_locator, $offset, $buffer );
- $offset += $length;
- }
+Indicates to DBI that you are finished with the statement handle and are not going to use it again. Only needed
+when you have not fetched all the possible rows.
- # BEGIN WRITING CHAR_DATA COLUMN
- $chunk_size = $dbh->ora_lob_chunk_size( $char_locator );
- $offset = 1; # Offsets start at 1, not 0
- $length = 0;
- $buffer = '';
- while( $length = read( CHAR_FH, $buffer, $chunk_size ) ) {
- $dbh->ora_lob_write( $char_locator, $offset, $buffer );
- $offset += $length;
- }
+=head3 B<rows>
+ $rv = $sth->rows;
-In this example we demonstrate the use of ora_lob_write()
-interactively to append data to the columns 'bin_data' and
-'char_data'. Had we used ora_lob_append(), we could have
-saved ourselves the trouble of keeping track of the offset
-into the lobs. The snippet of code beneath the comment
-'BEGIN WRITING BIN_DATA COLUMN' could look as follows:
+Returns the number of rows affected for updates, deletes and inserts and -1 for selects.
- my $buffer = '';
- while ( read( BIN_FH, $buffer, $chunk_size ) ) {
- $dbh->ora_lob_append( $bin_locator, $buffer );
- }
+=head3 B<bind_col>
-The scalar variables $offset and $length are no longer
-needed, because ora_lob_append() keeps track of the offset
-for us.
+ $rv = $sth->bind_col($column_number, \$var_to_bind);
+ $rv = $sth->bind_col($column_number, \$var_to_bind, \%attr );
+ $rv = $sth->bind_col($column_number, \$var_to_bind, $bind_type );
+Binds a Perl variable and/or some attributes to an output column of a SELECT statement.
+Column numbers count up from 1. You do not need to bind output columns in order to fetch data.
-=head3 Example: Updating an existing row with large data
+See the DBI documentation for a discussion of the optional parameters C<\%attr> and C<$bind_type>
-In this example, we demonstrate a technique for overwriting
-a portion of a blob field with new binary data. The blob
-data before and after the section overwritten remains
-unchanged. Hence, this technique could be used for updating
-fixed length subfields embedded in a binary field.
+=head3 B<bind_columns>
- my $lob_id = 5; # Arbitrary row identifier, for example
+ $rv = $sth->bind_columns(@list_of_refs_to_vars_to_bind);
- $sth = $dbh->prepare( <<" SQL", { ora_auto_lob => 0 } );
- SELECT bindata
- FROM lob_example
- WHERE lob_id = ?
- FOR UPDATE
- SQL
- $sth->execute( $lob_id );
- my ( $bin_locator ) = $sth->fetchrow_array();
+Calls the L</bind_col> method for each column in the SELECT statement, using the supplied list.
- my $offset = 100234;
- my $data = "This string will overwrite a portion of the blob";
- $dbh->ora_lob_write( $bin_locator, $offset, $data );
+=head3 B<dump_results>
-After running this code, the row where lob_id = 5 will
-contain, starting at position 100234 in the bin_data column,
-the string "This string will overwrite a portion of the blob".
+ $rows = $sth->dump_results($maxlen, $lsep, $fsep, $fh);
-=head3 Example: Streaming character data from the database
+Fetches all the rows from the statement handle, calls C<DBI::neat_list> for each row, and
+prints the results to C<$fh> (which defaults to F<STDOUT>). Rows are separated by C<$lsep> (which defaults
+to a newline). Columns are separated by C<$fsep> (which defaults to a comma). The C<$maxlen> controls
+how wide the output can be, and defaults to 35.
-In this example, we demonstrate a technique for streaming
-data from the database to a file handle, in this case
-STDOUT. This allows more data to be read in and written out
-than could be stored in memory at a given time.
+This method is designed as a handy utility for prototyping and testing queries. Since it uses
+"neat_list" to format and edit the string for reading by humans, it is not recommended
+for data transfer applications.
- my $lob_id = 17; # Arbitrary row identifier, for example
- $sth = $dbh->prepare( <<" SQL", { ora_auto_lob => 0 } );
- SELECT chardata
- FROM lob_example
- WHERE lob_id = ?
- SQL
- $sth->execute( $lob_id );
- my ( $char_locator ) = $sth->fetchrow_array();
+=head2 Private Statement Handle Methods
- my $chunk_size = 1034; # Arbitrary chunk size, for example
- my $offset = 1; # Offsets start at 1, not 0
- while(1) {
- my $data = $dbh->ora_lob_read( $char_locator, $offset, $chunk_size );
- last unless length $data;
- print STDOUT $data;
- $offset += $chunk_size;
- }
+=head3 B<ora_stmt_type>
-Notice that the select statement does not contain the phrase
-"FOR UPDATE". Because we are only reading from the LOB
-Locator returned, and not modifying the LOB it refers to,
-the select statement does not require the "FOR UPDATE"
-clause.
+Returns the OCI Statement Type number for the SQL of a statement handle.
-A word of caution when using the data returned from an ora_lob_read in a conditional statement.
-for example if the code below;
+=head3 B<ora_stmt_type_name>
- while( my $data = $dbh->ora_lob_read( $char_locator, $offset, $chunk_size ) ) {
- print STDOUT $data;
- $offset += $chunk_size;
- }
+Returns the OCI Statement Type name for the SQL of a statement handle.
-was used with a chunk size of 4096 against a blob that requires more than 1 chunk to return
-the data and the last chunk is one byte long and contains a zero (ASCII 48) you will miss this last byte
-as $data will contain 0 which Perl will see as false and not print it out.
+=head2 Statement Handle Attributes
-=head3 Example: Truncating existing large data
+=head3 B<NUM_OF_FIELDS> (integer, read-only)
-In this example, we truncate the data already present in a
-large object column in the database. Specifically, for each
-row in the table, we truncate the 'bindata' value to half
-its previous length.
+Returns the number of columns returned by the current statement. A number will only be returned for
+SELECT statements for INSERT,
+UPDATE, and DELETE statements which contain a RETURNING clause.
+This method returns undef if called before C<execute()>.
-After acquiring a LOB Locator for the column, we query its
-length, then we trim the length by half. Because we modify
-the large objects with the call to ora_lob_trim(), we must
-select the LOB locators 'FOR UPDATE'.
+=head3 B<NUM_OF_PARAMS> (integer, read-only)
- my $sth = $dbh->prepare( <<" SQL", { ora_auto_lob => 0 } );
- SELECT bindata
- FROM lob_example
- FOR UPATE
- SQL
- $sth->execute();
- while( my ( $bin_locator ) = $sth->fetchrow_array() ) {
- my $binlength = $dbh->ora_lob_length( $bin_locator );
- if( $binlength > 0 ) {
- $dbh->ora_lob_trim( $bin_locator, $binlength/2 );
- }
- }
+Returns the number of placeholders in the current statement.
-=head1 Binding Cursors
+=head3 B<NAME> (arrayref, read-only)
-Cursors can be returned from PL/SQL blocks, either from stored
-functions (or procedures with OUT parameters) or
-from direct C<OPEN> statements, as shown below:
+Returns an arrayref of column names for the current statement. This
+method will only work for SELECT statements, for SHOW statements, and for
+INSERT, UPDATE, and DELETE statements which contain a RETURNING clause.
+This method returns undef if called before C<execute()>.
- use DBI;
- use DBD::Oracle qw(:ora_types);
- my $dbh = DBI->connect(...);
- my $sth1 = $dbh->prepare(q{
- BEGIN OPEN :cursor FOR
- SELECT table_name, tablespace_name
- FROM user_tables WHERE tablespace_name = :space;
- END;
- });
- $sth1->bind_param(":space", "USERS");
- my $sth2;
- $sth1->bind_param_inout(":cursor", \$sth2, 0, { ora_type => ORA_RSET } );
- $sth1->execute;
- # $sth2 is now a valid DBI statement handle for the cursor
- while ( my @row = $sth2->fetchrow_array ) { ... }
+=head3 B<NAME_lc> (arrayref, read-only)
-The only special requirement is the use of C<bind_param_inout()> with an
-attribute hash parameter that specifies C<ora_type> as C<ORA_RSET>.
-If you don't do that you'll get an error from the C<execute()> like:
-"ORA-06550: line X, column Y: PLS-00306: wrong number or types of
-arguments in call to ...".
+The same as the C<NAME> attribute, except that all column names are forced to lower case.
-Here's an alternative form using a function that returns a cursor.
-This example uses the pre-defined weak (or generic) REF CURSOR type
-SYS_REFCURSOR. This is an Oracle 9 feature.
+=head3 B<NAME_uc> (arrayref, read-only)
- # Create the function that returns a cursor
- $dbh->do(q{
- CREATE OR REPLACE FUNCTION sp_ListEmp RETURN SYS_REFCURSOR
- AS l_cursor SYS_REFCURSOR;
- BEGIN
- OPEN l_cursor FOR select ename, empno from emp
- ORDER BY ename;
- RETURN l_cursor;
- END;
- });
+The same as the C<NAME> attribute, except that all column names are forced to upper case.
- # Use the function that returns a cursor
- my $sth1 = $dbh->prepare(q{BEGIN :cursor := sp_ListEmp; END;});
- my $sth2;
- $sth1->bind_param_inout(":cursor", \$sth2, 0, { ora_type => ORA_RSET } );
- $sth1->execute;
- # $sth2 is now a valid DBI statement handle for the cursor
- while ( my @row = $sth2->fetchrow_array ) { ... }
+=head3 B<NAME_hash> (hashref, read-only)
-A cursor obtained from PL/SQL as above may be passed back to PL/SQL
-by binding for input, as shown in this example, which explicitly
-closes a cursor:
+Similar to the C<NAME> attribute, but returns a hashref of column names instead of an arrayref. The names of the columns
+are the keys of the hash, and the values represent the order in which the columns are returned, starting at 0.
+This method returns undef if called before C<execute()>.
- my $sth3 = $dbh->prepare("BEGIN CLOSE :cursor; END;");
- $sth3->bind_param(":cursor", $sth2, { ora_type => ORA_RSET } );
- $sth3->execute;
+=head3 B<NAME_lc_hash> (hashref, read-only)
-It is not normally necessary to close a cursor
-explicitly in this way. Oracle will close the cursor automatically
-at the first client-server interaction after the cursor statement handle is
-destroyed. An explicit close may be desirable if the reference to
-the cursor handle from the PL/SQL statement handle delays the destruction
-of the cursor handle for too long. This reference remains until the
-PL/SQL handle is re-bound, re-executed or destroyed.
+The same as the C<NAME_hash> attribute, except that all column names are forced to lower case.
-See the C<curref.pl> script in the Oracle.ex directory in the DBD::Oracle
-source distribution for a complete working example.
+=head3 B<NAME_uc_hash> (hashref, read-only)
-=head1 Fetching Nested Cursors
+The same as the C<NAME_hash> attribute, except that all column names are forced to lower case.
-Oracle supports the use of select list expressions of type REF CURSOR.
-These may be explicit cursor expressions - C<CURSOR(SELECT ...)>, or
-calls to PL/SQL functions which return REF CURSOR values. The values
-of these expressions are known as nested cursors.
+=head3 B<TYPE> (arrayref, read-only)
-The value returned to a Perl program when a nested cursor is fetched
-is a statement handle. This statement handle is ready to be fetched from.
-It should not (indeed, must not) be executed.
+Returns an arrayref indicating the data type for each column in the statement.
+This method returns undef if called before C<execute()>.
-Oracle imposes a restriction on the order of fetching when nested
-cursors are used. Suppose C<$sth1> is a handle for a select statement
-involving nested cursors, and C<$sth2> is a nested cursor handle fetched
-from C<$sth1>. C<$sth2> can only be fetched from while C<$sth1> is
-still active, and the row containing C<$sth2> is still current in C<$sth1>.
-Any attempt to fetch another row from C<$sth1> renders all nested cursor
-handles previously fetched from C<$sth1> defunct.
+=head3 B<PRECISION> (arrayref, read-only)
-Fetching from such a defunct handle results in an error with the message
-C<ERROR nested cursor is defunct (parent row is no longer current)>.
+Returns an arrayref of integer values for each column returned by the statement.
+The number indicates the precision for C<NUMERIC> columns, the size in number of
+characters for C<CHAR> and C<VARCHAR> columns, and for all other types of columns
+it returns the number of I<bytes>.
+This method returns undef if called before C<execute()>.
-This means that the C<fetchall...> or C<selectall...> methods are not useful
-for queries returning nested cursors. By the time such a method returns,
-all the nested cursor handles it has fetched will be defunct.
+=head3 B<SCALE> (arrayref, read-only)
-It is necessary to use an explicit fetch loop, and to do all the
-fetching of nested cursors within the loop, as the following example
-shows:
+Returns an arrayref of integer values for each column returned by the statement. The number
+indicates the scale of the that column. The only type that will return a value is C<NUMERIC>.
+This method returns undef if called before C<execute()>.
- use DBI;
- my $dbh = DBI->connect(...);
- my $sth = $dbh->prepare(q{
- SELECT dname, CURSOR(
- SELECT ename FROM emp
- WHERE emp.deptno = dept.deptno
- ORDER BY ename
- ) FROM dept ORDER BY dname
- });
- $sth->execute;
- while ( my ($dname, $nested) = $sth->fetchrow_array ) {
- print "$dname\n";
- while ( my ($ename) = $nested->fetchrow_array ) {
- print " $ename\n";
- }
- }
+=head3 B<NULLABLE> (arrayref, read-only)
+Returns an arrayref of integer values for each column returned by the statement. The number
+indicates if the column is nullable or not. 0 = not nullable, 1 = nullable, 2 = unknown.
+This method returns undef if called before C<execute()>.
-The cursor returned by the function C<sp_ListEmp> defined in the
-previous section can be fetched as a nested cursor as follows:
+=head3 B<Database> (dbh, read-only)
- my $sth = $dbh->prepare(q{SELECT sp_ListEmp FROM dual});
- $sth->execute;
- my ($nested) = $sth->fetchrow_array;
- while ( my @row = $nested->fetchrow_array ) { ... }
+Returns the database handle this statement handle was created from.
-=head2 Pre-fetching Nested Cursors
+=head3 B<ParamValues> (hash ref, read-only)
-By default, DBD::Oracle pre-fetches rows in order to reduce the number of
-round trips to the server. For queries which do not involve nested cursors,
-the number of pre-fetched rows is controlled by the DBI database handle
-attribute C<RowCacheSize> (q.v.).
+Returns a reference to a hash containing the values currently bound to placeholders. If the "named parameters"
+type of placeholders are being used (such as ":foo"), then the keys of the hash will be the names of the
+placeholders (without the colon). If the "dollar sign numbers" type of placeholders are being used, the keys of the hash will
+be the numbers, without the dollar signs. If the "question mark" type is used, integer numbers will be returned,
+starting at one and increasing for every placeholder.
-In Oracle, server side open cursors are a controlled resource, limited in
-number, on a per session basis, to the value of the initialization
-parameter C<OPEN_CURSORS>. Nested cursors count towards this limit.
-Each nested cursor in the current row counts 1, as does
-each nested cursor in a pre-fetched row. Defunct nested cursors do not count.
+If this method is called before L</execute>, the literal values passed in are returned. If called after
+L</execute>, then the quoted versions of the values are returned.
-An Oracle specific database handle attribute, C<ora_max_nested_cursors>,
-further controls pre-fetching for queries involving nested cursors. For
-each statement handle, the total number of nested cursors in pre-fetched
-rows is limited to the value of this parameter. The default value
-is 0, which disables pre-fetching for queries involving nested cursors.
+=head3 B<ParamTypes> (hash ref, read-only)
-=head1 Returning a Value from an INSERT
+Returns a reference to a hash containing the type names currently bound to placeholders. The keys
+are the same as returned by the ParamValues method. The values are hashrefs containing a single key value
+pair, in which the key is either 'TYPE' if the type has a generic SQL equivalent, and 'pg_type' if the type can
+only be expressed by a Postgres type. The value is the internal number corresponding to the type originally
+passed in. (Placeholders that have not yet been bound will return undef as the value). This allows the output of
+ParamTypes to be passed back to the L</bind_param> method.
-Oracle supports an extended SQL insert syntax which will return one
-or more of the values inserted. This can be particularly useful for
-single-pass insertion of values with re-used sequence values
-(avoiding a separate "select seq.nextval from dual" step).
+=head3 B<Statement> (string, read-only)
- $sth = $dbh->prepare(qq{
- INSERT INTO foo (id, bar)
- VALUES (foo_id_seq.nextval, :bar)
- RETURNING id INTO :id
- });
- $sth->bind_param(":bar", 42);
- $sth->bind_param_inout(":id", \my $new_id, 99);
- $sth->execute;
- print "The id of the new record is $new_id\n";
+Returns the statement string passed to the most recent "prepare" method called in this database handle, even if that method
+failed. This is especially useful where "RaiseError" is enabled and the exception handler checks $@ and sees that a C<prepare>
+method call failed.
+
+=head3 B<RowsInCache>
+
+Returns the number of un-fetched rows in the cache for selects.
+
+=head2 Scrollable Cursors
+
+Oracle supports the concept of a 'Scrollable Cursor' which is defined as a 'Result Set' where
+the rows can be fetched either sequentially or non-sequentially. One can fetch rows forward,
+backwards, from any given position or the n-th row from the current position in the result set.
+
+Rows are numbered sequentially starting at one and client-side caching of the partial or entire result set
+can improve performance by limiting round trips to the server.
+
+Oracle does not support DML type operations with scrollable cursors so you are limited
+to simple 'Select' operations only. As well you can not use this functionality with remote
+mapped queries or if the LONG datatype is part of the select list.
+
+However, LOBSs, CLOBSs, and BLOBs do work as do all the regular bind, and fetch methods.
+
+Only use scrollable cursors if you really have a good reason to. They do use up considerable
+more server and client resources and have poorer response times than non-scrolling cursors.
+
+
+=head3 B<Enabling Scrollable Cursors>
+
+To enable this functionality you must first import the 'Fetch Orientation' and the 'Execution Mode' constants by using;
+
+ use DBD::Oracle qw(:ora_fetch_orient :ora_exe_modes);
+
+Next you will have to tell DBD::Oracle that you will be using scrolling by setting the ora_exe_mode attribute on the
+statement handle to 'OCI_STMT_SCROLLABLE_READONLY' with the prepare method;
+
+ $sth=$dbh->prepare($SQL,{ora_exe_mode=>OCI_STMT_SCROLLABLE_READONLY});
+
+When the statement is executed you will then be able to use 'ora_fetch_scroll' method to get a row
+or you can still use any of the other fetch methods but with a poorer response time than if you used a
+non-scrolling cursor. As well scrollable cursors are compatible with any applicable bind methods.
+
+
+=head3 B<Scrollable Cursor Methods>
+
+The following driver-specific methods are used with scrollable cursors.
+
+=over
+
+=item ora_scroll_position
+
+ $position = $sth->ora_scroll_position();
+
+This method returns the current position (row number) attribute of the result set. Prior to the first fetch this value is 0. This is the only time
+this value will be 0 after the first fetch the value will be set, so you can use this value to test if any rows have been fetched.
+The minimum value will always be 1 after the first fetch. The maximum value will always be the total number of rows in the record set.
+
+=item ora_fetch_scroll
+
+ @ary = $sth->ora_fetch_scroll($fetch_orient,$fetch_offset);
+
+Works the same as fetchrow_array method however, one passes in a 'Fetch Orientation' constant and a fetch_offset
+value which will then determine the row that will be fetched. It returns the row as a list containing the field values.
+Null fields are returned as undef values in the list.
+
+The valid orientation constant and fetch offset values combination are detailed below
+
+ OCI_FETCH_CURRENT, fetches the current row, the fetch offset value is ignored.
+ OCI_FETCH_NEXT, fetches the next row from the current position, the fetch offset value
+ is ignored.
+ OCI_FETCH_FIRST, fetches the first row, the fetch offset value is ignored.
+ OCI_FETCH_LAST, fetches the last row, the fetch offset value is ignored.
+ OCI_FETCH_PRIOR, fetches the previous row from the current position, the fetch offset
+ value is ignored.
+ OCI_FETCH_ABSOLUTE, fetches the row that is specified by the fetch offset value.
+ OCI_FETCH_RELATIVE, fetches the row relative from the current position as specified by the
+ fetch offset value.
+
+ OCI_FETCH_ABSOLUTE, and a fetch offset value of 1 is equivalent to a OCI_FETCH_FIRST.
+ OCI_FETCH_ABSOLUTE, and a fetch offset value of 0 is equivalent to a OCI_FETCH_CURRENT.
+
+ OCI_FETCH_RELATIVE, and a fetch offset value of 0 is equivalent to a OCI_FETCH_CURRENT.
+ OCI_FETCH_RELATIVE, and a fetch offset value of 1 is equivalent to a OCI_FETCH_NEXT.
+ OCI_FETCH_RELATIVE, and a fetch offset value of -1 is equivalent to a OCI_FETCH_PRIOR.
+
+The effect that a ora_fetch_scroll method call has on the current_positon attribute is detailed below.
+
+ OCI_FETCH_CURRENT, has no effect on the current_positon attribute.
+ OCI_FETCH_NEXT, increments current_positon attribute by 1
+ OCI_FETCH_NEXT, when at the last row in the record set does not change current_positon
+ attribute, it is equivalent to a OCI_FETCH_CURRENT
+ OCI_FETCH_FIRST, sets the current_positon attribute to 1.
+ OCI_FETCH_LAST, sets the current_positon attribute to the total number of rows in the
+ record set.
+ OCI_FETCH_PRIOR, decrements current_positon attribute by 1.
+ OCI_FETCH_PRIOR, when at the first row in the record set does not change current_positon
+ attribute, it is equivalent to a OCI_FETCH_CURRENT.
+
+ OCI_FETCH_ABSOLUTE, sets the current_positon attribute to the fetch offset value.
+ OCI_FETCH_ABSOLUTE, and a fetch offset value that is less than 1 does not change
+ current_positon attribute, it is equivalent to a OCI_FETCH_CURRENT.
+ OCI_FETCH_ABSOLUTE, and a fetch offset value that is greater than the number of records in
+ the record set, does not change current_positon attribute, it is
+ equivalent to a OCI_FETCH_CURRENT.
+ OCI_FETCH_RELATIVE, sets the current_positon attribute to (current_positon attribute +
+ fetch offset value).
+ OCI_FETCH_RELATIVE, and a fetch offset value that makes the current position less than 1,
+ does not change fetch offset value so it is equivalent to a OCI_FETCH_CURRENT.
+ OCI_FETCH_RELATIVE, and a fetch offset value that makes it greater than the number of records
+ in the record set, does not change fetch offset value so it is equivalent
+ to a OCI_FETCH_CURRENT.
+
+The effects of the differing orientation constants on the first fetch (current_postion attribute at 0) are as follows.
+
+ OCI_FETCH_CURRENT, dose not fetch a row or change the current_positon attribute.
+ OCI_FETCH_FIRST, fetches row 1 and sets the current_positon attribute to 1.
+ OCI_FETCH_LAST, fetches the last row in the record set and sets the current_positon
+ attribute to the total number of rows in the record set.
+ OCI_FETCH_NEXT, equivalent to a OCI_FETCH_FIRST.
+ OCI_FETCH_PRIOR, equivalent to a OCI_FETCH_CURRENT.
+
+ OCI_FETCH_ABSOLUTE, and a fetch offset value that is less than 1 is equivalent to a
+ OCI_FETCH_CURRENT.
+ OCI_FETCH_ABSOLUTE, and a fetch offset value that is greater than the number of
+ records in the record set is equivalent to a OCI_FETCH_CURRENT.
+ OCI_FETCH_RELATIVE, and a fetch offset value that is less than 1 is equivalent
+ to a OCI_FETCH_CURRENT.
+ OCI_FETCH_RELATIVE, and a fetch offset value that makes it greater than the number
+ of records in the record set, is equivalent to a OCI_FETCH_CURRENT.
+
+=back
+
+=head3 B<Scrollable Cursor Usage>
+
+Given a simple code like this:
+
+ use DBI;
+ use DBD::Oracle qw(:ora_types :ora_fetch_orient :ora_exe_modes);
+ my $dbh = DBI->connect($dsn, $dbuser, '');
+ my $SQL = "select id,
+ first_name,
+ last_name
+ from employee";
+ my $sth=$dbh->prepare($SQL,{ora_exe_mode=>OCI_STMT_SCROLLABLE_READONLY});
+ $sth->execute();
+ my $value;
+
+and one assumes that the number of rows returned from the query is 20, the code snippets below will illustrate the use of ora_fetch_scroll
+method;
+
+=over
+
+=item Fetching the Last Row
+
+ $value = $sth->ora_fetch_scroll(OCI_FETCH_LAST,0);
+ print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
+ print "current scroll position=".$sth->ora_scroll_position()."\n";
+
+The current_positon attribute to will be 20 after this snippet. This is also a way to get the number of rows in the record set, however,
+if the record set is large this could take some time.
+
+=item Fetching the Current Row
+
+ $value = $sth->ora_fetch_scroll(OCI_FETCH_CURRENT,0);
+ print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
+ print "current scroll position=".$sth->ora_scroll_position()."\n";
+
+The current_positon attribute will still be 20 after this snippet.
+
+=item Fetching the First Row
+
+ $value = $sth->ora_fetch_scroll(OCI_FETCH_FIRST,0);
+ print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
+ print "current scroll position=".$sth->ora_scroll_position()."\n";
+
+The current_positon attribute will be 1 after this snippet.
+
+=item Fetching the Next Row
+
+ for(my $i=0;$i<=3;$i++){
+ $value = $sth->ora_fetch_scroll(OCI_FETCH_NEXT,0);
+ print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
+ }
+ print "current scroll position=".$sth->ora_scroll_position()."\n";
+
+The current_positon attribute will be 5 after this snippet.
+
+=item Fetching the Prior Row
+
+ for(my $i=0;$i<=3;$i++){
+ $value = $sth->ora_fetch_scroll(OCI_FETCH_PRIOR,0);
+ print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
+ }
+ print "current scroll position=".$sth->ora_scroll_position()."\n";
+
+The current_positon attribute will be 1 after this snippet.
+
+=item Fetching the 10th Row
+
+ $value = $sth->ora_fetch_scroll(OCI_FETCH_ABSOLUTE,10);
+ print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
+ print "current scroll position=".$sth->ora_scroll_position()."\n";
+
+The current_positon attribute will be 10 after this snippet.
+
+=item Fetching the 10th to 14th Row
+
+ for(my $i=10;$i<15;$i++){
+ $value = $sth->ora_fetch_scroll(OCI_FETCH_ABSOLUTE,$i);
+ print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
+ }
+ print "current scroll position=".$sth->ora_scroll_position()."\n";
+
+The current_positon attribute will be 14 after this snippet.
+
+=item Fetching the 14th to 10th Row
+
+ for(my $i=14;$i>9;$i--){
+ $value = $sth->ora_fetch_scroll(OCI_FETCH_ABSOLUTE,$i);
+ print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
+ }
+ print "current scroll position=".$sth->ora_scroll_position()."\n";
+
+The current_positon attribute will be 10 after this snippet.
+
+=item Fetching the 5th Row From the Present Position.
+
+ $value = $sth->ora_fetch_scroll(OCI_FETCH_RELATIVE,5);
+ print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
+ print "current scroll position=".$sth->ora_scroll_position()."\n";
+
+The current_positon attribute will be 15 after this snippet.
+
+=item Fetching the 9th Row Prior From the Present Position
+
+ $value = $sth->ora_fetch_scroll(OCI_FETCH_RELATIVE,-9);
+ print "id=".$value->[0].", First Name=".$value->[1].", Last Name=".$value->[2]."\n";
+ print "current scroll position=".$sth->ora_scroll_position()."\n";
+
+The current_positon attribute will be 6 after this snippet.
+
+=item Use Finish
+
+ $sth->finish();
+
+When using scrollable cursors it is required that you use the $sth->finish() method when you are done with the cursor as this type of
+cursor has to be explicitly cancelled on the server. If you do not do this you may cause resource problems on your database.
+
+=back
+
+=head2 LOBs and LONGs
+
+The key to working with LOBs (CLOB, BLOBs) is to remember the value of an Oracle LOB column is not the content of the LOB. It's a
+'LOB Locator' which, after being selected or inserted needs extra processing to read or write the content of the LOB. There are also legacy LONG types (LONG, LONG RAW, VARCHAR2)
+which are presently deprecated by Oracle but are still in use. These LONG types do not utilize a 'LOB Locator' and also are more limited in
+functionality than CLOB or BLOB fields.
+
+DBD::Oracle now offers three interfaces to LOB and LONG data,
+
+=over
+
+=item L</Data Interface for Persistent LOBs>
+
+With this interface DBD::Oracle handles your data directly utilizing regular OCI calls, Oracle itself takes care of the LOB Locator operations in the case of
+BLOBs and CLOBs treating them exactly as if they were the same as the legacy LONG or LONG RAW types.
+
+=item L</Data Interface for LOB Locators>
+
+With this interface DBD::Oracle handles your data utilizing LOB Locator OCI calls so it only works with CLOB and BLOB datatypes. With this interface DBD::Oracle takes care of the LOB Locator operations for you.
+
+=item L</LOB Locator Method Interface>
+
+This allows the user direct access to the LOB Locator methods, so you have to take case of the LOB Locator operations yourself.
+
+=back
+
+Generally speaking the interface that you will chose will be dependent on what end you are trying to achieve. All have their benefits and
+drawbacks.
+
+One point to remember when working with LOBs (CLOBs, BLOBs) is if your LOB column can be in one of three states;
+
+=over
+
+=item NULL
+
+The table cell is created, but the cell holds no locator or value.
+If your LOB field is in this state then there is no LOB Locator that DBD::Oracle can work so if your encounter a
+
+ DBD::Oracle::db::ora_lob_read: locator is not of type OCILobLocatorPtr
+
+error when working with a LOB.
+
+You can correct this by using an SQL UPDATE statement to reset the LOB column to a non-NULL (or empty LOB) value with either EMPTY_BLOB or EMPTY_CLOB as in this example;
+
+ UPDATE lob_example
+ SET bindata=EMPTY_BLOB()
+ WHERE bindata IS NULL.
+
+=item Empty
+
+A LOB instance with a locator exists in the cell, but it has no value. The length of the LOB is zero. In this case DBD::Oracle will return 'undef' for the field.
+
+=item Populated
+
+A LOB instance with a locator and a value exists in the cell. You actually get the LOB value.
+
+=back
+
+=head3 B<Data Interface for Persistent LOBs>
+
+This is the original interface for LONG and LONG RAW datatypes and from Oracle 9iR1 and later the OCI API was extended to work directly with the other LOB datatypes.
+In other words you can treat all LOB type data (BLOB, CLOB) as if it was a LONG, LONG RAW, or VARCHAR2. So you can perform INSERT, UPDATE, fetch, bind, and define operations on LOBs using the same techniques
+you would use on other datatypes that store character or binary data. In some cases there are fewer round trips to the server as no 'LOB Locators' are
+used, normally one can get an entire LOB is a single round trip.
+
+=head4 Simple Fetch for LONGs and LONG RAWs
+
+As the name implies this is the simplest way to use this interface. DBD::Oracle just attempts to get your LONG datatypes as a single large piece.
+There are no special settings, simply set the database handle's 'LongReadLen' attribute to a value that will be the larger than the expected size of the LONG or LONG RAW.
+If the size of the LONG or LONG RAW exceeds the 'LongReadLen' DBD::Oracle will return a 'ORA-24345: A Truncation' error. To stop this set the database handle's 'LongTruncOk' attribute to '1'.
+The maximum value of 'LongReadLen' seems to be dependent on the physical memory limits of the box that Oracle is running on. You have most likely reached this limit if you run into
+an 'ORA-01062: unable to allocate memory for define buffer' error. One solution is to set the size of 'LongReadLen' to a lower value.
+
+For example give this table;
+
+ CREATE TABLE test_long (
+ id NUMBER,
+ long1 long)
+
+this code;
+
+ $dbh->{LongReadLen} = 2*1024*1024; #2 meg
+ $SQL='select p_id,long1 from test_long';
+ $sth=$dbh->prepare($SQL);
+ $sth->execute();
+ while (my ( $p_id,$long )=$sth->fetchrow()){
+ print "p_id=".$p_id."\n";
+ print "long=".$long."\n";
+ }
+
+Will select out all of the long1 fields in the table as long as they are all under 2MB in length. A value in long1 longer than this will throw an error. Adding this line;
+
+ $dbh->{LongTruncOk}=1;
+
+before the execute will return all the long1 fields but they will be truncated at 2MBs.
+
+=head4 Using ora_ncs_buff_mtpl
+
+When getting CLOBs and NCLOBs in or out of Oracle, the Server will translate from the Server's NCharSet to the
+Client's. If they happen to be the same or at least compatible then all of these actions are a 1 char to 1 char bases.
+Thus if you set your LongReadLen buffer to 10_000_000 you will get up to 10_000_000 char.
+
+However if the Server has to translate from one NCharSet to another it will use bytes for conversion. The buffer
+value is set to 4 * LONG_READ_LEN which was very wasteful as you might only be asking for 10_000_000 bytes
+but you were actually using 40_000_000 bytes of buffer under the hood. You would still get 10_000_000 bytes
+(maybe less characters though) but you are using allot more memory that you need.
+
+You can now customize the size of the buffer by setting the 'ora_ncs_buff_mtpl' either on the connection or statement handle. You can
+also set this as 'ORA_DBD_NCS_BUFFER' OS environment variable so you will have to go back and change all your code if you are getting into trouble.
+
+The default value is still set to 4 for backward compatibility. You can lower this value and thus increase the amount of data you can retrieve. If the
+ora_ncs_buff_mtpl is too small DBD::Oracle will throw and error telling you to increase this buffer by one.
+
+If the error is not captured then you may get at some random point later on, usually at a finish() or disconnect() or even a fetch() this error;
+
+ ORA-03127: no new operations allowed until the active operation ends
+
+This is one of the more obscure ORA errors (have some fun and report it to Meta-Link they will scratch their heads for hours)
+
+If you get this, simply increment the ora_ncs_buff_mtpl by one until it goes away.
+
+This should greatly increase your ability to select very large CLOBs or NCLOBs, by freeing up a large block of memory.
+
+You can tune this value by setting ora_oci_success_warn which will display the following
+
+ OCILobRead field 2 of 3 SUCCESS: csform 1 (SQLCS_IMPLICIT), LOBlen 10240(characters), LongReadLen
+ 20(characters), BufLen 80(characters), Got 28(characters)
+
+In the case above the query Got 28 characters (well really only 20 characters of 28 bytes) so we could use ora_ncs_buff_mtpl=>2 (20*2=40) thus saving 40bytes of memory.
+
+
+=head4 Simple Fetch for CLOBs and BLOBs
+
+To use this interface for CLOBs and LOBs datatypes set the 'ora_pers_lob' attribute of the statement handle to '1' with the prepare method, as well
+set the database handle's 'LongReadLen' attribute to a value that will be the larger than the expected size of the LOB. If the size of the LOB exceeds
+the 'LongReadLen' DBD::Oracle will return a 'ORA-24345: A Truncation' error. To stop this set the database handle's 'LongTruncOk' attribute to '1'.
+The maximum value of 'LongReadLen' seems to be dependent on the physical memory limits of the box that Oracle is running on in the same way that LONGs and LONG RAWs are.
+
+For CLOBs and NCLOBs the limit is 64k chars if there is no truncation, this is an internal OCI limit complain to them if you want it changed. However if you CLOB is longer than this
+and also larger than the 'LongReadLen' than the 'LongReadLen' in chars is returned.
+
+It seems with BLOBs you are not limited by the 64k.
+
+For example give this table;
+
+ CREATE TABLE test_lob (id NUMBER,
+ clob1 CLOB,
+ clob2 CLOB,
+ blob1 BLOB,
+ blob2 BLOB)
+
+this code;
+
+ $dbh->{LongReadLen} = 2*1024*1024; #2 meg
+ $SQL='select p_id,lob_1,lob_2,blob_2 from test_lobs';
+ $sth=$dbh->prepare($SQL,{ora_pers_lob=>1});
+ $sth->execute();
+ while (my ( $p_id,$log,$log2,$log3,$log4 )=$sth->fetchrow()){
+ print "p_id=".$p_id."\n";
+ print "clob1=".$clob1."\n";
+ print "clob2=".$clob2."\n";
+ print "blob1=".$blob2."\n";
+ print "blob2=".$blob2."\n";
+ }
+
+Will select out all of the LOBs in the table as long as they are all under 2MB in length. Longer lobs will throw an error. Adding this line;
+
+ $dbh->{LongTruncOk}=1;
+
+before the execute will return all the lobs but they will be truncated at 2MBs.
+
+=head4 Piecewise Fetch with Callback
+
+With a piecewise callback fetch DBD::Oracle sets up a function that will 'callback' to the DB during the fetch and gets your LOB (LONG, LONG RAW, CLOB, BLOB) piece by piece.
+To use this interface set the 'ora_clbk_lob' attribute of the statement handle to '1' with the prepare method. Next set the 'ora_piece_size' to the size of the piece that
+you want to return on the callback. Finally set the database handle's 'LongReadLen' attribute to a value that will be the larger than the expected
+size of the LOB. Like the L</Simple Fetch for LONGs and LONG RAWs> and L</Simple Fetch for CLOBs and BLOBs> the if the size of the LOB exceeds the is 'LongReadLen' you can use the 'LongTruncOk' attribute to truncate the LOB
+or set the 'LongReadLen' to a higher value. With this interface the value of 'ora_piece_size' seems to be constrained by the same memory limit as found on
+the Simple Fetch interface. If you encounter an 'ORA-01062' error try setting the value of 'ora_piece_size' to a smaller value. The value for 'LongReadLen' is
+dependent on the version and settings of the Oracle DB you are using. In theory it ranges from 8GBs
+in 9iR1 up to 128 terabytes with 11g but you will also be limited by the physical memory of your PERL instance.
+
+Using the table from the last example this code;
+
+ $dbh->{LongReadLen} = 20*1024*1024; #20 meg
+ $SQL='select p_id,lob_1,lob_2,blob_2 from test_lobs';
+ $sth=$dbh->prepare($SQL,{ora_clbk_lob=>1,ora_piece_size=>5*1024*1024});
+ $sth->execute();
+ while (my ( $p_id,$log,$log2,$log3,$log4 )=$sth->fetchrow()){
+ print "p_id=".$p_id."\n";
+ print "clob1=".$clob1."\n";
+ print "clob2=".$clob2."\n";
+ print "blob1=".$blob2."\n";
+ print "blob2=".$blob2."\n";
+ }
+
+Will select out all of the LOBs in the table as long as they are all under 20MB in length. If the LOB is longer than 5MB (ora_piece_size) DBD::Oracle will fetch it in at least 2 pieces to a
+maximum of 4 pieces (4*5MB=20MB). Like the Simple Fetch examples Lobs longer than 20MB will throw an error.
+
+Using the table from the first example (LONG) this code;
+
+ $dbh->{LongReadLen} = 20*1024*1024; #2 meg
+ $SQL='select p_id,long1 from test_long';
+ $sth=$dbh->prepare($SQL,{ora_clbk_lob=>1,ora_piece_size=>5*1024*1024});
+ $sth->execute();
+ while (my ( $p_id,$long )=$sth->fetchrow()){
+ print "p_id=".$p_id."\n";
+ print "long=".$long."\n";
+ }
+
+Will select all of the long1 fields from table as long as they are is under 20MB in length. If the long1 filed is longer than 5MB (ora_piece_size) DBD::Oracle will fetch it in at least 2 pieces to a
+maximum of 4 pieces (4*5MB=20MB). Like the other examples long1 fields longer than 20MB will throw an error.
+
+=head4 Piecewise Fetch with Polling
+
+With a polling piecewise fetch DBD::Oracle iterates (Polls) over the LOB during the fetch getting your LOB (LONG, LONG RAW, CLOB, BLOB) piece by piece. To use this interface set the 'ora_piece_lob'
+attribute of the statement handle to '1' with the prepare method. Next set the 'ora_piece_size' to the size of the piece that
+you want to return on the callback. Finally set the database handle's 'LongReadLen' attribute to a value that will be the larger than the expected
+size of the LOB. Like the L</Piecewise Fetch with Callback> and Simple Fetches if the size of the LOB exceeds the is 'LongReadLen' you can use the 'LongTruncOk' attribute to truncate the LOB
+or set the 'LongReadLen' to a higher value. With this interface the value of 'ora_piece_size' seems to be constrained by the same memory limit as found on
+the L</Piecewise Fetch with Callback>.
+
+Using the table from the example above this code;
+
+ $dbh->{LongReadLen} = 20*1024*1024; #20 meg
+ $SQL='select p_id,lob_1,lob_2,blob_2 from test_lobs';
+ $sth=$dbh->prepare($SQL,{ora_piece_lob=>1,ora_piece_size=>5*1024*1024});
+ $sth->execute();
+ while (my ( $p_id,$log,$log2,$log3,$log4 )=$sth->fetchrow()){
+ print "p_id=".$p_id."\n";
+ print "clob1=".$clob1."\n";
+ print "clob2=".$clob2."\n";
+ print "blob1=".$blob2."\n";
+ print "blob2=".$blob2."\n";
+ }
+
+Will select out all of the LOBs in the table as long as they are all under 20MB in length. If the LOB is longer than 5MB (ora_piece_size) DBD::Oracle will fetch it in at least 2 pieces to a
+maximum of 4 pieces (4*5MB=20MB). Like the other fetch methods LOBs longer than 20MB will throw an error.
+
+Finally with this code;
+
+ $dbh->{LongReadLen} = 20*1024*1024; #2 meg
+ $SQL='select p_id,long1 from test_long';
+ $sth=$dbh->prepare($SQL,{ora_piece_lob=>1,ora_piece_size=>5*1024*1024});
+ $sth->execute();
+ while (my ( $p_id,$long )=$sth->fetchrow()){
+ print "p_id=".$p_id."\n";
+ print "long=".$long."\n";
+ }
+
+Will select all of the long1 fields from table as long as they are is under 20MB in length. If the long1 field is longer than 5MB (ora_piece_size) DBD::Oracle will fetch it in at least 2 pieces to a
+maximum of 4 pieces (4*5MB=20MB). Like the other examples long1 fields longer than 20MB will throw an error.
+
+=head4 Binding for Updates and Inserts for CLOBs and BLOBs
+
+To bind for updates and inserts all that is required to use this interface is to set the statement handle's prepare method
+'ora_type' attribute to 'SQLT_CHR' in the case of CLOBs and NCLOBs or 'SQLT_BIN' in the case of BLOBs as in this example for an insert;
+
+ my $in_clob = "<document>\n";
+ $in_clob .= " <value>$_</value>\n" for 1 .. 10_000;
+ $in_clob .= "</document>\n";
+ my $in_blob ="0101" for 1 .. 10_000;
+
+ $SQL='insert into test_lob3@tpgtest (id,clob1,clob2, blob1,blob2) values(?,?,?,?,?)';
+ $sth=$dbh->prepare($SQL );
+ $sth->bind_param(1,3);
+ $sth->bind_param(2,$in_clob,{ora_type=>SQLT_CHR});
+ $sth->bind_param(3,$in_clob,{ora_type=>SQLT_CHR});
+ $sth->bind_param(4,$in_blob,{ora_type=>SQLT_BIN});
+ $sth->bind_param(5,$in_blob,{ora_type=>SQLT_BIN});
+ $sth->execute();
+
+So far the only limit reached with this form of insert is the LOBs must be under 2GB in size.
+
+=head4 Support for Remote LOBs;
+
+Starting with Oracle 10gR2 the interface for Persistent LOBs was expanded to support remote LOBs (access over a dblink). Given a database called 'lob_test' that has a 'LINK' defined like this;
+
+ CREATE DATABASE LINK link_test CONNECT TO test_lobs IDENTIFIED BY tester USING 'lob_test';
+
+to a remote database called 'test_lobs', the following code will work;
+
+ $dbh = DBI->connect('dbi:Oracle:','test@lob_test','test');
+ $dbh->{LongReadLen} = 2*1024*1024; #2 meg
+ $SQL='select p_id,lob_1,lob_2,blob_2 from test_lobs@link_test';
+ $sth=$dbh->prepare($SQL,{ora_pers_lob=>1});
+ $sth->execute();
+ while (my ( $p_id,$log,$log2,$log3,$log4 )=$sth->fetchrow()){
+ print "p_id=".$p_id."\n";
+ print "clob1=".$clob1."\n";
+ print "clob2=".$clob2."\n";
+ print "blob1=".$blob2."\n";
+ print "blob2=".$blob2."\n";
+ }
+
+Below are the limitations of Remote LOBs;
+
+=over
+
+=item Queries involving more than one database are not supported;
+
+so the following returns an error:
+
+ SELECT t1.lobcol,
+ a2.lobcol
+ FROM t1,
+ t2.lobcol@dbs2 a2 W
+ WHERE LENGTH(t1.lobcol) = LENGTH(a2.lobcol);
+
+as does:
+
+ SELECT t1.lobcol
+ FROM t1@dbs1
+ UNION ALL
+ SELECT t2.lobcol
+ FROM t2@dbs2;
+
+=item DDL commands are not supported;
+
+so the following returns an error:
+
+ CREATE VIEW v AS SELECT lob_col FROM tab@dbs;
+
+=item Only binds and defines for data going into remote persistent LOBs are supported.
+
+so that parameter passing in PL/SQL where CHAR data is bound or defined for remote LOBs is not allowed .
+
+These statements all produce errors:
+
+ SELECT foo() FROM table1@dbs2;
+
+ SELECT foo()@dbs INTO char_val FROM DUAL;
+
+ SELECT XMLType().getclobval FROM table1@dbs2;
+
+=item If the remote object is a view such as
+
+ CREATE VIEW v AS SELECT foo() FROM ...
+
+the following would not work:
+
+ SELECT * FROM v@dbs2;
+
+=item Limited PL/SQL parameter passing
+
+PL/SQL parameter passing is not allowed where the actual argument is a LOB type
+and the remote argument is one of VARCHAR2, NVARCHAR2, CHAR, NCHAR, or RAW.
+
+=item RETURNING INTO does not support implicit conversions between CHAR and CLOB.
+
+so the following returns an error:
+
+ SELECT t1.lobcol as test, a2.lobcol FROM t1, t2.lobcol@dbs2 a2 RETURNING test
+
+=back
+
+=head3 B<Locator Data Interface>
+
+=head4 Simple Usage
+
+When fetching LOBs with this interface a 'LOB Locator' is created then used to get the lob with the LongReadLen and LongTruncOk attributes.
+The value for 'LongReadLen' is dependent on the version and settings of the Oracle DB you are using. In theory it ranges from 8GBs
+in 9iR1 up to 128 terabytes with 11g but you will also be limited by the physical memory of your PERL instance.
+
+When inserting or updating LOBs some I<major> magic has to be performed
+behind the scenes to make it transparent. Basically the driver has to
+insert a 'LOB Locator' and then refetch the newly inserted LOB
+Locator before being able to write the data into it. However, it works
+well most of the time, and I've made it as fast as possible, just one
+extra server-round-trip per insert or update after the first. For the
+time being, only single-row LOB updates are supported.
+
+To insert or update a large LOB using a placeholder, DBD::Oracle has to
+know in advance that it is a LOB type. So you need to say:
+
+ $sth->bind_param($field_num, $lob_value, { ora_type => ORA_CLOB });
+
+The ORA_CLOB and ORA_BLOB constants can be imported using
+
+ use DBD::Oracle qw(:ora_types);
+
+or use the corresponding integer values (112 and 113).
+
+One further wrinkle: for inserts and updates of LOBs, DBD::Oracle has
+to be able to tell which parameters relate to which table fields.
+In all cases where it can possibly work it out for itself, it does,
+however, if there are multiple LOB fields of the same type in the table
+then you need to tell it which field each LOB param relates to:
+
+ $sth->bind_param($idx, $value, { ora_type=>ORA_CLOB, ora_field=>'foo' });
+
+There are some limitations inherent in the way DBD::Oracle makes typical
+LOB operations simple by hiding the LOB Locator processing:
+
+ - Can't read/write LOBs in chunks (except via DBMS_LOB.WRITEAPPEND in PL/SQL)
+ - To INSERT a LOB, you need UPDATE privilege.
+
+The alternative is to disable the automatic LOB Locator processing.
+If L</ora_auto_lob> is 0 in prepare(), you can fetch the LOB Locators and
+do all the work yourself using the ora_lob_*() methods.
+See the L</Data Interface for LOB Locators> section below.
+
+=head4 LOB support in PL/SQL
+
+LOB Locators can be passed to PL/SQL calls by binding them to placeholders
+with the proper C<ora_type>. If L</ora_auto_lob> is true, output LOB
+parameters will be automatically returned as strings.
+
+If the Oracle driver has support for temporary LOBs (Oracle 9i and higher),
+strings can be bound to input LOB placeholders and will be automatically
+converted to LOBs.
+
+Example:
+ # Build a large XML document, bind it as a CLOB,
+ # extract elements through PL/SQL and return as a CLOB
+
+ # $dbh is a connected database handle
+ # output will be large
+
+ local $dbh->{LongReadLen} = 1_000_000;
+
+ my $in_clob = "<document>\n";
+ $in_clob .= " <value>$_</value>\n" for 1 .. 10_000;
+ $in_clob .= "</document>\n";
+
+ my $out_clob;
+
+
+ my $sth = $dbh->prepare(<<PLSQL_END);
+ -- extract 'value' nodes
+ DECLARE
+ x XMLTYPE := XMLTYPE(:in);
+ BEGIN
+ :out := x.extract('/document/value').getClobVal();
+ END;
+
+ PLSQL_END
+
+ # :in param will be converted to a temp lob
+ # :out parameter will be returned as a string.
+
+ $sth->bind_param( ':in', $in_clob, { ora_type => ORA_CLOB } );
+ $sth->bind_param_inout( ':out', \$out_clob, 0, { ora_type => ORA_CLOB } );
+ $sth->execute;
+
+If you ever get an
+
+ ORA-01691 unable to extend lob segment sss.ggg by nnn in tablespace ttt
+
+error, while attempting to insert a LOB, this means the Oracle user has insufficient space for LOB you are trying to insert.
+One solution it to use "alter database datafile 'sss.ggg' resize Mnnn" to increase the available memory for LOBs.
+
+=head3 B<Persistent & Locator Interface Caveats>
+
+Now that one has the option of using the Persistent or the Locator interface for LOBs the questions arises
+which one to use. For starters, if you want to access LOBs over a dblink you will have to use the Persistent
+interface so that choice is simple. The question of which one to use after that is a little more tricky.
+It basically boils down to a choice between LOB size and speed.
+
+The Callback and Polling piecewise fetches are very very slow
+when compared to the Simple and the Locator fetches but they can handle very large blocks of data. Given a situation where a
+large LOB is to be read the Locator fetch may time out while either of the piecewise fetches may not.
+
+With the Simple fetch you are limited by physical memory of your server but it runs a little faster than the Locator, as there are fewer round trips
+to the server. So if you have small LOBs and need to save a little bandwidth this is the one to use. It you are going after large LOBs then the Locator interface is the one to use.
+
+If you need to update more than a single row of with LOB data then the Persistent interface can do it while the Locator can't.
+
+If you encounter a situation where you have to access the legacy LOBs (LONG, LONG RAW) and the values are to large for you system then you can use
+the Callback or Polling piecewise fetches to get all of the data.
+
+Not all of the Persistent interface has been implemented yet, the following are not supported;
+
+ 1) Piecewise, polling and callback binds for INSERT and UPDATE operations.
+ 2) Piecewise array binds for SELECT, INSERT and UPDATE operations.
+
+Most of the time you should just use the L</Locator Data Interface> as this is in one that has the best combination of speed and size.
+
+All this being said if you are doing some critical programming I would use the L</Data Interface for LOB Locators> as this gives you very
+fine grain control of your LOBs, of course the code for this will be somewhat more involved.
+
+=head3 B<Data Interface for LOB Locators>
+
+The following driver-specific methods let you manipulate "LOB Locators" directly.
+To select a LOB locator directly set the if the C<ora_auto_lob>
+attribute to false, or alternatively they can be returned via PL/SQL procedure calls.
+
+(If using a DBI version earlier than 1.36 they must be called via the
+func() method. Note that methods called via func() don't honour
+RaiseError etc, and so it's important to check $dbh->err after each call.
+It's recommended that you upgrade to DBI 1.38 or later.)
+
+Note that LOB locators are only valid while the statement handle that
+created them is valid. When all references to the original statement
+handle are lost, the handle is destroyed and the locators are freed.
+
+=over 4
+
+=item ora_lob_read
+
+ $data = $dbh->ora_lob_read($lob_locator, $offset, $length);
+
+Read a portion of the LOB. $offset starts at 1.
+Uses the Oracle OCILobRead function.
+
+=item ora_lob_write
+
+ $rc = $dbh->ora_lob_write($lob_locator, $offset, $data);
+
+Write/overwrite a portion of the LOB. $offset starts at 1.
+Uses the Oracle OCILobWrite function.
+
+=item ora_lob_append
+
+ $rc = $dbh->ora_lob_append($lob_locator, $data);
+
+Append $data to the LOB. Uses the Oracle OCILobWriteAppend function.
+
+=item ora_lob_trim
+
+ $rc = $dbh->ora_lob_trim($lob_locator, $length);
+
+Trims the length of the LOB to $length.
+Uses the Oracle OCILobTrim function.
+
+=item ora_lob_length
+
+ $length = $dbh->ora_lob_length($lob_locator);
+
+Returns the length of the LOB.
+Uses the Oracle OCILobGetLength function.
+
+
+=item ora_lob_is_init
+
+ $is_init = $dbh->ora_lob_is_init($lob_locator);
+
+Returns true(1) if the Lob Locator is initialized false(0) if it is not, or 'undef'
+if there is an error.
+Uses the Oracle OCILobLocatorIsInit function.
+
+=item ora_lob_chunk_size
+
+ $chunk_size = $dbh->ora_lob_chunk_size($lob_locator);
+
+Returns the chunk size of the LOB.
+Uses the Oracle OCILobGetChunkSize function.
+
+For optimal performance, Oracle recommends reading from and
+writing to a LOB in batches using a multiple of the LOB chunk size.
+In Oracle 10g and before, when all defaults are in place, this
+chunk size defaults to 8k (8192).
+
+=back
+
+=head4 LOB Locator Method Examples
+
+I<Note:> Make sure you first read the note in the section above about
+multi-byte character set issues with these methods.
+
+The following examples demonstrate the usage of LOB Locators
+to read, write, and append data, and to query the size of
+large data.
+
+The following examples assume a table containing two large
+object columns, one binary and one character, with a primary
+key column, defined as follows:
+
+ CREATE TABLE lob_example (
+ lob_id INTEGER PRIMARY KEY,
+ bindata BLOB,
+ chardata CLOB
+ )
+
+It also assumes a sequence for use in generating unique
+lob_id field values, defined as follows:
+
+ CREATE SEQUENCE lob_example_seq
+
+
+=head4 Example: Inserting a new row with large data
+
+Unless enough memory is available to store and bind the
+entire LOB data for insert all at once, the LOB columns must
+be written interactively, piece by piece. In the case of a new row,
+this is performed by first inserting a row, with empty values in
+the LOB columns, then modifying the row by writing the large data
+interactively to the LOB columns using their LOB locators as handles.
+
+The insert statement must create token values in the LOB
+columns. Here, we use the empty string for both the binary
+and character large object columns 'bindata' and 'chardata'.
+
+After the INSERT statement, a SELECT statement is used to
+acquire LOB locators to the 'bindata' and 'chardata' fields
+of the newly inserted row. Because these LOB locators are
+subsequently written, they must be acquired from a select
+statement containing the clause 'FOR UPDATE' (LOB locators
+are only valid within the transaction that fetched them, so
+can't be used effectively if AutoCommit is enabled).
+
+ my $lob_id = $dbh->selectrow_array( <<" SQL" );
+ SELECT lob_example_seq.nextval FROM DUAL
+ SQL
+
+ my $sth = $dbh->prepare( <<" SQL" );
+ INSERT INTO lob_example
+ ( lob_id, bindata, chardata )
+ VALUES ( ?, EMPTY_BLOB(),EMPTY_CLOB() )
+ SQL
+ $sth->execute( $lob_id );
+
+ $sth = $dbh->prepare( <<" SQL", { ora_auto_lob => 0 } );
+ SELECT bindata, chardata
+ FROM lob_example
+ WHERE lob_id = ?
+ FOR UPDATE
+ SQL
+ $sth->execute( $lob_id );
+ my ( $bin_locator, $char_locator ) = $sth->fetchrow_array();
+ $sth->finish();
+
+ open BIN_FH, "/binary/data/source" or die;
+ open CHAR_FH, "/character/data/source" or die;
+ my $chunk_size = $dbh->ora_lob_chunk_size( $bin_locator );
+
+ # BEGIN WRITING BIN_DATA COLUMN
+ my $offset = 1; # Offsets start at 1, not 0
+ my $length = 0;
+ my $buffer = '';
+ while( $length = read( BIN_FH, $buffer, $chunk_size ) ) {
+ $dbh->ora_lob_write( $bin_locator, $offset, $buffer );
+ $offset += $length;
+ }
+
+ # BEGIN WRITING CHAR_DATA COLUMN
+ $chunk_size = $dbh->ora_lob_chunk_size( $char_locator );
+ $offset = 1; # Offsets start at 1, not 0
+ $length = 0;
+ $buffer = '';
+ while( $length = read( CHAR_FH, $buffer, $chunk_size ) ) {
+ $dbh->ora_lob_write( $char_locator, $offset, $buffer );
+ $offset += $length;
+ }
+
+
+In this example we demonstrate the use of ora_lob_write()
+interactively to append data to the columns 'bin_data' and
+'char_data'. Had we used ora_lob_append(), we could have
+saved ourselves the trouble of keeping track of the offset
+into the lobs. The snippet of code beneath the comment
+'BEGIN WRITING BIN_DATA COLUMN' could look as follows:
+
+ my $buffer = '';
+ while ( read( BIN_FH, $buffer, $chunk_size ) ) {
+ $dbh->ora_lob_append( $bin_locator, $buffer );
+ }
+
+The scalar variables $offset and $length are no longer
+needed, because ora_lob_append() keeps track of the offset
+for us.
+
+
+=head4 Example: Updating an existing row with large data
+
+In this example, we demonstrate a technique for overwriting
+a portion of a blob field with new binary data. The blob
+data before and after the section overwritten remains
+unchanged. Hence, this technique could be used for updating
+fixed length subfields embedded in a binary field.
+
+ my $lob_id = 5; # Arbitrary row identifier, for example
+
+ $sth = $dbh->prepare( <<" SQL", { ora_auto_lob => 0 } );
+ SELECT bindata
+ FROM lob_example
+ WHERE lob_id = ?
+ FOR UPDATE
+ SQL
+ $sth->execute( $lob_id );
+ my ( $bin_locator ) = $sth->fetchrow_array();
+
+ my $offset = 100234;
+ my $data = "This string will overwrite a portion of the blob";
+ $dbh->ora_lob_write( $bin_locator, $offset, $data );
+
+After running this code, the row where lob_id = 5 will
+contain, starting at position 100234 in the bin_data column,
+the string "This string will overwrite a portion of the blob".
+
+=head4 Example: Streaming character data from the database
+
+In this example, we demonstrate a technique for streaming
+data from the database to a file handle, in this case
+STDOUT. This allows more data to be read in and written out
+than could be stored in memory at a given time.
+
+ my $lob_id = 17; # Arbitrary row identifier, for example
+
+ $sth = $dbh->prepare( <<" SQL", { ora_auto_lob => 0 } );
+ SELECT chardata
+ FROM lob_example
+ WHERE lob_id = ?
+ SQL
+ $sth->execute( $lob_id );
+ my ( $char_locator ) = $sth->fetchrow_array();
+
+ my $chunk_size = 1034; # Arbitrary chunk size, for example
+ my $offset = 1; # Offsets start at 1, not 0
+ while(1) {
+ my $data = $dbh->ora_lob_read( $char_locator, $offset, $chunk_size );
+ last unless length $data;
+ print STDOUT $data;
+ $offset += $chunk_size;
+ }
+
+Notice that the select statement does not contain the phrase
+"FOR UPDATE". Because we are only reading from the LOB
+Locator returned, and not modifying the LOB it refers to,
+the select statement does not require the "FOR UPDATE"
+clause.
+
+A word of caution when using the data returned from an ora_lob_read in a conditional statement.
+for example if the code below;
+
+ while( my $data = $dbh->ora_lob_read( $char_locator, $offset, $chunk_size ) ) {
+ print STDOUT $data;
+ $offset += $chunk_size;
+ }
+
+was used with a chunk size of 4096 against a blob that requires more than 1 chunk to return
+the data and the last chunk is one byte long and contains a zero (ASCII 48) you will miss this last byte
+as $data will contain 0 which PERL will see as false and not print it out.
+
+=head4 Example: Truncating existing large data
+
+In this example, we truncate the data already present in a
+large object column in the database. Specifically, for each
+row in the table, we truncate the 'bindata' value to half
+its previous length.
-If you have many columns to bind you can use code like this:
+After acquiring a LOB Locator for the column, we query its
+length, then we trim the length by half. Because we modify
+the large objects with the call to ora_lob_trim(), we must
+select the LOB locators 'FOR UPDATE'.
- @params = (... column values for record to be inserted ...);
- $sth->bind_param($_, $params[$_-1]) for (1..@params);
- $sth->bind_param_inout(@params+1, \my $new_id, 99);
- $sth->execute;
+ my $sth = $dbh->prepare( <<" SQL", { ora_auto_lob => 0 } );
+ SELECT bindata
+ FROM lob_example
+ FOR UPATE
+ SQL
+ $sth->execute();
+ while( my ( $bin_locator ) = $sth->fetchrow_array() ) {
+ my $binlength = $dbh->ora_lob_length( $bin_locator );
+ if( $binlength > 0 ) {
+ $dbh->ora_lob_trim( $bin_locator, $binlength/2 );
+ }
+ }
-If you have many rows to insert you can take advantage of Oracle's built in execute array feature
-with code like this:
+=head1 PL/SQL Examples
- my @in_values=('1',2,'3','4',5,'6',7,'8',9,'10');
- my @out_values;
- my @status;
- my $sth = $dbh->prepare(qq{
- INSERT INTO foo (id, bar)
- VALUES (foo_id_seq.nextval, ?)
- RETURNING id INTO ?
- });
- $sth->bind_param_array(1,\@in_values);
- $sth->bind_param_inout_array(2,\@out_values,0,{ora_type => ORA_VARCHAR2});
- $sth->execute_array({ArrayTupleStatus=>\@status}) or die "error inserting";
- foreach my $id (@out_values){
- print 'returned id='.$id.'\n';
- }
+Most of these PL/SQL examples come from: Eric Bartley <[email protected]>.
-Which will return all the ids into @out_values.
+ /*
+ * PL/SQL to create package with stored procedures invoked by
+ * Perl examples. Execute using sqlplus.
+ *
+ * Use of "... OR REPLACE" prevents failure in the event that the
+ * package already exists.
+ */
-Note:
+ CREATE OR REPLACE PACKAGE plsql_example
+ IS
+ PROCEDURE proc_np;
-1) This will only work for numbered (?) placeholders,
+ PROCEDURE proc_in (
+ err_code IN NUMBER
+ );
-2) The third parameter of bind_param_inout_array, (0 in the example), "maxlen" is required by DBI but not used by DBD::Oracle
+ PROCEDURE proc_in_inout (
+ test_num IN NUMBER,
+ is_odd IN OUT NUMBER
+ );
-3) The "ora_type" attribute is not needed but only ORA_VARCHAR2 will work.
+ FUNCTION func_np
+ RETURN VARCHAR2;
-=head1 Returning a Recordset
+ END plsql_example;
+ /
-DBD::Oracle does not currently support binding a PL/SQL table (aka array)
-as an IN OUT parameter to any Perl data structure. You cannot therefore call
-a PL/SQL function or procedure from DBI that uses a non-atomic datatype as
-either a parameter, or a return value. However, if you are using Oracle 9.0.1
-or later, you can make use of table (or pipelined) functions.
+ CREATE OR REPLACE PACKAGE BODY plsql_example
+ IS
+ PROCEDURE proc_np
+ IS
+ whoami VARCHAR2(20) := NULL;
+ BEGIN
+ SELECT USER INTO whoami FROM DUAL;
+ END;
-For example, assume you have the existing PL/SQL Package :
+ PROCEDURE proc_in (
+ err_code IN NUMBER
+ )
+ IS
+ BEGIN
+ RAISE_APPLICATION_ERROR(err_code, 'This is a test.');
+ END;
- CREATE OR REPLACE PACKAGE Array_Example AS
- --
- TYPE tRec IS RECORD (
- Col1 NUMBER,
- Col2 VARCHAR2 (10),
- Col3 DATE) ;
- --
- TYPE taRec IS TABLE OF tRec INDEX BY BINARY_INTEGER ;
- --
- FUNCTION Array_Func RETURN taRec ;
- --
- END Array_Example ;
+ PROCEDURE proc_in_inout (
+ test_num IN NUMBER,
+ is_odd IN OUT NUMBER
+ )
+ IS
+ BEGIN
+ is_odd := MOD(test_num, 2);
+ END;
- CREATE OR REPLACE PACKAGE BODY Array_Example AS
- --
- FUNCTION Array_Func RETURN taRec AS
- --
- l_Ret taRec ;
- --
- BEGIN
- FOR i IN 1 .. 5 LOOP
- l_Ret (i).Col1 := i ;
- l_Ret (i).Col2 := 'Row : ' || i ;
- l_Ret (i).Col3 := TRUNC (SYSDATE) + i ;
- END LOOP ;
- RETURN l_Ret ;
- END ;
- --
- END Array_Example ;
+ FUNCTION func_np
+ RETURN VARCHAR2
+ IS
+ ret_val VARCHAR2(20);
+ BEGIN
+ SELECT USER INTO ret_val FROM DUAL;
+ RETURN ret_val;
+ END;
+
+ END plsql_example;
/
+ /* End PL/SQL for example package creation. */
-Currently, there is no way to directly call the function
-Array_Example.Array_Func from DBI. However, by making the following relatively
-painless additions, its not only possible, but extremely efficient.
+ use DBI;
-First, you need to create database object types that correspond to the record
-and table types in the package. From the above example, these would be :
+ my($db, $csr, $ret_val);
- CREATE OR REPLACE TYPE tArray_Example__taRec
- AS OBJECT (
- Col1 NUMBER,
- Col2 VARCHAR2 (10),
- Col3 DATE
- ) ;
+ $db = DBI->connect('dbi:Oracle:database','user','password')
+ or die "Unable to connect: $DBI::errstr";
- CREATE OR REPLACE TYPE taArray_Example__taRec
- AS TABLE OF tArray_Example__taRec ;
+ # So we don't have to check every DBI call we set RaiseError.
+ # See the DBI docs now if you're not familiar with RaiseError.
+ $db->{RaiseError} = 1;
-Now, assuming the existing function needs to remain unchanged (it is probably
-being called from other PL/SQL code), we need to add a new function to the
-package. Here's the new package specification and body :
+ # Example 1 Eric Bartley <[email protected]>
+ #
+ # Calling a PLSQL procedure that takes no parameters. This shows you the
+ # basic's of what you need to execute a PLSQL procedure. Just wrap your
+ # procedure call in a BEGIN END; block just like you'd do in SQL*Plus.
+ #
+ # p.s. If you've used SQL*Plus's exec command all it does is wrap the
+ # command in a BEGIN END; block for you.
- CREATE OR REPLACE PACKAGE Array_Example AS
- --
- TYPE tRec IS RECORD (
- Col1 NUMBER,
- Col2 VARCHAR2 (10),
- Col3 DATE) ;
- --
- TYPE taRec IS TABLE OF tRec INDEX BY BINARY_INTEGER ;
- --
- FUNCTION Array_Func RETURN taRec ;
- FUNCTION Array_Func_DBI RETURN taArray_Example__taRec PIPELINED ;
- --
- END Array_Example ;
+ $csr = $db->prepare(q{
+ BEGIN
+ PLSQL_EXAMPLE.PROC_NP;
+ END;
+ });
+ $csr->execute;
- CREATE OR REPLACE PACKAGE BODY Array_Example AS
- --
- FUNCTION Array_Func RETURN taRec AS
- l_Ret taRec ;
- BEGIN
- FOR i IN 1 .. 5 LOOP
- l_Ret (i).Col1 := i ;
- l_Ret (i).Col2 := 'Row : ' || i ;
- l_Ret (i).Col3 := TRUNC (SYSDATE) + i ;
- END LOOP ;
- RETURN l_Ret ;
- END ;
- FUNCTION Array_Func_DBI RETURN taArray_Example__taRec PIPELINED AS
- l_Set taRec ;
- BEGIN
- l_Set := Array_Func ;
- FOR i IN l_Set.FIRST .. l_Set.LAST LOOP
- PIPE ROW (
- tArray_Example__taRec (
- l_Set (i).Col1,
- l_Set (i).Col2,
- l_Set (i).Col3
- )
- ) ;
- END LOOP ;
- RETURN ;
- END ;
- --
- END Array_Example ;
+ # Example 2 Eric Bartley <[email protected]>
+ #
+ # Now we call a procedure that has 1 IN parameter. Here we use bind_param
+ # to bind out parameter to the prepared statement just like you might
+ # do for an INSERT, UPDATE, DELETE, or SELECT statement.
+ #
+ # I could have used positional placeholders (e.g. :1, :2, etc.) or
+ # ODBC style placeholders (e.g. ?), but I prefer Oracle's named
+ # placeholders (but few DBI drivers support them so they're not portable).
+
+ my $err_code = -20001;
+
+ $csr = $db->prepare(q{
+ BEGIN
+ PLSQL_EXAMPLE.PROC_IN(:err_code);
+ END;
+ });
+
+ $csr->bind_param(":err_code", $err_code);
+
+ # PROC_IN will RAISE_APPLICATION_ERROR which will cause the execute to 'fail'.
+ # Because we set RaiseError, the DBI will croak (die) so we catch that with eval.
+ eval {
+ $csr->execute;
+ };
+ print 'After proc_in: $@=',"'$@', errstr=$DBI::errstr, ret_val=$ret_val\n";
+
+
+ # Example 3 Eric Bartley <[email protected]>
+ #
+ # Building on the last example, I've added 1 IN OUT parameter. We still
+ # use a placeholders in the call to prepare, the difference is that
+ # we now call bind_param_inout to bind the value to the place holder.
+ #
+ # Note that the third parameter to bind_param_inout is the maximum size
+ # of the variable. You normally make this slightly larger than necessary.
+ # But note that the Perl variable will have that much memory assigned to
+ # it even if the actual value returned is shorter.
+
+ my $test_num = 5;
+ my $is_odd;
+
+ $csr = $db->prepare(q{
+ BEGIN
+ PLSQL_EXAMPLE.PROC_IN_INOUT(:test_num, :is_odd);
+ END;
+ });
-As you can see, the new function is very simple. Now, it is a simple matter
-of calling the function as a straight-forward SELECT from your DBI code. From
-the above example, the code would look something like this :
+ # The value of $test_num is _copied_ here
+ $csr->bind_param(":test_num", $test_num);
- my $sth = $dbh->prepare('SELECT * FROM TABLE(Array_Example.Array_Func_DBI)');
- $sth->execute;
- while ( my ($col1, $col2, $col3) = $sth->fetchrow_array {
- ...
- }
+ $csr->bind_param_inout(":is_odd", \$is_odd, 1);
-=head1 Timezones
+ # The execute will automagically update the value of $is_odd
+ $csr->execute;
-If TWO_TASK isn't set, Oracle uses the TZ variable from the local environment.
+ print "$test_num is ", ($is_odd) ? "odd - ok" : "even - error!", "\n";
-If TWO_TASK IS set, Oracle uses the TZ variable of the listener process
-running on the server.
-You could have multiple listeners, each with their own TZ, and assign
-users to the appropriate listener by setting TNS_ADMIN to a directory
-that contains a tnsnames.ora file that points to the port that their
-listener is on.
+ # Example 4 Eric Bartley <[email protected]>
+ #
+ # What about the return value of a PLSQL function? Well treat it the same
+ # as you would a call to a function from SQL*Plus. We add a placeholder
+ # for the return value and bind it with a call to bind_param_inout so
+ # we can access it's value after execute.
-[Brad Howerter, who supplied this info said: "I've done this to simulate
-running a Perl script at the end of the previous month even though it
-was the 6th of the new month. I had the dba start up a listener with
-TZ=X+144. (144 hours = 6 days)"]
+ my $whoami = "";
-=head1 Object & Collection Data Types
+ $csr = $db->prepare(q{
+ BEGIN
+ :whoami := PLSQL_EXAMPLE.FUNC_NP;
+ END;
+ });
-Oracle databases allow for the creation of object oriented like user-defined types.
-There are two types of objects, Embedded--an object stored in a column of a regular table
-and REF--an object that uses the REF retrieval mechanism.
+ $csr->bind_param_inout(":whoami", \$whoami, 20);
+ $csr->execute;
+ print "Your database user name is $whoami\n";
-DBD::Oracle supports only the 'selection' of embedded objects of the following types OBJECT, VARRAY
-and TABLE in any combination. Support is seamless and recursive, meaning you
-need only supply a simple SQL statement to get all the values in an embedded object.
-You can either get the values as an array of scalars or they can be returned into a DBD::Oracle::Object.
+ $db->disconnect;
+You can find more examples in the t/plsql.t file in the DBD::Oracle
+source directory.
-Array example, given this type and table;
+Oracle 9.2 appears to have a bug where a variable bound
+with bind_param_inout() that isn't assigned to by the executed
+PL/SQL block may contain garbage.
+See L<http://www.mail-archive.com/[email protected]/msg18835.html>
- CREATE OR REPLACE TYPE "PHONE_NUMBERS" as varray(10) of varchar(30);
+=head2 Avoid Using "SQL Call"
- CREATE TABLE "CONTACT"
- ( "COMPANYNAME" VARCHAR2(40),
- "ADDRESS" VARCHAR2(100),
- "PHONE_NUMBERS" "PHONE_NUMBERS"
- )
+Avoid using the "SQL Call" statement with DBD:Oracle as you might find that
+DBD::Oracle will not raise an exception in some case. Specifically if you use
+"SQL Call" to run a procedure all "No data found" exceptions will be quietly
+ignored and returned as null. According to Oracle support this is part of the same
+mechanism where;
-The code to access all the data in the table could be something like this;
+ select (select * from dual where 0=1) from dual
+
+returns a null value rather than an exception.
- my $sth = $dbh->prepare('SELECT * FROM CONTACT');
- $sth->execute;
- while ( my ($company, $address, $phone) = $sth->fetchrow()) {
- print "Company: ".$company."\n";
- print "Address: ".$address."\n";
- print "Phone #: ";
- foreach my $items (@$phone){
- print $items.", ";
- }
- print "\n";
- }
+=head1 Oracle Related Links
-Note that values in PHONE_NUMBERS are returned as an array reference '@$phone'.
+=head2 DBD::Oracle Tutorial
-As stated before DBD::Oracle will automatically drill into the embedded object and extract
-all of the data as reference arrays of scalars. The example below has OBJECT type embedded in a TABLE type embedded in an
-SQL TABLE;
+ http://www.pythian.com/blogs/wp-content/uploads/introduction-dbd-oracle.html
- CREATE OR REPLACE TYPE GRADELIST AS TABLE OF NUMBER;
+=head2 Oracle Instant Client
- CREATE OR REPLACE TYPE STUDENT AS OBJECT(
- NAME VARCHAR2(60),
- SOME_GRADES GRADELIST);
+ http://www.oracle.com/technology/tech/oci/instantclient/index.html
- CREATE OR REPLACE TYPE STUDENTS_T AS TABLE OF STUDENT;
+=head2 Oracle on Linux
- CREATE TABLE GROUPS(
- GRP_ID NUMBER(4),
- GRP_NAME VARCHAR2(10),
- STUDENTS STUDENTS_T)
- NESTED TABLE STUDENTS STORE AS GROUP_STUDENTS_TAB
- (NESTED TABLE SOME_GRADES STORE AS GROUP_STUDENT_GRADES_TAB);
+ http://www.eGroups.com/list/oracle-on-linux
-The following code will access all of the embedded data;
+ http://www.ixora.com.au/
- $SQL='select grp_id,grp_name,students as my_students_test from groups';
- $sth=$dbh->prepare($SQL);
- $sth->execute();
- while (my ($grp_id,$grp_name,$students)=$sth->fetchrow()){
- print "Group ID#".$grp_id." Group Name =".$grp_name."\n";
- foreach my $student (@$students){
- print "Name:".$student->[0]."\n";
- print "Marks:";
- foreach my $grades (@$student->[1]){
- foreach my $marks (@$grades){
- print $marks.",";
- }
- }
- print "\n";
- }
- print "\n";
- }
+=head2 Free Oracle Tools and Links
-Object example, given this object and table;
+ ora_explain supplied and installed with DBD::Oracle.
- CREATE OR REPLACE TYPE Person AS OBJECT (
- name VARCHAR2(20),
- age INTEGER)
- ) NOT FINAL;
+ http://www.orafaq.com/
- CREATE TYPE Employee UNDER Person (
- salary NUMERIC(8,2)
- );
+ http://vonnieda.org/oracletool/
- CREATE TABLE people (id INTEGER, obj Person);
+=head2 Commercial Oracle Tools and Links
- INSERT INTO people VALUES (1, Person('Black', 25));
- INSERT INTO people VALUES (2, Employee('Smith', 44, 5000));
+Assorted tools and references for general information.
+No recommendation implied.
-The following code will access the data;
+ http://www.platinum.com/products/oracle.htm
+ http://www.SoftTreeTech.com
+ http://www.databasegroup.com
- $dbh{'ora_objects'} =>1;
+Also PL/Vision from RevealNet and Steven Feuerstein, and
+"Q" from Savant Corporation.
- $sth = $dbh->prepare("select * from people order by id");
- $sth->execute();
- # object are fetched as instance of DBD::Oracle::Object
- my ($id1, $obj1) = $sth->fetchrow();
- my ($id2, $obj2) = $sth->fetchrow();
+=head1 SEE ALSO
- # get full type-name of object
- print $obj1->type_name."44\n"; # 'TEST.PERSON' is printed
- print $obj2->type_name."4\n"; # 'TEST.EMPLOYEE' is printed
+DBI
- # get attribute NAME from object
- print $obj1->attr('NAME')."3\n"; # 'Black' is printed
- print $obj2->attr('NAME')."3\n"; # 'Smith' is printed
+http://search.cpan.org/~timb/DBD-Oracle/MANIFEST for all files in
+the DBD::Oracle source distribution including the examples in the
+Oracle.ex directory
- # get all atributes as hash reference
- my $h1 = $obj1->attr; # returns {'NAME' => 'Black', 'AGE' => 25}
- my $h2 = $obj2->attr; # returns {'NAME' => 'Smith', 'AGE' => 44,
- # 'SALARY' => 5000 }
+ http://search.cpan.org/search?query=Oracle&mode=dist
- # get all attributes (names and values) as array
- my @a1 = $obj1->attributes; # returns ('NAME', 'Black', 'AGE', 25)
- my @a2 = $obj2->attributes; # returns ('NAME', 'Smith', 'AGE', 44,
- # 'SALARY', 5000 )
+=head1 AUTHOR
-So far DBD::Oracle has been tested on a table with 20 embedded Objects, Varrays and Tables
-nested to 10 levels.
+DBD::Oracle by Tim Bunce. DBI by Tim Bunce.
-Any NULL values found in the embedded object will be returned as 'undef'.
+=head1 ACKNOWLEDGEMENTS
-=head1 Support for Insert of XMLType (ORA_XMLTYPE)
+A great many people have helped me with DBD::Oracle over the 17 years
+between 1994 and 2011. Far too many to name, but I thank them all.
+Many are named in the Changes file.
-Inserting large XML data sets into tables with XMLType fields is now supported by DBD::Oracle. The only special
-requirement is the use of bind_param() with an attribute hash parameter that specifies ora_type as ORA_XMLTYPE. For
-example with a table like this;
+See also L<DBI/ACKNOWLEDGEMENTS>.
- create table books (book_id number, book_xml XMLType);
+=head1 MAINTAINER
-one can insert data using this code
+As of release 1.17 in February 2006 The Pythian Group, Inc. (L<http://www.pythian.com>)
+are taking the lead in maintaining DBD::Oracle with my assistance and
+gratitude. That frees more of my time to work on DBI for Perl 5 and Perl 6.
- $SQL='insert into books values (1,:p_xml)';
- $xml= '<Books>
- <Book id=1>
- <Title>Programming the Perl DBI</Title>
- <Subtitle>The Cheetah Book</Subtitle>
- <Authors>
- <Author>T. Bunce</Author>
- <Author>Alligator Descartes</Author>
- </Authors>
+=head1 COPYRIGHT
- </Book>
- <Book id=10000>...
- </Books>';
- my $sth =$dbh-> prepare($SQL);
- $sth-> bind_param("p_xml", $xml, { ora_type => ORA_XMLTYPE });
- $sth-> execute();
+The DBD::Oracle module is Copyright (c) 1994-2006 Tim Bunce. Ireland.
+The DBD::Oracle module is Copyright (c) 2006-2011 John Scoles (The Pythian Group). Canada.
+The DBD::Oracle module is Copyright (c) 2011 John Scoles. Canada.
-In the above case we will assume that $xml has 10000 Book nodes and is over 32k in size and is well formed XML.
-This will also work for XML that is smaller than 32k as well. Attempting to insert malformed XML will cause an error.
+The DBD::Oracle module is free open source software; you can
+redistribute it and/or modify it under the same terms as Perl 5.
=head1 CONTRIBUTING
@@ -4736,7 +5546,7 @@
After making your changes you can generate a patch file, but before
you do, make sure your source is still upto date using:
- svn update
+ svn update
If you get any conflicts reported you'll need to fix them first.
Then generate the patch file from within the C<trunk> directory using:
@@ -4782,74 +5592,8 @@
of them being rejected because they don't fit into some larger plans
you may not be aware of.
-=head1 Oracle Related Links
-
-=head2 DBD::Oracle Tutorial
-
- http://www.pythian.com/blogs/wp-content/uploads/introduction-dbd-oracle.html
-
-=head2 Oracle Instant Client
-
- http://www.oracle.com/technology/tech/oci/instantclient/index.html
-
-=head2 Oracle on Linux
-
- http://www.ixora.com.au/
-
-=head2 Free Oracle Tools and Links
-
- ora_explain supplied and installed with DBD::Oracle.
-
- http://www.orafaq.com/
-
- http://vonnieda.org/oracletool/
-
-=head2 Commercial Oracle Tools and Links
-
-Assorted tools and references for general information.
-No recommendation implied.
-
- http://www.platinum.com
- http://www.SoftTreeTech.com
-
-Also PL/Vision from RevealNet and Steven Feuerstein, and
-"Q" from Savant Corporation.
-
-
-=head1 SEE ALSO
-
-DBI
-
-http://search.cpan.org/~timb/DBD-Oracle/MANIFEST for all files in
-the DBD::Oracle source distribution including the examples in the
-Oracle.ex directory
-
- http://search.cpan.org/search?query=Oracle&mode=dist
-
-=head1 AUTHOR
-
-DBD::Oracle by Tim Bunce. DBI by Tim Bunce.
-
-=head1 ACKNOWLEDGEMENTS
-
-A great many people have helped me with DBD::Oracle over the 14 years
-between 1994 and 2008. Far too many to name, but I thank them all.
-Many are named in the Changes file.
-
-See also L<DBI/ACKNOWLEDGEMENTS>.
-
-=head1 MAINTAINER
-
-As of release 1.17 in February 2006 The Pythian Group, Inc. (L<http://www.pythian.com>)
-are taking the lead in maintaining DBD::Oracle with my assistance and
-gratitude. That frees more of my time to work on DBI for Perl 5 and Perl 6.
+=cut
-=head1 COPYRIGHT
-The DBD::Oracle module is Copyright (c) 1994-2006 Tim Bunce. Ireland.
-The DBD::Oracle module is Copyright (c) 2006-2011 John Scoles (The Pythian Group). Canada.
-The DBD::Oracle module is free open source software; you can
-redistribute it and/or modify it under the same terms as Perl 5.
-=cut
Modified: dbd-oracle/trunk/Oraperl.pm
==============================================================================
--- dbd-oracle/trunk/Oraperl.pm (original)
+++ dbd-oracle/trunk/Oraperl.pm Fri May 13 05:46:22 2011
@@ -229,7 +229,7 @@
=head1 NAME
-Oraperl - deprecated (Will be removed from DBD::Oracle in 1.29) Perl access to Oracle databases for old oraperl scripts
+Oraperl - deprecated (Repreived for now, but Will be removed in a future release) Perl access to Oracle databases for old oraperl scripts
=head1 SYNOPSIS
Modified: dbd-oracle/trunk/oci8.c
==============================================================================
--- dbd-oracle/trunk/oci8.c (original)
+++ dbd-oracle/trunk/oci8.c Fri May 13 05:46:22 2011
@@ -969,7 +969,6 @@
IV ora_pers_lob = 0;
IV ora_piece_lob = 0;
IV ora_clbk_lob = 0;
- ub4 oparse_lng = 1; /* auto v6 or v7 as suits db connected to */
int ora_check_sql = 1; /* to force a describe to check SQL */
IV ora_placeholders = 1; /* find and handle placeholders */
/* XXX we set ora_check_sql on for now to force setup of the */
@@ -1004,7 +1003,6 @@
if (attribs) {
SV **svp;
IV ora_auto_lob = 1;
- DBD_ATTRIB_GET_IV( attribs, "ora_parse_lang", 14, svp, oparse_lng);
DBD_ATTRIB_GET_IV( attribs, "ora_placeholders", 16, svp, ora_placeholders);
DBD_ATTRIB_GET_IV( attribs, "ora_auto_lob", 12, svp, ora_auto_lob);
DBD_ATTRIB_GET_IV( attribs, "ora_pers_lob", 12, svp, ora_pers_lob);
@@ -1046,18 +1044,12 @@
imp_sth->srvhp = imp_dbh->srvhp;
imp_sth->svchp = imp_dbh->svchp;
- switch(oparse_lng) {
- case 0: /* old: calls for V6 syntax - give them V7 */
- case 2: /* old: calls for V7 syntax */
- case 7: oparse_lng = OCI_V7_SYNTAX; break;
- case 8: oparse_lng = OCI_V8_SYNTAX; break;
- default: oparse_lng = OCI_NTV_SYNTAX; break;
- }
+
OCIHandleAlloc_ok(imp_dbh->envhp, &imp_sth->stmhp, OCI_HTYPE_STMT, status);
OCIStmtPrepare_log_stat(imp_sth->stmhp, imp_sth->errhp,
(text*)imp_sth->statement, (ub4)strlen(imp_sth->statement),
- oparse_lng, OCI_DEFAULT, status);
+ OCI_NTV_SYNTAX, OCI_DEFAULT, status);
if (status != OCI_SUCCESS) {
oci_error(sth, imp_sth->errhp, status, "OCIStmtPrepare");
@@ -1070,9 +1062,9 @@
OCIAttrGet_stmhp_stat(imp_sth, &imp_sth->stmt_type, 0, OCI_ATTR_STMT_TYPE, status);
if (DBIS->debug >= 3 || dbd_verbose >= 3 )
- PerlIO_printf(DBILOGFP, " dbd_st_prepare'd sql %s (pl%d, auto_lob%d, check_sql%d)\n",
+ PerlIO_printf(DBILOGFP, " dbd_st_prepare'd sql %s ( auto_lob%d, check_sql%d)\n",
oci_stmt_type_name(imp_sth->stmt_type),
- oparse_lng, imp_sth->auto_lob, ora_check_sql);
+ imp_sth->auto_lob, ora_check_sql);
DBIc_IMPSET_on(imp_sth);
@@ -1080,30 +1072,7 @@
if (!dbd_describe(sth, imp_sth))
return 0;
}
-/* else {
- set initial cache size by memory
- [I'm not now sure why this is here - from a patch sometime ago - Tim]
- you are right Tim thre is no need to have this here so out it goes
- a very useless call to the server
- ub4 cache_mem;
- IV cache_mem_iv;
- D_imp_dbh_from_sth ;
- D_imp_drh_from_dbh ;
- if(SvOK(imp_drh->ora_cache_o)) cache_mem_iv = -SvIV(imp_drh -> ora_cache_o);
- else if (SvOK(imp_drh->ora_cache)) cache_mem_iv = -SvIV(imp_drh -> ora_cache);
- else cache_mem_iv = -imp_dbh->RowCacheSize;
- cache_mem = (cache_mem_iv <= 0) ? 10 * 1460 : cache_mem_iv;
- OCIAttrSet_log_stat(imp_sth->stmhp, OCI_HTYPE_STMT,
- &cache_mem, sizeof(cache_mem), OCI_ATTR_PREFETCH_MEMORY,
- imp_sth->errhp, status);
- if (status != OCI_SUCCESS) {
- oci_error(sth, imp_sth->errhp, status,
- "OCIAttrSet OCI_ATTR_PREFETCH_MEMORY");
- return 0;
- }
- }
-*/
return 1;
}