|
NAMEXBase - Perl module for reading and writing the dbf filesSYNOPSISuse XBase; my $table = new XBase "dbase.dbf" or die XBase->errstr; for (0 .. $table->last_record) { my ($deleted, $id, $msg) = $table->get_record($_, "ID", "MSG"); print "$id:\t$msg\n" unless $deleted; } DESCRIPTIONThis module can read and write XBase database files, known as dbf in dBase and FoxPro world. It also reads memo fields from the dbt and fpt files, if needed. An alpha code of reading index support for ndx, ntx, mdx, idx and cdx is available for testing -- see the DBD::Index(3) man page. Module XBase provides simple native interface to XBase files. For DBI compliant database access, see the DBD::XBase and DBI modules and their man pages.The following methods are supported by XBase module: General methods
Reading the data one by oneWhen dealing with the records one by one, reading or writing (the following six methods), you have to specify the number of the record in the file as the first argument. The range is "0 .. $table->last_record".
Writing the dataAll three writing methods always undelete the record. On success they return true -- the record number actually written.
To explicitely delete/undelete a record, use methods delete_record or undelete_record with record number as a parameter. Assorted examples of reading and writing: my @data = $table->get_record(3, "jezek", "krtek"); my $hashref = $table->get_record_as_hash(38); $table->set_record_hash(8, "jezek" => "jezecek", "krtek" => 5); $table->undelete_record(4); This is a code to update field MSG in record where ID is 123. use XBase; my $table = new XBase "test.dbf" or die XBase->errstr; for (0 .. $table->last_record) { my ($deleted, $id) = $table->get_record($_, "ID") die $table->errstr unless defined $deleted; next if $deleted; $table->update_record_hash($_, "MSG" => "New message") if $id == 123; } Sequentially reading the fileIf you plan to sequentially walk through the file, you can create a cursor first and then repeatedly call fetch to get next record.
Prepare will return object cursor, the following method are methods of the cursor, not of the table.
Examples of using cursors: my $table = new XBase "names.dbf" or die XBase->errstr; my $cursor = $table->prepare_select("ID", "NAME", "STREET"); while (my @data = $cursor->fetch) { ### do something here, like print "@data\n"; } my $table = new XBase "employ.dbf"; my $cur = $table->prepare_select_with_index("empid.ndx"); ## my $cur = $table->prepare_select_with_index( ["empid.cdx", "ADDRES", "char"], "id", "address"); $cur->find_eq(1097); while (my $hashref = $cur->fetch_hashref and $hashref->{"ID"} == 1097) { ### do something here with $hashref } The second example shows that after you have done find_eq, the fetches continue untill the end of the index, so you have to check whether you are still on records with given value. And if there is no record with value 1097 in the indexed field, you will just get the next record in the order. The updating example can be rewritten to: use XBase; my $table = new XBase "test.dbf" or die XBase->errstr; my $cursor = $table->prepare_select("ID") while (my ($id) = $cursor->fetch) { $table->update_record_hash($cursor->last_fetched, "MSG" => "New message") if $id == 123 } Dumping the content of the fileA method get_all_records returns reference to an array containing array of values for each undeleted record at once. As parameters, pass list of fields to return for each record.To print the content of the file in a readable form, use method dump_records. It prints all not deleted records from the file. By default, all fields are printed, separated by colons, one record on a row. The method can have parameters in a form of a hash with the following keys:
Example of use is use XBase; my $table = new XBase "table" or die XBase->errstr; $table->dump_records("fs" => " | ", "rs" => " <-+\n", "fields" => [ "id", "msg" ]);' Also note that there is a script dbfdump(1) that does the printing. Errors and debuggingIf the method fails (returns false or null list), the error message can be retrieved via errstr method. If the new or create method fails, you have no object so you get the error message using class syntax "XBase->errstr()".The method header_info returns (not prints) string with information about the file and about the fields. Module XBase::Base(3) defines some basic functions that are inherited by both XBase and XBase::Memo(3) module. DATA TYPESThe character fields are returned "as is". No charset or other translation is done. The numbers are converted to Perl numbers. The date fields are returned as 8 character string of the 'YYYYMMDD' form and when inserting the date, you again have to provide it in this form. No checking for the validity of the date is done. The datetime field is returned in the number of (possibly negative) seconds since 1970/1/1, possibly with decimal part (since it allows precision up to 1/1000 s). To get the fields, use the gmtime (or similar) Perl function.If there is a memo field in the dbf file, the module tries to open file with the same name but extension dbt, fpt or smt. It uses module XBase::Memo(3) for this. It reads and writes this memo field transparently (you do not know about it) and returns the data as single scalar. INDEX, LOCKSNew: A support for ndx, ntx, mdx, idx and cdx index formats is available with alpha status for testing. Some of the formats are already rather stable (ndx). Please read the XBase::Index(3) man page and the eg/use_index file in the distribution for examples and ideas. Send me examples of your data files and suggestions for interface if you need indexes.General locking methods are locksh, lockex and unlock for shared lock, exclusive lock and unlock. They call flock but you can redefine then in XBase::Base package. INFORMATION SOURCEThis module is built using information from and article XBase File Format Description by Erik Bachmann, URLhttp://www.clicketyclick.dk/databases/xbase/format/ Thanks a lot. VERSION1.08AVAILABLE FROMhttp://www.adelton.com/perl/DBD-XBase/AUTHOR(c) 1997--2017 Jan Pazdziora.All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Contact the author at jpx dash perl at adelton dot com. THANKSMany people have provided information, test files, test results and patches. This project would not be so great without them. See the Changes file for (I hope) complete list. Thank you all, guys!Special thanks go to Erik Bachmann for his great page about the file structures; to Frans van Loon, William McKee, Randy Kobes and Dan Albertsson for longtime cooperation and many emails we've exchanged when fixing and polishing the modules' behaviour; and to Dan Albertsson for providing support for the project. SEE ALSOperl(1); XBase::FAQ(3); DBD::XBase(3) and DBI(3) for DBI interface; dbfdump(1)
Visit the GSP FreeBSD Man Page Interface. |