From: toddpw@cco.caltech.edu (Todd P. Whitesel)
Newsgroups: comp.sys.apple2
Subject: BINSCII TUTORIAL & SELF-EXTRACTING FILE (Re: EXEC Kermit?)
Date: 12 Nov 1992 10:16:06 GMT
Organization: California Institute of Technology, Pasadena
NNTP-Posting-Host: sandman.caltech.edu

jmarkus@electrical.watstar.uwaterloo.ca writes:

>So (finally) here is my question:  Is there a EXEC (text) version of kermit
>which I can FTP, then scroll on my screen and capture in a file, make a few
>adjustments and then exec on my Apple?

No, Kermit is too big to do that directly. Your best bet is to get BinSCII
(which is small enough) and use it to get Shrinkit if you don't already have
it. Then get Kermit, and use BinSCII/Shrinkit to un-text and de-compress it.
We can boot-strap an Apple from the bare serial port if necessary, but since
you already have text-capture ability it will be a lot easier in your case.
You can get both Shrinkit and Kermit via FTP to cco.caltech.edu, pub/apple2.

Todd Whitesel
toddpw @ cco.caltech.edu
____________________________________________________________________________

	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.

REM DELETE EVERYTHING ABOVE THIS LINE AND EXEC FROM BASIC.SYSTEM
NEW
0GR:COLOR=10:HLIN0,39AT9:HLIN0,39AT21:VLIN10,20AT39:LOMEM:11834
1DIMC%(79):HOME:?"CREATING BINSCII,TSYS,A8192,L3633":FORI=1TO64
2GOSUB9:C%(C)=I:NEXT:T=0:P=256:L=P*P*P:FORX=8192TO11825STEP3
3GOSUB7:T=T+I:T=T-L*(T>=L):A=INT(I/P/P):POKEX,A:I=I-A*P*P:A=INT(I/P)
4POKEX+1,A:I=I-A*P:POKEX+2,I:VLIN10,20AT39*(X-8192)/3633:NEXT:GOSUB7
5GETA$:?CHR$(4)"CREATE BINSCII,TSYS":TEXT:HOME:?I,T
6?CHR$(4)"BSAVE BINSCII,TSYS,A8192,L3633":END
7I=0:FORJ=1TO4:GOSUB8:I=I*64+C%(C)-1:NEXT:RETURN
8GOSUB9:ONC%(C)<1GOTO8:RETURN
9GETA$:C=ASC(A$)-48:ONC<0GOTO9:RETURN
RUN
QWERTYUIOPASDFGHJKLZXCVBNMqwertyuiopasdfghjklzxcvbnm0123456789[]
ZONu7x6QQRQbDpD0FZN3GRsWJaFTKXNvDZOmFRX2Fmu5JXPRKTCUDRTnDmJ1Fpe4
GXYEJ0KYKpQbDpD0FZN3GRsWJaFTKJQvDZOmFRX2Fmu5JXPRKTCUDRTnDmJ1Fpe4
GXYEJ0KYKpQbDpD0FZN3GRsWJaFTKXNvDZOmFRX2Fmu5JXPRKTCNOQ8fjJEFdE2F
gE2o]5guCorOENQu7y2hoERz]VpPJ9QRZP4pnCBJQ0mRODsK0FKNmcJROYp8OQE]
MtgzjJEYILRgAnRrSAaWiK0u6EluQS]U3nRvWavfAJIbSqXsiLOu3EOueLTupnlu
znAhJO2wSqaQpMvz7hazOANkgQEoSnQTA62WA5TKOQehOUOknj2EA5TKOQehOUOk
nj2RA5TKOQehOUOkniRBOY8iOFQa0Sxzmn2Fgn2z0E2FhE0uiExhWO2wSqaQpMvz
7hazOANkOU0oOOXpZGNuOR8pPWXvEj0Qins]OITkDG9ujZLFdn2hQO2eSt6MSLEd
A6QQlKDhymphJO1UOEWwA6OWlKDhy51UOEWwA[puTFRbjJAYILRKSEE3OoE[OoQQ
c9RFSLE[OoQQc87FSq3HSXoz0E1OkrTzLAOQOQJkkNTkfw4zOQeh6A2EA52[SLQI
Atozunxrco0uWnfg4Q]J2nE[OoWzOoQQc8G7SMQRZEehOY8ijqJu7y2z0E0u2c2z
mn0u2c0u1nuuNfs0MBDurU8uQEQ1Oduu2c1gOFk9qERq]XnG]qQQnSsUOQdQOG39
mTNu0HOu1nuuJEQaQUQu1noFJ3PsNBKhwdeuQAQQnSsUOQdQOG39mTNu0HPuOQJk
hKmFuLcJRAXwmNOk0QVzuncvFoRBATPiMEWRXaDiOYKgqBDuMdslMLWgNBDuNdCs
woWpw3PnrBW0MVJxpJQuXouuFniDwoGhQOXeiKzuOQJkkNTkpe8zOQehkNOkprQz
OQehkNDkprTzZQehOD8kgQQuHnDaYKQyOU4pOFegXIPse3DuNLWkMBaxSo4QOReg
jJEYOanAOA0Qins]2Zaz0D7OvWSJnnWyOqsQpMlzjJEFfE3xdL0uhoxuQAOQlKDh
y51SSLWwA[puJFRbZY8ijJUFdn2hQO2eSXndAbozfL1hQOX8kM4zqNtYHqQQjJEK
HGN80HkdHqX9nwyJ8UQurEFDiLGzdE3vE42gSqaQpMuzOPOpNA2uSyQJpquzjJEF
gE0uQS]Dhn2vQVWDPndhQNXrOGukjJEYILRgAnEgPoRrSEQQc8q9O]QUZEehQyTz
hLVYOoEvPqaQiJ4uUnqhQO2wSqavpMvzkMuzpe4zOQE]0e0zkrTzLA3JSXozmn1O
OQE]m80zGUpzmn3JR2pz0E3JEdpzmn3JWXnFPUigOT4ojJAYILRKSEE3OoRjPA2r
SJ2tSrQRZO0aOSeoPWXJQnWDO6QQgo[bT42WAnQIALWwA8jbT42EAnQIALWwA8jb
T42RAnQIALWwAnE3AlgJ1nWXAnEzPFRFOOJkhKnFuLxsU42EA6aQpNDkOSejOYJk
OOJkOOXpPWXvQ0mSOnW0OnRBAO1JedCmenWiOUzstL4xSuQuFnohQOXoZOguGA2r
StXZiK[zfo3sYTuNhK9hQOXyqUdIDQwJWjXy0QAhQUQ4ke8z7qDziK[z0E3zhE0v
WzQUhK]JQjaQNAQQOO8kguE9GL2KTLWoA[puTzRmOYJkguE9Ln2KTLWoA[puJFRm
OYJkOOJkOF4sgQEzdE2Fmo0uQS]KmL0uaoXuQS]HmL0uaoVoQS2lSN2WAnQIAto9
kE2FuoluWnfgcqvzpNDkOQeh6EE3AxQH0FluhoxzfL2FuLluWndzfo2FuoluWndh
QO2RAnQIALE3AjXepNTkhKxFuoxhQO2RAnE3AoWXA0nTA63HSN2WAnQIAq3JSN2E
AnQIAq3KSN2RAnQIAXn3Aj4UOS0UODdc8QHA0HquQGpOcJNudXNu7QNu0HHQRMQE
gQmOjL6MKoROnObUOUQuNoxxWoE9WoRPk]QRnzR2gQRgnS0UOEs]dJWUOUOk7QNu
0G6NUUsQpJWUjLROvWRvEhaQKoWoA8iDREMu5u7vA65UOAXGAJ8NqZRPGhQRUUaI
fXNunjXGAyWjqdhjUUavnZjJQbihW51UOUQu1niXqUCnMLWiedXurU9cOU1iwfau
MdslMBDipXPnMVYkOIKgMLWmw3CnN2XuMdslMLW1eEWhwfKcpBWhMVFsenWmwVYl
wUCnOIKgNV4uDnWzMVexpN0QOYOgZOguOFegpCrgqVFgOT5sr2bhwdXuwV9aMZ[F
DLauJ1OuAUMceoWWeIWlMBDhpZOhOTbUOEidw3OuCX5PVEdFpCrgqVFgOE0[OQQu
FniOENQu7y2hoERz]VpPDyQOnZSJ6qaA0QAhRNXJNAdUpyORjLEF8vFPhN30Q6dC
OG39git9HotrVS]ATHtzdS8hiFQTjNRJQjaQiJ9umvQQQQQQQQQQQQQQQQQQQQQQ
QQQQQQQWOYp8OFegJdsxX0FPLLW2DL4vSpDuJ29vtBPhM2i0OEiRALQbGZu5pVP5
OTKirdsaOYrgqBKxMBaxpN1ZMVbsN3JuMfCxN3Khw246pXDhw252MBP0OUTuXIPc
KT9ZOUMhwUXurU8uCYiXpCXhwdFcwfMsefJuNLWXVYJuMdslMLWoNVFkOIKcOYWn
w0KHX41KABChrO2FC2ihN2uuSZ4uQTv3ATpdHFQFhZ3dHXX9ALRvQnQJAUulQDWu
5igucEpPvPQUntEvQasQLNWDbLiOOSvgKijJWXdQODXgjJEYUdiuOHafTHluPEoz
QDEFTDQhy8s7lQwPNMQE6LWuLOJygUEhWoEg]O0vvOpJ9qJyqUEYPO17WUEYPMiO
hLXAjSdDAOXgnSdDAOXhhLQNMLoYAUoghLXNNQQTuQJQWNQYQQqQWuQIuQegWAuT
AQVgWLuUjQNgW6uIXQZJWYQY0QCJWzQUXQyJW4JyhELbAAJyNOJyhELKAAJyNAOY
OAp8niR6NOJVqOX8qOX9ii[uQGN80QSdHwT88Q8aRbQROTegENQu7y1D4nodI6X9
LAX8LAJVNOJyKKxYU6QIWivdU5QDjLYYIOXejKWYU4XwoWRkhW9uLEWN]EWLAUpP
P9QKOFegLL9HOTCned9nOJWDjnkPA9QyOFegKUsmqnWhenW3eds0ML1ved90MVF0
MVJiQTnkAlsQ0W4u1niPwfMiwUsaOYWirUixNV1sOYF5rUY4OJWDjnkPKFQrOFeg
Zd8ue3CpqEWmrVOzMUsnMVF0w3P5OJWDjnkPKrQNOFegCd9lrV1sOT5crEWUw3Cx
METQZAljnXwJYoRBATMhwUXuZd90OTMcrV5aOJWDjnkPLFQKOFegKUsmqnWUrVbl
OJWDjnkPLrQrOFegCd9lrV1sOTKhedCprU9ntLWUrVblOJWDjnkPZzQZOFegKdsl
MLWDw2FkMVJiQTnkAlsL0Wau1niGw24zXIPcKT9ZOYMcwICzMLTQZAljnCyJFoRB
AT1cedXurUiiwoWcwdXurd9lrV1sOU9xwUsxMLW3qBKgOIKgMLWmNV1sOU5iwVXi
QTnkAauu1niPwfKsed5iwEWYefPceoTuXIPcKT9ZOTFcMUXuHLQQqERq]LEG]LQ3
AEWxO0nAOONBiWquQ6OYRgDkSgOkSgTkPi]ATHAsIna]jk1SSLs]dB0koWRugQEz
yLxKTLWoA61[A5TKOUOkkB8kaKTuNoxzuExKTLWoA6JVhiruiitTYjQQlKDhy419
AnWwA7TZAB[FyoluVnxbTns]pB8kOYlklKDhy42QAnWwA7s9AnWbA4XyguCUI26W
A26EA26RA8gJ8lpQWFRphWqdY2EsTPTKZUOk5iHJQxNXNGNK0QSdTx6pSrQR7jJz
NAO]3Xlz8QHATHoANTYEJ0JQQQQuQS]Sfn2JQ0vfAqaQiKUFgL2hKgXLpqOzjJEF
gn2FhE1ujJEYYLQQc8jBSMQTnXmJYj2rSe2wSrQOkM4zmMvz8QdhuOXC0QFDPndh
QOXZpMazjNtYYO2qSqaQpMlzjZEFfE1ujJEFjE2sILaEUHQEjXWhWgXNjJWhOOXM
OFegpXCxrUCnOQEsILaW0EJu1nivNBKgwdYzMLWcMoWdqVbsOIKcOUFcwfMsefJ6
pJWDNEvu1nivedCdqBuurU8ue3KcedXuN29xrdCne2scwpjFQEQqSqfbiKohSNXM
OFegSZ4uQAQQlKogiW]vRjQQnSTNENQu7y3TI9R0nEQ3AQdQnqEvU8dF8RyPd]Qa
nNpJ68QW8Geu1noOgOuQoTb]SDWQ8FpP]]RhaKuu7y3OZI8ljJDuMoohfLRz]qQW
ZI8loFQRZI8ldAQQaKiDpc0uQS]Q3o2JWDsI0RjsILaE8WOuQS]OaL2vSA2VSN3G
SN2uSVQuQS]Oon2vUj2JSN3GSN2NSLQQc8LhSwQPOQE]0e0zlQYuZEehOQE]bmNz
kcTz8WEoQGo98L0PuP3bStmbSrRnNQIbSXMhZUCZrTYnCUMPwTCmCUYLrTYEJ0KY
KarOLXhSZT1GZ1WKXsFXCCMBVYsqNVPpMUCdM2ihqdzlwV5ceIYne3K1rfr4tBgv
DZOmFRX2Fmu5AEaRWoQQxvQRKoQQzvQTQQEIDQQQQQJQQTNQQQQQQJQAWoQQQQQQ
QQQQQQQQQQQQQQQIKoQQQQQQQQQQQQQQQQQQQQQEQQQQQQeUODDTQQQWQQQQQQrU
ODDTQQQWQQQQQQJQQQQQQQQQDRTnDmJ1Fpe4GXYEJ0KYKpQbDpD0FZN3GRsWJaFT
KXNvDZOmFRX2Fmu5JXPRKTCUDRTnDmJ1Fpe4GXYEJ0KYQQQQRmqI
REM DELETE ANYTHING AFTER THIS LINE
Newsgroups: comp.sys.apple2