gEvtCli.py

#!/usr/local/bin/python
#
#                               Copyright 2002
#                                     by
#                        The Board of Trustees of the
#                     Leland Stanford Junior University.
#                            All rights reserved.
#

## \namespace evtCli
##
## \brief Event handler classes
##
##  Event objects:
##
##    The following list contains the objects populated during parsing.
##    Please refer to the individual classes to find out how to access
##    event data stored in these objects:
##
##    - CAL_LogAccepts   -- List of evCAL_LogAccepts
##
##    - CAL_LogData      -- List of evCAL_LayerLogData
##
##    - TKRstrips        -- List of evTKR_StripData
##
##    - TKRaccepts       -- List of int
##
##    - TKRtots          -- List of evTKR_TOTdata
##
##    - diag             -- evDiag_Data
##
##    - errSummary       -- evErr_Summary
##
##    - errGCCCmsg       -- List of evErr_GCCC_Message
##
##    - errGTCCmsg       -- List of evErr_GTCC_Message
##
##    - errCablePhase    -- evErr_CablePhase
##
##    - errCableTimeOut  -- evErr_CableTimeOut
##
##    - aem              -- AEM
##
##    - aem.PHA          -- Dictionary of evAEM_PHA indexed by cable number
##
##    - gem              -- GEM
##
##    - gem.vetoList     -- evGEM_Veto_List

__facility__ = "Online"
__abstract__ = "Event handler client"
__author__   = "Selim Tuvi <stuvi@slac.stanford.edu> SLAC - GLAST I&T/Online"
__date__     = ("$Date: 2005/09/01 01:50:56 $").split(' ')[1]
__version__  = "$Revision: 2.37 $"
__release__  = "$Name: R04-12-00 $"
__credits__  = "SLAC"

import LATTE.copyright_SLAC

import          sys
import          struct
import          select
import          traceback
import logging  as     log
from string     import *
from os         import *
from time       import sleep, time, gmtime, asctime
from operator   import isNumberType
from math       import modf

from gLog import logStack, logException
from gException import LATInterfaceStatus, LATInterfaceException
from gBits import BitField, q, dump_cells
from gSocket import Socket
from gOpcode import Opcode


N_GCCC =  4
N_GCRC =  4
N_GCFE = 12

N_GTCC =  8
N_GTRC =  9
N_GTFE = 24

N_GARC = 12
N_GAFE = 18

GTCC_MAP     = [6, 3, 7, 2, 5, 0, 4, 1]
GTCC_ERR_MAP = [3, 6, 2, 7, 0, 5, 1, 4]

GCCC_MAP = [0, 2, 3, 1]

# AEM class
class AEM(object):
  """\brief AEM event object

  Members:
  - \c vetoHitVectors
  - \c acceptHitVectors
  - \c PHA

  """
  EV_AEM_VETO = 1
  EV_AEM_ZEROSUP = 2

  def __init__(self):
    self.clearEvent()

  def clearEvent(self):
    """\brief Initialize accept and veto hit vectors

    """
    self.vetoHitVectors = [0]*N_GARC
    self.acceptHitVectors = [0]*N_GARC
    self.PHA = {}
    for cbl in range(N_GARC):
      self.PHA[cbl] = []

  def addPHA(self, cbl, pha):
    """\brief Adds a PHA value.

    Called from evDumpAEM_PHA

    \param cbl Cable number
    \param pha 16 bit PHA value
    """
    self.PHA[cbl].append(pha)

class evAEM_PHA(BitField):
  """\brief PHA object

  Bit Fields:
  - \c more
  - \c range
  - \c ADC
  - \c parityErr

  """
  evAEM_PHA_BF =  [
                    ('more',         14, 15),
                    ('range',        13, 14),
                    ('ADC',           1, 13),
                    ('parityErr',     0,  1)
                  ]
  def __init__(self, ui):
    BitField.__init__(self, ui, self.evAEM_PHA_BF)

class GEM(object):
  """\brief GEM event object.

  Members:
  - \c ROI_Vector
  - \c TKR_Vector
  - \c CAL_HE_Vector
  - \c CAL_LE_Vector
  - \c deadzone
  - \c conditions
  - \c CNO_Vector
  - \c vetoList
  - \c liveTime
  - \c prescaled
  - \c discarded
  - \c condArrivalTimes
  - \c triggerTime
  - \c onePPSTime
  - \c deltaOpenWindowTime
  - \c deltaEventTime

  \deprecated
  - \c \b triggerSummary Use 'conditions' instead
  - \c \b sent           Use 'condArrivalTimes' instead

  """
  def __init__(self):
    self.vetoList = evGEM_Veto_List()
    self.condArrivalTimes = evGEM_Cond_Arrival_Times(0)
    self.clear()

  def clear(self):
    self.ROI_Vector = 0
    self.TKR_Vector = 0
    self.CAL_HE_Vector = 0
    self.CAL_LE_Vector = 0
    self.triggerSummary = 0 # Deprecated
    self.deadzone = 0
    self.conditions = 0
    self.CNO_Vector = 0
    self.vetoList.clear()
    self.liveTime = 0
    self.prescaled = 0
    self.discarded = 0
    self.sent = 0 # Deprecated
    self.condArrivalTimes.set(0)
    self.triggerTime = 0
    self.onePPSTime = 0
    self.deltaOpenWindowTime = 0
    self.deltaEventTime = 0

class evGEM_Veto_List(object):
  """\brief GEM Veto List object.

  Members:
  - \c XZP
  - \c XZM
  - \c YZP
  - \c YZM
  - \c XY
  - \c NA
  - \c RBN

  """
  def __init__(self):
    self.clear()

  def clear(self):
    self.XZP = 0
    self.XZM = 0
    self.YZP = 0
    self.YZM = 0
    self.XY  = 0
    self.NA  = 0
    self.RBN = 0

class evGEM_Cond_Arrival_Times(BitField):
  """\brief GEM Condition Arrival Times bitfield.

  Members:
  - \c External
  - \c CNO
  - \c CAL_HE
  - \c CAL_LE
  - \c TKR
  - \c ROI

  """
  evGEM_Cond_Arrival_Times_BF =  [
                    ('External',     25, 30),
                    ('CNO',          20, 25),
                    ('CAL_HE',       15, 20),
                    ('CAL_LE',       10, 15),
                    ('TKR',           5, 10),
                    ('ROI',           0,  5)
                  ]
  def __init__(self, ui):
    BitField.__init__(self, ui, self.evGEM_Cond_Arrival_Times_BF)


class Evt(object):
  """\brief Event object

  Members:
  - \c aem
  - \c gem
  - \c contributor
  - \c summary
  - \c TKRstrips
  - \c TKRaccepts
  - \c TKRtots
  - \c CAL_LogAccepts
  - \c CAL_LogData
  - \c diag
  - \c errSummary
  - \c errGCCCmsg
  - \c errGTCCmsg
  - \c errCablePhase
  - \c errCableTimeOut

  """
  def __init__(self):
    """\brief Event object constructor.

    Instantiate the AEM object and clear the event.
    """
    self.aem = AEM()
## New Event Format
    self.gem = GEM()
##
    self.clearEvent()

  def clearEvent(self):
    """\brief Clear the event data

    """
    self.contributor = None
    self.summary = None
    self.TKRstrips = []
    self.TKRaccepts = []
    self.TKRtots = []
    self.CAL_LogAccepts = []
    self.CAL_LogData = []
    self.diag = None
    self.errSummary = None
    self.errGCCCmsg = []
    self.errGTCCmsg = []
    self.errCablePhase = None
    self.errCableTimeOut = None

  def addTKRstrip(self, cc, rc, strip):
    """\brief Add a stripData to the tracker strip hit list of evTKR_StripData objects.

    \param cc    Cable controller id
    \param rc    Readout controller id
    \param strip evTKR_Strip object instance
    """
    self.TKRstrips.append(evTKR_StripData(cc, rc, strip))

  def addTKRaccept(self, accept):
    """\brief Add a TKR accept to the list

    \param 9-bit TKR accept value
    """
    self.TKRaccepts.append(accept)

  def addTKRtot(self, cc, rc, tot):
    """\brief Add a TKR tot to the list of evTKR_TOTdata objects.

    \param cc    Cable controller id
    \param rc    Readout controller id
    \param tot   8-bit tot value
    """
    self.TKRtots.append(evTKR_TOTdata(cc, rc, tot))

  def addCAL_LogAccept(self, accept):
    """\brief Add a log accept to the list

    \param accept An evCAL_LogAccepts object instance
    """
    self.CAL_LogAccepts.append(accept)

  def addCAL_LogData(self, twr, layer, data):
    """\brief Add a log data to the list

    \param layer A layer id in the form of 'x1', 'y1', etc.
    \param data  An evCAL_LogData object instance
    """
    self.CAL_LogData.append(evCAL_LayerLogData(twr, layer, data))

  def addErrGCCCmsg(self, errGCCC):
    """\brief Add a GCCC error contribution to the event object

    \param errGCCC An evErr_GCCC object instance
    """
    self.errGCCCmsg.append(errGCCC)

  def addErrGTCCmsg(self, errGTCCmsg):
    """\brief Add a GTCC error message to the event object

    \param errGTCCmsg An evErr_GTCC_Message object instance
    """
    self.errGTCCmsg.append(errGTCCmsg)

class evErr_Summary(BitField):
  """\brief Error summary bitfields

  Bit Fields:
  - \c cblTimeOut
  - \c cblPhsErr
  - \c gtccErr
  - \c gcccErr

  """
  evErr_Summary_BF =  [
                        ('cblTimeOut',  13, 14),
                        ('cblPhsErr',   12, 13),
                        ('gtccErr',      4, 12),
                        ('gcccErr',      0,  4)
                      ]
  def __init__(self, ui):
    BitField.__init__(self, ui, self.evErr_Summary_BF)

class evSummary(BitField):
  """\brief Event summary bitfields

  Bit Fields:
  - \c startbit
  - \c calStrobe
  - \c tag
  - \c TACK
  - \c readout4
  - \c zeroSuppress
  - \c marker
  - \c error
  - \c diag
  - \c evNumber
  - \c trgParityErr

  """
  evSummary_BF =  [
                    ('startbit ',     31, 32),
                    ('calStrobe',     30, 31),
                    ('tag',           28, 30),
                    ('TACK',          27, 28),
                    ('readout4',      26, 27),
                    ('zeroSuppress',  25, 26),
                    ('marker',        22, 25),
                    ('error',         21, 22),
                    ('diag',          20, 21),
                    ('evNumber',       1, 16),
                    ('trgParityErr',   0,  1)
                  ]
  def __init__(self, ui):
    BitField.__init__(self, ui, self.evSummary_BF)

class evSummary_Singleton(evSummary):
  def __init__(self, ui):
    evSummary.__init__(self, ui)

  def __call__(self, ui):
    self.set(ui)
    return self

class evContPacket(BitField):
  """\brief Contribution Packet bitfields

  Bit Fields:
  - \c error
  - \c sequence
  - \c length

  """
  evContPacket_BF = [
                    ('error',     13, 16),
                    ('sequence',   8, 13),
                    ('length',     0,  8),
                  ]
  def __init__(self, ui):
    BitField.__init__(self, ui, self.evContPacket_BF)

class evContPacket_Singleton(evContPacket):
  def __init__(self, ui):
    evContPacket.__init__(self, ui)

  def __call__(self, ui):
    self.set(ui)
    return self

class evTKR_TOTdata(object):
  """\brief TKR TOT data class

  Members:
  - \c tot
  - \c cc
  - \c rc

  """
  def __init__(self, cc, rc, tot):
    """\brief evTKR_TOTdata constructor

    \param cc  Cable controller id
    \param rc  Readout controller id
    \param tot 8-bit TOT value

    """
    self.tot = tot
    self.cc = cc
    self.rc = rc

class evTKR_Strip(BitField):
  """\brief TKR strip bitfields

  Bit Fields:
  - \c done
  - \c gtfe
  - \c strip

  """
  evTKR_Strip_BF =  [
                      ('done',    11, 12),
                      ('gtfe',     6, 11),
                      ('strip',    0,  6)
                    ]
  def __init__(self, ui):
    BitField.__init__(self, ui, self.evTKR_Strip_BF)

