home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / CPM / ZCPR33 / A-R / DIFF30.LBR / DIFF30.DZC / DIFF30.DOC
Text File  |  2000-06-30  |  14KB  |  373 lines
  1.                  DIFF Version 3.0 Documentation
  2.                         February 19, 1989
  3.                           Carson Wilson
  4.  
  5.  
  6.                           - Contents -
  7.  
  8.           1.  Overview.
  9.  
  10.           2.  System Requirements.
  11.  
  12.           3.  Purpose.
  13.  
  14.           4.  Operation.
  15.  
  16.           5.  Usage.
  17.  
  18.               5.1.  Command Line Syntax.
  19.  
  20.                   5.1.1.  File Specifications.
  21.  
  22.                   5.1.2.  Options.
  23.  
  24.                       5.1.2.1.  D - Test Datestamps Only.
  25.                       5.1.2.2.  I - Ignore Datestamps  
  26.                       5.1.2.3.  M - Perform Multiple Comparison.
  27.                       5.1.2.4.  Q - Perform Quiet Comparison.
  28.                       5.1.2.4.  V - Perform Verbose Comparison.
  29.                       5.1.2.6.  Combining Options.
  30.  
  31.               5.2.  Advanced Use With Command Scripts.
  32.  
  33.           6.  Customizing DIFF.
  34.  
  35.           7.  Error Handling.
  36.  
  37.           8.  Acknowledgements.
  38.  
  39.           9.  Legal Use of These Files.
  40.  
  41.  
  42.  
  43. 1.  Overview.
  44.  
  45.      DIFF version 3.0 is an extensively modified and improved 
  46. version of the original ZCPR 3.0 DIFF utility by Richard Conn.  
  47. The program's basic functions have been enhanced to take 
  48. advantage of ZCPR 3.3 and 3.4, and several additional functions 
  49. have been added.
  50.  
  51.  
  52. 2.  System Requirements.
  53.  
  54.      DIFF now requires ZCPR versions 3.3 and above to operate.  
  55. Additional features are available if DIFF is used under ZSDOS, 
  56. Z3PLUS, and/or DosDisk, but these system enhancements are not 
  57. required by DIFF.  DIFF100.COM loads at 100 hex and requires 
  58. memory from 100 hex to about 3200 hex.  DIFF6000.COM loads at 
  59. 6000 hex and requires memory from 100 hex to about 9100 hex.  
  60. Insufficient memory causes DIFF to abort with an error message.
  61.  
  62.  
  63. 3.  Purpose.
  64.  
  65.      DIFF quickly compares two files and reports the results to 
  66. the screen and to the ZCPR environment.  This is useful in 
  67. verifying backup copies of files or eliminating duplicate copies. 
  68. Because DIFF reports its findings to the ZCPR environment, it may 
  69. be used with command scripts for automated file maintanence.
  70.  
  71.      In fact, while DIFF can produce a byte-by-byte report of 
  72. file differences, other programs such as Rob Friefeld's BCOMP or 
  73. Malcom Kemp's CPA are more suited to making detailed file 
  74. comparisons.  DIFF's main strength is as a non-interactive, 
  75. command-line or script driven utility.
  76.  
  77.  
  78. 4.  Operation.
  79.  
  80.      By default, DIFF determines file equivalence using the most 
  81. efficient means available.  It first checks for matching file 
  82. names and datestamps and assumes that files with the same name 
  83. which were created or last modified during the same minute are 
  84. identical.  This is much faster in most cases than performing a 
  85. complete data test.  If file datestamps are not present, DIFF 
  86. falls back to a normal data comparison, stopping at the first 
  87. difference, user abort command, or end of file.  If a data test 
  88. is desired regardless of datestamp information, the /I option can 
  89. be used to tell DIFF to ignore datestamps and proceed directly to 
  90. a data comparison.
  91.  
  92.      In comparing file datestamps, DIFF first tries to compare 
  93. the "last modified" stamps.  If a file's "last modified" stamp is 
  94. missing, that file's "create" stamp is used instead.  If either 
  95. file is missing both create and modify stamps, DIFF falls back on 
  96. file data to determine equivalence.
  97.  
  98.      DIFF communicates its results both to the screen and to the 
  99. ZCPR environment.  The program error byte is set to true 
  100. ("ERROR") by default for each file compare, and is only reset to 
  101. false when a matching pair of files is found.  Thus all of the 
  102. following conditions will set the program error byte to "true:"
  103.  
  104.                    a. Either or both files missing
  105.                    b. User abort
  106.                    c. Files do not match
  107.  
  108.      ZCPR register zero is set to reflect the results of 
  109. filestamp comparisons.  Register zero is set as follows:
  110.  
  111.      Register
  112.      0 Value        Condition
  113.      -------        ---------------------------------------------
  114.           0         No stamp comparison was performed, either due 
  115.                     to the /I option or because one or both 
  116.                     stamps were not available.
  117.           1         Source 1 is more recent.
  118.           2         Source 2 is more recent.
  119.           3         Sources 1 and 2 have matching stamps.
  120.  
  121.  
  122.      Unless the /V Verbose option is given, DIFF simply reports 
  123. the results of file stamp comparisons (if any) and data 
  124. comparisons to the screen, telling which file was more recent and 
  125. whether files match or not.  The /V option may be used to 
  126. generate a more detailed report of file data differences (see 
  127. below).
  128.  
  129.  
  130. 5.  Usage.
  131.  
  132. 5.1.  Command Line Syntax.
  133.  
  134.      DIFF's command line consists of the command verb, followed 
  135. by one or two unambiguous file specifications, optionally 
  136. followed by one or more option characters:
  137.  
  138.               DIFF [dir:]ufn [dir:][ufn] [/][options]
  139.  
  140. A leading slash must introduce options if only one file 
  141. specification was given, to prevent DIFF from confusing options 
  142. with filespecs.
  143.  
  144.  
  145. 5.1.1.  File Specifications.
  146.  
  147.      The first file spec is given in the command and is referred 
  148. to as "Source 1."  The second file spec is either given in the 
  149. command or is filled in by DIFF and is referred to as "Source 2".
  150.  
  151.      If only one file specification is given, Source 2 is assumed 
  152. to have the same name as Source 1 and to reside in the current 
  153. directory.  For example, the command
  154.  
  155. WORK>diff root:myfile.txt
  156.  
  157. compares ROOT:MYFILE.TXT with WORK:MYFILE.TXT.  If only a 
  158. directory is given for the second file, DIFF assumes a file of 
  159. the same name as the first, but in the specified directory.
  160.  
  161. WORK>diff myfile.txt root:
  162.  
  163. therefore compares WORK:MYFILE.TXT with ROOT:MYFILE.TXT.  This is 
  164. equivalent to the previous example with the exception that Source 
  165. 1 and Source 2 are reversed.  This is an important difference 
  166. only when interpreting results stored by DIFF in ZCPR register 0 
  167. (see table above).
  168.  
  169.      Since DIFF uses ZCPR's command line parser when interpreting 
  170. drive, user and directory specifications, directory security is 
  171. enforced to current system levels, and DIFF may safely be used 
  172. with secure systems.
  173.  
  174.  
  175. 5.1.2.  Options.
  176.  
  177.      One or more of the following option characters may be given 
  178. following the file specifications:
  179.  
  180.                     D - test Datestamps only
  181.                     I - Ignore datestamps  
  182.                     M - perform Multiple comparison
  183.                     Q - perform Quiet comparison
  184.                     V - perform Verbose comparison
  185.  
  186. As mentioned above, if only one filespec is given, option 
  187. characters must be introduced with the slash character ("/").
  188.  
  189.  
  190. 5.1.2.1.  D - Test Datestamps Only.
  191.  
  192.      Normally, unless matching filenames and datestamps are 
  193. detected DIFF falls back on a file data comparison.  The /D 
  194. option causes DIFF to exit as soon as the datestamp comparison 
  195. has been attempted.  This is useful in situations where only the 
  196. temporal relationships of files are of interest.
  197.  
  198.  
  199. 5.1.2.2.  I - Ignore Datestamps.
  200.  
  201.      The /I option is the complement of the /D option, and causes 
  202. DIFF to skip datestamp comparisons and go directly to a file data 
  203. comparison.  Register 0 is always set to 0 by this option. 
  204.  
  205.  
  206. 5.1.2.3.  M - Perform Multiple Comparison.
  207.  
  208.      If the /M option is given, DIFF repeatedly prompts the user 
  209. for new floppy disks, allowing a file to be compared with other 
  210. files on several floppy disks.
  211.  
  212.  
  213. 5.1.2.4.  Q - Perform Quiet Comparison.
  214.  
  215.      The /Q option causes DIFF to report only error messages to 
  216. the screen; all other screen output is suppressed.  This option 
  217. is designed for use with command scripts which must maintain 
  218. screen control.
  219.  
  220.  
  221. 5.1.2.5.  V - Perform Verbose Comparison.
  222.  
  223.      Normally, DIFF reports only the final results of a 
  224. comparison to the screen.  Selecting the /V option causes DIFF to 
  225. display the ASCII, Hex, and Decimal equivalents of all 
  226. non-matching bytes.
  227.  
  228.  
  229. 5.1.2.6.  Combining Options.
  230.  
  231.      From what we have said above, it should be obvious that 
  232. certain option combinations produce meaningless or contradictory 
  233. results.  For example, combining the /D and /I options causes 
  234. DIFF to do nothing at all.  The /Q option contradicts the /V and 
  235. /M options, and for this reason where /Q is used it takes 
  236. precedence over /M and /V, forcing a single, non-verbose 
  237. comparison.
  238.  
  239.  
  240. 5.2.  Advanced Use With Command Scripts.
  241.  
  242.      Where DIFF really excels is in its ability to pass file 
  243. comparison information to the ZCPR environment.  This capability 
  244. can be used in conjunction with ZCPR's Flow Control feature and 
  245. other programs to automate file maintenance in various ways.
  246.  
  247.      The Flow Control Package (FCP) can be configured to detect 
  248. the status of ZCPR's program error byte and register byte zero 
  249. and set the flow state accordingly.  Here is a simple example 
  250. using DIFF, FCP, and ERA commands to erase file1 only if file1 
  251. equals file2:
  252.  
  253. WORK>diff file1 file2;if ~er;era file1;fi
  254.  
  255.      The following example uses DIFF, FCP, CP, and ECHO commands 
  256. to copy the most recent of file1 and file2 to the other file:
  257.  
  258. WORK>diff file1 file2 /d;if 0 1;cp file1 file2;else;if 0 2;<<
  259.      cp file2 file1;else;echo error;fi;fi
  260.  
  261. The above command is equivalent to the following pseudo-code:
  262.  
  263. run DIFF
  264. if file1 was created/modified after file2
  265.    copy file1 to file2
  266.    else
  267.    if file2 was created/modified after file1
  268.       copy file2 to file1
  269.       else
  270.       echo error (files or datestamps missing, or files equal)
  271.    fi
  272. fi
  273.  
  274. If one or both files are missing or have missing stamps, or if 
  275. the filestamps are equal, the word "ERROR" appears on the screen 
  276. and no copy operation is performed.
  277.  
  278.      Many more complicated scripts are possible.  The two 
  279. preceding samples were issued from the command line, but command 
  280. scripts are most useful when issued from a script processing 
  281. program, such as ZEX or ZFILER.  For example, the following 
  282. command script can be used under ZFILER to update all 
  283. non-archived files at the current directory to the current user 
  284. area of drive C:.  To use the macro, I press G-T (group tag), 
  285. followed by G-A (group archive) and finally G-ESC-A (group macro 
  286. A):
  287.  
  288. A $d$u:;$!diff c:$f /q;if er;copy $f c: /ae;else;fa $f a;fi
  289.  
  290. If DIFF does not find a matching backup on drive C, the ZSDOS 
  291. COPY program makes a fresh archive from the current drive.  If a 
  292. matching backup was found, the ZSDOS FA command simply sets the 
  293. file's archive attribute.
  294.  
  295.      Finally, DIFF can be used to select files by their temporal 
  296. relation to another file and process them accordingly.  For 
  297. instance, to append all files created before a particular file to 
  298. an archive file, I use the following ZFILER macro, invoked by 
  299. pressing GT, then G-ESC-N:
  300.  
  301. N $d$u:;diff $p $"Newer file: " /dq;if 0 2;<<
  302.      append $f $"File to append to:";era $f;fi
  303.  
  304.      These suggestions do not exhaust even the applications I 
  305. have found for DIFF.  I am sure there are many others, and that 
  306. you will discover ways of automating file and directory 
  307. maintenance with DIFF that I have not yet thought of.
  308.  
  309.  
  310. 6.  Customizing DIFF.
  311.  
  312.      As distributed, DIFF's Datestamp, Ignore, Multiple, Quiet, 
  313. and Verbose options are "off" by default, and are turned on when 
  314. the option character is given in the command line.  The sense of 
  315. any or all of the command line options may be reversed by 
  316. altering the five bytes following the ASCII label "[DIMQV>" at 
  317. address 10d hex in the program itself.
  318.  
  319.      As distributed, the five bytes at 112 hex are 0,0,0,0,0.  To 
  320. change an option to "on" by default, set the corresponding byte 
  321. following the label to 0FF hex.  For example, to make DIFF 
  322. perform Verbose comparisons by default, change the byte at 116 
  323. hex from 00 to 0FFh.  Now DIFF will display all differences 
  324. between files UNLESS the /V option is given on the command line.
  325.  
  326.  
  327. 7.  Error Handling.
  328.  
  329.      If ZCPR 3.3 or above is not present or if available memory 
  330. is insufficient, DIFF aborts to the command line with an error 
  331. message.
  332.  
  333.      If an ambiguous file name was used in the command or if an 
  334. illegal ZCPR directory or drive/user combination was given, DIFF 
  335. chains to the ZCPR error handler if present, or aborts to the 
  336. command line.
  337.  
  338.      Missing files simply cause DIFF to set the program error 
  339. byte rather than chaining to the error handler.  This allows 
  340. command scripts to retain control in the event of missing files.  
  341. See the ZFILER command script in section 5.2 for an example of 
  342. this.
  343.  
  344.  
  345. 8.  Acknowledgements.
  346.  
  347.      The use of file datestamps to compare files was adapted from 
  348. Bridger Mitchell's DATSWEEP utility, which is part of 
  349. Plu*Perfect's DateStamper system and will be included with the 
  350. ZSDOS operating system.
  351.  
  352.  
  353. 9.  Legal Use of These Files.
  354.  
  355.      DIFF is an official ZCPR utility.  As such, it is released 
  356. to the public for personal use, but commercial use must be 
  357. licensed by Alpha Systems.
  358.  
  359.      I encourage you to explore the source code, suggest 
  360. improvements, and document errors.  However, please obtain 
  361. permission before redistributing any of these files in altered 
  362. form.  This will prevent confusion by allowing your work to be 
  363. coordinated with the efforts of others.
  364.  
  365. Carson Wilson may be reached via
  366.  
  367.          Antelope Freeway Remote Access System, Chicago
  368.                           312-764-5162
  369.                   300-1200-2400 Baud, 24 Hours
  370.  
  371. As I am sysop of this system, you may leave comments for me when 
  372. you apply for access.
  373.