evio::BlockHeaderV2 Class Reference

This holds an evio block header, also known as a physical record header. More...

#include <BlockHeaderV2.h>

Public Member Functions
	BlockHeaderV2 ()=default
	Constructor initializes all fields to default values. More...
	BlockHeaderV2 (uint32_t sz, uint32_t num)
	Creates a BlockHeader for evio versions 1-3 format. More...
	BlockHeaderV2 (std::shared_ptr< BlockHeaderV2 > &blkHeader)
	This copy constructor creates an evio version 1-3 BlockHeader from another object of this class. More...
void	copy (std::shared_ptr< BlockHeaderV2 > &blkHeader)
	This method copies another header's contents. More...
bool	hasDictionary () override
	Does this block contain an evio dictionary? Returns true if this block contains an evio dictionary, else false. Always returns false for versions 1-3 (not implemented). More...
bool	isLastBlock () override
	Is this the last block in the file or being sent over the network? Returns true if this is the last block in the file or being sent over the network, else false. Always returns false for versions 1-3 (not implemented). More...
bool	isCompressed () override
	Is this the data in this block compressed? Returns true if the data in this block is compressed, else false. More...
Compressor::CompressionType	getCompressionType () override
	Get the type of data compression used. Returns type of data compression used. More...
uint32_t	getSize () override
	Get the size of the block (record) in 32 bit words. Returns size of the block (record) in 32 bit words. More...
void	setSize (uint32_t sz)
	Set the size of the block (physical record). More...
uint32_t	getStart () const
	Get the starting position of the block (physical record.). More...
void	setStart (uint32_t strt)
	Set the starting position of the block (physical record.). More...
uint32_t	getEnd () const
	Get the ending position of the block (physical record.) This is the number of valid words (header + data) in the block (physical record.) This is normally the same as the block size, except for the last block (physical record) in the file. More...
void	setEnd (uint32_t endd)
	Set the ending position of the block (physical record.) This is the number of valid words (header + data) in the block (physical record.) This is normally the same as the block size, except for the last block (physical record) in the file. More...
uint32_t	getNumber () override
	Get the block number for this block (record).In a file, this is usually sequential, starting at 1. Returns the block number for this block (record). More...
void	setNumber (uint32_t num)
	Set the block number for this block (physical record). More...
uint32_t	getHeaderLength () const
	Get the block header length in ints. More...
uint32_t	getHeaderWords () override
	Get the block (record) header length, in 32 bit words. Returns block (record) header length, in 32 bit words. More...
void	setHeaderLength (uint32_t len)
	Set the block header length, in ints. More...
bool	hasFirstEvent () override
	Does this block/record contain the "first event" (first event to be written to each file split)? Returns true if this record has the first event, else false. Evio versions 1-3 always return false. More...
