ZCOPY20.DOC	2/10/88

Documentation for ZCOPY v2.0 and ZERA v1.0 by Richard Brewster

ZCOPY is a file copier utility.  Its companion utility ZERA is a 
file eraser.  Both should run on any CP/M 2.2 computer.  Please 
copy and distribute ZCOPY20.COM, ZERA10.COM, and this DOC file 
together.  ZCOPY and ZERA are written in the C language and 
compiled with C/80 by the Software Toolworks.  If you use ZCOPY 
or its companion ZERA, please consider sending me a donation.  I 
have spent hundreds of hours over the past two years developing 
the assembly language and C libraries that support these 
programs.  There are fewer and fewer CP/M programmers these days. 
We need your encouragement.  I hope to write more utilities using 
the same flexible command syntax.  ZGREP is next!

Please send a check for $10.00 to:

     Richard Brewster
     R.D. 1  Box 46
     Brackney, PA 18812       phone: (717) 663-2408

ZCOPY20.COM and ZERA10.COM are Copyright (c) 1988 Richard 
Brewster.  You may use and distribute them freely, but you may 
not charge for these programs.  You may charge only for a 
diskette or other costs of distribution.  Richard Brewster 
assumes no liability whatsoever with respect to another's use of 
ZCOPY20.COM or ZERA10.COM.  Your use of either program 
constitutes acceptance of these terms.

Features shared by ZCOPY, ZERA, and future Zutilities:

1.     Maximum compatibility:

          All 8080 code.
          Standard CP/M 2.2 BDOS calls.

2.     ZCPR style DU: filespec, e.g. A0: 1: B15:, etc.

3:     Wildcard user specs, e.g. B*:

4.     Multiple filespecs on command line.

5.     Flexible order of command line arguments.

6.     Option to Query the user before each operation.
       Query mode may be patched as entry default.
       Query mode may be entered any time by ESC.

7.     R/O file is detected before erasing, and
       user given option to erase or preserve file.

8.     Program can be aborted any time by Control-C.

9.     User patchable maximum drive, maximum user, and maximum
       files matched per wildcard filespec.

10.    Redirected input or output where useful.

ZCOPY Use

The purpose of ZCOPY is to copy a set of files from selected 
locations to one destination drive/user - quickly!  It doesn't 
rename, it doesn't send files to logical devices, it doesn't 
concatenate, it performs no transformation of any kind on the 
file being copied, and it doesn't waste time verifying.  The 
command line arguments to ZCOPY fall into three simple 
categories:  source filespecs, destination, and flags.  These do 
not have to be in any special order on the command line, so you 
can use whatever order feels right to you.

Source Filespecs (similar for both ZCOPY and ZERA)

ZCOPY takes a filespec list of as many source filespecs as you 
can fit on the command line, and more.

Example

     ZCOPY B:TEST 12:HELP HELP2 D:HELP.COM C*:LAST.ONE

will take B(current user):TEST, B12:HELP, B12:HELP2, D12:HELP.COM,
will search all user areas on C: for LAST.ONE, and copy all these 
files to the current drive and user.  Notice that each drive or 
user spec down the list sets a default for those that follow, so 
that you don't have to retype it.

Copying is always from one drive/user to another.  If a 
Read/Write file of the same name exists in the destination 
drive/user, it will be erased before the copy operation begins, 
and you will see the message

     Replacing <filename>
  
If such an existing file is Read/Only, this will be indicated, 
and you will be prompted before the file is replaced.

If the destination drive and user happens to be the same as one 
of the source filespecs, ZCOPY will say

     Not copying <filespec>

and just skip to the next filespec.

ZCOPY checks each filespec for validity as a CP/M filespec.  
Drive letters beyond the maximum (patchable by the user), and 
user numbers above the maximum (also patchable) are disallowed.  
As distributed, the maximum drive is 'P', and maximum user is 15. 
Disallowed printable characters are <>.,:;=[]_/ and space.  Your 
CCP may filter out some of these characters anyway.  If you have 
filenames with any of these characters or control characters in 
them, they are non-standard.

