view release on metacpan or  search on metacpan

new-XBase  view on Meta::CPAN

=head1 NAME

XBase - Perl module for reading and writing the dbf files

=head1 POZOR!

This is suggestion for new interface. Not current documentation,
see normal perldoc XBase.

=head1 SYNOPSIS

  use 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;
  }

  $table->{'RaiseError'} = 1;			# new
  my $cur = $table->prepare_select_with_index("dbaseid.ndx",
  	"id", "msg");
  $cur->find_eq(156) or do {
  	print "Value 156 not found.\n"; exit;
  };
  my ($id, $msg) = $cur->fetch;


=head1 DESCRIPTION

This module can read and write XBase database files, known as dbf in
dBase and FoxPro world. It also transparently reads memo fields from
the dbt, fpt and smt files and works with index files (ndx, ntx, mdx, idx,
cdx and SDBM). This module XBase.pm provides simple native interface
to XBase files. For DBI compliant database access, see DBD::XBase and
DBI modules and their man pages.

To work with dbf and associated files, you first need to open the
dbf file using

    my $table = new XBase 'dbase.dbf' or die XBase->errstr;

type of call. This gives you an object to interact with the table.
You can then access the records using their position in the file

    my ($deleted, $id, $name, $born)
    	= $table->get_record($num, 'ID', 'NAME', 'DO_BIRTH');
    if ($id == 436) {
    	$table->update_record_hash($num, 'NAME' => 'Peter')
    }

or via cursors that allow you to walk through the file

    my $cur = $table->prepare_select('ID', 'NAME', 'DO_BIRTH');
    while (my ($id, $name, $born) = $cur->fetch) {
		# do some work
    }

If there are index files for given table, they can be used to speedup
the searches. You can either use them explicitely to open cursor based
on the index

    my $cur = $table->prepare_select_with_index('dbaseid.ndx'
    	'ID', 'NAME', 'DO_BIRTH');
    if ($cur->find_eq(436)) {
    	my ($id, $name, $born) = $cur->fetch;
    }

or you can attach the indexes to the table and they will be used when
needed and also updated when the dbf table changes

    my $table = new XBase 'file' => 'dbase.dbf', 'RaiseError' => 1,
    	'index' => [ 'dbaseid.ndx', 'dbasename.ndx' ];
    my $cur = $table->prepare_select_where('id = 436', 'NAME');
    while (my ($name) = $cur->fetch) {
    	print "Old value $name, new value 'Peter'\n";
    	$table->update_record_hash($cur->last_fetched,
    		'name' => 'Peter');
    }

The cdx, mdx and SDBM index files (with the same base name as the dbf)
are attached by default.

=head1 LIST OF METHODS

The following methods are available for XBase.pm tables and their
cursors, their meaning and parameters are in more detail described
below:

=over 4

=item General methods working with the table

	new			close
	create			drop
	attach_index
	pack			errstr

=item Methods returning information about the file

	last_record		field_names
	last_field		field_types
	header_info		field_lengths
	field_type		field_decimals
	field_length
	field_decimal

=item Accessing and modifying the records

	get_record		set_record
	get_record_nf		set_record_hash
	get_record_as_hash	update_record_hash
	get_all_records		delete_record
	dump_records		undelete_record

=item Creating cursors and working with them

	prepare_select			fetch
	prepare_select_with_index	fetch_hashref
	prepare_select_where		last_fetched
					find_eq
					cursor_uses_index

=back

=head1 General methods

The general methods working with the whole files or tables.

=head2 new

Opens the existing dbf file and provides an object to interact with
the table. Memo and index files are also opened transparently. If opening
of the dbf file or any other needed file (memo, index) fails, C<new>
returns undef and the error message may be retrieved via
B<XBase-E<gt>errstr>.

The parameters to B<new> are passed as hash:

=over 4

=item name

Name of the dbf file (dbf table). The C<.dbf> suffix may be omitted.
The name of the file may also be passed as the very first single
parameter.

=item memofile

Specifies non standard name for the associated memo file.
By default it's the name of the dbf file, with suffix C<.dbt>,
C<.fpt> or C<.smt>.

=item ignorememo

Makes B<new> and all subsequent operation to ignore memo file at all.
This is usefull if you've lost the dbt file and you do not need it.
The default is undef, not ignoring the memo file.

=item memosep

Separator of memo records in the dBase III memo files. The
standard says it should be C<"\x1a\x1a">. There are however
implementations that only put in one C<"\x1a">. XBase.pm tries hard to
guess which is the case for your dbt but if it fails, you can tell it
yourself.

=item nolongchars

Prevents B<new> to treat the decimal value of character
fields as high byte of the length -- there are some broken products
around producing character fields with decimal values set. XBase.pm
tries hard to guess which is the case for your dbf, so again you need
this option only if it fails.

=item index

Name of arrayref of names of index files to attach to the opened
object. The cdx, mdx and SDBM indexes are attached by default.

=item noindex

Prevents any index file to be attached automatically (cdx, mdx,
SDBM). Default is undef.

=item PrintError

If the B<new> or any subsequent call to the object fail, they
generate a warning using warn. The default is undef (but future
versions may default to 1).

=item RaiseError

new-XBase  view on Meta::CPAN

    $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;
    	}

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"], "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 B<find_eq>, the
B<fetch>es 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	
	}

=head1 DATA TYPES

The 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 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
normal scalar.

=head1 INFORMATION SOURCE

This module is built using information from and article XBase File
Format Description by Erik Bachmann, URL

	http://www.clicketyclick.dk/databases/xbase/format/

Thanks a lot.

=head1 VERSION

1.00

=head1 AUTHOR

(c) 1997--2011 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.

=head1 THANKS

Many 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!

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 module's behaviour; and to
Dan Albertsson for providing support for the project.

=head1 SEE ALSO

XBase::FAQ(3); XBase::Index(3);
DBD::XBase(3) and DBI(3) for DBI interface;
dbfdump(1); perl(1)

=cut