uint32_t	getEventType () override
	Get the type of events in block/record (see values of DataType.This is not supported by versions 1-3 which returns 0. Returns type of events in block/record, or 0 if evio version 1-3. More...
uint32_t	getVersion () override
	Get the evio version of the block (record) header. Returns evio version of the block (record) header. More...
void	setVersion (uint32_t ver)
	Sets the evio version. More...
uint32_t	getSourceId () override
	Get the source ID number if in CODA online context and data is coming from ROC. Returns source ID number if in CODA online context and data is coming from ROC. More...
uint32_t	getReserved1 () const
	Get the first reserved word in the block (physical record) header. More...
void	setReserved1 (uint32_t r1)
	Sets the value of reserved1. More...
uint32_t	getMagicNumber () override
	Get the magic number the block (record) header which should be 0xc0da0100. Returns magic number in the block (record). More...
void	setMagicNumber (uint32_t magicNum)
	Sets the value of magicNumber. More...
ByteOrder &	getByteOrder () override
	Get the byte order of the data being read. Returns byte order of the data being read. More...
void	setByteOrder (ByteOrder &order)
	Sets the byte order of data being read. More...
std::string	toString () override
	Get the string representation of the block (record) header. Returns string representation of the block (record) header. More...
size_t	getBufferEndingPosition () override
	Get the position in the buffer (bytes) of this block's last data word. Returns position in the buffer (bytes) of this block's last data word. More...
size_t	getBufferStartingPosition () override
	Get the starting position in the buffer (bytes) from which this header was read–if that happened. This is not part of the block header proper. It is a position in a memory buffer of the start of the block (record). It is kept for convenience. It is up to the reader to set it. Returns starting position in buffer (bytes) from which this header was read–if that happened. More...
void	setBufferStartingPosition (size_t pos) override
	Set the starting position in the buffer (bytes) from which this header was read–if that happened. This is not part of the block header proper. It is a position in a memory buffer of the start of the block (record). It is kept for convenience. It is up to the reader to set it. Parameters pos starting position in buffer from which this header was read–if that happened. More...
size_t	nextBufferStartingPosition () override
	Determines where the start of the next block (record) header in some buffer is located (bytes).This assumes the start position has been maintained by the object performing the buffer read. Returns the start of the next block (record) header in some buffer is located (bytes). More...
size_t	firstEventStartingPosition () override
	Determines where the start of the first event in this block (record) is located (bytes).This assumes the start position has been maintained by the object performing the buffer read. Returns where the start of the first event in this block (record) is located (bytes). In evio format version 2, returns 0 if start is 0, signaling that this entire record is part of a logical record that spans at least three physical records. More...
size_t	bytesRemaining (size_t position) override
	Gives the bytes remaining in this block (record) given a buffer position.The position is an absolute position in a byte buffer. This assumes that the absolute position in bufferStartingPosition is being maintained properly by the reader. Parameters position the absolute current position in a byte buffer. Returns the number of bytes remaining in this block (record). Exceptions EvioException if position out of bounds More...
size_t	write (ByteBuffer &byteBuffer) override
	Write myself out into a byte buffer.This write is relative–i.e., it uses the current position of the buffer. Parameters byteBuffer the byteBuffer to write to. Returns the number of bytes written. Exceptions overflow_error if insufficient room to write header into buffer. More...

Static Public Attributes
static const uint32_t	MAX_BLOCK_SIZE = 32768
	The maximum block size in 32 bit ints in this implementation of evio. More...
static const uint32_t	MAGIC_NUMBER = 0xc0da0100
	The magic number, should be the value of magicNumber. More...
static const uint32_t	MAGIC_OFFSET = 28
	Byte offset from beginning of header to the magic number. More...
static const uint32_t	BIT_INFO_OFFSET = 20
	Byte offset from beginning of header to bit info word. More...
static const uint32_t	VERSION_MASK = 0xff
	Mask to get version number from bitinfo word in header. More...

Detailed Description

This holds an evio block header, also known as a physical record header.

Unfortunately, in versions 1, 2 & 3, evio files impose an anachronistic block structure. The complication that arises is that logical records (events) will sometimes cross physical record boundaries.

####################################
Evio block header, versions 1,2 & 3:
####################################

MSB(31)                          LSB(0)
<---  32 bits ------------------------>
_______________________________________
|            Block Length             |
|_____________________________________|
|            Block Number             |
|_____________________________________|
|          Header Length = 8          |
|_____________________________________|
|               Start                 |
|_____________________________________|
|                End                  |
|_____________________________________|
|              Version                |
|_____________________________________|
|             Reserved 1              |
|_____________________________________|
|            Magic Number             |
|_____________________________________|

     Block Length  = number of ints in block (including this one).
                     This is fixed for versions 1-3, generally at 8192 (32768 bytes)
     Block Number  = id number (starting at 0)
     Header Length = number of ints in this header (always 8)
     Start         = offset to first event header in block relative to start of block
     End           = # of valid words (header + data) in block (normally = block size)
     Version       = evio format version
     Reserved 1    = reserved
     Magic #       = magic number (0xc0da0100) used to check endianness

Author

heddle (original java version)

timmer

Constructor & Destructor Documentation

evio::BlockHeaderV2::BlockHeaderV2 ( )

default

Constructor initializes all fields to default values.

evio::BlockHeaderV2::BlockHeaderV2 ( uint32_t  sz, uint32_t  num  )

inline

Creates a BlockHeader for evio versions 1-3 format.

Only the block size and block number are provided. The other six words, which can be modified by setters, are initialized to these values:

• headerLength is initialized to 8
  
• start is initialized to 8
  
• end is initialized to size
  
• version is initialized to 2
  
• reserved1 is initialized to 0
  
• magicNumber is initialized to MAGIC_NUMBER
  

Parameters

sz	the size of the block in ints.
num	the block number–usually sequential.

evio::BlockHeaderV2::BlockHeaderV2 ( std::shared_ptr< BlockHeaderV2 > &  blkHeader )

inlineexplicit

This copy constructor creates an evio version 1-3 BlockHeader from another object of this class.

Parameters

blkHeader

block header object to copy

References copy().

Member Function Documentation

size_t evio::BlockHeaderV2::bytesRemaining ( size_t  position )

inlineoverridevirtual

Gives the bytes remaining in this block (record) given a buffer position.The position is an absolute position in a byte buffer. This assumes that the absolute position in bufferStartingPosition is being maintained properly by the reader.

Parameters

position

the absolute current position in a byte buffer.

Returns

the number of bytes remaining in this block (record).

Exceptions

EvioException

if position out of bounds

Implements evio::IBlockHeader.

References nextBufferStartingPosition().

void evio::BlockHeaderV2::copy ( std::shared_ptr< BlockHeaderV2 > &  blkHeader )

inline

This method copies another header's contents.

Parameters

blkHeader

block header object to copy

Referenced by BlockHeaderV2().

size_t evio::BlockHeaderV2::firstEventStartingPosition ( )

inlineoverridevirtual

Determines where the start of the first event in this block (record) is located (bytes).This assumes the start position has been maintained by the object performing the buffer read.

Returns

where the start of the first event in this block (record) is located (bytes). In evio format version 2, returns 0 if start is 0, signaling that this entire record is part of a logical record that spans at least three physical records.

Implements evio::IBlockHeader.

size_t evio::BlockHeaderV2::getBufferEndingPosition ( )

inlineoverridevirtual

Get the position in the buffer (bytes) of this block's last data word.

Returns

position in the buffer (bytes) of this block's last data word.

Implements evio::IBlockHeader.

size_t evio::BlockHeaderV2::getBufferStartingPosition ( )

inlineoverridevirtual

Get the starting position in the buffer (bytes) from which this header was read–if that happened.
This is not part of the block header proper. It is a position in a memory buffer of the start of the block (record). It is kept for convenience. It is up to the reader to set it.

Returns

starting position in buffer (bytes) from which this header was read–if that happened.

Implements evio::IBlockHeader.

Referenced by toString().

ByteOrder& evio::BlockHeaderV2::getByteOrder ( )

inlineoverridevirtual

Get the byte order of the data being read.

Returns

byte order of the data being read.

Implements evio::IBlockHeader.

Compressor::CompressionType evio::BlockHeaderV2::getCompressionType ( )

inlineoverridevirtual

Get the type of data compression used.

Returns

type of data compression used.

Implements evio::IBlockHeader.

References evio::Compressor::UNCOMPRESSED.

uint32_t evio::BlockHeaderV2::getEnd ( ) const

inline

Get the ending position of the block (physical record.) This is the number of valid words (header + data) in the block (physical record.) This is normally the same as the block size, except for the last block (physical record) in the file.

NOTE: for evio files, even if end < size (blocksize) for the last block (physical record), the data behind it will be padded with zeroes so that the file size is an integer multiple of the block size.

Returns

the ending position of the block (physical record.)

uint32_t evio::BlockHeaderV2::getEventType ( )

inlineoverridevirtual

Get the type of events in block/record (see values of DataType.This is not supported by versions 1-3 which returns 0.

Returns

type of events in block/record, or 0 if evio version 1-3.

Implements evio::IBlockHeader.

uint32_t evio::BlockHeaderV2::getHeaderLength ( ) const

inline

Get the block header length in ints.

This should be 8.

Returns

block header length in ints.

uint32_t evio::BlockHeaderV2::getHeaderWords ( )

inlineoverridevirtual

Get the block (record) header length, in 32 bit words.

Returns

block (record) header length, in 32 bit words.

Implements evio::IBlockHeader.

uint32_t evio::BlockHeaderV2::getMagicNumber ( )

inlineoverridevirtual

Get the magic number the block (record) header which should be 0xc0da0100.

Returns

magic number in the block (record).

Implements evio::IBlockHeader.

uint32_t evio::BlockHeaderV2::getNumber ( )

inlineoverridevirtual

Get the block number for this block (record).In a file, this is usually sequential, starting at 1.

Returns

the block number for this block (record).

Implements evio::IBlockHeader.

uint32_t evio::BlockHeaderV2::getReserved1 ( ) const

inline

Get the first reserved word in the block (physical record) header.

Used in evio versions 1-3 only.

Returns

the first reserved word in the block (physical record). Used in evio versions 1-3 only.

uint32_t evio::BlockHeaderV2::getSize ( )

inlineoverridevirtual

Get the size of the block (record) in 32 bit words.

Returns

size of the block (record) in 32 bit words.

Implements evio::IBlockHeader.

uint32_t evio::BlockHeaderV2::getSourceId ( )

inlineoverridevirtual

Get the source ID number if in CODA online context and data is coming from ROC.

Returns

source ID number if in CODA online context and data is coming from ROC.

Implements evio::IBlockHeader.

uint32_t evio::BlockHeaderV2::getStart ( ) const

inline

Get the starting position of the block (physical record.).

This is the offset (in ints, relative to start of block) to the start of the first event (logical record) that begins in this block. For the first event it will just be = 8, the size of the block header. For subsequent blocks it will generally not be 8. Note that a an event that spans three blocks (physical records) will have start = 0.

NOTE: a logical record (event) that spans three blocks (physical records) will have start = 0.

Returns

the starting position of the block (physical record.)

uint32_t evio::BlockHeaderV2::getVersion ( )

inlineoverridevirtual

Get the evio version of the block (record) header.

Returns

evio version of the block (record) header.

Implements evio::IBlockHeader.

bool evio::BlockHeaderV2::hasDictionary ( )

inlineoverridevirtual

Does this block contain an evio dictionary?

Returns

true if this block contains an evio dictionary, else false. Always returns false for versions 1-3 (not implemented).

Implements evio::IBlockHeader.

bool evio::BlockHeaderV2::hasFirstEvent ( )

inlineoverridevirtual

Does this block/record contain the "first event" (first event to be written to each file split)?

Returns

true if this record has the first event, else false. Evio versions 1-3 always return false.

Implements evio::IBlockHeader.

bool evio::BlockHeaderV2::isCompressed ( )

inlineoverridevirtual

Is this the data in this block compressed?

Returns

true if the data in this block is compressed, else false.

Implements evio::IBlockHeader.

bool evio::BlockHeaderV2::isLastBlock ( )

inlineoverridevirtual

Is this the last block in the file or being sent over the network?

Returns

true if this is the last block in the file or being sent over the network, else false. Always returns false for versions 1-3 (not implemented).

Implements evio::IBlockHeader.

size_t evio::BlockHeaderV2::nextBufferStartingPosition ( )

inlineoverridevirtual

Determines where the start of the next block (record) header in some buffer is located (bytes).This assumes the start position has been maintained by the object performing the buffer read.

Returns

the start of the next block (record) header in some buffer is located (bytes).

Implements evio::IBlockHeader.

Referenced by bytesRemaining(), and toString().

void evio::BlockHeaderV2::setBufferStartingPosition ( size_t  pos )

inlineoverridevirtual

Set the starting position in the buffer (bytes) from which this header was read–if that happened.
This is not part of the block header proper. It is a position in a memory buffer of the start of the block (record). It is kept for convenience. It is up to the reader to set it.

Parameters

pos	starting position in buffer from which this header was read–if that happened.

Implements evio::IBlockHeader.

void evio::BlockHeaderV2::setByteOrder ( ByteOrder &  order )

inline

Sets the byte order of data being read.

Parameters

order

the new value for data's byte order.

void evio::BlockHeaderV2::setEnd ( uint32_t  endd )

inline

Set the ending position of the block (physical record.) This is the number of valid words (header + data) in the block (physical record.) This is normally the same as the block size, except for the last block (physical record) in the file.

Some trivial checking is done.
NOTE: for evio files, even if end < size (blocksize) for the last block (physical record), the data behind it will be padded with zeroes so that the file size is an integer multiple of the block size.

Parameters

endd	the new value for the end.

Exceptions

EvioException

if end < 8 or > MAX_BLOCK_SIZE.

References MAX_BLOCK_SIZE.

void evio::BlockHeaderV2::setHeaderLength ( uint32_t  len )

inline

Set the block header length, in ints.

This should be 8. However, since this is usually read as part of reading the physical record header, it is a good check to have a setter rather than just fix its value at 8.

Parameters

len	the new block header length. This should be 8.

Exceptions

EvioException

if headerLength is not 8.

void evio::BlockHeaderV2::setMagicNumber ( uint32_t  magicNum )

inline

Sets the value of magicNumber.

This should match the constant MAGIC_NUMBER ... If it doesn't, some obvious possibilities:
1) The evio data (perhaps from a file) is screwed up.
2) The reading algorithm is screwed up.
3) The endianness is not being handled properly.

