RFC: downloading info for c.s.a2 FAQ

[nathan@visi.com (Nathan Mates)]

[For those of you not too familiar with internet terminology, 'RFC'
means 'Request For Comments' In other words, this is a preliminary
draft I just wrote that I'd like comments/corrections before I
officially make it part of the FAQ. The current c.s.a2 FAQ is at
http://www.visi.com/~nathan/a2/faq/csa2.html, and what I wrote below
would replace sections 3-8 of it]

--- Begin text
How do I download files from the internet to my Apple II? 8/18/96

Quick summary:
1: Make sure you have a Binscii decoder
2: Make sure you have a Shrinkit unpacker
3: Download the files to your Apple II
4: Unpack with the programs

And, in more detail, starting with a word of explanation:

   [There used to be details about older Apple II packing programs in
the FAQ, but as they're pretty much never used anymore, the info on
them has been relegated to the 'obsolete' section of the
comp.sys.apple2 FAQ at
http://www.visi.com/~nathan/a2/faq/old_csa2.html]

What are Binscii & Shrinkit, and why do I need them?

   Shrinkit was written by Andy Nicholas to be able to take multiple
files (or disks) and compress them into one file. This allows a
authors to distribute programs, documentation, and anything else as
one complete file without the worry of not getting everything. It is
analogous (but NOT equivalent to Stuff-It or [PK]ZIP for Macs and
IBMs). Shrinkit comes in many different forms, as will be noted in
the section on downloading it.

   Binscii is a method of turning arbitrary Apple II files into pieces
that can be transmitted by the internet, while still retaining the
file type information, and can be safely transmitted over email, and
rearranged. It is used for two major reasons: 1) Since it splits files
up into manageable pieces, it lets huge files be transmitted without
fear of being cut short. 2) Since it translates files to strictly
printable characters, mediums that cannot support binary files (i.e.
programs that have been shrunk) such as email and usenet can send
binscii'd files, while they cannot safely send shrunk files.

   Binscii is similar (but not identical) to the unix 'uuencode'
protocol, but it is far superior. Firstly, it allows Apple II Filetype
information to be restored when the file is unpacked. Secondly,
binscii is not too picky about email or news headers (it ignores
them), and also can unpack the various pieces of a binscii'd file in
any order, and the original file will be be intact as long as all the
pieces were unpacked. Finally, you do not have to rejoin all the
pieces into one file before unpacking.

   Why these two programs are so necessary in downloading is the
following: pretty much all Apple II programs are first compressed with
Shrinkit, and if they are to be sent via email or to
comp.binaries.apple2, the shrunk file is then binscii'd. To unpack,
you will need to first un-binscii the file, if appropriate, and then
un-Shrink it.


Ok, fine. What do Binscii and Shrinkit files look like?

   If you are given a file, first look at the end of the filename.  If
it ends in ".BSC" or ".BSQ" (no "s, and upper/lower case doesn't
matter), you most likely have a binscii file. Shrinkit files tend to
end in ".SHK", but ".BXY" is also used.

   If that isn't helpful, or you have a file without a name, then take
a look at the first few lines of content. After any optional news or
email header, a binscii file should look like this:

FiLeStArTfIlEsTaRt
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789()
GBINSCII        AQhmAAAAA8)4MIAI02DA9ARMQEDtAQhmAIVZ
gYITA6u7xADA0MjM3YTNBlDOENkQwYURzITM2UDN5gzNDJUQGVERyEDM1QzM4cjN
CFUOFR0QxAjR0MjM3YTNBlDOENkQwAQRzITM2UDN5gzNDJUQGVERyEDM1QzM4cjN  

   The first two lines are constant throughout all binscii files;
the third contains the filename ('BINSCII' here) and then the encoded
file.

   On the other hand, a .SHK file cannot have any news or email header,
and the first few lines can look like this:

