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. Conditions of use of EHWIM.EXE ------------------------------ EHWIM.EXE is NOT supported by Psion. Please do not telephone any Psion personnel (Support or otherwise) with any questions regarding EHWIM. (The concept of a tool being released but not supported should be familiar to developers who work with any other large software system.) Any questions regarding EHWIM should ONLY be raised in the PSION conference on CIX, where unofficial support may be available from time to time, and where other EHWIM users may also help you. EHWIM.EXE was originally developed for use purely inside Psion Software Development, and only runs within a limited set of circumstances. In view of the potential assistance it may provide to other people writing software for the Series3, it is being released "as is" on CIX. Releasing an internal tool in this way on CIX is an experiment. If people disregard the above request, and telephone Psion with questions about EHWIM, the experiment will not be repeated - ie no other tools, documentation, etc, will be released in a similar way on CIX in the future. Instead, these other tools and documentation will simply remain un-released. 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 in the FLIST of the PSION SERIES3 conference: 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. These notes prepared -------------------- By David Wood, Psion Software Development, on 21/9/92.