seAppBase.py

Go to the documentation of this file.

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

__facility__ = "Online"
__abstract__ = "Script engine application base class"
__author__   = "S. Tuvi <stuvi@SLAC.Stanford.edu> SLAC - GLAST LAT I&T/Online"
__date__     = "2005/07/15 00:08:27"
__updated__  = "$Date: 2006/04/26 21:52:26 $"
__version__  = "$Revision: 1.26 $"
__release__  = "$Name: HEAD $"
__credits__  = "SLAC"

import LICOS.copyright_SLAC

import logging as log
import os
import time
import types

# The following imports are needed for added LATTE4 features
from   threading import Thread, Event, Lock

from LICOS.scriptEngine.FSM                import FSM
from LICOS.scriptEngine.ScriptEngineCommon import ScriptEngineCommon
from LICOS.scriptEngine                    import rcUtil, rcActivitiesInterface

from LICOS.scriptEngine   import rcReportGen, rcRunIdHelper, rcComplStatus
from LICOS.lib.testReport import rcTestReport

from   LICOS.util             import FreeSpace
from   LICOS.core.export      import DataExport
from   LICOS.util.gVersions   import Gversions, ROOT_DIRS
from   LICOS.lib.LATconstants import *


class seAppBase(FSM):
  """!\brief Base class for all script engine tests.

  All script engine test applications should inherit from this base class.
  This class in turn inherits from the FSM (a finite state machine) class
  which allows the scriptRun method to go through its transitions and
  execute the test.

  getRunSequence() method notifies the script engine as to the order of the
  transitions to be processed. If any of the transition methods return a
  value other than None, then the transition is rejected and the test is
  put back to the RESET state.


  """
  def __init__(self, common):
    """!\brief seAppBase constructor.

    \param common ScriptEngineCommon instance.
                  Contains session helper methods such as
                  preferences, command line options, etc.

    """
    FSM.__init__(self, 'RESET', None)
    self.set_default_transition(                            self.error,     None    )
    self.add_transition        ('SETUP',     'RESET',       self.seSetup,   'STOPPED')
    self.add_transition        ('START_RUN', 'STOPPED',     self.seStartRun,'RUNNING')
    self.add_transition        ('RUN',       'RUNNING',     self.seRun,     'COMPLETE')
    self.add_transition        ('STOP_RUN',  'COMPLETE',    self.seStopRun, 'STOPPED')
    self.add_transition        ('ABORT',     'RUNNING',     self.seAbort,   'STOPPED')
    self.add_transition        ('TEARDOWN',  'STOPPED',     self.seTeardown,'RESET')

    self.common = common
    self.gui = common.getGUI()
    self.rc = self.gui # for backward compatibility
    self.__stopRequested = False

    # The following are needed for added LATTE4 features
    self.__complStatus         = rcComplStatus.rcCompletionStatus()

    self.prefs                 = self.common.preferences()
    self.vsc                   = self.common.getCmdCli()

    self.__archiver            = None
    self.__archiverClass       = None
    self.__errArchiver         = None
    self.__badArchiver         = None

    self.__pauseCount          = 0
    self.__pausedTime          = 0
    self.__pauseTime           = None
    self.__startTime           = None
    self.__strobeTime          = None
    self.__elapsedTime         = 0
    self.__endTime             = None
    self.__excludedTime        = 0
    self.__excludeTime         = 0
    self.__excluding           = False
    self.__excludeLock         = Lock()
    self.__tstamp              = None
    self.__tstampRaw           = None
    self.__statMon             = None

    # This will contain the parent suite instance during execution
    self.__parentSuite         = None

    # This will be True if it is the last script in the suite
    self.__lastSuiteScript     = False

    self.__EBFplayback         = self.common.options().playback is not None

    self.__runIdHelper         = rcRunIdHelper.rcRunIdHelper(self.prefs)
    self.runId                 = 'N/A'

    self.__customReportData    = {}

    if self.gui is not None:
      self.__paramVerifier       = self.gui.parameterVerifier()

    self.__verifyStatus        = None

    self.__appStatus           = None
    self.__completionStatus    = self.COMPL_STATUS_UNDEFINED

    self.__dds               = self.common.getDDS()

    # Contains the full path for the run based message log
    self.__runMsgLogFile = None

    # Contains the full path for the run based LCMMSGOUT log
    self.__runLcmLogFile = None

    # Additional input files
    self.__additionalInputFiles = []

    if self.gui is not None and 'statusMonitor' in dir(self.gui):
      statMon = self.gui.statusMonitor()
      statMon.addWatchItem('Run Id', self.getRunId)
      statMon.addWatchItem('Test Name', self.getName)
      statMon.addWatchItem('Suite Name', self.getParentSuiteName)
      statMon.addWatchItem('Additional Input Files', self.getAddlInputFiles)
      statMon.addWatchItem('Completion Status', self.getCompletionStatusStr,
                            alarmExpr="@!='" + self.__complStatus.getCompletionStatusStr(self.COMPL_STATUS_PASSED)+"'")
      statMon.addWatchItem('Start Time', self.getStartTime)
      statMon.addWatchItem('End Time', self.getEndTime)
      statMon.addWatchItem('Elapsed Time', self.getElapsedTime)
      statMon.addWatchItem('Run Message Log File', self.getRunMsgLogFile)
      statMon.addWatchItem('Error Log Count', self.common.getErrorLogCount, alarmExpr='!=0')
      statMon.addWatchItem('Free Disk Space', FreeSpace.FreeSpace,
                           alarmExpr='<'+ str(self.DISKSPACE_WARN_LEVEL))
      statMon.addWatchItem('Suite State', self.getSuiteState)
      statMon.addWatchItem('Application State', self.getAppState)
      self.__statMon = statMon

    self.__reportGen = rcReportGen.rcReportGen(os.path.join(self.prefs["reportdir"], 'rcReport.out'), self.prefs)
    try:
      if self.prefs is not None and int(self.prefs["elognbl"]):
        self.__activitiesObj = rcActivitiesInterface.ActivitiesInterface()
      else:
        self.__activitiesObj = None
    except:
      self.__activitiesObj = None


  def getRunSequence(self):
    """!\brief Return the order of transitions for this type of application.

    \return A list of transitions
    """
    return ['SETUP','START_RUN','RUN','STOP_RUN','TEARDOWN']

  def doAbort(self):
    """!\brief Request an abort.

    """
    if self.get_transition("ABORT", self.current_state)[1] is not None:
      return self.process("ABORT")

  def doReset(self):
    """!\brief Reset the application.

    """
    curState = self.current_state
    if curState == "STOPPED":
      self.process("TEARDOWN")
    elif curState in ("RUNNING", "PAUSED"):
      status = self.doAbort()
      if status is None:
        self.process("TEARDOWN")
    self.__updateGUI()

  def error(self):
    """!\brief This method is called when an undefined transition is requested.

    """
    log.error(self.__class__.__name__ + " - Undefined transition: %s from state %s" % \
            (self.input_symbol, self.current_state))

  def getSuiteState(self):
    suite = self.getParentSuite()
    if suite is not None:
      return suite.current_state

  def getAppState(self):
    return self.current_state

  def getActivitiesObject(self):
    """\brief Return the activities table interface

    """
    return self.__activitiesObj

  def seSetup(self):
    """!\brief SETUP transition method.

    Calls self.setup()

    \return None for success or
            False if there is an exception or
            status returned by the user script.
    """
    fn = "seAppBase.seSetup"
    log.debug("%s -- %s" % (fn, self.getName()))
    self.__additionalInputFiles = []
    self.__updateGUI()

    # Call the application back
    try:
      status = self.setup()
      if status is not None:  return status
    except:
      log.exception("Exception in " + self.getName() + ".setup()")
      self.__appStatus = self.COMPL_STATUS_FAILED
      return False                      # Stay in RESET state

  def seTeardown(self):
    """!\brief TEARDOWN transition method.

    Calls self.teardown()

    \return None for success or status returned by the user script.
    """
    fn = "seAppBase.seTeardown"
    log.debug("%s -- %s" % (fn, self.getName()))
    self.__updateGUI()

    # Just in case this was missed in __stopRun because of an exception...
    self.__strobeTime = None

    # Call the application back
    try:
      status = self.teardown()
    except:                             # Continue as if nothing had happened
      log.exception("Exception in " + self.getName() + ".teardown()")
      self.__appStatus = self.COMPL_STATUS_FAILED
      status = None                     # Go into RESET state
    return status

  def seStartRun(self):
    """!\brief START_RUN transition method

    Calls self.startRun()

    \return None for success or
            False if there is an exception or
            status returned by the user script.
    """
    fn = "seAppBase.seStartRun"
    log.debug("%s -- %s" % (fn, self.getName()))

    self.__updateGUI()
    self.__stopRequested = False

    self.__appStatus        = None
    self.__completionStatus = self.COMPL_STATUS_UNDEFINED
    self.__endTime          = None
    self.__startTime        = None
    self.__excludeLock.acquire()
    self.__elapsedTime      = 0
    self.__strobeTime       = None
    self.__excluding        = False
    self.__excludedTime     = 0
    self.__excludeLock.release()
    self.__pauseCount       = 0
    self.__pausedTime       = 0

    self.common.resetErrorLogCount()

    # This while loop makes sure the session log level filename is different
    # than the run level filename by waiting 1 second if necessary.
    # This condition may happen in standalone scripts and suites.
    while True:
      # The timestamp is measured here because things below depend on its value.
      # Therefore the run time includes the amount of time spent in the parameter verifier
      # in addition to the time the user spends entering the parameters.
      self.__tstampRaw   = time.gmtime()
      self.__tstamp      = time.strftime('%y%m%d%H%M%S', self.__tstampRaw)
      if self.prefs.has_key("logfilename"):
        logfilename = self.prefs["logfilename"]
        if self.__tstamp != logfilename[3:15]:
          break
      else:
        break
      time.sleep(1)

    self.__exportedFiles      = []

    # Contains the rcTestReport instance used by the script if any
    self.__testReport = None
    # Contains the file name for the test report generated by the script
    self.__testReportFile = None

    self.runId = self.__runIdHelper.nextRunId()

    # Check exported directory, as per LTE-226
    if int(self.prefs["dataexport"]) == 1:
      exportDir = os.path.abspath(self.prefs["exportdir"])
      if not os.path.exists(exportDir):
        msg = "Export directory %s does not exist.  Aborting run" % exportDir
        log.fatal(msg)
        return False    # reject the transition

    if self.gui is not None:
      self.__paramVerifier.initialize(self.getName())
    self.__verifyStatus = None

    now = time.time()

    #Initialize timers
    self.__endTime     = None
    self.__startTime   = now
    self.__excludeLock.acquire()
    self.__elapsedTime = 0
    self.__strobeTime  = now
    self.__excludeLock.release()

    try:
      if self.prefs is not None and int(self.prefs["elognbl"]):
        self.__genActivity()
    except Exception, e:
      log.exception(e)
      raise


    # Call the application back
    try:
      status = self.startRun()
    except:
      log.exception("Exception in " + self.getName() + ".startRun()")
      self.__appStatus = self.COMPL_STATUS_FAILED
      status = False                    # Stay in STOPPED state

    if self.common.options().securedir is not None or self.common.options().paramverify is not None:
      # Don't prompt the parameter verifier if the script
      # is in a suite that is called from another suite or
      # if it is not the first script in the suite
      scriptSeq = 0
      if self.isRunFromSuite():
        suiteInst = self.getParentSuite()
        if suiteInst.getParentSuite() is None:
          scriptSeq = suiteInst.getScriptSequence()
        else:
          scriptSeq = -1
      if scriptSeq == 0 or scriptSeq == 1:
        self.__paramVerifier.add("Particle Type", self.prefs["lastparticletype"])
        self.__paramVerifier.add("Orientation", self.prefs["lastorientation"])
        self.__paramVerifier.add("Site", self.prefs["lastsite"])
        self.__paramVerifier.add("Instrument Type", self.prefs["lastinstrumenttype"])
        self.__paramVerifier.add("Phase", self.prefs["lastphase"])
      self.__verifyStatus = self.gui.execGUImethod(self.__paramVerifier.verify)
      if self.__verifyStatus == 1: # The user successfully signed off on the parameters
        pass
      elif self.__verifyStatus == 0: # The user cancelled the verification
        log.error("Parameter verification failed because the user cancelled verification.")
        return self.__verifyStatus
      else:
        if self.__verifyStatus is None: self.__verifyStatus = -1
        log.error("Parameter verification failed due to an unknown reason.")
        return self.__verifyStatus

    self.__runMsgLogFile = None
    self.__runLcmLogFile = None
    if int(self.prefs["lognbl"]) == 1:
      self.__runMsgLogFile = os.path.join(self.prefs["logdir"],
                                          "msg" + self.__tstamp + ".log")
      self.__runMsgLog = self.common.startRunLog(self.__runMsgLogFile)
      self.__runLcmLogFile = os.path.join(self.prefs["logdir"],
                                          "lcm" + self.__tstamp + ".log")
      self.common.startLcmLog(self.__runLcmLogFile)
    log.info("""%s -- Test %s starting run, Operator: %s,"""
             """ Run Id: %s, Time Started: %s -- %s"""
              % (fn, self.getName(), self.prefs["operator"],
                 self.runId, self.__tstamp, time.asctime(self.__tstampRaw)))
    return status

  def seRun(self):
    """!\brief RUN transition method

    Calls self.run()

    \return None for success or
            False if there is an exception or
            status returned by the user script.
    """
    fn = "seAppBase.seStartRun"
    log.debug("%s -- %s" % (fn, self.getName()))

    self.__updateGUI()
    try:
      status = self.__jacket(self.run)
    except:
      log.exception("Exception in " + self.getName() + ".startRun()")
      self.__appStatus = self.COMPL_STATUS_FAILED
      self.doReset()
      status = False
    return status

  def seStopRun(self):
    """!\brief STOP_RUN transition method

    Calls self.stopRun()
    """
    fn = "seAppBase.seStopRun"
    log.debug("%s -- %s" % (fn, self.getName()))
    self.__updateGUI()

    # Call the application back
    try:
      self.stopRun()       # RiC: It appears rejecting the transition won't work
    except:                             # Go into STOPPED state
      log.exception("Exception in " + self.getName() + ".stopRun()")
      self.__appStatus = self.COMPL_STATUS_FAILED

    # Stop the run - Must be done after the application stopRun()
    self.__stopRun()
    self.__logEndRun(fn)
    curDir = os.getcwd()
    self.__exportData()
    if os.path.exists(curDir):
      os.chdir(curDir)

  def seAbort(self):
    """!\brief ABORT transition method

    Calls self.abort()

    \return None for success or
            False if there is an exception or
            status returned by the user script.
    """
    fn = "seAppBase.seAbort"
    log.debug("%s -- %s" % (fn, self.getName()))

    self.__updateGUI()
    self.setStopRequested()
    return self.abort()

  def __updateGUI(self):
    """!\brief Update the state of the run on the GUI.

    \param  transition Transition string such as ('SETUP', 'START_RUN')
    """
    if self.gui is not None:
      self.gui.execGUImethodNR(self.gui.updateState, self.current_state)

  def setup(self):
    """ \brief Transition method to be overridden by the user script.

    """
    pass

  def teardown(self):
    """ \brief Transition method to be overridden by the user script.

    """
    pass

  def startRun(self):
    """ \brief Transition method to be overridden by the user script.

    """
    pass

  def run(self):
    """ \brief Transition method to be overridden by the user script.

    """
    pass

  def stopRun(self):
    """ \brief Transition method to be overridden by the user script.

    """
    pass

  def abort(self):
    """ \brief Transition method to be overridden by the user script.

    """
    pass

  def getName(self):
    """!\brief Return the test application name

    \return Test application class name.
    """
    return self.__class__.__name__

  def getType(self):
    """!\brief Return the type of test based on this class.

    Used for logging purposes.

    \return Test type
    """
    return 'Application'

  def isStopRequested(self):
    """!\brief Return stop requested flag.

    \return Stop requested flag.
    """
    return self.__stopRequested

  def setStopRequested(self):
    """!\brief Signal stop requested.

    """
    self.__stopRequested = True

  def setParentSuite(self, suite):
    """!\brief Set the parent suite instance.

    \param Suite instance
    """
    self.__parentSuite = suite

  def getParentSuite(self):
    """!\brief Retrieve the parent suite instance.

    \return Suite instance
    """
    return self.__parentSuite

  def getParentSuiteName(self):
    """!\brief Retrieve the parent suite name.

    \return Parent suite name.
    """
    if self.__parentSuite is not None:
      return self.__parentSuite.getName()

  def isRunFromSuite(self):
    """!\brief Check if the script is being run from a suite.

    \return True  If the script is being run from a suite,
            False otherwise.
    """
    return self.__parentSuite is not None

  def setLastSuiteScript(self):
    """!\brief Set the script as the last one in the suite.

    Called from rcSuite.
    """
    self.__lastSuiteScript = True

  def isLastSuiteScript(self):
    """!\brief Check if the script is the last one.

    """
    return self.__lastSuiteScript

  class StandaloneLauncher(object):
    """!\brief Class to facilitate the running of the test scripts and
    suites in standalone mode.

    This class allows all tests to be run unmodified in standalone
    mode. Everything is available in standalone mode except the
    GUI object (ie. self.common().getGUI() will be None)

    See testRunner
    """
    def __init__(self, logLevel="INFO"):
      """!\brief StandaloneLauncher constructor.

      \param logLevel Initial loglevel.
      """
      self.__common = ScriptEngineCommon()
      self.__common.initialize()
      self.__common.setLoggingLevel(logLevel)
      self.__common.connect()

    def launch(self, appClass, callbacks=None):
      """!\brief Launch the specified application script.

      This method launches the application passed in \a appClass or
      if the \a appClass parameter is None the application whose name
      is passed as a parameter in the --app command line argument.

      \param appClass Application instance.
      \param callbacks Not implemented yet.

      \return Result from rcUtil.scriptRun()
      """
      if appClass is None:
        module = self.__common.options().app
        (module, filename, app) = rcUtil.scriptLoad(module, self.__common)
        if app is None:
          return
        else:
          return rcUtil.scriptRun(app)
      else:
        app= appClass(self.__common)
        return rcUtil.scriptRun(app)

    def getCommon(self):
      """!\brief Accessor method for the testRunner script

      \return ScriptEngineCommon instance
      """
      return self.__common

