The ExoGam event-by-event data tape files consist of a number of data blocks. Each data block in the file has the same fixed length. Individual events have a variable length and are packed into the data blocks with a minimal amount of padding at the end of each block. Events will be contained totally within a given data block. No events will span data blocks.

The data block header identifies the type of data block (ie normal data, configuration data, comment) and also contains other information such as source of the data.
The data block header is 32 bytes in length.

bytes 0-7	*	block type
bytes 8-11		sequence number
bytes 12-15	*	magic number
bytes 16-17		source id
bytes 18-19		destination id
bytes 20-21		data stream number
bytes 22-23	*	number of events in the block (for EBYEDAT)
bytes 24-27		checksum (=0 if omitted)
bytes 28-31	*	actual length of data in the block

For the initial implementation only fields marked with a * will be used.

block type

This is an 8 byte character string field.
The block type identifies the format of data which follows in the block. The following block types are currently defined. The identifiers are text strings WHICH START WITH A LEADING SPACE and which are padded with space characters to fill the 8 byte field. In the following table the character ^ is used to represent a space character.

^EBYEDAT	normal formatted event data
^RAWDT32	DT32 bus "raw" data
^CONFIG^	configuration data block
^INFODAT	information (comment) data block

This is a 32 bit numeric field.
The sequence number identifies this data block. This field should not be confused with the Event Number.

This is a 32 bit numeric field.
The magic number is provided to enable an easy test of the processing required to interpret the data following in the block. This is necessary because of the differences caused by different processor hardware architectures.
The magic number has the hexadecimal value 0x22061999 if the processor reading the data has the same byte ordering as the tape server which wrote the data and has the hexadecimal value 0x99190622 if the processor reading the data has the opposite byte ordering as the tape server which wrote the data. In the latter case byte swapping of the data portion of the block will be needed before processing.
For further information see the section Byte Ordering at the end of this document.

These are 16 bit numeric fields.
The source id field identifies the source of the data which follows in the block and the destination id field identifies the destination of the data which follows in the block.
The source and destination id fields are reserved for use by the data acquisition system as required and can normally be ignored by software analysing the data within the block.

This is a 16 bit numeric field.
The data stream number will not be used in the initial implementation.

This is a 16 bit numeric field.
This field is only used for data blocks of type EBYEDAT. It contains the number of events (that is the number of Start Event Tokens) in the data which follows.

This is a 32 bit numeric field.
The checksum field will always be set to zero (ie omitted) in the initial implementation.

This is a 32 bit numeric field.
The length field contains the length of actual data in the block (in units of 16 bit words) and excludes the data block header and any padding added at the end of the block.

Programs designed to process ExoGam event-by-event data tapes MUST check the block type field to ensure that the block type is EBYEDAT.

Each event starts with an Event Header which is of variable length and can be from 2 to 8 words in length. All data elements within the event structure are defined in units of 16 bit words and hence the Event Header is aligned on a 16 bit boundary with respect to the start of the data block.
The data format is defined only in terms of 16 bit data words and thus data alignment is only on 16 bit boundaries. See also the section Byte Ordering at the end of this document.
All length fields throughout the data format are in units of 16 bit data words.
Throughout this document bit 0 refers to the most significant bit of the 16 bit data words and bit 15 refers to the least significant bit of the data word.

The Start Event Token is a single 16 bit data word which marks the start of the event and defines the format of the event.

8 bits = 0xff

2 bits status words

2 bits event number words

4 bits event format type

The most significant 8 bits of the Start Event Token are set to 1 bits.

The status words field is a 2 bit field which contains the number of status words in the event header.
There can be from 0 to 3 16 bit status words.

The event number words field is a 2 bit field which contains the number of event number words in the event header.
The Event Number can be either omitted or be 16, 32 or 48 bits in length.

The Event Format Type is a 4 bit field which identifies the format of the event which follows. Currently only the following values are defined:

0	16 bit event length follows the Start Event Token

Other event format types are reserved for possible use in the future if new detector types make the current formats inefficient.

The Event Length is the length (in units of 16 bit words) of the whole event INCLUDING the Event Header. Thus it is possible to step from one event to the next in the data block by adding the contents of the Event Length to a pointer variable containing the address of the start of the current event (the address of the current Event Header).

16 bits event length

Note - The Start Event Token most significant 8 bits are all one bits. However this is not unique since the Event Number following (if present) will also from time to time have the most significant 8 bits set. However in practice this is the only possible source of confusion.

This is an optional item which is only present if the Status Words in the Event Header = 1, 2 or 3.

This is an optional item which is only present if the Event Number Words in the Event Header = 1, 2 or 3. It contains the event number as generated by the electronics using information derived directly from the Master Trigger Module. This can be either a 16, 32 or 48 bit number. In the case of 32 or 48 bits it is stored in the event as 2 or 3 16 bit words with the most significant 16 bits stored first and the least significant 16 bits stored last.
For example a 32 bit Event Number is:

16 bits event number (most significant half)

16 bits event number (least significant half)

After the Event Header follows a variable number of Sub-Event Data Items. There will be one Sub-Event Data Item for each distinct detector system in the event.
A distinct detector system will be one which has its own individual readout system handled by the Event Builder. Thus not all detector systems used by an experiment need be distinct and thus create individual Sub-Event Data Items.

