This file contains user documentation for the UUENCODE/DECODE pair. SUMMARY: This package encodes and decodes "UUencoded files". UUencoding is a popular technique for reliably sending binary files over communications systems. Common binary files are "zip files" produced by pkzip, gif and jpg picture files, and doc files produced by word processors. To send a binary file, UUencode the file and send it out with your favorite e-mail or communications program. To receive the file, download the UUencoded version to your PC and UUdecode it. There are many public domain UUencoders and decoders. This pair was originally written in 1987 and has been kept up to date since; it is designed to handle just about anything you can throw at it with ease. For more details on how to use the UUENCODE and UUDECODE programs, read this document. For a technical description of the UUencode process, see UUTECH.TXT. SIMPLE, COMMON USE: To decode a file, download it to your PC. Give the filename an extension of ".UUE". (ie: FOO.UUE); this aids you in identifying it as a uuencoded file. If the file was sent out in multiple parts, put the part number on the end of the file name (ie: FOO1.UUE, FOO2.UUE, etc.). Then enter: UUDECODE FOO The name of the file to decode into is saved in the encoded file; so you do not have to supply it. To encode a file, enter: UUENCODE filename There are all kinds of options, which are described below; but you should ignore them if the above works for you. DISCLAIMER: This program was written by me, Richard Marks, and it is copyrighted. Please see the copyright notice in UUTECH.TXT. The program is freeware for personnal, private use. If used in any other way, please contact me - there is a modest charge. The feature of MIME Base64 decoding is available as a $10 option. My address is at the end of this file. ************************************************************************ UUENCODE: UUencode a file to send it out over a communications system (e-mail). Most e-mail systems limit the size of a single message. A typical limit is 64 thousand bytes. UUencode splits the encoded file into parts which can be sent out one at a time. Thus a very large file is sent out as a number of smaller files that are within size limits. UUencode can automatically put checksum characters in the encoded file so the decode program can do validation. (Modern communications systems are so reliable that one rarely sees a checksum error when decoding, but I still think it is a good idea to leave checksum-ing turned on just to be sure there are no problems. This adds at most a few seconds to encoding and decoding times.) The command: UUENCODE [options] input-file [output-file] Popular options: -c - Do not create any checksums. (Checksums recommended!) -s - Do NOT split the encoded file into sections. -s nnn - Split the encoded file into sections of nnn lines, or nnK byte sections. Default is split into 950 line sections. -h nnn - Leave room in first section for nnn header (extra comment) lines. -x - Use XX encoding (see below). -6 - Use Base64 MIME compliant encoding (see below). Less Popular options: -o - write to standard output, not to a file. No splitting is done in this case. -L - Insert checksums on every line. This is an old option for use with unreliable communication systems. -t - Write the mapping table that was used into the encoded file (see below). -u - Unix format file (Unix end of line character). UUENCODE INPUT FILE NAME: The input file name must be supplied. It is the name of the file to be encoded. The file name and extension, but not the drive or path, is saved in the encoded file. This name is used by UUdecode to recreate a file with the same name. UUENCODE OUTPUT FILE NAME (of the encoded file): This is an optional parameter. Normally it is not needed. Naming can get a little complicated if you are creating split files. So let's take things in little steps. (The problem is that in automated systems, there is a need for a variety of ways to specify file names.) First, the normal case is with no output file name supplied: Output file name is input file name, with a ".UUE" extension. Output is to the current directory; the drive & directory of the input file is ignored. UUENCODE FOO.BAR creates FOO.UUE If you supply an output file name, it is used. If the output file name you supply does not have an extension, ".UUE" is used. UUENCODE FOO.BAR ABC.DEF creates ABC.DEF UUENCODE FOO.BAR ABC creates ABC.UUE UUENCODE FOO.BAR ABC. creates ABC. Note the subtly of the last example. The "." after "ABC" is an extension of all spaces; so there is no extension on the output file. This differs from the second example where, since there is no ".", the default extension of ".UUE" is supplied. Normally output is put in to the directory you are in when you enter the UUencode command (the current directory). This happens even if the input file is in some other directory. But if a drive and/or directory is specified for the output file, it is used. If you want to use the input file's drive & directory, use a directory of *\ for the output file. The input file's drive & directory is used. UUENCODE ZZZ\FOO.BAR creates FOO.UUE UUENCODE ZZZ\FOO.BAR ABC creates ABC.UUE UUENCODE ZZZ\FOO.BAR *\ABC creates ZZZ\ABC.UUE UUENCODE ZZZ\FOO.BAR *\ creates ZZZ\FOO.UUE The *\ options are very useful in automated systems. SPLIT FILES and OUTPUT FILE NAMES: UUencode checks the size of your file, if it is too small to split, the naming convention above is used. If the file is larger, the part number is put into the part name as described below. Normally UUencode splits encoded files by putting a number after the file name. UUENCODE FOO.BAR creates FOO1.UUE, FOO2.UUE, etc. UUENCODE FOO.BAR *.ZZZ creates FOO1.ZZZ, FOO2.ZZZ, etc. UUENCODE FOO.BAR ABC.ZZZ creates ABC1.ZZZ, ABC2.ZZZ, etc. Another popular way to name split files is with the extension of .001, .002, etc. If you specify an output file extension of .001, then this naming convention is used. UUENCODE FOO.BAR ABC.001 creates ABC.001, ABC.002, etc. UUENCODE FOO.BAR *.001 creates FOO.001, FOO.002, etc. (I personally prefer to use the ".UUE" extension so I can determine that this is a UUencoded file from the file name; but some prefer the .001 naming convention. The .UUE extension is strongly recommended for Windows95 users.) XXENCODING (the -x and -t options): UUencode maps a binary file into a certain character set. This character set goes through most communications systems with no problems. However some communications systems change some of the special characters used by UUencode. For example the "{" character is changed into a "<" on some systems. If you are having this sort of problem mailing to a friend, read on. One could argue that it was a bad decision for UUencode to use characters that may be changed. But many years ago, it was hard to find enough characters that could go over all communications systems unchanged. Maybe 15 years ago, the characters that UUencode uses were a good choice; but today there are other options. The XXencode option, is a better choice. It uses characters that usually get through with no problems. (It uses some lower case characters; lower case was not common on all computers 15 years ago.) Unfortunately, XXdecoders are not as commonly available as UUencoders. If the person you are mailing to has an XXdecoder, try the "-x" option on UUencode. My UUdecoder automatically detects and handles XX encoded files. Note that the default file extension is .XXE for XX encoded files. Another option is to send out the mapping table that UUencode uses. Then whatever gets changed, gets changed in the mapping table and in the data, so the decode will decode correctly. If the person you are mailing to has a UUdecoder that accepts mapping tables, try the -t option on UUencode. You can use -x and -t together, but there is no reason to do this. My UUdecoder handles mapping tables. Note that if a file is changed, UUdecode will report an input file checksum error. This is OK as long as it does not report an output file checksum error (what comes out is the important thing). Base64 (MIME Compliant) ENCODING: There is a new generalized Mail system (MIME) that can use a variety of encoding techniques. These include UU, XX, and a new slightly more efficient encoding method called Base64. The -6 option enables this form of encoding. It also disables all checksums and the table option. Do not use this mechanism unless you are certain that the recepiant can handle it. MIME decoders are yet as popular as UUdecoders. MIME has one design problem with multi-part encoded files. There is no "end" marker; the decoder knows how many parts there are by a count in the header lines. But some MIME encoders (notably the one used when AOL automatically splits files into sections) do not put in these count lines. Thus the decoder does not know this is a multi-part encoding. The solution is to use the "-p" option. followed by the number of parts. UUDECODE -6 -p 3 foo1.b64 My uudecoder can accept Base64, but to make a little money, it is a $10 shareware option. Please see my address below. ************************************************************************ UUDECODE: UUdecoding is the inverse of UUencoding. The input is a UUencoded file or a several split UUencoded files. The output is what the original UUencode started with. This UUdecode automatically checks for just about everything. It automatically handles split files, checksums, files packaged with the Unix 'sed' program, and UU or XX encoding. But more importantly, over the years I have encountered many different minor problems and eccentricities of various communications systems. (Even CompuServe and GEnie do, on occasion, insert some weird stuff in the middle of your files.) This UUdecode handles all this sort of stuff. In most cases you can just download a whole set of files as: FOO1.UUE, FOO2.UUE, etc. then just enter: UUDECODE FOO with no editing or anything else and "poof" the thing will decode. The majority of decode problems are related to the PC learning curve (file naming and directories) or to downloading problems. However sometimes you will have a problem situation which occurs when decoding files from one particular site. This may require special procedures for handling files from just that site. The typical site related problem is caused by a non-standard UUencoder. I have seen a lot of encoded files, but if you think there is a problem, please contact me. (Contact info is at the end of this writeup.) The command: UUDECODE [options] input-file [output-file] popular options: none - normally you do not use any options with UUdecode less popular options: -c/C - do not do any checksum testing. If upper case "C", checksum testing is done on the output file but not on any input files (see below) -L - do not do line level checks (see below) -s - do not handle split files -i - take input from stdin (implies -s) -u/x - use UU or XX decoding, do not do automatic analysis -6 - use Base64 decoding ($10 feature), no automatic analysis -p n - file is encoded in N parts, used for some Mime Base64 encoders that do not prperly include the number of parts. options for use in automated systems (see UUTECH.TXT): -e/E - call .bat file when decoding complete. -q - quiet operation (no beeps) -y - force "yes" response to all prompts. -n - force "no" response to all prompts. -z - use specific "cut" line. Options can be entered in upper or lower case unless, like for c/C, there is a specific meaning for each case. CHECKSUM TESTING: Normally you will want to run UUdecode with all checksum options on. Occasionally you will encounter a file with junk appended to lines and UUdecode will display messages stating something is wrong with a specific line. You may then accept or reject the line. If you accept all the supposedly invalid lines and if the resultant file proves correct, run UUdecode with the -L option to suppress these errors. Also let me know of the details as this is some unknown UUencoder that I want to handle. See the "contact" section at the end of this document. Some UUencoders insert checksum information in the encoded file. Checksum are a way to check the bits at a low level to make sure the resultant output file and the encoded input files are valid. In many cases if the input file is bad, the output file is also bad. But frequently the problem with the input file does not affect the output file. If you get messages about checksum errors on input files and the output file is correct, run UUdecode with the -C (upper case) option to turn off input file checksum tests. If you do get input file checksum errors, they should be understood. Even if the file decodes with no output file checksum errors; you should be certain the problem will not cause output file problems in the future. It is possible, but unlikely, that the output file may have checksum errors and still be acceptable. You can turn off all checksum testing with the -c (lower case) option. Note: -C or -c imply the -L option. FILE NAMING: UUDECODE INPUT FILE NAME: The problem with input file names is that you may be working with split files. Perhaps file FOO.EXE is encoded in two parts and you have downloaded them as FOO1.UUE and FOO2.UUE. If you supply UUdecode an input file name of FOO1.UUE, then it will find this file, decode it and go to FOO2.UUE automatically. However, most users, myself included, have the mind set that they are working with file FOO and "forget all this other stuff please". To handle this situation, UUdecode scans for several variations of the input file name you supply. If you supply a file name with an extension, FOO.XYZ, that file name is used. If not found, then UUdecode puts the number '1' after the file name (FOO1.XYZ) and UUdecode tries again. The more common case is where just the file name, with no extension is supplied: UUDECODE FOO UUdecode tries the files in the following order: FOO.UUE FOO.XXE xx encoded file FOO1.UUE FOO1.XXE FOO.001 FOO.01 FOO.1 FOO. FOO1. This may seem complicated, but it runs quickly. A drive and directory may also be supplied: UUDECODE C:\MYDIR\FOO All the above rules apply. But the given drive & directory is scanned. UUDECODE OUTPUT FILE NAME: Normally the name of the output file is obtained from the encoded file; it was put there when the file was encoded. The decoded file is recreated with this file name. The file is put into the current directory (the directory from which the UUdecode command is executed). There are several ways to alter this. If you want to specify a specific output file name, optionally with drive and directory, specify it as the second file on the command line: UUDECODE FOO c:\ABC\MYOUT.XXX If you want to use the name from within the encoded file, but with a specific drive and directory, use the drive:directory with a '*' as the file name: UUDECODE FOO c:ABC\* If you want to use the drive and directory of the input file, use a '*' as the directory name: UUDECODE c:ABC\FOO *\NAME.NEW drive & dir from encoded file UUDECODE c:ABC\FOO *\ file name from encoded file ************************************************************************ WINDOWS 95 While this is a DOS program, I use it under Windows95 all the time. The trick is file types and registration. Included with this package is a "reg" file for Win95. After you load this package in to your machine, use the Explorer to go to the folder you put it in and find the UUDECODE.REG file. Right mouse click on this file and click on "Edit". Change the lines containing c:\???\UUDECODE.EXE to state the folder where UUDECODE resides. (The machine is not magic, it's somehow gotta know where the program is.) Save the eddited file. Then double click on it; this will bring up the Registry program. The net result is that the .UUE, .XXE, and .B64 file types will be registered with Win95. Then when you double click on a file which is one of these types, UUDECODE, with the correct options to decode that file will be started. ************************************************************************ CONTACTING THE AUTHOR: You can mail me: Richard Marks 931 Sulgrave Lane Bryn Mawr, PA 19010 USA If you encounter a problem I will need to see exactly what you are working with. Please send me a diskette with whatever you think is important. You can put a 3 1/2" diskette in an envelope with no special precautions and a single stamp. You may telephone me at (610) 525-8993. I am usually home after 7PM and stay up till 11PM - US Eastern Time; it is OK to call then.