/ 
DBD-XBase-0.032
River stage one • 4 direct dependents • 6 total dependents
/ XBase

NAME

XBase - Perl module for reading and writing the dbf files

SYNOPSIS

use XBase;
my $table = new XBase("dbase.dbf");
for (0 .. $table->last_record())
	{
	my ($deleted, $id, $msg)
		= $table->get_record($_, "ID", "MSG");
	print "$id:\t$msg\n" unless $deleted;
	}

DESCRIPTION

This module can read and write XBase database file, known as dbf in dBase and FoxPro world. It also reads memo (and the like) fields from the dbt files, if needed. This module should really be used via DBD::XBase DBI driver, but this is the alternative interface. Note for now: no real DBD:: support currently exists.

Remember: Since the version number is pretty low now, you might want to check the CHANGES file any time you upgrade to see wheather some of the features you use haven't disappeared.

WARNING for now: It doesn't support any index files at the present time! That means if you change your dbf, your idx&mdx (if you have any) will not match. So do not do that.

The following methods are supported:

General methods

new

Creates the XBase object, takes the file's name as argument, parses the file's header, fills the data structures.

close

Closes the object/file.

create

Creates new database file. Expects class name and hash of options, containing at least name and references to lists field_names, field_types, field_lengths and field_decimals.

You can also pass reference to XBase object instead of class name (and then can omit the other field_* attributes) and the new table will have the same structure (fields) as the original object.

BUG: currently will not create .dbt file for you.

last_record

Number of the last record in the file. The lines deleted but present in the file are included in this number.

last_field

Number of the last field in the file, number of fields minus 1.

field_names, field_types, field_lengths, field_decimals

List of field names and so for the dbf file.

When dealing with the records, you always have to specify the number of the record in the file. The range is 0 .. $table->last_record().

Reading the data

get_record

Returns a list of data from the specified record (line of the table). The first argument is the number of the record. If there are any other arguments, they are considered to be the names of the fields and only the specified fields are returned. If no field names are present, returns all fields in the record. The first value of the returned list is the 1/0 value saying if the record is deleted or not.

get_record_as_hash

Returns hash (in list context) or reference to hash (scalar), where keys are the field names of the record and values the values. The deleted flag has name _DELETED.

Writing the data

set_record

As arguments, takes the number of the record and the list of values of the fields. It writes the record to the file. Unspecified fields (if you pass less than you should) are set to undef/empty. The record is undeleted.

set_record_hash

Takes number of the record and hash, sets the fields, unspecified are undeffed/emptied. The record is undeleted.

update_record_hash

Like write_record_hash but preserves fields that do not have value specified in the hash. The record is undeleted.

delete_record, undelete record

Deletes/undeletes the record.

Errors and debugging

If the method fails (returns undef of null list), the error message can be retrieved via errstr method. If the new method fails, you have no object and so new (and only new) puts the error message into the $XBase::errstr variable.

The methods get_header_info and dump_records can be used to quickly view the content of the file, at least for now. Please speak up if you like them and want them to be supported. They are here mainly for my debugging purposes.

Module XBase::Base(3) defines some basic functionality and also following variables, that affect the internal behaviour:

$DEBUG

Enables error messages on stderr.

$FIXPROBLEMS

When reading the file, try to continue, even if there is some (minor) missmatch in the data.

In the module XBase there is variable $CLEARNULLS which if true, will make the reading methods cuts off spaces and nulls from the end of character fields on read.

LITTLE EXAMPLE

This is a code to update field MSG in record where ID is 123.

use XBase;
my $table = new XBase("test.dbf");
die $XBase::errstr unless defined $table;
for (0 .. $table->last_record())
	{
	my ($deleted, $id)
		= $table->get_record($_, "ID");
	die $table->errstr unless defined $deleted;
	next if $deleted;
	if ($id == 123)
		{
		$table->update_record_hash($_,
			"MSG" => "New message");
		last;
		}
	}

MEMO FIELDS and INDEX FILES

If there is a memo field in the dbf file, the module tries to open file with the same name but extension .dbt. It uses module XBase::Memo(3) for this. It reads and writes this memo field transparently (ie you do not know about it).

Quiz question: can there be more than one memo field in the dbf file? In what file (.dbt?) should I search for their values? Any ideas?

No index files are currently supported. Two reasons: you do not need them when reading the file because you specify the record number anyway and writing them is extremely difficult. I will try to add the support but do not promise anything ;-) There are too many too complex questions: how about compound indexes? Which index formats should I support? What files contain the index data? I do not have dBase nor Fox* so do not have data to experiment. Send me anything that might help.

Any ideas, suggestions, URLs, help or code? Please write me, I am writing this module for you.

INTERFACE

Would you like different interface in the module? Write me, we shall figure something out.

HISTORY

I have been using the Xbase(3) module by Pratap Pereira for quite a time to read the dbf files, but it had no writing capabilities, it was not use strict clean and the author did not support the module behind the version 1.07. So I started to make my own patches and thought it would be nice if other people could make use of them. I thought about taking over the development of the original Xbase package, but the interface seemed rather complicated to me and I also disliked the licence Pratap had about the module.

So with the help of article XBase File Format Description by Erik Bachmann, URL http://www.geocities.com/SiliconValley/Pines/2563/xbase.htm, I have written a new module. It doesn't use any code from Xbase-1.07 and you are free to use and distribute it under the same terms as Perl itself.

Please send all bug reports CC'ed to my e-mail, since I might miss your post in c.l.p.misc or dbi-users (or other groups). Any comments from both Perl and XBase gurus are welcome, since I do neither use dBase nor Fox*, so there are probably pieces missing.

VERSION

0.032

AUTHOR

(c) Jan Pazdziora, adelton@fi.muni.cz

SEE ALSO

perl(1); DBD::XBase(3) and DBI(3) for DBI interface; XBase::Base(3) and DBD::Memo(3) for internal details