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.