Debian Codegraph @

new-XBase

raw ◀ ▶
1 Debian patch touch this file
1
2 =head1 NAME
3
4 XBase - Perl module for reading and writing the dbf files
5
6 =head1 POZOR!
7
8 This is suggestion for new interface. Not current documentation,
9 see normal perldoc XBase.
10
11 =head1 SYNOPSIS
12
13 use XBase;
14 my $table = new XBase "dbase.dbf" or die XBase->errstr;
15 for (0 .. $table->last_record) {
16 my ($deleted, $id, $msg)
17 = $table->get_record($_, "ID", "MSG");
18 print "$id:\t$msg\n" unless $deleted;
19 }
20
21 $table->{'RaiseError'} = 1; # new
22 my $cur = $table->prepare_select_with_index("dbaseid.ndx",
23 "id", "msg");
24 $cur->find_eq(156) or do {
25 print "Value 156 not found.\n"; exit;
26 };
27 my ($id, $msg) = $cur->fetch;
28
29
30 =head1 DESCRIPTION
31
32 This module can read and write XBase database files, known as dbf in
33 dBase and FoxPro world. It also transparently reads memo fields from
34 the dbt, fpt and smt files and works with index files (ndx, ntx, mdx, idx,
35 cdx and SDBM). This module XBase.pm provides simple native interface
36 to XBase files. For DBI compliant database access, see DBD::XBase and
37 DBI modules and their man pages.
38
39 To work with dbf and associated files, you first need to open the
40 dbf file using
41
42 my $table = new XBase 'dbase.dbf' or die XBase->errstr;
43
44 type of call. This gives you an object to interact with the table.
45 You can then access the records using their position in the file
46
47 my ($deleted, $id, $name, $born)
48 = $table->get_record($num, 'ID', 'NAME', 'DO_BIRTH');
49 if ($id == 436) {
50 $table->update_record_hash($num, 'NAME' => 'Peter')
51 }
52
53 or via cursors that allow you to walk through the file
54
55 my $cur = $table->prepare_select('ID', 'NAME', 'DO_BIRTH');
56 while (my ($id, $name, $born) = $cur->fetch) {
57 # do some work
58 }
59
60 If there are index files for given table, they can be used to speedup
61 the searches. You can either use them explicitely to open cursor based
62 on the index
63
64 my $cur = $table->prepare_select_with_index('dbaseid.ndx'
65 'ID', 'NAME', 'DO_BIRTH');
66 if ($cur->find_eq(436)) {
67 my ($id, $name, $born) = $cur->fetch;
68 }
69
70 or you can attach the indexes to the table and they will be used when
71 needed and also updated when the dbf table changes
72
73 my $table = new XBase 'file' => 'dbase.dbf', 'RaiseError' => 1,
74 'index' => [ 'dbaseid.ndx', 'dbasename.ndx' ];
75 my $cur = $table->prepare_select_where('id = 436', 'NAME');
76 while (my ($name) = $cur->fetch) {
77 print "Old value $name, new value 'Peter'\n";
78 $table->update_record_hash($cur->last_fetched,
79 'name' => 'Peter');
80 }
81
82 The cdx, mdx and SDBM index files (with the same base name as the dbf)
83 are attached by default.
84
85 =head1 LIST OF METHODS
86
87 The following methods are available for XBase.pm tables and their
88 cursors, their meaning and parameters are in more detail described
89 below:
90
91 =over 4
92
93 =item General methods working with the table
94
95 new close
96 create drop
97 attach_index
98 pack errstr
99
100 =item Methods returning information about the file
101
102 last_record field_names
103 last_field field_types
104 header_info field_lengths
105 field_type field_decimals
106 field_length
107 field_decimal
108
109 =item Accessing and modifying the records
110
111 get_record set_record
112 get_record_nf set_record_hash
113 get_record_as_hash update_record_hash
114 get_all_records delete_record
115 dump_records undelete_record
116
117 =item Creating cursors and working with them
118
119 prepare_select fetch
120 prepare_select_with_index fetch_hashref
121 prepare_select_where last_fetched
122 find_eq
123 cursor_uses_index
124
125 =back
126
127 =head1 General methods
128
129 The general methods working with the whole files or tables.
130
131 =head2 new
132
133 Opens the existing dbf file and provides an object to interact with
134 the table. Memo and index files are also opened transparently. If opening
135 of the dbf file or any other needed file (memo, index) fails, C<new>
136 returns undef and the error message may be retrieved via
137 B<XBase-E<gt>errstr>.
138
139 The parameters to B<new> are passed as hash:
140
141 =over 4
142
143 =item name
144
145 Name of the dbf file (dbf table). The C<.dbf> suffix may be omitted.
146 The name of the file may also be passed as the very first single
147 parameter.
148
149 =item memofile
150
151 Specifies non standard name for the associated memo file.
152 By default it's the name of the dbf file, with suffix C<.dbt>,
153 C<.fpt> or C<.smt>.
154
155 =item ignorememo
156
157 Makes B<new> and all subsequent operation to ignore memo file at all.
158 This is usefull if you've lost the dbt file and you do not need it.
159 The default is undef, not ignoring the memo file.
160
161 =item memosep
162
163 Separator of memo records in the dBase III memo files. The
164 standard says it should be C<"\x1a\x1a">. There are however
165 implementations that only put in one C<"\x1a">. XBase.pm tries hard to
166 guess which is the case for your dbt but if it fails, you can tell it
167 yourself.
168
169 =item nolongchars
170
171 Prevents B<new> to treat the decimal value of character
172 fields as high byte of the length -- there are some broken products
173 around producing character fields with decimal values set. XBase.pm
174 tries hard to guess which is the case for your dbf, so again you need
175 this option only if it fails.
176
177 =item index
178
179 Name of arrayref of names of index files to attach to the opened
180 object. The cdx, mdx and SDBM indexes are attached by default.
181
182 =item noindex
183
184 Prevents any index file to be attached automatically (cdx, mdx,
185 SDBM). Default is undef.
186
187 =item PrintError
188
189 If the B<new> or any subsequent call to the object fail, they
190 generate a warning using warn. The default is undef (but future
191 versions may default to 1).
192
193 =item RaiseError
194
195 If the B<new> or any subsequent call to the object fail, they
196 raise an exception (die). The default is undef.
197
198 =back
199
200 Examples:
201
202 my $table = new XBase "table.dbf" or die XBase->errstr;
203
204 my $table = new XBase 'name' => 'table.dbf',
205 'index' => 'table.ndx', 'PrintError' => 1;
206
207 =head2 create
208
209 Creates new empty dbf file on disk; memo file will be also created
210 if the table contains some memo fields. Parameters to create are
211 passed as hash.
212
213 =over 4
214
215 =item name
216
217 Name of the new dbf file.
218
219 =back
220
221 You can call this method as method of another XBase object and then
222 you only need to pass B<name> value of the hash; the structure
223 (fields) of the new file will be the same as of the original object.
224
225 If you call B<create> using class name (XBase), you have to (besides
226 B<name>) also specify the structure of the file:
227
228 =over 4
229
230 =item field_names
231
232 Arrayref to list of field name.
233
234 =item field_types
235
236 Arrayref to list of field types, specified either by one letter
237 strings (C, N, L, D, ...) or by long versions (char, numeric,
238 date, ...)
239
240 =item field_lengths
241
242 Arrayref to list of field widths.
243
244 =item field_decimals
245
246 Arrayref to list of precissions, for numeric columns.
247
248 =item version
249
250 Force different version of the dbf or memo file. The default is
251 version of the source table (if you call B<create> on an object),
252 3 (dBase III compatible) otherwise.
253
254 =item memofile
255
256 Specify nonstandard memo file name or location.
257
258 =back
259
260 If you keep some value undefined, B<create> will make it into some
261 reasonable default. The new dbf file (nor memo file) mustn't exist
262 yet -- B<create> will not allow you to overwrite existing table.
263 Use B<drop> (or unlink) to delete it first.
264
265 my $newtable = $table->create("name" => "copy.dbf");
266
267 my $newtable = XBase->create("name" => "new.dbf",
268 "field_names" => [ "ID", "MSG" ],
269 "field_types" => [ "N", "C" ],
270 "field_lengths" => [ 6, 40 ],
271 "field_decimals" => [ 0, undef ]);
272
273 =head2 attach_index
274
275 The index file may be attached during the B<new> call or
276 additionally with this call.
277
278 =head2 pack
279
280 All records that were marked deleted in the table, will be purged from
281 the file. Effectively does a fresh copy to new file and then moves it
282 to original location, so is not aimed at efficiency. Also recreates
283 all attached index files.
284
285 =head2 close
286
287 Closes the object and associated memo file and attached index files,
288 no arguments.
289
290 =head2 drop
291
292 This method closes the table and deletes it on disk (including
293 associated memo file and attached index files, if there are any).
294
295 =head2 errstr
296
297 Called either as a class method (after B<new> or B<create>) or on
298 a table object, it returns error string describing the last error
299 of previous failed method call.
300
301 =head1 Information about dbf file
302
303 =head2 last_record
304
305 Returns number of the last record in the file. The records marked
306 deleted but present in the file are included in this number.
307
308 =head2 last_field
309
310 Returns number of the last field in the file, number of fields minus 1.
311
312 =head2 header_info
313
314 Returns string with formated information about the file and about
315 the fields.
316
317 =head2 field_names, field_types, field_lengths, field_decimals
318
319 Return list of field names and so on for the dbf file.
320
321 =head2 field_type, field_length, field_decimal
322
323 For a field name, returns the appropriate value. Returns undef if the
324 field doesn't exist in the table.
325
326 =head1 Accessing the records
327
328 When dealing with the records one by one, reading or writing, you have
329 to specify the number of the record in the file as the first argument.
330 The valid range is from 0 to C<$table-E<gt>last_record> and
331 C<$table-E<gt>last_record+1> to insert new record to the file.
332
333 =head2 get_record
334
335 Returns list of field values from the specified record. The first
336 parameter in the call is the number of the record. If you do not
337 specify any other parameters, all fields are returned in the same
338 order as they appear in the file. You can also put list of field
339 names after the record number and then only those will be returned.
340 The first value of the returned list is always the 1/0 C<_DELETED>
341 value saying whether the record is marked deleted or not, so
342 on success, B<get_record> never returns empty list.
343
344 =head2 get_record_as_hash
345
346 Like B<get_record>, but returns the values as hash (in list context)
347 or reference to hash (in scalar context) containing field values
348 indexed by field names. The name of the deleted flag is C<_DELETED>.
349 The field names are returned as uppercase.
350
351 =head2 get_record_nf
352
353 Like B<get_record> but instead if the names of the fields, you can
354 pass list of numbers of the fields to read.
355
356 =head2 get_all_records
357
358 Returns reference to an array containing array of values for each
359 undeleted record at once. As parameters, pass list of fields to
360 return for each record.
361
362 =head2 dump_records
363
364 Prints to currently selected filehandle all non-deleted records from
365 the file. By default, all fields are printed, separated by colons, one
366 record on a row. The method can have parameters in a form of a hash
367 with the following keys:
368
369 =over 4
370
371 =item rs
372
373 Record separator, string, newline by default.
374
375 =item fs
376
377 Field separator, string, one colon by default.
378
379 =item fields
380
381 Reference to a list of names of the fields to print. By default it's
382 undef, meaning all fields. You can also pass in scalar where the field
383 names are separated by commas, or by dashes to denote intervals.
384
385 =item undef
386
387 What to print for undefined (NULL) values, empty string by default.
388
389 =back
390
391 Example of use is
392
393 use XBase;
394 my $table = new XBase "table" or die XBase->errstr;
395 $table->dump_records("fs" => " | ", "rs" => " <-+\n",
396 "fields" => [ "id", "msg" ]);'
397
•398 Also note that there is a command line script dbf_dump(1) that does
399 the printing.
400
401 =head1 Writing the data
402
403 All three writing methods always undelete the record. On success they
404 return true -- the record number actually written.
405
406 =head2 set_record
407
408 As parameters, takes the number of the record and the list of values
409 of the fields. It writes the record to the file. Unspecified fields
410 (if you pass less than you should) are set to undef/empty.
411
412 =head2 set_record_hash
413
414 Takes number of the record and hash as parameters, sets the fields,
415 unspecified fields are undefed/emptied.
416
417 =head2 update_record_hash
418
419 Like B<set_record_hash> but fields that do not have value specified
420 in the hash retain their original value.
421
422 =head2 delete_record, undelete_record
423
424 Marks the specified record in the file deleted/undeleted.
425
426 =head1 Sequentially reading the file
427
428 If you plan to sequentially walk through the file, you can create
429 a cursor first and then repeatedly call B<fetch> to get next record.
430
431 =head2 prepare_select
432
433 Creates and returns an cursor to walk through the file.
434 As parameters, pass list of field names to return, by default all
435 fields.
436
437 =head2 prepare_select_with_index
438
439 The first parameter is the file name of the index file, the rest is
440 optional list of field names. For index types that can hold more
441 index structures in one file (have tags), instead of file name use
442 arrayref with the file name, the tag name and optionaly the index type
443 (at the moment, expressions are not supported, so XBase.pm won't be
444 able to determine type of the index unless you tell it).
445 The B<fetch> will then return records in the ascending order,
446 according to the index.
447
448 =head2 prepare_select_where
449
450 The first parameter is a string with boolean expression, the rest is
451 optional list of field names. The B<fetch>es on the returned cursor
452 will return only records matching the expression. If there are
453 attached index files, they may be used to speed the search.
454
455 The previous methods on the table object will return cursor object,
456 the following methods are to be called on the cursor, not on the
457 table.
458
459 =head2 fetch
460
461 Returns the fields of the next available undeleted record from the
462 cursor. The list thus doesn't contain the C<_DELETED> flag since you
463 are guaranteed that the record is not deleted.
464
465 =item fetch_hashref
466
467 Returns a hash reference of fields for the next undeleted record from
468 the cursor.
469
470 =item last_fetched
471
472 Returns the record number of the record last fetched.
473
474 =item find_eq
475
476 This only works with cursor created via B<prepare_select_with_index>
477 or B<prepare_select_where> that uses index. As a parameter it takes
478 the cursor value to find. It returns 1 if there is matching record,
479 or 0 otherwise.
480
481 If there is a match, the next B<fetch>es will fetch the records
482 matching, and continue with records greater than the specified value
483 (walk the index). If there isn't match, B<fetch> returns next greater
484 record.
485
486 =item cursor_uses_index
487
488 Returns true if the cursor created with B<prepare_select_where> uses
489 index.
490
491 =head1 EXAMPLES
492
493 Assorted examples of reading and writing:
494
495 my @data = $table->get_record(3, "jezek", "krtek");
496 my $hashref = $table->get_record_as_hash(38);
497 $table->set_record_hash(8, "jezek" => "jezecek",
498 "krtek" => 5);
499 $table->undelete_record(4);
500
501 This is a code to update field MSG in record where ID is 123.
502
503 use XBase;
504 my $table = new XBase "test.dbf" or die XBase->errstr;
505 for (0 .. $table->last_record) {
506 my ($deleted, $id) = $table->get_record($_, "ID")
507 die $table->errstr unless defined $deleted;
508 next if $deleted;
509 $table->update_record_hash($_, "MSG" => "New message")
510 if $id == 123;
511 }
512
513 Examples of using cursors:
514
515 my $table = new XBase "names.dbf" or die XBase->errstr;
516 my $cursor = $table->prepare_select("ID", "NAME", "STREET");
517 while (my @data = $cursor->fetch)
518 { ### do something here, like print "@data\n"; }
519
520 my $table = new XBase "employ.dbf";
521 my $cur = $table->prepare_select_with_index("empid.ndx");
522 ## my $cur = $table->prepare_select_with_index(
523 ["empid.cdx", "ADDRES"], "id", "address");
524 $cur->find_eq(1097);
525 while (my $hashref = $cur->fetch_hashref
526 and $hashref->{"ID"} == 1097)
527 { ### do something here with $hashref }
528
529 The second example shows that after you have done B<find_eq>, the
530 B<fetch>es continue untill the end of the index, so you have to check
531 whether you are still on records with given value. And if there is no
532 record with value 1097 in the indexed field, you will just get the
533 next record in the order.
534
535 The updating example can be rewritten to:
536
537 use XBase;
538 my $table = new XBase "test.dbf" or die XBase->errstr;
539 my $cursor = $table->prepare_select("ID")
540 while (my ($id) = $cursor->fetch) {
541 $table->update_record_hash($cursor->last_fetched,
542 "MSG" => "New message") if $id == 123
543 }
544
545 =head1 DATA TYPES
546
547 The character fields are returned "as is". No charset or other
548 translation is done. The numbers are converted to Perl numbers. The
549 date fields are returned as 8 character string of the 'YYYYMMDD' form
550 and when inserting the date, you again have to provide it in this
551 form. No checking for the validity of the date is done. The datetime
552 field is returned in the number of seconds since 1970/1/1, possibly
553 with decimal part (since it allows precision up to 1/1000 s). To get
554 the fields, use the gmtime (or similar) Perl function.
555
556 If there is a memo field in the dbf file, the module tries to open
557 file with the same name but extension dbt, fpt or smt. It uses module
558 XBase::Memo(3) for this. It reads and writes this memo field
559 transparently (you do not know about it) and returns the data as
560 normal scalar.
561
562 =head1 INFORMATION SOURCE
563
564 This module is built using information from and article XBase File
565 Format Description by Erik Bachmann, URL
566
567 http://www.clicketyclick.dk/databases/xbase/format/
568
569 Thanks a lot.
570
571 =head1 VERSION
572
573 1.00
574
575 =head1 AUTHOR
576
577 (c) 1997--2011 Jan Pazdziora.
578
579 All rights reserved. This package is free software; you can
580 redistribute it and/or modify it under the same terms as Perl itself.
581
582 =head1 THANKS
583
584 Many people have provided information, test files, test results and
585 patches. This project would not be so great without them. See the
586 Changes file for (I hope) complete list. Thank you all!
587
588 Special thanks go to Erik Bachmann for his great page about the
589 file structures; to Frans van Loon, William McKee, Randy Kobes and
590 Dan Albertsson for longtime cooperation and many emails we've
591 exchanged when fixing and polishing the module's behaviour; and to
592 Dan Albertsson for providing support for the project.
593
594 =head1 SEE ALSO
595
596 XBase::FAQ(3); XBase::Index(3);
597 DBD::XBase(3) and DBI(3) for DBI interface;
•598 dbf_dump(1); perl(1)
599
600 =cut
601