class evTKR_StripData(object):
  """\brief TKR StripData class

  Members:
  - \c cc
  - \c rc
  - \c strip

  """
  def __init__(self, cc, rc, strip):
    """\brief evTKR_StripData constructor

    \param cc    Cable controller id
    \param rc    Readout controller id
    \param strip An evTKR_Strip object instance
    """
    self.strip = strip
    self.cc = cc
    self.rc = rc

class evCAL_LogAccepts(BitField):
  """\brief Log Accepts bitfields

  Bit Fields:
  - \c y3
  - \c y2
  - \c y1
  - \c y0
  - \c x3
  - \c x2
  - \c x1
  - \c x0

  """
  evCAL_LogAccepts_BF = [
                          ('y3',    28, 32),
                          ('y2',    24, 28),
                          ('y1',    20, 24),
                          ('y0',    16, 20),
                          ('x3',    12, 16),
                          ('x2',     8, 12),
                          ('x1',     4,  8),
                          ('x0',     0,  4)
                        ]
  def __init__(self, twr, ui):
    BitField.__init__(self, ui, self.evCAL_LogAccepts_BF)
    self.twr = twr

class evCAL_LayerLogData(object):
  """\brief Class that associates a layer with the log data

  """
  def __init__(self, twr, layer, data):
    """\brief evCAL_LayerLogData constructor

    \param layer CAL layer (such as 'x1', 'y1', etc)
    \param data  evCAL_LogData bitfield
    """
    self.twr   = twr
    self.layer = layer
    self.data  = data

class evCAL_LogData(BitField):
  """\brief Log Data bitfields

  Bit Fields:
  - \c column
  - \c rangeADC_neg
  - \c valADC_neg
  - \c rangeADC_pos
  - \c valADC_pos

  """
  evCAL_LogData_BF =  [
                        ('column',       28, 32),
                        ('rangeADC_neg', 26, 28),
                        ('valADC_neg',   14, 26),
                        ('rangeADC_pos', 12, 14),
                        ('valADC_pos',    0, 12)
                      ]
  def __init__(self, ui):
    BitField.__init__(self, ui, self.evCAL_LogData_BF)

class evDiag_CalLayerEnd(BitField):
  """\brief Calorimeter Layer End bitfields

  Bit Fields:
  - \c trgRequestHigh
  - \c trgRequestLow
  - \c logAccepts

  """
  evDiag_CalLayerEnd_BF =   [
                              ('trgRequestHigh',  13, 14),
                              ('trgRequestLow',   12, 13),
                              ('logAccepts',       0, 12)
                            ]
  def __init__(self, ui):
    BitField.__init__(self, ui, self.evDiag_CalLayerEnd_BF)

class evDiag_CalLayer:
  """\brief Calorimeter Layer class

  Members:
  - \c gccc
  - \c layer
  - \c negLayerEnd
  - \c posLayerEnd

  """
  def __init__(self):
    self.gccc        = None
    self.layer       = None
    self.negLayerEnd = evDiag_CalLayerEnd(0)
    self.posLayerEnd = evDiag_CalLayerEnd(0)


class evDiag_TkrTrgReq(BitField):
  """\brief TKR Trigger Request bitfields

  Members:
  - \c gtcc

  Bit Fields:
  - \c trgRequests

  """
  evDiag_TkrTrgReq_BF =   [
                            ('trgRequests',  0, 9)
                          ]
  def __init__(self, ui):
    BitField.__init__(self, ui, self.evDiag_TkrTrgReq_BF)
    self.gtcc = None

class evErr_GCCC(BitField):
  """\brief GCCC Error bitfields

  Bit Fields:

  - \c errParm
  - \c sweepNum
  - \c errType

  """
  evErr_GCCC_BF =   [
                      ('errParm',   8, 16),
                      ('sweepNum',  6,  8),
                      ('errType',   0,  4)
                    ]
  def __init__(self, ui):
    BitField.__init__(self, ui, self.evErr_GCCC_BF)

class evErr_GCCC_Message(object):
  """\brief GCCC Error Message object

  Members:
  - \c gccc
  - \c errGCCC

  """
  def __init__(self, gccc, errGCCC):
    """\brief evErr_GCCC_Message constructor

    \param gccc    GCCC id
    \param errGCCC evErr_GCCC object instance
    """
    self.gccc       = gccc
    self.errGCCC    = errGCCC

class evErr_CablePhase(BitField):
  """\brief Cable Controller Phasing Error bitfields

  Bit Fields:
  - \c tag7
  - \c tag6
  - \c tag5
  - \c tag4
  - \c tag3
  - \c tag2
  - \c tag1
  - \c tag0

  """
  evErr_CablePhase_BF = [
                          ('tag7', 14, 16),
                          ('tag6', 12, 14),
                          ('tag5', 10, 12),
                          ('tag4',  8, 10),
                          ('tag3',  6,  8),
                          ('tag2',  4,  6),
                          ('tag1',  2,  4),
                          ('tag0',  0,  2)
                        ]
  def __init__(self, ui):
    BitField.__init__(self, ui, self.evErr_CablePhase_BF)

class evErr_GTCC(BitField):
  """\brief GTCC Error bitfields

  Bit Fields:
  - \c dataParity
  - \c GTRCsum
  - \c wrdCntParity
  - \c hdrParity
  - \c cblTimeOut
  - \c fifoFull
  - \c phsGTFE
  - \c phsGTRC
  - \c nGTRC

  """
  evErr_GTCC_BF =   [
                      ('dataParity',    15, 16),
                      ('GTRCsum',       14, 15),
                      ('wrdCntParity',  13, 14),
                      ('hdrParity',     12, 13),
                      ('cblTimeOut',    11, 12),
                      ('fifoFull',      10, 11),
                      ('phsGTFE',        9, 10),
                      ('phsGTRC',        8,  9),
                      ('nGTRC',          0,  8)
                    ]
  def __init__(self, ui):
    BitField.__init__(self, ui, self.evErr_GTCC_BF)

class evErr_GTCC_Message(object):
  """\brief GTCC Error Message object

  Members:
  - \c gtcc
  - \c errGTCC
  - \c parameters

  """
  def __init__(self):
    self.gtcc       = None
    self.errGTCC    = None
    self.parameters = {}


class evErr_CableTimeOut(BitField):
  """\brief Cable Timeout Error bitfields

  Bit Fields:
  - \c tkr
  - \c cal

  """
  evErr_CableTimeOut_BF = [
                            ('tkr',  4, 12),
                            ('cal',  0,  4)
                          ]
  def __init__(self, ui):
    BitField.__init__(self, ui, self.evErr_CableTimeOut_BF)


class evDiag_Data(object):
  """\brief Diagnostic Data class

  Members:
  - \c cal
  - \c tkr

  """
  size = 48 # 8*(4 + 2)
  def __init__(self):
    self.cal = []
    self.tkr = []
    for i in range(8):
      inst = evDiag_CalLayer()
      self.cal.append(inst)
      inst = evDiag_TkrTrgReq(0)
      self.tkr.append(inst)

class evCellHeader(BitField):
  """\brief Cell Header bitfields

  Bit Fields:
  - \c respond
  - \c destination
  - \c protocol
  - \c source
  - \c parity

  """
  evCellHeader_BF = [
                      ('respond',    15, 16),
                      ('destination', 9, 15),
                      ('protocol',    7,  9),
                      ('source',      1,  7),
                      ('parity',      0,  1),
                    ]
  def __init__(self, ui):
    BitField.__init__(self, ui, self.evCellHeader_BF)

class evCellHeader_Singleton(evCellHeader):
  def __init__(self, ui):
    evCellHeader.__init__(self, ui)

  def __call__(self, ui):
    self.set(ui)
    return self


class EvtCliIO(Socket):
  """\brief Event client input/output class

\b Contents:

  This base class contains all the input/output handling routines for the event client (EvtCli) class.

  """

  EVENT_SRC_SOCK = 0
  EVENT_SRC_FILE = 1
  PortNumber = 2000

  def __init__(self, debug, port=PortNumber):
    Socket.__init__(self, port)
    self.read                = None
    self.__abort             = 0
    self.__timeout           = 1        # !!!!
    self.__timeoutEnabled    = 0
    self.__debugErrorOutput  = debug & (EvtCli.DEBUG_ALL | EvtCli.DEBUG_ERROR_OUTPUT)

  def connect(self, host, force=False):
    Socket.connect(self, host)
    self.read = self.readSocket
    if force: opcode = Opcode(Opcode.ForceEventSocket)
    else:     opcode = Opcode(Opcode.SetEventSocket)
    self.send(opcode.packet())
    dat = self.recvall(8)
    [size, status] = struct.unpack('!2L', dat)
    if status & 0x3: raise LATInterfaceException(status)

  def setSocket(self, sock):
    Socket.setSocket(self, sock)
    self.read = self.readSocket

  def readSocket(self):
    """\brief The 'lightweight' event read routine.

    This routine does the minimal work of reading the raw
    event data from a file or a socket.

    \return Event buffer read
    """
    self.__abort = 0
    while not self.__abort:
      rd, wr, ex = select.select([self.socket()], [], [], self.__timeout)
      if rd:
        dat = self.recvall(28)
        header = struct.unpack('!7L', dat)
        numLeft = header[2] - 24
        dat += self.recvall(numLeft)
        return (header, dat[4:])
      elif self.__timeoutEnabled:
        raise IOError, "Event read timeout"
    # Abort:
    raise RuntimeError, "EvtCli.readSocket was aborted"

  def readFile(self):
    """\brief Read the event from a file.

    """
    # The archive file includes the first two datagram words
    dat = self.__f.read(20)
    header = (0,)
    header += struct.unpack('!5L', dat)
    numLeft = (header[2] & 0xFFFF) - 20
    dat += self.__f.read(numLeft)
    return (header, dat)

  def open(self,filename,mode="r+b"):
    """\brief Open the event archive file for input.

    \param filename Event archive file name
    """
    self.__f=file(filename, mode)
    self.read = self.readFile

  def close(self):
    """\brief Close the event source file.
    """
    self.__f.close()

  def abort(self):
    """\brief Abort out of a readEvent().

    Can be used from another thread
    """
    self.__abort = 1

  def setTimeoutEnabled(self, flag):
    """\brief Enable or disable event timeout

    \param flag 1 = Enable event timeout
                0 = Disable event timeout (default)
    """
    self.__timeoutEnabled = flag;

  def isTimeoutEnabled(self):
    """\brief Checks the event timeout state

    \return 1 = If event timeout is enabled
            0 = If event timeout is disabled
    """
    return self.__timeoutEnabled

  def setTimeout(self, timeout = 1.0):
    """\brief Set the timeout value.

    \param timeout Event timeout value as a floating point number in seconds.
                   Default is 1 second.  Use 'None' to disable the timeout.
    """
    #self.__timeout = timeout
    self.socket().settimeout(timeout)

  def getTimeout(self):
    """\brief Query the current timeout value.

    \return Current event timeout value as a floating point number in seconds
    """
    #return self.__timeout
    return self.socket().gettimeout()

  def unpack(self, fmt, str):
    """\brief Wrapper method for unpack

    \param  fmt Unpack format
    \param  str String to be unpacked

    \return     Unpacked data tuple
    """
    try:
      result = struct.unpack(fmt, str)
    except:
      if self.__debugErrorOutput:
        logException()
        logStack()
      return ()
    else:
      return result


