    PMERGE:  Alethic BackMail phone directory merge utility

PMERGE allows one to merge all the data entries from a 'foreign' phone
directory into one's own thus reducing a certain amount of drudge-work
among a network of BackMailers.  To start PMERGE use the following syntax:

        PMERGE [-Bpathname -Q -Paaaxxxyyyy] <Enter>

Where the options are explained as follows:

-B is the path to the original phone directory.  The user may enter this
switch explicitly or set an environment variable called BACKMAIL to this
path (e.g. by entering the DOS command SET BACKMAIL=c:\mypath).
IMORTANT NOTE:  when entering this path, DO NOT terminate with the
'backslash' character ("\"). If neither option is exercised then PMERGE
will assume that the user's original phone directory is to be found in
C:\BACKMAIL.

-Q requests 'quiet' mode.  When running in this mode PMERGE will not print
error messages but rather will indicate fatal errors by means of exit
codes alone.  These codes, the meaning of which is detailed below, may
be retrieved by the DOS batch processor.

-P is the user's phone number which must be in ten digit format without
spaces or punctuation symbols e.g. 8769024312.  As an alternative to
entering this option on the PMERGE command line, the user can set an
environment variable called PHONE to the required number.  If PMERGE can
not discover the user's phone number either from the command line option
or the environment, it aborts with an error message (or exit code alone
depending on the mode).


                            USAGE NOTES

PMERGE expects both the original and the 'foreign' phone directories to be
named PHONE so evidently they cannot both be in the same subdirectory.  It
is normally the case that one receives a new phone directory by means of
BackMail, so it will be called PHONE and reside in the user's transfer
subdirectory (where all files go that are received by BackMail).  PMERGE
requires that the new phone directory be in the current subdirectory.  Here's
a scenario:  a new phone directory is sent to the user and ends up in the
subdirectory C:\BACKMAIL\TRANSFER.  The user can now either place the
program PMERGE.EXE somewhere on their path (as set by the DOS command PATH=)
or copy the program to the transfer subdirectory.  Now to merge the new
phone directory with e user's original phone directory, the user issues the
command:
           CD C:\BACKMAIL\TRANSFER <Enter>

in order to make the transfer subdirectory current.  Next the user issues:

           PMERGE -P8174236543 <Enter>

where the string following the '-P' is the user's phone number including
area code but without punctuation.  Notice that in this example, the user
keeps the original phone directory in C:\BACKMAIL so there is no need to
enter the -B option.  PMERGE will then print a 'banner' and a number of
messages detailing its operation since 'quiet' mode is not in effect (the
-Q option was not given).  When it has finished, the user's phone directory
in C:\BACKMAIL will have been increased by the addition of those data numbers
in the 'new' phone directory such that (1) the numbers in question did not
already appear in the original directory (i.e. PMERGE will not create
duplicate entries) and (2) The user's own number will not be included even
if there is such an entry in the 'new' directory.  This is the reason that
PMERGE insists on being told the user's telephone number before it will
operate.

                LIMITATIONS and CAUTIONS

PMERGE cannot 'merge in' new phone numbers if the user's current phone
directory contains 3000 data entries or more already.
If either the new directory or the original directory has become corrupted,
then the result of running PMERGE will certainly inherit this corruption.
Phone directories can become corrupt in a number of ways (not excluding
malice) so it pays to take precautions.  Alethic recomends frequent
saving of backup copies of phone directory and mail files (notice that these
files are intimately related so that a saved PHONE without its corresponding
OUTMAIL at least will cause trouble up to and including a system crash).  In
particular, it would be sensible to make a backup copy of PHONE before
running PMERGE.

            ERROR MESSAGES and EXIT CODES

The following are the error messages and exit codes produced by PMERGE when
it encounters an error condition.  In quiet mode, no message is printed
except for error 1.

EXIT CODE               MESSAGE                 ACTION

   1                    PMERGE found an option  Re-enter the command line with
                        on the command line     typos corrected.  Consult the
                        which it couldn't       list of options.
                        interpret.  A summary
                        of the allowable
                        options is printed.

   2                    No phone number found.  Either re-enter the command
                                                line giving the -P option or
                                                set the environment variable
                                                PHONE to the user's number.

   3                    Bad phone format.       Re-enter the command line or
                                                re-set the environment
                                                variable making sure that the
                                                number has 10 digits (include
                                                area code) with no spaces or
                                                punctuation.

   4                    Error opening user's    Make certain that PMERGE is
                        original phone          told the correct location of
                        directory.              the original directory either
                                                by means of the -B option or
                                                the environment variable
                                                BACKMAIL.  If this information
                                                is not given PMERGE, will
                                                assume (perhaps wrongly) that
                                                the phone directory is in
                                                C:\BACKMAIL.

   5,6                  Error creating          During its operation PMERGE
                        temporary files.        must create temporary files to
                                                hold information.  If the user
                                                is low on disk space this error
                                                might well result.  Clean up
                                                unnecessary files.

   7                    Error opening file      The 'foreign' phone directory
                        of new phone numbers.   must be in the current
                                                subdirectory.

   8                    Error writing to        This error, like 5 and 6 is
                        temporary files.        typically the result of not
                                                having enough disk space to
                                                run PMERGE.

  9                     Wrong version.          PMERGE has discovered that one
                                                or both of the phone
                                                directories that it has been
                                                asked to merge are in a format
                                                that it doesn't recognise.
                                                Make certain that both phone
                                                directories are in BackMail
                                                format and of a version which
                                                is no later than the version
                                                of PMERGE (printed when it
                                                starts).  If necessary obtain
                                                a later version of PMERGE.
