    UCOPY.EXE
    =========                       (c) Copyright M N Summerfield 1994


    License
    -------
This program is 'free software' in the sense that you may use it and
copy it freely. The author retains copyright to the program however. You
may not use this program as part of a program that is not 'free
software'. You may not sell this program, although you may charge a
(small) fee for copying and postage if you are a software distributor.
This program comes without warranty of any kind: use it at your own risk.


    Purpose
    -------
UCOPY is designed to copy your files. It is particularly useful for
backing up a whole tree of directories, since it can recreate or extend a
directory tree at the destination, and will only copy new and newer (i.e. 
later time/date stamped) files.
Another important use is to transfer files between two different
machines, 'equalising' their data.


    One Line Summary
    ----------------
Copies new & updated files skipping unchanged ones.


    Example
    -------
Suppose you have a directory tree on your hard disk where you keep files
related to various projects, the root of which is called PROJECTS. You 
could back this structure up as follows:
    
	UCOPY PROJECTS A: /S

This will copy all the files in PROJECTS and its subdirectories onto the
A: drive, recreating or extending the directory structure as necessary.
Whenever you want to back up your PROJECTS tree, you can type the same
command, not worrying about the fact that you may only have changed a
few files since you last backed up, because UCOPY will not copy
unchanged files, only new or changed ones. (Further examples are given
later.)


    Typical Use
    -----------
In practice I keep one floppy disk for each tree in which I keep data,
so backing up at the end of the day is a snap using a batch file which
simply prompts me for the PROJECTS disk, the PERSONAL disk, and so on,
and uses UCOPY to copy just those files that have been added or changed
since the last backup. (If I have a directory which contains more than
about 1 Mb I split it into two or more subdirectories, so that I can
always mirror one subdirectory to one floppy disk.) For those who use
an on-the-fly disk compressor/decompressor, UCOPY is particularly
useful, since you can easily mirror directories of over 2 Mb onto a
single floppy disk.

Another use is to copy all your data files between two different 
machines, in the following way:

    copying from the office machine onto a disk to take home:-
	UCOPY OFFICDAT\*.DOC A: /S
    now copy from the disk to the home machine:-
	UCOPY A: HOMEDAT /S

    copying from the home machine onto the disk to take to the office:-
	UCOPY HOMEDAT\*.DOC A: /S
    now copy from the disk to the office machine:-
	UCOPY A: OFFICDAT /S

    Note that in the above scenario, only *.DOC files are transferred: 
    if no wild-cards had been used all files would have been copied. But
    the two most important things to note are firstly by using the /S 
    switch, all the subdirectories are searched (and recreated on the 
    floppy disk where necessary), and secondly, only new files and the
    most recently updated files are transferred: files which are unchanged
    are not copied. Furthermore, old files do not overwrite more up-to-
    date files.


    Description
    -----------
Entering UCOPY /? will display the following help screen:

	UCOPY <source> <dest> [/S] [/M] [/T] [/B<n>] [/Q] [/A] [/?]
<source> Source may be one or a combination of: a drive, a path, a filename.
    If only a drive, the current path is assumed, and the filename is *.*.
    If only a path, the current drive is assumed, and the filename is *.*.
    If only a filename, the current drive and current path are assumed.
    e.g. ., C:, *.*, FILENAME.EXT, C:DIR, DIR\*.W??, SUBDIR, SUBDIR\SUBDIR.
<dest> Dest may be a drive, path, or both, e.g. ., A:\, A:\DIR\SUBDIR.
/S  Subdir. Recursively copy from and into subdirs as necessary, creating
    subdirs under <dest> as required.
/M  Move. Delete source files & empty subdirs after skipping or copying.
/T  Time/date. Copy using the time/date of copying as the time/date of the
    copied file(s), instead defaulting to the original file(s) time/dates.
/B<n> Buffer. Specify the size of buffer which UCOPY uses in Kbytes.
    <n> is an integer between 1 and 30 which defaults to 30.
