
Comparing Files Using FILCOM

Function

The FILCOM program compares two files and  displays  any  differences.
Generally,  this  comparison  is  line-by-line  for  ASCII  files  and
word-by-word  for  binary  files.   FILCOM  determines  the  type   of
comparison  to  use  by examining either the switches specified in the
command string or the extensions of the files.  Switches  always  take
precedence over file extensions.


Format

     R FILCOM
     *output-file-spec=input-file-spec,input-file-spec/switch

where:   *  is  the  FILCOM  prompt,  file-spec  is   a   valid   file
        specification, output-file-spec specifies the name and area on
        which the results should be stored, and input-file-spec  is  a
        list of the files to be compared.

The FILCOM program takes the following defaults if you  omit  some  of
the above information:

      o  If you omit the output specification, the  output  device  is
         assumed   to   be   TTY:.    If  you  omit  the  output  file
         specification, you must still type the equal sign.

      o  If you specify only the output file name, the default  output
         device is DSK:.

      o  If you omit the output file name, the second input file  name
         is  used,  unless  it  is  null.  In this case, the file name
         FILCOM is used.

      o  If you omit the output file extension,  .SCM  is  used  on  a
         source compare and .BCM is used on a binary compare.

      o  If you omit the [directory] in either  the  input  or  output
         file specifications, your default directory is assumed.

      o  If you omit an input device name, it is assumed to be DSK:.

      o  If you omit the file name of the second  input  file,  it  is
         taken from the first input file.

      o  You must place a dot following the file name  of  the  second
         input  file  to  explicitly  indicate a null extension if the
         extension of the first input file is not null.  For  example,
         to   compare   FILE.MAC   and  FILE.   (that  is,  with  null
         extension), use the following command string:

              R FILCOM<RET>
              *=FILE.MAC,FILE.

      o  The second input file specification cannot be null  unless  a
         binary  compare  is being performed.  In a binary compare, if
         the first input file is not followed by a comma and a  second
         input  file  descriptor, the input file is compared to a zero
         file and is output in its entirety.  This gives you a  method
         of listing a binary file.  (Refer to Example 4.)


/switch is one of the options listed below.  A switch can  follow  the
input  file-specs.   The following switches are used for a binary file
comparison:


/E             Specifies that the input files  are  executable  (.EXE)
               files.

/H             Prints a list of switches  available  (help  text  from
               device HLP:).

/nL            Specifies the lower limit for a partial binary  compare
               (n  is  an  octal number).  This switch, when used with
               the /nU switch, allows a binary  file  to  be  compared
               only within the specified limits.

/Q             Prints the message ?FILES ARE DIFFERENT when the  files
               are different, but does not list the differences.  This
               switch is useful when you test batch control files  for
               differences  but  do  not  want  a  log  file  of these
               differences.

/nU            Specifies the upper limit for a partial binary  compare
               (n  is  an  octal number).  This switch, when used with
               the /nL switch, allows a binary  file  to  be  compared
               only within the specified limits.

/W             Compares files in binary  mode  without  expanding  the
               files first.  This switch is used to compare two binary
               files with ASCII extensions.

/X             Expands .SAV files  before  comparing  them  in  binary
               mode.   This  action removes differences resulting from
               zero compression.

If you did not specify any switches  in  the  command  string,  FILCOM
compares  the  files  in  the  mode  the  extension  implies.   FILCOM
recognizes the following extensions as binary:

     .APL      .ATR      .BAC      .BIN
     .BUG      .CAL      .CHN      .DAE
     .DBS      .DCR      .DMP      .EXE
     .HGH      .LOW      .MSB      .OVL
     .QUC      .QUD      .QUE      .QUF
     .REL      .RIM      .RMT      .RTB
     .SAV      .SCH      .SFD      .SHR
     .SVE      .SYM      .SYS      .UFD
     .UNV      .XPN

