NAME

CAM::DBF - Perl extension for reading and writing dBASE III DBF files

LICENSE

Copyright 2005 Clotho Advanced Media, Inc., <cpan@clotho.com>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Please see the XBase modules on CPAN for more complete implementations of DBF file reading and writing. This module differs from those in that it is designed to be error-correcting for corrupted DBF files, and is (IMHO) simpler to use.

SYNOPSIS

use CAM::DBF;
my $dbf = new CAM::DBF($filename);

# Read routines:

print join("|", $dbf->fieldnames()),"\n";
for my $row (0 .. $dbf->nrecords()-1) {
   print join("|", $dbf->fetchrow_array($row)),"\n";
}

my $row = 100;
my $hashref = $dbf->fetchrow_hashref($row);
my $arrayref = $dbf->fetchrow_hashref($row);

# Write routines:

$dbf->delete($row);
$dbf->undelete($row);

DESCRIPTION

This package facilitates reading dBASE III PLUS DBF files. This is made possible by documentation generously released by Borland at:

http://community.borland.com/article/0%2C1410%2C15838%2C00.html

Currently, only version III PLUS files are readable. Support has not yet been added for dBASE version IV or 5.0 files.

This library also supports writing dBASE files, but the writing interface is not as polished as the reading interface.

CLASS METHODS

new FILENAME

new FILENAME, MODE

new FILENAME, MODE, KEY => VALUE, KEY => VALUE, ...

Open and read a dBASE file. The optional mode parameter defaults to "r" for readonly. If you plan to append to the DBF, open it as "r+".

Additional behavior flags can be passed after the file mode. Available flags are:

ignoreHeaderBytes => 0|1 (default 0)
    looks for the 0x0D end-of-header marker instead of trusting the 
    stated header length
allowOffByOne => 0|1 (default 0)
    only matters if ignoreHeaderBytes is on.  If the computed header
    size differs from the declared header size by one byte, use the
    latter.
verbose => 0|1 (default 0)
    print warning messages about header problems, or stay quiet

create FILENAME, [FLAGS,] COLUMN, COLUMN, ...

create FILENAME, FILEMODE, [FLAGS,] COLUMN, COLUMN, ...

Create a new DBF file in FILENAME, initially empty. The optional FILEMODE argument defaults to "w+". We can't think of any reason to use any other mode, but if you can think of one, go for it.

The column structure is specified as a list of hash references, each containing the fields: name, type, length and decimals. The name should be 11 characters or shorted. The type should be one of C, N, D, or L (for character, number, date or logical).

The optional flags are:

-quick => 0|1 (default 0) -- skips column format checking if set

Example:

my $dbf = CAM::DBF->create("new.dbf",
                           {name=>"id",
                            type=>"N", length=>8,  decimals=>0},
                           {name=>"lastedit",
                            type=>"D", length=>8,  decimals=>0},
                           {name=>"firstname",
                            type=>"C", length=>15, decimals=>0},
                           {name=>"lastname",
                            type=>"C", length=>20, decimals=>0},
                           );

validateColumns COLUMN, COLUMN, ...

Check an array of DBF columns structures for validity. Emits warnings and returns undef on failure.

INSTANCE METHODS

writeHeader

Write all of the DBF header data to the file. This truncates the file first.

appendrow_arrayref DATA_ARRAYREF

Add a new row to the end of the DBF file immediately. The argument is treated as a reference of fields, in order. The DBF file is altered as little as possible.

The record count is incremented but is *NOT* written to the file until the closeDB() method is called (for speed increase).

appendrows_arrayref ARRAYREF_DATA_ARRAYREFS

Add new rows to the end of the DBF file immediately. The argument is treated as a reference of references of fields, in order. The DBF file is altered as little as possible. The record count is incremented but is NOT written until the closeDB() method is called (for speed increase).

appendrow_hashref DATA_HASHREF

Just like appendrow_arrayref, except the incoming data is in a hash. The DBF columns are used to reorder the data. Missing values are converted to blanks.

appendrows_hashref ARRAYREF_DATA_HASHREF

Just like appendrows_arrayref, except the incoming data is in a hash. The DBF columns are used to reorder the data. Missing values are converted to blanks.

closeDB

Closes a DBF file after updating the record count. This is only necessary if you append new rows.

writeRecordNumber

Edits the DBF file to record the current value of nrecords(). This is useful after appending rows.

nfields

Return the number of columns in the data table.

fieldnames

Return a list of field header names.

fieldname COLUMN

Return a the title of the specified column. COLUMN can be a column name or number. Column numbers count from zero.

fieldtype COLUMN

Return the dBASE field type for the specified column. COLUMN can be a column name or number. Column numbers count from zero.

fieldlength COLUMN

Return the byte width for the specified column. COLUMN can be a column name or number. Column numbers count from zero.

fielddecimals COLUMN

Return the decimals for the specified column. COLUMN can be a column name or number. Column numbers count from zero.

nrecords

Return number of records in the file.

fetchrow_arrayref ROW

Return a record as a reference to an array of fields. Row numbers count from zero.

fetchrows_arrayref ROW COUNT

Return array ref of records as a reference to an array of fields. Row numbers start from zero and count is trimed if it excedes table limits

fetchrow_hashref ROW

Return a record as a reference to a hash of (field name => field value) pairs. Row numbers count from zero.

fetchrow_array ROW

Return a record as an array of fields. Row numbers count from zero.

delete ROW

Flags a row as deleted. This alters the DBF file immediately.

undelete ROW

Removes the deleted flag from a row. This alters the DBF file immediately.

toText [STARTROW,] [ENDROW,] [-ARG => VALUE, ...]

Return the contents of the file in an ascii character-separated representation. Possible arguments (with default values) are:

-field      =>  ','
-enclose    =>  '"'
-escape     =>  '\'
-record     =>  '\n'
-showheader => 0
-startrow   => 0
-endrow     => nrecords()-1

Alternatively, if the -arg switches are not used, the first two arguments are interpreted as:

toText(startrow,endrow)

Additional -arg switches are permitted after these. For example: print $dbf->toText(100,100,-field=>'\n',-record=>''); print $dbf->toText(300,-field=>'|');

computeRecordBytes

Useful primarily for debugging. Recompute the number of bytes needed to store a record.

computeHeaderBytes

Useful primarily for debugging. Recompute the number of bytes needed to store the header.

computeNumRecords

Useful primarily for debugging. Recompute the number of records in the file, given the header size, file size and bytes needed to store a record.

nHeaderBytes

Useful primarily for debugging. Returns the number of bytes for the file header. This date is read from the header itself, not computed.

nRecordBytes

Useful primarily for debugging. Returns the number of bytes for a record. This date is read from the header itself, not computed.

repairHeaderData

Test and fix corruption of the 'nrecords' and 'nrecordbytes' header fields. This does NOT alter the file, just the in-memory representation of the header metadata. Returns a boolean indicating whether header repairs were necessary.

AUTHOR

Clotho Advanced Media Inc., cpan@clotho.com

Primary developer: Chris Dolan