.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DBI::DBD::SqlEngine::HowTo 3pm"
.TH DBI::DBD::SqlEngine::HowTo 3pm "2010-08-30" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBI::DBD::SqlEngine::HowTo \- Guide to create DBI::DBD::SqlEngine based driver
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 8
\&  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
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This document provides a step-by-step guide, how to create a new
\&\f(CW\*(C`DBI::DBD::SqlEngine\*(C'\fR based \s-1DBD\s0. It expects that you carefully read the
\&\s-1DBI\s0 documentation and that you're familiar with \s-1DBI::DBD\s0 and had
read and understood DBD::ExampleP.
.PP
This document addresses experienced developers who are really sure that
they need to invest time when writing a new \s-1DBI\s0 Driver. Writing a \s-1DBI\s0
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.
.PP
Those who are still reading, should be able to sing the rules of
\&\*(L"\s-1CREATING\s0 A \s-1NEW\s0 \s-1DRIVER\s0\*(R" in \s-1DBI::DBD\s0.
.SH "CREATING DRIVER CLASSES"
.IX Header "CREATING DRIVER CLASSES"
Do you have an entry in \s-1DBI\s0's \s-1DBD\s0 registry? For this guide, a prefix of
\&\f(CW\*(C`foo_\*(C'\fR is assumed.
.SS "Sample Skeleton"
.IX Subsection "Sample Skeleton"
.Vb 1
\&    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;
.Ve
.PP
Tiny, eh? And all you have now is a \s-1DBD\s0 named foo which will is able to
deal with temporary tables, as long as you use SQL::Statement. In
DBI::SQL::Nano environments, this \s-1DBD\s0 can do nothing.
.SS "Deal with own attributes"
.IX Subsection "Deal with own attributes"
Before we start doing usable stuff with our \s-1DBI\s0 driver, we need to think
about what we want to do and how we want to do it.
.PP
Do we need tunable knobs accessible by users? Do we need status
information? All this is handled in attributes of the database handles (be
careful when your \s-1DBD\s0 is running \*(L"behind\*(R" a DBD::Gofer proxy).
.PP
How come the attributes into the \s-1DBD\s0 and how are they fetchable by the
user? Good question, but you should know because you've read the \s-1DBI\s0
documentation.
.PP
\&\f(CW\*(C`DBI::DBD::SqlEngine::db::FETCH\*(C'\fR and \f(CW\*(C`DBI::DBD::SqlEngine::db::STORE\*(C'\fR
taking care for you \- all they need to know is which attribute names
are valid and mutable or immutable. Tell them by adding
\&\f(CW\*(C`init_valid_attributes\*(C'\fR to your db class:
.PP
.Vb 3
\&    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;
\&    }
.Ve
.PP
Woooho \- but now the user cannot assign new managers? This is intended,
overwrite \f(CW\*(C`STORE\*(C'\fR to handle it!
.PP
.Vb 3
\&    sub STORE ($$$)
\&    {
\&        my ( $dbh, $attrib, $value ) = @_;
\&
\&        $dbh\->SUPER::STORE( $attrib, $value );
\&
\&        # we\*(Aqre 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
\&        }
\&    }
.Ve
.PP
But ... my driver runs without a manager until someone first assignes
a \f(CW\*(C`foo_manager_type\*(C'\fR. Well, no \- there're two places where you can
initialize defaults:
.PP
.Vb 3
\&    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;
\&    }
.Ve
.PP
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 important
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.
.SS "Dealing with Tables"
.IX Subsection "Dealing with Tables"
Let's put some life into it \- it's going to be time for it.
.PP
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 \s-1DBD\s0's works pretty
fine with SQL::Statement and DBI::SQL::Nano.
.SS "Testing"
.IX Subsection "Testing"
Now you should have your first own \s-1DBD\s0. Was easy, wasn't it?  But does
it work well? Prove it by writing tests and remember to use
dbd_edit_mm_attribs from \s-1DBI::DBD\s0 to ensure testing even rare cases.
.SH "AUTHOR"
.IX Header "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.
.PP
The module DBI::DBD::SqlEngine is currently maintained by
.PP
H.Merijn Brand < h.m.brand at xs4all.nl > and
Jens Rehsack  < rehsack at googlemail.com >
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2010 by H.Merijn Brand & Jens Rehsack
.PP
All rights reserved.
.PP
You may freely distribute and/or modify this module under the terms of
either the \s-1GNU\s0 General Public License (\s-1GPL\s0) or the Artistic License, as
specified in the Perl \s-1README\s0 file.