DBD::File::Developers man page on Raspbian

Man page or keyword search:  
man Server   8174 pages
apropos Keyword Search (all sections)
Output format
Raspbian logo
[printable version]

DBD::File::Developers(User Contributed Perl DocumentDBD::File::Developers(3pm)

NAME
       DBD::File::Developers - Developers documentation for DBD::File

SYNOPSIS
	 perldoc DBD::File::Developers

	 perldoc DBD::File::Roadmap

       This document describes how DBD developers can write DBD::File based
       DBI drivers. It supplements DBI::DBD, which you should read first.

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

       DBD::File::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(DBD::File::dr);

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

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

	   Pure Perl DBI 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.

       DBD::File::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");

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

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

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

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

	 package DBD::DBM;

	 use base qw( DBD::File );

	 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 DBD::File
       takes care of it.

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

       DBD::File 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 (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";

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

       Methods provided by DBD::File:

       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
	   DBD::File::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
	   "DBD::File::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.

	   "DBD::File::db::init_valid_attributes" initializes the attributes
	   "f_valid_attrs", "sql_valid_attrs", "f_readonly_attrs" and
	   "sql_readonly_attrs".

	   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:

	       # for DBD::CSV
	       $dbh->{csv_meta} = "csv_tables";
	       # for DBD::DBM
	       $dbh->{dbm_meta} = "dbm_tables";
	       # for DBD::AnyData
	       $dbh->{ad_meta}	= "ad_tables";

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

	   "DBD::File::db::init_default_attributes" initializes the attributes
	   "f_dir", "f_meta", "f_meta_map", "f_version",
	   "sql_identifier_case", "sql_quoted_identifier_case" and
	   "sql_handler".

	   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", "drv_version" and
	   "drv_meta" are added (when available) to the list of valid and
	   immutable attributes (where "drv_" is interpreted as the driver
	   prefix).

	   If "drv_meta" is set, an attribute with the name in "drv_meta" is
	   initialized providing restricted read/write access to the meta data
	   of the tables using "DBD::File::TieTables" in the first (table)
	   level and "DBD::File::TieMeta" for the meta attribute level.
	   "DBD::File::TieTables" uses "DBD::DRV::Table::get_table_meta" to
	   initialize the second level tied hash on FETCH/STORE. The
	   "DBD::File::TieMeta" class uses
	   "DBD::DRV::Table::get_table_meta_attr" to FETCH attribute values
	   and "DBD::DRV::Table::set_table_meta_attr" to STORE attribute
	   values. This allows it to map meta attributes for compatibility
	   reasons.

       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 DBD::File implementation returns all version information known
	   by DBD::File (e.g. DBI version, Perl version, DBD::File 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 "DBD::File::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.

       get_single_table_meta
       get_file_meta
	   Retrieve an attribute from a table's meta information. The method
	   signature is "get_file_meta ($dbh, $table, $attr)". This method is
	   called by the injected db handle method "${drv_prefix}get_meta".

	   While get_file_meta allows $table or $attr 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 '.' (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 "$dbh->{$attrib}".

	   get_file_meta allows '+' and '*' as wildcards for table names and
	   $table being a regular expression matching against the table names
	   (evaluated without the default table). The table name '*' is all
	   currently known tables, including the default one. The table name
	   '+' is all table names which conform to ANSI file name restrictions
	   (/^[_A-Za-z0-9]+$/).

	   The table meta information is retrieved using the get_table_meta
	   and get_table_meta_attr methods of the table class of the
	   implementation.

       set_single_table_meta
       set_file_meta
	   Sets an attribute in a table's meta information. The method
	   signature is "set_file_meta ($dbh, $table, $attr, $value)". This
	   method is called by the injected db handle method
	   "${drv_prefix}set_meta".

	   While set_file_meta allows $table to be a list of tables and $attr
	   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.

	   The wildcard characters for the table name are the same as for
	   get_file_meta.

	   The table meta information is updated using the get_table_meta and
	   set_table_meta_attr methods of the table class of the
	   implementation.

       clear_file_meta
	   Clears all meta information cached about a table. The method
	   signature is "clear_file_meta ($dbh, $table)". This method is
	   called by the injected db handle method "${drv_prefix}clear_meta".

       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 DBD::File.

       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.
	   DBD::File is typically a driver which commits every action
	   instantly when executed.

       rollback
	   Warns about a useless call (if warnings enabled) and returns.
	   DBD::File is typically a driver which commits every action
	   instantly when executed.

   DBD::File::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 DBD::File 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" 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.

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

   DBD::File::Statement
       Derives from DBI::SQL::Nano::Statement to provide following method:

       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 parameterized in DBD::File::Table. Unless
	   you intend to add anything to the following implementation, an
	   empty DBD::XXX::Statement package satisfies DBD::File.

	     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

   DBD::File::Table
       Derives from DBI::SQL::Nano::Table and provides physical file access
       for the table data which are stored in the files.

       file2table
	   This method 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_ext", "f_dir", "f_lockfile" and "sql_identifier_case".

	   If a file/table map can be found then this method sets the
	   "f_fqfn", "f_fqbn", "f_fqln" and "table_name" attributes in the
	   meta structure. If a map cannot be found the table name will be
	   undef.

       bootstrap_table_meta
	   Initializes a table meta structure. Can be safely overridden in a
	   derived class, as long as the "SUPER" method is called at the end
	   of the overridden method.

	   It copies the following attributes from the database into the table
	   meta data "f_dir", "f_ext", "f_encoding", "f_lock", "f_schema",
	   "f_lockfile" and "sql_identifier_case" and makes them sticky to the
	   table.

	   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.

       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.

       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.

       get_table_meta_attr
	   Returns a single attribute from the table meta data. This method
	   should be overridden when mapped attribute names should be returned
	   for compatibility reasons.

       set_table_meta_attr
	   Sets a single attribute in the table meta data. This method should
	   be overridden when mapped attribute names should be modified for
	   compatibility reasons.

	   If the modified attribute requires to reset a calculated attribute,
	   the calculated attribute is reset (deleted from meta data
	   structure) and the initialized flag is removed, too.

       register_reset_on_modify
	   Allows "set_table_meta_attr" to reset meta attributes when special
	   attributes are modified. For DBD::File, modifying one of "f_file",
	   "f_dir", "f_ext" or "f_lockfile" will reset "f_fqfn". DBD::DBM
	   extends the list for "dbm_type" and "dbm_mldbm" to reset the value
	   of "dbm_tietype".

	   If your DBD has calculated values in the meta data area, then call
	   "register_reset_on_modify":

	       my %reset_on_modify = ( "xxx_foo" => "xxx_bar" );
	       __PACKAGE__->register_reset_on_modify( \%reset_on_modify );

       open_file
	   Called to open the table's data file.

	   Depending on the attributes set in the table's meta data, the
	   following steps are performed. Unless "f_dontopen" is set to a true
	   value, "f_fqfn" must contain the full qualified file name for the
	   table to work on (file2table ensures this). The encoding in
	   "f_encoding" is applied if set and the file is opened. If "<f_fqln
	   "> (full qualified lock name) is set, this file is opened, too.
	   Depending on the value in "f_lock", the appropriate lock is set on
	   the opened data file or lock file.

	   After this is done, a derived class might add more steps in an
	   overridden "open_file" method.

       new Instantiates the table. This is done in 3 steps:

	    1. get the table meta data
	    2. open the data file
	    3. bless the table data structure using inherited constructor new

	   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.

       drop
	   Implements the abstract table method for the "DROP" command.
	   Discards table meta data after all files belonging to the table are
	   closed and unlinked.

	   Overriding this method might be reasonable in very rare cases.

       seek
	   Implements the abstract table method used when accessing the table
	   from the engine. "seek" is called every time the engine uses dumb
	   algorithms for iterating over the table content.

       truncate
	   Implements the abstract table method used when dumb table
	   algorithms for "UPDATE" or "DELETE" need to truncate the table
	   storage after the last written row.

       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 DBD::File is currently maintained by

       H.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack  < rehsack
       at googlemail.com >

       The original author is Jochen Wiedmann.

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.10.1			  2010-07-02	    DBD::File::Developers(3pm)
[top]

List of man pages available for Raspbian

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net