# The following are needed for added LATTE4 features
  COMPL_STATUS_UNDEFINED            = \
      rcComplStatus.rcCompletionStatus.getCompletionStatus('UNDEFINED')
  COMPL_STATUS_ABORTED              = \
      rcComplStatus.rcCompletionStatus.getCompletionStatus('ABORTED')
  COMPL_STATUS_ERROR                = \
      rcComplStatus.rcCompletionStatus.getCompletionStatus('FAILED')
  COMPL_STATUS_SUCCESS              = \
      rcComplStatus.rcCompletionStatus.getCompletionStatus('PASSED')
  COMPL_STATUS_FAILED               = \
      rcComplStatus.rcCompletionStatus.getCompletionStatus('FAILED')
  COMPL_STATUS_PASSED               = \
      rcComplStatus.rcCompletionStatus.getCompletionStatus('PASSED')
  COMPL_STATUS_PASSED_CONDITIONALLY = \
      rcComplStatus.rcCompletionStatus.getCompletionStatus('PASSED CONDITIONALLY')
  COMPL_STATUS_MARGINAL             = \
      rcComplStatus.rcCompletionStatus.getCompletionStatus('MARGINAL')
  COMPL_STATUS_OPERATOR_ABORTED = \
      rcComplStatus.rcCompletionStatus.getCompletionStatus('OPERATOR ABORTED')
  COMPL_STATUS_INCOMPLETE = \
      rcComplStatus.rcCompletionStatus.getCompletionStatus('INCOMPLETE')

  # Watermark for diskspace warning
  DISKSPACE_WARN_LEVEL = (200*1024*1024)

  def getRunId(self):
    """!\brief Return the run id

    \return Run id
    """
    return self.runId

  def getAddlInputFiles(self):
    """!\brief Return a list containing the additional input files.

    """
    return self.__additionalInputFiles

  def addAddlInputFile(self, filename):
    """!\brief Add an additional input file.

    \param filename Name of the file
    """
    self.addExportedFile(filename, delete=False)
    self.__additionalInputFiles.append(os.path.split(filename)[1])


  def getRunMsgLogFile(self):
    """!\brief Return the filename for the message log for the current run.

    \return Message log filename.
    """
    if self.__runMsgLogFile is not None:
      return os.path.basename(self.__runMsgLogFile)
    else:
      return None

  def getRunLcmLogFile(self):
    """!\brief Return the filename for the LCM log for the current run.

    \return LCM log filename.
    """
    if self.__runLcmLogFile is not None:
      return os.path.basename(self.__runLcmLogFile)
    else:
      return None

  def getElapsedTime(self):
    """!\brief Return the elapsed time spent during test execution.

    \return Elapsed time.
    """
    return "%.2f seconds"  % self.__getElapsedTime()

  def __getElapsedTime(self):
    """!\brief Return the elapsed time (raw)

    \return Elapsed time.
    """
    self.__excludeLock.acquire()
    if self.__strobeTime is not None and \
       self.__pauseTime  is     None and not self.__excluding:
      elapsedTime = self.__elapsedTime + (time.time() - self.__strobeTime)
    else:
      elapsedTime = self.__elapsedTime
    self.__excludeLock.release()
    return elapsedTime

  def getStartTime(self):
    """!\brief Return the test start time

    \return Test start time in GMT as a tuple
    """
    if self.__startTime is not None:
      return time.asctime(time.gmtime(self.__startTime))
    else:
      return None

  def getEndTime(self):
    """!\brief Return the test end time

    \return Test end time in GMT as a tuple
    """
    if self.__endTime is not None:
      return time.asctime(time.gmtime(self.__endTime))
    else:
      return None

  def getDataDistributor(self):
    """!\brief Return the data distribution server instance.

    \return Data distribution server instance.
    """
    return self.__dds

  def setSessionVar(self, key, value):
    """!\brief Set session variable \a key to value \a value.

    Session variables are data that is shared between different runs.
    They exist as long as the run control session they are defined in.
    Typical uses of session variables are to pass data from one suite
    script to another or to maintain state during a multiple step
    test run.

    \param key   Session variable identifier.
    \param value Session variable value.
    """
    sessionVars = self.common.getDBN()
    if sessionVars is not None:
      sessionVars[key] = value
    else:
      raise RuntimeError, "Database node does not exist"

  def getSessionVar(self, key):
    """!\brief Return the session variable identified by \a key.

    \param key Session variable identifier.

    \return Value of the session variable if it exists,
            otherwise None.
    """
    sessionVars = self.common.getDBN()
    if sessionVars is not None and sessionVars.has_key(key):
      return sessionVars[key]
    else:
      return None

  def setPrefs(self, prefs):
    """!\brief Explicitly set preferences.

    When scripts are run in standalone mode it may be
    necessary to pass in a script defined set of preferences.

    The preferences specified in \a prefs get appended to
    the set of preferences read from the configuration file.

    \param prefs Preferences as a dictionary.
    """
    for (key, val) in prefs.items():
      self.prefs[key] = val

  def setCompletionStatus(self, completionStatus, completionStatusStr=None):
    """!\brief Sets the completion status of the test.

    Please use one of the following:

      - COMPL_STATUS_ABORTED              = -2
      - COMPL_STATUS_ERROR                = -3
      - COMPL_STATUS_FAILED               = -3
      - COMPL_STATUS_SUCCESS              =  0
      - COMPL_STATUS_PASSED               =  0
      - COMPL_STATUS_PASSED_CONDITIONALLY = -4
      - COMPL_STATUS_MARGINAL             = -5

    Or a user defined completion status in which case
    a description needs to be supplied along with the code.

    \param completionStatus    Numeric completion status code
    \param completionStatusStr Completion status description

    """
    if not self.__complStatus.isCompletionStatus(completionStatus):
      if completionStatusStr is None:
        raise RuntimeError, "Need to specify a completion status description " \
                            "when specifying a user defined completion status"
      else:
        addRes = self.__complStatus.addCompletionStatus(completionStatus, completionStatusStr)
        if addRes == -2:
          raise RuntimeError, "Completion status description '%s' already exists " \
                              "under a different status code." % completionStatusStr
    self.__completionStatus = completionStatus

  def getCompletionStatus(self):
    """!\brief Return the completion status code.

    Returns the code set by the script or
    COMPL_STATUS_UNDEFINED if it hasn't been set.

    \return Completion status code.
    """
    if self.__appStatus is None:
      return self.__completionStatus
    else:
      return self.__appStatus

  def getCompletionStatusStr(self):
    """!\brief Return the description of the completion status.

    Returns the code as set by the script or
    'UNDEFINED' if it hasn't been set.

    \return Completion status description.
    """
    completionStatus = self.getCompletionStatus()
    return self.__complStatus.getCompletionStatusStr(completionStatus)
    #if completionStatus == rcTransitions.COMPL_STATUS_ABORTED:
    #  return("ABORTED")
    #elif completionStatus == rcTransitions.COMPL_STATUS_ERROR:
    #  return("ERROR")
    #elif completionStatus == rcTransitions.COMPL_STATUS_SUCCESS:
    #  return("SUCCESS")
    #else:
    #  return("UNDEFINED")

