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.

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.

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.

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.

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.

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:

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.

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.

Fetches statement handle attributes. Supported attributes (for full overview see "Statement Handle Attributes" in DBI) are NAME, TYPE, PRECISION and NULLABLE in case that SQL::Statement is used as SQL 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.

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

The method complete_table_name 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.

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.

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.

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.

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. The decision is made based on %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:

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.

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.