class EvtCli(EvtCliIO):
  """\brief Event handler client

\b Contents:

  Receives an event from TCP socket or a file stream and
  parses it into the evt object.

\b Overview:

  The event client is responsible for communicating with the event server
  and retrieve events triggered by a script or an external source.
  The source of the event can be either a TCP socket or an archive file.

  The event client uses lazy parsing to parse the event. This means the
  user application needs to call the parsing routines that corresponds
  to the section of the event that the user is interested in. The parser
  methods populate event objects inside the Evt class in the event client,
  so after the parser method is called these objects can be accessed or
  iterated over. The parser methods only apply to the current contribution.
  By default after readEvent() the first contribution after the GEM
  contribution is the current contribution. Use the setCurrentContribution
  method to change the current contribution. Use the getContributionList
  method to find out which contributions exist in the event.

  Available parser methods:
    - evDumpSummary()
    - evDumpCAL_LogAccepts()
    - evDumpCAL_Logs()
    - evDumpTKR()
    - evDumpDiagnostic()
    - evDumpTEM_Error()
    - evDumpEventAEM()

  Contribution related methods:
  - getContributionList()
  - getCurrentContribution()
  - setCurrentContribution()
  - dumpContributionData()

  Retrieving the timestamp and timebase:
  - evGetTimestamp()
  - evGetTimebase()

\b Usage:

  For reading events from a socket:
  \code
    from gEvtCli import *
    ec = EvtCli(debug=0)
    ec.connect('gitot')
    while ec.readEvent() == 0:
      ec.setCurrentContribution(...)
      if ec.getContributionStatus() == 0:
        ec.evDumpXXX()
        :
      else:
        print "Error %s in contribution %s ",
          (ec.getContributionStatusStr(), cId)
    ec.disconnect()
  \endcode
  For reading events from an archived event file:
  \code
    from gEvtCli import *
    ec = EvtCli(debug=0)
    ec.open('030305165528.ldf')
    while ec.readEvent() == 0:
      ec.setCurrentContribution(...)
      if ec.getContributionStatus() == 0:
        ec.evDumpXXX()
        :
      else:
        print "Error %s in contribution %s ",
          (ec.getContributionStatusStr(), cId)
    ec.close()
  \endcode
  For looping over contributions:
  \code
    from gEvtCli import *
    ec = EvtCli(debug=0)
    ec.connect('gitot')
    status = ec.readEvent()
    contList = ec.getContributionList()
    for cId in contList:
      ec.setCurrentContribution(cId)
      if ec.getContributionStatus() == 0:
        ec.evDumpSummary()
        if cId.startswith('TEM'):
          ec.evDumpCAL_LogAccepts()
          ec.evDumpCAL_Logs()
          ec.evDumpTKR()
          ec.evDumpTEM_Error()
          ec.evDumpDiagnostic()
        elif cId == 'AEM':
          ec.evDumpEventAEM()
      else:
        print "Error %s in contribution %s ",
          (ec.getContributionStatusStr(), cId)
  \endcode
  """

  __SWEEP_MARKER = 5            # Arbitrary marker value for recognizing
                                #   when the event pipeline is flushed
  EVENT_SRC_SOCK = 0
  EVENT_SRC_FILE = 1
  DATAGRAM_IDENTITY = 0x201F1010
  UNRECOGNIZED_BUFFER_IDENTITY = 0x201F1020
  MINIMAL_BYTES = 32
  FIRST_CONTRIBUTION_OFFSET = 4 # In 32-bit words
## New event format
##  EXPECTED_EVENT_VERSION = 0x101F0010
##  EXPECTED_EVENT_VERSION = 0x102F0010
##  EXPECTED_EVENT_VERSION = 0x103F0010
  EXPECTED_EVENT_VERSION = 0x104F0010
##

  # Errors that the getOnlineStatus() method can return
  ERROR_BASE             = 0x1000
  GGLT_STATUS_ERROR      = ERROR_BASE + (1 << 0)
  MINIMAL_SIZE_ERROR     = ERROR_BASE + (1 << 1)
  EOE_ERROR              = ERROR_BASE + (1 << 2)
  UNPACK_ERROR           = ERROR_BASE + (1 << 3)
  IO_ERROR               = ERROR_BASE + (1 << 4)
  EVENT_VERSION_MISMATCH = ERROR_BASE + (1 << 5)
  PLAYBACK_ERROR         = ERROR_BASE + (1 << 6) # Agrees with evtSvr.c
  READ_TIMEOUT_ERROR     = ERROR_BASE + (1 << 7)
  EOF_ERROR              = ERROR_BASE + (1 << 8)
  ABORT_ERROR            = ERROR_BASE + (1 << 9)

  # Errors that the getContributionStatus() method can return
  CONTRIB_ERR_NONE        = 0
  CONTRIB_ERR_PARITY      = 1
  CONTRIB_ERR_TRUNCATED   = 2
  CONTRIB_ERR_WRITE_FAULT = 3
  CONTRIB_ERR_TIMEDOUT    = 4

  CONTRIBUTOR = {  0:'TEM0',
                   1:'TEM1',
                   2:'TEM2',
                   3:'TEM3',
                   4:'TEM4',
                   5:'TEM5',
                   6:'TEM6',
                   7:'TEM7',
                   8:'TEM8',
                   9:'TEM9',
                  10:'TEM10',
                  11:'TEM11',
                  12:'TEM12',
                  13:'TEM13',
                  14:'TEM14',
                  15:'TEM15',
                  16:'GEM',
                  17:'AEM',
                  32:'OSW'
                }

  (
    TEM0,
    TEM1,
    TEM2,
    TEM3,
    TEM4,
    TEM5,
    TEM6,
    TEM7,
    TEM8,
    TEM9,
    TEM10,
    TEM11,
    TEM12,
    TEM13,
    TEM14,
    TEM15,
    GEM,
    AEM,
    _NA,_NA,_NA,_NA,_NA,_NA,_NA,_NA,_NA,_NA,_NA,_NA,_NA,_NA,
    OSW,
  ) = \
  ( range (0,33) )

  # Debug levels
  DEBUG_NONE          = 0
  DEBUG_ALL           = 1
  DEBUG_EVENT_DUMP    = 1 << 1
  DEBUG_WARNINGS      = 1 << 2
  DEBUG_PARSER_OUTPUT = 1 << 3
  DEBUG_ERROR_OUTPUT  = 1 << 4

  def __init__(self, debug=0, port=EvtCliIO.PortNumber):
    """\brief Event client constructor

    \param debug  Debug mode (0=Debug, 1=No debug)
    """

    if debug is None:
      self.setDebug(0)
    else:
      self.setDebug(int(debug))

    EvtCliIO.__init__(self, self.__debug, port)

    self.__sock              = None
    self.__src               = None
    self.evt                 = Evt()
    self.__evContPacket      = evContPacket_Singleton(0)
    self.__evSummary         = evSummary_Singleton(0)
    self.__evCellHeader      = evCellHeader_Singleton(0)
    self.__oes_status        = 0
    self.__online_status     = 0
    self.__evt_status        = None
    self.__evt_size          = None
    self.__version_info      = None
    self.latInterfaceStatus  = LATInterfaceStatus(0)

    # Make sure the custom event client does not override EvtCliIO.read() method
    customEvtCli = EvtCli.__subclasses__()
    if len(customEvtCli) != 0:
      customEvtCli = customEvtCli[0]
      if 'read' in customEvtCli.__dict__:
        raise RuntimeError, "Custom event client %s should not override the read() method" % customEvtCli.__name__

  def setDebug(self, debug):
    """\brief Set the debug mode

    \param debug Debug mode
                 The following debug modes are available and can be added together
                 for combinations:
                     0: No Debug
                     1: Debug All
                     2: Event Dump
                     4: Warnings
                     8: Parser Output
                    16: Error Output
    """
    self.__debug             = debug
    self.__debugWarnings     = debug & (EvtCli.DEBUG_ALL | EvtCli.DEBUG_WARNINGS)
    self.__debugEventDump    = debug & (EvtCli.DEBUG_ALL | EvtCli.DEBUG_EVENT_DUMP)
    self.__debugErrorOutput  = debug & (EvtCli.DEBUG_ALL | EvtCli.DEBUG_ERROR_OUTPUT)
    self.__debugParserOutput = debug & (EvtCli.DEBUG_ALL | EvtCli.DEBUG_PARSER_OUTPUT)


  def readEvent(self, dat=None):
    """\brief Read an event

    Reads one event from an archive file or socket

    \param  dat If not None then interpret this data as event instead

    \return     oes_status
    """
    evt = self.evt
    evt.clearEvent()
    evt.cont_offset = EvtCli.FIRST_CONTRIBUTION_OFFSET
    self.__online_status = 0

    if dat is not None:
      header = (0,)
      header += struct.unpack('!5L', dat[0:20])
      self.dat = dat
    else:
      (header, self.dat) = self.read()
      if header is None:
        return EvtCli.ABORT_ERROR

    self.header = header

    self.__oes_status   = header[0]
    self.__version_info = header[3]
    self.__evt_status   = header[4] >> 16
    self.__evt_size     = header[4] & 0xFFFF

    if self.__debugEventDump:
      print "OES status    = 0x%08x" % self.__oes_status
      print "Event version = 0x%08x" % self.__version_info
      dump_cells(self.dat)
    if self.__oes_status != 0:
      raise LATInterfaceException(self.__oes_status)
    if len(self.dat) < EvtCli.MINIMAL_BYTES:
      self.__online_status |= EvtCli.MINIMAL_SIZE_ERROR
      if self.__debugWarnings:
        log.error("*** gEvtCli: datagram size %d less than minimal bytes %d"
                  %(len(self.dat), EvtCli.MINIMAL_BYTES))

    if self.__version_info != EvtCli.EXPECTED_EVENT_VERSION:
      self.__online_status |= EvtCli.EVENT_VERSION_MISMATCH
      if self.__debugWarnings:
        log.error("*** gEvtCli: event version 0x%08x is not the expected 0x%08x"
                  %(self.__version_info, EvtCli.EXPECTED_EVENT_VERSION))

    if self.__online_status != 0:
      return self.__online_status

    # Get the summary word stored in the OSW contribution
    # to determine if the event has error.
    evt.summary = self.__evSummary(self.getDWord(self.evGetSummary()))

    if self.__debugEventDump:
      print "\nEvent Size            =", self.__evt_size
      print "Event Status          =", self.__evt_status
      ts = self.evGetTimestamp()
      print "Event Timestamp (GMT) =", asctime(gmtime(ts)), \
                                      "and", int(modf(ts)[0]*1000), "ms"
      print "Event timebase        =", hex(self.evGetTimebase())
      print "Event Sequence MSW    =", hex(self.evGetEvtSeqMSW())
      print "Event Sequence        =", hex(self.evGetEvtSequence())

    self.__evt_error = self.evt.summary.error
    self.__evt_trgParityError = self.evt.summary.trgParityErr
    # Get the OSW container packet
    osw_packet = self.__evContPacket(self.getDWord(evt.cont_offset) & 0xFFFF)
    self.__evt_packetError = osw_packet.error

    # Contribution offset (skip over the OSW contribution)
    evt.cont_offset += ((header[5] & 0xFFFF) << 2)
    cont_header = self.getDWord(evt.cont_offset)
    evt.cont_packet = self.__evContPacket(cont_header & 0xFFFF)
    evt.cont_status = evt.cont_packet.error
    evt.summary = self.__evSummary(self.getDWord(self.evGetSummary()))
    evt.cont_cellHeader = self.__evCellHeader(cont_header >> 16)
    evt.contributor = evt.cont_cellHeader.source
    evt.cont_size   = (cont_header & 0x00FF) << 4
    evt.cont_end    = (evt.cont_offset << 2) + evt.cont_size

    if self.__debugEventDump:
      print
      self.dumpContributionData()

    return self.__online_status

  def getGGLTStatus(self):
    """\brief Retrieve the GGLT status.

    If this status value is non zero then the event is considered "bad"
    """
    return self.__oes_status

  def getGGLTStatusStr(self):
    """\brief Return the string equivalent of the GGLT status code.

    """
    return self.latInterfaceStatus.errstr(self.__oes_status)

  def getOnlineStatus(self):
    """\brief Retrieve the Online status code.

    See getOnlineStatusStr method for a list of possible errors

    """
    return self.__online_status

  def getEvtStatus(self):
    """\brief Return the event status from the event header.

    """
    return self.__evt_status

  def getContributionStatus(self):
    """\brief Return the contribution status

    \return Contribution status
    """
    return self.evt.cont_status

  def getContributionStatusStr(self):
    """\brief Return the contribution status string

    \return Contribution status string
    """
    statusList = {0: 'NONE',
                  1: 'PARITY',
                  2: 'TRUNCATED',
                  3: 'WRITE_FAULT',
                  4: 'TIMEDOUT',
                 }
    if self.evt.cont_status in statusList:
      return statusList[self.evt.cont_status]
    else:
      return 'UNKNOWN ERROR'

  def getOnlineStatusStr(self):
    """\brief Retrieve the string equivalent of the Online status code.

    The error can be one of the following:

    GGLT_STATUS_ERROR     : A bad event was received. Call getGGLTStatusStr method
                            for the description.
    MINIMAL_SIZE_ERROR    : The event size was below the acceptable size.
    EOE_ERROR             : End of event was reached before the parse completed.
    UNPACK_ERROR          : There was an error while unpacking part of the event for parsing.
    IO_ERROR              : An I/O error occurred while retrieving the event (socket or file).
    EVENT_VERSION_MISMATCH: An event with an old or unsupported format was received.
    PLAYBACK_ERROR        : End of file was received while playing back an event archive file.
    READ_TIMEOUT_ERROR    : A read timeout occurred while waiting for the event to be
                            retrieved (Set by rcTransitions).
    EOF_ERROR             : End of file is reached while reading the event file.

    \return Online status string

    """
    statusList = ['GGLT_STATUS_ERROR',
                  'MINIMAL_SIZE_ERROR',
                  'EOE_ERROR',
                  'UNPACK_ERROR',
                  'IO_ERROR',
                  'EVENT_VERSION_MISMATCH',
                  'PLAYBACK_ERROR',
                  'READ_TIMEOUT_ERROR',
                  'EOF_ERROR',
                 ]
    s = ''
    status = self.__online_status & 0xFFF
    bitIndex = 0
    while (bitIndex < 12):
      if (1 << bitIndex) & status:
        if bitIndex < len(statusList):
          s += statusList[bitIndex] + ' '
        else:
          s += 'UNKNOWN_ERROR '
      bitIndex += 1
    return s.strip()

  def getEvtSize(self):
    """\brief Return the event size

    \return Event size
    """
    return self.__evt_size

  def isErrorEvent(self):
    """Determines whether at least one contribution
    has the error bit set in its summary word.

    \return 1: If at least one contribution has an error.
            0: Otherwise
    """
    return self.__evt_error

  def isTrgParityErrorEvent(self):
    """Determines whether at least one contribution
    has the trigger parity error bit set in its summary word.

    \return 1: If at least one contribution has an error.
            0: Otherwise
    """
    return self.__evt_trgParityError

  def isPacketErrorEvent(self):
    """Determines whether at least one contribution
    has a non-zero packet error set in the EBF contribution.

    \return 1: If at least one contribution has an error.
            0: Otherwise
    """
    return self.__evt_packetError != 0

  def isSweepEvent(self):
    """\brief Determine if a sweep event is received.

    User script can call this method in process() to determine if
    the current event is a sweep event. A try block around the call
    should be used in case a bad event is received.

    \return 0: Not a sweep event.
            1: A sweep event.
    """
    if self.evt.summary.marker == EvtCli.__SWEEP_MARKER:
      return 1
    else:
      return 0

  def isGGLTStatus(self, status=None):
    """\brief Determine if the current event is bad.

    User script can call this method in process() to determine if
    the current event is a bad event (gglt_status != 0).

    \param  Optional status value

    \return 0: Not a bad event.
            1: A bad event.
    """
    if status is None: status = self.__online_status
    return self.checkOnlineStatus(status, EvtCli.GGLT_STATUS_ERROR)

  def checkOnlineStatus(self, status, mask):
    """\brief Checks if the bit mask \a mask matches the \a status that is
    assumed as an Online status.

    \param status The status word to be checked against
    \param mask   The mask bit(s) to be checked

    \return 1 if there is a match
            0 if there is no match

    """
    if status < 0:
      return 0
    elif not (status & 0x1000):
      return 0
    else:
      return status & mask & 0xFFF

  def checkGGLTstatus(self, status, mask):
    """\brief Checks if the bit mask \a mask matches the \a status
    that is assumed as a GGLT status.

    \param status The status word to be checked against
    \param mask   The mask bit(s) to be checked

    \return 1 if there is a match
            0 if there is no match

    """
    if status > 0:
      return 0
    elif status & 0x1000:
      return 0
    else:
      return status & mask

  # The following function is experimental code: Do Not Use.
  def readEventSocket(self):
    # Maybe better to do this with setsockopt(SO_RCVLOWAT, 12) and select()
    l   = 0
    buf = ""
    while l < 12:
      buf += self.recv(4096 - l)
      l    = len(buf)
    (retCode, version, status, length) = self.unpack('!lLhH', buf[0:12])
    i = 0
    #print "readEventSocket:           %u, length = %u, l = %u" % (i, length, l)
    while l < length:
      buf += self.recv(4096 - l)
      l    = len(buf)
      i   += 1
      print "readEventSocket: Got more: %u, length = %u, l = %u" % (i, length,l)
    return (retCode, buf, l)

  def setCurrentContribution(self, contributionId):
    """\brief Given a contribution id, set the current contribution data
    needed for the parsing routines.

    \param  contributionId Integer contribution id

    \return The offset to the contribution requested.
            -1 If the contribution requested is not found
               or contribution offset was found to be larger
               than the event size
            Note: Use getContributionStatus() method after
               calling this routine to find out if the
               contribution has an error.

    """
    cont_offset = EvtCli.FIRST_CONTRIBUTION_OFFSET
    if isNumberType(contributionId):
      cId = contributionId
    else:
      for (key, value) in EvtCli.CONTRIBUTOR.items():
        if value == contributionId:
          cId = key
          break
    evt = self.evt
    while(True):
      cont_header = self.getDWord(cont_offset)
      evt.cont_packet = self.__evContPacket(cont_header & 0xFFFF)
      contributor = (cont_header >> 17) & 0x3F
      cont_size = evt.cont_packet.length << 4
      cont_cellHeader = self.__evCellHeader(cont_header >> 16)
      if contributor == cId:
        evt.cont_status = evt.cont_packet.error
        # Make sure it is a good contribution
        if evt.cont_status == 0:
          evt.cont_cellHeader = cont_cellHeader
          evt.contributor = contributor
          evt.cont_size = cont_size
          evt.cont_offset = cont_offset
          evt.cont_end = (cont_offset << 2) + cont_size
          evt.summary = self.__evSummary(self.getDWord(self.evGetSummary()))
          if self.__debugEventDump:
            self.dumpContributionData()
          return self.evt.cont_offset
      cont_offset += (cont_size >> 2)
      if cont_cellHeader.respond == 0:
        return -1
      if not (self.__evt_size > (cont_offset << 2)):
        return -1

  def getCurrentContribution(self):
    """\brief Return the integer id of the current contribution

    \return Current constribution id
    """
    return self.evt.cont_cellHeader.source

  def getContributionList(self):
    """\brief Walk through the whole event and construct a list of contribution id strings

    \return A list of contributors that have contributed to the current event
    """
    cont_offset = EvtCli.FIRST_CONTRIBUTION_OFFSET
    contributorList = []
    evt = self.evt
    while(True):
      cont_header = self.getDWord(cont_offset)
      cont_size = (cont_header & 0x00FF) << 4
      evt.cont_cellHeader = self.__evCellHeader(self.getDWord(cont_offset) >> 16)
      #if cont_size == 0:
      #  return contributorList
      contributor = (cont_header >> 17) & 0x3F
      contributorList = contributorList + [EvtCli.CONTRIBUTOR[contributor]]
      cont_offset += (cont_size >> 2)
      if evt.cont_cellHeader.respond == 0:
        return contributorList
      if not (self.__evt_size > (cont_offset << 2)):
        return contributorList

  def dumpContributionData(self):
    """\brief Prints out information pertaining to the current contribution.

    """
    if self.getContributionStatus() != 0:
      print("   *** WARNING *** WARNING *** WARNING *** WARNING *** WARNING ***")
      print("   ***    This contribution is suspect. Error: %-15s ***"
            % self.getContributionStatusStr())
      print("   *** WARNING *** WARNING *** WARNING *** WARNING *** WARNING ***\n")

    self.evDumpSummary(16)
    print
    print "Event Contributor=", EvtCli.CONTRIBUTOR[self.evt.contributor]
    print "Contribution size=", self.evt.cont_size
    print "\nPacket     = 0x%04X" % int(self.evt.cont_packet)
    print "\terror      =", hex(int(self.evt.cont_packet.error))
    print "\tsequence   =", hex(int(self.evt.cont_packet.sequence))
    print "\tlength     =", hex(int(self.evt.cont_packet.length))
    print "\nCell header= 0x%04X" % int(self.evt.cont_cellHeader)
    print "\tparity     =", hex(int(self.evt.cont_cellHeader.parity))
    print "\tsource     =", hex(int(self.evt.cont_cellHeader.source))
    print "\tprotocol   =", hex(int(self.evt.cont_cellHeader.protocol))
    print "\tdestination=", hex(int(self.evt.cont_cellHeader.destination))
    print "\trespond    =", hex(int(self.evt.cont_cellHeader.respond))
    dump_cells(self.dat[(self.evt.cont_offset<<2):self.evt.cont_end])
    print

  def evGetTimestamp(self):
    """\brief Return the timestamp of the event in seconds.

    The resolution of this timestamp is 1/60th of a second, by default.
    Consult VxWorks documentation for sysClkRateSet() and clock_setres()
    to see how to change this default. Beware that increasing the resolution
    from the default may cause adverse effects due to the increased
    interrupt rate generated.

    \return Timestamp of the event in seconds.
    """
