                 README.TXT for Workabout emulator
                 =================================

This file explains how to run the Workabout emulator, which provides
an emulation of Psion's workabouts software on sufficiently powerful
PCs.

Files in the emulator:
----------------------
The Workabout Emulator is distributed in the form of a .ZIP file 
containing the following files:

    readme.txt          this documentation file
    licence.txt         user licence agreement
    install.bat         copies the files to your Hard drive
    runme.bat           sorts out your SUBST commands  
    wrkaemul.exe        the emulator top level
    epoc.dll            used by the emulator (contains EPOC)
    epoc.rmi            used by the emulator (rest of OS and APPS)
    hhserver.par        configures the emulator
    rtm.exe             run-time support
    dpmi16bi.ovl        run-time support

Licence agreement - important
-----------------------------
Note: before using this software, you must read and agree with the
terms of the accompanying file LICENCE.TXT.

Intended purpose
----------------
Note: the intended purpose of WorkAbout Emulator is as an unsupported
tool for software developers.  Treat it with the caution you would
normally accord to unsupported software development tools - be sure
to have backups of any data on your PC, before using WorkAbout
Emulator.

That said, it has been the experience of developers who have already
used WorkAbout Emulator that no significant data loss has resulted
from the use of this tool.

However, Psion cannot offer any warranties or guarantees on this
point.  In particular, users are warned not to try running WorkAbout
Emulator from inside Windows, OS/2, or Windows NT.

Installation of the software
----------------------------
Either run the install batch file which will copy all the files
to the C: to a directory called wrkabout or put them manually
into the required directory. If you choose to do this manually you
may need to edit the runme.bat file to accomdate the different 
directory

Limitations of the emulator:
----------------------------
    You must be running a 386 (at least) PC.
    You must have at least 4MB ram.
    Only VGA graphics support.
    The emulator will not run in a DOS box in Windows (it will 
    "violate Windows system integrity").
    The Emulator will not run under Windows NT or O/S 2.

To run the emulator:
--------------------
Go to the directory containing the files and type "Runme".

To exit the emulator:
---------------------
Press and hold down Ctrl-Alt-Esc simultaneously.
Or execute a program (IMG or OPO) that calls HwExit (call($168e)).

**** Ctrl-Alt-Z is an alternative to Ctrl-Alt-Esc.

When the emulator exits:
------------------------
The message "Fatal application error 00" will be displayed.
This is perfectly normal (no error has, in fact, occurred).

Other fatal application errors:
-------------------------------
These almost invariably mean that insufficient ram was available.
For example, ram allocated to a ram drive is inaccessible to 
the emulator.

Special keys inside the emulator:
---------------------------------
F9 Menu, F10 Help, F12 Diamond
F11 simulates the machine being switched off then on.
Alt is the Psion key.
You can use the Insert key as an alternative to Shift-System.

Other limitations of the emulator:
----------------------------------
Differences at the low-level filing system level.
Address trapping is implemented differently.

Run-time errors with the emulator:
----------------------------------
The low-level memory manager inside the emulator may generate 
exceptions, known as "run-time errors", if various error conditions
arise - eg programs attempting to read or write outside the limits
of the code and/or data segments.  
(On a real WorkAbout, these conditions would lead to
"panic"s, but they are caught earlier, at a lower level, inside
WorkAbout.  This is not to say, incidentally, that *all* WorkAbout
panics are converted to the emulator exceptions, only a fixed 
minority.)

When a run-time error of this sort occurs, the whole emulator stops
at once, and all data in all programs is lost (though not data saved
to file).  The emulator stops so suddenly that the screen will be
left in graphics mode.  To return it to standard character mode, type
eg      
        MODE co80
(you'll have to type this "blind", since the characters you type
won't be echoed onto the screen until after the command is processed).

When a run-time error occurs, some part of the memory of the PC may
on occasion be left tied up, even after the emulator has exited.  
(Use eg the DOS MEM command to find out if this is the case.) 
Reset your PC if this becomes a problem.

Note that under normal circumstances, the emulator will not encounter
a run-time error - only if a program contains a bug.  However, if you
use the emaultor to test programs under development, you may well
encounter this situation.

Remote Link:
------------
Note that you can turn on Remote Link in the System Screen and gain
access to an attached Workabout (or other Sibo computer) as REM::.

By default, this connection presupposes use of COM1.  However, if you
type "-p2" into the "Extra parameters" line in the "Remote link"
dialog in the System screen inside the emulator, COM2 will be used
instead.

Notes about SUBST: (as used by runme.bat)
-----------------------------------------
See your DOS manual for full details.
Example syntax is
    SUBST M: C:\PSION
To change a subst, you first have to "delete" it, eg using
    SUBST M: /D

Note that before you can SUBST to M:, the LASTDRIVE setting in
CONFIG.SYS must be set as least as high as M.  (If you have to change
your CONFIG.SYS, you will have to reboot your PC before this takes
any effect.)

Troubleshooting:
----------------
If you have problems running the emulator:
    disconnect any serial mice and/or remove their drivers
    remove any ramdrives from your PC configuration
    remove other ram-guzzlers from your PC configuration
    re-read this document (sorry if this sounds condescending).

Technical support for the emulator:
------------------------------
Psion regrets that no technical support is available on the use of
the emulator, whether by post, fax, telephone calls, or EMAIL.