NOTE: This file was written by an Executor user to help other Executor
users solve common problems.  ARDI has edited it slightly, but left it
essentially unchanged.  Enjoy!


GETTING STARTED WITH EXECUTOR
-----------------------------

"A bug is an undocumented feature. 
A bug becomes a feature by documenting it."

The author of this document had no previous knowledge about Macintosh
software and architecture before buying Executor. PC experience in
abundance but totally blank about the Mac world. Executor was bought
to fill this hole and fully lived up to its expectations.

Although Executor can be used without any previous Macintosh knowledge
(proof that this unique selling point for a Mac still holds true)
there are some facts that would have helped the author. Some of these
are described below; perhaps they will help you.

The original Macintosh was introduced in 1984 with the now famous 1984
Big Brother advertisements. It was followed by an enormous range of
machines. The original Motorola 68000 processor (comparable to an
8086) was followed by the 68020 (eq. 80286), 68030 (386DX) and 68040
(486SX/DX).  Executor emulates a 68LC040, which is a 68040 without a
floating point processor (the "LC" stands for "low cost").

Most of the Mac's success was not caused by its hardware but by its
software. The Mac was one of the very first systems using a Graphical
User Interface. It is this GUI that Executor emulates.

The Macintosh operating system comes with the strange name of
'System'. It has had a number of releases comparable to MS-DOS; it is
now in its 7th life and like a cat, it was its last; future versions
are called MacOS.  Although System 7 added a lot of new features,
Executor emulates a Mac running System 6.0.7; it is ARDI's intention
to make it possible some day that you will be able to use Apple's
System 7 on top of Executor.

Like Windows, System supports applications by giving them an
environment to run in. Interaction between the user and System is done
with a program called Finder; comparable to Program Manager within
Windows.  It is Finder that generates the metaphors of folders,
desktop, trash can and others. It is Finder that starts
applications. With Finder the user can rename, copy and delete files
and folders.

The original Finder enabled the user to run one application at the
time, MultiFinder, introduced with System 6, made it possible to start
several applications. Executor is a single-program-at-a-time type of
emulator.

ARDI is developing its own Finder substitute which will be more
integrated with Executor. Until then, the HFS_XFer program, described
in a separate chapter of this manual, is used to copy, delete and
rename files and folders.

System needs a harddisk with a number of pre-defined folders, one of
which is the System Folder. In it you will find a file called 'System'
which contains most of the Mac's operating System. On a real Mac also
the file 'Finder' will be found in this folder. The System Folder is
present on Executor's file system but it does not contain a Finder,
nor is ARDI's System file compatible with Apple's.  If you try to use
a Macintosh and replace Apple's System file with ARDI's, your
Macintosh will crash.  If you try to run Executor using Apple's System
file instead of ARDI's, Executor will crash.

This implies that although Executor emulates a Mac very well the first
impression is that it looks different because it lacks the important
Finder interface. Instead Executor pops up a dialogue box that you can
use to tell it which program to start. Mind you; there are a number of
ways to disable Finder on a real Mac too, which saves a little memory.
ARDI has been working on a Finder substitute for some time; it might
be available to you the moment you read this, if not, it's still being
tested by ARDI's beta testers. Check your favourite BBS or network.

ARDI's Finder substitute has a band under the menu bar with icons of
commonly used applications and directories and other objects.  This
band is known as the "hot band".  You can drag objects into and out of
this band.  When you double click on a directory or volume, a window
with icons for all the files in the directory will appear.  You can
drag files from one window to another to move or copy them.  To delete
a file, you must select it and choose delete; there is no trash can.
Double clicking runs an application. The band has six buttons on it
which allow you to choose which kind of objects are displayed in the
hot band (applications, documents, volumes, directories, fonts, or
desk accesories). Also the capability to format disks is included.

Since the Mac is meant to be used for graphical applications it uses a
number of scalable fonts. These are stored in the 'System' file using
a tool called FONT/DA Mover when using System 6. Under System 7 one
can just copy a font in the System Folder and it will be recognised.
FONT/DA Mover is Apple copyrighted software.  That makes it difficult
to install fonts under Executor until ARDI's file browser is
universally available.

On a Mac, files are arranged in folders, the equivalent of MS-DOS
directories. Folders can be nested and contain icons for programs
and/or data files. A remarkable feature of Finder is the alias. An
alias is a copy of an application's icon that can be used to create
groups of objects. It is Apple's first effort towards object
orientation. Changing the properties of an icon also changes them of
the alias, contrary to within Windows.

