huschi.net

DBD::File::HowTo(3)   User Contributed Perl Documentation  DBD::File::HowTo(3)
NAME
       DBD::File::HowTo - Guide to create DBD::File based driver
SYNOPSIS
         perldoc DBD::File::HowTo
         perldoc DBI
         perldoc DBI::DBD
         perldoc DBD::File::Developers
         perldoc DBI::DBD::SqlEngine::Developers
         perldoc DBI::DBD::SqlEngine
         perldoc SQL::Eval
         perldoc DBI::DBD::SqlEngine::HowTo
         perldoc SQL::Statement::Embed
         perldoc DBD::File
         perldoc DBD::File::HowTo
         perldoc DBD::File::Developers
DESCRIPTION
       This document provides a step-by-step guide, how to create a new
       "DBD::File" 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
       "CREATING A NEW DRIVER" in DBI::DBD.
       Of course, DBD::File is a DBI::DBD::SqlEngine and you surely read
       DBI::DBD::SqlEngine::HowTo before continuing here.
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(@ISA $VERSION);
           use base qw(DBD::File);
           use DBI ();
           $VERSION = "0.001";
           package DBD::Foo::dr;
           use vars qw(@ISA $imp_data_size);
           @ISA = qw(DBD::File::dr);
           $imp_data_size = 0;
           package DBD::Foo::db;
           use vars qw(@ISA $imp_data_size);
           @ISA = qw(DBD::File::db);
           $imp_data_size = 0;
           package DBD::Foo::st;
           use vars qw(@ISA $imp_data_size);
           @ISA = qw(DBD::File::st);
           $imp_data_size = 0;
           package DBD::Foo::Statement;
           use vars qw(@ISA);
           @ISA = qw(DBD::File::Statement);
           package DBD::Foo::Table;
           use vars qw(@ISA);
           @ISA = qw(DBD::File::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.
   Start over
       Based on DBI::DBD::SqlEngine::HowTo, we're now having a driver which
       could do basic things. Of course, it should now derive from DBD::File
       instead of DBI::DBD::SqlEngine, shouldn't it?
       DBD::File extends DBI::DBD::SqlEngine to deal with any kind of files.
       In principle, the only extensions required are to the table class:
           package DBD::Foo::Table;
           sub bootstrap_table_meta
           {
               my ( $self, $dbh, $meta, $table ) = @_;
               # initialize all $meta attributes which might be relevant for
               # file2table
               return $self->SUPER::bootstrap_table_meta($dbh, $meta, $table);
           }
           sub init_table_meta
           {
               my ( $self, $dbh, $meta, $table ) = @_;
               # called after $meta contains the results from file2table
               # initialize all missing $meta attributes
               $self->SUPER::init_table_meta( $dbh, $meta, $table );
           }
       In case "DBD::File::Table::open_file" doesn't open the files as the
       driver needs that, override it!
           sub open_file
           {
               my ( $self, $meta, $attrs, $flags ) = @_;
               # ensure that $meta->{f_dontopen} is set
               $self->SUPER::open_file( $meta, $attrs, $flags );
               # now do what ever needs to be done
           }
       Combined with the methods implemented using the SQL::Statement::Embed
       guide, the table is full working and you could try a start over.
   User comfort
       "DBD::File" since 0.39 consolidates all persistent meta data of a table
       into a single structure stored in "$dbh->{f_meta}". With "DBD::File"
       version 0.41 and "DBI::DBD::SqlEngine" version 0.05, this consolidation
       moves to DBI::DBD::SqlEngine. It's still the "$dbh->{$drv_prefix .
       "_meta"}" attribute which cares, so what you learned at this place
       before, is still valid.
           sub init_valid_attributes
           {
               my $dbh = $_[0];
               $dbh->SUPER::init_valid_attributes ();
               $dbh->{foo_valid_attrs} = { ... };
               $dbh->{foo_readonly_attrs} = { ...  };
               $dbh->{foo_meta} = "foo_tables";
               return $dbh;
           }
       See updates at "User comfort" in DBI::DBD::SqlEngine::HowTo.
   Testing
       Now you should have your own DBD::File based driver. 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. DBD::File is written by Jochen
       Wiedmann and Jeff Zucker.
       The module DBD::File 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.26.3                      2013-04-04               DBD::File::HowTo(3)