Binary files are compared word by word, starting at word 0, except for
the following cases:

      o  Files with  extensions  .SHR  and  .HGH  are  assumed  to  be
         high-segment files.  Because the word count starts at 400000,
         upper and lower limits, if used, must  be  greater  than  (or
         equal to in the case of the lower limit) 400000.

      o  Files with extensions .SAV, .LOW, and .SVE are assumed to  be
         compressed   core   image   files  and  are  expanded  before
         comparing.

      o  Files with the extension .EXE  are  assumed  to  be  in  .EXE
         format.

Conflicts are resolved by switches or defaults.  If a conflict  arises
in  the  absence  of  switches,  the  files are assumed to be ordinary
binary files.

The following switches are used for an ASCII source file comparison:

/A             Compares files in ASCII mode.  This switch is  used  to
               force comparison of two files to be done in ASCII.

/B             Compares blank lines.  Without this switch, blank lines
               are ignored.

/C             Ignores comments  (all  text  on  a  line  following  a
               semicolon)  and  spacing  (spaces  and  tabs).   A line
               consisting entirely  of  comments  or  spacing  is  not
               treated as if it were a blank line; differences in such
               lines are not ignored.

/H             Prints a list of switches  available  (help  text  from
               device HLP:).

/nL            Specifies the number of lines that determine a match (n
               is  an  octal number).  A match means that n successive
               lines  in  each  input  file  have  been  found  to  be
               identical.   When  a  match  is  found, all differences
               occurring before the match and after the previous match
               are listed.  In addition, the first line of the current
               match is listed after  the  differences,  to  help  you
               locate   the  place  within  each  file  at  which  the
               differences occurred.  The default value for n is 3.

/O             Instructs FILCOM to include a label and offset  in  the
               differences  listing  for ASCII files.  There are three
               types of messages.  One message is:

               [;At top of file + nL]

               nL, a decimal number, represents the  number  of  lines
               from  the  top  of the file that the difference occurs.
               If a difference occurs at the top of the  file,  nL  is
               not listed.  Another message is:

               [;At Label + nL]

               Label is the MACRO label closest to the difference  and
               nL represents the decimal number of lines away from the
               label that the difference occurs.   If  the  difference
               occurs at the label, nL is not listed.  The message for
               PDP-11 files is:

               [;At Label + nL + following label name]

               Label is the local label  name  in  the  form  nn$,  nL
               represents  the  decimal number of lines from the local
               label where the difference occurs, and following  label
               name  is  the name of the block label.  The block label
               name  is  listed  as  further  help  in  locating   the
               difference,  since  local  label  names  are not always
               unique.  If the difference occurs at the  label,  nL  +
               following  label  name  are not listed.  The label name
               for all labels must be in the first ten  characters  of
               the line.  Label name refers to file 1.

/Q             Prints the message ?FILES ARE DIFFERENT, when the files
               are different, but does not list the differences.

/S             Ignores spaces and tabs.

/T             Instructs  FILCOM  to  generate  output  even   if   no
               differences  are  found.   Ordinarily,  FILCOM does not
               produce  a  list  of  differences  if  there   are   no
               differences in the files.

/U             Compares in update mode.  This means  that  the  output
               file  consists  of  the second input file with vertical
               bars (or backslashes for 64-character printers) next to
               the  lines  that differ from the first input file.  Any
               lines found in the first input  file  but  not  in  the
               second are designated by a bullet (o).  This feature is
               useful when updating a  document  because  the  changes
               made to the latest edition are flagged with change bars
               in the left margin.  The latest edition of the document
               is the second input file.


FILCOM Output

In most cases, headers consisting of the device, file name, extension,
and creation date of each input file are listed before the differences
are listed.  However, headers do not appear  on  output  from  the  /U
switch (update mode on source compare).

Output from a source compare has the following notation  in  the  left
column of the output after the headers:

     n)m

n is the number of the input file, and m is the  page  number  of  the
input file (refer to the examples).