Since Executor comes without Finder, and doesn't recognize aliases, it
might occur that you open a folder on a floppy or CD-ROM finding
nothing in it. On a Mac there might have been aliases in those
folders.

A difference that a Windows user notices is that on a Mac the menu is
always on the topline of the display where in Windows the active menu
is always within the current window. A Windows desktop with a number
of applications running shows a lot of menus which can lead to
confusion. Windows indicates the current menu by giving it a different
colour. On a Mac selecting a window automatically makes its associated
menu appear on the topline.  Since Executor can only run one
application at a time this should not be much of a problem. One
notices it using HFS_XFer (described below) though.


RUNNING SOFTWARE WITH EXECUTOR
------------------------------

Now that you have installed Executor on your system and you have
verified that it runs, you are ready to start some of the demo
software that comes with Executor. These are freeware, shareware or
fully working demos of commercial packages. The files are located in
the EXDEMOS1.HFV DOS volume and appear after installation in an
Executor volume in the 'demos' and 'games' folders. Also Executor
comes with some useful utilities included in the EXSYSTEM.HFV DOS
volume that appear in the 'utils' folder on your System drive.

After you have started some of these programs you probably want to do
something useful with Executor. This means getting hold of the
software that you need and properly installing it.

Before you start installing software there are a couple of issues that
have to be understood. First you need to have set aside a volume that
can hold the files you need. Such a volume can be created with MKVOL
as stated in the appropriate section of this manual. Remember that
unless you to tell Executor otherwise, your newly created volume has
to have a filename ending with ".hfv" and has to be placed in the same
directory as the other ".hfv" files are (the default is
\EXECUTOR. 

The program that creates the new volume is called "mkvol" (make
volume).  It takes three arguments, the name of the DOS file that the
volume will reside in, the name of the volume as it will be seen by
any program running under Executor and the number of 512 byte blocks
that the volume will take up.

For example, to create a 10 megabyte volume, in the DOS file
newvol.hfv, with the internal name NewVolume, you would execute this
command:

	C:\> mkvol newvol.hfv NewVolume 20480

When you next start Executor and cycle through your available drives
by clicking the 'DRIVE' button you will have an empty volume ready to
take your files.

Also remember that Executor is a complex piece of software. ARDI has
beta-tested this product thoroughly but the enormous diversity of PC
hardware coupled with the complexity of emulating a totally different
system on top of this hardware means that crashes are possible.  When
Executor or your PC dies, unpredictable things might happen.  It is
recommended that so-called write-behind-cacheing be disabled when you
use Executor. Most systems nowadays use Microsoft's SMARTDRV which has
write-behind-cacheing turned off by default only when you use MS-DOS
6.2 If you have another MS-DOS version or when you have turned it on
please change the line that starts SMARTDRV to :

   SMARTDRV C

instead of

   SMARTDRV C+  

As always, it is best to back up your data frequently.


GETTING HOLD OF SOFTWARE
------------------------

Apple's Macintosh is the second most widespread architecture in the
world.  Software for the Mac is as freely available as for the PC
platform.  There are however a few distinctions. Commercial software
tends to be more expensive and sometimes updated versions arrive later
than their MS-Windows counterparts. It used to be the other way around
but this is the way it is.

An important issue to note here is that Executor, due to constraints
in PC hardware, can only read Macintosh HD (SuperDrive) floppy-disks
and Macintosh formatted CD-ROMs (more on CD-ROMs later on). SuperDrive
floppy disks are physically identical to PC HD diskettes (all of them
have a second hole on the other side of the write-protect notch). As
on the PC they have a capacity of 1.4 Mb.

These disks share the same "low-level" format, but have a different
"filesystem format" than they do on a PC. i.e. the physical format is
the same as on a PC; it is just the logical format that differs.

Macintosh commercial software is available from most shops. If you
have no possibility to use a 'real' Macintosh then be sure that the
disks you get are HD ones. Otherwise let the dealer convert them.

Since not all software will run under Executor it is advisable to
arrange with your dealer to test the software first.

Especially look for explicit statements whether the software needs
System 7.  If an application *requires* System 7, then it is unlikely
to work under the current implementation of Executor.

Good software for the Macintosh can be found with most magazines
(again verify that they come with HD disks), on all commercial
networks and on the Internet.

When you want to use software on a Macintosh CD-ROM, your CD-ROM drive
will appear automatically within Executor if your CD-ROM controlling
software conforms to Microsoft's MSCDEX or Adaptec's ASPI standard.

When you insert a Macintosh formatted HD floppy or CD-ROM these will
be automatically recognised when you start Executor. If you insert
them when Executor has already started, you must press
Shift-left-Alt-2 before they will be seen. 

Due to size constraints on a floppy, most of the time the software on
it will be in a compressed format. This is comparable to the way it is
done on the PC where ZIP, ARC, ARJ and LZH are some of the used
extensions to denote a compressed file. Amazingly the number of
different compression systems used on Macs is as large as on the PC
and all of them are different between the two platforms. Yes, there is
a ZIP utility for the Mac but no available software seems to be
compressed with it.

Although the naming convention for Mac files is much less constraining
than the one we are familiar with on the PC (name of 8 characters and
an extension of 3), most of the time the name of a compressed file
ends with a decimal point followed by a three character extension.

Mind that the name of a Mac file when found on a system that has a
more constraining naming convention (like MS-DOS) might not be able to
tell you what sort of format it is in. However, when you transform it
to Mac format (more on this later) its name will explain more. For
instance you might find a file called ACMECALC.BIN on CompuServe
which, when it ends up on your Executor volume, suddenly gets called
'Acme Super Calculator.sea'.

The most used compression systems and their extensions are:

.pit	; PackIt compressed file
.sit	; Stuffit compressed file
.cpt	; Compact Pro compressed file
.dde	; DiskDoubler compressed file
.sea	; One of the above but self-extracting

For the first four files you will need the mentioned shareware
programs to extract (decompress) them. The full Stuffit package can
also handle the other formats. Compact Pro is found in the 'utils'
folder on your System disk. Stuffit is excellent shareware and there
is a freeware Stuffit Expander program that as its name suggests can
only expand a compressed file (expanding again being another word for
decompress, foo). DiskDoubler is less used than the others, mainly
because it is commercial software.  There is a free expander though.

A .sea file basically consists of a compressed file with an integrated
expander. When you start an .sea file it will expand itself
automatically.

Of the mentioned decompressors there are a number of different
versions to be found; not all of these work with Executor. Also some
self-extracting compressed files tend to kill Executor. When this
happens there is a simple but effective trick. Try to get hold of a
utility called 'DeSEA'. It does what its name implies; it turns a .sea
file in a .sit,.pit or .cpt file that then can be decompressed using
one of the mentioned tools.

Excellent information on the various compression schemes, .hqx and
BinHex formats can be found in a FAQ (Frequently Asked Questions)
document on datacommunication, available via anonymous ftp on the
Internet from:

site :	sumex-aim.stanford.edu
file : /info-mac/comm/info/comp-sys-mac-comm-faq.txt

When the file is decompressed, you are ready to roll. Mind that a lot
of software that comes on CDs take the capacity of a CD to the maximum
by using audio and video clips (called QuickTime). These cannot be
used in Executor. A program with such a restriction will probably
complain that you need System 7; the version of the Mac's operating
system that supports video.


GETTING SOFTWARE USING YOUR PC
------------------------------

The above is all well but you might be tempted to get software for
Executor by downloading files from bulletin boards and/or networks
like CompuServe, America Online or the Internet. This is possible
though a bit more complicated since the PC is not a Mac (you might
have noticed this; ARDI lives because of it).

In the PC world every file on your harddisk comes as one logical
collection of bytes, with a start, a middle and an end.  On the Mac
every file has two components (honest!), these are called the
data-fork and the resource-fork. The data-fork contains the data that
is unformatted, or at least not formatted in a way that the actual
Macintosh OS itself understands. The resource-fork contains data that
is formatted in a way that the Macintosh OS understands and hence can
be used to specify parameters for various Macintosh OS routines, for
instance icons. Every file has both a data-fork and a resource-fork
although either, (or even both) can be empty.

To enable distribution of Macintosh files on a non-Macintosh medium
like most bulletin-boards, a number of people, Apple amongst them,
found a way to combine the two forks in one file. Two of these system
are known as BinHex.  BinHex 4 is often known as "HQX" and it combines
both forks into a single ASCII file.  BinHex 5 is often known as
"MacBinary" and it combines both forks into a single BINARY file.

Since Executor at this moment does not support serial I/O all
downloading of Mac files has to be done using your favourite PC
communication program and your PC modem. Downloaded files will thus
appear on your PC's harddisk.

If the file's description from where you downloaded it or its name on
your PC's harddisk indicates that is in HQX format (for instance
because its name contains the .hqx extension) there is an extra step
to take.

