















                                MRBackup Version 2.1
           
                             A Hard Disk Backup Utility

                                       for the

                                  Commodore Amiga 

                                   1 February 1988
           
                                   Mark R. Rinfret

^L






          Introduction

               This   document   describes   a   program,   named  MRBackup
          (pronounced M R Backup, not Mister  Backup :-),  which will allow
          you to  backup the  files on  an Amiga  hard disk drive to floppy
          disk media. I wrote MRBackup primarily out of my own need. I also
          saw it  as a means for learning more about programming the Amiga.
          Please take the time to read  this document  carefully. There are
          some fine  points ("Now  THOSE are  some fine points!") about the
          program that you won't want to miss.

               MRBackup is reasonably flexible,  allowing  you  to  back up
          individual directories,  directory trees or a whole disk. You can
          backup from  one  directory  hierarchy  and  restore  to another.
          Incremental backups  can be  performed based on file modification
          dates. MRBackup also uses, at your discretion, the  "archive bit"
          feature added  with release  1.2 of  the WorkBench. Just for fun,
          MRBackup also talks.  Though  this  is  may  seem  frivolous, the
          speech capability  provides a  method for alerting you that a new
          output disk is required for formatting.

               MRBackup is not fast. When choosing a method for packing the
          backup  data,   a  fast-scan  approach  with  specialized  backup
          directory structure was considered. However, there is an inherent
          danger in  committing multiple files to a specialized file system
          which can only be accessed through a solitary  piece of software.
          I decided  to maintain  the AmigaDOS  file system structure which
          has a great deal of integrity and allows  the backup  media to be
          accessed by  standard software. When I do it again, I'll probably
          go with the specialized approach - the current method is just too
          darned slow.

               The  user  should  take  a serious and organized approach to
          his/her backup methods, however.  I highly  recommend that backup
          listings be  kept in  a safe  place (I  use a  3-ring binder) and
          backup floppies be stored  safe  from  magnetic  damage  or other
          hazards  (like   spilled  coffee  -  argh!).  A  truly  committed
          individual will backup his entire disk once a month, once  a week
          and "areas of interest" once a day (default). 

               MRBackup  attempts  to  economize  on  output media usage by
          using Lempel-Ziv data compression/decompression  (at the  cost of
          time). This   is an option which can be enabled/disabled via menu
          selection. The compression routine used was lifted from  the Un*x
          "compress" program  but has  been adapted to employ buffering and
          native AmigaDOS I/O. 


          Operation

               To use MRBackup, click on the program icon  or type MRBackup
          at the CLI prompt. A new window will open in which you will see a
