2.32 sddsvmonitor

• description: sddsvmonitor reads values of process variables and writes them to a file at a specified time interval. This command differs from sddsmonitor in that the monitored process variables names are specified in two lists. The first list gives PV “rootnames”. The second list gives suffixes to apply to each of the rootnames. For each readback step, a page is written to the output file with the PV rootnames appearing in one column, and the process variable values in separate data columns for each suffix.

  Warning: If the readback values of all of the vector 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 vector PVs may be implemented.

• examples: The pressures readbacks of storage ring vacuum gauges are monitored with the command below.
  sddsvmonitor SRvac.vmon SRvac.vsdds -time=24,hours -interval=1,minute

  where the contents of the file SRvac.vmon are

  SDDS1  
  &parameter name=ListType, type=string &end  
  &column  
   name = "ListData",  type = "string", &end  
  &data  
   mode = "ascii", no_row_counts=1 &end  
  Rootnames  
  VM:01:  
  VM:02:  
  VM:03:  
  ...  
  VM:40:  
   
  Suffixes  
  VGC1.PRES

  There is only one element in the suffix list of this example. The output file will contain columns Rootname and VGC1.PRES.

• synopsis:
  usage: sddsvmonitor [<inputfile> | -rootnames=<file> -suffixes=<file>]  
      <outputfile> [{-erase | -append[=recover] | -generations[=digits=<integer>][,delimiter=<string>]}]  
      [-steps=<integer> | -time=<value>[,<units>]] [-interval=<value>[,<units>]]  
      [-enforceTimeLimit] [-offsetTimeOfDay]  
      [-verbose] [-singleShot{=noprompt|stdout}] [-precision={single | double}]  
      [-onCAerror={useZero | skipPage | exit}] [-PVlist=<filename>]  
      [-scalars=<filename>]  
      [-conditions=<filename>,{allMustPass | oneMustPass}[,touchOutput][,retakeStep]]  
      [-logDuplicates[=countThreshold=<number>]]  
      [-comment=<parameterName>,<text>]  
  Writes values of process variables to a binary SDDS file.

• files:
  • input file:

    The input file is an SDDS file with one data column and one parameter:

    • ListData — Required string column for the root part or the suffix part of the process variable names.
    • ListType — Required string parameter for the name part type. The only values recognized by sddsvmonitor are “rootnames” and “suffixes”.

    The list of process variables is formed by combining all the rootnames and suffixes.

  • rootname and suffix files:

    An alternative to specifying the rootnames and suffixes with the above input file is to specify the list of rootnames and suffixes with two separate files, as shown in the usage message above. The string data in rootname file must be in column Rootname. The string data in suffix file must be in column Suffix.

  • 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 specified on the command line which lists conditions that must be satisfied at each time steps 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 suffix named in the input file. By default, the data type is float (single precision). Other columns are:

    • Index — Long column for index of rootname.
    • Rootname — String column for rootnames from the input file.

    Each reading step produces a new page in the output file. Time and other miscellaneous parameters are defined:

    • Time — Double column for time of readback since the 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 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 scalar PV defined in the scalars command line option a parameter of type double is defined.

    Many time-related 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. 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 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:
  • -rootnames=<file> — Specifies input file for rootnames. String values must be in column Rootname.
  • -suffixes=<file> — Specifies input file for suffixes. String values must be in column Suffix.
  • -scalars=<filename> — Specifies input file for scalar PV names. The values are logged as parameters.
  • -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.

  • -erase — If the output file already exists, the it will be overwritten by sddsvmonitor.
  • -append[=recover] — If the output file already exists, then append the new readings. The output file must have previously been generated by sddsvmonitor 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 formatting <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 make take up a significant amount of time, the average effective time interval may sometimes be longer 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 guaranteed.
  • -enforceTimeLimit — Enforces the total monitoring time given by -time even if the expected number of steps has not been taken.
  • -offsetTimeOfDay — Adjusts the starting TimeOfDay value so that it corresponds to the day on which most data are taken.
  • -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, but a <cr> is still expected. Using stdout directs the prompt to standard output. Typing “q” or “Q” terminates the monitoring.
  • -precision={single|double} — Sets the data precision for PV values in the output file.
  • -oncaerror={useZero|skipPage|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 (skipPage) is to simply throw away all the data for that read step, and resume execution. The third option is to exit the program.
  • -PVlist=<filename> — Specifies a file in which to write the names of all PVs monitored.
  • -logDuplicates[=countThreshold=<number>] — Specifies that data should be logged even if it is exactly the same as the last data.
  • -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.
• see also:
  • sddsmonitor()
  • sddswmonitor()
  • sddssnapshot()
• author: Michael Borland, Louis Emery, ANL/APS.