sddsstatmon

• description: sddsstatmon reads EPICS process variables, collects statistics, and writes these statistics to an output file. The statistics are the mean, standrd deviation, mininum, maximum, and sigma. An input file defines the process variables to be monitored.
• example: 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,second \
   -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>]]
      [-steps=<integer-value> | -time=<real-value>[,<time-units>]] 
      [-interval=<real-value>[,<time-units>] | [-singleShot{=noprompt | stdout}]
      [-samplesPerStatistic=<integer>] 
      [-verbose] [-precision={single|double}]
      [-updateInterval=<integer>] 
      [-ezcaTiming[=<timeout>,<retries>]] [-noezca]
      [-oncaerror={skip | exit | repeat}
      [-comment=<parameterName>,<text>]
      [-getUnits={force | ifBlank | ifNoneGiven}]
      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 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:
  • -erase -- If the output file already exists, then it will be overwritten by sddsstatmon.
  • -generations[=digits=<integer>][,delimiter=<string>] -- The output is sent to the file <SDDSoutputfile>-<N>, where <N> is the smallest positive integer such that the file does not already exist. By default, four digits are used for formating <N>, so that the first generation number is 0001.
  • -interval=<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.
  • -steps=<integer-value> -- Number of readbacks for each process variable before normal exiting.
  • -time=<real-value>[,<time-units>] -- Total time for monitoring. Valid time units are seconds, minutes, hours, and days. The program calculates the number of steps by dividing this time by the interval. The completion time may be longer, because the time interval in not garanteed.
  • -singleShot[=noprompt] -- a single read is prompted at the terminal and initiated by a <cr> key press. The time interval is disabled. With noprompt present, no prompt is written to the terminal, but a <cr> is still expected. Typing ``q'' or ``Q'' terminates the monitoring.
  • -samplesPerStatistic=<integer> -- The number of samples to use for computing each statistic. The default is 25.
  • -verbose -- Prints out a message when data is taken.
  • -precision={single|double} -- Selects teh data type for the statistics columns.
  • -updateInterval=<integer> -- Number of sample sets between each output file update. The default is 1.
  • -ezcaTiming[=<timeout>,<retries>] -- Sets EZCA timeout and retry parameters.
  • -noezca -- Obsolete.
  • -oncaerror={usezero|skiprow|exit} -- Selects action taken when a channel access error occurs. The default is using zero (usezero) for the value of the process variable with the channel access error, and resuming execution. The second option (skiprow) is to

• see also:
  • sddsvmonitor
  • sddswmonitor
  • sddssnapshot
• author: M. Borland, ANL