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

KNOWN BUGS AND LIMITATIONS

345       ·   This module uses flock () internally but flock is not available on
346           all platforms. On MacOS and Windows 95 there is no locking at all
347           (perhaps not so important on MacOS and Windows 95, as there is only
348           a single user).
349
350       ·   The module stores details about the handled tables in a private
351           area of the driver handle ($drh). This data area is not shared
352           between different driver instances, so several "DBI->connect ()"
353           calls will cause different table instances and private data areas.
354
355           This data area is filled for the first time when a table is
356           accessed, either via an SQL statement or via "table_info" and is
357           not destroyed until the table is dropped or the driver handle is
358           released.  Manual destruction is possible via f_clear_meta.
359
360           The following attributes are preserved in the data area and will
361           evaluated instead of driver globals:
362
363           f_ext
364           f_dir
365           f_lock
366           f_lockfile
367           f_encoding
368           f_schema
369           col_names
370           sql_identifier_case
371
372           The following attributes are preserved in the data area only and
373           cannot be set globally.
374
375           f_file
376
377           The following attributes are preserved in the data area only and
378           are computed when initializing the data area:
379
380           f_fqfn
381           f_fqbn
382           f_fqln
383           table_name
384
385           For DBD::CSV tables this means, once opened "foo.csv" as table
386           named "foo", another table named "foo" accessing the file "foo.txt"
387           cannot be opened.  Accessing "foo" will always access the file
388           "foo.csv" in memorized "f_dir", locking "f_lockfile" via memorized
389           "f_lock".
390
391           You can use f_clear_meta or the "f_file" attribute for a specific
392           table to work around this.
393
394       ·   When used with SQL::Statement and temporary tables e.g.,
395
396             CREATE TEMP TABLE ...
397
398           the table data processing bypasses DBD::File::Table. No file system
399           calls will be made and there are no clashes with existing (file
400           based) tables with the same name. Temporary tables are chosen over
401           file tables, but they will not covered by "table_info".
402

AUTHOR

404       This module is currently maintained by
405
406       H.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack < rehsack at
407       googlemail.com >
408
409       The original author is Jochen Wiedmann.
410

COPYRIGHT AND LICENSE

412        Copyright (C) 2009-2013 by H.Merijn Brand & Jens Rehsack
413        Copyright (C) 2004-2009 by Jeff Zucker
414        Copyright (C) 1998-2004 by Jochen Wiedmann
415
416       All rights reserved.
417
418       You may freely distribute and/or modify this module under the terms of
419       either the GNU General Public License (GPL) or the Artistic License, as
420       specified in the Perl README file.
421

NAME

SYNOPSIS

DESCRIPTION

KNOWN BUGS AND LIMITATIONS

AUTHOR

COPYRIGHT AND LICENSE

SEE ALSO