Parameters

magicNum

the new value for magic number.

Exceptions

EvioException

if magic number not the correct value.

References evio::IBlockHeader::MAGIC_NUMBER.

void evio::BlockHeaderV2::setNumber ( uint32_t  num )

inline

Set the block number for this block (physical record).

In a file, this is usually sequential. This is not checked.

Parameters

num	the number of the block (physical record).

void evio::BlockHeaderV2::setReserved1 ( uint32_t  r1 )

inline

Sets the value of reserved1.

Parameters

r1	the value for reserved1.

void evio::BlockHeaderV2::setSize ( uint32_t  sz )

inline

Set the size of the block (physical record).

Some trivial checking is done.

Parameters

sz	the new value for the size, in ints.

Exceptions

EvioException

if size < 8 or > MAX_BLOCK_SIZE.

References MAX_BLOCK_SIZE.

void evio::BlockHeaderV2::setStart ( uint32_t  strt )

inline

Set the starting position of the block (physical record.).

This is the offset (in ints, relative to start of block) to the start of the first event (logical record) that begins in this block. For the first event it will just be = 8, the size of the block header. For subsequent blocks it will generally not be 8. Some trivial checking is done. Note that an event that spans three blocks (physical records) will have start = 0.

NOTE: a logical record (event) that spans three blocks (physical records) will have start = 0.

