home *** CD-ROM | disk | FTP | other *** search
/ PC Online 1996 October / PCO_10.ISO / filesbbs / uudecode.arj / UUTECH.TXT < prev   
Encoding:
Text File  |  1996-09-05  |  17.5 KB  |  435 lines
  1. This file contains a write-up of the more technical aspects of
  2. uuencoding and uudecoding.  First read the file UUSER.TXT, then read
  3. this for more details.
  4.  
  5. Documentation for UUENCODE/DECODE 95 (v36)
  6.  
  7. UU-encoding is a way to code a file which may contain any characters
  8. into a standard character set that can be reliably sent over diverse
  9. networks.
  10.  
  11.  
  12. THE CHARACTER ENCODING:
  13.  
  14. The basic scheme is to break groups of 3 eight bit characters (24 bits)
  15. into 4 six bit characters and then add 32 (a space) to each six bit
  16. character which maps it into a readily transmittable character.  Another
  17. way of phrasing this is to say that the encoded 6 bit characters are
  18. mapped into the set:
  19.         `!"#$%&'()*+,-./012356789:;<=>?@ABC...XYZ[\]^_
  20. for transmission over communications lines.
  21.  
  22. As some transmission mechanisms compress or remove spaces, spaces are
  23. changed into back-quote characters (a 96).  (A better scheme might be to
  24. use a bias of 33 so the space is not created, but this is not done.)
  25.  
  26. A newer, less popular, encoding method, called XX-encoding uses the set:
  27.         +-01..89ABC...XYZabc...xyz
  28.  
  29. In my opinion, XX-encoding is superior to UU-encoding because it uses
  30. more "normal" characters that are less likely to get corrupted.  In fact
  31. several of the special characters in the UU set do not get through an
  32. EBCDIC to ASCII translation correctly.  Conversely, an advantage of the
  33. UU set is that it does not use lower case characters.  Now-a-days both
  34. upper and lower case are sent with no problems; maybe in the
  35. communications dark ages, there was a problem with lower case.
  36.  
  37. This "UU" encode/decode pair can handle either XX or UU encoding.  The
  38. encode program defaults to creating a UU encoded file; but can be run
  39. with a "-x" option to create an XX encoding.
  40.  
  41. The decode program defaults to autodetect.  However the program can get
  42. confused by comment lines preceding the actual encoded data.  The decode
  43. mode can be forced to UU or XX with the "-u" or "-x" parameter.
  44.  
  45. Another option is for the character mapping table to be inserted at the
  46. front of the file.  The format for this is discussed later.  The table
  47. parameters are detected and used by this decode program.  (A table will
  48. override the "-x" or "-u" parameters.) The encode program can be run
  49. with a "-t" option which tells it to put the table into the encoded
  50. file.
  51.  
  52. A third encode mapping is the one used by Brad Templeton's ABE program.
  53. This is not handled by these programs as the check and control
  54. information surrounding the actual encoded data is in a different form.
  55.  
  56. From a theoretical view, this encoding is breaking down 24 bits modulo
  57. 64.  Note that 64**3 is = 2**24.  The result is 24 bits in for 32 bits
  58. out, a 33% size increase.  Note that 85**5 > 2**32.  Also note that
  59. there are 94 transmittable ASCII characters (from 0x21 through 0x7e).
  60. Thus modulo 85 encoding (the atob encoder) transforms 32 bits to 5 ASCII
  61. chars or 40 bits for a 25% size increase.
  62.  
  63. The trade off in the module 85 encoding is that many communications
  64. systems do not reliably transmit 85 ASCII characters.  The tilde, carat,
  65. brackets, and sometimes upper or lower case frequently get corrupted.
  66.  
  67. There are two other popular encoding techniques.  One is BinHex used on
  68. Apple Computers.  The current version is BinHex 4.0.  BinHex uses
  69. another mapping into 64 characters.  The first encoded line in a BinHex
  70. file is an encoded structure that contains the file name, size,
  71. checksum, date and time The remaining lines are encoded data.
  72.  
  73. The other technique that I have seen is BinMail used on Unisys A-series.
  74.  
  75.  
  76. COMPOSING A LINE OF ENCODED CHARACTERS:
  77.  
  78. A small number of eight bit characters are encoded into a single line
  79. and a count is put at the start of the line.  (Most lines in an encoded
  80. file have 45 encoded characters.  When you look at a UU-encoded file
  81. note that most lines start with the letter "M".  "M" is decimal 77
  82. which, minus the 32 bias, is 45.)
  83.  
  84. BinHex does not use this count character, every encoded line contains 64
  85. characters.  Except the last is limited by the size obtained from the
  86. first line.
  87.  
  88. This encode program optionally puts a check character at the end of each
  89. line.  The check is the sum of all the encoded characters, before adding
  90. the mapping, modulo 64.
  91.  
  92. Note: Horton 9/1/87 UUENCODE has a bug in the line check algorithm; it
  93. uses the sum of the original, not the encoded characters.  This decode
  94. program accepts either form of line check character.
  95.  
  96. In previous versions (4.13 and lower) the line check characters was
  97. generated by default by this encode program and was suppressed with the
  98. "-L" option.  One reason to suppress them is if they will be decoded by
  99. one of the old Horton decoders.  Most decoders either accept this form
  100. of check or simply stop looking after the line length is exhausted.  My
  101. feelings are mixed about the line checksums because errors of this type
  102. essentially never occur.
  103.  
  104. Given modern, error-free communications systems and the CRC checks on
  105. the entire file (see below) I have made the default for uuencoding to
  106. have NO line level check characters effective version 4.21.  The "-L"
  107. option on uuencode turns on generation of line checksums.  If you have a
  108. really bad communications system and you want to isolate a problem, turn
  109. them on.
  110.  
  111. Uudecode automatically checks for the presence of line checksums; so the
  112. default for uudecode is to leave line level checks on; if there are some
  113. problems the "-L" option for uudecode turns them off.  Sometimes there
  114. is junk at the end of the line which causes spurious line checksum
  115. errors.
  116.  
  117. I have encountered various other ways that encoders end lines.  One
  118. encoder put an "M" at both the start and end of the line.  Another used
  119. a line count character.  This decode program checks all of these.  I
  120. would not be surprised if some encoder out there ends lines with
  121. sequential astrological symbols.  If you encounter some other weird form
  122. of encoded file, let me know.  (The -L option turns line level checking
  123. off.)
  124.  
  125.  
  126. PACKAGING THE LINES INTO FILES:
  127.  
  128. The lines of encoded data can be preceded by comments and by network
  129. addressing information.  The encoded data is directly preceded by a line
  130. containing:
  131.  
  132.              begin <file-mode> <file-name>
  133.  
  134. This line is created by the encoding program.  The decode program scans
  135. the file looking for "begin" in column 1.  The following line is the
  136. encoded data.
  137.  
  138. Some encoders put file time and date information on the begin line:
  139.  
  140.              begin <file-mode> <file-name> <date> <time>
  141.  
  142. My UUdecoder will accept this form of begin line, but does not use the
  143. time and date information.
  144.  
  145. The final end of encoded data is an encoded line with zero encoded
  146. characters (a back-quote), followed by a line containing "end".
  147.  
  148. For integrity checking, some encode programs insert checksums for the
  149. entire file.  This decode tries to check for all known types of file
  150. checksums.  This is discussed in more detail below.
  151.  
  152. This encode program puts a header line, containing the section number
  153. and file name, in front of every section:
  154.  
  155.          "section <number> of uuencode of file <file name>"
  156.  
  157. At the end of a section the encode program inserts a line containing
  158. checksum and file size information.  This can be suppressed with the
  159. "-c" option.
  160.  
  161. Other encoders use a variety of section lines:
  162.  
  163.         The format of the Archive-name line is:
  164.                 "Archive-name: <name>/part<number>"
  165.         for example:
  166.                 Archive-name: diskutl/part02
  167.  
  168.         The format of the part line is:
  169.                 <name> part<number>/<max-number>
  170.         for example:
  171.                 diskutl part02/03
  172.  
  173.         WinCode uses:
  174.                 [ section: 1/2 file: diskutl.exe . . . .
  175.  
  176.         enuu uses:
  177.                 section 001/002  diskutl.exe  . . . .
  178.  
  179. This program checks for consistency of these names and numbers as of
  180. release 5.0.  The problem is distinguishing random text from valid
  181. lines.
  182.  
  183. For each line that uudecode thinks is a "section" line, tests are made
  184. to validate the current section number, the maximum section number and
  185. the file name.  The program is conservative and may sometimes
  186. erroneously give an "invalid section line" type of error.  Inspect the
  187. file; if uudecode made a mistake, edit or delete the indicated line; and
  188. continue.  If the problem appears to be a uudecode problem, not just
  189. some random comment lines that caused a one time problem, please contact
  190. me.
  191.  
  192. All the "integrity fields" (the checksum, the line check, and the
  193. section header line) are inserted in a way that they will be ignored by
  194. other UUDECODE programs that cannot handle them.  This decode program
  195. does not require any of these fields; if not present, integrity checking
  196. is not done.  This program pair is 100% downward compatible!
  197.  
  198.  
  199. FILE NAMES:
  200.  
  201. See UUSER.TXT for a discussion of file naming conventions.
  202.  
  203.  
  204.  
  205. DECODE and VALID LINES:
  206.  
  207. The below information is to help you solve infrequent problems when
  208. decoding files.  Normally you do not have to be concerned with any of
  209. this stuff.
  210.  
  211. UUdecode sometimes get confused and thinks header lines are encoded
  212. data.  Sometimes this is because the separator line between sections
  213. (the "cut" line) is indistinguishable from valid decodable data.  (An
  214. example is the line "---" used as a cut line on several DOS BBS
  215. systems.) You can tell UUdecode that a specific line is a cut line and
  216. not a decodable line with the -Z option:
  217.  
  218.     uudecode -Z "---" myfile
  219.  
  220. Other times there is not a cut line between file sections or there is
  221. some other problem with the file.  If so, edit the file and try again.
  222.  
  223. When decode encounters a premature end-of-file or some data which is not
  224. decodable, it assumes the end of a file section.  Decode is conservative
  225. when it encounters data it cannot decode (better an error than a bad
  226. file).
  227.  
  228. Usually this undecodable data is valid "trailer" data put at the end of
  229. file for data transmission purposes.  However the file may be bad.  So
  230. decode continues to scan the file, if decode then encounters a line
  231. which is decodable it assumes the file is bad.
  232.  
  233. When decode encounters a valid end of file section it must get the next
  234. file in sequence.  If the file name ends with a number, decode tries the
  235. next file name in numeric sequence.  Otherwise decode asks for a file
  236. name.  If this file does not contain decodable data, decode asks for
  237. another file to try.
  238.  
  239. If multiple sections are saved in a single file, each section must have
  240. some type of section line for validation.  Decode builds a table of
  241. section information so it can go back and reread if sections are not
  242. saved in order.
  243.  
  244. The "SECTION" line inserted by the UUENCODE program is used for validity
  245. checking only.  If not present, decode will accept any file containing
  246. encoded lines.
  247.  
  248.  
  249. OTHER FILE FORMS:
  250.  
  251. Sometimes files are wrapped in shell archives that automatically check
  252. sequencing and call uudecode for you on Unix systems.  If you prefer to
  253. download the raw files to MS-DOS, uudecode 5.33 will filter simple shell
  254. scripts, that use the Unix 'sed' command, and decode the data
  255. automatically.
  256.  
  257. There is one more rarely used feature of ENCODE: many input files can be
  258. encoded into one large encode file.  (I have never seen this used.) The
  259. end of an input file is a zero length encoded line, followed by another
  260. "begin" line instead of by an "end" line.  This decode program will
  261. decode this sort of file; but the encode will only handle a single input
  262. file.
  263.  
  264.  
  265. FILE LEVEL CHECKSUMS:
  266.  
  267. There are three types of file checksums found in encoded files:
  268.  
  269.        UUENCODE 2.14 and below inserted lines that gave the section
  270.        size and the original input file size.  This is supplanted
  271.        by a better technique in 3.07; but 3.07 UUDECODE still checks
  272.        and validates the old form
  273.  
  274.        UUENCODE 3.07 and Rahul Dhesi's encode scripts compute a Unix
  275.        "sum -r" on the encoded sections and on the original input file.
  276.        A difference is that UUENCODE 3.07 puts the expected "sum -r"
  277.        and size at the end of a file while Rahul''s scripts put them at
  278.        beginning.  This UUDECODE analyzes either.
  279.  
  280.        The third form of checksum is a full 32 bit CRC that Rahul's
  281.        script inserts.  My code does not handle this.  Rahul has written
  282.        the BRIK program to check them.  If there is a "sum -r" failure,
  283.        BRIK analysis should be considered.
  284.  
  285. Several encoders put in a line containing just the original file size.
  286. My uudecode checks these.
  287.  
  288.  
  289. TABLE LINES:
  290.  
  291. Some encoded files but the mapping used at the front of the encoded
  292. file, just in front of the "begin" line.  The format for this is:
  293.  
  294.                    table
  295.                    first 32 characters
  296.                    second 32 characters
  297.  
  298. All this starts in column 1.
  299.  
  300. If decode encounters a table specification, it uses it and overrides any
  301. command line parameters.  Encode will create the table lines if run with
  302. the "-t" parameter.
  303.  
  304.  
  305. COMPLETION CODES:
  306.  
  307. On successful completion, UUDECODE sets ERRORLEVEL to 0.  If there are
  308. any problems, ERRORLEVEL is set to non-zero.
  309.  
  310. The purpose of "-e" is to automatically run an un-archiver (like PKZIP
  311. or ARJ) when UUDECODE successfully completes.  If the "-e" option is
  312. given, UUDECODE calls BAT file UNARCUUE on successful completion;
  313. UNARCUUE is passed five parameters:
  314.  
  315.                 the filename decoded (with path but no extension),
  316.                 the file extension,
  317.                 the input file name  (with path but no extension),
  318.                 the input file extension that is used,
  319.                 the number of sections.
  320.  
  321. Normally the file extension tells which un-archiver to call.  The
  322. UNARCUUE BAT file, can test these parameters and call the necessary
  323. un-archiver.  If UNARCUUE is called, the return code from UUDECODE is
  324. the return code passed back from UNARCUUE.  Note: one user had a problem
  325. in that the routines called by UNARCUUE set the errorlevel to 1 which
  326. was passed back to be the return code from UUDECODE.
  327.  
  328. The "-E" (upper case) option is like "-e" but you can supply the name of
  329. the file to execute.
  330.  
  331. If you are running an automated system, the -y or -n options which force
  332. a "Y" or "N" response to messges, may be helpful.
  333.  
  334. BUGS and PROBLEMS:
  335.  
  336. I try to make this program as good as possible.  If you find a problem,
  337. please send me a diskette.  You can mail a 3 1/2" diskette in a regular
  338. envelope, with no special protection, with a single stamp.
  339.  
  340.  
  341. CONCLUSION:
  342.  
  343. This works well for me.  On UNIX I find a program I want in 3 sections:
  344.               PRG1, PRG2, PRG3.
  345. I copy the three files down to my PC as PRG1.UUE, PRG2.UUE, and PRG3.UUE.  I
  346. then just enter UUDECODE PRG and the thing decodes.
  347.  
  348.  
  349. Done privately and not for profit (freeware).  Suggestions appreciated.
  350. The programs are written in Turbo Pascal 5.5 with about 5% TASM for speed.
  351. The source is not public domain.  If included in your for profit product,
  352. please contact me.
  353.  
  354.  
  355. Richard Marks
  356. 931 Sulgrave Lane
  357. Bryn Mawr, PA 19010
  358.  
  359. Copyright (c) Richard E. Marks, Bryn Mawr, PA, 1992, 1993, 1994, 1995
  360.  
  361. Also Copyright program name of
  362.      UUENCODE 95, UUDECODE 95, UUCODE 95, UUWIN 95,
  363.      UUENCODE 96, UUDECODE 96, UUCODE 96, UUWIN 96,
  364.      UUENCODE 97, UUDECODE 97, UUCODE 97, UUWIN 97,
  365.      UUENCODE 98, UUDECODE 98, UUCODE 98, UUWIN 98,
  366.      UUENCODE 99, UUDECODE 99, UUCODE 99, UUWIN 99
  367. Copyright (c) by Richard E. Marks, Bryn Mawr, PA 1995
  368.  
  369. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  370.  
  371. Change log (started with 5.13):
  372. 95 (v36)
  373. Changed name to reflect year.
  374. -N option - always reply "NO" for automated bat files.
  375. handled nucode headers (not checksums)
  376. Fix problems involving leading blanks and GEnie (GEnie randomly inserts
  377. leading blanks on lines, sometimes leading blanks are valid, this requires
  378. a sophisticated analysis).
  379. 5.33
  380. Fix autodetect of xx encode format introduced in 5.32
  381. Fix problem with part line at very end of file
  382. 5.32
  383. Anaylsis of size lines used by other encoders. Analysis of uupost's
  384. END lines.
  385. Better 'sed' handling to work with Sun posting routines
  386. Validation of file name on 'begin' line
  387.  
  388. 5.28
  389. split ot .001, .002.
  390. Better analysis of begin line - line following must be valid encoded data.
  391. Improved (again) part line analysis.
  392. Better file name parameter analysis.
  393.  
  394. 5.25
  395. Fix memory overflow bug in 5.24.
  396.  
  397. 5.24
  398. Ignore pad characters inserted by some comm systems.
  399.  
  400. 5.22 & .23
  401. Improve analysis of "part" lines to accept form used in bin.pictures
  402. group and by mail server on Garbo.
  403. Fixes problem with encoded files that use blanks rather than backquotes.
  404.  
  405. 5.20
  406. Z command line option to specify a "cut" line between multiple sections.
  407. Needed if cut line is a valid decodable line (of low probability) which
  408. the user chooses to be interpreted as a "cut" line.  Plus other
  409. improvements in detecting end of section.
  410.  
  411. 5.16
  412. Encode will split to a minimum of 75 (was 150) lines.
  413. Passes more info to UNARCUUE
  414.  
  415. 5.15
  416. Fixes a problem with trailing blanks on lines.
  417.  
  418. 5.14:
  419. Fixes a minor bug in which a redundant error message was produced when
  420. decoding single section files.
  421.  
  422.  
  423. 5.13 VERSUS 5.10:
  424.  
  425. 5.13 decode has a command line option that disables all interactive
  426. responses to make it more useable from some BBS systems.  Examine the
  427. "y" and "Y" options.
  428.  
  429. 5.13 can increment the number on files up to five digits.  The prior
  430. limit was two digits.  You can now save files with names based on news
  431. article numbers.
  432.  
  433. 5.13 can decode files encoded into 100 or more parts.  A restriction is
  434. that if there are more than 100 parts, the sections MUST be in order.
  435.