sddsglitchlogger

• description: sddsglitchlogger reads values of process variables and writes them to a file at a specified time interval when a trigger occurrs. An input file defines the process variables to be monitored and/or the trigger parameters. An trigger file defines the the process variables that act as triggers.
• example: The position readbacks of PMs in linac are monitored with the command below.

  sddsglitchlogger SRvac.mon . -time=24,hours -interval=1,minute
  

  ``.'' specifies the directory of the outputfile is current directory,the file name is generated as related to the date. where the contents of the file SRvac.mon are

  SDDS1
  &parameter name=TriggerControlName type=string &end
  &parameter name=MajorAlarm type=short &end
  &parameter name=MinorAlarm, type=short &end
  &parameter name=NoAlarm type=short &end
  &parameter name=OutputRootname type=string &end
  &column name=ControlName type=string  &end
  &column name=ReadbackName type=string &end
  &column name=ReadbackUnits type=string &end
  &data mode=ascii no_row_counts=1 &end
  !page 1
  soliday:PM1:X:positionM
  0
  0
  1
  PM
  soliday:PM1:X:positionM  soliday:PM1:X:positionM  mm
  soliday:PM1:Y:positionM  soliday:PM1:Y:positionM  mm
  soliday:PM2:X:positionM  soliday:PM2:X:positionM  mm
  ...
  

