CP/M/CPM_CDROM.iso/jsage/zsus/z3help/d.lbr/DIFF.HZP/DIFF.HLP

Text File | 1991-11-18 | 10.3 KB | 232 lines

;

                                  DIFF.COM                                     

             Size (recs) CRC   Version    Author/Latest Issue      Disk
DIFF100.COM    4k (29)   1A97  3.0        Carson Wilson 2/89       Z3COM2
DIFF6000.COM   4k (29)   BC87  3.0        Carson Wilson 2/89       Z3COM2


  1- Syntax/Options  2- Operation  3- Notes  4- Examples of Use                

   DIFF version 3.0 is  an  extensively modified and improved  version  of the
original ZCPR 3.0 DIFF utility by Richard Conn.  The program's basic functions
have  been  enhanced  to  take advantage  of ZCPR 3.3  and  3.4,  and  several
additional functions have been added.

   DIFF quickly compares two  files and reports the results  to the screen and
to  the ZCPR environment.   This is useful in verifying backup copies of files
or eliminating duplicate copies.   Because DIFF reports  its  findings to  the
ZCPR  environment,  it may  be  used with command  scripts for  automated file
maintanence.
:1

   
Syntax:  DIFF [dir:]ufn [dir:][ufn] [/][options]

  
Options:  D - test Datestamps only
            I - Ignore datestamps
            M - perform Multiple comparison
            Q - perform Quiet comparison
            V - perform Verbose comparison

   DIFF's command line consists  of the command verb,  followed by  one or two
unambiguous file specs,  optionally followed by one or more option characters.
A leading  slash must introduce options if  only one file  spec is  given,  to
prevent DIFF from confusing options with filespecs.

   It should be obvious that certain  option combinations  produce meaningless
or contradictory results.  For example, combining the /D and /I options causes
DIFF to do nothing  at all.   The /Q option contradicts the /V and /M options,
and for this  reason where /Q is used  it  takes  precedence  over  /M and /V,
forcing a single, non-verbose comparison.



File Specifications:

   The first file spec is  given in the command and is referred  to as "Source
1."  The second  file spec is  either given in the command or is filled in  by
DIFF and is referred to as "Source 2".

   If only one  file specification is  given,  Source 2 is assumed to have the
same name  as Source 1 and  to reside in the current directory.   For example,
the command

            WORK>diff root:myfile.txt

compares ROOT:MYFILE.TXT with WORK:MYFILE.TXT.   If only  a directory is given
for the second file, DIFF assumes a file of the same name as the first, but in
the specified directory.



