2.34 sddswmonitor

• description: sddswmonitor reads values of waveform process variables and writes them to a file at a specified time interval. An input file defines the process variables to be monitored.

  Warning: If the readback values of all of the waveform PVs do not change, then no data sets are written to the output file. This skipping of duplicate values is intended to keep the size of the output file as small as possible. The scalar PVs are not checked for changes though. In the future an option that allows logging of duplicate waveform PVs may be implemented.

• examples: The history of a beam position monitor readback is collected with this command:
  sddswmonitor SlowBh.wmon SlowBh.sdds -steps=1

  where the contents of the file SlowBh.wmon are

  SDDS1  
  &description &end  
  &description  
   contents = "sddssequence output", &end  
  &parameter  
   name = WaveformLength, type=long, &end  
  &column  
   name = WaveformPV,  type = string, &end  
  &column  
   name = WaveformName,  type = string, &end  
  &data  
   mode = ascii, &end  
  ! page number 1  
  512             ! WaveformLength  
  2               ! number of rows  
  S1A:P1:bh:x_wf S1A:P1:x  
  S1A:P1:bh:y_wf S1A:P1:y

• synopsis:
  usage: sddswmonitor {<inputfile> | -PVnames=<name>[,<name>]} <outputfile>  
      [{-erase | -generations[=digits=<integer>][,delimiter=<string>]}]  
      [-append[=recover]] [-pendIOtime=<seconds>]  
      [-steps=<integer> | -time=<value>[,<units>]] [-interval=<value>[,<units>]]  
      [-enforceTimeLimit] [-offsetTimeOfDay]  
      [-verbose] [-singleShot[=noprompt|stdout]]  
      [-precision={single | double}] [-dataType={short | long | float | double | character | string}]  
      [-onCAerror={useZero | skipPage | exit}]  
      [-scalars=<filename>]  
      [-conditions=<filename>,{allMustPass | oneMustPass}[,touchOutput][,retakeStep]]  
      [-accumulate={average | sum},number=<number>[,noquery]]  
      [-logOnChange[=waveformOnly][,scalarsOnly][,anyChange]]  
      [-ezcaTiming=<timeout>,<retries>]  
      [-comment=<parameterName>,<text>] [-nowarnings] [-nounits]  
      [-xParameter=dimension=<value>[,name=<name>][,minimum=<value>][,maximum=<value>][,interval=<value>]]  
      [-yParameter=dimension=<value>[,name=<name>][,minimum=<value>][,maximum=<value>][,interval=<value>]]  
      [-versus=name=<columnName>[,unitsValue=<string>|unitsPV=<string>]  
        [,deltaValue=<number>|deltaPV=<string>][,offsetValue=<integer>|offsetPV=<string>]]  
      [-rms] [-bandwidthLimitedRMS=<minHz>,<maxHz>[,scaleByOneOverOmegaSquared][,noPV]]  
  Writes values of waveform process variables to a binary SDDS file.

