The QL Toolbox '98 Collection
-----------------------------

FComp - A Poor Man's File Comparator
------------------------------------
FComp is a simple utility for comparing the contents of two files. If a
difference is found, the program will display the offset at which the
files differ, and the 8 bytes of information either side of that position.

This program is part of a "family" of utilities which include: ListNames,
DirList, MakeDirs, and CompareDirs. All of these programs share the same
user interface:-

A DO on File 1 or File 2 will call up a standard File Select dialog from
which you can choose the two files to be compared. A HIT on these fields
allows you to directly edit their contents.

Whilst editing a field, most of the standard QDOS editing keys work
as expected. But there are some additional keys which are worth knowing
about:-

[SHIFT]+[SPACE] (Normally the [INSERT] key on a PC keyboard) toggles between
insert and overwrite modes.

[CTRL]+[S] will insert the contents of the scrap at the current cursor
position. Be careful with this, the Scrap can hold a LOT of data!

[CTRL]+[SHIFT]+[S] puts the current contents of the edit buffer into the
Scrap, overwriting anything already there.

[CTRL]+[SHIFT]+[H] puts the current contents of the edit buffer into the
HotKey System II Stuffer Buffer.

[CTRL]+[SHIFT]+[F] calls up the Menu Extension's Character Select dialog,
allowing you to select any character to insert at the current cursor
position.

To Scrap
--------
If "To Scrap" is selected, the results of the comparison are sent to the
Scrap, where they can be pasted into other applications (e.g. QD) or
accessed from S*BASIC. Otherwise, all output appears in the main program
window.

Verbose
-------
The optional "Verbose" setting, if selected, causes the program to display
extended filing system (Level 2) attributes for both files.

Lengths
-------
If selected, this allows the program to compare files that are different
lengths. This is especially useful for comparing two text files to find the
first line where they differ. When not selected, the program will not
perform a comparison on files unless they are of equal length.

Compare
-------
A HIT or a DO on the Compare button starts the comparison.

If the files are different, and either of them is type 1 or 2, the
differing bytes are shown in hex, otherwise they are displayed in ASCII.

FComp may be called with a command line in the following format:-

        File1 File2

        In addition, switches may be passed at any point in the command
        line, and have the following effect:-

        /X If both File1 and File2 have been supplied, and they exist, the
           program will just do the comparison and exit on completion.

        /B In conjunction with /X, this setting causes the program to
           execute completely in the background. It will not display a
           window, nor any dialog boxes. Any confirmation requests will
           be taken as a YES.

        /W In conjunction with /X, this causes the program to wait and
           display the result of the comparison.

        /S Sends output to the Scrap.

        /V Display "verbose" information.

        /L Allows comparison of files not of equal length.

        /0 Ignore any channels that have been passed (see note below).
           This facility is only useful in cases where the program has
           been launched by a shell that automatically sets up the three
           channels stdin, stdout and stderr.

It is also possible to pass a channel to FComp using the EX and QX
commands, in which case the result of the comparison is written to
that channel.

Examples:-

        EX 'FComp_obj';'WIN1_MyFirst_exe FLP1_MyLast_exe /s /x'

        Compare two exe files, sending the result to the Scrap
        (perhaps to be accessed by SCRAP_GET$)

        EX 'FComp_obj',#1;'WIN1_Balderdash RAM1_AndSoOn /x'

        Compare WIN1_Balderdash and RAM1_AndSoOn - sending the
        result to the current S*BASIC's channel #1.

        EX 'FComp_obj','PIPE_Result_100';'Ver1_txt Ver1_bak /x /b'

        Send the result of a comparison between the two files
        Ver1_txt and Ver1_bak, both of which are located in
        the current Data Default Directory, to the Named Pipe
        'Result'. Note: Named pipes require SMSQ or NPipe_Rext.

If three channels are passed, these are taken to be stdin, stdout and
stderr, and the program assumes that it has been launched from a UNIX-like
shell and should act as if it were a simple command-line utility. In
these circumstances, the /X and /B switches are automatically forced on.

Configuration
-------------

FComp can be configured with the Level 1 or Level 2 config programs,
however it has just a single item which is the Block Comparison Size.
By defult, files are compared 512 bytes at a time, this can be
increased to increase the speed of operation, but as a string function
is used to fetch bytes there is the possibility that the Arithmetic
Stack will overflow if a very large number is specified. The result
will be a nasty run-time error message.

Requirements
------------

This program was compiled with QLiberator v3.33 (but with the 3.36mod
runtimes). The file FCompRT_obj has the runtimes bound to it.

Toolkit II and the JMS Menu Extension are required to run this program.

Revision History
----------------

0.20    13/02/1998      First version released.
0.21    14/02/1998      Fixed coding error that always left the
                        Compare button disabled on startup, even
                        if two valid filenames had been passed in
                        the command line.
0.25    23/02/1998      Added support for passing a channel.
                        Added support for /B switch.
0.30    01/03/1998      Copes with multiple channels passed
                        (i.e. stdin, stdout, and stderr)


License Terms
-------------

You are granted a license to use and distribute this software. The
terms of this license are stated below.

Provided that credit is given to the author, and that such credit is
included in any accompanying documentation, whether it be on written
or electronic media ...

1) This program may be freely distributed.

2) This program and its documentation may be incorporated as part of
another package, so long as it does not form the major or substantial
part of such package, and so long as, when taken in combination with
other programs supplied by the author under the same terms, the programs
together do not form the major or substantial part of that package.

3) The executable(s) may be modified, or patched, as necessary, to suit
different target environments. However, where such alterations are made,
and the executables are distributed, details of these changes must also
be included in electronic or written form.

No charge may be made for this program, other than reasonable costs of
electronic media and data transmission to facilitate its distribution.

The author gives no warranty as to the suitability of the program, or
the accuracy of the documentation. The programs are supplied 'as-is'.
It is the responsibility of the user to establish whether the program
is suitable and safe to use in his/her environment.

The author accepts no responsibility for any data that is lost or
corrupted as a result of using this program.

The author will make his best endeavours to fix any problems that are
reported to him, but does not accept an obligation to do so. The author
may be contacted via the E-Mail address quoted at the foot of this
document.


Adrian.D.Ives
ADIves@aol.com
01/03/1998
