org.jlab.coda.jevio
Class BlockHeaderV4

java.lang.Object
  org.jlab.coda.jevio.BlockHeaderV4

All Implemented Interfaces:

IBlockHeader, IEvioWriter

public class BlockHeaderV4
extends java.lang.Object
implements IEvioWriter, IBlockHeader

This holds a 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. This block structure is changed in version 4 so that blocks only contain integral numbers of events. The information stored in this block header has also changed.

 ################################
 Evio block header, version 4:
 ################################

 MSB(31)                          LSB(0)
 <---  32 bits ------------------------>
 _______________________________________
 |            Block Length             |
 |_____________________________________|
 |            Block Number             |
 |_____________________________________|
 |          Header Length = 8          |
 |_____________________________________|
 |             Event Count             |
 |_____________________________________|
 |             reserved 1              |
 |_____________________________________|
 |          Bit info         | Version |
 |_____________________________________|
 |             reserved 2              |
 |_____________________________________|
 |             Magic Int               |
 |_____________________________________|


      Block Length       = number of ints in block (including this one).
      Block Number       = id number (starting at 1)
      Header Length      = number of ints in this header (8)
      Event Count        = number of events in this block (always an integral #).
                           NOTE: this value should not be used to parse the following
                           events since the first block may have a dictionary whose
                           presence is not included in this count.
      Reserved 1         = If bits 2-5 in bit info are RocRaw (1), then (in the first block)
                           this contains the total number of payload banks following
      Bit info & Version = Lowest 8 bits are the version number (4).
                           Upper 24 bits contain bit info.
                           If a dictionary is included as the first event, bit #9 is set (=1)
      Magic Int          = magic number (0xc0da0100) used to check endianness



 Bit info has the first (lowest) 6 bits taken:
   Bit  0   = true if dictionary is included (relevant for first block only)
   Bit  1   = true if this block is the last block in file or network transmission
   Bits 2-5 = type of events following (ROC Raw = 0, Physics = 1, PartialPhysics = 2,
              DisentangledPhysics = 3, User = 4, Control = 5, Prestart = 6, Go = 7,
              Pause = 8, End = 9, Other = 15)



 

Author:

heddle, timmer

Field Summary

static int	EV_BLOCKNUM Position of word for block number, starting at 0.
static int	EV_BLOCKSIZE Position of word for size of block in 32-bit words.
static int	EV_COUNT Position of word for number of events in block.
static int	EV_DICTIONARY_MASK Dictionary presence is 9th bit in version/info word
static int	EV_HEADERSIZE Position of word for size of header in 32-bit words (=8).
static int	EV_LASTBLOCK_MASK "Last block" is 10th bit in version/info word
static int	EV_MAGIC Position of word for magic number for endianness tracking.
static int	EV_RESERVED1 Position of word for reserved.
static int	EV_RESERVED2 Position of word for reserved.
static int	EV_VERSION Position of word for version of file format.
static int	HEADER_SIZE The minimum & expected block header size in 32 bit ints.
static int	MAX_BLOCK_SIZE The maximum block size in 32 bit ints.

Fields inherited from interface org.jlab.coda.jevio.IBlockHeader

MAGIC_NUMBER

Constructor Summary

BlockHeaderV4()
Null constructor initializes all fields to zero.

BlockHeaderV4(BlockHeaderV4 blkHeader)
This copy constructor creates an evio version 4 BlockHeader from another object of this class.

BlockHeaderV4(int size, int number)
Creates a BlockHeader for evio version 4 format.

Method Summary

int	bytesRemaining(int position) Gives the bytes remaining in this block (physical record) given a buffer position.
static int	clearLastBlockBit(int i) Clear the last-block bit in the given arg to indicate it is NOT the last block.
java.lang.Object	clone()
int	firstEventStartingPosition() Determines where the start of the first event (logical record) in this block (physical record) is located (in bytes).
static int	generateSixthWord(java.util.BitSet set) Calculates the sixth word of this header which has the version number (4) in the lowest 8 bits and the set in the upper 24 bits.
static int	generateSixthWord(java.util.BitSet bSet, boolean isDictionary, boolean isEnd) Calculates the sixth word of this header which has the version number (4) in the lowest 8 bits and the set in the upper 24 bits.
static int	generateSixthWord(java.util.BitSet bSet, boolean isDictionary, boolean isEnd, int eventType) Calculates the sixth word of this header which has the version number (4) in the lowest 8 bits and the set in the upper 24 bits.
java.util.BitSet	getBitInfo() Gets a copy of all stored bit information.
boolean	getBitInfo(int bitIndex) Gets the value of a particular bit in the bitInfo field.
int	getBufferEndingPosition() Get the position in the buffer (in bytes) of this block's last data word.
int	getBufferStartingPosition() Get the starting position in the buffer (in bytes) from which this header was read--if that happened. This is not part of the block header proper.
int	getEventCount() Get the number of events completely contained in the block.
int	getEventType() Get the value of bits 2-5.
int	getHeaderLength() Get the block header length, in ints.
int	getMagicNumber() Get the magic number the block (physical record) header which should be 0xc0da0100.
int	getNumber() Get the block number for this block (physical record).
int	getReserved1() Get the first reserved word.
int	getReserved2() Get the second reserved word.
int	getSixthWord() Calculates the sixth word of this header which has the version number in the lowest 8 bits and the bit info in the highest 24 bits.
int	getSize() Get the size of the block (physical record).
int	getVersion() Get the evio version of the block (physical record) header.
boolean	hasDictionary() Is this block's first event is an evio dictionary?
static boolean	hasDictionary(int i) Does this integer indicate that there is an evio dictionary (assuming it's the header's sixth word)?
boolean	isLastBlock() Is this the last block in the file or being sent over the network?
static boolean	isLastBlock(int i) Does this integer indicate that this is the last block (assuming it's the header's sixth word)?
int	nextBufferStartingPosition() Determines where the start of the next block (physical record) header in some buffer is located (in bytes).
void	parseToBitInfo(int word) Parses the argument into the bit info fields.
void	setBit(int bitIndex, boolean value) Sets a particular bit in the bitInfo field.
void	setBufferStartingPosition(int bufferStartingPosition) Set the starting position in the buffer (in bytes) from which this header was read--if that happened. This is not part of the block header proper.
void	setEventCount(int count) Set the number of events completely contained in the block.
static void	setEventType(java.util.BitSet bSet, int type) Sets the right bits in bit set (2-5 when starting at 0) to hold 4 bits of the given type value.
void	setHeaderLength(int headerLength) Set the block header length, in ints.
static int	setLastBlockBit(int i) Set the bit in the given arg which indicates this is the last block.
void	setMagicNumber(int magicNumber) Sets the value of magicNumber.
void	setNumber(int number) Set the block number for this block (physical record).
void	setReserved1(int reserved1) Sets the value of first reserved word.
void	setReserved2(int reserved2) Sets the value of second reserved word.
void	setSize(int size) Set the size of the block (physical record).
void	setVersion(int version) Sets the evio version.
java.lang.String	toString() Obtain a string representation of the block (physical record) header.
int	write(java.nio.ByteBuffer byteBuffer) Write myself out a byte buffer.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

HEADER_SIZE

public static final int HEADER_SIZE

The minimum & expected block header size in 32 bit ints.

See Also:

Constant Field Values

MAX_BLOCK_SIZE

public static final int MAX_BLOCK_SIZE

The maximum block size in 32 bit ints. Don't allow more than 40MBytes per block.

See Also:

Constant Field Values

EV_DICTIONARY_MASK

public static final int EV_DICTIONARY_MASK

Dictionary presence is 9th bit in version/info word

See Also:

Constant Field Values

EV_LASTBLOCK_MASK

public static final int EV_LASTBLOCK_MASK

"Last block" is 10th bit in version/info word

See Also:

Constant Field Values

EV_BLOCKSIZE

public static final int EV_BLOCKSIZE

Position of word for size of block in 32-bit words.

See Also:

Constant Field Values

EV_BLOCKNUM

public static final int EV_BLOCKNUM

Position of word for block number, starting at 0.

See Also:

Constant Field Values

EV_HEADERSIZE

public static final int EV_HEADERSIZE

Position of word for size of header in 32-bit words (=8).

See Also:

Constant Field Values

EV_COUNT

public static final int EV_COUNT

Position of word for number of events in block.

See Also:

Constant Field Values

EV_RESERVED1

public static final int EV_RESERVED1

Position of word for reserved.

See Also:

Constant Field Values

EV_VERSION

public static final int EV_VERSION

Position of word for version of file format.

See Also:

Constant Field Values

EV_RESERVED2

public static final int EV_RESERVED2

Position of word for reserved.

See Also:

Constant Field Values

EV_MAGIC

public static final int EV_MAGIC

Position of word for magic number for endianness tracking.

See Also:

Constant Field Values

Constructor Detail

BlockHeaderV4

public BlockHeaderV4()

Null constructor initializes all fields to zero.

BlockHeaderV4

public BlockHeaderV4(int size,
                     int number)

Creates a BlockHeader for evio version 4 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 4
  
• bitInfo is initialized to all bits off
  
• magicNumber is initialized to MAGIC_NUMBER
  

Parameters:

size - the size of the block in ints.

number - the block number--usually sequential.

BlockHeaderV4

public BlockHeaderV4(BlockHeaderV4 blkHeader)

This copy constructor creates an evio version 4 BlockHeader from another object of this class.

Parameters:

blkHeader - block header object to copy

Method Detail

getSize

public int getSize()

Get the size of the block (physical record).

Specified by:

getSize in interface IBlockHeader

Returns:

the size of the block (physical record) in ints.

clone

public java.lang.Object clone()

Overrides:

clone in class java.lang.Object

setSize

public void setSize(int size)
             throws EvioException

Set the size of the block (physical record). Some trivial checking is done.

Parameters:

size - the new value for the size, in ints.

Throws:

EvioException

getEventCount

public int getEventCount()

Get the number of events completely contained in the block. NOTE: There are no partial events, only complete events stored in one block.

Returns:

the number of events in the block.

setEventCount

public void setEventCount(int count)
                   throws EvioException

Set the number of events completely contained in the block. NOTE: There are no partial events, only complete events stored in one block.

Parameters:

count - the new number of events in the block.

Throws:

EvioException

getNumber

public int getNumber()

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

Specified by:

getNumber in interface IBlockHeader

Returns:

the block number for this block (physical record).

setNumber

public void setNumber(int number)

Set the block number for this block (physical record). In a file, this is usually sequential. This is not checked.

Parameters:

number - the number of the block (physical record).

getHeaderLength

public int getHeaderLength()

Get the block header length, in ints. This should be 8.

Specified by:

getHeaderLength in interface IBlockHeader

Returns:

the block header length. This should be 8.

setHeaderLength

public void setHeaderLength(int headerLength)

Set the block header length, in ints. Although technically speaking this value is variable, it should be 8. param headerLength the new block header length. This should be 8.

getVersion

public int getVersion()

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

Specified by:

getVersion in interface IBlockHeader

Returns:

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

setVersion

public void setVersion(int version)

Sets the evio version. Should be 4 but no check is performed here, see EvioReader.nextBlockHeader().

Parameters:

version - the evio version of evio.

hasDictionary

public static boolean hasDictionary(int i)

Does this integer indicate that there is an evio dictionary (assuming it's the header's sixth word)?

Returns:

true if this int's indicates an evio dictionary, else false

hasDictionary

public boolean hasDictionary()

Is this block's first event is an evio dictionary?

Specified by:

hasDictionary in interface IBlockHeader

Returns:

true if this block's first event is an evio dictionary, else false

isLastBlock

public boolean isLastBlock()

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

Specified by:

isLastBlock in interface IBlockHeader

Returns:

true if this is the last block in the file or being sent over the network, else false

isLastBlock

public static boolean isLastBlock(int i)

Does this integer indicate that this is the last block (assuming it's the header's sixth word)?

Returns:

true if this int's indicates the last block, else false

setLastBlockBit

public static int setLastBlockBit(int i)

Set the bit in the given arg which indicates this is the last block.

Parameters:

i - integer in which to set the last-block bit

Returns:

arg with last-block bit set

clearLastBlockBit

public static int clearLastBlockBit(int i)

Clear the last-block bit in the given arg to indicate it is NOT the last block.

Parameters:

i - integer in which to clear the last-block bit

Returns:

arg with last-block bit cleared

getEventType

public int getEventType()

Get the value of bits 2-5. If this header is coming from the ROC, it represents the type of event being sent.

Returns:

bits 2-5 as an integer, representing event type.

getBitInfo

public java.util.BitSet getBitInfo()

Gets a copy of all stored bit information.

Returns:

copy of BitSet containing all stored bit information.

getBitInfo

public boolean getBitInfo(int bitIndex)

Gets the value of a particular bit in the bitInfo field.

Parameters:

bitIndex - index of bit to get

Returns:

BitSet containing all stored bit information.

setBit

public void setBit(int bitIndex,
                   boolean value)

Sets a particular bit in the bitInfo field.

Parameters:

bitIndex - index of bit to change

value - value to set bit to

setEventType

public static void setEventType(java.util.BitSet bSet,
                                int type)

Sets the right bits in bit set (2-5 when starting at 0) to hold 4 bits of the given type value. Useful when generating a bitset for use with EventWriter constructor.

Parameters:

bSet - Bitset containing all bits to be set

type - event type as int

getSixthWord

public int getSixthWord()

Calculates the sixth word of this header which has the version number in the lowest 8 bits and the bit info in the highest 24 bits.

Returns:

sixth word of this header.

generateSixthWord

public static int generateSixthWord(java.util.BitSet set)

Calculates the sixth word of this header which has the version number (4) in the lowest 8 bits and the set in the upper 24 bits.

Parameters:

set - Bitset containing all bits to be set

Returns:

generated sixth word of this header.

generateSixthWord

public static int generateSixthWord(java.util.BitSet bSet,
                                    boolean isDictionary,
                                    boolean isEnd)

Calculates the sixth word of this header which has the version number (4) in the lowest 8 bits and the set in the upper 24 bits. The arg isDictionary is set in the 9th bit and isEnd is set in the 10th bit.

Parameters:

bSet - Bitset containing all bits to be set

isDictionary - does this block include an evio xml dictionary as the first event?

isEnd - is this the last block of a file or a buffer?

Returns:

generated sixth word of this header.

generateSixthWord

public static int generateSixthWord(java.util.BitSet bSet,
                                    boolean isDictionary,
                                    boolean isEnd,
                                    int eventType)

Calculates the sixth word of this header which has the version number (4) in the lowest 8 bits and the set in the upper 24 bits. The arg isDictionary is set in the 9th bit and isEnd is set in the 10th bit. Four bits of an int (event type) are set in bits 10-13.

Parameters:

bSet - Bitset containing all bits to be set

isDictionary - does this block include an evio xml dictionary as the first event?

isEnd - is this the last block of a file or a buffer?

eventType - 4 bit type of events header is containing

Returns:

generated sixth word of this header.

parseToBitInfo

public void parseToBitInfo(int word)
                    throws EvioException

Parses the argument into the bit info fields. This ignores the version in the lowest 8 bits.

Throws:

EvioException

getReserved1

public int getReserved1()

Get the first reserved word.

Returns:

the first reserved word.

setReserved1

public void setReserved1(int reserved1)

Sets the value of first reserved word.

Parameters:

reserved1 - the value for first reserved word.

getReserved2

public int getReserved2()

Get the second reserved word.

Returns:

the second reserved word.

setReserved2

public void setReserved2(int reserved2)

Sets the value of second reserved word.

Parameters:

reserved2 - the value for second reserved word.

getMagicNumber

public int getMagicNumber()

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

Specified by:

getMagicNumber in interface IBlockHeader

Returns:

the magic number in the block (physical record).

setMagicNumber

public void setMagicNumber(int magicNumber)
                    throws EvioException

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 endianess is not being handled properly.

Parameters:

magicNumber - the new value for magic number.

Throws:

EvioException

toString

public java.lang.String toString()

Obtain a string representation of the block (physical record) header.

Specified by:

toString in interface IBlockHeader

Overrides:

toString in class java.lang.Object

Returns:

a string representation of the block (physical record) header.

getBufferEndingPosition

public int getBufferEndingPosition()

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

Specified by:

getBufferEndingPosition in interface IBlockHeader

Returns:

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

getBufferStartingPosition

public int getBufferStartingPosition()

Get the starting position in the buffer (in 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 (physical record). It is kept for convenience. It is up to the reader to set it.

Specified by:

getBufferStartingPosition in interface IBlockHeader

Returns:

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

setBufferStartingPosition

public void setBufferStartingPosition(int bufferStartingPosition)

Set the starting position in the buffer (in 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 (physical record). It is kept for convenience. It is up to the reader to set it.

Specified by:

setBufferStartingPosition in interface IBlockHeader

Parameters:

bufferStartingPosition - the starting position in the buffer from which this header was read--if that happened.

nextBufferStartingPosition

public int nextBufferStartingPosition()

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

Specified by:

nextBufferStartingPosition in interface IBlockHeader

Returns:

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

firstEventStartingPosition

public int firstEventStartingPosition()

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

Specified by:

firstEventStartingPosition in interface IBlockHeader

Returns:

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

bytesRemaining

public int bytesRemaining(int position)
                   throws EvioException

Gives the bytes remaining in this block (physical 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.

Specified by:

bytesRemaining in interface IBlockHeader

Parameters:

position - the absolute current position is a byte buffer.

Returns:

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

Throws:

EvioException

write

public int write(java.nio.ByteBuffer byteBuffer)

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

Specified by:

write in interface IBlockHeader

Specified by:

write in interface IEvioWriter

Parameters:

byteBuffer - the byteBuffer to write to.

Returns:

the number of bytes written, which for a BlockHeader is 32.