This is a slightly revised copy of the Executor 2 manual that was written in 1996. This manual has many deficiencies, including:
Previous to February 28th 2002, the material in this document was part of the 32 page mini-manual shipped with Executor 2.0. Now that it is online, the documentation will be brought up to date. ARDI is currently undermanned, but each time a question is answered via e-mail or phone, ARDI will make some effort to update the documentation. ARDI anticipates hiring a full-time technical writer, but not just yet.
Thank you for licensing Executor 2. Please review the Executor 2 license agreement printed on the back of this manual.
Executor bridges the gap between Macintoshes and PCs, allowing your PC not only to read and write Macintosh files but to run many Macintosh applications. With Executor you can use Macintosh high-density floppies and CDs. You can also create simulated Macintosh volumes on your PC to hold Macintosh applications. If your PC has a SCSI adapter, it can even read and write external Macintosh hard drives. Executor 2 is the first mainstream release of Executor.
Most PCs run the DOS or Windows operating system, so this manual is written primarily from an Executor/DOS user's perspective. Most material contained in this manual will also apply to people running the less common Linux operating system. If you do not know what Linux is, then you can comfortably ignore any mention of Executor/Linux. The end of this manual contains a chapter of Linux specific information. If you're using either of those two operating systems, please be sure to read the relevant operating system specific chapter in addition to reading the rest of this manual.
Executor 2 uses no software written by Apple Computer, Inc. That means Executor 2 will not run the Macintosh Finder. Because ARDI has only rewritten a subset of the MacOS, Executor 2 has other limitations, including a lack of support for serial ports and for networking. Executor/DOS can't print to any printer except a PostScript printer, although it can print to a postscript file. Executor/DOS and Executor/Linux have only limited sound support. System 7 support is still somewhat limited, and some Macintosh features (QuickTime, INITs, CDEVs, and anything from System 7.5) are not supported. Hardware limitations of the PC floppy controller prevent the use of 800K floppies.
Within these restrictions, though, Executor should run many, but not all, of your Macintosh applications. The web site http://www.ardi.com/ contains a compatibility database that can help point out which Macintosh applications run under Executor 2 and what, if any, problems they may have when running under Executor 2.
Executor 2 emulates a 68LC040-based Macintosh. The 68LC040 CPU (used in the Quadra 610, for example) doesn't have a built-in floating point unit. As such, applications that try to directly manipulate the CPU's floating point unit will fail, just as they would on a Quadra 610. Executor 2 does not emulate a PowerMac and cannot run PowerMac-only applications.
Executor/DOS runs under DOS 6.x, Windows 3.x, Windows95, Windows NT 4.x and OS/2 Warp.
Executor/DOS 2 requires 10,314,455 bytes of free hard disk space to install. After verifying that you have sufficient disk space free, insert the Executor 2 CD-ROM into your CD-ROM drive. If you're using an operating system with a graphical user interface, find the CD-ROM drive, double-click to open it, then double click on the icon labeled install. If you're using DOS, you'll need to know the drive letter that DOS assigns to your CD-ROM drive; then you'll need to run the install program from your command line. For example, if DOS assigns D: to your CD-ROM drive, type
D:\install
to start the installer program.
By default, the installation program will use "C:\EXECUTOR" as the installation directory. If you want to change the installation directory, you can use option 1 to do so. When you're ready to begin the installation, select option 2 to begin. Installation time varies with CD-ROM speed and processor speed, but an entry level Pentium should be able to install Executor 2 within three minutes.
If you're running under a windowing system such as Windows95, Windows 3.x, or OS/2 Warp, then you may also want to create an icon to represent Executor in your graphical interface. Consult your operating system's manual for instructions, or read one of the tips files from the Executor 2 CD-ROM. The tips files are in the \DOS\EXTRA\DOCS directory and are named W95_TIPS.TXT, W3X_TIPS.TXT and OS2_TIPS.TXT.
After installation, start Executor 2 by double-clicking on the Executor icon or by using the command line. If you installed Executor in the default installation directory, the command that will start Executor 2 is
C:\EXECUTOR\EXECUTOR
It's a little confusing because Executor is the name of the directory that contains Executor and its auxiliary files as well as the name of the application, which is why Executor appears twice in the above command line.
The first time you run Executor 2, you'll be prompted for your registration information. Enter your name, organization (if any), serial number, and authorization key. You'll find your serial number and authorization key on the registration card enclosed with the CD.
Since Apple doesn't yet license MacOS to emulator makers, ARDI had to re-implement the Macintosh OS and Toolbox from scratch. One of the consequences of this reimplementation is that Apple's Finder and operating system extensions are not compatible with Executor 2. You can't install them on top of Executor 2, although this capability is planned for a later release.
Executor 2 has a substitute "Finder" called Browser. Browser's interface is different from Apple's Finder interface.
The PC keyboard is a bit different from the keyboard of a Macintosh. The PC has one key the Macintosh doesn't have, the Alt key, while the Macintosh has Command and Option keys which aren't found on the PC. Executor solves this by using the left Alt key as the Command key and the right Alt key as the Option key.
Each time you start Executor, the Browser will be run. Browser's interface is a lot like that of a real Macintosh; it consists chiefly of an area into which you can open windows. These windows can contain files and folders.
In addition to the area with the windows, Browser's interface includes two bands across the top of the screen. The top-most band is the menu-bar. Almost all Macintosh applications have a menu-bar. The larger, gray, band is specific to the browser. It's called the hot-band, and it contains icons.
Clicking on a volume (filing cabinet icon), folder, application or document will select it but will not actually open it or run it. All volumes are represented by filing cabinets, and all folders are represented by the same folder icon, but applications have their own unique icons. Documents that were created by an application that Executor knows about also have their own unique icons. Documents that were created by an application that Executor hasn't seen or has forgotten are represented by a circle with a question mark. Unlike the Macintosh Finder, which has a good memory, Executor only remembers the icons for applications that are in currently opened windows or are on the hot-band.
Double-clicking on a volume or folder will open it into a window (create a new window displaying its contents). Double-clicking on a non-question-mark document icon will open the document by running the application which created it. Double-clicking on an application's icon will run the application.
Each window has a bar across the top which shows its status. This bar contains the name of the volume or folder it represents. When the window is not active, the name will be gray and the bar itself will be solid white.
When the window is active, the name is black. The bar itself will be gray, and there will be a small control box on each side of the bar. The left box closes the window. The right box toggles the window between full-screen and initial size.
If there is more to display in a window than will fit, there will also be a scroll bar along the right side of each window. If all the icons in a window can be displayed without needing extra room in the window, the place that would normally hold the scroll bar will be empty (white). When the scroll bar is present, the up and down arrows let you scroll through the window's contents.
To move a file or folder from one location to another, open windows for both the source and the destination and drag the file/folder's icon from one window to the other. Executor will move the file from one location to another within a single volume. If you drag something from one volume to another (such as from a CD to your hard drive, or from your hard drive to a floppy disk), the Browser will actually create a copy instead.
If you want the Browser to create another copy of something on your hard drive, you can duplicate the item using the Duplicate command under the File menu.
The white band across the very top of the screen is the menu bar, which contains pull-down menus. Many of the menus let you work with an item you've selected. Pull-down menus in Executor are accessed by dragging rather than by clicking as in some systems. To use them, hold the mouse button down on the menu header and drag downward until the selection you want is highlighted, then release the mouse. The menu that was under the mouse when you released it will then be used.
As on a real Macintosh, you can use command key equivalents to perform many tasks that would normally require a menu choice. For example, you can create a new folder with Cmd-N (holding down the command key while pressing the letter "N").
Command key equivalents can be found in the pull-down menus. For instance, when you're running an application and pull down the File menu, you'll see something that looks like a cloverleaf and the letter "Q" next to the Quit option. This tells you that you can also use Cmd-Q to quit an application. You can learn many other keyboard shortcuts from the menus.
The browser has a shortcut that isn't listed in a pull-down menu. You can delete a file or folder by selecting it and then pressing the delete key instead of selecting Delete from the File menu. Learning this shortcut is one of your rewards for reading this manual.
The gray ribbon across the top of the screen (beneath the menu bar) is the hot-band, where you can keep the applications, documents, and other files which you access frequently. It's controlled by the set of six small buttons in the upper-left-hand corner of the screen.
Clicking on a button will bring a particular group of icons into view in the hot-band. The Volumes group includes your simulated Macintosh volumes, your DOS drives and any floppies or CDs you have loaded.
To add an item to the hot-band, use the mouse to drag its icon there and it will be installed into the appropriate view of the band. It will still be visible in its folder as well; the hot-band icon is just a shortcut. You can also install desk accessories and bitmapped fonts by dragging them to the hot-band. Beware: desk accessories don't work particularly well under Executor 2, and it's hard to deinstall bitmapped fonts once you've put them in the hot-band.
Executor comes with some pre-installed demos which can help you learn these techniques. Two of them are Tex-Edit, a simple text editor, and a demo of Oh No! More Lemmings for the Macintosh. They can be found in the Applications view of the hot-band or in the shareware or demoware folder.
In order to install additional Macintosh software, it's important to understand some of the differences between the Macintosh and the PC filesystems. Macintoshes and PCs store files in radically different ways. These differences make it difficult to even store Macintosh files on a non-Macintosh, much less to use them there.
DOS uses an "eight-dot-three" naming system, with eight characters for the file's name, a period, and a three-character extension to indicate what type of file it is. Macintoshes not only support more flexible filenames than DOS's eight-dot-three, but also have two sections for each file: an unstructured section called the data fork and a structured section called the resource fork.
In addition to a filename and the two forks mentioned above, each Macintosh file has associated with it two four-character tags. These tags are known as the File Creator and File Type. These constants identify which application created the file and what format the file is in. In part these constants serve the same purpose as the three-letter file extensions on a DOS system. As an example, a Macintosh file with a File Type of TEXT indicates a simple text file in the same way the ".txt" file extension does under DOS. Although each Macintosh file has a File Creator and File Type associated with it, that information is not part of the filename.
Unless both of these tags and both forks of the file can be preserved on the non-Macintosh system, Executor will have trouble working with the files. In fact, if you use something other than Executor to transfer files to a PC and then transfer them back to a real Macintosh, the Macintosh will also have trouble if the File Type, File Creator or one of the two forks gets lost in the transfer.
Executor provides two ways to store Macintosh files, each with advantages and disadvantages. One option is to use an HFV, which is a single file that simulates a Macintosh volume. Each Macintosh volume can contain many files and folders, so using an HFV is like having a virtual Macintosh drive that only Executor can access. When Executor is installed, the HFV "exsystem.hfv" is created. From DOS it appears to be a single file, but from within Executor it appears to be the entire "System:" volume.
Alternately, you can choose to use two DOS files for each Macintosh file and leave these files in the DOS filesystem. If you do this, the data fork will go into one file and all the other information (including the File Type, the File Creator and the resource fork) will go into the other. The first character of the filename is then used to mark the difference between the two (% is prepended to the name of the file that contains the resource fork and other information).
The advantage to using two files for each Macintosh file is that there is no wasted space. The forks grow and shrink separately, and each file is just as large as it needs to be. The chief disadvantage under DOS, OS/2, and Windows 3.x is that Macintosh files will be forced to conform to the DOS eight-dot-three naming convention. In fact, because a "%" is prepended to one of the two forks, you're actually forced to conform to a seven-dot-three naming convention. Executor has support for long filenames under Windows95, but other DOS-capable systems will be limited by the seven-dot-three rule.
As an example of the reason for the "seven-dot-three" naming convention, consider two Macintosh files, one called librarya and the other libraryb. If both are stored as pairs of DOS files, Executor will not be able to tell the difference between the %library which went with librarya and the %library which went with libraryb. That's because although "librarya" and "libraryb" each contain eight characters, "%librarya" and "%libraryb" both contain nine characters, so DOS truncates those names to "%library" in both cases. That truncation confuses Executor.
Another disadvantage is that Executor may write file and directory names containing characters such as spaces, which are fine in Macintosh names but are hard to work with in other systems. Files or directories whose filenames contain special characters require special measures to modify or remove.
The advantages to using an HFV, which is a single file that simulates a Macintosh volume, are that no information is lost in the filenames and that it is easy to group related Macintosh applications and folders into logical subgroups. A disadvantage is that you may be wasting disk space. If you make a simulated Macintosh volume 5 MB in size and put only 1 MB of Macintosh files in it, you're still using 5 MB of your disk space. Another disadvantage is that only Executor will be able to access the files and folders that are in the HFV. DOS and Windows will only see the HFV file itself. They will not be able to see the contents of the HFV.
Executor can read and write Macintosh high-density formatted floppy disks. No amount of software can allow your PC to read or write 800K Macintosh floppy disks because Apple used a variable speed encoding system which PC floppy-drive controllers don't support. Beware: if you put a high density floppy in a very old Macintosh, the Macintosh will format the high density floppy as an 800K floppy and you still won't be able to use the floppy on your PC.
Macintosh floppies and CDs can be inserted into your drives either before or after you start Executor. If you insert them after starting, you will have to tell Executor that you have inserted a disk -- PCs don't detect this automatically; Macintoshes do. You can do this either by selecting "Check for Disk" from the File menu or with the keyboard shortcut Cmd-Shift-2. The disk will appear as an icon in the volumes view of the hot-band. When you want to eject the disk, select it in the Volumes view of the hot-band and choose "Eject Disk" from the File menu. Executor will bring up a dialog box that confirms that your floppy or CD-ROM has been ejected. If you do not get confirmation, something has gone wrong and Executor will continue to think that the floppy or CD-ROM is in its drive. Always eject the disk via the menu and receive confirmation that Executor is aware of your actions before removing the disk physically. If you don't do this, Executor can get very confused, which can lead to corrupt data or missing data on a floppy disk.
DOS formatted floppies and DOS formatted CDs are treated as fixed media. If you have a DOS floppy or CD in the drive when you start Executor, then it is treated as a fixed drive for the duration of that Executor session. It should not be removed or replaced until you quit Executor.
Executor can format high-density floppies in the Macintosh filesystem format, but it can't do low-level formatting. If a floppy is totally unformatted, then it can't be used with Executor until it's formatted. If it already contains a low-level DOS or Macintosh format, then Executor can imprint it with a blank Macintosh filesystem. If the disk is totally unformatted, you can work with it by first formatting it under DOS, then taking it out of the floppy drive before starting Executor. After you have started Executor, you can then put the DOS formatted floppy in the drive and instruct Executor to format the floppy, which will result in a Macintosh formatted floppy that you can then use under Executor.
The rules concerning when floppies need to be in floppy drives and when they don't are a little tricky until you get used to them. Keep this portion of the manual open when you first start using floppies under Executor.
To format a floppy, simply place the floppy in the disk drive and choose "Format Floppy" from the File menu. A dialog box will ask you for a name for the floppy volume, with "Untitled" being the default. Formatting takes several minutes, but once it's done you'll have a disk which can be used with a real Macintosh as well as with Executor.
In order to read Macintosh formatted CD-ROMs, Executor needs to be able to read raw CD-ROM sectors so it can interpret the Macintosh filesystem for itself. However, DOS, Windows and OS/2 don't necessarily make this easy.
When Executor/DOS starts up, it tries to determine whether there will be a problem reading raw CD-ROM sectors. It does this by looking to see if the Executor 2 CD-ROM is in any DOS drive, and if it is, it tries to read the raw sectors of that drive. If it's unable to read the raw sectors, Executor will bring up a dialog box that will tell you to read a particular file which describes what the problem most likely is and a likely solution.
After you've experimented with the demos, you'll want to install more Macintosh applications. The Executor CD-ROM contains many Macintosh applications in various formats which you can use to familiarize yourself with installation procedures.
When Macintosh applications are distributed on floppies or CD-ROMs, the distribution media often contains one or more compressed archives with a built-in installer. In these cases, if the distribution medium is a high-density floppy, or a CD-ROM, all you need to do is open the icon of the CD or floppy and run the installer application. Applications you get in this way will usually have documentation which will tell you exactly how to install them. Beware: some installation applications won't run under Executor even though the application itself will work; in that case, see INSTALL.TXT in the \DOS\EXTRA\DOCS directory of the Executor 2 CD-ROM for instructions on how to install these applications.
Some files from CDs and floppies, as well as those you download, will not have readily available documentation. You can often tell what to do with them by the names of the files themselves. If you copied (or downloaded) the file to a DOS machine, then the name may have been truncated to fit the DOS eight-dot-three standard; check the source to get the original name of the file. Many of them will be compressed in various formats described below.
A file ending with the suffix .sea is a self-extracting archive. These applications can be run with a double-click just like normal applications. When run, they expand themselves into the full-scale ready-to-use application. If you don't have documentation, there is no easy way to tell whether these files will allow you to choose where they install or whether they'll just expand themselves wherever they happen to be. To be safe, put the file where you want the eventual file or folder before expanding it. You can always move it later.
The included demoware utility StuffIt Expander decompresses most common compressed formats for Macintosh archives, including the two most common: StuffIt and Compact Pro. You can often identify these files by their suffixes of .sit and .cpt, but Macintosh files don't really need suffixes to identify them, so sometimes you'll find that various archives don't have suffixes. To use StuffIt Expander, just double-click on its icon in the hot-band and select "Expand" from the pull-down File menu. The "Drive" button will cycle through your simulated Macintosh volumes as well as your high-density floppies, CDs, and hard drives. When you find the compressed file you want, just select it and click on "expand."
StuffIt Expander can also decode files encoded in the BinHex 4.0 and BinHex 5.0 formats. The former encodes binary files in a text format, which is handy for sending applications through email or storing them on bulletin boards and ftp sites. The latter is also known as MacBinary format, and is a way of storing the multi-forked Macintosh files, as a single binary unit, so that they can be more easily stored on non-Macintosh machines. BinHex 4.0 archive names usually end in .hqx, while BinHex 5.0 names generally end with .bin or .Bin.
Because of the filesystem differences between the computer types, installing software you've downloaded often requires a few more steps than installing software from diskettes or CDs. PC software often only captures the data fork of the Macintosh file, ignoring the resource fork. If you try to download an executable Macintosh application with a PC, it probably won't work because the heart of a Macintosh application is always stored in the resource fork. You'll need to download these files in a format designed to accommodate non-Macintosh filesystems, such as BinHex or StuffIt.
A file with the filename suffix .hqx or .sit will probably be usable because those formats store all the information in the data fork. A file with the .sea suffix is technically an executable application, but you may be able to use it anyway with the aid of StuffIt Expander (see below).
When you first access a file which has lost its resource fork, Executor will create a resource fork and a File Creator and File Type. Executor's default is to assume that the file is a text file which was created on a Unix computer. If the file is anything other than a plain text file, then you can use the following procedure to change the File Creator and File Type accordingly. Beware: this won't restore the resource fork of the file. So if the file type is one that normally contains information in the resource fork, simply changing the File Creator and File Type won't be sufficient to render the file usable under Executor. Therefore, it's safest to transfer Mac files via Macintosh formatted floppies or via .hqx files.
1.) Click on the file's icon to select it.
2.) Choose Get Info from the File menu, or use the keyboard shortcut Cmd-I to bring up the application's information.
3.) Change the File Creator and File Type fields to the appropriate characters from FILETYPE.TXT in the \DOS\EXTRA\DOCS directory of the Executor 2 CD-ROM.
4.) Click the file's icon again, and it will transform into a non-question-mark icon, if the Browser recognizes the File Type and File Creator tags.
For a StuffIt archive, for example, you would change both Creator and Type to SIT! (it must be in all capital letters, and the exclamation point is important). For a .hqx file you won't need to change the creator and type at all because the BinHex 4.0 format actually encodes the binary data as text.
The StuffIt Expander application can also unpack many self-extracting archives, so you may be able to use StuffIt Expander to salvage some SEAs which have lost their resource forks. Treat the file ending in .sea as you would a .sit archive, by changing the file type and creator to SIT! and using StuffIt Expander to unpack it.
Remember, any file which should have information in the resource fork -- including any application -- cannot be fixed by changing the File Creator and File Type. Unless your PC software is unusually capable, you will need to restrict your downloading to archives. Most BBSes and ftp sites store their files in the BinHex 4.0 format, so hopefully you'll rarely encounter this limitation.
Executor uses specially formatted files called HFV (Hierarchical File Volume) files to simulate Macintosh hard drives. In your Executor directory you will see exsystem.hfv, which is a file containing the Macintosh "System:" volume you see in Executor. HFVs have exactly the same image format that a Macintosh hard drive has.
Any file in your Executor directory which ends in .hfv will automatically be recognized as a Macintosh volume by Executor. A large HFV of Macintosh demoware, freeware and shareware is included on the CD, but most HFV files will be created by you on your hard disk.
New HFVs are created from the command line rather than from within Executor. The makehfv utility provides an easy way to do this. The syntax is
makehfv DOS_name Mac_name size
An example would be
makehfv myvol "New Volume" 10m
This command will create a DOS file called myvol.hfv, which is 10 MB in size and will be the Macintosh volume "NewVolume" within Executor. If you want spaces in the Macintosh name, then you must enclose it in quotation marks. You don't need the quotes if you don't use spaces.
When Macintosh applications, running under Executor, try to print, Executor produces PostScript output. Hence, the PostScript output can only be printed directly if you have a PostScript-capable printer. Since most PC printers are not PostScript-capable, Executor routes its output to a PostScript file. The first time you print, the file will be named execout0.ps and will be located in the same directory as executor.exe. The next time you print, the file that contains the PostScript output will be named execout1.ps, then execout2.ps, etc.
You can then print this file on a PostScript printer, or you can use a PostScript-compatible printer driver to print it on your non-PostScript printer. A popular driver is Ghostscript. Ghostscript is free, but slightly tricky to install. There are also a few commercial applications which will let you print PostScript output on non-PostScript printers.
If you do have a PostScript-compatible printer, you can skip the creation of execout0.ps and print directly to the printer by using the "-printer" command line switch. e.g.
executor -printer lpt1
Most printers are lpt1, but you may need to change this to lpt2, lpt3, etc., as appropriate.
Executor has two different ways for you to set various options. A variety of command-line switches can be used to start Executor with various options, and there is a panel within Executor where you can associate specific options with specific applications being run under Executor. Some parameters can only be set from the command line, but parameters set from the Preferences Panel are the only ones which can be saved from session to session.
Executor has many command line switches. All command line switches begin with a leading dash ("-"). Some switches are specific to particular platforms, so to get a complete list of those available to you, type
executor -help > switches
at the command line prompt. This will place the output of "executor -help" in a file called "switches" which you can then read with any text editor.
Here are some of the most commonly used switches (switches are always lower-case):
-help Display a complete list of command line switches.
-info Display information about your system.
-size Specify the dimensions of Executor's screen (e.g.
"-size 800x600").
-printer Specify the file or printer to which PostScript output from printing should be sent (e.g., if you have a PostScript printer,
"-printer lpt1").
-pagesize Specify printer page size. The argument should be one of (letter, tabloid, ledger, legal, executive, a3, a4, a5, b4, b5) or widthxheight where width and height are in points (72 of them to an inch).
"-pagesize 792x612" is the only way to get Executor 2 to print in landscape mode.
-memory Specify the total amount of emulated memory. e.g., "executor -memory 5.5m" would make five and a half megabytes available to the virtual machine. Executor will require extra memory above and beyond this amount for other uses.
-desperate Run in "desperation mode". This will cause Executor to use as few system features as possible, which is handy for troubleshooting if Executor is having serious problems with your system.
The Preferences Panel is used to set specific options for particular applications. To bring up the Preferences Panel, type Cmd-Shift-5. Preferences Panel settings affect only the application which is running when you set them, while command line switches affect the state of Executor before any saved Preferences are retrieved. As such, saved Preferences Panel settings will override the command line switches with which Executor was started. When you click on the "Save" button within the Preferences Panel, Executor will write a configuration file that will be used to restore Executor to your saved preferences the next time the same application is run.
One of the most common reasons to use the Preferences Panel is to tell Executor 2 to pretend that it's emulating System 7 instead of System 6. This is needed to run some applications, but in general, you get better results when Executor emulates System 6. Therefore, the option of emulating System 7 requires you to explicitly turn it on. For example, if you run an application and the first thing it does is bring up a dialog box that says "This application requires System 7", you can then immediately type Cmd-Shift-5, change the System box to say "7.0", then click on the "Save" button. Then you can dismiss the dialog that is displaying the System 7 requirement, and the next time you run the application, Executor will pretend to be emulating System 7 and you should no longer get the "This application requires System 7" dialog.
Real Macintoshes are built in such a way that the video memory is always accessible to both the MacOS drawing routines and to the applications running on the Mac. Executor does not always have this luxury, and often video memory can only be accessed indirectly. In those circumstances, the drawing routines and the applications running under Executor are able to manipulate a virtual screen, then Executor copies the new portions of the virtual screen to the PC's real screen. This process works, but it introduces the question of exactly when Executor should copy from the virtual screen to the real screen. Two portions of the Preferences Panel address this question.
Normally (i.e. when "Screen Updates" is set to "Normal"), Executor only copies from the virtual screen to the real screen when the application is looking for input. Setting Screen Updates to "Animation" will tell Executor to redraw the screen every time the application makes a drawing request. This will slow Executor down, but is needed for some applications, notably games.
Some applications bypass drawing requests altogether and write directly to the screen. You can use the Refresh option to tell Executor to periodically check for these direct screen writes. Set Refresh to a small number specifying the number of 60ths of a second to wait between checks. In general, Refresh should be left on the default of 0 to avoid doing these checks. Executor usually will turn on Refresh when needed.
Neither Animation nor Refresh is needed if Executor can directly access the video memory, which is why Executor is much faster when you have a linearly mapped framebuffer.
The System box lets you set which version of the Macintosh operating system Executor will claim to emulate. The default is System 6.0.7 because Executor 2 supports the vast majority of System 6.0.7 routines. To run applications which require System 7, you will need to set System to 7 either here or on the command line. In general, try an application under System 6.0.7 emulation first and let it tell you if it needs System 7. Beware: Many applications will behave differently when they're running under System 7 and sometimes the different behavior will result in Executor 2 failing to run a given application when pretending to emulate System 7 even though the same application will run properly when Executor 2 is emulating System 6. Microsoft Word 5.x is an example of an application that will fail under Executor's System 7 but will run properly under Executor's System 6.
Executor 2's sound emulation is incomplete. As such, some applications will crash when trying to use sound under Executor 2. Therefore, Executor normally leaves Sound off. When applications ask to allocate sound resources and Executor's sound subsystem is turned off, Executor returns a "resource busy" error-code, and well behaved applications realize that they should run silently.
Setting Sound to "Pretend" will cause Executor to tell applications that it is producing sound, even though it actually isn't, which may be good enough to fool an application into running even when it would fail with Sound Off or Sound On. When Sound is "On," some Macintosh applications will be able to play sounds on your Sound-Blaster (or compatible) equipped PC. Sound support is preliminary, and using it may cause problems. If you're using sound with an application and have trouble, try turning the application's and Executor's sound off.
Number of Colors defines how many different colors can be present on the screen at a time. Executor will run in 256-color mode by default if you have Super VGA support, and that's the setting you'll usually want. Occasionally some applications require fewer colors in order to run. Scruffy ][ is an example of such an application.
When Newline Mapping is on, Executor 2 attempts to treat UNIX-style text files as though they were created on a Macintosh, by translating line-feeds to carriage returns on the fly, as an application reads the file in text mode. Newline Mapping should almost always be on.
An instruction cache is a portion of a CPU that remembers the contents of memory for potential future re-use. This allows the CPU to run faster. On some CPUs, when certain portions of memory are changed, the instruction cache needs to be flushed. Normally the MacOS flushes the instruction cache often, but Executor 2 uses heuristics to avoid unnecessary flushes. That allows Executor 2 to run faster, but conceivably an application might require Flush Cache Often to be set.
Direct Disk Access lets applications read and write raw floppy disk and hard disk sectors. The Browser needs this option enabled in order for it to be able to format floppies, since formatting a floppy consists of writing raw sectors to an unformatted floppy. In general, you don't want other applications able to write raw sectors to floppies or hard disks because by doing so they could damage the filesystem that is already on the floppy or hard disk.
When the Macintosh was still young, programmers were able to write applications in such a way that would cause the programs to fail on machines with 32-bits of addressing space, since the original Macintoshes only had 24-bits of addressing space. Since Executor emulates a machine with 32-bits of addressing space, such applications will fail under Executor. Executor tries to detect when an application may have this problem, and it issues a warning when it thinks the application you've just started might fit this category. However, Executor can be wrong, and those warning messages can get tiring. The No 32-bit Warnings option tells Executor to not warn you when it detects this condition in the application you're running.
The Font Substitution option doesn't do anything. Older versions of Executor 2 had a need for this option and nobody thought to remove it from the Preferences Panel after the need had passed. This turn of events escaped everyone's notice until this manual was being proofread.
Pretend Help, Pretend Edition, Pretend Script and Pretend Alias tell Executor to spoof the functions of the Help Manager, Edition Manager, Script Manager and Alias Manager. Executor doesn't support these managers, but if you turn on one of these options it will make Executor pretend to support the corresponding manager. Enabling some of these options may satisfy the requirements of an application that insists on having some combination of these managers available, thus allowing it to run. Executor doesn't actually implement these managers' functions, so you should generally leave these options off, since if an application thinks these managers are available, it may try to use unimplemented routines.
The text box at the bottom of the Preferences Panel allows you to store a brief comment with the settings that you save for a particular Macintosh application.
Preference Panel settings are stored in configuration files. Executor's configuration files have the suffix ".ecf", and are stored in the "configur" subdirectory in the same directory that contains executor.exe. The rest of this section provides some technical details of Executor's configuration files. In general, you don't need to know any of this information to use Executor, since the Preferences Panel is the best way to manipulate configuration files.
Configuration files are named after the File Creator of the application whose configuration information they store. However, because File Creators can contain unprintable characters, configuration file names are the hexadecimal representation of the ASCII characters that make up the File Creator.
Configuration files are simple files that you can edit with a text editor, although you should never have to. If you do, be careful because Executor isn't tolerant of malformed configuration files.
Executor expects certain files and directories to be in particular places. You can use environment variables to override some of these default locations. To change an environment variable, use the SET command.
set variable=new value
Be sure not to put a space before or after the equal sign. Below is a list of environment variable names, their default values under DOS and a brief description of what each variable controls. Slashes ("/") or backslashes ("\") are used to delimit DOS filesystem paths; colons (":") are used to delimit paths within a Macintosh volume, and semi-colons (";") are used to separate multiple arguments. A leading plus ("+") is replaced by the directory that contains executor.exe.
MacVolumes
+/exsystem.hfv;+
This variable tells Executor where it should look for Macintosh volumes. Directories listed in MacVolumes will automatically be scanned for HFVs. The volume which contains the System file must be first in any MacVolumes list, so the default is to explicitly list exsystem.hfv, then list the directory that contains executor.exe. As such, any HFV that you create in the same directory as executor.exe will automatically be recognized by Executor.
ConfigurationFolder
+/configur
The name of the directory Executor will search for configuration files.
SystemFolder
System:System Folder
The Macintosh folder which holds the special file called System. This file corresponds to the System file on a Macintosh and contains resources, such as fonts and cursors Executor needs. The default is the folder "System Folder" on the volume "System:". When Executor is installed, "System:" is created in exsystem.hfv.
PrintFolder
+
The directory where the PostScript output from printing should be created.
ScreenDumpFolder
+
When you type Cmd-Shift-3, Executor creates a TIFF file containing a dump of the Executor screen. It stores that .tif file in the directory specified by ScreenDumpFolder.
The Macintosh operating system has evolved over time. In the early days of the Macintosh, the majority of the operating system was stored in the file "System". Because of this, people identified the version of the operating system by the revision number for System. For example, System 4 was the first version of the Macintosh Operating System that supported color. The latest major release of the Classic MacOS is 9.x.
When applications run, they can query the operating system to find out what version it is. Because Executor 2 doesn't actually use Apple's Macintosh Operating System, there is no exact answer. By default, Executor 2 reports System 6.0.7, because most of the features present in System 6.0.7 have been built in to Executor 2.
However, some of the routines present in System 7.0 are also implemented in Executor 2, so telling Executor 2 to report that it's running System 7.0 makes sense at times. In fact, you can have Executor report any System version to the applications it's running, but since Executor implements almost no routines that were added after System 7.0, having Executor report that it's running something more recent than System 7.0 will only encourage applications to try to use routines that aren't supported.
To run an application which requires System 7, start Executor and call up the Preferences Panel with Cmd-Shift-5. Set the System setting to 7 and click OK. Don't save yet; these are just the Browser settings. Now start the application, call up the Preferences Panel again, and save it with the System 7 setting. After that, Executor will automatically invoke System 7 support whenever you run that application.
Beware: If you save Browser's preferences to be System 7, you're asking for trouble. When an application that doesn't have its own configuration file is run, it inherits its preferences from the Browser. When applications see that they're running under System 7, they're more likely to use routines that aren't supported, so Browser's default is to always run new programs in System 6.0.7 mode.
For Executor to run at full speed it needs memory and a way to quickly access the video screen. The "-info" option will tell you two important things.
The number of bytes of potentially useful physical DPMI memory is how much memory is left for Executor's use after Executor has already been loaded into memory. If "-info" reports that you have less than 3 MB of potentially useful physical DPMI memory, then Executor will probably run slowly since it won't have enough memory for all its needs and it will instead use your PC's disk drive to emulate memory. Emulating memory that way is much slower than using physical memory.
The "-info" command line option will also tell you whether or not Executor detects a VESA-compatible video driver, and if so, which VBE version the driver supports. Executor is fastest with a 2.0 VBE driver. If "-info" reports that you have a 1.x VBE version or doesn't report that you have a VESA-compatible driver at all, you should try SciTech Software's "SciTech Display Doctor" (SDD). SDD provides VBE 2.0 capability for dozens of popular video cards. It's a commercial product, so if it helps you out you'll need to license a copy from SciTech Software. You can find a trial version of SDD in the \DOS\EXTRA\SDD directory on the Executor 2 CD-ROM.
To make best make use of VBE 2.0 capability, you'll need to reboot your PC into DOS mode since Windows doesn't usually allow you to directly access video memory.
More extensive documentation is available on the CD in the directory
\DOS\EXTRA\DOCS
and in the DOCS subdirectory of the directory that contains executor.exe.
The file called problems.txt contains the most common problems and their solutions. The FAQ lists the most frequently asked questions and their answers. Long-time Executor user Ernst Oud has contributed ernstoud.txt, a thorough introduction to Executor from a DOS user's point of view which will probably be useful to users of other platforms as well. Instructions for installing hard-to-install applications are given in install.txt.
Some online documentation is available on our web site:
http://www.ardi.com/
Have your serial number handy in order to access the areas reserved for registered users. You must send in your registration card in order to be added to the list of people who can access this area.
There is a Usenet newsgroup, comp.emulators.mac.executor, for Executor-related discussion. This newsgroup is not formally affiliated with ARDI, but ARDI employees do participate in it.
If you have questions or problems which aren't addressed anywhere in the documentation, write to support@ardi.com or call ARDI at +1 505 766 9115. Tech support is available 9:00 AM - 5:00 PM Mountain Time. Again, have your serial number ready or include it in your email.
To install Executor/LINUX, you need to mount the Executor 2 CD-ROM as an ISO9660 filesystem. Run the "linux/install" script as root . The programs "executor" and "executor-svga" will be installed in the directory "/usr/local/bin". Additionally, the directory "/usr/local/lib/executor" will be created. You'll need to run each one once as root, so that your serial number and authorization key can be entered and stored.
"/usr/local/bin/executor" is an X application. It will try to connect to your X server, and bring up a virtual Macintosh in an X window. If your X server is running in 8 bit-per-pixel mode, Executor will try to share colors with other programs. This slows Executor down and causes Executor to use different colors than it would otherwise. The "-privatecmap" option tells Executor to allocate its own color map.
"/usr/local/bin/executor-svga" is an SVGAlib application. It will take over a virtual console and use your entire monitor as the virtual Macintosh. For video cards that are supported by SVGAlib, this version of Executor is significantly faster than the X version.
Because Linux supports long filenames, HFVs are less important to Executor/Linux then they are to Executor/DOS.
By default, Executor will examine "/dev/fd0" and "/dev/cdrom" to detect the presence of Macintosh formatted floppies or CD-ROMs. If you don't have permission to access those devices, you won't be able to use Macintosh formatted floppies or CD-ROMs. If you have a SCSI adapter in your PC, you can connect a Macintosh formatted external hard disk to your PC and use it with Executor/Linux. You'll need to specify the device name (e.g. "/dev/sdb") in the MacVolumes environment variable.
When you print from Executor/Linux, Executor /Linux will automatically send its output to a program called executor_filter, if it exists. You can create this by hand as a script to do whatever you want with the output, including filtering it through the Linux version of Ghostscript. If executor_filter doesn't exist, Executor/Linux sends its output to the lpr command. If your printer is PostScript-compatible, that's usually all you need.
Executor is written and copyrighted by Abacus Research and Development Inc. (ARDI). Executor is not sold, but is provided under this Software License Agreement. This license allows the licensee the use of this fully enabled version (commercial) of Executor after payment of the appropriate licensing fees to ARDI.
This fully enabled version (commercial) of Executor may be copied only for backup purposes. Licensee may not modify or create derivative works based on Executor or any part thereof.
Executor is licensed with a limited 30 day warranty. If you are dissatisfied with Executor during the first 30 days of this license, ARDI will, at the licensee's request, refund the license fee and terminate this license agreement. Licensee's remedy in the event of negligence or contractual breach by ARDI in connection with the creation, manufacture, marketing, distribution or licensing of Executor is strictly limited to the license fee paid by licensee.
In no event will ARDI be liable for indirect, special, incidental, or consequential damages resulting from the use of Executor, even if advised of the possibility of such damages.
Executor's limited 30 day warranty is the sole warranty provided by ARDI to Licensee. If Licensee uses the licensed software in a state which does not allow the exclusion or limitation of implied warranties or limitation of liabilities for incidental or consequential damages, then the limitations on warranties and exclusions of damages agreed upon by the parties to this license agreement shall be interpreted, to the extent permitted by the applicable state's law, to fulfill the agreement of the parties set forth herein.
This license is the entire agreement between Licensee and ARDI. If any provision of this License shall be held to be unenforceable, such holding shall not affect the enforceability of the remaining provisions. This license shall be governed by and construed under the laws of the State of New Mexico. Licensee agrees to bring any proceeding concerning this license before a court of the State of New Mexico or a Federal court located in the State of New Mexico.
This Software is licensed only with RESTRICTED RIGHTS.
For civilian agencies: The use, reproduction, or disclosure of this software is subject to restrictions as set forth in subparagraphs (a) through (d) of the Commercial Computer Software--Restricted Rights clause at 52.227-19 of the Federal Acquisition Regulations.
For Department of Defense agencies: The use, reproduction, or disclosure of this software by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013.
Copyright 1996-2002, Abacus Research and Development, Inc.
Executor and the ARDI logo are registered trademarks of Abacus Research and Development, Inc.
ARDI is a trademark of Abacus Research and Development, Inc.
Apple, AppleTalk, Macintosh and MacOS are registered trademarks of
Apple Computer, Inc. Finder, QuickDraw, QuickTime and System 7 are
trademarks of Apple Computer, Inc.