• synopsis:

  usage: sddsglitchlogger <input> <outputDirectory>|<outputRootname> [-triggerFile=<filename>]
          [-sampleInterval=<secs>] [-time=<real-value>[,<time-units>]
          [-circularBuffer=[before=<number>,][after=<number>]]
          [-holdoffTime=<seconds>] [-autoHoldoff]
          [-inhibitPV=name=<name>[,pendIOTime=<seconds>][,waitTime=<seconds>]]
          [-conditions=<filename>,{allMustPass | oneMustPass}]
          [-verbose] [-watchInput] [-lockFile=<filename>[,verbose]] 
  Writes values of process variables or devices to a binary SDDS file.
  

• files:
  • input file:

    The input file is an SDDS file with a few data columns required:

    • ControlName or Device -- Required string column for the names of the process variables or devices to be monitored. Both column names are equivalent.
    • ReadbackName -- Optional string column for the names of the data columns in the output file. If absent, process variable or device name is used.
    • ReadbackUnits -- Optional string column for the units fields of the data columns in the output file.If absent, units are null.
    If triggerFile that gives the trigger information is not given, the input file should contain following parameters:
    • OutputRootname -- Required string parameter for the root name of output file. Different OutputRootmames go to different output files. If different pages have the same OutputRootname, the columns defined in new pages are ignored. Only the trigger defined in newer page is counted to the same output.
    • TriggerControlName -- Required string parameter for the name of process variable that acts as trigger.
    • MajorAlarm -- Optional short parameter for alarm-based trigger. if nonzero, then severity of MAJOR on TriggerControlName, results in a buffer dump.
    • MinorAlarm -- Optional short parameter for alarm-based trigger. if nonzero, then severity of MINOR on TriggerControlName, results in a buffer dump.
    • NoAlarm -- Optional short parameter for alarm-based trigger. if nonzero, then severity of NOALARM on TriggerControlName, results in a buffer dump.
    • TransitionDirection -- Optional short parameter for transition-based trigger. required if TransitionThreshold parameter is defined.
      • -1 transition of TriggerControlName from above threshold to below threshold. results in buffer dump.
      • 0 ignore transition-based triggers for this PV.
      • 1 transition from below threshold to above threshold results in buffer dump.
    • TransitionThreshold -- Optional double parameter for transition-based trigger. required if TransitionDirection parameter is defined. It defines the threshold of a transition trigger.
    • GlitchThreshold -- Optional double parameter for glitch-based trigger.
      • 0 ignore glitch-based triggers for this PV.
      • >0 absolute glitch level.
      • <0 -1*(fractional glitch level).
    • GlitchBaselineSamples -- Optional long parameter for glitch-based trigger. It defines number of samples to average to get the baseline value for glitch determination. A glitch occurs when newReading is different from the baseline by more than GlitchThreshold or (if GlitchThreshold<0) by |GlitchThreshold*baseline|.
    • GlitchBaselineAutoReset -- Optional short parameter for glitch-based trigger. Normally (if there is no glitch) the baseline is updated at each step using baseline -> (baseline*samples+newReading)/(samples+1). After a glitch, one may want to do something different.
      • 1 After a glitch, the baseline is reassigned to its current value.
      • 0 The pre-glitch baseline is retained.
  • trigger file:

    The trigger file is an SDDS file with following columns, the meaning of these columns are the same as the parameters defined in input file, which are replaced by a trigger file:

    • TriggerControlName -- Required string column for the names of the process variables that act as triggers.
    • MajorAlarm -- Optional short column.
    • MinorAlarm -- Optional short column.
    • NoAlarm -- Optional short column.
    • TransitionThreshold -- Optional double column. (required for transition trigger exists)
    • TransitionDirection -- Optional short column.(required for transition trigger exists)
    • GlitchThreshold -- Optional double column.(required for glitch trigger exists)
    • GlitchBaselineSamples -- Optional long column.
    • GlitchBaselineAutoReset -- Optional short column
  • conditions file:

    The conditions file is an optional input file specified on the command line which lists conditions that must be satisfied at each time step before the data can be logged.

    The file is like the main input file, but has numerical columns LowerLimit and UpperLimit. The minimal column set is ControlName, which contain the PV names, and the two limits columns above. Depending on comand line options, when any or all PV readback from this file is outstide the range defined by the corresponding data from LowerLimit and UpperLimit, none of the data of the input file PVs are recorded. When this situation occurs for a long period of time, the size of the output file doesn't grow, and it may appear that the monitoring process has somehow stopped. It is possible to check the program activity with the touch sub-option which causes the monitoring program to touch the output file at every step.

  • output file:

    If trigger file is not given, the output file name is: outputDirectory/OutputRootname-string here, there may be many output files depends how many pages and how many different OutputRootnames the input file has. If trigger file is given, the outputDirectory given in command line is actually the OutputRootname, the output file name is now (only one output in this case): outputDirectory-string In above, both string is generated by MakeDailyGenerationFilename().

    The output file contains one data column for each process variables named in the input file. Time columns and other miscellaneous columns are defined:

    • Time -- Double column of time since start of epoch. This time data can be used by the plotting program sddsplot to make the best coice of time unit conversions for time axis labeling.
    • TimeOfDay -- Float column of system time in units of hours. The time does not wrap around at 24 hours.
    • DayOfMonth -- Float column of system time in units of days. The day does not wrap around at the month boundary.
    • Step -- Long column for step number.
    • CAerrors -- Long column for number of channel access errors at each reading step.

    Many time-related parameters are defined in the output file:

    • TimeStamp -- String parameter for time stamp for file.
    • PageTimeStamp -- String parameter for time stamp for each page. When data is appended to an existing file, the new data is written to a new page. The PageTimeStamp value for the new page is the creation date of the new page. The TimeStamp value for the new page is the creation date of the very first page.
    • StartTime -- Double parameter for start time from the C time call cast to type double.
    • YearStartTime -- Double parameter for start time of present year from the C time call cast to type double.
    • StartYear -- Short parameter for the year when the file was started.
    • StartJulianDay -- Short parameter for the day when the file was started.
    • StartMonth -- Short parameter for the month when the file was started.
    • StartDayOfMonth -- Short parameter for the day of month when the file was started.
    • StartHour -- Short parameter for the hour when the file was started.

• switches:
  • -triggerFile -- specifies the name of trigger file.
  • -lockFile -- specifies the name of lock file. When this option is given, sddsglitchlogger uses the named file to prevent running multiple versions of the program. If the named file exists and is locked, the program exits. If it does not exist or is not locked, it is created and locked.
  • -sampleInterval=<real-value>[,<time-units>] -- Specifies the interval between readings. The time interval is implemented with a call to usleep between calls to the control system. Because the calls to the control system may take up a significant amount of time, the average effective time interval may be longer than specified.
  • -time=<real-value>[,<time-units>] -- Total time for monitoring. Valid time units are seconds, minutes, hours, and days. The completion time may be longer, because the time interval in not garanteed.
  • -enforceTimeLimit -- Enforces the time limit given with the -time option.
  • -circularBuffer -- Set how many samples to keep before and after the triggering event.
  • -holdoffTime -- Set the number of seconds to wait after a trigger or alarm before accepting new triggers or alarms.
  • -autoHoldoff -- Sets holdoff time so that the after-trigger samples are guaranteed to be collected before a new trigger or alarm is accepted.
  • -verbose -- Prints out a message when data is taken.
  • -pendIOtime=<value> -- sets the maximum time to wait for return of each value.
  • -inhibitPV -- Checks this PV prior to each sample. If the value is nonzero, then data collection is inhibited. None of the conditions-related or other PVs are polled.
  • -watchInput - If it is given, then the programs checks the input file to see if it is modifed. If the inputfile is modified, then read the input files again and start the logging.
  • -conditions=<filename>,{allMustPass | oneMustPass}[,touchOutput][,retakeStep] -- Names an SDDS file containing PVs to read and limits on each PV that must be satisfied for data to be taken and logged. The file is like the main input file, but has numerical columns LowerLimit and UpperLimit.

    One of allMustPass or oneMustPass must be specified. It would make sense to use allMustPass in most monitoring applications. If touchOutput is present, then the output file is touched, even if no data is written. This way, one can determine by the time stamp of the file whether the monitoring job is still alive when the conditions fail for a long period of time. If retakeStep is present, then the value of Step in the output file is not incremented until the conditions pass, and data is written to the output file.

• see also:
  • sddsmonitor
• author: Hairong Shang, ANL