Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

DBI::DBD::SqlEngine::Developers(3)   User Contributed Perl Documentation  DBI::DBD::SqlEngine::Developers(3)



NAME
       DBI::DBD::SqlEngine::Developers - Developers documentation for DBI::DBD::SqlEngine

SYNOPSIS
           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);

           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 { ... }

DESCRIPTION
       This document describes the interface of DBI::DBD::SqlEngine for DBD developers who write
       DBI::DBD::SqlEngine based DBI drivers. It supplements DBI::DBD and DBI::DBD::SqlEngine::HowTo, which
       you should read first.

CLASSES
       Each DBI driver must provide a package global "driver" method and three DBI related classes:

       DBI::DBD::SqlEngine::dr
           Driver package, contains the methods DBI calls indirectly via DBI interface:

             DBI->connect ('DBI:DBM:', undef, undef, {})

             # invokes
             package DBD::DBM::dr;
             @DBD::DBM::dr::ISA = qw(DBI::DBD::SqlEngine::dr);

             sub connect ($$;$$$)
             {
                 ...
             }

           Similar for "data_sources ()" and "disconnect_all()".

           Pure Perl DBI drivers derived from DBI::DBD::SqlEngine 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.

       DBI::DBD::SqlEngine::db
           Contains the methods which are called through DBI database handles ($dbh). e.g.,

             $sth = $dbh->prepare ("select * from foo");
             # returns the f_encoding setting for table foo
             $dbh->csv_get_meta ("foo", "f_encoding");

           DBI::DBD::SqlEngine provides the typical methods required here. Developers who write DBI drivers
           based on DBI::DBD::SqlEngine need to override the methods "set_versions" and
           "init_valid_attributes".

       DBI::DBD::SqlEngine::st
           Contains the methods to deal with prepared statement handles. e.g.,

             $sth->execute () or die $sth->errstr;

   DBI::DBD::SqlEngine
       This is the main package containing the routines to initialize DBI::DBD::SqlEngine based DBI drivers.
       Primarily the "DBI::DBD::SqlEngine::driver" method is invoked, either directly from DBI when the
       driver is initialized or from the derived class.

         package DBD::DBM;

         use base qw( DBI::DBD::SqlEngine );

         sub driver
         {
             my ( $class, $attr ) = @_;
             ...
             my $drh = $class->SUPER::driver( $attr );
             ...
             return $drh;
         }

       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 "setup_driver" as
       DBI::DBD::SqlEngine takes care of it.

   DBI::DBD::SqlEngine::dr
       The driver package contains the methods DBI calls indirectly via the DBI interface (see "DBI Class
       Methods" in DBI).

       DBI::DBD::SqlEngine based DBI drivers usually do not need to implement anything here, it is enough to
       do the basic initialization:

         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";

   DBI::DBD::SqlEngine::db
       This package defines the database methods, which are called via the DBI database handle $dbh.

       Methods provided by DBI::DBD::SqlEngine:

       ping
           Simply returns the content of the "Active" attribute. Override when your driver needs more
           complicated actions here.

       prepare
           Prepares a new SQL statement to execute. Returns a statement handle, $sth - instance of the
           DBD:XXX::st. It is neither required nor recommended to override this method.

       FETCH
           Fetches an attribute of a DBI 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 $drv_prefix) is added.

           The driver prefix is extracted from the attribute name and verified against "$dbh->{ $drv_prefix
           . "valid_attrs" }" (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 "$dbh->{
           $drv_prefix . "readonly_attrs" }" when it exists), a real copy of the attribute value is
           returned. So it's not possible to modify "f_valid_attrs" from outside of DBI::DBD::SqlEngine::db
           or a derived class.

       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 $drv_prefix) is added. If the database handle has an attribute
           "${drv_prefix}_valid_attrs" - for attribute names which are not listed in that hash, this method
           croaks. If the database handle has an attribute "${drv_prefix}_readonly_attrs", 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.

           An example of a valid attributes list can be found in
           "DBI::DBD::SqlEngine::db::init_valid_attributes".

       set_versions
           This method sets the attributes "f_version", "sql_nano_version", "sql_statement_version" and (if
           not prohibited by a restrictive "${prefix}_valid_attrs") "${prefix}_version".

           This method is called at the end of the "connect ()" phase.

           When overriding this method, do not forget to invoke the superior one.

       init_valid_attributes
           This method is called after the database handle is instantiated as the first attribute
           initialization.

           "DBI::DBD::SqlEngine::db::init_valid_attributes" initializes the attributes "sql_valid_attrs" and
           "sql_readonly_attrs".

           When overriding this method, do not forget to invoke the superior one, preferably before doing
           anything else.

       init_default_attributes
           This method is called after the database handle is instantiated to initialize the default
           attributes.

           "DBI::DBD::SqlEngine::db::init_default_attributes" initializes the attributes
           "sql_identifier_case", "sql_quoted_identifier_case", "sql_handler", "sql_engine_version",
           "sql_nano_version" and "sql_statement_version" when SQL::Statement is available.

           When the derived implementor class provides the attribute to validate attributes (e.g.
           "$dbh->{dbm_valid_attrs} = {...};") or the attribute containing the immutable attributes (e.g.
           "$dbh->{dbm_readonly_attrs} = {...};"), the attributes "drv_valid_attrs", "drv_readonly_attrs"
           and "drv_version" are added (when available) to the list of valid and immutable attributes (where
           "drv_" is interpreted as the driver prefix).

       get_versions
           This method is called by the code injected into the instantiated driver to provide the user
           callable driver method "${prefix}versions" (e.g.  "dbm_versions", "csv_versions", ...).

           The DBI::DBD::SqlEngine implementation returns all version information known by
           DBI::DBD::SqlEngine (e.g. DBI version, Perl version, DBI::DBD::SqlEngine version and the SQL
           handler version).

           "get_versions" takes the $dbh as the first argument and optionally a second argument containing a
           table name. The second argument is not evaluated in "DBI::DBD::SqlEngine::db::get_versions"
           itself - but might be in the future.

           If the derived implementor class provides a method named "get_${drv_prefix}versions", this is
           invoked and the return value of it is associated to the derived driver name:

               if (my $dgv = $dbh->{ImplementorClass}->can ("get_" . $drv_prefix . "versions") {
                   (my $derived_driver = $dbh->{ImplementorClass}) =~ s/::db$//;
                   $versions{$derived_driver} = &$dgv ($dbh, $table);
               }

           Override it to add more version information about your module, (e.g.  some kind of parser version
           in case of DBD::CSV, ...), if one line is not enough room to provide all relevant information.

       sql_parser_object
           Returns a SQL::Parser instance, when "sql_handler" is set to "SQL::Statement". The parser
           instance is stored in "sql_parser_object".

           It is not recommended to override this method.

       disconnect
           Disconnects from a database. All local table information is discarded and the "Active" attribute
           is set to 0.

       type_info_all
           Returns information about all the types supported by DBI::DBD::SqlEngine.

       table_info
           Returns a statement handle which is prepared to deliver information about all known tables.

       list_tables
           Returns a list of all known table names.

       quote
           Quotes a string for use in SQL statements.

       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.

       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.

   DBI::DBD::SqlEngine::st
       Contains the methods to deal with prepared statement handles:

       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.

       execute
           Executes a previously prepared statement (with placeholders, if any).

       finish
           Finishes a statement handle, discards all buffered results. The prepared statement is not
           discarded so the statement can be executed again.

       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.

       fetchrow_arrayref
           Alias for "fetch".

       FETCH
           Fetches statement handle attributes. Supported attributes (for full overview see "Statement
           Handle Attributes" in DBI) are "NAME", "TYPE", "PRECISION" and "NULLABLE". Each column is
           returned as "NULLABLE" 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. Note that
           statement attributes are not associated with any table used in this statement.

           This method usually requires extending in a derived implementation.  See DBD::CSV or DBD::DBM for
           some example.

       STORE
           Allows storing of statement private attributes. No special handling is currently implemented
           here.

       rows
           Returns the number of rows affected by the last execute. This method might return "undef".

   DBI::DBD::SqlEngine::Statement
       Derives from DBI::SQL::Nano::Statement for unified naming when deriving new drivers. No additional
       feature is provided from here.

   DBI::DBD::SqlEngine::Table
       Derives from DBI::SQL::Nano::Table for unified naming when deriving new drivers. No additional
       feature is provided from here.

       You should consult the documentation of "SQL::Eval::Table" (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 SQL engines.

AUTHOR
       The module DBI::DBD::SqlEngine 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.



perl v5.12.5                                     2010-08-30               DBI::DBD::SqlEngine::Developers(3)