home *** CD-ROM | disk | FTP | other *** search
/ APDL Public Domain 1 / APDL_PD1A.iso / compress / uucoder / ReadMe next >
Encoding:
Text File  |  1993-04-26  |  6.6 KB  |  159 lines
  1.  
  2. Documentation for UUcoder Module V1.00
  3. --------------------------------------
  4.  
  5. ********************** Incredibly boring Copyright Notice *********************
  6. *                                                                             *
  7. *  All program code is the copyright of Richard K. Lloyd and the 'borrowing'  *
  8. *     any part of it without the permission of the author is prohibited.      *
  9. *                                                                             *
  10. *******************************************************************************
  11.  
  12. If you are passing on UUcoder to your friends, please include this
  13. short text file (which I've called UUcoderDoc).
  14.  
  15. Installing UUcoder
  16. ------------------
  17.  
  18. The UUcoder is installed by typing *UUcoder. If there isn't enough RMA
  19. workspace available, then the installation will fail. To remedy this, you can :
  20.  
  21. 1) Type *GOS, which permits extra RMA space to be claimed because there is no
  22.    application (e.g. BASIC) active or
  23.  
  24. 2) *RMKILL or *RMCLEAR unwanted RAM-based modules or
  25.  
  26. 3) *UNPLUG unwanted ROM-based modules or
  27.  
  28. 4) Use *Configure RMASize to allocate more space to the RMA or
  29.  
  30. If you still can't install the UUcoder after all that, then either you
  31. have inordinately large *Configure SpriteSize/ScreenSize etc. settings or you
  32. only have a 512K RAM A305, though God knows why you have - there's only 100K
  33. free after booting !
  34.  
  35. So what does UUcoder do and why use it instead of someone else's version ?
  36. --------------------------------------------------------------------------
  37.  
  38. *Help UUcoder will reveal a little about what the program does. UUcoder is a
  39. UUencoder/UUdecoder entirely written in ARM code for speed and convenience.
  40.  
  41. I am now going to make the following bold claim :
  42. UUcoder is the fastest and best UUdecoder/UUencoder available.
  43. There, I said it !
  44.  
  45. Speed tests
  46. -----------
  47.  
  48. To back up the previous rash statement, here's a table of UUencode/UUdecode
  49. speeds for the three versions I know of on the Archimedes. The times are in
  50. seconds for a 40K binary file using an 800K moderately fragmented floppy.
  51.  
  52. Program                      Size     UUencode   UUdecode   Average   Scaled
  53. -------                      ----     --------   --------   -------   ------
  54. Hearsay C version          40K/31.5K    12.7       11.3      12.0       1.8
  55. BASIC UUcoder 1.00 (fast)     5K       129.0      191.2     160.1      23.5
  56. ARM   UUcoder 1.00 (slow)    4.5K       28.9       26.5      27.7       4.1
  57. ARM   UUcoder 1.00 (fast)    4.5K        6.5        7.1       6.8       1.0
  58.  
  59. Figures are unavailable for the 'slow' version of the BASIC UUcoder because
  60. there's a bug in it ('String too long' - I'm not going to investigate it).
  61. So my program is nearly twice as fast as the Hearsay version in the best case !
  62. It is also smaller than any other version I know of and, dare I say it, has
  63. more features...
  64.  
  65. The *UUencode command
  66. ---------------------
  67.  
  68. Syntax: *UUencode <filename> [<options>]
  69.  
  70. *UUencode takes the (usually binary) file specified and converts every 3 bytes
  71. of binary into 4 bytes of ASCII. The resulting conversion is saved in a file
  72. with the same core name as the input filename, but with an _uue extension.
  73. The ASCII format of UUencoded files is highly convenient for file transfers
  74. where the remote host can't cope with binary files. It is also more compact
  75. than plain hex and has a checksum byte at the end of each encoded line.
  76.  
  77. The *UUdecode command
  78. ---------------------
  79.  
  80. Syntax: *UUdecode <filename> [<options>]
  81.  
  82. *UUdecode takes the previously UUencoded file specified and decodes it back
  83. into the original binary, saving the result in the file mentioned in the
  84. 'begin' header of the input file. The decoded file has the file type &FFD
  85. (Data), so you may need to set the correct file type (using *SetType) or
  86. load/exec addresses afterwards.
  87.  
  88. Note: Many uuencoders/uudecoders don't bother with the checksum byte at the
  89. end of line. *UUdecode will not complain if there is no checksum at the end
  90. of line. HOWEVER, some uuencoders put a line sequence byte at the end of the
  91. line instead and *UUdecode WILL moan about this. There's not much I can do
  92. about this - I'd rather have the checksum than the line sequence byte anyday !
  93.  
  94. The command parameters
  95. ----------------------
  96.  
  97. <filename> : Maximum filename length of 23 characters. UUencoded lines must
  98.              be less than 87 characters long (they are usually a maximum of
  99.              61 or 62 characters).
  100.  
  101. <options>  : If any of the options below are omitted, then the environmental
  102.              variable 'UUcoder$Options' is read for the default values of the
  103.              missing options. Use ~ to reverse the meaning of the option.
  104.  
  105. Option   Default    Description
  106.  
  107.   F        Off      If on, forces overwriting of existing output file.
  108.                     If off, you are asked if you wish to overwrite it.
  109.  
  110.   Q        Off      If on, uses application workspace (&8000 onwards) to speed
  111.                     up the operation. If there is insufficient memory to do so,
  112.                     then the operation will be automatically switched off.
  113.                     Memory required = 19 * binary file length / 8.
  114.                     N.B. OS_Exit is called on completion if the Q option is on.
  115.                     If off, uses two open data files and reads/writes one byte
  116.                     at a time. This is much S L O W E R....
  117.  
  118.   V        On       If on, verbose mode is used whereby percentage completed
  119.                     will be displayed every 25th percentile and a '.' will be
  120.                     shown for every 1K of data processed.
  121.                     If off, the operation will be completely silent.
  122.  
  123. Revision History of UUcoder
  124. ---------------------------
  125.  
  126. BASIC version V1.00
  127. -------------------
  128.  
  129. * Written in BASIC to test that the algorithm worked. Found a bug, but don't
  130.   know what it is and I'm not going to fix it - all support for this version
  131.   has now been dropped. The bug is NOT present in the ARM code version.
  132.  
  133. ARM code module version 1.00
  134. ----------------------------
  135.  
  136. * Written as a module - now (at least) 23 times faster (with the Q option on)
  137.   than the BASIC version !
  138.  
  139. Future Improvements to UUcoder V1.00
  140. ------------------------------------
  141.  
  142. * Ho hum. All those lovely options, but I haven't coded support for wildcards
  143.   yet ! V1.00 allows only a single file to be processed at a time - I shall
  144.   work on wildcards, mark my words...
  145.  
  146. * When wildcards are sorted out, a new C (for Confirm) option will be added.
  147.  
  148. Where to find me to report bugs or improvements to the UUcoder
  149. --------------------------------------------------------------
  150.  
  151. Snail Mail           JANET e-mail
  152. ----------           ------------
  153. Richard K. Lloyd,    rkl@uk.ac.liv.cs.mva
  154. 1, Banks Road,
  155. Lower Heswall,
  156. Wirral,
  157. Merseyside. 
  158.  
  159.