## New Event Format
##    tv_sec  = self.getDWord(EvtCli.FIRST_CONTRIBUTION_OFFSET+2)
##    tv_nsec = self.getDWord(EvtCli.FIRST_CONTRIBUTION_OFFSET+3)
    tv_sec  = self.getDWord(EvtCli.FIRST_CONTRIBUTION_OFFSET+3)
    tv_nsec = self.getDWord(EvtCli.FIRST_CONTRIBUTION_OFFSET+4)
##
    return (tv_sec + (tv_nsec / 1000000000.0))

  def evGetTimebase(self):
    """\brief Return the timestamp of the event derived from the PPC timebase register.

    This is a 64 bit value that increments at an SBC implementation dependant
    rate (60 nS on MVME2306s).  The value is reset at PPC reset time.

    \return Timestamp of the event in PPC timebase ticks.
    """
    return self.unpack('!Q',
## New event format
##                       self.dat[(EvtCli.FIRST_CONTRIBUTION_OFFSET+4) << 2:
##                                (EvtCli.FIRST_CONTRIBUTION_OFFSET+6) << 2])[0]
                       self.dat[(EvtCli.FIRST_CONTRIBUTION_OFFSET+5) << 2:
                                (EvtCli.FIRST_CONTRIBUTION_OFFSET+7) << 2])[0]
