PC Online 1996 October/PCO_10.ISO/filesbbs/uudecode.arj/UUSER.TXT

Text File | 1996-09-05 | 15.4 KB | 399 lines

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, get 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

UUdecode will scan for variations of the name.  The name of the file
to decode into is saved in the encoded file.

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 copyright notice in UUTECH.TXT.
The program is freeware; but if used in a for profit situation, please
contact me.

************************************************************************

UUENCODE:

UUencode a file to send it out over a communications system (e-mail).
Most e-mail systems limit the size of a single file.  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 gets 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.
                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).


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 put
in the encoded file.  This name is used by UUdecode to recreate a file
with the same name.


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 goes 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


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.

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.)


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 character set that UUencode uses was
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 not popular !

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


    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.

        -y   - 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.

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.  -C or -c imply the -L option.

FILE NAMING:

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 supplied an input file
name of FOO1.UUE, then UUdecode would 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 goes quickly.

A drive and path may also be supplied:

        UUDECODE C:\MYDIR\FOO

All the above rules apply.  But the given drive & directory is scanned.


OUTPUT FILE NAME:

Normally the name of the output file is obtained from within 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 conventions 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   *\             file name from encoded file
        UUDECODE c:ABC\FOO   *\NAME.NEW

************************************************************************

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 [phone].  I am usually home after 7PM and
stay up till 1AM - US Eastern Time; it is OK to call then.