A file with the .hqx extension has been constructed using version 4.0
of BinHex. This program enables binary files to be transported on
networks that otherwise would have problems with them by translating
them in 7-bit ASCII text. You can try this by using your favourite DOS
editor on such a file; it will contain seemingly endless lists of
numbers; the human-readable equivalent of machine-code.

The supplied BinHex 5.0 program converts a.hqx file automatically to
its original format. There is also an excellent shareware program
called DeHQX that also gives a lot of information in the process.

To get a file converted so that it appears on an Executor Mac volume,
start the program BinHex in the 'utils' folder on your System disk. In
its file menu you will find a Download -> Application choice. It will
pop-up a dialogue box where you can specify the file on your PC volume
after which it will ask you where to store the result. When all goes
well you will find some form of Mac file on the destination
disk. (Remember that Executor in its starting dialogue box only shows
you folders and programs. To open a .sit file you will have to start
Stuffit for instance.)

If a file is not HQX'ed BinHex effectively only copies the file and creates
the two forks from the one file. To find out whether BinHex needs to take
the extra step it looks for the phrase :

   (This file must be converted with BinHex 4.0)

at the beginning of the file.

CompuServe has its own Macintosh File Finder that enables you to find
your favourite Mac file amongst the odd 20,000 it stores. On the
Internet a lot of Mac software can be found. Look for the SimTel ftp
archives.  Another good archive is the HENSA archive of Lancaster
University, UK.

