home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 2: PC / frozenfish_august_1995.bin / bbs / d09xx / d0904.lha / Fill / Fill.doc < prev    next >
Text File  |  1993-08-26  |  15KB  |  371 lines
  1. ============================================================================
  2.  
  3.                     Fill V1.1.  Smart Multi-file Mover.
  4.              Copyright ⌐1993 Barry Wills.  All rights reserved.
  5.  
  6.  
  7. ============================================================================
  8.  
  9.  
  10. DISTRIBUTION.
  11. ~~~~~~~~~~~~
  12. This product may be freely distributed under the following restrictions:
  13.  
  14. 1.  The complete contents of the original archive must remain intact.
  15. 2.  The original material may in no way be modified.  (See P.S. at the end
  16.     of this document for extenuation of this term.)
  17. 3.  This product may not be distributed for profit.  A nominal copying fee
  18.     is authorized (for cost of materials and shipping and handling
  19.     comparable to that charged by Fred Fish.)
  20. 4.  Commercial distribution of this product without written permission from
  21.     the author is forbidden.
  22.  
  23.  
  24.  
  25. USE OF THIS PRODUCT.
  26. ~~~~~~~~~~~~~~~~~~~
  27. This product may be used under the following restrictions:
  28.  
  29. 1.  Non-commercial use of this product is free of charge.
  30. 2.  Commercial use of this product without written permission from the
  31.     author is forbidden.  This includes shareware.
  32. 3.  Honorable mention of the author and product must be included in the
  33.     client documentation.
  34. 4.  This product may not be used for malicious intent.
  35.  
  36.  
  37.  
  38. DISCLAIMER.
  39. ~~~~~~~~~~
  40. This product is provided without any warranty, express or implied.  The user
  41. of this product assumes full responsibility for any damage resulting from
  42. the use and/or misuse of this product.
  43.  
  44.  
  45. CONTENTS.
  46. ~~~~~~~~
  47. This archive should contain the following files:
  48.  
  49.   Fishcon.txt   - Short description.
  50.   bin/cf        - Executable, creates a file of any given size.
  51.   bin/Fill      - Executable, V1.1.
  52.   docs/Fill.doc - Copyright notice and product information (this file).
  53.   source/cf.e   - Dummy-file creation utility source.
  54.   source/Fill.e - Fill program source.
  55.   pmodules/     - Directory containing the following EPP source modules:
  56.     commandLineArgs.e
  57.     skipNonWhite.e
  58.     skipWhite.e
  59.     upperChar.e
  60.  
  61.  
  62. ============================================================================
  63.  
  64.  
  65. REQUIREMENTS.
  66. ~~~~~~~~~~~~
  67. ╖ An Amiga with the minimum configuration.  Should operate under KickStart
  68.   V1.3 or higher.
  69.  
  70. ╖ Requires arp.library V39+.
  71.  
  72. ╖ You will need EPP (an E Preprocessor), Wouter van Oortmerssen's Amiga E
  73.   and at least 1Meg of RAM if you want to compile the sources.
  74.  
  75.  
  76.  
  77. WHAT IS IT?
  78. ~~~~~~~~~~
  79. This is no longer a Beta version.  Bug reports are still requested.  FILL
  80. copies or moves all files from the directory specified on the command-line
  81. to a destination (normally a floppy drive) in such a fashion as to waste as
  82. little storage as possible on the destination.  Fill supports wildcard
  83. pattern matching of filenames.
  84.  
  85.  
  86.  
  87. WHY IS IT?
  88. ~~~~~~~~~
  89. I was suitably impressed by a program I saw (can you believe it?) on
  90. IBM/clone machines called FILL.  I hunted for an equivalent (or the source
  91. so I could port it) for Amiga but it was unavailable.  So I wrote it.
  92.  
  93. This was not just an exercise.  I need this program.  I often download a lot
  94. of files to my hard drive and then peruse through them and classify them
  95. later.  But sometimes I can't get to them until MUCH later (school gets in
  96. the way, etc.)  In the meantime if I need space on my drive then I have to
  97. manually copy these files to floppy for temporary storage.
  98.  
  99. Both time and floppy diskettes are at a premium.  Manually copying takes a
  100. lot of time, and diskettes aren't a dime a dozen ($6 - $10 a dozen,
  101. actually.)  That's where FILL comes to the rescue.
  102.  
  103.  
  104.  
  105. USAGE.
  106. ~~~~~
  107. 1.  Typing FILL without any parameters (or with invalid parameters) will
  108. produce the following message:
  109.  
  110.    Usage:  Fill [<options>] <source> <dest>
  111.      <source>  Any valid DOS "dev:dir", ARP wildcards supported
  112.      <dest>    Any valid DOS "dev:dir"
  113.      [<options>]
  114.       -b##  Buffer size in kbytes (1-100; default 20)
  115.       -c    Copy files only, don't delete source (default MOVE FILES)
  116.       -e##  Error margin, add blocks to storage estimate (1-20; default 0)
  117.       -n    No DOS overhead considerations (use on MS-DOS floppies)
  118.  
  119. 2.  Typing "Fill * DF0:" will MOVE all files in the current directory to the
  120. floppy in DF0:.  The source directory may be any valid DOS file specification
  121. (i.e., any [dev:][path/]filepattern.)  Arp wildcards are supported, so if you
  122. type "Fill temp/*.l* DF0:" than all files in the temp directory that have a
  123. ".lzh", ".lha", ".l#?" extension will be moved to the floppy in DF0:.
  124.  
  125. 3. All files moved or copied retain their protection bits.  If the diskette
  126. in DF0: becomes full the number of unused bytes is displayed for your
  127. edification and you will be prompted to insert the next diskette.  Entering
  128. "Q" or "q" at the prompt will abort the program.  Typing Ctrl-C at any time
  129. will abort the copy/move and remove from destination the partially copied file
  130. in progress at the time of interrupt.
  131.  
  132. 4.  Buffer size is 20k by default.  Allowable range is 1k-100k.  Using a
  133. buffer size of 20 on my machine seemed to work well enough.  I've noticed
  134. that if you use a buffer that will accommodate half your files you'll get
  135. the best throughput.  Using 100k for tiny files does not improve the speed.
  136.  
  137. 5.  Program mode is MOVE by default.  The option '-c' disables deletion of
  138. files from the source medium.  If an error occurs while writing to
  139. destination, the destination file is removed (but the source file is not,) a
  140. message is displayed and a smaller file will be attempted.  (I could not
  141. test this feature because I couldn't get FILL to fail.  I would like to be
  142. notified if this occurs!)
  143.  
  144. 6.  Error margin is 0 blocks by default.  This option was supplied in the
  145. event that storage requirements are incorrectly calculated by the program.
  146. This should only occur when attempting to FILL a floppy that isn't empty; in
  147. this case fragmentation may occur on an uneven file extension boundary,
  148. causing an extra file extension block to be required.  I don't yet know how
  149. to predict this, so we're stuck using the option until then.  (I would
  150. greatly appreciate it if someone suggested a source of information.)
  151. (*****  DOES ANYBODY USE THIS???  *****)
  152.  
  153. 7.  Since MS-DOS has no overhead, it reserves a fixed number of blocks for the
  154. file system.  Therefore it "appears" to have no overhead, but it's an illusion.
  155. Anyway, it takes a slightly different treatment to copy to MS-DOS floppies,
  156. hence the "-n" option.  This is provided to allow you to completely fill an
  157. MS-DOS floppy.  Something which was, to the best of my knowledge, impossible
  158. with FILL prior to this version.
  159.  
  160.  
  161.  
  162. OTHER CONSIDERATIONS.
  163. ~~~~~~~~~~~~~~~~~~~~
  164. FILL does not check for files on destination that have the same name, they
  165. are simply over-written.  For this reason, and the probability of file
  166. fragmentation, using partially-full disks with this program is discouraged.
  167.  
  168. The storage requirements formula used in this program is not sanctioned (as
  169. far as I am aware) by anyone but me.  I formulated it by experimentation
  170. with DOS.  Therefore, it is possible that the calculations may occasionally
  171. be inaccurate.  If this occurs I would appreciate a bug report and as much
  172. information about the circumstances as possible.  Redirecting the output of
  173. the DOS List command to a text file(s) would be very helpful, as would error
  174. messages generated by DOS and the program.
  175.  
  176. Since FILL was written with 880k OFS floppies in mind as the standard
  177. destination device, the storage requirements calculation may be inaccurate
  178. if you are trying to fill hard/floptical drives or high density drives.  I
  179. have no need (and no means) to test other media types at this time.  If this
  180. causes you severe heartburn please let me know and I'll consider researching
  181. it.  I intentionally did not play with FFS since I don't use it on my
  182. floppies.  FILL may act a little flakey if used with FFS floppies.  I don't
  183. know for sure.
  184.  
  185.  
  186. ============================================================================
  187.  
  188.  
  189. LIMITATIONS.
  190. ~~~~~~~~~~~
  191.   ╖ Doesn't do subdirectories.
  192.  
  193.   ╖ Empty floppies work best.  Floppies that have stuff on them already may
  194.     cause fragmentation on uneven file extension boundaries.  This causes
  195.     innacurate calculation of destination storage requirements.  This is
  196.     the reason for the Error Margin option.  I don't have a rule of thumb
  197.     for the use of this option; it's up to you.
  198.  
  199.   ╖ Any other features not included that you think would be worthwhile...
  200.  
  201.  
  202.  
  203. CAVEATS.
  204. ~~~~~~~
  205.  
  206.   ╖ I've repeated this caution about using blank disks with FILL.  Let me
  207.     qualify this by saying that FILL should work properly on disks that have
  208.     been copied to, but not deleted from and recopied-redeleted, or any
  209.     combination thereof, since deleting and rewriting leave "holes" in
  210.     disks.  FILL should also work on optimized disks.  [I haven't proved this
  211.     suspicion yet.  Send news if *you* do!]
  212.  
  213.  
  214.  
  215. TO DO.
  216. ~~~~~
  217.   ╖ Optimized copying.  Comparing combined size of two or three smaller
  218.     files instead of just using the largest file that will fit.  (Not sure
  219.     if this is feasible.)
  220.  
  221.   ╖ Allow specification of an alternate destination drive (for those of us
  222.     with more than one floppy.)
  223.  
  224.   ╖ There was one request for sub-directories.  What should one do with a
  225.     a sub-directory???
  226.  
  227.  
  228.  
  229. HISTORY.
  230. ~~~~~~~
  231.    V0.10b - First release, May 1993.
  232.    ~~~~~~
  233.    1.  Locks destination.  Doesn't care if it's a floppy.
  234.    2.  Locks source.  Source is always current directory.
  235.    3.  Examines contents of source directory, stores filenames and sizes in
  236.        a list in descending order.
  237.    4.  Checks free space on destination.  Gets from list largest file that
  238.        will fit on destination.  Moves file to destination.  Continues
  239.        until list is emptied or files remaining in list won't fit on an
  240.        empty volume.
  241.    5.  Prompts for disk-change when volume becomes full.  Allows user
  242.        interruption.
  243.    6.  Displays number of unused bytes on a finished volume.
  244.    7.  Supports options:
  245.        -b##  Copy buffer size (1-100k; default 20)
  246.        -c    Copy only.  Don't move files. (default MOVE FILES)
  247.        -e##  Error Margin for storage estimate (1-20 blocks; default 0)
  248.    8.  Preserves file attributes.
  249.    9.  Recovers from full disk error (untested.)
  250.  
  251.    V0.11b - Released (oops, I don't remember).
  252.    ~~~~~~
  253.    1.  Corrected erroneous check for file too big to fit on empty volume.
  254.        V0.10b would keep asking for another disk, even though a file would
  255.        not fit on an empty volume.  User had to enter 'Q' or 'q' to quit at
  256.        the prompt.
  257.    2.  Corrected to get the destination infodata before displaying free
  258.        space when exiting the program.  Previously, the free space shown
  259.        upon exiting was the free space on the destination BEFORE the last
  260.        file was copied/moved.  (oops)
  261.  
  262.    V0.12b - Released 22 May 93.
  263.    ~~~~~~
  264.    1.  Added Ctrl-C interrupt capability.
  265.  
  266.    V1.0 - Released 13 Jun 93.
  267.    ~~~~
  268.    1.  Removed from beta status.
  269.    2.  New command-line argument for source dev:directory.
  270.    3.  Now using arp.library to select filenames by pattern.
  271.  
  272.    V1.1 - Released 24 Jul 93.
  273.    ~~~~
  274.    1.  Added -n switch for "no overhead consideration", intended for use
  275.        with MS-DOS floppies.
  276.    2.  Cosmetic adjustment of status messages.
  277.    3.  If a destination directory is specified, the file name was prepended
  278.        with the directory name instead of being placed in the destination
  279.        directory.
  280.  
  281.  
  282. ============================================================================
  283.  
  284.  
  285. MISCELLANEOUS.
  286. ~~~~~~~~~~~~~
  287. This product was developed and tested on a Commodore Amiga 500 with the
  288. following configuration:
  289.  
  290.    KickStart V1.3, WorkBench V1.3, ⌐Commodore-Amiga, Inc.
  291.    Amiga E V2.1, ⌐Wouter van Oortmerssen
  292.    AZ V1.50, ⌐Jean-Michel Forgeas
  293.    ARP V1.3, Amiga Resource Project, ⌐ARP Authors.
  294.  
  295.    DataFlyer 500 SCSI controller
  296.    Quantum 52M HD
  297.    Dual 880K floppy drive
  298.    1M 16-bit Chip RAM
  299.    CSA Derringer 030 accellerator:
  300.       68030 CPU @25MHz
  301.       68881 FPU @27MHz
  302.       4M 32-bit Fast RAM
  303.  
  304.  
  305. ============================================================================
  306.  
  307.  
  308. CREDITS.
  309. ~~~~~~~
  310. Special thanks go to:
  311.  
  312.   ╖ Wouter van Oortmerssen for making Amiga E awesome and available!
  313.  
  314.   ╖ Jean-Michel Forgeas and The Software Winery for producing such an
  315.     outstanding text editor (nice docs, too!)
  316.  
  317.   ╖ Arp Authors, those Amiga monoliths, most (all?) of whom are still
  318.     around!
  319.  
  320. Thanks!  You guys are awesome!
  321.  
  322.   ╖ Thanks goes also to those who helped me test this thing:
  323.     Kenny Odle.
  324.  
  325. "But," you say, recalling my words, "if time is at such a premium, then why
  326. spend a week writing a program that may not save you that time in return?"
  327. Well, it's because I eat bytes and I shit bits, so I gotta write SOMETHING.
  328. I WANT a program that does what FILL does; I don't particularly feel an urge
  329. to author a spreadsheet.  Would an artist paint buffalo if he wanted to
  330. paint naked women?  Besides potential fame and glory (hah-hah-haaaaah!) and
  331. the drive to make an unruly beast bow to my wim (hah-hah-haaaaah,
  332. HAH-HAH-HAAAAAAH!), it's because of programmers like the guys I just
  333. mentioned that I need a program like this.  If you LIKE to send money, then
  334. don't let me discourage you.  Otherwise, you may use FILL under the
  335. conditions described above with a clear conscience.
  336.  
  337.  
  338. ============================================================================
  339.  
  340.  
  341. CONTACTING THE AUTHOR.
  342. ~~~~~~~~~~~~~~~~~~~~~
  343. I can be reached by the following means:
  344.  
  345.   Internet:  bwills@kirk.safb.af.mil
  346.  
  347.   USnail:    Barry Wills
  348.              5528D Pryor Dr.
  349.              Scott AFB, IL 62225 (USA)
  350.              (618)-744-1096
  351.  
  352. I wrote this for my own use, but I hope you get as much use out of it as I
  353. do.  Send mail, money, software, warm weather to the address(es) above.  I
  354. am very interested in feedback; I will answer all mail.  Good luck and
  355. enjoy!
  356.  
  357. P.S. - Distributers and users of this program are hereby granted the right
  358. to replace the letters of the singly occurring expletive "shit" (now doubly
  359. occurring) with asterisks (*), character for character, if it so offends
  360. them.  This is the only permitted change to the package contents.  A package
  361. so changed MAY BE DISTRIBUTED IN THAT MODIFIED FORM (although there are some
  362. out there who would feel cheated if they couldn't figure out just what that
  363. darn word was before somone axed it!)  This amendment is intended for the
  364. convenience of G-rated BBSs.  (Those who get this package in its censored
  365. form may contact me and I will reveal to them the original word so they can
  366. change it back.)
  367.  
  368.  
  369.  
  370. ============================================================================
  371.