README

                      README.TXT for S3aEMUL.EXE
                      ==========================

This file explains how to run the program S3AEMUL.EXE, which provides
an emulation of Psion's S3a software on sufficiently powerful PCs.

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

    readme.txt          this documentation file
    licence.txt         user licence agreement
    s3aemul.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 S3AEMUL 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 S3AEMUL.

That said, it has been the experience of developers who have already
used S3AEMUL 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 S3AEMUL
from inside Windows, OS/2, or Windows NT.

Installation of the software
----------------------------
You should copy the following files into the same directory on your
PC: s3aemul.exe, epoc.dll, epoc.rmi, hhserver.par, rtm.exe, and
dpmi16bi.ovl.

Rename S3aEMUL.EXE if you like, but don't rename any other file.

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

To run the emulator:
--------------------
Go to the directory including S3aEMUL.EXE and type "S3aEMUL".

NB The emulator will behave oddly if it cannot find an M:.
So be sure that one is available (create one using SUBST if you need
to), although there doesn't have to be anything special in it.
(See below for notes on the DOS SUBST command.)

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 S3aEMUL.

Special keys inside the emulator:
---------------------------------
F1 is System, F2 Data, ..., F8 Sheet, F9 Menu, F10 Help, F12 Diamond
F11 simulates the machine being switched off then on (only has any
effect when a password is set).
Alt is the Psion key.
You can use the Insert key as an alternative to Shift-System.

Other limitations of the emulator:
----------------------------------
Limited emulation of the WVE sound system.
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 S3aEMUL 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 S3a, these conditions would lead to
"panic"s, but they are caught earlier, at a lower level, inside
S3aEMUL.  This is not to say, incidentally, that *all* S3a panics are
converted to S3aEMUL 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 S3aEMUL 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, S3aEMUL will not encounter a
run-time error - only if a program contains a bug.  However, if you
use S3aEMUL 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 S3a (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 S3aEMUL, COM2 will be used instead.

Notes about SUBST:
------------------
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.)

You may also find it convenient to SUBST A: or B: whilst S3aEMUL is
running, to lessen the amount of access made by S3aEMUL to your floppy
disk drives.

Troubleshooting:
----------------
If you have problems running S3aEMUL:
    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 S3aEMUL:
------------------------------
Psion regrets that no technical support is available on the use of
S3aEMUL, whether by post, fax, telephone calls, or EMAIL.

The sole exceptions to this are that questions raised about S3aEMUL in
the PSION conferences on CIX will generally be answered within a few
days.