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