CP/M/CPM_CDROM.iso/mbug/mbug144.arc/ARCOPY21.LBR/ARCOPY.DZC/ARCOPY.DOC

Text File | 1979-12-31 | 19KB | 438 lines

                               ARCOPY.DOC
                               ----------
                      Instructions for ARCOPY.COM
                         Version 2.1 - 3/21/88

                           (c)1988 Eric Meyer


                            1. INTRODUCTION

ARCOPY (ARchive COPY) is a small, fast file copy utility for all Z80 CPM
(2.2 or 3.0) systems.  With ARCOPY you can easily copy files:

  * while changing disks             * selectively (with Yes/No prompts)
  * to/from any CP/M user areas      * only if new (not on destination)
  * to different destination names   * only if already on destination
  * to/from the console and printer  * only if changed since last backup
  * with PIP or MSDOS COPY syntax    * with deletion of original file


                        2. AN ALTERNATIVE TO PIP

Though ARCOPY has several sophisticated options for selective file copy-
ing, it can also simply function as a substitute for PIP. ARCOPY is just
as fast, and quite a bit  smaller,  though  it has all the commonly used
functions of PIP; in fact you can rename it to PIP.COM if you want.  But
note the following extra features:

  *- ARCOPY automatically resets the disks under CP/M 2.2 before copying
     (including between commands, in resident mode). This means that you
     can swap disks as desired without BDOS R/O errors.

  *- Especially when backing up floppy disks, you often have the problem
     that both disks are relatively full.  Despite the fact that the re-
     placement file should fit, PIP  may  run  out of space, as it won't
     erase the existing file until after it's copied the new one. ARCOPY
     doesn't require this extra free space; it always erases  the exist-
     ing file first.  (Use caution -- or PIP -- in situations where this
     could be a problem.)

  *- ARCOPY processes files  in alphabetical order.  This, combined with
     the individual Confirm (Y/N) option, makes it a sort  of mini-SWEEP
     utility.

  *- ARCOPY supports ZCPR-style  user numbers "Duu:" (like B12:GORT.TXT)
     in both arguments.  This is a lot easier than PIP's "[Guu]" option.

  *- ARCOPY can rename groups of files, or copy while renaming:  for ex-
     ample, you can copy *.TXT to *.DOC. It's even clever enough to copy
     *.* to *.BAK, if that will work in a given situation.

  *- ARCOPY accepts the same syntax as PIP; but it can also operate like
     the MS-DOS COPY command (source  then destination, rather than vice
     versa).  One nice result is that if you rename ARCOPY  to COPY.COM,
     you will  be  able to move files around with the same command as on
     MS-DOS: A>COPY SOURCE DEST.  This  will  make life less complicated
     for those who (like me) are finally making the transition to MSDOS.




     Do keep a copy of the "real" PIP.COM around; it's a versatile beast
     and ARCOPY can't quite do everything that PIP  can.  ARCOPY doesn't
     concatenate files,  and  supports  only a subset of PIP options and
     devices (see below).


                          3. SELECTIVE COPYING

     Keeping backup copies of valuable  data is very important; however,
