;
                                                  
                            ---  A C O P Y  ---          
                                                  
                                Version 3.2

              An Enhanced ZCPR3-Compatible File Copy Utility
        With Optional Source and Destination Disk Directory Caching

            I ->  Installation       A ->  File Attributes        
            O ->  Overview           D ->  DOS Datestamping       
            S ->  Syntax             F ->  Dest Free Space        
            W ->  Wildcard Use       E ->  Error Flag             
            C ->  Caching            B ->  Backing Up Files 
            / ->  Options            M ->  Modifications    
:I                       
 Installation 
 
The distribution version of ACOPY is supplied with a Z3ENV address of 
0000H, ready for use in ZCPR33+ environments.  ZCPR30 users should install 
ACOPY using their regular installation methods.  

No installation is required for operation in non-ZCPR3 environments.  
However, several locations affecting program operation may be patched as 
described in the file ACOPY.PAT, although the default values should be 
satisfactory for most users.  
:O
 Overview - 1/2 

ACOPY (Attribute COPY) is an enhanced Z80 file copy utility for use with 
CP/M 2.2, CP/M+, or ZCPR3 CCP's running under CP/M 2.2, CP/M+, Z80DOS, 
ZRDOS, ZSDOS/ZDDOS or other extended DOS's.  

ACOPY, originally based on David Jewett, III's PPIP12, was developed as a 
fast, general purpose file copy utility with flexible command line option 
control over many aspects of the copy process, and more specifically to 
help simplify the command line script required to copy groups of files with 
unrelated names to a RAM disk.  It does this by optionally copying only 
those files that have any of the specified filename attributes (the high 
bits of the filename and filetype bytes) F1 through F7 set.  Filename 
attributes may be set using a ZCPR3 utility such as DFA (Display/Define 
File Attributes) or a similar CP/M Public Domain utility such as DA.  See 
'Options' section for info on the rest of ACOPY's command line options.
 Overview - 2/2 

ACOPY automatically supports DOS datestamping when it operates under CP/M+, 
Z80DOS or ZSDOS.  See 'DOS Datestamping' section for more info.

ACOPY is fully ZCPR3 compatible when operating in a ZCPR3 environment, 
accepting both the DU: and DIR: forms and checking the environment for the 
validity of the drive and user specified, whether it is to be operating in 
a quiet environment and the name the program was called by for use in the 
command line HELP message.  ACOPY will operate using the ZCPR3 GO command.  
Errors will cause the ZCPR3 program error flag to be set.  Under ZRDOS,
files in the ZRDOS PUBLIC areas are protected.

In a non-ZCPR3 environment, the information it needs is obtained from internal
locations, which may be patched to suit your system as described in the file
ACOPY.PAT.  ACOPY will not accept the DIR: form when operating in a non-ZCPR3
environment.
:C
 Disk Directory Caching - 1/2 

ACOPY can be configured so that it caches both the source and destination 
disk directories in RAM to speed up the copying process when it runs under 
CP/M 2.2-compatible systems.  Because CP/M+ handles directory operations 
differently, directory caching is automatically turned off when ACOPY runs 
under CP/M+.  ACOPY is distributed with directory caching turned off, but 
may be activated by using ZCNFG or by direct patching.  See ACOPY.PAT for 
more info.

ACOPY adapts the ideas developed by Hal Bower in his SPEEDUP directory 
buffer RSX to cache both source and destination disk directories in RAM.  
All references to source and destination directory entries, up to a maximum 
of 256 entries per directory, are made to the cached RAM copies, 
eliminating the time required to move the disk drive head to the directory 
track, read the required directory record and then move the head back to 
the required disk track each time a directory reference is made.  All 
references to directory entries not in the RAM cache are made to the media 
disk directories as usual.  When the copy process is complete, all changed 
cached source and directory directory records are written back to the 
source and destination disks.  
 Disk Directory Caching - 2/2 

