home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d6xx / d652 / burf.lha / Burf / Burf.Doc < prev    next >
Text File  |  1992-05-14  |  12KB  |  260 lines
  1.                                  BURF
  2.                                  ----
  3.  
  4.                      Version 1.00  -  April 1992
  5.  
  6.                    Copyright © Michael Tanzer 1992
  7.  
  8. +---------------------------------------------------------------------------+
  9. |                             N O T I C E                                   |
  10. |                                                                           |
  11. | Freely distributable.  Not to be used for commercial purposes without     |
  12. | written consent from the author.  Not to be distributed without this      |
  13. | notice and accompanying components intact.                                |
  14. |                                                                           |
  15. | This product is distributed on an 'as-is' basis, with no warranty of any  |
  16. | kind, either express or implied.  No responsibility whatsoever is assumed |
  17. | by the author for the use of this product, nor for any results of its     |
  18. | use.  No claim whatsoever is made as to this product's accuracy, useful-  |
  19. | ness, completeness, nor suitability to any purpose.                       |
  20. |                                                                           |
  21. | Components include the following files:                                   |
  22. |   Burf                                                                    |
  23. |   Burf.Doc (this document)                                                |
  24. |   Burf.Doc.info                                                           |
  25. |   Install_Burf                                                            |
  26. |   Install_Burf.info                                                       |
  27. |                                                                           |
  28. +---------------------------------------------------------------------------+
  29.  
  30. Syntax:
  31. -------
  32.  
  33. The symbols '<' and '>' are used in this document to enclose optional
  34. parameters, i.e. those that may be but need not be specified.  Strings that
  35. must be specified verbatim are shown in upper case; parameters are shown in
  36. lower case.  For example, the line:
  37.     RX BURF source <target>
  38. indicates that 'RX BURF' must be entered as shown (although not necessarily
  39. in upper case), 'source' is a required parameter, and 'target' is an
  40. optional parameter.
  41.  
  42.  
  43. What is Burf?
  44. -------------
  45.  
  46. Burf is a BackUp ReFresher written in Rexx.  It can refresh a backup copy of
  47. a directory by copying only those files that have been added or modified
  48. since the last backup.
  49.  
  50.  
  51. Why use Burf?
  52. -------------
  53.  
  54. Burf is useful for those times when you want to keep a backup of a directory
  55. but don't want to run a complete backup of your system every time that
  56. directory is changed.  For example, you might keep a number of important
  57. documents in a directory on your hard disk and back them up to floppy
  58. fairly frequently, although you run a complete backup of your hard disk only
  59. once in a while.  Frequent incremental backups take up lots of diskettes,
  60. and it takes too long to copy the entire directory or to search through it
  61. trying to remember which files you changed.
  62.  
  63. Burf addresses this situation by copying only those files that are new or
  64. that have been modified since the last backup.  It can determine which files
  65. have been modified either by comparing the dates of files in the source
  66. directory with those in the target directory, or by checking the archive
  67. flags in the source directory.  It will check all subdirectories within
  68. the source directory, duplicating them in the target directory if necessary.
  69.  
  70. Burf can also delete any subdirectory or file that is found in the target
  71. directory but not in the source directory.  This will ensure that your
  72. backup will not contain any subdirectories or files that you no longer use;
  73. it also ensures that there will be only one copy of any subdirectory or file
  74. that has been renamed since the last backup.  If this option is chosen, Burf
  75. will also make sure that subdirectory names and file names in the target
  76. directory exactly match those in the source directory.  That is, if a
  77. subdirectory or file in the source directory has already been copied to the
  78. target directory but has since been renamed by capitalising letters in its
  79. name, the copy will be similarly renamed.  This ensures that the contents
  80. of the target directory will exactly match the contents of the source
  81. directory.
  82.  
  83. Burf can run asynchronously, so you can run it without tying up a CLI.
  84.  
  85. The result is that you can keep an up-to-date backup of any directory with
  86. a minimum of effort.
  87.  
  88. Best of all, Burf is written in Rexx, so if you want to add or change a
  89. feature, you can do it easily.  And it's free.
  90.  
  91.  
  92. What you need in order to use Burf:
  93. -----------------------------------
  94.  
  95. You must have the following libraries in your LIBS: directory:
  96.   rexxsyslib.library    (version 36.17 or later)
  97.   rexxsupport.library   (version 34.9 or later)
  98. These are available from a variety of sources and are not distributed with
  99. Burf.
  100.  
  101.  
  102. How to customise Burf:
  103. ----------------------
  104.  
  105. Copy Burf to your REXX: directory.  (You can run 'Install_Burf' to do this.)
  106. Edit Burf and check the settings of the variables 'flagsw', 'clonesw',
  107. 'ressw', 'asynchsw' and 'log'.
  108.  
  109. If you want Burf to check archive flags to determine whether a file should
  110. be copied, set 'flagsw' to 1 (the archive flags will be set as each file is
  111. copied); if you want Burf to compare file dates, replacing files in the
  112. target directory with those in the source directory if those in the source
  113. directory are more recent, set 'flagsw' to 0 (the archive flags will remain
  114. unchanged).
  115.  
  116. If you want Burf to delete disused subdirectories and files from the target
  117. directory, set 'clonesw' to 1.  This will also cause Burf to make sure that
  118. the names of subdirectories and files already in the target directory
  119. exactly match those in the source directory.  This option can be dangerous
  120. (e.g. if Workbench: is the current directory and no target is specified,
  121. you could wipe out your system), so Burf will prompt you to make sure you
  122. want to continue if 'clonesw' is set to 1.
  123.  
  124. If you want Burf to make the COPY and PROTECT commands storage-resident,
  125. set 'ressw' to 1.  The commands will be removed from storage when Burf is
  126. finished.
  127.  
  128. If you want Burf to run asynchronously (especially useful when backing up
  129. large directories) set 'asynchsw' to 1.  This enables Burf to run without
  130. tying up a CLI.  If this option is chosen, Burf will inform you when it has
  131. finished via the SAY command in the Utilities directory.  It will also use
  132. this method to tell you if its operation is aborted due to a fatal error.
  133. If this occurs, the last line of the log will indicate the action that
  134. caused the error.
  135.  
  136. Burf writes a log of its activities.  It will also show a number of counters
  137. indicating the number of directories checked, made, renamed and deleted,
  138. the number of files checked, replaced, added, renamed and deleted, and the
  139. number of non-fatal errors that occurred during the backup.  Any message in
  140. the log indicating a non-fatal error begins with an exclamation point (!).
  141. Set 'log' to indicate the output stream for the Burf log.  If you choose
  142. to have the log typed at the console, set this variable to '*'; if you
  143. prefer the log to be written to a file, specify the file name (e.g.
  144. 'RAM:BurfLog'.  You may not specify '*' if 'asynchsw' is set to 1 because
  145. Burf has no console when running asynchronously.
  146.  
  147.  
  148. How to run Burf:
  149. ----------------
  150.  
  151. To run Burf from the CLI, enter:
  152.     RX BURF source <target>
  153. where 'source' and 'target' indicate the source and target directories.  If
  154. no target directory is specified, the current directory will be used.
  155.  
  156. For example, if you have a directory on your hard drive (DH0:) called
  157. 'Documents' and you want to keep an up-to-date copy on a diskette which you
  158. have placed in floppy drive DF0: you could enter:
  159.   RX BURF DH0:DOCUMENTS DF0:
  160. You could also enter:
  161.   CD DF0:
  162.   RX BURF DH0:DOCUMENTS
  163.  
  164. If your directory contains a subdirectory that you do not want to be backed
  165. up, it is simple matter to write a Rexx program that invokes Burf to back up
  166. the remaining subdirectories explicitly.  If, for example, your 'Documents'
  167. directory contains three subdirectories ('Letters', 'Memos' and 'Faxes') and
  168. you want only two of them ('Letters' and 'Faxes') to be backed up, you could
  169. use the following program once DF0:Documents has been created:
  170.     /* BurfDocs */
  171.     Burf 'DH0:Documents/Letters DF0:Documents/Letters'
  172.     Burf 'DH0:Documents/Faxes DF0:Documents/Faxes'
  173.  
  174. Note that Burf will create the target directory if it does not exist, but
  175. will not create a directory to contain it.  For example, if you specify
  176. 'DF0:Documents/Faxes' as a target and 'DF0:Documents' does not exist, Burf
  177. will not attempt to create it.
  178.  
  179. If you have the good fortune to be using DirWork 1.51 (by Chris Hames), you
  180. can invoke Burf by setting a button to:
  181.   'Burf ,uDP----drx Burf'        (without the quotes)
  182. Display the contents of the target directory in one file list and the
  183. contents of the device (or directory) containing the source directory in the
  184. other; select the source directory, then click on the Burf button.  The
  185. Command requester allows you to specify a different target directory.  If
  186. no target directory is specified, the 'd' special option causes the directory
  187. displayed in the other list to become current when Burf is executed.
  188.  
  189. WARNING: DO NOT SPECIFY A TARGET DIRECTORY THAT IS CONTAINED WITHIN THE
  190.          SOURCE DIRECTORY.  THIS WOULD RESULT IN A LOOP THAT WOULD RUN
  191.          UNTIL THE CAPACITY OF THE DEVICE CONTAINING THE DIRECTORIES IS
  192.          EXHAUSTED.
  193.  
  194.  
  195. Explanation of non-fatal error messages:
  196. ----------------------------------------
  197.  
  198. ! Rename failed.
  199.     An attempt to rename a subdirectory or file in the target directory
  200.     failed.  The device containing the target directory may have Read Only
  201.     status.  Write-enable the device and re-run Burf.
  202.  
  203. ! Delete failed.
  204.     An attempt to delete a subdirectory or file in the target directory
  205.     failed.  The device containing the target directory may have Read Only
  206.     status or the object may be unerasable.  Write-enable the device or use
  207.     the PROTECT command to remove the 'u' flag and re-run Burf.
  208.  
  209. ! File found: (file name)
  210.    A file in the target directory was found to have the same name as a
  211.    subdirectory in the source directory.  If 'clonesw' is set to 1, the
  212.    file may have been deleted (check the log).  Otherwise delete the file
  213.    before re-running Burf.
  214.  
  215. ! Directory found: (subdirectory name)
  216.    A subdirectory in the target directory was found to have the same name
  217.    as a file in the source directory.  If 'clonesw' is set to 1, the
  218.    subdirectory may have been deleted (check the log). Otherwise delete the
  219.    subdirectory before re-running Burf.
  220.  
  221. ! Backup is newer.
  222.    In comparing the dates of two files, the file in the target directory
  223.    was found to be newer than that in the source directory.  Delete the
  224.    file in the target directory, then copy the source file or re-run Burf.
  225.  
  226.  
  227. Fatal errors:
  228. -------------
  229.  
  230. Certain errors are regarded as fatal and cause Burf operation to be aborted.
  231. These errors include the failure of the makedir() function and a non-zero
  232. return code from any COPY, PROTECT or RESIDENT command.
  233.  
  234.  
  235. Other things you might like to know about Burf:
  236. -----------------------------------------------
  237.  
  238. Return codes from ADDRESS COMMAND are not available to Rexx programs running
  239. under pre-2.0 versions of Amiga DOS.  If you are running an old version, you
  240. should be sure that the target directory is not write-protected and has
  241. enough room for all the files in the source directory, and that the source
  242. directory is not write-protected if 'flagsw' has been set to 1.  Under
  243. Amiga DOS 2.04 or later, Burf will terminate if any COPY, PROTECT or
  244. RESIDENT command results in a non-zero return code.
  245.  
  246. You are free use Burf for as long as you like and to modify it in any way
  247. that suits your needs, but please do not distribute a modified version.  I
  248. do not ask for any remuneration, but if you would like to send me anything
  249. (except perhaps a duck), I would be delighted to receive it.  I will make
  250. a sincere effort to answer any questions you may have about Burf.  My
  251. address is:
  252.  
  253.     Michael Tanzer
  254.     P.O. Box 289
  255.     Carlton North, VIC 3054
  256.     Australia
  257.  
  258.     Telephone:  +61 3 387 6589
  259.     Facsimile:  +61 3 388 1863
  260.