;
                                  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