it can often be enough of a pain to discourage you from doing it. (Copy-
ing an entire disk takes a long time; copying just  what  you  think you
might have changed recently is unreliable.)  By automating tedious back-
up tasks,  ARCOPY should encourage you to play it safe.  Situations that
arise when constructing or updating backup disks are:

        The need to copy onto the backup disk ONLY files that do
    NOT already exist  on the backup disk.  (As when you want to
    copy some new files, but don't need to recopy the old ones.)

        The need to copy ONLY files that DO already exist on the
    backup disk.  (As when  other  files are backed up  on other
    disks.)

        The need to systematically rename a whole group of files
    while copying them.

        The need to select just a few assorted files to copy.

     ARCOPY's ability to do all this, along with the choice of appropri-
ate filenames, makes backing up  data  far more convenient, even if your
CP/M system doesn't support an Archive attribute.  If it does,  read on.


                         4. INCREMENTAL BACKUP

     Suppose you have a disk with a number of files on it, a few of them
hving been changed recently.  How  do  you update your backup copy?  You
can always wipe it clean and recopy everything; but it would be  nice if
you could  just  copy  exactly  those  things that need it ("incremental
backup").

     CP/M 3.0 maintains  a  file  attribute  (analogous to Read/Only and
System) called Archive.  Whenever a disk file is  modified,  this attri-
bute is  cleared.  Consequently,  if this attribute was set in the past,
the files which now lack it are those you have created or changed since,
and need to back up  now.  CP/M  3.0  PIP  includes an option "[A" which
uses this attribute to provide incremental backup: it copies  only files
which are not marked as Archived, and then marks them so.




     ARCOPY can do the  same  thing,  even under CP/M 2.2.  However, 2.2
does not, as a rule, properly support the Archive attribute: there is no
guarantee that it will be cleared as it should  be  whenever  a  file is
modified (though  apparently it will not be accidentally cleared if once
set).  Some OS enhancements (eg, ZCPRx) may add full support for the Ar-
chive bit; check your documentation.  Failing  this, it is also possible
to maintain the "A" attribute manually, using a utility  like  my DA.COM
to set  or  remove  it.  In particular, you can set the attribute on all
files to begin with and then  remove  it  from files when they are modi-
fied; then ARCOPY will back up just those files.


                            5. USING ARCOPY

SYNTAX:      A>ARCOPY {sourcefil {destfil} {[options]}     "{}"=optional
        or            {destfil=sourcefil {[options]}}

        If the file arguments are separated by an "=", they will
        be interpreted as PIP would, in  destination, source or-
        der.  If they are only separated by spaces, they will be
        taken in MSDOS COPY order as source, destination.  If NO
        arguments  are given, ARCOPY  will load into  memory and
        give you an interactive  prompt ("-").  You can then en-
        ter one copy command after another.  To exit, just press
        RETURN or ^C.

        Either filespec  may be ambiguous; destination  name de-
        faults to same as source.  In addition, ZCPR-style Drive
        User specifications (Duu:) are supported.  If not speci-
        fied,  drive  and  user  default  to the current values.
        Common device names (eg. CON:) are also  accepted.  "Op-
        tions" must be preceded by "["; separating  spaces and a
        closing "]" are optional. You may select one or more of:

  ** A - ARCHIVE (incremental backup)   N - NEW (NONexisting) files only
   * C - CONFIRM each file copy (Y/N) * R - READ System files too
     D - DELETE original after copy   * W - WRITE over Read/Only files
     E -  EXISTING files only         * Z -  ZERO parity bit

     (* - Options in common with CP/M 2.2 PIP;  ** - CP/M 3.0 PIP only)

     ARCOPY resets disks before attempting to copy files.  For ambiguous
(group) copying, it alphabetically lists  each file being processed; you
may abort at any time by typing ^C.  By DEFAULT all specified files will
be copied from the source to the  destination  disk.  Copies  retain the
same attributes as the original, except Archive which is always cleared.
Files with the SYStem attribute will be ignored.  However:

     If you specify the "A"  option,  only files without the Archive at-
tribute will be copied; and as each is backed up, the original will have
its Archive attribute set.  (See above for further explanation.)

     If you specify "C", along  with  an ambiguous filename, you will be
prompted "y/n?" for each file about to be copied.  Press "Y" to copy the
file, or "N" to skip it.  (If the "A" option is also in force,  the file
will be marked as Archived whether copied or not.)




     If you specify "D", each  source  file  will be deleted after it is
copied, allowing you to simply move files  from  one  place  to another.
NOTE: If  the source and destination directories are the same, ARCOPY is
clever enough to  recognize  this  as  a  request  to  simply RENAME the
file(s).

     If you specify "E", only those files that already EXIST on the des-
tination disk will be  copied.  (Note  that  the DESTINATION name is the
one considered here, rather the source name, if these differ.)

     If you specify "N", only those  files  that are NEW (do NOT already
exist on the destination disk) will  be  copied.  (Note  that  you can't
specify both "E" and "N", as they are mutually exclusive.)

     If you specify "R", SYStem files  will be copied as well; otherwise
they are ignored.

     If you specify "W", Read/Only  files may be overwritten; otherwise,
any attempt to delete them will cause a BDOS R/O error.

     If you specify "Z", ARCOPY will  zero  the high (parity) bit on all
output data.  This can be useful for converting  nonstandard  data (like
WordStar text files) into standard ASCII form.


                           6. ABOUT RENAMING

     If you are copying to a  different  name, ARCOPY will show you both
the original and destination name, eg:  OLDFIL.NAM -> NEWFIL.NAM.

     Copying multiple files  to  different  names can get confusing.  If
the wildcards match exactly (as in *.DOC to *.BAK)  it's straightforward
enough (although PIP can't do it).  But ARCOPY also lets you do stranger
copies, which  may  or  may not work depending on the specific filenames
encountered.  Suppose you have these  three files on drive A:  GORT.TXT,
KLAATU.DOC, NIKTO.  You want to create some extra  backups  on  drive B.
You might type:
                          A>ARCOPY *.* B:*.BAK

Despite the fact that  most  utilities  would  refuse this request, it's
perfectly clear what you want, and ARCOPY will do it:

  GORT.TXT, KLAATU.DOC, NIKTO  --->  B:GORT.BAK, KLAATU.BAK, NIKTO.BAK

     But suppose there had been  a fourth file A:GORT.NOT.  Because both
it and GORT.TXT would get copied  to  the  same  destination B:GORT.BAK,
which is  likely  to be a bad idea, in this case ARCOPY would refuse the
(same!) copy request.  Rather than  give  up in principle, because there
might be trouble, ARCOPY looks ahead at what the actual results of copy-
ing would be.  If no conflict would arise, ARCOPY will do it.  If a file
would overwrite itself, or two files copy to the same destination, or an
illegal filename be constructed, ARCOPY gives an error  message,  and no
files are copied.




     ARCOPY is also a mass renaming  utility.  If you use the "D" option
when the source and destination directories are the same ARCOPY realizes
it doesn't actually have to copy the file(s), but can just  rename them.
All the rules above apply.


                            6. ABOUT DEVICES

     ARCOPY recognizes several  CP/M  "device  names" as substitutes for
filename arguments: CON, CRT, PRN, LST, NUL.  Device names  may  be fol-
lowed by a colon (eg. CON:) or not, as desired.  Devices allow ARCOPY to
transfer data between any combination of the terminal, printer, and disk
files.  Data sent  to/from  any  device  is treated as a stream of bytes
terminated by a ^Z.

        CON: Console.  When used as a source ARCOPY accepts any-
             thing you type in as input; type ^Z to finish. When
             used as a destination, the data will be sent to the
             screen.  This device  expands tabs, filters control
             codes  (eg, "^[" for ESC), and  allows  you to quit
             with ^C or pause output with ^S.

        CRT: Terminal. A more basic console I/O device that does
             not expand tabs, filter output or respond to ^S/^C.
             Useful for setting screen attributes.

        PRN: Printer. Can only be used as a destination.  Output
             will be sent to  the printer, with a formfeed added
             every 60 lines to paginate it.

        LST: List device.  A more  basic  printer  output device
             that does  not add any extra formfeeds.  Useful for
             initialization codes, or files with their own pagi-
             nation.

        NUL: Null.  When used  as a source, this  creates an im-
             mediate EOF (no data).  When used as a destination,
             no output  at all is created.  Useful for  creating
             empty files, or suppressing output  in batch files.


     In most other respects  ARCOPY  handles device input/output just as
PIP does.  One notable exception is that device I/O is  buffered  in the
same way  as disk input, rather than sent a character at a time.  (Other
points:  PIP numbers lines on output to PRN:, and doesn't recognize CRT:
ARCOPY doesn't allow RDR, PUN,  or  AUX;  CP/M never supported these de-
vices well enough for them to be useful anyway.)

     When you use devices you  cannot  use wildcards or the options "A",
"C","D", "E" or "N", which refer to file  copying  only.  (Note:  as the
devices are  reserved  names, you can't refer to disk files named "CON",
etc., unless you do it with wildcards!)




                           7. USAGE EXAMPLES

     Each example shows MS-DOS COPY syntax on the left PIP syntax
     on the right.


A>ARCOPY B:GORT [dw]            or   A>ARCOPY A:=B:GORT [dw]

     The file B:GORT will be copied to drive A: and then deleted
     from drive B: even if it was Read/Only.


A>ARCOPY *.Z80 *.ASM [d]        or   A>ARCOPY *.ASM=*.Z80 [d]

     Every file  A:*.Z80  will get  renamed with an extension of
     .ASM instead.  (ARCOPY  recognizes  that no actual  copying
     has to be done.)


A>ARCOPY *.* *.BAK              or   A>ARCOPY *.BAK=*.*

     If all goes well, a copy of every file  on drive A: will be
     created with a filetype of ".BAK".  However, this might not
     work; ARCOPY  will  refuse  to  do it  if filename problems
     would result.


A0>ARCOPY 1:*.DOC *.TXT [zc]    or   A0>ARCOPY *.TXT=1:*.DOC [zc]

     Each file of type ".DOC" on drive A: user 1  will be copied
     to user 0, with the  same name but type  ".TXT"  instead of
     ".DOC".  In the process, the high bit will be zeroed out to
     convert to standard  ASCII.  You will be  asked  to confirm
     each item to copy individually.


A>ARCOPY *.* B: [ae]            or   A>ARCOPY B:=*.* [ae]

      All files on A: which  require archiving  (see explanation
      above) and which  already  exist  on drive B: will  be ar-
      chived to B:.  (This allows you to archive the contents of
      one directory on more than one floppy disk.)


A>ARCOPY b:*.COM [nr]           or   A>ARCOPY A:=B:*.COM [nr]

      All files  B:*.COM  (including SYStem files)  which do not
      already exist on drive A: will be copied to draive A: from
      drive B:


A>ARCOPY B:GORT.DOC CON [z]     or   A>ARCOPY CON:=B:GORT.DOC [z]

      The file B:GORT.DOC will be typed out on screen, stripping
      off any high bits set.  This is a handy way  to view Word-
      Star documents.




A0>ARCOPY 10:PROG.ASM PRN       or   A0>ARCOPY PRN:=10:PROG.ASM

      The file  A10:PROG.ASM  will be sent  to the printer, with
      pagination.


A>ARCOPY NUL -LETTERS           or   A>ARCOPY -LETTERS=NUL:

      A true empty (0k) file  A:-LETTERS  will be created.  Such
      files are a popular  way to identify  or date  disk direc-
      tories.


A>ARCOPY CON LST                or   A>ARCOPY LST:=CON:

      Anything you type in  will be sent to the printer.  Useful
      for sending setup codes, etc.  Exit with ^Z.  If you abort
      with ^C nothing happens.O)


A>ARCOPY CON CRT                or   A>ARCOPY CRT:=CON:

      Anything you type  in will be sent  back to the screen af-
      terwards, but without  control filtering.  Useful for set-
      ting screen attributes, etc.



                           8. ERROR MESSAGES

These errors indicate that no copying has been done:

    NO FILE     There were no  source  files matching all given criteria
                   (Filename, existence on destination,  archive status)
   <BAD ARGT>   Missing or invalid argument; think (read?) and try again
   <BAD DEV>    Invalid device name or usage (see DEVICES)
   <TOO MANY>   ARCOPY can't process more than 255 files; be more speci-
                   fic.
   <SAME ITEM>  A file destination would  have  been the same as its own
                   source
   <CONFLICT>   Two source files would have  copied to the same destina-
                   tion
   <ILLEGAL>    A file with an illegal  name would have been constructed


These errors can occur in the middle of copying:

   <I/O ERR>    BDOS disk error, probably bad file or full disk
   <ABORTED>    Somebody typed ^C


     If something causes ARCOPY to  terminate  while copying to disk, an
incomplete work file of type ".$$$" may get left behind.

     Please note that ARCOPY does  require  a Z80 CPU or equivalent.  It
will not run on 8080/85 CP/M systems.




                               9. HISTORY

     ARCOPY v1.0 (1986) was the  first  release of this program, chiefly
intended to provide incremental backup for CP/M 2.2 users. However, this
often didn't work properly under CP/M 2.2 systems, so...

     ARCOPY v2.0 (1988)  added  many  improvements including MSDOS COPY-
like syntax, alphabetization, user number support, and the  "E"  and "N"
options to enhance the choices for selective backup.

            v2.1 (3/88) - copies to/from devices; allows renaming during
ambiguous copying; adds "D"elete option; fixes display column bug.


     ARCOPY and its documentation  are  (c)1988  E.Meyer, all rights re-
served.  They may be freely distributed, but not  modified  or  sold for
profit without  my  written consent.  The user takes full responsibility
for any damages resulting  from  the  use  (or  misuse) of this program.
Please report any problems encountered.

                               Eric Meyer
                          427 N. Washington #4
                         Bloomington, IN  47401
                        CompuServe [74415,1305]

--------------------------------- end ----------------------------------