Disk directory caching is most effective with floppy disks, but it is also 
slightly faster with RAM disks and hard disks.  It is not as effective when 
datestamper-type datestamping is being done, as the required accesses to 
the !!!TIME&.DAT file offset much of the time saved on directory accesses.  
If you routinely use datestamper datestamping, caching may not provide much 
advantage.  

While copying using disk directory caching in RAM is faster, the directory 
on the disk is not updated until all copying is completed.  This makes 
copying using directory caching less robust than copying using just the 
media disk directories, and less tolerant of flakey media.  
:S
 Syntax - 1/4 

ACOPY supports the use of both CP/M (destination=source) and MS-DOS (source 
destination) syntax.  The command line syntax is:

     ACOPY [dir:]source [[dir:]dest] [excluded] [/option(s)]
  or ACOPY [[dir:]dest=][dir:]source [excluded] [/option(s)]

Both     
          A0>acopy filename.typ b11: 
      and A0>acopy b11:=filename.typ 

will copy the file FILENAME.TYP from A0 to B11.
 Syntax - 2/4 

When only one filename is given, it's assumed to be the source file, and will
be copied to a destination file of the same name on the logged drive.  For 
example:

          B11:SAMPLE>acopy work:filename.ext

will copy the source file WORK:FILENAME.EXT to a file of the same name on 
B11:SAMPLE.  
 Syntax - 3/4  

You may sometimes wish to copy a group of files specified by a 
filename/attribute mask which also includes some files you don't want 
copied.  You can optionally use up to three filename masks to specify files 
that you wish to exclude from copying, even if they otherwise match the 
source file spec.  If you choose to use them, the exclusion filenames must 
be specified after both the source and destination filenames.  The exclusion 
filenames are filename masks only, and any drive/user specified will be 
ignored.
 Syntax - 4/4  

In situations where you would normally only need to specify the source 
filename and you also wish to specify an exclusion filename, you must 
provide at least a minimum destination file spec such as the destination 
drive, user, or *.*, so that you have specified both source and destination 
filenames in some way.  For example:

     A0:WORK>acopy b:filename.* a: /nes *.doc *.hlp *.ws 

will copy all unarchived files B:FILENAME.*, except for DOC, HLP, or WS 
files, to existing files of the same names on A0:WORK, automatically 
overwriting the existing files and archiving the source files after 
copying.  The excluded filename masks must appear after the source and 
destination filename specs and while they don't have to be placed after 
the options, the sample syntax above may be easier to remember.
:W
 Wildcards - 1/2 

Source, destination and exclusion filenames as well as source and 
destination user numbers may all contain wildcards.  Source and exclusion 
filename wildcards are expanded in the usual way.  ACOPY attempts to 
resolve destination file wildcards by a matching process.  For example:

          A0>acopy file.z80 b:??????10.*

will result in a destination filename of FILE10.Z80.  

Since it is possible that this process may result in the creation of 
duplicate files, ACOPY stores the user, drive and filename of the last file 
copied and compares it to the current destination file.  If they match, 
ACOPY prints a 'Duplicate!' error message, and the current file is skipped.  
If two files with the same names are not copied in sequence, a duplicate 
filename may still be created.  Care should be exercised in using 
destination file wildcards, but if you are careful and aware of the 
limitations of the process, you can do copying and renaming of multiple 
files in one step with minimal typing.
 Wildcards - 2/2 

ACOPY also accepts wildcard source and destination user numbers, primarily 
for hard disk backup purposes.  If you specify a wildcard source user 
number, ACOPY will copy files from all user areas as long as they otherwise 
match the filename/attribute mask.  If a wildcard destination user number 
is also specified, the files will be copied to their original user areas on 
the destination drive.  If a specific destination user number is specified, 
all source files will be copied to the specified destination user area.  

