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.