Parameters

strt	the new value for the start.

Exceptions

EvioException

if start < 8 or > MAX_BLOCK_SIZE.

References MAX_BLOCK_SIZE.

void evio::BlockHeaderV2::setVersion ( uint32_t  ver )

inline

Sets the evio version.

Should be 1, 2 or 3 but no check is performed here.

Parameters

ver	the evio version of evio.

std::string evio::BlockHeaderV2::toString ( )

inlineoverridevirtual

Get the string representation of the block (record) header.

Returns

string representation of the block (record) header.

Implements evio::IBlockHeader.

References getBufferStartingPosition(), and nextBufferStartingPosition().

size_t evio::BlockHeaderV2::write ( ByteBuffer &  byteBuffer )

inlineoverridevirtual

Write myself out into a byte buffer.This write is relative–i.e., it uses the current position of the buffer.

Parameters

byteBuffer

the byteBuffer to write to.

Returns

the number of bytes written.

Exceptions

overflow_error

if insufficient room to write header into buffer.

Implements evio::IBlockHeader.

References evio::ByteBuffer::putInt(), and evio::ByteBuffer::remaining().

Member Data Documentation

const uint32_t evio::IBlockHeader::BIT_INFO_OFFSET = 20

staticinherited

Byte offset from beginning of header to bit info word.

Referenced by evio::Util::findEvioVersion().

const uint32_t evio::IBlockHeader::MAGIC_NUMBER = 0xc0da0100

staticinherited

The magic number, should be the value of magicNumber.

Referenced by evio::Util::findEvioVersion(), evio::EvioReaderV4::parseFirstHeader(), setMagicNumber(), and evio::BlockHeaderV4::setMagicNumber().

const uint32_t evio::IBlockHeader::MAGIC_OFFSET = 28

staticinherited

Byte offset from beginning of header to the magic number.

Referenced by evio::Util::findEvioVersion().

const uint32_t evio::BlockHeaderV2::MAX_BLOCK_SIZE = 32768

static

The maximum block size in 32 bit ints in this implementation of evio.

There is, in actuality, no limit on size; however, the versions 1-3 C library only used 8192 as the block size.

Referenced by setEnd(), setSize(), and setStart().

const uint32_t evio::IBlockHeader::VERSION_MASK = 0xff

staticinherited

Mask to get version number from bitinfo word in header.

Referenced by evio::Util::findEvioVersion().

---

The documentation for this class was generated from the following file:

• BlockHeaderV2.h