You should be careful about blindly copying files from all source user 
areas to a single destination user area, however.  If files with duplicate 
filenames exist in several of the source user areas, it is possible that 
some or all of them may be invertently overwritten on a single destination 
file of the same name, especially when using the 'O' or 'R' options that 
automatically overwrite existing destination files.  On the other hand, if 
the source directory is sorted, duplicate filenames in different user areas 
will appear in sequential order in the source directory and will trigger 
the 'Duplicate!' message when an attempt is made to copy them to the same 
destination user area.  As previously discussed, only the first such file 
will be copied.
:/
 Options - 1/9 

ACOPY has a number of command line options, which must be preceded by the 
option flag character '/'.  The option letters or numbers may appear in any 
order and may appear anywhere in the command line.  Options may be combined 
in any combination.  They are toggled as they are read, so that an option 
appearing twice will cancel itself.  For example, all of the following 
command lines have the same meaning:

          A0>acopy /12qr source.ext dest.ext excluded.ft
          A0>acopy source.ext dest.ext /1 /r excluded.ft /q /2
          A0>acopy /12 dest.ext=source.ext excluded.ft /rq
          A0>acopy /rq /q source.ext /q dest.ext /21 excluded.ft


Except for the attribute options (1-7), individual options may be disabled 
if you'd rather not have them available.  See ACOPY.PAT for more information.
 Options - 2/9 

The following descriptions of the options reflect the default option 
settings in the distribution version.  You may change the default option 
characters or settings to suit your own needs by patching.  See ACOPY.PAT 
for more information.  The command line HELP screen will automatically 
display the proper selection message for each option based on whether it 
has been set to ON or OFF.
 Options - 3/9  

The default options are:

     1 - 7 options.  Copies only those specified files which also 
          have the selected combination of the F1 through the F7 
          attributes set.  

          Under Z80DOS and ZSDOS, PUBLIC files have the F2 
          attribute set, and you can use the '2' option to select 
          only PUBLIC files for copying.  In this case, the 
          operating system will prevent you from creating more 
          than one PUBLIC file of the same name on a disk.  If 
          you try copying a PUBLIC file to a different user area, 
          ACOPY will tell you that it already exists.  If you try 
          to overwrite the 'existing' file, DOS will prevent 
          it by aborting with a File W/P BDOS error.  
 Options - 4/9  

     N - Copies only non-archived (changed) files.  Under ZRDOS, 
          ZSDOS and other extended DOS's, the 'N' option allows 
          you to limit copying to non-archived files (those files 
          that have been opened or modified since the archive 
          attribute was set).  The destination files are created 
          as non-archived files unless the 'D' option is selected 
          to archive the destination files.

          Under CP/M 2.2, the archive attribute is not reset when 
          a file is updated, so this option is not too useful 
          unless you use a utility program to 'manually' set or 
          reset the archive attribute.  
 Options - 5/9 

     U - Update older destination files when doing datestamping 
          under Z80DOS or ZSDOS.  This option allows you to 
          automatically overwrite and update older destination 
          files by copying only when the source file modification 
          date is newer than the destination file modification 
          date, or if no destination file already exists.  It may 
          also be used with the 'E' option to update only 
          existing files.  Sets 'C' and 'O' options to ON.  When 
          operating under any other DOS or when no clock is 
          found, this option becomes inactive and will not appear 
          in the command line HELP message.  

     A - Copy all (directory AND system) files.  This can be 
          useful if you keep utility files as system files and 
          want to exclude them from being copied when using 
          wildcard filename masks.  May be patched to normally 
          copy only directory files.  ACOPY is distributed with 
          this option disabled, but it may be enabled with ZCNFG 
          or by patching.  
 Options - 6/9 

     E - Copy and automatically overwrite (R/W) files only if 
          destination files of the same name already exist.  Sets 
          the 'O' option  to ON and the 'X' option to OFF.

     X - Automatically skips copying if destination files of the 
          same name already exist.  Normally, you're asked 
          first.  Overridden by the 'E' (Exists), 'O' (Overwrite) 
          or 'R' (R/O) options.

     O - Overwrites R/W destination files of the same name 
          without asking.  Normally, you're asked first.

     R - Overwrites R/O (and R/W) destination files of the same 
          name without asking.  Normally, you're asked first.

     M - Moves files.  Deletes the source files when the copying 
          operation has been successfully completed and displays 
          the status message 'Source Deleted'.
 Options - 7/9  

     Y - Marks destination files as system files.  Normally, 
          destination files are marked as directory files.  

     C - Controls whether the source file datestamps will be 
          copied to the destination file datestamps when 
          operating under Z80DOS or ZSDOS (default is to copy 
          datestamps).  When operating under any other DOS or 
          when no clock is found, this option is inactive and 
          will not appear in the command line HELP message.  

          If datestamps are copied, the destination files will 
          have the same creation and modification dates as the 
          source files.  If datestamp copying is suppressed, 
          destination files will be dated as newly created.
 Options - 8/9 

     D - Sets the archive attributes in the destination files, 
          marking them as archived.  Speeds setting up RAM disks 
          by copying and marking the copies as archived in the 
          same operation.  No message is displayed in the status 
          line.

     S - Sets the archive attributes in the source files after 
          copying, marking them as archived and displays the 
          status message 'Source Archived'.

     V - Toggles CRC verification.  The distribution default is 
          to always verify copies.  
 Options - 9/9 

     Q - Quiet.  Usually used in alias environments, the 'Q' 
          option turns off non-error status messages.  Any 
          information you should know about during the copying 
          process, such as error information, is still displayed.  
          No existing files will be overwritten unless the 'O' or 
          'R' options are also used.  If you attempt to copy a
          file to a disk which doesn't have enough free space
          while in the QUIET mode, ACOPY will cancel QUIET
          operation so that you can view subsequent status
          information.

          When operating in a ZCPR3 environment, the 'Q' option
          state will automatically be set according to the state
          of the ZCPR3 QUIET flag, no matter how the default
          option setting is patched.
