2.20 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.
• examples: 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

  Writes values of process variables or devices to a binary SDDS file. 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][,toPage] |  
      -generations[=digits=<integer>][,delimiter=<string>][,rowlimit=<number>][,timelimit=<secs>] |  
      -dailyFiles]  
    [-steps=<integer-value> | -time=<real-value>[,<time-units>]]  
    [-interval=<real-value>[,<time-units>]] [-enforceTimeLimit] [-offsetTimeOfDay] [-watchInput]  
    [-updateinterval=<integer-value>] [-verbose] [-singleshot[=noprompt|stdout]]  
    [-precision={single|double}]  
    [-oncaerror={usezero|skiprow|exit}] [-pendIOtime=<value>] [-ezcaTiming[=<timeout>,<retries>]]  
    [-noezca]  
    [-glitch=<controlname>[,message=<string>]{,delta=<value>|,fraction=<value>}[,before=<number>]  
      [,after=<number>][,{baseline=<number>|filterFraction=<value>}][,sign={+|-}][,noReset]  
      [,{autoHoldoff|holdoff=<seconds>}]]  
    [-trigger=<controlName>,level=<value>[,message=<string>][,slope={+|-}][,before=<number>]  
      [,after=<number>][,autoArm][,{autoHoldoff|holdoff=<seconds>}]]  
    [-alarmTrigger=<controlName>[,status=<statusNames>][,notStatus=<statusNames>]  
      [,severity=<sevNames>][,notSeverity=<sevNames>][,{autoHoldoff|holdoff=<seconds>}]]  
    [-circularBuffer=[before=<number>,][after=<number>]] [-holdoffTime=<seconds>] [-autoHoldoff]  
    [-conditions=<filename>,{allMustPass|oneMustPass}[,touchOutput][,retakeStep]]  
    [-comment=<parameterName>,<text>] [-getUnits={force|ifBlank|ifNoneGiven}]  
    [-inhibitPV=name=<name>[,pendIOTime=<seconds>][,waitTime=<seconds>]]  
    [-stopPV=<controlName>[,pendIOTime=<seconds>]]  
    [-runControlPV=string=<string>,pingTimeout=<value>]  
    [-runControlDescription=string=<string>]

• 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 command 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 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, then it will be overwritten by sddsmonitor.
  • -append[=recover][,toPage] — 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>][,rowlimit=<number>][,timelimit=<secs>] — 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 formatting <N> so that the first generation number is 0001. New files are started when the optional row or time limits are reached.
  • -dailyFiles — Creates a new output file each day with a name of the form <SDDSoutputfile>-YYYY-JJJ-MMDD.<N>.
  • -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 is not guaranteed.
  • -enforceTimeLimit — Stops monitoring when the total time given with -time has elapsed, even if the requested number of samples has not been taken.
  • -offsetTimeOfDay — Adjusts the starting TimeOfDay value so it corresponds to the day for which the bulk of the data is taken.
  • -watchInput — Exits if the input file is modified while monitoring is in progress.
  • -updateinterval=<integer-value> — Number of read steps before each output file update.
  • -verbose — Prints out a message when data is taken.
  • -singleshot[=noprompt|stdout] — 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. If stdout is given, the prompt is written to standard output.
  • -precision={single|double} — Selects precision for PV data.
  • -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> — Sets the maximum time to wait for return of each value.
  • -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>|filterFraction=<value>]
    [,sign=+|-][,noReset][,autoHoldoff|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 or using filterFraction of the new reading. 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>][,autoArm][,autoHoldoff|holdoff=<seconds>] — 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.
  • -alarmTrigger=<controlName>[,status=<statusNames>][,notStatus=<statusNames>]
    [,severity=<sevNames>][,notSeverity=<sevNames>][,autoHoldoff|holdoff=<seconds>] — Uses alarm callbacks to trigger saving of data when the given channel enters one of the specified alarm states.
  • -circularBuffer=[before=<number>,][after=<number>] — Sets how many samples to keep before and after a triggering event. Replaces the before and after qualifiers on -trigger and -glitch.
  • -holdoffTime=<seconds> — Sets the number of seconds to wait after a trigger or alarm before accepting new triggers or alarms.
  • -autoHoldoff — Ensures after-trigger samples are collected before a new trigger is accepted.
  • -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.
  • -inhibitPV=name=<name>[,pendIOTime=<seconds>][,waitTime=<seconds>] — Checks this PV prior to each sample. If the value is nonzero, then data collection is inhibited.
  • -stopPV=<controlName>[,pendIOTime=<seconds>] — Specifies a stop PV name. Program will exit when PV value is true (non-zero).
  • -runControlPV=string=<string>,pingTimeout=<value> — Specifies a runControl PV name.
  • -runControlDescription=string=<string> — Specifies a runControl PV description record.
• see also:
  • sddsvmonitor()
  • sddswmonitor()
  • sddssnapshot()
• author: Louis Emery, Michael Borland, ANL/APS.