^L




          STOP sign,  some  other  gadgetry,    and  a  couple  of embedded
          windows. If  you click  with the right mouse button and drag from
          left to right across the menu bar, you'll see the various program
          menus which control MRBackup's operation.


          Pathname Specifications Window

               The  Pathname   Specifications  window  is  where  you  tell
          MRBackup where data is coming from and going to. It  is important
          to note that the meanings of "Home Path" and "Backup Path" remain
          the same for a backup or a restore operation. That  is, the "Home
          Path" always refers to the files' normal "home" and "Backup Path"
          always refers to the location where the copies are kept. 

               The "Listing Path" refers to the  destination of  a detailed
          listing of  the contents  of the  backup floppies and may specify
          the printer (PRT:, default) or  a  file  on  the  hard  disk. The
          listing is  an option  which may  be enabled/disabled via a Flags
          menu selection. 

               The "Exclude Path", if specified,  is  the  name  of  a file
          which contains  lines describing files which should not be backed
          up. Any filename matching an entry in this list will  be excluded
          from   the   backup.   The   exclude   file   consists   of  file
          specifications, one per line, or comments  (a line  with a number
          sign   - #  - in  column 1).  Blank lines  are ignored. Also, the
          specifications  are  case-insensitive.  That   is,  "SYSTEM"  and
          "system" are equivalent. Examples:

          # Exclude all object files
          *.o
          # Exclude all files beginning with "System":
          system*
          # Exclude all ".info" files:
          *.info
          # Exclude the "include" directory and all subdirectories:
          include

               You can  customize the operation of MRBackup through the use
          of   an   initialization   file.   This   file   must   be  named
          S:MRBackup.init. With  it, you  may set your desired defaults and
          Flags. Each line in the file  consists of  an option  setting, of
          the form:

          OPTION = VALUE

          or  a  comment.  Comment  lines  begin  with a number sign (#). A
          sample initialization file is included which  illustrates the use
          of all possible parameter settings.

          The following  example is  from a working MRBackup initialization
          file:

^L




          # The home path is the name of the hard disk.
          home =          DH0:
          # The backup path is the external floppy disk.
          backup =        DF1:
          # Send the listing to a file on the hard disk.
          # The default is PRT:
          list =          S:MRBackup.list
          # Give the name of the file containing exclusion specifications.
          exclude =       S:MRBackup.xcld
          # Employ file compression / decompression.
          compression =   YES
          # Disable the listing capability.
          listing =       NO
          # Let MRBackup talk to me.
          speech =        YES
          # Format each floppy targetted for output.
          format =        YES
          # Do special processing for "big files".
          bigfiles =      YES
          # Provide special handling of the "archive bit".
          archivebits =   YES


          Backing Up a Disk

               To back up your hard disk, or a section of it, first  get an
          indication of  the size  of the  area with the Info command, "ls"
          (if you have it), List, etc. If you multiply the  total number of
          bytes (blocks  * 512)  by 0.65, then divide by 800000, you should
          get a very rough estimate (probably high) of the number of floppy
            disks required  to back up that area. The floppies selected for
          backup need not be preformatted, as MRBackup will  format them as
          needed. You should be sure, however, that no valuable data exists
          on them since it will be destroyed by the formatting  process, if
          formatting is enabled.

               Once your floppies are ready and stacked neatly within reach
          (get some  labels and  your favorite  marker pen,  too!), the fun
          begins.  First,  modify  the pathname specifications according to
          your requirements. Normally, the "Home Path" would be  the device
          name of your hard disk or a directory on it (e.g. DH0:) while the
          "Backup Path" would specify the  device  name  of    one  of your
          floppy  drives  (e.g.  DF0:).  While earlier versions of MRBackup
          were pretty rigid in this regard, this version will allow  you to
          specify ANY  disk device  name in either specification. PLEASE BE
          CAREFUL!  Many users asked for  this increased  flexibility. Just
          be aware  that it  carries with it an increased risk that you now
          have more "opportunity" to  burn yourself  with improper pathname
          specifications.

               Finally, the  listing path  may be set to the printer device
          (PRT:) or to the name of a file on a hard drive  or any available
          floppy drive  not being used by the backup. The listing path will
^L




          be ignored if you disable  the  Generate  Listing  option  in the
          Flags menu.

               Make sure that you have set the desired options in the Flags
          menu, then select Backup  from  the  Project  menu.  You  will be
          prompted  with  a  date  requester.  The  default date value that
          appears is one day earlier than  the  current  date.  If  that is
          satisfactory, simply  depress the  RETURN key and the backup will
          commence. If you desire to change the date,  edit the  date value
          as necessary, using the standard Amiga conventions. Remember that
          to clear the gadget you  may  press  right-Amiga-x.  A  null date
          value  (all  blanks)  is  allowed,  should you want to backup all
          files in the home path, regardless  of their  creation dates. The
          minimum  date  value  handled  by this date requester is 03/01/84
          (though AmigaDOS supports dates  back to  01/01/78). The required
          date and  time format  is MM/DD/YY  HH:MM:SS (24 hour clock), the
          time specification being optional.  You  will  notice  upward and
          downward pointing "arrows" above each date component. Clicking on
          the appropriate arrow will increment or  decrement the respective
          portion of the date. Though the values normally will wrap around,
          not affecting adjacent date  components, certain  situations will
          arise  where  incrementing  a  day  value  may cause the month to
          increment (incrementing February 28 in a non-leap-year will yield
          March 31).

               Once  the   date  has  been  entered,  the  rest  is  fairly
          automatic. You will be  prompted immediately  for a  floppy disk.
          Insert it  into the floppy drive that you specified in the backup
          path and the disk requester will be satisfied. Should you want to
          abort, simply  hit the  CANCEL gadget in the requester. Also, you
          may abort the backup process at  any  time  by  hitting  the STOP
          gadget which  appears in  the top  left area  of the screen. This
          gadget is checked prior to  each  block  write  operation,  so be
          patient if  it does  not respond immediately. Use the STOP gadget
          with caution - it really lives up to its name!

               As each floppy disk is filled, you should promptly label it.
          If formatting is enabled, MRBackup automatically generates volume
          names of the form:

               Backup MM-DD-YY.<sequence number>

          Also to be noted is the fact that the files  on the  backup media
          retain the  creation/modification date,  comments (FileNotes) and
          protection bits of their counterparts on the home device.

               You will  find  that  the  Amiga's  multitasking environment
          shines when  using this program. For those long-haul backups, get
          everything started, then shove MRBackup's screen to the  back and
          go start  something useful.  MRBackup will  carry on without your
          watchful eye. When it needs a disk, the  disk requester  will pop
          out in  front of  everything and  MRBackup will ask (out loud, if
          speech is enabled ) for another disk. Having something else to do
          will make the time pass faster.
^L






          Restoring the Backups

               No, this  isn't always  the bad part. Backup and restore can
          also be useful when  your hard  disk is  crowded and  you have to
          "juggle" data  around. The  restoration process is quite similar,
          mechanically, to the backup  process  -  it's  just  reversed. In
          addition, the meanings of the pathname specifications are altered
          somewhat. The  "Home  path"  describes  the  destination  for the
          restored files  and, as  with the backup process, may specify the
          hard drive only or a directory  specification. The  "Backup path"
          describes  the  file  or  files  to  be  restored and thus may be
          defined down to the file level (1 file).

               Note that on a restore operation, the file  creation date of
          the backup  file is  compared to its matching file (if it exists)
          on the home device. If the file on the home device is  newer, the
          file will  not be  replaced. If  this is desired, the file on the
          home device must  be  deleted  first.  A  later  version  of this
          program  will  probably  offer  a  "force" or "force with prompt"
          option. 


          Menus

               This section  provides  a  brief  description  of MRBackup's
          menus and their items.

          Operations Menu

               The  Operations  Menu  provides  access  to MRBackup's major
          processing functions. They are:

               About
                    This  item  gives  a  quick  description  of MRBackup's
               features and lists my address and phone numbers.

               Backup
                    This  command  begins  the  backup  process. You should
               first be sure that  all  Pathname  Specifications  and Flags
               menu settings are correct.

               Resume Backup
                    This  command  allows  you  to backup your hard disk in
               stages or recover from  an  interruption,  such  as  a power
               failure.  Prior  to  "starting" each backup floppy, MRBackup
               writes information about its  current  internal  state  to a
               file named  S:MRBackup.context. The  first line of this file
               is the disk sequence number (1..n).  The second  line is the
               name  of  the  first  file  to be written to the floppy. The
               third line is the backup "delta date". Subsequent  lines are
               the names  of files  and directories in MRBackup's top-level
               file list. As long as the  file specified  in line  2 can be
^L




               found, MRBackup  should be  able to resume your backup, even
               if changes  have  occurred  since  the  original  backup was
               interrupted. You  may even edit the context file for special
               situations where  you  wish  to  backup  a  disjoint  set of
               directories.

               Restore
                    Restore  allows   you  to  recover  files  from  backup
               floppies previously created with the Backup or Resume Backup
               commands. MRBackup  will prompt you for floppy disks as they
               are needed. Note  that  there  is  no  prescribed  order for
               restoring floppy disks.

               Load Preferences
                    This  command  reads  your  Pathname Specifications and
               Flag menu  settings from  a file  named S:MRBackup.init. You
               would  typically  use  this  command  to  restore MRBackup's
               settings to your startup settings.

               Save Preferences
                    This command writes the current Pathname Specifications
               and  Flag  menu  settings  to the file S:MRBackup.init. This
               allows you to  establish  MRBackup's  default initialization
               parameters.

               Quit
                    Alas - all good things must come to an end. As much fun
               as MRBackup is to use, you'll probably want  to put  it away
               once in a while.


          Flags Menu

                    The  Flags  menu  allows  you  to  set or clear certain
               operating  parameters  (flags)  which  constrain  MRBackup's
               operation.  A  flag  is  considered  "set"  if  there  is  a
               checkmark to the left of its  name in  the Flags  menu. Each
               time the  item is selected it will toggle to the opposite of
               its current state.

               Compress Files
                    This option,  when set,  allows files  to be compressed
               during   backup   and   decompressed  when  restoring.  File
               compression can  typically  save  from  35%  to  60%  of the
               original file  size. Though  this is more costly in terms of
               time, fewer floppies will be required to perform a backup.

               Do Big Files
                    Big files  are files  whose size  exceeds the formatted
               capacity  of  a  floppy  diskette (1756 blocks). In order to
               backup big files, MRBackup must  split  them  across  two or
               more  diskettes.  In  order  to  accomplish  this, a special
               information  file,  MRBackup.bigfile,  is  written  to  each
               backup  diskette   containing  a  big  file.  MRBackup  also
^L




               requires another flag,  Format  Destination,  to  be  set in
               order  for  big  file  backup  to  be  attempted.  If  these
               conditions are not met, MRBackup will  simply skip  over the
               big file, reporting the event.

               Generate Listing
                    This  option  causes  MRBackup  to list the contents of
               each backup diskette (created by the Backup command)  to the
               file or device specified by the Listing Path in the Pathname
               Specifications window.

               Speak
                    Setting the Speak flag allows MRBackup to talk  to you.
               This  is  especially  useful  when doing backups. When a new
               floppy disk is required, MRBackup  will  call  you  for help
               (it's  a  pity  the  Amiga  doesn't  have a diskette jukebox
               feature).

               Format Destination
                    This flag is normally set and tells MRBackup  to format
               each floppy  used for backup purposes. However, you may wish
               to disable this feature for special backups which you prefer
               to "refresh"  by writing over previous versions of backed up
               files.

               Use Archive Bits
                    A new feature, added with release 1.2 of the WorkBench,
               is an  archive bit  in each file's protection word. This bit
               is cleared whenever a  file is  modified and  can be  set by
               MRBackup  when  a  file  is  backed  up. When this option is
               enabled, files for which the archive bit is set will  not be
               backed up.  This gives you a very accurate method for backup
               selection  if  you're  careful  with  your  backup  diskette
               library.


          Windows Menu
               The Windows menu allows you to reactivate windows which have
          been closed. Currently, the only window supported in  this manner
          is the  Pathname Specification  window, which  you may close once
          all pathname specifications have been made.


          Warranties and Support

               There are no warranties,  either expressed  or implied, with
          regard to  the use  of this  program. You  didn't pay for it (did
          you?), so how's you gonna' get  you money  back (sic,  sic, sic)?
          Seriously, folk,  I've tested  this beastie  pretty thoroughly (I
          USE it!), but you know how things go. There may  be a  bugaboo or
          two lurking  about. Please exercise it a little before committing
          your life (your precious data) to its care.