#  def __isTestComplete(self):
#    """!\brief Check if the criteria for completeness of test is met.

#    \return Boolean indicating whether the test is complete or not.
#    """
#    if self.common.options().securedir is not None:
#      requiredOptions = ['snapnbl', 'datasave']
#      complete = True
#      for option in requiredOptions:
#        if self.prefs[option] != 1:
#          complete = False
#          break
#      return complete
#    else:
#      return True

  def addCustomReportData(self, key, value):
    """!\brief Add custom report data to the run report.

    This method allows the application to add any additional data
    that Run Control is not already providing to the run report
    (rcReport.out).

    When the custom report data gets processed and written to the
    database, it will go under the "AdditionFields" column. Please
    only provide values that can be converted to a string.

    \param key   Custom report data identifier.
    \param value Custom report data value.
    """
    self.__customReportData[key] = value

  def getParameterVerifier(self):
    """!\brief Return the parameter verifier instance

    \return Parameter verifier instance
    """
    return self.__paramVerifier

  def addExportedFile(self,file=None,delete=False):
    """!\brief Add file to the list of files to be exported.

    \param file   file to be added
    \param delete delete original on export (default False)
    """
    if file is not None:
      (filePath,fileName) = os.path.split(file)
      self.__exportedFiles.append( [filePath,fileName,delete] )

      # Try to extract the report file from the rcTestReport instance
      # that the script may have been using.
      if self.__testReport is None:
        for objStr in dir(self):
          obj = getattr(self, objStr)
          if '__class__' in dir(obj):
            if rcTestReport.rcTestReport in obj.__class__.__mro__:
              self.__testReport = obj
              break
      if self.__testReport is not None and file in self.__testReport.getReports():
        self.__testReportFile = fileName


  def getFileTimeStamp(self):
    """!\brief Return the formatted timestamp used to name output files.

    Using this method, applications can request the formatted timestamp
    value used in naming archive, snapshot and housekeeping files.
    The format is YYMMDDHHMISS.

    \return Formatted GMT timestamp
    """
    return self.__tstamp

  def getRawTimeStamp(self):
    """!\brief Return the raw timestamp as returned from gmtime().

    \return Raw GMT timestamp tuple.
    """
    return self.__tstampRaw

  def __genActivity(self):
    """!\brief generate the activity db entry

    Called from sestartRun
    """

    # Note, JHP: Called at end of run because elogReport table isn't updated til then.
    if self.__activitiesObj is not None:
      aObj = self.__activitiesObj
      suiteID = None
      if self.getParentSuite() is not None:
        suiteID = self.getParentSuite().getSuiteID()
      aObj.newActivity(self.runId, suiteID)
      aObj.setState(self.runId, aObj.CommandingState, aObj.CommandingStarted)
      aObj.setTime(self.runId, aObj.DataStart, self.__startTime)
    else:
      log.debug("Activities logging disabled due to prior exception")

  def __endActivity(self):
    """!\brief finalize the activities database entry

    Called from __genReport
    """
    if self.__activitiesObj is not None:
      aObj = self.__activitiesObj
      aObj.setState(self.runId, aObj.CommandingState, aObj.CommandingComplete)
      aObj.setTime(self.runId, aObj.DataStop, self.__endTime)
    else:
      log.debug("Activities logging disabled due to prior exception")

  def __genReport(self):
    """!\brief Generate the run report

    Called through the GUI bridge
    """
    log.debug("Generating run report...")
    self.__reportGen.initialize(self.__tstampRaw)
    self.__reportGen.addField("TestName", self.getName())
    if self.getParentSuiteName() is not None:
      self.__reportGen.addField("SuiteName", self.getParentSuiteName())
    self.__reportGen.addField("RunId", self.runId)
    if self.prefs.has_key("operator"):
      self.__reportGen.addField("Operator", self.prefs["operator"])
    if self.prefs.has_key("userid"):
      self.__reportGen.addField("OperatorId", self.prefs["userid"], rcReportGen.UNITS_LONG)
    self.__reportGen.addField("PauseCount", str(self.__pauseCount), rcReportGen.UNITS_INT)
    self.__reportGen.addField("PausedTime", str(self.__pausedTime), rcReportGen.UNITS_FLOAT)
    self.__reportGen.addField("StartTime", str(time.gmtime(self.__startTime)))
    self.__reportGen.addField("ElapsedTime", str(self.__elapsedTime), rcReportGen.UNITS_FLOAT)
    self.__reportGen.addField("EndTime", str(time.gmtime(self.__endTime)))
    self.__reportGen.addField("FreeDiskSpace", str(FreeSpace.FreeSpace()), rcReportGen.UNITS_LONG)
    self.__reportGen.addField("AdditionalInputFiles", str(self.getAddlInputFiles()))
    failed = []
    failedNoVersion = []
    releases = {}

    if int(self.prefs["versionnbl"]) == 1:
      try:
        self.gui.waitCursor()
        versions = Gversions.getModuleVersions(self.common.getLCATcmd().LCM)
        for (module, version) in versions.items():
          if type(version) is types.StringType:
            if version.strip() == '':
              failedNoVersion.append(module)
              failed.append(module)
        self.gui.normalCursor()
      except:
        log.exception("Error in retrieving version information. Setting VersionData to an empty list.")
        versions = {}
      self.__reportGen.addField("VersionData", str(versions))

    if int(self.prefs["disableverification"]) == 0:
      try:
        filesToVerify= []
        for rootDir in ROOT_DIRS:
          if os.path.exists(os.path.join(ONLINE_ROOT, rootDir)):
            release = Gversions.verifyModuleDigests(digestDataFile=None, rootDir=rootDir,
                                                    additionalFilesToVerify=filesToVerify)
            releases[rootDir] = release[0]
            for module in release[1]:
              if module not in failed:
                failed.append(module)
            noVersionInRelease = False
            for module in failedNoVersion:
              if module in release[1]:
                noVersionInRelease = True
                break
            if len(release[1]) > 0 or noVersionInRelease:
              log.error("Some modules failed verification for %s release %s. Check Elogbook for the modules that failed." % (rootDir, release[0]))
      except:
        log.exception("Error in verification. Setting Release and ModulesFailedVerification to empty lists.")
        releases = {}
        failed = []
    self.__reportGen.addField("Release", str(releases))
    self.__reportGen.addField("ModulesFailedVerification", str(failed))

    if self.prefs.has_key("logfilename"):
      self.__reportGen.addField("LogFile", self.prefs["logfilename"])
    if self.getRunMsgLogFile() is not None:
      self.__reportGen.addField("RunLogFile", self.getRunMsgLogFile())
    if self.getRunLcmLogFile() is not None:
      self.__reportGen.addField("LcmLogFile", self.getRunLcmLogFile())
    comments = []
    if self.rc is not None:
      cw = self.rc.getCommentWidget()
      if cw is not None:
        hist = cw.getHistory()
        tstamp = cw.getTimestamps()
        comments += zip(tstamp, hist)
      cw = self.rc.getEndRunComments()
      if cw is not None:
        hist = cw.getHistory()
        tstamp = cw.getTimestamps()
        comments += zip(tstamp, hist)
    self.__reportGen.addField("Comments", str(comments))
    for (key, value) in self.__customReportData.items():
      self.__reportGen.addField(key, str(value))
    if self.prefs is not None:
      prefs = self.prefs
      if prefs.has_key("lastsite"):
        self.__reportGen.addField("Site",           prefs["lastsite"])
      if prefs.has_key("lastparticletype"):
        self.__reportGen.addField("ParticleType",   prefs["lastparticletype"])
      if prefs.has_key("lastinstrumenttype"):
        self.__reportGen.addField("InstrumentType", prefs["lastinstrumenttype"])
      if prefs.has_key("lastorientation"):
        self.__reportGen.addField("Orientation",    prefs["lastorientation"])
      if prefs.has_key("lastphase"):
        self.__reportGen.addField("Phase",          prefs["lastphase"])
      if prefs.has_key("hwConfig"):
        self.__reportGen.addField("hwConfig", str(prefs["hwConfig"]))
    if self.__verifyStatus is not None:
      self.__reportGen.addField("ParamVerify", str(self.__verifyStatus))
    if self.__testReportFile is not None:
      self.__reportGen.addField("ScriptReport", self.__testReportFile)

    errorLogCount = self.common.getErrorLogCount()
    self.__reportGen.addField("ErrorLogCount", str(errorLogCount), rcReportGen.UNITS_INT)
    # If there are any error logs during the run override the status as FAILED
    if self.getCompletionStatus() == self.COMPL_STATUS_PASSED and errorLogCount != 0:
      log.warn("Errors were encountered during the run. Overriding the completion status as FAILED.")
      self.__appStatus = self.COMPL_STATUS_FAILED

    # Does not apply to LICOS.
    ## As per Eduardo's request override the PASSED completion status to be
    ## INCOMPLETE if any of his criteria (see __isTestComplete) aren't met
    #elif self.getCompletionStatus() == self.COMPL_STATUS_PASSED and \
    #       not self.__isTestComplete():
    #  log.warn("Test was not complete. Overriding the completion status as INCOMPLETE.")
    #  self.__appStatus = self.COMPL_STATUS_INCOMPLETE

    self.__reportGen.addField("CompletionStatus", str(self.getCompletionStatus()), rcReportGen.UNITS_INT)
    self.__reportGen.addField("CompletionStatusStr", self.getCompletionStatusStr())

    self.__reportGen.addField("ScriptOptions", str(self.common.getScriptOpts(self.getName())))

    # We're done!
    self.__reportGen.writeReportXML()
    try:
      if self.prefs is not None and int(self.prefs["elognbl"]):
        self.__endActivity()
    except Exception, e:
      log.exception(e)
      raise

    log.debug("Run report generation complete.")

  def startExcludeTime(self):
    """!\brief Save the start time for exclusion from the run's elapsed time.

    This method allows excluding some amount of time from the run's elapsed
    time.  The start time is the time that the method is called.

    Note that time spent in the PAUSED state is also excluded from the elapsed
    time value.  Overlapping time is excluded from the elapsed time only once.
    """
    if not self.__excluding:
      self.__excludeLock.acquire()
      now = time.time()
      self.__excluding = True
      self.__excludeTime  = now
      self.__elapsedTime += now - self.__strobeTime
      self.__strobeTime   = now
      self.__excludeLock.release()
    elif self.__pauseTime is not None:
      pass                              # Going into PAUSED started it
    else:
      assert not self.__excluding, "Error: " + \
             "Attempt made to exclude time when it is already being excluded"

  def endExcludeTime(self):
    """!\brief Strobe the end time for exclusion from the run's elapsed time.

    This method allows excluding some amount of time from the run's elapsed
    time.  The end time is the time that the method is called.  The difference
    between the end time and the start time is added to the excluded time.
    """

    if self.__pauseTime is None:
      assert self.__excluding, "Error: startExcludeTime was not called"
      self.__excludeLock.acquire()
      now = time.time()
      dExcludedTime         = now - self.__excludeTime
      self.__excludedTime += dExcludedTime
      self.__elapsedTime  += now - self.__strobeTime - dExcludedTime
      self.__strobeTime    = now
      self.__excludeTime   = None
      self.__excluding     = False
      self.__excludeLock.release()
    else:                               # In PAUSED state: nothing to do
      pass

  def adjustExcludeTime(self, dExcludeTime):
    """!\brief This method allows adjustment of the amount of time to be
    excluded from the run's elapsed time.

    The amount of time to be excluded from the run's elapsed time can be
    adjusted positivily or negativily with this method.  It does not take
    into account any other effects on the excluded time, such as whether
    the run was in the PAUSED state.

    \param dExcludeTime  The amount of time to be excluded as given by the
    difference of two time.time() values.
    """
    # Ensure this doesn't interrupt another thread diddling excludeTime
    self.__excludeLock.acquire()
    self.__excludedTime += dExcludeTime
    self.__excludeLock.require()

  def __jacket(self, function, *args, **kwargs):
    """!\brief Jacketting method for catching exceptions

    This method is used for catching exceptions and initiating graceful
    termination of the user application.

    \param function The function being jacketted
    \param *args    Unnamed arguments passed to \a function
    \param **kwargs Named arguments passed to \a function
    """
    try:
      function(*args, **kwargs)
    except Exception, e:
      log.exception("%s: %s" % (function.__name__, e))
      self.__appStatus = self.COMPL_STATUS_ABORTED
      self.gui.doReset()

  def __stopRun(self):
    """!\brief Logic executed during a stop run.

    This method is responsible for:
    - Calculating the final elapsed time
    - Bringing up the end run dialog
    - Setting the completion status
    - Creating the test report
    """
    # Calculate the final elapsed time
    now = time.time()
    self.__endTime      = now
    self.__excludeLock.acquire()
    if self.__strobeTime is not None:
      self.__elapsedTime += now - self.__strobeTime
    self.__strobeTime   = None
    self.__excludeLock.release()

    if self.__completionStatus == self.COMPL_STATUS_UNDEFINED:
      log.warn("Script completed with an undefined completion status. "
               "Please use the setCompletionStatus method.")

    # Let the operator override the completion status and add comments.
    if self.common.options().securedir is not None or \
       self.common.options().paramverify is not None or \
       self.common.options().endRunDlg is not None:
      if self.rc is not None and not self.rc.inShutdown:
        if not self.isRunFromSuite() or self.isLastSuiteScript():
          self.rc.execGUImethod(self.__handleEndRunDlg)

    # Create test report
    if self.rc is not None:
      if not self.rc.inShutdown:
        self.rc.execGUImethod(self.__genReport)
    else:
      self.__genReport()

  def __logEndRun(self, fn):
    """!\brief Log the end of the run

    \param fn The function name it is called from
    """
    log.info("%s -- Test %s finished, Run Id: %s, Status: %s, Completion Time: %s"
             % (fn, self.getName(), self.runId, self.getCompletionStatusStr(),
                time.asctime(time.gmtime(self.__endTime))))

    if int(self.prefs["lognbl"]) == 1:
      self.common.stopRunLog(self.__runMsgLog)
      self.common.stopLcmLog()
      self.addExportedFile(self.__runMsgLogFile, delete=True)
      self.addExportedFile(self.__runLcmLogFile, delete=True)

  def __removeZeroLengthFile(self, filePath, fileName):
    """!\brief Delete the file if the file size is zero length.

    \param filePath
    \param fileName

    \return  0 If file size is not zero or if the deletion is successful.
            -1 If the deletion is not successful.
    """
    fname = os.path.join(filePath, fileName)
    size = os.stat(fname)[6]
    if size == 0:
      try:
        os.remove(fname)
      except:
        return -1
    return 0

  def __exportData(self):
    """!\brief Export all relevant data from a run.

      Routine to export all relevant data from a run to
      local storage and possibly to offsite backup.
      This routine is designed to execute after the completion of a run,
      but before teardown of Run Control.
      The name of the export directory is the run ID.  This is
      to guarantee against unintentional overwrites between multiple
      teststands.
    """

    # If we aren't exporting, return
    exportEnabled = (int(self.prefs["dataexport"]) == 1)
    if not exportEnabled: return

    # first thing is to create a local directory structure
    outDir = self.getRunId()
    outDirRoot = self.prefs["datadir"]
    outPath = os.path.join(outDirRoot,outDir)

    # Define two exporters.
    # One which purges the files after export, one which doesn't.
    hardExporter    = DataExport.DataExport()
    safeExporter    = DataExport.DataExport()
    hardExporter.setPurge(True)
    safeExporter.setPurge(False)

    if os.access(outDirRoot,os.W_OK):             # can we write?
      os.mkdir(outPath)

      # export housekeeping file
      # Change as per LTE-193
      #hskReadOnly = (int(self.prefs["envmonreadonly"]) == 1)
      #if self.__hsk is not None and (int(self.prefs["envmonnbl"]) == 1) and not hskReadOnly:
      #  self.addExportedFile(self.__hsk.getFileName(full=1), delete=True)

      # make the rcReport.out file
      rcLastLine = self.__rcLastLine()    # Grab the info from rcReport.out
      rcOutFile = open(os.path.join(outPath,"rcReport.out"), 'w')
      rcOutFile.write(rcLastLine)
      rcOutFile.close()

      for path,name,delete in self.__exportedFiles:
        try:
          if delete:
            hardExporter.export(os.path.join(path,name),os.path.join(outPath,name))
          else:
            safeExporter.export(os.path.join(path,name),os.path.join(outPath,name))
        except Exception, e:
          log.error("Exception %s in trying to export file %s" % (e, name))

    else: # Can't write to outDirRoot
      err = "rcTransitions.__exportData: Local directory ", outDirRoot, " is not writable"
      log.error(err)
      return         # Can't continue exporting, so return


    # if the data dir and the export dir are the same, don't export.
    if os.path.abspath(self.prefs["datadir"]) == os.path.abspath(self.prefs["exportdir"]):
      msg = "Data source and Export directories are identical\n" + \
            "source: %s, export: %s" % ( self.prefs["datadir"] , self.prefs["exportdir"] )
      log.warn(msg)
      exportEnabled = False

    # Export the directory to permanent storage
    if exportEnabled:
      if not os.path.exists(os.path.abspath(self.prefs["exportdir"])):
        log.fatal("Final export directory %s no longer exists.  Something has gone very, very wrong." % self.prefs["exportdir"])
        return

      destDir    = os.path.join(self.prefs["exportdir"] ,outDir)
      dbn = self.common.getDBN()
      dbn['_LastExportPath'] = destDir
      sourceDir  = outPath
      hardExporter.export(sourceDir, destDir)

      # done export.  Create an "I'm done" file in the export area
      done = file(destDir+'/zzz.done','w')
      done.close()

  def __rcLastLine(self):
    """!\brief Get the last line of the run report file.

    \return Last line of the run report.
    """
    # Now, we need the info from rcReport.out
    # As this routine runs after the writing of the file, just grab
    # the last usable line.
    filename = ( os.path.join(self.prefs["reportdir"], 'rcReport.out') )

    rcFile = open(filename,'r')
    charsPerLine = 4096                         # this probably needs tuning.
    while 1:
      try:                                      # read from the end of the file
        rcFile.seek(-1 * charsPerLine ,2)
      except IOError:                           # the file's shorter than charsPerLine
        rcFile.seek(0)                          # reposition at head
      if rcFile.tell() == 0:
        atstart=True
      else:
        atstart=False

      rcLines=rcFile.read().split("\n")         # last line of file is blank,
      if (len(rcLines) > 2) or atstart:         # so require 2 full lines
        break
                                                # The lines are bigger than we thought,
      charsPerLine=charsPerLine * 2             # so double the read

    rcFile.close()
    rcLastLine = rcLines[len(rcLines)-2]        # cache this for later

    # extract the run id from rcLastLine, and compare it with what's expected
    import re
    runId = 0
    runIdRE = re.compile(r".*<RunId>(\d+)</RunId>.*")
    rList = runIdRE.findall(rcLastLine)
    if len(rList) > 0:
      runId = rList[0]
    else:
      log.fatal("Could not parse a run ID out of the last line of rcReport.out.")
      log.error("Last line = %s" % rcLastLine)
    if runId != self.getRunId():
      msg = "Run identifier read from rcReport.out (%s) does not match LICOS internal run ID (%s)" % (runId, self.getRunId())
      log.fatal(msg)

    return rcLastLine


  def __handleEndRunDlg(self):
    """!\brief Handle the end run dialog.

    """
    prefs = self.common.preferences()
    secMan = self.common.getSecurityMan()
    endRunDlg = self.rc.getEndRunDlg()
    loginId = prefs["operatorobj"].getLoginId()
    endRunDlg.initialize(secMan, loginId, self)
    if endRunDlg.exec_loop() == endRunDlg.Accepted:
      curComplStatusStr = self.getCompletionStatusStr()
      (cv, cs) = endRunDlg.getNewCompletionStatus(curComplStatusStr)
      if cv is not None:
        self.setCompletionStatus(cv)
        msg = ("Completion Status '%s' is overridden with status '%s' by operator %s" %
              (curComplStatusStr, cs, prefs["operator"]))
        log.info(msg)
        endRunDlg.enterComment(msg, addToHistory=1)
    else:
      endRunDlg.clearHistory()

  class StopRequestedException(Exception):
    def __init__(self, msg, *args):
      self.msg = msg
      self.args = (msg,) + args

---