💾 Archived View for mirrors.apple2.org.za › archive › apple.cabi.net › Utilities › GS.DOS3.3.SHK.TXT captured on 2024-02-05 at 11:44:06.
⬅️ Previous capture (2023-01-29)
-=-=-=-=-=-=-
DOS 3.3 Launcher 2.0 - Copyright 1993 John MacLean
--------------------------------------------------
What's It All About:
--------------------
For those that haven't been around the Apple // community all that long,
DOS 3.3 is an old operating system for the Apple // under which literally
thousands of programs run.
However, because DOS 3.3 only runs (without modification) on 140K 5.25"
disks, most of these programs are no longer in use. This is a real shame,
as many of them are just as good or better than the software now available
under ProDOS, and the variety is endless, particularly in the areas of games
and education.
DOS 3.3 Launcher is a utility that lets you install these DOS 3.3 programs
on your hard disk or 3.5" disks, and launch them via your favourite program
launcher, such as the Finder on the GS or ProSel on a //e or //c.
With it you can bring some of these old programs back to life, and at the
same time clear your shelves of many of your dusty and mouldy 5.25" disks.
I hope this program helps extend the life of our good friend, the Apple //.
Formal bit:
-----------
This program is shareware. To legally use this program after a ten day
evaluation period please send US$10 (or Australian $15) to:
John MacLean
2 Grant Place
St Ives, NSW, 2075
AUSTRALIA
As many people have asked, I have no problem cashing US$ checks.
Please include your name and address so I can keep track of registered users.
For those that have previously sent in their shareware fees, there is no
upgrade fee, and thankyou for your early support.
Informal Bit:
-------------
This program, particularly version 2.0, represents a lot of my time and
energy. If you think my efforts were worthwhile, let me know by sending
in your shareware fees.
I would also really appreciate any suggestions for improvements or
encouragements to be sent to the same address. I'm particularly interested
to hear from //e and //c users, as I don't own a //e or //c (anymore), and
I don't know if my efforts so far, or any possible future efforts for //e
and //c users, are worthwhile.
I know its a pain to write a letter, but if you would like something changed
I'll probably do it - but I need to know about it. Many of the changes in
version 2.0 were in response to user suggestions.
I have received a number of disks in the mail asking if I could get them
going and return the disk to them.
Although I enjoy the spirit of the Apple // community, my time (and money)
is valuable to me.
If you would like me to look at particular disks that don't seem to work,
I'm quite happy to, but please send an additional US$10 (Australian $15) to
cover my time, a 3.5" disk, and postage from Australia.
Finally, I have access to the internet at:
johnmac@fawlty.towers.oz.au
and regularly read comp.sys.apple2 if anyone wants to contact me.
----------------------------------------------------------------------------
Requirements:
-------------
To use DOS 3.3 launcher, you will need either: a ROM1 or ROM3 GS, a
//c or //c+, or a 128K enhanced //e. You will also need a 3.5" disk drive
or hard disk, and an appropriate program launcher such as the Finder
on the GS or ProSel on a //e or //c. Finally, you will need a 5.25" disk
drive and some old DOS 3.3 software.
For those users who no longer have a 5.25" drive available, you may like
to try out DOS 3.3 Launcher with one of my old games, KEY BORED, which
is included with this software.
----------------------------------------------------------------------------
//e and //c Installation:
-------------------------
You simply:
1) Create a directory called DOS3.3 in the root directory of your hard disk.
2) Copy the file DOS3.3.LAUNCHER into this directory.
3) Copy all the remaining files except DOS3.3.COPIER and DOS3.3.ICONS into
this this directory.
4) Rename the file DOS3.3.COPIEREC to DOS3.3.COPIER on your hard disk.
All of this steps can be done using a file copying program such as Copy II
Plus.
GS Installation:
----------------
You simply:
1) Copy the DOS3.3.ICONS to your ICON directory.
2) Create a directory called DOS3.3 in the root directory of your hard disk.
3) Copy the remaining files except DOS3.3.COPIEREC into this directory.
All of these steps can be done using the Finder under System 6.0, or by
a file copying program such as Copy II Plus.
----------------------------------------------------------------------------
Copying DOS 3.3 Programs To Your Hard Disk:
-------------------------------------------
There are two options for copying DOS 3.3 programs to your hard disk:
The first is only appropriate for single file DOS 3.3 programs that do not
access the disk once they are loaded into memory. Many old arcade style
games fall into this category. These files can simply be copied from a
DOS 3.3 disk onto a ProDOS disk, and then have their launch options set.
They can then be launched by DOS 3.3 Launcher, which simply loads the
files into memory and executes them.
The second option involves converting one or more disks into a large file
on your hard disk. Any disk that uses a standard RWTS (Read/Write
Track/Sector) routine can be copied in this manner. This includes not only
DOS 3.3 disks, but also many old games which use a standard RWTS, but are
not actually DOS 3.3. They can then be launched by DOS 3.3 Launcher, which
"boots" the large file directly from your hard disk.
These two options are further explained in the following sections:
Converting DOS 3.3 Files:
-------------------------
Single DOS 3.3 binary files can be copied to ProDOS using the Finder in
System 6.0 (on the GS), or by programs such as Copy II Plus.
If you are using the Finder under System 6.0, you need to have both the
5.25" driver and the DOS 3.3 FST installed.
You then need to set the launch options using the DOS3.3.COPIER program.
Although there are different versions of this program for GS users, and
for //e and //c users, the procedure is basically the same for all users.
On a //e or //c, you need to:
- Select the "Set Launch Options" option from the main menu.
- Enter the full pathname of the directory where the DOS 3.3 program is
stored on your hard disk. The associated volume must be online, and the
directory must already exist before you will be allowed to proceed.
- Enter the filename of the DOS 3.3 program. This filename must comply with
ProDOS file naming conventions (ie: 15 alpha-numeric characters, no spaces),
and must already exist.
- Select the appropriate launch options. For more information on launch
options see the following section on "Launch Options".
On a GS, you need to:
- Select the "Set Launch Options" option from the file menu.
- Select the DOS 3.3 program to convert through the standard file dialog box.
- Select the appropriate launch options. For more information on launch
options see the following section on "Launch Options".
Converting DOS 3.3 Disks:
-------------------------
Disks are copied and converted using the DOS3.3.COPIER program. Although
there are different versions of this program for GS users, and for //e and
//c users, the procedure is basically the same for all users.
On a //e or //c you need to:
- Select the "Copy Disks" option from the main menu.
- Select the number of disk surfaces you wish to copy into a single file
on your hard disk. You can copy up to 2 disk surfaces into a single file.
- Select the slot number of your 5.25" drive.
- Select the drive number of your 5.25" drive.
- Enter the full pathname of the directory where you want to store the
DOS 3.3 program on your hard disk. The associated volume must be online,
and the directory must already exist before you will be allowed to proceed.
- Enter a filename for the DOS 3.3 program. This filename must comply with
ProDOS file naming conventions (ie: 15 alpha-numeric characters, no spaces).
If this file already exists it will be deleted.
- Select the appropriate launch options. For more information on launch
options see the section on "Launch Options".
After entering all of this information, you will be prompted to insert each
disk in turn as they are copied to your hard disk.
On the GS, you need to:
- Select the "Copy Disks" option from the file menu.
- Select the directory in which you want to store the DOS 3.3 program from
the list box.
- Enter a filename for the DOS 3.3 program into the edit box. This filename
must comply with ProDOS file naming conventions (ie: 15 alpha-numeric
characters, no spaces).
- Select the number of disk surfaces you wish to copy into a single file
on your hard disk. You can copy up to 16 disk surfaces into a single file.
- Select the appropriate launch options at the bottom of the dialog box.
For more information on launch options see the section on "Launch Options".
When you press OK, you will be prompted to insert each disk in turn as they
are copied to your hard disk.
The DOS3.3.COPIER program assumes you will be using the first available 5.25"
disk drive to perform the copy.
Multiple Disk Surfaces:
-----------------------
When you copy multiple disk surfaces into a single file, these disk surfaces
are accessed as different drives when the program is launched.
The first surface is accessed as slot 6, drive 1, and the second surface is
accessed as slot 6, drive 2.
Only the GS version allows more than 2 disks to be copied, as it also has
the capability to swap "disks". For more information on swapping "disks"
see the section on the DOS 3.3 Launcher CDA.
Launch Options:
---------------
There are several options which take effect when a program is launched.
These are as follows:
Automatically slowing down to 1Mhz:
Many DOS 3.3 programs (mainly games) assume a 1Mhz system, and simply run
too fast to use on faster systems. When this launch option is enabled, the
program slows down to 1Mhz automatically on launch, and returns the system
to its faster speed before returning to the program launcher. //c owners
should read the special note for //c owners in the technical information
section.
Automatically turning off keyboard buffering (GS only):
Many DOS 3.3 programs (mainly games) assume there is no keyboard buffering,
and are unusable on a GS with keyboard buffering enabled. When this option
is enabled the program disables keyboard buffering on launch, and returns
it to its previous setting before returning to the program launcher.
Launching DOS 3.3 Programs From The Finder (GS Only):
-----------------------------------------------------
If you have properly installed DOS 3.3 Launcher, your DOS 3.3 programs
should appear with DOS 3.3 icons when viewed through the Finder.
To launch them, you simply double click on them, which launches them
via ProDOS 8.
Launching DOS 3.3 Programs From ProSel (//e, //c, IIGS):
----------------------------------------------------------
Menu entries for ProSel should be set up as follows:
Screen Title: A description of the DOS 3.3 program.
Prefix: The directory containing the DOS 3.3 program.
Application: The full pathname of the DOS 3.3 Launcher.
This should be /HD/DOS3.3/DOS3.3.LAUNCHER,
where HD is the name of your hard disk volume.
Startup: The full pathname of the DOS 3.3 program.
Launching DOS 3.3 Programs From Other Launchers:
------------------------------------------------
Any launcher that supports the ProDOS 8 startup protocol (ie: can make
applications automatically open a data file) can be used to launch DOS 3.3
programs via DOS 3.3 Launcher.
The general rule is that the program to execute is DOS3.3.LAUNCHER, and
the data file is the DOS 3.3 program stored on your hard disk.
Quitting:
---------
On a //e or //c the only way to quit is to press control-reset.
The reset vector is set up to restore ProDOS 8, and to return you to
the previous application. The reset vector is set up this way on launch,
and also on every access to the disk. This will allow you to return to your
program launcher from most, but not all, DOS 3.3 programs.
Some DOS 3.3 programs modify the reset vector themselves, and if this is
done after the last disk access, control-reset will not return you to your
previous application.
On the GS you also have the option of quitting via the CDA. To do this
just select the DOS 3.3 Launcher CDA, hilite "Return To Previous Application",
press the right or left arrow key (which will change the "No" to a "Yes"), and
then press return. When you quit from the CDA main menu, you will be returned
to your program launcher. The CDA is the recommended way of quitting DOS 3.3
programs, as it will work with almost all DOS 3.3 programs.
When you quit, the launch options (system speed and keyboard buffering) will
be restored to their previous settings.
The DOS 3.3 Launcher GS Classic Desk Accessory (CDA):
-----------------------------------------------------
Don't go looking for the DOS 3.3 Launcher CDA on disk - it is part of the
DOS3.3.LAUNCHER program. It is installed automatically by the launcher
whenever a program is launched, and removed before returning to the previous
application. This means it does not clutter up your CDA menu when its not
needed.
When the CDA is selected, it indicates how many "disks" are in the DOS 3.3
program that is currently being run, and whether the program is read-only,
or read/write. This information cannot be modified.
The CDA gives you the option of returning to the previous application,
which will usually be your program launcher. This takes affect when you
quit from the CDA main menu.
If there are two or more disks in the DOS 3.3 program currently running,
you will also have the option of "swapping disks" in each of the two drives:
"Slot 6, drive 1", and "Slot 6, drive 2". These are pseudo drives only,
and bear no relationship with physical drives you may have connected in
slot 6.
----------------------------------------------------------------------------
About Key Bored:
----------------
Key Bored is a program I wrote about ten years ago on my ][+. It is
distributed as part of the DOS 3.3 Launcher package so you can see how
things work without pulling out your 5.25" disks.
----------------------------------------------------------------------------
Technical Information:
---------------------
Write Protecting Disk Images:
-----------------------------
DOS 3.3 disk images stored on your hard disk can be "write protected"
simply by locking the file.
Unlocking the file will "write-enable" the disk again.
See also the section below on sparse files.
Most disk utilities such as the Finder and Copy II Plus can be used to
lock and unlock files.
Sparse Files:
-------------
Sparse files are files in which some parts of the file are known to
contain all zeroes, and do not occupy disk space.
When these areas of the file are read back, ProDOS automatically returns
the appropriate number of zeroes. When new (non-zero) data is written to
these areas of the file, ProDOS allocates more disk space before actually
writing out the data.
Sparse files represent a problem for DOS 3.3 Launcher, because it bypasses
ProDOS and accesses your hard disk directly. DOS 3.3 Launcher is capable
of detecting reads on sparse files and returning the appropriate number
of zeroes, however, it cannot allocate disk space on writes to sparse files.
Because of this, when DOS 3.3 Launcher launches a disk image it checks to
see if the file is sparse, and if it is, the disk is launched as read only,
regardless of whether the file is locked or not.
When disks are converted to files by the DOS 3.3 copier program, the
files produced will be non-sparse, and they can therefore be written
to (provided they are not locked). However, some (if not all) GS copying
programs will produce a sparse file when a non-sparse file is copied.
This effectively means that moving a file can change it from being
read/write, to being read only. If this happens to you, it is possible
to convert the sparse file to a non-sparse file again through an option
in the GS DOS 3.3 copier program.
Filetypes and Auxtypes:
-----------------------
DOS 3.3 Launcher uses the "user" filetypes: $F1, $F2, $F3, and $F4.
They have the following meaning:
$F1 - Slow down to 1Mhz; Turn off keyboard buffering.
$F2 - Do not slow down to 1Mhz; Turn off keyboard buffering.
$F3 - Slow down to 1Mhz; Do not turn off keyboard buffering.
$F4 - Do not slow down to 1Mhz; Do not turn off keyboard buffering.
The auxtype is zero for all disk images, and non-zero for single load files.
For single load files, the auxtype indicates the load address in memory.
File Systems:
-------------
DOS 3.3 Launcher only works when DOS 3.3 programs are stored on the ProDOS
file system. Since the launcher is a ProDOS 8 program, it is not possible
to access other file systems, even on the GS via the FSTs in System 6.0.
Resource Forks:
---------------
If you are using DOS 3.3 Launcher on a GS, DO NOT create resource forks
on DOS 3.3 programs. DOS 3.3 Launcher does not know anything about resource
forks, and may not like them very much.
Memory Usage:
-------------
DOS 3.3 Launcher saves ProDOS 8 in auxiliary memory when a DOS 3.3 program
is launched. It also uses auxiliary memory for its quit code, and for tables
used by the RWTS routine. This means that most DOS 3.3 programs that use
auxiliary memory will not work with DOS 3.3 Launcher. However, DOS 3.3
Launcher does not use the portion of auxiliary memory required for double
high resolution graphics, so programs that only use auxiliary memory for this
purpose should work OK.
/RAM and Other RAM Drives:
--------------------------
The memory used by /RAM (the RAM drive available in auxiliary memory in
some versions of ProDOS) will be overwritten by DOS 3.3 Launcher.
You will need to re-initialise /RAM to make it useable after launching a
program via DOS 3.3 launcher. /RAM5 on the GS, and other slot based RAM
drives are not affected by DOS 3.3 Launcher.
Disk Partitions:
----------------
DOS 3.3 Launcher uses the ProDOS firmware entry point at $CN00 + ($CNFF), so
it will only work with up to two hard disk partitions per slot.
Modified DOS 3.3:
-----------------
DOS 3.3 Launcher will work with most modified (ie: fast) versions of DOS 3.3,
however, it will not work with versions of DOS 3.3 that have been modified
to load into the language card.
Special Note For //c Owners:
----------------------------
The following problem is known to exist when running DOS 3.3 Launcher on
a //c without a zip chip installed:
If the launch option to automatically slow down to 1MHz is selected, some
programs which make use of hi-res graphics can have colors affected. In
particular, oranges can appear green, and blues can appear purple.
It is therefore not recommended for //c users to select this launch option
unless a zip chip is installed.
----------------------------------------------------------------------------
Revision History:
-----------------
Version 1.0:
------------
Version 1.0 was the first released version.
It worked.
Version 1.1:
------------
Version 1.1 fixed a major bug in DOS3.3.COPIER which caused certain errors
not to be detected when copying disks to your hard drive.
This version has seen the widest distribution to date.
Note that the version number displayed on launch of DOS 3.3 programs still
appeared to be 1.0.
You had version 1.1 if the about box in the DOS3.3.COPIER program indicated
it was version 1.1.
Version 1.2:
------------
Version 1.2 has the additional configuration option of turning keyboard
buffering off automatically on launch (and restoring it on quit).
Many people requested this because keyboard buffering is a pain with
some old games.
It also uses documented calls to slow down to normal speed, rather than
accessing softswitches directly.
This makes things behave much more sensibly when you leave the control panel.
Version 1.3:
------------
The following were done on request from users:
- Keyboard options were added to the DOS3.3.COPIER program.
- The documentation in this READ.ME file was improved (particularly in
regard to copying files and disks, the System 6.0 DOS 3.3 FST and 5.25"
driver, and the operation of the CDA).
- The reset vector is now directed at the quit code - this means that
it is now possible to reset out of programs that turn off interrupts.
- When converting disks, a check is performed for an appropriate drive
(and installation of the 5.25" driver) before any work is done.
- A test launch option was added to the copier program.
- It now uses the standard ProDOS 8 launch facility, rather than using
the message center. This should enable it to work with launchers other
than the Finder.
I also changed some zero page locations used by the RWTS routine.
I was saving/restoring these locations, and quite a few programs were
expecting them to get clobbered by the RWTS.
The result in English is that quite a few programs that went really close
to working with previous versions, now work correctly.
Version 2.0:
------------
Version 2.0 is a complete re-write with the following enhancements:
- When launching disk images, both reads and writes from disk work directly
from your hard disk. Changes are actually written to your hard disk, and not
just to memory as they are in version 1.3.
- The launcher itself (not the copying program) now uses 8-bit Apple //
facilities only (without loss of functionality).
This means that Apple //e and //c owners with hard disks are able to make
use of DOS 3.3 Launcher, through their favourite program launcher.
Quiting back to the launcher is by control-reset only on an 8-bit
Apple //, but the CDA option is still available to GS owners.
- The CDA now allows you to dynamically change which "disk" is in which
"drive". This allow you to run software that prompts you to insert disks
in particular drives.
- It is now possible to launch "master" disks (master disks are really old
DOS 3.3 disks where DOS is loaded initially into low memory, and then
relocated to an appropriate area of memory depending on how much memory is
available). Many users were previously confused because what they thought
was a standard DOS 3.3 disk could not be launched by DOS 3.3 Launcher.
The Future:
-----------
I still feel there is a lot of room for improvement in DOS 3.3 Launcher.
Some of the following changes come to mind:
- Automatic handling of sparse files to save disk space and simplify
operation. The copier programs would always create sparse files, and
only the lock/unlock status would control whether the disk image was
write protected.
- Adding a utility to copy files between DOS 3.3 disk images and ProDOS.
- Adding a utility to allow //e and //c users to dynamically swap disks.
This would give //e and //c users almost the same functionality as IIGS
users [If anyone has any bright ideas on how this could be done, please
let me know].
- Support for other accelerators [If you have the technical information
for an accelerator that is not currently supported (and you own one),
please send this information to me].