home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d9xx / d952 / uuarc.lha / UUArc / UUArc.doc < prev    next >
Text File  |  1993-11-22  |  16KB  |  386 lines
  1.  
  2.                      UUARC Version 1.3 04/10/93
  3.                              J.G.BRANDON
  4.  
  5.                               FREEWARE
  6.  
  7.  
  8.   Introduction 
  9.  
  10.   Reason For Writing The Program 
  11.   Detailed Description of Program 
  12.   Installation Procedure 
  13.   Technical Reference Information 
  14.   History 
  15.   Bug Reports and Future Updates 
  16.  
  17.   Acknowledgements 
  18.  
  19.   Bibliography 
  20.  
  21.   Quick Usage Reference 
  22.  
  23.  
  24.  
  25. INTRODUCTION
  26. ------------
  27.  
  28. UUArc is an archiving system designed to enable easy transmission of
  29. binary files/archives over communcation links only capable of using
  30. ASCII, such as Electronic Mail.  It encodes binary
  31. files into files containing only printable standard ASCII characters.
  32.  
  33. Written primarily for use with GuiArc to add UUEncoding/UUDecoding
  34. facilities to it, it takes similar command line options to other commonly
  35. used archiving programs - though if you intend to use the program only via
  36. GuiArc they will not be of much interest to you.
  37.  
  38. There is a fairly comprehensive installation script included,
  39. called 'Install' which will automatically install UUArc into your system,
  40. including adding to the ArcTypes file so that, if you have it, GuiArc
  41. be able to use UUArc and play with UUEncoded files from now on.
  42.  
  43.  
  44. If you like this program, use it a lot, and can afford to do so,
  45. contributions to a charity in the U.K. called C.I.C.R.A.
  46. would be very much appreciated.
  47.  
  48. Enjoy.  :-)
  49.  
  50.  
  51. REASON FOR WRITING THE PROGRAM
  52. -------------------------------
  53.  
  54. At the moment, it is more practical for me to obtain most of my
  55. software via E-Mail, which means having to UUEncode/UUDecode
  56. all the files & archives, as E-Mail can only handle ASCII.
  57.  
  58. Now that the rather fabulous GuiArc program is available, all
  59. my archiving can by done via a nice graphical user interface
  60. rather than the horrid CLI that I used to be stuck with....
  61.  
  62. almost......
  63.  
  64. BUT as I have to UUEncode/UUDecode, I was stuck having to return to
  65. the CLI to use the rather old UUE/UUD programs.  I hunted around for
  66. a UUE archiver that would interface nicely with GuiArc, but
  67. couldn't find any.  Certainly the few others that were available were
  68. restricted in thier use, and couldn't do some of the rather simple but
  69. very useful acts of deleting/listing/moving files in an archive - all
  70. functions that can be accessed by GuiArc and are generally available
  71. with other archiving/coding systems.
  72.  
  73. Hence the birth of UUArc!
  74.  
  75.  
  76. DETAILED DESCRIPTION OF PROGRAM
  77. -------------------------------
  78.  
  79. UUArc functions like most other archivers available, and has
  80. very similar command line options to them; so if you regularly use other
  81. archiver systems then using UUArc should be fairly intuitive - a brief
  82. discription of the command line options is given if you enter 'UUArc'
  83. or 'UUArc ?' at the CLI (obviously after installing the
  84. program!)
  85.  
  86. It is based on the standard UUEncode/UUDecode utilities already very
  87. commonly in use throughout various computer systems, and will read/write
  88. files compatable with these utilities (I have test all the
  89. ones I've managed to locate with UUArc); although UUArc allows you to
  90. store multiple files in an archive, is contained in one
  91. single executable file, and unlike most other versions
  92. available UUArc also has options to list, delete etc. files in an
  93. archive.
  94.  
  95. UUArc is completely compatable with GuiArc (so I hope anyway)
  96. and all the archiving commands that GuiArc expects to be available
  97. have been included.  The main reason for writing this program was to
  98. enable me to perform all file conversions/archiving/decoding
  99. that I ever required within the GuiArc program, so as to avoid
  100. requiring the use of a CLI at any point.  As things stood I had to do
  101. all my UUEncoding/UUDecoding via the CLI, which seemed rather a shame
  102. and somewhat irritating - as everything else I could do with GuiArc's
  103. very nice and very friendly graphical interface.  Included is
  104. a suitable ArcTypes file for GuiArc, to add to your current
  105. ArcTypes file if you so wish to do so, to allow GuiArc to the UUE
  106. system; this is automatically added by the installing program
  107. included.  The one incompatibility between UUArc and GuiArc is that
  108. you can only do operations on archives relating to one file or all
  109. files in an archive, i.e. extract all files, or selectively extract
  110. one file at a time.  You can't select to extract 3 out 8 files (for
  111. instance) in one go; in that case you would select each of the three
  112. files in turn and extract them individually under GuiArc, or
  113. extract all 8 of them in one go and ignore or delete the ones you aren't
  114. interested in - though this shouldn't really pose much of a problem;
  115. one generally wants to decode a whole archive or just one or two
  116. files from the archive, not half of it.
  117.  
  118.  
  119. INSTALLATION PROCEDURE
  120. ----------------------
  121.  
  122. Installation should be relatively easy, an installation script called
  123. 'Install' has been included which will attempt to do all the work for you.
  124. Basically, all it does is to copy the UUArc executable program
  125. from this directory into your 'C:' directory, and
  126. if you have GuiArc installed in SYS:Utilities, it
  127. will attempt to add a suitable ArcTypes file onto
  128. the end of your current ArcTypes file.  If the script fails then
  129. you can easily do the installation manually; copy 'UUArc' to your
  130. 'C:' directory, and add 'ArcType' onto the end of your 'ArcTypes' file
  131. (which would normally be in the same directory as GuiArc.)
  132.  
  133. The program ought to work on just about any Amiga computer system,
  134. (and most other machines if you re-compile the 'C' source
  135. code on them!)
  136.  
  137.  
  138. TECHNICAL REFERENCE INFORMATION
  139. -------------------------------
  140.  
  141. This program has been written in 'C' using North 'C' V1.3, and is
  142. coded as nicely as I knew how to, but also as nicely as North 'C' will
  143. allow; unfortunately North 'C' V1.3 is not completely ANSI 'C'
  144. compatable and doesn't seem to allow function prototyping, but other
  145. than that North 'C' is an extremely usefull 'C' package for the Amiga.
  146. Although I have been a serious programmer since I was 13, I am rather
  147. new to 'C'!
  148.  
  149. The 'C' Source Code has of course been included, and
  150. is fairly self-explanitory.
  151.  
  152. I have written the program with machine portability in mind, hid any
  153. documentation I had on my Amiga, and tried to stick to only the
  154. standard 'C' libraries.  Unfortunately there is one machine specific
  155. part of the code which relates to extracting a filename from a
  156. filename with a full path attached to it; though this section of the
  157. code (like the rest of it) has been fairly thoroughly documented, so
  158. ought to be relatively easy to change as required by even the most
  159. novice of programmers.  Having said that, although I have no
  160. experience writing 'C' code for UN*X, I just uploaded an exact copy of
  161. the source supplied onto a UN*X machine; it compiled and ran first
  162. time, successfully, without any errors at all (which rather made my
  163. day!)
  164.  
  165. Basically, the UUEncoding algorithm works by taking sets
  166. of 3 8-bit bytes from the source file, and translates them into sets of
  167. 4 ASCII characters, each ASCII character being between decimal 33
  168. ("!") and decimal 96 ("`").  Each line of UUEncoded data is proceeded
  169. by a UUEncoded number indicating the number of bytes required to be
  170. extracted from that line, is within normal line width boundaries
  171. (generally around 61 characters long) and is terminated like a
  172. normal text file line.  The start of a UUEncoded file in an archive
  173. is indicated by a line containing a 'begin' statement (in lower case)
  174. followed by the file mode protection bits (3 digit octal number -
  175. ignored in this version as it would make the code rather system
  176. specific) followed by the name of the file.  The end of a file is
  177. indicated by a line containing an 'end' statement (again in lower
  178. case.)  Optionally a 'size' statement followed by the size of the
  179. file (decoded) in bytes can be included in a line after an 'end'
  180. statement line.
  181.  
  182. Checksums have been used in UUEncoding algorithm - outputed in
  183. UUEncoded form after the data bytes at the end of the line; although
  184. checksum output can be stopped by removing the compiler pre-processor
  185. define called 'ADDCHECK'.  The UUDecoding algorithm will check
  186. checksums digits if they have been included, but does not require
  187. them.  The 'size' statement is included in UUEncoding, but is optional
  188. for decoding - if it is there then it will be checked, but again the
  189. decoding algorithm doesn't actually require it to be there.
  190.  
  191. The program makes its best attempt to work out if an archive is corrupt
  192. by checking that all lines containing UUEncoded data are of the
  193. right length, and all UUEncoded characters are between the
  194. right limits, and checks any checksums (if present.)  If a UUEncoded line
  195. appears to be corrupt then that line is ignored and an error is
  196. displayed on the screen; though the rest of that file will be still be
  197. processed - this means that you ought to be able to give UUArc a mailbox
  198. full of UUEncoded files, even if each UUEncoded file has been split up
  199. into many seperate e-mails, as long as all the lines of the UUEncoded
  200. files are in the mailbox and in the right order the mailbox file could
  201. be processed by UUArc just as any other UUEncoded archive would be;
  202. UUArc would spew out a few errors about encountering bad lines - but
  203. these lines would presumably be the 'human' textual parts of the E-Mail
  204. and have nothing to do with the UUEncoded file; UUArc would just ignore
  205. such lines and only extract from the definitely UUEncoded lines!  Infact,
  206. just to test this was completely true, I stuck my current 100Kbytes of
  207. mailbox right into the middle of a UUEncoded archive (including all the
  208. e-mail headers etc. of course) 8-O - UUArc successfull managed to decode the
  209. files in the archive without any difficulty still.  8-)
  210.  
  211. I am neither an Amiga 'Guru' (though I've owned one back since the
  212. days the Fish disks were only into double digits) or an amazing
  213. 'C' hack; so the code is most certainly not the fastest of the
  214. UUEncoder/UUDecoder around, but hopefully it makes up for this in its
  215. completeness and portability.  If you find any bugs or have any
  216. suggestions, please do get in contact with me - I'm an
  217. electronics/computing student and am currently spending time trying to
  218. get up to date with programming langauges; I sort-of avoided 'C' for
  219. quite a while and am now paying my penance by spending many hours
  220. practising writing 'C' code, particularly portable 'C', so any comments
  221. you have on my programming style would actually be greatly appreciated.
  222.  
  223. Enjoy.  :-)
  224.  
  225.  
  226. HISTORY
  227. -------
  228.  
  229. V1.3 - 04/10/93
  230.   Cleaned up source to be more ANSI 'C' compatible and added function
  231.   prototypes - in particular the function type of signal handler for
  232.   signal exception processing, and corrected a checksum digit type bug (the
  233.   checksum digit is now an unsigned int rather than a normal int.)
  234.   Move command dropped, replaced with a generic move option/flag.  Added
  235.   support for processing of more than one filename at a time.
  236.  
  237. V1.2 - 29/09/93
  238.   Stripped the guide down.  Compatible with more UUEncoders - some naughty
  239.   encoder programs out in the world don't convert ASCII 32 'Space' characters
  240.   to ASCII 96 (`) characters, UUArc should now decode such encoded files
  241.   successfully.
  242.  
  243. V1.1 - 08/07/93
  244.   Recognises more signals to abort.
  245.  
  246. V1.0 - 07/07/93
  247.   First version completed and released.
  248.  
  249.  
  250. BUG REPORTS AND FUTURE UPDATES
  251. ------------------------------
  252.  
  253. My current contact details are:
  254.  
  255.  
  256.   Postal mail-
  257.  
  258.     Julie Brandon,
  259.     1, Olivers Mill,
  260.     New Ash Green,
  261.     Longfield,
  262.     Kent DA3 8RE,
  263.     ENGLAND.
  264.  
  265.  
  266.  
  267.   E-Mail (until September '94)-
  268.  
  269.     csc280@cent1.lancs.ac.uk
  270.  
  271.  
  272. ACKNOWLEDGEMENTS
  273. ----------------
  274.  
  275. I would like to give great thanks to all those who have contributed to
  276. the Public Domain utilities/languages for the Commodore Amiga;
  277. especially the writers of North 'C', A68k, and Blink, and
  278. of course not forgetting Fred Fish for his work in putting
  279. together a renowned reliable source for this software; specifically
  280. because I haven't ever had nearly enough money to buy a 'C'
  281. compiler for my Amiga, infact since I bought
  282. my Amiga back in the late 80's I haven't been able to afford to
  283. purchase any programming languages or any Amiga documentation!
  284. (Other than the 'The Kickstart Guide To The Amiga' and very recently
  285. Kernighan & Ritchie's 2nd Edition of 'The C Programming Language.'
  286.  
  287. I owe all the 'usefulness' I get out of my Amiga is due to the fantastic high
  288. quality utilities/langauges available on Public Domain, especially via
  289. the Fish Disk collection.  Without the Public Domain versions of
  290. many languages available for the Amiga, the grades I got during my first
  291. and second year at University would have probably been very
  292. considerably lower, and most certainly would have ment many many
  293. dreary nights stuck in terminal rooms all night fighting for use of a
  294. computer and printer.  In my second year 10 miles away from my place
  295. of residence:  away from piece, tranquility, a nice graphics user
  296. interface, cups of tea, Marmite sandwiches, decent music, a nice
  297. bath/shower, and a bed immediately on completion of any programming work.
  298.  
  299. If I knew the origins of the UUEncoding/UUDecoding algorithms, then I'd
  300. have acknowledged the programmer here!
  301.  
  302.  
  303. BIBLIOGRAPHY
  304. -----------
  305.  
  306. THE 'C' PROGRAMMING LANGUAGE - 2nd Edition
  307.     Brian W. Kernighan
  308.     Dennis M. Ritchie
  309.     ISBN 0-13-110362-8
  310.     Prentice Hall Software Series
  311.  
  312. Recommended reading for anyone wishing to pursue learning the 'C'
  313. language, with a good reference section also for those well
  314. experienced with programming other langauges.  Not recommended for
  315. novice programmers.
  316.  
  317.  
  318. THE 'KICKSTART' GUIDE TO THE AMIGA
  319.     ISBN 0-9512921-0-2
  320.     Ariadne Software Ltd,
  321.     273 Kensal Road, London W10 5DB, ENGLAND.
  322.  
  323. The version I have came out just when Kickstart 1.2
  324. was released, and therefore is rather out of date.  If this is still in
  325. print and if an up-to-date version of it is available, definitely
  326. the 'paupers' replacement to having all the official books.
  327.  
  328.  
  329. QUICK USAGE REFERENCE
  330. ---------------------
  331.  
  332. Usage with CLI only.  No graphical user interface is
  333. available by default; that is what GuiArc is for!
  334.  
  335.  
  336. Just type 'uuarc' on its own to get some brief instructions:-
  337.  
  338.  
  339. ---
  340.  
  341.  
  342. UUArc Version 1.3 by Miss J.G.Brandon Oct 05 1993.
  343.  
  344.  
  345. USAGE:    UUArc -<command>[p][m] <archive> [<filename> ... ]
  346.  
  347. Where <command> is one of-
  348.     l = List contents of <archive>.
  349.     t = Test contents of <archive>.
  350.     a = Add <filename(s)> to <archive>.
  351.     x = Extract <filenames> from <archive>.
  352.         (All files if no <filenames> given.)
  353.     d = Delete <filenames> from <archive>.
  354.         (All files if no <filenames> given.)
  355.  
  356. If included after the archiver command, the 'p' option
  357. specifies full path names to be considered; otherwise path
  358. names will be ignored.
  359.  
  360. If included after an add/extract archiver command, the 'm'
  361. option specifies files to be moved from source, i.e. source
  362. files will be deleted; otherwise they are left as is.
  363.  
  364. If applicable, <archive> must include the '.uue' extension.
  365.  
  366.  
  367. ---
  368.  
  369.  
  370. Some examples:-
  371.  
  372.   uuarc -apm fred.uue ram:harry.lha
  373.  
  374.   This would UUEncode the file 'harry.lha' from the RAM disk, into a
  375.   UUEncoded archive called 'fred.uue' in the current directory, with the
  376.   'p' option specifying that the the path 'RAM:' is to be left attached
  377.   to filename in the archive.  The 'm' option specifies that when (and if)
  378.   'ram:harry.lha' is successfully added to the archive, the file is
  379.   deleted (i.e. the file is physically 'moved' into the archive.)
  380.  
  381.   uuarc -x fred.uue
  382.  
  383.   This would extract all files from the UUEncoded archive 'fred.uue',
  384.   stripping any path-names, leaving the original files in the archive.
  385.  
  386.