:A
 File Attributes 

New destination files will normally have the same filename attributes as
the source files.  If a destination file overwrites an existing file of the
same name, the new file will take on the attributes of the previous file.

Destination files will normally be marked as changed (not archived).  To
help set up RAM disk workspaces and as an aid in some backup schemes, the
'D' option may be used to mark destination files as archived.  Source files
may be archived after the files have been copied by using the 'S' option.
This helps you back up files and mark the source and/or destination files
as archived in one step.  

Destination files are normally set as directory files.  The 'Y' option
allows the option of copying files and setting them as system files in one
step, a useful ability when loading RAM disk workspaces.  See the 'Options'
section for more information.
:D
 DOS Datestamping - 1/2 

When ACOPY operates under CP/M+, Z80DOS or ZSDOS, it takes advantage of the
appropriate extended DOS calls to automatically copy the source file
datestamps, if they exist, to the destination file datestamps so that
destination files have the same creation and modification dates as the
source files.  See 'Options' section for more information.

There is are two datestamping options available under Z80DOS or ZSDOS.
When operating under other DOS's, these options are not active and do not
appear in the command line HELP message.

The 'C' option allows you to suppress datestamp copying so that destination
files are dated as newly created.  The 'U' option allows you to update
existing older files by copying and overwriting only when a destination
file of the same name has an older modification date than the source file
or if no destination file exists.  See 'Options' section for more
information.
 DOS Datestamping - 2/2 

When operating under Z80DOS or ZSDOS, successful datestamp copying is
indicated by displaying '(Dated)' in the copying status message.  No
datestamping message will be displayed when clock support is not present,
when there is a datestamping error, when destination files are stamped as
newly created, or when datestamping is done under CP/M+.
:F
 Destination Disk Free Space - 1/2 

