XS, Advanced XS Callback Patch For OCI, Part III The Plan

Adding some more for the new chapter in XS Fun. Today I am just going to go my implimetaion plan of what needs to be changed how that fits into the world of XS

The Plan

The first thing to note about this patch is that there is no change to the Oracle.xs file. Now the reason for this is has been hinted at earlier in the chapter and that is DBD::Oracle is largely a 'C' program that is linked directly with Perl using dynaloader and its bootstrap method.

So we can ignore Oracle.xs in this patch and that leads us to the question what is going to be patched? Well the answer is almost every file but the Oracle.xs as this patch digs very deeply into the guts of DBB::Oracle, and OCI but never fear there is lots of XS work that has to be done as well.

Step 1 The API

One of the reasons DBI and DBDs have managed to stick around for almost 20 years and have been copied by PHP and D it that is provides a standard API across a multitude of differing DBs. Now when one is playing with DBDs one wants to keep within that API.

So that means we just can't add in new functions in our DBD willy-nilly especially as this is very Oracle specific functionality. Now to limit the API to just to the present DBI spec would be just as bad as there are many many differing flavors of DBs and each having their own custom methods and attributes So the designers of DBI and given us some wiggle room when is comes to custom methods and attriburtes.

One can simply add in the custom method on any of the DBI handles and as long as one prepends that function with a DBD specific name. For example in DBD::Oracle one uses ora_ and you can see there are a number of them 'ora_can_unicode' or 'ora_stmt_type' for example. This of course handles new methods but what about attributes that a specific to a DB the same rule applies and DBD::Oracle has a whole bunch of these like 'ora_dbh_share', 'ora_ph_type' and 'ora_ncharset'

Now in the case of this patch we will not be adding a new custom function to DBD::Oracle as FAN events do not work in this way, it is more a configuration that is set that we can tap into. So what we will be doing is adding in a number of custom attributes to DBD::Oracle so these can be passed to Oracle via OCI.

DBI has a number of pathways to enter the values of these attributes in general one can do this

  • on connect
  • on prepare
  • on bind
  • on select and
  • on execute

by passing in a Hash-Ref that contains the attribute key value pairs into the method call. It is normally the scope of the attribute that will determine at what point and on what handle you enter the value in.

In the case of this Patch 'FAN events' are global setting so we will be passing our configuration attributes on connect.

Now the question is what attributes do we need? Well reading the OCI doc all we will really need to get from Perl is just the function name or a reference to a function and looking a the very similar TAF functionality all we need is


Which will point to the name or a code reference to our Perl function. So its use would be something like

my $DBH = DBI->connect("Oracle:XS",'HR','HR',{ora_ha_function=>'some_fucntion});

Now how to set this up in DBD::Oracle?

Well we will see tomorrow


Leave a comment

About byterock

user-pic Long time Perl guy, a few CPAN mods allot of work on DBD::Oracle and a few YAPC presentations