Documentation for CMPBBS version 1.0
By Ken Goosens
19 February 1990

Contents
1.0 What is CMPBBS?
2.0 How CMPBBS Can be Useful to You
3.0 How to Set up and Run CMPBBS
4.0 An Example
5.0 Details and a Caution
6.0 Recompiling

1.0 What is CMPBBS?

CMPBBS is a utility for comparing two lists of files. The
first, your master list of files that you already have, is compared
to the second, a list of files from another source. Written
out is the ones new, that is, in the other source and not in your
master. CMPBBS is distributed with the following files:

CMPBBS.BAS - Basic source code
XMODEM.OBJ - Assember subprogram required for recompiling
CMPBBS.DOC - This documentation
MASTER.DIR - Sample list of files you have
DEATHSTR.DIR - Sample list of files from BBS to compare to master
DISK1.DIR - Sample list of files from diskette to compare to master
CMPBBS.CFG - Configuration file to drive the master


2.0 How CMPBBS Can be Useful to You

CMPBBS has one main application: you maintain a list of files you
already have, for example, on your own BBS. Most BBS's make a list
of all downloadable files available for downloading. You get
lists of files that are on other BBS's. The 1st thing you want to
know is what's new on the other lists. CMPBBS is designed to tell
you exactly what is new.

CMPBBS is design to run extemely fast on large numbers of files. For
example, it will compare lists with 8000 entries in about a minute on
a 10mhz 80286. It has no trouble handling up to 30,000 files.

You might want to select the new files for downloading.

But CMPBBS is designed especially to support another type of application:
namely, SysOps who want to maintain a list of files available
"off line", that is not their own BBS. With RBBS-PC 17.3A, you
can automatically inform callers on what other boards the
files are on. Or you can maintain your own files off line on removable
media, such as floppy disks, and log requests for those files for you
to inspect and restore the next day. Many SysOps maintain lists of
offline files but they are inconvient to use because they must be noted
as being off line in the directories, and require the caller to leave
a message. RBBS-PC 17.3A makes this work so automatic that it is easily
to set up and maintain for all involved.

If you are running RBBS 17.3A or higher, just install the Fast File
System and get other SysOps to give you their updated file lists. You
can become a kind of "library" resource on where all files in the area
can be found.


3.0 How to Set up and Run CMPBBS

CMPBBS gets its directions from a configuraton file whose default name
is CMPBBS.CFG. This file specifies what your master file is, what
lists to compare it to, and what to write the new files to. Just
load up CMPBBS.CFG into a full screen editor and following the
commented directions in the file. You can specify the configuration
file to use on the command line, e.g. to use CMPBBS.KG simply say

CMPBBS CMPBBS.KG

CMPBBS will display the parameters it reads from the configuration
file and give you an opportunity to confirm that you want to run with
them as specified. You can bypass the confirmation by putting "/B"
on the command line to make the program run batch.

Note that you can compare up to 200 lists in a single run.


4.0 An Example

Enclosed is an operating example:

MASTER.DIR - list of files you have
TEST1.DIR - list of files to compare to your master
TEST2.DIR - list of files to compare to your master
CMPBBS.CFG - Configuration file to drive the master

Type in

CMPBBBS

and in response to the displayed screen, press Enter. If you compare
MASTER to TEST1 and TEST2, you will see that each contains two new files
not in MASTER, which are written out to NEWLIST.DIR.

out the ones in the 2nd and not in the 1st.


5.0 Details and a Caution

CMPBBS is enormously fast - magnitudes faster than other BBS compare
programs. This lightning speed is achieved by using CRC checks rather
than the file name, which allows the entire index to be held in memory
and to be searched in a single step. But this lightning speed occurs
at a theoretical cost:

o it is possible that two distinct file names will be treated
as the same.

Possibly, but very unlikely. Since most BBS lists will overlap
heavily and there are relatively few new files, the likelihood of
having a file that is really new but not treated as new (because
its CRC is the same as another file on the list) is tiny but not
zero. BUT IF YOU MUST BE CERTAIN THAT EVERY NEW FILE IS REPORTED
AS NEW, DON'T USE CMPBBS. For the applications it was designed to
cover, occasionally missing a new file is a small price to pay for
the enormous increase in speed of execution.

CMPBBS allows the column in which the file name begins to be
specified in the configuration, separately for the master directory
and the dirs to be added. CMPBBS does expect the file name to be in
the 12 characters at and following the starting column. CMPBBS
also requires that the file name be in ALL CAPS.
The file name can either have a period separating the prefix
and extension, or a space, and will be treated the same in each case.
However, if a space separator is used, the extension must begin in
the 10th column of the name field. The line will be skipped if
the first column of the name field is a space or one of the
following characters: /[]|<>+=;,?*


The outputted list of new files can be used as listable directory.
If processing multiple sources, you will probably want the source
to be identified in the output. This can be accomplised by
including the "OutCatAt" parameter. This specified the column
at which a category is to be written. The category will be
constructed from the first three characters of macro name specified
by the "Header" parameter. For example, the macro "DEATHSTR.IMC"
will have "DEA" as its category classification. Using a OutCatAt
causes the output to be fixed length. Any description in those
columns will simply be overwritten by the category.


6.0 Recompiling

CMPBBS uses QuickBasic source code that requires QB 4.5 or higher,
plus the assembler source code XMODEM.OBJ to calculate the CRC value.
It can be recompiled as follows:

bc CMPBBS /O/X;
link CMPBBS+XMODEM;