ACOPY checks to make sure that enough free space for the destination file
exists on the destination disk before attempting the copy.  If a file to be
overwritten already exists on the destination disk, its size will be
allowed for and it will not be deleted unless there will be in enough free
space for the new file on the disk after the deletion.  If insufficient
space exists, ACOPY will display a 'Disk too full!' message in the copying
status message, the ZCPR3 program error flag will be set to 7 and the
console bell will be sounded.  

If a wildcard source filename was specified, ACOPY will continue to step
through the list of source files, copying any files that will fit and
giving error messages for each file that won't.  Even if you use the 'O' or
'R' option to specify automatically overwriting existing files, no
destination disk file will be deleted unless doing so will create enough
space to allow copying of the replacement file.  
 Destination Disk Free Space - 2/2 

If you are operating in the QUIET mode and attempt to copy a file to a disk
that doesn't have enough free space,  ACOPY will cancel QUIET operation, as
you will probably be interested in which files were copied and which
weren't.  This will give you the information you need to take appropriate
corrective measures, such as changing disks and repeating the command, or
erasing enough files on the destination disk to create enough free space
for the files you still want to copy.  
:E
 ZCPR3 Program Error Flag 

If the ZCPR3 program error flag exists, ACOPY sets it when an error occurs
during program operation.  For more flexible use by alias and ZEX scripts
using flow control, ACOPY32 follows and extends the convention set by Rick
Charnes by setting the error flag to the following values for the indicated
error conditions: 

     0 = Program operation successful - no errors.
     6 = Some files weren't copied - corresponding destination
          files didn't exist (EXIST option only).
     7 = Some files weren't copied - destination disk was too full.
     8 = Program abort - user abort command.
     9 = Program abort - destination disk directory was full.
  0FFh = Program abort - fatal error.
:B
 Backing Up Files - 1/3 

ACOPY can help you 'pack' a backup disk by checking whether there is space
for each specified file on the destination disk and copying it if there is.
If it finds insufficient space, it sets the ZCPR3 error flag to 7 and
continues through the list of source files testing for files small enough
to fit, and copying those that will.  If you use the 'S' option (archive
source files after copying) to mark as archived those files successfully
copied, you will be able to copy the uncopied (and non-archived) files to
another backup disk using the ACOPY 'N' option (copy only non-archived
files).  An alias or ZEX script can also test the value of the ZCPR3 error
flag and inform you of the nature of the error condition and the need to
insert another disk.
 Backing Up Files - 2/3 

A simple command line for backing up all non-archived files on a disk is:

          A0>acopy m:*.* b: /nos     

which will copy all non-archived files from M0: to B0:, automatically
overwriting destination files of the same name and archiving the source
files after copying.  The ZCPR3 error flag will be set to 7 if any of the
specified source files couldn't be copied because of insufficient space on
the destination disk and will be set to 9 if the destination disk directory
is full.
 Backing Up Files - 3/3 

A variation for hard disk backup using wildcard source and destination user
numbers is:

          A0>acopy m?:*.* b?: /nos     

which will copy all non-archived files from all user areas on drive M: to
the corresponding user areas on drive B:, automatically overwriting
destination files of the same name and archiving the source files after
copying.  

If you are updating existing backup disks, a similar command line that
copies changed files only if files of the same name already exist on the
destination disk and archives the source files after copying is:

          A0>acopy m?:*.* b?: /nes

In this case, the ZCPR3 error flag will be set to 6 if any of the specified
source files don't exist on the destination disk.  Similar aliases may be
written using the datestamping options.
:M
 Modifications 

ACOPY has a number of locations near the beginning of the program that can
be patched using ZP, ZPATCH, DDT, etc, to alter the operation of the
program to suit the user.  ACOPY.PAT may also be renamed, assembled to an
overlay file and overlaid on ACOPY.COM to create a custom copy of
ACOPY.COM.  ZCNFG17.COM and the configuration file ACOPY32.CFG may also be
used to change some of ACOPY.COM's more common user-configurable settings.
See ACOPY.PAT for further information.