* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * A C O P Y * * * * An Enhanced ZCPR3-Compatible * * File Copy Utility * * * * Copyright (c) 1986-91 * * by * * Terry Hazen * * 21460 Bear Creek Road * * Los Gatos, CA 95030 * * * * Voice.......... (408) 354-7188 * * Zee-Machine.... (408) 245-1420 * * Ladera Znode... (213) 670-9465 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Lastest Revision ---------------- Version 3.2 - 01/14/91 See ACOPY32.HIS for revision history. ================================================================= Overview -------- 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 the 'Options' section for information on the rest of ACOPY's command line options. ACOPY automatically supports DOS datestamping when it operates under CP/M+, Z80DOS or ZSDOS. See the 'DOS Datestamping' section for more information. 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. When operating under ZRDOS, files in the ZRDOS PUBLIC areas are protected. When ACOPY operates 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. Disk Directory Caching ---------------------- 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 it may be activated by using ZCNFG or by direct patching. See ACOPY.PAT for more information. 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 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. 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. Syntax ------ 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. When only one filename is given, it 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. Excluding Files --------------- 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 specification. 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. 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 specification 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 specifications and while they don't have to be placed after the options, the sample syntax above may be easier to remember. Wildcards --------- 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. 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. 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. DOS Datestamping ---------------- 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 the '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 the 'Options' section for more information. 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+. Destination Disk Free Space --------------------------- 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. 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. Options ------- 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. Options 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. 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. 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, the DOS will prevent it by aborting with a File W/P BDOS error. 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. 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. 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 are 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 are asked first. R - Overwrites R/O (and R/W) destination files of the same name without asking. Normally, you are asked first. M - Moves files. Deletes the source files when the copying operation has been successfully completed and displays the status message 'Source Deleted'. 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. 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. 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. 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. Backing Up Files ---------------- 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. 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. 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. Optional ACOPY 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. ACOPY in Alias Scripts ---------------------- When a ZCPR3 alias script is used to copy a large number of files with unrelated filenames, the command line may quickly become longer than the command line buffer. F1-F7 filename attribute tagging helps group the files by the desired function, allowing shorter and faster alias scripts. Specifying files to be copied by both filename masks and attributes can be useful, for example, when copying files from a disk containing a large number of software development utilities to a RAM disk. For example, an alias script can be written to copy only those files necessary for Z80 assembly language work, and another script written to copy only those necessary for document editing. The source files may be tagged so that several single copy aliases will copy different subsets of the same group of source files. For example, all Z80 development files might have the F3 attribute set, all the necessary text processing files might have the F4 attribute set, and all desired general utility files might have the F5 attribute set. You can then copy a complete Z80 work utility file set from drive F0: to drive A0:, skipping copying those files where the destination files already exist, mark the destination files as archived, and set them to system files with the script: A0>acopy f:*.* /345dxy A complete Z80 work utility file set, except for .DOC files, may then be similarly copied, archived and set to system with the script: A0>acopy f:*.* a: /345dxy *.doc Acknowledgements ---------------- ACOPY was originally developed to suit my own special needs based on David Jewett, III's well-written and documented PPIP12, a very nice piece of work! PPIP has been further updated by Jay Sage and others to support Z-system and datestamping operation. I refer interested users to the latest version of PPIP for further information. The disk directory buffering used in ACOPY was adapted from the core code of Hal Bower's great SPEEDUP disk directory buffer RSX contained in SPEEDUP.LBR. The operation of SPEEDUP is also described in Hal's LINKPRL article in The Computer Journal, issue #41. The destination disk relogging used beginning with ACOPY30 was adapted from Bridger Mitchell's FRESET fast disk reset code described in his column in The Computer Journal, issue #32. Thanks also to Ian Cottrell for helping to get ACOPY to run properly under CP/M+ and special thanks to all you ACOPY users whose ideas, comments, suggestions, bug reports and testing contributions have been so helpful!