Edit File: DBD::File.3pm
.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) .\" .\" 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" '' '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. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "DBD::File 3" .TH DBD::File 3 "2014-12-11" "perl v5.10.1" "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" DBD::File \- Base class for writing file based DBI drivers .SH "SYNOPSIS" .IX Header "SYNOPSIS" This module is a base class for writing other \s-1DBD\s0s. It is not intended to function as a \s-1DBD\s0 itself (though it is possible). If you want to access flat files, use DBD::AnyData, or \&\s-1DBD::CSV\s0 (both of which are subclasses of DBD::File). .SH "DESCRIPTION" .IX Header "DESCRIPTION" The DBD::File module is not a true \s-1DBI\s0 driver, but an abstract base class for deriving concrete \s-1DBI\s0 drivers from it. The implication is, that these drivers work with plain files, for example \s-1CSV\s0 files or \&\s-1INI\s0 files. The module is based on the SQL::Statement module, a simple \s-1SQL\s0 engine. .PP See \s-1DBI\s0 for details on \s-1DBI\s0, SQL::Statement for details on SQL::Statement and \s-1DBD::CSV\s0, \s-1DBD::DBM\s0 or DBD::AnyData for example drivers. .SS "Metadata" .IX Subsection "Metadata" The following attributes are handled by \s-1DBI\s0 itself and not by DBD::File, thus they all work as expected: .PP .Vb 10 \& Active \& ActiveKids \& CachedKids \& CompatMode (Not used) \& InactiveDestroy \& AutoInactiveDestroy \& Kids \& PrintError \& RaiseError \& Warn (Not used) .Ve .PP \fIThe following \s-1DBI\s0 attributes are handled by DBD::File:\fR .IX Subsection "The following DBI attributes are handled by DBD::File:" .PP AutoCommit .IX Subsection "AutoCommit" .PP Always on. .PP ChopBlanks .IX Subsection "ChopBlanks" .PP Works. .PP \s-1NUM_OF_FIELDS\s0 .IX Subsection "NUM_OF_FIELDS" .PP Valid after \f(CW\*(C`$sth\->execute\*(C'\fR. .PP \s-1NUM_OF_PARAMS\s0 .IX Subsection "NUM_OF_PARAMS" .PP Valid after \f(CW\*(C`$sth\->prepare\*(C'\fR. .PP \s-1NAME\s0 .IX Subsection "NAME" .PP Valid after \f(CW\*(C`$sth\->execute\*(C'\fR; undef for Non-Select statements. .PP \s-1NULLABLE\s0 .IX Subsection "NULLABLE" .PP Not really working, always returns an array ref of ones, except the affected table has been created in this session. Valid after \&\f(CW\*(C`$sth\->execute\*(C'\fR; undef for non-select statements. .PP \fIUnsupported \s-1DBI\s0 attributes and methods\fR .IX Subsection "Unsupported DBI attributes and methods" .PP bind_param_inout .IX Subsection "bind_param_inout" .PP CursorName .IX Subsection "CursorName" .PP LongReadLen .IX Subsection "LongReadLen" .PP LongTruncOk .IX Subsection "LongTruncOk" .PP \fIDBD::File specific attributes\fR .IX Subsection "DBD::File specific attributes" .PP In addition to the \s-1DBI\s0 attributes, you can use the following dbh attributes: .PP f_dir .IX Subsection "f_dir" .PP This attribute is used for setting the directory where the files are opened and it defaults to the current directory (\fI.\fR). Usually you set it on the dbh but it may be overridden per table (see f_meta). .PP When the value for \f(CW\*(C`f_dir\*(C'\fR is a relative path, it is converted into the appropriate absolute path name (based on the current working directory) when the dbh attribute is set. .PP .Vb 1 \& f_dir => "/data/foo/csv", .Ve .PP See \*(L"\s-1KNOWN\s0 \s-1BUGS\s0 \s-1AND\s0 \s-1LIMITATIONS\s0\*(R". .PP f_dir_search .IX Subsection "f_dir_search" .PP This optional attribute can be set to pass a list of folders to also find existing tables. It will \fBnot\fR be used to create new files. .PP .Vb 1 \& f_dir_search => [ "/data/bar/csv", "/dump/blargh/data" ], .Ve .PP f_ext .IX Subsection "f_ext" .PP This attribute is used for setting the file extension. The format is: .PP .Vb 1 \& extension{/flag} .Ve .PP where the /flag is optional and the extension is case-insensitive. \&\f(CW\*(C`f_ext\*(C'\fR allows you to specify an extension which: .PP .Vb 1 \& f_ext => ".csv/r", .Ve .IP "\(bu" 4 makes DBD::File prefer \fItable.extension\fR over \fItable\fR. .IP "\(bu" 4 makes the table name the filename minus the extension. .PP .Vb 1 \& DBI:CSV:f_dir=data;f_ext=.csv .Ve .PP In the above example and when \f(CW\*(C`f_dir\*(C'\fR contains both \fItable.csv\fR and \&\fItable\fR, DBD::File will open \fItable.csv\fR and the table will be named \*(L"table\*(R". If \fItable.csv\fR does not exist but \fItable\fR does that file is opened and the table is also called \*(L"table\*(R". .PP If \f(CW\*(C`f_ext\*(C'\fR is not specified and \fItable.csv\fR exists it will be opened and the table will be called \*(L"table.csv\*(R" which is probably not what you want. .PP \&\s-1NOTE:\s0 even though extensions are case-insensitive, table names are not. .PP .Vb 1 \& DBI:CSV:f_dir=data;f_ext=.csv/r .Ve .PP The \f(CW\*(C`r\*(C'\fR flag means the file extension is required and any filename that does not match the extension is ignored. .PP Usually you set it on the dbh but it may be overridden per table (see f_meta). .PP f_schema .IX Subsection "f_schema" .PP This will set the schema name and defaults to the owner of the directory in which the table file resides. You can set \f(CW\*(C`f_schema\*(C'\fR to \&\f(CW\*(C`undef\*(C'\fR. .PP .Vb 5 \& my $dbh = DBI\->connect ("dbi:CSV:", "", "", { \& f_schema => undef, \& f_dir => "data", \& f_ext => ".csv/r", \& }) or die $DBI::errstr; .Ve .PP By setting the schema you affect the results from the tables call: .PP .Vb 1 \& my @tables = $dbh\->tables (); \& \& # no f_schema \& "merijn".foo \& "merijn".bar \& \& # f_schema => "dbi" \& "dbi".foo \& "dbi".bar \& \& # f_schema => undef \& foo \& bar .Ve .PP Defining \f(CW\*(C`f_schema\*(C'\fR to the empty string is equal to setting it to \f(CW\*(C`undef\*(C'\fR so the \s-1DSN\s0 can be \f(CW"dbi:CSV:f_schema=;f_dir=."\fR. .PP f_lock .IX Subsection "f_lock" .PP The \f(CW\*(C`f_lock\*(C'\fR attribute is used to set the locking mode on the opened table files. Note that not all platforms support locking. By default, tables are opened with a shared lock for reading, and with an exclusive lock for writing. The supported modes are: .PP .Vb 1 \& 0: No locking at all. \& \& 1: Shared locks will be used. \& \& 2: Exclusive locks will be used. .Ve .PP But see \s-1KNOWN\s0 \s-1BUGS\s0 below. .PP f_lockfile .IX Subsection "f_lockfile" .PP If you wish to use a lockfile extension other than \f(CW\*(C`.lck\*(C'\fR, simply specify the \f(CW\*(C`f_lockfile\*(C'\fR attribute: .PP .Vb 3 \& $dbh = DBI\->connect ("dbi:DBM:f_lockfile=.foo"); \& $dbh\->{f_lockfile} = ".foo"; \& $dbh\->{dbm_tables}{qux}{f_lockfile} = ".foo"; .Ve .PP If you wish to disable locking, set the \f(CW\*(C`f_lockfile\*(C'\fR to \f(CW0\fR. .PP .Vb 3 \& $dbh = DBI\->connect ("dbi:DBM:f_lockfile=0"); \& $dbh\->{f_lockfile} = 0; \& $dbh\->{dbm_tables}{qux}{f_lockfile} = 0; .Ve .PP f_encoding .IX Subsection "f_encoding" .PP With this attribute, you can set the encoding in which the file is opened. This is implemented using \f(CW\*(C`binmode $fh, ":encoding(<f_encoding>)"\*(C'\fR. .PP f_meta .IX Subsection "f_meta" .PP Private data area aliasing \*(L"sql_meta\*(R" in DBI::DBD::SqlEngine which contains information about the tables this module handles. Table meta data might not be available until the table has been accessed for the first time e.g., by issuing a select on it however it is possible to pre-initialize attributes for each table you use. .PP DBD::File recognizes the (public) attributes \f(CW\*(C`f_ext\*(C'\fR, \f(CW\*(C`f_dir\*(C'\fR, \&\f(CW\*(C`f_file\*(C'\fR, \f(CW\*(C`f_encoding\*(C'\fR, \f(CW\*(C`f_lock\*(C'\fR, \f(CW\*(C`f_lockfile\*(C'\fR, \f(CW\*(C`f_schema\*(C'\fR, in addition to the attributes \*(L"sql_meta\*(R" in DBI::DBD::SqlEngine already supports. Be very careful when modifying attributes you do not know, the consequence might be a destroyed or corrupted table. .PP \&\f(CW\*(C`f_file\*(C'\fR is an attribute applicable to table meta data only and you will not find a corresponding attribute in the dbh. Whilst it may be reasonable to have several tables with the same column names, it is not for the same file name. If you need access to the same file using different table names, use \f(CW\*(C`SQL::Statement\*(C'\fR as the \s-1SQL\s0 engine and the \&\f(CW\*(C`AS\*(C'\fR keyword: .PP .Vb 1 \& SELECT * FROM tbl AS t1, tbl AS t2 WHERE t1.id = t2.id .Ve .PP \&\f(CW\*(C`f_file\*(C'\fR can be an absolute path name or a relative path name but if it is relative, it is interpreted as being relative to the \f(CW\*(C`f_dir\*(C'\fR attribute of the table meta data. When \f(CW\*(C`f_file\*(C'\fR is set DBD::File will use \f(CW\*(C`f_file\*(C'\fR as specified and will not attempt to work out an alternative for \f(CW\*(C`f_file\*(C'\fR using the \f(CW\*(C`table name\*(C'\fR and \f(CW\*(C`f_ext\*(C'\fR attribute. .PP While \f(CW\*(C`f_meta\*(C'\fR is a private and readonly attribute (which means, you cannot modify it's values), derived drivers might provide restricted write access through another attribute. Well known accessors are \&\f(CW\*(C`csv_tables\*(C'\fR for \s-1DBD::CSV\s0, \f(CW\*(C`ad_tables\*(C'\fR for DBD::AnyData and \&\f(CW\*(C`dbm_tables\*(C'\fR for \s-1DBD::DBM\s0. .PP \fINew opportunities for attributes from DBI::DBD::SqlEngine\fR .IX Subsection "New opportunities for attributes from DBI::DBD::SqlEngine" .PP sql_table_source .IX Subsection "sql_table_source" .PP \&\f(CW\*(C`$dbh\->{sql_table_source}\*(C'\fR can be set to \&\fIDBD::File::TableSource::FileSystem\fR (and is the default setting of DBD::File). This provides usual behaviour of previous DBD::File releases on .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); \& \& @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 sql_data_source .IX Subsection "sql_data_source" .PP \&\f(CW\*(C`$dbh\->{sql_data_source}\*(C'\fR can be set to either \&\fIDBD::File::DataSource::File\fR, which is default and provides the well known behavior of DBD::File releases prior to 0.41, or \&\fIDBD::File::DataSource::Stream\fR, which reuses already opened file-handle for operations. .PP \fIInternally private attributes to deal with \s-1SQL\s0 backends\fR .IX Subsection "Internally private attributes to deal with SQL backends" .PP Do not modify any of these private attributes unless you understand the implications of doing so. The behavior of DBD::File and derived DBDs might be unpredictable when one or more of those attributes are modified. .PP sql_nano_version .IX Subsection "sql_nano_version" .PP Contains the version of loaded DBI::SQL::Nano. .PP sql_statement_version .IX Subsection "sql_statement_version" .PP Contains the version of loaded SQL::Statement. .PP sql_handler .IX Subsection "sql_handler" .PP Contains either the text 'SQL::Statement' or 'DBI::SQL::Nano'. .PP sql_ram_tables .IX Subsection "sql_ram_tables" .PP Contains optionally temporary tables. .PP sql_flags .IX Subsection "sql_flags" .PP Contains optional flags to instantiate the SQL::Parser parsing engine when SQL::Statement is used as \s-1SQL\s0 engine. See SQL::Parser for valid flags. .SS "Driver private methods" .IX Subsection "Driver private methods" \fIDefault \s-1DBI\s0 methods\fR .IX Subsection "Default DBI methods" .PP data_sources .IX Subsection "data_sources" .PP The \f(CW\*(C`data_sources\*(C'\fR method returns a list of subdirectories of the current directory in the form \*(L"dbi:CSV:f_dir=$dirname\*(R". .PP If you want to read the subdirectories of another directory, use .PP .Vb 2 \& my ($drh) = DBI\->install_driver ("CSV"); \& my (@list) = $drh\->data_sources (f_dir => "/usr/local/csv_data"); .Ve .PP \fIAdditional methods\fR .IX Subsection "Additional methods" .PP The following methods are only available via their documented name when DBD::File is used directly. Because this is only reasonable for testing purposes, the real names must be used instead. Those names can be computed by replacing the \f(CW\*(C`f_\*(C'\fR in the method name with the driver prefix. .PP f_versions .IX Subsection "f_versions" .PP Signature: .PP .Vb 6 \& sub f_versions (;$) \& { \& my ($table_name) = @_; \& $table_name ||= "."; \& ... \& } .Ve .PP Returns the versions of the driver, including the \s-1DBI\s0 version, the Perl version, DBI::PurePerl version (if DBI::PurePerl is active) and the version of the \s-1SQL\s0 engine in use. .PP .Vb 9 \& my $dbh = DBI\->connect ("dbi:File:"); \& my $f_versions = $dbh\->func ("f_versions"); \& print "$f_versions\en"; \& _\|_END_\|_ \& # DBD::File 0.41 using IO::File (1.16) \& # DBI::DBD::SqlEngine 0.05 using SQL::Statement 1.406 \& # DBI 1.623 \& # OS darwin (12.2.1) \& # Perl 5.017006 (darwin\-thread\-multi\-ld\-2level) .Ve .PP Called in list context, f_versions will return an array containing each line as single entry. .PP Some drivers might use the optional (table name) argument and modify version information related to the table (e.g. \s-1DBD::DBM\s0 provides storage backend information for the requested table, when it has a table name). .SH "KNOWN BUGS AND LIMITATIONS" .IX Header "KNOWN BUGS AND LIMITATIONS" .IP "\(bu" 4 This module uses flock () internally but flock is not available on all platforms. On MacOS and Windows 95 there is no locking at all (perhaps not so important on MacOS and Windows 95, as there is only a single user). .IP "\(bu" 4 The module stores details about the handled tables in a private area of the driver handle (\f(CW$drh\fR). This data area is not shared between different driver instances, so several \f(CW\*(C`DBI\->connect ()\*(C'\fR calls will cause different table instances and private data areas. .Sp This data area is filled for the first time when a table is accessed, either via an \s-1SQL\s0 statement or via \f(CW\*(C`table_info\*(C'\fR and is not destroyed until the table is dropped or the driver handle is released. Manual destruction is possible via f_clear_meta. .Sp The following attributes are preserved in the data area and will evaluated instead of driver globals: .RS 4 .IP "f_ext" 8 .IX Item "f_ext" .PD 0 .IP "f_dir" 8 .IX Item "f_dir" .IP "f_dir_search" 8 .IX Item "f_dir_search" .IP "f_lock" 8 .IX Item "f_lock" .IP "f_lockfile" 8 .IX Item "f_lockfile" .IP "f_encoding" 8 .IX Item "f_encoding" .IP "f_schema" 8 .IX Item "f_schema" .IP "col_names" 8 .IX Item "col_names" .IP "sql_identifier_case" 8 .IX Item "sql_identifier_case" .RE .RS 4 .PD .Sp The following attributes are preserved in the data area only and cannot be set globally. .IP "f_file" 8 .IX Item "f_file" .RE .RS 4 .Sp The following attributes are preserved in the data area only and are computed when initializing the data area: .IP "f_fqfn" 8 .IX Item "f_fqfn" .PD 0 .IP "f_fqbn" 8 .IX Item "f_fqbn" .IP "f_fqln" 8 .IX Item "f_fqln" .IP "table_name" 8 .IX Item "table_name" .RE .RS 4 .PD .Sp For \s-1DBD::CSV\s0 tables this means, once opened \*(L"foo.csv\*(R" as table named \*(L"foo\*(R", another table named \*(L"foo\*(R" accessing the file \*(L"foo.txt\*(R" cannot be opened. Accessing \*(L"foo\*(R" will always access the file \*(L"foo.csv\*(R" in memorized \&\f(CW\*(C`f_dir\*(C'\fR, locking \f(CW\*(C`f_lockfile\*(C'\fR via memorized \f(CW\*(C`f_lock\*(C'\fR. .Sp You can use f_clear_meta or the \f(CW\*(C`f_file\*(C'\fR attribute for a specific table to work around this. .RE .IP "\(bu" 4 When used with SQL::Statement and temporary tables e.g., .Sp .Vb 1 \& CREATE TEMP TABLE ... .Ve .Sp the table data processing bypasses DBD::File::Table. No file system calls will be made and there are no clashes with existing (file based) tables with the same name. Temporary tables are chosen over file tables, but they will not covered by \f(CW\*(C`table_info\*(C'\fR. .SH "AUTHOR" .IX Header "AUTHOR" This module is currently maintained by .PP H.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack < rehsack at googlemail.com > .PP The original author is Jochen Wiedmann. .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" .Vb 3 \& Copyright (C) 2009\-2013 by H.Merijn Brand & Jens Rehsack \& Copyright (C) 2004\-2009 by Jeff Zucker \& Copyright (C) 1998\-2004 by Jochen Wiedmann .Ve .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. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1DBI\s0, \s-1DBD::DBM\s0, \s-1DBD::CSV\s0, Text::CSV, Text::CSV_XS, SQL::Statement, and DBI::SQL::Nano
Back to File Manager