/ 
VMS-FlatFile-0.01
River stage zero No dependents
/ VMS::FlatFile

NAME

VMS::FlatFile - read and write hashes with VMS::IndexedFile.

SYNOPSIS

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);

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');

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 new method accepts four arguments:

filename

The filename argument is passed directly to VMS::IndexedFile.

access

If access is true, the file is opened read/write. If false the file is opened read only.

format

The format argument is used to construct a Data::FixedFormat instance for the file. This argument is passed directly to Data::FixedFormat::new.

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.

To read records, use the get method:

my $hashref = $file->get($key);

get returns a reference to a hash created by Data::FixedFormat::unformat.

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 put method:

my $sts = $file->put($hashref);

The status returned by 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 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 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 _initialize routine takes the same arguments as 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:

File

This is the hash bound to the file with tie. Records are read from the file by reading attributes (i.e., file keys) from this hash.

Handle

This attribute receives the result from the call to tie which connects the VMS file to the hash.

Formatter

The Formatter attribute is an instance of a Data::FixedFormat which is used for converting between file records and hashes.

AUTHOR

VMS::FlatFile was written by Thomas Pfau <pfau@eclipse.net> http://www.eclipse.net/~pfau/.

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.