^L




               As for support, I will do my best to respond  to bug reports
          for as  long as I have an Amiga in working condition. I will only
          support the most recent  version,  so  please  know  your version
          number if  you call. I am a fairly trusting sort, so if your need
          is urgent and I have a spare floppy, I'll probably  respond right
          away and assume you'll return my floppy and a couple of stamps in
          equally prompt fashion.

               Several people have suggested that I should have made this a
          shareware product,  if not a commercial one. I don't really think
          that shareware works, and it really was not my intention  to make
          money with  this program.  I can see in retrospect, however, that
          there was a need for such a utility and that  with a  little more
          work (OK,  a lot  of work!),  I could  probably have  had a minor
          financial success. However,  by  my  standards,  that  would have
          required a  lot more  effort and commitment than I had to give at
          the time. Your calls and letters  have been  extremely gratifying
          and all  the incentive  I've needed to continue to steal a couple
          hours here and there to continue making improvements.  (If anyone
          wants to  talk a deal for some reasonably priced custom software,
          I'm all ears.)


          Permissions

               This program is contributed to the public domain, as a token
          of  gratitude  for  the  many  wonderful programs I have received
          through the same channels. Feel free  to enhance,  destroy, sell,
          distribute  or  otherwise  benefit  from  the  legal  use of this
          program. I would love to hear from those of you who find MRBackup
          either useful  or useless (with specific criticisms in the latter
          case). If you make  any enhancements  (there's room  for PLENTY),
          please share  them with  me and  the rest  of the world. I can be
          reached as:

               mrr@amanpt1.ZONE1.COM
               ...rayssd!galaxia!amanpt1!mrr

               or

               Mark R. Rinfret
               348 Indian Avenue
               Portsmouth, RI 02871
               401-846-7639 (home)
               401-849-8900 (work)


          Changes

               This section lists changes, in reverse  chronological order,
          as they  have appeared in subsequent releases of MRBackup. I have
          attempted to be thorough, but may have missed a few key items.

          Version 2.1
^L





               Added the "archive bits" capability.

               Fixed  an  error  in  the  file  exclusion  list  processing
          algorithm.  While   this  problem  seems  to  have  drawn  little
          attention, the  previous algorithm  did not  properly handle file
          specifications involving nested directory components.

               File  comments  and  protection  bits now are saved/restored
          along with the file date.

               A new command, Resume Backup, plus  a new  method for saving
          "context" information, has been implemented. 


          Version 2.0

          New User Interface

               MRBackup has  undergone a major facelift. It now has its own
          screen and color palette and newly  designed menus  and gadgetry.
          All  of   this  is  due  to  my  use  of  PowerWindows  2.0  from
          Inovatronics, a very worthwhile tool for Intuition programming.

               You will notice some new gadgetry on the  screen. I've added
          a  "fuel  gauge"  which  indicates  the  "fullness" of the output
          floppy. There's a  new  error  count  gadget  which  tracks total
          errors  encountered  and  a  "Current  Backup Volume Name" gadget
          which keeps  you  informed  as  to  which  disk  you're currently
          archiving to or restoring from.

               The  Pathname  Specifications  window  has a close box which
          will make the window go away.  A new  menu, Windows,  has an item
          Pathnames which will reopen the window for you.

               A  new  command,  Save  Preferences, allows you to save your
          current  pathname  specs  and  flags  to   the  preferences  file
          (S:MRBackup.init). The Flags menu has been totally redone. This 
          menu previously consisted of item pairs (<feature>/No <feature> -
          pretty dumb, I must  admit -  I think  I was  intrigued by mutual
          exclusion  at  the  time).  The  new  Flags menu just consists of
          check-marked  items.  If  an  item  is  checked,  the  feature is
          enabled.


          Improved Error Handling

               This is  usually the  hardest task  in any programming chore
          and  usually  gets  the  least  attention.  Previous  versions of
          MRBackup were no exception. Version 2.0, however, has come a long
          way in this direction, especially in the area  of recoverability.
          A new requester has been introduced which lists your recovery (or
          abort) options  when  certain  errors  have  been  detected. Most
          significantly, new  context-saving code has been added which will
^L




          allow you to restart a backup disk from  its beginning,  should a
          non-recoverable  output  error  occur.  Currently,  this  context
          information is saved in memory. I would like to save it to a file
          on the system disk. This, coupled with  
          a new  command (Resume  Backup), would allow recovery even from a
          power failure.


          Increased Flexibility

               Previous versions of MRBackup were fairly  rigid with regard
          to home  and backup  path specifications.  Version 2.0 allows ANY
          disk device to be referenced in either location.  On systems with
          dual floppy disks, you can even backup from floppy to floppy!

               MRBackup now allows you to suppress formatting of the backup
          disk. This allows you  to "freshen"  a previously  created backup
          set. Though  this option  should be used with care, it does speed
          things up and enhances MRBackup's partial backup capability.


          Big File Handling

               This is truly a last-minute item!  I personally don't have a
          file big enough to require this, so I didn't address the problem.
          However, enough users have requested this that I  took a  stab at
          it.  "Big"  files,  according  to  MRBackup,  are files which are
          larger than the formatted capacity of the output media. Iff (sic)
          you enable  the "Do Big Files" and "Format Destination" Flag     
                                           menu items,  MRBackup will split
          big files  across multiple floppy disks. If these options are not
          enabled, MRBackup will just complain that the file is too  big to
          back up and go on.

               Some of  you will  probably think that the method used to do
          this is somewhat kludgy, but it's consistent with  my approach to
          total  AmigaDOS  compatibility.  When  backing  up  a big file, a
          special information file,  MRBackup.bigfile,  is  written  to the
          output disk.  The information  file contains  stuff like the file
          name, the "chunk number" (which piece of the file is this?),  the
          chunk size,  and a  flag which indicates whether this is the last
          chunk. This information  is  used  by  the  restore  operation to
          insure that the file chunks get reassembled in the correct order.

               In order  to test this, I had to write a program to create a
          big file  (slightly larger  than 1  floppy disk),  archive it and
          restore it,  then compare the two files. To do all this, I had to
          first clean house on my 20 MB hard  drive!   The big  file backup
          appears  to  work  OK.  I  think  it could use some more testing,
          however, and would encourage you  to  test  drive  it  before you
          commit to it.


             
