ACE-128/64 BCODE/UNBCODE DOCUMENTATION  for version 1.00  [Rev: June 29, 1995]
------------------------------------------------------------------------------
1. INTRODUCTION

This document contains the documentation for the "bcode" and "unbcode"
programs for ACE.  There are also (more advanced) versions of these programs
available in the C programming language for Unix and MS-DOS environments.

These programs allow you to encode binary data into a text format that can
be e-mailed or posted to USENET newsgroups.  Functionally, they are quite
similar to the uuencode/uudecode standard Unix utilities, except that these
programs can use a different encoding technique from "uucode" which allow
for the automatic splitting, reordering, and incremental reassembly of
multiple file segments for long files, and provide CRC-32 and size error
checking on each encoded segment.  These ACE programs will eventually be
extended to the level of the C-language programs, which can handle uucode
and hexcode formats in addition to bcode format.

2. BCODE PROGRAM

bcode [-help] [-v] [-u] [-m] [-l max_line_count] [filename ...]

Encode the given files into BCODE format.  This format, like uuencoded
format, is used for transmitting binary information through a text-only
medium.  The "-help" flag is used to display "usage" information to stderr.
The command will exit after encountering the flag, before doing any work.

The "-v" flag means to give "verbose" information about what is going on.
The "-u" and "-m" flags instruct bcode to output in either Unix (Ascii-Lf)
or MESS-DOS (Ascii-CrLf) format.  The default is good ole Petscii.

The "-l" flag and value allows you to specify the maximum number of bcoded
lines to include in each segment of the bcoded data.  When this flag is
used, output is sent to special output files rather than to stdout (where it
is usually sent).  One segment is sent to each special output file.  These
special output files are named after the file being encoded, appended with a
".b" followed by the at-least-two digit segment number.  If the full name
would exceed 16 characters, the "basename" is truncated.  If the source file
includes a path, the path is ignored and the special file is put in the
current directory.  For example,

bcode -l 800 b:junkfile

would put the bcoded segment data into "junkfile.b01", "junkfile.b02", ...,
"junkfile.b99", "junkfile.b100", etc., in the current directory.  Each line
of bcoded data contains 72 characters (which represent 54 raw data bytes),
so 800 lines will produce 59200 bytes of output (counting CR and LF at the
end of each line), which is a good size for posting or for mailing to
brain-damaged mailers (under 64K).  The max_line_count does not include the
two control lines in the bcode format.

If you include filenames on the command line, then input will be taken from
them in turn.  Otherwise, input will NOT be taken from stdin and no work
will be done.  You may include many filenames (and associated aliases) on a
command line to create a BCODE archive (which should be suffixed ".bca").

If you specify that a file is to be broken into multiple segments for
encoding, then last segment may be of zero length.  This is not an error and
will be decoded correctly, although it may be a bit of a pain.

3. UNBCODE PROGRAM

unbcode [-help] [-i] [-v] [-d] [filename ...]

This is a full-blown BCODE decoder.  It will read BCODE data from files
named in any order and reconstruct the original binary files that were
encoded using the BCODE program above.  If the "-help" flag is specified,
usage information will be given and the program will exit.

The three other flags are used to request different levels of operational
information: informative, verbose, and debugging.  Informative messages
include when a file is completely pieced back together, verbose information
includes when a file is opened or closed, and debugging information includes
a dump of the internal "have" table that keeps track of which segments of
which files the decoder currently has.  Currently, informative and verbose
information is hard-wired on.

Intermediate segments are decoded immediately and placed into temporary
files in the current directory with names like "0BC00001", with different
numbers.  These files are created and deleted as needed.  Between runs, if
there are any files that have not yet been completely pieced together, the
"have" information is saved into "0BC-STAT", which can be listed to see what
is in the temporary files and which segments of the files are missing.  An
example of its contents would be:

00001-00001  beg  0000001223  0BC00002  filea
00001-00001  beg  0000540122  0BC00004  fileb
00003-00003  mid  0000002832  0BC00001  fileb
00005-00005  end  0000000023  0BC00003  fileb

The first two columns with the dash between indicate the range of segment
numbers that are contained in the temporary file.  The next column gives the
interpretation of the temporary file, indicating if it is the beginning,
middle, or the end of the complete file being decoded.  The next column
gives the length of the temporary data (used for error recovery).  The next
column gives the name of the temporary file, and the final column gives the
name of the file that the "fragment" belongs to.

The fact that the status of decoding is kept between runs means that you
don't have to have all of the segments of the final file(s) present at any
one run.  Error checking is performed on each segment as it is being
decoded, and if an error is encoutered, the segment will be ignored.
Because of the "incremental decode" feature, you can obtain correct copies
of the segments that were found to be in error before and run them through
again.

This program will recover from all errors in the input data, including one
tricky case that the C unbcode program released earlier before could not.
The only ways that things can get fowled up are if unbcode has access
problems to the temporary files, or if you STOP the program at an
inopportune time.  To recover from all errors, you just have to delete all
of the "0BC" temporary files, including "0BC-STAT".

During decoding, this program will overwrite existing "0BC" files or files
being decoded.
------------------------------------------------------------------------END---