To summarise; when you have downloaded a Mac file it will appear to be
a normal PC file on your PC. Run BinHex to write it to an Executor
volume.  BinHex will automatically de-HQX the file. If required run a
de-compression program.

If Executor 'touches' a file on a PC volume it immediately creates a
pseudo resource fork for that file which is a separate file with a
percent-sign as its first character. This can confuse BinHex and other
programs , and a 'touched' file might not be shown anymore, unless you
turn off the "TEXT filter", so that all files are displayed instead of
just "TEXT" ones. In such a case simply delete the resource-fork file.
This problem is actually a result of a bug in Executor and hopefully
the bug will be fixed soon.

A special word on text files. When you download a text file that was
produced on a Mac you will experience that a number of DOS editors
have problems with the fact that the Mac only uses a LF character at
the end of every line, where the PC uses a CR, LF pair. Luckily the
MS-DOS EDIT command can read both formats. When you open a Mac style
text document, change one character and then write it back, EDIT will
convert it to PC text format. There exists a shareware/freeware MS-DOS
program called MAC2PC80.EXE that does this all automatically.

If you do not want to store a compressed text file on an Executor
volume but want to read it using a PC editor then there are shareware
PC programs, like UNSTUFF.EXE (free!) that can decompress such a file
on the PC.

Apart from files being BinHex'ed and/or compressed, more complex
programs come in the form of an 'Installer'; a program that installs
the software so that it is automatically copied to the proper
folders. An installer most of the time also decompresses its
components and scatters them around in for instance your System
Folder.

The problem here is that most of the time installers are complex
programs that might confuse Executor. Many installers were written by
Apple and have special information about the insides of Macintoshes
that the authors of Executor did not have (Executor was written using
"clean room" techniques -- no Apple ROMs or System files were
disassembled).  In such a case you will have to install the program on
a real Mac and then transfer the installed program to an Executor
volume. Afterward, if it is not publicly redistributable, delete the
program from the Mac.  It is illegal not to.

On the issue of files in your System Folder; this folder acts as the
notorious WIN.INI file under Windows, i.e. it is regarded as every
application's liberty to litter it. A separate folder 'Preferences'
most of the time holds files that store items like your highest score
in your favourite game. Since Executor's System drive is limited in
size it pays to occasionally delete unwanted files from the System
Folder.  Be careful with the file \TMP\EXECOUT.PS though. This file is
required for printing in Executor.

Note: The size of Executor's System drive is not really limited in size.
      If you run out of space you have to create a second, larger System
      volume with MKVOL. Do not call the DOS volume EXSYSTEM.HFV but choose
      a different name like EXSYS1.HFV making sure that its logical volume
      name remains System. The proper MKVOL command line would be :

         MKVOL EXSYS1.HFV System 4096

      to create a 2 Mb. System drive.  Copy all files from the first
      drive to the second drive using HFS_XFer. Be careful; both
      drives are called System - the empty one should be the
      destination. When everything has been copied delete EXSYSTEM.HFV
      and rename EXSYS1.HFV to EXSYSTEM.HFV. 

Transferring a file from a Mac to Executor larger than can be fitted
on one floppy is not so easy. Try compressing it first. If it still
doesn't fit you can use a serial cable and transfer it using two
terminal programs, or try to get your hands on a program that cuts
archives in parts.


FILE CREATORS AND FILE TYPES
----------------------------

