💾 Archived View for mirrors.apple2.org.za › archive › ftp.gno.org › prodos › archivers › binscii.txt captured on 2024-12-17 at 15:03:08.
⬅️ Previous capture (2023-01-29)
-=-=-=-=-=-=-
How to use BinSCII, or Text Encoding for Fun and Profit by Todd Whitesel rev.2, 6-Sep-90 BinSCII is a program for the Apple II series that encodes and decodes Apple ProDOS files to allow convenient and error free transmission over computer networks. BinSCII is the functional equivalent to unix' uuencode / uudecode utilities and Macintosh Bin Hqx (binhex); that is, it allows any local file to be transferred via mail in a format that consists entirely of printable text, including the file's local attributes, so that the file may be perfectly recreated on the destination system. What a BinSCII File Looks Like The easiest way to identify a BinSCII encoded file is for the person who sends it to tell you it's BinSCII. The second easiest 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 (text or otherwise). 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 may 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. You will see 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 in an attempt to get BinSCII to a guy whose download environment broke Executioner. (Up until now, I sent out a file created by Glen Bredon's Executioner program: when EXEC'd, an Executioner file enters a small machine language subroutine and calls it to read the actual data from the text file.) Executioner is much faster than this EXEC file, but it cannot deal with extra white space that might slip in during transmission or editing. The encoding scheme 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 (rest assured, this will change soon). However, there are a few things you should know that could save you some minor headaches: 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. 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. When you encode files with BinSCII, it asks if you want to use CR or LF. All this does is control the newline (return) character that separates every line of text. All Apple and Mac programs expect CR, but unix programs expect LF. If you are using text transfer between an Apple (or Mac) and a unix system, use CR because the transfer program (usually Kermit or X/Y/Z-MODEM) will take care of things. (If you are using binary transfer to a unix system, use LF.) In general, one of these options has to work. If you try to list the file at some point and it prints all on a single line (CR's on an LF based system), or it prints in a barber pole style pattern (LF's on a CR based system), then using the other option will probably fix things. 4. 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. 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 @ tybalt.caltech.edu BITnet: TPW @ CITDEIMO America Online: Toddpw This file is the public domain. I place no limits on its distribution.