File Specifications (cont'd):

              WORK>diff myfile.txt root:

therefore compares WORK:MYFILE.TXT  with ROOT:MYFILE.TXT.   This is equivalent
to the  previous example  with the exception  that Source 1  and  Source 2 are
reversed.   This is  an important  difference only  when  interpreting results
stored by DIFF in ZCPR register 0.

   Since DIFF uses  ZCPR's command line  parser when interpreting drive,  user
and directory specifications, directory security is enforced to current system
levels, and DIFF may safely be used with secure systems.
:2


Operation:

   By default, DIFF determines file equivalence using the most efficient means
available.  It first checks for matching file names and datestamps and assumes
that files with the  same name which  were created or last modified during the
same minute are identical.   This is much faster in most cases than performing
a complete data test.   If file datestamps are not present, DIFF falls back to
a  normal data comparison,  stopping  at  the  first  difference,  user  abort
command,  or end of file.   If a data test is desired  regardless of datestamp
information, the /I option can  be used to tell  DIFF to ignore datestamps and
proceed directly to a data comparison.

   In  comparing  file  datestamps, DIFF  first  tries  to  compare  the "last
modified" stamps.  If  a file's "last modified" stamp is missing,  that file's
"create" stamp is used instead.   If either file is  missing  both  create and
modify stamps, DIFF falls back on file data to determine equivalence.



Operation (cont'd):

   DIFF  communicates  its  results  both  to  the  screen  and  to  the  ZCPR
environment.   The program error  byte is set to true ("ERROR") by default for
each file compare, and is only reset to false when  a matching  pair  of files
is  found.   Thus all of  the following conditions will set the  program error
byte to "true:"

                   a. Either or both files missing
                   b. User abort
                   c. Files do not match

   ZCPR register zero is set to reflect the  results of filestamp comparisons.
Register zero is set as follows:


     Register
     0 Value        Condition
     -------        ---------------------------------------------
          0         No stamp comparison was performed, either due
                    to the /I option or because one or both
                    stamps were not available.
          1         Source 1 is more recent.
          2         Source 2 is more recent.
          3         Sources 1 and 2 have matching stamps.

   Unless the /V Verbose  option is given,  DIFF simply reports the results of
file  stamp comparisons (if any) and  data comparisons to the screen,  telling
which file was more recent and whether files match or not.   The /V option may
be used to generate a more detailed report of file data differences.
:3


DIFF Notes:  System Requirements

   DIFF now requires  ZCPR versions 3.3  and  above  to  operate.   Additional
features are  available if DIFF is used under ZSDOS,  Z3PLUS,  and/or DosDisk,
but these system enhancements are not required by DIFF.   DIFF100.COM loads at
100 hex  and  requires memory from 100 hex  to  about 3200 hex.   DIFF6000.COM
loads  at  6000  hex  and  requires  memory  from 100 hex  to  about 9100 hex.
Insufficient memory causes DIFF to abort with an error message.



Diff Notes:  Customization

   As distributed,  DIFF's Datestamp,  Ignore,  Multiple,  Quiet,  and Verbose
options are "off" by default,  and  are turned on when the option character is
given in  the  command line.   The sense of  any or  all  of the  command line
options may be reversed by altering the  five  bytes following the ASCII label
"[DIMQV>" at address 10d hex in the program itself.

   As distributed,  the five  bytes  at 112 hex  are 0,0,0,0,0.  To  change an
option  to "on" by default,  set the corresponding byte following the label to
0FF hex.   For example,  to make DIFF perform  Verbose comparisons by default,
change the  byte  at 116  hex from 00  to 0FFh.   Now DIFF  will  display  all
differences between files UNLESS the /V option is given on the command line.



Diff Notes:  Error Handling

   If ZCPR 3.3 or above is not present or if available memory is insufficient,
DIFF aborts to the command line with an error message.

   If an  ambiguous file name  was used  in the command or if  an illegal ZCPR
directory or  drive/user combination was given,  DIFF chains to the ZCPR error
handler if present, or aborts to the command line.

   Missing files simply cause DIFF to  set the program  error byte rather than
chaining to the error handler.   This allows command scripts to retain control
in the event of missing files.
:4


Examples of Use:

   a. Where DIFF really excels  is  in  its ability  to  pass  file comparison
      information to the ZCPR environment.   This capability  can  be  used in
      conjunction  with  ZCPR's Flow Control feature  and  other  programs  to
      automate file maintenance in various ways.

      The Flow Control Package (FCP) can be configured to detect the status of
      ZCPR's program error byte and register byte  zero and set the flow state
      accordingly.  Here is a simple example using DIFF, FCP, and ERA commands
      to erase file1 only if file1 equals file2:

      WORK>diff file1 file2;if ~er;era file1;fi

   b. The following example  uses DIFF, FCP, CP, and ECHO commands to copy the
      most recent of file1 and file2 to the other file:

      WORK>diff file1 file2 /d;if 0 1;cp file1 file2;else;if 0 2;<<
      cp file2 file1;else;echo error;fi;fi



Examples of Use (cont'd):

      This is equivalent to the following pseudo-code:

      run DIFF
      if file1 was created/modified after file2
         copy file1 to file2
         else
         if file2 was created/modified after file1
            copy file2 to file1
            else
            echo error (files or datestamps missing, or files equal)
         fi
      fi

      If one  or  both files  are  missing  or have  missing stamps, or if the
      filestamps are equal, the word "ERROR" appears on the screen and no copy
      operation is performed.



Examples of Use (cont'd):

   c. Many more complicated scripts are possible.   The two  preceding samples
      were issued from  the command line,  but command scripts are most useful
      when issued from a  script processing program,  such  as ZEX  or ZFILER.
      For example,  the  following command script can  be used under ZFILER to
      update all non-archived files  at the  current directory to  the current
      user  area  of  drive C:.   To use  the macro,  I press G-T (group tag),
      followed by G-A (group archive) and finally G-ESC-A (group macro A):

      A $d$u:;$!diff c:$f /q;if er;copy $f c: /ae;else;fa $f a;fi

      If DIFF does  not  find  a  matching  backup  on drive C, the ZSDOS COPY
      program makes a  fresh archive  from the current drive.   If  a matching
      backup was found,  the ZSDOS FA  command simply sets  the file's archive
      attribute.



Examples of Use (cont'd):

   d. Finally, DIFF can be used to  select files by their temporal relation to
      another file and process them accordingly.   For instance, to append all
      files created before  a particular file  to an archive file, I  use  the
      following ZFILER macro, invoked by pressing GT, then G-ESC-N:

      N $d$u:;diff $p $"Newer file: " /dq;if 0 2;<<
      append $f $"File to append to:";era $f;fi