ARCHIVE COPY (Version 1.72)
ARCOPY is a small, fast file copy and backup
utility for DOS. It allows copying different
groups of files, all except certain files,
backup files by time stamp or archive flag,
and more.

ARCOPY.DOC
----------
Instructions for ARCOPY.COM
Version 1.72 (16 Feb 1993)

(c)1988-93 E. Meyer


ARCOPY (ARchive COPY) is a small, fast file copy utility for all MSDOS
(2.x and above) systems. Its features are geared toward the task of backing
up (archiving) files, but it can also simplify ordinary file copying, moving,
and renaming.
ARCOPY is designed for command line aficionados who want to be able to do
as much as possible at one DOS prompt. It can copy different groups of files
at once; copy all except certain files; backup files by time stamp or archive
flag; select files to copy by existence on destination directory, or by
prompting the user individually; move files easily from one directory to
another; do ambiguous copying and renaming safely; and more.

The syntax and options of ARCOPY are compatible with my DTA (directory/
tree/attribute), DIRCMP (directory compare), and DLT (delete) file utilities,
which work well together.


USING ARCOPY
------------

SYNTAX: A>ARCOPY source{,source2,...} {dest} {/options} "{}"=optional

"source,etc" - filespec(s) to copy from.
"dest" - directory and/or filespec to copy to.
"options" - follow slash "/"; see below for list.

Like the DOS COPY or XCOPY command, ARCOPY expects two arguments: a
source and a destination filespec. Any filespec may contain a path and/or
wildcards. Common device names (CON,PRN...) are also accepted. If the
destination is not completely specified, its directory defaults to the current
one, and its filename to the same as the source file.

However, the source may be a list of files as well, delimited with
commas; if so, the previous filespec's drive and directory carry over to the
next, unless the next begins with a drive or root directory.

ARCOPY lists files in each source filespec alphabetically as it processes
them; you may abort at any time by typing ^C. If the destination names are
different, both names are shown: OLDFILE.NAM -> NEWFILE.NAM.


OPTIONS: "Options" must be preceded by one slash "/"; separating
spaces, and further slashes, are optional. The /A,M,P
options are identical to those of the DOS XCOPY utility; the
/H,W,Z options resemble those of the CP/M PIP utility, if
anyone remembers that.

/? - display help message

