package DBZ_File;

BEGIN {
    if ($] >= 5.002) {
	use strict;
    }
}
use Carp;
use vars qw($VERSION @ISA);

require DynaLoader;

@ISA = qw(DynaLoader);

$VERSION = '1.1';

bootstrap DBZ_File $VERSION;

sub DELETE {
    croak "DBZ_File::DELETE not implemented";
}
sub FIRSTKEY {
    croak "DBZ_File::FIRSTKEY not implemented";
}
sub NEXTKEY {
    croak "DBZ_File::NEXTKEY not implemented";
}

1;

__END__

=head1 NAME

DBZ_File - Tied access to dbz files

=head1 SYNOPSIS

 use DBZ_File;

 tie(%hist,DBZ_File,'/usr/lib/news/history');  # must exist
 tie(%hist,DBZ_File,'/usr/lib/news/history', O_CREAT, 0664);  # create OK

 $history_file_offset = %hist{$message_id};
 %hist{$message_id} = $history_file_offset;

 untie(%hist);

=head1 DESCRIPTION

B<DBZ_File> allows perl programs to read and write a B<dbz> database,
such as the news history file.

The fetch and store functions handle all the B<dbz> quirks, such as
including a null character at the end of the key and translating the
offset to/from a datum.  It also calls the dbzfetch and dbzstore
functions, which means that the key gets the same upper-/lower- case
processing that is done by the news system.

=head1 BUGS

You cannot delete a hash entry, or enumerate the keys since
B<dbz> doesn't support the functions necessary to support the
DELETE, FIRSTKEY, and NEXTKEY tied array functions.  If you
attempt to use one of these features, you'll get a fatal error.

When creating a new database, the flags and umask are ignored by
B<dbz>, however they must both be non-zero for the command to
indicate that a create is OK.

You can't use multiple B<dbz>-tied arrays at the same time since B<dbz>
can only open one database.  If you try, the tie call returns a failure.

This module is probably not compatible with any previous (partial)
versions of B<dbz> support.  The reason for this is that they either
required the appending of a null character to the key (ick) or the
use of pack/unpack to be used with the offset value (yuck).

=head1 EXAMPLE

    use DBZ_File;

    tie(%hist, DBZ_File, '/usr/lib/news/history') or die $!;
    open(HFP, '+</usr/lib/news/history') or die $!;

    # Find an entry and output its line from the history file
    if (defined($pos = $hist{'<1234@clari.net>'})) {
	seek(HFP, $pos, 0);
	$_ = <HFP>;
	print;
    }

    # Write a new entry at the EOF
    seek(HFP, 0, 2);
    $msgid = '<54321@clari.net>';
    $hist{$msgid} = tell(HFP);
    print HFP "$msgid\t", time, "~-~0\n";

    close(HFP);
    untie(%hist);

=head1 AUTHOR

DBZ_File was written by Wayne Davison <wayne@clari.net>.  It is
based on the NDBM_File module with a few ideas derived from an old
alpha release written by Ian Phillipps <ian@pipex.net>.  The dbz
module has many names on it, and is copyright 1988 Jon Zeeff.

=cut