The right column lists the differences occurring  between  matches  in
the  input files.  Following the list of differences, a line identical
in each file is listed for reference purposes.

The output from the /U switch differs from the above-described  output
in that the output file created is the second input file with vertical
bars in the left column next to the lines that are different from  the
first input file.

The output from a binary compare prints  the  following  line  on  the
output  device  when  FILCOM  encounters  a difference between the two
input files:

     octal loc 1st file-word  2nd file-word XOR of both words

If the exclusive OR (XOR) of the two words differs only in  the  right
half, the third word listed is the absolute value of the difference of
the two right halves.  This usually indicates an address that changed.

If one input file is shorter than the other, after the end of file  is
encountered  on  the shorter file, the remainder of the longer file is
listed.


Characteristics

The FILCOM program:

     Places your terminal at user level.

     Destroys your core image.

     Requires LOGIN.


Examples

     1.  You have the following two ASCII files on disk:

              .TYPE FILE1.TST<RET>
              A
              B
              C
              D
              E
              F
              G
              H
              I
              J
              K
              L
              M
              N
              O
              P
              Q
              R
              S
              T
              U
              V
              W
              X
              Y
              Z




              .TYPE FILE2.TST<RET>
              A
              B
              C
              G
              H
              I
              1
              2
              3
              N
              O
              P
              Q
              R
              S
              T
              U
              V
              4
              5
              W
              X
              Y
              Z

         To compare the two files and print the  differences  on  your
         terminal, use the following sequence.

         Run the FILCOM program.

              .R FILCOM<RET>

         Compare the two files on disk and output the  differences  on
         your terminal.  By default, three consecutive identical lines
         determine a match.

              *=FILE1.TST,FILE2.TST<RET>

              FILE 1) DSKC:FILE1.TST[27,5434] CREATED: 0825 dd-mmm-yyyy
              FILE 2) DSKC:FILE2.TST[27,5434] CREATED: 0826 dd-mmm-yyyy

              1)1      D
              1        E
              1)       F
              1)       G
              ****
              2)1      G
              **************
              1)1      J
              1)       K
              1)       L
              1)       M
              1)       N
              ****
              2)1      1
              2)       2
              2)       3
              2)       N
              **************
              1)1      W
              ****
              2)1      4
              2)       5
              2)       W
              **************

              %FILES ARE DIFFERENT

     2.  To compare the two files and print  the  differences  on  the
         line printer, use the following command.  In this example the
         number of successive lines that determines a match  has  been
         set to four with the /4L switch.

              */4L = FILE1.TST,FILE2.TST<RET>
              FILE 1) DSKC:FILE1.TST[27,5434] CREATED 0825 dd-mmm-yyyy
              FILE 2) DSKC:FILE2.TST[27,5434] CREATED 0826 dd-mmm-yyyy

              1)1      D
              1)       E
              1)       F
              1)       G
              1)       H
              1)       I
              1)       J
              1)       K
              1)       L
              1)       M
              1)       N
              ****
              2)1      G
              2)       H
              2)       I
              2)       1
              2)       2
              2)       3
              2)       N
              **************
              1)1      W
              ****
              2)1      4
              2)       5
              2)       W
              **************

              %FILES ARE DIFFERENT

     3.  To compare the two files so that the  second  input  file  is
         output  with  vertical  bars  in  the left column next to the
         lines  that  differ  from  the  first  input  file,  use  the
         following command sequence:

              .R FILCOM<RET>

              */U=FILE1.TST,FILE2.TST<RET>
                       A
                       B
                       C
              |        G
                       H
                       I
              |        1
              |        2
              |        3
                       N
                       O
                       P
                       Q
                       R
                       S
                       T
                       U
                       V
              |        4
              |        5
                       W
                       X
                       Y
                       Z

              %FILES ARE DIFFERENT

         File number two is displayed.  The lines with  vertical  bars
         indicate the differences between the two files.

