2.29 sddsstatmon

• description: sddsstatmon reads EPICS process variables, collects statistics, and writes these statistics to an output file. The statistics are the mean, standard deviation, minimum, maximum, and sigma. An input file defines the process variables to be monitored.
• examples: Statistics of the pressure readbacks of storage ring ion pumps and the stored current for groups of 60 data points taken at 1 second interval are collected with the command below.
  sddsstatmon SRvac.mon SRvac.sdds -time=24,hours -interval=1,seconds  
   -samplesPerStatistic=60

  where the contents of the file SRvac.mon are

  SDDS1  
  &description &end  
  &column  
   name = ControlName,  type = string, &end  
  &column  
   name = ControlType,  type = string, &end  
  &column  
   name = ReadbackUnits,  type = string, &end  
  &column  
   name = ReadbackName,  type = string, &end  
  &data  
   mode = ascii, no_row_counts=1 &end  
  ! page number 1  
  S35DCCT:currentCC pv mA S35DCCT  
  VM:01:3IP1.VAL pv Torr VM:01:3IP1  
  VM:01:2IP2.VAL pv Torr VM:01:2IP2  
  VM:01:2IP3.VAL pv Torr VM:01:2IP3  
  ...

• synopsis:
  usage: sddsstatmon <input> <output>  
      [-erase | -generations[=digits=<integer>][,delimiter=<string>] | -append[=recover][,toPage]]  
      [-steps=<integer-value> | -time=<real-value>[,<time-units>]]  
      [-dataStrobeSamplePV=<PVname>] [-dataStrobeOutputPV=<PVname>]  
      [-interval=<real-value>[,<time-units>] | -singleShot[={noprompt|stdout}]]  
      [-enforceTimeLimit] [-offsetTimeOfDay]  
      [-includeStatistics=[mean,][standardDeviation,][minimum,][maximum,][sigma][,first][,last]  
        [,sample][,sum][,all]]  
      [-samplesPerStatistic=<integer>]  
      [-verbose] [-precision={single|double}]  
      [-updateInterval=<integer>] [-watchInput]  
      [-oncaerror={repeat|skip|exit}]  
      [-comment=<parameterName>,<text>]  
      [-conditions=<filename>,{allMustPass|oneMustPass}[,touchOutput][,retakeStep]]  
      [-getUnits={force|ifBlank|ifNoneGiven}]  
      [-pendIOtime=<seconds>] [-ezcaTiming=<timeout>,<retries>]  
      [-inhibitPV=name=<name>[,pendIOTime=<seconds>][,waitTime=<seconds>]]  
      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.
    • Message — Optional string column for the device read message. If a row entry in column ControlName is a process variable, then the corresponding entry in Message should be a null string.
    • 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.
    • ScaleFactor — Optional double column for a factor with which to multiply values of the readback in the output file.
  • output file:

    The output file contains one column per statistic per process variable monitored. The five statistics are the mean, standard deviation, minimum value, maximum value, and sigma. The corresponding column names are <name>Mean, <name>StDev, <name>Min, <name>Max, and <name>Sigma, where <name> is the ReadbackName name value of the process variable in the input file.

    By default, the data type is float (single precision). 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 choice 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:
  • -erase — If the output file already exists, it will be overwritten.
  • -append[=recover][,toPage] — Append data to an existing output file. With recover, attempt to salvage a corrupted file; toPage appends rows to the last page.
  • -generations[=digits=<integer>][,delimiter=<string>] — Send output to <output>-<N> where <N> is the first nonexisting integer, formatted to four digits by default.
  • -steps=<integer> — Number of statistic sets to collect before exiting.
  • -time=<real>[,<time-units>] — Total monitoring time. Units are seconds, minutes, hours, or days.
  • -dataStrobeSamplePV=<pv> — PV whose change triggers sampling of data.
  • -dataStrobeOutputPV=<pv> — PV whose change triggers writing statistics to the output file.
  • -interval=<real>[,<time-units>] — Interval between readings. Actual interval may be longer due to control system overhead.
  • -singleShot[=noprompt|stdout] — Acquire a single set of samples on a terminal return. Qualifiers suppress or redirect the prompt.
  • -enforceTimeLimit — Enforce the time limit given with -time even if the expected number of samples is not reached.
  • -offsetTimeOfDay — Offset starting TimeOfDay so long jobs remain monotonic across midnight.
  • -includeStatistics=<list> — Include only selected statistics. Qualifiers include mean, standardDeviation, minimum, maximum, sigma, extreme, sample, sum, first, last, or all.
  • -samplesPerStatistic=<integer> — Number of samples used for each statistic (default 25).
  • -verbose — Print a message when data is taken.
  • -precision={single|double} — Select the data type for statistics columns.
  • -updateInterval=<integer> — Number of sample sets between each output file update (default 1).
  • -watchInput — Reload the input file if it changes.
  • -oncaerror={repeat|skip|exit} — Action on channel access errors: repeat uses zero and continues (default), skip drops the row, and exit terminates.
  • -comment=<parameterName>,<text> — Add a parameter and text comment to the output file.
  • -conditions=<filename>,{allMustPass|oneMustPass}[,touchOutput][,retakeStep] — Take data only when specified PV limits are satisfied.
  • -getUnits={force|ifBlank|ifNoneGiven} — Obtain units from EPICS. Qualifiers control when retrieved units override file data.
  • -pendIOtime=<seconds> — Timeout for channel access pendIO calls.
  • -inhibitPV=name=<name>[,pendIOTime=<seconds>][,waitTime=<seconds>] — Check this PV before each sample; data collection is inhibited if it is nonzero.
  • -ezcaTiming=<timeout>,<retries> — Set EZCA timeout and retry values (obsolete).
• see also:
  • sddsvmonitor()
  • sddswmonitor()
  • sddssnapshot()
• author: Michael Borland, ANL/APS.