DBI::DBD::SqlEngine::HowTo man page on AIX

Man page or keyword search:  
man Server   4752 pages
apropos Keyword Search (all sections)
Output format
AIX logo
[printable version]

DBI::DBD::SqlEngine::HUser(Contributed Perl DocumDBI::DBD::SqlEngine::HowTo(3)

NAME
       DBI::DBD::SqlEngine::HowTo - Guide to create DBI::DBD::SqlEngine based
       driver

SYNOPSIS
	 perldoc DBI::DBD::SqlEngine::HowTo
	 perldoc DBI
	 perldoc DBI::DBD
	 perldoc DBI::DBD::SqlEngine::Developers
	 perldoc SQL::Eval
	 perldoc DBI::DBD::SqlEngine
	 perldoc DBI::DBD::SqlEngine::HowTo
	 perldoc SQL::Statement::Embed

DESCRIPTION
       This document provides a step-by-step guide, how to create a new
       "DBI::DBD::SqlEngine" based DBD. It expects that you carefully read the
       DBI documentation and that you're familiar with DBI::DBD and had read
       and understood DBD::ExampleP.

       This document addresses experienced developers who are really sure that
       they need to invest time when writing a new DBI Driver. Writing a DBI
       Driver is neither a weekend project nor an easy job for hobby coders
       after work. Expect one or two man-month of time for the first start.

       Those who are still reading, should be able to sing the rules of "CRE‐
       ATING A NEW DRIVER" in DBI::DBD.

CREATING DRIVER CLASSES
       Do you have an entry in DBI's DBD registry? For this guide, a prefix of
       "foo_" is assumed.

       Sample Skeleton

	   package DBD::Foo;

	   use strict;
	   use warnings;
	   use vars qw($VERSION);
	   use base qw(DBI::DBD::SqlEngine);

	   use DBI ();

	   $VERSION = "0.001";

	   package DBD::Foo::dr;

	   use vars qw(@ISA $imp_data_size);

	   @ISA = qw(DBI::DBD::SqlEngine::dr);
	   $imp_data_size = 0;

	   package DBD::Foo::db;

	   use vars qw(@ISA $imp_data_size);

	   @ISA = qw(DBI::DBD::SqlEngine::db);
	   $imp_data_size = 0;

	   package DBD::Foo::st;

	   use vars qw(@ISA $imp_data_size);

	   @ISA = qw(DBI::DBD::SqlEngine::st);
	   $imp_data_size = 0;

	   package DBD::Foo::Statement;

	   use vars qw(@ISA);

	   @ISA = qw(DBI::DBD::SqlEngine::Statement);

	   package DBD::Foo::Table;

	   use vars qw(@ISA);

	   @ISA = qw(DBI::DBD::SqlEngine::Table);

	   1;

       Tiny, eh? And all you have now is a DBD named foo which will is able to
       deal with temporary tables, as long as you use SQL::Statement. In
       DBI::SQL::Nano environments, this DBD can do nothing.

       Deal with own attributes

       Before we start doing usable stuff with our DBI driver, we need to
       think about what we want to do and how we want to do it.

       Do we need tunable knobs accessible by users? Do we need status infor‐
       mation? All this is handled in attributes of the database handles (be
       careful when your DBD is running "behind" a DBD::Gofer proxy).

       How come the attributes into the DBD and how are they fetchable by the
       user? Good question, but you should know because you've read the DBI
       documentation.

       "DBI::DBD::SqlEngine::db::FETCH" and "DBI::DBD::SqlEngine::db::STORE"
       taking care for you - all they need to know is which attribute names
       are valid and mutable or immutable. Tell them by adding
       "init_valid_attributes" to your db class:

	   sub init_valid_attributes
	   {
	       my $dbh = $_[0];

	       $dbh->SUPER::init_valid_attributes ();

	       $dbh->{foo_valid_attrs} = {
		   foo_version	       => 1,   # contains version of this driver
		   foo_valid_attrs     => 1,   # contains the valid attributes of foo drivers
		   foo_readonly_attrs  => 1,   # contains immutable attributes of foo drivers
		   foo_bar	       => 1,   # contains the bar attribute
		   foo_baz	       => 1,   # contains the baz attribute
		   foo_manager	       => 1,   # contains the manager of the driver instance
		   foo_manager_type    => 1,   # contains the manager class of the driver instance
	       };
	       $dbh->{foo_readonly_attrs} = {
		   foo_version	       => 1,   # ensure no-one modifies the driver version
		   foo_valid_attrs     => 1,   # do not permit to add more valid attributes ...
		   foo_readonly_attrs  => 1,   # ... or make the immutable mutable
		   foo_manager	       => 1,   # manager is set internally only
	       };

	       return $dbh;
	   }

       Woooho - but now the user cannot assign new managers? This is intended,
       overwrite "STORE" to handle it!

	   sub STORE ($$$)
	   {
	       my ( $dbh, $attrib, $value ) = @_;

	       $dbh->SUPER::STORE( $attrib, $value );

	       # we're still alive, so no exception is thrown ...
	       # by DBI::DBD::SqlEngine::db::STORE
	       if ( $attrib eq "foo_manager_type" )
	       {
		   $dbh->{foo_manager} = $dbh->{foo_manager_type}->new();
		   # ... probably correct some states based on the new
		   # foo_manager_type - see DBD::Sys for an example
	       }
	   }

       But ... my driver runs without a manager until someone first assignes a
       "foo_manager_type". Well, no - there're two places where you can ini‐
       tialize defaults:

	   sub init_default_attributes
	   {
	       my ($dbh, $phase) = @_;

	       $dbh->SUPER::init_default_attributes($phase);

	       if( 0 == $phase )
	       {
		   # init all attributes which have no knowledge about
		   # user settings from DSN or the attribute hash
		   $dbh->{foo_manager_type} = "DBD::Foo::Manager";
	       }
	       elsif( 1 == $phase )
	       {
		   # init phase with more knowledge from DSN or attribute
		   # hash
		   $dbh->{foo_manager} = $dbh->{foo_manager_type}->new();
	       }

	       return $dbh;
	   }

       So far we can prevent the users to use our database driver as data
       storage for anything and everything. We care only about the real impor‐
       tant stuff for peace on earth and alike attributes. But in fact, the
       driver still can't do anything. It can do less than nothing - meanwhile
       it's not a stupid storage area anymore.

       Dealing with Tables

       Let's put some life into it - it's going to be time for it.

       This is a good point where a quick side step to SQL::Statement::Embed
       will help to shorten the next paragraph. The documentation in
       SQL::Statement::Embed regarding embedding in own DBD's works pretty
       fine with SQL::Statement and DBI::SQL::Nano.

       Testing

       Now you should have your first own DBD. Was easy, wasn't it?  But does
       it work well? Prove it by writing tests and remember to use
       dbd_edit_mm_attribs from DBI::DBD to ensure testing even rare cases.

AUTHOR
       This guide is written by Jens Rehsack. DBI::DBD::SqlEngine is written
       by Jens Rehsack using code from DBD::File originally written by Jochen
       Wiedmann and Jeff Zucker.

       The module DBI::DBD::SqlEngine is currently maintained by

       H.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack  < rehsack
       at googlemail.com >

COPYRIGHT AND LICENSE
       Copyright (C) 2010 by H.Merijn Brand & Jens Rehsack

       All rights reserved.

       You may freely distribute and/or modify this module under the terms of
       either the GNU General Public License (GPL) or the Artistic License, as
       specified in the Perl README file.

perl v5.8.8			  2010-08-30	 DBI::DBD::SqlEngine::HowTo(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server AIX

List of man pages available for AIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net