.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Paranoid::IO::FileMultiplexer::Block::BATHeader 3pm"
.TH Paranoid::IO::FileMultiplexer::Block::BATHeader 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Paranoid::IO::FileMultiplexer::Block::BATHeader \- BAT Header Block
.SH VERSION
.IX Header "VERSION"
\&\f(CW$Id:\fR lib/Paranoid/IO/FileMultiplexer/Block/BATHeader.pm, 2.10 2022/03/08 00:01:04 acorliss Exp $
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&    $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);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
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.
.PP
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.
.SH SUBROUTINES/METHODS
.IX Header "SUBROUTINES/METHODS"
.SS new
.IX Subsection "new"
.Vb 2
\&    $obj = Paranoid::IO::FileMultiplexer::Block::BATHeader\->new($file,
\&        $blockNo, $blockSize, $strmName, $sequenceNo);
.Ve
.PP
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.
.PP
\&\fBNOTE:\fR creating an object does not automatically create the file and/or
write a signature.  That must be done using the methods below.
.SS maxData
.IX Subsection "maxData"
.Vb 1
\&    $max = $obj\->maxData;
.Ve
.PP
This method returns the maximum number of data blocks that can be tracked in a
single BAT block.
.SS sequence
.IX Subsection "sequence"
.Vb 1
\&    $seq = $obj\->sequence;
.Ve
.PP
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.
.SS dataBlocks
.IX Subsection "dataBlocks"
.Vb 1
\&    @data = $obj\->dataBlocks;
.Ve
.PP
This method returns the list of data blocks being tracked by this BAT.
.SS full
.IX Subsection "full"
.Vb 1
\&    $rv   = $obj\->full;
.Ve
.PP
This method returns a boolean value denoting whether this BAT's array of data
blocks is at maximum capacity or not.
.SS writeSig
.IX Subsection "writeSig"
.Vb 1
\&    $rv = $obj\->writeSig;
.Ve
.PP
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.
.SS readSig
.IX Subsection "readSig"
.Vb 1
\&    $rv = $obj\->readSig;
.Ve
.PP
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.
.PP
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.
.SS writeData
.IX Subsection "writeData"
.Vb 1
\&    $rv = $obj\->writeData;
.Ve
.PP
This method writes the data block numbers to the header block, and returns a
boolean denoting success.
.SS readData
.IX Subsection "readData"
.Vb 1
\&    $rv = $obj\->readData;
.Ve
.PP
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.
.SS addData
.IX Subsection "addData"
.Vb 1
\&    $rv = $obj\->addData($bn);
.Ve
.PP
This method does some basic validation of the requested BAT, and if it
passes, updates the data block number list on the disk.
.SH DEPENDENCIES
.IX Header "DEPENDENCIES"
.IP o 4
.IX Item "o"
Fcntl
.IP o 4
.IX Item "o"
Paranoid
.IP o 4
.IX Item "o"
Paranoid::Debug
.IP o 4
.IX Item "o"
Paranoid::Data
.IP o 4
.IX Item "o"
Paranoid::IO
.IP o 4
.IX Item "o"
Paranoid::IOFileMultiplexer::Block
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
.SH AUTHOR
.IX Header "AUTHOR"
Arthur Corliss (corliss@digitalmages.com)
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
This software is free software.  Similar to Perl, you can redistribute it
and/or modify it under the terms of either:
.PP
.Vb 7
\&  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>,
.Ve
.PP
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.
.PP
(c) 2005 \- 2021, Arthur Corliss (corliss@digitalmages.com)
(tm) 2008 \- 2021, Paranoid Inc. (www.paranoid.com)