1 FDIFF
!
The NSWC-developed FDIFF utility is used to generate a report showing the
differences, over time, of the contents of a directory structure.  FDIFF
shows the names of files which have been deleted, added, or modified since
the last time FDIFF was run on the directory structure.  The directory
structure can encompass an entire disk pack, as long as the user running
FDIFF has legal access to all the directories on the pack.

Since many directory structures contain files that constantly change, FDIFF
allows the use of an exclusion list, which names files which should not be
reported.

2 Parameters

FDIFF takes two parameters.  The first must be the name of the directory,
directory structure, or disk to be analyzed.  Examples of valid parameters
are:

		K55SOFTWAREDISK     (a disk name; entire disk is checked)

		UDISK2:[AUSER...]   (a directory structure)
		UDISK2:[AUSER]      (a single directory)

A rooted logical name can be specified where a disk name is expected, and
is treated as a disk name.

A search list logical name can be used to have two or more disjoint direc-
tories or structures processed together:

	$  DEFINE  ALIST  [AUSER...],[BUSER...]
	$  FDIFF   ALIST

The second parameter must be the location and name for files used and
generated by FDIFF.  These files include:

	The report output file (type .DOC)
	The baseline output file (type .BASELINE)
	The optional exclusion list (type .EXCLUDE)
	Temporary files (type .FDIFFn, n=1-4)

An example of a valid second parameter is "UDISK2:[AUSER]MY".  This
will cause all files to be placed or sought in directory UDISK2:[AUSER],
and the files will be named MY (for example, MY.DOC, MY.BASELINE, etc.)

Examples of FDIFF commands are:

	$  FDIFF  MYDISK:  UDISK2:[AUSER]MYDISK
	
	$  FDIFF  UDISK2:[AUSER...]  STRUCT

The latter example will create a report STRUCT.DOC in the current
default directory.

2 Output_files

FDIFF creates several temporary files, which are deleted before FDIFF
terminates, and two output files.  Note that the temporary files can
be left if FDIFF is terminated by CONTROL-Y or by an error.  These
files should be deleted manually, since they can take up a lot of
space.  They will have file types .FDIFFn, n=1-4.

The two output files are the report, file type .DOC, and the baseline
file, file type .BASELINE.  The baseline file is required for the next
run of FDIFF.  FDIFF always shows the differences between the current
contents of the directory structure, and the contents as documented in
the baseline file.  If FDIFF runs and finds no existing baseline file
(as will happen the first time it is run on a structure), FDIFF will
build an initial baseline, but produce no report.  FDIFF always purges
the baseline; if it is desired to save old baselines, you must copy
them to a different name before FDIFF purges them.

The report lists each file which changed, with one of the keywords
"New", "Mod", or "Del" showing how the file changed; it was either
created since the last baseline, modified since the last baseline,
or deleted since the last baseline.

The report is produced using RNO, and can be printed, LASERed, or LQPed.
FDIFF does not purge the report file; you must do this yourself.

If you do not like the way RNO formats the report, you can override it;
see subtopic RNO.

3 RNO

The RNO utility is used to create the report .DOC file from a temporary
.RNF file.  The .RNF file begins with the prologue:

	.PAGE SIZE 58,80
	.NO FILL
	.NO FINAL EJECT
	.NO FLAGS ALL
	.MACRO QDIR 1>
	.CANCEL TEXT HEADING
	.TEST PAGE 5
	.BLANK 1;Directory ¨1
	.BLANK 1
	.TEXT HEADING;Directory ¨1 (Continued)
	.BLANK 1 .END TEXT
	.MEND
	.FIRST TITLE <disk or structure name>
	.SUBTITLE ------- ... ------- FDIFF mm-ddd-yy

where the .FIRST TITLE line contains the text of the first parameter to
the FDIFF command, and the .SUBTITLE line is 80 columns wide, with the
current date.

After the prologue comes the body, with lines like:

	.QDIR [A]
	  Mod MYFILE.EXE.3
	  New MYFILE.FOR;1
	  Del MYFILE.OBJ;2
	.QDIR [A.B]
	 . . .

i.e. each new directory is introduced with a .QDIR command, and then the
changes within that directory are enumerated.

If you want to override any of the default format choices, you do the
following:

  1. Create an RNO require file, changing any of the formatting param-
     eters.  Note that you can re-define the .QDIR macro if necessary.
     At the very minimum, this macro should be something like:

	.MACRO QDIR
	Directory ¨1
	.MEND

  2. Invoke FDIFF with then name of your require file, as in:

	$  FDIFF  MYDISK [MYDIR]ZZZ /REQUIRE=ZZZ.REQ

2 Exclusion_list

FDIFF allows optional use of an exclusion list.  This is a file, of type
.EXCLUDE, containing names of directories and files which should not be
reported.  You may elect to suppress the reporting of files which change
often and/or for which changes are not important.  Suppression of these
changes can make it easier to notice important changes in the report.

If you execute  $ FDIFF MYDISK: UDISK2:[MYDIR]MYDISK_C , then the exclu-
sion list must be the file UDISK2:[MYDIR]MYDISK_C.EXCLUDE.

Each line on the exclusion list is either a comment, or an exclusion.
Comments must have an exclamation point ("!") in column 1.  Lines con-
taining exclusions can also have comments after the exclusion.  Examples:

	!
	! Exclusion list for MYDISK
	!
	[AUSER...]	! Remove this next MAY
	[BUSER]*.LOG
	[BUSER]A.DAT
	[CUSER]
	[*]TEST.*

As the examples show, exclusions may be regular or wild-card file
specifications, or the names of directories or directory trees.

Each exclusion can also contain one or more FLAGs.  Flags must
follow the exclusion on the same line, after one or more blanks
or tabs.  Examples of exclusions with flags are:

	[AUSER]*.LOG	M     ! Ignore modifications to log files
	[AUSER]*.DAT	D1    ! List all .DAT deletions after the first
	[AUSER]*.RNO	ND    ! Ignore new and deleted .RNO files

The allowed flags are:

    D - Exclude this file if it was DELETED.

    M - Exclude this file if it was MODIFIED.

    N - Exclude this file if it is NEW.

    1 - Exclude only one file meeting the specification, then
	ignore this exclusion for the remainder of this FDIFF run.

An example of using flags together is "DM", which means exclude this
file if it was deleted or modified (but not if it was new).

Specifying no flags is the same as specifying "DMN"; specifying "1"
by itself is the same as specifying "DMN1".

2 Limitations

FDIFF can take quite a while to analyze a large disk or directory
structure; it should be run in batch mode.  The baseline file, and the
temporary files, can be quite large.

If FDIFF finds a very large difference in the structure, it can overflow.
This can happen, for example, if several thousand files are deleted from
a disk.  In such cases, the report may not be consistent; a diagnostic
message will alert you that this may be the case.

Currently, a maximum of 256 exclusions can be entered in the exclusion
list.  Exclusions containing ellipses ("...") count as two.

