NAME

VisionDB::Read - Vision DB v.4-5 files parser

VERSION

Version 0.04

SYNOPSIS

        use VisionDB::Read;

        # constructor
        my $vision = VisionDB::Read->new('filename');

        # error checking
        print $vision->{error};

        # get some DB infos
        print "File name is: ".$vision->filename."\n";
        print "File is a VisionDB version ".$vision->version."\n";
        print "DB has ".($vision->records+0)." record(s)\n";

        # acquire fields infos
        my @fields = $vision->fields;
        for ($i=0; $i<scalar(@fields); $i++) {
                print "Field $i found at offset ".$fields[$i]."\n";
        }

        # move record ptr
        $vision->reset;         # reset record ptr to 1st record
        $vision->recno(0);      # same thing
        $vision->recno(100);    # goto record #100
        $vision->recno(-1);     # goto last record
        $vision->recno(-10);    # goto 10th record from end

        # get current record number
        print "Current record is: ".($vision->recno+0)."\n";

        # read all data records
        $vision->reset;
        while ($rec = $vision->next) {    # get next record
                print "Record size is ".($rec->size+0)." bytes\n";
                print "Raw data is: ".$rec->data."\n";
                # free the data memory
                $rec->dispose;
        }

        # destructor
        $vision->free;

DESCRIPTION

This modules parses data from AcuCobol Vision DBs V.4-5 to permit a simple way to export the contained data. It offers also a way to discover the data inner fields by examining the index keys headers. This module doesn't use indexes to read data, so index files are generally ignored during processing and output dump is ordered using natural DB order. VisionDB::Read is a pure Perl implementation and doesn't require any external library.

METHODS of VisionDB::Read object

new($filename)

This method creates the class object and opens the DB file(s). It takes one scalar argument $filename specifying the pathname of the first DB file (Vision DBs may consist in one or more data files, plus indexes). The return value is a reference to the newly created VisionDB object or undef if any error occurred.

free()

This method frees the class object and releases (closes) the DB files. It has no return value.

reset()

This method moves the record pointer to the beginning of the DB and returns the current record number (always 0) or undef if any error occurred; in the latter case the error message may be read using the error attribute.

next()

This method reads the record data and moves the pointer to the next record. It returns a reference to the newly created record object. If there are no more records to read, it returns undef and the current record number is set to -1. If any error occurred, undef is returned and the corresponding error message may be read using the error attribute.

METHODS of VisionDB::Read::record object

dispose()

Frees-up the memory used by the record object. This will render the record data unusable. Mostly useful for effectively managing big records sets, saving some RAM space. This method has no return value.

ATTRIBUTES of VisionDB::Read object

version

This attribute returns the version of the opened DB file. The return value is a scalar; this is a read-only attribute.

filename

This attribute returns the base name (without path) of the DB file. The return value is a scalar containing the filename or undef if no DB was opened; this is a read-only attribute.

error

This attribute returns the error code of last executed operation. The return value is a scalar containing the error string or undef if no error; this is a read-only attribute.

records

This attribute returns the records count of the opened DB file. The return value is a scalar; this is a read-only attribute.

recno

This attribute sets/returns the current record pointer of the opened DB file. The return value is a scalar or undef if error is detected. The first record is always at 0. When at EOF this attribute returns -1; setting a negative value sets the current recno starting from the end of DB, so -1 means the last record, -2 the 2nd from the end, and so on. If any error occurred, the error message may be read using the error attribute.

fields

This attribure returns an array containing the fields offsets inside records; these infos are extracted from index keys data, unfortunately they aren't guaranteed to be 100% accurate, they just could give a good idea about how each record is built; this is a read-only attribute.

ATTRIBUTES of VisionDB::Read::record object

size

This attribute returns the size of the whole record data. The return value is a scalar.

data

This attribute returns the raw data from the current record. The content is not guaranteed to be an ASCII text, so always use the size attribute to determine the effective data block length. The return value is a scalar.

SUPPORT

To request for some support you may try to use the mailing list at

http://www.opendiogene.it/mailman/listinfo/opendiogene-users

Bugs should be reported via mailing list at

http://www.opendiogene.it/mailman/listinfo/opendiogene-bugs

AUTHOR

Riccardo Scussat - OpenDiogene Project <r.scussat@dsplabs.net>

COPYRIGHT

The code in this module is released under GNU GPLv2.

Copyright (C) 2009 - 2011 R.Scussat - OpenDiogene Project.

This program is free software; you can redistribute it and/or modify it under the terms of supplied license.

The full text of the license can be found in the LICENSE file included with this module.