PC emulation of Series3
=======================

This document describes EHWIM.EXE, a PC emulation of the Series3
environment.

If you are developing either C programs or Opl programs for the
Series3, you may find that using EHWIM.EXE can significantly increase
your productivity over many parts of the development life-cycle.

Copyright notice
----------------
(C) Copyright Psion PLC 1992.

All rights reserved.  The program EHWIM.EXE, the other files in the
PC emulator of the Series3, and the accompanying documentation are
copyrighted works of Psion PLC, London, England.  Reproduction in
whole or in part, including utilisation in machines capable of
reproduction or retrieval, without express written permission of
Psion PLC, is prohibited.  Reverse engineering is also prohibited.

The proper role of the emulator
-------------------------------
In no circumstances should programs be released for use on the
Series3 without being fully tested ON A SERIES3 ITSELF.  The fact
that a program runs on a PC emulation of the Series3 in no way
guarantees that it will run on a Series3 itself.

The role of the emulator is to speed up the earlier parts of program
development, and more routine program development, before the program
receives more serious testing on a real Series3.
        
Limitations of the emulator
---------------------------
This release of EHWIM comes with the Time and Word applications, and
the Program alias.  This will allow you to edit, translate and run
Opl programs on a PC.

The emulator will only run on truly IBM-compatible PCs.  The emulator
is unlikely to run successfully on DOS emulations or inside "DOS
boxes" such as under OS/2 or Windows.  Serial mice may have to be
removed before you can run the emulator successfully.

The hardware of a PC is, of course, different from the hardware on
the Series3.  This particularly effects comms parts of programs.  For
example, a program that prints via the serial port or parallel port
will appear to work correctly, on a PC, even if no parallel lead or
serial lead is connected to the PC, whereas an error message will be
given in the corresponding case on the Series3.

The low-level filing systems on the emulator do not match those on
the Series3.  For example, the notifier "Please replace the SSD"
never arises on the emulator, and as a result, the important error
condition "User abandoned" can never be tested on the emulator.  Disk
caching on the PC can also give rise to unexpected results, differing
from on the Series3.  There are other error messages, such as "O/S
error", that can arise on the PC, but never on a Series3.

There is no hardware address trapping on the PC.  Aberrant programs
which would be terminated by the O/S on the Series3 with Exit Number
60, will trash random memory locations on the PC.

Note that when the emulator is exited, applications have no chance to
save any data to file.

Installing EHWIM.EXE on a PC
----------------------------
The PC emulator actually consists of more than one file (not all of
which are needed every time the emulator runs).  In all these files
are distributed among FIVE different zip files:
        ehwim.zip       The main emulator executable, ehwim.exe
                        plus a "configuration" file hhserver.par
        apps.zip        The programs time.app, word.app, and program.als
        wsrvhdhv.zip    A VGA Window Server, wsrvhdhv.img
        wsrvhdhh.zip    A Hercules Window Server, wsrvhdhh.img
        wsrvhdhc.zip    A CGA Window Server, wsrvhdhc.img

For a VGA graphics screen, use wsrvhdhv.img.  For Hercules, use
wsrvhdhh.img.  For CGA, use wsrvhdhc.img.  IN EACH CASE, the .img file
has to be renamed to SYS$WSRV.IMG before the emulator will run.

Choose a suitable top-level directory to run the emulator from (say
the directory c:\s3emul).  Unzip EHWIM.ZIP and at least one of WSRV*.ZIP
into this directory.

Make an APP subdirectory of the initial directory (say c:\s3emul\app),
go there, and unzip APPS.ZIP there.

BEFORE THE EMULATOR WILL RUN, you MUST perform a DOS SUBST of drive m:
to the chosen top-level directory.  Eg type the DOS command
    subst m: c:\s3emul
(see below for more details of SUBST).

Failure to correctly SUBST drive m: will lead to the System Screen of
the emulator repeatedly exiting with Exit Number 55.

NOTE CAREFULLY that before you can type (eg) "subst m: c:\s3emul" you
must have your value of LASTDRIVE set to be at least as high as 'm'. 
So you may need to add a line such as
    lastdrive=m
to your config.sys (and then reboot the PC).

You can rename the file EHWIM.EXE to something more memorable, if you
like.  BUT DO NOT RENAME ANY OF THE OTHER FILES.

To start the emulator, simply type "ehwim".

Special key-presses
-------------------
F1 is the SYSTEM button, F2 is the DATA button, and so on up to F8
which is the PROG button.  F9 is the MENU key and F10 is HELP.

F11 simulates turning the Series3 off then on again: this has a
visible effect only if a password is set.

The ALT key has the same function as the PSION key on the Series3.

To exit the emulator and return to DOS, press and hold down CTRL-ALT-ESC.

Auto-installing applications
----------------------------
To have one of your programs auto-installed and auto-started whenever
the emulator starts, copy it into m:\app and give it the name eg DATA.APP.

(Note however that applications containing embedded DYLs shouldn't be
renamed in this way as they will not run successfully.)

Large and small screen versions of the emulator
-----------------------------------------------
The emulator is initially set up to create TWO copies of its display
on the screen: a small one that matches the Series3 pixel for pixel,
and a large one that is easier to read.

To turn off the second display, you have to edit (use a text editor
such as Brief) the file HHSERVER.PAR that is part of the emulator, to
make its contents as follows
    SERVER_PARAMS -X240 -Y80
ie removing the final -M -N that actually creates the magnified display.

The main drawback of running in the magnified mode is that some
aspects of the emulator run more slowly.  (You may like to experiment
removing only the final -N flag).

Notes on SUBST-ing
------------------
When the emulator starts, it will make very frequent accesses to the
a: floppy disk drive, resulting in a sound sometimes likened to a
machine gun.

To disable this, you can redirect a: elsewhere, if you like.  For
example, create a directory c:\acolon, and then type
    subst a: c:\acolon

You may also wish to do a similar SUBST for b:.

Don't forget to un-subst a: after you have finished with the emulator
- otherwise you won't be able to use the real floppy disk drive.
