.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DBD::File::HowTo 3"
.TH DBD::File::HowTo 3 2024-09-13 "perl v5.40.0" "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
DBD::File::HowTo \- Guide to create DBD::File based driver
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 12
\&  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
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This document provides a step-by-step guide, how to create a new
\&\f(CW\*(C`DBD::File\*(C'\fR 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.
.PP
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.
.PP
Those who are still reading, should be able to sing the rules of
"CREATING A NEW DRIVER" in DBI::DBD.
.PP
Of course, DBD::File is a DBI::DBD::SqlEngine and you surely read
DBI::DBD::SqlEngine::HowTo before continuing here.
.SH "CREATING DRIVER CLASSES"
.IX Header "CREATING DRIVER CLASSES"
Do you have an entry in DBI's DBD 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 base qw(DBD::File);
\&
\&    use DBI ();
\&
\&    our $VERSION = "0.001";
\&
\&    package DBD::Foo::dr;
\&
\&    our @ISA = qw(DBD::File::dr);
\&    our $imp_data_size = 0;
\&
\&    package DBD::Foo::db;
\&
\&    our @ISA = qw(DBD::File::db);
\&    our $imp_data_size = 0;
\&
\&    package DBD::Foo::st;
\&
\&    our @ISA = qw(DBD::File::st);
\&    our $imp_data_size = 0;
\&
\&    package DBD::Foo::Statement;
\&
\&    our @ISA = qw(DBD::File::Statement);
\&
\&    package DBD::Foo::Table;
\&
\&    our @ISA = qw(DBD::File::Table);
\&
\&    1;
.Ve
.PP
Tiny, eh? And all you have now is a DBD named foo which will be able to
deal with temporary tables, as long as you use SQL::Statement. In
DBI::SQL::Nano environments, this DBD can do nothing.
.SS "Start over"
.IX Subsection "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?
.PP
DBD::File extends DBI::DBD::SqlEngine to deal with any kind of files.
In principle, the only extensions required are to the table class:
.PP
.Vb 1
\&    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 );
\&    }
.Ve
.PP
In case \f(CW\*(C`DBD::File::Table::open_file\*(C'\fR doesn't open the files as the driver
needs that, override it!
.PP
.Vb 7
\&    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
\&    }
.Ve
.PP
Combined with the methods implemented using the SQL::Statement::Embed
guide, the table is full working and you could try a start over.
.SS "User comfort"
.IX Subsection "User comfort"
\&\f(CW\*(C`DBD::File\*(C'\fR since \f(CW0.39\fR consolidates all persistent meta data of a table
into a single structure stored in \f(CW\*(C`$dbh\->{f_meta}\*(C'\fR. With \f(CW\*(C`DBD::File\*(C'\fR
version \f(CW0.41\fR and \f(CW\*(C`DBI::DBD::SqlEngine\*(C'\fR version \f(CW0.05\fR, this
consolidation moves to DBI::DBD::SqlEngine. It's still the
\&\f(CW\*(C`$dbh\->{$drv_prefix . "_meta"}\*(C'\fR attribute which cares, so what you
learned at this place before, is still valid.
.PP
.Vb 3
\&    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;
\&    }
.Ve
.PP
See updates at "User comfort" in DBI::DBD::SqlEngine::HowTo.
.SS Testing
.IX Subsection "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.
.SH AUTHOR
.IX Header "AUTHOR"
This guide is written by Jens Rehsack. DBD::File is written by Jochen
Wiedmann and Jeff Zucker.
.PP
The module DBD::File 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 GNU General Public License (GPL) or the Artistic License, as
specified in the Perl README file.