NAME

Xbase - Perl Module to Read Xbase DBF Files and Foxpro IDX indexes

ABSTRACT

This is a perl module to access xbase files with simple IDX indexes. At the moment only read access to the files are provided by this package Writing is tougher with IDX updates etc and is being worked on. Since the read functionality is useful in itself this version is being released.

INSTALLATION

To install this package, change to the directory where this file is present and type

perl Makefile.PL
make
make install

This will copy Xbase.pm to the perl library directory provided you have the permissions to do so. To use the module in your programs you will use the line:

use Xbase;

If you cannot install it in the system directory, put it whereever you like and tell perl where to find it by using the following in the beginning of your script:

BEGIN {
	unshift(@INC,'/usr/underprivileged/me/lib');
}
use Xbase;

DESCRIPTION

The various methods that are supported by this module are given below. There is a very distinct xbase like flavour to most of the commands.

CREATING A NEW XBASE OBJECT:

$database = new Xbase;

This will create an object $database that will be used to interact with the various methods the module provides.

OPENING A DATABASE

$database->open_dbf($dbf_name, $idx_name);

Associates the DBF file and optionally the IDX file with the object. It opens the files and if a associated MEMO file is present automatically opens it. Only Foxpro Memo files are currently supported and assumes the same filename as the DBF with a FPT extension.

DATABASE TYPE

print $database->dbf_type;

Returns a string telling you if the xbase file opened is DBF3, DBF4 or FOX

LAST UPDATE DATE

print $database->last_update;

Returns a date string telling you when the database was last updated.

LAST RECORD NUMBER

$end=$database->lastrec;

Returns the record number of the last record in the database file.

DATABASE STATUS INFORMATION

$database->dbf_stat;

This prints out on to STDOUT a display of the status/structure of the database. It is similar to the xbase command DISPLAY STATUS. Since it prints field names and structure it is commonly used to see if the module is reading the database as intended and finding out the field names.

INDEX FILE STATUS INFORMATION

$database->idx_stat;

Prints on to STDOUT the status information of an open IDX file.

GO TOP

$database->go_top;

Moves the record pointer to the top of the database. Physical top of database if no index is present else first record according to index order.

GO BOTTOM

$database->go_bottom;

Moves the record pointer to the bottom of the database. Physical bottom of database if no index is present else last record according to index order.

GO NEXT

$database->go_next;

Equivalent to the xbase command SKIP 1 which moves the record pointer to the next record.

GO PREVIOUS

$database->go_prev;

Equivalent to the xbase command SKIP -1 which moves the record pointer to the previous record.

SEEK

$stat=$database->seek($keyvalue);

This command positions the record pointer on the first matching record that has the key value specified. The database should be opened with an associated index. Seek without an available index will print an error message and abort. The return value indicates whether the key value was found or not.

RECORD NUMBER

$current_rec=$database->recno;

Returns the record number that the record pointer is currently at.

BEGINNING OF FILE

if ($database->bof) {
	print "At the very top of the file \n";
}

Tells you whether you are at the beginning of the file. Like in xbase it is not true when you are at record number one but rather it is set when you try to $database->go_prev when you are at the top of the file.

END OF FILE

if ($database->eof) {
	print "At the very end of the file \n";
}

Tells you whether you are at the end of the file. Like in xbase it is not true when you are at the last record but rather it is set when you try to $database->go_next from the last record.

READ INDIVIDUAL FIELD VALUES

print $database->get_field("NAME");

Returns as a string the contents of a field name specified from the current record. Using the pseudo field name _DELETED will tell you if the current record is marked for deletion.

READ FIELD VALUES INTO ARRAY

@fields = $database->get_record;

Returns as an array all the fields from the current record. The fields are in the same order as in the database.

CLOSE DATABASE

$database->close_dbf;

This closes the database files, index files and memo files that are associated with the $database object with $database->open_dbf

COPYRIGHT

Copyright (c) 1995 Pratap Pereira. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

I request that if you use this module at a web site to make a link to

http://eewww.eng.ohio-state.edu/~pereira/software/xbase/

This is just so that others might find it. This is however not required of you.

AUTHOR INFORMATION

Please send your comments, suggestions, gripes, bug-reports to

Pratap Pereira
pereira@ee.eng.ohio-state.edu

UPDATE HISTORY

Original perl 4 script done in March 1994
Perl 5 module done in February 1995
RELEASE 2 was first public release now called xbase12.pm
RELEASE 3 was done 6/22/95 called xbase13.pm
	Fixed problem with GO_PREV & GO_NEXT after SEEK.
	Fixed problem with parsing headers of dbfs with 
        record length > 255.
	Added Memo file support.
RELEASE 4 was done 9/29/95
	Fixed problem with certain IDX failing completely, 
        was a stupid
	indexing mistake.
RELEASE 5 was done 11/14/95 (called xbase.pm 1.05)
	Fixed field length inconsistency errors by changing 
        way header is decoded. Should work with more xbase 
        variants. (Dick Sutton & Andrew Vasquez)
Version 1.06 was done 11/17/95
Added binmode command to file handles to support 
Windows NT 
Version 1.07 was done 01/23/96
	Made documentation in pod format, installation 
        automated. Fixed problem with deleted status being 
        improperly read (Chung Huynh). Renamed to Xbase 
        (previously xbase) to be consistent with other perl
        modules. Released in CPAN.
	Prettied up dbf_stat output (Gilbert Ramirez).    

CREDITS

Thanks are due to Chung Huynh (chuynh@nero.finearts.uvic.ca), Jim Esposito (jgespo@exis.net), Dick Sutton (suttond@federal.unisys.com), Andrew Vasquez (praka@ophelia.fullcoll.edu), Leonard Samuelson (lcs@synergy.smartpages.com) and Gilbert Ramirez Jr (gram@merece.uthscsa.edu)