Paranoid::IO::FileMultiplexer::Block::BATHeader - BAT Header Block

       Arthur Corliss (corliss@digitalmages.com)

       o   Fcntl

       o   Paranoid

       o   Paranoid::Debug

       o   Paranoid::Data

       o   Paranoid::IO

       o   Paranoid::IOFileMultiplexer::Block

       This class is not meant to be used directly, but as part of the Paranoid::IO::FileMultiplexer
       functionality.  This provides functionality necessary for manipulation of the stream header block.

       This module does presume that whatever file it is being used on has already been opened in the
       appropriate mode, and that the Paranoid::IO flock stack has been enabled.  For the purposes of
       Paranoid::IO::FileMultiplexer, this is done in that class.

       This  software  is  free  software.   Similar to Perl, you can redistribute it and/or modify it under the
       terms of either:

         a)     the GNU General Public License
                <https://www.gnu.org/licenses/gpl-1.0.html> as published by the
                Free Software Foundation <http://www.fsf.org/>; either version 1
                <https://www.gnu.org/licenses/gpl-1.0.html>, or any later version
                <https://www.gnu.org/licenses/license-list.html#GNUGPL>, or
         b)     the Artistic License 2.0
                <https://opensource.org/licenses/Artistic-2.0>,

       subject to the following additional term:  No trademark rights to "Paranoid" have been  or  are  conveyed
       under  any  of  the  above  licenses.  However, "Paranoid" may be used fairly to describe this unmodified
       software, in good faith, but not as a trademark.

       (c)  2005  -  2021,  Arthur  Corliss  (corliss@digitalmages.com)  (tm)  2008  -   2021,   Paranoid   Inc.
       (www.paranoid.com)

perl v5.38.2                                       2024-03-07              Paranoid::IO::...lock::BATHeader(3pm)

       Paranoid::IO::FileMultiplexer::Block::BATHeader - BAT Header Block

new
           $obj = Paranoid::IO::FileMultiplexer::Block::BATHeader->new($file,
               $blockNo, $blockSize, $strmName, $sequenceNo);

       This creates a new instance of a BAT header block object.  It requires the filename in order to retrieve
       the cached file handle from Paranoid::IO, the block number of the block, the size of the block, the name
       of the stream, and the block sequence number.

       NOTE: creating an object does not automatically create the file and/or write a signature.  That must be
       done using the methods below.

   maxData
           $max = $obj->maxData;

       This method returns the maximum number of data blocks that can be tracked in a single BAT block.

   sequence
           $seq = $obj->sequence;

       This method returns the sequence number of the BAT.  In essence, this is the ordinal index of the BAT in
       a stream's array of BATs.

   dataBlocks
           @data = $obj->dataBlocks;

       This method returns the list of data blocks being tracked by this BAT.

   full
           $rv   = $obj->full;

       This method returns a boolean value denoting whether this BAT's array of data blocks is at maximum
       capacity or not.

   writeSig
           $rv = $obj->writeSig;

       This method writes the BAT header signature to disk, returning a boolean value denoting its success.
       Note that the signature contains the file format, stream name, and the BAT sequence number.  This does
       not include the allocated data block numbers.

   readSig
           $rv = $obj->readSig;

       This method reads the BAT header signature from disk and performs basic validation that the information
       in it is acceptable.  It validates that the stream name and sequence number matches what is expected and
       the block format is correct.

       If the method call was successful it will update the cached values in the object.  Note that this is only
       the signature values, not the data block numbers.

   writeData
           $rv = $obj->writeData;

       This method writes the data block numbers to the header block, and returns a boolean denoting success.

   readData
           $rv = $obj->readData;

       This method reads the data block numbers from the file, and returns a boolean value denoting success.  If
       the read is successful, this will update the cached data blocks in the object.

   addData
           $rv = $obj->addData($bn);

       This method does some basic validation of the requested BAT, and if it passes, updates the data block
       number list on the disk.

           $obj = Paranoid::IO::FileMultiplexer::Block::BATHeader->new($file,
               $blockNo, $blockSize, $strmName, $sequenceNo);

           $max  = $obj->maxData;
           $seq  = $obj->sequence;
           @data = $obj->dataBlocks;
           $rv   = $obj->full;

           $rv = $obj->writeSig;
           $rv = $obj->readSig;
           $rv = $obj->writeData;
           $rv = $obj->readData;
           $rv = $obj->addData($bn);

       $Id: lib/Paranoid/IO/FileMultiplexer/Block/BATHeader.pm, 2.10 2022/03/08 00:01:04 acorliss Exp $