Destination (ZCOPY only)

All copy operations are to one destination drive/user.  To 
specify a different destination drive/user than the logged one, 
just place it somewhere on the command line.

     ZCOPY *.DOC E3:     or
     ZCOPY E3: *.DOC

will copy all .DOC files on the current drive/user to E3:

If you put two or more destination drive/user specs on the 
command line, ZCOPY will use the last one it finds.

     ZCOPY B0: *.DOC C1:

copies *.DOC on current drive/user to C1:

As with the source filespec default sequence, the previous drive 
or user is retained , so for example

     B0>ZCOPY A: C0:*.DOC 1:

copies C0:*.DOC to A1:

Query Option (both ZCOPY and ZERA)

There is a command line option to Query the user before each 
operation.  Adding a '[Q' causes the program to start in Query 
mode.

     ZCOPY *.DOC E3: [Q  or
     ZCOPY [Q *.DOC E3:  or any other order of these

will yield a Query of the following form

     Copying <filename> OK?

to which you may answer in one of five ways:

     Y    copies the file.
     N    (or anything else except the below) skips the file.
     ESC  copies the file, and turns off the Query option, so 
          that all remaining files will be copied.  But see below!
     TAB  skips the remaining files matching the current filespec 
          and goes on to the next filespec, if there is one.
     ^C   exits safely back to CP/M.

Even if you did not give the '[Q' flag on the command line, you 
can enter the Query mode any time you like during multiple file 
operations.  Just type ESC, and the next copy operation will give 
you the Query.  Using ESC you can go back and forth as much as 
you like, toggling the Query mode on and off.  So if you 
accidentally typed *.* and didn't mean it, just hit ESC.

You will be queried about replacing an existing Read/Only file, 
even if not in Query mode.  When this occurs, your options are 
limited to Yes and No.  Anything but 'Y' skips.  The existing 
R/O file WILL BE ERASED if you reply 'Y'.

If you patch ZCOPY.COM to come up normally in Query mode, then 
the [Q flag will cause ZCOPY to come up NOT in Query mode.

Add Mode and Replace Mode (ZCOPY only)

The flag [A on the command line sets Add mode.  Add Mode simply 
refuses to copy any file that already exists on the destination.

The [R flag sets Replace mode, which is just the opposite.  
Replace mode refuses to copy any file that does not already exist 
on the destination.

You can combine Add mode or Replace mode with Query mode, for 
example:

     ZCOPY *.COM B: [QA       or
     ZCOPY *.COM B: [Q [A     or any other order

will run down the list of all .COM files on the current drive and 
user, and will copy only those that you first select, and then 
only if the file does not already exist on B:

Obviously the combination of Add and Replace would not copy any 
files, so those flags found together will cause ZCOPY to abort.

Indirect Input (ZCOPY only)

Instead of - or in addition to - the filespecs typed on the 
command line, you can create an ASCII text file listing a set of 
files you want copied, and then command ZCOPY to use it.

     ZCOPY <FILELIST

will use the text of a file named FILELIST as its command line.  
You must create the indirect file properly for this to work.  
Each line must contain one and only one command line argument.  
For example, if the following text file named WP exists on the 
default drive and user -

B0:WS*.*
SPELL.*
1:CHECK.COM

The command line

     ZCOPY <WP

will do the same thing as

     ZCOPY B0:WS*.* SPELL.* 1:CHECK.COM

Arguments in the file are ADDED to whatever else you type on the 
command line, so

     ZCOPY C1:TEXT.FIL <WP A1: [Q

works just fine.  Notice that you can have a list of source 
files and copy it to different destinations by adding the 
desination specifier on the command line.  The indirect file in 
the above example must be on the default drive and user, but it 
can be located anywhere as long as you give the proper du: spec.  
For example:

     ZCOPY <C15:WP

will look for the indirect file WP on C15:

Be careful not to put any SPACES after a filespec on a line in 
the indirect file, or it will be an invalid filespec.  Lower case 
letters are converted to uppercase automatically.

As a special usage of input redirection, try

     ZCOPY <CON:

You will be prompted to enter a column of filespecs, just as if 
it were coming from an indirect file.  You must type control-Z 
alone on the last line to terminate input and begin copying.

Copy Buffer

ZCOPY takes all the available memory for its IO buffer, and tells 
you how big the buffer is.  Buffer size will vary depending on 
how big your TPA is, the number of filespecs handed to ZCOPY, and 
on whether you have an RSX (for example, EX.COM) in place.  ZCOPY 
causes a warm boot on leaving to recover the CCP, which is 
overwritten to gain the maximum buffer.  (ZERA returns to the 
CCP.)  With its large buffer ZCOPY works faster than many other 
copy programs.

Aborting ZCOPY or ZERA

If you type control-C during a multiple file copy or erase 
operation, you will see

     Abort? (Y/N)

If you type 'Y' you will immediately abort all operations and 
return to CP/M.  If you want to continue with just the current 
file and then abort, you should answer 'N' (or anything but 'Y'), 
and then type ESC.  The next operation will Query you, and then 
you can type ^C.

Patching ZCOPY.COM and ZERA.COM (for the intrepid user)

There are four locations in the first sector of each file which 
may be patched using DDT, EDFILE, etc.  (The following locations 
are shown as displayed by DDT or EDFILE.  The actual locations in 
the .COM file are 0100H less.)

     0155H     00H entry Query mode:  00 for no, 01 for yes.
     0157H     50H ('P') maximum drive letter, ASCII upper case.
     0159H     0FH (15)  maximum user number.
     015BH     64H (100) maximum number of files per filespec.
     015CH     00 - high order byte for maximum number of files.

Locations in ZERA.COM are

     0133H     00H entry Query mode:  00 for no, 01 for yes.
     0135H     50H ('P') maximum drive letter, ASCII upper case.
     0137H     0FH (15)  maximum user number.
     0139H     FFH (255) maximum number of files per filespec.
     013AH     00 - high order byte for maximum number of files.

Maximum drive is the highest drive letter that will be accepted 
as valid in a filespec.  Maximum user number is similar, but also 
sets the highest user number that will be searched if a wild user 
spec, for example, A*:*.COM is given.  You may want to lower 
the maximum user to speed up wild user searches, since the search 
starts at user zero and goes up to and includes the maximum.  The 
highest allowable maximum user is 31.

Maximum files per filespec

There is a preset limit on the number of files that can be 
operated on with one ambiguous filespec, and you can change this 
number.  I picked 100 for ZCOPY for optimization reasons.  This 
is not a limit on the number of files copied with any one 
command, since two or more ambiguous specs can be given, each 
matching up to the maximum number of files.  If an ambiguous 
filespec does match more than the maximum number of files, a 
message will say so, and the maximum number of files will be 
copied.

For ZCOPY the maximum number of files that can be matched by a 
given file spec is a tradeoff of memory buffer size for the 
number of files that can match.  Set it to the mimimum number of 
files you expect to want to copy with one ambiguous spec.  If you 
have only floppies, set it to the maximum number of directory 
entries per floppy.  For a hard drive, set it to the maximum you 
want to copy at once.  But remember that higher settings reduce 
the size of the buffer.

There is virtually no limit on the number of filespecs that can 
be read in from an indirect file (each takes 17 bytes of memory). 
The limit here, set by maximum files, is on the number of actual 
files that can match any one of those ambiguous filespec.

For ZERA the maximum number of files can be set to any reasonable 
value you want.  It is initially set at 255, but can be made 
higher by using the next byte which is the high order byte.