/Q  Quiet. Do not display any 'skipping', 'copying', etc messages.
/A  Alarm. Beep once for successful run, twice on error.
/?  Help. Print this help screen.
UCOPY Copies new and newer (i.e. later time/date) source files from <source>
to <dest> that match the source filename (which may include wildcards).
UCOPY can work recursively, (with the /S switch), thus mirroring entire
directory trees from <source> to <dest>. (See UCOPY.TXT for full details.)
	UCOPY v1.1 Standard Edition (c) M N Summerfield 1994.


    Copying Logic
    -------------
    .   If a file with the same name as the source file already exists
	at the destination and the time and date of both files is
	the same, (or the destination is newer), the source file will
	not be copied. (This is 'skipping'.)
    .   If a file with the same name as the source file already exists
	at the destination, but the source file is a later version
	the source file will be copied over the file of the same name
	at the destination. (This is 'copying'.)
    .   If the /M (move) switch has been used, UCOPY will delete the
	original file after it has skipped or copied.
    .   If the /S (subdirectories) switch is used, UCOPY will copy into 
	subdirectories which are rooted in the destination to match
	the directory structure of the source file(s), creating 
	directories at the destination as required, and copying files
	into the matching subdirectories so that the source and
	destination directory tree structures match as do their file
	contents. (If the /M (move) switch is also used source file(s)
	will be deleted after copying or skipping throughout the
	directory tree, and so will empty source subdirectories.)
    .   The <dest> path must exist, but if a subdirectory under <dest>
	does not exist, UCOPY will create it, if the /S switch has been
	used.
    .   If the source is described as *.* and the /S switch is used then
	at the end of the copying process both the source and
	destination directory trees will be identical is structure and
	content (unless the destination has additional files to the source).
	In all other circumstances there will not be an exact match, since 
	if the *.* pattern is not given, some files may not be copied (since 
	their names do not match the pattern), or if the /S switch is not 
	used and there are subdirectories, their contents will be ignored.


    Messages
    --------
If the /Q switch is not used UCOPY will print a message on the screen
for each file and subdirectory processed. Error messages are printed
regardless of the /Q switch. The messages are shown below:

    Skipping <source>
    Copying  <source> to <destination>
    Deleting <source>
    Created  <directory>
    Removed  <directory>

If UCOPY cannot continue due to an error condition it will print an
appropriate message, and usually the name of the file or directory
being processed, and return a corresponding ERRORLEVEL value to DOS.
The 'fatal' error messages, (with their ERRORLEVEL) are shown below:

    No more free memory (1)
    Internal error: contact your supplier (2)
    Source or destination path not given (3)
    Source path invalid or not found (4)
    Destination path invalid or not found (5)
    Destination is not a directory (6)
    Too many files open (7)
    Cannot open destination file: permission denied (8)
    Failed to open file (9)
    Failed to create sub-directory (10)
    Failed to read destination attribute(s) (11)
    Cannot open source file: permission denied (12)
    Failed during copy (13)
    Cannot copy source into itself (14)
    Failed to reset destination's time (15)
    No space on destination drive (16)
    User aborted with <CONTROL>-C (17)


    Notes on Use
    ------------
Command line arguments may be entered in any order, with the 
exception that <source> must come before <dest> and all arguments
must be separated by white-space (one or more spaces and or tabs).
Thus all the following are valid:
	UCOPY /S . A: 
	UCOPY . /S A:
	UCOPY . A: /S
	UCOPY /S . /Q A: /B16

To create an exact mirror between two directory trees, one rooted at 
the current (non-root) directory, the other at A:\
	UCOPY . A: /S
	UCOPY A: . /S

To create an exact mirror between two directory trees, one rooted at 
the root directory of the C: drive, the other at A:\
	UCOPY C: A: /S
	UCOPY A: C: /S
(This would not be sensible in practice since the C: drive is likely
to have far more files than can fit on an A: floppy disk.)

Note that the following are all exactly equivalent:
	UCOPY . A:
	UCOPY .\*.* A:\
	UCOPY *.* A: 
	UCOPY *.* A:\

To copy all your Word .DOC files from C:\PERSONAL\LETTERS to 
A:\LETTERS, assuming that we are on the C: drive, but not in the 
correct directory, and using an 8K buffer
	UCOPY \PERSONAL\LETTERS\*.DOC A:\LETTERS /B8


    Author
    ------
Written by M N Summerfield, (with very useful advice from
Mike Bews), in C++ using Borland C++ 3.1.

I can be contacted by post at:              By email as:
    6 Pantygwydr Road,                          csmarks.pg@swansea.ac.uk
    Uplands,
    Swansea,
    SA2 OJB,
    U.K.


    Stop-Press
    ----------
A Windows 3.1 version is under development. It will offer slightly 
improved functionality over the DOS version, and be fully interactive in
style. In addition it will support scripts (macros) so that users who
often perform the same copying processes can type these in once and have
them executed simply by selecting the appropriate script.