Each Sub-Event Data Item starts with a Sub-Event Header which has a similar format to the Event Header.

The Start Sub-Event Token is a single 16 bit data word which marks the start of the sub-event and defines the format of the sub-event.

6 bits detector system id

2 bits clock words

2 bits status words

2 bits sub-event number words

4 bits sub-event format type

The most significant 6 bits of the Start Sub-Event Token contains the Detector System Identification.

Currently the following Detector Systems are defined. Other systems will be added as they are identified.

0	ExoGam
1	Vamos
2	Tiara

The Detector System Identifier = 0x3f will never be used as this could cause the Sub-Event Header to be confused with an Event Header.

The sub-event clock words field is a 2 bit field which contains the number of clock words in the sub-event header.
The Sub-Event Clock can be either omitted or be 16, 32 or 48 bits in length.

The status words field is a 2 bit field which contains the number of status words in the sub-event header.
There can be from 0 to 3 16 bit status words.

The sub-event number words field is a 2 bit field which contains the number of event number words in the sub-event header.
The Sub-Event Number can be either omitted or be 16, 32 or 48 bits in length.

1	16 bit event length follows the Start Sub-Event Token

Other event format types are reserved for possible use in the future if new detector types make the current formats inefficient.

The Sub-Event Length is the length (in units of 16 bit words) of the whole sub-event INCLUDING the Sub-Event Header. Thus it is possible to step from one sub-event to the next in the data block by adding the contents of the Sub-Event Length to a pointer variable containing the address of the start of the current sub-event (the address of the current Sub-Event Header).

This is an optional item which is only present if the Sub-Event Clock Words in the Sub-Event Header = 1, 2 or 3. It can be either a 16, 32 or 48 bit number. In the case of 32 or 48 bits it is stored in the event as 2 or 3 16 bit words with the most significant 16 bits stored first and the least significant 16 bits stored last.
The source and resolution of the Sub-Event Clock will be dependent on the detector system.

This is an optional item which is only present if the Status Words in the Sub-Event Header = 1, 2 or 3.

This is an optional item which is only present if the Sub-Event Number Words in the Sub-Event Header = 1, 2 or 3. It can be either a 16, 32 or 48 bit number. In the case of 32 or 48 bits it is stored in the event as 2 or 3 16 bit words with the most significant 16 bits stored first and the least significant 16 bits stored last.
The source of the Sub-Event Number will be dependent on the detector system. It may be omitted if the source is the Master Trigger or if for any other reason it is identical to the Event Number.

The Format Type is a 4 bit field which identifies the format of the event data which follows. In the current format all event data items in the sub-event are required to have the same format type.

The Format Type has the following values

0	16 bit unlabelled data item
1	ExoGam 32 bit labelled data item

The format of the ExoGam 32 bit labelled data item is exactly the same as the data generated by the VXI electronics. (See EDOC300).
The 32 bit data item is composed of a 16 bit label which identifies the source of the data and a 16 bit data word.

2 bits status bits

6 bits item (ADC) identifier

8 bits group (Detector) identifier

16 bits ADC data

There then follows a variable number of Data Items each of which has the format defined by the Format Type field in the current Sub-Event Header.
The number of data items can be calculated by

((sub-event length) - (length of sub-event header)) / (length of a data item)

There is no End Sub-Event Token or End Event Token since the total length of the sub-event and event is available in the Start Sub-Event Token and the Start Event Token.

Events are packed into the data block until there is insufficient room for the next event to fit totally into the current data block. Events are complete within a data block and will not span data blocks.

The end of events in a data block is marked by a special Event Header having the following format.

16 bits = 0xff00

16 bits = 0x0000

This is equivalent to a Event Header for an event of length = 0 and no Event Number or Status Words.

The example event has 3 ExoGam 32 bit labelled data items.

Start Event Token = 0xff60 (event format type = 0)

Event Length = 13

Status = 0

Event Number MSW

Event Number LSW

Start Sub-Event Token = 0x0001 (sub-event format type = 1)

Sub-Event Length = 8

data item 1 address

data item 1 data

data item 2 address

data item 2 data

data item 3 address

data item 3 data

The processor used for the Exogam tape server is a Digital Alpha CPU. This is what is known as a Little Endian processor. This means that for a 16 bit data word the least significant 8 data bits are addressed before the most significant 8 data bits. Other Little Endian processors are the Intel x86 and Pentium architecture processors used in all PCs. The Sun MicroSystems SPARC architecture processors and the Motorola PowerPC and 68K processors are what are known as Big Endian processors.
The Magic Number in the data block header at offset 12 should be read as a 32 bit number. If the value obtained is 0x22061999 then your processor has the same byte ordering as the tape server and you can proceed without further work. If however the value obtained is 0x99190622 then your processor has the opposite byte ordering to the tape server and some preprocessing of the data will be necessary.
In this case all 16 bit data items have to be reordered as 0xaabb is converted to 0xbbaa and all 32 bit data items reordered as 0xaabbccdd is converted to 0xddccbbaa. All 8 bit data items (character strings) are unchanged.
Only the Data Block Header (first 32 bytes of the data block) has a mixture of 8, 16 and 32 bit data items. The rest of the data block (the actual event part) is totally 16 bit data items.
It is recommended that the magic number is tested and if necessary then the event portion of the data block is all byte swapped in place before you start processing the event data.