DBD::File(3pm)

1DBD::File(3)          User Contributed Perl Documentation         DBD::File(3)
2
3
4

NAME

6       DBD::File - Base class for writing file based DBI drivers
7

SYNOPSIS

9       This module is a base class for writing other DBDs.  It is not intended
10       to function as a DBD itself (though it is possible).  If you want to
11       access flat files, use DBD::AnyData, or DBD::CSV (both of which are
12       subclasses of DBD::File).
13

DESCRIPTION

15       The DBD::File module is not a true DBI driver, but an abstract base
16       class for deriving concrete DBI drivers from it. The implication is,
17       that these drivers work with plain files, for example CSV files or INI
18       files. The module is based on the SQL::Statement module, a simple SQL
19       engine.
20
21       See DBI for details on DBI, SQL::Statement for details on
22       SQL::Statement and DBD::CSV, DBD::DBM or DBD::AnyData for example
23       drivers.
24
25   Metadata
26       The following attributes are handled by DBI itself and not by
27       DBD::File, thus they all work as expected:
28
29           Active
30           ActiveKids
31           CachedKids
32           CompatMode             (Not used)
33           InactiveDestroy
34           Kids
35           PrintError
36           RaiseError
37           Warn                   (Not used)
38
39       The following DBI attributes are handled by DBD::File:
40
41       AutoCommit
42
43       Always on.
44
45       ChopBlanks
46
47       Works.
48
49       NUM_OF_FIELDS
50
51       Valid after "$sth->execute".
52
53       NUM_OF_PARAMS
54
55       Valid after "$sth->prepare".
56
57       NAME
58
59       Valid after "$sth->execute"; undef for Non-Select statements.
60
61       NULLABLE
62
63       Not really working, always returns an array ref of ones, as DBD::CSV
64       does not verify input data. Valid after "$sth->execute"; undef for non-
65       select statements.
66
67       The following DBI attributes and methods are not supported:
68
69       bind_param_inout
70       CursorName
71       LongReadLen
72       LongTruncOk
73
74       DBD::File specific attributes
75
76       In addition to the DBI attributes, you can use the following dbh
77       attributes:
78
79       f_dir
80
81       This attribute is used for setting the directory where the files are
82       opened and it defaults to the current directory (.). Usually you set it
83       on the dbh but it may be overridden per table (see f_meta).
84
85       When the value for "f_dir" is a relative path, it is converted into the
86       appropriate absolute path name (based on the current working directory)
87       when the dbh attribute is set.
88
89       See "KNOWN BUGS AND LIMITATIONS".
90
91       f_ext
92
93       This attribute is used for setting the file extension. The format is:
94
95         extension{/flag}
96
97       where the /flag is optional and the extension is case-insensitive.
98       "f_ext" allows you to specify an extension which:
99
100       ·   makes DBD::File prefer table.extension over table.
101
102       ·   makes the table name the filename minus the extension.
103
104           DBI:CSV:f_dir=data;f_ext=.csv
105
106       In the above example and when "f_dir" contains both table.csv and
107       table, DBD::File will open table.csv and the table will be named
108       "table". If table.csv does not exist but table does that file is opened
109       and the table is also called "table".
110
111       If "f_ext" is not specified and table.csv exists it will be opened and
112       the table will be called "table.csv" which is probably not what you
113       want.
114
115       NOTE: even though extensions are case-insensitive, table names are not.
116
117           DBI:CSV:f_dir=data;f_ext=.csv/r
118
119       The "r" flag means the file extension is required and any filename that
120       does not match the extension is ignored.
121
122       Usually you set it on the dbh but it may be overridden per table (see
123       f_meta).
124
125       f_schema
126
127       This will set the schema name and defaults to the owner of the
128       directory in which the table file resides. You can set "f_schema" to
129       "undef".
130
131           my $dbh = DBI->connect ("dbi:CSV:", "", "", {
132               f_schema => undef,
133               f_dir    => "data",
134               f_ext    => ".csv/r",
135               }) or die $DBI::errstr;
136
137       By setting the schema you affect the results from the tables call:
138
139           my @tables = $dbh->tables ();
140
141           # no f_schema
142           "merijn".foo
143           "merijn".bar
144
145           # f_schema => "dbi"
146           "dbi".foo
147           "dbi".bar
148
149           # f_schema => undef
150           foo
151           bar
152
153       Defining "f_schema" to the empty string is equal to setting it to
154       "undef" so the DSN can be "dbi:CSV:f_schema=;f_dir=.".
155
156       f_lock
157
158       The "f_lock" attribute is used to set the locking mode on the opened
159       table files. Note that not all platforms support locking.  By default,
160       tables are opened with a shared lock for reading, and with an exclusive
161       lock for writing. The supported modes are:
162
163         0: No locking at all.
164
165         1: Shared locks will be used.
166
167         2: Exclusive locks will be used.
168
169       But see KNOWN BUGS below.
170
171       f_lockfile
172
173       If you wish to use a lockfile extension other than ".lck", simply
174       specify the "f_lockfile" attribute:
175
176         $dbh = DBI->connect ("dbi:DBM:f_lockfile=.foo");
177         $dbh->{f_lockfile} = ".foo";
178         $dbh->{f_meta}{qux}{f_lockfile} = ".foo";
179
180       If you wish to disable locking, set the "f_lockfile" to 0.
181
182         $dbh = DBI->connect ("dbi:DBM:f_lockfile=0");
183         $dbh->{f_lockfile} = 0;
184         $dbh->{f_meta}{qux}{f_lockfile} = 0;
185
186       f_encoding
187
188       With this attribute, you can set the encoding in which the file is
189       opened.  This is implemented using "binmode $fh,
190       ":encoding(<f_encoding>)"".
191
192       f_meta
193
194       Private data area which contains information about the tables this
195       module handles. Table meta data might not be available until the table
196       has been accessed for the first time e.g., by issuing a select on it
197       however it is possible to pre-initialize attributes for each table you
198       use.
199
200       DBD::File recognizes the (public) attributes "f_ext", "f_dir",
201       "f_file", "f_encoding", "f_lock", "f_lockfile", "f_schema",
202       "col_names", "table_name" and "sql_identifier_case". Be very careful
203       when modifying attributes you do not know, the consequence might be a
204       destroyed or corrupted table.
205
206       "f_file" is an attribute applicable to table meta data only and you
207       will not find a corresponding attribute in the dbh. Whilst it may be
208       reasonable to have several tables with the same column names, it is not
209       for the same file name. If you need access to the same file using
210       different table names, use "SQL::Statement" as the SQL engine and the
211       "AS" keyword:
212
213           SELECT * FROM tbl AS t1, tbl AS t2 WHERE t1.id = t2.id
214
215       "f_file" can be an absolute path name or a relative path name but if it
216       is relative, it is interpreted as being relative to the "f_dir"
217       attribute of the table meta data. When "f_file" is set DBD::File will
218       use "f_file" as specified and will not attempt to work out an
219       alternative for "f_file" using the "table name" and "f_ext" attribute.
220
221       While "f_meta" is a private and readonly attribute (which means, you
222       cannot modify it's values), derived drivers might provide restricted
223       write access through another attribute. Well known accessors are
224       "csv_tables" for DBD::CSV, "ad_tables" for DBD::AnyData and
225       "dbm_tables" for DBD::DBM.
226
227       Internally private attributes to deal with SQL backends:
228
229       Do not modify any of these private attributes unless you understand the
230       implications of doing so. The behavior of DBD::File and derived DBDs
231       might be unpredictable when one or more of those attributes are
232       modified.
233
234       sql_nano_version
235
236       Contains the version of loaded DBI::SQL::Nano.
237
238       sql_statement_version
239
240       Contains the version of loaded SQL::Statement.
241
242       sql_handler
243
244       Contains either the text 'SQL::Statement' or 'DBI::SQL::Nano'.
245
246       sql_ram_tables
247
248       Contains optionally temporary tables.
249
250       sql_flags
251
252       Contains optional flags to instantiate the SQL::Parser parsing engine
253       when SQL::Statement is used as SQL engine. See SQL::Parser for valid
254       flags.
255
256   Driver private methods
257       Default DBI methods
258
259       data_sources
260
261       The "data_sources" method returns a list of subdirectories of the
262       current directory in the form "dbi:CSV:f_dir=$dirname".
263
264       If you want to read the subdirectories of another directory, use
265
266           my ($drh)  = DBI->install_driver ("CSV");
267           my (@list) = $drh->data_sources (f_dir => "/usr/local/csv_data" );
268
269       list_tables
270
271       This method returns a list of file names inside $dbh->{f_dir}.
272       Example:
273
274           my ($dbh)  = DBI->connect ("dbi:CSV:f_dir=/usr/local/csv_data");
275           my (@list) = $dbh->func ("list_tables");
276
277       Note that the list includes all files contained in the directory, even
278       those that have non-valid table names, from the view of SQL.
279
280       Additional methods
281
282       The following methods are only available via their documented name when
283       DBD::File is used directly. Because this is only reasonable for testing
284       purposes, the real names must be used instead. Those names can be
285       computed by replacing the "f_" in the method name with the driver
286       prefix.
287
288       f_versions
289
290       Signature:
291
292           sub f_versions (;$)
293           {
294               my ($table_name) = @_;
295               $table_name ||= ".";
296               ...
297           }
298
299       Returns the versions of the driver, including the DBI version, the Perl
300       version, DBI::PurePerl version (if DBI::PurePerl is active) and the
301       version of the SQL engine in use.
302
303           my $dbh = DBI->connect ("dbi:File:");
304           my $f_versions = $dbh->f_versions ();
305           print "$f_versions\n";
306           __END__
307           # DBD::File        0.39 using SQL::Statement 1.28
308           # DBI              1.612
309           # OS               netbsd (5.99.24)
310           # Perl             5.010001 (x86_64-netbsd-thread-multi)
311
312       Called in list context, f_versions will return an array containing each
313       line as single entry.
314
315       Some drivers might use the optional (table name) argument and modify
316       version information related to the table (e.g. DBD::DBM provides
317       storage backend information for the requested table, when it has a
318       table name).
319
320       f_get_meta
321
322       Signature:
323
324           sub f_get_meta ($$)
325           {
326               my ($table_name, $attrib) = @_;
327               ...
328           }
329
330       Returns the value of a meta attribute set for a specific table, if any.
331       See f_meta for the possible attributes.
332
333       A table name of "." (single dot) is interpreted as the default table.
334       This will retrieve the appropriate attribute globally from the dbh.
335       This has the same restrictions as "$dbh->{$attrib}".
336
337       f_set_meta
338
339       Signature:
340
341           sub f_set_meta ($$$)
342           {
343               my ($table_name, $attrib, $value) = @_;
344               ...
345           }
346
347       Sets the value of a meta attribute set for a specific table.  See
348       f_meta for the possible attributes.
349
350       A table name of "." (single dot) is interpreted as the default table
351       which will set the specified attribute globally for the dbh.  This has
352       the same restrictions as "$dbh->{$attrib} = $value".
353
354       f_clear_meta
355
356       Signature:
357
358           sub f_clear_meta ($)
359           {
360               my ($table_name) = @_;
361               ...
362           }
363
364       Clears the table specific meta information in the private storage of
365       the dbh.
366

SQL ENGINES

368       DBD::File currently supports two SQL engines: SQL::Statement and
369       DBI::SQL::Nano::Statement_. DBI::SQL::Nano supports a very limited
370       subset of SQL statements, but it might be faster for some very simple
371       tasks. SQL::Statement in contrast supports a much larger subset of ANSI
372       SQL.
373
374       To use SQL::Statement, you need at least version 1.28 of SQL::Statement
375       and the environment variable "DBI_SQL_NANO" must not be set to a true
376       value.
377

KNOWN BUGS AND LIMITATIONS

379       ·   This module uses flock () internally but flock is not available on
380           all platforms. On MacOS and Windows 95 there is no locking at all
381           (perhaps not so important on MacOS and Windows 95, as there is only
382           a single user).
383
384       ·   The module stores details about the handled tables in a private
385           area of the driver handle ($drh). This data area is not shared
386           between different driver instances, so several "DBI->connect ()"
387           calls will cause different table instances and private data areas.
388
389           This data area is filled for the first time when a table is
390           accessed, either via an SQL statement or via "table_info" and is
391           not destroyed until the table is dropped or the driver handle is
392           released.  Manual destruction is possible via f_clear_meta.
393
394           The following attributes are preserved in the data area and will
395           evaluated instead of driver globals:
396
397           f_ext
398           f_dir
399           f_lock
400           f_lockfile
401           f_encoding
402           f_schema
403           col_names
404           sql_identifier_case
405
406           The following attributes are preserved in the data area only and
407           cannot be set globally.
408
409           f_file
410
411           The following attributes are preserved in the data area only and
412           are computed when initializing the data area:
413
414           f_fqfn
415           f_fqbn
416           f_fqln
417           table_name
418
419           For DBD::CSV tables this means, once opened "foo.csv" as table
420           named "foo", another table named "foo" accessing the file "foo.txt"
421           cannot be opened.  Accessing "foo" will always access the file
422           "foo.csv" in memorized "f_dir", locking "f_lockfile" via memorized
423           "f_lock".
424
425           You can use f_clear_meta or the "f_file" attribute for a specific
426           table to work around this.
427
428       ·   When used with SQL::Statement and temporary tables e.g.,
429
430             CREATE TEMP TABLE ...
431
432           the table data processing bypasses DBD::File::Table. No file system
433           calls will be made and there are no clashes with existing (file
434           based) tables with the same name. Temporary tables are chosen over
435           file tables, but they will not covered by "table_info".
436

AUTHOR

438       This module is currently maintained by
439
440       H.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack  < rehsack
441       at googlemail.com >
442
443       The original author is Jochen Wiedmann.
444

COPYRIGHT AND LICENSE

446        Copyright (C) 2009-2010 by H.Merijn Brand & Jens Rehsack
447        Copyright (C) 2004-2009 by Jeff Zucker
448        Copyright (C) 1998-2004 by Jochen Wiedmann
449
450       All rights reserved.
451
452       You may freely distribute and/or modify this module under the terms of
453       either the GNU General Public License (GPL) or the Artistic License, as
454       specified in the Perl README file.
455