.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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 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.
.\"
.\" 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 "DBI::DBD::SqlEngine::Developers 3"
.TH DBI::DBD::SqlEngine::Developers 3 "2016-04-21" "perl v5.16.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"
DBI::DBD::SqlEngine::Developers \- Developers documentation for DBI::DBD::SqlEngine
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    package DBD::myDriver;
\&
\&    use base qw(DBI::DBD::SqlEngine);
\&
\&    sub driver
\&    {
\&        ...
\&        my $drh = $proto\->SUPER::driver($attr);
\&        ...
\&        return $drh\->{class};
\&    }
\&
\&    sub CLONE { ... }
\&
\&    package DBD::myDriver::dr;
\&
\&    @ISA = qw(DBI::DBD::SqlEngine::dr);
\&
\&    sub data_sources { ... }
\&    ...
\&
\&    package DBD::myDriver::db;
\&
\&    @ISA = qw(DBI::DBD::SqlEngine::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 { ... }
\&    sub get_avail_tables { ... }
\&
\&    package DBD::myDriver::st;
\&
\&    @ISA = qw(DBI::DBD::SqlEngine::st);
\&
\&    sub FETCH { ... }
\&    sub STORE { ... }
\&
\&    package DBD::myDriver::Statement;
\&
\&    @ISA = qw(DBI::DBD::SqlEngine::Statement);
\&
\&    sub open_table { ... }
\&
\&    package DBD::myDriver::Table;
\&
\&    @ISA = qw(DBI::DBD::SqlEngine::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 new { ... }
\&
\&    sub fetch_row { ... }
\&    sub push_row { ... }
\&    sub push_names { ... }
\&    sub seek { ... }
\&    sub truncate { ... }
\&    sub drop { ... }
\&
\&    # 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 the interface of DBI::DBD::SqlEngine for \s-1DBD\s0
developers who write DBI::DBD::SqlEngine based \s-1DBI\s0 drivers. It supplements
\&\s-1DBI::DBD\s0 and DBI::DBD::SqlEngine::HowTo, 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 "DBI::DBD::SqlEngine::dr" 4
.IX Item "DBI::DBD::SqlEngine::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(DBI::DBD::SqlEngine::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 DBI::DBD::SqlEngine usually don't need to
override any of the methods provided through the DBD::XXX::dr package.
However if you need additional initialization not fitting in
\&\f(CW\*(C`init_valid_attributes()\*(C'\fR and \f(CW\*(C`init_default_attributes()\*(C'\fR of you're ::db
class, the connect method might be the final place to be modified.
.IP "DBI::DBD::SqlEngine::db" 4
.IX Item "DBI::DBD::SqlEngine::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
DBI::DBD::SqlEngine provides the typical methods required here. Developers who
write \s-1DBI\s0 drivers based on DBI::DBD::SqlEngine need to override the methods
\&\f(CW\*(C`set_versions\*(C'\fR and \f(CW\*(C`init_valid_attributes\*(C'\fR.
.IP "DBI::DBD::SqlEngine::TieMeta;" 4
.IX Item "DBI::DBD::SqlEngine::TieMeta;"
Provides the tie-magic for \f(CW\*(C`$dbh\->{$drv_pfx . "_meta"}\*(C'\fR. Routes
\&\f(CW\*(C`STORE\*(C'\fR through \f(CW\*(C`$drv\->set_sql_engine_meta()\*(C'\fR and \f(CW\*(C`FETCH\*(C'\fR through
\&\f(CW\*(C`$drv\->get_sql_engine_meta()\*(C'\fR. \f(CW\*(C`DELETE\*(C'\fR is not supported, you have
to execute a \f(CW\*(C`DROP TABLE\*(C'\fR statement, where applicable.
.IP "DBI::DBD::SqlEngine::TieTables;" 4
.IX Item "DBI::DBD::SqlEngine::TieTables;"
Provides the tie-magic for tables in \f(CW\*(C`$dbh\->{$drv_pfx . "_meta"}\*(C'\fR.
Routes \f(CW\*(C`STORE\*(C'\fR though \f(CW\*(C`$tblClass\->set_table_meta_attr()\*(C'\fR and \f(CW\*(C`FETCH\*(C'\fR
though \f(CW\*(C`$tblClass\->get_table_meta_attr()\*(C'\fR. \f(CW\*(C`DELETE\*(C'\fR removes an
attribute from the \fImeta object\fR retrieved by
\&\f(CW\*(C`$tblClass\->get_table_meta()\*(C'\fR.
.IP "DBI::DBD::SqlEngine::st" 4
.IX Item "DBI::DBD::SqlEngine::st"
Contains the methods to deal with prepared statement handles. e.g.,
.Sp
.Vb 1
\&  $sth\->execute () or die $sth\->errstr;
.Ve
.IP "DBI::DBD::SqlEngine::TableSource;" 4
.IX Item "DBI::DBD::SqlEngine::TableSource;"
Base class for 3rd party table sources:
.Sp
.Vb 1
\&  $dbh\->{sql_table_source} = "DBD::Foo::TableSource";
.Ve
.IP "DBI::DBD::SqlEngine::DataSource;" 4
.IX Item "DBI::DBD::SqlEngine::DataSource;"
Base class for 3rd party data sources:
.Sp
.Vb 1
\&  $dbh\->{sql_data_source} = "DBD::Foo::DataSource";
.Ve
.IP "DBI::DBD::SqlEngine::Statement;" 4
.IX Item "DBI::DBD::SqlEngine::Statement;"
Base class for derived drivers statement engine. Implements \f(CW\*(C`open_table\*(C'\fR.
.IP "DBI::DBD::SqlEngine::Table;" 4
.IX Item "DBI::DBD::SqlEngine::Table;"
Contains tailoring between \s-1SQL\s0 engine's requirements and
\&\f(CW\*(C`DBI::DBD::SqlEngine\*(C'\fR magic for finding the right tables and storage.
Builds bridges between \f(CW\*(C`sql_meta\*(C'\fR handling of \f(CW\*(C`DBI::DBD::SqlEngine::db\*(C'\fR,
table initialization for \s-1SQL\s0 engines and \fImeta object\fR's attribute
management for derived drivers.
.SS "DBI::DBD::SqlEngine"
.IX Subsection "DBI::DBD::SqlEngine"
This is the main package containing the routines to initialize
DBI::DBD::SqlEngine based \s-1DBI\s0 drivers. Primarily the
\&\f(CW\*(C`DBI::DBD::SqlEngine::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( DBI::DBD::SqlEngine );
\&
\&  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 DBI::DBD::SqlEngine takes care of it.
.SS "DBI::DBD::SqlEngine::dr"
.IX Subsection "DBI::DBD::SqlEngine::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
DBI::DBD::SqlEngine 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 (DBI::DBD::SqlEngine::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
.PP
\fIMethods provided by \f(CI\*(C`DBI::DBD::SqlEngine::dr\*(C'\fI:\fR
.IX Subsection "Methods provided by DBI::DBD::SqlEngine::dr:"
.IP "connect" 4
.IX Item "connect"
Supervises the driver bootstrap when calling
.Sp
.Vb 1
\&  DBI\->connect( "dbi:Foo", , , { ... } );
.Ve
.Sp
First it instantiates a new driver using \f(CW\*(C`DBI::_new_dbh\*(C'\fR. After that,
initial bootstrap of the newly instantiated driver is done by
.Sp
.Vb 1
\&  $dbh\->func( 0, "init_default_attributes" );
.Ve
.Sp
The first argument (\f(CW0\fR) signals that this is the very first call to
\&\f(CW\*(C`init_default_attributes\*(C'\fR. Modern drivers understand that and do early
stage setup here after calling
.Sp
.Vb 2
\&  package DBD::Foo::db;
\&  our @DBD::Foo::db::ISA = qw(DBI::DBD::SqlEngine::db);
\&  
\&  sub init_default_attributes
\&  {
\&    my ($dbh, $phase) = @_;
\&    $dbh\->SUPER::init_default_attributes($phase);
\&    ...; # own setup code, maybe separated by phases
\&  }
.Ve
.Sp
When the \f(CW$phase\fR argument is passed down until
\&\f(CW\*(C`DBI::DBD::SqlEngine::db::init_default_attributes\*(C'\fR, \f(CW\*(C`connect()\*(C'\fR recognizes
a \fImodern\fR driver and initializes the attributes from \fI\s-1DSN\s0\fR and \fI\f(CI$attr\fI\fR
arguments passed via \f(CW\*(C`DBI\->connect( $dsn, $user, $pass, \e%attr )\*(C'\fR.
.Sp
At the end of the attribute initialization after \fIphase 0\fR, \f(CW\*(C`connect()\*(C'\fR
invoked \f(CW\*(C`init_default_attributes\*(C'\fR again for \fIphase 1\fR:
.Sp
.Vb 1
\&  $dbh\->func( 1, "init_default_attributes" );
.Ve
.IP "data_sources" 4
.IX Item "data_sources"
Returns a list of \fI\s-1DSN\s0\fR's using the \f(CW\*(C`data_sources\*(C'\fR method of the
class specified in \f(CW\*(C`$dbh\->{sql_table_source}\*(C'\fR or via \f(CW\*(C`\e%attr\*(C'\fR:
.Sp
.Vb 2
\&  @ary = DBI\->data_sources($driver);
\&  @ary = DBI\->data_sources($driver, \e%attr);
.Ve
.IP "disconnect_all" 4
.IX Item "disconnect_all"
\&\f(CW\*(C`DBI::DBD::SqlEngine\*(C'\fR doesn't have an overall driver cache, so nothing
happens here at all.
.SS "DBI::DBD::SqlEngine::db"
.IX Subsection "DBI::DBD::SqlEngine::db"
This package defines the database methods, which are called via the \s-1DBI\s0
database handle \f(CW$dbh\fR.
.PP
\fIMethods provided by \f(CI\*(C`DBI::DBD::SqlEngine::db\*(C'\fI:\fR
.IX Subsection "Methods provided by DBI::DBD::SqlEngine::db:"
.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 "validate_FETCH_attr" 4
.IX Item "validate_FETCH_attr"
Called by \f(CW\*(C`FETCH\*(C'\fR to allow inherited drivers do their own attribute
name validation. Calling convention is similar to \f(CW\*(C`FETCH\*(C'\fR and the
return value is the approved attribute name.
.Sp
.Vb 1
\&    return $validated_attribute_name;
.Ve
.Sp
In case of validation fails (e.g. accessing private attribute or similar),
\&\f(CW\*(C`validate_FETCH_attr\*(C'\fR is permitted to throw an exception.
.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 DBI::DBD::SqlEngine::db or a derived class.
.IP "validate_STORE_attr" 4
.IX Item "validate_STORE_attr"
Called by \f(CW\*(C`STORE\*(C'\fR to allow inherited drivers do their own attribute
name validation. Calling convention is similar to \f(CW\*(C`STORE\*(C'\fR and the
return value is the approved attribute name followed by the approved
new value.
.Sp
.Vb 1
\&    return ($validated_attribute_name, $validated_attribute_value);
.Ve
.Sp
In case of validation fails (e.g. accessing private attribute or similar),
\&\f(CW\*(C`validate_STORE_attr\*(C'\fR is permitted to throw an exception
(\f(CW\*(C`DBI::DBD::SqlEngine::db::validate_STORE_attr\*(C'\fR throws an exception when
someone tries to assign value other than \f(CW\*(C`SQL_IC_UPPER .. SQL_IC_MIXED\*(C'\fR
to \f(CW\*(C`$dbh\->{sql_identifier_case}\*(C'\fR or
\&\f(CW\*(C`$dbh\->{sql_quoted_identifier_case}\*(C'\fR).
.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`DBI::DBD::SqlEngine::db::init_valid_attributes\*(C'\fR.
.IP "set_versions" 4
.IX Item "set_versions"
This method sets the attributes \f(CW\*(C`f_version\*(C'\fR, \f(CW\*(C`sql_nano_version\*(C'\fR,
\&\f(CW\*(C`sql_statement_version\*(C'\fR and (if not prohibited by a restrictive
\&\f(CW\*(C`${prefix}_valid_attrs\*(C'\fR) \f(CW\*(C`${prefix}_version\*(C'\fR.
.Sp
This method is called at the end 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`DBI::DBD::SqlEngine::db::init_valid_attributes\*(C'\fR initializes the
attributes \f(CW\*(C`sql_valid_attrs\*(C'\fR and \f(CW\*(C`sql_readonly_attrs\*(C'\fR.
.Sp
When overriding this method, do not forget to invoke the superior one,
preferably before doing anything else.
.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. It expects one argument: \f(CW$phase\fR.
If \f(CW$phase\fR is not given, \f(CW\*(C`connect\*(C'\fR of \f(CW\*(C`DBI::DBD::SqlEngine::dr\*(C'\fR
expects this is an old-fashioned driver which isn't capable of multi-phased
initialization.
.Sp
\&\f(CW\*(C`DBI::DBD::SqlEngine::db::init_default_attributes\*(C'\fR initializes the
attributes \f(CW\*(C`sql_identifier_case\*(C'\fR, \f(CW\*(C`sql_quoted_identifier_case\*(C'\fR,
\&\f(CW\*(C`sql_handler\*(C'\fR, \f(CW\*(C`sql_init_order\*(C'\fR, \f(CW\*(C`sql_meta\*(C'\fR, \f(CW\*(C`sql_engine_version\*(C'\fR,
\&\f(CW\*(C`sql_nano_version\*(C'\fR and \f(CW\*(C`sql_statement_version\*(C'\fR when SQL::Statement
is available.
.Sp
It sets \f(CW\*(C`sql_init_order\*(C'\fR to the given \f(CW$phase\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 and
\&\f(CW\*(C`drv_version\*(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).
.IP "get_versions" 4
.IX Item "get_versions"
This method is called by the code injected into the instantiated driver to
provide the user callable driver method \f(CW\*(C`${prefix}versions\*(C'\fR (e.g.
\&\f(CW\*(C`dbm_versions\*(C'\fR, \f(CW\*(C`csv_versions\*(C'\fR, ...).
.Sp
The DBI::DBD::SqlEngine implementation returns all version information known by
DBI::DBD::SqlEngine (e.g. \s-1DBI\s0 version, Perl version, DBI::DBD::SqlEngine version and
the \s-1SQL\s0 handler version).
.Sp
\&\f(CW\*(C`get_versions\*(C'\fR takes the \f(CW$dbh\fR as the first argument and optionally a
second argument containing a table name. The second argument is not
evaluated in \f(CW\*(C`DBI::DBD::SqlEngine::db::get_versions\*(C'\fR itself \- but
might be in the future.
.Sp
If the derived implementor class provides a method named
\&\f(CW\*(C`get_${drv_prefix}versions\*(C'\fR, this is invoked and the return value of
it is associated to the derived driver name:
.Sp
.Vb 4
\&    if (my $dgv = $dbh\->{ImplementorClass}\->can ("get_" . $drv_prefix . "versions") {
\&        (my $derived_driver = $dbh\->{ImplementorClass}) =~ s/::db$//;
\&        $versions{$derived_driver} = &$dgv ($dbh, $table);
\&    }
.Ve
.Sp
Override it to add more version information about your module, (e.g.
some kind of parser version in case of \s-1DBD::CSV, ...\s0), if one line is not
enough room to provide all relevant information.
.IP "sql_parser_object" 4
.IX Item "sql_parser_object"
Returns a SQL::Parser instance, when \f(CW\*(C`sql_handler\*(C'\fR is set to
\&\*(L"SQL::Statement\*(R". The parser instance is stored in \f(CW\*(C`sql_parser_object\*(C'\fR.
.Sp
It is not recommended to override this method.
.IP "disconnect" 4
.IX Item "disconnect"
Disconnects from a database. All local table information is discarded and
the \f(CW\*(C`Active\*(C'\fR attribute is set to 0.
.IP "type_info_all" 4
.IX Item "type_info_all"
Returns information about all the types supported by DBI::DBD::SqlEngine.
.IP "table_info" 4
.IX Item "table_info"
Returns a statement handle which is prepared to deliver information about
all known tables.
.IP "list_tables" 4
.IX Item "list_tables"
Returns a list of all known table names.
.IP "quote" 4
.IX Item "quote"
Quotes a string for use in \s-1SQL\s0 statements.
.IP "commit" 4
.IX Item "commit"
Warns about a useless call (if warnings enabled) and returns.
DBI::DBD::SqlEngine is typically a driver which commits every action
instantly when executed.
.IP "rollback" 4
.IX Item "rollback"
Warns about a useless call (if warnings enabled) and returns.
DBI::DBD::SqlEngine is typically a driver which commits every action
instantly when executed.
.PP
\fIAttributes used by \f(CI\*(C`DBI::DBD::SqlEngine::db\*(C'\fI:\fR
.IX Subsection "Attributes used by DBI::DBD::SqlEngine::db:"
.PP
This section describes attributes which are important to developers of \s-1DBI\s0
Database Drivers derived from \f(CW\*(C`DBI::DBD::SqlEngine\*(C'\fR.
.IP "sql_init_order" 4
.IX Item "sql_init_order"
This attribute contains a hash with priorities as key and an array
containing the \f(CW$dbh\fR attributes to be initialized during before/after
other attributes.
.Sp
\&\f(CW\*(C`DBI::DBD::SqlEngine\*(C'\fR initializes following attributes:
.Sp
.Vb 4
\&  $dbh\->{sql_init_order} = {
\&       0 => [qw( Profile RaiseError PrintError AutoCommit )],
\&      90 => [ "sql_meta", $dbh\->{$drv_pfx_meta} ? $dbh\->{$drv_pfx_meta} : () ]
\&  }
.Ve
.Sp
The default priority of not listed attribute keys is \f(CW50\fR. It is well
known that a lot of attributes needed to be set before some table settings
are initialized. For example, for \s-1DBD::DBM\s0, when using
.Sp
.Vb 11
\&  my $dbh = DBI\->connect( "dbi:DBM:", undef, undef, {
\&      f_dir => "/path/to/dbm/databases",
\&      dbm_type => "BerkeleyDB",
\&      dbm_mldbm => "JSON", # use MLDBM::Serializer::JSON
\&      dbm_tables => {
\&          quick => {
\&              dbm_type => "GDBM_File",
\&              dbm_MLDBM => "FreezeThaw"
\&          }
\&      }
\&  });
.Ve
.Sp
This defines a known table \f(CW\*(C`quick\*(C'\fR which uses the GDBM_File backend and
FreezeThaw as serializer instead of the overall default BerkeleyDB and
\&\s-1JSON\s0. \fBBut\fR all files containing the table data have to be searched in
\&\f(CW\*(C`$dbh\->{f_dir}\*(C'\fR, which requires \f(CW\*(C`$dbh\->{f_dir}\*(C'\fR must be initialized
before \f(CW\*(C`$dbh\->{sql_meta}\->{quick}\*(C'\fR is initialized by
\&\f(CW\*(C`bootstrap_table_meta\*(C'\fR method of \*(L"DBI::DBD::SqlEngine::Table\*(R" to get
\&\f(CW\*(C`$dbh\->{sql_meta}\->{quick}\->{f_dir}\*(C'\fR being initialized properly.
.IP "sql_init_phase" 4
.IX Item "sql_init_phase"
This attribute is only set during the initialization steps of the \s-1DBI\s0
Database Driver. It contains the value of the currently run initialization
phase. Currently supported phases are \fIphase 0\fR and \fIphase 1\fR. This
attribute is set in \f(CW\*(C`init_default_attributes\*(C'\fR and removed in \f(CW\*(C`init_done\*(C'\fR.
.IP "sql_engine_in_gofer" 4
.IX Item "sql_engine_in_gofer"
This value has a true value in case of this driver is operated via
DBD::Gofer. The impact of being operated via Gofer is a read-only
driver (not read-only databases!), so you cannot modify any attributes
later \- neither any table settings. \fBBut\fR you won't get an error in
cases you modify table attributes, so please carefully watch
\&\f(CW\*(C`sql_engine_in_gofer\*(C'\fR.
.IP "sql_table_source" 4
.IX Item "sql_table_source"
Names a class which is responsible for delivering \fIdata sources\fR and
\&\fIavailable tables\fR (Database Driver related). \fIdata sources\fR here
refers to \*(L"data_sources\*(R" in \s-1DBI\s0, not \f(CW\*(C`sql_data_source\*(C'\fR.
.Sp
See \*(L"DBI::DBD::SqlEngine::TableSource\*(R" for details.
.IP "sql_data_source" 4
.IX Item "sql_data_source"
Name a class which is responsible for handling table resources open
and completing table names requested via \s-1SQL\s0 statements.
.Sp
See \*(L"DBI::DBD::SqlEngine::DataSource\*(R" for details.
.IP "sql_dialect" 4
.IX Item "sql_dialect"
Controls the dialect understood by SQL::Parser. Possible values (delivery
state of SQL::Statement):
.Sp
.Vb 3
\&  * ANSI
\&  * CSV
\&  * AnyData
.Ve
.Sp
Defaults to \*(L"\s-1CSV\*(R". \s0 Because an SQL::Parser is instantiated only once and
SQL::Parser doesn't allow one to modify the dialect once instantiated,
it's strongly recommended to set this flag before any statement is
executed (best place is connect attribute hash).
.SS "DBI::DBD::SqlEngine::st"
.IX Subsection "DBI::DBD::SqlEngine::st"
Contains the methods to deal with prepared statement handles:
.IP "bind_param" 4
.IX Item "bind_param"
Common routine to bind placeholders to a statement for execution. It
is dangerous to override this method without detailed knowledge about
the DBI::DBD::SqlEngine internal storage structure.
.IP "execute" 4
.IX Item "execute"
Executes a previously prepared statement (with placeholders, if any).
.IP "finish" 4
.IX Item "finish"
Finishes a statement handle, discards all buffered results. The prepared
statement is not discarded so the statement can be executed again.
.IP "fetch" 4
.IX Item "fetch"
Fetches the next row from the result-set. This method may be rewritten
in a later version and if it's overridden in a derived class, the
derived implementation should not rely on the storage details.
.IP "fetchrow_arrayref" 4
.IX Item "fetchrow_arrayref"
Alias for \f(CW\*(C`fetch\*(C'\fR.
.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. Each column is returned as \f(CW\*(C`NULLABLE\*(C'\fR which might be wrong
depending on the derived backend storage.  If the statement handle has
private attributes, they can be fetched using this method, too. \fBNote\fR that
statement attributes are not associated with any table used in this statement.
.Sp
This method usually requires extending in a derived implementation.
See \s-1DBD::CSV\s0 or \s-1DBD::DBM\s0 for some example.
.IP "\s-1STORE\s0" 4
.IX Item "STORE"
Allows storing of statement private attributes. No special handling is
currently implemented here.
.IP "rows" 4
.IX Item "rows"
Returns the number of rows affected by the last execute. This method might
return \f(CW\*(C`undef\*(C'\fR.
.SS "DBI::DBD::SqlEngine::TableSource"
.IX Subsection "DBI::DBD::SqlEngine::TableSource"
Provides data sources and table information on database driver and database
handle level.
.PP
.Vb 1
\&  package DBI::DBD::SqlEngine::TableSource;
\&
\&  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 "DBI::DBD::SqlEngine::DataSource"
.IX Subsection "DBI::DBD::SqlEngine::DataSource"
Provides base functionality for dealing with tables. It is primarily
designed for allowing transparent access to files on disk or already
opened (file\-)streams (e.g. for \s-1DBD::CSV\s0).
.PP
Derived classes shall be restricted to similar functionality, too (e.g.
opening streams from an archive, transparently compress/uncompress
log files before parsing them,
.PP
.Vb 1
\&  package DBI::DBD::SqlEngine::DataSource;
\&
\&  sub complete_table_name ($$;$)
\&  {
\&    my ( $self, $meta, $table, $respect_case ) = @_;
\&    ...
\&  }
.Ve
.PP
The method \f(CW\*(C`complete_table_name\*(C'\fR is called when first setting up the
\&\fImeta information\fR for a table:
.PP
.Vb 1
\&  "SELECT user.id, user.name, user.shell FROM user WHERE ..."
.Ve
.PP
results in opening the table \f(CW\*(C`user\*(C'\fR. First step of the table open
process is completing the name. Let's imagine you're having a \s-1DBD::CSV\s0
handle with following settings:
.PP
.Vb 3
\&  $dbh\->{sql_identifier_case} = SQL_IC_LOWER;
\&  $dbh\->{f_ext} = \*(Aq.lst\*(Aq;
\&  $dbh\->{f_dir} = \*(Aq/data/web/adrmgr\*(Aq;
.Ve
.PP
Those settings will result in looking for files matching
\&\f(CW\*(C`[Uu][Ss][Ee][Rr](\e.lst)?$\*(C'\fR in \f(CW\*(C`/data/web/adrmgr/\*(C'\fR. The scanning of the
directory \f(CW\*(C`/data/web/adrmgr/\*(C'\fR and the pattern match check will be done
in \f(CW\*(C`DBD::File::DataSource::File\*(C'\fR by the \f(CW\*(C`complete_table_name\*(C'\fR method.
.PP
If you intend to provide other sources of data streams than files, in
addition to provide an appropriate \f(CW\*(C`complete_table_name\*(C'\fR method, a method
to open the resource is required:
.PP
.Vb 1
\&  package DBI::DBD::SqlEngine::DataSource;
\&
\&  sub open_data ($)
\&  {
\&    my ( $self, $meta, $attrs, $flags ) = @_;
\&    ...
\&  }
.Ve
.PP
After the method \f(CW\*(C`open_data\*(C'\fR has been run successfully, the table's meta
information are in a state which allows the table's data accessor methods
will be able to fetch/store row information. Implementation details heavily
depends on the table implementation, whereby the most famous is surely
DBD::File::Table.
.SS "DBI::DBD::SqlEngine::Statement"
.IX Subsection "DBI::DBD::SqlEngine::Statement"
Derives from DBI::SQL::Nano::Statement for unified naming when deriving
new drivers. No additional feature is provided from here.
.SS "DBI::DBD::SqlEngine::Table"
.IX Subsection "DBI::DBD::SqlEngine::Table"
Derives from DBI::SQL::Nano::Table for unified naming when deriving
new drivers.
.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.
.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`$dbh\->{ReadOnly}\*(C'\fR into \f(CW\*(C`$meta\->{readonly}\*(C'\fR, \f(CW\*(C`sql_identifier_case\*(C'\fR
and \f(CW\*(C`sql_data_source\*(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 after bootstrapping a new \fItable_meta\fR
and completing the table name a
mapping can be established between an existing \fItable_meta\fR and the
new bootstrapped one, the already existing is used and a mapping
shortcut between the recent used table name and the already known
table name is hold in \f(CW\*(C`$dbh\->{sql_meta_map}\*(C'\fR.  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_data" 4
.IX Item "open_data"
Called to open the table's data storage. This is silently forwarded
to \f(CW\*(C`$meta\->{sql_data_source}\->open_data()\*(C'\fR.
.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.
.SH "AUTHOR"
.IX Header "AUTHOR"
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.