GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  DBD::FILE::HOWTO (3)

.ds Aq ’

NAME

DBD::File::HowTo - Guide to create DBD::File based driver

CONTENTS

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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 DBD::FILE::HOWTO (3) 2013-04-04

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.