Skip to content

TSTool / Command / CompareFiles

Overview

The CompareFiles command compares text files to determine differences. Each file can be specified as a path to a file on the local computer, or a URL specifying a file on a web server. If a URL is specified for an input file, the URL contents are downloaded to a temporary file, which is then compared with the other file.

The command can be used to compare old and new files produced by a software process. This command is suitable for comparing files that are similar, but is not suitable for comparing files that are very different, although it may be enhanced in the future to provide more sophisticated comparison features.

  • Each line in each file is read. Different numbers of non-comment lines will result in differences.
  • By default, lines beginning with # are treated as comment lines and are ignored (see the CommentLineChar parameter to specify the comment indicator). Therefore, only non-comment lines are compared. Comment lines in the middle of the file are simply discarded.
  • Missing input files will result in an error. However, if WaitUntil is specified, a missing file is treated as an empty file.
  • No attempt is made to align similar lines to jump past groups of different lines. Therefore, if the number of lines is different, many lines may be reported to be different.

Differences and simple statistics are printed to the log file. A warning can be generated if a difference is detected or if no differences are detected (see also the CompareTimeSeries and CompareTables commands).

Command Editor

The following dialog is used to edit the command and illustrates the syntax for the command. If the DiffProgram property has been defined in the TSTool configuration file and both files exist, the View Diff button will be enabled to display a visual difference. The KDiff3 software is one option for a visual difference program.

The following dialog is used to edit the command and illustrates the command syntax.

CompareFiles

CompareFiles Command Editor for Comparing Contents (see also the full-size image)

CompareFiles-Properties

CompareFiles Command Editor for Comparing File Properties (see also the full-size image)

CompareFiles-Wait

CompareFiles Command Editor for Wait Properties (see also the full-size image)

Command Syntax

The command syntax is as follows:

CompareFiles(Parameter="Value",...)

Command Parameters

Tab Parameter                          Description Default          
All InputFile1
required		 The path to the local file or URL for the first file to read for comparison. Can be specified using ${Property}. None - must be specified.
InputFile2
required		 The path to the local file or URL for the second file to read for comparison. Can be specified using ${Property}. None - must be specified.
Compare File Contents InputFile1
required		 The name of the first file to read for comparison. Can be specified using ${Property}. None - must be specified.
CommentLineChar The character(s) that if found at the start of a line indicate comment lines. Comment lines are ignored in the comparison because they typically may include information such as date/time that changes even if the remainder of the file contents is the same. #
MatchCase If True, lines must match exactly. If False, case is ignored for the comparison. True
ExcludeText Specify one or more patterns using * for wildcard and separated by commas. The syntax *abc*|*xyz* is also supported for or'ed patterns. If any patterns are matched, exclude the text line from the comparison. Include all lines.
IgnoreWhitespace If True, then each line is trimmed to remove leading and trailing whitespace characters (spaces, tabs, etc.) before doing the comparison. If False, then whitespace is retained for the comparison. False
AllowedDiff The number of lines allowed to be different, when checking for differences. This is useful, for example, when a non-comment line contains the date/time when the file was generated, and other dynamic data. 0
IfDifferent Indicate the action if the source files are different: Ignore (ignore differences and do not warn), Warn (generate a warning message), Fail (generate a failure message) Ignore
IfSame Indicate the action if the source files are the same: Ignore (ignore if same and do not warn), Warn (generate a warning message), Fail (generate a failure message) Ignore
Compare File Properties FileProperty File property to compare:
  • ModificationTime - file modification time
  • Size - file size in bytes
FilePropertyOperator Operator for comparison, such as Property (for file 1) > Property (for file 2).
FilePropertyAction Action to take if the file property check is true:
  • Warn - create a warning message
  • Fail - create a failure message
Wait WaitUntil Indicate whether the command should wait until a condition is met, useful to confirm that a process has completed updating a file or a file has been updated to a web server:
  • FilesAreDifferent - wait until the files are different
  • FilesAreSame - wait until the files are the same
  • NoWait - don't wait (evaluate the files once)
 NoWait
WaitTimeout The maximum number of milliseconds to wait to achieve the WaitUntil condition. If the condition is met before the timeout, the output reflects the files being the requested condition. If the time is reached, no further attempts occur and the result of the last comparison is output. 1000 (1 second).
WaitInterval The number of milliseconds to wait between evaluations (to allow an external process to complete its work). 1000 (1 second).

Examples

See the automated tests.

Troubleshooting

See Also