[svn:dbd-oracle] r14814 - dbd-oracle/branches/TAF

Author: byterock
Date: Mon Apr  4 10:05:29 2011
New Revision: 14814

Modified:
   dbd-oracle/branches/TAF/Oracle.pm

Log:
updating Pod ready to merge

Modified: dbd-oracle/branches/TAF/Oracle.pm
==============================================================================
--- dbd-oracle/branches/TAF/Oracle.pm	(original)
+++ dbd-oracle/branches/TAF/Oracle.pm	Mon Apr  4 10:05:29 2011
@@ -1143,9 +1143,11 @@
   |      1.25+          | N  |      N      |    N    |  N   |    N   |    Y   |
   +---------------------+----+-------------+---------+------+--------+--------+
 
-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.  
+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.
+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;
 
@@ -1432,9 +1434,9 @@
 
 =head2 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 an 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 callback event takes place. The main use of the callback is that it 
-gives the oppertunity for the program to inform the user that a failover is taking place.  
+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 
+oppertunity for the program 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 
 
@@ -1452,8 +1454,8 @@
                (RETRIES=10)
                (DELAY=10))
 
-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 allways return
-two values, the failover event value and the failover type value.  You can also set a sleep value in case of failover error and the oci client will sleep 
+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 allways 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));
@@ -1735,6 +1737,31 @@
 
 This value can be set at the environment level with 'ORA_DRCP_INCR'.
 
+
+=item ora_taf
+
+If your Oracle instace has been configured to use TAF events you can enable the TAF callback by seting this
+value to anything other than 0;
+
+=item ora_taf_function
+
+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
+allways 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
+
+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.
+
+
 =item ora_session_mode
 
 The ora_session_mode attribute can be used to connect with SYSDBA
@@ -3107,9 +3134,7 @@
   # retrieve the string
   $date_string = $dbh->func( 'dbms_output_get' );
 
-=over 4
-
-=item dbms_output_enable ( [ buffer_size ] )
+=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
@@ -3120,7 +3145,7 @@
 buffer and must be between 2000 and 1,000,000.  If buffer_size is not
 given, the default is 20,000 bytes.
 
-=item dbms_output_put ( [ @lines ] )
+=head2 dbms_output_put ( [ @lines ] )
 
 This function calls DBMS_OUTPUT.PUT_LINE to add lines to the buffer.
 
@@ -3131,7 +3156,7 @@
 is raised and the function call fails.  Some of the text might be in
 the buffer.
 
-=item dbms_output_get
+=head2 dbms_output_get
 
 This function calls DBMS_OUTPUT.GET_LINE to retrieve lines of text from
 the buffer.
@@ -3147,18 +3172,18 @@
 DBMS_OUTPUT.GET is discarded by the next call to DBMS_OUTPUT.PUT_LINE,
 DBMS_OUTPUT.PUT, or DBMS_OUTPUT.NEW_LINE.
 
-=item reauthenticate ( $username, $password )
+=head2 reauthenticate ( $username, $password )
 
 Starts a new session against the current database using the credentials
 supplied.
 
-=item ora_nls_parameters ( [ $refresh ] )
+=head2 ora_nls_parameters ( [ $refresh ] )
 
 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.
 
-=item ora_can_unicode ( [ $refresh ] )
+=head2 ora_can_unicode ( [ $refresh ] )
 
 Returns a number indicating whether either of the database character sets
 is a Unicode encoding. Calls ora_nls_parameters() and passes the optional
@@ -3172,22 +3197,22 @@
 
 3 = Both character sets are Unicode encodings.
 
-=back
+=head2 ora_can_taf 
+
+Returns true if the current connection supports TAF events. False if otherise.
 
 =head1 Private statement handle functions
 
 =over
 
-=item ora_stmt_type
+=head2 ora_stmt_type
 
 Returns the OCI Statement Type number for the SQL of a statement handle.
 
-=item ora_stmt_type_name
+=head2 ora_stmt_type_name
 
 Returns the OCI Statement Type name for the SQL of a statement handle.
 
-=back
-
 =head1 Scrollable Cursors
 
 Oracle supports the concept of a 'Scrollable Cursor' which is defined as a 'Result Set' where