x3x3x3x_5h3ll
— 53cur3 — 5h3ll_1d —
Linux vps-10654784.cedaps.org.br 3.10.0-1160.119.1.el7.x86_64 #1 SMP Tue Jun 4 14:43:51 UTC 2024 x86_64
  INFO SERVER : Apache PHP : 7.4.33
/lib64/perl5/vendor_perl/DBI/DBD/SqlEngine/
162.240.100.168

 
[ NAME ] [ SIZE ] [ PERM ] [ DATE ] [ ACTN ]
+FILE +DIR
  Developers.pod 26.693 KB -rw-r--r-- 2013-05-15 09:20 R E G D
  HowTo.pod 10.215 KB -rw-r--r-- 2013-04-04 22:17 R E G D
REQUEST EXIT
=head1 NAME DBI::DBD::SqlEngine::Developers - Developers documentation for DBI::DBD::SqlEngine =head1 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); my %reset_on_modify = ( myd_abc => "myd_foo", myd_mno => "myd_bar", ); __PACKAGE__->register_reset_on_modify( \%reset_on_modify ); my %compat_map = ( abc => 'foo_abc', xyz => 'foo_xyz', ); __PACKAGE__->register_compat_map( \%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 { ... } =head1 DESCRIPTION This document describes the interface of DBI::DBD::SqlEngine for DBD developers who write DBI::DBD::SqlEngine based DBI drivers. It supplements L and L, which you should read first. =head1 CLASSES Each DBI driver must provide a package global C<< driver >> method and three DBI related classes: =over 4 =item 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 C and C. Pure Perl DBI 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 C and C of you're ::db class, the connect method might be the final place to be modified. =item DBI::DBD::SqlEngine::db Contains the methods which are called through DBI database handles (C<< $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 C<< set_versions >> and C<< init_valid_attributes >>. =item DBI::DBD::SqlEngine::TieMeta; Provides the tie-magic for C<< $dbh->{$drv_pfx . "_meta"} >>. Routes C through C<< $drv->set_sql_engine_meta() >> and C through C<< $drv->get_sql_engine_meta() >>. C is not supported, you have to execute a C statement, where applicable. =item DBI::DBD::SqlEngine::TieTables; Provides the tie-magic for tables in C<< $dbh->{$drv_pfx . "_meta"} >>. Routes C though C<< $tblClass->set_table_meta_attr() >> and C though C<< $tblClass->get_table_meta_attr() >>. C removes an attribute from the I retrieved by C<< $tblClass->get_table_meta() >>. =item DBI::DBD::SqlEngine::st Contains the methods to deal with prepared statement handles. e.g., $sth->execute () or die $sth->errstr; =item DBI::DBD::SqlEngine::TableSource; Base class for 3rd party table sources: $dbh->{sql_table_source} = "DBD::Foo::TableSource"; =item DBI::DBD::SqlEngine::DataSource; Base class for 3rd party data sources: $dbh->{sql_data_source} = "DBD::Foo::DataSource"; =item DBI::DBD::SqlEngine::Statement; Base class for derived drivers statement engine. Implements C. =item DBI::DBD::SqlEngine::Table; Contains tailoring between SQL engine's requirements and C magic for finding the right tables and storage. Builds bridges between C handling of C, table initialization for SQL engines and I's attribute management for derived drivers. =back =head2 DBI::DBD::SqlEngine This is the main package containing the routines to initialize DBI::DBD::SqlEngine based DBI drivers. Primarily the C<< 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 C<< setup_driver >> as DBI::DBD::SqlEngine takes care of it. =head2 DBI::DBD::SqlEngine::dr The driver package contains the methods DBI calls indirectly via the DBI interface (see L). 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"; =head3 Methods provided by C<< DBI::DBD::SqlEngine::dr >>: =over 4 =item connect Supervises the driver bootstrap when calling DBI->connect( "dbi:Foo", , , { ... } ); First it instantiates a new driver using C. After that, initial bootstrap of the newly instantiated driver is done by $dbh->func( 0, "init_default_attributes" ); The first argument (C<0>) signals that this is the very first call to C. Modern drivers understand that and do early stage setup here after calling 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 } When the C<$phase> argument is passed down until C, C recognizes a I driver and initializes the attributes from I and I<$attr> arguments passed via C<< DBI->connect( $dsn, $user, $pass, \%attr ) >>. At the end of the attribute initialization after I, C invoked C again for I: $dbh->func( 1, "init_default_attributes" ); =item data_sources Returns a list of I's using the C method of the class specified in C<< $dbh->{sql_table_source} >> or via C<\%attr>: @ary = DBI->data_sources($driver); @ary = DBI->data_sources($driver, \%attr); =item disconnect_all C doesn't have an overall driver cache, so nothing happens here at all. =back =head2 DBI::DBD::SqlEngine::db This package defines the database methods, which are called via the DBI database handle C<< $dbh >>. =head3 Methods provided by C<< DBI::DBD::SqlEngine::db >>: =over 4 =item ping Simply returns the content of the C<< Active >> attribute. Override when your driver needs more complicated actions here. =item prepare Prepares a new SQL statement to execute. Returns a statement handle, C<< $sth >> - instance of the DBD:XXX::st. It is neither required nor recommended to override this method. =item validate_FETCH_attr Called by C to allow inherited drivers do their own attribute name validation. Calling convention is similar to C and the return value is the approved attribute name. return $validated_attribute_name; In case of validation fails (e.g. accessing private attribute or similar), C is permitted to throw an exception. =item 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 C<$drv_prefix>) is added. The driver prefix is extracted from the attribute name and verified against C<< $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 C<< $dbh->{ $drv_prefix . "readonly_attrs" } >> when it exists), a real copy of the attribute value is returned. So it's not possible to modify C from outside of DBI::DBD::SqlEngine::db or a derived class. =item validate_STORE_attr Called by C to allow inherited drivers do their own attribute name validation. Calling convention is similar to C and the return value is the approved attribute name followed by the approved new value. return ($validated_attribute_name, $validated_attribute_value); In case of validation fails (e.g. accessing private attribute or similar), C is permitted to throw an exception (C throws an exception when someone tries to assign value other than C to C<< $dbh->{sql_identifier_case} >> or C<< $dbh->{sql_quoted_identifier_case} >>). =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 C<$drv_prefix>) is added. If the database handle has an attribute C<${drv_prefix}_valid_attrs> - for attribute names which are not listed in that hash, this method croaks. If the database handle has an attribute C<${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 C<< DBI::DBD::SqlEngine::db::init_valid_attributes >>. =item set_versions This method sets the attributes C<< f_version >>, C<< sql_nano_version >>, C<< sql_statement_version >> and (if not prohibited by a restrictive C<< ${prefix}_valid_attrs >>) C<< ${prefix}_version >>. This method is called at the end of the C<< connect () >> phase. When overriding this method, do not forget to invoke the superior one. =item init_valid_attributes This method is called after the database handle is instantiated as the first attribute initialization. C<< DBI::DBD::SqlEngine::db::init_valid_attributes >> initializes the attributes C and C. When overriding this method, do not forget to invoke the superior one, preferably before doing anything else. =item init_default_attributes This method is called after the database handle is instantiated to initialize the default attributes. It expects one argument: C<$phase>. If C<$phase> is not given, C of C expects this is an old-fashioned driver which isn't capable of multi-phased initialization. C<< DBI::DBD::SqlEngine::db::init_default_attributes >> initializes the attributes C, C, C, C, C, C, C and C when L is available. It sets C to the given C<$phase>. When the derived implementor class provides the attribute to validate attributes (e.g. C<< $dbh->{dbm_valid_attrs} = {...}; >>) or the attribute containing the immutable attributes (e.g. C<< $dbh->{dbm_readonly_attrs} = {...}; >>), the attributes C, C and C are added (when available) to the list of valid and immutable attributes (where C is interpreted as the driver prefix). =item get_versions This method is called by the code injected into the instantiated driver to provide the user callable driver method C<< ${prefix}versions >> (e.g. C<< dbm_versions >>, C<< 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). C takes the C<$dbh> as the first argument and optionally a second argument containing a table name. The second argument is not evaluated in C<< DBI::DBD::SqlEngine::db::get_versions >> itself - but might be in the future. If the derived implementor class provides a method named C, 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. =item sql_parser_object Returns a L instance, when C<< sql_handler >> is set to "SQL::Statement". The parser instance is stored in C<< sql_parser_object >>. It is not recommended to override this method. =item disconnect Disconnects from a database. All local table information is discarded and the C<< Active >> attribute is set to 0. =item type_info_all Returns information about all the types supported by DBI::DBD::SqlEngine. =item table_info Returns a statement handle which is prepared to deliver information about all known tables. =item list_tables Returns a list of all known table names. =item quote Quotes a string for use in SQL statements. =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. =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. =back =head3 Attributes used by C<< DBI::DBD::SqlEngine::db >>: This section describes attributes which are important to developers of DBI Database Drivers derived from C. =over 4 =item sql_init_order This attribute contains a hash with priorities as key and an array containing the C<$dbh> attributes to be initialized during before/after other attributes. C initializes following attributes: $dbh->{sql_init_order} = { 0 => [qw( Profile RaiseError PrintError AutoCommit )], 90 => [ "sql_meta", $dbh->{$drv_pfx_meta} ? $dbh->{$drv_pfx_meta} : () ] } The default priority of not listed attribute keys is C<50>. It is well known that a lot of attributes needed to be set before some table settings are initialized. For example, for L, when using 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" } } }); This defines a known table C which uses the L backend and L as serializer instead of the overall default L and L. B all files containing the table data have to be searched in C<< $dbh->{f_dir} >>, which requires C<< $dbh->{f_dir} >> must be initialized before C<< $dbh->{sql_meta}->{quick} >> is initialized by C method of L to get C<< $dbh->{sql_meta}->{quick}->{f_dir} >> being initialized properly. =item sql_init_phase This attribute is only set during the initialization steps of the DBI Database Driver. It contains the value of the currently run initialization phase. Currently supported phases are I and I. This attribute is set in C and removed in C. =item sql_engine_in_gofer This value has a true value in case of this driver is operated via L. 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. B you won't get an error in cases you modify table attributes, so please carefully watch C. =item sql_table_source Names a class which is responsible for delivering I and I (Database Driver related). I here refers to L, not C. See L for details. =item sql_data_source Name a class which is responsible for handling table resources open and completing table names requested via SQL statements. See L for details. =item sql_dialect Controls the dialect understood by SQL::Parser. Possible values (delivery state of SQL::Statement): * ANSI * CSV * AnyData Defaults to "CSV". Because an SQL::Parser is instantiated only once and SQL::Parser doesn't allow 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). =back =head2 DBI::DBD::SqlEngine::st Contains the methods to deal with prepared statement handles: =over 4 =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. =item execute Executes a previously prepared statement (with placeholders, if any). =item finish Finishes a statement handle, discards all buffered results. The prepared statement is not discarded so the statement can be executed again. =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. =item fetchrow_arrayref Alias for C<< fetch >>. =item FETCH Fetches statement handle attributes. Supported attributes (for full overview see L) are C, C, C and C. Each column is returned as C 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. B that statement attributes are not associated with any table used in this statement. This method usually requires extending in a derived implementation. See L or L for some example. =item STORE Allows storing of statement private attributes. No special handling is currently implemented here. =item rows Returns the number of rows affected by the last execute. This method might return C. =back =head2 DBI::DBD::SqlEngine::TableSource Provides data sources and table information on database driver and database handle level. package DBI::DBD::SqlEngine::TableSource; sub data_sources ($;$) { my ( $class, $drh, $attrs ) = @_; ... } sub avail_tables { my ( $class, $drh ) = @_; ... } The C method is called when the user invokes any of the following: @ary = DBI->data_sources($driver); @ary = DBI->data_sources($driver, \%attr); @ary = $dbh->data_sources(); @ary = $dbh->data_sources(\%attr); The C method is called when the user invokes any of the following: @names = $dbh->tables( $catalog, $schema, $table, $type ); $sth = $dbh->table_info( $catalog, $schema, $table, $type ); $sth = $dbh->table_info( $catalog, $schema, $table, $type, \%attr ); $dbh->func( "list_tables" ); Every time where an C<\%attr> argument can be specified, this C<\%attr> object's C attribute is preferred over the C<$dbh> attribute or the driver default. =head2 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-