class HMdcUnpacker: public HldUnpack

 id = sub event id for which the unpacker is called by

 set the default values for all intrinsic variables
 called by the constructor

 get status of quietMode
 quiet = kTRUE : messaging switch off
       = kFALSE: messages are displayed

 switch to disable all error messages and warnings from hmdcunpacker AND hmdcdataword
 quiet = kTRUE : messaging switch of
       = kFALSE: messages are displayed

 this function is only for debugging use!
 the decoding of the data words continue even if there is
 unconsistency in the datawords
 cont = kTRUE : continue
 cont = kFALSE: skip event

 returns decoding version of the unpacker

      version    : decoding version for the unpacker

                   version = 1, used for data since  2002-10-01 12:00:00
                                includes new naming scheme for the SAMs
                   version = 0, used for data before 2002-10-01 12:00:00

 set decoding version of the unpacker

      version    : decoding version for the unpacker

                   version = 1, used for data since  2002-10-01 12:00:00
                                includes new naming scheme for the SAMs
                   version = 0, used for data before 2002-10-01 12:00:00

      manual     : used for internal calls

 if version exceeds the value of maxDecodeVersion exit is called

 returns mode the tdc is triggering on signals
 mode 0 (default) : trigger on leading and trailing edge
 mode 1           : trigger on 2 leading edges:

 In measurement mode the TDC accepts two hits per channel. The TDC can hereby
 trigger either on on a leading and the trailing edge of a single pulse
 or on two leading edges.
 This influences the polarity of the hitCounter in the HMdcRaw Class:
 mode 0  : trigger on leading and trailing edge
           (hit multiplicity nHits: +1 or +2)
 mode 1  : trigger on 2 leading edges:
           (hit multiplicity nHits: -1 or -2)
 (0 default if i is not equal to 0 or 1)

 function to set the size in words of the ROC Header

 tool to execute an arbitray unix command
 the output is returned as an Char_t pointer (maximum size 1000)
 TODO: check whether PTools::myexec or other method can replace it

 prints out the variables of the unpacker object

 Initialisation of
                  - lookup table
                  - category for raw-level  storage
                  - additional category if debug option
                  - additional Tree if debug option
                  - local mdc setup table for lookup

 gets Mdc detector setup
 and initializes setup array

 inits the container cat
 looks first whether it already exists
 otherwise it is created
 default for detector is "Mdc"
 catname is used for Error handling

 initializes list of black listed mask and adress matches to be exclude from data stream

 initializes list of black listed mask and adress matches which can be recovered

 reinit function
 if versionSetManual not set it determines the decodeVersion via determineDecodeVersion()

 execute funtion of the task
 calls the fill() function (DETAILED) information here
 before it checks whether the called subEvtId corresponds
 to an active module in the mdc detector setup

 return values: always 1 (philosophy: a wrong sub event should not affect the other sub events)

 Tests the Mdc setup if the module are present
 in the running analysis at position sector, module

 determines the samNr from the sub event id localSubEvtId
 in addition it crosschecks the samNr with the DAQ specifications
 and does boundary checks by default.
 You can switch it off by setDisableSamNrConsistencyCheck()

 fill function:
 performs the loop over the subevent data

 -- if the ROC header size > 0 (change it via setRocEvtHeaderSize())
    then the roc header is decoded via decodeSubHeader()
    otherwise the whole subevent is decoded as once

 -- The data loop performs the following steps
     1.a. if enabled check for recoverable blacklisted adresses and store them
     1.b. if enabled check for further blacklisted adresses and ignore them
     2.   call of decode for each dataword
     3.   the hardware address is matched to the sector/module/mbo/tdc coordinates of HMdcRaw
          via the lookup table HMdcEvReadout
     4.   a new/existing slot at the corresponding address is requested
     5.   the time information is filled to this slot

 --  if enabled recover recoverable datawords after the data loop

 --  if the debug and fillDataWord flag is set (set via setFillDataWord() and setDebug())
     the extended dataword information is written to the category HMdcDataword()
     (the persistency of this container can be set via setPersistencyDataWord())

 -- the return values of the function are:
     1 : success
    -1 : Error while decoding the dataword
    -1 : Error while decoding the roc header
    -1 : Error while decoding the in data loop (data pointer exceeds data range)
    -2 : Error while filling the to category HMdcRaw

 -- in the case that there is no entry in the lookup table
    for a correctly decoded dataword there the next dataword is taken


 DETAILS:
 The single steps of this function are:

 1. check for existing pointers to subEvt and pReadout
    - if not
      -> "goto" end of function returning 1

 2. if the decode version is not set manually (via setDecodeVersion())
    -> call determineDecodeVersion()

 3. get subEvt's pointers to data and its end

 4. check for positive difference (data-end > 0)
    - if not
      -> leave function with return code -1

 5. if decodingMode() returns kFALSE (DETAILS see decodingMode())
      -> leave function with return code -1

 6. if "recoverBlackList" is enabled
      -> call prepareBlackListRecovery()

 7. sub sub event while loop

 7.1. determine end of subsub event loop from subsub event header

 7.2. subsub event dataword loop

 7.2.1. check whether subsub event endpointer exceeds sub event pointer
        - yes:
          -> skipping rest of sub event returning -1
            (incl. a possible correction of recoverable datawords)
          -> exception: "ontinueAfterInconsistency" is enabled
             -> continue with next dataword at 7.2

 7.2.2. if "recoverBlackList" is enabled
        -> check if dataword matches the list criteria
           - yes:
             -> call storeForRecoveryFromBlackList()
                and continue with next dataword at 7.2

 7.2.3. if "recoverBlackList" is enabled
        -> check if dataword matches the list criteria
           - yes:
             -> continue with next dataword at 7.2

 7.2.4. dataword decoding

        * behaviour during the dataword decoding:
   	      - if the consistency check is switched
            - on
              -> decode returns
   	             - kFALSE if any of the border checks failed
   	             - kTRUE else
   	        - off
              -> decode returns kTRUE

 	      - in case of an inconsistency: (kFALSE returned from decode with checkInconsistency switched on)
    	-> the decoding of all following datawords of this sub event is skipped
      	   (including a possible correction of recoverable datawords)
               the function returns -1
    	-> exception: "continueDecodingAfterInconsistency" is enabled
         	   - then, ignoring this maybe hazardous error (!!!),
                 decoding is continued with the next dataword at 7.2

 	      - in case of errors and "noComment" disabled
    	-> error messages are issued
       	and if also unpackerDebug is enabled
       	-> the dataword is dumped to the screen

  7.2.5. fill data to Raw categories calling fillData()
         in case of failures of fillData():
         - adress, setup or matching table errors
           -> continue with next dataword at 7.2
         - "cannot get Slot" (severe problems)
           -> leave function returning -1 and skipping rest of sub event
              (incl. possible recovery of datawords)

  7.2.6. END OF subsub event dataword loop

  7.3. increase data pointer by subsub event size

  7.4. END OF sub event while loop

  8. if recoverBlackList is enabled
     -> call of executeBlackListRecovery()
        - same return code behaviour as in 7.2.5 (fillData())

  9. leave function always returning 1

 method to determine from the referenceId/runId the time and so the valid version for decoding
 see the discription in setDecodeVersion()

 function to compare were the date and time of the event is relative to the given Time and Date
 returns:

  0 : time and date are the same
  1 : time and date of event are after the given time
 -1 : time and date of event are before the given time

 evaluates the decoding info in the sub event header

 dependent on the decoding information in the sub event header
 the following modes are selected:

 the least significant byte of the decoding word determines the compression modes:
 so decoding & f =

    0 : not allowed by definition of the sub event header

    1 : uncompressed structure
              - the event contains a roc sub structure
              - error bits and roc event sizes are determined from the roc headers
                and filled independently to HMdcRawEventHeader

    2 : compressed structure
              - the only contains pure data words
              - error informations are determined from
                the second least significant byte
                and assigned to all roc header synchronously
                to HMdcRawEventHeader but shifted by 4 bits to the left (*16)
                also the size of the complete sub event is assigned to each roc
                to distinguish from the case they have a negativ sign.

    any other value: not defined

 decodes the sub header (ROC-Header)
 and returns the size of this header

 If the errorFlag of the ROC-Header is set or
 the debug flag of the unpacker is set
 the header is written out to the category HMdcRawEventHeader
 (set its persistency via, setPersistencyRawEventHeader())

 If the standalone mode is chosen the trigger type (id) of the whole event
 is set to the trigger type of the roc header if it is a calibration trigger
 (If MDCs are not run via the common daq system, but in a standalone mode,
 the event trig type is not provided in the event header (it is always 1).)

 function for filling the category HMdcRawEventHeader

 Is dataword include in an recovery black list?
 TODO: recovery black list from oracle
 first masking then comparing to adress
 if it matches this dataword is stored
 until the end of the while loop and then processes

 returns kTRUE if data word matches
         kFALSE else

 Is dataword included in an excluding black list?
 TODO: black list from oracle
 first masking then comparing to adress
 if it matches this dataword is ignored

 returns kTRUE if data word matches
         kFALSE else

 Converts the content of the already decoded dataword via the lookup table HMdcEvReadout
 to sector/module/mbo/tdc coordinates.
 Then, if available the information is stored in a new or added to an existing
 data slot of HMdcRaw
 If activated, the raw data is written by fillMdcDataWord()
 (formerly additional debug had to be switched on, not necessary any more)

 the hardware address is matched to the sector/module/mbo/tdc coordinates of HMdcRaw
 via the lookup table HMdcEvReadout
 the result is checked for consistency
 deb is the pointer to the current rwa dataword

 kFALSE is returned in case of failures
 otherwise kTRUE

 checks whether module and sector are set in the MdcSetup
 returns kTRUE if set,
 kFALSE else

 checks consistency whether sector, module, mbo, tdc values are inside
 the bounds of the parameter container MboRawStruct
 return value
              kTRUE the checks were passed
              kFALSE if otherwise

 get a free or existing slot from the HMdcRaw category
 at the location of HLocation loc
 returns the pointer to the (new) HMdcRaw object
 NULL if it couldn't be done

 function for filling the category HMdcDataword

 Hardware bugfix for beamtime apr2006:
 In Module IV (Orsay) of Sector IV (SubEvtId 222)
 The mob id of the two motherboards in the LVL1 chain
 of mbo 113 and mbo 115 is corrupted.

 Up to now the Blacklist option ignored all datawords of this if activated
 Now it the channels should if possible be reconstructed:

 Because mbo 113 is a 64-channel board and mbo 115 is a 96 Long_t     // the topmost 32 channels can automatically be assigned to mbo 115

 Since this is the same error as in Sep2005
 recoverBlackListSep2005 is called

 Hardware bugfix for beamtime sep05:
 In Module IV (Orsay) of Sector IV (SubEvtId 222)
 The mob id of the two motherboards in the LVL1 chain
 of mbo 113 and mbo 115 is corrupted.

 Up to now the Blacklist option ignored all datawords of this if activated
 Now the channels should, if possible, be reconstructed:

 Because mbo 113 is a 64-channel board and mbo 115 is a 96 Long_t
 the topmost 32 channels can automatically be assigned to mbo 115

 function set/unset exclude black list feature via HMdcUnpacker::setExcludeBlackList
 and its context via HMdcUnpacker::setExcludeBlackListContext
 in one line.

 if context is empty or equal to HMdcUnpacker::excludeBlackListContextDefaultString
 the feature is deactivated.
 Any other value activates this, provided a corresponding table exists
 up to now "sep05" is the only valid context
 (see HMdcUnpacker::init() function)

 function set/unset recover black list feature via HMdcUnpacker::setRecoverBlackList
 and its context via HMdcUnpacker::setRecoverBlackListContext
 in one line.

 if context is empty or equal to HMdcUnpacker::recoverBlackListContextDefaultString
 the feature is deactivated.
 Any other value activates this, provided a corresponding table exists
 up to now "sep05" is the only valid context
 (see HMdcUnpacker::init() function)

 finalize function
 returning always kTRUE

 prints out messages for each mask - adress pair how many excludes were encountered

 prints out messages for each mask - adress pair how many recovers were encountered