NAME

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

LICENSE

Copyright 2006 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. If you already know how to use DBI, then DBD::XBase will likely make you happier than this module.

I don't do much DBF work any longer, so updates to this module will be infrequent.

SYNOPSIS

  use CAM::DBF;
  my $dbf = CAM::DBF->new($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 and writing dBASE III PLUS DBF files. This is made possible by documentation generously released by Borland at http://community.borland.com/article/0,1410,15838,00.html

Currently, only version III PLUS files are readable. This module does not support dBASE version IV or 5.0 files. See XBase for better support.

CLASS METHODS

$pkg->new($filename)

$pkg->new($filename, $mode)

$pkg->new($filename, $mode, $key => $value, ...)

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

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

ignoreHeaderBytes => 0|1

Looks for the 0x0D end-of-header marker instead of trusting the stated header length. Default 0.

allowOffByOne => 0|1

Only matters if ignoreHeaderBytes is on. If the computed header size differs from the declared header size by one byte, use the latter. Default 0.

verbose => 0|1

Print warning messages about header problems, or stay quiet. Default 0.

$pkg->create($filename, [flags,] $column, $column, ...)

$pkg->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},
                              );

$pkg_or_self->validateColumns($column, $column, ...)

$self->validateColumns()

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

INSTANCE METHODS

$self->writeHeader()

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

$self->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).

$self->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).

$self->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.

$self->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.

$self->closeDB()

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

$self->writeRecordNumber()

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

$self->nfields()

Return the number of columns in the data table.

$self->fieldnames()

Return a list of field header names.

$self->fieldname($column)

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

$self->fieldtype($column)

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

$self->fieldlength($column)

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

$self->fielddecimals($column)

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

$self->nrecords()

Return number of records in the file.

$self->fetchrow_arrayref($rownumber)

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

$self->fetchrows_arrayref($rownumber, $count)

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

$self->fetchrow_hashref($rownum)

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

$self->fetchrow_array($rownum)

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

$self->delete($rownum);

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

$self->undelete($rownum)

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

$self->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:

    $dbf->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 => '|');

$self->computeRecordBytes()

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

$self->computeHeaderBytes()

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

$self->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.

$self->nHeaderBytes()

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

$self->nRecordBytes()

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

$self->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