How to use BinSCII or Text Encoding for Fun and Profit?

by

This looks like documentation for a very old piece of software. I’ll make sure to preserve its original tone and technical details.

BinSCII: A Guide to File Transfer for Apple II Systems

BinSCII is a utility designed for the Apple II series that enables the encoding and decoding of ProDOS files. Its primary purpose is to facilitate convenient and error-free transmission of files over computer networks. Functionally similar to Unix’s uuencode/uudecode and Macintosh’s BinHex, BinSCII allows any local file, including its local attributes, to be transferred via email in a format consisting entirely of printable text, ensuring perfect recreation on the destination system.

Identifying a BinSCII Encoded File

The most straightforward way to identify a BinSCII encoded file is for the sender to explicitly state that it is BinSCII. Alternatively, you can look for one or more blocks of text that resemble the following:

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

BinSCII version 1.0.3 refers to any file containing such a block as ‘TXT’, and filename prompts use the term ‘text file’. In both instances, these terms signify a ProDOS file presumed to contain multiple such blocks, which may be interspersed with arbitrary amounts of non-block information (text or otherwise).

Getting Started with BinSCII: Three Easy Steps

  1. Download and Prepare the EXEC File: Obtain the file named BINSCII.EXE. If it’s part of a larger file, edit it so that the first and last lines begin with REM. Delete any content before the first REM and after the last REM. Save the result as a ‘text only’ file (or print to disk), ensuring it’s a simple ASCII text file without special formatting. This guide assumes you name this file BINSCII.EXE. Before proceeding, verify that no file named BINSCII already exists in the target directory, as this will cause the decoding process to fail.
  2. Execute from BASIC.SYSTEM: From BASIC.SYSTEM (also known as AppleSoft BASIC, or the ] prompt under ProDOS), type EXEC BINSCII.EXE. Observe the lo-res thermometer bar as the decoding process unfolds, which will take a few minutes. Upon completion, a SYS file named BINSCII will be created in your current directory. You should see two large, identical numbers displayed. If they do not match, an error occurred during transit or editing, and the BINSCII file may be unreliable; it is advised not to run it. You might also encounter a ?SYNTAX ERROR or two after the numbers; this is merely AppleSoft encountering extra blank lines at the end of the text file and is not a cause for concern.
  3. Run BinSCII: BinSCII is a SYS file, similar to AppleWorks or Basic.System. You can launch it via the GS/OS Finder, a ProDOS 8 program selector, the basic dash command (type -BINSCII from the ]), or your preferred method. This will bring up BinSCII’s main menu; simply follow the on-screen menus and prompts.

For the Curious: About the Appended EXEC File

This EXEC file was developed to provide BinSCII to users whose download environments were incompatible with Executioner, a program previously used for this purpose. Executioner is significantly faster but cannot tolerate extra whitespace introduced during transmission or editing.

The encoding scheme employed by this EXEC file is similar to BinSCII’s but is implemented entirely in AppleSoft, which accounts for its slower performance. It was designed for robustness and is considerably more forgiving of text file mishaps than Executioner. Notably, it can read through spaces that AppleWorks 2.0 might insert into the main data section, which Executioner (and BinSCII 1.0.3) cannot.

When you type EXEC BINSCII.EXE, Basic.System (the ProDOS component of the BASIC environment) opens BINSCII.EXE and feeds its contents as “phantom keyboard” input to AppleSoft, simulating fast, error-free typing. If you’ve edited the file according to instructions, AppleSoft will first encounter and ignore the REM line. Next, a NEW command, a short AppleSoft program, and a RUN command will be processed. The AppleSoft program performs the actual work, using GET to read data from the rest of the file. Deciphering this program is left as an exercise for the reader; doing so will provide insight into BinSCII’s operation. However, BinSCII employs a more sophisticated integrity check, can split files into multiple text blocks, and successfully reconstructs the original file from these pieces. BinSCII is also much faster.

Important Caveats: BinSCII 1.0.3 and Its Quirks

BinSCII 1.0.3 is generally straightforward to operate, though its interface is acknowledged as archaic. The following points can help prevent minor frustrations:

  1. Full Filenames: When BinSCII prompts for a filename, it’s advisable to enter the complete name, including directories (e.g., /DATA/DOWNLOADS/SHRINKIT.BSQ). This is because every time BinSCII requests a prefix for storing files, it sets the current directory to that location (equivalent to a PREFIX command). Subsequent operations with other files will still be affected by this prefix, requiring you to account for it in the filenames you provide to BinSCII.
  2. Unconvert Option Behavior: The Unconvert option in BinSCII searches the text file for a FiLeStArTfIlEsTaRt line, then decodes a block (which contains at most a 12KB piece of the ProDOS file). This process repeats until the end of the file is reached or an error occurs. This functionality allows you to concatenate multiple BinSCII files into one large file. Assuming you have sufficient disk space for this combined file and its decoded counterparts, you can process the entire file at once through BinSCII, which will place each block correctly. You can initiate the process and leave it to complete. Be warned: BinSCII 1.0.3 does not account for extra whitespace within the text blocks. While usually not an issue, this has been known to cause BinSCII to abort processing of an otherwise intact file, which can be particularly annoying during very long file transfers.
  3. CR vs. LF Newline Characters: When encoding files, BinSCII asks whether to use CR (Carriage Return) or LF (Line Feed). This choice determines the newline character separating each line of text. Apple and Mac programs typically expect CR, while Unix programs expect LF. If you’re transferring text between an Apple (or Mac) and a Unix system, use CR as the transfer program (usually Kermit or X/Y/Z-MODEM) will handle the conversion. If performing a binary transfer to a Unix system, use LF. Generally, one of these options should work. If a file lists as a single long line (CRs on an LF-based system) or displays a “barber pole” pattern (LFs on a CR-based system), switching to the other option will likely resolve the issue.
  4. Encoded File Naming Convention: BinSCII encodes files by processing each 12KB (or smaller) chunk and outputting the result to a destination file. The names of these output files are formed by adding a sequential suffix (.01, .02, .03, etc.) to the original filename. These names are solely for organization, and you are free to rename them as you wish.

Leave a Comment