Gold Fish 2/goldfish_vol2_cd1.bin/files/dev/lang/struct/exampleprograms/uout.doc

Text File | 1994-02-01 | 6KB | 119 lines

                          Uuencode Out 1.1
                          by Roland Acton

  A number of Internet (Usenet) newsgroups allow the posting of
uuencoded binary files. Since some systems have limits (imposed by
their hardware or software) on the lengths of posted articles, these
uuencoded files are typically split up into sections of about 60K,
each of which are sent out as separate posts.
  Many newsreaders have the ability to extract the uuencoded data
from these posts and use it to recreate the original file. If yours
doesn't, or it doesn't work, you have a problem. You may have to
download the files and join them together yourself. This isn't as
easy as it sounds. The posts typically contain message headers,
comments by the poster, and the like which will confuse your
uudecode program. This extranous information must be edited out by
hand, which is tedious.
  UOut was written to deal with this problem. It will take the
separate files, join them together (stripping out all non-uucode
data in the process), call your uudecode program on the resulting
file, and then delete the uucode files.
  This program was written as an example program for the Struct
compiler, and is being distributed both with it and as a stand-alone
archive. If you have the stand-alone version, just copy the UOut
program into your C: directory. If you have the Struct archive, all
that's included is the source code. Set up the compiler as described
in the documentation, then compile and link the UOut program and
place the object code into your C: directory.
  You'll need to have a uudecode program in your C: directory as
well. Any standard one should work.
  UOut expects to find the uucoded files in the current directory
with names like this:

<file-list-prefix>.01
<file-list-prefix>.02
<file-list-prefix>.03
     .........

  For example:

Belldandy.01
Belldandy.02
Belldandy.03
Belldandy.04

  To decode the example, you would type:

UOut Belldandy

  UOut will create a temporary file called "uotBelldandy" in the
current directory, place all the important information from the
original files in it, call the uudecode program on the temporary
file, and then delete the temporary file and the originals. The
binary file contained in the "Belldandy" posts will be left in the
current directory.
  A potential problem with UOut is that it doesn't really understand
the data it's processing - it's just a joiner, not an actual
decoder. It will report an error and stop if it sees something in
the data that it can't deal with, but there may be files out there
that will slip past its checks and be decoded wrongly. (Read the How
It Works section, below, to understand this better)
  Another problem is that UOut has no idea if the uudecode program
was actually able to decode the file. If there's an error during
decoding (disk full is most likely), and UOut hasn't detected
anything wrong, the source files will be deleted. Always make
backups of important uucoded files.
 If a decoded file seems wrong in some way, restore the uucoded
files from backups (or redownload them) and run UOut on them again.
Use a text editor to look at the temporary file during the decoding
phase. If something is obviously wrong with it, you'll have to join
the files together manually. If everything looks fine, it's possible
that the file was corrupted at some point before UOut ever got to
it.

HOW IT WORKS
------------
  The basic idea behind the program is that each of the separate
files have the same fundamental structure:

  <irrelevant header>
  <uuencoded data>
  <irrelevant trailer>

  The header includes such things as the Net mail system's
information about on the post, comments from the poster, and maybe
even a shell script joiner/decoder that couldn't be used for some
reason. The trailer may include plaintext information about the
uuencoding or splitting, extra return characters, or null
characters inadvertently appended to the file at some point along
the line. None of this is necessary or useful to the uudecode
program, so it must be removed.
  UOut has a variable, COPYSTATUS, which is set to zero when a file
is first opened for reading. While the program is in the header
section, COPYSTATUS remains zero, and all data brought in from the
file is discarded instead of being written to the temporary file.
When the program believes that it has found the beginning of the
uuencoded data, COPYSTATUS is set to one and all further lines of
data are redirected to the temporary file.
  The program has several ways of determining when it has passed the
header and reached the uuencoding. It primarily uses the fact that
uuencoded data takes up exactly 62 columns, and assumes that five of
these lines in a row means that it has found the uuencoding.
(Interestingly, I found one or two cases where *63* columns were
used, and when the files were joined manually, the output binary
worked! Perhaps the 62 columns are only a convention and not a
restriction...?)
  Additionally, it knows that the data in the first file must start
with "begin", and that many encoding programs use the word "BEGIN"
in uppercase to mark the start of a segment.
  To find the end of the uuencoded data, UOut looks for a line that
is not 62 columns (which means the end of the current segment) or a
line that has the word "end" all by itself, possibly preceded by a
line less than 62 columns. It also knows that many programs mark the
end of a segment with "END" in uppercase.
  At this point, since there is nothing else of value in the file,
UOut simply closes it and goes on to the next one in the sequence.
It expects that the file containing "end" is the last one in the
sequence, and will report an error if there are more files after it
or "end" is never found at all.