DOS 3.3 Launcher 2.2 - Copyright 1996 John MacLean -------------------------------------------------- ref. file http://apple2.org.za/gswv/a2zine/System/DOS33Launch.zip This file is included in DOS33Launch.zip . 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: ----------- Earlier versions of this program have been shareware. As of Version 2.2, John MacLean has now changed the status of Dos 3.3 Launcher to Freeware. Informal Bit: ------------- John MacLean has passed on the job of maintaining the Dos 3.3 Launcher source code to, me, Andrew Roughan. If you think my efforts were worthwhile, let me know by sending me an email message. I would also really appreciate any suggestions for improvements. I'm particularly interested to hear from //e and //c users, as I don't know if any possible future efforts for //e and //c users, are worthwhile. My email address is: posty@triode.apana.org.au --------------------------------------------------------------------------- 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 John's 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 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. --------------------------------------------------------------------------- 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. --------------------------------------------------------------------------- Launching Over AppleTalk: ------------------------- As of version 2.1, you can now launch both files and disks over AppleTalk networks. If you intend to make use of this feature, read the following notes: - Launching DOS 3.3 disk images over an AppleTalk networks is considerably slower than launching them from a local hard disk. - When a DOS 3.3 disk is launched over an AppleTalk network, ProDOS is kept in memory, which means that only programs that do not make use of the language card area of memory will work. --------------------------------------------------------------------------- About Key Bored: ---------------- Key Bored is a program John MacLean wrote about ten years ago on his ][+. 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. 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. Version 2.1: ------------ John Maclean has unfortunately decided to move on from the Apple II. Version 2.1 of Dos 3.3 Launcher was assembled from John's original source code by Andrew Roughan after consultation with John, and released to the usual places on the internet. - Added the ability to launch files resident on a network drive. Version 2.2: ------------ Andrew Roughan is now fully responisble for Dos 3.3 Launcher changes and releases. - Apple IIgs owners can now launch files from ProDOS 8 program launchers. Previous versions returned an "Out of memory" error when an invalid userID was used to request memory for the CDA. - A new error message was added to remind the user to use the full pathname to specify the file. - Dos 3.3 Launcher can now launch Apple II emulator disk 'Images' of Dos 3.3 compatible disks. These disk images are being made for use with projects discussed in the usenet newsgroup comp.emulators.apple2. Note: Dos 3.3 Launcher IS NOT an emulator and therefore can not be expected to launch all such disk images! Dos 3.3 Launcher can only launch disk images of disks which use Dos 3.3 (or minor variations). 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]. ---------------------------------------------------------------------------