##

  # Not used anymore -ST
  #def extend(self, buffer):
  #  if self.dat is not None:
  #    self.dat += buffer

  def evGetEvtSeqMSW(self):
    """\brief Return the MSW portion of the event sequence

    \return MSW portion of the event sequence.
    """
    return self.getDWord(EvtCli.FIRST_CONTRIBUTION_OFFSET+7)

  def evGetEvtSequence(self):
    """\brief Return the Event Sequence

    \return Event sequence.
    """
    return ((self.evGetEvtSeqMSW()     << 17) |
            (self.evt.summary.evNumber <<  2) |
            (self.evt.summary.tag      <<  0)
          )

  def getUserId(self):
    """\brief Return the user id passed to the event client.

    \return Current user id
    """
    return 123 # Deprecated.

  def evGetTKR_Accepts(self, pAccept):
    """\brief Walks tower event contribution to the TKR accepts data.

    Fills in the evGetTKR_Accepts structure pointed to by \a pAccept
    with the TKR accepts data.  Also returns a pointer to the TKR
    accepts information.

    \param   pAccept Array to be filled with TKR accepts data
    \return  Offset to the start of TKR accepts data

    """
    p = self.evGetCAL_LogAccepts() + 1 + self.evGetCAL_NumAccepts() * (1 + 3 * self.evt.summary.readout4)
    if pAccept != None:
      for i in range(N_GTCC):
        dWordOffset = int(p + (9 * i) / 32)
        bitOffset  = (9 * i) % 32
        if ((32 - bitOffset) >= 9):
          if (dWordOffset << 2) > self.evt.cont_end:
            self.print_EOE_Warning()
            return -1
          pAccept[i] = (self.getDWord(dWordOffset) >> (32 - bitOffset - 9)) & 0x1FF
          self.evt.addTKRaccept(pAccept[i])
        else:
          if ((dWordOffset+1) << 2) > self.evt.cont_end:
            self.print_EOE_Warning()
            return -1
          pAccept[i] = (self.getDWord(dWordOffset)   << (9 - (32 - bitOffset)) & 0x1FF) | \
                       (self.getDWord(dWordOffset+1) >> (32 - (9 - (32 - bitOffset))))
          self.evt.addTKRaccept(pAccept[i])
    return p

  def evGetCAL_NumAccepts(self):
    """\brief Counts the number of hit calorimeter logs in the tower
    event contribution.

    Given a pointer to an entire TEM event contribution walk the data
    structure to the calorimeter log accepts word and return the sum of
    the number of hit logs.

    \return Number of hit logs
    """
    nAccepts = 0
    la = self.getDWord(self.evGetCAL_LogAccepts())
    for i in range(8):
      nAccepts = nAccepts + ((la >> (i<<2)) & 0xF)
    return nAccepts

  def evDumpGEM(self):
    """\brief Parses the GEM contribution by populating the data in self.evt.gem

    Requires calling evtCli.setCurrentContribution(EvtCli.GEM) before usage.

    """
    offset = self.evGetSummary() + 1
    val = self.getDWord(offset)
    self.evt.gem.ROI_Vector = (val >> 16)
    self.evt.gem.TKR_Vector = val & 0xFFFF
    val = self.getDWord(offset+1)
    self.evt.gem.CAL_HE_Vector = (val >> 16)
    self.evt.gem.CAL_LE_Vector = val & 0xFFFF
    val = self.getDWord(offset+2)
    self.evt.gem.triggerSummary = (val >> 16)
    self.evt.gem.deadzone = (self.evt.gem.triggerSummary >> 8)
    self.evt.gem.conditions = self.evt.gem.triggerSummary & 0xFF
    self.evt.gem.CNO_Vector = val & 0xFFFF
    self.evDumpGEM_Veto_List(offset+3)
    self.evt.gem.liveTime = self.getDWord(offset+7)
    self.evt.gem.prescaled = self.getDWord(offset+8)
    self.evt.gem.discarded = self.getDWord(offset+9)
    self.evt.gem.sent = self.getDWord(offset+10) # Deprecated
    self.evt.gem.condArrivalTimes.set(self.evt.gem.sent)
    self.evt.gem.triggerTime = self.getDWord(offset+11)
    self.evt.gem.onePPSTime = self.getDWord(offset+12)
    val = self.getDWord(offset+13)
    self.evt.gem.deltaOpenWindowTime = (val >> 16)
    self.evt.gem.deltaEventTime = val & 0xFFFF

    if self.__debugParserOutput:
      print "   ROI vector    = 0x%04x" % self.evt.gem.ROI_Vector
      print "   TKR vector    = 0x%04x" % self.evt.gem.TKR_Vector
      print "   CAL HE vector = 0x%04x" % self.evt.gem.CAL_HE_Vector
      print "   CAL LE vector = 0x%04x" % self.evt.gem.CAL_LE_Vector
      print "   Dead zone     = 0x%02x" % self.evt.gem.deadzone
      print "   Conditions    = 0x%02x" % self.evt.gem.conditions
      print "   CNO Vector    = 0x%04x" % self.evt.gem.CNO_Vector
      print "   Veto List:"
      print "     XZP, XZM    = 0x%04x, 0x%04x" % (self.evt.gem.vetoList.XZP,
                                                   self.evt.gem.vetoList.XZM)
      print "     YZP, YZM    = 0x%04x, 0x%04x" % (self.evt.gem.vetoList.YZP,
                                                   self.evt.gem.vetoList.YZM)
      print "     XY          = 0x%04x"         %  self.evt.gem.vetoList.XY
      print "     NA, RBN     = 0x%04x, 0x%04x" % (self.evt.gem.vetoList.NA,
                                                   self.evt.gem.vetoList.RBN)
      print "   Live time     = 0x%08x" % self.evt.gem.liveTime
      print "   Prescaled     = 0x%08x" % self.evt.gem.prescaled
      print "   Discarded     = 0x%08x" % self.evt.gem.discarded
      print "   Condition arrival:"
      print "     raw         = 0x%08x" % self.evt.gem.condArrivalTimes.ui
      print "     external    = 0x%02x" % self.evt.gem.condArrivalTimes.External
      print "     cno         = 0x%02x" % self.evt.gem.condArrivalTimes.CNO
      print "     calHE       = 0x%02x" % self.evt.gem.condArrivalTimes.CAL_HE
      print "     calLE       = 0x%02x" % self.evt.gem.condArrivalTimes.CAL_LE
      print "     tkr         = 0x%02x" % self.evt.gem.condArrivalTimes.TKR
      print "     roi         = 0x%02x" % self.evt.gem.condArrivalTimes.ROI
      print "   Trigger time  = 0x%08x" % self.evt.gem.triggerTime
      print "   One PPS time  = 0x%08x" % self.evt.gem.onePPSTime
      print "   Delta window open time = 0x%04x" % self.evt.gem.deltaOpenWindowTime
      print "   Delta event time       = 0x%04x" % self.evt.gem.deltaEventTime
      print

  def evDumpGEM_Veto_List(self, offset):
    """\brief Parses the Veto List block of the GEM contribution

    Used by evDumpGEM

    \param offset 32-bit word offset to the veto list block

    """
    veto = self.getDWord(offset)
    self.evt.gem.vetoList.XZP = (veto >> 16)
    self.evt.gem.vetoList.XZM = veto & 0xFFFF
    veto = self.getDWord(offset+1)
    self.evt.gem.vetoList.YZP = (veto >> 16)
    self.evt.gem.vetoList.YZM = veto & 0xFFFF
    self.evt.gem.vetoList.XY = self.getDWord(offset+2)
    veto = self.getDWord(offset+3)
    self.evt.gem.vetoList.NA = (veto >> 16)
    self.evt.gem.vetoList.RBN = veto & 0xFFFF

  def getWord(self,wordOffset):
    """\brief Unpack and return a 16-bit word value located at wordOffset

    \param  wordOffset Pointer to data

    \return            16-bit word value
    """
    result = self.unpack('!H',self.dat[(wordOffset<<1):((wordOffset+1)<<1)])
    if result != ():
      return result[0]
    else:
      return 0

  def getDWord(self,dWordOffset):
    """\brief Unpack and return a 32-bit word value located at dWordOffset

    \param  dWordOffset Pointer to data

    \return             32-bit word value
    """
    result = self.unpack('!L',self.dat[(dWordOffset<<2):((dWordOffset+1)<<2)])
    if result != ():
      return result[0]
    else:
      return 0

  def getByte(self,byteOffset):
    """\brief Unpack and return an 8-bit byte value located at byteOffset

    \param  byteOffset Pointer to data

    \return            8-bit byte value
    """
    result = self.unpack('B',self.dat[byteOffset])
    if result != ():
      return result[0]
    else:
      return 0

  def evGetCAL_Logs(self):
    """\brief Walks tower event contribution to the CAL log data.

    Given a pointer to an entire TEM event contribution walk the data
    structure to the beginning of the calorimeter log data.

    \return Offset to the beginning of the calorimeter log data
    """
    return self.evGetCAL_LogAccepts() + 1

  def evGetCAL_LogAccepts(self):
    """\brief Walks the tower event contribution to the calorimeter
    log accepts word.

    Given a pointer to an entire TEM event contribution walk the data
    structure returning a pointer to the calorimeter log accepts word.

    The 32-bit calorimeter log accepts word is immediately after the event
    summary word, i.e. the 2nd 32-bit word in the data.

    \return Offset to the calorimeter log accepts word.
    """
    return self.evGetSummary() + 1

  def evDumpCAL_LogAccepts(self):
    """\brief Decodes the log accepts word and stores it in evt.CAL_LogAccepts.

    """
    la = evCAL_LogAccepts(self.getCurrentContribution(), self.getDWord(self.evGetCAL_LogAccepts()))
    if self.__debugParserOutput:
      print("\n   CAL Log Accepts")
      # look for bogus accept values ( anything greater than 12 )
      for i in range(N_GCCC):
        if ((la.ui >> (i<<2)) & 0xF) > 12:
          print("   *** WARNING *** WARNING *** WARNING *** WARNING *** WARNING ***")
          print("   *** Log accepts greater than 12.  This event is suspect     ***")
          print("   *** WARNING *** WARNING *** WARNING *** WARNING *** WARNING ***\n")

      print("   ================================================")
      print("   GCCC   | GCCC_01 | GCCC_03 | GCCC_02 | GCCC_00 |")
      print("   -------+---------+---------+---------+---------+-------------")
      print("   layer  | y3   y2 | y1   y0 | x3   x2 | x1   x0 |  Raw")
      print("   -------+----+----+----+----+----+----+----+----+-------------")
      print("   hits   | %02d   %02d | %02d   %02d | %02d   %02d | %02d   %02d |  0x%08x" %
           (la.y3, la.y2, la.y1, la.y0, la.x3, la.x2, la.x1, la.x0, la.ui))
    self.evt.addCAL_LogAccept(la)


  def evDumpCAL_Logs(self):
    """\brief Decodes all the log data for the event and stores it in evt.CAL_LogData

    """
    la = evCAL_LogAccepts(0, self.getDWord(self.evGetCAL_LogAccepts()))
    if ( la.ui == 0 ):
      # nothing to decode
      return

    # get log data
    pLogData = self.evGetCAL_Logs()

    if self.__debugParserOutput:
      print("\n   CAL Log Data")
      print("   =====================================================")
      print("   -----   -----+------+------+------+------+-----------")
      print("   layer    Col   -Rng   -ADC   +Rng   +ADC   Raw")
      print("   -----   -----+------+------+------+------+-----------")

    twr = self.getCurrentContribution()
    if ( self.evt.summary.readout4 == 0):
      # regular read out
      # step through the 8 layers
      for i in range(8):
        nHitLogs = (la.ui >> (i<<2)) & 0xF
        if (nHitLogs):
          for j in range(nHitLogs):
            self.__dumpCAL_Log(twr, pLogData, i)
            pLogData = pLogData + 1
    else:
      # read out 4 range data
      # loop over accepts in groups of 2 -- 8 all together
      for i in range(4):
        # loop over 4 ranges
        for j in range(4):
          # loop over current 2 accepts
          for k in range(2):
            nHitLogs = (la.ui >> (((i<<1) + k)<<2)) & 0xF
            for l in range(nHitLogs):
              self.__dumpCAL_Log(twr, pLogData, ((i<<1) + k))
              pLogData = pLogData + 1

  def __dumpCAL_Log(self, twr, pLogData, layer):
    """\brief Decodes the log data

    \param pLogData Pointer to data from one accepted CAL log
    \param layer    Which layer the log data is a member of

    """
    if (pLogData<<2) > self.evt.cont_end:
      self.print_EOE_Warning()
    else:
      ld = evCAL_LogData(self.getDWord(pLogData))
      if self.__debugParserOutput:
        print("    %c%d       %02d    %d     %04x    %d     %04x   0x%08x" %
          (q(layer < 4,'x','y'), layer % 4,
          ld.column,
          ld.rangeADC_neg,
          ld.valADC_neg,
          ld.rangeADC_pos,
          ld.valADC_pos,
          ld.ui))
      self.evt.addCAL_LogData(twr, layer, ld)


  def evGetSummary(self):
    """\brief Return the offset to the summary word of the current contribution.

    In a contribution, first word after the header is the summary word

    \return Offset to the summary word of the current contribution
    """
    return self.evt.cont_offset + 1

  def __dumpTkrStrip(self, pAccepts, acceptArray):
    """\brief Decodes all TKR event strip data and stores it in evt.TKRstrips

    \param  pAccepts     Pointer to 32-bit aligned tracker event data
    \param  acceptArray  pointer to array of decoded tkr accept vectors

    \return              Number of strip hits
    """
    nStrip = 0
    if self.__debugParserOutput:
      print("\n   TKR Strips")
      print("   ========================================================")
      print("   GTCC  | GTRC | GTFE | Strip # | Raw      |")
      print("   ------+------+------+---------+----------+")
    stripData = evTKR_Strip(0)
    for i in range(N_GTCC):
      # foreach set bit in GTCC accept vector
      accept = acceptArray[i]
      for j in range(N_GTRC):
        if ( (accept >> (N_GTRC - 1 - j)) & 0x1):
          # walk strip data until done bit found
          done = 0
          while 1:
            stripData = self.evGetTKR_StripN(pAccepts, nStrip)

            if stripData.done != 0:
              stripData.done = 0
              done = 1
            self.evt.addTKRstrip(GTCC_MAP[i], j, stripData)
            nStrip = nStrip + 1
            if self.__debugParserOutput:
              print("    %d    |  %d   |  %02d  |   %02d    | 0x%03x    |" % (GTCC_MAP[i], j, stripData.gtfe, stripData.strip, stripData.ui))
            if done != 0: break
    return nStrip

  def evGetTKR_StripN(self, pAccepts, stripN, stripData=None):
    """\brief Fetches a 12-bit strip word from pAccepts, indexed by stripN.

    pAccepts points to the top of the accepts data ... the strip data
    starts 72 bits ( 8 * 9 ) from the beginning of accepts.  I.e. it
    starts 8 bits into the 3rd 32-bit word.

    \param  pAccepts  Pointer to 32-bit aligned tracker event data
    \param  stripN    The index of the 12-bit strip to fetch from pAccepts
    \param  stripData Optional argument, if passed, avoid creating the object
    \return          An evTKR_Strip object instance.
    """
    # Don't create the object if we are only counting, ie. called from evGetTKR_NumStrips()
    if stripData is None:
      stripData = evTKR_Strip(0)
    # skip the first two 32-bit words
    pAccepts = pAccepts + 2
    # each strip is 12 bits long.  the first strip starts 8 bits into the 32-bit word
    nBits = 8 + 12 * stripN
    dWordOffset = pAccepts + (nBits / 32)
    bitOffset = nBits % 32
    if ((32 - bitOffset) >= 12):
      if (dWordOffset<<2) > self.evt.cont_end:
        self.print_EOE_Warning()
        stripData.done = 1
      else:
        # all 12 bits are in this word
        stripData.ui = (self.getDWord(dWordOffset) >> (32 - bitOffset - 12)) & 0xFFF
    else:
      if ((dWordOffset+1)<<2) > self.evt.cont_end:
        self.print_EOE_Warning()
        stripData.done = 1
      else:
        # need to sew bits together across word boundary
        stripData.ui = (((self.getDWord(dWordOffset)   << ( 12 - ( 32 - bitOffset))) & 0xFFF) | \
                    (self.getDWord(dWordOffset+1) >> ( 32 - ( 12 - ( 32 - bitOffset)))))
    return stripData


  def __dumpTkrTOT(self, pAccepts, acceptArray, nStrip):
    """\brief Decodes all TKR event TOT data and stores them in evt.TKTtots

    \param pAccepts    Pointer to 32-bit aligned tracker event data
    \param acceptArray Pointer to array of decoded tkr accept vectors
    \param nStrip      Number of TKR strips decoded

    """
    if self.__debugParserOutput:
      print("\n   TKR TOT")
      print("   ========================================================")
      print("   GTCC  | GTRC | TOT    |")
      print("   ------+------+--------+")

    #determine where TOTs start -- count 8-bit bytes from the begining of the accepts
    #accepts bits = 9 bits * 8 GTCC = 72 bits = 9 bytes
    #strip bits   = 12 bits * nStrip = (12 bits * nStrip)/8 bytes

    #if nStrip is odd then we're on a nibble boundry -- add one more byte

    byteSkip = 9 + (( 12 * nStrip ) / 8)
    if ( nStrip & 0x1 ):
      byteSkip += 1
    # foreach GTCC
    for i in range(N_GTCC):
      # foreach set bit in GTCC accept vector
      for j in range(N_GTRC):
        if ( (acceptArray[i] >> (N_GTRC - j - 1)) & 0x1):
          # print TOT
          byteOffset = (pAccepts<<2) + byteSkip
          if byteOffset > self.evt.cont_end:
            self.print_EOE_Warning()
            return -1
          tot = self.getByte(byteOffset)
          if self.__debugParserOutput:
            print("    %d    |  %d   | 0x%02x   |"%(GTCC_MAP[i], j, tot))
          byteSkip += 1
          self.evt.addTKRtot(GTCC_MAP[i], j, tot)

  def evDumpTKR(self):
    """\brief Decodes all the TKR event data and stores it in the event object.

    """
    tkrAcpt = [0]*N_GTCC
    nAccept = 0

    p = self.evGetTKR_Accepts(tkrAcpt)
    if p == -1: return
    if self.__debugParserOutput:
      print("\n   TKR Accepts")
      print("   ========================================================")
      #   print("   Raw word 0:  0x%08x\n", p[0])
      #   print("   Raw word 1:  0x%08x\n", p[1])
      #   print("   Raw word 2:  0x%08x\n", p[2])
      print("   ========================================================")
      print("   GTCC  |  X/Y  |  L/R  |  E/O  |  Accepts    | Raw")
      print("   ------+-------+-------+-------+-------------+-----------")
    for i in range(N_GTCC):
      if self.__debugParserOutput:
        print("    %d    |   %c   | %5s | %4s  |  " % (GTCC_MAP[i],
              q(i < 4,'x','y'),
              q(((i == 1) | (i == 2) | (i == 4) | ( i == 7)),"right","left"),
              q(i % 2,"even","odd"))),
      bits = ""
      for j in range(N_GTRC):
        if ( (tkrAcpt[i] >> (N_GTRC - j - 1)) & 0x1):
          bits += "1"
          nAccept += 1
        else:
          bits += "0"
      if self.__debugParserOutput:
        print("\b%s  | 0x%03x"%(bits,tkrAcpt[i]))
    if self.__debugParserOutput:
      print("   ------+-------+-------+-------+-------------+-----------")

    if (nAccept != 0):
      # dump strip data
      nStrips = self.__dumpTkrStrip(p, tkrAcpt)

      # dump TOT data
      self.__dumpTkrTOT(p, tkrAcpt, nStrips)

  def evBitCount(self, x):
    """\brief Count the number of set bits in x

    \param  x 32-bit word value

    \return   Set bit count
    """
    count = 0
    for i in range(32):
      count = count + (( x >> i ) & 0x1)
    return count


  def evGetTKR_NumStrips(self):
    """Returns number of hit strips in the event

    \return Number of hit strips
    """
    nStrip = 0
    tkrAcpt = [0]*N_GTCC

    pAccepts = self.evGetTKR_Accepts(tkrAcpt)
    if pAccepts == -1: return
    stripData = evTKR_Strip(0)
    # foreach GTCC
    for i in range(N_GTCC):
      # foreach set bit in GTCC accept vector
      for j in range(N_GTRC):
        if ( (tkrAcpt[i] >> (N_GTRC - 1 - j)) & 0x1):
          # walk strip data until done bit found
          done = 0
          while not done:
            stripData = self.evGetTKR_StripN(pAccepts, nStrip, stripData)
            done = stripData.done
            nStrip += 1
    return nStrip

  def evGetTKR_TOT(self):
    """\brief Returns pointer to start of tracker TOT list

    \return Offset to the tracker TOT list
    """
    nStrips = self.evGetTKR_NumStrips()

    if nStrips == 0:
      return 0


    #  the TOTs come after the accepts (72-bits or 9 bytes) and after
    #  the strips ( 12-bits per strip ).  If the number of strips is odd
    #  we need to add one extra byte.

    pTOT = self.evGetTKR_Accepts(None) << 2
    pTOT += 9  # size of the accept words
    pTOT += (( 12 * nStrips ) / 8) # size of the strip words
    pTOT += (nStrips & 0x1)  # pad with one byte if number of strips is odd
    return pTOT


  def evGetTKR_NumAccepts(self):
    """\brief Counts the number of accepted TKR layer-ends.

    \return Number of accepted TKR layer-ends.
    """
    tkrAcpt = [0]*N_GTCC
    self.evGetTKR_Accepts(tkrAcpt)

    nBits = 0
    for i in range(N_GTCC):
      nBits += self.evBitCount(tkrAcpt[i])
    return nBits


  def evGetTEM_Diagnostic(self):
    """\brief Returns pointer to start of diagnostic event data.

    Caller should check the event summary word if a diagnostic
    contribution is present before calling this function.

    \return Offset to start of diagnostic event data
    """
    start = self.evGetTKR_Accepts(None) << 2
    nTkrAccepts = self.evGetTKR_NumAccepts()
    if nTkrAccepts == 0:
      # no tracker strip data, just skip over tracker accept data
      end = start + 9
    else:
      end = self.evGetTKR_TOT() # beginning of TOT data
      end += nTkrAccepts # one byte after the TOT data

    #  the diagnostic data comes after the tracker data and must be on a
    #  32-bit boundary

    offset = end - start
    #offset = offset + q((offset % 4), 4 - (offset % 4), 0)
    if (offset % 4):
      offset += (4 - (offset % 4))
    return ((start + offset) >> 2)

  def evGetTEM_Error(self):
    """\brief Returns pointer to the error word contribution of event data.

    Caller should check the event summary word if an error
    contribution is present before calling this function.

    \return Offset to the error word contribution
    """
    # the error contribution comes after the diagnostic contribution
    pErr = self.evGetTEM_Diagnostic()
    # check if we have a diagnostic contribution
    es = self.evt.summary
    if es.diag:
      # skip over diagnostic contribution
      pErr += (evDiag_Data.size >> 2)
    return pErr


  def __dumpErrGCCC(self, es, pErr, nWord, forcePrint=0):
    """\brief Decodes the GCCC error contribution.

    \param  es         Error summary 16-bit word
    \param  pErr       Pointer to 16-bit aligned tower event error contribution
    \param  nWord      Index into begining of error data
    \param  forcePrint If specified, dump the error even if in non-debug mode

    \return            Current offset into the error contribution
    """
    errSummary = es

    if self.__debugParserOutput or forcePrint: print

    # loop over 4 GCCC
    for gcccId in range(N_GCCC):
      # test summary bit for this GCCC
      if ( ( errSummary.gcccErr >> gcccId) & 0x1 ):
        # dump the error message
        idx = nWord
        nWord += 1
        errLen = self.getWord(pErr+idx)
        if self.__debugParserOutput or forcePrint:
          print("GCCC error word count %d" % errLen)
        # obtained "mapped GCCC" number
        mGCCC = GCCC_MAP[gcccId]
        #layer = q(( mGCCC % 2 ),'y','x')
        if (mGCCC % 2):
          layer = 'y'
        else:
          layer = 'x'
        while (errLen):
          errLen -= 1
          idx = nWord
          nWord += 1
          errGCCC = evErr_GCCC(self.getWord(pErr+idx))
          self.evt.addErrGCCCmsg(evErr_GCCC_Message(mGCCC, errGCCC))
          if errGCCC.errType == 0:
            # start bit missing
            if self.__debugParserOutput or forcePrint:
              print("   GCCC %d Start Bit Missing: raw ( 0x%04x )" % (mGCCC, errGCCC.ui))
          elif errGCCC.errType == 1:
            # parity error
            if self.__debugParserOutput or forcePrint:
              print("   GCCC %d Parity Error: raw ( 0x%04x )\n" % (mGCCC, errGCCC.ui))
          else:
            # unknown GCCC error message
            print("****************************************************")
            print("**")
            print("** Unknown GCCC error message type:  %d\n" % errGCCC.errType)
            print("** Raw value                      :  0x%04x" % errGCCC.ui)
            print("**")
            print("****************************************************")
            return nWord
          # both error types have the same display format
          if self.__debugParserOutput or forcePrint:
            print("   ================================================")
            print("   | %c%d- | %c%d- | %c%d+ | %c%d+ | Sweep | Type |" %
              (layer, q(( mGCCC % 2 ) , (mGCCC + 2)%4 , mGCCC + 1),
               layer, q(( mGCCC % 2 ) , (mGCCC + 1)%4 , mGCCC),
               layer, q(( mGCCC % 2 ) , (mGCCC + 2)%4 , mGCCC + 1),
               layer, q(( mGCCC % 2 ) , (mGCCC + 1)%4 , mGCCC)
              )
            )
            print("   ------+-----+-----+-----+-------+------+--------")
            print("   | %d%d  | %d%d  | %d%d  | %d%d  |   %d   |  %d   |" %
              ((errGCCC.errParm >> 7) & 0x1, (errGCCC.errParm >> 6) & 0x1,
               (errGCCC.errParm >> 5) & 0x1, (errGCCC.errParm >> 4) & 0x1,
               (errGCCC.errParm >> 3) & 0x1, (errGCCC.errParm >> 2) & 0x1,
               (errGCCC.errParm >> 1) & 0x1, (errGCCC.errParm     ) & 0x1,
               errGCCC.sweepNum, errGCCC.errType
              )
            )
            print("   ------------------------------------------------")
            print
    return nWord


  def __dumpErrGTCC(self, es, pErr, nWord, forcePrint=0):
    """\brief Decodes the GTCC error contribution.

    \param  es         Error summary 16-bit word
    \param  pErr       Pointer to 16-bit aligned tower event error contribution
    \param  nWord      Index into begining of error data
    \param  forcePrint If specified, dump the error even if in non-debug mode

    \return            Current offset into the error contribution
    """
    errSummary = es

    # loop over 8 GTCC
    for gtccId in range(N_GTCC):
      # test summary bit for this GTCC
      if ( ( errSummary.gtccErr >> gtccId) & 0x1 ):
        # dump the error message
        errLen = curErrLen = self.getWord(pErr+nWord)
        # loop over all errors
        while (curErrLen):
          curErrWords = 0
          errGTCCmsg = evErr_GTCC_Message()
          errGTCC = evErr_GTCC(self.getWord(pErr+nWord+curErrLen))
          errGTCCmsg.errGTCC = errGTCC
          errGTCCmsg.gtcc = GTCC_ERR_MAP[gtccId]
          self.evt.addErrGTCCmsg(errGTCCmsg)
          if self.__debugParserOutput or forcePrint:
            print
            print ("   GTCC %d, GTRC %d Error Message: raw ( 0x%04x )" %
                    ( errGTCCmsg.gtcc,
                      errGTCC.nGTRC,
                      errGTCC.ui
                    )
                  )
            print("   ================================================")
          # process error bits from LSB upto LSB
          if errGTCC.phsGTRC:
            # print GTRC error parameter from stack
            curErrWords+=1
            err = self.getWord(pErr+nWord+curErrLen-curErrWords)
            errGTCCmsg.parameters['PHS_GTRC'] = err
            if self.__debugParserOutput or forcePrint:
              print("   GTRC Phasing Error:   0x%04x" % err)
              print("   =============+=============")
              print("       Layer    |     Tag")
              print("   Rcvd   Expct | Rcvd   Expct")
              print("   =============+=============")
              print("    %02d     %02d   |  %d      %d" % ((err>>12) & 0xF, (err>>8) & 0xF, (err>>2) & 0x3, err & 0x3))
              print
          if ( errGTCC.phsGTFE):
            # print 5 GTFE error parameters from stack -- comes before
            # FIFO FULL error words if any.
            errGTCCmsg.parameters['PHS_GTFE'] = []
            for i in range(5):
              gtfePhs = self.getWord(pErr+nWord+curErrLen-curErrWords-5+i)
              errGTCCmsg.parameters['PHS_GTFE'].append(gtfePhs)
              if self.__debugParserOutput or forcePrint:
                print("   GTFE Phasing Error:   0x%04x\n" % gtfePhs)
            curErrWords += 5
          if errGTCC.fifoFull:
            #  print 1 error parameter from stack -- last word on parameter stack, immediately
            #  before the error word.
            curErrWords+=1
            errGTCCmsg.parameters['FIFO_FULL'] = self.getWord(pErr+nWord+curErrLen-curErrWords)
            if self.__debugParserOutput or forcePrint:
              print("   FIFO Full Error:   0x%04x\n" % errGTCCmsg.parameters['FIFO_FULL'])
          if self.__debugParserOutput or forcePrint:
            if errGTCC.cblTimeOut:
                print("   Cable Timeout Error")
            if errGTCC.hdrParity:
                print("   Header Parity Error")
            if errGTCC.wrdCntParity:
                print("   Word Count Parity Error")
            if errGTCC.GTRCsum:
                print("   GTRC Summary Error")
            if errGTCC.dataParity:
                print("   Data Parity Error")
          curErrLen -= curErrWords + 1
        if self.__debugParserOutput or forcePrint:
          print("   ------------------------------------------------")
          print
        nWord += errLen + 1
    return nWord

  def __dumpErrCablePhase(self, pErr, nWord, forcePrint=0):
    """\brief Decodes the cable phase error contribution.

    \param  pErr       Pointer to 16-bit aligned tower event error contribution
    \param  nWord      Index into begining of error data
    \param  forcePrint If specified, dump the error even if in non-debug mode

    \return            Current offset into the error contribution
    """

    # decode cable phase error structure
    cblPhs = evErr_CablePhase(self.getWord(pErr+nWord))
    self.evt.errCablePhase = cblPhs
    if self.__debugParserOutput or forcePrint:
      print("   Cable Controller Phasing Error: raw ( 0x%04x )" % cblPhs.ui)
      print("   ================================================")
      print("   GTCC |"),
    # loop over 8 GTCCs
      for i in range(N_GTCC):
        print("\b %d |" % GTCC_ERR_MAP[7 - i]),
      print
      print("   -----+"),
      # loop over 8 GTCCs
      for i in range(N_GTCC):
        print("\b---+"),
      print
      print("   Tag  |"),
      # loop over 8 GTCCs
      for i in range(N_GTCC):
        print("\b %d |" % (cblPhs.ui >> ((7-i) << 1) & 0x3)),
      print
      print("   ------------------------------------------------")
      print

    # increment past cable phase error
    return nWord+1


  def __dumpErrCableTimeOut(self, pErr, nWord, forcePrint=0):
    """\brief Decodes the cable timeout error contribution.

    \param  pErr       Pointer to 16-bit aligned tower event error contribution
    \parm   nWord      Index into begining of error data
    \param  forcePrint If specified, dump the error even if in non-debug mode

    \return            Current offset into the error contribution
    """
    cblTimeOut = evErr_CableTimeOut(self.getWord(pErr+nWord))
    self.evt.errCableTimeOut = cblTimeOut
    if self.__debugParserOutput or forcePrint:
      print("   Cable Time Out Error: raw ( 0x%04x )" % cblTimeOut.ui)
      print("   ================================================")
      print("   GCCC | "),
    # loop over 4 GCCCs
      for i in range(N_GCCC):
        if (cblTimeOut.ui >> i) & 0x1:
          print("\b%d  " % GCCC_MAP[i]),
      print
      print("   ------------------------------------------------")
      print("   GTCC | "),
    # loop over 8 GTCCs
      for i in range(N_GTCC):
        if (cblTimeOut.ui >> (i+4)) & 0x1:
          print("\b%d  " % GTCC_ERR_MAP[i]),
      print
      print("   ------------------------------------------------")
      print

    # increment past cable timeout error
    return nWord+1


  def evDumpTEM_Error(self, forcePrint=0):
    """\brief Decodes the event error contribution.

    If an error contribution is present this prints up to 20 16-bit
    words of the error contribution.

    \param  forcePrint If specified, dump the error even if in non-debug mode
    """
    errWord = 0

    # check if we have an error contribution
    es = self.evt.summary
    if ( es.error == 0):
      return 0

    pErr = self.evGetTEM_Error() << 1
    errVal = self.getWord(pErr+errWord)
    if errVal:
      if self.__debugParserOutput or forcePrint:
        print ("   Event Error Info")
        print ("   ================================================")

      if self.__debugParserOutput or forcePrint:
        # print 16-bit error words
        errPtr = pErr
        i = 0
        while errPtr < self.evt.cont_size / 2:
          print ("    raw %d: 0x%04x" % (i, self.getWord(errPtr)))
          errPtr = errPtr + 1
          i += 1
          if i > 20: break
        print

      # print error summary
      errSummary = evErr_Summary(errVal)
      self.evt.errSummary = errSummary
      if self.__debugParserOutput or forcePrint:
        print("   Error Summary: raw ( 0x%04x )" % errSummary.ui)
        print("   ================================================")
        print("   | cbl t/o | cbl phs |    TKR    |   CAL ")
        print("   ----------+---------+-----------+---------------")
      gtccErrBits = ""
      for i in range(N_GTCC):
        if ( (errSummary.gtccErr >> (7-i)) & 0x1):
          gtccErrBits = gtccErrBits + "1"
        else:
          gtccErrBits = gtccErrBits + "0"
      gcccErrBits = ""
      for i in range(4):
        if ( (errSummary.gcccErr >> (3-i)) & 0x1):
          gcccErrBits += "1"
        else:
          gcccErrBits += "0"
      if self.__debugParserOutput or forcePrint:
        print("   |    %d    |    %d    |  %s |  %s" % (errSummary.cblTimeOut, errSummary.cblPhsErr, gtccErrBits, gcccErrBits))
        print("   ------------------------------------------------")

      # increment error pointer past error summary word
      errWord += 1

      # error contributions are order as the LSB of the error summary,
      # i.e. the contributions come as: CAL, TKR, cable timeout, cable phase

      if errSummary.gcccErr:
        errWord = self.__dumpErrGCCC( errSummary, pErr, errWord, forcePrint)
      if errSummary.gtccErr:
        errWord = self.__dumpErrGTCC( errSummary, pErr, errWord, forcePrint)
      if errSummary.cblPhsErr:
        errWord = self.__dumpErrCablePhase( pErr, errWord, forcePrint)
      if errSummary.cblTimeOut:
        errWord = self.__dumpErrCableTimeOut( pErr, errWord, forcePrint)

      if self.__debugParserOutput or forcePrint:
        print("   ------------------------------------------------")

    return 0

  def __dumpCalDiag(self, diag):
    """\brief Decodes all the Calorimeter diagnostic info

    \param diag Pointer to event diagnostic data
    """
    print("   Calorimeter Diagnostic Data")
    print("   ================================================")

    for i in range(len(diag.cal)):
      print("                     layer %s    GCCC %d" % (diag.cal[i].layer, diag.cal[i].gccc ))
      print("               ----------------+-------------------")
      print("                Neg Layer-End  |  Pos Layer-End")
      print("               ----------------+-------------------")
      print("   Log Accepts "),
      nle_str = ""
      ple_str = ""
      for j in range(N_GCFE):
        if (diag.cal[i].negLayerEnd.logAccepts >> j) & 0x1:
          nle_str += "1"
        else:
          nle_str += "0"
      for j in range(N_GCFE):
        if (diag.cal[i].posLayerEnd.logAccepts >> j) & 0x1:
          ple_str += "1"
        else:
          ple_str += "0"
      print("%s   |  %s") % (nle_str, ple_str)
      print("               ----------------+-------------------")
      print("   Trg Low Eng         %d       |        %d" %
        (diag.cal[i].negLayerEnd.trgRequestLow, diag.cal[i].posLayerEnd.trgRequestLow))
      print("               ----------------+-------------------")
      print("   Trg High Eng        %d       |        %d" %
        (diag.cal[i].negLayerEnd.trgRequestHigh, diag.cal[i].posLayerEnd.trgRequestHigh))
      print("               ------------------------------------\n")

  def __dumpTkrDiag(self, diag):
    """\brief Decodes all the tracker diagnostic info

    \param diag Pointer to event diagnostic data

    """
    print("   Tracker Diagnostic Data")
    print("   =============================")

    print("   GTCC     | Trigger Request (GTRC)")
    print("   ---------+-------------------")

    for i in range(len(diag.tkr)):
      print("   GTCC_%d   | " % diag.tkr[i].gtcc),
      trq_str = ""
      for j in range(N_GTRC):
        if (diag.tkr[i].trgRequests >> (N_GTRC - 1 - j)) & 0x1:
          trq_str += "1"
        else:
          trq_str += "0"
      print("%s" % trq_str)
      print("   ---------+-------------------")
    print

  def evDumpDiagnostic(self):
    """\brief Decodes the event diagnostic contribution

    """

    # check if we have a diagnostic contribution
    es = self.evt.summary
    if es.diag == 0:
      return 0

    pDiag = self.evGetTEM_Diagnostic() << 1
    if pDiag:
      diag = evDiag_Data()
      for i in range(len(diag.cal)):
        diag.cal[i].gccc           = GCCC_MAP[i>>1]
        diag.cal[i].layer          = "%c%d" % (q(i<4,'x','y'), i%4)
        diag.cal[i].negLayerEnd.ui = self.getWord(pDiag)
        pDiag += 1
        diag.cal[i].posLayerEnd.ui = self.getWord(pDiag)
        pDiag += 1
      for i in range(len(diag.tkr)):
        diag.tkr[i].ui = self.getWord(pDiag)
        diag.tkr[i].gtcc = GTCC_MAP[i]
        pDiag += 1
      self.evt.diag = diag
      if self.__debugParserOutput:
        # print out the diagnostic
        print("\n   Event Diagnostic Info")
        print("   ================================================\n")
        self.__dumpCalDiag( diag)
        self.__dumpTkrDiag( diag)
        print("   End of Event Diagnostic Info")
        print("   ================================================")
        print
    return 1

  def evDumpSummary(self, minEvSize=24):
    """\brief Decodes the event summary word.

    Given a pointer to tower event contribution print the event summary word.

    \param minEvSize Minimum event size w/o error (default=24)
    """
    es = self.evt.summary
    print
    print("   Event Contribution Size (bytes): %d" % self.evt.cont_size)
    if self.evt.cont_size < minEvSize:
      print
      print("   *** WARNING *** WARNING *** WARNING *** WARNING ***")
      print("   *** Event size less than minimal bytes (%d)     ***" % minEvSize)
      print("   *** WARNING *** WARNING *** WARNING *** WARNING ***")
    print("   Event Contribution Source Addr : 0x%02x" % self.evt.contributor)
    print("   Event Contribution Summary Word: 0x%08x" % es.ui)
    print("   =====================================")
    print("   %-20s: %05d-%02d" % ("Event Number-Tag", es.evNumber, es.tag))
    print("   =====================================")
    print("   %-20s: %d" % ("Error", es.error))
    print("   %-20s: %d" % ("TRG Parity Error", es.trgParityErr))
    print("   =====================================")
    print("   %-20s: %d" % ("Diagnostic", es.diag))
    print("   %-20s: %d" % ("Cal Strobe", es.calStrobe))
    print("   %-20s: %d" % ("Readout 4", es.readout4))
    print("   %-20s: %d" % ("Zero suppress", es.zeroSuppress))
    print("   %-20s: %d" % ("TACK", es.TACK))
    print("   %-20s: %d" % ("Marker", es.marker))

    if es.error or es.trgParityErr:
      print
      print("   *** WARNING *** WARNING *** WARNING *** WARNING ***")
      print("   *** This event has errors -- See Summary Word   ***")
      print("   *** WARNING *** WARNING *** WARNING *** WARNING ***")
    return 0

  def __dumpAEMvec(self, cbl, type):
    """\brief Decodes the set bits specified by \a cbl and \a type

    This method is used by the old AEM event parser evDumpEventAEM_G2

    \param cbl  Which cable is being decoded
    \param type ACD vector type 1-veto, 2-zs
    """
    hitVect = self.evGetAEM_Vec(cbl, type)
    if self.__debugParserOutput:
      print("    %02d             " % cbl),
      for i in range(N_GAFE):
        print("%d" % ((hitVect >> i) & 0x1)),
      print("  0x%05x" % hitVect)
      print("   -----   ---------------------------------------------------------")

  def __dumpAEMlist(self, type):
    """\brief Decodes the list of hit vectors specified by \a type.

    This method is used by the old AEM event parser evDumpEventAEM_G2

    This function is used to decode the AEM Veto List and the AEM Accepts List.

    \param type ACD vector type
    """
    if self.__debugParserOutput:
      print("   -----   ---------------------------------------------------------")
      print("   Cable   Channel "),
      # number channels 17 down to 0
      for i in range(8):
        print("1"),
      for i in range(10):
        print("0"),
      print("  Raw")
      print("                   "),
      for i in range(17, -1, -1):
        print("%d" % (i % 10)),
      print
      print("   -----   ---------------------------------------------------------")

    # find i_th 18 bit word
    for i in range(N_GARC):
      self.__dumpAEMvec(i, type)

  def evDumpAEM_Vetos(self):
    """\brief Decodes the AEM veto hit list contribution

    This method is used by the old AEM event parser evDumpEventAEM_G2

    """
    if self.__debugParserOutput:
      print("\n   AEM Veto Hit Vectors")
      print("   =================================================================")
    self.__dumpAEMlist(AEM.EV_AEM_VETO)
    return 0

  def __getCblDataAEM(self, cbl):
    """\brief Returns pointer to AEM event data header for cable specified by \a cbl.

    This method is used by the old AEM event parser evDumpEventAEM_G2

    \param  cbl Which cable is being decoded
    \return     Offset to the AEM event data header
    """
    # the data begins one word after the event summary
    pCur = (self.evGetSummary() + 1) << 1
    while (cbl):
      # skip to the third word and test the "PHAs Follow" bit
      pCur += 2
      if self.getWord(pCur) & (0x1 <<10):
        # walk PHAs
        pCur += 1
        morePHAs = 1
        while (morePHAs):
          # check bit 15 for more PHAs
          morePHAs = self.getWord(pCur) & 0x4000
          pCur += 1
      else:
        pCur += 1
      cbl -= 1
    return pCur

  def evDumpAEM_Accepts(self):
    """\brief Decodes the AEM accept list contribution

    This method is used by the old AEM event parser evDumpEventAEM_G2

    """
    if self.__debugParserOutput:
      print("\n   AEM Accept Hit Vectors")
      print("   =================================================================")
    self.__dumpAEMlist(AEM.EV_AEM_ZEROSUP)
    return 0

  def evGetAEM_PHA(self, cbl):
    """\brief Returns pointer to start of AEM PHA values

    This method is used by the old AEM event parser evDumpEventAEM_G2

    \param cbl Which cable is being decoded
    """
    # fetch pointer to header for requested cable
    pHdr = self.__getCblDataAEM(cbl)
    # check "has PHA" bit is set
    if self.getWord(pHdr+2) & (0x1 << 10):
      # return pointer to first PHA value
      pPHA = pHdr+3
    else:
      pPHA = None
    return pPHA

  def evGetAEM_Vec(self, cbl, type):
    """\brief Returns the 18-bit vector for cable specified by \a cbl and \a type

    This method is used by the old AEM event parser evDumpEventAEM_G2

    \param  cbl  Which cable is being decoded
    \param  type ACD vector type
    \return      18-bit vector

    """
    # fetch pointer to header for requested cable
    pHdr = self.__getCblDataAEM(cbl)

    if ( type == AEM.EV_AEM_VETO):
      # decode veto vector
      vec = ((self.getWord(pHdr) << 3) | (self.getWord(pHdr+1) >> 13)) & 0x3FFFF
      self.evt.aem.vetoHitVectors[cbl] = vec
    elif ( type == AEM.EV_AEM_ZEROSUP ):
      # decode zero suppress vector
      vec = ((self.getWord(pHdr+1) << 5) | (self.getWord(pHdr+2) >> 11)) & 0x3FFFF
      self.evt.aem.acceptHitVectors[cbl] = vec
    else:
      vec = 0

    return vec


  def evDumpAEM_PHA(self):
    """\brief Decodes the AEM PHA contribution.

    This method is used by the old AEM event parser evDumpEventAEM_G2

    Given a pointer to AEM event contribution print the PHA values.
    """
    if self.__debugParserOutput:
      print("\n   AEM PHA Values")
      print("   ================================================================")
      print("   ** Warning:  This decoder assumes GARC register MAX_PHA = 18")
      print("   ** and GARC registers PHA_EN_0/1 = 0xFFFF.")
      print("   ================================================================\n")
      print("   ----+-----+-------+------------+--------------------")
      print("   Cbl   Rng    ADC    Parity Err    Raw")
      print("   ----+-----+-------+------------+--------------------")

    for cbl in range(N_GARC):
      # do we have any PHAs for this cable ?
      pRaw = self.evGetAEM_PHA(cbl)
      if pRaw != None:
        if ( self.getWord(pRaw) == 0 ):
          # null terminator PHA value -- go to next cable
          continue
        morePHAs = 1
        while (morePHAs):
          pha = evAEM_PHA(self.getWord(pRaw))
          self.evt.aem.addPHA(cbl, pha)
          pRaw += 1
          if self.__debugParserOutput:
            print("    %02d    %d    0x%03x      %d         0x%04x" % (cbl, pha.range, pha.ADC, pha.parityErr, pha.ui))
          # check bit 15 for more PHAs
          morePHAs = pha.more

    if self.__debugParserOutput:
      print("   ----------------------------------------------------\n")

    return 0