• files:
  • input file:

    The input file is an SDDS file with two required columns and one required parameter:

    • WaveformLength — Required long parameter for the length of the waveform PV’s. All WaveformPVs are expected to have this length.
    • WaveformPV — Required string column for the names of the waveform process variables.
    • WaveformName — Required string column for the names of the data columns in the output file.
  • scalar PV input file:

    An optional input file for scalar PVs (i.e. regular PVs) can be specified. The required columns are:

    • ControlName — Required string column for the names of the scalar process variables to be monitored.
    • ReadbackName — Required string column for the names of the parameter in the output file in which the values of the scalar process variables are written.
  • 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 situations 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 waveform process variable named in the input file. The names of the data columns are given by the values of WaveformName in the input file. The units are obtained internally from the EPICS database. An additional long column Index is created that give the index of each point in the waveform.

    The values of the scalar PVs are written to parameters with names given by the ReadbackName column of the optional scalars input file. The units are obtained internally from the EPICS database. Scalar PVs that fail to connect when the program starts are omitted from the output file.

    By default, the data type is float (single precision). Each reading step produces a new page in the output file.

    Time and other miscellaneous parameters are defined:

    • Time — Double column for elapsed time of readback since the start of epoch.
    • TimeOfDay — Float column for system time in units of hours. The time does not wrap around at 24 hours.
    • DayOfMonth — Float column for 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.

    For each connected scalar PV defined in the scalars command line option a parameter of type double is defined.

    Many additional parameters which don’t change values throughout the file are defined:

    • TimeStamp — String column for time stamp for file.
    • PageTimeStamp — String column for time stamp for each page.
    • StartTime — Double column for start time from C time call cast to type double.
    • YearStartTime — Double column for start time of present year from 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:
  • -PVnames=<name>[,<name>] — specifies a list of PV names to read. If the waveforms are of different lengths, the shorter ones are padded with zeros.
  • -scalars=<filename> — Specifies input file for scalar PV names. The values are logged as parameters.
  • -erase — If the output file already exists, then it will be overwritten by sddswmonitor.
  • -generations[=digits=<integer>][,delimiter=<string>] — Sends output to <SDDSoutputfile>-<N>, where <N> is the smallest positive integer that doesn’t already exist. Four digits are used for <N> by default.
  • -append[=recover] — Append data to an existing output file, optionally recovering a truncated file.
  • -pendIOtime=<seconds> — Maximum time to wait for channel access I/O.
  • -interval=<real-value>[,<time-units>] — Specifies the interval between readings. Because control system calls may take time, the effective interval may be longer than requested.
  • -steps=<integer-value> — Number of readbacks for each process variable before normal exiting.
  • -time=<real-value>[,<time-units>] — Total time for monitoring. The program computes the number of steps by dividing this time by the interval.
  • -enforceTimeLimit — Enforce the time limit even if the expected number of samples has not been taken.
  • -offsetTimeOfDay — Adjusts the starting time of day so that long runs that span midnight have intuitive TimeOfDay values.
  • -verbose — Prints out a message when data is taken.
  • -singleShot[=noprompt|stdout] — A single read is initiated by a <cr> key press. With noprompt present, no prompt is written. With stdout, the prompt goes to standard output. Typing “q” or “Q” terminates the monitoring.
  • -precision=single|double — Specify floating-point precision for PV data.
  • -dataType=short|long|float|double|character|string — Override the PV data type used in the output file.
  • -oncaerror=usezero|skippage|exit — Selects action taken when a channel access error occurs. The default uses zero for the PV value. skippage discards the entire step; exit terminates the program.
  • -ezcaTiming[=<timeout>,<retries>] — Sets EZCA timeout and retry parameters.
  • -conditions=<filename>,{allMustPass | oneMustPass}[,touchOutput][,retakeStep] — Names an SDDS file containing PVs to read with limits that must be satisfied for data to be logged.
  • -accumulate=average|sum,number=<number>[,noquery] — Accumulate multiple readings of each waveform either by averaging or summing. With noquery only one prompt is issued in single-shot mode.
  • -logOnChange[=waveformOnly][,scalarsOnly][,anyChange] — Log data only when values change. Qualifiers restrict the change detection to waveforms, scalars, or any change.
  • -comment=<parameterName>,<text> — Places a comment in the SDDS output file using the given parameter name.
  • -nowarnings — Suppress connection warnings.
  • -nounits — Do not read PV units from the database.
  • -xParameter=dimension=<value>[,name=<name>][,minimum=<value>][,maximum=<value>][,interval=<value>] — Define x-axis parameter information.
  • -yParameter=dimension=<value>[,name=<name>][,minimum=<value>][,maximum=<value>][,interval=<value>] — Define y-axis parameter information.
  • -versus=name=<columnName>[,unitsValue=<string>|unitsPV=<string>][,deltaValue=<number>|deltaPV=<string>][,offsetValue=<integer>|offsetPV=<string>] — Define the physical quantity represented by the waveform index.
  • -rms — Create RMS parameters for each waveform.
  • -bandwidthLimitedRMS=<minHz>,<maxHz>[,scaleByOneOverOmegaSquared][,noPV] — Compute RMS values within a frequency band. With noPV, the waveform is not stored for this calculation.
• see also:
  • sddsmonitor()
  • sddsvmonitor()
  • sddssnapshot()
• author: Michael Borland, Louis Emery, ANL/APS.