/A - only files with the ARCHIVE attribute will be copied. (See "Incremental
Backup" below for further explanation.)
/B - only files with timestamp BEFORE specified date/time (see formats below)
will be copied. (Defaults are today, 0 hours.)
/E - only files previously EXISTING on the destination directory will be
copied. (Normally used together with /T,A,M for incremental backup.)
/H - HIDDEN and System files, normally ignored, will be found and copied
along with normal files.
/L - only files with timestamp LATER than specified date/time (see formats
below) will be copied. (Defaults are today, 0 hours.)
/M - only files with the Archive attribute are copied, and then MARKED by
having their Archive attribute removed. (See "Incremental Backup" below.)
/N - only files previously NOT existing on the destination directory will be
copied.
/P - you will be PROMPTED "y/n?" for each file about to be processed. Press
"Y" to copy the file, or "N" to skip it.
/R - files will be RENAMED or moved: renamed, if the directory is the same;
moved, if the destination directory is different.
/T - existing files on the destination directory will only be overwritten if
the source copy has a more recent TIMESTAMP.
/W - copying may WRITE over or delete Read-only files. (Normally, any
attempt to do this will cause a DOS error.)
/X - all files (*.*) EXCEPT those named will be copied. (This option
requires a single source, not a comma-delimited list.)
/Z - the high (parity) bit will be ZEROED in the output file, which converts
nonstandard data (like WordStar text) into readable ASCII form.


INCREMENTAL BACKUP: /A,E,M,T

It's important to maintain backup copies of important data, but this can
be a tedious task. Fortunately you don't need to remember exactly which files
have been modified recently; there are two automatic ways to update disks by
selecting and copying just those files that need it ("incremental backup").

(1) THE ARCHIVE ATTRIBUTE
MSDOS maintains an attribute called Archive in a file's directory entry.
Whenever a file is modified, this attribute is set. Consequently, if this
attribute was cleared in the past (the last time you did a backup), the files
which now have it set are those you have created or changed since, and need to
back up now.
ARCOPY can copy just those modified files, and (if you want) clear their
attribute again to indicate they have been archived. So all you have to type
each time you want to back up the contents of a directory to disk B: is:
ARCOPY *.* B: /M
In conjunction with this, when you are first setting up your disks, you may
find a use for a utility that can manually set or clear the Archive attribute
on groups of files, such as my DTA.COM.
The /A option works the same way, but does not reset the Archive
attribute on files after copying. The /E option can be added to either one,
in order to archive only a certain group of files (see below).
(Users of DOS 3.x or later should look up the ATTRIB and XCOPY utilities
in their DOS manual for an alternative approach to the task.)

(2) THE TIMESTAMP
If your computer's clock maintains the correct time and date, the MSDOS
file timestamp can also be used to determine whether one copy of a file has
been modified more recently than another. Thus, you can also back up files by
typing: ARCOPY *.* B: /T
Files that already exist on B: will only be copied if the source copy is more
recent. In addition, all files that don't already exist on the destination
directory will be copied, so B: will become a full backup for the current
directory. If you want to avoid this, add the /E option:
ARCOPY *.* B: /E/T
This time only files already existing on B: are updated. This allows B: to be
the backup for only a certain group of files in the current directory (which
can therefore be backed up on multiple disks).
This method of backup is generally the easiest to use.


COPYING BY TIME STAMPS: /B,L

With the /B and /L options, you can choose to copy only files dated
before or later than a given date or time. (You can even use both together,
to specify an interval of time.)
In either case, the date and/or time should follow the option letter; if
both are specified, separate them with a comma. If the time is omitted, it
defaults to 0 hours (12 AM); if the date is omitted, it defaults to TODAY.
ARCOPY recognizes U.S., European, and Numeric formats for entering each, by
the punctuation used:
U.S.(M/D/Y,H:MMa-p) Euro (D.M.Y,H:MM) Num (Y-M-D,HHMM)
3/25/90,1:45p = 25.3.90,13:45 = 90-3-25,1345
(If you add the /A or /P option after a Euro format time, insert a slash or
space so it doesn't look like a U.S. format time.)
To make selecting files by age more convenient, you can specify a time so
many days or hours AGO simply by using a "-" sign: thus "-3" means 3 DAYS ago,
"-,2" means 2 HOURS ago. Examples:
/L today (later than today, 0:00)
/L-,1 in the last hour
/B12:45a before 12:45 AM today
/L25.3.90,13:00 later than March 25 1990, 1 PM
/L89-12-1 /B90-1-1 any time in December 1989


MOVING AND RENAMING FILES: /R

The /R option has powerful moving and renaming features, depending on the
circumstances of its use. If the destination is another drive, files are
copied and then the originals are deleted. If it is another directory on the
same drive, files are quickly re-assigned to the new directory. If it is the
same directory, files are simply renamed. Examples:
ARCOPY B: A: /R move all files from drive B: to A:
ARCOPY *.DOC \NEW /R move files *.DOC from current dir to \NEW
ARCOPY *.DOC,*.TXT * /R remove filetype from all files *.DOC,*.TXT


MISCELLANY: /H,N,P,W,X,Z

The /H,/P,/W,/Z options are all quite straightforward. /N can be useful
for reconciling two directories in a simple situation where different versions
of the same file aren't an issue; it copies only files that aren't already in
the destination directory. /X will copy all files except those named in the
source filespec -- note that it cannot be used with a comma-delimited list.
Examples:
ARCOPY *.COM,*.EXE B: /N copy all COM/EXE files not already on B:
ARCOPY TEMP.NOT A: /X copy all files except TEMP.NOT to A:


SAFE COPYING AND RENAMING

Renaming groups of files (or copying them to new names) can create
unexpected problems. If the wildcards match exactly (as in *.DOC to *.BAK)
it's straightforward enough. But (unlike COPY or XCOPY) ARCOPY also lets you
do more complex renaming safely, when it's difficult to forsee results which
depend on the specific filenames encountered. Suppose you want to create
backup copies on drive B: of some text files on drive A:. You might type:
ARCOPY A:*.* B:*.BAK
Now, if the files on drive A: were KLAATU.DOC, GORT.DOC, and NIKTO, this would
work just fine, and ARCOPY would create copies (B:KLAATU.BAK etc) as intended.
But suppose there had been a fourth file A:GORT.TXT. Both it and
GORT.DOC would have to be copied to the same destination B:GORT.BAK, causing
one file to overwrite the other, which is likely to be a bad idea. The DOS
copy commands go ahead and do this, and you'd think you had copies of all four
files, when you only had three. ARCOPY is more intelligent: before processing
each group of files (here *.*), it checks to make sure their output names are
all different from one another (and from those of any previous groups), and if
not it will give a warning ("Conflict") and skip the group.
Similarly, ARCOPY will warn of situations where a file would be copied
onto itself and destroyed ("Overwrite") or an illegal filename would be
created ("Illegal"), and skip the offending group; the DOS commands allow the
error to occur, then announce it and quit.


ABOUT DEVICES

MSDOS provides a number of "device names" which may be used in place of a
filename, as either source or destination. ARCOPY fully supports these: AUX,
COM1-4, CON, LPT1-2, LST, PRN, NUL. The most useful are:
CON - the console (keyboard input, screen output)
PRN - printer output
Console input is terminated with ^Z, RETURN. (Certain disk file specific
options are not allowed with device I/O. Note also that ARCOPY reads disk
files as binary data, and does NOT treat ^Z as an end of file marker.)
Example: ARCOPY PAPER.DOC CON /Z types word processor file PAPER.DOC
onscreen in ASCII



CUSTOMIZING ARCOPY
------------------

You can use DEBUG or a similar utility (like the Norton disk editor) to
change ARCOPY's text colors (on IBM PC compatibles). Use of contrasting
colors can make the display more easily readable. All values below are in
hexadecimal. (Note: the addresses shown are for DEBUG; for most disk editors,
subtract 0100.)

ADDRESS ORIGINAL
IN ARCOPY.COM VALUE FUNCTION POSSIBLE VALUES
0108 FF Use color output? 00=no, FF=yes
0109 07 Message color 00-FF \
010A 0F Filename color 00-FF >see below
010B 07 Error color 00-FF /

COLOR OUTPUT: With this set to FF, ARCOPY will use PC BIOS output for a
color display on IBM PC compatibles. If you set this to 00, ARCOPY will use
standard DOS output.

COLORS: Specify each color by a pair of hex digits for background and
foreground, according to the following codes:
0 = BLACK 4 = red 8 = GREY C = bright red
1 = blue 5 = magenta 9 = bright blue D = bright magenta
2 = green 6 = brown A = bright green E = yellow
3 = cyan 7 = WHITE B = bright cyan F = BRIGHT WHITE
For example, "17" means "blue background, white text".
All monochrome screens can display black, white, and bright white; in
some cases, grey may also be visible.
Colors 8-F should generally be avoided as background colors because they
produce blinking video. On EGA/VGA displays, if blinking video is disabled,
the whole range of background colors will be available.

EXAMPLE: To change the error color to yellow on red, type "DEBUG
ARCOPY.COM", then "E010B 4E", then "W", then "Q".

Please distribute copies of ARCOPY with original settings only, to avoid
confusing other users.



ERROR MESSAGES

Missing, illegal, or invalid filespec or option
Nonexistent drive/directory
Destination would have been the same as source
Two sources would have copied to the same destination
A file with an illegal name would have been constructed
Too many files (over 1000; try copying fewer at once)
DOS error opening or reading source file
DOS error on output: full disk, read-only file, etc
Not enough memory available
User pressed ^C to abort operation

If an error occurs, ARCOPY sets the DOS error code, so that batch files
can test the ERRORLEVEL to determine subsequent action. Normally 0, the value
returned will be the sum of whichever of the following errors occurred:
1 = bad argument/option/directory 16 = disk error (read/write)
2 = out of memory 128 = user abort
4 = files skipped (overwrite/conflict/illegal/overflow)


HISTORY

ARCOPY 1.0 (Mar88) - First release, based on my previous CP/M utility ARCOPY.
1.1 (Jul88) - New options /T, /?. Improved parsing.
1.2 (Apr89) - Comma-delimited multiple source lists.
1.3 (Oct89) - Improved efficiency of copying and moving files.
1.4 (Dec89) - New options /B, /L. Improved parsing.
1.5 (May90) - Small fixes; simplified multiple-source syntax.
1.6 (Apr91) - New option /X. Small fixes.
1.7 (May91) - US/Euro/Numeric time,date formats. Small fixes.
1.71 (Oct91) - Improved conflict detection; sets DOS ERRORLEVEL.
1.72 (Feb93) - /B,L accept "-" for "ago"; color output.

ARCOPY and its documentation are (c)1988-93 E.Meyer, all rights reserved.
They may be freely distributed, but not modified or sold for profit without my
written consent. (Exception: Libraries may charge up to $6 for a disk.) The
user takes full responsibility for any damages resulting from the use of this
program. For a disk with the latest versions of all my programs send $10 to:

Eric Meyer
3541 Smuggler Way CompuServe [74415,1305]
Boulder, CO 80303 USA