2.18 sddslogger

• description: sddslogger reads values of process variables and writes them to a file at a specified time interval. One or more input files 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.
  sddslogger SRvac.mon SRvac.sdds -time=24,hours -sampleInterval=1,minutes

  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: sddslogger <SDDSinputfile1> <SDDSoutputfile1> <SDDSinputfile2> <SDDSoutputfile2>...  
      [-generations[=digits=<integer>][,delimiter=<string>][,rowlimit=<number>][,timelimit=<secs>] |  
        -dailyFiles[=rowlimit=<number>][,timelimit=<secs>,timetag][,verbose] |  
        -monthlyFiles[=rowlimit=<number>][,timelimit=<secs>,timetag][,verbose]]  
      [-onePvPerFile=<dirName>]  
      [-erase | -append[=recover][,toPage]]  
      [-sampleInterval=<real-value>[,<time-units>] | -dataStrobePV=<PVname>]  
      [-logInterval=<integer-value>] [-flushInterval=<integer-value>] [-watchInput]  
      [-steps=<integer-value> | -time=<real-value>[,<time-units>]]  
      [-enforceTimeLimit] [-offsetTimeOfDay]  
      [-verbose] [-singleshot{=noprompt|stdout}]  
      [-precision={single|double}] [-highTimePrecision]  
      [-onerror={usezero|skiprow|exit}] [-pendIOtime=<value>]  
      [-conditions=<filename>,{allMustPass|oneMustPass}[,touchOutput][,retakeStep]]  
      [-inhibitPV=name=<name>[,pendIOTime=<seconds>][,waitTime=<seconds>]]  
      [-runControlPV=string=<string>,pingTimeout=<value>]  
      [-runControlDescription=string=<string>]  
  Writes values of process variables or devices to a binary SDDS file.

• files:
  • input file(s):

    The input files are SDDS files 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.
    • ReadbackUnits — Required string column for the units fields of the data columns in the output file.
    • ReadbackName — Optional string column for the names of the data columns in the output file. If absent, process variable or device name is used.
    • 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.
    • ScaleFactor — Optional double column for a factor with which to multiply values of the readback in the output file.
    • Average — Optional long column. If value is non-zero the process variable will have its average value logged. Otherwise it will log the most recent value. values of the readback in the output file.
    • DoublePrecision — Optional long column. If value is non-zero the process variable will be logged as a double-precision number. Otherwise it will be logged as a single-precision number.
  • 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 PVs in the input files are recorded. When this situation occurs for a long period of time, the size of the output files doesn’t change, 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 logging program to touch the output file at every step.

  • output file(s):

    The output files contains one data column for each process variable named in the corresponding 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:
  • -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.
  • -dailyFiles — Starts a new output file each day. Optional qualifiers rowlimit, timelimit, timetage, and verbose control file rollover behavior.
  • -monthlyFiles — Starts a new output file each month with the same optional qualifiers as -dailyFiles.
  • -onePvPerFile=<dirName> — Writes each PV to a separate file located in <dirName>/<pvName>. Only one input file is allowed and no output filenames are given.
  • -erase — Deletes any existing output file before logging.
  • -append[=recover][,toPage] — Appends data to an existing file. The recover qualifier attempts to salvage a corrupted file. With toPage, data are appended to the last page instead of creating a new page.
  • -sampleInterval=<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.
  • -dataStrobePV=<PVname> — Logs data when the named PV changes value, typically to the current UNIX time, providing an external data strobe.
  • -logInterval=<interval> — Specifies the number of sampling intervals to average before writing to the output file.
  • -flushInterval=<interval> — Number of sampling intervals between forced flushes of data to disk.
  • -watchInput — Exits if any input file or its link target is modified.
  • -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 time limit given even if the expected number of samples has not been taken.
  • -offsetTimeOfDay — Adjusts the starting TimeOfDay value so that it corresponds to the day for which the bulk of the data is taken. Hence, a 26 hour job started at 11pm would have an initial time of day of -1 hour and a final time of day of 25 hours.
  • -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. With stdout present, the prompt is written to standard output. Typing “q” or “Q” terminates the monitoring.
  • -precision=single|double — Sets floating-point precision for logged data.
  • -highTimePrecision — Stores time values using long double precision and, with -dataStrobePV, records an additional TimeWS column.
  • -onerror={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 connection to each PV.
  • -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.

  • -inhibitPV=name=<name>[,pendIOTime=<seconds>][,waitTime=<seconds>] — Checks the specified PV before each sample; if it is nonzero, data collection is suspended. pendIOTime sets the connection timeout, and waitTime gives the delay before the PV is checked again.
  • -runControlPV=string=<string>,pingTimeout=<value> — Enables run-control support using the named PV. pingTimeout (in seconds) sets the allowed acknowledgment time.
  • -runControlDescription=string=<string> — Supplies a description string for the run-control PV record.
• see also:
  • sddsmonitor()
  • sddsvmonitor()
  • sddswmonitor()
  • sddssnapshot()
• author: Robert Soliday, Michael Borland, Hairong Shang, ANL/APS.