# @fn       unsigned int evDumpEventAEM( unsigned int *pEv)
# @param pEv pointer to 32-bit aligned AEM event contribution
# @brief    Decodes the event contribution
# @return   OK

  def evDumpEventAEM_G2(self):
    """\brief Given a pointer to AEM event contribution print its contents.

    This method is the old G2 compatible AEM event parser, please use the new
    event parser evDumpEventAEM for G3 based AEM events.

    """
    if self.__debugParserOutput:
      # minimum event size is 24
      self.evDumpSummary(24)

    self.evDumpAEM_Vetos()
    self.evDumpAEM_Accepts()
    self.evDumpAEM_PHA()
    # evDumpAEM_Error()
    return 0


  def evDumpEventAEM(self):
    """\brief The new AEM event parsing routine.

    This parser works according to the latest specs
    where not all cable contributions are guaranteed to
    be provided.
    """
    self.evt.aem.clearEvent()
    if self.__debugParserOutput:
      # minimum contribution size is 16
      self.evDumpSummary(16)
    # the data begins one word after the event summary
    pHdr = (self.evGetSummary() + 1) << 1
    endOfCables = 0
    while not endOfCables:
      # Skip to the third word to check end of cables and cable number
      cblHdr3 = self.getWord(pHdr+2)
      cblNo = (cblHdr3 >> 4) & 0xF
      endOfCables = (cblHdr3 >> 8) & 0x1
      # Check if there are no contributions
      if endOfCables and cblNo == 0xF:
        break
      # decode veto vector
      vec = ((self.getWord(pHdr) << 3) | (self.getWord(pHdr+1) >> 13)) & 0x3FFFF
      self.evt.aem.vetoHitVectors[cblNo] = vec
      # decode zero suppress vector
      vec = ((self.getWord(pHdr+1) << 5) | (self.getWord(pHdr+2) >> 11)) & 0x3FFFF
      self.evt.aem.acceptHitVectors[cblNo] = vec
      # check "has PHA" bit is set
      if cblHdr3  & (0x1 << 10):
        pPHA = pHdr + 3
        morePHAs = 1
        while (morePHAs):
          pha = evAEM_PHA(self.getWord(pPHA))
          self.evt.aem.addPHA(cblNo, pha)
          pPHA += 1
          morePHAs = pha.more
        pHdr = pPHA
      else:
        pHdr += 3
    if self.__debugParserOutput:
      # Dump the hit vectors
      for typ in (AEM.EV_AEM_VETO, AEM.EV_AEM_ZEROSUP):
        if typ == AEM.EV_AEM_VETO:
          print("\n   AEM Veto Hit Vectors")
        else:
          print("\n   AEM Accept Hit Vectors")
        print("   =================================================================")
        print("   -----   ---------------------------------------------------------")
        print("   Cable   Channel "),
        # number channels 17 down to 0
        for i in range(8):
          print("1"),
        for i in range(10):
          print("0"),
        print("  Raw")
        print("                   "),
        for i in range(17, -1, -1):
          print("%d" % (i % 10)),
        print
        print("   -----   ---------------------------------------------------------")
        cbl = 0
        if typ == AEM.EV_AEM_VETO:
          hitVect = self.evt.aem.vetoHitVectors
        else:
          hitVect = self.evt.aem.acceptHitVectors
        for vec in hitVect:
          print("    %02d             " % cbl),
          for i in range(N_GAFE):
            print("%d" % ((vec >> i) & 0x1)),
          print("  0x%05x" % vec)
          print("   -----   ---------------------------------------------------------")
          cbl += 1

      # Dump the PHA values
      print("\n   AEM PHA Values")
      print("   ================================================================")
      print("   ** Warning:  This decoder assumes GARC register MAX_PHA = 18")
      print("   ** and GARC registers PHA_EN_0/1 = 0xFFFF.")
      print("   ================================================================\n")
      print("   ----+-----+-------+------------+--------------------")
      print("   Cbl   Rng    ADC    Parity Err    Raw")
      print("   ----+-----+-------+------------+--------------------")

      cablesWithPHA = self.evt.aem.PHA.keys()
      cablesWithPHA.sort()
      for cbl in cablesWithPHA:
        phaVect = self.evt.aem.PHA[cbl]
        for pha in phaVect:
          print("    %02d    %d    0x%03x      %d         0x%04x" %
                   (cbl, pha.range, pha.ADC, pha.parityErr, pha.ui) )
      print("   ----------------------------------------------------\n")


  def print_EOE_Warning(self):
    """\brief Print warning if we have reached the end of the contribution prematurely

    """
    if self.__debugWarnings:
      log.error("   *** WARNING *** WARNING *** WARNING *** WARNING *** WARNING ***")
      log.error("   *** Reached the end of event data while parsing             ***")
      log.error("   ***               This event is suspect                     ***")
      log.error("   *** WARNING *** WARNING *** WARNING *** WARNING *** WARNING ***")
      logStack()

---