The DIFFERENCES command performs the following functions:
o Compares two files, two generations of elements, or a file and
a generation of an element (see File).
o Compares the contents of two classes (see /CLASS).
1 – file
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.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.
1.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".
1.3 – Qualifiers
1.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.
1.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).
1.3.3 /FULL
Directs CMS to include a complete listing in the output file,
including identical text and differences between file1 and file2.
1.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.
1.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.
1.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.
1.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.
1.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.
1.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.
1.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.
1.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.
1.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.
1.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.
1.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.
2 /CLASS
Compares the contents of two classes. If the particular generation
of any element, that is a member of the class, differs between the
classes, CMS creates a file that contains a listing of the class
members that differ between them. If the contents of the classes
are the same, CMS issues a message to that effect and does not create
a differences file (unless the /FULL qualifier is in effect). The
/CLASS qualifier must be specified prior to any other qualifiers.
Format:
DIFFERENCES/CLASS class1 class2
2.1 – Command Parameters
class1
Specifies the first class that is to be compared.
class2
Specifies the second class that is to be compared.
2.2 – Description
The DIFFERENCES/CLASS command compares the contents of two
classes. If CMS finds differences, it creates a file named
first-class-name.DIF in your current default directory (unless
/OUTPUT is in effect.) If the contents of the classes are the
same, it issues a message to that effect and does not create a
differences file.
Note: Both classes 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 particular generation of an element is a member of one
class but no generation of the element is a member of the
other class.
o One particular generation of an element is a member of one
class and a different generation of the same element is a
member of the other class.
Only the generations 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 class names of the two classes being
compared.
2.3 – Qualifiers
2.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.
2.3.2 /FULL
Directs CMS to include a complete listing in the output file,
including both identical and different generations between
class1 and class2.
2.3.3 /IGNORE=(keyword[,...])
Specifies one or more of the following keywords. Each keyword
indicates a type of difference to be ignored during the
comparison.
Keyword Ignored Difference
FIRST_VARIANT Directs CMS to ignore any differences where the
generation in one class is the first variant of
the generation in the other class. For example
generation 2C1 is a first variant of generation
2 and generation 4B6D1 is a first variant of
generation 4B6.
2.3.4 /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.
2.3.5 /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.
2.3.6 /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 class1 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.
2.3.7 /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.
2.3.8 /PARALLEL
Controls whether the differing member generations from the two
classes are formatted side by side. If you specify /PARALLEL,
the differences from the first class are displayed on the left
and the differences from the second class are displayed on the
right. The heading of the differences report displays the class
name of the first class on the left and the class name of the
second class 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 classes is allotted equal space (half
the width of the full report).
If a line from one of the classes being compared is longer than
half the width of the full report, the line is truncated on the
right. A plus sign (+) is printed at the end of the line to
indicate that the line has been truncated.
2.3.9 /SHOW=(keyword[,...])
Specifies one or more of the following keywords. Each keyword
indicates a type of class difference to show.
Keyword Difference Type
GENERATION_DIFFERENCES Directs CMS to show the difference if the
generation in one class differs from the
generation in the other class but one
generation isn't a variant of the other
generation.
VARIANT_DIFFERENCES Directs CMS to show the difference if the
generation in one class differs from the
generation in the other class and one
generation is a variant of the other. One
generation will be a variant of the other
if at some point in the path between one
generation and the other a generation is
reserved and replaced /VARIANT.
If the /SHOW qualifier is not specified, both generation differences
and variant differences are shown. If a generation of an element is
in one class but no generation of the element is in the other class
then the difference is always shown regardless of whether the /SHOW
qualifier is specified or not.
2.3.10 /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 generation comment on the right. Thus, for example, if you
specify a value of 100 on the /WIDTH qualifier, the actual width
is 95.