—package
VMS::FlatFile;
use
strict;
$VERSION
=
"0.01"
;
# use the IndexedFile module
use
VMS::IndexedFile;
use
Data::FixedFormat;
1;
sub
new {
my
$class
=
shift
;
my
$self
= {};
bless
$self
,
$class
;
$self
->_initialize(
@_
);
return
$self
;
}
sub
_initialize {
my
$self
=
shift
;
$self
->{FileName} =
shift
;
$self
->{Access} =
shift
;
my
$fmt
=
shift
;
$self
->{KeyNum} =
shift
|| 0;
$self
->{Handle} =
tie
(%{
$self
->{File}},
'VMS::IndexedFile'
,
$self
->{FileName},
$self
->{KeyNum},
$self
->{Access} ? O_RDWR : O_RDONLY)
||
die
"Unable to tie to file $self->{FileName}\n$!\n"
;
$self
->{Formatter} = Data::FixedFormat->new(
$fmt
);
1;
}
sub
get {
my
$self
=
shift
;
my
$key
=
shift
;
my
$frec
= ${
$self
->{File}}{
$key
};
return
undef
unless
$frec
;
$self
->{Formatter}->unformat(
$frec
);
}
sub
put {
my
$self
=
shift
;
my
$frec
=
$self
->{Formatter}->
format
(
@_
);
$self
->{Handle}->store(
$frec
);
}
sub
delete
{
my
$self
=
shift
;
my
$key
=
shift
;
delete
(${
$self
->{File}}{
$key
});
}
=head1 NAME
VMS::FlatFile - read and write hashes with VMS::IndexedFile.
=head1 SYNOPSIS
=head2 Standalone
# Load the module
use VMS::FlatFile;
# Create an instance
# args - file name, access (ro=0, rw=1), format, key number
my $file = new VMS::FlatFile 'disk$user01:[user]file.dat', 0,
[ 'field1:a10', 'field2:a16' ], 0;
# Read a hash
my $hashref = $file->get($key);
# Write a hash
my $sts = $file->put($hashref);
# Delete a record
$sts = $file->delete($key);
=head2 As a Base Class
# name your derived class
package MyFile;
# Load the module and derive
use VMS::FlatFile;
use var qw(@ISA);
@ISA = qw(VMS::FlatFile);
1;
# override new
sub new {
my $class = shift;
my $self = {};
bless $self,$class;
# default to read only
my $access = shift || 0;
# use key 0
my $krf = shift || 0;
$self->_initialize('disk:[dir]filename.type', $access,
[ 'field1:a10', 'field2:a16' ], $krf);
return $self;
}
package main;
# create an instance
my $file = new MyFile;
my $hashref = $file->get('keyvalue');
=head1 DESCRIPTION
VMS::FlatFile combines VMS::IndexedFile and Data::FixedFormat to make
it possible to read and write hashes to VMS indexed files.
First, load the module:
use VMS::FlatFile;
Next, create an instance:
my $file = new VMS::FlatFile 'disk$user01:[user]file.dat', 0,
[ 'field1:a10', 'field2:a16' ], 0;
The B<new> method accepts four arguments:
=over 4
=item filename
The filename argument is passed directly to VMS::IndexedFile.
=item access
If access is true, the file is opened read/write. If false the file
is opened read only.
=item format
The format argument is used to construct a Data::FixedFormat instance
for the file. This argument is passed directly to
Data::FixedFormat::new.
=item key of reference
This argument is passed to VMS::IndexedFile to select a key of
reference. If not specified or if specified as 0, the file's primary
key is used. Specify 1 for the first alternate key, etc.
=back
To read records, use the B<get> method:
my $hashref = $file->get($key);
B<get> returns a reference to a hash created by
Data::FixedFormat::unformat.
B<get> accepts one argument which is the key of the record to be read.
If specified as the null string, the next sequential record is read
from the file.
To write records, use the B<put> method:
my $sts = $file->put($hashref);
The status returned by B<put> comes from VMS::IndexedFile::store. The
lone argument is a reference to a hash which is converted into a file
buffer with Data::FixedFormat::format and written to the file.
To delete records, use the B<delete> method:
my $sts = $file->delete($key);
The record with the specified key value will be deleted from the file.
The easiest way to use VMS::FlatFile as a base class would be to write a
derived module that provides the filename and format arguments for
each file you need to access. To do this, override the B<new> method
with a routine like the following:
package MyFile;
use VMS::FlatFile;
use vars qw(@ISA);
@ISA = qw(VMS::FlatFile);
sub new {
my $class = shift;
my $self = {};
bless $self,$class;
# default to read only
my $access = shift || 0;
# use key 0
my $krf = shift || 0;
$self->_initialize('disk:[dir]filename.type', $access,
[ 'field1:a10', 'field2:a16' ], $krf);
return $self;
}
The B<_initialize> routine takes the same arguments as B<new>. This
new constructor takes two arguments; the access mode (true for
read/write) and the key of reference.
VMS::FlatFile instances contain the attributes:
=over 4
=item File
This is the hash bound to the file with B<tie>. Records are read from
the file by reading attributes (i.e., file keys) from this hash.
=item Handle
This attribute receives the result from the call to B<tie> which
connects the VMS file to the hash.
=item Formatter
The Formatter attribute is an instance of a Data::FixedFormat which is
used for converting between file records and hashes.
=back
=head1 AUTHOR
VMS::FlatFile was written by Thomas Pfau <pfau@eclipse.net>
http://www.eclipse.net/~pfau/.
=head1 COPYRIGHT
Copyright (C) 2000 Thomas Pfau. All rights reserved.
This module is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU General Public License
along with this progam; if not, write to the Free Software Foundation,
Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
=cut