On a PC an application most of the time uses the 3-character extension
of files to denote that it created them. For instance an application
named ACMECALC might create files with an .ACM extension.  Also the
extension might indicate the type of file like .TXT denoting a text
file.  This way of doing things has lead to a lot of confusion since
nobody is regulating the list of used extensions, and three letters
doesn't lend itself to enough logical combinations.

On the Mac the above is regulated. The Mac uses a system where every
file has a 4-character 'creator' and a 4-character 'type'. These are
distributed by Apple - a list can be obtained of valid ones. (This
does not mean that everybody follows the rules of course.) The creator
field is used twofold. Firstly it tells a Mac's Finder what
application to load when the user double-clicks the icon of a
data-file. Secondly it enables an application to only show files in
dialogue boxes that it can handle.

Normally you do not have to worry about the above, but sometimes a
file that you think belongs to a certain application cannot be opened
by it.  The adventurous can then change the type and or creator using
a tool like File Kit. From the number of available programs that can
change types and creators we might conclude that the confusion on the
Mac platform as to which file belongs to who is as confusing as it is
on PCs.


USEFUL PROGRAMS
---------------

Apart from the already mentioned utilities there are a couple more
that you probably might want to look for. Get a simple text processor
like UpWord to edit an occasional file. To view the contents of most
word-processor documents get Quill.

To make sure that the files you download are not virus-ridden get
Disinfectant. There are only an odd twenty viruses around but still
you might be unlucky. Because Executor has slightly different
"internals" than a Macintosh does, it is slightly less susceptible to
virus infection than a real Mac but better not take chances.

Easy Errors tells you what an error number generated by an application
actually means. (Who ever said a Mac was userfriendly?)

Get File Kit to have a look at file attributes like creation date and
length.

If you need to format Macintosh floppy disks on your PC look out for
future versions of Executor or buy Insignia's MacDISK. Alternatively
buy pre-formatted disks. Better still : since the physical format for
Macintosh floppies equals the PC format you can use DISKCOPY to copy a
Macintosh disk.  You can use mkvol to create a .hfv file with 2880
blocks and then copy that to a raw disk if you have the tools to do
that.

Shareware and/or freeware programming languages are not that freely
available as on the PC. There are a number of freeware 'C' compilers,
ChipMunk Basic is a simple Basic interpreter.

HyperCard from Claris runs fairly well, but some stacks will not work
under HyperCard under Executor.  Supercard created stacks also usually
work, although some aspects of Supercard's use of color can confuse
the experimental versions of Executor that support color.

If you want to learn how to program a Mac be prepared for a shock. To
fully understand how the Mac works you need to master a large and very
expensive series of books from Apple, called Inside Macintosh. Apple
is working on a CD version of these books though.

Just like the Windows environment just knowing a programming language
is not enough to write a nice looking application. On a Mac one needs
to master the equivalent of the Windows API, called the Toolbox.


LIMITATIONS ON WHAT WILL RUN UNDER EXECUTOR
-------------------------------------------

On a real Mac there is a large number of ways to interact with the
machine. Apart from starting normal programs, there are

- Desk Accessories; these are handy programs that can be found
                    in the Apple Menu, just like HFS_XFer.

- Extensions;       these extend the Mac's Operating System, for
                    instance for video.

- Control Panels;   enable a Mac user to control various settings
                    of his/her system.

- Inits;            small programs that a Mac loads for special
                    devices and/or functionality.

Apart from the Desk Accessory HFS_Xfer, Executor at this moment cannot run
any of the above.


TRANSFERRING DATA BETWEEN MAC APPLICATIONS AND DOS COUNTERPARTS
---------------------------------------------------------------

You can manipulate data within applications on both platforms if they
can read the applicable format, i.e. a Word for Windows 5.x document
can be edited using Word 5 with Executor.

If you let an application produce print output then Executor puts it
in a file \TMP\EXECOUT.PS if the directory \TMP exists.  This output
is a proper PostScript file that can be printed on a printer that
supports PostScript. Otherwise you can use the freeware package
GhostScript to view or print them under MS-DOS.


Bibliography
------------

Suggested further reading if you want to know more.

Title				Author			Content
------------------------------------------------------------------------
Insanely Great			Steven Levy		History of the Mac

Technical Introduction		Apple			THE Source
to the Macintosh Family

comp.sys.mac.comm FAQ		D.L. Oppenheimer	Everything on
							datacommunication,
							compression and
							file formats.


All company names and products mentioned are copyrighted and trademarks
of their respective owners.

Ernst J. Oud
Compuserve : 100265,3601
Internet   : ernstoud@euronet.nl
