How to use BinSCII, or Text Encoding for Fun and Profit
               by Todd Whitesel        rev.3, 14-Dec-92

BinSCII is a program for the Apple II series that encodes and decodes Apple
ProDOS files to allow convenient and relatively error free transmission over
email networks. BinSCII is functionally similar to unix' uuencode/uudecode
utilities and Macintosh Bin Hqx (binhex); that is, it allows any local file,
including the file's local attributes, to be transferred via email in a format
that consists entirely of printable text. This allows the file to traverse the
network unscathed, and be perfectly reconstructed on the destination system.


        What a BinSCII File Looks Like

The easiest way to identify a BinSCII encoded file is for the person who
sent it to tell you it's BinSCII. The second easiest is to look for the name
extensions "BSC", "BSQ" (which implies that the encoded file is a Shrinkit
archive), or "BNS" (obsolete, but still used in some parts of the globe).
The hard way is to look for one or more blocks of text that resemble the
following (minus the one tab indent):

        FiLeStArTfIlEsTaRt
        ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789()
        HFILENAME       AsU4AAAACA(4nIAg1(BAfcBFXQRtAADAA0gB
        GVvTlzW6B09JAAAAXQBAH4hWAAAAadBFAcgHAIAAAAAAAAAAhDAAAAwSAAAAAAAA
        GVvTUqJ2BAAPAMAABAAAA8CAAAw4AYAAAAAAAAAAAAgAaJRBAcgHFAAAeolEAAwB
        XQBAH4hWAAAAAAAAAAwAAAAAJAAAAAAAAAAIAAAABAAAAAAAAAAAAgMACAAAAIAA
                [ ... many more lines of similar construction ... ]
        U60b3ZXx6fQLxHknavFB8KEvsqYPEAwJxxHwixYGwGPw9UmP05Zvv19IqxRGlSAI
        (Yi1OKL7CAyfqJFAN)W(Ih7F5JzLrm1Rgx8jG(e2dcOgvc(6mvpw))6mopP6h85D
        erpz7nNjyY2pI8OIbAGCHiPA4kAAiIAwKAI8DACNAIwPAAAAAAAAAAAAAAAAAAAA
        AsIR

The main menu of BinSCII 1.0.3 refers to any file containing such a block as
'TXT'. The filename prompts use the term 'text file'. In both cases, they
denote a ProDOS file which is assumed to contain any number of the above
blocks, optionally interspersed with arbitrary amounts of non-block
information (usually things like mail and news headers, and messages from the
sender describing the contents).


        Getting Started with BinSCII, in Three Easy Steps

1.      Download the file BINSCII.EXE. (If you are receiving it as part of
another file, edit the file so that the first and last lines begin with REM.
Delete anything before the first REM and anything after the last REM. Save the
result as 'text only', or print to disk, or whatever; the idea is to get a
simple ASCII text file with no special formatting information. Step two below
assumes that you named this file BINSCII.EXE, which is just an arbitrary name
that I chose. Make sure there isn't already a file named BINSCII in that
directory -- especially not the text file itself -- because the decoding
process will fail if there is.)

2.      EXEC the resulting text file from BASIC.SYSTEM (otherwise known as
AppleSoft BASIC, or the ']' prompt under ProDOS) by typing EXEC BINSCII.EXE
and watch the nifty lo-res thermometer bar. The decoding process will take a
few minutes, and when it is finished a SYS file named BINSCII will have been
created in the current directory. You should see two large numbers when it is
finished, and they should match exactly. If they don't, something went wrong
along the way (either in transit or in editing) and the BINSCII file will not
be reliable, so I'd advise against running it (in other words, don't push your
luck). You may also see a ?SYNTAX ERROR or two after the numbers; this is just
AppleSoft burping on extra blank lines at the end of the text file and, while
it may be disconcerting, it is nothing to worry about.

3.      BinSCII is a SYS file just like AppleWorks or Basic.System, and you can
run it from the GS/OS Finder, a ProDOS 8 program selector, the basic dash
command (type -BINSCII from the ']'), or whatever method you prefer. This will
bring up BinSCII's main menu; just follow the menus and prompts and you're all
set. (Well, not quite; see below for some helpful hints about BinSCII 1.0.3.)


        For the Curious: About the Appended EXEC File

This exec file was developed by me during the summer of 1990, in an attempt to
get BinSCII to a guy whose download environment broke Executioner. (Prior to
that, I sent out self-extracting files created by Glen Bredon's Executioner
program.) Executioner is much faster than this EXEC file, but it cannot deal
with extra white space that might slip in during transmission or editing, and
its method of encoding is less space-efficient. (The Executioner BinSCII is
roughly 200% the size of the original, whereas this EXEC file is about 133%
larger.)

The encoding scheme I use is similar to BinSCII, but is implemented entirely
in AppleSoft (that's why it's so slow). I made it to be rugged; in fact, it is
far more forgiving of text file mishaps than Executioner. You will notice the
difference if you use AppleWorks 2.0 to edit the file, because 2.0 adds spaces
into the main data section and this file reads right through them. Executioner
(and BinSCII 1.0.3, by the way) do not.

How it works: when you type EXEC BINSCII.EXE, Basic.System (the ProDOS part of
the BASIC environment) opens up BINSCII.EXE and uses it as 'phantom keyboard'
input to AppleSoft -- that is, it makes AppleSoft think that you typed in the
contents of the file, really fast and without any typos. If you edited the
file according to instructions, the first thing AppleSoft sees will be the REM
line, which it will ignore. Next comes a NEW, a short AppleSoft program, and a
RUN. The AppleSoft program does the real work, and uses GET to read the actual
data from the rest of the file; I'll leave deciphering the program itself as
an exercise for the reader. Since it uses the same basic process as BinSCII,
you will gain some insight into how BinSCII works by the time you are
finished. BinSCII, however, uses a far more sophisticated integrity check, and
can split files up into more than one text block (and successfully recreate
the original file from the pieces). BinSCII is also much faster.


        Important Caveats: BinSCII 1.0.3 and Various Quirks Thereof

BinSCII 1.0.3 is fairly easy to operate, but its interface is admittedly
archaic (work is progressing on a replacement, but not as fast as I'd like).
Here are some tips and clarifications on exactly what BinSCII does and how
to make it do your bidding without a lot of fuss.

1.      When BinSCII asks you for a filename, it is a good idea to enter the
complete name, directories and all. (Example: /DATA/DOWNLOADS/SHRINKIT.BSQ)
The reason for this is that every time BinSCII asks you for a prefix to store
files in, it sets the current directory there. (BinSCII does the equivalent of
a PREFIX command with the directory you specified.) If you then do something
else with another file, that prefix will still be in effect, and the filenames
you give BinSCII will have to take that into account. The safest way to avoid
all that is to always enter the complete name.

2.      How the Unconvert option works: BinSCII searches the text file for a
'FiLeStArTfIlEsTaRt' line, and then decodes a block (which contains at most a
12K piece of the ProDOS file). It repeats this process until it reaches the
end of the file (or an error occurs). This means that you can take all the
BinSCII files you have and concatenate them into one big file, and (assuming
you have the disk space for that file and its decoded counterparts) run the
file through BinSCII all at once -- BinSCII will put each block where it
belongs. You can just go away, grab a drink and a donut, and come back when it
is finished. Be warned, however, that BinSCII 1.0.3 does not account for extra
white space inside the text blocks; this is usually not a problem but it has
been known to cause BinSCII to abort processing of a file that is otherwise
intact. In the middle of a very long file, this can be rather annoying when it
happens.

3.      The flip side to #2 is that BinSCII also does not need to see complete
files in every input. You can decode part 1 today, and part 2 tomorrow, and
part three next week if you want. As long as you decode the parts into the
same directory, and don't touch the output file until you've decoded all the
parts, then everything works. This is a feature unique to BinSCII and is not
possible with similar formats on other platforms. For it to work, though, the
output file name MUST be both correct and unique within the destination
directory or BinSCII will mangle the output file. (See #4 below.)

4.      BinSCII does not check before overwriting files while it is decoding;
if you are decoding a file and there is already a different file with the same
name in the destination directory, BinSCII will happily trample it thinking it
contains previously decoded pieces of the file it is decoding. The same
applies for concatenated input files (see #2 above): if two files with the
same name are found in the same input, BinSCII will assume that they are
indeed the same file, even if they conflict, and will mix them together to
produce a completely unusable output file. This almost _never_ happens, but
the potential for danger does exist.

5.      When you encode files with BinSCII, it asks if you want to use CR or
LF. All this does is determine the newline (return) character that separates
every line of text. All Apple and Mac programs expect CR (the return key or
Control-M), but unix programs expect LF (Control-J or down-arrow). If you are
using text transfer to the other system, use CR because the transfer program
(usually Kermit or X/Y/Z-MODEM) will take care of any necessary conversions.
(Binary transfer to a unix system is the main case in which you'd want to
use LF.) In general, unless you are doing binary transfer to a PC clone or an
EBCDIC mainframe, one of those two options has to work. If you look at the
file on the other system and it prints all on a single line (CR's on an LF
system), or it prints in a barber pole style pattern (LF's on a CR system),
or it prints with no line breaks at all and fills the screen (this might
happen on a really foreign system) then using the other option will almost
definitely fix things.

6.      BinSCII files are produced by encoding each 12K (or less) chunk of the
file and outputting the result to a file in the destination directory whose
name is formed by adding a .01, .02, .03, ..., to the original filename. (If
the combined length is too long for ProDOS then it will lose the last few
characters of the original filename to make things fit.) These names are just
to keep everything organized and you can do whatever you want to them.

Send any comments, questions, flames, etc. to
Todd Whitesel
Internet: toddpw @ cco.caltech.edu
GEnie: A2PRO.TODDPW