Compares two files, two generations of elements, or a file and
a generation of an element. If the entities are different, CMS
creates a file that contains the lines that differ between them.
If they are the same, CMS issues a message to that effect and does
not create a differences file (unless the /FULL qualifier is in
effect).
Format:
DIFFERENCES file1 [file2]
1 – Command Parameters
file1
Specifies the first file that is to be compared. If you specify
/GENERATION for this parameter, file1 must be an element name;
otherwise, an OpenVMS file specification is assumed.
file2
Specifies the second file that is to be compared. If you specify
/GENERATION for this parameter, file2 must be an element name;
otherwise, an OpenVMS file specification is assumed.
CMS follows these rules when you do not provide a second file
specification:
o If you direct CMS to take file1 from a location that is not a
CMS library, CMS uses the next lower file version in the same
directory as file1.
o If you direct CMS to take file1 from a CMS library (by
specifying /GENERATION), CMS uses the latest default directory
version of file1 as the second input file.
2 – Description
The DIFFERENCES command compares the contents of two files. If
CMS finds differences, it creates a file named first-file-name.DIF
in your current default directory (unless /OUTPUT is in effect.)
If the files are the same, it issues a message to that effect
and does not create a differences file. By default, CMS compares
two files that are not located in a CMS library. However, you can
direct CMS to use element generations from the current library by
specifying the /GENERATION qualifier on one or both of the file
name parameters.
Note: If both file1 and file2 are element generations, both
generations must reside in the same library of the search list
or an error will occur.
A difference is defined as one of the following:
o A line or lines that are in one file and not in the other.
o A replacement of n lines by m lines (n may or may not be equal
to m).
Only the lines that differ are displayed in the differences file
(unless you specify /FULL).
A heading at the beginning of the differences file includes the
name of the user that issued the command, the date and time the
command was issued, and the file specifications of the two files
being compared. If you direct CMS to use element generations and
you have specified the /FORMAT option generation-differences,
the differences listing contains a section labeled "Generation
Differences" that contains the replacement history for the
element. Each generation used in the comparison is identified by
an asterisk (*) in the first column of the transaction record.
The differences between the files are contained in a section
labeled "Text Differences." By default, each difference is
formatted with the line or lines from the first file followed by
the differing line or lines from the second file. If a difference
consists of a line or lines in one file but not the other,
only the lines from the file containing the additional text are
displayed.
If you specify the /SKIP, /SENTINEL, and /IGNORE qualifiers on the
same command line, they are processed in the following order:
(1) /IGNORE=HISTORY
(2) /IGNORE=NOTES
(3) /SKIP
(4) /SENTINEL
(5) /IGNORE options other than HISTORY or NOTES
For example, if you specify /SKIP=5 and /SENTINEL=("sushi","bar"),
DIFFERENCES disregards the first 5 lines in each of the compared
files, and then searches the remainder of each file for the
sentinel character strings "sushi" and "bar".
3 – Qualifiers
3.1 /APPEND
Controls whether CMS appends the command output to an existing
file, or creates a new file. If you specify /APPEND and the output
file does not exist, CMS creates a new file. If you do not provide
an output file specification (see the description for /OUTPUT),
CMS searches your current default directory for a file with the
file name specified in the file1 parameter and the file type .DIF.
3.2 /FORMAT=(data-format, data-partition, [no]generation-differences)
Controls whether the output file is formatted, specifies the
type of formatting, and controls whether a list of generation
differences is included in the DIFFERENCES output. You can specify
the parameters in any order.
data-format
Specifies the type of format. Possible values for data formats
include: ASCII (Default), DECIMAL, HEXADECIMAL, and OCTAL.
data-partition
Specifies the type of data partition. Possible values for data
partitions include: BYTE, LONGWORD, RECORDS (Default), and WORD.
generation-differences
Specifies whether or not a list of generation differences is to
be included in the DIFFERENCES output. This option is applicable
only if two element generations are compared by the DIFFERENCES
command. In any other case, this option is ignored. Possible
values for generation-differences include: GENERATION_DIFFERENCES
and NOGENERATION_DIFFERENCES (Default).
3.3 /FULL
Directs CMS to include a complete listing in the output file,
including identical text and differences between file1 and file2.
3.4 /GENERATION[=generation-expression]
Directs CMS to search for an element generation in the current
CMS library. The /GENERATION qualifier must immediately follow
the element name to which it applies. If you specify /GENERATION
but do not provide a generation expression, CMS uses the latest
generation on the main line of descent.
3.5 /IGNORE=(keyword[,...])
Specifies one or more of the following keywords. Each keyword
indicates a type of special character to be ignored during the
comparison.
Keyword Ignored Characters
CASE Directs CMS to ignore any differences between the
case of alphabetic characters (A-Z, a-z).
FORM_FEEDS Directs CMS to remove formfeed characters as it
compares records from the two files.
HISTORY Directs CMS to ignore element generation history
as it compares a file with a generation. At least
one of the files must be an element generation
with the history attribute enabled.
LEADING_BLANKS Directs CMS to remove leading blanks and tabs as
it compares records from the two files.
NOTES Directs CMS to ignore notes as it compares a file
with a generation. At least one of the files must
be an element generation with the notes attribute
enabled.
SPACING Directs CMS to compress multiple blanks and tabs
into a single space as it compares records from
the two files.
TRAILING_BLANKS Directs CMS to remove trailing blanks and tabs as
it compares records from the two files.
If the HISTORY or NOTES keyword is specified, the history or notes
text is not used for the comparison, and is also removed from
the output generated by DIFFERENCES. For all other options, the
output generated by DIFFERENCES contains the original records used
for the comparison, instead of the modified form of the records
designated by the /IGNORE qualifier.
3.6 /LOG (D)
Controls whether CMS displays success and informational messages
on the default output device. By default, if the command executes
successfully, CMS displays a success message. If you specify
/NOLOG, success and informational messages are suppressed. Any
warning, error, or fatal error messages are displayed regardless
of whether /LOG or /NOLOG is specified.
3.7 /OCCLUDE[=option,...]
Controls whether CMS selects the first instance of the specified
object, or all instances of the specified object in the library
search list. The options field contains one or more keywords
associated with the name of the object. The options field can
contain the following keywords:
ALL--equivalent to (ELEMENT, CLASS)
ELEMENT (D)
NOELEMENT
CLASS (D)
NOCLASS
NONE--equivalent to (NOELEMENT, NOCLASS)
You can specify either ALL or NONE, or any combination of the
[NO]ELEMENT and [NO]CLASS keywords.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
3.8 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file. CMS creates a
new file if you do not specify /APPEND. If you omit the /OUTPUT
qualifier (or if you specify /OUTPUT but do not provide a file
specification), CMS creates a file with the file name specified in
the file1 parameter and the file type .DIF. If you specify a file
name but omit the file type component, CMS writes the output to a
file with the specified file name and a file type of .DIF.
3.9 /NOOUTPUT
Directs CMS to execute a comparison without creating an output
file. This form of the comparison may be significantly faster
because CMS stops the transaction when it encounters the first
difference.
3.10 /PAGE_BREAK
Controls whether CMS allows page breaks in the output file. By
default, page breaks are converted to the string "<PAGE>" in the
output file. Use /PAGE_BREAK to request the inclusion of page
breaks in the output file.
3.11 /PARALLEL
Controls whether the differing lines from the two files are
formatted side by side. If you specify /PARALLEL, the differences
from the first file are displayed on the left and the differences
from the second file are displayed on the right. The heading of
the differences report displays the file specification of the
first file on the left and the file specification of the second
file on the right.
By default, the width of the listing is 132. Use the /WIDTH
qualifier to control the width. Vertical lines separate the text
on the left side of the report from the text on the right side.
The text from each of the files is allotted equal space (half the
width of the full report).
If a line from one of the files being compared is longer than half
the width of the full report, the line is truncated on the right.
An asterisk (*) is printed at the end of the line to indicate
that the line has been truncated.
3.12 /SENTINEL=("begin-delimiter", "end-delimiter")
Specifies a pair of strings used to delimit a section of text to
be ignored during the comparison of both files. The delimiters
can be up to 256 characters per line, and must be unique. Any text
between and including the delimiters is treated as if it did not
exist. If you do not enclose the sentinel strings in quotation
marks, they are converted to uppercase before the comparison of
the files. Sentinel strings may contain any characters, but if you
include spaces or tabs, they must be enclosed in quotation marks.
Sentinel strings can appear anywhere in a file. If text delimited
by a sentinel pair crosses record boundaries, the text after the
delimited region appears in its own record in the output file; it
is not appended to the contents of the record in which the begin
delimiter was found.
3.13 /SKIP=number-of-lines
Indicates the number of lines at the beginning of each file (or
generation) that are to be ignored during the comparison of both
files. You must specify a nonnegative integer value indicating the
number of lines to be ignored.
3.14 /WIDTH=n
Specifies the limit for the width of the differences report. The
value n is required and must be an integer in the range 48 to 511.
If n is less than 48, 48 is used. If n is more than 511, 511 is
used. The default width is the same as the width of the output
device.
The width of the report is rounded down to the nearest multiple
of 8 minus 1. CMS rounds down so that if you have specified the
/PARALLEL qualifier, CMS correctly interprets the horizontal tabs
in the file on the right. Thus, for example, if you specify a
value of 100 on the /WIDTH qualifier, the actual width is 95.