sddsmonitor

• description: sddsmonitor reads values of process variables and writes them to a file at a specified time interval. An input file defines the process variables to be monitored.
• example: The pressure readbacks of storage ring ion pumps and the stored current are monitored with the command below.

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

  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: sddsmonitor <SDDSinputfile> <SDDSoutputfile>
      [-erase | -append[=recover] | -generations[=digits=<integer>][,delimiter=<string>]]
      [-steps=<integer-value> | -time=<real-value>[,<time-units>]] 
      [-interval=<real-value>[,<time-units>]] [-updateinterval=<integer-value>]
      [-verbose] [-singleShot[=noprompt] [-precision={single|double}]
      [-oncaerror={usezero|skiprow|exit}] [-pendIOtime=<value>] 
      [-ezcaTiming[=<timeout>,<retries>]]
      [-glitch=<controlname>[,message=<string>]{,delta=<value>|,fraction=<value>}\
  [,before=<number>][,after=<number>][,baseline=<number>][,holdoff=<seconds>]] 
      [-trigger=<controlName>,level=<value>[,message=<string>][,slope={+ | -}]\
  [,before=<number>][,after=<number>][,holdoff=<seconds>][,autoArm]]
      [-conditions=<filename>,{allMustPass | oneMustPass}[,touchOutput][,retakeStep]]
      [-noezca] [-comment=<parameterName>,<text>]
      [-getUnits={force | ifBlank | ifNoneGiven}]\n\
  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.

  • 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:

    The output file contains one data column for each process variables named 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 sddsmonitor.
  • -append[=recover] -- If the output file already exists, then append the new readings. The output file must have previously been generated by sddsmonitor using the same information in the input files. The recover option allows an attempt to recover the data using sddsconvert if the input file is somehow corrupted.
  • -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.
  • -updateinterval -- Obsolete.
  • -verbose -- Prints out a message when data is taken.
  • -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.
  • -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 simply throw away all the data for that read step, and resume execution. the third option is to exit the program.
  • -pendIOtime=<value> -- Obsolete.
  • -ezcaTiming[=<timeout>,<retries>] -- Sets EZCA timeout and retry parameters.
  • -noezca -- Obsolete.
  • -glitch=<controlname>[,message=<string>],delta=<value>|,fraction=<value>
    [,before=<number>][,after=<number>][,baseline=<number>][,holdoff=<seconds>] -- Writes a buffer of PV readback values whenever the glitch PV (<controlname>) or device changes by some value. If <controlname> is a device, then the message field should be specified. A glitch is triggered if the control variable changes by the values of the delta or a fraction field with respect to an exponential average from baseline number of readings. The before and after fields give the number of readings recorded in a page before and after the glitch is triggered. Some buffers may be joined in one large page if the triggering events occur close together. Option -oncaerror is ignored.
  • -trigger=<controlName>,level=<value>[,message=<string>][,slope=+ | -]
    [,before=<number>][,after=<number>][,holdoff=<seconds>][,autoArm] -- Similar to glitch, except buffered data is recorded when the named PV exceeds the given level with the given slope. This is analogous to an oscilloscope trigger.
  • -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.

  • -comment=<parameterName>,<text> -- Gives the parameter name for a comment to be placed in the SDDS output file, along with the text to be placed in the file.
  • [-getUnits={force | ifBlank | ifNoneGiven}] -- Gets the units of quantities from EPICS. 'force' means ignore the ReadbackUnits data in the input, if any. 'ifBlank' means attempt to get units for any quantity that has a blank string given for units. 'ifNoneGiven' (default) means get units for all quantities, but only if no ReadbackUnits column is given in the file.

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