home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / c / cbatools / !CBAdecode / !Help next >
Encoding:
Text File  |  1992-06-17  |  10.1 KB  |  242 lines
  1. Help for !CBAdecode (version 1.01)
  2. ==================================
  3.  
  4.  *  This program is FREEWARE
  5.  *  You may copy/distribute it as much as you like so long as it is not
  6.  *  copied or distributed for profit, or as part of a commercial product.
  7.  *  Use (of application and source) is entirely at your own risk.
  8.  *
  9.  *  This program uses calls and source code from the DeskLib library
  10.  
  11. This application is designed specifically to make decoding
  12. comp.binaries.acorn postings easier and quicker. It will NOT work with
  13. postings to other usenet or FidoNet groups! (This is because it relies on
  14. some header data that we place when we post files, which cannot be expected
  15. in other groups)
  16.  
  17. This application can be run in two ways:
  18. (Impressive, huh? How many other RISC OS applications do you know which
  19. can do this? (Not that any others would need to...))
  20.  
  21.  
  22. From the desktop
  23. ================
  24.  
  25. Double-click the !CBAdecode icon. A window should appear.
  26.  
  27. Drag any files that you wish to decode to the window (The order in which you
  28. do this is not important).
  29. You can also drag a directory to the window, and all files inside that
  30. directory (but NOT any files in subdirectories of it) will be scanned.
  31.  
  32.  =>  And now you can drag files from another application (i.e. your
  33.  =>  newsreader) as well (please see the note at the bottom of this file
  34.  =>  before trying this option!)
  35.  
  36. As each file is given to the application, it is scanned to find any valid
  37. cba posting parts in it. For every valid posted binary found, an icon that
  38. looks like an archive file icon (Displayed as "Full Info") will appear.
  39.  
  40. The information on this line indicates the name the post will be saved as,
  41. the approximate size (actually, it is the correct size, rounded UP to the
  42. nearest 37 kilobytes) that it will be when decoded, and the number of parts
  43. that have been found out of the number expected.
  44.  
  45. When some but not all of the parts have been found, the icon will be grey
  46. and unselectable. Once all the parts have been found, the file will be
  47. automatically selected.
  48.  
  49. This initial scan is non-multitasking, but usually takes less than a second
  50. on an Arm-2 machine to scan a typical 50kB post message file from a fast
  51. hard drive. From fast file media (ramdisc/hard drive) the operation is
  52. pretty quick, and from slow media the desktop response would be very
  53. sluggish, so you'll have to put up with it singletasking for now...
  54.  
  55. Once all files have been found (the icon will become a coloured one rather
  56. than greyed out, and will automatically be selected (inverted)), you are
  57. ready to decode the file.
  58.  
  59. To decode files, select the ones you want, just as in a normal filer window,
  60. and drag them to any filer window. Don't drag them to an application,
  61. because this won't work! (It appears to save into the CSD but don't count on
  62. this property! New versions of the application might try to do something
  63. clever like actually passing the decode file to the app.) As soon as you
  64. complete the drag, uudecoding will begin.
  65.  
  66. This uudecoding phaze is conducted in the background on the desktop. This
  67. means that most of the time you shouldn't notice its operation too badly,
  68. except where filing operations are slow (this is particularly noticable when 
  69. it is necessary to swap files). The main reason that this multitasks is so
  70. that you can see its progress, and so that you can hit the close-window icon
  71. to quit (and thus abort the operation) at any point.
  72.  
  73. If a file of the same name as the attempted output file (called, e.g.
  74. "file") exists, names A_file, B_file, C_file ... will be tried. If Z_file
  75. is reached (very unlikely) without finding a unique filename, then
  76. the attempt will be aborted completely.
  77.  
  78. If you wish to clear the list of files and start fresh, bring up the menu,
  79. and click on "Clear files". The menu also has an info window and a quit
  80. option.
  81.  
  82. To quit, use the quit on the menu, or simply close the decoder window.
  83.  
  84.  
  85. From the command-line (Archimedes or UNIX)
  86. =====================
  87.  
  88. Run the application with the syntax:
  89.   CBAdecode [options] [list_of_filenames]
  90.  
  91. e.g.
  92.   CBAdecode csa.95 csa.96 csa.97  (Archimedes)
  93.   CBAdecode csa/95 csa/96 csa/97  (UNIX)
  94.  
  95. NOTE: Currently, you CANNOT give a directory name or any wildcarded
  96. filenames to the command-line version.
  97.  
  98. Any complete and valid postings found will be decoded immediately, exactly
  99. as in the WIMP version, but without the fancy WIMP features. Decoded files
  100. will be placed into the CSD (currently selected directory)
  101.  
  102. CBAdecode has two command-line flags:
  103.   -d          Sets desktop operation mode. This manke CBAdecode try to start
  104.               up as a desktop task. It should only be used in the desktop
  105.               !Run file. DO NOT use it from within a taskwindow!
  106.   -b <size>   Sets the input and output buffer size. Specified in terms of
  107.               kilobytes. The default value is 16 (16 kilobytes), which
  108.               results in an extra 32k (2 buffers) being needed.
  109.               Values <= 4 will result in operating-system buffers being used
  110.               (as these are 4k anyway), but will cause a lot of disc
  111.               seeking, which slows down operation on floppies considerably.
  112.               Values > 64k will not make much of a difference unless all
  113.               posted parts are contained in one large input file.
  114.               Values outside the range 0..128 cause an error.
  115.               Note also, that if memory is not available for the buffers,
  116.               only operating-system buffers will be used (so if you specify
  117.               too large a value, it will drop back to 4k buffers)
  118.  
  119. (The -b flag is used in the !Run file for desktop operation, and can also be
  120. changed to a default you are happier with)
  121.  
  122. Operation
  123. =========
  124.  
  125. The way the program scans for parts means that you do not need to delete
  126. message headers and signatures, concatenate files, or even get them in the
  127. right order - everything is done automatically for you!
  128.  
  129. In fact, if you do strip headers, the program will FAIL, so just leave the
  130. message files you get from c.b.a alone, and pass them to this program in
  131. their RAW, unprocessed form.
  132.  
  133. The application will cope with all of the posted messages concatenated into
  134. one (or more) file(s), or a lot of seperate files.
  135.  
  136. It also handles any mixture of parts from different postings without
  137. complaint.
  138.  
  139. The only thing it won't currently handle is a posting with more than 32
  140. parts in it (which is a 1.6 Megabyte posting...). However, such a large
  141. posting will produce an archive file of approximately 1MB, which is a bit
  142. big for many people to handle anyway, so it is extremely unlikely that
  143. binaries larger than this will be posted on c.b.a. in one archive chunk.
  144.  
  145.  
  146. Problem shooting
  147. ================
  148.  
  149. Don't shoot problems. It's antisocial. (Bdooom-Tsh!)
  150.  
  151. What can you do wrong? Here's a list:
  152. (There are 2 types of error - warnings, which indicate possible problems,
  153. but usually don't affect the outcome of the decode (which are not even
  154. reported under the WIMP), and bad errors, which will cause the application
  155. to abort its attempt to decode that particular posting. (Some very bad
  156. and unlikely errors may even cause the application to quit)
  157.  
  158. * Not all parts present
  159.   You will not be able to decode a posting until files containing all the
  160.   relevant parts have been supplied. (These incomplete postings are shown on
  161.   the desktop in grey)
  162.  
  163. * One or more parts duplicated
  164.   The duplicate parts are ignored without comment. (actually, on the
  165.   commandline a warning is given, just ignore it)
  166.  
  167. * The quoted total number of posted parts changes from one part to another
  168.   Processing of that posting will abort, and the next posting will be
  169.   started. This shouldn't happen unless the messages get corrupted or
  170.   you happen to get 2 different postings under the same name (unlikely!)
  171.  
  172. * Too many parts in the posting
  173.   The application thinks there are supposed to be (eg) 5 parts in the
  174.   posting, and it has found a part number less than 1 or greater than 5.
  175.   This usually indicates corruption of some of the files.
  176.  
  177. * Filing errors
  178.   If any problems occur when trying to read or write any files (most likely
  179.   because an input file wasn't found or because the disc is full), the
  180.   application will abort.
  181.   For disc full errors, try decoding only a single post at a time, and
  182.   if necessary, decode to a different disc than the source files are on
  183.   (note that this will require disc swapping unless using 2 drives or a
  184.   RAMdisc)
  185.  
  186. * UUcode errors
  187.   These are usually fatal (uucode is either right or wrong), and are usually
  188.   caused by parts of the uucode data being corrupted or missing. There isn't
  189.   much that can be done about this - try to get a new copy of the offending
  190.   files.
  191.  
  192. If anything goes wrong, what can you do to fix it?
  193. * Check that you are giving it the correct set of files, and try again.
  194.  
  195. * If you still can't get any joy, then you will have to resort to decoding
  196.   the file by hand - strip headers and footers, concatenate all the text
  197.   together in the correct order, and use Spark, SparkFS, or uudecode
  198.   to decode the file.
  199.  
  200.  
  201. Decoding files direct from other applications
  202. =============================================
  203.  
  204. If you drag a file to !CBAdecode from other applications (Edit or a
  205. newsreader most likely), then CBAdecode will save the file as
  206. !CBAdecode.temp.<number>
  207. This temporary file will be used when you subsequently drag archives out to
  208. a filer window.
  209.  
  210. When you next quit !CBAdecode, ALL files in the !CBAdecode.temp directory
  211. will be wiped. This includes any parts that have not been used.
  212.  
  213. DON'T delete your original messages until you have a complete, working
  214. archive from CBAdecode - don't expect CCBAdecode to keep the file for you!
  215.  
  216. *FUTURE* versions of CBAdecode may be upgraded to keep any parts that have
  217. not yet been decoded successfully, so that you can just drag in any new
  218. messages and 'skim off' any completed postings...
  219.  
  220.  
  221. The author
  222. ==========
  223.  
  224. If you have any bug reports or suggestions to send to the author, or if you
  225. want to offer him an extremely highly paid job and a Porsche (preference,
  226. black 930 or 944), write to:
  227.  
  228.   *  Jason Williams
  229.   *  R.D.2, Manuel Road,
  230.   *  Silverdale,
  231.   *  North Auckland,
  232.   *  NEW ZEALAND.
  233.   *
  234.   *  jwil1@cs.aukuni.ac.nz
  235.   *
  236.   *  (Moderator of usenet groups comp.binaries.acorn and comp.sources.acorn)
  237.  
  238. P.S.
  239. ====
  240.  
  241. Apologies for the humour - I'm in a good mood today ;-)
  242.