22

✏️ Editing: DBD::File::Developers.3pm

.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    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::Developers 3"
.TH DBD::File::Developers 3 "2013-04-04" "perl v5.26.3" "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::Developers \- Developers documentation for DBD::File
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    package DBD::myDriver;
\&
\&    use base qw( DBD::File );
\&
\&    sub driver
\&    {
\&        ...
\&        my $drh = $proto\->SUPER::driver ($attr);
\&        ...
\&        return $drh\->{class};
\&        }
\&
\&    sub CLONE { ... }
\&
\&    package DBD::myDriver::dr;
\&
\&    @ISA = qw( DBD::File::dr );
\&
\&    sub data_sources { ... }
\&    ...
\&
\&    package DBD::myDriver::db;
\&
\&    @ISA = qw( DBD::File::db );
\&
\&    sub init_valid_attributes { ... }
\&    sub init_default_attributes { ... }
\&    sub set_versions { ... }
\&    sub validate_STORE_attr { my ($dbh, $attrib, $value) = @_; ... }
\&    sub validate_FETCH_attr { my ($dbh, $attrib) = @_; ... }
\&    sub get_myd_versions { ... }
\&
\&    package DBD::myDriver::st;
\&
\&    @ISA = qw( DBD::File::st );
\&
\&    sub FETCH { ... }
\&    sub STORE { ... }
\&
\&    package DBD::myDriver::Statement;
\&
\&    @ISA = qw( DBD::File::Statement );
\&
\&    package DBD::myDriver::Table;
\&
\&    @ISA = qw( DBD::File::Table );
\&
\&    my %reset_on_modify = (
\&        myd_abc => "myd_foo",
\&        myd_mno => "myd_bar",
\&        );
\&    _\|_PACKAGE_\|_\->register_reset_on_modify (\e%reset_on_modify);
\&    my %compat_map = (
\&        abc => \*(Aqfoo_abc\*(Aq,
\&        xyz => \*(Aqfoo_xyz\*(Aq,
\&        );
\&    _\|_PACKAGE_\|_\->register_compat_map (\e%compat_map);
\&
\&    sub bootstrap_table_meta { ... }
\&    sub init_table_meta { ... }
\&    sub table_meta_attr_changed { ... }
\&    sub open_data { ... }
\&
\&    sub fetch_row { ... }
\&    sub push_row { ... }
\&    sub push_names { ... }
\&
\&    # optimize the SQL engine by add one or more of
\&    sub update_current_row { ... }
\&    # or
\&    sub update_specific_row { ... }
\&    # or
\&    sub update_one_row { ... }
\&    # or
\&    sub insert_new_row { ... }
\&    # or
\&    sub delete_current_row { ... }
\&    # or
\&    sub delete_one_row { ... }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This document describes how \s-1DBD\s0 developers can write DBD::File based \s-1DBI\s0
drivers. It supplements \s-1DBI::DBD\s0 and DBI::DBD::SqlEngine::Developers,
which you should read first.
.SH "CLASSES"
.IX Header "CLASSES"
Each \s-1DBI\s0 driver must provide a package global \f(CW\*(C`driver\*(C'\fR method and three
\&\s-1DBI\s0 related classes:
.IP "DBD::File::dr" 4
.IX Item "DBD::File::dr"
Driver package, contains the methods \s-1DBI\s0 calls indirectly via \s-1DBI\s0
interface:
.Sp
.Vb 1
\&  DBI\->connect (\*(AqDBI:DBM:\*(Aq, undef, undef, {})
\&
\&  # invokes
\&  package DBD::DBM::dr;
\&  @DBD::DBM::dr::ISA = qw( DBD::File::dr );
\&
\&  sub connect ($$;$$$)
\&  {
\&      ...
\&      }
.Ve
.Sp
Similar for \f(CW\*(C`data_sources\*(C'\fR and \f(CW\*(C`disconnect_all\*(C'\fR.
.Sp
Pure Perl \s-1DBI\s0 drivers derived from DBD::File do not usually need to
override any of the methods provided through the DBD::XXX::dr package
however if you need additional initialization in the connect method
you may need to.
.IP "DBD::File::db" 4
.IX Item "DBD::File::db"
Contains the methods which are called through \s-1DBI\s0 database handles
(\f(CW$dbh\fR). e.g.,
.Sp
.Vb 3
\&  $sth = $dbh\->prepare ("select * from foo");
\&  # returns the f_encoding setting for table foo
\&  $dbh\->csv_get_meta ("foo", "f_encoding");
.Ve
.Sp
DBD::File provides the typical methods required here. Developers who
write \s-1DBI\s0 drivers based on DBD::File need to override the methods \f(CW\*(C`set_versions\*(C'\fR and \f(CW\*(C`init_valid_attributes\*(C'\fR.
.IP "DBD::File::st" 4
.IX Item "DBD::File::st"
Contains the methods to deal with prepared statement handles. e.g.,
.Sp
.Vb 1
\&  $sth\->execute () or die $sth\->errstr;
.Ve
.SS "DBD::File"
.IX Subsection "DBD::File"
This is the main package containing the routines to initialize
DBD::File based \s-1DBI\s0 drivers. Primarily the \f(CW\*(C`DBD::File::driver\*(C'\fR
method is invoked, either directly from \s-1DBI\s0 when the driver is
initialized or from the derived class.
.PP
.Vb 1
\&  package DBD::DBM;
\&
\&  use base qw( DBD::File );
\&
\&  sub driver
\&  {
\&      my ($class, $attr) = @_;
\&      ...
\&      my $drh = $class\->SUPER::driver ($attr);
\&      ...
\&      return $drh;
\&      }
.Ve
.PP
It is not necessary to implement your own driver method as long as
additional initialization (e.g. installing more private driver
methods) is not required.  You do not need to call \f(CW\*(C`setup_driver\*(C'\fR
as DBD::File takes care of it.
.SS "DBD::File::dr"
.IX Subsection "DBD::File::dr"
The driver package contains the methods \s-1DBI\s0 calls indirectly via the \s-1DBI\s0
interface (see \*(L"\s-1DBI\s0 Class Methods\*(R" in \s-1DBI\s0).
.PP
DBD::File based \s-1DBI\s0 drivers usually do not need to implement anything here,
it is enough to do the basic initialization:
.PP
.Vb 1
\&  package DBD:XXX::dr;
\&
\&  @DBD::XXX::dr::ISA = qw (DBD::File::dr);
\&  $DBD::XXX::dr::imp_data_size     = 0;
\&  $DBD::XXX::dr::data_sources_attr = undef;
\&  $DBD::XXX::ATTRIBUTION = "DBD::XXX $DBD::XXX::VERSION by Hans Mustermann";
.Ve
.SS "DBD::File::db"
.IX Subsection "DBD::File::db"
This package defines the database methods, which are called via the \s-1DBI\s0
database handle \f(CW$dbh\fR.
.PP
Methods provided by DBD::File:
.IP "ping" 4
.IX Item "ping"
Simply returns the content of the \f(CW\*(C`Active\*(C'\fR attribute. Override
when your driver needs more complicated actions here.
.IP "prepare" 4
.IX Item "prepare"
Prepares a new \s-1SQL\s0 statement to execute. Returns a statement handle,
\&\f(CW$sth\fR \- instance of the DBD:XXX::st. It is neither required nor
recommended to override this method.
.IP "\s-1FETCH\s0" 4
.IX Item "FETCH"
Fetches an attribute of a \s-1DBI\s0 database object. Private handle attributes
must have a prefix (this is mandatory). If a requested attribute is
detected as a private attribute without a valid prefix, the driver prefix
(written as \f(CW$drv_prefix\fR) is added.
.Sp
The driver prefix is extracted from the attribute name and verified against
\&\f(CW\*(C`$dbh\->{$drv_prefix . "valid_attrs"}\*(C'\fR (when it exists). If the
requested attribute value is not listed as a valid attribute, this method
croaks. If the attribute is valid and readonly (listed in \f(CW\*(C`$dbh\->{
$drv_prefix . "readonly_attrs" }\*(C'\fR when it exists), a real copy of the
attribute value is returned. So it's not possible to modify
\&\f(CW\*(C`f_valid_attrs\*(C'\fR from outside of DBD::File::db or a derived class.
.IP "\s-1STORE\s0" 4
.IX Item "STORE"
Stores a database private attribute. Private handle attributes must have a
prefix (this is mandatory). If a requested attribute is detected as a private
attribute without a valid prefix, the driver prefix (written as
\&\f(CW$drv_prefix\fR) is added. If the database handle has an attribute
\&\f(CW\*(C`${drv_prefix}_valid_attrs\*(C'\fR \- for attribute names which are not listed in
that hash, this method croaks. If the database handle has an attribute
\&\f(CW\*(C`${drv_prefix}_readonly_attrs\*(C'\fR, only attributes which are not listed there
can be stored (once they are initialized). Trying to overwrite such an
immutable attribute forces this method to croak.
.Sp
An example of a valid attributes list can be found in
\&\f(CW\*(C`DBD::File::db::init_valid_attributes\*(C'\fR.
.IP "set_versions" 4
.IX Item "set_versions"
This method sets the attribute \f(CW\*(C`f_version\*(C'\fR with the version of DBD::File.
.Sp
This method is called at the begin of the \f(CW\*(C`connect ()\*(C'\fR phase.
.Sp
When overriding this method, do not forget to invoke the superior one.
.IP "init_valid_attributes" 4
.IX Item "init_valid_attributes"
This method is called after the database handle is instantiated as the
first attribute initialization.
.Sp
\&\f(CW\*(C`DBD::File::db::init_valid_attributes\*(C'\fR initializes the attributes
\&\f(CW\*(C`f_valid_attrs\*(C'\fR and \f(CW\*(C`f_readonly_attrs\*(C'\fR.
.Sp
When overriding this method, do not forget to invoke the superior one,
preferably before doing anything else. Compatibility table attribute
access must be initialized here to allow DBD::File to instantiate the
map tie:
.Sp
.Vb 6
\&    # for DBD::CSV
\&    $dbh\->{csv_meta} = "csv_tables";
\&    # for DBD::DBM
\&    $dbh\->{dbm_meta} = "dbm_tables";
\&    # for DBD::AnyData
\&    $dbh\->{ad_meta}  = "ad_tables";
.Ve
.IP "init_default_attributes" 4
.IX Item "init_default_attributes"
This method is called after the database handle is instantiated to
initialize the default attributes.
.Sp
\&\f(CW\*(C`DBD::File::db::init_default_attributes\*(C'\fR initializes the attributes
\&\f(CW\*(C`f_dir\*(C'\fR, \f(CW\*(C`f_meta\*(C'\fR, \f(CW\*(C`f_meta_map\*(C'\fR, \f(CW\*(C`f_version\*(C'\fR.
.Sp
When the derived implementor class provides the attribute to validate
attributes (e.g. \f(CW\*(C`$dbh\->{dbm_valid_attrs} = {...};\*(C'\fR) or the attribute
containing the immutable attributes (e.g.
\&\f(CW\*(C`$dbh\->{dbm_readonly_attrs} = {...};\*(C'\fR), the attributes
\&\f(CW\*(C`drv_valid_attrs\*(C'\fR, \f(CW\*(C`drv_readonly_attrs\*(C'\fR, \f(CW\*(C`drv_version\*(C'\fR and \f(CW\*(C`drv_meta\*(C'\fR
are added (when available) to the list of valid and immutable attributes
(where \f(CW\*(C`drv_\*(C'\fR is interpreted as the driver prefix).
.Sp
If \f(CW\*(C`drv_meta\*(C'\fR is set, an attribute with the name in \f(CW\*(C`drv_meta\*(C'\fR is
initialized providing restricted read/write access to the meta data of the
tables using \f(CW\*(C`DBD::File::TieTables\*(C'\fR in the first (table) level and
\&\f(CW\*(C`DBD::File::TieMeta\*(C'\fR for the meta attribute level. \f(CW\*(C`DBD::File::TieTables\*(C'\fR
uses \f(CW\*(C`DBD::DRV::Table::get_table_meta\*(C'\fR to initialize the second level
tied hash on \s-1FETCH/STORE.\s0 The \f(CW\*(C`DBD::File::TieMeta\*(C'\fR class uses
\&\f(CW\*(C`DBD::DRV::Table::get_table_meta_attr\*(C'\fR to \s-1FETCH\s0 attribute values and
\&\f(CW\*(C`DBD::DRV::Table::set_table_meta_attr\*(C'\fR to \s-1STORE\s0 attribute values. This
allows it to map meta attributes for compatibility reasons.
.IP "get_single_table_meta" 4
.IX Item "get_single_table_meta"
.PD 0
.IP "get_file_meta" 4
.IX Item "get_file_meta"
.PD
Retrieve an attribute from a table's meta information. The method
signature is \f(CW\*(C`get_file_meta ($dbh, $table, $attr)\*(C'\fR. This method
is called by the injected db handle method \f(CW\*(C`${drv_prefix}get_meta\*(C'\fR.
.Sp
While get_file_meta allows \f(CW$table\fR or \f(CW$attr\fR to be a list of tables or
attributes to retrieve, get_single_table_meta allows only one table name
and only one attribute name. A table name of \f(CW\*(Aq.\*(Aq\fR (single dot) is
interpreted as the default table and this will retrieve the appropriate
attribute globally from the dbh. This has the same restrictions as
\&\f(CW\*(C`$dbh\->{$attrib}\*(C'\fR.
.Sp
get_file_meta allows \f(CW\*(Aq+\*(Aq\fR and \f(CW\*(Aq*\*(Aq\fR as wildcards for table names and
\&\f(CW$table\fR being a regular expression matching against the table names
(evaluated without the default table). The table name \f(CW\*(Aq*\*(Aq\fR is
\&\fIall currently known tables, including the default one\fR. The table
name \f(CW\*(Aq+\*(Aq\fR is \fIall table names which conform to
\&\s-1ANSI\s0 file name restrictions\fR (/^[_A\-Za\-z0\-9]+$/).
.Sp
The table meta information is retrieved using the get_table_meta and
get_table_meta_attr methods of the table class of the implementation.
.IP "set_single_table_meta" 4
.IX Item "set_single_table_meta"
.PD 0
.IP "set_file_meta" 4
.IX Item "set_file_meta"
.PD
Sets an attribute in a table's meta information. The method signature is
\&\f(CW\*(C`set_file_meta ($dbh, $table, $attr, $value)\*(C'\fR. This method is called
by the injected db handle method \f(CW\*(C`${drv_prefix}set_meta\*(C'\fR.
.Sp
While set_file_meta allows \f(CW$table\fR to be a list of tables and \f(CW$attr\fR
to be a hash of several attributes to set, set_single_table_meta allows
only one table name and only one attribute name/value pair.
.Sp
The wildcard characters for the table name are the same as for
get_file_meta.
.Sp
The table meta information is updated using the get_table_meta and
set_table_meta_attr methods of the table class of the implementation.
.IP "clear_file_meta" 4
.IX Item "clear_file_meta"
Clears all meta information cached about a table. The method signature is
\&\f(CW\*(C`clear_file_meta ($dbh, $table)\*(C'\fR. This method is called
by the injected db handle method \f(CW\*(C`${drv_prefix}clear_meta\*(C'\fR.
.SS "DBD::File::st"
.IX Subsection "DBD::File::st"
Contains the methods to deal with prepared statement handles:
.IP "\s-1FETCH\s0" 4
.IX Item "FETCH"
Fetches statement handle attributes. Supported attributes (for full overview
see \*(L"Statement Handle Attributes\*(R" in \s-1DBI\s0) are \f(CW\*(C`NAME\*(C'\fR, \f(CW\*(C`TYPE\*(C'\fR, \f(CW\*(C`PRECISION\*(C'\fR
and \f(CW\*(C`NULLABLE\*(C'\fR in case that SQL::Statement is used as \s-1SQL\s0 execution engine
and a statement is successful prepared.  When SQL::Statement has additional
information about a table, those information are returned. Otherwise, the
same defaults as in DBI::DBD::SqlEngine are used.
.Sp
This method usually requires extending in a derived implementation.
See \s-1DBD::CSV\s0 or \s-1DBD::DBM\s0 for some example.
.SS "DBD::File::TableSource::FileSystem"
.IX Subsection "DBD::File::TableSource::FileSystem"
Provides data sources and table information on database driver and database
handle level.
.PP
.Vb 1
\&  package DBD::File::TableSource::FileSystem;
\&
\&  sub data_sources ($;$)
\&  {
\&      my ($class, $drh, $attrs) = @_;
\&      ...
\&      }
\&
\&  sub avail_tables
\&  {
\&      my ($class, $drh) = @_;
\&      ...
\&      }
.Ve
.PP
The \f(CW\*(C`data_sources\*(C'\fR method is called when the user invokes any of the
following:
.PP
.Vb 2
\&  @ary = DBI\->data_sources ($driver);
\&  @ary = DBI\->data_sources ($driver, \e%attr);
\&  
\&  @ary = $dbh\->data_sources ();
\&  @ary = $dbh\->data_sources (\e%attr);
.Ve
.PP
The \f(CW\*(C`avail_tables\*(C'\fR method is called when the user invokes any of the
following:
.PP
.Vb 1
\&  @names = $dbh\->tables ($catalog, $schema, $table, $type);
\&  
\&  $sth   = $dbh\->table_info ($catalog, $schema, $table, $type);
\&  $sth   = $dbh\->table_info ($catalog, $schema, $table, $type, \e%attr);
\&
\&  $dbh\->func ("list_tables");
.Ve
.PP
Every time where an \f(CW\*(C`\e%attr\*(C'\fR argument can be specified, this \f(CW\*(C`\e%attr\*(C'\fR
object's \f(CW\*(C`sql_table_source\*(C'\fR attribute is preferred over the \f(CW$dbh\fR
attribute or the driver default.
.SS "DBD::File::DataSource::Stream"
.IX Subsection "DBD::File::DataSource::Stream"
.Vb 1
\&  package DBD::File::DataSource::Stream;
\&
\&  @DBD::File::DataSource::Stream::ISA = \*(AqDBI::DBD::SqlEngine::DataSource\*(Aq;
\&
\&  sub complete_table_name
\&  {
\&      my ($self, $meta, $file, $respect_case) = @_;
\&      ...
\&      }
.Ve
.PP
Clears all meta attributes identifying a file: \f(CW\*(C`f_fqfn\*(C'\fR, \f(CW\*(C`f_fqbn\*(C'\fR and
\&\f(CW\*(C`f_fqln\*(C'\fR. The table name is set according to \f(CW$respect_case\fR and
\&\f(CW\*(C`$meta\->{sql_identifier_case}\*(C'\fR (\s-1SQL_IC_LOWER, SQL_IC_UPPER\s0).
.PP
.Vb 1
\&  package DBD::File::DataSource::Stream;
\&
\&  sub apply_encoding
\&  {
\&      my ($self, $meta, $fn) = @_;
\&      ...
\&      }
.Ve
.PP
Applies the encoding from \fImeta information\fR (\f(CW\*(C`$meta\->{f_encoding}\*(C'\fR)
to the file handled opened in \f(CW\*(C`open_data\*(C'\fR.
.PP
.Vb 1
\&  package DBD::File::DataSource::Stream;
\&
\&  sub open_data
\&  {
\&      my ($self, $meta, $attrs, $flags) = @_;
\&      ...
\&      }
.Ve
.PP
Opens (\f(CW\*(C`dup (2)\*(C'\fR) the file handle provided in \f(CW\*(C`$meta\->{f_file}\*(C'\fR.
.PP
.Vb 1
\&  package DBD::File::DataSource::Stream;
\&
\&  sub can_flock { ... }
.Ve
.PP
Returns whether \f(CW\*(C`flock (2)\*(C'\fR is available or not (avoids retesting in
subclasses).
.SS "DBD::File::DataSource::File"
.IX Subsection "DBD::File::DataSource::File"
.Vb 1
\&  package DBD::File::DataSource::File;
\&
\&  sub complete_table_name ($$;$)
\&  {
\&      my ($self, $meta, $table, $respect_case) = @_;
\&      ...
\&      }
.Ve
.PP
The method \f(CW\*(C`complete_table_name\*(C'\fR tries to map a filename to the associated
table name.  It is called with a partially filled meta structure for the
resulting table containing at least the following attributes:
\&\f(CW\*(C`f_ext\*(C'\fR, \f(CW\*(C`f_dir\*(C'\fR, \f(CW\*(C`f_lockfile\*(C'\fR and \f(CW\*(C`sql_identifier_case\*(C'\fR.
.PP
If a file/table map can be found then this method sets the \f(CW\*(C`f_fqfn\*(C'\fR, \f(CW\*(C`f_fqbn\*(C'\fR, \f(CW\*(C`f_fqln\*(C'\fR and \f(CW\*(C`table_name\*(C'\fR attributes in
the meta structure. If a map cannot be found the table name will be
undef.
.PP
.Vb 1
\&  package DBD::File::DataSource::File;
\&
\&  sub open_data ($)
\&  {
\&      my ($self, $meta, $attrs, $flags) = @_;
\&      ...
\&      }
.Ve
.PP
Depending on the attributes set in the table's meta data, the
following steps are performed. Unless \f(CW\*(C`f_dontopen\*(C'\fR is set to a
true value, \f(CW\*(C`f_fqfn\*(C'\fR must contain the full qualified file name
for the table to work on (file2table ensures this). The encoding in
\&\f(CW\*(C`f_encoding\*(C'\fR is applied if set and the file is opened. If
\&\f(CW\*(C`<f_fqln \*(C'\fR> (full qualified lock name) is set, this file is opened,
too. Depending on the value in \f(CW\*(C`f_lock\*(C'\fR, the appropriate lock is
set on the opened data file or lock file.
.SS "DBD::File::Statement"
.IX Subsection "DBD::File::Statement"
Derives from DBI::SQL::Nano::Statement to provide following method:
.IP "open_table" 4
.IX Item "open_table"
Implements the open_table method required by SQL::Statement and
DBI::SQL::Nano. All the work for opening the file(s) belonging to the
table is handled and parametrized in DBD::File::Table. Unless you intend
to add anything to the following implementation, an empty DBD::XXX::Statement
package satisfies DBD::File.
.Sp
.Vb 3
\&  sub open_table ($$$$$)
\&  {
\&      my ($self, $data, $table, $createMode, $lockMode) = @_;
\&
\&      my $class = ref $self;
\&      $class =~ s/::Statement/::Table/;
\&
\&      my $flags = {
\&          createMode => $createMode,
\&          lockMode   => $lockMode,
\&          };
\&      $self\->{command} eq "DROP" and $flags\->{dropMode} = 1;
\&
\&      return $class\->new ($data, { table => $table }, $flags);
\&      } # open_table
.Ve
.SS "DBD::File::Table"
.IX Subsection "DBD::File::Table"
Derives from DBI::SQL::Nano::Table and provides physical file access for
the table data which are stored in the files.
.IP "bootstrap_table_meta" 4
.IX Item "bootstrap_table_meta"
Initializes a table meta structure. Can be safely overridden in a
derived class, as long as the \f(CW\*(C`SUPER\*(C'\fR method is called at the end
of the overridden method.
.Sp
It copies the following attributes from the database into the table meta data
\&\f(CW\*(C`f_dir\*(C'\fR, \f(CW\*(C`f_ext\*(C'\fR, \f(CW\*(C`f_encoding\*(C'\fR, \f(CW\*(C`f_lock\*(C'\fR, \f(CW\*(C`f_schema\*(C'\fR
and \f(CW\*(C`f_lockfile\*(C'\fR and makes them sticky to the table.
.Sp
This method should be called before you attempt to map between file
name and table name to ensure the correct directory, extension etc. are
used.
.IP "init_table_meta" 4
.IX Item "init_table_meta"
Initializes more attributes of the table meta data \- usually more
expensive ones (e.g. those which require class instantiations) \- when
the file name and the table name could mapped.
.IP "get_table_meta" 4
.IX Item "get_table_meta"
Returns the table meta data. If there are none for the required
table, a new one is initialized. When it fails, nothing is
returned. On success, the name of the table and the meta data
structure is returned.
.IP "get_table_meta_attr" 4
.IX Item "get_table_meta_attr"
Returns a single attribute from the table meta data. If the attribute
name appears in \f(CW%compat_map\fR, the attribute name is updated from
there.
.IP "set_table_meta_attr" 4
.IX Item "set_table_meta_attr"
Sets a single attribute in the table meta data. If the attribute
name appears in \f(CW%compat_map\fR, the attribute name is updated from
there.
.IP "table_meta_attr_changed" 4
.IX Item "table_meta_attr_changed"
Called when an attribute of the meta data is modified.
.Sp
If the modified attribute requires to reset a calculated attribute, the
calculated attribute is reset (deleted from meta data structure) and
the \fIinitialized\fR flag is removed, too. The decision is made based on
\&\f(CW%register_reset_on_modify\fR.
.IP "register_reset_on_modify" 4
.IX Item "register_reset_on_modify"
Allows \f(CW\*(C`set_table_meta_attr\*(C'\fR to reset meta attributes when special
attributes are modified. For DBD::File, modifying one of \f(CW\*(C`f_file\*(C'\fR, \f(CW\*(C`f_dir\*(C'\fR,
\&\f(CW\*(C`f_ext\*(C'\fR or \f(CW\*(C`f_lockfile\*(C'\fR will reset \f(CW\*(C`f_fqfn\*(C'\fR. \s-1DBD::DBM\s0 extends the
list for \f(CW\*(C`dbm_type\*(C'\fR and \f(CW\*(C`dbm_mldbm\*(C'\fR to reset the value of \f(CW\*(C`dbm_tietype\*(C'\fR.
.Sp
If your \s-1DBD\s0 has calculated values in the meta data area, then call
\&\f(CW\*(C`register_reset_on_modify\*(C'\fR:
.Sp
.Vb 2
\&  my %reset_on_modify = (xxx_foo => "xxx_bar");
\&  _\|_PACKAGE_\|_\->register_reset_on_modify (\e%reset_on_modify);
.Ve
.IP "register_compat_map" 4
.IX Item "register_compat_map"
Allows \f(CW\*(C`get_table_meta_attr\*(C'\fR and \f(CW\*(C`set_table_meta_attr\*(C'\fR to update the
attribute name to the current favored one:
.Sp
.Vb 3
\&  # from DBD::DBM
\&  my %compat_map = (dbm_ext => "f_ext");
\&  _\|_PACKAGE_\|_\->register_compat_map (\e%compat_map);
.Ve
.IP "open_file" 4
.IX Item "open_file"
Called to open the table's data file.
.Sp
Depending on the attributes set in the table's meta data, the
following steps are performed. Unless \f(CW\*(C`f_dontopen\*(C'\fR is set to a
true value, \f(CW\*(C`f_fqfn\*(C'\fR must contain the full qualified file name
for the table to work on (file2table ensures this). The encoding in
\&\f(CW\*(C`f_encoding\*(C'\fR is applied if set and the file is opened. If
\&\f(CW\*(C`<f_fqln \*(C'\fR> (full qualified lock name) is set, this file is opened,
too. Depending on the value in \f(CW\*(C`f_lock\*(C'\fR, the appropriate lock is
set on the opened data file or lock file.
.Sp
After this is done, a derived class might add more steps in an overridden
\&\f(CW\*(C`open_file\*(C'\fR method.
.IP "new" 4
.IX Item "new"
Instantiates the table. This is done in 3 steps:
.Sp
.Vb 3
\& 1. get the table meta data
\& 2. open the data file
\& 3. bless the table data structure using inherited constructor new
.Ve
.Sp
It is not recommended to override the constructor of the table class.
Find a reasonable place to add you extensions in one of the above four
methods.
.IP "drop" 4
.IX Item "drop"
Implements the abstract table method for the \f(CW\*(C`DROP\*(C'\fR
command. Discards table meta data after all files belonging to the
table are closed and unlinked.
.Sp
Overriding this method might be reasonable in very rare cases.
.IP "seek" 4
.IX Item "seek"
Implements the abstract table method used when accessing the table from the
engine. \f(CW\*(C`seek\*(C'\fR is called every time the engine uses dumb algorithms
for iterating over the table content.
.IP "truncate" 4
.IX Item "truncate"
Implements the abstract table method used when dumb table algorithms
for \f(CW\*(C`UPDATE\*(C'\fR or \f(CW\*(C`DELETE\*(C'\fR need to truncate the table storage
after the last written row.
.PP
You should consult the documentation of \f(CW\*(C`SQL::Eval::Table\*(C'\fR (see
SQL::Eval) to get more information about the abstract methods of the
table's base class you have to override and a description of the table
meta information expected by the \s-1SQL\s0 engines.
.SH "AUTHOR"
.IX Header "AUTHOR"
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 >
.PP
The original author is Jochen Wiedmann.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2010\-2013 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.

MR SKB