Re: RFC: downloading info for c.s.a2 FAQ

[nathan@visi.com (Nathan Mates)]

Ok, try this for revisions....

How do I download files from the internet to my Apple II? 8/21/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
5: Next time you do this, you can skip steps 1 and 2 !

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 to (but NOT the same as) 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 quotess, 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()
GSOMEFILE.SHK   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 has only about 6 characters at the start (not all viewable
on a normal screen, especially non-Apple IIs) that identify it. Thus,
trying to look at the first few lines is pointless.

   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 IBM PC 5.25" and 3.5" disk formats are different at a
hardware level, so without (rare) addon hardware on one or both sides,
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. Alternatively, the commercial program ProTERM
3.1 by Intrec is by far the best general Apple II communications
program, so if you have at least a 128K Enhanced Apple //e, a //c,
IIc+, or Apple IIGS, it is worth it to invest in this program. See the
sections on dealers below for Intrec's address and phone number.

   The rest of this tutorial assumes that you have a basic clue as to
how to navigate the internet and download files. If this is not the
case, please read the documentation on your comm program, as well as
become familiar with getting to places on the internet and getting
files from them. As there are far too many variations of
communications, ftp and www programs to begin to scratch the surface
of them in the comp.sys.apple2 FAQ (not to mention that such info is
not really relevant), your best bet is to contact a friend with a clue
or to ask the helpdesk at the place that provides your connection to
the internet.

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.

   If you used a Macintosh to write the file to a ProDOS disk, be
warned that it'll sometimes add a 'resource fork' to the file,
rendering it unusable under ProDOS and Basic with a "FILE TYPE
MISMATCH" error on trying to access it. There's no easy solution to
this other than to avoid using the Mac.


1D) See if you can 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 not part of this FAQ, but is
available at http://www.visi.com/~nathan/a2/faq/doscmds.html]

   Next, verify that the file was transferred as a text file. From the
prompt, type the following:

PR#3
CATALOG

   If the "PR#3" command causes your computer to crash, hang, or
display garbage, you do not have an 80-column card in the normal
place. [This is rare, and only happens on ][+s, or stock //es.] Reboot
your computer and try again without the PR#3 command. The catalog
should have a line like the following (though the date and time will
vary)

 BINSCII.TXT       TXT       12   20-AUG-96  20-AUG-96  3:14    5645

   [If not in 80-column mode, that'll be wrapped to 2 lines.] Anyhow,
the number we wanted was the very last number, which should be 5645.
If tha number is 5737, you downloaded in binary mode off an IBM
PC. That'll require fixing. Also, note the file type in the second
column, which is 'TXT' here. If it is already TXT, you can skip
forward to step 1E.

   Fixing the filetype. First, note what it currently is. If it's not
'TXT', common alternatives are 'BIN' or '$00', but almost anything is
possible. The second and fourth line of the following commands, assume
it's '$00', with file length 5645. Modify those two values to match
what you saw in the catalog listing above:

RENAME BINSCII.TXT,BINSCII.ORIG
BLOAD BINSCII.ORIG,A$2000,T$00,L5645
CREATE BINSCII.TXT,TTXT
BSAVE BINSCII.TXT,A$2000,TTXT,L5645

   This first renames the old file, loads it up, creates a file of
the right length and then writes the new file.

1E) Now that the file type is correct, trying to install binscii. 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. If the file size you got
from the CATALOG above is not 5645, change the 5645 in line 10 to
whatever it is.

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

   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. 

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. These programs are listed in increasing order of
features and better user interfaces, so Unshrink ][+ will run on
preetty much anything that you got binscii running on, while
GS-Shrinkit 1.1 will only run Apple IIGSs. Apple IIGS programs can
have file formats known as 'forked files' which ProDOS 8 and regular
Shrinkit cannot unpack, so if you wish to download and unpack most GS
programs, GS-Shrinkit is required.

At least an 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

At least an Enhanced Apple //e with 128K, or //c, IIc+, IIGS:
   Although you can run Unshrink ][+, Shrinkit 3.4 is far better. Get

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

At least an 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 well 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 mentioned and downloaded
in stage 1, 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

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.

3A) 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.

3B) 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

   If you are using Lynx, when the cursor is on the file to download,
you can hit 'd' to download the file, which for most people forces a
binary download. [Lynx has too many versions with the same version
'number' and possible configurations to be able to list which ones
will work.] 

   Using most WWW browsers under unix (Netscape, Mosaic, lynx, maybe
some others) 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.

3C) 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), and
download that to your Apple II. You can keep the posts as separate
files, no need to paste them all together when saving or downloading.
For a multiple part binscii file, the order in which you unpack them
does not matter as long as you unpack every part.

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.


--
<*> 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