NuFilei][![/#NuFX_<:c[[[ H`F-fGSCII~[
cRJ0)fNN^P)3'A2p6SF6X#GPd<9#'LC^08N7n\NB7Dd!eMN&eYX0Am=fXp
dsPAsp7rh`I'NS0ALAfi2)2ysGEQ$k9CP%L9
 
   Only the first 6 characters remain constant, the 'NuFile'

   Finally, you can always try to unpack the file, as the binscii and
Shrinkit programs will notify you if the file is in the wrong format.
As files are always binscii'd last, you should thus try and unbinscii
them first, then try to unshrink them.


Enough technical discussions, now on to the specifics of how to
get binscii and shrinkit running on your system.


Step 1: Make sure you have a Binscii decoder

[If you'd rather skip this and most of the next step, Steve Cavanaugh
(who took over this service from Chuck Orem) has a disk containing
this and Shrinkit 3.4.  See the Resources section below.]

1A) Binscii has many programs that can unpack it, but if you have none
of them, you will need to first get 'BINSCII.TXT', the only binscii
program that can be transferred without any of the others or Shrinkit.
After you have this binscii program and Shrinkit, you can unpack other
binscii decoders.

1B) Make sure you have a method of getting files to a ProDOS disk on
your Apple. That may include downloading with a communications program,
or copying to a disk from another computer. [Please note that Apple II
and MS-DOS 5.25" and 3.5" disk formats are different at a hardware level,
so without (rare) addon hardware, you cannot use an IBM PC to download
stuff to an Apple II disk. Macs running system 7 can write to ProDOS
3.5" 800K disks.]

   If you do not have ProDOS, please contact your local Apple II User
Group for a copy-- they can copy it free of charge. If you do not have
a modem program, but do have a modem or null modem to another computer,
Steve Cavanaugh's disk that was mentioned above has some simple comm
programs.

1C) Download the file 'BINSCII.TXT' to your Apple II. A copy is linked
in at Nathan Mates's Apple II Resources WWW pages,
http://www.visi.com/~nathan/a2/binscii.txt Or, check the major Apple
II ftp sites (see above), as well as ftp.ugcs.caltech.edu,
pub/nathan/binscii.txt

   This is a _text_ file. (Previous versions of it were named
'binscii.exe', which most people confused as being a MS-DOS
executable, which the program most definitely is not.) It must be
downloaded in text mode to your computer, or it will require some work
to get it working. Check the ftp and [z]modem transfer options to make
sure binary mode is off before downloading it to your Apple II.

1D) Try to unpack it. You will need to get to Applesoft Basic under
ProDOS to do this. [ProDOS identifies itself as such when booting, and
Basic is the ']' prompt available by running 'BASIC.SYSTEM' if you
booted to the Finder]. From the prompt, change to the disk/directory
with the BINSCII.TXT file in it. [A quick list of Dos 3.3 and ProDOS
commands is available at http://www.visi.com/~nathan/a2/faq/doscmds.html]
Then, type the following:

EXEC BINSCII.TXT

   If you get a lot of ?SYNTAX ERRORs and beeps, then you most likely
did not download it in ascii mode. You should try again, making sure
of ascii mode, or try typing in this program and running it:

10 D$=CHR$(4):PRINT D$"BLOAD BINSCII.TXT,A$2000,L5645,TTXT"
20 FOR I=8192 TO 8192+5645: IF PEEK(I)=10 THEN POKE I,13
30 NEXT: PRINT D$"DELETE BINSCII2.TXT"
40 PRINT D$"CREATE BINSCII2.TXT,TTXT"
50 PRINT D$"BSAVE BINSCII2.TXT,A$2000,L5645,TTXT"

   Use the basic command 'RUN' (no "s) to run this program. After it
is done, you should have a better chance at being able to "EXEC
BINSCII2.TXT" and run it. [Note that if you downloaded this to an IBM
PC in ascii, then to an Apple II in binary mode, this'll probably not
work due to the way MS-DOS signals the end of a line. Try changing the
5645 in lines 10, 20 and 50 to 5737, rerunning it, and EXECing
BINSCII2.TXT again .]

   If you get a FILE TYPE MISMATCH, then your comm program or
translator most likely did not set it to an Apple II text file. That
can be changed by this sequence of ProDOS commands:

BLOAD BINSCII.TXT,A$2000,L5645,TTXT
CREATE BINSCII2.TXT,TTXT
BSAVE BINSCII2.TXT,A$2000,L5645,TTXT

   And then "EXEC BINSCII2.TXT". (Again, if it went through an IBM PC
Note that downloading binscii.txt via an IBM PC, the 5645 may have to
change to 5737) The macintosh will sometimes add a 'resource fork' to
the file, rendering it unusable under ProDOS and Basic with the same
"FILE TYPE MISMATCH" error. There's no easy solution to this other
than to avoid using the Mac.

1D) After all of this is done, you should have the 'BINSCII.SYSTEM'
program on the disk/directory you EXECd binscii from. To run it, type

-BINSCII

   That should start it. For now, with no files to decompress, just
exit it. Congratulations, you can now unpack BINSCII files.

1E) There are fancier BINSCII decoders, but this one is the only that
can be easily transferred. If you have a GS, you might want to consider
downloading the gsciiplus program from some of the following ftp sites:

apple2.archive.umich.edu, apple2/gs/archivers/gscii.bsc 
apple2.caltech.edu pub/apple2/addons/nda/gscii231.shk

   However, to unpack this, you will need a Shrinkit program (detailed
in the next section) to unpack them before you can use them. Once
unpacked, you will need to copy the 'gsciiplus' NDA to the DESK.ACCS
folder inside the SYSTEM folder on your boot GS/OS disk.

   There are some binscii decoders for non-Apple II platforms; they
will be listed shortly.



Step 2: Getting a Shrinkit Program for your Apple II

2A) Ok, getting and downloading binscii is the hard part,
promise. Because binscii takes care of the worry of filetypes, end of
lines and the like, you don't really need to worry about those
problems again.

   Which Shrinkit program you should download depends on which model
of Apple II you have:

Apple ][+ with 64K running ProDOS:
Your only option is Unshrink ][+ and Autounshrink, available via ftp from

apple2.caltech.edu, pub/apple/ARCHIVERS/unshk2plus.bsc
apple2.caltech.edu, pub/apple/ARCHIVERS/autounshk.bsq

Apple //e, //c, IIc+, IIGS:
   Although you can run Unshrink ][+, Shrinkit 3.4 is far better. Get
apple2.caltech.edu, pub/apple/ARCHIVERS/shrinkit34.bsc

Apple IIGS with at least 1.5MB Ram, running GS/OS System 5.0.4 or later
[Hard drive recommended]
   GS-Shrinkit is the best choice, though if you spend most of your
time in ProDOS 8, you may also want to get Shrinkit 3.4 as detailed
above. You can get GS-SHrinkit from

apple2.caltech.edu, pub/apple/ARCHIVERS/gshk11.bsc

2B) Download the appropriate file(s) to your computer, and unpack them
with the binscii decoder. 

   IMPORTANT NOTICE: The gscii plus NDA (and related unpackers, like
the sscii command) can NOT correctly unpack the GS-Shrinkit 1.1 file.
You _MUST_ use the binscii program that was detailed in stage, or wait
for GS-Shrinkit 1.1A.

2C) Run them Shrinkit program you just unpacked. GS-Shrinkit can be
run by double-clicking on its icon in the Finder or the eqivalent for
other launchers. For the other programs, from the Basic ']' command in
the disk/directory where you unpacked the program type 'CAT' to get a
list of files. Find the filename of the program, and then '-FILENAME'
to run it. (Replace 'FILENAME' with the name you saw in the list)

2D) See, that was definitely easier!


Step 3: Downloading anything else

3A) Figure out what files you wish to download. Your usual choices are
are from FTP sites, over the web, or from comp.binaries.apple2/email.

3B) From a FTP site, determine which files you want to download. If
the filenames end in '.SHK' or '.BXY' (upper/lower case doesn't
matter), then the files _MUST_ be downloaded in binary format to
unpack correctly.  [.BSC and .BSQ don't care, thanks to the wonders of
Binscii] To do this from a text ftp program, type 'BIN' (no 's) and
press return before downloading any files. Any other ftp program will
probably have its own methods; read its manual or help documentation.

   Next, when transferring the files to your Apple II, the transfer
must also be done in binary mode; check the download options of your
program and whatever program you're using to transfer.

3C) From a WWW browser, most browsers are not set up to download .SHK
files in binary, which will make them impossible to unpack. There are
two solutions to this. Firstly, Dan Zimmerman has made the Apple II
archive at Caltech automatically send files in binary mode; go to
http://apple2.caltech.edu/a2archive.html

   Secondly, you can try editing the file '.mime.types' (no 's) in
your home directory on most unix systems. (Contact your local sysadmin
or guru for help on unix editors). Add the following lines to the
file:

application/x-Shrinkit shk SHK sdk SDK
application/x-BinaryII bny BNY bqy BQY bxy BXY

   This will work for most files downloaded with lynx, netscape, and
mosaic. Non-unix browsers can do similar things, but you'll need to
read the documentation on them.

3D) From email or comp.binaries.apple2, the files are pretty much
always in BINSCII format, so you do not need to worry about binary
downloading.  Simply save the email or news articles to disk (most
things do have multiple parts, so be sure to get all of them. The
subject line on the article usually gives an indication of how many
parts there are total, and which one it is), and download that to your
Apple II. You can keep the posts separate (no need to paste them all
together when saving or downloading), as long as you run each
BINSCII'd file through the binscii decoder. [They do not automatically
support multiple part decoding]

Step 4: Unpacking them

4A) Now that you have all the files you want on your Apple II, you
will first need to run the binscii program on any BINSCII'd files you
downloaded, and then the Shrinkit program on the results of the
un-binsciiing and/or any .SHK/.BXY files you downloaded. Once you're
done with that, it's up to you to play around with the files you
unpacked.

4B) After unpacking the .BSQ files, you'll notice that .SHK files are
usually produced. You do not need to keep the .BSQ files around to
unpack the .SHK files; you may delete the .BSQ file(s) at your
convenience.  Similarly, once the .SHK file is unpacked, you can
delete it if you do not expect to need to unpack it again anytime
soon.

--- End new section

Nathan Mates
--
<*> Nathan Mates http://www.visi.com/~nathan/      <*>
# What are the facts? Again and again and again-- what are the _facts_?
# Shun wishful thinking, avoid opinion, care not what the neighbors
# think-- what are the facts, and to how many decimal places?  -R.A. Heinlein